@krapwoo/ds-viewer 0.6.9 → 0.6.10

package/README.md

@@ -502,6 +502,22 @@ Button
     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.
+
+  The catalog also warns at render time when a page under-declares the width its examples need.
+  A `PhoneFrame` given a cell narrower than the 375px device scales the whole phone down, and its
+  own body text shrinks with it, so it reports the page, the example and the cell:
+
+      [Catalog] BottomSheet (variants/content-only) is shown at 75% of device size: its cell is
+      283px, narrower than the 375px device. Declare a larger specimenSize so the example keeps
+      the width it is used at.
+
+  `check:catalog` fails on any `[Catalog]` warning, so this is caught in CI. The threshold is 95%,
+  not 100%: a regular cell leaves 370px for a 375px device, and warning about a reduction nobody
+  can see would only train you to ignore the warning. Where the scaling *is* the subject — a page
+  documenting that a narrow cell shrinks the device rather than reflowing it — write
+  `<PhoneFrame intentionalScale>` in that example, so the exemption is visible where the decision
+  was made.
+
   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;

package/dist/cli/explain.js

@@ -70,7 +70,7 @@ function toSectionDef(page) {
         hide: (page.hideVariants || page.hideStates) ? { variants: page.hideVariants, states: page.hideStates } : undefined,
     };
 }
-function explainBlock(block) {
+function explainBlock(block, availableWidth) {
     if (block.kind === 'grid') {
         const rows = axisItems(block.comparison.rows).length;
         const columns = axisItems(block.comparison.columns).length;
@@ -82,10 +82,10 @@ function explainBlock(block) {
         };
     }
     if (block.kind === 'list') {
-        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, block.size, block.maxColumns);
+        const geometry = listGeometry(block.items.length, availableWidth, block.size, block.maxColumns);
         return {
             kind: 'list', title: block.title,
-            reason: `${block.items.length} items (${block.size}) → ${geometry.columns} columns × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
+            reason: `${block.items.length} items (${block.size}) → ${geometry.columns} column${geometry.columns === 1 ? '' : 's'} × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
                 (geometry.fillers > 0 ? ` (${geometry.fillers} filler${geometry.fillers === 1 ? '' : 's'})` : '') + '.' +
                 surfaceOverrideNote(block.items) + alignOverrideNote(block.items),
         };
@@ -149,29 +149,40 @@ export function explainPage(config, pageId, options = {}) {
         return { pageId, notCheckable: true, blocks: [] };
     const def = toSectionDef(page);
     const blocks = presentationBlocks(def, { defaultPreviewWidths: [402] });
-    const explained = blocks.map(explainBlock);
+    // Two blocks placed side by side get half the row each, which changes how many columns fit.
+    // Reporting the full-width counts for a page the viewer will halve states the wrong geometry as
+    // fact, so the width every block is measured at follows the placement decision.
+    const full = MATRIX_LAYOUT.laptopContentWidth;
+    const half = Math.floor((full - CATALOG_LAYOUT.blockGap) / 2);
     let placement;
+    let blockWidth = full;
     if (blocks.length === 2) {
         if (options.heights) {
             const [firstHeight, secondHeight] = options.heights;
             const decision = choosePlacement({
-                available: MATRIX_LAYOUT.laptopContentWidth,
+                available: full,
                 gap: CATALOG_LAYOUT.blockGap,
                 first: toPlacementBlock(blocks[0], firstHeight),
                 second: toPlacementBlock(blocks[1], secondHeight),
             });
+            if (decision === 'side')
+                blockWidth = half;
             placement = {
                 decision,
-                reason: `With heights ${firstHeight}px/${secondHeight}px on a 1280px laptop (${MATRIX_LAYOUT.laptopContentWidth}px content width): ${decision}.`,
+                reason: `With heights ${firstHeight}px/${secondHeight}px on a 1280px laptop (${full}px content width): ${decision}` +
+                    (decision === 'side' ? `, so each block gets ${half}px.` : `, so each block gets the full ${full}px.`),
             };
         }
         else {
             placement = {
                 decision: 'decided-in-viewer',
-                reason: "Side-by-side placement depends on each block's measured height — decided in the viewer at runtime. Pass --heights <first>,<second> to check it here.",
+                reason: "Side-by-side placement depends on each block's measured height — decided in the viewer at runtime. " +
+                    `The counts above are for the full ${full}px row; side by side each block gets ${half}px instead, which can fit fewer columns. ` +
+                    'Pass --heights <first>,<second> to resolve it here.',
             };
         }
     }
+    const explained = blocks.map((block) => explainBlock(block, blockWidth));
     return { pageId, blocks: explained, placement, intentionalStaticPreviewReason: page.intentionalStaticPreviewReason };
 }
 export function formatExplain(result) {

package/native/catalog/PhoneFrame.tsx

@@ -1,7 +1,7 @@
-import React, { useState } from 'react';
+import React, { useState, useRef } 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 { DEVICE_FRAME, DEVICE_SCALE_WARN_BELOW, deviceFrameScale } from './deviceFrame';
 import { resolveOverlayViewport } from './overlayViewport';
 import { useSpecimenAddress } from './SpecimenAddress';
 
@@ -27,7 +27,16 @@ function isWeb(): boolean {
  * 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 }) {
+export function PhoneFrame({
+  children,
+  intentionalScale = false,
+}: {
+  children: React.ReactNode;
+  /** This example is *about* the scaling — a page demonstrating that a narrow cell shrinks the
+   *  device rather than reflowing it. Declared here, in the example itself, so the exemption is
+   *  visible where the decision was made instead of hidden in config. */
+  intentionalScale?: boolean;
+}) {
   const address = useSpecimenAddress();
   const [available, setAvailable] = useState(0);
   const [status, setStatus] = useState<'loading' | 'ready' | 'unavailable'>('loading');
@@ -36,6 +45,23 @@ export function PhoneFrame({ children }: { children: React.ReactNode }) {
     if (width > 0 && width !== available) setAvailable(width);
   };
   const scale = deviceFrameScale(available);
+  // A scaled device is a page that under-declared its width: the cell it was given is narrower
+  // than the phone, so the whole viewport shrinks and the example's own text shrinks with it,
+  // which is not the size anyone reads the component at. The scale is already computed, so this
+  // needs no measurement of its own. Guarded to once per transition, like TokenSections' own
+  // degradation warning; `check:catalog` fails on any [Catalog] warning, so this blocks CI.
+  const warnedScale = useRef<string | undefined>(undefined);
+  if (!intentionalScale && available > 0 && scale < DEVICE_SCALE_WARN_BELOW && (globalThis as { __DEV__?: boolean }).__DEV__) {
+    const key = `${available}`;
+    if (warnedScale.current !== key) {
+      warnedScale.current = key;
+      const where = address ? `${address.pageId} (${address.slot}/${address.itemKey})` : 'a PhoneFrame';
+      console.warn(
+        `[Catalog] ${where} is shown at ${Math.round(scale * 100)}% of device size: its cell is ${available}px, ` +
+          `narrower than the ${DEVICE_FRAME.width}px device. Declare a larger specimenSize so the example keeps the width it is used at.`,
+      );
+    }
+  }
   // 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

package/native/catalog/deviceFrame.ts

@@ -12,3 +12,12 @@ export function deviceFrameScale(availableWidth: number): number {
   if (!(availableWidth > 0)) return 1;
   return Math.min(1, availableWidth / DEVICE_FRAME.width);
 }
+
+/** Below this, a device is scaled enough that its own text is no longer the size a reader sees it
+ *  at, and the page should declare a wider specimen instead.
+ *
+ *  Not exactly 1. A regular cell leaves 370px for a 375px device — a 1.3% reduction nobody can
+ *  see, and warning about it would train authors to ignore the warning. The cases worth a page's
+ *  attention are the ones that shrink a phone by a tenth or more: a 283px cell renders the device
+ *  at 75%, which is the difference between readable body text and not. */
+export const DEVICE_SCALE_WARN_BELOW = 0.95;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "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

@@ -65,6 +65,10 @@ const dock = (close: () => void) => (
 export default defineCatalogPage({
   component: 'BottomSheet',
   group: 'Components',
+  // Every example is a phone. At the default size two blocks share the row and each cell falls to
+  // 270px, which squeezes the frame until the sheet's own text is barely readable — 'wide' keeps a
+  // 402px minimum, the width the sheet is actually used at.
+  specimenSize: 'wide',
   composedOf: [
     { component: 'TopNav', role: "The header slot, typically a TopNav with a close or back action.", relationship: 'slot' },
     { component: 'Dock', role: "The footer slot, typically a Dock with the sheet's primary actions; a Dock footer gets its shadow once the content scrolls.", relationship: 'slot' },

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

@@ -33,6 +33,9 @@ function Demo({ title, body, actions }: { title: string; body?: string; actions:
 export default defineCatalogPage({
   component: 'Dialog',
   group: 'Components',
+  // Every example is a phone. The default size left 283px for a 375px device, rendering it at 75%
+  // — small enough that the dialog's own body text stopped being the size a reader sees.
+  specimenSize: 'wide',
   composedOf: [
     { component: 'ButtonGroup', role: "Lays out the dialog's actions; a dialog's own children decide this, not Dialog.", relationship: 'related' },
   ],