@krapwoo/ds-viewer 0.4.6 → 0.4.8

package/native/catalog/ComparisonList.tsx

@@ -3,6 +3,7 @@ import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { MATRIX_LAYOUT, listGeometry, type ListItem } from './comparison';
 import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { SpecimenAddressProvider } from './SpecimenAddress';
 import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
@@ -19,10 +20,13 @@ export function ComparisonList({
   label,
   maxColumns,
   surface = DEFAULT_SPECIMEN_SURFACE,
+  pageId,
 }: {
   items: ListItem[];
   size: SpecimenSize;
   label: string;
+  /** The page these examples belong to, so a device frame inside one can address it. */
+  pageId?: string;
   maxColumns?: 1 | 2 | 3 | 4 | 5;
   surface?: SpecimenSurfaceKind;
 }) {
@@ -61,8 +65,10 @@ export function ComparisonList({
                   <View style={styles.caption}>
                     <Text style={styles.captionText}>{item.label}</Text>
                   </View>
-                  <SpecimenSurface surface={surface} style={styles.specimen}>
-                    <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                  <SpecimenSurface surface={item.surface ?? surface} style={styles.specimen}>
+                    <SpecimenAddressProvider address={pageId && item.slot ? { pageId, slot: item.slot, itemKey: item.key } : undefined}>
+                      <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
+                    </SpecimenAddressProvider>
                   </SpecimenSurface>
                 </View>
               );

package/native/catalog/PhoneFrame.tsx

@@ -1,31 +1,100 @@
-import React from 'react';
-import { View, StyleSheet } from 'react-native';
-import { CATALOG_RADIUS, CATALOG_COLOR } from './tokens';
+import React, { useState } from 'react';
+import { Platform, StyleSheet, Text, View, type LayoutChangeEvent } from 'react-native';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { DEVICE_FRAME, deviceFrameScale } from './deviceFrame';
+import { resolveOverlayViewport } from './overlayViewport';
+import { useSpecimenAddress } from './SpecimenAddress';
 
-const WIDTH_CAP = 280;
-const HEIGHT = 480;
+function isWeb(): boolean {
+  return Platform.OS === 'web' && typeof window !== 'undefined';
+}
 
 /**
- * A bounded "phone screen" preview frame — contains a live demo (e.g. a BottomSheet or Dropdown's
- * picker) inside a fixed-size box instead of letting its absolutely-positioned overlay cover the
- * whole documentation page. Purely a documentation device: a real app screen never needs to fake
- * being a phone screen inside itself, since the actual device viewport already does that job — that's
- * why this lives in the catalog framework (like VariantGroup/TokenRow) rather than the host app's
- * own component library (a downstream app would never import this file).
+ * A real phone screen for a live demo: a screen, a sheet, a dialog, a toast sliding in.
+ *
+ * - **Real dimensions.** The demo lays out in a viewport of exactly `DEVICE_FRAME` (iPhone SE,
+ *   375 × 667 points). A cell narrower than that scales the whole device down rather than
+ *   squeezing its layout.
+ * - **A real viewport on the web.** Inside a catalog example, the frame opens that one example in
+ *   its own child document at device size (the same mechanism as `BoundedOverlayViewport`). Its
+ *   window is the device: anything that portals to the document body, such as React Native's
+ *   `Modal`, opens inside the phone instead of over the whole catalog, and the window reports the
+ *   device's size.
+ * - **Elsewhere** (native, or a frame outside a catalog example) it renders inline at the same
+ *   size; overlays that portal to the body are then not contained.
  *
- * `width: '100%'` capped at 280 (not a fixed width) — a fixed px width could exceed the card's real
- * content width once the surrounding column shrinks below its own max-width cap (it does at common
- * viewport sizes), overflowing past the card's edge since the card itself doesn't clip.
+ * Centred in its cell by its own full-width measuring wrapper, whatever the cell's alignment.
+ * Purely a documentation device: a real app screen never frames itself, so this lives in the
+ * catalog framework rather than in an app's component library.
  */
 export function PhoneFrame({ children }: { children: React.ReactNode }) {
-  return <View style={styles.frame}>{children}</View>;
+  const address = useSpecimenAddress();
+  const [available, setAvailable] = useState(0);
+  const [status, setStatus] = useState<'loading' | 'ready' | 'unavailable'>('loading');
+  const onLayout = (event: LayoutChangeEvent) => {
+    const width = Math.floor(event.nativeEvent.layout.width);
+    if (width > 0 && width !== available) setAvailable(width);
+  };
+  const scale = deviceFrameScale(available);
+  // Until the cell is measured, fit it at the device's proportions rather than drawing at full size
+  // for a frame (which would briefly overflow a cell narrower than the device).
+  const box = available > 0
+    ? { width: DEVICE_FRAME.width * scale, height: DEVICE_FRAME.height * scale }
+    : { width: '100%' as const, maxWidth: DEVICE_FRAME.width, aspectRatio: DEVICE_FRAME.width / DEVICE_FRAME.height };
+
+  if (isWeb() && address) {
+    const decision = resolveOverlayViewport({
+      address,
+      isWeb: true,
+      currentSearch: window.location.search,
+      pathname: window.location.pathname,
+    });
+    // This document is the device itself: fill it edge to edge.
+    if (decision.mode === 'inline') return <View style={styles.screenFill}>{children}</View>;
+    return (
+      <View style={styles.measure} onLayout={onLayout}>
+        <View style={[styles.device, box]}>
+          {status !== 'ready' && (
+            <Text style={styles.status}>{status === 'unavailable' ? 'This example is unavailable right now.' : 'Loading…'}</Text>
+          )}
+          {
+            // react-native-web has no iframe primitive; this is a plain same-origin iframe.
+            React.createElement('iframe' as unknown as string, {
+              src: decision.href,
+              title: `${address.pageId} on ${DEVICE_FRAME.name} (${DEVICE_FRAME.width} × ${DEVICE_FRAME.height})`,
+              style: {
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: DEVICE_FRAME.width,
+                height: DEVICE_FRAME.height,
+                border: 0,
+                transform: `scale(${scale})`,
+                transformOrigin: '0 0',
+                visibility: status === 'ready' ? 'visible' : 'hidden',
+              },
+              onLoad: () => setStatus('ready'),
+              onError: () => setStatus('unavailable'),
+            })
+          }
+        </View>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.measure} onLayout={onLayout}>
+      <View style={[styles.device, box]}>
+        <View style={[styles.screenInline, { transform: [{ scale }], transformOrigin: 'top left' } as object]}>{children}</View>
+      </View>
+    </View>
+  );
 }
 
 const styles = StyleSheet.create({
-  frame: {
-    width: '100%',
-    maxWidth: WIDTH_CAP,
-    height: HEIGHT,
+  // Spans the cell so the device can be measured against it and centred in it.
+  measure: { width: '100%', alignItems: 'center' },
+  device: {
     borderRadius: CATALOG_RADIUS.md,
     borderWidth: StyleSheet.hairlineWidth,
     borderColor: CATALOG_COLOR.border,
@@ -34,4 +103,25 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
+  screenInline: {
+    width: DEVICE_FRAME.width,
+    height: DEVICE_FRAME.height,
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+  },
+  // The child document's whole window is the device screen: exactly the device's height, never
+  // more, so a `flex: 1` scroll area inside a demo shrinks to fit and scrolls instead of growing.
+  screenFill: {
+    width: '100%',
+    height: DEVICE_FRAME.height,
+    backgroundColor: CATALOG_COLOR.surfacePressed,
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+  },
+  status: { position: 'absolute', fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
 });

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,42 +40,98 @@ 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) {
+    // Full-width pages with no component API (token galleries, and whole screens such as a
+    // starter kit's Patterns) still disclose what they're built from when they say so.
     return (
       <View style={styles.card}>
         <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
         {def.path && <Fact label="Source" value={def.path} mono />}
+        {def.composedOf && def.composedOf.length > 0 && (
+          <>
+            <Text style={styles.subheading}>Composition</Text>
+            <CompositionFacts composedOf={def.composedOf} />
+          </>
+        )}
       </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 +149,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 +169,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

@@ -6,9 +6,10 @@ import { ComparisonGroups } from './ComparisonGroups';
 import { ComparisonList } from './ComparisonList';
 import { ReferenceDetails } from './ReferenceDetails';
 import { SpecimenSurface } from './SpecimenSurface';
+import { SpecimenAddressProvider } from './SpecimenAddress';
 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 +104,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,18 +132,57 @@ 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':
       return <ComparisonGrid def={block.comparison} size={block.size} sectionId={def.id} surface={surface} />;
     case 'grouped':
-      return <ComparisonGroups groups={block.groups} size={block.size} label={def.id} surface={surface} />;
+      return <ComparisonGroups groups={block.groups} size={block.size} label={def.id} surface={surface} pageId={def.id} />;
     case 'list':
-      return <ComparisonList items={block.items} size={block.size} label={`${def.id}: ${block.title}`} maxColumns={block.maxColumns} surface={surface} />;
+      return <ComparisonList items={block.items} size={block.size} label={`${def.id}: ${block.title}`} maxColumns={block.maxColumns} surface={surface} pageId={def.id} />;
     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 ? (
+        <SpecimenAddressProvider address={{ pageId: def.id, slot: 'preview', itemKey: 'preview' }}>
+          <Preview render={def.render} widths={block.widths} surface={def.tokenGallery ? undefined : surface} layout={def.previewLayout === 'table' ? 'table' : undefined} />
+        </SpecimenAddressProvider>
+      ) : null;
     case 'tokenSections':
       return <TokenSections sections={block.sections} columns={block.columns} />;
     default:
@@ -331,7 +374,8 @@ const styles = StyleSheet.create({
   blocks: { gap: CATALOG_LAYOUT.blockGap, marginBottom: CATALOG_LAYOUT.blockGap },
   blocksSide: { flexDirection: 'row', alignItems: 'flex-start' },
   blockFill: { flex: 1, minWidth: 0 },
-  frames: { flexDirection: 'row', flexWrap: 'wrap', gap: CATALOG_SPACE.xl, alignItems: 'flex-start' },
+  // Centred in the card, like every other example (a single phone-width frame used to sit left).
+  frames: { flexDirection: 'row', flexWrap: 'wrap', gap: CATALOG_SPACE.xl, alignItems: 'flex-start', justifyContent: 'center' },
   frame: { maxWidth: '100%', gap: CATALOG_SPACE.sm },
   frameLabel: {
     fontSize: CATALOG_TYPE.tableHeader,
@@ -356,5 +400,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/SpecimenAddress.tsx

@@ -0,0 +1,15 @@
+import React, { createContext, useContext } from 'react';
+import type { OverlayAddress } from './overlayViewport';
+
+const SpecimenAddressContext = createContext<OverlayAddress | undefined>(undefined);
+
+/** Tells the example rendered inside it which catalog example it is (page, slot, item key), so a
+ *  `PhoneFrame` in it can open that one example in its own device-sized document. Set by the
+ *  catalog's own list, grid and preview renderers, and by the child document itself. */
+export function SpecimenAddressProvider({ address, children }: { address: OverlayAddress | undefined; children: React.ReactNode }) {
+  return <SpecimenAddressContext.Provider value={address}>{children}</SpecimenAddressContext.Provider>;
+}
+
+export function useSpecimenAddress(): OverlayAddress | undefined {
+  return useContext(SpecimenAddressContext);
+}

package/native/catalog/SpecimenSurface.tsx

@@ -1,9 +1,13 @@
 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, overflowsCell, paintedExtent, shouldCenterFilledContent, specimenContentAlignItems,
+  specimenContentBoundedStyle, visibleBoxes, type LayoutBox,
+} from './specimenSurfaceStyle';
+import { useSpecimenAddress } from './SpecimenAddress';
 import { blendsIntoCell, measurePaintedBoxes } from './specimenFill';
-import type { SpecimenSurfaceKind } from './types';
+import type { SpecimenAlign, SpecimenSurfaceKind } from './types';
 
 type Browser = {
   getComputedStyle?: (element: unknown) => never;
@@ -65,9 +69,80 @@ 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. */
+type MeasurableNode = {
+  getBoundingClientRect: () => { left: number; right: number; width: number };
+  children: ArrayLike<MeasurableNode>;
+  childElementCount: number;
+  tagName: string;
+};
+
+/** The example's element tree as `LayoutBox`es (up to 400 elements), so `visibleBoxes` can skip
+ *  what scrolling or clipping containers hide. */
+function readTree(root: MeasurableNode, browser: Browser): LayoutBox {
+  let budget = 400;
+  const read = (el: MeasurableNode): LayoutBox => {
+    const rect = el.getBoundingClientRect();
+    const style = browser.getComputedStyle!(el) as unknown as { backgroundColor: string; borderTopWidth: string; visibility: string; overflowX: string };
+    const kids: LayoutBox[] = [];
+    const children = el.children;
+    for (let i = 0; i < children.length && budget > 0; i++) {
+      budget -= 1;
+      const child = children[i];
+      if (child.getBoundingClientRect().width < 1) continue;
+      kids.push(read(child));
+    }
+    return {
+      left: rect.left,
+      right: rect.right,
+      painted:
+        style.visibility !== 'hidden' &&
+        (el.childElementCount === 0 || el.tagName === 'svg' || el.tagName === 'IFRAME' ||
+          style.backgroundColor !== 'rgba(0, 0, 0, 0)' || parseFloat(style.borderTopWidth) > 0),
+      clips: style.overflowX === 'hidden' || style.overflowX === 'auto' || style.overflowX === 'scroll' || style.overflowX === 'clip',
+      children: kids,
+    };
+  };
+  return read(root);
+}
+
+export function SpecimenContent({ fill, align, children }: { fill?: boolean; align?: SpecimenAlign; children: React.ReactNode }) {
+  // After layout (browser only): a `fill` example whose visible content is narrower than the cell
+  // (a fixed-width skeleton, a tooltip around a small trigger) is centred instead of sitting
+  // against the leading edge; an explicit `align` always wins. And in development, an example
+  // wider than its cell logs a warning naming a wider `specimenSize`.
+  const address = useSpecimenAddress();
+  const ref = useRef<View>(null);
+  const [centerNarrow, setCenterNarrow] = useState(false);
+  const warned = useRef(false);
+  const measure = useCallback(() => {
+    const browser = globalThis as unknown as Browser;
+    const node = ref.current as unknown as MeasurableNode | null;
+    if (!browser.Element || !browser.getComputedStyle || !node?.getBoundingClientRect) return;
+    const wrapperWidth = node.getBoundingClientRect().width;
+    const visible = paintedExtent(visibleBoxes(readTree(node, browser)));
+    if (fill && align === undefined && !centerNarrow && shouldCenterFilledContent(visible, wrapperWidth)) setCenterNarrow(true);
+    if ((globalThis as { __DEV__?: boolean }).__DEV__ && !warned.current && overflowsCell(visible, wrapperWidth)) {
+      warned.current = true;
+      console.warn(
+        `[Catalog] ${address ? `${address.pageId} (${address.itemKey})` : 'An example'} is ${Math.round(visible)}px wide in a ${Math.round(wrapperWidth)}px cell, so it's cut off. Give the page a wider specimenSize ('regular' or 'wide').`,
+      );
+    }
+  }, [fill, align, centerNarrow, address]);
+  if (fill) {
+    const alignItems = centerNarrow ? 'center' : specimenContentAlignItems(fill, align);
+    return <View ref={ref} onLayout={measure} style={[SPECIMEN_SURFACE_WIDTH_STYLE, { alignItems }]}>{children}</View>;
+  }
+  return <View ref={ref} onLayout={measure} style={specimenContentBoundedStyle(align)}>{children}</View>;
 }
 
 // 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token); there is no dark-surface token.
@@ -77,8 +152,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 },
-});