@cube-dev/ui-kit 0.0.0-canary-c210a8c → 0.0.0-canary-60981ef

package/docs/components/overlays/Toast.md

@@ -0,0 +1,285 @@
+# Toast
+
+Toast notifications provide brief, non-intrusive feedback to users about actions or events. They appear at the top center of the viewport and automatically dismiss after a configurable duration.
+
+## When to Use
+
+- Provide feedback after user actions (e.g., "Copied to clipboard")
+- Show success/error/warning messages that don't require user action
+- Display progress states for ongoing operations
+- Communicate non-critical information that doesn't interrupt workflow
+
+## Component
+
+---
+
+### Properties
+
+### Base Properties
+
+Supports [Base properties](/BaseProperties)
+
+### Styling Properties
+
+#### styles
+
+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
+
+## Themes
+
+Available themes:
+
+- `default` - Standard appearance
+- `success` - Positive feedback (green)
+- `danger` - Error or destructive action (red)
+- `warning` - Caution or attention needed (yellow)
+- `note` - Informational (blue)
+
+## Examples
+
+### Using useToast Hook
+
+The primary way to show toasts programmatically:
+
+```jsx
+const toast = useToast();
+
+// String shorthand
+toast.success('Copied to clipboard');
+
+// Object with options
+toast.success({
+  title: 'Success',
+  description: 'File copied to clipboard',
+  icon: <CustomIcon />,
+  duration: 3000,
+});
+
+// Available methods
+toast();           // Default theme
+toast.success();   // Success theme
+toast.danger();    // Danger theme
+toast.warning();   // Warning theme
+toast.note();      // Note theme
+toast.remove(id);  // Remove a toast by id
+```
+
+### Declarative Toast Component
+
+Use the `<Toast>` component for toasts that should be visible while mounted:
+
+```jsx
+// Simple toast (visible while mounted)
+<Toast theme="success">Saved successfully</Toast>
+
+// With description
+<Toast title="Success" description="Changes saved" theme="success" />
+```
+
+### Progress Toast
+
+Use `useProgressToast` for operations that have loading, success, and error states. The hook manages the entire lifecycle of the toast automatically.
+
+#### How It Works
+
+The `useProgressToast` hook accepts an optional options object that controls the toast state. The toast only appears after `isLoading: true` is seen — non-loading initial states are silently ignored until a loading cycle occurs.
+
+```tsx
+interface ProgressToastOptions {
+  isLoading: boolean;      // Whether the operation is in progress
+  title?: ReactNode;       // Primary message
+  description?: ReactNode; // Secondary message
+  theme?: ToastType;       // 'default' | 'success' | 'danger' | 'warning' | 'note'
+  icon?: ReactNode;        // Custom icon (theme-based icons applied automatically when not loading)
+  id?: Key;                // For deduplication
+}
+
+// Or pass empty value to immediately dismiss any existing toast
+type ProgressToastEmpty = null | undefined | false | {};
+```
+
+#### State Transitions
+
+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
+
+#### Basic Usage
+
+```jsx
+function SaveButton() {
+  const [status, setStatus] = useState('idle');
+  
+  useProgressToast(
+    status === 'saving'
+      ? { isLoading: true, title: 'Saving...' }
+      : status === 'success'
+        ? { isLoading: false, title: 'Saved!', theme: 'success' }
+        : status === 'error'
+          ? { isLoading: false, title: 'Failed to save', theme: 'danger' }
+          : null // idle state - no toast
+  );
+  
+  return <Button onPress={() => setStatus('saving')}>Save</Button>;
+}
+```
+
+#### With Error Handling
+
+```jsx
+function DataLoader() {
+  const { data, isLoading, error } = useQuery('data');
+  
+  useProgressToast(
+    isLoading
+      ? { isLoading: true, title: 'Loading data...' }
+      : error
+        ? { isLoading: false, title: 'Error', description: error.message, theme: 'danger' }
+        : { isLoading: false, title: 'Data loaded', theme: 'success' }
+  );
+  
+  return <div>{/* content */}</div>;
+}
+```
+
+#### Conditional Display
+
+Pass an empty value to prevent the toast from showing or to immediately remove an existing one:
+
+```jsx
+// Only show toast when needed
+useProgressToast(
+  shouldShowProgress 
+    ? { isLoading: true, title: 'Processing...' } 
+    : null
+);
+
+// All of these are equivalent "empty" values:
+useProgressToast(null);
+useProgressToast(undefined);
+useProgressToast(false);
+useProgressToast({});
+useProgressToast(); // no argument also works
+```
+
+#### Custom Icons
+
+When `isLoading` is `false`, the hook automatically applies theme-based icons. You can override this with a custom icon:
+
+```jsx
+useProgressToast({
+  isLoading: false,
+  title: 'Uploaded!',
+  theme: 'success',
+  icon: <IconCloudUpload />, // Custom icon instead of default checkmark
+});
+```
+
+#### Declarative Alternative
+
+For component-based usage, use `<Toast.Progress>`:
+
+```jsx
+<Toast.Progress
+  {...(isLoading
+    ? { isLoading: true, title: 'Saving...' }
+    : { isLoading: false, title: 'Saved!', theme: 'success' }
+  )}
+/>
+
+### Interactive Progress State Toggle
+
+<Story of={ToastStories.ProgressStateToggle} />
+
+### Deduplication
+
+Toasts with identical content are deduplicated. Clicking the same action multiple times will refresh the existing toast instead of creating duplicates:
+
+<Story of={ToastStories.Deduplication} />
+
+### Multiple Toasts
+
+Maximum 3 toasts are visible at once. When the limit is exceeded, the oldest toast is removed:
+
+<Story of={ToastStories.MultipleToasts} />
+
+## Toast Behavior
+
+### Positioning
+- Fixed at top center of the viewport
+- 16px from the top edge
+- Toasts stack vertically (newest at bottom)
+
+### Collapse on Hover
+- When hovering over toasts, they collapse to reveal content behind them
+- Only 8px of the newest toast remains visible
+- Moving the mouse away restores the full toast display
+
+### Auto-dismiss
+- Default duration: 5 seconds
+- Progress toasts remain visible while `isLoading` is true
+- Set `duration: null` for persistent toasts
+
+### Limits
+- Maximum 3 visible toasts
+- Progress toasts count toward the limit
+- At least 1 temporal toast is always allowed, even with 3 progress toasts
+
+## Accessibility
+
+### Keyboard Navigation
+
+- Toasts do not trap focus
+- Close button is keyboard accessible
+- Screen readers announce toast content
+
+### Screen Reader Support
+
+- Toasts are announced when they appear
+- Uses appropriate ARIA live regions for notifications
+
+### ARIA Properties
+
+- `aria-label` - Provides accessible label for close button
+
+## Best Practices
+
+1. **Do**: Use clear, concise messages
+
+   ```jsx
+   toast.success('Changes saved');
+   ```
+
+2. **Don't**: Use overly long or technical messages
+
+   ```jsx
+   toast.success('The database transaction completed successfully with no errors');
+   ```
+
+3. **Accessibility**: Keep toast messages brief and actionable
+
+4. **Performance**: Use deduplication for repeated actions to avoid toast spam
+
+## Related Components
+
+- [Item](/components/Item) - Base component used for toast rendering
+- [Alert](/components/Alert) - For persistent, inline feedback

package/docs/components/overlays/Tooltip.md

@@ -0,0 +1,371 @@
+# Tooltip
+
+Tooltips display informative text when users hover over or focus an element. They provide supplementary information about an element without cluttering the interface.
+
+## When to Use
+
+- Provide brief descriptions of buttons, icons, or other UI elements
+- Show keyboard shortcuts or additional context for actions
+- Display truncated text or labels in full
+- Explain unfamiliar terms or provide helpful hints
+- Add supplementary information without overwhelming the interface
+
+## Components
+
+This module exports three components that work together:
+
+- **`TooltipProvider`** - Convenience wrapper for simple tooltip use cases (recommended)
+- **`TooltipTrigger`** - Lower-level component for advanced tooltip scenarios
+- **`Tooltip`** - The tooltip content container (used with `TooltipTrigger`)
+
+## TooltipProvider (Recommended)
+
+The simplest way to add tooltips to your components. It combines `TooltipTrigger` and `Tooltip` for convenience.
+
+---
+
+### Properties
+
+### Base Properties
+
+Supports [Base properties](/docs/base-properties)
+
+### Styling Properties
+
+#### tooltipStyles
+
+Customizes the tooltip content container.
+
+**Sub-elements:**
+- None (tooltip tip is styled via `tipStyles` prop on `Tooltip` component)
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop: `width`.
+
+### Modifiers
+
+The `mods` property on the tooltip accepts the following modifiers you can override:
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| material | `boolean` | Enables material-style tooltip with pointer events |
+| light | `boolean` | Uses light color scheme instead of dark |
+| open | `boolean` | Indicates whether the tooltip is currently visible |
+
+## TooltipTrigger
+
+Lower-level component that wraps a trigger element and a `Tooltip`. Use this when you need more control over the tooltip content or behavior.
+
+---
+
+### Properties
+
+### Base Properties
+
+Supports [Base properties](/docs/base-properties)
+
+## Tooltip
+
+Display container for tooltip content. Has a directional arrow dependent on its placement. This component is typically used as a child of `TooltipTrigger` or automatically rendered by `TooltipProvider`.
+
+### Properties
+
+#### tipStyles
+
+Customizes the tooltip arrow (tip) element.
+
+#### showIcon
+
+`boolean` - Controls whether an icon should be displayed in the tooltip.
+
+#### placement
+
+`PlacementAxis` - Controls the position of the tooltip relative to its trigger. Options: `top`, `bottom`, `left`, `right`.
+
+#### isMaterial
+
+`boolean` - Enables material-style tooltip with auto pointer events.
+
+#### isLight
+
+`boolean` - Uses light color scheme for the tooltip.
+
+#### width
+
+Specifies the width of the tooltip.
+
+### Base Properties
+
+Supports [Base properties](/docs/base-properties)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the tooltip.
+
+**Sub-elements:**
+- None
+
+## Usage Patterns
+
+### Standard Pattern (Active Elements)
+
+For focusable and hoverable elements like `Button`, `Link`, `IconButton`, etc., use the standard pattern with `TooltipProvider`:
+
+```jsx
+<TooltipProvider title="Click to save">
+  <Button>Save</Button>
+</TooltipProvider>
+```
+
+Or with `TooltipTrigger`:
+
+```jsx
+<TooltipTrigger>
+  <Button>Save</Button>
+  <Tooltip>Click to save</Tooltip>
+</TooltipTrigger>
+```
+
+### Function Pattern (Non-Focusable Elements)
+
+For elements that don't have native DOM focus or hover support (like `div`, `span`, or custom components), use the function-as-child pattern:
+
+```jsx
+<TooltipProvider title="Additional information">
+  {(triggerProps, ref) => (
+    <div ref={ref} {...triggerProps}>
+      Hoverable content
+    </div>
+  )}
+</TooltipProvider>
+```
+
+With `TooltipTrigger`:
+
+```jsx
+<TooltipTrigger>
+  {(triggerProps, ref) => (
+    <span ref={ref} {...triggerProps}>
+      Custom element
+    </span>
+  )}
+  <Tooltip>Tooltip content</Tooltip>
+</TooltipTrigger>
+```
+
+### Different Placements
+
+Control where the tooltip appears relative to its trigger:
+
+```jsx
+<TooltipProvider title="Tooltip on the right" placement="right">
+  <Button>Hover me</Button>
+</TooltipProvider>
+```
+
+### Light Theme
+
+Use the light theme for tooltips on dark backgrounds:
+
+```jsx
+<TooltipProvider title="Light tooltip" isLight>
+  <Button>Hover me</Button>
+</TooltipProvider>
+```
+
+### Custom Delay
+
+Adjust how long the user must hover before the tooltip appears:
+
+```jsx
+<TooltipProvider title="Quick tooltip" delay={100}>
+  <Button>Fast tooltip</Button>
+</TooltipProvider>
+
+<TooltipProvider title="Slower tooltip" delay={1000}>
+  <Button>Slow tooltip</Button>
+</TooltipProvider>
+```
+
+### Custom Styling
+
+Customize the appearance of the tooltip:
+
+```jsx
+<TooltipProvider
+  title="Styled tooltip"
+  tooltipStyles={{
+    fill: '#purple',
+    color: '#white',
+    padding: '1.5x 2x',
+  }}
+>
+  <Button>Custom tooltip</Button>
+</TooltipProvider>
+```
+
+### Controlled Tooltip
+
+Programmatically control when the tooltip is shown:
+
+```jsx
+function ControlledExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <TooltipProvider
+      title="Controlled tooltip"
+      isOpen={isOpen}
+      onOpenChange={setIsOpen}
+    >
+      <Button onClick={() => setIsOpen(!isOpen)}>
+        Toggle tooltip
+      </Button>
+    </TooltipProvider>
+  );
+}
+```
+
+### Conditional Tooltip
+
+Show a tooltip only when certain conditions are met:
+
+```jsx
+<TooltipProvider title={hasError ? "Fix errors first" : null}>
+  <Button isDisabled={hasError}>Submit</Button>
+</TooltipProvider>
+```
+
+### Focus-Only Trigger
+
+Show tooltip only on focus, not on hover:
+
+```jsx
+<TooltipProvider title="Focus only" trigger="focus">
+  <Button>Focus me</Button>
+</TooltipProvider>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the trigger element, showing the tooltip after the delay
+- `Shift + Tab` - Moves focus away from the trigger, hiding the tooltip
+- Tooltips automatically appear on focus for keyboard users
+
+### Screen Reader Support
+
+- Tooltips use the `tooltip` ARIA role
+- Content is announced to screen readers when the tooltip appears
+- The trigger element maintains proper focus management
+- Tooltips are associated with their triggers via ARIA attributes
+
+### ARIA Properties
+
+- `aria-describedby` - Automatically set on the trigger to reference the tooltip
+- All standard ARIA labeling props are supported
+
+### Best Practices
+
+1. **Keep it brief** - Tooltips should contain concise, supplementary information
+   ```jsx
+   {/* Good */}
+   <TooltipProvider title="Save changes">
+     <Button><IconDeviceFloppy /></Button>
+   </TooltipProvider>
+
+   {/* Avoid */}
+   <TooltipProvider title="This button will save all your changes to the database and close the dialog. Make sure you review your changes before clicking.">
+     <Button>Save</Button>
+   </TooltipProvider>
+   ```
+
+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">
+     <Button theme="danger">Delete</Button>
+   </TooltipProvider>
+
+   {/* Avoid - essential action only in tooltip */}
+   <TooltipProvider title="Delete item">
+     <Button><IconX /></Button>
+   </TooltipProvider>
+   ```
+
+3. **Use appropriate delays** - Default delay (250ms) works for most cases
+   ```jsx
+   {/* Good - default delay */}
+   <TooltipProvider title="Info">
+     <Button>Action</Button>
+   </TooltipProvider>
+
+   {/* Consider longer delay for dense interfaces */}
+   <TooltipProvider title="Info" delay={500}>
+     <IconButton><IconInfo /></IconButton>
+   </TooltipProvider>
+   ```
+
+4. **Choose the right pattern** - Use function pattern only when necessary
+   ```jsx
+   {/* Good - standard pattern for active elements */}
+   <TooltipProvider title="Click me">
+     <Button>Action</Button>
+   </TooltipProvider>
+
+   {/* Good - function pattern for non-focusable elements */}
+   <TooltipProvider title="Info">
+     {(props, ref) => (
+       <div ref={ref} {...props}>Content</div>
+     )}
+   </TooltipProvider>
+
+   {/* Avoid - unnecessary function pattern */}
+   <TooltipProvider title="Click me">
+     {(props, ref) => (
+       <Button ref={ref} {...props}>Action</Button>
+     )}
+   </TooltipProvider>
+   ```
+
+5. **Provide meaningful context** - Ensure tooltip text is descriptive
+   ```jsx
+   {/* Good */}
+   <TooltipProvider title="Export as CSV">
+     <IconButton><IconDownload /></IconButton>
+   </TooltipProvider>
+
+   {/* Avoid */}
+   <TooltipProvider title="Click here">
+     <IconButton><IconDownload /></IconButton>
+   </TooltipProvider>
+   ```
+
+## Migration from activeWrap
+
+The `activeWrap` prop is deprecated. If you're using it, migrate to the function pattern:
+
+```jsx
+{/* Before (deprecated) */}
+<TooltipProvider title="Tooltip" activeWrap>
+  <span>Text</span>
+</TooltipProvider>
+
+{/* After */}
+<TooltipProvider title="Tooltip">
+  {(props, ref) => (
+    <span ref={ref} {...props}>
+      Text
+    </span>
+  )}
+</TooltipProvider>
+```
+
+## Related Components
+
+- [Button](../actions/Button.md) - Primary use case for tooltips
+- [Dialog](./Dialog.md) - For more complex interactive content