Kanban API

Complete API reference for @oge-ui/kanban. The kernel — card normalization and write-back, the drag hit-testing, per-column virtual windows, the WIP arithmetic, the keyboard and move machines — is the framework-free @oge-ui/kanban-engine, shared with the React board; live demos are on the overview page.

Properties Methods Events Types

OgeKanban

oge-kanban

Properties 20

Data

Name	Type	Default	Description
`dataSource`	`readonly T[]`	`[]`	Card items — a plain array, copied into an internal working set; the input is never mutated. Edits surface through the past-tense events.
`keyExpr / columnExpr / titleExpr / descriptionExpr / colorExpr`	`string \| ((item: T) => unknown)`	`'id' / 'status' / 'title' / 'description' / 'color'`	Card field mapping: names (dotted paths reach nested objects) or getter functions. `columnExpr` holds the card's column key; a card with no resolvable column lands in the untitled column instead of being dropped.
`orderExpr`	`string \| ((item: T) => unknown) \| undefined`	`undefined`	Numeric in-column sort order. Unset, the array order is the board order and moves reorder the working set; set, moves write a midpoint order value back onto the item (sequential renumber of the cell when the midpoint has no room).
`swimlaneExpr`	`string \| ((item: T) => unknown) \| undefined`	`undefined`	Set = the board renders collapsible swimlane rows (first-seen data order); each lane holds every column.
`tagsExpr / assigneeExpr`	`string \| ((item: T) => unknown) \| undefined`	`undefined`	Tag chips and assignee avatars (initials). Both accept a single value or an array — write-back preserves the storage shape.
`dueDateExpr / priorityExpr`	`string \| ((item: T) => unknown) \| undefined`	`undefined`	Due-date badge (danger when overdue; formatted through `locale`) and the priority indicator (colored by value: `'low'` green, `'medium'`/`'normal'` amber, `'high'`/`'urgent'`/`'critical'` red).
`searchExprs`	`readonly (string \| ((item: T) => unknown))[] \| undefined`	`undefined`	Extra fields the toolbar search matches, beyond the built-in title + description + tags + assignees haystack. Matching is fold-insensitive (accents, Turkish İ/i).
`columns`	`readonly OgeKanbanColumn[] \| undefined`	`undefined`	Declared columns (`{ key, title?, color?, wipLimit?, minCount?, collapsed?, allowAdding?, allowDrag?, allowDrop?, transitionColumns? }`); unset = derived from the data's distinct column keys in first-seen order. Cards in undeclared columns stay in the data but leave the view.

State (two-way)

Name	Type	Default	Description
`collapsedColumns / collapsedSwimlanes`	`model<readonly string[]>`	`[]`	Collapsed column keys (slim vertical pills) and collapsed swimlane keys.
`columnOrder`	`model<readonly string[]>`	`[]`	Persisted column key order (empty = declared order); written by header drags when `allowColumnReordering` is on.
`selectedCardKey`	`model<unknown>`	`null`	The selected card's key — single selection.

Behavior

Name	Type	Default	Description
`virtualScrolling`	`boolean`	`true`	Per-column card windowing over a fixed `cardHeight` — 10k cards stay smooth. Rich variable-height templates may opt out (`false`), the documented exception.
`cardHeight`	`number \| undefined`	`undefined (config: 112)`	Fixed card height in px; also drives the drag hit-testing and the keyboard scroll-into-view math.
`showToolbar`	`boolean`	`true`	The built-in toolbar: primary add button, collapse/expand-all pill and the search box.
`allowAdding / allowUpdating / allowDeleting / allowDragging / allowColumnReordering / allowColumnAdding`	`boolean`	`true / true / true / true / false / false`	Capability gates for the toolbar, dialog, menu, hover quick actions, keyboard shortcuts and drags. `allowColumnAdding` renders the "+ Add column" ghost column (inline composer → cancelable `columnAdding` → `columnAdded`). Per-column `allowAdding: false` overrides the board.
`columnWidth`	`number`	`300`	Fixed column track width in px — headers stay legible and the board scrolls horizontally, Trello-style.
`cardColorMode`	`'stripe' \| 'surface'`	`'stripe'`	How `colorExpr` renders: an accent bar on the card's edge, or the whole card surface tinted with the color.
`dialogItems`	`readonly OgeFormItemData[] \| undefined`	`undefined`	Replaces the edit dialog's default form wholesale (generic `OgeForm` items); `cardEditDialogShowing` can still adjust per open. The default form only renders editors for fields the board actually maps.
`readOnly`	`boolean`	`false`	One switch over every `allow*` capability; the context menu falls back to the browser's native menu.
`messages / locale`	`Partial<OgeKanbanMessages> / string \| undefined`	`{} / undefined`	Per-instance overrides of the DI config (`provideOgeKanbanConfig`). Every user-facing string, aria labels and live-region templates included, lives in the messages interface; `locale` drives every Intl format.

Methods 7

Methods

Name	Type	Description
`addCard(item)`	`(item: T) => void`	Programmatic insert through the cancelable `cardAdding` pipeline; the column and swimlane resolve from the item's own fields.
`updateCard(original, updated)`	`(original: T, updated: T) => void`	Programmatic update through the cancelable `cardUpdating` pipeline.
`deleteCard(item)`	`(item: T) => void`	Programmatic delete through the cancelable `cardDeleting` pipeline.
`moveCard(key, toColumn, toIndex?, toSwimlane?)`	`(key: unknown, toColumn: string, toIndex?: number, toSwimlane?: string \| null) => void`	Moves a card (append when `toIndex` is omitted) through the cancelable `cardMoving` pipeline — the same path the drag, the Ctrl+Arrow twin and the context menu commit through.
`editCard(card) / openNewCard(column, swimlane)`	`(…) => void`	Opens the built-in dialog for an existing card / prefilled for a new card, through the `cardEditDialogShowing` hook.
`closeDialog()`	`() => void`	Closes the edit dialog without saving; fires `cardEditDialogHidden`.
`collapseAllColumns() / expandAllColumns()`	`() => void`	The toolbar buttons, callable from code.

Events 7

Events

Name	Type	Description
`cardClick / cardDblClick / cardContextMenu`	`OgeKanbanCardEvent<T>`	Pointer interactions with a card (`{ card, event }`). Double-click also opens the editor; right-click fires before the built-in menu opens, so app handlers can coexist with it.
`cardAdding / cardUpdating / cardDeleting / cardMoving`	`Oge…Event<T> (mutable cancel)`	Cancelable pre-events — set `cancel = true` to veto. `cardMoving` carries `{ card, fromColumn, toColumn, fromIndex, toIndex, fromSwimlane, toSwimlane }` and guards drags, keyboard moves and programmatic moves alike.
`cardAdded / cardUpdated / cardDeleted / cardMoved`	`Oge…Event<T>`	Past-tense events fire only for applied changes and carry the data to persist (`cardMoved.card` is the updated item, orderExpr write-back included).
`cardEditDialogShowing`	`OgeKanbanEditDialogShowingEvent<T>`	Cancelable + customization point before the dialog opens: `formItems` arrives pre-populated with the default `OgeForm` items and may be mutated or replaced (dx `onAppointmentFormOpening` parity).
`cardEditDialogHidden`	`void`	The edit dialog closed — saved, cancelled, deleted or `closeDialog()` (Syncfusion `dialogClose` parity).
`columnReordered`	`OgeKanbanColumnReorderedEvent`	A header drag committed a new order: `{ column, fromIndex, toIndex, columnOrder }`.
`columnAdding / columnAdded`	`OgeKanbanColumnAddingEvent / OgeKanbanColumnAddedEvent`	The "+ Add column" composer's cancelable pre-event and its past-tense commit.

Types 7

Templates

Name	Type	Description
`*ogeKanbanCardTemplate`	`OgeKanbanCardTemplateContext<T>`	Replaces the card body (`$implicit` card with its `source`, plus `column` and `swimlane`). Drag, keyboard and ARIA stay on the component. Buttons, links and inputs in the template are real interactive content: Tab reaches them while the card is its column's tab stop, they never start a drag or feed the board's arrow keys, and Escape returns to the card.
`*ogeKanbanColumnHeaderTemplate`	`OgeKanbanColumnHeaderTemplateContext`	Replaces the column header's title row (`$implicit` column, `count`, `wip`); the collapse affordance stays. An OGE extra — no reference library templates its headers.

Configuration

Name	Type	Description
`provideOgeKanbanConfig(config)`	`(config: OgeKanbanConfigInput) => Provider`	DI-level configuration: `messages` (shallow-merged per top-level block), `locale`, `cardHeight`.
`OgeKanbanMessages`	`interface`	Every user-facing string: `toolbar`, `menu`, `dialog`, `board` (aria label templates with `{title}`/`{count}`/`{limit}` tokens) and `announcements` (live-region templates).
`OgeKanbanBoardMessages`	`interface`	The `board` block: `boardLabel`, `columnLabel` / `columnLabelWip` (the column list's name), `cardLabel` (`{title}`, `{column}`), `cardRoleDescription` (default `card` — every card's `aria-roledescription`), `editCardAction` / `deleteCardAction` (the quick-action buttons, `{title}`), `boardHint`, `wipExceeded`, `overdue`, the empty-state and add-card/column strings.
`OgeKanbanColumn`	`interface`	`{ key, title?, color?, wipLimit?, minCount?, collapsed?, allowAdding?, allowDrag?, allowDrop?, transitionColumns? }` — the declared column shape. `wipLimit`/`minCount` drive the danger/warning badges; `allowDrag`/`allowDrop`/`transitionColumns` gate interactive moves (programmatic `moveCard` is deliberately not gated).
`OgeKanbanCard<T>`	`interface`	The normalized card handed to templates and events: `key`, `source` (your item, unchanged), `column`, `title`, `description`, `color`, `order`, `swimlane`, `tags`, `assignees`, `dueDate`, `priority`.

Notes

No WAI-ARIA APG kanban pattern exists, and a listbox cannot hold interactive content, so the board is a set of lists with a roving focus: each column is a labeled role="list" (title, count and WIP limit in the accessible name) of role="listitem" wrappers, each holding a focusable card (role="group", aria-roledescription="card" from messages.board.cardRoleDescription, the selected card aria-current). One Tab stop per column.
Keyboard on a focused card: Arrow keys rove within and across columns, Enter edits, Delete deletes, Ctrl+Arrow moves the card as the exact keyboard twin of the drag (announced through a polite live region), and Tab continues into the card's own content — the edit / delete quick actions are real labeled buttons, and so is whatever a custom card template renders. Keys typed there stay with that control (Ctrl+Arrow in an input moves by word, not the card); Escape returns to the card.
Binding plain arrays never mutates them — edits land in an internal working set and the past-tense events carry the data to persist. Without an orderExpr the array order is the board order; with one, moves write a midpoint order value back in the item's own storage shape.
Virtualization assumes the fixed cardHeight — that is also what keeps drag hit-testing allocation-free and agreeing with what is rendered. Rich variable-height card templates should set [virtualScrolling]="false" (the documented exception).