Predefined Elements, Placements & Multi-Step Quote Wizard

Overview

Two builder enhancements ship in this release: predefined elements and placement configuration let products load with ready-to-customize text and graphic slots (e.g. team name, player number, chest logo) from database-driven rules; and the multi-step quote wizard replaces the single-shot quote form with a guided flow (auth, contact, order, address, notes) to improve completion rates and data quality.

Predefined Elements & Placement

Design Load with Product Element Rules

When a user enters the builder for a product, the form is seeded with predefined customization elements from the product_element_rules table. Each enabled rule:

Text elements — Inserted into text.items with default styles (font, size, color, outline) and placement
Image elements — Inserted into graphics.items with default placement and editable slot

Elements are idempotent: if a restored draft already contains the same element-{id} items, they are not duplicated.

Element Data Flow

Source	Purpose
`product_element_rules`	Per-product rules linking to `customization_elements`
`customization_elements`	Element metadata: name, code, type (text/image), default styles, allowed placements
`placements`	Anchor coordinates (`anchor_x`, `anchor_y`) for each placement code
`text-placement.ts` / `graphics-placement.ts`	Map placement codes to canvas positions; DB placements override hardcoded presets

Placement Configuration

Database-first — placements table stores code, anchor_x, anchor_y, surface, applies_to (text/image), bounds, rotation defaults
Fallback — Hardcoded presets (e.g. back-top, front-chest, chest-center) used when no DB placements exist
Canonical space — 2048×2048 UV texture space; text uses center origin; graphics use placement config
Arc text — getArcPathSvgPath() builds semicircle paths for curved text along placement anchors

Builder Integration

BuilderPage fetches productElementRules and placements in parallel via loadBuilderElementData()
BuilderDataContext seeds text/graphics items in a useEffect after rules load
text-step and graphics-step filter placements by applies_to (text vs image) for their selectors
fabric-canvas-view uses getPlacementPosition() and getGraphicPlacementPosition() with DB placements for rendering

Multi-Step Quote Wizard

Wizard Steps

Step	Component	Purpose
0. Auth Gate	`QuoteAuthGate`	Guests sign in or sign up; skips when user is authenticated
1. Contact	`QuoteContactStep`	Full name, email, phone, company — pre-filled from account
2. Order Context	`QuoteOrderStep`	Event date, rush order flag, delivery method (standard/express/pickup)
3. Address	`QuoteAddressStep`	Shipping address; optional billing (same-as-shipping toggle)
4. Notes	`QuoteNotesStep`	Special instructions; final submit button

Flow Behavior

Step validation — Each step validates only its fields (ContactStepSchema, OrderStepSchema, AddressStepSchema) before advancing
Progress bar — Visual indicator for authenticated users; hidden on auth gate
Back navigation — From Contact or Auth, returns to review summary; from other steps, returns to previous step
Success confirmation — Shows quote number and links to /home/quotes; option to start a new design

Technical Details

Schema — QuoteRequestSchema (Zod) validates full payload; per-step schemas for incremental validation
Server action — submitQuoteAction() receives quote data + builderData (design, colors, text, graphics) for line-item creation
Translations — builder:quoteForm.* keys for labels, validation messages, confirmation copy

Integration Points

File	Feature
`builder/[sport]/[productSlug]/page.tsx`	Loads element rules and placements
`builder-data-context.tsx`	Seeds text/graphics from `productElementRules`
`text-placement.ts`, `graphics-placement.ts`	Placement position lookup
`quote-form-wizard.tsx`	Orchestrates multi-step flow
`quote-contact-step.tsx`, `quote-order-step.tsx`, etc.	Per-step form fields
`quote-request.schema.ts`	Validation schemas
`submit-quote.action.ts`	Server-side quote creation

Database Dependencies

product_element_rules — Links products to customization elements with default placement and style overrides
customization_elements — Element definitions (name, code, type, default_styles, allowed_placements)
placements — Placement slots with anchor coordinates and applicability (text/image)
quotes, quote_line_items — Quote storage (see cut-pattern-and-quotes changelog)