@fasl-work/caos-app-shell 0.3.0 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@ fix lands in one place.
 ```bash
 npm i @fasl-work/caos-app-shell
 # peer deps (the app provides them):
-npm i react react-dom react-router-dom lucide-react katex zustand
+npm i react react-dom react-router-dom lucide-react katex zustand
 ```
 
 ## Use
@@ -60,9 +60,20 @@ const config: ShellConfig = {
 
 ## Exports
 
-`AppShell`, `ThemeToggle`, `LanguageToggle`, `useThemeStore`, `applyTheme`, `readTheme`, `useLangStore`,
+`AppShell`, `WorkbenchShell`, `ThemeToggle`, `LanguageToggle`, `useThemeStore`, `applyTheme`, `readTheme`, `useLangStore`,
 `useShellLang`, `usePausedViz`, `createVizLoop`, `CaseSelector` (+ `caseModel` helpers), `Tabs`, `SubTabs`,
 `Callout`, `Equation`, `InlineMath`, `Figure`, `CitationsProvider`, `Cite`, `Refs`, `ReferenceList`, plus
-the `@fasl-work/caos-app-shell/styles.css` design system.
+the `@fasl-work/caos-app-shell/styles.css` design system.
+
+### Authenticated workbenches
+
+`WorkbenchShell` is the shared frame for products whose authenticated UI needs a desktop sidebar and
+mobile bottom navigation. It renders typed routes and the main landmark while the product supplies its
+own stateful controls through `brand`, `sidebarFooter`, `headerLead`, `headerActions`, and `overlays`.
+Authentication, account policy, preference persistence, chat, and modal content remain product-owned.
+The component uses the stable core `NavLink` contract and supports `react-router` 6, 7, and 8.
+Browser applications on 6/7 install the matching `react-router-dom`, which supplies the core peer;
+Router 8 applications provide `react-router` directly. Do not mix different core and DOM majors in
+one application.
 
 MIT · part of the Faena mining-analytics hub.

package/dist/index.d.ts

@@ -68,6 +68,36 @@ declare function AppShell({ config, children }: {
     children: ReactNode;
 }): react.JSX.Element;
 
+/** One authenticated workbench destination rendered by the shared responsive navigation frame. */
+interface WorkbenchRoute {
+    path: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    end?: boolean;
+    ariaLabel?: string;
+}
+/**
+ * Slots owned by a product around the shared workbench layout.
+ *
+ * The shell deliberately does not own authentication, preferences, account state, chat, or modal
+ * content. Products supply those controls as slots while this package owns the frame, navigation
+ * semantics, responsive layout classes, and main-content landmark.
+ */
+interface WorkbenchShellProps {
+    brand: ReactNode;
+    routes: WorkbenchRoute[];
+    navigationLabel: string;
+    children: ReactNode;
+    sidebarFooter?: ReactNode;
+    headerLead?: ReactNode;
+    headerActions?: ReactNode;
+    overlays?: ReactNode;
+    mainId?: string;
+    className?: string;
+}
+/** Shared CAOS frame for authenticated consoles with desktop sidebar and mobile bottom navigation. */
+declare function WorkbenchShell({ brand, routes, navigationLabel, children, sidebarFooter, headerLead, headerActions, overlays, mainId, className, }: WorkbenchShellProps): react.JSX.Element;
+
 /** Light/dark icon toggle. Shows the icon of the theme you would switch TO. */
 declare function ThemeToggle(): react.JSX.Element;
 
@@ -316,4 +346,4 @@ declare function ReferenceList({ ids, heading }: {
     heading?: string;
 }): react.JSX.Element;
 
-export { AppShell, type ArchTab, type ArchitectureConfig, ArchitectureModal, Callout, type CaseDef, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, type Citation, CitationsProvider, Cite, Equation, Figure, InlineMath, type Lang, LanguageToggle, type PausedVizController, ReferenceList, Refs, type ShellConfig, type ShellRoute, type SubTabDef, SubTabs, type TabDef, Tabs, type Theme, ThemeToggle, type UsePausedVizOptions, type VizFrame, type VizLoop, type VizLoopDeps, type VizLoopOptions, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, groupByCategory, readCaseParam, readTheme, sourcesPresent, useLangStore, usePausedViz, useShellLang, useThemeStore, withCaseParam };
+export { AppShell, type ArchTab, type ArchitectureConfig, ArchitectureModal, Callout, type CaseDef, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, type Citation, CitationsProvider, Cite, Equation, Figure, InlineMath, type Lang, LanguageToggle, type PausedVizController, ReferenceList, Refs, type ShellConfig, type ShellRoute, type SubTabDef, SubTabs, type TabDef, Tabs, type Theme, ThemeToggle, type UsePausedVizOptions, type VizFrame, type VizLoop, type VizLoopDeps, type VizLoopOptions, type WorkbenchRoute, WorkbenchShell, type WorkbenchShellProps, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, groupByCategory, readCaseParam, readTheme, sourcesPresent, useLangStore, usePausedViz, useShellLang, useThemeStore, withCaseParam };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createContext, useState, useRef, useEffect, useCallback, useId, useContext } from 'react';
-import { NavLink } from 'react-router-dom';
+import { NavLink } from 'react-router';
 import { Sun, Moon, Languages, Boxes, Github, Globe, Briefcase, Info } from 'lucide-react';
 import { create } from 'zustand';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
@@ -308,6 +308,55 @@ function AppShell({ config, children }) {
     ] }) }) })
   ] });
 }
+function WorkbenchShell({
+  brand,
+  routes,
+  navigationLabel,
+  children,
+  sidebarFooter,
+  headerLead,
+  headerActions,
+  overlays,
+  mainId = "main-content",
+  className
+}) {
+  const rootClassName = ["caos-workbench-shell", "app-shell", className].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsxs("div", { className: rootClassName, children: [
+    /* @__PURE__ */ jsxs(
+      "aside",
+      {
+        className: "caos-workbench-sidebar sidebar",
+        style: { "--caos-workbench-route-count": routes.length },
+        children: [
+          brand,
+          /* @__PURE__ */ jsx("nav", { "aria-label": navigationLabel, children: routes.map((route) => /* @__PURE__ */ jsxs(
+            NavLink,
+            {
+              to: route.path,
+              end: route.end ?? route.path === "/",
+              "aria-label": route.ariaLabel,
+              className: ({ isActive }) => isActive ? "active" : void 0,
+              children: [
+                route.icon,
+                /* @__PURE__ */ jsx("span", { children: route.label })
+              ]
+            },
+            route.path
+          )) }),
+          sidebarFooter
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsxs("div", { className: "caos-workbench-main shell-main", children: [
+      /* @__PURE__ */ jsxs("header", { className: "caos-workbench-header topbar", children: [
+        headerLead,
+        headerActions
+      ] }),
+      /* @__PURE__ */ jsx("main", { id: mainId, className: "caos-workbench-content content", children })
+    ] }),
+    overlays
+  ] });
+}
 
 // src/lib/vizLoop.ts
 function createVizLoop(frame, options, deps) {
@@ -788,4 +837,4 @@ function ReferenceList({ ids, heading }) {
   ] });
 }
 
-export { AppShell, ArchitectureModal, Callout, CaseSelector, CitationsProvider, Cite, Equation, Figure, InlineMath, LanguageToggle, ReferenceList, Refs, SubTabs, Tabs, ThemeToggle, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, groupByCategory, readCaseParam, readTheme, sourcesPresent, useLangStore, usePausedViz, useShellLang, useThemeStore, withCaseParam };
+export { AppShell, ArchitectureModal, Callout, CaseSelector, CitationsProvider, Cite, Equation, Figure, InlineMath, LanguageToggle, ReferenceList, Refs, SubTabs, Tabs, ThemeToggle, WorkbenchShell, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, groupByCategory, readCaseParam, readTheme, sourcesPresent, useLangStore, usePausedViz, useShellLang, useThemeStore, withCaseParam };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fasl-work/caos-app-shell",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared web-app shell + content primitives + design system for the CAOS / Faena public apps (ADR-0016).",
   "license": "MIT",
   "author": "Felipe Santibáñez-Leal",
@@ -28,7 +28,7 @@
   ],
   "scripts": {
     "build": "tsup",
-    "test": "node --import tsx --test test/vizLoop.test.ts test/caseModel.test.ts",
+    "test": "node --import tsx --test test/vizLoop.test.ts test/caseModel.test.ts test/workbenchShell.test.tsx",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
@@ -36,10 +36,10 @@
     "lucide-react": ">=0.400.0",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19",
-    "react-router-dom": "^6 || ^7",
+    "react-router": "^6 || ^7 || ^8",
     "zustand": "^4 || ^5"
   },
-  "devDependencies": {
+  "devDependencies": {
     "@types/katex": "^0.16.7",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
@@ -47,10 +47,13 @@
     "lucide-react": "^0.469.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "react-router-dom": "^7.1.1",
+    "react-router": "^8.3.0",
     "tsup": "^8.3.5",
     "tsx": "^4.23.0",
     "typescript": "^5.7.3",
-    "zustand": "^5.0.2"
-  }
-}
+    "zustand": "^5.0.2"
+  },
+  "overrides": {
+    "esbuild": "0.28.1"
+  }
+}

package/styles.css

@@ -25,7 +25,8 @@
   --color-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), 0 6px 16px rgba(0, 0, 0, 0.45);
   --font-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
-  --maxw: 1200px;
+  --maxw: 1200px;          /* reading width, for PROSE pages */
+  --maxw-wide: 100%;       /* instrument width, for workbench pages */
 }
 
 [data-theme="light"] {
@@ -69,6 +70,10 @@ code, kbd { font-family: var(--font-mono); }
 .container { width: 100%; max-width: var(--maxw); margin-inline: auto; padding-inline: 1.5rem; }
 .page { flex: 1 1 auto; width: 100%; }
 .page-body { width: 100%; max-width: var(--maxw); margin-inline: auto; padding: 2.25rem 1.5rem 3rem; }
+/* A WORKBENCH is not prose. Capping an instrument at a 1200px reading measure wastes every pixel beyond
+   it, which is why the App surfaces across the line render their visualization as a thumbnail on a wide
+   display. Prose pages keep the reading width; the App route opts into the full viewport. */
+.page-body.wide { max-width: var(--maxw-wide); padding-inline: 1.25rem; }
 .muted { color: var(--color-fg-subtle); }
 .faint { color: var(--color-fg-faint); }
 .mono { font-family: var(--font-mono); font-size: 0.9em; }
@@ -155,7 +160,18 @@ code, kbd { font-family: var(--font-mono); }
 .callout-body p:last-child { margin-bottom: 0; }
 
 /* ── Tabs ── */
-.tablist { display: flex; gap: 0.35rem; padding-bottom: 0.6rem; margin-bottom: 1.5rem; border-bottom: 1px solid var(--color-border); flex-wrap: wrap; }
+.tablist { display: flex; gap: 0.35rem; padding-bottom: 0.6rem; margin-bottom: 1.5rem; border-bottom: 1px solid var(--color-border); flex-wrap: nowrap; }
+/* SINGLE-LINE TAB BAR.
+   `flex-wrap: wrap` lets a 14-to-18 tab bar spill onto a second and third row, and every extra row is
+   vertical space taken from the instrument below it, permanently, on every render. A tab bar is
+   navigation chrome: it gets ONE row and scrolls horizontally when it does not fit.
+   Scrollbar is hidden but the row stays scrollable by wheel, trackpad, drag and keyboard. */
+.tablist { flex-wrap: nowrap !important; overflow-x: auto; overflow-y: hidden;
+  scrollbar-width: none; -ms-overflow-style: none; padding-bottom: 0.4rem; margin-bottom: 0.9rem;
+  scroll-behavior: smooth; }
+.tablist::-webkit-scrollbar { display: none; }
+.tablist .tab, .tablist button { flex: 0 0 auto; white-space: nowrap; }
+
 .tab { padding: 0.5rem 1rem; border: 1px solid transparent; border-radius: 8px; background: transparent; color: var(--color-fg-subtle); font-size: 0.92rem; font-weight: 550; transition: color 0.15s, background-color 0.15s, border-color 0.15s; }
 .tab:hover { color: var(--color-fg); background: var(--color-surface-2); }
 .tab.active { color: var(--color-accent); background: var(--color-accent-soft); border-color: color-mix(in oklab, var(--color-accent) 35%, transparent); font-weight: 650; }
@@ -238,5 +254,50 @@ code, kbd { font-family: var(--font-mono); }
 .cs-kind { font-size: 0.62rem; font-weight: 700; line-height: 1; padding: 0.12rem 0.28rem; border-radius: 4px; border: 1px solid var(--color-border); color: var(--color-fg-faint); background: var(--color-surface-2); align-self: center; }
 .cs-kind-real { color: var(--color-accent-2); border-color: color-mix(in oklab, var(--color-accent-2) 40%, transparent); }
 .cs-kind-uploaded { color: var(--color-warn); border-color: color-mix(in oklab, var(--color-warn) 40%, transparent); }
-.cs-modified { display: flex; align-items: center; gap: 0.5rem; }
-.cs-reset { border: none; background: transparent; color: var(--color-accent); font-size: 0.8rem; font-weight: 600; padding: 0.1rem 0.2rem; text-decoration: underline; text-underline-offset: 2px; }
+.cs-modified { display: flex; align-items: center; gap: 0.5rem; }
+.cs-reset { border: none; background: transparent; color: var(--color-accent); font-size: 0.8rem; font-weight: 600; padding: 0.1rem 0.2rem; text-decoration: underline; text-underline-offset: 2px; }
+
+/* Authenticated workbench frame. Product styles may refine tokens and controls, but the package owns
+   the responsive navigation/layout contract and keeps route/content landmarks consistent. */
+.caos-workbench-shell { min-height: 100vh; display: grid; grid-template-columns: 238px minmax(0, 1fr); }
+.caos-workbench-sidebar { position: fixed; inset: 0 auto 0 0; z-index: 20; width: 238px; display: flex; flex-direction: column; padding: 1.25rem 0.875rem; border-right: 1px solid var(--color-border); background: var(--color-surface); }
+.caos-workbench-sidebar nav { display: grid; gap: 0.25rem; }
+.caos-workbench-sidebar nav a { display: flex; align-items: center; gap: 0.75rem; padding: 0.625rem 0.7rem; border: 1px solid transparent; border-radius: 0.7rem; color: var(--color-fg-subtle); font-size: 0.9rem; font-weight: 650; }
+.caos-workbench-sidebar nav a:hover { color: var(--color-fg); background: var(--color-surface-2); text-decoration: none; }
+.caos-workbench-sidebar nav a.active { color: var(--color-accent); border-color: color-mix(in oklab, var(--color-accent) 24%, transparent); background: var(--color-accent-soft); }
+.caos-workbench-main { grid-column: 2; min-width: 0; }
+.caos-workbench-header { position: sticky; top: 0; z-index: 15; min-height: 64px; display: flex; align-items: center; justify-content: space-between; gap: 1rem; padding: 0 2rem; border-bottom: 1px solid var(--color-border); background: color-mix(in oklab, var(--color-bg) 88%, transparent); backdrop-filter: blur(12px); }
+.caos-workbench-content { width: min(1540px, 100%); margin: 0 auto; padding: 2.25rem 2rem 4rem; }
+
+@media (max-width: 760px) {
+  .caos-workbench-shell { display: block; padding-bottom: 66px; }
+  .caos-workbench-sidebar { inset: auto 0 0; width: auto; height: 62px; display: block; border: 0; border-top: 1px solid var(--color-border); padding: 5px 8px; }
+  .caos-workbench-sidebar > :not(nav) { display: none; }
+  .caos-workbench-sidebar nav { grid-template-columns: repeat(var(--caos-workbench-route-count, 5), minmax(0, 1fr)); }
+  .caos-workbench-sidebar nav a { display: grid; justify-items: center; gap: 2px; overflow: hidden; padding: 5px; font-size: 0.7rem; text-overflow: ellipsis; white-space: nowrap; }
+  .caos-workbench-main { min-width: 0; }
+  .caos-workbench-header { min-height: 58px; padding: 0 1rem; }
+  .caos-workbench-content { padding: 1.5rem 1rem 2.5rem; }
+}
+
+/* CONTAINED LAYOUT. A `nowrap` tab bar sizes its container to its intrinsic width unless every
+   ancestor is allowed to shrink: a flex/grid item defaults to `min-width: auto`. Without this, making
+   the tab bar a single scrollable row pushes the whole page wider than the viewport and the user has to
+   drag sideways to reach the right edge. Measured on ChargeCascade: scrollWidth 1817 on a 1600 viewport. */
+html, body { overflow-x: hidden; }
+.page-body { max-width: 100%; }
+.tabs, .tabpanel { min-width: 0; max-width: 100%; }
+.tablist { min-width: 0; max-width: 100%; width: 100%; }
+
+/* NO MAGIC CHROME NUMBER. An app surface must not compute its height from a hardcoded guess at the
+   header and footer: the guess drifts the moment either changes, leaving either a dead gap above the
+   footer or a few pixels of scroll. Measured on ChargeCascade: guess 150px, real 175px (header 57 +
+   footer 70 + 48px body padding), so 25px of scroll and a 48px gap. Apps that fill the viewport add
+   `.app-shell.fixed` and let flex distribute the height. */
+.app-shell.fixed { height: 100dvh; min-height: 100dvh; overflow: hidden; }
+.app-shell.fixed > .page { flex: 1 1 auto; min-height: 0; display: flex; }
+.app-shell.fixed .page-body.wide { flex: 1 1 auto; min-height: 0; padding-top: 1rem; padding-bottom: 1rem; }
+
+/* A viewport-filling app must not carry the prose footer margin: it becomes dead space between the
+   content and the chrome. Measured on ChargeCascade as exactly 48px (3rem). */
+.app-shell.fixed .site-footer { margin-top: 0; }