@l3mpire/ui 3.5.1 → 4.0.0

package/USAGE.md

@@ -156,13 +156,15 @@ icon-spin classes are the load-bearing ones; the rest are decorative.
 
 | Class | Usage |
 |---|---|
-| `bg-ai-gradient` | Brand AI gradient (blue → violet → indigo, 125deg) |
+| `bg-ai-gradient` | Decorative brand AI gradient (blue → violet → indigo, 125deg) |
+| `bg-ai-subtle` / `-hover` / `-pressed` | Translucent AI wash (ghost AI surfaces) |
+| `bg-ai-strong` / `-hover` / `-pressed` | Vivid AI gradient (solid AI fill) |
+| `ai-grad-text` | Gradient-clipped text/icons (outlined/ghost AI); follows `[data-ai-text]` host hover/pressed |
 | `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 |
@@ -236,12 +238,19 @@ import { faPaperPlaneOutline } from "@l3mpire/icons";
 <Button appearance="solid" intent="brand" size="md" badge={99}>
   Notifications
 </Button>
+
+{/* AI intent — brand→violet gradient. Solid = vivid fill + white label;
+    outlined/ghost = gradient-clipped label & icons. No disabled-specific
+    art (falls back to the appearance's disabled style). */}
+<Button appearance="solid" intent="ai" leftIcon={faStarsOutline}>Ask AI</Button>
+<Button appearance="outlined" intent="ai" leftIcon={faStarsOutline}>Ask AI</Button>
+<Button appearance="ghost" intent="ai" leftIcon={faStarsOutline}>Ask AI</Button>
 ```
 
 | Prop | Values |
 |---|---|
 | `appearance` | `"solid"`, `"outlined"`, `"ghost"` |
-| `intent` | `"brand"`, `"alert"` |
+| `intent` | `"brand"`, `"alert"`, `"ai"` |
 | `size` | `"sm"` (24px), `"md"` (32px, radius 10px), `"lg"` (40px, radius 12px) |
 | `leftIcon` | `IconDefinition` |
 | `rightIcon` | `IconDefinition` |
@@ -267,13 +276,18 @@ import { faStarOutline } from "@l3mpire/icons";
 <Badge tone="indigo">SaaS</Badge>
 <Badge variant="light" tone="amber">Manufacturing</Badge>
 <Badge variant="outlined" tone="emerald">Finance</Badge>
+
+// AI tone — gradient surface (solid = vivid fill + white; light/outlined = gradient-clipped content).
+// Pure variant: pass your own icon + label.
+<Badge tone="ai" icon={faStarsOutline}>AI</Badge>
+<Badge variant="light" tone="ai" icon={faStarsOutline}>Enriched</Badge>
 ```
 
 | Prop | Values |
 |---|---|
 | `variant` | `"solid"`, `"light"`, `"outlined"` |
 | `type` | `"primary"`, `"success"`, `"critical"`, `"warning"`, `"neutral"` |
-| `tone` | `"indigo"`, `"rose"`, `"lime"`, `"violet"`, `"cyan"`, `"orange"`, `"emerald"`, `"fuchsia"`, `"amber"`, `"slate"`, `"teal"`, `"sky"`, `"purple"`, `"pink"` — categorical palette; combines with `variant`, overrides `type` |
+| `tone` | `"indigo"`, `"rose"`, `"lime"`, `"violet"`, `"cyan"`, `"orange"`, `"emerald"`, `"fuchsia"`, `"amber"`, `"slate"`, `"teal"`, `"sky"`, `"purple"`, `"pink"`, `"ai"` — categorical/AI palette; combines with `variant`, overrides `type`. `"ai"` uses the shared AI gradient surfaces. |
 | `size` | `"sm"`, `"md"`, `"lg"` |
 | `icon` | `IconDefinition` (optional) |
 
@@ -1130,6 +1144,56 @@ import {
 
 ---
 
+### Discreet (inline fields)
+
+The "discreet" inline-edit pattern: a value reads as plain text at rest, a content-hugging pill +
+affordance reveal it's editable on hover, and a right-sized overlay opens **in place with zero
+layout shift** on click. Built on the composable `InlineEdit` engine; each `Discreet*` wrapper
+**reuses the matching existing component** as its editor (existing components are untouched).
+
+```tsx
+import {
+  DiscreetTextInput, DiscreetLink, DiscreetNumberInput, DiscreetTextarea,
+  DiscreetChipInput, DiscreetSelect, DiscreetOwner, DiscreetTags,
+  DiscreetDate, DiscreetSwitch, InlineEdit,
+} from "@l3mpire/ui";
+
+// Controlled: pass `value`, commit in `onCommit` (return a Promise → saving spinner).
+<DiscreetTextInput label="Job title" value={title} onCommit={setTitle} />
+<DiscreetSelect label="Status" options={statusOptions} value={status} onCommit={setStatus} />
+<DiscreetDate label="Follow-up" value={iso} onCommit={setIso} />
+
+// Build a discreet field for any control with the engine directly:
+<InlineEdit
+  label="Custom"
+  display={<span>{value}</span>}
+  editView={({ commit, cancel }) => <MyEditor onDone={(v) => { save(v); commit(); }} />}
+/>
+```
+
+Shared axis props (all `Discreet*`): `label`, `labelType` (`default`/`optional`/`mandatory`/
+`info`, via `InputLabel`), `labelLayout` (`inline` \| `stacked` \| `none`), `reveal` (`subtle` \|
+`pen` \| `outline`), `edit` (`inplace` \| `bordered`), `size` (`sm` = 32px default \| `md` =
+40px), `placeholder`, `readOnly`, `error`, `errorMessage`. Each also takes `value` + `onCommit`.
+
+| Component | Value type | Editor (reused) |
+|---|---|---|
+| `DiscreetTextInput` | `string` (`type`: text/tel) | borderless input |
+| `DiscreetLink` | `string` (URL) | input; value stays clickable |
+| `DiscreetNumberInput` | `number \| ""` | borderless numeric input (`prefix`) |
+| `DiscreetTextarea` | `string` | borderless textarea (⌘+Enter saves) |
+| `DiscreetChipInput` | `string[]` | chip input + inline `validate` |
+| `DiscreetSelect` | `string` (`options`) | `DropdownMenu` + colour dot |
+| `DiscreetOwner` | `string` (`options`) | `DropdownMenu` + `Avatar` |
+| `DiscreetTags` | `string[]` (`options`) | `DropdownMenu` + `Checkbox` (multi) |
+| `DiscreetDate` | ISO `YYYY-MM-DD` | `DatePicker` calendar |
+| `DiscreetSwitch` | `boolean` | `Switch` — commits on click |
+
+Tokens: `comp.inlineField.*` (pill, value, overlay, menu, affordance, accent, error) →
+`--color-inline-field-*`.
+
+---
+
 ### FilterSystem
 
 Composable filter system with inline chips, sort, property selector, and advanced filter popover.
@@ -1557,11 +1621,24 @@ const columns: ColumnDef<Item>[] = [
       enableDrag: true,           // Draggable (requires enableColumnDrag)
       filterType: "string",       // Filter popover type: "string" | "number" | "date" | "select"
       filterOptions: ["A", "B"], // Options for "select" filter type
+      onRunColumn: () => runAi(), // AI columns: reveals a hover "run on all rows" Play button
+      runColumnLabel: "Run on all rows", // tooltip/aria-label for that button
     },
   },
 ];
 ```
 
+For an AI column, pair `meta.onRunColumn` (the header run button) with an `AICell` renderer and a `<Badge tone="ai">` header marker:
+
+```tsx
+{
+  id: "summary",
+  header: () => <span className="inline-flex items-center gap-xs">Summary <Badge tone="ai" size="sm" icon={faStarsOutline}>AI</Badge></span>,
+  cell: ({ row }) => <AICell state={row.original.aiState} seed={row.id} />,
+  meta: { onRunColumn: () => runAi() },
+}
+```
+
 #### Manage Table (Column Visibility Modal)
 
 Set `enableTableSettings` to render a sticky-right "Manage table" button in the header row. The button is hidden by default and reveals on header-row hover. Clicking it opens a modal with a search input and a checkbox per column. Locked columns (those with `enableHiding: false`, plus any column with id `select`) are filtered out.
@@ -1607,7 +1684,7 @@ Pre-built cell components for common patterns:
 ```tsx
 import {
   AvatarCell, StatusCell, NumberCell, DateCell,
-  EmailCell, LinkCell, ButtonCell, EditableCell, RowActions,
+  EmailCell, LinkCell, ButtonCell, EditableCell, RowActions, AICell,
 } from "@l3mpire/ui";
 
 // Row cells are a fixed 40px tall; headers 32px; both with 12px horizontal padding.
@@ -1622,6 +1699,16 @@ import {
 { cell: ({ row }) => <RowActions actions={[{ label: "Edit", onClick: () => {} }]} /> }
 ```
 
+`AICell` renders an asynchronous AI result through one stable shell across four states — `{ status: "pending" }`, `{ status: "running" }`, `{ status: "done"; value; citations? }`, `{ status: "error"; message }`. Pass a stable `seed` so the running verb stays consistent across re-renders. Helpers `AI_RUNNING_VERBS` / `pickRunningVerb(seed)` back the running label.
+
+```tsx
+import { AICell, type AICellState } from "@l3mpire/ui";
+
+<AICell state={{ status: "running" }} seed={row.id} />
+<AICell state={{ status: "done", value: "B2B SaaS", citations: ["crunchbase"] }} seed={row.id} />
+<AICell state={{ status: "error", message: "Rate limited" }} />
+```
+
 ---
 
 ### EntityCell
@@ -1906,124 +1993,6 @@ Side panel to build a weighted Score column: add rules (field + operator + value
 
 ---
 
-### 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