@galaxy-io/dls 1.6.1 → 2.0.1

package/dist/hooks/useDismiss.js

@@ -1,43 +1,55 @@
 import { useEffect, useRef } from "react";
-import { useHotkeys } from "react-hotkeys-hook";
 //#region src/hooks/useDismiss.ts
+/** Focus in one of these keeps Escape for the field (clearing a search, cancelling an edit). */
+var isEditableTarget = (target) => {
+	if (!(target instanceof HTMLElement)) return false;
+	const tag = target.tagName;
+	return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || target.isContentEditable;
+};
 /**
-* Closes a floating element on Escape or a click outside it. Returns the ref to
-* attach to the element you want to keep open.
+* Dismisses an app-built floating element on Escape or on a mousedown outside it. Returns the ref
+* to attach to the element that should stay open. DLS overlays (Popover, Modal, Drawer, Menu,
+* Tooltip, Toast) dismiss themselves through the overlay stack and never need this hook.
+*
+* Every mounted `useDismiss` hears every Escape (its own `document` listener, no shortcut
+* registry), except one an open DLS overlay has already consumed (the overlay stack calls
+* `preventDefault()`; mount order decides which listener runs first). SSR-safe: listeners attach
+* in effects only.
 *
-* Accepts either a bare handler or an options object as the first argument.
+* @example
+* const ref = useDismiss<HTMLDivElement>({ onDismiss: () => onOpenChange(false), isEnabled: isOpen });
+* return <div ref={ref}>…</div>;
 */
-var useDismiss = (handlerOrOptions, options) => {
-	const isOptionsOnly = typeof handlerOrOptions !== "function";
-	const handler = isOptionsOnly ? void 0 : handlerOrOptions;
-	const { excludeRefs, enableEscape = true, enableClickOutside = true, enabled = true, onDismiss } = (isOptionsOnly ? handlerOrOptions : options) || {};
+function useDismiss({ onDismiss, isEnabled = true, shouldCloseOnEscape = true, shouldCloseOnOutsideClick = true, excludeRefs }) {
 	const ref = useRef(null);
-	const dismissHandler = onDismiss ?? handler;
-	const handlerRef = useRef(dismissHandler);
+	const onDismissRef = useRef(onDismiss);
 	const excludeRefsRef = useRef(excludeRefs);
 	useEffect(() => {
-		handlerRef.current = dismissHandler;
+		onDismissRef.current = onDismiss;
 		excludeRefsRef.current = excludeRefs;
-	}, [dismissHandler, excludeRefs]);
+	}, [onDismiss, excludeRefs]);
 	useEffect(() => {
-		if (!enabled || !enableClickOutside) return;
-		const handleClickOutside = (event) => {
+		if (!isEnabled || !shouldCloseOnOutsideClick) return;
+		const handleMouseDown = (event) => {
 			const target = event.target;
-			if (ref.current && ref.current.contains(target)) return;
-			if (excludeRefsRef.current) {
-				for (const excludeRef of excludeRefsRef.current) if (excludeRef.current && excludeRef.current.contains(target)) return;
-			}
-			if (handlerRef.current) handlerRef.current();
+			if (ref.current?.contains(target)) return;
+			for (const excludeRef of excludeRefsRef.current ?? []) if (excludeRef.current?.contains(target)) return;
+			onDismissRef.current?.();
 		};
-		document.addEventListener("mousedown", handleClickOutside);
-		return () => {
-			document.removeEventListener("mousedown", handleClickOutside);
+		document.addEventListener("mousedown", handleMouseDown);
+		return () => document.removeEventListener("mousedown", handleMouseDown);
+	}, [isEnabled, shouldCloseOnOutsideClick]);
+	useEffect(() => {
+		if (!isEnabled || !shouldCloseOnEscape) return;
+		const handleKeyDown = (event) => {
+			if (event.key !== "Escape" || event.defaultPrevented || event.isComposing) return;
+			if (isEditableTarget(event.target)) return;
+			onDismissRef.current?.();
 		};
-	}, [enabled, enableClickOutside]);
-	useHotkeys("esc", () => {
-		if (enabled && handlerRef.current) handlerRef.current();
-	}, { enabled: enabled && enableEscape }, [enabled, enableEscape]);
+		document.addEventListener("keydown", handleKeyDown);
+		return () => document.removeEventListener("keydown", handleKeyDown);
+	}, [isEnabled, shouldCloseOnEscape]);
 	return ref;
-};
+}
 //#endregion
 export { useDismiss };

package/dist/hooks/useElementClientSize.d.ts

@@ -1,20 +1,20 @@
+import { type RefObject } from "react";
 /** Measured client size. Both fields are `undefined` before the first measurement. */
 export interface ElementClientSize {
+    /** `clientWidth` in pixels, or `undefined` before the first measurement. */
     width: number | undefined;
+    /** `clientHeight` in pixels, or `undefined` before the first measurement. */
     height: number | undefined;
 }
 /**
- * Hook that tracks an element's *client* size — the padding box, excluding
- * scrollbars and borders.
+ * Tracks an element's *client* size — the padding box, excluding scrollbars and borders.
  *
- * Use this instead of {@link useElementWidth} when the measurement drives
- * something that must line up with the scrollport (a sticky overlay, a
- * viewport-width panel). `useElementWidth` measures the border box via
- * `getBoundingClientRect`, which includes the scrollbar gutter and would make
- * such an element overhang.
+ * Use this instead of `useElementWidth` when the measurement drives something that must line up
+ * with the scrollport (a sticky overlay, a viewport-width panel). `useElementWidth` measures the
+ * border box via `getBoundingClientRect`, which includes the scrollbar gutter and would make such
+ * an element overhang. SSR-safe: measures in an effect, `undefined` on the server.
  *
  * @param ref - A ref to the element to measure
- * @returns The current client width/height in pixels, or undefined before the
- *   first measurement
+ * @returns The current client width/height in pixels, or undefined before the first measurement
  */
-export declare const useElementClientSize: (ref: React.RefObject<HTMLElement | null>) => ElementClientSize;
+export declare function useElementClientSize(ref: RefObject<HTMLElement | null>): ElementClientSize;

package/dist/hooks/useElementClientSize.js

@@ -1,20 +1,17 @@
 import { useEffect, useState } from "react";
 //#region src/hooks/useElementClientSize.ts
 /**
-* Hook that tracks an element's *client* size — the padding box, excluding
-* scrollbars and borders.
+* Tracks an element's *client* size — the padding box, excluding scrollbars and borders.
 *
-* Use this instead of {@link useElementWidth} when the measurement drives
-* something that must line up with the scrollport (a sticky overlay, a
-* viewport-width panel). `useElementWidth` measures the border box via
-* `getBoundingClientRect`, which includes the scrollbar gutter and would make
-* such an element overhang.
+* Use this instead of `useElementWidth` when the measurement drives something that must line up
+* with the scrollport (a sticky overlay, a viewport-width panel). `useElementWidth` measures the
+* border box via `getBoundingClientRect`, which includes the scrollbar gutter and would make such
+* an element overhang. SSR-safe: measures in an effect, `undefined` on the server.
 *
 * @param ref - A ref to the element to measure
-* @returns The current client width/height in pixels, or undefined before the
-*   first measurement
+* @returns The current client width/height in pixels, or undefined before the first measurement
 */
-var useElementClientSize = (ref) => {
+function useElementClientSize(ref) {
 	const [size, setSize] = useState({
 		width: void 0,
 		height: void 0
@@ -38,6 +35,6 @@ var useElementClientSize = (ref) => {
 		return () => observer.disconnect();
 	}, [ref]);
 	return size;
-};
+}
 //#endregion
 export { useElementClientSize };

package/dist/hooks/useElementWidth.d.ts

@@ -1,6 +1,8 @@
+import { type RefObject } from "react";
 /**
- * Hook that measures and tracks the width of an element using ResizeObserver.
- * Returns undefined until the first measurement is complete.
+ * Measures and tracks an element's border-box width (`getBoundingClientRect().width`) with a
+ * `ResizeObserver`. Returns `undefined` until the first measurement. SSR-safe: measures in an
+ * effect, `undefined` on the server.
  *
  * @param ref - A ref to the element to measure
  * @returns The current width of the element in pixels, or undefined if not yet measured
@@ -8,15 +10,6 @@
  * @example
  * const containerRef = useRef<HTMLDivElement>(null);
  * const width = useElementWidth(containerRef);
- *
- * if (width === undefined) {
- *   return <div ref={containerRef} />;
- * }
- *
- * return (
- *   <div ref={containerRef}>
- *     <Chart width={width} />
- *   </div>
- * );
+ * return <div ref={containerRef}>{width === undefined ? null : <Chart width={width} />}</div>;
  */
-export declare const useElementWidth: (ref: React.RefObject<HTMLElement | null>) => number | undefined;
+export declare function useElementWidth(ref: RefObject<HTMLElement | null>): number | undefined;

package/dist/hooks/useElementWidth.js

@@ -1,8 +1,9 @@
 import { useEffect, useState } from "react";
 //#region src/hooks/useElementWidth.ts
 /**
-* Hook that measures and tracks the width of an element using ResizeObserver.
-* Returns undefined until the first measurement is complete.
+* Measures and tracks an element's border-box width (`getBoundingClientRect().width`) with a
+* `ResizeObserver`. Returns `undefined` until the first measurement. SSR-safe: measures in an
+* effect, `undefined` on the server.
 *
 * @param ref - A ref to the element to measure
 * @returns The current width of the element in pixels, or undefined if not yet measured
@@ -10,18 +11,9 @@ import { useEffect, useState } from "react";
 * @example
 * const containerRef = useRef<HTMLDivElement>(null);
 * const width = useElementWidth(containerRef);
-*
-* if (width === undefined) {
-*   return <div ref={containerRef} />;
-* }
-*
-* return (
-*   <div ref={containerRef}>
-*     <Chart width={width} />
-*   </div>
-* );
+* return <div ref={containerRef}>{width === undefined ? null : <Chart width={width} />}</div>;
 */
-var useElementWidth = (ref) => {
+function useElementWidth(ref) {
 	const [width, setWidth] = useState(void 0);
 	useEffect(() => {
 		const element = ref.current;
@@ -39,6 +31,6 @@ var useElementWidth = (ref) => {
 		return () => observer.disconnect();
 	}, [ref]);
 	return width;
-};
+}
 //#endregion
 export { useElementWidth };

package/dist/hooks/useField.d.ts

@@ -0,0 +1,47 @@
+/** What a Field tells the control inside it. `null` outside a Field. */
+export interface FieldContextValue {
+    /** The id the control must carry; the Field label's `htmlFor`. */
+    controlId: string;
+    /** Id of the visible label, for controls that are not labelable elements (`aria-labelledby`). `undefined` without a `label`. */
+    labelId: string | undefined;
+    /** Space-separated ids of the description, counter and error currently rendered, for `aria-describedby`. `undefined` when none. */
+    describedBy: string | undefined;
+    /** The Field's `isRequired`. */
+    isRequired: boolean;
+    /** `true` when the Field has an `error`. */
+    isError: boolean;
+}
+/** The context `Field` provides to its control. Default `null`; `Field` is the only provider. */
+export declare const FieldContext: import("react").Context<FieldContextValue | null>;
+/**
+ * The nearest `Field`'s wiring for the control inside it, or `null` outside a Field.
+ *
+ * The consumer contract, which every DLS input follows and a custom control should too:
+ * - set `id = field.controlId` (the Field's id wins over the control's own `id`);
+ * - merge `field.describedBy` into `aria-describedby`;
+ * - set `aria-invalid` when `field.isError` (or the control's own error);
+ * - set `aria-required` (and native `required` where it exists) when `field.isRequired`;
+ * - draw the error border when `field.isError`;
+ * - a control that is not a labelable element (`role="radiogroup"`, a `div` switch, a listbox
+ *   trigger) sets `aria-labelledby={field.labelId}`.
+ *
+ * A control wrapped in a Field must not also receive its own `label`.
+ *
+ * @returns The Field's control id, label id, `aria-describedby` ids, required and invalid flags
+ *
+ * @example
+ * function MyPicker() {
+ *   const field = useField();
+ *   return (
+ *     <div
+ *       role="listbox"
+ *       id={field?.controlId}
+ *       aria-labelledby={field?.labelId}
+ *       aria-describedby={field?.describedBy}
+ *       aria-invalid={field?.isError || undefined}
+ *       aria-required={field?.isRequired || undefined}
+ *     />
+ *   );
+ * }
+ */
+export declare function useField(): FieldContextValue | null;

package/dist/hooks/useField.js

@@ -0,0 +1,40 @@
+import { createContext, useContext } from "react";
+//#region src/hooks/useField.ts
+/** The context `Field` provides to its control. Default `null`; `Field` is the only provider. */
+var FieldContext = createContext(null);
+/**
+* The nearest `Field`'s wiring for the control inside it, or `null` outside a Field.
+*
+* The consumer contract, which every DLS input follows and a custom control should too:
+* - set `id = field.controlId` (the Field's id wins over the control's own `id`);
+* - merge `field.describedBy` into `aria-describedby`;
+* - set `aria-invalid` when `field.isError` (or the control's own error);
+* - set `aria-required` (and native `required` where it exists) when `field.isRequired`;
+* - draw the error border when `field.isError`;
+* - a control that is not a labelable element (`role="radiogroup"`, a `div` switch, a listbox
+*   trigger) sets `aria-labelledby={field.labelId}`.
+*
+* A control wrapped in a Field must not also receive its own `label`.
+*
+* @returns The Field's control id, label id, `aria-describedby` ids, required and invalid flags
+*
+* @example
+* function MyPicker() {
+*   const field = useField();
+*   return (
+*     <div
+*       role="listbox"
+*       id={field?.controlId}
+*       aria-labelledby={field?.labelId}
+*       aria-describedby={field?.describedBy}
+*       aria-invalid={field?.isError || undefined}
+*       aria-required={field?.isRequired || undefined}
+*     />
+*   );
+* }
+*/
+function useField() {
+	return useContext(FieldContext);
+}
+//#endregion
+export { FieldContext, useField };

package/dist/hooks/useHotkey.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Keyboard shortcuts. One `keydown` listener on `document` serves every binding; when several
+ * bindings match, the innermost `scope` wins, then the most recently registered, and only the
+ * winner's handler runs.
+ *
+ * Key grammar (Kbd adopts it): a combo is tokens joined by `+`, matched case-insensitively.
+ * Modifiers are `mod` (⌘ on Mac, Ctrl elsewhere), `ctrl`, `meta` (alias `cmd`), `alt` (alias
+ * `option`) and `shift`, and must match exactly. Exactly one key per combo: a single character,
+ * or `escape` (`esc`), `enter`, `space`, `tab`, `backspace`, `delete`, `up`, `down`, `left`,
+ * `right`, `home`, `end`, `pageup`, `pagedown`, `f1`–`f12`. Letters and digits match on
+ * `event.code` (so Option or Shift cannot change them); every other key on `event.key`.
+ * Sequences (`g g`) are not supported.
+ */
+import { type RefObject } from "react";
+/** Options for `useHotkey`. */
+export interface UseHotkeyOptions {
+    /** Whether the binding is registered. Re-enabling registers it again (it becomes the newest). @default true */
+    isEnabled?: boolean | undefined;
+    /** Only fire while focus is inside this element; a scoped binding beats a global one. */
+    scope?: RefObject<HTMLElement | null> | undefined;
+    /** Call `event.preventDefault()` when this binding fires (e.g. to stop the browser's ⌘K). @default false */
+    shouldPreventDefault?: boolean | undefined;
+    /** Do not fire while focus is in an `input`, `textarea`, `select` or `[contenteditable]`. @default false */
+    shouldIgnoreInputs?: boolean | undefined;
+}
+/** A parsed combo. `mod` resolves to `meta` or `ctrl` at match time. */
+export interface ParsedHotkey {
+    /** ⌘ on Mac, Ctrl elsewhere. */
+    mod: boolean;
+    /** Control. */
+    ctrl: boolean;
+    /** ⌘ / Windows key. */
+    meta: boolean;
+    /** Option / Alt. */
+    alt: boolean;
+    /** Shift. */
+    shift: boolean;
+    /** `KeyK` / `Digit1` when `matchOn` is `code`; the lowercased `event.key` otherwise. */
+    key: string;
+    /** Which `KeyboardEvent` field `key` is compared with. */
+    matchOn: "code" | "key";
+}
+/** The `KeyboardEvent` fields the matcher reads. */
+export type HotkeyEventLike = Pick<KeyboardEvent, "key" | "code" | "ctrlKey" | "metaKey" | "altKey" | "shiftKey">;
+/**
+ * Parses one combo (`"mod+k"`, `"shift+enter"`, `"escape"`) per the grammar above. Returns
+ * `null` when it does not parse: an empty token, an unknown key name, or not exactly one key.
+ *
+ * @param combo - The combo to parse
+ * @returns The parsed combo, or `null`
+ */
+export declare function parseHotkey(combo: string): ParsedHotkey | null;
+/**
+ * Whether `event` is exactly `hotkey`: the key, and every modifier pressed or not as written.
+ *
+ * @param hotkey - A combo from `parseHotkey`
+ * @param event - The `keydown` event (or its key, code and modifier fields)
+ * @param isMac - Whether `mod` means ⌘ (`true`) or Ctrl (`false`)
+ * @returns Whether the event matches
+ */
+export declare function matchesHotkey(hotkey: ParsedHotkey, event: HotkeyEventLike, isMac: boolean): boolean;
+/**
+ * Binds a keyboard shortcut (`"mod+k"`, `"shift+enter"`, `"escape"`; an array means any of them)
+ * to `handler`. The binding behind `Button shouldBindHotKey`, `SearchInput hotKey` and
+ * `CommandPalette`. When several bindings match, the innermost `scope` wins, then the most
+ * recently registered; only the winner runs, and in development a duplicate combo in the same
+ * scope warns once. Fires inside text fields unless `shouldIgnoreInputs`. A combo that does not
+ * parse warns in development and never fires.
+ *
+ * @param keys - One combo, or an array of combos any of which fires
+ * @param handler - Called with the `keydown` event when this binding wins
+ * @param options - `isEnabled` (default `true`), `scope`, `shouldPreventDefault` (default `false`), `shouldIgnoreInputs` (default `false`)
+ *
+ * @example
+ * useHotkey("mod+k", () => setIsOpen(true), { shouldPreventDefault: true });
+ */
+export declare function useHotkey(keys: string | string[], handler: (event: KeyboardEvent) => void, options?: UseHotkeyOptions): void;

package/dist/hooks/useHotkey.js

@@ -0,0 +1,246 @@
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+import { useIsMac } from "./useIsMac.js";
+import { useEffect, useRef } from "react";
+//#region src/hooks/useHotkey.ts
+/**
+* Keyboard shortcuts. One `keydown` listener on `document` serves every binding; when several
+* bindings match, the innermost `scope` wins, then the most recently registered, and only the
+* winner's handler runs.
+*
+* Key grammar (Kbd adopts it): a combo is tokens joined by `+`, matched case-insensitively.
+* Modifiers are `mod` (⌘ on Mac, Ctrl elsewhere), `ctrl`, `meta` (alias `cmd`), `alt` (alias
+* `option`) and `shift`, and must match exactly. Exactly one key per combo: a single character,
+* or `escape` (`esc`), `enter`, `space`, `tab`, `backspace`, `delete`, `up`, `down`, `left`,
+* `right`, `home`, `end`, `pageup`, `pagedown`, `f1`–`f12`. Letters and digits match on
+* `event.code` (so Option or Shift cannot change them); every other key on `event.key`.
+* Sequences (`g g`) are not supported.
+*/
+/** Modifier tokens and their aliases. A `Map`, so `"constructor"` is not a modifier. */
+var MODIFIER_TOKEN_TO_MODIFIER_MAP = new Map([
+	["mod", "mod"],
+	["ctrl", "ctrl"],
+	["meta", "meta"],
+	["cmd", "meta"],
+	["alt", "alt"],
+	["option", "alt"],
+	["shift", "shift"]
+]);
+/** Named keys → the lowercased `event.key` they match. */
+var KEY_NAME_TO_EVENT_KEY_MAP = new Map([
+	["escape", "escape"],
+	["esc", "escape"],
+	["enter", "enter"],
+	["space", " "],
+	["tab", "tab"],
+	["backspace", "backspace"],
+	["delete", "delete"],
+	["up", "arrowup"],
+	["down", "arrowdown"],
+	["left", "arrowleft"],
+	["right", "arrowright"],
+	["home", "home"],
+	["end", "end"],
+	["pageup", "pageup"],
+	["pagedown", "pagedown"],
+	...Array.from({ length: 12 }, (_, index) => [`f${index + 1}`, `f${index + 1}`])
+]);
+var LETTER = /^[a-z]$/;
+var DIGIT = /^[0-9]$/;
+/**
+* Parses one combo (`"mod+k"`, `"shift+enter"`, `"escape"`) per the grammar above. Returns
+* `null` when it does not parse: an empty token, an unknown key name, or not exactly one key.
+*
+* @param combo - The combo to parse
+* @returns The parsed combo, or `null`
+*/
+function parseHotkey(combo) {
+	const parsed = {
+		mod: false,
+		ctrl: false,
+		meta: false,
+		alt: false,
+		shift: false,
+		key: "",
+		matchOn: "key"
+	};
+	let keyCount = 0;
+	for (const rawToken of combo.split("+")) {
+		const token = rawToken.trim().toLowerCase();
+		if (token === "") return null;
+		const modifier = MODIFIER_TOKEN_TO_MODIFIER_MAP.get(token);
+		if (modifier !== void 0) {
+			parsed[modifier] = true;
+			continue;
+		}
+		keyCount += 1;
+		const namedKey = KEY_NAME_TO_EVENT_KEY_MAP.get(token);
+		if (LETTER.test(token)) {
+			parsed.key = `Key${token.toUpperCase()}`;
+			parsed.matchOn = "code";
+		} else if (DIGIT.test(token)) {
+			parsed.key = `Digit${token}`;
+			parsed.matchOn = "code";
+		} else if (namedKey !== void 0) {
+			parsed.key = namedKey;
+			parsed.matchOn = "key";
+		} else if ([...token].length === 1) {
+			parsed.key = token;
+			parsed.matchOn = "key";
+		} else return null;
+	}
+	return keyCount === 1 ? parsed : null;
+}
+/**
+* Whether `event` is exactly `hotkey`: the key, and every modifier pressed or not as written.
+*
+* @param hotkey - A combo from `parseHotkey`
+* @param event - The `keydown` event (or its key, code and modifier fields)
+* @param isMac - Whether `mod` means ⌘ (`true`) or Ctrl (`false`)
+* @returns Whether the event matches
+*/
+function matchesHotkey(hotkey, event, isMac) {
+	return (hotkey.matchOn === "code" ? event.code === hotkey.key : event.key.toLowerCase() === hotkey.key) && event.ctrlKey === (hotkey.ctrl || hotkey.mod && !isMac) && event.metaKey === (hotkey.meta || hotkey.mod && isMac) && event.altKey === hotkey.alt && event.shiftKey === hotkey.shift;
+}
+/** One canonical spelling per combo, for the dev conflict warning (`"Cmd+K"` = `"meta+k"`). */
+var toCanonicalCombo = (hotkey) => [
+	hotkey.mod && "mod",
+	hotkey.ctrl && "ctrl",
+	hotkey.meta && "meta",
+	hotkey.alt && "alt",
+	hotkey.shift && "shift",
+	`${hotkey.matchOn}:${hotkey.key}`
+].filter(Boolean).join("+");
+function isDevelopment() {
+	try {
+		return process.env.NODE_ENV !== "production";
+	} catch {
+		return false;
+	}
+}
+/** Created on the first registration, so nothing runs at module scope. */
+var registry;
+var isEditableTarget = (target) => target instanceof HTMLElement && (target.isContentEditable || [
+	"INPUT",
+	"TEXTAREA",
+	"SELECT"
+].includes(target.tagName));
+/** Whether `a` beats `b`: the innermost scope, then the newest registration. */
+function isHigherPriority(a, b) {
+	const scopeA = a.scope?.current ?? null;
+	const scopeB = b.scope?.current ?? null;
+	if (scopeA !== scopeB) {
+		if (scopeB === null) return true;
+		if (scopeA === null) return false;
+		return scopeB.contains(scopeA);
+	}
+	return a.order > b.order;
+}
+function handleKeyDown(event) {
+	if (registry === void 0) return;
+	const target = event.target instanceof Node ? event.target : null;
+	let winner;
+	for (const binding of registry.bindings) {
+		const state = binding.stateRef.current;
+		if (state === null) continue;
+		if (!binding.hotkeys.some((hotkey) => matchesHotkey(hotkey, event, state.isMac))) continue;
+		if (binding.scope !== void 0) {
+			const scope = binding.scope.current;
+			if (scope === null || target === null || !scope.contains(target)) continue;
+		}
+		if (state.shouldIgnoreInputs && isEditableTarget(event.target)) continue;
+		if (winner === void 0 || isHigherPriority(binding, winner)) winner = binding;
+	}
+	const state = winner?.stateRef.current;
+	if (state === void 0 || state === null) return;
+	if (state.shouldPreventDefault) event.preventDefault();
+	state.handler(event);
+}
+function register(binding, combos) {
+	if (registry === void 0) registry = {
+		bindings: /* @__PURE__ */ new Set(),
+		nextOrder: 0,
+		handleKeyDown
+	};
+	const current = registry;
+	if (current.bindings.size === 0) document.addEventListener("keydown", current.handleKeyDown);
+	if (isDevelopment()) {
+		const scope = binding.scope?.current ?? null;
+		const held = new Set([...current.bindings].filter((other) => (other.scope?.current ?? null) === scope).flatMap((other) => other.hotkeys.map(toCanonicalCombo)));
+		const conflicts = combos.filter((_, index) => {
+			const hotkey = binding.hotkeys[index];
+			return hotkey !== void 0 && held.has(toCanonicalCombo(hotkey));
+		});
+		if (conflicts.length > 0) console.warn(`[@galaxy-io/dls] useHotkey: "${conflicts.join("\", \"")}" is already bound in the same scope; the most recently registered binding wins.`);
+	}
+	const entry = {
+		...binding,
+		order: current.nextOrder
+	};
+	current.nextOrder += 1;
+	current.bindings.add(entry);
+	return () => {
+		current.bindings.delete(entry);
+		if (current.bindings.size === 0) document.removeEventListener("keydown", current.handleKeyDown);
+	};
+}
+/**
+* Binds a keyboard shortcut (`"mod+k"`, `"shift+enter"`, `"escape"`; an array means any of them)
+* to `handler`. The binding behind `Button shouldBindHotKey`, `SearchInput hotKey` and
+* `CommandPalette`. When several bindings match, the innermost `scope` wins, then the most
+* recently registered; only the winner runs, and in development a duplicate combo in the same
+* scope warns once. Fires inside text fields unless `shouldIgnoreInputs`. A combo that does not
+* parse warns in development and never fires.
+*
+* @param keys - One combo, or an array of combos any of which fires
+* @param handler - Called with the `keydown` event when this binding wins
+* @param options - `isEnabled` (default `true`), `scope`, `shouldPreventDefault` (default `false`), `shouldIgnoreInputs` (default `false`)
+*
+* @example
+* useHotkey("mod+k", () => setIsOpen(true), { shouldPreventDefault: true });
+*/
+function useHotkey(keys, handler, options) {
+	const isEnabled = options?.isEnabled ?? true;
+	const scope = options?.scope;
+	const isMac = useIsMac();
+	const stateRef = useRef({
+		handler,
+		isMac,
+		shouldPreventDefault: options?.shouldPreventDefault ?? false,
+		shouldIgnoreInputs: options?.shouldIgnoreInputs ?? false
+	});
+	useIsomorphicLayoutEffect(() => {
+		stateRef.current = {
+			handler,
+			isMac,
+			shouldPreventDefault: options?.shouldPreventDefault ?? false,
+			shouldIgnoreInputs: options?.shouldIgnoreInputs ?? false
+		};
+	});
+	const combosKey = (Array.isArray(keys) ? keys : [keys]).join("\n");
+	useEffect(() => {
+		if (!isEnabled) return;
+		const combos = [];
+		const hotkeys = [];
+		for (const combo of combosKey.split("\n")) {
+			const hotkey = parseHotkey(combo);
+			if (hotkey === null) {
+				if (isDevelopment()) console.warn(`[@galaxy-io/dls] useHotkey: "${combo}" is not a valid combo; it never fires.`);
+				continue;
+			}
+			combos.push(combo);
+			hotkeys.push(hotkey);
+		}
+		if (hotkeys.length === 0) return;
+		return register({
+			hotkeys,
+			scope,
+			stateRef
+		}, combos);
+	}, [
+		isEnabled,
+		combosKey,
+		scope
+	]);
+}
+//#endregion
+export { matchesHotkey, parseHotkey, useHotkey };

package/dist/hooks/useIsMac.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether the user is on an Apple platform (macOS, iOS, iPadOS), for ⌘ vs Ctrl labels and
+ * bindings. Reads `navigator.userAgentData.platform`, falling back to `navigator.platform`.
+ * `false` on the server and during hydration; the client re-renders once with the real value.
+ *
+ * @returns Whether the platform is macOS, iOS or iPadOS
+ *
+ * @example
+ * const isMac = useIsMac();
+ * const modLabel = isMac ? "⌘" : "Ctrl";
+ */
+export declare function useIsMac(): boolean;