@krapwoo/ds-viewer 0.4.9 → 0.6.0

package/native/catalog/comparison.ts

@@ -17,7 +17,6 @@ import type React from 'react';
  *  content width is a 1280px viewport minus the 264px sidebar and 32px side padding. */
 export const MATRIX_LAYOUT = {
   rowHeaderWidth: 120,
-  columnMaxWidth: 402,
   cellPadding: 16,
   rowMinHeight: 150,
   laptopContentWidth: 952,
@@ -43,8 +42,9 @@ export const REFERENCE_MIN_COLUMN_WIDTH = 280;
  *  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 };
+/** Smallest column or cell width per specimen size. `wide` is phone width as a minimum, not a
+ *  maximum: cells share their container equally above it. */
+export const COLUMN_MIN_WIDTH: Record<SpecimenSize, number> = { compact: 160, regular: 240, wide: 402, page: 512 };
 
 /** `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) ? ... :
@@ -106,12 +106,11 @@ export function gridColumnLimit(size: SpecimenSize): number {
   return Math.floor((MATRIX_LAYOUT.laptopContentWidth - MATRIX_LAYOUT.rowHeaderWidth) / COLUMN_MIN_WIDTH[size]);
 }
 
-export function gridWidthBounds(columnCount: number, size: SpecimenSize): { minWidth: number; maxWidth: number } {
-  const n = Math.max(0, columnCount);
-  return {
-    minWidth: MATRIX_LAYOUT.rowHeaderWidth + n * COLUMN_MIN_WIDTH[size],
-    maxWidth: MATRIX_LAYOUT.rowHeaderWidth + n * MATRIX_LAYOUT.columnMaxWidth,
-  };
+/** The narrowest a grid card may be: the row header plus every column at its minimum. A card wider
+ *  than its container scrolls inside itself; above this width the columns share the container
+ *  equally, because the phone-width cap belongs to the specimen inside a cell, not to the column. */
+export function gridMinWidth(columnCount: number, size: SpecimenSize): number {
+  return MATRIX_LAYOUT.rowHeaderWidth + Math.max(0, columnCount) * COLUMN_MIN_WIDTH[size];
 }
 
 export interface ListGeometry {
@@ -123,7 +122,8 @@ export interface ListGeometry {
 }
 
 /** Balanced wrapping for a one-axis list inside a single bordered card (1px outer border). Each
- *  cell's 1px divider sits inside its own width, so no cell is ever wider than 402px. Uses as few
+ *  cell's 1px divider sits inside its own width. Cells share the container equally — phone width
+ *  caps the specimen inside a cell, not the cell. Uses as few
  *  rows as fit, then spreads items evenly across them so a short last row leaves as little empty
  *  space as possible. `fillers` blank cells complete the last row. `columnCap` (from
  *  `VariantSlot.maxColumns`) only ever lowers the natural, width-based column count — a narrow
@@ -139,7 +139,7 @@ export function listGeometry(itemCount: number, availableWidth: number, size: Sp
   const rows = Math.ceil(itemCount / maxColumns);
   const columns = Math.ceil(itemCount / rows);
   const fitted = Math.floor(inner / columns);
-  const cellWidth = size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : Math.max(min, Math.min(MATRIX_LAYOUT.columnMaxWidth, fitted));
+  const cellWidth = Math.max(min, fitted);
   return {
     columns,
     rows,
@@ -253,7 +253,7 @@ export type PresentationBlock =
   | { kind: 'grid'; title: string; size: SpecimenSize; comparison: ComparisonDef }
   | { kind: 'grouped'; title: string; size: SpecimenSize; groups: ListGroup[] }
   | { kind: 'list'; title: string; size: SpecimenSize; items: ListItem[]; maxColumns?: 1 | 2 | 3 | 4 | 5 }
-  | { kind: 'preview'; title: string; widths: PreviewWidths }
+  | { kind: 'preview'; title: string; widths: PreviewWidths; layout?: 'frames' | 'table' }
   | { kind: 'tokenSections'; title: string; sections: TokenSection[]; columns: 1 | 2 | 3 }
   | { kind: 'empty'; title: string; message: string };
 
@@ -278,10 +278,11 @@ function slotColumnCap(slot: VariantSlot): { maxColumns?: 1 | 2 | 3 | 4 | 5 } {
   return slot.itemsFill ? { maxColumns: FILLED_SLOT_MAX_COLUMNS } : {};
 }
 
-function slotItems(slot: VariantSlot, from: 'variants' | 'states'): ListItem[] {
+function slotItems(slot: VariantSlot, from: 'variants' | 'states', fillByDefault = false): ListItem[] {
   // 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, slot: from, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill, surface: item.surface, align: item.align }));
+  // Page-width examples (layouts wider than a phone) fill their cell unless they say otherwise.
+  return slot.items.map((item) => ({ key: item.key, slot: from, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill ?? (fillByDefault || undefined), surface: item.surface, align: item.align }));
 }
 
 /** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
@@ -350,11 +351,11 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
         kind: 'list',
         title: 'Variants',
         size: slotSize(def, def.variants),
-        items: slotItems(def.variants, 'variants'),
+        items: slotItems(def.variants, 'variants', def.specimenSize === 'page'),
         ...slotColumnCap(def.variants),
       });
     } else if (def.render) {
-      blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
+      blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths), ...(def.previewLayout ? { layout: def.previewLayout } : {}) });
     }
   }
 
@@ -364,7 +365,7 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
       kind: 'list',
       title: secondary ? 'Other configurations' : 'States / configurations',
       size: slotSize(def, states),
-      items: slotItems(states, 'states'),
+      items: slotItems(states, 'states', def.specimenSize === 'page'),
       ...slotColumnCap(states),
     });
   }
@@ -377,9 +378,11 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
 
 export interface PlacementBlock {
   kind: PresentationBlock['kind'];
-  /** Rendered width of the block's card (lists hug their columns; everything else fills). */
-  width?: number;
-  /** Measured height of the whole block, label included, while stacked. */
+  /** The narrowest this block renders without its cells dropping below their minimum, from
+   *  `blockMinWidth`. A block that can only fill a whole row (a 'full' preview, token sections)
+   *  reports `Infinity` and never shares one. */
+  minWidth?: number;
+  /** Measured height of the whole block, label included, while stacked at the full width. */
   height: number;
   /** For a list: item count, specimen size, and any explicit column cap, so its side-by-side
    *  height can be predicted from the same geometry the rendered list uses. */
@@ -388,20 +391,61 @@ export interface PlacementBlock {
   maxColumns?: 1 | 2 | 3 | 4 | 5;
 }
 
-/** Side by side or stacked, for a page with exactly two blocks. Tries both and keeps the shorter;
- *  stays stacked unless side by side saves at least PLACEMENT_MIN_SAVING. Only a list can move
- *  beside a first block that hugs its content, and only when its cells keep their minimum width. */
+/** The narrowest a block renders at. Every card fills the column it is given, so this is a floor,
+ *  not the width it will take: below it a grid scrolls inside itself and a list would push its
+ *  cells under their minimum. `Infinity` means the block can only have a whole row. */
+/** What a preview card adds around its frames: `padding` (CATALOG_SPACE.xl) and a 1px border on
+ *  each side. `blockMinWidth` must add it, or a preview is offered a half-row that fits its frame
+ *  only after the card has taken its share, and the frame silently renders under phone width.
+ *  SectionBlock's `previewCard` style is built from these, so the two cannot drift. */
+export const PREVIEW_CARD_CHROME = { padding: 24, border: 1 } as const;
+/** The same for a `previewLayout: 'table'` card: no outer padding, a 1px border, and each cell
+ *  carries `cellPadding` on both sides of its frame. */
+export const TABLE_PREVIEW_CHROME = { padding: MATRIX_LAYOUT.cellPadding, border: 1 } as const;
+/** Total horizontal chrome for one preview frame in either card. */
+export function previewChrome(layout: 'frames' | 'table' | undefined): number {
+  const chrome = layout === 'table' ? TABLE_PREVIEW_CHROME : PREVIEW_CARD_CHROME;
+  return 2 * chrome.padding + 2 * chrome.border;
+}
+
+export function blockMinWidth(block: PresentationBlock): number {
+  switch (block.kind) {
+    case 'grid':
+      return gridMinWidth(axisItems(block.comparison.columns).length, block.size);
+    case 'grouped':
+      return MATRIX_LAYOUT.rowHeaderWidth + Math.max(1, ...block.groups.map((g) => g.items.length)) * COLUMN_MIN_WIDTH[block.size] + 2;
+    case 'list':
+      // One column: a list always wraps further rather than going below its size's minimum.
+      return COLUMN_MIN_WIDTH[block.size] + 2;
+    case 'preview':
+      // A 'full' preview is the row. Otherwise the *widest* frame sets the minimum: the frames wrap,
+      // so each one sits on its own row and `maxWidth: '100%'` would squeeze any frame wider than
+      // the card. The card's own chrome counts too — a frame keeps its width only if the row also
+      // covers the padding and border around it.
+      return block.widths === 'full' ? Infinity : Math.max(...block.widths) + previewChrome(block.layout);
+    default:
+      return Infinity;
+  }
+}
+
+/** The height a block takes at `width`, from the height measured while stacked at `available`.
+ *  Only a list reflows: its rows change with the width, and every row is the same height. */
+function heightAtWidth(block: PlacementBlock, width: number, available: number): number {
+  if (block.kind !== 'list' || !block.itemCount || !block.size) return block.height;
+  const stackedRows = listGeometry(block.itemCount, available, block.size, block.maxColumns).rows;
+  const rows = listGeometry(block.itemCount, width, block.size, block.maxColumns).rows;
+  return (block.height / Math.max(1, stackedRows)) * rows;
+}
+
+/** Side by side or stacked, for a page with exactly two blocks. Side by side splits the row into
+ *  two equal columns and each block fills its own, so it is only possible when both blocks keep
+ *  their minimum width in half a row; it is only taken when it saves at least PLACEMENT_MIN_SAVING
+ *  against stacking, measuring each block at the width it would actually have. */
 export function choosePlacement({ available, gap, first, second }: { available: number; gap: number; first: PlacementBlock; second: PlacementBlock }): 'side' | 'stacked' {
-  if (second.kind !== 'list' || !second.itemCount || !second.size) return 'stacked';
-  const firstWidth = first.width ?? available;
-  if (firstWidth > available * 0.7) return 'stacked';
-  const room = available - firstWidth - gap;
-  const minCell = second.size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : COLUMN_MIN_WIDTH[second.size];
-  if (room < minCell + 2) return 'stacked';
-  const stackedRows = listGeometry(second.itemCount, available, second.size, second.maxColumns).rows;
-  const sideRows = listGeometry(second.itemCount, room, second.size, second.maxColumns).rows;
-  const rowHeight = second.height / Math.max(1, stackedRows);
-  const sideHeight = Math.max(first.height, sideRows * rowHeight);
+  const half = Math.floor((available - gap) / 2);
+  if (half <= 0) return 'stacked';
+  if ((first.minWidth ?? Infinity) > half || (second.minWidth ?? Infinity) > half) return 'stacked';
+  const sideHeight = Math.max(heightAtWidth(first, half, available), heightAtWidth(second, half, available));
   const stackedHeight = first.height + gap + second.height;
   return sideHeight <= stackedHeight - PLACEMENT_MIN_SAVING ? 'side' : 'stacked';
 }

package/native/catalog/index.ts

@@ -31,6 +31,9 @@ export { TokenSections, TokenGrid, TokenTile } from './TokenLayouts';
 export { DividedStack } from './DividedStack';
 export { Swatch } from './Swatch';
 export { PhoneFrame } from './PhoneFrame';
+export { PhoneScreen } from './PhoneScreen';
+export { OverlayDemo } from './OverlayDemo';
+export { CatalogButton } from './CatalogButton';
 export { BoundedOverlayViewport } from './BoundedOverlayViewport';
 export type { BoundedOverlayViewportProps } from './BoundedOverlayViewport';
 export { comparisonCellItemKey } from './overlayViewport';
@@ -47,7 +50,7 @@ export type {
 } from './types';
 export { UpdatePanel } from './UpdatePanel';
 export { UPDATE_PAGE_ID } from './catalogNavigation';
-export type { UpdateNotice } from './types';
+export type { UpdateNotice, VersionStatus, AutoCheckSource } from './types';
 export type { ListGroup, ListItem } from './comparison';
 export {
   CATALOG_TYPE,

package/native/catalog/overlayDemoState.ts

@@ -0,0 +1,8 @@
+/** What `OverlayDemo` shows for a given open state. Kept free of runtime imports for `node --test`. */
+export function overlayTrigger(
+  open: boolean,
+  options: { triggerLabel: string | ((open: boolean) => string); keepTrigger?: boolean },
+): { visible: boolean; label: string } {
+  const label = typeof options.triggerLabel === 'function' ? options.triggerLabel(open) : options.triggerLabel;
+  return { visible: !open || Boolean(options.keepTrigger), label };
+}

package/native/catalog/pageApi.ts

@@ -37,6 +37,8 @@ export interface CatalogPageInput<TId extends string = string> {
   composedOf?: ComposedOfEntry[];
   /** See `SectionDef.intentionalStaticPreview`. */
   intentionalStaticPreview?: { reason: string };
+  /** See `SectionDef.internalProps`. */
+  internalProps?: Record<string, string>;
   /** Export name this page documents; defaults to `id` for component pages. */
   component?: string;
   /** Sidebar group label. */
@@ -175,6 +177,7 @@ export function buildCatalogSections<TId extends string>(
       previewLayout: page.previewLayout,
       hide: component ? page.hide : { ...page.hide, props: true },
       composedOf: page.composedOf,
+      internalProps: page.internalProps,
       intentionalStaticPreview: page.intentionalStaticPreview,
     };
   });

package/native/catalog/specimenSurfaceStyle.ts

@@ -142,3 +142,14 @@ export function visibleBoxes(root: LayoutBox): { left: number; right: number; pa
   walk(root, true);
   return out;
 }
+
+/** The widest a filled example gets: a phone's content width (402 minus 16 px padding each side).
+ *  Fields, dropdowns and full-width buttons fill a phone's width in real use, so a wider cell would
+ *  misrepresent them. Examples that aren't filled keep their own width. */
+export const FILLED_CONTENT_MAX_WIDTH = 370;
+
+/** The wrapper style for a filled example: full width up to `FILLED_CONTENT_MAX_WIDTH`, centred.
+ *  `capped: false` (page-width examples) fills the whole cell. */
+export function filledContentStyle(capped = true): { width: '100%'; maxWidth?: number; alignSelf: 'center' } {
+  return capped ? { width: '100%', maxWidth: FILLED_CONTENT_MAX_WIDTH, alignSelf: 'center' } : { width: '100%', alignSelf: 'center' };
+}

package/native/catalog/tokens.ts

@@ -11,15 +11,17 @@
  * `textMuted` stays #666666 because the references' #777777 fails WCAG AA contrast.
  */
 
+/** Owner decision 2026-10-11: only 10, 12, 14, 16, 18, 24, 28, 32 and 40. Named roles share a
+ *  step (tableHeader and panelHeading are 12, brand is 18). */
 export const CATALOG_TYPE = {
   xs: 10,
-  tableHeader: 11,
+  tableHeader: 12,
   sm: 12,
-  panelHeading: 13,
+  panelHeading: 12,
   md: 14,
   lg: 16,
-  brand: 17,
-  xl: 20,
+  brand: 18,
+  xl: 18,
   '2xl': 24,
   pageTitle: 28,
   '3xl': 32,
@@ -82,8 +84,8 @@ export const CATALOG_TYPE_USE: Record<keyof typeof CATALOG_TYPE, string> = {
   md: 'Default body text: descriptions, nav links, grid row headers, quick-reference rows, the filter field.',
   lg: 'Pager arrows and the filter field\'s clear (×) glyph.',
   brand: 'The app name at the top of the sidebar.',
-  xl: 'Reserved — no current consumer.',
-  '2xl': 'Reserved — no current consumer.',
+  xl: "The major-update banner's close (×) glyph.",
+  '2xl': "The update page's version numbers and the arrow between them.",
   pageTitle: 'The selected page\'s title.',
   '3xl': 'Reserved — no current consumer.',
   '4xl': 'Reserved — no current consumer.',

package/native/catalog/types.ts

@@ -75,9 +75,10 @@ export interface VariantSlot {
   items: VariantExample[];
 }
 
-/** Width class for a page's specimens: compact (min 160px), regular (min 240px), or wide (fixed
- *  402px, phone width). Sets grid column and list cell widths. */
-export type SpecimenSize = 'compact' | 'regular' | 'wide';
+/** Width class for a page's specimens: compact (min 160px), regular (min 240px), wide (min 402px,
+ *  phone width), or page (min 512px) for components wider than a phone, such as a whole catalog
+ *  page. Each is a minimum: cells share the row they are given. Sets grid column and cell widths. */
+export type SpecimenSize = 'compact' | 'regular' | 'wide' | 'page';
 
 /** Widths for a component preview: one or more phone widths (each capped at 402px), or 'full' for
  *  content that is not a phone component (catalog chrome, token galleries). */
@@ -267,6 +268,12 @@ export interface SectionDef<TId extends string = string> {
    *  sentence explaining why (not free-form prose) — e.g. "Selection is already demonstrated by X's
    *  working preview." Omit when no such declaration applies; the advisory then runs normally. */
   intentionalStaticPreview?: { reason: string };
+  /** Props the reader never chooses: plumbing a parent passes (a layout size, an internal surface
+   *  kind). `cli/doctor.ts`'s `option-not-covered` advisory then skips them, instead of asking for
+   *  an example of every option of a prop nobody picks by hand. Each entry needs a short reason,
+   *  so the exemption is a visible declaration in the page rather than a silent gap — write an
+   *  example instead whenever the reader really does choose the value. */
+  internalProps?: Record<string, string>;
 }
 
 /** A labeled group of section ids in the sidebar (e.g. "Components" vs "Tokens"). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.9",
+  "version": "0.6.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",

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

@@ -1,6 +1,6 @@
-import React, { useState } from 'react';
+import React from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Button } from '../Button';
 import { Dock } from '../Dock';
 import { TopNav } from '../TopNav';
@@ -17,53 +17,43 @@ const styles = StyleSheet.create({
 });
 
 function BottomSheetDemo() {
-  const [visible, setVisible] = useState(false);
   return (
-    <PhoneFrame>
-      {!visible && <Button label="Open sheet" onPress={() => setVisible(true)} />}
-      <BottomSheet
-        visible={visible}
-        onDismiss={() => setVisible(false)}
-        header={
-          <TopNav
-            title="Trip details"
-            trailing={
-              <Button
-                variant="secondary"
-                size="small"
-                showIcon
-                showLabel={false}
-                iconName="clear"
-                accessibilityLabel="Close"
-                onPress={() => setVisible(false)}
-              />
-            }
-          />
-        }
-        footer={
-          <Dock>
-            <Button label="Confirm" onPress={() => setVisible(false)} />
-          </Dock>
-        }
-      >
-        <View style={styles.sheetContent}>
-          <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
-          <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min.</Text>
-          {/* Long enough to overflow the phone frame's fixed height — demonstrates the Dock footer's
-              `elevated` shadow turning on automatically once this content area actually scrolls. */}
-          <Text style={styles.cardBody}>Board at the front car for a faster transfer at Union Sq.</Text>
-          <Text style={styles.cardBody}>
-            This line runs express between 96 St and 168 St during rush hours, skipping local stops in
-            between. Weekend service runs local along the full route, with some stations closed for
-            planned maintenance.
-          </Text>
-          <Text style={styles.cardBody}>
-            Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible
-            entrances before you travel.
-          </Text>
-        </View>
-      </BottomSheet>
-    </PhoneFrame>
+    <OverlayDemo triggerLabel="Open sheet">
+      {({ open, close }) => (
+        <BottomSheet
+          visible={open}
+          onDismiss={close}
+          header={
+            <TopNav
+              title="Trip details"
+              trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={close} />}
+            />
+          }
+          footer={
+            <Dock>
+              <Button label="Confirm" onPress={close} />
+            </Dock>
+          }
+        >
+          <View style={styles.sheetContent}>
+            <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
+            <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min.</Text>
+            {/* Long enough to overflow the phone frame's fixed height — demonstrates the Dock footer's
+                `elevated` shadow turning on automatically once this content area actually scrolls. */}
+            <Text style={styles.cardBody}>Board at the front car for a faster transfer at Union Sq.</Text>
+            <Text style={styles.cardBody}>
+              This line runs express between 96 St and 168 St during rush hours, skipping local stops in
+              between. Weekend service runs local along the full route, with some stations closed for
+              planned maintenance.
+            </Text>
+            <Text style={styles.cardBody}>
+              Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible
+              entrances before you travel.
+            </Text>
+          </View>
+        </BottomSheet>
+      )}
+    </OverlayDemo>
   );
 }
 

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

@@ -1,6 +1,6 @@
-import React, { useState } from 'react';
+import React from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Button } from '../Button';
 import { ButtonGroup } from '../ButtonGroup';
 import { Dialog } from './Dialog';
@@ -13,21 +13,21 @@ const styles = StyleSheet.create({
 });
 
 function DialogDemo() {
-  const [visible, setVisible] = useState(false);
   return (
-    <PhoneFrame>
-      {!visible && <Button label="Open dialog" onPress={() => setVisible(true)} />}
-      <Dialog visible={visible} onDismiss={() => setVisible(false)}>
-        <Text style={styles.cardTitle}>Delete this trip?</Text>
-        <Text style={styles.cardBody}>This can't be undone.</Text>
-        <View style={styles.dialogActions}>
-          <ButtonGroup>
-            <Button label="Cancel" variant="tertiary" onPress={() => setVisible(false)} />
-            <Button label="Delete" onPress={() => setVisible(false)} />
-          </ButtonGroup>
-        </View>
-      </Dialog>
-    </PhoneFrame>
+    <OverlayDemo triggerLabel="Open dialog">
+      {({ open, close }) => (
+        <Dialog visible={open} onDismiss={close}>
+          <Text style={styles.cardTitle}>Delete this trip?</Text>
+          <Text style={styles.cardBody}>This can't be undone.</Text>
+          <View style={styles.dialogActions}>
+            <ButtonGroup>
+              <Button label="Cancel" variant="tertiary" onPress={close} />
+              <Button label="Delete" onPress={close} />
+            </ButtonGroup>
+          </View>
+        </Dialog>
+      )}
+    </OverlayDemo>
   );
 }
 

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

@@ -1,7 +1,6 @@
-import React, { useState } from 'react';
+import React from 'react';
 import { View, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
-import { Button } from '../Button';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Toast } from './Toast';
 import { DS_SPACING } from '../../tokens';
 
@@ -15,14 +14,14 @@ const styles = StyleSheet.create({
 // pattern) so this demo actually exercises the slide-in-from-top/fade animation, not just the two
 // static end states.
 function ToastDemo() {
-  const [visible, setVisible] = useState(true);
   return (
-    <PhoneFrame>
-      <Button label={visible ? 'Hide toast' : 'Show toast'} onPress={() => setVisible((v) => !v)} />
-      <View style={styles.toastDemoOverlay} pointerEvents="box-none">
-        <Toast message="Trip saved" variant="success" visible={visible} />
-      </View>
-    </PhoneFrame>
+    <OverlayDemo triggerLabel={(open) => (open ? 'Hide toast' : 'Show toast')} keepTrigger initiallyOpen>
+      {({ open }) => (
+        <View style={styles.toastDemoOverlay} pointerEvents="box-none">
+          <Toast message="Trip saved" variant="success" visible={open} />
+        </View>
+      )}
+    </OverlayDemo>
   );
 }
 

package/starter-kit/pages/ReportIssue.catalog.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, OverlayDemo } from '@krapwoo/ds-viewer';
 import { Banner } from '../components/Banner';
 import { BottomSheet } from '../components/BottomSheet';
 import { Button } from '../components/Button';
@@ -51,7 +51,6 @@ const REPORT_ISSUE_TYPE_PILLS: PillRowItem[] = [
 ];
 
 function ReportIssueDemo() {
-  const [visible, setVisible] = useState(false);
   const [confirmDiscard, setConfirmDiscard] = useState(false);
   const [issueType, setIssueType] = useState('delay');
   const [line, setLine] = useState('4');
@@ -60,17 +59,19 @@ function ReportIssueDemo() {
   const [visibility, setVisibility] = useState('public');
   const [notify, setNotify] = useState(true);
 
-  const requestClose = () => setConfirmDiscard(true);
-  const discard = () => {
-    setConfirmDiscard(false);
-    setVisible(false);
-  };
-
   return (
-    <PhoneFrame>
-      {!visible && <Button label="Report an issue" onPress={() => setVisible(true)} />}
+    <OverlayDemo triggerLabel="Report an issue">
+      {({ open, close }) => {
+        // Closing asks first; discarding confirms and closes the sheet.
+        const requestClose = () => setConfirmDiscard(true);
+        const discard = () => {
+          setConfirmDiscard(false);
+          close();
+        };
+        return (
+          <>
       <BottomSheet
-        visible={visible}
+        visible={open}
         onDismiss={requestClose}
         header={
           <TopNav
@@ -82,7 +83,7 @@ function ReportIssueDemo() {
         }
         footer={
           <Dock>
-            <Button label="Submit report" onPress={() => setVisible(false)} />
+            <Button label="Submit report" onPress={close} />
           </Dock>
         }
       >
@@ -135,7 +136,10 @@ function ReportIssueDemo() {
           </ButtonGroup>
         </View>
       </Dialog>
-    </PhoneFrame>
+          </>
+        );
+      }}
+    </OverlayDemo>
   );
 }