funicular 0.1.0 → 0.2.1

data/mrblib/component.rb

@@ -62,6 +62,25 @@ module Funicular
       {}
     end
 
+    # Merge externally provided state into the component before rendering.
+    # Used by SSR to inject server data, and by client hydration to restore
+    # the same state from window.__FUNICULAR_STATE__ so the first client
+    # render matches the server HTML. Top-level keys are symbolized so they
+    # are reachable via state.foo (StateAccessor uses symbol keys); nested
+    # values are left untouched (components read them with string keys).
+    def seed_state(state_hash)
+      return self if state_hash.nil?
+      return self if state_hash.respond_to?(:empty?) && state_hash.empty?
+
+      symbolized = {} #: Hash[Symbol, untyped]
+      state_hash.each do |key, value|
+        symbolized[key.to_sym] = value
+      end
+      @state = @state.merge(symbolized)
+      @state_accessor = nil
+      self
+    end
+
     # Load all registered suspense data
     # Called automatically in component_mounted if suspense definitions exist
     def load_suspense_data
@@ -173,10 +192,14 @@ module Funicular
     #     div { user.name }
     #   end
     def suspense(fallback:, error: nil, &block)
+      current_children = @current_children
+      child_count_before = current_children&.size
+      result = nil
+
       # Check for any rejected suspense
       rejected_name = self.class.suspense_definitions.keys.find { |name| @suspense_states[name] == :rejected }
       if rejected_name
-        if error
+        result = if error
           error.call(@suspense_errors[rejected_name])
         else
           fallback.call
@@ -184,13 +207,17 @@ module Funicular
       elsif suspense_loading?
         # Check if any suspense is still loading
         # Note: Loading is started in mount(), not here
-        fallback.call
+        result = fallback.call
       else
         # All suspense data loaded, render content
-        block.call
+        result = block.call
       end
-      # Note: We don't add result to @current_children because
-      # the DSL methods inside fallback/block already do that
+
+      if current_children && current_children.size == child_count_before
+        add_child(result)
+      end
+
+      result
     end
 
     # Class methods for styles DSL
@@ -298,6 +325,65 @@ module Funicular
       end
     end
 
+    # Hydrate this component against server-rendered DOM.
+    #
+    # Unlike mount, which builds a fresh DOM tree via VDOM::Renderer, hydrate
+    # reuses the existing DOM produced by the server: it builds the VDOM,
+    # associates it with the existing nodes, and only attaches event listeners
+    # and refs (plus wiring child components). The first client render must
+    # match the server HTML, which is why state is seeded from
+    # window.__FUNICULAR_STATE__ before calling this.
+    def hydrate(dom_element)
+      return if @mounted
+      raise "hydrate: missing server DOM element" unless dom_element
+
+      begin
+        component_will_mount if respond_to?(:component_will_mount)
+
+        # The router/start sets the container; without it, unmount could not
+        # detach this subtree later. Derive it from the existing DOM.
+        @container ||= dom_element.parentNode
+        @dom_element = dom_element
+
+        new_vdom = build_vdom
+
+        if hydration_match?(new_vdom, dom_element)
+          # Wire child components first so their instances exist for collection.
+          hydrate_child_components(new_vdom, dom_element)
+
+          # Reuse the same positional walks as mount: they skip Component vnodes
+          # (children manage their own events/refs during their own hydrate).
+          bind_events(dom_element, new_vdom)
+          collect_refs(dom_element, new_vdom)
+          collect_child_components(new_vdom)
+        else
+          # Server and client disagree on structure (nondeterministic render or
+          # stale state). Recover by discarding the server DOM and rendering a
+          # fresh tree, the same way mount does. The page stays usable; only the
+          # first-paint reuse is lost for this subtree.
+          warn_hydration_mismatch(new_vdom, dom_element)
+          @dom_element = full_render_fallback(new_vdom, dom_element)
+        end
+
+        @vdom = new_vdom
+        @mounted = true
+
+        load_suspense_data if self.class.suspense_definitions.any?
+
+        @child_components.each do |child|
+          unless child.mounted
+            child.mounted = true
+            child.component_mounted if child.respond_to?(:component_mounted)
+          end
+        end
+
+        component_mounted if respond_to?(:component_mounted)
+      rescue => e
+        component_raised(e) if respond_to?(:component_raised)
+        raise e
+      end
+    end
+
     # Unmount component from DOM
     def unmount
       return unless @mounted
@@ -495,42 +581,25 @@ module Funicular
 
     private
 
-    # Normalize state value by converting JS::Object to Ruby native types
+    # Normalize state value for storage. Primitives are already auto-
+    # converted to Ruby native values by picoruby-wasm, so only composite
+    # JS::Object values (array / plain object / function / symbol / bigint)
+    # and nested Ruby collections need handling here.
     def normalize_state_value(value)
-      if value.is_a?(Hash)
-        # Recursively normalize hash values
+      case value
+      when Hash
         normalized = {} #: Hash[untyped, untyped]
-        value.each do |k, v|
-          normalized[k] = normalize_state_value(v)
-        end
+        value.each { |k, v| normalized[k] = normalize_state_value(v) }
         normalized
-      elsif value.is_a?(Array)
-        # Recursively normalize array elements
+      when Array
         value.map { |v| normalize_state_value(v) }
-      elsif value.is_a?(JS::Object)
-        # Convert JS::Object to appropriate Ruby type
-        case value.type
-        when :string
-          value.to_s
-        when :number
-          # Check if it's an integer or float
-          num = value.to_f
-          num == num.to_i ? num.to_i : num
-        when :boolean
-          # JS::Object#== now supports direct comparison with Ruby true/false
-          value == true
-        when :null, :undefined
-          nil
-        when :array
+      when JS::Object
+        if value.typeof == :array
           value.to_a.map { |v| normalize_state_value(v) }
-        when :object
-          # For plain objects, keep as JS::Object or convert to hash if needed
-          value
         else
           value
         end
       else
-        # Return as-is for Ruby native types
         value
       end
     end
@@ -546,7 +615,10 @@ module Funicular
       cleanup_events
 
       unless patches.empty?
-        @dom_element = VDOM::Patcher.new.apply(@dom_element, patches)
+        new_dom_element = VDOM::Patcher.new.apply(@dom_element, patches)
+        # apply returns JS::Object (it must accept text-node patches), but
+        # the component's root is always an Element. Narrow to JS::Element.
+        @dom_element = new_dom_element if new_dom_element.is_a?(JS::Element)
       end
 
       bind_events(@dom_element, new_vdom)
@@ -599,6 +671,64 @@ module Funicular
       end
     end
 
+    # Lightweight structural check: the root tag of the freshly built VDOM
+    # must match the server-rendered element. A mismatch means server and
+    # client disagree (nondeterministic render or stale state); the caller
+    # falls back to a full client render.
+    def hydration_match?(vnode, dom_element)
+      return true unless vnode.is_a?(VDOM::Element)
+      actual = dom_element[:tagName]
+      return true unless actual  # non-element node; let later steps surface issues
+      vnode.tag.to_s.downcase == actual.to_s.downcase
+    end
+
+    # Emit a development-only warning describing a hydration mismatch. Uses
+    # puts so the message reaches the browser console (same idiom as the
+    # ErrorBoundary logger), and is silent in production.
+    def warn_hydration_mismatch(vnode, dom_element)
+      return unless Funicular.env.development?
+      expected = vnode.is_a?(VDOM::Element) ? vnode.tag.to_s.downcase : vnode.class.to_s
+      got = dom_element[:tagName].to_s.downcase
+      puts "[Funicular] Hydration mismatch: expected <#{expected}>, found <#{got}>; " \
+           "falling back to full client render"
+    end
+
+    # Recover from a hydration mismatch by rendering a fresh DOM tree and
+    # swapping it in for the server-rendered node. Mirrors mount, minus the
+    # appendChild: the stale node already has a place in the document, so we
+    # replaceChild instead.
+    def full_render_fallback(new_vdom, server_dom)
+      fresh = VDOM::Renderer.new.render(new_vdom)
+      parent = server_dom.parentNode
+      parent.replaceChild(fresh, server_dom) if parent
+      bind_events(fresh, new_vdom)
+      collect_refs(fresh, new_vdom)
+      collect_child_components(new_vdom)
+      fresh
+    end
+
+    # Walk the VDOM and existing DOM in parallel to hydrate nested components.
+    # Uses the same positional indexing as bind_events/collect_refs so the
+    # three walks agree on which DOM node maps to which vnode.
+    def hydrate_child_components(vnode, dom_element)
+      return unless vnode.is_a?(VDOM::Element)
+      return unless dom_element
+
+      dom_children = dom_element.children.to_a
+      vnode.children.each_with_index do |child, index|
+        child_dom = dom_children[index]
+        next unless child_dom
+
+        if child.is_a?(VDOM::Component)
+          instance = child.component_class.new(child.props)
+          child.instance = instance
+          instance.hydrate(child_dom)
+        elsif child.is_a?(VDOM::Element)
+          hydrate_child_components(child, child_dom)
+        end
+      end
+    end
+
     # Collect child component instances from VDOM tree
     def collect_child_components(vnode)
       @child_components = []
@@ -632,6 +762,13 @@ module Funicular
       br hr
     ]
 
+    # The HTML tag DSL methods are public: besides being called inside render
+    # (implicit self), they are invoked by collaborators such as FormBuilder
+    # with an explicit receiver (@component.div). A private method would forbid
+    # that under CRuby (it is tolerated under mruby), which would break SSR of
+    # any component using form_for. Keep them public on both VMs.
+    public
+
     HTML_TAGS.each do |tag|
       define_method(tag) do |props = {}, &block|
         # @type self: Component
@@ -674,6 +811,8 @@ module Funicular
       end
     end
 
+    private
+
     # Helper to add children in DSL blocks
     def add_child(child)
       return unless @rendering && @current_children
@@ -715,20 +854,7 @@ module Funicular
         ->(event) do
           event.preventDefault
 
-          # Collect form data from state
-          model_data = state.send(model_key)
-          form_data = if model_data.is_a?(Hash)
-            model_data
-          elsif model_data.respond_to?(:instance_variables)
-            data = {} #: Hash[Symbol, untyped]
-            model_data.instance_variables.each do |var|
-              key = var.to_s.sub('@', '').to_sym
-              data[key] = model_data.instance_variable_get(var)
-            end
-            data
-          else
-            {} #: Hash[Symbol, untyped]
-          end
+          form_data = collect_form_data(event, model_key)
 
           # Call the submit handler (Symbol, Method, or Proc)
           case on_submit
@@ -753,6 +879,79 @@ module Funicular
       end
     end
 
+    def collect_form_data(event, model_key)
+      form_data = collect_dom_form_data(event)
+      return form_data unless form_data.empty?
+
+      collect_state_form_data(model_key)
+    end
+
+    def collect_dom_form_data(event)
+      form = event_target(event)
+      return {} unless form
+
+      elements = form[:elements]
+      return {} unless elements
+
+      data = {} #: Hash[Symbol, untyped]
+      length_value = elements[:length]
+      length = length_value ? length_value.to_i : 0
+      i = 0
+      while i < length
+        field = elements[i]
+        add_form_field_value(data, field) if field
+        i += 1
+      end
+      data
+    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)
+    end
+
+    def add_form_field_value(data, field)
+      name = field[:name].to_s
+      return if name.empty?
+
+      type = field[:type].to_s.downcase
+      return if %w[submit button reset].include?(type)
+      return if type == "radio" && !field[:checked]
+
+      value = if type == "checkbox"
+        field[:checked]
+      elsif type == "file"
+        field[:files]
+      else
+        field[:value]
+      end
+
+      data[name.to_sym] = value
+    end
+
+    def collect_state_form_data(model_key)
+      model_data = state.send(model_key)
+      if model_data.is_a?(Hash)
+        model_data
+      elsif model_data.respond_to?(:instance_variables)
+        data = {} #: Hash[Symbol, untyped]
+        model_data.instance_variables.each do |var|
+          key = var.to_s.sub('@', '').to_sym
+          data[key] = model_data.instance_variable_get(var)
+        end
+        data
+      else
+        {} #: Hash[Symbol, untyped]
+      end
+    end
+
     # Rails-style link_to helper
     # Default behavior: Fetch API for same-page actions (SPA-friendly)
     # Use navigate: true for router navigation (different component tree)

data/mrblib/debug.rb

@@ -4,6 +4,9 @@ module Funicular
       attr_accessor :enabled
 
       def enabled?
+        # Disabled on the server: SSR instantiates components per request and
+        # must not accumulate them in the debug registry.
+        return false if Funicular.server?
         @enabled ||= Funicular.env.development?
       end
 

data/mrblib/differ.rb

@@ -90,9 +90,22 @@ module Funicular
         end
       end
 
+      # Produce a single composite patch describing a keyed-children diff.
+      #
+      # The earlier implementation emitted independent `[index, ...]` patches
+      # for inserts, removes and updates. The patcher consumed them as
+      # `replaceChild`, which is unsafe whenever insert and remove indices
+      # overlap (e.g. switching between two equal-length sets of keyed
+      # children with disjoint keys): inserts overwrite old nodes in place,
+      # then the descending removes drop the just-inserted new nodes and
+      # the DOM ends up empty.
+      #
+      # The new shape is `[[:keyed_children, ops, removes]]`, applied as
+      # three phases by the patcher:
+      #   1. removes (descending old_index, against the original DOM snapshot)
+      #   2. content updates for kept children (against the snapshot, no move)
+      #   3. inserts in ascending new_index using insertBefore on the live DOM
       def self.diff_children_with_keys(old_children, new_children)
-        patches = [] #: Array[patch_t]
-
         # 1. Build key map from old children
         old_key_map = {} #: Hash[untyped, [Integer, child_t]]
         old_children.each_with_index do |child, index|
@@ -101,63 +114,60 @@ module Funicular
           end
         end
 
-        # 2. Track matched old indices
         matched_old_indices = {} #: Hash[Integer, bool]
+        ops = [] #: Array[Array[untyped]]
+        has_change = false
 
-        # 3. Process new children
+        # 2. Process new children, recording one op per new position
         new_children.each_with_index do |new_child, new_index|
           if new_child.is_a?(VNode) && new_child.respond_to?(:key) && new_child.key
             key = new_child.key
-
             if old_key_map[key]
               old_index, old_child = old_key_map[key]
               matched_old_indices[old_index] = true
-
-              # Diff existing element
               child_patches = diff(old_child, new_child)
-              unless child_patches.empty?
-                patches << [new_index, child_patches]
-              end
+              ops << [:keep, old_index, new_index, child_patches]
+              has_change = true unless child_patches.empty?
             else
-              # Insert new element
-              patches << [new_index, [[:replace, new_child, nil]]] # old_node is nil for insertion
+              ops << [:insert, new_index, new_child]
+              has_change = true
             end
           else
-            # Fallback to index-based for elements without keys
-            # Even if old_child.nil?, diff will handle it (insertion)
+            # Unkeyed new child: positional fallback. Match it with the
+            # old child at the same index only when that old child is
+            # itself unkeyed (otherwise the keyed old child is matched
+            # separately via its key, and the unkeyed new is a fresh insert).
             old_child = old_children[new_index]
-            child_patches = diff(old_child, new_child)
-            unless child_patches.empty?
-              patches << [new_index, child_patches]
+            old_is_keyed = old_child.is_a?(VNode) && old_child.respond_to?(:key) && old_child.key
+            if old_child.nil? || old_is_keyed
+              ops << [:insert, new_index, new_child]
+              has_change = true
+            else
+              matched_old_indices[new_index] = true
+              child_patches = diff(old_child, new_child)
+              ops << [:keep, new_index, new_index, child_patches]
+              has_change = true unless child_patches.empty?
             end
           end
         end
 
-        # 4. Remove unmatched old elements
+        # 3. Collect every unmatched old child to remove, keyed or not. An old
+        #    child that no new child matched (by key, or positionally for
+        #    unkeyed ones) is gone from the new render and must be removed.
+        #    Skipping unkeyed olds here left stale nodes in the DOM, e.g. a
+        #    "Loading..." placeholder that never disappeared once the keyed
+        #    list it was replaced by arrived.
+        removes = [] #: Array[[Integer, child_t]]
         old_children.each_with_index do |old_child, old_index|
           next unless old_child.is_a?(VNode)
           next if matched_old_indices[old_index]
-
-          if old_child.respond_to?(:key) && old_child.key # Only remove keyed children
-            patches << [old_index, [[:remove, old_child]]]
-          end
+          removes << [old_index, old_child]
+          has_change = true
         end
 
-        # Sort patches: updates first, removes last (descending index)
-        patches.sort { |a, b|
-          a_is_remove = a[1].length == 1 && a[1][0][0] == :remove
-          b_is_remove = b[1].length == 1 && b[1][0][0] == :remove
-
-          if a_is_remove && b_is_remove
-            b[0] <=> a[0] # Sort remove patches by descending index
-          elsif a_is_remove
-            1 # Remove patches come after non-remove patches
-          elsif b_is_remove
-            -1 # Non-remove patches come before remove patches
-          else
-            a[0] <=> b[0] # Sort non-remove patches by ascending index
-          end
-        }
+        return [] unless has_change
+
+        [[:keyed_children, ops, removes]]
       end
 
       def self.diff_children_by_index(old_children, new_children)

data/mrblib/file_upload.rb

@@ -1,4 +1,11 @@
-require 'rng'
+# 'rng' is a PicoRuby gem available only in the wasm build. When the runtime
+# is loaded under CRuby for SSR it is absent; FileUpload is client-only and
+# its methods are never called on the server (see Funicular.server?).
+begin
+  require 'rng'
+rescue LoadError
+  # not available outside wasm environment
+end
 
 module Funicular
   module FileUpload
@@ -31,6 +38,7 @@ module Funicular
     JAVASCRIPT
 
     def self.mount
+      return if Funicular.server?
       script = JS.document.createElement("script")
       script[:textContent] = JS_HELPER_CODE
       JS.document.body.appendChild(script)

data/mrblib/form_builder.rb

@@ -6,8 +6,15 @@ module Funicular
       @component = component
       @model_key = model_key
       @options = options
-      @error_class = options[:error_class] || "text-red-600 text-sm mt-1"
-      @field_error_class = options[:field_error_class] || "border-red-500"
+      # Per-form options win, then the global Funicular.configure_forms config,
+      # then the built-in defaults. The defaults are semantic class names whose
+      # CSS the gem ships and injects via picoruby_include_tag, so error styling
+      # works without depending on the host app's CSS pipeline (e.g. Tailwind,
+      # which never scans the gem and so would not generate utility classes
+      # emitted from here).
+      config = Funicular.form_builder_config || {}
+      @error_class = options[:error_class] || config[:error_class] || "funicular-error"
+      @field_error_class = options[:field_error_class] || config[:field_error_class] || "funicular-field-error"
     end
 
     # Generic field builder for input elements
@@ -26,7 +33,10 @@ module Funicular
 
       # Check for errors
       error_message = @component.state.errors ? @component.state.errors[field_key.to_sym] : nil
-      has_error = !error_message.nil?
+      # errors may be a single message (legacy) or an array of messages
+      # (Funicular::Model::Errors#messages). Show the first.
+      error_message = error_message.first if error_message.is_a?(Array)
+      has_error = !(error_message.nil? || error_message == "")
 
       # Merge CSS classes (add error class if error exists)
       css_class = field_options[:class]
@@ -43,6 +53,7 @@ module Funicular
 
       # Build field attributes
       attrs = {
+        name: field_options[:name] || field_key,
         type: field_type,
         value: value,
         oninput: on_input
@@ -89,7 +100,10 @@ module Funicular
       end
 
       error_message = @component.state.errors ? @component.state.errors[field_key.to_sym] : nil
-      has_error = !error_message.nil?
+      # errors may be a single message (legacy) or an array of messages
+      # (Funicular::Model::Errors#messages). Show the first.
+      error_message = error_message.first if error_message.is_a?(Array)
+      has_error = !(error_message.nil? || error_message == "")
 
       css_class = options[:class]
       css_class = css_class.to_s if css_class
@@ -104,13 +118,15 @@ module Funicular
       end
 
       attrs = {
+        name: options[:name] || field_key,
+        value: value,
         oninput: on_input
       }.merge(options.reject { |k, _| k == :class })
 
       attrs[:class] = css_class unless css_class.empty?
 
       @component.div do
-        @component.textarea(attrs) { value }
+        @component.textarea(attrs)
         if has_error
           @component.div(class: @error_class) { error_message }
         end
@@ -129,6 +145,7 @@ module Funicular
       end
 
       attrs = {
+        name: options[:name] || field_key,
         type: "checkbox",
         checked: value,
         onchange: on_change
@@ -149,7 +166,10 @@ module Funicular
       end
 
       error_message = @component.state.errors ? @component.state.errors[field_key.to_sym] : nil
-      has_error = !error_message.nil?
+      # errors may be a single message (legacy) or an array of messages
+      # (Funicular::Model::Errors#messages). Show the first.
+      error_message = error_message.first if error_message.is_a?(Array)
+      has_error = !(error_message.nil? || error_message == "")
 
       css_class = options[:class]
       css_class = css_class.to_s if css_class
@@ -164,6 +184,7 @@ module Funicular
       end
 
       attrs = {
+        name: options[:name] || field_key,
         onchange: on_change
       }.merge(options.reject { |k, _| k == :class })
 
@@ -206,6 +227,7 @@ module Funicular
       on_change = custom_handler || default_handler
 
       attrs = {
+        name: options[:name] || field_key,
         type: "file",
         onchange: on_change
       }.merge(options)