coradoc-adoc 2.0.21 → 2.0.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c4b5749f4fd1a691eb76fe9f7848b1d4bc2cd2e43cd2ee0a5f1afdcb697459c
-  data.tar.gz: 90e6bf66da9a7c4dba7c7eafbdabf378259e4b9792a93d4c88209d52bd991876
+  metadata.gz: 69bc04902f8020decc17928a5397de2876f060ed8ee36de95f0920ba6312e8b4
+  data.tar.gz: ca56574d1b78863a574551732397ff65944f2b012781def3bb4ea4bcf8b0aaf1
 SHA512:
-  metadata.gz: e421d05a3a2c43387471224818a5261229478c1539ddade33a30957be8d7fb0775c9b0bb95b59afa32cb4e84f0adab07b62164113a521635fd5e70cdbe66ecec
-  data.tar.gz: dd6c2ea15fcb4c3e521a929006ba2e7ebbff5f6548902a2d7947cdac04a9005a792a9ae4fb07d68f53e30c844de9cbd00bd62a0fa034fa9f9c298209fe50ec7e
+  metadata.gz: 708cf53d7a9c6de58e15aac99a1e77343e004b7d014697335cd91f96143584b0701235e84030948a5ab6a09eba8612a361b215b1be9707ca07943d3f7179ad09
+  data.tar.gz: ff60d697d4fff0ec229ca5b597f1fe2f37d34129bff79f10276b72824ecd418f770d9229800dee6f143f95345af0c1432aceb100385b6c578fd08abb01a3767a

data/lib/coradoc/asciidoc/model/attribute_list.rb

@@ -87,6 +87,20 @@ module Coradoc
           )
         end
 
+        # Remove the first named attribute matching `name` and return its
+        # scalar value (or nil if absent). Used by promoters that lift a
+        # named attr out of the residual bag into a typed field.
+        # @param name [String, Symbol]
+        # @return [String, nil]
+        def delete_named(name)
+          name_str = name.to_s
+          idx = named.index { |n| n.name.to_s == name_str }
+          return nil unless idx
+
+          removed = @named.delete_at(idx)
+          removed.value.first&.to_s
+        end
+
         # Validate named attributes against validators
         #
         # @param validators [Hash] Hash of name => matcher pairs
@@ -209,12 +223,24 @@ module Coradoc
           positional.empty? && named.empty?
         end
 
-        # Get a named attribute value by name
+        # Get the scalar value of the first named attribute matching `name`.
+        # Returns the first element of the underlying multi-value array, or
+        # nil if the name is absent. Use {#fetch_all} to retrieve the full
+        # multi-value array.
         # @param name [String, Symbol] The attribute name
-        # @return [Object, nil] The attribute value or nil if not found
+        # @return [String, nil]
         def [](name)
           name_str = name.to_s
-          named.find { |n| n.name.to_s == name_str }&.value
+          named.find { |n| n.name.to_s == name_str }&.value&.first&.to_s
+        end
+
+        # Get the full multi-value array for a named attribute.
+        # @param name [String, Symbol]
+        # @return [Array<String>] (empty when absent)
+        def fetch_all(name)
+          name_str = name.to_s
+          found = named.find { |n| n.name.to_s == name_str }
+          found ? found.value : []
         end
 
         # Get a named attribute value with default
@@ -222,7 +248,8 @@ module Coradoc
         # @param default [Object] The default value if not found
         # @return [Object] The attribute value or default
         def fetch(name, default = nil)
-          self[name] || default
+          value = self[name]
+          value.nil? ? default : value
         end
       end
     end

data/lib/coradoc/asciidoc/model/image/attribute_extractor.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      module Image
+        # Pure-function promoter: lifts semantically meaningful slots out of
+        # a generic {Model::AttributeList} into the typed fields declared on
+        # an image class, and the inverse — composes a serialisable
+        # AttributeList from typed fields + residual.
+        #
+        # The promotion map is owned by the target class itself, via
+        # +promoted_positional+ and +promoted_named+. This module is the
+        # single place that consumes those declarations, so adding a new
+        # promoted field is a one-line class-level change (OCP).
+        #
+        # Positional slots are consumed by index; named slots are removed
+        # from the residual list so they don't appear twice. The residual
+        # list preserves order and identity for everything that wasn't
+        # promoted (e.g. +scaledwidth+, +pdfwidth+, +opts+).
+        #
+        # @example Extract for an inline image
+        #   list = Model::AttributeList.new
+        #   list.add_positional('Alt', 'Thumb')
+        #   list.add_named('width', '640')
+        #   extracted, residual = AttributeExtractor.call(list, InlineImage)
+        #   extracted  # => { alt: 'Alt', role: 'Thumb', width: '640' }
+        #   residual.positional   # => []
+        #   residual.named         # => []
+        #
+        # @example Compose for serialisation
+        #   AttributeExtractor.compose(image)
+        #   # => Model::AttributeList with positional [alt, role] + named
+        #   #    [width, height, link] + residual attrs, in declaration order
+        #
+        module AttributeExtractor
+          module_function
+
+          # @param attribute_list [Model::AttributeList, nil]
+          # @param target_class [Class] an Image::Core subclass
+          # @return [Array<(Hash{Symbol=>String}, Model::AttributeList)>]
+          #   a tuple of promoted typed values and the residual list
+          def call(attribute_list, target_class)
+            source = attribute_list || Model::AttributeList.new
+            residual = Model::AttributeList.new
+            extracted = {}
+
+            promote_positional(extracted, residual, source, target_class)
+            promote_named(extracted, residual, source, target_class)
+
+            [extracted, residual]
+          end
+
+          # Inverse of {call}: rebuild a serialisable AttributeList from a
+          # model's typed fields plus its residual list. Used by the AsciiDoc
+          # image serializer so round-trips reproduce the original syntax.
+          #
+          # A field that's declared in both +promoted_positional+ and
+          # +promoted_named+ (e.g. inline image +role+) is emitted only
+          # once — via its positional slot when filled, otherwise via named.
+          # @param model [Coradoc::AsciiDoc::Model::Image::Core]
+          # @return [Model::AttributeList]
+          def compose(model)
+            composed = Model::AttributeList.new
+            filled = compose_positional(composed, model)
+            compose_named(composed, model, filled)
+            append_residual(composed, model.attributes)
+            composed
+          end
+
+          def compose_positional(composed, model)
+            filled = []
+            model.class.promoted_positional.each do |attr_name|
+              value = model.public_send(attr_name)
+              next if value.nil? || value.to_s.empty?
+
+              composed.add_positional(value.to_s)
+              filled << attr_name
+            end
+            filled
+          end
+
+          def compose_named(composed, model, filled)
+            model.class.promoted_named.each do |attr_name|
+              next if filled.include?(attr_name)
+
+              value = model.public_send(attr_name)
+              next if value.nil? || value.to_s.empty?
+
+              composed.add_named(attr_name.to_s, value.to_s)
+            end
+          end
+
+          def promote_positional(extracted, residual, source, target_class)
+            promoted = target_class.promoted_positional
+            source.positional.each_with_index do |positional_attr, index|
+              attr_name = promoted[index]
+              value = positional_attr.value
+              if attr_name && !value.to_s.empty?
+                extracted[attr_name] = value.to_s
+              else
+                residual.add_positional(value)
+              end
+            end
+          end
+
+          def promote_named(extracted, residual, source, target_class)
+            promoted_names = target_class.promoted_named.to_set(&:to_s)
+            source.named.each do |named_attr|
+              promote_one_named(extracted, residual, named_attr, promoted_names)
+            end
+          end
+
+          def promote_one_named(extracted, residual, named_attr, promoted_names)
+            name_str = named_attr.name.to_s
+            unless promoted_names.include?(name_str)
+              residual.add_named(named_attr.name, named_attr.value)
+              return
+            end
+            # Positional promotion wins: a slot already filled positionally
+            # is not overwritten by a same-named entry (rare, but possible
+            # when both `[alt, role, role=X]` are supplied).
+            key = name_str.to_sym
+            return if extracted.key?(key)
+
+            value = named_attr.value.first&.to_s
+            return if value.nil? || value.empty?
+
+            extracted[key] = value
+          end
+
+          def append_residual(composed, residual)
+            return unless residual.is_a?(Model::AttributeList)
+
+            residual.positional.each { |p| composed.add_positional(p.value) }
+            residual.named.each { |n| composed.add_named(n.name, n.value) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/image/block_image.rb

@@ -18,6 +18,14 @@ module Coradoc
                     default: lambda {
                       ::Coradoc::AsciiDoc::Model::AttributeList.new
                     }
+
+          # Block images support the legacy positional form
+          # `image::target[alt, caption, role, ...]`, so the 2nd positional
+          # is promoted to `caption` (Asciidoctor image block macro shorthand).
+          # @return [Array<Symbol>]
+          def self.promoted_positional
+            %i[alt caption]
+          end
         end
       end
     end

data/lib/coradoc/asciidoc/model/image/core.rb

@@ -9,30 +9,21 @@ module Coradoc
         # Images can be block-level (standalone paragraphs) or inline (within text).
         # This base class provides common functionality for both types.
         #
-        # @!attribute [r] id
-        #   @return [String, nil] Optional identifier for the image
+        # Typed promotion of attribute-list slots
+        # ---------------------------------------
         #
-        # @!attribute [r] title
-        #   @return [String, nil] Optional image title/alt text
-        #
-        # @!attribute [r] src
-        #   @return [String] The image source URL or path
-        #
-        # @!attribute [r] attributes
-        #   @return [Coradoc::AsciiDoc::Model::Image::Core::AttributeList] Image-specific attributes
-        #
-        # @!attribute [r] annotate_missing
-        #   @return [String, nil] Annotation text for missing images
-        #
-        # @!attribute [r] line_break
-        #   @return [String] Line break character (default: "")
-        #
-        # @!attribute [r] colons
-        #   @return [String, nil] Colon positioning for attributes
-        #
-        # @see Coradoc::AsciiDoc::Model::Image::BlockImage Block-level images
-        # @see Coradoc::AsciiDoc::Model::Image::InlineImage Inline images
+        # Semantically meaningful image attributes (`alt`, `role`, `width`,
+        # `height`, `link`) are declared as typed lutaml-model fields on
+        # `Core` itself — not as validators on a generic bag. The class-level
+        # {promoted_positional} and {promoted_named} methods are the single
+        # source of truth for which slots get lifted into typed fields and in
+        # what order; subclasses override them to reflect syntax differences
+        # (e.g. inline images treat the 2nd positional as `role`, block images
+        # do not).
         #
+        # The lift itself is performed by {AttributeExtractor}, a pure function
+        # over (AttributeList, target_class) → (extracted_hash, residual_list).
+        # Anything not promoted stays in `attributes` for round-trip fidelity.
         class Core < Coradoc::AsciiDoc::Model::Base
           # Autoload nested AttributeList class
           autoload :AttributeList, 'coradoc/asciidoc/model/image/core/attribute_list'
@@ -42,6 +33,12 @@ module Coradoc
           attribute :id, :string
           attribute :title, :string
           attribute :src, :string
+          attribute :alt, :string
+          attribute :caption, :string
+          attribute :role, :string
+          attribute :width, :string
+          attribute :height, :string
+          attribute :link, :string
           attribute :attributes,
                     Coradoc::AsciiDoc::Model::Image::Core::AttributeList,
                     default: lambda {
@@ -51,17 +48,29 @@ module Coradoc
           attribute :line_break, :string, default: -> { '' }
           attribute :colons, :string
 
-          # Aliases for common attribute accessors
           alias path src
-          alias alt title
+
+          # Positional attribute-list slots that this image class promotes to
+          # typed fields, in order. Subclasses override to reflect their
+          # syntax. Index 0 → alt for all image kinds; index 1 → role for
+          # inline images only.
+          # @return [Array<Symbol>]
+          def self.promoted_positional
+            %i[alt]
+          end
+
+          # Named attribute-list keys that this image class promotes to typed
+          # fields. The same set applies to both inline and block images.
+          # @return [Array<Symbol>]
+          def self.promoted_named
+            %i[width height link role]
+          end
 
           # Custom to_adoc implementation that uses ElementRegistry directly
           # to avoid recursion issues with image serialization.
           #
           # @return [String] AsciiDoc representation of this image
           def to_adoc
-            # Use the registered serializer rather than Coradoc::AsciiDoc::Serializer.serialize
-            # to avoid recursion
             serializer_class = Coradoc::AsciiDoc::Serializer::ElementRegistry.lookup(self.class)
             serializer_class.new.to_adoc(self)
           end

data/lib/coradoc/asciidoc/model/image/inline_image.rb

@@ -10,6 +10,13 @@ module Coradoc
           end
 
           attribute :colons, :string, default: -> { ':' }
+
+          # Inline images use the 2nd positional slot for the role, per
+          # Asciidoctor: `image:target[alt, role, width=N, ...]`.
+          # @return [Array<Symbol>]
+          def self.promoted_positional
+            %i[alt role]
+          end
         end
       end
     end

data/lib/coradoc/asciidoc/model/image.rb

@@ -8,6 +8,7 @@ module Coradoc
         autoload :Core, 'coradoc/asciidoc/model/image/core'
         autoload :InlineImage, 'coradoc/asciidoc/model/image/inline_image'
         autoload :BlockImage, 'coradoc/asciidoc/model/image/block_image'
+        autoload :AttributeExtractor, 'coradoc/asciidoc/model/image/attribute_extractor'
       end
     end
   end

data/lib/coradoc/asciidoc/parser/admonition.rb

@@ -4,13 +4,22 @@ module Coradoc
   module AsciiDoc
     module Parser
       module Admonition
+        # Match a single style name case-insensitively. Each character
+        # class `[Xx]` lets the same alternation accept +note+, +Note+,
+        # and +NOTE+ without three separate str() branches per style.
+        def case_insensitive_str(s)
+          s.chars.reduce(nil) do |acc, ch|
+            node = match("[#{ch.upcase}#{ch.downcase}]")
+            acc.nil? ? node : (acc >> node)
+          end
+        end
+
         def admonition_type
-          str('NOTE') | str('TIP') | str('EDITOR') |
-            str('IMPORTANT') | str('WARNING') | str('CAUTION') |
-            str('TODO')
-          # requires atypical syntax for access?
-          # | str('DANGER')
-          # | str('SAFETY PRECAUTION')
+          styles = Coradoc::AsciiDoc::Transform::ElementTransformers::AdmonitionStyles.all_styles
+          styles.reduce(nil) do |acc, style|
+            matcher = case_insensitive_str(style)
+            acc.nil? ? matcher : (acc | matcher)
+          end
         end
 
         def admonition_line

data/lib/coradoc/asciidoc/parser/attribute_list.rb

@@ -44,7 +44,10 @@ module Coradoc
         end
 
         def positional_value_unquoted
-          match('[^\],]').repeat(1)
+          # Exclude `=` so that `key=value` is matched by `named_attribute`
+          # rather than swallowed as a single positional token. A positional
+          # value that legitimately contains `=` must be quoted.
+          match('[^\],=]').repeat(1)
         end
 
         def positional_value_single_quote

data/lib/coradoc/asciidoc/parser/inline.rb

@@ -120,20 +120,38 @@ module Coradoc
           (str('image:').present? >> str('image:') >>
             str(':').absent? >>
             match('[A-Za-z0-9_.\\-:/&?=+,%#~;]+').repeat(1).as(:path) >>
-            (str('[') >> match('[^\\]]').repeat(1).as(:text) >> str(']')).maybe
+            attribute_list(:attribute_list).maybe
           ).as(:inline_image)
         end
 
         # Triple-plus inline passthrough: `+++raw content+++`. The content
         # passes through all substitutions verbatim. Common use is to embed
         # raw HTML in AsciiDoc documents.
-        def inline_passthrough
+        def inline_passthrough_triple_plus
           (str('+++') >>
             (str('+++').absent? >> match('[^\n]')).repeat(1).as(:raw) >>
             str('+++')
           ).as(:inline_passthrough)
         end
 
+        # `pass:[raw]` macro form. Equivalent semantic to triple-plus:
+        # the bracket payload survives all substitutions verbatim. Common
+        # use is inside monospace spans to keep characters like `<` from
+        # being re-interpreted as xref markers. The optional `subs` segment
+        # (`pass:quotes[...]`) is consumed but currently ignored — the
+        # payload is always passed through raw.
+        def inline_passthrough_macro
+          (str('pass:').present? >> str('pass:') >>
+            match('[a-zA-Z,+]').repeat(0) >>
+            str('[') >> (str(']]').absent? >> match('[^\]\n]')).repeat(1).as(:raw) >>
+            str(']')
+          ).as(:inline_passthrough)
+        end
+
+        def inline_passthrough
+          inline_passthrough_triple_plus | inline_passthrough_macro
+        end
+
         def underline
           (attribute_list >> match('\\[.underline\\]').as(:role) >>
             str('#') >>
@@ -157,10 +175,26 @@ module Coradoc
             str('link:').present? |
             str('image:').present? |
             str('+++').present? |
+            str('pass:').present? |
             term_type.present? |
             str('footnote').present? |
             stem_type.present? |
-            str('\\<<').present?
+            str('\\<<').present? |
+            hard_line_break_marker?
+        end
+
+        # AsciiDoc hard line break: a space followed by `+` at end of line,
+        # or a backslash at end of line. Both forms render as `<br>` inside
+        # the enclosing paragraph/verse. Recognised ahead of `text_unformatted`
+        # so the marker isn't swallowed as plain text.
+        def hard_line_break_marker?
+          (str(' +') >> str("\n")).present? |
+            (str('\\') >> str("\n")).present?
+        end
+
+        def hard_line_break
+          ((str(' +') >> str("\n")) |
+             (str('\\') >> str("\n"))).as(:hard_line_break)
         end
 
         def inline
@@ -187,7 +221,8 @@ module Coradoc
             inline_image |
             inline_passthrough |
             underline |
-            small
+            small |
+            hard_line_break
         end
 
         def text_unformatted

data/lib/coradoc/asciidoc/parser/list.rb

@@ -149,8 +149,13 @@ module Coradoc
         end
 
         def dlist_definition
-          text
-            .as(:definition) >> line_ending >> empty_line.repeat(0)
+          # AsciiDoc convention: the definition body is indented relative
+          # to the term. That leading whitespace is structural (marks
+          # the line as a continuation of the dlist item), not content.
+          # Consume it without capturing so downstream CoreModel text
+          # doesn't carry the source indentation into HTML/Markdown.
+          (match('[ \t]').repeat(0) >> text.as(:definition)) >>
+            line_ending >> empty_line.repeat(0)
         end
 
         def dlist_item(_delimiter = nil)

data/lib/coradoc/asciidoc/serializer/serializers/image/core.rb

@@ -14,7 +14,8 @@ module Coradoc
                         end
               _anchor = model.anchor.nil? ? '' : "#{serialize_child(model.anchor)}\n"
               _title = model.title.to_s.empty? ? '' : ".#{model.title}\n"
-              attrs = serialize_child(model.attributes, options)
+              composed = Model::Image::AttributeExtractor.compose(model)
+              attrs = serialize_child(composed, options)
               [missing, _anchor, _title, 'image', model.colons, model.src, attrs,
                model.line_break].join
             end
@@ -24,6 +25,7 @@ module Coradoc
         # Self-register this serializer
         ElementRegistry.register(Coradoc::AsciiDoc::Model::Image::Core, Image::Core)
         ElementRegistry.register(Coradoc::AsciiDoc::Model::Image::BlockImage, Image::Core)
+        ElementRegistry.register(Coradoc::AsciiDoc::Model::Image::InlineImage, Image::Core)
       end
     end
   end

data/lib/coradoc/asciidoc/transform/element_transformers/admonition_styles.rb

@@ -26,6 +26,21 @@ module Coradoc
               BUILTIN.include?(name) || custom.include?(name)
             end
 
+            # Canonical uppercase form for +style+, or nil if unknown.
+            # Single source of truth for the canonical casing used in
+            # CoreModel::AnnotationBlock#annotation_type and AsciiDoc
+            # round-trip output.
+            def canonicalize(style)
+              return nil unless admonition?(style)
+
+              style.to_s.upcase
+            end
+
+            # All registered style names (BUILTIN + custom), lowercased.
+            def all_styles
+              (BUILTIN + custom).freeze
+            end
+
             # Register an additional admonition style. Open for extension.
             def register(style)
               name = style.to_s.downcase

data/lib/coradoc/asciidoc/transform/element_transformers/block_transformer.rb

@@ -71,16 +71,26 @@ module Coradoc
 
             # Dispatch entry point for any block whose AsciiDoc model carries
             # an attribute list (delimited blocks + open blocks). Per the
-            # AsciiDoc spec, every delimited block accepts admonition styles
-            # in its attribute line. Admonition style wins for example,
-            # sidebar, quote, and open blocks; verbatim blocks (source,
-            # listing) intentionally ignore it because their verbatim
-            # semantics are stronger than the annotation label.
+            # AsciiDoc spec, every delimited block accepts both admonition
+            # labels and verbatim/stem casts in its attribute line. The cast
+            # is resolved by +block_cast_semantic+ in MECE order:
+            # admonition > stem > verbatim > fallback.
             def transform_with_admonition_check(block, native_class)
-              style = first_positional_attr(block)
-              return transform_admonition_block(block, style) if AdmonitionStyles.admonition?(style)
-
-              transform_typed_block(block, native_class)
+              semantic = block_cast_semantic(block)
+              case semantic
+              when :admonition
+                transform_admonition_block(block, first_positional_attr(block))
+              when :stem
+                transform_stem_block(block, first_positional_attr(block))
+              when :source
+                transform_source_block(block)
+              when :listing
+                transform_listing_from_open(block)
+              when :literal
+                transform_literal_from_open(block)
+              else
+                transform_typed_block(block, native_class)
+              end
             end
 
             def transform_example_block(block)
@@ -98,36 +108,32 @@ module Coradoc
             # Open blocks (`--`) are generic containers. AsciiDoc allows
             # casting them to a different block type via positional
             # attributes: verbatim types (`[source]`, `[listing]`,
-            # `[literal]`) and admonition labels (`[NOTE]`, `[TIP]`,
+            # `[literal]`), STEM types (`[stem]`, `[latexmath]`,
+            # `[asciimath]`), and admonition labels (`[NOTE]`, `[TIP]`,
             # `[WARNING]`, `[CAUTION]`, `[IMPORTANT]`). When such a cast
             # is present, the block behaves like the corresponding
             # delimited block. Anything else stays an OpenBlock.
             def transform_open_block(block)
-              semantic = open_block_semantic(block)
-              case semantic
-              when :source
-                transform_source_block(block)
-              when :listing
-                transform_listing_from_open(block)
-              when :literal
-                transform_literal_from_open(block)
-              when :admonition
-                transform_admonition_block(block, first_positional_attr(block))
-              else
-                transform_typed_block(block, Coradoc::CoreModel::OpenBlock)
-              end
+              transform_with_admonition_check(block, Coradoc::CoreModel::OpenBlock)
             end
 
             VERBATILE_CAST_STYLES = %w[source listing literal].freeze
 
-            def open_block_semantic(block)
+            # Resolve a delimited block's cast from its first positional
+            # attribute. Single source of truth for the cast ladder used
+            # by every block-form transformer (example/sidebar/quote/open).
+            # Returns one of: :admonition, :stem, :source, :listing,
+            # :literal, or nil (no cast — use the block's native class).
+            def block_cast_semantic(block)
               style = first_positional_attr(block)
               return nil unless style
 
-              case style.to_s.downcase
-              when *VERBATILE_CAST_STYLES then :"#{style.downcase}"
-              else :admonition if AdmonitionStyles.admonition?(style)
-              end
+              style_str = style.to_s.downcase
+              return :admonition if AdmonitionStyles.admonition?(style)
+              return :stem if STEM_STYLES.key?(style_str)
+              return style_str.to_sym if VERBATILE_CAST_STYLES.include?(style_str)
+
+              nil
             end
 
             # Returns the first positional attribute on the block's
@@ -148,10 +154,14 @@ module Coradoc
             # (example / sidebar / quote / pass / open). Builds an
             # AnnotationBlock with annotation_type set from the style and
             # the block's body lines joined into a single content string.
+            # Type is canonicalised via AdmonitionStyles so every code path
+            # (line admonition, block admonition, attribute-cast admonition)
+            # produces the same uppercase key.
             def transform_admonition_block(block, type)
+              canonical = AdmonitionStyles.canonicalize(type) || type.to_s
               content_lines = Array(block.lines).map { |line| ToCoreModel.extract_text_content(line) }.join("\n")
               Coradoc::CoreModel::AnnotationBlock.new(
-                annotation_type: type.to_s.downcase,
+                annotation_type: canonical,
                 content: content_lines,
                 title: ToCoreModel.extract_title_text(block.title)
               )

data/lib/coradoc/asciidoc/transform/element_transformers/document_transformer.rb

@@ -13,6 +13,7 @@ module Coradoc
               children = CalloutMerger.call(children)
               children = prepend_frontmatter(children, doc.frontmatter)
               children = insert_title_heading_after_frontmatter(children, title_text)
+              children = resolve_attribute_references(children, attributes)
 
               Coradoc::CoreModel::DocumentElement.new(
                 id: doc.id,
@@ -58,6 +59,16 @@ module Coradoc
               children.insert(frontmatter_count, title_heading)
             end
 
+            # Resolve `{name}` attribute references in the body against the
+            # document's own declared attributes. Single source of truth:
+            # the resolver lives in core so other format gems can reuse it
+            # when they have equivalent reference macros.
+            def resolve_attribute_references(children, attributes)
+              return children if attributes.nil? || attributes.keys.empty?
+
+              Coradoc::CoreModel::AttributeReferenceResolver.call(children, attributes)
+            end
+
             def transform_section(section, parent_id: nil)
               title_text = ToCoreModel.extract_title_text(section.title)
               section_id = section.id || Coradoc::CoreModel::IdGenerator.generate_from_title(

data/lib/coradoc/asciidoc/transform/element_transformers/list_transformer.rb

@@ -67,20 +67,28 @@ module Coradoc
               )
               li.children = children
 
-              if item.nested.is_a?(Coradoc::AsciiDoc::Model::List::Core)
-                nested_core = transform_list(item.nested, list_marker_type(item.nested))
-                li.children << nested_core
-              elsif item.nested.is_a?(Array)
-                item.nested.each do |n|
-                  next unless n.is_a?(Coradoc::AsciiDoc::Model::List::Core)
-
-                  li.children << transform_list(n, list_marker_type(n))
-                end
-              end
-
+              nested_lists = extract_nested_lists(item)
+              li.nested_list = nested_lists.first if nested_lists.size == 1
               li
             end
 
+            # Pull every nested List::Core off the AsciiDoc model item and
+            # transform each into a CoreModel::ListBlock. Returns [] when
+            # the item has no nested lists. Single source of truth for the
+            # nested-list shape so transform_list_item and any future caller
+            # share the same extraction logic.
+            def extract_nested_lists(item)
+              nested = item.nested
+              return [] if nested.nil?
+
+              candidates = nested.is_a?(Array) ? nested : [nested]
+              candidates.filter_map do |n|
+                next unless n.is_a?(Coradoc::AsciiDoc::Model::List::Core)
+
+                transform_list(n, list_marker_type(n))
+              end
+            end
+
             def list_marker_type(list)
               case list
               when Coradoc::AsciiDoc::Model::List::Ordered then 'ordered'

data/lib/coradoc/asciidoc/transform/element_transformers/other_transformer.rb

@@ -15,9 +15,10 @@ module Coradoc
             end
 
             def transform_admonition(admonition)
+              canonical = Coradoc::AsciiDoc::Transform::ElementTransformers::AdmonitionStyles.canonicalize(admonition.type) || admonition.type.to_s
               children = ToCoreModel.transform_inline_content(admonition.content)
               block = Coradoc::CoreModel::AnnotationBlock.new(
-                annotation_type: admonition.type,
+                annotation_type: canonical,
                 content: ToCoreModel.extract_text_content(admonition.content)
               )
               block.children = children
@@ -25,24 +26,22 @@ module Coradoc
             end
 
             def transform_image(image)
-              src = image.src.to_s
-              src = src[1..] if src.start_with?(':')
-              positional = image.attributes&.positional || []
-              positional_alt = positional.first&.value&.to_s || ''
-              caption = positional[1]&.value&.to_s
-              title = image.title&.to_s
-              # AsciiDoc block-title (`.Caption`) is semantically a caption,
-              # but for compatibility with the existing pipeline that treated
-              # it as alt when no positional alt was supplied, fall back to it.
-              alt = positional_alt.empty? ? title : positional_alt
-              Coradoc::CoreModel::Image.new(
-                src: src,
-                alt: alt,
-                caption: caption,
-                title: title,
-                width: image.attributes&.[]('width'),
-                height: image.attributes&.[]('height')
-              )
+              Coradoc::CoreModel::Image.new(**image_attributes(image))
+            end
+
+            def image_attributes(image)
+              {
+                src: normalize_image_src(image.src),
+                alt: image.alt, title: image.title, caption: image.caption,
+                width: image.width, height: image.height,
+                link: image.link, role: image.role,
+                inline: image.is_a?(Coradoc::AsciiDoc::Model::Image::InlineImage)
+              }
+            end
+
+            def normalize_image_src(src)
+              s = src.to_s
+              s.start_with?(':') ? s[1..] : s
             end
 
             def transform_bibliography(bib)

data/lib/coradoc/asciidoc/transform/from_core_model.rb

@@ -319,17 +319,25 @@ module Coradoc
               )
             when 'raw_inline'
               Coradoc::AsciiDoc::Model::Inline::Passthrough.new(content: inline.content)
+            when 'hard_line_break'
+              Coradoc::AsciiDoc::Model::Inline::HardLineBreak.new
             else
               Coradoc::AsciiDoc::Model::TextElement.new(content: inline.content)
             end
           end
 
           def transform_image(image)
-            Coradoc::AsciiDoc::Model::Image::BlockImage.new(
-              src: image.src,
-              title: image.alt,
-              attributes: build_image_attributes(image)
-            )
+            target_class = image.inline ? Coradoc::AsciiDoc::Model::Image::InlineImage
+                                        : Coradoc::AsciiDoc::Model::Image::BlockImage
+            target_class.new(**image_attributes(image))
+          end
+
+          def image_attributes(image)
+            {
+              src: image.src, alt: image.alt, title: image.title,
+              caption: image.caption, width: image.width, height: image.height,
+              link: image.link, role: image.role
+            }
           end
 
           def transform_bibliography(bib)
@@ -528,6 +536,10 @@ module Coradoc
               content.map { |item| create_text_elements(item) }
             when Coradoc::CoreModel::InlineElement
               transform_inline(content)
+            when Coradoc::CoreModel::TextContent
+              Coradoc::AsciiDoc::Model::TextElement.new(content: content.text.to_s)
+            when Coradoc::CoreModel::Base
+              transform(content)
             when Coradoc::AsciiDoc::Model::Base
               content
             when Lutaml::Model::Serializable
@@ -553,13 +565,6 @@ module Coradoc
             attrs
           end
 
-          def build_image_attributes(image)
-            attrs = {}
-            attrs['width'] = image.width if image.width
-            attrs['height'] = image.height if image.height
-            attrs
-          end
-
           def default_marker(marker_type)
             case marker_type
             when 'ordered' then '.'

data/lib/coradoc/asciidoc/transform/to_core_model_registrations.rb

@@ -172,9 +172,11 @@ module Coradoc
             Registry.register(
               Coradoc::AsciiDoc::Model::Inline::AttributeReference,
               lambda { |model|
+                name = model.name.to_s
                 Coradoc::CoreModel::InlineElement.new(
                   format_type: 'attribute_reference',
-                  content: "{#{model.name}}"
+                  target: name,
+                  content: "{#{name}}"
                 )
               }
             )
@@ -246,6 +248,16 @@ module Coradoc
               ->(model) { Inc.transform_include(model) }
             )
 
+            # Inline hard line break — distinct from the structural
+            # Model::LineBreak (which represents paragraph-separator blank
+            # lines and is dropped at the CoreModel boundary). Hard breaks
+            # are semantic and round-trip as CoreModel::HardLineBreakElement
+            # so HTML/Markdown renderers can map them to <br>.
+            Registry.register(
+              Coradoc::AsciiDoc::Model::Inline::HardLineBreak,
+              ->(_model) { Coradoc::CoreModel::HardLineBreakElement.new(content: '') }
+            )
+
             [
               Coradoc::AsciiDoc::Model::Audio,
               Coradoc::AsciiDoc::Model::Video,

data/lib/coradoc/asciidoc/transformer/block_rules.rb

@@ -37,12 +37,15 @@ module Coradoc
               Model::Block::Example.new(title: '', lines: example)
             end
 
-            # Admonition
+            # Admonition. Canonicalise the type to uppercase so round-trips
+            # through HTML/Markdown/DocBook all see the same key used by
+            # icon and CSS-class lookups.
             rule(
               admonition_type: simple(:admonition_type),
               content: sequence(:content)
             ) do
-              Model::Admonition.new(content: content, type: admonition_type.to_s)
+              canonical = Coradoc::AsciiDoc::Transform::ElementTransformers::AdmonitionStyles.canonicalize(admonition_type.to_s)
+              Model::Admonition.new(content: content, type: canonical)
             end
 
             # Block image
@@ -51,12 +54,16 @@ module Coradoc
               title = block_image[:title]
               path = block_image[:path]
               attrs = AttributeListNormalizer.coerce(block_image[:attribute_list_macro])
+              promoted, residual = Model::Image::AttributeExtractor.call(
+                attrs, Model::Image::BlockImage
+              )
               Model::Image::BlockImage.new(
                 title: title,
                 id: id,
                 src: path,
-                attributes: attrs,
-                line_break: "\n"
+                attributes: residual,
+                line_break: "\n",
+                **promoted
               )
             end
           end

data/lib/coradoc/asciidoc/transformer/inline_rules.rb

@@ -36,14 +36,21 @@ module Coradoc
 
             # Inline image
             rule(inline_image: subtree(:inline_image)) do
+              attrs = AttributeListNormalizer.coerce(inline_image[:attribute_list])
+              promoted, residual = Model::Image::AttributeExtractor.call(
+                attrs, Model::Image::InlineImage
+              )
               Model::Image::InlineImage.new(
-                title: inline_image[:text],
                 src: inline_image[:path],
-                attributes: inline_image[:attribute_list]
+                attributes: residual,
+                **promoted
               )
             end
 
-            # Inline passthrough (`+++raw content+++`)
+            # Inline passthrough (`+++raw content+++` or `pass:[raw]`).
+            # Both forms carry an opaque payload that survives all
+            # substitutions verbatim; `form` records which syntax was
+            # used so the AsciiDoc serializer can round-trip faithfully.
             rule(inline_passthrough: subtree(:passthrough)) do
               Model::Inline::Passthrough.new(
                 content: passthrough[:raw].to_s,
@@ -56,6 +63,15 @@ module Coradoc
               Model::Inline::AttributeReference.new(name:)
             end
 
+            # Hard line break (` +\n` or `\\n`). Emitted as a dedicated
+            # AsciiDoc model (Inline::HardLineBreak) distinct from
+            # Model::LineBreak, which only represents paragraph-separator
+            # blank lines. Hard breaks carry semantic meaning: HTML/Markdown
+            # renderers map them to <br>.
+            rule(hard_line_break: simple(:_)) do
+              Model::Inline::HardLineBreak.new
+            end
+
             # Term
             rule(
               term_type: simple(:term_type),

data/lib/coradoc/asciidoc/transformer/table_cell_builder.rb

@@ -20,12 +20,24 @@ module Coradoc
           cell_opts = {}
           style = parse_format(format, cell_opts)
 
-          unescaped_content = content.to_s.gsub(/\\([|!,:;])/, '\1')
+          unescaped_content = cell_content_to_string(content).gsub(/\\([|!,:;])/, '\1')
           cell_opts[:content] = parse_inline_content(unescaped_content, style)
 
           Model::TableCell.new(**cell_opts)
         end
 
+        # Coerce the parser-supplied cell content into a plain String.
+        # The cell parser emits `text:` as either a single Parslet::Slice
+        # or an Array of slices (from `.repeat(0)`). An empty Array must
+        # map to "" — Ruby's `[].to_s` returns "[]", which previously
+        # leaked into TableCell content as a phantom "[]" cell.
+        def cell_content_to_string(content)
+          return '' if content.nil?
+          return content.map(&:to_s).join if content.is_a?(Array)
+
+          content.to_s
+        end
+
         # Coerce a raw parser cell value into a TableCell.
         # Used by TableLayout.group_cells_into_rows when it encounters
         # cells that the parser emitted as Hashes or plain strings.

data/lib/coradoc/asciidoc/version.rb

@@ -2,6 +2,6 @@
 
 module Coradoc
   module AsciiDoc
-    VERSION = '2.0.21'
+    VERSION = '2.0.23'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc-adoc
 version: !ruby/object:Gem::Version
-  version: 2.0.21
+  version: 2.0.23
 platform: ruby
 authors:
 - Ribose Inc.
@@ -146,6 +146,7 @@ files:
 - lib/coradoc/asciidoc/model/header.rb
 - lib/coradoc/asciidoc/model/highlight.rb
 - lib/coradoc/asciidoc/model/image.rb
+- lib/coradoc/asciidoc/model/image/attribute_extractor.rb
 - lib/coradoc/asciidoc/model/image/block_image.rb
 - lib/coradoc/asciidoc/model/image/block_image/attribute_list.rb
 - lib/coradoc/asciidoc/model/image/core.rb