xertica-ui 2.2.1 → 2.4.0

package/docs/components/timeline.md

@@ -1,121 +1,121 @@
-# Timeline
-
-## Overview
-
-A vertical sequence of events displayed chronologically, each with a timestamp, title, and optional description. Used in activity logs, audit trails, case histories, and notification feeds.
-
----
-
-## When to Use
-
-- Activity logs and audit trails
-- Event histories on records (status changes, actions)
-- Notification feeds on dashboards
-
----
-
-## Anatomy
-
-```
-<Timeline>
-  <TimelineItem>
-    <TimelineDot variant="success" icon={<CheckCircle />} />
-    <TimelineContent>
-      <TimelineTime>Today, 09:00</TimelineTime>
-      <TimelineHeading>Event Title</TimelineHeading>
-      <TimelineDescription>Optional description</TimelineDescription>
-    </TimelineContent>
-  </TimelineItem>
-</Timeline>
-```
-
----
-
-## TimelineDot Variants
-
-| Variant       | Color         | Usage                    |
-| ------------- | ------------- | ------------------------ |
-| `default`     | Muted         | Neutral events           |
-| `primary`     | Primary brand | Highlighted events       |
-| `success`     | Green         | Completed actions        |
-| `info`        | Blue          | Informational events     |
-| `warning`     | Amber         | Caution events           |
-| `destructive` | Red           | Errors or failures       |
-| `outline`     | Border only   | Pending or future events |
-
----
-
-## Sub-components
-
-| Component             | Description                                    |
-| --------------------- | ---------------------------------------------- |
-| `Timeline`            | Root `<ol>` with the left border line          |
-| `TimelineItem`        | `<li>` wrapper for a single event              |
-| `TimelineDot`         | Colored dot or icon badge on the timeline line |
-| `TimelineContent`     | Content area to the right of the dot           |
-| `TimelineHeading`     | Event title (`<h3>`)                           |
-| `TimelineTime`        | Timestamp (`<time>`)                           |
-| `TimelineDescription` | Optional description paragraph                 |
-
----
-
-## Examples
-
-```tsx
-import {
-  Timeline,
-  TimelineItem,
-  TimelineDot,
-  TimelineContent,
-  TimelineHeading,
-  TimelineTime,
-  TimelineDescription,
-} from 'xertica-ui/ui';
-import { CheckCircle, AlertCircle, LogIn, Clock } from 'lucide-react';
-
-<Timeline>
-  <TimelineItem>
-    <TimelineDot variant="default" icon={<LogIn className="size-4" />} />
-    <TimelineContent>
-      <TimelineHeading>Login</TimelineHeading>
-      <TimelineTime>Today, 09:00</TimelineTime>
-      <TimelineDescription>User logged in from Chrome on macOS</TimelineDescription>
-    </TimelineContent>
-  </TimelineItem>
-
-  <TimelineItem>
-    <TimelineDot variant="success" icon={<CheckCircle className="size-4" />} />
-    <TimelineContent>
-      <TimelineHeading>Password Changed</TimelineHeading>
-      <TimelineTime>Yesterday, 16:32</TimelineTime>
-    </TimelineContent>
-  </TimelineItem>
-
-  <TimelineItem>
-    <TimelineDot variant="destructive" icon={<AlertCircle className="size-4" />} />
-    <TimelineContent>
-      <TimelineHeading>Security Alert</TimelineHeading>
-      <TimelineTime>Mon, 10:15</TimelineTime>
-      <TimelineDescription>Suspicious login attempt blocked</TimelineDescription>
-    </TimelineContent>
-  </TimelineItem>
-
-  <TimelineItem>
-    <TimelineDot variant="outline" />
-    <TimelineContent>
-      <TimelineHeading>Pending Review</TimelineHeading>
-      <TimelineTime>Scheduled</TimelineTime>
-    </TimelineContent>
-  </TimelineItem>
-</Timeline>;
-```
-
----
-
-## AI Rules
-
-- Always compose: `Timeline > TimelineItem > (TimelineDot + TimelineContent)`.
-- `TimelineTime` renders a `<time>` element — pass a pre-formatted display string, not a Date object.
-- Use `TimelineDot variant="outline"` for pending or future events.
-- Pass `icon` to `TimelineDot` for large icon dots; omit for small colored dots.
-- For large timelines, wrap in `<ScrollArea className="h-[400px]">`.
+# Timeline
+
+## Overview
+
+A vertical sequence of events displayed chronologically, each with a timestamp, title, and optional description. Used in activity logs, audit trails, case histories, and notification feeds.
+
+---
+
+## When to Use
+
+- Activity logs and audit trails
+- Event histories on records (status changes, actions)
+- Notification feeds on dashboards
+
+---
+
+## Anatomy
+
+```
+<Timeline>
+  <TimelineItem>
+    <TimelineDot variant="success" icon={<CheckCircle />} />
+    <TimelineContent>
+      <TimelineTime>Today, 09:00</TimelineTime>
+      <TimelineHeading>Event Title</TimelineHeading>
+      <TimelineDescription>Optional description</TimelineDescription>
+    </TimelineContent>
+  </TimelineItem>
+</Timeline>
+```
+
+---
+
+## TimelineDot Variants
+
+| Variant       | Color         | Usage                    |
+| ------------- | ------------- | ------------------------ |
+| `default`     | Muted         | Neutral events           |
+| `primary`     | Primary brand | Highlighted events       |
+| `success`     | Green         | Completed actions        |
+| `info`        | Blue          | Informational events     |
+| `warning`     | Amber         | Caution events           |
+| `destructive` | Red           | Errors or failures       |
+| `outline`     | Border only   | Pending or future events |
+
+---
+
+## Sub-components
+
+| Component             | Description                                    |
+| --------------------- | ---------------------------------------------- |
+| `Timeline`            | Root `<ol>` with the left border line          |
+| `TimelineItem`        | `<li>` wrapper for a single event              |
+| `TimelineDot`         | Colored dot or icon badge on the timeline line |
+| `TimelineContent`     | Content area to the right of the dot           |
+| `TimelineHeading`     | Event title (`<h3>`)                           |
+| `TimelineTime`        | Timestamp (`<time>`)                           |
+| `TimelineDescription` | Optional description paragraph                 |
+
+---
+
+## Examples
+
+```tsx
+import {
+  Timeline,
+  TimelineItem,
+  TimelineDot,
+  TimelineContent,
+  TimelineHeading,
+  TimelineTime,
+  TimelineDescription,
+} from 'xertica-ui/ui';
+import { CheckCircle, AlertCircle, LogIn, Clock } from 'lucide-react';
+
+<Timeline>
+  <TimelineItem>
+    <TimelineDot variant="default" icon={<LogIn className="size-4" />} />
+    <TimelineContent>
+      <TimelineHeading>Login</TimelineHeading>
+      <TimelineTime>Today, 09:00</TimelineTime>
+      <TimelineDescription>User logged in from Chrome on macOS</TimelineDescription>
+    </TimelineContent>
+  </TimelineItem>
+
+  <TimelineItem>
+    <TimelineDot variant="success" icon={<CheckCircle className="size-4" />} />
+    <TimelineContent>
+      <TimelineHeading>Password Changed</TimelineHeading>
+      <TimelineTime>Yesterday, 16:32</TimelineTime>
+    </TimelineContent>
+  </TimelineItem>
+
+  <TimelineItem>
+    <TimelineDot variant="destructive" icon={<AlertCircle className="size-4" />} />
+    <TimelineContent>
+      <TimelineHeading>Security Alert</TimelineHeading>
+      <TimelineTime>Mon, 10:15</TimelineTime>
+      <TimelineDescription>Suspicious login attempt blocked</TimelineDescription>
+    </TimelineContent>
+  </TimelineItem>
+
+  <TimelineItem>
+    <TimelineDot variant="outline" />
+    <TimelineContent>
+      <TimelineHeading>Pending Review</TimelineHeading>
+      <TimelineTime>Scheduled</TimelineTime>
+    </TimelineContent>
+  </TimelineItem>
+</Timeline>;
+```
+
+---
+
+## AI Rules
+
+- Always compose: `Timeline > TimelineItem > (TimelineDot + TimelineContent)`.
+- `TimelineTime` renders a `<time>` element — pass a pre-formatted display string, not a Date object.
+- Use `TimelineDot variant="outline"` for pending or future events.
+- Pass `icon` to `TimelineDot` for large icon dots; omit for small colored dots.
+- For large timelines, wrap in `<ScrollArea className="h-[400px]">`.

package/docs/components/toggle-group.md

@@ -1,68 +1,68 @@
-# ToggleGroup
-
-## Overview
-
-A set of related `<Toggle>` buttons that operate together — either allowing only one selection at a time (`type="single"`) or multiple simultaneous selections (`type="multiple"`). Used for mutually exclusive view modes, filter groups, and formatting toolbars.
-
----
-
-## When to Use
-
-- View mode switchers (Table / Grid / Kanban)
-- Text alignment controls (Left / Center / Right)
-- Multi-select filter chips in compact toolbars
-
----
-
-## Props
-
-### ToggleGroup
-
-| Prop            | Type                     | Default | Required | Description          |
-| --------------- | ------------------------ | ------- | -------- | -------------------- |
-| `type`          | `'single' \| 'multiple'` | —       | **Yes**  | Selection mode       |
-| `value`         | `string \| string[]`     | —       | No       | Controlled value(s)  |
-| `defaultValue`  | `string \| string[]`     | —       | No       | Uncontrolled default |
-| `onValueChange` | `(value) => void`        | —       | No       | Change handler       |
-
-### ToggleGroupItem
-
-| Prop         | Type     | Required        | Description                       |
-| ------------ | -------- | --------------- | --------------------------------- |
-| `value`      | `string` | **Yes**         | Unique identifier for this option |
-| `aria-label` | `string` | Yes (icon-only) | Accessibility label               |
-
----
-
-## Examples
-
-### View Mode Switcher
-
-```tsx
-import { ToggleGroup, ToggleGroupItem } from 'xertica-ui/ui';
-import { LayoutGrid, LayoutList } from 'lucide-react';
-
-<ToggleGroup type="single" defaultValue="list">
-  <ToggleGroupItem value="list" aria-label="List view">
-    <LayoutList className="size-4" />
-  </ToggleGroupItem>
-  <ToggleGroupItem value="grid" aria-label="Grid view">
-    <LayoutGrid className="size-4" />
-  </ToggleGroupItem>
-</ToggleGroup>;
-```
-
----
-
-## AI Rules
-
-- `type` is **required** — never omit it.
-- Always provide `aria-label` for icon-only items.
-- For text format toolbars (bold/italic/underline), use `type="multiple"` to allow simultaneous formatting.
-
----
-
-## Related Components
-
-- [`Toggle`](./toggle.md) — Single standalone toggle
-- [`RadioGroup`](./radio-group.md) — Text-heavy single-choice alternatives
+# ToggleGroup
+
+## Overview
+
+A set of related `<Toggle>` buttons that operate together — either allowing only one selection at a time (`type="single"`) or multiple simultaneous selections (`type="multiple"`). Used for mutually exclusive view modes, filter groups, and formatting toolbars.
+
+---
+
+## When to Use
+
+- View mode switchers (Table / Grid / Kanban)
+- Text alignment controls (Left / Center / Right)
+- Multi-select filter chips in compact toolbars
+
+---
+
+## Props
+
+### ToggleGroup
+
+| Prop            | Type                     | Default | Required | Description          |
+| --------------- | ------------------------ | ------- | -------- | -------------------- |
+| `type`          | `'single' \| 'multiple'` | —       | **Yes**  | Selection mode       |
+| `value`         | `string \| string[]`     | —       | No       | Controlled value(s)  |
+| `defaultValue`  | `string \| string[]`     | —       | No       | Uncontrolled default |
+| `onValueChange` | `(value) => void`        | —       | No       | Change handler       |
+
+### ToggleGroupItem
+
+| Prop         | Type     | Required        | Description                       |
+| ------------ | -------- | --------------- | --------------------------------- |
+| `value`      | `string` | **Yes**         | Unique identifier for this option |
+| `aria-label` | `string` | Yes (icon-only) | Accessibility label               |
+
+---
+
+## Examples
+
+### View Mode Switcher
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from 'xertica-ui/ui';
+import { LayoutGrid, LayoutList } from 'lucide-react';
+
+<ToggleGroup type="single" defaultValue="list">
+  <ToggleGroupItem value="list" aria-label="List view">
+    <LayoutList className="size-4" />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="grid" aria-label="Grid view">
+    <LayoutGrid className="size-4" />
+  </ToggleGroupItem>
+</ToggleGroup>;
+```
+
+---
+
+## AI Rules
+
+- `type` is **required** — never omit it.
+- Always provide `aria-label` for icon-only items.
+- For text format toolbars (bold/italic/underline), use `type="multiple"` to allow simultaneous formatting.
+
+---
+
+## Related Components
+
+- [`Toggle`](./toggle.md) — Single standalone toggle
+- [`RadioGroup`](./radio-group.md) — Text-heavy single-choice alternatives

package/docs/components/toggle.md

@@ -1,62 +1,62 @@
-# Toggle
-
-## Overview
-
-A pressable button that maintains an on/off state visually, similar to a keyboard key that stays pressed. Used in toolbars for formatting, view switching, and feature activation.
-
----
-
-## When to Use
-
-- Text formatting toolbars (Bold, Italic, Underline)
-- View mode switches (List view / Grid view)
-- Filter activation buttons that remain pressed when active
-
-## When NOT to Use
-
-- Immediate action triggers — use `<Button>` instead.
-- Feature settings — use `<Switch>` or `<Checkbox>` for clearer semantics.
-
----
-
-## Props
-
-| Prop              | Type                         | Default     | Description                        |
-| ----------------- | ---------------------------- | ----------- | ---------------------------------- |
-| `pressed`         | `boolean`                    | —           | Controlled pressed state           |
-| `defaultPressed`  | `boolean`                    | `false`     | Uncontrolled initial state         |
-| `onPressedChange` | `(pressed: boolean) => void` | —           | Change handler                     |
-| `variant`         | `'default' \| 'outline'`     | `'default'` | Visual style                       |
-| `size`            | `'default' \| 'sm' \| 'lg'`  | `'default'` | Size preset                        |
-| `disabled`        | `boolean`                    | `false`     | Disables interaction               |
-| `aria-label`      | `string`                     | —           | **Required** for icon-only toggles |
-
----
-
-## Examples
-
-```tsx
-import { Toggle } from 'xertica-ui/ui';
-import { Bold } from 'lucide-react';
-
-<Toggle aria-label="Bold">
-  <Bold className="size-4" />
-</Toggle>;
-```
-
-### Controlled
-
-```tsx
-const [bold, setBold] = useState(false);
-
-<Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">
-  <Bold className="size-4" />
-</Toggle>;
-```
-
----
-
-## Related Components
-
-- [`ToggleGroup`](./toggle-group.md) — Multiple related toggles with exclusion
-- [`Switch`](./switch.md) — For settings toggles with clearer on/off semantics
+# Toggle
+
+## Overview
+
+A pressable button that maintains an on/off state visually, similar to a keyboard key that stays pressed. Used in toolbars for formatting, view switching, and feature activation.
+
+---
+
+## When to Use
+
+- Text formatting toolbars (Bold, Italic, Underline)
+- View mode switches (List view / Grid view)
+- Filter activation buttons that remain pressed when active
+
+## When NOT to Use
+
+- Immediate action triggers — use `<Button>` instead.
+- Feature settings — use `<Switch>` or `<Checkbox>` for clearer semantics.
+
+---
+
+## Props
+
+| Prop              | Type                         | Default     | Description                        |
+| ----------------- | ---------------------------- | ----------- | ---------------------------------- |
+| `pressed`         | `boolean`                    | —           | Controlled pressed state           |
+| `defaultPressed`  | `boolean`                    | `false`     | Uncontrolled initial state         |
+| `onPressedChange` | `(pressed: boolean) => void` | —           | Change handler                     |
+| `variant`         | `'default' \| 'outline'`     | `'default'` | Visual style                       |
+| `size`            | `'default' \| 'sm' \| 'lg'`  | `'default'` | Size preset                        |
+| `disabled`        | `boolean`                    | `false`     | Disables interaction               |
+| `aria-label`      | `string`                     | —           | **Required** for icon-only toggles |
+
+---
+
+## Examples
+
+```tsx
+import { Toggle } from 'xertica-ui/ui';
+import { Bold } from 'lucide-react';
+
+<Toggle aria-label="Bold">
+  <Bold className="size-4" />
+</Toggle>;
+```
+
+### Controlled
+
+```tsx
+const [bold, setBold] = useState(false);
+
+<Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">
+  <Bold className="size-4" />
+</Toggle>;
+```
+
+---
+
+## Related Components
+
+- [`ToggleGroup`](./toggle-group.md) — Multiple related toggles with exclusion
+- [`Switch`](./switch.md) — For settings toggles with clearer on/off semantics