@awarebydefault/display-case 1.0.0

package/src/core/mdx-lite/mdx-lite.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { ComponentType } from 'react'
+import {
+  extractBoundNames,
+  mdxToTsx,
+  scanBraces,
+  scanElement,
+  scanString,
+  segmentMdx,
+} from './index'
+
+const FIXTURES = join(import.meta.dir, '__fixtures__')
+
+/** Assert the emitted TSX is syntactically valid by transpiling it with Bun's
+ *  built-in transpiler (no extra deps). Throws on a syntax error. */
+function assertValidTsx(code: string): void {
+  const t = new Bun.Transpiler({ loader: 'tsx' })
+  t.transformSync(code)
+}
+
+// ---------------------------------------------------------------------------
+// Low-level scanners
+// ---------------------------------------------------------------------------
+
+describe('scanString', () => {
+  test('plain strings and escapes', () => {
+    expect(scanString(`"ab\\"c"x`, 0)).toBe(7)
+    expect(scanString(`'a'`, 0)).toBe(3)
+  })
+  test('template with nested interpolation containing braces', () => {
+    // Build the literal `a${ {x:1} }b` without a raw ${ token in source.
+    const s = `\`a${'$'}{ {x:1} }b\``
+    expect(scanString(s, 0)).toBe(s.length)
+  })
+})
+
+describe('scanBraces', () => {
+  test('nested object expression', () => {
+    const s = '{{ a: 1, b: { c: 2 } }}rest'
+    expect(s.slice(0, scanBraces(s, 0))).toBe('{{ a: 1, b: { c: 2 } }}')
+  })
+  test('braces inside strings are ignored', () => {
+    const s = `{ "a}b" + '}' }tail`
+    expect(s.slice(0, scanBraces(s, 0))).toBe(`{ "a}b" + '}' }`)
+  })
+  test('block and line comments containing braces', () => {
+    const s = '{ /* } */ x } '
+    expect(s.slice(0, scanBraces(s, 0))).toBe('{ /* } */ x }')
+  })
+})
+
+describe('scanElement', () => {
+  const end = (s: string) => {
+    const tags: string[] = []
+    return { i: scanElement(s, 0, tags), tags }
+  }
+  test('self-closing element', () => {
+    const r = end('<Foo />after')
+    expect('<Foo />after'.slice(0, r.i)).toBe('<Foo />')
+    expect(r.tags).toEqual(['Foo'])
+  })
+  test('attributes with > and < inside strings', () => {
+    const s = '<Foo title="a > b" data-x="<3">hi</Foo>!'
+    expect(s.slice(0, end(s).i)).toBe('<Foo title="a > b" data-x="<3">hi</Foo>')
+  })
+  test('object expression prop with nested braces', () => {
+    const s = '<W style={{ fontSize: "1rem", x: { y: 2 } }}>t</W>z'
+    expect(s.slice(0, end(s).i)).toBe(
+      '<W style={{ fontSize: "1rem", x: { y: 2 } }}>t</W>',
+    )
+  })
+  test('nested same-name elements track depth', () => {
+    const s = '<Box><Box><Box/></Box></Box>tail'
+    expect(s.slice(0, end(s).i)).toBe('<Box><Box><Box/></Box></Box>')
+  })
+  test('fragment shorthand', () => {
+    const s = '<><A/><B/></>x'
+    const r = end(s)
+    expect(s.slice(0, r.i)).toBe('<><A/><B/></>')
+    expect(r.tags).toEqual(['A', 'B'])
+  })
+  test('JSX expression comment containing delimiters', () => {
+    const s = '<A>{/* < } > */}done</A>!'
+    expect(s.slice(0, end(s).i)).toBe('<A>{/* < } > */}done</A>')
+  })
+  test('spread attribute', () => {
+    const s = '<A {...props} b="1"/>z'
+    expect(s.slice(0, end(s).i)).toBe('<A {...props} b="1"/>')
+  })
+  test('multi-line element with blank lines in the body', () => {
+    const s = '<Box>\n\n  <A/>\n\n  <B/>\n\n</Box>\ntrailing'
+    const r = end(s)
+    expect(s.slice(0, r.i)).toBe('<Box>\n\n  <A/>\n\n  <B/>\n\n</Box>')
+    expect(r.tags).toEqual(['Box', 'A', 'B'])
+  })
+})
+
+describe('extractBoundNames', () => {
+  test('default, named, aliased, namespace, and export bindings', () => {
+    const code = [
+      "import Def from './a'",
+      "import { x, y as z } from './b'",
+      "import Mix, { q } from './c'",
+      "import * as NS from './d'",
+      'export const Local = 1',
+    ].join('\n')
+    const names = extractBoundNames(code)
+    expect([...names].sort()).toEqual(
+      ['Def', 'Local', 'Mix', 'NS', 'q', 'x', 'z'].sort(),
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Segmentation
+// ---------------------------------------------------------------------------
+
+describe('segmentMdx', () => {
+  test('classifies imports, prose, and block JSX', () => {
+    const blocks = segmentMdx(
+      [
+        "import { Button } from './c'",
+        '',
+        '# Title',
+        '',
+        'Some **bold** prose.',
+        '',
+        '<Display title="x"><Button/></Display>',
+        '',
+        'After.',
+      ].join('\n'),
+    )
+    expect(blocks.map((b) => b.kind)).toEqual([
+      'imports',
+      'markdown',
+      'jsx',
+      'markdown',
+    ])
+    const jsx = blocks[2] as Extract<(typeof blocks)[number], { kind: 'jsx' }>
+    expect(jsx.tags).toEqual(['Display', 'Button'])
+  })
+
+  test('fenced code containing <Tag> stays markdown, not JSX', () => {
+    const blocks = segmentMdx(
+      ['```mdx', '<Display title="x">', '  <Foo/>', '</Display>', '```'].join(
+        '\n',
+      ),
+    )
+    expect(blocks).toHaveLength(1)
+    expect(blocks[0]?.kind).toBe('markdown')
+  })
+
+  test('multi-line named import is one imports block', () => {
+    const blocks = segmentMdx(
+      ['import {', '  A,', '  B,', '} from "./x"', '', 'prose'].join('\n'),
+    )
+    expect(blocks[0]?.kind).toBe('imports')
+    expect((blocks[0] as { code: string }).code).toContain('B,')
+    expect(blocks[1]?.kind).toBe('markdown')
+  })
+
+  test('multi-line JSX block with blank lines inside is one jsx block', () => {
+    const blocks = segmentMdx(
+      [
+        '<Display title="t">',
+        '',
+        '  <A/>',
+        '',
+        '  <B/>',
+        '',
+        '</Display>',
+      ].join('\n'),
+    )
+    expect(blocks).toHaveLength(1)
+    expect(blocks[0]?.kind).toBe('jsx')
+  })
+
+  test('prose line starting with lowercase < or autolink is not JSX', () => {
+    const blocks = segmentMdx('see <https://example.com> and a < b here')
+    expect(blocks).toHaveLength(1)
+    expect(blocks[0]?.kind).toBe('markdown')
+  })
+
+  test('degenerate inputs', () => {
+    expect(segmentMdx('')).toEqual([])
+    expect(segmentMdx('   \n\n  ')).toEqual([])
+    expect(segmentMdx("import x from './x'").map((b) => b.kind)).toEqual([
+      'imports',
+    ])
+    expect(segmentMdx('<A/>').map((b) => b.kind)).toEqual(['jsx'])
+    expect(segmentMdx('just prose').map((b) => b.kind)).toEqual(['markdown'])
+  })
+
+  test('CRLF newlines are normalized', () => {
+    const blocks = segmentMdx('# T\r\n\r\nbody')
+    expect(blocks).toHaveLength(1)
+    expect((blocks[0] as { text: string }).text).toBe('# T\n\nbody')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Compilation to TSX
+// ---------------------------------------------------------------------------
+
+describe('mdxToTsx', () => {
+  test('emits a valid default-export component', () => {
+    const code = mdxToTsx(
+      [
+        "import { Button } from './c'",
+        '',
+        '# Hi',
+        '',
+        '<Display><Button/></Display>',
+      ].join('\n'),
+    )
+    assertValidTsx(code)
+    expect(code).toContain('export default function MDXContent')
+    expect(code).toContain("import { Button } from './c'")
+    // Display is not imported → resolved from the components prop.
+    expect(code).toContain('const { Display } = __components')
+    // Button is imported → NOT destructured from components.
+    expect(code).not.toContain('Button } = __components')
+  })
+
+  test('markdown payload is embedded as a JSON-safe string', () => {
+    // Prose containing backticks and a dollar-brace must not corrupt the TSX.
+    const code = mdxToTsx(
+      `a \`code\` and ${'$'}{not interpolated} and a "quote"`,
+    )
+    assertValidTsx(code)
+    expect(code).toContain('<__Md options={__mdOpts}>')
+  })
+
+  test('no external components → no empty destructure', () => {
+    const code = mdxToTsx("import { A } from './a'\n\n<A/>")
+    assertValidTsx(code)
+    expect(code).not.toContain('= __components\n  const { h1')
+    expect(code).not.toContain('{  } = __components')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// End-to-end SSR round-trips
+// ---------------------------------------------------------------------------
+
+describe('SSR round-trip (synthetic)', () => {
+  test('imports resolve, prose renders, JSX specimens render', async () => {
+    const src = [
+      "import { Box } from './box-stub'",
+      '',
+      '# Heading',
+      '',
+      'Some **prose** here.',
+      '',
+      '<Display title="Demo"><Box>inner</Box></Display>',
+    ].join('\n')
+    const code = mdxToTsx(src, { markdownSpecifier: 'markdown-to-jsx' })
+    const tmp = join(FIXTURES, `__rt_${Date.now()}.tsx`)
+    await Bun.write(tmp, code)
+    try {
+      const { renderToStaticMarkup } = await import('react-dom/server')
+      const { createElement } = await import('react')
+      const mod = (await import(tmp)) as {
+        default: ComponentType<{ components?: unknown }>
+      }
+      const Display = ({
+        title,
+        children,
+      }: {
+        title?: string
+        children?: unknown
+      }) =>
+        createElement(
+          'section',
+          { 'data-display': '', title },
+          children as never,
+        )
+      const html = renderToStaticMarkup(
+        createElement(mod.default, { components: { Display } }) as never,
+      )
+      expect(html).toContain('<strong>prose</strong>') // prose via markdown-to-jsx
+      expect(html).toContain('data-display') // Display resolved from components
+      expect(html).toContain('data-box') // imported Box rendered
+      expect(html).toContain('inner')
+    } finally {
+      await rm(tmp, { force: true })
+    }
+  })
+})
+
+describe('SSR round-trip (real primer.mdx)', () => {
+  const Primer = join(
+    import.meta.dir,
+    '..',
+    '..',
+    'ui',
+    'design-system',
+    'primer.mdx',
+  )
+
+  test('the real primer segments, counts Display specimens, and emits valid TSX', async () => {
+    const source = await Bun.file(Primer).text()
+    const blocks = segmentMdx(source)
+    const displays = blocks
+      .filter((b) => b.kind === 'jsx')
+      .filter((b) => (b as { tags: string[] }).tags[0] === 'Display').length
+    expect(displays).toBeGreaterThanOrEqual(15)
+    // prose exists
+    expect(blocks.some((b) => b.kind === 'markdown')).toBe(true)
+    assertValidTsx(mdxToTsx(source))
+  })
+
+  test('the real primer renders to HTML under SSR with a stubbed Display', async () => {
+    const source = await Bun.file(Primer).text()
+    const code = mdxToTsx(source, { markdownSpecifier: 'markdown-to-jsx' })
+    // Write next to primer.mdx so its relative imports (./components, etc.) resolve.
+    const tmp = join(
+      import.meta.dir,
+      '..',
+      '..',
+      'ui',
+      'design-system',
+      `__rt_primer_${Date.now()}.tsx`,
+    )
+    await Bun.write(tmp, code)
+    try {
+      const { renderToStaticMarkup } = await import('react-dom/server')
+      const { createElement } = await import('react')
+      const mod = (await import(tmp)) as {
+        default: ComponentType<{ components?: unknown }>
+      }
+      const Display = ({ children }: { children?: unknown }) =>
+        createElement('section', { 'data-display': '' }, children as never)
+      const html = renderToStaticMarkup(
+        createElement(mod.default, { components: { Display } }) as never,
+      )
+      expect(html).toContain('data-display')
+      expect(html).toContain('Design System') // a heading from the prose
+    } finally {
+      await rm(tmp, { force: true })
+    }
+  })
+})

package/src/core/mdx-plugin.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { makeTempDir } from '../testing/test-helpers'
+import { mdxPlugin } from './mdx-plugin'
+
+type OnLoadArgs = { path: string }
+type OnLoadResult = { contents: string; loader: string }
+type OnLoadCb = (args: OnLoadArgs) => Promise<OnLoadResult>
+
+/**
+ * Drive the plugin without a real Bun build: capture the `onLoad` handler it
+ * registers, then invoke it against a temp `.mdx` file and inspect the compiled
+ * output.
+ */
+function captureOnLoad(): {
+  filter: RegExp
+  run: OnLoadCb
+} {
+  const calls: Array<{ filter: RegExp; cb: OnLoadCb }> = []
+  const build = {
+    onLoad: (opts: { filter: RegExp }, cb: OnLoadCb) =>
+      calls.push({ filter: opts.filter, cb }),
+  }
+  const plugin = mdxPlugin()
+  plugin.setup(build as unknown as Parameters<typeof plugin.setup>[0])
+  if (!calls[0]) throw new Error('plugin registered no onLoad handler')
+  return { filter: calls[0].filter, run: calls[0].cb }
+}
+
+describe('mdxPlugin', () => {
+  test('registers an onLoad handler that matches .mdx files only', () => {
+    const { filter } = captureOnLoad()
+    expect(filter.test('doc.mdx')).toBe(true)
+    expect(filter.test('doc.tsx')).toBe(false)
+  })
+
+  test('compiles an .mdx document to a TSX module on load', async () => {
+    const { run } = captureOnLoad()
+    const dir = await makeTempDir()
+    try {
+      const file = join(dir, 'doc.mdx')
+      await Bun.write(
+        file,
+        "import { Button } from './c'\n\n# Title\n\nSome **bold** text.\n\n<Display><Button/></Display>\n",
+      )
+      const result = await run({ path: file })
+      // mdx-lite emits TSX so Bun handles imports + JSX expression props.
+      expect(result.loader).toBe('tsx')
+      expect(result.contents).toContain('export default function MDXContent')
+      // Author imports pass through; <Display> resolves from the components prop.
+      expect(result.contents).toContain("import { Button } from './c'")
+      expect(result.contents).toContain('const { Display } = __components')
+      // Emitted TSX is syntactically valid.
+      new Bun.Transpiler({ loader: 'tsx' }).transformSync(result.contents)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/core/mdx-plugin.ts

@@ -0,0 +1,30 @@
+import type { BunPlugin } from 'bun'
+import { mdxToTsx } from './mdx-lite'
+
+/**
+ * Bun bundler plugin that compiles `.mdx` to TSX on load, so the Primer entry can
+ * `import` an authored `.mdx` document and the components it pulls in.
+ *
+ * Compilation is done by the in-repo `mdx-lite` compiler (no `@mdx-js/mdx`): it
+ * segments the document into imports / prose / block-level JSX and emits a `.tsx`
+ * module. The author's `import`s and JSX expression props pass through verbatim
+ * and are handled by Bun's own TSX toolchain; prose renders via `markdown-to-jsx`
+ * (the same renderer the `.placard.md` DocPanel uses, so the two reading surfaces
+ * stay consistent). The compiled default export is `MDXContent({ components })`:
+ * capitalized JSX a doc doesn't import (notably `<Display>`) resolves from the
+ * `components` prop passed at render time (see `primer-mount`).
+ *
+ * The `tsx` loader hands the emitted source back to Bun, which strips types and
+ * compiles JSX with the project's automatic React runtime.
+ */
+export function mdxPlugin(): BunPlugin {
+  return {
+    name: 'display-case-mdx',
+    setup(build) {
+      build.onLoad({ filter: /\.mdx$/ }, async (args) => {
+        const source = await Bun.file(args.path).text()
+        return { contents: mdxToTsx(source), loader: 'tsx' }
+      })
+    },
+  }
+}

package/src/flow-step.test-d.ts

@@ -0,0 +1,39 @@
+/**
+ * Type-level test for `flowStep` inference. Compiled by `tsc` (the `lint:types`
+ * check) but never executed — each `@ts-expect-error` asserts a compile error,
+ * and a `const x: T =` asserts the inferred type. A regression of the inference
+ * fails the typecheck.
+ */
+import { flowStep, tweak } from './index'
+
+// A tweaked step: `values` is typed from its own tweaks.
+flowStep({
+  tweaks: { error: tweak.boolean(false), code: tweak.text('') },
+  render: ({ values }) => {
+    const _error: boolean = values.error
+    const _code: string = values.code
+    void _error
+    void _code
+    // @ts-expect-error — `nope` is not a declared tweak of this step
+    void values.nope
+    return null
+  },
+})
+
+// A step with no tweaks: `values` is empty; render need not read it.
+flowStep({
+  transitions: ['Done'],
+  render: ({ goto }) => {
+    goto('Done')
+    return null
+  },
+})
+
+// A no-tweaks step that wrongly reads a tweak value.
+flowStep({
+  render: ({ values }) => {
+    // @ts-expect-error — this step declares no tweaks
+    void values.error
+    return null
+  },
+})

package/src/index.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  defineCases,
+  defineConfig,
+  defineFlow,
+  flowStep,
+  HIERARCHY_LEVELS,
+  tweak,
+} from './index'
+
+describe('tweak builders', () => {
+  test('text defaults to an empty string and echoes a provided default', () => {
+    expect(tweak.text()).toEqual({ kind: 'text', default: '' })
+    expect(tweak.text('hi')).toEqual({ kind: 'text', default: 'hi' })
+  })
+
+  test('boolean defaults to false', () => {
+    expect(tweak.boolean()).toEqual({ kind: 'boolean', default: false })
+    expect(tweak.boolean(true)).toEqual({ kind: 'boolean', default: true })
+  })
+
+  test('number defaults to zero', () => {
+    expect(tweak.number()).toEqual({ kind: 'number', default: 0 })
+    expect(tweak.number(42)).toEqual({ kind: 'number', default: 42 })
+  })
+
+  test('choice records its options and default', () => {
+    expect(tweak.choice(['sm', 'md', 'lg'], 'md')).toEqual({
+      kind: 'choice',
+      options: ['sm', 'md', 'lg'],
+      default: 'md',
+    })
+  })
+})
+
+describe('defineCases', () => {
+  test('builds a non-flow module from a name and cases', () => {
+    const mod = defineCases('Button', { Default: () => null })
+    expect(mod.component).toBe('Button')
+    expect(mod.isFlow).toBe(false)
+    expect(mod.level).toBeUndefined()
+    expect(mod.area).toBeUndefined()
+    expect(Object.keys(mod.cases)).toEqual(['Default'])
+  })
+
+  test('carries level and area from meta', () => {
+    const mod = defineCases(
+      'Button',
+      { Default: () => null },
+      {
+        level: 'atom',
+        area: 'marketing',
+      },
+    )
+    expect(mod.level).toBe('atom')
+    expect(mod.area).toBe('marketing')
+  })
+})
+
+describe('defineFlow', () => {
+  test('builds a flow module pinned at the flow level', () => {
+    const mod = defineFlow('Sign In', {
+      steps: { Start: flowStep({ render: () => null }) },
+    })
+    expect(mod.component).toBe('Sign In')
+    expect(mod.isFlow).toBe(true)
+    expect(mod.level).toBe('flow')
+    expect(Object.keys(mod.cases)).toEqual(['Start'])
+  })
+
+  test('carries an area tag from config', () => {
+    const mod = defineFlow('Sign In', { steps: {}, area: 'auth' })
+    expect(mod.area).toBe('auth')
+  })
+})
+
+describe('identity helpers', () => {
+  test('flowStep returns its argument unchanged', () => {
+    const step = { render: () => null }
+    expect(flowStep(step)).toBe(step)
+  })
+
+  test('defineConfig returns its argument unchanged', () => {
+    const config = { title: 'X', roots: ['**/*.case.tsx'] }
+    expect(defineConfig(config)).toBe(config)
+  })
+})
+
+describe('HIERARCHY_LEVELS', () => {
+  test('orders the atomic-design levels from atom to flow', () => {
+    expect(HIERARCHY_LEVELS).toEqual([
+      'atom',
+      'molecule',
+      'organism',
+      'template',
+      'page',
+      'flow',
+    ])
+  })
+})