Task Tree

TaskTree is the lightweight sibling to @ilinxa/task-card. Same fixed TaskItem schema, but renders a thin two-line row (bold name + truncated description) instead of the time-driven card chrome.

• Sub-issue / outline lists where dozens to hundreds of rows must scan quickly.
• Side panels next to a primary editor (file-tree-style layout).
• Hierarchical task pickers, often with a rich editor opening on row click.
• Bulk management screens (multi-select + bulk-toggle / bulk-remove).

For time-aware urgency coloring or the full edit popup, use task-card. For kanban boards, compose @ilinxa/kanban-board with taskCardKanbanRenderer.

import { TaskTree } from "@ilinxa/task-tree";
import type { TaskItem } from "@ilinxa/task-card";

const items: TaskItem[] = [
  {
    id: "t-1",
    name: "Ship Q3 plan",
    status: "in-progress",
    active: true,
    setAt: "2026-05-18T09:00:00Z",
    children: [
      { id: "t-1a", name: "Draft outline", status: "done", active: true, setAt: "2026-05-18T09:00:00Z" },
    ],
  },
];

<TaskTree
  defaultValue={items}
  statusOptions={[
    { value: "todo", label: "To do", variant: "outline" },
    { value: "in-progress", label: "In progress", variant: "secondary" },
    { value: "done", label: "Done", variant: "default" },
  ]}
  onChange={({ items, reason }) => save(items)}
/>

Both modes work; the three-defenses pattern protects controlled consumers from echo storms and mid-drag setState races (microtask-defer + structural resync guard + drag-active notification suppression).

// Uncontrolled
<TaskTree defaultValue={items} onChange={({ items }) => save(items)} />

// Controlled — value wins, defaultValue ignored
<TaskTree value={items} onChange={({ items }) => setItems(items)} />

Pair the tree with a Dialog-mounted TaskCard in one line. Clicking a row opens the matching card editable; live-saves propagate back into the tree (Q-P1 auto-persistence).

import { TaskTreeWithEditor } from "@ilinxa/task-tree";

<TaskTreeWithEditor
  defaultValue={items}
  statusOptions={statusOptions}
  onChange={({ items }) => save(items)}
/>

For stricter integrations (confirm dialog before edit, custom editor surface) compose <TaskTree> + your own dialog using the onItemClick callback.

const ref = useRef<TaskTreeHandle>(null);

// Tree state
ref.current?.getValue();
ref.current?.setValue(newItems);

// Item ops
ref.current?.addItem(item, { parentId: "t-1", index: 0 });
ref.current?.addChild("t-1", item);
ref.current?.removeItem("t-1a");
ref.current?.removeItems(["t-1a", "t-1b"]);
ref.current?.toggleActive("t-1", false);
ref.current?.toggleActiveBulk(["t-1", "t-2"], true);

// Focus + lookup
ref.current?.focusItem("t-1");
ref.current?.getItemById("t-1");

// Collapse
ref.current?.expandItem("t-1");
ref.current?.collapseItem("t-1");
ref.current?.toggleCollapse("t-1");
ref.current?.expandAll();
ref.current?.collapseAll();
ref.current?.isCollapsed("t-1");

// Selection
ref.current?.selectItem("t-1");
ref.current?.deselectItem("t-1");
ref.current?.selectRange("t-1", "t-3");
ref.current?.selectAll(); // visible only
ref.current?.clearSelection();
ref.current?.getSelectedIds();

// Toolbar state
ref.current?.setQuery("review");
ref.current?.setSort({ kind: "name", direction: "asc" });
ref.current?.setFilter({ statuses: ["done"] });
ref.current?.clearAllFilters();

The same engine that powers <TaskTree> is also a hook. Drive your own toolbar / row layout / external state manager off the returned value, or feed it back into the default shell via the state prop.

import { useTaskTreeState, TaskTree } from "@ilinxa/task-tree";

function MyTree() {
  const state = useTaskTreeState({
    defaultValue: items,
    onChange: ({ items }) => save(items),
  });

  // Drive a custom search input:
  // <input value={state.query} onChange={(e) => state.setQuery(e.target.value)} />

  // OR feed back into the default shell:
  return <TaskTree state={state} />;
}

• renderRow — full row paint; receives defaultRender.
• renderName / renderDescription / renderPerson — per-field overrides.
• renderStatusIndicator — receives the matched statusOption.
• renderToolbar — wraps or replaces the toolbar; receives defaultToolbar + state.
• renderEmptyState — replaces the default placeholder; receives hasFilter.
• renderDragOverlay — replaces the cursor-follow visual; receives the dragged item.

• ↑ / ↓ — previous / next visible row
• → — expand collapsed row OR move to first child
• ← — collapse expanded row OR move to parent
• Home / End — first / last visible row
• Space — toggle active state of focused row
• Enter — select + fire onItemClick
• Delete / Backspace — remove focused row
• Cmd/Ctrl + A — select all visible
• Cmd/Ctrl + Click — toggle row in selection
• Shift + Click — range select from anchor
• Escape — clear selection