PSA/ee/docs/plans/2026-02-13-invoice-designer-native-css-layout-engine/PRD.md

PRD — Invoice Designer Native CSS Layout Engine (Flex/Grid + dnd-kit)

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

Summary

Replace the invoice designer's custom geometry and constraint-math layout engine with native browser layout (CSS Flexbox/Grid + standard CSS features like aspect-ratio). Replace custom drop-parent resolution math with @dnd-kit/core collision detection based on DOM measurements.

The designer should map layout intent to CSS rules, and let the browser compute sizes, alignment, and bounding boxes.

Problem

Current designer behavior relies on a custom coordinate/constraint system for:

• drop target resolution and nesting decisions
• spatial constraints and edge case math
• aspect ratio enforcement
• manual layout calculations

This creates high maintenance cost, hard-to-debug geometry bugs, and divergence from how invoices render in the real HTML/CSS world.

Insight

All spatial constraints, aspect ratios, and grid layouts are special cases of the browser's native layout engine.

Goals

• Represent layout properties in the designer as native CSS semantics (flex/grid/box model).
• Compute all layout and bounding boxes using DOM layout, not custom math.
• Use @dnd-kit/core collision detection for drop placement and nesting.
• Preserve or improve current designer UX for:
  • dragging nodes
  • reordering nodes in a container
  • moving nodes across containers
  • resizing nodes (where supported)
  • aspect ratio for images and fixed-ratio blocks
• Keep designer preview output consistent with invoice rendering output (HTML/CSS).
• Delete the custom geometry/constraint layers listed below.

Non-goals

• Building a full “Figma-like” layout engine (guides, autolayout inference, advanced snapping).
• Supporting arbitrary custom physics/geometry behavior in drag-drop.
• Reworking unrelated invoice-template AST or billing flows beyond the designer canvas/layout editing.

Users and Primary Flows

Primary personas:

• Billing admins composing invoice layout in the visual designer.
• Implementers maintaining the designer and renderer.

Primary flows:

1. Drag a node into a container
2. Reorder nodes within a container
3. Move a node between containers
4. Adjust container layout mode (column/row/grid) and spacing
5. Set sizing constraints using CSS primitives (width, min/max, flex, grid)
6. Enforce aspect ratio for images (and optionally other nodes)
7. Preview invoice output using the same HTML/CSS semantics used for rendering/PDF

UX / UI Notes

• Replace “constraint” concepts with a “Layout” panel that edits CSS-like properties.
• Layout modes:
  • Stack (flex column/row)
  • Grid (CSS grid)
  • Freeform/absolute positioning is out of scope
• Expose a small, safe subset of properties first:
  • container: direction, gap, align, justify, padding, border
  • item: width/height, min/max, flex grow/shrink/basis
  • grid: columns (template), rows (template), auto-flow, gap
  • image: aspect-ratio and object-fit
• Drop indicators should be based on DOM geometry (closest edges, insertion index).
• Snapping:
  • edge snapping within a container (before/after insertion positions)
  • grid snapping when a parent container is in grid mode

Interaction Semantics

• Resizable node types (by drag handles):
  • image
  • container blocks: section, stack
• Non-resizable by drag handles (size naturally; configurable via spacing/layout):
  • text, field, divider, totals, table, dynamic-table
  • No table column resizing.
• Resize units:
  • Drag handles update pixel values only (e.g. width: 320px, height: 180px, flex-basis: 240px).
  • The property panel may accept CSS strings (e.g. %, rem, auto) for advanced control.
  • For flex children, resizing along the main axis should prefer flex-basis over width/height.
• Nesting model:
  • Containers (droppable-into): document, section, stack, grid (if represented as a node/type).
  • Leaf nodes (droppable-between only): text, field, image, divider, totals, table, dynamic-table.
• Drag-drop is discrete, not coordinate-based:
  • Drop resolves to targetContainerId + insertionIndex (no "drop at x,y" semantics).
• Basic snapping definition:
  • Flex: snap to before/after sibling insertion indices.
  • Grid: snap to a deterministic cell/index insertion derived from grid tracks, not arbitrary pixel snapping.

Requirements

Functional Requirements

• Canvas layout should be computed by CSS (flex/grid), not custom math utilities.
• Each designer node type that participates in layout must have a deterministic mapping:
  • Designer layout state -> DOM element style -> rendered geometry
• Drag/drop must use @dnd-kit/core with collision detection derived from DOM measurements.
• Drop-parent resolution must support:
  • inserting before/after siblings
  • nesting into eligible containers
  • rejecting invalid drop targets with clear UX
• Resizing (if present today) should rely on DOM measurement + CSS properties (not constraint solving).
• Aspect ratio enforcement must use CSS aspect-ratio (and/or intrinsic image sizing), not JS math.
• Snapping must be discrete (insertion/cell selection), not freeform coordinate snapping.
• Drag-drop implementation guidance:
  • Prefer @dnd-kit/sortable for within-container ordering and insertion-index snapping.
  • Collision detection:
    • Use pointerWithin first (select the deepest eligible droppable under the cursor).
    • Fallback to closestCenter when the pointer is not within any droppable (fast drags / overlays).
    • Use dnd-kit measuring configured to keep rects fresh during drag (avoid stale geometry in nested layouts).
  • Sensors and overlays:
    • Use PointerSensor with an activation distance (e.g. 6px) to avoid accidental drags.
    • Use DragOverlay so dragging does not reflow layout.
  • Sorting strategies:
    • Flex column: verticalListSortingStrategy
    • Flex row: horizontalListSortingStrategy
    • Grid: rectSortingStrategy
  • Snapping thresholds:
    • Flex insertion uses the midpoint rule on the hovered item's rect (before/after); avoid additional pixel snapping math.
    • Grid insertion uses the sortable over resolution directly (deterministic cell/index selection).
• The delete list modules must be removed from the runtime dependency graph:
  • utils/constraintSolver.ts
  • utils/constraints.ts
  • utils/dropParentResolution.ts
  • utils/aspectRatio.ts
• utils/layout.ts should be reduced to lightweight mapping/helpers, not geometry solvers.

Non-functional Requirements

• Behavior should remain stable across preview and PDF (headless Chromium) since both are HTML/CSS.
• Drag-drop interactions should remain responsive for typical template sizes (tens to low hundreds of nodes).
• Errors should be surfaced as structured, actionable messages (invalid container, invalid nesting, etc.).

Deleted / Eliminated Layers

• packages/billing/src/components/invoice-designer/utils/constraintSolver.ts
• packages/billing/src/components/invoice-designer/utils/constraints.ts
• packages/billing/src/components/invoice-designer/utils/dropParentResolution.ts
• packages/billing/src/components/invoice-designer/utils/aspectRatio.ts

And eliminate “thousands of lines” of bespoke coordinate math and geometry edge cases.

Rollout / Migration

• No tenant templates require migration (no custom templates in production yet).
• Internal-only cutover is acceptable as long as parity holds for the “standard templates” designer output.

Risks

• CSS semantics may not exactly match legacy constraint behavior for edge cases.
• Drag-drop collision strategies can change perceived drop target behavior; needs UX tuning.
• Print/PDF layout differences vs. in-app preview if the preview container differs (scale, margins).

Acceptance Criteria (Definition of Done)

• Designer canvas uses DOM layout (flex/grid) for geometry; no constraint solver usage.
• Drag/drop uses @dnd-kit/core and supports reorder + cross-container move + nesting.
• Aspect ratio uses CSS aspect-ratio for images (and any other nodes requiring it).
• Resizing works using CSS sizing props (width/height/min/max/flex/grid), with no constraint solving.
• Snapping works (edge snapping for insertion/reorder and grid snapping for grid containers).
• Nesting rules are enforced via an explicit allowlist and covered by automated tests.
• Drag-drop resolves to container + insertion index only (no coordinate persistence).
• Removed modules are deleted and no longer referenced.
• Visual designer output renders consistently with the invoice renderer (HTML/CSS preview parity).
• Automated tests cover drag-drop behaviors, nesting rules, and deletion of legacy utilities.