@krapwoo/ds-viewer 0.6.0 → 0.6.2

package/dist/cli/explain.js

@@ -58,6 +58,9 @@ function toSectionDef(page) {
         fullWidthLabel: page.fullWidthLabel,
         specimenSize: page.specimenSize,
         previewWidths: page.previewWidths,
+        // Carried because `blockMinWidth` reads it: the two preview cards have different chrome, so
+        // without it `explain` prices a 'table' preview as a frames card.
+        previewLayout: page.previewLayout,
         variants: page.variantsItems ? { itemsFill: page.variantsItemsFill, maxColumns: page.variantsMaxColumns, items: page.variantsItems.map(placeholderItem) } : undefined,
         states: page.statesItems ? { itemsFill: page.statesItemsFill, maxColumns: page.statesMaxColumns, items: page.statesItems.map(placeholderItem) } : undefined,
         comparison,

package/dist/cli/staticPage.js

@@ -120,6 +120,19 @@ function readStaticPage(file) {
         // Anything else (a function call, a non-literal expression) is simply left unset — `previewWidths`
         // isn't in design §4's literal-checkable list, so it's never a reason to flip `checkable`.
     }
+    const previewLayoutProp = findProp(pageObject, 'previewLayout');
+    if (previewLayoutProp) {
+        // Unlike `previewWidths`, an unread value here is not harmless: the two card shapes have
+        // different chrome, so a missed 'table' would make `explain` price the preview 16px wider
+        // than the viewer does.
+        const resolved = resolve(previewLayoutProp.initializer, consts, new Set());
+        if (ts.isStringLiteral(resolved) && (resolved.text === 'frames' || resolved.text === 'table')) {
+            page.previewLayout = resolved.text;
+        }
+        else {
+            page.checkable = false;
+        }
+    }
     const fullWidthLabelProp = findProp(pageObject, 'fullWidthLabel');
     if (fullWidthLabelProp)
         page.fullWidthLabel = stringLiteral(resolve(fullWidthLabelProp.initializer, consts, new Set()));

package/dist/native/catalog/tokens.js

@@ -113,6 +113,10 @@ export const CATALOG_COLOR = {
     surfaceMuted: '#fafafa',
     /** Hover and pressed feedback on nav rows and buttons. */
     surfacePressed: '#f1f3f8',
+    /** A disabled control's surface, and its label. Approved with the update page's buttons
+     *  (docs/design/2026-10-10-ds-viewer-update-page-always-approved.html). */
+    controlDisabled: '#e6e6e6',
+    controlDisabledText: '#8a8a8a',
     /** An example's cell when the example itself is white (`specimenSurface`), darker than surfaceMuted so a white card's edges show. */
     specimenStage: '#f2f2f2',
     pageBackground: '#f6f6f4',

package/native/catalog/CatalogButton.tsx

@@ -1,47 +1,85 @@
 import React, { forwardRef, useState } from 'react';
-import { Pressable, StyleSheet, Text, type View } from 'react-native';
-import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { ActivityIndicator, Pressable, StyleSheet, Text, type View } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 
 /** The viewer's own button, for catalog chrome and demo triggers (not an app component): a rounded
- *  rectangle, primary in the accent blue, secondary outlined. */
+ *  rectangle, primary in the accent blue, secondary outlined. `disabled` greys it and stops the
+ *  press; `busy` keeps its own colours while the action it started is still running, with a
+ *  spinner before the label. */
 export const CatalogButton = forwardRef<View, {
   label: string;
-  onPress: () => void;
+  /** Optional, because a permanently unavailable button still renders (see `disabled`). */
+  onPress?: () => void;
   variant?: 'primary' | 'secondary';
+  /** Not pressable, and visibly unavailable. */
+  disabled?: boolean;
+  /** Pressed already, still working: a spinner and a muted label. Also stops a second press. */
+  busy?: boolean;
   accessibilityLabel?: string;
-}>(function CatalogButton({ label, onPress, variant = 'primary', accessibilityLabel }, ref) {
+}>(function CatalogButton({ label, onPress, variant = 'primary', disabled = false, busy = false, accessibilityLabel }, ref) {
   const [focused, setFocused] = useState(false);
   const primary = variant === 'primary';
+  // Busy stops the press like disabled does — the action is already running — but keeps the
+  // button's own colours, because it is working rather than unavailable.
+  const off = disabled || busy;
   return (
     <Pressable
       ref={ref}
-      onPress={onPress}
+      onPress={off ? undefined : onPress}
+      disabled={off}
       onFocus={() => setFocused(true)}
       onBlur={() => setFocused(false)}
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel ?? label}
+      accessibilityState={{ disabled: off, busy }}
       style={({ pressed }) => [
         styles.base,
         primary ? styles.primary : styles.secondary,
-        pressed && (primary ? styles.primaryPressed : styles.secondaryPressed),
+        pressed && !off && (primary ? styles.primaryPressed : styles.secondaryPressed),
+        disabled && styles.disabled,
         focused && styles.focus,
       ]}
     >
-      <Text style={[styles.label, primary ? styles.labelPrimary : styles.labelSecondary]}>{label}</Text>
+      {busy ? <ActivityIndicator size="small" color={CATALOG_COLOR.textMuted} /> : null}
+      <Text
+        style={[
+          styles.label,
+          primary ? styles.labelPrimary : styles.labelSecondary,
+          busy && styles.labelBusy,
+          disabled && styles.labelDisabled,
+        ]}
+      >
+        {label}
+      </Text>
     </Pressable>
   );
 });
 
 const styles = StyleSheet.create({
   // A rounded rectangle (owner decision 2026-10-11); primary in the catalog's accent blue.
-  base: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: CATALOG_RADIUS.control, alignItems: 'center', justifyContent: 'center', alignSelf: 'center' },
+  // A row, so `busy` can put a spinner before the label without the label moving.
+  base: {
+    height: CATALOG_LAYOUT.controlSize,
+    paddingHorizontal: 18,
+    borderRadius: CATALOG_RADIUS.control,
+    flexDirection: 'row',
+    gap: CATALOG_SPACE.sm,
+    alignItems: 'center',
+    justifyContent: 'center',
+    alignSelf: 'center',
+  },
   primary: { backgroundColor: CATALOG_COLOR.accent },
   primaryPressed: { opacity: 0.85 },
   secondary: { borderWidth: 1, borderColor: CATALOG_COLOR.borderStrong, backgroundColor: CATALOG_COLOR.surface },
   secondaryPressed: { backgroundColor: CATALOG_COLOR.surfacePressed },
+  // One flat grey for both variants, so a disabled primary and a disabled secondary read the same:
+  // what stops the press is the state, not which button it is.
+  disabled: { backgroundColor: CATALOG_COLOR.controlDisabled, borderColor: CATALOG_COLOR.controlDisabled },
   // Same ring as the sidebar's: an outline, so focusing never shifts the layout.
   focus: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing } as object,
   label: { fontSize: CATALOG_TYPE.md, fontWeight: '700' },
   labelPrimary: { color: '#ffffff' },
   labelSecondary: { color: CATALOG_COLOR.text },
+  labelBusy: { color: CATALOG_COLOR.textMuted },
+  labelDisabled: { color: CATALOG_COLOR.controlDisabledText },
 });

package/native/catalog/SpecimenSurface.tsx

@@ -130,14 +130,18 @@ export function SpecimenContent({ fill, align, capped = true, children }: { fill
     if (!browser.Element || !browser.getComputedStyle || !node?.getBoundingClientRect) return;
     const wrapperWidth = node.getBoundingClientRect().width;
     const visible = paintedExtent(visibleBoxes(readTree(node, browser)));
-    if (fill && align === undefined && !centerNarrow && shouldCenterFilledContent(visible, wrapperWidth)) setCenterNarrow(true);
+    // Only for a phone-width cell. Centring exists for a small control adrift in a wide cell (a
+    // tooltip, a fixed-width skeleton); a 'page' cell holds a layout, whose own content is
+    // supposed to sit at the left of its own measure, and centring it collapses it to the width of
+    // whatever it happens to have painted.
+    if (capped && fill && align === undefined && !centerNarrow && shouldCenterFilledContent(visible, wrapperWidth)) setCenterNarrow(true);
     if ((globalThis as { __DEV__?: boolean }).__DEV__ && !warned.current && overflowsCell(visible, wrapperWidth)) {
       warned.current = true;
       console.warn(
         `[Catalog] ${address ? `${address.pageId} (${address.itemKey})` : 'An example'} is ${Math.round(visible)}px wide in a ${Math.round(wrapperWidth)}px cell, so it's cut off. Give the page a wider specimenSize ('regular', 'wide', or 'page' for components wider than a phone).`,
       );
     }
-  }, [fill, align, centerNarrow, address]);
+  }, [capped, fill, align, centerNarrow, address]);
   if (fill) {
     const alignItems = centerNarrow ? 'center' : specimenContentAlignItems(fill, align);
     return <View ref={ref} onLayout={measure} style={[SPECIMEN_SURFACE_WIDTH_STYLE, filledContentStyle(capped), { alignItems }]}>{children}</View>;

package/native/catalog/UpdatePanel.tsx

@@ -1,9 +1,10 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
-import { ActivityIndicator, Platform, Pressable, ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
+import { Platform, Pressable, ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { CatalogButton } from './CatalogButton';
 import { DS_VIEWER_SECRET_HEADER } from './catalogNavigation';
 import {
-  autoCheckHelp, bumpLabel, checkedAgoLabel, resultNote, daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
+  autoCheckHelp, bumpLabel, checkedAgoLabel, resultNote, daysAgoLabel, isAlreadyUpToDateError, isRemoteOrigin, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
 } from './updatePanelState';
 import type { UpdateNotice, VersionStatus } from './types';
 
@@ -11,6 +12,13 @@ function isWeb(): boolean {
   return Platform.OS === 'web' && typeof window !== 'undefined';
 }
 
+/** The page is open from somewhere other than the machine running the viewer, so every action will
+ *  be refused however healthy the server is — see `isRemoteOrigin`. */
+function remoteOrigin(endpoint: Endpoint | undefined): boolean {
+  if (!endpoint || !isWeb()) return false;
+  return isRemoteOrigin(window.location.protocol, window.location.hostname);
+}
+
 type Endpoint = { baseUrl: string; secret: string };
 
 async function authedFetch(endpoint: Endpoint, path: string, init: RequestInit = {}): Promise<Response> {
@@ -225,7 +233,12 @@ function VersionDetails({
       setJustChecked(next.lastOutcome === 'ok' && !next.update);
       onStatus(next);
     } catch {
-      setLocalError('Couldn’t reach the viewer’s local server. If this keeps happening, restart npx ds-viewer dev.');
+      setLocalError(remoteOrigin(endpoint)
+        // The endpoint only answers its own origin, and it can install packages and restart the
+        // server — so saying "restart the viewer" here would send the reader after a fault that
+        // isn't there. The page itself is fine over a tunnel; only its actions are local.
+        ? '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.'
+        : 'Couldn’t reach the viewer’s local server. If this keeps happening, restart npx ds-viewer dev.');
     } finally {
       setChecking(false);
     }
@@ -304,18 +317,12 @@ function VersionDetails({
       {localError && <NoteBox variant="err">{localError}</NoteBox>}
       {live && (
         <View style={styles.actions}>
-          <Pressable
+          <CatalogButton
+            variant="secondary"
+            busy={checking}
             onPress={checkNow}
-            disabled={checking}
-            accessibilityRole="button"
-            accessibilityState={{ disabled: checking, busy: checking }}
-            style={[styles.secondaryButton, styles.buttonRow, checking && styles.busyButton]}
-          >
-            {checking && <ActivityIndicator size="small" color={CATALOG_COLOR.textMuted} />}
-            <Text style={[styles.secondaryButtonText, checking && styles.busyButtonText]}>
-              {checking ? 'Checking…' : overview.action === 'retry' ? 'Try again' : 'Check now'}
-            </Text>
-          </Pressable>
+            label={checking ? 'Checking…' : overview.action === 'retry' ? 'Try again' : 'Check now'}
+          />
           {unreachable && !checking && <Text style={styles.muted}>or run <Code>npm view @krapwoo/ds-viewer version</Code></Text>}
         </View>
       )}
@@ -504,15 +511,7 @@ export function UpdatePanel({
           <Text style={styles.muted}>Not a git repository, so uncommitted changes couldn’t be checked.</Text>
         )}
         <View style={styles.actions}>
-          <Pressable
-            onPress={startUpdate}
-            disabled={starting}
-            accessibilityRole="button"
-            accessibilityState={{ disabled: starting }}
-            style={[styles.primaryButton, starting && styles.disabledButton]}
-          >
-            <Text style={[styles.primaryButtonText, starting && styles.disabledButtonText]}>Update now</Text>
-          </Pressable>
+          <CatalogButton label="Update now" onPress={startUpdate} disabled={starting} />
           {starting ? <Text style={styles.muted}>Starting…</Text> : <Text style={styles.muted}>or run <Code>npx ds-viewer update</Code></Text>}
         </View>
       </>
@@ -542,17 +541,8 @@ export function UpdatePanel({
         </NoteBox>
         <FilesList files={plan.files} />
         <View style={styles.actions}>
-          <Pressable
-            disabled
-            accessibilityRole="button"
-            accessibilityState={{ disabled: true }}
-            style={[styles.primaryButton, styles.disabledButton]}
-          >
-            <Text style={[styles.primaryButtonText, styles.disabledButtonText]}>Update now</Text>
-          </Pressable>
-          <Pressable onPress={fetchPlan} accessibilityRole="button" style={styles.secondaryButton}>
-            <Text style={styles.secondaryButtonText}>Check again</Text>
-          </Pressable>
+          <CatalogButton label="Update now" disabled />
+          <CatalogButton label="Check again" variant="secondary" onPress={fetchPlan} />
         </View>
       </>
     );
@@ -570,9 +560,7 @@ export function UpdatePanel({
           {' You may be offline, or npm didn’t respond. Nothing was changed.'}
         </NoteBox>
         <View style={styles.actions}>
-          <Pressable onPress={fetchPlan} accessibilityRole="button" style={styles.secondaryButton}>
-            <Text style={styles.secondaryButtonText}>Try again</Text>
-          </Pressable>
+          <CatalogButton label="Try again" variant="secondary" onPress={fetchPlan} />
           <Text style={styles.muted}>or run <Code>npx ds-viewer update</Code></Text>
         </View>
       </>
@@ -681,9 +669,6 @@ const styles = StyleSheet.create({
   switchLabel: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
   switch: { width: 44, height: 26 },
   switchHelp: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
-  buttonRow: { flexDirection: 'row', gap: CATALOG_SPACE.sm },
-  busyButton: { borderColor: CATALOG_COLOR.border },
-  busyButtonText: { color: CATALOG_COLOR.textMuted },
   muted: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 4 },
   block: { marginTop: 18 },
   h3: { fontSize: CATALOG_TYPE.panelHeading, textTransform: 'uppercase', letterSpacing: 0.5, color: CATALOG_COLOR.text, marginBottom: 8 },
@@ -695,12 +680,6 @@ const styles = StyleSheet.create({
   fileReason: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
   fileReasonDirty: { color: CATALOG_COLOR.warning, fontWeight: '700' },
   actions: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md, marginTop: 20 },
-  primaryButton: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: 22, backgroundColor: CATALOG_COLOR.text, alignItems: 'center', justifyContent: 'center' },
-  primaryButtonText: { color: '#fff', fontWeight: '700', fontSize: CATALOG_TYPE.md },
-  secondaryButton: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: 22, borderWidth: 1, borderColor: CATALOG_COLOR.borderStrong, alignItems: 'center', justifyContent: 'center' },
-  secondaryButtonText: { fontWeight: '700', fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text },
-  disabledButton: { backgroundColor: '#e6e6e6', borderColor: '#e6e6e6' },
-  disabledButtonText: { color: '#8a8a8a' },
   noteBox: { borderRadius: CATALOG_RADIUS.md, padding: 12, marginTop: 18 },
   noteBoxText: { fontSize: CATALOG_TYPE.md },
   noteBoxBold: { fontWeight: '700' },

package/native/catalog/tokens.ts

@@ -121,6 +121,10 @@ export const CATALOG_COLOR = {
   surfaceMuted: '#fafafa',
   /** Hover and pressed feedback on nav rows and buttons. */
   surfacePressed: '#f1f3f8',
+  /** A disabled control's surface, and its label. Approved with the update page's buttons
+   *  (docs/design/2026-10-10-ds-viewer-update-page-always-approved.html). */
+  controlDisabled: '#e6e6e6',
+  controlDisabledText: '#8a8a8a',
   /** An example's cell when the example itself is white (`specimenSurface`), darker than surfaceMuted so a white card's edges show. */
   specimenStage: '#f2f2f2',
   pageBackground: '#f6f6f4',

package/native/catalog/updatePanelState.ts

@@ -211,3 +211,11 @@ export function resultNote(
       );
   }
 }
+
+/** Whether a page at this protocol and hostname can use the viewer's local endpoint. The endpoint
+ *  allows exactly `http://localhost:<dev port>` — it installs packages and restarts the server —
+ *  so a tunnel, a LAN address or a reverse proxy is refused before the secret is read. Comparing
+ *  the page's origin with the endpoint's would be wrong: the endpoint is always on its own port. */
+export function isRemoteOrigin(protocol: string, hostname: string): boolean {
+  return !(protocol === 'http:' && hostname === 'localhost');
+}

package/package.json

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