@nxds/core 0.7.2 → 0.9.1

package/dist/runtime/catalogue.d.cts

@@ -1,6 +1,6 @@
-import { N as NexusPresetField, a as NexusAppearancePrefs, b as NexusAppearanceState } from './surface-ladder-C2sSp67b.cjs';
-export { D as DARK_SURFACE_LADDER, L as LIGHT_SURFACE_LADDER, S as SURFACE_TOKENS, c as ShadeAnchor } from './surface-ladder-C2sSp67b.cjs';
-import { M as Mode } from './palette-DgJXuoTz.cjs';
+import { N as NxdsPresetField, a as NxdsAppearancePrefs, b as NxdsAppearanceState } from './surface-ladder-C8HTwT7z.cjs';
+export { D as DARK_SURFACE_LADDER, L as LIGHT_SURFACE_LADDER, S as SURFACE_TOKENS, c as ShadeAnchor } from './surface-ladder-C8HTwT7z.cjs';
+import { M as Mode } from './palette-BKTIQ0WC.cjs';
 
 /** An authored DTCG `$value`: a scalar, a reference string, or a composite. */
 type TokenValue = string | number | boolean | null | readonly TokenValue[] | {
@@ -64,7 +64,7 @@ interface CatalogueVariant {
     /** The authored leaf, or `null` for a colour the engine derives. */
     readonly source: CatalogueSource | null;
     /** The full appearance config a derived colour was computed from. */
-    readonly appearance: DeepReadonly<NexusAppearanceState> | null;
+    readonly appearance: DeepReadonly<NxdsAppearanceState> | null;
     readonly authoredValue: TokenValue | null;
     /**
      * What the generated CSS declares: one custom property for a scalar or a
@@ -81,10 +81,10 @@ interface CatalogueVariant {
  */
 type CatalogueControl = {
     readonly kind: 'preset';
-    readonly field: NexusPresetField;
+    readonly field: NxdsPresetField;
 } | {
     readonly kind: 'pref';
-    readonly field: keyof NexusAppearancePrefs;
+    readonly field: keyof NxdsAppearancePrefs;
 };
 interface CatalogueToken {
     readonly name: CatalogueTokenName;
@@ -104,9 +104,9 @@ interface CatalogueToken {
 }
 
 /**
- * Every Nexus token, identified by its `--nx-*` name: primitives, runtime
+ * Every nxds token, identified by its `--nx-*` name: primitives, runtime
  * colours, spacing, z-index, breakpoints, and typography and shadow styles.
- * Runtime colours are computed from `DEFAULT_NEXUS_APPEARANCE` in explicit
+ * Runtime colours are computed from `DEFAULT_NXDS_APPEARANCE` in explicit
  * light and dark modes; each variant records the appearance it used.
  */
 declare function createTokenCatalogue(): readonly CatalogueToken[];

package/dist/runtime/catalogue.d.ts

@@ -1,6 +1,6 @@
-import { N as NexusPresetField, a as NexusAppearancePrefs, b as NexusAppearanceState } from './surface-ladder-yQyRTCRt.js';
-export { D as DARK_SURFACE_LADDER, L as LIGHT_SURFACE_LADDER, S as SURFACE_TOKENS, c as ShadeAnchor } from './surface-ladder-yQyRTCRt.js';
-import { M as Mode } from './palette-DgJXuoTz.js';
+import { N as NxdsPresetField, a as NxdsAppearancePrefs, b as NxdsAppearanceState } from './surface-ladder-B950TU4_.js';
+export { D as DARK_SURFACE_LADDER, L as LIGHT_SURFACE_LADDER, S as SURFACE_TOKENS, c as ShadeAnchor } from './surface-ladder-B950TU4_.js';
+import { M as Mode } from './palette-BKTIQ0WC.js';
 
 /** An authored DTCG `$value`: a scalar, a reference string, or a composite. */
 type TokenValue = string | number | boolean | null | readonly TokenValue[] | {
@@ -64,7 +64,7 @@ interface CatalogueVariant {
     /** The authored leaf, or `null` for a colour the engine derives. */
     readonly source: CatalogueSource | null;
     /** The full appearance config a derived colour was computed from. */
-    readonly appearance: DeepReadonly<NexusAppearanceState> | null;
+    readonly appearance: DeepReadonly<NxdsAppearanceState> | null;
     readonly authoredValue: TokenValue | null;
     /**
      * What the generated CSS declares: one custom property for a scalar or a
@@ -81,10 +81,10 @@ interface CatalogueVariant {
  */
 type CatalogueControl = {
     readonly kind: 'preset';
-    readonly field: NexusPresetField;
+    readonly field: NxdsPresetField;
 } | {
     readonly kind: 'pref';
-    readonly field: keyof NexusAppearancePrefs;
+    readonly field: keyof NxdsAppearancePrefs;
 };
 interface CatalogueToken {
     readonly name: CatalogueTokenName;
@@ -104,9 +104,9 @@ interface CatalogueToken {
 }
 
 /**
- * Every Nexus token, identified by its `--nx-*` name: primitives, runtime
+ * Every nxds token, identified by its `--nx-*` name: primitives, runtime
  * colours, spacing, z-index, breakpoints, and typography and shadow styles.
- * Runtime colours are computed from `DEFAULT_NEXUS_APPEARANCE` in explicit
+ * Runtime colours are computed from `DEFAULT_NXDS_APPEARANCE` in explicit
  * light and dark modes; each variant records the appearance it used.
  */
 declare function createTokenCatalogue(): readonly CatalogueToken[];

package/dist/runtime/catalogue.js

@@ -1078,7 +1078,7 @@ var STROKE_OPTIONS = [
   { value: "normal", label: "Normal" },
   { value: "strong", label: "Strong" }
 ];
-var DEFAULT_NEXUS_APPEARANCE = {
+var DEFAULT_NXDS_APPEARANCE = {
   mode: "light",
   brandColor: DEFAULT_BRAND_COLOR,
   surfaceTone: "zinc",
@@ -1113,7 +1113,7 @@ var ELEVATIONS = new Set(
 var STROKES = new Set(
   STROKE_OPTIONS.map((option) => option.value)
 );
-function createNexusThemeContract(state) {
+function createNxdsThemeContract(state) {
   const tone = BASE_TONE_SEEDS[state.surfaceTone];
   return {
     surfaceTone: state.surfaceTone,
@@ -3317,24 +3317,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 = {
@@ -8791,7 +8884,7 @@ var shadow_strong_light_default = {
 
 // tokens/semantic/breakpoints.json
 var breakpoints_default = {
-  $description: "Responsive breakpoints (rem). Values match Tailwind v4's own defaults exactly \u2014 Nexus declares them explicitly so they fall under the same reset-and-own discipline as every other namespace (color/spacing/radius/shadow) instead of being inherited implicitly. Tailwind v4 auto-discovers --breakpoint-* from @theme and uses them to generate the nx:sm:\u2026nx:2xl: responsive variants. Override at BUILD TIME by re-declaring a value in a consumer @theme block \u2014 NOT at runtime: @media cannot read var(), so Tailwind bakes the resolved value into the generated media queries at build time.",
+  $description: "Responsive breakpoints (rem). Values match Tailwind v4's own defaults exactly \u2014 nxds declares them explicitly so they fall under the same reset-and-own discipline as every other namespace (color/spacing/radius/shadow) instead of being inherited implicitly. Tailwind v4 auto-discovers --breakpoint-* from @theme and uses them to generate the nx:sm:\u2026nx:2xl: responsive variants. Override at BUILD TIME by re-declaring a value in a consumer @theme block \u2014 NOT at runtime: @media cannot read var(), so Tailwind bakes the resolved value into the generated media queries at build time.",
   "breakpoint-sm": {
     $value: {
       value: 40,
@@ -11138,8 +11231,8 @@ function styleLeaves(family, file) {
 }
 function runtimeAppearance(mode) {
   return {
-    ...DEFAULT_NEXUS_APPEARANCE,
-    prefs: { ...DEFAULT_NEXUS_APPEARANCE.prefs },
+    ...DEFAULT_NXDS_APPEARANCE,
+    prefs: { ...DEFAULT_NXDS_APPEARANCE.prefs },
     mode
   };
 }
@@ -11157,7 +11250,7 @@ function runtimeColorTokens() {
     return {
       mode,
       appearance,
-      values: deriveThemeMode(createNexusThemeContract(appearance), mode)
+      values: deriveThemeMode(createNxdsThemeContract(appearance), mode)
     };
   });
   return SEMANTIC_TOKEN_REGISTRY.map(({ name, category }) => {