@g4rcez/components 4.0.2 → 4.1.2

package/ai/docs/Switch.md

@@ -21,27 +21,27 @@ import { Switch } from "@g4rcez/components/switch";
 
 Inherits all standard HTML `input[type="checkbox"]` attributes, plus:
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode` | — | Label text or element displayed next to the switch. |
-| `onCheck` | `(nextValue: boolean) => void` | — | Called with the new boolean value after toggling. |
-| `error` | `string` | — | Error message displayed below the switch. |
-| `loading` | `boolean` | `false` | Disables the switch and signals a pending operation. |
-| `container` | `string` | — | Additional CSS classes for the outer `<fieldset>`. |
+| Prop        | Type                           | Default | Description                                          |
+| ----------- | ------------------------------ | ------- | ---------------------------------------------------- |
+| `children`  | `React.ReactNode`              | —       | Label text or element displayed next to the switch.  |
+| `onCheck`   | `(nextValue: boolean) => void` | —       | Called with the new boolean value after toggling.    |
+| `error`     | `string`                       | —       | Error message displayed below the switch.            |
+| `loading`   | `boolean`                      | `false` | Disables the switch and signals a pending operation. |
+| `container` | `string`                       | —       | Additional CSS classes for the outer `<fieldset>`.   |
 
 ## Design Tokens
 
 Tokens this component reads. Customize by overriding these CSS variables in your theme.
 
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
+| Token                | CSS Variable        | Purpose                         |
+| -------------------- | ------------------- | ------------------------------- |
 | `bg-input-switch-bg` | `--input-switch-bg` | Track background when unchecked |
-| `bg-primary` | `--primary` | Track background when checked |
-| `bg-disabled` | `--disabled` | Thumb fill when unchecked |
-| `bg-input-switch` | `--input-switch` | Thumb fill when checked |
-| `focus:ring-primary` | `--primary` | Focus ring on the toggle button |
-| `text-danger` | `--danger` | Error message color |
-| `text-foreground` | `--foreground` | Label text color |
+| `bg-primary`         | `--primary`         | Track background when checked   |
+| `bg-disabled`        | `--disabled`        | Thumb fill when unchecked       |
+| `bg-input-switch`    | `--input-switch`    | Thumb fill when checked         |
+| `focus:ring-primary` | `--primary`         | Focus ring on the toggle button |
+| `text-danger`        | `--danger`          | Error message color             |
+| `text-foreground`    | `--foreground`      | Label text color                |
 
 ## Themes
 
@@ -55,11 +55,11 @@ The switch appearance is driven entirely by design tokens. Override them in your
 import { Switch } from "@g4rcez/components/switch";
 
 export default function NotificationsToggle() {
-  return (
-    <Switch defaultChecked onChange={(e) => console.log(e.target.checked)}>
-      Enable notifications
-    </Switch>
-  );
+    return (
+        <Switch defaultChecked onChange={(e) => console.log(e.target.checked)}>
+            Enable notifications
+        </Switch>
+    );
 }
 ```
 
@@ -70,13 +70,13 @@ import { useState } from "react";
 import { Switch } from "@g4rcez/components/switch";
 
 export default function DarkModeToggle() {
-  const [enabled, setEnabled] = useState(false);
+    const [enabled, setEnabled] = useState(false);
 
-  return (
-    <Switch checked={enabled} onCheck={setEnabled}>
-      Dark mode
-    </Switch>
-  );
+    return (
+        <Switch checked={enabled} onCheck={setEnabled}>
+            Dark mode
+        </Switch>
+    );
 }
 ```
 
@@ -86,11 +86,7 @@ export default function DarkModeToggle() {
 import { Switch } from "@g4rcez/components/switch";
 
 export default function SyncSwitch() {
-  return (
-    <Switch loading>
-      Syncing data…
-    </Switch>
-  );
+    return <Switch loading>Syncing data…</Switch>;
 }
 ```
 
@@ -100,11 +96,7 @@ export default function SyncSwitch() {
 import { Switch } from "@g4rcez/components/switch";
 
 export default function TermsSwitch() {
-  return (
-    <Switch error="You must accept the terms to continue">
-      Accept terms and conditions
-    </Switch>
-  );
+    return <Switch error="You must accept the terms to continue">Accept terms and conditions</Switch>;
 }
 ```
 
@@ -114,19 +106,17 @@ export default function TermsSwitch() {
 import { Switch } from "@g4rcez/components/switch";
 
 export default function PrivacySettings() {
-  return (
-    <div className="flex flex-col gap-base">
-      <Switch defaultChecked onCheck={(v) => updateSetting("emails", v)}>
-        Receive marketing emails
-      </Switch>
-      <Switch onCheck={(v) => updateSetting("analytics", v)}>
-        Share analytics data
-      </Switch>
-      <Switch defaultChecked onCheck={(v) => updateSetting("notifications", v)}>
-        Push notifications
-      </Switch>
-    </div>
-  );
+    return (
+        <div className="flex flex-col gap-base">
+            <Switch defaultChecked onCheck={(v) => updateSetting("emails", v)}>
+                Receive marketing emails
+            </Switch>
+            <Switch onCheck={(v) => updateSetting("analytics", v)}>Share analytics data</Switch>
+            <Switch defaultChecked onCheck={(v) => updateSetting("notifications", v)}>
+                Push notifications
+            </Switch>
+        </div>
+    );
 }
 ```
 
@@ -154,11 +144,11 @@ export default function PrivacySettings() {
 
 ## Data Attributes
 
-| Attribute | Element | Value | Description |
-|-----------|---------|-------|-------------|
-| `data-component` | `fieldset` | `"switch"` | Identifies the component. |
-| `data-checked` | `input`, `button`, thumb `span` | `"true" \| "false"` | Reflects the checked state for CSS targeting. |
-| `data-trigger` | `input` | `"change"` | Used internally to track the synthetic change event. |
+| Attribute        | Element                         | Value               | Description                                          |
+| ---------------- | ------------------------------- | ------------------- | ---------------------------------------------------- |
+| `data-component` | `fieldset`                      | `"switch"`          | Identifies the component.                            |
+| `data-checked`   | `input`, `button`, thumb `span` | `"true" \| "false"` | Reflects the checked state for CSS targeting.        |
+| `data-trigger`   | `input`                         | `"change"`          | Used internally to track the synthetic change event. |
 
 ## Notes
 

package/ai/docs/Table.md

@@ -21,25 +21,25 @@ import { Table, createColumns, useTablePreferences, ColType } from "@g4rcez/comp
 
 ### Table
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `name` | `string` | — | Unique identifier used to persist user preferences in `localStorage`. |
-| `cols` | `Col<T>[]` | — | Column definitions produced by `createColumns`. |
-| `rows` | `T[]` | — | Data array to render. Each element maps to a table row. |
-| `loading` | `boolean` | `false` | Replaces rows with animated skeleton cells while data loads. |
-| `loadingMore` | `boolean` | `false` | Shows a pulse footer bar for infinite-scroll loading indicators. |
-| `operations` | `boolean` | `true` | Toggles the metadata bar (bulk filter, sort, group controls). |
-| `inlineFilter` | `boolean` | `true` | Enables per-column filter dropdowns in the header row. |
-| `inlineSorter` | `boolean` | `true` | Enables per-column sort toggles in the header row. |
-| `sticky` | `number \| null` | — | `top` offset in px for the sticky header. Pass `null` to disable stickiness. |
-| `Aside` | `React.FC<CellAsideElement<T>>` | — | Component rendered before the first cell in every row (e.g., row-level actions). |
-| `pagination` | `TablePagination` | — | Pagination configuration. When provided, a footer with page controls is shown. |
-| `reference` | `keyof T` | — | Field used as the stable row key. |
-| `useControl` | `boolean` | `false` | When `true`, disables internal filtering/sorting so you can drive it externally. |
-| `onScrollEnd` | `() => void` | — | Called when the user scrolls to the last row (infinite scroll trigger). |
-| `getScrollRef` | `() => HTMLElement \| undefined` | — | Returns a custom scroll container instead of `window`. |
-| `getRowProps` | `(row: T) => ComponentProps<"tr">` | — | Merge arbitrary `<tr>` props (e.g., `onClick`, `className`) per row. |
-| `set` | `(v: TableGetters<T>) => void` | — | External callback invoked whenever internal table state changes. |
+| Prop           | Type                               | Default | Description                                                                      |
+| -------------- | ---------------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `name`         | `string`                           | —       | Unique identifier used to persist user preferences in `localStorage`.            |
+| `cols`         | `Col<T>[]`                         | —       | Column definitions produced by `createColumns`.                                  |
+| `rows`         | `T[]`                              | —       | Data array to render. Each element maps to a table row.                          |
+| `loading`      | `boolean`                          | `false` | Replaces rows with animated skeleton cells while data loads.                     |
+| `loadingMore`  | `boolean`                          | `false` | Shows a pulse footer bar for infinite-scroll loading indicators.                 |
+| `operations`   | `boolean`                          | `true`  | Toggles the metadata bar (bulk filter, sort, group controls).                    |
+| `inlineFilter` | `boolean`                          | `true`  | Enables per-column filter dropdowns in the header row.                           |
+| `inlineSorter` | `boolean`                          | `true`  | Enables per-column sort toggles in the header row.                               |
+| `sticky`       | `number \| null`                   | —       | `top` offset in px for the sticky header. Pass `null` to disable stickiness.     |
+| `Aside`        | `React.FC<CellAsideElement<T>>`    | —       | Component rendered before the first cell in every row (e.g., row-level actions). |
+| `pagination`   | `TablePagination`                  | —       | Pagination configuration. When provided, a footer with page controls is shown.   |
+| `reference`    | `keyof T`                          | —       | Field used as the stable row key.                                                |
+| `useControl`   | `boolean`                          | `false` | When `true`, disables internal filtering/sorting so you can drive it externally. |
+| `onScrollEnd`  | `() => void`                       | —       | Called when the user scrolls to the last row (infinite scroll trigger).          |
+| `getScrollRef` | `() => HTMLElement \| undefined`   | —       | Returns a custom scroll container instead of `window`.                           |
+| `getRowProps`  | `(row: T) => ComponentProps<"tr">` | —       | Merge arbitrary `<tr>` props (e.g., `onClick`, `className`) per row.             |
+| `set`          | `(v: TableGetters<T>) => void`     | —       | External callback invoked whenever internal table state changes.                 |
 
 ### createColumns
 
@@ -52,38 +52,38 @@ createColumns<T>((c) => {
 })
 ```
 
-| Builder method | Signature | Description |
-|----------------|-----------|-------------|
-| `add` | `(id: AllPaths<T>, thead: ReactNode, options?: ColOptions<T, K>) => void` | Registers a column. |
-| `remove` | `(id: AllPaths<T>) => void` | Removes a column by id. |
-| `filter` | `(c: (col: Col<T>) => boolean) => Col<T>[]` | Filters the column list in-place. |
-| `getAll` | `() => Col<T>[]` | Returns a copy of all registered columns. |
+| Builder method | Signature                                                                 | Description                               |
+| -------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
+| `add`          | `(id: AllPaths<T>, thead: ReactNode, options?: ColOptions<T, K>) => void` | Registers a column.                       |
+| `remove`       | `(id: AllPaths<T>) => void`                                               | Removes a column by id.                   |
+| `filter`       | `(c: (col: Col<T>) => boolean) => Col<T>[]`                               | Filters the column list in-place.         |
+| `getAll`       | `() => Col<T>[]`                                                          | Returns a copy of all registered columns. |
 
 ### ColOptions
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `type` | `ColType` | `ColType.Text` | Data type (`Text`, `Number`, `Boolean`, `Select`). Affects filter operators. |
-| `allowSort` | `boolean` | `true` | Whether this column can be sorted. |
-| `allowFilter` | `boolean` | `true` | Whether this column shows a filter control. |
-| `headerLabel` | `string` | — | Overrides the column header text used in the filter/sort metadata bar. |
-| `Element` | `React.FC<CellPropsElement<T, K>>` | — | Custom cell renderer. Receives `{ row, value, rowIndex, matrix, col }`. |
-| `thProps` | `HTMLAttributes<HTMLTableCellElement>` | — | Extra props forwarded to the `<th>` element. |
-| `cellProps` | `HTMLAttributes<HTMLTableCellElement>` | — | Extra props forwarded to each `<td>` element. |
+| Option        | Type                                   | Default        | Description                                                                  |
+| ------------- | -------------------------------------- | -------------- | ---------------------------------------------------------------------------- |
+| `type`        | `ColType`                              | `ColType.Text` | Data type (`Text`, `Number`, `Boolean`, `Select`). Affects filter operators. |
+| `allowSort`   | `boolean`                              | `true`         | Whether this column can be sorted.                                           |
+| `allowFilter` | `boolean`                              | `true`         | Whether this column shows a filter control.                                  |
+| `headerLabel` | `string`                               | —              | Overrides the column header text used in the filter/sort metadata bar.       |
+| `Element`     | `React.FC<CellPropsElement<T, K>>`     | —              | Custom cell renderer. Receives `{ row, value, rowIndex, matrix, col }`.      |
+| `thProps`     | `HTMLAttributes<HTMLTableCellElement>` | —              | Extra props forwarded to the `<th>` element.                                 |
+| `cellProps`   | `HTMLAttributes<HTMLTableCellElement>` | —              | Extra props forwarded to each `<td>` element.                                |
 
 ### TablePagination
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `size` | `number` | Current page size. |
-| `pages` | `number` | Total number of pages. |
-| `current` | `number` | Current page index (1-based). |
-| `hasNext` | `boolean` | Whether a next page exists. |
-| `hasPrevious` | `boolean` | Whether a previous page exists. |
-| `totalItems` | `number` | Total row count across all pages. |
-| `sizes` | `number[]` | Optional list of selectable page sizes. |
-| `onChangeSize` | `(size: number) => void` | Called when the user selects a different page size. |
-| `asLink` | `React.FC<{ href: number \| "previous" \| "next"; className: string }>` | Polymorphic page button — supply a router `Link` for deep-linkable pages. |
+| Field          | Type                                                                    | Description                                                               |
+| -------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `size`         | `number`                                                                | Current page size.                                                        |
+| `pages`        | `number`                                                                | Total number of pages.                                                    |
+| `current`      | `number`                                                                | Current page index (1-based).                                             |
+| `hasNext`      | `boolean`                                                               | Whether a next page exists.                                               |
+| `hasPrevious`  | `boolean`                                                               | Whether a previous page exists.                                           |
+| `totalItems`   | `number`                                                                | Total row count across all pages.                                         |
+| `sizes`        | `number[]`                                                              | Optional list of selectable page sizes.                                   |
+| `onChangeSize` | `(size: number) => void`                                                | Called when the user selects a different page size.                       |
+| `asLink`       | `React.FC<{ href: number \| "previous" \| "next"; className: string }>` | Polymorphic page button — supply a router `Link` for deep-linkable pages. |
 
 ### useTablePreferences
 
@@ -94,37 +94,37 @@ const prefs = useTablePreferences("users-table", columns, options?);
 // Spread into <Table {...prefs} rows={data} />
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Storage key (`@components/table-{name}`). |
-| `cols` | `Col<T>[]` | Initial column definitions. |
+| Parameter | Type                       | Description                                                                |
+| --------- | -------------------------- | -------------------------------------------------------------------------- |
+| `name`    | `string`                   | Storage key (`@components/table-{name}`).                                  |
+| `cols`    | `Col<T>[]`                 | Initial column definitions.                                                |
 | `options` | `Partial<TableGetters<T>>` | Optional initial state overrides for filters, sorters, groups, pagination. |
 
 ## Design Tokens
 
 Tokens this component reads. Customize by overriding these CSS variables in your theme.
 
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `bg-table-header` | `--table-header` | Column header background |
-| `bg-table-background` | `--table-background` | Table body background |
-| `border-table-border` | `--table-border` | Column separator and row divider color |
-| `shadow-shadow-table` | `--shadow-table` | Table card shadow |
-| `bg-card-background` | `--card-background` | Footer and loading-more bar background |
-| `text-foreground` | `--foreground` | Default cell text color |
-| `text-primary` | `--primary` | Active filter / sort accent color |
-| `bg-muted` | `--muted` | Hover background for metadata bar items |
+| Token                 | CSS Variable         | Purpose                                 |
+| --------------------- | -------------------- | --------------------------------------- |
+| `bg-table-header`     | `--table-header`     | Column header background                |
+| `bg-table-background` | `--table-background` | Table body background                   |
+| `border-table-border` | `--table-border`     | Column separator and row divider color  |
+| `shadow-shadow-table` | `--shadow-table`     | Table card shadow                       |
+| `bg-card-background`  | `--card-background`  | Footer and loading-more bar background  |
+| `text-foreground`     | `--foreground`       | Default cell text color                 |
+| `text-primary`        | `--primary`          | Active filter / sort accent color       |
+| `bg-muted`            | `--muted`            | Hover background for metadata bar items |
 
 The `--table-cell-padding` CSS variable controls cell padding (default `0.75rem`). Override it via `className` on `<Table>`.
 
 ## Column Types
 
-| `ColType` | Enum value | Filter operators available |
-|-----------|-----------|---------------------------|
-| `ColType.Text` | `"text"` | contains, equals, starts with, ends with |
-| `ColType.Number` | `"number"` | =, ≠, >, <, ≥, ≤ |
-| `ColType.Boolean` | `"boolean"` | is true, is false |
-| `ColType.Select` | `"select"` | equals |
+| `ColType`         | Enum value  | Filter operators available               |
+| ----------------- | ----------- | ---------------------------------------- |
+| `ColType.Text`    | `"text"`    | contains, equals, starts with, ends with |
+| `ColType.Number`  | `"number"`  | =, ≠, >, <, ≥, ≤                         |
+| `ColType.Boolean` | `"boolean"` | is true, is false                        |
+| `ColType.Select`  | `"select"`  | equals                                   |
 
 ## Examples
 
@@ -136,19 +136,13 @@ import { Table, createColumns } from "@g4rcez/components/table";
 type User = { id: string; name: string; email: string };
 
 const columns = createColumns<User>((c) => {
-  c.add("id", "ID");
-  c.add("name", "Name");
-  c.add("email", "Email");
+    c.add("id", "ID");
+    c.add("name", "Name");
+    c.add("email", "Email");
 });
 
 export function UsersTable({ users }: { users: User[] }) {
-  return (
-    <Table
-      name="users"
-      cols={columns}
-      rows={users}
-    />
-  );
+    return <Table name="users" cols={columns} rows={users} />;
 }
 ```
 
@@ -161,24 +155,22 @@ import { Tag } from "@g4rcez/components/tag";
 type Product = { sku: string; name: string; price: number; active: boolean };
 
 const columns = createColumns<Product>((c) => {
-  c.add("sku", "SKU");
-  c.add("name", "Product Name", { allowFilter: true, allowSort: true });
-  c.add("price", "Price", {
-    type: ColType.Number,
-    Element: ({ value }) => (
-      <span className="font-mono tabular-nums">
-        {value.toLocaleString("en-US", { style: "currency", currency: "USD" })}
-      </span>
-    ),
-  });
-  c.add("active", "Status", {
-    type: ColType.Boolean,
-    Element: ({ value }) => (
-      <Tag theme={value ? "success" : "neutral"} size="small">
-        {value ? "Active" : "Inactive"}
-      </Tag>
-    ),
-  });
+    c.add("sku", "SKU");
+    c.add("name", "Product Name", { allowFilter: true, allowSort: true });
+    c.add("price", "Price", {
+        type: ColType.Number,
+        Element: ({ value }) => (
+            <span className="font-mono tabular-nums">{value.toLocaleString("en-US", { style: "currency", currency: "USD" })}</span>
+        ),
+    });
+    c.add("active", "Status", {
+        type: ColType.Boolean,
+        Element: ({ value }) => (
+            <Tag theme={value ? "success" : "neutral"} size="small">
+                {value ? "Active" : "Inactive"}
+            </Tag>
+        ),
+    });
 });
 ```
 
@@ -188,14 +180,14 @@ const columns = createColumns<Product>((c) => {
 import { Table, createColumns, useTablePreferences } from "@g4rcez/components/table";
 
 const baseColumns = createColumns<Order>((c) => {
-  c.add("id", "Order ID");
-  c.add("status", "Status");
-  c.add("total", "Total");
+    c.add("id", "Order ID");
+    c.add("status", "Status");
+    c.add("total", "Total");
 });
 
 export function OrdersTable({ orders }: { orders: Order[] }) {
-  const prefs = useTablePreferences("orders-table", baseColumns);
-  return <Table {...prefs} rows={orders} />;
+    const prefs = useTablePreferences("orders-table", baseColumns);
+    return <Table {...prefs} rows={orders} />;
 }
 ```
 
@@ -203,23 +195,25 @@ export function OrdersTable({ orders }: { orders: Order[] }) {
 
 ```tsx
 <Table
-  name="invoices"
-  cols={columns}
-  rows={pageData}
-  useControl
-  pagination={{
-    current: page,
-    pages: totalPages,
-    size: pageSize,
-    totalItems: totalCount,
-    hasNext: page < totalPages,
-    hasPrevious: page > 1,
-    sizes: [10, 25, 50],
-    onChangeSize: setPageSize,
-    asLink: ({ href, className, children }) => (
-      <a href={`?page=${href}`} className={className}>{children}</a>
-    ),
-  }}
+    name="invoices"
+    cols={columns}
+    rows={pageData}
+    useControl
+    pagination={{
+        current: page,
+        pages: totalPages,
+        size: pageSize,
+        totalItems: totalCount,
+        hasNext: page < totalPages,
+        hasPrevious: page > 1,
+        sizes: [10, 25, 50],
+        onChangeSize: setPageSize,
+        asLink: ({ href, className, children }) => (
+            <a href={`?page=${href}`} className={className}>
+                {children}
+            </a>
+        ),
+    }}
 />
 ```
 
@@ -229,32 +223,26 @@ export function OrdersTable({ orders }: { orders: Order[] }) {
 import { TrashIcon, PencilIcon } from "@phosphor-icons/react";
 
 <Table
-  name="contacts"
-  cols={columns}
-  rows={contacts}
-  Aside={({ row }) => (
-    <div className="flex gap-1">
-      <button onClick={() => edit(row)} aria-label="Edit">
-        <PencilIcon size={14} />
-      </button>
-      <button onClick={() => remove(row)} aria-label="Delete" className="hover:text-danger">
-        <TrashIcon size={14} />
-      </button>
-    </div>
-  )}
-/>
+    name="contacts"
+    cols={columns}
+    rows={contacts}
+    Aside={({ row }) => (
+        <div className="flex gap-1">
+            <button onClick={() => edit(row)} aria-label="Edit">
+                <PencilIcon size={14} />
+            </button>
+            <button onClick={() => remove(row)} aria-label="Delete" className="hover:text-danger">
+                <TrashIcon size={14} />
+            </button>
+        </div>
+    )}
+/>;
 ```
 
 ### Infinite scroll
 
 ```tsx
-<Table
-  name="feed"
-  cols={columns}
-  rows={items}
-  loadingMore={isFetchingNextPage}
-  onScrollEnd={fetchNextPage}
-/>
+<Table name="feed" cols={columns} rows={items} loadingMore={isFetchingNextPage} onScrollEnd={fetchNextPage} />
 ```
 
 ## Do