@skunkworksai/ui-kit 0.1.18

package/rules/table-manager.md

@@ -0,0 +1,306 @@
+# TableManager
+
+> Docs: https://ui-kit.vercel.app/docs/blocks/table-manager
+
+**This is a block — import from `blocks/TableManager`, not `primitives/`.**
+
+```tsx
+import {
+  TableManager,
+  TableManagerToolbar,
+  TableManagerSearch,
+  TableManagerToolbarActions,
+  TableManagerMultiFilter,
+  TableManagerDateRange,
+  TableManagerRowsPerPage,
+  TableManagerPagination,
+  TableManagerColumnToggle,
+  TableManagerExport,
+  TableManagerContent,
+  TableManagerFooter,
+  type TableManagerColumnDef,
+  type TableManagerFilterOption,
+  type TableManagerExportOption,
+} from "@/components/blocks/TableManager"
+```
+
+## Hard stop
+
+> ❌ **Never build a data table + toolbar manually using `AppTable`, `AppPagination`, and raw inputs.**
+>
+> `TableManager` handles sort state, column visibility, drag-to-reorder columns, row selection, loading overlay, search debounce, multiselect filters, date range, and pagination UI. Building this from scratch will produce inconsistent behaviour and visual drift. Use this block.
+
+## Data model
+
+TableManager uses a **hybrid data model**:
+
+| Concern | Where it lives |
+|---------|---------------|
+| Filtering (search, multiselect, date range) | **Server-side** — block fires callbacks; consumer fetches and passes filtered data |
+| Sorting | **Client-side** — block sorts the `data` prop internally |
+| Pagination | **Server-side** — consumer passes `totalCount`; block renders pagination UI |
+| Column visibility / order | **Client-side** — block owns this state internally |
+| Row selection | **Client-side** — block owns this state; fires `onSelectionChange` |
+
+All row objects must have `id: string | number`.
+
+## Types
+
+```tsx
+type TableManagerColumnDef<T> = {
+  id: string                               // Unique column identifier
+  header: string                           // Column header label
+  type?: "date" | "text" | "other"         // Drives default sort order
+  accessorKey?: keyof T                    // Key for reading cell values
+  cell?: (row: T) => React.ReactNode       // Custom cell renderer
+  enableSorting?: boolean                  // Click label to sort (default: false)
+  enableFiltering?: boolean                // Show filter icon on header (default: false)
+  filterPopover?: () => React.ReactNode    // Body of the column's filter popover
+  defaultVisible?: boolean                 // Initially visible (default: true)
+  headerClassName?: string                 // Extra class on the rendered <TableHead>
+  headerAlign?: "left" | "right" | "center"  // Header content alignment
+  cellAlign?: "left" | "right" | "center"    // Body cell text alignment
+  headerCell?: () => React.ReactNode       // Full custom header renderer (overrides text/sort/filter content)
+}
+
+type TableManagerFilterOption = {
+  value: string
+  label: string
+  icon?: React.ReactNode
+}
+
+type TableManagerExportOption = {
+  label: string
+  value: string
+  icon?: React.ReactNode
+}
+```
+
+## Props — TableManager
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `TableManagerColumnDef<T>[]` | required | Column definitions. Drive headers, cell renderers, sort, and filter. |
+| `data` | `T[]` | required | Server-filtered rows for the current page. Must have `id: string \| number`. |
+| `totalCount` | `number` | required | Total records across all pages (for pagination math). |
+| `loading` | `boolean` | `false` | Shows a loading overlay on the table content while data is fetching. Toolbar and footer remain interactive. |
+| `defaultRowsPerPage` | `number` | `20` | Initial rows-per-page value. |
+| `defaultVisibleColumns` | `string[]` | all | Column IDs to show on initial render. |
+| `defaultFilters` | `Record<string, string[]>` | `{}` | Initial filter selections. Use to pre-check multiselect filters. |
+| `onSearchChange` | `(term: string) => void` | — | Fired when search input changes (debounced 300 ms). |
+| `onFilterChange` | `(filters: Record<string, string[]>) => void` | — | Fired when any multiselect filter changes. |
+| `onDateRangeChange` | `(range: { from?: Date; to?: Date }) => void` | — | Fired when the date range changes. |
+| `onPageChange` | `(page: number) => void` | — | Fired when the page changes (0-indexed). |
+| `onRowsPerPageChange` | `(rowsPerPage: number) => void` | — | Fired when rows per page changes. |
+| `onSelectionChange` | `(rows: T[]) => void` | — | Fired when row selection changes. |
+
+## Default sort order
+
+When no column header has been clicked, data is sorted by:
+
+1. First column with `type: "date"` — **descending** (most recent first)
+2. If no date column, first column with `type: "text"` — **ascending**
+3. If neither, natural order
+
+Clicking a sortable column header cycles: **desc → asc → default**.
+
+## Column header interactions
+
+Each column header supports two independent click targets:
+
+- **Label click** — sorts the column client-side (if `enableSorting: true`)
+- **Filter icon click** — opens a popover anchored to the header (if `enableFiltering: true` and `filterPopover` is provided)
+
+A column may have both `enableSorting` and `enableFiltering` set simultaneously.
+
+## Usage
+
+### Minimal
+
+```tsx
+const columns: TableManagerColumnDef<Row>[] = [
+  { id: "name", header: "Name", type: "text", accessorKey: "name", enableSorting: true },
+  { id: "status", header: "Status", accessorKey: "status" },
+  { id: "date", header: "Date", type: "date", accessorKey: "date", enableSorting: true },
+]
+
+export default function Page() {
+  const [data, setData] = React.useState<Row[]>(rows)
+
+  return (
+    <TableManager
+      columns={columns}
+      data={data}
+      totalCount={data.length}
+      onSearchChange={(term) => setData(rows.filter(r => r.name.includes(term)))}
+    >
+      <TableManagerToolbar>
+        <TableManagerSearch placeholder="Search..." />
+        <TableManagerToolbarActions>
+          <TableManagerPagination />
+        </TableManagerToolbarActions>
+      </TableManagerToolbar>
+      <TableManagerContent />
+      <TableManagerFooter />
+    </TableManager>
+  )
+}
+```
+
+### Full toolbar
+
+```tsx
+<TableManager
+  columns={columns}
+  data={data}
+  totalCount={totalCount}
+  loading={loading}
+  defaultFilters={{ applet: ["sami", "zone"] }}
+  onSearchChange={handleSearch}
+  onFilterChange={handleFilter}
+  onDateRangeChange={handleDateRange}
+  onPageChange={handlePage}
+  onRowsPerPageChange={handleRowsPerPage}
+  onSelectionChange={handleSelection}
+>
+  <TableManagerToolbar>
+    <TableManagerSearch placeholder="Search sessions..." />
+    <TableManagerToolbarActions>
+      <TableManagerMultiFilter
+        name="applet"
+        label="Service Applet"
+        icon={<img src={icon.src} alt="" className="size-5 rounded object-cover" />}
+        options={appletOptions}
+        searchPlaceholder="Search Service Applet"
+      />
+      <TableManagerDateRange />
+      <TableManagerRowsPerPage />
+      <TableManagerPagination />
+      <TableManagerColumnToggle />
+      <TableManagerExport
+        options={[{ label: "CSV", value: "csv" }]}
+        onExport={(fmt) => exportAs(fmt)}
+      />
+    </TableManagerToolbarActions>
+  </TableManagerToolbar>
+  <TableManagerContent />
+  <TableManagerFooter />
+</TableManager>
+```
+
+### Pre-checked multiselect filter
+
+Use `defaultFilters` to pre-select all options. The consumer's `onFilterChange` should use OR logic: a row is visible if any of its values match any checked option.
+
+```tsx
+<TableManager
+  defaultFilters={{ applet: ["sami", "zone", "shelf"] }}
+  onFilterChange={(filters) => {
+    const checked = filters["applet"] ?? []
+    const filtered = checked.length === 0
+      ? []
+      : rows.filter(r => r.applets.some(a => checked.includes(a)))
+    setData(filtered)
+  }}
+  ...
+>
+```
+
+### Right-aligned actions column
+
+Use `headerAlign` and `cellAlign` to mirror header alignment with cell alignment. Both accept `"left" | "right" | "center"`.
+
+```tsx
+{
+  id: "actions",
+  header: "Actions",
+  headerAlign: "right",
+  cellAlign: "right",
+  cell: (row) => (
+    <AppButton size="sm" variant="ghost" onClick={() => edit(row)}>Edit</AppButton>
+  ),
+}
+```
+
+When `headerCell` is provided it fully replaces the header content (text + sort icon + filter icon). `headerClassName` still applies.
+
+```tsx
+{
+  id: "actions",
+  header: "Actions",
+  headerCell: () => (
+    <div className="flex justify-end">
+      <span className="text-xs text-muted-foreground">Actions</span>
+    </div>
+  ),
+  cellAlign: "right",
+  cell: (row) => <AppButton size="sm">Edit</AppButton>,
+}
+```
+
+### Custom cell renderer
+
+```tsx
+{
+  id: "status",
+  header: "Status",
+  accessorKey: "status",
+  cell: (row) => (
+    <AppBadge variant={row.status === "PASSED" ? "default" : "destructive"}>
+      {row.status}
+    </AppBadge>
+  ),
+}
+```
+
+### Column-level filter popover
+
+```tsx
+{
+  id: "site",
+  header: "Site",
+  accessorKey: "site",
+  enableSorting: true,
+  enableFiltering: true,
+  filterPopover: () => (
+    <div className="p-2">
+      {/* your filter UI here */}
+    </div>
+  ),
+}
+```
+
+### Extending the toolbar
+
+`TableManagerToolbarActions` is an open slot — add any custom controls inside it:
+
+```tsx
+<TableManagerToolbarActions>
+  <TableManagerMultiFilter ... />
+  <TableManagerDateRange />
+  <TableManagerPagination />
+  <TableManagerColumnToggle />
+  <TableManagerExport ... />
+  {/* custom */}
+  <AppButton variant="outline" size="sm">Custom Action</AppButton>
+</TableManagerToolbarActions>
+```
+
+## Rules
+
+- ✅ Always wrap everything in `<TableManager>` before using any sub-component
+- ✅ All row objects must have `id: string | number`
+- ✅ Pass `totalCount` equal to the total filtered record count (not just the current page length) for correct pagination
+- ✅ Use `defaultFilters` to pre-select multiselect filter options so they render as checked on first render
+- ✅ Implement OR logic in `onFilterChange` when a row can belong to multiple filter values
+- ✅ Set `type: "date"` on date columns and `type: "text"` on primary text columns so the default sort works correctly
+- ✅ Use `TableManagerToolbarActions` with `shrink-0` behavior built in — it will not compress when the search input grows
+- ❌ Never import sub-components outside of a `<TableManager>` tree — they read from internal context and will throw
+- ❌ Never filter data internally in the block — always pass already-filtered data via the `data` prop
+- ❌ Never add `date-fns` or a date library just for this block — it uses native `Date` methods
+- ❌ Never use arbitrary CSS selectors (`:last-child`, `[&_th:last-child]`) to align column headers — use `headerAlign` / `headerCell` instead
+- ❌ If a prop you need is missing, stop and inform the design team
+
+## Responsive
+
+`TableManagerToolbar` wraps with `flex-wrap` on small screens. `TableManagerToolbarActions` loses its `ml-auto` below `sm` and flows inline with other toolbar children. Wrapping is automatic — no consumer change needed.

package/rules/table.md

@@ -0,0 +1,177 @@
+# AppTable
+
+> Docs: https://ui-kit.vercel.app/docs/components/table
+
+```tsx
+import {
+  AppTable,
+  AppTableHeader,
+  AppTableBody,
+  AppTableFooter,
+  AppTableHead,
+  AppTableRow,
+  AppTableCell,
+  AppTableCaption,
+} from "@/components/primitives/AppTable"
+```
+
+## Sub-components
+
+### AppTable
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Merged onto `<table>` via `cn()`. The overflow scroll wrapper is not className-accessible. |
+
+### AppTableHeader
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Merged onto `<thead>`. Default: `[&_tr]:border-b`. |
+
+### AppTableBody
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Merged onto `<tbody>`. Default removes border from the last row. |
+
+### AppTableFooter
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Merged onto `<tfoot>`. Default: `border-t bg-muted/50 font-medium [&>tr]:last:border-b-0`. |
+
+### AppTableHead
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Merged onto `<th>`. Default: `h-10 px-2 text-left align-middle font-medium text-muted-foreground`. |
+
+### AppTableRow
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data-state` | `"selected" \| undefined` | — | Set to `"selected"` to apply the selection highlight (`bg-muted`). Controlled by your state. |
+| `className` | `string` | — | Merged onto `<tr>`. Default: `border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted`. |
+
+### AppTableCell
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `colSpan` | `number` | — | Span multiple columns. Common in footer summary rows. |
+| `className` | `string` | — | Merged onto `<td>`. Default: `p-2 align-middle`. |
+
+### AppTableCaption
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Merged onto `<caption>`. Default: `mt-4 text-sm text-muted-foreground`. Renders below body via `caption-bottom`. |
+
+## Usage
+
+### Basic
+
+```tsx
+<AppTable>
+  <AppTableHeader>
+    <AppTableRow>
+      <AppTableHead>Name</AppTableHead>
+      <AppTableHead>Role</AppTableHead>
+    </AppTableRow>
+  </AppTableHeader>
+  <AppTableBody>
+    <AppTableRow>
+      <AppTableCell>John Doe</AppTableCell>
+      <AppTableCell>Admin</AppTableCell>
+    </AppTableRow>
+  </AppTableBody>
+</AppTable>
+```
+
+### With caption
+
+Place `AppTableCaption` as the first child of `AppTable`. It renders below the body via `caption-bottom`.
+
+```tsx
+<AppTable>
+  <AppTableCaption>A list of your recent invoices.</AppTableCaption>
+  <AppTableHeader>
+    <AppTableRow>
+      <AppTableHead>Invoice</AppTableHead>
+      <AppTableHead>Status</AppTableHead>
+      <AppTableHead className="text-right">Amount</AppTableHead>
+    </AppTableRow>
+  </AppTableHeader>
+  <AppTableBody>
+    <AppTableRow>
+      <AppTableCell className="font-medium">INV-001</AppTableCell>
+      <AppTableCell>Paid</AppTableCell>
+      <AppTableCell className="text-right">$250.00</AppTableCell>
+    </AppTableRow>
+  </AppTableBody>
+</AppTable>
+```
+
+### With footer
+
+Use `AppTableFooter` for totals or summary rows. Use `colSpan` on `AppTableCell` to span multiple columns.
+
+```tsx
+<AppTable>
+  <AppTableHeader>
+    <AppTableRow>
+      <AppTableHead>Invoice</AppTableHead>
+      <AppTableHead>Status</AppTableHead>
+      <AppTableHead className="text-right">Amount</AppTableHead>
+    </AppTableRow>
+  </AppTableHeader>
+  <AppTableBody>
+    <AppTableRow>
+      <AppTableCell className="font-medium">INV-001</AppTableCell>
+      <AppTableCell>Paid</AppTableCell>
+      <AppTableCell className="text-right">$250.00</AppTableCell>
+    </AppTableRow>
+  </AppTableBody>
+  <AppTableFooter>
+    <AppTableRow>
+      <AppTableCell colSpan={2}>Total</AppTableCell>
+      <AppTableCell className="text-right">$250.00</AppTableCell>
+    </AppTableRow>
+  </AppTableFooter>
+</AppTable>
+```
+
+### With selected row
+
+Set `data-state="selected"` on any `AppTableRow` to apply the selection highlight. No built-in selection logic is included — control this via your own state.
+
+```tsx
+const [selectedId, setSelectedId] = React.useState<string | null>(null)
+
+<AppTableBody>
+  {rows.map((row) => (
+    <AppTableRow
+      key={row.id}
+      data-state={selectedId === row.id ? "selected" : undefined}
+      onClick={() => setSelectedId(row.id)}
+    >
+      <AppTableCell>{row.name}</AppTableCell>
+      <AppTableCell>{row.email}</AppTableCell>
+    </AppTableRow>
+  ))}
+</AppTableBody>
+```
+
+## Rules
+
+- ✅ Always use `AppTable` and its sub-components — never use raw `<table>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>`, or `<caption>`
+- ✅ Use `AppTableHeader` for column title rows and `AppTableBody` for data rows
+- ✅ Place `AppTableCaption` as the **first child** of `AppTable`
+- ✅ Use `AppTableFooter` for totals and aggregates — it applies the correct muted background automatically
+- ✅ Use `colSpan` on `AppTableCell` in footer rows to span multiple columns
+- ✅ Control row selection via `data-state="selected"` on `AppTableRow` — do not add custom selected styling
+- ❌ Do not add `border-b` manually to rows — `AppTableRow` already applies it
+- ❌ Do not nest `AppTableHead` inside `AppTableBody` or `AppTableCell` inside `AppTableHeader`
+- ❌ Do not place `AppTableCaption` after `AppTableBody` — always put it first inside `AppTable`
+- ❌ Do not apply direct width/height to table cells unless absolutely necessary — use container-level Tailwind classes instead
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/tabs.md

@@ -0,0 +1,82 @@
+# AppTabs
+
+> Docs: https://ui-kit.vercel.app/docs/components/tabs
+
+```tsx
+import { AppTabs, AppTabsList, AppTabsTrigger, AppTabsContent } from "@/components/primitives/AppTabs"
+```
+
+## AppTabs
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "underline" \| "pills"` | `"default"` | Visual style — propagates automatically to `AppTabsList` and `AppTabsTrigger` |
+| `defaultValue` | `string` | — | The value of the tab that should be active by default |
+| `value` | `string` | — | The controlled value of the active tab |
+| `onValueChange` | `(value: string) => void` | — | Event handler called when the value changes |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the tabs |
+
+## AppTabsTrigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | A unique value for the tab |
+| `disabled` | `boolean` | `false` | When true, prevents the user from interacting with the tab |
+
+## AppTabsContent
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | A unique value that associates the content with a trigger |
+
+## Usage
+
+### Default (pill container)
+```tsx
+<AppTabs defaultValue="account">
+  <AppTabsList>
+    <AppTabsTrigger value="account">Account</AppTabsTrigger>
+    <AppTabsTrigger value="password">Password</AppTabsTrigger>
+  </AppTabsList>
+  <AppTabsContent value="account">Account settings content.</AppTabsContent>
+  <AppTabsContent value="password">Password settings content.</AppTabsContent>
+</AppTabs>
+```
+
+### Underline
+```tsx
+<AppTabs defaultValue="overview" variant="underline">
+  <AppTabsList>
+    <AppTabsTrigger value="overview">Overview</AppTabsTrigger>
+    <AppTabsTrigger value="analytics">Analytics</AppTabsTrigger>
+  </AppTabsList>
+  <AppTabsContent value="overview">Overview content.</AppTabsContent>
+  <AppTabsContent value="analytics">Analytics content.</AppTabsContent>
+</AppTabs>
+```
+
+### Pills
+```tsx
+<AppTabs defaultValue="all" variant="pills">
+  <AppTabsList>
+    <AppTabsTrigger value="all">All</AppTabsTrigger>
+    <AppTabsTrigger value="active">Active</AppTabsTrigger>
+    <AppTabsTrigger value="archived">Archived</AppTabsTrigger>
+  </AppTabsList>
+  <AppTabsContent value="all">All items.</AppTabsContent>
+  <AppTabsContent value="active">Active items.</AppTabsContent>
+  <AppTabsContent value="archived">Archived items.</AppTabsContent>
+</AppTabs>
+```
+
+## Rules
+- ✅ Always use `AppTabs` — never use a custom tab implementation
+- ✅ Set `variant` once on `AppTabs` — do not pass it to `AppTabsList` or `AppTabsTrigger` directly
+- ✅ Ensure `value` on `AppTabsTrigger` matches the `value` on the corresponding `AppTabsContent`
+- ✅ Use `defaultValue` for uncontrolled tabs
+- ❌ Do not use `AppTabs` for navigation between pages — use `AppNavigationMenu` or simple links instead
+- ❌ If a prop you need is missing, stop and inform the design team
+
+## Responsive
+
+`AppTabsList` scrolls horizontally on mobile via an `overflow-x-auto scrollbar-none` wrapper with `min-w-max` on the inner list, so tabs never wrap to a second line and remain fully swipeable. No consumer changes are needed.

package/rules/text.md

@@ -0,0 +1,3 @@
+# Renamed
+
+`AppText` has been renamed to `AppTypography`. See `typography.md`.

package/rules/textarea.md

@@ -0,0 +1,38 @@
+# AppTextarea
+
+> Docs: https://ui-kit.vercel.app/docs/components/textarea
+
+```tsx
+import { AppTextarea } from "@/components/primitives/AppTextarea"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placeholder` | `string` | — | Placeholder text |
+| `disabled` | `boolean` | `false` | Disables the textarea |
+| `className` | `string` | — | Additional Tailwind classes |
+
+> Accepts all standard HTML `<textarea>` attributes in addition to the props above.
+
+## Usage
+
+### Basic
+```tsx
+<AppTextarea placeholder="Type your message here..." />
+```
+
+### With Label
+```tsx
+<div className="grid w-full gap-1.5">
+  <AppLabel htmlFor="message">Your message</AppLabel>
+  <AppTextarea placeholder="Type your message here." id="message" />
+</div>
+```
+
+## Rules
+- ✅ Always use `AppTextarea` — never use a raw `<textarea>` element
+- ✅ Use `AppLabel` for accessibility
+- ✅ Control height via `rows` attribute or Tailwind `h-*` classes
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/toaster.md

@@ -0,0 +1,58 @@
+# AppToaster
+
+> Docs: https://ui-kit.vercel.app/docs/components/toaster
+
+```tsx
+import { AppToaster, toast } from "@/components/primitives/AppToaster"
+```
+
+## AppToaster
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| — | — | — | No primary props; configuration is handled internally |
+
+## toast (sonnerToast)
+
+| Method | Description |
+|--------|-------------|
+| `toast(message, options?)` | Show a default toast |
+| `toast.success(message, options?)` | Show a success toast |
+| `toast.error(message, options?)` | Show an error toast |
+| `toast.info(message, options?)` | Show an info toast |
+
+## Usage
+
+### Setup (Layout)
+```tsx
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <AppToaster />
+      </body>
+    </html>
+  )
+}
+```
+
+### Triggering toast
+```tsx
+<AppButton
+  onClick={() =>
+    toast.success("Event created", {
+      description: "Monday, January 3rd at 6:00pm",
+    })
+  }
+>
+  Show success
+</AppButton>
+```
+
+## Rules
+- ✅ Place `<AppToaster />` once in your root layout
+- ✅ Use `toast.success` or `toast.error` for feedback on user actions
+- ✅ Use the `description` option for additional context
+- ❌ Do not create multiple `AppToaster` instances
+- ❌ If a prop you need is missing, stop and inform the design team