@ahrowe/ui 0.45.0 → 0.46.0

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

@@ -1,3 +1,3 @@
 import { KanbanBoardProps } from './kanbanBoard.types.js';
-declare function KanbanBoard<T = unknown>({ columns, items, renderItem, onChange, dragHandle, getItemLabel, getItemDisabled, renderEmptyColumn, renderColumnActions, reorderableColumns, collapseEmptyColumns, columnMaxHeight, onLoadMore, loadMoreThreshold, className, style, classNames, styles: slotStyles, ...rest }: KanbanBoardProps<T>): import("react").JSX.Element;
+declare function KanbanBoard<T = unknown>({ columns, items, renderItem, onChange, dragHandle, getItemLabel, getItemDisabled, renderEmptyColumn, renderColumnActions, reorderableColumns, collapseEmptyColumns, columnMaxHeight, onLoadMore, loadMoreThreshold, onKeyDown, className, style, classNames, styles: slotStyles, ...rest }: KanbanBoardProps<T>): import("react").JSX.Element;
 export default KanbanBoard;

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

@@ -1,25 +1,21 @@
-import { ReactNode } from 'react';
-import { KanbanColumnProps } from './kanbanBoard.types.js';
+import { HTMLAttributes, ReactNode, Ref } from 'react';
+import { DataProps, SlotClassNames, SlotStyles } from '../types/slots.types.js';
+import { KanbanColumnProps, KanbanColumnSlots } from './kanbanBoard.types.js';
 interface KanbanColumnInternalProps<T> extends KanbanColumnProps {
     itemIds: string[];
     items: Record<string, T>;
     renderItem: (item: T, id: string) => ReactNode;
     dragHandle?: boolean;
-    /**
-     * Keep the column at its normal flex width even when `itemIds` is empty. Used while a drag
-     * is in progress: the empty-column collapse is driven by transient shadow state during a
-     * drag, and letting the column shrink mid-drag shifts every column's layout underneath the
-     * pointer, which can flip the collision target back and forth forever.
-     */
-    preserveSizeWhileEmpty?: boolean;
-    /** Shrink to a narrow strip when empty — see `KanbanBoardProps.collapseEmptyColumns`. Defaults to `true`. */
-    collapseEmptyColumns?: boolean;
+    /** Shrink to a narrow strip. The board decides when, see `KanbanBoardProps.collapseEmptyColumns`. */
+    collapsed?: boolean;
     /** Work-in-progress limit — see `KanbanColumnDef.maxItems`. Display-only. */
     maxItems?: number;
     /** Freezes the column — see `KanbanColumnDef.disabled`. */
     disabled?: boolean;
     /** Returns whether a specific card can't be picked up — see `KanbanBoardProps.getItemDisabled`. */
     getItemDisabled?: (item: T, id: string) => boolean;
+    /** Names a card's drag handle — see `KanbanBoardProps.getItemLabel`. */
+    getItemLabel?: (item: T, id: string) => string;
     /** Custom content shown when the column has no cards — see `KanbanBoardProps.renderEmptyColumn`. */
     emptyPlaceholder?: ReactNode;
     /** Custom header actions — see `KanbanBoardProps.renderColumnActions`. */
@@ -41,5 +37,18 @@ interface KanbanColumnInternalProps<T> extends KanbanColumnProps {
     /** Scroll distance from the bottom that triggers `onLoadMore` — see `KanbanBoardProps.loadMoreThreshold`. */
     loadMoreThreshold?: number;
 }
-declare function KanbanColumn<T>({ id, title, itemIds, items, renderItem, dragHandle, preserveSizeWhileEmpty, collapseEmptyColumns, maxItems, disabled, getItemDisabled, emptyPlaceholder, actions, reorderable, activeIsColumn, columnMaxHeight, hasMore, onLoadMore, loadMoreThreshold, className, style, classNames, styles: slotStyles, ...rest }: KanbanColumnInternalProps<T>): import("react").JSX.Element;
+interface ColumnHeaderContentProps {
+    title: string;
+    count: number;
+    maxItems?: number;
+    actions?: ReactNode;
+    /** Makes the title the column's keyboard drag handle. */
+    titleProps?: HTMLAttributes<HTMLSpanElement> & DataProps & {
+        ref?: Ref<HTMLSpanElement>;
+    };
+    classNames?: SlotClassNames<KanbanColumnSlots>;
+    styles?: SlotStyles<KanbanColumnSlots>;
+}
+export declare function ColumnHeaderContent({ title, count, maxItems, actions, titleProps, classNames, styles: slotStyles, }: ColumnHeaderContentProps): import("react").JSX.Element;
+declare function KanbanColumn<T>({ id, title, itemIds, items, renderItem, dragHandle, collapsed, maxItems, disabled, getItemDisabled, getItemLabel, emptyPlaceholder, actions, reorderable, activeIsColumn, columnMaxHeight, hasMore, onLoadMore, loadMoreThreshold, className, style, classNames, styles: slotStyles, ...rest }: KanbanColumnInternalProps<T>): import("react").JSX.Element;
 export default KanbanColumn;

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

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

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

@@ -38,14 +38,17 @@ export interface KanbanBoardProps<T = unknown> extends Omit<HtmlProps, 'onChange
      */
     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.
+     * Drag a card only by the element marked `data-drag-handle` inside it, with the mouse, touch
+     * and the keyboard, instead of by the whole card. The handle is made focusable and named with
+     * `getItemLabel` unless it has a name, and the card stops being a button. Use when `renderItem`
+     * includes controls (buttons, inputs): inside a card that is itself the button, a screen reader
+     * reads them as plain text.
      */
     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.
+     * (e.g. "Picked up <label>."), and naming a `dragHandle` handle that has no name of its own.
+     * Defaults to the card's id when omitted.
      */
     getItemLabel?: (item: T, id: string) => string;
     /**
@@ -70,27 +73,28 @@ export interface KanbanBoardProps<T = unknown> extends Omit<HtmlProps, 'onChange
      */
     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`.
+     * Shrink a column to a narrow strip while it has no cards. Defaults to `false`. Widths hold
+     * still during a drag: a column the drag empties or fills changes width after the drop. The
+     * collapsed width 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.
+     * Caps each column's card list at a length (any CSS length, e.g. `'70vh'`, `'600px'`), so a
+     * long column scrolls on its own instead of growing the page. To fill the space your layout
+     * gives the board instead, give the board a height (`style={{ height: '100%' }}` in a parent
+     * with one): its columns then scroll the same way.
      */
     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.
+     * 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.
+     * the list), so overlapping calls for the same column are never made concurrently. Also called
+     * while the column's cards leave empty space below them, since a column that doesn't overflow
+     * can't be scrolled. Paging all the way needs a column that scrolls: `columnMaxHeight`, or a
+     * board with a height. On a board that grows with its cards, a short column only fills up to
+     * the tallest one.
      */
     onLoadMore?: (columnId: string) => void | Promise<void>;
     /**
@@ -115,6 +119,8 @@ export interface KanbanColumnProps extends HtmlProps {
 }
 export interface KanbanItemProps {
     id: string;
+    /** Names the card's `[data-drag-handle]` when it has no `aria-label` of its own. */
+    label?: string;
     dragHandle?: boolean;
     /** Whether this card can't be picked up (column frozen, or the card itself is pinned). */
     disabled?: boolean;

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

@@ -20,8 +20,28 @@ export declare function moveColumn(columns: KanbanColumnDef[], activeColumnId: s
  * 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.
+ *
+ * A card drag also lets the pointer pick the column, and `closestCorners` only the position within
+ * it. Corners alone compare the dragged card's whole rect, so a wide card over a collapsed column
+ * had its corners nearer the neighbours' cards, and landed beside the column under the pointer.
+ * Without a pointer (the keyboard) or between columns, every column is a candidate as before.
  */
 export declare const kanbanCollisionDetection: CollisionDetection;
+/**
+ * Whether the auto-scroll may move `scroller`, an ancestor of the board such as the page, while
+ * something is dragged: only toward a part of the board that is out of view. Nothing beyond the
+ * board takes a drop, and a page left free to scroll carried the whole board off screen.
+ */
+export declare function scrollsTowardBoard(scroller: {
+    top: number;
+    bottom: number;
+}, board: {
+    top: number;
+    bottom: number;
+}, dragged: {
+    top: number;
+    height: number;
+}): boolean;
 /** 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 {
@@ -40,9 +60,35 @@ export interface DragGeometry {
  * position (see the two branches below for what each one decides).
  */
 export declare function moveItem(columns: KanbanColumnDef[], activeItemId: string, overId: string, geometry: DragGeometry): KanbanColumnDef[];
+/**
+ * Where a drag has put the dragged card or column so far. The board keeps this rather than a copy
+ * of `columns`, so a change the consumer makes mid-drag (a page appended by `onLoadMore`) still
+ * shows, and is still there in what `onChange` receives on drop.
+ */
+export interface DragPlacement {
+    /** The dragged card's or column's id. */
+    id: string;
+    /** The column the card sits in, or `null` while a whole column is dragged. */
+    columnId: string | null;
+    index: number;
+}
+/** The position `id` holds in `columns`, as a placement to lay over a later `columns`. */
+export declare function findPlacement(columns: KanbanColumnDef[], id: string, isColumn: boolean): DragPlacement | null;
+/**
+ * Moves the dragged card or column to its placement in `columns`. Returns `columns` itself when
+ * there is no placement, or when the card, the column, or its destination is no longer there.
+ */
+export declare function applyPlacement(columns: KanbanColumnDef[], placement: DragPlacement | null): KanbanColumnDef[];
+/**
+ * Where an arrow key moves focus from a focused card or column handle while nothing is picked up.
+ * It mirrors what the same keys do to a picked-up card: Up/Down within the column, Left/Right to
+ * the nearest card in the next column with anything to focus, or from a handle to the next handle.
+ * Returns `null` when `from` is not a card or handle, or there is nowhere to go.
+ */
+export declare function findArrowFocusTarget(board: HTMLElement, from: HTMLElement, key: string): HTMLElement | null;
 /**
  * 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).
+ * (the live 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;
 /**

package/docs/KanbanBoard.md

@@ -37,13 +37,14 @@ 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
+// Drag by a handle instead of the whole card: needed when a card contains its own
+// controls (buttons, inputs). The handle is also the card's keyboard handle, named
+// with getItemLabel, so the card is not one button wrapped around the Delete button
 <KanbanBoard
   columns={columns}
   items={items}
   dragHandle
+  getItemLabel={(task) => task.title}
   renderItem={(task, id) => (
     <div className="task-card">
       <span data-drag-handle>⠿</span>
@@ -128,18 +129,33 @@ const columnsWithLock: KanbanColumnDef[] = [
   onChange={(updatedColumns) => setColumns(updatedColumns)}
 />
 
-// Keep every column the same width regardless of card count — opt out of the
-// default shrink-when-empty behaviour
+// Shrink a column with no cards to a narrow strip. Widths hold still during a drag,
+// so a column the drag empties or fills changes width once the card is dropped
 <KanbanBoard
   columns={columns}
   items={items}
   renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
-  collapseEmptyColumns={false}
+  collapseEmptyColumns
   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
+// Fill the height your layout gives the board, like a full-screen board app: give the
+// board a height and each column scrolls on its own inside it. Here the board takes
+// what the header leaves of the window (minHeight: 0 lets a flex child shrink below
+// its content)
+<div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+  <AppHeader />
+  <KanbanBoard
+    columns={columns}
+    items={items}
+    renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+    style={{ flex: 1, minHeight: 0 }}
+    onChange={(updatedColumns) => setColumns(updatedColumns)}
+  />
+</div>
+
+// Or cap each column at a length, so a long column scrolls on its own instead of
+// growing the page, while a board of short columns stays short
 <KanbanBoard
   columns={columns}
   items={items}
@@ -148,12 +164,12 @@ const columnsWithLock: KanbanColumnDef[] = [
   onChange={(updatedColumns) => setColumns(updatedColumns)}
 />
 
-// Paginate a column instead of loading everything up front — mark it `hasMore`
+// 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.
+// bottom. Needs a column that scrolls: `columnMaxHeight` or a board with a height.
 // 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.
+// the bottom of the list) and asks again while a column's cards leave empty space
+// below them, so pagination doesn't dead-end on a short first batch.
 const columnsPaged: KanbanColumnDef[] = [
   { id: 'done', title: 'Done', itemIds: doneTaskIds, hasMore: doneHasMore },
 ];
@@ -171,10 +187,12 @@ const columnsPaged: KanbanColumnDef[] = [
 />
 ```
 
-**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).
+**Keyboard support:** cards are focusable, and the arrow keys move focus between them while nothing is picked up: Up/Down within a column, Left/Right to the nearest card in the next column. Space or Enter picks a card up, Space or Enter again drops it, and Escape cancels (reverts to the original position). While a card is picked up, the same arrow keys move the card instead: Up/Down reorders it within its 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`, each column's title is focusable too and joins the arrow-key navigation (Left/Right goes title to title, Up/Down between the title and the column's cards): Space/Enter picks the column up and Left/Right moves it. Keys pressed in a control inside a card or header, such as a `renderColumnActions` button or an input in a card, go to that control and never start a drag.
 
 **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.
 
+**Scrolling while dragging:** holding a card near the edge of a column's card list scrolls that list. The page scrolls only toward a part of the board that is out of view, and stops once the board's edge is on screen, since nothing outside the board takes a drop.
+
 **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:**
@@ -185,15 +203,15 @@ const columnsPaged: KanbanColumnDef[] = [
 | `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 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 |
+| `dragHandle` | `boolean` | Drag a card only by the element marked `data-drag-handle` inside it (mouse, touch and keyboard), instead of by the whole card. The board makes the handle focusable and names it with `getItemLabel` unless it has an `aria-label`, and the card stops being a button. Use when `renderItem` includes controls: without it the whole card is one button, its text can't be selected, and a screen reader reads controls inside it as plain text |
+| `getItemLabel` | `(item: T, id: string) => string` | Accessible label for a card, used in screen-reader drag announcements and as the name of a `dragHandle` handle without one. 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 |
+| `collapseEmptyColumns` | `boolean` | Shrink a column to a narrow strip while it has no cards (default `false`). Widths hold still during a drag: a column the drag empties or fills changes width after the drop. 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` | Caps each column's card list at a length (any CSS length, e.g. `'70vh'`), so a long column scrolls on its own instead of growing the page. Unset by default. To fill the space your layout gives the board instead, give the board a height (`style={{ height: '100%' }}` in a parent with one, or `flex: 1; min-height: 0` in a flex column): its columns then scroll the same way |
+| `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. Also called while the column's cards leave empty space below them. Paging all the way needs a column that scrolls (`columnMaxHeight` or a board with a height); on a board that grows with its cards, a short column only fills up to the tallest one |
 | `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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",