@fasl-work/caos-app-shell 0.13.1 → 0.14.0

package/README.md

@@ -87,6 +87,14 @@ const config: ShellConfig = {
   `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.
+- **Focus mode for the App (0.14.0):** `<CaseWorkbench focus />` adds a Focus button to the rail head that opens the
+  selected case's open group in the full viewport (`FocusShell`: the stage is the view, the rail stays), keeps `?focus=1`
+  beside `?case=` and `?view=`, and returns with Escape or the exit button to the same case, group and sub-view; a product with
+  a simulation must offer it (ADR-0070, `caos-shell-gate --require-focus`). See [docs/04](docs/04_views.md).
+- **Small cards and animation (0.14.0):** `FlipCard` and `CardDeck` for SMALL cards the reader scans by title (a flip card
+  shows its title and turns to its content; a deck is a row up to four cards and a carousel above), used by the executive
+  view for its bearers, roles, approaches and 4 C's; an executive illustration may be an animated SVG with a
+  `prefers-reduced-motion` block ([docs/04](docs/04_views.md), [docs/06](docs/06_executive-view.md)).
 - **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
@@ -130,7 +138,7 @@ const config: ShellConfig = {
 `ChipGroup`, `Stage`, `useStageSize`, `makeStateKey`, `isStale`, `useWorkbenchState`,
 `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`; since 0.9.0 `ViewsRow`. Separate entries:
+`formatTicks`, `NBSP`, `SCIENTIFIC_BELOW`, the type `ShellColorToken`; since 0.9.0 `ViewsRow`. Since 0.14.0 `FlipCard`, `CardDeck` (with `FLIP_LIMITS`, `FLIP_TEXT`, `DECK_TEXT`, `perPageFor`, `deckWindow`, `deckPosition`), the `focus` prop of `CaseWorkbench` (`CaseFocusConfig`, `FOCUS_TEXT`, `FOCUS_PARAM`) and `removeQueryParam`. Separate entries:
 `/chart` (`UPlotChart` with `x.log`, `parity`, `onPick`; `drawMarks`, `tickSteps`, `repeatedLabels`, `seriesStyle`,
 `sortOrder`, `parityRange`), `/keys` (the storage keys, no React), `/styles.css`, `/chart.css`,
 `/reserved-classes.json`. Bin: `caos-shell-gate`.

package/bin/caos-shell-gate.mjs

@@ -15,12 +15,13 @@
 //   --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  --stage-floor 140
 //   --wide-font-sizes 390x844,1280x800   the sizes of the wide-font pass (G10); --no-wide-font skips it
+//   --require-focus              fail an App without a Focus control (G18; ADR-0070 requires one in a product with simulations)
 //   --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', 'no-wide-font']);
+const FLAGS = new Set(['single-case', 'no-wide-font', 'require-focus']);
 const args = {};
 const argv = process.argv.slice(2);
 for (let i = 0; i < argv.length; i += 1) {
@@ -44,6 +45,7 @@ const options = {
   langs: args.langs,
   caseSample: args['case-sample'],
   singleCase: args['single-case'] === true,
+  requireFocus: args['require-focus'] === true,
   idleMs: num('idle-ms'),
   settleMs: num('settle-ms'),
   textFloor: num('text-floor'),

package/dist/index.d.ts

@@ -63,9 +63,14 @@ interface FocusShellProps {
     onExit: () => void;
     exitLabel: string;
     stageLabel: string;
+    /**
+     * True (default): the frame is the page's `main`. False: the frame sits inside a page that already has its `main` (the App's
+     * Focus mode does), so it renders a `div` and the page holds one `main`.
+     */
+    landmark?: boolean;
 }
 /** Full-viewport, scenario-scoped analysis frame. The product supplies only its instrument and controls. */
-declare function FocusShell({ stage, rail, title, description, hud, onExit, exitLabel, stageLabel }: FocusShellProps): react.JSX.Element;
+declare function FocusShell({ stage, rail, title, description, hud, onExit, exitLabel, stageLabel, landmark }: FocusShellProps): react.JSX.Element;
 
 /** Light/dark icon toggle. Shows the icon of the theme you would switch TO. */
 declare function ThemeToggle(): react.JSX.Element;
@@ -665,6 +670,129 @@ interface QuestionProps {
  */
 declare function Question({ question, answer }: QuestionProps): react.JSX.Element;
 
+/**
+ * The limits of a SMALL card (rule of use, CAOS_MANAGE plans/app-shell/0-14-0-plan.md decision 3): a title of about eight
+ * words and a back of about forty. They are counted in the interface language: Spanish runs about a quarter longer than
+ * English for the same text, so its limits are a quarter higher. `gate/areas.mjs` FLIP_LIMITS holds the same values and
+ * `test/flipCard.test.tsx` keeps the two equal.
+ */
+declare const FLIP_LIMITS: {
+    readonly title: {
+        readonly en: 8;
+        readonly es: 10;
+    };
+    readonly back: {
+        readonly en: 40;
+        readonly es: 50;
+    };
+};
+/** The words the card itself writes (the product writes none of them). */
+declare const FLIP_TEXT: {
+    readonly show: {
+        readonly en: "Show details";
+        readonly es: "Mostrar detalles";
+    };
+    readonly hide: {
+        readonly en: "Hide details";
+        readonly es: "Ocultar detalles";
+    };
+};
+interface FlipCardProps {
+    /** The face: a short title (a node, so a card may carry a source mark). */
+    title: ReactNode;
+    /** The title as plain text, repeated on the back beside the return control; omit it and the back shows none. */
+    label?: string;
+    /** The back: the content shown after the card turns. It stays in the markup while the face shows. */
+    children: ReactNode;
+    /** Base of the ids (default: generated). */
+    id?: string;
+    /** Start turned (default: face up). */
+    defaultOpen?: boolean;
+    /** Controlled turn, when the product holds it itself. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    className?: string;
+    /** Forces the language of the card's own words (tests; the card otherwise follows the language toggle). */
+    lang?: Lang;
+}
+/**
+ * A small card whose face shows its title and whose back shows its content after a click or a key press (Enter or Space),
+ * and back again (shell 0.14.0). Use it only for a small card the reader scans by title first and opens when it matters
+ * (a title of about eight words, a back of about forty; the gate fails a card over the limit): a long card or an ordered
+ * sequence stays plain.
+ *
+ * - A real `button` carries `aria-expanded` and `aria-controls`; each face has one, so focus moves to the face that shows
+ *   and never rests on a hidden one. Escape closes an open card.
+ * - The hidden face is out of the accessibility tree and the tab order (`aria-hidden` and `inert` at once, `visibility: hidden`
+ *   after the turn) while its content stays in the markup (search, copy and the gate read it).
+ * - `prefers-reduced-motion: reduce` swaps the faces without the turn; colours are theme tokens only.
+ * - The face states that it turns: a small icon and a visually hidden label in both languages.
+ */
+declare function FlipCard({ title, label, children, id, defaultOpen, open: controlled, onOpenChange, className, lang: forced }: FlipCardProps): react.JSX.Element;
+
+/** The words the deck itself writes (the product writes none of them). */
+declare const DECK_TEXT: {
+    readonly previous: {
+        readonly en: "Previous";
+        readonly es: "Anterior";
+    };
+    readonly next: {
+        readonly en: "Next";
+        readonly es: "Siguiente";
+    };
+    readonly of: {
+        readonly en: "of";
+        readonly es: "de";
+    };
+    readonly to: {
+        readonly en: "to";
+        readonly es: "a";
+    };
+};
+/** How many cards of at least `minCard` px fit a row of `width` px with `gap` px between them: at least one. */
+declare function perPageFor(width: number, minCard: number, gap: number): number;
+/** The window `[start, end)` of `n` cards that `per` at a time show from `start`: never empty, never past the end, pulled back so it is full. */
+declare function deckWindow(n: number, per: number, start: number): {
+    start: number;
+    end: number;
+};
+/** "2 of 5" for one card, "1 to 3 of 5" for several (1-based). */
+declare function deckPosition(start: number, shown: number, n: number, lang: Lang): string;
+interface DeckCard {
+    /** Stable key (default: the index). */
+    id?: string | number;
+    /** The title of the card (a flip card's face). */
+    title: ReactNode;
+    /** The title as plain text, for the back of a flip card. */
+    label?: string;
+    /** The content: a plain card's body, a flip card's back. */
+    body: ReactNode;
+    /** Attributes written on the card's list item (for example `data-exec-item`). */
+    attrs?: Record<string, string | number | undefined>;
+}
+interface CardDeckProps {
+    cards: DeckCard[];
+    /** Render each card as a `FlipCard` (a small card the reader scans by title; see FlipCard for the rule of use). */
+    flip?: boolean;
+    /** A list longer than this is a carousel; up to it, a row (default 4). */
+    carouselAbove?: number;
+    /** The accessible name of the deck. */
+    ariaLabel: string;
+    /** Extra classes of the list that holds the cards. */
+    className?: string;
+    /** Forces the language of the deck's own words (tests). */
+    lang?: Lang;
+}
+/**
+ * A list of cards, plain or as flip cards, shown as a row up to `carouselAbove` cards (default 4) and as a CAROUSEL above
+ * it (shell 0.14.0): one row of as many cards as fit (at least one), previous and next buttons, a swipe on touch, the arrow
+ * keys, Home and End while it has focus, and a position ("2 of 5"). No autoplay. Every card is reachable by keyboard: the
+ * cards the window hides are removed from sight and from the tab order but stay in the markup. The carousel pages through
+ * its cards instead of scrolling a strip, so neither the page nor its panel ever scrolls sideways (ADR-0071). Reduced
+ * motion removes the slide. When every card fits, the controls are not drawn.
+ */
+declare function CardDeck({ cards, flip, carouselAbove, ariaLabel, className, lang: forced }: CardDeckProps): react.JSX.Element;
+
 interface SurfacePageProps {
     /** The route's heading; omit it when the header's active route already names the surface. */
     title?: BiText;
@@ -697,6 +825,8 @@ declare function SurfacePage({ title, lede, actions, tabs, value, onChange, deep
 /** 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;
+/** Removes one query parameter with replaceState (the counterpart of `replaceQueryParam`). */
+declare function removeQueryParam(param: 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
@@ -966,6 +1096,44 @@ interface VariantBarProps {
  * 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;
 
+/** The words Focus mode writes (the product writes none of them). */
+declare const FOCUS_TEXT: {
+    readonly enter: {
+        readonly en: "Focus";
+        readonly es: "Enfocar";
+    };
+    readonly enterLabel: {
+        readonly en: "Open this case in focus mode";
+        readonly es: "Abrir este caso en modo enfoque";
+    };
+    readonly exit: {
+        readonly en: "Back to the App";
+        readonly es: "Volver a la App";
+    };
+    readonly stage: {
+        readonly en: "Focus stage";
+        readonly es: "Escenario de enfoque";
+    };
+};
+/** The query parameter that holds Focus mode (`?focus=1`), beside `?case=` and `?view=`. */
+declare const FOCUS_PARAM = "focus";
+/** What a product may say about the Focus mode of its App (`CaseWorkbench.focus`; `true` means all defaults). */
+interface CaseFocusConfig {
+    /** The stage's heading (default: the name of the selected case). */
+    title?: BiText;
+    /** One line under it (default: the name of the open group). */
+    description?: BiText;
+    /** Readouts laid over the stage (ADR-0070): at most four on a phone. */
+    hud?: Array<{
+        label: BiText;
+        value: string;
+    }>;
+    /** Called when Focus opens (`true`) and closes (`false`), for a product that records it. */
+    onChange?: (on: boolean) => void;
+    /** The query parameter (default `focus`). */
+    param?: string;
+}
+
 /** One group of views of the selected case, named for the question the user is asking (ADR-0071 rule 5). */
 interface WorkbenchGroup {
     id: string;
@@ -1016,6 +1184,13 @@ interface CaseWorkbenchProps {
      * keeps it out of the URL. Ignored when `group` is controlled. */
     deepLinkView?: boolean | string;
     ariaLabel?: BiText;
+    /**
+     * Focus mode for the App (ADR-0070, shell 0.14.0): a Focus button in the rail head opens the selected case's open group in
+     * the full viewport through `FocusShell` (the stage is the view, the rail stays), holds `?focus=1` beside `?case=` and
+     * `?view=` in the URL, and returns with Escape or the exit button to the same case, group and sub-view. `true` takes all
+     * the defaults. Omit it and the App is exactly what it was.
+     */
+    focus?: boolean | CaseFocusConfig;
 }
 declare const MAX_WORKBENCH_GROUPS = 6;
 /**
@@ -1104,4 +1279,4 @@ interface ViewsRowProps {
  */
 declare function ViewsRow({ children, shares }: ViewsRowProps): react.JSX.Element;
 
-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, DOC_AREAS, DocPage, type DocPageProps, DocReferences, DocRefsScope, DocSection, type DocSectionProps, EXECUTIVE_SCHEMA_VERSION, Equation, type ExecutiveData, type ExecutiveProblem, ExecutiveView, type ExecutiveViewProps, FOUR_CS, Figure, type FittedLabel, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, Glossary, type GlossaryEntry, InlineMath, Knob, type KnobProps, Landing, type Lane, LaneBadge, Lang, LanguageToggle, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, Question, type QuestionProps, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Stage, type StageSize, Stat, type StatProps, 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, ViewsRow, type ViewsRowProps, 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, firstAppearance, fitLabel, fontFamily, groupByCategory, isStale, makeStateKey, niceStep, niceTicks, readCaseParam, readTheme, replaceQueryParam, sourcesPresent, textWidth, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, validateExecutive, viewParamOf, widestLabel, withCaseParam };
+export { BREAKPOINTS, BarChart, type BarChartProps, type BarDatum, BiText, Callout, CardDeck, type CardDeckProps, type CaseDef, type CaseFocusConfig, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, CaseWorkbench, type CaseWorkbenchProps, ChipGroup, type ChipGroupProps, type ChipOption, type Citation, CitationsProvider, Cite, DECK_TEXT, DOC_AREAS, type DeckCard, DocPage, type DocPageProps, DocReferences, DocRefsScope, DocSection, type DocSectionProps, EXECUTIVE_SCHEMA_VERSION, Equation, type ExecutiveData, type ExecutiveProblem, ExecutiveView, type ExecutiveViewProps, FLIP_LIMITS, FLIP_TEXT, FOCUS_PARAM, FOCUS_TEXT, FOUR_CS, Figure, type FittedLabel, FlipCard, type FlipCardProps, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, Glossary, type GlossaryEntry, InlineMath, Knob, type KnobProps, Landing, type Lane, LaneBadge, Lang, LanguageToggle, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, Question, type QuestionProps, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Stage, type StageSize, Stat, type StatProps, 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, ViewsRow, type ViewsRowProps, 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, deckPosition, deckWindow, firstAppearance, fitLabel, fontFamily, groupByCategory, isStale, makeStateKey, niceStep, niceTicks, perPageFor, readCaseParam, readTheme, removeQueryParam, replaceQueryParam, sourcesPresent, textWidth, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, validateExecutive, viewParamOf, widestLabel, withCaseParam };