@datalayer/primer-addons 1.0.21 → 1.0.23

package/lib/components/sliding-panel/SlidingPanel.stories.js

@@ -1,4 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2021-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
 import { useRef, useState } from 'react';
 import { Box, Button, Heading } from '@primer/react';
 import { SlidingPanel } from './SlidingPanel';

package/lib/components/toolbar/Toolbar.d.ts

@@ -1,3 +1,3 @@
-import type { ToolbarProps } from './types';
-export declare function Toolbar({ items, extraItems, className, disabled, ariaLabel, overflow, }: ToolbarProps): import("react/jsx-runtime").JSX.Element;
+import type { ToolbarProps } from "./types";
+export declare function Toolbar({ items, extraItems, className, disabled, ariaLabel, overflow, }: ToolbarProps): import("react").JSX.Element;
 export default Toolbar;

package/lib/components/toolbar/ToolbarButton.d.ts

@@ -3,6 +3,8 @@ export interface ToolbarButtonProps {
     item: ToolbarButtonItem;
     /** Size variant: 'small' for floating toolbar, 'medium' for fixed toolbar */
     size?: 'small' | 'medium';
+    /** Print `ariaLabel` beside the icon — see the module doc. Off by default. */
+    showLabel?: boolean;
 }
-export declare function ToolbarButton({ item, size }: ToolbarButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolbarButton({ item, size, showLabel, }: ToolbarButtonProps): import("react").JSX.Element;
 export default ToolbarButton;

package/lib/components/toolbar/ToolbarButton.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /*
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
@@ -15,11 +15,21 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * and the tooltip of a disabled action is precisely where the why-disabled
  * explanation lives.
  *
+ * `showLabel` prints that same name beside the icon instead of leaving it in
+ * the tooltip alone. On the toolbar's own line an icon earns its keep — Bold,
+ * Italic, Underline read at a glance, and a name beside each would crowd a
+ * strip already short on room. Inside the "..." overflow menu there is a
+ * whole row to spend and nothing to read at a glance until the pointer
+ * happens to rest on one: a tooltip nobody is hovering says nothing, the way
+ * `ariaLabel` says it whether or not anyone points at the row at all. The
+ * `Toolbar` sets it on that menu alone; a host wiring `ToolbarButton` up on
+ * its own line does not need to know the flag exists.
+ *
  * @module components/toolbar/ToolbarButton
  */
-import { isValidElement } from 'react';
+import { isValidElement, useState } from 'react';
 import { Tooltip } from '@primer/react';
-export function ToolbarButton({ item, size = 'medium' }) {
+export function ToolbarButton({ item, size = 'medium', showLabel = false, }) {
     const { ariaLabel, title, icon, label, isActive, onClick, disabled } = item;
     // Resolve icon → React element.
     // Octicon components use React.forwardRef, which returns an *object*
@@ -41,34 +51,56 @@ export function ToolbarButton({ item, size = 'medium' }) {
         iconElement = _jsx("span", { style: { fontSize: 12, fontWeight: 600, lineHeight: 1 }, children: label });
     }
     const btnSize = size === 'small' ? 28 : 32;
-    const button = (_jsx("button", { type: "button", "aria-label": ariaLabel, "aria-disabled": disabled || undefined, onMouseDown: (e) => e.preventDefault(), onClick: disabled ? undefined : onClick, style: {
+    // Only when there is a name to show, and only where it was asked for:
+    // showLabel with no ariaLabel (should never happen — it is required on
+    // the item — but this keeps a bare icon rather than an empty gap) falls
+    // back to the icon-only layout below.
+    const printLabel = showLabel && Boolean(ariaLabel);
+    /*
+     * Hover, as state rather than as a style written onto the element.
+     *
+     * The `Tooltip` around a titled button replays its `onMouseEnter` from a
+     * timeout, by which time React has cleared the event's `currentTarget`:
+     * writing `e.currentTarget.style` there threw "Cannot read properties of
+     * null (reading 'style')". A ref would not do either — the Tooltip clones
+     * the button with a ref of its own.
+     */
+    const [hovered, setHovered] = useState(false);
+    const lit = hovered && !disabled;
+    const button = (_jsxs("button", { type: "button", "aria-label": ariaLabel, "aria-disabled": disabled || undefined, onMouseDown: (e) => e.preventDefault(), onClick: disabled ? undefined : onClick, style: {
             display: 'inline-flex',
             alignItems: 'center',
-            justifyContent: 'center',
-            width: btnSize,
+            justifyContent: printLabel ? 'flex-start' : 'center',
+            gap: printLabel ? 6 : 0,
+            // No explicit `width` when labelled: sized to its own icon-plus-name
+            // content, the same as `ToolbarDropdown`'s trigger — the two sit in
+            // the same overflow menu, and a button stretched to fill it beside a
+            // dropdown sized to its own text would read as two different kinds
+            // of row rather than one consistent list.
+            width: printLabel ? undefined : btnSize,
+            minWidth: btnSize,
             height: btnSize,
-            padding: 0,
+            padding: printLabel ? '0 8px' : 0,
             margin: 0,
             border: 'none',
             borderRadius: 6,
             cursor: disabled ? 'not-allowed' : 'pointer',
-            background: isActive ? 'var(--bgColor-accent-muted, rgba(9,105,218,0.1))' : 'transparent',
-            color: isActive ? 'var(--fgColor-accent, #0969da)' : 'var(--fgColor-muted, #656d76)',
+            background: lit
+                ? 'var(--bgColor-neutral-muted, rgba(175,184,193,0.2))'
+                : isActive
+                    ? 'var(--bgColor-accent-muted, rgba(9,105,218,0.1))'
+                    : 'transparent',
+            color: lit
+                ? 'var(--fgColor-default, #1f2328)'
+                : isActive
+                    ? 'var(--fgColor-accent, #0969da)'
+                    : 'var(--fgColor-muted, #656d76)',
             opacity: disabled ? 0.5 : 1,
             lineHeight: 1,
-        }, onMouseEnter: (e) => {
-            if (!disabled) {
-                e.currentTarget.style.background = 'var(--bgColor-neutral-muted, rgba(175,184,193,0.2))';
-                e.currentTarget.style.color = 'var(--fgColor-default, #1f2328)';
-            }
-        }, onMouseLeave: (e) => {
-            e.currentTarget.style.background = isActive
-                ? 'var(--bgColor-accent-muted, rgba(9,105,218,0.1))'
-                : 'transparent';
-            e.currentTarget.style.color = isActive
-                ? 'var(--fgColor-accent, #0969da)'
-                : 'var(--fgColor-muted, #656d76)';
-        }, children: iconElement }));
+            fontSize: size === 'small' ? 12 : 14,
+            fontFamily: 'inherit',
+            whiteSpace: 'nowrap',
+        }, onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false), children: [iconElement, printLabel && _jsx("span", { children: ariaLabel })] }));
     // No title: nothing to say, no wrapper to say it with.
     return title ? (_jsx(Tooltip, { text: title, direction: "s", children: button })) : (button);
 }

package/lib/components/toolbar/ToolbarDivider.d.ts

@@ -2,5 +2,5 @@ export interface ToolbarDividerProps {
     /** Orientation: vertical for horizontal toolbars, horizontal for vertical */
     orientation?: 'vertical' | 'horizontal';
 }
-export declare function ToolbarDivider({ orientation }: ToolbarDividerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolbarDivider({ orientation }: ToolbarDividerProps): import("react").JSX.Element;
 export default ToolbarDivider;

package/lib/components/toolbar/ToolbarDropdown.d.ts

@@ -1,8 +1,8 @@
-import type { ToolbarDropdownItem } from './types';
+import type { ToolbarDropdownItem } from "./types";
 export interface ToolbarDropdownProps {
     item: ToolbarDropdownItem;
     /** Size variant */
-    size?: 'small' | 'medium';
+    size?: "small" | "medium";
 }
-export declare function ToolbarDropdown({ item, size }: ToolbarDropdownProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolbarDropdown({ item, size, }: ToolbarDropdownProps): import("react").JSX.Element;
 export default ToolbarDropdown;

package/lib/components/toolbar/ToolbarDropdown.js

@@ -16,9 +16,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * @module components/toolbar/ToolbarDropdown
  */
-import { isValidElement, useMemo } from 'react';
-import { ActionMenu, ActionList, Text } from '@primer/react';
-import { Box } from '../box/Box';
+import { isValidElement, useMemo, useState } from "react";
+import { ActionMenu, ActionList, Text } from "@primer/react";
+import { Box } from "../box/Box";
 /**
  * Resolve an icon prop to a ReactNode.
  *
@@ -38,55 +38,86 @@ function renderIcon(icon) {
 }
 /** Whether any dropdown option in the list has an icon. */
 function hasAnyIcon(options) {
-    return options.some(o => !!o.icon);
+    return options.some((o) => !!o.icon);
 }
-export function ToolbarDropdown({ item, size = 'medium' }) {
+export function ToolbarDropdown({ item, size = "medium", }) {
     const { ariaLabel, icon, label, minWidth, options, disabled } = item;
-    // Highlight the trigger when any option is active.
-    const anyActive = useMemo(() => options.some(o => o.isActive), [options]);
+    const [open, setOpen] = useState(false);
+    /*
+     * When the trigger is highlighted.
+     *
+     * Not simply "an option is active". A dropdown that *selects* something —
+     * the cell type, say — always has exactly one active option, so that rule
+     * painted it in the accent colour permanently: a control that looked
+     * switched on before it had been touched, in a blue that was Primer's
+     * rather than the theme's whenever the accent variable did not reach it.
+     *
+     * A labelled dropdown already shows its current value in the label, so the
+     * highlight tells the reader nothing they cannot see. Only a label-less one
+     * — an icon that means "filter on" — has a state worth colouring, and any
+     * dropdown is worth marking while its menu is open.
+     */
+    const anyActive = useMemo(() => !label && options.some((o) => o.isActive), [label, options]);
     // If any option has an icon we reserve a leading-visual column for all rows.
     const showLeadingVisual = useMemo(() => hasAnyIcon(options), [options]);
-    const btnSize = size === 'small' ? 28 : 32;
-    return (_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Anchor, { children: _jsxs("button", { type: "button", "aria-label": ariaLabel, title: ariaLabel, disabled: disabled, style: {
-                        display: 'inline-flex',
-                        alignItems: 'center',
-                        justifyContent: 'center',
+    const btnSize = size === "small" ? 28 : 32;
+    return (_jsxs(ActionMenu, { open: open, onOpenChange: setOpen, children: [_jsx(ActionMenu.Anchor, { children: _jsxs("button", { type: "button", "aria-label": ariaLabel, title: ariaLabel, disabled: disabled, style: {
+                        display: "inline-flex",
+                        alignItems: "center",
+                        justifyContent: "center",
                         gap: 4,
                         minWidth: btnSize,
                         height: btnSize,
-                        padding: label ? '0 8px' : 0,
+                        padding: label ? "0 8px" : 0,
                         margin: 0,
-                        border: 'none',
+                        border: "none",
                         borderRadius: 6,
-                        cursor: disabled ? 'not-allowed' : 'pointer',
-                        background: anyActive
-                            ? 'var(--bgColor-accent-muted, rgba(9,105,218,0.1))'
-                            : 'transparent',
-                        color: anyActive
-                            ? 'var(--fgColor-accent, #0969da)'
-                            : 'var(--fgColor-muted, #656d76)',
+                        cursor: disabled ? "not-allowed" : "pointer",
+                        /*
+                          Neutral while the menu is open, not accented.
+                          
+                          An accent here is a colour the host has to have defined for this
+                          subtree, and where it has not the browser falls back to Primer's
+                          blue — so the control turned blue the moment it was clicked, in a
+                          hue belonging to no theme on the page. The neutral pair is the
+                          same one the hover state uses, which the theme does define.
+                        */
+                        background: anyActive || open
+                            ? "var(--bgColor-neutral-muted, rgba(175,184,193,0.2))"
+                            : "transparent",
+                        color: anyActive || open
+                            ? "var(--fgColor-default, #1f2328)"
+                            : "var(--fgColor-muted, #656d76)",
                         opacity: disabled ? 0.5 : 1,
-                        fontSize: size === 'small' ? 12 : 14,
-                        fontWeight: 'normal',
-                        fontFamily: 'inherit',
+                        fontSize: size === "small" ? 12 : 14,
+                        fontWeight: "normal",
+                        fontFamily: "inherit",
                         lineHeight: 1,
                     }, onMouseEnter: (e) => {
                         if (!disabled) {
                             e.currentTarget.style.background =
-                                'var(--bgColor-neutral-muted, rgba(175,184,193,0.2))';
-                            e.currentTarget.style.color = 'var(--fgColor-default, #1f2328)';
+                                "var(--bgColor-neutral-muted, rgba(175,184,193,0.2))";
+                            e.currentTarget.style.color = "var(--fgColor-default, #1f2328)";
                         }
                     }, onMouseLeave: (e) => {
-                        e.currentTarget.style.background = anyActive
-                            ? 'var(--bgColor-accent-muted, rgba(9,105,218,0.1))'
-                            : 'transparent';
-                        e.currentTarget.style.color = anyActive
-                            ? 'var(--fgColor-accent, #0969da)'
-                            : 'var(--fgColor-muted, #656d76)';
+                        e.currentTarget.style.background =
+                            anyActive || open
+                                ? "var(--bgColor-neutral-muted, rgba(175,184,193,0.2))"
+                                : "transparent";
+                        e.currentTarget.style.color =
+                            anyActive || open
+                                ? "var(--fgColor-default, #1f2328)"
+                                : "var(--fgColor-muted, #656d76)";
                     }, children: [renderIcon(icon), label && (_jsx("span", { style: {
-                                display: 'inline-block',
+                                display: "inline-block",
                                 minWidth: minWidth ? minWidth : undefined,
-                                textAlign: 'left',
-                            }, children: label }))] }) }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsx(ActionList, { children: options.map(option => (_jsxs(ActionList.Item, { onSelect: option.onClick, disabled: option.disabled, active: option.isActive, children: [showLeadingVisual && (_jsx(ActionList.LeadingVisual, { children: option.icon ? renderIcon(option.icon) : _jsx(Box, { sx: { width: 16 } }) })), _jsxs(Box, { sx: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', width: '100%', gap: 3 }, children: [_jsx(Text, { children: option.label }), option.shortcut && (_jsx(Text, { sx: { color: 'fg.subtle', fontSize: 0, fontFamily: 'mono' }, children: option.shortcut }))] })] }, option.key))) }) })] }));
+                                textAlign: "left",
+                            }, children: label }))] }) }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsx(ActionList, { children: options.map((option) => (_jsxs(ActionList.Item, { onSelect: option.onClick, disabled: option.disabled, active: option.isActive, children: [showLeadingVisual && (_jsx(ActionList.LeadingVisual, { children: option.icon ? (renderIcon(option.icon)) : (_jsx(Box, { sx: { width: 16 } })) })), _jsxs(Box, { sx: {
+                                    display: "flex",
+                                    justifyContent: "space-between",
+                                    alignItems: "center",
+                                    width: "100%",
+                                    gap: 3,
+                                }, children: [_jsx(Text, { children: option.label }), option.shortcut && (_jsx(Text, { sx: { color: "fg.subtle", fontSize: 0, fontFamily: "mono" }, children: option.shortcut }))] })] }, option.key))) }) })] }));
 }
 export default ToolbarDropdown;

package/lib/components/toolbar/ToolbarRenderer.d.ts

@@ -1,11 +1,28 @@
-import type { ToolbarItem } from './types';
+import type { ToolbarItem } from "./types";
 export interface ToolbarRendererProps {
     items: ToolbarItem[];
     disabled?: boolean;
-    size?: 'small' | 'medium';
+    size?: "small" | "medium";
+    /**
+     * Print a button's name beside its icon instead of leaving it in the
+     * tooltip alone — see `ToolbarButton`. Meaningless for a dropdown, which
+     * already shows its own label wherever it is drawn.
+     */
+    showLabel?: boolean;
+    /**
+     * How the caller lays the items out: along a row (a toolbar line, the
+     * default) or down a column (the "..." overflow menu).
+     *
+     * Only dividers read it. A divider is drawn across the direction of travel
+     * — a vertical bar between items on a row, a horizontal rule between groups
+     * in a column. Left vertical in a column it became a 20px-tall empty row
+     * with a 1px line down its left edge, which is exactly what showed under
+     * the last item of every group in the overflow menu.
+     */
+    direction?: "row" | "column";
 }
 /**
  * Sort items by order, then render each one according to its type.
  */
-export declare function ToolbarRenderer({ items, disabled, size }: ToolbarRendererProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolbarRenderer({ items, disabled, size, showLabel, direction, }: ToolbarRendererProps): import("react").JSX.Element;
 export default ToolbarRenderer;

package/lib/components/toolbar/ToolbarRenderer.js

@@ -10,30 +10,30 @@ import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
  *
  * @module components/toolbar/ToolbarRenderer
  */
-import { Fragment } from 'react';
-import { Box } from '../box/Box';
-import { ToolbarButton } from './ToolbarButton';
-import { ToolbarDropdown } from './ToolbarDropdown';
-import { ToolbarDivider } from './ToolbarDivider';
+import { Fragment } from "react";
+import { Box } from "../box/Box";
+import { ToolbarButton } from "./ToolbarButton";
+import { ToolbarDropdown } from "./ToolbarDropdown";
+import { ToolbarDivider } from "./ToolbarDivider";
 /**
  * Sort items by order, then render each one according to its type.
  */
-export function ToolbarRenderer({ items, disabled, size = 'medium' }) {
+export function ToolbarRenderer({ items, disabled, size = "medium", showLabel = false, direction = "row", }) {
     const sorted = [...items]
-        .filter(item => !item.hidden)
+        .filter((item) => !item.hidden)
         .sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
-    return (_jsx(_Fragment, { children: sorted.map(item => {
+    return (_jsx(_Fragment, { children: sorted.map((item) => {
             const itemDisabled = disabled || item.disabled;
             switch (item.type) {
-                case 'button':
-                    return (_jsx(Fragment, { children: _jsx(ToolbarButton, { item: { ...item, disabled: itemDisabled }, size: size }) }, item.key));
-                case 'dropdown':
+                case "button":
+                    return (_jsx(Fragment, { children: _jsx(ToolbarButton, { item: { ...item, disabled: itemDisabled }, size: size, showLabel: showLabel }) }, item.key));
+                case "dropdown":
                     return (_jsx(Fragment, { children: _jsx(ToolbarDropdown, { item: { ...item, disabled: itemDisabled }, size: size }) }, item.key));
-                case 'divider':
-                    return (_jsx(Fragment, { children: _jsx(ToolbarDivider, {}) }, item.key));
-                case 'spacer':
-                    return (_jsx(Box, { sx: { flex: '1 1 auto', minWidth: 8 } }, item.key));
-                case 'custom':
+                case "divider":
+                    return (_jsx(Fragment, { children: _jsx(ToolbarDivider, { orientation: direction === "column" ? "horizontal" : "vertical" }) }, item.key));
+                case "spacer":
+                    return (_jsx(Box, { sx: { flex: "1 1 auto", minWidth: 8 } }, item.key));
+                case "custom":
                     return _jsx(Fragment, { children: item.render() }, item.key);
                 default:
                     return null;

package/lib/components/toolbar/types.d.ts

@@ -1,9 +1,9 @@
-import type { ReactNode } from 'react';
-import type { IconProps } from '@primer/octicons-react';
+import type { ReactNode } from "react";
+import type { IconProps } from "@primer/octicons-react";
 /**
  * Toolbar item types that can be registered in a toolbar.
  */
-export type ToolbarItemType = 'button' | 'dropdown' | 'divider' | 'spacer' | 'custom';
+export type ToolbarItemType = "button" | "dropdown" | "divider" | "spacer" | "custom";
 /**
  * Base toolbar item definition.
  */
@@ -25,7 +25,7 @@ export interface ToolbarItemBase {
  * Toolbar button item definition.
  */
 export interface ToolbarButtonItem extends ToolbarItemBase {
-    type: 'button';
+    type: "button";
     /** Accessible label */
     ariaLabel: string;
     /** Tooltip text */
@@ -64,7 +64,7 @@ export interface ToolbarDropdownOption {
  * Toolbar dropdown item definition.
  */
 export interface ToolbarDropdownItem extends ToolbarItemBase {
-    type: 'dropdown';
+    type: "dropdown";
     /** Accessible label */
     ariaLabel: string;
     /** Tooltip text */
@@ -86,7 +86,7 @@ export interface ToolbarDropdownItem extends ToolbarItemBase {
  * Toolbar divider item definition.
  */
 export interface ToolbarDividerItem extends ToolbarItemBase {
-    type: 'divider';
+    type: "divider";
 }
 /**
  * Toolbar spacer item definition.
@@ -95,13 +95,13 @@ export interface ToolbarDividerItem extends ToolbarItemBase {
  * the trailing edge — e.g. a status indicator kept away from the actions.
  */
 export interface ToolbarSpacerItem extends ToolbarItemBase {
-    type: 'spacer';
+    type: "spacer";
 }
 /**
  * Toolbar custom item definition.
  */
 export interface ToolbarCustomItem extends ToolbarItemBase {
-    type: 'custom';
+    type: "custom";
     /** Custom render function */
     render: () => ReactNode;
 }

package/lib/index.js

@@ -1,3 +1,7 @@
+/*
+ * Copyright (c) 2021-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
 export * from "./components";
 export * from "./utils";
 export * from './theme';

package/lib/reactor/AppearancePlugin.d.ts

@@ -0,0 +1,31 @@
+import type { ReactorReactOutput } from "@datalayer/reactor/react";
+export declare const APPEARANCE_PLUGIN_NAME = "@datalayer/primer-appearance";
+/** The id of the slot component, for a host that looks it up. */
+export declare const APPEARANCE_MENU_COMPONENT_ID = "appearance-menu";
+export type AppearancePluginConfig = {
+    /** The slot the menu renders into. */
+    slot: string;
+    /**
+     * Its place among that slot's components: lower first. High by default, so
+     * the menu sits at the trailing edge of a header, after a view selector.
+     */
+    order: number;
+    /** The trigger's size in pixels. */
+    size: number;
+    /** The trigger's shape. */
+    shape: "square" | "circle";
+    /** Which way the overlay opens from the trigger. */
+    placement: "bottom-start" | "bottom-end";
+    /**
+     * Whether the overlay carries the chosen theme's description and its
+     * preview, or only the circles.
+     */
+    showThemePreviews: boolean;
+    /**
+     * Whether choosing a theme also switches to its default color mode. Off,
+     * as in the public header: a person who chose dark keeps dark.
+     */
+    applyThemeColorMode: boolean;
+};
+export declare const AppearancePlugin: import("@datalayer/reactor").ReactorPlugin<AppearancePluginConfig, unknown, ReactorReactOutput>;
+export default AppearancePlugin;

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;