coradoc 1.1.7 → 2.0.15

data/lib/coradoc/core_model/bibliography.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Bibliography section in a document.
+    #
+    # Bibliography sections contain lists of references cited in the document.
+    #
+    # @!attribute [r] id
+    #   @return [String, nil] Optional identifier for the bibliography
+    #
+    # @!attribute [r] title
+    #   @return [String, nil] Bibliography section title
+    #
+    # @!attribute [r] level
+    #   @return [Integer, nil] Section level
+    #
+    # @!attribute [r] entries
+    #   @return [Array<Coradoc::CoreModel::BibliographyEntry>] Bibliography entries
+    #
+    # @example Create a bibliography section
+    #   bib = Coradoc::CoreModel::Bibliography.new(
+    #     id: "norm-refs",
+    #     title: "Normative references",
+    #     entries: [
+    #       Coradoc::CoreModel::BibliographyEntry.new(
+    #         anchor_name: "ISO712",
+    #         document_id: "ISO 712",
+    #         ref_text: "Cereals and cereal products..."
+    #       )
+    #     ]
+    #   )
+    #
+    class Bibliography < Base
+      attribute :id, :string
+      attribute :title, :string
+      attribute :level, :integer
+      attribute :entries, Coradoc::CoreModel::BibliographyEntry, collection: true
+    end
+  end
+end

data/lib/coradoc/core_model/bibliography_entry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Individual bibliography entry (reference).
+    #
+    # Bibliography entries represent single references within a bibliography,
+    # with anchor names for citation linking.
+    #
+    # @!attribute [r] anchor_name
+    #   @return [String, nil] The anchor name for citing this entry (e.g., "ISO712")
+    #
+    # @!attribute [r] document_id
+    #   @return [String, nil] The document identifier (e.g., "ISO 712")
+    #
+    # @!attribute [r] ref_text
+    #   @return [String, nil] The reference text/citation description
+    #
+    # @!attribute [r] url
+    #   @return [String, nil] Optional URL for the reference
+    #
+    # @example Create a bibliography entry
+    #   entry = Coradoc::CoreModel::BibliographyEntry.new(
+    #     anchor_name: "ISO712",
+    #     document_id: "ISO 712",
+    #     ref_text: "Cereals and cereal products. Determination of moisture content."
+    #   )
+    #
+    class BibliographyEntry < Base
+      attribute :anchor_name, :string
+      attribute :document_id, :string
+      attribute :ref_text, :string
+      attribute :url, :string
+
+      # Returns a formatted display string combining label and reference text.
+      #
+      # Uses document_id or anchor_name as the label, falling back to ref_text
+      # alone when no label is available.
+      #
+      # @return [String] formatted citation text
+      def display_text
+        label = document_id || anchor_name || ''
+        ref = ref_text || ''
+        label.empty? ? ref : "#{label}: #{ref}"
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/block.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Generic block model
+    #
+    # Represents all block-level elements in a format-neutral way.
+    # Typed subclasses (SourceBlock, QuoteBlock, etc.) express their
+    # semantic identity via the class hierarchy — the class IS the type.
+    # Generic Block instances use block_semantic_type for typing.
+    class Block < Base
+      attribute :children, Base, collection: true
+
+      include ChildrenContent
+
+      class << self
+        def semantic_type
+          nil
+        end
+      end
+
+      def resolve_semantic_type
+        self.class.semantic_type || block_semantic_type&.to_sym
+      end
+
+      # Derived element_type string for backward compatibility.
+      # Returns the semantic type as a string, derived from the class
+      # or block_semantic_type.
+      def element_type
+        resolve_semantic_type&.to_s
+      end
+
+      # @!attribute block_semantic_type
+      #   @return [String, nil] semantic type for generic Block instances.
+      #     Typed subclasses should not override this — use the class instead.
+      attribute :block_semantic_type, :string
+
+      # @!attribute delimiter_type
+      #   @return [String, nil] raw delimiter for round-trip fidelity.
+      #     Format-specific; CoreModel does NOT derive semantics from this.
+      attribute :delimiter_type, :string
+
+      # @!attribute content
+      #   @return [String, nil] the block's text content (simple string)
+      #     For mixed content with inline elements, use children instead.
+      attribute :content, :string
+
+      # @!attribute lines
+      #   @return [Array<String>, nil] individual lines of content
+      attribute :lines, :string, collection: true
+
+      # @!attribute language
+      #   @return [String, nil] language identifier for source code blocks
+      attribute :language, :string
+
+      private
+
+      def comparable_attributes
+        super + %i[block_semantic_type content]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/children_content.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Shared helpers for models that carry mixed-content children
+    # (TextContent + InlineElement + Block instances) alongside a string
+    # content attribute.
+    #
+    # Included by Block, ListItem, TableCell, and InlineElement.
+    # The children attribute is declared as
+    #   attribute :children, Base, collection: true
+    # on each including class. This module overrides the setter to
+    # auto-wrap raw strings as TextContent, keeping all callers simple.
+    module ChildrenContent
+      # Override the children= setter to auto-wrap strings as TextContent.
+      # This is defined via define_method so it always overrides the
+      # lutaml-generated setter, regardless of include order.
+      def self.included(base)
+        super
+
+        base.define_method(:children=) do |value|
+          wrapped = Array(value).map do |item|
+            next nil if item.nil?
+            next item if item.is_a?(CoreModel::Base)
+
+            CoreModel::TextContent.new(text: item.to_s)
+          end.compact
+          instance_variable_set(:@children, wrapped)
+        end
+      end
+
+      # Get content for rendering, preferring children over content.
+      # When children are all TextContent (plain text), use the content
+      # attribute instead since it already has proper spacing between lines.
+      def renderable_content
+        return content if children.nil? || children.none?
+        return content if content && children.all?(TextContent)
+
+        children
+      end
+
+      # Flatten renderable_content to a single plain-text string.
+      def flat_text
+        rc = renderable_content
+        case rc
+        when String then rc
+        when Array then rc.map { |c| c.is_a?(TextContent) ? c.text : c.content.to_s }.join
+        else rc.to_s
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/comment_block.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Comment block — editorial or hidden comments
+    class CommentBlock < Block
+      def self.semantic_type
+        :comment
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/definition_item.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    class DefinitionItem < Base
+      attribute :term, :string
+      attribute :definitions, :string, collection: true
+
+      def initialize(args = {})
+        @term_children = args.delete(:term_children) || []
+        @definition_children = args.delete(:definition_children) || []
+        super(args)
+      end
+
+      attr_reader :term_children, :definition_children
+
+      def term_children=(value)
+        @term_children = value || []
+      end
+
+      def definition_children=(value)
+        @definition_children = value || []
+      end
+
+      def term_renderable
+        return term if term_children.nil? || term_children.none?
+        return term if term && term_children.all?(String)
+
+        term_children
+      end
+
+      def definition_renderable
+        return definitions if definition_children.nil? || definition_children.none?
+        return definitions if definition_children.all?(String)
+
+        definition_children
+      end
+
+      private
+
+      def comparable_attributes
+        super + %i[term definitions term_children definition_children]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/definition_list.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents a definition list
+    #
+    # DefinitionList contains terms and their definitions.
+    #
+    # @example Creating a definition list
+    #   list = CoreModel::DefinitionList.new(
+    #     items: [
+    #       DefinitionItem.new(term: "API", definitions: ["Application Programming Interface"]),
+    #       DefinitionItem.new(term: "REST", definitions: ["Representational State Transfer"])
+    #     ]
+    #   )
+    class DefinitionList < Base
+      # @!attribute items
+      #   @return [Array<DefinitionItem>] the definition items
+      attribute :items, DefinitionItem, collection: true
+
+      private
+
+      def comparable_attributes
+        super + %i[items]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/element_attribute.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents a single attribute (key-value pair) on an element
+    #
+    # @example
+    #   attr = ElementAttribute.new(name: "role", value: "note")
+    class ElementAttribute < Base
+      attribute :name, :string
+      attribute :value, :string
+
+      # Convert to hash representation
+      # @return [Hash] Single key-value pair
+      def to_h
+        { name => value }
+      end
+
+      # Convert to string representation (e.g., for serialization)
+      # @return [String] Attribute in name="value" format
+      def to_s
+        %("#{name}="#{value}"")
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/example_block.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Example block — a delimited block for examples
+    class ExampleBlock < Block
+      def self.semantic_type
+        :example
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/footnote.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents a footnote definition in a document
+    #
+    # Footnotes are used for auxiliary information, citations, or
+    # explanatory notes that appear at the bottom of a page or
+    # end of a document.
+    #
+    # @example Creating a simple footnote
+    #   footnote = CoreModel::Footnote.new(
+    #     id: "fn1",
+    #     content: "This is a footnote explanation."
+    #   )
+    #
+    # @example Creating a footnote with backlink
+    #   footnote = CoreModel::Footnote.new(
+    #     id: "cite1",
+    #     content: "Smith, J. (2024). The Reference.",
+    #     backlink: true
+    #   )
+    class Footnote < Base
+      # @!attribute id
+      #   @return [String, nil] the footnote identifier (e.g., "1", "fn1")
+      attribute :id, :string
+
+      # @!attribute content
+      #   @return [String, nil] the footnote content
+      attribute :content, :string
+
+      # @!attribute inline_content
+      #   @return [Array<String>, nil] inline content elements
+      attribute :inline_content, :string, collection: true
+
+      # @!attribute backlink
+      #   @return [Boolean] whether to include backlink to reference
+      attribute :backlink, :boolean, default: -> { true }
+
+      private
+
+      def comparable_attributes
+        super + %i[id content backlink]
+      end
+    end
+
+    # Represents an inline footnote reference
+    #
+    # FootnoteReference links to a Footnote definition within document text.
+    #
+    # @example Creating a footnote reference
+    #   ref = CoreModel::FootnoteReference.new(id: "fn1")
+    #   # Renders as: [^fn1] in Markdown, <sup>1</sup> in HTML
+    class FootnoteReference < Base
+      # @!attribute id
+      #   @return [String, nil] the footnote identifier being referenced
+      attribute :id, :string
+
+      private
+
+      def comparable_attributes
+        super + %i[id]
+      end
+    end
+
+    # Represents an abbreviation definition in a document
+    #
+    # Abbreviations define the expansion of shortened terms.
+    # They are typically rendered with the full definition on first use.
+    #
+    # @example Creating an abbreviation
+    #   abbr = CoreModel::Abbreviation.new(
+    #     term: "API",
+    #     definition: "Application Programming Interface"
+    #   )
+    class Abbreviation < Base
+      # @!attribute term
+      #   @return [String, nil] the abbreviated term
+      attribute :term, :string
+
+      # @!attribute definition
+      #   @return [String, nil] the full definition/expansion
+      attribute :definition, :string
+
+      private
+
+      def comparable_attributes
+        super + %i[term definition]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/horizontal_rule_block.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Horizontal rule — a thematic break between sections
+    class HorizontalRuleBlock < Block
+      def self.semantic_type
+        :horizontal_rule
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/id_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    module IdGenerator
+      def self.generate_from_title(title, parent_id: nil)
+        return nil if title.nil? || title.to_s.strip.empty?
+
+        suffix = title.to_s.downcase
+                      .gsub(/[^a-z0-9\s]/, '')
+                      .gsub(/\s+/, '_')
+                      .gsub(/^_+|_+$/, '')
+
+        return "_#{suffix}" if parent_id.nil? || parent_id.to_s.strip.empty?
+
+        "#{parent_id}_#{suffix}"
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/image.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents an image in a document
+    #
+    # Images can be block-level (standalone) or inline. They support
+    # various attributes like alt text, dimensions, and linking.
+    #
+    # @example Creating a block image
+    #   image = CoreModel::Image.new(
+    #     src: "images/diagram.png",
+    #     alt: "System Architecture",
+    #     caption: "Figure 1: System Overview",
+    #     width: "800px"
+    #   )
+    #
+    # @example Creating an inline image
+    #   icon = CoreModel::Image.new(
+    #     src: "icons/warning.png",
+    #     alt: "Warning",
+    #     inline: true
+    #   )
+    class Image < Base
+      # @!attribute src
+      #   @return [String, nil] source URL or path to the image
+      attribute :src, :string
+
+      # @!attribute alt
+      #   @return [String, nil] alternative text for accessibility
+      attribute :alt, :string
+
+      # @!attribute caption
+      #   @return [String, nil] caption text for the image
+      attribute :caption, :string
+
+      # @!attribute width
+      #   @return [String, nil] image width (e.g., '100%', '500px')
+      attribute :width, :string
+
+      # @!attribute height
+      #   @return [String, nil] image height (e.g., '300px', 'auto')
+      attribute :height, :string
+
+      # @!attribute link
+      #   @return [String, nil] URL to link to when image is clicked
+      #   @note Not yet wired by any transformer; reserved for future use
+      attribute :link, :string
+
+      # @!attribute inline
+      #   @return [Boolean] whether this is an inline image
+      attribute :inline, :boolean, default: -> { false }
+
+      # @!attribute float
+      #   @return [String, nil] float position ('left', 'right')
+      #   @note Not yet wired by any transformer; reserved for future use
+      attribute :float, :string
+
+      private
+
+      def comparable_attributes
+        super + %i[src alt caption width height link inline]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/inline_element.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Generic inline formatting element
+    #
+    # Typed subclasses (BoldElement, ItalicElement, etc.) express their
+    # format identity via the class hierarchy — the class IS the format type.
+    # Generic InlineElement instances use the format_type attribute for typing.
+    class InlineElement < Base
+      attribute :children, Base, collection: true
+
+      include ChildrenContent
+
+      def self.format_type
+        nil
+      end
+
+      def self.format_type_class(type)
+        FORMAT_TYPE_CLASS_MAP[type] || InlineElement
+      end
+
+      def resolve_format_type
+        self.class.format_type || format_type
+      end
+
+      FORMAT_TYPES = %w[
+        bold italic monospace underline strikethrough
+        subscript superscript highlight
+        link xref stem footnote
+        hard_line_break text span term
+        line_break quotation
+      ].freeze
+
+      attribute :format_type, :string
+      attribute :content, :string
+      attribute :nested_elements, InlineElement, collection: true
+      attribute :target, :string
+      attribute :stem_type, :string
+
+      private
+
+      def comparable_attributes
+        %i[format_type content nested_elements stem_type]
+      end
+    end
+
+    # Typed InlineElement subclasses
+
+    class BoldElement < InlineElement
+      def self.format_type
+        'bold'
+      end
+    end
+
+    class ItalicElement < InlineElement
+      def self.format_type
+        'italic'
+      end
+    end
+
+    class MonospaceElement < InlineElement
+      def self.format_type
+        'monospace'
+      end
+    end
+
+    class UnderlineElement < InlineElement
+      def self.format_type
+        'underline'
+      end
+    end
+
+    class StrikethroughElement < InlineElement
+      def self.format_type
+        'strikethrough'
+      end
+    end
+
+    class SubscriptElement < InlineElement
+      def self.format_type
+        'subscript'
+      end
+    end
+
+    class SuperscriptElement < InlineElement
+      def self.format_type
+        'superscript'
+      end
+    end
+
+    class HighlightElement < InlineElement
+      def self.format_type
+        'highlight'
+      end
+    end
+
+    class LinkElement < InlineElement
+      def self.format_type
+        'link'
+      end
+    end
+
+    class CrossReferenceElement < InlineElement
+      def self.format_type
+        'xref'
+      end
+    end
+
+    class StemElement < InlineElement
+      def self.format_type
+        'stem'
+      end
+    end
+
+    class FootnoteElement < InlineElement
+      def self.format_type
+        'footnote'
+      end
+    end
+
+    class HardLineBreakElement < InlineElement
+      def self.format_type
+        'hard_line_break'
+      end
+    end
+
+    class TextElement < InlineElement
+      def self.format_type
+        'text'
+      end
+    end
+
+    class SpanElement < InlineElement
+      def self.format_type
+        'span'
+      end
+    end
+
+    class TermElement < InlineElement
+      def self.format_type
+        'term'
+      end
+    end
+
+    class LineBreakElement < InlineElement
+      def self.format_type
+        'line_break'
+      end
+    end
+
+    FORMAT_TYPE_CLASS_MAP = {
+      'bold' => BoldElement,
+      'italic' => ItalicElement,
+      'monospace' => MonospaceElement,
+      'underline' => UnderlineElement,
+      'strikethrough' => StrikethroughElement,
+      'subscript' => SubscriptElement,
+      'superscript' => SuperscriptElement,
+      'highlight' => HighlightElement,
+      'link' => LinkElement,
+      'xref' => CrossReferenceElement,
+      'stem' => StemElement,
+      'footnote' => FootnoteElement,
+      'hard_line_break' => HardLineBreakElement,
+      'text' => TextElement,
+      'span' => SpanElement,
+      'term' => TermElement,
+      'line_break' => LineBreakElement
+    }.freeze
+  end
+end