@airmark/quiver 0.32.2 → 0.34.0

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

@@ -0,0 +1,226 @@
+// The personal letter's heading elements, and the page setup the rest of the
+// document inherits: AFH 33-337 "The Personal Letter".
+
+#import "primitives.typ": *
+
+#let frontmatter(
+  letter-for: none,
+  letter-from: none,
+  salutation: none,
+  date: none,
+  letterhead-title: "DEPARTMENT OF THE AIR FORCE",
+  letterhead-caption: "[YOUR SQUADRON/UNIT NAME]",
+  letterhead-seal: none,
+  letterhead-seal-subtitle: none, // optional line under seal (9pt bold caps); ignored if no seal
+  letterhead-emblem: none, // optional image placed opposite the seal (right side)
+  letterhead-emblem-height: 1in, // emblem fit-box height; reduce for shorter emblems
+  letterhead-font: DEFAULT_LETTERHEAD_FONTS,
+  body-font: DEFAULT_BODY_FONTS,
+  font-size: 12pt,
+  classification-level: none,
+  dissemination: none,
+  cui-controlled-by: none,
+  cui-category: none,
+  cui-limited-dissemination: none,
+  cui-poc: none,
+  footer-tag-line: none,
+  it,
+) = {
+  assert(letter-for != none, message: "letter-for is required")
+
+  let actual-date = if date == none { datetime.today() } else { date }
+
+  // The banner is `LEVEL` or `LEVEL//SUFFIX`. `classification-level` is an enum
+  // (a `str`), but `dissemination` may arrive as content, which `str + str`
+  // cannot absorb — so the marking is assembled as content instead.
+  let classification-marking = if classification-level == none or type(classification-level) != str {
+    none
+  } else {
+    let base = classification-level.trim()
+    if base == "" {
+      none
+    } else if falsey(dissemination) {
+      [#base]
+    } else {
+      // `//` is a line comment in Typst markup, so the separator is
+      // interpolated as a string rather than written literally. The suffix is
+      // boxed so the markup block's edge newlines do not read as a space and
+      // split the banner into `CUI// NF`.
+      let separator = "//"
+      [#base#separator#box(upper(dissemination))]
+    }
+  }
+  let classification-color = get-classification-level-color(classification-level)
+
+  // Build the CUI designation indicator block (DoDM 5200.48, Table 1), shown
+  // only for CUI when at least one indicator field is set. Rendered as a
+  // bottom-right page-1 float (see placement below).
+  let cui-indicator = if (
+    classification-level != none
+    and type(classification-level) == str
+    and classification-level.trim().starts-with("CUI")
+  ) {
+    // An indicator may arrive as content or as a `str`; `falsey` is the
+    // presence test that reads both shapes.
+    let lines = ()
+    if not falsey(cui-controlled-by) {
+      lines.push([Controlled By: #cui-controlled-by])
+    }
+    if not falsey(cui-category) {
+      lines.push([CUI Category: #cui-category])
+    }
+    if not falsey(cui-limited-dissemination) {
+      lines.push([LDC: #upper(cui-limited-dissemination)])
+    }
+    if not falsey(cui-poc) {
+      lines.push([POC: #cui-poc])
+    }
+    if lines.len() > 0 { lines.join(linebreak()) } else { none }
+  } else {
+    none
+  }
+
+  set par(leading: spacing.line, spacing: spacing.line, justify: false)
+  set block(above: spacing.line, below: 0em, spacing: 0em)
+  set text(font: body-font, size: font-size, fallback: true)
+  show raw: set text(font: DEFAULT_MONO_FONTS)
+
+  set page(
+    paper: "us-letter",
+    // AFH 33-337: 1-inch margins on the left, right and bottom, on every page,
+    // and on the top of every page but the first, whose text starts lower (the
+    // `v()` below the letterhead).
+    margin: (
+      left: spacing.margin,
+      right: spacing.margin,
+      top: spacing.margin,
+      bottom: spacing.margin,
+    ),
+    header: {
+      // AFH 33-337: the first page of a personal letter is never numbered.
+      // Succeeding pages are numbered from 2, flush with the right margin.
+      context if counter(page).get().first() > 1 {
+        place(
+          dy: +.5in,
+          block(
+            width: 100%,
+            align(right, text(12pt)[#counter(page).display()]),
+          ),
+        )
+      }
+
+      if classification-marking != none {
+        place(
+          top + center,
+          dy: 0.375in,
+          text(12pt, font: DEFAULT_BODY_FONTS, fill: classification-color)[#strong(classification-marking)],
+        )
+      }
+    },
+    footer: {
+      if classification-marking != none {
+        place(
+          bottom + center,
+          dy: -.375in,
+          text(12pt, font: DEFAULT_BODY_FONTS, fill: classification-color)[#strong(classification-marking)],
+        )
+      }
+
+      if not falsey(footer-tag-line) {
+        place(
+          bottom + center,
+          dy: -0.625in,
+          align(center)[
+            #text(fill: LETTERHEAD_COLOR, font: "Spectral SC", size: 15pt)[#footer-tag-line]
+          ],
+        )
+      }
+    },
+  )
+
+  // DoDM 5200.48 §3: CUI designation indicator block — page 1 only, bottom-right
+  // corner, dropped into the 0.5in page-edge band. Emitted as a bottom float so
+  // it (1) reserves flow space, raising page 1's effective bottom margin so body
+  // text never overlaps it, and (2) stays pinned to page 1 — as the first flow
+  // content it can never be bumped to page 2.
+  if cui-indicator != none {
+    context {
+      // The box shrink-wraps to its widest line; `set align(left)` keeps the
+      // text flush-left within it, overriding the `align(right)` the placement
+      // below imposes.
+      let indicator-box = box({
+        set text(font: DEFAULT_BODY_FONTS, size: 10pt)
+        set par(leading: 0.4em, spacing: 0pt)
+        set align(left)
+        cui-indicator
+      })
+      // Reserve only the part of the block inside the text area (`reserved`):
+      // float a box of that height, then `place` the full block inside it pushed
+      // down by `overhang` so the surplus overflows into the edge band. (A bare
+      // `box(height: reserved, indicator-box)` overflows *upward* into the body
+      // instead.) The inner `place` adds no size, so the box stays `reserved`
+      // tall and the block's bottom lands 0.5in from the page edge.
+      let overhang = spacing.margin - 0.5in
+      let reserved = measure(indicator-box).height - overhang
+      place(
+        bottom + right,
+        float: true,
+        // Slide the right edge into the page-edge band, 0.5in from the border;
+        // the inner place right-aligns the block to that edge.
+        dx: spacing.margin - 0.5in,
+        // Minimum gap to the body's last line; the actual gap is larger when the
+        // next paragraph can't fit above the block and breaks to the next page.
+        clearance: spacing.line,
+        box(height: reserved, place(bottom + right, dy: overhang, indicator-box)),
+      )
+    }
+  }
+
+  render-letterhead(
+    letterhead-title,
+    letterhead-caption,
+    letterhead-font,
+    letterhead-seal: letterhead-seal,
+    letterhead-seal-subtitle: letterhead-seal-subtitle,
+    letterhead-emblem: letterhead-emblem,
+    letterhead-emblem-height: letterhead-emblem-height,
+  )
+
+  // AFH 33-337: the date sits 1.75 inches from the top of the first page. The
+  // top margin is 1 inch, so the remainder is made up here.
+  v(1.75in - spacing.margin)
+
+  // Measure one line's stride once, under the typography just set, for the
+  // blank-line spacing every element below is laid out on.
+  context {
+    let one-line = measure(par(spacing: 0pt)[x]).height
+    LINE_STRIDE.update(measure(par(spacing: 0pt)[x#linebreak()x]).height - one-line)
+  }
+
+  render-date-section(actual-date)
+
+  // AFH 33-337: the sender's block on the second line below the date, the
+  // receiver's on the third line below the sender's last line. With no sender's
+  // block the receiver's takes the line the sender's would have started on.
+  let has-sender = not falsey(letter-from)
+  if has-sender {
+    blank-line()
+    join-lines(letter-from)
+  }
+  blank-lines(if has-sender { 2 } else { 1 })
+  join-lines(letter-for)
+
+  // AFH 33-337: the salutation sits on the second line below the receiver's
+  // address, and takes no punctuation after the receiver's last name. A blank
+  // one prints nothing and takes no line, so the body opens on the second line
+  // below the receiver's address.
+  if not falsey(salutation) {
+    blank-line()
+    [#salutation]
+  }
+
+  // The body opens on the second line below the salutation, which `mainmatter`
+  // supplies: the gap above its first paragraph is the same blank line it puts
+  // between any two.
+  it
+}

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

@@ -0,0 +1,35 @@
+// Public API of the USAF personal letter template, which typesets per AFH
+// 33-337 "The Tongue and Quill", "The Personal Letter".
+//
+// The three sections compose in document order: `frontmatter` and `mainmatter`
+// as show rules, `backmatter` as a function.
+//
+// `config.typ`, `utils.typ` and `primitives.typ` are `tonguetoquill-usaf-memo`
+// 5.0.0's, byte for byte, so the letterhead, signature block and closing
+// elements the two documents share are set by one implementation and a sync is
+// a copy. The other files are the letter's own.
+//
+// #import "@preview/tonguetoquill-usaf-letter:0.1.0": (
+//   backmatter, frontmatter, mainmatter,
+// )
+//
+// #show: frontmatter.with(
+//   letter-from: ("Colonel Jane A. Doe", "Commander", "123d Example Squadron",
+//                 "1 Example Way", "Placeholder AFB ST 12345-6789"),
+//   letter-for: ("Major John B. Smith", "Chief, Plans and Programs",
+//                "456th Example Group", "2 Sample Blvd", "Sample AFB ST 98765-4321"),
+//   salutation: "Dear Major Smith",
+// )
+// #show: mainmatter
+//
+// Body paragraphs.
+//
+// #backmatter(
+//   complimentary-close: "Sincerely",
+//   signature-block: ("FIRST M. LAST, Rank, USAF",),
+// )
+
+#import "frontmatter.typ": frontmatter
+#import "mainmatter.typ": mainmatter
+#import "backmatter.typ": backmatter
+#import "utils.typ": date-pattern

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

@@ -0,0 +1,140 @@
+// The personal letter's body: AFH 33-337 "For the body of the personal letter,
+// the paragraphs are indented 0.5 inches from the left margin but they are not
+// numbered."
+
+#import "config.typ": *
+#import "utils.typ": *
+#import "primitives.typ": render-memo-table
+
+// AFH 33-337: a personal letter's paragraphs are indented half an inch from the
+// left margin and carry no number or letter.
+#let paragraph-indent = 0.5in
+
+/// Splits content at the closing section: the part this styles as body
+/// paragraphs, and the part that reaches the page untouched.
+///
+/// Applied as a show rule, `mainmatter` is handed the closing section along
+/// with the body, and the body's first-line indent would then displace the
+/// complimentary close and the signature lines. `backmatter` labels its output
+/// to mark the boundary.
+///
+/// Everything from the marker on stays together, prose a caller wrote after the
+/// closing included.
+///
+/// A marker is found on `it` itself, on a direct child, or inside the `styled`
+/// element that a `set` or `show` rule after `#show: mainmatter` wraps the
+/// remainder in; both halves come back under those styles. A marker a caller
+/// nested in a container of their own — a `block`, a `grid` cell — is not
+/// found. A closing section built in a code block or a loop is not nested:
+/// joining content extends the sequence on the left in place, so its marker
+/// stays a direct child.
+///
+/// - it (content): Content handed to `mainmatter`
+/// -> array: the body content and the closing content
+#let split-closing(it) = {
+  if it.at("label", default: none) == <usaf-letter-closing> { return ([], it) }
+  // `styled` is not a name in scope; its two fields identify it.
+  if it.has("child") and it.has("styles") {
+    let (body, closing) = split-closing(it.child)
+    let restyle = part => (it.func())(part, it.styles)
+    return (restyle(body), restyle(closing))
+  }
+  if not it.has("children") { return (it, []) }
+  let children = it.children
+  let boundary = children.position(child => child.at("label", default: none) == <usaf-letter-closing>)
+  if boundary == none { return (it, []) }
+  // `sum` over `join`: an empty half is `none` from a join and `[]` from this.
+  (children.slice(0, boundary).sum(default: []), children.slice(boundary).sum(default: []))
+}
+
+// The body's blocks in order — its own paragraphs, and each list, table and
+// block quote whole — so the last can be found; and how deep in one of those
+// containers the current paragraph sits.
+#let BLOCKS = counter("usaf-letter-blocks")
+#let NESTED = state("usaf-letter-nested", 0)
+
+/// Whether a body's last block holds the signature to its page: a sticky block
+/// relocates whole rather than splitting, so one taller than a third of the
+/// text height is left to the break, which leaves its own tail above the
+/// signature.
+///
+/// - it (content): The last block
+/// -> bool
+#let keeps-signature(it) = {
+  let budget = (page.height - spacing.margin * 2) / 3
+  measure(it, width: page.width - spacing.margin * 2).height <= budget
+}
+
+/// Counts a container as one block of the body and the paragraphs inside it
+/// as none, and sets it a blank line off the paragraphs around it.
+///
+/// - it (content): The container
+/// -> content
+#let container(it) = context {
+  if NESTED.get() > 0 { return it }
+  BLOCKS.step()
+  NESTED.update(n => n + 1)
+  context {
+    let last = BLOCKS.get() == BLOCKS.final()
+    block(above: par.spacing, sticky: last and keeps-signature(it), it)
+  }
+  NESTED.update(n => n - 1)
+}
+
+/// Show rule for the personal letter's body.
+///
+/// - it (content): Body content
+/// -> content
+#let mainmatter(it) = {
+  let (body, closing) = split-closing(it)
+  context {
+    // `par.leading` and `par.spacing` are both half an em, so a paragraph break
+    // would otherwise land on the page as an ordinary line break. A blank line
+    // is what separates one letter paragraph from the next.
+    set par(
+      first-line-indent: (amount: paragraph-indent, all: true),
+      spacing: spacing.line + line-stride(),
+    )
+    // The indent belongs to the letter's own paragraphs. Inside a list, a
+    // quote, or a table cell, a line already sits where its container put it.
+    show list: it => {
+      set par(first-line-indent: 0pt)
+      container(it)
+    }
+    show enum: it => {
+      set par(first-line-indent: 0pt)
+      container(it)
+    }
+    show table: it => {
+      set par(first-line-indent: 0pt)
+      container(render-memo-table(it))
+    }
+    // A block quote is the body's unindented block: the author's lines as
+    // written, flush with the margin, which is what lets a letter carry a
+    // roster of names or an address without the paragraph indent claiming its
+    // first line.
+    show quote.where(block: true): it => {
+      set par(first-line-indent: 0pt)
+      container(it.body)
+    }
+    show raw.where(block: true): container
+    // AFH 33-337: "Do not place the signature element on a continuation page
+    // by itself." The signature block has no keep-with-previous of its own —
+    // Typst has no such property — so the anchor comes from this side: the
+    // body's last block, a paragraph or a container, is set sticky, carried
+    // onto the next page along with the signature instead of breaking away
+    // from it.
+    show par: p => context {
+      if NESTED.get() > 0 { return p }
+      BLOCKS.step()
+      context {
+        if BLOCKS.get() != BLOCKS.final() { return p }
+        // `above` stands in for the paragraph spacing a bare paragraph would
+        // have taken from the one before it.
+        block(sticky: keeps-signature(p), above: par.spacing, p)
+      }
+    }
+    body
+  }
+  closing
+}