coradoc 1.1.8 → 2.0.12

data/lib/coradoc/core_model/table.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents a table cell in a document
+    #
+    # Table cells can contain text content and have various formatting
+    # attributes like alignment, colspan, rowspan, and styling.
+    #
+    # Cell format specification: [colspan][.rowspan][halign][valign][style][*]
+    #
+    # @example Creating a table cell with full formatting
+    #   cell = CoreModel::TableCell.new(
+    #     content: "Cell content",
+    #     alignment: "center",
+    #     colspan: 2,
+    #     rowspan: 3,
+    #     style: "emphasis",
+    #     bgcolor: "#ffff00"
+    #   )
+    class TableCell < Base
+      attribute :children, Base, collection: true
+
+      include ChildrenContent
+
+      # @!attribute content
+      #   @return [String, nil] text content of the cell
+      attribute :content, :string
+
+      # @!attribute alignment
+      #   @return [String, nil] horizontal text alignment ('left', 'center', 'right')
+      attribute :alignment, :string
+
+      # @!attribute vertical_alignment
+      #   @return [String, nil] vertical alignment ('top', 'middle', 'bottom')
+      attribute :vertical_alignment, :string
+
+      # @!attribute colspan
+      #   @return [Integer, nil] number of columns to span
+      attribute :colspan, :integer
+
+      # @!attribute rowspan
+      #   @return [Integer, nil] number of rows to span
+      attribute :rowspan, :integer
+
+      # @!attribute header
+      #   @return [Boolean] whether this is a header cell
+      attribute :header, :boolean, default: -> { false }
+
+      # @!attribute style
+      #   @return [String, nil] cell style ('default', 'strong', 'emphasis', 'monospace',
+      #     'asciidoc', 'literal', 'verse')
+      attribute :style, :string
+
+      private
+
+      def comparable_attributes
+        %i[content alignment vertical_alignment colspan rowspan header style]
+      end
+    end
+
+    # Represents a row in a table
+    #
+    # A table row contains multiple cells and can be a header row
+    # or a data row.
+    #
+    # @example Creating a table row
+    #   row = CoreModel::TableRow.new(
+    #     cells: [
+    #       CoreModel::TableCell.new(content: "Name"),
+    #       CoreModel::TableCell.new(content: "Value")
+    #     ],
+    #     header: true
+    #   )
+    class TableRow < Base
+      # @!attribute cells
+      #   @return [Array<TableCell>] collection of cells in the row
+      attribute :cells, TableCell, collection: true
+
+      # @!attribute header
+      #   @return [Boolean] whether this is a header row
+      attribute :header, :boolean, default: -> { false }
+
+      private
+
+      def comparable_attributes
+        %i[cells header]
+      end
+    end
+
+    # Represents a table in a document
+    #
+    # Tables contain rows of cells and support various formatting options
+    # like frame, grid, column widths, and styling.
+    #
+    # @example Creating a simple table
+    #   table = CoreModel::Table.new(
+    #     title: "Data Table",
+    #     rows: [
+    #       CoreModel::TableRow.new(
+    #         cells: [
+    #           CoreModel::TableCell.new(content: "Header 1", header: true),
+    #           CoreModel::TableCell.new(content: "Header 2", header: true)
+    #         ],
+    #         header: true
+    #       ),
+    #       CoreModel::TableRow.new(
+    #         cells: [
+    #           CoreModel::TableCell.new(content: "Cell 1"),
+    #           CoreModel::TableCell.new(content: "Cell 2")
+    #         ]
+    #       )
+    #     ]
+    #   )
+    #
+    # @example Creating a table with column specifications
+    #   table = CoreModel::Table.new(
+    #     cols: ["1", "2", "3"],  # relative widths
+    #     col_alignments: ["left", "center", "right"],
+    #     col_styles: [nil, "emphasis", "monospace"],
+    #     rows: [...]
+    #   )
+    class Table < Base
+      # @!attribute rows
+      #   @return [Array<TableRow>] collection of table rows
+      attribute :rows, TableRow, collection: true
+
+      # @!attribute grid
+      #   @return [String, nil] table grid style ('all', 'cols', 'rows', 'none')
+      #   @note Not yet wired by any transformer; reserved for future use
+      attribute :grid, :string
+
+      # @!attribute width
+      #   @return [String, nil] table width (e.g., '100%', '500px')
+      attribute :width, :string
+
+      # @!attribute cols
+      #   @return [Array<String>, nil] column width specifications (e.g., ["1", "2", "3"])
+      attribute :cols, :string, collection: true
+
+      private
+
+      def comparable_attributes
+        super + %i[rows grid width cols]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/term.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents a definition term in a document
+    #
+    # Terms are used in definition lists, glossaries, and terminology
+    # sections. They can have various types (acronym, symbol, preferred, etc.)
+    # and support multi-language content.
+    #
+    # @example Creating a simple term
+    #   term = CoreModel::Term.new(
+    #     text: "API",
+    #     type: "acronym",
+    #     definition: "Application Programming Interface"
+    #   )
+    #
+    # @example Creating a multi-language term
+    #   term = CoreModel::Term.new(
+    #     text: "computer",
+    #     type: "preferred",
+    #     lang: "en",
+    #     definition: "An electronic device for processing data"
+    #   )
+    class Term < Base
+      # @!attribute text
+      #   @return [String, nil] the term text
+      attribute :text, :string
+
+      # @!attribute type
+      #   @return [String, nil] term type ('acronym', 'symbol', 'preferred', 'admitted', 'deprecated')
+      attribute :type, :string
+
+      # @!attribute lang
+      #   @return [String] language code (default: 'en')
+      attribute :lang, :string, default: -> { 'en' }
+
+      # @!attribute definition
+      #   @return [String, nil] definition of the term
+      attribute :definition, :string
+
+      # @!attribute source
+      #   @return [String, nil] source reference for the term
+      attribute :source, :string
+
+      private
+
+      def comparable_attributes
+        super + %i[text type lang definition]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/text_content.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Wrapper for plain-text strings in mixed-content children arrays.
+    #
+    # Enables every child in a children collection to be a typed Base
+    # instance, so that children can be declared as
+    #   attribute :children, Base, collection: true
+    # matching StructuralElement's proven pattern.
+    #
+    # @example
+    #   TextContent.new(text: "Hello, world")
+    class TextContent < Base
+      attribute :text, :string
+
+      def to_s
+        text.to_s
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/toc.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents a Table of Contents in a document
+    #
+    # TOC provides hierarchical navigation structure for documents.
+    # It can be auto-generated from document sections or manually defined.
+    #
+    # @example Creating a TOC from sections
+    #   toc = CoreModel::Toc.new(
+    #     entries: [
+    #       CoreModel::TocEntry.new(
+    #         id: 'section-1',
+    #         title: 'Section 1',
+    #         level: 1,
+    #         children: [
+    #           CoreModel::TocEntry.new(id: 'subsection', title: 'Subsection', level: 2)
+    #         ]
+    #       )
+    #     ]
+    #   )
+    #
+    # @example Creating a TOC with configuration
+    #   toc = CoreModel::Toc.new(
+    #     entries: entries,
+    #     min_level: 1,
+    #     max_level: 3,
+    #     numbered: true
+    #   )
+    class Toc < Base
+      # @!attribute entries
+      #   @return [Array<TocEntry>] the TOC entries
+      attribute :entries, :string, collection: true
+
+      # @!attribute min_level
+      #   @return [Integer] minimum heading level to include (default: 1)
+      attribute :min_level, :integer, default: -> { 1 }
+
+      # @!attribute max_level
+      #   @return [Integer] maximum heading level to include (default: 6)
+      attribute :max_level, :integer, default: -> { 6 }
+
+      # @!attribute numbered
+      #   @return [Boolean] whether to include section numbers
+      attribute :numbered, :boolean, default: -> { false }
+
+      # @!attribute styled
+      #   @return [Boolean] whether to include styling
+      attribute :styled, :boolean, default: -> { false }
+
+      private
+
+      def comparable_attributes
+        super + %i[entries min_level max_level numbered styled]
+      end
+    end
+
+    # Represents a single entry in a Table of Contents
+    #
+    # Each entry represents a heading/section and can contain
+    # nested child entries.
+    class TocEntry < Base
+      # @!attribute id
+      #   @return [String, nil] the anchor ID for linking
+      attribute :id, :string
+
+      # @!attribute title
+      #   @return [String, nil] the heading text
+      attribute :title, :string
+
+      # @!attribute level
+      #   @return [Integer] the heading level (1-6)
+      attribute :level, :integer, default: -> { 1 }
+
+      # @!attribute number
+      #   @return [String, nil] the section number (e.g., "1.2.3")
+      attribute :number, :string
+
+      # @!attribute children
+      #   @return [Array<TocEntry>] nested child entries
+      attribute :children, :string, collection: true
+
+      private
+
+      def comparable_attributes
+        super + %i[id title level number children]
+      end
+    end
+
+    # Re-open Toc to properly type entries now that TocEntry is defined
+    class Toc
+      remove_method :entries if method_defined?(:entries)
+      remove_method :entries= if method_defined?(:entries=)
+      attribute :entries, TocEntry, collection: true
+    end
+
+    # Re-open TocEntry to properly type children now that TocEntry is defined
+    class TocEntry
+      remove_method :children if method_defined?(:children)
+      remove_method :children= if method_defined?(:children=)
+      attribute :children, TocEntry, collection: true
+    end
+  end
+end

data/lib/coradoc/core_model/toc_generator.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Table of Contents Generator for CoreModel documents
+    #
+    # Generates a Toc model from CoreModel::StructuralElement documents.
+    # Supports configurable level ranges and section numbering.
+    #
+    # @example Basic usage
+    #   doc = Coradoc::CoreModel::StructuralElement.new(
+    #     element_type: 'document',
+    #     children: [section1, section2]
+    #   )
+    #   toc = CoreModel::TocGenerator.generate(doc)
+    #
+    # @example With options
+    #   toc = CoreModel::TocGenerator.generate(doc,
+    #     min_level: 2,
+    #     max_level: 4,
+    #     numbered: true
+    #   )
+    #
+    class TocGenerator
+      # Default options for TOC generation
+      DEFAULT_OPTIONS = {
+        min_level: 1,
+        max_level: 6,
+        numbered: false,
+        styled: false
+      }.freeze
+
+      class << self
+        # Generate a Toc from a CoreModel document
+        #
+        # @param document [CoreModel::StructuralElement] The document to process
+        # @param options [Hash] Generation options
+        # @option options [Integer] :min_level (1) Minimum heading level
+        # @option options [Integer] :max_level (6) Maximum heading level
+        # @option options [Boolean] :numbered (false) Add section numbers
+        # @option options [Boolean] :styled (false) Add styling
+        # @return [CoreModel::Toc, nil] The generated TOC or nil if no sections
+        def generate(document, options = {})
+          opts = DEFAULT_OPTIONS.merge(options)
+          entries = extract_toc_entries(document, opts)
+
+          return nil if entries.empty?
+
+          CoreModel::Toc.new(
+            entries: entries,
+            min_level: opts[:min_level],
+            max_level: opts[:max_level],
+            numbered: opts[:numbered],
+            styled: opts[:styled]
+          )
+        end
+
+        private
+
+        # Extract TOC entries from a document
+        def extract_toc_entries(document, options)
+          sections = find_sections(document, options[:min_level], options[:max_level])
+          return [] if sections.empty?
+
+          # Track section numbers
+          counters = {}
+
+          build_entries(sections, options, counters)
+        end
+
+        # Find all sections in the document within level range
+        def find_sections(element, min_level, max_level)
+          sections = []
+          return sections unless element.is_a?(CoreModel::StructuralElement)
+
+          Array(element.children).each do |child|
+            next unless child.is_a?(CoreModel::StructuralElement)
+
+            if child.section?
+              level = child.heading_level
+              sections << { element: child, level: level } if level >= min_level && level <= max_level
+
+              # Also search nested sections
+            else
+              # Search children for sections
+            end
+            sections.concat(find_sections(child, min_level, max_level))
+          end
+
+          sections
+        end
+
+        # Build hierarchical TOC entries from flat section list
+        def build_entries(sections, options, counters)
+          return [] if sections.empty?
+
+          entries = []
+          options[:min_level]
+
+          # Stack for tracking parent entries at each level
+          stack = { options[:min_level] - 1 => nil }
+
+          sections.each do |section_info|
+            element = section_info[:element]
+            level = section_info[:level]
+
+            # Update counters
+            counters[level] ||= 0
+            counters[level] += 1
+            # Reset deeper level counters
+            (level + 1..6).each { |l| counters[l] = 0 }
+
+            # Generate number if needed
+            number = (generate_number(counters, options[:min_level], level) if options[:numbered])
+
+            entry = CoreModel::TocEntry.new(
+              id: element.id,
+              title: element.title,
+              level: level,
+              number: number,
+              children: []
+            )
+
+            # Find parent at previous level
+            parent_level = level - 1
+            parent_level -= 1 while parent_level >= options[:min_level] - 1 && !stack.key?(parent_level)
+
+            if stack[parent_level]
+              stack[parent_level].children << entry
+            else
+              entries << entry
+            end
+
+            # Add to stack for potential children
+            stack[level] = entry
+          end
+
+          entries
+        end
+
+        def generate_number(counters, min_level, current_level)
+          parts = []
+          (min_level..current_level).each do |l|
+            parts << counters[l] if counters[l]&.positive?
+          end
+          parts.join('.')
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/verse_block.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Verse block — a block for verse/poetry with optional attribution
+    class VerseBlock < Block
+      def self.semantic_type = :verse
+
+      attribute :attribution, :string
+    end
+  end
+end

data/lib/coradoc/core_model.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # CoreModel namespace for format-agnostic document models
+  #
+  # CoreModel provides the canonical document representation used as the hub
+  # in the hub-and-spoke architecture. Format-specific builders live in their
+  # respective format gems (e.g., Coradoc::AsciiDoc::Builder).
+  #
+  # @see CoreModel::Base for base functionality
+  module CoreModel
+    # Autoload submodules lazily using relative paths
+    autoload :Base, "#{__dir__}/core_model/base"
+    autoload :ChildrenContent, "#{__dir__}/core_model/children_content"
+    autoload :Block, "#{__dir__}/core_model/block"
+    autoload :AnnotationBlock, "#{__dir__}/core_model/annotation_block"
+    autoload :ListBlock, "#{__dir__}/core_model/list_block"
+    autoload :ListItem, "#{__dir__}/core_model/list_item"
+    autoload :InlineElement, "#{__dir__}/core_model/inline_element"
+    autoload :BoldElement, "#{__dir__}/core_model/inline_element"
+    autoload :ItalicElement, "#{__dir__}/core_model/inline_element"
+    autoload :MonospaceElement, "#{__dir__}/core_model/inline_element"
+    autoload :UnderlineElement, "#{__dir__}/core_model/inline_element"
+    autoload :StrikethroughElement, "#{__dir__}/core_model/inline_element"
+    autoload :SubscriptElement, "#{__dir__}/core_model/inline_element"
+    autoload :SuperscriptElement, "#{__dir__}/core_model/inline_element"
+    autoload :HighlightElement, "#{__dir__}/core_model/inline_element"
+    autoload :LinkElement, "#{__dir__}/core_model/inline_element"
+    autoload :CrossReferenceElement, "#{__dir__}/core_model/inline_element"
+    autoload :StemElement, "#{__dir__}/core_model/inline_element"
+    autoload :FootnoteElement, "#{__dir__}/core_model/inline_element"
+    autoload :HardLineBreakElement, "#{__dir__}/core_model/inline_element"
+    autoload :TextElement, "#{__dir__}/core_model/inline_element"
+    autoload :SpanElement, "#{__dir__}/core_model/inline_element"
+    autoload :TermElement, "#{__dir__}/core_model/inline_element"
+    autoload :LineBreakElement, "#{__dir__}/core_model/inline_element"
+    autoload :StructuralElement, "#{__dir__}/core_model/structural_element"
+    autoload :DocumentElement, "#{__dir__}/core_model/structural_element"
+    autoload :SectionElement, "#{__dir__}/core_model/structural_element"
+    autoload :PreambleElement, "#{__dir__}/core_model/structural_element"
+    autoload :HeaderElement, "#{__dir__}/core_model/structural_element"
+
+    autoload :Table, "#{__dir__}/core_model/table"
+    autoload :TableCell, "#{__dir__}/core_model/table"
+    autoload :TableRow, "#{__dir__}/core_model/table"
+    autoload :TextContent, "#{__dir__}/core_model/text_content"
+    autoload :Image, "#{__dir__}/core_model/image"
+    autoload :Term, "#{__dir__}/core_model/term"
+    autoload :ElementAttribute, "#{__dir__}/core_model/element_attribute"
+    autoload :Metadata, "#{__dir__}/core_model/metadata"
+    autoload :MetadataEntry, "#{__dir__}/core_model/metadata"
+    autoload :Footnote, "#{__dir__}/core_model/footnote"
+    autoload :FootnoteReference, "#{__dir__}/core_model/footnote"
+    autoload :Abbreviation, "#{__dir__}/core_model/footnote"
+    autoload :DefinitionItem, "#{__dir__}/core_model/definition_item"
+    autoload :DefinitionList, "#{__dir__}/core_model/definition_list"
+    autoload :Toc, "#{__dir__}/core_model/toc"
+    autoload :TocEntry, "#{__dir__}/core_model/toc"
+    autoload :TocGenerator, "#{__dir__}/core_model/toc_generator"
+    autoload :Bibliography, "#{__dir__}/core_model/bibliography"
+    autoload :BibliographyEntry, "#{__dir__}/core_model/bibliography_entry"
+    autoload :SourceBlock, "#{__dir__}/core_model/source_block"
+    autoload :ExampleBlock, "#{__dir__}/core_model/example_block"
+    autoload :QuoteBlock, "#{__dir__}/core_model/quote_block"
+    autoload :SidebarBlock, "#{__dir__}/core_model/sidebar_block"
+    autoload :LiteralBlock, "#{__dir__}/core_model/literal_block"
+    autoload :PassBlock, "#{__dir__}/core_model/pass_block"
+    autoload :ListingBlock, "#{__dir__}/core_model/listing_block"
+    autoload :OpenBlock, "#{__dir__}/core_model/open_block"
+    autoload :VerseBlock, "#{__dir__}/core_model/verse_block"
+    autoload :ReviewerBlock, "#{__dir__}/core_model/reviewer_block"
+    autoload :ParagraphBlock, "#{__dir__}/core_model/paragraph_block"
+    autoload :CommentBlock, "#{__dir__}/core_model/comment_block"
+    autoload :HorizontalRuleBlock, "#{__dir__}/core_model/horizontal_rule_block"
+    autoload :IdGenerator, "#{__dir__}/core_model/id_generator"
+  end
+end