metanorma-document 0.3.0 → 0.4.0

data/TODO.finalize/11-config-driven-flavor-metadata.md

@@ -1,20 +0,0 @@
-# 11 — Config-driven flavor metadata: eliminate boilerplate renderers — DONE
-
-## What was done
-All 13 theme YAML files contain publisher metadata:
-```yaml
-publishers:
-  - "ISO"
-publisher_name: "ISO"
-logos:
-  "ISO": "iso-logo.svg"
-```
-
-BaseRenderer reads publishers/logos from theme via `theme.publishers`, `theme.publisher_name`, `theme.logos`. No renderer code overrides these.
-
-10 flavor renderers are empty shells (0 methods, just inherit IsoRenderer). They exist because `Generator` maps document classes to renderer classes, but all customization comes from theme YAML config.
-
-Theme auto-resolves from document type via `FLAVOR_MAP` — no manual `theme` override needed in any renderer.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/12-add-frozen-string-literal.md

@@ -1,6 +0,0 @@
-# 12 — Add frozen_string_literal to all Ruby files — DONE
-
-All `lib/` and `spec/` Ruby files already have `# frozen_string_literal: true` on line 1. No changes needed.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/13-extract-composition-from-god-class.md

@@ -1,96 +0,0 @@
-# 13 — Extract module includes into composition — DONE
-
-## Problem
-BaseRenderer is a God class with 180+ public methods from 4 mixed-in modules:
-- `InlineRendering` (~590 lines, 39 methods)
-- `BlockRendering` (~295 lines, 24 methods)
-- `SectionRendering` (~90 lines, 8 methods)
-- `PubidRendering` (~55 lines, 2 methods)
-
-Module includes break OCP and encapsulation — all module methods become public on the single class, making it impossible to reason about responsibilities in isolation.
-
-## Architecture
-
-Replace `include` with composition. Each module becomes a standalone class that receives a reference to the coordinator for cross-concern calls:
-
-```
-BaseRenderer (coordinator, ~50 methods)
-  ├── InlineRenderer (inline elements, 39 methods)
-  ├── BlockRenderer (block elements, 24 methods)
-  ├── SectionRenderer (sections, 8 methods)
-  └── PubidRenderer (pubid parsing, 2 methods)
-```
-
-### Cross-concern dependencies (one-way, clean extraction)
-
-InlineRenderer needs from coordinator:
-- `escape_html`, `safe_attr`, `element_attrs`, `capture_output`, `render_liquid`
-- `render_paragraph`, `render_inline_element` (recursive dispatch)
-- `@output`, `@footnote_collector`, `@index_term_collector`
-
-BlockRenderer needs from coordinator:
-- `escape_html`, `safe_attr`, `element_attrs`, `capture_output`, `render_liquid`
-- `render_mixed_inline`, `render_inline_element`, `render_mixed_content_in_order`
-- `walk_ordered`, `block_element?`, `render` (recursive dispatch)
-- `@output`, `renderer_context`
-
-SectionRenderer needs from coordinator:
-- `escape_html`, `safe_attr`, `element_attrs`, `capture_output`, `render_liquid`
-- `walk_ordered`, `render`, `render_note`, `extract_plain_text`
-- `@output`
-
-PubidRenderer needs from coordinator:
-- `escape_html`, `flavor_name`
-
-### Implementation plan
-
-1. Create `InlineRenderer` class at `lib/metanorma/html/renderers/inline_renderer.rb`
-   - Receives `coordinator` in constructor
-   - Moves all methods from `InlineRendering` module
-   - Delegates shared utility calls to coordinator
-2. Create `BlockRenderer` class at `lib/metanorma/html/renderers/block_renderer.rb`
-   - Same pattern
-3. Create `SectionRenderer` class at `lib/metanorma/html/renderers/section_renderer.rb`
-   - Same pattern
-4. Create `PubidRenderer` class at `lib/metanorma/html/renderers/pubid_renderer.rb`
-   - Same pattern
-5. Update `BaseRenderer` to instantiate sub-renderers and delegate
-6. Update `RendererContext` to delegate through coordinator's sub-renderers
-7. Update all flavor renderers (IsoRenderer, StandardRenderer, etc.) for new API
-8. Update all Drop classes that call `renderer.method_name`
-9. Ensure all existing specs pass
-
-### Delegation pattern
-
-```ruby
-class BaseRenderer
-  attr_reader :inline_renderer, :block_renderer, :section_renderer, :pubid_renderer
-
-  def initialize
-    @inline_renderer = InlineRenderer.new(self)
-    @block_renderer = BlockRenderer.new(self)
-    @section_renderer = SectionRenderer.new(self)
-    @pubid_renderer = PubidRenderer.new(self)
-    # ...
-  end
-
-  # Delegate for backward compatibility during migration
-  def render_paragraph(...) = @block_renderer.render_paragraph(...)
-  def render_em(...) = @inline_renderer.render_em(...)
-  # etc.
-end
-```
-
-### Flavor renderers
-
-Sub-renderers can be extended per flavor:
-```ruby
-class IsoSectionRenderer < SectionRenderer
-  def render_preface(preface, **)
-    # ISO-specific preface ordering
-  end
-end
-```
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/14-config-driven-section-ordering.md

@@ -1,31 +0,0 @@
-# 14 — Config-driven preface and clause ordering — DONE
-
-## What was done
-
-### Theme config attributes added:
-- `preface_order` — array of section names, controls rendering order (default: `foreword introduction abstract clause acknowledgements executivesummary`)
-- `preface_wrap` — boolean, wraps preface content in a container div with heading (default: `false`)
-- `clause_order` — array of section names for clause ordering (default: `sections annex bibliography indexsect`)
-- `toc_filter_types` — array of clause types to exclude from preface rendering (default: `[]`)
-
-### All 13 theme YAML files updated:
-- ISO, IEC, IEEE, IETF, ITU, IHO, CC, BIPM, OIML, PDFA, Ribose, ICC: default ordering
-- OGC: `preface_order: [clause]`, `preface_wrap: true`, `toc_filter_types: [toc]`
-
-### Code changes:
-- `Theme` — added `preface_order`, `preface_wrap`, `clause_order`, `toc_filter_types` to VALID_KEYS, attr_accessor, and defaults
-- `SectionRenderer` — config-driven `render_preface` reads from theme, delegates to `render_ordered_preface` or `render_wrapped_preface` based on `preface_wrap`
-- `BaseRenderer` — added `render_preface` delegation to section_renderer
-- `IsoRenderer` — deleted hardcoded `render_preface` method (config-driven version replaces it)
-- `OgcRenderer` — deleted hardcoded `render_preface` override (now empty shell, all behavior from YAML)
-- Template `_ogc_preface.html.liquid` renamed to `_wrapped_preface.html.liquid` (generic name)
-
-### Specs added:
-- `config_preface_spec.rb` — 8 specs covering ordered mode, wrapped mode, clause filtering, and delegation
-- `theme_spec.rb` — 4 specs for section ordering defaults and OGC overrides
-
-### Key principle enforced:
-No flavor-specific knowledge (no "ogc", no hardcoded ordering) in generic renderer code. All behavior comes from theme YAML config.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/15-theme-directories-per-flavor.md

@@ -1,46 +0,0 @@
-# 15 — Theme directories per flavor with data-centric config — DONE
-
-## What was done
-
-### Theme class changes:
-- Added `theme_dir` attribute (set when loaded from directory, nil for flat file themes)
-- `Theme.load(flavor)` now checks for directory format first (`data/themes/{flavor}/theme.yaml`), falls back to flat file (`data/themes/{flavor}.yaml`)
-- Extracted `from_file`, `from_directory`, `apply_overrides` class methods for clean separation
-- Added `theme_templates_dir` — returns `{theme_dir}/templates/` if it exists
-- Added `theme_assets_dir` — returns `{theme_dir}/assets/` if it exists
-- Added `theme_css_path` — returns `{theme_dir}/custom.css` if it exists
-- Added `resolve_template(template_name)` — checks flavor templates dir first, falls back to shared templates
-- Added `resolve_asset(filename)` — checks flavor assets dir, returns nil if not found
-
-### BaseRenderer changes:
-- `render_liquid` uses `theme.resolve_template(template_name)` instead of hardcoded `File.join(TEMPLATES_ROOT, ...)`
-- `load_logo_svg` checks `theme.resolve_asset(filename)` before shared `LOGO_DIR`
-- `build_styles` appends `theme.theme_css_path` content if present
-
-### Directory-based theme structure (opt-in):
-```
-data/themes/
-  iso.yaml              # flat file — still works as before
-  ogc.yaml              # flat file — still works as before
-  {flavor}/             # directory format — new support
-    theme.yaml          # palette, fonts, layout, ordering, publisher metadata
-    custom.css          # per-flavor CSS overrides (optional)
-    templates/          # per-flavor Liquid template overrides (optional)
-      _cover.html.liquid
-    assets/             # per-flavor assets: logos, images (optional)
-      {flavor}-logo.svg
-```
-
-### Backward compatibility:
-- All 13 existing flat YAML theme files continue to work unchanged
-- `theme_dir` is nil for flat-file themes, so resolution always falls through to shared paths
-- No migration needed — directory format is opt-in
-
-### Specs added:
-- 12 new specs in `theme_spec.rb` covering directory loading, template/asset/CSS resolution, backward compat
-
-### Future consideration:
-When theme config moves to per-flavor gems, `Theme.load` can be extended to search gem data directories. The API (`theme.resolve_template`, `theme.resolve_asset`, etc.) stays the same — only the path resolution changes.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/16-theme-lutaml-model-schema.md

@@ -1,44 +0,0 @@
-# 16 — Theme as lutaml-model with YAML schema — DONE
-
-## What was done
-
-Converted `Theme` from a plain Ruby class with `attr_accessor` + `VALID_KEYS` + manual YAML parsing to a proper `Lutaml::Model::Serializable` with typed attributes.
-
-### Schema definition
-- 65 typed attributes declared with lutaml-model `attribute` DSL
-- Types: `:string` (colors, fonts, CSS), `:boolean` (preface_wrap), `:hash` (logos)
-- Collection arrays: `:string, collection: true` (publishers, preface_order, clause_order, toc_filter_types)
-- All defaults declared via `default: -> { ... }` procs
-- Nil-by-default attributes (accent_deep, warm, dark_note_bg, etc.) have no default
-
-### What was eliminated
-- `VALID_KEYS` constant — no longer needed, attribute declarations ARE the schema
-- `SETTERS` constant — lutaml-model handles key→setter mapping
-- Manual `initialize` with 60+ instance variable assignments — lutaml-model handles initialization
-- `apply_overrides` method — `from_yaml` handles deserialization
-- `require "yaml"` + `YAML.safe_load_file` — `File.read(path)` + `from_yaml` replaces it
-
-### What was preserved
-- `theme_dir` as regular `attr_accessor` (not a YAML attribute, set programmatically)
-- `THEMES_DIR`, `TEMPLATES_ROOT` constants
-- All behavior methods: `to_css_root`, `to_css_extras`, `resolve_template`, `resolve_asset`, etc.
-- `load(flavor)`, `from_file`, `from_directory` class methods
-- Full backward compatibility — all 111 theme specs pass unchanged
-
-### Schema introspection
-```ruby
-Metanorma::Html::Theme.attributes.size  # => 65
-Metanorma::Html::Theme.attributes[:preface_wrap].type  # => Lutaml::Model::Type::Boolean
-Metanorma::Html::Theme.attributes[:publishers].collection?  # => true
-Metanorma::Html::Theme.attributes[:logos].type  # => Lutaml::Model::Type::Hash
-```
-
-### Why this matters
-- **Flavor authors** get schema-level documentation — every valid key, its type, and default value is declared in one place
-- **Type safety** — wrong types in YAML are caught at load time by lutaml-model
-- **No silent ignores** — with the old `VALID_KEYS` + `SETTERS` pattern, unknown keys were silently skipped. Now lutaml-model handles key mapping
-- **Round-tripping** — themes can be loaded, modified, and serialized back to YAML via `to_yaml`
-- **Future-proof** — when theme configs move to per-flavor gems, the model stays the same; only the load path changes
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/docs/html-renderer.adoc

@@ -1,261 +0,0 @@
-= HTML Renderer Architecture
-
-== Overview
-
-The HTML renderer converts a Metanorma document model (parsed from presentation XML) into a complete, self-contained HTML document. It produces all body content, header, footer, table of contents, CSS theming, and JavaScript interactivity.
-
-== Pipeline
-
-....
-Generator.generate(doc)
-  ├── Auto-selects renderer by document class
-  ├── Renderer.new
-  └── renderer.generate_full_document(doc)
-        ├── Header (publisher logos, document title)
-        ├── ToC sidebar
-        ├── Body content (recursive render)
-        ├── Footnotes
-        ├── Footer (copyright)
-        └── Asset pipeline (inline CSS + JS)
-....
-
-== Renderer Hierarchy
-
-[source,ruby]
-BaseRenderer                  # Core HTML rendering, document assembly, CSS/JS pipeline
-└── StandardRenderer          # Terms, definitions, annexes, bibliography
-    ├── IsoRenderer           # ISO cover page, copyright, title formatting
-    │   ├── IccRenderer       # ICC publisher styling
-    │   └── PdfaRenderer      # PDF Association publisher styling
-    ├── IecRenderer           # IEC-specific formatting
-    ├── IeeeRenderer          # IEEE-specific formatting
-    ├── IetfRenderer          # IETF-specific formatting
-    ├── IhoRenderer           # IHO-specific formatting
-    ├── ItuRenderer           # ITU-specific formatting
-    ├── OgcRenderer           # OGC-specific formatting
-    ├── OimlRenderer          # OIML-specific formatting
-    ├── BipmRenderer          # BIPM-specific formatting
-    ├── CcRenderer            # CC-specific formatting
-    └── RiboseRenderer        # Ribose-specific formatting
-
-=== Renderer Selection
-
-The `Generator` uses a two-tier lookup:
-
-1. **Taste match**: If the document's publisher matches a registered taste, use that renderer.
-2. **Model class**: Walk the ancestor chain from most specific to `BaseRenderer`.
-
-[source,ruby]
-# ICC documents are IsoDocument::Root but use IccRenderer
-Metanorma::Html::Generator.register_taste(
-  Metanorma::IsoDocument::Root,
-  "ICC",
-  Metanorma::Html::IccRenderer
-)
-
-== Class Name Ownership
-
-The HTML renderer owns its class names entirely. **No XML-originated class names appear in the HTML output.**
-
-The XML document model's `class_attr` is read as **input only** to determine semantic role. The renderer maps XML roles to HTML-specific class names via `SPAN_ROLE_CLASSES`:
-
-[source,ruby]
-SPAN_ROLE_CLASSES = {
-  "boldtitle" => "title-text",
-  "citefig" => "xref-fig",
-  "citesec" => "xref-section",
-  "fmt-element-name" => "element-label",
-  "fmt-obligation" => "obligation-text",
-  # ...
-}.freeze
-
-Block-level classes (`note-block`, `formula`, `figure`, etc.) are assigned by the renderer based on what it's rendering — never carried over from XML.
-
-Inline span classes go through `html_class_for_span`:
-
-[source,ruby]
-def html_class_for_span(xml_class)
-  SPAN_ROLE_CLASSES[xml_class] || "span-#{xml_class}"
-end
-
-Raw XML content (e.g., boilerplate) passes through Nokogiri post-processing that remaps any remaining XML class names.
-
-== Drop Pattern
-
-Block elements (notes, examples, sourcecode, formulas, figures, admonitions) use the Drop pattern to separate data capture from template rendering.
-
-=== How It Works
-
-. A `Drop` class captures rendered content via `RendererContext`
-. The Drop passes pre-rendered HTML strings to a Liquid template
-. The template reads Drop attributes and outputs final HTML
-
-[source,ruby]
-# In the renderer:
-def render_note(note, **_opts)
-  drop = Drops::NoteDrop.from_model(note, renderer: renderer_context)
-  @output << render_liquid("_note.html.liquid", { "block" => drop })
-end
-
-# In the Drop:
-class NoteDrop < BlockElementDrop
-  def self.from_model(note, renderer:)
-    content_html = renderer.capture_output do
-      note.content.each { |para| renderer.render_paragraph(para) }
-    end
-    new(id: renderer.safe_attr(note, :id),
-        label_html: renderer.escape_html(label),
-        content_html: content_html,
-        css_class: "note-block")
-  end
-end
-
-=== BlockElementDrop
-
-All block drops inherit from `BlockElementDrop`, which provides common attributes:
-
-`id` :: HTML element id
-`type` :: Block type identifier
-`label_html` :: Pre-rendered label (e.g., "NOTE", "EXAMPLE 1")
-`content_html` :: Pre-rendered inner content
-`css_class` :: HTML-specific class name
-
-=== RendererContext
-
-`RendererContext` is a facade inside `BaseRenderer` that exposes only the rendering methods Drops need. Drops call renderer methods through this facade — the renderer's private interface stays encapsulated.
-
-[source,ruby]
-class RendererContext
-  def safe_attr(obj, method_name)
-  def escape_html(text)
-  def extract_block_label(block, default)
-  def extract_plain_text(node)
-  def capture_output(&block)
-  def render_paragraph(p)
-  def render_mixed_inline(node)
-  def render_inline_element(el)
-  def render_unordered_list(ul)
-  def render_ordered_list(ol)
-  def render_definition_list(dl)
-  def render_table(table)
-  def render_figure(figure)
-end
-
-== Liquid Templates
-
-HTML structure is defined in `.liquid` templates under `lib/metanorma/html/templates/`.
-
-[horizontal]
-`document.html.liquid` :: Full document shell (`<html>`, `<head>`, `<body>`)
-`_header.html.liquid` :: Sticky header with publisher logos
-`_footer.html.liquid` :: Footer with copyright
-`_cover.html.liquid` :: Generic cover page layout
-`_iso_cover.html.liquid` :: ISO-specific cover page
-`_iso_doc_title.html.liquid` :: ISO document title rendering
-`_doc_title.html.liquid` :: Generic document title rendering
-`_footnotes.html.liquid` :: Footnotes section
-`_note.html.liquid` :: Note block
-`_example.html.liquid` :: Example block
-`_sourcecode.html.liquid` :: Source code block
-`_formula.html.liquid` :: Formula block
-`_figure.html.liquid` :: Figure block
-`_admonition.html.liquid` :: Admonition block
-
-Templates use `Liquid::LocalFileSystem` for partials (prefixed with `_`). The `render_liquid` method handles template caching.
-
-=== Template Example
-
-`_note.html.liquid`:
-
-[source,liquid]
-----
-<div{% if block.id %} id="{{ block.id }}"{% endif %} class="{{ block.css_class }}">
-  {% if block.label_html %}
-  <p class="note-label"><strong>{{ block.label_html }}</strong></p>
-  {% endif %}
-  <div class="note-content">
-    {{ block.content_html }}
-  </div>
-</div>
-----
-
-== Theming
-
-Each renderer has a `Theme` object controlling colors, typography, and layout. Theme properties are emitted as CSS custom properties (`--mn-primary`, `--font-body`, etc.).
-
-[source,ruby]
-class MyRenderer < Metanorma::Html::StandardRenderer
-  def theme
-    @theme ||= begin
-      t = Theme.new
-      t.primary = "#1a5276"
-      t.accent = "#2e86c1"
-      t.font_body = '"Charter", serif'
-      t
-    end
-  end
-end
-
-=== Theme Properties
-
-[horizontal]
-`primary` :: Primary brand color
-`accent` :: Accent/highlight color
-`gradient` :: Header gradient
-`font_body` :: Body text font stack
-`font_sans` :: Sans-serif font stack
-`font_mono` :: Monospace font stack
-`font_url` :: Google Fonts URL
-`note_border` :: Note block border color
-`note_bg` :: Note block background
-`example_border` :: Example block border color
-`example_bg` :: Example block background
-`admonition_border` :: Admonition border color
-`admonition_bg` :: Admonition background
-`extra_css` :: Additional CSS string appended after defaults
-
-== Presentation XML
-
-The HTML renderer expects **presentation XML** (not source XML). Presentation XML contains `fmt-*` display elements alongside semantic elements:
-
-- `fmt-title` — formatted section/block titles
-- `fmt-xref` — formatted cross-reference text
-- `fmt-link` — formatted link text
-- `fmt-concept` — formatted concept references
-- `fmt-definition` — formatted term definitions
-- `fmt-preferred` — formatted preferred term names
-
-The renderer prioritizes `fmt-*` elements for rendering, falling back to semantic elements when display elements are absent.
-
-== Asset Pipeline
-
-The `AssetPipeline` compiles CSS and JavaScript from modular source files into inline `<style>` and `<script>` blocks for self-contained output.
-
-=== CSS
-
-[horizontal]
-`data/stylesheets/base/` :: Reset, typography, layout, dark mode, print
-`data/stylesheets/components/` :: Component stylesheets (inline, tables, notes, etc.)
-
-=== JavaScript
-
-[horizontal]
-`data/javascripts/core/` :: Reader, theme, scroll, navigation, reveal
-`data/javascripts/components/` :: ToC, search, lightbox, code copy, glossary, etc.
-
-== Extending
-
-To add a new flavor renderer:
-
-. Subclass the appropriate base (usually `IsoRenderer` or `StandardRenderer`)
-. Override `theme` with brand colors/fonts
-. Override `publisher_logo_map` with logo filenames
-. Register with the Generator:
-
-[source,ruby]
-Metanorma::Html::Generator.register(
-  Metanorma::MyDocument::Root,
-  Metanorma::Html::MyRenderer
-)
-
-To customize how a specific block renders, override the `render_*` method and either emit HTML directly or use the Drop pattern with a new template.