@airmark/quiver 0.32.2 → 0.34.0

package/quills/usaf_memo/0.3.0/packages/tonguetoquill-usaf-memo/src/utils.typ

@@ -1,21 +1,8 @@
-// utils.typ: Utility functions and backend code for Typst usaf-memo package.
-//
-// This module provides core utility functions, configuration constants, and helper
-// functions used by the main memorandum template. It handles spacing calculations,
-// paragraph numbering, grid layouts, and various formatting utilities required
-// for AFH 33-337 compliance.
-//
-// Key components:
-// - Spacing constants and configuration management
-// - Paragraph numbering and indentation utilities
-// - Grid layout and backmatter formatting functions
-// - Date formatting and content scaling utilities
-// - Indorsement processing and ordinal number generation
+// Spacing, normalization, and formatting helpers shared across the template.
 
 #import "config.typ": CLASSIFICATION_COLORS, counters, paragraph-config, spacing
 
-// Shared measured line-stride cache used by body line-count heuristics.
-// Value is a `length` set once in `frontmatter`.
+// Measured height of one wrapped body line, set once in `frontmatter`.
 #let LINE_STRIDE = state("LINE_STRIDE")
 
 /// The height one wrapped line of body text occupies.
@@ -48,25 +35,16 @@
 }
 
 /// Creates vertical spacing equivalent to one blank line.
-/// Convenience function for single line spacing.
 ///
 /// -> content
 #let blank-line() = blank-lines(1)
 
-// =============================================================================
-// GENERAL UTILITY FUNCTIONS
-// =============================================================================
-
 /// Checks if a value is "falsey" (none, false, empty array, empty string, or
 /// empty content).
 ///
-/// Provides a consistent way to test for empty or missing values across
-/// the template system. Used for conditional rendering of optional sections.
-///
-/// Content fields (`plaintext` / `richtext`) reach the template in one of two
-/// shapes: a blank one as the empty string `""`, a filled one as a markup
-/// block. Empty content (`[]`) is covered too, since that is what an emptied
-/// block and `join()`-over-nothing produce.
+/// A caller may hand a field over as a `str` or as content, so both empty
+/// shapes count: `""` and `[]`. Empty content is what an emptied markup block
+/// and `join()`-over-nothing both produce.
 ///
 /// - value (any): The value to check for "falsey" status
 /// -> bool
@@ -80,11 +58,9 @@
   )
 }
 
-/// Scales content to fit within a specified box while maintaining aspect ratio.
+/// Scales content uniformly to fit a fixed-size box, preserving aspect ratio.
 ///
-/// Automatically measures content and calculates uniform scaling to fit within
-/// the given dimensions. Commonly used for letterhead seals and other images
-/// that need to fit specific size constraints while preserving proportions.
+/// Used for letterhead seals and emblems, whose source images vary in size.
 ///
 /// - width (length): Maximum width for the content (default: 2in)
 /// - height (length): Maximum height for the content (default: 1in)
@@ -92,13 +68,9 @@
 /// - body (content): Content to scale and fit
 /// -> content
 #let fit-box(width: 2in, height: 1in, alignment: left + horizon, body) = context {
-  // 1) measure the unscaled content
   let s = measure(body)
-
-  // 2) compute the uniform scale that fits inside the box
   let f = calc.min(width / s.width, height / s.height) * 100% // ratio
-
-  // 3) fixed-size box, center the scaled content, and reflow so layout respects it
+  // `reflow: true` so layout respects the scaled size rather than the original.
   box(width: width, height: height, clip: true)[
     #align(alignment)[
       #scale(f, reflow: true)[#body]
@@ -177,24 +149,25 @@
 /// line tall and sits on the baseline, so the slot lines up with where a
 /// printed date would sit and takes exactly the space one would take.
 ///
-/// `field` is the caller's fill-in widget — the Quillmark helper's
-/// `form-field(.., type: "text")`, which lowers to a fillable AcroForm text box
-/// in PDF output. It is anchored at the slot's top-left corner, the corner the
-/// widget's own rectangle grows right and down from, so a widget declared at
-/// this slot's dimensions covers it exactly. `none` (a caller with no widget to
-/// give, e.g. the package used outside Quillmark) leaves the slot blank.
+/// `field` is the caller's fill-in widget, an interactive element such as a
+/// PDF form field. It is anchored at the slot's top-left corner, the corner
+/// such a widget's own rectangle grows right and down from, so one declared at
+/// this slot's dimensions covers it exactly. With no widget to anchor, the slot
+/// rules its baseline instead, for the endorser to date by hand.
 ///
 /// - field (content | none): Fill-in widget to anchor in the slot
 /// - width (length): Width of the slot; defaults to fit a long date such as
 ///   "15 September 2026".
 /// -> content
-#let date-placeholder-slot(field, width: 1in) = box(
+#let date-placeholder-slot(field: none, width: 1in) = box(
   width: width,
   height: 1em,
   // Keep the slot's bottom edge on the line's baseline, where the printed date
-  // would sit; the 1em height then reserves the line above it.
+  // would sit; the 1em height then reserves the line above it — the space a
+  // handwritten date is written in.
   // (A positive baseline shift would drop the box a full line too low.)
   baseline: 0pt,
+  stroke: if field == none { (bottom: 0.5pt + black) },
   if field != none { place(top + left, field) },
 )
 
@@ -220,56 +193,41 @@
   rgb(0, 0, 0)
 }
 
-// =============================================================================
-// GRID LAYOUT UTILITIES
-// =============================================================================
-
-/// Creates an automatic grid layout from a cell value or array of them.
-///
-/// Converts 1D content into a multi-column grid layout with proper spacing.
-/// Used primarily for formatting recipient lists in the "MEMORANDUM FOR" section
-/// where multiple organizations need to be displayed in columns.
+/// Arranges one cell or an array of them into a `cols`-wide grid, filled
+/// row-major. Used for the MEMORANDUM FOR recipient list.
 ///
-/// Features:
-/// - Automatic column distribution and row filling
-/// - Configurable column spacing and count
-/// - Handles a single cell or an array of them, as `str` or as content
-/// - Adds padding cells to maintain consistent column alignment
-///
-/// Cells may be content, not just `str`: a `plaintext` recipient list lowers
-/// each element to a markup block, which is what makes the rendered glyphs
-/// carry their own spans and so become click-navigable.
+/// Cells may be content as readily as `str`, so a caller that builds each
+/// recipient as markup — to keep the rendered glyphs traceable to their
+/// source — passes it through unflattened.
 ///
 /// - content (str | content | array): Cell(s) to arrange in grid
 /// - column-gutter (length): Space between columns (default: 0.5em)
 /// - cols (int): Number of columns for the grid (default: 3)
 /// -> grid
 #let create-auto-grid(content, column-gutter: .5em, cols: 3) = {
-  let content_type = type(content)
+  let content-type = type(content)
 
-  // Normalize to 1d array. A lone cell — `str` or content — is a one-cell grid.
-  if content_type != array {
+  if content-type != array {
     content = (content,)
   }
 
 
-  // Build cell array in row-major order
+  // Each row carries a trailing empty cell, so a row is `cols + 1` wide — the
+  // width both this loop and the tail padding below count against.
   let cells = ()
   let i = 0
   for item in content {
     i += 1
     cells.push(item)
     if calc.rem(i, cols) == 0 {
-      // Add empty cell to pad the page
       cells.push([])
     }
   }
 
-  // Add padding cells to complete the last row if needed
   let remainder = calc.rem(cells.len(), cols + 1)
   if remainder != 0 {
-    let padding_needed = (cols + 1) - remainder
-    for _ in range(padding_needed) {
+    let padding-needed = (cols + 1) - remainder
+    for _ in range(padding-needed) {
       cells.push([])
     }
   }
@@ -282,23 +240,10 @@
   )
 }
 
-// =============================================================================
-// TYPE NORMALIZATION UTILITIES
-// =============================================================================
-
-/// Ensures the input is an array. If already an array, returns as-is.
-/// If not an array, wraps the value in a tuple.
-///
-/// This utility eliminates repetitive `if type(x) == array` checks throughout
-/// the codebase by providing a canonical "normalize to array" function.
+/// Normalizes a value to an array, wrapping a scalar and mapping `none` to `()`.
 ///
 /// - value: Any value to normalize to array form
-/// - Returns: Array containing the value(s)
-///
-/// Examples:
-/// - ensure-array("foo") → ("foo",)
-/// - ensure-array(("a", "b")) → ("a", "b")
-/// - ensure-array(none) → ()
+/// -> array
 #let ensure-array(value) = {
   if value == none {
     ()
@@ -312,22 +257,18 @@
 /// Normalizes a scalar-or-array field to a single stacked-lines **content**
 /// value, one array element per line.
 ///
-/// This is the content-safe successor to the former `ensure-string`: every
-/// prose field the quill declares is now a `plaintext` / `richtext` field, so
-/// it arrives as Typst *content* (a markup block), and `str(..)` on content is
-/// an error. Joining with `linebreak()` rather than `"\n"` renders the same
+/// A field may arrive as a `str` or as content, and `str(..)` on content is an
+/// error. Joining with `linebreak()` rather than `"\n"` renders the same
 /// stacked lines while accepting either shape.
 ///
-/// A blank content field arrives as `""` and lands as empty content, which
-/// stays `falsey` for callers that test the result.
+/// A blank field lands as empty content, which stays `falsey` for callers that
+/// test the result.
 ///
 /// - value (any): Scalar or array of scalars/content to stack
 /// -> content
 ///
 /// Examples:
-/// - join-lines("foo") → [foo]
 /// - join-lines(([a], [b])) → [a] + linebreak() + [b]
-/// - join-lines(()) → []
 /// - join-lines(none) → []
 #let join-lines(value) = {
   if value == none { return [] }
@@ -339,20 +280,11 @@
   if joined == none { [] } else { joined }
 }
 
-/// Extracts the first element from an array, or returns the value if not an array.
-///
-/// This utility eliminates repetitive ternary operators like
-/// `if type(x) == array { x.at(0) } else { x }` by providing a canonical
-/// "first element or self" function.
+/// The first element of an array, or the value itself when it is not one.
+/// An empty array and `none` both yield `none`.
 ///
 /// - value: Any value to extract from
-/// - Returns: First array element if array, otherwise the value itself
-///
-/// Examples:
-/// - first-or-value("foo") → "foo"
-/// - first-or-value(("a", "b")) → "a"
-/// - first-or-value(()) → none
-/// - first-or-value(none) → none
+/// -> any
 #let first-or-value(value) = {
   if value == none {
     none
@@ -368,19 +300,10 @@
 }
 
 
-// =============================================================================
-// INDORSEMENT UTILITIES
-// =============================================================================
-
-/// Converts number to ordinal suffix for indorsements following AFH 33-337 conventions.
+/// The ordinal suffix for an indorsement number: 1st, 2d, 3d, 4th, …
 ///
-/// AFH 33-337 Chapter 14 indorsement examples show "1st Ind", "2d Ind", "3d Ind" format.
-/// Note: Military style uses "2d" and "3d" instead of "2nd" and "3rd" per DoD correspondence standards.
-///
-/// Generates proper ordinal suffixes for indorsement numbering:
-/// - 1st, 2d, 3d, 4th, 5th, etc. (note: military uses "2d" and "3d", not "2nd" and "3rd")
-/// - Special handling for 11th, 12th, 13th (all use "th")
-/// - Follows official military correspondence standards
+/// Military correspondence writes "2d" and "3d" where ordinary English writes
+/// "2nd" and "3rd"; 11th through 13th take "th" as usual.
 ///
 /// - number (int): The indorsement number (1, 2, 3, etc.)
 /// -> str
@@ -401,12 +324,7 @@
   }
 }
 
-/// Formats indorsement number according to AFH 33-337 standards.
-///
-/// Creates properly formatted indorsement labels with ordinal suffixes:
-/// - "1st Ind", "2d Ind", "3d Ind", "4th Ind", etc.
-/// - Uses military-specific ordinal format (2d/3d instead of 2nd/3rd)
-/// - Combines with "Ind" suffix for standard indorsement header format
+/// An indorsement's header label: "1st Ind", "2d Ind", "3d Ind", …
 ///
 /// - number (int): Indorsement sequence number (1, 2, 3, etc.)
 /// -> str
@@ -414,21 +332,3 @@
   let suffix = get-ordinal-suffix(number)
   str(number) + suffix + " Ind"
 }
-
-/// Processes and renders an array of indorsements.
-///
-/// Iterates through an array of indorsement objects and renders each one
-/// with proper formatting and font settings. Used by the main memorandum
-/// template to process the indorsements parameter.
-///
-/// - indorsements (array): Array of indorsement objects created with indorsement()
-/// - body-font (str | array): Font(s) to use for indorsement text
-/// - font-size (length): Font size for indorsement text (default: 12pt)
-/// -> content
-#let process-indorsements(indorsements, body-font: none, font-size: 12pt) = {
-  if not falsey(indorsements) {
-    for indorsement in indorsements {
-      (indorsement.render)(body-font: body-font, font-size: font-size)
-    }
-  }
-}

package/quills/usaf_memo/0.3.0/packages/tonguetoquill-usaf-memo/typst.toml

@@ -1,11 +1,11 @@
 [package]
 name = "tonguetoquill-usaf-memo"
-version = "4.0.0"
-compiler = "0.14.0"
+version = "5.0.0"
+compiler = "0.15.1"
 entrypoint = "src/lib.typ"
 repository = "https://github.com/nibsbin/tonguetoquill-usaf-memo"
 authors = ["Nibs"]
-license = "MIT"
+license = "Apache-2.0"
 description = "Typeset memos that are fully compliant with AFH 33-337 'The Tongue and Quill'."
 keywords = [
     "USAF",
@@ -20,8 +20,3 @@ keywords = [
 ]
 categories = ["office", "report"]
 disciplines = ["politics", "law", "business", "engineering", "education"]
-
-[template]
-path = "template"
-entrypoint = "usaf-template.typ"
-thumbnail = "template/assets/thumbnail.png"

package/quills/usaf_memo/0.3.0/plate.typ

@@ -1,7 +1,7 @@
 #import "@local/quillmark-helper:0.1.0": (
-  data, display, field-region, form-field, signature-field,
+  data, display, form-field, signature-field,
 )
-#import "@local/tonguetoquill-usaf-memo:4.0.0": (
+#import "@local/tonguetoquill-usaf-memo:5.0.0": (
   backmatter, date-pattern, frontmatter, indorsement, mainmatter,
 )
 
@@ -16,28 +16,48 @@
 // leaves no glyphs and takes no space from the flow, and the seal stands alone.
 #let letterhead_lines = data.letterhead_title
 
-// Body text size, in points. Also the height of one line of the indorsement
-// header, which is what an omitted indorsement date reserves for its fill-in
-// widget (`date-placeholder-slot`, whose slot is `1em` tall and 1in wide).
+// Body text size, in points. Also the height of a blank date's fill-in widget.
 #let body_font_size = data.font_size * 1pt
 
-// Frontmatter configuration
+// A blank date's fill-in slot: an empty AcroForm text box the signer types the
+// date into, set in the body face, the value flush right in the date line's
+// slot as the printed date would sit. Wide enough for the longest date either
+// style prints, "September 30, 2026", which runs 8em in the body face.
+//
+// The slot is built here rather than through the package's
+// `date-placeholder-slot`: that slot stands `1em` above the baseline, and a
+// text line only a cap-height, so a blank date grew its line and pushed
+// everything below it down. This one claims exactly a cap-height, the extent of
+// a printed date, and the widget overhangs it about the line's middle, taking
+// no room from the flow.
+#let date_slot_width = body_font_size * 8.5
+#let date_slot(name, field) = context box(
+  width: date_slot_width,
+  height: measure[0].height,
+  place(horizon + left, form-field(
+    name,
+    type: "text",
+    width: date_slot_width,
+    height: body_font_size,
+    field: field,
+    font: "times",
+    size: body_font_size,
+    align: "right",
+  )),
+)
+
 #show: frontmatter.with(
-  // Letterhead configuration
-  letterhead_title: letterhead_lines.at(0, default: ""),
-  letterhead_caption: if letterhead_lines.len() > 1 { letterhead_lines.slice(1) } else { () },
-  letterhead_seal_subtitle: data.letterhead_seal_subtitle,
-  // Enum blank is `""`, not a seal. Omit so the package renders none rather
-  // than treating the blank as DoW.
-  ..if data.letterhead_seal != "" {
-    (letterhead_seal: image(
-      if data.letterhead_seal == "dod" {
-        "assets/dod_seal.png"
-      } else {
-        "assets/dow_seal.png"
-      }
-    ))
-  },
+  letterhead-title: letterhead_lines.at(0, default: ""),
+  letterhead-caption: if letterhead_lines.len() > 1 { letterhead_lines.slice(1) } else { () },
+  letterhead-seal-subtitle: data.letterhead_seal_subtitle,
+  // A memo has no seal-less state, so the blank takes the default, DoW.
+  letterhead-seal: image(
+    if data.letterhead_seal == "dod" {
+      "assets/dod_seal.png"
+    } else {
+      "assets/dow_seal.png"
+    }
+  ),
 
   // Date. `data.date` is the native `datetime` and would render identically,
   // but its ink would be born inside the package and carry no schema address.
@@ -45,41 +65,26 @@
   // born in the generated helper, so the memo date stays click-to-edit however
   // deep the package formats it.
   //
-  // A blank date means today's, and the plate stamps it rather than falling
-  // through to `frontmatter`'s own `datetime.today()`: package-born ink carries
-  // no address, so the one date a memo never types would be the one date a
-  // preview cannot click. `field-region` claims that ink for the field instead.
-  //
-  // The stamp is markup, not the bare `str` `.display()` returns: a `str` off a
-  // function call carries no source position, and ink with none is unclaimable.
-  date: {
-    let pattern = date-pattern(memo-style: memo_style)
-    let authored = display("date", pattern)
-    if authored != none {
-      authored
-    } else {
-      field-region("date", [#datetime.today().display(pattern)])
-    }
-  },
+  // A blank date is left for the signer: a memo is dated when it is signed,
+  // which is generally not when it is rendered, so the slot is fillable rather
+  // than stamped with the compile date.
+  date: display("date", date-pattern(memo-style: memo_style)),
+  date-field: date_slot("Date", "date"),
 
-  // Receiver information
-  memo_for: data.memo_for,
+  memo-for: data.memo_for,
 
-  // Sender information (omitted for Memorandum for Record)
-  ..if data.memo_from.len() > 0 { (memo_from: data.memo_from) },
+  // A memo with no FROM line is a Memorandum for Record.
+  ..if data.memo_from.len() > 0 { (memo-from: data.memo_from) },
 
-  // Subject line
   subject: data.subject,
 
-  // Optional references
   ..if data.references.len() > 0 { (references: data.references) },
 
-  // Optional footer tag line
-  footer_tag_line: data.tag_line,
+  footer-tag-line: data.tag_line,
 
   // The blank reads as no banner, which is what the package's own
-  // `classification_level: none` default means.
-  classification_level: data.classification.value,
+  // `classification-level: none` default means.
+  classification-level: data.classification.value,
 
   dissemination: data.dissemination,
 
@@ -90,51 +95,45 @@
   // own `cui_*: none` defaults cover the worlds that omit them.
   ..if data.classification.value == "CUI" {
     (
-      cui_controlled_by: data.classification.controlled_by,
-      cui_category: data.classification.category,
-      cui_limited_dissemination: data.classification.limited_dissemination,
-      cui_poc: data.classification.poc,
+      cui-controlled-by: data.classification.controlled_by,
+      cui-category: data.classification.category,
+      cui-limited-dissemination: data.classification.limited_dissemination,
+      cui-poc: data.classification.poc,
     )
   },
 
-  // USAF vs DAF memorandum style (date format, body indentation).
-  memo_style: memo_style,
+  memo-style: memo_style,
 
-  // Font size
-  font_size: body_font_size,
+  font-size: body_font_size,
 
-  // List recipients in vertical list
-  memo_for_cols: 1,
+  // One recipient per line; the package's own default is three columns.
+  memo-for-cols: 1,
 )
 
-// Mainmatter. The body's region needs no recovery step here: the package's
-// render-body rebuilds paragraphs through a state buffer (AFH 33-337
-// auto-numbering), but the rebuilt glyphs keep their spans, which is what
-// the backend reads regions from.
+// The body's region needs no recovery step here: the package's render-body
+// rebuilds paragraphs through a state buffer (AFH 33-337 auto-numbering), but
+// the rebuilt glyphs keep their spans, which is what the backend reads regions
+// from.
 #mainmatter[
   #data.at("$body")
 ]
 
-// Backmatter
 #backmatter(
-  // Signature block
-  signature_block: data.signature_block,
+  authority-line: data.authority_line,
+  signature-block: data.signature_block,
   // The widget sits at the bottom of AFH 33-337's four blank lines and is
   // sized to two and a half of them, so the line and a half above it stays
   // clear of the body text without moving the block off the fifth line.
-  signing_field: signature-field(
+  signing-field: signature-field(
     "Signature",
     field: "signature_block",
     height: body_font_size * 2.5,
   ),
 
-  // Optional cc
   ..if data.cc.len() > 0 { (cc: data.cc) },
 
-  // Optional distribution
   ..if data.distribution.len() > 0 { (distribution: data.distribution) },
 
-  // Optional attachments
   ..if data.attachments.len() > 0 { (attachments: data.attachments) },
 )
 
@@ -158,7 +157,6 @@
     .at(-1, default: -1)
 )
 
-// Indorsements - iterate through CARDS array and filter by CARD tag
 #for (i, card) in data.at("$cards").enumerate() {
   if card.at("$kind", default: none) == "indorsement" {
     // The quillmark helper leaves an unset/whitespace-only markdown body as
@@ -187,29 +185,24 @@
     indorsement(
       from: card.at("from", default: ""),
       to: card.at("for", default: ""),
-      signature_block: card.signature_block,
-      signing_field: signature-field(
+      authority-line: card.authority_line,
+      signature-block: card.signature_block,
+      signing-field: signature-field(
         "Ind_" + str(i) + "_Signature",
         field: card.at("$path") + "signature_block",
         height: body_font_size * 2.5,
       ),
       ..if card.format != "" { (format: card.format) },
-      date: resolved_date,
-      // An omitted date becomes an empty AcroForm text box the endorser types
-      // the signing date into, sized to the slot the package reserves for it.
-      // Built only when there is no date to print: a widget over a printed date
-      // would offer an edit that the rendered document does not carry back.
-      ..if resolved_date == none {
-        (date_field: form-field(
-          "Ind_" + str(i) + "_Date",
-          type: "text",
-          width: 1in,
-          height: body_font_size,
-          field: card.at("$path") + "date",
-        ))
+      // An omitted date becomes a fill-in slot for the signing date. Built only
+      // when there is no date to print: a widget over a printed date would offer
+      // an edit that the rendered document does not carry back.
+      date: if resolved_date != none {
+        resolved_date
+      } else {
+        date_slot("Ind_" + str(i) + "_Date", card.at("$path") + "date")
       },
       ..if card.action != "" { (action: card.action) },
-      approval_authority: i == last_indorsement_index,
+      approval-authority: i == last_indorsement_index,
       body_content,
     )
   }

package/templates/af4141.md

@@ -0,0 +1,23 @@
+~~~card-yaml
+$quill: af4141@0.1
+$kind: main
+# EDIT: Full name in Last, First, Middle Initial format
+name: LAST, FIRST M.
+# EDIT: Unit of assignment (e.g., "1 ACCS/DOT", "726 ACS/MOC")
+unit: UNIT/SYMBOL
+# EDIT: Current grade or CCC level (e.g., "SSgt", "GS-12", "3")
+grade: GRADE
+# EDIT: Commander's authentication entry
+commanders_auth: ""
+~~~
+
+~~~card-yaml
+$kind: experience
+date: 2025-01-01
+action: Describe the action or event
+written_grade: ""
+written_grade_date: 2025-01-01
+positional_grade: ""
+positional_grade_date: 2025-01-01
+auth_or_remarks: ""
+~~~