@fasl-work/caos-app-shell 0.7.2 → 0.8.1

package/README.md

@@ -3,15 +3,18 @@
 [![License](https://img.shields.io/github/license/fsantibanezleal/CAOS_APP_SHELL)](LICENSE)
 [![Version](https://img.shields.io/github/v/tag/fsantibanezleal/CAOS_APP_SHELL?label=version&sort=semver)](https://github.com/fsantibanezleal/CAOS_APP_SHELL/tags)
 
-The shared **web-app shell + content primitives + design system** for the CAOS / Faena public apps
-(implements [ADR-0016](https://github.com/fsantibanezleal)). Define the header, footer, theme, language
-toggle and content primitives **once** here; every app consumes them so the chrome is identical and a
-fix lands in one place.
+The shared **web-app shell, route types, views, drawings, design system and measured gate** of the CAOS / Faena
+public apps, one of the three parts of the CAOS base with the product template
+([CAOS_PRODUCT_TEMPLATE](https://github.com/fsantibanezleal/CAOS_PRODUCT_TEMPLATE)) and the policy (ADR-0016,
+ADR-0017, ADR-0071, ADR-0078). The frame, the header, the icons, the tab structure, the viewport, the areas, the text in
+drawings and the numbers are defined **once** here; every product composes them, so a fix lands in one place and no
+product writes them again. **Documentation: [`docs/`](docs/README.md)** (structure, tokens, navigation, views,
+drawings, icons and numbers, the gate, releasing).
 
 ## Install
 
 ```bash
-npm i @fasl-work/caos-app-shell
+npm i -E @fasl-work/caos-app-shell        # an exact pin: the build you gated is the build you ship
 # peer deps (the app provides them):
 npm i react react-dom react-router lucide-react katex zustand
 # optional: the house chart and the measured gate
@@ -50,7 +53,11 @@ const config: ShellConfig = {
 </BrowserRouter>
 ```
 
-- **Land on the tool:** `/` is the workbench; the five documentation routes are separate pages.
+- **Three route types** ([docs/01](docs/01_structure.md)): the **workbench** (`CaseWorkbench`, a product about
+  cases), the **surface** (`SurfacePage`, a hub, an explorer or a console: a head, one row of views, the open view
+  filling the rest), the **document** (`DocPage`). Under `contain` each fills or scrolls inside the viewport; no product
+  writes containment CSS.
+- **Land on the tool:** `/` is the App route; the five documentation routes are separate pages.
 - **One React, one router:** set `resolve.dedupe: ['react', 'react-dom', 'react-router']` in Vite. A second copy
   leaves the shell outside the router context; `AppShell` reports it with `console.error` and names the cause.
 - **Product metadata:** `license` and `visibility` are required: the footer shows the product's licence and a
@@ -70,11 +77,16 @@ const config: ShellConfig = {
 - **Drawing:** put canvas, WebGL and SVG instruments in a `Stage` (or `useStageSize`): nothing draws at zero
   size, and colours come from `useThemeTokens()` (a canvas cannot read CSS variables).
 - **Charts:** `import { UPlotChart } from "@fasl-work/caos-app-shell/chart"`: x and y titles with units, series
-  by token colour, `marks` for what the engine detected, a key of every series when there are two or more, a cursor
-  readout row, theme and language rebuilds. Keep series labels short: the key wraps under the plot.
+  by token colour, `marks` for what the engine detected (placed inside the plot, haloed), a key of every series when
+  there are two or more, a cursor readout row, theme and language rebuilds, one tick notation per axis. Categories go
+  in `BarChart` (main entry, no uPlot). A drawing of your own measures its labels with the text kit (`textWidth`,
+  `fitLabel`, `niceTicks`) and declares `data-chart` ([docs/05](docs/05_drawings.md)).
+- **Views in the URL:** `CaseWorkbench` and `SurfacePage` hold the open view in `?view=` (and the case selector the
+  case in `?case=`), so a view can be shared and survives a reload.
+- **Icons:** lucide icons are sized by where they sit (`svg.lucide`); pass no `size` ([docs/06](docs/06_icons-and-numbers.md)).
 - **Numbers:** `formatNumber(value, lang, opts)` or `useFormat()`; never `toFixed` in a view. A magnitude below 1e-4
   is written in scientific notation (a p-value of 1e-200 is `1E-200`, not two hundred zeros); give `digits`, not
-  `decimals`, for p-values.
+  `decimals`, for p-values. A percent and a unit are joined by a no-break space.
 - **Documentation routes:** `DocPage` and `DocSection` (each section ends in its own `Refs`, or states why it
   cites nothing), `Equation` with a caption, `CitationsProvider` and `Cite` (every citation has a DOI or URL).
   `Tabs`, `SubTabs` and `TabGroups` are controllable and render only the open panel inside a `PanelBoundary`.
@@ -85,9 +97,14 @@ const config: ShellConfig = {
   every route, tab, sub-tab and case at five sizes, both themes and both languages, and fails on: a wrong subject
   (G1) or mode (G2), console errors and 4xx/5xx (G3), broken deep links or HTML for an artifact (G4), anything a
   reader cannot scroll to, see whole or click (G5), blank or underfilled drawings and an instrument under half the
-  viewport (G6), a view that never settles (G7), loops at rest (G8), and controls that change nothing (G9). The
-  report (`gate-output/gate-report.json`) lists every failure and the smallest margins against each floor.
-- **Your own CSS:** never redefine a class in `reserved-classes.json`; the product guard reads that list.
+  viewport (G6), a view that never settles (G7), loops at rest (G8), controls that change nothing (G9), labels cut or
+  overlapping in a drawing, also in a wider fallback font (G10), a decimal point on a Spanish page (G11), a vertical
+  sub-tab list that scrolls away (G12), text under WCAG AA contrast (G13). The report
+  (`gate-output/gate-report.json`) lists every failure and the smallest margins against each floor; `index.html`
+  beside it shows every capture (G14). Details: [docs/07](docs/07_gate.md).
+- **Your own CSS:** never restyle a class of `reserved-classes.json` `components`; a `modifiers` word (`on`,
+  `active`, `fill`, `wide`) may be joined to your own class (`.my-row.on`), never used alone. The template's guard reads
+  that list. Values come from the tokens (`var(--rail-w)`, `var(--space-3)`, [docs/02](docs/02_tokens.md)).
 - **Animated views:** drive every canvas or 3D loop through `usePausedViz` (default paused, run once, halt on a
   hidden tab), never call `requestAnimationFrame` directly.
 
@@ -102,8 +119,11 @@ const config: ShellConfig = {
 `ReferenceList` (deprecated), `DocPage`, `DocSection`, `WorkbenchLayout`, `CaseWorkbench`,
 `MAX_WORKBENCH_GROUPS`, `VariantBar`, `LaneBadge`, `Readout`, `Gauge`, `Verdict`, `PlotCard`, `Knob`,
 `ChipGroup`, `Stage`, `useStageSize`, `makeStateKey`, `isStale`, `useWorkbenchState`,
-`WorkbenchStateContext`, `pick`. Separate entries: `/chart` (`UPlotChart`), `/keys` (the storage keys, no
-React), `/styles.css`, `/chart.css`, `/reserved-classes.json`. Bin: `caos-shell-gate`.
+`WorkbenchStateContext`, `pick`; since 0.8.0 `SurfacePage`, `useUrlView`, `viewParamOf`, `replaceQueryParam`,
+`BREAKPOINTS`, `BarChart`, `textWidth`, `widestLabel`, `fitLabel`, `niceTicks`, `niceStep`, `fontFamily`,
+`formatTicks`, `NBSP`, `SCIENTIFIC_BELOW`, the type `ShellColorToken`. Separate entries: `/chart` (`UPlotChart`,
+`drawMarks`, `tickSteps`, `repeatedLabels`), `/keys` (the storage keys, no React), `/styles.css`, `/chart.css`,
+`/reserved-classes.json`. Bin: `caos-shell-gate`.
 
 ### Authenticated workbenches
 

package/bin/caos-shell-gate.mjs

@@ -14,12 +14,13 @@
 //   --case-sample id1,id2        cases walked outside the primary mode; default the first and the last
 //   --single-case                the workbench has one case and no case control
 //   --idle-ms 3000  --settle-ms 15000  --text-floor 400  --instrument-min 0.5  --stage-fill-min 0.3
-//   --out gate-output            report (gate-report.json) and screenshots (shots/)
+//   --wide-font-sizes 390x844,1280x800   the sizes of the wide-font pass (G10); --no-wide-font skips it
+//   --out gate-output            report (gate-report.json), screenshots (shots/) and the capture index (index.html)
 // Needs `playwright` in the consuming project (optional peer dependency). Exit 1 on any failure, 2 on misuse.
 
 import { runGate } from '../gate/run.mjs';
 
-const FLAGS = new Set(['single-case']);
+const FLAGS = new Set(['single-case', 'no-wide-font']);
 const args = {};
 const argv = process.argv.slice(2);
 for (let i = 0; i < argv.length; i += 1) {
@@ -48,6 +49,8 @@ const options = {
   textFloor: num('text-floor'),
   instrumentMin: num('instrument-min'),
   stageFillMin: num('stage-fill-min'),
+  wideFontSizes: args['wide-font-sizes'],
+  wideFont: args['no-wide-font'] === true ? false : undefined,
   out: args.out,
 };
 for (const k of Object.keys(options)) if (options[k] === undefined) delete options[k];

package/dist/chart.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
-import { F as FormatOptions, S as ShellToken } from './tokens-CSV0MOgR.js';
+import uPlot from 'uplot';
+import { F as FormatOptions, S as ShellColorToken } from './tokens-DkyEXX5g.js';
 import { B as BiText } from './text-BlY47nIt.js';
 import 'zustand';
 
@@ -8,7 +9,7 @@ interface ChartSeries {
     /** One value per x; `null` leaves a gap. */
     values: (number | null)[];
     /** A shell colour token; defaults rotate through the accent palette. */
-    color?: ShellToken;
+    color?: ShellColorToken;
     width?: number;
     dash?: number[];
     /** `points` draws markers only (a scatter of cases over a curve); `null` values are simply absent. */
@@ -42,6 +43,30 @@ interface UPlotChartProps {
     /** Called with the index under the cursor (or null), for linked views. */
     onCursor?: (index: number | null) => void;
 }
+/**
+ * The tick steps an axis may use. With fixed `decimals` (scaled by 100 for a percent) only multiples of the smallest
+ * difference its labels can show, so no two ticks read the same: an integer axis ticks at integers, never at 1.5,
+ * which reads "2" beside the 2 (CAOS_Contraste, 2026-10-05). `undefined` leaves uPlot its own steps: an axis formatted
+ * by significant digits has no fixed resolution, and `data-ticks-repeat` reports what it does.
+ */
+declare function tickSteps(fmt: FormatOptions | undefined): number[] | undefined;
+/** How many tick labels repeat the label before them (empty labels apart); the gate fails a chart with any (G6). */
+declare function repeatedLabels(labels: readonly (string | null | undefined)[]): number;
+/**
+ * The vertical marks of a chart and their labels. Every label is drawn with an explicit alignment (uPlot leaves the
+ * context right-aligned after its last axis, so a label meant to start at its line ended there and ran off the plot
+ * near the left edge, CAOS_Fragmenta 2026-10-06), on the side of its line where it fits inside the plot, on the next
+ * row down when it would overlap the label before it, with a halo in the surface colour so a curve under it does not
+ * cross its letters. A mark outside the x range is not drawn.
+ */
+declare function drawMarks(u: uPlot, marks: {
+    x: number;
+    label: string;
+}[], style: {
+    color: string;
+    halo: string;
+    family: string;
+}): void;
 /**
  * The house chart (S12 of the 2026-10-04 requirements; uPlot, ADR on interactive charts). It is built only once its
  * box has a size; it resolves the theme's colours to concrete values and rebuilds when the theme or language changes
@@ -55,4 +80,4 @@ interface UPlotChartProps {
  */
 declare function UPlotChart({ x, y, series, marks, height, onCursor }: UPlotChartProps): react.JSX.Element;
 
-export { type ChartAxis, type ChartSeries, UPlotChart, type UPlotChartProps };
+export { type ChartAxis, type ChartSeries, UPlotChart, type UPlotChartProps, drawMarks, repeatedLabels, tickSteps };

package/dist/chart.js

@@ -1,4 +1,4 @@
-import { useShellLang, useThemeStore, useStageSize, pick, resolveToken, formatNumber } from './chunk-LOSSTLPP.js';
+import { useShellLang, useThemeStore, useStageSize, pick, resolveToken, NBSP, formatNumber, formatTicks } from './chunk-ZLJCB7DD.js';
 import './chunk-X6Y5CDUD.js';
 import { useRef, useCallback, useState, useMemo, useEffect } from 'react';
 import uPlot from 'uplot';
@@ -17,6 +17,46 @@ function repeatedLabels(labels) {
   for (let i = 1; i < labels.length; i++) if (labels[i] && labels[i] === labels[i - 1]) n++;
   return n;
 }
+function drawMarks(u, marks, style) {
+  const ctx = u.ctx;
+  const pr = uPlot.pxRatio || 1;
+  const left = u.bbox.left;
+  const right = u.bbox.left + u.bbox.width;
+  const gap = 4 * pr;
+  const rowH = 14 * pr;
+  const placed = [];
+  ctx.save();
+  ctx.font = `${Math.round(11 * pr)}px ${style.family}`;
+  ctx.textBaseline = "alphabetic";
+  ctx.lineJoin = "round";
+  for (const m of [...marks].sort((a, b) => a.x - b.x)) {
+    const px = u.valToPos(m.x, "x", true);
+    if (!Number.isFinite(px) || px < left - 0.5 || px > right + 0.5) continue;
+    ctx.strokeStyle = style.color;
+    ctx.lineWidth = Math.max(1, pr);
+    ctx.setLineDash([4 * pr, 4 * pr]);
+    ctx.beginPath();
+    ctx.moveTo(px, u.bbox.top);
+    ctx.lineTo(px, u.bbox.top + u.bbox.height);
+    ctx.stroke();
+    ctx.setLineDash([]);
+    const w = ctx.measureText(m.label).width;
+    let x0 = px + gap;
+    if (x0 + w > right) x0 = px - gap - w;
+    if (x0 < left) x0 = Math.max(left, Math.min(right - w, px - w / 2));
+    let row = 0;
+    while (placed.some((p) => p.row === row && x0 < p.x1 + gap && x0 + w + gap > p.x0)) row += 1;
+    placed.push({ x0, x1: x0 + w, row });
+    const y = u.bbox.top + 12 * pr + row * rowH;
+    ctx.textAlign = "left";
+    ctx.lineWidth = 3 * pr;
+    ctx.strokeStyle = style.halo;
+    ctx.strokeText(m.label, x0, y);
+    ctx.fillStyle = style.color;
+    ctx.fillText(m.label, x0, y);
+  }
+  ctx.restore();
+}
 function UPlotChart({ x, y, series, marks, height = 280, onCursor }) {
   const lang = useShellLang();
   const theme = useThemeStore((s) => s.theme);
@@ -57,10 +97,12 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor }) {
     if (!el || width <= 0 || h <= 0) return;
     const fg = resolveToken("--color-fg-subtle", "#888");
     const grid = resolveToken("--color-border", "#ccc");
-    const font = `11px ${resolveToken("--font-sans", "sans-serif")}`;
+    const family = resolveToken("--font-sans", "sans-serif");
+    const font = `11px ${family}`;
+    const surface = resolveToken("--color-surface", "#fff");
     const repeats = { x: 0, y: 0 };
     const tick = (fmt, axis) => (_u, vals) => {
-      const labels = vals.map((v) => v === null || v === void 0 ? "" : formatNumber(v, lang, fmt ?? { digits: 4 }));
+      const labels = formatTicks(vals, lang, fmt ?? { digits: 4 });
       repeats[axis] = repeatedLabels(labels);
       hostRef.current?.setAttribute("data-ticks-repeat", String(repeats.x + repeats.y));
       return labels;
@@ -92,11 +134,15 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor }) {
           labelFont: font,
           values: tick(y.format, "y"),
           ...ySteps ? { incrs: ySteps } : {},
+          // Sized to the longest tick label. uPlot draws in device pixels with a font scaled by its pixel ratio, so the
+          // label is measured in that font and divided back (measuring the unscaled font and dividing by the ratio
+          // made the axis too narrow on every high-density screen; the gate runs at ratio 1 and never saw it).
           size: (u, values) => {
             if (!values || values.length === 0) return 48;
-            u.ctx.font = font;
+            const pr = uPlot.pxRatio || 1;
+            u.ctx.font = `${Math.round(11 * pr)}px ${family}`;
             const widest = Math.max(...values.map((v) => u.ctx.measureText(v ?? "").width));
-            return Math.ceil(widest / (window.devicePixelRatio || 1)) + 30;
+            return Math.ceil(widest / pr) + 30;
           }
         }
       ],
@@ -118,21 +164,11 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor }) {
         draw: [
           (u) => {
             if (!marks?.length) return;
-            const ctx = u.ctx;
-            ctx.save();
-            ctx.strokeStyle = resolveToken("--color-warn", "#c80");
-            ctx.fillStyle = resolveToken("--color-warn", "#c80");
-            ctx.setLineDash([4, 4]);
-            ctx.font = font;
-            for (const m of marks) {
-              const px = u.valToPos(m.x, "x", true);
-              ctx.beginPath();
-              ctx.moveTo(px, u.bbox.top);
-              ctx.lineTo(px, u.bbox.top + u.bbox.height);
-              ctx.stroke();
-              ctx.fillText(pick(m.label, lang), px + 4, u.bbox.top + 12);
-            }
-            ctx.restore();
+            drawMarks(u, marks.map((m) => ({ x: m.x, label: pick(m.label, lang) })), {
+              color: resolveToken("--color-warn", "#c80"),
+              halo: surface,
+              family
+            });
           }
         ]
       }
@@ -148,9 +184,9 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor }) {
     uRef.current?.setData(data);
   }, [data]);
   const read = cursor !== null ? [
-    `${xLabel} ${formatNumber(x.values[cursor], lang, x.format ?? { digits: 4 })}${xUnit ? ` ${xUnit}` : ""}`,
+    `${xLabel} ${formatNumber(x.values[cursor], lang, x.format ?? { digits: 4 })}${xUnit ? `${NBSP}${xUnit}` : ""}`,
     ...series.map(
-      (s) => `${pick(s.label, lang)} ${formatNumber(s.values[cursor] ?? null, lang, y.format ?? { digits: 4 })}${yUnit ? ` ${yUnit}` : ""}`
+      (s) => `${pick(s.label, lang)} ${formatNumber(s.values[cursor] ?? null, lang, y.format ?? { digits: 4 })}${yUnit ? `${NBSP}${yUnit}` : ""}`
     )
   ].join(" \xB7 ") : lang === "es" ? "Pase el cursor sobre el gr\xE1fico para leer los valores" : "Hover the chart to read the values";
   return /* @__PURE__ */ jsxs(
@@ -175,4 +211,4 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor }) {
   );
 }
 
-export { UPlotChart };
+export { UPlotChart, drawMarks, repeatedLabels, tickSteps };

package/dist/{chunk-LOSSTLPP.js → chunk-ZLJCB7DD.js}

@@ -93,8 +93,36 @@ var SHELL_TOKENS = [
   "--color-shadow",
   "--font-sans",
   "--font-mono",
+  "--text-xs",
+  "--text-sm",
+  "--text-md",
+  "--text-base",
+  "--text-lg",
+  "--text-xl",
+  "--text-2xl",
+  "--space-1",
+  "--space-2",
+  "--space-3",
+  "--space-4",
+  "--space-5",
+  "--space-6",
+  "--radius-sm",
+  "--radius-md",
+  "--radius-lg",
+  "--radius-pill",
   "--maxw",
-  "--maxw-wide"
+  "--maxw-wide",
+  "--measure",
+  "--measure-text",
+  "--header-h",
+  "--rail-w",
+  "--fade",
+  "--icon-sm",
+  "--icon-md",
+  "--icon-lg",
+  "--z-header",
+  "--z-focus",
+  "--z-modal"
 ];
 function resolveToken(token, fallback = "") {
   if (typeof document === "undefined") return fallback;
@@ -112,14 +140,25 @@ function useThemeTokens() {
 
 // src/lib/format.ts
 var LOCALE = { en: "en-US", es: "es-CL" };
+var NBSP = "\xA0";
 var SCIENTIFIC_BELOW = 1e-4;
 var NOT_AVAILABLE = { en: "not available", es: "no disponible" };
 function formatNumber(value, lang, opts = {}) {
   if (value === null || value === void 0 || !Number.isFinite(value)) return NOT_AVAILABLE[lang];
   const v = opts.percent ? value * 100 : value;
   const digits = opts.digits ?? 4;
-  const nf = opts.decimals !== void 0 ? new Intl.NumberFormat(LOCALE[lang], { minimumFractionDigits: opts.decimals, maximumFractionDigits: opts.decimals }) : v !== 0 && Math.abs(v) < SCIENTIFIC_BELOW ? new Intl.NumberFormat(LOCALE[lang], { notation: "scientific", maximumSignificantDigits: digits }) : Math.abs(v) >= 10 ** (digits - 1) ? new Intl.NumberFormat(LOCALE[lang], { maximumFractionDigits: 0 }) : new Intl.NumberFormat(LOCALE[lang], { maximumSignificantDigits: digits });
-  return opts.percent ? `${nf.format(v)} %` : nf.format(v);
+  const scientific = v !== 0 && (opts.notation === "scientific" || Math.abs(v) < SCIENTIFIC_BELOW);
+  const nf = opts.decimals !== void 0 ? new Intl.NumberFormat(LOCALE[lang], { minimumFractionDigits: opts.decimals, maximumFractionDigits: opts.decimals }) : scientific ? new Intl.NumberFormat(LOCALE[lang], { notation: "scientific", maximumSignificantDigits: digits }) : Math.abs(v) >= 10 ** (digits - 1) ? new Intl.NumberFormat(LOCALE[lang], { maximumFractionDigits: 0 }) : new Intl.NumberFormat(LOCALE[lang], { maximumSignificantDigits: digits });
+  return opts.percent ? `${nf.format(v)}${NBSP}%` : nf.format(v);
+}
+function formatTicks(values, lang, opts = {}) {
+  let o = opts;
+  if (opts.decimals === void 0 && opts.notation === void 0) {
+    const scale = opts.percent ? 100 : 1;
+    const small = values.some((v) => v !== null && v !== void 0 && Number.isFinite(v) && v !== 0 && Math.abs(v * scale) < SCIENTIFIC_BELOW);
+    if (small) o = { ...opts, notation: "scientific" };
+  }
+  return values.map((v) => v === null || v === void 0 ? "" : formatNumber(v, lang, o));
 }
 function useFormat() {
   const lang = useShellLang();
@@ -171,4 +210,4 @@ function Stage({ label, children, className }) {
   );
 }
 
-export { NOT_AVAILABLE, SHELL_TOKENS, Stage, applyTheme, formatNumber, pick, readTheme, resolveToken, useFormat, useLangStore, useShellLang, useStageSize, useThemeStore, useThemeTokens };
+export { NBSP, NOT_AVAILABLE, SCIENTIFIC_BELOW, SHELL_TOKENS, Stage, applyTheme, formatNumber, formatTicks, pick, readTheme, resolveToken, useFormat, useLangStore, useShellLang, useStageSize, useThemeStore, useThemeTokens };