canopycms 0.0.68-int.98 → 0.1.0

package/dist/editor/schema-editor/collection-draft.js

@@ -0,0 +1,40 @@
+/** The directory name in a logical path, without its embedded id ("posts.abc123" -> "posts"). */
+export function slugOf(logicalPath) {
+    const pathParts = logicalPath.split('/');
+    const lastPart = pathParts[pathParts.length - 1];
+    return lastPart?.split('.')[0] || '';
+}
+function findByPath(collections, path) {
+    for (const collection of collections) {
+        if (collection.path === path)
+            return collection;
+        const nested = collection.children && findByPath(collection.children, path);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}
+/** The collection named `name` directly under `parentPath`, or at the top level without one. */
+function findCollectionByName(collections, parentPath, name) {
+    const siblings = parentPath ? (findByPath(collections, parentPath)?.children ?? []) : collections;
+    return siblings.find((c) => c.type === 'collection' && c.name === name);
+}
+/**
+ * Whether the tree shows a details save: its collection holds every value it sent, or, for a save
+ * that changed the slug, is gone from its old path.
+ */
+function detailsLanded(collections, draft) {
+    const { updates } = draft;
+    const collection = findByPath(collections, draft.collectionPath);
+    if (!collection)
+        return updates.slug !== undefined && collections.length > 0;
+    return ((updates.name === undefined || collection.name === updates.name) &&
+        (updates.label === undefined || (collection.label ?? '') === updates.label) &&
+        (updates.slug === undefined || slugOf(collection.path) === updates.slug));
+}
+/** Whether `collections`, read from the draft's branch, show the draft's write. */
+export function collectionDraftLanded(collections, draft) {
+    return draft.kind === 'create'
+        ? !!findCollectionByName(collections, draft.input.parentPath, draft.input.name)
+        : detailsLanded(collections, draft);
+}

package/dist/editor/schema-editor/index.d.ts

@@ -1,2 +1,2 @@
-export { CollectionEditor, type CollectionEditorProps, type ExistingCollection, type ExistingEntryType, } from './CollectionEditor.js';
+export { CollectionEditor, type CollectionEditorProps, type ExistingCollection, type ExistingEntryType, type RestoredCollectionInput, } from './CollectionEditor.js';
 export { EntryTypeEditor, type EntryTypeEditorProps, type EntryTypeFormData, } from './EntryTypeEditor.js';

package/dist/editor/schema-label.d.ts

@@ -0,0 +1,10 @@
+/** A schema name read as words in sentence case: `blogPost` is "Blog post", `HTMLPage` "HTML page". */
+export declare const humanizeName: (name: string) => string;
+/**
+ * What the editor calls a field, group or block template: its label, else its name humanised, so
+ * an unlabelled schema name never shows raw (docs/ux-guidelines.md, Copy).
+ */
+export declare const schemaLabel: (item: {
+    label?: string;
+    name: string;
+}) => string;

package/dist/editor/schema-label.js

@@ -0,0 +1,17 @@
+/** A schema name read as words in sentence case: `blogPost` is "Blog post", `HTMLPage` "HTML page". */
+export const humanizeName = (name) => {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        // An acronym ("HTML") keeps its capitals.
+        .map((word) => (/^[A-Z0-9]{2,}$/.test(word) ? word : word.toLowerCase()))
+        .join(' ');
+    return words.charAt(0).toUpperCase() + words.slice(1);
+};
+/**
+ * What the editor calls a field, group or block template: its label, else its name humanised, so
+ * an unlabelled schema name never shows raw (docs/ux-guidelines.md, Copy).
+ */
+export const schemaLabel = (item) => item.label ?? humanizeName(item.name);

package/dist/editor/settings-conflict.d.ts

@@ -0,0 +1,5 @@
+export declare const SETTINGS_CHANGED_CODE = "SETTINGS_CHANGED";
+/** A groups or permissions save refused as the file changed since it loaded: shown yellow. */
+export declare class SettingsChangedError extends Error {
+    constructor(message: string);
+}

package/dist/editor/settings-conflict.js

@@ -0,0 +1,8 @@
+export const SETTINGS_CHANGED_CODE = 'SETTINGS_CHANGED';
+/** A groups or permissions save refused as the file changed since it loaded: shown yellow. */
+export class SettingsChangedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SettingsChangedError';
+    }
+}

package/dist/editor/shell/ActivityRail.d.ts

@@ -0,0 +1,37 @@
+import React, { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+export interface ActivityRailProps {
+    /** Rail buttons from the top: the monogram, then the activities. */
+    top: ReactNode;
+    /** Rail buttons pinned to the bottom, such as Settings. */
+    bottom?: ReactNode;
+    /** The account control, a tab stop of its own: an adopter's component manages its own focus. */
+    account?: ReactNode;
+}
+/**
+ * The left activity rail: one vertical toolbar whose `RailButton`s share a single Tab stop and move
+ * with the arrow keys, Home and End, then the account control. Layout only; the buttons come in as
+ * children.
+ */
+export declare function ActivityRail({ top, bottom, account }: ActivityRailProps): import("react/jsx-runtime").JSX.Element;
+export interface RailButtonProps extends Omit<ComponentPropsWithoutRef<'button'>, 'children'> {
+    /** Unique within the rail; the roving Tab stop is tracked by it. Not `id`: Mantine's
+     * `Menu.Target` sets that on its child. */
+    railId: string;
+    /** The accessible name and the tooltip's text. */
+    label: string;
+    icon: ReactNode;
+    /** Highlights the button while its panel or drawer is open. */
+    active?: boolean;
+    /** Tinted at rest, as the site monogram is. */
+    tinted?: boolean;
+    /** Shown after the label in the tooltip, as the platform writes it ("⌘P"). */
+    shortcut?: string;
+    /** A count badge, hidden at zero; the label should say it too. */
+    count?: number;
+    countTestId?: string;
+    tooltipDisabled?: boolean;
+    /** Disables the button, which stays focusable, and its tooltip gives this reason instead. */
+    disabledReason?: string;
+}
+/** A rail button: icon only, named by `label`, which its tooltip repeats on hover and focus. */
+export declare const RailButton: React.ForwardRefExoticComponent<RailButtonProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/editor/shell/ActivityRail.js

@@ -0,0 +1,91 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId, useLayoutEffect, useRef, useState, } from 'react';
+import { ActionIcon, Indicator, Stack, Tooltip, VisuallyHidden } from '@mantine/core';
+import { useElementSize, useMergedRef } from '@mantine/hooks';
+const ACTIVITY_RAIL_WIDTH = 44;
+const RAIL_ITEM_ATTR = 'data-rail-item';
+/**
+ * The left activity rail: one vertical toolbar whose `RailButton`s share a single Tab stop and move
+ * with the arrow keys, Home and End, then the account control. Layout only; the buttons come in as
+ * children.
+ */
+export function ActivityRail({ top, bottom, account }) {
+    const toolbarRef = useRef(null);
+    const currentRef = useRef(null);
+    // Re-renders on a resize, so the check below runs again.
+    const { ref: sizeRef } = useElementSize();
+    const mergedToolbarRef = useMergedRef(toolbarRef, sizeRef);
+    const [overflowing, setOverflowing] = useState(false);
+    const items = () => Array.from(toolbarRef.current?.querySelectorAll(`[${RAIL_ITEM_ATTR}]`) ?? []);
+    // Set on the DOM after every render, so a button that mounts or goes takes or hands on the Tab
+    // stop in the same commit; it falls back to the first button.
+    const placeTabStop = () => {
+        const all = items();
+        const stop = all.find((item) => item.getAttribute(RAIL_ITEM_ATTR) === currentRef.current);
+        for (const item of all)
+            item.tabIndex = item === (stop ?? all[0]) ? 0 : -1;
+    };
+    useLayoutEffect(placeTabStop);
+    // Only a rail too short for its buttons scrolls: a scroll container clips sideways too, and at
+    // full height nothing, such as a two-digit count badge, should be cut off.
+    useLayoutEffect(() => {
+        const toolbar = toolbarRef.current;
+        if (toolbar)
+            setOverflowing(toolbar.scrollHeight > toolbar.clientHeight);
+    });
+    const onKeyDown = (event) => {
+        const all = items();
+        // A menu portalled from a button still bubbles here through React; only the buttons rove.
+        const index = all.indexOf(event.target);
+        if (index < 0)
+            return;
+        const next = event.key === 'ArrowDown'
+            ? all[(index + 1) % all.length]
+            : event.key === 'ArrowUp'
+                ? all[(index - 1 + all.length) % all.length]
+                : event.key === 'Home'
+                    ? all[0]
+                    : event.key === 'End'
+                        ? all[all.length - 1]
+                        : undefined;
+        if (!next)
+            return;
+        event.preventDefault();
+        next.focus();
+    };
+    return (_jsxs(Stack, { gap: 0, h: "100%", w: ACTIVITY_RAIL_WIDTH, align: "center", style: {
+            borderInlineEnd: '1px solid var(--canopy-input-border)',
+            background: 'var(--mantine-color-body)',
+        }, children: [_jsxs(Stack, { ref: mergedToolbarRef, role: "toolbar", "aria-orientation": "vertical", "aria-label": "Activities", gap: 6, py: 8, align: "center", style: {
+                    flex: 1,
+                    minHeight: 0,
+                    ...(overflowing && {
+                        alignSelf: 'stretch',
+                        overflowY: 'auto',
+                        overflowX: 'hidden',
+                        scrollbarWidth: 'none',
+                    }),
+                }, onKeyDown: onKeyDown, onFocus: (event) => {
+                    const id = event.target.getAttribute(RAIL_ITEM_ATTR);
+                    if (id) {
+                        currentRef.current = id;
+                        placeTabStop();
+                    }
+                }, children: [top, _jsx("div", { style: { flex: 1 } }), bottom] }), account && _jsx(Stack, { pb: 8, children: account })] }));
+}
+/** A rail button: icon only, named by `label`, which its tooltip repeats on hover and focus. */
+export const RailButton = forwardRef(function RailButton({ railId, label, icon, active = false, tinted = false, shortcut, count = 0, countTestId, tooltipDisabled, disabledReason, onClick, ...rest }, ref) {
+    const reasonId = useId();
+    const button = (_jsxs(ActionIcon, { ref: ref, 
+        // Filled, not tinted, when active: a tint alone would show the state by colour, under 3:1.
+        variant: active ? 'filled' : tinted ? 'light' : 'subtle', color: active || tinted ? undefined : 'gray', size: "lg", radius: "md", "aria-label": label, ...rest, "aria-disabled": disabledReason ? true : rest['aria-disabled'], "aria-describedby": disabledReason ? reasonId : rest['aria-describedby'], "data-disabled": disabledReason ? true : undefined, onClick: disabledReason ? undefined : onClick, [RAIL_ITEM_ATTR]: railId, children: [icon, disabledReason && (_jsx(VisuallyHidden, { component: "span", id: reasonId, children: disabledReason }))] }));
+    return (_jsx(Tooltip, { label: disabledReason ?? (shortcut ? `${label} (${shortcut})` : label), position: "right", disabled: tooltipDisabled, children: _jsx(Indicator, { label: _jsx("span", { "aria-hidden": true, "data-testid": countTestId, children: count }), size: 16, offset: 4, withBorder: true, disabled: count === 0, styles: {
+                indicator: {
+                    pointerEvents: 'none',
+                    // Mantine paints the pill again in a ::before, from this variable.
+                    '--indicator-color': 'var(--canopy-count-bg)',
+                    '--indicator-text-color': 'var(--mantine-color-text)',
+                },
+            }, children: button }) }));
+});

package/dist/editor/shell/EditorShell.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+export interface EditorShellProps {
+    topBar?: ReactNode;
+    banner?: ReactNode;
+    rail?: ReactNode;
+    panel?: ReactNode;
+    main: ReactNode;
+    /** Drawers, modals and palettes, each portalling itself into `<body>`. */
+    overlays?: ReactNode;
+}
+/**
+ * The editor's window: a full-viewport grid of regions (top bar, banner, rail, panel, main,
+ * overlays), portalled into `<body>` above the host page, whose chrome it hides and makes inert
+ * and whose scrolling it stops. Layout only: features plug into the regions. The rail sits at the
+ * inline start, opposite the toasts (`theme.tsx`), and comes first after the banner in focus order.
+ */
+export declare function EditorShell({ topBar, banner, rail, panel, main, overlays }: EditorShellProps): import("react/jsx-runtime").JSX.Element;

package/dist/editor/shell/EditorShell.js

@@ -0,0 +1,31 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { Portal, getDefaultZIndex } from '@mantine/core';
+import { RemoveScroll } from 'react-remove-scroll';
+import { useHideHostChrome } from './host-chrome.js';
+const gridStyle = {
+    position: 'fixed',
+    inset: 0,
+    // Widgets a host adds outside its React tree bring their own z-index, so the shell sits just
+    // under Mantine's drawers and modals, leaving the layer between for MDXEditor's popups.
+    zIndex: getDefaultZIndex('modal') - 2,
+    display: 'grid',
+    gridTemplateAreas: '"topbar topbar topbar" "banner banner banner" "rail panel main"',
+    gridTemplateRows: 'auto auto minmax(0, 1fr)',
+    gridTemplateColumns: 'auto auto minmax(0, 1fr)',
+    background: 'var(--canopy-surface-subtle)',
+    color: 'var(--mantine-color-text)',
+};
+const region = (area) => ({ gridArea: area, minWidth: 0, minHeight: 0 });
+/**
+ * The editor's window: a full-viewport grid of regions (top bar, banner, rail, panel, main,
+ * overlays), portalled into `<body>` above the host page, whose chrome it hides and makes inert
+ * and whose scrolling it stops. Layout only: features plug into the regions. The rail sits at the
+ * inline start, opposite the toasts (`theme.tsx`), and comes first after the banner in focus order.
+ */
+export function EditorShell({ topBar, banner, rail, panel, main, overlays }) {
+    const anchorRef = useRef(null);
+    useHideHostChrome(anchorRef);
+    return (_jsxs(_Fragment, { children: [_jsx("span", { ref: anchorRef, hidden: true, "data-canopy-shell-anchor": true }), _jsx(Portal, { children: _jsxs(RemoveScroll, { noIsolation: true, removeScrollBar: true, style: gridStyle, "data-canopy-shell": "", children: [topBar && (_jsx("header", { style: region('topbar'), "data-canopy-region": "topbar", children: topBar })), _jsx("div", { style: region('banner'), "data-canopy-region": "banner", children: banner }), rail && (_jsx("aside", { style: region('rail'), "data-canopy-region": "rail", "aria-label": "Editor tools", children: rail })), _jsx("div", { style: region('panel'), "data-canopy-region": "panel", children: panel }), _jsx("main", { style: region('main'), "data-canopy-region": "main", children: main }), _jsx("div", { style: { position: 'absolute' }, "data-canopy-region": "overlays", children: overlays })] }) })] }));
+}

package/dist/editor/shell/PaneLayout.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+/** Preview beside the form, or above it. */
+export type PaneArrangement = 'side' | 'stacked';
+export declare const SPLIT_PERCENT_MIN = 15;
+export declare const SPLIT_PERCENT_MAX = 85;
+export declare const DEFAULT_SIDE_SPLIT_PERCENT = 52;
+export declare const DEFAULT_STACKED_SPLIT_PERCENT = 58;
+export interface PaneLayoutProps {
+    arrangement: PaneArrangement;
+    /** The preview's share (percent) beside the form; follows this prop when it changes. */
+    sideSplitPercent?: number;
+    /** The preview's share (percent) above the form; follows this prop when it changes. */
+    stackedSplitPercent?: number;
+    /** Called when a drag or a keyboard resize changes the split, with the preview's percent. */
+    onSplitPercentChange?: (arrangement: PaneArrangement, percent: number) => void;
+    preview?: React.ReactNode;
+    form?: React.ReactNode;
+    /** Laid over the form pane, outside its scrolling: the side panel in overlay mode. */
+    formOverlay?: React.ReactNode;
+    /** Takes the form out of focus and the pointer's reach while an open `formOverlay` hides it. */
+    formInert?: boolean;
+    /** Lays the preview over the whole layout, form and separator inert, without remounting it. */
+    previewMaximized?: boolean;
+    /** Called as a held separator first moves the split, and as it is let go after that. */
+    onSeparatorDrag?: (dragging: boolean) => void;
+}
+/** The resizable preview/form split that fills the shell's main region. */
+export declare function PaneLayout({ arrangement, sideSplitPercent, stackedSplitPercent, onSplitPercentChange, preview, form, formOverlay, formInert, previewMaximized, onSeparatorDrag, }: PaneLayoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/editor/shell/PaneLayout.js

@@ -0,0 +1,116 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import { Box } from '@mantine/core';
+import { Group, Panel, Separator, useGroupRef } from 'react-resizable-panels';
+export const SPLIT_PERCENT_MIN = 15;
+export const SPLIT_PERCENT_MAX = 85;
+export const DEFAULT_SIDE_SPLIT_PERCENT = 52;
+export const DEFAULT_STACKED_SPLIT_PERCENT = 58;
+const PREVIEW = 'canopy-preview';
+const FORM = 'canopy-form';
+// The preview's limits are the stored split's, so a drag never ends somewhere storage would move;
+// the form also keeps a usable minimum in a narrow window.
+const PREVIEW_LIMITS = { minSize: `${SPLIT_PERCENT_MIN}%`, maxSize: `${SPLIT_PERCENT_MAX}%` };
+const FORM_MIN_PX = 160;
+const SEPARATOR_STYLES = `
+.canopy-pane-separator {
+  min-width: 8px;
+  min-height: 8px;
+  background: var(--canopy-surface-muted);
+  box-shadow: inset 0 0 0 1px var(--canopy-input-border);
+}
+.canopy-pane-separator:is([data-separator='hover'], [data-separator='active']) {
+  background: var(--canopy-focus-ring);
+}
+.canopy-pane-separator:focus-visible {
+  outline: 2px solid var(--canopy-focus-ring);
+  outline-offset: -2px;
+}
+`;
+const splitLayout = (percent) => ({ [PREVIEW]: percent, [FORM]: 100 - percent });
+/** The resizable preview/form split that fills the shell's main region. */
+export function PaneLayout({ arrangement, sideSplitPercent = DEFAULT_SIDE_SPLIT_PERCENT, stackedSplitPercent = DEFAULT_STACKED_SPLIT_PERCENT, onSplitPercentChange, preview, form, formOverlay, formInert = false, previewMaximized = false, onSeparatorDrag, }) {
+    const groupRef = useGroupRef();
+    const separatorRef = useRef(null);
+    const previewRef = useRef(null);
+    const formRef = useRef(null);
+    const formPanelRef = useRef(null);
+    const percent = arrangement === 'side' ? sideSplitPercent : stackedSplitPercent;
+    // Stored sizes load after mount, and the group must never remount: that would reload the preview.
+    useEffect(() => {
+        const group = groupRef.current;
+        if (!group)
+            return;
+        if (Math.abs((group.getLayout()[PREVIEW] ?? percent) - percent) > 0.1) {
+            group.setLayout(splitLayout(percent));
+        }
+    }, [groupRef, percent, arrangement]);
+    // React 18 has no `inert` prop, so it is set on the DOM. A layout effect, so it changes before
+    // any passive effect of the same commit tries to focus into the form or out of the overlay.
+    useLayoutEffect(() => {
+        formRef.current?.toggleAttribute('inert', formInert);
+        formPanelRef.current?.toggleAttribute('inert', previewMaximized);
+        separatorRef.current?.toggleAttribute('inert', previewMaximized);
+    }, [formInert, previewMaximized]);
+    const onSeparatorDragRef = useRef(onSeparatorDrag);
+    useEffect(() => {
+        onSeparatorDragRef.current = onSeparatorDrag;
+    }, [onSeparatorDrag]);
+    // A press alone is no drag: one that only focuses the separator must not report one.
+    const hold = useRef(null);
+    // An iframe takes the pointer moves a drag needs, so the panes ignore the pointer while the
+    // separator is held. Set on the DOM as the attribute flips, before the first move arrives.
+    useEffect(() => {
+        const separator = separatorRef.current;
+        if (!separator)
+            return;
+        const observer = new MutationObserver(() => {
+            const held = separator.getAttribute('data-separator') === 'active';
+            for (const pane of [previewRef.current, formRef.current]) {
+                if (pane)
+                    pane.style.pointerEvents = held ? 'none' : '';
+            }
+            if (held && !hold.current) {
+                hold.current = { start: groupRef.current?.getLayout()[PREVIEW] ?? 0, moved: false };
+            }
+            else if (!held && hold.current) {
+                if (hold.current.moved)
+                    onSeparatorDragRef.current?.(false);
+                hold.current = null;
+            }
+        });
+        observer.observe(separator, { attributes: true, attributeFilter: ['data-separator'] });
+        return () => observer.disconnect();
+    }, [groupRef]);
+    const side = arrangement === 'side';
+    return (_jsxs(_Fragment, { children: [_jsx("style", { children: SEPARATOR_STYLES }), _jsxs(Group, { groupRef: groupRef, orientation: side ? 'horizontal' : 'vertical', defaultLayout: splitLayout(percent), 
+                // The hidden separator would otherwise still take drags over a maximized preview: the
+                // library hit-tests separators by their rectangles, which `inert` leaves in place.
+                disabled: previewMaximized, onLayoutChange: (layout) => {
+                    const next = layout[PREVIEW];
+                    const held = hold.current;
+                    if (held && !held.moved && next !== undefined && Math.abs(next - held.start) > 0.01) {
+                        held.moved = true;
+                        onSeparatorDragRef.current?.(true);
+                    }
+                }, onLayoutChanged: (layout, meta) => {
+                    const next = layout[PREVIEW];
+                    if (meta.isUserInteraction && next !== undefined && Math.abs(next - percent) > 0.01)
+                        onSplitPercentChange?.(arrangement, next);
+                }, 
+                // The maximized preview's containing block: the panels themselves are unpositioned.
+                style: { height: '100%', width: '100%', position: 'relative' }, children: [_jsx(Panel, { id: PREVIEW, ...PREVIEW_LIMITS, children: _jsx(Box, { ref: previewRef, "data-testid": "preview-pane", "data-maximized": previewMaximized || undefined, h: "100%", w: "100%", style: previewMaximized
+                                ? { overflow: 'auto', position: 'absolute', inset: 0, zIndex: 1 }
+                                : { overflow: 'auto' }, children: preview }) }), _jsx(Separator, { elementRef: separatorRef, "aria-label": "Resize preview and form", className: "canopy-pane-separator" }), _jsx(Panel, { id: FORM, minSize: FORM_MIN_PX, children: _jsxs(Box, { ref: formPanelRef, pos: "relative", h: "100%", w: "100%", 
+                            // `formOverlay` stacks within this pane, so a maximized preview always covers it.
+                            style: { isolation: 'isolate' }, children: [_jsx(Box, { ref: formRef, "data-testid": "form-pane", h: "100%", w: "100%", style: {
+                                        // FormHeader reads this to span the padding.
+                                        '--canopy-form-pane-padding': '20px',
+                                        padding: 'var(--canopy-form-pane-padding)',
+                                        overflow: 'auto',
+                                        backgroundColor: 'var(--canopy-surface-muted)',
+                                        // Keeps the form's sticky header under `formOverlay`.
+                                        isolation: 'isolate',
+                                    }, children: form }), formOverlay] }) })] })] }));
+}

package/dist/editor/shell/SidePanelHost.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode } from 'react';
+/** Docked beside the main region, or laid over the form pane only. */
+type SidePanelMode = 'docked' | 'overlay';
+export interface SidePanelHostProps {
+    title: string;
+    mode: SidePanelMode;
+    opened: boolean;
+    /** The stored width; a drag shows its own until it ends. */
+    width: number;
+    minWidth: number;
+    maxWidth: number;
+    /** Called when a drag ends and on each resize key. */
+    onWidthChange: (width: number) => void;
+    onClose: () => void;
+    /**
+     * Bumped by the caller each time the user asks for the panel, open or not: each new value moves
+     * focus in. Opening alone never does, as a panel also opens when stored state loads.
+     */
+    focusRequest?: number;
+    /** Where focus goes when the panel closes with focus inside it. */
+    returnFocusTo?: () => HTMLElement | null;
+    /** Controls beside the title, before the close button. */
+    actions?: ReactNode;
+    children: ReactNode;
+    id?: string;
+    'data-testid'?: string;
+}
+/**
+ * A titled side panel, resizable from its inline-end edge. Docked, it is a column of the shell;
+ * as an overlay it covers the form pane only, so the preview stays in view, and Escape closes it.
+ * A `focusRequest` moves focus to its `data-autofocus` element, else to the panel; closing with
+ * focus inside returns focus to `returnFocusTo`.
+ */
+export declare function SidePanelHost({ title, mode, opened, width, minWidth, maxWidth, onWidthChange, onClose, focusRequest, returnFocusTo, actions, children, id, 'data-testid': testId, }: SidePanelHostProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/editor/shell/SidePanelHost.js

@@ -0,0 +1,184 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState, } from 'react';
+import { CloseButton, Group, Text, Tooltip } from '@mantine/core';
+import { useWindowEvent } from '@mantine/hooks';
+import { focusIfIdle } from '../utils/focus-return.js';
+const KEY_STEP_PX = 16;
+const RESIZING_ATTR = 'data-canopy-panel-resizing';
+const PANEL_STYLES = `
+body[${RESIZING_ATTR}] { cursor: col-resize; user-select: none; }
+body[${RESIZING_ATTR}] iframe { pointer-events: none; }
+.canopy-side-panel-separator {
+  position: absolute;
+  inset-block: 0;
+  inset-inline-end: -3px;
+  width: 6px;
+  cursor: col-resize;
+  touch-action: none;
+  z-index: 1;
+}
+.canopy-side-panel-separator:hover,
+.canopy-side-panel-separator[data-dragging] {
+  background: var(--canopy-focus-ring);
+}
+.canopy-side-panel-separator:focus-visible {
+  outline: 2px solid var(--canopy-focus-ring);
+  outline-offset: -2px;
+}
+`;
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+ * A titled side panel, resizable from its inline-end edge. Docked, it is a column of the shell;
+ * as an overlay it covers the form pane only, so the preview stays in view, and Escape closes it.
+ * A `focusRequest` moves focus to its `data-autofocus` element, else to the panel; closing with
+ * focus inside returns focus to `returnFocusTo`.
+ */
+export function SidePanelHost({ title, mode, opened, width, minWidth, maxWidth, onWidthChange, onClose, focusRequest = 0, returnFocusTo, actions, children, id, 'data-testid': testId, }) {
+    const fallbackId = useId();
+    const panelId = id ?? fallbackId;
+    const titleId = `${panelId}-title`;
+    const panelRef = useRef(null);
+    const focusInside = useRef(false);
+    const wasOpened = useRef(opened);
+    const servedFocusRequest = useRef(focusRequest);
+    const drag = useRef(null);
+    const [dragWidth, setDragWidth] = useState(null);
+    if (!opened && dragWidth !== null)
+        setDragWidth(null);
+    const shownWidth = clamp(dragWidth ?? width, minWidth, maxWidth);
+    useEffect(() => {
+        const panel = panelRef.current;
+        const asked = opened && focusRequest !== servedFocusRequest.current;
+        servedFocusRequest.current = focusRequest;
+        if (!asked || !panel)
+            return;
+        const autofocus = () => panel.querySelector('[data-autofocus]');
+        const field = autofocus();
+        if (field) {
+            field.focus({ preventScroll: true });
+            return;
+        }
+        // The field may render with content still loading: it takes focus when it arrives, unless
+        // focus has moved off the panel by then.
+        panel.focus({ preventScroll: true });
+        const observer = new MutationObserver(() => {
+            if (document.activeElement !== panel)
+                return observer.disconnect();
+            const arrived = autofocus();
+            if (!arrived)
+                return;
+            observer.disconnect();
+            arrived.focus({ preventScroll: true });
+        });
+        observer.observe(panel, { childList: true, subtree: true });
+        return () => observer.disconnect();
+    }, [opened, focusRequest]);
+    useEffect(() => {
+        if (!opened && wasOpened.current) {
+            // Its separator is gone, and with it the pointer capture that would have ended a drag.
+            drag.current = null;
+            document.body.removeAttribute(RESIZING_ATTR);
+            if (focusInside.current) {
+                focusInside.current = false;
+                focusIfIdle(returnFocusTo?.() ?? null);
+            }
+        }
+        wasOpened.current = opened;
+    }, [opened, returnFocusTo]);
+    // On the window, not the panel: a dialog portalled from the panel would bubble its Escape here
+    // through React, so only a key from inside the panel's own DOM closes it.
+    useWindowEvent('keydown', (event) => {
+        if (opened &&
+            mode === 'overlay' &&
+            event.key === 'Escape' &&
+            !event.defaultPrevented &&
+            event.target instanceof Node &&
+            panelRef.current?.contains(event.target)) {
+            event.preventDefault();
+            onClose();
+        }
+    });
+    // A drag cut short by unmounting must not leave the page's iframes deaf to the pointer.
+    useEffect(() => () => document.body.removeAttribute(RESIZING_ATTR), []);
+    if (!opened)
+        return null;
+    const endDrag = () => {
+        const state = drag.current;
+        if (!state)
+            return;
+        drag.current = null;
+        document.body.removeAttribute(RESIZING_ATTR);
+        setDragWidth(null);
+        onWidthChange(state.width);
+    };
+    const separatorHandlers = {
+        onPointerDown: (event) => {
+            if (event.button !== 0)
+                return;
+            event.preventDefault();
+            event.currentTarget.setPointerCapture(event.pointerId);
+            const rtl = getComputedStyle(event.currentTarget).direction === 'rtl';
+            drag.current = {
+                startX: event.clientX,
+                startWidth: shownWidth,
+                width: shownWidth,
+                sign: rtl ? -1 : 1,
+            };
+            document.body.setAttribute(RESIZING_ATTR, '');
+            setDragWidth(shownWidth);
+        },
+        onPointerMove: (event) => {
+            const state = drag.current;
+            if (!state)
+                return;
+            state.width = clamp(state.startWidth + state.sign * (event.clientX - state.startX), minWidth, maxWidth);
+            setDragWidth(state.width);
+        },
+        onPointerUp: endDrag,
+        onPointerCancel: endDrag,
+        onLostPointerCapture: endDrag,
+        onKeyDown: (event) => {
+            const rtl = getComputedStyle(event.currentTarget).direction === 'rtl';
+            const grow = rtl ? 'ArrowLeft' : 'ArrowRight';
+            const shrink = rtl ? 'ArrowRight' : 'ArrowLeft';
+            const next = event.key === grow
+                ? shownWidth + KEY_STEP_PX
+                : event.key === shrink
+                    ? shownWidth - KEY_STEP_PX
+                    : event.key === 'Home'
+                        ? minWidth
+                        : event.key === 'End'
+                            ? maxWidth
+                            : undefined;
+            if (next === undefined)
+                return;
+            event.preventDefault();
+            onWidthChange(clamp(next, minWidth, maxWidth));
+        },
+    };
+    const overlay = mode === 'overlay';
+    const style = {
+        position: overlay ? 'absolute' : 'relative',
+        insetBlock: overlay ? 0 : undefined,
+        insetInlineStart: overlay ? 0 : undefined,
+        zIndex: overlay ? 2 : undefined,
+        boxShadow: overlay ? 'var(--mantine-shadow-md)' : undefined,
+        width: shownWidth,
+        maxWidth: '100%',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        background: 'var(--mantine-color-body)',
+        borderInlineEnd: '1px solid var(--canopy-input-border)',
+    };
+    return (_jsxs("section", { ref: panelRef, id: panelId, "aria-labelledby": titleId, tabIndex: -1, "data-testid": testId, "data-panel-mode": mode, style: style, onFocus: () => {
+            focusInside.current = true;
+        }, onBlur: (event) => {
+            if (!event.currentTarget.contains(event.relatedTarget))
+                focusInside.current = false;
+        }, children: [_jsx("style", { children: PANEL_STYLES }), _jsxs(Group, { justify: "space-between", wrap: "nowrap", gap: "xs", px: "md", py: "xs", style: { borderBlockEnd: '1px solid var(--canopy-input-border)' }, children: [_jsx(Text, { id: titleId, component: "h2", fw: 600, size: "md", m: 0, children: title }), _jsxs(Group, { gap: "xs", wrap: "nowrap", children: [actions, _jsx(Tooltip, { label: `Close ${title.toLowerCase()} panel`, children: _jsx(CloseButton, { "aria-label": `Close ${title.toLowerCase()} panel`, onClick: onClose }) })] })] }), _jsx("div", { style: { flex: 1, minHeight: 0, overflow: 'auto' }, children: children }), _jsx("div", { role: "separator", "aria-orientation": "vertical", "aria-label": `Resize ${title.toLowerCase()} panel`, "aria-controls": panelId, "aria-valuenow": Math.round(shownWidth), "aria-valuemin": minWidth, "aria-valuemax": maxWidth, 
+                // A focusable separator is a window splitter, a widget; jsx-a11y counts every one static.
+                // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+                tabIndex: 0, className: "canopy-side-panel-separator", "data-dragging": dragWidth !== null || undefined, ...separatorHandlers })] }));
+}