@estiva-app/ui 0.35.2 → 0.37.0

package/src/registry/behaviours.ts

@@ -0,0 +1,223 @@
+/**
+ * What a part owns, worked out from what it draws (Katerina's ruling B9,
+ * 25 September).
+ *
+ * The plan's Gate 0 asked for "the behaviours it owns — derived from which Base
+ * UI parts it imports". Until 0.36.0 only "is built on Base UI" was; the rest
+ * was UIG-8's hand list of owners, which is right for the part that does the
+ * work and silent for every part built from it: ConfirmDialog draws DialogShell,
+ * whose page says it keeps focus inside, and the catalogue listed no focus for
+ * ConfirmDialog. Every app entry listed nothing at all.
+ *
+ * Now a part owns:
+ *
+ * - what the Base UI parts it draws do, from UIG-8's enumeration (`baseUi` on
+ *   each behaviour, read from Base UI's source): all of it for a whole part
+ *   (`Menu.Root`), what it is for a piece (`Menu.Item`);
+ * - what the whole of the part it **is** does (floating, focus, keys, scroll):
+ *   the part it hands back at its root, followed through parts inside parts, in
+ *   the package and in an app. ConfirmDialog returns a DialogShell, so it keeps
+ *   focus inside; a page with a menu somewhere in it does not float, and a
+ *   tooltip's floating stays the tooltip's;
+ * - and, in the package, what UIG-8's list says (the floor: a part like `Link`
+ *   is reachable with Tab without any Base UI in it).
+ *
+ * Read from the code: a JSX tag inside the part's own declaration, or inside a
+ * function of the same file it draws. A root on one branch of a condition
+ * still counts, so the list says what a part can be, not what one screen shows.
+ */
+import ts from 'typescript'
+import { OWNED_BEHAVIOURS } from '../eslint/index'
+import type { EntryBehaviour } from './schema'
+
+/** `@base-ui/react`, its sub-paths, and the old `@base-ui-components/react` spelling. */
+export const isBaseUi = (specifier: string) => /^@base-ui(?:-components)?\/react(?:\/|$)/.test(specifier)
+
+/**
+ * What drawing a Base UI part gives, by behaviour id. The whole part (`Menu.Root`,
+ * or a part of one piece: `<Separator>`, `<Toggle>`) does all UIG-8 lists for it;
+ * a piece of one (`Menu.Item`, `Toolbar.Button`) only says what it is.
+ */
+export function baseUiBehaviours(part: string, piece?: string): string[] {
+  const whole = !piece || piece === 'Root' || piece === 'Provider'
+  return OWNED_BEHAVIOURS.filter((owned) => owned.id === 'base-ui' || (owned.baseUi.includes(part) && (whole || owned.id === 'role'))).map((owned) => owned.id)
+}
+
+/**
+ * What a part hands on to the parts drawn around it: what the whole thing does.
+ * Being built on Base UI, a role and a Tab stop stay the inner part's: a banner
+ * with a button in it is not itself reachable with Tab.
+ */
+export const HANDED_ON = new Set(['portal', 'press-outside', 'page-keys', 'focus', 'scroll-lock', 'follow', 'scroll'])
+
+/** A hint drawn beside a part: its floating is its own, never the part's. */
+export const HINTS = new Set(['Tooltip', 'WithTooltip', 'TooltipProvider', 'PreviewCard'])
+
+/** What a part drawn inside another hands on to it. */
+export const handedOn = (name: string, owned: Iterable<string>) => (HINTS.has(name) ? [] : [...owned].filter((id) => HANDED_ON.has(id)))
+
+/** Behaviour ids as the catalogue writes them: in UIG-8's order, each once. */
+export function asBehaviours(ids: Iterable<string>): EntryBehaviour[] {
+  const held = new Set(ids)
+  return OWNED_BEHAVIOURS.filter((owned) => held.has(owned.id)).map((owned) => ({ id: owned.id, behaviour: owned.behaviour }))
+}
+
+/** A tag as written: `Dialog.Popup`, `Button`. */
+function tagText(tag: ts.JsxTagNameExpression): string | null {
+  if (ts.isIdentifier(tag)) return tag.text
+  if (ts.isPropertyAccessExpression(tag)) {
+    const inner = tagText(tag.expression as ts.JsxTagNameExpression)
+    return inner && `${inner}.${tag.name.text}`
+  }
+  return null
+}
+
+/** A tag's name and its piece: `['Dialog', 'Popup']`, `['Button', undefined]`. */
+export const splitTag = (tag: string): [string, string | undefined] => {
+  const [root, piece] = tag.split('.')
+  return [root, piece]
+}
+
+/** Every tag drawn anywhere under `node`, as written. */
+function tagsUnder(node: ts.Node): Set<string> {
+  const found = new Set<string>()
+  const visit = (n: ts.Node) => {
+    if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) {
+      const tag = tagText(n.tagName)
+      if (tag && /^[A-Z]/.test(tag)) found.add(tag)
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(node)
+  return found
+}
+
+/**
+ * For each name a file declares at its top (a function, a `const`, a class):
+ * the tags drawn inside it, with the file's own functions it draws followed, so
+ * what is left are names the file imports or declares without a body.
+ */
+export function drawnIn(sf: ts.SourceFile): Map<string, Set<string>> {
+  const direct = new Map<string, Set<string>>()
+  for (const statement of sf.statements) {
+    if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) direct.set(statement.name.text, tagsUnder(statement))
+    else if (ts.isVariableStatement(statement)) {
+      for (const d of statement.declarationList.declarations) if (ts.isIdentifier(d.name) && d.initializer) direct.set(d.name.text, tagsUnder(d.initializer))
+    }
+  }
+  const closed = new Map<string, Set<string>>()
+  for (const name of direct.keys()) {
+    const out = new Set<string>()
+    const seen = new Set([name])
+    const stack = [name]
+    while (stack.length) {
+      for (const tag of direct.get(stack.pop() as string) ?? []) {
+        out.add(tag)
+        if (direct.has(tag) && !seen.has(tag)) {
+          seen.add(tag)
+          stack.push(tag)
+        }
+      }
+    }
+    closed.set(name, out)
+  }
+  return closed
+}
+
+/** The tags an expression hands back at its top: both sides of a condition, never a fragment's children. */
+function rootsOfExpression(e: ts.Node | undefined, out: Set<string>): void {
+  if (!e) return
+  if (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isSatisfiesExpression(e) || ts.isNonNullExpression(e)) return rootsOfExpression(e.expression, out)
+  if (ts.isConditionalExpression(e)) {
+    rootsOfExpression(e.whenTrue, out)
+    rootsOfExpression(e.whenFalse, out)
+    return
+  }
+  if (ts.isBinaryExpression(e)) {
+    if (e.operatorToken.kind !== ts.SyntaxKind.AmpersandAmpersandToken) rootsOfExpression(e.left, out)
+    rootsOfExpression(e.right, out)
+    return
+  }
+  // A fragment is several things side by side (a page and the dialog it opens):
+  // the part is none of them alone.
+  if (ts.isJsxFragment(e)) return
+  const tag = ts.isJsxElement(e) ? tagText(e.openingElement.tagName) : ts.isJsxSelfClosingElement(e) ? tagText(e.tagName) : null
+  if (tag && /^[A-Z]/.test(tag)) out.add(tag)
+}
+
+/** The tags a function hands back: every `return`, or an arrow's body, never a nested function's. */
+function rootsOfFunction(fn: ts.Node): Set<string> {
+  const out = new Set<string>()
+  if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body)) rootsOfExpression(fn.body, out)
+  const visit = (n: ts.Node) => {
+    if (n !== fn && (ts.isFunctionLike(n) || ts.isClassLike(n))) return
+    if (ts.isReturnStatement(n)) rootsOfExpression(n.expression, out)
+    ts.forEachChild(n, visit)
+  }
+  visit(fn)
+  return out
+}
+
+/** The function a declaration's value is: itself, or the one inside `forwardRef(…)`, `memo(…)`. */
+function functionOf(node: ts.Node | undefined): ts.Node | undefined {
+  if (!node) return undefined
+  if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node)) return node
+  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return functionOf(node.expression)
+  if (ts.isCallExpression(node)) for (const argument of node.arguments) {
+    const fn = functionOf(argument)
+    if (fn) return fn
+  }
+  return undefined
+}
+
+/**
+ * For each function a file declares at its top: the parts it **is** — the tags it
+ * hands back at its root, following the file's own functions it hands back.
+ * `ConfirmDialog` returns a `DialogShell`, so it is one; a page with a menu
+ * somewhere in it is not a menu.
+ */
+export function rootsIn(sf: ts.SourceFile): Map<string, Set<string>> {
+  const direct = new Map<string, Set<string>>()
+  for (const statement of sf.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.name) direct.set(statement.name.text, rootsOfFunction(statement))
+    else if (ts.isVariableStatement(statement)) {
+      for (const d of statement.declarationList.declarations) {
+        const fn = functionOf(d.initializer)
+        if (ts.isIdentifier(d.name) && fn) direct.set(d.name.text, rootsOfFunction(fn))
+      }
+    }
+  }
+  const closed = new Map<string, Set<string>>()
+  for (const name of direct.keys()) {
+    const out = new Set<string>()
+    const seen = new Set([name])
+    const stack = [name]
+    while (stack.length) {
+      for (const tag of direct.get(stack.pop() as string) ?? []) {
+        if (direct.has(tag)) {
+          if (!seen.has(tag)) {
+            seen.add(tag)
+            stack.push(tag)
+          }
+        } else out.add(tag)
+      }
+    }
+    closed.set(name, out)
+  }
+  return closed
+}
+
+/** Each imported value name → where it came from. */
+export function importsOf(sf: ts.SourceFile): Map<string, { specifier: string; imported: string }> {
+  const out = new Map<string, { specifier: string; imported: string }>()
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue
+    const clause = statement.importClause
+    if (!clause || clause.isTypeOnly) continue
+    const specifier = statement.moduleSpecifier.text
+    if (clause.name) out.set(clause.name.text, { specifier, imported: 'default' })
+    const bindings = clause.namedBindings
+    if (bindings && ts.isNamedImports(bindings)) for (const e of bindings.elements) if (!e.isTypeOnly) out.set(e.name.text, { specifier, imported: (e.propertyName ?? e.name).text })
+  }
+  return out
+}

package/src/registry/build.ts

@@ -19,6 +19,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import ts from 'typescript'
 import { OWNED_BEHAVIOURS } from '../eslint/index'
+import { asBehaviours, baseUiBehaviours, drawnIn, handedOn, importsOf, isBaseUi, rootsIn, splitTag } from './behaviours'
 import { looksOf, parseForLooks } from '../eslint/looks-of'
 import { SCHEMA_VERSION, type EntryBehaviour, type EntryKind, type EntryProp, type EntryVariant, type Registry, type RegistryEntry } from './schema'
 
@@ -654,6 +655,41 @@ export function buildRegistry({ root = process.cwd(), repo = 'estiva-ui' }: Buil
 
   if (problems.length) throw new Error(`the registry cannot be built:\n  ${problems.join('\n  ')}`)
 
+  // What each part owns, from what it draws (B9): the Base UI parts in it, and
+  // every part of the package inside it, followed; UIG-8's list is the floor.
+  const moduleByName = new Map(values.map((v) => [v.name, v.module]))
+  const drawing = new Map<string, { drawn: Map<string, Set<string>>; roots: Map<string, Set<string>>; imports: ReturnType<typeof importsOf> }>()
+  const drawingOf = (moduleName: string) => {
+    if (!drawing.has(moduleName)) {
+      const file = moduleOf(moduleName).file
+      const sf = ts.createSourceFile(file, readFileSync(join(root, file), 'utf8'), ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+      drawing.set(moduleName, { drawn: drawnIn(sf), roots: rootsIn(sf), imports: importsOf(sf) })
+    }
+    return drawing.get(moduleName)!
+  }
+  const owns = (name: string, seen: Set<string>): Set<string> => {
+    const out = new Set(behavioursOf(name).map((b) => b.id))
+    const moduleName = moduleByName.get(name)
+    if (!moduleName || seen.has(name)) return out
+    seen.add(name)
+    const { drawn, roots, imports } = drawingOf(moduleName)
+    // The Base UI parts it draws, anywhere in it.
+    for (const tag of drawn.get(name) ?? []) {
+      const [local, piece] = splitTag(tag)
+      const from = imports.get(local)
+      if (from && isBaseUi(from.specifier)) for (const id of baseUiBehaviours(from.imported, piece)) out.add(id)
+    }
+    // The parts it is: what it hands back at its root.
+    for (const tag of roots.get(name) ?? []) {
+      const [local] = splitTag(tag)
+      const from = imports.get(local)
+      const part = from?.specifier.startsWith('./') ? from.imported : !from && local !== name ? local : undefined
+      if (part && moduleByName.has(part)) for (const id of handedOn(part, owns(part, seen))) out.add(id)
+    }
+    return out
+  }
+  for (const entry of entries) if (entry.kind === 'component') entry.ownsBehaviours = asBehaviours(owns(entry.name, new Set()))
+
   entries.sort((a, b) => a.name.localeCompare(b.name))
 
   return {

package/src/registry/cli.ts

@@ -278,7 +278,10 @@ async function main(): Promise<number> {
         const registry = await buildApp(root, value('repo'))
         process.stdout.write(`${summary(registry)}\n`)
         // The usage-page contract and the story links (UIG-19): the one copy, run by every app's `gate` job.
-        const broken = contractProblems(registry, root)
+        // A When not may name a part of the package or of this app (B8).
+        const pkg = readPackageRegistry()
+        const known = new Set([...pkg.entries, ...registry.entries].map((e) => e.name))
+        const broken = contractProblems(registry, root, known)
         if (broken.length) {
           process.stderr.write(`${broken.length === 1 ? 'a part breaks' : `${broken.length} parts break`} the usage-page contract:\n  ${broken.join('\n  ')}\n`)
         } else {
@@ -291,9 +294,8 @@ async function main(): Promise<number> {
         const mapped = checkStoryMap(root, registry, linked.headings)
         // What the pages name must still be there (R14): parts under When and When not,
         // and the stories a Seen in line sends a reader to, here or in the package.
-        const pkg = readPackageRegistry()
         const stale = nameProblems(registry, root, {
-          known: new Set([...pkg.entries, ...registry.entries].map((e) => e.name)),
+          known,
           ...(linked.titles ? { titles: linked.titles } : {}),
           packageIds: pkg.entries.flatMap((e) => [e.storyId, e.docsId].filter((id): id is string => Boolean(id))),
         })

package/src/registry/contract.test.ts

@@ -18,7 +18,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { afterAll, describe, expect, it } from 'vitest'
 import { buildAppRegistry } from './app'
-import { contractProblems, hasSeenIn, linkProblems, nameProblems, pageProblem } from './contract'
+import { contractProblems, hasSeenIn, linkProblems, nameProblems, pageProblem, whenNotProblem } from './contract'
 
 const made: string[] = []
 afterAll(() => {
@@ -53,6 +53,8 @@ const PAGE = [
   '',
   'A word.',
   '',
+  'No alternative: a count has only this badge.',
+  '',
   '## How',
   '',
   '```tsx',
@@ -78,7 +80,7 @@ describe('a usage page', () => {
   })
 
   it('fails with its sections out of order', () => {
-    const swapped = PAGE.replace('## When not\n\nA word.\n', '').replace('## What it owns', '## When not\n\nA word.\n\n## What it owns')
+    const swapped = PAGE.replace('## When not\n\nA word.\n\nNo alternative: a count has only this badge.\n', '').replace('## What it owns', '## When not\n\nA word.\n\n## What it owns')
     expect(pageProblem(swapped)).toMatch(/^sections out of order/)
   })
 
@@ -93,6 +95,18 @@ describe('a usage page', () => {
     expect(pageProblem(later)).toBe('no code under "How"')
   })
 
+  // B8: When not names the part to use instead, or says there is none.
+  it('asks When not to name another real part, or to say there is none', () => {
+    const known = new Set(['Badge', 'Once', 'Chip'])
+    const whenNot = (body: string) => PAGE.replace('A word.\n\nNo alternative: a count has only this badge.', body)
+    expect(whenNotProblem(PAGE, ['Badge'], known)).toBeNull()
+    expect(whenNotProblem(whenNot('A word. That is a **Chip**.'), ['Badge'], known)).toBeNull()
+    expect(whenNotProblem(whenNot('- A word.\n\nNo alternative: a count has only this.'), ['Badge'], known)).toBeNull()
+    expect(whenNotProblem(whenNot('A word.'), ['Badge'], known)).toMatch(/^"When not" names no other part/)
+    // Its own name, a name nothing has, and "No alternative:" mid-line do not count.
+    expect(whenNotProblem(whenNot('Not **Badge** twice, nor a `Widget`. See: No alternative: here.'), ['Badge'], known)).not.toBeNull()
+  })
+
   it('reads a Windows checkout', () => {
     expect(pageProblem(PAGE.replace(/\n/g, '\r\n'))).toBeNull()
   })
@@ -136,6 +150,17 @@ describe('an app against the contract', () => {
     expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([])
   })
 
+  it("links a part with no story to its page by the page's title, and names one that links to nothing (B10)", () => {
+    const seen = PAGE.replace('A small count beside a name.\n', 'A small count beside a name.\n\n**Seen in** — *Parts/Card*, beside the title.\n')
+    const dir = app({ 'src/Badge.tsx': part('Badge'), 'src/Badge.mdx': seen })
+    const registry = buildAppRegistry({ root: dir, repo: 'fixture' })
+    expect(registry.entries.find((e) => e.name === 'Badge')).toMatchObject({ docsId: 'parts-badge--docs', storyId: null })
+    writeFileSync(join(dir, 'src/Badge.mdx'), seen.replace("<Meta title='Parts/Badge' />", '<Meta />'))
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([
+      'Badge (reusable, src/Badge.tsx) links to nothing in Storybook: give src/Badge.mdx a `<Meta title="…" />`, or give the part a story',
+    ])
+  })
+
   it("counts a story file named after the part that draws its view, from the part's own file", () => {
     const dir = app({
       'src/Panel.tsx': `${part('Panel')}\n/** The half that only draws. */\nexport function PanelView() {\n  return <div>view</div>\n}\n`,

package/src/registry/contract.ts

@@ -87,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
@@ -103,9 +103,16 @@ 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
 }
@@ -118,8 +125,26 @@ const toStoryId = (title: string) =>
     .replace(/^-+|-+$/g, '')
 
 /** The names a page's section writes as a part: bold or in backticks, starting with a capital. */
-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])
+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'
 }
 
 /**

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

@@ -45,16 +45,16 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 87 names over 57 files: 80 components, 6 helpers and 1 hook (Lightbox joined in UIG-35)', () => {
+  it('counts 88 names over 58 files: 81 components, 6 helpers and 1 hook (Panel joined on 26 September)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 80, helper: 6, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(57)
+    expect(kinds).toEqual({ component: 81, helper: 6, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(58)
   })
 
   it('gives every entry a purpose, from its own page or from the comment above it', () => {
     expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
-    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(57)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(58)
     expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(30)
   })
 
@@ -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/stories/Choosing.mdx

@@ -75,7 +75,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | 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` |
+| The bar across the top of a column: its title, and the buttons that act on the whole column | **ContainerHeader** — inside the package's columns; in an app, the header comes with **Panel** or **ListColumn** |
 | 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 |
@@ -115,11 +115,12 @@ the **floating** TopBar goes with the **Rail** and the content card.
 | 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 |
+| A panel of a page that is not a list — details, a thread, what is open — with a body that must never be cut off | **Panel** — a header, a body that scrolls whenever it is taller, and a `footer` that stays put |
 
 ## 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 beyond the list column (**ListColumn**) and a column's bar
-  (**ContainerHeader**) — split views, side rails — not here yet.
+- Page layouts beyond the list column (**ListColumn**) and a panel
+  (**Panel**) — split views, side rails — not here yet.