@nxds/core 0.7.2 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # @nxds/core
 
-The framework-agnostic engine behind Nexus Appearance: appearance model, runtime theme derivation, and first-paint snapshots. Use it directly for non-React targets like Electron, React Native, or native shells, or via `@nxds/react/appearance` in React apps. It also contains the design tokens in DTCG format and CSS generation documented below.
+The framework-agnostic engine behind nxds Appearance: appearance model, runtime theme derivation, and first-paint snapshots. Use it directly for non-React targets like Electron, React Native, or native shells, or via `@nxds/react/appearance` in React apps. It also contains the design tokens in DTCG format and CSS generation documented below.
 
 ## Install
 
@@ -10,17 +10,17 @@ pnpm add @nxds/core
 
 ## Primary Exports
 
-- `DEFAULT_NEXUS_APPEARANCE`, `sanitizeNexusAppearance`, `NexusAppearanceState`: the appearance model.
+- `DEFAULT_NXDS_APPEARANCE`, `sanitizeNxdsAppearance`, `NxdsAppearanceState`: the appearance model.
 - `BRAND_COLOR_PRESETS`, `BrandColorPreset`, `findBrandColorPreset`, `DEFAULT_BRAND_COLOR`: brand color choices for appearance editors. Default is `DEFAULT_BRAND_COLOR`; Indigo, Blue, Violet, Rose, Orange, Amber, Green, and Teal use each family's authored 600 hex. Assign a preset's `color` to `brandColor`; `findBrandColorPreset(brandColor)` returns the preset an opaque saved color matches in any CSS notation the engine parses (`#4F46E5`, `4f46e5`, `rgb(79 70 229)`), ignoring surrounding whitespace, or `undefined` for a custom or unparseable color.
-- `createNexusThemeContract`, `deriveTheme`, `themeToCss`: derive a full token set from appearance state and render it to CSS.
+- `createNxdsThemeContract`, `deriveTheme`, `themeToCss`: derive a full token set from appearance state and render it to CSS.
 - `measureThemeContrast`, `ThemeContrastCheck`, `Mode`, `Tier`: measure a derived theme against every registered APCA pair. See [Contrast report](#contrast-report).
-- `createNexusAppearanceSnapshotFromState`, `createNexusAppearanceBootstrapScript`, `resolveFirstPaint`, `DEFAULT_STORAGE_KEY`: first-paint, no-flash bootstrap.
+- `createNxdsAppearanceSnapshotFromState`, `createNxdsAppearanceBootstrapScript`, `resolveFirstPaint`, `DEFAULT_STORAGE_KEY`: first-paint, no-flash bootstrap.
 
 ## Advanced / Engine Exports
 
 `adjustContrast`, `PALETTE_KEYS`, `TIER_THRESHOLDS`, `isColor`: low-level palette and contrast utilities. Stability is not guaranteed pre-1.0.
 
-See the Nexus docs, Theming -> Appearance, for setup recipes.
+See the nxds docs, Theming -> Appearance, for setup recipes.
 
 ## Contrast report
 
@@ -28,14 +28,14 @@ See the Nexus docs, Theming -> Appearance, for setup recipes.
 
 ```ts
 import {
-  createNexusThemeContract,
-  DEFAULT_NEXUS_APPEARANCE,
+  createNxdsThemeContract,
+  DEFAULT_NXDS_APPEARANCE,
   deriveTheme,
   measureThemeContrast,
 } from '@nxds/core';
 
 const checks = measureThemeContrast(
-  deriveTheme(createNexusThemeContract(DEFAULT_NEXUS_APPEARANCE))
+  deriveTheme(createNxdsThemeContract(DEFAULT_NXDS_APPEARANCE))
 );
 const failing = checks.filter((check) => !check.pass);
 ```
@@ -77,20 +77,20 @@ Use the engine directly when a host shell owns DOM or native styling.
 
 ```ts
 import {
-  createNexusAppearanceSnapshotFromState,
-  createNexusThemeContract,
-  DEFAULT_NEXUS_APPEARANCE,
+  createNxdsAppearanceSnapshotFromState,
+  createNxdsThemeContract,
+  DEFAULT_NXDS_APPEARANCE,
   deriveTheme,
   resolveFirstPaint,
   themeToCss,
 } from '@nxds/core';
 
 const state = {
-  ...DEFAULT_NEXUS_APPEARANCE,
+  ...DEFAULT_NXDS_APPEARANCE,
   brandColor: '#2563eb',
   surfaceTone: 'slate',
 };
-const snapshot = createNexusAppearanceSnapshotFromState(state);
+const snapshot = createNxdsAppearanceSnapshotFromState(state);
 const firstPaint = resolveFirstPaint(snapshot, false);
 const themeStyle =
   document.querySelector<HTMLStyleElement>('style[data-theme]') ??
@@ -102,7 +102,7 @@ document.documentElement.classList.toggle(
   firstPaint.className === 'dark'
 );
 themeStyle.textContent = themeToCss(
-  deriveTheme(createNexusThemeContract(snapshot.state))
+  deriveTheme(createNxdsThemeContract(snapshot.state))
 );
 ```
 
@@ -155,7 +155,7 @@ Generated global CSS sets the native browser UI policy alongside the tokens: `:r
 ## Reference Resolution
 
 Semantic **color** is produced by the engine (`deriveTheme`), not authored as
-JSON. The build bakes each derived value into `nexus.css` as a `@theme inline`
+JSON. The build bakes each derived value into `nxds.css` as a `@theme inline`
 fallback that still accepts a runtime override:
 
 ```css
@@ -178,7 +178,7 @@ pnpm tokens:tailwind      # From the repo root: build core and generate @nxds/ta
 
 ### Output Files
 
-- `../tailwind/nexus.css` - Main Tailwind theme with `nx:` prefix
+- `../tailwind/nxds.css` - Main Tailwind theme with `nx:` prefix
 - `../tailwind/variables.css` - Primitive CSS variables with `--nx-*` prefix
 
 ## Future Platform Support

package/dist/runtime/catalogue.cjs

@@ -1107,7 +1107,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",
@@ -1142,7 +1142,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,
@@ -3346,24 +3346,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 = {
@@ -8820,7 +8913,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,
@@ -11167,8 +11260,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
   };
 }
@@ -11186,7 +11279,7 @@ function runtimeColorTokens() {
     return {
       mode,
       appearance,
-      values: deriveThemeMode(createNexusThemeContract(appearance), mode)
+      values: deriveThemeMode(createNxdsThemeContract(appearance), mode)
     };
   });
   return SEMANTIC_TOKEN_REGISTRY.map(({ name, category }) => {