@ahrowe/ui 0.14.0 → 0.15.0

package/dist/types/package/common/kanbanBoard/KanbanItem.d.ts

@@ -1,7 +1,3 @@
-import { ReactNode } from 'react';
-interface KanbanItemProps {
-    id: string;
-    children: ReactNode;
-}
-declare function KanbanItem({ id, children }: KanbanItemProps): import("react/jsx-runtime").JSX.Element;
+import { KanbanItemProps } from './kanbanBoard.types';
+declare function KanbanItem({ id, dragHandle, disabled, preventAsDropTarget, children }: KanbanItemProps): import("react/jsx-runtime").JSX.Element;
 export default KanbanItem;

package/dist/types/package/common/kanbanBoard/kanbanBoard.types.d.ts

@@ -1,12 +1,31 @@
 import { CSSProperties, ReactNode } from 'react';
-import { SlotClassNames, SlotStyles } from '../types/slots.types';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export interface KanbanColumnDef {
     id: string;
     title: string;
     itemIds: string[];
+    /**
+     * Optional work-in-progress limit. When set, the column header shows a `count/maxItems`
+     * badge, and the column gets a warning style once `itemIds.length` exceeds it. This is
+     * display-only — `KanbanBoard` doesn't block drops on its own. To enforce a hard limit,
+     * check it in `onChange` and skip updating your state when a drop would push a column over.
+     */
+    maxItems?: number;
+    /**
+     * Freezes the column: cards inside it can't be picked up, and nothing can be dropped into it.
+     * Use for a workflow rule like "cards in Done can't be moved back out."
+     */
+    disabled?: boolean;
+    /**
+     * Whether more items exist for this column beyond what's currently in `itemIds` — enables the
+     * scroll-triggered `onLoadMore` request. Only meaningful alongside `KanbanBoardProps.onLoadMore`;
+     * a column without it never asks for more regardless of this flag. Set `false` (or omit) once
+     * the column's source is exhausted to stop asking.
+     */
+    hasMore?: boolean;
 }
 export type KanbanBoardSlots = 'dragOverlay';
-export interface KanbanBoardProps<T = unknown> {
+export interface KanbanBoardProps<T = unknown> extends HtmlProps {
     /** Ordered list of column definitions. Each column owns its itemIds. */
     columns: KanbanColumnDef[];
     /** Flat map of all items keyed by their id. */
@@ -18,18 +37,93 @@ export interface KanbanBoardProps<T = unknown> {
      * Receives the full updated columns array — replace your state with this value.
      */
     onChange: (columns: KanbanColumnDef[]) => void;
+    /**
+     * Restrict drag initiation to elements marked `data-drag-handle` within a card,
+     * instead of the whole card. Use when `renderItem` includes interactive content
+     * (buttons, inputs) that would otherwise have its clicks swallowed by the drag listener.
+     */
+    dragHandle?: boolean;
+    /**
+     * Produce an accessible label for a card, announced to screen-reader users while dragging
+     * (e.g. "Picked up <label>."). Defaults to the card's id when omitted.
+     */
+    getItemLabel?: (item: T, id: string) => string;
+    /**
+     * Returns whether a specific card can't be picked up. Defaults to every card being draggable.
+     * Independent of a column's own `disabled` — a card can be pinned even in an otherwise
+     * unrestricted column.
+     */
+    getItemDisabled?: (item: T, id: string) => boolean;
+    /**
+     * Custom content shown inside a column when it has no cards, instead of leaving it blank.
+     * Receives the column definition.
+     */
+    renderEmptyColumn?: (column: KanbanColumnDef) => ReactNode;
+    /**
+     * Custom actions rendered in a column's header, next to its title (e.g. an "add card"
+     * button, a column menu). Receives the column definition.
+     */
+    renderColumnActions?: (column: KanbanColumnDef) => ReactNode;
+    /**
+     * Allow whole columns to be reordered by dragging their header, alongside the existing
+     * card dragging. Defaults to `false`.
+     */
+    reorderableColumns?: boolean;
+    /**
+     * Shrink a column to a narrow strip once it has no cards, instead of keeping it at the same
+     * width as every other column. Defaults to `true`. Set `false` to keep every column the same
+     * width regardless of card count. The collapsed width itself is set via the
+     * `--kanban-empty-column-width` CSS variable (falls back to `140px`) — override it theme-wide
+     * via `ThemeProvider`'s `variables`, or per board via `style`.
+     */
+    collapseEmptyColumns?: boolean;
+    /**
+     * Bounds each column's height (any CSS length, e.g. `'70vh'`, `'600px'`) and makes its card
+     * list scroll independently once content overflows, instead of growing the whole page. Leave
+     * unset for the default unbounded height. Required for `onLoadMore` to ever trigger, since an
+     * unbounded column never scrolls.
+     */
+    columnMaxHeight?: string;
+    /**
+     * Called with a column's `id` when that column has `hasMore` set and its card list is scrolled
+     * within `loadMoreThreshold` of the bottom — fetch and append the next page of items for it.
+     * `KanbanColumn` tracks its own in-flight state per column (shown as a spinner at the bottom of
+     * the list), so overlapping calls for the same column are never made concurrently. Also
+     * retried automatically if a loaded batch doesn't fill the column's visible height, since a
+     * column shorter than its own viewport never generates a scroll event to trigger a next page.
+     */
+    onLoadMore?: (columnId: string) => void | Promise<void>;
+    /**
+     * Distance in px from the bottom of a column's scroll area that triggers `onLoadMore` (default
+     * `100`, matching `VirtualList`'s `loadMoreThreshold`).
+     */
+    loadMoreThreshold?: number;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<KanbanBoardSlots>;
     styles?: SlotStyles<KanbanBoardSlots>;
 }
-export type KanbanColumnSlots = 'header' | 'items';
-export interface KanbanColumnProps {
+export type KanbanColumnSlots = 'header' | 'items' | 'count' | 'placeholder' | 'actions' | 'loadingIndicator';
+export interface KanbanColumnProps extends HtmlProps {
     id: string;
     title: string;
-    isOver?: boolean;
     children?: ReactNode;
     className?: string;
+    style?: CSSProperties;
     classNames?: SlotClassNames<KanbanColumnSlots>;
     styles?: SlotStyles<KanbanColumnSlots>;
 }
+export interface KanbanItemProps {
+    id: string;
+    dragHandle?: boolean;
+    /** Whether this card can't be picked up (column frozen, or the card itself is pinned). */
+    disabled?: boolean;
+    /**
+     * Whether this card also can't be a drop target for other cards — i.e. other cards can't be
+     * reordered relative to it either. Only true when the *column* is frozen (nothing should be
+     * dropped into it at all); a card pinned individually via `getItemDisabled` stays droppable, so
+     * other cards can still land before/after it normally.
+     */
+    preventAsDropTarget?: boolean;
+    children?: ReactNode;
+}

package/dist/types/package/common/kanbanBoard/kanbanBoard.utils.d.ts

@@ -0,0 +1,60 @@
+import { Announcements, ClientRect, CollisionDetection, KeyboardCoordinateGetter } from '@dnd-kit/core';
+import { KanbanColumnDef } from './kanbanBoard.types';
+export declare function columnsEqual(a: KanbanColumnDef[], b: KanbanColumnDef[]): boolean;
+export declare function findColumnForItem(columns: KanbanColumnDef[], itemId: string): number;
+/** Whether a drag's `active`/`over` participant is a whole column (vs. a card) — see `reorderableColumns`. */
+export declare function isColumnDragData(data: unknown): boolean;
+/**
+ * Reorders whole columns: moves `activeColumnId` to `overColumnId`'s position. Returns the same
+ * `columns` reference, unchanged, when either id doesn't resolve to a column or they're the same
+ * — callers can use that to skip a state update.
+ */
+export declare function moveColumn(columns: KanbanColumnDef[], activeColumnId: string, overColumnId: string): KanbanColumnDef[];
+/**
+ * Collision detection for the board's shared `DndContext`, which has to pick between two very
+ * differently-scaled sets of droppables at once: individual cards / a column's own card list
+ * (small, numerous) and whole columns (large, few). Plain `closestCorners` weighs every
+ * registered droppable together regardless of what's actually being dragged, so while dragging a
+ * column it competes against every card and card-list droppable it happens to fly over too — the
+ * column-level target only wins when the pointer lands somewhere that geometrically favors it,
+ * which reads as needing to "wiggle it around" before the right drop target lights up. This
+ * restricts the candidates to only the same kind as whatever is being dragged: a column drag only
+ * considers other columns, a card drag only considers cards and card lists.
+ */
+export declare const kanbanCollisionDetection: CollisionDetection;
+/** Extracts the column id from a column droppable's `column-<id>` identifier, or `null` for a card id. */
+export declare function resolveColumnDropId(overId: string): string | null;
+export interface DragGeometry {
+    /** The dragged card's current rect (translated by the drag delta), if measured. */
+    activeRect: ClientRect | null;
+    /** The rect of whatever `overId` refers to — a card, or a column's own droppable. */
+    overRect: ClientRect;
+}
+/**
+ * Computes the columns that result from dragging `activeItemId` over `overId` (a card id, or a
+ * `column-<id>` droppable id for empty column space). Returns the same `columns` reference,
+ * unchanged, when the drag doesn't resolve to a valid source/destination — callers can use that
+ * to skip a state update.
+ *
+ * `geometry` resolves cross-column drops that land on a card or gap with more than one possible
+ * position (see the two branches below for what each one decides).
+ */
+export declare function moveItem(columns: KanbanColumnDef[], activeItemId: string, overId: string, geometry: DragGeometry): KanbanColumnDef[];
+/**
+ * Builds screen-reader drag announcements against the columns layout as currently understood
+ * (the live shadow layout while a drag is in progress, or the settled `columns` prop otherwise).
+ */
+export declare function buildAnnouncements<T>(columns: KanbanColumnDef[], items: Record<string, T>, getItemLabel: (item: T, id: string) => string): Announcements;
+/**
+ * Custom keyboard coordinate getter for the board's multi-column, multi-`SortableContext`
+ * layout. dnd-kit's default `sortableKeyboardCoordinates` picks the geometrically closest
+ * droppable across the *entire* board — cards and column containers alike — which is unreliable
+ * once cards live inside independent per-column `SortableContext`s: up/down and left/right end up
+ * interchangeable depending on incidental rect positions. This instead restricts up/down to
+ * reordering within the active card's own column, and left/right to moving into the adjacent
+ * column (landing on the closest card there by vertical position, or the column itself when
+ * empty). Requires each `KanbanColumn`'s `SortableContext` to be given an explicit `id` matching
+ * its column id, so a card's `sortable.containerId` can be correlated with its `column-<id>`
+ * droppable.
+ */
+export declare const kanbanKeyboardCoordinateGetter: KeyboardCoordinateGetter;

package/dist/types/package/common/themeProvider/theme.types.d.ts

@@ -107,6 +107,8 @@ export interface ThemeVariables {
     '--stepper-gap'?: string;
     /** Text/check colour on a filled marker. Falls back to --text-on-primary. */
     '--stepper-text-on-marker'?: string;
+    /** Width a column collapses to once it has no cards (see `collapseEmptyColumns`). Falls back to 140px. */
+    '--kanban-empty-column-width'?: string;
     [key: string]: string | undefined;
 }
 export interface Theme {

package/dist/types/package/common/timeline/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './timeline';
+export * from './timeline.types';

package/dist/types/package/common/timeline/timeline.d.ts

@@ -0,0 +1,2 @@
+import { TimelineProps } from './timeline.types';
+export default function Timeline({ items, alignment, className, style, classNames, styles: slotStyles, ...rest }: TimelineProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/package/common/timeline/timeline.types.d.ts

@@ -0,0 +1,51 @@
+import { default as React } from 'react';
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+/** Layout of entries relative to the connecting line. */
+export declare enum TimelineAlignment {
+    /** Line and markers on the left, content to the right (the default). */
+    Left = "left",
+    /** Line and markers on the right, content to the left. */
+    Right = "right",
+    /** Line down the center, entries alternating left/right. */
+    Alternate = "alternate"
+}
+/** Semantic colour for an entry's marker, matching the theme's status colours. */
+export declare enum TimelineItemStatus {
+    Default = "default",
+    Primary = "primary",
+    Success = "success",
+    Warn = "warn",
+    Error = "error"
+}
+export type TimelineSlots = 'root' | 'item' | 'marker' | 'dot' | 'connector' | 'content' | 'title' | 'description' | 'timestamp';
+export interface TimelineItem {
+    /** Stable identity for the entry, used as its React key. Falls back to its array index when omitted; pass one whenever `items` can be reordered or have entries prepended (e.g. a live "newest first" audit log), so React doesn't misattribute row state across the shift. */
+    id?: string | number;
+    /** Primary label for the entry. */
+    title: React.ReactNode;
+    /** Secondary line under the title. */
+    description?: React.ReactNode;
+    /** Rendered next to the title, e.g. a date or relative time ("2 hours ago"). */
+    timestamp?: React.ReactNode;
+    /** FontAwesome icon shown in the marker instead of a plain dot. */
+    icon?: IconDefinition;
+    /** Semantic marker colour (default `Default`). */
+    status?: TimelineItemStatus;
+    /** Extra content rendered under the description, e.g. a diff, an attachment, an actor avatar. */
+    content?: React.ReactNode;
+    /** Makes the whole entry clickable (e.g. to open the full record), rendering it as an accessible button. */
+    onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
+    /** Disables the entry: never clickable, dimmed. Only relevant alongside `onClick`. */
+    disabled?: boolean;
+}
+export interface TimelineProps extends HtmlProps {
+    /** The entries to render, in display order (typically newest first for an audit log). */
+    items?: TimelineItem[];
+    /** Layout of entries relative to the connecting line (default `Left`). */
+    alignment?: TimelineAlignment;
+    className?: string;
+    style?: React.CSSProperties;
+    classNames?: SlotClassNames<TimelineSlots>;
+    styles?: SlotStyles<TimelineSlots>;
+}

package/dist/types/package/index.d.ts

@@ -47,6 +47,8 @@ export { default as Dropdown } from './common/dropdown';
 export * from './common/dropdown';
 export { default as EmptyState } from './common/emptyState';
 export * from './common/emptyState';
+export { default as ErrorBoundary } from './common/errorBoundary';
+export * from './common/errorBoundary';
 export { default as Fab } from './common/fab';
 export * from './common/fab';
 export { default as FloatingMenu } from './common/floatingMenu';
@@ -117,6 +119,8 @@ export * from './common/themeProvider';
 export { useTheme } from './common/themeProvider/useTheme';
 export { default as TimeInput } from './common/timeInput';
 export * from './common/timeInput';
+export { default as Timeline } from './common/timeline';
+export * from './common/timeline';
 export { default as ToastProvider } from './common/toast';
 export * from './common/toast';
 export { default as Tooltip } from './common/tooltip';

package/docs/CLAUDE.md

@@ -117,6 +117,7 @@ Slot keys per component are documented in each component's doc file below.
 @Dropdown.md
 @DropZone.md
 @EmptyState.md
+@ErrorBoundary.md
 @Fab.md
 @FloatingMenu.md
 @FormValidator.md
@@ -154,6 +155,7 @@ Slot keys per component are documented in each component's doc file below.
 @Textarea.md
 @ThemeProvider.md
 @TimeInput.md
+@Timeline.md
 @Toast.md
 @Tooltip.md
 @VirtualList.md

package/docs/ErrorBoundary.md

@@ -0,0 +1,93 @@
+# ErrorBoundary
+
+**When to use:** Wrap any subtree whose render errors shouldn't take down the rest of the app — a widget, a route, a third-party embed, a list row. It catches JavaScript errors thrown while rendering descendants (via React's `getDerivedStateFromError` / `componentDidCatch`) and swaps in a fallback UI instead of unmounting the whole tree. Only errors thrown during rendering, in lifecycle methods, or in constructors of the tree below it are caught — event handlers, async code, and errors in the boundary itself are not, same as any React error boundary.
+
+**Import:** `import { ErrorBoundary } from '@ahrowe/ui'`
+
+```tsx
+import { ErrorBoundary } from '@ahrowe/ui';
+
+// Basic — default fallback with a "Try again" button
+<ErrorBoundary>
+  <Widget />
+</ErrorBoundary>
+
+// Report to your error tracker, and re-arm whatever caused the crash on reset
+<ErrorBoundary
+  onError={(error, errorInfo) => reportToSentry(error, errorInfo)}
+  onReset={() => setWidgetKey((k) => k + 1)}
+>
+  <Widget />
+</ErrorBoundary>
+
+// Custom copy, no stack-trace section (e.g. for a small inline widget)
+<ErrorBoundary
+  title="Widget crashed"
+  description="This panel failed to load. The rest of the page is unaffected."
+  hideStack
+>
+  <Widget />
+</ErrorBoundary>
+
+// Fully custom fallback UI — render function receives the error and a reset callback
+<ErrorBoundary
+  fallback={({ error, resetErrorBoundary }) => (
+    <div>
+      Something broke: {error.message}
+      <button onClick={resetErrorBoundary}>Retry</button>
+    </div>
+  )}
+>
+  <Widget />
+</ErrorBoundary>
+
+// Auto-reset when inputs the crash depends on change (e.g. a route or record id)
+<ErrorBoundary resetKeys={[recordId]}>
+  <RecordDetail id={recordId} />
+</ErrorBoundary>
+
+// Translated strings for a non-English app — title/description are their own
+// props (see above); labels covers everything else the built-in fallback renders
+<ErrorBoundary
+  title="Etwas ist schiefgelaufen"
+  labels={{
+    stackTrace: 'Stapelverfolgung',
+    copy: 'Kopieren',
+    copied: 'Kopiert',
+    reset: 'Erneut versuchen',
+    copySuccessToast: 'Stapelverfolgung kopiert',
+    copyErrorToast: 'Kopieren fehlgeschlagen',
+  }}
+>
+  <Widget />
+</ErrorBoundary>
+```
+
+The default fallback is a centered card with a tinted icon badge, an `Accordion` for the collapsible stack trace (with a labeled copy `Button` that fires a `Toast` confirmation if `ToastProvider` is mounted), and a `Button` for "Try again".
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | The subtree to protect |
+| `title` | `ReactNode` | Heading in the default fallback (default `"Something went wrong"`) |
+| `description` | `ReactNode` | Overrides the message shown under the title. Defaults to `error.message` |
+| `labels` | `ErrorBoundaryLabels` | Overrides for every other built-in string (stack trace label, copy/reset button text, copy toasts) — pass a translated set for non-English apps. See below |
+| `fallback` | `ReactNode \| (props: ErrorBoundaryFallbackProps) => ReactNode` | Replaces the built-in fallback entirely. The render-function form receives `{ error, errorInfo, resetErrorBoundary }` |
+| `onError` | `(error: Error, errorInfo: ErrorInfo) => void` | Called once per catch — the place to report to Sentry/Datadog/etc. |
+| `onReset` | `() => void` | Called after the boundary is reset, whether via the built-in "Try again" button, a custom fallback calling `resetErrorBoundary`, or a `resetKeys` change. Use it to re-arm whatever state caused the crash |
+| `resetKeys` | `unknown[]` | When any value in this array changes while the boundary is showing an error, it resets automatically — mirrors the common `react-error-boundary` pattern |
+| `hideStack` | `boolean` | Hide the collapsible stack-trace section. Default `false` |
+
+**`ErrorBoundaryLabels`:**
+
+| Field | Default | Description |
+|-------|---------|--------------|
+| `stackTrace` | `"Stack trace"` | Accordion header for the stack trace section |
+| `copy` | `"Copy"` | Copy button label before copying |
+| `copied` | `"Copied"` | Copy button label right after a successful copy |
+| `reset` | `"Try again"` | Reset button label |
+| `copySuccessToast` | `"Stack trace copied to clipboard"` | Toast shown after a successful copy (only visible if `ToastProvider` is mounted) |
+| `copyErrorToast` | `"Could not copy stack trace"` | Toast shown if the copy fails |
+
+**Slots:** `root` `header` `badge` `icon` `title` `description` `stack` `stackHeader` `stackLabel` `stackTrace` `copyButton` `actions` `resetButton`

package/docs/KanbanBoard.md

@@ -34,22 +34,183 @@ const items: Record<string, Task> = {
   )}
   onChange={(updatedColumns) => setColumns(updatedColumns)}
 />
+
+// Restrict drag initiation to a handle — needed when a card contains its own
+// interactive controls (buttons, inputs), which would otherwise have their
+// clicks swallowed by the drag listener on the whole card
+<KanbanBoard
+  columns={columns}
+  items={items}
+  dragHandle
+  renderItem={(task, id) => (
+    <div className="task-card">
+      <span data-drag-handle>⠿</span>
+      <strong>{task.title}</strong>
+      <button onClick={() => deleteTask(id)}>Delete</button>
+    </div>
+  )}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Work-in-progress limit — shows a "count/max" badge on the column header and a
+// warning border once it's exceeded. Display-only: KanbanBoard doesn't block the
+// drop itself, so enforce a hard cap (if you want one) inside onChange, by simply
+// not calling setColumns when the destination column would go over its maxItems.
+const columnsWithLimit: KanbanColumnDef[] = [
+  { id: 'inprogress', title: 'In Progress', itemIds: ['task-3'], maxItems: 3 },
+];
+
+// Accessible labels for screen-reader drag announcements — defaults to the card's
+// id when omitted, so this is purely an upgrade for clearer narration
+<KanbanBoard
+  columns={columns}
+  items={items}
+  getItemLabel={(task) => task.title}
+  renderItem={(task, id) => (
+    <div className="task-card">
+      <strong>{task.title}</strong>
+    </div>
+  )}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Freeze a column — cards inside can't be picked up, and nothing can be dropped
+// into it. Use for a workflow rule like "cards in Done can't be moved back out."
+const columnsWithLock: KanbanColumnDef[] = [
+  { id: 'done', title: 'Done', itemIds: ['task-3'], disabled: true },
+];
+
+// Pin an individual card so it can't be dragged, independent of its column —
+// e.g. a task that's locked pending approval
+<KanbanBoard
+  columns={columns}
+  items={items}
+  getItemDisabled={(task) => task.locked === true}
+  renderItem={(task, id) => (
+    <div className="task-card">
+      <strong>{task.title}</strong>
+      {task.locked && <span>🔒</span>}
+    </div>
+  )}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Custom content for an empty column, instead of leaving it blank
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  renderEmptyColumn={(column) => <span>No tasks in {column.title}</span>}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Custom actions in a column's header — an "add card" button, a column menu — laid
+// out next to the title (and the maxItems count badge, when both are present)
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  renderColumnActions={(column) => (
+    <button onClick={() => addTaskTo(column.id)} aria-label={`Add task to ${column.title}`}>+</button>
+  )}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Let whole columns be reordered by dragging their header, alongside card dragging.
+// The same onChange receives the reordered columns array — no separate callback needed.
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  reorderableColumns
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Keep every column the same width regardless of card count — opt out of the
+// default shrink-when-empty behaviour
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  collapseEmptyColumns={false}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Bound each column's height and let its card list scroll independently, instead
+// of growing the whole page — useful once a column can hold a lot of cards
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  columnMaxHeight="70vh"
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Paginate a column instead of loading everything up front — mark it `hasMore`
+// and fetch/append the next page in `onLoadMore` once it's scrolled near the
+// bottom. Requires `columnMaxHeight`, since an unbounded column never scrolls.
+// KanbanBoard tracks its own in-flight state per column (shown as a spinner at
+// the bottom of the list) and retries automatically if a page doesn't fill the
+// column's visible height, so pagination doesn't dead-end on a short first batch.
+const columnsPaged: KanbanColumnDef[] = [
+  { id: 'done', title: 'Done', itemIds: doneTaskIds, hasMore: doneHasMore },
+];
+
+<KanbanBoard
+  columns={columnsPaged}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  columnMaxHeight="70vh"
+  onLoadMore={async (columnId) => {
+    const nextPage = await fetchNextPage(columnId);
+    appendItemsToColumn(columnId, nextPage); // your own state update
+  }}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
 ```
 
+**Keyboard support:** cards are focusable and can be picked up and moved with the keyboard — Space or Enter to pick up, Space or Enter again to drop, Escape to cancel (reverts to the original position). Arrow keys move the card: Up/Down reorders within its current column; Left/Right moves it into the adjacent column, landing on the nearest card there (or the column itself, if it's empty). This uses a board-aware coordinate getter rather than `dnd-kit`'s generic `sortableKeyboardCoordinates`, which — across multiple per-column `SortableContext`s — can't reliably tell "next card in this column" from "some other column's droppable" and ends up mixing up Up/Down and Left/Right. With `reorderableColumns`, a column's header is focusable the same way — Space/Enter to pick it up, Left/Right to move it, Up/Down does nothing (columns are a single row).
+
+**Column reordering (`reorderableColumns`):** a column's header becomes its drag handle for moving the whole column — dragging the cards area still only moves cards. This shares the same `DndContext` as card dragging (mouse, touch, and keyboard all work the same way), and commits through the same `onChange` — a column move is just a reordering of the `columns` array, same as any other change.
+
+**Screen-reader announcements:** every pick-up, hover, drop, and cancel is announced (e.g. "Picked up card Design mockup.", "Card Design mockup is over the In Progress column."). By default cards are announced by their id — pass `getItemLabel` to announce something meaningful instead (a title, a short description).
+
 **KanbanBoardProps:**
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `columns` | `KanbanColumnDef[]` | Column definitions with `id`, `title`, `itemIds` |
+| `columns` | `KanbanColumnDef[]` | Column definitions with `id`, `title`, `itemIds`, optional `maxItems` |
 | `items` | `Record<string, T>` | Flat map of all items keyed by id |
 | `renderItem` | `(item: T, id: string) => ReactNode` | Render function for each item |
-| `onChange` | `(columns: KanbanColumnDef[]) => void` | Called after every drop — replace state with this value |
+| `onChange` | `(columns: KanbanColumnDef[]) => void` | Called after a drop that actually changes column or order — replace state with this value |
+| `dragHandle` | `boolean` | Restrict drag initiation to elements marked `data-drag-handle` within a card, instead of the whole card. Use when `renderItem` includes interactive content |
+| `getItemLabel` | `(item: T, id: string) => string` | Accessible label for a card, used in screen-reader drag announcements. Defaults to the card's id |
+| `getItemDisabled` | `(item: T, id: string) => boolean` | Returns whether a specific card can't be picked up. Defaults to every card being draggable; independent of a column's own `disabled`. A pinned card stays a valid drop target — other cards can still be reordered before/after it, unlike a card inside a fully frozen (`disabled`) column |
+| `renderEmptyColumn` | `(column: KanbanColumnDef) => ReactNode` | Custom content shown inside a column when it has no cards, instead of leaving it blank |
+| `renderColumnActions` | `(column: KanbanColumnDef) => ReactNode` | Custom actions rendered in a column's header, next to its title (e.g. an "add card" button, a column menu) |
+| `reorderableColumns` | `boolean` | Allow whole columns to be reordered by dragging their header, alongside card dragging (default `false`) |
+| `collapseEmptyColumns` | `boolean` | Shrink a column to a narrow strip once it has no cards (default `true`). Set `false` to keep every column the same width regardless of card count. The collapsed width is set via `--kanban-empty-column-width` (falls back to `140px`) — override it theme-wide via `ThemeProvider`, or per board via `style` |
+| `columnMaxHeight` | `string` | Bounds each column's height (any CSS length, e.g. `'70vh'`) and makes its card list scroll independently once content overflows, instead of growing the whole page. Unset by default (unbounded height). Required for `onLoadMore` to ever trigger |
+| `onLoadMore` | `(columnId: string) => void \| Promise<void>` | Called when a column with `hasMore` is scrolled within `loadMoreThreshold` of the bottom — fetch and append the next page for that column. Tracked per column, so overlapping calls for the same column are never made concurrently; retried automatically if a loaded batch doesn't fill the column's own visible height |
+| `loadMoreThreshold` | `number` | Distance in px from the bottom of a column's scroll area that triggers `onLoadMore` (default `100`, matching `VirtualList`) |
+| `id` / `role` / `aria-*` / `data-*` | | Passed through to the root element |
+
+`KanbanColumn`'s own props accept the same `id` / `role` / `aria-*` / `data-*` pass-through on its root element.
 
 **KanbanColumnDef:**
 
 ```ts
-{ id: string; title: string; itemIds: string[] }
+{
+  id: string;
+  title: string;
+  itemIds: string[];
+  maxItems?: number; // work-in-progress limit — display-only, see above
+  disabled?: boolean; // freezes the column — cards inside can't be dragged, nothing can drop in
+  hasMore?: boolean; // more items exist beyond itemIds — enables onLoadMore, see above
+}
 ```
 
+**Note on item ids:** don't give a card an id starting with `column-` — the board uses that prefix internally to identify a column's own droppable (the empty space above/below its cards) versus a specific card. A colliding card id is silently misread as a column reference, and drops involving it silently no-op instead of throwing, so the bug can be easy to miss.
+
 **Slots (KanbanBoard):** `dragOverlay`  
-**Slots (KanbanColumn):** `header` `items`
+**Slots (KanbanColumn):** `header` `items` `count` (the `count/maxItems` badge, only rendered when `maxItems` is set) `placeholder` (the `renderEmptyColumn` wrapper, only rendered when the column has no cards and `renderEmptyColumn` is set) `actions` (the `renderColumnActions` wrapper, only rendered when `renderColumnActions` is set) `loadingIndicator` (the spinner shown while an `onLoadMore` request for that column is in flight)