funicular 0.3.0 → 0.5.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
@@ -120,6 +171,72 @@ module Funicular
       self
     end
 
+    # Bind a state key to a local-database Relation (docs decision 10):
+    # the block runs once now, and again after every change event on the
+    # relation's table. Each evaluation re-subscribes (a branchy block
+    # may return a different model's relation this time) and patches
+    # state[key], triggering a re-render. Subscriptions die with the
+    # component (see unmount), even when a lifecycle hook raises.
+    def watch(key, &block)
+      unless block
+        raise ArgumentError, "watch requires a block returning a Relation"
+      end
+      evaluate_watch(key, block)
+      nil
+    end
+
+    # Framework use (the subscription re-enters here on every event).
+    def evaluate_watch(key, block)
+      relation = block.call
+      unless relation.is_a?(Funicular::Relation)
+        raise ArgumentError,
+          "the watch(:#{key}) block must return a Funicular::Relation, " \
+          "got #{relation.class}; for hashes, counts, or raw SQL, " \
+          "subscribe with Model.on_change and patch state yourself"
+      end
+      # Materialize BEFORE touching subscriptions: if the query raises,
+      # neither a fresh subscription leaks (initial watch) nor the
+      # previous healthy one is lost (re-evaluation). Next-tick delivery
+      # guarantees no change event interleaves with this evaluation.
+      records = relation.to_a
+      source = relation.__event_source
+      watches = (@__watches ||= {}) # steep:ignore UnannotatedEmptyCollection
+      old = watches[key]
+      Funicular::DB.unsubscribe(old) if old
+      component = self
+      watches[key] = Funicular::DB.subscribe(source[0], source[1]) do |r, t|
+        component.evaluate_watch(key, block)
+      end
+      if @mounted
+        # The normal update contract: patch runs the update lifecycle
+        # (component_will_update/component_updated/component_raised),
+        # normalizes values, and re-renders. The bus's next-tick
+        # delivery guarantees we are never inside another update here.
+        patch(key => records)
+      else
+        # Before mount there is no update lifecycle to honor yet: land
+        # the initial data directly so state is ready for the first
+        # render.
+        @state = @state.merge({ key => records })
+        @state_accessor = nil
+      end
+      nil
+    end
+
+    def cleanup_watches
+      watches = @__watches
+      return nil unless watches
+      keys = watches.keys
+      keys_size = keys.size
+      i = 0
+      while i < keys_size
+        Funicular::DB.unsubscribe(watches[keys[i]])
+        i += 1
+      end
+      @__watches = {}
+      nil
+    end
+
     # Load all registered suspense data
     # Called automatically in component_mounted if suspense definitions exist
     def load_suspense_data
@@ -230,21 +347,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 +371,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)
@@ -349,6 +474,10 @@ module Funicular
 
         component_mounted if respond_to?(:component_mounted)
       rescue => e
+        # A failed mount never reaches unmount (@mounted is still
+        # false), so watch subscriptions taken before/during the mount
+        # must be released here or they would pin the dead component.
+        cleanup_watches
         component_raised(e) if respond_to?(:component_raised)
         raise e
       end
@@ -364,9 +493,12 @@ module Funicular
     # window.__FUNICULAR_STATE__ before calling this.
     def hydrate(dom_element)
       return if @mounted
-      raise "hydrate: missing server DOM element" unless dom_element
 
       begin
+        # Inside the begin so a nil element takes the same cleanup path
+        # (releasing watch subscriptions) as every other hydrate failure.
+        raise "hydrate: missing server DOM element" unless dom_element
+
         component_will_mount if respond_to?(:component_will_mount)
 
         # The router/start sets the container; without it, unmount could not
@@ -408,11 +540,30 @@ module Funicular
 
         component_mounted if respond_to?(:component_mounted)
       rescue => e
+        # Same as mount: a failed hydrate cannot be unmounted, so the
+        # watch subscriptions must not outlive it.
+        cleanup_watches
         component_raised(e) if respond_to?(:component_raised)
         raise e
       end
     end
 
+    # Navigation guard: return a String message to ask the user for
+    # confirmation before this component is navigated away from (router
+    # navigation, browser back/forward, reload, tab close), or nil to
+    # allow leaving freely. Consulted by the router and its beforeunload
+    # listener; override in components with unsaved work:
+    #
+    #   def navigation_guard
+    #     state[:dirty] ? "Unsaved changes will be lost. Leave?" : nil
+    #   end
+    #
+    # Must not suspend (no fetch/HTTP): the beforeunload path runs it on
+    # the synchronous JS event dispatch stack.
+    def navigation_guard
+      nil
+    end
+
     # Unmount component from DOM
     def unmount
       return unless @mounted
@@ -443,23 +594,29 @@ module Funicular
       rescue => e
         component_raised(e) if respond_to?(:component_raised)
         raise e
+      ensure
+        # Watch subscriptions die with the component NO MATTER WHAT: a
+        # raising lifecycle hook must not leave a zombie watcher
+        # patching an unmounted component (docs decision 10).
+        cleanup_watches
       end
     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
@@ -499,6 +656,7 @@ module Funicular
             begin
               self.send(value, event)
             rescue => e
+              report_handler_error(event_name, "##{value}", e)
               component_raised(e) if respond_to?(:component_raised)
               raise e
             end
@@ -515,6 +673,7 @@ module Funicular
                 value.call(event)
               end
             rescue => e
+              report_handler_error(event_name, "##{value.name}", e)
               component_raised(e) if respond_to?(:component_raised)
               raise e
             end
@@ -531,6 +690,7 @@ module Funicular
                 value.call(event)
               end
             rescue => e
+              report_handler_error(event_name, "(proc)", e)
               component_raised(e) if respond_to?(:component_raised)
               raise e
             end
@@ -563,6 +723,18 @@ module Funicular
       end
     end
 
+    # Name the culprit before an event handler error is re-raised into
+    # the JS bridge, where "Callback <id>: ArgumentError: ..." carries no
+    # hint of which component or handler it came from. Uses puts so the
+    # message reaches the browser console (same idiom as the
+    # ErrorBoundary logger). Never raises itself.
+    def report_handler_error(event_name, handler, error)
+      puts "[Funicular] #{self.class}#{handler} (on#{event_name}) raised " \
+           "#{error.class}: #{error.message}"
+    rescue
+      nil
+    end
+
     # Collect ref elements from VDOM
     # Called by VDOM::Renderer and Patcher
     def collect_refs(dom_element, vnode, refs_map = {})
@@ -622,9 +794,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 +862,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 +1089,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)