Card Tree Node

When to use

Reach for @ilinxa/card-tree-node when each flow-canvas node should carry a card-tree JSON tree as its data — agent workflow editors, schema/config canvases, decision or runbook maps. The viewer paints a read-only summary (title + first 3 flat fields + block chips + nested-card outlines with their own ports); clicking opens a consumer-owned dialog with the full CardTree editor. At most ONE card-tree editor instance is mounted at any moment regardless of node count.

Blocks on a node (v0.4.0)

A card-tree card can carry blocks — the five built-in predefined keys (codearea, image, table, quote, list) and any key the host registers through customPredefinedKeys. Through v0.3 the canvas viewer rendered none of them: it recognised scalars and __rcid-tagged objects, and a block is neither, so blocks vanished silently. v0.4.0 paints each one as a compact chip — table  2 x 3, body  2 items — sized for node zoom, with the full payload still living in the edit dialog.

Pass the same customPredefinedKeys array to the renderer and to <CardTree>. If the node knows about a registration and the dialog does not (or the reverse), the two surfaces disagree about what exists on the card.

import { CardTree, type CustomPredefinedKey } from "@ilinxa/card-tree";
import { createCardTreeViewerRenderer } from "@ilinxa/card-tree-node";

// Module scope — an inline literal re-allocates every render.
const CUSTOM_KEYS: CustomPredefinedKey[] = [
  {
    key: "body",
    validate: (v) => ({ ok: Array.isArray(v) }),
    defaultValue: () => [],
    render: (v) => <MyRichText value={v} />,
  },
];

// Call the factory ONCE. It resolves options into the stable object that
// keeps the viewer's memo effective.
const RENDERERS = [
  createCardTreeViewerRenderer({
    customPredefinedKeys: CUSTOM_KEYS,
    renderCustomBlocks: true,  // default false = summary chips
    maxBlocks: 3,              // also: maxFlatFields, maxSubcards
  }),
];

// ...and the dialog gets the same array:
<CardTree defaultValue={tree} editable customPredefinedKeys={CUSTOM_KEYS} />

• renderCustomBlocks is off by default. A canvas node is a summary surface, and host render code sized for a full-width editor rarely fits a 240px node. Turn it on when your renderer is compact.
• Host render() output is wrapped in an error boundary either way — a renderer that throws degrades to its summary chip and never blanks the canvas.
• Built-in blocks always use the chip; a host cannot capture table by registering that name (card-tree drops such collisions at mount, and the viewer matches).
• Target a block from CSS with [data-block-kind="table"] or [data-block-key="body"].

Canonical wiring

import { useRef, useState } from "react";
import { Dialog, DialogContent } from "@/components/ui/dialog";
import { FlowCanvas, updateNodeData } from "@ilinxa/flow-canvas";
import { CardTree, type CardTreeHandle } from "@ilinxa/card-tree";
import { cardTreeViewerRenderer } from "@ilinxa/card-tree-node";

const RENDERERS = [cardTreeViewerRenderer]; // module-scope!

export function MyCanvas() {
  const [canvas, setCanvas] = useState(initialData);
  const [editing, setEditing] = useState<
    { nodeId: string; subPath?: string } | null
  >(null);
  const cardTreeRef = useRef<CardTreeHandle>(null);

  return (
    <>
      <FlowCanvas
        data={canvas}
        onChange={setCanvas}
        renderers={RENDERERS}
        onEditRequest={(nodeId, subPath) => setEditing({ nodeId, subPath })}
      />
      <Dialog open={editing !== null} onOpenChange={(o) => !o && setEditing(null)}>
        <DialogContent aria-describedby={undefined}>
          {editing && (
            <CardTree
              key={editing.nodeId}                       // clean remount
              ref={cardTreeRef}
              defaultValue={canvas.nodes.find(n => n.id === editing.nodeId)!.data}
              editable={true}
              onChange={(next) =>
                setCanvas((prev) => updateNodeData(prev, editing.nodeId, next))
              }
            />
          )}
        </DialogContent>
      </Dialog>
    </>
  );
}

Subcard-level edit targeting (the subPath model)

The renderer fires ctx.onEditRequest?.(subPath?) wheresubPath is the clicked subcard's __rcid (card-tree's canonical card identifier). The host bubbles to FlowCanvasProps.onEditRequest?.(nodeId, subPath) verbatim — pass it through to your dialog. Inside the dialog, focus the targeted subcard via the imperative ref:

// Run after the dialog opens + CardTree has mounted.
useEffect(() => {
  if (editing?.subPath) cardTreeRef.current?.focusCard(editing.subPath);
}, [editing?.subPath, editing?.nodeId]);

F-02 lock — CardTreedoesn't expose aninitialFocusCardId prop today; the imperativeCardTreeHandle.focusCard(id) via ref is the only way to pre-focus a specific subcard. A v0.2 polish on card-tree may add a prop if consumers signal friction.

When __rcid is missing on a subcard

Rich-card auto-attaches __rcidon parse — so a consumer-defined fixture that hasn't been through <CardTree> once may carry subcards without IDs. The viewer renders them normally but disables click-to-focus on those subcards; clicking falls through to the root edit. Dev mode logs a console.warn pointing at the affected subcard. Pass the canvas data through <CardTree>once at boot OR attach IDs manually with card-tree's ID helper.

Multi-select on the canvas

n8n-style multi-select (marquee + shift-click) works out of the box — flow-canvas hosts the selection. Clicking-to-edit on the clicked node opens the dialog on THAT node; the other selected nodes stay selected for canvas-level operations (move, delete, duplicate). Bulk EDIT (single op applied across selection) is not implemented.

v0.1 viewer limits

• Title — data.titleif non-empty string, else first non-reserved string flat field, else "Untitled card-tree".
• Flat fields — first 3 entries that are boolean / number / ISO-8601 date string / plain string (by Object.entries order). Numbers right-aligned, dates formatted via Intl.DateTimeFormat, booleans as ✓ / —.
• Nested cards — up to 4 subcards painted as outlines with their own port handles; one level deep. v0.2 may make these configurable via CardTreeViewerOptions.
• Edit trigger — single click. v0.2 escape hatch (editTrigger?: "click" | "doubleClick") if a consumer surfaces real conflict.

Port editing (v0.2 — <PortEditorStrip>)

v0.2 ships an opt-in PortEditorStrip for editing theports[] array of a card or subcard inline. Mount it alongside <CardTree editable> inside your dialog — the strip is uncontrolled (operates on the canvas prop) and live-saves on every mutation.

import {
  PortEditorStrip,
  type PortEditorPermissions,
} from "@ilinxa/card-tree-node";

// inside the dialog body — strip above CardTree per Q1 lock
{editing && (
  <>
    <PortEditorStrip
      nodeId={editing.nodeId}
      subPath={editing.subPath}     // targets root if undefined; subcard by __rcid
      canvas={canvas}
      onChange={setCanvas}
      editable={true}
      // v0.5 — the THIRD surface that needs your registrations. Same array
      // you pass to createCardTreeViewerRenderer() and to <CardTree>.
      customPredefinedKeys={CUSTOM_KEYS}
      // optional — gates affordances when supplied
      permissions={{
        canAddPort: (cardId) => true,
        canRemovePort: (cardId, portId) => portId !== "p-locked-port",
        canEditPortField: (cardId, portId, field) =>
          field !== "id" || portId.startsWith("p-user-"),
      }}
    />
    <CardTree editable defaultValue={...} customPredefinedKeys={CUSTOM_KEYS} />
  </>
)}

v0.5 (FU-A) — pass your registrations here too.The strip walks the node's data tree to find the card named by subPath, and through v0.4 it decided what counted as a card by inspecting each value for __rcid or a portsarray. That disagreed with the renderer in both directions: a child card you hadn't yet round-tripped through <CardTree> was drawn on the canvas but unreachable here, and a registered block whose payload happened to carry ports was walked into as if it were a card — so a port edit could land inside a block payload. It now classifies keys with the same router the viewer uses, which is why it needs the same customPredefinedKeys (and disabledPredefinedKeys) you give the renderer. Both types are imported from @ilinxa/card-tree. Omitting them is safe only if you register nothing.

Direction multi-select on add: check [✓in],[✓out], or both. Both creates two atomic ports sharing type / side / multi / label with -in /-out id suffixes. After save, the two ports are independent rows in the editor — no auto-grouping (Q3 lock).

Doc-port type (v0.2.5 of flow-canvas — new built-in "doc" port type): forced to side: "bottom"in the editor picker. Targets (doc files) don't exist yet — doc-typed ports are orphan slots until a future doc-file procomp ships.

Live-save model: every change calls onChange(updatedCanvas). No commit/cancel button. Selects + checkbox commit on change; id and label inputs commit on blur (id renames have edge implications). Renaming a port with live edges surfaces a tooltip warning; the rename still commits but the consumer must update edge references manually.

Custom port-type registration in the strip's picker is not implemented — it needs shared-context plumbing — v0.2 uses the 6 defaults only. Per-field ports(a flat field IS a port) is also a v0.3 lift; in v0.2 you add ports via the strip's "+ add port" affordance independently from any field.

Footguns

• Port IDs must be unique within the node— including across subcards. flow-canvas's port-walker returns the first match for a given ID; duplicates silently mis-route edges. Dev mode warns when a duplicate is detected on viewer mount.
• position: relative is load-bearing at every DOM level (NodeShell, CardTreeViewer outer, SubcardBlock) — xyflow's <Handle> is position: absolute and anchors to the nearest positioned ancestor. If you fork the viewer and drop relative, subcard handles silently fly to the wrong parent.
• Don't use Radix <Dialog.Portal forceMount>— it defeats the "at most one editor mounted" property. shadcn's default <Dialog> unmounts content on close, which is what makes the perf claim hold.
• Subcards aren't drag-extractable in v0.1— they're part of one card-tree tree per node by design (Q1 lock); flow-canvas's data-draggable-subobject pattern won't work on subcards. v0.2 candidate if a consumer asks.

Full reference: docs/procomps/card-tree-node-procomp/ (description, plan, guide). Companion components: @ilinxa/flow-canvas@^0.2.1 (host; requires v0.2.1+ for onEditRequest) and @ilinxa/card-tree@^0.4.0 (editor).