herb 0.10.4 → 0.11.0

data/lib/herb/engine/slots/callee.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+# typed: true
+
+require "pathname"
+
+module Herb
+  class Engine
+    module Slots
+      # The state interface of a partial, read at a caller's compile.
+      #
+      # A render that binds states names the partial by its literal path, so the caller can
+      # open that file, compile it with a throwaway visitor and learn which region states it
+      # declares and of what kind. That is what lets a binding to a state the partial never
+      # declared, or of the wrong kind, fail the caller's compile instead of a render.
+      #
+      # Lookups are memoized by path and modification time. A partial that renders a caller
+      # that renders it again would compile forever, so a path already being read answers nil
+      # and the caller skips the interface check for that one render.
+      #
+      class Callee
+        Declared = Data.define(
+          :name,    #: String
+          :kind,    #: Symbol
+          :derived, #: bool
+          :counted  #: bool
+        )
+
+        COMPILING = :herb_slots_callee_compiling #: Symbol
+        CACHE_LIMIT = 256 #: Integer
+
+        @cache = {} #: Hash[[String, Float], Callee?]
+        @lock = Mutex.new #: Mutex
+
+        #: (Pathname | String) -> Callee?
+        def self.for(path)
+          pathname = path.is_a?(Pathname) ? path : Pathname.new(path)
+
+          return nil unless pathname.file?
+
+          key = [pathname.to_s, pathname.mtime.to_f] #: [String, Float]
+
+          @lock.synchronize do
+            return @cache.fetch(key) if @cache.key?(key)
+          end
+
+          compiling = (Fiber[COMPILING] ||= []) #: Array[String]
+
+          return nil if compiling.include?(pathname.to_s)
+
+          compiling.push(pathname.to_s)
+
+          callee = begin
+            new(pathname)
+          rescue StandardError
+            nil
+          ensure
+            compiling.pop
+          end
+
+          @lock.synchronize do
+            @cache.clear if @cache.size >= CACHE_LIMIT
+            @cache[key] = callee
+          end
+
+          callee
+        end
+
+        #: () -> void
+        def self.reset!
+          @lock.synchronize { @cache.clear }
+        end
+
+        attr_reader :path #: Pathname
+        attr_reader :diagnostics #: Array[Herb::Diagnostic]
+
+        #: (Pathname) -> void
+        def initialize(path)
+          @path = path
+          @declared = {} #: Hash[String, Declared]
+
+          visitor = Visitor.new(mode: :client, mark: false, fatal: false, deliver: :none)
+
+          Herb::Engine.new(path.read, visitors: [visitor], filename: path.to_s)
+
+          @diagnostics = visitor.diagnostics
+
+          visitor.state_entries.each do |entry|
+            next unless entry[:scope] == :region
+
+            name = entry[:name].to_s
+
+            @declared[name] = Declared.new(
+              name: name,
+              kind: entry[:kind],
+              derived: !entry[:derived].nil?,
+              counted: visitor.counted_state?(name)
+            )
+          end
+        end
+
+        #: (String) -> Declared?
+        def declaration(name)
+          @declared[name]
+        end
+
+        #: () -> Array[String]
+        def names
+          @declared.keys
+        end
+
+        #: () -> Array[Herb::Diagnostic]
+        def errors
+          @diagnostics.select(&:error?)
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/component_definitions.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# typed: true
+
+# NOTE: This file is generated by the templates/template.rb script and should not be
+# modified manually. See templates/lib/herb/engine/slots/component_definitions.rb.erb
+
+module Herb
+  class Engine
+    module Slots
+      # The built-in components a slots template may use, and what each one takes.
+      #
+      module ComponentDefinitions
+        COMPONENTS = {
+          "Fragment" => {
+            void: false,
+            deferred: false,
+            parents: nil,
+            description: "Wraps server-derived content with the markup to stand in while that content is stale.",
+            attributes: {
+              "delay" => { type: "milliseconds", description: "How long to wait before the fallback appears, so a fast answer never flashes it." }.freeze,
+              "hold" => { type: "milliseconds", description: "How long the fallback stays once it appears, so it does not flicker away." }.freeze,
+              "on" => { type: "state_list", description: "The states whose writes mask this fragment, named as a list." }.freeze,
+            }.freeze,
+          }.freeze,
+          "Fallback" => {
+            void: false,
+            deferred: false,
+            parents: ["Fragment", "Async", "Lazy"].freeze,
+            description: "The markup its component shows in place of content that is stale or not there yet.",
+            attributes: {}, #: Hash[String, Hash[Symbol, String]]
+          }.freeze,
+          "Async" => {
+            void: false,
+            deferred: true,
+            parents: nil,
+            description: "A deferred block the client requests on mount, so its content loads in parallel with the page.",
+            attributes: {
+              "delay" => { type: "milliseconds", description: "How long to wait before the fallback appears, so a fast answer never flashes it." }.freeze,
+              "hold" => { type: "milliseconds", description: "How long the fallback stays once it appears, so it does not flicker away." }.freeze,
+              "poll" => { type: "milliseconds", description: "How often to request the block again once it has settled." }.freeze,
+            }.freeze,
+          }.freeze,
+          "Lazy" => {
+            void: false,
+            deferred: true,
+            parents: nil,
+            description: "A deferred block the client requests when it nears the viewport, and never for content the reader never reaches.",
+            attributes: {
+              "delay" => { type: "milliseconds", description: "How long to wait before the fallback appears, so a fast answer never flashes it." }.freeze,
+              "hold" => { type: "milliseconds", description: "How long the fallback stays once it appears, so it does not flicker away." }.freeze,
+              "poll" => { type: "milliseconds", description: "How often to request the block again once it has settled." }.freeze,
+            }.freeze,
+          }.freeze,
+        }.freeze #: Hash[String, { void: bool, deferred: bool, parents: Array[String]?, description: String, attributes: Hash[String, Hash[Symbol, String]] }]
+
+        BUILT_IN = COMPONENTS.keys.freeze #: Array[String]
+
+        DEFERRED = COMPONENTS.select { |_, component| component[:deferred] }.keys.freeze #: Array[String]
+
+        #: (String) -> Hash[String, Hash[Symbol, String]]
+        def self.attributes_for(name)
+          COMPONENTS.dig(name, :attributes) || {}
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/components/async.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      module Components
+        # A deferred block the client requests immediately on mount, so expensive
+        # content loads in parallel with the page instead of blocking it.
+        #
+        class Async < Deferred
+          NAME = "Async" #: String
+
+          private
+
+          #: () -> String
+          def mode
+            "async"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/components/base.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      module Components
+        # What every built-in component shares.
+        #
+        # A component receives the element it stands on and the slots visitor
+        # transforming the template. It validates its attributes against its
+        # `allowed_attributes` and answers the nodes that replace it.
+        #
+        class Base
+          #: (untyped, untyped) -> Array[untyped]
+          def self.transform(element, visitor)
+            new(element, visitor).transform
+          end
+
+          #: (untyped, untyped) -> void
+          def initialize(element, visitor)
+            @element = element
+            @visitor = visitor
+          end
+
+          #: () -> Array[untyped]
+          def transform
+            raise NotImplementedError, "#{self.class} does not transform"
+          end
+
+          #: () -> Array[String]
+          def allowed_attributes
+            attribute_definitions.keys
+          end
+
+          #: () -> void
+          def refuse_unknown_attributes
+            allowed = allowed_attributes
+
+            return if attributes.all? { |attribute|
+              name = attribute_name(attribute).to_s
+
+              name.start_with?("data-herb-") || allowed.include?(name)
+            }
+
+            if allowed.empty?
+              error("`<#{tag_name}>` takes no attributes yet.", @element.location, suggestion: "Remove the attributes.")
+            else
+              error("`<#{tag_name}>` only takes #{allowed.map { |name| "`#{name}`" }.join(" and ")}.", @element.location, suggestion: "Remove the other attributes.")
+            end
+          end
+
+          private
+
+          #: () -> Hash[String, Hash[Symbol, String]]
+          def attribute_definitions
+            ComponentDefinitions.attributes_for(tag_name)
+          end
+
+          #: () -> Hash[String, Integer]
+          def timing
+            timed = {} #: Hash[String, Integer]
+
+            attributes.each do |attribute|
+              name = attribute_name(attribute).to_s
+
+              next unless attribute_definitions.dig(name, :type) == "milliseconds"
+
+              value = static_value(attribute)
+
+              if value&.match?(/\A\d+\z/)
+                timed[name] = Integer(value, 10)
+              else
+                error("`#{name}` on a `<#{tag_name}>` takes a whole number of milliseconds.", attribute.location, suggestion: %(Write it like `#{name}="150"`.))
+              end
+            end
+
+            timed
+          end
+
+          #: () -> String
+          def tag_name
+            @element.tag_name&.value.to_s
+          end
+
+          #: () -> Array[untyped]
+          def children
+            @element.body || []
+          end
+
+          #: () -> Array[untyped]
+          def attributes
+            open_tag = @element.open_tag
+
+            return [] unless open_tag.is_a?(Herb::AST::HTMLOpenTagNode)
+
+            (open_tag.children || []).grep(Herb::AST::HTMLAttributeNode)
+          end
+
+          #: (untyped) -> String?
+          def attribute_name(attribute)
+            parts = attribute.name&.children || []
+
+            return nil if parts.empty?
+            return nil unless parts.all?(Herb::AST::LiteralNode)
+
+            parts.filter_map { |part| part.content if part.respond_to?(:content) }.join
+          end
+
+          #: (untyped) -> String?
+          def static_value(attribute)
+            parts = attribute.value&.children || []
+
+            return nil unless parts.all?(Herb::AST::LiteralNode)
+
+            parts.map { |part| part.content.to_s }.join.strip
+          end
+
+          #: (String, untyped, ?suggestion: String?) -> nil
+          def error(message, location, suggestion: nil)
+            @visitor.slot_error(message, location, :component, suggestion: suggestion)
+          end
+
+          #: (String, untyped, ?suggestion: String?) -> void
+          def warning(message, location, suggestion: nil)
+            @visitor.slot_warning(message, location, :component, suggestion: suggestion)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/components/deferred.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      module Components
+        # A block whose primary content stays out of the initial response.
+        #
+        # The transform conditions the primary on an internal boolean state the
+        # client steers, so the first render shows only the `<Fallback>` and the
+        # block request is an ordinary steered refetch answering the primary
+        # branch with its statics. `Async` requests on mount and `Lazy` when the
+        # block nears the viewport.
+        #
+        class Deferred < Base
+          #: () -> Array[untyped]
+          def transform
+            refuse_unknown_attributes
+
+            fallbacks, primary = children.partition { |child| Components.element?(child, Fallback::NAME) }
+
+            primary = @visitor.transform_component_children(primary)
+
+            if fallbacks.size > 1
+              error("A `<#{tag_name}>` holds #{fallbacks.size} `<Fallback>` elements, and it can only stand one in.", @element.location, suggestion: "Keep one `<Fallback>` per `<#{tag_name}>`.")
+            end
+
+            fallback = fallbacks.first
+
+            Fallback.new(fallback, @visitor).refuse_unknown_attributes if fallback
+
+            state = @visitor.states.declare_internal_block
+            if_node = deferred_conditional(state, primary, fallback)
+
+            @visitor.record_deferred(if_node, mode: mode, state: state, timing: timing)
+
+            [@visitor.record_assignment(@visitor.erb_code_node(@visitor.states.internal_assignment(state))), if_node]
+          end
+
+          private
+
+          #: () -> String
+          def mode
+            raise NotImplementedError, "#{self.class} names no mode"
+          end
+
+          #: (String, Array[untyped], untyped) -> untyped
+          def deferred_conditional(state, primary, fallback)
+            subsequent = nil
+
+            if fallback
+              subsequent = Herb::AST::ERBElseNode.build(
+                location: fallback.location,
+                tag_opening: Herb::Token.from(:erb_start, "<%"),
+                content: Herb::Token.from(:erb_content, " else "),
+                tag_closing: Herb::Token.from(:erb_end, "%>"),
+                statements: @visitor.transform_component_children(fallback.body || [])
+              )
+            end
+
+            Herb::AST::ERBIfNode.build(
+              location: @element.location,
+              tag_opening: Herb::Token.from(:erb_start, "<%"),
+              content: Herb::Token.from(:erb_content, " if #{state} "),
+              tag_closing: Herb::Token.from(:erb_end, "%>"),
+              statements: primary,
+              subsequent: subsequent,
+              end_node: Herb::AST::ERBEndNode.build(
+                location: @element.location,
+                tag_opening: Herb::Token.from(:erb_start, "<%"),
+                content: Herb::Token.from(:erb_content, " end "),
+                tag_closing: Herb::Token.from(:erb_end, "%>")
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/components/fallback.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      module Components
+        # The markup a `<Fragment>` shows while its content is stale.
+        #
+        # A fallback only means something inside a `<Fragment>`, which consumes
+        # it during its own transform, so a fallback reaching its own transform
+        # stands outside one and errors.
+        #
+        class Fallback < Base
+          NAME = "Fallback" #: String
+
+          #: () -> Array[untyped]
+          def transform
+            error("`<Fallback>` sits outside a `<Fragment>`, so there is nothing for it to stand in for.", @element.location, suggestion: "Wrap the content it replaces and the `<Fallback>` together in a `<Fragment>`.")
+
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/components/fragment.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      module Components
+        # Suspense-like fallbacks for server-derived content.
+        #
+        # A fragment compiles its primary children into a synthesized single-arm
+        # conditional the page renders on first load, and parks its `<Fallback>`
+        # for the client to show the instant a state write invalidates a server
+        # read inside it. `delay` and `hold` tune when the fallback appears and
+        # how long it stays.
+        #
+        class Fragment < Base
+          NAME = "Fragment" #: String
+
+          #: () -> Array[untyped]
+          def transform
+            refuse_unknown_attributes
+
+            timing = self.timing
+            fallbacks, primary = children.partition { |child| Components.element?(child, Fallback::NAME) }
+
+            primary = @visitor.transform_component_children(primary)
+
+            if fallbacks.size > 1
+              error("A `<Fragment>` holds #{fallbacks.size} `<Fallback>` elements, and it can only stand one in.", @element.location, suggestion: "Keep one `<Fallback>` per `<Fragment>`.")
+            end
+
+            fallback = fallbacks.first
+
+            unless fallback
+              warning("`<Fragment>` holds no `<Fallback>`, so it wraps nothing and compiles away.", @element.location, suggestion: "Add a `<Fallback>` to stand in while its content is stale, or unwrap the children.")
+
+              return primary
+            end
+
+            Fallback.new(fallback, @visitor).refuse_unknown_attributes
+            refuse_nested_fragment(fallback)
+
+            if_node = synthesized_conditional(primary)
+
+            @visitor.record_fragment(if_node, fallback.body || [], timing.merge(masking))
+
+            [if_node]
+          end
+
+          private
+
+          #: () -> Hash[String, untyped]
+          def masking
+            named = attributes.find { |attribute| attribute_name(attribute) == "on" }
+
+            return {} unless named
+
+            states = static_value(named).to_s.split(/[,\s]+/).reject(&:empty?)
+
+            if states.empty?
+              error("`on` names the states that mask this `<Fragment>`, and it names none.", named.location, suggestion: %(Name at least one state, like `on="album"`.))
+
+              return {}
+            end
+
+            { "on" => states }
+          end
+
+          #: (untyped) -> void
+          def refuse_nested_fragment(fallback)
+            (fallback.body || []).each do |child|
+              next unless Components.element?(child, NAME)
+
+              error("A `<Fragment>` sits inside a `<Fallback>`, which renders once and stays static, so nothing inside it can stay live.", child.location, suggestion: "Move the inner `<Fragment>` next to the outer one.")
+            end
+          end
+
+          #: (Array[untyped]) -> untyped
+          def synthesized_conditional(statements)
+            Herb::AST::ERBIfNode.build(
+              location: @element.location,
+              tag_opening: Herb::Token.from(:erb_start, "<%"),
+              content: Herb::Token.from(:erb_content, " if true "),
+              tag_closing: Herb::Token.from(:erb_end, "%>"),
+              statements: statements,
+              subsequent: nil,
+              end_node: Herb::AST::ERBEndNode.build(
+                location: @element.location,
+                tag_opening: Herb::Token.from(:erb_start, "<%"),
+                content: Herb::Token.from(:erb_content, " end "),
+                tag_closing: Herb::Token.from(:erb_end, "%>")
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/components/lazy.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      module Components
+        # A deferred block the client requests when it nears the viewport, and
+        # never requests for content the reader never reaches.
+        #
+        class Lazy < Deferred
+          NAME = "Lazy" #: String
+
+          private
+
+          #: () -> String
+          def mode
+            "lazy"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/components.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "component_definitions"
+require_relative "components/base"
+require_relative "components/fragment"
+require_relative "components/fallback"
+require_relative "components/deferred"
+require_relative "components/async"
+require_relative "components/lazy"
+
+module Herb
+  class Engine
+    module Slots
+      # The compile-time components a slots template may use.
+      #
+      # A component is a capitalized wrapper tag the slots visitor recognizes and
+      # transforms away before any slot is recorded, so the rendered page never
+      # carries the tag itself. Each built-in lives in its own file under
+      # `components/` and registers here by name.
+      #
+      module Components
+        NAME = /\A[A-Z][A-Za-z0-9]*\z/ #: Regexp
+        REGISTRY = { Fragment::NAME => Fragment, Fallback::NAME => Fallback, Async::NAME => Async, Lazy::NAME => Lazy }.freeze #: Hash[String, singleton(Base)]
+        BUILT_IN = REGISTRY.keys.freeze #: Array[String]
+
+        #: (String?) -> bool
+        def self.component?(tag_name)
+          return false if tag_name.nil?
+
+          tag_name.match?(NAME) && tag_name.match?(/[a-z]/)
+        end
+
+        #: (String) -> singleton(Base)?
+        def self.for(tag_name)
+          REGISTRY[tag_name]
+        end
+
+        #: (untyped, ?String?) -> bool
+        def self.element?(node, name = nil)
+          return false unless node.is_a?(Herb::AST::HTMLElementNode)
+
+          tag_name = node.tag_name&.value
+
+          return false unless component?(tag_name)
+
+          name.nil? || tag_name == name
+        end
+      end
+    end
+  end
+end