funicular 0.0.1 → 0.2.0

data/mrblib/debug.rb

@@ -0,0 +1,208 @@
+module Funicular
+  module Debug
+    class << self
+      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
+
+      def component_registry
+        @component_registry ||= {}
+      end
+
+      def error_registry
+        @error_registry ||= []
+      end
+
+      def register_component(component)
+        return nil unless enabled?
+        @component_counter ||= 0
+        id = (@component_counter += 1)
+        component_registry[id] = component
+        id
+      end
+
+      # Report an error caught by an ErrorBoundary
+      def report_error(boundary, error, error_info = nil)
+        return unless enabled?
+
+        error_entry = {
+          id: (error_registry.length + 1),
+          timestamp: Time.now.to_s,
+          boundary_id: boundary.instance_variable_get(:@__debug_id__),
+          boundary_class: boundary.class.to_s,
+          error_class: error.class.to_s,
+          error_message: error.message,
+          component_class: error_info&.dig(:component_class),
+          backtrace: error.backtrace&.first(10)
+        }
+
+        error_registry << error_entry
+
+        # Log to console
+        puts "[ErrorBoundary] Caught error in #{error_info&.dig(:component_class) || 'unknown'}: #{error.message}"
+
+        # Keep only last 50 errors
+        @error_registry = error_registry.last(50) if error_registry.length > 50
+
+        error_entry
+      end
+
+      # Clear all recorded errors
+      def clear_errors
+        @error_registry = []
+      end
+
+      # Get all recorded errors as JSON
+      def error_list
+        return "[]" unless enabled?
+        begin
+          JSON.generate(error_registry)
+        rescue => e
+          JSON.generate([{ "error" => e.message }])
+        end
+      end
+
+      # Get the most recent error
+      def last_error
+        return nil unless enabled?
+        error_registry.last
+      end
+
+      def unregister_component(id)
+        return unless enabled?
+        component_registry.delete(id)
+      end
+
+      def get_component(id)
+        return nil unless enabled?
+        component_registry[id]
+      end
+
+      def all_components
+        return [] unless enabled?
+        component_registry.values
+      end
+
+      def component_tree
+        return "[]" unless enabled?
+
+        begin
+          components = component_registry.map do |id, component|
+            begin
+              mounted = component.instance_variable_get(:@mounted)
+              state_keys = get_state_keys(component)
+              class_name = component.class.to_s
+              child_ids = get_child_ids(component)
+              is_error_boundary = component.is_a?(Funicular::ErrorBoundary)
+              has_error = is_error_boundary && component.instance_variable_get(:@state)&.dig(:has_error)
+              entry = {
+                "id" => id,
+                "class" => class_name,
+                "state_keys" => state_keys,
+                "mounted" => mounted,
+                "children" => child_ids
+              } #: Hash[String, untyped]
+              if is_error_boundary
+                entry["is_error_boundary"] = true
+                entry["has_error"] = has_error
+              end
+              entry
+            rescue => e
+              { "id" => id, "error" => e.message }
+            end
+          end
+          JSON.generate(components)
+        rescue => e
+          JSON.generate({ "error" => e.message })
+        end
+      end
+
+      # Get error count
+      def error_count
+        return 0 unless enabled?
+        error_registry.length
+      end
+
+      def get_component_state(id)
+        return "{}" unless enabled?
+        component = get_component(id)
+        return "{}" unless component
+
+        state = component.instance_variable_get(:@state) || {}
+        result = {} #: Hash[String, String]
+        state.each do |key, value|
+          begin
+            result[key.to_s] = value.inspect
+          rescue
+            result[key.to_s] = "<error inspecting value>"
+          end
+        end
+        JSON.generate(result)
+      end
+
+      def get_component_instance_variables(id)
+        return "{}" unless enabled?
+        component = get_component(id)
+        return "{}" unless component
+
+        result = {} #: Hash[String, String]
+        component.instance_variables.each do |var|
+          next if var == :@state
+          next if var.to_s.start_with?('@__debug')
+          if var == :@vdom || var == :@child_components
+            result[var.to_s] = "<omitted>"
+            next
+          end
+          begin
+            result[var.to_s] = component.instance_variable_get(var).inspect
+          rescue
+            result[var.to_s] = "<error inspecting value>"
+          end
+        end
+        JSON.generate(result)
+      end
+
+      def expose_to_global
+        return unless enabled?
+        # Export to global variable for DevTools access
+        $__funicular_debug__ = self
+      end
+
+      private
+
+      def get_state_keys(component)
+        state = component.instance_variable_get(:@state)
+        return [] unless state.is_a?(Hash)
+        state.keys.map(&:to_s)
+      end
+
+      def get_child_ids(component)
+        # Get only direct children by scanning component's vdom
+        vdom = component.instance_variable_get(:@vdom)
+        return [] unless vdom
+
+        direct_children = [] #: Array[Funicular::Component]
+        collect_direct_children(vdom, direct_children)
+        direct_children.map { |child| child.instance_variable_get(:@__debug_id__) }.compact
+      end
+
+      def collect_direct_children(vnode, children)
+        if vnode.is_a?(VDOM::Component)
+          # Found a direct child component, don't recurse further
+          children << vnode.instance if vnode.instance
+        elsif vnode.is_a?(VDOM::Element)
+          # Keep looking through elements
+          vnode.children&.each do |child|
+            # @type var child: VDOM::VNode
+            collect_direct_children(child, children)
+          end
+        end
+      end
+    end
+  end
+end

data/mrblib/differ.rb

@@ -0,0 +1,254 @@
+module Funicular
+  module VDOM
+    class Differ
+      def self.diff(old_node, new_node)
+        return [[:replace, new_node, nil]] if old_node.nil? # old_node is nil for new nodes (insertion)
+        return [[:remove, old_node]] if new_node.nil? # new_node is nil for removed nodes
+
+        if old_node.is_a?(VNode) && new_node.is_a?(VNode)
+          if old_node.type != new_node.type
+            return [[:replace, new_node, old_node]]
+          end
+
+          case old_node.type
+          when :text
+            # @type var old_node: Funicular::VDOM::Text
+            # @type var new_node: Funicular::VDOM::Text
+            diff_text(old_node, new_node)
+          when :element
+            # @type var old_node: Funicular::VDOM::Element
+            # @type var new_node: Funicular::VDOM::Element
+            diff_element(old_node, new_node)
+          when :component
+            # @type var old_node: Funicular::VDOM::Component
+            # @type var new_node: Funicular::VDOM::Component
+            diff_component(old_node, new_node)
+          else
+            [[:replace, new_node, old_node]]
+          end
+        else
+          if old_node == new_node
+            []
+          else
+            [[:replace, new_node, old_node]]
+          end
+        end
+      end
+
+      private
+
+      def self.diff_text(old_node, new_node)
+        if old_node.content != new_node.content
+          [[:replace, new_node, old_node]]
+        else
+          []
+        end
+      end
+
+      def self.diff_element(old_node, new_node)
+        patches = [] #: Array[patch_t]
+
+        if old_node.tag != new_node.tag
+          return [[:replace, new_node, old_node]]
+        end
+
+        props_patch = diff_props(old_node.props, new_node.props)
+        patches << [:props, props_patch] unless props_patch.empty?
+
+        child_patches = diff_children(old_node.children, new_node.children)
+        patches += child_patches unless child_patches.empty?
+
+        patches
+      end
+
+      def self.diff_props(old_props, new_props)
+        patches = {} #: Hash[Symbol, untyped]
+        new_props.each do |key, value|
+          # Skip Proc/Lambda values as they are recreated on each render
+          # and should be handled by event binding, not props patching
+          next if value.is_a?(Proc)
+          patches[key] = value if old_props[key] != value
+        end
+        old_props.keys.each do |key|
+          # Skip Proc/Lambda values
+          next if old_props[key].is_a?(Proc)
+          patches[key] = nil unless new_props.key?(key)
+        end
+        patches
+      end
+
+      def self.diff_children(old_children, new_children)
+        # Check if any child has a key
+        has_keys = new_children.any? { |child|
+          child.is_a?(VNode) && child.respond_to?(:key) && child.key
+        }
+
+        if has_keys
+          diff_children_with_keys(old_children, new_children)
+        else
+          diff_children_by_index(old_children, new_children)
+        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)
+        # 1. Build key map from old children
+        old_key_map = {} #: Hash[untyped, [Integer, child_t]]
+        old_children.each_with_index do |child, index|
+          if child.is_a?(VNode) && child.respond_to?(:key) && child.key
+            old_key_map[child.key] = [index, child]
+          end
+        end
+
+        matched_old_indices = {} #: Hash[Integer, bool]
+        ops = [] #: Array[Array[untyped]]
+        has_change = false
+
+        # 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
+              child_patches = diff(old_child, new_child)
+              ops << [:keep, old_index, new_index, child_patches]
+              has_change = true unless child_patches.empty?
+            else
+              ops << [:insert, new_index, new_child]
+              has_change = true
+            end
+          else
+            # 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]
+            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
+
+        # 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]
+          removes << [old_index, old_child]
+          has_change = true
+        end
+
+        return [] unless has_change
+
+        [[:keyed_children, ops, removes]]
+      end
+
+      def self.diff_children_by_index(old_children, new_children)
+        patches = [] #: Array[patch_t]
+        # Collect remove patches separately to apply at the end
+        remove_patches = [] #: Array[patch_t]
+        max_length = [old_children.length, new_children.length].max
+        max_length&.times do |i|
+          old_child = old_children[i]
+          new_child = new_children[i]
+          child_patches = diff(old_child, new_child)
+          unless child_patches.empty?
+            # Check if this is a simple remove patch
+            if child_patches.length == 1 && child_patches[0][0] == :remove
+              remove_patches << [i, child_patches]
+            else
+              patches << [i, child_patches]
+            end
+          end
+        end
+        # Add remove patches at the end, sorted by index in descending order to avoid index shifts
+        patches + remove_patches.sort { |a, b| b[0] <=> a[0] }
+      end
+
+      def self.diff_component(old_node, new_node)
+        if old_node.component_class != new_node.component_class
+          return [[:replace, new_node, old_node]]
+        end
+
+        # If the component is marked for preservation,
+        # update its internal VDOM instead of replacing the whole component.
+        if new_node.props[:preserve]
+          instance = old_node.instance
+          return [[:replace, new_node, old_node]] unless instance # Fallback if instance is missing
+
+          new_node.instance = instance # Preserve the instance
+
+          # Check if data props (excluding Proc/Lambda) have changed
+          # Proc/Lambda props are always considered different between renders,
+          # but we want to ignore them for preservation purposes
+          data_props_changed = props_changed_excluding_procs?(old_node.props, new_node.props)
+
+          # If only Proc props changed, update props but skip VDOM rebuild
+          unless data_props_changed
+            instance.props = new_node.props
+            return []
+          end
+
+          old_internal_vdom = instance.vdom
+          instance.props = new_node.props
+          new_internal_vdom = instance.build_vdom
+          internal_patches = diff(old_internal_vdom, new_internal_vdom)
+
+          # Return a special patch that instructs the patcher to re-bind events
+          # Pass new_internal_vdom so patcher can update @vdom after applying patches
+          return [[:update_and_rebind, instance, internal_patches, new_internal_vdom]]
+        end
+
+        # Original logic: If props changed, replace the entire component
+        if old_node.props != new_node.props
+          return [[:replace, new_node, old_node]]
+        end
+
+        # Copy instance reference so parent's @vdom keeps valid instance refs
+        # This is needed for debug.rb's collect_direct_children to work correctly
+        new_node.instance = old_node.instance
+        []
+      end
+
+      # Helper method to check if props changed, excluding Proc/Lambda values
+      def self.props_changed_excluding_procs?(old_props, new_props)
+        # Get keys excluding Proc/Lambda values
+        old_data_keys = old_props.keys.select { |k| !old_props[k].is_a?(Proc) }
+        new_data_keys = new_props.keys.select { |k| !new_props[k].is_a?(Proc) }
+
+        # Check if keys changed
+        return true if old_data_keys.sort != new_data_keys.sort
+
+        # Check if values changed for data keys
+        old_data_keys.any? { |k| old_props[k] != new_props[k] }
+      end
+    end
+  end
+end

data/mrblib/environment_inquirer.rb

@@ -0,0 +1,34 @@
+module Funicular
+  class EnvironmentInquirer
+    def initialize(env)
+      @environment = env.to_s
+    end
+
+    def to_s
+      @environment
+    end
+
+    def inspect
+      @environment.inspect
+    end
+
+    def ==(other)
+      @environment == other.to_s
+    end
+
+    def method_missing(method_name, *args, &block) # steep:ignore MethodArityMismatch
+      if method_name.to_s.end_with?("?")
+        env_name = method_name.to_s.chomp("?")
+        return @environment == env_name
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.to_s.end_with?("?") || super
+    end
+  end
+
+end
+

data/mrblib/error_boundary.rb

@@ -0,0 +1,125 @@
+module Funicular
+  # ErrorBoundary component catches errors from child components and displays
+  # a fallback UI instead of crashing the entire application.
+  #
+  # Usage:
+  #   component(ErrorBoundary) do
+  #     component(RiskyComponent)
+  #   end
+  #
+  # With custom fallback:
+  #   component(ErrorBoundary, fallback: ->(error) { div { "Error: #{error.message}" } }) do
+  #     component(RiskyComponent)
+  #   end
+  #
+  # Props:
+  #   - fallback: Proc or Method that receives the error and returns VDOM
+  #   - on_error: Optional callback when error is caught (for logging, reporting)
+  #
+  class ErrorBoundary < Component
+    attr_accessor :error_caught_during_render
+
+    def initialize_state
+      { has_error: false, error: nil, error_info: nil }
+    end
+
+    # Called when a child component raises an error during rendering
+    # Returns true to indicate the error was handled and should not propagate
+    def catch_error(error, error_info = nil)
+      # Update state to show fallback UI
+      @state[:has_error] = true
+      @state[:error] = error
+      @state[:error_info] = error_info
+      @state_accessor = nil
+
+      # Mark that we caught an error (used to prevent @vdom overwrite)
+      @error_caught_during_render = true
+
+      # Call on_error callback if provided
+      if props[:on_error]
+        begin
+          props[:on_error].call(error, error_info)
+        rescue => callback_error
+          puts "[ErrorBoundary] on_error callback failed: #{callback_error.message}"
+        end
+      end
+
+      # Report to debug module
+      Funicular::Debug.report_error(self, error, error_info) if Funicular::Debug.enabled?
+
+      true # Indicate error was handled
+    end
+
+    # Reset the error boundary to try rendering children again
+    def reset
+      begin
+        patch(has_error: false, error: nil, error_info: nil)
+      rescue => e
+        # Re-catch the error and show fallback again
+        catch_error(e, { component_class: "child component" })
+      end
+    end
+
+    def render
+      if state[:has_error]
+        render_fallback
+      else
+        render_children
+      end
+    end
+
+    private
+
+    def render_fallback
+      if props[:fallback]
+        result = props[:fallback].call(state[:error])
+        if result.is_a?(VDOM::VNode)
+          result
+        else
+          div { result.to_s }
+        end
+      else
+        default_fallback
+      end
+    end
+
+    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]
+          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]
+          div(style: 'margin-top: 10px; font-size: 11px; color: #666;') do
+            "Component: #{state[:error_info][:component_class]}"
+          end
+        end
+      end
+    end
+
+    def render_children
+      # Children are passed via children_block prop from the component() DSL
+      # Errors are caught by VDOM::Renderer.render_component
+      if props[:children_block]
+        div(class: 'error-boundary-content') do
+          props[:children_block].call
+        end
+      elsif props[:children]
+        props[:children]
+      else
+        div { "" }
+      end
+    end
+  end
+
+  # Make ErrorBoundary available at top level
+  def self.const_missing(name)
+    if name == :ErrorBoundary
+      Funicular::ErrorBoundary
+    else
+      super
+    end
+  end
+end