@cratis/scene.blueprint.default 0.1.0

package/configuration/layoutConfigStorage.ts

@@ -0,0 +1,102 @@
+// 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 { LayoutConfigState } from './LayoutConfigState';
+import { LayoutMode } from './LayoutMode';
+import { MenuTheme } from './MenuTheme';
+import { defaultLayoutConfigState } from './layoutConfigTransitions';
+
+/** The `localStorage` key the shell persists its configuration under. */
+export const layoutConfigStorageKey = 'cratis.scene.blueprint.default';
+
+/**
+ * The parts of {@link LayoutConfigState} worth surviving a reload.
+ *
+ * Deliberately not the whole record: whether the sidebar happened to be open, whether the pointer was
+ * over it, and whether the viewport was narrow are all facts about the moment rather than preferences, and
+ * restoring them produces a shell that opens in a state the user never chose. The pin *is* a preference,
+ * so it stays.
+ */
+export type PersistedLayoutConfig = Pick<LayoutConfigState, 'mode' | 'menuTheme' | 'colorScheme' | 'themeName' | 'isSidebarAnchored'>;
+
+/**
+ * Reads the persisted configuration back, falling back to {@link defaultLayoutConfigState} for anything
+ * missing or unrecognized.
+ *
+ * Everything is validated against the enums rather than trusted, because `localStorage` is shared with
+ * every other script on the origin and outlives the version of this package that wrote it. An unknown
+ * mode left in place would put a class on the wrapper that no stylesheet rule matches - a shell with no
+ * sidebar at all, and no error to explain it.
+ *
+ * @param storage The storage to read from, or `undefined` when there is none (server-side rendering).
+ * @returns The restored state, with defaults filled in.
+ */
+export function readPersistedLayoutConfig(storage?: Storage): LayoutConfigState {
+    const defaults = defaultLayoutConfigState();
+    const stored = readRecord(storage);
+    if (!stored) {
+        return defaults;
+    }
+
+    return {
+        ...defaults,
+        mode: enumValue(Object.values(LayoutMode), stored.mode) ?? defaults.mode,
+        menuTheme: enumValue(Object.values(MenuTheme), stored.menuTheme) ?? defaults.menuTheme,
+        colorScheme: enumValue(Object.values(ColorScheme), stored.colorScheme) ?? defaults.colorScheme,
+        themeName: typeof stored.themeName === 'string' ? stored.themeName : defaults.themeName,
+        isSidebarAnchored: typeof stored.isSidebarAnchored === 'boolean' ? stored.isSidebarAnchored : defaults.isSidebarAnchored,
+    };
+}
+
+/**
+ * Writes the durable parts of the configuration.
+ *
+ * Storage can throw - Safari's private mode and a full quota both do - and a shell that cannot remember a
+ * preference is a far smaller problem than one that crashes on a mode switch, so a failure here is
+ * swallowed rather than propagated.
+ *
+ * @param state The state to persist.
+ * @param storage The storage to write to, or `undefined` when there is none.
+ */
+export function persistLayoutConfig(state: LayoutConfigState, storage?: Storage): void {
+    if (!storage) {
+        return;
+    }
+
+    const persisted: PersistedLayoutConfig = {
+        mode: state.mode,
+        menuTheme: state.menuTheme,
+        colorScheme: state.colorScheme,
+        themeName: state.themeName,
+        isSidebarAnchored: state.isSidebarAnchored,
+    };
+
+    try {
+        storage.setItem(layoutConfigStorageKey, JSON.stringify(persisted));
+    } catch {
+        // A browser that refuses to store a preference still has to render the shell.
+    }
+}
+
+function readRecord(storage?: Storage): Record<string, unknown> | undefined {
+    if (!storage) {
+        return undefined;
+    }
+
+    try {
+        const raw = storage.getItem(layoutConfigStorageKey);
+        if (!raw) {
+            return undefined;
+        }
+
+        const parsed = JSON.parse(raw) as unknown;
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+function enumValue<TValue extends string>(values: TValue[], candidate: unknown): TValue | undefined {
+    return typeof candidate === 'string' && values.includes(candidate as TValue) ? (candidate as TValue) : undefined;
+}

package/configuration/layoutConfigTransitions.ts

@@ -0,0 +1,150 @@
+// 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 { LayoutConfigState } from './LayoutConfigState';
+import { LayoutMode } from './LayoutMode';
+import { MenuTheme } from './MenuTheme';
+
+/**
+ * The viewport width, in CSS pixels, below which the shell stops honoring the chosen {@link LayoutMode}
+ * and forces the off-canvas one. 991 is the breakpoint the PrimeTek template line uses throughout; the
+ * value is exported rather than buried in a media query so the resize listener and the stylesheet cannot
+ * disagree about where the boundary is.
+ */
+export const mobileBreakpoint = 991;
+
+/** The media query the shell watches to know whether it is in the mobile regime. */
+export const mobileMediaQuery = `(max-width: ${mobileBreakpoint}px)`;
+
+/**
+ * Whether a viewport width falls in the mobile regime. Inclusive of the breakpoint itself, so this and
+ * {@link mobileMediaQuery}'s `max-width` agree on the boundary rather than disagreeing by one pixel.
+ */
+export function isMobileWidth(width: number): boolean {
+    return width <= mobileBreakpoint;
+}
+
+/**
+ * The state a shell starts in when nothing has been persisted: the docked sidebar every application
+ * template defaults to, on a light scheme, with the theme this package ships as its light one.
+ */
+export function defaultLayoutConfigState(): LayoutConfigState {
+    return {
+        mode: LayoutMode.Static,
+        menuTheme: MenuTheme.Light,
+        colorScheme: ColorScheme.Light,
+        themeName: 'Scene Default Light',
+        isSidebarOpen: true,
+        isSidebarAnchored: false,
+        isSidebarRevealed: false,
+        isMobile: false,
+    };
+}
+
+/**
+ * The mode the shell actually renders, as opposed to the one the user picked.
+ *
+ * Below the mobile breakpoint every mode collapses to {@link LayoutMode.Overlay}: a docked 18rem sidebar,
+ * an icon rail or a horizontal menu strip are all unusable on a phone, so the template line forces
+ * off-canvas there and hides the mode picker. Deriving it rather than overwriting `mode` is what lets the
+ * chosen mode come back untouched when the viewport grows again.
+ */
+export function effectiveLayoutMode(state: LayoutConfigState): LayoutMode {
+    return state.isMobile ? LayoutMode.Overlay : state.mode;
+}
+
+/** Whether the mode keeps the sidebar off-canvas until something opens it. */
+export function isOffCanvasMode(mode: LayoutMode): boolean {
+    return mode === LayoutMode.Overlay;
+}
+
+/** Whether the mode is one of the two that react to the pointer - `reveal` slides in, `drawer` grows. */
+export function isPointerRevealMode(mode: LayoutMode): boolean {
+    return mode === LayoutMode.Reveal || mode === LayoutMode.Drawer;
+}
+
+/**
+ * Chooses a different mode.
+ *
+ * Switching also resets the sidebar's transient state, because "open" means something different in each
+ * mode: a static sidebar starts docked, every other mode starts closed, and a reveal/drawer panel that
+ * was hovered out must not stay out under a mode that has no hover behavior. The pin survives, since it
+ * is a preference rather than transient state.
+ */
+export function withMode(state: LayoutConfigState, mode: LayoutMode): LayoutConfigState {
+    return { ...state, mode, isSidebarOpen: mode === LayoutMode.Static, isSidebarRevealed: false };
+}
+
+/**
+ * Records that the viewport crossed the mobile breakpoint.
+ *
+ * Entering the mobile regime closes the sidebar so the page is not covered on arrival; leaving it
+ * restores whatever the chosen mode considers its resting state. Both directions are recomputed rather
+ * than remembered, so a mode switch made while mobile still lands correctly on the way back out.
+ */
+export function withMobile(state: LayoutConfigState, isMobile: boolean): LayoutConfigState {
+    if (state.isMobile === isMobile) {
+        return state;
+    }
+
+    return {
+        ...state,
+        isMobile,
+        isSidebarOpen: isMobile ? false : state.mode === LayoutMode.Static,
+        isSidebarRevealed: false,
+    };
+}
+
+/** Opens or closes the sidebar. */
+export function withSidebarOpen(state: LayoutConfigState, isSidebarOpen: boolean): LayoutConfigState {
+    return { ...state, isSidebarOpen };
+}
+
+/** Flips the sidebar between open and closed - what the topbar's menu button does in every mode. */
+export function toggleSidebar(state: LayoutConfigState): LayoutConfigState {
+    return withSidebarOpen(state, !state.isSidebarOpen);
+}
+
+/**
+ * Holds a `reveal`/`drawer` sidebar out, or lets it fall back.
+ *
+ * An anchored sidebar ignores the pointer entirely - that is the whole point of pinning it - so this is a
+ * no-op while {@link LayoutConfigState.isSidebarAnchored} is set rather than something the pointer can
+ * fight with.
+ */
+export function withSidebarRevealed(state: LayoutConfigState, isSidebarRevealed: boolean): LayoutConfigState {
+    if (state.isSidebarAnchored) {
+        return state;
+    }
+
+    return { ...state, isSidebarRevealed };
+}
+
+/**
+ * Pins or unpins a `reveal`/`drawer` sidebar. Pinning implies revealed, so the panel does not snap shut
+ * the moment the pointer leaves the pin button that just pinned it.
+ */
+export function withSidebarAnchored(state: LayoutConfigState, isSidebarAnchored: boolean): LayoutConfigState {
+    return { ...state, isSidebarAnchored, isSidebarRevealed: isSidebarAnchored };
+}
+
+/** Flips the pin - what the sidebar's anchor button does. */
+export function toggleSidebarAnchor(state: LayoutConfigState): LayoutConfigState {
+    return withSidebarAnchored(state, !state.isSidebarAnchored);
+}
+
+/** Chooses the light/dark axis. */
+export function withColorScheme(state: LayoutConfigState, colorScheme: ColorScheme): LayoutConfigState {
+    return { ...state, colorScheme };
+}
+
+/** Chooses how the sidebar surface is tinted. */
+export function withMenuTheme(state: LayoutConfigState, menuTheme: MenuTheme): LayoutConfigState {
+    return { ...state, menuTheme };
+}
+
+/** Records which {@link Theme} is applied, so a theme switcher reflects the truth after a host-driven change. */
+export function withThemeName(state: LayoutConfigState, themeName: string): LayoutConfigState {
+    return { ...state, themeName };
+}

package/configuration/layoutWrapperClasses.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { LayoutConfigState } from './LayoutConfigState';
+import { LayoutMode } from './LayoutMode';
+import { effectiveLayoutMode, isPointerRevealMode } from './layoutConfigTransitions';
+
+/**
+ * Turns the shell's state into the wrapper class list its stylesheet keys off - the single seam between
+ * the state machine and the CSS.
+ *
+ * Every class name here is the one the PrimeTek template line already uses (`layout-static`,
+ * `layout-overlay-active`, `layout-sidebar-anchored`, `layout-mobile-active`, ...), so a stylesheet
+ * written against those templates keeps working and anyone who has themed one can read this shell's DOM
+ * without a translation table.
+ *
+ * The mode class reflects the *effective* mode, so the off-canvas rules a phone needs come from the same
+ * `layout-overlay` block a desktop overlay uses instead of a parallel mobile-only ruleset. The chosen mode
+ * is still emitted separately as `data-layout-mode`, so a configurator can show what the user picked even
+ * while the viewport overrides it.
+ *
+ * @param state The current shell state.
+ * @returns The classes to put on the shell's wrapper element, always starting with `layout-wrapper`.
+ */
+export function layoutWrapperClasses(state: LayoutConfigState): string[] {
+    const mode = effectiveLayoutMode(state);
+    const classes = [
+        'layout-wrapper',
+        `layout-${mode}`,
+        `layout-menu-${state.menuTheme}`,
+        `layout-color-scheme-${state.colorScheme}`,
+    ];
+
+    if (mode === LayoutMode.Static && !state.isSidebarOpen) {
+        classes.push('layout-static-inactive');
+    }
+
+    if (mode === LayoutMode.Overlay && state.isSidebarOpen && !state.isMobile) {
+        classes.push('layout-overlay-active');
+    }
+
+    if (isPointerRevealMode(mode) && state.isSidebarRevealed) {
+        classes.push('layout-sidebar-active');
+    }
+
+    if (isPointerRevealMode(mode) && state.isSidebarAnchored) {
+        classes.push('layout-sidebar-anchored');
+    }
+
+    if (state.isMobile) {
+        classes.push('layout-mobile');
+    }
+
+    if (state.isMobile && state.isSidebarOpen) {
+        classes.push('layout-mobile-active');
+    }
+
+    return classes;
+}
+
+/**
+ * Whether the scrim that dims the content behind a floating sidebar should be showing. Overlay and mobile
+ * both cover the page, and both need the click-anywhere-to-close the mask provides; a docked or rail
+ * sidebar covers nothing and must not dim anything.
+ */
+export function isLayoutMaskVisible(state: LayoutConfigState): boolean {
+    return effectiveLayoutMode(state) === LayoutMode.Overlay && state.isSidebarOpen;
+}

package/defaultBlueprint.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind, ScenePackage } from '@cratis/scene.model';
+import { ScenePackageBundle } from '@cratis/scene.react';
+import { ComponentName } from './ComponentName';
+import { defaultBlueprintComponents } from './defaultBlueprintComponents';
+import { galleryDialogTemplates, galleryScreenTemplates, galleryScreens } from './gallery';
+import { LayoutName, defaultLayouts } from './layouts';
+import { defaultBlueprintName } from './packageName';
+import { defaultBlueprintThemes } from './themes';
+
+/**
+ * The default blueprint's declaration.
+ *
+ * A blueprint is the package an application picks once to get a coherent shape: the {@link Layout}s that
+ * are its base navigational look, the {@link ScreenTemplate}s and {@link DialogTemplate}s that go inside
+ * them, the components that fill their slots, and the themes that color all of it. Picking the parts
+ * separately is how an application ends up with a sidebar from one design language and a form from
+ * another.
+ *
+ * The dependency list is what makes a blueprint honest about what it is built from. This one declares
+ * PrimeReact - the shell's buttons, breadcrumb, overlay menu and drawer are PrimeReact 10 components - and
+ * Cratis Components, which its screen templates fill their content with. A profile that activated this
+ * blueprint without them would render a shell whose every control was a dashed red placeholder, and
+ * `resolvePackageDependencies` exists to catch that when the profile is configured rather than when
+ * someone opens the page.
+ *
+ * `layouts` lists only true application shells. A dashboard, a CRUD list or a sign-in screen is a screen
+ * template, not a layout, and is listed as one.
+ */
+export const defaultBlueprintManifest: ScenePackage = {
+    name: defaultBlueprintName,
+    version: '1.0.0',
+    kind: PackageKind.Blueprint,
+    dependencies: [{ name: 'PrimeReact' }, { name: 'Cratis.Components' }],
+    components: Object.values(ComponentName),
+    layouts: Object.values(LayoutName),
+    screenTemplates: galleryScreenTemplates.map(template => template.name),
+    dialogTemplates: galleryDialogTemplates.map(template => template.name),
+    themes: defaultBlueprintThemes.map(theme => theme.name),
+    displayName: 'Cratis Default Blueprint',
+    description: 'Application shells with eight menu modes, the components that fill their slots, and a full screen and dialog template set.',
+    module: '@cratis/scene.blueprint.default',
+};
+
+/**
+ * The default blueprint as a loadable bundle.
+ *
+ * The manifest names things; this provides them. `validatePackageBundle` is what proves the two agree, and
+ * this package's specs run it - a manifest promising a component the bundle never registered renders as a
+ * dashed red placeholder somewhere deep inside a screen, a long way from the declaration that caused it.
+ *
+ * The screens are the gallery: real {@link Screen} instances naming a layout, a screen template and the
+ * content that fills it, so a preview boots them through the real engine as a working miniature
+ * application rather than a set of pictures.
+ */
+export const defaultBlueprint: ScenePackageBundle = {
+    manifest: defaultBlueprintManifest,
+    components: defaultBlueprintComponents,
+    layouts: defaultLayouts,
+    screenTemplates: galleryScreenTemplates,
+    dialogTemplates: galleryDialogTemplates,
+    screens: galleryScreens,
+    themes: defaultBlueprintThemes,
+};

package/defaultBlueprintComponents.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentRegistry, componentRegistryKey } from '@cratis/scene.react';
+import { ComponentName } from './ComponentName';
+import { defaultBlueprintName } from './packageName';
+import {
+    AppShell,
+    Breadcrumb,
+    ConfigPanel,
+    Footer,
+    FullPageShell,
+    LayoutModeSwitcher,
+    Logo,
+    Mask,
+    Menu,
+    MenuItem,
+    PageHeader,
+    RightPanel,
+    Sidebar,
+    ThemeSwitcher,
+    Topbar,
+    UserMenu,
+} from './shell';
+
+/**
+ * The components this package registers, keyed the way the renderer looks them up.
+ *
+ * Every key is built with `componentRegistryKey` rather than written out, because the separator between
+ * package and component name is the registry's own business - it is deliberately not the `.` a screen uses
+ * to qualify a name, so that a package name containing dots stays unambiguous. Building a key by hand is
+ * how a component ends up registered under something no lookup will ever produce.
+ */
+export const defaultBlueprintComponents: ComponentRegistry = {
+    [componentRegistryKey(defaultBlueprintName, ComponentName.AppShell)]: AppShell,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.FullPageShell)]: FullPageShell,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.Topbar)]: Topbar,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.Sidebar)]: Sidebar,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.Menu)]: Menu,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.MenuItem)]: MenuItem,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.Breadcrumb)]: Breadcrumb,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.Footer)]: Footer,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.RightPanel)]: RightPanel,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.ConfigPanel)]: ConfigPanel,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.PageHeader)]: PageHeader,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.Mask)]: Mask,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.Logo)]: Logo,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.UserMenu)]: UserMenu,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.ThemeSwitcher)]: ThemeSwitcher,
+    [componentRegistryKey(defaultBlueprintName, ComponentName.LayoutModeSwitcher)]: LayoutModeSwitcher,
+};

package/dist/cjs/ComponentName.js

@@ -0,0 +1,33 @@
+'use strict';
+
+// 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.
+ */ var ComponentName = /*#__PURE__*/ function(ComponentName) {
+    /** The application shell - topbar, sidebar, breadcrumb, content, footer and an optional right panel. */ ComponentName["AppShell"] = "appShell";
+    /** The chrome-less shell - content, an optional branding aside, and the configurator. */ ComponentName["FullPageShell"] = "fullPageShell";
+    /** The fixed strip across the top of the application shell. */ ComponentName["Topbar"] = "topbar";
+    /** The sidebar's own chrome, inside the shell-positioned panel. */ ComponentName["Sidebar"] = "sidebar";
+    /** A navigation list. */ ComponentName["Menu"] = "menu";
+    /** One entry in a navigation list, optionally with a submenu. */ ComponentName["MenuItem"] = "menuItem";
+    /** The trail above the content. */ ComponentName["Breadcrumb"] = "breadcrumb";
+    /** The strip below the content. */ ComponentName["Footer"] = "footer";
+    /** The inspector panel down the right-hand edge. */ ComponentName["RightPanel"] = "rightPanel";
+    /** The floating configurator: color scheme, layout mode, menu theme and theme. */ ComponentName["ConfigPanel"] = "configPanel";
+    /** A screen's title, subtitle and actions. */ ComponentName["PageHeader"] = "pageHeader";
+    /** The scrim behind a floating sidebar, which also closes it. */ ComponentName["Mask"] = "mask";
+    /** The brand mark. */ ComponentName["Logo"] = "logo";
+    /** The signed-in user's avatar and menu. */ ComponentName["UserMenu"] = "userMenu";
+    /** Switches between the themes a host offers. */ ComponentName["ThemeSwitcher"] = "themeSwitcher";
+    /** Switches between the layout modes. */ ComponentName["LayoutModeSwitcher"] = "layoutModeSwitcher";
+    return ComponentName;
+}({});
+
+exports.ComponentName = ComponentName;
+//# sourceMappingURL=ComponentName.js.map

package/dist/cjs/ComponentName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentName.js","sources":["../../ComponentName.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/**\n * The bare names this package declares components under.\n *\n * A page template writes a bare name and `resolveComponentName` decides which active package wins it, so\n * these names are public API: renaming one breaks every template that referenced it, in this package and\n * in anyone else's. Keeping them in one enum means the manifest, the registry and every template\n * reference the same symbol, and the specs can prove all three agree rather than hoping they do.\n */\nexport enum ComponentName {\n    /** The application shell - topbar, sidebar, breadcrumb, content, footer and an optional right panel. */\n    AppShell = 'appShell',\n\n    /** The chrome-less shell - content, an optional branding aside, and the configurator. */\n    FullPageShell = 'fullPageShell',\n\n    /** The fixed strip across the top of the application shell. */\n    Topbar = 'topbar',\n\n    /** The sidebar's own chrome, inside the shell-positioned panel. */\n    Sidebar = 'sidebar',\n\n    /** A navigation list. */\n    Menu = 'menu',\n\n    /** One entry in a navigation list, optionally with a submenu. */\n    MenuItem = 'menuItem',\n\n    /** The trail above the content. */\n    Breadcrumb = 'breadcrumb',\n\n    /** The strip below the content. */\n    Footer = 'footer',\n\n    /** The inspector panel down the right-hand edge. */\n    RightPanel = 'rightPanel',\n\n    /** The floating configurator: color scheme, layout mode, menu theme and theme. */\n    ConfigPanel = 'configPanel',\n\n    /** A screen's title, subtitle and actions. */\n    PageHeader = 'pageHeader',\n\n    /** The scrim behind a floating sidebar, which also closes it. */\n    Mask = 'mask',\n\n    /** The brand mark. */\n    Logo = 'logo',\n\n    /** The signed-in user's avatar and menu. */\n    UserMenu = 'userMenu',\n\n    /** Switches between the themes a host offers. */\n    ThemeSwitcher = 'themeSwitcher',\n\n    /** Switches between the layout modes. */\n    LayoutModeSwitcher = 'layoutModeSwitcher',\n}\n"],"names":["ComponentName"],"mappings":";;AAAA;AACA;AAEA;;;;;;;IAQO,IAAKA,aAAAA,iBAAAA,SAAAA,aAAAA,EAAAA;6GAC8F,aAAA,CAAA,UAAA,CAAA,GAAA,UAAA;8FAGf,aAAA,CAAA,eAAA,CAAA,GAAA,eAAA;oEAG1B,aAAA,CAAA,QAAA,CAAA,GAAA,QAAA;wEAGI,aAAA,CAAA,SAAA,CAAA,GAAA,SAAA;8BAG1C,aAAA,CAAA,MAAA,CAAA,GAAA,MAAA;sEAGwC,aAAA,CAAA,UAAA,CAAA,GAAA,UAAA;wCAG9B,aAAA,CAAA,YAAA,CAAA,GAAA,YAAA;wCAGA,aAAA,CAAA,QAAA,CAAA,GAAA,QAAA;yDAGiB,aAAA,CAAA,YAAA,CAAA,GAAA,YAAA;uFAG8B,aAAA,CAAA,aAAA,CAAA,GAAA,aAAA;mDAGpC,aAAA,CAAA,YAAA,CAAA,GAAA,YAAA;sEAGmB,aAAA,CAAA,MAAA,CAAA,GAAA,MAAA;2BAG3C,aAAA,CAAA,MAAA,CAAA,GAAA,MAAA;iDAGsB,aAAA,CAAA,UAAA,CAAA,GAAA,UAAA;sDAGK,aAAA,CAAA,eAAA,CAAA,GAAA,eAAA;8CAGR,aAAA,CAAA,oBAAA,CAAA,GAAA,oBAAA;AA9C/BA,IAAAA,OAAAA,aAAAA;AAgDX,CAAA,CAAA,EAAA;;;;"}

package/dist/cjs/configuration/ColorScheme.js

@@ -0,0 +1,23 @@
+'use strict';
+
+// 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.
+ */ var ColorScheme = /*#__PURE__*/ function(ColorScheme) {
+    ColorScheme["Light"] = "light";
+    ColorScheme["Dark"] = "dark";
+    return ColorScheme;
+}({});
+/** Every {@link ColorScheme}, in the order a configurator should offer them. */ const colorSchemes = [
+    "light",
+    "dark"
+];
+
+exports.ColorScheme = ColorScheme;
+exports.colorSchemes = colorSchemes;
+//# sourceMappingURL=ColorScheme.js.map

package/dist/cjs/configuration/ColorScheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColorScheme.js","sources":["../../../configuration/ColorScheme.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/**\n * The light/dark axis of the configurator.\n *\n * The shell never paints a color for a scheme itself - it only records which one is chosen, so the host\n * can hand {@link SceneThemeProvider} a matching {@link Theme}. Keeping the choice and the palette apart\n * is what lets a third-party theme participate in the same switch as the two this package ships.\n */\nexport enum ColorScheme {\n    Light = 'light',\n    Dark = 'dark',\n}\n\n/** Every {@link ColorScheme}, in the order a configurator should offer them. */\nexport const colorSchemes: ColorScheme[] = [ColorScheme.Light, ColorScheme.Dark];\n"],"names":["ColorScheme","colorSchemes"],"mappings":";;AAAA;AACA;AAEA;;;;;;IAOO,IAAKA,WAAAA,iBAAAA,SAAAA,WAAAA,EAAAA;;;AAAAA,IAAAA,OAAAA,WAAAA;AAGX,CAAA,CAAA,EAAA;AAED,iFACO,MAAMC,YAAAA,GAA8B;;;;;;;;"}

package/dist/cjs/configuration/LayoutConfigProvider.js

@@ -0,0 +1,96 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var layoutConfigStorage = require('./layoutConfigStorage.js');
+var layoutWrapperClasses = require('./layoutWrapperClasses.js');
+var layoutConfigTransitions = require('./layoutConfigTransitions.js');
+
+const LayoutConfigContext = /*#__PURE__*/ react.createContext(undefined);
+/**
+ * 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.
+ */ function LayoutConfigProvider({ initialConfig, storage, viewportWidth, children }) {
+    const resolvedStorage = react.useMemo(()=>storage !== undefined ? storage ?? undefined : defaultStorage(), [
+        storage
+    ]);
+    const [config, setConfig] = react.useState(()=>({
+            ...layoutConfigStorage.readPersistedLayoutConfig(resolvedStorage),
+            ...initialConfig
+        }));
+    react.useEffect(()=>{
+        layoutConfigStorage.persistLayoutConfig(config, resolvedStorage);
+    }, [
+        config,
+        resolvedStorage
+    ]);
+    const isReportedMobile = viewportWidth === undefined ? undefined : layoutConfigTransitions.isMobileWidth(viewportWidth);
+    react.useEffect(()=>{
+        if (isReportedMobile !== undefined) {
+            setConfig((current)=>layoutConfigTransitions.withMobile(current, isReportedMobile));
+            return;
+        }
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+            return;
+        }
+        const query = window.matchMedia(layoutConfigTransitions.mobileMediaQuery);
+        setConfig((current)=>layoutConfigTransitions.withMobile(current, query.matches));
+        const listener = (event)=>setConfig((current)=>layoutConfigTransitions.withMobile(current, event.matches));
+        query.addEventListener('change', listener);
+        return ()=>query.removeEventListener('change', listener);
+    }, [
+        isReportedMobile
+    ]);
+    const value = react.useMemo(()=>({
+            config,
+            effectiveMode: layoutConfigTransitions.effectiveLayoutMode(config),
+            wrapperClasses: layoutWrapperClasses.layoutWrapperClasses(config),
+            isMaskVisible: layoutWrapperClasses.isLayoutMaskVisible(config),
+            setMode: (mode)=>setConfig((current)=>layoutConfigTransitions.withMode(current, mode)),
+            setMenuTheme: (menuTheme)=>setConfig((current)=>layoutConfigTransitions.withMenuTheme(current, menuTheme)),
+            setColorScheme: (colorScheme)=>setConfig((current)=>layoutConfigTransitions.withColorScheme(current, colorScheme)),
+            setThemeName: (themeName)=>setConfig((current)=>layoutConfigTransitions.withThemeName(current, themeName)),
+            setSidebarOpen: (isOpen)=>setConfig((current)=>layoutConfigTransitions.withSidebarOpen(current, isOpen)),
+            toggleSidebar: ()=>setConfig(layoutConfigTransitions.toggleSidebar),
+            setSidebarRevealed: (isRevealed)=>setConfig((current)=>layoutConfigTransitions.withSidebarRevealed(current, isRevealed)),
+            toggleSidebarAnchor: ()=>setConfig(layoutConfigTransitions.toggleSidebarAnchor)
+        }), [
+        config
+    ]);
+    return /*#__PURE__*/ jsxRuntime.jsx(LayoutConfigContext.Provider, {
+        value: value,
+        children: children
+    });
+}
+/**
+ * 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.
+ */ function useOptionalLayoutConfig() {
+    return react.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.
+ */ function useLayoutConfig() {
+    const value = useOptionalLayoutConfig();
+    if (!value) {
+        throw new Error('useLayoutConfig() requires a <LayoutConfigProvider> above it.');
+    }
+    return value;
+}
+function defaultStorage() {
+    return typeof window !== 'undefined' ? window.localStorage : undefined;
+}
+
+exports.LayoutConfigProvider = LayoutConfigProvider;
+exports.useLayoutConfig = useLayoutConfig;
+exports.useOptionalLayoutConfig = useOptionalLayoutConfig;
+//# sourceMappingURL=LayoutConfigProvider.js.map

package/dist/cjs/configuration/LayoutConfigProvider.js.map

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