@ahrowe/ui 0.14.0 → 0.14.1

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

@@ -1,12 +1,24 @@
 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;
 }
 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 +30,72 @@ 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;
     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';
+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/docs/KanbanBoard.md

@@ -34,22 +34,147 @@ 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)}
+/>
 ```
 
+**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` |
+| `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
+}
 ```
 
+**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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "publishConfig": {
     "access": "public"
   },
@@ -55,7 +55,7 @@
     "build:mcp": "vite build --config vite.mcp.config.ts",
     "preview": "vite preview",
     "gen-barrel": "tsx scripts/gen-barrel.ts",
-    "gc": "bash src/scripts/generateComponent.sh $INIT_CWD process.argv",
+    "gc": "bash src/scripts/generateComponent.sh",
     "changeset": "changeset",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -84,7 +84,6 @@
     "@mona-health/react-input-mask": "^3.0.3",
     "classnames": "^2.5.1",
     "downshift": "^9.3.3",
-    "prop-types": "^15.8.1",
     "react-number-format": "^5.4.5",
     "zod": "^4.4.3"
   },
@@ -101,7 +100,6 @@
     "@types/node": "^25.9.1",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
-    "@types/react-helmet": "^6.1.11",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@vitejs/plugin-react": "^6.0.2",
     "@vitest/ui": "^4.1.7",