@krapwoo/ds-viewer 0.4.9 → 0.6.0

package/README.md

@@ -175,13 +175,18 @@ when the card is too narrow even for two. The specimens use one of four layouts:
 - **Preview** — `render()` content. Component previews render at phone width (402px), optionally
   with more widths such as a 320px small phone; token galleries and catalog chrome stay full width.
 
-When a page has two blocks, the catalog places them side by side if that makes the page at least
-120px shorter (e.g. Dropdown), and stacks them otherwise. A block with nothing to show is omitted.
-
-Grid columns and list cells are at most 402px wide with 16px padding. A page's `specimenSize`
-(`compact` 160px, `regular` 240px, `wide` 402px) sets the minimum width; full-width (`itemsFill`)
-slots default to `wide`. The catalog's own look comes from `native/catalog/tokens.ts`, never from
-the host app's tokens.
+When a page has two blocks, the catalog places them side by side — the row split into two equal
+columns, each block filling its own — if both keep their minimum width there and it makes the page
+at least 120px shorter (e.g. Dropdown); otherwise they stack, each filling the whole row. A block
+with nothing to show is omitted.
+
+Every card fills the column it is given, and its columns or cells share that width equally: a
+two-column grid is as wide as a five-column one, and a two-item list is as wide as a six-item one.
+Phone width (402px, 370px of content) caps the specimen inside a cell, not the cell. A page's
+`specimenSize` (`compact` 160px, `regular` 240px, `wide` 402px) sets the minimum column width — a
+card narrower than its minimum scrolls inside itself rather than squeezing its cells. Full-width
+(`itemsFill`) slots default to `wide`. The catalog's own look comes from `native/catalog/tokens.ts`,
+never from the host app's tokens.
 
 ## Adding a component (the recipe)
 
@@ -201,7 +206,9 @@ actually apply:
   combination does not exist. Never multiply `variants` by `states` to fill it. Keep the column axis
   within what fits a 1280px laptop: 5 compact, 3 regular, or 2 wide columns. `states` items whose
   key matches a row or column key are not repeated below the grid.
-- `specimenSize: 'compact' | 'regular' | 'wide'` — the page's specimen width class.
+- `specimenSize: 'compact' | 'regular' | 'wide' | 'page'` — the page's specimen width class. `'page'`
+  is for components wider than a phone (a whole screen layout, a catalog page): cells are at least
+  512px and share the row, with no 402px cap.
 - `specimenSurface: 'auto' | 'neutral' | 'white' | 'dark' | 'transparent'` — the fill of each
   example's cell (list, grouped and grid cells, and a non-token `render()` preview). Defaults to
   `'auto'`: after the page draws, a cell turns light gray only when its own example would vanish
@@ -272,6 +279,28 @@ actually apply:
   in an iPhone SE viewport (375 × 667 points), scaled down only when its cell is narrower. In the
   browser viewer it opens that example in its own device-sized document, so overlays that portal
   to the page (React Native's `Modal`) open inside the phone, not over the catalog.
+- **`OverlayDemo`** — a phone with a catalog button that opens an overlay. Children get
+  `{ open, close }`; keep the overlay mounted and drive its own `visible` from `open`, so its
+  animations play. `keepTrigger` makes the button a toggle; `triggerLabel` can follow the state;
+  `initiallyOpen` starts it open.
+  ```tsx
+  <OverlayDemo triggerLabel="Open sheet">
+    {({ open, close }) => (
+      <BottomSheet visible={open} onDismiss={close} footer={<Dock><Button label="Confirm" onPress={close} /></Dock>}>
+        …
+      </BottomSheet>
+    )}
+  </OverlayDemo>
+  ```
+- **`PhoneScreen`** — a whole app screen inside a `PhoneFrame`: `header` stays at the top,
+  `footer` at the phone's bottom, and the children scroll between them instead of pushing the
+  footer off the screen. `floating` is a layer over the top for toasts (position its content
+  yourself); `bodyWrapper` puts your own surface around the scrolling body.
+  ```tsx
+  <PhoneFrame>
+    <PhoneScreen header={<TopNav title="Saved trips" />} footer={<Dock>…</Dock>}>…</PhoneScreen>
+  </PhoneFrame>
+  ```
 - Full-width (`itemsFill`) variants and states wrap at most **3** across; set `maxColumns` to
   change that. A filled example that keeps its own fixed width is centred in its cell.
   Default to one preview; add a second width only when a narrower (or wider) viewport actually
@@ -459,10 +488,47 @@ Button
     or `x`/`onXChange`) but every example that renders it passes a fixed value with no working
     callback. Add `intentionalStaticPreview: { reason: '...' }` to the page to suppress it when the
     static examples are deliberate.
+  - `preview-only-component-page` — a component page's only examples are a free-form `render()`
+    preview, so nothing is named and the checks above have no example to read. Give the page
+    `variants` (and `states`, where they differ) naming each real configuration. Token galleries
+    and a declared `intentionalStaticPreview` are exempt; `render()` stays right for a token
+    gallery or a whole-page layout.
+  - `internal-prop-unknown` — `internalProps` names something that is not a prop of the component,
+    so the exemption it was written for is not in effect. Correct the spelling or delete the entry.
+  A page's `internalProps: { size: 'why' }` exempts a named prop from `option-not-covered` — for
+  plumbing a parent passes (a layout size, an internal surface kind) rather than a value the
+  reader picks. It needs a reason per prop, so the exemption is a visible declaration in the page;
+  when the reader really does choose the value, tag an example with `props` instead.
   The analyzer follows supported aliases and resolved exports, but uncertain wrappers or
   dynamically-constructed references remain uncheckable rather than being guessed at. A
   declared `intentionalStaticPreview` is taken as the author's own call, not independently
   verified; only a real browser check confirms actual behavior.
+- `overlay-without-device-frame` (warning) — the component imports React Native's `Modal`, which
+  opens over the whole catalog page on the web, but its page imports no `PhoneFrame`,
+  `OverlayDemo`, `PhoneScreen` or `BoundedOverlayViewport`. Conservative: it can't see
+  `import * as RN`, a re-exported `Modal`, or a Modal opened by a sub-component.
+
+### `doctor --render`
+
+`npx ds-viewer doctor --render` also starts the viewer, opens every page in a headless browser,
+and adds what only a real render shows:
+
+- `render-error` / `render-no-heading` (errors): a console error, or a page that didn't render.
+- `render-layout` (warning): an example wider than its cell (the viewer's own check), with the
+  page and file. `render-catalog-warning` (warning): any other `[Catalog]` warning, reported once.
+- `identical-variants` (warning): two examples in the same card whose specimens render identically,
+  so the difference their names claim isn't visible — usually a cell too narrow to show it, or a
+  prop that was never wired up. The fingerprint reads each specimen's whole subtree (including a
+  PhoneFrame's child document and a field's value) but not the caption carrying the variant's own
+  name, so two examples differing only in colour are not reported.
+- `render-unavailable` / `render-failed` (errors): no browser, or the catalog didn't start.
+
+It needs `puppeteer` in your project (`npm install --save-dev puppeteer`); ds-viewer doesn't
+install a browser. It takes about two minutes for 50 pages and works with `--json` (progress
+goes to stderr), `--ci` and `doctor.strict`, so CI can run `npx ds-viewer doctor --render --ci`.
+It stops the viewer it started, including on Ctrl-C (exit codes 130, 143 or 129 for SIGINT,
+SIGTERM or SIGHUP). On Windows it stops the viewer with `taskkill`; that path is unit-tested, not
+run on a real Windows machine.
 
 ## Known gaps
 

package/dist/cli/doctor.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { discoverAllPageFiles, resolvePageId } from "./pageIndex.js";
 import { readHostTsconfigOptions } from "./props.js";
-import { readStaticPages } from "./staticPage.js";
+import { importedNames, readStaticPages } from "./staticPage.js";
 import { resolveGlob } from "./glob.js";
 import { sync } from "./sync.js";
 import { gridColumnLimit } from "../native/catalog/comparison.js";
@@ -208,6 +208,43 @@ function checkMissingComposition(pages, components) {
     }
     return issues;
 }
+/** The viewer exports that frame an example as a phone (or another bounded document), so an
+ *  overlay that portals to the document body opens inside it instead of over the catalog. */
+const DEVICE_FRAME_EXPORTS = ['PhoneFrame', 'OverlayDemo', 'PhoneScreen', 'BoundedOverlayViewport'];
+/** Whether a component's own source imports React Native's `Modal` (by its imported name, so an
+ *  alias still counts and an unrelated local `Modal` doesn't). Conservative by design: it can't see
+ *  `import * as RN`, a re-exported `Modal`, or a Modal opened by a sub-component. */
+function importsModal(file) {
+    try {
+        const source = ts.createSourceFile(file, readFileSync(file, 'utf8'), ts.ScriptTarget.ES2022, true, ts.ScriptKind.TSX);
+        return [...importedNames(source, 'react-native').values()].includes('Modal');
+    }
+    catch {
+        return false;
+    }
+}
+/** `overlay-without-device-frame`: a page whose component opens a React Native `Modal` (which
+ *  portals to the document body on the web, covering the whole catalog) but whose page imports no
+ *  device frame. A page whose imports couldn't be read is skipped, never assumed unframed. */
+export function checkOverlaysFramed(pages, components, projectRoot) {
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const issues = [];
+    for (const page of pages) {
+        if (!page.component || page.viewerImports === undefined)
+            continue;
+        if (page.viewerImports.some((name) => DEVICE_FRAME_EXPORTS.includes(name)))
+            continue;
+        const component = byName.get(page.component);
+        if (!component || !importsModal(path.resolve(projectRoot, component.file)))
+            continue;
+        issues.push(issue({
+            id: 'overlay-without-device-frame', severity: 'warning', ...pageRef(page),
+            message: `"${component.name}" opens a React Native Modal, which covers the whole catalog page unless its example is inside a phone.`,
+            fix: 'Wrap the example in <PhoneFrame> (or use <OverlayDemo>), so it opens inside the phone.',
+        }));
+    }
+    return issues;
+}
 /** A function-typed prop's printed type always contains `=>` (`cli/props.ts`'s own displayed type
  *  strings — "(value: string) => void", "() => void", …); a plain data prop's never does. */
 function isFunctionPropType(type) {
@@ -242,6 +279,22 @@ function findControlledPair(component) {
  *   - no example directly renders the component at all, or any direct example's value/callback is
  *     `'unknown'` — genuinely uncheckable, and "uncheckable" must never be reported as "inert".
  *  Never a newly-fatal gate: always a warning, same as every other advisory in this file. */
+/** A component page whose only examples are a free-form `render()` preview: nothing is named, so
+ *  the reader sees one picture instead of the component's real variants and states, and several
+ *  other rules here (`missing-working-preview`, the option-coverage rules) are skipped because
+ *  they have no named example to read. A token gallery is exempt — raw token data has no variants
+ *  — and so is a page that says `intentionalStaticPreview` with a reason. */
+function checkPreviewOnlyPages(pages) {
+    return pages
+        .filter((page) => page.component !== undefined && page.checkable && page.hasRender === true && !page.tokenGallery
+        && !page.intentionalStaticPreviewReason
+        && !page.comparison && !page.variantsItems?.length && !page.statesItems?.length && !page.tokenSectionTitles?.length)
+        .map((page) => issue({
+        id: 'preview-only-component-page', severity: 'warning', ...pageRef(page),
+        message: `"${page.component}" is documented by a render() preview alone, with no named variants, states or comparison.`,
+        fix: 'Give the page variants (and states, where they differ) naming each real configuration, so every example has a caption and the other checks can read them. Keep render() for token galleries and whole-page layouts.',
+    }));
+}
 function checkMissingWorkingPreview(pages, components) {
     const componentsByName = new Map(components.map((c) => [c.name, c]));
     const issues = [];
@@ -372,8 +425,25 @@ function checkComponentPages(pages, components) {
                 }));
             }
         }
+        // Props the page declares as plumbing the reader never picks (with a reason) are not expected
+        // to have an example per option; see `internalProps`.
+        const internalProps = new Set(page.internalProps ?? []);
+        // A misspelled key silently exempts nothing, so the author sees the warnings it was meant to
+        // settle and no reason why — the same reasoning as propNotes' own key check.
+        for (const name of internalProps) {
+            // `component.props` deliberately omits a node_modules-declared prop (cli/props.ts), so an
+            // inherited name such as `autoCapitalize` is expected to be absent rather than misspelled —
+            // the same exemption the tagged-item check above makes.
+            if (!propsByName.has(name) && component.inheritedFrom.length === 0) {
+                issues.push(issue({
+                    id: 'internal-prop-unknown', severity: 'warning', ...ref,
+                    message: `internalProps names "${name}", which is not a prop of ${component.name}.`,
+                    fix: `Correct the spelling, or delete the "${name}" entry — it exempts nothing as written.`,
+                }));
+            }
+        }
         for (const prop of component.props) {
-            if (!prop.options)
+            if (!prop.options || internalProps.has(prop.name))
                 continue;
             const covered = new Set();
             if (page.comparison) {
@@ -419,10 +489,15 @@ function checkComponentPages(pages, components) {
                 fix: 'Add a one-sentence whenToUse note disambiguating this component from its closest look-alike(s), or omit it only when there genuinely is none.',
             }));
         }
-        if (!page.tokenGallery && page.hasA11y === false && !page.hidesAccessibility) {
+        // `hide: { accessibility: true }` is a display choice, not an exemption from documenting the
+        // component: hiding the section only removes the visible placeholder, so without this the gap
+        // becomes invisible to both the reader and the doctor.
+        if (!page.tokenGallery && page.hasA11y === false) {
             issues.push(issue({
                 id: 'missing-guidance-or-a11y', severity: 'warning', ...ref,
-                message: 'No "a11y" notes documented.',
+                message: page.hidesAccessibility
+                    ? 'No "a11y" notes documented, and the page hides the accessibility section.'
+                    : 'No "a11y" notes documented.',
                 fix: 'Add a one-sentence a11y note, grounded in the component\'s real behavior — even "no explicit handling beyond defaults" is better than leaving it blank.',
             }));
         }
@@ -443,6 +518,7 @@ export function collectIssues(pages, components) {
         ...checkComponentPages(pages, components),
         ...checkMissingComposition(pages, components),
         ...checkMissingWorkingPreview(pages, components),
+        ...checkPreviewOnlyPages(pages),
     ];
 }
 /** Issues that aren't tied to one page: `sync`'s own "Could not read" warnings, and a configured
@@ -509,6 +585,15 @@ export function checkPageTypeErrors(pages, options = {}) {
     }
     return issues;
 }
+/** Adds findings to a finished result: applies `doctor.strict`, recounts errors and warnings, and
+ *  resets the exit code. */
+export function withExtraIssues(result, extra, strict) {
+    const added = strict ? extra.map((i) => (i.severity === 'warning' ? { ...i, severity: 'error' } : i)) : extra;
+    const issues = [...result.issues, ...added];
+    const errors = issues.filter((i) => i.severity === 'error').length;
+    const summary = { ...result.summary, errors, warnings: issues.length - errors };
+    return { ...result, issues, summary, exitCode: errors > 0 ? 1 : 0 };
+}
 /** "With examples" means what `checkComponentNoExamples` (Task 4) checks the *absence* of: at
  *  least one checkable page with a real example, not merely "has a page" (an `init`-drafted
  *  "Needs examples" page has one, with none). */
@@ -572,6 +657,7 @@ export function runDoctor(config) {
     let issues = [
         ...collectIssues(pages, components),
         ...checkPageTypeErrors(pages, { fallbackPaths, hostRoot: config.projectRoot }),
+        ...checkOverlaysFramed(pages, components, config.projectRoot),
         ...collectGlobalIssues({ syncWarnings: syncResult.warnings, tokenFileCount }),
     ];
     // Design's own `--json` example gives a project-relative `file`; `StaticPage.file` is absolute
@@ -588,7 +674,8 @@ export function runDoctor(config) {
         withExamples: countWithExamples(pages, components),
         unboundExamples: countUnboundExamples(pages),
     };
-    return { version: 1, summary, update: null, issues, exitCode: summary.errors > 0 ? 1 : 0 };
+    const pageFileById = new Map(pages.map((p) => [resolvePageId(p, p.file), path.relative(config.projectRoot, p.file)]));
+    return { version: 1, summary, update: null, issues, exitCode: summary.errors > 0 ? 1 : 0, pageFiles: pageFileById };
 }
 export function toDoctorJson(result) {
     const { version, summary, update, issues } = result;

package/dist/cli/explain.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { readStaticPages } from "./staticPage.js";
 import { discoverAllPageFiles, resolvePageId } from "./pageIndex.js";
 import { resolveGlob } from "./glob.js";
-import { axisItems, choosePlacement, gridColumnLimit, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
+import { axisItems, blockMinWidth, choosePlacement, gridColumnLimit, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
 import { CATALOG_LAYOUT } from "../native/catalog/tokens.js";
 import { sectionColumns } from "../native/catalog/tokenLayout.js";
 function placeholderItem(item) {
@@ -113,23 +113,14 @@ function explainBlock(block) {
     }
     return { kind: 'empty', title: block.title, reason: block.message };
 }
-/** Mirrors `native/catalog/SectionBlock.tsx`'s own `blockWidth` helper: a list block's width is its
- *  own natural, content-hugging width (`listGeometry`'s `containerWidth`) — the real viewer only
- *  ever moves a *second* block beside a *first* one when that first block doesn't already fill the
- *  whole row, so `choosePlacement` only reads `first.width` (never `second.width`) — but it's
- *  computed uniformly here for either role, since setting it on `second` is simply unused, not wrong. */
-function toPlacementBlock(block, height, available) {
-    if (block.kind === 'list') {
-        return {
-            kind: 'list',
-            height,
-            itemCount: block.items.length,
-            size: block.size,
-            maxColumns: block.maxColumns,
-            width: listGeometry(block.items.length, available, block.size, block.maxColumns).containerWidth,
-        };
-    }
-    return { kind: block.kind, height };
+/** Mirrors `native/catalog/SectionBlock.tsx`'s own `placementBlock` helper: side by side splits the
+ *  row in two and each block fills its half, so the decision needs each block's narrowest width
+ *  plus, for a list, the geometry that predicts its height in half a row. */
+function toPlacementBlock(block, height) {
+    const base = { kind: block.kind, height, minWidth: blockMinWidth(block) };
+    return block.kind === 'list'
+        ? { ...base, itemCount: block.items.length, size: block.size, maxColumns: block.maxColumns }
+        : base;
 }
 /** Finds `pageId` among every page `cli/doctor.ts`'s own `discoverAllPageFiles` would find, builds
  *  its throwaway `SectionDef`, and asks the viewer's own pure layout functions for each block's
@@ -163,8 +154,8 @@ export function explainPage(config, pageId, options = {}) {
             const decision = choosePlacement({
                 available: MATRIX_LAYOUT.laptopContentWidth,
                 gap: CATALOG_LAYOUT.blockGap,
-                first: toPlacementBlock(blocks[0], firstHeight, MATRIX_LAYOUT.laptopContentWidth),
-                second: toPlacementBlock(blocks[1], secondHeight, MATRIX_LAYOUT.laptopContentWidth),
+                first: toPlacementBlock(blocks[0], firstHeight),
+                second: toPlacementBlock(blocks[1], secondHeight),
             });
             placement = {
                 decision,

package/dist/cli/main.js

@@ -5,7 +5,8 @@ import { resolveConfig } from "./config.js";
 import { initExistingProject, initNewProject, promptInitMode } from "./init.js";
 import { dev } from "./dev.js";
 import { sync } from "./sync.js";
-import { formatHuman, runDoctor, toDoctorJson } from "./doctor.js";
+import { formatHuman, runDoctor, toDoctorJson, withExtraIssues } from "./doctor.js";
+import { renderCheck } from "./render.js";
 import { explainPage, formatExplain, parseHeights } from "./explain.js";
 import { readOwnVersion } from "./packageVersion.js";
 import { checkForUpdate, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck } from "./updateCheck.js";
@@ -27,6 +28,7 @@ Commands:
   doctor   Check every page for drift and coverage gaps
            --json          print the machine-readable report instead
            --ci            exit 1 when any error was found (never on a warning alone)
+           --render        also open every page in a headless browser (needs puppeteer)
   explain <Page>
            Print why a page's specimens are laid out the way they are
            --heights <first>,<second>  check side-by-side placement with these measured heights
@@ -116,7 +118,14 @@ export async function runInit(projectRoot, rest, options = {}) {
  *  plain `doctor` (no `--ci`) always returns 0 here regardless of errors found. */
 export async function runDoctorCommand(projectRoot, rest, options = {}) {
     const config = resolveConfig(projectRoot);
-    const result = runDoctor(config);
+    let result = runDoctor(config);
+    // `--render`: open every page in a headless browser and add what only a real render shows.
+    // Progress goes to stderr, so `--json` output stays pure JSON.
+    if (rest.includes('--render')) {
+        const files = result.pageFiles;
+        const rendered = await (options.renderCheck ?? renderCheck)(config.projectRoot, { files, log: (line) => process.stderr.write(`${line}\n`) });
+        result = withExtraIssues(result, rendered, Boolean(config.doctor?.strict));
+    }
     // Design §4 "`--ci`: ... no update check." — `--ci` skips this whole block even when
     // `updateCheck` is otherwise enabled; `result.update` stays `null`.
     // Same precedence as the viewer: CI's environment variable, your own switch, the project config.