@cube-dev/ui-kit 0.185.3 → 0.186.1

package/dist/utils/react/mergeProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { mergeIds } from "./useId.js";
 import { mergeStyles } from "@tenphi/tasty";

package/dist/utils/react/nullableValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 //#region src/utils/react/nullableValue.ts
 function castNullableStringValue(props) {
 	return castNullableField(props, ["value", "defaultValue"], "string", (v) => String(v));

package/dist/utils/react/programmaticFocus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 //#region src/utils/react/programmaticFocus.ts
 /**
 * Telling focus the user moved from focus a component moved for them.

package/dist/utils/react/resolveIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 //#region src/utils/react/resolveIcon.ts
 /**
 * Resolves a dynamic icon prop to its content and slot state.

package/dist/utils/react/sharedStore.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { isDevEnv } from "../is-dev-env.js";
 import { c } from "react-compiler-runtime";

package/dist/utils/react/useBufferedValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useCallback, useRef, useState } from "react";
 

package/dist/utils/react/useCombinedRefs.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { c } from "react-compiler-runtime";
 import { useEffect, useRef } from "react";
 

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { c } from "react-compiler-runtime";
 import { useEffect } from "react";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { c } from "react-compiler-runtime";
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { c } from "react-compiler-runtime";
 import { useEffect, useRef, useState } from "react";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { c } from "react-compiler-runtime";
 import { useEffect, useState } from "react";
 

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { c } from "react-compiler-runtime";
 

package/dist/utils/react/useKeySymbols.js.map

@@ -1 +1 @@
-{"version":3,"file":"useKeySymbols.js","names":["useMemo","useIsDarwin","COMMON","Record","esc","escape","enter","return","space","backspace","delete","up","arrowup","down","arrowdown","left","arrowleft","right","arrowright","MAC","mod","meta","cmd","command","ctrl","control","alt","option","shift","PC","win","windows","useKeySymbols","combo","$","_c","isDarwin","modifiers","t0","t1","alternative","split","map","part","key","trim","toUpperCase","_temp","filter","Boolean","raw","toLowerCase"],"sources":["../../../src/utils/react/useKeySymbols.ts"],"sourcesContent":["import { useMemo } from 'react';\n\nimport { useIsDarwin } from './useIsDarwin';\n\n/* symbols that are identical on every OS */\nconst COMMON: Record<string, string> = {\n  esc: 'Esc',\n  escape: 'Esc',\n  enter: '⏎',\n  return: '⏎',\n  space: '␣',\n  backspace: '⌫',\n  delete: '⌦',\n  up: '↑',\n  arrowup: '↑',\n  down: '↓',\n  arrowdown: '↓',\n  left: '←',\n  arrowleft: '←',\n  right: '→',\n  arrowright: '→',\n};\n\n/* modifiers for macOS / iOS */\nconst MAC: Record<string, string> = {\n  mod: '⌘',\n  meta: '⌘',\n  cmd: '⌘',\n  command: '⌘',\n  ctrl: '⌃',\n  control: '⌃',\n  alt: '⌥',\n  option: '⌥',\n  shift: '⇧',\n};\n\n/* modifiers for Windows / Linux */\nconst PC: Record<string, string> = {\n  mod: 'Ctrl',\n  ctrl: 'Ctrl',\n  control: 'Ctrl',\n  meta: 'Win',\n  win: 'Win',\n  windows: 'Win',\n  cmd: 'Win',\n  command: 'Win',\n  alt: '⎇',\n  option: '⎇',\n  shift: '⇧',\n};\n\n/**\n * useKeySymbols\n * -------------\n * Turns an author string such as\n *   \"mod+k, ctrl+k\"\n * into\n *   [[\"⌘\", \"K\"], [\"Ctrl\", \"K\"]]\n */\nexport function useKeySymbols(combo: string): string[][] {\n  const isDarwin = useIsDarwin(); // ⌘ by default during SSR\n  const modifiers = isDarwin ? MAC : PC;\n\n  return useMemo(() => {\n    /** split on commas, trim each alternative */\n    return combo\n      .split(',')\n      .map((raw) => raw.trim().toLowerCase())\n      .filter(Boolean) // drop empty fragments\n      .map((alternative) =>\n        alternative.split('+').map((part) => {\n          const key = part.trim();\n          return (\n            modifiers[key] ?? // platform-specific modifier\n            COMMON[key] ?? // shared glyphs\n            part.toUpperCase() // plain key\n          );\n        }),\n      );\n  }, [combo, modifiers]);\n}\n"],"mappings":";;;;;AAKA,MAAME,SAAiC;CACrCE,KAAK;CACLC,QAAQ;CACRC,OAAO;CACPC,QAAQ;CACRC,OAAO;CACPC,WAAW;CACXC,QAAQ;CACRC,IAAI;CACJC,SAAS;CACTC,MAAM;CACNC,WAAW;CACXC,MAAM;CACNC,WAAW;CACXC,OAAO;CACPC,YAAY;CACb;AAGD,MAAMC,MAA8B;CAClCC,KAAK;CACLC,MAAM;CACNC,KAAK;CACLC,SAAS;CACTC,MAAM;CACNC,SAAS;CACTC,KAAK;CACLC,QAAQ;CACRC,OAAO;CACR;AAGD,MAAMC,KAA6B;CACjCT,KAAK;CACLI,MAAM;CACNC,SAAS;CACTJ,MAAM;CACNS,KAAK;CACLC,SAAS;CACTT,KAAK;CACLC,SAAS;CACTG,KAAK;CACLC,QAAQ;CACRC,OAAO;CACR;;;;;;;;;AAUD,SAAOI,cAAAC,OAAA;CAAA,MAAAC,IAAAC,EAAA,EAAA;CAEL,MAAAE,YADiBpC,aAAa,GACZkB,MAAAU;CAAoB,IAAAS;AAAA,KAAAJ,EAAA,OAAAD,SAAAC,EAAA,OAAAG,WAAA;EAAA,IAAAE;AAAA,MAAAL,EAAA,OAAAG,WAAA;AAQ7BE,SAAAC,gBACHA,YAAWC,MAAO,IAAI,CAAAC,KAAKC,SAAA;IACzB,MAAAC,MAAYD,KAAIE,MAAO;AAAC,WAEtBR,UAAUO,QACV1C,OAAO0C,QACPD,KAAIG,aAAc;KAEpB;AAAAZ,KAAA,KAAAG;AAAAH,KAAA,KAAAK;QAAAA,MAAAL,EAAA;AAZCI,OAAAL,MAAKQ,MACH,IAAI,CAAAC,IACNK,MAAkC,CAAAC,OAC/BC,QAAQ,CAAAP,IACXH,GASJ;AAAAL,IAAA,KAAAD;AAAAC,IAAA,KAAAG;AAAAH,IAAA,KAAAI;OAAAA,MAAAJ,EAAA;AAAA,QAbHI;;AANG,SAAAS,MAAAG,KAAA;AAAA,QAQaA,IAAGL,MAAO,CAAAM,aAAc"}
+{"version":3,"file":"useKeySymbols.js","names":["useIsDarwin","COMMON","Record","esc","escape","enter","return","space","backspace","delete","up","arrowup","down","arrowdown","left","arrowleft","right","arrowright","MAC","mod","meta","cmd","command","ctrl","control","alt","option","shift","PC","win","windows","useKeySymbols","combo","$","_c","isDarwin","modifiers","t0","t1","alternative","split","map","part","key","trim","toUpperCase","_temp","filter","Boolean","raw","toLowerCase"],"sources":["../../../src/utils/react/useKeySymbols.ts"],"sourcesContent":["import { useIsDarwin } from './useIsDarwin';\n\n/* symbols that are identical on every OS */\nconst COMMON: Record<string, string> = {\n  esc: 'Esc',\n  escape: 'Esc',\n  enter: '⏎',\n  return: '⏎',\n  space: '␣',\n  backspace: '⌫',\n  delete: '⌦',\n  up: '↑',\n  arrowup: '↑',\n  down: '↓',\n  arrowdown: '↓',\n  left: '←',\n  arrowleft: '←',\n  right: '→',\n  arrowright: '→',\n};\n\n/* modifiers for macOS / iOS */\nconst MAC: Record<string, string> = {\n  mod: '⌘',\n  meta: '⌘',\n  cmd: '⌘',\n  command: '⌘',\n  ctrl: '⌃',\n  control: '⌃',\n  alt: '⌥',\n  option: '⌥',\n  shift: '⇧',\n};\n\n/* modifiers for Windows / Linux */\nconst PC: Record<string, string> = {\n  mod: 'Ctrl',\n  ctrl: 'Ctrl',\n  control: 'Ctrl',\n  meta: 'Win',\n  win: 'Win',\n  windows: 'Win',\n  cmd: 'Win',\n  command: 'Win',\n  alt: '⎇',\n  option: '⎇',\n  shift: '⇧',\n};\n\n/**\n * useKeySymbols\n * -------------\n * Turns an author string such as\n *   \"mod+k, ctrl+k\"\n * into\n *   [[\"⌘\", \"K\"], [\"Ctrl\", \"K\"]]\n */\nexport function useKeySymbols(combo: string): string[][] {\n  const isDarwin = useIsDarwin(); // ⌘ by default during SSR\n  const modifiers = isDarwin ? MAC : PC;\n\n  /** split on commas, trim each alternative */\n  return combo\n    .split(',')\n    .map((raw) => raw.trim().toLowerCase())\n    .filter(Boolean) // drop empty fragments\n    .map((alternative) =>\n      alternative.split('+').map((part) => {\n        const key = part.trim();\n        return (\n          modifiers[key] ?? // platform-specific modifier\n          COMMON[key] ?? // shared glyphs\n          part.toUpperCase() // plain key\n        );\n      }),\n    );\n}\n"],"mappings":";;;;;AAGA,MAAMC,SAAiC;CACrCE,KAAK;CACLC,QAAQ;CACRC,OAAO;CACPC,QAAQ;CACRC,OAAO;CACPC,WAAW;CACXC,QAAQ;CACRC,IAAI;CACJC,SAAS;CACTC,MAAM;CACNC,WAAW;CACXC,MAAM;CACNC,WAAW;CACXC,OAAO;CACPC,YAAY;CACb;AAGD,MAAMC,MAA8B;CAClCC,KAAK;CACLC,MAAM;CACNC,KAAK;CACLC,SAAS;CACTC,MAAM;CACNC,SAAS;CACTC,KAAK;CACLC,QAAQ;CACRC,OAAO;CACR;AAGD,MAAMC,KAA6B;CACjCT,KAAK;CACLI,MAAM;CACNC,SAAS;CACTJ,MAAM;CACNS,KAAK;CACLC,SAAS;CACTT,KAAK;CACLC,SAAS;CACTG,KAAK;CACLC,QAAQ;CACRC,OAAO;CACR;;;;;;;;;AAUD,SAAOI,cAAAC,OAAA;CAAA,MAAAC,IAAAC,EAAA,EAAA;CAEL,MAAAE,YADiBpC,aAAa,GACZkB,MAAAU;CAAoB,IAAAS;AAAA,KAAAJ,EAAA,OAAAD,SAAAC,EAAA,OAAAG,WAAA;EAAA,IAAAE;AAAA,MAAAL,EAAA,OAAAG,WAAA;AAO/BE,SAAAC,gBACHA,YAAWC,MAAO,IAAI,CAAAC,KAAKC,SAAA;IACzB,MAAAC,MAAYD,KAAIE,MAAO;AAAC,WAEtBR,UAAUO,QACV1C,OAAO0C,QACPD,KAAIG,aAAc;KAEpB;AAAAZ,KAAA,KAAAG;AAAAH,KAAA,KAAAK;QAAAA,MAAAL,EAAA;AAZCI,OAAAL,MAAKQ,MACH,IAAI,CAAAC,IACNK,MAAkC,CAAAC,OAC/BC,QAAQ,CAAAP,IACXH,GASJ;AAAAL,IAAA,KAAAD;AAAAC,IAAA,KAAAG;AAAAH,IAAA,KAAAI;OAAAA,MAAAJ,EAAA;AAAA,QAbII;;AALF,SAAAS,MAAAG,KAAA;AAAA,QAOWA,IAAGL,MAAO,CAAAM,aAAc"}

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { c } from "react-compiler-runtime";
 import { useSyncExternalStore } from "react";

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/useOverlayEscapeGuard.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { c } from "react-compiler-runtime";
 

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { c } from "react-compiler-runtime";
 import { useContext, useEffect, useRef } from "react";

package/dist/utils/react/usePopoverSync.js.map

@@ -1 +1 @@
-{"version":3,"file":"usePopoverSync.js","names":["RefObject","useCallback","useContext","useEffect","useRef","EventBusContext","useEventBus","UsePopoverSyncOptions","menuId","isOpen","onClose","enabled","triggerRef","HTMLElement","containerRef","dismissOnInnerButtonPress","closeOnPeerOpen","PopoverOpenPayload","triggerEl","Element","PopoverDismissAncestorPayload","from","PopoverRegistryEntry","getContainerEl","getTriggerEl","openPopovers","Map","findOwningPopover","target","entry","contains","isLogicalDescendantOf","ancestorMenuId","ancestorContainer","cur","visited","Set","owner","id","has","add","usePopoverSync","t0","$","_c","t1","t2","t3","undefined","emit","on","isOpenRef","t4","t5","current","onCloseRef","t6","t7","containerRefRef","t8","t9","triggerRefRef","t10","t11","t12","t13","offOpen","data","container","offDismiss","data_0","container_0","wasOpenRef","t14","t15","delete","set","t16","t17","useDismissParentPopover","bus"],"sources":["../../../src/utils/react/usePopoverSync.ts"],"sourcesContent":["import { RefObject, useCallback, useContext, useEffect, useRef } from 'react';\n\nimport { EventBusContext, useEventBus } from './useEventBus';\n\nexport interface UsePopoverSyncOptions {\n  /** Stable identifier for this popover instance (typically a generateRandomId() memo). */\n  menuId: string;\n  /** Current open state of this popover. */\n  isOpen: boolean;\n  /** Called when another popover opens while this one is open. */\n  onClose: () => void;\n  /**\n   * When `false`, this popover does not participate in the sync (no listening,\n   * no emitting). Useful for \"dummy\" triggers that proxy a real one (see\n   * `MenuTrigger`'s `isDummy`). Defaults to `true`.\n   */\n  enabled?: boolean;\n  /**\n   * Ref to the popover's trigger element. When provided, the element is\n   * included in the `popover:open` emit payload so peers can detect whether\n   * the new opener is nested inside their own overlay (and skip closing in\n   * that case). Optional — omitting it preserves the legacy \"always close on\n   * peer open\" behaviour.\n   */\n  triggerRef?: RefObject<HTMLElement | null>;\n  /**\n   * Ref to the overlay/container element that hosts this popover's content.\n   * When provided, the listener performs a DOM `contains()` check on incoming\n   * peer triggers: peers whose trigger lives inside this container are\n   * considered nested children and do NOT close us.\n   */\n  containerRef?: RefObject<HTMLElement | null>;\n  /**\n   * Whether this overlay closes when a Button/ItemButton inside its container\n   * is pressed. Defaults to `true` (popover semantics — popovers are transient\n   * surfaces and any action inside them should dismiss them). Set to `false`\n   * for modals/trays/fullscreen dialogs — buttons inside a Dialog should not\n   * auto-close it. Requires `containerRef` to be set; without it the listener\n   * has no way to determine whether the dispatching button is \"inside\" this\n   * overlay and is effectively a no-op.\n   */\n  dismissOnInnerButtonPress?: boolean;\n  /**\n   * Whether this overlay closes when a peer popover opens. Defaults to `true`\n   * (popover semantics — only one popover open at a time). Set to `false` for\n   * modals/trays/fullscreen dialogs so a peer popover opening cannot bypass\n   * the dialog's own `isDismissable` / `onClose` handling and yank it shut.\n   *\n   * The host still EMITS `popover:open` regardless of this flag, so opening a\n   * modal/tray correctly dismisses any peer popover that was open before.\n   */\n  closeOnPeerOpen?: boolean;\n}\n\ninterface PopoverOpenPayload {\n  menuId: string;\n  triggerEl: Element | null;\n}\n\ninterface PopoverDismissAncestorPayload {\n  /** The DOM node of the button that requested the dismiss. */\n  from: Element | null;\n}\n\ninterface PopoverRegistryEntry {\n  getContainerEl: () => Element | null;\n  getTriggerEl: () => Element | null;\n}\n\n/**\n * Module-level registry of currently open popovers. Lets us resolve the\n * LOGICAL parent of an arbitrary element across portal boundaries.\n *\n * Popover content is portaled to a shared root (`document.body` by default —\n * see `Overlay.tsx`), so a grandchild popover's trigger lives inside a\n * sibling portal rather than physically inside its grandparent's container.\n * A naive `container.contains(triggerEl)` check therefore misses the\n * relationship and closes the grandparent — the bug that surfaces with 3+\n * levels of `SubMenuTrigger` nesting.\n *\n * The registry stores closures over the host's refs so reads always see the\n * latest `.current` value without forcing a re-register per render.\n */\nconst openPopovers = new Map<string, PopoverRegistryEntry>();\n\n/**\n * Find the open popover whose container directly contains `target`. Returns\n * `null` for elements that live outside every registered popover (e.g. a\n * top-level trigger button rendered next to its overlay root).\n */\nfunction findOwningPopover(\n  target: Element | null,\n): [string, PopoverRegistryEntry] | null {\n  if (!target) return null;\n  for (const entry of openPopovers) {\n    if (entry[1].getContainerEl()?.contains(target)) {\n      return entry;\n    }\n  }\n  return null;\n}\n\n/**\n * Returns `true` when `target` is nested inside the overlay identified by\n * `ancestorMenuId` — either as a direct DOM descendant of `ancestorContainer`\n * or as a descendant of a chain of popovers whose triggers eventually land\n * inside it. Used by `popover:open` peers to avoid closing themselves when a\n * grand-child overlay opens through a portal.\n */\nfunction isLogicalDescendantOf(\n  target: Element | null,\n  ancestorMenuId: string,\n  ancestorContainer: Element | null,\n): boolean {\n  if (ancestorContainer && target && ancestorContainer.contains(target)) {\n    return true;\n  }\n  let cur: Element | null = target;\n  const visited = new Set<string>();\n  while (cur) {\n    const owner = findOwningPopover(cur);\n    if (!owner) return false;\n    const [id, entry] = owner;\n    if (visited.has(id)) return false;\n    visited.add(id);\n    if (id === ancestorMenuId) return true;\n    cur = entry.getTriggerEl();\n  }\n  return false;\n}\n\n/**\n * Coordinates the \"only one popover open at a time\" invariant via the EventBus.\n *\n * - When `isOpen` flips `false -> true`, emits `popover:open` once.\n * - While open, listens for peers' `popover:open` events and calls `onClose`.\n *\n * Implementation notes (ALL of these matter — losing any one re-introduces a\n * race that surfaces only under rapid trigger switching, which is hard to\n * reproduce in tests):\n *\n * 1. `isOpen` and `onClose` are read through refs inside the listener, so the\n *    subscription effect's dep array does NOT include `isOpen`/`onClose`. This\n *    keeps the listener identity stable across open/close transitions and\n *    avoids the unsubscribe-emit-resubscribe window where an emit can be\n *    delivered to a stale listener (or no listener).\n * 2. The emit fires only on the `false -> true` transition, gated by\n *    `wasOpenRef`. A re-render where `isOpen` is still `true` must NOT\n *    re-emit, otherwise it could re-trigger listeners on peers that just\n *    opened in the same render flush.\n * 3. The `enabled` flag short-circuits both effects symmetrically. When it\n *    flips off, `wasOpenRef` is reset so re-enabling later still emits if\n *    `isOpen` is true at that moment.\n */\nexport function usePopoverSync({\n  menuId,\n  isOpen,\n  onClose,\n  enabled = true,\n  triggerRef,\n  containerRef,\n  dismissOnInnerButtonPress = true,\n  closeOnPeerOpen = true,\n}: UsePopoverSyncOptions): void {\n  const { emit, on } = useEventBus();\n\n  const isOpenRef = useRef(isOpen);\n  useEffect(() => {\n    isOpenRef.current = isOpen;\n  }, [isOpen]);\n\n  const onCloseRef = useRef(onClose);\n  useEffect(() => {\n    onCloseRef.current = onClose;\n  }, [onClose]);\n\n  // Track the latest containerRef via a stable ref-of-refs so the listener\n  // never resubscribes when callers pass freshly-created ref wrappers across\n  // renders. Same pattern as `onCloseRef` above — without this the listener's\n  // effect would churn for any caller that doesn't memoize its refs.\n  const containerRefRef = useRef(containerRef);\n  useEffect(() => {\n    containerRefRef.current = containerRef;\n  }, [containerRef]);\n\n  const triggerRefRef = useRef(triggerRef);\n  useEffect(() => {\n    triggerRefRef.current = triggerRef;\n  }, [triggerRef]);\n\n  useEffect(() => {\n    if (!enabled) return;\n\n    // `popover:open` listener — gated on `closeOnPeerOpen`. Modals/trays opt\n    // out so a peer popover opening cannot bypass the dialog's\n    // `isDismissable` / `onClose` handling and call `state.close()` directly.\n    // Note: the EMIT side (lower in this hook) still fires regardless, so\n    // opening a modal still correctly dismisses peer popovers.\n    const offOpen = closeOnPeerOpen\n      ? on('popover:open', (data: PopoverOpenPayload) => {\n          if (data.menuId === menuId || !isOpenRef.current) return;\n          const container = containerRefRef.current?.current ?? null;\n          // Nested-popover guard: stay open when the opening peer's trigger is\n          // a LOGICAL descendant of our overlay. Direct DOM containment only\n          // covers the first level — for grand-child popovers the trigger lives\n          // in a sibling portal, so we walk the registered popover chain back\n          // up via each parent's trigger element. Without this, opening a\n          // third-level `SubMenuTrigger` would close every ancestor menu.\n          if (isLogicalDescendantOf(data.triggerEl, menuId, container)) return;\n          onCloseRef.current();\n        })\n      : null;\n\n    // `popover:dismiss-ancestor` is emitted by `Button` / `ItemButton` (and any\n    // consumer using `useDismissParentPopover`) after their `onPress` runs.\n    // Only popover-type overlays subscribe; modals/trays opt out via\n    // `dismissOnInnerButtonPress: false` so a Button inside a Dialog content\n    // does NOT auto-close the Dialog.\n    const offDismiss = dismissOnInnerButtonPress\n      ? on(\n          'popover:dismiss-ancestor',\n          (data: PopoverDismissAncestorPayload) => {\n            if (!isOpenRef.current) return;\n            const container = containerRefRef.current?.current;\n            const from = data?.from;\n            // Require both a container and an originating element so we can do\n            // the contains-check. Hosts without `containerRef` (e.g.\n            // `use-anchored-menu`, `use-context-menu`) are silently no-op.\n            if (!container || !from) return;\n            if (container.contains(from)) onCloseRef.current();\n          },\n        )\n      : null;\n\n    return () => {\n      offOpen?.();\n      offDismiss?.();\n    };\n  }, [on, menuId, enabled, dismissOnInnerButtonPress, closeOnPeerOpen]);\n\n  const wasOpenRef = useRef(false);\n  useEffect(() => {\n    if (!enabled) {\n      if (wasOpenRef.current) {\n        openPopovers.delete(menuId);\n      }\n      wasOpenRef.current = false;\n      return;\n    }\n    if (isOpen && !wasOpenRef.current) {\n      wasOpenRef.current = true;\n      // Register BEFORE emitting so peers' listeners (deferred via the\n      // bus's `setTimeout(0)`) can already see us in the registry when\n      // they walk the logical chain.\n      openPopovers.set(menuId, {\n        getContainerEl: () => containerRefRef.current?.current ?? null,\n        getTriggerEl: () => triggerRefRef.current?.current ?? null,\n      });\n      emit<PopoverOpenPayload>('popover:open', {\n        menuId,\n        triggerEl: triggerRefRef.current?.current ?? null,\n      });\n    } else if (!isOpen && wasOpenRef.current) {\n      wasOpenRef.current = false;\n      openPopovers.delete(menuId);\n    }\n  }, [isOpen, emit, menuId, enabled]);\n\n  // Final cleanup on unmount: covers the case where a host unmounts while\n  // still flagged open (e.g. a parent unmount tears down a child popover\n  // before its close transition runs).\n  useEffect(() => {\n    return () => {\n      openPopovers.delete(menuId);\n    };\n  }, [menuId]);\n}\n\n/**\n * Hook that returns a dispatcher to close the popover that contains a given\n * DOM element. Used by `Button` / `ItemButton` to implement the default\n * \"press inside a popover closes the popover\" behaviour. Custom (non-Cube)\n * interactive controls can call this directly:\n *\n * ```tsx\n * const dismiss = useDismissParentPopover();\n * <MyCustomPressable onPress={(e) => { doThing(); dismiss(e.currentTarget); }} />\n * ```\n *\n * The actual dismiss is dispatched through the EventBus, which defers via\n * `setTimeout(0)` — so the user's synchronous handler (and any React state\n * updates it triggers) flushes BEFORE the popover closes. This is critical\n * for the \"open a hoisted modal from a popover footer\" case: the modal\n * mounts first, then the popover closes.\n *\n * Only popover-type containers (those that pass `dismissOnInnerButtonPress`\n * as `true`, the default) react to the event. Modal/tray/fullscreen Dialog\n * containers explicitly opt out so a Button inside their content does not\n * auto-close them.\n *\n * When called outside an `EventBusProvider` (e.g. in unit tests that render\n * a Button without wrapping in `<Root>`), the returned function is a no-op —\n * the dismiss flow gracefully degrades rather than throwing.\n */\nexport function useDismissParentPopover() {\n  // Read context defensively: `Button` / `ItemButton` use this hook\n  // unconditionally, but tests (and standalone usages outside `<Root>`) may\n  // mount them without an `EventBusProvider`. A throw would crash every\n  // Button render in those cases.\n  const bus = useContext(EventBusContext);\n  const emit = bus?.emit;\n  return useCallback(\n    (from: Element | null) => {\n      if (!from || !emit) return;\n      emit<PopoverDismissAncestorPayload>('popover:dismiss-ancestor', { from });\n    },\n    [emit],\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"usePopoverSync.js","names":["RefObject","useContext","useEffect","useRef","EventBusContext","useEventBus","UsePopoverSyncOptions","menuId","isOpen","onClose","enabled","triggerRef","HTMLElement","containerRef","dismissOnInnerButtonPress","closeOnPeerOpen","PopoverOpenPayload","triggerEl","Element","PopoverDismissAncestorPayload","from","PopoverRegistryEntry","getContainerEl","getTriggerEl","openPopovers","Map","findOwningPopover","target","entry","contains","isLogicalDescendantOf","ancestorMenuId","ancestorContainer","cur","visited","Set","owner","id","has","add","usePopoverSync","t0","$","_c","t1","t2","t3","undefined","emit","on","isOpenRef","t4","t5","current","onCloseRef","t6","t7","containerRefRef","t8","t9","triggerRefRef","t10","t11","t12","t13","offOpen","data","container","offDismiss","data_0","container_0","wasOpenRef","t14","t15","delete","set","t16","t17","useDismissParentPopover","bus"],"sources":["../../../src/utils/react/usePopoverSync.ts"],"sourcesContent":["import { RefObject, useContext, useEffect, useRef } from 'react';\n\nimport { EventBusContext, useEventBus } from './useEventBus';\n\nexport interface UsePopoverSyncOptions {\n  /** Stable identifier for this popover instance (typically a generateRandomId() memo). */\n  menuId: string;\n  /** Current open state of this popover. */\n  isOpen: boolean;\n  /** Called when another popover opens while this one is open. */\n  onClose: () => void;\n  /**\n   * When `false`, this popover does not participate in the sync (no listening,\n   * no emitting). Useful for \"dummy\" triggers that proxy a real one (see\n   * `MenuTrigger`'s `isDummy`). Defaults to `true`.\n   */\n  enabled?: boolean;\n  /**\n   * Ref to the popover's trigger element. When provided, the element is\n   * included in the `popover:open` emit payload so peers can detect whether\n   * the new opener is nested inside their own overlay (and skip closing in\n   * that case). Optional — omitting it preserves the legacy \"always close on\n   * peer open\" behaviour.\n   */\n  triggerRef?: RefObject<HTMLElement | null>;\n  /**\n   * Ref to the overlay/container element that hosts this popover's content.\n   * When provided, the listener performs a DOM `contains()` check on incoming\n   * peer triggers: peers whose trigger lives inside this container are\n   * considered nested children and do NOT close us.\n   */\n  containerRef?: RefObject<HTMLElement | null>;\n  /**\n   * Whether this overlay closes when a Button/ItemButton inside its container\n   * is pressed. Defaults to `true` (popover semantics — popovers are transient\n   * surfaces and any action inside them should dismiss them). Set to `false`\n   * for modals/trays/fullscreen dialogs — buttons inside a Dialog should not\n   * auto-close it. Requires `containerRef` to be set; without it the listener\n   * has no way to determine whether the dispatching button is \"inside\" this\n   * overlay and is effectively a no-op.\n   */\n  dismissOnInnerButtonPress?: boolean;\n  /**\n   * Whether this overlay closes when a peer popover opens. Defaults to `true`\n   * (popover semantics — only one popover open at a time). Set to `false` for\n   * modals/trays/fullscreen dialogs so a peer popover opening cannot bypass\n   * the dialog's own `isDismissable` / `onClose` handling and yank it shut.\n   *\n   * The host still EMITS `popover:open` regardless of this flag, so opening a\n   * modal/tray correctly dismisses any peer popover that was open before.\n   */\n  closeOnPeerOpen?: boolean;\n}\n\ninterface PopoverOpenPayload {\n  menuId: string;\n  triggerEl: Element | null;\n}\n\ninterface PopoverDismissAncestorPayload {\n  /** The DOM node of the button that requested the dismiss. */\n  from: Element | null;\n}\n\ninterface PopoverRegistryEntry {\n  getContainerEl: () => Element | null;\n  getTriggerEl: () => Element | null;\n}\n\n/**\n * Module-level registry of currently open popovers. Lets us resolve the\n * LOGICAL parent of an arbitrary element across portal boundaries.\n *\n * Popover content is portaled to a shared root (`document.body` by default —\n * see `Overlay.tsx`), so a grandchild popover's trigger lives inside a\n * sibling portal rather than physically inside its grandparent's container.\n * A naive `container.contains(triggerEl)` check therefore misses the\n * relationship and closes the grandparent — the bug that surfaces with 3+\n * levels of `SubMenuTrigger` nesting.\n *\n * The registry stores closures over the host's refs so reads always see the\n * latest `.current` value without forcing a re-register per render.\n */\nconst openPopovers = new Map<string, PopoverRegistryEntry>();\n\n/**\n * Find the open popover whose container directly contains `target`. Returns\n * `null` for elements that live outside every registered popover (e.g. a\n * top-level trigger button rendered next to its overlay root).\n */\nfunction findOwningPopover(\n  target: Element | null,\n): [string, PopoverRegistryEntry] | null {\n  if (!target) return null;\n  for (const entry of openPopovers) {\n    if (entry[1].getContainerEl()?.contains(target)) {\n      return entry;\n    }\n  }\n  return null;\n}\n\n/**\n * Returns `true` when `target` is nested inside the overlay identified by\n * `ancestorMenuId` — either as a direct DOM descendant of `ancestorContainer`\n * or as a descendant of a chain of popovers whose triggers eventually land\n * inside it. Used by `popover:open` peers to avoid closing themselves when a\n * grand-child overlay opens through a portal.\n */\nfunction isLogicalDescendantOf(\n  target: Element | null,\n  ancestorMenuId: string,\n  ancestorContainer: Element | null,\n): boolean {\n  if (ancestorContainer && target && ancestorContainer.contains(target)) {\n    return true;\n  }\n  let cur: Element | null = target;\n  const visited = new Set<string>();\n  while (cur) {\n    const owner = findOwningPopover(cur);\n    if (!owner) return false;\n    const [id, entry] = owner;\n    if (visited.has(id)) return false;\n    visited.add(id);\n    if (id === ancestorMenuId) return true;\n    cur = entry.getTriggerEl();\n  }\n  return false;\n}\n\n/**\n * Coordinates the \"only one popover open at a time\" invariant via the EventBus.\n *\n * - When `isOpen` flips `false -> true`, emits `popover:open` once.\n * - While open, listens for peers' `popover:open` events and calls `onClose`.\n *\n * Implementation notes (ALL of these matter — losing any one re-introduces a\n * race that surfaces only under rapid trigger switching, which is hard to\n * reproduce in tests):\n *\n * 1. `isOpen` and `onClose` are read through refs inside the listener, so the\n *    subscription effect's dep array does NOT include `isOpen`/`onClose`. This\n *    keeps the listener identity stable across open/close transitions and\n *    avoids the unsubscribe-emit-resubscribe window where an emit can be\n *    delivered to a stale listener (or no listener).\n * 2. The emit fires only on the `false -> true` transition, gated by\n *    `wasOpenRef`. A re-render where `isOpen` is still `true` must NOT\n *    re-emit, otherwise it could re-trigger listeners on peers that just\n *    opened in the same render flush.\n * 3. The `enabled` flag short-circuits both effects symmetrically. When it\n *    flips off, `wasOpenRef` is reset so re-enabling later still emits if\n *    `isOpen` is true at that moment.\n */\nexport function usePopoverSync({\n  menuId,\n  isOpen,\n  onClose,\n  enabled = true,\n  triggerRef,\n  containerRef,\n  dismissOnInnerButtonPress = true,\n  closeOnPeerOpen = true,\n}: UsePopoverSyncOptions): void {\n  const { emit, on } = useEventBus();\n\n  const isOpenRef = useRef(isOpen);\n  useEffect(() => {\n    isOpenRef.current = isOpen;\n  }, [isOpen]);\n\n  const onCloseRef = useRef(onClose);\n  useEffect(() => {\n    onCloseRef.current = onClose;\n  }, [onClose]);\n\n  // Track the latest containerRef via a stable ref-of-refs so the listener\n  // never resubscribes when callers pass freshly-created ref wrappers across\n  // renders. Same pattern as `onCloseRef` above — without this the listener's\n  // effect would churn for any caller that doesn't memoize its refs.\n  const containerRefRef = useRef(containerRef);\n  useEffect(() => {\n    containerRefRef.current = containerRef;\n  }, [containerRef]);\n\n  const triggerRefRef = useRef(triggerRef);\n  useEffect(() => {\n    triggerRefRef.current = triggerRef;\n  }, [triggerRef]);\n\n  useEffect(() => {\n    if (!enabled) return;\n\n    // `popover:open` listener — gated on `closeOnPeerOpen`. Modals/trays opt\n    // out so a peer popover opening cannot bypass the dialog's\n    // `isDismissable` / `onClose` handling and call `state.close()` directly.\n    // Note: the EMIT side (lower in this hook) still fires regardless, so\n    // opening a modal still correctly dismisses peer popovers.\n    const offOpen = closeOnPeerOpen\n      ? on('popover:open', (data: PopoverOpenPayload) => {\n          if (data.menuId === menuId || !isOpenRef.current) return;\n          const container = containerRefRef.current?.current ?? null;\n          // Nested-popover guard: stay open when the opening peer's trigger is\n          // a LOGICAL descendant of our overlay. Direct DOM containment only\n          // covers the first level — for grand-child popovers the trigger lives\n          // in a sibling portal, so we walk the registered popover chain back\n          // up via each parent's trigger element. Without this, opening a\n          // third-level `SubMenuTrigger` would close every ancestor menu.\n          if (isLogicalDescendantOf(data.triggerEl, menuId, container)) return;\n          onCloseRef.current();\n        })\n      : null;\n\n    // `popover:dismiss-ancestor` is emitted by `Button` / `ItemButton` (and any\n    // consumer using `useDismissParentPopover`) after their `onPress` runs.\n    // Only popover-type overlays subscribe; modals/trays opt out via\n    // `dismissOnInnerButtonPress: false` so a Button inside a Dialog content\n    // does NOT auto-close the Dialog.\n    const offDismiss = dismissOnInnerButtonPress\n      ? on(\n          'popover:dismiss-ancestor',\n          (data: PopoverDismissAncestorPayload) => {\n            if (!isOpenRef.current) return;\n            const container = containerRefRef.current?.current;\n            const from = data?.from;\n            // Require both a container and an originating element so we can do\n            // the contains-check. Hosts without `containerRef` (e.g.\n            // `use-anchored-menu`, `use-context-menu`) are silently no-op.\n            if (!container || !from) return;\n            if (container.contains(from)) onCloseRef.current();\n          },\n        )\n      : null;\n\n    return () => {\n      offOpen?.();\n      offDismiss?.();\n    };\n  }, [on, menuId, enabled, dismissOnInnerButtonPress, closeOnPeerOpen]);\n\n  const wasOpenRef = useRef(false);\n  useEffect(() => {\n    if (!enabled) {\n      if (wasOpenRef.current) {\n        openPopovers.delete(menuId);\n      }\n      wasOpenRef.current = false;\n      return;\n    }\n    if (isOpen && !wasOpenRef.current) {\n      wasOpenRef.current = true;\n      // Register BEFORE emitting so peers' listeners (deferred via the\n      // bus's `setTimeout(0)`) can already see us in the registry when\n      // they walk the logical chain.\n      openPopovers.set(menuId, {\n        getContainerEl: () => containerRefRef.current?.current ?? null,\n        getTriggerEl: () => triggerRefRef.current?.current ?? null,\n      });\n      emit<PopoverOpenPayload>('popover:open', {\n        menuId,\n        triggerEl: triggerRefRef.current?.current ?? null,\n      });\n    } else if (!isOpen && wasOpenRef.current) {\n      wasOpenRef.current = false;\n      openPopovers.delete(menuId);\n    }\n  }, [isOpen, emit, menuId, enabled]);\n\n  // Final cleanup on unmount: covers the case where a host unmounts while\n  // still flagged open (e.g. a parent unmount tears down a child popover\n  // before its close transition runs).\n  useEffect(() => {\n    return () => {\n      openPopovers.delete(menuId);\n    };\n  }, [menuId]);\n}\n\n/**\n * Hook that returns a dispatcher to close the popover that contains a given\n * DOM element. Used by `Button` / `ItemButton` to implement the default\n * \"press inside a popover closes the popover\" behaviour. Custom (non-Cube)\n * interactive controls can call this directly:\n *\n * ```tsx\n * const dismiss = useDismissParentPopover();\n * <MyCustomPressable onPress={(e) => { doThing(); dismiss(e.currentTarget); }} />\n * ```\n *\n * The actual dismiss is dispatched through the EventBus, which defers via\n * `setTimeout(0)` — so the user's synchronous handler (and any React state\n * updates it triggers) flushes BEFORE the popover closes. This is critical\n * for the \"open a hoisted modal from a popover footer\" case: the modal\n * mounts first, then the popover closes.\n *\n * Only popover-type containers (those that pass `dismissOnInnerButtonPress`\n * as `true`, the default) react to the event. Modal/tray/fullscreen Dialog\n * containers explicitly opt out so a Button inside their content does not\n * auto-close them.\n *\n * When called outside an `EventBusProvider` (e.g. in unit tests that render\n * a Button without wrapping in `<Root>`), the returned function is a no-op —\n * the dismiss flow gracefully degrades rather than throwing.\n */\nexport function useDismissParentPopover() {\n  // Read context defensively: `Button` / `ItemButton` use this hook\n  // unconditionally, but tests (and standalone usages outside `<Root>`) may\n  // mount them without an `EventBusProvider`. A throw would crash every\n  // Button render in those cases.\n  const bus = useContext(EventBusContext);\n  const emit = bus?.emit;\n  return (from: Element | null) => {\n    if (!from || !emit) return;\n    emit<PopoverDismissAncestorPayload>('popover:dismiss-ancestor', { from });\n  };\n}\n"],"mappings":"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"}

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useScheme.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { useSyncExternalStore } from "react";
 
 //#region src/utils/react/useScheme.ts

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { c } from "react-compiler-runtime";
 import { useEffect, useState } from "react";
 

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { Fragment, isValidElement } from "react";
 
 //#region src/utils/react/wrapNodeIfPlain.ts

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 
 //#region src/utils/warnings.ts

package/dist/version.js

@@ -1,7 +1,7 @@
-/** @license MIT | @cube-dev/ui-kit v0.185.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.185.3";
-const TASTY_VERSION = "3.9.2";
+const VERSION = "0.186.1";
+const TASTY_VERSION = "3.9.3";
 if (typeof window !== "undefined") {
 	const version = VERSION;
 	const tastyVersion = TASTY_VERSION;

package/docs/CreateComponent.md

@@ -446,7 +446,9 @@ For input components that need to integrate with forms, see the [Field documenta
 
 7. **Keep it simple when appropriate**: Not every component needs all features - use what makes sense for your use case
 
-8. **Use named React imports**: Import `useCallback`, `useState`, `forwardRef` etc. directly from `'react'` instead of using `React.useCallback(...)`.
+8. **Use named React imports**: Import `useState`, `useRef`, `forwardRef` etc. directly from `'react'` instead of using `React.useState(...)`.
+
+   **Skip `useMemo` and `useCallback` for performance.** React Compiler memoizes compiled components and hooks at build time, so derived values, `mods` objects, context values and handlers are plain expressions. Keep a manual memo only where identity is part of the contract: a callback ref, an effect dependency, a `useSyncExternalStore` subscription, or a value created once per mount.
 
 9. **Use `useEvent` for stable callbacks**: When a callback doesn't need to trigger re-renders, prefer `useEvent` from `src/_internal/hooks/use-event` for a stable identity that always calls the latest implementation:
 

package/docs/components/fields/TagInput.md

@@ -27,7 +27,7 @@ A multi-value field. The user types a value into a single-line input and commits
 - **`defaultValue`** `string[]` — The initial values in uncontrolled mode
 - **`inputValue`** `string` — The text being typed, in controlled mode
 - **`defaultInputValue`** `string` — The initial text being typed, in uncontrolled mode
-- **`allowsCustomValue`** `boolean` (default: `false`) — Whether typed values that are not among the options are accepted. Only applies when options are given
+- **`allowsCustomValue`** `boolean` (default: `false`) — Whether typed values that are not among the options are accepted. Only applies when options are given. Text that matches an option only in case or accents is then added as typed
 - **`delimiters`** `string[]` (default: `[',']`) — Characters that commit the typed text and split pasted text. Pasted text is also split on line breaks
 - **`validateTag`** `(value: string) => boolean | string | null | undefined` — Checks one value before it becomes a chip. Return `false` or a message to reject it
 - **`normalizeTag`** `(value: string) => string` — Rewrites a typed value before it is checked and added. Return an empty string to drop it
@@ -51,16 +51,16 @@ A multi-value field. The user types a value into a single-line input and commits
 - **`onClear`** `() => void` — Called when the clear button is pressed
 - **`onOpenChange`** `(isOpen: boolean) => void` — Called when the suggestions popover opens or closes
 - **`onFocus`** `() => void` — Called when focus enters the component: the input, a chip or the popover
-- **`onBlur`** `() => void` — Called when focus leaves the component entirely
+- **`onBlur`** `() => void` — Called when focus leaves the component entirely, after the typed text is committed and before the press that moved focus is handled, so a Save click sees the new value
 - **`onKeyDown`** `(e: KeyboardEvent) => void` — Called when a key is pressed in the input, before the component handles it. Call `e.preventDefault()` to stop the built-in handling
 - **`inputRef`**, **`wrapperRef`**, **`popoverRef`**, **`listBoxRef`** `RefObject` — Refs to the input, the bordered input box, the popover and its listbox. The forwarded `ref` points at the root, which holds the input and the chips
 - **`mods`** `Record<string, boolean>` — Modifiers for the bordered input box, see [Modifiers](#modifiers)
 
 #### Notable Properties
 
-**delimiters** - Typing a delimiter commits the text before it, and pasting splits the text on every delimiter and line break, so a column copied from a spreadsheet or a comma-separated list becomes one chip per entry. A single pasted value is inserted as plain text for the user to finish. Pass `[]` when a value may contain a comma: only Enter and pasted line breaks separate values then.
+**delimiters** - Typing a delimiter commits the text before it, and pasting splits the text on every delimiter and line break, so a column copied from a spreadsheet or a comma-separated list becomes one chip per entry. A single pasted value is inserted as plain text for the user to finish. Pass `[]` when a value may contain a comma: only Enter and pasted line breaks separate values then. Refused values go back to the input joined by the first delimiter, so they split into the same values again; with `[]` nothing can separate them in one line, so only the first refused value stays there, with its message.
 
-**validateTag** - Runs on every value about to become a chip. A rejected value stays in the input, the field turns invalid and the message shows below it until the text is edited. A value picked from the options is not checked. Values already in `value` that fail the check are drawn in the danger theme and carry the message as their description, so an invalid entry loaded from the server stands out. Duplicates are always refused, with a message of their own.
+**validateTag** - Runs on every value about to become a chip. A rejected value stays in the input, the field turns invalid and the message shows below it until the text is edited. A value picked from the options is not checked. Values already in `value` that fail the check are drawn in the danger theme and carry the message as their description, so an invalid entry loaded from the server stands out. Duplicates are always refused, with a message of their own, and leave the input: the value is there already, as a chip. When a paste mixes the two, the message is the one for the text left in the input. A message is cleared by Escape, and by leaving the field once nothing is left in the input, so a refused duplicate does not leave an empty field marked invalid.
 
 **normalizeTag** - Runs on typed text before anything else looks at it, so the duplicate check, `validateTag` and the new chip all see the rewritten value: lowercase an email address, strip thousands separators, write a number one way. The rejected text that stays in the input is what the user typed. Picked options keep their keys.
 
@@ -68,7 +68,7 @@ A multi-value field. The user types a value into a single-line input and commits
 
 **tagProps** - Called per value. Return a theme, an icon or `qa` for the chip. A string `children` replaces the chip's text and also names the value in the input's description and in the "Added"/"Removed" announcements, for values whose label does not come from the options. `isDisabled: true` locks the chip: it has no remove button, the keyboard skips it, and its option cannot be unpicked. An invalid chip stays in the danger theme whatever theme it asks for.
 
-**children / items** - Options turn the input into a combobox. Typing filters them and focuses the option whose label is exactly the typed text, or else the first match. Enter or a click toggles the focused option, and the popover stays open so the user can pick several in a row. Typed text means "add": pressing Enter on an option that is already a chip refuses it as a duplicate, and unpicking it takes the arrow keys, a click, or an empty input. A picked option shows a checked box. Without `allowsCustomValue`, typed text must match an option by key or label, and on blur a query that matches nothing is dropped. With it, the typed text is offered as its own option after the matches, the same way [FilterListBox](./FilterListBox.md) does, and custom values already added are listed there too, checked and sorted, so they can be unpicked from the list as well as from their chips. One unpicked in the list stays there, unchecked, until focus leaves the field, so it can be picked back. An option in `disabledKeys` is refused however it is entered. A chip for an option shows the option's label, while the value holds its key. The label is remembered, so it survives server-side filtering (`filter={false}` with changing `items`).
+**children / items** - Options turn the input into a combobox. Typing filters them and focuses the option the typed text names, or else the first match. Enter or a click toggles the focused option, and the popover stays open so the user can pick several in a row. A picked option is added as its own key, whatever other options its text resembles. Typed text means "add": pressing Enter on an option that is already a chip refuses it as a duplicate, and unpicking it takes the arrow keys, a click, or an empty input. A picked option shows a checked box. Typed text names an option by its exact label, then by its key, anywhere in the list, before any looser match counts, so `active` finds `active` even when `Active` comes first. Enter, a delimiter, a paste and blur all go by the same rule, and the option the text names stays listed and focused even when the filter would hide it, as when a key is typed, so they always add the same option. Without `allowsCustomValue`, typed text must name an option, and a label in another case or without its accents counts too: `production` adds `Production`. On blur a query that names nothing is dropped. With `allowsCustomValue`, only an exact match counts: `paris` next to an option `Paris` is a value of its own, offered and focused as its own row and added as typed, since a case-sensitive filter treats the two apart. A press on a control outside while the popover shows (a button, a link, another field) is not taken by it: it reaches the control, so a Save button saves on the first click, with the typed text already committed. A press anywhere else, such as the backdrop of a dialog the field sits in, only closes the popover, and the dialog stays open. The typed text is offered as its own option after the matches, the same way [FilterListBox](./FilterListBox.md) does, and custom values already added are listed there too, checked and sorted, so they can be unpicked from the list as well as from their chips. One unpicked in the list stays there, unchecked, until focus leaves the field, so it can be picked back. An option in `disabledKeys` is refused however it is entered. A chip for an option shows the option's label, while the value holds its key. The label is remembered, so it survives server-side filtering (`filter={false}` with changing `items`).
 
 ### Base Properties
 
@@ -185,7 +185,7 @@ const EMAIL = /^[^\s@,]+@[^\s@,]+\.[^\s@,]+$/;
 
 ### Pasting a List
 
-Pasted text is split on delimiters and line breaks. Accepted entries become chips, rejected ones stay in the input with the message from `validateTag`.
+Pasted text is split on delimiters and line breaks. Accepted entries become chips, rejected ones stay in the input with the message from `validateTag`, and duplicates of existing chips are dropped with a message of their own.
 
 ### Picking from Suggestions
 
@@ -359,9 +359,9 @@ const [recipients, setRecipients] = useState(['ana@acme.com']);
 
 - `Tab` - Moves focus from the input to the chips, then out of the field. The chips are one Tab stop; the popover trigger and the clear button are not Tab stops. Tabbing away closes the popover and commits the typed text
 - `Shift+Tab` - Moves back from the chips to the input
-- `Enter` - Commits the typed text. With the popover open, toggles the focused option, the one `aria-activedescendant` announces; with text typed, an option that is already a chip is refused as a duplicate rather than removed. Never submits a surrounding form, even with nothing typed, so one Enter too many after the last value does not send a half-filled dialog
+- `Enter` - Commits the typed text. With the popover open, toggles the focused option, the one `aria-activedescendant` announces; with text typed, an option that is already a chip is refused as a duplicate rather than removed, and the text is cleared. Never submits a surrounding form, even with nothing typed, so one Enter too many after the last value does not send a half-filled dialog
 - `,` (or another delimiter) - Commits the text before the caret and keeps the rest typed
-- `Escape` - Closes the popover, or clears the typed text when it is closed
+- `Escape` - Closes the popover, or clears the typed text when it is closed. Either way it clears a message about the text, even once the input is empty
 - `Backspace` in the empty input - Moves focus to the last chip without removing it, and closes the popover. A Backspace held down to clear the text stops at the empty input
 - `ArrowDown` / `ArrowUp` - Opens the popover or moves through the options
 - `Home` / `End` - Moves to the first or last option while the popover is open

package/docs/tasty/ai-agents.md

@@ -22,6 +22,12 @@ tastyStatic('.card', { … });                                              // b
 - Wrap, don't pass styles per instance: ❌ `<Box styles={{ padding: '2x' }} />` → ✅ `const Box = tasty({ styles: { padding: '2x' } })`.
 - Style values are **static**. Route anything conditional through a state map plus `mods` (or `tokens` / `styleProps`):
   ❌ `fill: isOpen ? '#primary' : '#surface'` → ✅ `fill: { '': '#surface', open: '#primary' }` with `mods={{ open: isOpen }}`.
+- Keep JavaScript identifiers, calls, computed keys, and interpolated templates
+  out of style values. Use token references inside strings for values supplied
+  at runtime. Spell out style properties rather than spreading objects; if a
+  runtime spread is unavoidable, add a
+  `// eslint-disable-next-line tasty/no-style-spread -- reason` comment directly
+  above it. `tastyStatic()` cannot use spreads.
 
 ## 2. Property names
 
@@ -128,7 +134,19 @@ Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `row
 
 Use semantic names, not CSS property names: `fade` `fill` `color` `theme` `border` `radius` `shadow` `outline` `preset` `text` `gap` `opacity` `translate` `rotate` `scale` `filter` `image` `background` `width` `height` `zIndex` `inset` `flow` `dimension`.
 
-❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill 0.2s'`
+❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill'`
+
+Omit the duration to use `$fill-transition` with `$transition` as fallback, or
+use a duration token explicitly (`transition: 'fill $transition'`). Avoid raw
+time values in duration slots. An explicit zero can be useful to disable motion.
+
+Use `transition` when defining a complete transition, and the native CSS
+`animation` shorthand when defining a complete animation. Tasty accepts
+`animation` directly and tracks local keyframes referenced by it; no special
+animation handler is needed. Use duration tokens in either form. Keep
+`transitionDuration`, `animationDuration`, and other motion longhands when a
+state or extension changes only one part of an existing effect. A shorthand
+resets omitted parts, including an animation's timeline and range.
 
 ## 4. State maps
 
@@ -155,7 +173,8 @@ Rules:
 3. **`_` is standalone-only** and always first (with `''` right after it, if present). `_` is a never-negated fallback floor for cases where a higher-priority branch may be _unknown_ (`@supports`, container queries). If a map contains only `_` and `''`, drop the `''`.
 4. **No nested maps:** ❌ `{ hovered: { pressed: 'x' } }` → ✅ `{ 'hovered & pressed': 'x' }`
 5. **State keys never sit at the top level** of a styles object — `:hover`, `.active`, `[open]` belong inside a property value.
-6. **Prefer automatic native states:** use `disabled` and `checked` in Tasty component styles instead of `[disabled]` and `[checked]`. The concise states track the corresponding native prop or attribute automatically.
+6. **Write keys Tasty can fully read.** Names start with a letter (a single letter is fine: `x` → `[data-x]`); join states with an operator (`hovered & focused`, not `hovered focused`); no space between `@media` and `(`. Tasty warns (`INVALID_STATE_KEY`) and skips what it cannot read.
+7. **Prefer automatic native states:** use `disabled` and `checked` in Tasty component styles instead of `[disabled]` and `[checked]`. The concise states track the corresponding native prop or attribute automatically.
 
 ```jsx
 color: { '': '#text', hovered: '#accent', disabled: '#text.40' }

package/docs/tasty/dsl.md

@@ -54,6 +54,8 @@ fill: {
 }
 ```
 
+Modifier and class names start with a letter and may be a single letter (`x` → `[data-x]`, `.x`). Tasty emits an `INVALID_STATE_KEY` warning for a key it cannot fully read and skips the unreadable parts. That covers characters outside the notation (`1st`, or `@media (w < 600px)` with a space before the parenthesis), an operator missing a state (`hovered &`), and two states with no operator between them (`hovered focused`). A partly read key can apply in states you did not mean, so fix the key rather than rely on what it produces.
+
 #### Default State Ordering
 
 Key order sets priority — later keys win and turn off earlier ones via negation. The bare default (`''`) is the lowest-priority state, so it **must be the first key**. If it appears after other states, Tasty moves it to the front and emits a dev warning (`MISPLACED_DEFAULT_STATE`); otherwise it would override every state above it.
@@ -701,7 +703,7 @@ const FadeIn = tasty({
   styles: {
     opacity: { '': '1', '@starting': '0' },
     transform: { '': 'scale(1)', '@starting': 'scale(0.95)' },
-    transition: 'opacity 0.3s, translate 0.3s',
+    transition: 'opacity, translate',
   },
 });
 ```
@@ -833,7 +835,7 @@ const AnimatedGradient = tasty({
     '$gradient-angle': '0deg',
     '#theme': 'okhst(280 80% 50%)',
     image: 'linear-gradient($gradient-angle, #theme, #clear)',
-    transition: '$$gradient-angle 0.3s, ##theme 0.3s',
+    transition: '$$gradient-angle, ##theme',
   },
 });
 ```

package/docs/tasty/getting-started.md

@@ -169,20 +169,22 @@ export default [
 
 ### What `recommended` catches
 
-The `recommended` config enables 18 of the plugin's 27 total rules. It covers the most common issues without turning on the stricter governance rules:
-
-| Category            | Rules                                                                                                  | Examples                                                     |
-| ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
-| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage           |
-| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax               |
-| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists      |
-| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                       |
-| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`           |
-| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax |
+The `recommended` config covers common correctness and style issues:
+
+| Category            | Rules                                                                                                  | Examples                                                              |
+| ------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage                    |
+| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax                        |
+| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists               |
+| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                                |
+| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`                    |
+| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax          |
+| Motion guidance     | `no-raw-transition-duration`                                                                           | Suggests timing tokens or the default timing for transition durations |
+| Dynamic styles      | `no-runtime-styles-mutation`, `no-style-spread`                                                         | Warns on JavaScript values and spreads inside runtime style objects   |
 
 ### Strict config
 
-For stricter governance, use `tasty.configs.strict`. It adds rules that enforce best practices like preferring shorthand properties, consistent token usage, and flagging direct `styles` prop usage:
+For stricter governance, use `tasty.configs.strict`. It adds rules that flag direct `styles` prop usage and other patterns:
 
 ```js
 export default [tasty.configs.strict];

package/docs/tasty/methodology.md

@@ -236,7 +236,7 @@ const ProgressBar = tasty({
       width: '$progress',
       height: '100%',
       fill: '#primary',
-      transition: 'width 0.3s',
+      transition: 'width',
     },
   },
   elements: { Bar: 'div' },
@@ -534,7 +534,7 @@ See [Configuration](configuration.md) for the full `configure()` API.
 
 - **Create styled wrappers** instead of passing `styles` directly — faster, composable, inspectable
 - **Use design tokens and custom units** (`#text`, `2x`, `1r`) instead of raw CSS values
-- **Use semantic transition names** (`transition: 'theme 0.3s'`) instead of listing CSS properties
+- **Use semantic transition names** (`transition: 'theme'`) instead of listing CSS properties; omit the duration to use the motion tokens
 - **Use `elements` prop** to declare typed sub-components for compound components
 - **Use `styleProps`** to define what product engineers can customize
 - **Use `modProps`** to expose known modifier states as clean component props