3.2 KiB
Learnings Registry
Format: LRN-XXX | Date | Pattern | Context | Future application
LRN-001 | 2026-05-18 | Zod discriminatedUnion for nextAppointment
Report.nextAppointment uses discriminatedUnion('kind', [...]). Gives precise TS narrowing on .kind; avoids optional union type ambiguity. Apply: any polymorphic field with a literal discriminant.
LRN-002 | 2026-05-18 | SVG hitbox+visible twin pattern
Two SVG elements share same data-anno-id: hitbox (pointer-events:all, fill:transparent) + visible (pointer-events:none, colored). Parser groups by data-anno-id → Bone.hitboxEls[], Bone.visibleEls[]. Apply: any SVG-based interactive map needing precise click areas.
LRN-003 | 2026-05-18 | pnpm via corepack shim breaks on older Node 20
corepack shim on Node 20.20.0 throws ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. Fix: install pnpm directly via get.pnpm.io/install.sh. Binary lands at ~/.local/share/pnpm/bin/pnpm. Apply: CI/dev envs without system pnpm.
LRN-004 | 2026-05-19 | SVG behavior hints via free-form data-anno-special
Branch click handling on data-anno-special (free-form string), not on data-anno-category.
Why: category is free-form metadata (LRN follow-up to refactor BDR/cad94a4 chain); coupling logic to category re-introduces a closed enum and silently breaks when SVG author renames a slug. Hints stay opaque to parser, consumed only at use site.
Apply: any SVG-driven UI where authors add new annotation types regularly — use data-anno-special for behavior triggers, keep category for grouping/filters only.
LRN-005 | 2026-05-19 | Detail-popup needs its own bones map
When a popup loads a separate SVG, its annotation ids are not in the parent's bones map.
Parse detail SVG on popup open and keep a detailBones map; fall back lookup bones.get(id) ?? detailBones.get(id) in shared click handler.
Apply: any nested/zoom-popup pattern where the child SVG has independent ids.
LRN-006 | 2026-05-19 | Strip authoring annotations before rasterizing for print
Source SVGs carry interaction-only artifacts (data-anno-, transparent hitboxes, faint default fills) that are invisible in-app via CSS but leak into PDF rasterization.
Before raster: walk [data-anno-id], hide non-selected via display="none", strip data-anno- attributes, recolor selected.
Apply: any "screen → print" pipeline where the screen SVG has interaction layers.
LRN-007 | 2026-05-19 | pdf-lib maxWidth wraps glyphs, not your cursor
pdf-lib's drawText({ maxWidth }) wraps the visible glyph run but the returned y is unchanged — caller must measure with widthOfTextAtSize and advance the cursor per wrapped line. Otherwise subsequent text blocks overlap the wrapped tail. Apply: any pdf-lib layout with variable-length user text. Always wrap explicitly + advance per line.
LRN-008 | 2026-05-19 | pdf-lib eyebrow + title vertical spacing
Times-22 ascender ≈ 17pt. Eyebrow size-9 baseline above title baseline needs ≥22pt gap to clear the ascender + leave ≥6pt visual breathing. Header rule needs ≥30pt cushion below for a size-22 title (title baseline at height-120ish on A4). Apply: any pdf-lib heading stack (eyebrow + title or chained headings). Compute from font.heightAtSize/widthOfTextAtSize, never eyeball pixel offsets.