herb 0.10.4 → 0.11.0

data/sig/herb/engine/slots/dynamics_compiler.rbs

@@ -0,0 +1,349 @@
+# Generated from lib/herb/engine/slots/dynamics_compiler.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      # Compiles a template into Ruby that returns its dynamic values rather than its HTML.
+      #
+      # `Herb::Engine` answers "what does this template render". This answers "what did the template
+      # evaluate to render it", which is the half that changes when state changes:
+      #
+      #     require "herb/engine/slots/dynamics_compiler"
+      #
+      #     source = Herb::Engine::Slots::DynamicsCompiler.new(%(<h1><%= @title %></h1>)).src
+      #     view.instance_eval(source)
+      #     #=> { template: "app/views/posts/index.html.erb", version: "fd3dfd36", slots: { 0 => "Hello" } }
+      #
+      # The names follow Phoenix LiveView, which splits a rendered template into its `static` strings
+      # and its `dynamic` values for the same reason. A template's statics never change between
+      # renders, so anything re-rendering on a state change only has to send the dynamics.
+      #
+      # This is a separate compiler rather than an option on `Herb::Engine` because that class is a
+      # drop-in for `Erubi::Engine` and has to keep answering the way Erubi does.
+      #
+      # ## Values name the template they came from
+      #
+      # An index means nothing on its own, because it is a position in one template's numbering, and
+      # it means something else in the next template. So the values arrive wrapped in the identifier
+      # and version `Visitor` gave the markers, which is the same pair the page carries in
+      # `<!--herb-region:ID:VERSION-->`. A client holding both can tell that they were compiled
+      # together, and a version that no longer matches says the indices cannot be trusted.
+      #
+      # ## The shape follows the template, not the render
+      #
+      # Every insertion point owns an index, decided while compiling and the same on every render.
+      # Control flow owns one too, because what it decided is itself a value that changes:
+      #
+      #     <% if admin? %><%= secret %><% else %><%= public %><% end %>
+      #     #=> { 0 => { branch: 0, slots: { 1 => "s" } } }   when admin?
+      #     #=> { 0 => { branch: 1, slots: { 2 => "p" } } }   otherwise
+      #
+      # Both branches keep their own indices, so a condition flipping changes which indices are
+      # present and never what an index means.
+      #
+      # ## Absent means it did not run
+      #
+      # A key is missing when the code that would have filled it never ran, which is the same thing
+      # the rendered markup says by not being there. Nothing has to be sent about a branch that was
+      # not taken, and nothing can be learned about one either.
+      #
+      # A conditional and a collection are always present, because both are evaluated on every render
+      # even when they produce nothing. A conditional that matched no branch is `{ branch: nil }` and
+      # an empty collection is `{ items: {} }`, both of which the client has to be told.
+      #
+      # ## Collections group by item
+      #
+      # A collection holds its items in render order, each item carrying the slots inside it:
+      #
+      #     <% users.each do |user| %><%= user.first %> <%= user.last %><% end %>
+      #     #=> { 0 => { items: { 1 => { 1 => "Marco", 2 => "Roth" },
+      #                           2 => { 1 => "Joe",   2 => "Doe" } } } }
+      #
+      # Grouping the other way would give one list per slot and leave the client to zip them back
+      # together, which it cannot do once an item is inserted rather than appended.
+      #
+      # An item is keyed by the key its template declares, through `herb-key` or `id` or a
+      # `<%# herb:key %>` directive, which is what makes it survive being reordered. `Visitor`
+      # decides what that key is and this evaluates it, so an item arrives under the same key the
+      # marker around it carries. A collection that declares none falls back to position.
+      #
+      # ## A partial keeps its own values
+      #
+      # `<%= render "posts/card" %>` evaluates to that partial's own values, so the slot holding it
+      # holds a whole payload rather than a string:
+      #
+      #     { template: "index.html.erb", version: "a1b2c3d4",
+      #       slots: { 0 => { template: "_card.html.erb", version: "e5f6a7b8", slots: { 0 => "Marco" } } } }
+      #
+      # Nothing else would work, because the partial numbers its slots in its own template and the
+      # page marks them out as their own region. Coercing it to a string would flatten a partial's
+      # values into the markup they were meant to replace, and a partial rendering a partial is
+      # ordinary, so this nests as deeply as the template does.
+      #
+      # ## Escaping
+      #
+      # A value carries the escaping of the place it was written, because that is where it is going
+      # back to. The same expression is escaped differently in an attribute, in a `<script>`, and in
+      # text, so the tree is left intact and the compiler decides as it normally would.
+      #
+      # ## Blocks
+      #
+      # A tag that takes a block, such as `<%= form_with do |f| %>`, owns an entry holding everything
+      # the block rendered, because the helper wraps that output in markup of its own that only the
+      # helper can produce. What the template wrote inside the block keeps its own indices alongside:
+      #
+      #     <%= form_with(model: @user) do |f| %><%= f.label %><% end %>
+      #     #=> { 0 => "<form>Name</form>", 1 => "Name" }
+      #
+      # So a caller that can address slot 1 sends a value, and one that cannot falls back to slot 0
+      # and the whole block. Slot 1 is inside slot 0, which the client already has to reason about
+      # for conditionals and collections.
+      #
+      # A block yielding more than once is the exception, since one index cannot stand for the several
+      # values its interior took. `each` and the other iterations are compiled as collections for that
+      # reason, and a helper that yields repeatedly reports the last value its interior took.
+      class DynamicsCompiler < Herb::Engine
+        BUFFER: String
+
+        BLOCK_BUFFER: String
+
+        SLOT_BUFFER: String
+
+        SCOPE_BUFFER: String
+
+        ITEMS_BUFFER: String
+
+        KEY_BUFFER: String
+
+        OCCURRENCE_BUFFER: String
+
+        BRANCHING_NODES: Array[String]
+
+        class Compiler < Herb::Engine::Compiler
+          # : (untyped, ?Hash[Symbol, untyped]) -> void
+          def initialize: (untyped, ?Hash[Symbol, untyped]) -> void
+
+          # : (untyped) -> void
+          def visit_html_attribute_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_html_element_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_content_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_yield_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_render_node: (untyped) -> void
+
+          # : (untyped) { () -> void } -> void
+          def visit_erb_control_node: (untyped) { () -> void } -> void
+
+          # : (untyped) -> void
+          def visit_erb_if_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_unless_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_case_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_case_match_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_iteration_block_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_for_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_while_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_until_node: (untyped) -> void
+
+          # : (untyped) -> void
+          def visit_erb_block_node: (untyped) -> void
+
+          # : () -> void
+          def generate_output: () -> void
+
+          private
+
+          # : (untyped) -> Integer?
+          def claim: (untyped) -> Integer?
+
+          # : (String) -> void
+          def add_expression: (String) -> void
+
+          # : (String) -> void
+          def add_expression_escaped: (String) -> void
+
+          # : (untyped) -> bool
+          def output_block?: (untyped) -> bool
+
+          # : (untyped) -> bool
+          def branch?: (untyped) -> bool
+
+          # : (Integer) -> Integer
+          def next_branch: (Integer) -> Integer
+
+          # : (untyped) { () -> void } -> void
+          def conditional: (untyped) { () -> void } -> void
+
+          # : (untyped, Integer) -> void
+          def own_branches: (untyped, Integer) -> void
+
+          # : (untyped) { (Integer?) -> void } -> void
+          def collection: (untyped) { (Integer?) -> void } -> void
+
+          # : (Integer?) { () -> void } -> void
+          def item: (Integer?) { () -> void } -> void
+
+          # : (Integer) -> String?
+          def item_key: (Integer) -> String?
+
+          # : (untyped, Symbol) -> void
+          def iteration: (untyped, Symbol) -> void
+        end
+
+        class Prune < Herb::Visitor
+          # : (Visitor, Integer) -> void
+          def initialize: (Visitor, Integer) -> void
+
+          # : (untyped) -> void
+          def visit_document_node: (untyped) -> void
+
+          private
+
+          # : (untyped, untyped) -> void
+          def keep: (untyped, untyped) -> void
+
+          # : (untyped, untyped) -> bool
+          def contains?: (untyped, untyped) -> bool
+        end
+
+        attr_reader slot_visitor: Visitor
+
+        # : (String, ?Hash[Symbol, untyped]) -> void
+        def initialize: (String, ?Hash[Symbol, untyped]) -> void
+
+        # : () -> untyped
+        def compiler_class: () -> untyped
+
+        # : (String) -> void
+        def add_text: (String) -> void
+
+        # : (Symbol, *untyped) -> void
+        def add_scope: (Symbol, *untyped) -> void
+
+        # : (String, Symbol?, Integer?, bool, ?nested: bool) -> void
+        def add_dynamic: (String, Symbol?, Integer?, bool, ?nested: bool) -> void
+
+        # : (Integer) -> bool
+        def boolean_presence?: (Integer) -> bool
+
+        # : (String, Integer?, bool) -> void
+        def add_dynamic_block: (String, Integer?, bool) -> void
+
+        # : (String, ?escaped: bool) -> void
+        def add_expression_block_end: (String, ?escaped: bool) -> void
+
+        # : () -> String
+        def inspect: () -> String
+
+        private
+
+        # : (String) -> void
+        def add_postamble: (String) -> void
+
+        # : () -> String
+        def region_seeds: () -> String
+
+        # : () -> void
+        def capture_occurrence: () -> void
+
+        # : () -> String
+        def current_scope: () -> String
+
+        # : (Integer) -> void
+        def scope_open_conditional: (Integer) -> void
+
+        # : (Integer, Integer) -> void
+        def scope_branch: (Integer, Integer) -> void
+
+        # : (Integer, Integer) -> String?
+        def payload_statics: (Integer, Integer) -> String?
+
+        # : () -> bool
+        def server_mode?: () -> bool
+
+        # : (Integer, Integer) -> bool
+        def withheld?: (Integer, Integer) -> bool
+
+        # : (Integer) -> String?
+        def item_statics: (Integer) -> String?
+
+        # : () -> Hash[String, String]
+        def branch_statics: () -> Hash[String, String]
+
+        # : (Integer) -> void
+        def scope_close_conditional: (Integer) -> void
+
+        # : (Integer) -> void
+        def scope_open_collection: (Integer) -> void
+
+        # : (Integer, ?String?) -> void
+        def scope_item_begin: (Integer, ?String?) -> void
+
+        # : (Integer) -> void
+        def scope_item_end: (Integer) -> void
+
+        # : (Integer) -> bool
+        def keyed?: (Integer) -> bool
+
+        # : (Integer) -> String
+        def item_seeds: (Integer) -> String
+
+        # : (Integer) -> void
+        def scope_close_collection: (Integer) -> void
+
+        # : (Integer, String) -> void
+        def scope_open_keyed: (Integer, String) -> void
+
+        # : (Integer) -> void
+        def scope_close_keyed: (Integer) -> void
+
+        # : (Integer) -> void
+        def leave_scope: (Integer) -> void
+
+        # : (String, Symbol?, bool) -> String
+        def dynamic_value: (String, Symbol?, bool) -> String
+
+        # : (Integer, String) -> String
+        def assignment: (Integer, String) -> String
+
+        # : (Integer) -> bool
+        def interpolated?: (Integer) -> bool
+
+        # : (String) -> void
+        def add_block_dynamic: (String) -> void
+
+        # : () -> void
+        def scope_part_open: () -> void
+
+        # : (Integer) -> void
+        def scope_part_close: (Integer) -> void
+
+        # : () -> void
+        def open_block: () -> void
+
+        # : () -> void
+        def close_block: () -> void
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/identifier.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/herb/engine/slots/identifier.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      # What a template is called on the wire. Markers, the values payload and the dependency map all
+      # name a template, and they only name the same one when they all follow this rule.
+      class Identifier
+        STRATEGIES: Array[Symbol]
+
+        # : ((Symbol | ^(String) -> String)) -> void
+        def initialize: (Symbol | ^(String) -> String) -> void
+
+        # : (String) -> String
+        def call: (String) -> String
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/manifest/channel.rbs

@@ -0,0 +1,49 @@
+# Generated from lib/herb/engine/slots/manifest/channel.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      module Manifest
+        # What every template on a page said about itself, collected once however many times those
+        # templates rendered.
+        #
+        # A template compiled with `deliver: :hoist` registers here as it renders:
+        #
+        #     ::Herb::Engine::Slots::Manifest::Channel.record("app/views/posts/_card.html.erb:a1b2c3d4", "{...}")
+        #
+        # It is a channel on the session the page is collecting into, so it registers itself the first
+        # time anything records, and nothing in `Report` or `Session` has to know it exists. A manifest
+        # is decided when a file is compiled, so the first template to record a version says everything
+        # there is to say about it and every later rendering costs nothing.
+        class Channel
+          NAME: Symbol
+
+          ATTRIBUTE: String
+
+          ANCHOR: Symbol
+
+          # : (String, String) -> void
+          def self.record: (String, String) -> void
+
+          # : () -> void
+          def initialize: () -> void
+
+          # : (String, String) -> void
+          def add: (String, String) -> void
+
+          # : () -> Hash[String, String]
+          def manifests: () -> Hash[String, String]
+
+          # : () -> Symbol
+          def anchor: () -> Symbol
+
+          # : () -> bool
+          def empty?: () -> bool
+
+          # : () -> String
+          def to_html: () -> String
+        end
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/manifest/collector.rbs

@@ -0,0 +1,45 @@
+# Generated from lib/herb/engine/slots/manifest/collector.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      module Manifest
+        # What a set of templates says about itself, gathered without rendering any of them.
+        #
+        # A manifest is decided when a file is compiled, so everything a page needs to know about
+        # its templates is knowable ahead of time. This compiles each file for that and nothing
+        # else, which is what makes it possible to write the manifests into an asset and have
+        # templates carry none of them:
+        #
+        #     collector = Herb::Engine::Slots::Manifest::Collector.new(project_path: root)
+        #
+        #     collector.add("app/views/posts/_card.html.erb")
+        #     collector.add("app/views/posts/index.html.erb")
+        #
+        #     collector.to_json #=> the one file those templates add up to
+        #
+        # Which files to give it, and where the asset goes, is the job of whatever integrates Herb
+        # with a framework. This knows how to compile and what to keep.
+        class Collector < Engine::Collector
+          # : (?identifier: untyped?, ?project_path: (String | Pathname)?, **untyped) -> void
+          def initialize: (?identifier: untyped?, ?project_path: (String | Pathname)?, **untyped) -> void
+
+          # : ((String | Pathname), ?String?) -> String?
+          def add: (String | Pathname, ?String?) -> String?
+
+          # : () -> Hash[String, Hash[String, untyped]]
+          def manifests: () -> Hash[String, Hash[String, untyped]]
+
+          # : () -> bool
+          def empty?: () -> bool
+
+          # : () -> String
+          def to_json: () -> String
+
+          # : () -> String
+          def inspect: () -> String
+        end
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/markers.rbs

@@ -0,0 +1,85 @@
+# Generated from lib/herb/engine/slots/markers.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      class Markers
+        DEFAULT_TYPE: Symbol
+
+        ITEM_STATICS: String
+
+        SEED_VALUE_TYPES: String
+
+        PREFIX: String
+
+        COMMENT: Regexp
+
+        # : (String) -> bool
+        def self.marker?: (String) -> bool
+
+        # : (String) -> String
+        def self.seeds_expression: (String) -> String
+
+        # : (Integer, Symbol) -> String
+        def slot_open: (Integer, Symbol) -> String
+
+        # : (Array[[Integer, Symbol, String?]]) -> String
+        def element_anchors: (Array[[ Integer, Symbol, String? ]]) -> String
+
+        # : (Integer) -> String
+        def slot_close: (Integer) -> String
+
+        # : (Integer, Integer | String) -> String
+        def branch: (Integer, Integer | String) -> String
+
+        # : (Integer, Integer | String) -> String
+        def statics_key: (Integer, Integer | String) -> String
+
+        # : (Integer) -> String
+        def item_statics_key: (Integer) -> String
+
+        # : () -> String
+        def seeds_open_prefix: () -> String
+
+        # : () -> String
+        def seeds_open_suffix: () -> String
+
+        # : (Integer) -> String
+        def keyed_open_prefix: (Integer) -> String
+
+        # : () -> String
+        def keyed_open_suffix: () -> String
+
+        # : (Integer) -> String
+        def item_open_prefix: (Integer) -> String
+
+        # : () -> String
+        def item_open_suffix: () -> String
+
+        # : (Integer) -> String
+        def item_close: (Integer) -> String
+
+        # : (String, String) -> String
+        def region_open_prefix: (String, String) -> String
+
+        # : () -> String
+        def region_open_suffix: () -> String
+
+        # : (String) -> String
+        def region_close: (String) -> String
+
+        # : (String, String) -> String
+        def statics_open: (String, String) -> String
+
+        # : () -> String
+        def statics_close: () -> String
+
+        # : () -> String
+        def manifests_open: () -> String
+
+        # : () -> String
+        def manifests_close: () -> String
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/render_bindings.rbs

@@ -0,0 +1,69 @@
+# Generated from lib/herb/engine/slots/render_bindings.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      # Reads the `state:` entries off a render call and answers the call without them.
+      #
+      # The parser already took the hash apart into one declaration node per entry, with the
+      # kind it would give a `herb:state` default, so a value the parser calls bare is a
+      # candidate for a binding to one of the caller's states and anything else is a seed.
+      # The splice works on the argument's location, turned into an index into the tag's
+      # content, so the stripped call is the original source minus exactly the `state:`
+      # argument and the comma that carried it.
+      module RenderBindings
+        BARE_IDENTIFIER: Regexp
+
+        SPLAT: String
+
+        REFUSED: Hash[Symbol, String]
+
+        class Entry < Data
+          attr_reader name(): String
+
+          attr_reader source(): String
+
+          attr_reader candidate(): String?
+
+          attr_reader kind(): Symbol
+
+          attr_reader location(): Herb::Location?
+
+          def self.new: (String name, String source, String? candidate, Symbol kind, Herb::Location? location) -> instance
+                      | (name: String, source: String, candidate: String?, kind: Symbol, location: Herb::Location?) -> instance
+
+          def self.members: () -> [ :name, :source, :candidate, :kind, :location ]
+
+          def members: () -> [ :name, :source, :candidate, :kind, :location ]
+        end
+
+        class Analysis < Data
+          attr_reader entries(): Array[Entry]
+
+          attr_reader stripped(): String
+
+          attr_reader problems(): Array[[ String, String, Herb::Location? ]]
+
+          def self.new: (Array[Entry] entries, String stripped, Array[[ String, String, Herb::Location? ]] problems) -> instance
+                      | (entries: Array[Entry], stripped: String, problems: Array[[ String, String, Herb::Location? ]]) -> instance
+
+          def self.members: () -> [ :entries, :stripped, :problems ]
+
+          def members: () -> [ :entries, :stripped, :problems ]
+        end
+
+        # : (untyped) -> Analysis?
+        def self.analyze: (untyped) -> Analysis?
+
+        # : (untyped, Array[Entry], Array[[String, String, Herb::Location?]]) -> void
+        def self.collect: (untyped, Array[Entry], Array[[ String, String, Herb::Location? ]]) -> void
+
+        # : (untyped, Herb::Location) -> String?
+        def self.strip: (untyped, Herb::Location) -> String?
+
+        # : (untyped, Herb::Position) -> Integer?
+        def self.index_in: (untyped, Herb::Position) -> Integer?
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/schema_compiler.rbs

@@ -0,0 +1,62 @@
+# Generated from lib/herb/engine/slots/schema_compiler.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      # Compiles a template into what a browser needs to know about its slots, without
+      # rendering anything.
+      #
+      # Slot identity depends on every visitor that runs before the slot visitor, and only
+      # the host knows its stack, so the host hands one over and this runs it. The stack
+      # arrives as a builder returning fresh visitors, because a visitor is stateful and the
+      # statics need a second compile:
+      #
+      #     result = Herb::Engine::Slots::SchemaCompiler.call(
+      #       source,
+      #       filename: "app/views/posts/index.html.erb",
+      #       mode: :client,
+      #       visitors: -> { [Herb::Engine::Validators::SecurityValidator.new(fatal: false)] }
+      #     )
+      #
+      #     result.version        #=> "5d1e0c77"
+      #     result.manifest       #=> what the page's manifest says
+      #     result.static_markup  #=> the markup with every slot as an empty marker pair
+      #
+      # A nil `mode` means slots are off for this template. The stack still runs so its
+      # diagnostics still flow, and everything slot-shaped comes back nil.
+      class SchemaCompiler
+        class Result < Data
+          attr_reader mode(): Symbol?
+
+          attr_reader manifest(): Hash[String, untyped]?
+
+          attr_reader version(): String?
+
+          attr_reader slot_entries(): Array[Hash[Symbol, untyped]]?
+
+          attr_reader statics(): Hash[String, String]?
+
+          attr_reader static_markup(): String?
+
+          attr_reader diagnostics(): Array[Herb::Diagnostic]
+
+          def self.new: (Symbol? mode, Hash[String, untyped]? manifest, String? version, Array[Hash[Symbol, untyped]]? slot_entries, Hash[String, String]? statics, String? static_markup, Array[Herb::Diagnostic] diagnostics) -> instance
+                      | (mode: Symbol?, manifest: Hash[String, untyped]?, version: String?, slot_entries: Array[Hash[Symbol, untyped]]?, statics: Hash[String, String]?, static_markup: String?, diagnostics: Array[Herb::Diagnostic]) -> instance
+
+          def self.members: () -> [ :mode, :manifest, :version, :slot_entries, :statics, :static_markup, :diagnostics ]
+
+          def members: () -> [ :mode, :manifest, :version, :slot_entries, :statics, :static_markup, :diagnostics ]
+        end
+
+        # : (String, filename: String, mode: Symbol?, ?visitors: ^() -> Array[::Herb::Visitor], ?engine: singleton(::Herb::Engine), ?options: Hash[Symbol, untyped]) -> Result
+        def self.call: (String, filename: String, mode: Symbol?, ?visitors: ^() -> Array[::Herb::Visitor], ?engine: singleton(::Herb::Engine), ?options: Hash[Symbol, untyped]) -> Result
+
+        # : (singleton(::Herb::Engine), String, String, Array[::Herb::Visitor], Hash[Symbol, untyped]) -> void
+        def self.compile: (singleton(::Herb::Engine), String, String, Array[::Herb::Visitor], Hash[Symbol, untyped]) -> void
+
+        # : (Array[::Herb::Visitor]) -> Array[Herb::Diagnostic]
+        def self.collect: (Array[::Herb::Visitor]) -> Array[Herb::Diagnostic]
+      end
+    end
+  end
+end