@sorb/seed 0.2.0 → 0.4.0

package/src/index.js

@@ -5,3 +5,51 @@
 // so the old `resolveBindableTokens` export is gone. What remains useful as a
 // library is the token-annotation layer used by `capture`.
 export { buildTokenIndex, annotateTree, matchColor, matchDimension } from './annotateTokens.js'
+
+// Sorb's custom Style Dictionary outputs (component-compat-roadmap P0, part
+// 2) — promoted from sorb-demo's copy-local `sd/sorb-format.js` so target
+// adapters import these formats instead of duplicating them. A consumer's
+// `sd.config.js` registers these with `StyleDictionary.registerFormat`/
+// `registerParser` the same way sorb-demo's does.
+export {
+  tierOfFile,
+  SORB_RESOLVED,
+  SORB_THEME_NESTED,
+  SORB_ALIASES,
+  SORB_VERSIONS,
+  SORB_SET_META,
+  SORB_TAILWIND,
+  SORB_TAILWIND_V3,
+  SORB_TOKENSET,
+  sorbSetMeta,
+  sorbVersions,
+  sorbTokenSet,
+  sorbResolved,
+  sorbAliases,
+  sorbThemeNested,
+  tailwindThemeEntry,
+  sorbTailwind,
+  tailwindV3Slot,
+  sorbTailwindV3,
+} from './emit/sorbFormat.js'
+
+// Mantine v7 CSS-var override format (framework-targets-productization T2) —
+// promoted from `sorb-demo-mantine/sd/mantine-format.js`.
+export { SORB_MANTINE_VARS, MANTINE_VAR_MAP, sorbMantineVars } from './emit/sorbMantine.js'
+
+// shadcn/ui theme format (framework-targets-productization T1) — promoted
+// from `sorb-demo-tailwind`'s hand-authored `shadcn-map.css`+`shadcn-theme.css`.
+export { SORB_SHADCN, sorbShadcn, shadcnRootLines, shadcnThemeInlineLines } from './emit/sorbShadcn.js'
+
+// MUI v6 CSS-var override format (framework-targets-productization T3) —
+// promoted from `sorb-demo-mui/sd.config.js:18-86`.
+export { SORB_MUI_VARS, MUI_VAR_MAP, sorbMuiVars } from './emit/sorbMui.js'
+
+// Angular Material 20 M3 system-variable override format
+// (framework-targets-productization T5) — promoted from
+// `sorb-demo-angular/sd.config.js:96-113`.
+export { SORB_MAT_SYS_VARS, MAT_SYS_MAP, sorbMatSysVars } from './emit/sorbMatSys.js'
+
+// PrimeVue v4 preset format (framework-targets-productization T4) — the first
+// JS-emitting target format; generated from `sorb-demo-primevue/src/jjPreset.js`.
+export { SORB_PRIMEVUE_PRESET, PRIMEVUE_ROLE_TREE, sorbPrimevuePreset } from './emit/sorbPrimevue.js'

package/src/sources/figmaPlugin.js

@@ -0,0 +1,83 @@
+// `figma-plugin` SourceConnector — the DEFAULT Figma tokens source (all
+// tiers; no Enterprise gate). spec/sorb/figma-source-connector.md §1a.
+//
+// Unlike `storybook-dom` (a local Playwright/Node process this package drives
+// directly), this connector's data does NOT come from a locally-callable API.
+// It comes from the Figma plugin (`sorb-canopy`), which reads
+// `figma.variables.*` **in-file** (via the shared token-mapping walk —
+// `sorb-canopy/lib/token-mapping.js`), maps it to Sorb's resolved-map shape,
+// and PUSHES it to the juice bridge (`POST /tokens/figma`, the plugin's
+// "Export variables" action). So this connector is a BRIDGE CLIENT, not a
+// Figma caller — spec's flagged riskiest coupling ("the plugin is the
+// executor, the seed-side connector is a bridge client"). `readTokens()`
+// reads the latest pushed artifact back via `GET /tokens/figma`.
+//
+// v1 scope is tokens-first (figma-source-connector.md §1a Fork F /
+// §R "Cut"): `listUnits`/`captureGeometry` need a geometry-capable bridge
+// endpoint the plugin doesn't push yet (component/node geometry, not just
+// variables) — that's a deferred follow-on phase, so they throw a clear,
+// actionable error instead of pretending to call Figma directly.
+//
+// No local token-mapping fork: this connector does no Figma-value mapping of
+// its own — the resolved-map entries it reads back already match
+// `@sorb/core`'s `ResolvedToken` shape because `sorb-canopy/lib/token-
+// mapping.js` produced them before the push. There is nothing to share/
+// extract on the seed side (the mapping stays owned by canopy, the one place
+// that actually touches `figma.variables.*`).
+
+import { registerSource } from '@sorb/core'
+
+// sorb.config.json may set seed.bridgeOrigin (mirrors storybookUrlOf's
+// seed.storybookUrl convention). Falls back to juice's default dev port.
+export const bridgeOriginOf = (config) =>
+  ((config && config.seed && config.seed.bridgeOrigin) || (config && config.bridgeOrigin) || 'http://localhost:7777').replace(
+    /\/$/,
+    '',
+  )
+
+const readTokens = async (config) => {
+  const origin = bridgeOriginOf(config)
+  const url = `${origin}/tokens/figma`
+  let res
+  try {
+    res = await fetch(url)
+  } catch (e) {
+    throw new Error(
+      `figma-plugin source: could not reach the bridge at ${origin} (${e.message}). ` +
+        'Run `sorb dev` first.',
+    )
+  }
+  if (res.status === 404) {
+    throw new Error(
+      'figma-plugin source: no Figma export yet — in the Sorb Figma plugin, run ' +
+        `"Export variables" (bridge: ${origin}).`,
+    )
+  }
+  if (!res.ok) {
+    throw new Error(`figma-plugin source: bridge GET /tokens/figma failed — HTTP ${res.status}`)
+  }
+  const artifact = await res.json()
+  return Array.isArray(artifact.tokens) ? artifact.tokens : []
+}
+
+const GEOMETRY_NOT_YET_IMPLEMENTED =
+  'figma-plugin source: listUnits/captureGeometry are not implemented in v1 (tokens-first — ' +
+  'see spec/sorb/figma-source-connector.md §1a Fork F). Use readTokens() for the token half; ' +
+  'geometry capture from Figma is a deferred follow-on phase.'
+
+const listUnits = async () => {
+  throw new Error(GEOMETRY_NOT_YET_IMPLEMENTED)
+}
+
+const captureGeometry = async () => {
+  throw new Error(GEOMETRY_NOT_YET_IMPLEMENTED)
+}
+
+export const figmaPluginConnector = {
+  id: 'figma-plugin',
+  listUnits,
+  captureGeometry,
+  readTokens,
+}
+
+registerSource(figmaPluginConnector)

package/src/sources/figmaPlugin.test.js

@@ -0,0 +1,65 @@
+// Tests for the `figma-plugin` SourceConnector (figma-source-connector.md
+// §1a). Mirrors the contract-registration style of sorb-core's
+// connectors.test.js dummy-source test, plus exercises readTokens() as a
+// bridge CLIENT against a mocked `fetch` (no real juice server needed —
+// the contract is "GET /tokens/figma returns { tokens: ResolvedToken[] }").
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { connectors, getSource } from '@sorb/core'
+import { figmaPluginConnector, bridgeOriginOf } from './figmaPlugin.js'
+
+test('registers under id "figma-plugin" and round-trips via getSource (contract dispatch)', () => {
+  assert.equal(getSource('figma-plugin'), figmaPluginConnector)
+  assert.equal(connectors.source.get('figma-plugin'), figmaPluginConnector)
+})
+
+test('bridgeOriginOf: defaults to the juice dev port, honors seed.bridgeOrigin, strips trailing slash', () => {
+  assert.equal(bridgeOriginOf({}), 'http://localhost:7777')
+  assert.equal(bridgeOriginOf(), 'http://localhost:7777')
+  assert.equal(bridgeOriginOf({ seed: { bridgeOrigin: 'http://localhost:9999/' } }), 'http://localhost:9999')
+  assert.equal(bridgeOriginOf({ bridgeOrigin: 'http://example.com/' }), 'http://example.com')
+})
+
+test('readTokens: reads the resolved-map array back from GET /tokens/figma', async (t) => {
+  const tokens = [{ id: 'color.bg.primary', cssVar: '--color-bg-primary', value: '#ffffff', tier: 'primitive', type: 'color' }]
+  const calls = []
+  const realFetch = global.fetch
+  global.fetch = async (url) => {
+    calls.push(url)
+    return { ok: true, status: 200, json: async () => ({ fileKey: 'abc', exportedAt: '2026-08-29T00:00:00Z', tokens }) }
+  }
+  t.after(() => { global.fetch = realFetch })
+
+  const got = await figmaPluginConnector.readTokens({ seed: { bridgeOrigin: 'http://localhost:7777' } })
+  assert.deepEqual(got, tokens)
+  assert.equal(calls[0], 'http://localhost:7777/tokens/figma')
+})
+
+test('readTokens: 404 (no export yet) throws an actionable "Export variables" error', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => ({ ok: false, status: 404, json: async () => ({ error: 'No Figma export yet.' }) })
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /Export variables/)
+})
+
+test('readTokens: non-2xx, non-404 → surfaces the HTTP status', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => ({ ok: false, status: 500, json: async () => ({}) })
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /HTTP 500/)
+})
+
+test('readTokens: network failure (bridge not running) → actionable error naming the origin', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => { throw new Error('ECONNREFUSED') }
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /could not reach the bridge at http:\/\/localhost:7777/)
+})
+
+test('listUnits/captureGeometry: v1 tokens-first scope — throw a clear not-yet-implemented error, not a silent no-op', async () => {
+  await assert.rejects(() => figmaPluginConnector.listUnits({}), /not implemented in v1/)
+  await assert.rejects(() => figmaPluginConnector.captureGeometry({ id: 'u1' }, {}), /not implemented in v1/)
+})

package/src/sources/storybookDom.js

@@ -0,0 +1,188 @@
+// `storybook-dom` SourceConnector — the default SOURCE connector (registered
+// under `@sorb/core`'s DEFAULT_SOURCE_ID = 'storybook-dom'). Extracted from
+// captureCli.js verbatim (spec/sorb/connectors-architecture.md §3.1, C1) — a
+// pure refactor, no behavior change. Owns everything source-specific:
+// discovering Storybook story entries (`listUnits`), running Playwright +
+// the `capture.js` walker to capture one entry's raw geometry
+// (`captureGeometry`), and reading the DTCG/Style-Dictionary resolved token
+// map (`readTokens`). The generic pipeline (tightenRoot -> annotateTree ->
+// hash -> write) stays in captureCli.js and is fed by this connector.
+
+import { basename, extname, dirname, resolve } from 'path'
+import { readFileSync, existsSync } from 'fs'
+import { build } from 'esbuild'
+import { registerSource } from '@sorb/core'
+
+// Playwright is an OPTIONAL peer dep — only `capture` needs it, and it pulls a
+// ~150 MB browser. Lazy-load it so plain installs and `resolve` stay lean.
+const loadChromium = async () => {
+  try {
+    const { chromium } = await import('playwright')
+    return chromium
+  } catch {
+    console.error(
+      '✗ `sorb-seed capture` needs Playwright (it is an optional peer dep).\n' +
+        '  Install it where you run capture:\n' +
+        '    npm install playwright            # its postinstall fetches Chromium\n' +
+        '  (or: npm install playwright && npx playwright install chromium)',
+    )
+    process.exit(1)
+  }
+}
+
+// The `playwright` PACKAGE can be installed while its Chromium BROWSER binary is
+// not (that's a separate `npx playwright install chromium` step). Launching then
+// throws a raw "Executable doesn't exist" error — turn it into the same
+// actionable guidance the missing-package path already gives.
+export const launchChromium = async (chromium) => {
+  try {
+    return await chromium.launch()
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e)
+    if (/Executable doesn't exist|playwright install|browserType\.launch/i.test(msg)) {
+      console.error(
+        '✗ `sorb-seed capture` found Playwright but its Chromium browser is not installed.\n' +
+          '  Install the browser where you run capture:\n' +
+          '    npx playwright install chromium',
+      )
+      process.exit(1)
+    }
+    throw e
+  }
+}
+
+// Bundle the walker into a single IIFE string we can addInitScript() into
+// every page. Playwright can't pass functions across the boundary directly,
+// and our walker has cross-file imports → bundling is the clean answer.
+const buildWalkerBundle = async () => {
+  const here = dirname(new URL(import.meta.url).pathname)
+  const out = await build({
+    entryPoints: [resolve(here, '..', 'capture.js')],
+    bundle: true,
+    format: 'iife',
+    platform: 'browser',
+    write: false,
+    logLevel: 'silent',
+    target: 'es2020',
+  })
+  return out.outputFiles[0].text
+}
+
+const isStoryEntry = (e) =>
+  e && (e.type === 'story' || (e.type === undefined && e.importPath)) // SB7/8: type:'story'
+
+// componentName: "Button" from "./src/.../Button.stories.jsx"
+const componentNameFromImportPath = (importPath) => {
+  const file = basename(importPath, extname(importPath)) // "Button.stories"
+  return file.replace(/\.stories$/i, '')
+}
+
+// sorb.config.json may set seed.storybookUrl. Fall back to localhost.
+export const storybookUrlOf = (config) =>
+  (config.seed && config.seed.storybookUrl) || 'http://localhost:6006'
+
+// ─── Playwright session (browser + context + walker init script) ──────────
+// Lazily launched on the first captureGeometry() call and reused across every
+// unit in a run — exactly today's single-launch/many-pages lifecycle. Not
+// part of the shared SourceConnector contract (that's just listUnits /
+// captureGeometry / readTokens); captureCli.js calls closeSession() once
+// after it has processed every unit, mirroring today's single browser.close().
+let session = null // { browser, ctx, sbUrl }
+
+const ensureSession = async (sbUrl) => {
+  if (session && session.sbUrl === sbUrl) return session
+  if (session) await closeSession()
+  const chromium = await loadChromium()
+  const walker = await buildWalkerBundle()
+  const browser = await launchChromium(chromium)
+  const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 } })
+  await ctx.addInitScript({ content: walker })
+  session = { browser, ctx, sbUrl }
+  return session
+}
+
+export const closeSession = async () => {
+  if (session) {
+    await session.browser.close()
+    session = null
+  }
+}
+
+// ─── SourceConnector implementation ────────────────────────────────────────
+
+const listUnits = async (config) => {
+  const sbUrl = storybookUrlOf(config).replace(/\/$/, '')
+  console.log(`→ Storybook: ${sbUrl}`)
+  let sbIndex
+  try {
+    const res = await fetch(`${sbUrl}/index.json`)
+    if (!res.ok) throw new Error('HTTP ' + res.status)
+    sbIndex = await res.json()
+  } catch (e) {
+    console.error('✗ Could not fetch Storybook index:', e.message)
+    process.exit(1)
+  }
+  const entries = Object.values(sbIndex.entries || sbIndex.stories || {}).filter(isStoryEntry)
+  return entries.map((e) => ({
+    id: e.id,
+    name: e.name,
+    title: e.title,
+    importPath: e.importPath,
+  }))
+}
+
+const captureGeometry = async (unit, config) => {
+  const sbUrl = storybookUrlOf(config).replace(/\/$/, '')
+  const { ctx } = await ensureSession(sbUrl)
+  const url = `${sbUrl}/iframe.html?id=${unit.id}&viewMode=story`
+  const page = await ctx.newPage()
+  try {
+    console.log(`  · ${unit.id}`)
+    await page.goto(url, { waitUntil: 'load' })
+    // Wait for Storybook to actually render the story.
+    await page
+      .waitForFunction(
+        () => !!document.querySelector('#storybook-root *'),
+        { timeout: 15000 },
+      )
+      .catch(() => {})
+    await page.evaluate(() => document.fonts && document.fonts.ready)
+    await page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {})
+
+    const rawTree = await page.evaluate(() => {
+      const root = document.querySelector('#storybook-root')
+      return root ? window.__sorbCapture(root) : null
+    })
+    if (!rawTree) {
+      console.warn('    ⚠ no #storybook-root content; skipped')
+      return null
+    }
+    return rawTree
+  } finally {
+    await page.close()
+  }
+}
+
+// Thin wrapper over the resolved bindable token map produced by `sorb-seed
+// resolve` (Style Dictionary build against the DTCG sources). Capture's own
+// generic pipeline still reads `.sorb/resolved.json` directly (unchanged) —
+// this exists so the connector satisfies the SOURCE contract for other
+// consumers. Does not move the SD internals (those stay owned by `resolve`).
+const readTokens = async (config) => {
+  const cwd = process.cwd()
+  const p = resolve(cwd, '.sorb/resolved.json')
+  if (!existsSync(p)) {
+    throw new Error('No .sorb/resolved.json — run `sorb-seed resolve` first.')
+  }
+  const data = JSON.parse(readFileSync(p, 'utf-8'))
+  return Array.isArray(data) ? data : data.tokens
+}
+
+export const storybookDomConnector = {
+  id: 'storybook-dom',
+  listUnits,
+  captureGeometry,
+  readTokens,
+}
+
+registerSource(storybookDomConnector)