glossarist 2.8.14 → 2.8.16

data/lib/glossarist/figure.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A dataset-level figure entity (ISO 10241-1 §6.5 — non-verbal representation).
+  #
+  # Figures are authored once at `datasets/{ds}/figures/{fig-id}.yaml` and
+  # referenced by any number of concepts via stable ID — the same sharing
+  # pattern as bibliography entries. This is the rich, shareable counterpart
+  # to concept-owned NonVerbRep entries.
+  #
+  # A Figure may carry multiple image variants (SVG + PNG + dark/light) for
+  # responsive rendering and accessibility. Composite figures use recursive
+  # subfigures.
+  #
+  # Caption, description, and alt are localized (hash keyed by ISO 639 code).
+  class Figure < SharedNonVerbalEntity
+    attribute :images, FigureImage, collection: true
+    attribute :subfigures, Figure, collection: true
+
+    key_value do
+      map :images, to: :images
+      map :subfigures, to: :subfigures
+    end
+
+    def find_by_id(target_id)
+      return self if id == target_id
+
+      Array(subfigures).each do |sub|
+        found = sub.find_by_id(target_id)
+        return found if found
+      end
+      nil
+    end
+
+    def all_ids
+      [id] + Array(subfigures).flat_map(&:all_ids)
+    end
+  end
+end

data/lib/glossarist/figure_image.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # One image variant within a Figure. Multiple variants enable responsive
+  # images, format fallbacks, and accessibility (dark/light, language-specific).
+  #
+  # The `role` field drives consumer-side selection:
+  #   vector  — SVG (preferred for diagrams, resolution-independent)
+  #   raster  — PNG/JPG (preferred for photos)
+  #   dark    — optimized for dark backgrounds
+  #   light   — optimized for light backgrounds
+  #   print   — high-resolution for print output
+  class FigureImage < Lutaml::Model::Serializable
+    attribute :src, :string
+    attribute :format, :string
+    attribute :role, :string
+    attribute :width, :integer
+    attribute :height, :integer
+    attribute :scale, :integer
+
+    key_value do
+      map :src, to: :src
+      map :format, to: :format
+      map :role, to: :role
+      map :width, to: :width
+      map :height, to: :height
+      map :scale, to: :scale
+    end
+  end
+end

data/lib/glossarist/figure_reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A reference from a concept to a dataset-level Figure entity.
+  #
+  # Produced by `figures: [id]` structural arrays and `{{fig:id}}` inline
+  # mentions. Both forms resolve through the same figure adapter.
+  class FigureReference < NonVerbalReference
+    key_value do
+      map :entity_id, to: :entity_id
+      map :display, to: :display
+    end
+
+    def dedup_key
+      [self.class.name, entity_id]
+    end
+  end
+end

data/lib/glossarist/formula.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A dataset-level formula entity (ISO 10241-1 §6.5 — non-verbal representation).
+  #
+  # Formulas are authored at `datasets/{ds}/formulas/{formula-id}.yaml` and
+  # shared across concepts. The mathematical expression is stored in a
+  # notation format (LaTeX, MathML, AsciiMath). Caption, description, and
+  # alt are localized for accessibility.
+  class Formula < SharedNonVerbalEntity
+    attribute :expression, :hash
+    attribute :notation, :string
+
+    key_value do
+      map :expression, to: :expression
+      map :notation, to: :notation
+    end
+  end
+end

data/lib/glossarist/formula_reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A reference from a concept to a dataset-level Formula entity.
+  #
+  # Produced by `formulas: [id]` structural arrays and `{{formula:id}}` inline
+  # mentions.
+  class FormulaReference < NonVerbalReference
+    key_value do
+      map :entity_id, to: :entity_id
+      map :display, to: :display
+    end
+
+    def dedup_key
+      [self.class.name, entity_id]
+    end
+  end
+end

data/lib/glossarist/localized_string.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Semantic operations on localized string fields.
+  #
+  # Localized strings are stored as hashes keyed by ISO 639 language code:
+  #   { "eng" => "Mixed reflection", "fra" => "Réflexion mixte" }
+  #
+  # This module provides typed access and fallback logic. It does not
+  # introduce a wrapper class — the hash IS the localized string, matching
+  # how Section#names, DatasetRegister#description, etc. already work.
+  module LocalizedString
+    # Fetch a localized value with language fallback.
+    #
+    # @param hash [Hash, nil] the localized string hash
+    # @param lang [String, Symbol] the desired language code
+    # @param fallback [String, nil] fallback language (default "eng")
+    # @return [String, nil] the localized value, or nil if not found
+    def self.fetch(hash, lang, fallback = "eng")
+      return nil unless hash.is_a?(Hash)
+
+      direct = hash[lang.to_s] || hash[lang.to_sym]
+      return direct if direct
+
+      fallback && fallback.to_s != lang.to_s ? hash[fallback.to_s] || hash[fallback.to_sym] : nil
+    end
+
+    # Check if a localized string hash is nil or empty.
+    #
+    # @param hash [Hash, nil]
+    # @return [Boolean]
+    def self.empty?(hash)
+      hash.nil? || hash.empty?
+    end
+
+    # Check if a localized string hash has any entries.
+    #
+    # @param hash [Hash, nil]
+    # @return [Boolean]
+    def self.present?(hash)
+      !empty?(hash)
+    end
+  end
+end

data/lib/glossarist/managed_concept_data.rb

@@ -7,6 +7,9 @@ module Glossarist
     attribute :localized_concepts, :hash
     attribute :domains, ConceptReference, collection: true
     attribute :tags, :string, collection: true
+    attribute :figures, FigureReference, collection: true
+    attribute :tables, TableReference, collection: true
+    attribute :formulas, FormulaReference, collection: true
     attribute :sources, ConceptSource, collection: true
     attribute :localizations, LocalizedConcept,
               collection: Collections::LocalizationCollection,
@@ -21,6 +24,12 @@ module Glossarist
       map %i[domains groups], to: :domains,
                               with: { from: :domains_from_yaml, to: :domains_to_yaml }
       map :tags, to: :tags
+      map :figures, to: :figures,
+                    with: { from: :figures_from_yaml, to: :figures_to_yaml }
+      map :tables, to: :tables,
+                   with: { from: :tables_from_yaml, to: :tables_to_yaml }
+      map :formulas, to: :formulas,
+                     with: { from: :formulas_from_yaml, to: :formulas_to_yaml }
       map :sources, to: :sources
       map :localizations, to: :localizations,
                           with: { from: :localizations_from_yaml, to: :localizations_to_yaml }
@@ -63,6 +72,46 @@ module Glossarist
       doc["domains"] = model.domains.map(&:to_hash)
     end
 
+    def figures_from_yaml(model, value)
+      model.figures = parse_non_verbal_refs(value, FigureReference)
+    end
+
+    def figures_to_yaml(model, doc)
+      serialize_non_verbal_refs(model.figures, doc, "figures")
+    end
+
+    def tables_from_yaml(model, value)
+      model.tables = parse_non_verbal_refs(value, TableReference)
+    end
+
+    def tables_to_yaml(model, doc)
+      serialize_non_verbal_refs(model.tables, doc, "tables")
+    end
+
+    def formulas_from_yaml(model, value)
+      model.formulas = parse_non_verbal_refs(value, FormulaReference)
+    end
+
+    def formulas_to_yaml(model, doc)
+      serialize_non_verbal_refs(model.formulas, doc, "formulas")
+    end
+
+    private
+
+    def parse_non_verbal_refs(value, ref_class)
+      return unless value.is_a?(Array)
+
+      value.map { |item| ref_class.of_yaml(item) }
+    end
+
+    def serialize_non_verbal_refs(refs, doc, key)
+      return if refs.nil? || refs.empty?
+
+      doc[key] = refs.map do |ref|
+        ref.display ? { "ref" => ref.entity_id, "display" => ref.display } : ref.entity_id
+      end
+    end
+
     def authoritative_source
       return [] unless sources
 

data/lib/glossarist/non_verb_rep.rb

@@ -1,30 +1,26 @@
 # frozen_string_literal: true
 
 module Glossarist
-  # A non-verbal representation used to help define a concept, following
-  # ISO 10241-1 §6.5.
+  # A concept-local non-verbal representation (ISO 10241-1 §6.5).
   #
-  # Non-verbal representations are associated resources (images, tables,
-  # formulas) that live outside the concept model. They are referenced by URI
-  # and can be shared across concepts. The resource belongs either to the
-  # dataset package (relative path) or is externally referenced (URL/URN).
+  # NonVerbRep is the inline form attached directly to a concept's data.
+  # The dataset-shared form is Figure / Table / Formula. The two share the
+  # same a11y + provenance payload via NonVerbalEntity; NonVerbRep differs
+  # only in that it has no dataset-wide identity (no +id+, no +identifier+)
+  # — its identity is its position inside the parent concept.
   #
-  # Each non-verbal representation specifies:
-  # - +type+: one of "image", "table", "formula"
-  # - +ref+: URI reference to the resource (relative path, URN, or URL)
-  # - +text+: optional text description or alt text
-  # - +sources+: bibliographic sources for the representation
-  class NonVerbRep < Lutaml::Model::Serializable
+  # +type+ discriminates the kind of non-verbal content: "image", "table",
+  # or "formula". When +type+ is "image", +images+ carries one or more
+  # FigureImage variants (responsive, format fallback, dark/light). The
+  # caption/description/alt fields are localized (hash keyed by ISO 639
+  # code) for accessibility.
+  class NonVerbRep < NonVerbalEntity
     attribute :type, :string
-    attribute :ref, :string
-    attribute :text, :string
-    attribute :sources, ConceptSource, collection: true
+    attribute :images, FigureImage, collection: true, initialize_empty: true
 
     key_value do
       map :type, to: :type
-      map :ref, to: :ref
-      map :text, to: :text
-      map :sources, to: :sources
+      map :images, to: :images
     end
   end
 end

data/lib/glossarist/non_verbal_entity.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Shared payload for every non-verbal representation, whether it lives
+  # inline on a concept (NonVerbRep) or as a dataset-shared file
+  # (Figure / Table / Formula).
+  #
+  # The four attributes here are the common a11y + provenance payload every
+  # non-verbal entity carries, regardless of content type or scope:
+  #
+  # - +caption+: localized short title (a11y / indexing).
+  # - +description+: localized long description (a11y screen readers).
+  # - +alt+: localized alternative text (a11y short screen-reader label).
+  # - +sources+: bibliographic sources for the representation.
+  #
+  # Identity (+id+, +identifier+) belongs on subclasses that have it; see
+  # SharedNonVerbalEntity for the dataset-shared variant.
+  class NonVerbalEntity < Lutaml::Model::Serializable
+    attribute :caption, :hash
+    attribute :description, :hash
+    attribute :alt, :hash
+    attribute :sources, ConceptSource, collection: true
+
+    key_value do
+      map :caption, to: :caption
+      map :description, to: :description
+      map :alt, to: :alt
+      map :sources, to: :sources
+    end
+
+    def find_by_id(_target_id)
+      nil
+    end
+
+    def all_ids
+      []
+    end
+
+    def self.from_file(path)
+      return nil unless File.exist?(path)
+
+      from_yaml(File.read(path, encoding: "utf-8"))
+    end
+  end
+end

data/lib/glossarist/non_verbal_reference.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Abstract base for references to dataset-level non-verbal entities.
+  #
+  # FigureReference, TableReference, and FormulaReference all carry an
+  # entity ID and an optional display override. They are produced both by
+  # structural arrays (`figures: [id]` on ManagedConceptData) and by inline
+  # mentions (`{{fig:id}}` in text).
+  class NonVerbalReference < Lutaml::Model::Serializable
+    attribute :entity_id, :string
+    attribute :display, :string
+
+    def self.of_yaml(hash)
+      return new(entity_id: hash) if hash.is_a?(String)
+
+      new(
+        entity_id: hash["ref"] || hash["id"] || hash[:ref] || hash[:id],
+        display: hash["display"] || hash[:display],
+      )
+    end
+  end
+end

data/lib/glossarist/reference_extractor.rb

@@ -170,9 +170,14 @@ module Glossarist
 
       concept.localizations.each do |l10n|
         Array(l10n.non_verb_rep).each do |nvr|
-          next unless nvr.is_a?(NonVerbRep) && nvr.ref && !nvr.ref.strip.empty?
+          next unless nvr.is_a?(NonVerbRep)
 
-          refs << AssetReference.new(path: nvr.ref.strip)
+          Array(nvr.images).each do |image|
+            next unless image.is_a?(FigureImage)
+            next if image.src.nil? || image.src.strip.empty?
+
+            refs << AssetReference.new(path: image.src.strip)
+          end
         end
 
         (l10n.data&.terms || []).each do |term|
@@ -226,6 +231,15 @@ module Glossarist
       AssetReference.new(path: path.strip)
     end
 
+    # Unified non-verbal entity mention resolver for fig:/table:/formula:.
+    # Strips the prefix and produces the appropriate reference type.
+    def resolve_non_verbal_mention(prefix, identifier, display, ref_class)
+      cleaned = identifier.delete_prefix(prefix).strip
+      return nil if cleaned.empty?
+
+      ref_class.new(entity_id: cleaned, display: display)
+    end
+
     private
 
     def gather_texts(lc_hash)
@@ -293,6 +307,18 @@ module Glossarist
       ext.resolve_cite_key(identifier, display)
     end
 
+    register_identifier_resolver("fig:") do |ext, identifier, display|
+      ext.resolve_non_verbal_mention("fig:", identifier, display, FigureReference)
+    end
+
+    register_identifier_resolver("table:") do |ext, identifier, display|
+      ext.resolve_non_verbal_mention("table:", identifier, display, TableReference)
+    end
+
+    register_identifier_resolver("formula:") do |ext, identifier, display|
+      ext.resolve_non_verbal_mention("formula:", identifier, display, FormulaReference)
+    end
+
     register_identifier_resolver("urn:iec:std:iec:60050") do |ext, identifier, display|
       ext.resolve_iec_urn(identifier, display)
     end

data/lib/glossarist/shared_non_verbal_entity.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Dataset-shared non-verbal entity — a NonVerbalEntity with a stable
+  # identity. Figure, Table, and Formula inherit from this; NonVerbRep
+  # (concept-local, positional) inherits from NonVerbalEntity directly.
+  #
+  # The +id+ is the stable identifier used for cross-referencing
+  # (e.g. +figures/fig_A.23.yaml+ → +id: fig_A.23+). The +identifier+ is
+  # the human-readable label (e.g. +"A.23"+) used for display and AsciiDoc
+  # xref targets like +<<fig_A.23>>+.
+  class SharedNonVerbalEntity < NonVerbalEntity
+    attribute :id, :string
+    attribute :identifier, :string
+
+    key_value do
+      map :id, to: :id
+      map :identifier, to: :identifier
+    end
+
+    def find_by_id(target_id)
+      id == target_id ? self : nil
+    end
+
+    def all_ids
+      [id].compact
+    end
+  end
+end

data/lib/glossarist/table.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A dataset-level table entity (ISO 10241-1 §6.5 — non-verbal representation).
+  #
+  # Tables are authored at `datasets/{ds}/tables/{table-id}.yaml` and shared
+  # across concepts. The content is stored as structured data (rows/columns)
+  # or as a markup string (HTML, Markdown, AsciiDoc). Caption, description,
+  # and alt are localized for accessibility.
+  class Table < SharedNonVerbalEntity
+    attribute :content, :hash
+    attribute :format, :string
+
+    key_value do
+      map :content, to: :content
+      map :format, to: :format
+    end
+  end
+end

data/lib/glossarist/table_reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A reference from a concept to a dataset-level Table entity.
+  #
+  # Produced by `tables: [id]` structural arrays and `{{table:id}}` inline
+  # mentions.
+  class TableReference < NonVerbalReference
+    key_value do
+      map :entity_id, to: :entity_id
+      map :display, to: :display
+    end
+
+    def dedup_key
+      [self.class.name, entity_id]
+    end
+  end
+end

data/lib/glossarist/transforms/concept_to_gloss_transform.rb

@@ -303,8 +303,8 @@ desig_index)
         Array(non_verb_reps).each_with_index.map do |nvr, idx|
           Rdf::GlossNonVerbalRep.new(
             representation_type: nvr.type,
-            representation_ref: nvr.ref,
-            representation_text: nvr.text,
+            representation_ref: nvr.images.first&.src,
+            representation_text: localized_alt_for(nvr.alt, lang),
             sources: build_gloss_sources(nvr.sources),
             concept_id: concept_id.to_s,
             lang_code: lang.to_s,
@@ -313,6 +313,12 @@ desig_index)
         end
       end
 
+      def localized_alt_for(alt, lang)
+        return nil unless alt.is_a?(Hash) && !alt.empty?
+
+        alt[lang.to_s] || alt[lang.to_sym] || alt.values.first
+      end
+
       def build_gloss_domains(domains, concept_id)
         Array(domains).map do |ref|
           Rdf::GlossConceptReference.new(

data/lib/glossarist/v3.rb

@@ -13,10 +13,6 @@ module Glossarist
     autoload :ManagedConceptData, "glossarist/v3/managed_concept_data"
     autoload :ManagedConcept, "glossarist/v3/managed_concept"
     autoload :ConceptDocument, "glossarist/v3/concept_document"
-    autoload :BibliographyEntry, "glossarist/v3/bibliography_entry"
-    autoload :BibliographyFile, "glossarist/v3/bibliography_file"
-    autoload :ImageEntry, "glossarist/v3/image_entry"
-    autoload :ImageFile, "glossarist/v3/image_file"
 
     Configuration.register_model(Citation, id: :citation)
     Configuration.register_model(ConceptSource, id: :concept_source)
@@ -28,9 +24,5 @@ module Glossarist
     Configuration.register_model(ManagedConceptData, id: :managed_concept_data)
     Configuration.register_model(ManagedConcept, id: :managed_concept)
     Configuration.register_model(ConceptDocument, id: :concept_document)
-    Configuration.register_model(BibliographyEntry, id: :bibliography_entry)
-    Configuration.register_model(BibliographyFile, id: :bibliography_file)
-    Configuration.register_model(ImageEntry, id: :image_entry)
-    Configuration.register_model(ImageFile, id: :image_file)
   end
 end

data/lib/glossarist/validation/asset_index.rb

@@ -95,9 +95,14 @@ module Glossarist
 
         def register_non_verb_rep(index, l10n)
           Array(l10n.non_verb_rep).each do |nvr|
-            next unless nvr.is_a?(NonVerbRep) && nvr.ref && !nvr.ref.strip.empty?
+            next unless nvr.is_a?(NonVerbRep)
 
-            index.register(nvr.ref.strip)
+            Array(nvr.images).each do |image|
+              next unless image.is_a?(FigureImage)
+              next if image.src.nil? || image.src.strip.empty?
+
+              index.register(image.src.strip)
+            end
           end
         end
 

data/lib/glossarist/validation/bibliography_index.rb

@@ -30,18 +30,15 @@ module Glossarist
 
         concepts.each { |concept| index_concept_sources(index, concept) }
         index_bibliography_file(index, dataset_path)
-        index_images_file(index, dataset_path)
 
         index
       end
 
-      def self.build_from_yaml(concepts, bibliography_yaml: nil,
-images_yaml: nil)
+      def self.build_from_yaml(concepts, bibliography_yaml: nil)
         index = new
 
         concepts.each { |concept| index_concept_sources(index, concept) }
         index_bib_from_yaml_string(index, bibliography_yaml)
-        index_images_from_yaml_string(index, images_yaml)
 
         index
       end
@@ -103,7 +100,7 @@ images_yaml: nil)
         def index_bibliography_file(index, dataset_path)
           return unless dataset_path
 
-          bib = V3::BibliographyFile.from_file(
+          bib = BibliographyData.from_file(
             File.join(dataset_path, "bibliography.yaml"),
           )
           return unless bib
@@ -118,27 +115,10 @@ images_yaml: nil)
           nil
         end
 
-        def index_images_file(index, dataset_path)
-          return unless dataset_path
-
-          images = V3::ImageFile.from_file(
-            File.join(dataset_path, "images.yaml"),
-          )
-          return unless images
-
-          Array(images.entries).each do |entry|
-            next unless entry&.id
-
-            index.register(entry.id, entry)
-          end
-        rescue StandardError
-          nil
-        end
-
         def index_bib_from_yaml_string(index, yaml_content)
           return unless yaml_content
 
-          bib = V3::BibliographyFile.from_yaml(yaml_content)
+          bib = BibliographyData.from_yaml(yaml_content)
           bib.entries.each do |entry|
             index.register(entry.id, entry)
             index.register(entry.reference, entry) if entry.reference
@@ -146,15 +126,6 @@ images_yaml: nil)
         rescue StandardError
           nil
         end
-
-        def index_images_from_yaml_string(index, yaml_content)
-          return unless yaml_content
-
-          images = V3::ImageFile.from_yaml(yaml_content)
-          images.entries.each { |entry| index.register(entry.id, entry) }
-        rescue StandardError
-          nil
-        end
       end
     end
   end

data/lib/glossarist/validation/rules/bibliography_yaml_rule.rb

@@ -18,7 +18,7 @@ module Glossarist
           return [] unless bib_content
 
           begin
-            V3::BibliographyFile.from_yaml(bib_content)
+            BibliographyData.from_yaml(bib_content)
           rescue StandardError => e
             return [issue(
               "bibliography.yaml is invalid YAML: #{e.message}",

data/lib/glossarist/validation/rules/gcr_context.rb

@@ -43,7 +43,6 @@ module Glossarist
           @bibliography_index ||= BibliographyIndex.build_from_yaml(
             concepts,
             bibliography_yaml: read_zip_file("bibliography.yaml"),
-            images_yaml: read_zip_file("images.yaml"),
           )
         end