toga-ai 1.0.521 → 1.0.522

package/knowledge/sessions/2026-08-04-surface-approval-details-layout-apeterson.md

@@ -0,0 +1,69 @@
+---
+type: session
+slug: surface-approval-details-layout
+title: SalesOrder approval-details card — layout split, title, submitted-by suffix
+author: apeterson
+repos: [toga25-supply, dbchanges2]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-08-04
+updated: 2026-08-04
+---
+
+# Session: surface-approval-details-layout
+**Date:** 2026-08-04
+**Project/Repo:** toga25-supply (2.0) + dbchanges2 (Core SQL)
+**Task:** Reshape the SalesOrders record-modal approval-details card — separate approval-stage layout, surface-driven section title, and an inline "submitted by" title suffix — while keeping the surface/FE boundary clean.
+
+---
+
+## What WORKED
+<!-- Include specific file paths and evidence -->
+- **Two-layout component split** (approval vs standard). `SalesOrderView.tsx` branches on `isApprovalDetailsActive` → `SalesOrderApprovalSummaryGrid` (new) vs `SalesOrderSummaryGrid`. Approval grid: approval-details spans 3 cols, order-summary totals 1 col (`.approvalSummaryGrid`/`.approvalDetailsSpan`). Chosen over prop-driven branching because the difference is placement across the DOM tree, not styling. tsc -b clean on all touched files.
+- **Shared machinery extracted** so both grids reuse it: `helpers/sectionRenderers.tsx` (`createSectionRenderers` factory — detailSection/approvalDetails/locationCard/totalsCard) and `helpers/getVisibleSections.ts` (isVisible + visibilityRule + approval-suppression filter).
+- **Section relocation in approval view** via `getDetailSections.tsx`: Order Details + Bill To move below the Items table, side-by-side (Order Details first, then Bill To — user reordered); Admin Notes moves to the TOP of the modal (rendered in `SalesOrderView`, suppressed from below-items). Guarded so absent sections don't throw for non-approval clients.
+- **Surface-driven 2-col field grid** for the approval-details card (`.approvalFieldsGrid` = `repeat(2, minmax(0,1fr))`), reflows via BaseDetailField's `grid-column: span var(--field-col-span,1)`.
+- **Section title** wired end-to-end from surface: confirmed resolver emits `titleMessageKey` from `Core.Surfaces.titleMessageId` (`_underscore/Model/Core/Surface.php:634-635`); `buildSection` already resolves `sectionTitle` from it — so it's a pure DB change. Migration `dbchanges2/Core/2026-08-04a - ApprovalDetailsSectionTitle.sql` inserts the message + links the surface.
+- **"Submitted by {name}" title suffix**: added a `config.role: 'titleSuffix'` marker pattern. `buildSection` pulls that element OUT of the grid fields and exposes `section.titleSuffix = {label, valueKey}`; the `approvalDetails` renderer draws it inline in the `<h2>` (dot-path value resolve), styled `.cardTitleSuffix` (muted/italic). Migration `2026-08-04b` stamps the role on the `createdByUser._name` element. tsc clean.
+
+## What did NOT work — DO NOT RETRY THESE
+<!-- Exact failure reasons — do not vague-ify -->
+- **Surface-driving grid GEOMETRY (column count + per-field colSpan) via surface config.** Tried `config.columns` on the surface + `config.colSpan` on elements. Dead end: the resolver's `CONFIG` SurfaceOverride REPLACES an element's whole config blob rather than merging (`_underscore/Model/Core/Surface.php` ~L827: `$config = $value`). So per-client colSpan would force adding a first-class `COL_SPAN` to the `SurfaceOverrides.attribute` ENUM + resolver + schema + framework deploy — far too much machinery for "this box is 2 columns wide". Reverted ALL of it (deleted the columns migration, removed the adapter passthroughs and `--approval-cols` var). Geometry is FE-driven; the 2-col grid is a fixed CSS choice. See KB memory `surface-vs-fe-layout-boundary`.
+- **Stable-sort reorder to float approval-details to the front of the shared summary grid** — superseded and removed by the component split. Net state is the split; do not reintroduce the sort.
+
+## Not tried yet (candidates for next session)
+- Run the two Core migrations (`2026-08-04a`, then `2026-08-04b`) local → beta → prod; add PLAYBOOK change-log + env-status rows; commit dbchanges2 with a `TRUE-#####:` message.
+- QA in the Compass/CompassCanada sandbox: (1) approval-stage order shows the new layout, 2-col field grid, "Approval Details — submitted by {name}" title, and Submitted By no longer in the grid; (2) a non-approval order is visually unchanged.
+- Optional copy tweak: lowercase the mock's "submitted by" by changing `Core.Messages 'salesOrder.approvalDetails.field.submittedBy'` defaultValue to `submitted by` (left as-is — copy decision).
+- Consider whether any approval-stage order can lack `createdByUser._name` (would show Submitted By in neither grid nor title — acceptable but confirm).
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| toga25-supply/.../helpers/sectionRenderers.tsx | Created | `createSectionRenderers` factory + `resolvePath`; approvalDetails renders titleSuffix inline |
+| toga25-supply/.../helpers/getVisibleSections.ts | Created | Extracted visibility filter for the standard grid |
+| toga25-supply/.../layoutComponents/SalesOrderApprovalSummaryGrid.tsx | Created | Approval top grid (approval-details span 3 + totals 1) |
+| toga25-supply/.../layoutComponents/SalesOrderSummaryGrid.tsx | Modified | Slimmed to delegate to the two helpers |
+| toga25-supply/.../view/SalesOrderView.tsx | Modified | Branches on approvalActive; Admin Notes at top in approval view |
+| toga25-supply/.../helpers/getDetailSections.tsx | Modified | Approval-only: Order Details + Bill To below items; adminNotes suppressed below |
+| toga25-supply/.../SalesOrderRecordModalLayout/index.ts | Modified | Exports SalesOrderApprovalSummaryGrid |
+| toga25-supply/.../helpers/surfaceBundleToTenantFields.ts | Modified | `titleSuffix` role marker → section.titleSuffix, excluded from grid; geometry passthroughs reverted |
+| toga25-supply/.../SalesOrderRecordModal.module.css | Modified | .approvalSummaryGrid/.approvalDetailsSpan, .approvalFieldsGrid (fixed 2-col), .cardTitleSuffix |
+| dbchanges2/Core/2026-08-04a - ApprovalDetailsSectionTitle.sql | Created | Message "Approval Details" + link surface.titleMessageId (NOT YET RUN) |
+| dbchanges2/Core/2026-08-04b - ApprovalDetailsSubmittedByTitleSuffix.sql | Created | Stamp config.role='titleSuffix' on createdByUser._name element (NOT YET RUN) |
+
+## Decisions made
+- **Component split, not prop-driven**, for approval vs standard — the layouts differ in DOM placement (sections move relative to the Items table), not just CSS. Rejected: one prop-driven `SalesOrderSummaryGrid` (would leak branch logic into SalesOrderView anyway).
+- **Grid geometry lives in the FE; surface owns content/visibility/order/ACL.** Rejected surface-driven columns/colSpan (see failure above). Saved as KB feedback memory `surface-vs-fe-layout-boundary`.
+- **Title suffix via a `config.role` marker**, mirroring the existing `sectionLayoutRule`/`sectionVisibility` markers — surface declares the semantic role + value/label (content), FE renders placement. Rejected: hardcoding the value/label in the FE.
+- **Section title stays surface-driven** (it's content, not geometry) — pure DB change, no FE edit needed.
+
+## Blockers
+None. FE is committed-ready and typechecks; the two Core migrations are authored but NOT yet run against any DB.
+
+## Exact next step
+> Run `dbchanges2/Core/2026-08-04a - ApprovalDetailsSectionTitle.sql` then `2026-08-04b - ApprovalDetailsSubmittedByTitleSuffix.sql` against the LOCAL Core DB, then load an approval-stage order in the Compass sandbox and verify: title reads "Approval Details — submitted by {name}", the field grid is 2-col, and Submitted By is gone from the grid.
+
+---
+_Saved by /session-save on 2026-08-04_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.521",
+  "version": "1.0.522",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",