@airmark/quiver 0.32.2 → 0.34.0

package/quills/usaf_letter/0.1.0/packages/tonguetoquill-usaf-letter/src/utils.typ

@@ -0,0 +1,334 @@
+// Spacing, normalization, and formatting helpers shared across the template.
+
+#import "config.typ": CLASSIFICATION_COLORS, counters, paragraph-config, spacing
+
+// 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.
+///
+/// Read from `LINE_STRIDE` (cached in `frontmatter`), falling back to an inline
+/// measurement when the cache is unset. Reads state, so callers must already be
+/// in a `context`.
+///
+/// -> length
+#let line-stride() = {
+  let stride = LINE_STRIDE.get()
+  if stride == none {
+    let one-line = measure(par(spacing: 0pt)[x]).height
+    stride = measure(par(spacing: 0pt)[x#linebreak()x]).height - one-line
+  }
+  stride
+}
+
+/// Creates vertical spacing equivalent to multiple blank lines.
+///
+/// Adds `count` wrapped-line strides on top of the natural inter-paragraph
+/// gap, so a blank line occupies exactly the same vertical space as a line
+/// produced by natural paragraph wrapping.
+///
+/// - count (int): Number of blank lines to create
+/// -> content
+#let blank-lines(count) = {
+  if count <= 0 { return }
+  context { v(line-stride() * count) }
+}
+
+/// Creates vertical spacing equivalent to one blank line.
+///
+/// -> content
+#let blank-line() = blank-lines(1)
+
+/// Checks if a value is "falsey" (none, false, empty array, empty string, or
+/// empty content).
+///
+/// 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
+#let falsey(value) = {
+  (
+    value == none
+      or value == false
+      or (type(value) == array and value.len() == 0)
+      or (type(value) == str and value == "")
+      or value == []
+  )
+}
+
+/// Scales content uniformly to fit a fixed-size box, preserving aspect ratio.
+///
+/// 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)
+/// - alignment (alignment): Content alignment within the box (default: left+horizon)
+/// - body (content): Content to scale and fit
+/// -> content
+#let fit-box(width: 2in, height: 1in, alignment: left + horizon, body) = context {
+  let s = measure(body)
+  let f = calc.min(width / s.width, height / s.height) * 100% // ratio
+  // `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]
+    ]
+  ]
+}
+
+/// Shrinks content to fit within a maximum width, never enlarging it.
+///
+/// Measures `body` at its current font size and scales it down uniformly only
+/// when it is wider than `width`; content that already fits keeps its set size
+/// (the scale is capped at 100%). Unlike `fit-box`, height flows naturally and
+/// small content is never scaled up. Used for the letterhead caption (unit
+/// designation): a long name is shrunk to the width that clears the seal rather
+/// than running underneath it. Pass a non-wrapping `box` as `body` so the
+/// measured width is the single-line width and the result stays on one line.
+///
+/// Empty content measures 0pt wide and has no scale to compute, so it is returned
+/// as-is rather than divided by; a non-positive `width` likewise admits no scale
+/// that fits, so the body is left at its set size instead of being flipped or
+/// collapsed.
+///
+/// - width (length): Maximum width the content may occupy
+/// - alignment (alignment): Horizontal placement within the reserved width
+/// - body (content): Content to fit (typically a non-wrapping `box`)
+/// -> content
+#let fit-to-width(width, alignment: left, body) = context {
+  let s = measure(body)
+  if s.width <= 0pt or width <= 0pt { return body }
+  let f = calc.min(1, width / s.width) * 100% // ratio, capped so it only shrinks
+  box(width: width)[
+    #align(alignment)[
+      #scale(f, reflow: true)[#body]
+    ]
+  ]
+}
+
+/// The date pattern a memo style prints, per AFH 33-337. Exported so a caller
+/// that pre-formats the date matches this package instead of restating it.
+///
+/// - memo-style (str): `"usaf"` or `"daf"`
+/// -> str
+#let date-pattern(memo-style: "usaf") = if memo-style == "daf" {
+  "[month repr:long] [day padding:none], [year]"
+} else {
+  "[day padding:none] [month repr:long] [year]"
+}
+
+/// Formats a date for the memo heading.
+///
+/// - str, content: shown as-is (a fixed placeholder, or ink the caller already
+///   formatted through [`date-pattern`]).
+/// - datetime: USAF style `DD Month YYYY`; DAF style `Month DD, YYYY`.
+///
+/// - date (str | content | datetime): Date to format for display
+/// - memo-style (str): `"usaf"` or `"daf"`
+/// -> content
+#let display-date(date, memo-style: "usaf") = {
+  assert(
+    memo-style in ("usaf", "daf"),
+    message: "memo-style for display-date must be \"usaf\" or \"daf\"",
+  )
+  // A caller that pre-formatted — to keep a click-to-edit region the package
+  // cannot mint itself — passes the finished ink through untouched.
+  if type(date) in (str, content) {
+    date
+  } else {
+    date.display(date-pattern(memo-style: memo-style))
+  }
+}
+
+/// Reserves the space a date occupies, for a date unknown at compile time.
+///
+/// Used for indorsements whose signing date is not known when the memo is
+/// rendered: the endorser supplies it after the fact. The reserved box is one
+/// 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, 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: 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 — 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) },
+)
+
+/// Gets the banner color for a classification marking.
+///
+/// Matches when `level` (trimmed) starts with a known prefix: TOP SECRET, SECRET,
+/// CONFIDENTIAL, CUI, or UNCLASSIFIED. Otherwise returns black.
+///
+/// - level (str): Marking string shown in header/footer
+/// -> color
+#let get-classification-level-color(level) = {
+  if level == none or type(level) != str {
+    return rgb(0, 0, 0)
+  }
+  let s = level.trim()
+  // Longest-prefix-first so e.g. "TOP SECRET" wins over "SECRET".
+  let level-order = ("TOP SECRET", "SECRET", "CONFIDENTIAL", "CUI", "UNCLASSIFIED")
+  for base-level in level-order {
+    if s.starts-with(base-level) {
+      return CLASSIFICATION_COLORS.at(base-level)
+    }
+  }
+  rgb(0, 0, 0)
+}
+
+/// Arranges one cell or an array of them into a `cols`-wide grid, filled
+/// row-major. Used for the MEMORANDUM FOR recipient list.
+///
+/// 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)
+
+  if content-type != array {
+    content = (content,)
+  }
+
+
+  // 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 {
+      cells.push([])
+    }
+  }
+
+  let remainder = calc.rem(cells.len(), cols + 1)
+  if remainder != 0 {
+    let padding-needed = (cols + 1) - remainder
+    for _ in range(padding-needed) {
+      cells.push([])
+    }
+  }
+
+  grid(
+    columns: calc.max(1, cols) + 1,
+    column-gutter: .1fr,
+    row-gutter: spacing.line,
+    ..cells
+  )
+}
+
+/// Normalizes a value to an array, wrapping a scalar and mapping `none` to `()`.
+///
+/// - value: Any value to normalize to array form
+/// -> array
+#let ensure-array(value) = {
+  if value == none {
+    ()
+  } else if type(value) == array {
+    value
+  } else {
+    (value,)
+  }
+}
+
+/// Normalizes a scalar-or-array field to a single stacked-lines **content**
+/// value, one array element per line.
+///
+/// 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 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(([a], [b])) → [a] + linebreak() + [b]
+/// - join-lines(none) → []
+#let join-lines(value) = {
+  if value == none { return [] }
+  let items = if type(value) == array { value } else { (value,) }
+  // A `str` element is wrapped so the join is content-to-content throughout;
+  // mixing `str` and content under `+` is not a legal Typst addition.
+  let joined = items.map(item => [#item]).join(linebreak())
+  // `().join(..)` is `none`, not `[]` — coerce so an empty array stays `falsey`.
+  if joined == none { [] } else { joined }
+}
+
+/// 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
+/// -> any
+#let first-or-value(value) = {
+  if value == none {
+    none
+  } else if type(value) == array {
+    if value.len() > 0 {
+      value.at(0)
+    } else {
+      none
+    }
+  } else {
+    value
+  }
+}
+
+
+/// The ordinal suffix for an indorsement number: 1st, 2d, 3d, 4th, …
+///
+/// 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
+#let get-ordinal-suffix(number) = {
+  let last-digit = calc.rem(number, 10)
+  let last-two-digits = calc.rem(number, 100)
+
+  if last-two-digits >= 11 and last-two-digits <= 13 {
+    "th"
+  } else if last-digit == 1 {
+    "st"
+  } else if last-digit == 2 {
+    "d"
+  } else if last-digit == 3 {
+    "d"
+  } else {
+    "th"
+  }
+}
+
+/// An indorsement's header label: "1st Ind", "2d Ind", "3d Ind", …
+///
+/// - number (int): Indorsement sequence number (1, 2, 3, etc.)
+/// -> str
+#let format-indorsement-number(number) = {
+  let suffix = get-ordinal-suffix(number)
+  str(number) + suffix + " Ind"
+}

package/quills/usaf_letter/0.1.0/packages/tonguetoquill-usaf-letter/typst.toml

@@ -0,0 +1,22 @@
+[package]
+name = "tonguetoquill-usaf-letter"
+version = "0.1.0"
+compiler = "0.15.1"
+entrypoint = "src/lib.typ"
+repository = "https://github.com/tonguetoquill/airmark-quiver"
+authors = ["tonguetoquill"]
+license = "Apache-2.0"
+description = "Typeset USAF personal letters per AFH 33-337 'The Tongue and Quill'."
+keywords = [
+    "USAF",
+    "Air Force",
+    "personal letter",
+    "letter",
+    "military",
+    "AFH 33-337",
+    "official",
+    "correspondence",
+    "formatting",
+]
+categories = ["office"]
+disciplines = ["politics", "business", "education"]

package/quills/usaf_letter/0.1.0/plate.typ

@@ -0,0 +1,121 @@
+#import "@local/quillmark-helper:0.1.0": (
+  data, display, form-field, signature-field,
+)
+#import "@local/tonguetoquill-usaf-letter:0.1.0": (
+  backmatter, date-pattern, frontmatter, mainmatter,
+)
+
+// The letterhead arrives as one ordered array of lines. Element 0 is the title,
+// set larger; the rest are caption lines beneath it. A single element renders
+// the title alone — the package skips a falsey caption. An empty array renders
+// no letterhead text at all, silently: the block is `place`d, so an empty title
+// 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 a blank date's fill-in widget.
+#let body_font_size = data.font_size * 1pt
+
+// A blank date's fill-in slot: an empty AcroForm text box the signer types the
+// date into, set in the body face and flush right, as the printed date would
+// be. Wide enough for the longest date, "30 September 2026", which runs 8em in
+// the body face.
+//
+// The slot claims a cap-height, the extent of a printed date, and the widget
+// overhangs it about the line's middle, so a blank date takes no more room from
+// the flow than a printed one and the page lays out the same either way.
+#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-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 letter 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.
+  // `display` places the field's *content* projection instead: the glyphs are
+  // born in the generated helper, so the letter's date stays click-to-edit
+  // however deep the package formats it.
+  //
+  // A blank date is left for the signer: a letter 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. Passing it as the date also keeps it
+  // from `frontmatter`'s own `datetime.today()` fallback.
+  date: {
+    let authored = display("date", date-pattern())
+    if authored != none { authored } else { date_slot("Date", "date") }
+  },
+
+  letter-from: data.letter_from,
+  letter-for: data.letter_for,
+  salutation: data.salutation,
+
+  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,
+
+  dissemination: data.dissemination,
+
+  // CUI designation indicator block fields (DoDM 5200.48). `classification`
+  // declares a `CUI` variant, so these four exist only where the discriminant
+  // reads CUI, and the branch is what makes reading them total: inside it every
+  // declared field of that world is present, outside it none is. The package's
+  // 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,
+    )
+  },
+
+  font-size: body_font_size,
+)
+
+// An empty body reaches the plate as `""`, and `mainmatter` would still set a
+// blank paragraph for it, dropping the close two lines too far.
+#if data.at("$body") != "" {
+  mainmatter[#data.at("$body")]
+}
+
+#backmatter(
+  complimentary-close: data.complimentary_close,
+  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 complimentary close without moving the block off the fifth
+  // line.
+  signing-field: signature-field(
+    "Signature",
+    field: "signature_block",
+    height: body_font_size * 2.5,
+  ),
+
+  ..if data.attachments.len() > 0 { (attachments: data.attachments) },
+
+  ..if data.cc.len() > 0 { (cc: data.cc) },
+)

package/quills/usaf_memo/0.2.0/Quill.yaml

@@ -8,21 +8,14 @@ typst:
   plate_file: plate.typ
 
 main:
+  description: Top-level body paragraphs are numbered and nested bullets lettered automatically; do not number them by hand.
   ui:
     groups: [addressing, letterhead, classification, additional]
-  body:
-    example: |
-      The first paragraph. Top-level paragraphs are auto-numbered; do not add manual numbering.
-
-      - Nested bullets are automatically lettered.
   fields:
     memo_for:
       type: array
       items:
         type: string
-      example:
-        - ORG1/SYMBOL
-        - ORG2/SYMBOL
       ui:
         group: addressing
         compact: true
@@ -33,19 +26,13 @@ main:
       items:
         type: string
       default: []
-      example:
-        - ORG/SYMBOL
-        - Organization Name
-        - 123 Street Ave
-        - City ST 12345-6789
       ui:
         group: addressing
         compact: true
-      description: "If recipients are on the same installation, use only the office symbol. For recipients on other installations, include the full mailing address to enable return correspondence. Omit entirely to produce a Memorandum for Record (no MEMO FROM line)."
+      description: "If recipients are on the same installation, use only the office symbol. For recipients on other installations, include the full mailing address, one line each, ending 'City ST 12345-6789', to enable return correspondence. Omit entirely to produce a Memorandum for Record (no MEMO FROM line)."
 
     subject:
       type: string
-      example: Subject of the Memorandum
       ui:
         group: addressing
       description: Be brief and clear. Capitalize the first letter of each word except articles, prepositions, and conjunctions. Include suspense dates in parentheses if applicable.
@@ -54,13 +41,10 @@ main:
       type: array
       items:
         type: string
-      example:
-        - "FIRST M. LAST, Rank, USAF"
-        - Duty Title
       ui:
         group: addressing
         compact: true
-      description: "Line 1: Name in UPPERCASE as signed, grade, and service. Line 2: Duty title."
+      description: "Line 1: Name in UPPERCASE as signed, grade, and service, as in 'FIRST M. LAST, Capt, USAF'. Line 2: Duty title."
 
     letterhead_title:
       type: string
@@ -73,11 +57,9 @@ main:
       type: array
       items:
         type: string
-      example:
-        - HEADQUARTERS [UNIT NAME]
       ui:
         group: letterhead
-      description: The full organization name of your unit.
+      description: The full organization name of your unit, as in HEADQUARTERS 123D EXAMPLE WING.
 
     letterhead_seal:
       type: enum
@@ -167,9 +149,6 @@ main:
         type: richtext
         inline: true
       default: []
-      example:
-        - "AFMAN 33-326, 25 November 2011, *Preparing Official Communications*"
-        - "AFI 33-360, *Publications and Forms Management*"
       ui:
         group: additional
       description: "References, auto-lettered (a), (b), (c) per AFH 33-337. Cite each by organization, type, date, and title; italicize publication titles with *asterisks* (standard Markdown emphasis)."
@@ -179,20 +158,15 @@ main:
       items:
         type: string
       default: []
-      example:
-        - Rank and Name, ORG/SYMBOL
       ui:
         group: additional
-      description: List office symbols of recipients to receive copies.
+      description: List office symbols of recipients to receive copies; for a person, 'Rank and Name, ORG/SYMBOL'.
 
     distribution:
       type: array
       items:
         type: string
       default: []
-      example:
-        - ORG1/SYMBOL
-        - ORG2/SYMBOL
       ui:
         group: additional
       description: Complete list of recipients if 'SEE DISTRIBUTION' is used in the 'Memo For' field.
@@ -202,11 +176,9 @@ main:
       items:
         type: string
       default: []
-      example:
-        - Attachment description, YYYY MMM DD
       ui:
         group: additional
-      description: List attachments in the order they are mentioned in the memo. Briefly describe each; do not use 'as stated' or abbreviations.
+      description: List attachments in the order they are mentioned in the memo. Briefly describe each and give its date; do not use 'as stated' or abbreviations.
 
     memo_style:
       type: enum
@@ -237,21 +209,19 @@ main:
 
 card_kinds:
   indorsement:
+    title: Routing indorsement
     description: Chain of routing endorsements. Each endorsement block adds an official response or forwarding action to the original memo.
     ui:
-      title: Routing indorsement
       groups: [addressing, additional]
     fields:
       from:
         type: string
-        example: ORG/SYMBOL
         ui:
           group: addressing
           compact: true
         description: Office symbol or Rank Name of the endorsing official.
       for:
         type: string
-        example: ORG/SYMBOL
         ui:
           group: addressing
           compact: true
@@ -260,13 +230,10 @@ card_kinds:
         type: array
         items:
           type: string
-        example:
-          - "FIRST M. LAST, Rank, USAF"
-          - Duty Title
         ui:
           group: addressing
           compact: true
-        description: "Line 1: Name in UPPERCASE as signed, grade, and service. Line 2: Duty title."
+        description: "Line 1: Name in UPPERCASE as signed, grade, and service, as in 'FIRST M. LAST, Capt, USAF'. Line 2: Duty title."
       format:
         type: enum
         values:

package/quills/usaf_memo/0.2.0/example.md

@@ -0,0 +1,45 @@
+~~~
+$quill: usaf_memo
+memo_for:
+  - SEE DISTRIBUTION
+memo_from:
+  - 123 CS/SCX
+subject: "Annual Records Management Review (Suspense: 30 October 2026)"
+date: 2026-09-15
+signature_block:
+  - JOHN B. SMITH, Maj, USAF
+  - Director of Operations
+letterhead_caption:
+  - 123D COMMUNICATIONS SQUADRON
+references:
+  - "AFMAN 33-326, 25 November 2011, *Preparing Official Communications*"
+  - "AFI 33-360, *Publications and Forms Management*"
+cc:
+  - 123 WG/CCE
+distribution:
+  - 123 OG/CC
+  - 123 MXG/CC
+  - 123 MSG/CC
+  - 123 MDG/CC
+attachments:
+  - Records Management Self-Inspection Checklist, 1 September 2026
+~~~
+
+Each group reviews every office of record it owns against references (a) and (b) by the suspense in the subject line. Group records custodians confirm two things for each office:
+
+- The file plan lists every series the office keeps, with its disposition authority.
+- Files past cutoff are staged for retirement or destruction.
+
+Return the checklist at the attachment, signed by the group commander, to 123 CS/SCX. Direct questions to 123 CS/SCX at DSN 555-0142.
+
+~~~
+$kind: indorsement
+from: 123 OG/CC
+for: 123 CS/SCX
+date: 2026-10-22
+signature_block:
+  - RICHARD C. ROE, Col, USAF
+  - Commander
+~~~
+
+The 123 OG completed its review on 21 October 2026. All four squadron file plans are current, and 123 OSS retires its two cutoff series by 15 November 2026.