@krapwoo/ds-viewer 0.4.4 → 0.4.6

package/native/catalog/specimenFill.ts

@@ -0,0 +1,102 @@
+/**
+ * Automatic cell fill for `specimenSurface: 'auto'` (the default): decides whether an example
+ * blends into its white comparison cell, so that one cell can turn gray. Kept free of any runtime
+ * import so `node --test` can assert on it directly (see `__tests__/specimenFill.test.ts`).
+ *
+ * The rule looks only at the example's largest painted box (the element with a background that
+ * covers the most area): if that box is near-white (every channel close to 255, so pale tints
+ * don't count) and has no visible border, the example's edges
+ * vanish against the white cell. A shadow alone doesn't count as an edge. Small boxes (under a
+ * tenth of the cell) and text-only examples never trigger it.
+ */
+
+export interface Rgba { r: number; g: number; b: number; a: number }
+
+/** One element inside an example, as measured in the browser. */
+export interface PaintedBox {
+  area: number;
+  background: Rgba | null;
+  /** The top border's colour when its width is above 0, else null. */
+  border: Rgba | null;
+}
+
+/** A fill is near-white when every channel (after compositing over the white cell) is at least
+ *  this. #fafafa and #f8f8f8 qualify; #f4f4f4 already reads as gray, and pale tints such as a
+ *  positive banner's rgb(240, 255, 244) read as colour, even when they're as bright as white. */
+const NEAR_WHITE_CHANNEL = 247;
+/** At or above this, a border draws the edge itself (#e4e4e4 is 1.27:1). */
+const VISIBLE_BORDER_CONTRAST = 1.2;
+/** A box smaller than this share of the cell is a detail, not the example's body. */
+const MIN_AREA_SHARE = 0.1;
+
+/** Parses a computed CSS colour (`rgb(…)`/`rgba(…)`). Fully transparent or unknown values are null. */
+export function parseCssColor(value: string): Rgba | null {
+  const match = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/.exec(value.trim());
+  if (!match) return null;
+  const alphaText = match[4];
+  const a = alphaText === undefined ? 1 : alphaText.endsWith('%') ? Number(alphaText.slice(0, -1)) / 100 : Number(alphaText);
+  if (!(a > 0)) return null;
+  return { r: Number(match[1]), g: Number(match[2]), b: Number(match[3]), a };
+}
+
+function channel(value: number): number {
+  const s = value / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+}
+
+/** True when every channel of `color`, composited over white, is at least `NEAR_WHITE_CHANNEL`. */
+export function isNearWhite(color: Rgba): boolean {
+  const over = (c: number) => color.a * c + (1 - color.a) * 255;
+  return Math.min(over(color.r), over(color.g), over(color.b)) >= NEAR_WHITE_CHANNEL;
+}
+
+/** WCAG contrast ratio against white, after compositing a translucent colour over the white cell. */
+export function contrastWithWhite(color: Rgba): number {
+  const over = (c: number) => color.a * c + (1 - color.a) * 255;
+  const luminance = 0.2126 * channel(over(color.r)) + 0.7152 * channel(over(color.g)) + 0.0722 * channel(over(color.b));
+  return 1.05 / (luminance + 0.05);
+}
+
+/** True when the example's body is near-white with no visible border, so it vanishes on a white cell. */
+export function blendsIntoCell(boxes: readonly PaintedBox[], cellArea: number): boolean {
+  let largest: PaintedBox | undefined;
+  for (const box of boxes) {
+    if (!box.background || box.area < cellArea * MIN_AREA_SHARE) continue;
+    if (!largest || box.area > largest.area) largest = box;
+  }
+  if (!largest?.background) return false;
+  if (!isNearWhite(largest.background)) return false;
+  return !(largest.border && contrastWithWhite(largest.border) >= VISIBLE_BORDER_CONTRAST);
+}
+
+/** Minimal DOM shapes, so this file needs no DOM lib types. */
+interface MeasurableElement {
+  getBoundingClientRect(): { width: number; height: number };
+  querySelectorAll(selector: string): ArrayLike<MeasurableElement>;
+}
+type ComputedStyleReader = (element: MeasurableElement) => {
+  backgroundColor: string;
+  borderTopColor: string;
+  borderTopWidth: string;
+  visibility: string;
+  opacity: string;
+};
+
+/** Measures every element inside `cell` (up to `limit`) in the browser. */
+export function measurePaintedBoxes(cell: MeasurableElement, readStyle: ComputedStyleReader, limit = 300): { boxes: PaintedBox[]; cellArea: number } {
+  const cellRect = cell.getBoundingClientRect();
+  const elements = cell.querySelectorAll('*');
+  const boxes: PaintedBox[] = [];
+  for (let i = 0; i < Math.min(elements.length, limit); i++) {
+    const element = elements[i];
+    const style = readStyle(element);
+    if (style.visibility === 'hidden' || Number(style.opacity) === 0) continue;
+    const rect = element.getBoundingClientRect();
+    boxes.push({
+      area: rect.width * rect.height,
+      background: parseCssColor(style.backgroundColor),
+      border: parseFloat(style.borderTopWidth) > 0 ? parseCssColor(style.borderTopColor) : null,
+    });
+  }
+  return { boxes, cellArea: cellRect.width * cellRect.height };
+}

package/native/catalog/specimenSurfaceStyle.ts

@@ -1,8 +1,10 @@
+import type { SpecimenSurfaceKind } from './types.ts';
+
 /**
- * `SpecimenSurface`'s width policy, kept free of any `react-native` import so `node --test` can
- * assert on it directly (see `native/catalog/__tests__/specimenSurfaceStyle.test.ts`).
+ * The example wrapper's width policy inside a cell, kept free of any `react-native` import so
+ * `node --test` can assert on it directly (see `__tests__/specimenSurfaceStyle.test.ts`).
  *
- * The surface always stretches to the full cross-axis width of whatever wraps it (a comparison
+ * The wrapper always stretches to the full cross-axis width of whatever wraps it (a comparison
  * cell, typically centered) rather than shrink-wrapping to its own content — `alignSelf: 'stretch'`
  * overrides a centered parent's `alignItems` for this one child. A compact specimen (e.g. Button)
  * still reads as centered, via `SpecimenSurface`'s own `alignItems`/`justifyContent: 'center'` on
@@ -13,3 +15,7 @@
 export const SPECIMEN_SURFACE_WIDTH_STYLE = {
   alignSelf: 'stretch',
 } as const;
+
+/** Each example's cell turns gray only when its example would vanish against white (see
+ *  `specimenFill.ts`). A page can force a fill with `specimenSurface`. */
+export const DEFAULT_SPECIMEN_SURFACE: SpecimenSurfaceKind = 'auto';

package/native/catalog/tokens.ts

@@ -119,6 +119,8 @@ export const CATALOG_COLOR = {
   surfaceMuted: '#fafafa',
   /** Hover and pressed feedback on nav rows and buttons. */
   surfacePressed: '#f1f3f8',
+  /** 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',
   chip: '#eeeeee',
   /** Active nav label, prop types, scale bars. */

package/native/catalog/types.ts

@@ -65,14 +65,12 @@ export type SpecimenSize = 'compact' | 'regular' | 'wide';
  *  content that is not a phone component (catalog chrome, token galleries). */
 export type PreviewWidths = readonly number[] | 'full';
 
-/** Background behind a live component specimen (the list/grouped/grid cell, or the preview frame)
- *  — a neutral (default), explicit white, dark, or transparent catalog-owned stage, so a specimen
- *  reads as visibly separate from the surrounding white card rather than floating on it, which
- *  matters most for a low-contrast or motion-only component that could otherwise blend into a
- *  plain white background. Purely a fixed catalog-chrome backdrop: it never inspects or infers the
- *  wrapped component's own colors, and is never applied to token galleries/sections, which keep
- *  their current full-width, unstaged presentation regardless of this setting. */
-export type SpecimenSurfaceKind = 'neutral' | 'white' | 'dark' | 'transparent';
+/** Fill of each example's cell. `'auto'` (default): a cell turns gray (#f2f2f2) only when its own
+ *  example would vanish against white — a near-white body with no visible border, like a white
+ *  card, sheet or neutral banner — so neighbouring examples keep a white cell. `'neutral'` makes
+ *  every example cell gray, `'white'` and `'transparent'` keep them white, `'dark'` checks light
+ *  components on a dark fill. Never applied to token galleries or sections. */
+export type SpecimenSurfaceKind = 'auto' | 'neutral' | 'white' | 'dark' | 'transparent';
 
 /** One real component this page's component is built from or composed with — rendered as a
  *  "Composition" subsection in Quick reference. `relationship` is `'built-in'` for a component
@@ -218,7 +216,7 @@ export interface SectionDef<TId extends string = string> {
    *  and everything else is 'regular'. */
   specimenSize?: SpecimenSize;
   /** Background stage behind every live component specimen on this page (list/grouped/grid cells,
-   *  and a `render()` preview that isn't a token gallery). Defaults to `'neutral'`. See
+   *  and a `render()` preview that isn't a token gallery). Defaults to `'auto'`. See
    *  `SpecimenSurfaceKind`. */
   specimenSurface?: SpecimenSurfaceKind;
   /** Widths for this page's `render()` preview, e.g. `[402, 320]` to add a small-phone example.
@@ -258,6 +256,26 @@ export interface UpdateNotice {
   releasedAt?: string;
 }
 
+/** Where the "check automatically" setting in effect comes from, strongest first: the
+ *  `DS_VIEWER_NO_UPDATE_CHECK=1` environment variable (CI), your own switch on the update page
+ *  (saved per project on this computer), the project's `updateCheck` config, or the default (on). */
+export type AutoCheckSource = 'env' | 'personal' | 'project' | 'default';
+
+/** What the update page and the sidebar's version line show. Written by `dev` at startup
+ *  (`.ds-viewer/version.json`) and kept current by the local endpoint (`GET /version`,
+ *  `POST /version/check`, `POST /version/auto-check`). */
+export interface VersionStatus {
+  /** The installed ds-viewer version. */
+  current: string;
+  autoCheck: { enabled: boolean; source: AutoCheckSource };
+  /** The last successful check on this computer (any project), when known. */
+  lastCheckedAt?: string;
+  /** This run's most recent check: answered, npm unreachable, or not run (checks off). */
+  lastOutcome: 'ok' | 'unreachable' | 'not-run';
+  /** A newer version, when one is known. */
+  update: UpdateNotice | null;
+}
+
 /** One titled card on a token page (`SectionDef.tokenSections`). */
 export interface TokenSection {
   /** The kind of token this card holds, e.g. "Semantic colours", "Palette", "Body". */

package/native/catalog/updatePanelState.ts

@@ -1,3 +1,5 @@
+import type { AutoCheckSource, VersionStatus } from './types.ts';
+
 /** The same shape as `cli/updatePlan.ts`'s `UpdatePlan` — duplicated, not imported: `native/catalog/`
  *  is the published package root and never imports from `cli/` (the reverse is normal: `cli/`
  *  already imports `native/catalog/` throughout). The endpoint's `POST /plan` response is this
@@ -72,3 +74,73 @@ export function daysAgoLabel(releasedAt: string, nowMs: number): string {
   if (days === 1) return 'Released 1 day ago.';
   return `Released ${days} days ago.`;
 }
+
+/** "Last checked" on the update page. */
+export function checkedAgoLabel(at: string | undefined, nowMs: number): string {
+  if (!at) return 'Never';
+  const minutes = Math.floor((nowMs - Date.parse(at)) / 60_000);
+  if (minutes < 1) return 'Just now';
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+  const days = Math.floor(hours / 24);
+  return `${days} day${days === 1 ? '' : 's'} ago`;
+}
+
+export interface VersionOverview {
+  pill?: 'latest' | 'off';
+  line: string;
+  note?: { variant: 'ok' | 'err'; bold?: string; text: string };
+  /** **Check now**, or **Try again** after npm didn't answer. */
+  action: 'check' | 'retry';
+}
+
+/** The update page when no newer version is known: which of "latest", "checks off", "not checked
+ *  yet" and "couldn't reach npm" applies. Only a check that actually answered may say "latest".
+ *  `justChecked` is true right after **Check now** found nothing newer. */
+export function versionOverview(status: VersionStatus, justChecked: boolean, nowMs: number): VersionOverview {
+  if (status.lastOutcome === 'unreachable') {
+    const last = status.lastCheckedAt ? ` The last successful check, ${checkedAgoLabel(status.lastCheckedAt, nowMs).toLowerCase()}, found no newer version.` : '';
+    return { line: `You’re on ${status.current}.`, action: 'retry', note: { variant: 'err', bold: 'Couldn’t reach npm.', text: ` You may be offline.${last}` } };
+  }
+  if (status.lastOutcome === 'not-run') {
+    if (!status.autoCheck.enabled) {
+      return { pill: 'off', line: `You’re on ${status.current}. Automatic checks are off, so this can’t tell whether a newer version exists.`, action: 'check' };
+    }
+    return { line: `You’re on ${status.current}. Not checked yet: automatic checks run when the viewer starts.`, action: 'check' };
+  }
+  // Turned off after a check answered (approved mockup state 7b); a fresh Check now still wins.
+  if (!status.autoCheck.enabled && !justChecked) {
+    return { pill: 'off', line: `You’re on ${status.current}. Automatic checks are off.`, action: 'check' };
+  }
+  return {
+    pill: 'latest',
+    line: 'You’re on the latest version.',
+    action: 'check',
+    ...(justChecked ? { note: { variant: 'ok' as const, text: 'Checked just now. No newer version.' } } : {}),
+  };
+}
+
+/** The switch's helper text: where the setting in effect comes from. Only CI's environment
+ *  variable locks the switch. */
+export function autoCheckHelp(autoCheck: { enabled: boolean; source: AutoCheckSource }): { text: string; locked: boolean } {
+  if (autoCheck.source === 'env') return { text: 'Off in this environment (DS_VIEWER_NO_UPDATE_CHECK=1).', locked: true };
+  if (autoCheck.source === 'personal') {
+    return { text: autoCheck.enabled ? 'Once a day, when the viewer starts. Saved for you on this computer.' : 'Turned off by you on this computer.', locked: false };
+  }
+  if (!autoCheck.enabled) {
+    return { text: 'Off for this project (updateCheck: false in ds-viewer.config.ts). Turning it on here applies to you only.', locked: false };
+  }
+  return { text: 'Once a day, when the viewer starts.', locked: false };
+}
+
+/** The update's size pill. Breaking updates are always "Major" (the CLI decides that); otherwise
+ *  a change in the second number is "Minor" and anything smaller "Patch". */
+export function bumpLabel(current: string, latest: string, breaking: boolean): 'Major' | 'Minor' | 'Patch' {
+  if (breaking) return 'Major';
+  const parts = (v: string) => /^(\d+)\.(\d+)\.(\d+)/.exec(v)?.slice(1, 4).map(Number);
+  const a = parts(current);
+  const b = parts(latest);
+  if (!a || !b) return 'Minor';
+  return a[0] === b[0] && a[1] === b[1] ? 'Patch' : 'Minor';
+}

package/package.json

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