@tonguetoquill/collection 0.1.0

package/quills/usaf_memo/0.2.0/packages/tonguetoquill-usaf-memo/src/body.typ

@@ -0,0 +1,325 @@
+// body.typ: Paragraph body rendering for USAF memorandum sections
+//
+// This module implements the visual rendering of AFH 33-337 compliant
+// paragraph bodies with proper numbering, nesting, and formatting.
+
+#import "config.typ": *
+#import "utils.typ": *
+#import "primitives.typ": render-memo-table
+
+// =============================================================================
+// PARAGRAPH NUMBERING UTILITIES
+// =============================================================================
+
+/// Gets the numbering format for a specific paragraph level.
+///
+/// AFH 33-337 "The Text of the Official Memorandum" §2: "Number and letter each
+/// paragraph and subparagraph" with hierarchical numbering implied by examples.
+/// Standard military format follows the pattern: 1., a., (1), (a), etc.
+///
+/// Returns the appropriate numbering format for AFH 33-337 compliant
+/// hierarchical paragraph numbering:
+/// - Level 0: "1." (1., 2., 3., etc.)
+/// - Level 1: "a." (a., b., c., etc.)
+/// - Level 2: "(1)" ((1), (2), (3), etc.)
+/// - Level 3: "(a)" ((a), (b), (c), etc.)
+/// - Level 4+: Underlined format for deeper nesting
+///
+/// - level (int): Paragraph nesting level (0-based)
+/// -> str | function
+#let get-paragraph-numbering-format(level) = {
+  paragraph-config.numbering-formats.at(level, default: "i.")
+}
+
+/// Generates paragraph number for a given level with proper formatting.
+///
+/// Creates properly formatted paragraph numbers for the hierarchical numbering
+/// system using Typst's native counter display capabilities.
+///
+/// - level (int): Paragraph nesting level (0-based)
+/// - counter-value (none | int): Optional explicit counter value to use (for measuring widths)
+/// - increment (bool): Whether to increment the counter after display
+/// -> content
+#let generate-paragraph-number(level, counter-value: none) = {
+  let paragraph-counter = counter(paragraph-config.counter-prefix + str(level))
+  let numbering-format = get-paragraph-numbering-format(level)
+
+  if counter-value != none {
+    // For measuring widths: create temporary counter at specific value
+    assert(counter-value >= 0, message: "Counter value of `" + str(counter-value) + "` cannot be less than 0")
+    let temp-counter = counter("temp-counter")
+    temp-counter.update(counter-value)
+    temp-counter.display(numbering-format)
+  } else {
+    // Standard case: display and increment
+    let result = paragraph-counter.display(numbering-format)
+    paragraph-counter.step()
+    result
+  }
+}
+
+/// Calculates proper indentation width for a paragraph level.
+///
+/// AFH 33-337 "The Text of the Official Memorandum" §4-5:
+/// - "The first paragraph is never indented; it is numbered and flush left"
+/// - "Indent the first line of sub-paragraphs to align the number or letter with
+///    the first character of its parent level paragraph"
+///
+/// Computes the exact indentation needed for hierarchical paragraph alignment
+/// by measuring the cumulative width of all ancestor paragraph numbers and their
+/// spacing. Uses direct iteration instead of recursion for better performance.
+///
+/// Per AFH 33-337: Sub-paragraph text aligns with first character of parent text,
+/// which means indentation = sum of all ancestor number widths + spacing.
+///
+/// - level (int): Paragraph nesting level (0-based)
+/// -> length
+#let calculate-paragraph-indent(level) = {
+  assert(level >= 0)
+  if level == 0 {
+    return 0pt
+  }
+
+  // Accumulate widths of all ancestor numbers iteratively
+  let total-indent = 0pt
+  for ancestor-level in range(level) {
+    let ancestor-counter-value = counter(paragraph-config.counter-prefix + str(ancestor-level)).get().at(0)
+    let ancestor-number = generate-paragraph-number(ancestor-level, counter-value: ancestor-counter-value)
+    // Measure number + spacing buffer
+    let width = measure([#ancestor-number#"  "]).width
+    total-indent += width
+  }
+
+  total-indent
+}
+
+/// Global state for tracking current paragraph level.
+/// Used internally by the paragraph numbering system to maintain proper nesting.
+/// -> state
+#let PAR_LEVEL_STATE = state("PAR_LEVEL", 0)
+
+
+/// Sets the current paragraph level state.
+///
+/// Internal function used by the paragraph numbering system to track
+/// the current nesting level for proper indentation and numbering.
+///
+/// - level (int): Paragraph nesting level to set
+/// -> content
+#let SET_PAR_LEVEL(level) = {
+  context {
+    PAR_LEVEL_STATE.update(level)
+    if level == 0 {
+      counter(paragraph-config.counter-prefix + str(level + 1)).update(1)
+    }
+  }
+}
+
+/// Creates a formatted paragraph with automatic numbering and indentation.
+///
+/// Generates a properly formatted paragraph with AFH 33-337 compliant numbering,
+/// indentation, and spacing. Automatically manages counter incrementation and
+/// nested paragraph state. Used internally by the body rendering system.
+///
+/// Features:
+/// - Automatic paragraph number generation and formatting
+/// - Proper indentation based on nesting level via direct width measurement
+/// - Counter management for hierarchical numbering
+/// - Widow/orphan prevention settings
+///
+/// - content (content): Paragraph content to format
+/// -> content
+#let memo-par(content) = context {
+  let level = PAR_LEVEL_STATE.get()
+  let paragraph-number = generate-paragraph-number(level)
+  // Reset child level counter
+  counter(paragraph-config.counter-prefix + str(level + 1)).update(1)
+  let indent-width = calculate-paragraph-indent(level)
+
+
+  // Number + two spaces + content, with left padding for nesting
+  //pad(left: indent-width, paragraph-number + "  " + content)
+  [#h(indent-width)#paragraph-number#"  "#content]
+}
+
+// =============================================================================
+// PARAGRAPH BODY RENDERING
+// =============================================================================
+// AFH 33-337 "The Text of the Official Memorandum" §1-12 specifies:
+// - Single-space text, double-space between paragraphs
+// - Number and letter each paragraph and subparagraph
+// - "A single paragraph is not numbered" (§2)
+// - First paragraph flush left, never indented
+// - Indent sub-paragraphs to align with first character of parent paragraph text
+#let render-body(content, auto-numbering: true) = {
+  let PAR_BUFFER = state("PAR_BUFFER")
+  PAR_BUFFER.update(())
+  let NEST_DOWN = counter("NEST_DOWN")
+  NEST_DOWN.update(0)
+  let NEST_UP = counter("NEST_UP")
+  NEST_UP.update(0)
+  let IS_HEADING = state("IS_HEADING")
+  IS_HEADING.update(false)
+  // Initialize level counters to 1 (Typst counters default to 0)
+  for i in range(0, 5) {
+    counter(paragraph-config.counter-prefix + "0").update(1)
+  }
+
+  // The first pass parses paragraphs, list items, etc. into standardized arrays
+  let first_pass = {
+    // Collect pars with nesting level
+    show par: p => context {
+      let nest_level = NEST_DOWN.get().at(0) - NEST_UP.get().at(0)
+      let is_heading = IS_HEADING.get()
+
+      PAR_BUFFER.update(pars => {
+        // Item tuple: (content, nest_level, is_heading, is_table)
+        pars.push((text([#p.body]), nest_level, is_heading, false))
+        pars
+      })
+      p
+    }
+    // Collect tables — captured as-is without paragraph numbering
+    show table: t => context {
+      PAR_BUFFER.update(pars => {
+        pars.push((t, -1, false, true))
+        pars
+      })
+      t
+    }
+    {
+      show heading: h => {
+        IS_HEADING.update(true)
+        [#parbreak()#h.body#parbreak()]
+        IS_HEADING.update(false)
+      }
+
+      // Convert list/enum items to pars
+      // Note: No context wrapper here - state updates don't need it and cause
+      // layout convergence issues with many list items
+      show enum.item: it => {
+        NEST_DOWN.step()
+        [#parbreak()#it.body#parbreak()]
+        NEST_UP.step()
+      }
+      show list.item: it => {
+        NEST_DOWN.step()
+        [#parbreak()#it.body#parbreak()]
+        NEST_UP.step()
+      }
+
+      {
+        // Typst bug bandaid:
+        // `show par` will not collect wrappers unless there is content outside
+        // Add zero width space to always have content outside of wrapper
+        show strong: it => {
+          [#it#sym.zws]
+        }
+        show emph: it => {
+          [#it#sym.zws]
+        }
+        show underline: it => {
+          [#it#sym.zws]
+        }
+        show raw: it => {
+          [#it#sym.zws]
+        }
+        [#content#parbreak()]
+      }
+    }
+  }
+  // Use place() to prevent hidden content from affecting layout flow
+  place(hide(first_pass))
+
+  //Second pass: consume par buffer
+  //
+  // PAR_BUFFER item tuple layout:
+  //   item.at(0) — content     : the paragraph body or table element
+  //   item.at(1) — nest_level  : nesting depth (−1 for tables)
+  //   item.at(2) — is_heading  : bool, true if item is a heading paragraph
+  //   item.at(3) — is_table    : bool, true if item is a table element
+  let ITEM_IS_TABLE = 3
+  context {
+    let heading_buffer = none
+    // Tables do not count as paragraphs for AFH 33-337 §2 numbering purposes
+    let par_count = PAR_BUFFER.get().filter(item => not item.at(ITEM_IS_TABLE, default: false)).len()
+    let items = PAR_BUFFER.get()
+    let total_count = items.len()
+    let i = 0
+    for item in items {
+      i += 1
+      let is_table = item.at(ITEM_IS_TABLE, default: false)
+
+      // Render tables inline without paragraph numbering
+      if is_table {
+        blank-line()
+        render-memo-table(item.at(0))
+        continue
+      }
+
+      let par_content = item.at(0)
+      let nest_level = item.at(1)
+      let is_heading = item.at(2)
+
+      // Prepend heading as bolded sentence
+      if heading_buffer != none {
+        par_content = [#strong[#heading_buffer.] #par_content]
+      }
+      if is_heading {
+        heading_buffer = par_content
+        continue
+      }
+
+      let final_par = {
+        if auto-numbering {
+          if par_count > 1 {
+            // Apply paragraph numbering per AFH 33-337 §2
+            SET_PAR_LEVEL(nest_level)
+            let paragraph = memo-par(par_content)
+            paragraph
+          } else {
+            // AFH 33-337 §2: "A single paragraph is not numbered"
+            // Return body content wrapped in block (like numbered case, but without numbering)
+            par_content
+          }
+        } else {
+          // Unnumbered mode: only explicitly nested items (enum/list) get numbered
+          if nest_level > 0 {
+            SET_PAR_LEVEL(nest_level - 1)
+            let paragraph = memo-par(par_content)
+            paragraph
+          } else {
+            // Base-level paragraphs are flush left with no numbering
+            par_content
+          }
+        }
+      }
+
+      //If this is the final paragraph, apply AFH 33-337 §11 rule:
+      // "Avoid dividing a paragraph of less than four lines between two pages"
+      blank-line()
+      if i == total_count {
+        let available_width = page.width - spacing.margin * 2
+
+        // Use configured spacing for line height calculation
+        let line_height = measure(line(length: spacing.line + spacing.line-height)).width
+        // Calculate last par's height
+        let par_height = measure(final_par, width: available_width).height
+
+        let estimated_lines = calc.ceil(par_height / line_height)
+
+        if estimated_lines < 4 {
+          // Short paragraph (< 4 lines): make sticky to keep with signature
+          block(sticky: true)[#final_par]
+        } else {
+          // Longer paragraph (≥ 4 lines): use default breaking behavior
+          block(breakable: true)[#final_par]
+        }
+      } else {
+        final_par
+      }
+    }
+  }
+}
+
+

package/quills/usaf_memo/0.2.0/packages/tonguetoquill-usaf-memo/src/config.typ

@@ -0,0 +1,63 @@
+// config.typ: Configuration constants and defaults for USAF memorandum template
+//
+// This module defines core configuration values that implement AFH 33-337 Chapter 14
+// formatting requirements for official USAF memorandums.
+
+// =============================================================================
+// SPACING CONSTANTS
+// =============================================================================
+// AFH 33-337 specifies precise spacing requirements throughout Chapter 14
+
+#let spacing = (
+  line: .5em, // Internal line spacing for readability
+  line-height: .7em, // Base line height for spacing calculations
+  tab: 0.5in, // Tab stop for multi-column recipient alignment
+  margin: 1in, // AFH 33-337 §4: "Use 1-inch margins on the left, right and bottom"
+)
+
+// =============================================================================
+// TYPOGRAPHY DEFAULTS
+// =============================================================================
+// AFH 33-337 §5: "Use 12 point Times New Roman font for text"
+
+#let DEFAULT_LETTERHEAD_FONTS = ("Copperplate CC",)
+#let DEFAULT_BODY_FONTS = ("times new roman", "NimbusRomNo9L")  // AFH 33-337 §5: Times New Roman required
+#let LETTERHEAD_COLOR = rgb("#000099")  // Standard USAF blue for letterhead
+
+// =============================================================================
+// PARAGRAPH CONFIGURATION
+// =============================================================================
+// AFH 33-337 "The Text of the Official Memorandum" §2:
+// "Number and letter each paragraph and subparagraph"
+// Hierarchical numbering: 1., a., (1), (a), etc.
+
+#let paragraph-config = (
+  counter-prefix: "par-counter-",
+  // AFH 33-337 §2: Hierarchical paragraph numbering format
+  // Level 0: 1., 2., 3. | Level 1: a., b., c. | Level 2: (1), (2), (3) | Level 3: (a), (b), (c)
+  numbering-formats: ("1.", "a.", "(1)", "(a)", n => underline(str(n)), n => underline(str(n))),
+)
+
+// =============================================================================
+// COUNTERS
+// =============================================================================
+
+#let counters = (
+  indorsement: counter("indorsement"),
+)
+
+// =============================================================================
+// CLASSIFICATION COLORS
+// =============================================================================
+// AFH 33-337 §3: "Follow AFI 31-401, Information Security Program Management,
+// applicable executive orders and DoD guidance for the necessary markings on
+// classified correspondence."
+// Color values follow DoD standard classification marking colors
+// Source: https://security.stackexchange.com/questions/161829
+
+#let CLASSIFICATION_COLORS = (
+  "UNCLASSIFIED": rgb(0, 122, 51), // Forest green (#007A33)
+  "CONFIDENTIAL": rgb(0, 51, 160), // Deep blue (#0033A0)
+  "SECRET": rgb(200, 16, 46), // Crimson red (#C8102E)
+  "TOP SECRET": rgb(255, 103, 31), // Burnt orange (#FF671F)
+)

package/quills/usaf_memo/0.2.0/packages/tonguetoquill-usaf-memo/src/frontmatter.typ

@@ -0,0 +1,114 @@
+// frontmatter.typ: Frontmatter show rule for USAF memorandum
+//
+// This module implements the frontmatter (heading section) of a USAF memorandum
+// per AFH 33-337 Chapter 14 "The Heading Section". It handles:
+// - Page setup with proper margins
+// - Letterhead rendering
+// - Date, MEMORANDUM FOR, FROM, SUBJECT, and References placement
+// - Classification markings in headers/footers
+
+#import "primitives.typ": *
+
+#let frontmatter(
+  subject: none,
+  memo_for: none,
+  memo_from: none,
+  date: none,
+  references: none,
+  letterhead_title: "DEPARTMENT OF THE AIR FORCE",
+  letterhead_caption: "[YOUR SQUADRON/UNIT NAME]",
+  letterhead_seal: none,
+  letterhead_font: DEFAULT_LETTERHEAD_FONTS,
+  body_font: DEFAULT_BODY_FONTS,
+  font_size: 12pt,
+  memo_for_cols: 3,
+  classification_level: none,
+  footer_tag_line: none,
+  auto_numbering: true,
+  it,
+) = {
+  assert(subject != none, message: "subject is required")
+  assert(memo_for != none, message: "memo_for is required")
+  assert(memo_from != none, message: "memo_from is required")
+
+  let actual_date = if date == none { datetime.today() } else { date }
+  let classification_color = get-classification-level-color(classification_level)
+
+  // Document-wide typography settings (inlined from configure())
+  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)
+
+  set page(
+    paper: "us-letter",
+    // AFH 33-337 §4: "Use 1-inch margins on the left, right and bottom"
+    margin: (
+      left: spacing.margin,
+      right: spacing.margin,
+      top: spacing.margin,
+      bottom: spacing.margin,
+    ),
+    header: {
+      // AFH 33-337 "Page numbering" §12: "The first page of a memorandum is never numbered.
+      // Number the succeeding pages starting with page 2. Place page numbers 0.5-inch from
+      // the top of the page, 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_level != none {
+        place(
+          top + center,
+          dy: 0.375in,
+          text(12pt, font: DEFAULT_BODY_FONTS, fill: classification_color)[#strong(classification_level)],
+        )
+      }
+    },
+    footer: {
+      place(
+        bottom + center,
+        dy: -.375in,
+        text(12pt, font: DEFAULT_BODY_FONTS, fill: classification_color)[#strong(classification_level)],
+      )
+
+      if not falsey(footer_tag_line) {
+        place(
+          bottom + center,
+          dy: -0.625in,
+          align(center)[
+            #text(fill: LETTERHEAD_COLOR, font: "cinzel", size: 15pt)[#footer_tag_line]
+          ],
+        )
+      }
+    },
+  )
+
+  render-letterhead(letterhead_title, letterhead_caption, letterhead_seal, letterhead_font)
+
+  // AFH 33-337 "Date": "Place the date 1 inch from the right edge, 1.75 inches from the top"
+  // Since we have a 1-inch top margin, we need (1.75in - margin) vertical space
+  v(1.75in - spacing.margin)
+
+  render-date-section(actual_date)
+  render-for-section(memo_for, memo_for_cols)
+  render-from-section(memo_from)
+  render-subject-section(subject)
+  render-references-section(references)
+
+  metadata((
+    subject: subject,
+    original_date: actual_date,
+    original_from: first-or-value(memo_from),
+    body_font: body_font,
+    font_size: font_size,
+    auto_numbering: auto_numbering,
+  ))
+
+  it
+}

package/quills/usaf_memo/0.2.0/packages/tonguetoquill-usaf-memo/src/indorsement.typ

@@ -0,0 +1,118 @@
+// indorsement.typ: Indorsement rendering for USAF memorandum
+//
+// This module implements indorsements (endorsements) per AFH 33-337 Chapter 14.
+// Indorsements are used to forward memorandums with additional commentary.
+// They follow the format: "1st Ind", "2d Ind", "3d Ind", etc.
+// Each indorsement includes its own body text and signature block.
+//
+// Note: When using #show: indorsement.with(...), the indorsement wraps the
+// entire remainder of the document. This works for a single indorsement at
+// the end of a file. For multiple indorsements, use the function call syntax:
+// #indorsement(...)[Body text...]
+
+#import "primitives.typ": *
+#import "body.typ": *
+
+#let indorsement(
+  from: none,
+  to: none,
+  signature_block: none,
+  signature_blank_lines: 4,
+  attachments: none,
+  cc: none,
+  date: none,
+  // Format of indorsement: "standard" (same page), "informal" (no header), or "separate_page" (starts on new page)
+  format: "standard",
+  // Show the APPROVED / DISAPPROVED action line. Default: false.
+  show_action: false,
+  // Approval decision: none (no decision), "approved", or "disapproved".
+  action: none,
+  content,
+) = {
+  // Validate format parameter
+  assert(
+    format in ("standard", "informal", "separate_page"),
+    message: "format must be \"standard\", \"informal\", or \"separate_page\"",
+  )
+
+  if format != "informal" {
+    assert(from != none, message: "from is required")
+    assert(to != none, message: "to is required")
+  }
+
+
+  let actual_date = if date == none { datetime.today() } else { date }
+  let ind_from = first-or-value(from)
+  let ind_for = to
+
+  if format != "informal" {
+    // Step the counter BEFORE the context block to avoid read-then-update loop
+    counters.indorsement.step()
+
+    context {
+      let config = query(metadata).last().value
+      let original_subject = config.subject
+      let original_date = config.original_date
+      let original_from = config.original_from
+
+      // Read the counter value (already stepped above)
+      let indorsement_number = counters.indorsement.get().at(0, default: 1)
+      let indorsement_label = format-indorsement-number(indorsement_number)
+
+      if format == "separate_page" {
+        pagebreak()
+        [#indorsement_label to #original_from, #display-date(original_date), #original_subject]
+
+        blank-line()
+        grid(
+          columns: (auto, 1fr),
+          ind_from, align(right)[#display-date(actual_date)],
+        )
+
+        blank-line()
+        grid(
+          columns: (auto, auto, 1fr),
+          "MEMORANDUM FOR", "  ", ind_for,
+        )
+      } else {
+        blank-line()
+        grid(
+          columns: (auto, 1fr),
+          [#indorsement_label, #ind_from], align(right)[#display-date(actual_date)],
+        )
+
+        blank-line()
+        grid(
+          columns: (auto, auto, 1fr),
+          "MEMORANDUM FOR", "  ", ind_for,
+        )
+      }
+    }
+    blank-line()
+  }
+
+  // Show action line if explicitly requested or if an action decision is set
+  if show_action or action != none {
+    render-action-line(action)
+  }
+
+  render-body(content)
+
+  render-signature-block(signature_block, signature-blank-lines: signature_blank_lines)
+
+  if not falsey(attachments) {
+    calculate-backmatter-spacing(true)
+    let attachment-count = attachments.len()
+    let section-label = if attachment-count == 1 { "Attachment:" } else { str(attachment-count) + " Attachments:" }
+    let continuation-label = (
+      (if attachment-count == 1 { "Attachment" } else { str(attachment-count) + " Attachments" })
+        + " (listed on next page):"
+    )
+    render-backmatter-section(attachments, section-label, numbering-style: "1.", continuation-label: continuation-label)
+  }
+
+  if not falsey(cc) {
+    calculate-backmatter-spacing(falsey(attachments))
+    render-backmatter-section(cc, "cc:")
+  }
+}

package/quills/usaf_memo/0.2.0/packages/tonguetoquill-usaf-memo/src/lib.typ

@@ -0,0 +1,55 @@
+// lib.typ: Public API for USAF memorandum template
+//
+// This module provides a composable API for creating United States Air Force
+// memorandums that comply with AFH 33-337 "The Tongue and Quill" Chapter 14
+// "The Official Memorandum" formatting standards.
+//
+// AFH 33-337 Chapter 14 specifies exact requirements for:
+// - Margins: 1 inch on all sides (§4)
+// - Font: 12pt Times New Roman (§5)
+// - Date placement: 1.75 inches from top, 1 inch from right (Date section)
+// - Heading elements: MEMORANDUM FOR, FROM, SUBJECT with 2-line spacing
+// - Paragraph numbering: Hierarchical 1., a., (1), (a) format (§2)
+// - Signature block: 4.5 inches from left, never orphaned (Signature Block section)
+// - Backmatter: Attachments, cc:, distribution with specific spacing
+//
+// Key features:
+// - Composable show rules for frontmatter and mainmatter
+// - Function-based backmatter and indorsements for correct ordering
+// - No global state - configuration flows through metadata
+// - Reusable primitives for common rendering tasks
+// - AFH 33-337 compliant formatting throughout
+//
+// Basic usage:
+//
+// #import "@preview/tonguetoquill-usaf-memo:0.2.0": frontmatter, mainmatter, backmatter, indorsement
+//
+// #show: frontmatter.with(
+//   subject: "Your Subject Here",
+//   memo_for: ("OFFICE/SYMBOL",),
+//   memo_from: ("YOUR/SYMBOL",),
+// )
+//
+// #show: mainmatter
+//
+// Your memo body content here.
+// (Paragraphs are automatically numbered per AFH 33-337)
+//
+// #backmatter(
+//   signature_block: ("NAME, Rank, USAF", "Title"),
+//   attachments: (...),
+//   cc: (...),
+// )
+//
+// #indorsement(
+//   from: "ORG/SYMBOL",
+//   to: "RECIPIENT/SYMBOL",
+//   signature_block: ("NAME, Rank, USAF", "Title"),
+// )[
+//   Indorsement content here.
+// ]
+
+#import "frontmatter.typ": frontmatter
+#import "mainmatter.typ": mainmatter
+#import "backmatter.typ": backmatter
+#import "indorsement.typ": indorsement