hs-uix 2.1.0 → 2.2.0

package/src/form/README.md

@@ -555,18 +555,61 @@ For centralized alert config:
 />
 ```
 
-## Dirty Tracking
+## Dirty Tracking & Unsaved-Changes Guard
+
+FormBuilder deep-compares current values against the initial snapshot (the
+resolved `initialValues` / first controlled `values`). `onDirtyChange` fires on
+transitions only — once when the form becomes dirty, once when it goes clean
+again (reset, submit-reset, or values edited back to their originals).
 
 ```jsx
 <FormBuilder
   fields={fields}
   onSubmit={save}
   onDirtyChange={(isDirty) => {
-    // e.g., show unsaved changes warning
+    // e.g., flip a "you have unsaved changes" banner outside the form
   }}
 />
 ```
 
+The ref exposes the same state imperatively: `formRef.current.isDirty()` and
+`formRef.current.getDirtyFields()` (names of changed fields).
+
+### Confirm Before Discarding (`confirmDiscard`)
+
+When `confirmDiscard` is set, the built-in Cancel button stops firing
+`onCancel` directly while the form is dirty. Instead it opens a native Modal
+confirmation — "Keep editing" closes the modal, the destructive confirm
+closes it and then calls `onCancel`. A clean form cancels immediately, no
+modal.
+
+```jsx
+<FormBuilder
+  fields={fields}
+  onSubmit={save}
+  showCancel={true}
+  onCancel={() => actions.closeOverlay("edit-panel")}
+  confirmDiscard={true} // or customize:
+  // confirmDiscard={{
+  //   title: "Discard this deal?",
+  //   message: "Your edits to this deal will be lost.",
+  //   confirmLabel: "Discard edits",
+  //   cancelLabel: "Keep editing",
+  // }}
+/>
+```
+
+The confirmation modal closes itself via `actions.closeOverlay` (FormBuilder
+calls `useExtensionActions` internally — nothing to thread in).
+
+**Host-close caveat.** UI extensions cannot intercept the host panel/modal
+close — the X button, ESC, and outside clicks discard silently and there is no
+`beforeunload` equivalent. `confirmDiscard` only guards FormBuilder's own
+Cancel button (and the imperative `ref.reset()` is intentionally unguarded —
+it's your code calling it). For everything else, `onDirtyChange` is your hook:
+track dirty state in the parent and surface your own warning UI (a banner, a
+disabled close affordance, an alert on reopen).
+
 ## Custom Render Escape Hatch
 
 For fields that need custom rendering:
@@ -1059,6 +1102,89 @@ const initialValues = useFormPrefill(properties, {
 <FormBuilder fields={fields} initialValues={initialValues} onSubmit={save} />
 ```
 
+## Fields from HubSpot Properties
+
+`fieldsFromHubSpotProperties` turns HubSpot property definitions (the objects
+returned by `GET /crm/v3/properties/{objectType}`) into FormBuilder field
+configs, so a CRM edit form is one fetch + one function call instead of a
+hand-maintained field list that drifts from the portal.
+
+```jsx
+import { FormBuilder, fieldsFromHubSpotProperties } from "hs-uix/form";
+
+// properties = the `results` array from the properties API (via hubspot.fetch
+// or a serverless function)
+const fields = fieldsFromHubSpotProperties(properties, {
+  include: ["dealname", "dealstage", "amount", "closedate"], // also sets order
+  requiredOverrides: ["dealname", "dealstage"],
+  overrides: {
+    amount: { min: 0, description: "USD" },
+  },
+});
+
+<FormBuilder fields={fields} onSubmit={save} />
+```
+
+Type mapping (HubSpot `fieldType` first, storage `type` as tie-breaker):
+
+| HubSpot | FormBuilder field type |
+|---|---|
+| `select` (enumeration) | `select` — options from property options, `hidden: true` options filtered |
+| `radio` | `radioGroup` |
+| `checkbox` (multi-enum) | `multiselect` |
+| `booleancheckbox` | `toggle` — with `transformIn`/`transformOut` normalizing HubSpot's `"true"`/`"false"` strings |
+| `date` (type `date`) | `date` |
+| `date` (type `datetime`) | `datetime` |
+| `number` | `number` — with `transformIn` parsing HubSpot's numeric strings |
+| `textarea` | `textarea` |
+| `text` / `phonenumber` | `text` |
+| anything else | falls back on storage type (`enumeration` → `select`, `bool` → `toggle`, `number` → `number`, else `text`) |
+
+Options:
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `include` | `string[]` | - | Property names to keep. Also sets the output field order. |
+| `exclude` | `string[]` | - | Property names to drop. |
+| `overrides` | `Record<string, Partial<Field>>` | - | Partial field configs merged over the generated config per property. |
+| `requiredOverrides` | `string[] \| Record<string, boolean>` | - | Mark properties required (property definitions don't carry required-ness — that's per-form in HubSpot). |
+| `includeDescriptions` | `boolean` | `false` | Copy property descriptions into field `description` help text (off by default — portal descriptions are often internal notes). |
+
+Hard-earned defaults: `hidden: true` properties are skipped unless explicitly
+listed in `include`; `calculated` and `modificationMetadata.readOnlyValue`
+properties come back `readOnly: true` (an editable input for a value HubSpot
+will refuse to save is a silent-fail trap). Date/datetime **values** are not
+transformed — epoch-ms ↔ `{ year, month, date }` conversion is timezone
+sensitive, so wire `transformIn`/`transformOut` yourself (see `dateToTimestamp`
+in `hs-uix/utils`).
+
+## Field-Level Loading
+
+Set `loading: true` on a field while its options (or any backing data) are
+still in flight: the input is disabled, and `select` / `multiselect` fields
+render an inline `LoadingSpinner` (`size="xs"`) beside the control so the
+empty dropdown reads as "still fetching" rather than broken.
+
+```jsx
+const { options, loading } = useCrmSearchOptions({ objectType: "companies", query });
+
+const fields = [
+  { name: "company", type: "select", label: "Company", options, loading },
+];
+```
+
+The CRM search adapters in `hs-uix/utils` set exactly this key, so the two
+compose with zero glue:
+
+```jsx
+import { useCrmSearchOptions, makeCrmSearchSelectField } from "hs-uix/utils";
+
+const search = useCrmSearchOptions({ objectType: "companies" });
+const fields = [
+  makeCrmSearchSelectField({ name: "company", label: "Company" }, search),
+];
+```
+
 ## Auto-Save
 
 Debounced auto-save on field changes:
@@ -1121,6 +1247,7 @@ try {
 | `submitVariant` | `"primary" \| "secondary"` | `"primary"` | Button variant |
 | `showCancel` | `boolean` | `false` | Show cancel button |
 | `onCancel` | `() => void` | - | Cancel callback |
+| `confirmDiscard` | `boolean \| { title?, message?, confirmLabel?, cancelLabel? }` | - | When set, the built-in Cancel button opens a native Modal confirmation before discarding dirty changes. Cannot intercept the host panel/modal close — use `onDirtyChange` for that |
 | `submitPosition` | `"bottom" \| "none"` | `"bottom"` | Button placement |
 | `submitAlign` | `"start" \| "end" \| "between"` | auto | Default single-step button-row alignment. Defaults to `"between"` when `showCancel` is true, otherwise `"start"` |
 | `loading` | `boolean` | - | Controlled loading state |
@@ -1156,7 +1283,7 @@ try {
 | `onSubmitError` | `(error, helpers) => void` | - | Post-submit error |
 | `resetOnSuccess` | `boolean` | `false` | Auto-reset after success |
 | `autoSave` | `{ debounce?, onAutoSave }` | - | Debounced auto-save |
-| `onDirtyChange` | `(isDirty) => void` | - | Dirty state callback |
+| `onDirtyChange` | `(isDirty) => void` | - | Dirty state callback (fires on transitions only) |
 | `ref` | `Ref<FormBuilderRef>` | - | Imperative ref |
 
 ### Field Props
@@ -1183,7 +1310,7 @@ try {
 | `useDefaultValidators` | `boolean` | All | Enable/disable built-in type/shape validation (default `true`) |
 | `validateDebounce` | `number` | All | Debounce async validation (ms) |
 | `debounce` | `number` | All | Debounce onChange callback (ms) |
-| `loading` | `boolean` | All | Field-level loading indicator |
+| `loading` | `boolean` | All | Field-level loading: disables the input; select/multiselect also render an inline `LoadingSpinner` (set automatically by `makeCrmSearchSelectField` / `makeCrmSearchMultiSelectField`) |
 | `group` | `string` | All | Divider-based field grouping |
 | `onFieldChange` | `(value, allValues, helpers) => void` | All | Cross-field side effects |
 | `transformIn` | `(rawValue) => displayValue` | All | Storage → display transform (on load) |
@@ -1233,6 +1360,7 @@ try {
 | `reset()` | `void` | Reset to initial values |
 | `getValues()` | `Record<string, unknown>` | Current form values |
 | `isDirty()` | `boolean` | Whether values differ from initial |
+| `getDirtyFields()` | `string[]` | Names of fields whose value differs from initial |
 | `setFieldValue(name, value)` | `void` | Set a field value programmatically |
 | `setFieldError(name, message)` | `void` | Set a field error programmatically |
 | `setErrors(errors)` | `void` | Batch set field errors (server-side validation) |

package/src/form/index.d.ts

@@ -106,6 +106,17 @@ export interface FormBuilderAlertConfig {
   successTitle?: string;
 }
 
+export interface FormBuilderConfirmDiscardConfig {
+  /** Modal title. Default "Discard changes?". */
+  title?: string;
+  /** Modal body text. Default "You have unsaved changes. If you discard now, they will be lost.". */
+  message?: string;
+  /** Destructive confirm button label. Default "Discard changes". */
+  confirmLabel?: string;
+  /** Keep-editing button label. Default "Keep editing". */
+  cancelLabel?: string;
+}
+
 export interface FormBuilderButtonsRenderContext {
   isMultiStep: boolean;
   isFirstStep: boolean;
@@ -114,6 +125,8 @@ export interface FormBuilderButtonsRenderContext {
   totalSteps: number;
   disabled: boolean;
   loading: boolean;
+  /** True when current values deep-differ from the initial snapshot. */
+  isDirty: boolean;
   labels: Required<Pick<FormBuilderLabels, "submit" | "cancel" | "back" | "next">>;
   onBack: () => void;
   onNext: () => void;
@@ -164,7 +177,12 @@ export interface FormBuilderField {
   minValidationMessage?: string;
   maxValidationMessage?: string;
 
-  // Field-level loading indicator
+  /**
+   * Field-level loading indicator. While true the input is disabled and
+   * select/multiselect fields render an inline LoadingSpinner beside the
+   * control — `makeCrmSearchSelectField` / `makeCrmSearchMultiSelectField`
+   * (hs-uix/utils) set this automatically while CRM search options load.
+   */
   loading?: boolean;
 
   // Conditional visibility
@@ -357,6 +375,8 @@ export interface FormBuilderRef {
   reset: () => void;
   getValues: () => Record<string, unknown>;
   isDirty: () => boolean;
+  /** Names of fields whose current value deep-differs from the initial snapshot. */
+  getDirtyFields: () => string[];
   setFieldValue: (name: string, value: unknown) => void;
   setFieldError: (name: string, message: string) => void;
   setErrors: (errors: Record<string, string>) => void;
@@ -424,6 +444,14 @@ export interface FormBuilderProps {
   submitVariant?: "primary" | "secondary";
   showCancel?: boolean;
   onCancel?: () => void;
+  /**
+   * Guard the built-in Cancel button while the form is dirty: clicking it
+   * opens a native Modal confirmation ("Keep editing" / destructive confirm)
+   * before onCancel fires. Pass `true` for default copy or an object to
+   * customize it. Note: extensions cannot intercept the host panel/modal
+   * close (the X button) — pair this with onDirtyChange for those cases.
+   */
+  confirmDiscard?: boolean | FormBuilderConfirmDiscardConfig;
   submitPosition?: "bottom" | "none";
   /**
    * Controls the default single-step action-row alignment.
@@ -496,3 +524,56 @@ export declare function useFormPrefill(
   properties: Record<string, unknown> | undefined,
   mapping?: Record<string, string>
 ): Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// HubSpot property schema mapping
+// ---------------------------------------------------------------------------
+
+/** One enumeration option on a HubSpot property definition. */
+export interface FormBuilderHubSpotPropertyOption {
+  label?: string;
+  value: string | number | boolean;
+  description?: string;
+  displayOrder?: number;
+  hidden?: boolean;
+}
+
+/** A HubSpot property definition (GET /crm/v3/properties/{objectType}). Extra API fields are tolerated. */
+export interface FormBuilderHubSpotProperty {
+  name: string;
+  label?: string;
+  type?: string; // "string" | "number" | "date" | "datetime" | "enumeration" | "bool" | ...
+  fieldType?: string; // "text" | "textarea" | "select" | "radio" | "checkbox" | "booleancheckbox" | "number" | "date" | "phonenumber" | ...
+  description?: string;
+  options?: FormBuilderHubSpotPropertyOption[];
+  hidden?: boolean;
+  calculated?: boolean;
+  modificationMetadata?: { readOnlyValue?: boolean; [k: string]: unknown };
+  [k: string]: unknown;
+}
+
+export interface FormBuilderHubSpotSchemaOptions {
+  /** Property names to keep. Also sets the output field order. */
+  include?: string[];
+  /** Property names to drop. */
+  exclude?: string[];
+  /** Per-property partial field configs merged over the generated config. */
+  overrides?: Record<string, Partial<FormBuilderField>>;
+  /** Property names to mark required — an array of names or a name → required map. */
+  requiredOverrides?: string[] | Record<string, boolean>;
+  /** Copy property descriptions into field `description` help text. Default false. */
+  includeDescriptions?: boolean;
+}
+
+/**
+ * Maps HubSpot property definitions to FormBuilder field configs.
+ * select → select · radio → radioGroup · checkbox → multiselect ·
+ * booleancheckbox → toggle (with "true"/"false" string normalization) ·
+ * date → date · datetime → datetime · number → number (string parsing) ·
+ * textarea → textarea · text/phonenumber → text. Hidden enumeration options
+ * are filtered; calculated / readOnlyValue properties come back readOnly.
+ */
+export declare function fieldsFromHubSpotProperties(
+  properties: FormBuilderHubSpotProperty[] | null | undefined,
+  options?: FormBuilderHubSpotSchemaOptions
+): FormBuilderField[];

package/src/kanban/README.md

@@ -33,6 +33,8 @@ That's a filterable, sortable, stage-bucketed board with per-stage footers and i
 - Full-text search across any combination of fields, with optional fuzzy matching via Fuse.js
 - Headline metrics panel rendered above the board (`<Statistics>` under the hood) via a `metrics` prop
 - Stage transition prompts — async confirmation or extra-property capture before committing a stage change, declared per-stage via `stage.onEnterRequired.render`
+- WIP limits — per-stage `wipLimit` (or a top-level `wipLimits` override) renders `count / limit` headers, an "Over WIP" warning tag on over-limit stages, and fires `onWipExceeded` once per crossing
+- Swimlanes — `swimlaneBy` groups the board vertically into stacked lane sections (each with its own header, count, and row of stage columns), with explicit ordering, custom labels, collapsible lanes, and optional per-lane metrics
 - Per-card selection with a bulk action bar, plus `KanbanCardActions` for per-card actions
 - Per-stage pagination via `stageMeta` + `onLoadMore` — mix client-side, server-load-more, and pre-bucketed server data column-by-column
 - Empty / loading / error render slots that mirror DataTable's override API
@@ -329,6 +331,91 @@ Invalid target stages are disabled in the inline control; no callback fires.
 
 ---
 
+### WIP limits
+
+Declare a limit per stage (or override centrally with `wipLimits`) and the stage header switches from a plain count to `count / limit`. When the count goes **over** the limit — at the limit is full, not over — the header grows a warning `StatusTag` ("Over WIP") and `onWipExceeded` fires.
+
+```jsx
+const STAGES = [
+  { value: "qualified",   label: "Qualified",   variant: "info" },
+  { value: "in_progress", label: "In Progress", variant: "info",    wipLimit: 5 },
+  { value: "review",      label: "Review",      variant: "warning", wipLimit: 3 },
+  { value: "done",        label: "Done",        variant: "success", terminal: true },
+];
+
+<Kanban
+  data={tickets}
+  stages={STAGES}
+  groupBy="status"
+  cardFields={CARD_FIELDS}
+  // Optional central override — beats stage.wipLimit per stage. Useful when
+  // limits come from team settings rather than the stage config.
+  wipLimits={{ in_progress: teamSettings.wipLimit }}
+  onWipExceeded={(stageId, count, limit) => {
+    notify(`${stageId} is over its WIP limit (${count}/${limit})`);
+  }}
+  onStageChange={handleStageChange}
+/>
+```
+
+Semantics worth knowing:
+
+- **Limits never block transitions.** A move that pushes a stage over its limit still completes and `onStageChange` still fires. The component is stateless on the write path — your server is the source of truth — so blocking client-side would only desync the board from reality and prevent legitimate over-limit moves (expedites, bulk reassignment). WIP limits are a signal, not a gate. Enforce hard caps server-side if you need them.
+- **`onWipExceeded` fires on the transition into exceeded**, not on every render: once when a stage crosses its limit (including a board that mounts already over a limit — that reports once on mount), and again only after the stage recovers below the limit and re-crosses.
+- **Counts follow the header.** The number checked against the limit is the same one the column header shows: `stageMeta[stage].totalCount` when present (server truth), otherwise the loaded, filtered bucket size.
+- **`wipLimit: 0` is valid** ("this stage should stay empty"); negative or non-numeric limits are ignored.
+- Customize the header strings via `labels.wipCount` (`(count, limit) => string`, default `"5 / 4"` style) and `labels.overWip` (default `"Over WIP"`).
+
+---
+
+### Swimlanes
+
+`swimlaneBy` (field name or `(row) => key` accessor) splits the board vertically into stacked lane sections — by owner, priority, team, SLA tier. Each lane renders a header (label + count + collapse chevron) above its own row of stage columns.
+
+```jsx
+<Kanban
+  data={deals}
+  stages={STAGES}
+  groupBy="stage"
+  cardFields={CARD_FIELDS}
+  swimlaneBy="priority"
+  swimlaneOrder={["high", "medium", "low"]}
+  swimlaneLabels={{ high: "High priority", medium: "Medium", low: "Low" }}
+  defaultCollapsedLanes={["low"]}
+  onStageChange={handleStageChange}
+/>
+```
+
+Behavior:
+
+- **Lane order**: keys in `swimlaneOrder` render first, in that order — and hold their slot even when empty (an explicit order doubles as an explicit lane list). Lanes not listed append in first-seen data order. Without `swimlaneOrder`, all lanes render first-seen.
+- **Labels**: `swimlaneLabels` is a `{ key: label }` map or a `(laneKey, rows) => ReactNode` function. Unlabeled lanes show their key. Rows whose lane value is `null`/`undefined`/`""` collect in a shared lane keyed `"__unassigned"` (exported as `UNASSIGNED_LANE_KEY`), labeled via `labels.unassignedLane` (default `"Unassigned"`).
+- **Collapsible lanes**: on by default; collapse state is the usual controlled/uncontrolled trio — `collapsedLanes` + `onCollapsedLanesChange` (controlled) or `defaultCollapsedLanes` (uncontrolled). Set `collapseLanes={false}` to remove the affordance. Collapsed lane keys are also included in `onParamsChange` payloads.
+- **Empty lane×stage cells render compactly** — a single header row with the empty placeholder instead of a full column shell, so sparse boards don't drown in empty columns.
+- **WIP limits stay per-stage** (a limit applies to the stage total across all lanes, not to each lane's slice). Lane cells show lane-local counts; every cell of an over-limit stage carries the "Over WIP" tag, while the `count / limit` fraction renders on the flat (non-swimlane) board where the header count *is* the stage count.
+- **Per-stage pagination (`stageMeta` / `onLoadMore`) is flat-board only.** In swimlane mode the per-cell footers describe lane slices, so load-more / totalCount displays are omitted; WIP evaluation still honors `stageMeta.totalCount`.
+- **Stage collapse/expand stays global** — collapsing a stage collapses it in every lane.
+
+#### Per-lane metrics
+
+The headline metrics row stays global by default. For per-lane summaries, pass `metricsPerLane={true}` and make `metrics` a *function* — it's called per lane with `(laneRows, laneKey)` and rendered under each lane header while the toolbar's Metrics toggle is on:
+
+```jsx
+<Kanban
+  {...rest}
+  swimlaneBy="owner"
+  metricsPerLane
+  metrics={(rows, laneKey) => [
+    { label: "Pipeline", number: formatCurrencyCompact(sumBy(rows, "amount")) },
+    { label: "Deals",    number: rows.length },
+  ]}
+/>
+```
+
+Without `metricsPerLane` (or without lanes), a metrics function is called once with all filtered rows — so the same function serves both modes. Arrays and ReactNodes keep rendering globally regardless of `metricsPerLane`.
+
+---
+
 ### Row selection with bulk actions
 
 Add `selectable={true}` and checkboxes appear on each card (top-right of the title row). When any card is selected, a compact selection bar appears above the board with selected count, "Select all", "Deselect all", and any custom action buttons.
@@ -497,7 +584,7 @@ If your data comes from an API or you have too many records to load up-front, dr
   searchValue={params.search}
   filterValues={params.filters}
   sort={params.sort}
-  onParamsChange={fetchBoard}    // { search, filters, sort, collapsedStages }
+  onParamsChange={fetchBoard}    // { search, filters, sort, collapsedStages, collapsedLanes }
 
   stageMeta={stageMeta}          // per-column totals / hasMore / loading
   onLoadMore={loadMoreForStage}
@@ -506,7 +593,7 @@ If your data comes from an API or you have too many records to load up-front, dr
 />
 ```
 
-`onParamsChange` fires on any toolbar change with a unified `{ search, filters, sort, collapsedStages }` object so you can avoid wiring four separate callbacks. The component never mutates `data` — updating the board after a stage change or load-more is the caller's job, same as DataTable's `onRowEdit`.
+`onParamsChange` fires on any toolbar change with a unified `{ search, filters, sort, collapsedStages, collapsedLanes }` object so you can avoid wiring five separate callbacks. The component never mutates `data` — updating the board after a stage change or load-more is the caller's job, same as DataTable's `onRowEdit`.
 
 ---
 
@@ -533,6 +620,16 @@ If your data comes from an API or you have too many records to load up-front, dr
 | `onExpandedStagesChange` | `(stages) => void` | — | Controlled-expansion callback |
 | `stageMeta` | `Record<string, KanbanStageMeta>` | — | Per-stage `hasMore` / `totalCount` / `loading` / `error` |
 | `onLoadMore` | `(stage) => void` | — | Per-column "Load more" callback |
+| `wipLimits` | `Record<string, number>` | — | Top-level per-stage WIP limit overrides (`{ [stageId]: n }`). Beats `stage.wipLimit`. |
+| `onWipExceeded` | `(stageId, count, limit) => void` | — | Fires once when a stage transitions over its limit (incl. mounting already over). Never blocks the move. |
+| `swimlaneBy` | `string \| (row) => key` | — | Groups the board vertically into stacked lane sections |
+| `swimlaneLabels` | `Record<string, string> \| (laneKey, rows) => ReactNode` | — | Lane header labels. Unlabeled lanes show their key. |
+| `swimlaneOrder` | string[] | first-seen | Explicit lane order; listed keys render first and persist even when empty |
+| `collapseLanes` | boolean | `true` | Show the collapse chevron on lane headers |
+| `collapsedLanes` | string[] | — | Controlled list of collapsed lane keys |
+| `defaultCollapsedLanes` | string[] | `[]` | Initial collapsed lane keys (uncontrolled) |
+| `onCollapsedLanesChange` | `(laneKeys) => void` | — | Lane collapse callback |
+| `metricsPerLane` | boolean | `false` | Render the metrics panel inside each lane. Requires `metrics` to be a function. |
 | `selectable` | boolean | `false` | Show a selection checkbox on each card |
 | `selectedIds` | `Id[]` | — | Controlled selection — array of row IDs |
 | `onSelectionChange` | `(ids) => void` | — | Called when selection changes |
@@ -565,14 +662,14 @@ If your data comes from an API or you have too many records to load up-front, dr
 | `columnWidth` | number | `350` | Min per-column width in px (AutoGrid `columnWidth`). Clamped to a 350px minimum. |
 | `collapsedStages` | string[] | — | Controlled list of collapsed stage values |
 | `onCollapsedStagesChange` | `(stages) => void` | — | Controlled-collapse callback |
-| `metrics` | `KanbanMetricItem[] \| ReactNode` | — | Headline metrics panel. Array → `<StatisticsItem>` shorthand; ReactNode → full custom render. |
+| `metrics` | `KanbanMetricItem[] \| ReactNode \| (rows, laneKey) => items \| node` | — | Headline metrics panel. Array → `<StatisticsItem>` shorthand; ReactNode → full custom render; function → computed from the filtered rows (and per lane with `metricsPerLane`). |
 | `showMetrics` | boolean | — | Controlled visibility of the metrics panel |
 | `onMetricsToggle` | `(visible) => void` | — | Called when the toolbar Metrics button is clicked |
 | `searchValue` | string | — | Controlled search term |
 | `onSearchChange` | `(term) => void` | — | Search callback |
 | `filterValues` | `Record<string, unknown>` | — | Controlled filter values |
 | `onFilterChange` | `(values) => void` | — | Filter callback |
-| `onParamsChange` | `({ search, filters, sort, collapsedStages }) => void` | — | Unified callback fired on any toolbar change |
+| `onParamsChange` | `({ search, filters, sort, collapsedStages, collapsedLanes }) => void` | — | Unified callback fired on any toolbar change |
 | `loading` | boolean | `false` | Show a loading skeleton in place of the board |
 | `error` | `string \| boolean` | — | Show an error state. String value is used as the title. |
 | `labels` | `KanbanLabels` | — | Override hardcoded UI strings for i18n |
@@ -592,6 +689,7 @@ If your data comes from an API or you have too many records to load up-front, dr
 | `color` | string | Optional dot color for the header |
 | `icon` | string | Optional HubSpot `Icon` name for the header |
 | `terminal` | boolean | Mark as a "closed" stage (hidden behind a "Show closed" toggle) |
+| `wipLimit` | number | WIP limit. Header shows `count / limit` plus an "Over WIP" tag when exceeded. `0` is valid; overridden per stage by the `wipLimits` prop. Advisory only — never blocks transitions. |
 | `order` | number | Explicit order override (otherwise array order wins) |
 | `footer` | `(rows) => ReactNode` | Per-stage footer content (overrides `columnFooter`) |
 | `canEnter` | `(row) => boolean` | Gate whether a row can move *into* this stage |
@@ -679,7 +777,23 @@ If your data comes from an API or you have too many records to load up-front, dr
 
 ### Labels
 
-`labels` accepts overrides for every hardcoded UI string. See `KanbanLabels` in `kanban.d.ts` for the full list — the most common overrides are `search`, `filtersButton`, `sortButton`, `loadMore`, `loadingMore`, `showMore`, `emptyTitle`, `emptyMessage`, `selected`, `selectAll`, `deselectAll`, `moveTo`, `metricsButton`.
+`labels` accepts overrides for every hardcoded UI string. See `KanbanLabels` in `kanban.d.ts` for the full list — the most common overrides are `search`, `filtersButton`, `sortButton`, `loadMore`, `loadingMore`, `showMore`, `emptyTitle`, `emptyMessage`, `selected`, `selectAll`, `deselectAll`, `moveTo`, `metricsButton`, plus the WIP/swimlane strings `wipCount` (`(count, limit) => string`), `overWip`, `laneCount`, and `unassignedLane`.
+
+### Lane & WIP helper functions
+
+The pure logic behind swimlanes and WIP limits is exported for reuse (custom lane summaries, server-side WIP alerting, tests):
+
+| Export | Signature | Description |
+|---|---|---|
+| `UNASSIGNED_LANE_KEY` | `"__unassigned"` | Lane key for rows with a null/undefined/empty swimlane value |
+| `getLaneKey` | `(row, swimlaneBy) => string` | Resolve a row's lane key (String-coerced) |
+| `orderLaneKeys` | `(seenKeys, swimlaneOrder?) => string[]` | Explicit order first (kept even when empty), then first-seen |
+| `partitionLanes` | `(rows, { swimlaneBy, swimlaneOrder }) => { laneKeys, rowsByLane }` | Full lane partition in render order |
+| `resolveLaneLabel` | `(laneKey, swimlaneLabels?, rows?, unassignedLabel?) => label` | Lane display label with fallbacks |
+| `resolveWipLimit` | `(stage, wipLimits?) => number \| null` | Effective limit (override beats `stage.wipLimit`; invalid → null) |
+| `computeStageCounts` | `(stages, buckets, stageMeta?) => Record<string, number>` | Header-consistent per-stage counts (`totalCount` else bucket size) |
+| `evaluateWip` | `(stages, counts, wipLimits?) => Record<string, { count, limit, exceeded }>` | Per-stage WIP status (`exceeded` = strictly over) |
+| `findNewlyExceededWip` | `(prev, next) => { stageId, count, limit }[]` | Stages that newly crossed into exceeded — the `onWipExceeded` contract |
 
 ---
 
@@ -695,7 +809,6 @@ These come from HubSpot UI Extensions itself, not Kanban:
 | Rotated column labels | Collapsed columns stack each character vertically in its own `Text` (no CSS transforms available). Long stage names become tall — use `shortLabel` for those. |
 | External-link glyph on title links | HubSpot's `Link` primitive always shows the external-link glyph when `href.external === true`. To get a title link *without* the glyph, omit `external: true`. New-tab + no-glyph is not possible today. |
 | No row expansion | Cards are read-mostly; expandable detail rows aren't supported. Route to the CRM record for full edits. |
-| No swimlanes | Secondary grouping (e.g. by owner within stage) isn't supported. On the roadmap. |
 | No export | No built-in CSV/Excel export. Pair with a serverless function. |
 
 See [`src/kanban/SPEC.md`](./SPEC.md) for the full design doc, decision log, and roadmap.