@krapwoo/ds-viewer 0.11.0 → 0.12.0

package/README.md

@@ -695,10 +695,22 @@ and adds what only a real render shows:
   cells are not visited at all. Usually fixed with a wider `specimenSize`, by stacking the blocks so
   the example gets the full row, or by dropping `itemsFill` from a small instance that should sit
   centered.
+- `page-head-overlap` (error): something is painting on top of a page's own heading. This is the
+  one check measured at **800x600** — Puppeteer's default viewport, and so the size a smoke check
+  judges your catalog at — because the overlap it catches does not appear at 1280 at all: a page
+  title that is a single unbroken identifier (a long Swift type name, say) has no break
+  opportunity for the browser to use, so it keeps its full intrinsic width and paints past its own
+  column into the previous/next buttons. It measures every leaf element carrying text, clips each
+  rect to any ancestor that scrolls or clips (so something scrolled out of view is not reported as
+  covering anything), and reports a pair only when it overlaps the heading by more than 1px in
+  both directions, so a shared edge between neighbours is not a finding. Only the heading is
+  checked: specimens legitimately stack text, and reporting those would bury the one overlap that
+  is always a defect.
 - `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
+install a browser. It takes about two minutes for 50 pages — plus a moment per page for the
+narrow-viewport heading pass — and works with `--json` (progress
 goes to stderr), `--ci` and `doctor.strict`, so CI can run `npx ds-viewer doctor --render --ci`.
 
 It starts its own catalog on the first free port from 5181. `--port <n>` pins it instead, which

package/dist/cli/render.js

@@ -121,6 +121,83 @@ export function identicalVariantIssues(page, pairs) {
         fix: "Make the difference visible — a wider specimenSize when the cell is too narrow to show it, or the prop the name claims — or drop one of the two examples.",
     }));
 }
+/**
+ * The width the heading check measures at. 800x600 is Puppeteer's own default viewport, which is
+ * what a consumer's smoke check uses unless it says otherwise, so it is the width their catalog is
+ * judged at. Every other check here runs at 1280x800, where this class of overlap does not appear
+ * at all — which is exactly why issue #51 reached a release.
+ */
+export const NARROW_VIEWPORT = { width: 800, height: 600 };
+/**
+ * Runs in the browser: finds anything painting on top of the page's own heading.
+ *
+ * The page head puts the title in a `flex: 1` column beside a non-shrinking pager row. A title
+ * that is one unbroken identifier — a Swift type name, say — has no space for the browser's
+ * default line breaking to use, so without an explicit break opportunity it keeps its full
+ * intrinsic width and paints straight through the column into the pager (issue #51:
+ * `TranscriptMediaUnavailableChip` covered the `←` button by 14x22 at an 800px window). The
+ * reader sees the title and the control drawn over each other, and the title is the page's own
+ * heading, so it is the one thing on the page that must stay readable.
+ *
+ * Measured the way a consumer's own smoke check measures it: every leaf element that carries
+ * text, its rect clipped to each ancestor that handles its own overflow (so a scrolled-away rect
+ * is not reported as covering anything), and a pair counted only when it overlaps by more than
+ * 1px in BOTH directions — a shared edge or a single-pixel seam between neighbours is not an
+ * overlap.
+ *
+ * Only the heading is checked, not every pair on the page. Host specimens legitimately stack text
+ * — a badge over a thumbnail, a caption over a surface — and reporting those would bury the one
+ * overlap that is always a defect. The heading's own descendants are skipped for the same reason:
+ * a heading's `<Text>` child sits inside its `<View>` by construction.
+ */
+export const HEAD_OVERLAP_SCRIPT = `(() => {
+  const doc = document;
+  const CONTAINS = /^(auto|scroll|hidden|clip)$/;
+  const heading = doc.querySelector('[role="heading"]');
+  if (!heading) return [];
+  const clip = (el) => {
+    const r = el.getBoundingClientRect();
+    let x1 = r.left, y1 = r.top, x2 = r.right, y2 = r.bottom;
+    for (let n = el.parentElement; n; n = n.parentElement) {
+      const cs = getComputedStyle(n);
+      if (CONTAINS.test(cs.overflowX) || CONTAINS.test(cs.overflowY)) {
+        const b = n.getBoundingClientRect();
+        if (b.left > x1) x1 = b.left;
+        if (b.top > y1) y1 = b.top;
+        if (b.right < x2) x2 = b.right;
+        if (b.bottom < y2) y2 = b.bottom;
+      }
+    }
+    return { x1: x1, y1: y1, x2: x2, y2: y2 };
+  };
+  const head = clip(heading);
+  if (head.x2 - head.x1 <= 0 || head.y2 - head.y1 <= 0) return [];
+  const out = [];
+  for (const el of doc.querySelectorAll('*')) {
+    if (el.children.length) continue;
+    if (el === heading || heading.contains(el)) continue;
+    const text = (el.textContent || '').trim();
+    if (!text) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0) continue;
+    const b = clip(el);
+    if (b.x2 - b.x1 <= 0 || b.y2 - b.y1 <= 0) continue;
+    const w = Math.min(head.x2, b.x2) - Math.max(head.x1, b.x1);
+    const h = Math.min(head.y2, b.y2) - Math.max(head.y1, b.y1);
+    if (w > 1 && h > 1) out.push({ other: text.slice(0, 40), w: Math.round(w), h: Math.round(h) });
+  }
+  return out;
+})()`;
+export function headOverlapIssues(ref, overlaps) {
+    return overlaps.map((o) => ({
+        id: 'page-head-overlap',
+        severity: 'error',
+        page: ref.id,
+        ...(ref.file ? { file: ref.file } : {}),
+        message: `At ${NARROW_VIEWPORT.width}px the page heading is covered by "${o.other}" over ${o.w}x${o.h}px.`,
+        fix: 'Let the heading wrap or truncate inside its own column, or move or clip whatever paints over it.',
+    }));
+}
 /**
  * Runs in the browser: finds specimen content that paints outside its cell and cannot be reached.
  *
@@ -213,6 +290,8 @@ const DEV_START_TIMEOUT_MS = 120_000;
 const FIRST_LOAD_TIMEOUT_MS = 300_000;
 const PAGE_TIMEOUT_MS = 120_000;
 const SETTLE_MS = 900;
+/** After a viewport change, long enough for react-native-web to reflow before anything is measured. */
+const RESIZE_SETTLE_MS = 250;
 /** Stops `dev` and everything it started (Expo/Metro): the whole process tree on Windows, the
  *  whole process group elsewhere (Expo stops through dev's own signal handler). Releases the pipes
  *  so this process can exit. `os` is injectable for tests. */
@@ -436,6 +515,20 @@ export async function renderCheck(projectRoot, options = {}) {
                 }
                 if (Array.isArray(clipped))
                     issues.push(...clippedSpecimenIssues({ id, file: options.files?.get(id) }, clipped));
+                // Last, because it is the only check that changes the viewport: the overlap it guards
+                // appears only at a narrow width, and every check above is calibrated at 1280. Advisory
+                // like the two passes above — a failing script must not cost this page its other findings.
+                let headOverlaps;
+                try {
+                    await page.setViewport({ width: NARROW_VIEWPORT.width, height: NARROW_VIEWPORT.height });
+                    await new Promise((r) => setTimeout(r, RESIZE_SETTLE_MS));
+                    headOverlaps = (await page.evaluate(HEAD_OVERLAP_SCRIPT));
+                }
+                catch {
+                    headOverlaps = undefined;
+                }
+                if (Array.isArray(headOverlaps))
+                    issues.push(...headOverlapIssues({ id, file: options.files?.get(id) }, headOverlaps));
                 await page.close();
             }
             catch (error) {

package/native/catalog/SectionBlock.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useState } from 'react';
-import { View, Text, Pressable, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { View, Text, Pressable, StyleSheet, type LayoutChangeEvent, type TextStyle } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TEXT } from './tokens';
 import { ComparisonGrid } from './ComparisonGrid';
 import { ComparisonGroups } from './ComparisonGroups';
@@ -391,7 +391,15 @@ const styles = StyleSheet.create({
     backgroundColor: CATALOG_COLOR.surface,
   },
   osBadgeText: { ...CATALOG_TEXT.microLabel, color: CATALOG_COLOR.text },
-  title: { ...CATALOG_TEXT.pageTitle, color: CATALOG_COLOR.text, marginBottom: 5 },
+  // `wordBreak` isn't declared on React Native's own `TextStyle` (react-native-web's own
+  // `Text/types.js` declares it; a browser applies any valid CSS property name it recognizes
+  // regardless — same caveat ReferenceDetails.tsx's own `mono` style documents), so this is cast
+  // the same way. Without it, an unbroken page title (a component identifier with no spaces,
+  // e.g. `TranscriptVideoPreviewPlayerView`) has no space for the browser's default line-breaking
+  // to use: it stays one unbroken run at its full intrinsic width — wide enough to push past
+  // `titleText`'s own column and into the pager — instead of wrapping inside the column like any
+  // title with spaces already does.
+  title: { ...CATALOG_TEXT.pageTitle, color: CATALOG_COLOR.text, marginBottom: 5, wordBreak: 'break-word' } as TextStyle,
   desc: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted, maxWidth: 700 },
   pager: { flexDirection: 'row', gap: 6, flexShrink: 0 },
   pagerButton: {

package/package.json

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