PSA/ee/docs/plans/2026-04-01-designer-ux-and-quote-bindings/PRD.md

PRD — Designer UX Improvements & Quote Collection Bindings

• Slug: designer-ux-and-quote-bindings
• Date: 2026-04-01
• Status: Draft

Summary

Make the invoice/quote template designer intuitive enough for non-technical users to create complex layouts (multi-column headers, side-by-side notes+totals, separate recurring/one-time tables) without knowing CSS syntax. Then extend the quote binding system so templates can separate line items by recurring vs one-time and services vs products.

Problem

The designer has powerful layout capabilities (full CSS flex/grid). Visual icon toggle buttons already exist for flex direction, justify content, and align items (in DesignerShell.tsx renderContainerLayoutControls). However:

• Grid mode is a dead end — switching to Grid layout shows no controls (flex controls are hidden, no grid-specific controls appear)
• Grid columns require typing "1fr 2fr" or "repeat(3, 1fr)" in the inspector text input — no visual picker
• Spacing (gap, padding, margin) requires typing CSS strings like "0 0 12px 0" in the inspector
• No grid presets — only flex-based layout presets exist in the palette
• Layout controls only appear for container type — not for section nodes

For quotes specifically:

• Only 2 collection bindings exist (lineItems, phases) — no way to bind a table to just recurring items or just one-time items
• No per-group aggregates (recurring subtotal/tax/total vs one-time subtotal/tax/total)
• The data model already has is_recurring, billing_frequency, and service_item_kind on line items but the template system doesn't expose filtered views

Goals

1. Add grid-specific controls (column layout picker) so grid mode isn't a dead end
2. Add visual spacing controls with stepper + unit selector for gap/padding/margin
3. Add grid-based layout presets to the palette
4. Extend quote template bindings with filtered collections and per-group aggregates
5. Surface new bindings in the designer palette so users can discover them

Non-goals

• Conditional rendering / show-hide based on data (future work)
• Drag-to-resize columns within a grid (stays manual via properties)
• Quote workflow changes (acceptance, approval) — out of scope
• New quote template design (separate follow-up after bindings ship)
• Responsive/mobile layouts — templates target fixed-size PDF output

Users and Primary Flows

Primary user: MSP admin designing invoice/quote templates in the billing settings area.

Flow 1 — Create a multi-column layout:

1. User selects a container/section in the canvas
2. In the inspector Layout panel, they see a visual column picker (1-col, 2-col equal, 2-col sidebar+main, 3-col)
3. Click a column preset → container switches to grid with appropriate gridTemplateColumns
4. Drag child elements into the grid cells

Flow 2 — Adjust flex layout visually:

1. User selects a flex container
2. Direction shown as icon toggle (↕ vertical / ↔ horizontal) instead of dropdown
3. Justify/align shown as icon button groups (visual representations of start/center/end/space-between)
4. Gap/padding shown as stepper with unit dropdown (px/%)

Flow 3 — Build a quote with separate recurring/one-time tables:

1. User drags two dynamic-table elements onto the canvas
2. First table: set collection binding to "Recurring Items" from dropdown
3. Second table: set collection binding to "One-time Items"
4. Add field elements for recurringTotal and onetimeTotal from the Fields palette tab

UX / UI Notes

Visual Layout Controls (replacing dropdowns)

Already implemented: Flex direction, justify content, and align items are already icon toggle buttons in DesignerShell.tsx renderContainerLayoutControls(). See screenshot in planning context.

Column Layout Picker (New — fills the grid mode gap)

Visual grid of clickable preset cards in the Layout panel (when display is grid or when first choosing):

• [ 1 ] — Single column (full width)
• [ 1 | 1 ] — Two equal columns
• [ 1 | 2 ] — Sidebar + main (1fr 2fr)
• [ 2 | 1 ] — Main + sidebar (2fr 1fr)
• [ 1 | 1 | 1 ] — Three equal columns

Clicking a preset:

1. Sets layout.display to grid
2. Sets layout.gridTemplateColumns to the corresponding value
3. Raw CSS input stays visible below for power users who want to customize

Spacing Controls

Replace raw CSS text inputs for gap, padding, margin with:

• Numeric stepper (up/down arrows, or type a number)
• Unit dropdown beside it: px (default), %, rem
• Value stored as combined string (e.g., "16px")
• For margin: four individual steppers (top, right, bottom, left) with a "link" toggle to set all at once

New Layout Presets in Palette

Add to the existing preset system:

• "Notes + Totals Row" (Body) — 2-col grid: wide notes left, narrow totals right
• "Two Equal Columns" (Body) — 2-col grid section
• "Three Info Columns" (Body) — 3-col grid for info cards
• "Recurring + One-time Tables" (Body, quote-specific) — Two stacked dynamic tables pre-bound to recurringItems and onetimeItems

Requirements

Functional Requirements

Phase 1: Visual Layout Controls

Already done: Flex direction, justify content, and align items icon toggle buttons exist in DesignerShell.tsx renderContainerLayoutControls() (lines 1019-1098). These render for container nodes when display is flex.

FR-0 Independent Panel Scrolling (palette + inspector + canvas)

• Problem: The 3-panel row (palette | canvas | inspector) is inside flex flex-1 min-h-[560px] (line 1830). Neither the inspector nor the canvas area constrains its height, so when content overflows, the whole page scrolls, pushing the canvas out of view.
• Palette bug: The palette has a fixed top-0 floating mode that triggers when rect.top <= 0 (line 703), but it pins to the browser viewport top, overlapping the app header/navbar. This causes a jarring jump visible in the screenshot.
• Fix approach: Replace the palette's floating/fixed hack with proper CSS layout:
  • Make the 3-panel flex row fill available viewport height (h-full / flex-1 with overflow-hidden on parent)
  • Each panel (palette, canvas, inspector) gets overflow-y-auto independently
  • Remove the isPaletteFloating / fixed top-0 logic entirely — no longer needed when panels scroll within their own bounds
  • Canvas area scrolls independently (it already has its own scroll context via DesignCanvas)
• Result: User can scroll the inspector to reach column settings while the canvas stays visible. User can scroll the palette without it jumping over the header.

FR-1 Grid Column Layout Picker

• Add a visual column picker widget to the Layout panel
• 5 preset options: 1-col, 2-equal, sidebar+main, main+sidebar, 3-equal
• Clicking a preset sets layout.display: 'grid' and layout.gridTemplateColumns accordingly
• Show below the Mode selector, visible when node is a container
• Raw grid CSS inputs remain available below the picker for customization
• Active preset highlighted based on current gridTemplateColumns value

FR-2 Spacing Stepper Controls

• Replace css-length text inputs for gap, padding with numeric stepper + unit selector
• Stepper: number input with up/down increment buttons (step: 1 for px, 0.25 for rem, 1 for %)
• Unit dropdown: px (default), %, rem
• Parse existing CSS values on load (e.g., "16px" → value: 16, unit: "px")
• Write back as combined string (e.g., "16px")

FR-3 Margin Controls

• Replace single margin css-length input with four individual stepper fields (top, right, bottom, left)
• "Link all" toggle button — when linked, changing one value changes all four
• Parse existing shorthand on load (e.g., "8px 16px" → top:8, right:16, bottom:8, left:16)
• Write back as shorthand

FR-4 New Layout Presets

• Add 3-4 new grid-based presets to LAYOUT_PRESETS array
• Each uses CSS grid layout (not legacy flex mode)
• Presets appear in the Presets tab of the palette alongside existing ones

Phase 2: Quote Collection Bindings

FR-5 Filtered Collection Bindings

• Add to QUOTE_TEMPLATE_COLLECTION_BINDINGS:
  • recurringItems → filters line_items where is_recurring === true
  • onetimeItems → filters line_items where is_recurring !== true
  • serviceItems → filters line_items where service_item_kind === 'service'
  • productItems → filters line_items where service_item_kind === 'product'
• These are virtual collections computed at render time from the full line_items array

FR-6 Per-Group Aggregate Value Bindings

• Add to QUOTE_TEMPLATE_VALUE_BINDINGS:
  • recurringSubtotal, recurringTax, recurringTotal
  • onetimeSubtotal, onetimeTax, onetimeTotal
  • serviceSubtotal, serviceTax, serviceTotal
  • productSubtotal, productTax, productTotal
• Computed from filtered line item groups

FR-7 Quote View Model Computation

• Extend QuoteViewModel type with:
  • recurring_items, onetime_items, service_items, product_items (filtered arrays)
  • recurring_subtotal, recurring_tax, recurring_total (aggregates)
  • onetime_subtotal, onetime_tax, onetime_total
  • service_subtotal, service_tax, service_total
  • product_subtotal, product_tax, product_total
• Computed in mapLoadedQuoteToViewModel() from the line items

FR-8 Collection Dropdown Discovery

• Table editor widget collection selector should list new filtered collections
• These come automatically from the AST bindings (already works via baseAst.bindings.collections enumeration)

FR-9 Fields Palette Discovery

• New value bindings appear in the Fields tab of the component palette
• Grouped under a "Quote Totals" or similar category
• Existing invoice expression context adapter may need quote-specific extension

Non-functional Requirements

• All new controls must work in both light and dark theme
• Inspector panel vertical space should not increase significantly (use compact controls)
• Existing templates must render identically (no regression)
• New field kinds must follow the existing normalizer pattern

Data / API / Integrations

No database changes. The filtered collections and aggregates are computed at render time from existing line_items data in the QuoteViewModel.

Type changes:

• QuoteViewModel interface in packages/types/src/interfaces/quote.interfaces.ts — add optional filtered arrays and aggregate fields
• QuoteViewModelLineItem — no changes (already has is_recurring, service_item_kind)

Security / Permissions

No changes — template editing already gated by billing admin permissions.

Rollout / Migration

• Existing templates unaffected — new controls write the same CSS property values
• New quote bindings are additive — old templates that don't reference them work fine
• No migration needed — the filtered collections are computed on-the-fly

Open Questions

1. Should margin controls always show 4 fields or start collapsed? Propose: start as single field, expand to 4 when user clicks "expand" or when shorthand has different values per side.
2. Should the column picker also add child containers? Propose: no, just set the grid template. Users drag content into cells.
3. Quote fields palette grouping — should filtered collection totals show under "Quote" category or a new "Quote Totals" sub-category?

Acceptance Criteria (Definition of Done)

1. A non-technical user can create a 2-column layout by clicking a visual preset (no CSS typing)
2. Flex direction, justify, and align are all icon-based controls
3. Gap/padding use numeric steppers with unit selectors
4. Quote templates can bind tables to recurringItems or onetimeItems collections
5. Per-group totals (recurringTotal, onetimeTotal) are available as field bindings
6. All existing templates render identically (no visual regression)
7. New controls work in both light and dark theme
8. Fields palette shows new quote-specific bindings for discovery