@krapwoo/ds-viewer 0.4.6 → 0.4.7

package/native/catalog/ReferenceDetails.tsx

@@ -1,9 +1,9 @@
 import React, { useState } from 'react';
-import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { View, Text, StyleSheet, type LayoutChangeEvent, type TextStyle } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { PropsTable } from './PropsTable';
-import { propsColumns } from './comparison';
-import type { SectionDef } from './types';
+import { propsColumns, referenceColumns } from './comparison';
+import type { ComposedOfEntry, SectionDef } from './types';
 
 // react-native-web reads `aria-level`; React Native's prop types do not declare it.
 const HEADING_LEVEL_2 = { 'aria-level': 2 } as Record<string, unknown>;
@@ -40,13 +40,51 @@ function PropsBox<TId extends string>({ def }: { def: SectionDef<TId> }) {
   );
 }
 
+// `built-in` is composition's assumed default relationship, so spelling it out reads redundantly
+// (e.g. "TrainArrivalRemainingTime · built-in"); `slot`/`related` still need their own suffix to
+// stay distinguishable from a plain built-in entry.
+function compositionLabel(entry: ComposedOfEntry): string {
+  return entry.relationship === 'built-in' ? entry.component : `${entry.component} · ${entry.relationship}`;
+}
+
+function CompositionFacts({ composedOf }: { composedOf: ComposedOfEntry[] }) {
+  return (
+    <>
+      {composedOf.map((entry, i) => (
+        <Fact key={`${entry.component}-${entry.relationship}-${i}`} label={compositionLabel(entry)} value={entry.role} />
+      ))}
+    </>
+  );
+}
+
 /**
- * Always-visible reference below a page's specimens: a card with Guidance and Quick reference
- * (source path, accessibility), then Props in their own box. Token galleries show only Quick
- * reference with the source path. No collapse control by design.
+ * Always-visible reference below a page's specimens: a card with Guidance, Quick reference
+ * (source path, accessibility), and — only when the page has confirmed composition to disclose —
+ * Composition, then Props in their own box. Token galleries show only Quick reference with the
+ * source path. No collapse control by design.
+ *
+ * Guidance/Quick reference/Composition lay out from the card's own measured INNER width
+ * (`referenceColumns`), not viewport width alone: three columns only when there is confirmed
+ * composition and the card is wide enough for all three (Composition gets its own column only
+ * then — otherwise it stays nested under Quick reference, as it always has); two when there's
+ * room for Guidance and Quick reference side by side; one (stacked, full document order, nothing
+ * dropped) when the card is too narrow even for two. `minWidth: 0` on every column lets its facts
+ * and source path actually shrink and wrap at that width instead of pushing the card wider than
+ * its own container.
+ *
+ * `onLayout` sits on the `columns` row itself, not the padded/bordered `card` around it:
+ * `referenceColumns` fits each column against `REFERENCE_MIN_COLUMN_WIDTH`, an INNER measurement —
+ * the card's own padding (`panelPadding`) and 1px border never belong in that budget. Measuring the
+ * outer card previously fed `referenceColumns` an outer width up to ~42px wider than what the three
+ * columns' content actually has, which can report a column count the inner content doesn't fit.
  */
 export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<TId> }) {
   const hide = def.hide ?? {};
+  const [width, setWidth] = useState(0);
+  const onLayout = (event: LayoutChangeEvent) => {
+    const next = Math.round(event.nativeEvent.layout.width);
+    if (next > 0 && next !== width) setWidth(next);
+  };
   if (def.tokenGallery) {
     return (
       <View style={styles.card}>
@@ -55,27 +93,37 @@ export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<
       </View>
     );
   }
+  const hasComposition = Boolean(def.composedOf && def.composedOf.length > 0);
+  const columns = referenceColumns(width, hasComposition);
+  const stacked = columns === 1;
+  const compositionIsOwnColumn = columns === 3 && hasComposition;
+  const columnStyle = stacked ? styles.columnStacked : styles.column;
+
   return (
     <View style={styles.stack}>
       <View style={styles.card}>
-        <View style={styles.columns}>
-          <View style={styles.column}>
+        <View style={[styles.columns, stacked && styles.columnsStacked]} onLayout={onLayout}>
+          <View style={columnStyle}>
             <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Guidance</Text>
             <Text style={styles.body}>{def.whenToUse ?? 'No usage guidance documented.'}</Text>
           </View>
-          <View style={styles.column}>
+          <View style={columnStyle}>
             <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
             {def.path && <Fact label="Source" value={def.path} mono />}
             {!hide.accessibility && <Fact label="Accessibility" value={def.a11y ?? 'No accessibility notes documented.'} />}
-            {def.composedOf && def.composedOf.length > 0 && (
+            {!compositionIsOwnColumn && hasComposition && def.composedOf && (
               <>
                 <Text style={styles.subheading}>Composition</Text>
-                {def.composedOf.map((entry, i) => (
-                  <Fact key={`${entry.component}-${entry.relationship}-${i}`} label={`${entry.component} · ${entry.relationship}`} value={entry.role} />
-                ))}
+                <CompositionFacts composedOf={def.composedOf} />
               </>
             )}
           </View>
+          {compositionIsOwnColumn && def.composedOf && (
+            <View style={columnStyle}>
+              <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Composition</Text>
+              <CompositionFacts composedOf={def.composedOf} />
+            </View>
+          )}
         </View>
       </View>
       {!hide.props && <PropsBox def={def} />}
@@ -93,7 +141,9 @@ const styles = StyleSheet.create({
     padding: CATALOG_LAYOUT.panelPadding,
   },
   columns: { flexDirection: 'row', gap: CATALOG_SPACE['2xl'] },
-  column: { flex: 1 },
+  columnsStacked: { flexDirection: 'column' },
+  column: { flex: 1, minWidth: 0 },
+  columnStacked: { minWidth: 0 },
   heading: {
     fontSize: CATALOG_TYPE.panelHeading,
     fontWeight: '700',
@@ -111,15 +161,20 @@ const styles = StyleSheet.create({
     marginBottom: CATALOG_SPACE.xs,
   },
   fact: {
-    flexDirection: 'row',
-    justifyContent: 'space-between',
-    gap: CATALOG_SPACE.lg,
+    flexDirection: 'column',
+    gap: CATALOG_SPACE.xs,
     paddingVertical: CATALOG_LAYOUT.factPaddingY,
     borderBottomWidth: 1,
     borderBottomColor: CATALOG_COLOR.borderSubtle,
   },
-  factLabel: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
-  factValue: { flex: 1, fontSize: CATALOG_TYPE.md, lineHeight: 20, textAlign: 'right', color: CATALOG_COLOR.textMuted },
-  mono: { fontFamily: CATALOG_COLOR.code },
+  factLabel: { flexShrink: 1, minWidth: 0, fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
+  factValue: { minWidth: 0, fontSize: CATALOG_TYPE.md, lineHeight: 20, textAlign: 'left', color: CATALOG_COLOR.textMuted },
+  // `wordBreak` isn't in the installed `TextStyle` type (RN's own, not RNW's — RNW's own
+  // `Text/types.js` declares it; a browser applies any valid CSS property name it recognizes
+  // regardless), so a bare literal here would report an unknown property under `--noEmit` even
+  // though it genuinely works: a long unbroken token (a source path with no spaces, e.g.
+  // `AnimatedChevron.tsx`) has no space for the browser's default line-breaking to use, so without
+  // this it stays one unbroken run and overflows a narrow card instead of wrapping at its '/'s.
+  mono: { fontFamily: CATALOG_COLOR.code, wordBreak: 'break-word' } as TextStyle,
   empty: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/SectionBlock.tsx

@@ -8,7 +8,7 @@ import { ReferenceDetails } from './ReferenceDetails';
 import { SpecimenSurface } from './SpecimenSurface';
 import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import { TokenSections } from './TokenLayouts';
-import { choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
+import { MATRIX_LAYOUT, choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
 import type { PreviewWidths, SectionDef, SpecimenSurfaceKind } from './types';
 
 // Matches a quoted-string-literal union type, e.g. "'primary' | 'secondary' | 'tertiary'" — anything
@@ -103,11 +103,14 @@ function frameLabel(width: number): string {
 
 /** A component preview: one frame per width (each at most phone width), or full width for catalog
  *  chrome and token galleries. Every frame is its own live instance with its own state. `surface`
- *  is omitted for token galleries, which keep their current, unstaged presentation. */
-function Preview({ render, widths, surface }: { render: () => React.ReactNode; widths: PreviewWidths; surface?: SpecimenSurfaceKind }) {
+ *  is omitted for token galleries, which keep their current, unstaged presentation. `layout: 'table'`
+ *  (only ever set for a numeric-width preview — see `presentationBlocks`) renders `TablePreview`
+ *  instead; omitted/`'frames'` keeps this exact, unchanged presentation. */
+function Preview({ render, widths, surface, layout }: { render: () => React.ReactNode; widths: PreviewWidths; surface?: SpecimenSurfaceKind; layout?: 'table' }) {
   // Token galleries pass no surface: their card stays white.
   const kind = surface ?? 'transparent';
   if (widths === 'full') return <SpecimenSurface surface={kind} style={styles.previewCard}>{render()}</SpecimenSurface>;
+  if (layout === 'table') return <TablePreview render={render} widths={widths} surface={kind} />;
   return (
     <View style={styles.previewCard}>
       <View style={styles.frames}>
@@ -128,6 +131,39 @@ function Preview({ render, widths, surface }: { render: () => React.ReactNode; w
   );
 }
 
+/** `layout: 'table'` presentation for a numeric-width Preview: every width shares ONE
+ *  `ComparisonList`-style card (same caption typography, muted caption strip, border/radius/surface
+ *  tokens) instead of each width getting its own bordered frame-card. Each width keeps its own
+ *  caption strip directly above its own live body, in a single flex-wrapped row — one stable parent
+ *  with keyed cells, so a viewport resize that wraps the row to stacked columns reflows in place
+ *  rather than remounting any demo. A cell's body carries the same `MATRIX_LAYOUT.cellPadding`
+ *  `ComparisonList`'s own cells use; the requested width instead reaches the demo untouched through
+ *  an inner width-qualified viewport nested inside that padded body (capped only by
+ *  `maxWidth: '100%'`, the same cap `Preview`'s own frames already use), so a cell's `flexBasis`
+ *  reserving `width + 2 * cellPadding` leaves the padded body exactly enough room for it, with no
+ *  blank trailing slack. The row's cells share 1px gutters (a `gap` on a bordered backing) for
+ *  dividers, in both the side-by-side and stacked-wrap arrangements. */
+function TablePreview({ render, widths, surface }: { render: () => React.ReactNode; widths: readonly number[]; surface: SpecimenSurfaceKind }) {
+  return (
+    <View style={styles.tableCard}>
+      <View style={styles.tableRow}>
+        {widths.map((width, i) => (
+          <View key={`${width}-${i}`} style={[styles.tableCell, { flexBasis: width + 2 * MATRIX_LAYOUT.cellPadding }]}>
+            <View style={styles.tableCaption}>
+              <Text style={styles.tableCaptionText}>{frameLabel(width)}</Text>
+            </View>
+            <SpecimenSurface surface={surface} style={styles.tableBody}>
+              <View role="group" aria-label={frameLabel(width)} style={[styles.tableBodyViewport, { width }]}>
+                {render()}
+              </View>
+            </SpecimenSurface>
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}
+
 function BlockContent<TId extends string>({ block, def, surface }: { block: PresentationBlock; def: SectionDef<TId>; surface: SpecimenSurfaceKind }) {
   switch (block.kind) {
     case 'grid':
@@ -139,7 +175,9 @@ function BlockContent<TId extends string>({ block, def, surface }: { block: Pres
     case 'preview':
       // A token gallery's `preview` block shows full-width raw token data, not a component
       // specimen — it keeps its current, unstaged presentation.
-      return def.render ? <Preview render={def.render} widths={block.widths} surface={def.tokenGallery ? undefined : surface} /> : null;
+      // `Preview`'s own `widths === 'full'` check already excludes a full-width or token-gallery
+      // preview from ever reaching the table layout, regardless of `def.previewLayout`.
+      return def.render ? <Preview render={def.render} widths={block.widths} surface={def.tokenGallery ? undefined : surface} layout={def.previewLayout === 'table' ? 'table' : undefined} /> : null;
     case 'tokenSections':
       return <TokenSections sections={block.sections} columns={block.columns} />;
     default:
@@ -356,5 +394,29 @@ const styles = StyleSheet.create({
     padding: CATALOG_SPACE.xl,
     gap: CATALOG_SPACE.md,
   },
+  // `ComparisonList`'s own card/caption tokens, reused so a 'table' preview reads as the same shared
+  // surface — no outer `previewCard` padding/chrome around it (that card provides its own).
+  tableCard: {
+    backgroundColor: CATALOG_COLOR.surface,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.borderStrong,
+    borderRadius: CATALOG_RADIUS.card,
+    overflow: 'hidden',
+  },
+  // 1px gutters between cells: a gap over a bordered backing, so dividers read correctly whether
+  // cells sit side by side or wrap into stacked rows.
+  tableRow: { flexDirection: 'row', flexWrap: 'wrap', gap: 1, backgroundColor: CATALOG_COLOR.border },
+  tableCell: { backgroundColor: CATALOG_COLOR.surface, flexGrow: 1, minWidth: 0, maxWidth: '100%' },
+  tableCaption: {
+    padding: MATRIX_LAYOUT.cellPadding,
+    backgroundColor: CATALOG_COLOR.surfaceMuted,
+    borderBottomWidth: 1,
+    borderBottomColor: CATALOG_COLOR.border,
+  },
+  tableCaptionText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
+  // Same cell padding `ComparisonList` uses: the requested width instead reaches the live demo
+  // untouched through `tableBodyViewport`, the inner width-qualified group nested inside this body.
+  tableBody: { padding: MATRIX_LAYOUT.cellPadding, flexGrow: 1, alignItems: 'center', justifyContent: 'flex-start' },
+  tableBodyViewport: { maxWidth: '100%' },
   emptyText: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/SpecimenSurface.tsx

@@ -1,9 +1,9 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
 import { CATALOG_COLOR } from './tokens';
-import { DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE } from './specimenSurfaceStyle';
+import { DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE, specimenContentAlignItems, specimenContentBoundedStyle } from './specimenSurfaceStyle';
 import { blendsIntoCell, measurePaintedBoxes } from './specimenFill';
-import type { SpecimenSurfaceKind } from './types';
+import type { SpecimenAlign, SpecimenSurfaceKind } from './types';
 
 type Browser = {
   getComputedStyle?: (element: unknown) => never;
@@ -65,9 +65,22 @@ export function SpecimenSurface({
 }
 
 /** Wraps one example inside its cell: full cell width (so a percentage-width example resolves
- *  against the cell), centered unless the example fills the cell. */
-export function SpecimenContent({ fill, children }: { fill?: boolean; children: React.ReactNode }) {
-  return <View style={fill ? styles.fill : styles.center}>{children}</View>;
+ *  against the cell). `fill` changes whether the example itself also stretches to that width
+ *  (default) or keeps its own content size — a non-`fill` specimen centers by default; a `fill`
+ *  one stretches by default instead, preserving an auto-sized full-width child (see
+ *  `specimenContentAlignItems`). `align` always overrides that default explicitly.
+ *
+ *  A non-`fill` specimen uses a row main axis (`specimenContentBoundedStyle`) so `justifyContent`
+ *  positions it horizontally — a column + `alignItems` left the specimen's own root `alignSelf`
+ *  (e.g. Badge's `alignSelf: 'flex-start'`) free to override that positioning outright, since
+ *  `alignItems` only sets a child's *default* `alignSelf`. `fill` keeps the existing column +
+ *  `alignItems` stretch behavior, unchanged. */
+export function SpecimenContent({ fill, align, children }: { fill?: boolean; align?: SpecimenAlign; children: React.ReactNode }) {
+  if (fill) {
+    const alignItems = specimenContentAlignItems(fill, align);
+    return <View style={[SPECIMEN_SURFACE_WIDTH_STYLE, { alignItems }]}>{children}</View>;
+  }
+  return <View style={specimenContentBoundedStyle(align)}>{children}</View>;
 }
 
 // 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token); there is no dark-surface token.
@@ -77,8 +90,3 @@ const FILL = StyleSheet.create({
   dark: { backgroundColor: CATALOG_COLOR.text },
   transparent: {},
 });
-
-const styles = StyleSheet.create({
-  center: { ...SPECIMEN_SURFACE_WIDTH_STYLE, alignItems: 'center' },
-  fill: { ...SPECIMEN_SURFACE_WIDTH_STYLE },
-});

package/native/catalog/comparison.ts

@@ -8,7 +8,9 @@
  * 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 { ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenSize, TokenSection, VariantSlot } from './types.ts';
+import type {
+  ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenAlign, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot,
+} from './types.ts';
 import type React from 'react';
 
 /** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
@@ -33,6 +35,14 @@ export const PROPS_MIN_COLUMN_WIDTH = 360;
 /** Gap between the two Props columns (CATALOG_SPACE['2xl']). */
 export const PROPS_COLUMN_GAP = 32;
 
+/** A reference column (Guidance, Quick reference, or Composition) is never narrower than this;
+ *  below it, `referenceColumns` drops to fewer columns. */
+export const REFERENCE_MIN_COLUMN_WIDTH = 280;
+
+/** Gap between reference columns (CATALOG_SPACE['2xl'], the same token the card's columns already
+ *  use). */
+export const REFERENCE_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 };
 
@@ -222,6 +232,12 @@ export interface ListItem {
   label: string;
   node: unknown;
   fill?: boolean;
+  /** This item's own `specimenSurface` override — see `SpecimenPresentation`. Omit to inherit the
+   *  surface already in effect (the slot's/page's `specimenSurface`, else `'auto'`). */
+  surface?: SpecimenSurfaceKind;
+  /** This item's own cross-axis alignment override — see `SpecimenPresentation.align`. Omit to
+   *  inherit the established default (centered, or stretched when `fill` is set). */
+  align?: SpecimenAlign;
 }
 
 export interface ListGroup {
@@ -250,7 +266,9 @@ export function slotSize<TId extends string>(def: SectionDef<TId>, slot: Variant
 }
 
 function slotItems(slot: VariantSlot): ListItem[] {
-  return slot.items.map((item) => ({ key: item.key, label: item.name, node: item.node, fill: item.fill || slot.itemsFill }));
+  // Nullish, not `||`: an item's own explicit `fill: false` must override an inherited
+  // `itemsFill: true`, which `false || slot.itemsFill` would silently discard.
+  return slot.items.map((item) => ({ key: item.key, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill, surface: item.surface, align: item.align }));
 }
 
 /** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
@@ -265,12 +283,14 @@ function previewWidths(requested: PreviewWidths | undefined, fallback: PreviewWi
 function groupStates(variants: VariantSlot, states: VariantSlot): { groups: ListGroup[]; leftovers: VariantSlot | undefined } | undefined {
   const variantKeys = new Set(variants.items.map((v) => v.key));
   if (!states.items.some((s) => s.group !== undefined && variantKeys.has(s.group))) return undefined;
-  const fill = (item: VariantSlot['items'][number], slot: VariantSlot) => item.fill || slot.itemsFill;
+  // Nullish, not `||` — same reasoning as `slotItems`: an explicit `fill: false` must win over an
+  // inherited `itemsFill: true`.
+  const fill = (item: VariantSlot['items'][number], slot: VariantSlot) => item.fill ?? slot.itemsFill;
   const groups = variants.items.map((variant) => {
     const own = states.items.filter((s) => s.group === variant.key);
     const items = own.length > 0
-      ? own.map((s) => ({ key: s.key, label: s.name, node: s.node, fill: fill(s, states) }))
-      : [{ key: variant.key, label: variant.name, node: variant.node, fill: fill(variant, variants) }];
+      ? own.map((s) => ({ key: s.key, label: s.name, node: s.node, fill: fill(s, states), surface: s.surface, align: s.align }))
+      : [{ key: variant.key, label: variant.name, node: variant.node, fill: fill(variant, variants), surface: variant.surface, align: variant.align }];
     return { key: variant.key, label: variant.name, items };
   });
   const rest = states.items.filter((s) => s.group === undefined || !variantKeys.has(s.group));
@@ -377,3 +397,17 @@ export function choosePlacement({ available, gap, first, second }: { available:
 export function propsColumns(count: number, width: number): 1 | 2 {
   return count >= 4 && width >= 2 * PROPS_MIN_COLUMN_WIDTH + PROPS_COLUMN_GAP ? 2 : 1;
 }
+
+/** How many columns the reference card's Guidance / Quick reference / Composition panel uses at a
+ *  given measured inner card width: 3 only when there is confirmed composition to show as its own
+ *  column AND the card is wide enough for three REFERENCE_MIN_COLUMN_WIDTH columns; 2 when wide
+ *  enough for two (any composition then stays nested under Quick reference, as it always has been);
+ *  1 (stacked, full content in document order — nothing dropped) when even two columns wouldn't
+ *  each keep their minimum. An unmeasured width (`<= 0`) stacks, so the first frame before layout
+ *  settles never overflows. */
+export function referenceColumns(width: number, hasComposition: boolean): 1 | 2 | 3 {
+  const fits = (n: number) => width >= n * REFERENCE_MIN_COLUMN_WIDTH + (n - 1) * REFERENCE_COLUMN_GAP;
+  if (hasComposition && fits(3)) return 3;
+  if (fits(2)) return 2;
+  return 1;
+}

package/native/catalog/index.ts

@@ -31,6 +31,10 @@ export { TokenSections, TokenGrid, TokenTile } from './TokenLayouts';
 export { DividedStack } from './DividedStack';
 export { Swatch } from './Swatch';
 export { PhoneFrame } from './PhoneFrame';
+export { BoundedOverlayViewport } from './BoundedOverlayViewport';
+export type { BoundedOverlayViewportProps } from './BoundedOverlayViewport';
+export { comparisonCellItemKey } from './overlayViewport';
+export type { OverlayAddress, OverlaySlot } from './overlayViewport';
 export { SpacingScaleGallery } from './SpacingScaleGallery';
 export { TypeScaleGallery } from './TypeScaleGallery';
 export { buildComponentManifest } from './manifest';

package/native/catalog/overlayViewport.ts

@@ -0,0 +1,156 @@
+/**
+ * Pure logic behind `BoundedOverlayViewport.tsx` — no React/React Native imports, so it runs
+ * under Node's test runner the same way `catalogNavigation.ts` does for `CatalogShell`. Addresses
+ * one specific authored specimen, decides whether an instance should frame itself in a bounded
+ * child document or render inline, and (for `CatalogShell`'s own chromeless selected-document
+ * render) resolves an address back to the `node` it names.
+ */
+import type React from 'react';
+import type { SectionDef } from './types.ts';
+
+/** Which block on a page an addressed specimen's `node` lives in — see `findOverlayNode`. */
+export type OverlaySlot = 'variants' | 'states' | 'comparison';
+
+/** Identifies exactly one authored specimen: a page id (`SectionDef.id`), which block it lives
+ *  in, and that item's own key — `VariantExample.key` for `'variants'`/`'states'`, or this
+ *  module's own `comparisonCellItemKey(rowKey, columnKey)` for a `'comparison'` cell (NOT an ad
+ *  hoc `"<rowKey>:<columnKey>"` join — a plain colon join is ambiguous whenever a row or column
+ *  key contains a colon itself). Always an existing author-assigned identifier, never inferred
+ *  from pixels, source strings, or a DOM selector. */
+export interface OverlayAddress {
+  pageId: string;
+  slot: OverlaySlot;
+  itemKey: string;
+}
+
+const OVERLAY_SLOTS: readonly OverlaySlot[] = ['variants', 'states', 'comparison'];
+
+/** `encodeURIComponent` leaves `.` untouched (it's an unreserved character), which would let a
+ *  literal `.` inside a segment collide with the `.`-joined encoding below; escape it too so
+ *  splitting on `.` is always safe. `decodeURIComponent` already reverses `%2E` with no special
+ *  casing needed. */
+function encodeSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(/\./g, '%2E');
+}
+
+/** The query param a `BoundedOverlayViewport`'s child document is opened with — distinct from
+ *  `CatalogShell`'s own page-routing hash (`#PageId`), which the child document's URL also keeps
+ *  (see `overlayViewportHrefSuffix`) so the SAME app entry still resolves the right page/providers
+ *  before the viewport component itself ever runs. */
+export const OVERLAY_ADDRESS_PARAM = 'ds-viewer-overlay';
+
+/** `pageId.slot.itemKey`, each segment percent-encoded — one URL-safe token for a query value. */
+export function encodeOverlayAddress(address: OverlayAddress): string {
+  return [address.pageId, address.slot, address.itemKey].map(encodeSegment).join('.');
+}
+
+/** The inverse of `encodeOverlayAddress` — `undefined` for anything that isn't exactly three
+ *  non-empty segments with a recognized slot: the same "malformed means absent" recovery
+ *  `catalogNavigation.ts`'s `idFromHash` uses for an unknown page fragment, rather than guessing
+ *  at a partial or corrupted address. */
+export function decodeOverlayAddress(value: string): OverlayAddress | undefined {
+  const parts = value.split('.');
+  if (parts.length !== 3) return undefined;
+  let decoded: string[];
+  try {
+    decoded = parts.map((part) => decodeURIComponent(part));
+  } catch {
+    return undefined;
+  }
+  const [pageId, slot, itemKey] = decoded;
+  if (!pageId || !itemKey) return undefined;
+  if (!OVERLAY_SLOTS.includes(slot as OverlaySlot)) return undefined;
+  return { pageId, slot: slot as OverlaySlot, itemKey };
+}
+
+/** Reads `OVERLAY_ADDRESS_PARAM` out of a URL search string (e.g. `window.location.search`);
+ *  `undefined` when the param is absent or its value doesn't decode. A trailing `#fragment` is
+ *  dropped first — `URLSearchParams` has no notion of a URL fragment, so without this a caller
+ *  that (like `overlayViewportHrefSuffix`'s own combined query+hash string) passes one along
+ *  would see it swallowed into the last param's value instead of ignored. */
+export function overlayAddressFromSearch(search: string): OverlayAddress | undefined {
+  const raw = new URLSearchParams(search.split('#')[0]).get(OVERLAY_ADDRESS_PARAM);
+  return raw ? decodeOverlayAddress(raw) : undefined;
+}
+
+export function overlayAddressesEqual(a: OverlayAddress, b: OverlayAddress): boolean {
+  return a.pageId === b.pageId && a.slot === b.slot && a.itemKey === b.itemKey;
+}
+
+/** The query + hash suffix that boots the SAME app entry directly into this address's
+ *  selected-document mode: the overlay param (so the `BoundedOverlayViewport` instance that
+ *  matches this address renders its children inline instead of framing itself again) plus the
+ *  page's own routing hash (so `CatalogShell`'s existing hash-based routing still resolves the
+ *  right `SectionDef`/providers before `findOverlayNode` narrows further). */
+export function overlayViewportHrefSuffix(address: OverlayAddress): string {
+  return `?${OVERLAY_ADDRESS_PARAM}=${encodeURIComponent(encodeOverlayAddress(address))}#${encodeURIComponent(address.pageId)}`;
+}
+
+/** `'inline'`: render the wrapped demo directly, no frame — either this isn't a web runtime (no
+ *  same-origin child-document mechanism to offer; see `BoundedOverlayViewport`'s own doc comment)
+ *  or `currentSearch` already names this exact address, meaning this instance IS the selected
+ *  child document's own addressed specimen and must not frame itself again (recursion guard).
+ *  `'frame'`: open `href` — the current pathname plus this address's query+hash — in a bounded
+ *  child document. */
+export type OverlayViewportDecision = { mode: 'inline' } | { mode: 'frame'; href: string };
+
+export function resolveOverlayViewport(args: {
+  address: OverlayAddress;
+  isWeb: boolean;
+  /** The hosting document's current `location.search` (e.g. `window.location.search`). */
+  currentSearch: string;
+  /** The hosting document's current `location.pathname` — same pathname the child document loads,
+   *  since this viewer is a single-page app whose page lives in the hash, not the path. */
+  pathname: string;
+}): OverlayViewportDecision {
+  if (!args.isWeb) return { mode: 'inline' };
+  const current = overlayAddressFromSearch(args.currentSearch);
+  if (current && overlayAddressesEqual(current, args.address)) return { mode: 'inline' };
+  return { mode: 'frame', href: `${args.pathname}${overlayViewportHrefSuffix(args.address)}` };
+}
+
+/** The authored `node` an `OverlayAddress` points at, or `undefined` for a stale/unknown address
+ *  (a removed example, a renamed key, a typo) — `CatalogShell`'s chromeless selected-document
+ *  render shows an honest "unavailable" recovery rather than rendering nothing silently. */
+export function findOverlayNode(sections: readonly SectionDef<string>[], address: OverlayAddress): React.ReactNode | undefined {
+  const def = sections.find((section) => section.id === address.pageId);
+  if (!def) return undefined;
+  if (address.slot === 'variants') return def.variants?.items.find((item) => item.key === address.itemKey)?.node;
+  if (address.slot === 'states') return def.states?.items.find((item) => item.key === address.itemKey)?.node;
+  // Matched by recomputing each cell's own canonical key, never by splitting `address.itemKey` —
+  // a row/column key may itself contain any delimiter this module could pick.
+  return def.comparison?.cells.find((cell) => comparisonCellItemKey(cell.rowKey, cell.columnKey) === address.itemKey)?.node;
+}
+
+/** The canonical, unambiguous `itemKey` for one comparison cell's row+column — this module's own
+ *  counterpart to `comparison.ts`'s `cellKey` (not imported from there: a VALUE import between two
+ *  pure `.ts` logic modules here can't carry the `.ts` extension that both Node's direct test run
+ *  and `kit-host`'s bundler-mode typechecker require/reject at once — `import type` is exempt
+ *  since it is fully erased, which is why `./types.ts` above is fine). Exported so a `.tsx` call
+ *  site building a `'comparison'` `OverlayAddress` constructs the exact same key this module looks
+ *  it up by — a plain `"${rowKey}:${columnKey}"` join is ambiguous whenever a row or column key
+ *  contains a colon itself. */
+export function comparisonCellItemKey(rowKey: string, columnKey: string): string {
+  return `${rowKey}${columnKey}`;
+}
+
+/** Usable CSS pixel dimensions for a bounded overlay viewport: finite and strictly positive.
+ *  `NaN`/`Infinity`/zero/negative (a measurement that hasn't settled yet, a miscomputed layout
+ *  value, an author typo) must never reach `BoundedOverlayViewport`'s iframe — an iframe sized to
+ *  a meaningless bound is worse than no iframe, since it still renders (and can still mount the
+ *  wrapped demo's overlay) at some browser-decided fallback size instead of honestly reporting
+ *  unavailable. */
+export function isFiniteOverlaySize(width: number, height: number): boolean {
+  return Number.isFinite(width) && width > 0 && Number.isFinite(height) && height > 0;
+}
+
+/** The framed stage's own box dimensions. `height` is exact — the production overlay's full
+ *  usable height is never renegotiated by its owner. `width` is only a MAXIMUM: `'100%'` lets the
+ *  stage fill and shrink to whatever its real owning specimen cell actually gives it, capped at
+ *  `width` when the owner has at least that much room. A fixed pixel width here previously let the
+ *  stage overflow a narrower owner (e.g. a 240px comparison cell at a narrow browser width) while
+ *  that owner's own `overflow: hidden` silently clipped the excess — a passing-looking but false
+ *  containment, not the honest unavailable/shrink this design requires. */
+export function overlayStageDimensions(width: number, height: number): { width: '100%'; maxWidth: number; height: number } {
+  return { width: '100%', maxWidth: width, height };
+}

package/native/catalog/pageApi.ts

@@ -31,8 +31,12 @@ export interface CatalogPageInput<TId extends string = string> {
   specimenSize?: SpecimenSize;
   specimenSurface?: SpecimenSurfaceKind;
   previewWidths?: PreviewWidths;
+  /** See `SectionDef.previewLayout`. */
+  previewLayout?: 'frames' | 'table';
   hide?: SectionDef['hide'];
   composedOf?: ComposedOfEntry[];
+  /** See `SectionDef.intentionalStaticPreview`. */
+  intentionalStaticPreview?: { reason: string };
   /** Export name this page documents; defaults to `id` for component pages. */
   component?: string;
   /** Sidebar group label. */
@@ -168,8 +172,10 @@ export function buildCatalogSections<TId extends string>(
       specimenSize: page.specimenSize,
       specimenSurface: page.specimenSurface,
       previewWidths: page.previewWidths,
+      previewLayout: page.previewLayout,
       hide: component ? page.hide : { ...page.hide, props: true },
       composedOf: page.composedOf,
+      intentionalStaticPreview: page.intentionalStaticPreview,
     };
   });