@happyvertical/smrt-svelte 0.55.0 → 0.55.2

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

@@ -0,0 +1,120 @@
+/**
+ * User-customizable shell layout: a small, versioned, JSON-serializable delta
+ * applied over the navigation and panel defaults the host generates.
+ *
+ * This module is pure (no Svelte, no DOM) so a host can validate, store,
+ * export, or apply a layout anywhere, including on the server. It is also
+ * published as `@happyvertical/smrt-svelte/workspace/layout`.
+ *
+ * Ids: sections are identified by `ShellNavGroup.id ?? heading`, items by
+ * `ShellNavItem.id ?? href`. Sections and items share one id namespace (the
+ * `hidden` list holds both), so keep them unique; later duplicates get a
+ * `#2`, `#3`, ... suffix. The flat `nav` items form an implicit first
+ * section, {@link SHELL_NAV_ROOT_SECTION_ID}, which always renders first and
+ * cannot be reordered or hidden as a whole.
+ */
+import type { PanelEdge, ShellNavGroup, ShellNavItem, ShellPanelDefaults } from './types.js';
+/** The only layout format version this package reads and writes. */
+export declare const SHELL_LAYOUT_VERSION: 1;
+/** Section id of the flat `nav` items rendered above all groups. */
+export declare const SHELL_NAV_ROOT_SECTION_ID = "@root";
+/** A user's choice for one edge panel. */
+export interface ShellLayoutPanel {
+    /** `false` hides the edge; absent or `true` keeps it as configured. */
+    visible?: boolean;
+    /** The state the edge starts in. */
+    initial?: 'collapsed' | 'expanded';
+}
+/**
+ * A user's customization of the shell, stored as a sparse delta over what the
+ * host generates. Every field is optional; unknown ids are ignored.
+ */
+export interface ShellLayout {
+    version: 1;
+    /** Section ids in display order. Sections not listed keep their slot. */
+    sectionOrder?: string[];
+    /** Per section id, item ids in display order. */
+    itemOrder?: Record<string, string[]>;
+    /** Ids of hidden sections and items. */
+    hidden?: string[];
+    /** Item id to the id of the section it was moved into. */
+    moved?: Record<string, string>;
+    /** Per edge panel overrides. */
+    panels?: Partial<Record<PanelEdge, ShellLayoutPanel>>;
+}
+/** An item as the layout sees it. */
+export interface ShellNavModelItem {
+    id: string;
+    item: ShellNavItem;
+    /** The section the host put the item in. */
+    nativeSectionId: string;
+    /** The section it is displayed in (differs when moved). */
+    sectionId: string;
+    /** Hidden by its own id. */
+    hidden: boolean;
+}
+/** A section as the layout sees it. */
+export interface ShellNavModelSection {
+    id: string;
+    /** `null` for the implicit root section of flat `nav` items. */
+    group: ShellNavGroup | null;
+    heading: string | null;
+    hidden: boolean;
+    /** Items in display order, including hidden ones. */
+    items: ShellNavModelItem[];
+}
+/** Result of {@link applyShellLayout}. */
+export interface AppliedShellLayout {
+    nav: ShellNavItem[];
+    groups: ShellNavGroup[];
+    panels: ShellPanelDefaults;
+}
+export declare function createShellLayout(): ShellLayout;
+/** A layout with no customization (nothing to apply). */
+export declare function isShellLayoutEmpty(layout: ShellLayout | null | undefined): boolean;
+/**
+ * Read an untrusted value (stored JSON, an imported blueprint) as a layout.
+ * Never throws: anything unreadable, including a version this package does not
+ * know, yields an empty layout, and unknown or malformed fields are dropped.
+ */
+export declare function normalizeShellLayout(input: unknown): ShellLayout;
+export declare function shellNavGroupId(group: ShellNavGroup): string;
+export declare function shellNavItemId(item: ShellNavItem): string;
+/**
+ * The navigation as the layout sees it: every section and item (hidden ones
+ * flagged, not removed) in display order. An editor renders this; the shell
+ * renders {@link applyShellLayout}'s filtered result.
+ */
+export declare function resolveShellNavModel(nav?: readonly ShellNavItem[], groups?: readonly ShellNavGroup[], layout?: ShellLayout | null): ShellNavModelSection[];
+/** The state an edge starts in once a layout override is applied. */
+export declare function applyShellLayoutPanel(base: ShellPanelDefaults[PanelEdge], panel: ShellLayoutPanel | undefined): ShellPanelDefaults[PanelEdge];
+/**
+ * Apply a layout over host-generated navigation and panel defaults.
+ *
+ * Pure and total: ids the host no longer has are ignored, items and sections
+ * the layout does not mention keep their default positions, and an empty or
+ * missing layout returns the inputs unchanged. Sections the layout empties
+ * (every item hidden or moved away) are dropped from `groups`.
+ */
+export declare function applyShellLayout(nav: ShellNavItem[], groups: ShellNavGroup[], panels: ShellPanelDefaults | undefined, layout: ShellLayout | null | undefined): AppliedShellLayout;
+/**
+ * Move a group section to `toIndex` among the groups (the root section is not
+ * counted). Returns the layout unchanged when `sectionId` is not a group.
+ */
+export declare function moveShellSection(nav: readonly ShellNavItem[], groups: readonly ShellNavGroup[], layout: ShellLayout | null | undefined, sectionId: string, toIndex: number): ShellLayout;
+/**
+ * Move an item into `toSectionId` (a group or the root section) at `toIndex`
+ * among that section's items, hidden ones included. `toIndex` defaults to the
+ * end. Returns the layout unchanged when either id is unknown.
+ */
+export declare function moveShellItem(nav: readonly ShellNavItem[], groups: readonly ShellNavGroup[], layout: ShellLayout | null | undefined, itemId: string, toSectionId: string, toIndex?: number): ShellLayout;
+/** Hide a section or item. Unknown ids and the root section are ignored. */
+export declare function hideShellEntry(nav: readonly ShellNavItem[], groups: readonly ShellNavGroup[], layout: ShellLayout | null | undefined, id: string): ShellLayout;
+/** Show a hidden section or item again. */
+export declare function showShellEntry(layout: ShellLayout | null | undefined, id: string): ShellLayout;
+/**
+ * Set an edge panel's `visible` and/or `initial`. Values equal to the host's
+ * defaults (`defaults`, when given) are dropped to keep the layout sparse.
+ */
+export declare function setShellLayoutPanel(layout: ShellLayout | null | undefined, edge: PanelEdge, patch: ShellLayoutPanel, defaults?: ShellPanelDefaults): ShellLayout;
+//# sourceMappingURL=layout.d.ts.map

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

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

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

@@ -0,0 +1,402 @@
+/** The only layout format version this package reads and writes. */
+export const SHELL_LAYOUT_VERSION = 1;
+/** Section id of the flat `nav` items rendered above all groups. */
+export const SHELL_NAV_ROOT_SECTION_ID = '@root';
+const EDGES = ['top', 'left', 'right', 'bottom'];
+export function createShellLayout() {
+    return { version: SHELL_LAYOUT_VERSION };
+}
+/** A layout with no customization (nothing to apply). */
+export function isShellLayoutEmpty(layout) {
+    if (!layout)
+        return true;
+    return (!layout.sectionOrder?.length &&
+        !hasKeys(layout.itemOrder) &&
+        !layout.hidden?.length &&
+        !hasKeys(layout.moved) &&
+        !hasKeys(layout.panels));
+}
+function hasKeys(value) {
+    return (typeof value === 'object' && value !== null && Object.keys(value).length > 0);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry === 'string' && entry !== '')
+            seen.add(entry);
+    }
+    return seen.size > 0 ? [...seen] : undefined;
+}
+/**
+ * Read an untrusted value (stored JSON, an imported blueprint) as a layout.
+ * Never throws: anything unreadable, including a version this package does not
+ * know, yields an empty layout, and unknown or malformed fields are dropped.
+ */
+export function normalizeShellLayout(input) {
+    const layout = createShellLayout();
+    if (!isRecord(input) || input.version !== SHELL_LAYOUT_VERSION)
+        return layout;
+    const sectionOrder = stringList(input.sectionOrder);
+    if (sectionOrder)
+        layout.sectionOrder = sectionOrder;
+    if (isRecord(input.itemOrder)) {
+        const itemOrder = {};
+        for (const [section, ids] of Object.entries(input.itemOrder)) {
+            const list = stringList(ids);
+            if (list)
+                itemOrder[section] = list;
+        }
+        if (hasKeys(itemOrder))
+            layout.itemOrder = itemOrder;
+    }
+    const hidden = stringList(input.hidden);
+    if (hidden)
+        layout.hidden = hidden;
+    if (isRecord(input.moved)) {
+        const moved = {};
+        for (const [id, section] of Object.entries(input.moved)) {
+            if (typeof section === 'string' && section !== '')
+                moved[id] = section;
+        }
+        if (hasKeys(moved))
+            layout.moved = moved;
+    }
+    if (isRecord(input.panels)) {
+        const panels = {};
+        for (const edge of EDGES) {
+            const raw = input.panels[edge];
+            if (!isRecord(raw))
+                continue;
+            const panel = {};
+            if (typeof raw.visible === 'boolean')
+                panel.visible = raw.visible;
+            if (raw.initial === 'collapsed' || raw.initial === 'expanded') {
+                panel.initial = raw.initial;
+            }
+            if (hasKeys(panel))
+                panels[edge] = panel;
+        }
+        if (hasKeys(panels))
+            layout.panels = panels;
+    }
+    return layout;
+}
+export function shellNavGroupId(group) {
+    return group.id ?? group.heading;
+}
+export function shellNavItemId(item) {
+    return item.id ?? item.href;
+}
+/**
+ * Keep every listed id that is present, in the listed order, in the slots the
+ * listed ids already occupy. Ids the list does not mention (for example new
+ * ones the host added later) stay exactly where the defaults put them.
+ */
+function mergeOrder(defaults, preferred) {
+    if (!preferred || preferred.length === 0)
+        return [...defaults];
+    const present = new Set(defaults);
+    const listed = [];
+    const listedSet = new Set();
+    for (const id of preferred) {
+        if (present.has(id) && !listedSet.has(id)) {
+            listedSet.add(id);
+            listed.push(id);
+        }
+    }
+    if (listed.length === 0)
+        return [...defaults];
+    let next = 0;
+    return defaults.map((id) => (listedSet.has(id) ? listed[next++] : id));
+}
+/**
+ * The navigation as the layout sees it: every section and item (hidden ones
+ * flagged, not removed) in display order. An editor renders this; the shell
+ * renders {@link applyShellLayout}'s filtered result.
+ */
+export function resolveShellNavModel(nav = [], groups = [], layout) {
+    const used = new Set([SHELL_NAV_ROOT_SECTION_ID]);
+    const unique = (id) => {
+        let candidate = id;
+        for (let n = 2; used.has(candidate); n += 1)
+            candidate = `${id}#${n}`;
+        used.add(candidate);
+        return candidate;
+    };
+    const natives = [
+        {
+            id: SHELL_NAV_ROOT_SECTION_ID,
+            group: null,
+            items: nav.map((item) => ({ id: unique(shellNavItemId(item)), item })),
+        },
+    ];
+    for (const group of groups) {
+        const id = unique(shellNavGroupId(group));
+        natives.push({
+            id,
+            group,
+            items: group.items.map((item) => ({
+                id: unique(shellNavItemId(item)),
+                item,
+            })),
+        });
+    }
+    const hidden = new Set(stringList(layout?.hidden) ?? []);
+    const moved = isRecord(layout?.moved)
+        ? layout?.moved
+        : {};
+    const sectionIds = new Set(natives.map((section) => section.id));
+    const itemIds = new Set(natives.flatMap((section) => section.items.map((entry) => entry.id)));
+    /** Where an item is displayed: its moved-to section when that exists. */
+    const displayedIn = (id, native) => {
+        const target = itemIds.has(id) ? moved[id] : undefined;
+        return typeof target === 'string' && sectionIds.has(target)
+            ? target
+            : native;
+    };
+    const groupSections = natives.slice(1).map((section) => section.id);
+    const orderedGroupIds = mergeOrder(groupSections, stringList(layout?.sectionOrder));
+    const byId = new Map(natives.map((section) => [section.id, section]));
+    const orderedSections = [
+        natives[0],
+        ...orderedGroupIds.map((id) => byId.get(id)),
+    ];
+    const itemOrder = isRecord(layout?.itemOrder)
+        ? layout?.itemOrder
+        : {};
+    return orderedSections.map((section) => {
+        const defaults = [];
+        for (const native of natives) {
+            for (const entry of native.items) {
+                if (displayedIn(entry.id, native.id) !== section.id)
+                    continue;
+                defaults.push({
+                    id: entry.id,
+                    item: entry.item,
+                    nativeSectionId: native.id,
+                    sectionId: section.id,
+                    hidden: hidden.has(entry.id),
+                });
+            }
+        }
+        // Items the host placed here keep their order; moved-in items follow.
+        defaults.sort((a, b) => Number(a.nativeSectionId !== section.id) -
+            Number(b.nativeSectionId !== section.id));
+        const byItem = new Map(defaults.map((entry) => [entry.id, entry]));
+        const order = mergeOrder(defaults.map((entry) => entry.id), stringList(itemOrder[section.id]));
+        return {
+            id: section.id,
+            group: section.group,
+            heading: section.group ? section.group.heading : null,
+            hidden: section.group ? hidden.has(section.id) : false,
+            items: order.map((id) => byItem.get(id)),
+        };
+    });
+}
+/** The state an edge starts in once a layout override is applied. */
+export function applyShellLayoutPanel(base, panel) {
+    if (!panel)
+        return base;
+    // `false` and `initial: 'hidden'` mean the host has no such panel; a
+    // layout can hide a panel but never conjures one the host removed.
+    if (base === false || base?.initial === 'hidden')
+        return base;
+    if (panel.visible === false)
+        return false;
+    if (panel.initial === 'collapsed' || panel.initial === 'expanded') {
+        return { ...base, initial: panel.initial };
+    }
+    return base;
+}
+/**
+ * Apply a layout over host-generated navigation and panel defaults.
+ *
+ * Pure and total: ids the host no longer has are ignored, items and sections
+ * the layout does not mention keep their default positions, and an empty or
+ * missing layout returns the inputs unchanged. Sections the layout empties
+ * (every item hidden or moved away) are dropped from `groups`.
+ */
+export function applyShellLayout(nav, groups, panels, layout) {
+    const basePanels = panels ?? {};
+    if (isShellLayoutEmpty(layout)) {
+        return { nav, groups, panels: basePanels };
+    }
+    const model = resolveShellNavModel(nav, groups, layout);
+    const visible = (section) => section.hidden
+        ? []
+        : section.items.filter((entry) => !entry.hidden).map((e) => e.item);
+    const [root, ...sections] = model;
+    const nextGroups = [];
+    for (const section of sections) {
+        const items = visible(section);
+        const group = section.group;
+        if (section.hidden || (items.length === 0 && group.items.length > 0)) {
+            continue;
+        }
+        nextGroups.push({ ...group, items });
+    }
+    const nextPanels = { ...basePanels };
+    const overrides = isRecord(layout?.panels) ? layout?.panels : undefined;
+    for (const edge of EDGES) {
+        const override = overrides?.[edge];
+        if (!isRecord(override))
+            continue;
+        const next = applyShellLayoutPanel(basePanels[edge], override);
+        if (next !== undefined)
+            nextPanels[edge] = next;
+    }
+    return { nav: visible(root), groups: nextGroups, panels: nextPanels };
+}
+// Mutations. Each returns a new sparse layout and never mutates its input.
+function compact(layout) {
+    const next = { version: SHELL_LAYOUT_VERSION };
+    if (layout.sectionOrder?.length)
+        next.sectionOrder = layout.sectionOrder;
+    if (hasKeys(layout.itemOrder))
+        next.itemOrder = layout.itemOrder;
+    if (layout.hidden?.length)
+        next.hidden = layout.hidden;
+    if (hasKeys(layout.moved))
+        next.moved = layout.moved;
+    if (hasKeys(layout.panels))
+        next.panels = layout.panels;
+    return next;
+}
+function sameList(a, b) {
+    return a.length === b.length && a.every((value, i) => value === b[i]);
+}
+function clampIndex(index, max) {
+    if (!Number.isFinite(index))
+        return max;
+    return Math.max(0, Math.min(Math.trunc(index), max));
+}
+/**
+ * Move a group section to `toIndex` among the groups (the root section is not
+ * counted). Returns the layout unchanged when `sectionId` is not a group.
+ */
+export function moveShellSection(nav, groups, layout, sectionId, toIndex) {
+    const current = normalizeShellLayout(layout ?? createShellLayout());
+    const ids = resolveShellNavModel(nav, groups, current)
+        .slice(1)
+        .map((section) => section.id);
+    if (!ids.includes(sectionId))
+        return current;
+    const next = ids.filter((id) => id !== sectionId);
+    next.splice(clampIndex(toIndex, next.length), 0, sectionId);
+    const defaults = resolveShellNavModel(nav, groups)
+        .slice(1)
+        .map((section) => section.id);
+    const sectionOrder = sameList(next, defaults) ? undefined : next;
+    return compact({ ...current, sectionOrder });
+}
+/**
+ * Move an item into `toSectionId` (a group or the root section) at `toIndex`
+ * among that section's items, hidden ones included. `toIndex` defaults to the
+ * end. Returns the layout unchanged when either id is unknown.
+ */
+export function moveShellItem(nav, groups, layout, itemId, toSectionId, toIndex) {
+    const current = normalizeShellLayout(layout ?? createShellLayout());
+    const model = resolveShellNavModel(nav, groups, current);
+    const source = model.find((section) => section.items.some((entry) => entry.id === itemId));
+    const target = model.find((section) => section.id === toSectionId);
+    if (!source || !target)
+        return current;
+    const entry = source.items.find((candidate) => candidate.id === itemId);
+    if (!entry)
+        return current;
+    const lists = new Map(model.map((section) => [
+        section.id,
+        section.items.map((candidate) => candidate.id),
+    ]));
+    lists.set(source.id, (lists.get(source.id) ?? []).filter((id) => id !== itemId));
+    const targetList = [...(lists.get(target.id) ?? [])];
+    targetList.splice(clampIndex(toIndex ?? targetList.length, targetList.length), 0, itemId);
+    lists.set(target.id, targetList);
+    const moved = { ...(current.moved ?? {}) };
+    if (target.id === entry.nativeSectionId)
+        delete moved[itemId];
+    else
+        moved[itemId] = target.id;
+    // With `moved` settled, a section's default order is what an empty
+    // itemOrder would give; write an order only where it differs.
+    const settled = { ...current, moved };
+    const defaultModel = resolveShellNavModel(nav, groups, {
+        version: SHELL_LAYOUT_VERSION,
+        moved,
+        sectionOrder: current.sectionOrder,
+    });
+    const itemOrder = { ...(current.itemOrder ?? {}) };
+    for (const id of new Set([source.id, target.id])) {
+        const defaults = defaultModel
+            .find((section) => section.id === id)
+            ?.items.map((candidate) => candidate.id);
+        const list = lists.get(id) ?? [];
+        if (defaults && sameList(list, defaults))
+            delete itemOrder[id];
+        else
+            itemOrder[id] = list;
+    }
+    return compact({ ...settled, itemOrder });
+}
+/** Hide a section or item. Unknown ids and the root section are ignored. */
+export function hideShellEntry(nav, groups, layout, id) {
+    const current = normalizeShellLayout(layout ?? createShellLayout());
+    if (!isKnownEntry(nav, groups, id) || current.hidden?.includes(id)) {
+        return current;
+    }
+    return compact({ ...current, hidden: [...(current.hidden ?? []), id] });
+}
+/** Show a hidden section or item again. */
+export function showShellEntry(layout, id) {
+    const current = normalizeShellLayout(layout ?? createShellLayout());
+    if (!current.hidden?.includes(id))
+        return current;
+    return compact({
+        ...current,
+        hidden: current.hidden.filter((entry) => entry !== id),
+    });
+}
+function isKnownEntry(nav, groups, id) {
+    return resolveShellNavModel(nav, groups).some((section) => (section.group !== null && section.id === id) ||
+        section.items.some((entry) => entry.id === id));
+}
+/**
+ * Set an edge panel's `visible` and/or `initial`. Values equal to the host's
+ * defaults (`defaults`, when given) are dropped to keep the layout sparse.
+ */
+export function setShellLayoutPanel(layout, edge, patch, defaults) {
+    const current = normalizeShellLayout(layout ?? createShellLayout());
+    if (!EDGES.includes(edge))
+        return current;
+    const panel = { ...(current.panels?.[edge] ?? {}) };
+    if ('visible' in patch) {
+        if (patch.visible === false)
+            panel.visible = false;
+        else
+            delete panel.visible;
+    }
+    if ('initial' in patch) {
+        if (patch.initial === 'collapsed' || patch.initial === 'expanded') {
+            panel.initial = patch.initial;
+        }
+        else
+            delete panel.initial;
+    }
+    const base = defaults?.[edge];
+    if (panel.initial !== undefined &&
+        base !== false &&
+        panel.initial === (base?.initial ?? 'collapsed')) {
+        delete panel.initial;
+    }
+    const panels = { ...(current.panels ?? {}) };
+    if (hasKeys(panel))
+        panels[edge] = panel;
+    else
+        delete panels[edge];
+    return compact({ ...current, panels });
+}

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

@@ -1,12 +1,14 @@
+import { type ShellLayoutPanel } from './layout.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;
 /**
- * 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.
+ * An edge's state: hidden edges (by the host or the user's layout) stay
+ * hidden; otherwise the user's setting, then the edge's default for
+ * `viewport` (when it declares `viewportDefaults`), then the layout's
+ * `initial`, then the configured initial state.
  */
-export declare function resolveInitialPanelState(edge: PanelEdge, config: ShellPanelConfig, settings?: ShellSettingsDelta, viewport?: ShellViewport): PanelState;
+export declare function resolveInitialPanelState(edge: PanelEdge, config: ShellPanelConfig, settings?: ShellSettingsDelta, viewport?: ShellViewport, layoutPanel?: ShellLayoutPanel): PanelState;
 /** Default limits for a resizable side edge (CSS px). */
 export declare const DEFAULT_SHELL_PANEL_RESIZE: Required<ShellPanelResize>;
 /**

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,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"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../../src/components/workspace/admin-shell/settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AACrB,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;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,gBAAgB,EACxB,QAAQ,GAAE,kBAAuB,EACjC,QAAQ,CAAC,EAAE,aAAa,EACxB,WAAW,CAAC,EAAE,gBAAgB,GAC7B,UAAU,CASZ;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,CA2BpB;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

@@ -1,3 +1,4 @@
+import { isShellLayoutEmpty, normalizeShellLayout, } from './layout.js';
 import { EDGE_SCOPES, PANEL_EDGES } from './types.js';
 export const DEFAULT_SHELL_KEYMAP = {
     top: { code: 'KeyW' },
@@ -73,15 +74,19 @@ export function resolveShellConfig(appDefaults = {}) {
     return { panels };
 }
 /**
- * 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.
+ * An edge's state: hidden edges (by the host or the user's layout) stay
+ * hidden; otherwise the user's setting, then the edge's default for
+ * `viewport` (when it declares `viewportDefaults`), then the layout's
+ * `initial`, then the configured initial state.
  */
-export function resolveInitialPanelState(edge, config, settings = {}, viewport) {
+export function resolveInitialPanelState(edge, config, settings = {}, viewport, layoutPanel) {
     if (config.initial === 'hidden')
         return 'hidden';
+    if (layoutPanel?.visible === false)
+        return 'hidden';
     return (settings.panels?.[edge] ??
         (viewport ? config.viewportDefaults?.[viewport] : undefined) ??
+        layoutPanel?.initial ??
         config.initial);
 }
 /** Default limits for a resizable side edge (CSS px). */
@@ -182,6 +187,11 @@ export function pruneShellSettingsDelta(delta) {
     if (delta.activeFocusToolId !== undefined) {
         pruned.activeFocusToolId = delta.activeFocusToolId;
     }
+    if (delta.layout !== undefined) {
+        const layout = normalizeShellLayout(delta.layout);
+        if (!isShellLayoutEmpty(layout))
+            pruned.layout = layout;
+    }
     if (delta.keymap && Object.keys(delta.keymap).length > 0) {
         pruned.keymap = delta.keymap;
     }