@datalayer/primer-addons 1.0.21 → 1.0.23

package/lib/reactor/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The reactor-facing corner of primer-addons.
+ *
+ * Deliberately NOT re-exported from the package's main barrel: importing
+ * anything from here pulls `@datalayer/reactor` into the bundle, and most
+ * consumers of primer-addons are pages with no reactor at all. A host that
+ * wants the plugins imports them by path:
+ *
+ * ```ts
+ * import { AppearancePlugin, ThemePlugin } from '@datalayer/primer-addons/lib/reactor';
+ * ```
+ *
+ * Three plugins. `ThemePlugin` keeps Primer's portals in the application's
+ * color mode and toggles that mode by command. `AppearancePlugin` puts the
+ * appearance menu — color mode, theme, the theme's description and a
+ * preview of it — in a slot, the header by default, and brings the first
+ * along as a dependency. `PageLayoutPlugin` arranges a host's slots as a
+ * page: the work on a centred sheet, a band above it, a side panel opened
+ * from the header — and the layout, its toggle and its signals are exported
+ * on their own for a host that wires the parts itself, as the Loop does.
+ *
+ * @module reactor
+ */
+export { ThemePlugin, THEME_PLUGIN_NAME, TOGGLE_COLOR_MODE_COMMAND, } from "./ThemePlugin";
+export { AppearancePlugin, APPEARANCE_PLUGIN_NAME, APPEARANCE_MENU_COMPONENT_ID, type AppearancePluginConfig, } from "./AppearancePlugin";
+export { PageLayoutPlugin, PAGE_LAYOUT_PLUGIN_NAME, PageLayoutSlots, type PageLayoutPluginConfig, } from "./page-layout/PageLayoutPlugin";
+export { PageLayout, PAGE_SHEET_WIDTH, PAGE_PANEL_WIDTH, PAGE_SIZE_FORMATS, resolvePageSize, type PageLayoutProps, type PageSize, type PageSizeFormat, } from "./page-layout/PageLayout";
+export { PagePanelToggle, type PagePanelToggleProps, } from "./page-layout/PagePanelToggle";
+export { SlotPageLayout, SlotPanelToggle, type SlotPageLayoutProps, } from "./page-layout/SlotPageLayout";
+export { pageLayoutPanelOpen, pageLayoutSheet, pageLayoutActivity, openPagePanel, closePagePanel, togglePagePanel, } from "./page-layout/panelState";

package/lib/reactor/index.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The reactor-facing corner of primer-addons.
+ *
+ * Deliberately NOT re-exported from the package's main barrel: importing
+ * anything from here pulls `@datalayer/reactor` into the bundle, and most
+ * consumers of primer-addons are pages with no reactor at all. A host that
+ * wants the plugins imports them by path:
+ *
+ * ```ts
+ * import { AppearancePlugin, ThemePlugin } from '@datalayer/primer-addons/lib/reactor';
+ * ```
+ *
+ * Three plugins. `ThemePlugin` keeps Primer's portals in the application's
+ * color mode and toggles that mode by command. `AppearancePlugin` puts the
+ * appearance menu — color mode, theme, the theme's description and a
+ * preview of it — in a slot, the header by default, and brings the first
+ * along as a dependency. `PageLayoutPlugin` arranges a host's slots as a
+ * page: the work on a centred sheet, a band above it, a side panel opened
+ * from the header — and the layout, its toggle and its signals are exported
+ * on their own for a host that wires the parts itself, as the Loop does.
+ *
+ * @module reactor
+ */
+export { ThemePlugin, THEME_PLUGIN_NAME, TOGGLE_COLOR_MODE_COMMAND, } from "./ThemePlugin";
+export { AppearancePlugin, APPEARANCE_PLUGIN_NAME, APPEARANCE_MENU_COMPONENT_ID, } from "./AppearancePlugin";
+export { PageLayoutPlugin, PAGE_LAYOUT_PLUGIN_NAME, PageLayoutSlots, } from "./page-layout/PageLayoutPlugin";
+export { PageLayout, PAGE_SHEET_WIDTH, PAGE_PANEL_WIDTH, PAGE_SIZE_FORMATS, resolvePageSize, } from "./page-layout/PageLayout";
+export { PagePanelToggle, } from "./page-layout/PagePanelToggle";
+export { SlotPageLayout, SlotPanelToggle, } from "./page-layout/SlotPageLayout";
+export { pageLayoutPanelOpen, pageLayoutSheet, pageLayoutActivity, openPagePanel, closePagePanel, togglePagePanel, } from "./page-layout/panelState";

package/lib/reactor/page-layout/PageLayout.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The page layout: the work on a centred sheet, like a document.
+ *
+ * A quiet canvas fills the view. On it, one sheet — the page, at a reading
+ * width, with the margins and the shadow a page has — and a band docked
+ * directly above the canvas — or, when the host asks for it, floating over
+ * the canvas as a draggable card — like the toolbar of a document
+ * application, with chips directly under it — or standing in the side panel
+ * under its content, the page bare. With no page to show, the side panel's
+ * content is the page: the same sheet, holding it, and no side panel. While
+ * something works in the page, a small line at the top of the sheet says
+ * what it is doing — "Analyst is adding a cell…" — so the change is seen
+ * where it happens. The panel is a column on the right that opens when it
+ * is wanted — on either side by `panelSide`, and by `panelMode` a column, an
+ * overlay over the page's edge or a small window in its corner; closed, the
+ * page is all there is.
+ *
+ * The sheet is a reading column by default, as tall as what is on it; asked
+ * for a paper (`pageSize`: letter, A4, or a free width and height), it takes
+ * the paper's width and is at least the paper's height.
+ *
+ * The band holds one **mount point**, and that is what gives its content its
+ * width: the same `sheetWidth` column the sheet gets, centred the same way,
+ * inside the same canvas padding. So the band and the page below it are one
+ * column with one pair of edges, and they stay one when the panel opens and
+ * narrows the canvas — because the band lives inside the page column, not
+ * across the whole view. A floating card sizes itself, which is why it never
+ * lines up with anything. It hangs at the top of the canvas, over the chips
+ * and the sheet, which start where they would with no band at all: the flow
+ * keeps no room for the card. What it covers is a drag away, and a strip of
+ * canvas held clear for it was a blank band before the page — worse than a
+ * card over the first lines.
+ *
+ * Nothing here decides what the parts do. A host wires them; this arranges
+ * them. It grew up as the Loop's page layout, where the page is a notebook or
+ * a document, the band is the composer and the panel is the conversation;
+ * the names here are the general ones.
+ *
+ * @module reactor/page-layout/PageLayout
+ */
+import { type JSX, type ReactNode } from "react";
+/** A page reads best at about this width; wider and lines run too long. */
+export declare const PAGE_SHEET_WIDTH = 920;
+/** The side panel, when open. */
+export declare const PAGE_PANEL_WIDTH = 400;
+/**
+ * How the sheet is sized: `free`, or as a sheet of paper.
+ *
+ * `free` is the reading column — `PAGE_SHEET_WIDTH` wide, or the width the
+ * host gives, as tall as its content. `letter` and `a4` are the papers, at
+ * CSS's 96 dots to the inch: the sheet takes their width and is at least
+ * their height, so a short document still reads as a page rather than as a
+ * box shrunk around three lines.
+ */
+export type PageSizeFormat = "free" | "letter" | "a4";
+/** The sheet's size: a format, and free width and height over it. */
+export type PageSize = {
+    /** `free` unless said otherwise. */
+    format?: PageSizeFormat;
+    /** The sheet's width in px. Over a paper format, replaces the paper's. */
+    width?: number;
+    /**
+     * The sheet's least height in px; content past it grows the sheet. Over a
+     * paper format, replaces the paper's. Omitted under `free`: the content's.
+     */
+    height?: number;
+};
+/** The papers, in CSS px (96 to the inch): US Letter 8.5 × 11 in, A4 210 × 297 mm. */
+export declare const PAGE_SIZE_FORMATS: Record<Exclude<PageSizeFormat, "free">, {
+    width: number;
+    height: number;
+}>;
+/**
+ * The width and least height a `PageSize` asks for: the format's, with any
+ * free width or height over it; `sheetWidth` and the content's height when
+ * neither says.
+ */
+export declare function resolvePageSize(size: PageSize | undefined, sheetWidth?: number): {
+    width: number;
+    height?: number;
+};
+export type PageLayoutProps = {
+    /** The page: what lies on the sheet. */
+    page?: ReactNode;
+    /**
+     * Whether there is a page on screen.
+     *
+     * When false, the panel's content lies on the sheet instead, and the page
+     * is kept mounted out of sight — whatever lives in it keeps running —
+     * rather than unmounted. Defaults to whether `page` was given.
+     */
+    hasPage?: boolean;
+    /** The side panel's content: a conversation, an inspector, a list. */
+    panel?: ReactNode;
+    /**
+     * The band above the page: a composer, a toolbar. Docked in a band at the
+     * sheet's width, or floating over the canvas, by `bandMode`. Nothing when
+     * omitted — an empty band is a strip of chrome that does nothing.
+     */
+    band?: ReactNode;
+    /** Chips under the band, above the sheet: openers, quick actions. */
+    chips?: ReactNode;
+    /** A strip above the canvas: a picker, a row of tabs. */
+    picker?: ReactNode;
+    /** Rendered after the canvas, positioned by itself: a transient notice. */
+    transient?: ReactNode;
+    /**
+     * What is happening in the page, pinned to the sheet's top edge while set.
+     * Omitted, the layout reads {@link pageLayoutActivity}.
+     */
+    activity?: string;
+    /**
+     * `docked` (the default): the band above the canvas, at the sheet's width.
+     * `floating`: the band's content is a draggable card at the top of the
+     * canvas, positioned by itself against this layout's root, over the chips
+     * and the sheet — which start at the top of the canvas as if there were
+     * no band; the card covers what it covers. `panel`: the band stands in the
+     * side panel, under the panel's content, with the chips above it; the
+     * page has no band over it at all, and the panel is on screen for as
+     * long as the band is in it, whatever the toggle says.
+     */
+    bandMode?: "docked" | "floating" | "panel";
+    /**
+     * Where the panel stands, when open. `docked` (the default): a column
+     * beside the page, narrowing it. `overlay`: over the page's right edge at
+     * full height, the page untouched under it. `popup`: a small window in
+     * the page's bottom-right corner.
+     */
+    panelMode?: "docked" | "overlay" | "popup";
+    /**
+     * Which side the panel stands on: `right` (the default), or `left`, where
+     * a navigation sidebar belongs. An overlay and a popup follow the same
+     * side, so a left panel slides in over the page's left edge.
+     */
+    panelSide?: "left" | "right";
+    /** The sheet's width; {@link PAGE_SHEET_WIDTH} by default. */
+    sheetWidth?: number;
+    /**
+     * The sheet's size: `free` (the default) at `sheetWidth`, or a paper —
+     * `letter`, `a4` — whose width the sheet takes and whose height it is at
+     * least; a `width` or `height` given here comes before either.
+     */
+    pageSize?: PageSize;
+    /** The panel's width when open; {@link PAGE_PANEL_WIDTH} by default. */
+    panelWidth?: number;
+};
+export declare function PageLayout({ page, hasPage, panel, band, chips, picker, transient, activity, bandMode, panelMode, panelSide, sheetWidth, pageSize, panelWidth, }: PageLayoutProps): JSX.Element;
+export default PageLayout;

package/lib/reactor/page-layout/PageLayout.js

@@ -0,0 +1,326 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The page layout: the work on a centred sheet, like a document.
+ *
+ * A quiet canvas fills the view. On it, one sheet — the page, at a reading
+ * width, with the margins and the shadow a page has — and a band docked
+ * directly above the canvas — or, when the host asks for it, floating over
+ * the canvas as a draggable card — like the toolbar of a document
+ * application, with chips directly under it — or standing in the side panel
+ * under its content, the page bare. With no page to show, the side panel's
+ * content is the page: the same sheet, holding it, and no side panel. While
+ * something works in the page, a small line at the top of the sheet says
+ * what it is doing — "Analyst is adding a cell…" — so the change is seen
+ * where it happens. The panel is a column on the right that opens when it
+ * is wanted — on either side by `panelSide`, and by `panelMode` a column, an
+ * overlay over the page's edge or a small window in its corner; closed, the
+ * page is all there is.
+ *
+ * The sheet is a reading column by default, as tall as what is on it; asked
+ * for a paper (`pageSize`: letter, A4, or a free width and height), it takes
+ * the paper's width and is at least the paper's height.
+ *
+ * The band holds one **mount point**, and that is what gives its content its
+ * width: the same `sheetWidth` column the sheet gets, centred the same way,
+ * inside the same canvas padding. So the band and the page below it are one
+ * column with one pair of edges, and they stay one when the panel opens and
+ * narrows the canvas — because the band lives inside the page column, not
+ * across the whole view. A floating card sizes itself, which is why it never
+ * lines up with anything. It hangs at the top of the canvas, over the chips
+ * and the sheet, which start where they would with no band at all: the flow
+ * keeps no room for the card. What it covers is a drag away, and a strip of
+ * canvas held clear for it was a blank band before the page — worse than a
+ * card over the first lines.
+ *
+ * Nothing here decides what the parts do. A host wires them; this arranges
+ * them. It grew up as the Loop's page layout, where the page is a notebook or
+ * a document, the band is the composer and the panel is the conversation;
+ * the names here are the general ones.
+ *
+ * @module reactor/page-layout/PageLayout
+ */
+import { useEffect } from "react";
+import { Box, Text } from "@primer/react";
+import { useSignalValue } from "@datalayer/reactor/react";
+import { pageLayoutActivity, pageLayoutPanelOpen, pageLayoutSheet, } from "./panelState";
+/** A page reads best at about this width; wider and lines run too long. */
+export const PAGE_SHEET_WIDTH = 920;
+/** The side panel, when open. */
+export const PAGE_PANEL_WIDTH = 400;
+/** The papers, in CSS px (96 to the inch): US Letter 8.5 × 11 in, A4 210 × 297 mm. */
+export const PAGE_SIZE_FORMATS = {
+    letter: { width: 816, height: 1056 },
+    a4: { width: 794, height: 1123 },
+};
+/**
+ * The width and least height a `PageSize` asks for: the format's, with any
+ * free width or height over it; `sheetWidth` and the content's height when
+ * neither says.
+ */
+export function resolvePageSize(size, sheetWidth = PAGE_SHEET_WIDTH) {
+    const paper = size?.format && size.format !== "free"
+        ? PAGE_SIZE_FORMATS[size.format]
+        : undefined;
+    return {
+        width: size?.width ?? paper?.width ?? sheetWidth,
+        height: size?.height ?? paper?.height,
+    };
+}
+/**
+ * The canvas' own gutters, shared by the sheet and the band.
+ *
+ * One constant rather than two literals: the two are only aligned as long as
+ * they are equal, and a column that lines up by coincidence stops lining up
+ * the first time one of them is edited.
+ */
+const CANVAS_PX = [2, 3, 4];
+/** What is happening in the page, pinned to the sheet's top edge. */
+function ActivityLine({ label }) {
+    return (_jsxs(Box, { "data-page-activity": "", role: "status", sx: {
+            position: "sticky",
+            top: 0,
+            zIndex: 2,
+            alignSelf: "flex-start",
+            display: "inline-flex",
+            alignItems: "center",
+            gap: 2,
+            px: 2,
+            py: "4px",
+            borderRadius: "999px",
+            border: "1px solid",
+            borderColor: "accent.muted",
+            bg: "accent.subtle",
+            color: "accent.fg",
+            fontSize: 0,
+            fontWeight: "semibold",
+            whiteSpace: "nowrap",
+            boxShadow: "0 4px 12px -6px rgba(0,0,0,0.3)",
+        }, children: [_jsx(Box, { as: "span", "aria-hidden": "true", sx: {
+                    width: 7,
+                    height: 7,
+                    borderRadius: "50%",
+                    bg: "accent.fg",
+                    animation: "page-activity-dot 1.1s ease-in-out infinite",
+                    "@keyframes page-activity-dot": {
+                        "0%, 100%": { opacity: 1 },
+                        "50%": { opacity: 0.3 },
+                    },
+                } }), _jsx(Text, { children: label })] }));
+}
+export function PageLayout({ page, hasPage = page !== undefined && page !== null, panel, band, chips, picker, transient, activity, bandMode = "docked", panelMode = "docked", panelSide = "right", sheetWidth = PAGE_SHEET_WIDTH, pageSize, panelWidth = PAGE_PANEL_WIDTH, }) {
+    const bandInPanel = bandMode === "panel";
+    const hasBand = band !== undefined && band !== null;
+    // One width for the sheet, the band's mount and the chips: the column.
+    const { width: pageWidth, height: pageHeight } = resolvePageSize(pageSize, sheetWidth);
+    const panelOpen = useSignalValue(pageLayoutPanelOpen);
+    // A panel holding the band is on screen whatever the toggle says: closing
+    // it would take the composer with it.
+    const panelShown = panelOpen || (bandInPanel && hasBand);
+    const announced = useSignalValue(pageLayoutActivity);
+    const activityLabel = activity ?? announced;
+    /*
+     * No page — a host without one, or a view that hid it — and the panel's
+     * content is what lies on the sheet. Told to the parts that only make
+     * sense beside a page, through the shared signal.
+     */
+    const sheet = hasPage ? "page" : "panel";
+    useEffect(() => {
+        pageLayoutSheet.value = sheet;
+    }, [sheet]);
+    return (_jsxs(Box, { "data-page-layout": "", sx: {
+            // The positioned ancestor the out-of-sight parts park against.
+            position: "relative",
+            flex: "1 1 auto",
+            minHeight: 0,
+            display: "flex",
+            flexDirection: "column",
+        }, children: [picker, _jsxs(Box, { sx: {
+                    flex: "1 1 auto",
+                    minHeight: 0,
+                    display: "flex",
+                    // The canvas the sheet lies on: a step darker than the page, so the
+                    // sheet reads as paper rather than as a bordered region of the
+                    // same surface.
+                    bg: "canvas.inset",
+                }, children: [_jsxs(Box, { sx: {
+                            flex: "1 1 auto",
+                            minWidth: 0,
+                            minHeight: 0,
+                            display: "flex",
+                            flexDirection: "column",
+                        }, children: [band && bandMode === "docked" ? (_jsx(Box, { "data-page-band": "", "data-page-prompt-dock": "", sx: {
+                                    flex: "0 0 auto",
+                                    display: "flex",
+                                    justifyContent: "center",
+                                    px: CANVAS_PX,
+                                    // The content brings its own padding, its own border and
+                                    // its own surface; the band only has to carry them the full
+                                    // width of the canvas and close with a rule.
+                                    bg: "canvas.subtle",
+                                    borderBottom: "1px solid",
+                                    borderColor: "border.default",
+                                }, children: _jsx(Box, { sx: { width: "100%", maxWidth: pageWidth, minWidth: 0 }, children: band }) })) : null, _jsxs(Box, { "data-page-canvas": "", sx: {
+                                    flex: "1 1 auto",
+                                    minWidth: 0,
+                                    minHeight: 0,
+                                    // A page's sheet grows with its content and the canvas
+                                    // scrolls; the panel's sheet fills the canvas and scrolls
+                                    // inside, so a conversation keeps following its stream.
+                                    overflowY: hasPage ? "auto" : "hidden",
+                                    overflowX: "hidden",
+                                    display: "flex",
+                                    flexDirection: "column",
+                                    alignItems: "center",
+                                    // The same under a floating card: the chips and the sheet
+                                    // start at the top, and the card hangs over them.
+                                    pt: 3,
+                                    pb: 6,
+                                    px: CANVAS_PX,
+                                }, children: [band && chips && !bandInPanel ? (_jsx(Box, { sx: {
+                                            width: "100%",
+                                            maxWidth: pageWidth,
+                                            mb: 3,
+                                            display: "flex",
+                                            justifyContent: "center",
+                                            "& > *": { justifyContent: "center" },
+                                        }, children: chips })) : null, activityLabel ? (_jsx(Box, { sx: {
+                                            width: "100%",
+                                            maxWidth: pageWidth,
+                                            display: "flex",
+                                            justifyContent: "flex-end",
+                                            mb: 2,
+                                        }, children: _jsx(ActivityLine, { label: activityLabel }) })) : null, _jsx(Box, { "data-page-sheet": "", sx: {
+                                            width: "100%",
+                                            maxWidth: pageWidth,
+                                            /*
+                                              A page's sheet is at least as tall as the canvas, and grows
+                                              past it with its content (`1 0 auto`: grow, never shrink).
+                                              It used to be `0 0 auto`, its content's height only — so
+                                              when the layout was given more room (full screen, a taller
+                                              frame, a resized window) the canvas grew and the page did
+                                              not, leaving an empty band of canvas under a short sheet.
+                                              Flex does the following: nothing is measured, so any
+                                              change in the layout's height reaches the page at once.
+                                            */
+                                            flex: hasPage ? "1 0 auto" : "1 1 auto",
+                                            bg: "canvas.default",
+                                            border: "1px solid",
+                                            borderColor: "border.default",
+                                            borderRadius: "10px",
+                                            boxShadow: "0 1px 2px rgba(0,0,0,0.06), 0 24px 48px -28px rgba(0,0,0,0.35)",
+                                            // The page's own margins. A page fills the sheet and reads
+                                            // against these, as text on paper does; a panel's content
+                                            // brings its own gutters, so it sits closer.
+                                            px: hasPage ? [3, 4, "56px"] : [2, 3, 4],
+                                            py: hasPage ? [3, 4, 4] : 2,
+                                            // What is on the sheet positions its hidden siblings
+                                            // against this.
+                                            position: "relative",
+                                            display: "flex",
+                                            // A paper's height when the size names one: the sheet is at
+                                            // least that tall, and grows past it with its content.
+                                            minHeight: hasPage ? (pageHeight ?? 480) : 0,
+                                            /*
+                                            The page fills the sheet, not the viewport: the sheet grows
+                                            with its content and the canvas scrolls, which is what makes
+                                            it a page.
+                                          */
+                                            "& > *": { flex: "1 1 auto", minWidth: 0 },
+                                        }, children: hasPage ? page : panel }), hasPage || !page ? null : (_jsx(Box, { "aria-hidden": "true", sx: {
+                                            position: "absolute",
+                                            inset: 0,
+                                            visibility: "hidden",
+                                            pointerEvents: "none",
+                                            zIndex: -1,
+                                            display: "flex",
+                                        }, children: page }))] })] }), !hasPage || !panel ? null : (_jsxs(Box, { "data-page-panel": panelShown ? "" : undefined, "data-page-panel-mode": panelMode, "aria-hidden": panelShown ? undefined : "true", sx: {
+                            minWidth: 0,
+                            minHeight: 0,
+                            display: "flex",
+                            flexDirection: "column",
+                            bg: "canvas.default",
+                            borderColor: "border.default",
+                            ...(!panelShown
+                                ? {
+                                    // Out of sight, and out of the way of the pointer, while
+                                    // whatever is in it goes on running. No `z-index` here:
+                                    // it would make a stacking context, and the composer —
+                                    // which lives in this column whether the panel is open or
+                                    // not — has to be able to float over the page from it.
+                                    position: "absolute",
+                                    inset: 0,
+                                    visibility: "hidden",
+                                    pointerEvents: "none",
+                                    overflow: "visible",
+                                }
+                                : panelMode === "docked"
+                                    ? {
+                                        flex: `0 0 ${panelWidth}px`,
+                                        maxWidth: "45%",
+                                        order: panelSide === "left" ? -1 : undefined,
+                                        [panelSide === "left" ? "borderRight" : "borderLeft"]: "1px solid",
+                                        // Over the canvas, and beside the band rather than under
+                                        // it: the band belongs to the page column.
+                                        zIndex: 1,
+                                    }
+                                    : panelMode === "overlay"
+                                        ? {
+                                            // Over the page's right edge, the page untouched
+                                            // under it; against the root, as the float is.
+                                            position: "absolute",
+                                            top: 0,
+                                            bottom: 0,
+                                            [panelSide]: 0,
+                                            width: panelWidth,
+                                            maxWidth: "85%",
+                                            [panelSide === "left" ? "borderRight" : "borderLeft"]: "1px solid",
+                                            boxShadow: "shadow.large",
+                                            zIndex: 5,
+                                        }
+                                        : {
+                                            // A window in the page's corner.
+                                            position: "absolute",
+                                            [panelSide]: 16,
+                                            bottom: 16,
+                                            width: panelWidth,
+                                            maxWidth: "calc(100% - 32px)",
+                                            height: "min(70%, 560px)",
+                                            border: "1px solid",
+                                            borderRadius: 2,
+                                            boxShadow: "shadow.large",
+                                            overflow: "hidden",
+                                            zIndex: 5,
+                                        }),
+                        }, children: [_jsx(Box, { sx: {
+                                    flex: "1 1 auto",
+                                    minHeight: 0,
+                                    display: "flex",
+                                    flexDirection: "column",
+                                    "& > *": { flex: "1 1 auto", minHeight: 0 },
+                                }, children: panel }), hasBand && bandMode !== "docked" ? (_jsxs(Box, { "data-page-panel-band": bandInPanel ? "" : undefined, sx: bandInPanel
+                                    ? {
+                                        flex: "0 0 auto",
+                                        borderTop: "1px solid",
+                                        borderColor: "border.default",
+                                        // Visible even while the column itself is hidden —
+                                        // which it is until something opens the panel.
+                                        visibility: "visible",
+                                        pointerEvents: "auto",
+                                        "& > *": { justifyContent: "center" },
+                                    }
+                                    : {
+                                        /* The card positions itself against this layout's
+                                           root; this only has to stay out of its way, and
+                                           stay visible when the column around it is not. */
+                                        position: "absolute",
+                                        inset: 0,
+                                        visibility: "visible",
+                                        pointerEvents: "none",
+                                        "& > *": { pointerEvents: "auto" },
+                                    }, children: [bandInPanel ? chips : null, band] })) : null] }))] }), transient] }));
+}
+export default PageLayout;

package/lib/reactor/page-layout/PageLayoutPlugin.d.ts

@@ -0,0 +1,59 @@
+import type { ReactorReactOutput } from "@datalayer/reactor/react";
+import type { Icon } from "@primer/octicons-react";
+import type { PageSize } from "./PageLayout";
+export declare const PAGE_LAYOUT_PLUGIN_NAME = "@datalayer/primer-page-layout";
+/** The slots the plugin opens, by their default names. */
+export declare const PageLayoutSlots: {
+    readonly page: "page";
+    readonly band: "page-band";
+    readonly panel: "page-panel";
+    readonly chips: "page-chips";
+};
+export type PageLayoutPluginConfig = {
+    /** The slot the layout renders into. */
+    slot: string;
+    /** Its place among that slot's components; lower first. */
+    order: number;
+    /** The slot the panel toggle renders into. Empty for no toggle. */
+    headerSlot: string;
+    /**
+     * The toggle's place among the header's components. Fifty by default:
+     * after a view selector, before an appearance menu at a hundred.
+     */
+    toggleOrder: number;
+    /** What the toggle's label calls the panel: "Show the conversation". */
+    panelName: string;
+    /** The toggle's glyph; the sidebar octicon by default. */
+    toggleIcon?: Icon;
+    /** The slot for what lies on the sheet. */
+    pageSlot: string;
+    /** The slot for the band above the page. */
+    bandSlot: string;
+    /** The slot for the side panel. */
+    panelSlot: string;
+    /** The slot for the chips under the band. */
+    chipsSlot: string;
+    /**
+     * Whether the band is docked at the sheet's width, floats over the canvas,
+     * or stands in the side panel under its content.
+     */
+    band: "docked" | "floating" | "panel";
+    /** Where the panel stands: beside the page, over its edge, or in its corner. */
+    panel: "docked" | "overlay" | "popup";
+    /** Which side it stands on. `right` by default; `left` for a nav sidebar. */
+    panelSide: "left" | "right";
+    /** Whether the panel is open when the page first draws. */
+    panelOpen: boolean;
+    /** The sheet's width, in pixels. */
+    sheetWidth?: number;
+    /**
+     * The sheet's size: free (the default) at `sheetWidth`, or a paper —
+     * `{ format: "letter" }`, `{ format: "a4" }` — with a free `width` or
+     * `height` over it.
+     */
+    pageSize?: PageSize;
+    /** The open panel's width, in pixels. */
+    panelWidth?: number;
+};
+export declare const PageLayoutPlugin: import("@datalayer/reactor").ReactorPlugin<PageLayoutPluginConfig, unknown, ReactorReactOutput>;
+export default PageLayoutPlugin;