Task Card

When to use

Reach for TaskCard when you need a time-aware task surface — agent run queues, content schedules, sprint cards, workflow tasks. The card carries the standard task fields out of the box, paints urgency directly onto the chrome via the time engine, and is fully data-interactive (JSON I/O, clipboard, drag-drop).

For lightweight tree-row rendering (collapsible sub-items, inline checkbox, single-line description preview), reach for the sibling task-tree procomp — shares the same TaskItem schema so drags + clipboard payload work cross-procomp. For kanban, use kanban-board + the renderer exported below.

Basic example

import { TaskCard } from "@/components/task-card";

export function Example() {
  return (
    <TaskCard
      defaultValue={{
        id: "task-001",
        name: "Review pull request #482",
        status: "in-progress",
        active: true,
        setAt: "2026-05-19T09:00:00Z",
        expireAt: "2026-05-21T17:00:00Z",
      }}
      editable
    />
  );
}

Auto-color engine

The engine normalizes (now − startAt) / (expireAt − startAt) to [0, 1] and maps it through an OKLCH ramp — green at 0, red at 1. Past expireAt pins to full red. If expireAt is absent, duration is used instead. Per-item borderColor overrides the engine for that node. Set colorRamp to swap presets: 'default' | 'muted' | 'vivid' | 'monochrome' — or pass a custom function for full control.

Edit modes

• editable=false (default) → click the edit button to open a popup with all fields in one form.
• editable=true→ click the edit button to toggle inline editing on that item. A secondary "Edit in dialog…" icon and action-menu item still open the popup.
• locked=true on an item blocks both modes for that node. onPermissionDenied fires with reason: 'locked'.

Collapsibility

Every card has a chevron at the left of its header. Clicking it collapses the card's body (description, time-info, chips, links, images) andits nested children — only the header stays visible. Per-item, independent at every depth. The collapse flag is UI-only state in the component's reducer (collapsedIds: ReadonlySet<string>) — it is not stored on TaskItem, so JSON I/O round-trips ignore it. Remounting via key resets all collapse state.

Color override (Dialog)

Click the action menu (...) on any card and choose Override color… to open a centered Dialog: 8 curated OKLCH palette swatches, a free-text input for any CSS color string, and an Autobutton (with sparkle icon) that clears the override and hands rendering back to the time engine. Dialog (vs Popover) avoids an outside-click race with the action menu's dismissal.

JSON I/O and clipboard

Use the imperative ref handle to copy(), paste(), getValue(), or getTree(). When a card has keyboard focus, Cmd/Ctrl+C copies it and Cmd/Ctrl+V pastes from the clipboard as a child. Drag a card onto another card's children area to drop the JSON payload as a child. The clipboard uses MIME application/x-ilinxa-task+json with a text/plain JSON fallback for browsers without custom-MIME support.

SSR + time engine

The engine reads new Date() at render time, which means server- and client-rendered HTML can compute slightly different border colors when nowisn't frozen. The card mitigates this with suppressHydrationWarning on the article root — the visual flash is sub-frame and the data is consistent server→client. For deterministic SSR (snapshot tests, server-rendered HTML caching), pass a frozen now: now={new Date("2026-05-20T12:00:00Z")}.

Composing with kanban-board

The package exports taskCardKanbanRenderer — a typed KanbanCardRenderer<TaskItem> with dragHandle: "header" so the kanban grip strip handles outer column reorder while the card body keeps its full edit / collapse / nested-DnD semantics. Drop it into the KanbanBoard renderers array alongside (or instead of) the built-in card renderers. The kanban-board demo on its own detail page shows mixed renderers; below is the minimum wiring.

import { KanbanBoard, kanbanCardRenderer } from "@/components/kanban-board";
import { taskCardKanbanRenderer } from "@/components/task-card";
import type { KanbanData } from "@/components/kanban-board";

const initial: KanbanData = {
  swimlanes: [],
  columns: [
    {
      id: "col-todo",
      title: "To do",
      color: "slate",
      items: [
        {
          id: "kanban-task-1",
          rendererId: "task-card",            // matches renderer.id
          data: {
            id: "task-001",
            name: "Review PR #482",
            status: "todo",
            active: true,
            setAt: "2026-05-19T09:00:00Z",
            expireAt: "2026-05-21T17:00:00Z",
          },
        },
      ],
    },
    { id: "col-doing", title: "In progress", color: "lime", items: [] },
    { id: "col-done",  title: "Done",        color: "emerald", items: [] },
  ],
};

export function TaskKanbanExample() {
  return (
    <KanbanBoard
      renderers={[kanbanCardRenderer, taskCardKanbanRenderer]}
      defaultData={initial}
      aria-label="Task kanban"
    />
  );
}

rendererId: "task-card" on each kanban item must match taskCardKanbanRenderer.id — the board uses this to look up the renderer for each item. Items with no matching renderer show a placeholder card.

Other composition targets

• flow-canvas (via todo-card-tree-node sibling adapter, shipping separately): exposes a NodeRenderer that wraps this card.
• task-tree (sibling procomp, shipping separately): lightweight tree-row alternative that shares the same TaskItem schema and DnD payload so drags cross-procomp.

Gotchas

• Images and links are read-only in inline edit mode in v0.1 — use the popup to add / remove them.
• No undo/redo in v0.1. Wire optimistic-undo yourself or wait for v0.2+.
• One item edits at a time. Opening a new edit closes any open one.