@krapwoo/ds-viewer 0.4.6 → 0.4.7

package/native/catalog/specimenSurfaceStyle.ts

@@ -1,4 +1,4 @@
-import type { SpecimenSurfaceKind } from './types.ts';
+import type { SpecimenAlign, SpecimenSurfaceKind } from './types.ts';
 
 /**
  * The example wrapper's width policy inside a cell, kept free of any `react-native` import so
@@ -16,6 +16,75 @@ export const SPECIMEN_SURFACE_WIDTH_STYLE = {
   alignSelf: 'stretch',
 } as const;
 
+/**
+ * Centers a non-`fill` specimen horizontally inside its (now full-width) wrapper — unchanged,
+ * bounded (non-`fill`) specimens stay centered by default. See `SpecimenSurface.tsx`'s
+ * `SpecimenContent`, the one place every presentation shape (list/grouped/grid) wraps a specimen
+ * before handing it to its cell.
+ */
+export const SPECIMEN_CONTENT_CENTER_STYLE = {
+  ...SPECIMEN_SURFACE_WIDTH_STYLE,
+  alignItems: 'center',
+} as const;
+
+/**
+ * A `fill` specimen's content stretches instead of centering: `alignItems: 'center'` on this
+ * wrapper previously applied to `fill` specimens too, which collapses an auto-sized, already
+ * full-width child (e.g. NextTrainInfo's row) down to its own intrinsic content width instead of
+ * leaving it at the wrapper's full width — `alignItems: 'center'` resolves a child with no definite
+ * cross-axis size to its content size, the opposite of what `fill` promises. A `fill` specimen
+ * whose own size is capped below the wrapper's width (e.g. a phone-frame preview's `maxWidth`) is
+ * expected to center itself (`alignSelf: 'center'`, see `PhoneFrame.tsx`) rather than lean on this
+ * wrapper's `alignItems` — the same way `alignItems: 'stretch'` already behaves like `flex-start`,
+ * not an actual stretch, for any child with a definite cross-axis size (a set width/maxWidth) per
+ * the flexbox spec. An explicit `align` (see `specimenContentAlignItems`) still overrides this.
+ */
+export const SPECIMEN_CONTENT_FILL_STYLE = {
+  ...SPECIMEN_SURFACE_WIDTH_STYLE,
+  alignItems: 'stretch',
+} as const;
+
+const ALIGN_ITEMS_BY_SPECIMEN_ALIGN: Record<SpecimenAlign, 'flex-start' | 'center' | 'flex-end'> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+};
+
+/** The `SpecimenContent` wrapper's `alignItems`: an explicit `align` (`SpecimenPresentation.align`)
+ *  always wins over `fill`. Omitted, `fill` decides the established default — `'stretch'` (preserve
+ *  a full-width auto-sized child) when true, `'center'` (unchanged) otherwise. */
+export function specimenContentAlignItems(fill: boolean | undefined, align: SpecimenAlign | undefined): 'flex-start' | 'center' | 'flex-end' | 'stretch' {
+  if (align !== undefined) return ALIGN_ITEMS_BY_SPECIMEN_ALIGN[align];
+  return fill ? 'stretch' : 'center';
+}
+
+/** A non-fill specimen's horizontal position, as `justifyContent` on `SpecimenContent`'s own row
+ *  main axis rather than `alignItems` on a column: `alignItems` only sets a child's *default*
+ *  `alignSelf`, which the specimen's own root can — and does, e.g. Badge's `alignSelf:
+ *  'flex-start'` — override outright, leaning the whole grid left regardless of the wrapper's
+ *  intent. `justifyContent` positions along the main axis directly and cannot be overridden by a
+ *  child's `alignSelf`, which only ever targets the cross axis (vertical, on a row). Reuses
+ *  `ALIGN_ITEMS_BY_SPECIMEN_ALIGN`'s mapping — `flex-start`/`center`/`flex-end` are valid values
+ *  for both `alignItems` and `justifyContent`. */
+export function specimenContentJustifyContent(align: SpecimenAlign | undefined): 'flex-start' | 'center' | 'flex-end' {
+  return align !== undefined ? ALIGN_ITEMS_BY_SPECIMEN_ALIGN[align] : 'center';
+}
+
+/** The non-fill `SpecimenContent` wrapper's own style: still full-width (`SPECIMEN_SURFACE_WIDTH_STYLE`,
+ *  so a percentage-width child keeps resolving against it), but a row main axis so
+ *  `justifyContent` — not `alignItems` — decides horizontal placement (see
+ *  `specimenContentJustifyContent`). Vertical cross-axis stays centered, as it already did. Only
+ *  for non-`fill` specimens; `fill` keeps the existing column + `alignItems` stretch behavior
+ *  (`specimenContentAlignItems`), unchanged. */
+export function specimenContentBoundedStyle(align: SpecimenAlign | undefined) {
+  return {
+    ...SPECIMEN_SURFACE_WIDTH_STYLE,
+    flexDirection: 'row' as const,
+    justifyContent: specimenContentJustifyContent(align),
+    alignItems: 'center' as const,
+  };
+}
+
 /** Each example's cell turns gray only when its example would vanish against white (see
  *  `specimenFill.ts`). A page can force a fill with `specimenSurface`. */
 export const DEFAULT_SPECIMEN_SURFACE: SpecimenSurfaceKind = 'auto';

package/native/catalog/types.ts

@@ -12,21 +12,39 @@ export interface PropDef {
   desc: string;
 }
 
+/** How a specimen's content is cross-axis aligned inside its (already full-width) wrapper —
+ *  `start`/`center`/`end` map to `flex-start`/`center`/`flex-end`. Omit to inherit the established
+ *  default: `center` when `fill` is false/omitted (unchanged), or the wrapper's own full-width
+ *  stretch when `fill` is true — a capped-width `fill` specimen (e.g. a phone-frame preview) that
+ *  still wants centering sets `align: 'center'` explicitly rather than relying on `fill` alone; see
+ *  `specimenContentAlignItems` in `specimenSurfaceStyle.ts`. */
+export type SpecimenAlign = 'start' | 'center' | 'end';
+
+/** Per-specimen presentation, layered under whatever a slot or page already decides: this one
+ *  specimen's own background (`surface`, overriding the slot's/page's `specimenSurface` — omit to
+ *  inherit it), whether its wrapper stretches to the row's full width instead of shrinking to its
+ *  own content width (`fill`, for a single wide-format instance, e.g. a `fullWidth` Button, sitting
+ *  among otherwise compact, centered siblings — independent of a slot's own `itemsFill`, which
+ *  applies to every item uniformly), and how its content cross-axis aligns inside that wrapper
+ *  (`align` — see `SpecimenAlign`). Shared by `VariantExample` (list/grouped items) and
+ *  `ComparisonCell` (grid cells) so the same knobs mean the same thing in every presentation shape
+ *  ds-viewer renders a specimen in; an explicit `surface` here always bypasses `'auto'`'s own fill
+ *  heuristic (`specimenFill.ts`), the same way a slot's/page's own explicit surface already does. */
+export interface SpecimenPresentation {
+  /** @default false */
+  fill?: boolean;
+  surface?: SpecimenSurfaceKind;
+  align?: SpecimenAlign;
+}
+
 /** One individual example inside a variant/state cluster — e.g. one Button instance. */
-export interface VariantExample {
+export interface VariantExample extends SpecimenPresentation {
   /** React key; keep stable and unique within its group. */
   key: string;
   /** Shown as a small caption under this item — the actual variant/state value it demonstrates
    *  (e.g. "Primary", "Icon-only"), not a generic label like "Example 1". */
   name: string;
   node: React.ReactNode;
-  /** Stretch *this item's* wrapper to the row's full width, instead of shrinking to its own content
-   *  width — for a single wide-format instance (e.g. a `fullWidth` Button) sitting among otherwise
-   *  compact, centered siblings in the same slot. Without this, a `fullWidth`/stretch-based prop on
-   *  the instance itself has nothing to stretch into — its wrapper still shrinks to content, so the
-   *  instance renders at its natural size regardless of the prop. Independent of the slot's own
-   *  `itemsFill` (which applies to every item uniformly); this is a per-item override. @default false */
-  fill?: boolean;
   /** Which real prop value(s) this instance demonstrates, e.g. `{ variant: 'primary' }` or
    *  `{ size: 'large', disabled: true }` — mirrors the actual props passed to `node`. Optional and
    *  additive: SectionBlock only cross-checks a section's enum props against this metadata once at
@@ -99,14 +117,13 @@ export interface ComparisonAxisItem {
 export type GridAxis = readonly ComparisonAxisItem[] | { prop: string; items: readonly ComparisonAxisItem[] };
 
 /** One authored row × column specimen. Provide exactly one of `node` (a real instance of the
- *  documented component) or `unavailableReason` (the combination genuinely does not exist). */
-export interface ComparisonCell {
+ *  documented component) or `unavailableReason` (the combination genuinely does not exist). See
+ *  `SpecimenPresentation` for `fill`/`surface`. */
+export interface ComparisonCell extends SpecimenPresentation {
   rowKey: string;
   columnKey: string;
   node?: React.ReactNode;
   unavailableReason?: string;
-  /** Stretch this specimen to the cell width. @default false */
-  fill?: boolean;
 }
 
 /** A grid of two props that combine freely. Every row × column pair is authored — never inferred
@@ -222,6 +239,13 @@ export interface SectionDef<TId extends string = string> {
   /** Widths for this page's `render()` preview, e.g. `[402, 320]` to add a small-phone example.
    *  Defaults to the catalog's default (CatalogShell `defaultPreviewWidths`), else `[402]`. */
   previewWidths?: PreviewWidths;
+  /** Presentation for this page's numeric-width component Preview (guided intelligence,
+   *  "Collapsible Preview table"): `'frames'` (default, unchanged) — one borderless-card frame per
+   *  width, side by side. `'table'` — the widths share one `ComparisonList`-style card, each with
+   *  its own muted caption strip above its live body; still an independent, stateful instance per
+   *  width. Has no effect on a `'full'` preview width (catalog chrome) or a token gallery — those
+   *  always render as `'frames'` regardless of this field. */
+  previewLayout?: 'frames' | 'table';
   /** Remove specific parts of the page — for sections with no meaningful states, props, or
    *  accessibility story (e.g. a framework's own building-block pages). `variants` removes the
    *  first specimen block (grid, Variants list, or Preview); `states` removes the States /
@@ -237,6 +261,12 @@ export interface SectionDef<TId extends string = string> {
    *  Quick reference. See `ComposedOfEntry`. Omit when the component has no meaningful composition
    *  to disclose (most leaf components). */
   composedOf?: ComposedOfEntry[];
+  /** Explicit author declaration (guided intelligence design §3) that this page's examples are
+   *  intentionally static despite the documented component having a controlled state/event pair —
+   *  suppresses `cli/doctor.ts`'s `missing-working-preview` advisory. `reason` is a short, bounded
+   *  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 };
 }
 
 /** 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.6",
+  "version": "0.4.7",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",

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

@@ -5,6 +5,9 @@ import { Banner } from './Banner';
 export default defineCatalogPage({
   component: 'Banner',
   group: 'Surfaces',
+  composedOf: [
+    { component: 'AnimatedChevron', role: "The expand/collapse chevron in the header of a collapsible banner.", relationship: 'built-in' },
+  ],
   description: 'An inline callout for status/announcements — five semantic variants, optional collapsible body, inline link, and action button.',
   whenToUse: "Persistent and in-flow, describing a standing condition about the screen's content. For a transient, self-contained event notification, use Toast instead.",
   a11y: 'When onPress/action is set the header/button are Pressables; the collapsible header toggles the description with a chevron affordance.',

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

@@ -56,6 +56,9 @@ const BUTTON_COMPARISON = grid(
 export default defineCatalogPage({
   component: 'Button',
   group: 'Actions',
+  composedOf: [
+    { component: 'Loading', role: "The spinner that replaces the label and icon while loading is true.", relationship: 'built-in' },
+  ],
   comparison: BUTTON_COMPARISON,
   description:
     'The primary tap target. Five visual weights, three sizes, optional leading/trailing icon, plus loading and icon-only modes.',

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

@@ -39,6 +39,12 @@ function DropdownDemo() {
 export default defineCatalogPage({
   component: 'Dropdown',
   group: 'Inputs',
+  composedOf: [
+    { component: 'FieldContainer', role: "The field frame around the label, value and chevron (the trigger).", relationship: 'built-in' },
+    { component: 'BottomSheet', role: "The sheet listing the options while the dropdown is open.", relationship: 'built-in' },
+    { component: 'TopNav', role: "The sheet's header, titled with the field's label.", relationship: 'built-in' },
+    { component: 'Button', role: "The icon-only Close button in the sheet header.", relationship: 'built-in' },
+  ],
   description: 'A labelled field that opens a BottomSheet picker on tap — the "bottom sheet picker" interaction: tap the trigger, pick an option from the sheet, it closes.',
   whenToUse: 'The answer is one of a small, known set of choices — never free text. For free-text filtering, use SearchField; for a named field with a fixed identity, use InputField.',
   a11y: 'The trigger is a Pressable (via FieldContainer) with accessibilityRole="button". Options render as accessibilityRole="radio" inside a "radiogroup", with accessibilityState.checked reflecting the current selection.',

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

@@ -6,6 +6,11 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'EmptyState',
   group: 'Layout',
+  composedOf: [
+    { component: 'Avatar', role: "The icon circle above the title (iconName, default 'users').", relationship: 'built-in' },
+    { component: 'ButtonGroup', role: "Stacks the action buttons when action is set.", relationship: 'built-in' },
+    { component: 'Button', role: "The action button, plus a tertiary secondaryAction button when set.", relationship: 'built-in' },
+  ],
   description: 'A centred placeholder for a screen or section with nothing to show yet — no results, no saved items, a first-run state.',
   whenToUse: "Fills the entire content area because there's nothing else to show. For a note that sits alongside other real content, use Banner instead.",
   a11y: 'A plain View with text; the action(s) render as real Buttons inside a ButtonGroup, which carry their own accessibility.',

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

@@ -18,6 +18,9 @@ function InputFieldDemo() {
 export default defineCatalogPage({
   component: 'InputField',
   group: 'Inputs',
+  composedOf: [
+    { component: 'InputClearButton', role: "The clear (\u00d7) button, shown while the field has a value and is focused (or active, when not editable).", relationship: 'built-in' },
+  ],
   description: 'A floating-label field. Resting: a centred, body-sized label with no border. Active (focused, or picker with active set) or filled: the label floats to a small top caption, row 2 shows the value/input, and a border fades in while active.',
   whenToUse: 'A named field with a fixed identity ("To", "Arrive by") across the interaction. For free-text search with no floating label, use SearchField; for one of a small known set of choices, use Dropdown.',
   a11y: 'The editable mode is a live TextInput; the picker mode is a Pressable row. Either mode shows a clear button while active (focused, or active for a picker) with a value set. Provide a meaningful label.',

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

@@ -9,6 +9,9 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'List',
   group: 'Layout',
+  composedOf: [
+    { component: 'Divider', role: "The hairline between consecutive items (none after the last).", relationship: 'built-in' },
+  ],
   description: 'Stacks ListItem rows on a rounded white surface, with a Divider automatically inserted between each consecutive pair — never after the last.',
   a11y: 'A plain View; each ListItem child carries its own accessibility.',
   variants: {

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

@@ -41,6 +41,9 @@ const PILL_COMPARISON = grid(
 export default defineCatalogPage({
   component: 'Pill',
   group: 'Actions',
+  composedOf: [
+    { component: 'Loading', role: "The spinner shown instead of the label and icon while loading is true.", relationship: 'built-in' },
+  ],
   specimenSize: 'compact',
   comparison: PILL_COMPARISON,
   description: 'A compact selectable chip — selected/unselected states with an optional leading icon.',

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

@@ -5,6 +5,9 @@ import { PillRow } from './PillRow';
 export default defineCatalogPage({
   component: 'PillRow',
   group: 'Actions',
+  composedOf: [
+    { component: 'Pill', role: "Each item in pills, plus the trailing icon-only Edit pill when shown.", relationship: 'built-in' },
+  ],
   description: 'A horizontally-scrolling row of Pill chips, with an optional trailing icon-only add pill — keeps the selected pill scrolled into view automatically.',
   whenToUse: 'A scrollable row of selection chips (e.g. saved-place shortcuts) — for a fixed row of action buttons instead, use ButtonGroup.',
   a11y: 'The row itself carries no accessibility role; each Pill (including the add pill) keeps its own accessibilityLabel/role from the Pill component.',

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

@@ -10,6 +10,10 @@ function SearchFieldDemo() {
 export default defineCatalogPage({
   component: 'SearchField',
   group: 'Inputs',
+  composedOf: [
+    { component: 'FieldContainer', role: "The field frame around the search icon, input and clear button.", relationship: 'built-in' },
+    { component: 'InputClearButton', role: "The clear (\u00d7) button, shown while focused with text.", relationship: 'built-in' },
+  ],
   description: 'Single-line search input on the shared field chrome — leading search icon, a border that darkens on focus, and a clear button while active with text.',
   whenToUse: 'Free-text filtering/searching only — never a named field with a fixed value. For that, use InputField; for a small known set of choices, use Dropdown.',
   a11y: 'Forwards a ref to the underlying TextInput; all TextInputProps pass through, so pass accessibilityLabel/placeholder as needed.',

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

@@ -5,6 +5,9 @@ import { SectionHeader } from './SectionHeader';
 export default defineCatalogPage({
   component: 'SectionHeader',
   group: 'Layout',
+  composedOf: [
+    { component: 'Button', role: "The trailing button, rendered when trailingButtonLabel is set.", relationship: 'built-in' },
+  ],
   description: 'An uppercase muted section label with an optional inline icon and a right-aligned ghost button.',
   whenToUse: "A label above a group of related rows within a screen (e.g. above a List) — for the screen's own top bar, use TopNav.",
   a11y: 'Title renders as plain Text — no heading role. A tappable labelIcon (onPress set) becomes accessibilityRole="button" with accessibilityLabel falling back to the section\'s own title; a non-interactive labelIcon has no accessibility node of its own. The trailing button is a real Button, so it carries Button\'s own accessibility for free.',

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

@@ -10,6 +10,9 @@ function TextAreaDemo() {
 export default defineCatalogPage({
   component: 'TextArea',
   group: 'Inputs',
+  composedOf: [
+    { component: 'FieldContainer', role: "The field frame around the multi-line input.", relationship: 'built-in' },
+  ],
   description: 'A multi-line input that grows with its content from a minimum height.',
   a11y: 'A multiline TextInput; pass accessibilityLabel via inputProps when there is no visible label beside it.',
   variants: {

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

@@ -32,6 +32,13 @@ export default defineCatalogPage({
   description: 'A transient confirmation bar. Without a variant it renders the dark surface with inverse text; a variant shifts to a pastel status color.',
   whenToUse: "Transient and self-contained, floating over the screen, expected to go away on its own or via its own action. For a persistent, in-flow message about a standing condition, use Banner.",
   a11y: 'Rendered with accessibilityRole="alert" so screen readers announce it when it appears.',
+  // Confirmed from Toast.tsx's own JSX, not inferred from its imports: it renders a Button itself
+  // (not a caller-supplied child) whenever `action` is set. Toast.tsx also renders an Icon for its
+  // status glyph, but Icon has no catalog page/known component name of its own to confirm against
+  // yet, so that entry is left out rather than logging an unknown-component warning.
+  composedOf: [
+    { component: 'Button', role: 'Renders the optional action button when action is set.', relationship: 'built-in' },
+  ],
   variants: {
     itemsFill: true,
     items: [