@airmark/quiver 0.27.0 → 0.29.0

package/README.md

@@ -1,7 +1,7 @@
 # @airmark/quiver
 
-A [Quillmark](https://github.com/nibsbin/quillmark) Source Quiver of Air Force
-and DAF official-document Quills, sourced from
+A [Quillmark](https://github.com/nibsbin/quillmark) source quiver of Air Force
+and DAF official-document quills, sourced from
 [tonguetoquill-collection](https://github.com/nibsbin/tonguetoquill-collection)
 and aligned to the current Quillmark spec.
 
@@ -9,7 +9,8 @@ and aligned to the current Quillmark spec.
 
 | Quill        | Version | Description                                                                       |
 |--------------|---------|-----------------------------------------------------------------------------------|
-| `usaf_memo`  | 0.2.0   | USAF / DAF Official Memorandum (AFH 33-337)                                       |
+| `usaf_memo`  | 0.3.0   | USAF / DAF Official Memorandum (AFH 33-337)                                       |
+| `usaf_memo`  | 0.2.0   | Previous release, retained so documents pinned to `@0.2` keep resolving           |
 | `af4141`     | 0.1.0   | AF Form 4141 — Individual's Record of Duties and Experience (Ground Environment)  |
 | `daf1206`    | 0.1.0   | DAF Form 1206 — Nomination for Award                                              |
 | `daf4392`    | 0.1.0   | DAF Form 4392 — Pre-Departure Safety Briefing (Page 2)                            |
@@ -20,30 +21,33 @@ and aligned to the current Quillmark spec.
 npm install @airmark/quiver @quillmark/quiver @quillmark/wasm
 ```
 
-This package ships only the Source Quiver assets (`Quiver.yaml` + `quills/`)
-and exposes no JavaScript API. All loading is performed by `@quillmark/quiver`,
-either from the on-disk package directory or from a packed archive fetched
-over HTTP.
+This package ships only the source-quiver assets (`Quiver.yaml` + `quills/`) and
+exposes no JavaScript API. Loading is `@quillmark/quiver`'s, rendering is
+`@quillmark/wasm`'s.
 
 ## Usage
 
-### Load from the exported directory
+### Load from the installed directory (Node)
 
-Resolve the package's `Quiver.yaml` via `import.meta.resolve` and hand it to
-`@quillmark/quiver`:
+Resolve this package's `Quiver.yaml` from your own module — your dependencies are
+reachable from you, not from the loader's install location — and hand its
+directory to `fromDir`:
 
 ```ts
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-import { Quillmark, Document } from '@quillmark/wasm';
-import { Quiver } from '@quillmark/quiver/node';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { Engine, init } from '@quillmark/wasm';
+import { fromDir } from '@quillmark/quiver/node';
 
-const quiverYaml = fileURLToPath(import.meta.resolve('@airmark/quiver/Quiver.yaml'));
-const quiver = await Quiver.fromDir(path.dirname(quiverYaml));
+// `init` is the only door to `Document`: there is no static export to reach early.
+const { Document } = await init();
+
+const root = dirname(createRequire(import.meta.url).resolve('@airmark/quiver/Quiver.yaml'));
+const quiver = await fromDir(root);
+const engine = new Engine();
 
-const engine = new Quillmark();
 const doc = Document.fromMarkdown(`~~~
-$quill: usaf_memo@0.2
+$quill: usaf_memo@0.3
 $kind: main
 memo_for: ["ORG/SYMBOL"]
 memo_from: ["ORG/SYMBOL", "Organization Name", "123 Street Ave", "City ST 12345-6789"]
@@ -53,19 +57,31 @@ signature_block: ["FIRST M. LAST, Rank, USAF", "Duty Title"]
 
 Body of the memo.`);
 
-const quill = await quiver.getQuill(doc.quillRef, { engine });
-const { artifacts } = quill.render(doc, { format: 'pdf' });
+const quill = await quiver.getQuill(doc.quillRef);
+const { artifacts } = await engine.render(quill, doc, { format: 'pdf' });
 ```
 
-### Load a packed Quiver via HTTP
+A quill from `getQuill` is borrowed: every caller asking for that ref gets the
+same instance, so it is not yours to `free()`.
+
+### Load over HTTP (browser)
+
+A browser cannot read the source layout, so pack it at deploy time and serve the
+output as static files:
+
+```ts
+import { build } from '@quillmark/quiver/node'; // build step
+await build(root, './public/quivers/airmark');
+```
 
-Publish a packed Quiver archive (e.g. as a CDN or GitHub release asset) and
-load it in the browser or any fetch-capable runtime through `@quillmark/quiver`.
-See the upstream `@quillmark/quiver` docs for the packed-format and HTTP API.
+```ts
+import { Quiver } from '@quillmark/quiver'; // browser runtime
+const quiver = await Quiver.fromBuiltUrl('/quivers/airmark/');
+```
 
 ## Layout
 
-This package is a [Source Quiver](https://www.npmjs.com/package/@quillmark/quiver)
+This package is a [source quiver](https://www.npmjs.com/package/@quillmark/quiver)
 conforming to the canonical layout:
 
 ```
@@ -79,20 +95,53 @@ quills/
       packages/
 ```
 
-## Testing
+## Working on a quill
 
-`quiver.test.js` at the repo root runs the
-[`@quillmark/quiver/testing`](https://www.npmjs.com/package/@quillmark/quiver)
-suite under the built-in [`node:test`](https://nodejs.org/api/test.html) runner,
-validating each `(quill, version)` pair through the full load +
-`engine.quill(tree)` compile pipeline:
+Two verbs, and they answer different questions.
+
+Both verbs are [`quillkit`](https://www.npmjs.com/package/quillkit)'s, the quill
+author's toolchain. It resolves `@quillmark/quiver` and `@quillmark/wasm` out of
+this collection's own `node_modules`, so the versions pinned here are the format
+the quiver is packed in and the wasm the gate renders through.
+
+**Does it work?** `quillkit test` loads the collection with `fromDir`, compiles
+every quill, and renders each one's example document — the blueprint seeded from
+the `example:` values in `Quill.yaml`. It is the gate CI runs, so a validation
+failure surfaces here rather than on a consumer's build:
 
 ```bash
 npm install
 npm test
 ```
 
+The gate renders nothing the schema did not write, so the coverage is the
+`example:` block: a field with no example is a field no render exercises.
+
+**What is it like to use?** `npm run dev` is `quillkit studio`: it packs this
+quiver, serves the studio client over it, and repacks on every save — pick a
+quill, edit the seeded document, watch it paint, read the diagnostics. The
+client is quillkit's own, so there is nothing to install for it and nothing to
+keep in step.
+
+Reload to pick up a repack. Editing a quill into an invalid state is not a
+failure of the loop: it packs, and the client says what is wrong with that quill
+and where, while the others stay usable.
+
+The two verbs answer to different authorities. `quillkit test` renders through
+the wasm pinned here and is what CI blocks on; the client renders through the
+wasm it was built against, and nothing at runtime reconciles the two. The gate
+is authoritative, studio is advisory.
+
+`npm run site` writes the arrangement a deploy serves into `site/` — the client
+at the root, a built quiver at `quiver/` beneath it — without serving it. CI
+uploads that on every run, so a pull request — a fork's included — is reviewed
+by downloading the artifact and serving the directory.
+
+`main` is deployed to GitHub Pages by `.github/workflows/studio.yml`, which runs
+that same command and keeps the deploy here: nothing outside this repository
+holds `pages: write`.
+
 ## License
 
-Apache-2.0. Individual Quills carry their own licensing terms; see the
-`packages/` directory inside each Quill for upstream font and template licenses.
+Apache-2.0. Individual quills carry their own licensing terms; see the
+`packages/` directory inside each quill for upstream font and template licenses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@airmark/quiver",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Airmark Quiver — Air Force and DAF document Quills for Quillmark.",
   "type": "module",
   "exports": {
@@ -16,12 +16,14 @@
     "node": ">=24"
   },
   "devDependencies": {
-    "@quillmark/quiver": "0.15.0",
-    "@quillmark/wasm": "^0.91.0"
+    "@quillmark/quiver": "0.21.0",
+    "@quillmark/wasm": "^0.104.0",
+    "quillkit": "0.2.2"
   },
   "scripts": {
-    "test": "quiver test",
-    "preview": "quiver preview"
+    "test": "quillkit test",
+    "site": "quillkit site --out site",
+    "dev": "quillkit studio"
   },
   "keywords": [
     "quillmark",

package/quills/af4141/0.1.0/Quill.yaml

@@ -2,9 +2,11 @@ quill:
   name: af4141
   version: 0.1.0
   backend: typst
-  plate_file: plate.typ
   description: "AF Form 4141 — Individual's Record of Duties and Experience, Ground Environment Personnel"
 
+typst:
+  plate_file: plate.typ
+
 main:
   body:
     enabled: false
@@ -36,58 +38,66 @@ card_kinds:
     description: Each card represents one row in the Record of Experience table. Rows fill page 1 (up to 16 rows) then page 2 (up to 21 rows), for a maximum of 37 rows.
     ui:
       title: Record of Experience
+      groups: [record]
     body:
       enabled: false
     fields:
       date:
-        type: datetime
+        type: date
         default: ""
+        example: "2026-03-14"
         ui:
-          group: Record
+          group: record
         description: Date of the action (column A).
 
       action:
         type: string
         default: ""
+        example: Upgraded to 5-level; assumed ADO duties
         ui:
-          group: Record
+          group: record
         description: One type of action per line (column B).
 
       written_grade:
         type: string
         default: ""
+        example: "3"
         ui:
-          group: Record
+          group: record
           compact: true
         description: Written grade, if applicable (column C).
 
       written_grade_date:
-        type: datetime
+        type: date
         default: ""
+        example: "2026-02-28"
         ui:
-          group: Record
+          group: record
           compact: true
         description: Date of written grade (column D). Omit or leave blank when there is no written grade.
 
       positional_grade:
         type: string
         default: ""
+        example: "2"
         ui:
-          group: Record
+          group: record
           compact: true
         description: Positional grade, if applicable (column E).
 
       positional_grade_date:
-        type: datetime
+        type: date
         default: ""
+        example: "2026-03-14"
         ui:
-          group: Record
+          group: record
           compact: true
         description: Date of positional grade (column F). Omit or leave blank when there is no positional grade.
 
       auth_or_remarks:
         type: string
         default: ""
+        example: "J.A.D."
         ui:
-          group: Record
+          group: record
         description: Authentication or remarks entry (column G).

package/quills/af4141/0.1.0/packages/typst-af4141/lib.typ

@@ -11,7 +11,15 @@
 /// True for short/narrow fields with brief content (grades, ranks, dates).
 #let should-shrink-to-fit(display, width, height) = {
   let aspect = width / height
-  let char-count = display.len()
+  // A date field's content is a single `text` element, and the string inside it
+  // is what decides the shrink, as a plain value's own does. Any other content
+  // (a styled label, a sequence) has no such string and counts as long, so only
+  // the dimension conditions apply.
+  let char-count = if type(display) == str {
+    display.len()
+  } else {
+    display.at("text", default: "0" * 99).len()
+  }
   char-count <= 10 or height < 20pt or aspect > 4.0
 }
 
@@ -81,8 +89,14 @@
 /// - field (dictionary): raw field entry from the schema
 #let render-field(field-type, value, width, height, field) = {
   if field-type == "text" {
-    if value != none and str(value) != "" {
-      render-text-field(str(value), width, height, 1.5pt, 1pt)
+    if value != none {
+      // A date field arrives as content carrying its click-to-edit region, so it
+      // is placed as it stands; a plain string is placed only when non-empty.
+      if type(value) == content {
+        render-text-field(value, width, height, 1.5pt, 1pt)
+      } else if str(value) != "" {
+        render-text-field(str(value), width, height, 1.5pt, 1pt)
+      }
     }
   } else if field-type == "checkbox" {
     if value == true {

package/quills/af4141/0.1.0/plate.typ

@@ -3,13 +3,20 @@
 
 #set text(font: "NimbusRomNo9L")
 
-// `type: date` fields arrive as Typst `datetime`; PDF overlay expects strings.
-// Missing / blank dates: helper uses `none`; empty strings may also appear from input.
+// A `type: date` field lowers to a click-to-edit value object
+// `(value: datetime, display: closure)`; `display` is a stored closure on a dict
+// rather than a method, so it is called through parentheses, and the content it
+// returns carries the region that makes the glyphs clickable. A native datetime
+// is still accepted. Missing / blank dates arrive as `none`; empty strings may
+// also appear from input.
 #let form-cell(v) = {
+  let pattern = "[month padding:none]/[day padding:none]/[year]"
   if v == none { "" }
   else if type(v) == str and v == "" { "" }
-  else if type(v) == datetime {
-    v.display("[month padding:none]/[day padding:none]/[year]")
+  else if type(v) == dictionary {
+    (v.display)(pattern)
+  } else if type(v) == datetime {
+    v.display(pattern)
   } else {
     str(v)
   }

package/quills/daf1206/0.1.0/Quill.yaml

@@ -2,9 +2,11 @@ quill:
   name: daf1206
   version: 0.1.0
   backend: typst
-  plate_file: plate.typ
   description: "DAF Form 1206 — Nomination for Award"
 
+typst:
+  plate_file: plate.typ
+
 main:
   body:
     example: |

package/quills/daf4392/0.1.0/Quill.yaml

@@ -2,21 +2,23 @@ quill:
   name: daf4392
   version: 0.1.0
   backend: typst
-  plate_file: plate.typ
   description: "DAF Form 4392 - Pre-Departure Safety Briefing (Page 2)"
 
+typst:
+  plate_file: plate.typ
+
 main:
   body:
     enabled: false
   fields:
     transportation_mode:
-      type: string
-      enum: [pmv, airplane, bus, train, motorcycle, other]
+      type: enum
+      values: [pmv, airplane, bus, train, motorcycle, other]
       default: pmv
       description: "Matches the check box."
 
     departure_date:
-      type: datetime
+      type: date
       default: ""
       example: "2026-06-01"
       ui:
@@ -59,7 +61,7 @@ main:
       description: "Unit / Organization."
 
     briefed_date:
-      type: datetime
+      type: date
       default: ""
       example: "2026-05-22"
       ui:
@@ -96,41 +98,42 @@ card_kinds:
     description: "Each card represents one row in the travel itinerary table. Up to 10 rows are supported."
     ui:
       title: Proposed Travel Itinerary
+      groups: [itinerary_entry]
     body:
       enabled: false
     fields:
       date:
-        type: datetime
+        type: date
         default: ""
         ui:
-          group: Itinerary Entry
+          group: itinerary_entry
           compact: true
         description: "Date for the itinerary row."
       departure_point:
         type: string
         default: ""
         ui:
-          group: Itinerary Entry
+          group: itinerary_entry
           compact: true
         description: "Point of departure."
       arrival_point:
         type: string
         default: ""
         ui:
-          group: Itinerary Entry
+          group: itinerary_entry
           compact: true
         description: "Point of arrival."
       rest_length:
         type: string
         default: ""
         ui:
-          group: Itinerary Entry
+          group: itinerary_entry
           compact: true
         description: "Duration of stay at arrival point"
       mileage:
         type: string
         default: ""
         ui:
-          group: Itinerary Entry
+          group: itinerary_entry
           compact: true
         description: "Approximate mileage for this leg (leave blank if not applicable, e.g., flights)."

package/quills/daf4392/0.1.0/packages/daf4392page2_pkg/lib.typ

@@ -31,11 +31,22 @@
 }
 
 /// Format a date value for display as `DD Mon YYYY`.
+///
+/// Dispatches on the shape a date can arrive in:
+/// - dict: a Quillmark `date` field lowers to a click-to-edit value object
+///   `(value: datetime, display: closure)`. `display` is a stored closure on a
+///   dict rather than a method, so it is called through parentheses, and the
+///   content it returns carries the region that makes the glyphs clickable.
+/// - datetime: a native Typst datetime, from a plate building its own value.
+/// - str: shown as-is.
 #let format-date(value) = {
+  let pattern = "[day padding:zero] [month repr:short] [year]"
   if value == none {
     none
+  } else if type(value) == dictionary {
+    (value.display)(pattern)
   } else if type(value) == datetime {
-    value.display("[day padding:zero] [month repr:short] [year]")
+    value.display(pattern)
   } else if type(value) == str and value == "" {
     ""
   } else {
@@ -45,11 +56,17 @@
 
 /// Should this field shrink text to a single line rather than word-wrap?
 /// True for short/narrow fields with brief content (grades, ranks, dates).
-/// `display` may be a string or content; char-count is skipped for content.
 #let should-shrink-to-fit(display, width, height) = {
   let aspect = width / height
-  // content has no .len(); treat as "long" so only the dimension conditions apply
-  let char-count = if type(display) == str { display.len() } else { 99 }
+  // A date field's content is a single `text` element, and the string inside it
+  // is what decides the shrink, as a plain value's own does. Any other content
+  // (a styled label, a sequence) has no such string and counts as long, so only
+  // the dimension conditions apply.
+  let char-count = if type(display) == str {
+    display.len()
+  } else {
+    display.at("text", default: "0" * 99).len()
+  }
   char-count <= 10 or height < 20pt or aspect > 4.0
 }