Add Theo support to Rollup configuration

[tylersticka]

Overview

Adds support for importing tokens from Theo configuration files in YAML format. (There is a Rollup plugin for Theo, but it appears to only transform to CSS.)

Tokens use the module.js format, which converts tokens into ES exports.

So given a token file like this:

aliases:
  black_transparent_85: 'rgba(0, 0, 0, 0.85)'
props:
  - name: text_dark
    value: '{!black_transparent_85}'
    category: text-color
    comment: Accessible on white and lightest gray.

And JavaScript source like this:

import * as colors from 'path/to/design-tokens/colors.yml';

console.log(colors.textDark);

The compiled JavaScript will look like this:

/* Accessible on white and lightest gray. */
const textDark = "rgba(0, 0, 0, 0.85)";

console.log(textDark);

This also adds usage examples in JavaScript to the design token pages.

Screenshots

Testing

1. Check out branch locally.
2. Attempt to import a design token of your choosing using one of those documented in Storybook. (To avoid having to create a new file, try adding it to the Elastic Textarea script.)
3. Run npm run build
4. See if the token made it to dist/cloudfour-patterns.js.

---

• Resolves Figure out how to consume design tokens in client-side JS #787

[changeset-bot]

💥 No Changeset

Latest commit: 5124da6

Merging this PR will not cause any packages to be released. If these changes should not cause updates to packages in this repo, this is fine 🙂

If these changes should be published to npm, you need to add a changeset.

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

[tylersticka]

@calebeby When I go through my own testing steps, Typescript complains that it can't figure out the types from the token file. Any ideas for how I could resolve that?

[calebeby]

@tylersticka You can add a declaration block like this: https://github.com/cloudfour/cloudfour.com-patterns/blob/v-next/src/types.ts#L1-L4

In this case, each yaml file can have infinitely many exports, and TS will not be able to know those. I don't know of any way to tell TS "anything can be imported from this module". This is the closest I could get:

declare module '*.yml' {
  const tokens: Record<string, any>;
  export = tokens;
}

Then it only allows importing as namespace, for some reason:

import * as colors from '../../design-tokens/colors.yml';

console.log(colors.purple_light);

[tylersticka]

@calebeby Would we be able to avoid this issue somehow if we made a new Theo module, like a module.ts?

Module definitions are pretty simple. Here's the module.js one we're currently using: https://github.com/salesforce-ux/theo/blob/master/lib/formats/module.js.js

Is there some way we could add more info that way, or is it more that Typescript doesn't know how we're using it within our project JS file?

(Apologies if these are dumb questions.)

[calebeby]

@tylersticka That would only work if it actually writes .ts or .d.ts files to the filesystem. TS doesn't know about the rollup or webpack build.

There is a similar problem with CSS Modules, and they solved it by automatically writing .d.ts files to disk: https://github.com/Quramy/typed-css-modules

[calebeby]

There is a discussion here: salesforce-ux/theo#174 (comment)

[tylersticka]

@calebeby

Then it only allows importing as namespace, for some reason:

If we do it that way, do you know if Rollup's tree-shaking will remove the unused variables for us, or will all of colors hang out even if we aren't using more than one variable therein?

[calebeby]

Rollup tree-shakes namespaces (the emitted code will be the same as using the named import): http://rollupjs.org/repl/?version=2.15.0&shareable=JTdCJTIybW9kdWxlcyUyMiUzQSU1QiU3QiUyMm5hbWUlMjIlM0ElMjJtYWluLmpzJTIyJTJDJTIyY29kZSUyMiUzQSUyMmltcG9ydCUyMColMjBhcyUyMGFzc2VydCUyMGZyb20lMjAnLiUyRmFzc2VydCclM0IlNUNuJTVDbmFzc2VydC5lcXVhbCglMjAxJTIwJTJCJTIwMSUyQyUyMDIlMjApJTNCJTIyJTJDJTIyaXNFbnRyeSUyMiUzQXRydWUlN0QlMkMlN0IlMjJuYW1lJTIyJTNBJTIyYXNzZXJ0LmpzJTIyJTJDJTIyY29kZSUyMiUzQSUyMmV4cG9ydCUyMGZ1bmN0aW9uJTIwZXF1YWwlMjAoJTIwYSUyQyUyMGIlMjApJTIwJTdCJTVDbiU1Q3RpZiUyMCglMjBhJTIwISUzRCUyMGIlMjApJTIwdGhyb3clMjBuZXclMjBFcnJvciglMjBtc2clMjApJTNCJTVDbiU3RCU1Q24lNUNuZXhwb3J0JTIwZnVuY3Rpb24lMjBvayUyMCglMjB2YWx1ZSUyQyUyMG1zZyUyMCklMjAlN0IlNUNuJTVDdGlmJTIwKCUyMCFtc2clMjApJTIwbXNnJTIwJTNEJTIwZm9ybWF0KCUyMCclMjVzJTIwaXMlMjBub3QlMjB0cnV0aHknJTJDJTIwdmFsdWUlMjApJTNCJTVDbiU1Q3RpZiUyMCglMjAhdmFsdWUlMjApJTIwdGhyb3clMjBuZXclMjBFcnJvciglMjBtc2clMjApJTNCJTVDbiU3RCUyMiUyQyUyMmlzRW50cnklMjIlM0FmYWxzZSU3RCU1RCUyQyUyMm9wdGlvbnMlMjIlM0ElN0IlMjJmb3JtYXQlMjIlM0ElMjJlcyUyMiUyQyUyMm5hbWUlMjIlM0ElMjJteUJ1bmRsZSUyMiUyQyUyMmFtZCUyMiUzQSU3QiUyMmlkJTIyJTNBJTIyJTIyJTdEJTJDJTIyZ2xvYmFscyUyMiUzQSU3QiU3RCU3RCUyQyUyMmV4YW1wbGUlMjIlM0FudWxsJTdE

[tylersticka]

Awesome!

So in that case, I think your first suggestion probably makes the most sense for now. Do you agree?

[calebeby]

Yeah probably. export = tokens feels like a hack for this scenario, and it is really weird that that makes namespace imports work but not named imports.

But for now, that is probably the easiest solution 👍

Maybe in the future we can add an npm script that generates .d.ts files for each yml file, (or we can make the rollup or webpack plugin do it), but for now that isn't necessary

[tylersticka]

@calebeby One issue with that approach... it looks like we'll have to disable the no-unsafe-member-access rule every single time we reference one of these properties.

I might take a look at the other approach later unless you're aware of a quick fix.

[calebeby]

I would be fine with disabling that rule globally, I did not realize it was enabled

[tylersticka]

@calebeby After making these changes and using one of the tokens, buildTypes results in an error:

src/components/input/elastic-textarea.ts(1,25): error TS2307: Cannot find module '../../design-tokens/colors.yml' or its corresponding type declarations.

Previously npm run build ran fine, but npm run type failed. Now that is reversed.

[tylersticka]

@calebeby Looking at this again, I think I can generate modules and declarations pretty easily. Trying it out instead. Might be nicer to use overall.

[tylersticka]

This is no longer necessary now that #790 has been merged.