@entifix/react-controls 0.19.0 → 0.20.1

package/dist/ui/utils/use-hotkey.d.ts

@@ -1,31 +1,50 @@
-/** One chord, described the way a person would say it. */
-export interface Hotkey {
-    /** The `KeyboardEvent.key`, compared case-insensitively. */
-    readonly key: string;
-    /** ⌘ on a Mac, Ctrl elsewhere. Either satisfies it. */
-    readonly mod?: boolean;
-    readonly shift?: boolean;
+/**
+ * Where a set of shortcuts applies: the page, or one workspace tab. A tab's
+ * shortcuts fire only while it is the active tab, so two tabs each holding a
+ * form can both bind Mod+S without one saving the other.
+ */
+export interface HotkeyScope {
+    readonly id: string;
+    readonly active: boolean;
 }
+/** The page: every shortcut outside a workspace tab. */
+export declare const PAGE_SCOPE: HotkeyScope;
 /**
- * Fire `handler` when any of `hotkeys` is pressed, anywhere on the page.
- *
- * The repo's first global shortcut, so two things are decided here rather than
- * at each future call site.
- *
- * **It skips while focus is in an editable element**, because a page-wide
- * listener that does not would eat the chord a person meant for the field they
- * are typing in. The palette's own input is exempt in practice: the palette
- * unmounts its trigger's listener behaviour by simply not being open.
+ * Scopes the shortcuts bound below it — a workspace tab passes its own id and
+ * whether it is the active tab.
+ */
+export declare const HotkeyScopeProvider: import("react").Provider<HotkeyScope>;
+/** For specs: a page with nothing bound. */
+export declare const resetHotkeysForTesting: () => void;
+export interface HotkeyOptions {
+    /**
+     * Bind only if the chord is free, and stay silent if it is not. Without it
+     * a second binding of a chord in one scope throws at registration: two
+     * handlers for one keystroke is a bug, and whichever fired first would
+     * decide what the reader got. A built-in default — a form's Mod+S — takes
+     * this, so a host's own binding wins.
+     */
+    readonly ifFree?: boolean;
+    /** Bound only while true; a disabled control's shortcut does nothing. */
+    readonly enabled?: boolean;
+}
+/**
+ * Runs `handler` on any of `chords` — `"Mod+K"`, `"Mod+Shift+P"` — within
+ * the nearest {@link HotkeyScope} (ADR 0026).
  *
- * **It calls `preventDefault`**, which is what stops the browser acting on a
- * chord it also claims. ⚠️ That is not guaranteed to work: Chrome, Safari and
- * Edge dispatch these to the page and honour it, Firefox reserves some chords
- * and ignores `defaultPrevented` for them. So no single binding may be
- * load-bearing — bind more than one, and always leave a visible control that
- * does the same thing.
+ * - **Modifier chords only**: every one holds `Mod`, so no single key or
+ *   Shift+key steals a character from a reader typing (WCAG 2.1.4), and no
+ *   Alt+letter, which macOS Option composes into a character. The editing
+ *   chords — Mod+A, C, V, X, Y, Z — stay the field's. Anything else throws
+ *   when it is bound.
+ * - **They fire inside a text field**: a chord is never typing, and Mod+S
+ *   is exactly what a reader presses with the caret in a field.
+ * - **A chord is held once per scope**, so a conflict is refused when it is
+ *   bound rather than resolved by whoever listens first.
  *
- * `handler` is held in a ref so a caller may pass an inline closure without
- * re-subscribing the listener on every render.
+ * It calls `preventDefault`, which stops the browser's own action for the
+ * chord where the browser lets it; no binding should be the only way to do
+ * anything, so a visible control always does the same thing.
  */
-export declare function useHotkey(hotkeys: readonly Hotkey[], handler: (event: KeyboardEvent) => void): void;
+export declare function useHotkey(chords: readonly string[], handler: (event: KeyboardEvent) => void, { ifFree, enabled }?: HotkeyOptions): void;
 //# sourceMappingURL=use-hotkey.d.ts.map

package/dist/ui/utils/use-hotkey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-hotkey.d.ts","sourceRoot":"","sources":["../../../src/ui/utils/use-hotkey.ts"],"names":[],"mappings":"AAIA,0DAA0D;AAC1D,MAAM,WAAW,MAAM;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AA2BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GACtC,IAAI,CAwBN"}
+{"version":3,"file":"use-hotkey.d.ts","sourceRoot":"","sources":["../../../src/ui/utils/use-hotkey.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,wDAAwD;AACxD,eAAO,MAAM,UAAU,EAAE,WAA0C,CAAC;AAIpE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,uCAA8B,CAAC;AAgC/D,4CAA4C;AAC5C,eAAO,MAAM,sBAAsB,QAAO,IAAqB,CAAC;AAUhE,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EACvC,EAAE,MAAc,EAAE,OAAc,EAAE,GAAE,aAAkB,GACrD,IAAI,CAqCN"}

package/dist/ui/utils/use-hotkey.js

@@ -1,68 +1,100 @@
 'use client';
-import { useEffect, useRef } from 'react';
-const isEditable = (target)=>{
-    if (!(target instanceof HTMLElement)) return false;
-    const tag = target.tagName;
-    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
-    // `closest`, not `isContentEditable`: the property is true for a *descendant*
-    // of an editable host but is not implemented in jsdom, so the branch that
-    // matters most for a rich editor would be the one no test could reach. The
-    // selector covers the host and everything inside it, and the `:not` arm is
-    // what keeps `contenteditable="false"` — the way a widget opts a subtree back
-    // out — from reading as editable.
-    return target.closest('[contenteditable]:not([contenteditable="false"])') !== null;
+import { parseChord } from '@entifix/core';
+import { createContext, useContext, useEffect, useRef } from 'react';
+/** The page: every shortcut outside a workspace tab. */ export const PAGE_SCOPE = {
+    id: 'page',
+    active: true
 };
-const matches = (event, hotkey)=>{
-    var _hotkey_mod, _hotkey_shift;
-    if (event.key.toLowerCase() !== hotkey.key.toLowerCase()) return false;
-    // ⌘ and Ctrl are the same intent on different platforms, so either satisfies
-    // `mod` rather than the hook asking the caller to sniff the platform. Nothing
-    // in the fleet binds a chord that means one thing with ⌘ and another with Ctrl.
-    const mod = event.metaKey || event.ctrlKey;
-    if (((_hotkey_mod = hotkey.mod) != null ? _hotkey_mod : false) !== mod) return false;
-    return ((_hotkey_shift = hotkey.shift) != null ? _hotkey_shift : false) === event.shiftKey;
+const HotkeyScopeContext = createContext(PAGE_SCOPE);
+/**
+ * Scopes the shortcuts bound below it — a workspace tab passes its own id and
+ * whether it is the active tab.
+ */ export const HotkeyScopeProvider = HotkeyScopeContext.Provider;
+/**
+ * Which chords each scope holds, for refusing a second binding of one. A
+ * chord is held at most once per scope — a second binding is refused or
+ * yields — so a set is enough.
+ */ const bound = new Map();
+const holds = (scope, chord)=>{
+    var _bound_get;
+    return ((_bound_get = bound.get(scope)) == null ? void 0 : _bound_get.has(chord)) === true;
 };
 /**
- * Fire `handler` when any of `hotkeys` is pressed, anywhere on the page.
- *
- * The repo's first global shortcut, so two things are decided here rather than
- * at each future call site.
- *
- * **It skips while focus is in an editable element**, because a page-wide
- * listener that does not would eat the chord a person meant for the field they
- * are typing in. The palette's own input is exempt in practice: the palette
- * unmounts its trigger's listener behaviour by simply not being open.
+ * Whether `chord` is taken where `scope` would bind it: in the same scope, or
+ * — since the page's shortcuts apply inside every tab — between the page and
+ * a tab.
+ */ function isTaken(scope, chord) {
+    if (holds(scope, chord)) return true;
+    if (scope === PAGE_SCOPE.id) return [
+        ...bound.values()
+    ].some((chords)=>chords.has(chord));
+    return holds(PAGE_SCOPE.id, chord);
+}
+function bind(scope, chord) {
+    var _bound_get;
+    const chords = (_bound_get = bound.get(scope)) != null ? _bound_get : new Set();
+    bound.set(scope, chords.add(chord));
+    return ()=>{
+        chords.delete(chord);
+    };
+}
+/** For specs: a page with nothing bound. */ export const resetHotkeysForTesting = ()=>bound.clear();
+const matches = (event, chord)=>event.key.toLowerCase() === chord.key && // ⌘ and Ctrl are the same intent on different platforms, so either one
+    // satisfies `Mod` rather than each caller sniffing the platform.
+    (event.metaKey || event.ctrlKey) && event.shiftKey === chord.shift && event.altKey === chord.alt;
+/**
+ * Runs `handler` on any of `chords` — `"Mod+K"`, `"Mod+Shift+P"` — within
+ * the nearest {@link HotkeyScope} (ADR 0026).
  *
- * **It calls `preventDefault`**, which is what stops the browser acting on a
- * chord it also claims. ⚠️ That is not guaranteed to work: Chrome, Safari and
- * Edge dispatch these to the page and honour it, Firefox reserves some chords
- * and ignores `defaultPrevented` for them. So no single binding may be
- * load-bearing — bind more than one, and always leave a visible control that
- * does the same thing.
+ * - **Modifier chords only**: every one holds `Mod`, so no single key or
+ *   Shift+key steals a character from a reader typing (WCAG 2.1.4), and no
+ *   Alt+letter, which macOS Option composes into a character. The editing
+ *   chords — Mod+A, C, V, X, Y, Z — stay the field's. Anything else throws
+ *   when it is bound.
+ * - **They fire inside a text field**: a chord is never typing, and Mod+S
+ *   is exactly what a reader presses with the caret in a field.
+ * - **A chord is held once per scope**, so a conflict is refused when it is
+ *   bound rather than resolved by whoever listens first.
  *
- * `handler` is held in a ref so a caller may pass an inline closure without
- * re-subscribing the listener on every render.
- */ export function useHotkey(hotkeys, handler) {
+ * It calls `preventDefault`, which stops the browser's own action for the
+ * chord where the browser lets it; no binding should be the only way to do
+ * anything, so a visible control always does the same thing.
+ */ export function useHotkey(chords, handler, { ifFree = false, enabled = true } = {}) {
+    const scope = useContext(HotkeyScopeContext);
     const handlerRef = useRef(handler);
+    const activeRef = useRef(scope.active);
     useEffect(()=>{
         handlerRef.current = handler;
+        activeRef.current = scope.active;
     });
-    // Serialized rather than passed by identity: callers build the array inline,
-    // so the array itself is a new object every render and would re-subscribe the
-    // listener on each one.
-    const signature = JSON.stringify(hotkeys);
+    // Joined rather than passed by identity: callers write the list inline.
+    const signature = chords.join(' ');
     useEffect(()=>{
-        const bindings = JSON.parse(signature);
+        if (!enabled || signature === '') return;
+        const parsed = signature.split(' ').map(parseChord);
+        const free = parsed.filter((chord)=>!isTaken(scope.id, chord.text));
+        if (free.length < parsed.length && !ifFree) {
+            const taken = parsed.find((chord)=>!free.includes(chord));
+            throw new Error(`${taken.text} is already bound here. A chord does one thing in a scope: unbind the other, or pass \`ifFree\` to the default that should yield.`);
+        }
+        if (free.length === 0) return;
+        const unbind = free.map((chord)=>bind(scope.id, chord.text));
         const onKeyDown = (event)=>{
-            if (isEditable(event.target)) return;
-            if (!bindings.some((hotkey)=>matches(event, hotkey))) return;
+            if (!activeRef.current) return;
+            if (!free.some((chord)=>matches(event, chord))) return;
             event.preventDefault();
             handlerRef.current(event);
         };
         document.addEventListener('keydown', onKeyDown);
-        return ()=>document.removeEventListener('keydown', onKeyDown);
+        return ()=>{
+            document.removeEventListener('keydown', onKeyDown);
+            for (const release of unbind)release();
+        };
     }, [
-        signature
+        signature,
+        scope.id,
+        ifFree,
+        enabled
     ]);
 }
 

package/dist/ui/utils/use-hotkey.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/ui/utils/use-hotkey.ts"],"sourcesContent":["'use client';\n\nimport { useEffect, useRef } from 'react';\n\n/** One chord, described the way a person would say it. */\nexport interface Hotkey {\n  /** The `KeyboardEvent.key`, compared case-insensitively. */\n  readonly key: string;\n  /** ⌘ on a Mac, Ctrl elsewhere. Either satisfies it. */\n  readonly mod?: boolean;\n  readonly shift?: boolean;\n}\n\nconst isEditable = (target: EventTarget | null): boolean => {\n  if (!(target instanceof HTMLElement)) return false;\n  const tag = target.tagName;\n  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;\n  // `closest`, not `isContentEditable`: the property is true for a *descendant*\n  // of an editable host but is not implemented in jsdom, so the branch that\n  // matters most for a rich editor would be the one no test could reach. The\n  // selector covers the host and everything inside it, and the `:not` arm is\n  // what keeps `contenteditable=\"false\"` — the way a widget opts a subtree back\n  // out — from reading as editable.\n  return (\n    target.closest('[contenteditable]:not([contenteditable=\"false\"])') !== null\n  );\n};\n\nconst matches = (event: KeyboardEvent, hotkey: Hotkey): boolean => {\n  if (event.key.toLowerCase() !== hotkey.key.toLowerCase()) return false;\n  // ⌘ and Ctrl are the same intent on different platforms, so either satisfies\n  // `mod` rather than the hook asking the caller to sniff the platform. Nothing\n  // in the fleet binds a chord that means one thing with ⌘ and another with Ctrl.\n  const mod = event.metaKey || event.ctrlKey;\n  if ((hotkey.mod ?? false) !== mod) return false;\n  return (hotkey.shift ?? false) === event.shiftKey;\n};\n\n/**\n * Fire `handler` when any of `hotkeys` is pressed, anywhere on the page.\n *\n * The repo's first global shortcut, so two things are decided here rather than\n * at each future call site.\n *\n * **It skips while focus is in an editable element**, because a page-wide\n * listener that does not would eat the chord a person meant for the field they\n * are typing in. The palette's own input is exempt in practice: the palette\n * unmounts its trigger's listener behaviour by simply not being open.\n *\n * **It calls `preventDefault`**, which is what stops the browser acting on a\n * chord it also claims. ⚠️ That is not guaranteed to work: Chrome, Safari and\n * Edge dispatch these to the page and honour it, Firefox reserves some chords\n * and ignores `defaultPrevented` for them. So no single binding may be\n * load-bearing — bind more than one, and always leave a visible control that\n * does the same thing.\n *\n * `handler` is held in a ref so a caller may pass an inline closure without\n * re-subscribing the listener on every render.\n */\nexport function useHotkey(\n  hotkeys: readonly Hotkey[],\n  handler: (event: KeyboardEvent) => void,\n): void {\n  const handlerRef = useRef(handler);\n  useEffect(() => {\n    handlerRef.current = handler;\n  });\n\n  // Serialized rather than passed by identity: callers build the array inline,\n  // so the array itself is a new object every render and would re-subscribe the\n  // listener on each one.\n  const signature = JSON.stringify(hotkeys);\n\n  useEffect(() => {\n    const bindings = JSON.parse(signature) as Hotkey[];\n\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (isEditable(event.target)) return;\n      if (!bindings.some(hotkey => matches(event, hotkey))) return;\n      event.preventDefault();\n      handlerRef.current(event);\n    };\n\n    document.addEventListener('keydown', onKeyDown);\n    return () => document.removeEventListener('keydown', onKeyDown);\n  }, [signature]);\n}\n"],"names":["useEffect","useRef","isEditable","target","HTMLElement","tag","tagName","closest","matches","event","hotkey","key","toLowerCase","mod","metaKey","ctrlKey","shift","shiftKey","useHotkey","hotkeys","handler","handlerRef","current","signature","JSON","stringify","bindings","parse","onKeyDown","some","preventDefault","document","addEventListener","removeEventListener"],"mappings":"AAAA;AAEA,SAASA,SAAS,EAAEC,MAAM,QAAQ,QAAQ;AAW1C,MAAMC,aAAa,CAACC;IAClB,IAAI,CAAEA,CAAAA,kBAAkBC,WAAU,GAAI,OAAO;IAC7C,MAAMC,MAAMF,OAAOG,OAAO;IAC1B,IAAID,QAAQ,WAAWA,QAAQ,cAAcA,QAAQ,UAAU,OAAO;IACtE,8EAA8E;IAC9E,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,8EAA8E;IAC9E,kCAAkC;IAClC,OACEF,OAAOI,OAAO,CAAC,wDAAwD;AAE3E;AAEA,MAAMC,UAAU,CAACC,OAAsBC;QAMhCA,aACGA;IANR,IAAID,MAAME,GAAG,CAACC,WAAW,OAAOF,OAAOC,GAAG,CAACC,WAAW,IAAI,OAAO;IACjE,6EAA6E;IAC7E,8EAA8E;IAC9E,gFAAgF;IAChF,MAAMC,MAAMJ,MAAMK,OAAO,IAAIL,MAAMM,OAAO;IAC1C,IAAI,EAACL,cAAAA,OAAOG,GAAG,YAAVH,cAAc,WAAWG,KAAK,OAAO;IAC1C,OAAO,EAACH,gBAAAA,OAAOM,KAAK,YAAZN,gBAAgB,WAAWD,MAAMQ,QAAQ;AACnD;AAEA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASC,UACdC,OAA0B,EAC1BC,OAAuC;IAEvC,MAAMC,aAAapB,OAAOmB;IAC1BpB,UAAU;QACRqB,WAAWC,OAAO,GAAGF;IACvB;IAEA,6EAA6E;IAC7E,8EAA8E;IAC9E,wBAAwB;IACxB,MAAMG,YAAYC,KAAKC,SAAS,CAACN;IAEjCnB,UAAU;QACR,MAAM0B,WAAWF,KAAKG,KAAK,CAACJ;QAE5B,MAAMK,YAAY,CAACnB;YACjB,IAAIP,WAAWO,MAAMN,MAAM,GAAG;YAC9B,IAAI,CAACuB,SAASG,IAAI,CAACnB,CAAAA,SAAUF,QAAQC,OAAOC,UAAU;YACtDD,MAAMqB,cAAc;YACpBT,WAAWC,OAAO,CAACb;QACrB;QAEAsB,SAASC,gBAAgB,CAAC,WAAWJ;QACrC,OAAO,IAAMG,SAASE,mBAAmB,CAAC,WAAWL;IACvD,GAAG;QAACL;KAAU;AAChB"}
+{"version":3,"sources":["../../../src/ui/utils/use-hotkey.ts"],"sourcesContent":["'use client';\n\nimport { parseChord, type ParsedChord } from '@entifix/core';\nimport { createContext, useContext, useEffect, useRef } from 'react';\n\n/**\n * Where a set of shortcuts applies: the page, or one workspace tab. A tab's\n * shortcuts fire only while it is the active tab, so two tabs each holding a\n * form can both bind Mod+S without one saving the other.\n */\nexport interface HotkeyScope {\n  readonly id: string;\n  readonly active: boolean;\n}\n\n/** The page: every shortcut outside a workspace tab. */\nexport const PAGE_SCOPE: HotkeyScope = { id: 'page', active: true };\n\nconst HotkeyScopeContext = createContext<HotkeyScope>(PAGE_SCOPE);\n\n/**\n * Scopes the shortcuts bound below it — a workspace tab passes its own id and\n * whether it is the active tab.\n */\nexport const HotkeyScopeProvider = HotkeyScopeContext.Provider;\n\n/**\n * Which chords each scope holds, for refusing a second binding of one. A\n * chord is held at most once per scope — a second binding is refused or\n * yields — so a set is enough.\n */\nconst bound = new Map<string, Set<string>>();\n\nconst holds = (scope: string, chord: string): boolean =>\n  bound.get(scope)?.has(chord) === true;\n\n/**\n * Whether `chord` is taken where `scope` would bind it: in the same scope, or\n * — since the page's shortcuts apply inside every tab — between the page and\n * a tab.\n */\nfunction isTaken(scope: string, chord: string): boolean {\n  if (holds(scope, chord)) return true;\n  if (scope === PAGE_SCOPE.id)\n    return [...bound.values()].some(chords => chords.has(chord));\n  return holds(PAGE_SCOPE.id, chord);\n}\n\nfunction bind(scope: string, chord: string): () => void {\n  const chords = bound.get(scope) ?? new Set<string>();\n  bound.set(scope, chords.add(chord));\n  return () => {\n    chords.delete(chord);\n  };\n}\n\n/** For specs: a page with nothing bound. */\nexport const resetHotkeysForTesting = (): void => bound.clear();\n\nconst matches = (event: KeyboardEvent, chord: ParsedChord): boolean =>\n  event.key.toLowerCase() === chord.key &&\n  // ⌘ and Ctrl are the same intent on different platforms, so either one\n  // satisfies `Mod` rather than each caller sniffing the platform.\n  (event.metaKey || event.ctrlKey) &&\n  event.shiftKey === chord.shift &&\n  event.altKey === chord.alt;\n\nexport interface HotkeyOptions {\n  /**\n   * Bind only if the chord is free, and stay silent if it is not. Without it\n   * a second binding of a chord in one scope throws at registration: two\n   * handlers for one keystroke is a bug, and whichever fired first would\n   * decide what the reader got. A built-in default — a form's Mod+S — takes\n   * this, so a host's own binding wins.\n   */\n  readonly ifFree?: boolean;\n  /** Bound only while true; a disabled control's shortcut does nothing. */\n  readonly enabled?: boolean;\n}\n\n/**\n * Runs `handler` on any of `chords` — `\"Mod+K\"`, `\"Mod+Shift+P\"` — within\n * the nearest {@link HotkeyScope} (ADR 0026).\n *\n * - **Modifier chords only**: every one holds `Mod`, so no single key or\n *   Shift+key steals a character from a reader typing (WCAG 2.1.4), and no\n *   Alt+letter, which macOS Option composes into a character. The editing\n *   chords — Mod+A, C, V, X, Y, Z — stay the field's. Anything else throws\n *   when it is bound.\n * - **They fire inside a text field**: a chord is never typing, and Mod+S\n *   is exactly what a reader presses with the caret in a field.\n * - **A chord is held once per scope**, so a conflict is refused when it is\n *   bound rather than resolved by whoever listens first.\n *\n * It calls `preventDefault`, which stops the browser's own action for the\n * chord where the browser lets it; no binding should be the only way to do\n * anything, so a visible control always does the same thing.\n */\nexport function useHotkey(\n  chords: readonly string[],\n  handler: (event: KeyboardEvent) => void,\n  { ifFree = false, enabled = true }: HotkeyOptions = {},\n): void {\n  const scope = useContext(HotkeyScopeContext);\n  const handlerRef = useRef(handler);\n  const activeRef = useRef(scope.active);\n  useEffect(() => {\n    handlerRef.current = handler;\n    activeRef.current = scope.active;\n  });\n\n  // Joined rather than passed by identity: callers write the list inline.\n  const signature = chords.join(' ');\n\n  useEffect(() => {\n    if (!enabled || signature === '') return;\n    const parsed = signature.split(' ').map(parseChord);\n    const free = parsed.filter(chord => !isTaken(scope.id, chord.text));\n    if (free.length < parsed.length && !ifFree) {\n      const taken = parsed.find(chord => !free.includes(chord)) as ParsedChord;\n      throw new Error(\n        `${taken.text} is already bound here. A chord does one thing in a scope: unbind the other, or pass \\`ifFree\\` to the default that should yield.`,\n      );\n    }\n    if (free.length === 0) return;\n    const unbind = free.map(chord => bind(scope.id, chord.text));\n\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (!activeRef.current) return;\n      if (!free.some(chord => matches(event, chord))) return;\n      event.preventDefault();\n      handlerRef.current(event);\n    };\n    document.addEventListener('keydown', onKeyDown);\n    return () => {\n      document.removeEventListener('keydown', onKeyDown);\n      for (const release of unbind) release();\n    };\n  }, [signature, scope.id, ifFree, enabled]);\n}\n"],"names":["parseChord","createContext","useContext","useEffect","useRef","PAGE_SCOPE","id","active","HotkeyScopeContext","HotkeyScopeProvider","Provider","bound","Map","holds","scope","chord","get","has","isTaken","values","some","chords","bind","Set","set","add","delete","resetHotkeysForTesting","clear","matches","event","key","toLowerCase","metaKey","ctrlKey","shiftKey","shift","altKey","alt","useHotkey","handler","ifFree","enabled","handlerRef","activeRef","current","signature","join","parsed","split","map","free","filter","text","length","taken","find","includes","Error","unbind","onKeyDown","preventDefault","document","addEventListener","removeEventListener","release"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entifix/react-controls",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Entity-agnostic React UI — table, form, filters, wizard, command palette — rendered from entity metadata, plus layout primitives.",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,7 @@
     "@headlessui/react": "^2.2.10",
     "class-variance-authority": "^0.7.1",
     "idb": "^8.0.4",
-    "@entifix/core": "0.19.0"
+    "@entifix/core": "0.20.1"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -55,8 +55,8 @@
     "react": "19.3.1",
     "react-i18next": "17.1.10",
     "storybook": "^10.6.5",
-    "@entifix/i18n": "0.19.0",
-    "@entifix/style": "0.19.0"
+    "@entifix/i18n": "0.20.1",
+    "@entifix/style": "0.20.1"
   },
   "nx": {
     "tags": [
@@ -111,7 +111,7 @@
     "i18next": ">=26 <27",
     "react": ">=19 <20",
     "react-i18next": ">=17 <18",
-    "@entifix/i18n": "0.19.0"
+    "@entifix/i18n": "0.20.1"
   },
   "peerDependenciesMeta": {
     "@entifix/i18n": {

package/dist/ui/molecules/split-button/index.d.ts

@@ -1,2 +0,0 @@
-export * from './split-button.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/ui/molecules/split-button/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ui/molecules/split-button/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/ui/molecules/split-button/index.js

@@ -1,3 +0,0 @@
-export * from './split-button.js';
-
-//# sourceMappingURL=index.js.map

package/dist/ui/molecules/split-button/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../src/ui/molecules/split-button/index.ts"],"sourcesContent":["export * from './split-button.js';\n"],"names":[],"mappings":"AAAA,cAAc,oBAAoB"}

package/dist/ui/molecules/split-button/split-button.d.ts

@@ -1,21 +0,0 @@
-import type { ReactNode } from 'react';
-/**
- * One main action, and a menu of the related ones beside it: `[Download │ ▾]`.
- *
- * The caller renders the main action — a link or a button, styled as the
- * primary button — so it stays in the static HTML and keeps its own
- * attributes; without `children` it stands alone, as before scripting runs.
- * The menu is a `NavMenu`, so it opens with scripting off and the page's own
- * menu handling closes it. Parts carry `data-slot` (`split-button`, and the
- * menu's own).
- */
-export declare function SplitButton({ primary, menuLabel, children, className, }: {
-    /** The main action, its corners squared on the side the menu joins. */
-    primary: ReactNode;
-    /** The accessible name of the ▾ trigger. */
-    menuLabel: string;
-    /** The menu's entries; none, and the main action stands alone. */
-    children?: ReactNode;
-    className?: string;
-}): import("react").JSX.Element;
-//# sourceMappingURL=split-button.d.ts.map

package/dist/ui/molecules/split-button/split-button.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"split-button.d.ts","sourceRoot":"","sources":["../../../../src/ui/molecules/split-button/split-button.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAYvC;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,SAAS,EACT,QAAQ,EACR,SAAS,GACV,EAAE;IACD,uEAAuE;IACvE,OAAO,EAAE,SAAS,CAAC;IACnB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,+BAuBA"}

package/dist/ui/molecules/split-button/split-button.js

@@ -1,35 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { button } from '../../atoms/button/button-recipe.js';
-import { cn } from '../../utils/cn.js';
-import { NavMenu } from '../nav-menu/nav-menu.js';
-/** The ▾ segment: the primary button's look, joined to the action before it. */ const TRIGGER = cn(button({
-    variant: 'primary',
-    size: 'sm'
-}), 'h-auto cursor-pointer list-none self-stretch rounded-l-none border-l border-l-[color-mix(in_srgb,var(--color-primary-content)_25%,transparent)] px-2xs select-none [&_[data-slot=nav-menu-chevron]]:text-current [&::-webkit-details-marker]:hidden');
-/**
- * One main action, and a menu of the related ones beside it: `[Download │ ▾]`.
- *
- * The caller renders the main action — a link or a button, styled as the
- * primary button — so it stays in the static HTML and keeps its own
- * attributes; without `children` it stands alone, as before scripting runs.
- * The menu is a `NavMenu`, so it opens with scripting off and the page's own
- * menu handling closes it. Parts carry `data-slot` (`split-button`, and the
- * menu's own).
- */ export function SplitButton({ primary, menuLabel, children, className }) {
-    return /*#__PURE__*/ _jsxs("div", {
-        "data-slot": "split-button",
-        className: cn('inline-flex items-stretch', children !== undefined && '[&>:first-child]:rounded-r-none', className),
-        children: [
-            primary,
-            children !== undefined && /*#__PURE__*/ _jsx(NavMenu, {
-                label: menuLabel,
-                icon: null,
-                className: "flex",
-                triggerClassName: TRIGGER,
-                children: children
-            })
-        ]
-    });
-}
-
-//# sourceMappingURL=split-button.js.map

package/dist/ui/molecules/split-button/split-button.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../src/ui/molecules/split-button/split-button.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\n\nimport { button } from '../../atoms/button/button-recipe.js';\nimport { cn } from '../../utils/cn.js';\nimport { NavMenu } from '../nav-menu/nav-menu.js';\n\n/** The ▾ segment: the primary button's look, joined to the action before it. */\nconst TRIGGER = cn(\n  button({ variant: 'primary', size: 'sm' }),\n  'h-auto cursor-pointer list-none self-stretch rounded-l-none border-l border-l-[color-mix(in_srgb,var(--color-primary-content)_25%,transparent)] px-2xs select-none [&_[data-slot=nav-menu-chevron]]:text-current [&::-webkit-details-marker]:hidden',\n);\n\n/**\n * One main action, and a menu of the related ones beside it: `[Download │ ▾]`.\n *\n * The caller renders the main action — a link or a button, styled as the\n * primary button — so it stays in the static HTML and keeps its own\n * attributes; without `children` it stands alone, as before scripting runs.\n * The menu is a `NavMenu`, so it opens with scripting off and the page's own\n * menu handling closes it. Parts carry `data-slot` (`split-button`, and the\n * menu's own).\n */\nexport function SplitButton({\n  primary,\n  menuLabel,\n  children,\n  className,\n}: {\n  /** The main action, its corners squared on the side the menu joins. */\n  primary: ReactNode;\n  /** The accessible name of the ▾ trigger. */\n  menuLabel: string;\n  /** The menu's entries; none, and the main action stands alone. */\n  children?: ReactNode;\n  className?: string;\n}) {\n  return (\n    <div\n      data-slot=\"split-button\"\n      className={cn(\n        'inline-flex items-stretch',\n        children !== undefined && '[&>:first-child]:rounded-r-none',\n        className,\n      )}\n    >\n      {primary}\n      {children !== undefined && (\n        <NavMenu\n          label={menuLabel}\n          icon={null}\n          className=\"flex\"\n          triggerClassName={TRIGGER}\n        >\n          {children}\n        </NavMenu>\n      )}\n    </div>\n  );\n}\n"],"names":["button","cn","NavMenu","TRIGGER","variant","size","SplitButton","primary","menuLabel","children","className","div","data-slot","undefined","label","icon","triggerClassName"],"mappings":";AAEA,SAASA,MAAM,QAAQ,sCAAsC;AAC7D,SAASC,EAAE,QAAQ,oBAAoB;AACvC,SAASC,OAAO,QAAQ,0BAA0B;AAElD,8EAA8E,GAC9E,MAAMC,UAAUF,GACdD,OAAO;IAAEI,SAAS;IAAWC,MAAM;AAAK,IACxC;AAGF;;;;;;;;;CASC,GACD,OAAO,SAASC,YAAY,EAC1BC,OAAO,EACPC,SAAS,EACTC,QAAQ,EACRC,SAAS,EASV;IACC,qBACE,MAACC;QACCC,aAAU;QACVF,WAAWT,GACT,6BACAQ,aAAaI,aAAa,mCAC1BH;;YAGDH;YACAE,aAAaI,2BACZ,KAACX;gBACCY,OAAON;gBACPO,MAAM;gBACNL,WAAU;gBACVM,kBAAkBb;0BAEjBM;;;;AAKX"}