@fasl-work/caos-app-shell

The shared web-app shell + content primitives + design system for the CAOS / Faena public apps (implements ADR-0016). 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.

Install

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

Use

// main.tsx
import { applyTheme, readTheme } from "@fasl-work/caos-app-shell";
import "@fasl-work/caos-app-shell/styles.css";
applyTheme(readTheme()); // (an inline script in index.html should also set data-theme pre-paint)

// router / app
import { BrowserRouter, Routes, Route } from "react-router-dom";
import { AppShell, type ShellConfig } from "@fasl-work/caos-app-shell";

const config: ShellConfig = {
  product: { name: "RotorVitals" },
  routes: [
    { path: "/", en: "App", es: "App" },
    { path: "/introduction", en: "Introduction", es: "Introducción" },
    { path: "/methodology", en: "Methodology", es: "Metodología" },
    { path: "/implementation", en: "Implementation", es: "Implementación" },
    { path: "/experiments", en: "Experiments", es: "Experimentos" },
  ],
  links: { github: "https://github.com/fsantibanezleal/CAOS_RotorVitals" }, // personal/portfolio default in
  version: "0.01.000",
};

<BrowserRouter>
  <AppShell config={config}>
    <Routes>{/* /  = the tool (landing); the rest are deep pages */}</Routes>
  </AppShell>
</BrowserRouter>

• Land on the tool: make / your interactive tool; Introduction/Methodology/etc. are separate routes.
• Hub case (Faena): pass routes: [] (or one) → the nav is hidden, header/footer identical.
• Deep pages: compose with Tabs, SubTabs, Equation/InlineMath, Callout, Figure, and CitationsProvider + Cite/Refs/ReferenceList. Read the current language with useShellLang().
• Case + source picking: use CaseSelector for the interactive tool's source/case selection (labelled groups, Synthetic | Real | Uploaded source control, locked-knobs explanation, divergence badge, ?case= deep-linking).
• Animated views: drive every canvas/3D loop through usePausedViz (default paused, run-once, halt on a hidden tab) — never call requestAnimationFrame directly.

Exports

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.

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.