@cube-dev/ui-kit 0.182.0 → 0.184.0

package/docs/components/fields/FilterPicker.md

@@ -56,7 +56,7 @@ Choose a different component when the interaction has another shape:
 - **`listBoxStyles`** `Styles` — Custom styles for the dropdown list container within the popover
 - **`popoverStyles`** `Styles` — Custom styles for the popover dialog that contains the FilterListBox
 - **`triggerStyles`** `Styles` — Custom styles for the trigger button element
-- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from field tooltip)
+- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from `labelTooltip`)
 - **`triggerDescription`** `string` — Description for the trigger button (separate from field description)
 - **`prefix`** `ReactNode` — Content to show before the trigger button text
 - **`suffix`** `ReactNode` — Content to show after the trigger button text
@@ -65,6 +65,8 @@ Choose a different component when the interaction has another shape:
 - **`headerStyles`** `Styles` — Custom styles for the header area when header prop is provided
 - **`footerStyles`** `Styles` — Custom styles for the footer area when footer prop is provided
 - **`shouldFlip`** `boolean` (default: `true`) — Whether to flip the popover placement when it overflows
+- **`placement`** `Placement` (default: `bottom start`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the trigger; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`containerPadding`** `number` (default: `8`) — Minimum padding in pixels between the popover and viewport edges
 - **`sortSelectedToTop`** `boolean` — Sort selected items to the top when the popover opens (only works with `items` prop, defaults to `true` when items are provided)
 - **`searchValue`** `string` — Controlled search input value
@@ -693,25 +695,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

package/docs/components/fields/ListBox.md

@@ -615,20 +615,25 @@ const [selectedKey, setSelectedKey] = useState('apple');
 ### In Forms
 
 ```jsx
-<Form onSubmit={handleSubmit}>
-  <ListBox
-    name="technology"
-    label="Preferred Technology"
-    isRequired
-    selectionMode="single"
-  >
-    <ListBox.Section title="Frontend">
-      <ListBox.Item key="react">React</ListBox.Item>
-      <ListBox.Item key="vue">Vue.js</ListBox.Item>
-    </ListBox.Section>
-  </ListBox>
-  <Form.Submit>Submit</Form.Submit>
-</Form>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form} onSubmit={handleSubmit}>
+      <ListBox
+        name="technology"
+        label="Preferred Technology"
+        isRequired
+        selectionMode="single"
+      >
+        <ListBox.Section title="Frontend">
+          <ListBox.Item key="react">React</ListBox.Item>
+          <ListBox.Item key="vue">Vue.js</ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+      <Form.Submit>Submit</Form.Submit>
+    </Form>
+  );
+}
 ```
 
 ### Reorderable
@@ -764,18 +769,23 @@ 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}>
-  <ListBox
-    name="preferences"
-    label="User Preferences"
-    isRequired
-    rules={[{ required: true }]}
-    selectionMode="multiple"
-  >
-    <ListBox.Item key="notifications">Email Notifications</ListBox.Item>
-    <ListBox.Item key="newsletter">Newsletter</ListBox.Item>
-  </ListBox>
-</Form>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form} onSubmit={handleSubmit}>
+      <ListBox
+        name="preferences"
+        label="User Preferences"
+        isRequired
+        rules={[{ required: true }]}
+        selectionMode="multiple"
+      >
+        <ListBox.Item key="notifications">Email Notifications</ListBox.Item>
+        <ListBox.Item key="newsletter">Newsletter</ListBox.Item>
+      </ListBox>
+    </Form>
+  );
+}
 ```
 
 ## Performance

package/docs/components/fields/PeriodPicker.md

@@ -35,6 +35,8 @@ In the month and quarter panels the year in the header is a button that opens a
 - **`formatValue`** `(date: DateValue, picker: PickerType, locale: string) => string` — Overrides the displayed label
 - **`size`** `'small' | 'medium' | 'large' | (string & {})` (default: `medium`) — Field size
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the popover flips to fit the viewport
+- **`placement`** `Placement` (default: `bottom right`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the field wrapper; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`isOpen`** `boolean` — Whether the popover is open (controlled)
 - **`defaultOpen`** `boolean` — Whether the popover is open by default (uncontrolled)
 - **`onChange`** `(value: DateValue | null) => void` — Fired when the selected period changes

package/docs/components/fields/Picker.md

@@ -58,9 +58,11 @@ Choose a different component when the interaction has another shape:
 - **`listBoxStyles`** `Styles` — Custom styles for the ListBox within the popover
 - **`popoverStyles`** `Styles` — Custom styles for the popover container
 - **`triggerStyles`** `Styles` — Custom styles for the trigger button
-- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from field tooltip)
+- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from `labelTooltip`)
 - **`triggerDescription`** `string` — Description for the trigger button (separate from field description)
 - **`shouldFlip`** `boolean` — Whether to flip the popover placement when it overflows
+- **`placement`** `Placement` (default: `bottom start`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the trigger; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`containerPadding`** `number` — Minimum padding between the popover and viewport edges
 - **`onSelectionChange`** `(keys: Key | Key[] | 'all' | null) => void` — Callback when selection changes
 - **`onClear`** `() => void` — Callback called when the clear button is pressed
@@ -788,12 +790,13 @@ This component supports all [Field properties](../../FieldProperties.md) when us
 import { Form, Picker } from '@cube-dev/ui-kit';
 
 function MyForm() {
+  const form = Form.useController();
   const handleSubmit = (values) => {
     console.log('Form values:', values);
   };
 
   return (
-    <Form onSubmit={handleSubmit}>
+    <Form form={form} onSubmit={handleSubmit}>
       <Picker
         name="category"
         label="Product Category"
@@ -807,7 +810,7 @@ function MyForm() {
         <Picker.Item key="books">Books</Picker.Item>
       </Picker>
 
-      <Button type="submit">Submit</Button>
+      <Form.Submit>Submit</Form.Submit>
     </Form>
   );
 }
@@ -816,26 +819,31 @@ function MyForm() {
 ### Multiple Selection in Forms
 
 ```jsx
-<Form onSubmit={handleSubmit}>
-  <Picker
-    name="tags"
-    label="Tags"
-    selectionMode="multiple"
-    isCheckable
-    placeholder="Select tags"
-    defaultValue={['tag1', 'tag2']}
-    rules={[
-      { required: true, message: 'At least one tag is required' },
-      { type: 'array', min: 2, message: 'Select at least 2 tags' }
-    ]}
-  >
-    <Picker.Item key="tag1">Tag 1</Picker.Item>
-    <Picker.Item key="tag2">Tag 2</Picker.Item>
-    <Picker.Item key="tag3">Tag 3</Picker.Item>
-  </Picker>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form} onSubmit={handleSubmit}>
+      <Picker
+        name="tags"
+        label="Tags"
+        selectionMode="multiple"
+        isCheckable
+        placeholder="Select tags"
+        defaultValue={['tag1', 'tag2']}
+        rules={[
+          { required: true, message: 'At least one tag is required' },
+          { type: 'array', min: 2, message: 'Select at least 2 tags' }
+        ]}
+      >
+        <Picker.Item key="tag1">Tag 1</Picker.Item>
+        <Picker.Item key="tag2">Tag 2</Picker.Item>
+        <Picker.Item key="tag3">Tag 3</Picker.Item>
+      </Picker>
 
-  <Button type="submit">Submit</Button>
-</Form>
+      <Form.Submit>Submit</Form.Submit>
+    </Form>
+  );
+}
 ```
 
 ### Key Form Properties

package/docs/components/fields/RadioGroup.md

@@ -49,12 +49,12 @@ Each option is a `Radio` (also exported as `Radio.Button`).
 - **`type`** `'radio' | 'button'` — Overrides the group's visual type for this option
 - **`size`**, **`buttonType`** — Override the group's `size` / `buttonType` for this option
 
-A `button`- or `tabs`-type radio renders an [Item](../content/Item.md), so it takes the same content props an [ItemButton](../actions/ItemButton.md) does. These are ignored by a classic radio:
+A `button`- or `tabs`-type radio renders an [Item](../content/Item.md), so it takes the same content props an [ItemButton](../actions/ItemButton.md) does. A classic radio ignores all of these except `tooltip` and `labelRef`:
 
 - **`icon`**, **`rightIcon`** — Icons before / after the label
 - **`prefix`**, **`suffix`** — Content before / after the label
 - **`description`**, **`descriptionPlacement`**, **`descriptionProps`** — Secondary line, placed `inline` (default) or `block`
-- **`tooltip`** — Tooltip content, or `true` to show one only when the label is truncated
+- **`tooltip`** — Tooltip content, or `true` to show one only when the label is truncated. A button radio defaults to `true`; its label truncates only when the radio gets less room than it (an explicit `width`, say), and never with a `block` description, which keeps the label at full width. A classic radio's label wraps instead of truncating, so it shows a tooltip only when given content. Either way a disabled option still shows its tooltip — a good place to say why it is unavailable. Tooltips open on hover and when the option takes keyboard focus, and describe its input to screen readers. The info badge next to the group's label is the group's `labelTooltip`
 - **`hotkeys`**, **`keyboardShortcutProps`** — Keyboard shortcut that selects the option, rendered as a hint
 - **`isLoading`**, **`loadingSlot`** — Replaces a slot with a spinner and disables the option
 - **`highlight`**, **`highlightCaseSensitive`**, **`highlightStyles`** — Highlights a substring of the label

package/docs/components/fields/Select.md

@@ -41,6 +41,8 @@ Choose a different component when the interaction has another shape:
 - **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
 - **`actions`** `ReactNode` — Custom actions rendered inside the trigger, to the left of the built-in clear button and dropdown caret
 - **`shouldFlip`** `boolean` (default: `true`) — Whether dropdown should flip to fit in viewport
+- **`placement`** `Placement` (default: `${direction} end`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the trigger; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`overlayOffset`** `number` (default: `8`) — Distance between select and dropdown in pixels
 - **`items`** `Iterable<T>` — Item objects used when rendering dynamic collections
 - **`disabledKeys`** `Iterable<Key>` — Keys of items that are disabled
@@ -60,6 +62,7 @@ Choose a different component when the interaction has another shape:
 - **`triggerDescription`** `ReactNode` — Description text displayed within the trigger button (different from field-level description)
 - **`descriptionPlacement`** `'inline' | 'block'` — Controls how the trigger description is positioned
 - **`hotkeys`** `string` — Keyboard shortcut that triggers the select when pressed
+- **`tooltip`** `string | boolean | object` — Tooltip on the trigger (see [Notable Properties](#notable-properties)). The info badge next to the label is the field-level `labelTooltip`
 - **`containerPadding`** `number` (default: `8`) — Minimum padding in pixels between the popover and viewport edges
 - **`isOpen`** `boolean` — Whether the dropdown is open (controlled)
 - **`defaultOpen`** `boolean` — Whether the dropdown is open by default (uncontrolled)
@@ -87,6 +90,8 @@ Choose a different component when the interaction has another shape:
 - `true` - Auto tooltip on overflow (shows selected value when truncated)
 - `object` - Advanced configuration with optional `auto` property
 
+It belongs to the trigger alone. The info badge next to the field's label is `labelTooltip` — before that prop existed, a `tooltip` on a labelled Select rendered in both places.
+
 **triggerDescription** - Text description displayed within the trigger button. Different from field-level description provided by FieldWrapper.
 
 **descriptionPlacement** - Controls how description is positioned: `inline` or `block`.
@@ -628,18 +633,22 @@ const groups = [
 This component supports all [Field properties](../../FieldProperties.md) when used within a Form. It integrates seamlessly with the form validation system and supports both controlled and uncontrolled modes.
 
 ```jsx
-<Form>
-  <Select
-    name="country"
-    label="Country"
-    isRequired
-    validationBehavior="native"
-  >
-    <Select.Item key="us">United States</Select.Item>
-    <Select.Item key="uk">United Kingdom</Select.Item>
-    <Select.Item key="ca">Canada</Select.Item>
-  </Select>
-</Form>
+function Example() {
+  const form = Form.useController();
+  return (
+    <Form form={form}>
+      <Select
+        name="country"
+        label="Country"
+        isRequired
+      >
+        <Select.Item key="us">United States</Select.Item>
+        <Select.Item key="uk">United Kingdom</Select.Item>
+        <Select.Item key="ca">Canada</Select.Item>
+      </Select>
+    </Form>
+  );
+}
 ```
 
 ## Suggested Improvements

package/docs/components/form/Field.md

@@ -1,11 +1,11 @@
-# Field
+# Field (legacy)
 
 The Field component is a **legacy wrapper** for form inputs that provides field-specific styling and behavior. Built-in input components already provide field support on both backends, so pass field properties directly to them. For custom controls in a modern controller form, use `useFieldProps` and `wrapWithField` as described in [Modern Form](./ModernForm.md#implement-a-reusable-custom-control); `Field` / `Form.Item` does not support that backend.
 
 ## When to Use
 
 - **❌ Don't use** for regular input components (TextInput, Select, etc.) - they have built-in field support
-- **✅ Use only** when wrapping read-only content to make it appear as a form field
+- For read-only values in new forms, use a built-in input with `isReadOnly`. Compose labels and layout components for display-only content.
 - **✅ Use only** when wrapping custom components in legacy forms that don't have built-in field support
 
 ## Component
@@ -17,7 +17,7 @@ The Field component is a **legacy wrapper** for form inputs that provides field-
 - **`label`** `string` — Field label text
 - **`description`** `string` — Field description text
 - **`extra`** `string` — Additional information displayed below help text
-- **`tooltip`** `string` — Tooltip content for the field label
+- **`labelTooltip`** `string` — Info badge content next to the field label (formerly `tooltip`)
 - **`errorMessage`** `string` — Error message
 - **`name`** `string` — Field name for form data
 - **`defaultValue`** `string` — Default field value
@@ -77,7 +77,7 @@ These properties allow direct style application without using the `styles` prop:
 - **`label`** `ReactNode` — Field label text
 - **`description`** `ReactNode` — Field description text
 - **`extra`** `ReactNode` — Additional information displayed below help text
-- **`tooltip`** `ReactNode` — Tooltip content for the field label
+- **`labelTooltip`** `ReactNode` — Info badge content next to the field label (formerly `tooltip`)
 - **`message`** `ReactNode` — Error or help message
 - **`defaultValue`** `any` — Default field value
 - **`rules`** `ValidationRule[]` — Validation rules array