@cube-dev/ui-kit 0.120.1 → 0.121.1

package/docs/components/content/Badge.md

@@ -0,0 +1,194 @@
+# Badge
+
+Badges are small, circular indicators that display numerical counts or short status text. They are typically used to draw attention to new, updated, or important information.
+
+## When to Use
+
+- **Notification counts**: Show unread messages, notifications, or pending items
+- **Status indicators**: Display simple status like "NEW", "HOT", or error counts
+- **Numerical data**: Show counts, quantities, or metrics at a glance
+- **Activity indicators**: Highlight areas with recent activity or updates
+- **Completion tracking**: Display progress counts (e.g., "3/10")
+
+## When Not to Use
+
+- **Long text**: Use `Tag` for longer labels or categorization
+- **Interactive elements**: Use `Button` for clickable actions
+- **Detailed information**: Use `Tooltip` or expanded content for complex details
+- **Navigation**: Use `Button` or `Link` for navigation purposes
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** `ReactNode` — Badge content (typically a number or short text)
+- **`icon`** `ReactNode` — Icon to display before the badge content
+- **`rightIcon`** `ReactNode` — Icon to display after the badge content
+- **`theme`** `'special' | 'danger' | 'success' | 'warning' | 'note' | 'disabled'` (default: `special`) — Visual theme of the badge
+- **`type`** `string` — Deprecated: Use theme instead
+- **`size`** `string` (default: `inline`) — Size of the badge
+
+### Base Properties
+
+Badge extends from `Item` component and supports all base design system properties including:
+- Layout props: `width`, `height`, `margin`, `padding`
+- Color props: `fill`, `color`, `border`
+- Typography props: `preset`, `fontSize`, `fontWeight`
+- Other Item props: `tooltip`, `isDisabled`, `qa`
+
+## Examples
+
+### Themes
+
+Badges support multiple themes for different semantic meanings:
+
+Available themes:
+- **Special** (default): Purple background, highlighted features
+- **Warning**: Yellow/amber background, caution or attention needed
+- **Note**: Violet background, informational content
+- **Success**: Green background, positive states
+- **Danger**: Red background, errors or urgent items
+- **Disabled**: Gray background, inactive items
+
+### Numbers
+
+Badges commonly display numerical counts:
+
+Best practices for numbers:
+- Use single digits for small counts (1-9)
+- Show exact numbers up to 99
+- Consider "99+" format for counts over 99
+- Keep numerical badges concise and scannable
+
+```jsx
+<Badge>5</Badge>
+<Badge>99</Badge>
+<Badge theme="danger">12</Badge>
+```
+
+### Text Content
+
+Short text labels work well in badges:
+
+Guidelines for text badges:
+- Keep text to 2-4 characters maximum
+- Use uppercase for better readability
+- Common patterns: "NEW", "HOT", "BETA", "PRO"
+
+```jsx
+<Badge>NEW</Badge>
+<Badge theme="success">OK</Badge>
+<Badge theme="danger">ERR</Badge>
+```
+
+### Sizes
+
+Badges support multiple sizes inherited from the Item component:
+
+- **inline** (default): Compact, inline badge optimized for text flow
+- **xsmall**: Extra small size
+- **small**: Small size
+- **medium**: Medium size
+- **large**: Large size
+- **xlarge**: Extra large size
+
+### With Icons
+
+Badges can include icons for additional visual context:
+
+Add an icon before the badge content using the `icon` prop:
+
+```jsx
+import { IconCoin } from '@tabler/icons-react';
+
+<Badge icon={<IconCoin />} theme="success">
+  12
+</Badge>
+```
+
+### With Right Icon
+
+Place icons after the content using the `rightIcon` prop:
+
+```jsx
+<Badge rightIcon={<IconCoin />} theme="danger">
+  ERR
+</Badge>
+```
+
+### With Both Icons
+
+Combine both `icon` and `rightIcon` for complex layouts:
+
+```jsx
+<Badge icon={<IconCoin />} rightIcon={<IconCoin />} theme="success">
+  NEW
+</Badge>
+```
+
+## Best Practices
+
+### Content
+
+- Keep badge content concise and scannable
+- Use numbers for counts ("3" not "three")
+- Use uppercase for text badges for better readability
+- Consider "99+" format for very large counts
+
+### Placement
+
+- Position badges near related content without obscuring it
+- Maintain consistent positioning across similar contexts
+
+### Visual Design
+
+- Use theme colors consistently for semantic meaning
+- Ensure adequate spacing from surrounding content
+
+### Accessibility
+
+- Provide context for counts via tooltips when needed
+- Don't rely solely on color to convey meaning
+- All themes maintain sufficient color contrast
+
+## Use Cases
+
+### Navigation Badges
+
+Display notification counts on menu items:
+
+```jsx
+<Item icon={<IconBell />}>
+  Notifications
+  <Badge theme="danger">5</Badge>
+</Item>
+```
+
+### Status Indicators
+
+Show item status or state:
+
+```jsx
+<Item>
+  Beta Feature <Badge theme="special">BETA</Badge>
+</Item>
+```
+
+### Inline Counts
+
+Display counts within text:
+
+```jsx
+<Text>
+  Unread Messages <Badge>12</Badge>
+</Text>
+```
+
+## Related Components
+
+- **Tag**: For longer labels, categorization, or closable elements
+- **Chip**: For interactive selection chips
+- **Item**: Base component that Badge extends from
+- **Text**: For displaying badge content inline with text

package/docs/components/content/Card.md

@@ -0,0 +1,40 @@
+# Card
+
+A container with rounded corners, border, and padding. Renders as a `<div role="region">`.
+
+## When to Use
+
+- Grouping related information
+- Content containers in dashboards
+- Highlighting standalone content blocks
+
+## Properties
+
+No component-specific props. Use style props directly.
+
+### Style Defaults
+
+- `display` — `block`
+- `flow` — `column`
+- `radius` — `(1cr + 1bw)`
+- `fill` — `#white`
+- `border` — `#border`
+- `padding` — `1.5x`
+- `preset` — `t3`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Card>
+  <Title level={3}>Card Title</Title>
+  <Paragraph>Card content goes here.</Paragraph>
+</Card>
+
+<Card padding="2x" fill="#surface">
+  Styled card with custom padding and background
+</Card>
+```

package/docs/components/content/Content.md

@@ -0,0 +1,44 @@
+# Content
+
+A scrollable content section for page layouts. Renders as `<section>` and is designed to work with `Layout`.
+
+## When to Use
+
+- Main content area in app layouts
+- Scrollable body sections
+- Content that flows with `Layout` header/footer
+
+## Properties
+
+No component-specific props. Use style props directly.
+
+### Style Defaults
+
+- `display` — `block`
+- `flow` — `column`
+- `gap` — `2x`
+- `preset` — `p3`
+- `color` — `#dark-02`
+- `overflow` — `auto`
+- `scrollbar` — `styled`
+- `gridArea` — `content`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Layout>
+  <Layout.Header>
+    <Title level={3}>Page Title</Title>
+  </Layout.Header>
+  <Layout.Content>
+    <Paragraph>Main page content goes here.</Paragraph>
+  </Layout.Content>
+  <Layout.Footer>
+    <Text>Footer</Text>
+  </Layout.Footer>
+</Layout>
+```

package/docs/components/content/CopyPasteBlock.md

@@ -0,0 +1,36 @@
+# CopyPasteBlock
+
+A block that displays a value with copy-to-clipboard functionality. Supports paste via click/focus.
+
+## When to Use
+
+- API keys or tokens display
+- One-time codes or passwords
+- Values users need to copy or paste
+
+## Properties
+
+- **`title`** `string` — Label for the block
+- **`value`** `string` (default: `''`) — The value to display and copy
+- **`placeholder`** `ReactNode` — Placeholder when value is empty
+- **`size`** `'small' | 'medium' | 'large'` (default: `'medium'`) — Block size
+
+### Style Defaults
+
+- `fill` — `#dark-bg`
+- `radius` — `1r`
+- `cursor` — pointer
+- `preset` — `t3` (switches to `t2` when `size="large"`)
+- `height` — `5x` (`4x` for small, `6x` for large)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<CopyPasteBlock title="API Key" value={apiKey} />
+
+<CopyPasteBlock title="Token" value={token} size="small" />
+```

package/docs/components/content/CopySnippet.md

@@ -0,0 +1,43 @@
+# CopySnippet
+
+A code block with copy-to-clipboard functionality and syntax highlighting. Extends `Card`.
+
+## When to Use
+
+- Documentation code examples
+- API response displays
+- Sharing code snippets with copy functionality
+
+## Properties
+
+- **`code`** `string` (default: `''`) — The code to display
+- **`language`** `string` (default: `'javascript'`) — Syntax highlighting language
+- **`title`** `string` (default: `'Code example'`) — Accessible title
+- **`prefix`** `string` (default: `''`) — Prefix text (e.g. `$`)
+- **`multiline`** `boolean` — Allow multiline display
+- **`nowrap`** `boolean` — Prevent line wrapping
+- **`showTooltip`** `boolean` (default: `false`) — Show tooltip on hover
+
+### Style Defaults
+
+- `fill` — `#dark-bg`
+- `border` — `0`
+- `radius` — `1r`
+- `padding` — `0`
+- `preset` — `default`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<CopySnippet code="const x = 1;" language="javascript" />
+
+<CopySnippet
+  code={'{\n  "key": "value"\n}'}
+  language="json"
+  multiline
+/>
+```

package/docs/components/content/Disclosure.md

@@ -0,0 +1,181 @@
+# Disclosure
+
+An accessible collapsible container that reveals or hides additional content. Built on React Aria's `useDisclosure` hook, it provides keyboard navigation, screen reader support, and smooth height animations. Supports both standalone usage and grouped accordion behavior.
+
+## When to Use
+
+- For FAQ sections where users can expand answers to questions
+- To hide supplementary information that shouldn't overwhelm the main content
+- For accordion-style navigation or settings panels
+- When you need collapsible sections with consistent accessibility patterns
+- To progressively disclose complex information
+
+## Component
+
+---
+
+### Properties
+
+- **`isExpanded`** `boolean` — Controls expanded state in controlled mode
+- **`defaultExpanded`** `boolean` (default: `false`) — Initial expanded state in uncontrolled mode
+- **`onExpandedChange`** `(isExpanded: boolean) => void` — Callback fired when expanded state changes
+- **`isDisabled`** `boolean` (default: `false`) — Disables trigger interactions and force-closes the content
+- **`shape`** `'default' | 'card' | 'sharp'` (default: `default`) — Visual shape variant: default (no styling), card (border/radius), sharp (radius 0)
+- **`transitionDuration`** `number` — Duration for DisplayTransition animation in milliseconds. When undefined, uses default CSS transition timing
+- **`children`** `ReactNode | ((state: DisclosureStateContext) => ReactNode)` — Disclosure.Trigger and Disclosure.Content components
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+## Compound Components
+
+### Disclosure.Trigger
+
+The clickable button that toggles the disclosure. Built on `ItemButton` and accepts all ItemButton props including `icon`, `type`, `theme`, `size`, and more.
+
+### Disclosure.Content
+
+The collapsible panel containing the hidden content. Animates smoothly using CSS `interpolate-size: allow-keywords` for height transitions.
+
+### Disclosure.Group
+
+Container for multiple disclosure items that coordinates their expanded states. By default, only one item can be expanded at a time (accordion behavior).
+
+### Disclosure.Item
+
+Individual disclosure within a group. Must have a unique `id` prop when used inside `Disclosure.Group`.
+
+## Styling
+
+### styles
+
+Customizes the root element of the Disclosure component.
+
+### triggerStyles
+
+When using `Disclosure.Trigger`, you can pass `styles` prop to customize the trigger button.
+
+### contentStyles
+
+When using `Disclosure.Content`, you can pass `styles` prop to customize the content panel.
+
+### Group-level Styling
+
+`Disclosure.Group` accepts `triggerProps` to apply consistent props to all triggers, and `contentStyles` to style all content panels uniformly.
+
+### Style Properties
+
+Direct style application without using the `styles` prop: `width`, `height`, `padding`, `margin`, `gap`.
+
+### Modifiers
+
+The `mods` property accepts the following modifiers:
+
+- **`expanded`** `boolean` — True when the disclosure content is visible
+- **`disabled`** `boolean` — True when interactions are disabled
+- **`shape`** `string` — The current shape variant (`default`, `card`, `sharp`)
+
+For `Disclosure.Content`, additional modifiers are available:
+
+- **`shown`** `boolean` — True when content is visible (controls height animation)
+- **`phase`** `string` — Transition phase (`enter`, `entered`, `exit`, `unmounted`)
+
+## Variants
+
+### Shapes
+
+#### Card
+
+Bordered container with rounded corners.
+
+#### Sharp
+
+Sharp edges with no border radius.
+
+## Examples
+
+### Default Expanded
+
+Disclosure that starts in expanded state using `defaultExpanded` prop.
+
+### Disabled
+
+Disabled disclosure that cannot be toggled.
+
+### Controlled State
+
+Control the disclosure state externally with `isExpanded` and `onExpandedChange`.
+
+### Multiple Expanded Items
+
+Group with `allowsMultipleExpanded` where multiple items can be open simultaneously.
+
+### Default Expanded Keys
+
+Group with specific items pre-expanded via `defaultExpandedKeys`.
+
+### Custom Trigger with Render Prop
+
+Use render prop pattern to create custom triggers with access to `isExpanded` and `toggle`.
+
+### Disabled Group
+
+Group-level `isDisabled` that disables all items at once.
+
+### Nested Disclosures
+
+Disclosures can be nested, each maintaining independent state.
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the disclosure trigger
+- `Space` / `Enter` - Toggles the disclosure open/closed
+- `Tab` (when expanded) - Moves focus into the content panel
+
+### Screen Reader Support
+
+- Trigger announces as a button with expanded/collapsed state
+- `aria-expanded` is automatically managed by React Aria
+- `aria-controls` links trigger to content panel automatically
+- State changes are announced when toggling
+
+### ARIA Properties
+
+- `aria-expanded` - Indicates whether content is visible (managed automatically)
+- `aria-controls` - Links trigger to panel (managed automatically)
+- `aria-disabled` - Applied when `isDisabled` is true
+
+## Best Practices
+
+1. **Do**: Provide clear, descriptive trigger labels
+
+   ```jsx
+   <Disclosure.Trigger>View shipping details</Disclosure.Trigger>
+   ```
+
+2. **Don't**: Use vague or icon-only triggers without labels
+
+   ```jsx
+   <Disclosure.Trigger>+</Disclosure.Trigger>
+   ```
+
+3. **Do**: Use groups for related collapsible sections
+
+   ```jsx
+   <Disclosure.Group>
+     <Disclosure.Item id="billing">...</Disclosure.Item>
+     <Disclosure.Item id="shipping">...</Disclosure.Item>
+   </Disclosure.Group>
+   ```
+
+4. **Accessibility**: Always ensure trigger text clearly indicates what will be revealed
+
+5. **Performance**: Content remains mounted during transitions for smooth animations and accessibility
+
+## Related Components
+
+- [ItemButton](../actions/ItemButton.md) - The base component used for triggers
+- [DisplayTransition](../helpers/DisplayTransition.md) - Manages animation phases

package/docs/components/content/Divider.md

@@ -0,0 +1,39 @@
+# Divider
+
+A horizontal separator. Can be a simple line or include centered text with lines on both sides.
+
+## When to Use
+
+- Separating sections of content
+- Dividing list items or form sections
+- "Or" or other labels between content blocks
+
+## Properties
+
+- **`children`** `ReactNode` — Optional text to display centered between two lines
+
+### Style Defaults
+
+- `display` — `block` (switches to `grid` when text is present)
+- `height` — `1bw` (switches to `auto` when text is present)
+- `fill` — `#border` (switches to `none` when text is present)
+- `preset` — `c1`
+- `gridArea` — `divider`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Divider />
+
+<Divider>or</Divider>
+
+<Flow gap="1x">
+  <Paragraph>Section 1</Paragraph>
+  <Divider />
+  <Paragraph>Section 2</Paragraph>
+</Flow>
+```

package/docs/components/content/Footer.md

@@ -0,0 +1,35 @@
+# Footer
+
+A footer section for page layouts. Designed to work with `Layout`.
+
+## When to Use
+
+- Page footers with links or copyright
+- Bottom bar of application layouts
+- Action bars at the bottom of modals or panels
+
+## Properties
+
+No component-specific props. Use style props directly.
+
+### Style Defaults
+
+- `display` — `block`
+- `flow` — `column`
+- `gridArea` — `footer`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Layout>
+  <Layout.Header>...</Layout.Header>
+  <Layout.Content>...</Layout.Content>
+  <Layout.Footer>
+    <Text.Minor>© 2024 Company</Text.Minor>
+  </Layout.Footer>
+</Layout>
+```

package/docs/components/content/Header.md

@@ -0,0 +1,35 @@
+# Header
+
+A header section for page layouts. Renders as `<header>` and is designed to work with `Layout`.
+
+## When to Use
+
+- Page headers with title and actions
+- Section headers in layouts
+- Top bar of application layouts
+
+## Properties
+
+No component-specific props. Use style props directly.
+
+### Style Defaults
+
+- `display` — `block`
+- `flow` — `column`
+- `gridArea` — `header`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Layout>
+  <Layout.Header>
+    <Title level={3}>Dashboard</Title>
+    <Button>Settings</Button>
+  </Layout.Header>
+  <Layout.Content>...</Layout.Content>
+</Layout>
+```