weft 0.1.0

data/lib/weft/page.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Weft
+  # Document shell component. Renders the full HTML skeleton (doctype,
+  # head, body) with registered scripts and stylesheets. Subclass to
+  # add application-specific assets and CSS.
+  #
+  # Pages auto-route via page_path declarations or class-name inference.
+  # The Router serves them as full documents at the resolved URL patterns.
+  #
+  #   class OrderDetailPage < Weft::Page
+  #     self.page_path = "/orders/:order_id"
+  #     attribute :order_id
+  #   end
+  #
+  # Subclasses without an explicit page_path auto-infer one from the class
+  # name: the demodulized name, snake-cased, with any trailing "Page" suffix
+  # stripped (DashboardPage and Dashboard both route at "/dashboard"). Use
+  # abstract! to opt out — typical for an intermediate base class that hosts
+  # shared assets and helpers but isn't itself a destination.
+  class Page < Arbre::Component # rubocop:disable Metrics/ClassLength
+    extend Weft::Registry::Eligibility
+
+    include Weft::Context::Interception
+    include Weft::DSL::Attributes
+    include Weft::DSL::Recoveries
+    include Weft::DSL::Containers
+
+    # @!method weft_page(*args, &block)
+    #   @api private
+    #   Arbre builder for the Weft page element. Internal plumbing — authors
+    #   subclass Weft::Page and render via the Router; they do not call this.
+    builder_method :weft_page
+
+    HTMX_SRC = "https://unpkg.com/htmx.org@2.0.4"
+    HTMX_ATTRS = {
+      integrity: "sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+",
+      crossorigin: "anonymous"
+    }.freeze
+    HTMX_SSE_SRC = "https://unpkg.com/htmx-ext-sse@2.2.2/sse.js"
+    HTMX_SSE_ATTRS = {
+      integrity: "sha384-fw+eTlCc7suMV/1w/7fr2/PmwElUIt5i82bi+qTiLXvjRXZ2/FkiTNA/w0MhXnGI",
+      crossorigin: "anonymous"
+    }.freeze
+
+    class << self
+      # Class-level page path pattern. Sinatra-style string with :param segments.
+      # Bidirectional: forward (interpolate attrs → URL) and reverse (match request → params).
+      #
+      #   self.page_path = "/orders/:order_id"
+      def page_path
+        if instance_variable_defined?(:@page_path)
+          @page_path
+        elsif superclass.respond_to?(:page_path)
+          superclass.page_path
+        end
+      end
+
+      attr_writer :page_path
+
+      # Resolve the page path by interpolating attrs into the pattern.
+      #   OrderDetailPage.resolve_page_path(order_id: "42") # => "/orders/42"
+      def resolve_page_path(attrs = {})
+        pattern = page_path || default_page_path
+        pattern.gsub(/:(\w+)/) { attrs[::Regexp.last_match(1).to_sym] || ":#{::Regexp.last_match(1)}" }
+      end
+
+      # Build a redirect URL targeting this page with the given attrs.
+      # Path :param segments interpolate from attrs; declared-but-not-param
+      # attrs become query string entries. Anything not in the page's
+      # declared schema is discarded — never leaks into the URL.
+      #
+      #   class OrderDetailPage < Weft::Page
+      #     self.page_path = "/orders/:order_id"
+      #     attribute :order_id
+      #     attribute :highlight_section
+      #   end
+      #   OrderDetailPage.redirect_url(order_id: 42, highlight_section: "items", junk: "x")
+      #   # => "/orders/42?highlight_section=items"
+      def redirect_url(attrs = {})
+        path = resolve_page_path(attrs)
+        query = attrs.slice(*(attributes.keys - path_param_keys)).compact
+        query.empty? ? path : "#{path}?#{::URI.encode_www_form(query)}"
+      end
+
+      def path_param_keys
+        pattern = page_path || default_page_path
+        pattern.scan(/:(\w+)/).flatten.map(&:to_sym)
+      end
+
+      # Inferred routability from declared state, ignoring any explicit
+      # override. Subclasses fall back to this when they have no override of
+      # their own, so an abstract parent does not disable concrete children.
+      #
+      # A page is inferred-routable if it has an explicit page_path, or if its
+      # class name yields a usable default — i.e. the demodulized name has a
+      # non-empty stem after stripping any trailing "Page" suffix. The suffix
+      # is optional: FooBarPage and BazBar both route. Pages with attributes
+      # are not inferred-routable; they require an explicit page_path (a
+      # parameterized route can't be derived from the name; see default_page_path).
+      def inferred_routable?
+        return true if instance_variable_defined?(:@page_path)
+        return false if attributes.any?
+
+        !name.to_s.delete_suffix("Page").demodulize.empty?
+      end
+
+      def inherited(subclass)
+        super
+        Weft.registry.register_page(subclass)
+      end
+
+      # Render this page as a full HTML document outside any Arbre DSL context.
+      # Used by the Router for full-document responses, and available to users
+      # for testing or standalone rendering.
+      def render(**attributes)
+        klass = self
+        Weft::Context.new({}, nil) do
+          insert_tag(klass, **attributes)
+        end.to_s
+      end
+
+      # Register a stylesheet to include in the page head.
+      #
+      # Absolute URLs (http(s)://, protocol-relative //, leading /) render as-is.
+      # Bare-relative paths resolve against a static_assets bundle: either the
+      # one named via `assets:`, or the :default bundle if one is configured.
+      # When neither applies, the path passes through unchanged and the browser
+      # resolves it relative to the current page URL.
+      #
+      #   register_stylesheet "https://cdn.example.com/bootstrap.css"
+      #   register_stylesheet "css/app.css"                   # resolves against :default
+      #   register_stylesheet "tailwind/tw.css", assets: :vendor
+      def register_stylesheet(href, assets: nil)
+        own_stylesheets << { href: href, assets: assets }
+      end
+
+      # Register a script to include in the page head. Same resolution rules
+      # as register_stylesheet. Additional kwargs become HTML attributes on
+      # the <script> tag.
+      #
+      #   register_script "https://cdn.example.com/app.js", defer: "defer"
+      #   register_script "js/app.js"                         # resolves against :default
+      #   register_script "vendor/x.js", assets: :vendor, defer: "defer"
+      def register_script(src, assets: nil, **html_attrs)
+        own_scripts << { src: src, attrs: html_attrs, assets: assets }
+      end
+
+      # Register a block of inline CSS to include in the page head.
+      # Each registered string emits as its own <style> tag (subclasses
+      # add on top of their parent's contributions; nothing replaces).
+      #
+      #   register_css <<~CSS
+      #     .card { padding: 1rem; }
+      #   CSS
+      def register_css(css)
+        own_inline_css << css
+      end
+
+      # All registered stylesheets (own + inherited).
+      def stylesheets
+        if superclass.respond_to?(:stylesheets)
+          superclass.stylesheets + own_stylesheets
+        else
+          own_stylesheets.dup
+        end
+      end
+
+      # All registered scripts (own + inherited).
+      def scripts
+        if superclass.respond_to?(:scripts)
+          superclass.scripts + own_scripts
+        else
+          own_scripts.dup
+        end
+      end
+
+      # All registered inline CSS blocks (own + inherited).
+      def inline_css
+        if superclass.respond_to?(:inline_css)
+          superclass.inline_css + own_inline_css
+        else
+          own_inline_css.dup
+        end
+      end
+
+      private
+
+      def own_stylesheets
+        @own_stylesheets ||= []
+      end
+
+      def own_scripts
+        @own_scripts ||= []
+      end
+
+      def own_inline_css
+        @own_inline_css ||= []
+      end
+
+      def default_page_path
+        if attributes.any?
+          raise Weft::InvalidDefinition,
+                "#{name} declares attributes but no explicit page_path. " \
+                "Set self.page_path = \"/your/path/:#{attributes.keys.first}\""
+        end
+
+        stem = name.to_s.delete_suffix("Page")
+        if stem.demodulize.empty?
+          raise Weft::InvalidDefinition,
+                "#{name.inspect} has no resolvable default page_path. " \
+                "Either rename the class with a meaningful stem (e.g. DashboardPage), " \
+                "set self.page_path = \"/your/path\" explicitly, " \
+                "or mark the class abstract! if it isn't meant to route."
+        end
+
+        "/#{stem.underscore}"
+      end
+    end
+
+    def build(attributes = {})
+      schema = self.class.attributes
+      @attrs = Weft::Attributes.extract_from(attributes, using: schema) if schema.any?
+      @page_title = attributes.delete(:title) || "Weft"
+      super(attributes.except(*schema.keys))
+      build_head
+      @body_el = insert_tag(Arbre::HTML::Body)
+    end
+
+    def tag_name
+      "html"
+    end
+
+    def add_child(child)
+      @body_el ? (@body_el << child) : super
+    end
+
+    def to_s
+      "<!DOCTYPE html>\n#{super}"
+    end
+
+    private
+
+    def build_head
+      insert_tag(Arbre::HTML::Head) do
+        meta charset: "utf-8"
+        meta name: "viewport", content: "width=device-width, initial-scale=1"
+        title { text_node @page_title }
+        render_assets
+        render_htmx_config
+      end
+    end
+
+    def render_assets
+      render_stylesheets
+      render_htmx_script if Weft.configuration.include_htmx
+      render_sse_script if include_sse_ext?
+      render_scripts
+      render_inline_css
+    end
+
+    def render_stylesheets
+      self.class.stylesheets.each do |entry|
+        link href: resolve_asset_url(entry[:href], assets: entry[:assets]), rel: "stylesheet"
+      end
+    end
+
+    def render_scripts
+      self.class.scripts.each do |entry|
+        script(src: resolve_asset_url(entry[:src], assets: entry[:assets]), **entry[:attrs])
+      end
+    end
+
+    # Resolve a registered asset path to a final URL.
+    #
+    # - Absolute URLs (http(s)://, //, /) pass through unchanged. Passing an
+    #   `assets:` kwarg alongside an absolute URL raises — the kwarg is only
+    #   meaningful for relative paths, and accepting it silently would train
+    #   callers to attach it everywhere "just in case."
+    # - Bare-relative paths with an explicit `assets: :name` resolve against
+    #   that bundle's root. Unknown bundle names raise with a list of
+    #   configured names.
+    # - Bare-relative paths without an `assets:` kwarg resolve against the
+    #   :default bundle if one is configured; otherwise they pass through and
+    #   the browser interprets them relative to the current page URL.
+    def resolve_asset_url(path, assets: nil)
+      return resolve_absolute_asset_url(path, assets) if absolute_asset_url?(path)
+
+      resolve_relative_asset_url(path, assets)
+    end
+
+    def resolve_absolute_asset_url(path, assets)
+      raise_absolute_with_assets_kwarg!(path, assets) if assets
+
+      path
+    end
+
+    def resolve_relative_asset_url(path, assets)
+      bundles = Weft.configuration.static_assets
+      target = assets&.to_sym || (bundles.key?(:default) ? :default : nil)
+      return path unless target
+
+      bundle = bundles[target]
+      raise_unknown_assets_bundle!(path, target, bundles) unless bundle
+
+      "#{bundle[:root]}/#{path}"
+    end
+
+    def absolute_asset_url?(path)
+      path.start_with?("http://", "https://", "//", "/")
+    end
+
+    def raise_absolute_with_assets_kwarg!(path, assets)
+      raise Weft::InvalidUsage,
+            "static asset #{path.inspect}: assets: #{assets.inspect} " \
+            "is only meaningful for relative paths (absolute URLs render as-is)"
+    end
+
+    def raise_unknown_assets_bundle!(path, target, bundles)
+      raise Weft::InvalidUsage,
+            "static asset #{path.inspect} references assets bundle #{target.inspect}, " \
+            "but no such bundle is configured. Configured bundles: #{bundles.keys.inspect}"
+    end
+
+    def render_inline_css
+      self.class.inline_css.each { |css| style { text_node css.html_safe } }
+    end
+
+    def render_htmx_script
+      script src: HTMX_SRC, **HTMX_ATTRS
+    end
+
+    def render_sse_script
+      script src: HTMX_SSE_SRC, **HTMX_SSE_ATTRS
+    end
+
+    # Resolve the include_sse_ext configuration into a boolean. :auto defers
+    # to the Registry; true/false short-circuit it.
+    def include_sse_ext?
+      case Weft.configuration.include_sse_ext
+      when true then true
+      when false then false
+      else Weft.registry.any_sse_components?
+      end
+    end
+
+    def render_htmx_config
+      script do
+        text_node htmx_config_js.html_safe
+      end
+    end
+
+    def htmx_config_js
+      <<~JS
+        htmx.config.responseHandling = [
+          {code: "204", swap: false},
+          {code: "[23]..", swap: true},
+          {code: "[45]..", swap: true, error: true}
+        ];
+      JS
+    end
+
+    # Gem-default recovery edges. Symbol form defers resolution until
+    # error-handling time so reassigning the configuration knob propagates.
+    # NotFound declared first so its more-specific match wins over StandardError.
+    recovers from: Weft::NotFound, with: :not_found_page
+    recovers from: StandardError, with: :error_page
+  end
+end

data/lib/weft/redirect.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Weft
+  # Value object returned from action callables to trigger navigation
+  # instead of re-rendering. The Router detects Redirect returns and
+  # sends HX-Redirect (htmx) or 302 (traditional form).
+  #
+  # Preferred form accepts a Page subclass:
+  #   Weft::Redirect.to(OrderDetailPage, order_id: order.id)
+  #
+  # String path fallback:
+  #   Weft::Redirect.to("/orders/#{order.id}")
+  #
+  # Convenience wrapper:
+  #   Weft.redirect(OrderDetailPage, order_id: order.id)
+  class Redirect
+    attr_reader :target, :attrs
+
+    # @api private
+    # Use {Redirect.to} (or {Weft.redirect}) — +new+ is private.
+    def initialize(target, **attrs)
+      @target = target
+      @attrs = attrs
+    end
+
+    # Resolve the redirect URL.
+    # Page targets: interpolate attrs into page_path pattern.
+    # String targets: use as-is.
+    def url
+      case @target
+      when String
+        @target
+      else
+        @target.resolve_page_path(@attrs)
+      end
+    end
+
+    # Primary constructor.
+    def self.to(target, **attrs)
+      new(target, **attrs)
+    end
+
+    private_class_method :new
+  end
+end

data/lib/weft/registry/eligibility.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Weft
+  class Registry
+    # Class-level routing-eligibility behaviors shared by the base classes that
+    # auto-register with {Weft.registry} on definition — {Weft::Component} and
+    # {Weft::Page}. Mixed in with +extend+, so these become class methods on
+    # those bases and their subclasses, and any individual class may override
+    # them. The companion +inferred_routable?+ is defined per base class (its
+    # logic differs: components infer from interactive behavior, pages from
+    # having a usable path).
+    module Eligibility
+      # Whether this class auto-routes. An explicit override via {abstract!} or
+      # {routable!} takes precedence; otherwise routability is inferred (see the
+      # per-class +inferred_routable?+).
+      #
+      # The override is stored as an instance variable on the declaring class
+      # object, so it does not percolate to subclasses — an abstract base can
+      # have concrete subclasses that auto-route normally.
+      def routable?
+        return @routable_explicit if instance_variable_defined?(:@routable_explicit)
+
+        inferred_routable?
+      end
+
+      # Mark this class as a non-routable abstract base, even if its declared
+      # state would otherwise make it routable. Does not percolate to subclasses.
+      def abstract!
+        @routable_explicit = false
+      end
+
+      # 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

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Weft
+  # Stores registered Weft::Component and Weft::Page classes for the Router
+  # to consume at request time.
+  #
+  # Components and Pages are stored separately because their lookup costs
+  # differ:
+  #
+  # - **Components** route at static paths (derived from the class name).
+  #   Stored in `@components`; looked up via `@path_index`, a lazily-built
+  #   hash keyed on the resolved path. O(1) lookup, invalidated when new
+  #   components register.
+  #
+  # - **Pages** route at user-declared patterns that may include `:param`
+  #   segments (e.g. `/orders/:order_id`). Stored in `@pages`; matched by
+  #   walking the set and pattern-matching each `page_path` against the
+  #   request path. O(n) match, but n is typically small (one entry per
+  #   user-declared Page).
+  #
+  # Because pages aren't in `@path_index`, `register_page` does not
+  # invalidate it. Unifying the two storage shapes would force pages-without-
+  # params into the linear walk OR invent two parallel code paths; keeping
+  # them separate is the simplest honest answer.
+  class Registry
+    def initialize
+      @components = Set.new
+      @pages = Set.new
+      @path_index = nil
+      @sse_present = nil
+      @routes_validated = false
+    end
+
+    def register(component_class)
+      @components.add(component_class)
+      @path_index = nil
+      @routes_validated = false
+    end
+
+    # No @path_index invalidation: pages aren't indexed there (see the class
+    # comment above). Pages *do* participate in collision detection, so the
+    # route-validation memo is cleared.
+    def register_page(page_class)
+      @pages.add(page_class)
+      @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!).
+    def clear
+      @components.clear
+      @pages.clear
+      @path_index = nil
+      @sse_present = nil
+      @routes_validated = false
+    end
+
+    def pages
+      @pages.to_a
+    end
+
+    # Match a request path against registered page patterns.
+    # Non-routable pages (abstract bases, classes without a resolvable path)
+    # are skipped. Returns [page_class, extracted_params] or nil.
+    def match_page(path)
+      validate_routes!
+      @pages.each do |page_class|
+        next unless page_class.routable?
+
+        params = match_pattern(resolved_page_pattern(page_class), path)
+        return [page_class, params] if params
+      end
+      nil
+    end
+
+    def lookup(path)
+      validate_routes!
+      path_index[path]
+    end
+
+    def components
+      @components.to_a
+    end
+
+    # True if any registered component declares `pushes` (i.e. participates in
+    # SSE streaming). Used by Weft::Page to decide whether to emit the
+    # htmx-ext-sse script tag automatically. One-way memoized: recomputed while
+    # still false, so components registered after an earlier render are picked
+    # up; once true it sticks, so the typical load-everything-then-serve pattern
+    # pays no steady-state recompute cost.
+    def any_sse_components?
+      return true if @sse_present
+
+      @sse_present = @components.any?(&:push_config)
+    end
+
+    private
+
+    # Routable components only — non-routable components register but are never
+    # served, so they don't occupy a route (and must not shadow one in the index).
+    def path_index
+      @path_index ||= routable_components.to_h { |klass| [klass.resolved_component_path, klass] }
+    end
+
+    def routable_components
+      @components.select(&:routable?)
+    end
+
+    def routable_pages
+      @pages.select(&:routable?)
+    end
+
+    def resolved_page_pattern(page_class)
+      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
+    # component, page vs page, or component vs page — or any malformed path.
+    # Memoized per registry generation (cleared when a class registers), so it
+    # runs once at first request and is a no-op thereafter. Routability gates
+    # everything: abstract!/non-routable classes derive no path and never collide.
+    def validate_routes!
+      return if @routes_validated
+
+      prune_stale!
+      seen = {}
+      routable_components.each do |klass|
+        base = klass.resolved_component_path
+        add_route!(seen, base, klass, :component)
+        add_route!(seen, "#{base}/#{Weft.configuration.stream_suffix}", klass, :stream)
+      end
+      routable_pages.each { |klass| add_route!(seen, resolved_page_pattern(klass), klass, :page) }
+      @routes_validated = true
+    end
+
+    def add_route!(seen, path, klass, kind)
+      validate_route_shape!(path, klass, kind)
+      if (existing = seen[path])
+        raise Weft::InvalidDefinition, collision_message(path, existing, [klass, kind])
+      end
+
+      seen[path] = [klass, kind]
+    end
+
+    # Tier-B well-formedness guard: a resolved route must be a non-empty string
+    # beginning with "/" (an explicit "/" homepage is fine). Catches garbage from
+    # custom/inherited component_path or page_path procs.
+    def validate_route_shape!(path, klass, kind)
+      return if path.is_a?(String) && path.start_with?("/")
+
+      raise Weft::InvalidDefinition,
+            "#{route_label(klass, kind)} resolves to #{path.inspect}, which is not a valid route: " \
+            "a route must be a non-empty string beginning with \"/\"."
+    end
+
+    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."
+    end
+
+    def route_label(klass, kind)
+      case kind
+      when :stream then "the SSE stream endpoint of component #{klass.name}"
+      when :page then "page #{klass.name}"
+      else "component #{klass.name}"
+      end
+    end
+
+    # Match a Sinatra-style pattern against a path.
+    # Returns a hash of extracted params, or nil if no match.
+    def match_pattern(pattern, path)
+      pattern_parts = pattern.split("/")
+      path_parts = path.split("/")
+      return nil unless pattern_parts.length == path_parts.length
+
+      params = {}
+      pattern_parts.zip(path_parts).each do |pat, val|
+        if pat.start_with?(":")
+          params[pat[1..].to_sym] = val
+        elsif pat != val
+          return nil
+        end
+      end
+      params
+    end
+  end
+end