@igne-agency/react-web-ui 0.3.1 → 0.5.0

package/dist/terrazzo/index.d.ts

@@ -15,15 +15,32 @@ export type KitTokensOptions = Readonly<{
  *   variableNameOf("sys.color.primary"); // "--sys-color-primary"
  */
 export declare const variableNameOf: (id: string) => string;
+/**
+ * The custom property a typography token takes its family from:
+ * `--sys-font-family-heading` for a heading, `--sys-font-family-body` for
+ * everything else.
+ *
+ * @example
+ *   fontFamilyPropertyOf("sys.font.heading.large"); // "--sys-font-family-heading"
+ */
+export declare const fontFamilyPropertyOf: (id: string) => string;
 /**
  * A Terrazzo plugin that builds a resolver's tokens into the custom properties
- * the kit's components read: `--ref-*` and `--sys-*`, the `light` theme on
- * `:root` and the `dark` theme's `sys` roles on `html[data-theme="dark"]`, and
- * under `prefers-color-scheme: dark` unless `data-theme="light"`, all in the
+ * the kit's components read: the `ref` ramps on `:root`, the `light` theme's
+ * `sys` roles on `:root` and any `[data-theme="light"]` element, and the `dark`
+ * theme's on any `[data-theme="dark"]` element and on `<html>` under
+ * `prefers-color-scheme: dark` unless `data-theme="light"`, all in the
  * `kit.base` cascade layer after the kit's layer order. A shadow
  * tagged `$extensions["nl.igne.css"].property: "filter"` is written as
  * `drop-shadow()` filters.
  *
+ * Typography tokens name no family. A heading role's `font` takes
+ * `--sys-font-family-heading` and every other role `--sys-font-family-body`,
+ * which defaults to the system stack; the heading family follows the body
+ * family unless set. The plugin narrows Terrazzo's `core/valid-typography` rule
+ * to `fontSize`, `fontWeight` and `lineHeight` unless the config sets that
+ * rule's `requiredProperties` itself.
+ *
  * @example
  *   // terrazzo.config.ts
  *   import { defineConfig } from "@terrazzo/cli";

package/dist/terrazzo/index.js

@@ -1,4 +1,16 @@
 import css, {} from "@terrazzo/plugin-css";
+/**
+ * The typography properties the kit's tokens set. `fontFamily` is left out:
+ * every role takes its family from a custom property the app sets.
+ */
+const TYPOGRAPHY_PROPERTIES = [
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+];
+const VALID_TYPOGRAPHY = "core/valid-typography";
+const BODY_FAMILY = "--sys-font-family-body";
+const HEADING_FAMILY = "--sys-font-family-heading";
 const isRecord = (value) => typeof value === "object" && value !== null;
 const drawnAsFilter = (extensions) => {
     if (!isRecord(extensions)) {
@@ -20,6 +32,74 @@ export const variableNameOf = (id) => `--${id
     .replaceAll(".", "-")
     .replace(/(\p{Uppercase_Letter})(\p{Uppercase_Letter}*)/gu, (_, first, rest) => `-${first.toLocaleLowerCase()}${rest}`)}`;
 const variableName = (token) => variableNameOf(token.id);
+/**
+ * The custom property a typography token takes its family from:
+ * `--sys-font-family-heading` for a heading, `--sys-font-family-body` for
+ * everything else.
+ *
+ * @example
+ *   fontFamilyPropertyOf("sys.font.heading.large"); // "--sys-font-family-heading"
+ */
+export const fontFamilyPropertyOf = (id) => id.split(".").includes("heading")
+    ? HEADING_FAMILY
+    : BODY_FAMILY;
+const families = `\t${BODY_FAMILY}: system-ui, sans-serif;\n\t${HEADING_FAMILY}: var(${BODY_FAMILY});\n`;
+const literal = (value) => isRecord(value) && "value" in value && "unit" in value
+    ? `${String(value["value"])}${String(value["unit"])}`
+    : String(value);
+const typography = (token, { tokensSet }) => {
+    if (token.$type !== "typography") {
+        return undefined;
+    }
+    const alias = token.aliasChain?.[0];
+    const partials = token.partialAliasOf;
+    const subValue = (property, value) => {
+        const partial = isRecord(partials)
+            ? partials[property]
+            : undefined;
+        if (alias !== undefined) {
+            return `var(${variableNameOf(`${alias}-${property}`)})`;
+        }
+        if (typeof partial === "string") {
+            return tokensSet[partial]?.$type === "typography"
+                ? `var(${variableNameOf(`${partial}-${property}`)})`
+                : `var(${variableNameOf(partial)})`;
+        }
+        return literal(value);
+    };
+    return Object.fromEntries([
+        [
+            "font-family",
+            `var(${fontFamilyPropertyOf(token.id)})`,
+        ],
+        ...Object.entries(token.$value).flatMap(([property, value]) => property === "fontFamily"
+            ? []
+            : [
+                [
+                    variableNameOf(property).slice(2),
+                    subValue(property, value),
+                ],
+            ]),
+    ]);
+};
+/** Narrows the recommended typography rule to the properties a kit token sets, unless the project chose its own list. */
+const narrowTypographyRule = (config) => {
+    const rule = config.lint.rules[VALID_TYPOGRAPHY];
+    if (rule === undefined) {
+        return;
+    }
+    const [severity, options] = rule;
+    const set = isRecord(options) ? options : {};
+    if (!("requiredProperties" in set)) {
+        config.lint.rules[VALID_TYPOGRAPHY] = [
+            severity,
+            {
+                ...set,
+                requiredProperties: [...TYPOGRAPHY_PROPERTIES],
+            },
+        ];
+    }
+};
 const dropShadows = (token, { tokensSet, transformAlias }) => {
     if (token.$type !== "shadow" ||
         !drawnAsFilter(token.$extensions)) {
@@ -40,19 +120,28 @@ const dropShadows = (token, { tokensSet, transformAlias }) => {
     })
         .join(" ");
 };
-const light = (contents) => `:root {\n\tcolor-scheme: light;\n${contents}\n}`;
+const ramps = (contents) => `:root {\n${families}${contents}\n}`;
+const light = (contents) => `:root,\n[data-theme="light"] {\n\tcolor-scheme: light;\n${contents}\n}`;
 const LAYER_ORDER = "@layer kit.reset, kit.base, kit.components;";
 const layered = (contents) => `${LAYER_ORDER}\n\n@layer kit.base {\n${contents.trimEnd()}\n}\n`;
-const dark = (contents) => `html[data-theme="dark"] {\n\tcolor-scheme: dark;\n${contents}\n}\n\n@media (prefers-color-scheme: dark) {\n\thtml:not([data-theme="light"]) {\n\t\tcolor-scheme: dark;\n${contents}\n\t}\n}`;
+const dark = (contents) => `[data-theme="dark"] {\n\tcolor-scheme: dark;\n${contents}\n}\n\n@media (prefers-color-scheme: dark) {\n\thtml:not([data-theme="light"]) {\n\t\tcolor-scheme: dark;\n${contents}\n\t}\n}`;
 /**
  * A Terrazzo plugin that builds a resolver's tokens into the custom properties
- * the kit's components read: `--ref-*` and `--sys-*`, the `light` theme on
- * `:root` and the `dark` theme's `sys` roles on `html[data-theme="dark"]`, and
- * under `prefers-color-scheme: dark` unless `data-theme="light"`, all in the
+ * the kit's components read: the `ref` ramps on `:root`, the `light` theme's
+ * `sys` roles on `:root` and any `[data-theme="light"]` element, and the `dark`
+ * theme's on any `[data-theme="dark"]` element and on `<html>` under
+ * `prefers-color-scheme: dark` unless `data-theme="light"`, all in the
  * `kit.base` cascade layer after the kit's layer order. A shadow
  * tagged `$extensions["nl.igne.css"].property: "filter"` is written as
  * `drop-shadow()` filters.
  *
+ * Typography tokens name no family. A heading role's `font` takes
+ * `--sys-font-family-heading` and every other role `--sys-font-family-body`,
+ * which defaults to the system stack; the heading family follows the body
+ * family unless set. The plugin narrows Terrazzo's `core/valid-typography` rule
+ * to `fontSize`, `fontWeight` and `lineHeight` unless the config sets that
+ * rule's `requiredProperties` itself.
+ *
  * @example
  *   // terrazzo.config.ts
  *   import { defineConfig } from "@terrazzo/cli";
@@ -68,9 +157,19 @@ const kitTokens = (options = {}) => {
     const plugin = css({
         filename: options.filename ?? "tokens.css",
         variableName,
-        transform: dropShadows,
+        transform: (token, transformOptions) => typography(token, transformOptions) ??
+            dropShadows(token, transformOptions),
         permutations: [
-            { input: { theme: "light" }, prepare: light },
+            {
+                input: { theme: "light" },
+                include: ["ref.**"],
+                prepare: ramps,
+            },
+            {
+                input: { theme: "light" },
+                include: ["sys.**"],
+                prepare: light,
+            },
             {
                 input: { theme: "dark" },
                 include: ["sys.**"],
@@ -80,6 +179,10 @@ const kitTokens = (options = {}) => {
     });
     return {
         ...plugin,
+        config: (config, context) => {
+            narrowTypographyRule(config);
+            return plugin.config?.(config, context);
+        },
         build: hook => plugin.build?.({
             ...hook,
             outputFile: (filename, contents) => {