funicular 0.1.0 → 0.2.1

data/mrblib/patcher.rb

@@ -20,7 +20,9 @@ module Funicular
               result = new_element
             end
           when :props
-            update_props(element, patch[1])
+            # Props patches only make sense for Element nodes (text nodes have
+            # no attributes); narrow before delegating.
+            update_props(element, patch[1]) if element.is_a?(JS::Element)
           when :update_and_rebind
             instance, internal_patches, new_vdom = patch[1], patch[2], patch[3]
             old_dom_element = instance.dom_element
@@ -29,7 +31,7 @@ module Funicular
             new_dom_element = Patcher.new(@doc).apply(old_dom_element, internal_patches)
 
             # Update the instance's reference to its root DOM element if it changed
-            if new_dom_element != old_dom_element
+            if new_dom_element != old_dom_element && new_dom_element.is_a?(JS::Element)
               instance.dom_element = new_dom_element
             end
 
@@ -37,11 +39,13 @@ module Funicular
             instance.vdom = new_vdom
 
             # Re-collect refs using the new DOM element
-            instance.collect_refs(new_dom_element, new_vdom)
+            if new_dom_element.is_a?(JS::Element)
+              instance.collect_refs(new_dom_element, new_vdom)
 
-            # Re-bind events using the new DOM element
-            instance.cleanup_events
-            instance.bind_events(new_dom_element, new_vdom)
+              # Re-bind events using the new DOM element
+              instance.cleanup_events
+              instance.bind_events(new_dom_element, new_vdom)
+            end
 
             # Call component_updated on the child instance
             instance.component_updated if instance.respond_to?(:component_updated)
@@ -54,6 +58,64 @@ module Funicular
             old_vnode = patch[1]
             unmount_component(old_vnode)
             element.parentElement&.removeChild(element)
+          when :keyed_children
+            # Composite patch produced by Differ.diff_children_with_keys.
+            # Applied in three phases against `element`:
+            #   1. snapshot DOM children, then remove unmatched keyed old
+            #      children (descending old_index so the snapshot indices
+            #      remain valid as removes happen).
+            #   2. apply content updates to kept children in place. The
+            #      lookup is by snapshot[old_index], so updates are stable
+            #      regardless of subsequent insertions.
+            #   3. insert new children at their new_index using
+            #      insertBefore on the live DOM. Processed in ascending
+            #      new_index order so each insertion fixes its own
+            #      position before later inserts run.
+            ops = patch[1]
+            removes = patch[2]
+
+            child_nodes = element[:childNodes]
+            snapshot = child_nodes.is_a?(JS::Object) ? child_nodes.to_a : [] #: Array[untyped]
+
+            # Phase 1: removes (descending old_index)
+            sorted_removes = removes.sort { |a, b| b[0] <=> a[0] }
+            sorted_removes.each do |entry|
+              old_index = entry[0]
+              old_vnode = entry[1]
+              target = snapshot[old_index]
+              next if target.nil?
+              unmount_component(old_vnode)
+              parent_el = target.parentElement
+              parent_el.removeChild(target) if parent_el
+            end
+
+            # Phase 2: updates against the snapshot (no movement)
+            ops.each do |op|
+              next unless op[0] == :keep
+              old_index = op[1]
+              child_patches = op[3]
+              next if child_patches.empty?
+              target = snapshot[old_index]
+              next if target.nil?
+              apply(target, child_patches)
+            end
+
+            # Phase 3: inserts in ascending new_index order
+            ops.each do |op|
+              next unless op[0] == :insert
+              new_index = op[1]
+              new_vnode = op[2]
+              new_node = create_element(new_vnode)
+              next if new_node.nil?
+              live_nodes = element[:childNodes]
+              live_arr = live_nodes.is_a?(JS::Object) ? live_nodes.to_a : [] #: Array[untyped]
+              ref = live_arr[new_index]
+              if ref.nil?
+                element.appendChild(new_node) if element.is_a?(JS::Element)
+              else
+                element.insertBefore(new_node, ref) if element.is_a?(JS::Element)
+              end
+            end
           when Integer
             child_index = patch[0]
             child_patches = patch[1]
@@ -67,7 +129,7 @@ module Funicular
                 case child_patch[0]
                 when :replace
                   new_child_element = create_element(child_patch[1])
-                  element.appendChild(new_child_element)
+                  element.appendChild(new_child_element) if element.is_a?(JS::Element)
                 when :remove
                   # Nothing to remove if child doesn't exist
                 when Integer
@@ -75,7 +137,9 @@ module Funicular
                   # But if it does, recursively process it
                 end
               end
-            else
+            elsif child_element.is_a?(JS::Object)
+              # Recurse into the child node. apply handles both Element and
+              # text Node cases (the latter only meaningfully via :replace).
               apply(child_element, child_patches)
             end
           end
@@ -91,6 +155,8 @@ module Funicular
       end
 
       def update_props(element, props_patch)
+        return unless element.is_a?(JS::Element)
+
         props_patch.each do |key, value|
           key_str = key.to_s
 
@@ -121,8 +187,10 @@ module Funicular
           if BOOLEAN_ATTRIBUTES.include?(key_str)
             if value.nil? || value.to_s == "false"
               element.removeAttribute(key_str)
+              element[key_str] = false
             else
               element.setAttribute(key_str, key_str)
+              element[key_str] = true
             end
           elsif value.nil?
             element.removeAttribute(key_str)
@@ -166,8 +234,10 @@ module Funicular
               element[:value] = value.to_s
             elsif BOOLEAN_ATTRIBUTES.include?(key_str)
               if value.nil? || value.to_s == "false"
+                element[key_str] = false
               else
                 element.setAttribute(key_str, key_str)
+                element[key_str] = true
               end
             else
               element.setAttribute(key_str, value.to_s)

data/mrblib/router.rb

@@ -44,8 +44,22 @@ module Funicular
       @default_route = path
     end
 
+    # Resolve a path to [component_class, params] without any DOM/JS work.
+    # Public entry point used by server-side rendering.
+    def match(path)
+      find_route(path)
+    end
+
     # Start listening to popstate
-    def start
+    #
+    # When hydrate is true and the container already holds server-rendered
+    # markup, the initial route hydrates that DOM instead of mounting fresh.
+    def start(hydrate: false)
+      # No browser history on the server.
+      return if Funicular.server?
+
+      @hydrate_initial = hydrate
+
       # Clean up existing listener if any (prevents duplicate registration)
       if @popstate_callback_id
         JS::Object.removeEventListener(@popstate_callback_id)
@@ -57,8 +71,10 @@ module Funicular
         handle_route_change
       end
 
-      # Handle initial route
-      if current_location_path == '/' && @default_route
+      # Handle initial route. Skip the default-route redirect when hydrating
+      # server content: the server already rendered for the current path.
+      hydrating_now = @hydrate_initial && Funicular.first_element_child(@container)
+      if !hydrating_now && current_location_path == '/' && @default_route
         # Use replaceState to not add a new entry to the history
         JS.global.history.replaceState(JS::Bridge.to_js({}), '', @default_route)
       end
@@ -95,6 +111,11 @@ module Funicular
     def handle_route_change
       path = current_location_path
 
+      # Hydration only applies to the very first navigation. Consume the flag
+      # here so an unmatched initial route does not leave it set for later.
+      hydrate_now = @hydrate_initial
+      @hydrate_initial = false
+
       # Find matching route
       component_class, params = find_route(path)
 
@@ -113,6 +134,22 @@ module Funicular
       @current_path = path
       @current_component = component_class.new(params)
       # @type ivar @current_component: Funicular::Component
+
+      server_root = hydrate_now ? Funicular.first_element_child(@container) : nil
+
+      if server_root
+        begin
+          @current_component.seed_state(Funicular.window_state)
+          @current_component.hydrate(server_root)
+          return
+        rescue => e
+          # Server/client disagreed: discard server DOM and render fresh.
+          puts "[Funicular] Hydration failed, falling back to full render: #{e.message}"
+          @container[:innerHTML] = ''
+          @current_component = component_class.new(params)
+        end
+      end
+
       @current_component.mount(@container)
     end
 

data/mrblib/store.rb

@@ -0,0 +1,304 @@
+module Funicular
+  # Declarative client-side store backed by IndexedDB::KVS.
+  #
+  # Subclass either Funicular::Store::Singleton (one value per scope) or
+  # Funicular::Store::Collection (ordered list per scope) and use the
+  # class-level DSL to wire everything up. See store_singleton.rb /
+  # store_collection.rb for the user-facing API.
+  class Store
+    # event_name => Array of store classes that subscribed via cleared_on
+    EVENT_REGISTRY = {} #: Hash[Symbol, Array[singleton(Funicular::Store)]]
+
+    # [database, kvs_store] => IndexedDB::KVS instance, shared across store classes
+    KVS_POOL = {} #: Hash[Array[String], IndexedDB::KVS]
+
+    # Snapshot of a `subscribes_to` declaration captured on the store class.
+    SubscribesTo = Data.define(:channel_name, :params_proc, :handler_block)
+
+    # Thin wrapper around a Funicular::Cable::Subscription. Exists so the
+    # store layer can hold lifecycle ownership without leaking the cable
+    # type into user code.
+    class Subscription
+      attr_reader :cable_sub
+
+      def initialize(cable_sub)
+        @cable_sub = cable_sub
+      end
+
+      def unsubscribe
+        @cable_sub.unsubscribe
+        nil
+      end
+    end
+
+    # Per-scope accessor returned by Funicular::Store.where(...). Singleton
+    # and Collection define their own subclasses with the data-shape API.
+    class Scope
+      attr_reader :store_class, :scope_kwargs
+
+      def initialize(store_class, scope_kwargs)
+        @store_class = store_class
+        @scope_kwargs = scope_kwargs
+        @on_change = {}
+        @next_cb_id = 0
+        @subscription = nil
+      end
+
+      # Expose scope kwargs as method calls (e.g. scope.channel_id) so that
+      # `params: ->(s) { { channel_id: s.channel_id } }` reads naturally in
+      # the subscribes_to DSL.
+      def method_missing(name, *args)
+        if @scope_kwargs.key?(name)
+          @scope_kwargs[name]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @scope_kwargs.key?(name) || super
+      end
+
+      def on_change(&blk)
+        @next_cb_id += 1
+        id = @next_cb_id
+        @on_change[id] = blk
+        id
+      end
+
+      def off_change(id)
+        @on_change.delete(id)
+        nil
+      end
+
+      def subscribed?
+        !@subscription.nil?
+      end
+
+      def subscription
+        @subscription
+      end
+
+      # Lazily create a Cable subscription for this scope using the store
+      # class's `subscribes_to` declaration. The handler block runs with
+      # `self == this Scope`, so bareword calls like `replace`, `append`,
+      # and `remove` resolve to the scope's mutators.
+      def subscribe!
+        existing = @subscription
+        return existing if existing
+        cable_binding = @store_class.__cable_binding
+        raise "no subscribes_to declared on #{@store_class}" unless cable_binding
+        consumer = @store_class.__consumer
+        params = cable_binding.params_proc.call(self)
+        handler = cable_binding.handler_block
+        scope = self
+        cable_sub = consumer.subscriptions.create(params) do |data|
+          scope.instance_exec(data, scope, &handler) # steep:ignore
+        end
+        sub = Funicular::Store::Subscription.new(cable_sub)
+        @subscription = sub
+        sub
+      end
+
+      def unsubscribe!
+        sub = @subscription
+        return nil unless sub
+        sub.unsubscribe
+        @subscription = nil
+      end
+
+      private
+
+      def storage_key
+        parts = [] #: Array[String]
+        @scope_kwargs.each do |k, v|
+          parts << "#{k}=#{v}"
+        end
+        parts.join(":")
+      end
+
+      def kvs
+        @store_class.__kvs
+      end
+
+      def now_seconds
+        Time.now.to_i
+      end
+
+      def expired_record?(rec)
+        return false unless rec.is_a?(Hash)
+        ttl = rec["expires_in"]
+        return false unless ttl.is_a?(Integer) && 0 < ttl
+        wrote = rec["wrote_at"]
+        return false unless wrote.is_a?(Integer)
+        ttl < (now_seconds - wrote)
+      end
+
+      def fire_change(snapshot)
+        @on_change.each_value do |cb|
+          begin
+            cb.call(snapshot)
+          rescue => e
+            puts "[Funicular::Store] on_change error in #{@store_class}: #{e.class}: #{e.message}"
+          end
+        end
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Class-level DSL & runtime
+    # ------------------------------------------------------------------
+
+    class << self
+      attr_reader :__database, :__kvs_store_name, :__scope_keys,
+                  :__expires_in, :__source, :__belongs_to,
+                  :__cable_url, :__cable_binding,
+                  :__cleared_handlers
+
+      # IndexedDB database name. Required (no implicit default; users
+      # should pin database names so refactors stay data-compatible).
+      def database(name)
+        @__database = name.to_s
+      end
+
+      # Object-store name within the database. Default: "kv".
+      def kvs_store(name)
+        @__kvs_store_name = name.to_s
+      end
+
+      # Declare scope keys. Single Symbol or splat of Symbols.
+      #
+      #   scope :channel_id
+      #   scope :channel_id, :user_id
+      def scope(*keys)
+        @__scope_keys = keys.map { |k| k.to_sym }
+      end
+
+      def expires_in(seconds)
+        @__expires_in = seconds
+      end
+
+      # Declarative-only annotation pointing at a Funicular::Model class.
+      # Has no behaviour; intended for documentation / tooling.
+      def source(model_class)
+        @__source = model_class
+      end
+
+      # Declarative-only association marker (e.g. `belongs_to :channel`).
+      # No behaviour.
+      def belongs_to(name)
+        @__belongs_to = name.to_sym
+      end
+
+      def cable_url(url)
+        @__cable_url = url.to_s
+      end
+
+      # Capture a Cable subscription binding. The block is invoked via
+      # instance_exec on the Scope when the cable subscription receives a
+      # message, so bareword `replace` / `append` / `remove` resolve to the
+      # scope's own mutators.
+      def subscribes_to(channel_name, params:, &block)
+        raise "subscribes_to requires a block" unless block
+        @__cable_binding = SubscribesTo.new(channel_name.to_s, params, block)
+      end
+
+      # Register this store class for one or more global event names. When
+      # Funicular::Store.dispatch(:event) is called, every registered class
+      # has its data wiped (default) or runs the user-supplied block.
+      def cleared_on(*event_names, &block)
+        pool = (@__cleared_handlers ||= {}) #: Hash[Symbol, Proc?]
+        registry = Funicular::Store::EVENT_REGISTRY
+        event_names.each do |ev|
+          sym = ev.to_sym
+          pool[sym] = block
+          arr = (registry[sym] ||= []) #: Array[singleton(Funicular::Store)]
+          arr << self unless arr.include?(self)
+        end
+      end
+
+      # Return (and memoize) the Scope for the given scope kwargs. Same
+      # kwargs always return the same Scope instance, which is required so
+      # `on_change` callbacks attach to a single identity.
+      def where(**scope_kwargs)
+        validate_scope_kwargs!(scope_kwargs)
+        pool = (@__scope_pool ||= {}) #: Hash[Hash[Symbol, untyped], Funicular::Store::Scope]
+        existing = pool[scope_kwargs]
+        return existing if existing
+        scope = scope_class.new(self, scope_kwargs)
+        pool[scope_kwargs] = scope
+        scope
+      end
+
+      # Subclasses (Singleton / Collection) override to return the
+      # appropriate Scope class.
+      def scope_class
+        raise NotImplementedError, "#{self} must subclass Funicular::Store::Singleton or Funicular::Store::Collection"
+      end
+
+      def __kvs
+        db = @__database || raise("#{self}: missing `database \"...\"` declaration")
+        store_name = @__kvs_store_name || "kv"
+        key = [db, store_name]
+        existing = Funicular::Store::KVS_POOL[key]
+        return existing if existing
+        kvs = IndexedDB::KVS.open(db, store: store_name)
+        Funicular::Store::KVS_POOL[key] = kvs
+        kvs
+      end
+
+      def __consumer
+        @__consumer ||= Funicular::Cable.create_consumer(@__cable_url || "/cable")
+      end
+
+      def __handle_dispatch(event, payload)
+        pool = @__cleared_handlers
+        block = pool ? pool[event] : nil
+        if block
+          instance_exec(payload) { |p| block.call(p) }
+        else
+          __clear_all!
+        end
+        nil
+      end
+
+      def __clear_all!
+        return nil unless @__database
+        __kvs.clear
+        @__scope_pool = {} if @__scope_pool
+        nil
+      end
+
+      private
+
+      def validate_scope_kwargs!(scope_kwargs)
+        declared = @__scope_keys || []
+        given = scope_kwargs.keys
+        unknown = given - declared
+        unless unknown.empty?
+          raise ArgumentError, "#{self}: unknown scope keys #{unknown.inspect}; declared #{declared.inspect}"
+        end
+        missing = declared - given
+        unless missing.empty?
+          raise ArgumentError, "#{self}: missing scope keys #{missing.inspect}"
+        end
+      end
+    end
+
+    # Dispatch an event to every store class that registered via
+    # `cleared_on`. Default per-class action is `__clear_all!` (wipe the
+    # KVS + drop memoized scopes); override per class with a block.
+    def self.dispatch(event, payload = nil)
+      sym = event.to_sym
+      classes = Funicular::Store::EVENT_REGISTRY[sym] || []
+      classes.each do |klass|
+        begin
+          klass.__handle_dispatch(sym, payload)
+        rescue => e
+          puts "[Funicular::Store] dispatch(#{sym.inspect}) error in #{klass}: #{e.class}: #{e.message}"
+        end
+      end
+      nil
+    end
+  end
+end

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