@estiva-app/ui 0.35.1 → 0.36.0

package/src/registry/contract.ts

@@ -51,7 +51,10 @@ export function pageProblem(source: string): string | null {
     .map((s) => s.trim())
     .find((s) => s && !s.startsWith('<') && !s.startsWith('import '))
   if (!opening) return 'no opening line under the title saying what the part is'
-  if (!/^##\s+How\s*\n[\s\S]*?```tsx?\n/m.test(text)) return 'no code under "How"'
+  // Only the How section: the code block must sit under How, not in a later section
+  // (a page with none under How and one under What it owns passed, R18).
+  const how = text.split(/^##\s+How\s*$/m)[1]?.split(/^##\s/m)[0] ?? ''
+  if (!/```tsx?\n/.test(how)) return 'no code under "How"'
   return null
 }
 
@@ -84,7 +87,7 @@ export function linkProblems(registry: Registry, ids: ReadonlySet<string>): stri
  *
  * `root` is the app's own folder: the one its catalogue's paths are relative to.
  */
-export function contractProblems(registry: Registry, root: string): string[] {
+export function contractProblems(registry: Registry, root: string, known: ReadonlySet<string> = new Set(registry.entries.map((e) => e.name))): string[] {
   const problems: string[] = []
   for (const entry of registry.entries) {
     const cls = entry.app?.class
@@ -100,9 +103,79 @@ export function contractProblems(registry: Registry, root: string): string[] {
     const text = readFileSync(join(root, page), 'utf8')
     const problem = pageProblem(text)
     if (problem) problems.push(`${where}: ${page} has ${problem}`)
+    const whenNot = whenNotProblem(text, [entry.name], known)
+    if (whenNot) problems.push(`${where}: ${page}: ${whenNot}`)
     if (entry.storyId === null && !hasSeenIn(text)) {
       problems.push(`${where} is drawn nowhere: give it a story, or write a "**Seen in**" line on ${page} naming the stories that draw it, or why none can`)
     }
+    // A reusable part links to its page or a story (Katerina's ruling B10, 25 September):
+    // the catalogue reads the page's `<Meta title>`, so a page without one leaves it unlinked.
+    if (entry.storyId === null && entry.docsId === null) {
+      problems.push(`${where} links to nothing in Storybook: give ${page} a \`<Meta title="…" />\`, or give the part a story`)
+    }
+  }
+  return problems
+}
+
+/** Storybook's id for a title: lower case, every run of other characters one hyphen. */
+const toStoryId = (title: string) =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+/** The names a page's section writes as a part: bold or in backticks, starting with a capital. */
+export function namedParts(section: string): string[] {
+  return [...section.matchAll(/\*\*`?([A-Z][A-Za-z0-9]+)`?\*\*|`([A-Z][A-Za-z0-9]+)`/g)].map((m) => m[1] ?? m[2])
+}
+
+/** The line a "When not" starts where no part stands in (Katerina's ruling B8). */
+export const NO_ALTERNATIVE = /^No alternative:/m
+
+/**
+ * Why a page's `When not` breaks the ruling B8 (25 September), or null. The plan
+ * asked for "When not — naming the alternative"; CI checked only that the
+ * heading was there, and 29 pages across the three repos named nothing. Now the
+ * section names a real part other than the page's own (`own`), from `known`, or
+ * a line of it starts "No alternative:" and says why there is none.
+ */
+export function whenNotProblem(source: string, own: readonly string[], known: ReadonlySet<string>): string | null {
+  const section = source.replace(/\r\n/g, '\n').split(/^##\s+When not\s*$/m)[1]?.split(/^##\s/m)[0]
+  // A missing section is pageProblem's to report.
+  if (section === undefined || NO_ALTERNATIVE.test(section)) return null
+  if (namedParts(section).some((name) => known.has(name) && !own.includes(name))) return null
+  return '"When not" names no other part: name the part to use instead, as **Name** or `Name`, or start a line "No alternative:" that says why there is none'
+}
+
+/**
+ * What an app's usage pages name that is not there (the re-review after the audit
+ * before UIG-26, R14): a part named under When or When not that no catalogue has —
+ * Peek's StartTopicDialog sent readers to CreateTopicDialog, deleted by FOL-23 —
+ * and a story a **Seen in** line names that no Storybook has. `known` is every part
+ * of the package and the app; `titles` is the app's Storybook titles, when there
+ * is an index to read them from; `packageIds` the package's story and docs ids, so
+ * a page may send readers to the package's Storybook too.
+ */
+export function nameProblems(registry: Registry, root: string, { known, titles, packageIds = [] }: { known: Set<string>; titles?: Set<string>; packageIds?: string[] }): string[] {
+  const problems: string[] = []
+  for (const entry of registry.entries) {
+    if (!entry.docPage || !existsSync(join(root, entry.docPage))) continue
+    const text = readFileSync(join(root, entry.docPage), 'utf8').replace(/\r\n/g, '\n')
+    for (const heading of ['When', 'When not']) {
+      const section = text.split(new RegExp(`^##\\s+${heading}\\s*$`, 'm'))[1]?.split(/^##\s/m)[0] ?? ''
+      for (const name of new Set(namedParts(section).filter((n) => !known.has(n)))) {
+        problems.push(`${entry.docPage}: "${heading}" names ${name}, which is no part of the package or this app`)
+      }
+    }
+    if (!titles) continue
+    const seenIn = text.match(/^\*\*Seen in\*\*[^\n]*(?:\n(?!\n)[^\n]*)*/m)?.[0] ?? ''
+    for (const [, raw] of seenIn.matchAll(/\*([A-Z][^*/]*\/[^*]+)\*/g)) {
+      // A title may wrap across lines, and a line may break after its slash.
+      const title = raw.replace(/\s+/g, ' ').replace(/\s*\/\s*/g, '/').trim()
+      const id = toStoryId(title)
+      if (titles.has(title) || packageIds.some((p) => p.startsWith(`${id}--`))) continue
+      problems.push(`${entry.docPage}: "Seen in" names ${title}, which no Storybook has`)
+    }
   }
   return problems
 }

package/src/registry/index.ts

@@ -12,7 +12,7 @@
  */
 export { buildRegistry, readIndexExports, serializeRegistry, type BuildOptions } from './build'
 export { buildAppRegistry, type AppBuildOptions } from './app'
-export { CONTRACT_KINDS, PAGE_SECTIONS, contractProblems, hasSeenIn, linkProblems, pageProblem } from './contract'
+export { CONTRACT_KINDS, NO_ALTERNATIVE, PAGE_SECTIONS, contractProblems, hasSeenIn, linkProblems, namedParts, pageProblem, whenNotProblem } from './contract'
 export { docsLink, findInRegistries, findInRegistry, formatFindings, type Finding } from './find'
 export {
   CLASSES,

package/src/registry/registry.test.ts

@@ -80,6 +80,20 @@ describe('the registry builds', () => {
     expect(entry('Card').ownsBehaviours).toEqual([])
   })
 
+  // B9: worked out from what a part draws and what it is, not only UIG-8's owners.
+  it('gives a part what the part it is owns, and a Base UI piece only what it is', () => {
+    const ids = (name: string) => entry(name).ownsBehaviours.map((owned) => owned.id)
+    // ConfirmDialog returns a DialogShell: it keeps focus inside and stops the page scrolling.
+    expect(ids('ConfirmDialog')).toEqual(expect.arrayContaining(['portal', 'focus', 'scroll-lock', 'press-outside']))
+    // MenuItem draws Menu.Item: a menu item, not a floating menu.
+    expect(ids('MenuItem')).toEqual(expect.arrayContaining(['base-ui', 'role']))
+    expect(ids('MenuItem')).not.toContain('portal')
+    // A tooltip's floating stays the tooltip's.
+    expect(ids('NavItem')).not.toContain('portal')
+    // Being built on Base UI, a role and a Tab stop are not handed on.
+    expect(ids('EmptyState')).not.toContain('tab-stop')
+  })
+
   it('reads the variants from the props type, following a local alias', () => {
     // ButtonVariant and ButtonSize are aliases; the props type points at them.
     expect(entry('Button').variants).toEqual([

package/src/registry/siblings.test.ts

@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it } from 'vitest'
-import { appName, findSiblings, workspaceOf } from './siblings'
+import { appName, behindBy, findSiblings, workspaceOf } from './siblings'
 
 const workspace = mkdtempSync(join(tmpdir(), 'uig20-'))
 afterAll(() => rmSync(workspace, { recursive: true, force: true }))
@@ -83,3 +83,26 @@ describe.skipIf(!existsSync(cli))('estiva-ui find, with nothing else typed', ()
     expect(find(join(workspace, 'alpha'), 'workbench', '--here')).not.toContain('Workbench')
   })
 })
+
+// The re-review after the audit before UIG-26: a search from one repository read a
+// neighbour's checkout eleven commits behind, and answered with a part it had deleted.
+describe('behindBy', () => {
+  it('says how far a checkout is behind its main as last fetched, and null for a folder that is none', () => {
+    const base = mkdtempSync(join(tmpdir(), 'behind-'))
+    const git = (cwd: string, ...a: string[]) => execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', ...a], { cwd, stdio: 'pipe' })
+    git(base, 'init', '-q', '--bare', '-b', 'main', 'origin.git')
+    git(base, 'clone', '-q', 'origin.git', 'writer')
+    git(join(base, 'writer'), 'commit', '-q', '--allow-empty', '-m', 'one')
+    git(join(base, 'writer'), 'push', '-q', 'origin', 'HEAD:main')
+    git(base, 'clone', '-q', 'origin.git', 'reader')
+    const reader = join(base, 'reader')
+    expect(behindBy(reader)).toBe(0)
+    git(join(base, 'writer'), 'commit', '-q', '--allow-empty', '-m', 'two')
+    git(join(base, 'writer'), 'push', '-q', 'origin', 'HEAD:main')
+    expect(behindBy(reader)).toBe(0)
+    git(reader, 'fetch', '-q')
+    expect(behindBy(reader)).toBe(1)
+    expect(behindBy(tmpdir())).toBeNull()
+    rmSync(base, { recursive: true, force: true })
+  })
+})

package/src/registry/siblings.ts

@@ -16,6 +16,7 @@
  * somebody's copy) carries the same package name; the app the search runs in
  * wins, then the one whose top folder has the shortest name.
  */
+import { execFileSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 
@@ -94,3 +95,25 @@ export function findSiblings(workspace: string, { skip = [] }: { skip?: string[]
   }
   return [...byPackage.values()].sort((a, b) => a.name.localeCompare(b.name))
 }
+
+/**
+ * How many commits the checkout that holds `folder` is behind its remote's main,
+ * as last fetched: nothing is fetched, so a search stays quick. Null when it is
+ * not a git checkout or has no remote main. A search that reads a stale copy
+ * answers with parts that are gone (the re-review after the audit before UIG-26:
+ * "files panel" found Peek's deleted FilesPanel in an old checkout), so `find`
+ * says so beside its answer.
+ */
+export function behindBy(folder: string): number | null {
+  const git = (...a: string[]) => {
+    try {
+      return execFileSync('git', ['-C', folder, ...a], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }).toString().trim()
+    } catch {
+      return null
+    }
+  }
+  const main = git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD') ?? (git('rev-parse', '--verify', '--quiet', 'origin/main') ? 'origin/main' : null)
+  if (!main) return null
+  const count = Number(git('rev-list', '--count', `HEAD..${main}`))
+  return Number.isFinite(count) ? count : null
+}

package/src/registry/storymap.test.ts

@@ -1,16 +1,18 @@
 /// <reference types="node" />
 /**
- * The app's hand-written map of its Storybook (audit A3). Every case is Peek's:
- * the Huddles heading its Introduction and `HEADINGS` kept after FOL-23 deleted
- * the stories, the "49 parts worth reusing" it kept when the catalogue built 41,
- * and a Storybook with no map at all, which has nothing to rot.
+ * The hand-written map of a Storybook (audit A3, widened by R16). Every case is a
+ * real one: Peek's Huddles heading, kept in its Introduction and `HEADINGS` after
+ * FOL-23 deleted the stories, and its "49 parts worth reusing" when the catalogue
+ * built 41; Ship's `storySort.order` naming a Feedback heading it does not have and
+ * leaving out Pages, and its Introduction's bullets; the package's order leaving
+ * out Layout; and a Storybook with no map at all, which has nothing to rot.
  */
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { afterAll, describe, expect, it } from 'vitest'
 import type { Registry } from './schema'
-import { introductionCount, introductionHeadings, orderedHeadings, sidebarHeadings, storyMapProblems } from './storymap'
+import { indexHeadings, introductionCount, introductionHeadings, orderedHeadings, sidebarHeadings, storyMapProblems } from './storymap'
 
 const made: string[] = []
 afterAll(() => {
@@ -31,66 +33,85 @@ function app(files: Record<string, string>): string {
 const catalogue = (...classes: string[]) => ({ entries: classes.map((cls) => ({ app: { class: cls } })) }) as unknown as Registry
 
 const STORY = (title: string) => `import type { Meta } from '@storybook/react-vite'\nconst meta = {\n  title: '${title}',\n} satisfies Meta\nexport default meta\n`
-const PREVIEW = (headings: string[]) =>
+const HEADINGS_PREVIEW = (headings: string[]) =>
   `export default {\n  parameters: {\n    options: {\n      storySort: (a, b) => {\n        const HEADINGS = [\n${headings.map((h) => `          '${h}', // someone's heading\n`).join('')}        ]\n        return 0\n      },\n    },\n  },\n}\n`
-const INTRO = (count: number, headings: string[]) =>
+const ORDER_PREVIEW = (headings: string[]) =>
+  `export default {\n  parameters: {\n    options: {\n      // Docs first; the rest follows\n      storySort: {\n        order: [${headings.map((h) => (h === 'Docs' ? "'Docs', ['Introduction']" : `'${h}'`)).join(', ')}],\n      },\n    },\n  },\n}\n`
+const TABLE_INTRO = (count: number, headings: string[]) =>
   `import { Meta } from '@storybook/addon-docs/blocks'\n\n<Meta title="Docs/Introduction" />\n\nOf everything the app owns, **${count} parts worth reusing** carry a written rule.\n\n| Heading | What |\n|---|---|\n${headings.map((h) => `| **${h}** | About ${h}. |`).join('\n')}\n`
+const BULLET_INTRO = (groups: string[][]) =>
+  `<Meta title="Docs/Introduction" />\n\n## How the sidebar is organised\n\n${groups.map((g) => `- **${g.join(' · ')}** — about them.`).join('\n')}\n\n## Conventions\n\n- **Stories first.** A component exists in Storybook first.\n`
 
 const PEEK_TODAY = {
-  'src/stories/Introduction.mdx': INTRO(2, ['Docs', 'Primitives', 'Huddles']),
+  'src/stories/Introduction.mdx': TABLE_INTRO(2, ['Docs', 'Primitives', 'Huddles']),
   'src/components/ui/Badge.stories.tsx': STORY('Primitives/Badge'),
   'src/components/ui/Chip.mdx': `import { Meta } from '@storybook/addon-docs/blocks'\n\n<Meta title='Primitives/Chip' />\n\n# Chip\n`,
-  '.storybook/preview.tsx': PREVIEW(['Docs', 'Primitives', 'Huddles']),
+  '.storybook/preview.tsx': HEADINGS_PREVIEW(['Docs', 'Primitives', 'Huddles']),
 }
 
 describe('reading the map', () => {
-  it('reads the sidebar from story titles and from page titles in either quote', () => {
-    expect([...sidebarHeadings(app(PEEK_TODAY))].sort()).toEqual(['Docs', 'Primitives'])
+  it('reads the sidebar from story titles and page titles in either quote, in src and stories', () => {
+    expect([...sidebarHeadings(app({ ...PEEK_TODAY, 'stories/Tokens.mdx': "<Meta title='Tokens/All' />\n" }))].sort()).toEqual(['Docs', 'Primitives', 'Tokens'])
   })
 
-  it('reads the order with its comments removed, and says when there is none', () => {
-    expect(orderedHeadings(PREVIEW(['Docs', 'Pages']))).toEqual(['Docs', 'Pages'])
+  it("reads Storybook's own index, whatever way a title was written", () => {
+    expect([...indexHeadings({ a: { title: 'Pages/Desk' }, b: { title: 'Docs/Introduction' }, c: {} })].sort()).toEqual(['Docs', 'Pages'])
+  })
+
+  it('reads a HEADINGS list and a storySort order, skipping comments and nested lists', () => {
+    expect(orderedHeadings(HEADINGS_PREVIEW(['Docs', 'Pages']))).toEqual(['Docs', 'Pages'])
+    expect(orderedHeadings(ORDER_PREVIEW(['Docs', 'Primitives', 'Feedback']))).toEqual(['Docs', 'Primitives', 'Feedback'])
     expect(orderedHeadings('export default {}')).toBeNull()
   })
 
-  it('reads the Introduction: its bold table rows and its stated count', () => {
-    const intro = INTRO(49, ['Docs', 'Huddles'])
-    expect([...introductionHeadings(intro)]).toEqual(['Docs', 'Huddles'])
-    expect(introductionCount(intro)).toBe(49)
+  it("reads the Introduction's table rows and its bullets, and its stated count", () => {
+    expect([...introductionHeadings(TABLE_INTRO(49, ['Docs', 'Huddles']))]).toEqual(['Docs', 'Huddles'])
+    // A bullet with no dash after its bold words is prose, not a heading.
+    expect([...introductionHeadings(BULLET_INTRO([['Docs'], ['Primitives', 'Feedback', 'Inputs']]))]).toEqual(['Docs', 'Primitives', 'Feedback', 'Inputs'])
+    expect(introductionCount(TABLE_INTRO(49, ['Docs']))).toBe(49)
     expect(introductionCount('# No number here')).toBeNull()
   })
 })
 
 describe('storyMapProblems', () => {
   it("finds Peek's three stale lines: a heading in both maps with no story, and the wrong count", () => {
-    const problems = storyMapProblems(catalogue('reusable', 'reusable', 'reusable', 'local'), app(PEEK_TODAY))
-    expect(problems).toEqual([
-      '.storybook/preview.tsx: named in HEADINGS but no story uses them: Huddles',
+    expect(storyMapProblems(app(PEEK_TODAY), { registry: catalogue('reusable', 'reusable', 'reusable', 'local') })).toEqual([
+      '.storybook/preview.tsx: in the heading order but no story uses them: Huddles',
       'src/stories/Introduction.mdx: the page names, the sidebar does not have: Huddles',
       'src/stories/Introduction.mdx: says 2 parts worth reusing; the catalogue builds 3',
     ])
   })
 
-  it('finds a heading the maps forget, which falls to the bottom of the sidebar', () => {
-    const dir = app({ ...PEEK_TODAY, 'src/pages/Desk.stories.tsx': STORY('Pages/Desk') })
-    expect(storyMapProblems(catalogue('reusable', 'promote-candidate'), dir)).toEqual([
-      '.storybook/preview.tsx: not named in HEADINGS, so they fall to the bottom of the sidebar: Pages',
-      '.storybook/preview.tsx: named in HEADINGS but no story uses them: Huddles',
+  it("finds Ship's: an order and bullets naming Feedback, which it has not got, and leaving out Pages", () => {
+    const dir = app({
+      '.storybook/preview.tsx': ORDER_PREVIEW(['Docs', 'Primitives', 'Feedback']),
+      'src/stories/Introduction.mdx': BULLET_INTRO([['Docs'], ['Primitives', 'Feedback']]),
+    })
+    expect(storyMapProblems(dir, { real: new Set(['Docs', 'Primitives', 'Pages']) })).toEqual([
+      '.storybook/preview.tsx: not in the heading order, so they fall to the bottom of the sidebar: Pages',
+      '.storybook/preview.tsx: in the heading order but no story uses them: Feedback',
       'src/stories/Introduction.mdx: the sidebar has, the page does not name: Pages',
-      'src/stories/Introduction.mdx: the page names, the sidebar does not have: Huddles',
+      'src/stories/Introduction.mdx: the page names, the sidebar does not have: Feedback',
+    ])
+  })
+
+  it("finds the package's order leaving out Layout, from a Storybook index", () => {
+    const dir = app({ '.storybook/preview.tsx': ORDER_PREVIEW(['Docs', 'Primitives']) })
+    expect(storyMapProblems(dir, { real: indexHeadings({ a: { title: 'Layout/ListColumn' }, b: { title: 'Primitives/Button' }, c: { title: 'Docs/Introduction' } }) })).toEqual([
+      '.storybook/preview.tsx: not in the heading order, so they fall to the bottom of the sidebar: Layout',
     ])
   })
 
   it('passes when both maps match the Storybook and the count matches the catalogue', () => {
     const dir = app({
       ...PEEK_TODAY,
-      'src/stories/Introduction.mdx': INTRO(2, ['Docs', 'Primitives']),
-      '.storybook/preview.tsx': PREVIEW(['Docs', 'Primitives']),
+      'src/stories/Introduction.mdx': TABLE_INTRO(2, ['Docs', 'Primitives']),
+      '.storybook/preview.tsx': HEADINGS_PREVIEW(['Docs', 'Primitives']),
     })
-    expect(storyMapProblems(catalogue('reusable', 'promote-candidate', 'local'), dir)).toEqual([])
+    expect(storyMapProblems(dir, { registry: catalogue('reusable', 'promote-candidate', 'local') })).toEqual([])
   })
 
-  it('has nothing to check in an app that keeps no map', () => {
-    expect(storyMapProblems(catalogue('reusable'), app({ 'src/Badge.stories.tsx': STORY('Parts/Badge') }))).toEqual([])
+  it('has nothing to check in a repository that keeps no map', () => {
+    expect(storyMapProblems(app({ 'src/Badge.stories.tsx': STORY('Parts/Badge') }), { registry: catalogue('reusable') })).toEqual([])
   })
 })

package/src/registry/storymap.ts

@@ -1,26 +1,30 @@
 /// <reference types="node" />
 /**
- * The hand-written map of an app's Storybook, held against the Storybook it
- * describes (moved here from Peek's own status checks, audit A3).
+ * The hand-written map of a Storybook, held against the Storybook it describes
+ * (moved here from Peek's own status checks, audit A3; widened by the re-review
+ * after it, R16).
  *
- * An app may keep two maps of its sidebar: the order of its top-level headings
- * (`const HEADINGS = [...]` in `.storybook/preview.tsx`, read by `storySort`),
- * and the Introduction page (`src/stories/Introduction.mdx`), which names each
- * heading in a table row and states how many parts are worth reusing. Both are
- * written by hand and both describe something that moves, so both rot: Peek's
- * named a Huddles heading for a day after its stories were deleted, and said 49
- * reusable parts when the catalogue built 41. Its own checks saw it, but they
- * ran only in `gates:status`, never in CI.
+ * A repository may keep two maps of its sidebar: the order of its top-level
+ * headings in `.storybook/preview.tsx` — a `const HEADINGS = [...]` list read by
+ * a `storySort` function (Peek), or `storySort: { order: [...] }` (Ship, this
+ * package) — and the Introduction page, which names each heading, in a table row
+ * (`| **Folders** | … |`, Peek) or a bullet (`- **Primitives · Inputs** — …`,
+ * Ship), and in an app states how many parts are worth reusing. Both are written
+ * by hand and both describe something that moves, so both rot: Peek's named a
+ * Huddles heading for a day after its stories were deleted and said 49 reusable
+ * parts when the catalogue built 41; Ship's named a Feedback heading it does not
+ * have and left out four it does.
  *
- * Every check here runs only when the app states the thing it checks: an app
- * with no `HEADINGS` list, or no Introduction, has nothing to rot.
+ * The real headings are read from Storybook's own index when the command has
+ * one, so a title written any way at all counts; otherwise from the story files.
+ * Every check runs only when the repository states the thing it checks.
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Registry } from './schema'
 
 const PREVIEW = '.storybook/preview.tsx'
-const INTRODUCTION = 'src/stories/Introduction.mdx'
+const INTRODUCTIONS = ['src/stories/Introduction.mdx', 'stories/Introduction.mdx']
 /** The classes an app's Introduction counts as "worth reusing". */
 const WORTH_REUSING = ['reusable', 'promote-candidate']
 
@@ -36,10 +40,11 @@ function storyFiles(root: string): string[] {
     }
   }
   walk(join(root, 'src'))
+  walk(join(root, 'stories'))
   return out
 }
 
-/** Every top-level heading the sidebar has: the first segment of each story file's or page's title. */
+/** Every top-level heading the sidebar has, read from the story files: the first segment of each title. */
 export function sidebarHeadings(root: string): Set<string> {
   const real = new Set<string>()
   for (const file of storyFiles(root)) {
@@ -52,19 +57,50 @@ export function sidebarHeadings(root: string): Set<string> {
   return real
 }
 
-/** The headings `preview.tsx` orders, or null when it keeps no list. */
+/** The top-level headings of Storybook's own index (`storybook index`): the first segment of every entry's title. */
+export function indexHeadings(entries: Record<string, { title?: string }>): Set<string> {
+  return new Set(Object.values(entries).flatMap((e) => (e.title ? [e.title.split('/')[0].trim()] : [])))
+}
+
+/** The strings at the top level of the array that starts at `open` (the index of its `[`), skipping nested arrays. */
+function topLevelStrings(text: string, open: number): string[] {
+  const out: string[] = []
+  let depth = 0
+  for (let i = open; i < text.length; i++) {
+    const c = text[i]
+    if (c === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2)
+      if (end < 0) break
+      i = end + 1
+    } else if (c === '/' && text[i + 1] === '/') i = text.indexOf('\n', i)
+    else if (c === '[') depth++
+    else if (c === ']') {
+      if (--depth === 0) return out
+    } else if (c === "'" || c === '"') {
+      const end = text.indexOf(c, i + 1)
+      if (depth === 1) out.push(text.slice(i + 1, end))
+      i = end
+    }
+    if (i < 0) break
+  }
+  return out
+}
+
+/** The headings the preview orders — a `HEADINGS` list or `storySort: { order: [...] }` — or null when it keeps no order. */
 export function orderedHeadings(previewText: string): string[] | null {
-  const block = previewText.match(/const HEADINGS = \[([\s\S]*?)\]/)
-  if (!block) return null
-  // Comments first: the list is commented per heading, and an apostrophe in a
-  // comment would open a string that swallows the rest.
-  const listed = block[1].replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '')
-  return [...listed.matchAll(/'([^']+)'/g)].map((m) => m[1])
+  const list = /const HEADINGS = \[/.exec(previewText) ?? /\border:\s*\[/.exec(previewText)
+  if (!list) return null
+  return topLevelStrings(previewText, list.index + list[0].length - 1)
 }
 
-/** The headings the Introduction names, one per table row that opens with a bold name. */
+/**
+ * The headings the Introduction names: a table row that opens with a bold name,
+ * or a bullet that opens with bold names joined by " · ".
+ */
 export function introductionHeadings(introText: string): Set<string> {
-  return new Set([...introText.matchAll(/^\|\s*\*\*([^*]+)\*\*\s*\|/gm)].map((m) => m[1].trim()))
+  const rows = [...introText.matchAll(/^\|\s*\*\*([^*]+)\*\*\s*\|/gm)].map((m) => m[1])
+  const bullets = [...introText.matchAll(/^[-*]\s+\*\*([^*]+)\*\*\s*[—–-]/gm)].flatMap((m) => m[1].split('·'))
+  return new Set([...rows, ...bullets].map((h) => h.trim()).filter(Boolean))
 }
 
 /** The number the Introduction states, or null when it states none. */
@@ -73,34 +109,37 @@ export function introductionCount(introText: string): number | null {
   return said ? Number(said[1]) : null
 }
 
-/** What is wrong with the app's hand-written map of its Storybook; empty when nothing is. */
-export function storyMapProblems(registry: Registry, root: string): string[] {
+/**
+ * What is wrong with the repository's hand-written map of its Storybook; empty
+ * when nothing is. `real` is the sidebar's top-level headings from Storybook's
+ * index, when the caller has it; `registry` is needed only for an app's count.
+ */
+export function storyMapProblems(root: string, { registry, real = sidebarHeadings(root) }: { registry?: Registry; real?: Set<string> } = {}): string[] {
   const problems: string[] = []
-  const real = sidebarHeadings(root)
   const previewPath = join(root, PREVIEW)
   if (existsSync(previewPath)) {
     const ordered = orderedHeadings(readFileSync(previewPath, 'utf8'))
     if (ordered) {
       const unordered = [...real].filter((r) => !ordered.includes(r))
       const empty = ordered.filter((o) => !real.has(o))
-      if (unordered.length) problems.push(`${PREVIEW}: not named in HEADINGS, so they fall to the bottom of the sidebar: ${unordered.join(', ')}`)
-      if (empty.length) problems.push(`${PREVIEW}: named in HEADINGS but no story uses them: ${empty.join(', ')}`)
+      if (unordered.length) problems.push(`${PREVIEW}: not in the heading order, so they fall to the bottom of the sidebar: ${unordered.join(', ')}`)
+      if (empty.length) problems.push(`${PREVIEW}: in the heading order but no story uses them: ${empty.join(', ')}`)
     }
   }
-  const introPath = join(root, INTRODUCTION)
-  if (existsSync(introPath)) {
-    const intro = readFileSync(introPath, 'utf8')
-    const named = introductionHeadings(intro)
+  const intro = INTRODUCTIONS.find((p) => existsSync(join(root, p)))
+  if (intro) {
+    const text = readFileSync(join(root, intro), 'utf8')
+    const named = introductionHeadings(text)
     if (named.size) {
       const missing = [...real].filter((r) => !named.has(r))
       const stale = [...named].filter((n) => !real.has(n))
-      if (missing.length) problems.push(`${INTRODUCTION}: the sidebar has, the page does not name: ${missing.join(', ')}`)
-      if (stale.length) problems.push(`${INTRODUCTION}: the page names, the sidebar does not have: ${stale.join(', ')}`)
+      if (missing.length) problems.push(`${intro}: the sidebar has, the page does not name: ${missing.join(', ')}`)
+      if (stale.length) problems.push(`${intro}: the page names, the sidebar does not have: ${stale.join(', ')}`)
     }
-    const said = introductionCount(intro)
-    if (said !== null) {
+    const said = introductionCount(text)
+    if (said !== null && registry) {
       const reusable = registry.entries.filter((entry) => WORTH_REUSING.includes(entry.app?.class ?? '')).length
-      if (said !== reusable) problems.push(`${INTRODUCTION}: says ${said} parts worth reusing; the catalogue builds ${reusable}`)
+      if (said !== reusable) problems.push(`${intro}: says ${said} parts worth reusing; the catalogue builds ${reusable}`)
     }
   }
   return problems

package/stories/Choosing.mdx

@@ -68,12 +68,16 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | One window to find something and act on it, opened by a shortcut | **CommandPalette** — rows, forms and written answers, one level at a time |
 | Anything with a title, body and footer | **DialogShell** |
 | "Are you sure?" | **ConfirmDialog** |
+| A picture full screen, from a thumbnail | **Lightbox** — an **AttachmentCard** opens one by itself |
 
 ## Structure and wayfinding
 
 | You need | Reach for |
 |---|---|
 | Label–value rows (a details rail) | **Property** — `row` and `stacked` |
+| The bar across the top of a column: its title, and the buttons that act on the whole column | **ContainerHeader** — one per column; the actions as IconButtons in `actions` |
+| A box that can hold more than fits — a list that grows with its data counts, even when today's data fits | **ScrollArea** — its bar is drawn over the content and takes no width |
+| A status, a count or a category, in a small pill | **Chip** — six colour types; the colour is the message, the label makes it legible |
 | One thing — a conversation, a project, an object — as a box you can pick | **Card** — the fill by what it sits on; `href` for a link, `hover="fill"` in a feed |
 | A section heading, chevron, hover actions | **SectionHeader** |
 | A group of rows that opens and closes, and stays how you left it | **CollapsibleSection** — `storageKey` remembers |
@@ -95,6 +99,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | It happened, briefly | **Toast**, via `useToast` inside a `ToastProvider` |
 | It happened, and must not be missed | **Toast** with `durationMs: 0` and an action — it floats and stays until dismissed (D21) |
 | The whole surface has something to say | **Banner** — the strip under the top bar, full width; `onDismiss` if the reader closes it rather than the app |
+| A part that breaks without taking the page with it | **ErrorBoundary** — around each column, panel or conversation, and once around the app; `label` says what it holds |
 
 ## The frame
 
@@ -109,11 +114,12 @@ the **floating** TopBar goes with the **Rail** and the content card.
 | A 240px navigation column | **Sidebar**, filled with **NavItem** rows |
 | A 64px icon strip | **Rail**, filled with **RailItem** tiles |
 | The menu button and the logo | the TopBar's `menu` and `logo` slots — collapsing stays yours |
+| The list beside the thing that is open | **ListColumn** — 290px, its name in a **ContainerHeader**, the list under it scrolling |
 
 ## Deliberately not in the package
 
 - Anything that knows your **product's objects** — its documents, threads,
   files, tickets. Build it in your app, out of these parts, and keep its
   stories in your app's own Storybook.
-- Page layouts — panels inside the content, split views, side rails —
-  not here yet; they are the next batch.
+- Page layouts beyond the list column (**ListColumn**) and a column's bar
+  (**ContainerHeader**) — split views, side rails — not here yet.