funicular 0.0.1 → 0.2.0

data/mrblib/store_collection.rb

@@ -0,0 +1,171 @@
+module Funicular
+  class Store
+    # Collection store: an ordered Array per scope, with bounded size and a
+    # key proc that supports remove(id) / same_tail? semantics.
+    #
+    #   class MessageCache < Funicular::Store::Collection
+    #     database "funicular_message_cache"
+    #     scope    :channel_id
+    #     limit    100
+    #     key      ->(m) { m["id"] }
+    #     cleared_on :logout
+    #
+    #     subscribes_to "ChatChannel",
+    #                   params: ->(s) { { channel: "ChatChannel", channel_id: s.channel_id } } do |data, _scope|
+    #       case data["type"]
+    #       when "initial_messages" then replace(data["messages"] || [])
+    #       when "new_message"      then append(data["message"])
+    #       when "delete_message"   then remove(data["message_id"])
+    #       end
+    #     end
+    #   end
+    class Collection < Store
+      DEFAULT_KEY_PROC = ->(item) {
+        item.is_a?(Hash) ? item["id"] : nil
+      }
+
+      class << self
+        attr_reader :__limit, :__order, :__key_proc
+
+        def limit(n)
+          @__limit = n
+        end
+
+        # :append (default) keeps the most recent items at the tail and caps
+        # by truncating the head; :prepend caps by truncating the tail.
+        def order(direction)
+          @__order = direction.to_sym
+        end
+
+        def key(proc)
+          @__key_proc = proc
+        end
+
+        def scope_class
+          Funicular::Store::Collection::Scope
+        end
+      end
+
+      class Scope < Funicular::Store::Scope
+        def all
+          rec = read
+          return [] unless rec.is_a?(Hash)
+          if expired_record?(rec)
+            erase
+            return []
+          end
+          items = rec["items"]
+          items.is_a?(Array) ? items : []
+        end
+
+        def replace(arr)
+          new_arr = cap(arr.is_a?(Array) ? arr : [])
+          # Skip IndexedDB write if the cached snapshot already matches by
+          # tail. Always fire callback so subscribers know replace completed
+          # (e.g. to clear loading state).
+          unless same_tail?(new_arr)
+            write(new_arr)
+          end
+          fire_change(new_arr)
+          new_arr
+        end
+
+        def append(item)
+          new_arr = cap(append_to(all, item))
+          write(new_arr)
+          fire_change(new_arr)
+          new_arr
+        end
+
+        def remove(id)
+          cur = all
+          kp = key_proc
+          new_arr = cur.reject { |m| kp.call(m) == id }
+          return cur if new_arr.size == cur.size
+          write(new_arr)
+          fire_change(new_arr)
+          new_arr
+        end
+
+        def last
+          arr = all
+          arr.empty? ? nil : arr[arr.size - 1]
+        end
+
+        def last_id
+          l = last
+          return nil unless l
+          key_proc.call(l)
+        end
+
+        def size
+          all.size
+        end
+
+        def clear
+          erase
+          fire_change([])
+          nil
+        end
+
+        def expired?
+          rec = read
+          expired_record?(rec)
+        end
+
+        # True iff `other` matches the current cached snapshot by size and
+        # last-item key. Cheap staleness probe used by callers that already
+        # have a fresh server response and want to skip a redundant
+        # state-replace re-render.
+        def same_tail?(other)
+          return false unless other.is_a?(Array)
+          cur = all
+          return false if cur.size != other.size
+          return true if cur.empty? && other.empty?
+          kp = key_proc
+          kp.call(cur[cur.size - 1]) == kp.call(other[other.size - 1])
+        end
+
+        private
+
+        def key_proc
+          @store_class.__key_proc || Funicular::Store::Collection::DEFAULT_KEY_PROC
+        end
+
+        def cap(arr)
+          lim = @store_class.__limit
+          return arr unless lim.is_a?(Integer) && lim < arr.size
+          if @store_class.__order == :prepend
+            arr[0, lim] || arr
+          else
+            arr[arr.size - lim, lim] || arr
+          end
+        end
+
+        def append_to(arr, item)
+          if @store_class.__order == :prepend
+            [item] + arr
+          else
+            arr + [item]
+          end
+        end
+
+        def read
+          kvs[storage_key]
+        end
+
+        def write(items)
+          kvs[storage_key] = {
+            "items" => items,
+            "wrote_at" => now_seconds,
+            "expires_in" => @store_class.__expires_in
+          }
+        end
+
+        def erase
+          kvs.delete(storage_key)
+        end
+      end
+    end
+  end
+end

data/mrblib/store_singleton.rb

@@ -0,0 +1,79 @@
+module Funicular
+  class Store
+    # Singleton store: one value per scope. Suitable for things like a
+    # per-channel draft text or per-user preferences blob.
+    #
+    #   class DraftStore < Funicular::Store::Singleton
+    #     database  "funicular_drafts"
+    #     scope     :channel_id
+    #     cleared_on :logout
+    #   end
+    #
+    #   draft = DraftStore.where(channel_id: 1)
+    #   draft.value = "hello"
+    #   draft.value           # => "hello"
+    #   draft.delete
+    class Singleton < Store
+      def self.scope_class
+        Funicular::Store::Singleton::Scope
+      end
+
+      class Scope < Funicular::Store::Scope
+        def value
+          rec = read
+          return nil unless rec.is_a?(Hash)
+          if expired_record?(rec)
+            erase
+            return nil
+          end
+          rec["v"]
+        end
+
+        # Setting "" on a String-typed value deletes the entry, matching
+        # the semantics of the original DraftStore.
+        def value=(v)
+          if v.is_a?(String) && v.empty?
+            delete
+            return v
+          end
+          write(v)
+          fire_change(v)
+          v
+        end
+
+        def delete
+          erase
+          fire_change(nil)
+          nil
+        end
+
+        def present?
+          !value.nil?
+        end
+
+        def expired?
+          rec = read
+          expired_record?(rec)
+        end
+
+        private
+
+        def read
+          kvs[storage_key]
+        end
+
+        def write(v)
+          kvs[storage_key] = {
+            "v" => v,
+            "wrote_at" => now_seconds,
+            "expires_in" => @store_class.__expires_in
+          }
+        end
+
+        def erase
+          kvs.delete(storage_key)
+        end
+      end
+    end
+  end
+end

data/mrblib/styles.rb

@@ -0,0 +1,83 @@
+module Funicular
+  class StyleValue
+    attr_reader :value
+
+    def initialize(value)
+      @value = value.to_s
+    end
+
+    def |(other)
+      case other
+      when StyleValue
+        StyleValue.new("#{@value} #{other.value}".strip)
+      when String
+        StyleValue.new("#{@value} #{other}".strip)
+      when nil
+        self
+      else
+        other = other #: untyped
+        StyleValue.new("#{@value} #{other.to_s}".strip)
+      end
+    end
+
+    def to_s
+      @value
+    end
+  end
+
+  class StyleAccessor
+    def initialize(definitions)
+      @definitions = definitions
+    end
+
+    def method_missing(name, *args)
+      style = @definitions[name]
+      return StyleValue.new("") unless style
+
+      if args.empty?
+        # No arguments: return base or value
+        StyleValue.new(style[:base] || style[:value] || "")
+      elsif args[0] == true || args[0] == false
+        # Boolean argument: base + active (if true)
+        # JS::Object#== now supports direct comparison with Ruby true/false
+        base = style[:base] || ""
+        active_class = (args[0] == true) ? (style[:active] || "") : ""
+        StyleValue.new("#{base} #{active_class}".strip)
+      elsif args[0].is_a?(Symbol)
+        # Symbol argument: base + variants[symbol]
+        base = style[:base] || ""
+        variant_class = style[:variants] ? (style[:variants][args[0]] || "") : ""
+        StyleValue.new("#{base} #{variant_class}".strip)
+      else
+        # Other types: just return base
+        StyleValue.new(style[:base] || style[:value] || "")
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @definitions.key?(name) || super
+    end
+  end
+
+  class StyleBuilder
+    def initialize
+      @definitions = {}
+    end
+
+    def method_missing(name, *args)
+      if args.size == 1 && args[0].is_a?(String)
+        # Simple style: name "class-string"
+        @definitions[name] = { value: args[0] }
+      elsif args.size == 1 && args[0].is_a?(Hash)
+        # Complex style with base/active/variants
+        @definitions[name] = args[0]
+      else
+        raise ArgumentError, "Invalid style definition for #{name}"
+      end
+    end
+
+    def to_definitions
+      @definitions
+    end
+  end
+end

data/mrblib/vdom.rb

@@ -0,0 +1,273 @@
+module Funicular
+  module VDOM
+    BOOLEAN_ATTRIBUTES = %w[
+      disabled checked selected readonly required autofocus multiple
+    ]
+
+    URL_ATTRIBUTES = %w[href src action formaction data poster xlink:href]
+
+    class VNode
+      attr_reader :type, :key
+
+      def initialize(type)
+        @type = type
+      end
+    end
+
+    class Element < VNode
+      attr_reader :tag, :props, :children
+
+      def initialize(tag, props = {}, children = [])
+        super(:element)
+        @tag = tag.to_s
+        @key = props.delete(:key)
+        @props = props || {}
+        @children = normalize_children(children || [])
+      end
+
+      private
+
+      def normalize_children(children)
+        result = [] #: Array[child_t]
+        children.each do |child|
+          case child
+          when VNode
+            result << child
+          when String
+            result << child
+          when Array
+            # Flatten arrays (typically from .each or .map return values)
+            # Recursively normalize nested arrays
+            # @type var child: Array[Funicular::VDOM::child_t]
+            result.concat(normalize_children(child))
+          when nil
+            # Skip nil values
+          else
+            # Convert other types to strings
+            result << child.to_s
+          end
+        end
+        result
+      end
+
+      def ==(other)
+        return false unless other.is_a?(Element)
+        @tag == other.tag && @props == other.props && @children == other.children
+      end
+    end
+
+    class Text < VNode
+      attr_reader :content
+
+      def initialize(content)
+        super(:text)
+        @content = content.to_s
+      end
+
+      def ==(other)
+        return false unless other.is_a?(Text)
+        @content == other.content
+      end
+    end
+
+    class Component < VNode
+      attr_reader :component_class, :props
+      attr_accessor :instance
+
+      def initialize(component_class, props = {})
+        super(:component)
+        @component_class = component_class
+        @key = props.delete(:key)
+        @props = props
+        @instance = nil
+      end
+
+      def ==(other)
+        return false unless other.is_a?(Component)
+        @component_class == other.component_class && @props == other.props
+      end
+    end
+
+    class Renderer
+      def initialize(doc = nil)
+        @doc = doc || JS.document
+        @error_boundary_stack = []
+      end
+
+      def render(vnode, parent = nil)
+        case vnode&.type
+        when :element
+          # @type var vnode: Funicular::VDOM::Element
+          render_element(vnode, parent)
+        when :text
+          # @type var vnode: Funicular::VDOM::Text
+          render_text(vnode, parent)
+        when :component
+          # @type var vnode: Funicular::VDOM::Component
+          render_component(vnode, parent)
+        else
+          raise "Unknown vnode type: #{vnode&.type}"
+        end
+      end
+
+      private
+
+      # Find the nearest error boundary instance on the stack
+      def current_error_boundary
+        @error_boundary_stack.last
+      end
+
+      def render_element(element, parent)
+        dom_node = @doc.createElement(element.tag)
+
+        element.props.each do |key, value|
+          key_str = key.to_s
+          if key_str.start_with?('on')
+            # Event handlers are handled by Funicular::Component and should not be set as attributes.
+            # warn "Funicular: Attempted to set event handler '#{key_str}' as an attribute. This will be ignored."
+          elsif URL_ATTRIBUTES.include?(key_str) && value.to_s.strip.downcase.start_with?('javascript:')
+            # Prevent XSS attacks by blocking javascript: URIs in URL attributes
+            puts "[WARN] Funicular: Blocked potentially malicious value for attribute '#{key_str}'."
+          elsif BOOLEAN_ATTRIBUTES.include?(key_str)
+            # Handle boolean attributes
+            if value.nil? || value.to_s == "false"
+              # Do not set attribute (leave it absent)
+            else
+              dom_node.setAttribute(key_str, key_str)
+            end
+          else
+            # Attribute
+            dom_node.setAttribute(key_str, value.to_s)
+          end
+        end
+
+        element.children.each do |child|
+          if child.is_a?(VNode)
+            child_dom = render(child)
+            dom_node.appendChild(child_dom)
+          elsif child.is_a?(String)
+            text_node = @doc.createTextNode(child)
+            dom_node.appendChild(text_node)
+          elsif child.is_a?(Array)
+            child.each do |c|
+              if c.is_a?(VNode)
+                child_dom = render(c)
+                dom_node.appendChild(child_dom)
+              elsif c.is_a?(String)
+                text_node = @doc.createTextNode(c)
+                dom_node.appendChild(text_node)
+              end
+            end
+          end
+        end
+
+        parent.appendChild(dom_node) if parent
+
+        dom_node
+      end
+
+      def render_text(text, parent)
+        dom_node = @doc.createTextNode(text.content)
+        parent.appendChild(dom_node) if parent
+        dom_node
+      end
+
+      def render_component(component_vnode, parent)
+        instance = component_vnode.component_class.new(component_vnode.props)
+        component_vnode.instance = instance
+
+        is_error_boundary = instance.is_a?(Funicular::ErrorBoundary)
+
+        # Push error boundary to stack if this component is one
+        @error_boundary_stack.push(instance) if is_error_boundary
+
+        begin
+          component_vdom = instance.build_vdom
+          dom_node = render(component_vdom, parent)
+
+          # Check if this ErrorBoundary caught an error during child rendering
+          # If so, its @vdom was already set to fallback in the rescue block
+          error_was_caught = is_error_boundary && instance.error_caught_during_render
+
+          if error_was_caught
+            # ErrorBoundary caught an error - use the fallback vdom/dom that were set in rescue
+            # Note: The div.error-boundary-content created during initial render
+            # will be orphaned, but that's acceptable as it's not attached to the DOM
+            fallback_vdom = instance.vdom
+            fallback_dom = instance.dom_element
+
+            # Bind events on the fallback DOM
+            instance.bind_events(fallback_dom, fallback_vdom)
+            instance.collect_refs(fallback_dom, fallback_vdom)
+
+            # Return the fallback DOM
+            fallback_dom
+          else
+            # Normal case - store VDOM and DOM element
+            instance.vdom = component_vdom
+            instance.dom_element = dom_node
+            instance.bind_events(dom_node, component_vdom)
+            instance.collect_refs(dom_node, component_vdom)
+            dom_node
+          end
+        rescue => e
+          # Pop error boundary from stack before handling
+          @error_boundary_stack.pop if is_error_boundary
+
+          # Try to find an error boundary to handle this error
+          boundary = current_error_boundary
+          if boundary && !is_error_boundary
+            error_info = {
+              component_class: component_vnode.component_class.to_s,
+              props: component_vnode.props
+            }
+
+            # Let the error boundary handle the error
+            boundary.catch_error(e, error_info)
+
+            # Re-render the error boundary with fallback UI
+            boundary_vdom = boundary.build_vdom
+            fallback_dom = render(boundary_vdom, nil)
+
+            # Update boundary's internal state
+            boundary.vdom = boundary_vdom
+            boundary.dom_element = fallback_dom
+            boundary.mounted = true
+            boundary.bind_events(fallback_dom, boundary_vdom)
+
+            fallback_dom
+          else
+            # No error boundary to catch this error, let it propagate
+            raise e
+          end
+        ensure
+          # Pop error boundary from stack after successful render
+          @error_boundary_stack.pop if is_error_boundary && @error_boundary_stack.last == instance
+        end
+      end
+    end
+
+    def self.create_element(tag, props = {}, *children)
+      Element.new(tag, props, children.flatten)
+    end
+
+    def self.create_text(content)
+      Text.new(content)
+    end
+
+    def self.render(vnode, container)
+      renderer = Renderer.new
+      container.innerHTML = ''
+      renderer.render(vnode, container)
+    end
+
+    def self.diff(old_vnode, new_vnode)
+      Differ.diff(old_vnode, new_vnode)
+    end
+
+    def self.patch(element, patches)
+      patcher = Patcher.new
+      patcher.apply(element, patches)
+    end
+  end
+end

data/sig/cable.rbs

@@ -0,0 +1,66 @@
+module Funicular
+  module Cable
+    STORAGE_KEY: String
+
+    def self.create_consumer: (String url) -> Consumer
+
+    class Consumer
+      attr_reader url: String
+      attr_reader subscriptions: Subscriptions
+      @reconnect_attempts: Integer
+
+      def initialize: (String url) -> void
+      def connect: () -> void
+      def send_command: (Hash[Symbol, untyped] command) -> void
+      def disconnect: () -> void
+      def cleanup: () -> void
+      def cleanup_event_listeners: () -> void
+
+      private def handle_message: (String data) -> void
+      private def flush_pending_commands: () -> void
+      private def schedule_reconnect: () -> void
+      private def calculate_backoff_delay: () -> Integer
+      private def setup_visibility_handler: () -> void
+      private def schedule_suspend: () -> void
+      private def cancel_suspend: () -> void
+      private def suspend_connection: () -> void
+      private def ensure_connected: () -> void
+      private def setup_beforeunload_handler: () -> void
+      private def save_pending_to_storage: () -> void
+      private def load_pending_from_storage: () -> Array[Hash[Symbol, untyped]]
+      private def clear_pending_storage: () -> void
+    end
+
+    class Subscriptions
+      @subscriptions: Hash[String, Subscription]
+
+      def initialize: (Consumer consumer) -> void
+      def create: (Hash[Symbol, untyped] params) ?{ (untyped message) -> void } -> Subscription
+      def find: (String identifier) -> Subscription?
+      def remove: (Subscription subscription) -> void
+      def notify_subscription_confirmed: (String identifier) -> void
+      def notify_subscription_rejected: (String identifier) -> void
+      def notify_message: (String identifier, untyped message) -> void
+      def resubscribe_all: () -> void
+    end
+
+    class Subscription
+      attr_reader consumer: Consumer
+      attr_reader identifier: String
+      attr_reader params: Hash[Symbol, untyped]
+
+      def initialize: (Consumer consumer, String identifier, Hash[Symbol, untyped] params) ?{ (untyped message) -> void } -> void
+      def subscribe: () -> void
+      def unsubscribe: () -> void
+      def perform: (String action, ?Hash[Symbol, untyped] data) -> void
+      def on_connected: () { () -> void } -> void
+      def on_disconnected: () { () -> void } -> void
+      def on_rejected: () { () -> void } -> void
+      def notify_connected: () -> void
+      def notify_rejected: () -> void
+      def notify_received: (untyped message) -> void
+
+      private def generate_idempotency_key: () -> String
+    end
+  end
+end