@datalayer/primer-addons 1.0.20 → 1.0.22

package/lib/reactor/AppearancePlugin.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/primer-appearance` — the appearance menu, as a reactor plugin.
+ *
+ * The control the public Datalayer header wears at its right edge: a small
+ * square showing the color mode which, hovered, opens the appearance overlay
+ * — light, dark and auto as a segmented control; one circle per theme; the
+ * chosen theme's name and description; and a "Show preview" button that
+ * unfolds a live card of it. That is {@link AppearanceMenuWithStore}, and
+ * every reactor host that wanted it wrote the same slot component around it.
+ * This plugin is that component, written once: a host lists the plugin, names
+ * a slot if the default is not `header`, and the menu is there.
+ *
+ * It depends on {@link ThemePlugin}: the menu changes the color mode, and the
+ * theme plugin is what keeps Primer's portals — a palette, a menu — in the
+ * mode chosen. Listing this plugin brings that one along.
+ *
+ * @module reactor/AppearancePlugin
+ */
+import { createElement } from "react";
+import { definePlugin } from "@datalayer/reactor";
+import { AppearanceMenuWithStore } from "../components/appearance/AppearanceMenuWithStore";
+import { ThemePlugin } from "./ThemePlugin";
+export const APPEARANCE_PLUGIN_NAME = "@datalayer/primer-appearance";
+/** The id of the slot component, for a host that looks it up. */
+export const APPEARANCE_MENU_COMPONENT_ID = "appearance-menu";
+export const AppearancePlugin = definePlugin({
+    name: APPEARANCE_PLUGIN_NAME,
+    displayName: "Appearance",
+    description: "The color mode and theme chooser, in the header.",
+    octicon: "paintbrush",
+    emoji: "\u{1F3A8}",
+    dependencies: [ThemePlugin],
+    config: {
+        slot: "header",
+        order: 100,
+        size: 26,
+        shape: "square",
+        placement: "bottom-end",
+        showThemePreviews: true,
+        applyThemeColorMode: false,
+    },
+    build: ({ config }) => ({
+        components: [
+            {
+                id: APPEARANCE_MENU_COMPONENT_ID,
+                slot: config.slot,
+                order: config.order,
+                Component: () => createElement(AppearanceMenuWithStore, {
+                    size: config.size,
+                    shape: config.shape,
+                    hoverOverlayPlacement: config.placement,
+                    showThemePreviews: config.showThemePreviews,
+                    applyThemeColorMode: config.applyThemeColorMode,
+                }),
+            },
+        ],
+    }),
+});
+export default AppearancePlugin;

package/lib/reactor/ThemePlugin.d.ts

@@ -0,0 +1,5 @@
+export declare const THEME_PLUGIN_NAME = "@datalayer/primer-theme";
+/** The command's id, for hosts that want to invoke or rebind it. */
+export declare const TOGGLE_COLOR_MODE_COMMAND = "theme.toggleColorMode";
+export declare const ThemePlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+export default ThemePlugin;

package/lib/reactor/ThemePlugin.js

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/primer-theme` — the Primer theme, as a reactor plugin.
+ *
+ * Every reactor application that portals Primer overlays — a command palette,
+ * a menu — needs the same two lines of glue: `setupPrimerPortals()` before
+ * anything portals, and again on every theme change so the portal root's
+ * `data-color-mode` follows the application. Each host wrote them for itself
+ * (the music example at module load, the LOOP palette inside its build), and
+ * each copy was one theme-change subscription short: a palette opened after a
+ * toggle wore the mode the page started in.
+ *
+ * This plugin is that glue, written once where the theme actually lives. It
+ * sets the portal root up when it registers, follows the shared theme store
+ * and the OS scheme (for `auto`) for as long as it runs, and contributes the
+ * command the copies never had: cycle the color mode, from the palette or by
+ * keystroke.
+ *
+ * It lives beside the theme store rather than in the reactor repo because the
+ * store is the thing being followed — the reactor knows nothing of Primer,
+ * and should not learn.
+ *
+ * @module reactor/ThemePlugin
+ */
+import { definePlugin } from "@datalayer/reactor";
+import { setupPrimerPortals } from "../utils/Portals";
+import { useThemeStore } from "../theme/useThemeStore";
+export const THEME_PLUGIN_NAME = "@datalayer/primer-theme";
+/** The command's id, for hosts that want to invoke or rebind it. */
+export const TOGGLE_COLOR_MODE_COMMAND = "theme.toggleColorMode";
+export const ThemePlugin = definePlugin({
+    name: THEME_PLUGIN_NAME,
+    displayName: "Theme",
+    description: "Keeps Primer portals in the application’s color mode, and toggles it.",
+    octicon: "sun",
+    emoji: "\u{1F317}",
+    commands: [
+        {
+            id: TOGGLE_COLOR_MODE_COMMAND,
+            name: "Toggle the color mode",
+            description: "Switch between light and dark",
+            emoji: "\u{1F317}",
+            category: "Appearance",
+            // Not Mod+Alt+T: on GNOME that is "launch a terminal", grabbed by the
+            // desktop before the browser sees the key, so the command never ran.
+            keybinding: "Mod+Alt+C",
+            execute: () => {
+                // A visible change on every press. The store's own `toggleColorMode`
+                // cycles light → dark → auto, and the step onto `auto` (or off it)
+                // shows nothing when `auto` resolves to the mode already on screen —
+                // so every third press looked like a dud, and from `auto` it took
+                // two. Resolve what is showing and go to the opposite explicit mode;
+                // `auto` remains a choice for the picker.
+                const store = useThemeStore.getState();
+                const showing = store.colorMode === "auto"
+                    ? typeof window !== "undefined" &&
+                        window.matchMedia?.("(prefers-color-scheme: dark)").matches
+                        ? "dark"
+                        : "light"
+                    : store.colorMode;
+                store.setColorMode(showing === "dark" ? "light" : "dark");
+            },
+        },
+    ],
+    register: () => {
+        // Nothing to portal into on a server.
+        if (typeof document === "undefined") {
+            return;
+        }
+        // Before anything portals: the root has to exist, in the right mode,
+        // by the time the first overlay looks for it.
+        setupPrimerPortals(useThemeStore.getState().colorMode);
+        // The user changing their mind. `setupPrimerPortals` is idempotent and
+        // re-reads the theme markers, so following the store is one call.
+        const unsubscribe = useThemeStore.subscribe((state, previous) => {
+            if (state.colorMode !== previous.colorMode) {
+                setupPrimerPortals(state.colorMode);
+            }
+        });
+        // The OS changing its mind, which only matters on `auto`: the store's
+        // value has not moved, but what it resolves to has.
+        const scheme = window.matchMedia("(prefers-color-scheme: dark)");
+        const followScheme = () => {
+            if (useThemeStore.getState().colorMode === "auto") {
+                setupPrimerPortals("auto");
+            }
+        };
+        scheme.addEventListener("change", followScheme);
+        return () => {
+            unsubscribe();
+            scheme.removeEventListener("change", followScheme);
+        };
+    },
+});
+export default ThemePlugin;

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;