funicular 0.1.0 → 0.2.0

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

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/sig/cable.rbs

@@ -41,6 +41,7 @@ module Funicular
       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

data/sig/component.rbs

@@ -12,9 +12,9 @@ module Funicular
 
     attr_accessor props: Hash[Symbol, untyped]
     attr_accessor vdom: VDOM::VNode | VDOM::Text | nil
-    attr_accessor dom_element: JS::Object
+    attr_accessor dom_element: JS::Element
     attr_accessor mounted: bool
-    attr_reader refs: Hash[Symbol, JS::Object]
+    attr_reader refs: Hash[Symbol, JS::Element]
     @event_listeners: Array[Integer]
     @child_components: Array[Component]
     @suspense_data: Hash[Symbol, untyped]
@@ -53,10 +53,12 @@ module Funicular
     def suspense: (fallback: ^() -> void, ?error: ^(untyped) -> void) { () -> void } -> void
 
     def patch: (Hash[Symbol, untyped] new_state) -> void
-    def mount: (JS::Object container) -> void
+    def mount: (JS::Element container) -> void
+    def hydrate: (JS::Element dom_element) -> void
+    def seed_state: (Hash[untyped, untyped]? state_hash) -> self
     def unmount: () -> void
     def render: () -> (VDOM::VNode | String | Integer | Float | Array[untyped] | nil)
-    def bind_events: (JS::Object dom_element, VDOM::VNode | VDOM::Text | nil vnode) -> void
+    def bind_events: (JS::Element dom_element, VDOM::VNode | VDOM::Text | nil vnode) -> void
     def build_vdom: () -> (VDOM::VNode | VDOM::Text | nil)
 
     # Lifecycle hooks (public, can be overridden in subclasses)
@@ -91,13 +93,19 @@ module Funicular
     private def re_render: () -> void
     private def normalize_vnode: (untyped value) -> (VDOM::Element | VDOM::Text | VDOM::Component | nil)
     private def add_data_component_attribute: (VDOM::VNode vnode) -> void
-    private def collect_refs: (JS::Object dom_element, VDOM::VNode | VDOM::Text | nil vnode, ?Hash[Symbol, JS::Object] refs_map) -> Hash[Symbol, JS::Object]
+    private def collect_refs: (JS::Element dom_element, VDOM::VNode | VDOM::Text | nil vnode, ?Hash[Symbol, JS::Element] refs_map) -> Hash[Symbol, JS::Element]
     private def cleanup_events: () -> void
     private def cleanup_suspense_timers: () -> void
     private def add_child: (untyped child) -> void
     private def collect_child_components: (VDOM::VNode | VDOM::Text | nil vnode) -> void
     private def collect_child_components_recursive: (VDOM::VNode | VDOM::Text | nil vnode, Array[Component] components) -> void
 
+    # Hydration helpers
+    private def hydration_match?: (untyped vnode, untyped dom_element) -> bool
+    private def warn_hydration_mismatch: (untyped vnode, untyped dom_element) -> void
+    private def full_render_fallback: (VDOM::VNode | VDOM::Text | nil new_vdom, untyped server_dom) -> JS::Element
+    private def hydrate_child_components: (untyped vnode, untyped dom_element) -> void
+
     # HTML element methods (DSL)
     def div: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
     def span: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element

data/sig/funicular.rbs

@@ -1,13 +1,26 @@
 module Funicular
   VERSION: String
 
+  self.@server: bool
+  self.@form_builder_config: Hash[Symbol, String]?
+
   def self.version: () -> String
   def self.env: () -> EnvironmentInquirer
   def self.env=: (EnvironmentInquirer | String environment) -> EnvironmentInquirer?
   def self.router: () -> Router?
+
+  # SSR / hydration support
+  def self.server?: () -> bool
+  def self.server=: (untyped value) -> bool
+  def self.window_state: () -> Hash[String, untyped]
+  def self.has_ssr_state?: () -> bool
+  def self.first_element_child: (JS::Element container_element) -> JS::Element?
+
   def self.load_schemas: (Hash[singleton(Model), String] models) ?{ () -> void } -> void
-  def self.start: (?singleton(Component)? component_class, ?container: String | JS::Object, ?props: Hash[Symbol, untyped]) ?{ (Router router) -> void } -> (Component | Router)
+  def self.start: (?singleton(Component)? component_class, ?container: String | JS::Element, ?props: Hash[Symbol, untyped], ?hydrate: bool) ?{ (Router router) -> void } -> (Component | Router | nil)
   def self.configure_forms: () ?{ (Hash[Symbol, String]) -> void } -> void
+  def self.form_builder_config: () -> Hash[Symbol, String]?
+  def self.form_builder_config=: (Hash[Symbol, String] config) -> Hash[Symbol, String]
   def self.configure_debug: () ?{ (self) -> void } -> void
   def self.export_debug_config: () -> void
 

data/sig/html_serializer.rbs

@@ -0,0 +1,20 @@
+module Funicular
+  module VDOM
+    class HTMLSerializer
+      VOID_ELEMENTS: Array[String]
+      SKIP_PROPS: Array[Symbol]
+
+      def self.serialize: (VNode? vnode) -> String
+      def render: (VNode? vnode) -> String
+
+      private
+      def render_element: (Element element) -> String
+      def render_children: (Array[child_t] children) -> String
+      def render_text: (Text text) -> String
+      def render_component: (Component component_vnode) -> String
+      def serialize_props: (Hash[Symbol, untyped] props) -> String
+      def escape_html: (untyped str) -> String
+      def escape_attr: (untyped str) -> String
+    end
+  end
+end

data/sig/http.rbs

@@ -1,5 +1,10 @@
 module Funicular
   module HTTP
+    CACHE_DB_NAME: String
+    CACHE_STORE: String
+
+    self.@cache: IndexedDB::KVS?
+
     class Response
       attr_reader data: untyped
       attr_reader status: Integer
@@ -10,13 +15,23 @@ module Funicular
       def error_message: () -> String?
     end
 
-    def self.get: (String url) { (Response) -> void } -> void
-    def self.post: (String url, ?Hash[untyped, untyped]? body) { (Response) -> void } -> void
-    def self.patch: (String url, ?Hash[untyped, untyped]? body) { (Response) -> void } -> void
-    def self.delete: (String url) { (Response) -> void } -> void
-    def self.put: (String url, ?Hash[untyped, untyped]? body) { (Response) -> void } -> void
+    def self.cache_init!: () -> IndexedDB::KVS
+    def self.cache_purge: (String url) -> nil
+    def self.cache_clear: () -> nil
+    def self.cache_lookup: (String url) -> untyped
+    def self.cache_write: (String url, Hash[String, untyped] entry) -> nil
+
+    def self.get: (String url, ?cache: Integer?) { (Response) -> void } -> void
+    def self.post: (String url, ?Hash[untyped, untyped]? body, ?cache: Integer?) { (Response) -> void } -> void
+    def self.patch: (String url, ?Hash[untyped, untyped]? body, ?cache: Integer?) { (Response) -> void } -> void
+    def self.delete: (String url, ?cache: Integer?) { (Response) -> void } -> void
+    def self.put: (String url, ?Hash[untyped, untyped]? body, ?cache: Integer?) { (Response) -> void } -> void
     def self.csrf_token: () -> String?
 
-    private def self.request: (String method, String url, Hash[untyped, untyped]? body) { (Response) -> void } -> void
+    private def self.warn_unsupported_cache: (String verb) -> void
+    private def self.now_seconds: () -> Integer
+    private def self.cache_hit?: (untyped entry, Integer ttl) -> bool
+    private def self.serve_from_cache: (Hash[String, untyped] entry) { (Response) -> void } -> void
+    private def self.request: (String method, String url, Hash[untyped, untyped]? body, ?cache: Integer?) { (Response) -> void } -> void
   end
 end