@cube-dev/ui-kit 0.0.0-canary-d688797 → 0.0.0-canary-9418aa4

package/docs/ComplexLayout.md

@@ -195,12 +195,10 @@ Use `invertOrder` to place primary actions on the right.
 
 Panels support four rendering modes via the `mode` prop:
 
-| Mode | Content Push | Overlay | Description |
-|------|--------------|---------|-------------|
-| `default` | Yes | No | Standard panel, pushes content |
-| `sticky` | No | No | Floats over content |
-| `overlay` | Yes | Yes | With dismissable backdrop |
-| `dialog` | No | Dialog | Renders as modal dialog |
+- **`default`** — Standard panel, pushes content (Content Push: Yes, Overlay: No)
+- **`sticky`** — Floats over content (Content Push: No, Overlay: No)
+- **`overlay`** — With dismissable backdrop (Content Push: Yes, Overlay: Yes)
+- **`dialog`** — Renders as modal dialog (Content Push: No, Overlay: Dialog)
 
 ### Sticky Panel
 
@@ -296,12 +294,10 @@ Panels with `mode="dialog"` render as a modal dialog instead of inline.
 
 **Panel vs Pane:**
 
-| Feature | Panel | Pane |
-|---------|-------|------|
-| Position | Absolute (overlays layout) | Inline (participates in flex) |
-| Use case | Sidebars, drawers | Split views, code editors |
-| Content adjustment | Pushes content via insets | Takes space in flex container |
-| `resizeEdge` | Based on `side` prop | `"right"` or `"bottom"` |
+- **`Position`** — Panel: Absolute (overlays layout); Pane: Inline (participates in flex)
+- **`Use case`** — Panel: Sidebars, drawers; Pane: Split views, code editors
+- **`Content adjustment`** — Panel: Pushes content via insets; Pane: Takes space in flex container
+- **`resizeEdge`** — Panel: Based on `side` prop; Pane: `"right"` or `"bottom"`
 
 ## Advanced Patterns
 
@@ -382,13 +378,11 @@ Use `Layout.Center` for content that should be centered both horizontally and ve
 
 ### When to Use Container vs Center
 
-| Use Case | Component |
-|----------|-----------|
-| Article/documentation content | `Layout.Container` |
-| Forms with top-aligned content | `Layout.Container` |
-| Empty states | `Layout.Center` |
-| Loading/splash screens | `Layout.Center` |
-| Error pages | `Layout.Center` |
+- **Article/documentation content** — `Layout.Container`
+- **Forms with top-aligned content** — `Layout.Container`
+- **Empty states** — `Layout.Center`
+- **Loading/splash screens** — `Layout.Center`
+- **Error pages** — `Layout.Center`
 
 ## Using Space Component
 
@@ -410,31 +404,27 @@ Use `Layout.Center` for content that should be centered both horizontally and ve
 
 ### When to Use Space vs Layout.Flex
 
-| Use Case | Component |
-|----------|-----------|
-| Inline button groups | `Space` |
-| Quick horizontal/vertical arrangement | `Space` |
-| Scrollable flex container | `Layout.Flex` |
-| Part of Layout structure | `Layout.Flex` |
-| Standalone flex wrapper | `Space` |
+- **Inline button groups** — `Space`
+- **Quick horizontal/vertical arrangement** — `Space`
+- **Scrollable flex container** — `Layout.Flex`
+- **Part of Layout structure** — `Layout.Flex`
+- **Standalone flex wrapper** — `Space`
 
 ## Sub-Components Reference
 
-| Component | Purpose |
-|-----------|---------|
-| `Layout` | Root wrapper, provides context |
-| `Layout.Content` | Scrollable content area, fills available space |
-| `Layout.Container` | Horizontally centered content with constrained width |
-| `Layout.Center` | Centered content (both axes) with text-align center |
-| `Layout.Header` | Page header with title, breadcrumbs, actions |
-| `Layout.Footer` | Footer bar, typically for actions |
-| `Layout.Toolbar` | Horizontal bar with space-between layout |
-| `Layout.Panel` | Side panel with modes: default, sticky, overlay, dialog |
-| `Layout.PanelHeader` | Header for panels with close button |
-| `Layout.Pane` | Inline resizable section |
-| `Layout.Flex` | Scrollable flex container |
-| `Layout.Grid` | Scrollable grid container |
-| `Layout.Block` | Simple block container |
+- **`Layout`** — Root wrapper, provides context
+- **`Layout.Content`** — Scrollable content area, fills available space
+- **`Layout.Container`** — Horizontally centered content with constrained width
+- **`Layout.Center`** — Centered content (both axes) with text-align center
+- **`Layout.Header`** — Page header with title, breadcrumbs, actions
+- **`Layout.Footer`** — Footer bar, typically for actions
+- **`Layout.Toolbar`** — Horizontal bar with space-between layout
+- **`Layout.Panel`** — Side panel with modes: default, sticky, overlay, dialog
+- **`Layout.PanelHeader`** — Header for panels with close button
+- **`Layout.Pane`** — Inline resizable section
+- **`Layout.Flex`** — Scrollable flex container
+- **`Layout.Grid`** — Scrollable grid container
+- **`Layout.Block`** — Simple block container
 
 ## Common Props
 

package/docs/FieldProperties.md

@@ -0,0 +1,117 @@
+# Field Properties
+
+All input components in UI Kit (`TextInput`, `Select`, `ComboBox`, `Checkbox`, `RadioGroup`, `NumberInput`, `Switch`, `DatePicker`, `Slider`, `FileInput`, etc.) share a common set of field properties. These properties are provided by the `FieldBaseProps` interface and enable form integration, validation, labeling, and state management.
+
+When used inside a [Form](./components/form/Form.md), these properties are automatically inherited from the form context and can be overridden at the field level.
+
+## Identity & Form Integration
+
+- **`name`** `string` — Field name for form data binding. Required when used within a Form.
+- **`form`** `CubeFormInstance` — Form instance. Automatically provided when inside a Form context.
+- **`defaultValue`** `any` — Default value for the field in uncontrolled mode.
+- **`id`** `string` — Unique ID for the field element.
+- **`idPrefix`** `string` — ID prefix to avoid collisions between multiple forms.
+
+## Labels & Description
+
+- **`label`** `ReactNode` — Label text displayed above or beside the input.
+- **`labelPosition`** `'top' | 'side' | 'split'` (default: `top`) — Position of the label relative to the input.
+- **`description`** `ReactNode` — Description text placed below the label.
+- **`extra`** `ReactNode` — Additional content displayed next to the label.
+- **`tooltip`** `ReactNode` — Tooltip shown inside the label.
+- **`labelSuffix`** `ReactNode` — Content displayed after the label text.
+- **`labelProps`** `object` — Additional HTML props passed to the label element.
+- **`labelStyles`** `Styles` — Tasty styles for the label element.
+
+## Necessity Indicators
+
+- **`isRequired`** `boolean` (default: `false`) — Whether user input is required before form submission.
+- **`necessityIndicator`** `'icon' | 'label'` — Type of necessity indicator shown next to the label.
+- **`necessityLabel`** `ReactNode` — Custom text for the necessity indicator (e.g., "Required" or "Optional").
+
+## State
+
+- **`isDisabled`** `boolean` (default: `false`) — Whether the field is disabled and non-interactive.
+- **`isReadOnly`** `boolean` (default: `false`) — Whether the field can be focused but not changed.
+- **`isLoading`** `boolean` (default: `false`) — Whether to show a loading spinner and disable interactions.
+- **`isHidden`** `boolean` (default: `false`) — Whether the field is hidden.
+- **`validationState`** `'valid' | 'invalid'` — Visual validation state of the field.
+- **`autoFocus`** `boolean` (default: `false`) — Whether the field should receive focus on render.
+
+## Validation
+
+- **`rules`** `ValidationRule[]` — Array of validation rules for the field.
+- **`validateTrigger`** `'onBlur' | 'onChange' | 'onSubmit'` — When to trigger validation.
+- **`validationDelay`** `number` — Debounce delay in milliseconds before running validation.
+- **`showValid`** `boolean` — Whether to show the valid state icon after successful validation.
+- **`errorMessage`** `ReactNode` — Error message always displayed in danger state, regardless of validation state.
+- **`message`** `ReactNode` — _(deprecated)_ Use `errorMessage` for errors and `description` for help text.
+
+## Styling
+
+- **`fieldStyles`** `Styles` — Tasty styles for the field wrapper.
+- **`messageStyles`** `Styles` — Tasty styles for the message/error text.
+
+## Validation Rules
+
+The `rules` prop accepts an array of rule objects. Built-in validators include:
+
+- **`required`** `boolean` — Field must have a value.
+- **`type`** `string` — Validates data type (`email`, `url`, `number`, etc.).
+- **`pattern`** `RegExp` — Value must match the regular expression.
+- **`min`** / **`max`** `number` — Minimum/maximum length or value constraints.
+- **`enum`** `any[]` — Value must be one of the allowed values.
+- **`whitespace`** `boolean` — Value must contain non-whitespace characters.
+- **`message`** `string` — Custom error message for the rule.
+- **`validator`** `(rule, value) => Promise<string | void>` — Custom async validation function.
+
+```jsx
+<TextInput
+  name="email"
+  label="Email Address"
+  isRequired
+  rules={[
+    { required: true, message: 'Email is required' },
+    { type: 'email', message: 'Enter a valid email' },
+  ]}
+/>
+```
+
+## Usage Example
+
+```jsx
+import { Form, TextInput, Select } from '@cube-dev/ui-kit';
+
+function ExampleForm() {
+  return (
+    <Form defaultValues={{ name: '', role: undefined }}>
+      <TextInput
+        name="name"
+        label="Full Name"
+        description="As it appears on your ID"
+        isRequired
+        rules={[{ required: true, min: 2 }]}
+      />
+
+      <Select
+        name="role"
+        label="Role"
+        tooltip="Your primary role in the organization"
+        necessityIndicator="label"
+        isRequired
+      >
+        <Select.Item key="admin">Admin</Select.Item>
+        <Select.Item key="member">Member</Select.Item>
+      </Select>
+
+      <Form.Submit>Save</Form.Submit>
+    </Form>
+  );
+}
+```
+
+## Related
+
+- [Base Properties](./BaseProperties.md) — Common styling and layout properties
+- [Form](./components/form/Form.md) — Form container with validation and state management
+- [Field](./components/form/Field.md) — Legacy field wrapper (for custom components only)

package/docs/RenderCache.md

@@ -15,6 +15,11 @@ RenderCache is a performance optimization component that caches rendered React e
 
 ### Properties
 
+- **`items`** `T[]` — Array of items to render
+- **`renderKeys`** `Array<string | number>` — Array of keys that should trigger re-render. Only items with keys in this array will be re-rendered
+- **`getKey`** `(item: T) => string | number` — Function that extracts a unique key from each item
+- **`children`** `(item: T) => ReactElement` — Render function that takes an item and returns a React element
+
 ### Property Details
 
 - **items**: Array of items to render

package/docs/Result.md

@@ -22,7 +22,14 @@ Use when important operations need to inform the user to process the results and
 
 ### Compact
 
-## API
+## Properties
+
+- **`status`** `'success' | 'error' | 'info' | 'warning' | 404 | 403 | 500` (default: `'info'`) — Result status, determines the icon and color from ready-made templates
+- **`title`** `ReactNode` — The title of the result
+- **`subtitle`** `ReactNode` — Subtitle of the result component
+- **`icon`** `ReactNode` — Custom icon element. Don't use together with `status`
+- **`isCompact`** `boolean` — Whether the result component has a compact presentation
+- **`children`** `ReactNode` — Additional block content, e.g. a set of action buttons
 
 ## Differences from Ant Design
 

package/docs/components/Block.md

@@ -0,0 +1,33 @@
+# Block
+
+A simple block-level container. The most basic layout primitive.
+
+## When to Use
+
+- Wrapping content in a block display context
+- Base layout when you need `display: block` without extra semantics
+- Generic container for styling with style props
+
+## Properties
+
+No component-specific props. Use style props directly.
+
+### Style Defaults
+
+- `display` — `block`
+
+### Base Properties
+
+Supports [Base properties](../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Block>
+  <Text>Content in a block container</Text>
+</Block>
+
+<Block padding="1x" fill="#surface">
+  Styled block with padding and background
+</Block>
+```

package/docs/components/CollectionItem.md

@@ -47,10 +47,8 @@ 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 |
+- **`id` or `key`** `string | number` — Unique identifier - **critical for selection callbacks** (✅ Required)
+- **`textValue`** `string` — For filtering & accessibility (⚠️ Recommended)
 
 **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.
 
@@ -265,22 +263,18 @@ const items: User[] = [
 
 ## 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 | ✅ |
+- **Static JSX** — Key Prop: ✅ Required; Source: Hardcoded value
+- **Data-driven (`items`)** — Key Prop: ✅ Required; Source: Pass `item.key` or `item.id`
+- **Using `.map()`** — Key Prop: ✅ Required; Source: Pass `item.key` or `item.id`
+
+- **ListBox** — Selection: Single/Multiple; Search: ❌
+- **FilterListBox** — Selection: Single/Multiple; Search: ✅
+- **Select** — Selection: Single; Search: ❌
+- **ComboBox** — Selection: Single; Search: ✅
+- **FilterPicker** — Selection: Single/Multiple; Search: ✅
+- **Picker** — Selection: Single/Multiple; Search: ❌
+- **Menu** — Selection: Single action; Search: ❌
+- **CommandMenu** — Selection: Single action; Search: ✅
 
 ## Essential Rules
 

package/docs/components/GridProvider.md

@@ -0,0 +1,38 @@
+# GridProvider
+
+Provides CSS custom properties for responsive grid column calculations. Children can use `$column-width` for precise column sizing.
+
+## When to Use
+
+- Responsive grid layouts with consistent column sizing
+- Layouts that need to calculate column widths based on container size
+- Grid systems with configurable column counts
+
+## Properties
+
+- **`columns`** `number` (default: `2`) — Number of grid columns
+- **`gap`** `Styles['gap']` (default: `'0'`) — Gap between columns
+- **`width`** `Styles['width']` — Forced container width (bypasses auto-detection)
+- **`initialWidth`** `Styles['width']` — Initial width before resize observer kicks in
+
+### CSS Custom Properties Provided
+
+- `--grid-width` — Total grid width
+- `--columns-amount` — Number of columns
+- `--column-gap` — Gap between columns
+- `--column-width` — Calculated width per column
+
+### Style Defaults
+
+- `display` — `contents`
+
+## Examples
+
+```jsx
+<GridProvider columns={12} gap="1x">
+  <Grid columns="repeat(12, $column-width)">
+    <Block gridColumn="span 6">Half</Block>
+    <Block gridColumn="span 6">Half</Block>
+  </Grid>
+</GridProvider>
+```

package/docs/components/Root.md

@@ -0,0 +1,50 @@
+# Root
+
+The root application wrapper. Provides theme context, global styles, portal container, modal/toast providers, and navigation. Wrap your app with `Root` at the top level.
+
+## When to Use
+
+- Top-level app component (required)
+- Provides context for modals, toasts, tooltips, and overlays
+- Theme and design token configuration
+
+## Properties
+
+- **`navigation`** `NavigationAdapter` — Custom navigation adapter for routing
+- **`tracking`** `TrackingProps` — Analytics/tracking event configuration
+- **`tokens`** `Record<string, string>` — Custom design tokens (CSS custom properties)
+- **`fonts`** `boolean` — Whether to load default fonts
+- **`font`** `string` — Custom font family name
+- **`monospaceFont`** `string` — Custom monospace font family name
+- **`fontDisplay`** `'auto' | 'block' | 'swap' | 'fallback' | 'optional'` (default: `'swap'`) — Font display strategy
+- **`bodyStyles`** `Record<string, string>` — Raw CSS styles applied to the `<body>`
+- **`publicUrl`** `string` — Public URL for font loading
+- **`cursorStrategy`** `'web' | 'native'` (default: `'web'`) — Cursor style for interactive elements (`web` uses pointer, `native` uses default)
+
+### Style Defaults
+
+- `display` — `contents`
+- `color` — `#dark-02`
+- `preset` — `t3`
+
+### Base Properties
+
+Supports [Base properties](../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Root>
+  <App />
+</Root>
+```
+
+```jsx
+<Root
+  font="Inter"
+  navigation={routerAdapter}
+  tokens={{ '--gap': '8px', '--radius': '4px' }}
+>
+  <App />
+</Root>
+```

package/docs/components/actions/Action.md

@@ -0,0 +1,47 @@
+# Action
+
+A low-level action element that can render as `<button>`, `<a>`, or `<span>`. When `to` is provided, it renders as a link. Used as a base for `Button` and `Link`.
+
+## When to Use
+
+- Building custom interactive elements
+- Actions that may navigate or submit
+- When you need a button that can become a link via the `to` prop
+
+## Properties
+
+- **`to`** `NavigateArg` — Navigation target (renders as `<a>` when provided)
+- **`label`** `string` — Accessible label for screen readers
+- **`htmlType`** `'button' | 'submit' | 'reset'` — HTML button type
+- **`download`** `string` — Download attribute for link mode
+- **`onPress`** `() => void` — Press event handler (React Aria)
+
+### Style Defaults
+
+- `position` — `relative`
+- `preset` — `inherit`
+- `transition` — `theme`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md). Extends React Aria `AriaButtonProps`.
+
+## Examples
+
+### Button action
+
+```jsx
+<Action onPress={() => doSomething()}>Click me</Action>
+```
+
+### Navigation action
+
+```jsx
+<Action to="/dashboard">Go to Dashboard</Action>
+```
+
+### Form submit
+
+```jsx
+<Action htmlType="submit">Submit</Action>
+```

package/docs/components/actions/Banner.md

@@ -15,9 +15,17 @@ Banner displays prominent messages and notifications to users. It supports diffe
 
 ### Properties
 
+- **`theme`** `'danger' | 'warning' | 'note' | 'success'` (default: `'note'`) — Visual theme of the banner with corresponding icon and colors
+- **`isDismissable`** `boolean` (default: `false`) — Whether the banner shows a dismiss button
+- **`onDismiss`** `() => void` — Callback fired when the dismiss button is clicked
+- **`icon`** `ReactNode` — Custom icon to display; defaults to a theme-appropriate icon
+- **`actions`** `ReactNode` — Action buttons displayed on the right side of the banner. Use `Banner.Action` for consistent styling
+- **`description`** `string` — Secondary text shown below the main content, truncated with ellipsis after two lines
+- **`shape`** `'sharp'` — Use `'sharp'` to remove rounded corners when stacking multiple banners
+
 ### Base Properties
 
-Supports [Base properties](../../tasty/tasty.md)
+Supports [Base properties](../../BaseProperties.md)
 
 ### Styling Properties
 
@@ -33,9 +41,7 @@ Customizes the root element of the component.
 
 The `mods` property accepts the following modifiers you can override:
 
-| Modifier | Type | Description |
-|----------|------|-------------|
-| theme | `'danger' \| 'warning' \| 'note' \| 'success'` | Visual theme of the banner |
+- **`theme`** `'danger' \| 'warning' \| 'note' \| 'success'` — Visual theme of the banner
 
 ## Variants
 
@@ -186,4 +192,4 @@ import { IconBell } from '@tabler/icons-react';
 ## Related Components
 
 - [Item](../content/Item.md) - Base component that Banner extends
-- ItemAction - Action button component used by Banner.Action
+- [ItemAction](./ItemAction.md) - Action button component used by Banner.Action

package/docs/components/actions/Button.md

@@ -17,18 +17,21 @@ A versatile action component that triggers commands and navigates users.
 
 - **`type`** `'primary' | 'secondary' | 'outline' | 'neutral' | 'clear' | 'link'` (default: `outline`) — Visual style variant of the button
 - **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Semantic colour palette theme
-- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `medium`) — Button size
+- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'inline' | number` (default: `medium`) — Button size. Use `'inline'` for link-type buttons or a number/string for custom sizes (e.g. `64` or `'8x'`)
 - **`icon`** — Icon rendered before the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
 - **`rightIcon`** — Icon rendered after the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
-- **`children`** `string` — Button label or custom content
-- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions (default: false)
-- **`isSelected`** `boolean` (default: `false`) — Marks the button as pressed / selected (toggle) (default: false)
+- **`children`** `ReactNode` — Button label or custom content
+- **`label`** `string` — Accessible label for the button (used as `aria-label`)
+- **`tooltip`** `string | boolean | object` — Tooltip content. Use a string for simple text, `true` for auto tooltip on overflow, or an object with `{ title, auto, placement, ...tooltipProps }`
+- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions
+- **`isSelected`** `boolean` (default: `false`) — Marks the button as pressed / selected (toggle)
 - **`to`** `string` — Destination URL or route; prefix with `!` to open in new tab, `@` to bypass router
+- **`htmlType`** `'button' | 'submit' | 'reset'` — HTML button type attribute
 - **`onPress`** `function` — Callback fired when the button is activated by mouse, touch, or keyboard
 
 ### Base Properties
 
-Supports [Base properties](../../tasty/tasty.md)
+Supports [Base properties](../../BaseProperties.md)
 
 ### Styling Properties
 
@@ -36,8 +39,10 @@ Supports [Base properties](../../tasty/tasty.md)
 
 Customises the root element of the component.
 
-Sub-elements:
-- `ButtonIcon` – wrapper around `icon` and `rightIcon`.
+**Sub-elements:**
+- `Icon` – wrapper around the leading icon
+- `RightIcon` – wrapper around the trailing icon
+- `Label` – the button text content
 
 ### Style Properties
 
@@ -47,16 +52,17 @@ These properties allow direct styling without using the `styles` prop: `width`,
 
 The `mods` prop accepts the following modifiers you can override:
 
-| Modifier | Type | Description |
-|----------|------|-------------|
-| hovered | `boolean` | Forces hover state. |
-| pressed | `boolean` | Forces pressed state. |
-| focused | `boolean` | Forces focus ring. |
-| disabled | `boolean` | Forces disabled appearance. |
-| loading | `boolean` | Displays loading spinner. |
-| selected | `boolean` | Displays selected state. |
-| has-icons | `boolean` | Indicates that the button contains at least one icon. |
-| single-icon | `boolean` | Icon-only button without text. |
+- **`hovered`** `boolean` — Forces hover state
+- **`pressed`** `boolean` — Forces pressed state
+- **`focused`** `boolean` — Forces focus ring
+- **`disabled`** `boolean` — Forces disabled appearance
+- **`loading`** `boolean` — Displays loading spinner
+- **`selected`** `boolean` — Displays selected state
+- **`has-icons`** `boolean` — Indicates that the button contains at least one icon
+- **`has-icon`** `boolean` — Indicates that the button has a leading icon
+- **`has-right-icon`** `boolean` — Indicates that the button has a trailing icon
+- **`single-icon`** `boolean` — Icon-only button without text
+- **`text-only`** `boolean` — Button has only text content, no icons
 
 ## Variants
 
@@ -85,6 +91,8 @@ The `mods` prop accepts the following modifiers you can override:
 - `medium` – Default height (32px).
 - `large` – Spacious height (40px).
 - `xlarge` – Extra spacious height (48px).
+- `inline` – Inline size for link-type buttons (no fixed height).
+- Custom values – Pass a number (pixels) or a string (e.g. `'8x'`) for custom sizing.
 
 ## Examples
 
@@ -141,6 +149,26 @@ import { IconPlus } from '@tabler/icons-react';
 <Button isLoading>Processing…</Button>
 ```
 
+### With Tooltip
+
+```jsx
+{/* Simple tooltip text */}
+<Button icon={<IconPlus />} tooltip="Add new item" aria-label="Add" />
+
+{/* Auto tooltip on overflow */}
+<Button tooltip={true} width="100px">This text will be truncated</Button>
+```
+
+### Custom Size
+
+```jsx
+{/* Using a number (pixels) */}
+<Button size={64}>Large Custom</Button>
+
+{/* Using a string multiplier */}
+<Button size="8x">8x Size</Button>
+```
+
 ## Accessibility
 
 ### Keyboard Navigation
@@ -173,9 +201,7 @@ import { IconPlus } from '@tabler/icons-react';
 
 ## Suggested Improvements
 
-- Add `autoFocus` support.
 - Provide `block` modifier to stretch the button 100% width.
-- Expose a `tooltip` helper for icon-only buttons.
 
 ## Related Components