@l3mpire/ui 3.2.1 → 3.5.0

package/USAGE.md

@@ -116,7 +116,7 @@ Works with all Tailwind spacing prefixes: `p-`, `px-`, `py-`, `m-`, `mx-`, `my-`
 
 **Line heights:** `leading-2xs` (14px), `leading-xs` (16px), `leading-sm` (20px), `leading-base` (24px), `leading-md` (28px), `leading-lg` (32px)
 
-**Font weights:** `font-regular` (400), `font-medium` (500), `font-semibold` (600), `font-bold` (700)
+**Font weights:** `font-regular` (400), `font-medium` (500), `font-semibold` (600), `font-solid` (700)
 
 ### Typography component
 
@@ -129,7 +129,8 @@ import { Typography } from "@l3mpire/ui";
 ```
 
 **Variants:** `h1`, `h2`, `h3`, `lg`, `md`, `sm`, `xs`
-**Weights:** `regular`, `medium`, `bold`
+**Weights:** `regular`, `medium`, `semibold`, `solid`
+Default weight by variant (from Figma text styles): `h1` → `semibold`, `h2`/`h3` → `medium`, body (`lg`/`md`/`sm`/`xs`) → `regular`. Override with the `weight` prop.
 
 ---
 
@@ -141,6 +142,57 @@ import { Typography } from "@l3mpire/ui";
 | `shadow-md` | Cards, dropdowns |
 | `shadow-lg` | Modals, popovers |
 | `shadow-focus-ring` | Focus state ring (3px blue) |
+| `shadow-elevation-sm` | Tight 1px AI cell / chip lift |
+| `shadow-elevation-md` | AI popover / floating panel |
+| `shadow-elevation-lg` | AI hero / standalone card |
+
+---
+
+## AI Utilities
+
+Animation primitives shared by AI cells, AI badges, suggestion dots and any
+surface that should look like it is thinking. The shimmer-text and
+icon-spin classes are the load-bearing ones; the rest are decorative.
+
+| Class | Usage |
+|---|---|
+| `bg-ai-gradient` | Brand AI gradient (blue → violet → indigo, 125deg) |
+| `ai-shimmer-text` | Text with a tertiary → info → tertiary sweep (2.1s) |
+| `ai-icon-spin` | Wrapper that rotates its child icon (see FA Kit caveat below) |
+| `ai-skeleton` | Surface skeleton with a horizontal sheen sweep |
+| `ai-cell-reveal` | One-shot blur(3px) → clear, 320ms fade-in for cells |
+| `ai-pulse` | Breathing scale + opacity for dot indicators |
+| `ai-gradient-text` | Flat info-blue accent for AI labels |
+| `ai-orb` | Decorative gradient disc with a soft glow |
+| `ai-halo` | Conic-gradient halo that rotates around an orb |
+| `ai-ring` | Pulsing concentric ring |
+| `animate-fade-up` | Generic entrance (8px translate + fade) |
+| `animate-pop-in` | Generic entrance (0.85 → 1 scale with overshoot) |
+
+All animations are disabled under `@media (prefers-reduced-motion: reduce)` —
+the shimmer text falls back to a flat info color so labels stay readable.
+
+### Spinning icons / FA Kit rule
+
+We load FontAwesome through the Kit script, which swaps every `<i class="fa-…">`
+into an `<svg>` via a MutationObserver. Any subsequent className change on the
+icon re-triggers the swap and **interrupts** any rotation animation applied
+directly to the icon. The symptom: an icon that ticks ~90° and resets in a loop.
+
+Always wrap the icon in a span that carries the rotation:
+
+```tsx
+// ❌ fa-spin on <Icon> is interrupted by the Kit re-swap
+<Icon icon={faSpinnerThirdOutline} className="fa-spin" />
+
+// ✅ rotation lives on a stable parent; the icon is left alone
+<span className="ai-icon-spin">
+  <Icon icon={faSpinnerThirdOutline} size="xs" />
+</span>
+```
+
+The same applies to any custom rotation animation — never put it on the icon
+className itself.
 
 ---
 
@@ -211,15 +263,17 @@ import { faStarOutline } from "@l3mpire/icons";
 <Badge variant="light" type="success" size="sm">Active</Badge>
 <Badge variant="outlined" type="critical" icon={faStarOutline}>99</Badge>
 
-// Categorical tone — overrides variant/type
+// Categorical tone — combines with variant (solid/light/outlined), overrides type
 <Badge tone="indigo">SaaS</Badge>
+<Badge variant="light" tone="amber">Manufacturing</Badge>
+<Badge variant="outlined" tone="emerald">Finance</Badge>
 ```
 
 | Prop | Values |
 |---|---|
 | `variant` | `"solid"`, `"light"`, `"outlined"` |
 | `type` | `"primary"`, `"success"`, `"critical"`, `"warning"`, `"neutral"` |
-| `tone` | `"indigo"`, `"rose"`, `"lime"`, `"violet"`, `"cyan"`, `"orange"`, `"emerald"`, `"fuchsia"`, `"amber"`, `"slate"` — categorical palette; overrides `variant`/`type` |
+| `tone` | `"indigo"`, `"rose"`, `"lime"`, `"violet"`, `"cyan"`, `"orange"`, `"emerald"`, `"fuchsia"`, `"amber"`, `"slate"`, `"teal"`, `"sky"`, `"purple"`, `"pink"` — categorical palette; combines with `variant`, overrides `type` |
 | `size` | `"sm"`, `"md"`, `"lg"` |
 | `icon` | `IconDefinition` (optional) |
 
@@ -243,7 +297,7 @@ import { faPaperPlaneOutline } from "@l3mpire/icons";
 | Prop | Values |
 |---|---|
 | `variant` | `"brand"`, `"neutral"` |
-| `tone` | `"indigo"`, `"rose"`, `"lime"`, `"violet"`, `"cyan"`, `"orange"`, `"emerald"`, `"fuchsia"`, `"amber"`, `"slate"` — categorical palette; overrides `variant` |
+| `tone` | `"indigo"`, `"rose"`, `"lime"`, `"violet"`, `"cyan"`, `"orange"`, `"emerald"`, `"fuchsia"`, `"amber"`, `"slate"`, `"teal"`, `"sky"`, `"purple"`, `"pink"` — categorical palette; overrides `variant` |
 | `size` | `"sm"`, `"md"` |
 | `icon` | `IconDefinition` |
 | `onClose` | `() => void` (shows remove button when provided) |
@@ -744,7 +798,7 @@ import { InfoMessage } from "@l3mpire/ui";
 
 | Prop | Values |
 |---|---|
-| `type` | `"info"`, `"success"`, `"alert"`, `"warning"`, `"empty"` |
+| `type` | `"info"`, `"success"`, `"alert"`, `"warning"`, `"empty"`, `"ai"` |
 | `title` | `React.ReactNode` (required) |
 | `description` | `React.ReactNode` |
 | `onClose` | `() => void` (shows close button when provided) |
@@ -902,6 +956,8 @@ import { faRocketOutline } from "@l3mpire/icons";
 
 Active tabs render with concave bottom corners that fuse into the bar divider (real browser-tab look). Inactive tabs get a hover fill + soft shadow on the inner pill (active tabs keep their bg on hover).
 
+The close `×` only appears **on hover** of a non-pinned tab, as an absolutely-positioned overlay with a gradient fade — it never takes layout space (the label slides under the gradient instead of being pushed). Set `pinned` to hide the close button entirely and show a **"Pinned tab"** tooltip on hover. Set `isEditable` (+ `onEdit`) to add a pencil button in the same overlay, to the left of the close `×`.
+
 | Prop (BrowserTab) | Values |
 |---|---|
 | `onAddTab` | `() => void` (shows + button) |
@@ -915,7 +971,10 @@ Active tabs render with concave bottom corners that fuse into the bar divider (r
 | `icon` | `IconDefinition` |
 | `badge` | `string` |
 | `isActive` | `boolean` |
-| `onClose` | `(e) => void` |
+| `pinned` | `boolean` (no close button, "Pinned tab" tooltip on hover) |
+| `isEditable` | `boolean` (pencil button in hover overlay, left of close) |
+| `onEdit` | `(e) => void` (edit-button click, used with `isEditable`) |
+| `onClose` | `(e) => void` (close `×` appears on hover only; ignored when `pinned`) |
 | `onRename` | `(newLabel: string) => void` (enables dbl-click rename) |
 
 ---
@@ -1357,7 +1416,7 @@ import { ProductLogo } from "@l3mpire/ui";
 
 ### BulkAction
 
-Bottom-anchored toolbar that appears when one or more list items are selected. The selection count sits on the **left**, a fully composable **responsive** actions slot in the middle, and a ghost-brand icon-only **close button on the right** (uses `clearLabel` as its `aria-label`). Actions that don't fit collapse automatically into a "more" menu.
+Bottom-anchored toolbar that appears when one or more list items are selected. The selection count sits on the **left**, a fully composable **responsive** actions slot in the middle, and a ghost-brand icon-only **close button on the right** (`clearLabel` shows as a hover tooltip + `aria-label`). Actions that don't fit collapse automatically into a "more" menu.
 
 ```tsx
 import { BulkAction, type BulkActionItem } from "@l3mpire/ui";
@@ -1383,9 +1442,10 @@ const actions: BulkActionItem[] = [
 | `count` | Number of selected items (rendered as `{count} {countLabel}`) |
 | `onClear` | Called when the user clicks the right-side close button |
 | `countLabel` | Defaults to `"selected"` — override for i18n |
-| `clearLabel` | Defaults to `"Clear"` — used as the close button's `aria-label` |
+| `clearLabel` | Defaults to `"Clear"` — shown as the close button's hover tooltip + `aria-label` |
 | `actions` | `BulkActionItem[]` — items collapse into a "more" menu when they overflow |
-| `sticky` | `true` (default) → `position: sticky; bottom: 0`. Set to `false` when placing it manually inside a flex column above a footer (e.g. inside a SidePanel) |
+| `position` | `"sticky"` (default), `"static"`, `"floating-top"` — `sticky` pins to the bottom of the scroll container; `static` flows inline; `floating-top` floats a centred pill above a `position: relative` parent (e.g. above a pagination footer) |
+| `sticky` | **Deprecated** — use `position`. `true` maps to `"sticky"`, `false` to `"static"`; ignored when `position` is set |
 
 **`BulkActionItem` shape:**
 
@@ -1472,6 +1532,8 @@ const columns: ColumnDef<Person>[] = [
 | `lockedColumnIds` | inferred | Column IDs the manage-table modal hides (defaults to `enableHiding: false` columns plus `select`) |
 | `tableSettingsTitle` | `"Manage table"` | Override the manage-table modal title |
 | `bordered` | `false` | Border-top on header (full-width layouts) |
+| `scrollContainer` | `"self"` | Set to `"parent"` to drop the internal `overflow-auto` wrapper. Required when sticky column pinning has to compose with a page-level scroll. |
+| `columnManagerSlot` | — | Slot mounted as a `<th>` at the right end of the header row. Use it to host a custom column manager (see `ColumnManagerPopover`). |
 | `emptyState` | — | `ReactNode` shown when `data` is empty |
 | `sorting` | — | Controlled sorting state |
 | `onSortingChange` | — | Controlled sorting callback |
@@ -1548,8 +1610,10 @@ import {
   EmailCell, LinkCell, ButtonCell, EditableCell, RowActions,
 } from "@l3mpire/ui";
 
+// Row cells are a fixed 40px tall; headers 32px; both with 12px horizontal padding.
 // In column definitions:
-{ cell: ({ row }) => <AvatarCell name={row.original.name} src={row.original.avatar} /> }
+// AvatarCell: shape="rounded" (default, people) | "squared" (companies)
+{ cell: ({ row }) => <AvatarCell name={row.original.name} src={row.original.avatar} shape="squared" /> }
 { cell: ({ row }) => <StatusCell status="active" /> }
 { cell: ({ row }) => <NumberCell value={row.original.amount} /> }
 { cell: ({ row }) => <DateCell value={row.original.date} /> }
@@ -1560,6 +1624,406 @@ import {
 
 ---
 
+### EntityCell
+
+```tsx
+import { EntityCell, Avatar } from "@l3mpire/ui";
+import { faArrowUpRightFromSquareOutline } from "@l3mpire/icons";
+
+<EntityCell avatar={<Avatar size="sm" initials="AC" />} name="Acme Corp" subtitle="acme.com" />
+<EntityCell
+  avatar={<Avatar size="sm" src={logo} />}
+  name="Acme Corp"
+  onNameClick={() => openRecord(id)}
+  hoverCard={<CompanyPreview id={id} />}
+  quickActions={[{ icon: faArrowUpRightFromSquareOutline, label: "Open", onClick: () => {} }]}
+/>
+```
+
+| Prop | Values |
+|---|---|
+| `avatar` | `React.ReactNode` (required) — pass an `<Avatar />` or any logo/icon |
+| `name` | `string` (required) |
+| `subtitle` | `string` — optional second line |
+| `badge` | `React.ReactNode` — marker after the name (sync/status indicator) |
+| `hoverCard` | `React.ReactNode` — opens in a `<HoverCard />` when the name is hovered |
+| `quickActions` | `RowQuickAction[]` — hover-revealed actions on the right edge |
+| `onNameClick` | `(e) => void` — makes the name a clickable link; stops propagation |
+
+---
+
+### HoverCard
+
+```tsx
+import { HoverCard, HoverCardTrigger, HoverCardContent } from "@l3mpire/ui";
+
+<HoverCard openDelay={350} closeDelay={120}>
+  <HoverCardTrigger asChild><span>Acme Corp</span></HoverCardTrigger>
+  <HoverCardContent side="bottom" align="start">
+    <CompanyPreview id={id} />
+  </HoverCardContent>
+</HoverCard>
+```
+
+Compound component (`HoverCard` / `HoverCardTrigger` / `HoverCardContent`). Hover-intent popover with open/close delays; stays open while the pointer is over the content.
+
+| Prop (HoverCard) | Values |
+|---|---|
+| `openDelay` | `number` ms before opening (default `350`) |
+| `closeDelay` | `number` ms before closing (default `120`) |
+| `open` / `onOpenChange` | controlled open state |
+
+| Prop (HoverCardTrigger) | Values |
+|---|---|
+| `asChild` | `boolean` — merge props onto the child |
+
+`HoverCardContent` accepts Radix Popover Content props (`side`, `align`, `sideOffset` — defaults `"bottom"` / `"start"` / `8`).
+
+---
+
+### RowQuickActions
+
+```tsx
+import { RowQuickActions } from "@l3mpire/ui";
+import { faPenOutline, faTrashOutline } from "@l3mpire/icons";
+
+<RowQuickActions
+  group="co"
+  actions={[
+    { icon: faPenOutline, label: "Edit", onClick: () => {} },
+    { icon: faTrashOutline, label: "Delete", onClick: () => {} },
+  ]}
+/>
+```
+
+A row of icon-only buttons that fade in on parent-row hover. Each button stops propagation and carries a tooltip from its `label`.
+
+| Prop | Values |
+|---|---|
+| `actions` | `RowQuickAction[]` (required) — `{ icon, label, onClick, href? }` |
+| `group` | `string` — named hover group to listen to (e.g. `"co"`); defaults to the unnamed `group` |
+| `size` | `"sm"` (default), `"md"` |
+
+---
+
+### StatusPickerCell
+
+```tsx
+import { StatusPickerCell, type StatusOption } from "@l3mpire/ui";
+
+const options: StatusOption[] = [
+  { id: "new", label: "New", tone: "sky" },
+  { id: "won", label: "Won", type: "success" },
+];
+
+<StatusPickerCell
+  current={options[0]}
+  options={options}
+  onChange={(id) => setStatus(id)}
+  onAddOption={(label) => addStatus(label)}
+  onSync={() => syncCrm()}
+/>
+```
+
+Badge-pill cell that opens a popover to pick, rename, add, or CRM-sync a status. Each `StatusOption` carries optional `variant` / `type` / `tone` to style its `<Badge />`.
+
+| Prop | Values |
+|---|---|
+| `current` | `StatusOption \| null` (required) |
+| `options` | `StatusOption[]` (required) |
+| `onChange` | `(id: string) => void` (required) |
+| `onAddOption` | `(label: string) => void` — adds an "Add status" row |
+| `onRenameOption` | `(id, label) => void` — adds per-row rename on hover |
+| `onSync` | `() => void` — adds a "Sync with CRM" row |
+| `triggerStyle` | `"cell"` (default), `"compact"` |
+| `placeholder` | `string` (default `"Set status"`) |
+
+---
+
+### ScoreBadge
+
+```tsx
+import { ScoreBadge } from "@l3mpire/ui";
+
+<ScoreBadge score={3} matched={2} total={5} />
+<ScoreBadge score={-1} matched={1} total={4} size="md" />
+```
+
+Renders a score-rule result: a colored Badge (positive → success, negative → critical, zero → neutral) plus a `matched/total` counter.
+
+| Prop | Values |
+|---|---|
+| `score` | `number` (required) — signed total |
+| `matched` | `number` (required) |
+| `total` | `number` (required) |
+| `size` | Badge size — `"sm"` (default), `"md"`, `"lg"` |
+
+---
+
+### ColumnTypeBadge
+
+```tsx
+import { ColumnTypeBadge } from "@l3mpire/ui";
+
+<ColumnTypeBadge kind="db" />
+<ColumnTypeBadge kind="field" />
+<ColumnTypeBadge kind="score" />
+<ColumnTypeBadge kind="ai" />
+```
+
+Small Badge labelling a column's kind: `DB` (neutral), `FIELD` (warning), `SCORE` (success), `AI` (primary).
+
+| Prop | Values |
+|---|---|
+| `kind` | `"db"`, `"field"`, `"score"`, `"ai"` (required) |
+| `size` | Badge size — `"sm"` (default), `"md"`, `"lg"` |
+
+---
+
+### ColumnHeaderMenu
+
+```tsx
+import { ColumnHeaderMenu } from "@l3mpire/ui";
+
+<ColumnHeaderMenu
+  column={column}
+  title="Company"
+  editable={!isBuiltIn}
+  onRename={(name) => renameColumn(name)}
+  onEdit={() => openEditor()}
+  onDuplicate={() => duplicate()}
+  onDelete={() => remove()}
+>
+  <span>Company</span>
+</ColumnHeaderMenu>
+```
+
+Dropdown attached to a column header: inline rename, sort, pin, hide, and (for editable columns) duplicate / edit / delete. Built-in columns grey the mutation items and surface `builtinReason` as a tooltip.
+
+| Prop | Values |
+|---|---|
+| `column` | `HeaderColumnApi` (required) — TanStack-compatible subset (sort/pin/hide methods) |
+| `title` | `string` (required) |
+| `editable` | `boolean` (required) — false greys rename/duplicate/edit/delete |
+| `onRename` | `(name: string) => void` |
+| `onEdit` / `onDuplicate` / `onDelete` | `() => void` |
+| `builtinReason` | `string` — tooltip on greyed items (default `"Built-in columns can't be edited"`) |
+| `children` | `React.ReactNode` (required) — header content inside the trigger |
+
+---
+
+### ColumnManagerPopover
+
+```tsx
+import {
+  ColumnManagerPopover,
+  ColumnManagerTrigger,
+  type ColumnManagerItem,
+} from "@l3mpire/ui";
+
+const items: ColumnManagerItem[] = [
+  { id: "name", name: "Company", kind: "db", visible: true },
+  { id: "score", name: "Fit score", kind: "score", visible: true },
+];
+
+<ColumnManagerPopover
+  items={items}
+  trigger={<ColumnManagerTrigger />}
+  onToggleVisible={(id, visible) => setVisible(id, visible)}
+  onDelete={(id) => remove(id)}
+  onAdd={(kind) => createColumn(kind)}
+/>
+```
+
+Popover to search, show/hide, delete, and add columns. When `onAdd` is set it renders three "Add column" cards: Field, Score, AI.
+
+| Prop | Values |
+|---|---|
+| `items` | `ColumnManagerItem[]` (required) — `{ id, name, kind, visible, icon? }` |
+| `onToggleVisible` | `(id, visible) => void` (required) |
+| `onDelete` | `(id) => void` — only offered for `kind !== "db"` |
+| `onAdd` | `(kind: AddColumnKind) => void` — `AddColumnKind` is `"field" \| "score" \| "ai"` |
+| `trigger` | `React.ReactNode` — e.g. `<ColumnManagerTrigger />` |
+| `open` / `onOpenChange` | controlled open state |
+
+---
+
+### CreateFieldColumnPanel
+
+```tsx
+import { CreateFieldColumnPanel } from "@l3mpire/ui";
+
+<CreateFieldColumnPanel
+  open={open}
+  onOpenChange={setOpen}
+  onSave={(column) => addFieldColumn(column)}
+/>
+```
+
+Side panel to create or edit a user-defined Field column (text / number / date / single select). For `select`, options are entered one per line.
+
+| Prop | Values |
+|---|---|
+| `onSave` | `(column: Omit<FieldColumn, "id" \| "createdAt" \| "kind">) => void` (required) |
+| `open` / `onOpenChange` | controlled open state |
+| `initial` | `Partial<Pick<FieldColumn, "name" \| "fieldType" \| "options">>` |
+| `trigger` | `React.ReactNode` — opens the panel in uncontrolled mode |
+| `title` | `string` (default `"Create field column"`) |
+| `saveLabel` | `string` (default `"Create column"`) |
+
+---
+
+### CreateScoreColumnPanel
+
+```tsx
+import {
+  CreateScoreColumnPanel,
+  type ScorableField,
+  type ScorePreviewRow,
+} from "@l3mpire/ui";
+
+<CreateScoreColumnPanel
+  open={open}
+  onOpenChange={setOpen}
+  fields={scorableFields}
+  preview={firstFiveRows}
+  onSave={(column) => addScoreColumn(column)}
+/>
+```
+
+Side panel to build a weighted Score column: add rules (field + operator + value + weight) and see a live preview of the first rows scored via `computeScore`.
+
+| Prop | Values |
+|---|---|
+| `fields` | `ScorableField[]` (required) — `{ id, name, fieldType, options? }` |
+| `onSave` | `(column: Pick<ScoreColumn, "name" \| "rules">) => void` (required) |
+| `preview` | `ScorePreviewRow[]` — rows to score in the preview |
+| `open` / `onOpenChange` | controlled open state |
+| `initial` | `Partial<Pick<ScoreColumn, "name" \| "rules">>` |
+| `trigger` | `React.ReactNode` |
+| `title` | `string` (default `"Score column"`) |
+| `saveLabel` | `string` (default `"Save"`) |
+
+---
+
+### AIBadge
+
+```tsx
+import { AIBadge } from "@l3mpire/ui";
+
+<AIBadge />
+<AIBadge size="md">Enriched</AIBadge>
+<AIBadge iconHidden>AI</AIBadge>
+```
+
+Marker flagging a value or column as AI-driven. Renders a `<Badge variant="light" type="primary" />` with a leading stars glyph. Children default to `"AI"`.
+
+| Prop | Values |
+|---|---|
+| `iconHidden` | `boolean` — hide the leading stars icon |
+| `size` | Badge size — `"lg"` (default), `"sm"`, `"md"` |
+| `children` | `React.ReactNode` (default `"AI"`) |
+
+---
+
+### AICell
+
+```tsx
+import { AICell, type AICellState } from "@l3mpire/ui";
+
+const state: AICellState = { status: "done", value: "B2B SaaS", citations: ["crunchbase"] };
+
+<AICell state={state} seed={row.id} />
+<AICell state={{ status: "running" }} seed={row.id} />
+<AICell state={{ status: "error", message: "Rate limited" }} />
+```
+
+Renders the four states of an AI-generated cell in one stable shell: `pending` (Queued), `running` (shimmer + spinning verb), `done` (value + optional citation count, tooltip), `error` (red message).
+
+| Prop | Values |
+|---|---|
+| `state` | `AICellState \| undefined` — `{ status: "pending" }` \| `{ status: "running" }` \| `{ status: "done"; value; citations? }` \| `{ status: "error"; message }` |
+| `seed` | `string` — stable per-cell seed so the running verb is consistent across re-renders |
+
+Helpers: `AI_RUNNING_VERBS` (verb pool) and `pickRunningVerb(seed)` (stable verb pick).
+
+---
+
+### AISuggestionDot
+
+```tsx
+import { AISuggestionDot } from "@l3mpire/ui";
+
+<AISuggestionDot
+  reason="LinkedIn lists a newer title."
+  from="VP Sales"
+  to="Chief Revenue Officer"
+  onApply={() => apply()}
+  onDismiss={() => dismiss()}
+/>
+```
+
+A pulsing dot anchored next to a cell value. Clicking it opens a popover showing the AI's `from → to` suggestion with Apply / Dismiss actions.
+
+| Prop | Values |
+|---|---|
+| `to` | `React.ReactNode` (required) — suggested value |
+| `onApply` | `() => void` (required) |
+| `onDismiss` | `() => void` (required) |
+| `from` | `React.ReactNode` — current value (left of the arrow) |
+| `reason` | `string` — short explanation in the popover |
+| `side` | `"top"`, `"right"`, `"bottom"` (default), `"left"` |
+| `title` / `applyLabel` / `dismissLabel` | localized labels (defaults `"Suggested change"` / `"Apply"` / `"Dismiss"`) |
+
+---
+
+### AIColumnHeaderBar
+
+```tsx
+import { AIColumnHeaderBar } from "@l3mpire/ui";
+
+<AIColumnHeaderBar label="Tech stack" onRun={() => runOnAllRows()} />
+```
+
+Header bar for an AI column. The Play ("run on all rows") button appears only on header hover.
+
+| Prop | Values |
+|---|---|
+| `label` | `string` (required) |
+| `onRun` | `() => void` — shows the hover-revealed Play button |
+| `runLabel` | `string` — tooltip/aria-label (default `"Run on all rows"`) |
+
+---
+
+### AIColumnSidePanel
+
+```tsx
+import { AIColumnSidePanel, type AIColumnConfig } from "@l3mpire/ui";
+
+<AIColumnSidePanel
+  open={open}
+  onOpenChange={setOpen}
+  onSave={(config) => createAIColumn(config)}
+  extrasSlot={(extras, setExtras) => <ModelPicker value={extras} onChange={setExtras} />}
+/>
+```
+
+Side panel scaffold to create or edit an AI column: name, prompt, and output format. Product-specific controls (model, sources, timeframe) plug in via `extrasSlot`.
+
+| Prop | Values |
+|---|---|
+| `onSave` | `(config: AIColumnConfig) => void` (required) — `{ name, prompt, outputFormat, extras? }` |
+| `open` / `onOpenChange` | controlled open state |
+| `initialConfig` | `Partial<AIColumnConfig>` |
+| `extrasSlot` | `(extras, setExtras) => React.ReactNode` — render slot for extra controls |
+| `trigger` | `React.ReactNode` — uncontrolled open |
+| `title` | `string` (default `"AI column"`) |
+| `saveLabel` | `string` (default `"Save"`) |
+
+`AIColumnOutputFormat`: `"text" \| "number" \| "boolean" \| "select" \| "date"`.
+
+---
+
 ### EmptyState
 
 ```tsx