@krapwoo/ds-viewer 0.12.1 → 0.13.1

package/README.md

@@ -167,6 +167,13 @@ npm run viewer:dev       # opens viewer-host/, the DS Viewer internals catalog (
 
 `check:catalog`, `check:doctor` and `check:types` cover both catalogs.
 
+Three checks cover three different things, and none substitutes for another: `npm test` covers
+pure logic and source assertions; `npm run test:render` renders catalog components into jsdom
+through react-native-web and covers component structure (which element wraps what); `npm run
+check:catalog` is the only one that sees geometry, because jsdom has no layout engine —
+`getBoundingClientRect()` returns zeros there. A layout or alignment claim must be verified in a
+browser, with `check:catalog`, never in a renderer test.
+
 ## Contributing
 
 Found a bug or an improvement while using ds-viewer in your app? Open an issue or a pull request:
@@ -459,6 +466,7 @@ export default defineCatalogPage({
   whole: 'Toast',
   sections: [
     { label: 'Parts', kind: 'blocks', inWhole: true, members: ['ToastBanner'] },
+    // deprecated shape — don't copy this; name a related component in `relatedPages` instead (below).
     { label: 'Related', kind: 'blocks', inWhole: false, members: ['ToastStandaloneBanner'] },
   ],
   members: [
@@ -484,7 +492,18 @@ export default defineCatalogPage({
   "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.
+  this ordering. A non-`inWhole` section is **deprecated**: it still works, but `doctor`'s
+  `deprecated-related-section` now warns about it — give the member its own catalog page and name
+  it in `relatedPages` instead of documenting it inline here. Under `doctor.strict`, this warning
+  becomes an error, so a consumer with existing non-`inWhole` sections sees red CI on upgrade until
+  they migrate.
+- **`relatedPages`** (`{ page, note? }[]`) names other catalog pages at the bottom of this page,
+  under the same "Related" heading, after any deprecated sections. Each row is the named page's own
+  id, linked when it resolves to a real catalog address — a page id, another family's member id, or
+  a family page's own alias or one of its members' aliases — and shown as plain text, never a dead link, when it doesn't
+  (`doctor` reports an unresolvable or self-naming entry either way), then its `note`, when
+  authored — no specimens, disclosure, source line, number, or pin. A page with neither
+  `relatedPages` nor a non-`inWhole` section renders no "Related" heading at all.
 - **`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
@@ -493,8 +512,10 @@ export default defineCatalogPage({
 - **`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
+  of this page's own members (not the whole); it shows that member's Part number, or no pin at all
+  when the member sits outside every `inWhole` section — such a row reserves no gutter for the pin
+  it doesn't have, its name starting flush at the row's own left edge; 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
@@ -642,6 +663,10 @@ Button
     gallery or a whole-page layout.
   - `internal-prop-unknown` — `internalProps` names something that is not a prop of the component,
     so the exemption it was written for is not in effect. Correct the spelling or delete the entry.
+  - `deprecated-related-section` — a family page still documents one or more members inline in a
+    non-`inWhole` section, naming every one of them so you can act without opening the file. Give
+    each its own catalog page and name it in the family's `relatedPages` list instead; the section
+    keeps working until you do.
 
   The catalog also warns at render time when a page under-declares the width its examples need.
   A `PhoneFrame` given a cell narrower than the 375px device scales the whole phone down, and its

package/dist/cli/doctor.js

@@ -168,7 +168,12 @@ function checkFamilyValidity(pages) {
     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) {
+    // I-B (independent review, confirmation pass): built from every page with members, not only
+    // checkable ones — the same precedent `checkMemberComposedOf` above already follows for
+    // `knownNames` (no `checkable` filter). A non-checkable family page still contributes a working
+    // link at runtime (`pageApi.ts`'s `otherMemberIds` has no `checkable` concept either), so
+    // excluding it here turned a valid `relatedPages` entry into a false CI-failing error.
+    for (const page of pages.filter((p) => p.members && p.members.length > 0)) {
         const id = resolvePageId(page, page.file);
         const ids = new Set();
         for (const member of page.members ?? []) {
@@ -192,10 +197,19 @@ function checkFamilyValidity(pages) {
         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 })),
+            // `validateFamily` does read `inWhole` now (`pageApi.ts:277`, C1's narrowing).
+            // `StaticFamilySection.inWhole` is optional (unlike the real `CatalogMemberSection`) only so
+            // hand-built test fixtures don't all need one, so this defaults a missing one to `false` —
+            // the lenient direction (an unreadable `inWhole` must never manufacture a false "has no
+            // number" the day `anatomy` joins the static read) rather than passing `undefined` where
+            // `validateFamily`'s own type expects a boolean.
+            sections: page.sections?.map((s) => ({ ...s, inWhole: s.inWhole ?? false })),
             members: (page.members ?? []).map((m) => ({ id: m.id, parent: m.parent, aliases: m.aliases, hasSpecimens: m.hasExamples })),
             aliases: page.aliases,
+            // I2: passed through so an unresolvable or self-naming `relatedPages` entry is reported here
+            // too, the same precedent `checkMemberComposedOf` below already follows for `composedOf` —
+            // not only ever silently warned in a browser console (`npm run check:catalog`).
+            relatedPages: page.relatedPages,
         };
         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.' }));
@@ -203,6 +217,31 @@ function checkFamilyValidity(pages) {
     }
     return issues;
 }
+/** Deprecation (`relatedPages`): a family page still using one or more non-`inWhole` sections to
+ *  document a merely-related component inline, instead of giving it its own page and naming it in
+ *  the page's `relatedPages` list. One finding per page (never per section), naming every member
+ *  still parked in a deprecated section so the author can act without opening the file. Always a
+ *  warning — `inWhole: false` keeps working. */
+function checkDeprecatedRelatedSections(pages) {
+    const issues = [];
+    for (const page of pages) {
+        if (!page.members || page.members.length === 0 || !page.checkable)
+            continue; // V2c item 6's own predicate.
+        // Strictly `false`, never `!s.inWhole` — a test fixture (or any other caller) that omits
+        // `inWhole` entirely means "not testing this", not "deprecated".
+        const deprecated = (page.sections ?? []).filter((s) => s.inWhole === false);
+        if (deprecated.length === 0)
+            continue;
+        const memberIds = deprecated.flatMap((s) => s.members);
+        const id = resolvePageId(page, page.file);
+        issues.push(issue({
+            id: 'deprecated-related-section', severity: 'warning', ...pageRef(page),
+            message: `Family "${id}" documents ${memberIds.length} member${memberIds.length === 1 ? '' : 's'} (${memberIds.join(', ')}) in a deprecated non-"inWhole" section.`,
+            fix: `Give each of these members its own catalog page, drop the non-"inWhole" section, and name its new page in "${id}"'s relatedPages instead.`,
+        }));
+    }
+    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/`
@@ -698,6 +737,7 @@ export function collectIssues(pages, components) {
         ...checkFamilyMembers(pages, components),
         ...checkFamilyValidity(pages),
         ...checkMemberComposedOf(pages, components),
+        ...checkDeprecatedRelatedSections(pages),
     ];
 }
 /** Issues that aren't tied to one page: `sync`'s own "Could not read" warnings, and a configured

package/dist/cli/staticPage.js

@@ -232,6 +232,9 @@ function readStaticPage(file) {
         else
             page.aliases = aliases;
     }
+    const relatedPagesProp = findProp(pageObject, 'relatedPages');
+    if (relatedPagesProp)
+        page.relatedPages = readRelatedPages(relatedPagesProp.initializer, consts);
     return page;
 }
 /** A literal array of string literals (or same-file `const` references to one) — undefined for
@@ -308,7 +311,10 @@ function readFamilyMembers(node, consts, gridNames, sourceFile) {
 /** 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. */
+ *  `members` array. I1: `inWhole` is read too, but — like `composedOf` — a non-literal `inWhole`
+ *  never costs the section's `label`/`kind`/`members`, so the page stays checkable; it only means
+ *  `checkDeprecatedRelatedSections` has nothing to check for that section (`StaticFamilySection`'s
+ *  own `inWhole?` already reflects this: present only when it was itself a literal). */
 function readSections(node, consts) {
     const resolved = resolve(node, consts, new Set());
     if (!ts.isArrayLiteralExpression(resolved))
@@ -322,12 +328,14 @@ function readSections(node, consts) {
         const kindProp = findProp(resolvedElement, 'kind');
         const kind = kindProp ? stringLiteral(resolve(kindProp.initializer, consts, new Set())) : undefined;
         const membersProp = findProp(resolvedElement, 'members');
+        const inWholeProp = findProp(resolvedElement, 'inWhole');
+        const inWhole = inWholeProp ? literalBooleanOrUnknown(inWholeProp.initializer, consts) : undefined;
         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 });
+        sections.push({ label, kind, members, inWhole });
     }
     return sections;
 }
@@ -352,6 +360,27 @@ function readComposedOf(node, consts) {
     }
     return entries;
 }
+/** A literal array of `RelatedPage`-shaped object literals, read down to just `page` (design
+ *  parity with `readComposedOf`: `note` is authored prose `doctor` never needs). Undefined — not
+ *  an empty array — for anything that isn't itself a literal array, or whose element isn't an
+ *  object literal with a literal `page`: `doctor` must never mistake "couldn't read this" for
+ *  "author declared no related pages here". */
+function readRelatedPages(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const entries = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const page = propertyStringLiteral(resolvedElement, 'page', consts);
+        if (page === undefined)
+            return undefined;
+        entries.push({ page });
+    }
+    return entries;
+}
 /** Local name -> imported name, for every named import from `moduleSpecifier`. */
 export function importedNames(sourceFile, moduleSpecifier) {
     const names = new Map();

package/dist/native/catalog/pageApi.js

@@ -130,11 +130,20 @@ export function validateFamily(page, allPageIds, otherMemberIds) {
         checkId(alias, false);
     // Slice D1 item 3: an anatomy `member` item must name a real, non-whole member of this page, and
     // each member may be pinned to the picture's legend at most once.
-    // D2 item A2: a member item whose member has no number — outside every `inWhole` section, or
-    // under a parent that isn't itself numbered — must also be reported; left unchecked, it renders
-    // a blank 34px pin slot in the legend and nothing at all from `AnatomyPin` in the picture.
+    // D2 item A2, narrowed per review C1: a member item is reported only when it sits inside an
+    // `inWhole` section but still has no number — i.e. its parent isn't itself numbered. Left
+    // unchecked, such a part renders indistinguishably from a Related row and its `AnatomyPin`
+    // renders nothing at all. A member outside every `inWhole` section (Related) is legitimately
+    // unnumbered by design (APPROVED.md: related members have no number) and must not be reported
+    // here.
     if (page.anatomy) {
         const numbered = numberFor(page);
+        const inWholeMemberIds = new Set();
+        for (const section of page.sections ?? []) {
+            if (section.inWhole)
+                for (const id of section.members)
+                    inWholeMemberIds.add(id);
+        }
         const seenAnatomyMembers = new Set();
         for (const group of page.anatomy.groups) {
             for (const item of group.items) {
@@ -153,12 +162,39 @@ export function validateFamily(page, allPageIds, otherMemberIds) {
                     continue;
                 }
                 seenAnatomyMembers.add(item.member);
-                if (!numbered.has(item.member)) {
+                if (inWholeMemberIds.has(item.member) && !numbered.has(item.member)) {
                     issues.push(`Family "${page.id}": anatomy item "${item.member}" has no number.`);
                 }
             }
         }
     }
+    // `relatedPages`: each entry must name a real catalog page, other than this one, and the list
+    // must not repeat a page. An unresolvable or self-naming entry still renders (plain text, never
+    // a dead link), but is always reported here so `doctor` fails in CI. N8: `allPageIds` ∪
+    // `otherMemberIds` is the same universe `FamilyPage`'s own `resolvesAddress` accepts as a
+    // working link — page ids, member ids, and both page-level and member aliases — so an entry
+    // naming another page's alias or another family's member address is accepted too.
+    if (page.relatedPages) {
+        const seenRelatedPages = new Set();
+        for (const entry of page.relatedPages) {
+            if (seenRelatedPages.has(entry.page)) {
+                issues.push(`Family "${page.id}": relatedPages lists "${entry.page}" more than once.`);
+                continue;
+            }
+            seenRelatedPages.add(entry.page);
+            if (entry.page === page.id) {
+                issues.push(`Family "${page.id}": relatedPages entry "${entry.page}" names this page itself.`);
+                continue;
+            }
+            if (byId.has(entry.page)) {
+                issues.push(`Family "${page.id}": relatedPages entry "${entry.page}" is a member of this page, not another page.`);
+                continue;
+            }
+            if (!allPageIds.has(entry.page) && !otherMemberIds.has(entry.page)) {
+                issues.push(`Family "${page.id}": relatedPages entry "${entry.page}" is not a catalog page.`);
+            }
+        }
+    }
     return issues;
 }
 /** Slice D1 item 2: anatomy-first numbering — the only numbering rule for every family page (not
@@ -334,7 +370,7 @@ pages, components, groupOrder) {
                 ...member,
                 hasSpecimens: Boolean(member.variants?.items?.length || member.states?.items?.length || member.comparison),
             }));
-            const issues = validateFamily({ ...page, members, anatomy: page.anatomy }, otherPageIds, otherMemberIds);
+            const issues = validateFamily({ ...page, members, anatomy: page.anatomy, relatedPages: page.relatedPages }, otherPageIds, otherMemberIds);
             if (globalThis.__DEV__) {
                 for (const issue of issues)
                     console.error(`[Catalog] ${issue}`);
@@ -347,6 +383,7 @@ pages, components, groupOrder) {
                 aliases: page.aliases,
                 apiLabel: page.apiLabel,
                 anatomy: page.anatomy,
+                relatedPages: page.relatedPages,
                 members: page.members.map((member) => {
                     const memberComponent = member.component ? componentByName.get(member.component) : undefined;
                     return {

package/native/catalog/FamilyPage.tsx

@@ -26,7 +26,7 @@ import {
   type PartTreeEntry,
   type RelatedSegment,
 } from './familyModel';
-import type { CatalogAnatomy, CatalogAnatomyGroup, CatalogMember, CatalogMemberSection, ComposedOfEntry, FamilyDef, PreviewWidths, PropDef, SectionDef } from './types';
+import type { CatalogAnatomy, CatalogAnatomyGroup, CatalogMember, CatalogMemberSection, ComposedOfEntry, FamilyDef, PreviewWidths, PropDef, RelatedPage, SectionDef } from './types';
 
 /** `SectionDef`'s parts `presentationBlocks`/`Blocks` actually read, built from one family member
  *  so its own specimens render through the exact same renderers (`VariantGroup`, `ComparisonGrid`,
@@ -654,12 +654,46 @@ function FamilySectionGroup({
   );
 }
 
+/** One row of the bottom-of-page `relatedPages` list (field spec, item 3 "Rendering"): the named
+ *  page's own id as a link when it resolves to a real catalog address, plain text when not — never
+ *  a dead link — then its note, when authored. No specimens, no disclosure, no source line, no
+ *  number, no pin. */
+function RelatedPageRow({ entry, resolvesAddress }: { entry: RelatedPage; resolvesAddress: (name: string) => boolean }) {
+  const resolved = resolvesAddress(entry.page);
+  return (
+    <Text style={styles.belowLine}>
+      {resolved ? (
+        <Text role="link" style={styles.relatedPageName} {...({ href: hashForId(entry.page) } as Record<string, unknown>)}>
+          {entry.page}
+        </Text>
+      ) : (
+        <Text style={[styles.relatedPageName, styles.relatedPageNameUnresolved]}>{entry.page}</Text>
+      )}
+      {entry.note ? ` — ${entry.note}` : null}
+    </Text>
+  );
+}
+
+function RelatedPagesList({ items, resolvesAddress }: { items: readonly RelatedPage[]; resolvesAddress: (name: string) => boolean }) {
+  return (
+    <View style={styles.relatedPagesList}>
+      {items.map((entry, i) => (
+        <RelatedPageRow key={i} entry={entry} resolvesAddress={resolvesAddress} />
+      ))}
+    </View>
+  );
+}
+
 /** Slice D1 item 4: the two umbrella labels — "Parts" groups every `inWhole` section, "Related"
- *  every other one. A divider sits above each, and nothing else renders between the authored
- *  sections it covers (item 10: authored `section.label`s stay in the data, never on screen). */
+ *  every other one (plus, on "Related" only, the page's own `relatedPages` list, rendered after
+ *  every deprecated section — field spec item 3: "render the deprecated sections first and the
+ *  links after, under the single Related heading"). A divider sits above each, and nothing else
+ *  renders between the authored sections it covers (item 10: authored `section.label`s stay in the
+ *  data, never on screen). */
 function FamilyLabeledGroup({
   label,
   sections,
+  relatedPages,
   outline,
   byId,
   allMemberIds,
@@ -672,6 +706,8 @@ function FamilyLabeledGroup({
 }: {
   label: 'Parts' | 'Related';
   sections: CatalogMemberSection[];
+  /** Only ever set for the "Related" group — "Parts" has no equivalent. */
+  relatedPages?: RelatedPage[];
   outline: FamilyDef['outline'];
   byId: ReadonlyMap<string, FamilyMember>;
   allMemberIds: readonly string[];
@@ -682,7 +718,9 @@ function FamilyLabeledGroup({
   onToggleRow: (id: string) => void;
   registerNode: (id: string, node: View | null) => void;
 }) {
-  if (sections.length === 0) return null;
+  // Field spec item 3: "a page with no relatedPages and no Related sections renders exactly as it
+  // does today — no heading, no divider, nothing."
+  if (sections.length === 0 && (!relatedPages || relatedPages.length === 0)) return null;
   return (
     <View style={styles.labeledGroup}>
       {/* Spec §5.2 "Heading semantics": "Parts"/"Related" are aria-level 2 headings — one level
@@ -711,6 +749,7 @@ function FamilyLabeledGroup({
             registerNode={registerNode}
           />
         ))}
+        {relatedPages && relatedPages.length > 0 && <RelatedPagesList items={relatedPages} resolvesAddress={resolvesAddress} />}
       </View>
     </View>
   );
@@ -723,8 +762,10 @@ const FamilyAnatomyContext = createContext<{ byId: ReadonlyMap<string, FamilyMem
 
 /** Slice D1 item 5: a pin for use inside `anatomy.picture`. `member` names one of this page's
  *  members and shows its number (dashed when it has no area of its own), looked up through
- *  `FamilyAnatomyContext` — renders nothing for an unknown member, one with no number (D2 item A2:
- *  already a `validateFamily` issue), or outside a family page's own anatomy box (no context).
+ *  `FamilyAnatomyContext` — renders nothing for an unknown member, one outside a family page's own
+ *  anatomy box (no context), or one with no number — the last is a `validateFamily` issue only
+ *  when the member sits inside an `inWhole` section (D2 item A2, narrowed per review C1); for a
+ *  member outside every `inWhole` section it's legal, deliberately silent, and reported by nobody.
  *  `other` marks a component documented on another page with the unnumbered ↗ pin the legend
  *  uses, and always renders it — it needs no context, with or without a family page in scope. */
 export function AnatomyPin({ member, other }: { member?: string; other?: string }) {
@@ -742,12 +783,23 @@ export function AnatomyPin({ member, other }: { member?: string; other?: string
 }
 
 /** Slice D1 item 5: one legend row naming a member of this page — a pin (looked up the same way
- *  `AnatomyPin` does), its name linked to the member's address, and the row's own description. */
+ *  `AnatomyPin` does), its name linked to the member's address, and the row's own description.
+ *  Defect fix (APPROVED.md "the legend is not indented"): the pin's 34px gutter is only reserved
+ *  when there's a pin to show — a member with no number (outside every `inWhole` section) gets no
+ *  gutter either, so its name starts flush at the row's own left edge instead of under blank
+ *  space. */
 function AnatomyMemberRow({ memberId, description, byId, outline }: { memberId: string; description: string; byId: ReadonlyMap<string, FamilyMember>; outline: FamilyDef['outline'] }) {
   const pin = anatomyPinFor(memberId, byId, outline);
   return (
     <View style={styles.legendRow}>
-      <View style={styles.legendPinSlot}>{pin && <Pin number={pin.number} dashed={pin.dashed} />}</View>
+      {pin && (
+        // `testID` exists only so a renderer test can assert the slot's presence without
+        // depending on class names — react-native-web renders it to the DOM as `data-testid`;
+        // native ignores it.
+        <View style={styles.legendPinSlot} testID="legend-pin-slot">
+          <Pin number={pin.number} dashed={pin.dashed} />
+        </View>
+      )}
       <View style={styles.legendBody}>
         <Text role="link" style={styles.legendName} {...({ href: hashForId(memberId) } as Record<string, unknown>)}>
           {memberId}
@@ -759,12 +811,16 @@ function AnatomyMemberRow({ memberId, description, byId, outline }: { memberId:
 }
 
 /** Slice D1 item 5: one legend row naming a component documented elsewhere — never numbered; its
- *  own name links only when it resolves to a real catalog address. */
+ *  own name links only when it resolves to a real catalog address. The ↗ marker keeps its own
+ *  gutter: the defect this slice fixes is a gutter reserved for a pin that *isn't there*, and an
+ *  "other page" row always shows its ↗, so the slot is never blank. Keeping it also keeps
+ *  APPROVED.md's "the description ... starts at the name's left edge" — pulling the marker inline
+ *  instead left each description hanging 26px to the left of its own name. */
 function AnatomyOtherRow({ name, description, resolvesAddress }: { name: string; description: string; resolvesAddress: (name: string) => boolean }) {
   const resolved = resolvesAddress(name);
   return (
     <View style={styles.legendRow}>
-      <View style={styles.legendPinSlot} {...ARIA_HIDDEN}>
+      <View style={styles.legendPinSlot} {...ARIA_HIDDEN} testID="legend-pin-slot">
         <View style={styles.extPin}>
           <Text style={styles.extPinText}>↗</Text>
         </View>
@@ -1025,6 +1081,7 @@ export function FamilyPage<TId extends string>({
       <FamilyLabeledGroup
         label="Related"
         sections={relatedSections}
+        relatedPages={family.relatedPages}
         outline={family.outline}
         byId={byId}
         allMemberIds={allMemberIds}
@@ -1114,6 +1171,10 @@ const styles = StyleSheet.create({
   memberSpecimens: { marginTop: CATALOG_SPACE.sm, marginBottom: CATALOG_SPACE.lg - CATALOG_SPACE.sm },
   belowLine: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted, maxWidth: 700 },
   relatedLink: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.accent },
+  // relatedPages (field spec item 3 "Rendering"): one row per entry, under the Related heading.
+  relatedPagesList: { gap: CATALOG_SPACE.sm },
+  relatedPageName: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.accent },
+  relatedPageNameUnresolved: { color: CATALOG_COLOR.text },
   wholeBelowRow: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.xs, marginTop: CATALOG_SPACE.sm, flexWrap: 'wrap' },
   wholeName: { ...CATALOG_TEXT.codeSmallStrong, color: CATALOG_COLOR.text },
   // V2d item 3: v8's own `.uses` line, inside the disclosure.

package/native/catalog/index.ts

@@ -49,7 +49,7 @@ export type { CatalogPage, CatalogPageInput, GeneratedComponent, GeneratedPropRe
 export type {
   PropDef, SectionDef, NavGroup, SpecimenSize, SpecimenSurfaceKind, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis,
   PreviewWidths, TokenSection, ComposedOfEntry, CatalogMember, CatalogMemberSection, FamilyDef,
-  CatalogAnatomy, CatalogAnatomyGroup, CatalogAnatomyItem,
+  CatalogAnatomy, CatalogAnatomyGroup, CatalogAnatomyItem, RelatedPage,
 } from './types';
 export { UpdatePanel } from './UpdatePanel';
 export { UPDATE_PAGE_ID } from './catalogNavigation';

package/native/catalog/pageApi.ts

@@ -1,5 +1,5 @@
 import type React from 'react';
-import type { CatalogAnatomy, CatalogMember, CatalogMemberSection, ComparisonDef, ComposedOfEntry, NavGroup, PreviewWidths, PropDef, SectionDef, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot } from './types.ts';
+import type { CatalogAnatomy, CatalogMember, CatalogMemberSection, ComparisonDef, ComposedOfEntry, NavGroup, PreviewWidths, PropDef, RelatedPage, SectionDef, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot } from './types.ts';
 
 /** `SectionDef` without the derived fields (`id`/`path`/`props` come from detection and
  *  generated props), plus the three fields design §1 "Page shape" adds. */
@@ -75,6 +75,13 @@ export interface CatalogPageInput<TId extends string = string> {
    *  a picture of the whole with numbered pins and a legend. Only takes effect on a page with
    *  `members`. */
   anatomy?: CatalogAnatomy;
+  /** Other catalog pages worth naming at the bottom of this page, under the "Related" heading,
+   *  rendered after any deprecated non-`inWhole` sections — a component merely related to the
+   *  whole owns its own page rather than being documented inline here. Each entry's `page` must
+   *  resolve to a real catalog page, never this page's own id; `validateFamily` reports both as
+   *  issues, and an entry that still fails to resolve at runtime renders its name as plain text
+   *  instead of a dead link. Only takes effect on a page with `members`. */
+  relatedPages?: RelatedPage[];
 }
 
 export interface CatalogPage<TId extends string = string> extends CatalogPageInput<TId> {
@@ -158,6 +165,8 @@ export interface FamilyPageLike extends FamilyOutlineInput {
    *  decoupled from the full `CatalogAnatomy` type (which carries a `picture` React node this pure
    *  module never touches). */
   anatomy?: FamilyAnatomyLike;
+  /** See `CatalogPageInput.relatedPages`. */
+  relatedPages?: RelatedPage[];
 }
 
 /** Slice D1 item 3. */
@@ -256,11 +265,18 @@ export function validateFamily(page: FamilyPageLike, allPageIds: ReadonlySet<str
 
   // Slice D1 item 3: an anatomy `member` item must name a real, non-whole member of this page, and
   // each member may be pinned to the picture's legend at most once.
-  // D2 item A2: a member item whose member has no number — outside every `inWhole` section, or
-  // under a parent that isn't itself numbered — must also be reported; left unchecked, it renders
-  // a blank 34px pin slot in the legend and nothing at all from `AnatomyPin` in the picture.
+  // D2 item A2, narrowed per review C1: a member item is reported only when it sits inside an
+  // `inWhole` section but still has no number — i.e. its parent isn't itself numbered. Left
+  // unchecked, such a part renders indistinguishably from a Related row and its `AnatomyPin`
+  // renders nothing at all. A member outside every `inWhole` section (Related) is legitimately
+  // unnumbered by design (APPROVED.md: related members have no number) and must not be reported
+  // here.
   if (page.anatomy) {
     const numbered = numberFor(page);
+    const inWholeMemberIds = new Set<string>();
+    for (const section of page.sections ?? []) {
+      if (section.inWhole) for (const id of section.members) inWholeMemberIds.add(id);
+    }
     const seenAnatomyMembers = new Set<string>();
     for (const group of page.anatomy.groups) {
       for (const item of group.items) {
@@ -278,13 +294,41 @@ export function validateFamily(page: FamilyPageLike, allPageIds: ReadonlySet<str
           continue;
         }
         seenAnatomyMembers.add(item.member);
-        if (!numbered.has(item.member)) {
+        if (inWholeMemberIds.has(item.member) && !numbered.has(item.member)) {
           issues.push(`Family "${page.id}": anatomy item "${item.member}" has no number.`);
         }
       }
     }
   }
 
+  // `relatedPages`: each entry must name a real catalog page, other than this one, and the list
+  // must not repeat a page. An unresolvable or self-naming entry still renders (plain text, never
+  // a dead link), but is always reported here so `doctor` fails in CI. N8: `allPageIds` ∪
+  // `otherMemberIds` is the same universe `FamilyPage`'s own `resolvesAddress` accepts as a
+  // working link — page ids, member ids, and both page-level and member aliases — so an entry
+  // naming another page's alias or another family's member address is accepted too.
+  if (page.relatedPages) {
+    const seenRelatedPages = new Set<string>();
+    for (const entry of page.relatedPages) {
+      if (seenRelatedPages.has(entry.page)) {
+        issues.push(`Family "${page.id}": relatedPages lists "${entry.page}" more than once.`);
+        continue;
+      }
+      seenRelatedPages.add(entry.page);
+      if (entry.page === page.id) {
+        issues.push(`Family "${page.id}": relatedPages entry "${entry.page}" names this page itself.`);
+        continue;
+      }
+      if (byId.has(entry.page)) {
+        issues.push(`Family "${page.id}": relatedPages entry "${entry.page}" is a member of this page, not another page.`);
+        continue;
+      }
+      if (!allPageIds.has(entry.page) && !otherMemberIds.has(entry.page)) {
+        issues.push(`Family "${page.id}": relatedPages entry "${entry.page}" is not a catalog page.`);
+      }
+    }
+  }
+
   return issues;
 }
 
@@ -459,7 +503,7 @@ export function buildCatalogSections<TId extends string>(
         ...member,
         hasSpecimens: Boolean(member.variants?.items?.length || member.states?.items?.length || member.comparison),
       }));
-      const issues = validateFamily({ ...page, members, anatomy: page.anatomy }, otherPageIds, otherMemberIds);
+      const issues = validateFamily({ ...page, members, anatomy: page.anatomy, relatedPages: page.relatedPages }, otherPageIds, otherMemberIds);
       if ((globalThis as { __DEV__?: boolean }).__DEV__) {
         for (const issue of issues) console.error(`[Catalog] ${issue}`);
       }
@@ -471,6 +515,7 @@ export function buildCatalogSections<TId extends string>(
         aliases: page.aliases,
         apiLabel: page.apiLabel,
         anatomy: page.anatomy,
+        relatedPages: page.relatedPages,
         members: page.members!.map((member) => {
           const memberComponent = member.component ? componentByName.get(member.component) : undefined;
           return {

package/native/catalog/types.ts

@@ -401,6 +401,14 @@ export interface CatalogAnatomy {
   groups: CatalogAnatomyGroup[];
 }
 
+/** One other catalog page worth naming at the bottom of a family page: a component merely
+ *  related to the whole owns its own page, and the family page links to it rather than
+ *  documenting it inside. `note` is one short sentence saying why a reader would go there. */
+export interface RelatedPage {
+  page: string;
+  note?: string;
+}
+
 /** A family page's members with resolved props and paths, the whole, sections, and the computed
  *  outline — set on `SectionDef.family` by `buildCatalogSections` when a page has `members`. */
 export interface FamilyDef {
@@ -417,6 +425,9 @@ export interface FamilyDef {
   apiLabel?: string;
   /** Slice D1 item 1. See `CatalogPageInput.anatomy`. */
   anatomy?: CatalogAnatomy;
+  /** Other catalog pages named at the bottom of this page, under the "Related" heading, after any
+   *  deprecated non-`inWhole` sections. See `CatalogPageInput.relatedPages`. */
+  relatedPages?: RelatedPage[];
 }
 
 /** One titled card on a token page (`SectionDef.tokenSections`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",
@@ -55,14 +55,18 @@
     "typescript": "^6.0.0"
   },
   "devDependencies": {
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
+    "esbuild": "^0.25.12",
+    "jsdom": "^26.1.0",
     "puppeteer": "^25.12.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build",
     "test": "node --experimental-strip-types --test 'cli/**/*.test.ts' 'config/**/*.test.ts' 'native/catalog/__tests__/*.test.ts'",
+    "test:render": "node --import ./test/register.mjs --test 'test/__tests__/*.test.ts' 'native/catalog/__tests__/*.test.tsx'",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "kit:dev": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",
     "viewer:dev": "npm run build && cd viewer-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",