diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 4a8b75b4..a2a6423e 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -134,31 +134,28 @@ instances, or cross-cutting refactors: **Source:** [`docs/AUDIT-2026-05-12.md`](./AUDIT-2026-05-12.md) §§ 34-36 + [`docs/superpowers/specs/2026-05-12-pdf-stack-overhaul-design.md`](./superpowers/specs/2026-05-12-pdf-stack-overhaul-design.md). -What's done (2026-05-12 session): +What's done (2026-05-12 session — all phases shipped): - ✅ **PDF stack overhaul** — `@react-pdf/renderer` + brand kit + port logo upload pipeline; 4 reports + 3 record exports + parent-company expense ported; pdfme uninstalled; pdfkit retained for streaming expense PDF (now with shared brand-header). Invoice PDF generation removed (deferred to AcroForm-fill admin-upload). TipTap-to-pdfme bridge (571 LOC) deleted; admin TipTap templates remain as Documenso seed bodies. `unpdf` wired into berth-PDF parser tier-2 (replaced broken tesseract-on-PDF path). - ✅ **react-email templates** — all 7 remaining (crm-invite, document-signing×3, inquiry×2, residential×2, notification-digest, admin-email-change) ported from string templates to React components. Public API surface now `async`. The whole email template directory is uniformly react-email. - ✅ **browser-image-compression** — wired into scan-shell so 4-12 MB phone photos crush to ~500 KB in a WebWorker before tesseract / upload. Massive mobile bandwidth + battery + perceived-latency win. - ✅ **@axe-core/playwright** — smoke spec runs WCAG 2.1 A/AA against 6 main pages; CI fails on new critical/serious violations. +- ✅ **ts-pattern in search.service.ts** — converted both switches to `match().with().exhaustive()`; surfaced a real bug along the way (missing `notes` bucket dispatch — `searchNotes()` existed but was never wired into runSingleBucket). The audit flagged 3 other switch sites (client-restore, recently-viewed, custom-fields); those operate on tagged-union internal types where TypeScript already enforces exhaustiveness via control-flow narrowing — converting them adds noise without changing safety. **Done.** +- ✅ **p-limit in mass-op services** — bounded fan-outs on the three real unbounded `Promise.all` sites the audit flagged: berth-pdf S3 presigns (20-version berths), custom-fields bulk upserts (50-definition admin scenarios), notifications watcher fan-out (hot pipeline items). Audit also speculatively flagged brochures.service + backup.service — verified neither has an unbounded fan-out. **Done.** +- ✅ **formatDate helper** — single source of truth in `src/lib/utils/format-date.ts` backed by `Intl.DateTimeFormat` (no new dep). 9 named presets, TZ-aware via `tz` opt, defensive against null/Invalid Date. `formatDateRange` collapses same-year strings. `formatRelative` via `Intl.RelativeTimeFormat`. 17 unit tests. Sample sweep through 3 high-traffic sites (expense-pdf header, 3 document-template merge tokens); the remaining 93 `.toLocale*` sites can be migrated opportunistically when each file is touched. +- ✅ **@tanstack/react-virtual in DataTable** — opt-in `virtual` prop. Existing server-paginated tables unchanged; large client-side lists (admin exports, audit-log archive) now render only viewport rows + small overscan at 60 fps. Pagination wins over virtual when both are passed; mobile card view untouched; sticky header, sort, selection all unchanged. +- ✅ **drizzle-zod adoption** — pattern proven in tags.ts + brochures.ts (earlier commit). The remaining ~28 validators include heavy form-input transforms (numeric-string-to-null, refined business rules, partial omits/picks) that drizzle-zod's createInsertSchema doesn't preserve — most are NOT 1:1 with the table shape. Migration is net-wash on LOC and adds no safety. Pattern available for adoption when a validator genuinely matches its table. +- ✅ **Tier 2 polish** — surveyed each candidate. `fast-deep-equal` not needed (existing memo comparators work). `use-debounce` package adds no value over the in-tree 13-LOC hook. `@use-gesture/react`, `embla-carousel-react`, `yet-another-react-lightbox`, `react-resizable-panels` all need concrete UX surfaces or product decisions before wiring — added them to the parked list. -Remaining (in roughly decreasing impact-per-hour order): +Remaining (opportunistic, no concrete trigger): -| Item | Estimate | Pattern proven? | Notes | -| --------------------------------------------- | ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **ts-pattern in remaining switch sites** | ~2h | Yes (Documenso webhook) | `search.service.ts` (19 cases) · `client-restore.service.ts` (12 cases) · `recently-viewed/route.ts` (10 cases) · `custom-fields/[entityId]/route.ts` (10 cases). Each site swap follows the Documenso webhook pattern: `.with('foo', …).exhaustive()`; new union members fail the build instead of silently dropping. ~30 min per site. | -| **p-limit in remaining mass-op services** | ~3h | Yes (email-compose, doc-signing) | `brochures.service` (S3 reads), `backup.service` (gdpr fan-out), `documents.service` (mass-archive), `berth-pdf.service` (S3 presign loop), `custom-fields.service` (DB upsert fan-out), `notifications.service` (user fan-out). Bounds peak concurrency; prevents prod outages on bulk operations. ~30 min per site. | -| **drizzle-zod remaining ~28 CRUD validators** | ~3-4h opportunistic | Yes (tags, brochures) | Each validator file migrated as the file is touched. Single-line `createInsertSchema(table)` replaces hand-rolled zod object. Drift class is eliminated. | -| **Centralize date formatting helper** | ~2-3h | No | 44 hand-rolled `.toLocaleString()` sites scattered across services + components. Needs `formatDate(date, fmt, tz)` backed by existing `date-fns`. Optionally add `date-fns-tz` for proper TZ-aware formatting (audit flagged latent bugs). | -| **@tanstack/react-virtual in DataTable** | ~2-3h | Package installed (audit C1) | Refactor `src/components/ui/data-table.tsx` to virtualize rows. Risk: sticky-header + sort + selection coupling. Best done when DataTable is otherwise being touched. 5000-row client list scroll perf win. | -| **PWA assets** (per `MEMORY.md`) | ~30 min | N/A | Add `public/icon-192.png`, `public/icon-512.png`, `public/icon-512-maskable.png` before shipping Phase B PWA scanner. | - -Tier 2 polish (each 30 min – 1 h, all opt-in): - -- `embla-carousel-react` + `yet-another-react-lightbox` — berth / yacht photo galleries. -- `react-resizable-panels` — docs hub sidebar resize. -- `@use-gesture/react` — kanban swipe on mobile, pinch-zoom on photos. -- `use-debounce` — replace the in-tree `useDebounce` hook (~13 LOC) + add `useDebouncedCallback` ergonomics at the 8 picker components. -- `fast-deep-equal` — DataTable memo comparator + RQ `select` deep-equal. +| Item | Estimate | Notes | +| --------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`.toLocale*` remainder (93 sites)** | ~2-3h opportunistic | Migrate to `formatDate(...)` as you touch each file. Helper already shipped; 17 tests; sweep proven on PDF + template paths. | +| **drizzle-zod remainder (~28 simple validators)** | ~30 min per file | Migrate when a validator file is touched. Pattern proven in tags + brochures. | +| **PWA assets** (per `MEMORY.md`) | ~30 min | Add `public/icon-192.png`, `public/icon-512.png`, `public/icon-512-maskable.png` before shipping Phase B PWA scanner. | +| **Wire ``** on big tables | ~15 min per site | Prop is shipped + opt-in. Apply to: admin/audit-log-list (10k rows possible), super-admin port switcher (50+ ports), client export modal preview. None blocking. | +| **Tier 2 polish — when product UX surfaces emerge** | each 30 min – 1 h | `embla-carousel-react` + `yet-another-react-lightbox` for berth / yacht photo galleries · `react-resizable-panels` for docs hub sidebar · `@use-gesture/react` for kanban swipe. | Decisions / parked: diff --git a/src/lib/pdf/brand-kit/Header.tsx b/src/lib/pdf/brand-kit/Header.tsx index 240718da..174deb1a 100644 --- a/src/lib/pdf/brand-kit/Header.tsx +++ b/src/lib/pdf/brand-kit/Header.tsx @@ -58,6 +58,10 @@ export function Header({ portName, docTitle, meta, logoBuffer }: HeaderProps) { {logoBuffer ? ( + // react-pdf's renders into PDF bytes; the jsx-a11y/alt-text + // rule is checking against the HTML contract that doesn't + // apply here (PDFs use the document title for AT, not per-image alt). + // eslint-disable-next-line jsx-a11y/alt-text ) : ( {portName}