npm - @enigmax/primitives - Versions diffs - 0.22.0 → 0.23.0 - Mend

@enigmax/primitives 0.22.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (67) hide show

package/dist/chunk-3BQVOOAM.js +388 -0
package/dist/{chunk-QQFNAKMY.js → chunk-45UHLZYT.js} +1 -1
package/dist/chunk-4VUHQFAT.js +130 -0
package/dist/{chunk-D5A2ZMAG.js → chunk-4ZPMP47J.js} +6 -1
package/dist/chunk-DSBYVA7V.js +713 -0
package/dist/{chunk-FWVWX67R.js → chunk-FGBIZDV2.js} +3 -3
package/dist/{chunk-R4ZAEE7V.js → chunk-KEVZ5XQV.js} +1 -1
package/dist/chunk-N6PDHMAX.js +213 -0
package/dist/chunk-NONGREXC.js +248 -0
package/dist/chunk-VKL3DEIQ.js +804 -0
package/dist/chunk-WSQC3PCC.js +466 -0
package/dist/context-menu-D3FtTn7v.d.ts +174 -0
package/dist/{index-BHpOZncw.d.ts → index-DQNnohoo.d.ts} +1 -1
package/dist/index.d.ts +5 -1
package/dist/index.js +8 -4
package/dist/keys-D2zJs1uB.d.ts +100 -0
package/dist/next/index.d.ts +9 -2
package/dist/next/index.js +20 -13
package/dist/react/context-menu.d.ts +202 -0
package/dist/react/context-menu.js +6 -0
package/dist/react/index.d.ts +10 -3
package/dist/react/index.js +19 -12
package/dist/react/input.d.ts +2 -2
package/dist/react/input.js +1 -1
package/dist/react/palette.d.ts +1 -1
package/dist/react/palette.js +3 -3
package/dist/react/search.d.ts +1 -1
package/dist/react/search.js +2 -2
package/dist/react/select.d.ts +217 -0
package/dist/react/select.js +7 -0
package/dist/react/selection.d.ts +104 -0
package/dist/react/selection.js +4 -0
package/dist/react-router/index.d.ts +9 -2
package/dist/react-router/index.js +20 -13
package/dist/search/index.d.ts +2 -2
package/dist/search/index.js +1 -1
package/dist/{search-BD9-5O5U.d.ts → search-DYgqRp37.d.ts} +13 -1
package/dist/{search-UQEXAPQB.js → search-PBZORZ7P.js} +1 -1
package/dist/select-ClSy-J1f.d.ts +100 -0
package/dist/selection-B_pmzHpy.d.ts +150 -0
package/package.json +21 -2
package/recipes/context-menu/styles.css +177 -0
package/recipes/input/styles.css +9 -0
package/recipes/palette/styles.css +3 -0
package/recipes/search/tailwind.tsx +3 -2
package/recipes/select/styles.css +230 -0
package/recipes/toast/styles.css +1 -1
package/registry.json +358 -1
package/src/core/context-menu.ts +694 -0
package/src/core/keys.ts +264 -0
package/src/core/search.ts +19 -0
package/src/core/select.ts +404 -0
package/src/core/selection.ts +648 -0
package/src/index.ts +60 -1
package/src/react/context-menu/context.ts +57 -0
package/src/react/context-menu/index.tsx +94 -0
package/src/react/context-menu/root.tsx +846 -0
package/src/react/context-menu/styles.ts +186 -0
package/src/react/index.ts +68 -1
package/src/react/palette/root.tsx +2 -2
package/src/react/select/context.ts +56 -0
package/src/react/select/index.tsx +96 -0
package/src/react/select/root.tsx +839 -0
package/src/react/select/styles.ts +238 -0
package/src/react/selection/index.tsx +115 -0
package/src/react/selection/use-selection.ts +260 -0
/package/dist/{chunk-U3V4EHOB.js → chunk-3HDEZ2E7.js} +0 -0

package/src/react/select/styles.ts ADDED Viewed

@@ -0,0 +1,238 @@
+/**
+ * The select's baseline look.
+ *
+ * A string rather than a stylesheet because `<Select.Root>` injects it - see the note in
+ * root.tsx for why this one component ships a look at all. `scripts/sync-recipes.mjs`
+ * generates `recipes/select/styles.css` from here, and CI fails when the two drift, so this
+ * module is the source and the `.css` is a copy for anyone who prefers the import.
+ *
+ * Everything below is either a custom property or an attribute selector: override the
+ * properties on `:root` for a different-looking select without writing one selector, and
+ * override a selector for the rest. The sheet is PREPENDED to `<head>`, so anything the
+ * document already has wins on source order at equal specificity.
+ */
+export const SELECT_STYLES = `
+:root {
+    --enigma-select-bg: #171717;
+    --enigma-select-border: #404040;
+    --enigma-select-border-focus: #a3a3a3;
+    --enigma-select-text: #f5f5f5;
+    --enigma-select-muted: #a3a3a3;
+    --enigma-select-radius: 0.5rem;
+    --enigma-select-font-size: 0.875rem;
+    --enigma-select-padding: 0.5rem 0.75rem;
+    --enigma-select-panel-bg: #1c1c1c;
+    --enigma-select-panel-border: #333333;
+    --enigma-select-panel-radius: 0.625rem;
+    --enigma-select-panel-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+    --enigma-select-panel-width: 100%;
+    --enigma-select-list-height: 15rem;
+    --enigma-select-active-bg: #2a2a2a;
+    --enigma-select-accent: #fbbf24;
+    --enigma-select-tag-bg: #2a2a2a;
+}
+@media (prefers-color-scheme: light) {
+    :root {
+        --enigma-select-bg: #ffffff;
+        --enigma-select-border: #d4d4d4;
+        --enigma-select-border-focus: #737373;
+        --enigma-select-text: #171717;
+        --enigma-select-muted: #737373;
+        --enigma-select-panel-bg: #ffffff;
+        --enigma-select-panel-border: #e5e5e5;
+        --enigma-select-panel-shadow: 0 12px 32px rgba(0, 0, 0, 0.12);
+        --enigma-select-active-bg: #f5f5f5;
+        --enigma-select-accent: #b45309;
+        --enigma-select-tag-bg: #f0f0f0;
+    }
+}
+[data-enigma-select-root] { position: relative; display: inline-block; min-width: 0; }
+[data-enigma-select-trigger] {
+    display: flex; align-items: center; gap: 0.5rem;
+    width: 100%; min-width: 0; box-sizing: border-box;
+    padding: var(--enigma-select-padding);
+    font: inherit; font-size: var(--enigma-select-font-size); text-align: left;
+    color: var(--enigma-select-text); background: var(--enigma-select-bg);
+    border: 1px solid var(--enigma-select-border); border-radius: var(--enigma-select-radius);
+    cursor: pointer;
+}
+[data-enigma-select-trigger]:focus-visible { outline: 2px solid var(--enigma-select-border-focus); outline-offset: 1px; }
+[data-enigma-select-trigger][data-open] { border-color: var(--enigma-select-border-focus); }
+[data-enigma-select-trigger]:disabled,
+[data-enigma-select-trigger][aria-disabled="true"] { opacity: 0.5; cursor: not-allowed; }
+/* Nothing to choose, or nothing yet: the control reads as unavailable and the caret fades,
+   because a caret at full strength promises a panel that will never open. Not the disabled
+   look, which would say the field is off rather than that the list is empty. */
+[data-enigma-select-trigger][data-empty],
+[data-enigma-select-trigger][data-loading] { opacity: 1; cursor: default; }
+[data-enigma-select-trigger][data-empty] [data-enigma-select-caret],
+[data-enigma-select-trigger][data-loading] [data-enigma-select-caret] { opacity: 0.25; }
+/* The indicator: one slot, holding the caret and the × stacked in the same cell. Side by
+   side they would be two targets a pixel apart - one of which throws away your choice - and
+   the pair would change the trigger's width the moment a value appeared. */
+[data-enigma-select-indicator] {
+    display: grid; place-items: center; flex: none;
+    margin-left: auto; width: 1rem; height: 1rem;
+}
+[data-enigma-select-indicator] > * { grid-area: 1 / 1; }
+/* The caret, drawn rather than loaded: an icon font or an SVG file is a request, and this
+   is two borders. */
+[data-enigma-select-caret] {
+    width: 0.4rem; height: 0.4rem;
+    /* Decoration, and it must not be the hit target: the rotation gives it a stacking
+       context, which paints it OVER the × sharing its cell and swallows the click. */
+    pointer-events: none;
+    border-right: 1.5px solid currentColor; border-bottom: 1.5px solid currentColor;
+    transform: translateY(-0.1rem) rotate(45deg);
+    opacity: 0.6; transition: transform 120ms ease-out, opacity 120ms ease-out;
+}
+[data-enigma-select-trigger][data-open] [data-enigma-select-caret] { transform: translateY(0.1rem) rotate(225deg); }
+[data-enigma-select-value] {
+    display: flex; align-items: center; gap: 0.375rem;
+    /* min-width: 0 is what lets the ellipsis happen: a flex item's default minimum is its
+       content, so without it a long label pushes the caret out of the button. */
+    min-width: 0; overflow: hidden; white-space: nowrap; text-overflow: ellipsis;
+}
+[data-enigma-select-value][data-placeholder] { color: var(--enigma-select-muted); }
+[data-enigma-select-value][data-tags] { flex-wrap: wrap; white-space: normal; }
+[data-enigma-select-tag] {
+    display: inline-flex; align-items: center; gap: 0.25rem;
+    padding: 0.125rem 0.25rem 0.125rem 0.5rem;
+    font-size: 0.8125rem; line-height: 1.4;
+    background: var(--enigma-select-tag-bg); border-radius: 999px;
+}
+[data-enigma-select-tag][data-rest] { padding: 0.125rem 0.5rem; color: var(--enigma-select-muted); }
+[data-enigma-select-tag-remove] {
+    display: grid; place-items: center;
+    width: 1rem; height: 1rem; border-radius: 999px;
+    color: var(--enigma-select-muted); font-size: 0.875rem; line-height: 1; cursor: pointer;
+}
+[data-enigma-select-tag-remove]:hover { color: var(--enigma-select-text); background: var(--enigma-select-active-bg); }
+/* The ×, in the caret's place and only while the control is under the pointer or holds
+   focus. ":focus" and not ":focus-visible": a tap focuses the button, and on a touch screen
+   there is no hover to reveal it with. */
+[data-enigma-select-clear] {
+    display: grid; place-items: center;
+    width: 1rem; height: 1rem; border-radius: 999px;
+    color: var(--enigma-select-muted); font-size: 0.875rem; line-height: 1; cursor: pointer;
+    opacity: 0; pointer-events: none; transition: opacity 120ms ease-out;
+}
+[data-enigma-select-trigger]:hover [data-enigma-select-clear],
+[data-enigma-select-trigger]:focus [data-enigma-select-clear] { opacity: 1; pointer-events: auto; }
+/* Scoped to a trigger that HAS a × - otherwise hovering a select with nothing to clear
+   would hide its caret and leave an empty slot. */
+[data-enigma-select-trigger][data-clearable]:hover [data-enigma-select-caret],
+[data-enigma-select-trigger][data-clearable]:focus [data-enigma-select-caret] { opacity: 0; }
+[data-enigma-select-clear]:hover { color: var(--enigma-select-text); background: var(--enigma-select-active-bg); }
+[data-enigma-select-content] {
+    position: absolute; z-index: 50;
+    top: calc(100% + 0.25rem); left: 0;
+    min-width: var(--enigma-select-panel-width); box-sizing: border-box;
+    padding: 0.25rem;
+    background: var(--enigma-select-panel-bg);
+    border: 1px solid var(--enigma-select-panel-border);
+    border-radius: var(--enigma-select-panel-radius);
+    box-shadow: var(--enigma-select-panel-shadow);
+    animation: enigma-select-in 120ms ease-out;
+    /* A bound, because the content is arbitrary: a long option label or a query typed into
+       the filter would otherwise widen the panel with it. min-width still wins for a
+       trigger wider than this, which is what it is for. */
+    max-width: min(28rem, calc(100vw - 2rem));
+}
+/* Opening upwards is not a variant, it is the same panel measured against the window: near
+   the bottom of the screen the list would otherwise be unreachable. */
+[data-enigma-select-content][data-side="top"] { top: auto; bottom: calc(100% + 0.25rem); }
+[data-enigma-select-content][data-state="closed"] { animation: enigma-select-out 120ms ease-in forwards; pointer-events: none; }
+@keyframes enigma-select-in {
+    from { opacity: 0; transform: translateY(-0.25rem); }
+    to { opacity: 1; transform: none; }
+}
+@keyframes enigma-select-out {
+    from { opacity: 1; }
+    to { opacity: 0; transform: translateY(-0.125rem); }
+}
+@media (prefers-reduced-motion: reduce) {
+    [data-enigma-select-content],
+    [data-enigma-select-content][data-state="closed"] { animation: none; }
+    [data-enigma-select-trigger]::after { transition: none; }
+}
+[data-enigma-select-search] {
+    width: 100%; box-sizing: border-box;
+    padding: 0.375rem 0.5rem 0.5rem;
+    font: inherit; font-size: var(--enigma-select-font-size);
+    color: var(--enigma-select-text); background: transparent;
+    border: 0; border-bottom: 1px solid var(--enigma-select-panel-border);
+    outline: none;
+}
+/* WebKit's own clear cross, gone: it is drawn on no other engine, so leaving it in gives
+   half the visitors a control the other half never sees. */
+[data-enigma-select-search]::-webkit-search-cancel-button,
+[data-enigma-select-search]::-webkit-search-decoration { -webkit-appearance: none; appearance: none; }
+[data-enigma-select-list] {
+    max-height: var(--enigma-select-list-height);
+    margin-top: 0.25rem;
+    overflow-y: auto; overscroll-behavior: contain;
+}
+[data-enigma-select-group-label] {
+    margin: 0.375rem 0 0.125rem; padding: 0 0.5rem;
+    font-size: 0.6875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.08em;
+    color: var(--enigma-select-muted);
+}
+[data-enigma-select-option] {
+    display: flex; align-items: center; gap: 0.5rem;
+    padding: 0.4375rem 0.5rem; border-radius: 0.375rem;
+    font-size: var(--enigma-select-font-size); color: var(--enigma-select-text);
+    cursor: pointer;
+}
+[data-enigma-select-option][data-active] { background: var(--enigma-select-active-bg); }
+[data-enigma-select-option][data-disabled] { opacity: 0.45; cursor: not-allowed; }
+[data-enigma-select-option-text] { display: grid; min-width: 0; }
+[data-enigma-select-option-label] { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+[data-enigma-select-option-description] {
+    font-size: 0.75rem; color: var(--enigma-select-muted);
+    overflow: hidden; white-space: nowrap; text-overflow: ellipsis;
+}
+[data-enigma-select-icon] { display: inline-flex; align-items: center; flex: none; max-height: 1.25em; line-height: 0; }
+/* The check, drawn with two borders and shown only where it belongs. Reserved space either
+   way, so choosing a row does not shift the label under the pointer. */
+[data-enigma-select-check] {
+    flex: none; margin-left: auto;
+    width: 0.35rem; height: 0.6rem;
+    border-right: 2px solid var(--enigma-select-accent); border-bottom: 2px solid var(--enigma-select-accent);
+    transform: rotate(45deg) translate(-0.05rem, -0.05rem);
+    opacity: 0;
+}
+[data-enigma-select-option][data-selected] [data-enigma-select-check] { opacity: 1; }
+/* The end-of-window marker: one pixel, so it has a box to be scrolled into. */
+[data-enigma-select-more] { height: 1px; }
+[data-enigma-select-empty] {
+    margin: 0; padding: 0.75rem 0.5rem;
+    font-size: var(--enigma-select-font-size); color: var(--enigma-select-muted);
+    /* The quoted query is cut in the text as well, but a pasted string with no spaces has
+       no break opportunity at all - so this is what stops it stretching the panel. */
+    overflow-wrap: anywhere;
+}
+`;

package/src/react/selection/index.tsx ADDED Viewed

@@ -0,0 +1,115 @@
+"use client";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { useSelection, type SelectionRenderer, type UseSelectionOptions } from "@/react/selection/use-selection";
+/**
+ * `onChange` is dropped from BOTH sides on purpose: the model's means "the state moved" and a
+ * div's means an input inside it changed, and one name cannot be both. The selection is
+ * reported through `onSelectionChange`, and the whole state through `useSelection`.
+ */
+export interface SelectionListProps<Item> extends Omit<UseSelectionOptions<Item>, "onChange">, Omit<ComponentPropsWithoutRef<"div">, "children" | "onSelect" | "onChange"> {
+    /** Draw one row. What it returns goes inside the row element, which this component owns. */
+    children: SelectionRenderer<Item>;
+    /** Shown instead of the rows when there are none. */
+    empty?: ReactNode;
+    /** Drag a rubber band over the empty space to select what it covers. Default: on. */
+    marquee?: boolean;
+}
+/**
+ * A list whose rows can be selected the way a file manager's are.
+ *
+ * ```tsx
+ * <SelectionList
+ *     items={files}
+ *     getId={(file) => file.path}
+ *     onCommand={(event) => {
+ *         if (event.command === "delete") remove(event.items);
+ *         if (event.command === "rename") rename(event.cursor);
+ *     }}
+ * >
+ *     {({ item }) => <><FileIcon kind={item.kind} />{item.name}</>}
+ * </SelectionList>
+ * ```
+ *
+ * It renders a container and one element per row, with the roles, the ids and the state
+ * attributes on them - and nothing else. No borders, no padding, no highlight: `[data-selected]`
+ * and `[data-cursor]` are there for the stylesheet, so the list looks like the rest of the
+ * product rather than like this package.
+ *
+ * The shape is the only thing it decides. A table, a grid of cards, a tree or a virtualized
+ * window - and anything that needs to reach the model itself, to clear the selection from a
+ * toolbar or read it into a header checkbox - uses `useSelection` directly and puts the same
+ * props on its own markup. That is the same component with the markup handed back.
+ */
+export function SelectionList<Item>(props: SelectionListProps<Item>): ReactNode {
+    const {
+        items,
+        getId,
+        disabled,
+        multiple,
+        columns,
+        page,
+        shortcuts,
+        onCommand,
+        onSelectionChange,
+        scrollIntoView,
+        children,
+        empty,
+        marquee = true,
+        ...rest
+    } = props;
+    const selection = useSelection<Item>({
+        items, getId, disabled, multiple, columns, page, shortcuts, onCommand, onSelectionChange, scrollIntoView
+    });
+    const listProps = selection.getListProps<HTMLDivElement>(rest);
+    const containerProps = marquee ? selection.getMarqueeProps<HTMLDivElement>(listProps) : listProps;
+    return (
+        // `position: relative` is the one style this component sets, and it is not a look: the
+        // rubber band is absolutely positioned inside, and without a positioned ancestor it
+        // would be drawn against the page instead of against the list.
+        <div {...containerProps} style={{ position: "relative", ...rest.style }}>
+            {items.length === 0 && empty !== undefined
+                ? <div data-enigma-selection-empty="">{empty}</div>
+                : items.map((item, index) => (
+                    <div key={getId ? getId(item, index) : index} {...selection.getItemProps<HTMLDivElement>(index)}>
+                        {children({
+                            item,
+                            index,
+                            selected: selection.state.selectedSet.has(getId ? getId(item, index) : String(index)),
+                            cursor: selection.state.cursor === index,
+                            disabled: Boolean(disabled?.(item, index))
+                        })}
+                    </div>
+                ))}
+            {selection.marquee && (
+                // The band is drawn, not just computed: without something on screen a drag over
+                // empty space looks like the list selecting rows at random.
+                <div
+                    aria-hidden="true"
+                    data-enigma-selection-marquee=""
+                    style={{ position: "absolute", pointerEvents: "none", ...selection.marquee }}
+                />
+            )}
+        </div>
+    );
+}
+export { useSelection, type UseSelectionOptions, type UseSelectionResult, type SelectionRenderer, type SelectionRowRender, type MarqueeRect } from "@/react/selection/use-selection";
+export {
+    createSelection,
+    DEFAULT_SELECTION_SHORTCUTS,
+    type SelectionCommand,
+    type SelectionCommandName,
+    type SelectionCommandEvent,
+    type SelectionShortcuts,
+    type SelectionOptions,
+    type SelectionInstance,
+    type SelectionState,
+    type SelectionClickModifiers
+} from "@/core/selection";
+export { shortcutTokens, shortcutText, parseShortcut, matchesShortcut, type Shortcut, type ShortcutSpec } from "@/core/keys";

package/src/react/selection/use-selection.ts ADDED Viewed

@@ -0,0 +1,260 @@
+"use client";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import type { KeyboardEvent, PointerEvent, HTMLAttributes, ReactNode } from "react";
+import {
+    createSelection,
+    type SelectionInstance,
+    type SelectionOptions,
+    type SelectionState
+} from "@/core/selection";
+/**
+ * The selection model as a hook, plus the props that put it on real elements.
+ *
+ * Prop getters rather than components, because a selectable list is every shape at once - a
+ * table, a grid of cards, a tree, a virtualized window - and a component that owned the markup
+ * would fit exactly one of them. `<SelectionList>` next door IS this hook with a container and
+ * rows around it, for the case where the shape is a plain list.
+ */
+export interface UseSelectionOptions<Item> extends Omit<SelectionOptions<Item>, "items"> {
+    items: readonly Item[];
+    /** Bring the cursor into view when the keyboard moves it. Default: on. */
+    scrollIntoView?: boolean;
+}
+export interface UseSelectionResult<Item> {
+    instance: SelectionInstance<Item>;
+    state: SelectionState<Item>;
+    /** Whether a row is selected, by id. */
+    isSelected: (id: string) => boolean;
+    /** The container: the keyboard, the roles and the id the rows point at. */
+    getListProps: <T extends HTMLElement = HTMLElement>(props?: HTMLAttributes<T>) => HTMLAttributes<T> & { ref: (node: T | null) => void; };
+    /** One row: its state, its id, and the click rule. */
+    getItemProps: <T extends HTMLElement = HTMLElement>(index: number, props?: HTMLAttributes<T>) => HTMLAttributes<T> & { id: string; };
+    /**
+     * A press on the empty space of the container, for a rubber band. Composed OVER the list
+     * props rather than beside them, so the two handlers do not overwrite each other:
+     * `<div {...getMarqueeProps(getListProps())}>`.
+     */
+    getMarqueeProps: <T extends HTMLElement = HTMLElement>(props?: HTMLAttributes<T>) => HTMLAttributes<T>;
+    /** The rubber band's rectangle while it is being dragged, in container coordinates. */
+    marquee: MarqueeRect | null;
+    ids: { list: string; };
+    itemId: (index: number) => string;
+}
+/** A rubber band, in coordinates relative to the scrolling container's content. */
+export interface MarqueeRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** How far the pointer must travel before a press becomes a rubber band rather than a click. */
+const MARQUEE_SLOP = 4;
+export function useSelection<Item>(options: UseSelectionOptions<Item>): UseSelectionResult<Item> {
+    const { items, scrollIntoView = true, ...rest } = options;
+    const id = useId();
+    const listRef = useRef<HTMLElement | null>(null);
+    const latest = useRef(options);
+    latest.current = options;
+    const instance = useMemo(() => createSelection<Item>({
+        items,
+        getId: (item, index) => (latest.current.getId ?? ((_: Item, position: number) => String(position)))(item, index),
+        disabled: (item, index) => Boolean(latest.current.disabled?.(item, index)),
+        onCommand: (event) => latest.current.onCommand?.(event),
+        onSelectionChange: (ids, chosen) => latest.current.onSelectionChange?.(ids, chosen)
+        // Built once: rebuilding it would drop the selection and the cursor on every render.
+        // Everything below is pushed in through update().
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }), []);
+    const [state, setState] = useState<SelectionState<Item>>(() => instance.state);
+    useEffect(() => {
+        const unsubscribe = instance.subscribe(setState);
+        setState(instance.state);
+        return () => {
+            unsubscribe();
+            instance.destroy();
+        };
+    }, [instance]);
+    const { multiple, columns, page, shortcuts } = rest;
+    // The bindings as a string, because `shortcuts={{ rename: "F3" }}` is a new object on every
+    // render: depending on its identity would push it in each time and emit a state for a
+    // binding table nobody changed.
+    const shortcutSignature = JSON.stringify(shortcuts ?? null);
+    useEffect(() => {
+        instance.update({ items, multiple, columns, page, shortcuts: latest.current.shortcuts });
+    }, [instance, items, multiple, columns, page, shortcutSignature]);
+    // The cursor can move by key onto a row that is scrolled out of sight, and a cursor nobody
+    // can see is the same as none - every arrow press then looks like it did nothing.
+    const cursor = state.cursor;
+    useEffect(() => {
+        if (!scrollIntoView || cursor < 0) return;
+        const row = listRef.current?.querySelector<HTMLElement>(`[data-enigma-selection-index="${cursor}"]`);
+        row?.scrollIntoView({ block: "nearest", inline: "nearest" });
+    }, [cursor, scrollIntoView]);
+    const isSelected = useCallback((rowId: string) => state.selectedSet.has(rowId), [state.selectedSet]);
+    const itemId = useCallback((index: number) => `${id}-item-${index}`, [id]);
+    const getListProps = useCallback(<T extends HTMLElement>(props: HTMLAttributes<T> = {}) => ({
+        ...props,
+        ref: (node: T | null) => { listRef.current = node; },
+        id: `${id}-list`,
+        role: props.role ?? "listbox",
+        "aria-multiselectable": (latest.current.multiple ?? true) || undefined,
+        // A single tab stop, with the arrows moving a cursor INSIDE it: a list of two hundred
+        // rows that are each tabbable is a list nobody can tab past.
+        tabIndex: props.tabIndex ?? 0,
+        "aria-activedescendant": state.cursor >= 0 ? itemId(state.cursor) : undefined,
+        "data-enigma-selection-list": "",
+        "data-selected-count": String(state.count),
+        onKeyDown: (event: KeyboardEvent<T>) => {
+            props.onKeyDown?.(event);
+            if (event.defaultPrevented) return;
+            // The browser's own meaning is taken only when a binding matched: Ctrl+A selects
+            // the whole page, F2 does nothing, and Backspace still navigates back where the
+            // list has not claimed them.
+            if (instance.keyDown(event)) event.preventDefault();
+        }
+    }), [id, instance, itemId, state.cursor, state.count]);
+    const getItemProps = useCallback(<T extends HTMLElement>(index: number, props: HTMLAttributes<T> = {}) => {
+        const item = latest.current.items[index];
+        const rowId = item === undefined ? null : (latest.current.getId ?? ((_: Item, position: number) => String(position)))(item, index);
+        const disabled = item !== undefined && Boolean(latest.current.disabled?.(item, index));
+        const chosen = rowId !== null && state.selectedSet.has(rowId);
+        return {
+            ...props,
+            id: itemId(index),
+            role: props.role ?? "option",
+            "aria-selected": chosen,
+            "aria-disabled": disabled || undefined,
+            "data-enigma-selection-item": "",
+            "data-enigma-selection-index": String(index),
+            "data-selected": chosen ? "" : undefined,
+            "data-cursor": state.cursor === index ? "" : undefined,
+            "data-disabled": disabled ? "" : undefined,
+            onPointerDown: (event: PointerEvent<T>) => {
+                props.onPointerDown?.(event);
+                if (event.defaultPrevented || disabled || event.button !== 0) return;
+                // Down rather than click, so a drag that starts on a row begins from a
+                // selection that already includes it - which is what makes dragging a group
+                // work instead of collapsing it to the row under the pointer.
+                instance.click(index, event);
+            },
+            onContextMenu: (event: React.MouseEvent<T>) => {
+                props.onContextMenu?.(event);
+                if (event.defaultPrevented || disabled) return;
+                // A right-click on a row OUTSIDE the selection selects it first, and one
+                // inside leaves the group alone. Same rule as `targets`, applied to the
+                // selection itself - so what the menu acts on is what is highlighted.
+                if (rowId !== null && !state.selectedSet.has(rowId)) instance.click(index);
+            }
+        } as HTMLAttributes<T> & { id: string; };
+    }, [instance, itemId, state.selectedSet, state.cursor]);
+    const [marquee, setMarquee] = useState<MarqueeRect | null>(null);
+    const drag = useRef<{ x: number; y: number; pointer: number; } | null>(null);
+    const getMarqueeProps = useCallback(<T extends HTMLElement>(props: HTMLAttributes<T> = {}) => ({
+        ...props,
+        onPointerDown: (event: PointerEvent<T>) => {
+            props.onPointerDown?.(event);
+            if (event.defaultPrevented || event.button !== 0) return;
+            // Only from EMPTY space: a press that lands on a row is that row's click, and a
+            // band started there would fight the drag-and-drop the row probably has.
+            if ((event.target as HTMLElement).closest("[data-enigma-selection-item]")) return;
+            drag.current = { x: event.clientX, y: event.clientY, pointer: event.pointerId };
+        }
+    }), []);
+    // The band lives on the window rather than on the container: the pointer leaves the list
+    // constantly while dragging one, and a listener on the element would stop tracking there.
+    useEffect(() => {
+        const list = listRef.current;
+        if (!list) return;
+        const move = (event: globalThis.PointerEvent) => {
+            const start = drag.current;
+            if (!start || event.pointerId !== start.pointer) return;
+            if (!marquee && Math.abs(event.clientX - start.x) < MARQUEE_SLOP && Math.abs(event.clientY - start.y) < MARQUEE_SLOP) return;
+            if (!marquee) instance.beginMarquee(event.ctrlKey || event.metaKey);
+            const bounds = list.getBoundingClientRect();
+            const left = Math.min(start.x, event.clientX);
+            const top = Math.min(start.y, event.clientY);
+            const rect = {
+                left: left - bounds.left + list.scrollLeft,
+                top: top - bounds.top + list.scrollTop,
+                width: Math.abs(event.clientX - start.x),
+                height: Math.abs(event.clientY - start.y)
+            };
+            setMarquee(rect);
+            // Measured from the rows themselves rather than from an assumed row height, so
+            // this works for a grid, a table and a list of different-sized cards alike.
+            const covered: number[] = [];
+            for (const row of list.querySelectorAll<HTMLElement>("[data-enigma-selection-item]")) {
+                const box = row.getBoundingClientRect();
+                const hits = box.right >= Math.min(start.x, event.clientX)
+                    && box.left <= Math.max(start.x, event.clientX)
+                    && box.bottom >= Math.min(start.y, event.clientY)
+                    && box.top <= Math.max(start.y, event.clientY);
+                if (hits) covered.push(Number(row.dataset.enigmaSelectionIndex));
+            }
+            instance.marqueeTo(covered);
+        };
+        const up = () => {
+            if (!drag.current) return;
+            drag.current = null;
+            setMarquee(null);
+            instance.endMarquee();
+        };
+        window.addEventListener("pointermove", move);
+        window.addEventListener("pointerup", up);
+        window.addEventListener("pointercancel", up);
+        return () => {
+            window.removeEventListener("pointermove", move);
+            window.removeEventListener("pointerup", up);
+            window.removeEventListener("pointercancel", up);
+        };
+    }, [instance, marquee]);
+    return {
+        instance,
+        state,
+        isSelected,
+        getListProps,
+        getItemProps,
+        getMarqueeProps,
+        marquee,
+        ids: { list: `${id}-list` },
+        itemId
+    };
+}
+/** What a row renderer is handed. Everything it needs to draw one row and nothing else. */
+export interface SelectionRowRender<Item> {
+    item: Item;
+    index: number;
+    selected: boolean;
+    cursor: boolean;
+    disabled: boolean;
+}
+export type SelectionRenderer<Item> = (row: SelectionRowRender<Item>) => ReactNode;

/package/dist/{chunk-U3V4EHOB.js → chunk-3HDEZ2E7.js} RENAMED Viewed

File without changes