@fasl-work/caos-app-shell 0.15.0 → 0.17.0

package/dist/index.d.ts

@@ -53,7 +53,8 @@ declare function WorkbenchShell({ brand, routes, navigationLabel, children, side
 
 interface FocusShellProps {
     stage: ReactNode;
-    rail: ReactNode;
+    /** The parameter column on the right. Null or omitted: no column, and the stage is the whole frame (a view of a surface with no rail). */
+    rail?: ReactNode;
     title: string;
     description: string;
     hud: Array<{
@@ -259,8 +260,9 @@ interface CaseSelectorProps {
      * category structure is preserved either way; only the height changes.
      */
     layout?: 'chips' | 'select';
-    /** A control that sits on the select's row, after it (the workbench's Focus button, shell 0.14.1): the select shrinks to make
-     * room, so the selector is no taller with it. With `layout: 'chips'` it gets a row of its own, after the chips. */
+    /** A control of the product that sits on the select's row, after it: the select shrinks to make room, so the selector is no taller with
+     * it (a long case name may then be cut: keep the control narrow). The workbench's own Focus control is not an accessory since 0.17.0:
+     * it sits in the group tab row. With `layout: 'chips'` it gets a row of its own, after the chips. */
     accessory?: ReactNode;
 }
 /**
@@ -275,10 +277,84 @@ interface CaseSelectorProps {
  */
 declare function CaseSelector(props: CaseSelectorProps): 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 enterViewLabel: {
+        readonly en: "Open this view in focus mode";
+        readonly es: "Abrir esta vista 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;
+}
+/** What a product may say about the Focus mode of a `SurfacePage` App (`SurfacePage.focus`; `true` means all defaults). */
+interface SurfaceFocusConfig {
+    /** 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;
+}
+/**
+ * What a product may say about one view of a `SurfacePage` that has a stage (`TabDef.focus`; `true` means all defaults). Only a
+ * view with a stage (a simulation, a drawing, a live run) sets it: a list or a form does not, and shows no Focus control.
+ */
+interface ViewFocusConfig {
+    /** The stage's heading (default: the view's label). */
+    title?: BiText;
+    /** One line under it (default: the surface's title). */
+    description?: BiText;
+    /** Readouts laid over the stage (ADR-0070): at most four on a phone. */
+    hud?: Array<{
+        label: BiText;
+        value: string;
+    }>;
+    /**
+     * The parameter column on the right of the stage in Focus (ADR-0070 requirement 2): the view's own controls, moved here by the
+     * product (the shell moves no DOM). Without a rail the stage is the whole frame and the view keeps its controls in its body.
+     */
+    rail?: ReactNode;
+}
+
 interface TabDef {
     id: string;
     label: ReactNode;
     content: ReactNode;
+    /**
+     * A view with a stage (a simulation, a drawing, a live run) of a `SurfacePage` that has `focus`: it opens in Focus mode (shell
+     * 0.16.0, ADR-0070). `true` takes the defaults. A list or a form sets nothing. Ignored outside a `SurfacePage`.
+     */
+    focus?: boolean | ViewFocusConfig;
 }
 /** At most about six peers, then group by the question (ADR-0071 rule 5). */
 declare const MAX_PEER_TABS = 6;
@@ -291,13 +367,19 @@ interface TabsProps {
     /** Called on every selection, controlled or not. */
     onChange?: (id: string) => void;
     ariaLabel?: string;
+    /**
+     * A control at the end of the tab row, in a slot beside the tab list (never inside it) on the same row: its space is reserved
+     * whatever it shows, so the row does not move. The tabs scroll beside it when they do not fit. Used by `SurfacePage` for its Focus
+     * control (shell 0.16.0). Omit it and the markup is what it was.
+     */
+    trailing?: ReactNode;
 }
 /**
  * Accessible roving-tabindex tab strip on ONE row (ADR-0071 rule 4): arrow keys, Home and End; only the active panel
  * is rendered, inside an error boundary; a row wider than its box fades the hidden end. Controlled when `value` is
  * given (known shell defect 6). More than six peers is reported (rule 5).
  */
-declare function Tabs({ tabs, initial, value, onChange, ariaLabel }: TabsProps): react.JSX.Element;
+declare function Tabs({ tabs, initial, value, onChange, ariaLabel, trailing }: TabsProps): react.JSX.Element;
 
 interface SubTabDef {
     id: string;
@@ -812,7 +894,7 @@ interface SurfacePageProps {
     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. */
+    /** The surface's views: one row of at most six (ADR-0071 rule 5); the open one is held in the URL. A view with a stage sets `focus`. */
     tabs?: TabDef[];
     /** Controlled selection, when the product holds it itself. */
     value?: string;
@@ -822,17 +904,28 @@ interface SurfacePageProps {
     ariaLabel?: BiText;
     /** Mark the body as the instrument, so the gate measures what is drawn in it (ADR-0071 rule 8). */
     instrument?: boolean;
+    /**
+     * Focus mode for the App (ADR-0070, shell 0.16.0): while the open view sets `TabDef.focus`, a Focus control at the end of the tab row
+     * opens that view in the full viewport through `FocusShell` (the view is the stage, its `rail` the parameter column), holds
+     * `?focus=1` beside `?view=` in the URL, and returns with Escape or the exit button to the same view and sub-view. `true` takes all
+     * the defaults. Omit it and the surface is exactly what it was. Needs `tabs`: a surface with one body has no view to focus.
+     */
+    focus?: boolean | SurfaceFocusConfig;
     /** The body when there are no tabs: it fills the viewport. */
     children?: ReactNode;
 }
 /**
  * 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
+ * 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.
+ *
+ * Its views that have a stage (a simulation, a drawing, a live run) open in Focus mode (0.16.0, ADR-0070): the same behaviour as
+ * `CaseWorkbench`'s, one piece of code (`useFocusMode`). The control sits at the end of the tab row (a slot beside the tab list) with
+ * its space reserved, so it adds no row and moves nothing; it is hidden while the open view has no stage.
  */
-declare function SurfacePage({ title, lede, actions, tabs, value, onChange, deepLinkView, ariaLabel, instrument, children }: SurfacePageProps): react.JSX.Element;
+declare function SurfacePage({ title, lede, actions, tabs, value, onChange, deepLinkView, ariaLabel, instrument, focus, 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). */
@@ -1108,44 +1201,6 @@ 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;
@@ -1197,7 +1252,7 @@ interface CaseWorkbenchProps {
     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
+     * Focus mode for the App (ADR-0070, shell 0.14.0): a Focus control at the end of the group tab row 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.
@@ -1219,6 +1274,40 @@ declare const MAX_WORKBENCH_GROUPS = 6;
  */
 declare function CaseWorkbench(props: CaseWorkbenchProps): react.JSX.Element;
 
+/** What the hook needs of a product's Focus configuration: `CaseFocusConfig` and `SurfaceFocusConfig` both satisfy it. */
+interface FocusModeConfig {
+    /** The query parameter (default `focus`). */
+    param?: string;
+    /** Called when Focus opens (`true`) and closes (`false`), for a product that records it. */
+    onChange?: (on: boolean) => void;
+}
+interface FocusModeOptions {
+    /**
+     * False while what Focus would open is not available (a surface whose open view has no stage): Focus is then never shown, and a
+     * `?focus=1` left in the URL is removed. Default true.
+     */
+    enabled?: boolean;
+    /** Whether a `?focus=1` in the URL at the first render may open Focus (a surface checks the view the link names). Default true. */
+    initialAllowed?: () => boolean;
+}
+interface FocusMode {
+    /** True when the frame shows: configured, on, and enabled. */
+    show: boolean;
+    /** Opens or closes Focus: writes the URL, moves keyboard focus on the next commit and calls `onChange`. */
+    setFocus: (on: boolean) => void;
+    /** Attach to the control that opens Focus: keyboard focus returns to it when Focus closes. */
+    enterRef: React.MutableRefObject<HTMLButtonElement | null>;
+    /** What the reader had open in the tab rows of the views; provide it as `ViewMemoryContext` around both frames. */
+    memory: Map<string, string>;
+}
+/**
+ * Focus mode (ADR-0070), the one behaviour `CaseWorkbench` and `SurfacePage` share: the state held in the URL (`?focus=1`), Escape
+ * to leave, the page behind the frame inert, keyboard focus moved to the exit control on entry and back to the entering control on
+ * return, and the view memory the frame's remount reads. The component renders the frame (`FocusShell`) when `show` is true.
+ * `cfg` null means the App has no Focus mode: nothing here acts.
+ */
+declare function useFocusMode(cfg: FocusModeConfig | null, options?: FocusModeOptions): FocusMode;
+
 interface KnobProps {
     /** Stable id, written as `data-control` so the gate can enumerate and move every control. */
     id: string;
@@ -1291,4 +1380,4 @@ interface ViewsRowProps {
  */
 declare function ViewsRow({ children, shares }: ViewsRowProps): react.JSX.Element;
 
-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 };
+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, type FocusMode, type FocusModeConfig, type FocusModeOptions, 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, type SurfaceFocusConfig, 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 ViewFocusConfig, 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, useFocusMode, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, validateExecutive, viewParamOf, widestLabel, withCaseParam };