@cube-dev/ui-kit 0.181.0 → 0.183.0

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

@@ -1 +1 @@
-{"version":3,"file":"useScheme.js","names":[],"sources":["../../../src/utils/react/useScheme.ts"],"sourcesContent":["import { useSyncExternalStore } from 'react';\n\n/**\n * The ambient viewing conditions — the color scheme and the contrast tier the\n * document is showing right now.\n *\n * This module is the single owner of the definition: it builds the `@dark` /\n * `@hc` predefined states that `src/components/Root.tsx` registers with tasty,\n * *and* it answers the same question in JS. One definition, two readers, so the\n * CSS and the JS answers cannot drift apart.\n *\n * **For styling, do not use this.** `{ '': light, '@dark': dark, '@hc': hc }` is\n * the answer, and branching styles in JS gives up the conditionality that lets a\n * scheme flip repaint without a re-render. Two cases the state map cannot serve:\n *\n * 1. **Surfaces the stylesheet does not reach** — a Vega spec, a CodeMirror or\n *    Monaco theme, a third-party iframe. They take values, not CSS, so `@dark`\n *    never applies and the branch has to happen in JS.\n * 2. **Control state that is not styling** — seeding or labelling a control from\n *    the ambient condition, e.g. a Light/Dark or Normal/High-contrast preview\n *    selector that starts on whatever the page is already showing.\n *\n * Root-level only, and deliberately not a generic state reader: tasty's state\n * vocabulary mixes element-local states (`hovered`, `pressed`, `disabled`) with\n * ambient ones (`@media(…)`, `@root(…)`), and only the ambient half is\n * answerable without an element. Evaluating the state language in JS would mean\n * a second implementation of the state algebra to keep in agreement with the CSS\n * one, for a question almost every caller asks about the root anyway.\n */\n\n// ============================================================================\n// The definition\n// ============================================================================\n\n/**\n * The `data-*` attribute names the opt-in uses, and the media queries it falls\n * back to. `@root(scheme=dark)` compiles to `:root[data-scheme=\"dark\"]`, hence\n * the `data-` prefix on the DOM side and the bare key on the tasty side.\n */\nconst SCHEME_KEY = 'scheme';\nconst CONTRAST_KEY = 'contrast';\nconst SCHEME_ATTR = `data-${SCHEME_KEY}`;\nconst CONTRAST_ATTR = `data-${CONTRAST_KEY}`;\nconst DARK_QUERY = '(prefers-color-scheme: dark)';\nconst HIGH_CONTRAST_QUERY = '(prefers-contrast: more)';\n\n/**\n * The `@dark` / `@hc` state aliases, in tasty's DSL — registered globally by\n * `<Root>` via `setGlobalPredefinedStates()`.\n *\n * The attribute opt-in wins over the system preference, and the fallback is\n * gated on the attribute being *absent* (`!@root(scheme)`) rather than on it\n * being some other value — so `<html data-scheme=\"light\">` stays light inside a\n * dark OS, which is the whole point of an opt-in. {@link resolveScheme} and\n * {@link resolveHighContrast} read the same way.\n */\nexport const AMBIENT_PREDEFINED_STATES = {\n  '@dark': `@root(${SCHEME_KEY}=dark) | (!@root(${SCHEME_KEY}) & @media${DARK_QUERY})`,\n  '@hc': `@root(${CONTRAST_KEY}=high) | (!@root(${CONTRAST_KEY}) & @media${HIGH_CONTRAST_QUERY})`,\n} as const;\n\n/** The color scheme the document resolves to — the two arms of the `@dark` state. */\nexport type ColorScheme = 'light' | 'dark';\n\n// ============================================================================\n// Reading\n// ============================================================================\n\n/**\n * `matchMedia` is called per read rather than cached, so a test that stubs it\n * takes effect immediately. Missing (older jsdom, non-DOM runtimes) reads as\n * \"no preference\", which lands on the light / normal-contrast defaults.\n */\nfunction mediaMatches(query: string): boolean {\n  return typeof window !== 'undefined' &&\n    typeof window.matchMedia === 'function'\n    ? window.matchMedia(query).matches\n    : false;\n}\n\nfunction rootAttribute(name: string): string | null {\n  return typeof document === 'undefined'\n    ? null\n    : document.documentElement.getAttribute(name);\n}\n\n/**\n * The document's current color scheme, read once — the JS answer to `@dark`.\n *\n * Outside React (a chart spec built in a module, an editor theme registered at\n * import time). In React use {@link useScheme}, which also re-renders on change.\n * Returns `'light'` with no DOM.\n */\nexport function resolveScheme(): ColorScheme {\n  const attribute = rootAttribute(SCHEME_ATTR);\n\n  if (attribute !== null) {\n    return attribute === 'dark' ? 'dark' : 'light';\n  }\n\n  return mediaMatches(DARK_QUERY) ? 'dark' : 'light';\n}\n\n/**\n * Whether the document is showing the high-contrast tier, read once — the JS\n * answer to `@hc`.\n *\n * Note this is an *ambient* condition, not the theme's `contrastLevel`: the\n * level is a `PaletteConfig` seed the app supplies (read it with\n * `getPaletteConfig()`), while this is the tier the viewer asked for.\n * Returns `false` with no DOM.\n */\nexport function resolveHighContrast(): boolean {\n  const attribute = rootAttribute(CONTRAST_ATTR);\n\n  if (attribute !== null) {\n    return attribute === 'high';\n  }\n\n  return mediaMatches(HIGH_CONTRAST_QUERY);\n}\n\n// ============================================================================\n// Watching\n// ============================================================================\n\nconst listeners = new Set<() => void>();\n\nlet stopWatching: (() => void) | null = null;\n\nfunction notify() {\n  listeners.forEach((listener) => listener());\n}\n\n/**\n * Both inputs have to be watched, because either can decide the answer: the\n * attribute when the opt-in is set, the media query otherwise — an attribute flip\n * is invisible to `matchMedia` and a system flip is invisible to a\n * `MutationObserver`. One observer and one pair of query listeners are shared by\n * every subscriber, and torn down when the last one leaves.\n */\nfunction startWatching(): () => void {\n  if (typeof document === 'undefined') {\n    return () => {};\n  }\n\n  const teardowns: (() => void)[] = [];\n\n  // Guarded rather than assumed: jsdom ships neither `matchMedia` nor a\n  // `MediaQueryList` in every version, and a consumer's unit tests are exactly\n  // where a hook like this gets mounted. Losing one source of change is a stale\n  // value; throwing is a broken render.\n  if (\n    typeof window !== 'undefined' &&\n    typeof window.matchMedia === 'function'\n  ) {\n    for (const query of [DARK_QUERY, HIGH_CONTRAST_QUERY]) {\n      const list = window.matchMedia(query);\n\n      if (typeof list?.addEventListener !== 'function') continue;\n\n      list.addEventListener('change', notify);\n      teardowns.push(() => list.removeEventListener('change', notify));\n    }\n  }\n\n  if (typeof MutationObserver === 'function' && document.documentElement) {\n    const observer = new MutationObserver(notify);\n\n    observer.observe(document.documentElement, {\n      attributes: true,\n      attributeFilter: [SCHEME_ATTR, CONTRAST_ATTR],\n    });\n\n    teardowns.push(() => observer.disconnect());\n  }\n\n  return () => teardowns.forEach((teardown) => teardown());\n}\n\n/**\n * Subscribe to ambient condition changes — either the scheme or the contrast\n * tier. Returns an unsubscribe function.\n *\n * The listener takes no argument: re-read with {@link resolveScheme} /\n * {@link resolveHighContrast}, which is what the hooks below do. For non-React\n * consumers that own a surface the stylesheet cannot reach — re-theming a Monaco\n * instance, re-rendering a chart.\n */\nexport function subscribeScheme(listener: () => void): () => void {\n  listeners.add(listener);\n\n  if (!stopWatching) {\n    stopWatching = startWatching();\n  }\n\n  return () => {\n    listeners.delete(listener);\n\n    if (!listeners.size && stopWatching) {\n      stopWatching();\n      stopWatching = null;\n    }\n  };\n}\n\n// ============================================================================\n// React bindings\n// ============================================================================\n\n/**\n * Snapshots are primitives, so React bails out on an unchanged value and no\n * memoization is needed — a contrast change re-runs a `useScheme()` reader's\n * `getSnapshot` and stops there.\n */\nconst getServerScheme = (): ColorScheme => 'light';\nconst getServerHighContrast = () => false;\n\n/**\n * The document's color scheme, kept live — `'light'` or `'dark'`.\n *\n * ```tsx\n * const scheme = useScheme();\n *\n * <VegaChart spec={useMemo(() => buildSpec(scheme), [scheme])} />;\n * ```\n *\n * Follows both the `<html data-scheme>` opt-in and `prefers-color-scheme`,\n * exactly as the `@dark` state does. Under SSR it renders `'light'` and\n * re-renders with the real value after hydration.\n */\nexport function useScheme(): ColorScheme {\n  return useSyncExternalStore(subscribeScheme, resolveScheme, getServerScheme);\n}\n\n/**\n * Whether the document is showing the high-contrast tier, kept live — the hook\n * form of {@link resolveHighContrast}, following `<html data-contrast>` and\n * `prefers-contrast` exactly as the `@hc` state does.\n *\n * Under SSR it renders `false` and re-renders with the real value after\n * hydration.\n */\nexport function useHighContrast(): boolean {\n  return useSyncExternalStore(\n    subscribeScheme,\n    resolveHighContrast,\n    getServerHighContrast,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAM,aAAa;AACnB,MAAM,eAAe;AACrB,MAAM,cAAc,QAAQ;AAC5B,MAAM,gBAAgB,QAAQ;AAC9B,MAAM,aAAa;AACnB,MAAM,sBAAsB;;;;;;;;;;;AAY5B,MAAa,4BAA4B;CACvC,SAAS,SAAS,WAAW,mBAAmB,WAAW,YAAY,WAAW;CAClF,OAAO,SAAS,aAAa,mBAAmB,aAAa,YAAY,oBAAoB;CAC9F;;;;;;AAcD,SAAS,aAAa,OAAwB;AAC5C,QAAO,OAAO,WAAW,eACvB,OAAO,OAAO,eAAe,aAC3B,OAAO,WAAW,MAAM,CAAC,UACzB;;AAGN,SAAS,cAAc,MAA6B;AAClD,QAAO,OAAO,aAAa,cACvB,OACA,SAAS,gBAAgB,aAAa,KAAK;;;;;;;;;AAUjD,SAAgB,gBAA6B;CAC3C,MAAM,YAAY,cAAc,YAAY;AAE5C,KAAI,cAAc,KAChB,QAAO,cAAc,SAAS,SAAS;AAGzC,QAAO,aAAa,WAAW,GAAG,SAAS;;;;;;;;;;;AAY7C,SAAgB,sBAA+B;CAC7C,MAAM,YAAY,cAAc,cAAc;AAE9C,KAAI,cAAc,KAChB,QAAO,cAAc;AAGvB,QAAO,aAAa,oBAAoB;;AAO1C,MAAM,4BAAY,IAAI,KAAiB;AAEvC,IAAI,eAAoC;AAExC,SAAS,SAAS;AAChB,WAAU,SAAS,aAAa,UAAU,CAAC;;;;;;;;;AAU7C,SAAS,gBAA4B;AACnC,KAAI,OAAO,aAAa,YACtB,cAAa;CAGf,MAAM,YAA4B,EAAE;AAMpC,KACE,OAAO,WAAW,eAClB,OAAO,OAAO,eAAe,WAE7B,MAAK,MAAM,SAAS,CAAC,YAAY,oBAAoB,EAAE;EACrD,MAAM,OAAO,OAAO,WAAW,MAAM;AAErC,MAAI,OAAO,MAAM,qBAAqB,WAAY;AAElD,OAAK,iBAAiB,UAAU,OAAO;AACvC,YAAU,WAAW,KAAK,oBAAoB,UAAU,OAAO,CAAC;;AAIpE,KAAI,OAAO,qBAAqB,cAAc,SAAS,iBAAiB;EACtE,MAAM,WAAW,IAAI,iBAAiB,OAAO;AAE7C,WAAS,QAAQ,SAAS,iBAAiB;GACzC,YAAY;GACZ,iBAAiB,CAAC,aAAa,cAAc;GAC9C,CAAC;AAEF,YAAU,WAAW,SAAS,YAAY,CAAC;;AAG7C,cAAa,UAAU,SAAS,aAAa,UAAU,CAAC;;;;;;;;;;;AAY1D,SAAgB,gBAAgB,UAAkC;AAChE,WAAU,IAAI,SAAS;AAEvB,KAAI,CAAC,aACH,gBAAe,eAAe;AAGhC,cAAa;AACX,YAAU,OAAO,SAAS;AAE1B,MAAI,CAAC,UAAU,QAAQ,cAAc;AACnC,iBAAc;AACd,kBAAe;;;;;;;;;AAcrB,MAAM,wBAAqC;AAC3C,MAAM,8BAA8B;;;;;;;;;;;;;;AAepC,SAAgB,YAAyB;AACvC,QAAO,qBAAqB,iBAAiB,eAAe,gBAAgB;;;;;;;;;;AAW9E,SAAgB,kBAA2B;AACzC,QAAO,qBACL,iBACA,qBACA,sBACD"}
+{"version":3,"file":"useScheme.js","names":["useSyncExternalStore","SCHEME_KEY","CONTRAST_KEY","SCHEME_ATTR","CONTRAST_ATTR","DARK_QUERY","HIGH_CONTRAST_QUERY","AMBIENT_PREDEFINED_STATES","const","ColorScheme","mediaMatches","query","window","matchMedia","matches","rootAttribute","name","document","documentElement","getAttribute","resolveScheme","attribute","resolveHighContrast","listeners","Set","stopWatching","notify","forEach","listener","startWatching","teardowns","list","addEventListener","push","removeEventListener","MutationObserver","observer","observe","attributes","attributeFilter","disconnect","teardown","subscribeScheme","add","delete","size","getServerScheme","getServerHighContrast","useScheme","useHighContrast"],"sources":["../../../src/utils/react/useScheme.ts"],"sourcesContent":["import { useSyncExternalStore } from 'react';\n\n/**\n * The ambient viewing conditions — the color scheme and the contrast tier the\n * document is showing right now.\n *\n * This module is the single owner of the definition: it builds the `@dark` /\n * `@hc` predefined states that `src/components/Root.tsx` registers with tasty,\n * *and* it answers the same question in JS. One definition, two readers, so the\n * CSS and the JS answers cannot drift apart.\n *\n * **For styling, do not use this.** `{ '': light, '@dark': dark, '@hc': hc }` is\n * the answer, and branching styles in JS gives up the conditionality that lets a\n * scheme flip repaint without a re-render. Two cases the state map cannot serve:\n *\n * 1. **Surfaces the stylesheet does not reach** — a Vega spec, a CodeMirror or\n *    Monaco theme, a third-party iframe. They take values, not CSS, so `@dark`\n *    never applies and the branch has to happen in JS.\n * 2. **Control state that is not styling** — seeding or labelling a control from\n *    the ambient condition, e.g. a Light/Dark or Normal/High-contrast preview\n *    selector that starts on whatever the page is already showing.\n *\n * Root-level only, and deliberately not a generic state reader: tasty's state\n * vocabulary mixes element-local states (`hovered`, `pressed`, `disabled`) with\n * ambient ones (`@media(…)`, `@root(…)`), and only the ambient half is\n * answerable without an element. Evaluating the state language in JS would mean\n * a second implementation of the state algebra to keep in agreement with the CSS\n * one, for a question almost every caller asks about the root anyway.\n */\n\n// ============================================================================\n// The definition\n// ============================================================================\n\n/**\n * The `data-*` attribute names the opt-in uses, and the media queries it falls\n * back to. `@root(scheme=dark)` compiles to `:root[data-scheme=\"dark\"]`, hence\n * the `data-` prefix on the DOM side and the bare key on the tasty side.\n */\nconst SCHEME_KEY = 'scheme';\nconst CONTRAST_KEY = 'contrast';\nconst SCHEME_ATTR = `data-${SCHEME_KEY}`;\nconst CONTRAST_ATTR = `data-${CONTRAST_KEY}`;\nconst DARK_QUERY = '(prefers-color-scheme: dark)';\nconst HIGH_CONTRAST_QUERY = '(prefers-contrast: more)';\n\n/**\n * The `@dark` / `@hc` state aliases, in tasty's DSL — registered globally by\n * `<Root>` via `setGlobalPredefinedStates()`.\n *\n * The attribute opt-in wins over the system preference, and the fallback is\n * gated on the attribute being *absent* (`!@root(scheme)`) rather than on it\n * being some other value — so `<html data-scheme=\"light\">` stays light inside a\n * dark OS, which is the whole point of an opt-in. {@link resolveScheme} and\n * {@link resolveHighContrast} read the same way.\n */\nexport const AMBIENT_PREDEFINED_STATES = {\n  '@dark': `@root(${SCHEME_KEY}=dark) | (!@root(${SCHEME_KEY}) & @media${DARK_QUERY})`,\n  '@hc': `@root(${CONTRAST_KEY}=high) | (!@root(${CONTRAST_KEY}) & @media${HIGH_CONTRAST_QUERY})`,\n} as const;\n\n/** The color scheme the document resolves to — the two arms of the `@dark` state. */\nexport type ColorScheme = 'light' | 'dark';\n\n// ============================================================================\n// Reading\n// ============================================================================\n\n/**\n * `matchMedia` is called per read rather than cached, so a test that stubs it\n * takes effect immediately. Missing (older jsdom, non-DOM runtimes) reads as\n * \"no preference\", which lands on the light / normal-contrast defaults.\n */\nfunction mediaMatches(query: string): boolean {\n  return typeof window !== 'undefined' &&\n    typeof window.matchMedia === 'function'\n    ? window.matchMedia(query).matches\n    : false;\n}\n\nfunction rootAttribute(name: string): string | null {\n  return typeof document === 'undefined'\n    ? null\n    : document.documentElement.getAttribute(name);\n}\n\n/**\n * The document's current color scheme, read once — the JS answer to `@dark`.\n *\n * Outside React (a chart spec built in a module, an editor theme registered at\n * import time). In React use {@link useScheme}, which also re-renders on change.\n * Returns `'light'` with no DOM.\n */\nexport function resolveScheme(): ColorScheme {\n  const attribute = rootAttribute(SCHEME_ATTR);\n\n  if (attribute !== null) {\n    return attribute === 'dark' ? 'dark' : 'light';\n  }\n\n  return mediaMatches(DARK_QUERY) ? 'dark' : 'light';\n}\n\n/**\n * Whether the document is showing the high-contrast tier, read once — the JS\n * answer to `@hc`.\n *\n * Note this is an *ambient* condition, not the theme's `contrastLevel`: the\n * level is a `PaletteConfig` seed the app supplies (read it with\n * `getPaletteConfig()`), while this is the tier the viewer asked for.\n * Returns `false` with no DOM.\n */\nexport function resolveHighContrast(): boolean {\n  const attribute = rootAttribute(CONTRAST_ATTR);\n\n  if (attribute !== null) {\n    return attribute === 'high';\n  }\n\n  return mediaMatches(HIGH_CONTRAST_QUERY);\n}\n\n// ============================================================================\n// Watching\n// ============================================================================\n\nconst listeners = new Set<() => void>();\n\nlet stopWatching: (() => void) | null = null;\n\nfunction notify() {\n  listeners.forEach((listener) => listener());\n}\n\n/**\n * Both inputs have to be watched, because either can decide the answer: the\n * attribute when the opt-in is set, the media query otherwise — an attribute flip\n * is invisible to `matchMedia` and a system flip is invisible to a\n * `MutationObserver`. One observer and one pair of query listeners are shared by\n * every subscriber, and torn down when the last one leaves.\n */\nfunction startWatching(): () => void {\n  if (typeof document === 'undefined') {\n    return () => {};\n  }\n\n  const teardowns: (() => void)[] = [];\n\n  // Guarded rather than assumed: jsdom ships neither `matchMedia` nor a\n  // `MediaQueryList` in every version, and a consumer's unit tests are exactly\n  // where a hook like this gets mounted. Losing one source of change is a stale\n  // value; throwing is a broken render.\n  if (\n    typeof window !== 'undefined' &&\n    typeof window.matchMedia === 'function'\n  ) {\n    for (const query of [DARK_QUERY, HIGH_CONTRAST_QUERY]) {\n      const list = window.matchMedia(query);\n\n      if (typeof list?.addEventListener !== 'function') continue;\n\n      list.addEventListener('change', notify);\n      teardowns.push(() => list.removeEventListener('change', notify));\n    }\n  }\n\n  if (typeof MutationObserver === 'function' && document.documentElement) {\n    const observer = new MutationObserver(notify);\n\n    observer.observe(document.documentElement, {\n      attributes: true,\n      attributeFilter: [SCHEME_ATTR, CONTRAST_ATTR],\n    });\n\n    teardowns.push(() => observer.disconnect());\n  }\n\n  return () => teardowns.forEach((teardown) => teardown());\n}\n\n/**\n * Subscribe to ambient condition changes — either the scheme or the contrast\n * tier. Returns an unsubscribe function.\n *\n * The listener takes no argument: re-read with {@link resolveScheme} /\n * {@link resolveHighContrast}, which is what the hooks below do. For non-React\n * consumers that own a surface the stylesheet cannot reach — re-theming a Monaco\n * instance, re-rendering a chart.\n */\nexport function subscribeScheme(listener: () => void): () => void {\n  listeners.add(listener);\n\n  if (!stopWatching) {\n    stopWatching = startWatching();\n  }\n\n  return () => {\n    listeners.delete(listener);\n\n    if (!listeners.size && stopWatching) {\n      stopWatching();\n      stopWatching = null;\n    }\n  };\n}\n\n// ============================================================================\n// React bindings\n// ============================================================================\n\n/**\n * Snapshots are primitives, so React bails out on an unchanged value and no\n * memoization is needed — a contrast change re-runs a `useScheme()` reader's\n * `getSnapshot` and stops there.\n */\nconst getServerScheme = (): ColorScheme => 'light';\nconst getServerHighContrast = () => false;\n\n/**\n * The document's color scheme, kept live — `'light'` or `'dark'`.\n *\n * ```tsx\n * const scheme = useScheme();\n *\n * <VegaChart spec={useMemo(() => buildSpec(scheme), [scheme])} />;\n * ```\n *\n * Follows both the `<html data-scheme>` opt-in and `prefers-color-scheme`,\n * exactly as the `@dark` state does. Under SSR it renders `'light'` and\n * re-renders with the real value after hydration.\n */\nexport function useScheme(): ColorScheme {\n  return useSyncExternalStore(subscribeScheme, resolveScheme, getServerScheme);\n}\n\n/**\n * Whether the document is showing the high-contrast tier, kept live — the hook\n * form of {@link resolveHighContrast}, following `<html data-contrast>` and\n * `prefers-contrast` exactly as the `@hc` state does.\n *\n * Under SSR it renders `false` and re-renders with the real value after\n * hydration.\n */\nexport function useHighContrast(): boolean {\n  return useSyncExternalStore(\n    subscribeScheme,\n    resolveHighContrast,\n    getServerHighContrast,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAMC,aAAa;AACnB,MAAMC,eAAe;AACrB,MAAMC,cAAc,QAAQF;AAC5B,MAAMG,gBAAgB,QAAQF;AAC9B,MAAMG,aAAa;AACnB,MAAMC,sBAAsB;;;;;;;;;;;AAY5B,MAAaC,4BAA4B;CACvC,SAAS,SAASN,WAAU,mBAAoBA,WAAU,YAAaI,WAAU;CACjF,OAAO,SAASH,aAAY,mBAAoBA,aAAY,YAAaI,oBAAmB;CAC7F;;;;;;AAcD,SAASI,aAAaC,OAAwB;AAC5C,QAAO,OAAOC,WAAW,eACvB,OAAOA,OAAOC,eAAe,aAC3BD,OAAOC,WAAWF,MAAM,CAACG,UACzB;;AAGN,SAASC,cAAcC,MAA6B;AAClD,QAAO,OAAOC,aAAa,cACvB,OACAA,SAASC,gBAAgBC,aAAaH,KAAK;;;;;;;;;AAUjD,SAAgBI,gBAA6B;CAC3C,MAAMC,YAAYN,cAAcZ,YAAY;AAE5C,KAAIkB,cAAc,KAChB,QAAOA,cAAc,SAAS,SAAS;AAGzC,QAAOX,aAAaL,WAAW,GAAG,SAAS;;;;;;;;;;;AAY7C,SAAgBiB,sBAA+B;CAC7C,MAAMD,YAAYN,cAAcX,cAAc;AAE9C,KAAIiB,cAAc,KAChB,QAAOA,cAAc;AAGvB,QAAOX,aAAaJ,oBAAoB;;AAO1C,MAAMiB,4BAAY,IAAIC,KAAiB;AAEvC,IAAIC,eAAoC;AAExC,SAASC,SAAS;AAChBH,WAAUI,SAASC,aAAaA,UAAU,CAAC;;;;;;;;;AAU7C,SAASC,gBAA4B;AACnC,KAAI,OAAOZ,aAAa,YACtB,cAAa;CAGf,MAAMa,YAA4B,EAAE;AAMpC,KACE,OAAOlB,WAAW,eAClB,OAAOA,OAAOC,eAAe,WAE7B,MAAK,MAAMF,SAAS,CAACN,YAAYC,oBAAoB,EAAE;EACrD,MAAMyB,OAAOnB,OAAOC,WAAWF,MAAM;AAErC,MAAI,OAAOoB,MAAMC,qBAAqB,WAAY;AAElDD,OAAKC,iBAAiB,UAAUN,OAAO;AACvCI,YAAUG,WAAWF,KAAKG,oBAAoB,UAAUR,OAAO,CAAC;;AAIpE,KAAI,OAAOS,qBAAqB,cAAclB,SAASC,iBAAiB;EACtE,MAAMkB,WAAW,IAAID,iBAAiBT,OAAO;AAE7CU,WAASC,QAAQpB,SAASC,iBAAiB;GACzCoB,YAAY;GACZC,iBAAiB,CAACpC,aAAaC,cAAa;GAC7C,CAAC;AAEF0B,YAAUG,WAAWG,SAASI,YAAY,CAAC;;AAG7C,cAAaV,UAAUH,SAASc,aAAaA,UAAU,CAAC;;;;;;;;;;;AAY1D,SAAgBC,gBAAgBd,UAAkC;AAChEL,WAAUoB,IAAIf,SAAS;AAEvB,KAAI,CAACH,aACHA,gBAAeI,eAAe;AAGhC,cAAa;AACXN,YAAUqB,OAAOhB,SAAS;AAE1B,MAAI,CAACL,UAAUsB,QAAQpB,cAAc;AACnCA,iBAAc;AACdA,kBAAe;;;;;;;;;AAcrB,MAAMqB,wBAAqC;AAC3C,MAAMC,8BAA8B;;;;;;;;;;;;;;AAepC,SAAOC,YAAA;AAAA,QACEhD,qBAAqB0C,iBAAiBtB,eAAe0B,gBAAgB;;;;;;;;;;AAW9E,SAAOG,kBAAA;AAAA,QACEjD,qBACL0C,iBACApB,qBACAyB,sBACD"}

package/dist/utils/react/useViewportSize.js

@@ -1,29 +1,53 @@
-/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+import { c } from "react-compiler-runtime";
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useViewportSize.ts
 let visualViewport = typeof window !== "undefined" && window.visualViewport;
-function useViewportSize(params = {}) {
-	const { isDisabled } = params;
-	let [size, setSize] = useState(() => getViewportSize());
-	useEffect(() => {
-		if (isDisabled) return;
-		let onResize = () => {
-			setSize((size) => {
-				let newSize = getViewportSize();
-				if (newSize.width === size.width && newSize.height === size.height) return size;
-				return newSize;
-			});
+function useViewportSize(t0) {
+	const $ = c(5);
+	let t1;
+	if ($[0] !== t0) {
+		t1 = t0 === void 0 ? {} : t0;
+		$[0] = t0;
+		$[1] = t1;
+	} else t1 = $[1];
+	const { isDisabled } = t1;
+	const [size, setSize] = useState(_temp);
+	let t2;
+	let t3;
+	if ($[2] !== isDisabled) {
+		t2 = () => {
+			if (isDisabled) return;
+			const onResize = () => {
+				setSize(_temp2);
+			};
+			if (!visualViewport) window.addEventListener("resize", onResize);
+			else visualViewport.addEventListener("resize", onResize);
+			return () => {
+				if (!visualViewport) window.removeEventListener("resize", onResize);
+				else visualViewport.removeEventListener("resize", onResize);
+			};
 		};
-		if (!visualViewport) window.addEventListener("resize", onResize);
-		else visualViewport.addEventListener("resize", onResize);
-		return () => {
-			if (!visualViewport) window.removeEventListener("resize", onResize);
-			else visualViewport.removeEventListener("resize", onResize);
-		};
-	}, [isDisabled]);
+		t3 = [isDisabled];
+		$[2] = isDisabled;
+		$[3] = t2;
+		$[4] = t3;
+	} else {
+		t2 = $[3];
+		t3 = $[4];
+	}
+	useEffect(t2, t3);
 	return size;
 }
+function _temp2(size_0) {
+	const newSize = getViewportSize();
+	if (newSize.width === size_0.width && newSize.height === size_0.height) return size_0;
+	return newSize;
+}
+function _temp() {
+	return getViewportSize();
+}
 function getViewportSize() {
 	return {
 		width: visualViewport && visualViewport.width || (typeof window !== "undefined" ? window.innerWidth : 0),

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

@@ -1 +1 @@
-{"version":3,"file":"useViewportSize.js","names":[],"sources":["../../../src/utils/react/useViewportSize.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\ninterface ViewportSize {\n  width: number;\n  height: number;\n}\n\nlet visualViewport = typeof window !== 'undefined' && window.visualViewport;\n\nexport type ViewportSizeParams = {\n  isDisabled?: boolean;\n};\nexport function useViewportSize(params: ViewportSizeParams = {}): ViewportSize {\n  const { isDisabled } = params;\n\n  let [size, setSize] = useState(() => getViewportSize());\n\n  useEffect(() => {\n    if (isDisabled) {\n      return;\n    }\n    // Use visualViewport api to track available height even on iOS virtual keyboard opening\n    let onResize = () => {\n      setSize((size) => {\n        let newSize = getViewportSize();\n        if (newSize.width === size.width && newSize.height === size.height) {\n          return size;\n        }\n        return newSize;\n      });\n    };\n\n    if (!visualViewport) {\n      window.addEventListener('resize', onResize);\n    } else {\n      visualViewport.addEventListener('resize', onResize);\n    }\n\n    return () => {\n      if (!visualViewport) {\n        window.removeEventListener('resize', onResize);\n      } else {\n        visualViewport.removeEventListener('resize', onResize);\n      }\n    };\n  }, [isDisabled]);\n\n  return size;\n}\n\nfunction getViewportSize(): ViewportSize {\n  return {\n    width:\n      (visualViewport && visualViewport.width) ||\n      (typeof window !== 'undefined' ? window.innerWidth : 0),\n    height:\n      (visualViewport && visualViewport.height) ||\n      (typeof window !== 'undefined' ? window.innerHeight : 0),\n  };\n}\n"],"mappings":";;;;AAOA,IAAI,iBAAiB,OAAO,WAAW,eAAe,OAAO;AAK7D,SAAgB,gBAAgB,SAA6B,EAAE,EAAgB;CAC7E,MAAM,EAAE,eAAe;CAEvB,IAAI,CAAC,MAAM,WAAW,eAAe,iBAAiB,CAAC;AAEvD,iBAAgB;AACd,MAAI,WACF;EAGF,IAAI,iBAAiB;AACnB,YAAS,SAAS;IAChB,IAAI,UAAU,iBAAiB;AAC/B,QAAI,QAAQ,UAAU,KAAK,SAAS,QAAQ,WAAW,KAAK,OAC1D,QAAO;AAET,WAAO;KACP;;AAGJ,MAAI,CAAC,eACH,QAAO,iBAAiB,UAAU,SAAS;MAE3C,gBAAe,iBAAiB,UAAU,SAAS;AAGrD,eAAa;AACX,OAAI,CAAC,eACH,QAAO,oBAAoB,UAAU,SAAS;OAE9C,gBAAe,oBAAoB,UAAU,SAAS;;IAGzD,CAAC,WAAW,CAAC;AAEhB,QAAO;;AAGT,SAAS,kBAAgC;AACvC,QAAO;EACL,OACG,kBAAkB,eAAe,UACjC,OAAO,WAAW,cAAc,OAAO,aAAa;EACvD,QACG,kBAAkB,eAAe,WACjC,OAAO,WAAW,cAAc,OAAO,cAAc;EACzD"}
+{"version":3,"file":"useViewportSize.js","names":["useEffect","useState","ViewportSize","width","height","visualViewport","window","ViewportSizeParams","isDisabled","useViewportSize","t0","$","_c","t1","undefined","params","size","setSize","_temp","t2","t3","onResize","_temp2","addEventListener","removeEventListener","size_0","newSize","getViewportSize","innerWidth","innerHeight"],"sources":["../../../src/utils/react/useViewportSize.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\ninterface ViewportSize {\n  width: number;\n  height: number;\n}\n\nlet visualViewport = typeof window !== 'undefined' && window.visualViewport;\n\nexport type ViewportSizeParams = {\n  isDisabled?: boolean;\n};\nexport function useViewportSize(params: ViewportSizeParams = {}): ViewportSize {\n  const { isDisabled } = params;\n\n  let [size, setSize] = useState(() => getViewportSize());\n\n  useEffect(() => {\n    if (isDisabled) {\n      return;\n    }\n    // Use visualViewport api to track available height even on iOS virtual keyboard opening\n    let onResize = () => {\n      setSize((size) => {\n        let newSize = getViewportSize();\n        if (newSize.width === size.width && newSize.height === size.height) {\n          return size;\n        }\n        return newSize;\n      });\n    };\n\n    if (!visualViewport) {\n      window.addEventListener('resize', onResize);\n    } else {\n      visualViewport.addEventListener('resize', onResize);\n    }\n\n    return () => {\n      if (!visualViewport) {\n        window.removeEventListener('resize', onResize);\n      } else {\n        visualViewport.removeEventListener('resize', onResize);\n      }\n    };\n  }, [isDisabled]);\n\n  return size;\n}\n\nfunction getViewportSize(): ViewportSize {\n  return {\n    width:\n      (visualViewport && visualViewport.width) ||\n      (typeof window !== 'undefined' ? window.innerWidth : 0),\n    height:\n      (visualViewport && visualViewport.height) ||\n      (typeof window !== 'undefined' ? window.innerHeight : 0),\n  };\n}\n"],"mappings":";;;;;AAOA,IAAIK,iBAAiB,OAAOC,WAAW,eAAeA,OAAOD;AAK7D,SAAOI,gBAAAC,IAAA;CAAA,MAAAC,IAAAC,EAAA,EAAA;CAAA,IAAAC;AAAA,KAAAF,EAAA,OAAAD,IAAA;AAAyBG,OAAAH,OAAAI,SAAA,EAA+B,GAA/BJ;AAA+BC,IAAA,KAAAD;AAAAC,IAAA,KAAAE;OAAAA,MAAAF,EAAA;CAC7D,MAAA,EAAAH,eAD8BK;CAG9B,MAAA,CAAAG,MAAAC,WAAsBhB,SAASiB,MAAwB;CAAC,IAAAC;CAAA,IAAAC;AAAA,KAAAT,EAAA,OAAAH,YAAA;AAE9CW,aAAA;AACR,OAAIX,WAAU;GAId,MAAAa,iBAAe;AACbJ,YAAQK,OAMN;;AAGJ,OAAI,CAACjB,eACHC,QAAMiB,iBAAkB,UAAUF,SAAS;OAE3ChB,gBAAckB,iBAAkB,UAAUF,SAAS;AACpD,gBAEM;AACL,QAAI,CAAChB,eACHC,QAAMkB,oBAAqB,UAAUH,SAAS;QAE9ChB,gBAAcmB,oBAAqB,UAAUH,SAAS;;;AAGzDD,OAAA,CAACZ,WAAW;AAAAG,IAAA,KAAAH;AAAAG,IAAA,KAAAQ;AAAAR,IAAA,KAAAS;QAAA;AAAAD,OAAAR,EAAA;AAAAS,OAAAT,EAAA;;AA5BfX,WAAUmB,IA4BPC,GAAa;AAAA,QAETJ;;AAnCF,SAAAM,OAAAG,QAAA;CAYC,MAAAC,UAAcC,iBAAiB;AAC/B,KAAID,QAAOvB,UAAWa,OAAIb,SAAUuB,QAAOtB,WAAYY,OAAIZ,OAAO,QACzDY;AACR,QACMU;;AAhBR,SAAAR,QAAA;AAAA,QAGgCS,iBAAiB;;AAmCxD,SAASA,kBAAgC;AACvC,QAAO;EACLxB,OACGE,kBAAkBA,eAAeF,UACjC,OAAOG,WAAW,cAAcA,OAAOsB,aAAa;EACvDxB,QACGC,kBAAkBA,eAAeD,WACjC,OAAOE,WAAW,cAAcA,OAAOuB,cAAc;EACzD"}

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

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

@@ -1 +1 @@
-{"version":3,"file":"wrapNodeIfPlain.js","names":[],"sources":["../../../src/utils/react/wrapNodeIfPlain.ts"],"sourcesContent":["import { isValidElement, ReactNode } from 'react';\nimport { isFragment } from 'react-is';\n\nexport function wrapNodeIfPlain(children: ReactNode, render: () => ReactNode) {\n  const childrenIsFragment =\n    children && (Array.isArray(children) || isFragment(children));\n\n  if (!children || (!childrenIsFragment && isValidElement(children))) {\n    return children;\n  }\n\n  return render();\n}\n"],"mappings":";;;;;AAGA,SAAgB,gBAAgB,UAAqB,QAAyB;CAC5E,MAAM,qBACJ,aAAa,MAAM,QAAQ,SAAS,IAAI,WAAW,SAAS;AAE9D,KAAI,CAAC,YAAa,CAAC,sBAAsB,eAAe,SAAS,CAC/D,QAAO;AAGT,QAAO,QAAQ"}
+{"version":3,"file":"wrapNodeIfPlain.js","names":["isValidElement","ReactNode","isFragment","wrapNodeIfPlain","children","render","childrenIsFragment","Array","isArray"],"sources":["../../../src/utils/react/wrapNodeIfPlain.ts"],"sourcesContent":["import { isValidElement, ReactNode } from 'react';\nimport { isFragment } from 'react-is';\n\nexport function wrapNodeIfPlain(children: ReactNode, render: () => ReactNode) {\n  const childrenIsFragment =\n    children && (Array.isArray(children) || isFragment(children));\n\n  if (!children || (!childrenIsFragment && isValidElement(children))) {\n    return children;\n  }\n\n  return render();\n}\n"],"mappings":";;;;;AAGA,SAAgBG,gBAAgBC,UAAqBC,QAAyB;CAC5E,MAAMC,qBACJF,aAAaG,MAAMC,QAAQJ,SAAS,IAAIF,WAAWE,SAAS;AAE9D,KAAI,CAACA,YAAa,CAACE,sBAAsBN,eAAeI,SAAU,CAChE,QAAOA;AAGT,QAAOC,QAAQ"}

package/dist/utils/selection.js

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

package/dist/utils/selection.js.map

@@ -1 +1 @@
-{"version":3,"file":"selection.js","names":[],"sources":["../../src/utils/selection.ts"],"sourcesContent":["import { Key } from 'react-aria';\n\n/**\n * Deduplicate/toggle keys in a selection: if a key appears twice it is\n * removed (toggled off), otherwise it is kept (selected).\n */\nexport function processSelectionArray(iterable: Iterable<Key>): string[] {\n  const resultSet = new Set<string>();\n  for (const key of iterable) {\n    const nKey = String(key);\n    if (resultSet.has(nKey)) {\n      resultSet.delete(nKey);\n    } else {\n      resultSet.add(nKey);\n    }\n  }\n  return Array.from(resultSet);\n}\n"],"mappings":";;;;;;AAMA,SAAgB,sBAAsB,UAAmC;CACvE,MAAM,4BAAY,IAAI,KAAa;AACnC,MAAK,MAAM,OAAO,UAAU;EAC1B,MAAM,OAAO,OAAO,IAAI;AACxB,MAAI,UAAU,IAAI,KAAK,CACrB,WAAU,OAAO,KAAK;MAEtB,WAAU,IAAI,KAAK;;AAGvB,QAAO,MAAM,KAAK,UAAU"}
+{"version":3,"file":"selection.js","names":["Key","processSelectionArray","iterable","Iterable","resultSet","Set","key","nKey","String","has","delete","add","Array","from"],"sources":["../../src/utils/selection.ts"],"sourcesContent":["import { Key } from 'react-aria';\n\n/**\n * Deduplicate/toggle keys in a selection: if a key appears twice it is\n * removed (toggled off), otherwise it is kept (selected).\n */\nexport function processSelectionArray(iterable: Iterable<Key>): string[] {\n  const resultSet = new Set<string>();\n  for (const key of iterable) {\n    const nKey = String(key);\n    if (resultSet.has(nKey)) {\n      resultSet.delete(nKey);\n    } else {\n      resultSet.add(nKey);\n    }\n  }\n  return Array.from(resultSet);\n}\n"],"mappings":";;;;;;AAMA,SAAgBC,sBAAsBC,UAAmC;CACvE,MAAME,4BAAY,IAAIC,KAAa;AACnC,MAAK,MAAMC,OAAOJ,UAAU;EAC1B,MAAMK,OAAOC,OAAOF,IAAI;AACxB,MAAIF,UAAUK,IAAIF,KAAK,CACrBH,WAAUM,OAAOH,KAAK;MAEtBH,WAAUO,IAAIJ,KAAK;;AAGvB,QAAOK,MAAMC,KAAKT,UAAU"}

package/dist/utils/styles.js

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

package/dist/utils/styles.js.map

@@ -1 +1 @@
-{"version":3,"file":"styles.js","names":[],"sources":["../../src/utils/styles.ts"],"sourcesContent":["import type { Styles } from '@tenphi/tasty';\n\n/**\n * Split properties into style and non-style properties.\n * Collects style-related props from `props` (based on `styleList`)\n * and merges them with `defaultStyles` and `props.styles`.\n *\n * @param props - Component prop map.\n * @param styleList - List of style property names to extract.\n * @param defaultStyles - Default style map of the component.\n * @param propMap - Props-to-style alias map (e.g. `{ bg: 'fill' }`).\n * @param ignoreList - Properties to skip during extraction.\n */\nexport function extractStyles(\n  props: object,\n  styleList: readonly string[] = [],\n  defaultStyles?: Styles,\n  propMap?: Record<string, string>,\n  ignoreList: readonly string[] = [],\n): Styles {\n  const ignoreSet = new Set(ignoreList);\n  const styleSet = new Set(styleList);\n  const record = props as Record<string, unknown>;\n\n  const styles: Styles = {\n    ...defaultStyles,\n    ...(!ignoreSet.has('styles') &&\n    record.styles &&\n    typeof record.styles === 'object'\n      ? (record.styles as Styles)\n      : undefined),\n  };\n\n  for (const prop of Object.keys(record)) {\n    if (ignoreSet.has(prop)) continue;\n\n    const styleName = propMap?.[prop] ?? prop;\n\n    if (styleSet.has(styleName)) {\n      styles[styleName] = record[prop] as Styles[keyof Styles];\n    }\n  }\n\n  return styles;\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAgB,cACd,OACA,YAA+B,EAAE,EACjC,eACA,SACA,aAAgC,EAAE,EAC1B;CACR,MAAM,YAAY,IAAI,IAAI,WAAW;CACrC,MAAM,WAAW,IAAI,IAAI,UAAU;CACnC,MAAM,SAAS;CAEf,MAAM,SAAiB;EACrB,GAAG;EACH,GAAI,CAAC,UAAU,IAAI,SAAS,IAC5B,OAAO,UACP,OAAO,OAAO,WAAW,WACpB,OAAO,SACR;EACL;AAED,MAAK,MAAM,QAAQ,OAAO,KAAK,OAAO,EAAE;AACtC,MAAI,UAAU,IAAI,KAAK,CAAE;EAEzB,MAAM,YAAY,UAAU,SAAS;AAErC,MAAI,SAAS,IAAI,UAAU,CACzB,QAAO,aAAa,OAAO;;AAI/B,QAAO"}
+{"version":3,"file":"styles.js","names":["Styles","extractStyles","props","styleList","defaultStyles","propMap","Record","ignoreList","ignoreSet","Set","styleSet","record","styles","has","undefined","prop","Object","keys","styleName"],"sources":["../../src/utils/styles.ts"],"sourcesContent":["import type { Styles } from '@tenphi/tasty';\n\n/**\n * Split properties into style and non-style properties.\n * Collects style-related props from `props` (based on `styleList`)\n * and merges them with `defaultStyles` and `props.styles`.\n *\n * @param props - Component prop map.\n * @param styleList - List of style property names to extract.\n * @param defaultStyles - Default style map of the component.\n * @param propMap - Props-to-style alias map (e.g. `{ bg: 'fill' }`).\n * @param ignoreList - Properties to skip during extraction.\n */\nexport function extractStyles(\n  props: object,\n  styleList: readonly string[] = [],\n  defaultStyles?: Styles,\n  propMap?: Record<string, string>,\n  ignoreList: readonly string[] = [],\n): Styles {\n  const ignoreSet = new Set(ignoreList);\n  const styleSet = new Set(styleList);\n  const record = props as Record<string, unknown>;\n\n  const styles: Styles = {\n    ...defaultStyles,\n    ...(!ignoreSet.has('styles') &&\n    record.styles &&\n    typeof record.styles === 'object'\n      ? (record.styles as Styles)\n      : undefined),\n  };\n\n  for (const prop of Object.keys(record)) {\n    if (ignoreSet.has(prop)) continue;\n\n    const styleName = propMap?.[prop] ?? prop;\n\n    if (styleSet.has(styleName)) {\n      styles[styleName] = record[prop] as Styles[keyof Styles];\n    }\n  }\n\n  return styles;\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAgBC,cACdC,OACAC,YAA+B,EAAE,EACjCC,eACAC,SACAE,aAAgC,EAAE,EAC1B;CACR,MAAMC,YAAY,IAAIC,IAAIF,WAAW;CACrC,MAAMG,WAAW,IAAID,IAAIN,UAAU;CACnC,MAAMQ,SAAST;CAEf,MAAMU,SAAiB;EACrB,GAAGR;EACH,GAAI,CAACI,UAAUK,IAAI,SAAS,IAC5BF,OAAOC,UACP,OAAOD,OAAOC,WAAW,WACpBD,OAAOC,SACRE;EACL;AAED,MAAK,MAAMC,QAAQC,OAAOC,KAAKN,OAAO,EAAE;AACtC,MAAIH,UAAUK,IAAIE,KAAK,CAAE;EAEzB,MAAMG,YAAYb,UAAUU,SAASA;AAErC,MAAIL,SAASG,IAAIK,UAAU,CACzBN,QAAOM,aAAaP,OAAOI;;AAI/B,QAAOH"}

package/dist/utils/tree.js

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

package/dist/utils/tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"tree.js","names":[],"sources":["../../src/utils/tree.ts"],"sourcesContent":["export function toFlatTree(tree, includingFolders) {\n  return tree.reduce((result, node) => {\n    if (!node.isLeaf) {\n      result = [\n        ...result,\n        ...(includingFolders ? [node] : []),\n        ...toFlatTree(node.children || [], includingFolders),\n      ];\n    } else {\n      result.push(node);\n    }\n    return result;\n  }, []);\n}\n"],"mappings":";;AAAA,SAAgB,WAAW,MAAM,kBAAkB;AACjD,QAAO,KAAK,QAAQ,QAAQ,SAAS;AACnC,MAAI,CAAC,KAAK,OACR,UAAS;GACP,GAAG;GACH,GAAI,mBAAmB,CAAC,KAAK,GAAG,EAAE;GAClC,GAAG,WAAW,KAAK,YAAY,EAAE,EAAE,iBAAiB;GACrD;MAED,QAAO,KAAK,KAAK;AAEnB,SAAO;IACN,EAAE,CAAC"}
+{"version":3,"file":"tree.js","names":["toFlatTree","tree","includingFolders","reduce","result","node","isLeaf","children","push"],"sources":["../../src/utils/tree.ts"],"sourcesContent":["export function toFlatTree(tree, includingFolders) {\n  return tree.reduce((result, node) => {\n    if (!node.isLeaf) {\n      result = [\n        ...result,\n        ...(includingFolders ? [node] : []),\n        ...toFlatTree(node.children || [], includingFolders),\n      ];\n    } else {\n      result.push(node);\n    }\n    return result;\n  }, []);\n}\n"],"mappings":";;AAAA,SAAgBA,WAAWC,MAAMC,kBAAkB;AACjD,QAAOD,KAAKE,QAAQC,QAAQC,SAAS;AACnC,MAAI,CAACA,KAAKC,OACRF,UAAS;GACP,GAAGA;GACH,GAAIF,mBAAmB,CAACG,KAAK,GAAG,EAAE;GAClC,GAAGL,WAAWK,KAAKE,YAAY,EAAE,EAAEL,iBAAiB;GACrD;MAEDE,QAAOI,KAAKH,KAAK;AAEnB,SAAOD;IACN,EAAE,CAAC"}

package/dist/utils/warnings.js

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

package/dist/utils/warnings.js.map

@@ -1 +1 @@
-{"version":3,"file":"warnings.js","names":[],"sources":["../../src/utils/warnings.ts"],"sourcesContent":["import { isDevEnvOrTest } from './is-dev-env';\n\nconst SUGGESTED_PROP_MAP = {\n  disabled: 'isDisabled',\n  loading: 'isLoading',\n  selected: 'isSelected',\n};\n\nconst PREFIX = 'CubeUIKit';\n\nexport function propDeprecationWarning(name, props, propList) {\n  propList.forEach((prop) => {\n    if (prop in props) {\n      const suggestion = SUGGESTED_PROP_MAP[prop];\n\n      warn(\n        `\"${prop}\" property of \"${name}\" component is deprecated.${\n          suggestion ? ` Use \"${suggestion}\" property instead.` : ''\n        }`,\n      );\n    }\n  });\n}\n\nexport function warn(...args) {\n  if (isDevEnvOrTest()) {\n    console.warn(`${PREFIX}:`, ...args);\n  }\n}\n\nexport function deprecationWarning(\n  condition: any,\n  {\n    property,\n    name,\n    betterAlternative,\n    reason,\n  }: {\n    property: string;\n    name: string;\n    betterAlternative: (() => string) | string;\n    reason?: (() => string) | string;\n  },\n) {\n  if (condition) return;\n\n  if (!isDevEnvOrTest()) return;\n\n  // we can make deprecations even better if we add the md syntax in the console.\n  // anyway, everything down below will be stripped in the production build\n  console.group(`⚠️ ${PREFIX}: Deprecation in ${name}`);\n  warn(\n    `\"${property}\" is deprecated, consider better alternative: ${\n      typeof betterAlternative === 'function'\n        ? (betterAlternative as () => string)()\n        : betterAlternative\n    }`,\n  );\n  reason &&\n    warn(\n      `Reason: ${\n        typeof reason === 'function' ? (reason as () => string)() : reason\n      }`,\n    );\n  console.groupEnd();\n}\n"],"mappings":";;;;AAEA,MAAM,qBAAqB;CACzB,UAAU;CACV,SAAS;CACT,UAAU;CACX;AAED,MAAM,SAAS;AAEf,SAAgB,uBAAuB,MAAM,OAAO,UAAU;AAC5D,UAAS,SAAS,SAAS;AACzB,MAAI,QAAQ,OAAO;GACjB,MAAM,aAAa,mBAAmB;AAEtC,QACE,IAAI,KAAK,iBAAiB,KAAK,4BAC7B,aAAa,SAAS,WAAW,uBAAuB,KAE3D;;GAEH;;AAGJ,SAAgB,KAAK,GAAG,MAAM;AAC5B,KAAI,gBAAgB,CAClB,SAAQ,KAAK,GAAG,OAAO,IAAI,GAAG,KAAK;;AAIvC,SAAgB,mBACd,WACA,EACE,UACA,MACA,mBACA,UAOF;AACA,KAAI,UAAW;AAEf,KAAI,CAAC,gBAAgB,CAAE;AAIvB,SAAQ,MAAM,MAAM,OAAO,mBAAmB,OAAO;AACrD,MACE,IAAI,SAAS,gDACX,OAAO,sBAAsB,aACxB,mBAAoC,GACrC,oBAEP;AACD,WACE,KACE,WACE,OAAO,WAAW,aAAc,QAAyB,GAAG,SAE/D;AACH,SAAQ,UAAU"}
+{"version":3,"file":"warnings.js","names":["isDevEnvOrTest","SUGGESTED_PROP_MAP","disabled","loading","selected","PREFIX","propDeprecationWarning","name","props","propList","forEach","prop","suggestion","warn","args","console","deprecationWarning","condition","property","betterAlternative","reason","group","groupEnd"],"sources":["../../src/utils/warnings.ts"],"sourcesContent":["import { isDevEnvOrTest } from './is-dev-env';\n\nconst SUGGESTED_PROP_MAP = {\n  disabled: 'isDisabled',\n  loading: 'isLoading',\n  selected: 'isSelected',\n};\n\nconst PREFIX = 'CubeUIKit';\n\nexport function propDeprecationWarning(name, props, propList) {\n  propList.forEach((prop) => {\n    if (prop in props) {\n      const suggestion = SUGGESTED_PROP_MAP[prop];\n\n      warn(\n        `\"${prop}\" property of \"${name}\" component is deprecated.${\n          suggestion ? ` Use \"${suggestion}\" property instead.` : ''\n        }`,\n      );\n    }\n  });\n}\n\nexport function warn(...args) {\n  if (isDevEnvOrTest()) {\n    console.warn(`${PREFIX}:`, ...args);\n  }\n}\n\nexport function deprecationWarning(\n  condition: any,\n  {\n    property,\n    name,\n    betterAlternative,\n    reason,\n  }: {\n    property: string;\n    name: string;\n    betterAlternative: (() => string) | string;\n    reason?: (() => string) | string;\n  },\n) {\n  if (condition) return;\n\n  if (!isDevEnvOrTest()) return;\n\n  // we can make deprecations even better if we add the md syntax in the console.\n  // anyway, everything down below will be stripped in the production build\n  console.group(`⚠️ ${PREFIX}: Deprecation in ${name}`);\n  warn(\n    `\"${property}\" is deprecated, consider better alternative: ${\n      typeof betterAlternative === 'function'\n        ? (betterAlternative as () => string)()\n        : betterAlternative\n    }`,\n  );\n  reason &&\n    warn(\n      `Reason: ${\n        typeof reason === 'function' ? (reason as () => string)() : reason\n      }`,\n    );\n  console.groupEnd();\n}\n"],"mappings":";;;;AAEA,MAAMC,qBAAqB;CACzBC,UAAU;CACVC,SAAS;CACTC,UAAU;CACX;AAED,MAAMC,SAAS;AAEf,SAAgBC,uBAAuBC,MAAMC,OAAOC,UAAU;AAC5DA,UAASC,SAASC,SAAS;AACzB,MAAIA,QAAQH,OAAO;GACjB,MAAMI,aAAaX,mBAAmBU;AAEtCE,QACE,IAAIF,KAAI,iBAAkBJ,KAAI,4BAC5BK,aAAa,SAASA,WAAU,uBAAwB,KAE3D;;GAEH;;AAGJ,SAAgBC,KAAK,GAAGC,MAAM;AAC5B,KAAId,gBAAgB,CAClBe,SAAQF,KAAK,GAAGR,OAAM,IAAK,GAAGS,KAAK;;AAIvC,SAAgBE,mBACdC,WACA,EACEC,UACAX,MACAY,mBACAC,UAOF;AACA,KAAIH,UAAW;AAEf,KAAI,CAACjB,gBAAgB,CAAE;AAIvBe,SAAQM,MAAM,MAAMhB,OAAM,mBAAoBE,OAAO;AACrDM,MACE,IAAIK,SAAQ,gDACV,OAAOC,sBAAsB,aACxBA,mBAAoC,GACrCA,oBAEP;AACDC,WACEP,KACE,WACE,OAAOO,WAAW,aAAcA,QAAyB,GAAGA,SAE/D;AACHL,SAAQO,UAAU"}

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.181.0";
+const VERSION = "0.183.0";
 const TASTY_VERSION = "3.9.2";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","names":[],"sources":["../src/version.ts"],"sourcesContent":["declare global {\n  interface Window {\n    CubeUIKit: {\n      version: string;\n      tastyVersion: string;\n    };\n  }\n\n  /** Replaced at build time by tsdown `define` */\n  const __UIKIT_VERSION__: string;\n  /** Replaced at build time by tsdown `define` */\n  const __TASTY_VERSION__: string;\n}\n\n// eslint-disable-next-line no-undef -- replaced at build time by tsdown `define`\nexport const VERSION: string = __UIKIT_VERSION__;\n// eslint-disable-next-line no-undef -- replaced at build time by tsdown `define`\nexport const TASTY_VERSION: string = __TASTY_VERSION__;\n\nif (typeof window !== 'undefined') {\n  const version = VERSION;\n  const tastyVersion = TASTY_VERSION;\n\n  // Ensure CubeUIKit is defined on window in a way bundlers recognize\n  window.CubeUIKit = window.CubeUIKit || { version, tastyVersion };\n\n  // Check for multiple versions\n  if (window.CubeUIKit.version && window.CubeUIKit.version !== version) {\n    console.error('More than one version of CubeUIKit is loaded', {\n      loadedVersions: [window.CubeUIKit.version, version],\n    });\n  } else {\n    window.CubeUIKit.version = version;\n    window.CubeUIKit.tastyVersion = tastyVersion;\n  }\n}\n"],"mappings":";;AAeA,MAAa;AAEb,MAAa;AAEb,IAAI,OAAO,WAAW,aAAa;CACjC,MAAM,UAAU;CAChB,MAAM,eAAe;AAGrB,QAAO,YAAY,OAAO,aAAa;EAAE;EAAS;EAAc;AAGhE,KAAI,OAAO,UAAU,WAAW,OAAO,UAAU,YAAY,QAC3D,SAAQ,MAAM,gDAAgD,EAC5D,gBAAgB,CAAC,OAAO,UAAU,SAAS,QAAQ,EACpD,CAAC;MACG;AACL,SAAO,UAAU,UAAU;AAC3B,SAAO,UAAU,eAAe"}
+{"version":3,"file":"version.js","names":["global","Window","CubeUIKit","version","tastyVersion","__UIKIT_VERSION__","__TASTY_VERSION__","VERSION","TASTY_VERSION","window","console","error","loadedVersions"],"sources":["../src/version.ts"],"sourcesContent":["declare global {\n  interface Window {\n    CubeUIKit: {\n      version: string;\n      tastyVersion: string;\n    };\n  }\n\n  /** Replaced at build time by tsdown `define` */\n  const __UIKIT_VERSION__: string;\n  /** Replaced at build time by tsdown `define` */\n  const __TASTY_VERSION__: string;\n}\n\n// eslint-disable-next-line no-undef -- replaced at build time by tsdown `define`\nexport const VERSION: string = __UIKIT_VERSION__;\n// eslint-disable-next-line no-undef -- replaced at build time by tsdown `define`\nexport const TASTY_VERSION: string = __TASTY_VERSION__;\n\nif (typeof window !== 'undefined') {\n  const version = VERSION;\n  const tastyVersion = TASTY_VERSION;\n\n  // Ensure CubeUIKit is defined on window in a way bundlers recognize\n  window.CubeUIKit = window.CubeUIKit || { version, tastyVersion };\n\n  // Check for multiple versions\n  if (window.CubeUIKit.version && window.CubeUIKit.version !== version) {\n    console.error('More than one version of CubeUIKit is loaded', {\n      loadedVersions: [window.CubeUIKit.version, version],\n    });\n  } else {\n    window.CubeUIKit.version = version;\n    window.CubeUIKit.tastyVersion = tastyVersion;\n  }\n}\n"],"mappings":";;AAeA,MAAaO;AAEb,MAAaC;AAEb,IAAI,OAAOC,WAAW,aAAa;CACjC,MAAMN,UAAUI;CAChB,MAAMH,eAAeI;AAGrBC,QAAOP,YAAYO,OAAOP,aAAa;EAAEC;EAASC;EAAc;AAGhE,KAAIK,OAAOP,UAAUC,WAAWM,OAAOP,UAAUC,YAAYA,QAC3DO,SAAQC,MAAM,gDAAgD,EAC5DC,gBAAgB,CAACH,OAAOP,UAAUC,SAASA,QAAO,EACnD,CAAC;MACG;AACLM,SAAOP,UAAUC,UAAUA;AAC3BM,SAAOP,UAAUE,eAAeA"}

package/docs/Usage.md

@@ -11,6 +11,12 @@ For styling engine internals see the [Tasty documentation](./tasty/usage.md). Ta
 - **injector.md** — Low-level style injector: `inject()`, `injectGlobal()`, deduplication, SSR.
 - **tasty-static.md** — Zero-runtime `tastyStatic()`, Babel plugin, Next.js/Vite integration.
 
+## React Compiler
+
+UI Kit ships components optimized with React Compiler and supports React 18 and 19. Your application does not need to enable Compiler to use this build. Adoption is incremental: functions with known compatibility diagnostics remain unoptimized, and the legacy form's mutable render paths are explicitly excluded.
+
+Compiling UI Kit does not make mutable legacy form reads in your application reactive. When enabling Compiler in an application, migrate those consumers to the modern Form subscriptions (`Form.useValue`, `Form.useSelector`, or `Form.Subscribe`) or keep the affected consumer components uncompiled with `"use no memo"`. Forms without an explicit instance still use the legacy implementation.
+
 ## Units
 
 Tasty provides custom units that map to CSS custom properties defined on the Root component. Use these instead of raw pixel values to keep styling consistent.
@@ -456,6 +462,8 @@ DataTable also accepts nested column definitions for already-shaped pivot result
 
 ## Form System
 
+UI Kit provides modern and legacy implementations. **Use the modern API for new forms.** Existing callers remain on the legacy implementation until explicitly migrated.
+
 ### Modern forms
 
 For a new modern form, create a typed controller, put defaults on the controller, and bind inputs with `name`. Modern names accept strings and nested tuples; `field` is an optional typed binding:
@@ -478,7 +486,7 @@ Inputs subscribe to their own values and errors. For other reactive UI, use `For
 
 ### Legacy forms
 
-`Form.useForm()` and roots without a modern controller keep the legacy backend. `DialogForm` and `Form.Item` still use this contract. See [Form](./components/form/Form.md) and [FormInstance](./components/form/FormInstance.md) for legacy instance methods, defaults, and dot notation.
+`Form.useForm()` and roots without a modern controller keep the legacy backend. `DialogForm` also supports modern controllers; `Form.Item` remains legacy-only. See [FormInstance (legacy)](./components/form/FormInstance.md) for legacy instance methods, defaults, and dot notation.
 
 ### Shared field integration
 

package/docs/components/actions/Button.md

@@ -227,7 +227,7 @@ A disabled button keeps showing its tooltip. Browsers stop dispatching mouse eve
 ### ARIA Properties
 
 - `aria-label`, `aria-labelledby` – Accessible name.
-- `aria-pressed` – Managed automatically when `isSelected` is used.
+- `aria-pressed` – Derived from `isSelected`. Not emitted when the button renders as a link (`to`) or when the call site sets its own `role` — a button acting as a tab or an option wants `aria-selected` / `aria-current` instead. An explicit `aria-pressed` always wins.
 - `aria-disabled` – Announces the disabled state whenever the native `disabled` attribute cannot be used: on links, and on buttons that carry a tooltip.
 - Additional ARIA attributes supported by React Aria's `useButton`.
 

package/docs/components/content/InlineInput.md

@@ -12,7 +12,7 @@ Unlike `TextInput`, `InlineInput` is intentionally **not** a form field. It mana
 
 ## When Not to Use
 
-- **Form fields**: Use `TextInput` (with `<Form>` + `Field`) for inputs that need validation rules
+- **Form fields**: Use `TextInput` with a modern `<Form form={form}>` for inputs that need validation rules
 - **Multi-line text**: Single-line only in this version (multiline planned)
 - **Complex inputs**: Use a proper input component when you need masks, prefixes/suffixes, or rich validation
 

package/docs/components/content/Item.md

@@ -70,6 +70,25 @@ These properties allow direct style application without using the `styles` prop:
 - **Color:** `color`, `fill`, `fade`, `image`
 - **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
+### Spacing Tokens
+
+`Item` lays its slots out on a grid with no gap, and `Label` drops its own inline padding whenever there is start or end content. A `prefix` or `suffix` therefore renders flush against the label by default, which is what most content wants — a checkbox, a kbd chip, a badge and a count are all boxes that already carry their own presence, and a gap on top of one reads as too much.
+
+A **bare glyph** is the case that needs spacing: it sits flush, while the same glyph in the `icon` slot looks spaced because that slot centres it inside a `$size`-wide square. Two tokens control it, both `0` by default:
+
+| Token         | Controls                                        |
+| ------------- | ----------------------------------------------- |
+| `$prefix-gap` | Space between the `Prefix` slot and the `Label` |
+| `$suffix-gap` | Space between the `Label` and the `Suffix` slot |
+
+```jsx
+<Item styles={{ '$prefix-gap': '1x' }} prefix={<MemberIcon />}>
+  Revenue
+</Item>
+```
+
+Set them on the item rather than overriding `Prefix` / `Suffix` padding directly — those slots carry state maps that drop the outer gutter next to an icon or an actions run, and a flat `padding` override silently replaces them.
+
 ### Modifiers
 
 The `mods` property accepts the following modifiers:

package/docs/components/fields/ColorInput.md

@@ -153,14 +153,19 @@ const [color, setColor] = useState('#7a4dbf');
 ### Inside a form
 
 ```jsx
-<Form onSubmit={onSubmit}>
-  <ColorInput
-    name="accent"
-    label="Accent color"
-    format="oklch"
-    rules={[{ required: true, message: 'Pick an accent color' }]}
-  />
-</Form>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form} onSubmit={onSubmit}>
+      <ColorInput
+        name="accent"
+        label="Accent color"
+        format="oklch"
+        rules={[{ required: true, message: 'Pick an accent color' }]}
+      />
+    </Form>
+  );
+}
 ```
 
 ### Opening on a specific space

package/docs/components/fields/ColorPicker.md

@@ -125,14 +125,19 @@ Give it an `aria-label` when you do: with no visible text, that is the only thin
 ### Inside a form
 
 ```jsx
-<Form onSubmit={onSubmit}>
-  <ColorPicker
-    name="accent"
-    label="Accent color"
-    format="oklch"
-    rules={[{ required: true, message: 'Pick an accent color' }]}
-  />
-</Form>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form} onSubmit={onSubmit}>
+      <ColorPicker
+        name="accent"
+        label="Accent color"
+        format="oklch"
+        rules={[{ required: true, message: 'Pick an accent color' }]}
+      />
+    </Form>
+  );
+}
 ```
 
 ## Accessibility

package/docs/components/fields/ComboBox.md

@@ -663,18 +663,22 @@ This component supports all [Field properties](../../FieldProperties.md) when us
 ### Form Example
 
 ```jsx
-<Form>
-  <ComboBox
-    name="country"
-    label="Country"
-    isRequired
-    validationBehavior="native"
-  >
-    <ComboBox.Item key="us">United States</ComboBox.Item>
-    <ComboBox.Item key="uk">United Kingdom</ComboBox.Item>
-    <ComboBox.Item key="ca">Canada</ComboBox.Item>
-  </ComboBox>
-</Form>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form}>
+      <ComboBox
+        name="country"
+        label="Country"
+        isRequired
+      >
+        <ComboBox.Item key="us">United States</ComboBox.Item>
+        <ComboBox.Item key="uk">United Kingdom</ComboBox.Item>
+        <ComboBox.Item key="ca">Canada</ComboBox.Item>
+      </ComboBox>
+    </Form>
+  );
+}
 ```
 
 ## Suggested Improvements

package/docs/components/fields/CommandTextArea.md

@@ -25,7 +25,9 @@ Choose a different component when the interaction has another outcome:
 - **`items`** `Iterable<T>` — Data-driven option source (alternative to JSX children).
 - **`children`** `ReactNode | ((item) => ReactElement)` — Static items or a render function (same shape as `ComboBox` / `ListBox`).
 - **`filter`** `(textValue, query) => boolean | false` — Custom filter. Pass `false` to disable internal filtering (e.g. server-side).
-- **`onCommand`** `(key, item) => void` — Fired when the user picks a command. The option's `textValue` is inserted into the textarea regardless.
+- **`onCommand`** `(key, item) => void` — Fired when the user picks a command. The option's `textValue` is inserted into the textarea regardless. `item.start` / `item.end` locate the insertion in the value passed to `onChange`, so a consumer can anchor its own record to the pick instead of searching the new value for the inserted text.
+- **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the suggestion popover opens or closes. Use it when the field needs its own `Enter` behaviour: `onKeyDown` runs before the component's own handling, so this is how you tell "pick the focused option" from "submit".
+- **`onActiveTokenChange`** `(token: ActiveToken | null) => void` — Fired when the active trigger token changes, with the component's own caret-aware scan result. `null` once the caret leaves a token.
 - **`insertSpaceAfter`** `boolean` (default: `true`) — Insert a trailing space after the chosen command.
 - **`disabledKeys`** `Iterable<Key>` — Keys of disabled options.
 - **`direction`** `'top' | 'bottom'` (default: `'top'`) — Popover placement. Chat inputs usually want `top`.

package/docs/components/fields/FilterListBox.md

@@ -535,25 +535,30 @@ const categories = [
 This component supports all [Field properties](../../FieldProperties.md) when used within a Form. The component automatically handles form validation, field states, and integrates with form submission.
 
 ```jsx
-<Form onSubmit={handleSubmit}>
-  <FilterListBox
-    name="skills"
-    label="Technical Skills"
-    isRequired
-    selectionMode="multiple"
-    searchPlaceholder="Search skills..."
-    rules={[{ required: true, min: 2 }]}
-  >
-    <FilterListBox.Section title="Frontend">
-      <FilterListBox.Item key="react">React</FilterListBox.Item>
-      <FilterListBox.Item key="vue">Vue.js</FilterListBox.Item>
-    </FilterListBox.Section>
-    <FilterListBox.Section title="Backend">
-      <FilterListBox.Item key="nodejs">Node.js</FilterListBox.Item>
-      <FilterListBox.Item key="python">Python</FilterListBox.Item>
-    </FilterListBox.Section>
-  </FilterListBox>
-</Form>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form} onSubmit={handleSubmit}>
+      <FilterListBox
+        name="skills"
+        label="Technical Skills"
+        isRequired
+        selectionMode="multiple"
+        searchPlaceholder="Search skills..."
+        rules={[{ required: true, min: 2 }]}
+      >
+        <FilterListBox.Section title="Frontend">
+          <FilterListBox.Item key="react">React</FilterListBox.Item>
+          <FilterListBox.Item key="vue">Vue.js</FilterListBox.Item>
+        </FilterListBox.Section>
+        <FilterListBox.Section title="Backend">
+          <FilterListBox.Item key="nodejs">Node.js</FilterListBox.Item>
+          <FilterListBox.Item key="python">Python</FilterListBox.Item>
+        </FilterListBox.Section>
+      </FilterListBox>
+    </Form>
+  );
+}
 ```
 
 ## Advanced Features

package/docs/components/fields/FilterPicker.md

@@ -31,6 +31,7 @@ Choose a different component when the interaction has another shape:
 - **`selectionMode`** `'single' | 'multiple'` (default: `single`) — Selection mode for the picker
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether to allow entering custom values that are not present in the predefined options
 - **`isClearable`** `boolean` (default: `false`) — Whether the filter picker is clearable using a clear button in the rightIcon slot
+- **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
 - **`isLoadingItems`** `boolean` (default: `false`) — Whether items are currently loading. Shows a loading spinner in the search input suffix inside the popover. Unlike `isLoading`, does not disable the trigger.
 - **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection. In single selection mode, re-selecting the current item becomes a no-op: `onSelectionChange` is not fired and the popover closes
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
@@ -692,25 +693,30 @@ const [keyOrder, setKeyOrder] = useState([
 This component supports all [Field properties](../../FieldProperties.md) when used within a Form. The component automatically handles form validation, field states, and integrates with form submission.
 
 ```jsx
-<Form onSubmit={handleSubmit}>
-  <FilterPicker
-    name="categories"
-    label="Product Categories"
-    isRequired
-    selectionMode="multiple"
-    placeholder="Select categories..."
-    rules={[{ required: true }]}
-  >
-    <FilterPicker.Section title="Electronics">
-      <FilterPicker.Item key="phones">Phones</FilterPicker.Item>
-      <FilterPicker.Item key="laptops">Laptops</FilterPicker.Item>
-    </FilterPicker.Section>
-    <FilterPicker.Section title="Clothing">
-      <FilterPicker.Item key="shirts">Shirts</FilterPicker.Item>
-      <FilterPicker.Item key="pants">Pants</FilterPicker.Item>
-    </FilterPicker.Section>
-  </FilterPicker>
-</Form>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form} onSubmit={handleSubmit}>
+      <FilterPicker
+        name="categories"
+        label="Product Categories"
+        isRequired
+        selectionMode="multiple"
+        placeholder="Select categories..."
+        rules={[{ required: true }]}
+      >
+        <FilterPicker.Section title="Electronics">
+          <FilterPicker.Item key="phones">Phones</FilterPicker.Item>
+          <FilterPicker.Item key="laptops">Laptops</FilterPicker.Item>
+        </FilterPicker.Section>
+        <FilterPicker.Section title="Clothing">
+          <FilterPicker.Item key="shirts">Shirts</FilterPicker.Item>
+          <FilterPicker.Item key="pants">Pants</FilterPicker.Item>
+        </FilterPicker.Section>
+      </FilterPicker>
+    </Form>
+  );
+}
 ```
 
 ## Advanced Features