@ttoss/fsl-theme 2.0.0 → 2.1.0

package/README.md

@@ -34,38 +34,39 @@ Components consume only semantic tokens. Core tokens never change between light
 
 One entry per semantic family. Use `vars.*` for typed CSS variable references; use the `semantic.*` path shape below when naming tokens in TypeScript or in discussion.
 
-| Family    | Path shape                                                          | Leaf value              |
-| --------- | ------------------------------------------------------------------- | ----------------------- |
-| colors    | `semantic.colors.{ux}.{role}.{dimension}.{state}`                   | CSS color               |
-| spacing   | `semantic.spacing.inset.{control,surface}.{sm,md,lg}`               | CSS length              |
-|           | `semantic.spacing.gap.{stack,inline}.{xs,sm,md,lg,xl}`              | CSS length              |
-|           | `semantic.spacing.gutter.{page,section}`                            | CSS length / `clamp()`  |
-|           | `semantic.spacing.separation.interactive.min`                       | CSS length              |
-| text      | `semantic.text.{display,headline,title,body,label,code}.{lg,md,sm}` | TextStyle object        |
-| sizing    | `semantic.sizing.hit.{min,base,prominent}`                          | CSS length              |
-|           | `semantic.sizing.icon.{sm,md,lg}`                                   | CSS length              |
-|           | `semantic.sizing.identity.{sm,md,lg,xl}`                            | CSS length              |
-|           | `semantic.sizing.measure.reading`                                   | CSS `ch` / `clamp()`    |
-|           | `semantic.sizing.surface.maxWidth`                                  | CSS length              |
-|           | `semantic.sizing.viewport.{height,width}.full`                      | CSS dvh/dvw             |
-| radii     | `semantic.radii.{control,surface,round}`                            | CSS length              |
-| border    | `semantic.border.divider`                                           | `{width, style}`        |
-|           | `semantic.border.outline.{surface,control,selected}`                | `{width, style}`        |
-| focus     | `semantic.focus.ring`                                               | `{width, style, color}` |
-| elevation | `semantic.elevation.surface.{flat,raised,overlay,blocking}`         | CSS box-shadow          |
-|           | `semantic.elevation.tonal.{raised,overlay,blocking}`                | CSS color (optional)    |
-| opacity   | `semantic.opacity.{scrim,loading,disabled}`                         | number in (0, 1)        |
-| overlay   | `semantic.overlay.scrim`                                            | CSS color with alpha    |
-| motion    | `semantic.motion.{feedback,emphasis,decorative}`                    | `{duration, easing}`    |
-|           | `semantic.motion.transition.{enter,exit}`                           | `{duration, easing}`    |
-| zIndex    | `semantic.zIndex.layer.{base,sticky,overlay,blocking,transient}`    | integer                 |
+| Family    | Path shape                                                       | Leaf value              |
+| --------- | ---------------------------------------------------------------- | ----------------------- |
+| colors    | `semantic.colors.{ux}.{role}.{dimension}.{state}`                | CSS color               |
+| spacing   | `semantic.spacing.inset.{control,surface}.{sm,md,lg}`            | CSS length              |
+|           | `semantic.spacing.gap.{stack,inline}.{xs,sm,md,lg,xl}`           | CSS length              |
+|           | `semantic.spacing.gutter.{page,section}`                         | CSS length / `clamp()`  |
+|           | `semantic.spacing.separation.interactive.min`                    | CSS length              |
+| text      | `semantic.text.{display,headline,title,body,label}.{lg,md,sm}`   | TextStyle object        |
+|           | `semantic.text.code.{md,sm}`                                     | TextStyle object        |
+| sizing    | `semantic.sizing.hit.{min,base,prominent}`                       | CSS length              |
+|           | `semantic.sizing.icon.{sm,md,lg}`                                | CSS length              |
+|           | `semantic.sizing.identity.{sm,md,lg,xl}`                         | CSS length              |
+|           | `semantic.sizing.measure.reading`                                | CSS `ch` / `clamp()`    |
+|           | `semantic.sizing.surface.maxWidth`                               | CSS length              |
+|           | `semantic.sizing.viewport.{height,width}.full`                   | CSS dvh/dvw             |
+| radii     | `semantic.radii.{control,surface,round}`                         | CSS length              |
+| border    | `semantic.border.divider`                                        | `{width, style}`        |
+|           | `semantic.border.outline.{surface,control,selected}`             | `{width, style}`        |
+| focus     | `semantic.focus.ring`                                            | `{width, style, color}` |
+| elevation | `semantic.elevation.surface.{flat,raised,overlay,blocking}`      | CSS box-shadow          |
+|           | `semantic.elevation.tonal.{raised,overlay,blocking}`             | CSS color (optional)    |
+| opacity   | `semantic.opacity.{scrim,loading,disabled}`                      | number in (0, 1)        |
+| overlay   | `semantic.overlay.scrim`                                         | CSS color with alpha    |
+| motion    | `semantic.motion.{feedback,emphasis,decorative}`                 | `{duration, easing}`    |
+|           | `semantic.motion.transition.{enter,exit}`                        | `{duration, easing}`    |
+| zIndex    | `semantic.zIndex.layer.{base,sticky,overlay,blocking,transient}` | integer                 |
 
 **Colors axes** (`semantic.colors.{ux}.{role}.{dimension}.{state}`):
 
 - `ux` — FSL Entity Kind: `action` · `input` · `navigation` · `feedback` · `informational`
 - `role` — Evaluation: `primary` · `secondary` · `accent` · `muted` · `positive` · `caution` · `negative`
 - `dimension` — `background` · `border` · `text`
-- `state` — `default` · `hover` · `active` · `focused` · `disabled` · `selected` · `pressed`
+- `state` — `default` · `hover` · `active` · `focused` · `disabled` · `selected` · `pressed` · `expanded` · `checked` · `indeterminate` · `current` · `visited` · `droptarget` · `invalid` (legality varies per `ux` — see the colors family spec)
 
 ## Pick a token in 60s
 
@@ -220,7 +221,7 @@ export const App = () => (
 );
 ```
 
-`ThemeProvider` injects CSS Custom Properties via React 19 style hoisting and persists mode to localStorage.
+`ThemeProvider` injects CSS Custom Properties via React 19 style hoisting, persists mode to localStorage, and keeps open tabs in sync via the `storage` event. The react entry point ships with `'use client'`, so it can be imported directly from a Next.js App Router layout.
 
 ### Hooks
 
@@ -242,7 +243,10 @@ import { useResolvedTokens } from '@ttoss/fsl-theme/react';
 
 // Non-CSS environments (React Native, canvas) — resolved raw values
 const resolved = useResolvedTokens();
-// resolved['semantic.colors.action.primary.background.default'] → '#0469E3'
+// resolved['semantic.colors.action.primary.background.default'] → '#020617'
+// ⚠ CSS-coupled tokens (spacing steps, fluid text sizes, hit/viewport sizing —
+// see model.md §8) stay as CSS expressions (var()/calc()/clamp()/cqi) and are
+// not usable outside a CSS engine. Colors and scalar tokens resolve fully.
 ```
 
 ### Consuming tokens
@@ -376,16 +380,23 @@ import { getThemeStylesContent } from '@ttoss/fsl-theme/css';
 
 const css = getThemeStylesContent(myTheme);
 // → :root { --tt-* } + :root[data-tt-mode="dark"] { --tt-* (overrides) }
+//   + @media (prefers-color-scheme: dark) fallback for no-JS / pre-hydration
+
+// Fixed light/dark default (dark only via explicit toggle)? Skip the OS fallback:
+const lightFirstCss = getThemeStylesContent(myTheme, undefined, {
+  systemModeFallback: false,
+});
+// <ThemeProvider> / <ThemeHead> derive this automatically from `defaultMode`.
 ```
 
 ## Storybook / micro-frontends
 
-Anchor theme attributes to a specific element instead of `<html>`:
+Anchor theme attributes to a specific element instead of `<html>`. Always pair `root` with a `themeId` — without one, the CSS targets `:root` on `<html>` while the attributes land on the element, and the alternate mode would never apply (a dev warning fires on this combination):
 
 ```tsx
 const rootRef = React.useRef<HTMLDivElement>(null);
 <div ref={rootRef}>
-  <ThemeProvider theme={myTheme} root={rootRef.current ?? undefined}>
+  <ThemeProvider theme={myTheme} themeId="story" root={rootRef}>
     <Story />
   </ThemeProvider>
 </div>;

package/dist/{Types-BkaxtsMv.d.cts → Types-a_sfpbha.d.cts}

@@ -366,14 +366,18 @@ interface ActionColorStates extends BaseColorStates {
   /** Disclosure trigger or menu button is currently open. Use for buttons that own an open popup, menu, or panel. */
   expanded?: CoreColorRef;
 }
-/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded` for form controls.
+/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded`,
+ * and `invalid` for form controls.
  *
- * Validation failure is *not* a state — it is an Evaluation (FSL Lexicon §5).
- * Components that fail validation render with the `input.negative.*` role,
- * not with an `invalid` state on `input.primary.*`. This avoids dual
- * representation of the same semantic concept and keeps FSL §7 State Law
- * intact ("States are not free-form"). React Aria's `isInvalid` flag maps
- * to selecting the `negative` role, not to a new state.
+ * Validation doctrine (ADR-017, mirrors `@ttoss/fsl-ui` taxonomy): validation
+ * outcome is a **runtime State** (`invalid`), never an authorial Evaluation —
+ * evaluation lives in the author's pen, state lives in the user's data.
+ * The control itself flips to `input.{role}.*.invalid` when React Aria's
+ * `isInvalid` (or a form library) says so; adjacent *display* parts
+ * (validationMessage, icon) still consume the `input.negative.*` role — they
+ * report valence, the control carries state. The mirror distinction to
+ * Lexicon §10.5 (`negative` ≠ `destructive`) is `invalid` (State) ≠
+ * `negative` (Evaluation) — Lexicon §10.15.
  *
  * Structural Role → token mapping (FSL Lexicon §2): a part declared with
  * Structural Role `validationMessage` consumes `input.negative.text.*` for
@@ -393,6 +397,14 @@ interface InputColorStates extends BaseColorStates {
   pressed?: CoreColorRef;
   /** Combobox / select / disclosure-style input is currently open. */
   expanded?: CoreColorRef;
+  /**
+   * Runtime validation outcome — the control's value failed validation.
+   * Use when React Aria's `isInvalid` (or a form library) asserts failure.
+   * Pair with `input.negative.text.*` on the validationMessage; do not use
+   * the `negative` role on the control itself — that is authorial valence
+   * (Lexicon §10.15).
+   */
+  invalid?: CoreColorRef;
 }
 /** `navigation` context: adds `selected`, `current`, `visited`, `expanded`. */
 interface NavigationColorStates extends BaseColorStates {
@@ -407,10 +419,10 @@ interface NavigationColorStates extends BaseColorStates {
 }
 /** `informational` context: adds `selected`, `visited`, `expanded`.
  *
- * `expanded` covers in-place disclosure on presentational surfaces (accordions,
- * collapsible panels, expandable cards). `Disclosure` Entity Kinds project to
- * `informational` per FSL identity (in-place reveal, not movement across
- * destinations — FSL Lexicon §1). */
+ * `expanded` covers in-place disclosure on presentational surfaces
+ * (accordions, collapsible panels, expandable cards). Note: `Disclosure`
+ * Entity Kinds project to `navigation` (ADR-001); `expanded` here serves
+ * presentational surfaces that disclose without being Disclosure entities. */
 interface InformationalColorStates extends BaseColorStates {
   /** Presentational element is **one of many** and the user picked it (selectable list row, focused card in a deck). */
   selected?: CoreColorRef;

package/dist/{Types-BkaxtsMv.d.mts → Types-a_sfpbha.d.mts}

@@ -366,14 +366,18 @@ interface ActionColorStates extends BaseColorStates {
   /** Disclosure trigger or menu button is currently open. Use for buttons that own an open popup, menu, or panel. */
   expanded?: CoreColorRef;
 }
-/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded` for form controls.
+/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded`,
+ * and `invalid` for form controls.
  *
- * Validation failure is *not* a state — it is an Evaluation (FSL Lexicon §5).
- * Components that fail validation render with the `input.negative.*` role,
- * not with an `invalid` state on `input.primary.*`. This avoids dual
- * representation of the same semantic concept and keeps FSL §7 State Law
- * intact ("States are not free-form"). React Aria's `isInvalid` flag maps
- * to selecting the `negative` role, not to a new state.
+ * Validation doctrine (ADR-017, mirrors `@ttoss/fsl-ui` taxonomy): validation
+ * outcome is a **runtime State** (`invalid`), never an authorial Evaluation —
+ * evaluation lives in the author's pen, state lives in the user's data.
+ * The control itself flips to `input.{role}.*.invalid` when React Aria's
+ * `isInvalid` (or a form library) says so; adjacent *display* parts
+ * (validationMessage, icon) still consume the `input.negative.*` role — they
+ * report valence, the control carries state. The mirror distinction to
+ * Lexicon §10.5 (`negative` ≠ `destructive`) is `invalid` (State) ≠
+ * `negative` (Evaluation) — Lexicon §10.15.
  *
  * Structural Role → token mapping (FSL Lexicon §2): a part declared with
  * Structural Role `validationMessage` consumes `input.negative.text.*` for
@@ -393,6 +397,14 @@ interface InputColorStates extends BaseColorStates {
   pressed?: CoreColorRef;
   /** Combobox / select / disclosure-style input is currently open. */
   expanded?: CoreColorRef;
+  /**
+   * Runtime validation outcome — the control's value failed validation.
+   * Use when React Aria's `isInvalid` (or a form library) asserts failure.
+   * Pair with `input.negative.text.*` on the validationMessage; do not use
+   * the `negative` role on the control itself — that is authorial valence
+   * (Lexicon §10.15).
+   */
+  invalid?: CoreColorRef;
 }
 /** `navigation` context: adds `selected`, `current`, `visited`, `expanded`. */
 interface NavigationColorStates extends BaseColorStates {
@@ -407,10 +419,10 @@ interface NavigationColorStates extends BaseColorStates {
 }
 /** `informational` context: adds `selected`, `visited`, `expanded`.
  *
- * `expanded` covers in-place disclosure on presentational surfaces (accordions,
- * collapsible panels, expandable cards). `Disclosure` Entity Kinds project to
- * `informational` per FSL identity (in-place reveal, not movement across
- * destinations — FSL Lexicon §1). */
+ * `expanded` covers in-place disclosure on presentational surfaces
+ * (accordions, collapsible panels, expandable cards). Note: `Disclosure`
+ * Entity Kinds project to `navigation` (ADR-001); `expanded` here serves
+ * presentational surfaces that disclose without being Disclosure entities. */
 interface InformationalColorStates extends BaseColorStates {
   /** Presentational element is **one of many** and the user picked it (selectable list row, focused card in a deck). */
   selected?: CoreColorRef;

package/dist/{baseBundle-R7WyjyTw.mjs → baseBundle-CXdxj_re.mjs}

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { a as darkAlternate, i as baseTheme, n as createTheme, r as baseBrief } from "./createTheme-B6tVIikC.mjs";
+import { a as darkAlternate, i as baseTheme, n as createTheme, r as baseBrief } from "./createTheme-Bm9LVQ4w.mjs";
 
 //#region src/baseBundle.ts
 /**

package/dist/{baseBundle-DdRSa5mf.cjs → baseBundle-a9LDsqYy.cjs}

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-const require_createTheme = require('./createTheme--UFgVlEn.cjs');
+const require_createTheme = require('./createTheme-B7H0xSVp.cjs');
 
 //#region src/baseBundle.ts
 /**

package/dist/{createTheme--UFgVlEn.cjs → createTheme-B7H0xSVp.cjs}

@@ -66,6 +66,7 @@ var baseTheme = {
         100: "#fee2e2",
         300: "#fca5a5",
         500: "#ef4444",
+        600: "#dc2626",
         700: "#b91c1c",
         900: "#7f1d1d"
       },
@@ -391,7 +392,7 @@ var baseTheme = {
         },
         negative: {
           background: {
-            default: "{core.colors.red.500}",
+            default: "{core.colors.red.600}",
             hover: "{core.colors.red.700}",
             active: "{core.colors.red.900}",
             disabled: "{core.colors.neutral.200}",
@@ -400,7 +401,7 @@ var baseTheme = {
             expanded: "{core.colors.red.700}"
           },
           border: {
-            default: "{core.colors.red.500}",
+            default: "{core.colors.red.600}",
             hover: "{core.colors.red.700}",
             active: "{core.colors.red.900}",
             focused: "{core.colors.red.700}",
@@ -455,7 +456,8 @@ var baseTheme = {
             checked: "{core.colors.brand.500}",
             indeterminate: "{core.colors.brand.300}",
             pressed: "{core.colors.neutral.100}",
-            expanded: "{core.colors.neutral.50}"
+            expanded: "{core.colors.neutral.50}",
+            invalid: "{core.colors.neutral.0}"
           },
           border: {
             default: "{core.colors.neutral.300}",
@@ -467,12 +469,14 @@ var baseTheme = {
             checked: "{core.colors.brand.500}",
             indeterminate: "{core.colors.brand.300}",
             pressed: "{core.colors.neutral.500}",
-            expanded: "{core.colors.brand.500}"
+            expanded: "{core.colors.brand.500}",
+            invalid: "{core.colors.red.600}"
           },
           text: {
             default: "{core.colors.neutral.900}",
             disabled: "{core.colors.neutral.500}",
             checked: "{core.colors.neutral.0}",
+            invalid: "{core.colors.neutral.900}",
             indeterminate: "{core.colors.neutral.900}"
           }
         },
@@ -1355,17 +1359,20 @@ var darkAlternate = {
             selected: "{core.colors.brand.700}",
             droptarget: "{core.colors.neutral.700}",
             pressed: "{core.colors.neutral.500}",
-            expanded: "{core.colors.neutral.500}"
+            expanded: "{core.colors.neutral.500}",
+            invalid: "{core.colors.neutral.700}"
           },
           border: {
             default: "{core.colors.neutral.500}",
             hover: "{core.colors.neutral.300}",
             focused: "{core.colors.brand.500}",
-            disabled: "{core.colors.neutral.700}"
+            disabled: "{core.colors.neutral.700}",
+            invalid: "{core.colors.red.300}"
           },
           text: {
             default: "{core.colors.neutral.0}",
-            disabled: "{core.colors.neutral.500}"
+            disabled: "{core.colors.neutral.500}",
+            invalid: "{core.colors.neutral.0}"
           }
         },
         secondary: {
@@ -1789,10 +1796,17 @@ var levenshtein = (a, b) => {
 * Validate that every `{ref}` in the merged theme points to an existing path.
 * Emits `console.warn` for each broken reference with a "did you mean?" suggestion.
 *
+* `onlyOwnerKeys` restricts which token paths are *checked* (resolution still
+* looks at the whole tree) — used to validate just the leaves an alternate
+* introduces without re-warning refs already reported for the base.
+*
 * **DEV-only** — callers gate this behind `process.env.NODE_ENV !== 'production'`
 * so bundlers tree-shake the entire call in production builds.
 */
-var validateRefs = theme => {
+var validateRefs = (theme, options = {}) => {
+  const {
+    onlyOwnerKeys
+  } = options;
   const {
     core,
     semantic
@@ -1817,6 +1831,7 @@ var validateRefs = theme => {
     return "";
   };
   for (const [ownerKey, value] of Object.entries(all)) {
+    if (onlyOwnerKeys && !onlyOwnerKeys.has(ownerKey)) continue;
     if (typeof value !== "string" || !value.includes("{")) continue;
     let match;
     const re = new RegExp(require_helpers.COMPOUND_REF_RE.source, require_helpers.COMPOUND_REF_RE.flags);
@@ -1835,6 +1850,41 @@ var validateRefs = theme => {
 //#endregion
 //#region src/createTheme.ts
 /**
+* Deep-clone to break shared references between base and result.
+* Tokens are primitives (strings, numbers) — `structuredClone` is safe and
+* more correct than a JSON round-trip (preserves `undefined`, `NaN`, etc.).
+*
+* Falls back to a JSON round-trip when `structuredClone` is unavailable
+* (e.g. Jest's jsdom environment, older embedded runtimes) so importing the
+* package never throws at module-evaluation time. Token trees are plain
+* string/number leaves, so the fallback is lossless for valid themes.
+*/
+var cloneTokens = value => {
+  if (typeof structuredClone === "function") return structuredClone(value);
+  return JSON.parse(JSON.stringify(value));
+};
+/**
+* DEV-only: validate the refs an alternate introduces against the built base.
+* The alternate is authored by hand (semantic-only remaps), so a typo'd
+* dark-mode ref must warn at theme creation instead of silently emitting a
+* broken CSS var in production.
+*
+* Only the leaves the alternate itself provides are checked — base refs were
+* already validated by `buildTheme`, so they would otherwise warn twice.
+*/
+var validateAlternateRefs = ({
+  base,
+  alternate
+}) => {
+  const alternateKeys = new Set(Object.keys(require_helpers.flattenObject(alternate.semantic, "semantic")));
+  validateRefs({
+    core: base.core,
+    semantic: require_helpers.deepMerge(base.semantic, alternate.semantic)
+  }, {
+    onlyOwnerKeys: alternateKeys
+  });
+};
+/**
 * Creates a fully resolved `ThemeTokens` by merging partial overrides into a base.
 * Internal engine — consumers should use `createTheme` which returns `ThemeBundle`.
 *
@@ -1846,13 +1896,28 @@ var buildTheme = ({
 } = {}) => {
   const merged = require_helpers.deepMerge(base, overrides);
   if (process.env.NODE_ENV !== "production") validateRefs(merged);
-  return structuredClone(merged);
+  return cloneTokens(merged);
 };
 var resolveAlternate = (alternate, parentBundle) => {
   if (alternate === null) return void 0;
   if (alternate !== void 0) return alternate;
   return parentBundle?.alternate ?? darkAlternate;
 };
+/** Resolve every `createTheme` input against its `extends` parent + defaults. */
+var resolveBundleInputs = ({
+  parentBundle,
+  baseMode,
+  base,
+  alternate,
+  brief
+}) => {
+  return {
+    resolvedBase: base ?? parentBundle?.base,
+    resolvedBaseMode: baseMode ?? parentBundle?.baseMode ?? "light",
+    resolvedAlternate: resolveAlternate(alternate, parentBundle),
+    resolvedMeta: brief ?? parentBundle?.meta
+  };
+};
 /**
 * Creates a theme bundle with an optional alternate color mode.
 *
@@ -1903,16 +1968,29 @@ var createTheme = ({
   alternate,
   brief
 } = {}) => {
-  const resolvedBase = base ?? parentBundle?.base;
-  const resolvedBaseMode = baseMode ?? parentBundle?.baseMode ?? "light";
-  const resolvedAlternate = resolveAlternate(alternate, parentBundle);
-  const resolvedMeta = brief ?? parentBundle?.meta;
+  const {
+    resolvedBase,
+    resolvedBaseMode,
+    resolvedAlternate,
+    resolvedMeta
+  } = resolveBundleInputs({
+    parentBundle,
+    baseMode,
+    base,
+    alternate,
+    brief
+  });
+  const builtBase = buildTheme({
+    base: resolvedBase,
+    overrides
+  });
+  if (process.env.NODE_ENV !== "production" && resolvedAlternate) validateAlternateRefs({
+    base: builtBase,
+    alternate: resolvedAlternate
+  });
   return {
     baseMode: resolvedBaseMode,
-    base: buildTheme({
-      base: resolvedBase,
-      overrides
-    }),
+    base: builtBase,
     alternate: resolvedAlternate,
     ...(resolvedMeta ? {
       meta: resolvedMeta