nexus-shared 1.1.20 → 2.0.0

package/dist/Client.Index.d.ts

@@ -0,0 +1,44 @@
+export * from "./Components/Documents/Menu.tsx";
+export * from "./Components/Documents/SplitButton.tsx";
+export * from "./Components/Documents/TabButtons.tsx";
+export * from "./Components/Forms/ApiForm.tsx";
+export * from "./Components/Forms/Crud.tsx";
+export * from "./Components/Forms/CrudParts.tsx";
+export * from "./Components/Forms/Form.tsx";
+export * from "./Components/Forms/SubmitForm.tsx";
+export * from "./Components/Inputs/Calendar.tsx";
+export * from "./Components/Inputs/CheckBox.tsx";
+export * from "./Components/Inputs/CheckBoxGroup.tsx";
+export * from "./Components/Inputs/DatePicker.tsx";
+export * from "./Components/Inputs/DateRangePicker.tsx";
+export * from "./Components/Inputs/DateTimePicker.tsx";
+export * from "./Components/Inputs/Dropdown.tsx";
+export * from "./Components/Inputs/GroupForm.tsx";
+export * from "./Components/Inputs/InputRenderer.tsx";
+export * from "./Components/Inputs/MarkdownEditor.tsx";
+export * from "./Components/Inputs/NumberBox.tsx";
+export * from "./Components/Inputs/RadioGroup.tsx";
+export * from "./Components/Inputs/ReadOnlyNotice.tsx";
+export * from "./Components/Inputs/RichTextEditor.tsx";
+export * from "./Components/Inputs/Slider.tsx";
+export * from "./Components/Inputs/TabularForm.tsx";
+export * from "./Components/Inputs/TextArea.tsx";
+export * from "./Components/Inputs/TextBox.tsx";
+export * from "./Components/Inputs/TimePanel.tsx";
+export * from "./Components/Inputs/TimePicker.tsx";
+export * from "./Components/Inputs/TreeView.tsx";
+export * from "./Components/Layouts/MessageBox.tsx";
+export * from "./Components/Layouts/Popup.tsx";
+export * from "./Components/Layouts/PopupDock.tsx";
+export * from "./Components/Layouts/PopupHost.tsx";
+export * from "./Components/Layouts/PopupRules.ts";
+export * from "./Components/Layouts/ThemePicker.tsx";
+export * from "./Components/Layouts/ThemeSwitcher.tsx";
+export * from "./Components/Layouts/Toaster.tsx";
+export * from "./Components/Viewers/DataTable.tsx";
+export * from "./Components/Viewers/DataTableParts.tsx";
+export * from "./Helpers/DatePreferences.ts";
+export * from "./Helpers/DragHelpers.ts";
+export * from "./Helpers/PopoverHelpers.ts";
+export * from "./Services/BrowserApi.ts";
+export * from "./Services/ThemeService.ts";

package/dist/Client.Index.js

@@ -0,0 +1,49 @@
+// Client components and browser services: files here start with "use client" or use browser APIs.
+// Import from "nexus-shared/client".
+// Components
+export * from "./Components/Documents/Menu.js";
+export * from "./Components/Documents/SplitButton.js";
+export * from "./Components/Documents/TabButtons.js";
+export * from "./Components/Forms/ApiForm.js";
+export * from "./Components/Forms/Crud.js";
+export * from "./Components/Forms/CrudParts.js";
+export * from "./Components/Forms/Form.js";
+export * from "./Components/Forms/SubmitForm.js";
+export * from "./Components/Inputs/Calendar.js";
+export * from "./Components/Inputs/CheckBox.js";
+export * from "./Components/Inputs/CheckBoxGroup.js";
+export * from "./Components/Inputs/DatePicker.js";
+export * from "./Components/Inputs/DateRangePicker.js";
+export * from "./Components/Inputs/DateTimePicker.js";
+export * from "./Components/Inputs/Dropdown.js";
+export * from "./Components/Inputs/GroupForm.js";
+export * from "./Components/Inputs/InputRenderer.js";
+export * from "./Components/Inputs/MarkdownEditor.js";
+export * from "./Components/Inputs/NumberBox.js";
+export * from "./Components/Inputs/RadioGroup.js";
+export * from "./Components/Inputs/ReadOnlyNotice.js";
+export * from "./Components/Inputs/RichTextEditor.js";
+export * from "./Components/Inputs/Slider.js";
+export * from "./Components/Inputs/TabularForm.js";
+export * from "./Components/Inputs/TextArea.js";
+export * from "./Components/Inputs/TextBox.js";
+export * from "./Components/Inputs/TimePanel.js";
+export * from "./Components/Inputs/TimePicker.js";
+export * from "./Components/Inputs/TreeView.js";
+export * from "./Components/Layouts/MessageBox.js";
+export * from "./Components/Layouts/Popup.js";
+export * from "./Components/Layouts/PopupDock.js";
+export * from "./Components/Layouts/PopupHost.js";
+export * from "./Components/Layouts/PopupRules.js";
+export * from "./Components/Layouts/ThemePicker.js";
+export * from "./Components/Layouts/ThemeSwitcher.js";
+export * from "./Components/Layouts/Toaster.js";
+export * from "./Components/Viewers/DataTable.js";
+export * from "./Components/Viewers/DataTableParts.js";
+// Helpers
+export * from "./Helpers/DatePreferences.js";
+export * from "./Helpers/DragHelpers.js";
+export * from "./Helpers/PopoverHelpers.js";
+// Services
+export * from "./Services/BrowserApi.js";
+export * from "./Services/ThemeService.js";

package/dist/Components/Documents/Button.d.ts

@@ -0,0 +1,29 @@
+import type { ComponentPropsWithRef, ReactNode } from "react";
+import type { Size, Tone } from "../../Interfaces/TypeInterfaces.ts";
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
+export type ButtonHoverTone = Exclude<Tone, "neutral">;
+export interface ButtonProps extends ComponentPropsWithRef<"button"> {
+    /** Default `secondary`. Use one `primary` per area for the main action. */
+    variant?: ButtonVariant;
+    /** Default `md`. */
+    size?: Size;
+    /**
+     * Keeps a `secondary` or `ghost` button neutral until hover or keyboard focus, then shows this color
+     * on the border, a light background, and the text. For actions that should not shout in a list or table,
+     * e.g. `hoverTone="danger"` on Delete.
+     */
+    hoverTone?: ButtonHoverTone;
+    /** Icon before the label, e.g. `<InlineIcon icon={iconPlus} />` or `<Icon name="wifi" />`. */
+    icon?: ReactNode;
+    /** Icon after the label. */
+    iconEnd?: ReactNode;
+    /** Shows a spinner in place of `icon` and blocks clicks while an action runs. */
+    loading?: boolean;
+    /** Fills the width of its container. */
+    block?: boolean;
+}
+/**
+ * A button. Without children it becomes a square icon button, which then needs an `aria-label`.
+ * Has no client state, so it renders in server and client components alike.
+ */
+export declare function Button({ variant, size, hoverTone, icon, iconEnd, loading, block, type, disabled, className, children, ...rest }: ButtonProps): import("react").JSX.Element;

package/dist/Components/Documents/Button.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { InlineIcon, iconLoader2 } from "nexus-icons";
+import { cx } from "../../Helpers/ClassHelpers.js";
+/**
+ * A button. Without children it becomes a square icon button, which then needs an `aria-label`.
+ * Has no client state, so it renders in server and client components alike.
+ */
+export function Button({ variant = "secondary", size = "md", hoverTone, icon, iconEnd, loading = false, block = false, type = "button", disabled, className, children, ...rest }) {
+    const hasLabel = children !== undefined && children !== null && children !== false;
+    return (_jsxs("button", { type: type, className: cx("nx-btn", `nx-btn--${variant}`, `nx-btn--${size}`, hoverTone && `nx-btn--hover-${hoverTone}`, block && "nx-btn--block", !hasLabel && "nx-btn--icon", className), disabled: disabled || loading, "aria-busy": loading || undefined, ...rest, children: [loading ? _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) : icon, hasLabel && _jsx("span", { className: "nx-btn__label", children: children }), iconEnd] }));
+}

package/dist/Components/Documents/Menu.d.ts

@@ -0,0 +1,102 @@
+import { type KeyboardEvent, type MouseEvent, type PointerEvent, type ReactElement, type ReactNode, type Ref, type ToggleEvent } from "react";
+import { type PopoverAlign } from "../../Helpers/PopoverHelpers.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export interface MenuItem<T extends string = string> {
+    value: T;
+    label: ReactNode;
+    /** A second line in muted text: what the action does, or when to use it. */
+    description?: ReactNode;
+    /** Icon before the label, e.g. `<InlineIcon icon={iconPencil} />`. */
+    icon?: ReactNode;
+    /** Shown at the end in muted text, e.g. "Ctrl+C". Display only: the page binds the key itself. */
+    shortcut?: string;
+    /** `danger` draws the item in the danger color, for Delete and the like. */
+    tone?: "danger";
+    disabled?: boolean;
+    /** Renders the item as a link. */
+    href?: string;
+    /** The link's target, e.g. `_blank`. */
+    target?: string;
+    /** In a `radio` or `checkbox` menu: the item shows a check mark. */
+    checked?: boolean;
+    /** Tooltip. */
+    title?: string;
+}
+/** A line between groups of items. */
+export interface MenuSeparator {
+    separator: true;
+}
+/** A small heading above a group of items. */
+export interface MenuHeading {
+    heading: ReactNode;
+}
+export type MenuEntry<T extends string = string> = MenuItem<T> | MenuSeparator | MenuHeading;
+export declare function isMenuItem<T extends string>(entry: MenuEntry<T>): entry is MenuItem<T>;
+/** `menu`: actions. `radio`: one item is checked at a time. `checkbox`: any number of items can be checked. */
+export type MenuKind = "menu" | "radio" | "checkbox";
+export interface MenuPanelProps<T extends string = string> {
+    id: string;
+    items: readonly MenuEntry<T>[];
+    /** Called with the item's value when it is chosen by click, Enter, or Space. */
+    onSelect?: (value: T, item: MenuItem<T>) => void;
+    /** Default `menu`. */
+    kind?: MenuKind;
+    /** Default `md`. */
+    size?: Size;
+    /** Closes the menu once an item is chosen. Default true; `false` suits checkbox menus. */
+    closeOnSelect?: boolean;
+    className?: string;
+    ref: Ref<HTMLDivElement>;
+    onToggle?: (event: ToggleEvent<HTMLDivElement>) => void;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}
+/**
+ * The list of a menu inside a native popover. Arrow keys move between items, Home and End jump, a letter jumps to
+ * the next item starting with it, Enter or Space chooses, Esc closes, and Tab closes and moves on.
+ */
+export declare function MenuPanel<T extends string>({ id, items, onSelect, kind, size, closeOnSelect, className, ref, onToggle, ...labelling }: MenuPanelProps<T>): import("react").JSX.Element;
+/** What `Menu` adds to its trigger. A component used as the trigger must pass these on to its button. */
+export interface MenuTriggerProps {
+    ref?: Ref<HTMLButtonElement>;
+    id?: string;
+    "aria-haspopup"?: "menu";
+    "aria-expanded"?: boolean;
+    "aria-controls"?: string;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    onPointerDown?: (event: PointerEvent<HTMLButtonElement>) => void;
+    onKeyDown?: (event: KeyboardEvent<HTMLButtonElement>) => void;
+}
+export interface MenuProps<T extends string = string> extends Pick<MenuPanelProps<T>, "items" | "onSelect" | "kind" | "size" | "closeOnSelect" | "className"> {
+    /** The button that opens the menu, such as a `Button`. It receives an id, aria attributes, and click and key handlers. */
+    children: ReactElement<MenuTriggerProps>;
+    /** Which edge of the button the menu lines up with. Default `start`. */
+    align?: PopoverAlign;
+    /** Name of the menu for screen readers. Default: the button's text. */
+    "aria-label"?: string;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A dropdown menu: a button that opens a list of actions in a native popover under it (above it when there is no
+ * room). Click or Enter opens it, ArrowDown opens it on the first item, Esc closes it and returns focus to the button.
+ *
+ * @example
+ * <Menu items={items} onSelect={value => run(value)}>
+ *   <Button iconEnd={<InlineIcon icon={iconChevronDown} />}>Actions</Button>
+ * </Menu>
+ */
+export declare function Menu<T extends string>({ children, align, "aria-label": ariaLabel, onOpenChange, ...panelProps }: MenuProps<T>): import("react").JSX.Element;
+export interface ContextMenuProps<T extends string = string> extends Pick<MenuPanelProps<T>, "items" | "onSelect" | "kind" | "size" | "closeOnSelect" | "className"> {
+    /** The content the menu belongs to: a row, a card, a list. */
+    children: ReactNode;
+    /** Name of the menu for screen readers. Default "Context menu". */
+    "aria-label"?: string;
+    /** Leaves the browser's own menu in place. */
+    disabled?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A menu that opens where the user right-clicks (or presses Shift+F10) over its content, kept inside the window.
+ * The wrapper takes no space of its own (`display: contents`), so it can wrap a table row or a grid cell.
+ */
+export declare function ContextMenu<T extends string>({ children, "aria-label": ariaLabel, disabled, onOpenChange, ...panelProps }: ContextMenuProps<T>): import("react").JSX.Element;

package/dist/Components/Documents/Menu.js

@@ -0,0 +1,238 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconCheck, InlineIcon } from "nexus-icons";
+import { cloneElement, useId, useLayoutEffect, useRef, useState, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { followAnchor, isPopoverOpen, placeAtPoint, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+export function isMenuItem(entry) {
+    return "value" in entry;
+}
+const ITEM_ROLE = {
+    menu: "menuitem",
+    radio: "menuitemradio",
+    checkbox: "menuitemcheckbox",
+};
+const ENABLED_ITEM = '.nx-menu__item:not([aria-disabled="true"])';
+function enabledItems(panel) {
+    return Array.from(panel.querySelectorAll(ENABLED_ITEM));
+}
+/** Focuses the item at `index`, counting from the end when negative and wrapping past either end. */
+function focusItemAt(panel, index) {
+    const items = enabledItems(panel);
+    if (items.length === 0)
+        return;
+    items[((index % items.length) + items.length) % items.length]?.focus();
+}
+function canShow(panel) {
+    return Boolean(panel && typeof panel.showPopover === "function");
+}
+function hide(panel) {
+    if (isPopoverOpen(panel))
+        panel?.hidePopover();
+}
+function mergeRefs(...refs) {
+    return node => {
+        for (const ref of refs) {
+            if (typeof ref === "function")
+                ref(node);
+            else if (ref)
+                ref.current = node;
+        }
+    };
+}
+/**
+ * The list of a menu inside a native popover. Arrow keys move between items, Home and End jump, a letter jumps to
+ * the next item starting with it, Enter or Space chooses, Esc closes, and Tab closes and moves on.
+ */
+export function MenuPanel({ id, items, onSelect, kind = "menu", size = "md", closeOnSelect = true, className, ref, onToggle, ...labelling }) {
+    function choose(item, event) {
+        if (item.disabled) {
+            event.preventDefault();
+            return;
+        }
+        onSelect?.(item.value, item);
+        if (closeOnSelect)
+            hide(event.currentTarget.closest(".nx-menu"));
+    }
+    function onKeyDown(event) {
+        const panel = event.currentTarget;
+        const items = enabledItems(panel);
+        const current = items.indexOf(document.activeElement);
+        const { key } = event;
+        if (key === "ArrowDown")
+            focusItemAt(panel, current + 1);
+        else if (key === "ArrowUp")
+            focusItemAt(panel, current < 0 ? -1 : current - 1);
+        else if (key === "Home")
+            focusItemAt(panel, 0);
+        else if (key === "End")
+            focusItemAt(panel, -1);
+        else if (key === "Tab") {
+            // The menu closes and focus returns to its button, so Tab moves on from there.
+            hide(panel);
+            return;
+        }
+        else if (key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey && key !== " ") {
+            // A letter jumps to the next item that starts with it.
+            const letter = key.toLowerCase();
+            const from = current + 1;
+            const match = items.slice(from).concat(items.slice(0, from)).find(item => item.textContent?.trim().toLowerCase().startsWith(letter));
+            if (match)
+                match.focus();
+            else
+                return;
+        }
+        else
+            return;
+        event.preventDefault();
+    }
+    // Focus follows the pointer, so the arrow keys carry on from the item under it. Only a pointer that moved counts:
+    // a menu opened from the keyboard under a resting pointer keeps the focus on its first item.
+    const pointerRef = useRef({ x: 0, y: 0 });
+    function onPointerMove(event) {
+        const last = pointerRef.current;
+        if (event.clientX === last.x && event.clientY === last.y)
+            return;
+        pointerRef.current = { x: event.clientX, y: event.clientY };
+        const item = event.currentTarget;
+        if (item.getAttribute("aria-disabled") !== "true" && document.activeElement !== item)
+            item.focus();
+    }
+    const role = ITEM_ROLE[kind];
+    // When any item has an icon, every item keeps the icon column, so the labels line up.
+    const hasIcons = items.some(entry => isMenuItem(entry) && entry.icon);
+    return (_jsx("div", { ref: ref, id: id, popover: "auto", role: "menu", tabIndex: -1, className: cx("nx-popover", "nx-menu", `nx-menu--${size}`, className), onToggle: onToggle, onKeyDown: onKeyDown, ...labelling, children: items.map((entry, index) => {
+            if (!isMenuItem(entry)) {
+                if ("separator" in entry)
+                    return _jsx("div", { role: "separator", className: "nx-menu__separator" }, index);
+                return (_jsx("div", { role: "presentation", className: "nx-menu__heading", children: entry.heading }, index));
+            }
+            const item = entry;
+            const content = (_jsxs(_Fragment, { children: [kind !== "menu" && _jsx("span", { className: "nx-menu__check", children: item.checked && _jsx(InlineIcon, { icon: iconCheck }) }), hasIcons && _jsx("span", { className: "nx-menu__icon", children: item.icon }), _jsxs("span", { className: "nx-menu__body", children: [_jsx("span", { className: "nx-menu__label", children: item.label }), item.description && _jsx("span", { className: "nx-menu__description", children: item.description })] }), item.shortcut && _jsx("kbd", { className: "nx-menu__shortcut", children: item.shortcut })] }));
+            const shared = {
+                role,
+                className: cx("nx-menu__item", item.tone === "danger" && "nx-menu__item--danger", item.checked && "nx-menu__item--checked"),
+                tabIndex: -1,
+                title: item.title,
+                "aria-disabled": item.disabled || undefined,
+                "aria-checked": kind === "menu" ? undefined : Boolean(item.checked),
+                onPointerMove,
+            };
+            return item.href && !item.disabled ? (_jsx("a", { ...shared, href: item.href, target: item.target, rel: item.target === "_blank" ? "noopener" : undefined, onClick: event => choose(item, event), children: content }, item.value)) : (_jsx("button", { ...shared, type: "button", onClick: event => choose(item, event), children: content }, item.value));
+        }) }));
+}
+/**
+ * A dropdown menu: a button that opens a list of actions in a native popover under it (above it when there is no
+ * room). Click or Enter opens it, ArrowDown opens it on the first item, Esc closes it and returns focus to the button.
+ *
+ * @example
+ * <Menu items={items} onSelect={value => run(value)}>
+ *   <Button iconEnd={<InlineIcon icon={iconChevronDown} />}>Actions</Button>
+ * </Menu>
+ */
+export function Menu({ children, align = "start", "aria-label": ariaLabel, onOpenChange, ...panelProps }) {
+    const id = useId();
+    const triggerId = children.props.id ?? `${id}-trigger`;
+    const panelId = `${id}-menu`;
+    const triggerRef = useRef(null);
+    const panelRef = useRef(null);
+    const [open, setOpen] = useState(false);
+    // Set on pointer down while the menu is open: that press closes the menu (light dismiss), and its click must not reopen it.
+    const dismissingRef = useRef(false);
+    function place() {
+        const panel = panelRef.current;
+        const trigger = triggerRef.current;
+        if (panel && trigger)
+            placeUnderAnchor(panel, trigger.getBoundingClientRect(), { align });
+    }
+    function show(focus) {
+        const panel = panelRef.current;
+        if (!canShow(panel) || isPopoverOpen(panel))
+            return;
+        panel.showPopover();
+        place();
+        if (focus === "panel")
+            panel.focus();
+        else
+            focusItemAt(panel, focus === "first" ? 0 : -1);
+    }
+    // The panel is fixed, so it follows the button while the page scrolls or the window changes size.
+    useLayoutEffect(() => {
+        if (!open)
+            return;
+        return followAnchor(place);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open, align]);
+    function onToggle(event) {
+        const isOpen = event.newState === "open";
+        setOpen(isOpen);
+        onOpenChange?.(isOpen);
+    }
+    const triggerProps = {
+        ref: mergeRefs(triggerRef, children.props.ref),
+        id: triggerId,
+        "aria-haspopup": "menu",
+        "aria-expanded": open,
+        "aria-controls": panelId,
+        onPointerDown: event => {
+            children.props.onPointerDown?.(event);
+            dismissingRef.current = isPopoverOpen(panelRef.current);
+        },
+        onClick: event => {
+            children.props.onClick?.(event);
+            if (event.defaultPrevented)
+                return;
+            if (dismissingRef.current) {
+                dismissingRef.current = false;
+                return;
+            }
+            if (isPopoverOpen(panelRef.current))
+                hide(panelRef.current);
+            // A click from the keyboard (Enter or Space) starts on the first item; a pointer click leaves the pointer in charge.
+            else
+                show(event.detail === 0 ? "first" : "panel");
+        },
+        onKeyDown: event => {
+            children.props.onKeyDown?.(event);
+            if (event.defaultPrevented)
+                return;
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+                event.preventDefault();
+                show(event.key === "ArrowDown" ? "first" : "last");
+            }
+        },
+    };
+    return (_jsxs(_Fragment, { children: [cloneElement(children, triggerProps), _jsx(MenuPanel, { ref: panelRef, id: panelId, "aria-label": ariaLabel, "aria-labelledby": ariaLabel ? undefined : triggerId, onToggle: onToggle, ...panelProps })] }));
+}
+/**
+ * A menu that opens where the user right-clicks (or presses Shift+F10) over its content, kept inside the window.
+ * The wrapper takes no space of its own (`display: contents`), so it can wrap a table row or a grid cell.
+ */
+export function ContextMenu({ children, "aria-label": ariaLabel = "Context menu", disabled = false, onOpenChange, ...panelProps }) {
+    const panelId = useId();
+    const panelRef = useRef(null);
+    // When the last press happened: a contextmenu event right after one comes from the mouse or a long touch.
+    const pressedAtRef = useRef(0);
+    function onContextMenu(event) {
+        const panel = panelRef.current;
+        if (disabled || !canShow(panel))
+            return;
+        event.preventDefault();
+        hide(panel);
+        panel.showPopover();
+        const fromPointer = performance.now() - pressedAtRef.current < 1500;
+        if (fromPointer) {
+            placeAtPoint(panel, event.clientX, event.clientY);
+            panel.focus();
+        }
+        else {
+            // From the keyboard (Shift+F10, the Menu key): browsers report the event at the element or at 0,0, so the
+            // menu opens under the focused element like a dropdown (above it when there is no room), on its first item.
+            placeUnderAnchor(panel, event.target.getBoundingClientRect());
+            focusItemAt(panel, 0);
+        }
+    }
+    return (_jsxs("div", { className: "nx-context-target", onPointerDown: () => {
+            pressedAtRef.current = performance.now();
+        }, onContextMenu: onContextMenu, children: [children, _jsx(MenuPanel, { ref: panelRef, id: panelId, "aria-label": ariaLabel, onToggle: onOpenChange && (event => onOpenChange(event.newState === "open")), ...panelProps })] }));
+}

package/dist/Components/Documents/SplitButton.d.ts

@@ -0,0 +1,64 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type PopoverAlign } from "../../Helpers/PopoverHelpers.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+import { type ButtonVariant } from "./Button.tsx";
+export interface SplitButtonOption<T extends string = string> {
+    value: T;
+    label: ReactNode;
+    /** A second line in the menu: what this action does. */
+    description?: ReactNode;
+    /** Icon on the main button and in the menu. */
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+export interface SplitButtonProps<T extends string = string> {
+    /** The actions. The chosen one is the main button; the others wait in the menu. */
+    options: readonly SplitButtonOption<T>[];
+    /** Runs when the main button is clicked. */
+    onAction: (value: T, option: SplitButtonOption<T>) => void;
+    /** The action shown first, unless a remembered choice exists. Default: the first option. */
+    defaultValue?: T;
+    /** The action shown, controlled. */
+    value?: T;
+    /** After the user picks another action in the menu. */
+    onValueChange?: (value: T, option: SplitButtonOption<T>) => void;
+    /**
+     * Remembers the picked action in the browser under this key, so the next visit starts with it,
+     * e.g. `storageKey="pull-request"`. Keys are shared by every split button with the same name.
+     */
+    storageKey?: string;
+    /** Picking an action in the menu also runs it. Default false: it only becomes the main button, as on GitHub. */
+    runOnSelect?: boolean;
+    /** Default `primary`. */
+    variant?: ButtonVariant;
+    /** Default `md`. */
+    size?: Size;
+    /** Shows a spinner on the main button and blocks both buttons while the action runs. */
+    loading?: boolean;
+    disabled?: boolean;
+    /** Fills the width of its container. */
+    block?: boolean;
+    /** `submit` makes the main button submit its form. Default `button`. */
+    type?: "button" | "submit";
+    /** The form the main button submits, when it is not inside it. */
+    form?: string;
+    /** Sends the chosen action's value with the form, through a hidden input. */
+    name?: string;
+    /** Name of the arrow button for screen readers. Default "More actions". */
+    menuLabel?: string;
+    /** Which edge of the button the menu lines up with. Default `end`. */
+    align?: PopoverAlign;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A main action with a menu of alternatives, like "Create pull request" with "Create draft pull request".
+ * Picking an alternative makes it the main button, and with `storageKey` the browser remembers it for next time.
+ *
+ * @example
+ * <SplitButton storageKey="pull-request" onAction={create} options={[
+ *   { value: "create", label: "Create pull request" },
+ *   { value: "draft", label: "Create draft pull request", description: "Cannot be merged until marked ready" },
+ * ]} />
+ */
+export declare function SplitButton<T extends string>({ options, onAction, defaultValue, value, onValueChange, storageKey, runOnSelect, variant, size, loading, disabled, block, type, form, name, menuLabel, align, className, style, }: SplitButtonProps<T>): import("react").JSX.Element | null;