@krapwoo/ds-viewer 0.2.0 → 0.4.0

package/native/catalog/comparison.ts

@@ -8,7 +8,8 @@
  * It also decides whether two blocks sit side by side (choosePlacement) and how many columns the
  * Props box uses (propsColumns). ComparisonGrid, ComparisonGroups, and ComparisonList render it.
  */
-import type { ComparisonDef, PreviewWidths, SectionDef, SpecimenSize, VariantSlot } from './types';
+import type { ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenSize, VariantSlot } from './types.ts';
+import type React from 'react';
 
 /** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
  *  content width is a 1280px viewport minus the 264px sidebar and 32px side padding. */
@@ -35,6 +36,61 @@ export const PROPS_COLUMN_GAP = 32;
 /** Smallest column or cell width per specimen size. Wide specimens are fixed at phone width. */
 export const COLUMN_MIN_WIDTH: Record<SpecimenSize, number> = { compact: 160, regular: 240, wide: 402 };
 
+/** `Array.isArray`'s built-in type guard narrows to a mutable `any[]`, which a `readonly T[]`
+ *  union member is never assignable to — so the `else` branch of `Array.isArray(axis) ? ... :
+ *  ...` keeps `axis`'s full union type instead of narrowing away the array member. This explicit
+ *  predicate sidesteps that (never caught before Task 4: this file had never been typechecked by
+ *  `tsc` until `cli/doctor.ts`'s import pulled it into the root `tsconfig.json`'s program). */
+function isBoundAxis(axis: GridAxis): axis is { prop: string; items: readonly ComparisonAxisItem[] } {
+  return !Array.isArray(axis);
+}
+
+/** A `GridAxis`'s own items, whether it's a plain array or bound to a prop — every reader of
+ *  `ComparisonDef.rows`/`columns` goes through this (never `Array.isArray` directly), so a future
+ *  third axis shape only needs to change this one function. */
+export function axisItems(axis: GridAxis): ComparisonAxisItem[] {
+  return isBoundAxis(axis) ? [...axis.items] : [...axis];
+}
+
+/** The prop name a `GridAxis` is bound to, or undefined for a plain, unbound axis. */
+export function axisProp(axis: GridAxis): string | undefined {
+  return isBoundAxis(axis) ? axis.prop : undefined;
+}
+
+/**
+ * Shared page-authoring helper (design §1 "Page shape", §4 "Binding examples to props"). Every
+ * grid comparison in the starter kit builds its `ComparisonDef` with this instead of its own local
+ * copy, so `cli/staticPage.ts`'s static reader has exactly one call shape to recognize anywhere a
+ * page's `comparison` field is produced by a function call rather than written as a plain object
+ * literal. `rows`/`columns` accept either a plain item array (unbound) or `{ prop, items }` (bound)
+ * — the cell grid itself is unaffected either way, since cells are always keyed by each axis's own
+ * items regardless of whether that axis names a prop. Lives here, beside `axisItems`/`axisProp`,
+ * rather than in its own `grid.ts` — every other file in this module has only *type-only* relative
+ * imports; a bare, no-extension value import would be the first of its kind in `native/catalog`.
+ *
+ * Each cell is a real instance with exactly the props its row and column name. Never build these by
+ * multiplying `variants` with `states` — those are pre-rendered nodes and cannot be combined.
+ */
+export function grid(
+  rowLabel: string,
+  columnLabel: string,
+  rows: GridAxis,
+  columns: GridAxis,
+  cell: (row: string, column: string) => React.ReactNode,
+  size?: SpecimenSize,
+): ComparisonDef {
+  const rowItems = axisItems(rows);
+  const columnItems = axisItems(columns);
+  return {
+    rowLabel,
+    columnLabel,
+    rows,
+    columns,
+    cells: rowItems.flatMap((row) => columnItems.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
+    size,
+  };
+}
+
 /** How many grid columns fit beside the row header on a 1280px laptop without scrolling. */
 export function gridColumnLimit(size: SpecimenSize): number {
   return Math.floor((MATRIX_LAYOUT.laptopContentWidth - MATRIX_LAYOUT.rowHeaderWidth) / COLUMN_MIN_WIDTH[size]);
@@ -94,17 +150,19 @@ export function indexCells(def: ComparisonDef): Map<string, ComparisonDef['cells
 /** Human-readable problems in a stable order: axis duplicates, column fit, each cell in
  *  declaration order, then missing coordinates in row-major order. Empty when valid. */
 export function validateComparison(def: ComparisonDef): string[] {
-  if (def.rows.length === 0 || def.columns.length === 0) {
+  const rowItems = axisItems(def.rows);
+  const columnItems = axisItems(def.columns);
+  if (rowItems.length === 0 || columnItems.length === 0) {
     return ['Comparison needs at least one row and one column.'];
   }
   const issues: string[] = [];
   const rowKeys = new Set<string>();
-  for (const row of def.rows) {
+  for (const row of rowItems) {
     if (rowKeys.has(row.key)) issues.push(`Duplicate row key "${row.key}".`);
     rowKeys.add(row.key);
   }
   const columnKeys = new Set<string>();
-  for (const column of def.columns) {
+  for (const column of columnItems) {
     if (columnKeys.has(column.key)) issues.push(`Duplicate column key "${column.key}".`);
     columnKeys.add(column.key);
   }
@@ -149,7 +207,7 @@ export function validateComparison(def: ComparisonDef): string[] {
 export function remainingStates(states: VariantSlot | undefined, comparison: ComparisonDef | undefined): VariantSlot | undefined {
   if (!states) return undefined;
   if (!comparison) return states;
-  const covered = new Set([...comparison.rows.map((row) => row.key), ...comparison.columns.map((column) => column.key)]);
+  const covered = new Set([...axisItems(comparison.rows).map((row) => row.key), ...axisItems(comparison.columns).map((column) => column.key)]);
   const items = states.items.filter((item) => !covered.has(item.key));
   return items.length > 0 ? { ...states, items } : undefined;
 }

package/native/catalog/index.ts

@@ -17,6 +17,7 @@ export { CatalogSidebar } from './CatalogSidebar';
 export { CatalogSearchInput } from './CatalogSearchInput';
 export { SectionBlock } from './SectionBlock';
 export { ComparisonGrid } from './ComparisonGrid';
+export { grid, axisItems, axisProp } from './comparison';
 export { ComparisonGroups } from './ComparisonGroups';
 export { ComparisonList } from './ComparisonList';
 export { ReferenceDetails } from './ReferenceDetails';
@@ -32,7 +33,10 @@ export { buildComponentManifest } from './manifest';
 export type { ComponentManifestEntry, ManifestExample } from './manifest';
 export { defineCatalogPage, buildCatalogSections } from './pageApi';
 export type { CatalogPage, CatalogPageInput, GeneratedComponent, GeneratedPropRecord } from './pageApi';
-export type { PropDef, SectionDef, NavGroup, SpecimenSize, ComparisonDef, ComparisonCell, ComparisonAxisItem, PreviewWidths } from './types';
+export type { PropDef, SectionDef, NavGroup, SpecimenSize, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis, PreviewWidths } from './types';
+export { UpdatePanel } from './UpdatePanel';
+export { UPDATE_PAGE_ID } from './catalogNavigation';
+export type { UpdateNotice } from './types';
 export type { ListGroup, ListItem } from './comparison';
 export {
   CATALOG_TYPE,

package/native/catalog/pageApi.ts

@@ -77,7 +77,7 @@ function mergePropNotes(component: GeneratedComponent, propNotes: Record<string,
   return [...own, ...inherited];
 }
 
-function orderGroups(groupIds: Map<string, string[]>, groupOrder: string[] | undefined): { label: string; ids: string[] }[] {
+function orderGroups<TId extends string>(groupIds: Map<string, TId[]>, groupOrder: string[] | undefined): NavGroup<TId>[] {
   const listed = groupOrder ?? [];
   const labels = [...groupIds.keys()];
   const ordered = [...listed.filter((label) => groupIds.has(label)), ...labels.filter((label) => !listed.includes(label)).sort()];
@@ -103,7 +103,16 @@ export function buildCatalogSections<TId extends string>(
   const groupIds = new Map<string, TId[]>();
   const addToGroup = (group: string, id: TId) => groupIds.set(group, [...(groupIds.get(group) ?? []), id]);
 
+  // Design §4 "duplicate-page-id" rule's viewer-side equivalent — this is the one place in the
+  // whole viewer that already resolves every page's id to build sections/groups, so it costs
+  // nothing extra to also notice two pages claiming the same one (`sectionsById` in
+  // `CatalogShell.tsx` would otherwise just let the last one silently win).
+  const seenIds = new Set<TId>();
   const sections: SectionDef<TId>[] = pages.map((page) => {
+    if ((globalThis as { __DEV__?: boolean }).__DEV__) {
+      if (seenIds.has(page.id)) console.warn(`[Catalog] Page id "${page.id}" is used by more than one page; only the last one will show. Give one of them its own "id".`);
+      seenIds.add(page.id);
+    }
     const componentName = page.component ?? page.id;
     const component = componentByName.get(componentName);
     addToGroup(page.group, page.id);
@@ -136,5 +145,5 @@ export function buildCatalogSections<TId extends string>(
     addToGroup('Components', id);
   }
 
-  return { sections, groups: orderGroups(groupIds, groupOrder) as NavGroup<TId>[] };
+  return { sections, groups: orderGroups(groupIds, groupOrder) };
 }

package/native/catalog/tokens.ts

@@ -63,6 +63,10 @@ export const CATALOG_LAYOUT = {
   logoMark: 32,
   logoWordmarkHeight: 28,
   logoCaptionGap: 6,
+  /** Max width of the update page's content column (approved mockup: direction "C · Update
+   *  page", content at most 512px) — independent of `CATALOG_MAX_CONTENT_WIDTH` (1200px), which
+   *  is every other page's column width. */
+  updateContentMaxWidth: 512,
 } as const;
 
 /** Max width of the main content column. */
@@ -124,4 +128,15 @@ export const CATALOG_COLOR = {
   /** 3px keyboard focus ring on every catalog control. */
   focusRing: '#c9d7ff',
   code: 'Menlo',
+  /** Major-update banner background/border/text (design §5 "Viewer notice"). */
+  warning: '#8a4b00',
+  warningSubtle: '#fff4e0',
+  warningBorder: '#f0cf97',
+  /** "Can't prepare"/failure note-boxes on the update page. */
+  danger: '#b3261e',
+  dangerSubtle: '#fdecea',
+  dangerBorder: '#f2b8b5',
+  /** The update page's post-update success note-box and "Updated" pill. */
+  success: '#1e6b3a',
+  successSubtle: '#e8f5ec',
 } as const;

package/native/catalog/types.ts

@@ -65,6 +65,13 @@ export interface ComparisonAxisItem {
   label: string;
 }
 
+/** A grid axis's rows or columns: a plain list of items (today's shape, unchanged), or items bound
+ *  to a real prop so `doctor` can check each item's key against that prop's actual options (design
+ *  §4 "Binding examples to props"). Only a prop typed as a string-literal union can be bound —
+ *  binding any other prop is a `doctor` error, never a runtime check here (the viewer renders a
+ *  bound and an unbound axis identically; see `native/catalog/comparison.ts`'s `axisItems`). */
+export type GridAxis = readonly ComparisonAxisItem[] | { prop: string; items: readonly ComparisonAxisItem[] };
+
 /** One authored row × column specimen. Provide exactly one of `node` (a real instance of the
  *  documented component) or `unavailableReason` (the combination genuinely does not exist). */
 export interface ComparisonCell {
@@ -83,8 +90,8 @@ export interface ComparisonDef {
   rowLabel: string;
   /** Names the column axis (e.g. "State"). */
   columnLabel: string;
-  rows: ComparisonAxisItem[];
-  columns: ComparisonAxisItem[];
+  rows: GridAxis;
+  columns: GridAxis;
   cells: ComparisonCell[];
   /** Defaults to the section's `specimenSize`, then 'regular'. */
   size?: SpecimenSize;
@@ -189,6 +196,13 @@ export interface NavGroup<TId extends string = string> {
   ids: readonly TId[];
 }
 
-/** Canonical within-group ordering — implemented in ./catalogNavigation (pure, unit-tested) and
- *  re-exported here so existing imports keep working. */
-export { sortIds } from './catalogNavigation';
+/** Design §5 "Update check"/"Viewer notice" — the generated entry file (Task 17) imports this
+ *  shape directly from `.ds-viewer/update.json`; `null` when no update is known (disabled,
+ *  offline, or genuinely up to date — the viewer treats all three identically). */
+export interface UpdateNotice {
+  current: string;
+  latest: string;
+  breaking: boolean;
+  summary: string[];
+  releasedAt?: string;
+}

package/native/catalog/updatePanelState.ts

@@ -0,0 +1,74 @@
+/** The same shape as `cli/updatePlan.ts`'s `UpdatePlan` — duplicated, not imported: `native/catalog/`
+ *  is the published package root and never imports from `cli/` (the reverse is normal: `cli/`
+ *  already imports `native/catalog/` throughout). The endpoint's `POST /plan` response is this
+ *  exact shape (confirmed by `cli/endpoint.ts`, Task 12, which forwards `cli/updatePlan.ts`'s own
+ *  `UpdatePlan` verbatim as JSON). */
+export interface UpdatePlanView {
+  current: string;
+  latest: string;
+  breaking: boolean;
+  summary: string[];
+  releasedAt?: string;
+  files: { path: string; reason: string; dirty: boolean }[];
+  dirtyFiles: string[];
+  kitFilesDiffering: number;
+  outsideGitRepo: boolean;
+}
+
+/** The same shape as `cli/endpoint.ts`'s `UpdateStatus`, same reason as above. `updating`'s each
+ *  step carries a three-way `state`, not a boolean `done` (Important finding, Fable correction
+ *  pass: the approved mockup's own `updating` state shows one step mid-flight — `ic now`, a
+ *  distinct icon from both `done` and the not-yet-reached `todo` — which a boolean cannot
+ *  represent). `success` also carries the changed files' paths and the version just installed
+ *  (Errata 1b: `update.json` becomes `null` once latest equals current, so `success` must carry
+ *  its own `latest` rather than relying on the now-gone `update` prop) — Task 16's `ready` phase
+ *  has `plan.files`/`plan.latest` to show the same values, but `plan` is gone by the time
+ *  `success` renders (the page has reloaded onto the new version), so the result itself must carry
+ *  them. */
+export type UpdateStatusView =
+  | { phase: 'idle' }
+  | { phase: 'updating'; steps: { label: string; state: 'done' | 'now' | 'todo' }[] }
+  | { phase: 'restarting' }
+  | { phase: 'success'; doctorSummary: string; files: string[]; latest: string }
+  | { phase: 'failure'; log: string; failedStep: string };
+
+export type UpdatePhase = 'checking' | 'ready' | 'dirty' | 'offline' | 'updating' | 'restarting' | 'success' | 'failure';
+
+/** Minor finding, Fable correction pass: every `{ error }` previously mapped to the same
+ *  `'offline'` phase regardless of *which* error — including `buildUpdatePlan`'s own "Already on
+ *  the latest version" message, which is not an offline/failure condition at all. `UpdatePanel`
+ *  (Task 16) still only needs one phase to key its `switch` on; it reads `result.error` itself,
+ *  directly, to pick between the two copies the mockup's `offline` state and a plain "you're
+ *  already up to date" note both need. */
+export function phaseFromPlanResult(result: UpdatePlanView | { error: string }): 'ready' | 'dirty' | 'offline' {
+  if ('error' in result) return 'offline';
+  return result.dirtyFiles.length > 0 ? 'dirty' : 'ready';
+}
+
+/** `true` only for `buildUpdatePlan`'s own "Already on the latest version (…)." message — never a
+ *  real failure, so `UpdatePanel`'s `offline` phase shows a plain up-to-date note instead of the
+ *  "Couldn't prepare the update" error copy for this one case. */
+export function isAlreadyUpToDateError(result: UpdatePlanView | { error: string }): boolean {
+  return 'error' in result && result.error.startsWith('Already on the latest version');
+}
+
+/** The one function `UpdatePanel.tsx` calls to decide which of the mockup's 10 states to render.
+ *  `status` (from the endpoint's own `/update/status`, authoritative once an update has started)
+ *  always wins over `planResult` — a plan fetched before an update began is stale the moment one
+ *  starts, and the mockup itself never shows plan content and progress content at once. While
+ *  `status.phase` is `'idle'` and no plan has resolved yet (`planResult === undefined`), the panel
+ *  is still in the mockup's own `'checking'` state. */
+export function resolvePanelPhase(status: UpdateStatusView, planResult: UpdatePlanView | { error: string } | undefined): UpdatePhase {
+  if (status.phase !== 'idle') return status.phase;
+  if (planResult === undefined) return 'checking';
+  return phaseFromPlanResult(planResult);
+}
+
+/** The panel's `"Released N days ago."` line — floors to whole days, never "23 hours ago" (the
+ *  mockup's own example, "Released 2 days ago.", is always a whole number of days). */
+export function daysAgoLabel(releasedAt: string, nowMs: number): string {
+  const days = Math.floor((nowMs - Date.parse(releasedAt)) / (24 * 60 * 60 * 1000));
+  if (days <= 0) return 'Released today.';
+  if (days === 1) return 'Released 1 day ago.';
+  return `Released ${days} days ago.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",
@@ -29,6 +29,7 @@
     "starter-kit",
     "dist/cli",
     "dist/config",
+    "dist/native",
     "config/index.ts",
     "README.md",
     "LICENSE"
@@ -51,6 +52,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
     "puppeteer": "^25.12.0"
   },
   "scripts": {
@@ -59,6 +61,8 @@
     "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",
     "check:catalog": "npm run build && node scripts/checkCatalogConsole.mjs kit-host",
+    "check:doctor": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci",
+    "check:types": "tsc --noEmit -p kit-host",
     "release": "node scripts/release.mjs"
   }
 }

package/starter-kit/components/Avatar/Avatar.catalog.tsx

@@ -1,30 +1,12 @@
 import React from 'react';
-import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, grid } from '@krapwoo/ds-viewer';
 import { Avatar } from './Avatar';
 import { DS_SEMANTIC } from '../../tokens';
 
-// Grid comparisons: each cell is a real instance with exactly the props its row and column name.
-// Never build these by multiplying `variants` with `states` — those are pre-rendered nodes and
-// cannot combine.
-function grid(
-  rowLabel: string,
-  columnLabel: string,
-  rows: { key: string; label: string }[],
-  columns: { key: string; label: string }[],
-  cell: (row: string, column: string) => React.ReactNode,
-  size?: ComparisonDef['size'],
-): ComparisonDef {
-  return {
-    rowLabel,
-    columnLabel,
-    rows,
-    columns,
-    cells: rows.flatMap((row) => columns.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
-    size,
-  };
-}
-
 // Avatar: content Kind × Size (Avatar's `size` is continuous; 24 / 40 default / 64 is the sweep).
+// Neither axis names a real prop — "Kind" is which of 3 optional props is set, not one enum, and
+// `size` has no fixed option set — so both stay unbound. An unbound axis is fully valid; `doctor`
+// only ever reports how many examples are unbound as information, never as an error or a warning.
 const AVATAR_COMPARISON = grid(
   'Kind',
   'Size',

package/starter-kit/components/Badge/Badge.catalog.tsx

@@ -1,29 +1,8 @@
 import React from 'react';
-import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, grid } from '@krapwoo/ds-viewer';
 import { Badge } from './Badge';
 import type { BadgeVariant } from './Badge.types';
 
-// Grid comparisons: each cell is a real instance with exactly the props its row and column name.
-// Never build these by multiplying `variants` with `states` — those are pre-rendered nodes and
-// cannot combine.
-function grid(
-  rowLabel: string,
-  columnLabel: string,
-  rows: { key: string; label: string }[],
-  columns: { key: string; label: string }[],
-  cell: (row: string, column: string) => React.ReactNode,
-  size?: ComparisonDef['size'],
-): ComparisonDef {
-  return {
-    rowLabel,
-    columnLabel,
-    rows,
-    columns,
-    cells: rows.flatMap((row) => columns.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
-    size,
-  };
-}
-
 // Badge: Tone × Icon layout. One icon per tone, matching the Variants examples.
 const BADGE_TONES: { key: BadgeVariant; label: string; text: string; icon: React.ComponentProps<typeof Badge>['leadingIcon'] }[] = [
   { key: 'neutral', label: 'Neutral', text: 'Local', icon: 'pin' },
@@ -32,10 +11,23 @@ const BADGE_TONES: { key: BadgeVariant; label: string; text: string; icon: React
   { key: 'warning', label: 'Warning', text: 'Delayed', icon: 'triangle-alert' },
   { key: 'negative', label: 'Negative', text: 'Suspended', icon: 'circle-slash' },
 ];
+// `rows` is bound to Badge's own `variant` prop (design §4) — written as its own literal array
+// (not `BADGE_TONES.map(...)`) so `doctor`'s static reader can check it without evaluating a
+// function call; `BADGE_TONES` above still drives the real rendering in `cell` below.
+const BADGE_ROWS = {
+  prop: 'variant',
+  items: [
+    { key: 'neutral', label: 'Neutral' },
+    { key: 'info', label: 'Info' },
+    { key: 'positive', label: 'Positive' },
+    { key: 'warning', label: 'Warning' },
+    { key: 'negative', label: 'Negative' },
+  ],
+} as const;
 const BADGE_COMPARISON = grid(
   'Tone',
   'Icon',
-  BADGE_TONES.map(({ key, label }) => ({ key, label })),
+  BADGE_ROWS,
   [
     { key: 'label-only', label: 'Label only' },
     { key: 'leading-icon', label: 'Leading icon' },

package/starter-kit/components/Banner/Banner.tsx

@@ -235,7 +235,7 @@ const styles = StyleSheet.create({
   },
   // Translucent pressed overlay — sits above the banner bg so the tinted bg shows through.
   pressOverlay: {
-    ...StyleSheet.absoluteFillObject,
+    ...StyleSheet.absoluteFill,
     backgroundColor: DS_SEMANTIC.interaction.pressed,
     borderRadius: DS_RADIUS.medium,
   },

package/starter-kit/components/BottomSheet/BottomSheet.tsx

@@ -126,8 +126,8 @@ export function BottomSheet({ visible, onDismiss, header, children, footer, styl
 }
 
 const styles = StyleSheet.create({
-  overlay: { ...StyleSheet.absoluteFillObject, justifyContent: 'flex-end' },
-  backdrop: { ...StyleSheet.absoluteFillObject, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
+  overlay: { ...StyleSheet.absoluteFill, justifyContent: 'flex-end' },
+  backdrop: { ...StyleSheet.absoluteFill, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
   sheet: {
     maxHeight: MAX_HEIGHT_PERCENT,
     backgroundColor: DS_SEMANTIC.surface.white,

package/starter-kit/components/Button/Button.catalog.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View, StyleSheet } from 'react-native';
-import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, grid } from '@krapwoo/ds-viewer';
 import { Button } from './Button';
 import type { ButtonVariant } from './Button.types';
 import { DS_SEMANTIC } from '../../tokens';
@@ -16,38 +16,24 @@ const styles = StyleSheet.create({
   },
 });
 
-// Grid comparisons: each cell is a real instance with exactly the props its row and column name.
-// Never build these by multiplying `variants` with `states` — those are pre-rendered nodes and
-// cannot combine.
-function grid(
-  rowLabel: string,
-  columnLabel: string,
-  rows: { key: string; label: string }[],
-  columns: { key: string; label: string }[],
-  cell: (row: string, column: string) => React.ReactNode,
-  size?: ComparisonDef['size'],
-): ComparisonDef {
-  return {
-    rowLabel,
-    columnLabel,
-    rows,
-    columns,
-    cells: rows.flatMap((row) => columns.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
-    size,
-  };
-}
-
 // Button: Variant × State. `white` keeps the dark backdrop its variant requires.
+// `rows` is bound to Button's own `variant` prop (design §4): each row key below is an actual
+// `ButtonVariant` option, so `doctor` can tell when one is renamed or removed. `columns` names no
+// single prop (disabled/loading are two separate booleans, not one "State" prop) and stays unbound
+// — unbound axes are just as valid, and `doctor` never flags one.
 const BUTTON_COMPARISON = grid(
   'Variant',
   'State',
-  [
-    { key: 'primary', label: 'Primary' },
-    { key: 'secondary', label: 'Secondary' },
-    { key: 'tertiary', label: 'Tertiary' },
-    { key: 'white', label: 'White' },
-    { key: 'ghost', label: 'Ghost' },
-  ],
+  {
+    prop: 'variant',
+    items: [
+      { key: 'primary', label: 'Primary' },
+      { key: 'secondary', label: 'Secondary' },
+      { key: 'tertiary', label: 'Tertiary' },
+      { key: 'white', label: 'White' },
+      { key: 'ghost', label: 'Ghost' },
+    ],
+  },
   [
     { key: 'default', label: 'Default' },
     { key: 'disabled', label: 'Disabled' },

package/starter-kit/components/Dialog/Dialog.tsx

@@ -65,12 +65,12 @@ export function Dialog({ visible, onDismiss, children, style }: DialogProps) {
 
 const styles = StyleSheet.create({
   overlay: {
-    ...StyleSheet.absoluteFillObject,
+    ...StyleSheet.absoluteFill,
     alignItems: 'center',
     justifyContent: 'center',
     padding: DS_SPACING[800],
   },
-  backdrop: { ...StyleSheet.absoluteFillObject, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
+  backdrop: { ...StyleSheet.absoluteFill, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
   card: {
     width: '100%',
     maxWidth: 400,

package/starter-kit/components/Pill/Pill.catalog.tsx

@@ -1,36 +1,22 @@
 import React from 'react';
-import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, grid } from '@krapwoo/ds-viewer';
 import { Pill } from './Pill';
 
-// Grid comparisons: each cell is a real instance with exactly the props its row and column name.
-// Never build these by multiplying `variants` with `states` — those are pre-rendered nodes and
-// cannot combine.
-function grid(
-  rowLabel: string,
-  columnLabel: string,
-  rows: { key: string; label: string }[],
-  columns: { key: string; label: string }[],
-  cell: (row: string, column: string) => React.ReactNode,
-  size?: ComparisonDef['size'],
-): ComparisonDef {
-  return {
-    rowLabel,
-    columnLabel,
-    rows,
-    columns,
-    cells: rows.flatMap((row) => columns.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
-    size,
-  };
-}
-
 // Pill: Selection × State.
+// `rows` is bound to Pill's own `variant` prop (design §4); the second item's key is
+// `'not_selected'` (underscore), matching `PillVariant` exactly — not `'not-selected'`, which is
+// only this page's own label-ish spelling and would fail `doctor`'s "item key must be a real
+// option" check.
 const PILL_COMPARISON = grid(
   'Selection',
   'State',
-  [
-    { key: 'selected', label: 'Selected' },
-    { key: 'not-selected', label: 'Not selected' },
-  ],
+  {
+    prop: 'variant',
+    items: [
+      { key: 'selected', label: 'Selected' },
+      { key: 'not_selected', label: 'Not selected' },
+    ],
+  },
   [
     { key: 'icon-text', label: 'Icon + Text' },
     { key: 'icon-only', label: 'Icon-only' },