@sorb/seed 0.2.0 → 0.4.0

package/src/emit/sorbPrimevue.js

@@ -0,0 +1,240 @@
+// Sorb PrimeVue v4 preset format (`sorb/primevue-preset`).
+//
+// PROMOTED from `sorb-demo-primevue/src/jjPreset.js` (P4/P4a spike →
+// framework-targets-productization T4, first of the six JJ-demo formats that
+// is a JS-EMITTING target rather than a CSS one). The demo file stays in
+// place for now (T8 retrofit is founder-gated); this is the canonical,
+// generalized home.
+//
+// MECHANISM (carried from the spike): a `definePreset` leaf value that is a
+// plain string (not one of PrimeVue's own `{a.b.c}` refs) is written VERBATIM
+// as the corresponding `--p-*` custom property's value. `var(--kebab-token)`
+// strings therefore make every `--p-*` var a pure indirection onto the kit's
+// own CSS vars — a Sorb bridge push re-themes PrimeVue with zero
+// component-level code changes. Two override tiers, same as the spike:
+//   1. SEMANTIC tier — a small set of roots (`primary`, `text`, `content`,
+//      `formField`, `navigation.item`, `overlay.*`, `colorScheme.light.surface`)
+//      that most PrimeVue components read from, so overriding them re-themes
+//      Card/InputText/Select/Dialog/Toast/Tabs/… all at once.
+//   2. COMPONENT tier — overrides for components that read straight from the
+//      PrimeVue PRIMITIVE palette instead of a semantic root (severity-colored
+//      Tag/Toast) or need an explicit per-component override (Menubar's
+//      brand-colored bar — the kit's `nav.*` tokens are a deliberately
+//      different color story than `content`/`surface`).
+//
+// RISK (framework-targets-productization risk table, T4): the emitted
+// module's `import { definePreset } from '@primeuix/themes'` (+ the base
+// preset import, e.g. `@primeuix/themes/aura`) is a PEER EXPECTATION — this
+// format does not install or vendor `@primeuix/themes`; the consuming app's
+// own bundler/dependency tree must already have it (any PrimeVue v4 app
+// does). `new Function`/eval can't prove this module resolves for real (no
+// `@primeuix/themes` in this package's — or even the consumer's CI —
+// test env); it only proves the emitted source is syntactically the right
+// shape. The real bundler path is proven by the T8 demo retrofit, not this
+// format's test. Document this in the adapter/README snippet too.
+//
+// GENERALIZATION (T0 semantic-role contract): the spike hardcoded Janes
+// Jeans' own token ids as every leaf. Promotion makes every leaf
+// ROLE-RESOLVED — a non-JJ kit passes `options.roleMap` (role id → its own
+// token id) instead of forking this file. Resolution is the same shape as
+// `@sorb/core`'s `resolveRole`/`DEFAULT_ROLE_IDS`, inlined here rather than
+// imported so this format degrades gracefully against an older published
+// `@sorb/core` that predates the role contract (same feature-detect posture
+// as the TargetAdapter registration side — see
+// `sorb-leaf/src/targets/primevue.js`). None of the role ids below are in
+// `@sorb/core`'s canonical `DEFAULT_ROLE_IDS` (JJ's component-tier ids —
+// `button.primary.bg.default`, `card.bg`, `nav.bg`, `toast.bg.success`, …
+// have no canonical counterpart yet; they're kit-private, per the
+// productization spec's "contract scope = the union of the six maps' role
+// columns, not a kit's full token tree"). They still go through the same
+// `roleMap` resolution for consistency, and so a kit that DOES want to
+// override them can.
+//
+// `options.basePreset` (default `'Aura'`) controls BOTH the base-theme
+// import (`@primeuix/themes/<lowercased-name>`) and the `definePreset(<Name>,
+// …)` call's first argument — PrimeVue v4 ships `Aura`/`Material`/`Lara`/
+// `Nora` as documented base presets, each importable the same way.
+
+export const SORB_PRIMEVUE_PRESET = 'sorb/primevue-preset'
+
+/**
+ * Structural role tree describing the PrimeVue `definePreset` shape this
+ * format generates, mirroring `jjPreset.js`'s hand-authored nesting exactly.
+ * Every leaf is a role id (a dot-path token id, canonical-or-JJ) resolved
+ * through `options.roleMap` before becoming a `var(--kebab-id)` ref.
+ */
+export const PRIMEVUE_ROLE_TREE = {
+  semantic: {
+    primary: {
+      color: 'button.primary.bg.default',
+      hoverColor: 'button.primary.bg.hover',
+      activeColor: 'button.primary.bg.hover',
+      contrastColor: 'button.primary.fg.default',
+    },
+    text: {
+      color: 'color.ink',
+      hoverColor: 'color.ink',
+      mutedColor: 'color.ink-muted',
+      hoverMutedColor: 'color.ink-muted',
+    },
+    content: {
+      background: 'card.bg',
+      hoverBackground: 'color.surface-raised',
+      borderColor: 'card.border',
+      color: 'color.ink',
+      hoverColor: 'color.ink',
+      borderRadius: 'card.radius',
+    },
+    formField: {
+      background: 'input.bg.default',
+      disabledBackground: 'input.bg.disabled',
+      filledBackground: 'input.bg.default',
+      filledHoverBackground: 'input.bg.default',
+      filledFocusBackground: 'input.bg.default',
+      borderColor: 'input.border.default',
+      hoverBorderColor: 'input.border.default',
+      focusBorderColor: 'input.border.focus',
+      invalidBorderColor: 'input.border.invalid',
+      color: 'input.fg',
+      disabledColor: 'color.ink-muted',
+      placeholderColor: 'input.placeholder',
+      invalidPlaceholderColor: 'input.placeholder',
+      borderRadius: 'input.radius',
+    },
+    navigation: {
+      item: {
+        activeColor: 'nav.link-active',
+        focusColor: 'nav.link-active',
+      },
+    },
+    overlay: {
+      select: { background: 'card.bg', borderColor: 'card.border', color: 'color.ink' },
+      popover: { background: 'card.bg', borderColor: 'card.border', color: 'color.ink' },
+      modal: { background: 'card.bg', borderColor: 'card.border', color: 'color.ink' },
+    },
+    colorScheme: {
+      light: {
+        surface: {
+          50: 'color.surface-raised',
+          100: 'color.surface-raised',
+          200: 'color.surface-sunken',
+          300: 'color.border',
+        },
+      },
+    },
+  },
+  components: {
+    // The brand-colored top bar — the one place the kit's nav.* tokens
+    // (distinct from the content/surface story used everywhere else) apply.
+    menubar: {
+      colorScheme: {
+        light: {
+          root: { background: 'nav.bg', borderColor: 'nav.bg', color: 'nav.fg' },
+          item: {
+            color: 'nav.fg',
+            focusColor: 'nav.link-active',
+            activeColor: 'nav.link-active',
+            icon: { color: 'nav.fg-muted', focusColor: 'nav.link-active', activeColor: 'nav.link-active' },
+          },
+        },
+      },
+    },
+    // Toast severities: success/danger/info only (no "warn" — PrimeVue's
+    // default stays themed by the semantic content/text overrides above).
+    toast: {
+      colorScheme: {
+        light: {
+          success: { background: 'toast.bg.success', color: 'toast.fg', borderColor: 'toast.bg.success' },
+          error: { background: 'toast.bg.danger', color: 'toast.fg', borderColor: 'toast.bg.danger' },
+          info: { background: 'toast.bg.info', color: 'toast.fg', borderColor: 'toast.bg.info' },
+        },
+      },
+    },
+  },
+}
+
+const cssVarOf = (id) => '--' + String(id).split('.').join('-')
+
+// Same shape as `@sorb/core`'s `resolveRole` — inlined per the promotion
+// spec so this format has no hard runtime dependency on a core version that
+// ships the role contract (see file header).
+const resolveRoleId = (roleId, roleMap) => (roleMap && roleMap[roleId]) || roleId
+
+/**
+ * Recursively walk `PRIMEVUE_ROLE_TREE` (or a subtree), resolving each leaf
+ * role id through `roleMap` and, when `known` is supplied, dropping any leaf
+ * whose resolved token id isn't in the dictionary (skip-missing, same
+ * posture as `sorbMantineVars` — a partial kit still emits a valid, if
+ * smaller, preset rather than a broken var() ref). Empty objects left behind
+ * by an all-missing branch are pruned too.
+ * @param {*} node
+ * @param {Set<string>|undefined} known
+ * @param {Record<string,string>|undefined} roleMap
+ * @param {string[]} missing  accumulator for unresolved role ids (mutated)
+ * @returns {*}
+ */
+const buildPresetNode = (node, known, roleMap, missing) => {
+  if (typeof node === 'string') {
+    const tokenId = resolveRoleId(node, roleMap)
+    if (known && !known.has(tokenId)) {
+      missing.push(tokenId)
+      return undefined
+    }
+    return `var(${cssVarOf(tokenId)})`
+  }
+  const out = {}
+  for (const [key, value] of Object.entries(node)) {
+    const resolved = buildPresetNode(value, known, roleMap, missing)
+    if (resolved === undefined) continue
+    if (typeof resolved === 'object' && Object.keys(resolved).length === 0) continue
+    out[key] = resolved
+  }
+  return out
+}
+
+const BASE_PRESET_IMPORTS = {
+  Aura: '@primeuix/themes/aura',
+  Material: '@primeuix/themes/material',
+  Lara: '@primeuix/themes/lara',
+  Nora: '@primeuix/themes/nora',
+}
+
+/**
+ * format: sorb/primevue-preset
+ * Emits a JS/ESM module string:
+ *   import { definePreset } from '@primeuix/themes';
+ *   import Aura from '@primeuix/themes/aura';
+ *   export const preset = definePreset(Aura, { semantic: {...}, components: {...} });
+ * Every leaf is a `var(--kebab-token-id)` string — the live-preview
+ * invariant, same as every other Sorb format (no baked literals). Pure
+ * function of `{dictionary, options}`; zero `style-dictionary` dep.
+ * @param {{dictionary: {allTokens: Array}, options?: {roleMap?: Record<string,string>, basePreset?: string}}} args
+ * @returns {string} the generated ESM module source.
+ */
+export const sorbPrimevuePreset = ({ dictionary, options }) => {
+  const roleMap = options && options.roleMap
+  const basePreset = (options && options.basePreset) || 'Aura'
+  const known = new Set((dictionary.allTokens || []).map((t) => t.path.join('.')))
+  const missing = []
+
+  const semantic = buildPresetNode(PRIMEVUE_ROLE_TREE.semantic, known, roleMap, missing)
+  const components = buildPresetNode(PRIMEVUE_ROLE_TREE.components, known, roleMap, missing)
+
+  if (missing.length) {
+    console.warn(`  ⚠ sorb/primevue-preset: ${missing.length} unmapped token id(s) skipped: ` + missing.join(', '))
+  }
+
+  const basePresetImport = BASE_PRESET_IMPORTS[basePreset] || `@primeuix/themes/${String(basePreset).toLowerCase()}`
+  const presetBody = JSON.stringify({ semantic, components }, null, 2)
+
+  return (
+    '// AUTO-GENERATED by Style Dictionary (sorb/primevue-preset) — do not edit.\n' +
+    '// PEER EXPECTATION: this module imports `@primeuix/themes` (+ its base preset\n' +
+    '// subpath) — install it in the consuming app; this format neither installs nor\n' +
+    '// vendors it. See sorb-seed/src/emit/sorbPrimevue.js header "RISK".\n' +
+    `import { definePreset } from '@primeuix/themes';\n` +
+    `import ${basePreset} from '${basePresetImport}';\n` +
+    '\n' +
+    `export const preset = definePreset(${basePreset}, ` + presetBody + ');\n'
+  )
+}

package/src/emit/sorbPrimevue.test.js

@@ -0,0 +1,130 @@
+// Tests for the Sorb PrimeVue v4 preset format (`sorb/primevue-preset`) — the
+// first JS-EMITTING target format (the others emit CSS). `@primeuix/themes`
+// isn't installed in this package's test env (it's a peer expectation of the
+// EMITTED module, not a dep of `@sorb/seed` — see the format's file header),
+// so these tests can't `import()` the real output. Instead they (a) assert
+// the raw source string's shape by regex, and (b) `new Function`-evaluate a
+// transformed copy (imports stripped, `definePreset`/base preset stubbed) to
+// prove the object-literal body is syntactically valid and structurally
+// correct — the same "prove it evaluates" spirit as sorbFormat.test.js's
+// `new Function('module','exports', src)` check, adapted for ESM `import`/
+// `export` syntax that `new Function` cannot parse directly.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { SORB_PRIMEVUE_PRESET, PRIMEVUE_ROLE_TREE, sorbPrimevuePreset } from './sorbPrimevue.js'
+
+// Helper: a fabricated dictionary of resolved tokens, keyed by dot-path id.
+const tok = (id) => ({ path: id.split('.') })
+const dictOf = (ids) => ({ allTokens: ids.map(tok) })
+
+// Every role id referenced anywhere in PRIMEVUE_ROLE_TREE, flattened.
+const flattenRoleIds = (node, out = []) => {
+  if (typeof node === 'string') { out.push(node); return out }
+  for (const v of Object.values(node)) flattenRoleIds(v, out)
+  return out
+}
+const ALL_ROLE_IDS = flattenRoleIds(PRIMEVUE_ROLE_TREE)
+
+// Evaluate the object-literal body of an emitted module: strip the `import`
+// lines and the `export const preset = definePreset(Base, ` … `);` wrapper,
+// then run the remaining `{ ... }` object literal through `new Function` with
+// no external bindings needed (it's pure data — strings only).
+const evalPresetBody = (src) => {
+  const withoutImports = src.replace(/^import .*$/gm, '')
+  const match = withoutImports.match(/export const preset = definePreset\(\w+, ([\s\S]*)\);\s*$/)
+  assert.ok(match, 'module source must match the definePreset(Base, {...}); shape')
+  return new Function(`return (${match[1]})`)()
+}
+
+test('format name constant is the documented id', () => {
+  assert.equal(SORB_PRIMEVUE_PRESET, 'sorb/primevue-preset')
+})
+
+test('emits the documented import lines + definePreset(Aura, ...) call by default', () => {
+  const dictionary = dictOf(ALL_ROLE_IDS)
+  const src = sorbPrimevuePreset({ dictionary })
+  assert.match(src, /^import \{ definePreset \} from '@primeuix\/themes';$/m)
+  assert.match(src, /^import Aura from '@primeuix\/themes\/aura';$/m)
+  assert.match(src, /^export const preset = definePreset\(Aura, \{/m)
+  assert.match(src, /\}\);\s*$/)
+})
+
+test('every leaf is a var() reference, never a baked literal (live-preview invariant)', () => {
+  const dictionary = dictOf(ALL_ROLE_IDS)
+  const src = sorbPrimevuePreset({ dictionary })
+  const preset = evalPresetBody(src)
+  const leaves = (o) => Object.values(o).flatMap((v) => (typeof v === 'string' ? [v] : leaves(v)))
+  const values = [...leaves(preset.semantic), ...leaves(preset.components)]
+  assert.ok(values.length > 0)
+  for (const val of values) assert.match(val, /^var\(--[a-z0-9-]+\)$/)
+})
+
+test('semantic tier matches jjPreset.js structure/values exactly (identity roleMap)', () => {
+  const dictionary = dictOf(ALL_ROLE_IDS)
+  const src = sorbPrimevuePreset({ dictionary })
+  const preset = evalPresetBody(src)
+  assert.equal(preset.semantic.primary.color, 'var(--button-primary-bg-default)')
+  assert.equal(preset.semantic.primary.contrastColor, 'var(--button-primary-fg-default)')
+  assert.equal(preset.semantic.text.mutedColor, 'var(--color-ink-muted)')
+  assert.equal(preset.semantic.content.borderRadius, 'var(--card-radius)')
+  assert.equal(preset.semantic.formField.focusBorderColor, 'var(--input-border-focus)')
+  assert.equal(preset.semantic.navigation.item.activeColor, 'var(--nav-link-active)')
+  assert.equal(preset.semantic.overlay.popover.background, 'var(--card-bg)')
+  assert.equal(preset.semantic.colorScheme.light.surface['200'], 'var(--color-surface-sunken)')
+})
+
+test('component tier (Menubar/Toast reading the primitive palette) matches jjPreset.js', () => {
+  const dictionary = dictOf(ALL_ROLE_IDS)
+  const src = sorbPrimevuePreset({ dictionary })
+  const preset = evalPresetBody(src)
+  assert.equal(preset.components.menubar.colorScheme.light.root.background, 'var(--nav-bg)')
+  assert.equal(preset.components.menubar.colorScheme.light.item.icon.color, 'var(--nav-fg-muted)')
+  assert.equal(preset.components.toast.colorScheme.light.success.background, 'var(--toast-bg-success)')
+  assert.equal(preset.components.toast.colorScheme.light.error.borderColor, 'var(--toast-bg-danger)')
+  assert.equal(preset.components.toast.colorScheme.light.info.color, 'var(--toast-fg)')
+})
+
+test('options.roleMap remaps the role-id column without forking the format', () => {
+  const roleMap = {
+    'button.primary.bg.default': 'kit.primary',
+    'color.ink': 'kit.text',
+  }
+  const dictionary = dictOf(['kit.primary', 'kit.text', ...ALL_ROLE_IDS.filter((id) => id !== 'button.primary.bg.default' && id !== 'color.ink')])
+  const src = sorbPrimevuePreset({ dictionary, options: { roleMap } })
+  const preset = evalPresetBody(src)
+  assert.equal(preset.semantic.primary.color, 'var(--kit-primary)')
+  assert.equal(preset.semantic.text.color, 'var(--kit-text)')
+  // unmapped roles fall back to their canonical/default id
+  assert.equal(preset.semantic.text.mutedColor, 'var(--color-ink-muted)')
+})
+
+test('options.basePreset swaps both the base import and the definePreset() base arg', () => {
+  const dictionary = dictOf(ALL_ROLE_IDS)
+  const src = sorbPrimevuePreset({ dictionary, options: { basePreset: 'Lara' } })
+  assert.match(src, /^import Lara from '@primeuix\/themes\/lara';$/m)
+  assert.match(src, /^export const preset = definePreset\(Lara, \{/m)
+})
+
+test('an unmapped/missing token id is skipped, not emitted as a broken var() ref', () => {
+  // Only supply the tokens for the `primary` subtree; everything else absent.
+  const dictionary = dictOf([
+    'button.primary.bg.default',
+    'button.primary.bg.hover',
+    'button.primary.fg.default',
+  ])
+  const src = sorbPrimevuePreset({ dictionary })
+  const preset = evalPresetBody(src)
+  assert.equal(preset.semantic.primary.color, 'var(--button-primary-bg-default)')
+  // text/content/formField/etc never had their tokens present → pruned away
+  assert.equal(preset.semantic.text, undefined)
+  assert.equal(preset.components.menubar, undefined)
+})
+
+test('emitted module source contains no baked literal — only var(--kebab) leaves', () => {
+  const dictionary = dictOf(ALL_ROLE_IDS)
+  const src = sorbPrimevuePreset({ dictionary })
+  // Every quoted string value in the object body must be a var() ref.
+  const stringValues = [...src.matchAll(/: "([^"]*)"/g)].map((m) => m[1])
+  assert.ok(stringValues.length > 0)
+  for (const v of stringValues) assert.match(v, /^var\(--[a-z0-9-]+\)$/)
+})

package/src/emit/sorbShadcn.js

@@ -0,0 +1,186 @@
+// Sorb shadcn/ui theme format (`sorb/shadcn-theme`) — framework-targets-
+// productization T1 (Tailwind v4 + shadcn/ui).
+//
+// Promoted from `sorb-demo-tailwind/src/tokens/shadcn-map.css` +
+// `shadcn-theme.css` (hand-authored source material) into ONE generated CSS
+// artifact: shadcn's conventional `:root{}` var map (--background,
+// --primary, …) chained onto Sorb's own tokens via the T0 semantic-role
+// contract, plus the `@theme inline{}` Tailwind-utility binding block
+// (including the `calc()` radius scale). Zero `style-dictionary` dep — pure
+// function of `{ dictionary, options }`, matching `sorbFormat.js`'s
+// conventions.
+//
+// Every leaf is a `var(--<kebab>)` reference (live-preview invariant) — the
+// bridge's runtime var-swap re-themes shadcn components with no
+// shadcn-specific bridge code.
+
+/** @type {'sorb/shadcn-theme'} */
+export const SORB_SHADCN = 'sorb/shadcn-theme'
+
+/**
+ * Resolve a canonical role id to the kit's actual token id via an optional
+ * override map — inlined one-liner matching `@sorb/core`'s `resolveRole`
+ * (T0). Kept local rather than imported so `@sorb/seed` doesn't take a
+ * runtime dep on a specific `@sorb/core` version (formats are plain
+ * functions; the published core can lag the connector contract).
+ * @param {string} roleId
+ * @param {Record<string,string>} [roleMap]
+ * @returns {string}
+ */
+const resolveShadcnRole = (roleId, roleMap) => (roleMap && roleMap[roleId]) || roleId
+
+const cssVarOf = (tokenId) => '--' + String(tokenId).split('.').join('-')
+
+// shadcn CSS var → canonical role id (DEFAULT_ROLE_IDS.color / .radius from
+// `@sorb/core`). Order matches the hand-authored `shadcn-map.css` for a
+// clean round-trip diff.
+const SHADCN_COLOR_ROLE_MAP = [
+  ['--background', 'color.surface'],
+  ['--foreground', 'color.ink'],
+  ['--card', 'color.surface'],
+  ['--card-foreground', 'color.ink'],
+  ['--popover', 'color.surface'],
+  ['--popover-foreground', 'color.ink'],
+  ['--primary', 'color.brand'],
+  ['--primary-foreground', 'color.brand-contrast'],
+  ['--secondary', 'color.surface-raised'],
+  ['--secondary-foreground', 'color.ink'],
+  ['--muted', 'color.surface-sunken'],
+  ['--muted-foreground', 'color.ink-muted'],
+  ['--accent', 'color.accent'],
+  ['--accent-foreground', 'color.accent-contrast'],
+  ['--destructive', 'color.danger'],
+  ['--border', 'color.border'],
+  ['--input', 'color.border'],
+  ['--ring', 'color.focus-ring'],
+]
+
+// ROLE-CONTRACT GAP (flagged, not invented — framework-targets-
+// productization T1 note): shadcn's `--destructive-foreground` wants "the
+// ink color that reads on top of --destructive". `@sorb/core`'s
+// `DEFAULT_ROLE_IDS` only defines `-contrast` roles for brand/accent, not
+// danger — there is no canonical `color.danger-contrast`. Rather than invent
+// one unilaterally, this references the kit's raw `color.white` primitive
+// (matches the JJ demo's hand-authored value) directly — NOT run through
+// `options.roleMap`, since it isn't a role id. A kit without a `color.white`
+// token overrides via `options.destructiveForeground`.
+const DESTRUCTIVE_FOREGROUND_DEFAULT = 'color.white'
+
+// `--radius` role — the one non-color entry in the `:root{}` map.
+const RADIUS_ROLE_DEFAULT = 'radius.control'
+
+// `@theme inline{}` block: purely mechanical — chains Tailwind's `--color-*`
+// theme keys onto the shadcn vars defined above (never onto Sorb token ids
+// directly), plus the fixed `calc()` radius scale. Independent of roleMap.
+const THEME_INLINE_COLOR_ENTRIES = [
+  ['--color-background', '--background'],
+  ['--color-foreground', '--foreground'],
+  ['--color-card', '--card'],
+  ['--color-card-foreground', '--card-foreground'],
+  ['--color-popover', '--popover'],
+  ['--color-popover-foreground', '--popover-foreground'],
+  ['--color-primary', '--primary'],
+  ['--color-primary-foreground', '--primary-foreground'],
+  ['--color-secondary', '--secondary'],
+  ['--color-secondary-foreground', '--secondary-foreground'],
+  ['--color-muted', '--muted'],
+  ['--color-muted-foreground', '--muted-foreground'],
+  ['--color-accent', '--accent'],
+  ['--color-accent-foreground', '--accent-foreground'],
+  ['--color-destructive', '--destructive'],
+  ['--color-destructive-foreground', '--destructive-foreground'],
+  ['--color-border', '--border'],
+  ['--color-input', '--input'],
+  ['--color-ring', '--ring'],
+]
+
+/**
+ * Build the `:root{}` shadcn-var → Sorb-token map, resolving roles through
+ * `options.roleMap` (defaulting to identity — the JJ reference kit already
+ * uses canonical role ids).
+ * @param {{roleMap?: Record<string,string>, destructiveForeground?: string, radiusRole?: string}} [options]
+ * @param {Set<string>} [knownTokenIds]  when provided, unknown resolved ids are warned (not skipped — CSS still emits, just points at an undefined var).
+ * @returns {string[]} lines
+ */
+export const shadcnRootLines = (options = {}, knownTokenIds) => {
+  const { roleMap, destructiveForeground, radiusRole } = options
+  const missing = []
+  const resolve = (roleId) => resolveShadcnRole(roleId, roleMap)
+  const checkAndVar = (tokenId, roleId) => {
+    if (knownTokenIds && !knownTokenIds.has(tokenId)) missing.push(`${roleId} → ${tokenId}`)
+    return `var(${cssVarOf(tokenId)})`
+  }
+
+  const lines = []
+  for (const [shadcnVar, roleId] of SHADCN_COLOR_ROLE_MAP) {
+    const tokenId = resolve(roleId)
+    lines.push(`  ${shadcnVar}: ${checkAndVar(tokenId, roleId)};`)
+    if (shadcnVar === '--destructive') {
+      // --destructive-foreground has no canonical role (see the
+      // ROLE-CONTRACT GAP note above) — emitted right after --destructive to
+      // match the hand-authored `shadcn-map.css` ordering byte-for-byte.
+      const destructiveFgId = destructiveForeground || DESTRUCTIVE_FOREGROUND_DEFAULT
+      lines.push(`  --destructive-foreground: ${checkAndVar(destructiveFgId, '(non-role) destructiveForeground')};`)
+    }
+  }
+  const radiusId = resolve(radiusRole || RADIUS_ROLE_DEFAULT)
+  lines.push(`  --radius: ${checkAndVar(radiusId, radiusRole || RADIUS_ROLE_DEFAULT)};`)
+
+  if (missing.length) {
+    // eslint-disable-next-line no-console
+    console.warn(`  ⚠ sorb/shadcn-theme: ${missing.length} unresolved token id(s): ` + missing.join(', '))
+  }
+  return lines
+}
+
+/** The fixed `@theme inline{}` block lines (mechanical; no roleMap input). */
+export const shadcnThemeInlineLines = () => {
+  const lines = THEME_INLINE_COLOR_ENTRIES.map(([key, ref]) => `  ${key}: var(${ref});`)
+  lines.push(
+    '  --radius-sm: calc(var(--radius) - 4px);',
+    '  --radius-md: calc(var(--radius) - 2px);',
+    '  --radius-lg: var(--radius);',
+    '  --radius-xl: calc(var(--radius) + 4px);',
+  )
+  return lines
+}
+
+/**
+ * format: sorb/shadcn-theme
+ * Emits ONE CSS artifact: shadcn's `:root{}` semantic-var map (chained onto
+ * Sorb tokens via the role contract) followed by the `@theme inline{}`
+ * Tailwind-utility binding block — reproducing what
+ * `sorb-demo-tailwind/src/tokens/shadcn-map.css` + `shadcn-theme.css` hand-
+ * authored. Pair with `variables.css` (defines the Sorb vars this format
+ * references) in the consumer's CSS import order:
+ *   @import "tailwindcss";
+ *   @import "./variables.css";     sorb tokens — the bridge swaps these live
+ *   @import "./shadcn-theme.css";  this file
+ * @param {{dictionary: {allTokens: Array<{path: string[]}>}, options?: {roleMap?: Record<string,string>, destructiveForeground?: string, radiusRole?: string}}} args
+ * @returns {string}
+ */
+export const sorbShadcn = ({ dictionary, options } = {}) => {
+  const known = dictionary && Array.isArray(dictionary.allTokens)
+    ? new Set(dictionary.allTokens.map((t) => t.path.join('.')))
+    : undefined
+
+  const rootLines = shadcnRootLines(options || {}, known)
+  const themeLines = shadcnThemeInlineLines()
+
+  return (
+    '/* AUTO-GENERATED by Style Dictionary (sorb/shadcn-theme) — do not edit.\n' +
+    '   shadcn/ui semantic-var map, chained onto Sorb\'s runtime CSS vars via the\n' +
+    '   semantic-role contract (@sorb/core DEFAULT_ROLE_IDS), plus the `@theme\n' +
+    '   inline` Tailwind-utility bindings shadcn components read (bg-primary,\n' +
+    '   text-foreground, border-input, …). Import order in your entry CSS:\n' +
+    '       @import "tailwindcss";\n' +
+    '       @import "./variables.css";     sorb tokens — the bridge swaps these live\n' +
+    '       @import "./shadcn-theme.css";  this file */\n' +
+    ':root {\n' +
+    rootLines.join('\n') +
+    '\n}\n\n' +
+    '@theme inline {\n' +
+    themeLines.join('\n') +
+    '\n}\n'
+  )
+}

package/src/emit/sorbShadcn.test.js

@@ -0,0 +1,102 @@
+// Tests for the Sorb shadcn/ui theme format (`sorb/shadcn-theme`).
+// Run: node --test
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { SORB_SHADCN, sorbShadcn, shadcnRootLines, shadcnThemeInlineLines } from './sorbShadcn.js'
+
+// A fabricated dictionary carrying the JJ role tokens the format resolves
+// against (identity roleMap case — the JJ reference kit already uses
+// canonical role ids from `@sorb/core`'s DEFAULT_ROLE_IDS).
+const JJ_ROLE_TOKEN_IDS = [
+  'color.surface', 'color.surface-raised', 'color.surface-sunken',
+  'color.ink', 'color.ink-muted',
+  'color.brand', 'color.brand-contrast',
+  'color.accent', 'color.accent-contrast',
+  'color.danger', 'color.border', 'color.focus-ring',
+  'color.white',
+  'radius.control',
+]
+const dictionary = { allTokens: JJ_ROLE_TOKEN_IDS.map((id) => ({ path: id.split('.') })) }
+
+test('format id is sorb/shadcn-theme', () => {
+  assert.equal(SORB_SHADCN, 'sorb/shadcn-theme')
+})
+
+test('root map: identity roleMap resolves every shadcn var to its canonical role\'s var()', () => {
+  const css = sorbShadcn({ dictionary })
+  assert.match(css, /--background: var\(--color-surface\);/)
+  assert.match(css, /--foreground: var\(--color-ink\);/)
+  assert.match(css, /--primary: var\(--color-brand\);/)
+  assert.match(css, /--primary-foreground: var\(--color-brand-contrast\);/)
+  assert.match(css, /--destructive: var\(--color-danger\);/)
+  assert.match(css, /--border: var\(--color-border\);/)
+  assert.match(css, /--input: var\(--color-border\);/)
+  assert.match(css, /--ring: var\(--color-focus-ring\);/)
+  assert.match(css, /--radius: var\(--radius-control\);/)
+})
+
+test('root map: destructive-foreground falls back to the color.white primitive (role-contract gap)', () => {
+  const css = sorbShadcn({ dictionary })
+  assert.match(css, /--destructive-foreground: var\(--color-white\);/)
+})
+
+test('root map: options.roleMap overrides a canonical role id to a non-JJ kit token', () => {
+  const css = sorbShadcn({
+    dictionary: { allTokens: [{ path: ['brand', 'primary'] }, ...dictionary.allTokens] },
+    options: { roleMap: { 'color.brand': 'brand.primary' } },
+  })
+  assert.match(css, /--primary: var\(--brand-primary\);/)
+})
+
+test('options.destructiveForeground / options.radiusRole override the non-role defaults', () => {
+  const css = sorbShadcn({
+    dictionary: { allTokens: [{ path: ['ink', 'onDanger'] }, { path: ['radius', 'lg'] }, ...dictionary.allTokens] },
+    options: { destructiveForeground: 'ink.onDanger', radiusRole: 'radius.lg' },
+  })
+  assert.match(css, /--destructive-foreground: var\(--ink-onDanger\);/)
+  assert.match(css, /--radius: var\(--radius-lg\);/)
+})
+
+test('emits an @theme inline block with the calc() radius scale, chained onto shadcn vars (not raw tokens)', () => {
+  const css = sorbShadcn({ dictionary })
+  assert.match(css, /@theme inline \{/)
+  assert.match(css, /--color-background: var\(--background\);/)
+  assert.match(css, /--color-primary-foreground: var\(--primary-foreground\);/)
+  assert.match(css, /--radius-sm: calc\(var\(--radius\) - 4px\);/)
+  assert.match(css, /--radius-md: calc\(var\(--radius\) - 2px\);/)
+  assert.match(css, /--radius-lg: var\(--radius\);/)
+  assert.match(css, /--radius-xl: calc\(var\(--radius\) \+ 4px\);/)
+})
+
+test('every emitted value is a var()/calc(var()) reference — never a baked literal (live-preview invariant)', () => {
+  const css = sorbShadcn({ dictionary })
+  const declLines = css.split('\n').filter((l) => /^\s*--[a-z-]+:/.test(l))
+  assert.ok(declLines.length > 0)
+  for (const line of declLines) {
+    assert.match(line, /:\s*(var\(--[a-zA-Z0-9-]+\)|calc\(var\(--[a-zA-Z0-9-]+\)[^)]*\))\s*;\s*$/, `unexpected literal: ${line}`)
+  }
+})
+
+test('warns (does not throw) when a resolved token id is not in the dictionary', () => {
+  const warnings = []
+  const origWarn = console.warn
+  console.warn = (msg) => warnings.push(msg)
+  try {
+    const css = sorbShadcn({ dictionary: { allTokens: [{ path: ['color', 'surface'] }] } })
+    assert.match(css, /--background: var\(--color-surface\);/) // still emits
+  } finally {
+    console.warn = origWarn
+  }
+  assert.ok(warnings.length > 0)
+  assert.match(warnings[0], /unresolved token id/)
+})
+
+test('shadcnRootLines / shadcnThemeInlineLines are pure and independently testable', () => {
+  const rootLines = shadcnRootLines({})
+  assert.equal(rootLines.length, SHADCN_ROOT_LINE_COUNT)
+  const themeLines = shadcnThemeInlineLines()
+  assert.equal(themeLines.filter((l) => l.includes('--radius-')).length, 4)
+})
+
+// 18 color-role pairs + destructive-foreground + radius
+const SHADCN_ROOT_LINE_COUNT = 20