@cube-dev/ui-kit 0.181.0 → 0.183.0

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/Picker.md

@@ -48,6 +48,7 @@ Choose a different component when the interaction has another shape:
 - **`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
 - **`isClearable`** `boolean` (default: `false`) — Whether the picker shows a clear button when a selection is made
+- **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
 - **`onClear`** `() => void` — Callback called when the clear button is pressed
 - **`actions`** `ReactNode` — Custom actions rendered inside the trigger, to the left of the built-in clear button and dropdown caret
 - **`sortSelectedToTop`** `boolean` — Sort selected items to the top when the popover opens (only works with `items` prop)
@@ -787,12 +788,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"
@@ -806,7 +808,7 @@ function MyForm() {
         <Picker.Item key="books">Books</Picker.Item>
       </Picker>
 
-      <Button type="submit">Submit</Button>
+      <Form.Submit>Submit</Form.Submit>
     </Form>
   );
 }
@@ -815,26 +817,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/Select.md

@@ -38,6 +38,7 @@ Choose a different component when the interaction has another shape:
 - **`size`** `string` (default: `medium`) — Size of the select component
 - **`direction`** `string` (default: `bottom`) — Preferred direction for the dropdown menu
 - **`isClearable`** `boolean` (default: `false`) — Whether the select 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".
 - **`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
 - **`overlayOffset`** `number` (default: `8`) — Distance between select and dropdown in pixels
@@ -627,18 +628,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