@cratis/scene.blueprint.default 0.1.0

package/.storybook/main.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { StorybookConfig } from "@storybook/react-vite";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import type { InlineConfig } from 'vite';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const config: StorybookConfig = {
+    // Scoped away from `dist/` so a story is never indexed twice - once as source and once as the
+    // tsc-emitted copy beside it.
+    stories: ["../*.stories.@(js|jsx|mjs|ts|tsx)", "../!(dist|node_modules)/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+    addons: [getAbsolutePath("@storybook/addon-links")],
+    framework: { name: getAbsolutePath("@storybook/react-vite"), options: {} },
+    async viteFinal(config: InlineConfig) {
+        config.resolve = config.resolve || {};
+        config.resolve.alias = {
+            ...config.resolve.alias,
+            '@cratis/scene.engine': resolve(__dirname, '../../engine/index.ts'),
+            '@cratis/scene.model': resolve(__dirname, '../../model/index.ts'),
+            '@cratis/scene.react': resolve(__dirname, '../../react/index.ts'),
+        };
+        return config;
+    },
+};
+export default config;
+
+function getAbsolutePath(value: string): string {
+    return dirname(fileURLToPath(import.meta.resolve(join(value, "package.json"))));
+}

package/.storybook/preview.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Preview } from '@storybook/react';
+
+// PrimeReact 10 ships its base styles and one theme per file, and the shell's own stylesheet layers on
+// top of them. Loading them here rather than from a story keeps every story looking the same and matches
+// what a host does once, at its entry point.
+import 'primereact/resources/primereact.min.css';
+import 'primereact/resources/themes/lara-light-indigo/theme.css';
+import 'primeicons/primeicons.css';
+import '../shell/layout.css';
+
+const preview: Preview = {
+    parameters: {
+        controls: { matchers: { color: /(background|color)$/i, date: /Date$/i } },
+    },
+};
+
+export default preview;

package/ComponentName.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The bare names this package declares components under.
+ *
+ * A page template writes a bare name and `resolveComponentName` decides which active package wins it, so
+ * these names are public API: renaming one breaks every template that referenced it, in this package and
+ * in anyone else's. Keeping them in one enum means the manifest, the registry and every template
+ * reference the same symbol, and the specs can prove all three agree rather than hoping they do.
+ */
+export enum ComponentName {
+    /** The application shell - topbar, sidebar, breadcrumb, content, footer and an optional right panel. */
+    AppShell = 'appShell',
+
+    /** The chrome-less shell - content, an optional branding aside, and the configurator. */
+    FullPageShell = 'fullPageShell',
+
+    /** The fixed strip across the top of the application shell. */
+    Topbar = 'topbar',
+
+    /** The sidebar's own chrome, inside the shell-positioned panel. */
+    Sidebar = 'sidebar',
+
+    /** A navigation list. */
+    Menu = 'menu',
+
+    /** One entry in a navigation list, optionally with a submenu. */
+    MenuItem = 'menuItem',
+
+    /** The trail above the content. */
+    Breadcrumb = 'breadcrumb',
+
+    /** The strip below the content. */
+    Footer = 'footer',
+
+    /** The inspector panel down the right-hand edge. */
+    RightPanel = 'rightPanel',
+
+    /** The floating configurator: color scheme, layout mode, menu theme and theme. */
+    ConfigPanel = 'configPanel',
+
+    /** A screen's title, subtitle and actions. */
+    PageHeader = 'pageHeader',
+
+    /** The scrim behind a floating sidebar, which also closes it. */
+    Mask = 'mask',
+
+    /** The brand mark. */
+    Logo = 'logo',
+
+    /** The signed-in user's avatar and menu. */
+    UserMenu = 'userMenu',
+
+    /** Switches between the themes a host offers. */
+    ThemeSwitcher = 'themeSwitcher',
+
+    /** Switches between the layout modes. */
+    LayoutModeSwitcher = 'layoutModeSwitcher',
+}

package/README.md

@@ -0,0 +1,204 @@
+# @cratis/scene.blueprint.default
+
+The default **blueprint** for Scene: the application shells an application picks once, the screen and
+dialog templates that go inside them, the components that fill their slots, and two themes.
+
+User-facing documentation lives in [`Documentation/blueprints/`](../../../Documentation/blueprints/index.md).
+This file is the contributor's note: the conventions the source follows and the reasoning behind them.
+
+## Layout
+
+```text
+blueprint.default/
+├── defaultBlueprint.ts             the ScenePackage manifest + the ScenePackageBundle
+├── defaultBlueprintComponents.ts   the ComponentRegistry - every bare name to its shell component
+├── ComponentName.ts                the bare names this blueprint declares
+├── packageName.ts                  the name a ui profile lists it under
+├── configuration/                  the layout-mode state machine, its React provider and persistence
+├── layouts/                        the two Layout definitions and the flow builders behind them
+├── shell/                          the sixteen shell components, and layout.css
+├── gallery/                        the screen and dialog templates, the screens, and preview helpers
+├── themes/                         the two themes and the provider that applies them
+└── for_*/                          BDD specs beside the code they specify
+```
+
+## The four things this ships, and why they are four
+
+| Concept | What it is | How many |
+| --- | --- | --- |
+| **Layout** | the application's base navigational look | one per application, chosen from two |
+| **Screen template** | a reusable shape *inside* a layout, at module / feature / slice level | twenty-three |
+| **Dialog template** | the same, for overlays - no `fitsSlot`, because a dialog occupies no parent slot | three |
+| **Screen** | an instance: names its layout and template, and provides the content | twenty-three |
+
+A screen template states where it belongs, in `fitsSlot`, rather than being told by whatever hosts it.
+That one rule composes at every depth: a module's template fits the layout's `content`, a feature's fits a
+slot the module declares, a slice's fits one the feature declares. `nestScreenTemplates` folds a chain from
+the inside out, and `ModuleWorkspace` → `FeatureSection` → `SliceSection` exists to be asserted rather than
+only described.
+
+## Regions (slots)
+
+`topbar`, `sidebar`, `menu`, `breadcrumb`, `content`, `footer`, `rightPanel`, `configPanel`, `aside`.
+
+Sakai establishes topbar/sidebar/menu/content/footer; the premium PrimeTek templates add the breadcrumb
+and the right panel; `aside` is the branding half of a full-page screen's split. All of them are here,
+because a blueprint covering only the free template's regions forces a fork on anyone wanting the others.
+
+`SlotName` is one enum used by the layouts, the templates and the shell components, because a slot filled
+under a name the shell never reads renders nothing and reports nothing.
+
+## Layout modes
+
+Eight, plus a mobile regime nobody selects. The class vocabulary is PrimeTek's, unchanged.
+
+| Mode | Wrapper class | What it does |
+| --- | --- | --- |
+| Static | `layout-static` | Sidebar docked at 18rem; content pushed by a matching margin, never covered |
+| Overlay | `layout-overlay` | Sidebar parked off-canvas; opening floats it over the content behind a mask |
+| Slim | `layout-slim` | 5rem icon-only rail, circular buttons; submenus pop out at the rail's width |
+| Slim+ | `layout-slim-plus` | 7rem rail with each label stacked under its icon |
+| Compact | `layout-compact` | The 5rem rail with square buttons; the topbar shifts by the rail width too |
+| Horizontal | `layout-horizontal` | Sidebar goes `position: static` into the topbar as a nowrap row; submenus drop down |
+| Reveal | `layout-reveal` | Full panel translated off-left behind a 4.25rem icon strip; hover slides it in over the content; a pin pushes the content out instead |
+| Drawer | `layout-drawer` | A 5.25rem rail that *animates its width* to full on hover - reveal slides, drawer grows - and pins the same way |
+
+State classes: `layout-static-inactive`, `layout-overlay-active`, `layout-sidebar-active`,
+`layout-sidebar-anchored`, `layout-mobile`, `layout-mobile-active`. Menu tint:
+`layout-menu-light|dark|primary`. Color scheme: `layout-color-scheme-light|dark`.
+
+**Mobile is not a mode.** At or below 991px `effectiveLayoutMode` returns `overlay` regardless of what was
+chosen, the mode picker disables itself and says why, and the choice is kept so it comes back when the
+window grows. The breakpoint is exported as `mobileBreakpoint` so the resize listener and the media query
+cannot disagree.
+
+## Where the state lives
+
+One `LayoutConfigState`, one `LayoutConfigProvider`, one `useLayoutConfig`. Every transition is a pure
+function over the record (`layoutConfigTransitions.ts`), so the whole state machine is testable without
+React, and exactly one function turns state into CSS (`layoutWrapperClasses`).
+
+Preferences persist to `localStorage` under `cratis.scene.blueprint.default`: mode, menu theme, color
+scheme, theme name and the pin. Deliberately *not* whether the sidebar happened to be open, whether the
+pointer was over it, or whether the viewport was narrow - restoring those produces a shell that opens in a
+state nobody chose. Everything read back is validated against the enums, because storage outlives the
+version of the package that wrote it and an unknown mode puts a class on the wrapper that no rule matches.
+
+## Token vocabulary
+
+Thirteen tokens, matching `@cratis/scene.primereact`'s table exactly. A vocabulary that grows per package
+is one no package can rely on.
+
+`primary.color`, `primary.contrastColor`, `surface.background`, `surface.card`, `surface.border`,
+`surface.hover`, `surface.overlay`, `text.color`, `text.mutedColor`, `highlight.background`,
+`highlight.color`, `content.borderRadius`, `focus.ring`.
+
+`layout.css` aliases the `--scene-*` custom properties into `--layout-*` locals once, at the top, and no
+rule below references a `--scene-*` name - the same bridge pattern `@cratis/components` uses for its
+`--cratis-*` layer. Overriding the look means overriding tokens, never editing a rule.
+
+The stylesheet is a plain `.css` file rather than an import from TypeScript, because this repo's rollup
+config has no CSS plugin and adding one is not this package's call. A host imports
+`@cratis/scene.blueprint.default/styles` once; Storybook does it in `.storybook/preview.ts`.
+
+## Theme attribution
+
+| Theme | Author | Link | License |
+| --- | --- | --- | --- |
+| Scene Default Light | Cratis | <https://cratis.io> | MIT |
+| Scene Default Dark | Cratis | <https://cratis.io> | MIT |
+
+Both palettes are original to Cratis - a neutral grey ramp with an indigo accent - not adopted from any
+existing preset, which is why `author` says so rather than being left blank. A theme with empty
+attribution reads as "nobody has checked", and once a palette is lifted without its credit nobody can tell
+afterwards which of the two it was. Anything adopted later must fill `author`, `authorUrl` and `license`
+from the source package's own LICENSE file, verified rather than assumed.
+
+Both themes declare `compatibleWith: ['core', 'Cratis.Blueprint.Default', 'PrimeReact',
+'Cratis.Components', 'Tailwind']`. `core` is on the list on purpose: `incompatiblePackages` has no implicit
+exemption for it, so a theme omitting it is reported incompatible for `core` with every profile that lists
+it - which is every profile.
+
+## Component names borrowed from elsewhere
+
+A screen template names components by their **bare** name, so `resolveComponentName` picks the package and
+the template stays portable. `gallery/dependencyComponentNames.ts` lists every name the gallery borrows;
+each was checked against the owning package's own manifest (`primeReactPackage.ts`,
+`cratisComponentsPackage.ts`) rather than assumed, and a spec resolves all of them.
+
+Two names a dashboard obviously wants - `chart` and `fileUpload` - are declared by *neither* package, so
+the templates use what does exist (a table of monthly figures; an image beside a "Change photo" button)
+rather than referencing something that would render as a red placeholder.
+
+`menu`, `breadcrumb` and `sidebar` are declared by both PrimeReact and this blueprint. That is override
+priority working as designed: this blueprint sits last in the profile's ascending-priority list, so its
+shell versions win the bare names while PrimeReact's stay reachable as `PrimeReact.menu`.
+
+## Previewing
+
+`GalleryScreenPreview` boots one gallery screen through the real path - real `Screen`, real
+`resolveComponentName`, real `SceneElementView`, real registry. Nothing in it is a preview-only code path.
+
+It resolves against `galleryPreviewProfile` rather than `galleryProfile`. Same four packages, different
+order: this package takes no npm dependency on PrimeReact's or Cratis Components' *bundles* (a blueprint
+declares its dependencies in its manifest, not in its bundler graph), so a preview run from here has only
+`core` and this blueprint implemented. Ranking `core` above the two libraries means `text`, `button` and
+`card` resolve to something that exists. Names only the libraries declare still resolve to them, find no
+implementation, and render as `UnresolvedComponent`'s dashed box - which is the honest outcome, not a
+papered-over one. A host with all four bundles uses `galleryProfile` and sees the real widgets.
+
+## PrimeReact 11
+
+This shell is deliberately hand-rolled CSS **today**, because PrimeReact 10 has no app-shell primitive:
+its `Sidebar` is an overlay drawer (v11 renames it `Drawer` for exactly that reason), and the docked, rail,
+reveal and drawer behaviors have nowhere to come from but a stylesheet.
+
+PrimeReact 11 introduces a first-class `Sidebar` for the app-shell role, with `variant`, `collapsible`,
+`side`, `overlay` and `openOnHover` props and a `Sidebar.Layout` registry. A v11 port would collapse:
+
+- the docked/off-canvas rules (`layout-static*`, `layout-overlay*`) into `variant` + `overlay`;
+- the reveal and drawer hover machinery, and most of `isSidebarRevealed`, into `openOnHover`;
+- the rail widths (`slim`, `slim-plus`, `compact`) into `collapsible` plus a width token;
+- the wrapper-class plumbing in `layoutWrapperClasses` into `Sidebar.Layout`.
+
+What would **not** collapse, and would stay this package's own: the mobile forcing at 991px, the
+persistence, the menu-theme axis, and `horizontal` (a sidebar that stops being a sidebar is not a sidebar
+variant). Studio pins `primereact` to `10.9.8` and `@cratis/components` hard-depends on it, so the port is
+blocked on that pin, not on this package.
+
+## Deliberately not built
+
+- **No router.** `menuItem` and `breadcrumb` render hash routes (`#/Dashboard`) against a screen name. A
+  host with a real router wraps the shell and rewrites them; hashes keep the gallery navigable with no
+  router at all, which is what a preview needs.
+- **No widget adapters.** Every widget a template places comes from PrimeReact or Cratis Components. A
+  blueprint that shipped its own table would be a component library wearing a blueprint's manifest.
+- **No layout-arrangement renderer.** The layouts' `FlowArrangement`s are evaluated by the real
+  `evaluateFlowArrangement` in specs, but the shell positions its regions with CSS. Rendering an
+  arrangement generically is Scene#4's job, layered on top rather than folded in here.
+- **No `FreeformSlotArrangement`.** Both layouts reflow; neither has a fixed-position variant worth
+  expressing as absolute placements.
+
+## Known gaps outside this package
+
+- **`yarn install` has not been run since the folder was renamed** from `layout.default`, so Yarn's
+  workspace state still names the old path and `yarn build` / `yarn test` fail with
+  `Package for @cratis/scene.blueprint.default@workspace:... not found in the project`. Run `yarn install`
+  once; until then the gates run through `npx tsc -b`, `npx rollup -c ./rollup.config.mjs`, `npx vitest run`,
+  `npx eslint --cache --quiet .` and `npx storybook build`, which are what the `g:*` scripts invoke.
+- `Source/JavaScript/blueprint.default` is not in the root `tsconfig.json` `references` (which now lists
+  `tailwind`, `primereact` and `components`), so a root `npx tsc -b` does not build it.
+- `FlowRow`, `FlowColumn` and a `FlowGrid` with no `columns` are structurally identical in `Scene.Model`,
+  so a consumer cannot tell a row from a column by value. The builders in `layouts/flowBuilders.ts` keep
+  the *intent* legible at the declaration site, and `grid()` always sets `columns`, but the model gap is
+  real.
+
+## Gates
+
+```bash
+npx tsc -b            # from the repository root
+yarn build            # from this package
+yarn test
+yarn lint:ci
+yarn build-storybook
+```

package/configuration/ColorScheme.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The light/dark axis of the configurator.
+ *
+ * The shell never paints a color for a scheme itself - it only records which one is chosen, so the host
+ * can hand {@link SceneThemeProvider} a matching {@link Theme}. Keeping the choice and the palette apart
+ * is what lets a third-party theme participate in the same switch as the two this package ships.
+ */
+export enum ColorScheme {
+    Light = 'light',
+    Dark = 'dark',
+}
+
+/** Every {@link ColorScheme}, in the order a configurator should offer them. */
+export const colorSchemes: ColorScheme[] = [ColorScheme.Light, ColorScheme.Dark];

package/configuration/LayoutConfigProvider.tsx

@@ -0,0 +1,182 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { ColorScheme } from './ColorScheme';
+import { LayoutConfigState } from './LayoutConfigState';
+import { LayoutMode } from './LayoutMode';
+import { MenuTheme } from './MenuTheme';
+import { persistLayoutConfig, readPersistedLayoutConfig } from './layoutConfigStorage';
+import { isLayoutMaskVisible, layoutWrapperClasses } from './layoutWrapperClasses';
+import {
+    effectiveLayoutMode,
+    isMobileWidth,
+    mobileMediaQuery,
+    toggleSidebar,
+    toggleSidebarAnchor,
+    withColorScheme,
+    withMenuTheme,
+    withMobile,
+    withMode,
+    withSidebarOpen,
+    withSidebarRevealed,
+    withThemeName,
+} from './layoutConfigTransitions';
+
+/**
+ * What {@link useLayoutConfig} hands a shell component: the current state, the values every part of the
+ * shell derives from it, and one function per transition.
+ *
+ * The derived values live here rather than being recomputed per component so that the topbar, the
+ * sidebar and the mask cannot end up disagreeing about which mode is in force - the exact class of bug a
+ * shell with per-component state produces.
+ */
+export interface LayoutConfigContextValue {
+    /** The current state. */
+    config: LayoutConfigState;
+
+    /** The mode actually in force, with the mobile override applied. */
+    effectiveMode: LayoutMode;
+
+    /** The classes for the shell's wrapper element. */
+    wrapperClasses: string[];
+
+    /** Whether the scrim behind a floating sidebar should be showing. */
+    isMaskVisible: boolean;
+
+    /** Chooses a different mode. Below the mobile breakpoint the choice is still recorded, but the shell keeps rendering off-canvas. */
+    setMode(mode: LayoutMode): void;
+
+    /** Chooses how the sidebar surface is tinted. */
+    setMenuTheme(menuTheme: MenuTheme): void;
+
+    /** Chooses the light/dark axis. */
+    setColorScheme(colorScheme: ColorScheme): void;
+
+    /** Records which theme is applied. */
+    setThemeName(themeName: string): void;
+
+    /** Opens or closes the sidebar. */
+    setSidebarOpen(isOpen: boolean): void;
+
+    /** Flips the sidebar between open and closed. */
+    toggleSidebar(): void;
+
+    /** Holds a `reveal`/`drawer` sidebar out, or lets it fall back. */
+    setSidebarRevealed(isRevealed: boolean): void;
+
+    /** Pins or unpins a `reveal`/`drawer` sidebar. */
+    toggleSidebarAnchor(): void;
+}
+
+const LayoutConfigContext = createContext<LayoutConfigContextValue | undefined>(undefined);
+
+export interface LayoutConfigProviderProps {
+    /** Values to start from, overriding both the defaults and anything persisted - a story or a spec pinning a mode. */
+    initialConfig?: Partial<LayoutConfigState>;
+
+    /**
+     * Where preferences are read from and written to. Defaults to `window.localStorage` when there is a
+     * window; pass a fake in a spec, or `null` to opt out of persistence entirely.
+     */
+    storage?: Storage | null;
+
+    /**
+     * The width the shell should consider its viewport, for a host that renders it into a sized element
+     * rather than the window - Studio's preview surface, where the device frame is a few hundred pixels
+     * wide while the real window is a desktop one. When given, this replaces the `matchMedia` listener
+     * entirely rather than competing with it.
+     */
+    viewportWidth?: number;
+
+    /** The shell this configuration applies to. */
+    children?: ReactNode;
+}
+
+/**
+ * Owns the shell's configuration and keeps it in step with the viewport and with `localStorage`.
+ *
+ * One provider rather than state per shell component is what makes the modes work at all: the topbar's
+ * toggle, the sidebar's pin, the mask's click-to-close and the configurator's mode picker are four
+ * different components acting on one machine. It is also what makes a chosen mode survive a reload, which
+ * is the whole reason a mode picker is worth having.
+ */
+export function LayoutConfigProvider({ initialConfig, storage, viewportWidth, children }: LayoutConfigProviderProps) {
+    const resolvedStorage = useMemo(() => (storage !== undefined ? storage ?? undefined : defaultStorage()), [storage]);
+    const [config, setConfig] = useState<LayoutConfigState>(() => ({
+        ...readPersistedLayoutConfig(resolvedStorage),
+        ...initialConfig,
+    }));
+
+    useEffect(() => {
+        persistLayoutConfig(config, resolvedStorage);
+    }, [config, resolvedStorage]);
+
+    const isReportedMobile = viewportWidth === undefined ? undefined : isMobileWidth(viewportWidth);
+    useEffect(() => {
+        if (isReportedMobile !== undefined) {
+            setConfig(current => withMobile(current, isReportedMobile));
+            return;
+        }
+
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+            return;
+        }
+
+        const query = window.matchMedia(mobileMediaQuery);
+        setConfig(current => withMobile(current, query.matches));
+
+        const listener = (event: MediaQueryListEvent) => setConfig(current => withMobile(current, event.matches));
+        query.addEventListener('change', listener);
+        return () => query.removeEventListener('change', listener);
+    }, [isReportedMobile]);
+
+    const value = useMemo<LayoutConfigContextValue>(
+        () => ({
+            config,
+            effectiveMode: effectiveLayoutMode(config),
+            wrapperClasses: layoutWrapperClasses(config),
+            isMaskVisible: isLayoutMaskVisible(config),
+            setMode: mode => setConfig(current => withMode(current, mode)),
+            setMenuTheme: menuTheme => setConfig(current => withMenuTheme(current, menuTheme)),
+            setColorScheme: colorScheme => setConfig(current => withColorScheme(current, colorScheme)),
+            setThemeName: themeName => setConfig(current => withThemeName(current, themeName)),
+            setSidebarOpen: isOpen => setConfig(current => withSidebarOpen(current, isOpen)),
+            toggleSidebar: () => setConfig(toggleSidebar),
+            setSidebarRevealed: isRevealed => setConfig(current => withSidebarRevealed(current, isRevealed)),
+            toggleSidebarAnchor: () => setConfig(toggleSidebarAnchor),
+        }),
+        [config],
+    );
+
+    return <LayoutConfigContext.Provider value={value}>{children}</LayoutConfigContext.Provider>;
+}
+
+/**
+ * The shell configuration, or `undefined` when there is no {@link LayoutConfigProvider} above.
+ *
+ * This is what lets the shell components put a provider around themselves when a host has not - a gallery
+ * preview drops a single `appShell` element into a renderer with no wrapper of its own, and it still has
+ * to work.
+ */
+export function useOptionalLayoutConfig(): LayoutConfigContextValue | undefined {
+    return useContext(LayoutConfigContext);
+}
+
+/**
+ * The shell configuration. Throws when there is no {@link LayoutConfigProvider} above, because every
+ * alternative - a silent default, a no-op setter - produces a shell whose buttons do nothing and says
+ * nothing about why.
+ */
+export function useLayoutConfig(): LayoutConfigContextValue {
+    const value = useOptionalLayoutConfig();
+    if (!value) {
+        throw new Error('useLayoutConfig() requires a <LayoutConfigProvider> above it.');
+    }
+
+    return value;
+}
+
+function defaultStorage(): Storage | undefined {
+    return typeof window !== 'undefined' ? window.localStorage : undefined;
+}

package/configuration/LayoutConfigState.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ColorScheme } from './ColorScheme';
+import { LayoutMode } from './LayoutMode';
+import { MenuTheme } from './MenuTheme';
+
+/**
+ * Everything the shell needs to know about itself, in one place.
+ *
+ * The shell has a lot of visual state - eight modes, a sidebar that can be open, hovered or pinned, a
+ * mobile breakpoint that overrides the chosen mode, two color axes - and every one of those was, in the
+ * template line this follows, a separate boolean scattered across components. Holding it as one plain
+ * value instead means the whole state machine is pure functions over this record
+ * (`layoutConfigTransitions.ts`), testable without React, and rendered by exactly one function
+ * ({@link layoutWrapperClasses}).
+ */
+export interface LayoutConfigState {
+    /** The mode the user chose. Below the mobile breakpoint the shell renders a different one - see {@link effectiveLayoutMode}. */
+    mode: LayoutMode;
+
+    /** How the sidebar surface is tinted. */
+    menuTheme: MenuTheme;
+
+    /** The light/dark axis. The host maps this onto a {@link Theme}; the shell only records it. */
+    colorScheme: ColorScheme;
+
+    /** The name of the {@link Theme} currently applied, so a theme switcher has something to reflect. */
+    themeName: string;
+
+    /**
+     * Whether the sidebar currently occupies space (`static`) or floats over the content
+     * (`overlay`, mobile). One flag rather than the separate desktop/mobile/overlay booleans the
+     * template line uses - the mode already says how "open" should look.
+     */
+    isSidebarOpen: boolean;
+
+    /** Whether a `reveal`/`drawer` sidebar is pinned open, so it stays out when the pointer leaves. */
+    isSidebarAnchored: boolean;
+
+    /** Whether a `reveal`/`drawer` sidebar is currently held out by the pointer. */
+    isSidebarRevealed: boolean;
+
+    /** Whether the viewport is below the mobile breakpoint. Never set by a user action - only by the viewport. */
+    isMobile: boolean;
+}

package/configuration/LayoutMode.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * How the application shell arranges its sidebar against its content.
+ *
+ * The vocabulary - and the `layout-<mode>` wrapper class each value maps to - is deliberately the one
+ * PrimeTek's template line has used unchanged across Sakai, Diamond, Atlantis, Freya, Apollo, Ultima,
+ * Avalon and Verona. Anyone who has themed a PrimeReact application recognizes it, and a shell that
+ * invents its own names forces them to learn a second one for no gain.
+ *
+ * Every value here is user-selectable. Mobile deliberately is not - see {@link effectiveLayoutMode}.
+ */
+export enum LayoutMode {
+    /** Sidebar permanently docked; content is pushed by a matching margin, never covered. */
+    Static = 'static',
+
+    /** Sidebar parked off-canvas; opening floats it over the content behind a mask. */
+    Overlay = 'overlay',
+
+    /** Icon-only rail with circular buttons; submenus pop out as a floating panel. */
+    Slim = 'slim',
+
+    /** Wider rail with each icon's label stacked directly beneath it. */
+    SlimPlus = 'slim-plus',
+
+    /** The icon-only rail again, with square buttons, and the topbar shifted by the rail width. */
+    Compact = 'compact',
+
+    /** Sidebar flows into the topbar strip as a horizontal row; submenus drop down. */
+    Horizontal = 'horizontal',
+
+    /** Full panel translated off-left leaving a strip of icons; hovering slides it in over the content. */
+    Reveal = 'reveal',
+
+    /** Collapsed rail that animates its width to full on hover - it grows where reveal slides. */
+    Drawer = 'drawer',
+}
+
+/** Every {@link LayoutMode}, in the order a configurator should offer them. */
+export const layoutModes: LayoutMode[] = [
+    LayoutMode.Static,
+    LayoutMode.Overlay,
+    LayoutMode.Slim,
+    LayoutMode.SlimPlus,
+    LayoutMode.Compact,
+    LayoutMode.Horizontal,
+    LayoutMode.Reveal,
+    LayoutMode.Drawer,
+];

package/configuration/MenuTheme.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * How the sidebar surface is tinted, independently of the overall {@link ColorScheme}.
+ *
+ * A dark sidebar against a light page is the single most common brand customization in the PrimeTek
+ * template line, which is why menu theme is its own configurator axis rather than something implied by
+ * the color scheme. The shell resolves each value from the active theme's tokens, so a menu theme never
+ * introduces a color of its own.
+ */
+export enum MenuTheme {
+    /** The sidebar uses the theme's ordinary card surface. */
+    Light = 'light',
+
+    /** The sidebar uses an inverted surface, regardless of the page's color scheme. */
+    Dark = 'dark',
+
+    /** The sidebar uses the theme's primary color as its surface. */
+    Primary = 'primary',
+}
+
+/** Every {@link MenuTheme}, in the order a configurator should offer them. */
+export const menuThemes: MenuTheme[] = [MenuTheme.Light, MenuTheme.Dark, MenuTheme.Primary];

package/configuration/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './LayoutMode';
+export * from './ColorScheme';
+export * from './MenuTheme';
+export * from './LayoutConfigState';
+export * from './layoutConfigTransitions';
+export * from './layoutWrapperClasses';
+export * from './layoutConfigStorage';
+export * from './LayoutConfigProvider';