@nxds/core 0.9.0 → 0.10.0

package/dist/runtime/catalogue.d.cts

@@ -15,8 +15,8 @@ type DeepReadonly<T> = T extends object ? {
 type CatalogueFamily = 'borderwidth' | 'breakpoint' | 'color' | 'motion' | 'radius' | 'shadow' | 'spacing' | 'typography' | 'z-index';
 /**
  * Canonical identity: an identifier in the `--nx-*` custom property scheme.
- * Most tokens declare it in the generated CSS. Typography and shadow styles
- * and breakpoints do not; they declare a theme property or a utility instead.
+ * Most tokens declare it in the generated CSS. Typography styles and
+ * breakpoints do not; they declare a utility or a theme property instead.
  */
 type CatalogueTokenName = `--nx-${string}`;
 /** Another name that maps onto the canonical token. */
@@ -52,7 +52,7 @@ interface CatalogueDeclaration {
 interface CatalogueVariant {
     /**
      * The theme mode the value applies in (`light` / `dark` for a runtime
-     * colour or a shadow layer), or `null` when it applies in both.
+     * colour or a shadow), or `null` when it applies in both.
      */
     readonly mode: Mode | null;
     /**
@@ -68,8 +68,8 @@ interface CatalogueVariant {
     readonly authoredValue: TokenValue | null;
     /**
      * What the generated CSS declares: one custom property for a scalar or a
-     * shadow style (`--nx-spacing-4`, or `--breakpoint-md` and `--shadow-sm` for
-     * a token declared only under `@theme`), or the `@utility` body for a
+     * shadow style (`--nx-spacing-4`, `--nx-shadow-sm`, or `--breakpoint-md`
+     * for a token declared only under `@theme`), or the `@utility` body for a
      * typography style.
      */
     readonly declarations: readonly CatalogueDeclaration[];
@@ -106,6 +106,7 @@ interface CatalogueToken {
 /**
  * Every nxds token, identified by its `--nx-*` name: primitives, runtime
  * colours, spacing, z-index, breakpoints, and typography and shadow styles.
+ * Shadow layer primitives only compose the shadow styles.
  * Runtime colours are computed from `DEFAULT_NXDS_APPEARANCE` in explicit
  * light and dark modes; each variant records the appearance it used.
  */

package/dist/runtime/catalogue.d.ts

@@ -15,8 +15,8 @@ type DeepReadonly<T> = T extends object ? {
 type CatalogueFamily = 'borderwidth' | 'breakpoint' | 'color' | 'motion' | 'radius' | 'shadow' | 'spacing' | 'typography' | 'z-index';
 /**
  * Canonical identity: an identifier in the `--nx-*` custom property scheme.
- * Most tokens declare it in the generated CSS. Typography and shadow styles
- * and breakpoints do not; they declare a theme property or a utility instead.
+ * Most tokens declare it in the generated CSS. Typography styles and
+ * breakpoints do not; they declare a utility or a theme property instead.
  */
 type CatalogueTokenName = `--nx-${string}`;
 /** Another name that maps onto the canonical token. */
@@ -52,7 +52,7 @@ interface CatalogueDeclaration {
 interface CatalogueVariant {
     /**
      * The theme mode the value applies in (`light` / `dark` for a runtime
-     * colour or a shadow layer), or `null` when it applies in both.
+     * colour or a shadow), or `null` when it applies in both.
      */
     readonly mode: Mode | null;
     /**
@@ -68,8 +68,8 @@ interface CatalogueVariant {
     readonly authoredValue: TokenValue | null;
     /**
      * What the generated CSS declares: one custom property for a scalar or a
-     * shadow style (`--nx-spacing-4`, or `--breakpoint-md` and `--shadow-sm` for
-     * a token declared only under `@theme`), or the `@utility` body for a
+     * shadow style (`--nx-spacing-4`, `--nx-shadow-sm`, or `--breakpoint-md`
+     * for a token declared only under `@theme`), or the `@utility` body for a
      * typography style.
      */
     readonly declarations: readonly CatalogueDeclaration[];
@@ -106,6 +106,7 @@ interface CatalogueToken {
 /**
  * Every nxds token, identified by its `--nx-*` name: primitives, runtime
  * colours, spacing, z-index, breakpoints, and typography and shadow styles.
+ * Shadow layer primitives only compose the shadow styles.
  * Runtime colours are computed from `DEFAULT_NXDS_APPEARANCE` in explicit
  * light and dark modes; each variant records the appearance it used.
  */

package/dist/runtime/catalogue.js

@@ -2502,10 +2502,33 @@ var color_default = {
   }
 };
 
+// src/lib/token-scales.generated.ts
+var PRIMITIVE_PALETTE_NAMES = [
+  "green",
+  "emerald",
+  "teal",
+  "cyan",
+  "sky",
+  "indigo",
+  "violet",
+  "purple",
+  "fuchsia",
+  "pink",
+  "slate",
+  "rose",
+  "lime",
+  "yellow",
+  "blue",
+  "gray",
+  "zinc",
+  "neutral",
+  "stone",
+  "red",
+  "orange",
+  "amber"
+];
+
 // src/lib/primitive-palette.ts
-var PRIMITIVE_PALETTE_NAMES = Object.keys(color_default).filter(
-  (name) => name !== "white" && name !== "black"
-);
 var rampCache = /* @__PURE__ */ new Map();
 function getPaletteRamp(palette) {
   if (!PRIMITIVE_PALETTE_NAMES.includes(palette)) {
@@ -3168,6 +3191,15 @@ function formatShadowStyle(tokenPath, value, primitiveMap) {
   const isInset = tokenPath.length === 1 && tokenPath[0] === "inner";
   return formatShadowComposite(value, primitiveMap, isInset);
 }
+function inlineVariables(value, values) {
+  return value.replace(/var\((--[\w-]+)\)/g, (reference, name) => {
+    const literal = values.get(name);
+    if (literal === void 0) {
+      throw new Error(`inlineVariables: ${reference} has no value`);
+    }
+    return literal;
+  });
+}
 var TYPOGRAPHY_PROPERTIES = [
   ["fontFamily", "font-family"],
   ["fontSize", "font-size"],
@@ -3317,24 +3349,117 @@ function borderColorAliasName(tokenName) {
 }
 
 // src/catalogue/descriptions.ts
-var FOREGROUND_DESCRIPTIONS = Object.fromEntries(
-  COLOR_FAMILIES.flatMap((family) => [
-    [
-      `${family}-foreground`,
-      `Foreground on ${family}-background. The surface relationship defines this role, not text alone: text and icons share it, and contrasting control parts or indicators may use it on the same surface. Other pairings require contrast coverage.`
-    ],
-    [
-      `${family}-subtle-foreground`,
-      `Foreground on ${family}-subtle. The surface relationship defines this role, not text alone: text and icons share it, and contrasting indicators may use it on that surface. Use on neutral surfaces only with contrast coverage for the intended content tier.`
-    ]
-  ])
-);
-var RUNTIME_COLOR_DESCRIPTIONS = {
+var FAMILY_ROLES = {
+  primary: "the main action on a surface",
+  secondary: "a supporting action beside a primary one",
+  success: "a completed or healthy state",
+  warning: "a state that needs attention soon",
+  error: "a failed, invalid or destructive state",
+  information: "neutral guidance or a status update"
+};
+var FAMILY_TEMPLATES = {
+  background: (family, role) => `Solid fill for buttons, badges and other strong emphasis in this family. Pair with ${family}-foreground. Marks ${role}.`,
+  "background-hover": (family) => `${family}-background while the pointer is over the control.`,
+  "background-active": (family) => `${family}-background while the control is pressed.`,
+  foreground: (family) => `Foreground on ${family}-background. The surface relationship defines this role, not text alone: text and icons share it, and contrasting control parts or indicators may use it on the same surface. Other pairings require contrast coverage.`,
+  disabled: () => "Fill of a disabled control in this family. Pair with disabled-foreground.",
+  subtle: (family, role) => `Tinted fill for light badges, alerts and selected rows on background or container. Pair with ${family}-subtle-foreground. Marks ${role}.`,
+  "subtle-foreground": (family) => `Foreground on ${family}-subtle. The surface relationship defines this role, not text alone: text and icons share it, and contrasting indicators may use it on that surface. Use on neutral surfaces only with contrast coverage for the intended content tier.`,
+  "subtle-hover": (family) => `${family}-subtle while the pointer is over the control.`,
+  "subtle-active": (family) => `${family}-subtle while the control is pressed.`,
+  border: () => "Border of an outlined control or alert in this family, on background or container.",
+  "border-active": (family) => `${family}-border while the control is pressed or selected.`
+};
+function familyRole(name) {
+  for (const family of COLOR_FAMILIES) {
+    if (name === `border-${family}-active`) return [family, "border-active"];
+    if (name.startsWith(`${family}-`)) {
+      return [family, name.slice(family.length + 1)];
+    }
+  }
+  return void 0;
+}
+var NEUTRAL_DESCRIPTIONS = {
+  background: "Page background, the base surface everything sits on. Pair with foreground.",
+  "background-hover": "Row or ghost-control hover on background. Pair with foreground.",
+  "background-active": "Row or ghost-control press and selection on background. Pair with foreground.",
+  muted: "Quiet fill for wells, code, skeletons and inactive tracks on background. Pair with muted-foreground.",
   "muted-extralight": "Quietest muted surface \u2014 sits between background and muted for barely-there fills (empty states, subtle panels).",
+  container: "Card and panel surface on background. Pair with container-foreground.",
+  "container-hover": "Row or control hover inside a container.",
+  "container-active": "Row or control press and selection inside a container.",
+  popover: "Surface of menus, popovers, tooltips and dialogs. Pair with popover-foreground.",
+  "popover-hover": "Highlighted menu row inside a popover.",
+  "popover-active": "Pressed or checked menu row inside a popover.",
+  "control-background": "Rail of neutral controls: switch tracks, slider tracks, segmented tabs. Also the hover fill on a neutral control rail.",
+  "control-background-hover": "control-background while the pointer is over it.",
+  "control-thumb": "Thumb of switches and sliders, on control-background.",
+  "nav-background": "Sidebar and navigation surface. Pair with nav-foreground.",
+  "nav-item-hover": "Navigation item hover on nav-background.",
+  "nav-item-active": "Current navigation item on nav-background.",
+  "nav-border": "Border between the sidebar and the page, and inside it.",
+  disabled: "Fill of a disabled neutral control or input. Pair with disabled-foreground.",
+  "border-focus": "Border of a focused input, on background or container.",
+  foreground: "Body text and icons on background, muted and the hover fills.",
+  "container-foreground": "Text and icons on container.",
+  "popover-foreground": "Text and icons on popover and its row fills.",
+  "nav-foreground": "Navigation text and icons on nav-background.",
   "muted-foreground": "It's a gray that softens contrast so primary content stands forward.",
+  "nav-muted-foreground": "Secondary navigation text, such as group labels, on nav-background.",
   "muted-foreground-subtle": "Tertiary text tier below muted-foreground - helper text, captions, divider labels.",
-  ...FOREGROUND_DESCRIPTIONS
+  "disabled-foreground": "Text and icons of a disabled control, on disabled and the family disabled fills.",
+  "border-default": "Default border of inputs, cards, tables and separators, on background or container.",
+  "border-disabled": "Border of a disabled control.",
+  "border-hairline": "Faint divider between rows and grouped items.",
+  "chart-categorical-1": "First chart series, on container or background. Series colours stay in order.",
+  "chart-categorical-2": "Second chart series, on container or background.",
+  "chart-categorical-3": "Third chart series, on container or background.",
+  "chart-categorical-4": "Fourth chart series, on container or background.",
+  "chart-categorical-5": "Fifth chart series, on container or background.",
+  "focus-default": "Focus ring of every interactive control, on any surface.",
+  "focus-error": "Focus ring of an invalid control.",
+  "background-hover-alpha": "Translucent hover fill for controls that sit on an image or an unknown surface.",
+  "border-default-alpha": "Translucent border for controls that sit on an image or an unknown surface.",
+  overlay: "Scrim behind dialogs, sheets and drawers.",
+  "popover-alpha": "Translucent popover surface for frosted overlays.",
+  "popover-backdrop": "Backdrop behind a frosted popover."
 };
+var REGISTRY_NAMES = SEMANTIC_TOKEN_REGISTRY.map(
+  (token2) => token2.name
+);
+function familyDescriptions() {
+  const used = /* @__PURE__ */ new Set();
+  const entries = REGISTRY_NAMES.flatMap((name) => {
+    const match = familyRole(name);
+    if (!match) return [];
+    const [family, role] = match;
+    const template = FAMILY_TEMPLATES[role];
+    if (!template) return [];
+    used.add(role);
+    return [[name, template(family, FAMILY_ROLES[family])]];
+  });
+  const unused = Object.keys(FAMILY_TEMPLATES).filter(
+    (role) => !used.has(role)
+  );
+  if (unused.length > 0) {
+    throw new Error(
+      `FAMILY_TEMPLATES describes ${unused.join(", ")}, which no registry colour has.`
+    );
+  }
+  return entries;
+}
+function neutralDescriptions() {
+  const unknown = Object.keys(NEUTRAL_DESCRIPTIONS).filter(
+    (name) => !REGISTRY_NAMES.includes(name)
+  );
+  if (unknown.length > 0) {
+    throw new Error(
+      `NEUTRAL_DESCRIPTIONS describes ${unknown.join(", ")}, which the registry doesn't have.`
+    );
+  }
+  return Object.entries(NEUTRAL_DESCRIPTIONS);
+}
+var RUNTIME_COLOR_DESCRIPTIONS = Object.fromEntries([...neutralDescriptions(), ...familyDescriptions()]);
 
 // tokens/primitives/borderwidth/borderwidth-fine.json
 var borderwidth_fine_default = {
@@ -11115,21 +11240,46 @@ function typographyStyleEntry(lookup) {
     };
   };
 }
-function shadowStyleEntry(lookup) {
-  return ({ leaf }) => {
+function shadowLayerSets(layers, lookup) {
+  const sets = /* @__PURE__ */ new Map();
+  for (const { preset, mode, leaf } of layers) {
+    const key = `${preset}/${mode}`;
+    const set = sets.get(key) ?? { preset, mode, values: /* @__PURE__ */ new Map() };
+    set.values.set(
+      primitiveName("shadow", leaf.path),
+      resolveValue(leaf.value, lookup, leaf.type, leaf.path)
+    );
+    sets.set(key, set);
+  }
+  return [...sets.values()];
+}
+function shadowStyleTokens(layers, lookup) {
+  const sets = shadowLayerSets(layers, lookup);
+  return styleLeaves("shadow", SHADOW_STYLES_FILE).map(({ leaf }) => {
     const key = pathToCssVarPrefixed(leaf.path, "shadow");
-    const property = `--${key}`;
+    const name = `--nx-${key}`;
+    const composite = formatShadowStyle(leaf.path, leaf.value, lookup);
     return {
-      name: `--nx-${key}`,
-      aliases: [cssVariable(property)],
-      declarations: [
-        {
-          property,
-          value: formatShadowStyle(leaf.path, leaf.value, lookup)
-        }
-      ]
+      name,
+      family: "shadow",
+      group: leafGroup("shadow", leaf.path),
+      type: leaf.type,
+      description: leaf.description ?? null,
+      aliases: [cssVariable(`--${key}`)],
+      control: PRESET_CONTROLS.shadow ?? null,
+      variants: sets.map(({ preset, mode, values }) => ({
+        mode,
+        preset,
+        source: { file: SHADOW_STYLES_FILE, path: leaf.path },
+        appearance: null,
+        authoredValue: structuredClone(leaf.value),
+        declarations: [
+          { property: name, value: inlineVariables(composite, values) }
+        ],
+        references: []
+      }))
     };
-  };
+  });
 }
 function styleLeaves(family, file) {
   return fileLeaves(family, file, SINGLE_SOURCE).filter(
@@ -11191,8 +11341,13 @@ function runtimeColorTokens() {
 function createTokenCatalogue() {
   const primitives = PRIMITIVE_FAMILIES.flatMap(primitiveLeaves);
   const lookup = primitiveLookup(primitives);
+  const shadowLayers = primitives.filter(({ family }) => family === "shadow");
   return [
-    ...authoredTokens(primitives, lookup, primitiveEntry(lookup)),
+    ...authoredTokens(
+      primitives.filter((leaf) => leaf.family !== "shadow"),
+      lookup,
+      primitiveEntry(lookup)
+    ),
     ...runtimeColorTokens(),
     ...authoredTokens(spacingLeaves(), lookup, spacingEntry),
     ...authoredTokens(
@@ -11210,11 +11365,7 @@ function createTokenCatalogue() {
       lookup,
       typographyStyleEntry(lookup)
     ),
-    ...authoredTokens(
-      styleLeaves("shadow", SHADOW_STYLES_FILE),
-      lookup,
-      shadowStyleEntry(lookup)
-    )
+    ...shadowStyleTokens(shadowLayers, lookup)
   ];
 }
 export {