gitea
122480cd46
Brings in the A4 (millimetre) report designer alongside the existing matrix editor, migrates the frontend from react-scripts to Vite/Vitest, and fixes four defects found while using the A4 band tools. Layout — layout.js now implements the standard banded-report model: everything prints where it was drawn, and a band growing per data row is the only thing that moves anything. Previously `paginate` re-flowed every band from the top margin, so a band placed halfway down the page previewed at the top, and `header` was treated as a page header and hoisted above the statics drawn before it. A header is a COLUMN header: it prints in place and repeats only on a continuation page. Statics now take part too — one drawn below a band keeps its drawn gap as that band grows, and follows onto the next page rather than vanishing when pushed past the bottom margin. The displacement is keyed on the band's design bottom, not on an instance's laid-out y: every row of a band shares one design position, so keying on the instance measured the gap from row 1 and let the static overlap rows 2..n. Band children — a child's x is relative to its band, as its y already was. layout() emitted it raw, so a field printed measured from the paper edge instead of the band's left margin. Instances now carry bandX. Band placement — a band's x comes from the page margins, so creation takes only the click's Y (the factory's x was being overwritten by the spread order) and dragging is locked to the vertical axis. Bands render as a strip, with top/bottom rules only, matching the matrix editor. fromApiReport reflows on load so reports saved with a stray x straighten themselves. Matrix bands are constrained to vertical too. Drag lifecycle — useElementDrag re-subscribed its document listeners on every render during a drag, because the effect depended on an unmemoized onDrag. Each re-subscribe removed the mouseup listener before adding the next, measured as add/remove/add/remove/add across two mousemoves, and a release landing in that gap was lost: the element kept following the cursor until the next click. Snapping made it routine, since a held guide stops x/y changing and leaves the guide overlay's render sitting between the move and the release. onDrag and dragData now go through refs so the effect depends on [isDragging] alone. Note: the matrix editor has no test coverage, so its band constraint is verified by reading only. The A4 suite is 201 passing tests. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
84 lines
4.2 KiB
Markdown
84 lines
4.2 KiB
Markdown
# ScalesApp React Expert Memory
|
|
|
|
## Key File Paths
|
|
|
|
- Report Editor root: `frontend/src/components/ReportEditor/`
|
|
- Element models: `models/Element.jsx` — OOP class hierarchy, `fromJSON` has `elementClasses` map
|
|
- Element CSS: `elements.css` — one block per element type
|
|
- Inspector CSS: `ObjectInspector.css`
|
|
- Data resolver utils: `utils/dataResolver.js` — `resolveDBTextValue`, `getAvailableObjects`, `getAvailableFields`
|
|
- Expression evaluator: `utils/expressionEvaluator.js` — recursive-descent, no eval
|
|
- A4 designer (sibling tree, mm-based): `frontend/src/components/ReportEditor/a4/`
|
|
|
|
## Two editors, deliberately duplicated
|
|
|
|
The matrix editor (`EditorCanvas.jsx`, `models/Element.jsx`, `ResizeHandles.jsx`,
|
|
`ObjectInspector.jsx`, `ReportEditor.jsx`) is treated as frozen. The A4 designer under
|
|
`a4/` copies similar logic rather than extracting shared abstractions — per the plan at
|
|
`.claude/plans/a4-report-designer.md`. Do not "DRY up" the two; the duplication is the point.
|
|
|
|
Key unit difference: matrix bounds are **inclusive** (`x + width - 1`); A4 bounds in
|
|
`a4/geometry.js` are **exclusive** (a 40mm box at x=10 has right edge 50).
|
|
|
|
Safely reusable by both: `hooks/useElementDrag.jsx` (emits raw pixel deltas, snapping left
|
|
to the consumer), `hooks/useElementSelection.jsx`, `DataContext`, `BandContext`.
|
|
|
|
## Element Type Pattern (matrix editor)
|
|
|
|
Adding a new element type requires touching 8 files:
|
|
1. `models/Element.jsx` — new class + register in `elementClasses` map in `fromJSON`
|
|
2. `NewElement.jsx` — component file, modeled on `DBTextField.jsx`
|
|
3. `ExpressionEditorPanel.jsx` (or equivalent inspector panel)
|
|
4. `EditorCanvas.jsx` — import + `renderElement` case + click handler in `handleCanvasClick`
|
|
5. `Toolbar.jsx` — tool button
|
|
6. `ObjectInspector.jsx` — import panel + render for `element.type === 'xxx'`
|
|
7. `elements.css` — CSS block for new class
|
|
8. `ResizeHandles.jsx` — add type to `getHandles` switch, `getHandlePosition` branch, and resize logic branch
|
|
|
|
## ObjectInspector Band-Detection Pattern
|
|
|
|
When a panel needs to detect if an element is inside a band (for field resolution):
|
|
```js
|
|
const parentBand = allElements.find(el => el.type === 'band' && el.children && el.children.includes(element.id));
|
|
// Nested band handling:
|
|
if (parentBand.parentBandId) {
|
|
const grandparentBand = allElements.find(el => el.id === parentBand.parentBandId);
|
|
// grandparentData[0][parentBand.dataSource] → nestedData array
|
|
}
|
|
```
|
|
|
|
## DBTextField / ExpressionField Props Pattern
|
|
|
|
Both receive: `element, isSelected, isSingleSelection, onSelect, onUpdate, onDelete, onDragStart, onDrag, charWidth, charHeight, previewMode, toolMode, parentBandId`
|
|
|
|
Uses hooks: `useElementDrag`, `useElementSelection`, `useReportData`, `useBandContext`
|
|
|
|
## resolveDBTextValue signature
|
|
|
|
```js
|
|
resolveDBTextValue(reportData, objectKey, fieldPath, parentBandId, { currentBandData })
|
|
```
|
|
- objectKey = `''` for band-relative field access
|
|
|
|
## ExpressionField Field Ref Format
|
|
|
|
`[objectKey.fieldPath]` for top-level fields, `[fieldPath]` for band-relative fields.
|
|
Strip brackets, split on first `.` to get objectKey and fieldPath.
|
|
|
|
## Build tooling
|
|
|
|
**Vite + Vitest** (no CRA/Jest). `npm run dev` / `npm start` → port 5172;
|
|
`npm test` → `vitest run`; `npm run build` → `frontend/build/`.
|
|
Config: `frontend/vite.config.mjs`. Env vars are `import.meta.env.VITE_*`.
|
|
**Any new production file containing JSX must be named `.jsx`** — a `.js` file
|
|
with JSX passes tests and the dev server but fails `vite build`.
|
|
See [vite-vitest-migration](vite-vitest-migration.md).
|
|
|
|
## Detailed notes
|
|
|
|
- [Vite + Vitest build tooling](vite-vitest-migration.md) — the JSX-in-.js build trap, axios mocks, jsdom `border: none`
|
|
- [A4 entry points](a4-entry-points.md) — report `kind` decides the editor/print route; the two contexts A4ReportEditor now needs in tests
|
|
- [A4 smart guides](a4-smart-guides.md) — px-not-mm snap threshold; why useElementDrag must stay untouched; the drag-test gotcha snapping introduces
|
|
- [Testing React in this repo](testing-react.md) — no testing-library installed; jsdom/React event gotchas that cost real debugging time
|
|
- [Decimal number inputs](decimal-inputs.md) — why `type="number"` breaks mm/float entry
|