Kanban API Reference

API reference › The board (kanban) view

All 29 pages Everything on one page → Developer guide →

The board (kanban) view

modules/kanban is an opt-in view of grid rows as cards, grouped into columns by a configurable property - a status, a stage, a state GUID, whatever the host's schema calls it. It is a separate bundle in the same shape as charts and the data router: it adds no weight to a page that does not load it, changes nothing in grid core, and pulls in no dependency. A board is just another dataset viewer: it consumes data through the same keyed-diff contract a grid exposes, board.rows.apply({ add, update, remove }), so a Data Router can attach(value, board) and drive a kanban beside a grid and a chart off one feed. (Distinct from the grid-core board presentation mode, config.board in, which lays a single grid's rows out as lanes; this is a standalone view module.)

import { createKanban } from '@toclocoinc/lattice-grid/modules/kanban';

const board = createKanban(document.querySelector('#board'), {
  rows,                        // or { grid } to bind to a live grid; reuses its column formatters
  rowKey: 'id',
  columnProperty: 'status',    // the group-by property (configurable)
  columns: [                   // shown even when empty; this order is honoured
    { id: 'todo', title: 'To do' },
    { id: 'doing', title: 'In progress', wipLimit: 3 },
    { id: 'done', title: 'Done', color: '#2e7d32' },
  ],
  pointsProperty: 'points',    // configurable; drives the header points sum
  showPoints: true,
  card: { title: 'title', subtitle: 'assignee', labels: 'tags' },
  readonly: { columns: { done: true } },     // granular: whole board / per column / per card
  onCardClick: ({ card }) => open(card.row),
});

Every structural property is named in config - columnProperty, pointsProperty, orderProperty, swimlaneProperty, sprintProperty, epicProperty - so the same board maps any customer schema (a status field, points, sprint, epic, a swimlane) without code change. Configured columns show even when empty; a data value outside them gets its own column rather than being dropped. Each column header carries its card count and, with showPoints, its points sum, and is flagged when the count exceeds a column's wipLimit. Accessibility is built in: the board is a labelled group, each column a labelled list, each card a list item in a roving-tabindex focus ring with arrow-key navigation, and a polite live region is present for the move announcements a later cycle adds.

Drag-and-drop and keyboard move (write-back). Cards drag between columns (writing columnProperty) and within a column into a position (writing orderProperty with fractional ranking, so only the moved cards' order is written). The same move is available from the keyboard: focus a card, press Space to grab it, use the arrows to choose a target column and position (announced on a live region), Space/Enter to drop, Escape to cancel. Multi-select drags every selected card. A move calls onBeforeMove(card, from, to, index) first - return false (or a promise of it) to veto - then persists: grid-bound, through grid.edit.setCells (the same public edit-commit path inline editing and the write-back adapter use, so the grid's own pipeline owns the optimistic apply, the confirm and the revert); standalone, optimistically with a revert when onCardMove returns false/rejects. A configurable per-card contextMenu (an array or fn(card, selected)) replaces the card:contextmenu event when present.

Touch. The drag above is a pointer gesture, so cards, column headers and swimlane headers drag on phones and tablets as well as with a mouse. A mouse drag starts on movement; a touch or pen drag starts after a short press-and-hold - moving before the hold scrolls the board instead, so a quick swipe never accidentally moves a card. While a drag is held, the pointer auto-scrolls a board edge it sits within 24 px of, and Escape or a second finger cancels. A completed move still fires the same beforeMove/card:move events and the htmx lattice:kanban-change post, once per move.

Swimlanes, collapse, reorder and search. Set swimlanes: true to render a 2D lane×column grid grouped by swimlaneProperty: one band per lane with its own count/points, columns aligned across every lane, the board scrolling vertically through lanes and horizontally through columns inside its own box. A drag across lanes writes the swimlane property too. Columns and lanes collapse (their state survives a keyed-diff update); columns reorder by dragging their header (reorderColumns/moveColumn). setQuickFilter(text) searches across card fields, setFilter(fn) applies a predicate (sugar for filters.where(filters.DEFAULT, fn) - filters.where(name, fn) registers any number of independent named predicates, ANDed together), and facets(property) returns distinct-value counts to build a facet control. Naming the swimlaneProperty is separate from turning on the lane view, so a board can carry it for a cross-lane move without switching layout.

Sprint, epic and card pop-out. setSprint(id) shows one sprint, showBacklog() the cards with no sprint, and sprints() feeds a switcher; setEpic(id) narrows to an epic and epicRollup() (or rollup(property)) returns per-epic count, points and progress toward the done columns. A card can pop out a nested grid of its children - an epic's stories, a story's tasks, recursively. The child relationship is a childrenProperty (parent-id within the dataset) and/or a loadChildren(card) (per-card dataset or async fetch), and the child is a full composed createGrid (sort/filter/edit/write-back) - supplied as children.factory - opened in a drawer (default), modal or inline. With children.asBoard the child is itself a board, so it can pop its own children. This reuses the grid by composition and adds no grid-core coupling. expand(key) and the per-card drill affordance emit card:expand; a deeper open emits card:drill.

Live updates. Because the board consumes data through the same keyed-diff contract a grid does, a Data Router drives it directly - router.attach(board, predicate) - and one feed fans out to a grid, a kanban, a chart and a KPI tile at once. A live rows.apply({ add, update, remove }) is applied as a keyed diff (an unchanged card keeps its model) and re-rendered preserving scroll, focus, selection, collapsed columns/lanes and any open pop-out, so a card can appear, move or update under the user without losing their place.

Scale, state and accessibility. virtualize renders only a scroll window of a tall column (with true-height spacers so the scrollbar stays honest), for boards of thousands of cards. getState()/setState() (and config.state) save and restore the collapsed columns and lanes, the column order, the quick filter and the sprint/epic selection, so a reopened board comes back as it was; setLoading/setError add loading and error states. Accessibility runs throughout: the board is a labelled group of labelled column lists, cards are a roving-tabindex focus ring (arrows to move focus, Enter to activate), the move is fully keyboard-driven (Space grab, arrows for column/position, Alt+↑/↓ across swimlanes, Space/Enter drop, Escape cancel) with live-region announcements, and every affordance carries a name.

Column width. A board used to take a fixed --lattice-board-column-width (default 280px) on every column, so a three-column board left a wide host mostly empty and a page that computed the token from the viewport overflowed its host with a horizontal scrollbar. The columnWidth option fixes that: 'fill' (the default) shares the board width equally between the columns, never below minColumnWidth (240px), so a board that fits fills its host edge-to-edge and one that does not scrolls at the minimum; a number fixes every column at that many pixels; 'auto' keeps the natural token width. Collapsed columns stay narrow strips and the remaining columns take the freed space, and the board follows its host's resize. Setting --lattice-board-column-width on the host element still overrides. The resolved values are read back at board.columnWidth and board.minColumnWidth.

Card aging / SLA. A sla config ages each card and highlights the ones sitting too long. Thresholds are a raw millisecond count or a { days, hours, … } spec, set globally as { warn, breach }, per column (either sla.columns[id], or a column def's own sla/slaWarn/slaBreach) and per swimlane (sla.lanes[id]); the most specific wins, lane → column → global. basis chooses whether the clock is time-in-current-column (default) or age-on-the-board, resolved from the flow transition log, an enteredProperty/createdProperty timestamp, or arrival. The view puts an age chip on aged cards (showAge: 'always' shows it on every card) and a highlight on breached ones. A rising crossing (ok→warn, warn→breach) fires the card:sla event and the onWarn/onBreach(level, rows) callbacks - the same (signal, rows) shape a Data Router alert route uses, so one handler serves both. It is reached at runtime as board.sla; done-column cards are exempt by default (ignoreDone: false opts them in), and an optional tick re-checks so a card that breaches by simply sitting still still lights up. Example: createKanban(el, { …, sla: { warn: { days: 2 }, breach: { days: 4 }, onBreach: notify } }).

Inline edit and add-card. A field is opted into inline edit with the object mapping form - card: { title: { field: 'title', edit: true } }. Double-clicking a card (or editCard(key, field)) edits it in place: grid-bound, through the grid's own field editor for that column via its public edit path, so the column's parse, validate and optimistic/confirm/revert all run; standalone, through a host editor factory (or a default input), reverting when onCardEdit rejects. A per-column add-card affordance (config.addCard) creates a card carrying the column's group value - from a host onAddCard(columnId), or generated, or appended through grid.edit.addRow when bound - and opens it straight in inline edit on its title, so the user just types. The module imports nothing from the grid's DOM package: grid-bound edits ride the grid's public edit API, standalone edits use the host's editor, so a board-only page never pulls the grid in.

Blocked cards and dependencies. A card can be blocked outright, or blocked by other cards. blockedProperty names a row field that blocks a card - a boolean flag, or a reason string whose non-empty value is the reason the blocked badge shows (with an icon and a warning-tone chip, and an accessible name, so it is never colour alone). blockedByProperty names the field holding the keys of the cards that block this one (a comma-separated string or an array); the card then shows a "blocked by N" list of focusable chips, each one focusing (opening) its blocking card, and flips to a ready state once every blocker is in a done column. A blocked filter - setBlockedFilter(true), or blockedFilter: true at construction - shows only blocked cards (a card with an unresolved blocker counts as blocked). Blocking and unblocking run through setBlocked(key, blocked, reason?) (or toggleBlocked(key)), which raise card:edit with field: 'blocked' like any other edit, and a blocked card is refused any forward move (a move into a column to its right). The flow analytics record blocked intervals and report board.flow.blockedTime(), board.flow.flowEfficiency() (active time / cycle time) and board.flow.blockedTimeByColumn(), so a cycle time that was really time waiting on someone else stops looking like active work.

Blocked cards and dependencies, executed

An explicit block with a reason, a dependency on another card, the blocked filter, and a blocker resolving to ready - headless, run on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 'a', status: 'todo', title: 'A' },
    { id: 'b', status: 'todo', title: 'B', blockedBy: 'a' },          // blocked by card a
    { id: 'c', status: 'doing', title: 'C', blocked: 'Waiting on design' }, // explicit reason
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done', done: true }],
  blockedProperty: 'blocked',
  blockedByProperty: 'blockedBy',
  blockedFilter: true,                                    // start filtered to blocked cards
  card: { title: 'title' },
});

board.setBlockedFilter(false);                            // clear it (only b and c were shown)
const c = board.card('c');
const badge = c.blocked + ' ' + c.blockedReason;         // true Waiting on design
const b = board.card('b');
const deps = b.blockedBy.join(',') + ' ' + b.blocked;    // a true (a is not done yet)

board.setBlockedFilter(true);
const filtered = board.model.cardsByKey.size;            // 2 (b and c)
board.setBlockedFilter(false);

await board.setBlocked('c', false);                      // unblock C
const cleared = board.card('c').explicitBlocked;         // false
await board.toggleBlocked('c', 'oops');                 // re-block C
const toggled = board.card('c').blocked;                 // true

await board.move('a', 'done');                           // resolve B's blocker
const ready = board.card('b').ready;                     // true

board.destroy();
return [badge, deps, filtered, cleared, toggled, ready].join(' | ');

Richer card parts. Beyond title/subtitle/labels, the card mapping takes four built-in parts, each optional and each folded into the card's accessible name: assignee - one or several people (a name, a comma-separated string, or an array of { name, avatar } objects) drawn with the avatar component the Gantt has used since 1.88, image with an initials fallback coloured from the name, and a +N overflow beyond max (default 2); due - a date field shown in the grid's date format when bound, with a due-soon/overdue state and icon from a dueSoon day threshold (card: { due: { field: 'due', dueSoon: 3 } }); progress - a 0..1 fraction or 0..100 value as a thin bar; and checklist - a { done, total } object or two named fields, shown as 3/5. A bound grid's own formatters are reused, and board search matches assignee names. density: 'compact' tightens each card (less padding, no subtitle) so a column fits more cards; the default 'comfortable' keeps the roomier card.

Undo and redo. Every user move (a drag, a reorder, a lane change), add and inline edit is one undo step - a multi-card drag is one step, because it reaches move() once with every key it carries. board.undo() re-runs the inverse through the board's own write path (the workflow rules, the onBeforeMove/onBeforeEdit veto, the WIP rules and the confirm/revert pipeline still run, so a refused undo leaves the card and the history unchanged and logs a catalogued warning); board.redo() re-applies, and canUndo()/canRedo() report the stacks, with a history event ({ canUndo, canRedo, label }) on every change. Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z undo and redo while the board has focus (the shortcut stands aside inside a text field). historyDepth caps the steps kept (default 100, 0 turns undo off). On a grid-bound board the board shares the grid's timeline, so one Ctrl+Z order covers a grid edit and a board move; host loads through rows.apply are never undoable.

A board, grouped and aggregated, executed

A customer-shaped set - statuses as columns, points, an empty configured column, a WIP limit, and one status outside the configured set - grouped headless, then a keyed diff applied through the same rows.apply contract the Data Router drives. Run on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 'a', status: 'todo', points: 3, title: 'Login form' },
    { id: 'b', status: 'doing', points: 5, title: 'OAuth' },
    { id: 'c', status: 'doing', points: 2, title: 'Reset flow' },
    { id: 'd', status: 'done', points: 8, title: 'Audit log' },
    { id: 'z', status: 'archived', points: 1, title: 'Old ticket' }, // outside the configured columns
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [
    { id: 'todo', title: 'To do' },
    { id: 'doing', title: 'In progress', wipLimit: 1 },
    { id: 'done', title: 'Done' },
    { id: 'blocked', title: 'Blocked' },   // configured but empty; still shown
  ],
  pointsProperty: 'points',
  card: { title: 'title' },
});

const todo = board.count('todo') + '/' + board.points('todo');       // 1/3
const doing = board.count('doing') + '/' + board.points('doing');    // 2/7
const over = board.column('doing').over ? 'over' : 'ok';             // over the WIP limit of 1
const extra = board.column('archived') ? 'archived' : 'dropped';     // an out-of-set value is kept

// The keyed-diff consumer contract a Data Router drives: move b to done, drop c.
board.rows.apply({ update: [{ id: 'b', status: 'done', points: 5, title: 'OAuth' }], remove: ['c'] });
const done = board.count('done') + '/' + board.points('done');       // 2/13

board.destroy();
return [todo, doing, over, extra, done].join(' | ');

Move, reorder and veto, executed

The move path drag-and-drop and keyboard move share: a reorder writes the order property with fractional ranking, a cross-column move writes the column property, and onBeforeMove can veto. Run headless on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 'a', status: 'todo', ord: 1, title: 'A' },
    { id: 'b', status: 'todo', ord: 2, title: 'B' },
    { id: 'c', status: 'todo', ord: 3, title: 'C' },
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done' }],
  orderProperty: 'ord',
  // Veto any move into 'doing'; allow the rest.
  onBeforeMove: (card, from, to) => to !== 'doing',
});

await board.move('c', 'todo', 0);          // reorder C to the top of todo
const order = board.column('todo').cards.map((x) => x.key).join(',');  // c,a,b

await board.move('a', 'done');             // cross-column move writes the column
const moved = board.card('a').columnId;    // done

await board.move('b', 'doing');            // vetoed by onBeforeMove
const vetoed = board.card('b').columnId;   // still todo

return [order, moved, vetoed].join(' | ');

Workflow rules. Two optional config maps make the board enforce a workflow before a move persists, and both run first - before onBeforeMove, before the write-back, before any confirm or revert. transitions maps a source column id to the destination column ids it may move to (a list, or '*' for any); a source absent from the map may move anywhere, so a board that never configures rules stays exactly as permissive as it was. require maps a destination column id to the row properties a card must carry to enter it ({ field, label?, editor? }). A drag over a disallowed column shows it not droppable (dropEffect none, aria-dropeffect="none") and the keyboard move skips it; a drop into a column whose required fields are missing opens a small form, and the move commits only once the values are filled (cancel reverts). A programmatic board.move honours the same rules and fails with a catalogued [lattice] error naming the rule. Either map may also be declared on a lane (config.lanes[i].transitions / .require), overriding the board per key.

Workflow rules, executed

A transition map that gates movement between columns and a required field on done - the refused programmatic moves name their rule, and a card that already carries the required value moves through. Run headless on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 1, status: 'todo', title: 'A' },
    { id: 2, status: 'doing', title: 'B', deployed: '2026-01-01' },
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done' }],
  card: { title: 'title' },
  transitions: { todo: ['doing'], doing: ['done'] },   // todo may only reach doing
  require: { done: [{ field: 'deployed', label: 'Deployed' }] },
});

let transition = 'no';
try { await board.move(1, 'done'); }                       // todo → done is not in todo's map
catch (err) { transition = /kanban\.transition/.test(err.message) ? 'transition' : err.message; }

let required = 'no';
await board.move(1, 'doing');                            // todo → doing is allowed
try { await board.move(1, 'done'); }                  // but done requires `deployed`
catch (err) { required = /kanban\.require/.test(err.message) ? 'require' : err.message; }

const moved = (await board.move(2, 'done')).moved.length;  // 1 - card 2 already carries it

board.destroy();
return [transition, required, moved].join(' | ');

Swimlanes, collapse and search, executed

Lanes with per-lane aggregates, a collapsed column, a reorder, and a quick-filter - all headless, run on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 1, status: 'todo', assignee: 'Ann', points: 3, title: 'Login' },
    { id: 2, status: 'doing', assignee: 'Ann', points: 5, title: 'OAuth' },
    { id: 3, status: 'doing', assignee: 'Bob', points: 2, title: 'Reset' },
    { id: 4, status: 'done', assignee: 'Bob', points: 8, title: 'Audit' },
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done' }],
  swimlaneProperty: 'assignee',
  swimlanes: true,
  pointsProperty: 'points',
  card: { title: 'title' },
});

const ann = board.model.lanes.find((l) => l.id === 'Ann');
const lane = 'Ann ' + ann.count + '/' + ann.points;   // Ann 2/8

board.reorderColumns(['done', 'todo', 'doing']);
const order = board.columns().map((c) => c.id).join(',');  // done,todo,doing

board.setQuickFilter('reset');
const shown = board.model.cardsByKey.size;             // 1 (only "Reset" matches)

return [lane, order, shown].join(' | ');

Richer card parts, executed

Assignee avatars, a progress bar, a checklist count, an overdue due date, the compact density and a search that matches an assignee's name - resolved headless, run on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 1, status: 'todo', title: 'Ship', assignee: [{ name: 'Ann' }, 'Bo Chen'], pct: 0.4, ck: { done: 3, total: 5 } },
    { id: 2, status: 'todo', title: 'Late', assignee: ['Cy'], due: new Date(Date.now() - 86400000).toISOString() },
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }],
  density: 'compact',
  card: { title: 'title', assignee: 'assignee', progress: 'pct', checklist: 'ck', due: { field: 'due', dueSoon: 3 } },
});

const card = board.card(1);
const overdue = board.card(2).due.state;                     // overdue
board.setQuickFilter('Ann');                                    // search matches an assignee name
const shown = board.model.cardsByKey.size;                    // 1 (only "Ship")

board.destroy();
return [card.assignees.length, card.progressPct, card.checklist.done + '/' + card.checklist.total, overdue, shown].join(' | ');

Label and badge tones, and a due format, executed

A label or badge tone (a map from value to accent, info, success, warning, danger or neutral, or a function of the row) draws the chip in the theme's variant roles; a due format (a date pattern or a function) sets the chip text. Unmapped values stay neutral and raw - resolved headless, run on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 1, status: 'todo', title: 'Ship', tags: 'bug, ok, misc', due: '2026-03-05T12:00:00' },
    { id: 2, status: 'todo', title: 'Fix', tags: 'bug', due: '2026-03-05T12:00:00' },
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }],
  card: {
    title: 'title',
    labels: { field: 'tags', tone: { bug: 'danger', ok: 'success' } },
    due: { field: 'due', format: 'MMM d', locale: 'en-US' },
  },
});
const tones = board.card(1).labelTones;
const text = board.card(1).due.text;

board.destroy();
const plain = createKanban(null, {
  rows: [{ id: 1, status: 'todo', due: '2026-03-05T12:00:00' }],
  rowKey: 'id', columnProperty: 'status', columns: [{ id: 'todo' }],
  card: { due: { field: 'due', format: (d) => 'due ' + d.getFullYear() } },
});
const fn = plain.card(1).due.text;
plain.destroy();
return [tones.bug, tones.ok, tones.misc || 'none', text, fn].join(' | ');

Column width, executed

The columnWidth and minColumnWidth options resolve to fill (default), a fixed pixel width, auto, and a raised minimum - headless, run on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const base = createKanban(null, {
  rows: [], rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done' }],
});

const fixed = createKanban(null, {
  rows: [], rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }], columnWidth: 300,
});

const auto = createKanban(null, {
  rows: [], rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }], columnWidth: 'auto',
});

const wide = createKanban(null, {
  rows: [], rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }], minColumnWidth: 200,
});

return [base.columnWidth, base.minColumnWidth, fixed.columnWidth, auto.columnWidth, wide.minColumnWidth].join(' | ');

Sprint, backlog and epic rollup, executed

A sprint view, the backlog, and an epic rollup with progress toward the done column - headless, run on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 's1', status: 'todo', epic: 'E', sprint: 'S1', points: 3, title: 'Story 1' },
    { id: 's2', status: 'done', epic: 'E', sprint: 'S1', points: 5, title: 'Story 2' },
    { id: 's3', status: 'todo', epic: 'E', sprint: null, points: 2, title: 'Story 3' },
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'done', done: true }],
  pointsProperty: 'points',
  sprintProperty: 'sprint',
  epicProperty: 'epic',
});

board.setSprint('S1');
const inSprint = board.model.cardsByKey.size;   // 2 (s1, s2 are in S1; s3 has no sprint)
board.showBacklog();
const backlog = board.model.cardsByKey.size;    // 1 (s3)
board.setSprint(undefined);

const e = board.epicRollup()[0];
const rollup = e.points + ' ' + e.progress;      // 10 0.5

return [inSprint, backlog, rollup].join(' | ');

Live, driven by a Data Router, executed

One feed, routed to a board through the same keyed-diff contract a grid uses: a snapshot hydrates it and a delta moves a card. Run headless on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');
const { createDataRouter } = await import('../packages/modules/data-router/index.js');

const board = createKanban(null, {
  rows: [], rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'done' }], card: { title: 'title' },
});

const router = createDataRouter({ key: 'kind', rowKey: 'id' });
router.attach(board, 'task');                // the board is a drop-in router target
router.load([
  { id: 't1', kind: 'task', status: 'todo', title: 'T1' },
  { id: 't2', kind: 'task', status: 'done', title: 'T2' },
]);
const hydrated = board.count('todo') + ',' + board.count('done');   // 1,1

router.apply([{ op: 'upsert', row: { id: 't1', kind: 'task', status: 'done', title: 'T1' } }]);
const afterDelta = board.count('todo') + ',' + board.count('done'); // 0,2

router.destroy();
return [hydrated, afterDelta].join(' | ');

Re-bound to a replacement grid, executed

A grid-bound board, pointed at a replacement grid through rebind(grid) - the same call the htmx module's re-bind pass makes after a swap. Run headless on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');
const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  rowKey: 'id', columns: [{ field: 'title' }, { field: 'status' }],
  rows: [{ id: 1, title: 'A', status: 'todo' }],
});
const board = createKanban(null, {
  grid, columnProperty: 'status', columns: [{ id: 'todo' }, { id: 'done' }], card: { title: 'title' },
});
const before = board.cards().map((c) => c.fields.title).join(',');   // A

const replacement = createHeadlessGrid({
  rowKey: 'id', columns: [{ field: 'title' }, { field: 'status' }],
  rows: [{ id: 2, title: 'X', status: 'todo' }],
});
board.rebind(replacement);
const after = board.cards().map((c) => c.fields.title).join(',');    // X

return before + ' | ' + after;

Undo and redo, executed

A move is one undo step: undo() returns the card to its column and position, redo() re-applies it, and canUndo()/canRedo() report the stacks, capped by historyDepth. Run headless on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');

const board = createKanban(null, {
  rows: [
    { id: 'a', status: 'todo', ord: 1, title: 'A' },
    { id: 'b', status: 'todo', ord: 2, title: 'B' },
  ],
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'done' }],
  orderProperty: 'ord',
  historyDepth: 5,                    // keep five undo steps (default 100)
});

await board.move('a', 'done');                 // one undo step
const moved = board.card('a').columnId;        // done
const can = (board.canUndo() ? 'yes' : 'no') + '/' + (board.canRedo() ? 'yes' : 'no');  // yes/no

await board.undo();                           // a returns to todo, its position restored
const undone = board.card('a').columnId;       // todo

await board.redo();                           // re-apply the move
const redone = board.card('a').columnId;       // done

board.destroy();
return [moved, can, undone, redone].join(' | ');

A server-side board, executed

A board bound to the same pushdown source a grid takes: the column count and points sum come from an engine GROUP BY, cards load one pageSize at a time (loadMore fetches the next page), and a move writes through the source's update path. Run headless on every build.

const { createKanban } = await import('../packages/modules/kanban/index.js');
const { createPushdownSource } = await import('../packages/core/src/index.js');

const rows = [
  { id: 1, status: 'todo', points: 1, title: 'A' },
  { id: 2, status: 'todo', points: 2, title: 'B' },
  { id: 3, status: 'todo', points: 3, title: 'C' },
  { id: 4, status: 'todo', points: 4, title: 'D' },
  { id: 5, status: 'todo', points: 5, title: 'E' },
  { id: 6, status: 'done', points: 6, title: 'F' },
  { id: 7, status: 'done', points: 7, title: 'G' },
];

// A mock pushdown adapter over rows: pages the fetch, groups the totals.
const adapter = {
  capabilities: {
    filter: true, operators: ['eq', 'and'], quick: true, range: true, total: true, group: true,
    mutate: { update: true, returning: 'row' },
  },
  async execute(query) {
    const tree = query.filters;
    const eq = tree && Array.isArray(tree.conditions) ? tree.conditions.find((c) => c.op === 'eq') : tree;
    const col = eq && eq.value;
    const matched = rows.filter((r) => col === undefined || r.status === col);
    const start = query.range ? query.range.start : 0;
    const end = query.range ? Math.min(query.range.end, matched.length) : matched.length;
    return { rows: matched.slice(start, end), total: matched.length };
  },
  async executeGroupedAggregates(query, groupBy, aggs) {
    const by = new Map();
    for (const r of rows) {
      const keys = groupBy.map((g) => r[g]);
      const k = JSON.stringify(keys);
      if (!by.has(k)) by.set(k, { keys, rows: [] });
      by.get(k).rows.push(r);
    }
    return [...by.values()].map(({ keys, rows: bucket }) => ({
      keys,
      level: groupBy.length,
      values: Object.fromEntries(aggs.map((a) => [a.id,
        a.fn === 'count' ? bucket.length : bucket.reduce((t, r) => t + r[a.col], 0)])),
    }));
  },
  async mutate(op) {
    const r = rows.find((x) => String(x.id) === op.key);
    if (r) Object.assign(r, op.patch);
    return { keys: [op.key], rows: [r] };
  },
};

const source = createPushdownSource({ adapter, pageSize: 2, aggregates: { default: 'engine' }, edit: true });

const board = createKanban(null, {
  source,
  rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo', title: 'To do', wipLimit: 2 }, { id: 'done', title: 'Done' }],
  pointsProperty: 'points',
  card: { title: 'title' },
  pageSize: 2,
  transitionLog: [],      // the source-supplied transition log enables flow analytics
});

await new Promise((r) => setTimeout(r, 20));  // the construction load settles

const count = board.count('todo');                // 5 - the engine GROUP BY, not the 2 loaded
const cards = board.column('todo').cards.length;   // 2 - the first page
const over = board.column('todo').over;           // true - 5 > the WIP limit of 2
const more = await board.loadMore('todo');        // true - another page was fetched
const cardsAfter = board.column('todo').cards.length;  // 4
const reloaded = await board.reload();          // reload re-queries the engine totals
const isBoard = reloaded === board;
const flow = board.flowAvailable;                // true - the transitionLog is supplied

board.destroy();
return [count, cards, over, more, cardsAfter, isBoard, flow].join(' | ');

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

The kanban module

KanbanCard

A card model - one row as it appears on the board. `fields` holds the resolved display text for each mapped card field; `columnId` is the column the card sits in; `points` is the numeric points value (0 when absent). `swimlane`/`sprint`/`epic`/`order` are read from their configured properties and carried for the later cycles that render them.

KanbanColumn

A column with its cards and aggregates. `over` is true when `count` exceeds `wipLimit`.

KanbanEditor

A card field editor handle returned by a host editor factory.

KanbanRequiredField

A required-field rule: the row property a card must carry before it may enter a column, shown in the fill-in form when missing.

KanbanCardMap

The field-to-property mapping that drives the card template.

KanbanEvent

The payload of the three card pointer events - `card:click`, `card:dblclick` and `card:contextmenu`. The board's other events carry their own shapes; {@link KanbanEventPayloads} names one per event.

KanbanSlaConfig

Card-aging / SLA configuration. A card is measured against a `warn` and a `breach` threshold; the view puts an age chip on aged cards and a highlight on breached ones, and a rising crossing fires the `card:sla` event and the matching `onWarn`/`onBreach` callback (signature `(level, rows)`, the Data Router alert handler's). Thresholds resolve most-specific-first: lane → column → global. Reached at runtime as {@link Kanban#sla}.

KanbanSlaState

The computed SLA state of one card.

KanbanSla

The card-aging / SLA monitor, reached as {@link Kanban#sla} when a `sla` config is supplied. Pure and DOM-free: it computes each card's ageing state from the board's card model and the flow transition log, and the view paints it.

KanbanFlowDurationStats

Distribution stats over a set of durations, in milliseconds - the shape {@link KanbanFlow.cycleTime} and {@link KanbanFlow.leadTime} return. `null` throughout when there is nothing to summarise (`count` is then 0).

KanbanFlowCfd

The cumulative-flow series {@link KanbanFlow.cfd} returns: at each bucket boundary, how many cards sat in each column, plus the WIP and done totals.

KanbanFlow

Flow analytics over a board's transition log: how long a card takes from start to finish (cycle time), from arrival to finish (lead time), and how the shape of the board has changed over time (the cumulative-flow diagram). Reached as {@link Kanban#flow}.

KanbanConfig

Kanban configuration. Every structural property is named here so the same board maps any customer schema (a status field, `points`, `sprint`, `epic`, a swimlane property) without code change. Theme: no `theme` of its own - it inherits. Its colours are the grid's `--lattice-*` tokens, so `data-theme="dark"` on any ancestor (a layout's `theme: 'dark'`, or `<html>`) darkens it with everything else, and the nearest `data-theme` wins. Load the grid stylesheet, which carries the tokens.

KanbanChildren

KanbanMenuItem

One context-menu item. `action` receives the card, the selected cards, and the board.

KanbanMoveEvent

The payload of a `card:move` (and `card:reverted`) event.

KanbanHistoryStep

The outcome of one board undo/redo step.

KanbanHistoryEvent

`history`: the undo/redo stacks moved.

KanbanBeforeEvent

The members every cancellable board before-event carries.

KanbanCardEditEvent

`card:edit` and `beforeEdit`: one field of one card.

KanbanBeforeEditEvent

`beforeEdit`: an inline card edit is about to be written.

KanbanEditCancelledEvent

`edit:cancelled`: a `beforeEdit` handler refused the write.

KanbanCardAddEvent

`card:add`: a card was appended to a column.

KanbanBeforeAddEvent

`beforeAdd`: a card is about to be appended.

KanbanAddCancelledEvent

`add:cancelled`: a `beforeAdd` handler refused the append.

KanbanBeforeMoveEvent

`beforeMove`: one card of a move is about to be applied; raised once per card.

KanbanMoveCancelledEvent

`move:cancelled`: a `beforeMove` handler refused one card of a move.

KanbanCardRevertedEvent

`card:reverted`: a move did not stick - the bound grid refused the write, an `onCardMove` callback returned false, or the server reverted the cell.

KanbanCardConfirmedEvent

`card:confirmed`: the grid confirmed the column write behind an optimistic move.

KanbanSelectionEvent

`selection:changed`: the selected cards changed.

KanbanColumnCollapseEvent

`column:collapse`: a column was collapsed or expanded.

KanbanBeforeColumnChangeEvent

`beforeColumnChange`: a column is about to be collapsed or expanded.

KanbanColumnChangeCancelledEvent

`columnChange:cancelled`: a `beforeColumnChange` handler refused it.

KanbanSwimlaneCollapseEvent

`swimlane:collapse`: a swimlane was collapsed or expanded.

KanbanOrderEvent

`column:reorder` and `swimlane:reorder`: the order the board draws them in.

KanbanBeforeOrderEvent

`beforeColumnReorder` and `beforeLaneReorder`: an order is about to be applied.

KanbanOrderCancelledEvent

`columnReorder:cancelled` and `laneReorder:cancelled`: a handler refused the order.

KanbanFilterChangedEvent

`filter:changed`: the quick filter or a named predicate changed.

KanbanSprintChangedEvent

`sprint:changed`: the shown sprint changed.

KanbanEpicChangedEvent

`epic:changed`: the shown epic changed.

KanbanCardExpandEvent

`card:expand`: a card's children were opened.

KanbanCardDrillEvent

`card:drill`: a card was expanded from inside an already-open detail.

KanbanDragStartEvent

`drag:start`: a card drag began.

KanbanDragEndEvent

`drag:end`: a card drag ended, whether or not it dropped on a column.

KanbanSlaEvent

`card:sla`: a card crossed an ageing threshold.

KanbanCardsLoadedEvent

The payload of the `cards:loaded` event: a page of cards has been fetched from the bound pushdown source for one column (and, in swimlane mode, one lane).

KanbanEventPayloads

What a handler receives, per board event.

KanbanRows

The keyed-diff consumer surface a board shares with a grid, so a Data Router routes to it directly.

KanbanFilters

Named card predicates, composed with AND, following the grid's `filters.where` convention. Several may be registered under different names at once; each can be replaced or removed without touching the others. `setFilter(fn)` is unchanged sugar for `where(DEFAULT, fn)` / `where(DEFAULT, null)`.

Kanban

A board instance: a kanban view of grid rows as cards grouped into columns. It consumes data through the same keyed-diff `rows.apply` contract a grid exposes, so `dataRouter.attach(value, board)` drives it like any other viewer.

Properties

Methods

Events