npm - @awarebydefault/display-case - Versions diffs - 1.0.0 - Mend

@awarebydefault/display-case 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (254) hide show

package/src/render/ssr-primer.test.tsx ADDED Viewed

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'bun:test'
+import type { DisplayCaseConfig } from '../index'
+import { makePrimerRenderer } from './ssr-primer'
+const config: DisplayCaseConfig = { title: 'T', roots: [] }
+describe('makePrimerRenderer', () => {
+  test('renders the MDX content to markup', () => {
+    const render = makePrimerRenderer(() => <h1>Primer Heading</h1>, config)
+    const result = render()
+    expect(result.browserOnly).toBe(false)
+    expect(result.html).toContain('Primer Heading')
+    expect(result.error).toBeUndefined()
+  })
+  test('falls the whole primer back to the client when a specimen needs a browser', () => {
+    const render = makePrimerRenderer(() => {
+      throw new Error('specimen touched window')
+    }, config)
+    const result = render()
+    expect(result.browserOnly).toBe(true)
+    expect(result.html).toBe('')
+    expect(result.error).toContain('specimen touched window')
+  })
+})

package/src/render/ssr-primer.tsx ADDED Viewed

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react'
+import { StrictMode } from 'react'
+import type { DisplayCaseConfig } from '../index'
+import { PrimerRoot } from '../ui/primer'
+import { renderWithStyles } from './collect-styles'
+/**
+ * Server-side primer rendering — the sibling of {@link makeCaseRenderer} for
+ * the `/render/primer` document. The codegen'd SSR-primer entry imports the
+ * compiled MDX and binds it here; the server imports that freshly-built bundle
+ * each rebuild (same staleness reasoning as the case renderer). The primer's
+ * prose and its embedded specimens render to markup once — the theme is a
+ * document attribute, not part of the tree, so one render serves both themes.
+ */
+type MDXContent = (props: { components?: unknown }) => ReactNode
+export interface PrimerHtmlResult {
+  html: string
+  /** True when the primer could not be rendered outside a browser (a specimen
+   *  touched a browser-only API under `renderToString`). The whole primer then
+   *  falls back to client rendering — the same isolation a single case gets. */
+  browserOnly: boolean
+  error?: string
+  /** Render-time (CSS-in-JS) styling collected by the configured style engines,
+   *  as `<head>` markup. `''` (or absent) when no engine produced styling. */
+  headStyles?: string
+}
+export function makePrimerRenderer(
+  Content: MDXContent,
+  config: DisplayCaseConfig,
+): () => PrimerHtmlResult {
+  return function renderPrimerToHtml(): PrimerHtmlResult {
+    try {
+      // Apply any configured style engines around the primer tree, exactly as the
+      // case renderer does, so a specimen's render-time CSS-in-JS styling is
+      // delivered before scripting too.
+      const { html, headStyles } = renderWithStyles(
+        <StrictMode>
+          <PrimerRoot content={Content} />
+        </StrictMode>,
+        config.styleEngines,
+      )
+      return { html, browserOnly: false, headStyles }
+    } catch (err) {
+      return {
+        html: '',
+        browserOnly: true,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+}

package/src/render/ssr-render.test.tsx ADDED Viewed

@@ -0,0 +1,142 @@
+import { describe, expect, test } from 'bun:test'
+import { type DisplayCaseConfig, defineCases, type StyleEngine } from '../index'
+import type { CaseTreeState } from './render-node'
+import { makeCaseRenderer } from './ssr-render'
+const NO_CONFIG: DisplayCaseConfig = {} as DisplayCaseConfig
+/** A stub engine emitting a per-render-instance-tagged style tag. */
+function stubEngine(counter: { n: number }): StyleEngine {
+  return () => {
+    const id = ++counter.n
+    return {
+      wrap: (node) => node,
+      collect: () => `<style data-stub="${id}"></style>`,
+    }
+  }
+}
+const state = (over: Partial<CaseTreeState>): CaseTreeState => ({
+  componentId: 'button',
+  caseId: 'default',
+  width: null,
+  tweaks: {},
+  ...over,
+})
+function Boom(): never {
+  throw new Error('needs a browser')
+}
+describe('makeCaseRenderer', () => {
+  test('renders an SSR-able case to inner markup', () => {
+    const render = makeCaseRenderer(
+      [
+        defineCases('Button', {
+          Default: () => <button type="button">Hi</button>,
+        }),
+      ],
+      NO_CONFIG,
+    )
+    const result = render(state({}))
+    expect(result.browserOnly).toBe(false)
+    expect(result.html).toContain('Hi')
+    expect(result.error).toBeUndefined()
+  })
+  test('skips server rendering for a browser-only module without attempting it', () => {
+    const render = makeCaseRenderer(
+      [
+        defineCases(
+          'Canvas',
+          { Default: () => <canvas /> },
+          { browserOnly: true },
+        ),
+      ],
+      NO_CONFIG,
+    )
+    const result = render(state({ componentId: 'canvas' }))
+    expect(result).toEqual({ html: '', browserOnly: true })
+  })
+  test('catches a render that needs a browser and reports it browser-only with the error', () => {
+    const render = makeCaseRenderer(
+      [defineCases('Bad', { Default: () => <Boom /> })],
+      NO_CONFIG,
+    )
+    const result = render(state({ componentId: 'bad' }))
+    expect(result.browserOnly).toBe(true)
+    expect(result.html).toBe('')
+    expect(result.error).toContain('needs a browser')
+  })
+  test('renders the not-found node for an unknown case (not a browser-only fallback)', () => {
+    const render = makeCaseRenderer([], NO_CONFIG)
+    const result = render(state({ componentId: 'ghost', caseId: 'x' }))
+    expect(result.browserOnly).toBe(false)
+    // renderToString interleaves `<!-- -->` markers between text nodes, so match
+    // the stable wrapper + ids rather than the contiguous sentence.
+    expect(result.html).toContain('dc-render-missing')
+    expect(result.html).toContain('No such case:')
+    expect(result.html).toContain('ghost')
+  })
+  test('without a style engine, headStyles is empty (inert when unused)', () => {
+    const render = makeCaseRenderer(
+      [
+        defineCases('Button', {
+          Default: () => <button type="button">Hi</button>,
+        }),
+      ],
+      NO_CONFIG,
+    )
+    expect(render(state({})).headStyles).toBe('')
+  })
+  test('a configured style engine collects head styling for the render', () => {
+    const render = makeCaseRenderer(
+      [
+        defineCases('Button', {
+          Default: () => <button type="button">Hi</button>,
+        }),
+      ],
+      { ...NO_CONFIG, styleEngines: [stubEngine({ n: 0 })] },
+    )
+    const result = render(state({}))
+    expect(result.html).toContain('Hi')
+    expect(result.headStyles).toContain('data-stub=')
+  })
+  test('each render gets its own isolated collector (no cross-case bleed)', () => {
+    const render = makeCaseRenderer(
+      [
+        defineCases('Button', {
+          Default: () => <button type="button">Hi</button>,
+        }),
+        defineCases('Link', { Default: () => <a href="/x">Go</a> }),
+      ],
+      { ...NO_CONFIG, styleEngines: [stubEngine({ n: 0 })] },
+    )
+    const a = render(state({ componentId: 'button' }))
+    const b = render(state({ componentId: 'link' }))
+    // Distinct per-render instance ids ⇒ a fresh store per render, not shared.
+    expect(a.headStyles).toContain('data-stub="1"')
+    expect(b.headStyles).toContain('data-stub="2"')
+  })
+  test('a browser-only case runs no engine and emits no head styling', () => {
+    const render = makeCaseRenderer(
+      [
+        defineCases(
+          'Canvas',
+          { Default: () => <canvas /> },
+          { browserOnly: true },
+        ),
+      ],
+      { ...NO_CONFIG, styleEngines: [stubEngine({ n: 0 })] },
+    )
+    const result = render(state({ componentId: 'canvas' }))
+    expect(result).toEqual({ html: '', browserOnly: true })
+    expect(result.headStyles).toBeUndefined()
+  })
+})

package/src/render/ssr-render.tsx ADDED Viewed

@@ -0,0 +1,63 @@
+import { findCase } from '../core/catalog'
+import type { CaseModule, DisplayCaseConfig } from '../index'
+import { renderWithStyles } from './collect-styles'
+import { type CaseTreeState, caseTree, NOOP_GOTO } from './render-node'
+/**
+ * Server-side case rendering. The codegen'd SSR entry (see
+ * `codegenSsrEntry`) imports every discovered case module plus the consumer
+ * config, hands them here, and exports the resulting `renderCaseToHtml`. The
+ * server imports that freshly-built bundle each rebuild — the bundle inlines the
+ * case source from disk, so its modules are always current, sidestepping the
+ * per-path module cache that forces the manifest into a subprocess.
+ */
+export interface CaseHtmlResult {
+  /** Pre-rendered `#root` inner markup, or `''` when the case is browser-only. */
+  html: string
+  /** True when the case could not be rendered outside a browser (it threw under
+   *  `renderToString`, or no such case exists to even attempt). */
+  browserOnly: boolean
+  /** The throw's message, for the server to log once per browser-only case. */
+  error?: string
+  /** Render-time (CSS-in-JS) styling collected by the configured style engines,
+   *  as `<head>` markup to place after the document's static styles. `''` (or
+   *  absent) when no engine is configured or none produced styling. */
+  headStyles?: string
+}
+export type CaseRenderer = (state: CaseTreeState) => CaseHtmlResult
+export function makeCaseRenderer(
+  modules: CaseModule[],
+  config: DisplayCaseConfig,
+): CaseRenderer {
+  return function renderCaseToHtml(state: CaseTreeState): CaseHtmlResult {
+    // A component declared `browserOnly` opts out of server rendering: skip the
+    // attempt (no throw, no log) and let the client mount it.
+    const found = findCase(modules, state.componentId, state.caseId)
+    if (found?.module.browserOnly) return { html: '', browserOnly: true }
+    try {
+      // Apply any configured style engines around the case tree so render-time
+      // CSS-in-JS styling (emotion/MUI, styled-components…) is collected and
+      // delivered before scripting. No engines ⇒ a plain render, `headStyles`
+      // `''`, document byte-identical to before.
+      const { html, headStyles } = renderWithStyles(
+        caseTree(modules, config, state, NOOP_GOTO),
+        config.styleEngines,
+      )
+      return { html, browserOnly: false, headStyles }
+    } catch (err) {
+      // The case — or a component it renders — needs a browser: it touched a
+      // browser-only API (window, layout measurement, canvas…) under
+      // `renderToString`. Don't fail the document; emit no server markup for
+      // this case and let the client mount it. The server records it so later
+      // requests skip the server attempt and so the author gets one log line.
+      return {
+        html: '',
+        browserOnly: true,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+}

package/src/render/ssr-shell.test.tsx ADDED Viewed

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test'
+import type { Manifest } from '../core/manifest'
+import { renderShellToHtml } from './ssr-shell'
+const manifest: Manifest = {
+  title: 'Showcase',
+  components: [
+    {
+      id: 'button',
+      name: 'Button',
+      level: 'atom',
+      isFlow: false,
+      caseFile: 'src/Button.case.tsx',
+      placardDoc: null,
+      cases: [
+        {
+          id: 'default',
+          name: 'Default',
+          browseUrl: '/c/button/default',
+          renderUrl: '/render/button/default',
+          tweaks: null,
+          transitions: [],
+        },
+      ],
+    },
+  ],
+  primer: false,
+  landing: 'library',
+}
+describe('renderShellToHtml', () => {
+  test('server-renders the browse chrome to markup', () => {
+    const result = renderShellToHtml({
+      manifest,
+      pathname: '/c/button/default',
+      search: '',
+      theme: 'dark',
+      a11y: false,
+    })
+    expect(result.ssr).toBe(true)
+    expect(result.html.length).toBeGreaterThan(0)
+    // The seeded component name reaches the rendered nav.
+    expect(result.html).toContain('Button')
+  })
+  test('renders the primer landing without throwing when one is configured', () => {
+    const result = renderShellToHtml({
+      manifest: { ...manifest, primer: true, landing: 'primer' },
+      pathname: '/',
+      search: '',
+      theme: 'light',
+      a11y: true,
+    })
+    expect(result.ssr).toBe(true)
+    expect(result.html.length).toBeGreaterThan(0)
+  })
+})

package/src/render/ssr-shell.tsx ADDED Viewed

@@ -0,0 +1,54 @@
+import { StrictMode } from 'react'
+import { renderToString } from 'react-dom/server'
+import type { Manifest } from '../core/manifest'
+import { Shell } from '../ui/shell'
+import { parseRoute, type Theme } from '../ui/shell-core'
+import type { ShellSeed } from '../ui/use-shell'
+/**
+ * Server-side render of the browse shell. Unlike the case/primer renderers, the
+ * shell depends only on the manifest *data* and the request route — not on any
+ * consumer case module — so it renders in-process from the in-memory manifest
+ * with no per-rebuild bundle. The same `<Shell seed=…>` the client hydrates is
+ * rendered here, seeded from the request, so the two agree.
+ */
+export interface ShellHtmlResult {
+  /** Pre-rendered `#root` inner markup, or `''` when the shell could not render. */
+  html: string
+  /** Whether `html` is present, so the client adopts instead of mounting fresh. */
+  ssr: boolean
+}
+export function renderShellToHtml(args: {
+  manifest: Manifest
+  pathname: string
+  search: string
+  theme: Theme
+  a11y: boolean
+}): ShellHtmlResult {
+  const route = parseRoute(args.pathname, args.search)
+  const seed: ShellSeed = {
+    manifest: args.manifest,
+    route,
+    theme: args.theme,
+    a11y: args.a11y,
+  }
+  try {
+    const html = renderToString(
+      <StrictMode>
+        <Shell seed={seed} />
+      </StrictMode>,
+    )
+    return { html, ssr: true }
+  } catch (err) {
+    // The shell is first-party code; a throw here is a defect, not a graceful
+    // case. Don't fail the document — serve it empty for the client to mount,
+    // and surface the error so it gets fixed.
+    console.warn(
+      '[display-case] shell server-render failed; the client will render it:',
+      err instanceof Error ? err.message : String(err),
+    )
+    return { html: '', ssr: false }
+  }
+}

package/src/server/prod-server.ts ADDED Viewed

@@ -0,0 +1,237 @@
+import { mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { BuildDescriptor } from '../commands/publish'
+import type { Manifest } from '../core/manifest'
+import { primerDoc, renderDoc, shellDoc } from '../render/documents'
+import type { PrimerHtmlResult } from '../render/ssr-primer'
+import type { CaseRenderer } from '../render/ssr-render'
+import { renderShellToHtml } from '../render/ssr-shell'
+import type { Theme } from '../ui/shell-core'
+/**
+ * The production host for a published build. It serves the pre-rendered shell,
+ * isolated case render, and primer documents — rendered on request through the
+ * SAME renderers the dev server uses (`ssr-shell`/`ssr-render`/`ssr-primer`) —
+ * plus the content-hashed assets, with hosting-appropriate caching, a health
+ * endpoint, and base-path support. It carries NONE of the dev machinery: no
+ * watcher, no rebuild, no live-reload stream, no on-demand a11y, no dev
+ * endpoints. Build once, serve.
+ */
+const ASSET_CACHE = 'public, max-age=31536000, immutable'
+const HTML_CACHE = 'no-cache'
+interface Loaded {
+  buildDir: string
+  descriptor: BuildDescriptor
+  manifest: Manifest
+  renderCase: CaseRenderer
+  renderPrimer: (() => PrimerHtmlResult) | null
+}
+async function load(buildDir: string): Promise<Loaded> {
+  const descriptor = (await Bun.file(
+    join(buildDir, 'dc-build.json'),
+  ).json()) as BuildDescriptor
+  const manifest = (await Bun.file(
+    join(buildDir, 'manifest.json'),
+  ).json()) as Manifest
+  const ssrMod = (await import(join(buildDir, 'server', 'ssr-entry.js'))) as {
+    renderCaseToHtml: CaseRenderer
+  }
+  let renderPrimer: (() => PrimerHtmlResult) | null = null
+  if (descriptor.hasPrimer) {
+    const pMod = (await import(
+      join(buildDir, 'server', 'ssr-primer-entry.js')
+    )) as { renderPrimerToHtml: () => PrimerHtmlResult }
+    renderPrimer = pMod.renderPrimerToHtml
+  }
+  return {
+    buildDir,
+    descriptor,
+    manifest,
+    renderCase: ssrMod.renderCaseToHtml,
+    renderPrimer,
+  }
+}
+function parseRenderState(url: URL) {
+  const parts = url.pathname.split('/').filter(Boolean)
+  const p = url.searchParams
+  const tweaks: Record<string, string> = {}
+  for (const [k, v] of p) if (k.startsWith('t.')) tweaks[k.slice(2)] = v
+  const widthParam = p.get('width')
+  // path shape (after base strip): /render/<component>/<case>
+  return {
+    componentId: parts[1] ?? '',
+    caseId: parts[2] ?? '',
+    theme: (p.get('theme') === 'dark' ? 'dark' : 'light') as Theme,
+    width: widthParam ? Number(widthParam) : null,
+    tweaks,
+    fit: p.get('fit') === '1',
+    transparent: p.get('transparent') === '1',
+  }
+}
+/** Render the document for an internal path (base already stripped) + query.
+ *  Returns null for non-document paths (assets/health handled by the caller). */
+function documentFor(loaded: Loaded, path: string, url: URL): string {
+  const { descriptor, manifest, renderCase, renderPrimer } = loaded
+  const assets = descriptor.assets
+  const theme: Theme =
+    url.searchParams.get('theme') === 'dark' ? 'dark' : 'light'
+  if (path === '/render/primer') {
+    let markup = ''
+    let ssr = false
+    let headStyles: string | undefined
+    if (renderPrimer) {
+      const r = renderPrimer()
+      if (!r.browserOnly) {
+        markup = r.html
+        ssr = true
+        headStyles = r.headStyles
+      }
+    }
+    return primerDoc({
+      tokensCss: descriptor.tokensCss,
+      globalCss: descriptor.globalCss,
+      vitrineCss: descriptor.vitrineCss,
+      theme,
+      markup,
+      ssr,
+      headStyles,
+      assets,
+    })
+  }
+  if (path === '/render' || path.startsWith('/render/')) {
+    const rs = parseRenderState(url)
+    let markup = ''
+    let ssr = false
+    let headStyles: string | undefined
+    if (rs.componentId && rs.caseId) {
+      const r = renderCase({
+        componentId: rs.componentId,
+        caseId: rs.caseId,
+        width: rs.width,
+        tweaks: rs.tweaks,
+      })
+      if (!r.browserOnly) {
+        markup = r.html
+        ssr = true
+        headStyles = r.headStyles
+      }
+    }
+    return renderDoc({
+      globalCss: descriptor.globalCss,
+      vitrineCss: descriptor.vitrineCss,
+      theme: rs.theme,
+      transparent: rs.transparent,
+      fit: rs.fit,
+      markup,
+      ssr,
+      headStyles,
+      assets,
+    })
+  }
+  // Shell: `/`, `/primer`, every `/c/...` deep link.
+  const shell = renderShellToHtml({
+    manifest,
+    pathname: path,
+    search: url.search,
+    theme,
+    a11y: false,
+  })
+  return shellDoc({
+    title: descriptor.title,
+    tokensCss: descriptor.tokensCss,
+    globalCss: descriptor.globalCss,
+    vitrineCss: descriptor.vitrineCss,
+    theme,
+    markup: shell.html,
+    ssr: shell.ssr,
+    manifest,
+    a11y: false,
+    assets,
+  })
+}
+export async function startProdServer(
+  buildDir: string,
+  opts: { port?: number } = {},
+) {
+  const loaded = await load(buildDir)
+  const base = loaded.descriptor.base
+  const server = Bun.serve({
+    port: opts.port ?? 3000,
+    async fetch(req) {
+      const url = new URL(req.url)
+      let path = url.pathname
+      if (base && (path === base || path.startsWith(`${base}/`))) {
+        path = path.slice(base.length) || '/'
+      }
+      if (path === '/health') return new Response('ok')
+      if (path.startsWith('/assets/')) {
+        const file = Bun.file(
+          join(buildDir, 'assets', path.slice('/assets/'.length)),
+        )
+        if (!(await file.exists())) {
+          return new Response('not found', { status: 404 })
+        }
+        return new Response(file, { headers: { 'cache-control': ASSET_CACHE } })
+      }
+      return new Response(documentFor(loaded, path, url), {
+        headers: {
+          'content-type': 'text/html; charset=utf-8',
+          'cache-control': HTML_CACHE,
+        },
+      })
+    },
+  })
+  return server
+}
+/**
+ * Crawl every address and write complete HTML files, so the build can be hosted
+ * with no running server. Files are keyed by *path* (default theme + tweaks);
+ * address-encoded variations resolve on the client after hydration — logged so
+ * the boundary is explicit, not silent.
+ */
+export async function writeStaticExport(buildDir: string): Promise<void> {
+  const loaded = await load(buildDir)
+  const { manifest } = loaded
+  const write = async (route: string, file: string) => {
+    const url = new URL(`http://static${route}`)
+    const html = documentFor(loaded, url.pathname, url)
+    const abs = join(buildDir, file)
+    await mkdir(dirname(abs), { recursive: true })
+    await Bun.write(abs, html)
+  }
+  await write('/', 'index.html')
+  if (loaded.descriptor.hasPrimer) {
+    await write('/primer', 'primer/index.html')
+    await write('/render/primer', 'render/primer/index.html')
+  }
+  let pages = 2
+  for (const c of manifest.components) {
+    for (const cs of c.cases) {
+      await write(`/c/${c.id}/${cs.id}`, `c/${c.id}/${cs.id}/index.html`)
+      await write(
+        `/render/${c.id}/${cs.id}`,
+        `render/${c.id}/${cs.id}/index.html`,
+      )
+      pages += 2
+    }
+  }
+  console.log(
+    `  static export: ${pages} page(s). Note: query-encoded tweak/theme ` +
+      'variations have no per-path file — they resolve on the client after hydration.',
+  )
+}