archsight 0.4.3 → 0.5.0

data/lib/archsight/pdf/theme.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "typst"
+require_relative "../assets"
+
+module Archsight
+  module Pdf
+    # The look of an exported document: what a Config resource of type pdf says, with a neutral built-in look for
+    # everything it leaves out (or for no template at all). Every value is checked here, so a template loaded
+    # from a file that was never linted cannot put anything but a colour, a font name or a length into the
+    # Typst source.
+    class Theme
+      DEFAULT_NAME = "default"
+      TYPE = "pdf" # the `config/type` of the Configs that describe the look
+      COLORS = {
+        primary: "#1f3a5f", accent: "#2f7fd1", text: "#1c1c1c", muted: "#6b7280",
+        ok: "#1f9d55", warn: "#d98e04", danger: "#c0392b"
+      }.freeze
+      FONTS = {
+        body: ["Liberation Sans", "DejaVu Sans", "Helvetica", "Arial"],
+        heading: ["Liberation Sans", "DejaVu Sans", "Helvetica", "Arial"],
+        mono: ["DejaVu Sans Mono", "Liberation Mono", "Menlo", "Courier New"]
+      }.freeze
+      PAPERS = %w[a4 a5 us-letter].freeze
+      LANGS = %w[en de].freeze
+      HEADER_PARTS = %w[id version date owner].freeze
+      DEFAULT_MARGIN = "16mm"
+      LOGO_TYPES = %w[.svg .png].freeze
+
+      attr_reader :name, :colors, :fonts, :footer_text, :classification, :header_meta, :lang, :paper, :margin,
+                  :logo, :logo_light, :font_dir
+
+      # @param template [Archsight::Resources::Config, nil]
+      # @param resources_dir [String] logos and fonts are looked up below it
+      def initialize(template = nil, resources_dir: Archsight.resources_dir)
+        @name = template&.name
+        ann = template ? template.annotations : {}
+        @colors = COLORS.to_h { |key, default| [key, color(ann["pdf/color-#{key}"], default)] }
+        @fonts = FONTS.to_h { |key, default| [key, font_list(ann["pdf/font-#{key}"], default)] }
+        @footer_text = blank_to_nil(ann["pdf/footer-text"])
+        @classification = blank_to_nil(ann["pdf/classification"])
+        @header_meta = header_parts(ann["pdf/header-meta"])
+        @lang = LANGS.include?(ann["pdf/lang"]) ? ann["pdf/lang"] : "en"
+        @paper = PAPERS.include?(ann["pdf/paper"]) ? ann["pdf/paper"] : "a4"
+        @margin = ann["pdf/margin"].to_s.match?(Resources::Config::LENGTH) ? ann["pdf/margin"] : DEFAULT_MARGIN
+        @logo = logo_file(ann["pdf/logo"], resources_dir)
+        @logo_light = logo_file(ann["pdf/logo-light"], resources_dir) || @logo
+        @font_dir = font_directory(ann["pdf/font-dir"], resources_dir)
+      end
+
+      # The Config a document asks for (`pdf:template:<name>`), else the one named `default`, else the built-in look. Only
+      # Configs of type pdf count.
+      # @param requested [String, nil] name as written in the tag, with or without the `Config:` and `PDF:` prefixes
+      def self.for(database, requested = nil)
+        wanted = (requested || DEFAULT_NAME).to_s.strip
+        configs = database.instances_by_kind("Config").values.select { |c| c.annotations["config/type"].to_s.casecmp?(TYPE) }
+        new(configs.find { |config| matches?(config.name, wanted) })
+      end
+
+      # `brand`, `PDF:brand` and `Config:PDF:brand` all name the same Config
+      def self.matches?(name, wanted)
+        short(name).casecmp?(short(wanted))
+      end
+
+      def self.short(name)
+        name.to_s.strip.sub(/\AConfig:/i, "").sub(/\APDF:/i, "")
+      end
+
+      # Typst source defining `theme`. `logo` and `logo_light` are the file names the logos were staged under.
+      def to_typst(logo: nil, logo_light: nil)
+        fields = colors.map { |key, hex| "#{key}: #{Typst.color(hex)}" }
+        fields += fonts.map { |key, list| "font-#{key}: (#{list.map { |f| Typst.lit(f) }.join(", ")},)" }
+        fields += [
+          "logo: #{logo ? Typst.lit(logo) : "none"}", "logo-light: #{logo_light ? Typst.lit(logo_light) : "none"}",
+          "footer-text: #{footer_text ? Typst.lit(footer_text) : "none"}",
+          "header-meta: (#{header_meta.map { |p| Typst.lit(p) }.join(", ")},)",
+          "lang: #{Typst.lit(lang)}", "paper: #{Typst.lit(paper)}", "margin: #{margin}"
+        ]
+        "#let theme = (#{fields.join(", ")})\n"
+      end
+
+      private
+
+      def color(value, default)
+        value.to_s.strip.match?(Resources::Config::COLOR) ? value.to_s.strip : default
+      end
+
+      def font_list(value, default)
+        name = value.to_s.strip
+        name.match?(Resources::Config::FONT_NAME) ? [name, *default] : default
+      end
+
+      def header_parts(value)
+        return HEADER_PARTS if value.to_s.strip.empty?
+
+        parts = value.to_s.split(",").map(&:strip) & HEADER_PARTS
+        parts.empty? ? HEADER_PARTS : parts
+      end
+
+      def blank_to_nil(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+
+      # @return [String, nil] absolute path of a logo inside the resources directory
+      def logo_file(path, resources_dir)
+        return nil if path.to_s.strip.empty?
+
+        file = Assets.file_for(path.to_s, resources_dir: resources_dir)
+        file if file && LOGO_TYPES.include?(File.extname(file).downcase)
+      end
+
+      def font_directory(path, resources_dir)
+        normalized = Assets.normalize(path.to_s)
+        return nil unless normalized
+
+        root = File.realpath(resources_dir)
+        dir = File.realpath(File.join(root, normalized))
+        dir if dir.start_with?(root + File::SEPARATOR) && File.directory?(dir)
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/archsight/pdf/typst/archsight.typ

@@ -0,0 +1,152 @@
+// Page shell of the Archsight PDF export. Generic: every colour, font, logo and text comes from `theme`
+// (see Archsight::Pdf::Theme), every per-document value is an argument.
+
+#let labels = (
+  en: (page: "Page", of: "of", contents: "Contents", draft: "DRAFT", doc-id: "Document ID", version: "Version", date: "Date", owner: "Owner", classification: "Classification"),
+  de: (page: "Seite", of: "von", contents: "Inhalt", draft: "ENTWURF", doc-id: "Dokument-ID", version: "Version", date: "Datum", owner: "Eigentümer", classification: "Einstufung"),
+)
+
+// Identifiers have no spaces: allow a line break after `-`, `:` and `/` and between camel-case words (no visible change)
+#let breakable(s) = if type(s) != str { s } else {
+  s.replace(regex("([:/-])"), m => m.text + "\u{200B}").replace(regex("([a-z0-9])([A-Z])"), m => m.captures.at(0) + "\u{200B}" + m.captures.at(1))
+}
+
+// An image at its natural size, shrunk to fit the text width and `max-height` of the page, centred
+#let fit-image(path, max-height: 0.5) = layout(size => context {
+  let natural = measure(image(path))
+  let limit = page.height * max-height
+  let w = calc.min(natural.width, size.width)
+  let h = w * (natural.height / natural.width)
+  if h > limit {
+    h = limit
+    w = h * (natural.width / natural.height)
+  }
+  align(center, image(path, width: w, height: h))
+})
+
+// The meta line of the header: the document id in the mono font, the parts separated by a light bar
+#let _meta-line(theme, id, version, date, owner) = {
+  let t = labels.at(theme.lang)
+  let parts = ()
+  if "id" in theme.header-meta and id != none { parts.push(text(font: theme.font-mono, breakable(id))) }
+  if "version" in theme.header-meta and version != none { parts.push(box[#t.version #version]) }
+  if "date" in theme.header-meta and date != none { parts.push(box[#date]) }
+  if "owner" in theme.header-meta and owner != none { parts.push(box[#owner]) }
+  parts.join(h(4pt) + text(fill: theme.muted.lighten(60%), "|") + h(4pt))
+}
+
+// The document shell: page layout, header, footer, headings, watermark.
+#let doc(
+  theme: none,
+  title: "",
+  doc-id: none,
+  version: none,
+  date: none,
+  owner: none,
+  classification: none,
+  draft: false,
+  landscape: false,
+  body,
+) = {
+  let t = labels.at(theme.lang)
+  set document(title: title)
+  set page(
+    paper: theme.paper,
+    flipped: landscape,
+    margin: (x: theme.margin, top: 22mm, bottom: 16mm),
+    header-ascent: 30%,
+    footer-descent: 35%,
+    header: grid(
+      columns: (1fr, auto),
+      align: (left + bottom, right + bottom),
+      text(size: 7pt, fill: theme.muted.lighten(30%), _meta-line(theme, doc-id, version, date, owner)),
+      if theme.logo != none { image(theme.logo, height: 6.5mm) },
+    ),
+    footer: {
+      set text(size: 7pt, fill: theme.muted)
+      line(length: 100%, stroke: 0.5pt + theme.muted.lighten(70%))
+      v(-2pt)
+      grid(
+        columns: (1fr, auto, 1fr),
+        column-gutter: 8pt,
+        align: (left + horizon, center + horizon, right + horizon),
+        if classification != none { text(weight: "bold", tracking: 0.06em, fill: theme.danger, classification) },
+        if theme.footer-text != none { text(style: "italic", theme.footer-text) },
+        context [#t.page #counter(page).display() #t.of #counter(page).final().first()],
+      )
+    },
+    background: if draft {
+      rotate(-45deg, text(size: 110pt, weight: "bold", fill: theme.muted.transparentize(85%), t.draft))
+    },
+  )
+  set text(font: theme.font-body, size: 10pt, fill: theme.text, lang: theme.lang)
+  set par(justify: false, leading: 0.62em)
+  show raw: set text(font: theme.font-mono, size: 8.5pt)
+  show raw.where(block: true): it => block(fill: luma(245), inset: 8pt, radius: 3pt, width: 100%, it)
+  show heading: set text(font: theme.font-heading, fill: theme.primary)
+  show heading.where(level: 1): set text(size: 16pt)
+  show heading.where(level: 2): set text(size: 13pt)
+  show heading.where(level: 3): set text(size: 11pt)
+  show link: set text(fill: theme.accent)
+  // Tables have horizontal rules only: a stronger one under the header, a light one under every other row, no frame and
+  // no vertical lines; the first column is flush with the text. Tables that pass their own stroke keep it.
+  set table(
+    stroke: (x, y) => if y == 0 { (bottom: 0.7pt + theme.muted.lighten(35%)) } else { (bottom: 0.4pt + theme.muted.lighten(75%)) },
+    inset: (x, y) => (left: if x == 0 { 0pt } else { 6pt }, right: 6pt, y: 6pt),
+  )
+  set table.cell(breakable: false)
+  show table.header: set text(weight: "semibold")
+  body
+}
+
+// Title with the kind at its right, a hairline directly below, then an optional intro
+#let title-block(theme: none, title: "", kind: none, intro: none) = {
+  grid(
+    columns: (1fr, auto),
+    align: (left + bottom, right + bottom),
+    text(font: theme.font-heading, size: 22pt, weight: "bold", fill: theme.primary, breakable(title)),
+    if kind != none { text(size: 8pt, fill: theme.muted, kind) },
+  )
+  v(-4pt)
+  line(length: 100%, stroke: 0.5pt + theme.muted.lighten(70%))
+  if intro != none { block(above: 8pt, below: 6pt, text(size: 9pt, fill: theme.muted, intro)) }
+}
+
+// A cover page without header and footer: a band with the logo at its bottom left, kind, title and a short rule, the
+// document meta at the bottom left of the page. The pages after it are numbered from 1.
+#let cover-page(theme: none, title: "", kind: none, doc-id: none, version: none, date: none, owner: none, classification: none) = {
+  let t = labels.at(theme.lang)
+  page(header: none, footer: none, margin: 0mm, background: none)[
+    #block(width: 100%, height: 52mm, fill: theme.primary, inset: (x: theme.margin, bottom: 12mm), align(left + bottom, if theme.logo-light != none { image(theme.logo-light, height: 9mm) }))
+    #block(width: 100%, inset: (x: theme.margin, top: 34mm), {
+      if kind != none {
+        text(size: 7.5pt, weight: 600, tracking: 0.04em, fill: theme.accent, upper(kind))
+        v(2pt)
+      }
+      par(leading: 0.4em, text(font: theme.font-heading, size: 28pt, weight: "bold", fill: theme.primary, breakable(title)))
+      v(10pt)
+      line(length: 36mm, stroke: 2pt + theme.accent)
+    })
+    #let meta = (
+      (t.doc-id, if doc-id != none { text(font: theme.font-mono, breakable(doc-id)) }),
+      (t.version, version),
+      (t.date, date),
+      (t.owner, owner),
+      (t.classification, if classification != none { text(weight: "bold", fill: theme.danger, classification) }),
+    ).filter(m => m.at(1) != none)
+    #place(bottom + left, dx: theme.margin, dy: -20mm, grid(
+      columns: 2,
+      column-gutter: 14pt,
+      row-gutter: 7pt,
+      ..meta.map(((k, v)) => (text(size: 8pt, fill: theme.muted, k), text(size: 9pt, v))).flatten(),
+    ))
+    // the pages after the cover count from 1 (set inside the cover, so that nothing after it forces another page)
+    #counter(page).update(0)
+  ]
+}
+
+#let toc-page(theme: none, depth: 3) = {
+  let t = labels.at(theme.lang)
+  outline(title: t.contents, depth: depth)
+  pagebreak()
+}

data/lib/archsight/pdf/typst.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Pdf
+    # Building blocks for Typst source (https://typst.app). All text is emitted as Typst string literals
+    # (`#"..."`) and structure as function calls (`#strong[...]`), so no content can be mistaken for markup.
+    module Typst
+      LANGUAGE = /\A[A-Za-z0-9+#-]+\z/
+
+      module_function
+
+      # A Typst string literal, for use as a function argument
+      def lit(text)
+        escaped = text.to_s.delete("\r").gsub(/[\\"]/) { "\\#{Regexp.last_match(0)}" }.gsub("\n", "\\n")
+        "\"#{escaped}\""
+      end
+
+      # A Typst string literal as markup, for use inside content
+      def str(text)
+        "##{lit(text)}"
+      end
+
+      # A block of preformatted text
+      def raw(source, lang = nil)
+        lang_arg = lang.to_s.match?(LANGUAGE) ? ", lang: #{lit(lang)}" : ""
+        "#raw(#{lit(source.to_s.chomp)}, block: true#{lang_arg})"
+      end
+
+      # A short text on a coloured background (a status)
+      def badge(text, hex)
+        "#box(fill: #{color(hex)}, inset: (x: 4pt, y: 1pt), radius: 2pt)[#{str(text)}]"
+      end
+
+      # A framed message that stands where something could not be shown
+      def note(text, fill: "#fff3cc")
+        "#block(fill: #{color(fill)}, inset: 8pt, radius: 3pt, width: 100%)[#{str(text)}]"
+      end
+
+      # A Typst colour from `#rrggbb` / `#rgb`
+      def color(hex)
+        "rgb(#{lit(hex)})"
+      end
+    end
+  end
+end

data/lib/archsight/pdf.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require_relative "pdf/compiler"
+require_relative "pdf/document"
+
+module Archsight
+  # PDF export of pages and resources, laid out by Typst (https://typst.app, installed as the `typst` command).
+  # See Archsight::Pdf::Document for what steers it and Archsight::Resources::Config (type pdf) for the look.
+  module Pdf
+    module_function
+
+    # @param resource [Archsight::Resources::Base] a page or any other resource
+    # @return [Archsight::Pdf::Document]
+    def document(database, resource, compiler: Compiler.new, **)
+      Document.new(database, resource, pdf_images: compiler.pdf_images?, **)
+    end
+
+    # The PDF of a prepared document
+    # @return [String]
+    # @raise [Unavailable, Error]
+    def compile(document, compiler: Compiler.new)
+      Dir.mktmpdir("archsight-pdf") do |dir|
+        document.files.each { |name, content| File.binwrite(File.join(dir, name), content) }
+        compiler.compile(dir, font_paths: document.font_paths)
+      end
+    end
+  end
+end

data/lib/archsight/resources/config.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# Config holds settings of a feature of the tool, kept with the model so they are shared and versioned like it
+class Archsight::Resources::Config < Archsight::Resources::Base
+  include_annotations :architecture
+
+  description <<~MD
+    Holds the settings of a feature of the tool, such as the look of the PDF export.
+
+    ## Definition
+
+    A Config is a tool-specific resource type. It carries no architecture, only settings, so that everything that
+    should look or behave the same is written once and shared through the resources repository instead of being
+    repeated in every page. It is not the per-user configuration file (tokens, URLs of other systems): that stays in
+    `~/.config/archsight/archsight.yaml`.
+
+    ## Type
+
+    `config/type` says which feature the settings are for; the feature looks up its own Configs by type, so every
+    feature can have a Config named `default`. The settings of a feature use the annotations of its own prefix.
+
+    | `config/type` | Settings | Used by |
+    |---------------|----------|---------|
+    | `pdf` | `pdf/*`: colours, fonts, logo, header and footer | [PDF export](/doc/pdf-export) |
+
+    A document picks a different Config of the type with the tag `pdf:template:<name>`; without a tag the one named
+    `default` is used, and without any the export has a neutral built-in look.
+
+    ## PDF settings
+
+    - **Colours** (`pdf/color-*`) are hex values (`#0b3d91`). `primary` is used for headings, the cover band and
+      table headers, `accent` for rules and links.
+    - **Fonts** (`pdf/font-*`) are family names. Fonts that are not installed fall back to the built-in ones; put
+      font files in a directory of the resources and name it in `pdf/font-dir` to ship them with the model.
+    - **Logos** (`pdf/logo`, `pdf/logo-light`) are image files (svg, png) of the resources directory, given
+      relative to it. `logo` goes on white (page header), `logo-light` on the coloured cover band.
+    - **Texts** (`pdf/footer-text`, `pdf/classification`) appear on every page.
+  MD
+
+  icon "settings"
+  layer "other"
+
+  TYPE_FORMAT = /\A[a-z][a-z0-9-]*\z/
+
+  annotation "config/type",
+             description: "The feature these settings are for (pdf). The feature looks up its Configs by this type",
+             title: "Type",
+             filter: :word,
+             summary: true,
+             validator: ->(value) { Archsight::Resources::Config.pattern_error(value, TYPE_FORMAT, "a lowercase word such as pdf") }
+
+  COLOR = /\A#(\h{3}|\h{6})\z/
+  FONT_NAME = /\A[\p{L}\p{N} ._+-]{1,80}\z/
+  LENGTH = /\A\d+(\.\d+)?(mm|cm|pt|in)\z/
+
+  # Colour annotations: key suffix, title, role
+  COLORS = {
+    "primary" => ["Primary colour", "headings, cover band, table headers"],
+    "accent" => ["Accent colour", "rules and links"],
+    "text" => ["Text colour", "body text"],
+    "muted" => ["Muted colour", "secondary text, header and footer"],
+    "ok" => ["Positive colour", "good status"],
+    "warn" => ["Warning colour", "warning status"],
+    "danger" => ["Danger colour", "bad status and the classification marking"]
+  }.freeze
+
+  COLORS.each do |key, (title, role)|
+    annotation "pdf/color-#{key}",
+               description: "#{title} as hex value (#rrggbb), used for #{role}",
+               title: title,
+               validator: ->(value) { Archsight::Resources::Config.pattern_error(value, COLOR, "a hex colour such as #0b3d91") },
+               sidebar: false
+  end
+
+  %w[body heading mono].each do |role|
+    annotation "pdf/font-#{role}",
+               description: "Font family of the #{role} text",
+               title: "#{role.capitalize} font",
+               validator: ->(value) { Archsight::Resources::Config.pattern_error(value, FONT_NAME, "a font family name") },
+               sidebar: false
+  end
+
+  annotation "pdf/font-dir",
+             description: "Directory with font files (ttf, otf), relative to the resources directory",
+             title: "Font directory",
+             sidebar: false
+
+  annotation "pdf/logo",
+             description: "Logo for the page header (svg or png), path relative to the resources directory",
+             title: "Logo",
+             validator: ->(value) { Archsight::Resources::Config.logo_error(value) },
+             sidebar: false
+  annotation "pdf/logo-light",
+             description: "Logo for the coloured cover band (svg or png), path relative to the resources directory",
+             title: "Logo (light)",
+             validator: ->(value) { Archsight::Resources::Config.logo_error(value) },
+             sidebar: false
+
+  annotation "pdf/footer-text",
+             description: "Text in the footer of every page (centre)",
+             title: "Footer text",
+             sidebar: false
+  annotation "pdf/classification",
+             description: "Marking shown in the footer of every page, e.g. Internal. A document can override it with " \
+                          "the page property Classification",
+             title: "Classification",
+             sidebar: false
+  annotation "pdf/header-meta",
+             description: "Comma-separated parts of the header line: id, version, date, owner (default: all)",
+             title: "Header line",
+             sidebar: false,
+             validator: ->(value) { Archsight::Resources::Config.header_meta_error(value) }
+  annotation "pdf/lang",
+             description: "Language of the fixed texts (page, contents, ...)",
+             title: "Language",
+             enum: %w[en de],
+             sidebar: false
+  annotation "pdf/paper",
+             description: "Paper size",
+             title: "Paper",
+             enum: %w[a4 a5 us-letter],
+             sidebar: false
+  annotation "pdf/margin",
+             description: "Horizontal page margin as length (e.g. 16mm)",
+             title: "Margin",
+             validator: ->(value) { Archsight::Resources::Config.pattern_error(value, LENGTH, "a length such as 16mm") },
+             sidebar: false
+
+  HEADER_PARTS = %w[id version date owner].freeze
+
+  # Validator helpers: nil if the value is fine, else the message
+  def self.pattern_error(value, pattern, expected)
+    value.to_s.match?(pattern) ? nil : "expected #{expected}"
+  end
+
+  def self.logo_error(value)
+    ext = File.extname(value.to_s).downcase
+    return nil if %w[.svg .png].include?(ext) && Archsight::Assets.normalize(value.to_s)
+
+    "expected a path of an svg or png file relative to the resources directory"
+  end
+
+  def self.header_meta_error(value)
+    unknown = value.to_s.split(",").map(&:strip) - HEADER_PARTS
+    unknown.empty? ? nil : "unknown part #{unknown.join(", ")}; use #{HEADER_PARTS.join(", ")}"
+  end
+end

data/lib/archsight/version.rb

@@ -4,5 +4,5 @@
 # Do not edit manually.
 
 module Archsight
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end