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

package/docs/Result.md

@@ -0,0 +1,35 @@
+# Result
+
+Used to feed back the results of a series of operational tasks.
+
+## When To Use
+
+Use when important operations need to inform the user to process the results and the feedback is more complicated.
+
+## Examples
+
+### Success
+
+### Info
+
+### Warning
+
+### Error
+
+### Custom Icon
+
+### Custom Title
+
+### Compact
+
+## API
+
+## Differences from Ant Design
+
+| There are differences | Ant Design property | Cube UIKit property |
+| :-------------------: | :-----------------: | :-----------------: |
+|          No           |      `status`       |      `status`       |
+|          No           |       `title`       |       `title`       |
+|          Yes          |     `subTitle`      |     `subtitle`      |
+|          No           |       `icon`        |       `icon`        |
+|          Yes          |       `extra`       |     `children`      |

package/docs/SimpleLayout.md

@@ -0,0 +1,26 @@
+# Layout examples
+
+## Flow layout
+
+Flow Component is used to create gaps between blocks inside block layout.
+
+## Flex layout
+
+Use Space Component to create a row or a column of elements.
+
+Use Flex Component for more flexible layouts.
+
+## Grid layout
+
+Use Grid Component for grid layouts.
+
+### Simple layout with side bar.
+
+```jsx
+<Grid gridColumns="200px 1fr" gridRows="60px 1fr" height="500px">
+  <Card gridColumn="1 / -1">Header</Card>
+  <Card>Sidebar</Card>
+  <Card>Content</Card>
+</Grid>
+```
+

package/docs/Typography.md

@@ -0,0 +1,38 @@
+# Typography
+
+There are many ways to create typography elements like text labels and headings. You can use complete components, presets or low-level styles to get exact text label you want.
+
+## Typography Components
+
+### Headings
+
+### Paragraphs
+
+Paragraphs with gaps between them.
+
+### Text labels
+
+### Links
+
+Use `!` prefix to open link in new tab.
+
+```jsx
+(
+  <Link to="https://cube-uikit-storybook.netlify.app/">
+    Open Cube Cloud UI Kit
+  </Link>
+) |
+  (
+    <Link to="!https://cube-uikit-storybook.netlify.app/">
+      Open Cube Cloud UI Kit in new tab
+    </Link>
+  );
+```
+
+Use `@` prefix to navigate to the new page without using the Router.
+
+```jsx
+<Link to="@">Reload this page</Link> |
+<Link to="@/">Move to the Main Page</Link>;
+```
+

package/docs/components/CollectionItem.md

@@ -0,0 +1,299 @@
+# CollectionItem
+
+`CollectionItem` is the building block for all collection-based components in the UI Kit, providing a consistent API for list items, menu options, and selectors.
+
+## Used By
+
+ListBox, FilterListBox, Select, ComboBox, FilterPicker, Picker, Menu, CommandMenu
+
+## Usage Patterns
+
+There are two ways to provide items to collection components:
+
+### Static JSX
+
+Define items directly. You **must** provide `key` props:
+
+```jsx live=false
+<ListBox>
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+```
+
+### Data-driven (Recommended)
+
+**🚨 IMPORTANT:** The `items` prop **must be an array of objects**, where each object contains at least an `id` or `key` property.
+
+```jsx live=false
+// ✅ Correct: Array of objects with id/key
+const items = [
+  { id: 'apple', name: 'Apple' },
+  { id: 'banana', name: 'Banana' },
+];
+
+<ListBox items={items}>
+  {(item) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+```
+
+```jsx live=false
+// ❌ Wrong: Array of strings won't work
+const items = ['apple', 'banana']; // Don't do this!
+
+// ❌ Wrong: Array of primitives won't work
+const items = [1, 2, 3]; // Don't do this!
+```
+
+## Item Requirements
+
+| Property | Required | Type | Purpose |
+|----------|----------|------|---------|
+| `id` or `key` | ✅ **Required** | `string \| number` | Unique identifier - **critical for selection callbacks** |
+| `textValue` | ⚠️ Recommended | `string` | For filtering & accessibility |
+
+**Without `id`/`key`:** React Aria falls back to using order-based keys (e.g., `"0"`, `"1"`), which breaks selection functionality in select components as these values are meaningless for identifying specific items.
+
+**Without `textValue`:** Falls back to rendered content, then to key/id.
+
+### Rules
+
+```jsx live=false
+// ✅ Using 'id'
+const items = [
+  { id: 'apple', name: 'Apple' },
+  { id: 'banana', name: 'Banana' },
+];
+
+// ✅ Using 'key'
+const items = [
+  { key: 'apple', name: 'Apple' },
+  { key: 'banana', name: 'Banana' },
+];
+
+// ✅ Consistent types
+const items = [
+  { id: '1', name: 'First' },
+  { id: '2', name: 'Second' },
+];
+
+// ✅ Explicit textValue for complex content
+const items = [{
+  id: 'user-1',
+  firstName: 'John',
+  lastName: 'Smith',
+  textValue: 'John Smith',
+}];
+```
+
+**Always provide explicit `textValue` for:**
+- Icons/images without text
+- Formatted/complex content
+- Non-readable keys (UUIDs)
+- Searchable components (ComboBox, FilterListBox, FilterPicker, CommandMenu)
+
+## Properties
+
+Extends all [Item component](./content/Item.md) props:
+
+- `children` - Item content
+- `icon` / `rightIcon` - Icons
+- `prefix` / `suffix` - Additional content
+- `description` - Secondary text
+- `textValue` - Text for filtering/accessibility
+- `onAction` - Action handler (Menu items)
+
+## Examples
+
+### Basic
+
+```jsx live=false
+const permissions = [
+  { id: 'read', name: 'Read' },
+  { id: 'write', name: 'Write' },
+];
+
+<ListBox items={permissions}>
+  {(item) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+```
+
+### With Icons
+
+```jsx live=false
+import { IconFile, IconFolder } from '@tabler/icons-react';
+
+const items = [
+  { id: 'file', name: 'File', icon: <IconFile /> },
+  { id: 'folder', name: 'Folder', icon: <IconFolder /> },
+];
+
+<Menu items={items}>
+  {(item) => <Menu.Item key={item.id} icon={item.icon}>{item.name}</Menu.Item>}
+</Menu>
+```
+
+### With Descriptions
+
+```jsx live=false
+const users = [
+  {
+    id: '1',
+    name: 'John Smith',
+    email: 'john@example.com',
+    textValue: 'John Smith john@example.com',
+  },
+];
+
+<ComboBox items={users}>
+  {(item) => (
+    <ComboBox.Item key={item.id} description={item.email}>
+      {item.name}
+    </ComboBox.Item>
+  )}
+</ComboBox>
+```
+
+### With Sections
+
+```jsx live=false
+<ListBox>
+  <ListBox.Section title="Fruits">
+    <ListBox.Item key="apple">Apple</ListBox.Item>
+    <ListBox.Item key="banana">Banana</ListBox.Item>
+  </ListBox.Section>
+  <ListBox.Section title="Vegetables">
+    <ListBox.Item key="carrot">Carrot</ListBox.Item>
+  </ListBox.Section>
+</ListBox>
+```
+
+### Disabled Items
+
+```jsx live=false
+const items = [
+  { id: 'read', name: 'Read' },
+  { id: 'write', name: 'Write' },
+  { id: 'delete', name: 'Delete', disabled: true },
+];
+
+<ListBox
+  items={items}
+  disabledKeys={items.filter(i => i.disabled).map(i => i.id)}
+>
+  {(item) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+```
+
+## Best Practices
+
+```jsx live=false
+// ✅ Items must be an array of objects
+const items = [{ id: 'user-1', name: 'John' }];
+
+// ✅ Always provide id/key in each object
+const items = [
+  { id: 'apple', name: 'Apple' },
+  { id: 'banana', name: 'Banana' },
+];
+
+// ✅ Always pass key prop to Item
+<ListBox items={items}>
+  {(item) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+
+// ✅ Consistent types for id/key
+const items = [
+  { id: '1', name: 'First' },
+  { id: '2', name: 'Second' },
+];
+
+// ✅ Explicit textValue for complex content
+const items = [{
+  id: 'user-1',
+  name: 'John Smith',
+  textValue: 'John Smith',
+}];
+
+// ✅ Memoize large collections
+const items = useMemo(
+  () => data.map(d => ({ id: d.id, name: d.name })),
+  [data]
+);
+
+// ❌ Don't pass array of strings
+const items = ['apple', 'banana']; // Wrong!
+
+// ❌ Don't pass array of numbers
+const items = [1, 2, 3]; // Wrong!
+
+// ❌ Don't omit key prop
+<ListBox items={items}>
+  {(item) => <ListBox.Item>{item.name}</ListBox.Item>}
+</ListBox>
+
+// ❌ Don't omit id/key in objects
+const items = [
+  { name: 'First' }, // Missing id!
+  { name: 'Second' }, // Missing id!
+];
+
+// ❌ Don't mix types
+const items = [
+  { id: 1, name: 'First' },
+  { id: '2', name: 'Second' },
+];
+```
+
+## TypeScript
+
+```tsx live=false
+interface User {
+  id: string;          // Required!
+  name: string;
+  textValue?: string;
+}
+
+const items: User[] = [
+  { id: '1', name: 'John', textValue: 'John' },
+];
+
+<ListBox items={items}>
+  {(item: User) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+```
+
+## Quick Reference
+
+| Approach | Key Prop | Source |
+|----------|----------|--------|
+| Static JSX | ✅ Required | Hardcoded value |
+| Data-driven (`items`) | ✅ Required | Pass `item.key` or `item.id` |
+| Using `.map()` | ✅ Required | Pass `item.key` or `item.id` |
+
+| Component | Selection | Search |
+|-----------|-----------|--------|
+| ListBox | Single/Multiple | ❌ |
+| FilterListBox | Single/Multiple | ✅ |
+| Select | Single | ❌ |
+| ComboBox | Single | ✅ |
+| FilterPicker | Single/Multiple | ✅ |
+| Picker | Single/Multiple | ❌ |
+| Menu | Single action | ❌ |
+| CommandMenu | Single action | ✅ |
+
+## Essential Rules
+
+1. **🚨 The `items` prop must be an array of objects** - Never pass arrays of strings, numbers, or other primitives. Each object must have an `id` or `key` property.
+2. **🚨 Always provide `id` or `key` in each object** - Required for selection callbacks to work properly. Without it, React Aria uses order-based keys which are useless in select components.
+3. **🚨 Always pass `key` prop to Item** - Must explicitly pass `key={item.id}` or `key={item.key}` in the render function
+4. **Provide explicit `textValue`** - For icons, complex content, or searchable components
+5. **Use consistent types** - All strings or all numbers, never mixed
+
+## Related Components
+
+- [Item](./content/Item.md) - Base item component
+- [ListBox](./fields/ListBox.md) - List with selection
+- [Select](./fields/Select.md) - Dropdown selector
+- [ComboBox](./fields/ComboBox.md) - Searchable input
+- [Menu](./actions/Menu.md) - Action menu

package/docs/components/actions/Banner.md

@@ -0,0 +1,189 @@
+# Banner
+
+Banner displays prominent messages and notifications to users. It supports different visual themes with appropriate icons and can include action buttons and inline links.
+
+## When to Use
+
+- Display system-wide notifications or alerts that require user attention
+- Show billing, subscription, or account status warnings
+- Communicate deployment errors or operational issues
+- Provide contextual information with optional calls-to-action
+
+## Component
+
+---
+
+### Properties
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the component.
+
+**Sub-elements:**
+- `Label` - The main text content area
+- `Actions` - Container for action buttons
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| theme | `'danger' \| 'warning' \| 'note' \| 'success'` | Visual theme of the banner |
+
+## Variants
+
+### Themes
+
+- `note` (default) - Informational messages, tips, or neutral notifications
+- `warning` - Alerts that require attention but are not critical
+- `danger` - Critical errors or issues that need immediate action
+- `success` - Confirmation of successful operations
+
+## Sub-components
+
+### Banner.Action
+
+Action button styled to match the banner's theme. Use for primary calls-to-action.
+
+```jsx
+<Banner theme="warning" actions={<Banner.Action to="/upgrade">Upgrade Plan</Banner.Action>}>
+  You are approaching your monthly API request limit.
+</Banner>
+```
+
+### Banner.Link
+
+Inline link styled with white color and underline. Use for links within the banner's text content.
+
+```jsx
+<Banner theme="danger">
+  <Banner.Link to="https://docs.example.com">Daily limit</Banner.Link> exceeded.
+  Please contact support.
+</Banner>
+```
+
+## Examples
+
+### Basic Banner
+
+```jsx
+<Banner theme="note">
+  Scheduled maintenance will occur on Sunday at 2:00 AM UTC.
+</Banner>
+```
+
+### Dismissible Banner
+
+```jsx
+<Banner theme="success" isDismissable onDismiss={() => console.log('Dismissed')}>
+  Your deployment has been successfully updated.
+</Banner>
+```
+
+### Banner with Actions
+
+```jsx
+<Banner
+  theme="danger"
+  actions={
+    <>
+      <Banner.Action to="/billing">Go to Billing</Banner.Action>
+      <Banner.Action onPress={() => openChat()}>Contact us</Banner.Action>
+    </>
+  }
+>
+  Your account has been suspended due to payment failure.
+</Banner>
+```
+
+### Banner with Inline Links
+
+```jsx
+<Banner theme="warning" actions={<Banner.Action>Upgrade tier</Banner.Action>}>
+  The selected time range exceeds{' '}
+  <Banner.Link to="https://docs.example.com/retention">
+    the retention period
+  </Banner.Link>
+  . To extend this period, please upgrade or contact us.
+</Banner>
+```
+
+### Stacked Banners
+
+Use `shape="sharp"` when stacking multiple banners to remove gaps between them.
+
+```jsx
+<Flex flow="column">
+  <Banner theme="danger" shape="sharp">Critical alert</Banner>
+  <Banner theme="warning" shape="sharp">Warning message</Banner>
+  <Banner theme="note" shape="sharp">Information</Banner>
+</Flex>
+```
+
+### Custom Icon
+
+```jsx
+import { IconBell } from '@tabler/icons-react';
+
+<Banner theme="note" icon={<IconBell />} isDismissable>
+  You have new notifications.
+</Banner>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to action buttons within the banner
+- `Space/Enter` - Activates focused action button or dismiss button
+
+### Screen Reader Support
+
+- Banner has `role="status"` to announce content changes
+- Dismiss button includes tooltip "Hide banner" for accessibility
+
+### ARIA Properties
+
+- `role="status"` - Announces the banner as a status message
+- Action buttons inherit proper focus management from Item.Action
+
+## Best Practices
+
+1. **Do**: Use appropriate theme for the message severity
+
+```jsx
+<Banner theme="danger">Critical error requiring immediate action</Banner>
+<Banner theme="warning">Warning that needs attention</Banner>
+<Banner theme="note">Informational message</Banner>
+<Banner theme="success">Success confirmation</Banner>
+```
+
+2. **Do**: Keep banner messages concise and actionable
+
+```jsx
+<Banner theme="warning" actions={<Banner.Action>Upgrade</Banner.Action>}>
+  API usage at 85% of monthly limit.
+</Banner>
+```
+
+3. **Don't**: Use banners for non-important information that doesn't need prominent display
+
+4. **Do**: Use Banner.Link for inline links within content, Banner.Action for buttons
+
+```jsx
+<Banner theme="danger" actions={<Banner.Action>Contact us</Banner.Action>}>
+  <Banner.Link to="/docs/limits">Daily limit</Banner.Link> exceeded.
+</Banner>
+```
+
+## Related Components
+
+- [Item](../content/Item.md) - Base component that Banner extends
+- ItemAction - Action button component used by Banner.Action