weft 0.1.0 → 0.2.0

data/lib/weft/context/traversal.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "arbre"
+
+module Weft
+  class Context < Arbre::Context
+    # Render-tree navigation for components and pages: reach an ancestor — or
+    # self — in the Arbre tree by type or tag, to read its identity (class,
+    # weft_dom_id, route, page path). This is the "child affects ancestor"
+    # affordance: a nested component discovers what it needs to target instead
+    # of being hand-fed its parent's identity.
+    #
+    # Mixed into Weft::Component and Weft::Page (not Context itself — the tree's
+    # root has no ancestors to walk). Lives here beside Interception as the
+    # other render-context mechanism the two share.
+    #
+    # Call inside `build`. (There is no instance, and no render tree to walk,
+    # inside a verb block.) Lean on the ancestor's identity and params — fixed
+    # at construction — rather than state its own `build` may not have set yet,
+    # since it is mid-build above you.
+    module Traversal
+      # The nearest node matching +matcher+, self included, walking up the tree —
+      # impedance-matched to the DOM's Element.closest(): include-self,
+      # nearest-first, nil if none.
+      #
+      #   closest(Weft::Page)                     # nearest enclosing page
+      #   closest(OrdersPanel)                    # nearest panel of that type
+      #   closest(Paginatable)                    # nearest node playing that role
+      #   closest(:div)                           # nearest <div> (self included)
+      #   closest(Weft::Component) { |c| c.params.key?(:order_id) }  # refined
+      #
+      # +matcher+ is a Class/Module (matched is_a?, subclass- and
+      # include-inclusive) or a Symbol (matched against tag_name). An optional
+      # block refines: a candidate must match the positional AND the block.
+      # Returns the matching Arbre node — a component for a class match, a plain
+      # element for a tag — or nil.
+      def closest(matcher, include_self: true, &refine)
+        unless matcher.is_a?(Module) || matcher.is_a?(Symbol)
+          raise ArgumentError,
+                "closest matcher must be a Class, Module, or Symbol tag name (got #{matcher.class})"
+        end
+
+        node = include_self ? self : parent
+        while node
+          return node if traversal_match?(node, matcher, refine)
+
+          node = node.parent
+        end
+        nil
+      end
+
+      # closest strictly above self (self excluded) — the expressive read for
+      # "reach my enclosing X". Does not take include_self; use closest for that.
+      def enclosing(matcher, &) = closest(matcher, include_self: false, &)
+
+      # closest that raises Weft::AncestorNotFound instead of returning nil — for
+      # a component that requires the ancestor (pair with dependent!).
+      def closest!(matcher, include_self: true, &)
+        closest(matcher, include_self: include_self, &) ||
+          raise(Weft::AncestorNotFound,
+                "no #{matcher.inspect} #{include_self ? 'at or above' : 'above'} #{self.class}")
+      end
+
+      # enclosing that raises instead of returning nil.
+      def enclosing!(matcher, &) = closest!(matcher, include_self: false, &)
+
+      private
+
+      def traversal_match?(node, matcher, refine)
+        matched =
+          if matcher.is_a?(Symbol)
+            node.respond_to?(:tag_name) && node.tag_name.to_s == matcher.to_s
+          else
+            node.is_a?(matcher)
+          end
+        matched && (refine.nil? || refine.call(node))
+      end
+    end
+  end
+end

data/lib/weft/context/wiring.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "arbre"
+require "uri"
+
+require "weft/action"
+
+module Weft
+  class Context < Arbre::Context
+    # The low-level wiring layer under the kwarg grammar: htmx attribute
+    # builders and render-tree lookups. Context::Expansion decides WHICH
+    # interaction claims an element; these methods build the actual hx-*
+    # hashes and find the components they point at. Mixed into Weft::Context
+    # alongside Expansion and Modifiers (whose resolve_swap/resolve_target
+    # vocabulary the builders lean on).
+    module Wiring
+      private
+
+      # On <form> elements, also emit the HTML action and method attributes so
+      # non-JS submission works (browser POSTs to the same URL htmx would).
+      # Drop hx-vals because the form fields are the submission payload —
+      # hx-vals would duplicate or shadow them.
+      def augment_for_form(expanded, action, htmx)
+        url = htmx["hx-#{action.method}"]
+        expanded.except("hx-vals").merge("action" => url, "method" => action.method.to_s)
+      end
+
+      def navigate_attrs(component, overrides)
+        {
+          "hx-get" => component.weft_url(**overrides),
+          "hx-target" => "##{component.weft_dom_id}",
+          "hx-swap" => "outerHTML"
+        }
+      end
+
+      def preset_wiring(attrs, target_or_url, preset, swap, target)
+        htmx = if target_or_url.is_a?(String)
+                 htmx_get_attrs(target_or_url, swap, target)
+               else
+                 loads_attrs(target_or_url, resolve_with(attrs), swap, target)
+               end
+        htmx["hx-trigger"] = resolve_trigger(preset[:trigger]) if preset[:trigger]
+        htmx
+      end
+
+      def loads_attrs(target_class, with_attrs, swap, target)
+        htmx_get_attrs(component_url(target_class, with_attrs), swap, target)
+      end
+
+      def component_url(target_class, with_attrs)
+        path = target_class.resolved_component_path
+        params = with_attrs.compact
+        params.empty? ? path : "#{path}?#{URI.encode_www_form(params)}"
+      end
+
+      def htmx_get_attrs(url, swap, target)
+        {
+          "hx-get" => url,
+          "hx-swap" => Action.resolve_swap(swap),
+          "hx-target" => resolve_target(target)
+        }
+      end
+
+      def find_action_context(action_name)
+        el = current_arbre_element
+        while el
+          return el if el.is_a?(Weft::Component) && el.class.action_for(action_name)
+
+          el = el.parent
+        end
+        nil
+      end
+
+      def find_nearest_component
+        el = current_arbre_element
+        while el
+          return el if el.is_a?(Weft::Component)
+
+          el = el.parent
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/weft/context.rb

@@ -1,184 +1,90 @@
 # frozen_string_literal: true
 
+require "arbre"
+
+require "weft/context/expansion"
 require "weft/context/interception"
+require "weft/context/modifiers"
+require "weft/context/wiring"
 
 module Weft
-  # Arbre::Context subclass that intercepts element creation to expand
-  # Weft kwargs into htmx attributes.
+  # Arbre::Context subclass that intercepts element creation to expand Weft
+  # kwargs into htmx attributes — the kwarg vocabulary and its claim rules
+  # live in Context::Expansion.
   #
   # Works at every nesting depth because Arbre instance_evals the top-level
   # block, making the Context the receiver for all insert_tag calls throughout
   # the element tree.
-  #
-  # Supported kwargs:
-  # - `action: :name` — expands into htmx attrs for a declared performs/transfers action
-  # - `navigate: { key: val }` — expands into htmx GET to self with overridden attrs
-  # - `trigger: "event"` — sets hx-trigger (standalone or alongside action:/navigate:)
   class Context < Arbre::Context
+    include Expansion
     include Interception
-
-    # @api private
-    # Expands Weft kwargs into htmx attributes. Invoked by the Interception
-    # mixin's #insert_tag on the root Weft::Context (via +arbre_context+).
-    def expand_weft_attrs(attrs, for_class: nil)
-      attrs = attrs.dup
-      custom_trigger = attrs.delete(:trigger)
-      push_url = attrs.delete(:push_url)
-      attrs = expand_action(attrs, for_class: for_class) || expand_navigate(attrs) || expand_loads(attrs) ||
-              expand_shorthand(attrs) || attrs
-      attrs["hx-trigger"] = resolve_trigger(custom_trigger) if custom_trigger
-      attrs["hx-push-url"] = push_url.to_s if push_url
-      attrs
+    include Modifiers
+    include Wiring
+
+    # The render's wire params (query/body/path values), carried on the
+    # context so every component in the tree resolves its own declared
+    # params at any depth. Assigned before super because Arbre's initialize
+    # instance_evals the construction block — the tree builds during super.
+    attr_reader :wire_params
+
+    # Request-scoped overlay values — the accumulated verb-block deltas
+    # (action callable returns, includes deltas, recovery injections). In
+    # the source stack an overlay entry speaks AS the wire for its key:
+    # a value overrides the wire's, a nil clears it (resolution falls
+    # below). One universe per request; these are its amendments.
+    attr_reader :overlays
+
+    # A bag for ROOT components to branch from, standing in for the tree
+    # ancestor a root doesn't have — how an OOB companion inherits its
+    # primary's bag (rich values included) exactly like a child built in
+    # the primary's own build.
+    attr_reader :branch_bag
+
+    # The DOM ids this RESPONSE has already spoken for — a Set shared across
+    # every context the response builds in, because the primary and each of
+    # its companions get their own. An out-of-band swap is addressed by DOM
+    # id, so only one fragment per id can land; a root component claims its
+    # id as it builds (Component#claim_dom_slot!) and a second claimant
+    # abandons its render by throwing SLOT_TAKEN. Absent on renders with
+    # nothing to arbitrate, and nothing is claimed then.
+    attr_reader :slots
+
+    # Thrown with the contested DOM id when a root loses a slot. Caught by
+    # whoever asked for the render; nothing partial reaches the tree, because
+    # Arbre adds a tag to its parent only after the build returns.
+    SLOT_TAKEN = :weft_slot_taken
+
+    # Two positional parameters are Arbre's own signature; the four keywords
+    # are Weft's render-scoped channels, each independently optional. That
+    # they have grown to four is a fair signal that they want a render-environment
+    # object of their own — a change that would touch every render path and
+    # a documented constructor, so it belongs with the lifecycle work, not here.
+    def initialize(assigns = {}, helpers = nil, wire_params: nil, overlays: nil, # rubocop:disable Metrics/ParameterLists
+                   branch_bag: nil, slots: nil, &)
+      @wire_params = wire_params || {}
+      @overlays = overlays || {}
+      @branch_bag = branch_bag
+      @slots = slots
+      super(assigns, helpers, &)
     end
 
     # @api private
-    # Guard check for whether an attrs hash carries any Weft kwarg. Invoked by
-    # the Interception mixin's #insert_tag on the root Weft::Context (via
-    # +arbre_context+).
-    def weft_kwarg?(hash)
-      hash[:action].is_a?(Symbol) || hash.key?(:trigger) || hash[:navigate].is_a?(Hash) ||
-        hash[:loads].is_a?(Class) || hash.key?(:push_url) || find_shorthand_kwarg(hash)
-    end
-
-    private
-
-    def expand_action(attrs, for_class: nil)
-      action_name = attrs[:action]
-      return unless action_name.is_a?(Symbol)
-
-      component = find_action_context(action_name)
-      return unless component
-
-      action = component.class.action_for(action_name)
-      htmx = action.to_htmx_attrs(component)
-      expanded = attrs.except(:action).merge(htmx)
-      return augment_for_form(expanded, action, htmx) if for_class && for_class <= Arbre::HTML::Form
-
-      expanded
-    end
-
-    # On <form> elements, also emit the HTML action and method attributes so
-    # non-JS submission works (browser POSTs to the same URL htmx would).
-    # Drop hx-vals because the form fields are the submission payload —
-    # hx-vals would duplicate or shadow them.
-    def augment_for_form(expanded, action, htmx)
-      url = htmx["hx-#{action.method}"]
-      expanded.except("hx-vals").merge("action" => url, "method" => action.method.to_s)
-    end
-
-    def expand_navigate(attrs)
-      overrides = attrs[:navigate]
-      return unless overrides.is_a?(Hash)
-
-      component = find_nearest_component
-      return unless component
-
-      attrs.except(:navigate).merge(navigate_attrs(component, overrides))
-    end
-
-    def expand_loads(attrs)
-      target_class = attrs[:loads]
-      return unless target_class.is_a?(Class)
-
-      validate_loads_kwargs!(attrs)
-      remaining = attrs.except(:loads, :swap, :target, :with)
-      remaining.merge(loads_attrs(target_class, resolve_with(attrs), attrs[:swap], attrs[:target]))
-    end
-
-    def expand_shorthand(attrs)
-      shorthand_key, target_class = find_shorthand_kwarg(attrs)
-      return unless shorthand_key
-
-      build_shorthand_attrs(attrs, shorthand_key, target_class, Weft.shorthand(shorthand_key))
-    end
-
-    # A shorthand value is either a target Class (derive the URL from it) or a
-    # ready-made URL String (retry-style — the caller already has the URL).
-    def find_shorthand_kwarg(attrs)
-      attrs.find { |k, v| (v.is_a?(Class) || v.is_a?(String)) && Weft.shorthand(k) }
+    # One-shot register for `receives` hand-offs. Interception stages the
+    # extracted kwargs here immediately before Arbre constructs the target
+    # (insert_tag → build_tag → new); the new instance consumes them during
+    # params assembly. Class-checked so a stale staging can never leak into
+    # a different component's bag.
+    def stage_received(klass, values)
+      @staged_received = [klass, values]
     end
 
-    def build_shorthand_attrs(attrs, shorthand_key, target_or_url, preset)
-      target = attrs[:target] || preset[:target]
-      raise ArgumentError, "#{shorthand_key}: requires target: (e.g., target: :self)" unless target
-
-      swap = attrs[:swap] || preset[:swap]
-      htmx = if target_or_url.is_a?(String)
-               htmx_get_attrs(target_or_url, swap, target)
-             else
-               loads_attrs(target_or_url, resolve_with(attrs), swap, target)
-             end
-      htmx["hx-trigger"] = resolve_trigger(preset[:trigger]) if preset[:trigger]
-      attrs.except(shorthand_key, :swap, :target, :with).merge(htmx)
-    end
-
-    def resolve_with(attrs)
-      attrs[:with] || find_nearest_component&.attrs&.to_h || {}
-    end
-
-    def validate_loads_kwargs!(attrs)
-      raise ArgumentError, "loads: requires swap: (e.g., swap: :fill)" unless attrs[:swap]
-      raise ArgumentError, "loads: requires target: (e.g., target: :self)" unless attrs[:target]
-    end
-
-    def find_action_context(action_name)
-      el = current_arbre_element
-      while el
-        return el if el.is_a?(Weft::Component) && el.class.action_for(action_name)
-
-        el = el.parent
-      end
-      nil
-    end
-
-    def find_nearest_component
-      el = current_arbre_element
-      while el
-        return el if el.is_a?(Weft::Component)
-
-        el = el.parent
-      end
-      nil
-    end
-
-    def navigate_attrs(component, overrides)
-      {
-        "hx-get" => component.weft_url(**overrides),
-        "hx-target" => "##{component.weft_id}",
-        "hx-swap" => "outerHTML"
-      }
-    end
-
-    def loads_attrs(target_class, with_attrs, swap, target)
-      htmx_get_attrs(component_url(target_class, with_attrs), swap, target)
-    end
-
-    def component_url(target_class, with_attrs)
-      path = target_class.resolved_component_path
-      params = with_attrs.compact
-      params.empty? ? path : "#{path}?#{URI.encode_www_form(params)}"
-    end
-
-    def htmx_get_attrs(url, swap, target)
-      {
-        "hx-get" => url,
-        "hx-swap" => Action.resolve_swap(swap),
-        "hx-target" => resolve_target(target)
-      }
-    end
-
-    def resolve_target(target)
-      case target
-      when :self then "this"
-      when String then target
-      else
-        # Arbre element reference — extract #id
-        target.respond_to?(:id) ? "##{target.id}" : target.to_s
-      end
-    end
+    # @api private
+    def take_received!(klass)
+      staged_class, values = @staged_received
+      return unless staged_class.equal?(klass)
 
-    def resolve_trigger(value)
-      Action.resolve_trigger(value)
+      @staged_received = nil
+      values
     end
   end
 end

data/lib/weft/defaults/error_component.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "weft/component"
+
 module Weft
   module Defaults
     # Gem-default component rendered when an action or partial-render fails
@@ -7,56 +9,90 @@ module Weft
     # exception class and message; non-verbose shows a generic message.
     # Users override by setting Weft.configuration.error_component or by
     # declaring their own `recovers` chain.
+    #
+    # Doubles as the default recovery frame for SSE push failures: the Router
+    # injects :attempts_remaining only on that path, so its presence switches
+    # the build into push shape — a countdown notice while the stream retries,
+    # then a stopped notice with a reopen button on the final frame.
     class ErrorComponent < Weft::Component
       abstract!
 
-      # Auto-injected attributes (opt-in, schema-gated by the Router). The
+      # Auto-injected params (opt-in, schema-gated by the Router). The
       # Router populates these at error-handling time on any recovers target
       # that declares them.
-      # :component_id preserves the failing component's DOM identity so the
-      # recovered fragment lands at the original element's id — preventing
-      # duplicate IDs when several siblings fail in the same window.
-      # :retry_url is the failing component's GET URL with current attrs.
-      attribute :component_id
-      attribute :exception
-      attribute :request_path
-      attribute :status_code
-      attribute :retry_url
+      # :retry_url is the failing component's GET URL with current params.
+      # :attempts_remaining is the push-path countdown (nil on HTTP paths).
+      # (Identity is not among them — the Router stamps the failing
+      # component's DOM id onto every recovery fragment itself.)
+      param :component_tag, type: :string
+      param :exception
+      param :request_path, type: :string
+      param :status_code, type: :integer
+      param :retry_url, type: :string
+      param :attempts_remaining, type: :integer
 
       STYLE = "padding:1rem; border:1px solid #fca5a5; border-radius:6px; " \
               "background:#fef2f2; color:#991b1b; font-size:0.875rem"
+      HEADING_STYLE = "font-weight:600; margin-bottom:0.5rem"
       MONO_STYLE = "margin-bottom:0.5rem; font-family:monospace; font-size:0.8rem"
       BUTTON_STYLE = "padding:0.25rem 0.75rem; border:1px solid #b91c1c; border-radius:4px; " \
                      "background:#fff; color:#b91c1c; font-size:0.75rem; cursor:pointer"
 
       def build(attributes = {})
         super
+        return build_push_error if push_context?
+
         add_class "weft-error"
         set_attribute "style", STYLE
 
-        div(style: "font-weight:600; margin-bottom:0.5rem") { text_node "Something went wrong" }
-        render_verbose if Weft.configuration.verbose_error_pages && @attrs.exception
-        render_retry_button if @attrs.retry_url
+        div(style: HEADING_STYLE) { text_node "Something went wrong" }
+        render_verbose if verbose?
+        render_retry_button if @params.retry_url
       end
 
-      # Preserve the failing component's DOM identity when the Router injected
-      # :component_id. Otherwise fall back to the class-derived default.
-      def weft_id
-        @attrs.component_id || super
+      # Adopt the failing component's wrapper tag when the Router injected
+      # :component_tag — a div swapped into a <tr>'s position is invalid
+      # table content; a <tr> error row is not.
+      def tag_name
+        @params.component_tag || super
       end
 
       private
 
+      def push_context? = !@params.attempts_remaining.nil?
+      def verbose? = Weft.configuration.verbose_error_pages && @params.exception
+
+      # Push frames ship children only — the persistent wrapper client-side
+      # belongs to the original component — so the visual box must be an inner
+      # element; anything set on the wrapper would never reach the browser.
+      def build_push_error
+        stopped = @params.attempts_remaining.zero?
+        div(class: "weft-error", style: STYLE) do
+          div(style: HEADING_STYLE) do
+            text_node stopped ? "Live updates stopped" : "Live updates interrupted — retrying"
+          end
+          render_verbose if verbose?
+          render_reopen_button if stopped && @params.retry_url
+        end
+      end
+
       def render_verbose
-        exc = @attrs.exception
+        exc = @params.exception
         div(style: MONO_STYLE) { text_node "#{exc.class}: #{exc.message}" }
       end
 
       # Retry by re-issuing a GET to refresh the failing component. The :retry
-      # shorthand supplies the htmx wiring (outerHTML-swap the closest
-      # .weft-error box), so it works whether or not :component_id was carved out.
+      # preset supplies the htmx wiring (outerHTML-swap the closest
+      # .weft-error box), so it works wherever the fragment happens to land.
       def render_retry_button
-        button "Retry", retry: @attrs.retry_url, style: BUTTON_STYLE
+        button "Retry", retry: @params.retry_url, style: BUTTON_STYLE
+      end
+
+      # Resume by re-fetching the component whole: the fresh wrapper's
+      # sse-connect reopens the stream with a full attempts budget. The
+      # :reopen_stream preset targets the dead wrapper itself.
+      def render_reopen_button
+        button "Resume live updates", reopen_stream: @params.retry_url, style: BUTTON_STYLE
       end
     end
   end

data/lib/weft/defaults/error_page.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "weft/page"
+
 module Weft
   module Defaults
     # Gem-default full-document page rendered for traditional (non-htmx)
@@ -8,19 +10,19 @@ module Weft
     class ErrorPage < Weft::Page
       self.page_path = "/_weft/error"
 
-      attribute :exception
-      attribute :request_path
-      attribute :status_code
+      param :exception
+      param :request_path, type: :string
+      param :status_code, type: :integer
+
+      title "Error"
 
+      # The component reads the same request the page did — recovery values
+      # ride as overlays and reach every depth — so handing them over as
+      # builder kwargs would only render them as HTML attributes on the error
+      # box, exception message and all.
       def build(attributes = {})
-        attributes[:title] ||= "Error"
         super
-        insert_tag(
-          Weft::Defaults::ErrorComponent,
-          exception: @attrs.exception,
-          request_path: @attrs.request_path,
-          status_code: @attrs.status_code
-        )
+        insert_tag(Weft::Defaults::ErrorComponent)
       end
     end
   end

data/lib/weft/defaults/not_found_component.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "weft/component"
+
 module Weft
   module Defaults
     # Gem-default component rendered when a routing miss falls through to
@@ -8,12 +10,12 @@ module Weft
     class NotFoundComponent < Weft::Component
       abstract!
 
-      # Opt into the :component_id auto-injected attribute for parity with
-      # ErrorComponent — preserves DOM identity when a component-context
-      # NotFound recovers through this.
-      attribute :component_id
-      attribute :request_path
-      attribute :status_code
+      # Auto-injected params, opt-in for parity with ErrorComponent. Identity
+      # is not among them — the Router stamps the failing component's DOM id
+      # onto every recovery fragment itself.
+      param :component_tag, type: :string
+      param :request_path, type: :string
+      param :status_code, type: :integer
 
       STYLE = "padding:1rem; border:1px solid #cbd5e1; border-radius:6px; " \
               "background:#f8fafc; color:#0f172a; font-size:0.875rem"
@@ -25,19 +27,19 @@ module Weft
         set_attribute "style", STYLE
 
         div(style: "font-weight:600") { text_node "Not found" }
-        render_verbose if Weft.configuration.verbose_error_pages && @attrs.request_path
+        render_verbose if Weft.configuration.verbose_error_pages && @params.request_path
       end
 
-      # Preserve the failing component's DOM identity when the Router injected
-      # :component_id. Otherwise fall back to the class-derived default.
-      def weft_id
-        @attrs.component_id || super
+      # Adopt the failing component's wrapper tag when the Router injected
+      # :component_tag (see ErrorComponent#tag_name).
+      def tag_name
+        @params.component_tag || super
       end
 
       private
 
       def render_verbose
-        div(style: MONO_STYLE) { text_node @attrs.request_path.to_s }
+        div(style: MONO_STYLE) { text_node @params.request_path.to_s }
       end
     end
   end

data/lib/weft/defaults/not_found_page.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "weft/page"
+
 module Weft
   module Defaults
     # Gem-default full-document page rendered for traditional (non-htmx)
@@ -8,17 +10,16 @@ module Weft
     class NotFoundPage < Weft::Page
       self.page_path = "/_weft/not_found"
 
-      attribute :request_path
-      attribute :status_code
+      param :request_path, type: :string
+      param :status_code, type: :integer
+
+      title "Not found"
 
+      # See ErrorPage#build: the component resolves these from the same
+      # request, so passing them here would only paint them onto the wrapper.
       def build(attributes = {})
-        attributes[:title] ||= "Not found"
         super
-        insert_tag(
-          Weft::Defaults::NotFoundComponent,
-          request_path: @attrs.request_path,
-          status_code: @attrs.status_code
-        )
+        insert_tag(Weft::Defaults::NotFoundComponent)
       end
     end
   end