herb 0.10.4 → 0.11.0

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

@@ -0,0 +1,62 @@
+# Generated from lib/herb/engine/slots/callee.rb with RBS::Inline
+
+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
+        class Declared < Data
+          attr_reader name(): String
+
+          attr_reader kind(): Symbol
+
+          attr_reader derived(): bool
+
+          attr_reader counted(): bool
+
+          def self.new: (String name, Symbol kind, bool derived, bool counted) -> instance
+                      | (name: String, kind: Symbol, derived: bool, counted: bool) -> instance
+
+          def self.members: () -> [ :name, :kind, :derived, :counted ]
+
+          def members: () -> [ :name, :kind, :derived, :counted ]
+        end
+
+        COMPILING: Symbol
+
+        CACHE_LIMIT: Integer
+
+        # : (Pathname | String) -> Callee?
+        def self.for: (Pathname | String) -> Callee?
+
+        # : () -> void
+        def self.reset!: () -> void
+
+        attr_reader path: Pathname
+
+        attr_reader diagnostics: Array[Herb::Diagnostic]
+
+        # : (Pathname) -> void
+        def initialize: (Pathname) -> void
+
+        # : (String) -> Declared?
+        def declaration: (String) -> Declared?
+
+        # : () -> Array[String]
+        def names: () -> Array[String]
+
+        # : () -> Array[Herb::Diagnostic]
+        def errors: () -> Array[Herb::Diagnostic]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# Generated from lib/herb/engine/slots/component_definitions.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      # The built-in components a slots template may use, and what each one takes.
+      module ComponentDefinitions
+        COMPONENTS: Hash[String, { void: bool, deferred: bool, parents: Array[String]?, description: String, attributes: Hash[String, Hash[Symbol, String]] }]
+
+        BUILT_IN: Array[String]
+
+        DEFERRED: Array[String]
+
+        # : (String) -> Hash[String, Hash[Symbol, String]]
+        def self.attributes_for: (String) -> Hash[String, Hash[Symbol, String]]
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/components/async.rbs

@@ -0,0 +1,20 @@
+# Generated from lib/herb/engine/slots/components/async.rb with RBS::Inline
+
+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: String
+
+          private
+
+          # : () -> String
+          def mode: () -> String
+        end
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/components/base.rbs

@@ -0,0 +1,60 @@
+# Generated from lib/herb/engine/slots/components/base.rb with RBS::Inline
+
+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: (untyped, untyped) -> Array[untyped]
+
+          # : (untyped, untyped) -> void
+          def initialize: (untyped, untyped) -> void
+
+          # : () -> Array[untyped]
+          def transform: () -> Array[untyped]
+
+          # : () -> Array[String]
+          def allowed_attributes: () -> Array[String]
+
+          # : () -> void
+          def refuse_unknown_attributes: () -> void
+
+          private
+
+          # : () -> Hash[String, Hash[Symbol, String]]
+          def attribute_definitions: () -> Hash[String, Hash[Symbol, String]]
+
+          # : () -> Hash[String, Integer]
+          def timing: () -> Hash[String, Integer]
+
+          # : () -> String
+          def tag_name: () -> String
+
+          # : () -> Array[untyped]
+          def children: () -> Array[untyped]
+
+          # : () -> Array[untyped]
+          def attributes: () -> Array[untyped]
+
+          # : (untyped) -> String?
+          def attribute_name: (untyped) -> String?
+
+          # : (untyped) -> String?
+          def static_value: (untyped) -> String?
+
+          # : (String, untyped, ?suggestion: String?) -> nil
+          def error: (String, untyped, ?suggestion: String?) -> nil
+
+          # : (String, untyped, ?suggestion: String?) -> void
+          def warning: (String, untyped, ?suggestion: String?) -> void
+        end
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/components/deferred.rbs

@@ -0,0 +1,29 @@
+# Generated from lib/herb/engine/slots/components/deferred.rb with RBS::Inline
+
+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: () -> Array[untyped]
+
+          private
+
+          # : () -> String
+          def mode: () -> String
+
+          # : (String, Array[untyped], untyped) -> untyped
+          def deferred_conditional: (String, Array[untyped], untyped) -> untyped
+        end
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/components/fallback.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/herb/engine/slots/components/fallback.rb with RBS::Inline
+
+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: String
+
+          # : () -> Array[untyped]
+          def transform: () -> Array[untyped]
+        end
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/components/fragment.rbs

@@ -0,0 +1,34 @@
+# Generated from lib/herb/engine/slots/components/fragment.rb with RBS::Inline
+
+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: String
+
+          # : () -> Array[untyped]
+          def transform: () -> Array[untyped]
+
+          private
+
+          # : () -> Hash[String, untyped]
+          def masking: () -> Hash[String, untyped]
+
+          # : (untyped) -> void
+          def refuse_nested_fragment: (untyped) -> void
+
+          # : (Array[untyped]) -> untyped
+          def synthesized_conditional: (Array[untyped]) -> untyped
+        end
+      end
+    end
+  end
+end

data/sig/herb/engine/slots/components/lazy.rbs

@@ -0,0 +1,20 @@
+# Generated from lib/herb/engine/slots/components/lazy.rb with RBS::Inline
+
+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: String
+
+          private
+
+          # : () -> String
+          def mode: () -> String
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# Generated from lib/herb/engine/slots/components.rb with RBS::Inline
+
+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: Regexp
+
+        REGISTRY: Hash[String, singleton(Base)]
+
+        BUILT_IN: Array[String]
+
+        # : (String?) -> bool
+        def self.component?: (String?) -> bool
+
+        # : (String) -> singleton(Base)?
+        def self.for: (String) -> singleton(Base)?
+
+        # : (untyped, ?String?) -> bool
+        def self.element?: (untyped, ?String?) -> bool
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# Generated from lib/herb/engine/slots/dependencies/channel.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      class Dependencies
+        # The state map a page is driven by, carried once for the response it belongs to.
+        #
+        # A map is built from the template an action rendered, so there is one for a page however
+        # many templates it is made of. The host decides which template that is and hands the map
+        # over as it renders:
+        #
+        #     ::Herb::Engine::Slots::Dependencies::Channel.record(json)
+        #
+        # Where it lands is the middleware's business, which is what keeps a host from splicing
+        # markup into a response itself.
+        class Channel
+          NAME: Symbol
+
+          ATTRIBUTE: String
+
+          ANCHOR: Symbol
+
+          # : () -> String?
+          attr_reader json: untyped
+
+          # : (String) -> String
+          def self.tag: (String) -> String
+
+          # : (String) -> void
+          def self.record: (String) -> void
+
+          # : () -> void
+          def initialize: () -> void
+
+          # : (String) -> void
+          def add: (String) -> void
+
+          # : () -> Symbol
+          def anchor: () -> Symbol
+
+          # : () -> bool
+          def empty?: () -> bool
+
+          # : () -> String
+          def to_html: () -> String
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# Generated from lib/herb/engine/slots/dependencies.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Slots
+      # Says which state each of a template's slots reads, and where that slot's next value can come
+      # from:
+      #
+      #     Herb::Engine::Slots::Dependencies.new(project_path).slots_for("app/views/posts/index.html.erb")
+      #     #=> { 0 => { state: ["@items"], mode: :structural },
+      #           1 => { state: ["@items"], mode: :derived } }
+      #
+      # `Visitor` records a `node_path` for every slot and `TemplateDependencies` reports one for
+      # every node a state reaches, so the two are joined on that path.
+      #
+      # A mode says who can produce the next value. `identity` is a slot whose expression is the
+      # state itself, so a client writes it by copying what it was given. `structural` is a
+      # conditional or a collection, which a client can only rebuild from markup the server parked.
+      # `derived` is an expression that has to be evaluated, and evaluating it means running Ruby.
+      #
+      # A conditional is reported against its own condition rather than everything inside it. What
+      # the branches read belongs to the slots in them, which carry their own state.
+      class Dependencies
+        # : (String | Pathname, ?compile: ^(String, String) -> untyped) -> void
+        def initialize: (String | Pathname, ?compile: ^(String, String) -> untyped) -> void
+
+        # : (String) -> Hash[String, Array[Hash[Symbol, untyped]]]
+        def across: (String) -> Hash[String, Array[Hash[Symbol, untyped]]]
+
+        # : (String, Array[String]) -> Array[Hash[Symbol, untyped]]
+        def subtree_slots: (String, Array[String]) -> Array[Hash[Symbol, untyped]]
+
+        # : (String, ?params: Hash[String, String]) -> Hash[String, untyped]
+        def payload: (String, ?params: Hash[String, String]) -> Hash[String, untyped]
+
+        # : (String, ?params: Hash[String, String]) -> String
+        def envelope: (String, ?params: Hash[String, String]) -> String
+
+        # : (String, ?params: Hash[String, String]) -> String
+        def dependencies_tag: (String, ?params: Hash[String, String]) -> String
+
+        # : (String, ?params: Hash[String, String]) -> void
+        def deliver: (String, ?params: Hash[String, String]) -> void
+
+        # : (String) -> Hash[Integer, Hash[Symbol, untyped]]
+        def slots_for: (String) -> Hash[Integer, Hash[Symbol, untyped]]
+
+        # : (String) -> String
+        def version_for: (String) -> String
+
+        private
+
+        # : (String, ?Array[String]?) -> Hash[Symbol, untyped]
+        def template: (String, ?Array[String]?) -> Hash[Symbol, untyped]
+
+        # : (String, Array[String]?) -> Hash[Symbol, untyped]
+        def build: (String, Array[String]?) -> Hash[Symbol, untyped]
+
+        # : (untyped, ?Array[Hash[Symbol, untyped]], ?per_item: bool) -> Array[Hash[Symbol, untyped]]
+        def reached_slots: (untyped, ?Array[Hash[Symbol, untyped]], ?per_item: bool) -> Array[Hash[Symbol, untyped]]
+
+        # : (Symbol, bool) -> Symbol
+        def mode_within: (Symbol, bool) -> Symbol
+
+        # : (untyped, untyped) -> bool
+        def per_item?: (untyped, untyped) -> bool
+
+        # : (String, Array[String], Hash[String, String]) -> Hash[String, String]
+        def request_names: (String, Array[String], Hash[String, String]) -> Hash[String, String]
+
+        # : (String) -> String
+        def identifier_for: (String) -> String
+
+        # : (String) -> String
+        def relative_to_project: (String) -> String
+
+        # : (String) -> String
+        def absolute: (String) -> String
+
+        # : (String, String) -> untyped
+        def visitor_for: (String, String) -> untyped
+
+        # : (untyped, String, Array[String]) -> Hash[String, Hash[Array[Integer], Array[String?]]]
+        def reached_paths: (untyped, String, Array[String]) -> Hash[String, Hash[Array[Integer], Array[String?]]]
+
+        # : (untyped) -> Array[String]
+        def state_names: (untyped) -> Array[String]
+
+        # : (untyped, Array[String], Array[String?], Set[String]) -> Symbol
+        def mode_for: (untyped, Array[String], Array[String?], Set[String]) -> Symbol
+      end
+    end
+  end
+end