@krapwoo/ds-viewer 0.9.0 → 0.10.0

package/native/catalog/VariantGroup.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { CATALOG_TYPE, CATALOG_COLOR } from './tokens';
+import { CATALOG_TEXT, CATALOG_COLOR } from './tokens';
 
 /** Labels one example (or small group of examples) inside a section's Examples card — a bold
  *  uppercase name plus a one-line description stacked below it, sitting above whatever demo content
@@ -39,10 +39,7 @@ const styles = StyleSheet.create({
   group: { gap: 6 },
   groupCenter: { alignItems: 'center' },
   groupLeft: { alignItems: 'flex-start' },
-  name: {
-    fontSize: CATALOG_TYPE.xs, fontWeight: '700', color: CATALOG_COLOR.text,
-    textTransform: 'uppercase', letterSpacing: 0.4,
-  },
-  desc: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  name: { ...CATALOG_TEXT.microLabel, color: CATALOG_COLOR.text },
+  desc: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
   textCenter: { textAlign: 'center' },
 });

package/native/catalog/index.ts

@@ -55,6 +55,9 @@ export type { ListGroup, ListItem } from './comparison';
 export {
   CATALOG_TYPE,
   CATALOG_TYPE_USE,
+  CATALOG_FONT,
+  CATALOG_TEXT,
+  CATALOG_TEXT_USE,
   CATALOG_SPACE,
   CATALOG_SPACE_USE,
   CATALOG_RADIUS,

package/native/catalog/tokens.ts

@@ -28,6 +28,32 @@ export const CATALOG_TYPE = {
   '4xl': 40,
 } as const;
 
+export const CATALOG_FONT = { code: 'Menlo, monospace' } as const;
+
+/** The catalog's fixed set of typography roles, each a complete `fontSize`/`fontWeight`/
+ *  `lineHeight` (plus `letterSpacing`/`textTransform`/`fontFamily` where the role needs them)
+ *  built on `CATALOG_TYPE`. Every catalog-chrome text style spreads one of these rather than
+ *  setting its own typography properties directly (enforced by
+ *  `__tests__/textRoles.test.ts`). */
+export const CATALOG_TEXT = {
+  pageTitle: { fontSize: CATALOG_TYPE.pageTitle, fontWeight: '700', lineHeight: 34 },
+  heading1: { fontSize: CATALOG_TYPE['2xl'], fontWeight: '700', lineHeight: 30 },
+  heading2: { fontSize: CATALOG_TYPE.xl, fontWeight: '700', lineHeight: 24 },
+  heading3: { fontSize: CATALOG_TYPE.lg, fontWeight: '700', lineHeight: 22 },
+  icon: { fontSize: CATALOG_TYPE.lg, fontWeight: '400', lineHeight: 22 },
+  body: { fontSize: CATALOG_TYPE.md, fontWeight: '400', lineHeight: 20 },
+  bodyStrong: { fontSize: CATALOG_TYPE.md, fontWeight: '700', lineHeight: 20 },
+  caption: { fontSize: CATALOG_TYPE.sm, fontWeight: '400', lineHeight: 18 },
+  captionStrong: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', lineHeight: 18 },
+  label: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', lineHeight: 18, letterSpacing: 0.72, textTransform: 'uppercase' },
+  micro: { fontSize: CATALOG_TYPE.xs, fontWeight: '400', lineHeight: 14 },
+  microLabel: { fontSize: CATALOG_TYPE.xs, fontWeight: '700', lineHeight: 14, letterSpacing: 0.6, textTransform: 'uppercase' },
+  code: { fontSize: CATALOG_TYPE.md, fontWeight: '400', lineHeight: 20, fontFamily: CATALOG_FONT.code },
+  codeSmall: { fontSize: CATALOG_TYPE.sm, fontWeight: '400', lineHeight: 18, fontFamily: CATALOG_FONT.code },
+  codeSmallStrong: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', lineHeight: 18, fontFamily: CATALOG_FONT.code },
+  codeMicro: { fontSize: CATALOG_TYPE.xs, fontWeight: '400', lineHeight: 14, fontFamily: CATALOG_FONT.code },
+} as const;
+
 export const CATALOG_SPACE = {
   xs: 4,
   sm: 8,
@@ -75,22 +101,44 @@ export const CATALOG_LAYOUT = {
 export const CATALOG_MAX_CONTENT_WIDTH = 1200;
 
 /** When to reach for each catalog-chrome type size. Rendered in the framework catalog's Type
- *  Scale page. */
+ *  Scale page. Every size is now consumed through a `CATALOG_TEXT` role (see `CATALOG_TEXT_USE`)
+ *  rather than directly. */
 export const CATALOG_TYPE_USE: Record<keyof typeof CATALOG_TYPE, string> = {
-  xs: 'Sidebar group labels (uppercase); a prop\'s type annotation.',
-  tableHeader: 'Grid column headers and list cell captions (uppercase).',
-  sm: 'Breadcrumb, catalog caption, block labels, prop names and descriptions.',
-  panelHeading: 'Reference-panel headings: Guidance, Quick reference, Props (uppercase).',
-  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: "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.',
+  xs: 'Backs the `micro`, `microLabel` and `codeMicro` roles: token values and meta captions; sidebar group labels and OS badges (uppercase); a prop\'s type and default value (monospace).',
+  tableHeader: 'Reserved — no current consumer; grid column headers and list cell captions now use the `captionStrong` role (built on `sm`).',
+  sm: 'Backs the `caption`, `captionStrong`, `label`, `codeSmall` and `codeSmallStrong` roles: breadcrumbs, block/prop descriptions, swatch/token names, table captions, monospace prop names and file paths.',
+  panelHeading: 'Reserved — no current consumer; reference-panel and update-page headings now use the `label` role (built on `sm`).',
+  md: 'Backs the `body`, `bodyStrong` and `code` roles: descriptions, nav links, the filter field, switch labels, a long unbroken value that needs to wrap at its \'/\'s (monospace).',
+  lg: 'Backs the `heading3` and `icon` roles: a result note\'s title; pager arrows and the filter field\'s clear (×) glyph.',
+  brand: 'Reserved — no current consumer; the sidebar app name now uses the `heading2` role (built on `xl`).',
+  xl: 'Backs the `heading2` role: the app name at the top of the sidebar.',
+  '2xl': 'Backs the `heading1` role: the update page\'s version numbers and the arrow between them.',
+  pageTitle: 'Backs the `pageTitle` role: the selected page\'s title, including the update page\'s own title.',
   '3xl': 'Reserved — no current consumer.',
   '4xl': 'Reserved — no current consumer.',
 };
 
+/** When to reach for each catalog-chrome typography role. Rendered in the framework catalog's
+ *  Type Scale page. */
+export const CATALOG_TEXT_USE: Record<keyof typeof CATALOG_TEXT, string> = {
+  pageTitle: 'The selected page\'s title, including the update page\'s own title.',
+  heading1: 'The update page\'s version numbers and the arrow between them.',
+  heading2: 'The app name at the top of the sidebar.',
+  heading3: 'A result note\'s title (the update page\'s success/failure banner).',
+  icon: 'Glyph-only controls: pager arrows, the filter field\'s clear (×) glyph, the update banner\'s close (×) glyph.',
+  body: 'Default body text: descriptions, nav links, the filter field, update-page facts/notes/steps.',
+  bodyStrong: 'Emphasised body text: grid/list row headers, switch and step labels, inline-bold notice text.',
+  caption: 'Secondary text: breadcrumbs, status captions, block/prop descriptions, sidebar subtitle/footer, update-page captions.',
+  captionStrong: 'Emphasised secondary text: grid column headers, grid/list/table captions, reference-panel subheadings, swatch/token names, replay and result links, step-icon glyphs.',
+  label: 'Uppercase labels and headings: block and preview-frame labels, token-section labels, reference-panel and update-page headings.',
+  micro: 'The smallest text: token values and meta captions, a prop\'s default-value label.',
+  microLabel: 'Uppercase micro labels: variant-group names, sidebar group labels, OS badges.',
+  code: 'Monospace body text: a long unbroken value that needs to wrap at its \'/\'s.',
+  codeSmall: 'Monospace secondary text: a prop\'s optional marker, the update page\'s inline code, file paths and log lines.',
+  codeSmallStrong: 'Emphasised monospace secondary text: a prop\'s own name.',
+  codeMicro: 'Monospace micro text: a prop\'s type and default value.',
+};
+
 /** When to reach for each catalog-chrome spacing step. Rendered in the framework catalog's
  *  Spacing page. */
 export const CATALOG_SPACE_USE: Record<keyof typeof CATALOG_SPACE, string> = {
@@ -135,7 +183,10 @@ export const CATALOG_COLOR = {
   accentSubtle: '#e9efff',
   /** 3px keyboard focus ring on every catalog control. */
   focusRing: '#c9d7ff',
-  code: 'Menlo',
+  /** @deprecated kept for the public API; re-points at `CATALOG_FONT.code` so there is one source
+   *  of truth. New code should reach for `CATALOG_FONT.code` (or a `CATALOG_TEXT` `code*` role)
+   *  instead. */
+  code: CATALOG_FONT.code,
   /** Major-update banner background/border/text (design §5 "Viewer notice"). */
   warning: '#8a4b00',
   warningSubtle: '#fff4e0',

package/native/catalog/updatePanelState.ts

@@ -219,3 +219,176 @@ export function resultNote(
 export function isRemoteOrigin(protocol: string, hostname: string): boolean {
   return !(protocol === 'http:' && hostname === 'localhost');
 }
+
+/** `VersionDetails`' own near-miss message, when the endpoint answered with a non-ok status (not
+ *  a rejected fetch) and the page is open from a tunnelled/remote origin. Pulled out as its own
+ *  function only so a test can pin it exactly — the approved design leaves this condition alone
+ *  ("Keep the existing distinct remote-origin/tunnel message exactly as is"). */
+export function remoteOriginLocalErrorMessage(): string {
+  return 'This page is open from another address, and the viewer only takes actions from the machine it runs on. Open the catalog on that machine, or run npx ds-viewer update there.';
+}
+
+/** The result of one endpoint call, classified the one way that matters for self-healing: did
+ *  `fetch` itself reject (the socket is simply gone — *unreachable*, see the implementation
+ *  brief), or did it resolve with a response at all, however unhappy (401/409/502 included — the
+ *  endpoint answered, so the caller's existing status/body handling is unchanged and untouched by
+ *  this module). Every endpoint call on the update page routes through this one function so "one
+ *  condition has one treatment" instead of each call site re-deriving it. */
+export type EndpointOutcome = { kind: 'ok'; response: Response } | { kind: 'unreachable' };
+
+export async function requestOrUnreachable(doFetch: () => Promise<Response>): Promise<EndpointOutcome> {
+  try {
+    return { kind: 'ok', response: await doFetch() };
+  } catch {
+    return { kind: 'unreachable' };
+  }
+}
+
+/** Critical finding, Fable correction pass: `cli/endpoint.ts` answers a rejected `Origin` with
+ *  403 and *no* CORS headers, so the browser blocks the response and the page's own `fetch`
+ *  rejects — exactly like a genuinely dead socket. Without this check, that rejection was routed
+ *  straight into the page-wide reachability flow, which reloads and then polls forever for a
+ *  server that was never down; self-healing is meaningless for a page that can never use the
+ *  endpoint in the first place (a tunnel, or `isRemoteOrigin`'s own `127.0.0.1` case). Every call
+ *  site with a rejected fetch must check this *before* calling into the reachability flow, and
+ *  keep showing `remoteOriginLocalErrorMessage()` instead. */
+export function classifyRejectedFetch(isRemoteOriginPage: boolean): 'remote-origin' | 'unreachable' {
+  return isRemoteOriginPage ? 'remote-origin' : 'unreachable';
+}
+
+/** The pre-existing offline plan-error outcome (`fetchPlan`'s own `catch`) — pulled out so the one
+ *  other place that needs it (below) can't drift from this wording. */
+export const PLAN_FETCH_ERROR: { error: string } = { error: "Couldn't prepare the update. You may be offline, or npm didn't respond. Nothing was changed." };
+
+/** Correction pass 3: a background `fetchPlan` whose fetch was rejected routes through
+ *  `routeUnreachableInBackground`, which refuses to act for a remote-origin page (it must never
+ *  latch the page-wide `remoteOriginError` state for a call the user didn't make — correction pass
+ *  #2). That refusal used to be the end of it: `planResult` stayed `undefined` forever, and
+ *  `resolvePanelPhase` reads that as `'checking'` with no button and no way out. `handled` is
+ *  whatever that route reports back — `true` once it has entered the reachability flow (which owns
+ *  the page from there), `false` when it declined to act. Only the `false` case needs anything
+ *  here: fall back to the exact same plan-error note (and working **Try again**) the pre-existing
+ *  `catch` already shows for every other kind of plan failure. */
+export function backgroundPlanFetchOutcome(handled: boolean): { error: string } | undefined {
+  return handled ? undefined : PLAN_FETCH_ERROR;
+}
+
+/** Critical finding, Fable correction pass: the restart-handoff rule ("a failed `/update/status`
+ *  poll while an update was already in flight or restarting means 'still restarting,' not
+ *  unreachable") used to be decided by reading a value assigned inside the very `setStatus`
+ *  updater that decided it — updaters run during React's render phase, not at dispatch, so under
+ *  any pending update the read could see stale or re-invoked state. Pulled out as a pure function
+ *  of the *already-committed* phase (read from a ref, never from inside an updater) so the
+ *  decision is both correct and independently testable. `undefined` means "not mid-update": the
+ *  caller must still classify the failure itself (unreachable vs. remote-origin, vs. a delivered
+ *  but unusable response). */
+export function statusPollFailureOutcome(currentPhase: UpdateStatusView['phase']): UpdateStatusView | undefined {
+  return currentPhase === 'updating' || currentPhase === 'restarting' ? { phase: 'restarting' } : undefined;
+}
+
+/** Correction pass 4 (Critical): a stable endpoint address means the restarted server answers the
+ *  already-open page's poll *before* Metro has served the new bundle — same host, same pinned
+ *  Metro origin, same reused secret, so the poll succeeds and would otherwise accept the delivered
+ *  `{ phase: 'success' }` onto the still-old page. `restarting` must be terminal for the page: only
+ *  the Metro-origin reload poller (which owns the actual reload) may leave it, by delivering
+ *  `'restarting'` right back — every other delivered phase while `restarting` is stale and must be
+ *  ignored. */
+export function acceptsDeliveredStatus(current: UpdateStatusView['phase'], next: UpdateStatusView['phase']): boolean {
+  return current !== 'restarting' || next === 'restarting';
+}
+
+/** Correction pass 5 (Important): whether a just-fetched plan is the offline error note rather
+ *  than a usable plan — `/plan` answers 200 with an `{ error }` body for that case, so a reached
+ *  plan fetch alone doesn't mean "Everything below is current." Takes the plan straight from the
+ *  fetch that produced it, never from a ref a passive effect fills in later, so this reads the
+ *  value that was actually just stored. */
+export function planShowsError(result?: UpdatePlanView | { error: string }): boolean {
+  return result !== undefined && 'error' in result && !isAlreadyUpToDateError(result);
+}
+
+/** The approved design's unreachable-recovery states (`waiting`/`stuck` replace this page's normal
+ *  content; `recovered` is a transient banner over content that's already current). Never
+ *  `'ok'`/absent here — the panel represents "nothing wrong" as no `ReachabilityState` at all, the
+ *  same way `UpdateStatusView`'s `idle` phase represents nothing in flight.
+ *
+ *  Final slice: a stable endpoint address (`cli/dev.ts` now reuses its port and secret across
+ *  restarts) means an ordinary restart recovers through the `waiting` poller's own direct endpoint
+ *  retry alone — no reload is needed, so there is no `reconnecting` phase anymore, and nothing in
+ *  this module ever calls `window.location.reload()`. The only reload left is the user's own
+ *  explicit press of **Reconnect** on `stuck`, handled entirely in `UpdatePanel.tsx`. */
+export type ReachabilityPhase = 'waiting' | 'recovered' | 'stuck';
+
+export interface ReachabilityState {
+  phase: ReachabilityPhase;
+  /** Consecutive failed endpoint retries while `waiting` — the bound `nextWaitingAttempt` gives up
+   *  at. Meaningless (and left unchanged) for every other phase. */
+  attempts: number;
+}
+
+/** ~20 seconds of 500ms retries (the same interval the existing restart flow already polls at) —
+ *  long enough for someone to actually type `npx ds-viewer dev`, short enough that the page
+ *  doesn't spin forever before offering the manual `Reconnect`. */
+export const REACHABILITY_MAX_ATTEMPTS = 40;
+
+/** One more failed attempt while `waiting`: advances the bounded counter and gives up once it
+ *  reaches `REACHABILITY_MAX_ATTEMPTS`, exactly as the approved design's "Edge · Still not back"
+ *  state requires. The caller (the `waiting` poller) only calls this when its own direct retry
+ *  against the endpoint has already failed; a retry that succeeds recovers in place and never
+ *  reaches this function at all. */
+export function nextWaitingAttempt(current: ReachabilityState): ReachabilityState {
+  const attempts = current.attempts + 1;
+  return { phase: attempts >= REACHABILITY_MAX_ATTEMPTS ? 'stuck' : 'waiting', attempts };
+}
+
+/** The manual **Reconnect** button on the gave-up state: starts the same bounded cycle over from
+ *  zero, exactly like the first time an endpoint call found the viewer unreachable. `UpdatePanel.tsx`
+ *  pairs this with its own, separate `window.location.reload()` — one press, one reload, initiated
+ *  by the user, so no marker or loop guard is needed here or anywhere else. */
+export function restartReachability(): ReachabilityState {
+  return { phase: 'waiting', attempts: 0 };
+}
+
+/** Called on every endpoint call that actually succeeds. Most of the time there was nothing to
+ *  recover from (`current` is `undefined`) and this is a no-op — the ordinary case, which must not
+ *  show a "Reconnected" banner on every routine poll. Otherwise the panel shows the approved
+ *  design's auto-dismissing `recovered` note while its normal content — already current, since the
+ *  endpoint itself just answered — resumes underneath. */
+export function recoveredReachabilityState(current: ReachabilityState | undefined): ReachabilityState | undefined {
+  if (current === undefined) return undefined;
+  return { phase: 'recovered', attempts: 0 };
+}
+
+export interface ReachabilityNote {
+  variant: 'muted' | 'ok';
+  spinner: boolean;
+  bold?: string;
+  text: string;
+  /** A recovery command to render in `Code`, split from its lead-in text so the component can
+   *  place the two in separate `Text`/`Code` nodes. */
+  hint?: { prefix: string; command: string };
+}
+
+/** The exact approved copy (`.hermes-task/approved-unreachable-states.html`) for each reachability
+ *  phase — never invent wording beyond this. */
+export function reachabilityNote(phase: ReachabilityPhase): ReachabilityNote {
+  switch (phase) {
+    case 'waiting':
+      return {
+        variant: 'muted',
+        spinner: true,
+        bold: 'The viewer isn’t running.',
+        text: ' Nothing was changed. This page reconnects by itself as soon as it’s back.',
+        hint: { prefix: 'Start it with ', command: 'npx ds-viewer dev' },
+      };
+    case 'recovered':
+      return { variant: 'ok', spinner: false, text: 'Reconnected. Everything below is current.' };
+    case 'stuck':
+      return {
+        variant: 'muted',
+        spinner: false,
+        bold: 'The viewer still isn’t answering.',
+        text: ' Nothing was changed.',
+        hint: { prefix: 'or start it with ', command: 'npx ds-viewer dev' },
+      };
+  }
+}

package/package.json

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