canopycms 0.1.0-int.115 → 0.1.0

package/dist/editor/hooks/useEntryManager.js

@@ -102,10 +102,6 @@ export function useEntryManager(options) {
     selectedPathRef.current = selectedPath;
     // Counts selections through the returned setter, not this hook's own fallbacks.
     const selectionsByCallerRef = useRef(0);
-    const selectEntryPath = useCallback((path) => {
-        selectionsByCallerRef.current += 1;
-        setSelectedPath(path);
-    }, []);
     const [navigatorOpen, setNavigatorOpen] = useState(() => readUrlEntry() === '');
     const isInitialMount = useRef(true);
     const hasSyncedFromUrl = useRef(false);
@@ -184,8 +180,18 @@ export function useEntryManager(options) {
     if (initialUrlEntry.current === undefined) {
         initialUrlEntry.current = readUrlEntry();
     }
-    // Honoured until any entry is selected; after that a lost selection opens the first again.
+    // Set by the URL's empty `entry` or by `closeEntry`; honoured until an entry is selected or the
+    // branch changes, after which a lost selection opens the first again.
     const noEntryRequested = useRef(initialUrlEntry.current === '');
+    const selectEntryPath = useCallback((path) => {
+        selectionsByCallerRef.current += 1;
+        setSelectedPath(path);
+    }, []);
+    // No entry open, as the URL's empty `entry` asks, where a lost selection opens the first.
+    const closeEntry = useCallback(() => {
+        noEntryRequested.current = true;
+        selectEntryPath('');
+    }, [selectEntryPath]);
     const collectionByPath = useMemo(() => {
         const map = new Map();
         const walk = (collections) => {
@@ -492,10 +498,24 @@ export function useEntryManager(options) {
         const renaming = entriesState.find((e) => e.path === path);
         const contentId = renaming?.contentId;
         const label = renaming?.label ?? path;
+        // As `refreshAndOpen`: the new path opens only if the user is still on the entry and branch.
+        const branch = options.branchName;
+        const stillOnIt = selectedPathRef.current === path;
+        const selections = selectionsByCallerRef.current;
+        // The rename landed whatever the refresh does. The new path is selected only once the list
+        // holds it: before that, the selection check would find it missing and open the first entry.
         const landed = async (newPath) => {
-            if (newPath && selectedPath === path)
+            const listed = await refreshEntries().catch((err) => {
+                console.error(err);
+                return null;
+            });
+            if (newPath &&
+                listed?.some((e) => e.path === newPath) &&
+                stillOnIt &&
+                selections === selectionsByCallerRef.current &&
+                branch === currentBranchRef.current) {
                 setSelectedPath(newPath);
-            await refreshEntries();
+            }
             notifications.show({ message: 'Entry renamed', color: 'green' });
         };
         options.setBusy(true);
@@ -543,6 +563,7 @@ export function useEntryManager(options) {
             isInitialMount.current = false;
         }
         else {
+            noEntryRequested.current = false;
             setSelectedPath('');
             // Bound version-map growth across switches. Correctness no longer
             // depends on this clear: tokens are keyed by `${branch}:${contentId}`
@@ -710,12 +731,14 @@ export function useEntryManager(options) {
     return {
         selectedPath,
         setSelectedPath: selectEntryPath,
+        closeEntry,
         entries: entriesState,
         setEntries,
         collections: collectionsState,
         currentEntry,
         availableSchemas,
         entriesInitializing,
+        entriesLoadFailed: Boolean(options.branchName) && Boolean(entriesError),
         navigatorOpen,
         setNavigatorOpen,
         refreshEntries,

package/dist/editor/media/MediaLibrary.d.ts

@@ -4,7 +4,7 @@ export interface MediaLibraryProps {
     opened: boolean;
     onClose: () => void;
     /**
-     * 'manage': right-side Drawer opened from the EditorSidebar Settings menu.
+     * 'manage': right-side Drawer opened from the rail's Media button.
      * 'picker': Modal used by ImageField ("Browse library"/"Replace") and the
      * MDX image dialog's "From library" tab.
      */

package/dist/editor/preview-path.d.ts

@@ -8,3 +8,15 @@
 export declare const normalizePreviewPath: (url: string) => string;
 /** Whether two preview URLs name the same page; see `normalizePreviewPath`. */
 export declare const isSamePreviewPath: (a: string, b: string) => boolean;
+/** Where `buildPreviewSrc` mounts the preview routes, and the `basePath` the site's pages keep. */
+export interface PreviewMount {
+    basePath?: string;
+    previewPrefix?: string;
+}
+/**
+ * The previewed page's path on the site, as the preview toolbar shows and copies it: without the
+ * `previewPrefix` mount, the `branch` query the top bar already names, or a fragment. A relative
+ * URL stays relative. An absolute one keeps its origin, since it may be another site, unless an
+ * absolute `previewPrefix` mount is what was taken out.
+ */
+export declare const displayPreviewPath: (src: string, mount?: PreviewMount) => string;

package/dist/editor/preview-path.js

@@ -1,4 +1,4 @@
-import { stripTrailingSlashes } from '../utils/url-prefix.js';
+import { isAbsoluteUrl, joinUrlPrefix, stripTrailingSlashes } from '../utils/url-prefix.js';
 /**
  * Reduces a preview URL to what identifies the page, its path and query, with no origin,
  * fragment or trailing slash. The editor names a page by the `src` it built and the framed page
@@ -18,3 +18,47 @@ export const normalizePreviewPath = (url) => {
 };
 /** Whether two preview URLs name the same page; see `normalizePreviewPath`. */
 export const isSamePreviewPath = (a, b) => normalizePreviewPath(a) === normalizePreviewPath(b);
+/** `url` with the `previewPrefix` mount taken out, so `/base/preview/posts/x` reads `/base/posts/x`. */
+const stripPreviewPrefix = (url, { basePath, previewPrefix }) => {
+    if (!previewPrefix || !stripTrailingSlashes(previewPrefix))
+        return url;
+    const mount = stripTrailingSlashes(joinUrlPrefix(basePath, joinUrlPrefix(previewPrefix, '/')));
+    if (!url.startsWith(mount))
+        return url;
+    const rest = url.slice(mount.length);
+    if (rest !== '' && !/^[/?#]/.test(rest))
+        return url;
+    // An absolute prefix skips `basePath`, so the page under it has none either.
+    const base = isAbsoluteUrl(mount) ? '' : stripTrailingSlashes(joinUrlPrefix(basePath, '/'));
+    return rest.startsWith('/') ? `${base}${rest}` : `${base || '/'}${rest}`;
+};
+/**
+ * The previewed page's path on the site, as the preview toolbar shows and copies it: without the
+ * `previewPrefix` mount, the `branch` query the top bar already names, or a fragment. A relative
+ * URL stays relative. An absolute one keeps its origin, since it may be another site, unless an
+ * absolute `previewPrefix` mount is what was taken out.
+ */
+export const displayPreviewPath = (src, mount = {}) => {
+    const url = stripPreviewPrefix(src, mount);
+    let parsed;
+    try {
+        parsed = new URL(url, 'http://preview.invalid');
+    }
+    catch {
+        return url;
+    }
+    // Filtered as text: a URLSearchParams round trip would form-encode the query it keeps (`flag`
+    // becomes `flag=`, `%20` becomes `+`).
+    const query = parsed.search
+        .slice(1)
+        .split('&')
+        .filter((part) => part !== '' && part.split('=', 1)[0] !== 'branch')
+        .join('&');
+    const path = `${parsed.pathname}${query ? `?${query}` : ''}`;
+    if (!isAbsoluteUrl(url))
+        return path;
+    // `origin` is 'null' for a scheme the URL spec does not treat as special.
+    return url.startsWith('//')
+        ? `//${parsed.host}${path}`
+        : `${parsed.protocol}//${parsed.host}${path}`;
+};

package/dist/editor/preview-scale.d.ts

@@ -0,0 +1,27 @@
+import type { PreviewWidth } from './hooks/useEditorLayout.js';
+/** The CSS width each fixed preview width renders the site at. */
+export declare const PREVIEW_DEVICE_WIDTHS: {
+    readonly desktop: 1280;
+    readonly tablet: 768;
+    readonly mobile: 390;
+};
+/** Where and how large the preview iframe renders inside a pane of a given size. */
+export interface PreviewViewport {
+    /** The iframe's CSS width: the width the site's breakpoints see. */
+    frameWidth: number;
+    /** The iframe's CSS height, before scaling; scaled, it fills the pane's height. */
+    frameHeight: number;
+    /** The factor the iframe is scaled by, at most 1. */
+    scale: number;
+    /** The left offset that centres the scaled iframe in the pane. */
+    offsetX: number;
+}
+/**
+ * Fits the preview into a pane. "fit" renders at the pane's width. A fixed width renders at
+ * exactly that CSS width and, when the pane is narrower, scales down so the whole width shows,
+ * stretching the CSS height by the same factor so the scaled frame still fills the pane's height.
+ * An unmeasured pane (zero or non-finite) renders unscaled.
+ */
+export declare function computePreviewViewport(previewWidth: PreviewWidth, paneWidth: number, paneHeight: number): PreviewViewport;
+/** The readout beside the width selector: the CSS width, plus the scale when it rounds below 100%. */
+export declare function formatPreviewWidthReadout({ frameWidth, scale }: PreviewViewport): string;

package/dist/editor/preview-scale.js

@@ -0,0 +1,34 @@
+/** The CSS width each fixed preview width renders the site at. */
+export const PREVIEW_DEVICE_WIDTHS = {
+    desktop: 1280,
+    tablet: 768,
+    mobile: 390,
+};
+const positiveOr = (value, fallback) => Number.isFinite(value) && value > 0 ? value : fallback;
+/**
+ * Fits the preview into a pane. "fit" renders at the pane's width. A fixed width renders at
+ * exactly that CSS width and, when the pane is narrower, scales down so the whole width shows,
+ * stretching the CSS height by the same factor so the scaled frame still fills the pane's height.
+ * An unmeasured pane (zero or non-finite) renders unscaled.
+ */
+export function computePreviewViewport(previewWidth, paneWidth, paneHeight) {
+    const width = positiveOr(paneWidth, 0);
+    const height = positiveOr(paneHeight, 0);
+    if (previewWidth === 'fit') {
+        return { frameWidth: width, frameHeight: height, scale: 1, offsetX: 0 };
+    }
+    const frameWidth = PREVIEW_DEVICE_WIDTHS[previewWidth];
+    const scale = width > 0 ? Math.min(1, width / frameWidth) : 1;
+    return {
+        frameWidth,
+        frameHeight: height / scale,
+        scale,
+        offsetX: width > 0 ? Math.max(0, (width - frameWidth * scale) / 2) : 0,
+    };
+}
+/** The readout beside the width selector: the CSS width, plus the scale when it rounds below 100%. */
+export function formatPreviewWidthReadout({ frameWidth, scale }) {
+    const px = `${Math.round(frameWidth)} px`;
+    const percent = Math.round(scale * 100);
+    return percent < 100 ? `${px} at ${percent}%` : px;
+}

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 {};