@toclocoinc/lattice-grid 1.59.0 → 1.61.0

package/modules/kanban.d.ts

@@ -0,0 +1,492 @@
+/*!
+ * Lattice Grid 1.61.0, kanban module type declarations
+ * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
+ * https://latticegrid.dev
+ */
+/** A row backing a card: any object. Its column comes from `columnProperty` and its identity from `rowKey`. */
+type KanbanRow = Record<string, unknown>;
+
+/**
+ * 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.
+ */
+interface KanbanCard {
+  key: unknown;
+  row: KanbanRow;
+  columnId: string | null;
+  points: number;
+  hasPoints: boolean;
+  order?: unknown;
+  swimlane?: unknown;
+  sprint?: unknown;
+  epic?: unknown;
+  fields: Record<string, string>;
+}
+
+/** A column with its cards and aggregates. `over` is true when `count` exceeds `wipLimit`. */
+interface KanbanColumn {
+  id: string;
+  title: string;
+  color: string | null;
+  wipLimit: number | null;
+  collapsed: boolean;
+  cards: KanbanCard[];
+  count: number;
+  points: number;
+  over: boolean;
+}
+
+/** A column definition: an id string, or an object configuring one column. */
+type KanbanColumnDef = string | {
+  id: string;
+  title?: string;
+  color?: string;
+  wipLimit?: number;
+  collapsed?: boolean;
+  /**
+   * A per-column SLA override (BACKLOG-0000960): a lone threshold read as the
+   * breach level, or a `{ warn, breach }` pair. Overrides the global `sla`
+   * thresholds for cards in this column (precedence: lane → column → global).
+   */
+  sla?: KanbanSlaThreshold | { warn?: KanbanSlaThreshold; breach?: KanbanSlaThreshold };
+  /** A per-column warn threshold — the shorthand for `sla: { warn }`. */
+  slaWarn?: KanbanSlaThreshold;
+  /** A per-column breach threshold — the shorthand for `sla: { breach }`. */
+  slaBreach?: KanbanSlaThreshold;
+};
+
+/** A card field editor handle returned by a host editor factory. */
+interface KanbanEditor {
+  el: HTMLElement;
+  focus?: () => void;
+  destroy?: () => void;
+}
+
+/** A card field mapping: a property path, a function, or an object opting into inline edit. */
+type KanbanFieldMap = string | ((row: KanbanRow) => unknown) | {
+  field: string;
+  edit?: boolean;
+  editor?: (ctx: { card: KanbanCard; field: string; value: string; commit: (value: unknown) => void; cancel: () => void }) => KanbanEditor;
+};
+
+/** The field-to-property mapping that drives the card template. */
+interface KanbanCardMap {
+  title?: KanbanFieldMap;
+  subtitle?: KanbanFieldMap;
+  labels?: KanbanFieldMap;
+  assignee?: KanbanFieldMap;
+  due?: KanbanFieldMap;
+  cover?: KanbanFieldMap;
+  progress?: KanbanFieldMap;
+  badges?: KanbanFieldMap;
+  accent?: KanbanFieldMap;
+  [field: string]: KanbanFieldMap | undefined;
+}
+
+/** Granular readonly: the whole board, or selectively by column id and card key. */
+type KanbanReadonly = boolean | {
+  board?: boolean;
+  columns?: Record<string, boolean>;
+  cards?: Record<string, boolean>;
+};
+
+/** The payload every board event carries. */
+interface KanbanEvent {
+  card: KanbanCard;
+  column: string | null;
+  el?: unknown;
+  originalEvent?: unknown;
+}
+
+/**
+ * A card-aging / SLA threshold (BACKLOG-0000960): a raw millisecond count, or
+ * a `{ weeks, days, hours, minutes, seconds, ms }` spec whose fields are summed
+ * (`{ days: 3, hours: 12 }` → 3.5 days). A negative or non-finite value means
+ * "no threshold at this level".
+ */
+type KanbanSlaThreshold = number | {
+  weeks?: number; week?: number; w?: number;
+  days?: number; day?: number; d?: number;
+  hours?: number; hour?: number; h?: number;
+  minutes?: number; minute?: number; m?: number; min?: number;
+  seconds?: number; second?: number; s?: number; sec?: number;
+  ms?: number; milliseconds?: number;
+};
+
+/**
+ * Card-aging / SLA configuration (BACKLOG-0000960). 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}.
+ */
+interface KanbanSlaConfig {
+  /** The global warn threshold. */
+  warn?: KanbanSlaThreshold;
+  /** The global breach threshold. */
+  breach?: KanbanSlaThreshold;
+  /** Per-column overrides by column id (each a threshold or a `{ warn, breach }` pair). */
+  columns?: Record<string, KanbanSlaThreshold | { warn?: KanbanSlaThreshold; breach?: KanbanSlaThreshold }>;
+  /** Per-swimlane overrides by lane id (each a threshold or a `{ warn, breach }` pair). */
+  lanes?: Record<string, KanbanSlaThreshold | { warn?: KanbanSlaThreshold; breach?: KanbanSlaThreshold }>;
+  /**
+   * Where the ageing clock starts: `'column'` (default) measures time in the
+   * card's current column; `'board'` measures age since the card arrived/was
+   * created.
+   */
+  basis?: 'column' | 'board';
+  /** A row property holding the wall-clock time the card entered its column. */
+  enteredProperty?: string;
+  /** A row property holding the wall-clock time the card was created. */
+  createdProperty?: string;
+  /** Whether cards in a done column are exempt from ageing (default true). */
+  ignoreDone?: boolean;
+  /** Whether the flow transition log drives the ageing basis when present (default true). */
+  useTransitionLog?: boolean;
+  /** Show the age chip on every aged card (`'always'`), or only on warn/breach (`'threshold'`, default). */
+  showAge?: 'always' | 'threshold';
+  /** A wall-clock epoch clock, injectable for deterministic tests (default `Date.now`). */
+  now?: () => number;
+  /** A re-check interval in ms so a card breaching by sitting still still lights up (0 = off). */
+  tick?: number;
+  /** Called on a rising crossing to warn level, `(level, rows)` — the router alert handler's shape. */
+  onWarn?: (level: 'warn' | 'breach', rows: KanbanRow[]) => void;
+  /** Called on a rising crossing to breach level, `(level, rows)` — the router alert handler's shape. */
+  onBreach?: (level: 'warn' | 'breach', rows: KanbanRow[]) => void;
+}
+
+/** The computed SLA state of one card (BACKLOG-0000960). */
+interface KanbanSlaState {
+  key: unknown;
+  columnId: string | null;
+  lane?: unknown;
+  /** The ageing-clock start epoch (ms), or null when no time source could be resolved. */
+  start: number | null;
+  /** The card's age in ms, or null when unknown. */
+  ageMs: number | null;
+  /** A short human age label (`2d`, `5h`, …), '' when unknown. */
+  ageText: string;
+  /** The resolved warn threshold in ms, or null. */
+  warnMs: number | null;
+  /** The resolved breach threshold in ms, or null. */
+  breachMs: number | null;
+  /** The classified level, or null when the card cannot be aged. */
+  level: 'ok' | 'warn' | 'breach' | null;
+  /** True when `level` is `'breach'`. */
+  breached: boolean;
+}
+
+/**
+ * The card-aging / SLA monitor (BACKLOG-0000960), 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.
+ */
+interface KanbanSla {
+  /** The normalised SLA config (read-only). */
+  readonly config: object;
+  /** Recompute every card's SLA state without emitting anything. */
+  sync(): KanbanSla;
+  /** Recompute and fire `card:sla`/`onWarn`/`onBreach` on each rising crossing. */
+  evaluate(opts?: { emit?: boolean }): KanbanSlaState[];
+  /** Establish the baseline, notify on the current state, and start the optional tick. */
+  start(): KanbanSla;
+  /** The SLA state of one card (by card model or key), or null when unknown. */
+  stateFor(cardOrKey: KanbanCard | unknown): KanbanSlaState | null;
+  /** Every card's current SLA state. */
+  states(): KanbanSlaState[];
+  /** The cards currently at breach level. */
+  breaches(): KanbanSlaState[];
+  /** The cards currently at warn level (not yet breached). */
+  warnings(): KanbanSlaState[];
+  /** Stop the tick and drop the board subscriptions. */
+  destroy(): void;
+}
+
+/**
+ * Kanban configuration. Every structural property is named here so the same
+ * board maps DemandFlow (a status field, `points`, `sprint`, `epic`, a
+ * swimlane property) and any customer schema without code change.
+ */
+interface KanbanConfig {
+  rows?: KanbanRow[];
+  grid?: unknown;
+  rowKey?: string | ((row: KanbanRow) => unknown);
+  columnProperty?: string;
+  columns?: KanbanColumnDef[];
+  columnOrder?: string[];
+  pointsProperty?: string;
+  showPoints?: boolean;
+  orderProperty?: string;
+  swimlaneProperty?: string;
+  /** Render the 2D swimlane layout using `swimlaneProperty` (default false). */
+  swimlanes?: boolean;
+  /** Explicit lane definitions; otherwise lanes come from the distinct swimlane values. */
+  lanes?: (string | { id: string; title?: string })[];
+  /** An explicit lane order by id (also set by a lane-header-drag reorder). */
+  laneOrder?: string[];
+  /** Enforce `wipLimit` as a hard gate: a move that would exceed it is refused (default false). */
+  enforceWip?: boolean;
+  /** A custom card template: return an HTML string or a DOM node to own the whole card body. */
+  cardRenderer?: (card: KanbanCard, ctx: { column: KanbanColumn; readonly: boolean; el: HTMLElement; doc: Document }) => string | Node | void;
+  sprintProperty?: string;
+  epicProperty?: string;
+  /** A configurable sprint dataset: the canonical sprint list (order + titles), shown even when empty. */
+  sprints?: (string | { id: unknown; title?: string })[];
+  /** The initially selected sprint id, `Kanban.BACKLOG`, or undefined for all. */
+  sprint?: unknown;
+  /** The initially selected epic id, or undefined for all. */
+  epic?: unknown;
+  /** Column ids that count as "done" for a rollup's progress (also a column def's `done: true`). */
+  doneColumns?: string[];
+  /** Card pop-out: a nested child grid or board (master-detail by composition). */
+  children?: KanbanChildren;
+  /** Card virtualization for tall columns: true, or `{ rowHeight, overscan, threshold, viewport }`. */
+  virtualize?: boolean | { rowHeight?: number; overscan?: number; threshold?: number; viewport?: number };
+  /**
+   * Card aging / SLA highlighting (BACKLOG-0000960): warn/breach thresholds
+   * (globally, per column and/or per lane) that age each card and fire
+   * `card:sla` on a rising crossing. Opt-in; reached at runtime as
+   * {@link Kanban#sla}. See {@link KanbanSlaConfig}.
+   */
+  sla?: KanbanSlaConfig;
+  /** A saved board state (from `getState`) to restore on construction. */
+  state?: object;
+  /** Show a per-column add-card affordance. */
+  addCard?: boolean;
+  /** Persist a standalone inline edit; return false or a rejected promise to revert. */
+  onCardEdit?: (event: { card: KanbanCard; key: unknown; field: string; fieldPath: string; value: unknown }) => boolean | void | Promise<boolean | void>;
+  /**
+   * Create a card for a column on add-card; return the row to create (with
+   * its key), a Promise of that row, or nothing to auto-generate. A rejected
+   * Promise creates no card and leaves the board unchanged (BACKLOG-0001230).
+   */
+  onAddCard?: (columnId: string) => KanbanRow | Promise<KanbanRow> | void;
+  /** A predicate filter over cards; only matching cards are shown. */
+  filter?: (row: KanbanRow, card: KanbanCard) => boolean;
+  /** Quick-filter text matched case-insensitively across card fields. */
+  quickFilter?: string;
+  card?: KanbanCardMap;
+  readonly?: KanbanReadonly;
+  ariaLabel?: string;
+  emptyText?: string;
+  /** Whether card selection is enabled (default true). */
+  selectable?: boolean;
+  /** Host-localised words for the move announcements (grabbed/moved/dropped/reverted/cancelled). */
+  labels?: Record<string, string>;
+  /**
+   * Veto/confirm a move before any write. Return `false` (or a promise of it)
+   * to refuse; `from`/`to` are column ids, `index` the target position.
+   */
+  onBeforeMove?: (card: KanbanCard, from: string | null, to: string, index: number | null) => boolean | Promise<boolean>;
+  /**
+   * Persist a move on a standalone (non-grid) board. Return `false` or a
+   * rejected promise to revert the optimistic move. On a grid-bound board the
+   * grid's write-back pipeline persists instead and this is not called.
+   */
+  onCardMove?: (event: KanbanMoveEvent) => boolean | void | Promise<boolean | void>;
+  /** A per-card context menu: items, or `fn(card, selectedCards)` returning items. Suppresses `card:contextmenu`. */
+  contextMenu?: KanbanMenuItem[] | ((card: KanbanCard, selected: KanbanCard[]) => KanbanMenuItem[]);
+  onCardClick?: (event: KanbanEvent) => void;
+  onCardDblClick?: (event: KanbanEvent) => void;
+  onCardContextMenu?: (event: KanbanEvent) => void;
+}
+
+/**
+ * Card pop-out configuration. The child view is a full composed grid (via
+ * `factory`, a `createGrid`), a nested board (`asBoard`), or a custom `render`.
+ * The child set is the rows whose `property` equals the card key, or the
+ * `load(card)` result. Recursion falls out: a nested board can pop its own
+ * children.
+ */
+interface KanbanChildren {
+  /** Parent-id property linking child rows to a card within the same dataset. */
+  property?: string;
+  /** Per-card child rows, sync or async — an alternative (or addition) to `property`. */
+  load?: (card: KanbanCard) => KanbanRow[] | Promise<KanbanRow[]>;
+  /** Whether a card can be expanded, overriding the property/load inference. */
+  hasChildren?: (card: KanbanCard) => boolean;
+  /** Where the pop-out appears (default `drawer`). */
+  present?: 'drawer' | 'modal' | 'inline';
+  /** The grid factory (a `createGrid`) that builds the child grid. */
+  factory?: (container: HTMLElement, options: object) => { destroy?: () => void };
+  /** Make the child a nested board (recursive) instead of a grid. */
+  asBoard?: boolean;
+  /** Options for the child grid/board — an object or `fn(card)`. */
+  gridOptions?: object | ((card: KanbanCard) => object);
+  /** Fully custom child render; returns a cleanup function. */
+  render?: (container: HTMLElement, ctx: { card: KanbanCard; rows: KanbanRow[]; board: Kanban; depth: number }) => (void | (() => void));
+  /** The pop-out title (default the card title). */
+  title?: (card: KanbanCard) => string;
+}
+
+/** One context-menu item. `action` receives the card, the selected cards, and the board. */
+interface KanbanMenuItem {
+  label: string;
+  action?: (ctx: { card: KanbanCard; cards: KanbanCard[]; board: Kanban }) => void;
+  disabled?: boolean;
+}
+
+/** The payload of a `card:move` (and `card:reverted`) event. */
+interface KanbanMoveEvent {
+  keys: unknown[];
+  cards: KanbanCard[];
+  from: (string | null)[];
+  to: string;
+  index: number | null;
+  orders: number[] | null;
+}
+
+/** The keyed-diff consumer surface a board shares with a grid, so a Data Router routes to it directly. */
+interface KanbanRows {
+  apply(change: { add?: KanbanRow[]; update?: KanbanRow[]; remove?: unknown[] }): void;
+  forEach(fn: (row: KanbanRow, key: unknown) => void): void;
+  readonly count: number;
+}
+
+/**
+ * Named card predicates, composed with AND (BACKLOG-0001229), following the
+ * grid's `filters.where` convention (BACKLOG-0001202). 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)`.
+ */
+interface KanbanFilters {
+  /** The reserved name `board.setFilter` registers/removes under. */
+  readonly DEFAULT: string;
+  /** The registered names, in registration order. */
+  where(): string[];
+  /** Register or replace the predicate under `name`. */
+  where(name: string, predicate: (row: KanbanRow, card: KanbanCard) => boolean): Kanban;
+  /** Remove whatever is registered under `name`; a no-op if nothing was. */
+  where(name: string, predicate: null): Kanban;
+  /** Re-run every named predicate (or one, by name) and re-render. */
+  reapply(name?: string): boolean;
+}
+
+/**
+ * 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.
+ */
+interface Kanban {
+  readonly el: unknown | null;
+  readonly rowKey: string | ((row: KanbanRow) => unknown);
+  rows: KanbanRows;
+  /** The card-aging / SLA monitor, present only when a `sla` config was supplied (BACKLOG-0000960). */
+  sla?: KanbanSla;
+  columns(): KanbanColumn[];
+  column(id: string): KanbanColumn | undefined;
+  count(id: string): number;
+  points(id: string): number;
+  cards(): KanbanCard[];
+  card(key: unknown): KanbanCard | undefined;
+  on(name: string, fn: (event: KanbanEvent) => void): () => void;
+  off(name: string, fn: (event: KanbanEvent) => void): void;
+  readonly(scope?: { column?: string; card?: unknown }): boolean;
+  /**
+   * Move one or more cards to a column (and, with an order property, to a
+   * position within it), through the `onBeforeMove` veto and the grid's
+   * shipped write-back path. The single entry point behind drag-and-drop and
+   * keyboard move.
+   */
+  move(keys: unknown | unknown[], toColumn: string, toIndex?: number | null, toLane?: string): Promise<{ moved: unknown[]; reverted: boolean }>;
+  /** The selected card keys. */
+  selection(): unknown[];
+  /** Whether a card is selected. */
+  isSelected(key: unknown): boolean;
+  /** Change the selection: `set` (replace), `add`, `toggle` or `remove`. */
+  select(keys: unknown | unknown[], mode?: 'set' | 'add' | 'toggle' | 'remove'): Kanban;
+  /** Clear the selection. */
+  clearSelection(): Kanban;
+  /** Collapse, expand or toggle a column (emits `column:collapse`). */
+  collapseColumn(id: string, collapsed?: boolean): Kanban;
+  /** Collapse, expand or toggle a swimlane (emits `swimlane:collapse`). */
+  collapseLane(id: string, collapsed?: boolean): Kanban;
+  /** Reorder the columns to the given id order (emits `column:reorder`). */
+  reorderColumns(order: string[]): Kanban;
+  /** Move one column before another (or to the end); emits `column:reorder`. */
+  moveColumn(id: string, beforeId: string | null): Kanban;
+  /** Reorder the swimlanes to the given id order (emits `swimlane:reorder`). */
+  reorderLanes(order: string[]): Kanban;
+  /** Move one swimlane before another (or to the end); emits `swimlane:reorder`. */
+  moveLane(id: string, beforeId: string | null): Kanban;
+  /** Named card predicates, composed with AND (BACKLOG-0001229). See {@link KanbanFilters}. */
+  filters: KanbanFilters;
+  /** Set a predicate filter over cards, or clear it with null. Sugar for `filters.where(filters.DEFAULT, fn)`. */
+  setFilter(fn: ((row: KanbanRow, card: KanbanCard) => boolean) | null): Kanban;
+  /** Set the quick-filter text matched across card fields. Independent of every `filters.where` predicate. */
+  setQuickFilter(text: string): Kanban;
+  /** Distinct values of a property with card counts — the raw material for a facet control. */
+  facets(property: string): { value: unknown; count: number }[];
+  /** The sentinel `setSprint` value that selects the backlog (cards with no sprint). */
+  readonly BACKLOG: unknown;
+  /** Select the shown sprint (`BACKLOG` for the backlog, undefined for all); emits `sprint:changed`. */
+  setSprint(sprint: unknown): Kanban;
+  /** Show only the backlog (cards with no sprint). */
+  showBacklog(): Kanban;
+  /** Select the shown epic (undefined for all); emits `epic:changed`. */
+  setEpic(epic: unknown): Kanban;
+  /** The distinct sprint values (the switcher's options); a configured `sprints` dataset pins the order. */
+  sprints(): unknown[];
+  /** The sprint dataset as `{ id, title }` descriptors — the configured list plus any data-only sprint. */
+  sprintDefs(): { id: unknown; title: string }[];
+  /** The distinct epic values. */
+  epics(): unknown[];
+  /** Roll rows up by a property: per-bucket count, points, done and progress. */
+  rollup(property: string): { value: unknown; count: number; points: number; doneCount: number; donePoints: number; progress: number }[];
+  /** The epic rollup (empty when no epic property is configured). */
+  epicRollup(): { value: unknown; count: number; points: number; doneCount: number; donePoints: number; progress: number }[];
+  /** Whether a card can be expanded to a child pop-out. */
+  canExpand(card: KanbanCard): boolean;
+  /** Open a card's children in a pop-out (drawer/modal/inline); emits `card:expand`/`card:drill`. */
+  expand(key: unknown): Promise<object | null>;
+  /** Close any open card pop-out. */
+  closeDetail(): Kanban;
+  /** Whether a mapped card field is opted into inline edit and writable. */
+  isFieldEditable(name: string): boolean;
+  /** Start inline editing a card's field (the grid's own field editor when bound); no-op headless. */
+  editCard(key: unknown, name?: string): object | null;
+  /** Commit an inline edit through the write-back path (grid.edit.setCells when bound); emits `card:edit`. */
+  applyEdit(key: unknown, name: string, value: unknown): Promise<boolean>;
+  /**
+   * Add a card to a column and open it in inline edit; emits `card:add`.
+   * Returns the new key directly, or a Promise of it when `onAddCard`
+   * returns a Promise or a `beforeAdd` handler defers (BACKLOG-0001230); a
+   * rejected `onAddCard` Promise resolves this to `null` with no card added.
+   */
+  addCard(columnId: string, seed?: KanbanRow): unknown | Promise<unknown>;
+  /** Serialise the restorable state: collapsed columns/lanes, order, filter, sprint/epic, selection. */
+  getState(): object;
+  /** Restore a state snapshot from {@link Kanban#getState}. */
+  setState(snapshot: object): Kanban;
+  /** Mark the board loading (renders a host-localised loading state). */
+  setLoading(loading: boolean): Kanban;
+  /** Set (or clear with null) an error state, rendered as a host-supplied message. */
+  setError(message: string | null): Kanban;
+  setRows(rows: KanbanRow[]): Kanban;
+  /**
+   * Replace the board's configured column set (BACKLOG-0001228). Keeps card
+   * placement and interaction state (collapsed columns, column order, quick
+   * filter, selection) for every column id that survives; a dropped id is
+   * not specially handled — a card whose value has nowhere configured to go
+   * re-derives an ad hoc column rather than becoming `unplaced` (the same
+   * "never silently drop a card" rule an unconfigured value already gets).
+   */
+  setColumns(defs: KanbanColumnDef[]): Kanban;
+  refresh(): Kanban;
+  destroy(): void;
+}
+
+/**
+ * Create a board (kanban) view of rows, grouped into columns by a configurable
+ * property. Pass a DOM element to render into, or `null` for a headless board
+ * that computes the same column/card model without a DOM.
+ */
+export function createKanban(el: HTMLElement | null, config?: KanbanConfig): Kanban;
+export default createKanban;