@ttoss/fsl-theme 1.1.13 → 1.1.14

package/dist/dtcg.cjs

@@ -0,0 +1,115 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+Object.defineProperty(exports, Symbol.toStringTag, {
+  value: 'Module'
+});
+const require_helpers = require('./helpers-4p4-QVt_.cjs');
+const require_tokenRegistry = require('./tokenRegistry-OhaJ9sPJ.cjs');
+
+//#region src/roots/toDTCG.ts
+/**
+* Suffix-level overrides applied after prefix lookup.
+*
+* The token registry uses a single prefix per semantic subtree (e.g.
+* `semantic.motion.`, `semantic.text.`) which cannot express per-property
+* DTCG types for composite token shapes (TextStyle, SemanticMotionEntry).
+* These overrides catch every case where the leaf property name alone
+* carries the required type — regardless of the token family it belongs to.
+*
+* Rule: a suffix override takes precedence over the prefix-based $type.
+*
+* Typography leaves (TextStyle) that need non-string $types:
+* - `.fontFamily`   → 'fontFamily'  (DTCG named type for font stacks)
+* - `.fontSize`     → 'dimension'   (clamp() / px value)
+* - `.fontWeight`   → 'fontWeight'  (numeric weight: 400, 500, 700 …)
+* - `.lineHeight`   → 'number'      (unitless multiplier: 1.15, 1.5 …)
+* - `.letterSpacing` → 'dimension'  (em value: '-0.02em', '0.04em' …)
+*
+* Motion leaves (SemanticMotionEntry) overridden separately:
+* - `.duration`     → 'duration'
+*/
+const SUFFIX_TYPE_OVERRIDES = [[".duration", "duration"], [".fontFamily", "fontFamily"], [".fontSize", "dimension"], [".fontWeight", "fontWeight"], [".lineHeight", "number"], [".letterSpacing", "dimension"], [".ring.color", "color"]];
+const inferType = path => {
+  for (const [suffix, type] of SUFFIX_TYPE_OVERRIDES) if (path.endsWith(suffix)) return type;
+  for (const [prefix, type] of require_tokenRegistry.DTCG_TYPE_PREFIXES) if (path.startsWith(prefix)) return type;
+  return "string";
+};
+/**
+* Set a value at a dot-path in a nested object, creating intermediate
+* objects as needed.
+*/
+const setNestedValue = (root, path, value) => {
+  const segments = path.split(".");
+  let current = root;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i];
+    if (!(seg in current) || typeof current[seg] !== "object") current[seg] = {};
+    current = current[seg];
+  }
+  current[segments[segments.length - 1]] = value;
+};
+/** Semantic hit token prefix that carries coarse-pointer overrides. */
+const SEMANTIC_HIT_PREFIX = "semantic.sizing.hit.";
+/**
+* Build the `$extensions` metadata for a semantic hit token.
+*
+* Each `semantic.sizing.hit.{step}` token defaults to the fine-pointer value.
+* The extension declares the corresponding coarse-pointer raw value so that
+* non-CSS consumers (React Native, design tool pipelines) can locate and
+* apply touch-target overrides without reading `toCssVars` source code.
+*/
+const buildHitExtension = (step, theme) => {
+  const coarseValue = theme.core.sizing.hit.coarse[step];
+  if (coarseValue === void 0) return void 0;
+  return {
+    "com.ttoss.pointer-override": {
+      condition: "any-pointer: coarse",
+      value: coarseValue
+    }
+  };
+};
+/**
+* Root 3 — W3C Design Tokens (DTCG JSON).
+*
+* Convert a `ThemeTokens` into a structured token tree following the
+* W3C Design Tokens Community Group format. Every leaf node has `$value`
+* (fully resolved) and `$type` (inferred from the token path).
+*
+* Semantic hit tokens (`semantic.sizing.hit.*`) include a `$extensions`
+* field declaring their coarse-pointer override value, so non-CSS consumers
+* can apply touch-target ergonomics without reading the CSS emitter source.
+*
+* This is the interchange format for design tools (Tokens Studio, Figma,
+* Style Dictionary, Specify, Supernova) and CI/CD token pipelines.
+*
+* @example
+* ```ts
+* import { toDTCG } from '@ttoss/fsl-theme/dtcg';
+* import { createTheme } from '@ttoss/fsl-theme';
+*
+* const myBundle = createTheme();
+* const tokens = toDTCG(myBundle.base);
+* // tokens.core.colors.brand['500'] === { $value: '#0469E3', $type: 'color' }
+*
+* // Write to file (build script / token pipeline)
+* await fs.writeFile('tokens.json', JSON.stringify(tokens, null, 2));
+* ```
+*/
+const toDTCG = theme => {
+  const flat = require_helpers.toFlatTokens(theme);
+  const tree = {};
+  for (const [path, value] of Object.entries(flat)) {
+    const token = {
+      $value: value,
+      $type: inferType(path)
+    };
+    if (path.startsWith(SEMANTIC_HIT_PREFIX)) {
+      const ext = buildHitExtension(path.slice(20), theme);
+      if (ext) token.$extensions = ext;
+    }
+    setNestedValue(tree, path, token);
+  }
+  return tree;
+};
+
+//#endregion
+exports.toDTCG = toDTCG;

package/dist/{dtcg.d.ts → dtcg.d.cts}

@@ -1,5 +1,7 @@
-import { T as ThemeTokens } from './Types-6tR0_2Ss.js';
 
+import { i as ThemeTokens } from "./Types-BiBa17RL.cjs";
+
+//#region src/roots/toDTCG.d.ts
 /**
  * A single DTCG token node with `$value` and `$type`.
  *
@@ -7,15 +9,15 @@ import { T as ThemeTokens } from './Types-6tR0_2Ss.js';
  * https://design-tokens.github.io/community-group/format/
  */
 interface DTCGToken {
-    $value: string | number;
-    $type: string;
-    $extensions?: Record<string, unknown>;
+  $value: string | number;
+  $type: string;
+  $extensions?: Record<string, unknown>;
 }
 /**
  * A recursive tree where every leaf is a `DTCGToken`.
  */
 type DTCGTokenTree = DTCGToken | {
-    [key: string]: DTCGTokenTree;
+  [key: string]: DTCGTokenTree;
 };
 /**
  * Root 3 — W3C Design Tokens (DTCG JSON).
@@ -45,5 +47,5 @@ type DTCGTokenTree = DTCGToken | {
  * ```
  */
 declare const toDTCG: (theme: ThemeTokens) => DTCGTokenTree;
-
-export { type DTCGToken, type DTCGTokenTree, toDTCG };
+//#endregion
+export { type DTCGToken, type DTCGTokenTree, toDTCG };

package/dist/dtcg.d.mts

@@ -0,0 +1,51 @@
+
+import { i as ThemeTokens } from "./Types-BiBa17RL.mjs";
+
+//#region src/roots/toDTCG.d.ts
+/**
+ * A single DTCG token node with `$value` and `$type`.
+ *
+ * Follows the W3C Design Tokens Community Group format:
+ * https://design-tokens.github.io/community-group/format/
+ */
+interface DTCGToken {
+  $value: string | number;
+  $type: string;
+  $extensions?: Record<string, unknown>;
+}
+/**
+ * A recursive tree where every leaf is a `DTCGToken`.
+ */
+type DTCGTokenTree = DTCGToken | {
+  [key: string]: DTCGTokenTree;
+};
+/**
+ * Root 3 — W3C Design Tokens (DTCG JSON).
+ *
+ * Convert a `ThemeTokens` into a structured token tree following the
+ * W3C Design Tokens Community Group format. Every leaf node has `$value`
+ * (fully resolved) and `$type` (inferred from the token path).
+ *
+ * Semantic hit tokens (`semantic.sizing.hit.*`) include a `$extensions`
+ * field declaring their coarse-pointer override value, so non-CSS consumers
+ * can apply touch-target ergonomics without reading the CSS emitter source.
+ *
+ * This is the interchange format for design tools (Tokens Studio, Figma,
+ * Style Dictionary, Specify, Supernova) and CI/CD token pipelines.
+ *
+ * @example
+ * ```ts
+ * import { toDTCG } from '@ttoss/fsl-theme/dtcg';
+ * import { createTheme } from '@ttoss/fsl-theme';
+ *
+ * const myBundle = createTheme();
+ * const tokens = toDTCG(myBundle.base);
+ * // tokens.core.colors.brand['500'] === { $value: '#0469E3', $type: 'color' }
+ *
+ * // Write to file (build script / token pipeline)
+ * await fs.writeFile('tokens.json', JSON.stringify(tokens, null, 2));
+ * ```
+ */
+declare const toDTCG: (theme: ThemeTokens) => DTCGTokenTree;
+//#endregion
+export { type DTCGToken, type DTCGTokenTree, toDTCG };

package/dist/dtcg.mjs

@@ -0,0 +1,112 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { s as toFlatTokens } from "./helpers-CaswNJMy.mjs";
+import { n as DTCG_TYPE_PREFIXES } from "./tokenRegistry-DjgSN3oU.mjs";
+
+//#region src/roots/toDTCG.ts
+/**
+* Suffix-level overrides applied after prefix lookup.
+*
+* The token registry uses a single prefix per semantic subtree (e.g.
+* `semantic.motion.`, `semantic.text.`) which cannot express per-property
+* DTCG types for composite token shapes (TextStyle, SemanticMotionEntry).
+* These overrides catch every case where the leaf property name alone
+* carries the required type — regardless of the token family it belongs to.
+*
+* Rule: a suffix override takes precedence over the prefix-based $type.
+*
+* Typography leaves (TextStyle) that need non-string $types:
+* - `.fontFamily`   → 'fontFamily'  (DTCG named type for font stacks)
+* - `.fontSize`     → 'dimension'   (clamp() / px value)
+* - `.fontWeight`   → 'fontWeight'  (numeric weight: 400, 500, 700 …)
+* - `.lineHeight`   → 'number'      (unitless multiplier: 1.15, 1.5 …)
+* - `.letterSpacing` → 'dimension'  (em value: '-0.02em', '0.04em' …)
+*
+* Motion leaves (SemanticMotionEntry) overridden separately:
+* - `.duration`     → 'duration'
+*/
+const SUFFIX_TYPE_OVERRIDES = [[".duration", "duration"], [".fontFamily", "fontFamily"], [".fontSize", "dimension"], [".fontWeight", "fontWeight"], [".lineHeight", "number"], [".letterSpacing", "dimension"], [".ring.color", "color"]];
+const inferType = path => {
+  for (const [suffix, type] of SUFFIX_TYPE_OVERRIDES) if (path.endsWith(suffix)) return type;
+  for (const [prefix, type] of DTCG_TYPE_PREFIXES) if (path.startsWith(prefix)) return type;
+  return "string";
+};
+/**
+* Set a value at a dot-path in a nested object, creating intermediate
+* objects as needed.
+*/
+const setNestedValue = (root, path, value) => {
+  const segments = path.split(".");
+  let current = root;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i];
+    if (!(seg in current) || typeof current[seg] !== "object") current[seg] = {};
+    current = current[seg];
+  }
+  current[segments[segments.length - 1]] = value;
+};
+/** Semantic hit token prefix that carries coarse-pointer overrides. */
+const SEMANTIC_HIT_PREFIX = "semantic.sizing.hit.";
+/**
+* Build the `$extensions` metadata for a semantic hit token.
+*
+* Each `semantic.sizing.hit.{step}` token defaults to the fine-pointer value.
+* The extension declares the corresponding coarse-pointer raw value so that
+* non-CSS consumers (React Native, design tool pipelines) can locate and
+* apply touch-target overrides without reading `toCssVars` source code.
+*/
+const buildHitExtension = (step, theme) => {
+  const coarseValue = theme.core.sizing.hit.coarse[step];
+  if (coarseValue === void 0) return void 0;
+  return {
+    "com.ttoss.pointer-override": {
+      condition: "any-pointer: coarse",
+      value: coarseValue
+    }
+  };
+};
+/**
+* Root 3 — W3C Design Tokens (DTCG JSON).
+*
+* Convert a `ThemeTokens` into a structured token tree following the
+* W3C Design Tokens Community Group format. Every leaf node has `$value`
+* (fully resolved) and `$type` (inferred from the token path).
+*
+* Semantic hit tokens (`semantic.sizing.hit.*`) include a `$extensions`
+* field declaring their coarse-pointer override value, so non-CSS consumers
+* can apply touch-target ergonomics without reading the CSS emitter source.
+*
+* This is the interchange format for design tools (Tokens Studio, Figma,
+* Style Dictionary, Specify, Supernova) and CI/CD token pipelines.
+*
+* @example
+* ```ts
+* import { toDTCG } from '@ttoss/fsl-theme/dtcg';
+* import { createTheme } from '@ttoss/fsl-theme';
+*
+* const myBundle = createTheme();
+* const tokens = toDTCG(myBundle.base);
+* // tokens.core.colors.brand['500'] === { $value: '#0469E3', $type: 'color' }
+*
+* // Write to file (build script / token pipeline)
+* await fs.writeFile('tokens.json', JSON.stringify(tokens, null, 2));
+* ```
+*/
+const toDTCG = theme => {
+  const flat = toFlatTokens(theme);
+  const tree = {};
+  for (const [path, value] of Object.entries(flat)) {
+    const token = {
+      $value: value,
+      $type: inferType(path)
+    };
+    if (path.startsWith(SEMANTIC_HIT_PREFIX)) {
+      const ext = buildHitExtension(path.slice(20), theme);
+      if (ext) token.$extensions = ext;
+    }
+    setNestedValue(tree, path, token);
+  }
+  return tree;
+};
+
+//#endregion
+export { toDTCG };

package/dist/helpers-4p4-QVt_.cjs

@@ -0,0 +1,258 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/roots/helpers.ts
+/** Check if a value is a token reference like `{core.colors.brand.500}` */
+const isTokenRef = value => {
+  return typeof value === "string" && value.length > 2 && value.startsWith("{") && value.endsWith("}");
+};
+/** Extract the inner path from a token reference: `{core.colors.brand.500}` → `core.colors.brand.500` */
+const extractRefPath = ref => {
+  return ref.slice(1, -1);
+};
+/**
+* Allowed characters for a theme identifier: alphanumeric, hyphens, underscores.
+* Shared between toCssVars (CSS selector injection guard) and ssrScript (SSR inline script).
+* A single definition prevents the two validation paths from silently diverging.
+*/
+const SAFE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+* Matches every `{token.path}` reference embedded in a string value.
+* Shared between helpers.ts (toFlatTokens) and toCssVars.ts (inlineRefsToVars)
+* so a single definition governs the `{…}` syntax in both resolution paths.
+*/
+const COMPOUND_REF_RE = /\{([^}]+)\}/g;
+const isPlainObject = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+/**
+* Recursively merges `overrides` into `base`.
+* - Plain objects are merged recursively.
+* - All other values (primitives, arrays) are replaced.
+*/
+const deepMerge = (base, overrides) => {
+  if (!isPlainObject(base) || !isPlainObject(overrides)) return overrides ?? base;
+  const result = {
+    ...base
+  };
+  for (const key of Object.keys(overrides)) {
+    const baseVal = result[key];
+    const overVal = overrides[key];
+    if (overVal === void 0) continue;
+    if (isPlainObject(baseVal) && isPlainObject(overVal)) result[key] = deepMerge(baseVal, overVal);else result[key] = overVal;
+  }
+  return result;
+};
+/**
+* Flatten a nested object into a flat record with dot-separated keys.
+*
+* `{ brand: { 500: '#0469E3' } }` → `{ 'brand.500': '#0469E3' }`
+*/
+const flattenObject = (obj, prefix = "") => {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(value)) Object.assign(result, flattenObject(value, fullKey));else if (typeof value === "string" || typeof value === "number") result[fullKey] = value;
+  }
+  return result;
+};
+/**
+* Flatten a `ThemeTokens` into separate `{ core, semantic }` flat records
+* with dot-separated keys. Centralizes the unsafe casts needed to traverse
+* the opaque token trees.
+*
+* Used by both `toFlatTokens` (resolution) and `buildCssVars` (CSS emission)
+* so the casts live in exactly one place.
+*/
+const flattenTheme = theme => {
+  return {
+    core: flattenObject(theme.core, "core"),
+    semantic: flattenObject(theme.semantic, "semantic")
+  };
+};
+/**
+* Compute the Levenshtein edit distance between two strings.
+* Used exclusively by `validateRefs` to power "did you mean?" suggestions.
+*/
+const levenshtein = (a, b) => {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({
+    length: m + 1
+  }, () => {
+    return Array.from({
+      length: n + 1
+    }, () => {
+      return 0;
+    });
+  });
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) for (let j = 1; j <= n; j++) dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+  return dp[m][n];
+};
+/**
+* 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.
+*
+* **DEV-only** — callers gate this behind `process.env.NODE_ENV !== 'production'`
+* so bundlers tree-shake the entire call in production builds.
+*/
+const validateRefs = theme => {
+  const {
+    core,
+    semantic
+  } = flattenTheme(theme);
+  const all = {
+    ...core,
+    ...semantic
+  };
+  const allKeys = Object.keys(all);
+  const findSuggestion = (refPath, candidates) => {
+    if (candidates.length === 0) return "";
+    let bestDist = Infinity;
+    let bestKey = "";
+    for (const candidate of candidates) {
+      const dist = levenshtein(refPath, candidate);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestKey = candidate;
+      }
+    }
+    if (bestDist <= Math.ceil(refPath.length * .4)) return `\n   Did you mean '{${bestKey}}'?`;
+    return "";
+  };
+  for (const [ownerKey, value] of Object.entries(all)) {
+    if (typeof value !== "string" || !value.includes("{")) continue;
+    let match;
+    const re = new RegExp(COMPOUND_REF_RE.source, COMPOUND_REF_RE.flags);
+    while ((match = re.exec(value)) !== null) {
+      const refPath = match[1];
+      if (all[refPath] !== void 0) continue;
+      const prefix = refPath.split(".")[0];
+      const suggestion = findSuggestion(refPath, allKeys.filter(k => {
+        return k.startsWith(prefix + ".");
+      }));
+      console.warn(`[fsl-theme] Invalid token reference '{${refPath}}' at path '${ownerKey}'.${suggestion}`);
+    }
+  }
+};
+/**
+* Flatten a `ThemeTokens` into a `Record<string, string | number>` with
+* every `{ref}` recursively resolved to its final raw value where possible.
+*
+* By default, unresolvable references (missing target or circular dependency)
+* are preserved as-is in the output. Pass `{ strict: true }` to instead throw
+* on any unresolved reference — useful in tests and build steps that must
+* fail loudly on palette drift.
+*
+* This is the universal primitive — every root is derived from this.
+*/
+const toFlatTokens = (theme, options = {}) => {
+  const {
+    strict = false
+  } = options;
+  const {
+    core: coreFlat,
+    semantic: semanticFlat
+  } = flattenTheme(theme);
+  const all = {
+    ...coreFlat,
+    ...semanticFlat
+  };
+  const unresolved = [];
+  const reportUnresolved = (key, path, reason) => {
+    if (strict) unresolved.push(`${key} → {${path}} (${reason})`);
+  };
+  /** Resolve a single pure `{path}` reference to its raw value. */
+  const resolveRef = (value, seen, ownerKey) => {
+    if (typeof value !== "string" || !isTokenRef(value)) return value;
+    const path = extractRefPath(value);
+    if (seen.has(path)) {
+      reportUnresolved(ownerKey, path, "circular reference");
+      return value;
+    }
+    const target = all[path];
+    if (target === void 0) {
+      reportUnresolved(ownerKey, path, "missing target");
+      return value;
+    }
+    seen.add(path);
+    return resolveRef(target, seen, ownerKey);
+  };
+  /**
+  * Resolve all embedded `{path}` refs in a raw string expression.
+  *
+  * Handles both pure refs (`{core.space.4}`) and compound expressions
+  * (`clamp({core.space.4}, {core.space.6}, {core.space.12})`).
+  */
+  const resolveInline = (value, seen, ownerKey) => {
+    return value.replace(COMPOUND_REF_RE, (_match, path) => {
+      const target = all[path];
+      if (target === void 0) {
+        reportUnresolved(ownerKey, path, "missing target");
+        return `{${path}}`;
+      }
+      if (seen.has(path)) {
+        reportUnresolved(ownerKey, path, "circular reference");
+        return `{${path}}`;
+      }
+      const resolved = resolveRef(target, new Set(seen).add(path), ownerKey);
+      return String(resolved);
+    });
+  };
+  const resolved = {};
+  for (const [key, value] of Object.entries(all)) if (typeof value === "string") {
+    if (isTokenRef(value)) resolved[key] = resolveRef(value, /* @__PURE__ */new Set(), key);else if (value.includes("{")) resolved[key] = resolveInline(value, /* @__PURE__ */new Set(), key);else resolved[key] = value;
+  } else resolved[key] = value;
+  if (strict && unresolved.length > 0) throw new Error(`toFlatTokens: ${unresolved.length} unresolved reference(s):\n  ${unresolved.join("\n  ")}`);
+  return resolved;
+};
+
+//#endregion
+Object.defineProperty(exports, 'COMPOUND_REF_RE', {
+  enumerable: true,
+  get: function () {
+    return COMPOUND_REF_RE;
+  }
+});
+Object.defineProperty(exports, 'SAFE_ID_RE', {
+  enumerable: true,
+  get: function () {
+    return SAFE_ID_RE;
+  }
+});
+Object.defineProperty(exports, 'deepMerge', {
+  enumerable: true,
+  get: function () {
+    return deepMerge;
+  }
+});
+Object.defineProperty(exports, 'flattenObject', {
+  enumerable: true,
+  get: function () {
+    return flattenObject;
+  }
+});
+Object.defineProperty(exports, 'flattenTheme', {
+  enumerable: true,
+  get: function () {
+    return flattenTheme;
+  }
+});
+Object.defineProperty(exports, 'isPlainObject', {
+  enumerable: true,
+  get: function () {
+    return isPlainObject;
+  }
+});
+Object.defineProperty(exports, 'toFlatTokens', {
+  enumerable: true,
+  get: function () {
+    return toFlatTokens;
+  }
+});
+Object.defineProperty(exports, 'validateRefs', {
+  enumerable: true,
+  get: function () {
+    return validateRefs;
+  }
+});