weft 0.1.0 → 0.2.0

data/lib/weft/page/assets.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "arbre"
+
+require "weft/error"
+require "weft/registry"
+
+module Weft
+  class Page < Arbre::Component
+    # The asset surface of the page head: the register_* family (class-level
+    # DSL, accumulate semantics — subclasses add atop their parents) plus the
+    # rendering and URL-resolution machinery that emits them. Mixed into
+    # Weft::Page alongside Head, whose build_head drives render_assets.
+    module Assets
+      def self.included(base) = base.extend(ClassMethods)
+
+      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-level registration DSL. Each register_* call accumulates; the
+      # matching reader returns own + inherited entries in ancestor order.
+      module ClassMethods
+        # 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_inline_css <<~CSS
+        #     .card { padding: 1rem; }
+        #   CSS
+        def register_inline_css(css)
+          own_inline_css << css
+        end
+
+        # Register a block of inline JavaScript to include in the page head.
+        # Same accumulate semantics as register_inline_css; emitted after the
+        # registered external scripts, so registered libraries are in reach.
+        #
+        #   register_inline_js "htmx.logAll();"
+        def register_inline_js(javascript)
+          own_inline_js << javascript
+        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
+
+        # All registered inline JS blocks (own + inherited).
+        def inline_js
+          if superclass.respond_to?(:inline_js)
+            superclass.inline_js + own_inline_js
+          else
+            own_inline_js.dup
+          end
+        end
+
+        private
+
+        def own_stylesheets = @own_stylesheets ||= []
+        def own_scripts = @own_scripts ||= []
+        def own_inline_css = @own_inline_css ||= []
+        def own_inline_js = @own_inline_js ||= []
+      end
+
+      private
+
+      def render_assets
+        render_stylesheets
+        render_htmx_script if Weft.configuration.include_htmx
+        render_sse_script if include_sse_ext?
+        render_scripts
+        render_inline_js
+        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
+
+      def render_inline_js
+        self.class.inline_js.each { |js| script { text_node js.html_safe } }
+      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
+
+      # 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
+    end
+  end
+end

data/lib/weft/page/head.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "arbre"
+
+require "weft/dsl/sandbox"
+require "weft/error"
+require "weft/params"
+
+module Weft
+  class Page < Arbre::Component
+    # The document-head surface: the `title` verb (class-level DSL, override
+    # semantics — nearest declaration in the ancestry wins) and the head
+    # assembly that consumes it. Mixed into Weft::Page alongside Assets,
+    # whose render_assets this module's build_head drives.
+    module Head
+      def self.included(base) = base.extend(ClassMethods)
+
+      module ClassMethods
+        # Declare the page's <title>. A static value, or a block computed from
+        # the page's params at render time — a `(params) → value` function run
+        # in the verb sandbox, like every other verb block.
+        #
+        #   title "Orders"
+        #   title { |params| "Order ##{params.order_id}" }
+        #
+        # The nearest declaration in the class ancestry wins; without one
+        # anywhere, the title falls back to "Weft".
+        def title(value = nil, &block)
+          if value && block
+            raise Weft::InvalidDefinition, "#{name}: title takes a value or a block, not both"
+          elsif value.nil? && block.nil?
+            raise Weft::InvalidDefinition, "#{name}: title needs a value or a block"
+          end
+
+          @title_declaration = block || value
+        end
+
+        # The declared title (own or nearest inherited); nil when no ancestor declares.
+        def title_declaration
+          if instance_variable_defined?(:@title_declaration)
+            @title_declaration
+          elsif superclass.respond_to?(:title_declaration)
+            superclass.title_declaration
+          end
+        end
+      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 resolved_page_title }
+          render_assets
+          render_htmx_config
+        end
+      end
+
+      # The page's <title> text: the declared title (static, or block-computed
+      # from params in the verb sandbox), else "Weft".
+      def resolved_page_title
+        case (declared = self.class.title_declaration)
+        when Proc then Weft::DSL::Sandbox.run(@params || Weft::Params.new({}), &declared)
+        when nil then "Weft"
+        else declared
+        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
+    end
+  end
+end

data/lib/weft/page.rb

@@ -1,18 +1,32 @@
 # frozen_string_literal: true
 
+require "arbre"
 require "uri"
 
+require "weft/context"
+require "weft/context/interception"
+require "weft/context/traversal"
+require "weft/dsl/containers"
+require "weft/dsl/params"
+require "weft/dsl/recoveries"
+require "weft/error"
+require "weft/page/assets"
+require "weft/page/head"
+require "weft/registry"
+require "weft/registry/eligibility"
+
 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.
+  # head, body); the head surface — the `title` verb and the registered
+  # scripts and stylesheets — lives in Page::Head and Page::Assets.
+  # 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
+  #     param :order_id
   #   end
   #
   # Subclasses without an explicit page_path auto-infer one from the class
@@ -20,13 +34,16 @@ module Weft
   # 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
+  class Page < Arbre::Component
     extend Weft::Registry::Eligibility
 
     include Weft::Context::Interception
-    include Weft::DSL::Attributes
+    include Weft::DSL::Params
     include Weft::DSL::Recoveries
     include Weft::DSL::Containers
+    include Weft::Context::Traversal
+    include Assets
+    include Head
 
     # @!method weft_page(*args, &block)
     #   @api private
@@ -34,20 +51,9 @@ module Weft
     #   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).
+      # Bidirectional: forward (interpolate params → URL) and reverse (match request → params).
       #
       #   self.page_path = "/orders/:order_id"
       def page_path
@@ -60,28 +66,28 @@ module Weft
 
       attr_writer :page_path
 
-      # Resolve the page path by interpolating attrs into the pattern.
+      # Resolve the page path by interpolating params into the pattern.
       #   OrderDetailPage.resolve_page_path(order_id: "42") # => "/orders/42"
-      def resolve_page_path(attrs = {})
+      def resolve_page_path(params = {})
         pattern = page_path || default_page_path
-        pattern.gsub(/:(\w+)/) { attrs[::Regexp.last_match(1).to_sym] || ":#{::Regexp.last_match(1)}" }
+        pattern.gsub(/:(\w+)/) { params[::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
+      # Build a redirect URL targeting this page with the given params.
+      # Path :param segments interpolate from params; declared-but-not-path
+      # params 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
+      #     param :order_id
+      #     param :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
+      def redirect_url(params = {})
+        path = resolve_page_path(params)
+        query = params.slice(*(self.params.keys - path_param_keys)).compact
         query.empty? ? path : "#{path}?#{::URI.encode_www_form(query)}"
       end
 
@@ -97,12 +103,12 @@ module Weft
       # 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
+      # is optional: FooBarPage and BazBar both route. Pages with params
       # 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?
+        return false if params.any?
 
         !name.to_s.delete_suffix("Page").demodulize.empty?
       end
@@ -113,98 +119,23 @@ module Weft
       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)
+      # The kwargs are pseudo-wire: exactly what a request's query/path params
+      # would carry. Used by the Router for full-document responses, and
+      # available to users for testing or standalone rendering.
+      def render(**wire_params)
         klass = self
-        Weft::Context.new({}, nil) do
-          insert_tag(klass, **attributes)
+        Weft::Context.new({}, nil, wire_params: wire_params) do
+          insert_tag(klass)
         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?
+        if params.any?
           raise Weft::InvalidDefinition,
-                "#{name} declares attributes but no explicit page_path. " \
-                "Set self.page_path = \"/your/path/:#{attributes.keys.first}\""
+                "#{name} declares params but no explicit page_path. " \
+                "Set self.page_path = \"/your/path/:#{params.keys.first}\""
         end
 
         stem = name.to_s.delete_suffix("Page")
@@ -220,11 +151,17 @@ module Weft
       end
     end
 
+    # Params resolve at construction (see Weft::Component#initialize) so
+    # user build bodies can read them before super — e.g. computing body
+    # chrome from a record looked up by param.
+    def initialize(*)
+      super
+      @params = assembled_params if self.class.declared_keys.any?
+    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))
+      warn_declared_chrome_collisions(attributes)
+      super
       build_head
       @body_el = insert_tag(Arbre::HTML::Body)
     end
@@ -241,127 +178,6 @@ module Weft
       "<!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.