Card Tree

When to use

Reach for CardTree when you have JSON-shaped, deeply nested, structured content — agent transcripts, configuration trees, decision records, runbooks, requirement docs — and want a card-tree view with typed-scalar fields, predefined content blocks (code, image, table, quote, list), and full keyboard accessibility.

Skip it for prose-only writing (use a markdown editor) or flat lists (use a table). Markdown source is not supported in v0.1 — card-tree is JSON-native.

Basic example

import { CardTree } from "@/components/card-tree";

export function Example() {
  return (
    <CardTree
      defaultValue={{
        title: "ADR-0042",
        status: "accepted",
        priority: 2,
        codearea: { format: "ts", content: "const x = 1;" },
        context: { reason: "..." },
      }}
    />
  );
}

Reserved keys

__rcid, __rcorder, and __rcmeta are reserved. __rcid auto-generates via crypto.randomUUID() if absent. __rcorder controls sibling order (integer, gaps allowed). __rcmeta is a per-card scalar map exposed via the metaPresentation prop.

Predefined keys

Five reserved-name fields render as styled blocks:

• codearea — { format, content }
• image — { src, alt? }
• table — { headers: string[], rows: scalar[][] }
• quote — a string
• list — an array of scalars

Add a key to disabledPredefinedKeys to opt out — the parser then treats it as a flat field instead.

Field value typing

Flat-field values are JSON scalars: string, number, boolean, null. Type is inferred at parse time and rendered per type (numbers right-aligned mono; booleans as check / dash icons; ISO-8601 date strings formatted via Intl.DateTimeFormat; null as a muted em-dash).

Pass dateDetection="never" to disable date inference, or a custom predicate function for fine control.

Children

Any non-reserved, non-predefined property whose value is a plain object becomes a child card. Arrays of objects are rejected in v0.1 — convert to object-keyed form (e.g. { items: { item_0: a, item_1: b } }) or use the list predefined key for scalar arrays.

State model

The component is uncontrolled: defaultValue is the seed. To reset, remount via the key prop. Read the current state imperatively via a ref:

const ref = useRef<CardTreeHandle>(null);
// ...
const json = ref.current?.getValue();   // canonical JSON string
const tree = ref.current?.getTree();    // object form with auto-IDs

Accessibility

The tree implements the full ARIA tree contract: role="tree", role="treeitem", aria-level, aria-expanded. Keyboard: arrows navigate visible cards, → expands / descends, ← collapses / ascends, Home / End jump to first / last, Enter / Space toggles collapse on a card with children.