@happyvertical/smrt-svelte 0.51.38 → 0.52.0

package/dist/components/workspace/admin-shell/mobile-shell-dom.js

@@ -0,0 +1,150 @@
+/**
+ * DOM wiring for AdminShell's responsive chrome. Every installer returns a
+ * disposer and is a no-op without the browser API it needs, so callers can
+ * run them from `onMount` without guards. The decisions live in
+ * `./mobile-shell.ts`.
+ */
+import { isEditableTarget } from './hotkeys.js';
+import { FORM_ACTION_BAR_SELECTOR, keyboardLikelyOpen, ScrollChrome, viewportFor, } from './mobile-shell.js';
+import { ADMIN_SHELL_DESKTOP_QUERY, ADMIN_SHELL_PHONE_QUERY, } from './state.svelte.js';
+/**
+ * Keep `shell.viewport` in step with the phone/desktop media queries (which
+ * applies each edge's `viewportDefaults` when the class changes).
+ */
+export function installShellViewport(shell) {
+    if (typeof window === 'undefined' ||
+        typeof window.matchMedia !== 'function') {
+        return () => { };
+    }
+    const phone = window.matchMedia(ADMIN_SHELL_PHONE_QUERY);
+    const desktop = window.matchMedia(ADMIN_SHELL_DESKTOP_QUERY);
+    const sync = () => shell.setViewport(viewportFor({ phone: phone.matches, desktop: desktop.matches }));
+    sync();
+    phone.addEventListener('change', sync);
+    desktop.addEventListener('change', sync);
+    return () => {
+        phone.removeEventListener('change', sync);
+        desktop.removeEventListener('change', sync);
+    };
+}
+/**
+ * Keep `shell.overlayMatches` in step with each side edge's `overlayMedia`
+ * query (edges without one are skipped).
+ */
+export function installShellOverlayMedia(shell) {
+    if (typeof window === 'undefined' ||
+        typeof window.matchMedia !== 'function') {
+        return () => { };
+    }
+    const disposers = [];
+    for (const edge of ['left', 'right']) {
+        const query = shell.config.panels[edge].overlayMedia;
+        if (!query)
+            continue;
+        const media = window.matchMedia(query);
+        const sync = () => shell.setOverlayMatch(edge, media.matches);
+        sync();
+        media.addEventListener('change', sync);
+        disposers.push(() => media.removeEventListener('change', sync));
+    }
+    return () => {
+        for (const dispose of disposers)
+            dispose();
+    };
+}
+/**
+ * Hide-on-scroll for one scroller (AdminShell's main region). Samples once
+ * per animation frame and reports changes of the hidden state.
+ */
+export function installScrollChrome(scroller, options) {
+    const chrome = new ScrollChrome(options.tuning);
+    let frame = 0;
+    let last = false;
+    function sample() {
+        frame = 0;
+        const hidden = chrome.update({
+            y: scroller.scrollTop,
+            maxY: scroller.scrollHeight - scroller.clientHeight,
+            pinned: options.isPinned(),
+        });
+        if (hidden !== last) {
+            last = hidden;
+            options.onChange(hidden);
+        }
+    }
+    function onScroll() {
+        if (!frame)
+            frame = requestAnimationFrame(sample);
+    }
+    scroller.addEventListener('scroll', onScroll, { passive: true });
+    return {
+        recheck: sample,
+        reset() {
+            chrome.reset();
+            if (last) {
+                last = false;
+                options.onChange(false);
+            }
+        },
+        destroy() {
+            if (frame)
+                cancelAnimationFrame(frame);
+            scroller.removeEventListener('scroll', onScroll);
+        },
+    };
+}
+/**
+ * Watch for the on-screen keyboard. Sets `data-keyboard-open` on `<html>`
+ * (phone bars and `FormActionBar` hide on it) and keeps the focused field in
+ * view when the keyboard opens.
+ */
+export function installKeyboardWatcher(onChange) {
+    if (typeof window === 'undefined' || !window.visualViewport) {
+        return () => { };
+    }
+    const viewport = window.visualViewport;
+    let open = false;
+    function sync() {
+        const next = keyboardLikelyOpen({
+            layoutHeight: window.innerHeight,
+            visualHeight: viewport.height,
+            scale: viewport.scale,
+        });
+        if (next === open)
+            return;
+        open = next;
+        if (open)
+            document.documentElement.dataset.keyboardOpen = '';
+        else
+            delete document.documentElement.dataset.keyboardOpen;
+        onChange(open);
+        const active = document.activeElement;
+        if (open && active instanceof HTMLElement && isEditableTarget(active)) {
+            active.scrollIntoView({ block: 'center' });
+        }
+    }
+    viewport.addEventListener('resize', sync);
+    return () => {
+        viewport.removeEventListener('resize', sync);
+        delete document.documentElement.dataset.keyboardOpen;
+    };
+}
+/**
+ * Report whether `container` holds a form action bar
+ * (`[data-form-action-bar]`), now and whenever its subtree changes.
+ */
+export function watchFormActionBar(container, onChange) {
+    let present = Boolean(container.querySelector(FORM_ACTION_BAR_SELECTOR));
+    onChange(present);
+    if (typeof MutationObserver === 'undefined')
+        return () => { };
+    const observer = new MutationObserver(() => {
+        const next = Boolean(container.querySelector(FORM_ACTION_BAR_SELECTOR));
+        if (next === present)
+            return;
+        present = next;
+        onChange(present);
+    });
+    observer.observe(container, { childList: true, subtree: true });
+    return () => observer.disconnect();
+}

package/dist/components/workspace/admin-shell/mobile-shell.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Pure logic behind AdminShell's phone chrome: the hide-on-scroll state
+ * machine, the on-screen keyboard heuristic, the phone top-bar model, and the
+ * bottom-bar mode. DOM-free and SSR-safe so it can be unit tested; the DOM
+ * wiring lives in `./mobile-shell-dom.ts`.
+ */
+import type { Component, ComponentType, SvelteComponent } from 'svelte';
+import type { ShellViewport } from './types.js';
+/** Classify a viewport from the phone and desktop media-query matches. */
+export declare function viewportFor(matches: {
+    phone: boolean;
+    desktop: boolean;
+}): ShellViewport;
+/** Tuning for {@link ScrollChrome}. */
+export interface ScrollChromeOptions {
+    /** Always show the chrome within this many px of the top (default 56). */
+    revealWithin?: number;
+    /** Downward travel in px before the chrome hides (default 12). */
+    hideAfter?: number;
+    /** Upward travel in px before it comes back (default 4, "first scroll up"). */
+    showAfter?: number;
+}
+/** One scroll position fed to {@link ScrollChrome.update}. */
+export interface ScrollSample {
+    /** Current scrollTop. */
+    y: number;
+    /** Largest reachable scrollTop, to ignore iOS overscroll bounce. */
+    maxY?: number;
+    /** Keep the chrome shown (a banner is visible, a drawer is open, …). */
+    pinned?: boolean;
+}
+/**
+ * Hide-on-scroll state machine for the phone top bar (and anything that
+ * slides with it). Feed it every scroll position; read `hidden`. Travel
+ * accumulates in one direction and resets when the direction reverses.
+ */
+export declare class ScrollChrome {
+    #private;
+    hidden: boolean;
+    constructor(options?: ScrollChromeOptions);
+    /** Feed a scroll sample; returns whether the chrome is now hidden. */
+    update(sample: ScrollSample): boolean;
+    /** Show the chrome and forget the scroll history (e.g. after navigating). */
+    reset(): void;
+}
+/**
+ * `visualViewport` heuristic: the keyboard is open when the visible viewport
+ * is much shorter than the layout viewport. `scale` undoes pinch zoom, which
+ * also shrinks `visualViewport.height`.
+ */
+export declare function keyboardLikelyOpen(input: {
+    layoutHeight: number;
+    visualHeight: number;
+    scale?: number;
+    threshold?: number;
+}): boolean;
+/** A nav entry as far as path matching is concerned. */
+export interface ShellNavPathItem {
+    href: string;
+    exact?: boolean;
+    children?: ShellNavPathItem[];
+}
+/** Drop trailing slashes (`/` stays `/`). */
+export declare function normalizeShellPath(path: string): string;
+/** Whether `path` is the item's page or (unless `exact`) below it. */
+export declare function shellNavItemMatches(item: ShellNavPathItem, path: string): boolean;
+/** The chain of nav items from the top level down to the one matching `path`. */
+export declare function findShellNavTrail<T extends ShellNavPathItem>(items: T[], path: string): T[];
+/** One ancestor of the current page: a breadcrumb and a possible back target. */
+export interface ShellCrumb {
+    label: string;
+    href: string;
+}
+/** Input for {@link shellPageTrailFor}. */
+export interface ShellPageTrailInput<T extends ShellNavPathItem & {
+    label: string;
+}> {
+    /** Current pathname. */
+    path: string;
+    /** The workspace home (overview) page. */
+    homeHref: string;
+    /** Workspace name: the first ancestor of every non-home page. */
+    homeTitle: string;
+    /** The workspace nav. */
+    navItems: T[];
+    /**
+     * Ancestors deeper than the nav knows (an article above its video, a
+     * council above its meeting), nearest last. They follow the nav trail.
+     */
+    parents?: readonly ShellCrumb[] | null;
+}
+/** Where a page sits: a section home, or a page with ancestors. */
+export interface ShellPageTrail {
+    /** The home page or a top-level nav page (and no page-given parents). */
+    sectionHome: boolean;
+    /** Ancestors only, never the current page; empty on section homes. */
+    crumbs: ShellCrumb[];
+    /** The nav item for the current page itself, if it is one. */
+    current: {
+        label: string;
+        href: string;
+    } | null;
+}
+/**
+ * The single source for a page's place in the workspace: breadcrumbs on
+ * wider screens and the phone top bar's back target both come from here.
+ *
+ * Section homes (the home page and top-level nav pages) have no ancestors.
+ * Anything else lists the workspace home, the nav items above it (a nested
+ * nav page's parent item counts, even when its URL is not below it), then the
+ * page-given `parents`. The current page is never a crumb.
+ */
+export declare function shellPageTrailFor<T extends ShellNavPathItem & {
+    label: string;
+}>(input: ShellPageTrailInput<T>): ShellPageTrail;
+/**
+ * What the phone top bar shows: the workspace name on section home pages, or
+ * a back arrow (to the parent, never `history.back()`) plus the page's
+ * title on every other page.
+ */
+export type PhoneTopBarModel = {
+    kind: 'home';
+    title: string;
+} | {
+    kind: 'detail';
+    title: string;
+    backHref: string;
+    backLabel: string;
+};
+/** Input for {@link phoneTopBarFor}. */
+export interface PhoneTopBarInput<T extends ShellNavPathItem & {
+    label: string;
+}> extends ShellPageTrailInput<T> {
+    /** Title the page provided (article headline, person's name, …). */
+    pageTitle?: string | null;
+    /**
+     * Explicit back target. Prefer `parents` (the same ancestors the page's
+     * breadcrumbs show); this overrides the last one.
+     */
+    backHref?: string | null;
+    /** Back label used with an explicit `backHref` (default "Back"). */
+    backLabel?: string;
+}
+/**
+ * Section homes (see {@link shellPageTrailFor}) show the workspace name.
+ * Every other page shows a back arrow to its nearest ancestor (the last
+ * breadcrumb) and the page's title.
+ */
+export declare function phoneTopBarFor<T extends ShellNavPathItem & {
+    label: string;
+}>(input: PhoneTopBarInput<T>): PhoneTopBarModel;
+/**
+ * What sits at the bottom of a phone screen: the nav bar, a form's own
+ * action bar (which replaces it), or nothing while the keyboard is open.
+ */
+export type BottomBarMode = 'nav' | 'form' | 'none';
+/** Decide the {@link BottomBarMode}. */
+export declare function bottomBarMode(input: {
+    formActions: boolean;
+    keyboardOpen: boolean;
+}): BottomBarMode;
+/** Selector a form's action row carries to replace the phone bottom bar. */
+export declare const FORM_ACTION_BAR_SELECTOR = "[data-form-action-bar]";
+/**
+ * An icon component: a Svelte 5 function component or a legacy class
+ * component (e.g. lucide-svelte icons).
+ */
+export type ShellIcon = Component<{
+    size?: number | string;
+}> | ComponentType<SvelteComponent<{
+    size?: number | string;
+}>>;
+/** One phone bottom bar entry: a link (`href`; `onclick` also runs) or a button. */
+export interface PhoneBottomBarItem {
+    id: string;
+    label: string;
+    icon: ShellIcon;
+    href?: string;
+    onclick?: () => void;
+    active?: boolean;
+    /** Count badge (hidden at 0). */
+    badge?: number;
+    /** Small dot, e.g. an unread reply. */
+    dot?: boolean;
+    /** Accessible description of the dot (default "new"). */
+    dotLabel?: string;
+    /** For items that open a panel: its expanded state and id. */
+    expanded?: boolean;
+    controls?: string;
+}
+//# sourceMappingURL=mobile-shell.d.ts.map

package/dist/components/workspace/admin-shell/mobile-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobile-shell.d.ts","sourceRoot":"","sources":["../../../../src/components/workspace/admin-shell/mobile-shell.ts"],"names":[],"mappings":"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"}

package/dist/components/workspace/admin-shell/mobile-shell.js

@@ -0,0 +1,165 @@
+/** Classify a viewport from the phone and desktop media-query matches. */
+export function viewportFor(matches) {
+    if (matches.phone)
+        return 'phone';
+    return matches.desktop ? 'desktop' : 'tablet';
+}
+/**
+ * Hide-on-scroll state machine for the phone top bar (and anything that
+ * slides with it). Feed it every scroll position; read `hidden`. Travel
+ * accumulates in one direction and resets when the direction reverses.
+ */
+export class ScrollChrome {
+    hidden = false;
+    #lastY = 0;
+    #travel = 0;
+    #revealWithin;
+    #hideAfter;
+    #showAfter;
+    constructor(options = {}) {
+        this.#revealWithin = options.revealWithin ?? 56;
+        this.#hideAfter = options.hideAfter ?? 12;
+        this.#showAfter = options.showAfter ?? 4;
+    }
+    /** Feed a scroll sample; returns whether the chrome is now hidden. */
+    update(sample) {
+        const max = sample.maxY ?? Number.POSITIVE_INFINITY;
+        const y = Math.min(Math.max(sample.y, 0), Math.max(max, 0));
+        if (sample.pinned || y <= this.#revealWithin) {
+            this.hidden = false;
+            this.#lastY = y;
+            this.#travel = 0;
+            return this.hidden;
+        }
+        const delta = y - this.#lastY;
+        this.#lastY = y;
+        if (delta === 0)
+            return this.hidden;
+        this.#travel =
+            Math.sign(delta) === Math.sign(this.#travel)
+                ? this.#travel + delta
+                : delta;
+        if (this.#travel >= this.#hideAfter)
+            this.hidden = true;
+        else if (-this.#travel >= this.#showAfter)
+            this.hidden = false;
+        return this.hidden;
+    }
+    /** Show the chrome and forget the scroll history (e.g. after navigating). */
+    reset() {
+        this.hidden = false;
+        this.#lastY = 0;
+        this.#travel = 0;
+    }
+}
+// ---- On-screen keyboard ---------------------------------------------------
+/**
+ * `visualViewport` heuristic: the keyboard is open when the visible viewport
+ * is much shorter than the layout viewport. `scale` undoes pinch zoom, which
+ * also shrinks `visualViewport.height`.
+ */
+export function keyboardLikelyOpen(input) {
+    const visible = input.visualHeight * (input.scale ?? 1);
+    return input.layoutHeight - visible > (input.threshold ?? 150);
+}
+/** Drop trailing slashes (`/` stays `/`). */
+export function normalizeShellPath(path) {
+    return path.replace(/\/+$/, '') || '/';
+}
+/** Whether `path` is the item's page or (unless `exact`) below it. */
+export function shellNavItemMatches(item, path) {
+    const href = normalizeShellPath(item.href);
+    const current = normalizeShellPath(path);
+    if (href === current)
+        return true;
+    if (item.exact || href === '/')
+        return false;
+    return current.startsWith(`${href}/`);
+}
+/** The chain of nav items from the top level down to the one matching `path`. */
+export function findShellNavTrail(items, path) {
+    for (const item of items) {
+        const childTrail = item.children
+            ? findShellNavTrail(item.children, path)
+            : [];
+        if (childTrail.length > 0)
+            return [item, ...childTrail];
+        if (shellNavItemMatches(item, path))
+            return [item];
+    }
+    return [];
+}
+/**
+ * The single source for a page's place in the workspace: breadcrumbs on
+ * wider screens and the phone top bar's back target both come from here.
+ *
+ * Section homes (the home page and top-level nav pages) have no ancestors.
+ * Anything else lists the workspace home, the nav items above it (a nested
+ * nav page's parent item counts, even when its URL is not below it), then the
+ * page-given `parents`. The current page is never a crumb.
+ */
+export function shellPageTrailFor(input) {
+    const path = normalizeShellPath(input.path);
+    const home = normalizeShellPath(input.homeHref);
+    const parents = [...(input.parents ?? [])];
+    const trail = findShellNavTrail(input.navItems, path);
+    const last = trail.at(-1);
+    const currentItem = last && normalizeShellPath(last.href) === path ? last : null;
+    const current = currentItem
+        ? { label: currentItem.label, href: currentItem.href }
+        : null;
+    const topLevelHome = path === home ||
+        input.navItems.some((item) => normalizeShellPath(item.href) === path);
+    if (topLevelHome && parents.length === 0) {
+        return { sectionHome: true, crumbs: [], current };
+    }
+    const crumbs = [
+        { label: input.homeTitle, href: input.homeHref },
+    ];
+    for (const item of trail) {
+        if (item === currentItem)
+            continue;
+        const href = normalizeShellPath(item.href);
+        if (href === home || href === path)
+            continue;
+        crumbs.push({ label: item.label, href: item.href });
+    }
+    for (const parent of parents) {
+        const href = normalizeShellPath(parent.href);
+        if (href === path)
+            continue;
+        // A page that names an ancestor the nav already supplied (a form under
+        // its list's nav item) must not show that crumb twice.
+        if (crumbs.some((crumb) => normalizeShellPath(crumb.href) === href))
+            continue;
+        crumbs.push({ label: parent.label, href: parent.href });
+    }
+    return { sectionHome: false, crumbs, current };
+}
+/**
+ * Section homes (see {@link shellPageTrailFor}) show the workspace name.
+ * Every other page shows a back arrow to its nearest ancestor (the last
+ * breadcrumb) and the page's title.
+ */
+export function phoneTopBarFor(input) {
+    const trail = shellPageTrailFor(input);
+    if (trail.sectionHome && !input.backHref) {
+        return { kind: 'home', title: input.homeTitle };
+    }
+    const parent = trail.crumbs.at(-1) ?? {
+        label: input.homeTitle,
+        href: input.homeHref,
+    };
+    const backHref = input.backHref ?? parent.href;
+    const backLabel = input.backHref ? (input.backLabel ?? 'Back') : parent.label;
+    const title = input.pageTitle?.trim() || trail.current?.label || parent.label;
+    return { kind: 'detail', title, backHref, backLabel };
+}
+/** Decide the {@link BottomBarMode}. */
+export function bottomBarMode(input) {
+    if (input.keyboardOpen)
+        return 'none';
+    return input.formActions ? 'form' : 'nav';
+}
+/** Selector a form's action row carries to replace the phone bottom bar. */
+export const FORM_ACTION_BAR_SELECTOR = '[data-form-action-bar]';

package/dist/components/workspace/admin-shell/settings.d.ts

@@ -1,7 +1,32 @@
-import type { PanelEdge, PanelState, ResolvedShellConfig, ShellHotkeyBinding, ShellPanelConfig, ShellPanelDefaults, ShellSettingsAdapter, ShellSettingsDelta } from './types.js';
+import type { PanelEdge, PanelState, ResolvedShellConfig, ShellHotkeyBinding, ShellPanelConfig, ShellPanelDefaults, ShellPanelResize, ShellSettingsAdapter, ShellSettingsDelta, ShellViewport } from './types.js';
 export declare const DEFAULT_SHELL_KEYMAP: Record<PanelEdge, ShellHotkeyBinding>;
 export declare function resolveShellConfig(appDefaults?: ShellPanelDefaults): ResolvedShellConfig;
-export declare function resolveInitialPanelState(edge: PanelEdge, config: ShellPanelConfig, settings?: ShellSettingsDelta): PanelState;
+/**
+ * An edge's state: hidden edges stay hidden; otherwise the user's setting,
+ * then the edge's default for `viewport` (when it declares
+ * `viewportDefaults`), then its configured initial state.
+ */
+export declare function resolveInitialPanelState(edge: PanelEdge, config: ShellPanelConfig, settings?: ShellSettingsDelta, viewport?: ShellViewport): PanelState;
+/** Default limits for a resizable side edge (CSS px). */
+export declare const DEFAULT_SHELL_PANEL_RESIZE: Required<ShellPanelResize>;
+/**
+ * Resolved resize limits for an edge, or `null` when it is not resizable.
+ * Only `left` and `right` edges resize.
+ */
+export declare function resolvePanelResize(edge: PanelEdge, config: ShellPanelConfig): Required<ShellPanelResize> | null;
+/** Clamp a requested width into an edge's resize limits (rounded to px). */
+export declare function clampPanelSize(size: number, limits: Required<ShellPanelResize>): number;
+/**
+ * Whether the settings adapter stores an edge's `state` (open/closed) or
+ * `size`. Edges with `viewportDefaults` never store their state: it follows
+ * the viewport class.
+ */
+export declare function panelPersists(config: ShellPanelConfig, what: 'state' | 'size'): boolean;
+/**
+ * Drop the panel states and sizes the config says not to store, so they are
+ * neither written by nor read back from a settings adapter.
+ */
+export declare function stripUnpersistedSettings(delta: ShellSettingsDelta, config: ResolvedShellConfig): ShellSettingsDelta;
 export declare function resolveHotkey(edge: PanelEdge, config: ShellPanelConfig, settings?: ShellSettingsDelta): ShellHotkeyBinding | null;
 export declare function mergeShellSettingsDelta(base: ShellSettingsDelta, next: ShellSettingsDelta): ShellSettingsDelta;
 export declare function pruneShellSettingsDelta(delta: ShellSettingsDelta): ShellSettingsDelta;

package/dist/components/workspace/admin-shell/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../../src/components/workspace/admin-shell/settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,SAAS,EAAE,kBAAkB,CAKtE,CAAC;AA6CF,wBAAgB,kBAAkB,CAChC,WAAW,GAAE,kBAAuB,GACnC,mBAAmB,CA2BrB;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,gBAAgB,EACxB,QAAQ,GAAE,kBAAuB,GAChC,UAAU,CAGZ;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,gBAAgB,EACxB,QAAQ,GAAE,kBAAuB,GAChC,kBAAkB,GAAG,IAAI,CAM3B;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,kBAAkB,GACvB,kBAAkB,CAapB;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,CAepB;AAED,qBAAa,gCAAiC,YAAW,oBAAoB;IAC/D,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,MAAM;IAExC,IAAI,IAAI,kBAAkB,GAAG,IAAI;IAWjC,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;CAOvC"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../../src/components/workspace/admin-shell/settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACd,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,SAAS,EAAE,kBAAkB,CAKtE,CAAC;AA6CF,wBAAgB,kBAAkB,CAChC,WAAW,GAAE,kBAAuB,GACnC,mBAAmB,CA2BrB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,gBAAgB,EACxB,QAAQ,GAAE,kBAAuB,EACjC,QAAQ,CAAC,EAAE,aAAa,GACvB,UAAU,CAOZ;AAED,yDAAyD;AACzD,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,gBAAgB,CAIjE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,gBAAgB,GACvB,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAUnC;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GACjC,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,OAAO,GAAG,MAAM,GACrB,OAAO,CAKT;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,mBAAmB,GAC1B,kBAAkB,CAqBpB;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,gBAAgB,EACxB,QAAQ,GAAE,kBAAuB,GAChC,kBAAkB,GAAG,IAAI,CAM3B;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,kBAAkB,GACvB,kBAAkB,CAiBpB;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,CAuBpB;AAED,qBAAa,gCAAiC,YAAW,oBAAoB;IAC/D,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,MAAM;IAExC,IAAI,IAAI,kBAAkB,GAAG,IAAI;IAWjC,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;CAOvC"}

package/dist/components/workspace/admin-shell/settings.js

@@ -72,10 +72,84 @@ export function resolveShellConfig(appDefaults = {}) {
     }));
     return { panels };
 }
-export function resolveInitialPanelState(edge, config, settings = {}) {
+/**
+ * An edge's state: hidden edges stay hidden; otherwise the user's setting,
+ * then the edge's default for `viewport` (when it declares
+ * `viewportDefaults`), then its configured initial state.
+ */
+export function resolveInitialPanelState(edge, config, settings = {}, viewport) {
     if (config.initial === 'hidden')
         return 'hidden';
-    return settings.panels?.[edge] ?? config.initial;
+    return (settings.panels?.[edge] ??
+        (viewport ? config.viewportDefaults?.[viewport] : undefined) ??
+        config.initial);
+}
+/** Default limits for a resizable side edge (CSS px). */
+export const DEFAULT_SHELL_PANEL_RESIZE = {
+    min: 240,
+    max: 720,
+    step: 16,
+};
+/**
+ * Resolved resize limits for an edge, or `null` when it is not resizable.
+ * Only `left` and `right` edges resize.
+ */
+export function resolvePanelResize(edge, config) {
+    if (edge !== 'left' && edge !== 'right')
+        return null;
+    if (!config.resizable || config.initial === 'hidden')
+        return null;
+    const limits = config.resizable === true ? {} : config.resizable;
+    const min = Math.max(0, limits.min ?? DEFAULT_SHELL_PANEL_RESIZE.min);
+    return {
+        min,
+        max: Math.max(min, limits.max ?? DEFAULT_SHELL_PANEL_RESIZE.max),
+        step: Math.max(1, limits.step ?? DEFAULT_SHELL_PANEL_RESIZE.step),
+    };
+}
+/** Clamp a requested width into an edge's resize limits (rounded to px). */
+export function clampPanelSize(size, limits) {
+    return Math.round(Math.min(limits.max, Math.max(limits.min, size)));
+}
+/**
+ * Whether the settings adapter stores an edge's `state` (open/closed) or
+ * `size`. Edges with `viewportDefaults` never store their state: it follows
+ * the viewport class.
+ */
+export function panelPersists(config, what) {
+    if (what === 'state' && config.viewportDefaults)
+        return false;
+    const persist = config.persist ?? true;
+    if (typeof persist === 'boolean')
+        return persist;
+    return persist[what] ?? true;
+}
+/**
+ * Drop the panel states and sizes the config says not to store, so they are
+ * neither written by nor read back from a settings adapter.
+ */
+export function stripUnpersistedSettings(delta, config) {
+    const stripped = { ...delta };
+    for (const key of ['panels', 'sizes']) {
+        const values = delta[key];
+        if (!values)
+            continue;
+        const kept = {};
+        for (const edge of PANEL_EDGES) {
+            if (!(edge in values))
+                continue;
+            if (panelPersists(config.panels[edge], key === 'panels' ? 'state' : 'size')) {
+                kept[edge] = values[edge];
+            }
+        }
+        if (Object.keys(kept).length > 0) {
+            stripped[key] = kept;
+        }
+        else {
+            delete stripped[key];
+        }
+    }
+    return stripped;
 }
 export function resolveHotkey(edge, config, settings = {}) {
     if (config.initial === 'hidden')
@@ -95,6 +169,9 @@ export function mergeShellSettingsDelta(base, next) {
         panels: base.panels || next.panels
             ? { ...(base.panels ?? {}), ...(next.panels ?? {}) }
             : undefined,
+        sizes: base.sizes || next.sizes
+            ? { ...(base.sizes ?? {}), ...(next.sizes ?? {}) }
+            : undefined,
     };
 }
 export function pruneShellSettingsDelta(delta) {
@@ -111,6 +188,11 @@ export function pruneShellSettingsDelta(delta) {
     if (delta.panels && Object.keys(delta.panels).length > 0) {
         pruned.panels = delta.panels;
     }
+    if (delta.sizes) {
+        const sizes = Object.fromEntries(Object.entries(delta.sizes).filter(([, size]) => typeof size === 'number' && Number.isFinite(size)));
+        if (Object.keys(sizes).length > 0)
+            pruned.sizes = sizes;
+    }
     return pruned;
 }
 export class LocalStorageShellSettingsAdapter {