PSA/ee/docs/plans/2026-02-13-invoice-designer-unified-component-ast/PRD.md

# PRD — Invoice Designer Unified Component AST (Generic Nodes + Schema-Driven Inspector)

- Slug: `invoice-designer-unified-component-ast`
- Date: `2026-02-13`
- Status: Planned
- Depends on:
  - `ee/docs/plans/2026-02-13-invoice-designer-native-css-layout-engine/`
  - `ee/docs/plans/2026-02-12-invoice-template-json-ast-renderer-cutover/`

## Summary

Refactor the invoice designer's internal canvas state from a typed, field-heavy `DesignerNode` model plus per-property actions into a single unified, immutable JSON tree:

- `Record<NodeId, { type: string, props: Record<string, unknown>, children: NodeId[] }>`

All mutations must go through a small, generic patch/mutation API (for example: `setNodeProp(id, 'style.width', '320px')`). This patch API is the primary enabler of the simplification: without it, the refactor becomes a re-shape with no velocity gain.

The Inspector (Property Editor) becomes schema-driven: it renders its controls by reading a component schema rather than being hardcoded per property or per component type.

## Problem

The designer's state model and editor UI are effectively coupled to specific property groups:

- Adding a new CSS-like property (for example `borderRadius`) requires new store wiring, bespoke reducer logic, dedicated inspector UI, and tests.
- Hierarchy and per-property concerns leak across multiple modules, creating sync logic, duplication, and drift.

This increases maintenance cost and slows iteration on layout and styling capabilities.

## Insight

Every visual element on the canvas is the same abstraction:

- a node with a `type`
- a `props` dictionary
- a list of `children`

Once the designer state is a generic tree, editing becomes a generic patch problem and the property editor becomes a schema rendering problem.

## Goals

- Represent the full designer workspace as a unified JSON tree with one source of truth.
- Replace per-property store actions (`updateNodeStyle`, `updateNodeLayout`, `updateNodeMetadata`, etc.) with a single generic patch/mutation API.
- Make the Inspector schema-driven so most new properties require only schema changes, not store changes.
- Move hierarchy rules (allowed parent/child types) out of `state/hierarchy.ts` into component schema definitions.
- Keep undo/redo, selection, drag-drop, and resizing behavior intact.

## Non-goals

- Changing invoice-template AST semantics or invoice renderer behavior.
- Implementing a general-purpose JSON Schema engine; the designer only needs a constrained, safe schema format.
- Building an expression language for arbitrary computation inside the designer.

## Users and Primary Flows

Primary personas:

- Billing admins composing invoice layout in the designer.
- Engineers adding new components and styling/layout properties.

Primary flows:

1. Add a component from the palette
2. Select a node and edit properties in the Inspector
3. Drag/drop to reorder and reparent nodes
4. Resize nodes (where supported) and see sizing properties updated
5. Save and preview templates

## UX / UI Notes

- Inspector panels should be generated from schema and grouped logically (Layout, Spacing, Sizing, Typography, Data Binding, Table Columns, etc.).
- Component-specific metadata editing (for example table columns) remains supported, but is driven by schema-based UI widgets (array editor, enum pickers, etc.).
- The palette and outline should be driven by the same component schema source of truth (labels, descriptions, defaults, hierarchy rules).

## Data Model

### Canonical Workspace Tree

Store source of truth:

- `rootId: NodeId`
- `nodesById: Record<NodeId, DesignerAstNode>`

Where:

- `DesignerAstNode = { id: NodeId, type: DesignerComponentType, props: Record<string, unknown>, children: NodeId[] }`

Notes:

- `children` is the only authoritative structure for the hierarchy.
- `parentId` is not persisted to avoid redundant data and sync bugs; parent is derived when needed.

### Props Conventions

Standardized props keys (conventions, not hard typing):

- `props.name: string` (designer display name)
- `props.style: Record<string, unknown>` (CSS-like style, same conceptual fields as today)
- `props.layout: Record<string, unknown>` (container layout: flex/grid subset)
- `props.metadata: Record<string, unknown>` (component-specific configuration)

### Mutations (Patch Operations)

Replace bespoke store actions with a small set of generic operations. This is a hard requirement for this strategy to pay off; implementing the unified node shape without the patch API does not meaningfully reduce complexity.

- `setNodeProp(nodeId, path, value)` where `path` is dot-notation like `style.width` or `metadata.bindingKey`
- `unsetNodeProp(nodeId, path)`
- `insertChild(parentId, childId, index)`
- `removeChild(parentId, childId)`
- `moveNode(nodeId, nextParentId, nextIndex)`
- `deleteNode(nodeId)` (removes subtree + fixes parent children list)

Implementation should use immutable updates (structural sharing) and preserve undo/redo behavior.

## Requirements

### Functional Requirements

- Designer store persists and exports the unified tree (not a list of typed nodes).
- Existing operations are supported through the generic patch/mutation API (no per-property store actions remain):
  - adding components from palette (uses schema defaults)
  - updating layout/style properties
  - updating component metadata (tables, totals, fields, etc.)
  - reparenting and reorder operations (drag-drop)
  - resizing nodes updates sizing-related props
- Inspector renders based on a component schema:
  - Field types: string, number, boolean, enum, css-length, css-color, object, array
  - Support custom widgets for complex props:
    - table columns editor
    - dynamic-table column bindings
    - rich text (optional, if already supported)
- Hierarchy allowlists are enforced by schema (allowed parents/children) and are the only authority.

### Non-functional Requirements

- Avoid performance regressions for typical template sizes (tens to low hundreds of nodes).
- Keep state history snapshots bounded (same behavior as today).
- Keep serialized workspace format deterministic and stable.

## Eliminated (Deleting Architectural Layers)

- `packages/billing/src/components/invoice-designer/state/hierarchy.ts`
- Dozens of special-case state slices and per-property actions (size, constraints, label text, etc.)
- Synchronization logic between hierarchy representations and property stores

## Rollout / Migration

- No tenant templates require migration (no custom templates in production yet).
- Workspace persistence format may change; update standard templates and designer storage accordingly.

## Risks

- A naive patch engine can accidentally allow invalid values (needs schema validation and normalizers).
- Some complex metadata editors (tables) require schema widgets beyond primitive fields.
- Refactor touches many call sites and tests; risk of regressions in drag-drop and undo/redo.

## Acceptance Criteria (Definition of Done)

- [ ] Designer state source of truth is `nodesById + rootId` with generic node shape (`type`, `props`, `children`).
- [ ] Store exposes a generic patch/mutation API (`setNodeProp`, `unsetNodeProp`, `moveNode`, etc.) as the only way to modify the tree; per-property update actions are removed.
- [ ] Inspector UI is generated from a schema and covers the existing editable properties.
- [ ] Palette defaults, inspector defaults, and hierarchy rules all come from the same schema source of truth.
- [ ] `state/hierarchy.ts` is deleted and no longer referenced.
- [ ] Undo/redo works correctly with patch operations.
- [ ] Drag-drop reorder and reparent operations update only the unified tree and remain covered by tests.
- [ ] Designer workspace import/export to invoice-template AST still roundtrips deterministically.