@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.4

package/dist/shell/headless/navigation.js

@@ -0,0 +1,138 @@
+// =============================================================================
+// The shell's navigation model (issue #868; moved from the reference app's
+// `config/destinations.ts`, issues #55, #92, #94, #105, #425)
+// =============================================================================
+//
+// The app declares its destinations ONCE and every navigation surface of the
+// shell (rail, bottom bar, user menu) draws them from that one table, with the
+// same visibility rule and the same active-state rule. Before the table existed
+// the same menu paths were spelled out in four places, each with its own idea
+// of who could see them; one table is the fix.
+//
+// Two rules keep the ownership table trustworthy:
+//
+//  1. A route is owned by at most one destination (the app's own test asserts
+//     this against its live route list).
+//  2. Matching respects segment boundaries (`owns`): a bare `startsWith` would
+//     make `/settings` own `/settingsfoo`.
+// =============================================================================
+import { isFeatureEnabled } from '../../settings/index.js';
+/**
+ * Is `path` a plain `http:` or `https:` URL? What an `external` destination's
+ * `path` must be; any other scheme (`javascript:`, `data:`) is refused.
+ *
+ * @param path - a destination's `path`.
+ * @returns whether it is an absolute http(s) URL.
+ *
+ * @stability experimental
+ */
+export function isExternalUrl(path) {
+    if (!path)
+        return false;
+    try {
+        const url = new URL(path);
+        return url.protocol === 'https:' || url.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Split destinations into runs of the same `group`, keeping declaration order. A
+ * destination without a group never joins a run of grouped ones. With no
+ * `group` anywhere the result is one run holding every destination.
+ *
+ * @param destinations - the destinations to draw, in order.
+ * @returns the runs.
+ *
+ * @stability experimental
+ */
+export function groupDestinationRuns(destinations) {
+    const runs = [];
+    for (const destination of destinations) {
+        const last = runs[runs.length - 1];
+        if (last && last.group === destination.group)
+            last.destinations.push(destination);
+        else
+            runs.push({ group: destination.group, destinations: [destination] });
+    }
+    return runs;
+}
+/**
+ * Does `prefix` own `path`? True when the path equals the prefix or continues
+ * with a `/`. `'/'` owns only itself, or Home would own the whole app.
+ *
+ * @param prefix - a route prefix.
+ * @param path - a pathname.
+ * @returns whether `prefix` owns `path`.
+ *
+ * @stability experimental
+ */
+export function owns(prefix, path) {
+    if (prefix === '/')
+        return path === '/';
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+/**
+ * Is `destination` visible to this viewer? Every surface asks this one
+ * function: the feature gate, then `permission`, then `anyPermission`.
+ *
+ * @param destination - the destination.
+ * @param hasPermission - the viewer's permission predicate.
+ * @param features - the deployment's feature map (fail closed).
+ * @returns whether to draw it.
+ *
+ * @stability experimental
+ */
+export function isDestinationVisible(destination, hasPermission, features = {}) {
+    if (!isFeatureEnabled(destination.feature, features))
+        return false;
+    // Fail closed: an external destination whose `path` is not a plain http(s) URL (a
+    // `javascript:` or `data:` target) is never drawn.
+    if (destination.external && !isExternalUrl(destination.path))
+        return false;
+    if (destination.permission && !hasPermission(destination.permission))
+        return false;
+    if (destination.anyPermission && !destination.anyPermission.some(hasPermission))
+        return false;
+    return true;
+}
+/**
+ * The route prefixes of each destination: `navigation.destinationRoutes`, or
+ * each destination's own `path`.
+ *
+ * @param navigation - the app's navigation.
+ * @returns the ownership table.
+ *
+ * @stability experimental
+ */
+export function shellDestinationRoutes(navigation) {
+    if (navigation.destinationRoutes)
+        return navigation.destinationRoutes;
+    const routes = {};
+    for (const destination of navigation.destinations)
+        routes[destination.key] = [destination.path];
+    return routes;
+}
+/**
+ * Which destination, if any, owns `pathname`. The longest owning prefix wins.
+ *
+ * @param routes - the ownership table (`shellDestinationRoutes`).
+ * @param pathname - the current path.
+ * @returns the owning key, or `null` (a route deliberately owned by none).
+ *
+ * @stability experimental
+ */
+export function resolveActiveDestination(routes, pathname) {
+    let best = null;
+    for (const [key, prefixes] of Object.entries(routes)) {
+        for (const prefix of prefixes) {
+            if (!owns(prefix, pathname))
+                continue;
+            if (!best || prefix.length > best.length)
+                best = { key, length: prefix.length };
+        }
+    }
+    return best?.key ?? null;
+}
+//# sourceMappingURL=navigation.js.map

package/dist/shell/headless/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../../src/shell/headless/navigation.ts"],"names":[],"mappings":"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"}

package/dist/shell/headless/providers.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentType, ReactElement, ReactNode } from 'react';
+/**
+ * One provider of the stack: any component that renders its `children`.
+ * Bind props with a small wrapper (`({ children }) => <X api={api}>{children}</X>`)
+ * declared at module scope, so its identity is stable.
+ *
+ * @stability experimental
+ */
+export type ShellProvider = ComponentType<ShellProviderProps>;
+/**
+ * What {@link ShellProviders} passes each provider.
+ *
+ * @stability experimental
+ */
+export interface ShellProviderProps {
+    /** The rest of the stack, then the shell. */
+    children: ReactNode;
+}
+/**
+ * Nest `providers` around `children`, the first OUTERMOST. Renders no element
+ * of its own, so the DOM is the same as the hand-written staircase.
+ *
+ * @param props - `providers`: the stack, outermost first (declare it at module
+ *   scope); `children`: what the innermost provider wraps (the shell layout).
+ * @returns the nested tree.
+ *
+ * @example
+ * ```tsx
+ * const SHELL_PROVIDERS: readonly ShellProvider[] = [NotificationProvider, AppPlatformHostProvider];
+ * <ShellProviders providers={SHELL_PROVIDERS}><Layout /></ShellProviders>
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export declare function ShellProviders(props: {
+    providers: readonly ShellProvider[];
+    children: ReactNode;
+}): ReactElement;
+//# sourceMappingURL=providers.d.ts.map

package/dist/shell/headless/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/shell/headless/providers.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IAAE,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,GAAG,YAAY,CAOhH"}

package/dist/shell/headless/providers.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Nest `providers` around `children`, the first OUTERMOST. Renders no element
+ * of its own, so the DOM is the same as the hand-written staircase.
+ *
+ * @param props - `providers`: the stack, outermost first (declare it at module
+ *   scope); `children`: what the innermost provider wraps (the shell layout).
+ * @returns the nested tree.
+ *
+ * @example
+ * ```tsx
+ * const SHELL_PROVIDERS: readonly ShellProvider[] = [NotificationProvider, AppPlatformHostProvider];
+ * <ShellProviders providers={SHELL_PROVIDERS}><Layout /></ShellProviders>
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export function ShellProviders(props) {
+    let tree = props.children;
+    for (let index = props.providers.length - 1; index >= 0; index -= 1) {
+        const Provider = props.providers[index];
+        tree = _jsx(Provider, { children: tree });
+    }
+    return _jsx(_Fragment, { children: tree });
+}
+//# sourceMappingURL=providers.js.map

package/dist/shell/headless/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../../src/shell/headless/providers.tsx"],"names":[],"mappings":";AAiCA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,KAAmE;IAChG,IAAI,IAAI,GAAc,KAAK,CAAC,QAAQ,CAAC;IACrC,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpE,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAE,CAAC;QACzC,IAAI,GAAG,KAAC,QAAQ,cAAE,IAAI,GAAY,CAAC;IACrC,CAAC;IACD,OAAO,4BAAG,IAAI,GAAI,CAAC;AACrB,CAAC"}

package/dist/shell/headless/rail-preference.d.ts

@@ -0,0 +1,34 @@
+import type { PlatformApiClient } from '../../core/index.js';
+import type { ShellRailPreference } from './navigation.js';
+/**
+ * Options of {@link useShellRailPreference}.
+ *
+ * @stability experimental
+ */
+export interface ShellRailPreferenceOptions {
+    /** The transport. Default: the platform host's (`PlatformHostProvider`). */
+    api?: PlatformApiClient;
+}
+/**
+ * What {@link useShellRailPreference} returns.
+ *
+ * @stability experimental
+ */
+export interface UseShellRailPreferenceResult extends ShellRailPreference {
+    /** True until the first settings read resolves; the rail renders the default meanwhile. */
+    isLoading: boolean;
+}
+/**
+ * The desktop rail's collapse preference, stored in the viewer's `navigation`
+ * user-settings namespace (`railCollapsed`). Optimistic toggle; a default is
+ * never written back. Never syncs the stored theme (it is mounted by
+ * always-present chrome, where a sync would stamp over the AppBar's toggle).
+ *
+ * @param options - an explicit transport, else the platform host's.
+ * @returns the preference, its toggle and whether it has loaded.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useShellRailPreference(options?: ShellRailPreferenceOptions): UseShellRailPreferenceResult;
+//# sourceMappingURL=rail-preference.d.ts.map

package/dist/shell/headless/rail-preference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rail-preference.d.ts","sourceRoot":"","sources":["../../../src/shell/headless/rail-preference.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAU3D;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,4EAA4E;IAC5E,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA6B,SAAQ,mBAAmB;IACvE,2FAA2F;IAC3F,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,0BAA+B,GAAG,4BAA4B,CAmC7G"}

package/dist/shell/headless/rail-preference.js

@@ -0,0 +1,67 @@
+// =============================================================================
+// `user_settings.navigation` - the rail's collapse preference (issue #868;
+// moved from the reference app's `hooks/useNavigationPrefs.ts`, issue #55)
+// =============================================================================
+//
+// No endpoint of its own: the same `GET`/`PATCH /api/user-settings` the
+// settings slice's `useUserSettings` uses. The API merges the `navigation`
+// namespace field-wise, so only the changed field goes on the wire.
+//
+// TWO CONTRACTS THIS FILE HOLDS
+//
+// 1. ABSENT MEANS DEFAULT, and a default is never written back. An absent
+//    namespace or field means "rail expanded"; we never PATCH that on load, so
+//    a later change to the default still reaches users who never touched it.
+//    The read is `=== true`: absent and an explicit `false` both mean expanded.
+// 2. THE TOGGLE IS OPTIMISTIC. The overlay is cleared once the write settles,
+//    at which point the stored value either carries the new value (success) or
+//    the old one (failure): the revert is the same path as the commit.
+// =============================================================================
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { useUserSettings } from '../../settings/index.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+/**
+ * The desktop rail's collapse preference, stored in the viewer's `navigation`
+ * user-settings namespace (`railCollapsed`). Optimistic toggle; a default is
+ * never written back. Never syncs the stored theme (it is mounted by
+ * always-present chrome, where a sync would stamp over the AppBar's toggle).
+ *
+ * @param options - an explicit transport, else the platform host's.
+ * @returns the preference, its toggle and whether it has loaded.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useShellRailPreference(options = {}) {
+    const { settings, isLoading, updateSettings } = useUserSettings({
+        syncTheme: false,
+        ...(options.api === undefined ? {} : { api: options.api }),
+    });
+    const isMounted = useIsMounted();
+    // What the server says; absent anywhere collapses to the default.
+    const stored = useMemo(() => ({ railCollapsed: settings?.navigation?.railCollapsed === true }), [settings]);
+    const [overlay, setOverlay] = useState(null);
+    // Guards against a late write from a PREVIOUS click clearing a NEWER overlay.
+    const writeSeq = useRef(0);
+    const effective = overlay ?? stored;
+    const toggleRailCollapsed = useCallback(() => {
+        // No settings yet means no `version` for If-Match, so the write would
+        // no-op; skipping the overlay too keeps the UI honest.
+        if (!settings)
+            return;
+        const railCollapsed = !effective.railCollapsed;
+        const seq = ++writeSeq.current;
+        setOverlay({ railCollapsed });
+        void updateSettings({ navigation: { railCollapsed } })
+            .catch(() => undefined)
+            .finally(() => {
+            if (!isMounted())
+                return;
+            if (writeSeq.current !== seq)
+                return;
+            setOverlay(null);
+        });
+    }, [settings, effective, updateSettings, isMounted]);
+    return { railCollapsed: effective.railCollapsed, toggleRailCollapsed, isLoading };
+}
+//# sourceMappingURL=rail-preference.js.map

package/dist/shell/headless/rail-preference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rail-preference.js","sourceRoot":"","sources":["../../../src/shell/headless/rail-preference.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,2EAA2E;AAC3E,2EAA2E;AAC3E,gFAAgF;AAChF,EAAE;AACF,wEAAwE;AACxE,2EAA2E;AAC3E,oEAAoE;AACpE,EAAE;AACF,gCAAgC;AAChC,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,8EAA8E;AAC9E,+EAA+E;AAC/E,uEAAuE;AACvE,gFAAgF;AAEhF,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AA+B7D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAsC,EAAE;IAC7E,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,eAAe,CAAuC;QACpG,SAAS,EAAE,KAAK;QAChB,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;KAC3D,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,kEAAkE;IAClE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE5G,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAoC,IAAI,CAAC,CAAC;IAChF,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAE3B,MAAM,SAAS,GAAG,OAAO,IAAI,MAAM,CAAC;IAEpC,MAAM,mBAAmB,GAAG,WAAW,CAAC,GAAG,EAAE;QAC3C,sEAAsE;QACtE,uDAAuD;QACvD,IAAI,CAAC,QAAQ;YAAE,OAAO;QAEtB,MAAM,aAAa,GAAG,CAAC,SAAS,CAAC,aAAa,CAAC;QAC/C,MAAM,GAAG,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC;QAC/B,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;QAE9B,KAAK,cAAc,CAAC,EAAE,UAAU,EAAE,EAAE,aAAa,EAAE,EAAE,CAAC;aACnD,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;aACtB,OAAO,CAAC,GAAG,EAAE;YACZ,IAAI,CAAC,SAAS,EAAE;gBAAE,OAAO;YACzB,IAAI,QAAQ,CAAC,OAAO,KAAK,GAAG;gBAAE,OAAO;YACrC,UAAU,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC,CAAC,CAAC;IACP,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC;IAErD,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,mBAAmB,EAAE,SAAS,EAAE,CAAC;AACpF,CAAC"}

package/dist/shell/headless/theme.d.ts

@@ -0,0 +1,190 @@
+import type { Components, PaletteOptions, Theme } from '@mui/material/styles';
+/**
+ * The viewer's theme choice: `light`, `dark`, `system` (follows
+ * `prefers-color-scheme`), or the id of a theme the app registered with
+ * {@link registerThemeMode} or passed to the provider's `themes` (a
+ * `high-contrast` theme, a brand skin). The id is the same one the API accepts
+ * for the `theme` user setting when the app registered it there with
+ * `registerThemePreference`.
+ *
+ * @stability experimental
+ */
+export type ShellThemeMode = 'light' | 'dark' | 'system' | (string & {});
+/**
+ * The three modes the shell always has: `light`, `dark` and `system`. A theme
+ * registered under one of these ids is refused.
+ *
+ * @stability experimental
+ */
+export declare const BUILTIN_SHELL_THEME_MODES: readonly ["light", "dark", "system"];
+/**
+ * Whether `mode` is one of {@link BUILTIN_SHELL_THEME_MODES}.
+ *
+ * @param mode - a mode id.
+ * @returns whether it is built in.
+ *
+ * @stability experimental
+ */
+export declare function isBuiltinThemeMode(mode: string): mode is (typeof BUILTIN_SHELL_THEME_MODES)[number];
+/**
+ * One theme an app added to the shell's modes.
+ *
+ * @stability experimental
+ */
+export interface ShellThemeModeDefinition {
+    /** The mode id: lower-case, starting with a letter, 2 to 48 characters (the API's theme id pattern). */
+    id: string;
+    /** What a theme picker calls it. */
+    label: string;
+    /** The MUI theme shown while the mode is chosen. Its `palette.mode` decides whether the app counts as dark (the AppBar toggle's icon). */
+    theme: Theme;
+}
+/**
+ * Add a theme mode to the shell: after this, `setMode(id)` of the theme context
+ * chooses it, the stored choice is restored on the next visit, and
+ * `ShellThemeProvider` resolves it to `theme`. Register at module scope, before
+ * the first render, next to the app's own themes.
+ *
+ * To let a user pick it on the Appearance page, register the same id on the API
+ * with `registerThemePreference` (`@marinoscar/platform-api/settings`): the
+ * settings document then lists it in `themeOptions`, and the packaged settings
+ * hook hands a stored value to the host's `applyTheme` (the app's `setMode`).
+ *
+ * @param definition - the id, label and theme.
+ * @throws Error when the id is malformed, built in or already registered, the label is empty or the theme is missing.
+ *
+ * @example
+ * ```ts
+ * registerThemeMode({ id: 'high-contrast', label: 'High contrast', theme: highContrastTheme });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerThemeMode(definition: ShellThemeModeDefinition): void;
+/**
+ * The theme modes registered with {@link registerThemeMode}, in registration order.
+ *
+ * @returns a fresh array.
+ *
+ * @stability experimental
+ */
+export declare function listThemeModes(): ShellThemeModeDefinition[];
+/**
+ * Forget every registered theme mode. For tests only.
+ *
+ * @internal
+ */
+export declare function resetThemeModesForTests(): void;
+/**
+ * The shell's palette for `mode`, with `overrides` merged one level deep into
+ * `primary`, `secondary`, `background` and `text` (so `{ primary: { main } }`
+ * keeps the hand-picked `light` and `dark` tints) and shallowly elsewhere.
+ *
+ * @param mode - `light` or `dark`.
+ * @param overrides - the app's palette changes (its brand colour).
+ * @returns the palette options.
+ *
+ * @stability experimental
+ */
+export declare function shellPalette(mode: 'light' | 'dark', overrides?: PaletteOptions): PaletteOptions;
+/**
+ * The shell's component overrides for `mode`: no-uppercase 500-weight
+ * buttons, a soft card shadow, and a flat AppBar with a 1px bottom border.
+ *
+ * @param mode - `light` or `dark`.
+ * @returns the MUI component overrides.
+ *
+ * @stability experimental
+ */
+export declare function shellComponentOverrides(mode: 'light' | 'dark'): Components<Theme>;
+/**
+ * Options of {@link createShellTheme}.
+ *
+ * @stability experimental
+ */
+export interface ShellThemeOptions {
+    /** Palette changes, merged by {@link shellPalette} (the app's brand colour). */
+    palette?: PaletteOptions;
+    /** Applied to the built theme last (e.g. the telemetry slice's `withTelemetryTokens`). */
+    extend?: (theme: Theme) => Theme;
+}
+/**
+ * Build the shell's MUI theme for `mode`.
+ *
+ * @param mode - `light` or `dark`.
+ * @param options - the app's palette changes and a final `extend` step.
+ * @returns the theme.
+ *
+ * @example
+ * ```ts
+ * export const lightTheme = createShellTheme('light', { palette: { primary: { main: THEME_COLOR } }, extend: withTelemetryTokens });
+ * export const darkTheme = createShellTheme('dark', { extend: withTelemetryTokens });
+ * ```
+ *
+ * @extensionPoint theme-token
+ * @stability experimental
+ */
+export declare function createShellTheme(mode: 'light' | 'dark', options?: ShellThemeOptions): Theme;
+/**
+ * One theme mode beyond light, dark and system, as a picker lists it.
+ *
+ * @stability experimental
+ */
+export interface ShellThemeModeOption {
+    /** The mode id, what `setMode` takes. */
+    id: string;
+    /** What a picker calls it. */
+    label: string;
+}
+/**
+ * What the shell's theme context holds.
+ *
+ * @stability experimental
+ */
+export interface ShellThemeContextValue {
+    /** The viewer's choice. */
+    mode: ShellThemeMode;
+    /** The resolved MUI theme. */
+    theme: Theme;
+    /**
+     * The themes beyond light, dark and system that can be chosen (the provider's
+     * extra `themes` and the registered ones), for a picker. Absent from a context
+     * value built by hand.
+     */
+    modes?: readonly ShellThemeModeOption[];
+    /**
+     * Choose a mode (persisted in this browser). An id that is neither built in
+     * nor a known theme is ignored.
+     */
+    setMode(mode: ShellThemeMode): void;
+    /** Flip between light and dark (from whatever is showing now). */
+    toggleMode(): void;
+    /** Whether the dark theme is showing. */
+    isDarkMode: boolean;
+}
+/**
+ * The context `ShellThemeProvider` (`@marinoscar/platform-web/shell/ui`) fills.
+ *
+ * @stability experimental
+ */
+export declare const ShellThemeContext: import("react").Context<ShellThemeContextValue | null>;
+/**
+ * The shell's theme context, or `null` outside a `ShellThemeProvider` (the
+ * AppBar then draws no theme toggle).
+ *
+ * @returns the context value, or `null`.
+ *
+ * @stability experimental
+ */
+export declare function useOptionalShellTheme(): ShellThemeContextValue | null;
+/**
+ * The shell's theme context: the mode, the resolved theme and the setters.
+ *
+ * @returns the context value.
+ * @throws Error outside a `ShellThemeProvider`.
+ *
+ * @stability experimental
+ */
+export declare function useShellTheme(): ShellThemeContextValue;
+//# sourceMappingURL=theme.d.ts.map

package/dist/shell/headless/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../src/shell/headless/theme.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,EAAgB,MAAM,sBAAsB,CAAC;AAE5F;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,sCAAuC,CAAC;AAE9E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAEnG;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,wGAAwG;IACxG,EAAE,EAAE,MAAM,CAAC;IACX,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,0IAA0I;IAC1I,KAAK,EAAE,KAAK,CAAC;CACd;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,wBAAwB,GAAG,IAAI,CAU5E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,wBAAwB,EAAE,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAkCD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,SAAS,GAAE,cAAmB,GAAG,cAAc,CAUnG;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CA0BjF;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAAC;CAClC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,KAAK,CAU/F;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,2BAA2B;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,8BAA8B;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACxC;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IACpC,kEAAkE;IAClE,UAAU,IAAI,IAAI,CAAC;IACnB,yCAAyC;IACzC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,wDAAqD,CAAC;AAGpF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,sBAAsB,GAAG,IAAI,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,sBAAsB,CAQtD"}