@cube-dev/ui-kit 0.201.0 → 0.203.0

package/dist/utils/react/overlayKeyPropagation.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 //#region src/utils/react/overlayKeyPropagation.ts
 /**
 * Keys whose final handling belongs to the overlay around a control, not to
@@ -20,11 +20,9 @@ const OVERLAY_KEYS = /* @__PURE__ */ new Set(["Escape", "Tab"]);
 * is opposite between them:
 *
 * - Wrapped by `useKeyboard`, the event is augmented and propagation is
-*   stopped unless the handler opts out. `createEventHandler` also keeps that
-*   decision for the LIFE of the handler rather than per event — nothing
-*   resets it when the next key arrives — so an earlier opt-out would keep
-*   releasing later keys until a render replaced the handler. Re-asserting the
-*   default here is what keeps the opt-out from outliving its own event.
+*   stopped after the handler unless it opts out, decided per event. A
+*   handler that already opted out keeps every key except `Escape` and `Tab`
+*   contained here all the same, by re-asserting the stop.
 * - Spread straight onto an element, the event is an ordinary React one and
 *   propagation is the default, so containment is what has to be asked for.
 *
@@ -40,7 +38,46 @@ function allowOverlayKeysToPropagate(event) {
 	}
 	if (!isOverlayKey) event.stopPropagation();
 }
+/**
+* Where `Escape` and `Tab` go from a field a user types into, once the field
+* and its caller's `onKeyDown` have both seen the key: a prevented one stops
+* at the field, any other goes on to the overlay around it. Other keys are
+* left as they are.
+*
+* Prevention is the signal because that is how the overlay reads it too: a
+* Dialog stays open on a prevented `Escape` (`useOverlayEscapeGuard`). React
+* Aria's `FocusScope` does not: it moves focus on every `Tab` that reaches it
+* and ignores `defaultPrevented`, so a `Tab` a field or caller takes over has
+* to stop here or focus moves anyway.
+*
+* Shape-aware like `allowOverlayKeysToPropagate`: an event wrapped by
+* `useKeyboard` stops unless released, a plain one travels unless stopped.
+* A key an IME is composing with is left as it is: it cancels or confirms
+* the composition, and the overlay ignores it anyway. That is `isComposing`
+* alone. The key Safari fires as a composition ends (`keyCode` 229,
+* `isComposing` false) is an ordinary key to the overlay, so it follows the
+* rule too, even in a field that skips it for its own key handling.
+*/
+function settleOverlayKey(event) {
+	if (!OVERLAY_KEYS.has(event.key) || event.nativeEvent.isComposing) return;
+	const isAugmented = typeof event.continuePropagation === "function";
+	if (!event.isDefaultPrevented()) {
+		if (isAugmented) event.continuePropagation();
+	} else if (!isAugmented || event.isPropagationStopped?.() === false) event.stopPropagation();
+}
+/**
+* A text field's `onKeyDown`, followed by `settleOverlayKey`. Without a
+* handler there is nothing to wrap: React Aria then leaves every key to
+* propagate, `Escape` and `Tab` included.
+*/
+function withOverlayKeys(onKeyDown) {
+	if (!onKeyDown) return void 0;
+	return (event) => {
+		onKeyDown(event);
+		settleOverlayKey(event);
+	};
+}
 //#endregion
-export { allowOverlayKeysToPropagate };
+export { OVERLAY_KEYS, allowOverlayKeysToPropagate, settleOverlayKey, withOverlayKeys };
 
 //# sourceMappingURL=overlayKeyPropagation.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"overlayKeyPropagation.js","names":["KeyboardEvent","MaybeAugmentedKeyboardEvent","continuePropagation","isPropagationStopped","OVERLAY_KEYS","Set","allowOverlayKeysToPropagate","event","isOverlayKey","has","key","stopPropagation"],"sources":["../../../src/utils/react/overlayKeyPropagation.ts"],"sourcesContent":["import type { KeyboardEvent } from 'react';\n\n/**\n * A key event as it reaches a handler that may or may not have been wrapped by\n * React Aria's `useKeyboard`.\n */\ntype MaybeAugmentedKeyboardEvent = KeyboardEvent<any> & {\n  continuePropagation?: () => void;\n  isPropagationStopped?: () => boolean;\n};\n\n/**\n * Keys whose final handling belongs to the overlay around a control, not to\n * the control. `Escape` dismisses it (CUB-4839). `Tab` is how its `FocusScope`\n * keeps focus inside: React Aria contains focus from a `keydown` listener on\n * the document, so a `Tab` held here left a Dialog's first or last control\n * unable to wrap (CUB-5603).\n */\nconst OVERLAY_KEYS = new Set(['Escape', 'Tab']);\n\n/**\n * Let `Escape` and `Tab` keep travelling out of a trigger or list, and hold\n * every other key exactly as before.\n *\n * Every other key stays contained: releasing them too would let `Enter` and\n * typeahead reach ancestor shortcuts and form submits, which callers have\n * always had held here.\n *\n * Shape-aware because the same `onKeyDown` is reached two ways and the DEFAULT\n * is opposite between them:\n *\n * - Wrapped by `useKeyboard`, the event is augmented and propagation is\n *   stopped unless the handler opts out. `createEventHandler` also keeps that\n *   decision for the LIFE of the handler rather than per event — nothing\n *   resets it when the next key arrives — so an earlier opt-out would keep\n *   releasing later keys until a render replaced the handler. Re-asserting the\n *   default here is what keeps the opt-out from outliving its own event.\n * - Spread straight onto an element, the event is an ordinary React one and\n *   propagation is the default, so containment is what has to be asked for.\n *\n * Getting this backwards is silent in one direction and loud in the other:\n * calling `stopPropagation()` on a plain event really does stop it.\n */\nexport function allowOverlayKeysToPropagate(\n  event: MaybeAugmentedKeyboardEvent,\n) {\n  const isOverlayKey = OVERLAY_KEYS.has(event.key);\n\n  if (typeof event.continuePropagation === 'function') {\n    if (isOverlayKey) {\n      event.continuePropagation();\n    } else if (event.isPropagationStopped?.() === false) {\n      // Only ever called when the flag is already clear, which is the one case\n      // `stopPropagation` does not warn about.\n      event.stopPropagation();\n    }\n\n    return;\n  }\n\n  if (!isOverlayKey) event.stopPropagation();\n}\n"],"mappings":";;;;;;;;;AAkBA,MAAMI,+BAAe,IAAIC,IAAI,CAAC,UAAU,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyB9C,SAAgBC,4BACdC,OACA;CACA,MAAMC,eAAeJ,aAAaK,IAAIF,MAAMG,GAAG;CAE/C,IAAI,OAAOH,MAAML,wBAAwB,YAAY;EACnD,IAAIM,cACFD,MAAML,oBAAoB;OACrB,IAAIK,MAAMJ,uBAAuB,MAAM,OAG5CI,MAAMI,gBAAgB;EAGxB;CACF;CAEA,IAAI,CAACH,cAAcD,MAAMI,gBAAgB;AAC3C"}
+{"version":3,"file":"overlayKeyPropagation.js","names":["KeyboardEvent","MaybeAugmentedKeyboardEvent","continuePropagation","isPropagationStopped","OVERLAY_KEYS","Set","allowOverlayKeysToPropagate","event","isOverlayKey","has","key","stopPropagation","settleOverlayKey","nativeEvent","isComposing","isAugmented","isDefaultPrevented","withOverlayKeys","onKeyDown","E","undefined"],"sources":["../../../src/utils/react/overlayKeyPropagation.ts"],"sourcesContent":["import type { KeyboardEvent } from 'react';\n\n/**\n * A key event as it reaches a handler that may or may not have been wrapped by\n * React Aria's `useKeyboard`.\n */\ntype MaybeAugmentedKeyboardEvent = KeyboardEvent<any> & {\n  continuePropagation?: () => void;\n  isPropagationStopped?: () => boolean;\n};\n\n/**\n * Keys whose final handling belongs to the overlay around a control, not to\n * the control. `Escape` dismisses it (CUB-4839). `Tab` is how its `FocusScope`\n * keeps focus inside: React Aria contains focus from a `keydown` listener on\n * the document, so a `Tab` held here left a Dialog's first or last control\n * unable to wrap (CUB-5603).\n */\nexport const OVERLAY_KEYS = new Set(['Escape', 'Tab']);\n\n/**\n * Let `Escape` and `Tab` keep travelling out of a trigger or list, and hold\n * every other key exactly as before.\n *\n * Every other key stays contained: releasing them too would let `Enter` and\n * typeahead reach ancestor shortcuts and form submits, which callers have\n * always had held here.\n *\n * Shape-aware because the same `onKeyDown` is reached two ways and the DEFAULT\n * is opposite between them:\n *\n * - Wrapped by `useKeyboard`, the event is augmented and propagation is\n *   stopped after the handler unless it opts out, decided per event. A\n *   handler that already opted out keeps every key except `Escape` and `Tab`\n *   contained here all the same, by re-asserting the stop.\n * - Spread straight onto an element, the event is an ordinary React one and\n *   propagation is the default, so containment is what has to be asked for.\n *\n * Getting this backwards is silent in one direction and loud in the other:\n * calling `stopPropagation()` on a plain event really does stop it.\n */\nexport function allowOverlayKeysToPropagate(\n  event: MaybeAugmentedKeyboardEvent,\n) {\n  const isOverlayKey = OVERLAY_KEYS.has(event.key);\n\n  if (typeof event.continuePropagation === 'function') {\n    if (isOverlayKey) {\n      event.continuePropagation();\n    } else if (event.isPropagationStopped?.() === false) {\n      // Only ever called when the flag is already clear, which is the one case\n      // `stopPropagation` does not warn about.\n      event.stopPropagation();\n    }\n\n    return;\n  }\n\n  if (!isOverlayKey) event.stopPropagation();\n}\n\n/**\n * Where `Escape` and `Tab` go from a field a user types into, once the field\n * and its caller's `onKeyDown` have both seen the key: a prevented one stops\n * at the field, any other goes on to the overlay around it. Other keys are\n * left as they are.\n *\n * Prevention is the signal because that is how the overlay reads it too: a\n * Dialog stays open on a prevented `Escape` (`useOverlayEscapeGuard`). React\n * Aria's `FocusScope` does not: it moves focus on every `Tab` that reaches it\n * and ignores `defaultPrevented`, so a `Tab` a field or caller takes over has\n * to stop here or focus moves anyway.\n *\n * Shape-aware like `allowOverlayKeysToPropagate`: an event wrapped by\n * `useKeyboard` stops unless released, a plain one travels unless stopped.\n * A key an IME is composing with is left as it is: it cancels or confirms\n * the composition, and the overlay ignores it anyway. That is `isComposing`\n * alone. The key Safari fires as a composition ends (`keyCode` 229,\n * `isComposing` false) is an ordinary key to the overlay, so it follows the\n * rule too, even in a field that skips it for its own key handling.\n */\nexport function settleOverlayKey(event: MaybeAugmentedKeyboardEvent) {\n  if (!OVERLAY_KEYS.has(event.key) || event.nativeEvent.isComposing) return;\n\n  const isAugmented = typeof event.continuePropagation === 'function';\n\n  if (!event.isDefaultPrevented()) {\n    if (isAugmented) event.continuePropagation!();\n  } else if (!isAugmented || event.isPropagationStopped?.() === false) {\n    // Only when the flag is clear, the one case `stopPropagation` does not\n    // warn about on a wrapped event.\n    event.stopPropagation();\n  }\n}\n\n/**\n * A text field's `onKeyDown`, followed by `settleOverlayKey`. Without a\n * handler there is nothing to wrap: React Aria then leaves every key to\n * propagate, `Escape` and `Tab` included.\n */\nexport function withOverlayKeys<E extends MaybeAugmentedKeyboardEvent>(\n  onKeyDown: ((event: E) => void) | undefined,\n) {\n  if (!onKeyDown) return undefined;\n\n  return (event: E) => {\n    onKeyDown(event);\n    settleOverlayKey(event);\n  };\n}\n"],"mappings":";;;;;;;;;AAkBA,MAAaI,+BAAe,IAAIC,IAAI,CAAC,UAAU,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;AAuBrD,SAAgBC,4BACdC,OACA;CACA,MAAMC,eAAeJ,aAAaK,IAAIF,MAAMG,GAAG;CAE/C,IAAI,OAAOH,MAAML,wBAAwB,YAAY;EACnD,IAAIM,cACFD,MAAML,oBAAoB;OACrB,IAAIK,MAAMJ,uBAAuB,MAAM,OAG5CI,MAAMI,gBAAgB;EAGxB;CACF;CAEA,IAAI,CAACH,cAAcD,MAAMI,gBAAgB;AAC3C;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgBC,iBAAiBL,OAAoC;CACnE,IAAI,CAACH,aAAaK,IAAIF,MAAMG,GAAG,KAAKH,MAAMM,YAAYC,aAAa;CAEnE,MAAMC,cAAc,OAAOR,MAAML,wBAAwB;CAEzD,IAAI,CAACK,MAAMS,mBAAmB,GACxBD;MAAAA,aAAaR,MAAML,oBAAqB;CAAA,OACvC,IAAI,CAACa,eAAeR,MAAMJ,uBAAuB,MAAM,OAG5DI,MAAMI,gBAAgB;AAE1B;;;;;;AAOA,SAAgBM,gBACdC,WACA;CACA,IAAI,CAACA,WAAW,OAAOE,KAAAA;CAEvB,QAAQb,UAAa;EACnBW,UAAUX,KAAK;EACfK,iBAAiBL,KAAK;CACxB;AACF"}

package/dist/utils/react/programmaticFocus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | 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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | 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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | 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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useCallback, useRef, useState } from "react";
 //#region src/utils/react/useBufferedValue.ts

package/dist/utils/react/useCombinedRefs.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useRef } from "react";
 //#region src/utils/react/useCombinedRefs.ts

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | 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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 //#region src/utils/react/useEventBus.ts

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import "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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useState } from "react";
 //#region src/utils/react/useIsDarwin.ts

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { c } from "react/compiler-runtime";
 //#region src/utils/react/useKeySymbols.ts

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import * as React$1 from "react";
 //#region src/utils/react/useLayoutEffect.tsx
 const useLayoutEffect$1 = typeof window !== "undefined" ? React$1.useLayoutEffect : React$1.useEffect;

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | 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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 //#region src/utils/react/useMergeStyles.ts

package/dist/utils/react/useOverlayEscapeGuard.js

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

package/dist/utils/react/usePopoverSync.js

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

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | 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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | 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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useState } from "react";
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { Fragment, isValidElement } from "react";
 //#region src/utils/react/wrapNodeIfPlain.ts
 function wrapNodeIfPlain(children, render) {

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.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/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { isSelector, mergeStyles } from "@tenphi/tasty";
 //#region src/utils/styles.ts
 function isRecord(value) {

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | 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.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.201.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.203.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.201.0";
+const VERSION = "0.203.0";
 const TASTY_VERSION = "3.15.0";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/CreateComponent.md

@@ -429,7 +429,7 @@ export function Action(
 
 ## Form Integration
 
-Call `wrapWithField(control, props)` consistently: it renders the field chrome when the field has something to show, and `isBare` decides when set. Attach the field's ref to the control's own root, as the `Action` above does; the chrome takes none, so the ref reaches the control with or without it, and `labelRef` reaches the label. `useFieldProps` works out whether a field without a label needs the chrome, and asks for it with `isBare={false}`; a control that shows messages of its own asks the same way after it, with `isBare: props.isBare ?? false`, as `TagInput` does. A control that shows the errors of its `validate` passes `showsValidateErrors: true` to `useFieldProps`, so a `validate` asks too. Never infer presentation from message content. Pass React Aria's label props to the wrapper so a supplied label remains associated with the control in both modes. Inner controls whose parent owns the field chrome should receive `isBare` to avoid nested fields, written after any spread of the parent's resolved props, which can carry `isBare={false}`.
+Call `wrapWithField(control, props)` consistently: it renders the field chrome when the field has something to show, and `isBare` decides when set. Attach the field's ref to the control's own root, as the `Action` above does; the chrome takes none, so the ref reaches the control with or without it, and `labelRef` reaches the label. `useFieldProps` works out whether a field without a label needs the chrome, and asks for it with `isBare={false}`; a control that shows messages of its own asks the same way after it, with `isBare: props.isBare ?? false`, as `TagInput` does. A control that shows the errors of its `validate` passes `showsValidateErrors: true` to `useFieldProps`, so a `validate` asks too. Never infer presentation from message content. Pass React Aria's label props to the wrapper so a supplied label remains associated with the control in both modes. Inner controls whose parent owns the field chrome should receive `isBare` to avoid nested fields, written after any spread of the parent's resolved props, which can carry `isBare={false}`. An input's style props are `FieldLayoutStyleProps` and go to its outer element: route them with `splitFieldLayout`, put its `styles` on the control and pass `{ ...props, ...field }` to `wrapWithField`.
 
 For input components that need to integrate with forms, see the [Field documentation](./components/form/Field.md) for comprehensive guidance on:
 

package/docs/FieldProperties.md

@@ -2,7 +2,7 @@
 
 All input components in UI Kit (`TextInput`, `Select`, `ComboBox`, `Checkbox`, `RadioGroup`, `NumberInput`, `Switch`, `DatePicker`, `Slider`, `FileInput`, etc.) share a common set of field properties. These properties are provided by the `FieldBaseProps` interface and enable form integration, validation, labeling, and state management.
 
-When used inside a [Form](./components/form/Form.md), these properties are automatically inherited from the form context and can be overridden at the field level.
+When used inside a [Form](./components/form/Form.md), these properties are automatically inherited from the form context and can be overridden at the field level. For the state a form passes down (`isDisabled`, `isReadOnly`, `isInvalid` and `isValid`), a field prop set to `undefined` counts as not set, so a wrapper that passes an optional `isDisabled` through keeps the form's state.
 
 For modern forms, follow the [use-case guide](./components/form/ModernForm.md). Bind with `name` and put validation options on the input, or choose `field={form.field(path, options)}` for model-aware type checking and validator inference. Keep presentation props on the input. These binding styles are alternatives; descriptors are not required for nested data.
 
@@ -22,10 +22,10 @@ For modern forms, follow the [use-case guide](./components/form/ModernForm.md).
 - **`label`** `ReactNode` — Label text displayed above or beside the input.
 - **`labelPosition`** `'top' | 'side' | 'split'` (default: `top`) — Position of the label relative to the input. Side and split layouts reserve a label column only when a label is present.
 - **`description`** `ReactNode` — Help text. It appears below a top label or the control when there is no visible label, and beside the control with a side or split label. It remains independent of the error message.
-- **`isBare`** `boolean` — Render the control without field layout, description or message text. A supplied `label` remains as a visually hidden accessible label; label tooltips, suffixes and extra content are omitted. Form binding, invalid state and control styles still apply. Use this for an inline control that would otherwise show its chrome but has no room for it, or when a parent already renders that chrome. Provide `aria-describedby` when the error is explained elsewhere. Unset, a field renders its chrome when there is something to show: a non-empty `label`, a form binding, or a `description`, `errorMessage`, `message`, `fieldStyles`, `fieldProps` or `isHidden` prop, whatever it holds. On `TextInput`, `TextArea`, `PasswordInput` and `NumberInput`, which show the errors of a `validate`, that prop counts too. Otherwise it renders only the control. `TagInput` always has something to show: its refusal messages. Pass `isBare={false}` to render the chrome anyway. Layout props on the control stay there; use `fieldStyles` to place the entire field.
+- **`isBare`** `boolean` — Render the control without field layout, description or message text. A supplied `label` remains as a visually hidden accessible label; label tooltips, suffixes and extra content are omitted. Form binding, invalid state and control styles still apply. Use this for an inline control that would otherwise show its chrome but has no room for it, or when a parent already renders that chrome. Provide `aria-describedby` when the error is explained elsewhere. Unset, a field renders its chrome when there is something to show: a non-empty `label`, a form binding, or a `description`, `errorMessage`, `message`, `fieldStyles`, `fieldProps` or `isHidden` prop, whatever it holds. On `TextInput`, `TextArea`, `PasswordInput` and `NumberInput`, which show the errors of a `validate`, that prop counts too. Otherwise it renders only the control. `TagInput` always has something to show: its refusal messages. Pass `isBare={false}` to render the chrome anyway. Style props size whichever element is outermost, so adding a label never changes where they apply; see _Field sizing and alignment_.
 - **`forceField`** `boolean` — **Deprecated.** Use `isBare={false}`. Renders the chrome even with nothing to show; an explicit `isBare` wins.
 - **`extra`** `ReactNode` — Additional content displayed next to the label.
-- **`labelTooltip`** `ReactNode` — Content of an info badge shown next to the label. Only rendered when the field has a label. (Formerly `tooltip`. On most fields `tooltip` is gone; on `Select` and `Checkbox` it is the control's own tooltip, as on `Item` and `Button`.)
+- **`labelTooltip`** `ReactNode` — Content of an info badge shown next to the label. Only rendered when the field has a label. (Formerly `tooltip`. On most fields `tooltip` is gone; on `Select`, `Picker`, `FilterPicker`, `ColorPicker`, `Checkbox`, `Switch` and the text inputs (`TextInput`, `TextArea`, `PasswordInput`, `SearchInput`, `NumberInput`, `CommandTextArea`) it is the control's own tooltip, as on `Item` and `Button`.)
 - **`labelSuffix`** `ReactNode` — Content displayed after the label text.
 - **`labelProps`** `object` — Additional HTML props passed to the label element.
 - **`labelStyles`** `Styles` — Tasty styles for the label element.
@@ -51,12 +51,33 @@ The field wrapper stays in place when a description or message appears or disapp
 
 ### Field sizing and alignment
 
-Set `fieldStyles` to size the entire field, including its label, description and feedback. Control-level `width`, `styles` and `wrapperStyles` continue to size the control itself:
+An input's style props (`width`, `height`, `flex*`, `gridArea`, `margin`, `inset`, `position`, …) place and size its outer element: the field wrapper when it renders, the input itself otherwise. Adding a label never changes where they apply. When they size a wrapped field, the input stretches to fill it as it would in a grid cell of that size. Inputs with a fixed or capped size keep it: `Checkbox` and `Switch` their content width, single-line inputs and a vertical `Slider` their height. A side label's column is part of the width, and a split label keeps the input at its content width.
+
+`width` is the space an input takes in the layout, label included. `controlWidth` is the control's own width: it sizes the element `width` sizes when the input renders bare, in every label position. On a bare input, with no label, description or form binding, the two reach the same element, so use `width` there; `controlWidth` wins when both are set. Beside a side label, `controlWidth` sizes the control alone, fixed, capped or following its value, however long the label is in a given language:
 
 ```jsx
-<TextInput label="Name" fieldStyles={{ width: '40x' }} />
+// The field is 40x wide, label column included; the input fills it.
+<TextInput label="Name" labelPosition="side" width="40x" />
+
+// The select is 100px wide beside its label.
+<Select label="Limit" labelPosition="side" controlWidth="100px">…</Select>
+
+// The select fills the space beside its label, up to 30x.
+<Select label="Compare with" labelPosition="side" controlWidth="max 30x">…</Select>
+
+// The select follows its value, up to 30x.
+<Select label="Compare with" labelPosition="side" controlWidth="initial max-content 30x">…</Select>
+
+// The field is 40x wide; the input inside it stays 20x.
+<TextInput label="Name" width="40x" controlWidth="20x" />
 ```
 
+In a `Form`, a side label's column is the Form's `labelWidth` (25x by default) plus 1x, so the control starts `labelWidth` + 1x from the field's edge and is `controlWidth` wide. `controlWidth` wins over `styles.width`. `styles` always styles the input and `fieldStyles` always styles the wrapper: keep `styles` for restyling the input itself.
+
+A style prop wins over `fieldStyles` for the same key. `fieldStyles` keeps working for everything else, but it never makes the input fill the field. Field-level inputs take only these style props and `controlWidth`; restyle the input through `styles` and its part props (`inputStyles`, `triggerStyles`, …).
+
+A state map on a style prop resolves against the element it lands on, which is the wrapper on a labelled field. Use media, container or root states there, not the input's own states such as `focused`. A state map on `controlWidth` resolves against the control. `className`, `style`, `qa` and `ref` never move to the wrapper.
+
 Fields without labels no longer reserve an empty side or split label column. If a row should intentionally align with neighbouring side labels, add `fieldStyles={{ padding: '$full-label-width left' }}`. For a nameless legacy `Form.Item`, put that padding on the item's `styles` instead; it owns the wrapper. Remove deprecated `forceField` when migrating these rows.
 
 ## Necessity Indicators
@@ -89,7 +110,7 @@ Fields without labels no longer reserve an empty side or split label column. If
 
 ## State
 
-- **`isDisabled`** `boolean` (default: `false`) — Whether the field is disabled and non-interactive. A field also takes it from an enclosing `<Provider isDisabled>` or `<Form isDisabled>`. Buttons don't, apart from `Form.Submit` and `Form.Reset`: see [Button](./components/actions/Button.md).
+- **`isDisabled`** `boolean` (default: `false`) — Whether the field is disabled and non-interactive. A field also takes it from an enclosing `<Provider isDisabled>` or `<Form isDisabled>`, including when its own `isDisabled` is `undefined`. Buttons don't, apart from `Form.Submit` and `Form.Reset`: see [Button](./components/actions/Button.md).
 - **`isReadOnly`** `boolean` (default: `false`) — Whether the field can be focused but not changed.
 - **`isLoading`** `boolean` (default: `false`) — Whether the field shows its loading spinner. `Select`, `Picker`, `FilterPicker`, `ColorPicker` and a button-type `Radio` also disable while loading; other fields stay interactive, and fields without a spinner, such as `Checkbox`, `RadioGroup`, `ListBox` or `Slider`, ignore it.
 - **`isHidden`** `boolean` (default: `false`) — Whether the field is hidden.
@@ -113,7 +134,8 @@ Fields without labels no longer reserve an empty side or split label column. If
 
 ## Styling
 
-- **`fieldStyles`** `Styles` — Tasty styles for the field wrapper.
+- **`controlWidth`** `Styles['width']` — The control's own width, in every label position: the element `width` sizes when the input renders bare. Beside a side label it sizes the control alone. It wins over `width` on a bare input and over `styles.width`; see _Field sizing and alignment_.
+- **`fieldStyles`** `Styles` — Tasty styles for the field wrapper. A style prop for the same key wins over it.
 - **`messageStyles`** `Styles` — Tasty styles for the message/error text.
 
 ## Validation Rules

package/docs/Usage.md

@@ -415,6 +415,8 @@ The package's `tasty.config.ts` lists the other components as `protectedComponen
 - style props other than the ones that place or size the component (`width`, `height`, `gridArea`, `margin`, `inset`, …). Containers (`Card`, `Panel`, `ResizablePanel`, `Content`, `Header`, `Footer`, and `Layout` and `GridLayout` with their sub-components) also keep the ones that lay out their content: `padding`, `gap`, `flow`, `place*`, `align*`, `justify*`, `grid*`, `overflow` and `scrollbar`. Root `styles` that sets only allowed props passes too;
 - `tasty()` wrappers that restyle a protected component, and wrappers of those wrappers.
 
+On an input, the style props that place or size it act on its outer element: the field wrapper when it renders (see [Field properties](./FieldProperties.md)), the input itself otherwise. Its `styles` always style the input, so a root `styles` that only sizes it passes the rule but sizes the input inside the field, not the field. To size the input alone, beside a side label for example, use its `controlWidth` prop. Input components take no other style props.
+
 A component's own prop that shares a name with a style passes, such as a field's `direction` and `filter`, a text field's `resize`, `ColorSwatch`'s `color` or `AlertDialog`'s `content`.
 
 A sub-component counts as the component it hangs off, so `Button.Split` is protected like `Button`, and `Layout.Content` is a container like `Layout`. The list names the exceptions, such as `Button.Group`.
@@ -465,6 +467,7 @@ These are data-attribute modifiers used in component style maps (via the `mods`
 | Modifier | Description |
 | --- | --- |
 | `disabled` | Disabled state |
+| `readonly` | Read-only state: the value shows but cannot change |
 | `hovered` | Hover state |
 | `focused` | Focus state |
 | `pressed` | Active/pressed state |

package/docs/components/content/Divider.md

@@ -1,28 +1,44 @@
 # Divider
 
-A horizontal separator. Can be a simple line or include centered text with lines on both sides.
+A line that separates content. It is horizontal by default and vertical with `orientation="vertical"`, and it can show text, such as "or", between two lines. Built on React Aria's `useSeparator`.
 
 ## When to Use
 
 - Separating sections of content
-- Dividing list items or form sections
-- "Or" or other labels between content blocks
+- Separating the items of a toolbar or an action row (vertical)
+- "Or" or another label between two blocks of content
 
-## Properties
+## Component
 
-- **`children`** `ReactNode` — Optional text to display centered between two lines
+---
 
-### Style Defaults
+### Properties
 
-- `display` — `block` (switches to `grid` when text is present)
-- `height` — `1bw` (switches to `auto` when text is present)
-- `fill` — `#border` (switches to `none` when text is present)
-- `preset` — `c1`
-- `gridArea` — `divider`
+- **`children`** `ReactNode` — Text shown between two lines. It also names the separator for screen readers, unless `aria-label` or `aria-labelledby` names it. Screen readers get it only as that name, so keep it to text: a link or button in it would be unreachable.
+- **`orientation`** `'horizontal' | 'vertical'` (default: `'horizontal'`) — The direction of the line. A vertical divider stretches to the height of its flex or grid row, even when the row centers its items. Elsewhere, or to make it shorter, give it a `height`.
 
 ### Base Properties
 
-Supports [Base properties](../../BaseProperties.md).
+Supports [Base properties](../../BaseProperties.md). A divider's `qa` defaults to `Divider`.
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element. Without text, the root is the line itself.
+
+**Sub-elements:**
+
+- `Line` - Each of the two lines around the text.
+
+### Style Defaults
+
+- `fill` — `#border`; `none` with text, where the `Line` sub-elements carry the color
+- `height` — `1bw` when horizontal without text
+- `width` — `1bw` when vertical without text
+- `margin` — `0`
+- `preset` — `c1`
+- `display` — `block`; `grid` with text
 
 ### Style Properties
 
@@ -31,21 +47,87 @@ These properties allow direct style application without using the `styles` prop:
 - **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
 - **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
+- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`
 - **Color:** `color`, `fill`, `fade`, `image`
-- **Text:** `textTransform`, `fontWeight`, `fontStyle`
-- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
-## Examples
+### Modifiers
 
-```jsx
-<Divider />
+The `mods` property accepts the following modifiers you can override:
 
-<Divider>or</Divider>
+| Modifier | Type | Description |
+| --- | --- | --- |
+| text | `boolean` | The divider shows text between two lines |
+| vertical | `boolean` | The divider is vertical |
+| sized | `boolean` | It has a `height` or `blockSize` of its own, so a vertical divider follows the row's alignment instead of stretching |
+
+## Examples
+
+### Between sections
 
-<Flow gap="1x">
+```jsx
+<Space flow="column" gap="1x">
   <Paragraph>Section 1</Paragraph>
   <Divider />
   <Paragraph>Section 2</Paragraph>
-</Flow>
+</Space>
+```
+
+### Spacing
+
+```jsx
+<Divider margin="1x 0" />
+```
+
+### With text
+
+```jsx
+<Divider>or</Divider>
+```
+
+### Vertical, in a row of actions
+
+```jsx
+<Space placeItems="center" gap="1.5x">
+  <Button>Edit</Button>
+  <Divider orientation="vertical" />
+  <Button>Delete</Button>
+</Space>
+```
+
+A vertical divider takes the height of its row in a flex or grid container. Give it a `height` when it should be shorter, or when its container is a plain block. A divider with a height follows the row's alignment, so it stays centered in a row that centers its items. A `min max` range counts as a height too; add `alignSelf="stretch"` to stretch within it:
+
+```jsx
+<Space placeItems="center" gap="1.5x">
+  <Button>Edit</Button>
+  <Divider orientation="vertical" height="3x" />
+  <Button>Delete</Button>
+</Space>
 ```
+
+A vertical divider with text needs a row about `8x` tall or more. In a shorter row the lines shrink to nothing and only the text is left.
+
+## Accessibility
+
+### Screen Reader Support
+
+- A horizontal divider without text is an `<hr>`, which screen readers announce as a separator.
+- A vertical divider, or one with text, is a `div` with `role="separator"`. A vertical one carries `aria-orientation="vertical"`.
+- ARIA treats a separator's content as presentational, so a text divider is named by its text through `aria-labelledby`: its accessible name is its text, and the text is hidden from screen readers so it is not read a second time. An `aria-label` or `aria-labelledby` you pass replaces that name.
+
+## Best Practices
+
+1. **Do**: put spacing on the divider or its container
+
+   ```jsx
+   <Divider margin="2x 0" />
+   ```
+
+2. **Don't**: draw a separator with a bordered empty element; it is invisible to screen readers
+
+   ```jsx
+   <Block styles={{ border: 'top' }} />
+   ```
+
+## Related Components
+
+- [Space](../layout/Space.md) - Lays out the content a divider separates

package/docs/components/content/Tree.md

@@ -25,8 +25,8 @@ The component's data shape (`treeData`) and the public callback shape are design
 - **`defaultExpandedKeys`** `string[]` — Default expanded keys (uncontrolled).
 - **`expandedKeys`** `string[]` — Controlled expanded keys.
 - **`autoExpandParent`** `boolean` (default: `false`) — Auto-expand parents of currently expanded keys. Useful for filtering.
-- **`defaultCheckedKeys`** `string[]` — Default checked keys (uncontrolled).
-- **`checkedKeys`** `string[] | { checked: string[]; halfChecked?: string[] }` — Controlled checked keys. Pass the object form to receive the same shape back from `onCheck`.
+- **`defaultCheckedKeys`** `string[]` — Default checked keys (uncontrolled). A parent key checks its whole subtree, as in AntD.
+- **`checkedKeys`** `string[] | { checked: string[]; halfChecked?: string[] }` — Controlled checked keys. In the array form, a parent key checks its whole subtree, as in AntD. Pass the object form to receive the same shape back from `onCheck`; it is taken as given.
 - **`defaultSelectedKeys`** `string[]` — Default selected keys (uncontrolled).
 - **`selectedKeys`** `string[]` — Controlled selected keys.
 - **`height`** `number` — Fixed height in pixels. When omitted, the tree fills the available vertical space and scrolls internally.
@@ -53,6 +53,7 @@ The component's data shape (`treeData`) and the public callback shape are design
 
 - **`key`** `string` — Unique identifier of the node.
 - **`title`** `ReactNode` — Visible label.
+- **`textValue`** `string` — Plain-text label, for a `title` that is not a string. It names the row's checkbox and is what `FilterPicker`'s tree mode searches and summarises.
 - **`children`** `CubeTreeNodeData[]` — Children. Pass `undefined` together with `isLeaf={false}` for lazy nodes.
 - **`isLeaf`** `boolean` — Force leaf rendering (no expand toggle, no `loadData` call).
 - **`isDisabled`** `boolean` — Disable interactions on this row (focus / select / expand / check).
@@ -200,7 +201,7 @@ Pass the matching keys via `expandedKeys` and set `autoExpandParent` to keep the
 
 ### Per-node Disabling
 
-Disable the entire row, just the checkbox, or hide the checkbox via node-level flags.
+Disable the entire row, just the checkbox, or hide the checkbox via node-level flags. Such a node with no eligible nodes below it keeps its own checked state. Above eligible nodes, its state follows them, and the cascade passes through it: checking its parent checks the eligible nodes below it.
 
 ```jsx
 const data = [
@@ -268,7 +269,7 @@ Tree implements the [`treegrid` ARIA pattern](https://www.w3.org/WAI/ARIA/apg/pa
 ### Screen Reader Support
 
 - Each row reports `aria-level`, `aria-posinset` and `aria-setsize`. Expandable rows also report `aria-expanded`, including a lazy row (`isLeaf: false`) whose children have not loaded yet.
-- When `isCheckable` is enabled, the row carries `aria-checked` (`true`, `false`, or `mixed` for the indeterminate state).
+- When `isCheckable` is enabled, each row's checkbox carries the checked state (`checked`, `not checked`, or `mixed` for the indeterminate state), named by the node's `textValue` or string `title`. The row itself takes no `aria-checked`, which `row` does not support; it has `data-checked` and `data-indeterminate` for tests.
 - Disabled rows expose `aria-disabled="true"`.
 
 ### ARIA Properties