@fasl-work/caos-app-shell 0.6.13 → 0.7.1

package/dist/keys-CnvqkckF.d.ts

@@ -0,0 +1,135 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { B as BiText } from './text-BlY47nIt.js';
+
+interface ArchTab {
+    id: string;
+    /** tab label. */
+    en: string;
+    es: string;
+    /** the explanation body (paragraphs separated by a blank line). */
+    body_en: string;
+    body_es: string;
+    /**
+     * an inline '<svg…>…</svg>' string (import it with `?raw`); a URL is refused, because an `<img>` or a fetched
+     * file cannot read the page's theme tokens and a path goes stale (S11).
+     *
+     * ONE file carries BOTH languages (ADR-0058). Tag each translatable `<text>` twice at the same
+     * coordinates, `class="… l-en"` and `class="… l-es"`; the modal wrapper sets `data-arch-lang`
+     * and the shell stylesheet shows exactly one. Two files would be two things to keep in step, and
+     * the one that is not on screen is the one that goes stale. Anything language-neutral (a number,
+     * a file name, an identifier) needs no pair.
+     */
+    svg: string;
+}
+interface ArchitectureConfig {
+    /** modal title override (defaults to "Architecture / How it works"). */
+    title_en?: string;
+    title_es?: string;
+    tabs: ArchTab[];
+}
+/**
+ * Problems with an architecture configuration, one string each (ADR-0058, ADR-0078). The diagram must be an INLINE
+ * SVG string (a fetched or `<img>` file cannot be checked against the theme tokens before it is shown, failure class
+ * 14); every `var(--x)` it names must be a shell token (an undefined token renders as nothing, silently, failure
+ * class 25); a hex colour does not follow the theme; both languages are required; at least five tabs.
+ */
+declare function validateArchitectureConfig(config: ArchitectureConfig): string[];
+declare function ArchitectureModal({ config, onClose }: {
+    config: ArchitectureConfig;
+    onClose: () => void;
+}): react.JSX.Element | null;
+
+interface ShellRoute {
+    path: string;
+    en: string;
+    es: string;
+}
+interface ShellConfig {
+    /** Brand: product name + optional lucide icon element (defaults to a generic mark). */
+    product: {
+        name: string;
+        mark?: ReactNode;
+    };
+    /** Top-level routes for the header nav (use `STANDARD_ROUTES`). 0 or 1 entries hide the nav (a hub). */
+    routes?: ShellRoute[];
+    /** External links. personal/portfolio default to Felipe's canonical URLs (kept identical app-to-app). */
+    links: {
+        github: string;
+        personal?: string;
+        portfolio?: string;
+    };
+    /** Display version `X.XX.XXX`, read from the repo's VERSION (ADR-0068); a semver form is reported. */
+    version: string;
+    /** Short commit SHA of the build, printed after the version so the deployed build is identifiable. */
+    build?: string;
+    /** The product's licence as the footer shows it. Required: the shell's own licence is not inherited, and a
+     * default "MIT · open source" once appeared on private products (failure class 16). */
+    license: BiText;
+    /** Repository visibility. A private product shows no source link in the header or the footer. */
+    visibility: 'public' | 'private';
+    /** In-app Architecture / "How it works" modal (ADR-0058). When present, an info button appears in the header. */
+    architecture?: ArchitectureConfig;
+    /** Footer provenance + honesty (ADR-0016 s2): the real data/engine source with citation + licence, and the
+     * one-line honest disclaimer of how the app runs. */
+    footer?: {
+        /** Explicit product attribution, or false when the product excludes personal attribution. */
+        attribution?: {
+            en: string;
+            es: string;
+        } | false;
+        /** @deprecated use `ShellConfig.license`. */
+        license?: {
+            en: string;
+            es: string;
+        };
+        provenance?: {
+            en: string;
+            es: string;
+        };
+        disclaimer?: {
+            en: string;
+            es: string;
+        };
+    };
+    /** Routes whose surface IS the viewport (ADR-0071 rule 1), matched exactly or by prefix for a non-root path. */
+    fixedRoutes?: string[];
+    /** Every route fixed: a single-surface app (a hub, a one-page tool). */
+    fixed?: boolean;
+    /**
+     * Every route is the viewport (ADR-0071 rule 1, as amended 2026-10-04): the workbench (`WorkbenchLayout`) fills
+     * it, and a documentation route scrolls INSIDE the main container, so the header and footer stay in view and the
+     * document itself never scrolls. The configuration the product template uses.
+     */
+    contain?: boolean;
+}
+/** The shared CAOS/Faena app shell: sticky header (brand + nav + icon-links + lang/theme) + footer.
+ * Wrap your <Routes> (or single landing) in it, inside a Router. */
+declare function AppShell({ config, children }: {
+    config: ShellConfig;
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * The six routes every CAOS product carries, in this order (ADR-0016 s3, ADR-0069 s7, the product quality bar):
+ * the App (the tool, landing) and the five documentation routes. One definition, so the header, the router and the
+ * gate read the same list and no product retypes it.
+ */
+declare const STANDARD_ROUTES: ShellRoute[];
+
+/**
+ * The storage keys the shell reads and writes. Exported (and built as their own entry, `dist/keys.js`) so the
+ * measured gate sets the theme and the language exactly the way the shell reads them, instead of guessing the
+ * key names (failure class 10 of the 2026-10-04 history: gates that measured the wrong mode).
+ */
+declare const THEME_STORAGE_KEY = "caos.theme";
+declare const LANG_STORAGE_KEY = "caos.lang";
+/**
+ * The pre-paint script for index.html (inline, before the bundle): applies the stored or preferred theme and the
+ * stored language before the first frame, so a light-theme user never sees a dark flash and the document language
+ * is right from the start (ADR-0011, ADR-0012). Built from the keys above, so the two cannot drift; exported from
+ * this React-free entry so a build config can inline it.
+ */
+declare const THEME_BOOT_SCRIPT: string;
+
+export { AppShell as A, LANG_STORAGE_KEY as L, STANDARD_ROUTES as S, THEME_BOOT_SCRIPT as T, type ArchTab as a, type ArchitectureConfig as b, ArchitectureModal as c, type ShellConfig as d, type ShellRoute as e, THEME_STORAGE_KEY as f, validateArchitectureConfig as v };

package/dist/keys.d.ts

@@ -0,0 +1,4 @@
+export { L as LANG_STORAGE_KEY, S as STANDARD_ROUTES, T as THEME_BOOT_SCRIPT, f as THEME_STORAGE_KEY } from './keys-CnvqkckF.js';
+import 'react';
+import './text-BlY47nIt.js';
+import 'zustand';

package/dist/keys.js

@@ -0,0 +1 @@
+export { LANG_STORAGE_KEY, STANDARD_ROUTES, THEME_BOOT_SCRIPT, THEME_STORAGE_KEY } from './chunk-X6Y5CDUD.js';

package/dist/text-BlY47nIt.d.ts

@@ -0,0 +1,21 @@
+import * as zustand from 'zustand';
+
+type Lang = 'en' | 'es';
+interface LangState {
+    lang: Lang;
+    setLang: (l: Lang) => void;
+    toggle: () => void;
+}
+declare const useLangStore: zustand.UseBoundStore<zustand.StoreApi<LangState>>;
+/** Current language, for app pages that render language-branched long-form content. */
+declare const useShellLang: () => Lang;
+
+/** A string shown to users: one language-neutral string (a number, a code, a name) or both languages. */
+type BiText = string | {
+    en: string;
+    es: string;
+};
+/** The text for the current language. English is the canonical fallback (ADR-0011). */
+declare function pick(text: BiText | undefined, lang: Lang): string;
+
+export { type BiText as B, type Lang as L, useShellLang as a, pick as p, useLangStore as u };

package/dist/tokens-CSV0MOgR.d.ts

@@ -0,0 +1,41 @@
+import { L as Lang } from './text-BlY47nIt.js';
+
+interface FormatOptions {
+    /** Significant digits for a value below 10^(digits-1) (default 4); a larger value shows every integer digit, so a
+     * count is never rounded (27345 people, not 27,350). A magnitude below 1e-4 is written in scientific notation with
+     * these significant digits (6.53E-13). Ignored when `decimals` is set. */
+    digits?: number;
+    /** Fixed number of decimals. The caller's explicit choice: a value below the last decimal reads as zero. */
+    decimals?: number;
+    /** Render a fraction as a percentage (0.123 -> 12.3 %). */
+    percent?: boolean;
+}
+/** "Not available" in the interface language: what an absent or non-finite value renders as. */
+declare const NOT_AVAILABLE: Record<Lang, string>;
+/**
+ * A number in the interface language: a decimal point in English and a decimal comma in Spanish
+ * (`conventions/languages.md`), significant digits by default, scientific notation below 1e-4. `null`, `undefined` and non-finite values render as
+ * "not available", never as `NaN` (failure classes 5 and 23 of the 2026-10-04 history).
+ */
+declare function formatNumber(value: number | null | undefined, lang: Lang, opts?: FormatOptions): string;
+/** `formatNumber` bound to the current shell language. */
+declare function useFormat(): (value: number | null | undefined, opts?: FormatOptions) => string;
+
+/**
+ * The colour and font tokens `styles.css` defines for both themes. The architecture-modal validation and the
+ * template's web-baseline guard check every `var(--x)` a product names against this list; a token that is not
+ * defined renders as nothing, silently (failure class 25 of the 2026-10-04 history). A unit test keeps this list
+ * equal to the stylesheet.
+ */
+declare const SHELL_TOKENS: readonly ["--color-bg", "--color-surface", "--color-surface-2", "--color-border", "--color-fg", "--color-fg-subtle", "--color-fg-faint", "--color-accent", "--color-accent-fg", "--color-accent-soft", "--color-accent-2", "--color-magenta", "--color-good", "--color-warn", "--color-bad", "--color-shadow", "--font-sans", "--font-mono", "--maxw", "--maxw-wide"];
+type ShellToken = (typeof SHELL_TOKENS)[number];
+/** The computed value of a token on the document, or `fallback` outside a browser. */
+declare function resolveToken(token: string, fallback?: string): string;
+/**
+ * The colour tokens resolved to concrete values for the active theme, recomputed when the theme changes. Canvas
+ * and WebGL renderers cannot read CSS variables, so they take these (failure classes 7 and 18: charts drawn in
+ * dark-theme colours on a light page).
+ */
+declare function useThemeTokens(): Record<ShellToken, string>;
+
+export { type FormatOptions as F, NOT_AVAILABLE as N, type ShellToken as S, SHELL_TOKENS as a, useThemeTokens as b, formatNumber as f, resolveToken as r, useFormat as u };