andromeda_cms 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44592cbc430b9bf1022ac0627a2cc6d76aa8e3f4834e6bc13873b95674862e02
-  data.tar.gz: 3908dd979cc31bb8c71b7db2886dcb86c3199d12214a41547ae22609db064e71
+  metadata.gz: 2702633c9baaedc1b40c9a7bf767fe41dd472276bd1f279cabcea893746b9924
+  data.tar.gz: 6c4c0463b1709aa434a11ce3700f67a4b2d573237353cef8f2ed87e034b8b742
 SHA512:
-  metadata.gz: aa22ba028964288a581eb0e24df49a744a5726ce3ad5ce1fe922c7c4c66f7a18d5973194fd08696b1473b0437e25ac9fd156027605273b0773803ee2261cd515
-  data.tar.gz: b8ae98566b309a8cd25e4740bee5c61e0b31e9a8d2678a70969c70821a240a41f1a38e253cd3da793ebdfd3f44a2072ad734e4af7cc610d4774f0099c885d3df
+  metadata.gz: a6dae30e5bcd69aeb8665d1991be26ec0705471d8fe592c703f0824441adfa0b40dd69de95b6480616fe49348aebc6127ba2051611dc19156f62ea66192b396e
+  data.tar.gz: 856b571be0856f01afe55c14661e5ac9f49eb1b67b7329e712ebc077fa413a2b961a95832ee38374fa768b688779cbbc4ce705ab3bddccc9008d7cab0374b41a

data/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-09-29
+
+### Added
+
+- An image imported in MDX (`import photo from './photo.png'`) can be passed
+  to a component as a prop (`<Figure src={photo} />`). It is published like
+  an `image` attribute, and the partial receives an `Andromeda::Image`.
+- `rails g andromeda:component` writes a strict locals declaration that
+  includes `content: nil`, since `content` is passed even to a self-closing
+  tag.
+
+### Fixed
+
+- A component that queries entries (`Content::Post.find(slug)`) during
+  `andromeda:build` in production reads source files instead of the
+  previous build's `_index.json`, so an entry not converted yet is found.
+- `andromeda_image_url` called inside a component while converting returns
+  an asset marker instead of a URL without a digest, which 404'd in
+  production. `andromeda_content` leaves markers in place there too.
+- A component that renders another entry's HTML during `andromeda:build`
+  converts that entry on the spot when it has not been converted yet,
+  instead of raising `Andromeda::BuildMissing`. Entries whose components
+  render each other fail with a "circular conversion" error.
+- An `Andromeda::Error` raised inside a component partial (such as
+  `EntryNotFound` from `find`) is no longer wrapped in
+  `ActionView::Template::Error`, so the build lists it with the other
+  problems instead of aborting with a stack trace.
+
 ## [0.3.0] - 2026-09-29
 
 ### Added
@@ -93,6 +121,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Generators: `andromeda:install`, `andromeda:collection`,
   `andromeda:component` and `andromeda:import_astro`.
 
+[0.4.0]: https://github.com/AndromedaCMS/andromeda_cms/releases/tag/v0.4.0
 [0.3.0]: https://github.com/AndromedaCMS/andromeda_cms/releases/tag/v0.3.0
 [0.2.0]: https://github.com/AndromedaCMS/andromeda_cms/releases/tag/v0.2.0
 [0.1.2]: https://github.com/AndromedaCMS/andromeda_cms/releases/tag/v0.1.2

data/README.md

@@ -168,8 +168,33 @@ import Callout from 'content_components/callout';
 
 Props arrive as locals (`camelCase` becomes `snake_case`), the tag's children
 arrive as `content`, and `<Fragment slot="header">` becomes a `header` local.
+`content` is passed even to a self-closing tag (`<Callout />`), so a partial
+using strict locals must declare it:
+
+```erb
+<%# locals: (type: "note", title: nil, content: nil) %>
+```
+
 `bin/rails generate andromeda:component Callout type title` writes the stub.
 
+A component can query other entries, e.g. a card linking to another post:
+
+```erb
+<%# app/views/content_components/_post_card.html.erb %>
+<%# locals: (slug:, content: nil) %>
+<% post = Content::Blog.find(slug) %>
+<a href="<%= blog_path(post.id) %>">
+  <img src="<%= andromeda_image_url(post.cover_image) %>" alt="">
+  <%= post.title %>
+</a>
+```
+
+During `andromeda:build` such queries read the source files, so an entry not
+converted yet is still found, and `andromeda_content(post)` converts it on
+the spot. Component HTML is rendered once at build time
+and stored, so `andromeda_image_url` emits a placeholder there that
+`andromeda_content` turns into the digest-stamped URL when the page is served.
+
 ### Images
 
 Put an image next to the entry and reference it relatively:
@@ -191,6 +216,24 @@ through the pipeline too; anything under `public/` or on another host is left
 untouched. Declare a frontmatter image with `attribute :hero_image, :image`
 and render it with `andromeda_image_url`.
 
+To pass an image to a component, import it and use it as a prop, as in Astro:
+
+```mdx
+import photo from './photo.png';
+
+<Figure src={photo} caption="The view from the top" />
+```
+
+The partial receives the same `Andromeda::Image` an `image` attribute holds:
+
+```erb
+<%# locals: (src:, caption: nil, content: nil) %>
+<figure>
+  <img src="<%= andromeda_image_url(src) %>" class="w-full" alt="">
+  <figcaption><%= caption %></figcaption>
+</figure>
+```
+
 ## Development and deployment
 
 ```

data/lib/andromeda/build_context.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Andromeda
+  # What the current thread is doing on Andromeda's behalf, for code that
+  # runs *inside* a conversion but cannot be told so directly: a component
+  # partial rendered into an entry's HTML calls the same `Entry.find` and
+  # `andromeda_image_url` a request-time view does, yet both must behave
+  # differently while the output is being produced.
+  #
+  # Thread-local because a build or a development request converts on one
+  # thread, and another thread serving requests at the same time must keep
+  # seeing the built index.
+  module BuildContext
+    BUILD_KEY = :andromeda_build_source_entries
+    CONVERTING_KEY = :andromeda_converting
+
+    module_function
+
+    # Marks the block as an `andromeda:build`. Queries made during it read
+    # source files instead of `_index.json`, which is still the previous
+    # build's (or absent) until each collection finishes -- so a component
+    # that looks up another entry would otherwise miss one that has not been
+    # converted yet. Each collection is loaded once per build and shared.
+    #
+    # Nested calls reuse the outer build's cache.
+    def building
+      return yield if building?
+
+      Thread.current[BUILD_KEY] = {}
+      begin
+        yield
+      ensure
+        Thread.current[BUILD_KEY] = nil
+      end
+    end
+
+    def building?
+      !Thread.current[BUILD_KEY].nil?
+    end
+
+    # @param entry_class [Class] an Andromeda::Entry subclass.
+    # @return [Array<Andromeda::Entry>] the block's result, cached for the
+    #   rest of the build.
+    def source_entries(entry_class)
+      cache = Thread.current[BUILD_KEY]
+      return yield if cache.nil?
+
+      cache[entry_class] ||= yield
+    end
+
+    # Marks the block as rendering an entry's body into stored HTML. Anything
+    # that would bake a final asset URL into it must emit a marker instead:
+    # the digest is only known once `assets:precompile` runs, after the build.
+    #
+    # A component can ask another entry for its HTML, which converts that
+    # entry inside this one; the stack of entries being converted is what
+    # stops two entries whose components show each other from recursing
+    # forever.
+    #
+    # @param label [String] identifies the entry, e.g. "blog/hello-world".
+    # @raise [Andromeda::Error] if `label` is already being converted.
+    def converting(label)
+      stack = Thread.current[CONVERTING_KEY] ||= []
+      if stack.include?(label)
+        raise Andromeda::Error, "circular conversion: #{[*stack.drop_while { |l| l != label }, label].join(' -> ')} " \
+                                "-- a component renders the HTML of an entry that renders this one"
+      end
+
+      stack.push(label)
+      begin
+        yield
+      ensure
+        stack.pop
+      end
+    end
+
+    def converting?
+      !(Thread.current[CONVERTING_KEY] || []).empty?
+    end
+  end
+end

data/lib/andromeda/components/errors.rb

@@ -71,11 +71,30 @@ module Andromeda
         location = [path, line].compact.join(":")
         super(
           "#{location}: unsupported MDX expression `{#{source}}` -- only literals, " \
-          "`frontmatter.x` references, and comments are supported"
+          "`frontmatter.x` references, imported images, and comments are supported"
         )
       end
     end
 
+    # Raised when a prop passes an imported image (`import photo from
+    # './photo.png'` then `src={photo}`) that cannot be published: the file
+    # is missing, lies outside the project, or was not imported by a
+    # relative path. Raising at build time keeps a typo from shipping as a
+    # 404.
+    class InvalidImageImportError < Andromeda::Error
+      attr_reader :name, :specifier, :path, :line
+
+      def initialize(name, specifier, reason, path:, line:)
+        @name = name
+        @specifier = specifier
+        @path = path
+        @line = line
+
+        location = [path, line].compact.join(":")
+        super("#{location}: image `#{name}` imported from #{specifier.inspect} #{reason}")
+      end
+    end
+
     # Raised when there is no Rails renderer to hand a partial to -- either
     # `ApplicationController` is not defined (Rails is not loaded / not
     # booted yet) and no `view:` was passed explicitly to

data/lib/andromeda/components/import_scanner.rb

@@ -29,9 +29,8 @@ module Andromeda
       # @param tree [Hash] an mdast root node.
       # @return [Hash{String => String}] the name a component tag would use
       #   in the document, mapped to the raw import path/specifier. An
-      #   `import cover from './cover.png'` (image imports, deferred) ends
-      #   up here too -- harmless, since it is only ever consulted when that name is
-      #   later used as a component tag, and image imports never are.
+      #   `import cover from './cover.png'` ends up here too, which is how
+      #   Components resolves `{cover}` passed as a prop to an image.
       def scan(tree)
         imports = {}
 

data/lib/andromeda/components.rb

@@ -36,9 +36,14 @@ module Andromeda
     #   the original contract this class was written against, so it defaults
     #   to `{}` and callers that don't pass it simply get `nil` back for
     #   every `frontmatter.x` reference instead of an error.
-    def initialize(tree:, path: nil, view: nil, frontmatter: {})
+    # @param content_root [String, nil] the collection's base directory, which
+    #   decides where an imported image is published (see
+    #   `Andromeda::Assets.publish`). Defaults to the content file's own
+    #   directory.
+    def initialize(tree:, path: nil, view: nil, frontmatter: {}, content_root: nil)
       @tree = tree
       @path = path
+      @content_root = content_root
       @frontmatter = frontmatter || {}
       @view = view || default_view
       @imports = ImportScanner.scan(tree)
@@ -197,12 +202,48 @@ module Andromeda
     end
 
     def evaluate_prop_expression(source, node)
+      name = source.to_s.strip
+      return imported_image(name, node) if image_import?(name)
+
       StaticExpression.evaluate(source, frontmatter: @frontmatter)
     rescue StaticExpression::UnsupportedExpressionError
       position = node_position(node)
       raise UnsupportedExpressionError.new(source, path: @path, line: position[:line], column: position[:column])
     end
 
+    IMAGE_EXTENSIONS = %w[.png .jpg .jpeg .gif .webp .avif .svg].freeze
+    IDENTIFIER_RE = /\A[A-Za-z_$][\w$]*\z/.freeze
+
+    # `{photo}` where `photo` was bound by `import photo from './photo.png'`
+    # -- Astro's way of passing an image to a component.
+    def image_import?(name)
+      return false unless IDENTIFIER_RE.match?(name)
+
+      specifier = @imports[name]
+      !specifier.nil? && IMAGE_EXTENSIONS.include?(File.extname(specifier).downcase)
+    end
+
+    # Publishes the imported file the same way an `image` attribute is, so
+    # the partial receives an Andromeda::Image and `andromeda_image_url`
+    # works on it unchanged. Containment is checked before existence so a
+    # crafted path never learns whether something outside the project exists.
+    #
+    # @return [Andromeda::Image]
+    # @raise [InvalidImageImportError]
+    def imported_image(name, node)
+      specifier = @imports[name]
+      invalid = ->(reason) { InvalidImageImportError.new(name, specifier, reason, path: @path, line: node_position(node)[:line]) }
+      raise invalid.call("must be a relative path (./ or ../)") unless specifier.start_with?("./", "../") && @path
+
+      source = File.expand_path(specifier, File.dirname(File.expand_path(@path)))
+      content_root = @content_root || File.dirname(source)
+      raise invalid.call("resolves outside the project") unless Andromeda::Assets.logical_path(source, content_root: content_root)
+      raise invalid.call("does not exist") unless File.file?(source)
+
+      logical = Andromeda::Assets.publish(source, content_root: content_root)
+      Andromeda::Image.new(path: source, relative_path: specifier, asset: Andromeda::Assets.marker_for(logical))
+    end
+
     # @return [Hash{Symbol => String}] `{content: ...}` plus one entry per
     #   named slot. When no child carries a `slot` attribute this
     #   is just `{content: children_html}` -- the common case reuses the
@@ -259,6 +300,14 @@ module Andromeda
         @view.render(partial: partial, locals: locals).html_safe
       rescue ActionView::MissingTemplate
         raise missing_partial_error(name, node, partial)
+      rescue ActionView::Template::Error => e
+        # A partial that queries entries (`Content::Post.find(slug)`) can
+        # raise Andromeda's own errors; ActionView wraps them, which would
+        # slip past the build's `rescue Andromeda::Error` and abort it with a
+        # stack trace instead of listing the problem with the others.
+        raise e.cause if e.cause.is_a?(Andromeda::Error)
+
+        raise
       ensure
         restore_view_annotation(annotate_before)
       end

data/lib/andromeda/entry.rb

@@ -170,7 +170,7 @@ module Andromeda
       # @return [Array<Andromeda::Entry>]
       # @raise [Andromeda::LoaderError] listing every file that failed.
       def source_entries
-        load_entries_from_source
+        Andromeda::BuildContext.source_entries(self) { load_entries_from_source }
       end
 
       # Drops the in-memory cache, forcing the next query to re-run the
@@ -186,8 +186,13 @@ module Andromeda
       # needs was validated and written to `_index.json` at build time, so
       # reading it back is both faster and immune to a content file that
       # changed on disk after the build. Development goes to the Loader so
-      # edits are visible without a build step.
+      # edits are visible without a build step. A build is the exception:
+      # the index is only rewritten once a collection finishes converting,
+      # so a component querying entries mid-build reads source instead
+      # (see Andromeda::BuildContext).
       def entries
+        return source_entries if Andromeda::BuildContext.building?
+
         @entries ||= production? ? entries_from_index : load_entries_from_source
       end
 

data/lib/andromeda/helpers.rb

@@ -8,19 +8,28 @@ module Andromeda
     # Outputs an entry's converted body. Marked html_safe because the build
     # produced this markup from content the application's own authors wrote,
     # the same trust model Astro applies to `.md`/`.mdx` (see 13_security).
+    # Inside a component rendered at conversion time the asset markers are
+    # left in place, for the same reason `andromeda_image_url` leaves them.
     #
     # @param entry [Andromeda::Entry]
     # @return [ActiveSupport::SafeBuffer]
     def andromeda_content(entry)
-      Andromeda::Assets.resolve(entry.html).html_safe # rubocop:disable Rails/OutputSafety
+      html = Andromeda::BuildContext.converting? ? entry.html : Andromeda::Assets.resolve(entry.html)
+      html.html_safe # rubocop:disable Rails/OutputSafety
     end
 
+    # Inside a component partial rendered at conversion time, this returns
+    # the asset marker instead of a URL: the digest does not exist until
+    # `assets:precompile` runs, after the build, and `andromeda_content`
+    # resolves the marker when the page is served.
+    #
     # @param image [Andromeda::Image, nil] an `image` attribute's value.
     # @return [String, nil] its URL, or nil when the attribute is unset.
     def andromeda_image_url(image)
       return nil if image.nil?
 
-      Andromeda::Assets.resolve(image.asset || image.relative_path)
+      source = image.asset || image.relative_path
+      Andromeda::BuildContext.converting? ? source : Andromeda::Assets.resolve(source)
     end
 
     # Renders a nested table of contents from `entry.headings`.

data/lib/andromeda/pipeline.rb

@@ -62,10 +62,12 @@ module Andromeda
     def convert(entry)
       mdx = Andromeda::Parser.mdx?(entry.file_path)
       tree = Andromeda::Parser.parse(entry.body, mdx: mdx, path: entry.file_path)
-      result = Andromeda::Renderer.new(
-        components: components_for(entry, tree),
-        image_resolver: image_resolver_for(entry)
-      ).render(tree)
+      result = Andromeda::BuildContext.converting("#{entry.collection}/#{entry.id}") do
+        Andromeda::Renderer.new(
+          components: components_for(entry, tree),
+          image_resolver: image_resolver_for(entry)
+        ).render(tree)
+      end
 
       payload = {
         id: entry.id,
@@ -105,7 +107,11 @@ module Andromeda
     def fetch(entry)
       stored = @store.read_entry(entry.collection, entry.id)
 
-      if production?
+      # During a build a component may ask for an entry that has not been
+      # converted yet (or only by the previous build), so it is converted
+      # the development way. Once done, the digest and render key match and
+      # a second request reuses it.
+      if production? && !Andromeda::BuildContext.building?
         return stored if stored
 
         raise Andromeda::BuildMissing.new(collection: entry.collection, id: entry.id, file_path: entry.file_path)
@@ -177,28 +183,7 @@ module Andromeda
     # @param entry_class [Class]
     # @return [BuildResult]
     def build_collection(entry_class)
-      entries =
-        begin
-          entry_class.source_entries
-        rescue Andromeda::LoaderError => e
-          return BuildResult.new(
-            collection: entry_class.collection_name, converted: 0,
-            errors: e.messages.map { |message| "[#{entry_class.collection_name}] #{message}" }
-          )
-        end
-
-      errors = []
-      payloads = entries.filter_map do |entry|
-        begin
-          convert(entry)
-        rescue Andromeda::Error => e
-          errors << "[#{entry_class.collection_name}] #{entry.file_path}: #{e.message}"
-          nil
-        end
-      end
-
-      @store.replace_collection!(entry_class.collection_name, payloads)
-      BuildResult.new(collection: entry_class.collection_name, converted: payloads.size, errors: errors, entries: entries)
+      Andromeda::BuildContext.building { build_collection_from_source(entry_class) }
     end
 
     # Converts every registered collection, reporting every problem found
@@ -216,13 +201,15 @@ module Andromeda
     #   every collection, if any entry failed to convert or references an
     #   entry that does not exist.
     def self.build_all(entry_classes = default_entry_classes, store: Andromeda::Store.new)
-      results = entry_classes.map { |entry_class| new(store: store).build_collection(entry_class) }
-      errors = results.flat_map(&:errors)
-      loaded = entry_classes.zip(results).filter_map { |entry_class, result| [entry_class, result.entries] if result.entries }
-      errors.concat(Andromeda::References.problems(loaded.to_h))
-      raise Andromeda::BuildError, errors unless errors.empty?
-
-      results
+      Andromeda::BuildContext.building do
+        results = entry_classes.map { |entry_class| new(store: store).build_collection(entry_class) }
+        errors = results.flat_map(&:errors)
+        loaded = entry_classes.zip(results).filter_map { |entry_class, result| [entry_class, result.entries] if result.entries }
+        errors.concat(Andromeda::References.problems(loaded.to_h))
+        raise Andromeda::BuildError, errors unless errors.empty?
+
+        results
+      end
     end
 
     def self.default_entry_classes
@@ -231,6 +218,31 @@ module Andromeda
 
     private
 
+    def build_collection_from_source(entry_class)
+      entries =
+        begin
+          entry_class.source_entries
+        rescue Andromeda::LoaderError => e
+          return BuildResult.new(
+            collection: entry_class.collection_name, converted: 0,
+            errors: e.messages.map { |message| "[#{entry_class.collection_name}] #{message}" }
+          )
+        end
+
+      errors = []
+      payloads = entries.filter_map do |entry|
+        begin
+          convert(entry)
+        rescue Andromeda::Error => e
+          errors << "[#{entry_class.collection_name}] #{entry.file_path}: #{e.message}"
+          nil
+        end
+      end
+
+      @store.replace_collection!(entry_class.collection_name, payloads)
+      BuildResult.new(collection: entry_class.collection_name, converted: payloads.size, errors: errors, entries: entries)
+    end
+
     # What the stored HTML depends on besides the entry's own source.
     # Component partials are rendered into the HTML at conversion time, so
     # without this an edited partial would keep serving the old markup until
@@ -318,7 +330,10 @@ module Andromeda
       return nil unless Andromeda::Parser.mdx?(entry.file_path)
       return nil unless defined?(Andromeda::Components)
 
-      Andromeda::Components.new(tree: tree, path: entry.file_path, view: nil, frontmatter: entry.data)
+      Andromeda::Components.new(
+        tree: tree, path: entry.file_path, view: nil, frontmatter: entry.data,
+        content_root: Andromeda::Registry[entry.collection]&.base_dir
+      )
     end
   end
 end

data/lib/andromeda/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Andromeda
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/andromeda_cms.rb

@@ -3,6 +3,7 @@
 require_relative "andromeda/version"
 require_relative "andromeda/errors"
 require_relative "andromeda/configuration"
+require_relative "andromeda/build_context"
 require_relative "andromeda/assets"
 require_relative "andromeda/helpers"
 require_relative "andromeda/fix"

data/lib/generators/andromeda/component/component_generator.rb

@@ -44,12 +44,20 @@ module Andromeda
       def partial_content
         <<~ERB
           #{usage_comment}
+          #{strict_locals}
           <div class="#{underscored_name.dasherize}">
           #{prop_lines.join("\n")}#{"\n" unless prop_lines.empty?}  <%= content %>
           </div>
         ERB
       end
 
+      # Every prop is optional, and `content` is declared too: it is passed
+      # even to a self-closing tag (`<Callout />`), where it is empty.
+      def strict_locals
+        locals = props.map { |prop| "#{prop.underscore}: nil" } << "content: nil"
+        "<%# locals: (#{locals.join(', ')}) %>"
+      end
+
       def prop_lines
         props.map do |prop|
           local = prop.underscore

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: andromeda_cms
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - LIMHAUS Inc.
@@ -89,6 +89,7 @@ files:
 - ext/andromeda_cms/src/lib.rs
 - ext/andromeda_cms/src/nodes.rs
 - lib/andromeda/assets.rb
+- lib/andromeda/build_context.rb
 - lib/andromeda/check.rb
 - lib/andromeda/components.rb
 - lib/andromeda/components/errors.rb