@cube-dev/ui-kit 0.0.0-canary-1f0dd2c → 0.0.0-canary-1d27aa0

package/docs/components/other/Calendar.md

@@ -1,14 +1,22 @@
 # Calendar
 
-`Calendar` renders a month grid for picking a single date. `RangeCalendar` picks a contiguous range, and `PeriodCalendar` picks a whole month, quarter or year. All three are the panels behind the date fields — [DatePicker](../fields/DatePicker.md), DateRangePicker and the [period pickers](../fields/PeriodPicker.md) — and they are built on React Aria's `useCalendar` / `useRangeCalendar`.
+`Calendar` renders a month grid for picking a single date. `RangeCalendar` picks
+a contiguous range, and `PeriodCalendar` picks a whole month, quarter or year.
+All three are the panels behind the date fields — [DatePicker](../fields/DatePicker.md),
+DateRangePicker and the
+[period pickers](../fields/PeriodPicker.md) — and they are built on
+React Aria's `useCalendar` / `useRangeCalendar`.
 
-The header title is the navigation: the month and the year are buttons that open a month list and a year list, so reaching a date two years out takes two clicks instead of twenty-four.
+The header title is the navigation: the month and the year are buttons that open
+a month list and a year list, so reaching a date two years out takes two clicks
+instead of twenty-four.
 
 ## When to Use
 
 - Embedding a calendar directly in a page or panel rather than behind a field
 - Building a custom date input that needs the same grid and states
-- Otherwise, prefer the date fields — they add the text input, label, validation and popover for you
+- Otherwise, prefer the date fields — they add the text input, label, validation
+  and popover for you
 
 ## Component
 
@@ -32,13 +40,14 @@ The header title is the navigation: the month and the year are buttons that open
 
 #### RangeCalendar
 
-Accepts React Aria's `AriaRangeCalendarProps` (a `{ start, end }` value) plus **`hasMonthYearNavigation`**.
+Accepts React Aria's `AriaRangeCalendarProps` (a `{ start, end }` value) plus
+**`hasMonthYearNavigation`**.
 
 #### PeriodCalendar
 
 - **`picker`** `'month' | 'quarter' | 'year'` — Which period the panel selects
 - **`value`** `DateValue | null` — The selected period, represented by its start date
-- **`minValue`** / **`maxValue`** `DateValue | null` — Range limits; a period is disabled only when _all_ of it falls outside
+- **`minValue`** / **`maxValue`** `DateValue | null` — Range limits; a period is disabled only when *all* of it falls outside
 - **`isDateUnavailable`** `(date: DateValue) => boolean` — Called with the period's start date
 - **`isDisabled`** `boolean`
 - **`autoFocus`** `boolean` — Moves focus into the grid on mount
@@ -52,16 +61,16 @@ Supports [Base properties](../../BaseProperties.md)
 
 Day cells and period cells share one set of modifiers:
 
-| Modifier      | Type      | Description                                      |
-| ------------- | --------- | ------------------------------------------------ |
-| `selected`    | `boolean` | The cell is part of the current selection        |
-| `current`     | `boolean` | The cell contains today                          |
-| `outside`     | `boolean` | The cell belongs to an adjacent month or decade  |
-| `rangeHover`  | `boolean` | The whole row is highlighted (week mode)         |
-| `pressed`     | `boolean` | The cell is being pressed                        |
-| `focused`     | `boolean` | The cell holds keyboard focus                    |
-| `disabled`    | `boolean` | The cell is outside `minValue` / `maxValue`      |
-| `unavailable` | `boolean` | `isDateUnavailable` returned `true` for the cell |
+| Modifier      | Type      | Description                                          |
+| ------------- | --------- | ---------------------------------------------------- |
+| `selected`    | `boolean` | The cell is part of the current selection            |
+| `current`     | `boolean` | The cell contains today                              |
+| `outside`     | `boolean` | The cell belongs to an adjacent month or decade      |
+| `rangeHover`  | `boolean` | The whole row is highlighted (week mode)             |
+| `pressed`     | `boolean` | The cell is being pressed                            |
+| `focused`     | `boolean` | The cell holds keyboard focus                        |
+| `disabled`    | `boolean` | The cell is outside `minValue` / `maxValue`          |
+| `unavailable` | `boolean` | `isDateUnavailable` returned `true` for the cell     |
 
 ## Examples
 
@@ -84,7 +93,8 @@ import { parseDate } from '@internationalized/date';
 
 ### Limited Range
 
-Months and years that fall entirely outside `minValue` / `maxValue` are disabled in the month and year lists too, and the navigation arrows stop at the edge.
+Months and years that fall entirely outside `minValue` / `maxValue` are disabled
+in the month and year lists too, and the navigation arrows stop at the edge.
 
 ```jsx
 <Calendar
@@ -143,25 +153,32 @@ Month and year lists:
 ### Screen Reader Support
 
 - Each panel is a `grid`, labelled `Months` / `Quarters` / `Years`
-- The visible month and year are the calendar's `heading`, and their buttons are the controls that open the lists
+- The visible month and year are the calendar's `heading`, and their buttons are
+  the controls that open the lists
 - Cells expose `aria-selected`; out-of-range periods are `disabled`
 
 ## Best Practices
 
-1. **Do**: bound the calendar when the domain is bounded — the month and year lists disable everything out of range, which is far clearer than letting the user land somewhere unselectable.
+1. **Do**: bound the calendar when the domain is bounded — the month and year
+   lists disable everything out of range, which is far clearer than letting the
+   user land somewhere unselectable.
 
    ```jsx
    <Calendar minValue={today(getLocalTimeZone())} />
    ```
 
-2. **Don't**: reach for `PeriodCalendar` to pick a day. Its value is always the _start_ of a period, never an exact date.
+2. **Don't**: reach for `PeriodCalendar` to pick a day. Its value is always the
+   *start* of a period, never an exact date.
 
-3. **Accessibility**: always give a standalone calendar an `aria-label` — inside a field the label comes from the field.
+3. **Accessibility**: always give a standalone calendar an `aria-label` — inside
+   a field the label comes from the field.
 
 ## Suggested Improvements
 
-- Range calendars paint every day in the range the same way; distinct start/end caps would read better for long ranges.
-- Multi-month (`visibleDuration`) layouts are not implemented; the header falls back to a plain title when a range spans more than one month.
+- Range calendars paint every day in the range the same way; distinct start/end
+  caps would read better for long ranges.
+- Multi-month (`visibleDuration`) layouts are not implemented; the header falls
+  back to a plain title when a range spans more than one month.
 
 ## Related Components
 

package/docs/components/other/CubeLogo.md

@@ -47,7 +47,7 @@ That means the swap costs no re-render, is correct during SSR and before hydrati
 
 ### Pinning a scheme
 
-`@dark` is a _state_, and it is resolved against the **document**. Where the background is known but the document scheme does not describe it, pass `scheme` to pin one mark:
+`@dark` is a *state*, and it is resolved against the **document**. Where the background is known but the document scheme does not describe it, pass `scheme` to pin one mark:
 
 ```jsx
 {/* A fixed-dark panel inside a light app */}

package/docs/components/overlays/Dialog.md

@@ -36,7 +36,6 @@ Supports [Base properties](../../BaseProperties.md)
 Customizes the root element of the dialog.
 
 **Sub-elements:**
-
 - `Dialog` - The main dialog container
 - `Content` - The content area wrapper
 - `Header` - The header section wrapper
@@ -162,7 +161,6 @@ The `mods` property accepts the following modifiers you can override:
 ## Best Practices
 
 1. **Do**: Provide clear titles and actionable buttons
-
    ```jsx
    <Dialog>
      <Header>
@@ -179,7 +177,6 @@ The `mods` property accepts the following modifiers you can override:
    ```
 
 2. **Don't**: Use dialogs for trivial notifications
-
    ```jsx
    {/* Avoid using dialogs for simple success messages */}
    <Dialog>

package/docs/components/overlays/DialogContainer.md

@@ -172,7 +172,6 @@ function ConditionalDialog() {
 ## Best Practices
 
 1. **Do**: Use DialogContainer for dialogs without specific triggers
-
    ```jsx
    <DialogContainer isOpen={showErrorDialog} onDismiss={clearError}>
      <Dialog>
@@ -187,7 +186,6 @@ function ConditionalDialog() {
    ```
 
 2. **Don't**: Use DialogContainer when DialogTrigger is more appropriate
-
    ```jsx
    {/* Prefer DialogTrigger when you have a specific trigger */}
    <DialogContainer isOpen={buttonPressed}>

package/docs/components/overlays/DialogForm.md

@@ -188,7 +188,7 @@ When you need custom action buttons, use `noActions` prop and the render functio
     <>
       <Input.Text name="field1" label="Field 1" />
       <Input.Text name="field2" label="Field 2" />
-
+      
       <ButtonGroup>
         <SubmitButton>Save</SubmitButton>
         <Button onPress={() => {
@@ -263,26 +263,22 @@ See [Dialog Accessibility](./Dialog.md#accessibility) and [Form Accessibility](.
 ## Best Practices
 
 1. **Use useDialogContainer for programmatic control**: Preferred method for better state management
-
    ```jsx
    const dialog = useDialogContainer(MyFormDialog);
    dialog.open({ initialData, onSubmit: handleSubmit });
    ```
 
 2. **Provide clear titles**: Always set a descriptive `title` for context
-
    ```jsx
    <DialogForm title="Edit User Profile" onSubmit={save}>
    ```
 
 3. **Use danger theme for destructive actions**: Apply `danger` for delete/remove operations
-
    ```jsx
    <DialogForm title="Delete Item" danger submitProps={{ label: 'Delete' }}>
    ```
 
 4. **Customize button labels**: Make action buttons specific to the task
-
    ```jsx
    <DialogForm
      title="Create Project"
@@ -292,7 +288,6 @@ See [Dialog Accessibility](./Dialog.md#accessibility) and [Form Accessibility](.
    ```
 
 5. **Handle submission errors**: Implement `onSubmitFailed` for error handling
-
    ```jsx
    <DialogForm
      onSubmit={save}
@@ -312,3 +307,4 @@ See [Dialog Accessibility](./Dialog.md#accessibility) and [Form Accessibility](.
 - [Form](../form/Form.md) - Form component with validation
 - [DialogTrigger](./DialogTrigger.md) - Alternative: manages dialog open/close state
 - [AlertDialog](./AlertDialog.md) - For simple confirmations without forms
+

package/docs/components/overlays/DialogTrigger.md

@@ -36,7 +36,7 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`targetRef`** — The ref of the element the Dialog should visually attach itself to
 - **`styles`** — The style map for the overlay
 - **`shouldCloseOnInteractOutside`** — Function to determine if overlay should close on outside interaction
-- **`shouldRestoreFocus`** `boolean` (default: `true`) — Whether focus returns to the trigger when the dialog closes. Only needed for a surface that claims focus _later_ than the restore (async load, entry animation); an action that focuses the surface it opens is already left alone — see [Focus Management](#best-practices)
+- **`shouldRestoreFocus`** `boolean` (default: `true`) — Whether focus returns to the trigger when the dialog closes. Only needed for a surface that claims focus *later* than the restore (async load, entry animation); an action that focuses the surface it opens is already left alone — see [Focus Management](#best-practices)
 
 ### Base Properties
 
@@ -172,7 +172,6 @@ function ControlledDialog() {
 ## Best Practices
 
 1. **Do**: Provide clear trigger labels
-
    ```jsx
    <DialogTrigger>
      <Button>Edit Profile</Button>
@@ -181,7 +180,6 @@ function ControlledDialog() {
    ```
 
 2. **Don't**: Use vague trigger text
-
    ```jsx
    <DialogTrigger>
      <Button>Click</Button>
@@ -189,7 +187,7 @@ function ControlledDialog() {
    </DialogTrigger>
    ```
 
-3. **Focus Management**: Closing the dialog returns focus to the trigger, unless the action that closed it already moved focus somewhere else — an action that opens a panel or another dialog just focuses that surface, and the trigger leaves it alone. A single `focus()` from a mount effect is enough; no retry loop is needed. Reach for `shouldRestoreFocus={false}` only when the opened surface claims focus _later_ than the restore (after an async load or an entry animation), where the trigger would otherwise take focus first and flash.
+3. **Focus Management**: Closing the dialog returns focus to the trigger, unless the action that closed it already moved focus somewhere else — an action that opens a panel or another dialog just focuses that surface, and the trigger leaves it alone. A single `focus()` from a mount effect is enough; no retry loop is needed. Reach for `shouldRestoreFocus={false}` only when the opened surface claims focus *later* than the restore (after an async load or an entry animation), where the trigger would otherwise take focus first and flash.
 4. **Mobile Considerations**: Use appropriate mobile types for better UX
 5. **Dismissible**: Make modal dialogs dismissible unless absolutely necessary
 

package/docs/components/overlays/Notifications.md

@@ -25,7 +25,6 @@ Supports [Base properties](../../BaseProperties.md)
 Customizes the root element of the notification.
 
 **Sub-elements:**
-
 - `Description` - The description text area below the title
 
 ## Variants
@@ -322,7 +321,6 @@ Collapse is disabled when notifications are present, since notifications require
 ## Best Practices
 
 1. **Do**: Use notifications for action-oriented messages
-
    ```jsx
    notify({
      theme: 'success',
@@ -336,19 +334,16 @@ Collapse is disabled when notifications are present, since notifications require
    ```
 
 2. **Don't**: Use notifications for simple messages without actions — use Toast instead
-
    ```jsx
    // Use toast.success('Copied to clipboard') instead
    ```
 
 3. **Do**: Provide explicit `id` for persistent and stored notifications
-
    ```jsx
    notify({ id: 'deploy:123', persistent: true, ... });
    ```
 
 4. **Do**: Place the dismiss action last for consistent right-side positioning
-
    ```jsx
    notify({
      actions: (
@@ -361,7 +356,6 @@ Collapse is disabled when notifications are present, since notifications require
    ```
 
 5. **Do**: When using `isDismissable: false`, always provide actions — the user needs a way to interact
-
    ```jsx
    // isDismissable: false hides the default "Dismiss" button and Escape key,
    // but actions with closeOnPress (default true) still close the notification.
@@ -378,7 +372,6 @@ Collapse is disabled when notifications are present, since notifications require
    ```
 
 6. **Do**: Return `false` from `onPress` to keep the notification when the user cancels a confirmation flow
-
    ```jsx
    <Notification.Action
      onPress={async () => {

package/docs/components/overlays/Toast.md

@@ -30,7 +30,6 @@ Supports [Base properties](../../BaseProperties.md)
 Customizes the root element of the toast. The toast uses the `Item` component with `type="card"` internally.
 
 **Sub-elements:**
-
 - `Label` - Primary content text
 - `Description` - Secondary content text
 - `Icon` - Icon container
@@ -113,20 +112,17 @@ type ProgressToastEmpty = null | undefined | false | {};
 The hook requires a loading cycle (`isLoading: true`) before any toast becomes visible. If the initial state is not loading, no toast is shown until `isLoading: true` is passed. The hook handles three main scenarios:
 
 **1. Loading State** (`isLoading: true`) — triggers initial appearance
-
 - Toast appears immediately and persists until `isLoading` becomes `false`
 - No auto-dismiss timer while loading
 - This is the only state that can trigger the initial appearance of the toast
 
 **2. Result State** (`isLoading: false` with content)
-
 - Only shown after a prior loading state — ignored if loading was never seen
 - When transitioning from loading to not loading, the toast updates to show the result
 - Result toast auto-dismisses after 3 seconds
 - Theme-based icons are automatically applied (success checkmark, danger X, etc.)
 
 **3. Dismissed** (empty value, no argument, or no title when not loading)
-
 - Pass `null`, `undefined`, `false`, `{}`, or call with no argument to immediately remove any existing toast
 - Also resets the loading gate, so the next toast cycle requires `isLoading: true` again
 - Useful for conditional rendering or cleanup
@@ -136,7 +132,7 @@ The hook requires a loading cycle (`isLoading: true`) before any toast becomes v
 ```jsx
 function SaveButton() {
   const [status, setStatus] = useState('idle');
-
+  
   useProgressToast(
     status === 'saving'
       ? { isLoading: true, title: 'Saving...' }
@@ -146,7 +142,7 @@ function SaveButton() {
           ? { isLoading: false, title: 'Failed to save', theme: 'danger' }
           : null // idle state - no toast
   );
-
+  
   return <Button onPress={() => setStatus('saving')}>Save</Button>;
 }
 ```
@@ -156,7 +152,7 @@ function SaveButton() {
 ```jsx
 function DataLoader() {
   const { data, isLoading, error } = useQuery('data');
-
+  
   useProgressToast(
     isLoading
       ? { isLoading: true, title: 'Loading data...' }
@@ -164,7 +160,7 @@ function DataLoader() {
         ? { isLoading: false, title: 'Error', description: error.message, theme: 'danger' }
         : { isLoading: false, title: 'Data loaded', theme: 'success' }
   );
-
+  
   return <div>{/* content */}</div>;
 }
 ```
@@ -176,8 +172,8 @@ Pass an empty value to prevent the toast from showing or to immediately remove a
 ```jsx
 // Only show toast when needed
 useProgressToast(
-  shouldShowProgress
-    ? { isLoading: true, title: 'Processing...' }
+  shouldShowProgress 
+    ? { isLoading: true, title: 'Processing...' } 
     : null
 );
 
@@ -206,7 +202,7 @@ useProgressToast({
 
 For component-based usage, use `<Toast.Progress>`:
 
-````jsx
+```jsx
 <Toast.Progress
   {...(isLoading
     ? { isLoading: true, title: 'Saving...' }
@@ -275,7 +271,7 @@ Maximum 3 toasts are visible at once. When the limit is exceeded, the oldest toa
 
    ```jsx
    toast.success('Changes saved');
-````
+   ```
 
 2. **Don't**: Use overly long or technical messages
 

package/docs/components/overlays/Tooltip.md

@@ -59,7 +59,6 @@ Supports [Base properties](../../BaseProperties.md)
 Customizes the root element of the tooltip.
 
 **Sub-elements:**
-
 - None
 
 ### Style Properties
@@ -139,6 +138,18 @@ Control where the tooltip appears relative to its trigger:
 </TooltipProvider>
 ```
 
+### Long Content
+
+The tooltip is capped at `36x` wide (or the viewport minus `4x`, whichever is smaller) and wraps
+its content to stay inside that cap. Runs with no spaces — URLs, tokens, identifiers, error strings —
+are broken mid-word rather than allowed to overflow the bubble.
+
+```jsx
+<TooltipProvider title="https://cubecloud.example.com/deployments/12345/schema/files/model/cubes/very_long_cube_name.yml">
+  <Button>Hover me</Button>
+</TooltipProvider>
+```
+
 ### Light Theme
 
 Use the light theme for tooltips on dark backgrounds:
@@ -245,7 +256,6 @@ Show tooltip only on focus, not on hover:
 ### Best Practices
 
 1. **Keep it brief** - Tooltips should contain concise, supplementary information
-
    ```jsx
    {/* Good */}
    <TooltipProvider title="Save changes">
@@ -259,7 +269,6 @@ Show tooltip only on focus, not on hover:
    ```
 
 2. **Don't hide critical information** - Never put essential information only in a tooltip
-
    ```jsx
    {/* Good - tooltip adds context */}
    <TooltipProvider title="Permanently delete this item">
@@ -273,7 +282,6 @@ Show tooltip only on focus, not on hover:
    ```
 
 3. **Use appropriate delays** - Default delay (250ms) works for most cases
-
    ```jsx
    {/* Good - default delay */}
    <TooltipProvider title="Info">
@@ -287,7 +295,6 @@ Show tooltip only on focus, not on hover:
    ```
 
 4. **Choose the right pattern** - Use function pattern only when necessary
-
    ```jsx
    {/* Good - standard pattern for active elements */}
    <TooltipProvider title="Click me">
@@ -310,7 +317,6 @@ Show tooltip only on focus, not on hover:
    ```
 
 5. **Provide meaningful context** - Ensure tooltip text is descriptive
-
    ```jsx
    {/* Good */}
    <TooltipProvider title="Export as CSV">

package/docs/components/overlays/UseDialogContainer.md

@@ -189,14 +189,14 @@ function UserFormDialog({ onSubmit, initialData, onCancel }) {
         label: 'Cancel'
       }}
     >
-      <Form.Item
-        name="name"
+      <Form.Item 
+        name="name" 
         rules={[{ required: true, message: 'Name is required' }]}
       >
         <TextInput label="Name" />
       </Form.Item>
-      <Form.Item
-        name="email"
+      <Form.Item 
+        name="email" 
         rules={[
           { required: true, message: 'Email is required' },
           { type: 'email', message: 'Please enter a valid email' }
@@ -392,7 +392,7 @@ The `rendered` property **must** be included in your component tree, or the hook
 // ✅ Correct usage
 function App() {
   const dialog = useDialogContainer(MyDialog);
-
+  
   return (
     <div>
       <Button onPress={() => dialog.open({ message: 'Hello' })}>Open</Button>
@@ -404,7 +404,7 @@ function App() {
 // ❌ Incorrect usage - will throw error
 function App() {
   const dialog = useDialogContainer(MyDialog);
-
+  
   return (
     <div>
       <Button onPress={() => dialog.open({ message: 'Hello' })}>Open</Button>
@@ -424,7 +424,6 @@ function App() {
 ### Container Props Priority
 
 When both `defaultContainerProps` and runtime `containerProps` are provided:
-
 - Runtime `containerProps` override `defaultContainerProps`
 - Deep merging is performed for nested objects
 - Arrays are replaced entirely (no merging)
@@ -432,7 +431,6 @@ When both `defaultContainerProps` and runtime `containerProps` are provided:
 ## Best Practices
 
 1. **Always include `rendered`**: Place `{dialog.rendered}` in your component tree
-
    ```tsx
    return (
      <div>
@@ -443,35 +441,32 @@ When both `defaultContainerProps` and runtime `containerProps` are provided:
    ```
 
 2. **Use TypeScript for type safety**: The hook automatically infers prop types from your dialog component
-
    ```tsx
    interface MyDialogProps {
      title: string;
      onConfirm: () => void;
    }
-
+   
    function MyDialog(props: MyDialogProps) {
      return <Dialog>{/* ... */}</Dialog>;
    }
-
+   
    const dialog = useDialogContainer(MyDialog); // Props type is automatically inferred
    ```
 
 3. **Handle cleanup in dialog components**: Ensure your dialog components handle their own cleanup
-
    ```tsx
    function MyDialog({ onClose, onSubmit }) {
      const handleSubmit = async (data) => {
        await onSubmit(data);
        onClose(); // Close dialog after successful submission
      };
-
+     
      return <Dialog>{/* ... */}</Dialog>;
    }
    ```
 
 4. **Use default container props for common patterns**: Set common dialog behaviors once
-
    ```tsx
    const dialog = useDialogContainer(MyDialog, {
      isDismissable: true,
@@ -480,13 +475,12 @@ When both `defaultContainerProps` and runtime `containerProps` are provided:
    ```
 
 5. **Separate concerns**: Keep dialog content components focused and reusable
-
    ```tsx
    // Good: Focused dialog component
    function ConfirmDialog({ message, onConfirm }) {
      return <Dialog>{/* Simple confirmation UI */}</Dialog>;
    }
-
+   
    // Avoid: Dialog component with complex business logic
    function OverlyComplexDialog({ userId, permissions, settings }) {
      // Too much business logic here

package/docs/components/status/LoadingAnimation.md

@@ -39,6 +39,12 @@ These properties allow direct style application without using the `styles` prop:
 
 ## Colors
 
-The cube's three faces come from the shared isometric-cube tokens (`#loading-face-1` … `#loading-face-3`), a near-neutral ramp positioned by a WCAG floor against `#surface`. Each face therefore keeps the same separation from the page in light, dark, and high contrast, and follows a re-seeded brand hue as a tint rather than as a color. There is no `color` prop to override — recolouring one face and not the others would break the shading.
-
-[`NoDataIcon`](../other/NoDataIcon.md) draws its empty crate from the same three tokens, so a loading table and an empty table read as the same object.
+The cube's three faces come from the shared isometric-cube tokens
+(`#loading-face-1` … `#loading-face-3`), a near-neutral ramp positioned by a WCAG
+floor against `#surface`. Each face therefore keeps the same separation from the
+page in light, dark, and high contrast, and follows a re-seeded brand hue as a
+tint rather than as a color. There is no `color` prop to override — recolouring
+one face and not the others would break the shading.
+
+[`NoDataIcon`](../other/NoDataIcon.md) draws its empty crate from the same
+three tokens, so a loading table and an empty table read as the same object.