@tonguetoquill/collection 0.1.0

package/quills/usaf_memo/0.1.0/packages/tonguetoquill-usaf-memo/src/mainmatter.typ

@@ -0,0 +1,32 @@
+// mainmatter.typ: Mainmatter show rule for USAF memorandum
+//
+// This module implements the mainmatter (body text) of a USAF memorandum per
+// AFH 33-337 Chapter 14 "The Text of the Official Memorandum" (§1-12).
+
+#import "primitives.typ": *
+#import "body.typ": *
+
+/// Mainmatter show rule for USAF memorandum body content.
+///
+/// AFH 33-337 "The Text of the Official Memorandum" §1-12 requirements:
+/// - Begin text on second line below subject/references
+/// - Single-space text, double-space between paragraphs
+/// - Number and letter each paragraph/subparagraph
+/// - "A single paragraph is not numbered" (§2)
+/// - First paragraph flush left, never indented
+///
+/// Applies AFH 33-337 paragraph numbering and formatting to the main body
+/// of the memorandum. Automatically detects single vs. multiple paragraphs
+/// to comply with AFH 33-337 numbering requirements.
+///
+/// When auto_numbering is false (set in frontmatter), base-level paragraphs
+/// render flush left without numbering. Only explicitly numbered or bulleted
+/// items enter the numbering hierarchy.
+///
+/// - content (content): The body content to render
+/// -> content
+#let mainmatter(it) = context {
+  let config = query(metadata).last().value
+  let auto-numbering = config.at("auto_numbering", default: true)
+  render-body(it, auto-numbering: auto-numbering)
+}

package/quills/usaf_memo/0.1.0/packages/tonguetoquill-usaf-memo/src/primitives.typ

@@ -0,0 +1,272 @@
+// primitives.typ: Reusable rendering primitives for USAF memorandum sections
+//
+// This module implements the visual rendering functions that produce AFH 33-337
+// compliant formatting for all sections of a USAF memorandum. Each function
+// corresponds to specific placement and formatting requirements from Chapter 14.
+
+#import "config.typ": *
+#import "utils.typ": *
+
+// =============================================================================
+// LETTERHEAD RENDERING
+// =============================================================================
+// AFH 33-337 §1: "Use printed letterhead, computer-generated letterhead, or plain bond paper"
+// Letterhead placement is not explicitly specified in AFH 33-337, but follows
+// standard USAF memo formatting conventions
+
+#let render-letterhead(title, caption, letterhead-seal, font) = {
+  font = ensure-array(font)
+  caption = ensure-string(caption)
+
+  place(
+    dy: 0.625in - spacing.margin,
+    box(
+      width: 100%,
+      fill: none,
+      stroke: none,
+      [
+        #place(
+          center + top,
+          align(center)[
+            #set text(12pt, font: font, fill: LETTERHEAD_COLOR)
+            #title\
+            #text(10.5pt)[#caption]
+          ],
+        )
+      ],
+    ),
+  )
+
+  if letterhead-seal != none {
+    place(
+      left + top,
+      dx: -0.5in,
+      dy: -.5in,
+      block[
+        #fit-box(width: 2in, height: 1in)[#letterhead-seal]
+      ],
+    )
+  }
+}
+
+// =============================================================================
+// HEADER SECTIONS
+// =============================================================================
+// AFH 33-337 "The Heading Section" specifies exact placement and format for:
+// - Date: 1 inch from right edge, 1.75 inches from top
+// - MEMORANDUM FOR: Second line below date
+// - FROM: Second line below MEMORANDUM FOR
+// - SUBJECT: Second line below FROM
+
+// AFH 33-337 "Date": "Place the date 1 inch from the right edge, 1.75 inches from the top"
+#let render-date-section(date) = {
+  align(right)[#display-date(date)]
+}
+
+// AFH 33-337 "MEMORANDUM FOR": "Place 'MEMORANDUM FOR' on the second line below the date"
+#let render-for-section(recipients, cols) = {
+  blank-line()
+  grid(
+    columns: (auto, auto, 1fr),
+    "MEMORANDUM FOR",
+    "  ",
+    align(left)[
+      #if type(recipients) == array {
+        create-auto-grid(recipients, column-gutter: spacing.tab, cols: cols)
+      } else {
+        recipients
+      }
+    ],
+  )
+}
+
+// AFH 33-337 "FROM:": "Place 'FROM:' in uppercase, flush with the left margin,
+// on the second line below the last line of the MEMORANDUM FOR element"
+#let render-from-section(from-info) = {
+  blank-line()
+  from-info = ensure-string(from-info)
+
+  grid(
+    columns: (auto, auto, 1fr),
+    "FROM:", "  ", align(left)[#from-info],
+  )
+}
+
+// AFH 33-337 "SUBJECT:": "In all uppercase letters place 'SUBJECT:', flush with the
+// left margin, on the second line below the last line of the FROM element"
+#let render-subject-section(subject-text) = {
+  blank-line()
+  grid(
+    columns: (auto, auto, 1fr),
+    "SUBJECT:", "  ", [#subject-text],
+  )
+}
+
+#let render-references-section(references) = {
+  if not falsey(references) {
+    blank-line()
+    grid(
+      columns: (auto, auto, 1fr),
+      "References:", "  ", enum(..references, numbering: "(a)"),
+    )
+  }
+}
+
+// =============================================================================
+// SIGNATURE BLOCK
+// =============================================================================
+// AFH 33-337 "Signature Block": "Start the signature block on the fifth line below
+// the last line of text and 4.5 inches from the left edge of the page"
+// AFH 33-337 "Do not place the signature element on a continuation page by itself"
+
+#let render-signature-block(signature-lines, signature-blank-lines: 4) = {
+  signature-lines = ensure-array(signature-lines)
+  // AFH 33-337: "The signature block is never on a page by itself"
+  // Note: Perfect enforcement isn't feasible without over-engineering
+  // We use weak: false spacing and breakable: false to discourage orphaning
+  // AFH 33-337: "fifth line below" = 4 blank lines between text and signature block
+  blank-lines(signature-blank-lines, weak: false)
+  block(breakable: false)[
+    #align(left)[
+      // AFH 33-337: "4.5 inches from the left edge of the page"
+      // We use (4.5in - margin) because Typst's pad() is relative to the text area, not page edge
+      #pad(left: 4.5in - spacing.margin)[
+        #text(hyphenate: false)[
+          #for line in signature-lines {
+            par(hanging-indent: 4 * 0.5em, line)
+          }
+        ]
+      ]
+    ]
+  ]
+}
+
+// =============================================================================
+// ACTION LINE RENDERING
+// =============================================================================
+// Renders the APPROVED / DISAPPROVED action line for indorsement memos.
+// action: none = both plain (no decision yet), "approved" = bold APPROVED /
+// strike DISAPPROVED, "disapproved" = strike APPROVED / bold DISAPPROVED.
+// Visibility is controlled by the caller (show_action / action != none).
+
+#let render-action-line(action) = {
+  assert(
+    action in (none, "approved", "disapproved"),
+    message: "action must be none, \"approved\", or \"disapproved\"",
+  )
+  blank-line()
+  let approved-text = if action == "approved" { strong[APPROVED] } else if action == "disapproved" { strike[APPROVED] } else { [APPROVED] }
+  let disapproved-text = if action == "disapproved" { strong[DISAPPROVED] } else if action == "approved" { strike[DISAPPROVED] } else { [DISAPPROVED] }
+  [#approved-text / #disapproved-text]
+}
+
+// =============================================================================
+// TABLE RENDERING
+// =============================================================================
+// AFH 33-337 does not specify table formatting, so we follow the general
+// aesthetic principles of the standard: plain black borders, no decorative
+// fills, and the body font inherited throughout.
+
+/// Renders a table with USAF memorandum–consistent formatting.
+///
+/// Applies simple 0.5pt black cell borders and standard padding to any
+/// Typst `table` element, keeping the visual style clean and formal.
+/// Font and size are inherited from the surrounding body text.
+///
+/// - it (content): The table element to style and render
+/// -> content
+#let render-memo-table(it) = {
+  set table(
+    stroke: 0.5pt + black,
+    inset: (x: 0.5em, y: 0.4em),
+  )
+  it
+}
+
+// =============================================================================
+// BACKMATTER SECTIONS
+// =============================================================================
+// AFH 33-337 "Attachment or Attachments": "Place 'Attachment:' (for a single attachment)
+// or '# Attachments:' (for two or more attachments) at the left margin, on the third
+// line below the signature element"
+// AFH 33-337 "Courtesy Copy Element": "place 'cc:' flush with the left margin, on the
+// second line below the attachment element"
+
+#let render-backmatter-section(
+  content,
+  section-label,
+  numbering-style: none,
+  continuation-label: none,
+) = {
+  let formatted-content = {
+    // Use text() wrapper to prevent section label from being treated as a paragraph
+    text()[#section-label]
+    linebreak()
+    if numbering-style != none {
+      let items = ensure-array(content)
+      enum(..items, numbering: numbering-style)
+    } else {
+      ensure-string(content)
+    }
+  }
+
+  context {
+    let available-space = page.height - here().position().y - 1in
+    if measure(formatted-content).height > available-space {
+      let continuation-text = if continuation-label != none {
+        text()[#continuation-label]
+      } else {
+        text()[#section-label + " (listed on next page):"]
+      }
+      continuation-text
+      pagebreak()
+    }
+    formatted-content
+  }
+}
+
+#let calculate-backmatter-spacing(is-first-section) = {
+  context {
+    let line_count = if is-first-section { 2 } else { 1 }
+    blank-lines(line_count)
+  }
+}
+
+#let render-backmatter-sections(
+  attachments: none,
+  cc: none,
+  distribution: none,
+  leading-pagebreak: false,
+) = {
+  let has-backmatter = (
+    (attachments != none and attachments.len() > 0)
+      or (cc != none and cc.len() > 0)
+      or (distribution != none and distribution.len() > 0)
+  )
+
+  if leading-pagebreak and has-backmatter {
+    pagebreak(weak: true)
+  }
+
+  if attachments != none and attachments.len() > 0 {
+    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 cc != none and cc.len() > 0 {
+    calculate-backmatter-spacing(attachments == none or attachments.len() == 0)
+    render-backmatter-section(cc, "cc:")
+  }
+
+  if distribution != none and distribution.len() > 0 {
+    calculate-backmatter-spacing((attachments == none or attachments.len() == 0) and (cc == none or cc.len() == 0))
+    render-backmatter-section(distribution, "DISTRIBUTION:")
+  }
+}
+

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

@@ -0,0 +1,377 @@
+// 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
+
+#import "config.typ": CLASSIFICATION_COLORS, counters, paragraph-config, spacing
+
+/// Creates vertical spacing equivalent to multiple blank lines.
+///
+/// Calculates proper vertical space based on line height and leading
+/// to maintain consistent spacing throughout the document.
+///
+/// - count (int): Number of blank lines to create
+/// - weak (bool): Whether spacing can be compressed at page breaks
+/// -> content
+#let blank-lines(count, weak: true) = {
+  if count == 0 {
+    v(0em, weak: weak)
+  } else {
+    let lead = spacing.line
+    let height = spacing.line-height
+    v(lead + (height + lead) * count, weak: weak)
+  }
+}
+
+/// Creates vertical spacing equivalent to one blank line.
+/// Convenience function for single line spacing.
+///
+/// - weak (bool): Whether spacing can be compressed at page breaks
+/// -> content
+#let blank-line(weak: true) = blank-lines(1, weak: weak)
+
+// =============================================================================
+// GENERAL UTILITY FUNCTIONS
+// =============================================================================
+
+/// Checks if a value is "falsey" (none, false, empty array, or empty string).
+///
+/// Provides a consistent way to test for empty or missing values across
+/// the template system. Used for conditional rendering of optional sections.
+///
+/// - 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 == "")
+}
+
+/// Scales content to fit within a specified box while maintaining 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.
+///
+/// - 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 {
+  // 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
+  box(width: width, height: height, clip: true)[
+    #align(alignment)[
+      #scale(f, reflow: true)[#body]
+    ]
+  ]
+}
+
+/// Checks if a string is in ISO date format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS).
+///
+/// Performs a simple pattern check for ISO 8601 date strings by verifying:
+/// - String is at least 10 characters long
+/// - Characters at positions 4 and 7 are dashes
+///
+/// - date-str (str): String to check for ISO date pattern
+/// -> bool
+#let is-iso-date-string(date-str) = {
+  if date-str.len() == 10 {
+    let char4 = date-str.at(4)
+    let char7 = date-str.at(7)
+    return char4 == "-" and char7 == "-"
+  } else if date-str.len() > 10 {
+    let char4 = date-str.at(4)
+    let char7 = date-str.at(7)
+    let char10 = date-str.at(10)
+    return char4 == "-" and char7 == "-" and char10 == "T"
+  }
+  return false
+}
+
+/// Extracts the date portion (YYYY-MM-DD) from an ISO date string.
+///
+/// Returns the first 10 characters which contain the date portion of an
+/// ISO 8601 date string, removing any time component if present.
+///
+/// - date-str (str): ISO date string to extract from
+/// -> str
+#let extract-iso-date(date-str) = {
+  date-str.slice(0, 10)
+}
+
+/// Formats a date in standard military format or ISO format depending on input type.
+///
+/// AFH 33-337 "Date": "Use the 'Day Month Year' or 'DD Mmm YY' format for documents
+/// addressed to a military organization. For civilian addressees, use the 'Month Day, Year' format."
+/// Examples: "15 October 2014" or "15 Oct 14" for military, "October 15, 2014" for civilian
+///
+/// Intelligently handles different date input formats:
+/// - ISO string (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS): Parsed via TOML and displayed in military format
+/// - Non-ISO string: Displayed as-is
+/// - datetime object: Displayed in military format ("1 January 2024")
+///
+/// - date (str|datetime): Date to format for display
+/// -> str
+// NOTE: Consider simplification if Typst adds native ISO date parsing (see CASCADES.md §A)
+#let display-date(date) = {
+  if type(date) == str {
+    if is-iso-date-string(date) {
+      // Parse ISO date string using TOML to get datetime object
+      let iso-date = extract-iso-date(date)
+      let toml-str = "date = " + iso-date
+      let parsed = toml(bytes(toml-str))
+      parsed.date.display("[day padding:none] [month repr:long] [year]")
+    } else {
+      date
+    }
+  } else {
+    date.display("[day padding:none] [month repr:long] [year]")
+  }
+}
+
+/// Gets the color associated with a classification level.
+///
+/// - level (str): Classification level string
+/// -> color
+#let get-classification-level-color(level) = {
+  if level == none {
+    return rgb(0, 0, 0) // Default to black if no classification
+  }
+  // Order matters - check most specific first
+  let level-order = ("TOP SECRET", "SECRET", "CONFIDENTIAL", "UNCLASSIFIED")
+
+  for base-level in level-order {
+    if base-level in level {
+      return CLASSIFICATION_COLORS.at(base-level)
+    }
+  }
+
+  rgb(0, 0, 0) // Default
+}
+
+// =============================================================================
+// GRID LAYOUT UTILITIES
+// =============================================================================
+
+/// Creates an automatic grid layout from string or array content.
+///
+/// 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.
+///
+/// Features:
+/// - Automatic column distribution and row filling
+/// - Configurable column spacing and count
+/// - Handles both single strings and arrays of strings
+/// - Adds padding cells to maintain consistent column alignment
+///
+/// - content (str | array): Content to arrange in grid (strings only)
+/// - 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)
+
+  assert(content_type == str or content_type == array, message: "Content must be a string or an array of strings.")
+  if content_type == array {
+    for item in content {
+      assert(type(item) == str, message: "All items in content array must be strings.")
+    }
+  }
+
+  // Normalize to 1d array
+  if content_type == str {
+    content = (content,)
+  }
+
+
+  // Build cell array in row-major order
+  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) {
+      cells.push([])
+    }
+  }
+
+  grid(
+    columns: calc.max(1, cols) + 1,
+    column-gutter: .1fr,
+    row-gutter: spacing.line,
+    ..cells
+  )
+}
+
+// =============================================================================
+// 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.
+///
+/// - 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) → ()
+#let ensure-array(value) = {
+  if value == none {
+    ()
+  } else if type(value) == array {
+    value
+  } else {
+    (value,)
+  }
+}
+
+/// Ensures the input is a string. If already a string, returns as-is.
+/// If an array, joins elements with the specified separator.
+///
+/// This utility eliminates repetitive `if type(x) == array { x.join(...) }`
+/// checks throughout the codebase by providing a canonical "normalize to string"
+/// function.
+///
+/// - value: Any value to normalize to string form
+/// - separator: String to use when joining array elements (default: "\n")
+/// - Returns: String representation of the value
+///
+/// Examples:
+/// - ensure-string("foo") → "foo"
+/// - ensure-string(("a", "b")) → "a\nb"
+/// - ensure-string(("a", "b"), ", ") → "a, b"
+/// - ensure-string(none) → ""
+#let ensure-string(value, separator: "\n") = {
+  if value == none {
+    ""
+  } else if type(value) == array {
+    value.join(separator)
+  } else {
+    str(value)
+  }
+}
+
+/// 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.
+///
+/// - 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
+#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
+  }
+}
+
+
+// =============================================================================
+// INDORSEMENT UTILITIES
+// =============================================================================
+
+/// Converts number to ordinal suffix for indorsements following AFH 33-337 conventions.
+///
+/// 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
+///
+/// - number (int): The indorsement number (1, 2, 3, etc.)
+/// -> str
+// NOTE: Could be table-driven vs algorithmic (see CASCADES.md §B) — current approach is correct
+#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"
+  }
+}
+
+/// 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
+///
+/// - 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"
+}
+
+/// 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)
+    }
+  }
+}