Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,13 @@

- **Fail closed.** The plugin throws at config time unless `access.manage` or `access.print` is set. `access.print` decides printing; without it only `access.manage` may print. Templates and media are read by whoever may manage or print (a printer must read the template); the log is read by `manage` only. There is no signed-in fallback. The template lookup tries the key, then the id exactly as given, so numeric ids work on Postgres and SQLite.

- **Template editor** (`/client`): layers list with keyboard selection and announced reorder, hide and delete; an inspector for position, size, rotation, text, font size, fit rule and barcode settings; a live SVG preview from the same layout as printing, with a sample record and a warnings list. Installed on the `elements` field. New peer dependencies: `react` and `@payloadcms/ui`.

- **Security fix (review).** The `elements` field is validated on save (`validateElements`): known kinds, finite numbers in range, strings where strings belong, fixed lists for enums, at most 200 elements. The SVG writer sends every number through one sanitizer, so a stored value can no longer carry markup into the live preview.
- Tested: a malicious thickness and rotation, an infinite position, a non-text content, an unknown kind and a non-list are each refused on save; the SVG of an unvalidated hostile element holds no markup; 4 new tests.
- Not tested: the editor in a real browser against a hostile record.

No version bump (still 0.0.0).

Tested: 44 tests with made-up data. Core math and tokens; PDF page count and size (288 x 432 pt for 4 x 6 in), SVG viewBox, text escaping, rotation, vector barcodes, invalid barcode without a crash; the print endpoint on in-memory MongoDB (page count, one log entry with ids only, 2,001-over refusal with count, signed-out, no scope, other site's template, an unreadable record, bad requests); config throws with neither access option, manage-only and print-only behavior, and the template lookup order with a stand-in for Payload; a Payload config build checking the collections, default access and strict answers; and an in-memory MongoDB run with two sites proving cross-scope reads, creates, updates, deletes and moves are refused, the shared template is admin-only, the print log is unwritable, and signed-out and scope-less users get nothing.
Not tested: the cost of reading printed documents at depth 3 (to revisit before 0.1), numeric ids on a real SQL database, the endpoint over real HTTP, 2,000 labels' render time (the 2,000 limit is a guess), PDF in a viewer or printer, SVG in a browser, scanning a printed barcode, sheet pages, images in output, real font metrics, real printers.
Tested: 54 tests with made-up data. Core math and tokens; PDF page count and size (288 x 432 pt for 4 x 6 in), SVG viewBox, text escaping, rotation, vector barcodes, invalid barcode without a crash; the print endpoint on in-memory MongoDB (page count, one log entry with ids only, 2,001-over refusal with count, signed-out, no scope, other site's template, an unreadable record, bad requests); the editor in jsdom (preview follows the sample and inspector edits, edits write back to the elements, keyboard selection and reorder with announcements, hide, delete, add, warnings per layer, invalid sample JSON, every control labeled); config throws with neither access option, manage-only and print-only behavior, and the template lookup order with a stand-in for Payload; a Payload config build checking the collections, default access and strict answers; and an in-memory MongoDB run with two sites proving cross-scope reads, creates, updates, deletes and moves are refused, the shared template is admin-only, the print log is unwritable, and signed-out and scope-less users get nothing.
Not tested: the editor in a real browser, with a screen reader, in the Payload admin (the field wrapper that reads the form is not run in any test), color contrast; the cost of reading printed documents at depth 3 (to revisit before 0.1), numeric ids on a real SQL database, the endpoint over real HTTP, 2,000 labels' render time (the 2,000 limit is a guess), PDF in a viewer or printer, SVG in a browser, scanning a printed barcode, sheet pages, images in output, real font metrics, real printers.
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Labels for Payload: design labels with field tokens in the admin, then print one, a few or every label for a document, on thermal rolls or Avery-style sheets.

**Status:** early checkpoint, version 0.0.0, not published. Built and tested (44 tests): the layout engine in `src/core` (field tokens, text fitting, barcode value checks, sheet grid positions, the 4 x 6 inch thermal preset), and the plugin that adds the three collections with write access closed by default and scope filtering on reads and writes, plus SVG and PDF output drawn from the layout marks, with barcodes, QR and Data Matrix as vectors (bwip-js), and the print endpoint `POST /api/labels/print`. The scope rules are tested against an in-memory MongoDB with two made-up sites. The PDF was checked for page count and page size in points, not opened in a printer or viewer; the SVG was checked as text, not in a browser; no barcode has been scanned. The endpoint is tested by calling its handler against an in-memory MongoDB, not over HTTP. **Not built yet:** sheet (Avery) pages, images in output, sets, the print dialog and button, the admin inspector and live preview. The design is in [docs/design.md](docs/design.md).
**Status:** early checkpoint, version 0.0.0, not published. Built and tested (54 tests): the layout engine in `src/core` (field tokens, text fitting, barcode value checks, sheet grid positions, the 4 x 6 inch thermal preset), and the plugin that adds the three collections with write access closed by default and scope filtering on reads and writes, plus SVG and PDF output drawn from the layout marks, with barcodes, QR and Data Matrix as vectors (bwip-js), and the print endpoint `POST /api/labels/print`. The scope rules are tested against an in-memory MongoDB with two made-up sites. The PDF was checked for page count and page size in points, not opened in a printer or viewer; the SVG was checked as text, not in a browser; no barcode has been scanned. The endpoint is tested by calling its handler against an in-memory MongoDB, not over HTTP. The admin editor (layers list, inspector, live preview) is tested in jsdom only: it has not been seen in a real browser, with a screen reader, or inside the Payload admin. **Not built yet:** the drag-and-drop canvas, sheet (Avery) pages, images in output, sets, the print dialog and button. The design is in [docs/design.md](docs/design.md).

## What it will do (the plan)

Expand All @@ -26,6 +26,10 @@ This part is still the plan from [docs/design.md](docs/design.md).

**Family:** Labels sits in the Fulfillment family, with Kitting, Restock, Sample Kits, Shipping, Scan, Wizards, Custody and Sequences, though the families are a working draft and Fulfillment is due to be split into different groups.

## The template editor

The `elements` field of a template uses an editor from `@extantape/payload-plugin-labels/client` (set up by the plugin; the site needs `react` and `@payloadcms/ui`, and the admin import map regenerated). It has three parts: a layers list (arrow keys move the selection; buttons move a layer up or down, hide it from the preview, or delete it; each result is announced), a preview drawn from the same layout as printing, and an inspector for the selected layer (position and size in mm, rotation, text and tokens, font size, fit rule, barcode type and value). A sample record, edited as JSON, fills the tokens, and a warnings list names the layer for each missing value, text that does not fit and bad barcode value. Hiding a layer affects the preview only and is not saved. The label's width and height come from the template's own fields. Placing layers by dragging comes later.

## Install or build

Not published yet. It will be `@extantape/payload-plugin-labels` on npm. To build it here: `npm install`, `npm test`, `npm run build`.
Expand Down
2 changes: 2 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,5 @@ Dated decisions for this repo, newest last.
- 2026-11-16: outputs. SVG and PDF both draw the layout's mark list. Dependencies, licenses checked in their package files: pdfkit 0.20 (MIT), bwip-js 4.11 (MIT), @types/pdfkit (MIT, dev). Both runtime packages are real dependencies, as the design names them. Choices: the PDF has one label per page (sheet pages come later); the SVG helper lives in `/core` and the PDF writer in its own `/pdf` export, so the plugin config never loads pdfkit; barcode vectors come from bwip-js's SVG output and the same path data feeds both renderers; the human-readable line under a linear barcode is drawn by us at 7 pt in Helvetica; images draw as a placeholder box until upload resolving exists; text fitting still uses the estimated width. Rotation turns a mark about the center of its box.
- 2026-11-16: print endpoint. Follows the design's `POST /api/labels/print` and its 2,000-label limit (documents times copies, checked before any read). Choices where the design was open: the request takes `template` (key or id), `ids` and `copies` only for now (sets, media and start position come with the dialog); the template is read as the person, so scope rules apply; documents are read with the person's access (`overrideAccess: false`, depth 3) and one unreadable or missing document refuses the whole request, because a silent gap on a printed run is worse than a refusal; with no `print` check configured any signed-in person may print what they can read, with one only exactly `true` passes; the log entry is written by the server and a failed log write refuses the request, so nothing prints unlogged; `printedBy` holds the user id only; the log takes the person's scope, or the template's for a platform admin; pdfkit loads on the first request, not at config time; thermal 4 x 6 in media is used until media choice is built.
- 2026-11-16: fail closed (review). The earlier default let any signed-in person read templates and print. Now `access.manage` or `access.print` must be set or the plugin throws at config time. `access.print` decides printing; without it only `access.manage` may print. The design has no separate read option, so templates and media are read by whoever may manage or print, because printing reads the template as the person; the print log is read by `manage` only. Template lookup tries the key, then the id as given, with no format guess. Printing reads documents at depth 3; its cost is not measured and is a later item.
- 2026-11-16: template editor (design, builder section, without the canvas). The editor replaces the `elements` field's input through `admin.components.Field`; the label size comes from the template's `width` and `height` fields. Hide in the layers list affects the preview only and is not stored, since the design saves only what prints. Sample data is a JSON text box with a made-up default, because the plugin cannot know a site's fields; pulling a real document into the preview waits for the print dialog's document picker. The editor styles itself with Payload theme variables and fallbacks, and every result of a button is announced in a status line. New peer dependencies: `react` and `@payloadcms/ui` (both MIT); dev: jsdom, @testing-library/react. The drag-and-drop canvas, rulers and snapping stay in K7.
- 2026-11-16: review fix for the inspector. `elements` is validated on the server when a template is saved, and the SVG writer coerces every number, so stored values cannot inject markup into the preview. Limits: 200 elements, text up to 2,000 characters, positions within 2,000 mm, font size 1 to 500 points, line and box thickness 0 to 50 mm. Dev dependencies added by the editor also include `react`, `react-dom` and `@types/react` (all MIT).
6 changes: 6 additions & 0 deletions docs/test-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

Newest first.

## 2026-11-16: template editor

- Promises: the preview follows the sample and edits; inspector edits write back to the elements; arrow keys move the selection; reordering follows the layer and announces the result; warnings name the right layer; every control has a label; a bad sample does not break the editor.
- Covered: `test/editor.test.tsx` (10 tests, jsdom).
- Gaps skipped (and why): the Payload field wrapper (`TemplateEditorField`, three lines over `useField`) needs the admin to run; focus outline and color contrast need a real browser; screen reader behavior needs a hands-on check.

## 2026-11-16: fail closed and template lookup

- Promises: with neither `access.manage` nor `access.print` the config throws and names them; manage-only means a plain signed-in member can neither print nor read templates; print-only lets printers print and read templates but not change them or read the log; a template is found by key, then by id as given.
Expand Down
Loading
Loading