@awarebydefault/display-case 1.0.0

package/src/core/affected.ts

@@ -0,0 +1,144 @@
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+/**
+ * Change-scoping support: compute, for a set of changed files, which components
+ * a render-time check (a11y / visual) actually needs to re-run.
+ *
+ * A component is "affected" when any changed file lies in the *import closure*
+ * of its case file — the case itself, the component it imports, and everything
+ * those pull in transitively (including `@import`ed CSS). The closure follows
+ * only **relative** specifiers: a Display Case showcase is dependency-light and
+ * a pull request virtually never edits a node_modules package, so bare imports
+ * (`react`, `display-case`, …) are intentionally not traced. This keeps the
+ * analysis a pure, fast file walk with no bundler or module-graph dependency.
+ *
+ * Everything here is pure (path + file reads only) so it is unit-testable
+ * without a server, a browser, or git.
+ */
+
+// Extensions we try when a relative specifier omits one, in resolution order.
+// A specifier that already carries an extension (e.g. `./styles.css`) resolves
+// via the bare candidate first.
+const RESOLVE_EXTS = [
+  '.tsx',
+  '.ts',
+  '.jsx',
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.css',
+  '.json',
+] as const
+
+// Relative import/export specifiers in a JS/TS source. Covers `import … from`,
+// `export … from`, side-effect `import '…'`, and dynamic `import('…')` /
+// `require('…')`. Source-level regexes (not a parser) — good enough for a
+// dependency walk and free of any parsing dependency.
+const JS_FROM = /(?:import|export)\b[^;'"]*?\bfrom\s*['"]([^'"]+)['"]/g
+const JS_BARE = /\bimport\s*['"]([^'"]+)['"]/g
+const JS_DYNAMIC = /\b(?:import|require)\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+// `@import '…'` / `@import "…"` / `@import url(…)` in CSS.
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?['"]([^'"]+)['"]/g
+
+function specifiers(source: string, isCss: boolean): string[] {
+  const out: string[] = []
+  const collect = (re: RegExp) => {
+    re.lastIndex = 0
+    for (let m = re.exec(source); m; m = re.exec(source)) out.push(m[1])
+  }
+  if (isCss) {
+    collect(CSS_IMPORT)
+  } else {
+    collect(JS_FROM)
+    collect(JS_BARE)
+    collect(JS_DYNAMIC)
+  }
+  return out
+}
+
+function* candidates(base: string): Generator<string> {
+  yield base
+  for (const ext of RESOLVE_EXTS) yield base + ext
+  for (const ext of RESOLVE_EXTS) yield join(base, `index${ext}`)
+}
+
+/** Resolve a relative specifier to an absolute file path, or null. Bare
+ *  specifiers (not starting with `.` or `/`) are not traced and return null. */
+async function resolveSpecifier(
+  fromFile: string,
+  spec: string,
+): Promise<string | null> {
+  if (!spec.startsWith('.') && !spec.startsWith('/')) return null
+  const base = isAbsolute(spec) ? spec : resolve(dirname(fromFile), spec)
+  for (const cand of candidates(base)) {
+    if (await Bun.file(cand).exists()) return cand
+  }
+  return null
+}
+
+/**
+ * The transitive relative-import closure of one or more entry files, as a set
+ * of absolute paths that includes the entries themselves. Files that can't be
+ * read are skipped (an entry pointing at a deleted file contributes only
+ * itself).
+ */
+export async function importClosure(entries: string[]): Promise<Set<string>> {
+  const seen = new Set<string>()
+  const queue = entries.map((e) => resolve(e))
+  while (queue.length) {
+    const file = queue.pop()
+    if (!file || seen.has(file)) continue
+    seen.add(file)
+    let source: string
+    try {
+      source = await Bun.file(file).text()
+    } catch {
+      continue
+    }
+    for (const spec of specifiers(source, file.endsWith('.css'))) {
+      const resolved = await resolveSpecifier(file, spec)
+      if (resolved && !seen.has(resolved)) queue.push(resolved)
+    }
+  }
+  return seen
+}
+
+/** Each component's import closure, keyed by component id. */
+export async function componentClosures(
+  components: { id: string; caseFile: string }[],
+): Promise<Map<string, Set<string>>> {
+  const map = new Map<string, Set<string>>()
+  for (const c of components) map.set(c.id, await importClosure([c.caseFile]))
+  return map
+}
+
+/**
+ * The subset of `components` affected by `changedFiles` — i.e. those whose case
+ * file's import closure contains at least one changed file. `changedFiles` and
+ * each `caseFile` are absolute paths.
+ *
+ * Note: this attributes a changed file to a component only when that file is in
+ * the component's *import closure*. A changed file that no closure claims (e.g.
+ * globally-inlined CSS, the render pipeline) is invisible here — the caller is
+ * responsible for treating such an unattributed render-input as affecting every
+ * component. See `componentClosures` for building the closures once to make that
+ * coverage check.
+ */
+export async function affectedComponents(
+  components: { id: string; caseFile: string }[],
+  changedFiles: Iterable<string>,
+): Promise<Set<string>> {
+  const changed = new Set<string>()
+  for (const f of changedFiles) changed.add(resolve(f))
+  const closures = await componentClosures(components)
+  const affected = new Set<string>()
+  for (const [id, files] of closures) {
+    for (const f of files) {
+      if (changed.has(f)) {
+        affected.add(id)
+        break
+      }
+    }
+  }
+  return affected
+}

package/src/core/catalog.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from 'bun:test'
+import type { CaseModule } from '../index'
+import { defineCases, defineFlow, flowStep, tweak } from '../index'
+import { buildCatalog, findCase, slugify } from './catalog'
+
+describe('slugify', () => {
+  test('lowercases and kebabs whitespace', () => {
+    expect(slugify('Sign In Form')).toBe('sign-in-form')
+  })
+
+  test('collapses runs of non-alphanumerics into a single dash', () => {
+    expect(slugify('Hello   World!!!')).toBe('hello-world')
+  })
+
+  test('strips leading and trailing separators', () => {
+    expect(slugify('  --Button--  ')).toBe('button')
+  })
+
+  test('keeps an existing hyphen inside a name', () => {
+    expect(slugify('Sign-in')).toBe('sign-in')
+  })
+
+  test('keeps digits', () => {
+    expect(slugify('H1 Heading 2')).toBe('h1-heading-2')
+  })
+
+  test('treats non-ascii letters as separators', () => {
+    expect(slugify('Café Crème')).toBe('caf-cr-me')
+  })
+
+  test('slugs all-separator or empty input to an empty string', () => {
+    expect(slugify('   ')).toBe('')
+    expect(slugify('—')).toBe('')
+    expect(slugify('')).toBe('')
+  })
+})
+
+describe('buildCatalog', () => {
+  test('slugifies component and case ids while preserving display names', () => {
+    const cat = buildCatalog([
+      defineCases('Icon Button', { 'With Label': () => null }),
+    ])
+    expect(cat).toHaveLength(1)
+    expect(cat[0].id).toBe('icon-button')
+    expect(cat[0].name).toBe('Icon Button')
+    expect(cat[0].cases[0].id).toBe('with-label')
+    expect(cat[0].cases[0].name).toBe('With Label')
+  })
+
+  test('a simple (function) case carries null tweaks and no transitions', () => {
+    const cat = buildCatalog([defineCases('Button', { Default: () => null })])
+    expect(cat[0].cases[0].tweaks).toBeNull()
+    expect(cat[0].cases[0].transitions).toEqual([])
+  })
+
+  test('a tweaked case exposes its declared tweak schema', () => {
+    const tweaks = { label: tweak.text('Save') }
+    const cat = buildCatalog([
+      defineCases('Button', { Custom: { tweaks, render: () => null } }),
+    ])
+    expect(cat[0].cases[0].tweaks).toEqual(tweaks)
+  })
+
+  test('orders components by hierarchy level, then by name', () => {
+    const cat = buildCatalog([
+      defineCases('Zeta', { D: () => null }, { level: 'organism' }),
+      defineCases('Alpha', { D: () => null }, { level: 'atom' }),
+      defineCases('Beta', { D: () => null }, { level: 'atom' }),
+    ])
+    expect(cat.map((c) => c.name)).toEqual(['Alpha', 'Beta', 'Zeta'])
+  })
+
+  test('places unclassified (level-less) components last', () => {
+    const cat = buildCatalog([
+      defineCases('NoLevel', { D: () => null }),
+      defineCases('Page', { D: () => null }, { level: 'page' }),
+      defineCases('Atom', { D: () => null }, { level: 'atom' }),
+    ])
+    expect(cat.map((c) => c.name)).toEqual(['Atom', 'Page', 'NoLevel'])
+  })
+
+  test('preserves case insertion order within a component', () => {
+    const cat = buildCatalog([
+      defineCases('Button', {
+        Third: () => null,
+        First: () => null,
+        Second: () => null,
+      }),
+    ])
+    expect(cat[0].cases.map((c) => c.name)).toEqual([
+      'Third',
+      'First',
+      'Second',
+    ])
+  })
+
+  test('records a flow step’s outgoing transitions as slugified target ids', () => {
+    const cat = buildCatalog([
+      defineFlow('Sign In', {
+        steps: {
+          'Request Link': flowStep({
+            transitions: ['Check Email'],
+            render: () => null,
+          }),
+          'Check Email': flowStep({ render: () => null }),
+        },
+      }),
+    ])
+    expect(cat[0].isFlow).toBe(true)
+    expect(cat[0].level).toBe('flow')
+    expect(cat[0].cases[0].transitions).toEqual(['check-email'])
+    expect(cat[0].cases[1].transitions).toEqual([])
+  })
+
+  test('sorts flows after every classified level (flow is the last level)', () => {
+    const cat = buildCatalog([
+      defineFlow('Onboard', { steps: { A: flowStep({ render: () => null }) } }),
+      defineCases('Page', { D: () => null }, { level: 'page' }),
+    ])
+    expect(cat.map((c) => c.name)).toEqual(['Page', 'Onboard'])
+  })
+})
+
+describe('findCase', () => {
+  const modules: CaseModule[] = [
+    defineCases('Icon Button', { 'With Label': () => null }),
+    defineFlow('Sign In', {
+      steps: { 'Request Link': flowStep({ render: () => null }) },
+    }),
+  ]
+
+  test('resolves a component+case slug to original names and the case', () => {
+    const hit = findCase(modules, 'icon-button', 'with-label')
+    expect(hit).not.toBeNull()
+    expect(hit?.module.component).toBe('Icon Button')
+    expect(hit?.caseName).toBe('With Label')
+    expect(typeof hit?.case).toBe('function')
+  })
+
+  test('resolves a flow step by its slug', () => {
+    const hit = findCase(modules, 'sign-in', 'request-link')
+    expect(hit?.caseName).toBe('Request Link')
+  })
+
+  test('returns null for an unknown component', () => {
+    expect(findCase(modules, 'nope', 'with-label')).toBeNull()
+  })
+
+  test('returns null for an unknown case within a known component', () => {
+    expect(findCase(modules, 'icon-button', 'nope')).toBeNull()
+  })
+})

package/src/core/catalog.ts

@@ -0,0 +1,92 @@
+import type {
+  Case,
+  CaseModule,
+  FlowStep,
+  HierarchyLevel,
+  TweakSchema,
+} from '../index'
+import { HIERARCHY_LEVELS } from '../index'
+
+/**
+ * Pure catalog model shared by the server (to build the manifest) and the
+ * browser (to resolve a slug back to a case). No node/DOM-specific imports.
+ */
+
+export interface CatalogCase {
+  id: string
+  name: string
+  /** Declared tweak schema, or null when the case takes no tweaks. */
+  tweaks: TweakSchema | null
+  /** Slugified ids of steps this step can transition to (flows only; else []). */
+  transitions: string[]
+}
+
+export interface CatalogComponent {
+  id: string
+  name: string
+  level: HierarchyLevel | null
+  isFlow: boolean
+  cases: CatalogCase[]
+}
+
+/** Kebab-case a display name into a stable, URL-safe slug. */
+export function slugify(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function caseTweaks(c: Case | FlowStep): TweakSchema | null {
+  return typeof c === 'function' ? null : (c.tweaks ?? null)
+}
+
+/** Outgoing transitions of a flow step, as slugified target ids. */
+function caseTransitions(c: Case | FlowStep): string[] {
+  if (typeof c === 'function' || !('transitions' in c) || !c.transitions) {
+    return []
+  }
+  return c.transitions.map(slugify)
+}
+
+/** Build the ordered catalog from discovered case modules. */
+export function buildCatalog(modules: CaseModule[]): CatalogComponent[] {
+  const components = modules.map((mod) => ({
+    id: slugify(mod.component),
+    name: mod.component,
+    level: mod.level ?? null,
+    isFlow: mod.isFlow,
+    cases: Object.entries(mod.cases).map(([name, c]) => ({
+      id: slugify(name),
+      name,
+      tweaks: caseTweaks(c),
+      transitions: caseTransitions(c),
+    })),
+  }))
+  // Stable sort: by hierarchy level (atoms first, unclassified last), then name.
+  return components.sort((a, b) => {
+    const la = a.level
+      ? HIERARCHY_LEVELS.indexOf(a.level)
+      : HIERARCHY_LEVELS.length
+    const lb = b.level
+      ? HIERARCHY_LEVELS.indexOf(b.level)
+      : HIERARCHY_LEVELS.length
+    return la - lb || a.name.localeCompare(b.name)
+  })
+}
+
+/** Resolve a component+case slug pair back to its module and renderable case. */
+export function findCase(
+  modules: CaseModule[],
+  componentId: string,
+  caseId: string,
+): { module: CaseModule; caseName: string; case: Case | FlowStep } | null {
+  const mod = modules.find((m) => slugify(m.component) === componentId)
+  if (!mod) return null
+  const entry = Object.entries(mod.cases).find(
+    ([name]) => slugify(name) === caseId,
+  )
+  if (!entry) return null
+  return { module: mod, caseName: entry[0], case: entry[1] }
+}

package/src/core/discovery.test.ts

@@ -0,0 +1,184 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+import type { DisplayCaseConfig } from '../index'
+import { makeTempDir, writeFiles } from '../testing/test-helpers'
+import {
+  baselineDir,
+  cacheDir,
+  codegenPrimerEntry,
+  codegenRenderEntry,
+  discoverCaseFiles,
+  loadModules,
+  resolveConfig,
+} from './discovery'
+
+const dirs: string[] = []
+const setup = async (files: Record<string, string>) => {
+  const dir = await makeTempDir()
+  dirs.push(dir)
+  await writeFiles(dir, files)
+  return dir
+}
+
+afterEach(async () => {
+  while (dirs.length)
+    await rm(dirs.pop() as string, { recursive: true, force: true })
+})
+
+const cfg = (over: Partial<DisplayCaseConfig> = {}): DisplayCaseConfig => ({
+  title: 'T',
+  roots: ['**/*.case.tsx'],
+  ...over,
+})
+
+describe('resolveConfig', () => {
+  test('imports the default-exported config and returns its path', async () => {
+    const dir = await setup({
+      'display-case.config.ts': `export default { title: 'T', roots: ['x'] }\n`,
+    })
+    const { config, configPath } = await resolveConfig(dir)
+    expect(config.title).toBe('T')
+    expect(configPath.endsWith('display-case.config.ts')).toBe(true)
+  })
+
+  test('throws when no config file is present', async () => {
+    const dir = await setup({})
+    expect(resolveConfig(dir)).rejects.toThrow(/No Display Case config/)
+  })
+
+  test('throws when the config file has no default export', async () => {
+    const dir = await setup({
+      'display-case.config.ts': `export const notDefault = { title: 'T', roots: [] }\n`,
+    })
+    expect(resolveConfig(dir)).rejects.toThrow(/default-export/)
+  })
+})
+
+describe('discoverCaseFiles', () => {
+  test('resolves globs to sorted absolute paths', async () => {
+    const dir = await setup({
+      'a/Beta.case.tsx': 'export default {}\n',
+      'a/Alpha.case.tsx': 'export default {}\n',
+      'b/Gamma.case.tsx': 'export default {}\n',
+    })
+    const files = await discoverCaseFiles(dir, cfg())
+    expect(files.every(isAbsolute)).toBe(true)
+    expect(files.map((f) => f.slice(dir.length + 1))).toEqual([
+      'a/Alpha.case.tsx',
+      'a/Beta.case.tsx',
+      'b/Gamma.case.tsx',
+    ])
+  })
+
+  test('skips node_modules and dedups across overlapping globs', async () => {
+    const dir = await setup({
+      'Button.case.tsx': 'export default {}\n',
+      'node_modules/pkg/Ignored.case.tsx': 'export default {}\n',
+    })
+    const files = await discoverCaseFiles(
+      dir,
+      cfg({ roots: ['**/*.case.tsx', '**/*.case.tsx'] }),
+    )
+    expect(files.map((f) => f.slice(dir.length + 1))).toEqual([
+      'Button.case.tsx',
+    ])
+  })
+})
+
+describe('loadModules', () => {
+  test('imports a valid case module', async () => {
+    const dir = await setup({
+      'Button.case.tsx': `export default { component: 'Button', cases: {}, isFlow: false }\n`,
+    })
+    const file = join(dir, 'Button.case.tsx')
+    const { modules, errors } = await loadModules([file])
+    expect(errors).toEqual([])
+    expect(modules).toHaveLength(1)
+    expect(modules[0].module.component).toBe('Button')
+    expect(modules[0].file).toBe(file)
+  })
+
+  test('records a file with no default export as an error', async () => {
+    const dir = await setup({ 'Bad.case.tsx': `export const nope = 1\n` })
+    const file = join(dir, 'Bad.case.tsx')
+    const { modules, errors } = await loadModules([file])
+    expect(modules).toEqual([])
+    expect(errors).toHaveLength(1)
+    expect(errors[0].file).toBe(file)
+    expect(errors[0].error).toMatch(/no valid default export/)
+  })
+
+  test('records a default export whose component is not a string', async () => {
+    const dir = await setup({
+      'Bad.case.tsx': `export default { cases: {}, isFlow: false }\n`,
+    })
+    const { modules, errors } = await loadModules([join(dir, 'Bad.case.tsx')])
+    expect(modules).toEqual([])
+    expect(errors).toHaveLength(1)
+  })
+
+  test('captures a throwing import and still loads the rest', async () => {
+    const dir = await setup({
+      'Throws.case.tsx': `throw new Error('boom')\n`,
+      'Good.case.tsx': `export default { component: 'Good', cases: {}, isFlow: false }\n`,
+    })
+    const { modules, errors } = await loadModules([
+      join(dir, 'Throws.case.tsx'),
+      join(dir, 'Good.case.tsx'),
+    ])
+    expect(modules.map((m) => m.module.component)).toEqual(['Good'])
+    expect(errors).toHaveLength(1)
+    expect(errors[0].error).toMatch(/boom/)
+  })
+})
+
+describe('cacheDir / baselineDir', () => {
+  test('cacheDir is the .display-case dir under the package', () => {
+    expect(cacheDir('/pkg')).toBe('/pkg/.display-case')
+  })
+
+  test('baselineDir defaults to the cache baselines dir', () => {
+    expect(baselineDir('/pkg', cfg())).toBe('/pkg/.display-case/baselines')
+  })
+
+  test('baselineDir joins a relative override to the package', () => {
+    expect(baselineDir('/pkg', cfg({ baselineDir: 'snaps' }))).toBe(
+      '/pkg/snaps',
+    )
+  })
+
+  test('baselineDir honors an absolute override verbatim', () => {
+    expect(baselineDir('/pkg', cfg({ baselineDir: '/abs/snaps' }))).toBe(
+      '/abs/snaps',
+    )
+  })
+})
+
+describe('codegen entries', () => {
+  test('codegenRenderEntry imports every case, tags its source path, and mounts', async () => {
+    const dir = await setup({})
+    const files = [join(dir, 'a/Button.case.tsx'), join(dir, 'b/Card.case.tsx')]
+    const configPath = join(dir, 'display-case.config.ts')
+    const entry = await codegenRenderEntry(dir, files, configPath)
+    expect(entry).toBe(join(cacheDir(dir), 'render-entry.tsx'))
+    const src = await Bun.file(entry).text()
+    expect(src).toContain('AUTO-GENERATED')
+    expect(src).toContain('import m0 from')
+    expect(src).toContain('import m1 from')
+    expect(src).toContain('mountRender([')
+    expect(src).toContain(`sourcePath: ${JSON.stringify('a/Button.case.tsx')}`)
+    expect(src).toContain(`sourcePath: ${JSON.stringify('b/Card.case.tsx')}`)
+  })
+
+  test('codegenPrimerEntry imports the MDX document and mounts the primer', async () => {
+    const dir = await setup({})
+    const entry = await codegenPrimerEntry(dir, 'docs/primer.mdx')
+    expect(entry).toBe(join(cacheDir(dir), 'primer-entry.tsx'))
+    const src = await Bun.file(entry).text()
+    expect(src).toContain('AUTO-GENERATED')
+    expect(src).toContain('import MDXContent from')
+    expect(src).toContain('primer.mdx')
+    expect(src).toContain('mountPrimer(MDXContent)')
+  })
+})