feat(catalog): the reference shows syntax, parameters and an example for the ten most used commands

Author: u8array

README.md

@@ -95,7 +95,7 @@ The **ZPL** panel at the bottom shows the generated ZPL, **Copy** puts it on the
 
 The **ZPL** panel highlights syntax and collapses long blocks of image data. Selecting a canvas object marks its ZPL lines. A notice above the code lists commands that change saved printer settings or control the printer.
 
-The **command list** left of the code filters as you search. The **ZPL reference** on the right follows the cursor. Click a command to pin its details. A double-click or the right-click menu inserts the command at the cursor. A chevron folds each pane to a rail. Click the rail to bring it back.
+The **command list** left of the code filters as you search. The **ZPL reference** on the right follows the cursor. Click a command to pin its details. The details also show the syntax, a parameter table and an example where the reference has them. A double-click or the right-click menu inserts the command at the cursor. A chevron folds each pane to a rail. Click the rail to bring it back.
 
 While you edit, the canvas shows a live preview. Canvas editing and the **Properties** tab are disabled. Page switching stays enabled. The editor refuses source that is too large or has mismatched `^XA`/`^XZ` commands, and marks the mismatches. Click a mark to insert the missing command.
 

packages/core/src/catalog/catalog.test.ts

@@ -26,7 +26,7 @@ describe("zpl command catalog", () => {
   });
 
   it("keeps every title a short plain phrase without parentheses", () => {
-    // A name, not a sentence: the panel shows it beside the command, and the en text is what translations hash against.
+    // A name, not a sentence: the panel shows it beside the command.
     const TITLE_WORD_CAP = 8;
     for (const c of ZPL_COMMANDS) {
       expect(c.title.split(/\s+/).length, c.cmd).toBeLessThanOrEqual(TITLE_WORD_CAP);
@@ -51,6 +51,33 @@ describe("zpl command catalog", () => {
     }
   });
 
+  it("ties each reference block to its command and keeps the parameter prose plain", () => {
+    const PARAM_WORD_CAP = 12;
+    for (const c of ZPL_COMMANDS) {
+      if (!c.reference) continue;
+      const { syntax, params, example } = c.reference;
+      expect(syntax.startsWith(commandId(c)), c.cmd).toBe(true);
+      expect(example, c.cmd).toContain(commandId(c));
+      expect(syntax.slice(commandId(c).length).match(/[a-z]/g) ?? [], c.cmd).toEqual(params.map((p) => p.name));
+      for (const p of params) {
+        for (const text of [p.meaning, p.values, p.default ?? "x"]) {
+          expect(text.split(/\s+/).length, `${c.cmd} ${p.name}`).toBeLessThanOrEqual(PARAM_WORD_CAP);
+          expect(text, `${c.cmd} ${p.name}`).not.toMatch(/[();:]|[^\x20-\x7E]/);
+        }
+        // An enum cell lists its tokens, so a single-token default must be one of them.
+        if (p.default && !/ to /.test(p.values) && /^[A-Z0-9]$/.test(p.default)) {
+          expect(p.values.split(", ").map((v) => v.split(" ")[0]), `${c.cmd} ${p.name}`).toContain(p.default);
+        }
+      }
+    }
+  });
+
+  it("pins the commands that ship a parameter table", () => {
+    for (const id of ["^FO", "^FD", "^A", "^A0", "^CF", "^FB", "^GB", "^BY", "^BC", "^PW", "^LL"]) {
+      expect(catalogEntry(id)?.reference?.params.length, id).toBeGreaterThan(0);
+    }
+  });
+
   it("never claims less on desktop than on the web, and names why a row is out of scope", () => {
     const rank = { no: 0, planned: 1, yes: 2 } as const;
     for (const c of ZPL_COMMANDS) {