weft 0.1.0

data/lib/weft/defaults/not_found_page.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Weft
+  module Defaults
+    # Gem-default full-document page rendered for traditional (non-htmx)
+    # responses when a NotFound error falls through to the Page recovers
+    # chain. Thin wrapper around NotFoundComponent.
+    class NotFoundPage < Weft::Page
+      self.page_path = "/_weft/not_found"
+
+      attribute :request_path
+      attribute :status_code
+
+      def build(attributes = {})
+        attributes[:title] ||= "Not found"
+        super
+        insert_tag(
+          Weft::Defaults::NotFoundComponent,
+          request_path: @attrs.request_path,
+          status_code: @attrs.status_code
+        )
+      end
+    end
+  end
+end

data/lib/weft/defaults.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Weft::Defaults namespace — gem-provided Page/Component classes used as
+# fallback targets when no user-declared recovers entry matches. Pointed at
+# by Weft::Configuration#error_component / #error_page / #not_found_page.
+require "weft/defaults/error_component"
+require "weft/defaults/error_page"
+require "weft/defaults/not_found_component"
+require "weft/defaults/not_found_page"

data/lib/weft/dsl/actions.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Weft
+  module DSL
+    # Mixin for classes that declare user-initiated actions: `performs`,
+    # `transfers`, and the `dismisses` sugar. Included into Weft::Component.
+    module Actions
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declare a user-initiated action on this component.
+        #
+        #   performs :advance do |attrs|
+        #     order = Order.find(attrs.order_id)
+        #     Oms::PrepareOrder.call(order)
+        #   end
+        #
+        #   performs method: :delete, swap: :delete do |attrs| ... end
+        def performs(name = nil, method: :post, swap: :outer_html, target: nil, &block)
+          action = Weft::Action.new(name: name, method: method, swap: swap,
+                                    target: target, renders: self, callable: block)
+          own_actions[[name, method]] = action
+        end
+
+        # Sugar for performs with swap: :delete. Removes the component from
+        # the DOM on success. The callable (if given) runs for side effects;
+        # the return value is rendered but htmx ignores the response body.
+        #
+        #   dismisses :close                          # no side effects
+        #   dismisses :remove do |attrs|              # with side effects
+        #     Item.find(attrs.item_id).archive!
+        #   end
+        def dismisses(name = nil, method: :delete, &)
+          performs(name, method: method, swap: :delete, &)
+        end
+
+        # Declare a transfer — an action that renders a different component.
+        #
+        #   transfers :edit, to: EditableOrderHeader do |attrs|
+        #     { mode: "full" }
+        #   end
+        def transfers(name = nil, to:, method: :post, swap: :outer_html, target: nil, &block)
+          action = Weft::Action.new(name: name, method: method, swap: swap,
+                                    target: target, renders: to, callable: block)
+          own_actions[[name, method]] = action
+        end
+
+        # All declared actions (own + inherited), keyed by [name, method].
+        def actions
+          if superclass.respond_to?(:actions)
+            superclass.actions.merge(own_actions)
+          else
+            own_actions.dup
+          end
+        end
+
+        # Look up an action by name (for Context interception).
+        def action_for(name)
+          actions.values.find { |a| a.name == name }
+        end
+
+        private
+
+        def own_actions
+          @own_actions ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/weft/dsl/attributes.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Weft
+  module DSL
+    # Mixin for classes that declare wire-state attributes.
+    # Provides the `attribute` class DSL and `attrs` instance reader.
+    # Used by Component (for partial route params) and Page (for page route params).
+    module Attributes
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declare a wire attribute. Accepts optional default: and type: kwargs.
+        #   attribute :status, default: "active", type: :string
+        def attribute(name, default: nil, **options)
+          meta = { default: default }
+          meta[:type] = options[:type] if options.key?(:type)
+          own_attributes[name] = meta
+        end
+
+        # Returns all declared attributes (own + inherited), preserving declaration order.
+        def attributes
+          if superclass.respond_to?(:attributes)
+            superclass.attributes.merge(own_attributes)
+          else
+            own_attributes.dup
+          end
+        end
+
+        private
+
+        def own_attributes
+          @own_attributes ||= {}
+        end
+      end
+
+      # Instance access to resolved wire attribute values.
+      # Returns a Weft::Attributes object with method-style and hash access.
+      attr_reader :attrs
+    end
+  end
+end

data/lib/weft/dsl/containers.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Weft
+  module DSL
+    # Mixin for the `adds_children_to :@ivar` macro — generates the standard
+    # Arbre container override that redirects user-block children into a
+    # nested element while letting structural children (added during `build`)
+    # pass through to the wrapper.
+    #
+    # Mixed into both Weft::Component and Weft::Page by default. Usable on
+    # any class that inherits from Arbre::Component.
+    #
+    #   class Card < Weft::Component
+    #     adds_children_to :@body
+    #
+    #     def build(attributes = {})
+    #       super
+    #       h2 "Header"            # structural — goes to wrapper
+    #       @body = div(class: "card-body")
+    #     end
+    #   end
+    #
+    # The `:@body` form (with the leading `@`) is required — a pedagogical
+    # cue that the macro depends on the user assigning the ivar somewhere
+    # in `build`. If `build` returns without setting the ivar and a child
+    # is then added, the macro raises with a pointed error message.
+    module Containers
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declare that block-style children should be added to the named
+        # instance variable instead of the wrapper element itself.
+        def adds_children_to(ivar)
+          unless ivar.is_a?(Symbol)
+            raise ArgumentError,
+                  "adds_children_to expects a Symbol (e.g., :@body), got #{ivar.inspect}"
+          end
+          unless ivar.to_s.start_with?("@")
+            raise Weft::InvalidDefinition,
+                  "adds_children_to expects a Symbol that must start with @ (e.g., :@body), got #{ivar.inspect}"
+          end
+
+          prepend(Containers.behavior_for(ivar))
+        end
+      end
+
+      # Build the prepended Module that implements both the `build` wrap
+      # (to detect "build returned without assigning the ivar") and the
+      # `add_child` redirect. Each call returns a fresh anonymous module
+      # — declaring the macro on multiple classes is safe.
+      def self.behavior_for(ivar)
+        Module.new do
+          define_method(:build) do |*args, **kwargs|
+            super(*args, **kwargs)
+            @_weft_container_built = true
+          end
+
+          define_method(:add_child) do |child|
+            target = instance_variable_defined?(ivar) ? instance_variable_get(ivar) : nil
+            if target
+              target << child
+            elsif @_weft_container_built
+              raise Weft::MissingContainerIvar,
+                    "#{self.class} declared `adds_children_to #{ivar.inspect}` " \
+                    "but never assigned #{ivar} in build " \
+                    "(e.g., #{ivar} = div(class: 'body') inside build)"
+            else
+              super(child)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/weft/dsl/inclusions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Weft
+  module DSL
+    # Mixin for classes that declare OOB-swapped sibling components.
+    # Included into Weft::Component.
+    #
+    # See Weft::Component#includes for the DSL surface.
+    module Inclusions
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declare that another component should be OOB-swapped alongside
+        # this component's action responses and SSE pushes.
+        #
+        #   includes OrderHeader                          # pass-through attrs
+        #   includes OrderHeader, on: :advance            # only on :advance action
+        #   includes OrderHeader do |attrs|               # explicit attr mapping
+        #     { order_id: attrs.order_id, compact: true }
+        #   end
+        #
+        # Without a block, the included component resolves from the same
+        # request params as the primary component. With a block, the block
+        # receives the primary component's resolved attrs and returns wire
+        # attrs for the included component's Resolver.
+        def includes(component_class, on: nil, &block)
+          own_inclusions << { component_class: component_class, on: on, block: block }
+        end
+
+        # All declared inclusions (own + inherited).
+        def inclusions
+          if superclass.respond_to?(:inclusions)
+            superclass.inclusions + own_inclusions
+          else
+            own_inclusions.dup
+          end
+        end
+
+        private
+
+        def own_inclusions
+          @own_inclusions ||= []
+        end
+      end
+    end
+  end
+end

data/lib/weft/dsl/recoveries.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Weft
+  module DSL
+    # Mixin for classes that declare recovery edges via `recovers`.
+    # Used by both Component (action and partial-render failures) and Page
+    # (full-document render failures, routing misses).
+    #
+    # See Weft::Component#recovers for the DSL surface.
+    module Recoveries
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declare a recovery edge: how this class handles a specific error.
+        #
+        #   recovers from: Weft::Unprocessable do |attrs, error|
+        #     { error_messages: error.messages }
+        #   end
+        #
+        #   recovers from: Weft::Unauthorized, with: LoginPage
+        #
+        # `from:` accepts a Class (subclass-inclusive), Integer (matched against
+        # HTTPError#status), Range, or Array of any of the above.
+        # `with:` accepts a Class (Page or Component) or Symbol (resolved against
+        # Weft.configuration at error-handling time). Default: self.
+        # The optional block receives `|attrs, error|` and returns a hash of
+        # additional attrs that merge with the original on the recovery edge.
+        # Symmetric with performs/transfers contracts (attrs first; error is the
+        # recovery-specific extra). The block never returns HTML.
+        def recovers(from:, with: nil, &block)
+          own_recoveries << { from: from, with: with, block: block }
+        end
+
+        # All declared recovery entries (own + inherited), in resolution order.
+        # Own entries precede inherited entries so subclass declarations take
+        # precedence over ancestor declarations. Within a class, declaration
+        # order is preserved — first-declared wins on ties.
+        def recoveries
+          if superclass.respond_to?(:recoveries)
+            own_recoveries + superclass.recoveries
+          else
+            own_recoveries.dup
+          end
+        end
+
+        # Find the first recovery entry whose `from:` matches the given exception.
+        # Returns nil if nothing matches. `from:` accepts Class (subclass-inclusive),
+        # Integer (status equality — HTTPError carries .status; non-HTTPError = 500),
+        # Range (status in range), or Array of any of the above (any element matches).
+        def recovery_for(exception)
+          recoveries.find { |entry| recovery_matches?(entry[:from], exception) }
+        end
+
+        # Resolve the recovery entry's `with:` value to a concrete target class.
+        # Symbol values look up `Weft.configuration.<sym>` (resolved at error-handling
+        # time so config reassignment propagates). Nil falls back to self.
+        def resolve_recovery_target(entry)
+          case entry[:with]
+          when Symbol then Weft.configuration.public_send(entry[:with])
+          when nil    then self
+          else entry[:with]
+          end
+        end
+
+        private
+
+        def own_recoveries
+          @own_recoveries ||= []
+        end
+
+        def recovery_matches?(from_clause, exception)
+          case from_clause
+          when Array   then from_clause.any? { |f| recovery_matches?(f, exception) }
+          when Class   then exception.is_a?(from_clause)
+          when Integer then recovery_status_of(exception) == from_clause
+          when Range   then from_clause.cover?(recovery_status_of(exception))
+          else false
+          end
+        end
+
+        def recovery_status_of(exception)
+          exception.is_a?(Weft::HTTPError) ? exception.status : 500
+        end
+      end
+    end
+  end
+end

data/lib/weft/dsl/triggers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Weft
+  module DSL
+    # Mixin for classes that declare HX-Trigger response events.
+    # Included into Weft::Component.
+    #
+    # See Weft::Component#triggers for the DSL surface.
+    module Triggers
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declare an event to trigger on all action responses for this component.
+        # Sets the HX-Trigger response header.
+        #
+        #   triggers "order-updated"
+        def triggers(event_name)
+          own_triggers << event_name.to_s
+        end
+
+        # All declared trigger events (own + inherited).
+        def trigger_events
+          if superclass.respond_to?(:trigger_events)
+            superclass.trigger_events | own_triggers
+          else
+            own_triggers.dup
+          end
+        end
+
+        private
+
+        def own_triggers
+          @own_triggers ||= []
+        end
+      end
+    end
+  end
+end

data/lib/weft/dsl/updates.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Weft
+  module DSL
+    # Mixin for classes that declare live-update behavior — polling and
+    # event-driven refreshes (`refreshes`) and SSE push streams (`pushes`).
+    # Included into Weft::Component.
+    module Updates
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declare that this component refreshes automatically.
+        #
+        #   refreshes every: 10.seconds          # polling
+        #   refreshes on: "delivery-completed"   # event-driven
+        #   refreshes every: 10, on: "updated"   # both
+        #
+        # Generates hx-get, hx-trigger, hx-swap on the wrapper element.
+        # Multiple calls accumulate into a single hx-trigger value.
+        # Fractional intervals render in htmx's millisecond syntax.
+        def refreshes(every: nil, on: nil)
+          if every
+            ms = interval_in_ms(every, :refreshes)
+            own_refresh_triggers << ((ms % 1000).zero? ? "every #{ms / 1000}s" : "every #{ms}ms")
+          end
+          own_refresh_triggers << "#{on} from:body" if on
+        end
+
+        # Declare that this component pushes updates via SSE.
+        #
+        #   pushes every: 5.seconds   # server pushes on interval
+        #
+        # Generates hx-ext="sse", sse-connect, sse-swap on the wrapper element.
+        # The Router auto-generates a streaming endpoint at
+        # /component_path/_stream (the suffix is the stream_suffix config knob).
+        #
+        # Future: pushes on: "event-name" for event-driven server push (v1.0).
+        def pushes(every: nil)
+          @push_config = {}
+          return unless every
+
+          ms = interval_in_ms(every, :pushes)
+          @push_config[:every] = (ms % 1000).zero? ? ms / 1000 : ms / 1000.0
+        end
+
+        # Push configuration (own or inherited). Returns nil if no pushes declared.
+        def push_config
+          if instance_variable_defined?(:@push_config)
+            @push_config
+          elsif superclass.respond_to?(:push_config)
+            superclass.push_config
+          end
+        end
+
+        # All declared refresh triggers (own + inherited).
+        def refresh_triggers
+          if superclass.respond_to?(:refresh_triggers)
+            superclass.refresh_triggers | own_refresh_triggers
+          else
+            own_refresh_triggers.dup
+          end
+        end
+
+        private
+
+        def own_refresh_triggers
+          @own_refresh_triggers ||= []
+        end
+
+        # htmx's smallest expressible interval is 1ms; rather than emit an
+        # "every 0s" that polls flat-out, round up and say so.
+        def interval_in_ms(every, verb)
+          ms = (every.to_f * 1000).round
+          return ms if ms.positive?
+
+          Weft.logger.warn(
+            "#{name} declares `#{verb} every: #{every.inspect}`, below the 1ms floor; using 1ms"
+          )
+          1
+        end
+      end
+    end
+  end
+end

data/lib/weft/error.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Weft
+  # Abstract base — never raise directly; use a semantic subclass.
+  # Exists for `rescue Weft::Error` to catch the whole gem-error family.
+  Error = Class.new(StandardError)
+
+  # Intermediate carrying an HTTP status. Subclass for status-bearing semantics.
+  # `recovers from: Weft::HTTPError` catches the whole status-bearing family.
+  class HTTPError < Error
+    def self.status
+      nil
+    end
+
+    def status
+      self.class.status
+    end
+  end
+
+  class NotFound < HTTPError
+    def self.status = 404
+  end
+
+  class Unauthorized < HTTPError
+    def self.status = 401
+  end
+
+  class Forbidden < HTTPError
+    def self.status = 403
+  end
+
+  class Unprocessable < HTTPError
+    def self.status = 422
+  end
+
+  class InternalError < HTTPError
+    def self.status = 500
+  end
+
+  # Below this comment, maintain semantically-named errors (not ending in "Error") in alphabetical order, e.g.:
+  #
+  # OrderAlreadyFulfilled = Class.new(Error)
+  # InsufficientFunds = Class.new(Error)
+
+  # Raised for semantic mistakes inside `Weft.configure { |c| ... }` — values
+  # of the right kind that nonetheless violate a constraint (e.g. an asset
+  # root not starting with `/`), or state conflicts (duplicate asset bundles).
+  InvalidConfiguration = Class.new(Error)
+
+  # Raised for semantic mistakes in class-body DSL declarations — e.g. a page
+  # declares attributes but no `page_path`, or `adds_children_to` receives a
+  # Symbol that does not start with `@`.
+  InvalidDefinition = Class.new(Error)
+
+  # Raised for semantic mistakes at render / action time — invalid input
+  # combinations or references to state that isn't there (e.g. an unknown
+  # assets bundle named at `register_stylesheet`).
+  InvalidUsage = Class.new(Error)
+
+  # Raised by the `adds_children_to :@ivar` macro when build returns without
+  # ever assigning the named ivar and then a child is added — almost always
+  # means the developer declared the macro but forgot the matching assignment.
+  MissingContainerIvar = Class.new(InvalidDefinition)
+end