funicular 0.3.0 → 0.4.0

data/mrblib/component.rb

@@ -52,9 +52,60 @@ module Funicular
       end
     end
 
+    include Tags
+
     attr_accessor :props, :vdom, :dom_element, :mounted, :runtime, :children, :current_children
     attr_reader :refs
 
+    # Opt out of DSL collision detection for the given method names. The
+    # shadowed tag remains reachable through tag(:name, ...).
+    def self.allow_dsl_override(*names)
+      @dsl_overrides ||= [] #: Array[Symbol]
+      @dsl_overrides.concat(names)
+    end
+
+    def self.dsl_overrides
+      @dsl_overrides ||= [] #: Array[Symbol]
+    end
+
+    # Layer 1: catches `def`, `define_method`, and `alias` in subclasses at
+    # class-definition time. attr_* does not fire this hook on mruby, and
+    # included modules never do; validate_dsl_conflicts! covers those.
+    def self.method_added(name)
+      if self != Funicular::Component && Funicular::Tags::RESERVED_DSL[name] && !dsl_overrides.include?(name)
+        kind = Funicular::Tags::RESERVED_DSL[name] == :tag ? "<#{name}> tag helper" : "##{name} helper"
+        raise Funicular::DSLCollisionError,
+          "#{self}##{name} collides with the Funicular DSL (#{kind}). " \
+          "Rename it (e.g. `#{name}_value`), or declare `allow_dsl_override :#{name}` " \
+          "and use `tag(:#{name}, ...)` to emit the element."
+      end
+      super
+    end
+
+    # Layer 2: once per class, sweep methods the method_added hook cannot
+    # see (attr_* on mruby, user-included modules).
+    def self.validate_dsl_conflicts!
+      return if @dsl_validated
+      if instance_method(:render).arity != 0
+        raise Funicular::DSLCollisionError,
+          "#{self}#render must not take parameters as of Funicular 0.4.0: " \
+          "delete the parameter (`def render`) and drop the `h.` receivers " \
+          "inside; tags are bareword methods on the component now."
+      end
+      ancestors.each do |mod|
+        break if mod == Funicular::Component || mod == Funicular::Tags
+        next unless mod.is_a?(Module)
+        methods = mod.instance_methods(false) + mod.private_instance_methods(false)
+        offenders = methods.select { |m| Funicular::Tags::RESERVED_DSL[m] } - dsl_overrides
+        next if offenders.empty?
+        raise Funicular::DSLCollisionError,
+          "#{mod} defines methods that collide with the Funicular DSL: " \
+          "#{offenders.map { |m| m.to_s }.join(', ')}. Rename them, or declare " \
+          "`allow_dsl_override` and use `tag(...)` to emit the element."
+      end
+      @dsl_validated = true
+    end
+
     def initialize(props = {})
       @props = props
       @state = initialize_state || {}
@@ -93,7 +144,7 @@ module Funicular
     end
 
     def styles
-      @style_accessor ||= StyleAccessor.new(self.class.styles_definitions)
+      @style_accessor ||= self.class.style_accessor_class.new(self.class.styles_definitions)
     end
 
     # Override this method in subclasses to define initial state
@@ -230,21 +281,21 @@ module Funicular
     #   ) do
     #     div { user.name }
     #   end
-    def render_suspense(h, name, fallback:, error: nil, &block)
+    def render_suspense(name, fallback:, error: nil, &block)
       current_children = @current_children
       child_count_before = current_children&.size
       result = nil
 
       if @suspense_states[name] == :rejected
         result = if error
-          error.call(h, @suspense_errors[name])
+          error.call(@suspense_errors[name])
         else
-          fallback.call(h)
+          fallback.call
         end
       elsif suspense_loading?(name)
-        result = fallback.call(h)
+        result = fallback.call
       else
-        result = block.call(h, resources)
+        result = block.call(resources)
       end
 
       if current_children && current_children.size == child_count_before
@@ -254,17 +305,25 @@ module Funicular
       result
     end
 
-    # Class methods for styles DSL
+    # Class methods for styles DSL. The block is instance_exec'd on a
+    # StyleBuilder cleanroom so barewords define styles; it also receives
+    # the builder for the explicit `styles { |css| css.define(...) }` form.
     def self.styles(&block)
       builder = StyleBuilder.new
-      block.call(builder)
+      builder.instance_exec(builder, &block) # steep:ignore
       @styles_definitions = builder.to_definitions
+      @style_accessor_class = nil
     end
 
     def self.styles_definitions
       @styles_definitions ||= {}
     end
 
+    # Per-class accessor with one real method per declared style name.
+    def self.style_accessor_class
+      @style_accessor_class ||= StyleAccessor.accessor_for(styles_definitions)
+    end
+
     # Suspense DSL - register async data loaders
     #
     # @param name [Symbol] Name of the suspense data (becomes accessible as method)
@@ -447,19 +506,20 @@ module Funicular
     end
 
     # Override this method in subclasses to define render logic
-    def render(h)
-      raise "Subclasses must implement render(h)"
+    def render
+      raise "Subclasses must implement render"
     end
 
     # Build VDOM tree from render method
     # Called by VDOM::Renderer, Differ, and Patcher
     def build_vdom
+      self.class.validate_dsl_conflicts!
       previous_rendering = @rendering
       previous_children = @current_children
       @rendering = true
       @current_children = nil
       begin
-        result = render(ViewContext.new(self))
+        result = render
       ensure
         @rendering = previous_rendering
         @current_children = previous_children
@@ -622,9 +682,45 @@ module Funicular
       normalize_vnode(value)
     end
 
+    # Internal element factory shared by the Tags mixin, FormBuilder, and
+    # the framework helpers. One instance per component; ViewContext itself
+    # is stateless (the render cursor lives on the component).
+    def __view__
+      @__view__ ||= ViewContext.new(self)
+    end
+
+    def routes
+      @runtime.routes
+    end
+
+    # Bareword DSL helpers available inside render (self is the component).
+    def component(component_class, props = {}, &block)
+      __view__.component(component_class, props, &block)
+    end
+
+    def form_for(model_key, options = {}, &block)
+      build_form_for(__view__, model_key, options, &block)
+    end
+
+    def link_to(path, **options, &block)
+      build_link_to(__view__, path, **options, &block)
+    end
+
+    def button_to(path, method: :post, **options, &block)
+      build_button_to(__view__, path, method: method, **options, &block)
+    end
+
+    def suspense(name, fallback:, error: nil, &block)
+      render_suspense(name, fallback: fallback, error: error, &block)
+    end
+
     def add_child_from_view(child)
+      unless @rendering
+        raise Funicular::RenderContextError,
+          "view DSL called outside render (tags may only be used while the component is rendering)"
+      end
       current_children = @current_children
-      return unless @rendering && current_children
+      return unless current_children
 
       normalized = normalize_vnode(child)
       current_children << normalized if normalized
@@ -654,8 +750,8 @@ module Funicular
         ->(event) { event.preventDefault }
       end
 
-      h.form({ onsubmit: submit_handler, class: form_class }.merge(options)) do |hh|
-        builder = Funicular::FormBuilder.new(self, hh, model_key, options)
+      h.form({ onsubmit: submit_handler, class: form_class }.merge(options)) do
+        builder = Funicular::FormBuilder.new(self, h, model_key, options)
         block.call(builder)
       end
     end
@@ -881,15 +977,9 @@ module Funicular
     end
 
     def event_target(event)
-      target = nil
-      begin
-        target = event[:target]
-      rescue
-        target = nil
-      end
-      return target if target
-
-      event.target if event.respond_to?(:target)
+      event[:target]
+    rescue
+      nil
     end
 
     def add_form_field_value(data, field)

data/mrblib/error_boundary.rb

@@ -3,17 +3,23 @@ module Funicular
   # a fallback UI instead of crashing the entire application.
   #
   # Usage:
-  #   h.component(ErrorBoundary) do |hh|
-  #     hh.component(RiskyComponent)
+  #   component(ErrorBoundary) do
+  #     component(RiskyComponent)
   #   end
   #
   # With custom fallback:
-  #   h.component(ErrorBoundary, fallback: ->(h, error) { h.div { "Error: #{error.message}" } }) do |hh|
-  #     hh.component(RiskyComponent)
+  #   component(ErrorBoundary, fallback: ->(h, error) { h.div { "Error: #{error.message}" } }) do
+  #     component(RiskyComponent)
   #   end
   #
   # Props:
-  #   - fallback: Proc or Method that receives the error and returns VDOM
+  #   - fallback: Proc or Method that receives (view_context, error) and
+  #     returns VDOM. NOTE: unlike everywhere else, the fallback cannot use
+  #     bareword tags. The proc is created in the parent component's scope
+  #     but runs during the boundary's render, where only the boundary's
+  #     cursor is active; a bareword tag would dispatch against the parent
+  #     and raise RenderContextError. Build elements through the view
+  #     context argument (`h.div { ... }`) instead.
   #   - on_error: Optional callback when error is caught (for logging, reporting)
   #
   class ErrorBoundary < Component
@@ -60,47 +66,47 @@ module Funicular
       end
     end
 
-    def render(h)
+    def render
       if state[:has_error]
-        render_fallback(h)
+        render_fallback
       else
-        render_children(h)
+        render_children
       end
     end
 
     private
 
-    def render_fallback(h)
+    def render_fallback
       if props[:fallback]
-        result = props[:fallback].call(h, state[:error])
+        result = props[:fallback].call(__view__, state[:error])
         if result.is_a?(VDOM::VNode)
           result
         else
-          h.div { result.to_s }
+          div { result.to_s }
         end
       else
-        default_fallback(h)
+        default_fallback
       end
     end
 
-    def default_fallback(h)
-      h.div(class: 'error-boundary-fallback', style: 'padding: 20px; background: #fee; border: 1px solid #f00; border-radius: 4px;') do |hh|
-        hh.h3(style: 'color: #c00; margin: 0 0 10px 0;') { "Something went wrong" }
+    def default_fallback
+      div(class: 'error-boundary-fallback', style: 'padding: 20px; background: #fee; border: 1px solid #f00; border-radius: 4px;') do
+        h3(style: 'color: #c00; margin: 0 0 10px 0;') { "Something went wrong" }
         if state[:error]
-          hh.div(style: 'font-family: monospace; white-space: pre-wrap; font-size: 12px; color: #600;') do
+          div(style: 'font-family: monospace; white-space: pre-wrap; font-size: 12px; color: #600;') do
             "#{state[:error].class}: #{state[:error].message}"
           end
         end
         if Funicular.env.development? && state[:error_info]
-          hh.div(style: 'margin-top: 10px; font-size: 11px; color: #666;') do
+          div(style: 'margin-top: 10px; font-size: 11px; color: #666;') do
             "Component: #{state[:error_info][:component_class]}"
           end
         end
       end
     end
 
-    def render_children(h)
-      h.div(class: 'error-boundary-content') do
+    def render_children
+      div(class: 'error-boundary-content') do
         children
       end
     end

data/mrblib/form_builder.rb

@@ -65,10 +65,10 @@ module Funicular
       attrs[:class] = css_class unless css_class.empty?
 
       # Render field + error message
-      @view_context.div do |h|
-        h.input(attrs)
+      @view_context.div do
+        @view_context.input(attrs)
         if has_error
-          h.div(class: @error_class) { error_message }
+          @view_context.div(class: @error_class) { error_message }
         end
       end
     end
@@ -128,10 +128,10 @@ module Funicular
 
       attrs[:class] = css_class unless css_class.empty?
 
-      @view_context.div do |h|
-        h.textarea(attrs)
+      @view_context.div do
+        @view_context.textarea(attrs)
         if has_error
-          h.div(class: @error_class) { error_message }
+          @view_context.div(class: @error_class) { error_message }
         end
       end
     end
@@ -194,18 +194,18 @@ module Funicular
 
       attrs[:class] = css_class unless css_class.empty?
 
-      @view_context.div do |h|
-        h.select(attrs) do |hh|
+      @view_context.div do
+        @view_context.select(attrs) do
           choices.each do |choice|
             option_value, option_text = choice.is_a?(Array) ? choice : [choice, choice]
             selected = value.to_s == option_value.to_s
-            hh.option(value: option_value, selected: selected) do
+            @view_context.option(value: option_value, selected: selected) do
               option_text
             end
           end
         end
         if has_error
-          h.div(class: @error_class) { error_message }
+          @view_context.div(class: @error_class) { error_message }
         end
       end
     end

data/mrblib/funicular.rb

@@ -18,7 +18,7 @@ module Funicular
   # Guard against redefinition: when the mrblib runtime is loaded into a
   # CRuby/Rails process for SSR, lib/funicular/version.rb has already defined
   # VERSION for the CRuby gem. In the wasm build VERSION is undefined here.
-  VERSION = '0.3.0' unless Funicular.const_defined?(:VERSION)
+  VERSION = '0.4.0' unless Funicular.const_defined?(:VERSION)
 
   def self.version
     VERSION

data/mrblib/styles.rb

@@ -25,25 +25,42 @@ module Funicular
     end
   end
 
-  class StyleAccessor
+  # Read-side accessor. One subclass is generated per component class with a
+  # real method per declared style name (see accessor_for), so lookups never
+  # go through method_missing at render time and a typo raises loudly.
+  # BasicObject keeps Object/Kernel names (display, hash, ...) usable as
+  # style names on both mruby and CRuby.
+  class StyleAccessor < BasicObject
+    def self.accessor_for(definitions)
+      klass = ::Class.new(self) #: singleton(StyleAccessor)
+      definitions.each_key do |name|
+        klass.__send__(:define_method, name) do |variant = nil|
+          self[name, variant] # steep:ignore
+        end
+      end
+      klass
+    end
+
     def initialize(definitions)
       @definitions = definitions
     end
 
     def [](name, variant = nil)
       style = @definitions[name]
-      return StyleValue.new("") unless style
+      unless style
+        ::Kernel.raise ::ArgumentError,
+          "unknown style :#{name} (declared: #{@definitions.keys.map { |k| ":#{k}" }.join(', ')})"
+      end
 
       if variant.nil?
         # No arguments: return base or value
         StyleValue.new(style[:base] || style[:value] || "")
       elsif variant == true || variant == false
         # Boolean argument: base + active (if true)
-        # JS::Object#== now supports direct comparison with Ruby true/false
         base = style[:base] || ""
         active_class = (variant == true) ? (style[:active] || "") : ""
         StyleValue.new("#{base} #{active_class}".strip)
-      elsif variant.is_a?(Symbol)
+      elsif ::Symbol === variant
         # Symbol argument: base + variants[symbol]
         base = style[:base] || ""
         variant_class = style[:variants] ? (style[:variants][variant] || "") : ""
@@ -53,27 +70,100 @@ module Funicular
         StyleValue.new(style[:base] || style[:value] || "")
       end
     end
+
+    def method_missing(name, *_args)
+      ::Kernel.raise ::NoMethodError,
+        "unknown style '#{name}' (declared: #{@definitions.keys.map { |k| ":#{k}" }.join(', ')})"
+    end
+
+    def respond_to_missing?(name, _include_private = false)
+      @definitions.key?(name)
+    end
   end
 
-  class StyleBuilder
+  # Definition-side builder. The class-level `styles do ... end` block is
+  # instance_exec'd on an instance, so barewords define styles:
+  #
+  #   styles do
+  #     shell "app-shell"
+  #     button base: "btn", variants: { primary: "btn--primary" }
+  #   end
+  #
+  # BasicObject keeps the bareword namespace clean on both VMs; the block
+  # also receives the builder as an argument for the explicit form
+  # `styles { |css| css.define(:name, ...) }`, needed when a value is
+  # computed (a bareword helper call inside the block would be captured as
+  # a style definition, and its nil return raises via validation below).
+  class StyleBuilder < BasicObject
+    # Style names that would clobber the builder/accessor internals.
+    RESERVED_NAMES = %i[
+      initialize method_missing respond_to_missing? define to_definitions
+      validate_options
+      == != ! [] equal? __send__ __id__ instance_eval instance_exec
+    ]
+
     def initialize
-      @definitions = {}
+      @definitions = {} #: Hash[Symbol, untyped]
     end
 
     def define(name, value = nil, **options)
-      if value.is_a?(String)
+      if RESERVED_NAMES.include?(name)
+        ::Kernel.raise ::ArgumentError, "style name :#{name} is reserved"
+      end
+      if @definitions.key?(name)
+        ::Kernel.raise ::ArgumentError, "style :#{name} is already defined"
+      end
+
+      if ::String === value
         @definitions[name] = { value: value }
-      elsif value.is_a?(Hash)
-        @definitions[name] = value
-      elsif !options.empty?
-        @definitions[name] = options
+      elsif ::Hash === value
+        @definitions[name] = validate_options(name, value)
+      elsif (::NilClass === value) && !options.empty?
+        @definitions[name] = validate_options(name, options)
       else
-        raise ArgumentError, "Invalid style definition for #{name}"
+        ::Kernel.raise ::ArgumentError,
+          "invalid style definition for :#{name}; expected a String, a " \
+          "Hash, or keyword options. Note: helper methods cannot be called " \
+          "bareword inside a styles block; use " \
+          "`styles { |css| css.define(...) }` for computed values."
+      end
+      self
+    end
+
+    def validate_options(name, options)
+      options.each do |key, val|
+        case key
+        when :value, :base, :active
+          unless ::String === val
+            ::Kernel.raise ::ArgumentError,
+              "style :#{name} option #{key}: must be a String. Note: helper " \
+              "methods cannot be called bareword inside a styles block; use " \
+              "`styles { |css| css.define(...) }` for computed values."
+          end
+        when :variants
+          unless (::Hash === val) && val.all? { |_k, v| ::String === v }
+            ::Kernel.raise ::ArgumentError,
+              "style :#{name} option variants: must be a Hash of Symbol => String"
+          end
+        else
+          ::Kernel.raise ::ArgumentError,
+            "style :#{name} has unknown option #{key.inspect} " \
+            "(allowed: value, base, active, variants)"
+        end
       end
+      options
     end
 
     def to_definitions
       @definitions
     end
+
+    def method_missing(name, value = nil, **options)
+      define(name, value, **options)
+    end
+
+    def respond_to_missing?(_name, _include_private = false)
+      true
+    end
   end
 end

data/mrblib/view_context.rb

@@ -1,40 +1,11 @@
 module Funicular
   class ViewContext
-    HTML_TAGS = %w[
-      div span p a data
-      h1 h2 h3 h4 h5 h6
-      ul ol li
-      table thead tbody tr th td
-      form input textarea button select option label
-      header footer nav section article aside
-      img video audio canvas
-      br hr
-    ]
+    HTML_TAGS = Funicular::Tags::HTML_TAGS
 
     def initialize(component)
       @component = component
     end
 
-    def state
-      @component.state
-    end
-
-    def props
-      @component.props
-    end
-
-    def resources
-      @component.resources
-    end
-
-    def styles
-      @component.styles
-    end
-
-    def routes
-      @component.runtime.routes
-    end
-
     def tag(name, props = {}, &block)
       build_element(name, props, &block)
     end
@@ -66,7 +37,7 @@ module Funicular
     end
 
     def suspense(name, fallback:, error: nil, &block)
-      @component.render_suspense(self, name, fallback: fallback, error: error, &block)
+      @component.render_suspense(name, fallback: fallback, error: error, &block)
     end
 
     def link_to(path, **options, &block)
@@ -81,7 +52,7 @@ module Funicular
       children = [] #: Array[Funicular::VDOM::child_t]
       previous = @component.current_children
       @component.current_children = children
-      result = block.call(self)
+      result = block.call
       @component.current_children = previous
 
       if result && !result.equal?(children) && children.empty?

data/sig/component.rbs

@@ -17,6 +17,8 @@ module Funicular
       def error: (Symbol key) -> untyped
     end
 
+    include Tags
+
     attr_accessor props: Hash[Symbol, untyped]
     attr_accessor vdom: VDOM::VNode | VDOM::Text | nil
     attr_accessor dom_element: JS::Element
@@ -29,8 +31,13 @@ module Funicular
     type suspense_definition = { loader: untyped, on_resolve: untyped, min_delay: Integer? }
 
     def initialize: (?Hash[Symbol, untyped] props) -> void
+    def self.allow_dsl_override: (*Symbol names) -> void
+    def self.dsl_overrides: () -> Array[Symbol]
+    def self.method_added: (Symbol name) -> void
+    def self.validate_dsl_conflicts!: () -> void
     def self.styles: () { (StyleBuilder) -> void } -> void
     def self.styles_definitions: () -> Hash[Symbol, Hash[Symbol, untyped]]
+    def self.style_accessor_class: () -> singleton(StyleAccessor)
     def self.use_suspense: (Symbol name, untyped loader, ?on_resolve: untyped, ?min_delay: Integer) -> void
     def self.suspense_definitions: () -> Hash[Symbol, suspense_definition]
 
@@ -46,22 +53,29 @@ module Funicular
     def suspense_loading?: (*Symbol names) -> bool
     def suspense_error?: (Symbol name) -> bool
     def suspense_error: (Symbol name) -> untyped
-    def render_suspense: (ViewContext h, Symbol name, fallback: untyped, ?error: untyped) { (ViewContext, ResourceAccessor) -> untyped } -> untyped
+    def render_suspense: (Symbol name, fallback: untyped, ?error: untyped) { (ResourceAccessor) -> untyped } -> untyped
 
     def patch: (Hash[Symbol, untyped] new_state) -> void
     def mount: (JS::Element container) -> void
     def hydrate: (JS::Element dom_element) -> void
     def unmount: () -> void
-    def render: (ViewContext h) -> (VDOM::VNode | String | Integer | Float | Array[untyped] | nil)
+    def render: () -> (VDOM::VNode | String | Integer | Float | Array[untyped] | nil)
     def build_vdom: () -> (VDOM::VNode | VDOM::Text | nil)
 
     def bind_events: (JS::Element dom_element, VDOM::VNode | VDOM::Text | nil vnode) -> void
     def collect_refs: (JS::Element dom_element, VDOM::VNode | VDOM::Text | nil vnode, ?Hash[Symbol, JS::Element] refs_map) -> Hash[Symbol, JS::Element]
     def normalize_vnode_for_view: (untyped value) -> (VDOM::Element | VDOM::Text | VDOM::Component | nil)
+    def __view__: () -> ViewContext
+    def routes: () -> untyped
+    def component: (singleton(Component) component_class, ?Hash[Symbol, untyped] props) ?{ () -> untyped } -> VDOM::Component
+    def form_for: (Symbol model_key, ?Hash[Symbol, untyped] options) { (FormBuilder) -> void } -> VDOM::Element
+    def link_to: (String path, **untyped options) ?{ -> untyped } -> VDOM::Element
+    def button_to: (String path, ?method: Symbol, **untyped options) ?{ -> untyped } -> VDOM::Element
+    def suspense: (Symbol name, fallback: untyped, ?error: untyped) { (ResourceAccessor) -> untyped } -> untyped
     def add_child_from_view: (untyped child) -> void
     def build_form_for: (ViewContext h, Symbol model_key, ?Hash[Symbol, untyped] options) { (FormBuilder) -> void } -> VDOM::Element
-    def build_link_to: (ViewContext h, String path, **untyped options) { (ViewContext) -> untyped } -> VDOM::Element
-    def build_button_to: (ViewContext h, String path, ?method: Symbol, **untyped options) { (ViewContext) -> untyped } -> VDOM::Element
+    def build_link_to: (ViewContext h, String path, **untyped options) ?{ () -> untyped } -> VDOM::Element
+    def build_button_to: (ViewContext h, String path, ?method: Symbol, **untyped options) ?{ () -> untyped } -> VDOM::Element
 
     def component_will_mount: () -> void
     def component_mounted: () -> void

data/sig/error_boundary.rbs

@@ -5,10 +5,10 @@ module Funicular
     def initialize_state: () -> Hash[Symbol, untyped]
     def catch_error: (Exception error, ?Hash[Symbol, untyped]? error_info) -> bool
     def reset: () -> void
-    def render: (ViewContext h) -> (VDOM::VNode | String | Integer | Float | Array[untyped] | nil)
+    def render: () -> (VDOM::VNode | String | Integer | Float | Array[untyped] | nil)
 
-    private def render_fallback: (ViewContext h) -> (VDOM::VNode | String)
-    private def default_fallback: (ViewContext h) -> VDOM::VNode
-    private def render_children: (ViewContext h) -> VDOM::VNode
+    private def render_fallback: () -> (VDOM::VNode | String)
+    private def default_fallback: () -> VDOM::VNode
+    private def render_children: () -> VDOM::VNode
   end
 end