basalt-ui 1.30.2 → 1.31.0

package/dist/agent-chat/thread-workspace.js

@@ -1,9 +1,9 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { Box, Divider, Flex, Skeleton, Stack, Text, useMantineTheme } from "@mantine/core";
-import { useMediaQuery } from "@mantine/hooks";
+import { Box, Divider, Flex, Skeleton, Stack, Text } from "@mantine/core";
 import { useAgentThreadRuns } from "../agent/index.js";
 import { cx } from "../common/props.js";
 import { assertRequiredProps } from "../common/validate.js";
+import { useSizeClass } from "../shell/use-size-class.js";
 import { VX } from "../tokens/index.js";
 import { Composer } from "./composer.js";
 import { ThreadDetailPanel } from "./thread-detail-panel.js";
@@ -54,8 +54,7 @@ function ThreadWorkspace({
   assertRequiredProps("ThreadWorkspace", { useThreads }, ["useThreads"]);
   const store = useThreads();
   const runs = useAgentThreadRuns({ transport, store, resolveOutcome });
-  const theme = useMantineTheme();
-  const narrow = useMediaQuery(`(max-width: calc(${theme.breakpoints.sm} - 0.00625em))`);
+  const narrow = useSizeClass() === "compact";
   const threads = store.threads;
   const activeThread = threads.find((thread) => thread.id === store.activeId) ?? null;
   const activeRun = store.activeId !== null ? runs.runs.get(store.activeId) : void 0;

package/dist/agent-chat/use-keyboard-inset.d.ts

@@ -0,0 +1,2 @@
+export declare function useKeyboardInsetRef(): (el: HTMLElement | null) => void;
+//# sourceMappingURL=use-keyboard-inset.d.ts.map

package/dist/agent-chat/use-keyboard-inset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-keyboard-inset.d.ts","sourceRoot":"","sources":["../../src/agent-chat/use-keyboard-inset.ts"],"names":[],"mappings":"AAiCA,wBAAgB,mBAAmB,IAAI,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAkCtE"}

package/dist/agent-chat/use-keyboard-inset.js

@@ -0,0 +1,34 @@
+import { useCallback, useState } from "react";
+import { useIsomorphicLayoutEffect } from "../common/isomorphic-layout-effect.js";
+const KEYBOARD_INSET_VAR = "--vx-keyboard-inset";
+function useKeyboardInsetRef() {
+  const [node, setNode] = useState(null);
+  const attach = useCallback((el) => {
+    setNode(el);
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    if (node === null) return;
+    if (typeof window === "undefined") return;
+    const viewport = window.visualViewport;
+    if (viewport === null || viewport === void 0) return;
+    const publish = () => {
+      const inset = Math.max(
+        0,
+        document.documentElement.clientHeight - viewport.height - viewport.offsetTop
+      );
+      node.style.setProperty(KEYBOARD_INSET_VAR, `${inset}px`);
+    };
+    publish();
+    viewport.addEventListener("resize", publish);
+    viewport.addEventListener("scroll", publish);
+    return () => {
+      viewport.removeEventListener("resize", publish);
+      viewport.removeEventListener("scroll", publish);
+      node.style.removeProperty(KEYBOARD_INSET_VAR);
+    };
+  }, [node]);
+  return attach;
+}
+export {
+  useKeyboardInsetRef
+};

package/dist/charts/cursor/touch-pin.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Outside-tap / Escape / scroll (optionally resize) dismissal for a pinned/open floating element.
+ * Capture-phase `pointerdown` so a descendant that stops propagation on its own handler can't leave
+ * the dismissal stuck.
+ */
+export declare function useDismissOnOutside({ enabled, isInside, onDismiss, dismissOnResize, scrollExemptInside, }: {
+    enabled: boolean;
+    /** A tap (or, with `scrollExemptInside`, a scroll) landing where this returns true doesn't
+     * dismiss. Omit to treat every tap as outside. */
+    isInside?: (target: Node) => boolean;
+    onDismiss: () => void;
+    /** Also dismiss on a window `resize` — `ChartLegend`'s disclosure needs this, the touch-pinned
+     * cursors don't (their host doesn't reflow independently of the chart it's pinned to). */
+    dismissOnResize?: boolean;
+    /** Exempts a scroll whose target is `isInside` — `ChartLegend`'s own scrollable panel needs this
+     * (`overflowY: auto`), the cursor hooks don't (a chart has no internal scroller to protect). */
+    scrollExemptInside?: boolean;
+}): void;
+export type TouchPin = {
+    /** `onPointerDown` for a coarse press: snapshots whatever is currently committed (via
+     * `getCommitted`) so a later `cancel` can restore exactly that, then tracks `pointerId`. */
+    begin: (pointerId: number) => void;
+    /** `onPointerUp` for the tracked pointer: the press is now committed — nothing left to revert. */
+    commit: (pointerId: number) => boolean;
+    /** `onPointerCancel`/`onPointerLeave` for the tracked pointer: the browser took the gesture (a
+     * scroll) before the press committed — restores the pre-press value via `setCommitted`, or
+     * leaves it clear when nothing was committed before. Returns whether this pointer was tracked. */
+    cancel: (pointerId: number) => boolean;
+    /** Hard reset — no restore, just drop any in-flight press bookkeeping (an explicit `clear()`, e.g.
+     * Escape or an outside tap, is about to overwrite the value directly anyway). */
+    reset: () => void;
+};
+/**
+ * Provisional-press state machine shared by `useChartCursor`/`useDiscreteCursor`: a coarse press
+ * shows a value immediately (PROVISIONAL, not yet committed) — `commit` on `pointerup` leaves it in
+ * place, `cancel` on `pointercancel`/`pointerleave` (a scroll winning the gesture) restores whatever
+ * was committed before this press started, rather than dropping it. This is what keeps a previously
+ * COMMITTED pin alive through a second tap that gets cancelled instead of completed.
+ */
+export declare function useTouchPin<V>({ getCommitted, setCommitted, }: {
+    /** Reads the value currently committed — snapshotted on `begin`, restored on `cancel`. */
+    getCommitted: () => V;
+    setCommitted: (value: V) => void;
+}): TouchPin;
+//# sourceMappingURL=touch-pin.d.ts.map

package/dist/charts/cursor/touch-pin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"touch-pin.d.ts","sourceRoot":"","sources":["../../../src/charts/cursor/touch-pin.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,QAAQ,EACR,SAAS,EACT,eAAuB,EACvB,kBAA0B,GAC3B,EAAE;IACD,OAAO,EAAE,OAAO,CAAA;IAChB;sDACkD;IAClD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,KAAK,OAAO,CAAA;IACpC,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB;8FAC0F;IAC1F,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;oGACgG;IAChG,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,GAAG,IAAI,CA2BP;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB;gGAC4F;IAC5F,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,kGAAkG;IAClG,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;IACtC;;sGAEkG;IAClG,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;IACtC;qFACiF;IACjF,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,EAC7B,YAAY,EACZ,YAAY,GACb,EAAE;IACD,0FAA0F;IAC1F,YAAY,EAAE,MAAM,CAAC,CAAA;IACrB,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;CACjC,GAAG,QAAQ,CAiDX"}

package/dist/charts/cursor/touch-pin.js

@@ -0,0 +1,79 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+function useDismissOnOutside({
+  enabled,
+  isInside,
+  onDismiss,
+  dismissOnResize = false,
+  scrollExemptInside = false
+}) {
+  useEffect(() => {
+    if (!enabled) return;
+    const onPointerDown = (event) => {
+      if (event.target instanceof Node && isInside?.(event.target) === true) return;
+      onDismiss();
+    };
+    const onKeyDown = (event) => {
+      if (event.key === "Escape") onDismiss();
+    };
+    const onScroll = (event) => {
+      if (scrollExemptInside && event.target instanceof Node && isInside?.(event.target) === true) {
+        return;
+      }
+      onDismiss();
+    };
+    document.addEventListener("pointerdown", onPointerDown, true);
+    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("scroll", onScroll, true);
+    if (dismissOnResize) window.addEventListener("resize", onDismiss);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown, true);
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("scroll", onScroll, true);
+      if (dismissOnResize) window.removeEventListener("resize", onDismiss);
+    };
+  }, [enabled, isInside, onDismiss, dismissOnResize, scrollExemptInside]);
+}
+function useTouchPin({
+  getCommitted,
+  setCommitted
+}) {
+  const pressRef = useRef(null);
+  const backupRef = useRef(void 0);
+  const hasBackupRef = useRef(false);
+  const getCommittedRef = useRef(getCommitted);
+  getCommittedRef.current = getCommitted;
+  const setCommittedRef = useRef(setCommitted);
+  setCommittedRef.current = setCommitted;
+  const begin = useCallback((pointerId) => {
+    backupRef.current = getCommittedRef.current();
+    hasBackupRef.current = true;
+    pressRef.current = pointerId;
+  }, []);
+  const commit = useCallback((pointerId) => {
+    if (pressRef.current !== pointerId) return false;
+    pressRef.current = null;
+    backupRef.current = void 0;
+    hasBackupRef.current = false;
+    return true;
+  }, []);
+  const cancel = useCallback((pointerId) => {
+    if (pressRef.current !== pointerId) return false;
+    pressRef.current = null;
+    const backup = backupRef.current;
+    const hasBackup = hasBackupRef.current;
+    backupRef.current = void 0;
+    hasBackupRef.current = false;
+    if (hasBackup) setCommittedRef.current(backup);
+    return true;
+  }, []);
+  const reset = useCallback(() => {
+    pressRef.current = null;
+    backupRef.current = void 0;
+    hasBackupRef.current = false;
+  }, []);
+  return useMemo(() => ({ begin, commit, cancel, reset }), [begin, commit, cancel, reset]);
+}
+export {
+  useDismissOnOutside,
+  useTouchPin
+};

package/dist/charts/hooks/use-discrete-cursor.d.ts

@@ -0,0 +1,66 @@
+import type { KeyboardEventHandler, PointerEventHandler } from 'react';
+/** A discrete target plus the viewport-space point its tooltip anchors to. */
+export type DiscreteCursorTip<T> = {
+    target: T;
+    anchor: {
+        x: number;
+        y: number;
+    };
+};
+export type UseDiscreteCursorResult<T> = {
+    /** The target whose tooltip should render, resolved from whichever mode last set it (hover, a
+     * touch pin, or keyboard focus). `null` when nothing is active. */
+    tip: DiscreteCursorTip<T> | null;
+    /** True once a coarse-pointer tap has PINNED `tip` open (survives pointer lift). */
+    isPinned: boolean;
+    /** Pointer handlers for one target's shape — spread onto its `<g>`/`<rect>`. Fine pointers
+     * (mouse/pen) hover; a coarse pointer (touch) pins on `pointerdown` instead. */
+    pointerProps: (t: T) => {
+        onPointerEnter: PointerEventHandler<Element>;
+        onPointerMove: PointerEventHandler<Element>;
+        onPointerDown: PointerEventHandler<Element>;
+        onPointerUp: PointerEventHandler<Element>;
+        onPointerLeave: PointerEventHandler<Element>;
+        onPointerCancel: PointerEventHandler<Element>;
+    };
+    /** DOM id for a target's `role="option"` element — also `aria-activedescendant`'s value while
+     * that target is active. Spread `id={optionId(t)}` on the same node that gets `pointerProps`. */
+    optionId: (t: T) => string;
+    /** Dismisses a pin and clears keyboard focus. Already wired to Escape and an outside tap while
+     * pinned; call it directly for anything else that should close the tooltip (e.g. data changing
+     * out from under the focused key). */
+    clear: () => void;
+    /** Spread on the ONE shared, focusable host (the chart's `<svg>`). */
+    hostProps: {
+        ref: (node: Element | null) => void;
+        tabIndex: 0;
+        role: 'listbox';
+        'aria-label': string;
+        'aria-activedescendant': string | undefined;
+        onKeyDown: KeyboardEventHandler<Element>;
+        onBlur: () => void;
+    };
+};
+/**
+ * Keyboard + focus + tap parity for a DISCRETE set of targets (donut slices, heatmap cells) — the
+ * counterpart `HoverOverlay` gives a continuous cartesian domain (`docs/CHARTS-SPEC.md` §4).
+ *
+ * **Role choice**: `listbox`/`option` (WAI-ARIA APG "Listbox"), not `slider`. A cartesian domain is
+ * one continuous value; a donut slice or heatmap cell is a named choice among discrete siblings.
+ * `aria-activedescendant` announces the focused option's id while DOM focus stays on the one host.
+ *
+ * Three input modes converge on one `tip`: hover (fine pointer, ephemeral), a provisional tap that
+ * `pointerup` commits into a pin (a `pointercancel` first — a scroll — clears it), and keyboard
+ * stepping on the one focusable host (`columns` maps Up/Down to a full-row jump for a 2D grid;
+ * Left/Right always step by one). Keyboard focus anchors the tooltip to the host's center — an
+ * accepted simplification; the value still reaches a screen reader via the option's text.
+ */
+export declare function useDiscreteCursor<T>({ targets, getKey, columns, ariaLabel, }: {
+    targets: readonly T[];
+    getKey: (t: T) => string;
+    /** Row width for a 2D grid — see the Up/Down mapping above. Omit for a 1D ring. */
+    columns?: number;
+    /** Accessible name for the shared listbox host. */
+    ariaLabel?: string;
+}): UseDiscreteCursorResult<T>;
+//# sourceMappingURL=use-discrete-cursor.d.ts.map

package/dist/charts/hooks/use-discrete-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-discrete-cursor.d.ts","sourceRoot":"","sources":["../../../src/charts/hooks/use-discrete-cursor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EAEpB,mBAAmB,EACpB,MAAM,OAAO,CAAA;AAGd,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAIlF,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI;IACvC;uEACmE;IACnE,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAChC,oFAAoF;IACpF,QAAQ,EAAE,OAAO,CAAA;IACjB;oFACgF;IAChF,YAAY,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK;QACtB,cAAc,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAA;QAC5C,aAAa,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAA;QAC3C,aAAa,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAA;QAC3C,WAAW,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAA;QACzC,cAAc,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAA;QAC5C,eAAe,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAA;KAC9C,CAAA;IACD;qGACiG;IACjG,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAA;IAC1B;;0CAEsC;IACtC,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,sEAAsE;IACtE,SAAS,EAAE;QACT,GAAG,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAA;QACnC,QAAQ,EAAE,CAAC,CAAA;QACX,IAAI,EAAE,SAAS,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;QACpB,uBAAuB,EAAE,MAAM,GAAG,SAAS,CAAA;QAC3C,SAAS,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAA;QACxC,MAAM,EAAE,MAAM,IAAI,CAAA;KACnB,CAAA;CACF,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,EACnC,OAAO,EACP,MAAM,EACN,OAAO,EACP,SAAwE,GACzE,EAAE;IACD,OAAO,EAAE,SAAS,CAAC,EAAE,CAAA;IACrB,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAA;IACxB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAoQ7B"}

package/dist/charts/hooks/use-discrete-cursor.js

@@ -0,0 +1,198 @@
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { useDismissOnOutside, useTouchPin } from "../cursor/touch-pin.js";
+function useDiscreteCursor({
+  targets,
+  getKey,
+  columns,
+  ariaLabel = "Chart data \u2014 use arrow keys to navigate, Escape to dismiss"
+}) {
+  const [active, setActive] = useState(null);
+  const [pinned, setPinned] = useState(false);
+  const hostElRef = useRef(null);
+  const idPrefix = useId();
+  const activeRef = useRef(active);
+  activeRef.current = active;
+  const pinnedRef = useRef(pinned);
+  pinnedRef.current = pinned;
+  const targetsRef = useRef(targets);
+  targetsRef.current = targets;
+  const getKeyRef = useRef(getKey);
+  getKeyRef.current = getKey;
+  const columnsRef = useRef(columns);
+  columnsRef.current = columns;
+  const moveFrameRef = useRef(null);
+  const pendingActiveRef = useRef(null);
+  useEffect(
+    () => () => {
+      if (moveFrameRef.current !== null) cancelAnimationFrame(moveFrameRef.current);
+    },
+    []
+  );
+  const scheduleActive = useCallback((next) => {
+    pendingActiveRef.current = next;
+    if (moveFrameRef.current !== null) return;
+    moveFrameRef.current = requestAnimationFrame(() => {
+      moveFrameRef.current = null;
+      setActive(pendingActiveRef.current);
+    });
+  }, []);
+  const cancelPendingFrame = useCallback(() => {
+    if (moveFrameRef.current !== null) {
+      cancelAnimationFrame(moveFrameRef.current);
+      moveFrameRef.current = null;
+    }
+    pendingActiveRef.current = null;
+  }, []);
+  const touchPin = useTouchPin({
+    getCommitted: () => pinnedRef.current ? activeRef.current : null,
+    setCommitted: (value) => {
+      setActive(value);
+      setPinned(value !== null);
+    }
+  });
+  const clear = useCallback(() => {
+    cancelPendingFrame();
+    touchPin.reset();
+    setActive(null);
+    setPinned(false);
+  }, [touchPin, cancelPendingFrame]);
+  const isInsideHost = useCallback(
+    (target) => hostElRef.current?.contains(target) === true,
+    []
+  );
+  useDismissOnOutside({ enabled: pinned, isInside: isInsideHost, onDismiss: clear });
+  const indexByKey = useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    targets.forEach((t, i) => map.set(getKeyRef.current(t), i));
+    return map;
+  }, [targets]);
+  const optionId = useCallback(
+    (t) => `${idPrefix}-${indexByKey.get(getKeyRef.current(t)) ?? -1}`,
+    [idPrefix, indexByKey]
+  );
+  const findTarget = (key) => {
+    const index = indexByKey.get(key);
+    return index === void 0 ? void 0 : targetsRef.current[index];
+  };
+  const pointerProps = (t) => {
+    const key = getKeyRef.current(t);
+    const showAt = (event) => {
+      scheduleActive({ key, anchor: { x: event.clientX, y: event.clientY } });
+    };
+    const cancelIfUncommitted = (event) => touchPin.cancel(event.pointerId);
+    return {
+      onPointerEnter: (event) => {
+        if (event.pointerType !== "mouse" || pinned) return;
+        showAt(event);
+      },
+      onPointerMove: (event) => {
+        if (event.pointerType !== "mouse" || pinned) return;
+        showAt(event);
+      },
+      // Only a coarse pointer presses — a fine pointer's `down` is a no-op, it already shows via
+      // enter/move above. The press is PROVISIONAL: it snapshots whatever is committed now (so a
+      // cancel can restore it) BEFORE showing the readout, which only `onPointerUp` commits. On
+      // touch the readout anchors to the HOST's top edge rather than the finger, which would cover
+      // it; a missing host falls back to the pointer.
+      onPointerDown: (event) => {
+        if (event.pointerType === "mouse") return;
+        touchPin.begin(event.pointerId);
+        cancelPendingFrame();
+        const rect = hostElRef.current?.getBoundingClientRect();
+        setActive({
+          key,
+          anchor: rect === void 0 ? { x: event.clientX, y: event.clientY } : { x: rect.left + rect.width / 2, y: rect.top }
+        });
+      },
+      // A completed tap commits the pin. Only the tracked pointer commits — and only a coarse one:
+      // some browsers assign a touch's `pointerId` the same value (1) mouse pointers use, so a
+      // `pointerType` check keeps an unrelated mouse `pointerup` reusing that id from committing an
+      // abandoned touch press.
+      onPointerUp: (event) => {
+        if (event.pointerType === "mouse") return;
+        if (!touchPin.commit(event.pointerId)) return;
+        setPinned(true);
+      },
+      // A still-uncommitted press ending here is the browser taking the gesture (a scroll); clear it
+      // regardless of `pinned`. Otherwise keep the fine-pointer/pinned guard. Routes through the
+      // same `clear()` the outside-tap/Escape dismissal uses (mirrors `useChartCursor`'s own
+      // `onPointerLeave`) rather than a bare `setActive(null)` — a `pointermove` scheduled just
+      // before this event fires is still in flight (coalesced onto `moveFrameRef`/
+      // `pendingActiveRef`), and only `clear()` cancels it. A bare `setActive(null)` left that frame
+      // free to land a tick later and resurrect the tooltip this leave/cancel was meant to dismiss.
+      onPointerLeave: (event) => {
+        if (cancelIfUncommitted(event)) return;
+        if (event.pointerType !== "mouse" || pinned) return;
+        clear();
+      },
+      onPointerCancel: (event) => {
+        if (cancelIfUncommitted(event)) return;
+        if (event.pointerType !== "mouse" || pinned) return;
+        clear();
+      }
+    };
+  };
+  const onKeyDown = (event) => {
+    const list = targetsRef.current;
+    if (list.length === 0) return;
+    if (event.key === "Escape") {
+      clear();
+      return;
+    }
+    const cols = columnsRef.current;
+    let delta = 0;
+    switch (event.key) {
+      case "ArrowRight":
+        delta = 1;
+        break;
+      case "ArrowLeft":
+        delta = -1;
+        break;
+      case "ArrowDown":
+        delta = cols ?? 1;
+        break;
+      case "ArrowUp":
+        delta = -(cols ?? 1);
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    const currentIndex = active === null ? -1 : list.findIndex((t) => getKeyRef.current(t) === active.key);
+    const base = currentIndex === -1 ? delta > 0 ? -1 : list.length : currentIndex;
+    const nextIndex = Math.min(Math.max(base + delta, 0), list.length - 1);
+    const next = list[nextIndex];
+    const rect = hostElRef.current?.getBoundingClientRect();
+    const anchor = rect === void 0 ? { x: 0, y: 0 } : { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+    cancelPendingFrame();
+    setActive({ key: getKeyRef.current(next), anchor });
+  };
+  const tip = (() => {
+    if (active === null) return null;
+    const target = findTarget(active.key);
+    return target === void 0 ? null : { target, anchor: active.anchor };
+  })();
+  return {
+    tip,
+    isPinned: pinned,
+    pointerProps,
+    optionId,
+    clear,
+    hostProps: {
+      ref: (node) => {
+        hostElRef.current = node;
+      },
+      tabIndex: 0,
+      role: "listbox",
+      "aria-label": ariaLabel,
+      "aria-activedescendant": tip === null ? void 0 : optionId(tip.target),
+      onKeyDown,
+      onBlur: () => {
+        if (!pinned) clear();
+      }
+    }
+  };
+}
+export {
+  useDiscreteCursor
+};

package/dist/charts/hooks/use-hysteresis.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A derived value that feeds back into its own next computation — hysteresis, "was X last frame" —
+ * without the anti-pattern of mutating a ref during render (`ChartCard`'s short-card flag, P0-1;
+ * `Donut`'s side/stacked layout, P2-10, both hit the SAME bug independently: a render a concurrent
+ * commit discards must not still poison the next real one's input).
+ *
+ * `compute` is called with the PREVIOUS committed value (never mutated here) and returns this
+ * render's value; the ref only updates in a `useLayoutEffect`, after the value has actually
+ * committed. Internal only — not on any public barrel.
+ *
+ * @example
+ * const short = useHysteresis(
+ *   (wasShort) => measuredHeight > 0 && measuredHeight < (wasShort ? EXIT : ENTER),
+ *   false,
+ * )
+ */
+export declare function useHysteresis<T>(compute: (previous: T) => T, initial: T): T;
+//# sourceMappingURL=use-hysteresis.d.ts.map

package/dist/charts/hooks/use-hysteresis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-hysteresis.d.ts","sourceRoot":"","sources":["../../../src/charts/hooks/use-hysteresis.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAO3E"}

package/dist/charts/hooks/use-hysteresis.js

@@ -0,0 +1,12 @@
+import { useLayoutEffect, useRef } from "react";
+function useHysteresis(compute, initial) {
+  const ref = useRef(initial);
+  const value = compute(ref.current);
+  useLayoutEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return value;
+}
+export {
+  useHysteresis
+};

package/dist/charts/hooks/useBandPlot.d.ts

@@ -122,6 +122,13 @@ export type BandPlot<T> = {
     /** Drawn width of one band — the pitch minus a 1px separator, floored at 1. */
     bandWidth: number;
     tickValues: string[];
+    /** Where the left axis paints: inside the plot (compact), not at all (micro), else outside. An
+     * explicit `margin.left` keeps it outside. Same law as `CartesianChart`. */
+    yPlacement: 'outside' | 'inside' | 'none';
+    /** Terminal x labels anchor inward (compact/micro). */
+    xAnchorTerminals: boolean;
+    /** Width to wrap x labels to; undefined when they do not wrap. */
+    xWrapWidth: number | undefined;
     svgRef: RefObject<SVGSVGElement | null>;
     tooltipAnchor: CursorAnchor | null;
     showTooltip: boolean;

package/dist/charts/hooks/useBandPlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBandPlot.d.ts","sourceRoot":"","sources":["../../../src/charts/hooks/useBandPlot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useBandPlot.d.ts","sourceRoot":"","sources":["../../../src/charts/hooks/useBandPlot.ts"],"names":[],"mappings":"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"}