PSA/ee/docs/plans/2026-02-04-project-materials-drawer/SCRATCHPAD.md

Project Materials Drawer - Scratchpad

Initial Discovery (2026-02-04)

Related Work

• Ticket Materials PR #1701 (merged 2026-01-29): 328eff8b0 - "feat: implement ticket materials with multi-currency"
• Tag Filter Fix: 6057c5bd0 - "Fix tag filter to preserve colors and clean orphans"

Architecture Decision: Component Location

Pattern Discovered: TicketMaterialsCard lives in @alga-psa/tickets, NOT in @alga-psa/billing.

Decision: Keep ProjectMaterialsDrawer in @alga-psa/projects and add @alga-psa/billing as a dependency.

Rationale:

• Follows established pattern (TicketMaterialsCard in tickets, imports from billing)
• Feature modules keep their UI components
• Import actions from the domain owner (billing)

Required Package Change

packages/projects/package.json needs:

"dependencies": {
  "@alga-psa/billing": "*",
  // ... existing
}

Existing Infrastructure

Server Actions (Already Exist!)

Located in packages/billing/src/actions/materialActions.ts:

• listProjectMaterials(projectId) - Returns IProjectMaterial[] with service_name and sku joined
• addProjectMaterial(input) - Creates new material (rate in cents, quantity floored to min 1)
• deleteProjectMaterial(projectMaterialId) - Deletes if not billed

All actions are already exported from @alga-psa/billing/actions.

Data Model

IProjectMaterial interface (packages/types/src/interfaces/material.interfaces.ts):

• project_material_id: string - Primary key
• project_id: string - Foreign key to project
• client_id: string - Foreign key to client (for billing)
• service_id: string - Foreign key to service_catalog (product)
• service_name?: string - Denormalized from service_catalog
• sku?: string | null - Product SKU
• quantity: number
• rate: number - Price in cents
• currency_code: string - ISO 4217 currency code
• description?: string | null
• is_billed: boolean

Key Files

File	Purpose
packages/projects/package.json	Add billing dependency
packages/projects/src/components/ProjectMaterialsDrawer.tsx	Implement drawer
packages/tickets/src/components/ticket/TicketMaterialsCard.tsx	Reference impl
packages/billing/src/actions/materialActions.ts	Actions (complete)

---

Decisions Log

Date	Decision	Rationale
2026-02-04	Keep component in projects package	Follows TicketMaterialsCard pattern
2026-02-04	Add @alga-psa/billing dependency	Required for material actions
2026-02-04	12 features, 18 tests	Streamlined from initial 41/78

---

Updates

• 2026-02-04: Added @alga-psa/billing dependency to packages/projects/package.json for project materials drawer actions.
• 2026-02-04: Added drawer header scaffold and set project materials drawer width to 560px via openDrawer.
• 2026-02-04: Wired ProjectMaterialsDrawer to listProjectMaterials with loading and empty states.
• 2026-02-04: Added materials table layout with product, SKU, qty, rate, total, and status badge columns.
• 2026-02-04: Added per-currency unbilled totals summary to support multi-currency projects.
• 2026-02-04: Implemented add-form product picker with searchable catalog lookup.
• 2026-02-04: Added price/currency selector with auto-selected first price and multi-price dropdown.
• 2026-02-04: Added quantity/description inputs and live total display to the add form.
• 2026-02-04: Implemented add-material submission with validation, toast feedback, and list refresh.
• 2026-02-04: Added delete action for unbilled materials with toast feedback and reload.
• 2026-02-04: Allowed materials drawer to open without a client and display a no-client warning while hiding the Add button.
• 2026-02-04: Wrapped drawer content in ReflectionContainer and added automation IDs for key elements.
• 2026-02-04: Added T001 test to assert billing dependency in projects package.json.
• 2026-02-04: Added T002 test to assert ProjectInfo opens materials drawer with 560px width.
• 2026-02-04: Added T003 test to verify loading state while materials fetch is pending.
• 2026-02-04: Added T004 test to verify empty state when no materials are returned.
• 2026-02-04: Added T005 test to verify table columns and material row content.
• 2026-02-04: Added T006 test to verify Pending/Billed badge rendering.
• 2026-02-04: Added T007 test to verify currency formatting from minor units.
• 2026-02-04: Added T008 test to verify per-currency unbilled totals summary.
• 2026-02-04: Added T009 test to ensure product picker loads catalog items.
• 2026-02-04: Added T010 test to ensure price selector options appear after product selection.
• 2026-02-04: Added T011 test for quantity default/min validation.
• 2026-02-04: Added T012 test for total recalculation on quantity/currency changes.
• 2026-02-04: Added T013 test to verify add-material submission and list refresh.
• 2026-02-04: Added T014 test to verify validation toasts for missing product/price.
• 2026-02-04: Added T015 test to ensure delete controls only show for unbilled items.
• 2026-02-04: Added T016 test to verify delete action triggers list refresh.
• 2026-02-04: Added T017 test to verify no-client warning and Add button suppression.
• 2026-02-04: Added T018 test to verify automation IDs on key elements.
• 2026-02-04: Adjusted add button to allow validation toasts without disabling, and aligned vitest aliases for @alga-psa/projects.
• 2026-02-04: Added vitest alias for @alga-psa/tags and ensured RTL cleanup between drawer tests.
• 2026-02-04: Added explicit data-automation-id wrappers for quantity/description fields and mocked TagManager in tests.
• 2026-02-04: Test run: npx vitest --run packages/projects/tests/packageDependencies.test.ts packages/projects/tests/projectInfoDrawer.test.tsx packages/projects/tests/projectMaterialsDrawer.test.tsx (passes; warnings about act()).