refactor(cli): declarative build configuration

[unekinn]

This started as a refactor allowing this

const semanticThemes = R.filter((val) => val.mode === 'light' && val.typography === 'primary', themes)

to become this

const semanticThemes = getThemesFor('semantic');

The main reason for doing this was that it requires no changes to the filters when adding new modes, while the code as it is before this commit would require every R.filter(...) statement to be updated to ignore irrelevant modes -- or suffer exponential increase in build time.

Declarative config

However, after some issues with moving the definition of getThemesFor out of function buildTokens(...) I started refactoring the build script more generally. This ended up with a declarative config defined in build.ts, which looks like this

/*
 * Declarative configuration of the build output
 */
const buildConfigs = {
  typography: { sdConfig: 'typographyVariables', dimensions: ['typography'] },
  'color-mode': { sdConfig: 'colorModeVariables', dimensions: ['mode'] },
  semantic: { sdConfig: 'semanticVariables', dimensions: ['semantic'] },
  storefront: {
    name: 'Storefront preview tokens',
    sdConfig: 'typescriptTokens',
    dimensions: ['mode'],
    options: { outPath: path.resolve('../../apps/storefront/tokens') },
  },
  entryFiles: {
    name: 'CSS entry files',
    sdConfig: 'semanticVariables',
    dimensions: ['semantic'],
    build: async (sdConfigs, { outPath }) => {
      await Promise.all(
        sdConfigs.map(async ({ theme }) => {
          console.log(`👷 ${theme}.css`);

          return makeEntryFile({ theme, outPath, buildPath: path.resolve(`${outPath}/${theme}`) });
        }),
      );
    },
  },
} satisfies Record<string, BuildConfig>;

Note the BuildConfig type definition, which is

export type BuildConfig = {
  /** Optional name of the build config - only used in the console output */
  name?: string;
  /** Style Dictionary configuration id */
  sdConfig: StyleDictionaryConfigs;
  /** Which theme dimensions to include. `theme` (e.g. digdir/altinn) is always included. */
  dimensions: ThemeDimension[];
  /** Custom StyleDictionary options. If not supplied, the default is used */
  options?: Partial<GetSdConfigOptions>;
  /** Custom build function. If not supplied, the default is used. */
  build?: (sdConfigs: SDConfigForThemePermutation[], options: GetSdConfigOptions) => Promise<void>;
};

The resulting css files from the build command remain unchanged.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2792ebd

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Preview deployments for this pull request:

Storybook - 23. Oct 2024 - 12:28

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	57.87%	3636 / 6282
🔵	Statements	57.87%	3636 / 6282
🔵	Functions	83.91%	167 / 199
🔵	Branches	75.51%	515 / 682

File Coverage

No changed files found.

Generated in workflow #518 for commit 2792ebd by the Vitest Coverage Report Action

[unekinn]

Example run to demonstrate the verbose logging:

(...more output below...)

[mimarz]

I suggest we use the same casing for name and group on our themes so its more predictable to use in code. Ideally lowerCase, but maybe noCase since we might have group names with spaces?

[unekinn]

What does noCase actually do? I like camelCase since it is quite predictable:

import camelCase from 'camelcase';

camelCase('foo-bar');
//=> 'fooBar'

camelCase('foo_bar');
//=> 'fooBar'

camelCase('Foo-Bar');
//=> 'fooBar'

camelCase('--foo.bar');
//=> 'fooBar'

camelCase('foo bar');
//=> 'fooBar'

camelCase('Foo bar');
//=> 'fooBar'

camelCase(['__foo__', '--bar']);
//=> 'fooBar'

[mimarz]

noCase is just kebab-case with some additional parsing for replacing spaces. Maybe we should rename it then?

Its something thats been there since before I started and we still had some design-tokens we needed it for.

I think whats most important is we use the same case conversion for our fields for further use. Since we've already started using kebab-case for folders in design-tokens and names I feel its maybe the best fit?

[mimarz]

Fix for potential pitfall filtering themeobjects from $themes

Suggested change

	R.not(theme.group === 'size' && theme.name.toLowerCase() !== 'default'),
	R.not(theme.group.toLowerCase() === 'size' && theme.name.toLowerCase() !== 'default'),

[unekinn]

This is unneccessary because the names are normalised in processTheme. Actually I should have removed the other toLowerCase() as well.

[mimarz]

But these names are not normalised in this filter since its dones before processTheme. Its done straight on the raw ThemeObjects from $themes.json

Looking at it now this filter does not work for our own design-tokens as group is uppercase Size.

Removing it does not alter the build output either so suggest just removing as it seems redundant now?

[unekinn]

This is true! I guess I didn't complete my thought process, I was planning to move processTheme earlier in the "pipeline".

It works right now because the permutation with size: "default" comes before size: "compact", due to the order they are defined in $themes.json. Since none of the build configurations depend on the size dimension, the first one is always used.