@cube-dev/ui-kit 0.120.1 → 0.121.1

package/docs/components/organisms/FileTabs.md

@@ -0,0 +1,39 @@
+# FileTabs
+
+A tab bar for file-like items with close buttons and dirty state indicators. Designed for editor-style interfaces.
+
+## When to Use
+
+- Code editors or file editors
+- Multi-document interfaces
+- Tabbed interfaces with close/dirty indicators
+
+## Properties
+
+- **`activeKey`** `string` — Controlled active tab key
+- **`defaultActiveKey`** `string` — Default active tab key (uncontrolled)
+- **`onTabClick`** `(key: string) => void` — Callback when a tab is clicked
+- **`onTabClose`** `(key: string) => void` — Callback when a tab's close button is clicked
+- **`isClosable`** `boolean` (default: `true`) — Whether tabs can be closed
+- **`paneStyles`** `Styles` — Custom styles for the tab pane area
+
+### Style Defaults
+
+- Tab `radius` — `1r 1r 0 0`
+- Tab `padding` — `1x 1.5x`
+- Tab `fill` — `#dark.04` (active tabs use `#white`)
+- Tab gap — `.5x`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<FileTabs defaultActiveKey="1" onTabClose={(key) => removeTab(key)}>
+  <FileTabs.Tab key="1" title="index.ts" />
+  <FileTabs.Tab key="2" title="styles.css" isDirty />
+  <FileTabs.Tab key="3" title="readme.md" />
+</FileTabs>
+```

package/docs/components/organisms/StatsCard.md

@@ -0,0 +1,40 @@
+# StatsCard
+
+A card displaying a metric with title and value. Extends `Card` with a vertical layout showing label above value.
+
+## When to Use
+
+- Dashboard metrics
+- KPI displays
+- Summary statistics
+
+## Properties
+
+- **`title`** `ReactNode` — Label for the metric
+- **`value`** `string | number | ReactNode` — The metric value
+- **`suffix`** `string | number | ReactNode` — Optional suffix (e.g. unit, "%")
+
+### Style Defaults
+
+Extends Card with:
+
+- `display` — `flex`
+- `placeContent` — `space-between`
+- `gap` — `1x`
+- `border` — none
+- `shadow` — `0 2px 6px #dark.10`
+- `padding` — `2.5x`
+
+### Base Properties
+
+Extends [Card](../content/Card.md) and supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<StatsCard title="Users" value={1234} />
+
+<StatsCard title="Growth" value={12} suffix="%" />
+
+<StatsCard title="Revenue" value="$1.2M" />
+```

package/docs/components/other/CloudLogo.md

@@ -0,0 +1,33 @@
+# CloudLogo
+
+A Cube Cloud logo button. Extends `Button` with `type="clear"` and brand styling. Used for navigation branding in app headers.
+
+## When to Use
+
+- App header branding
+- Navigation to home/dashboard
+
+## Properties
+
+Extends [Button](../actions/Button.md) props (`onPress`, `to`, `href`, etc.).
+
+### Style Defaults
+
+- `type` — `clear`
+- `padding` — `0`
+- `gap` — `0`
+- `fill` — `#clear`
+- `border` — `0`
+- `radius` — `0`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<CloudLogo onPress={() => navigate('/')} />
+
+<CloudLogo to="/" />
+```

package/docs/components/overlays/AlertDialog.md

@@ -0,0 +1,51 @@
+# AlertDialog
+
+A modal dialog for important messages that require user acknowledgment. Extends `Dialog` with predefined confirm/cancel actions. Not dismissable by default.
+
+## When to Use
+
+- Confirmation dialogs
+- Error or warning messages
+- Destructive action confirmations
+
+## Properties
+
+- **`title`** `string` — Dialog title
+- **`content`** `ReactNode` — Dialog body content
+- **`danger`** `boolean` — Applies danger styling for destructive actions
+- **`noActions`** `boolean` — Hide the action buttons entirely
+- **`actions`** `object` — Customize buttons:
+  - `confirm` — Confirm button props or `false` to hide (default: `{ label: 'Ok', type: 'primary' }`)
+  - `cancel` — Cancel button props or `true` to show (default: hidden, uses `{ label: 'Cancel' }`)
+  - `secondary` — Optional secondary button props
+
+### Base Properties
+
+Extends [Dialog](./Dialog.md) and supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+### Confirmation dialog
+
+```jsx
+<DialogTrigger>
+  <Button>Delete Item</Button>
+  <AlertDialog
+    title="Confirm Delete"
+    content="Are you sure you want to delete this item?"
+    actions={{
+      confirm: { label: 'Delete', type: 'danger' },
+      cancel: true,
+    }}
+  />
+</DialogTrigger>
+```
+
+### Info dialog (confirm only)
+
+```jsx
+<AlertDialog
+  title="Update Available"
+  content="A new version is available. Please refresh to update."
+/>
+```

package/docs/components/overlays/Dialog.md

@@ -0,0 +1,200 @@
+# Dialog
+
+Dialogs are windows containing contextual information, tasks, or workflows that appear over the user interface. Depending on the kind of Dialog, further interactions may be blocked until the Dialog is acknowledged.
+
+## When to Use
+
+- Display important information or actions that require user attention
+- Confirm or cancel user actions before proceeding
+- Collect user input in a focused, contextual interface
+- Show complex workflows or forms that need dedicated space
+- Present alerts or notifications that require user acknowledgment
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** — Dialog content (Header, Content, Footer, etc.)
+- **`size`** `'small' | 'medium' | 'large' | 'S' | 'M' | 'L'` (default: `S`) — Dialog size
+- **`styles`** — Custom styles for the dialog root
+- **`closeButtonStyles`** — Custom styles for the close button
+- **`isDismissable`** `boolean` (default: `false`) — Whether the dialog is dismissable (shows close button, allows Escape key)
+- **`onDismiss`** `function` — Callback fired when the dialog is dismissed
+- **`closeIcon`** — Custom close icon element
+- **`role`** `'dialog' | 'alertdialog'` (default: `dialog`) — ARIA role for the dialog
+- **`onBlur`** `function` — Callback fired when the dialog loses focus
+- **`onFocus`** `function` — Callback fired when the dialog receives focus
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the dialog.
+
+**Sub-elements:**
+- `Dialog` - The main dialog container
+- `Content` - The content area wrapper
+- `Header` - The header section wrapper
+- `Footer` - The footer section wrapper
+
+#### closeButtonStyles
+
+Customizes the close button appearance.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop: `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `opacity`, `overflow`, `scrollbar`, `hide`, `outline`, `textAlign`, `resize`.
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+- **`dismissable`** `boolean` — Applied when the dialog can be dismissed with close button or Escape key
+
+## Variants
+
+### Types
+
+- `dialog` - Standard dialog for general content (default)
+- `alertdialog` - Alert dialog for critical notifications or confirmations
+
+### Sizes
+
+- `small` / `S` - Compact dialog for simple content (360px width)
+- `medium` / `M` - Standard dialog for moderate content (479px width)
+- `large` / `L` - Large dialog for complex content (798px width)
+
+## Examples
+
+### Basic Dialog
+
+```jsx
+<Dialog>
+  <Header>
+    <Title>Dialog Title</Title>
+  </Header>
+  <Content>
+    <Paragraph>Dialog content goes here.</Paragraph>
+  </Content>
+  <Footer>
+    <Button onPress={close}>Close</Button>
+  </Footer>
+</Dialog>
+```
+
+### Dismissable Dialog
+
+```jsx
+<Dialog isDismissable onDismiss={close}>
+  <Header>
+    <Title>Dismissable Dialog</Title>
+  </Header>
+  <Content>
+    <Paragraph>You can close this dialog with the close button or Escape key.</Paragraph>
+  </Content>
+</Dialog>
+```
+
+### Custom Size Dialog
+
+```jsx
+<Dialog size="large">
+  <Header>
+    <Title>Large Dialog</Title>
+  </Header>
+  <Content>
+    <Paragraph>This dialog uses the large size variant.</Paragraph>
+  </Content>
+</Dialog>
+```
+
+### Alert Dialog
+
+```jsx
+<Dialog role="alertdialog">
+  <Header>
+    <Title>Confirm Action</Title>
+  </Header>
+  <Content>
+    <Paragraph>Are you sure you want to delete this item? This action cannot be undone.</Paragraph>
+  </Content>
+  <Footer>
+    <Button type="danger" onPress={confirmDelete}>Delete</Button>
+    <Button onPress={close}>Cancel</Button>
+  </Footer>
+</Dialog>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus between interactive elements within the dialog
+- `Shift + Tab` - Moves focus backward between interactive elements
+- `Escape` - Dismisses the dialog if `isDismissable` is true
+- `Enter/Space` - Activates focused buttons or interactive elements
+
+### Screen Reader Support
+
+- Dialog announces as "dialog" or "alertdialog" based on role
+- Focus is trapped within the dialog when open
+- Focus returns to the trigger element when dialog closes
+- Dialog title and content are properly announced
+- State changes and actions are communicated to screen readers
+
+### ARIA Properties
+
+- `aria-labelledby` - Links dialog to its title element automatically
+- `aria-describedby` - Links dialog to its description content
+- `aria-modal` - Set to true for modal dialogs to indicate exclusive interaction
+- `role` - Set to "dialog" or "alertdialog" based on content type
+
+## Best Practices
+
+1. **Do**: Provide clear titles and actionable buttons
+   ```jsx
+   <Dialog>
+     <Header>
+       <Title>Save Changes</Title>
+     </Header>
+     <Content>
+       <Paragraph>Your changes will be saved to the document.</Paragraph>
+     </Content>
+     <Footer>
+       <Button type="primary" onPress={save}>Save</Button>
+       <Button onPress={close}>Cancel</Button>
+     </Footer>
+   </Dialog>
+   ```
+
+2. **Don't**: Use dialogs for trivial notifications
+   ```jsx
+   {/* Avoid using dialogs for simple success messages */}
+   <Dialog>
+     <Content>Item saved!</Content>
+   </Dialog>
+   ```
+
+3. **Accessibility**: Always provide a meaningful title for screen readers
+4. **Dismissal**: Use `isDismissable` for dialogs that users can close voluntarily
+5. **Focus Management**: Ensure focus moves to the most important action when dialog opens
+
+## Integration with Overlays
+
+Dialog is typically used within `DialogTrigger` or `Modal` components for proper overlay management and positioning. It should not be rendered directly without an overlay container.
+
+## Suggested Improvements
+
+- Enhancement 1: Add support for custom dialog animations and transitions
+- Enhancement 2: Implement automatic focus management for complex form scenarios
+
+## Related Components
+
+- [DialogTrigger](./DialogTrigger.md) - Manages dialog open/close state and positioning
+- [AlertDialog](./AlertDialog.md) - Specialized component for alert scenarios

package/docs/components/overlays/DialogContainer.md

@@ -0,0 +1,201 @@
+# DialogContainer
+
+A DialogContainer accepts a single Dialog as a child, and manages to show and hide it in a modal. Useful in cases where there is no trigger element or when the trigger unmounts while the dialog is open.
+
+## When to Use
+
+- When you need to display a dialog without a specific trigger element
+- To prevent dialog closure when the trigger component unmounts
+- For programmatically controlled dialogs in complex application flows
+- When managing dialog state externally from the component hierarchy
+- For dialogs that need to persist across route changes or component updates
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** — The Dialog to display, if any
+- **`type`** `'modal' | 'fullscreen' | 'fullscreenTakeover' | 'panel'` (default: `modal`) — The type of Dialog that should be rendered
+- **`isDismissable`** `boolean` (default: `false`) — Whether the Dialog is dismissible
+- **`isKeyboardDismissDisabled`** `boolean` (default: `false`) — Whether pressing the escape key to close the dialog should be disabled
+- **`isOpen`** `boolean` — Whether the modal is open or not
+- **`onDismiss`** `function` — Handler called when the x button of a dismissible Dialog is clicked
+- **`hideOnClose`** `boolean` (default: `false`) — Whether the dialog should be hidden when closed
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Styling Properties
+
+DialogContainer has no styling capabilities.
+
+## Variants
+
+### Types
+
+- `modal` - Standard modal dialog with backdrop (default)
+- `fullscreen` - Takes up entire screen with padding
+- `fullscreenTakeover` - Fullscreen without padding
+- `panel` - Side panel overlay
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<DialogContainer isOpen={isDialogOpen} onDismiss={() => setIsDialogOpen(false)}>
+  <Dialog>
+    <Header>
+      <Title>Dialog Title</Title>
+    </Header>
+    <Content>
+      <Paragraph>Dialog content goes here.</Paragraph>
+    </Content>
+  </Dialog>
+</DialogContainer>
+```
+
+### Controlled Dialog
+
+```jsx
+function ControlledDialogExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button onPress={() => setIsOpen(true)}>Open Dialog</Button>
+      <DialogContainer
+        isOpen={isOpen}
+        isDismissable
+        onDismiss={() => setIsOpen(false)}
+      >
+        <Dialog>
+          <Header>
+            <Title>Controlled Dialog</Title>
+          </Header>
+          <Content>
+            <Paragraph>This dialog is controlled externally.</Paragraph>
+          </Content>
+          <Footer>
+            <Button onPress={() => setIsOpen(false)}>Close</Button>
+          </Footer>
+        </Dialog>
+      </DialogContainer>
+    </>
+  );
+}
+```
+
+### Conditional Dialog
+
+```jsx
+function ConditionalDialog() {
+  const [showDialog, setShowDialog] = useState(false);
+  const [dialogContent, setDialogContent] = useState(null);
+
+  const openDialog = (content) => {
+    setDialogContent(content);
+    setShowDialog(true);
+  };
+
+  return (
+    <DialogContainer isOpen={showDialog} onDismiss={() => setShowDialog(false)}>
+      {dialogContent && (
+        <Dialog>
+          <Header>
+            <Title>Dynamic Dialog</Title>
+          </Header>
+          <Content>
+            {dialogContent}
+          </Content>
+        </Dialog>
+      )}
+    </DialogContainer>
+  );
+}
+```
+
+### Non-dismissable Dialog
+
+```jsx
+<DialogContainer isOpen={isOpen} isDismissable={false}>
+  <Dialog>
+    <Header>
+      <Title>Important Notice</Title>
+    </Header>
+    <Content>
+      <Paragraph>This dialog requires user action to close.</Paragraph>
+    </Content>
+    <Footer>
+      <Button type="primary" onPress={handleAction}>
+        Take Action
+      </Button>
+    </Footer>
+  </Dialog>
+</DialogContainer>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus between interactive elements within the dialog
+- `Shift + Tab` - Moves focus backward between interactive elements
+- `Escape` - Closes the dialog if `isDismissable` is true and `isKeyboardDismissDisabled` is false
+
+### Screen Reader Support
+
+- Dialog announces as "dialog" to screen readers
+- Focus is trapped within the dialog when open
+- Focus management is handled automatically
+- Modal state is properly communicated to assistive technologies
+
+### ARIA Properties
+
+- `aria-modal` - Set to true to indicate modal behavior
+- `aria-labelledby` - Links dialog to its title automatically
+- `aria-describedby` - Links dialog to its description content
+- `role` - Set to "dialog" for proper semantic meaning
+
+## Best Practices
+
+1. **Do**: Use DialogContainer for dialogs without specific triggers
+   ```jsx
+   <DialogContainer isOpen={showErrorDialog} onDismiss={clearError}>
+     <Dialog>
+       <Header>
+         <Title>Error</Title>
+       </Header>
+       <Content>
+         <Paragraph>{errorMessage}</Paragraph>
+       </Content>
+     </Dialog>
+   </DialogContainer>
+   ```
+
+2. **Don't**: Use DialogContainer when DialogTrigger is more appropriate
+   ```jsx
+   {/* Prefer DialogTrigger when you have a specific trigger */}
+   <DialogContainer isOpen={buttonPressed}>
+     <Dialog>...</Dialog>
+   </DialogContainer>
+   ```
+
+3. **State Management**: Always control the `isOpen` state externally
+4. **Single Child**: Only pass one Dialog as a child to DialogContainer
+5. **Cleanup**: Ensure proper cleanup of dialog state when component unmounts
+
+## Suggested Improvements
+
+- Enhancement 1: Add support for dialog stacking and z-index management
+- Enhancement 2: Implement automatic focus restoration after dialog closes
+- Enhancement 3: Add support for custom backdrop click behavior
+
+## Related Components
+
+- [DialogTrigger](./DialogTrigger.md) - Use when you have a specific trigger element
+- [Dialog](./Dialog.md) - The content component used within DialogContainer
+- [Button](../actions/Button.md) - Common element for dialog actions