weft 0.1.0 → 0.2.0

data/lib/weft/params/assembly.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "weft/params"
+require "weft/resolver"
+
+module Weft
+  class Params
+    # Composes a params bag from every source that can supply one. The single
+    # place that knows the source stack — components call it at construction
+    # for their own bag, and the Router calls it at the top of a request for
+    # the bag it hands the first verb block.
+    #
+    # The stack, top wins. `nil` never wins a level: it means that source
+    # didn't have the key.
+    #
+    #   1. hand-off   a caller staged a value for this component (`receives`)
+    #   2. overlay    a verb block earlier in this request returned the key
+    #   3. own wire   the request supplied it and this class declares it
+    #   4. inherited  the bag this one branched from had it
+    #   5. derivation this class declares one (registered lazily, never run here)
+    #   6. default    the declaration's own fallback
+    #
+    # The overlay speaks *as* the wire: its value replaces the wire's for that
+    # key, and an explicit nil clears — masking the wire so resolution falls
+    # below it. A derivation always "produces" (a thunk is never nil), so a
+    # same-key default sits unreachable behind one.
+    class Assembly
+      class << self
+        def call(...) = new(...).bag
+
+        # The state a request composes before any component of its own exists —
+        # what the first verb block sees. No caller and no enclosing build have
+        # run, so the hand-off door isn't merely unsatisfied, it isn't there:
+        # a `receives`-only key is absent, declared default and all. Dual it
+        # with a `param` or a `defines` to make the key visible here.
+        def for_request(component_class, wire_source)
+          call(component_class, wire_source, hand_offs: nil)
+        end
+
+        # One-time shadowing warnings, keyed [kind, class, key]. Set#add? races
+        # just double-warn; harmless.
+        def warned = @warned ||= Set.new
+      end
+
+      # +branched_from+ is the bag this one inherits: a tree ancestor's during
+      # a render, the state already composed at the top of a request. Passing
+      # +hand_offs: nil+ says the door does not exist (see .for_request);
+      # an empty hash says it exists and nobody staged anything.
+      def initialize(component_class, wire_source, hand_offs: {}, overlays: {}, branched_from: nil)
+        @component_class = component_class
+        @received = hand_offs || {}
+        @hand_offs = !hand_offs.nil?
+        @overlays = overlays
+        @wire = Weft::Resolver.resolve_present(component_class, wire_source)
+        @inherited = branched_from ? branched_from.branch_data : {}
+        @upstream_provenance = branched_from ? branched_from.provenance : {}
+      end
+
+      def bag
+        data = @inherited.dup
+        keys.each { |key| data[key] = stack_value(key) }
+        report_shadowed_derivations(data)
+        Weft::Params.new(data, provenance, defaults: declared_defaults)
+      end
+
+      private
+
+      def keys
+        return @component_class.declared_keys if @hand_offs
+
+        @component_class.declared_keys - hand_off_only_keys
+      end
+
+      # Keys whose only door is `receives`. A dual key is declared on another
+      # door too, so it stands on its own without a caller.
+      def hand_off_only_keys
+        @component_class.received_params.keys - @component_class.params.keys -
+          @component_class.derived_params.keys
+      end
+
+      def stack_value(key)
+        return @received[key] unless @received[key].nil?
+
+        wire_level = @overlays.key?(key) ? @overlays[key] : @wire[key]
+        [wire_level, @inherited[key], derived_thunk(key)].find { |v| !v.nil? }
+      end
+
+      # Fallbacks, not values: they ride on the bag rather than in it, so a
+      # key nobody supplied reads as this class's default without becoming
+      # something this class hands to anyone downstream.
+      def declared_defaults
+        keys.filter_map { |key| [key, default_for(key)] unless default_for(key).nil? }.to_h
+      end
+
+      def derived_thunk(key)
+        meta = @component_class.derived_params[key]
+        Weft::Params::Thunk.new(meta[:block]) if meta
+      end
+
+      # The wire door's default wins for dual keys — its meta always carries
+      # one, and the wire door sits above the hand-off's fallback in the stack.
+      def default_for(key)
+        wire_meta = @component_class.params[key]
+        return wire_meta[:default] if wire_meta
+
+        @component_class.received_params[key]&.[](:default)
+      end
+
+      # Where the derivation in force for each key was declared — a map of
+      # declarations, not of values. It tracks what *would* run, so it
+      # survives the value being forced, and survives another source winning
+      # the key outright: a derivation that lost is still a derivation
+      # someone downstream can collide with. The nearest upstream declaration
+      # wins, since its value is the one that would be inherited.
+      def provenance
+        declared = @upstream_provenance.dup
+        @component_class.derived_params.each do |key, meta|
+          declared[key] ||= meta[:source_location]
+        end
+        declared
+      end
+
+      # Two ways a declared derivation ends up dead, each said once per
+      # (class, key). Neither is an error — both are shapes a component can
+      # legitimately want — but both mean a block someone wrote never runs,
+      # which is better heard than discovered.
+      def report_shadowed_derivations(data)
+        @component_class.derived_params.each do |key, meta|
+          next unless @received[key].nil? && @wire[key].nil?
+
+          warn_upstream_derivation(key, meta) unless @inherited[key].nil?
+          warn_overlaid_derivation(key, meta) unless @overlays[key].nil?
+        end
+        data
+      end
+
+      # An inherited value won and was itself derived by a *different* block.
+      # A shared proc (one derivation mixed into many classes) is agreement,
+      # not divergence; values inherited through other doors carry no
+      # derivation provenance and stay silent.
+      def warn_upstream_derivation(key, meta)
+        upstream = @upstream_provenance[key]
+        return if upstream.nil? || upstream == meta[:source_location]
+        return unless warn_once?(:upstream, key)
+
+        Weft.logger.warn(
+          "#{@component_class.name}: inherited #{key.inspect} (derived at #{upstream.join(':')}) " \
+          "shadows this class's own derivation (#{meta[:source_location].join(':')}) — the " \
+          "ancestor's value wins. Use distinct keys or share one derivation if that isn't intended."
+        )
+      end
+
+      # A verb block earlier in this request returned the key. An overlay
+      # speaks as the wire, so it outranks the derivation entirely — which is
+      # exactly how a callable hands a record it already loaded to the render
+      # below it, and also how a derivation quietly stops running.
+      def warn_overlaid_derivation(key, meta)
+        return unless warn_once?(:overlaid, key)
+
+        Weft.logger.warn(
+          "#{@component_class.name}: #{key.inspect} arrived from a verb block in this request and " \
+          "outranks this class's own derivation (#{meta[:source_location].join(':')}), which will " \
+          "not run. Return a different key, or drop the derivation if the block is its only source."
+        )
+      end
+
+      def warn_once?(kind, key) = self.class.warned.add?([kind, @component_class, key])
+    end
+  end
+end

data/lib/weft/params.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "weft/dsl/sandbox"
+require "weft/error"
+
+module Weft
+  # Value object representing a component's resolved input bag.
+  # Provides method-style access with a clear collision-resolution rule:
+  # declared param names win, then the underlying Hash API is available
+  # for any name not declared as a param.
+  #
+  # Entries may be lazy: a `derives` declaration registers a Thunk that runs
+  # (at most once per bag) when its key is first read, and never runs if the
+  # key goes unread. `to_h` and delegated Hash-API calls materialize every
+  # remaining thunk first — the eager escape hatch.
+  #
+  # Action callables receive a ready-made instance (the sole argument to a
+  # +performs+/+transfers+ block); you don't construct these yourself:
+  #
+  #   params.status   # => "shipped"  (declared param)
+  #   params.count    # => 42         (declared param — wins over Hash#count)
+  #   params[:status] # => "shipped"  (explicit hash access)
+  #   params.select { ... }           # delegates to the underlying hash (materializes)
+  #   params.to_h     # => the underlying hash (explicit escape hatch; materializes)
+  class Params
+    # @api private
+    # A registered-not-yet-run derivation. Immutable, so branch copies may
+    # share it: forcing replaces the entry in the forcing bag only, which is
+    # what gives copy-on-branch memoization its semantics.
+    class Thunk
+      attr_reader :block
+
+      def initialize(block)
+        @block = block
+      end
+    end
+
+    # @api private
+    # Constructed internally (components self-resolve via the source stack;
+    # the Router wraps bags for action callables and recovery blocks).
+    # +provenance+ maps derives-born keys to their block's source_location —
+    # retained through forcing so divergence stays detectable.
+    # +defaults+ are the declaring class's own fallbacks, consulted when a
+    # read finds nothing. They are never stored as values, so they never ride
+    # a branch: a default belongs to whoever declared it, and a component
+    # deeper in the tree — or downstream of a hand-off — falls back to its
+    # own, not to the one above it.
+    def initialize(data, provenance = {}, defaults: {})
+      @data = data
+      @provenance = provenance
+      @defaults = defaults
+      @forcing = []
+    end
+
+    # @api private
+    attr_reader :provenance
+
+    # @api private
+    # A branchable snapshot for the inheritance axis: forced values and
+    # still-lazy thunks both ride (thunks are shared objects — forcing
+    # happens per bag, which is what makes the memo copy-on-branch); nils
+    # don't ride (nil means "nobody had it" and must not shadow a
+    # descendant's own defaults).
+    def branch_data
+      @data.compact
+    end
+
+    # @api private
+    # A same-bag copy with +values+ overlaid at their keys. Unlike
+    # to_h-then-merge, nothing materializes: untouched thunks stay lazy, nil
+    # entries stay resolved-absent, provenance rides. The plain-context
+    # hand-off fallback lands received values through this.
+    def overlay(values)
+      self.class.new(@data.merge(values), @provenance, defaults: @defaults)
+    end
+
+    # nil means no source had this key — so the read falls to the declared
+    # fallback, exactly as it falls past a nil at any other level of the stack.
+    def [](key)
+      value = @data[key]
+      value = force!(key, value) if value.is_a?(Thunk)
+      value.nil? ? @defaults[key] : value
+    end
+
+    def key?(key)
+      @data.key?(key) || @defaults.key?(key)
+    end
+
+    def to_h = materialized
+
+    def respond_to_missing?(name, include_private = false)
+      key?(name) || @data.respond_to?(name, include_private) || super
+    end
+
+    def method_missing(name, *args, **kwargs, &block)
+      if key?(name) && args.empty? && kwargs.empty? && !block
+        self[name]
+      elsif @data.respond_to?(name)
+        materialized.public_send(name, *args, **kwargs, &block)
+      else
+        super
+      end
+    end
+
+    private
+
+    # The bag as a plain hash: every thunk run, every unsupplied key standing
+    # at its declared fallback.
+    def materialized
+      materialize!
+      @defaults.merge(@data) { |_key, fallback, value| value.nil? ? fallback : value }
+    end
+
+    # Run a thunk with the bag as its argument (derivations chain by reading
+    # sibling keys) and memoize the result in place. A failed derivation is
+    # not memoized — like RSpec's let, it reruns if read again. The in-flight
+    # list turns circular derivations into a clear error instead of a stack
+    # overflow.
+    def force!(key, thunk)
+      if @forcing.include?(key)
+        raise Weft::InvalidUsage,
+              "circular derivation: #{(@forcing + [key]).join(' -> ')} " \
+              "(a derives block may not read its own key)"
+      end
+
+      @forcing << key
+      begin
+        @data[key] = Weft::DSL::Sandbox.run(self, &thunk.block)
+      ensure
+        @forcing.pop
+      end
+    end
+
+    def materialize!
+      @data.each_key { |key| self[key] }
+    end
+  end
+end

data/lib/weft/presets.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "weft/error"
+
+module Weft
+  # Registry for named interaction presets. Each preset is a bundle of
+  # trigger/swap/target defaults that Context expands via loads:.
+  #
+  # Shipped presets are registered at the bottom of this file. Users will be
+  # able to register custom presets in v1.x via the same API.
+  module Presets
+    # Weft's own element-kwarg vocabulary (keep in sync with
+    # Context::Expansion's grammar; :prompt reserved ahead of its arrival).
+    # A preset by one of these names would shadow the expansion grammar.
+    RESERVED_KWARGS = %i[action navigate loads trigger push_url swap target with confirm prompt].freeze
+
+    # HTML attribute names a preset would shadow: a registered preset claims
+    # its kwarg whenever the value is a Class or String, so `title: "..."`
+    # would stop rendering the HTML attribute. Global attributes plus the
+    # commonly-passed per-element ones.
+    HTML_ATTRIBUTE_NAMES = %i[
+      accesskey autocapitalize autofocus class contenteditable dir draggable enterkeyhint
+      hidden id inert inputmode lang nonce popover role slot spellcheck style tabindex
+      title translate
+      href src alt name value type placeholder disabled readonly required checked selected
+      multiple method rel download media width height
+    ].freeze
+
+    class << self
+      # Register a named interaction preset.
+      #
+      #   Weft::Presets.register :tooltip, trigger: :hover, swap: :fill
+      def register(name, **defaults)
+        validate_name!(name)
+        registry[name] = defaults
+      end
+
+      # Look up a registered preset by name. Returns the defaults hash or nil.
+      def lookup(name)
+        registry[name]
+      end
+
+      # All registered preset names.
+      def registered
+        registry.keys
+      end
+
+      private
+
+      def validate_name!(name)
+        if RESERVED_KWARGS.include?(name)
+          raise Weft::InvalidDefinition,
+                "cannot register preset #{name.inspect} — it is Weft's own element-kwarg vocabulary"
+        end
+        return unless HTML_ATTRIBUTE_NAMES.include?(name)
+
+        Weft.logger.warn "preset #{name.inspect} shadows the HTML attribute of the same name — " \
+                         "elements passing a Class or String value for #{name}: will expand as this " \
+                         "preset instead of rendering the attribute"
+      end
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end
+
+# Shipped interaction presets — each bundles the htmx wiring for a common
+# hypermedia interaction pattern. Adding one is a single line; Context dispatch
+# + loads: expansion handles the rest.
+
+Weft::Presets.register :tooltip,         trigger: :hover, swap: :fill
+# click_once, not click: the inserted detail lands after the trigger element,
+# so a repeat click would insert a second copy.
+Weft::Presets.register :inline_expand,   trigger: :click_once, swap: :after
+Weft::Presets.register :lazy,            trigger: :visible, swap: :fill, target: :self
+Weft::Presets.register :modal,           trigger: :click, swap: :fill
+Weft::Presets.register :load_more,       trigger: :click, swap: :replace, target: :self
+Weft::Presets.register :infinite_scroll, trigger: :visible, swap: :after
+Weft::Presets.register :live_search,     trigger: :input, swap: :fill
+Weft::Presets.register :tabs,            trigger: :click, swap: :fill
+
+# Retry is the odd one out: its value is a URL (the failing component's own GET
+# URL, injected as the :retry_url recovery param), not a target Class. It ships a
+# concrete hx-target so error components never hand-write htmx — outerHTML-swapping
+# the enclosing .weft-error box replaces the whole error display with the fresh
+# component. Callers override target: for a differently-classed container.
+Weft::Presets.register :retry,           trigger: :click, swap: :outer_html, target: "closest .weft-error"
+
+# Reopen_stream is retry's sibling for closed SSE streams (same URL value,
+# usually :retry_url). Targeting the enclosing sse-swap wrapper — the element
+# left behind after the Router closes a stream — means the fresh render
+# replaces it wholesale, and its new sse-connect attribute makes htmx open a
+# fresh EventSource: live updates resume with a full attempts budget.
+Weft::Presets.register :reopen_stream,   trigger: :click, swap: :outer_html, target: "closest [sse-swap]"

data/lib/weft/redirect.rb

@@ -14,30 +14,30 @@ module Weft
   # Convenience wrapper:
   #   Weft.redirect(OrderDetailPage, order_id: order.id)
   class Redirect
-    attr_reader :target, :attrs
+    attr_reader :target, :params
 
     # @api private
     # Use {Redirect.to} (or {Weft.redirect}) — +new+ is private.
-    def initialize(target, **attrs)
+    def initialize(target, **params)
       @target = target
-      @attrs = attrs
+      @params = params
     end
 
     # Resolve the redirect URL.
-    # Page targets: interpolate attrs into page_path pattern.
+    # Page targets: interpolate params into page_path pattern.
     # String targets: use as-is.
     def url
       case @target
       when String
         @target
       else
-        @target.resolve_page_path(@attrs)
+        @target.resolve_page_path(@params)
       end
     end
 
     # Primary constructor.
-    def self.to(target, **attrs)
-      new(target, **attrs)
+    def self.to(target, **params)
+      new(target, **params)
     end
 
     private_class_method :new

data/lib/weft/registry/eligibility.rb

@@ -29,30 +29,16 @@ module Weft
         @routable_explicit = false
       end
 
+      # Same switch as {abstract!}, named for the other reason to flip it:
+      # "I rely on state I can only receive, not reconstruct — my parent must
+      # hand it to me every time, so serving me standalone makes no sense."
+      alias dependent! abstract!
+
       # Force this class to be routable, even if its declared state would
       # otherwise make it non-routable. Does not percolate to subclasses.
       def routable!
         @routable_explicit = true
       end
-
-      # Whether this class object has been superseded — its fully-qualified name
-      # now resolves to a *different* class. This is the code-reload case: a
-      # reloader (e.g. Zeitwerk in development) redefines the constant, binding a
-      # new class object to the name while the old one lingers in the registry.
-      # The registry drops superseded classes so only the current definition
-      # routes (otherwise the two would look like a route collision).
-      #
-      # Classes whose name does not resolve to a constant — anonymous classes,
-      # or test doubles that stub +.name+ — are never stale. Override for
-      # bespoke liveness semantics.
-      #
-      # @note Uses ActiveSupport's +safe_constantize+, which walks the namespace.
-      #   The registry calls this only at route-resolution time (memoized), so
-      #   the cost is paid once per registry generation, not per request.
-      def stale?
-        current = name&.safe_constantize
-        !current.nil? && !equal?(current)
-      end
     end
   end
 end

data/lib/weft/registry.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module Weft
+  class << self
+    # The process-wide registry. Defined here rather than in the gem root
+    # because registration happens at class-definition time (the `inherited`
+    # hooks on Component and Page call this), so any file that defines a
+    # subclass needs the accessor resolvable at load.
+    def registry
+      @registry ||= Registry.new
+    end
+  end
+
   # Stores registered Weft::Component and Weft::Page classes for the Router
   # to consume at request time.
   #
@@ -45,10 +55,8 @@ module Weft
       @routes_validated = false
     end
 
-    # Empty the registry. Provided as an explicit reset hook for app-level
-    # reload integrations and for tests; ordinary reloading is handled
-    # automatically (superseded classes are pruned — see stale-class handling
-    # in validate_routes!).
+    # Empty the registry. The evict-everything reset for hand-rolled reload
+    # integrations and for tests; per-class eviction is #evict.
     def clear
       @components.clear
       @pages.clear
@@ -57,6 +65,21 @@ module Weft
       @routes_validated = false
     end
 
+    # Remove one class from the registry, invalidating route lookup so a fresh
+    # same-path registration serves cleanly. This is the reload-eviction
+    # primitive: Weft.configure_autoloading wires it to Zeitwerk's on_unload
+    # callback, and hand-rolled reloaders should call it (or #clear) as classes
+    # unload. Safe to call with any object — non-registered classes (models,
+    # service objects) fall through untouched. Returns true if evicted.
+    def evict(klass) # rubocop:disable Naming/PredicateMethod -- a command with a did-evict status return
+      return false unless @components.delete?(klass) || @pages.delete?(klass)
+
+      @path_index = nil
+      @sse_present = nil
+      @routes_validated = false
+      true
+    end
+
     def pages
       @pages.to_a
     end
@@ -116,16 +139,6 @@ module Weft
       page_class.page_path || page_class.send(:default_page_path)
     end
 
-    # Drop classes whose constant has been redefined out from under them (the
-    # code-reload case — see Weft::Registry::Eligibility#stale?). Without this, a
-    # reloaded class and its stale predecessor resolve to the same path and look
-    # like a route collision. Runs once per registry generation via
-    # validate_routes!; @path_index is rebuilt only if a component was removed.
-    def prune_stale!
-      @path_index = nil if @components.reject!(&:stale?)
-      @pages.reject!(&:stale?)
-    end
-
     # Build the effective-route table across every routable component (its base
     # path plus its reserved stream-suffix tail) and routable page (its resolved
     # pattern), and raise Weft::InvalidDefinition on any duplicate — component vs
@@ -136,9 +149,9 @@ module Weft
     def validate_routes!
       return if @routes_validated
 
-      prune_stale!
       seen = {}
       routable_components.each do |klass|
+        warn_dependent_receives!(klass)
         base = klass.resolved_component_path
         add_route!(seen, base, klass, :component)
         add_route!(seen, "#{base}/#{Weft.configuration.stream_suffix}", klass, :stream)
@@ -147,6 +160,24 @@ module Weft
       @routes_validated = true
     end
 
+    # A routable component with a required hand-off it cannot reconstruct
+    # standalone will raise on every refresh (nothing hands the value over).
+    # Defaulted hand-offs are exempt (declaring a default explicitly opts
+    # into standalone renders falling back to it), as are dual keys — a wire
+    # param or a derives supplies the standalone value. Runs once per
+    # registry generation, alongside route validation.
+    def warn_dependent_receives!(klass)
+      required = klass.received_params.reject { |_, meta| meta.key?(:default) }.keys
+      undualed = required - klass.params.keys - klass.derived_params.keys
+      return if undualed.empty?
+
+      Weft.logger.warn(
+        "#{klass.name} is routable but depends on hand-offs it cannot reconstruct standalone " \
+        "(#{undualed.map(&:inspect).join(', ')}) — a refresh will raise without them. " \
+        "Mark the class dependent!, or declare a derives or wire param dual for the key."
+      )
+    end
+
     def add_route!(seen, path, klass, kind)
       validate_route_shape!(path, klass, kind)
       if (existing = seen[path])
@@ -167,10 +198,19 @@ module Weft
             "a route must be a non-empty string beginning with \"/\"."
     end
 
+    # Two same-named class objects at one route is the signature of code
+    # reloading without eviction — say so, rather than suggesting a rename.
     def collision_message(path, existing, incoming)
-      "Route collision on #{path.inspect}: #{route_label(*existing)} and " \
-        "#{route_label(*incoming)} resolve to the same route. Rename one class, " \
-        "set an explicit component_path/page_path, or mark one abstract! if it should not route."
+      if existing[0].name == incoming[0].name
+        "Route collision on #{path.inspect}: two class objects named #{existing[0].name} " \
+          "are registered — usually a code reloading setup that never evicts. Evict classes " \
+          "as they unload (Weft.registry.evict, e.g. from a Zeitwerk on_unload callback), " \
+          "or reset with Weft.registry.clear before each reload."
+      else
+        "Route collision on #{path.inspect}: #{route_label(*existing)} and " \
+          "#{route_label(*incoming)} resolve to the same route. Rename one class, " \
+          "set an explicit component_path/page_path, or mark one abstract! if it should not route."
+      end
     end
 
     def route_label(klass, kind)