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

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { A as AppShell, a as ArchTab, b as ArchitectureConfig, c as Architecture
 import * as react from 'react';
 import { ReactNode, Component, ErrorInfo } from 'react';
 import * as zustand from 'zustand';
-import { F as FormatOptions } from './tokens-CSV0MOgR.js';
-export { N as NOT_AVAILABLE, a as SHELL_TOKENS, S as ShellToken, f as formatNumber, r as resolveToken, u as useFormat, b as useThemeTokens } from './tokens-CSV0MOgR.js';
+import { F as FormatOptions } from './tokens-DkyEXX5g.js';
+export { N as NBSP, a as NOT_AVAILABLE, b as SCIENTIFIC_BELOW, c as SHELL_TOKENS, S as ShellColorToken, d as ShellToken, f as formatNumber, e as formatTicks, r as resolveToken, u as useFormat, g as useThemeTokens } from './tokens-DkyEXX5g.js';
 import { L as Lang, B as BiText } from './text-BlY47nIt.js';
 export { p as pick, u as useLangStore, a as useShellLang } from './text-BlY47nIt.js';
 
@@ -397,33 +397,62 @@ interface DocSectionProps {
 /** One section of a documentation route, ending in its own references. */
 declare function DocSection({ title, id, refs, noRefsReason, children }: DocSectionProps): react.JSX.Element;
 
-/** One section of the control rail. A rail whose content does not fit is SPLIT into sections, one shown at a
- * time, never scrolled (ADR-0071 rule 6: a panel must show its own controls). */
-interface RailSection {
-    id: string;
-    label: BiText;
-    content: ReactNode;
-}
-interface WorkbenchLayoutProps {
-    /** The control rail: case and variant pickers, parameters, the live readout. Either one node or sections. */
-    rail: ReactNode | RailSection[];
-    /** Shown above the rail (and above its sections): the case and variant pickers, which every section shares. */
-    railHead?: ReactNode;
-    /** The instrument: the views of the selected case. It takes the rest of the viewport (ADR-0071 rules 2, 8). */
-    children: ReactNode;
-    /** Accessible name of the rail. */
-    railLabel?: BiText;
-    className?: string;
+interface SurfacePageProps {
+    /** The route's heading; omit it when the header's active route already names the surface. */
+    title?: BiText;
+    /** One line under the title: what the surface is for. */
+    lede?: ReactNode;
+    /** Controls that act on the whole surface (a source picker, an export button), at the right of the head. */
+    actions?: ReactNode;
+    /** The surface's views: one row of at most six (ADR-0071 rule 5); the open one is held in the URL. */
+    tabs?: TabDef[];
+    /** Controlled selection, when the product holds it itself. */
+    value?: string;
+    onChange?: (id: string) => void;
+    /** The query parameter that holds the open view (default `view`); `false` keeps it out of the URL. */
+    deepLinkView?: boolean | string;
+    ariaLabel?: BiText;
+    /** Mark the body as the instrument, so the gate measures what is drawn in it (ADR-0071 rule 8). */
+    instrument?: boolean;
+    /** The body when there are no tabs: it fills the viewport. */
+    children?: ReactNode;
 }
 /**
- * The App route of a CAOS product: a sized control rail beside the instrument, on the full viewport.
- *
- * Renders `.page-body.wide.caos-wb`: no reading-width cap (a workbench is not prose, ADR-0071 rule 2),
- * `min-width: 0` down the tree so no row pushes the page wider than the screen (rule 3), a rail with an
- * explicit width that never scrolls (rule 6), and an instrument marked `data-instrument` so the measured gate
- * can check that it covers at least half of the viewport (rule 8). Pair with `ShellConfig.contain`.
+ * The third route type, beside the workbench (`WorkbenchLayout`, a rail and an instrument for one case) and the
+ * document (`DocPage`, a scrolling reading column): a SURFACE fills the viewport with views that are not one case's,
+ * such as a hub, an explorer or a console. Under `ShellConfig.contain` its head and tab row keep their height and the
+ * open panel scrolls inside; below 900 px the document scrolls. The containment fifteen to nineteen products wrote for
+ * themselves (CAOS_MANAGE audit 2026-10-07, section 3), owned here so no product writes it again.
  */
-declare function WorkbenchLayout({ rail, railHead, children, railLabel, className }: WorkbenchLayoutProps): react.JSX.Element;
+declare function SurfacePage({ title, lede, actions, tabs, value, onChange, deepLinkView, ariaLabel, instrument, children }: SurfacePageProps): react.JSX.Element;
+
+/** Writes one query parameter with replaceState, keeping the router's history state (React Router keeps its entry
+ * key and index there; replacing it with null broke the index the back button relies on). */
+declare function replaceQueryParam(param: string, value: string): void;
+/**
+ * The open view of a tab row, held in the URL (`?view=` by default) so a reader can share it and a reload keeps it.
+ * Returns the id to show and the selector to call. Controlled when `value` is given: the product holds the state and
+ * the URL is left alone. An id in the URL that names no tab of this row is ignored.
+ */
+declare function useUrlView(ids: string[], param: string | null, value?: string, onChange?: (id: string) => void): [string | undefined, (id: string) => void];
+/** The parameter name from a `deepLinkView` option: `true` or absent is `view`, a string names it, `false` is none. */
+declare function viewParamOf(option: boolean | string | undefined): string | null;
+
+/**
+ * The one set of widths the stylesheet changes layout at (styles.css header), for code that must agree with it (a
+ * drawing that chooses a compact form, a test that sizes a viewport). CSS media queries cannot read custom
+ * properties, so the numbers are written in both places and a unit test keeps them equal.
+ */
+declare const BREAKPOINTS: {
+    /** A phone: the brand keeps only its mark; the header drops its separators. */
+    readonly phone: 480;
+    /** The compact header, single-column grids, the vertical sub-tab list as a row. */
+    readonly compact: 760;
+    /** The workbench stacks its rail over the instrument and the contained document scrolls. */
+    readonly stack: 900;
+    /** The gate's large screen: the viewport rules of ADR-0071 are measured from here up. */
+    readonly large: 1280;
+};
 
 /** Where a value on screen came from: observed data, a generator, or a published reference. */
 type Provenance = 'real' | 'synthetic' | 'published';
@@ -457,90 +486,6 @@ declare function LaneBadge({ lane, provenance, label }: {
     label?: BiText;
 }): react.JSX.Element;
 
-/** One configured regime of a case: a full parameter vector, never a cosmetic label (ADR-0016 §9). */
-interface VariantDef {
-    id: string;
-    label: BiText;
-    /** One line: what this regime shows. */
-    note?: BiText;
-    /** The lane of this variant's result, when it differs from the bar's. */
-    lane?: Lane;
-    disabled?: boolean;
-}
-interface VariantBarProps {
-    variants: VariantDef[];
-    activeId: string;
-    onSelect: (id: string) => void;
-    title?: BiText;
-    lane?: Lane;
-}
-/** The regimes of the selected case on ONE scrollable row (ADR-0071 rule 4), the active regime's lane, and the
- * one-line note of what it shows. Selecting a regime must change every view of the case. */
-declare function VariantBar({ variants, activeId, onSelect, title, lane }: VariantBarProps): react.JSX.Element;
-
-/** One group of views of the selected case, named for the question the user is asking (ADR-0071 rule 5). */
-interface WorkbenchGroup {
-    id: string;
-    label: BiText;
-    /** Which lane produced this group's views, and what data they rest on. Each view shows its own badges (PlotCard,
-     * Readout); these are written on the panel as `data-lane` and `data-provenance`. */
-    lane?: Lane;
-    provenance?: Provenance;
-    content: ReactNode;
-}
-interface CaseWorkbenchProps {
-    /** The selected case (written as `data-case`). */
-    caseId: string;
-    /** The case picker, shown first in the rail. Omit only for a workbench with a single case. */
-    cases?: CaseSelectorProps;
-    /** The data source of the case (for example `real` or `synthetic`), written as `data-source`. */
-    source?: string;
-    /** Every control value of the instrument; with the case and variant it forms the state key (S10). */
-    controls?: Record<string, unknown>;
-    /** A workbench whose views have no live control declares it, so the reactivity gate does not expect one. */
-    replayOnly?: boolean;
-    /** The regimes of the case, shown in the rail under the case picker; omit only for a case with no meaningful
-     * parametric or temporal family. */
-    variants?: VariantBarProps;
-    /** The rest of the rail: the case's parameters (Knob, ChipGroup) and its live values (Readout, Gauge, Verdict),
-     * as one node or as sections shown one at a time (ADR-0071 rule 6). */
-    rail?: ReactNode | RailSection[];
-    railLabel?: BiText;
-    /** The instrument: the case's own question groups (for example Model, Validation, Impact, Findings). */
-    groups: WorkbenchGroup[];
-    /** The comparison across the case's variants (one metric per regime; selecting one loads it). */
-    compare?: {
-        label?: BiText;
-        lane?: Lane;
-        provenance?: Provenance;
-        content: ReactNode;
-    };
-    /** The deep write-up of the case: problem, variables, equations, assumptions, what each variant shows, how to read
-     * the views (ADR-0016 s9.B). Always present. */
-    context: {
-        label?: BiText;
-        content: ReactNode;
-    };
-    /** Controlled group selection (for example held in the URL). */
-    group?: string;
-    onGroupChange?: (id: string) => void;
-    ariaLabel?: BiText;
-}
-declare const MAX_WORKBENCH_GROUPS = 6;
-/**
- * The App route of a product (ADR-0016 s9, ADR-0071 as amended 2026-10-04): the control rail beside the instrument on
- * the full viewport. The rail holds, in order, the case picker, the variants of the case, and the product's
- * parameters and live values; the instrument holds ONE row of at most six question groups in a fixed order (the
- * instrument groups, the variant comparison, the context write-up) and the open group's views, which take the
- * height that row leaves. Pickers, parameters and numbers sit in the rail so the drawing keeps the instrument
- * (rule 8: at least half the viewport is drawn).
- *
- * It provides the selection's state key to every `PlotCard` and `Readout` in the rail and the instrument, so a view
- * still showing data for an earlier selection says so, and it writes `data-case`, `data-variant`, `data-source` and
- * `data-state-key` on the instrument so the gate can check that the instrument shows what was asked for.
- */
-declare function CaseWorkbench(props: CaseWorkbenchProps): react.JSX.Element;
-
 type Tone = 'good' | 'warn' | 'bad' | 'accent' | 'neutral';
 interface ReadoutItem {
     label: BiText;
@@ -627,6 +572,198 @@ interface PlotCardProps {
  * protected by an error boundary, so one failing chart never blanks the page (failure class 20). */
 declare function PlotCard({ title, lane, provenance, dataKey, actions, note, fill, children }: PlotCardProps): react.JSX.Element;
 
+interface BarDatum {
+    id: string;
+    label: BiText;
+    /** `null` or `undefined` shows "not available" at the zero line, never a bar of zero. */
+    value: number | null | undefined;
+    /** An explicit colour by meaning; otherwise the accent, or faint beside a highlighted bar. */
+    tone?: Tone;
+    /** The bar the reader is on (the selected variant, the case asked about). */
+    highlight?: boolean;
+    /** One line shown as the bar's title. */
+    hint?: BiText;
+}
+interface BarChartProps {
+    /** The chart's accessible name. */
+    title: BiText;
+    data: BarDatum[];
+    /** The value axis: its title, unit and number format; `range` fixes the domain (it always includes zero). */
+    axis: {
+        label: BiText;
+        unit?: BiText;
+        format?: FormatOptions;
+        range?: [number, number];
+    };
+    /** Horizontal bars (the default) give every category label its own line, so long labels never collide;
+     * vertical bars suit a few short categories. */
+    orientation?: 'horizontal' | 'vertical';
+    /** Write each value at its bar (default true). */
+    values?: boolean;
+    /** A vertical chart's height in pixels (default 240), or `fill` to take its container's height (inside a filling
+     * PlotCard). A horizontal chart takes the height its rows need, or fills and spaces its rows when `fill`. */
+    height?: number | 'fill';
+    /** Called with a bar's id when it is clicked or chosen with the keyboard. */
+    onSelect?: (id: string) => void;
+}
+/**
+ * The house categorical chart (CAOS_MANAGE audit 2026-10-07: every product hand-drew its bar charts with fixed margins,
+ * the product template included). Margins are measured from the labels in the page's font; a category label is broken
+ * over two lines at a word and only then shortened, with the whole label as its title; ticks are round and share one
+ * notation; values are written in the interface language. It renders once its box has a width and declares
+ * `data-chart`, which the gate's text check (G10) measures.
+ */
+declare function BarChart({ title, data, axis, orientation, values, height, onSelect }: BarChartProps): react.JSX.Element;
+
+/**
+ * Text that fits the drawing it labels, measured in the font the page renders.
+ *
+ * Products drew their axes and labels with fixed margins and a fixed width per character. The Linux fonts (DejaVu
+ * Sans) are wider than the Windows ones and Spanish labels are longer than English ones, so a column sized for one
+ * ran its labels out of the drawing in the other (CAOS_Fragmenta 0.05.000: "Tamaño medio clásico, limitado al bloque
+ * in situ" read "dio clásico, limitado al bloque in situ"; its deploy gate failed on Linux). Here a label is measured
+ * with the canvas text metrics of the page's own font (`--font-sans`, which the gate's wide-font pass replaces),
+ * broken over two lines at a word when it does not fit, and only then shortened with an ellipsis, so the drawing can
+ * give the whole label as its title. Ported from CAOS_Fragmenta `viz/text.ts` (0.07.000).
+ */
+/** The page's sans-serif stack as the shell token resolves it. */
+declare function fontFamily(): string;
+/** The width of one line of text at a font size, in CSS pixels; outside a browser, an estimate on the wide side. */
+declare function textWidth(text: string, px: number, weight?: number): number;
+/** The widest a set of labels needs, each on one line. */
+declare function widestLabel(labels: readonly string[], px: number, weight?: number): number;
+interface FittedLabel {
+    /** One or two lines; the last is shortened with an ellipsis only when the lines allowed are not enough. */
+    lines: string[];
+    /** Whether the label was shortened, so the drawing gives the whole label as its title. */
+    shortened: boolean;
+}
+/** A label in at most `maxLines` lines of `width` pixels: whole when it fits, broken at a word, shortened last. */
+declare function fitLabel(label: string, width: number, px: number, maxLines?: 1 | 2): FittedLabel;
+/** The 1, 2, 2.5 or 5 times a power of ten at or above `x`. */
+declare function niceStep(x: number): number;
+/**
+ * Round ticks covering [lo, hi], as many as leave room for labels about `labelSize` pixels along an axis of `room`
+ * pixels (at least two, at most `most`). The first tick is at or below `lo` and the last at or above `hi`, so a bar
+ * or a point never runs past the last labelled value.
+ */
+declare function niceTicks(lo: number, hi: number, room: number, labelSize: number, most?: number): number[];
+
+/** One section of the control rail. A rail whose content does not fit is SPLIT into sections, one shown at a
+ * time, never scrolled (ADR-0071 rule 6: a panel must show its own controls). */
+interface RailSection {
+    id: string;
+    label: BiText;
+    content: ReactNode;
+}
+interface WorkbenchLayoutProps {
+    /** The control rail: case and variant pickers, parameters, the live readout. Either one node or sections. */
+    rail: ReactNode | RailSection[];
+    /** Shown above the rail (and above its sections): the case and variant pickers, which every section shares. */
+    railHead?: ReactNode;
+    /** The instrument: the views of the selected case. It takes the rest of the viewport (ADR-0071 rules 2, 8). */
+    children: ReactNode;
+    /** Accessible name of the rail. */
+    railLabel?: BiText;
+    className?: string;
+}
+/**
+ * The App route of a CAOS product: a sized control rail beside the instrument, on the full viewport.
+ *
+ * Renders `.page-body.wide.caos-wb`: no reading-width cap (a workbench is not prose, ADR-0071 rule 2),
+ * `min-width: 0` down the tree so no row pushes the page wider than the screen (rule 3), a rail with an
+ * explicit width that never scrolls (rule 6), and an instrument marked `data-instrument` so the measured gate
+ * can check that it covers at least half of the viewport (rule 8). Pair with `ShellConfig.contain`.
+ */
+declare function WorkbenchLayout({ rail, railHead, children, railLabel, className }: WorkbenchLayoutProps): react.JSX.Element;
+
+/** One configured regime of a case: a full parameter vector, never a cosmetic label (ADR-0016 §9). */
+interface VariantDef {
+    id: string;
+    label: BiText;
+    /** One line: what this regime shows. */
+    note?: BiText;
+    /** The lane of this variant's result, when it differs from the bar's. */
+    lane?: Lane;
+    disabled?: boolean;
+}
+interface VariantBarProps {
+    variants: VariantDef[];
+    activeId: string;
+    onSelect: (id: string) => void;
+    title?: BiText;
+    lane?: Lane;
+}
+/** The regimes of the selected case on ONE scrollable row (ADR-0071 rule 4), the active regime's lane, and the
+ * one-line note of what it shows. Selecting a regime must change every view of the case. */
+declare function VariantBar({ variants, activeId, onSelect, title, lane }: VariantBarProps): react.JSX.Element;
+
+/** One group of views of the selected case, named for the question the user is asking (ADR-0071 rule 5). */
+interface WorkbenchGroup {
+    id: string;
+    label: BiText;
+    /** Which lane produced this group's views, and what data they rest on. Each view shows its own badges (PlotCard,
+     * Readout); these are written on the panel as `data-lane` and `data-provenance`. */
+    lane?: Lane;
+    provenance?: Provenance;
+    content: ReactNode;
+}
+interface CaseWorkbenchProps {
+    /** The selected case (written as `data-case`). */
+    caseId: string;
+    /** The case picker, shown first in the rail. Omit only for a workbench with a single case. */
+    cases?: CaseSelectorProps;
+    /** The data source of the case (for example `real` or `synthetic`), written as `data-source`. */
+    source?: string;
+    /** Every control value of the instrument; with the case and variant it forms the state key (S10). */
+    controls?: Record<string, unknown>;
+    /** A workbench whose views have no live control declares it, so the reactivity gate does not expect one. */
+    replayOnly?: boolean;
+    /** The regimes of the case, shown in the rail under the case picker; omit only for a case with no meaningful
+     * parametric or temporal family. */
+    variants?: VariantBarProps;
+    /** The rest of the rail: the case's parameters (Knob, ChipGroup) and its live values (Readout, Gauge, Verdict),
+     * as one node or as sections shown one at a time (ADR-0071 rule 6). */
+    rail?: ReactNode | RailSection[];
+    railLabel?: BiText;
+    /** The instrument: the case's own question groups (for example Model, Validation, Impact, Findings). */
+    groups: WorkbenchGroup[];
+    /** The comparison across the case's variants (one metric per regime; selecting one loads it). */
+    compare?: {
+        label?: BiText;
+        lane?: Lane;
+        provenance?: Provenance;
+        content: ReactNode;
+    };
+    /** The deep write-up of the case: problem, variables, equations, assumptions, what each variant shows, how to read
+     * the views (ADR-0016 s9.B). Always present. */
+    context: {
+        label?: BiText;
+        content: ReactNode;
+    };
+    /** Controlled group selection, when the product holds it itself. */
+    group?: string;
+    onGroupChange?: (id: string) => void;
+    /** The query parameter that holds the open group, so a view can be shared and reloaded (default `view`); `false`
+     * keeps it out of the URL. Ignored when `group` is controlled. */
+    deepLinkView?: boolean | string;
+    ariaLabel?: BiText;
+}
+declare const MAX_WORKBENCH_GROUPS = 6;
+/**
+ * The App route of a product (ADR-0016 s9, ADR-0071 as amended 2026-10-04): the control rail beside the instrument on
+ * the full viewport. The rail holds, in order, the case picker, the variants of the case, and the product's
+ * parameters and live values; the instrument holds ONE row of at most six question groups in a fixed order (the
+ * instrument groups, the variant comparison, the context write-up) and the open group's views, which take the
+ * height that row leaves. Pickers, parameters and numbers sit in the rail so the drawing keeps the instrument
+ * (rule 8: at least half the viewport is drawn).
+ *
+ * It provides the selection's state key to every `PlotCard` and `Readout` in the rail and the instrument, so a view
+ * still showing data for an earlier selection says so, and it writes `data-case`, `data-variant`, `data-source` and
+ * `data-state-key` on the instrument so the gate can check that the instrument shows what was asked for.
+ */
+declare function CaseWorkbench(props: CaseWorkbenchProps): react.JSX.Element;
+
 interface KnobProps {
     /** Stable id, written as `data-control` so the gate can enumerate and move every control. */
     id: string;
@@ -686,4 +823,4 @@ declare function Stage({ label, children, className }: {
     className?: string;
 }): react.JSX.Element;
 
-export { BiText, Callout, type CaseDef, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, CaseWorkbench, type CaseWorkbenchProps, ChipGroup, type ChipGroupProps, type ChipOption, type Citation, CitationsProvider, Cite, DocPage, DocSection, type DocSectionProps, Equation, Figure, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, InlineMath, Knob, type KnobProps, type Lane, LaneBadge, Lang, LanguageToggle, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Stage, type StageSize, type SubTabDef, SubTabs, type SubTabsProps, type TabDef, type TabGroupDef, TabGroups, type TabGroupsProps, Tabs, type TabsProps, type Theme, ThemeToggle, type Tone, type UsePausedVizOptions, VariantBar, type VariantBarProps, type VariantDef, Verdict, type VerdictProps, type VizFrame, type VizLoop, type VizLoopDeps, type VizLoopOptions, type WorkbenchGroup, WorkbenchLayout, type WorkbenchLayoutProps, type WorkbenchRoute, WorkbenchShell, type WorkbenchShellProps, type WorkbenchState, WorkbenchStateContext, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, groupByCategory, isStale, makeStateKey, readCaseParam, readTheme, sourcesPresent, usePausedViz, useStageSize, useThemeStore, useWorkbenchState, withCaseParam };
+export { BREAKPOINTS, BarChart, type BarChartProps, type BarDatum, BiText, Callout, type CaseDef, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, CaseWorkbench, type CaseWorkbenchProps, ChipGroup, type ChipGroupProps, type ChipOption, type Citation, CitationsProvider, Cite, DocPage, DocSection, type DocSectionProps, Equation, Figure, type FittedLabel, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, InlineMath, Knob, type KnobProps, type Lane, LaneBadge, Lang, LanguageToggle, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Stage, type StageSize, type SubTabDef, SubTabs, type SubTabsProps, SurfacePage, type SurfacePageProps, type TabDef, type TabGroupDef, TabGroups, type TabGroupsProps, Tabs, type TabsProps, type Theme, ThemeToggle, type Tone, type UsePausedVizOptions, VariantBar, type VariantBarProps, type VariantDef, Verdict, type VerdictProps, type VizFrame, type VizLoop, type VizLoopDeps, type VizLoopOptions, type WorkbenchGroup, WorkbenchLayout, type WorkbenchLayoutProps, type WorkbenchRoute, WorkbenchShell, type WorkbenchShellProps, type WorkbenchState, WorkbenchStateContext, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, fitLabel, fontFamily, groupByCategory, isStale, makeStateKey, niceStep, niceTicks, readCaseParam, readTheme, replaceQueryParam, sourcesPresent, textWidth, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, viewParamOf, widestLabel, withCaseParam };