@krapwoo/ds-viewer 0.10.0 → 0.11.0

package/README.md

@@ -445,6 +445,88 @@ path. For anything beyond a single list of tokens, use the token-page layouts be
   declared in another component's folder, such as a shared `IconName`, is that component's
   options, so a Banner page never needs one example per icon.
 
+### Family pages
+
+A page can document a family of related declarations — a view and its internal parts, or a
+pattern and the pieces it's built from — on one page instead of scattering them across separate
+catalog pages, each member getting its own address and search entry. Give it `members`, `whole`
+and `sections` instead of `component`/`whenToUse`/`a11y`/specimens, which live on the members (the
+whole is a member too):
+
+```tsx
+export default defineCatalogPage({
+  id: 'Toast', group: 'Patterns', description: 'How a Toast is assembled from a Banner.',
+  whole: 'Toast',
+  sections: [
+    { label: 'Parts', kind: 'blocks', inWhole: true, members: ['ToastBanner'] },
+    { label: 'Related', kind: 'blocks', inWhole: false, members: ['ToastStandaloneBanner'] },
+  ],
+  members: [
+    { id: 'Toast', source: 'components/Toast/Toast.tsx:1', fidelity: 'documentation-only', relationship: 'Main pattern', description: '...' },
+    {
+      id: 'ToastBanner', component: 'Banner', parent: 'Toast',
+      source: 'components/Banner/Banner.tsx:28', fidelity: 'replicated', relationship: 'Anatomy', description: '...',
+      whenToUse: '...', a11y: '...', variants: { items: [/* ... */] },
+    },
+    {
+      id: 'ToastStandaloneBanner', source: 'components/Banner/Banner.tsx:28', fidelity: 'documentation-only', relationship: 'Related',
+      related: 'Wraps ToastBanner directly when a notice should stay until dismissed.', description: '...', aliases: ['BannerStandalone'],
+    },
+  ],
+});
+```
+
+- **`whole`** is a member id, and must equal the page's own `id`. It renders first, with no header
+  of its own (the page title already names it) and no number.
+- **`sections`** (`{ label, kind: 'blocks' | 'list', inWhole, members }`) group the rest: `blocks`
+  renders each member as its own full block (specimens and all); `list` renders one card of folded
+  rows, each a toggle that expands in place. `inWhole` sections render under the page's one
+  "Parts" label; the rest render under its one "Related" label — the only two section labels the
+  page ever shows; each section's own `label` stays in the data (for the anatomy legend and your
+  own reference) but is never rendered. Numbering follows each member's own `parent` (below), not
+  this ordering.
+- **`parent`** nests a member under another (e.g. a subview under its view). A top-level part (an
+  `inWhole` member whose `parent` is the whole, or who has no `parent` at all) is numbered `1`,
+  `2`, `3`… in the order it's first listed across `sections`; a child takes its parent's number
+  plus `.1`, `.2`, … the same way. A Related member (outside every `inWhole` section) gets no
+  number at all.
+- **`anatomy`** (page-level) is the first box after the page head, labeled “Anatomy” like the
+  specimen grids: `{ picture, groups }`, where each group is
+  `{ label, items: [{ member, description } | { other, description }] }`. A `member` item names one
+  of this page's own members (not the whole) and is numbered to match its Part; an `other` item
+  names a component documented elsewhere, shows an unnumbered ↗ pin, and links only when the name
+  resolves to a real catalog address. With six items or fewer the legend sits beside `picture`;
+  with more it goes below it in up to three columns, each group placed in the currently shortest
+  column so the columns end nearly level (a group never splits). Mark `picture` with
+  `<AnatomyPin member="ThatMemberId" />` (its number and style come from the page, so `picture`
+  never hardcodes one) or `<AnatomyPin other="ThatComponent" />`.
+- **`axis`** on a `variants` or `states` slot names the one property that grid varies (e.g.
+  `'Expression'`) and shows as the grid's label. Family pages hide the generic block labels, so
+  give each grid an `axis` there.
+- **`fidelity`** (`'replicated' | 'approximated' | 'documentation-only'`) shows as a small badge.
+  Use `'documentation-only'` for a member with no rendered specimen (no native counterpart to show,
+  or nothing meaningfully different to render).
+- **`related`** is a short sentence for a member outside the whole (e.g. "Wraps X directly …");
+  another member's name inside it becomes a link to that member's own address. **`aliases`** (on a
+  member, or on the page itself) resolve old/retired ids to the right address, for both routing and
+  search — on the page itself, this only takes effect when the page also has `members`; it's
+  accepted but unused on a normal (single-component) page.
+- **`composedOf`** on a member — same shape and meaning as the page-level field above — shows as
+  one "Uses …" line inside the member's own disclosure, after any notes. A name links when it
+  resolves to a real catalog address (a page, another member, or an alias — in this family or any
+  other), otherwise it shows in code; an unknown name logs a `[Catalog]` warning the same way the
+  page-level field's does.
+- **`notShown`** (page-level) is a short "Not shown in the browser: …" line under the page head,
+  for behavior a web catalog can't demonstrate (a timer, a native gesture). A member's own
+  `notShown` works the same way, under its specimens. Like `aliases`, the page-level field only
+  takes effect on a page with `members`.
+- **`apiLabel`** (default `'API'`) renames the disclosure's reference-excerpt part for a host app
+  that generates one (e.g. `'Swift API'`) — never hardcode a specific language's wording. Also
+  only takes effect on a page with `members`.
+- Every component-bound member (one with `component` set) wants a real `whenToUse`, a real `a11y`,
+  and at least one specimen, the same as a normal page's component — `doctor` checks each one.
+  See `viewer-host/viewer-pages/FamilyPage.catalog.tsx` in this repo for a complete, worked example.
+
 ### Token pages
 
 A token page shows each token at its real value with its role. Pick the layout by the token's

package/dist/cli/doctor.js

@@ -7,6 +7,7 @@ import { importedNames, readStaticPages } from "./staticPage.js";
 import { resolveGlob } from "./glob.js";
 import { sync } from "./sync.js";
 import { gridColumnLimit } from "../native/catalog/comparison.js";
+import { validateComposedOf, validateFamily } from "../native/catalog/pageApi.js";
 function issue(fields) {
     return fields;
 }
@@ -18,9 +19,14 @@ function pageRef(page) {
  *  own file (design §2; the viewer already applies this same default via `page.component ??
  *  page.id`, and the generated page index already defaults a missing `id` to the file stem). A
  *  page from a standalone `pages` glob is never touched — `componentFolders` only ever contains
- *  folders resolved from `config.components`, so a standalone page's own folder is never a member. */
+ *  folders resolved from `config.components`, so a standalone page's own folder is never a member.
+ *  A family page (non-empty `members`) is also never touched — same exemption the runtime applies
+ *  at `pageApi.ts`'s `buildCatalogSections` (`page.members && page.members.length > 0` skips the
+ *  `page.component ?? page.id` fallback entirely): a family's own guidance/examples always live on
+ *  its members, never on the page itself, so a documentation-only whole (its file stem naming no
+ *  real component export) must never be assigned one here either. */
 export function applyComponentDefaults(pages, componentFolders) {
-    return pages.map((page) => page.component === undefined && componentFolders.has(path.dirname(page.file))
+    return pages.map((page) => page.component === undefined && componentFolders.has(path.dirname(page.file)) && !(page.members && page.members.length > 0)
         ? { ...page, component: resolvePageId(page, page.file) }
         : page);
 }
@@ -59,12 +65,22 @@ function pageHasExamples(page) {
 }
 function checkComponentNoExamples(pages, components) {
     const byComponent = new Map();
+    // Plan V3: "a component documented only as a member counts as documented" — any family member
+    // naming a component (regardless of which page, or whether that specific member has its own
+    // examples — a member with none gets its own `component-no-examples` from `checkFamilyMembers`
+    // instead) is enough to clear the component-wide "no catalog page at all" half of this rule.
+    const documentedByMember = new Set();
     for (const page of pages) {
         if (page.component)
             byComponent.set(page.component, [...(byComponent.get(page.component) ?? []), page]);
+        for (const member of page.members ?? [])
+            if (member.component)
+                documentedByMember.add(member.component);
     }
     return components
         .filter((c) => {
+        if (documentedByMember.has(c.name))
+            return false;
         const componentPages = byComponent.get(c.name) ?? [];
         // A not-statically-checkable page is given the benefit of the doubt here — it might have
         // real examples this reader simply couldn't read (Global Constraint: never a partial read;
@@ -83,6 +99,152 @@ function checkComponentNoExamples(pages, components) {
         });
     });
 }
+/** Plan V3: the same two advisories `checkComponentPages` gives a page-level `component` —
+ *  missing guidance/accessibility, and no examples — evaluated per component-bound member of a
+ *  family page instead, with the member id in the message. A documentation-only member (no
+ *  `component`) is exempt from all three. V2c item 9: a member whose `component` no longer
+ *  resolves to a real export gets its own `component-export-removed` error here (below), naming
+ *  the member, instead of being silently exempted. */
+function checkFamilyMembers(pages, components) {
+    const componentsByName = new Map(components.map((c) => [c.name, c]));
+    const issues = [];
+    for (const page of pages) {
+        // V2c item 6: the same "is this really a family page" predicate the runtime uses
+        // (`pageApi.ts`'s `page.members && page.members.length > 0`) — an empty `members` array is a
+        // normal, single-component page, never a family.
+        if (!page.members || page.members.length === 0 || !page.checkable)
+            continue; // never a partial read — see checkGridAxisKeys's own note.
+        const ref = pageRef(page);
+        // Members in a `list` section render as folded rows without specimens, so asking them for
+        // examples would contradict `family-invalid`'s list-section rule.
+        const listMemberIds = new Set((page.sections ?? []).filter((s) => s.kind === 'list').flatMap((s) => s.members));
+        for (const member of page.members) {
+            if (!member.component)
+                continue; // documentation-only — exempt.
+            // V2c item 9: a member naming a component that no longer exists — reported here rather than
+            // silently exempted from every advisory (its props would also silently vanish at runtime).
+            if (!componentsByName.has(member.component)) {
+                issues.push(issue({
+                    id: 'component-export-removed', severity: 'error', ...ref,
+                    message: `Member "${member.id}" documents "${member.component}", which no longer exists as a component export.`,
+                    fix: `Delete this member, or update its "component" to the export's new name.`,
+                }));
+                continue;
+            }
+            if (!member.hasWhenToUse) {
+                issues.push(issue({
+                    id: 'missing-guidance-or-a11y', severity: 'warning', ...ref,
+                    message: `Member "${member.id}": no "whenToUse" guidance documented.`,
+                    fix: `Add a one-sentence whenToUse note for "${member.id}", or omit it only when there genuinely is none.`,
+                }));
+            }
+            if (!member.hasA11y) {
+                issues.push(issue({
+                    id: 'missing-guidance-or-a11y', severity: 'warning', ...ref,
+                    message: `Member "${member.id}": no "a11y" notes documented.`,
+                    fix: `Add a one-sentence a11y note for "${member.id}", grounded in its real behavior.`,
+                }));
+            }
+            if (!member.hasExamples && !listMemberIds.has(member.id)) {
+                issues.push(issue({
+                    id: 'component-no-examples', severity: 'warning', ...ref,
+                    message: `Member "${member.id}" ("${member.component}") has no variants, states, or comparison — it will show no specimen.`,
+                    fix: `Add variants/states/comparison to the "${member.id}" member.`,
+                }));
+            }
+        }
+    }
+    return issues;
+}
+/** Plan V3's `family-invalid`: reuses `native/catalog/pageApi.ts`'s own `validateFamily` —
+ *  the exact same rule `pageApi.ts`'s `buildCatalogSections` runs at runtime — against every
+ *  checkable family page, with the same catalog-wide "every other page/member id" contract that
+ *  function already takes. N3: `StaticPage.sections` already carries each section's real
+ *  `label`/`kind`, so `validateFamily`'s messages name the real section (never an empty label),
+ *  and its N6 list-section rule can tell a `list` section from a `blocks` one. */
+function checkFamilyValidity(pages) {
+    // V2c item 6: `members.length > 0`, the same predicate the runtime uses — an empty array is not
+    // a family page.
+    const familyPages = pages.filter((p) => p.members && p.members.length > 0 && p.checkable);
+    const allPageIds = new Set(pages.map((p) => resolvePageId(p, p.file)));
+    const familyIdsByPageId = new Map();
+    for (const page of familyPages) {
+        const id = resolvePageId(page, page.file);
+        const ids = new Set();
+        for (const member of page.members ?? []) {
+            ids.add(member.id);
+            for (const alias of member.aliases ?? [])
+                ids.add(alias);
+        }
+        for (const alias of page.aliases ?? [])
+            ids.add(alias);
+        familyIdsByPageId.set(id, ids);
+    }
+    const issues = [];
+    for (const page of familyPages) {
+        const id = resolvePageId(page, page.file);
+        const otherPageIds = new Set([...allPageIds].filter((pageId) => pageId !== id));
+        const otherMemberIds = new Set();
+        for (const [pageId, ids] of familyIdsByPageId)
+            if (pageId !== id)
+                for (const memberId of ids)
+                    otherMemberIds.add(memberId);
+        const pageLike = {
+            id,
+            whole: page.whole,
+            // `inWhole` is never read by `validateFamily` — only `label`/`kind`/`members` matter here.
+            sections: page.sections?.map((s) => ({ ...s, inWhole: true })),
+            members: (page.members ?? []).map((m) => ({ id: m.id, parent: m.parent, aliases: m.aliases, hasSpecimens: m.hasExamples })),
+            aliases: page.aliases,
+        };
+        for (const message of validateFamily(pageLike, otherPageIds, otherMemberIds)) {
+            issues.push(issue({ id: 'family-invalid', severity: 'error', ...pageRef(page), message, fix: 'Fix the family\'s members/whole/sections to satisfy the rule above.' }));
+        }
+    }
+    return issues;
+}
+/** V2d item 5: resolves each family member's own `composedOf` the same way `buildCatalogSections`
+ *  resolves it at runtime (`native/catalog/pageApi.ts`'s own `validateComposedOf`, imported
+ *  directly — the subpath-import boundary that once made importing that file from `dist/cli/`
+ *  unsafe is gone), against the same known-name universe `checkFamilyValidity` already builds for
+ *  member ids — every real component name, every page id, and every member id across the whole
+ *  catalog — so an unknown name is reported here too, not only ever silently warned in a browser
+ *  console (`npm run check:catalog`). A member whose `composedOf` wasn't itself literally readable
+ *  (`undefined`) has nothing to check — the same "never a partial read" leniency the page-level
+ *  field already gets. Always a warning, the same severity the runtime's own console warning
+ *  carries, never an error. N8: also accepts a member alias and a page-level alias — the same
+ *  universe `FamilyPage`'s own link resolution (`aliasTargets`) already accepts. */
+function checkMemberComposedOf(pages, components) {
+    const knownNames = new Set(components.map((c) => c.name));
+    for (const page of pages)
+        knownNames.add(resolvePageId(page, page.file));
+    for (const page of pages)
+        for (const member of page.members ?? [])
+            knownNames.add(member.id);
+    for (const page of pages)
+        for (const member of page.members ?? [])
+            for (const alias of member.aliases ?? [])
+                knownNames.add(alias);
+    for (const page of pages)
+        for (const alias of page.aliases ?? [])
+            knownNames.add(alias);
+    const issues = [];
+    for (const page of pages) {
+        if (!page.members || page.members.length === 0 || !page.checkable)
+            continue; // V2c item 6's own predicate.
+        const ref = pageRef(page);
+        for (const member of page.members) {
+            for (const message of validateComposedOf(member.composedOf, knownNames)) {
+                issues.push(issue({
+                    id: 'composed-of-unknown', severity: 'warning', ...ref,
+                    message: `Member "${member.id}": ${message}`,
+                    fix: 'Correct the name, or add { component: \'...\', role: \'...\', relationship: \'...\' } for a component/page/member that really does exist.',
+                }));
+            }
+        }
+    }
+    return issues;
+}
 function checkDuplicatePageId(pages) {
     const byId = new Map();
     for (const page of pages) {
@@ -225,7 +387,14 @@ function importsModal(file) {
 }
 /** `overlay-without-device-frame`: a page whose component opens a React Native `Modal` (which
  *  portals to the document body on the web, covering the whole catalog) but whose page imports no
- *  device frame. A page whose imports couldn't be read is skipped, never assumed unframed. */
+ *  device frame. A page whose imports couldn't be read is skipped, never assumed unframed.
+ *  V2c item 3 (CLI side): deliberately exempts a family member's own `component` — this check
+ *  keys off `page.component`/`page.viewerImports` (the page file's own top-level imports), neither
+ *  of which a family page sets; a member naming a Modal-opening component would need its OWN
+ *  device-frame-import evidence, which `cli/staticPage.ts`'s member reader doesn't currently carry.
+ *  Left as a gap rather than guessed at — a family member wrapping a Modal in a device frame is
+ *  rare enough (and the resulting miss only an advisory, never an error) that this is the smallest
+ *  honest fix here. */
 export function checkOverlaysFramed(pages, components, projectRoot) {
     const byName = new Map(components.map((c) => [c.name, c]));
     const issues = [];
@@ -342,6 +511,13 @@ function checkComponentPages(pages, components) {
     for (const page of pages) {
         if (!page.component)
             continue;
+        // Plan V3: a family page's own guidance always lives on its members, never on the page
+        // itself — even if `applyComponentDefaults` (or, in principle, the author) ends up giving it
+        // a page-level `component` matching a real export, this page-level advisory must still defer
+        // entirely to `checkFamilyMembers`'s own per-member one. V2c item 6: `members.length > 0`,
+        // the same predicate the runtime uses — an empty array is not a family page.
+        if (page.members && page.members.length > 0)
+            continue;
         if (!page.checkable)
             continue; // never a partial read — see checkGridAxisKeys's own note.
         const component = componentsByName.get(page.component);
@@ -519,6 +695,9 @@ export function collectIssues(pages, components) {
         ...checkMissingComposition(pages, components),
         ...checkMissingWorkingPreview(pages, components),
         ...checkPreviewOnlyPages(pages),
+        ...checkFamilyMembers(pages, components),
+        ...checkFamilyValidity(pages),
+        ...checkMemberComposedOf(pages, components),
     ];
 }
 /** Issues that aren't tied to one page: `sync`'s own "Could not read" warnings, and a configured

package/dist/cli/staticPage.js

@@ -200,8 +200,137 @@ function readStaticPage(file) {
                 page.internalProps = names;
         }
     }
+    const membersProp = findProp(pageObject, 'members');
+    if (membersProp) {
+        const members = readFamilyMembers(membersProp.initializer, consts, gridNames, sourceFile);
+        if (!members)
+            page.checkable = false;
+        else
+            page.members = members;
+    }
+    const wholeProp = findProp(pageObject, 'whole');
+    if (wholeProp) {
+        const whole = stringLiteral(resolve(wholeProp.initializer, consts, new Set()));
+        if (whole === undefined)
+            page.checkable = false;
+        else
+            page.whole = whole;
+    }
+    const sectionsProp = findProp(pageObject, 'sections');
+    if (sectionsProp) {
+        const sectionsRead = readSections(sectionsProp.initializer, consts);
+        if (!sectionsRead)
+            page.checkable = false;
+        else
+            page.sections = sectionsRead;
+    }
+    const aliasesProp = findProp(pageObject, 'aliases');
+    if (aliasesProp) {
+        const aliases = readStringLiteralArray(aliasesProp.initializer, consts);
+        if (!aliases)
+            page.checkable = false;
+        else
+            page.aliases = aliases;
+    }
     return page;
 }
+/** A literal array of string literals (or same-file `const` references to one) — undefined for
+ *  anything else, including an array containing even one non-literal element. */
+function readStringLiteralArray(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const items = [];
+    for (const element of resolved.elements) {
+        const value = stringLiteral(resolve(element, consts, new Set()));
+        if (value === undefined)
+            return undefined;
+        items.push(value);
+    }
+    return items;
+}
+/** Plan V3 / V2c item 5: a literal array of `CatalogMember`-shaped object literals, down to just
+ *  the five fields `cli/doctor.ts` needs (`StaticMember`). Undefined for anything that isn't
+ *  itself a literal array, or whose element isn't an object literal with a literal `id` — the
+ *  same "never a partial read" contract every other array reader here already follows.
+ *  `hasExamples` reuses the same item-reading helpers (`readSlotItems`/`readComparison`) the
+ *  page level uses, rather than a presence-only check — a member authored with `variants: {
+ *  items: [] }` has no real specimen to show, the same way a page-level empty list doesn't.
+ *  N1: a member's own `variants`/`states`/`comparison` follows the exact same "never a partial
+ *  read" contract the page level already does (`readStaticPage`'s own `page.checkable = false`
+ *  for the same three fields) — a non-literal slot or an unreadable comparison makes the whole
+ *  members array (and so the whole page) not checkable, rather than silently reading as "no
+ *  specimen" and firing a confidently false `component-no-examples`. */
+function readFamilyMembers(node, consts, gridNames, sourceFile) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const members = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const id = propertyStringLiteral(resolvedElement, 'id', consts);
+        if (id === undefined)
+            return undefined;
+        const component = propertyStringLiteral(resolvedElement, 'component', consts);
+        const parent = propertyStringLiteral(resolvedElement, 'parent', consts);
+        const aliasesProp = findProp(resolvedElement, 'aliases');
+        const aliases = aliasesProp ? readStringLiteralArray(aliasesProp.initializer, consts) : undefined;
+        const composedOfProp = findProp(resolvedElement, 'composedOf');
+        const composedOf = composedOfProp ? readComposedOf(composedOfProp.initializer, consts) : undefined;
+        const variants = readSlotItems(findProp(resolvedElement, 'variants'), consts, component, sourceFile);
+        if (!variants.checkable)
+            return undefined;
+        const states = readSlotItems(findProp(resolvedElement, 'states'), consts, component, sourceFile);
+        if (!states.checkable)
+            return undefined;
+        const comparisonProp = findProp(resolvedElement, 'comparison');
+        let comparison;
+        if (comparisonProp) {
+            comparison = readComparison(comparisonProp.initializer, consts, gridNames);
+            if (!comparison)
+                return undefined;
+        }
+        members.push({
+            id,
+            component,
+            parent,
+            aliases,
+            composedOf,
+            hasWhenToUse: findProp(resolvedElement, 'whenToUse') !== undefined,
+            hasA11y: findProp(resolvedElement, 'a11y') !== undefined,
+            hasExamples: Boolean(variants.items?.length) || Boolean(states.items?.length) || Boolean(comparison),
+        });
+    }
+    return members;
+}
+/** Plan V3 / N3: `CatalogPageInput.sections`, read down to `label`/`kind`/`members` — undefined
+ *  (not checkable) for anything that isn't itself a literal array, or whose element isn't an
+ *  object literal with a literal `label`, a literal `kind` of `'blocks'`/`'list'`, and a literal
+ *  `members` array. */
+function readSections(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const sections = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const label = propertyStringLiteral(resolvedElement, 'label', consts);
+        const kindProp = findProp(resolvedElement, 'kind');
+        const kind = kindProp ? stringLiteral(resolve(kindProp.initializer, consts, new Set())) : undefined;
+        const membersProp = findProp(resolvedElement, 'members');
+        if (label === undefined || (kind !== 'blocks' && kind !== 'list') || !membersProp)
+            return undefined;
+        const members = readStringLiteralArray(membersProp.initializer, consts);
+        if (!members)
+            return undefined;
+        sections.push({ label, kind, members });
+    }
+    return sections;
+}
 /** A literal array of `ComposedOfEntry`-shaped object literals, read down to just `component`
  *  (design §4: role/relationship are authored prose `doctor` never needs for its missing-
  *  composition comparison). Undefined — not an empty array — for anything that isn't itself a

package/dist/native/catalog/catalogNavigation.js

@@ -33,15 +33,20 @@ export function neighbors(order, id) {
         next: index < order.length - 1 ? order[index + 1] : null,
     };
 }
-/** Sidebar filter: case-insensitive substring match, sorted ids, empty groups removed. */
+/** Sidebar filter: case-insensitive substring match, sorted ids, empty groups removed. A page
+ *  matches on its id, its title, or (spec §5.3) any of its family's member ids or aliases. */
 export function filterGroups(groups, query, 
 /** Display titles by id; a page matches on its id or its title. */
-labels) {
+labels, 
+/** Every member id/alias a family page's members use, by page id. */
+memberIds) {
     const q = query.trim().toLowerCase();
     return groups
         .map((group) => ({
         label: group.label,
-        ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q) || (labels?.get(id)?.toLowerCase().includes(q) ?? false)) : group.ids),
+        ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q)
+            || (labels?.get(id)?.toLowerCase().includes(q) ?? false)
+            || (memberIds?.get(id)?.some((memberId) => memberId.toLowerCase().includes(q)) ?? false)) : group.ids),
     }))
         .filter((group) => group.ids.length > 0);
 }
@@ -109,6 +114,60 @@ export function resolveActiveFromHash(hash, order) {
         return UPDATE_PAGE_ID;
     return idFromHash(hash, order);
 }
+/** Every member id other than the whole, every member alias, and every family page's own
+ *  (page-level) alias, mapped to where it resolves (spec §5.3 "Old addresses"). Pages without a
+ *  `family` contribute nothing. */
+export function aliasTargets(sections) {
+    const targets = new Map();
+    for (const section of sections) {
+        const family = section.family;
+        if (!family)
+            continue;
+        for (const member of family.members) {
+            if (member.id === family.whole)
+                continue;
+            targets.set(member.id, { pageId: section.id, memberId: member.id });
+            for (const alias of member.aliases ?? [])
+                targets.set(alias, { pageId: section.id, memberId: member.id });
+        }
+        for (const alias of family.aliases ?? [])
+            targets.set(alias, { pageId: section.id });
+    }
+    return targets;
+}
+export function resolveRoute(hash, order, aliases) {
+    const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+    if (raw === '')
+        return { kind: 'empty' };
+    let decoded;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        return { kind: 'notFound', raw };
+    }
+    if (decoded === UPDATE_PAGE_ID)
+        return { kind: 'update' };
+    if (order.includes(decoded))
+        return { kind: 'page', id: decoded };
+    const target = aliases.get(decoded);
+    if (target) {
+        if (target.memberId !== undefined)
+            return { kind: 'member', pageId: target.pageId, memberId: target.memberId };
+        return { kind: 'page', id: target.pageId };
+    }
+    return { kind: 'notFound', raw: decoded };
+}
+/** Member search hits (spec §5.3 "Search"): every entry whose member id or alias contains the
+ *  query, case-insensitively. The label is always the member id — the Swift declaration name. */
+export function searchResults(entries, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    return entries
+        .filter((entry) => entry.memberId.toLowerCase().includes(q) || (entry.aliases ?? []).some((alias) => alias.toLowerCase().includes(q)))
+        .map((entry) => ({ pageId: entry.pageId, memberId: entry.memberId, label: entry.memberId, familyTitle: entry.familyTitle }));
+}
 /** Design §5: "Major: ... dismissible per version; the footer line remains." `dismissedVersion`
  *  is whatever a previous dismissal recorded (`CatalogShell`'s own `localStorage` read, Task 14) —
  *  any value other than the *current* `update.latest` (including `null`, or an older dismissed

package/dist/native/catalog/comparison.js

@@ -257,18 +257,28 @@ export function presentationBlocks(def, options = {}) {
                 title: `${def.comparison.rowLabel} × ${def.comparison.columnLabel}`,
                 size: def.comparison.size ?? def.specimenSize ?? 'regular',
                 comparison: def.comparison,
+                // A3: `comparison` replaces the Variants list, but `def.variants.axis` (if still set) is
+                // the only axis label a grid has to carry onto a family page, which hides generic titles.
+                ...(def.variants?.axis ? { axis: def.variants.axis } : {}),
             });
         }
         else if (grouped && def.variants) {
             // Grouped rows place several cells beside a row header, so full-width (itemsFill) slots do
             // not force 402px cells here; a cell's own `fill` still stretches its specimen.
-            blocks.push({ kind: 'grouped', title: 'Variant × configuration', size: def.specimenSize ?? 'regular', groups: grouped.groups });
+            blocks.push({
+                kind: 'grouped',
+                title: 'Variant × configuration',
+                size: def.specimenSize ?? 'regular',
+                groups: grouped.groups,
+                ...(def.variants.axis ? { axis: def.variants.axis } : {}),
+            });
             states = grouped.leftovers;
         }
         else if (def.variants) {
             blocks.push({
                 kind: 'list',
-                title: 'Variants',
+                title: def.variants.axis ?? 'Variants',
+                ...(def.variants.axis ? { axis: def.variants.axis } : {}),
                 size: slotSize(def, def.variants),
                 items: slotItems(def.variants, 'variants', def.specimenSize === 'page'),
                 ...slotColumnCap(def.variants),
@@ -282,7 +292,8 @@ export function presentationBlocks(def, options = {}) {
         const secondary = blocks.length > 0 && blocks[0].kind !== 'list';
         blocks.push({
             kind: 'list',
-            title: secondary ? 'Other configurations' : 'States / configurations',
+            title: states.axis ?? (secondary ? 'Other configurations' : 'States / configurations'),
+            ...(states.axis ? { axis: states.axis } : {}),
             size: slotSize(def, states),
             items: slotItems(states, 'states', def.specimenSize === 'page'),
             ...slotColumnCap(states),