@cube-dev/ui-kit 0.166.0 → 0.167.0

package/docs/components/fields/RadioGroup.md

@@ -104,6 +104,7 @@ The `mods` property accepts the following modifiers you can override:
 - `tabs` - Connected tab-style buttons (compact, clear styling)
 
 **Default Orientation:**
+
 - `radio` type: vertical
 - `button` and `tabs` types: horizontal
 
@@ -113,20 +114,22 @@ The `mods` property accepts the following modifiers you can override:
 - `horizontal` - Arrange radio options horizontally
 
 The orientation is automatically set based on the `type`:
+
 - Traditional radios default to vertical
 - Button and tabs types default to horizontal for better UX
 
 ### Size
 
 Controls the size of all radio buttons in the group:
+
 - `xsmall` - Extra small size
 - `small` - Small size
 - `medium` - Medium size (default)
 - `large` - Large size
 - `xlarge` - Extra large size
 
-**Size Mapping in Tabs Mode:**
-When `type="tabs"`, sizes are automatically mapped to maintain visual consistency:
+**Size Mapping in Tabs Mode:** When `type="tabs"`, sizes are automatically mapped to maintain visual consistency:
+
 - `large` → `medium`
 - every other size → `xsmall`
 
@@ -135,11 +138,13 @@ Only `large` is carried through; `xsmall`, `small`, `medium` and `xlarge` all co
 ### Button Type
 
 When using `type="button"`, you can customize the button appearance:
+
 - `outline` - Outlined buttons (default); `isSelected` state adds brand-tinted fill
 - `clear` - Minimal buttons without background; `isSelected` state adds brand-tinted fill
 - `primary` - Primary action buttons with smart styling: selected buttons use primary style, non-selected buttons use outline with brand tint
 
-**Note:** 
+**Note:**
+
 - The `buttonType` prop is ignored when `type="tabs"`. Tabs always use `clear` styling for visual consistency.
 
 ## Examples
@@ -287,6 +292,7 @@ When using `type="button"`, you can customize the button appearance:
 ## Best Practices
 
 1. **Do**: Provide clear, descriptive labels for both group and options
+
    ```jsx
    <Radio.Group label="Preferred contact method">
      <Radio value="email">Email</Radio>
@@ -295,6 +301,7 @@ When using `type="button"`, you can customize the button appearance:
    ```
 
 2. **Don't**: Use radio groups for more than 7 options
+
    ```jsx
    <Radio.Group label="Country"> {/* Use Select instead */}
      {/* Too many options... */}
@@ -302,19 +309,20 @@ When using `type="button"`, you can customize the button appearance:
    ```
 
 3. **Visual Type**: Use `Radio.Tabs` for compact toolbars, `type="button"` for spaced selections, traditional radios for forms
+
    ```jsx
    {/* Good for compact toolbars */}
    <Radio.Tabs label="View">
      <Radio value="list">List</Radio>
      <Radio value="grid">Grid</Radio>
    </Radio.Tabs>
-   
+
    {/* Good for button selections */}
    <Radio.Group type="button" label="Priority">
      <Radio value="low">Low</Radio>
      <Radio value="high">High</Radio>
    </Radio.Group>
-   
+
    {/* Good for forms */}
    <Radio.Group label="Gender">
      <Radio value="male">Male</Radio>

package/docs/components/fields/SearchComboBox.md

@@ -77,6 +77,7 @@ Supports the layout-related [Field properties](../../FieldProperties.md) (`label
 Customizes the root wrapper element of the SearchComboBox (the input container).
 
 **Sub-elements:**
+
 - `Prefix` - Container for prefix content and icons
 - `Suffix` - Container for suffix content, status icons, and action buttons
 - `InputIcon` - Container for the left icon
@@ -239,11 +240,13 @@ useEffect(() => {
 ## Best Practices
 
 1. **Do**: Debounce server requests before updating `items`
+
    ```jsx
    <SearchComboBox filter={false} isLoading={isLoading} items={results} />
    ```
 
 2. **Do**: Provide a meaningful `emptyLabel` for both the empty and loading states
+
    ```jsx
    <SearchComboBox emptyLabel={query ? 'No results' : 'Type to search'} />
    ```

package/docs/components/fields/SearchInput.md

@@ -50,6 +50,7 @@ Supports the layout-related [Field properties](../../FieldProperties.md) (`label
 Customizes the root wrapper element of the component.
 
 **Sub-elements:**
+
 - `Prefix` - Element displayed before the input (contains search icon)
 - `Suffix` - Element displayed after the input (contains clear button when shown)
 - `State` - Container for validation state indicators
@@ -202,11 +203,13 @@ const [searchValue, setSearchValue] = useState('');
 ## Best Practices
 
 1. **Do**: Provide clear placeholder text indicating what can be searched
+
    ```jsx
    <SearchInput placeholder="Search by name, email, or department..." />
    ```
 
 2. **Don't**: Use search input for non-search related text entry
+
    ```jsx
    <SearchInput label="Enter your name" /> {/* Use TextInput instead */}
    ```
@@ -218,8 +221,7 @@ const [searchValue, setSearchValue] = useState('');
 
 ## Integration with Forms
 
-SearchInput is not a form field. Use [TextInput](./TextInput.md) when the typed text has to be
-captured as a form value.
+SearchInput is not a form field. Use [TextInput](./TextInput.md) when the typed text has to be captured as a form value.
 
 ## Suggested Improvements
 

package/docs/components/fields/Select.md

@@ -78,6 +78,7 @@ Choose a different component when the interaction has another shape:
 **onClear** - Callback fired when the clear button is pressed, allowing you to perform custom actions when the selection is cleared.
 
 **tooltip** - Enables tooltip display on the trigger button. Can be:
+
 - `string` - Simple tooltip text
 - `true` - Auto tooltip on overflow (shows selected value when truncated)
 - `object` - Advanced configuration with optional `auto` property
@@ -113,6 +114,7 @@ Customizes the root wrapper element of the component.
 Customizes the trigger button element that opens the dropdown.
 
 **Sub-elements:**
+
 - `Label` - The displayed selected value text or placeholder
 - `Prefix` - Container for prefix content
 - `Suffix` - Container for suffix content
@@ -134,6 +136,7 @@ Customizes the popover overlay wrapper that contains the list.
 Customizes individual option items in the dropdown.
 
 **Sub-elements:**
+
 - `Label` - The main content/text of the option
 - `Description` - Secondary description text
 - `Prefix` - Container for prefix content
@@ -191,15 +194,15 @@ For detailed information about all available item properties, see [Item document
 
 ```jsx
 <Select label="Users">
-  <Select.Item 
-    key="user1" 
+  <Select.Item
+    key="user1"
     icon={<IconUser />}
     description="Administrator"
   >
     John Doe
   </Select.Item>
-  <Select.Item 
-    key="user2" 
+  <Select.Item
+    key="user2"
     icon={<IconUser />}
     description="Editor"
     suffix="Online"
@@ -350,23 +353,23 @@ Groups related options together with an optional heading.
 
 ```jsx
 <Select placeholder="Select a color">
-  <Select.Item 
-    key="yellow" 
-    description="Child and light" 
+  <Select.Item
+    key="yellow"
+    description="Child and light"
     icon={<IconUser />}
   >
     Yellow
   </Select.Item>
-  <Select.Item 
-    key="red" 
-    description="Hot and strong" 
+  <Select.Item
+    key="red"
+    description="Hot and strong"
     prefix={<span>🔥</span>}
   >
     Red
   </Select.Item>
-  <Select.Item 
-    key="green" 
-    description="Fresh and calm" 
+  <Select.Item
+    key="green"
+    description="Fresh and calm"
     suffix={<Text color="#dark-03">#00A000</Text>}
   >
     Green
@@ -490,6 +493,7 @@ const groups = [
 ## Best Practices
 
 1. **Do**: Provide clear, descriptive labels and meaningful option text
+
    ```jsx
    <Select label="Shipping method">
      <Select.Item key="standard">Standard (5-7 days)</Select.Item>
@@ -498,6 +502,7 @@ const groups = [
    ```
 
 2. **Don't**: Use select for very long lists (use ComboBox or FilterPicker with search instead)
+
    ```jsx
    {/* Consider ComboBox or FilterPicker for 50+ options */}
    <Select label="Country">
@@ -506,6 +511,7 @@ const groups = [
    ```
 
 3. **Do**: Use sections to group related options logically
+
    ```jsx
    <Select label="Category">
      <Select.Section title="Popular">
@@ -518,6 +524,7 @@ const groups = [
    ```
 
 4. **Do**: Provide clear error messages for validation failures
+
    ```jsx
    <Select
      isRequired
@@ -530,6 +537,7 @@ const groups = [
    ```
 
 5. **Do**: Consider providing sensible defaults when appropriate
+
    ```jsx
    <Select label="Language" defaultSelectedKey="en">
      <Select.Item key="en">English</Select.Item>
@@ -538,6 +546,7 @@ const groups = [
    ```
 
 6. **Do**: Show loading state when options are being fetched
+
    ```jsx
    <Select isLoading label="Categories" placeholder="Loading...">
      {categories.map(cat => <Select.Item key={cat.id}>{cat.name}</Select.Item>)}
@@ -545,6 +554,7 @@ const groups = [
    ```
 
 7. **Accessibility**: Always provide meaningful labels
+
    ```jsx
    <Select label="Country" aria-label="Select your country">
      <Select.Item key="us">United States</Select.Item>

package/docs/components/fields/Switch.md

@@ -43,6 +43,7 @@ Customizes the root wrapper element of the component.
 Customizes the switch toggle element specifically.
 
 **Sub-elements:**
+
 - `Thumb` - The movable indicator inside the switch
 
 #### fieldStyles
@@ -138,11 +139,13 @@ const [isEnabled, setIsEnabled] = useState(false);
 ## Best Practices
 
 1. **Do**: Use clear, descriptive labels that indicate what the switch controls
+
    ```jsx
    <Switch>Enable email notifications</Switch>
    ```
 
 2. **Don't**: Use switches for actions that require additional steps
+
    ```jsx
    <Switch>Delete account</Switch> {/* Use Button instead */}
    ```

package/docs/components/fields/TextInput.md

@@ -55,6 +55,7 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root element of the component.
 
 **Sub-elements:**
+
 - `InputWrapper` – container around the input field
 - `Prefix` – wrapper around prefix content
 - `Suffix` – wrapper around suffix content
@@ -182,11 +183,13 @@ import { IconMail } from '@tabler/icons-react';
 ## Best Practices
 
 1. **Do**: Provide clear labels and helpful placeholder text
+
    ```jsx
    <TextInput label="Email Address" placeholder="you@example.com" />
    ```
 
 2. **Don't**: Use placeholder text as the only label
+
    ```jsx
    {/* Avoid this */}
    <TextInput placeholder="Enter your email" />

package/docs/components/fields/TextInputMapper.md

@@ -24,8 +24,7 @@ Supports all [Field properties](../../FieldProperties.md)
 
 ## Validation States
 
-`isValid` and `isInvalid` are forwarded to every key and value input, so the whole mapping list picks up
-the state.
+`isValid` and `isInvalid` are forwarded to every key and value input, so the whole mapping list picks up the state.
 
 ## Sub-elements
 

package/docs/components/form/Field.md

@@ -50,6 +50,7 @@ Supports [Base properties](../../BaseProperties.md)
 Customizes the field wrapper element.
 
 **Sub-elements:**
+
 - `Label` - The field label element
 - `Description` - The field description text
 - `Message` - Error or help message text
@@ -184,8 +185,7 @@ function ModernForm() {
 
 ## Creating Custom Input Components
 
-To create your own input component with built-in field support, use `useFieldProps`. It applies the provider
-and form context for you, so it is the only hook you need:
+To create your own input component with built-in field support, use `useFieldProps`. It applies the provider and form context for you, so it is the only hook you need:
 
 ```jsx
 import { forwardRef, useRef } from 'react';
@@ -308,11 +308,13 @@ valuePropsMapper: ({ value, onChange }) => ({
 ## Best Practices
 
 1. **✅ Do**: Use input components directly with field properties
+
    ```jsx
    <TextInput name="email" label="Email" isRequired />
    ```
 
 2. **❌ Don't**: Wrap input components in Field unnecessarily
+
    ```jsx
    <Field name="email" label="Email">
      <TextInput />
@@ -320,6 +322,7 @@ valuePropsMapper: ({ value, onChange }) => ({
    ```
 
 3. **✅ Do**: Use Field only for read-only content or custom components
+
    ```jsx
    <Field label="Status">
      <StatusDisplay />

package/docs/components/form/Form.md

@@ -569,6 +569,7 @@ export function ConfirmDeletionDialogForm({ name, onSubmit, onDismiss }) {
 ## Best Practices
 
 1. **Use direct field properties**: Pass field properties directly to input components instead of using Field wrapper
+
    ```jsx
    // Recommended
    <Input.Text name="email" label="Email" type="email" rules={[{ required: true }]} />
@@ -580,11 +581,13 @@ export function ConfirmDeletionDialogForm({ name, onSubmit, onDismiss }) {
    ```
 
 2. **Provide clear labels**: Always include descriptive labels for form fields
+
    ```jsx
    <Input.Text name="email" label="Email Address" type="email" />
    ```
 
 3. **Use appropriate validation**: Combine built-in validators for common cases and custom validators for complex logic
+
    ```jsx
    <Input.Text
      name="email"
@@ -598,6 +601,7 @@ export function ConfirmDeletionDialogForm({ name, onSubmit, onDismiss }) {
    ```
 
 4. **Handle errors gracefully**: Always provide feedback for validation and submission errors
+
    ```jsx
    <Form onSubmit={handleSubmit} onSubmitFailed={handleError}>
      {/* fields */}
@@ -606,6 +610,7 @@ export function ConfirmDeletionDialogForm({ name, onSubmit, onDismiss }) {
    ```
 
 5. **Use proper field types**: Choose appropriate input types for better UX and validation
+
    ```jsx
    <Input.Text type="email" />     {/* for email addresses */}
    <Input.Password />              {/* for passwords */}

package/docs/components/form/FormInstance.md

@@ -11,7 +11,7 @@ import { Form } from '@cube-dev/ui-kit';
 
 function MyComponent() {
   const [form] = Form.useForm();
-  
+
   return <Form form={form}>{/* form fields */}</Form>;
 }
 ```

package/docs/components/helpers/DisplayTransition.md

@@ -50,7 +50,7 @@ import { Block } from '@cube-dev/ui-kit';
 
 <DisplayTransition isShown={isVisible} duration={150}>
   {({ phase, isShown }) => (
-    <Block 
+    <Block
       data-phase={phase}
       mods={{ entered: phase === 'entered' }}
       styles={{
@@ -111,14 +111,14 @@ Longer durations can be used for more dramatic entrance and exit effects.
 ### With Callbacks
 
 ```jsx
-<DisplayTransition 
+<DisplayTransition
   isShown={isVisible}
   onRest={(transition) => {
     console.log(`${transition} transition completed`);
   }}
 >
   {({ phase, isShown }) => (
-    <Block 
+    <Block
       data-phase={phase}
       mods={{ entered: phase === 'entered' }}
     >
@@ -182,12 +182,14 @@ Set `preserveContent={false}` if you need the exit animation to reflect real-tim
 ## Animation Flow
 
 ### Enter Flow
+
 1. `isShown` changes from `false` to `true`
 2. Phase changes to `enter` (isShown = false)
 3. After next paint, phase changes to `entered` (isShown = true)
 4. After `duration` milliseconds, `onRest('enter')` fires
 
 ### Exit Flow
+
 1. `isShown` changes from `true` to `false`
 2. Phase changes to `exit` (isShown = false)
 3. After `duration` milliseconds, phase changes to `unmounted` and `onRest('exit')` fires
@@ -196,10 +198,11 @@ Set `preserveContent={false}` if you need the exit animation to reflect real-tim
 ## Best Practices
 
 1. **Match CSS duration with duration prop**: Ensure your CSS transition/animation duration matches the `duration` prop for proper timing
+
    ```jsx
    <DisplayTransition duration={300}>
      {({ phase }) => (
-       <Block 
+       <Block
          data-phase={phase}
          mods={{ entered: phase === 'entered' }}
          styles={{
@@ -217,10 +220,11 @@ Set `preserveContent={false}` if you need the exit animation to reflect real-tim
 2. **Use stable callbacks**: The component uses `useEvent` internally, but you should still avoid recreating callbacks on every render when possible
 
 3. **Animate on mount thoughtfully**: Set `animateOnMount={false}` for content that should appear immediately on SSR or first paint
+
    ```jsx
    <DisplayTransition isShown={true} animateOnMount={false}>
      {({ phase }) => (
-       <Block 
+       <Block
          data-phase={phase}
          mods={{ entered: phase === 'entered' }}
        >
@@ -250,6 +254,7 @@ The component automatically respects the user's motion preferences when `respect
 ### Screen Reader Considerations
 
 Since this is a purely visual transition component, ensure that:
+
 - Content changes are announced appropriately (use `aria-live` if needed)
 - Focus management is handled by parent components
 - Critical state changes aren't communicated only through animations
@@ -265,4 +270,3 @@ Since this is a purely visual transition component, ensure that:
 - [Modal](/components/Modal) - Uses DisplayTransition internally for overlay animations
 - [Popover](/components/Popover) - Can use DisplayTransition for custom entrance animations
 - [OverlayWrapper](/components/OverlayWrapper) - Another component that may benefit from transition management
-

package/docs/components/helpers/IconSwitch.md

@@ -120,6 +120,7 @@ function ExpandableItem({ isExpanded, onToggle }) {
 ## Best Practices
 
 1. **Prefer `contentKey`**: The component can derive a key from the child element type, but explicit keys are more reliable (especially for custom “same type, different meaning” icons):
+
    ```jsx
    // Good - explicit key
    <IconSwitch contentKey={isOpen ? 'open' : 'closed'}>