canopycms 0.1.0 → 0.2.0-int.121

package/dist/editor/preview-bridge.js

@@ -4,7 +4,7 @@
  * hosts through `canopycms/preview`, so everything it reaches stays free of CSS and editor UI
  * (`pnpm lint:bundle`); the editor's side is `PreviewFrame.tsx`.
  */
-import { useCallback, useEffect, useLayoutEffect, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { createFieldProps } from './field-props.js';
 import { setPreviewAssetBase } from './preview-asset-base.js';
 import { isSamePreviewPath } from './preview-path.js';
@@ -15,6 +15,7 @@ export const CANOPY_PREVIEW_HIGHLIGHT = 'canopycms:preview:highlight';
 export const CANOPY_PREVIEW_READY = 'canopycms:preview:ready';
 export const CANOPY_PREVIEW_ERROR = 'canopycms:preview:error';
 export const CANOPY_PREVIEW_MARKS = 'canopycms:preview:marks';
+export const CANOPY_PREVIEW_NAVIGATE = 'canopycms:preview:navigate';
 /**
  * Resolve a (possibly relative) URL to an origin for postMessage targeting.
  * Falls back to the page's own origin, so same-origin editor/preview setups
@@ -73,9 +74,13 @@ export const useCanopyPreview = (opts) => {
     const resolvedPath = resolvePreviewPath(opts.path);
     const editorOrigin = opts.editorOrigin;
     const bridgeOpts = { editorOrigin };
-    const { data, isLoading } = usePreviewData(resolvedPath, opts.initialData, bridgeOpts);
+    const { data, isLoading } = usePreviewData(resolvedPath, opts.initialData, {
+        editorOrigin,
+        siteChrome: opts.siteChrome,
+    });
     const highlightEnabled = usePreviewHighlight(bridgeOpts);
     usePreviewFocusEmitter(resolvedPath, bridgeOpts);
+    usePreviewLinkNavigation({ editorOrigin, highlighting: highlightEnabled });
     const fieldProps = createFieldProps();
     /**
      * Report that the current draft fails to compile/render (the editor surfaces it
@@ -107,6 +112,7 @@ export const usePreviewData = (path, initialData, opts) => {
     // Every key of the loading state is optional, so an empty object is a valid one.
     const [isLoading, setIsLoading] = useState({});
     const editorOrigin = opts?.editorOrigin;
+    const siteChrome = opts?.siteChrome === true;
     useEffect(() => {
         // Only listen when actually framed by an editor; a standalone page (including
         // one opened via window.open from a hostile site) must never accept drafts.
@@ -133,10 +139,15 @@ export const usePreviewData = (path, initialData, opts) => {
         // so the first postMessage from the parent may arrive before this listener is set up.
         const target = resolveMessageOrigin(editorOrigin);
         if (!isOpaqueOrigin(target)) {
-            window.parent.postMessage({ type: CANOPY_PREVIEW_READY, path }, target);
+            const ready = {
+                type: CANOPY_PREVIEW_READY,
+                path,
+                ...(siteChrome ? { siteChrome } : {}),
+            };
+            window.parent.postMessage(ready, target);
         }
         return () => window.removeEventListener('message', handler);
-    }, [path, editorOrigin]);
+    }, [path, editorOrigin, siteChrome]);
     return { data, isLoading };
 };
 /** React 18 warns about a layout effect in a server render, where no effect runs. */
@@ -262,8 +273,96 @@ export const usePreviewHighlight = (opts) => {
     }, [enabled, editorOrigin]);
     return enabled;
 };
+const isPlainClick = (event) => event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+const linkClick = (event) => {
+    // The composed path reaches a link inside a shadow root, which the retargeted `target` hides.
+    const anchor = event
+        .composedPath()
+        .find((node) => node instanceof Element && node.matches('a[href], area[href]'));
+    if (!anchor)
+        return undefined;
+    let url;
+    try {
+        url = new URL(anchor.getAttribute('href') ?? '', document.baseURI);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return undefined;
+    const here = new URL(window.location.href);
+    if (url.href.split('#')[0] === here.href.split('#')[0])
+        return undefined;
+    const target = anchor.getAttribute('target') ?? document.querySelector('base[target]')?.getAttribute('target');
+    if (!isPlainClick(event) || (target && target !== '_self') || anchor.hasAttribute('download')) {
+        return { kind: 'browser' };
+    }
+    return { kind: url.origin === here.origin ? 'navigate' : 'open', href: url.href };
+};
+const isInMark = (event) => event
+    .composedPath()
+    .some((node) => node instanceof Element && node.hasAttribute('data-canopy-path'));
+/** Clicks `usePreviewLinkNavigation` followed itself, so click-to-focus leaves them be. */
+const followedLinkClicks = new WeakSet();
+/**
+ * Hook for preview pages to keep link clicks off public pages that may refuse framing. Captured on
+ * the window, so it runs before the page's own handlers, a client router's included.
+ */
+const usePreviewLinkNavigation = (opts) => {
+    const editorOrigin = opts.editorOrigin;
+    const highlighting = useRef(opts.highlighting);
+    useEffect(() => {
+        highlighting.current = opts.highlighting;
+    });
+    useEffect(() => {
+        if (window.parent === window)
+            return;
+        const targetOrigin = resolveMessageOrigin(editorOrigin);
+        if (isOpaqueOrigin(targetOrigin))
+            return;
+        // Links stay the browser's until the editor speaks: a frame that isn't a trusted editor, such
+        // as a site embedding a public page, would drop the message and leave every link dead.
+        let connected = false;
+        const handleMessage = (event) => {
+            const type = event.data?.type;
+            if (type !== CANOPY_PREVIEW_HIGHLIGHT && type !== CANOPY_PREVIEW_MESSAGE)
+                return;
+            if (isTrustedEditorMessage(event, editorOrigin))
+                connected = true;
+        };
+        const handleClick = (event) => {
+            if (!connected || event.defaultPrevented)
+                return;
+            const link = linkClick(event);
+            if (!link)
+                return;
+            // While fields are outlined, a marked link is a field to pick, which click-to-focus does.
+            if (highlighting.current && isPlainClick(event) && isInMark(event)) {
+                event.preventDefault();
+                return;
+            }
+            if (link.kind === 'browser')
+                return;
+            event.preventDefault();
+            followedLinkClicks.add(event);
+            if (link.kind === 'open') {
+                window.open(link.href, '_blank', 'noopener,noreferrer');
+                return;
+            }
+            const msg = { type: CANOPY_PREVIEW_NAVIGATE, href: link.href };
+            window.parent.postMessage(msg, targetOrigin);
+        };
+        window.addEventListener('message', handleMessage);
+        window.addEventListener('click', handleClick, true);
+        return () => {
+            window.removeEventListener('message', handleMessage);
+            window.removeEventListener('click', handleClick, true);
+        };
+    }, [editorOrigin]);
+};
 /**
  * Hook for preview pages to emit focus messages when elements with data-canopy-path are clicked.
+ * A click that follows a link, ours or the browser's, goes to another page, not to a field.
  */
 export const usePreviewFocusEmitter = (entryPath, opts) => {
     const editorOrigin = opts?.editorOrigin;
@@ -271,6 +370,8 @@ export const usePreviewFocusEmitter = (entryPath, opts) => {
         if (window.parent === window)
             return;
         const handleClick = (event) => {
+            if (followedLinkClicks.has(event) || (!event.defaultPrevented && linkClick(event)))
+                return;
             const target = event.target;
             if (!target)
                 return;

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

@@ -1,8 +1,9 @@
 /**
  * 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
- * by its own location. An absolute `src`, or a host redirect that adds or drops a trailing slash,
- * spells the same page two ways, and the bridge must still match them.
+ * fragment, trailing slash or `chrome=1`. The editor names a page by the `src` it built and the
+ * framed page by its own location. An absolute `src`, a host redirect that adds or drops a
+ * trailing slash, or the site header and footer toggle, spells the same page two ways, and the
+ * bridge must still match them.
  * @internal Exported for tests.
  */
 export declare const normalizePreviewPath: (url: string) => string;
@@ -13,10 +14,21 @@ export interface PreviewMount {
     basePath?: string;
     previewPrefix?: string;
 }
+/**
+ * `src` asking for the site's header and footer, or `undefined` when it cannot. Only a page under
+ * the `previewPrefix` mount is a `createPreviewPage` route, which reads `chrome=1`; any other URL
+ * is a page of the site itself, which the editor leaves as it is.
+ */
+export declare const siteChromeSrc: (src: string, mount?: PreviewMount) => string | undefined;
 /**
  * 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
+ * `previewPrefix` mount, the `branch` query the top bar already names, `chrome=1`, 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;
+/**
+ * The page `url` shows, as origin plus `displayPreviewPath` without a trailing slash, so a preview
+ * link and the entry `src` framing its page match, under the `previewPrefix` mount or not.
+ */
+export declare const previewPageKey: (url: string, mount: PreviewMount, base: string) => string | undefined;

package/dist/editor/preview-path.js

@@ -1,9 +1,27 @@
 import { isAbsoluteUrl, joinUrlPrefix, stripTrailingSlashes } from '../utils/url-prefix.js';
+/**
+ * The query part that asks a `createPreviewPage` route to render the site's header and footer
+ * (`canopycms-next`'s `layout` option). It changes how the page looks, not which page it is.
+ */
+const SITE_CHROME_PART = 'chrome=1';
+/**
+ * `search` without the parts `keep` refuses, as `?…`, or '' when none is left. Filtered as text:
+ * a URLSearchParams round trip would form-encode the rest (`flag` becomes `flag=`, `%20` `+`).
+ */
+const filterQuery = (search, keep) => {
+    const query = search
+        .slice(1)
+        .split('&')
+        .filter((part) => part !== '' && keep(part))
+        .join('&');
+    return query ? `?${query}` : '';
+};
 /**
  * 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
- * by its own location. An absolute `src`, or a host redirect that adds or drops a trailing slash,
- * spells the same page two ways, and the bridge must still match them.
+ * fragment, trailing slash or `chrome=1`. The editor names a page by the `src` it built and the
+ * framed page by its own location. An absolute `src`, a host redirect that adds or drops a
+ * trailing slash, or the site header and footer toggle, spells the same page two ways, and the
+ * bridge must still match them.
  * @internal Exported for tests.
  */
 export const normalizePreviewPath = (url) => {
@@ -14,27 +32,58 @@ export const normalizePreviewPath = (url) => {
     catch {
         return url;
     }
-    return `${stripTrailingSlashes(parsed.pathname) || '/'}${parsed.search}`;
+    const query = filterQuery(parsed.search, (part) => part !== SITE_CHROME_PART);
+    return `${stripTrailingSlashes(parsed.pathname) || '/'}${query}`;
 };
 /** 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 }) => {
+/** The `previewPrefix` mount `url` sits under, and what follows it; `undefined` when not under one. */
+const splitPreviewPrefix = (url, { basePath, previewPrefix }) => {
     if (!previewPrefix || !stripTrailingSlashes(previewPrefix))
-        return url;
+        return undefined;
     const mount = stripTrailingSlashes(joinUrlPrefix(basePath, joinUrlPrefix(previewPrefix, '/')));
     if (!url.startsWith(mount))
-        return url;
+        return undefined;
     const rest = url.slice(mount.length);
-    if (rest !== '' && !/^[/?#]/.test(rest))
+    return rest === '' || /^[/?#]/.test(rest) ? { mount, rest } : undefined;
+};
+/** `url` with the `previewPrefix` mount taken out, so `/base/preview/posts/x` reads `/base/posts/x`. */
+const stripPreviewPrefix = (url, previewMount) => {
+    const split = splitPreviewPrefix(url, previewMount);
+    if (!split)
         return url;
+    const { mount, rest } = split;
     // An absolute prefix skips `basePath`, so the page under it has none either.
-    const base = isAbsoluteUrl(mount) ? '' : stripTrailingSlashes(joinUrlPrefix(basePath, '/'));
+    const base = isAbsoluteUrl(mount)
+        ? ''
+        : stripTrailingSlashes(joinUrlPrefix(previewMount.basePath, '/'));
     return rest.startsWith('/') ? `${base}${rest}` : `${base || '/'}${rest}`;
 };
+/**
+ * `src` asking for the site's header and footer, or `undefined` when it cannot. Only a page under
+ * the `previewPrefix` mount is a `createPreviewPage` route, which reads `chrome=1`; any other URL
+ * is a page of the site itself, which the editor leaves as it is.
+ */
+export const siteChromeSrc = (src, mount = {}) => {
+    if (!splitPreviewPrefix(src, mount))
+        return undefined;
+    const hashIndex = src.indexOf('#');
+    const beforeHash = hashIndex === -1 ? src : src.slice(0, hashIndex);
+    const hash = hashIndex === -1 ? '' : src.slice(hashIndex);
+    const queryIndex = beforeHash.indexOf('?');
+    if (queryIndex !== -1 &&
+        beforeHash
+            .slice(queryIndex + 1)
+            .split('&')
+            .includes(SITE_CHROME_PART)) {
+        return src;
+    }
+    const separator = queryIndex === -1 ? '?' : beforeHash.endsWith('?') ? '' : '&';
+    return `${beforeHash}${separator}${SITE_CHROME_PART}${hash}`;
+};
 /**
  * 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
+ * `previewPrefix` mount, the `branch` query the top bar already names, `chrome=1`, 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.
  */
@@ -47,14 +96,8 @@ export const displayPreviewPath = (src, mount = {}) => {
     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}` : ''}`;
+    const query = filterQuery(parsed.search, (part) => part !== SITE_CHROME_PART && part.split('=', 1)[0] !== 'branch');
+    const path = `${parsed.pathname}${query}`;
     if (!isAbsoluteUrl(url))
         return path;
     // `origin` is 'null' for a scheme the URL spec does not treat as special.
@@ -62,3 +105,21 @@ export const displayPreviewPath = (src, mount = {}) => {
         ? `//${parsed.host}${path}`
         : `${parsed.protocol}//${parsed.host}${path}`;
 };
+/**
+ * The page `url` shows, as origin plus `displayPreviewPath` without a trailing slash, so a preview
+ * link and the entry `src` framing its page match, under the `previewPrefix` mount or not.
+ */
+export const previewPageKey = (url, mount, base) => {
+    let parsed;
+    try {
+        parsed = new URL(url, base);
+    }
+    catch {
+        return undefined;
+    }
+    // A relative mount is a path on the editor's origin, so a URL there is matched to it as a path.
+    const spelled = splitPreviewPrefix(parsed.href, mount) || parsed.origin !== new URL(base).origin
+        ? parsed.href
+        : `${parsed.pathname}${parsed.search}`;
+    return `${parsed.origin}${normalizePreviewPath(displayPreviewPath(spelled, mount))}`;
+};

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

@@ -1,6 +1,6 @@
 import React, { type ComponentPropsWithoutRef, type ReactNode } from 'react';
 export interface ActivityRailProps {
-    /** Rail buttons from the top: the monogram, then the activities. */
+    /** Rail buttons from the top: the activities. */
     top: ReactNode;
     /** Rail buttons pinned to the bottom, such as Settings. */
     bottom?: ReactNode;
@@ -22,8 +22,6 @@ export interface RailButtonProps extends Omit<ComponentPropsWithoutRef<'button'>
     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. */

package/dist/editor/shell/ActivityRail.js

@@ -75,11 +75,11 @@ export function ActivityRail({ top, bottom, account }) {
                 }, 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) {
+export const RailButton = forwardRef(function RailButton({ railId, label, icon, active = 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 }))] }));
+        // Filled when active: a tint alone would show the state by colour, under 3:1.
+        variant: active ? 'filled' : 'subtle', color: active ? 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',

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

@@ -8,6 +8,21 @@ export interface EditorShellProps {
     /** Drawers, modals and palettes, each portalling itself into `<body>`. */
     overlays?: ReactNode;
 }
+/** The line between two shell regions, as under the top bar and a shown banner. */
+export declare const SHELL_REGION_BORDER = "1px solid var(--canopy-input-border)";
+/**
+ * Every resizable divider in the shell, the panel's and the panes', shows this many pixels wide.
+ * Its pointer target is wider, `DIVIDER_TARGET_PX`. A finger's reaches 6px past each side of the
+ * bar: under the panes' separator, the narrow window's overlay panel keeps its header's close
+ * button clear, as that header's top padding is 10px.
+ */
+export declare const DIVIDER_WIDTH_PX = 4;
+export declare const DIVIDER_TARGET_PX: {
+    readonly fine: 12;
+    readonly coarse: 16;
+};
+/** A divider's colour at rest; held, hovered, dragged or focused it takes `--canopy-focus-ring`. */
+export declare const DIVIDER_COLOR = "var(--canopy-input-border)";
 /**
  * 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

package/dist/editor/shell/EditorShell.js

@@ -4,6 +4,22 @@ import { useRef } from 'react';
 import { Portal, getDefaultZIndex } from '@mantine/core';
 import { RemoveScroll } from 'react-remove-scroll';
 import { useHideHostChrome } from './host-chrome.js';
+/** The line between two shell regions, as under the top bar and a shown banner. */
+export const SHELL_REGION_BORDER = '1px solid var(--canopy-input-border)';
+/**
+ * Every resizable divider in the shell, the panel's and the panes', shows this many pixels wide.
+ * Its pointer target is wider, `DIVIDER_TARGET_PX`. A finger's reaches 6px past each side of the
+ * bar: under the panes' separator, the narrow window's overlay panel keeps its header's close
+ * button clear, as that header's top padding is 10px.
+ */
+export const DIVIDER_WIDTH_PX = 4;
+export const DIVIDER_TARGET_PX = { fine: 12, coarse: 16 };
+/** A divider's colour at rest; held, hovered, dragged or focused it takes `--canopy-focus-ring`. */
+export const DIVIDER_COLOR = 'var(--canopy-input-border)';
+// A banner component may render nothing, so the region's line follows its content, not the prop.
+const SHELL_STYLES = `
+[data-canopy-region='banner']:not(:empty) { border-block-end: ${SHELL_REGION_BORDER}; }
+`;
 const gridStyle = {
     position: 'fixed',
     inset: 0,
@@ -27,5 +43,5 @@ const region = (area) => ({ gridArea: area, minWidth: 0, minHeight: 0 });
 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 })] }) })] }));
+    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: [_jsx("style", { children: SHELL_STYLES }), 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/OverlayHeader.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+import { type DrawerRootProps } from '@mantine/core';
+interface OverlayHeaderProps {
+    title: React.ReactNode;
+    /** Sits beside the title and is part of its accessible name, such as a status badge. */
+    adornment?: React.ReactNode;
+    /** For a drawer that moves focus to its title. */
+    titleRef?: React.Ref<HTMLHeadingElement>;
+    titleTabIndex?: number;
+}
+export interface OverlayDrawerProps extends Omit<DrawerRootProps, 'children' | 'title' | 'padding'>, OverlayHeaderProps {
+    children: React.ReactNode;
+}
+/**
+ * A Mantine `Drawer` with an `OverlayHeader`, a blurred backdrop and a body padded under the rule.
+ * It is a `Drawer.Root`, so theme overrides for it go under `DrawerRoot`, not `Drawer`.
+ */
+export declare const OverlayDrawer: React.FC<OverlayDrawerProps>;
+export {};

package/dist/editor/shell/OverlayHeader.js

@@ -0,0 +1,15 @@
+'use client';
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Drawer, Group } from '@mantine/core';
+/**
+ * The header of every right-hand drawer, sized and ruled like the content panel's header in
+ * `SidePanelHost`: a 16px semibold title, a default-size close button, `md` by `xs` padding and a
+ * 1px bottom rule. It is the drawer's own `Drawer.Header`, so the title labels the dialog and the
+ * header stays pinned while the body scrolls.
+ */
+const OverlayHeader = ({ title, adornment, titleRef, titleTabIndex, }) => (_jsxs(Drawer.Header, { mih: 0, px: "md", py: "xs", style: { borderBlockEnd: '1px solid var(--canopy-input-border)' }, children: [_jsx(Drawer.Title, { ref: titleRef, tabIndex: titleTabIndex, fw: 600, fz: "md", miw: 0, children: _jsxs(Group, { component: "span", gap: "xs", wrap: "nowrap", children: [title, adornment] }) }), _jsx(Drawer.CloseButton, { "aria-label": "Close" })] }));
+/**
+ * A Mantine `Drawer` with an `OverlayHeader`, a blurred backdrop and a body padded under the rule.
+ * It is a `Drawer.Root`, so theme overrides for it go under `DrawerRoot`, not `Drawer`.
+ */
+export const OverlayDrawer = ({ title, adornment, titleRef, titleTabIndex, children, ...root }) => (_jsxs(Drawer.Root, { padding: "md", ...root, children: [_jsx(Drawer.Overlay, { blur: 2 }), _jsxs(Drawer.Content, { children: [_jsx(OverlayHeader, { title: title, adornment: adornment, titleRef: titleRef, titleTabIndex: titleTabIndex }), _jsx(Drawer.Body, { pt: "md", children: children })] })] }));

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

@@ -17,6 +17,11 @@ export interface PaneLayoutProps {
     form?: React.ReactNode;
     /** Laid over the form pane, outside its scrolling: the side panel in overlay mode. */
     formOverlay?: React.ReactNode;
+    /**
+     * Stacked arrangement only: docked at the form pane's inline start, pushing the form aside, so
+     * the preview above keeps its full width. A maximized preview leaves it beside it, full height.
+     */
+    formAside?: 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. */
@@ -25,4 +30,4 @@ export interface PaneLayoutProps {
     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;
+export declare function PaneLayout({ arrangement, sideSplitPercent, stackedSplitPercent, onSplitPercentChange, preview, form, formOverlay, formAside, formInert, previewMaximized, onSeparatorDrag, }: PaneLayoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/editor/shell/PaneLayout.js

@@ -1,8 +1,9 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef } from 'react';
 import { Box } from '@mantine/core';
 import { Group, Panel, Separator, useGroupRef } from 'react-resizable-panels';
+import { DIVIDER_COLOR, DIVIDER_TARGET_PX, DIVIDER_WIDTH_PX } from './EditorShell.js';
 export const SPLIT_PERCENT_MIN = 15;
 export const SPLIT_PERCENT_MAX = 85;
 export const DEFAULT_SIDE_SPLIT_PERCENT = 52;
@@ -13,29 +14,35 @@ const FORM = 'canopy-form';
 // 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 ASIDE_TOP = '--canopy-form-aside-top';
+const ASIDE_WIDTH = '--canopy-form-aside-width';
+// The pointer target is the group's `resizeTargetMinimumSize`, wider than the bar it draws. Lifted
+// over the panes' positioned contents, which would otherwise paint over its focus outline.
 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);
+  position: relative;
+  z-index: 1;
+  min-width: ${DIVIDER_WIDTH_PX}px;
+  min-height: ${DIVIDER_WIDTH_PX}px;
+  background: ${DIVIDER_COLOR};
 }
-.canopy-pane-separator:is([data-separator='hover'], [data-separator='active']) {
+.canopy-pane-separator:is([data-separator='hover'], [data-separator='active'], :focus-visible) {
   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, }) {
+export function PaneLayout({ arrangement, sideSplitPercent = DEFAULT_SIDE_SPLIT_PERCENT, stackedSplitPercent = DEFAULT_STACKED_SPLIT_PERCENT, onSplitPercentChange, preview, form, formOverlay, formAside, 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 layoutRef = useRef(null);
+    const asideProbeRef = 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(() => {
@@ -53,6 +60,36 @@ export function PaneLayout({ arrangement, sideSplitPercent = DEFAULT_SIDE_SPLIT_
         formPanelRef.current?.toggleAttribute('inert', previewMaximized);
         separatorRef.current?.toggleAttribute('inert', previewMaximized);
     }, [formInert, previewMaximized]);
+    const aside = arrangement === 'stacked' ? formAside : undefined;
+    const hasAside = Boolean(aside);
+    // The aside precedes the panes in the DOM, so focus reaches it first, as it reaches the shell's
+    // panel column first side by side. It is placed from the form row's measured top, and the form
+    // and a maximized preview start at its measured width. Written straight to CSS variables, so a
+    // drag moves them in the frame it moves the split.
+    useLayoutEffect(() => {
+        const layout = layoutRef.current;
+        if (!layout || !hasAside)
+            return;
+        const measure = () => {
+            const top = layout.getBoundingClientRect().top;
+            const formTop = formPanelRef.current?.getBoundingClientRect().top ?? top;
+            layout.style.setProperty(ASIDE_TOP, `${formTop - top}px`);
+            const width = asideProbeRef.current?.getBoundingClientRect().width ?? 0;
+            layout.style.setProperty(ASIDE_WIDTH, `${width}px`);
+        };
+        measure();
+        // The probe has no height, so moving the aside's top never resizes what is observed.
+        const observer = new ResizeObserver(measure);
+        for (const element of [layout, formPanelRef.current, asideProbeRef.current]) {
+            if (element)
+                observer.observe(element);
+        }
+        return () => {
+            observer.disconnect();
+            layout.style.removeProperty(ASIDE_TOP);
+            layout.style.removeProperty(ASIDE_WIDTH);
+        };
+    }, [hasAside]);
     const onSeparatorDragRef = useRef(onSeparatorDrag);
     useEffect(() => {
         onSeparatorDragRef.current = onSeparatorDrag;
@@ -84,7 +121,19 @@ export function PaneLayout({ arrangement, sideSplitPercent = DEFAULT_SIDE_SPLIT_
         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), 
+    // A maximized preview leaves a docked `aside` beside it, now the layout's full height, as the
+    // shell's own panel column stays beside it in the side arrangement.
+    const maximizedStyle = aside
+        ? { insetBlock: 0, insetInlineEnd: 0, insetInlineStart: `var(${ASIDE_WIDTH}, 0px)` }
+        : { inset: 0 };
+    return (_jsxs("div", { ref: layoutRef, style: { position: 'relative', height: '100%', width: '100%' }, children: [_jsx("style", { children: SEPARATOR_STYLES }), aside && (_jsxs("div", { "data-testid": "form-aside", "data-lifted": previewMaximized || undefined, style: {
+                    position: 'absolute',
+                    insetInlineStart: 0,
+                    bottom: 0,
+                    top: previewMaximized ? 0 : `var(${ASIDE_TOP}, 0px)`,
+                    // Over a maximized preview, which would cover its separator's target and focus ring.
+                    zIndex: previewMaximized ? 3 : 1,
+                }, children: [aside, _jsx("div", { ref: asideProbeRef, "aria-hidden": true, style: { height: 0 } })] })), _jsxs(Group, { groupRef: groupRef, orientation: side ? 'horizontal' : 'vertical', resizeTargetMinimumSize: DIVIDER_TARGET_PX, 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) => {
@@ -100,11 +149,17 @@ export function PaneLayout({ arrangement, sideSplitPercent = DEFAULT_SIDE_SPLIT_
                         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%", 
+                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, 
+                            // Sized in `style`, not by props: Mantine's style props would override the insets.
+                            style: previewMaximized
+                                ? // Over the separator, which sits over the panes.
+                                    { overflow: 'auto', position: 'absolute', zIndex: 2, ...maximizedStyle }
+                                : { overflow: 'auto', width: '100%', height: '100%' }, 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%", 
                             // `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: {
+                            style: {
+                                isolation: 'isolate',
+                                marginInlineStart: aside ? `var(${ASIDE_WIDTH}, 0px)` : undefined,
+                            }, 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)',