funicular 0.1.0 → 0.2.1

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/vdom.rb

@@ -132,8 +132,10 @@ module Funicular
             # Handle boolean attributes
             if value.nil? || value.to_s == "false"
               # Do not set attribute (leave it absent)
+              dom_node[key_str] = false
             else
               dom_node.setAttribute(key_str, key_str)
+              dom_node[key_str] = true
             end
           else
             # Attribute

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

data/sig/model.rbs

@@ -1,5 +1,8 @@
 module Funicular
   class Model
+    include Funicular::Model::Validations
+    extend Funicular::Model::Validations::ClassMethods
+
     attr_reader id: untyped
     @changed_attributes: Hash[String, untyped]
 
@@ -10,10 +13,12 @@ module Funicular
 
     def initialize: (?Hash[untyped, untyped] attributes) -> void
     def self.load_schema: (Hash[String, untyped] schema_data) -> void
+    def self.register_schema_validations: (untyped validations) -> void
+    def self.normalize_validation_options: (Symbol | String kind, untyped opts) -> untyped
 
     def self.all: (?Hash[untyped, untyped] params) ?{ (Array[Model]? instances, String? error) -> void } -> void
     def self.find: (?untyped id, ?endpoint_name: String, ?model_class: singleton(Model)) ?{ (Model? instance, String? error) -> void } -> void
-    def self.create: (Hash[untyped, untyped] attrs, ?model_class: singleton(Model)) ?{ (Model? instance, String? error) -> void } -> void
+    def self.create: (Hash[untyped, untyped] attrs, ?model_class: singleton(Model)) ?{ (Model? instance, untyped error) -> void } -> void
     def self.destroy: (?untyped id) ?{ (bool success, untyped result) -> void } -> void
 
     def update: (?Hash[untyped, untyped]? attrs) ?{ (bool success, untyped result) -> void } -> void

data/sig/patcher.rbs

@@ -3,9 +3,12 @@ module Funicular
     BOOLEAN_ATTRIBUTES: Array[String]
 
     class Patcher
-      def initialize: (?JS::Object? doc) -> void
+      def initialize: (?JS::Element? doc) -> void
+      # `apply` accepts any DOM node so text-node patches (e.g. :replace)
+      # can recurse into it; Element-only operations are narrowed inside.
       def apply: (JS::Object element, Array[patch_t] patches) -> JS::Object
 
+      # Accepts JS::Object since callers narrow via is_a?(JS::Element) at runtime
       private def update_props: (JS::Object element, Hash[Symbol, String?] props_patch) -> void
       private def create_element: (untyped vnode) -> JS::Object
       private def unmount_component: (VDOM::VNode vnode) -> void

data/sig/router.rbs

@@ -19,7 +19,7 @@ module Funicular
     attr_reader current_component: Component?
     attr_reader current_path: String?
 
-    def initialize: (JS::Object container) -> void
+    def initialize: (JS::Element? container) -> void
     def get: (String path, to: singleton(Component), ?as: String?, ?constraints: route_constraints_t?) -> void
     def post: (String path, to: singleton(Component), ?as: String?, ?constraints: route_constraints_t?) -> void
     def put: (String path, to: singleton(Component), ?as: String?, ?constraints: route_constraints_t?) -> void
@@ -27,7 +27,8 @@ module Funicular
     def delete: (String path, to: singleton(Component), ?as: String?, ?constraints: route_constraints_t?) -> void
     def add_route: (String path, singleton(Component) component_class, ?as: String?, ?constraints: route_constraints_t?) -> void
     def set_default: (String path) -> void
-    def start: () -> void
+    def match: (String path) -> [singleton(Component)?, Hash[Symbol, untyped]]
+    def start: (?hydrate: bool) -> void
     def stop: () -> void
     def navigate: (String path) -> void
     def current_hash_path: () -> String

data/sig/store.rbs

@@ -0,0 +1,89 @@
+module Funicular
+  class Store
+    EVENT_REGISTRY: Hash[Symbol, Array[singleton(Funicular::Store)]]
+    KVS_POOL: Hash[Array[String], IndexedDB::KVS]
+
+    class SubscribesTo < Data
+      attr_reader channel_name: String
+      attr_reader params_proc: ^(Funicular::Store::Scope) -> Hash[Symbol, untyped]
+      attr_reader handler_block: Proc
+
+      def self.new: (String channel_name, ^(Funicular::Store::Scope) -> Hash[Symbol, untyped] params_proc, Proc handler_block) -> instance
+    end
+
+    class Subscription
+      attr_reader cable_sub: Funicular::Cable::Subscription
+
+      def initialize: (Funicular::Cable::Subscription cable_sub) -> void
+      def unsubscribe: () -> nil
+    end
+
+    class Scope
+      attr_reader store_class: singleton(Funicular::Store)
+      attr_reader scope_kwargs: Hash[Symbol, untyped]
+
+      @on_change: Hash[Integer, Proc]
+      @next_cb_id: Integer
+      @subscription: Funicular::Store::Subscription?
+
+      def initialize: (singleton(Funicular::Store) store_class, Hash[Symbol, untyped] scope_kwargs) -> void
+      def method_missing: (Symbol name, *untyped args) -> untyped
+      def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
+      def on_change: () { (untyped) -> void } -> Integer
+      def off_change: (Integer id) -> nil
+      def subscribed?: () -> bool
+      def subscription: () -> Funicular::Store::Subscription?
+      def subscribe!: () -> Funicular::Store::Subscription
+      def unsubscribe!: () -> nil
+
+      private def storage_key: () -> String
+      private def kvs: () -> IndexedDB::KVS
+      private def now_seconds: () -> Integer
+      private def expired_record?: (untyped rec) -> bool
+      private def fire_change: (untyped snapshot) -> void
+    end
+
+    self.@__database: String?
+    self.@__kvs_store_name: String?
+    self.@__scope_keys: Array[Symbol]?
+    self.@__expires_in: Integer?
+    self.@__source: untyped
+    self.@__belongs_to: Symbol?
+    self.@__cable_url: String?
+    self.@__cable_binding: SubscribesTo?
+    self.@__cleared_handlers: Hash[Symbol, Proc?]?
+    self.@__scope_pool: Hash[Hash[Symbol, untyped], Funicular::Store::Scope]?
+    self.@__consumer: Funicular::Cable::Consumer?
+
+    def self.database: (String name) -> String
+    def self.kvs_store: (String name) -> String
+    def self.scope: (*Symbol keys) -> Array[Symbol]
+    def self.expires_in: (Integer seconds) -> Integer
+    def self.source: (untyped model_class) -> untyped
+    def self.belongs_to: (Symbol name) -> Symbol
+    def self.cable_url: (String url) -> String
+    def self.subscribes_to: (String channel_name, params: ^(Funicular::Store::Scope) -> Hash[Symbol, untyped]) { (untyped, Funicular::Store::Scope) -> void } -> SubscribesTo
+    def self.cleared_on: (*Symbol event_names) ?{ (untyped) -> void } -> void
+
+    def self.where: (**untyped scope_kwargs) -> Funicular::Store::Scope
+    def self.scope_class: () -> singleton(Funicular::Store::Scope)
+
+    def self.__database: () -> String?
+    def self.__kvs_store_name: () -> String?
+    def self.__scope_keys: () -> Array[Symbol]?
+    def self.__expires_in: () -> Integer?
+    def self.__source: () -> untyped
+    def self.__belongs_to: () -> Symbol?
+    def self.__cable_url: () -> String?
+    def self.__cable_binding: () -> SubscribesTo?
+    def self.__cleared_handlers: () -> Hash[Symbol, Proc?]?
+    def self.__kvs: () -> IndexedDB::KVS
+    def self.__consumer: () -> Funicular::Cable::Consumer
+    def self.__handle_dispatch: (Symbol event, untyped payload) -> void
+    def self.__clear_all!: () -> nil
+
+    private def self.validate_scope_kwargs!: (Hash[Symbol, untyped] scope_kwargs) -> void
+
+    def self.dispatch: (Symbol | String event, ?untyped payload) -> nil
+  end
+end

data/sig/store_collection.rbs

@@ -0,0 +1,43 @@
+module Funicular
+  class Store
+    class Collection < Funicular::Store
+      DEFAULT_KEY_PROC: ^(untyped) -> untyped
+
+      self.@__limit: Integer?
+      self.@__order: Symbol?
+      self.@__key_proc: ^(untyped) -> untyped | nil
+
+      def self.limit: (Integer n) -> Integer
+      def self.order: (Symbol direction) -> Symbol
+      def self.key: (^(untyped) -> untyped proc) -> (^(untyped) -> untyped)
+      def self.scope_class: () -> singleton(Funicular::Store::Collection::Scope)
+
+      def self.__limit: () -> Integer?
+      def self.__order: () -> Symbol?
+      def self.__key_proc: () -> (^(untyped) -> untyped | nil)
+
+      class Scope < Funicular::Store::Scope
+        attr_reader store_class: singleton(Funicular::Store::Collection)
+        @store_class: singleton(Funicular::Store::Collection)
+
+        def all: () -> Array[untyped]
+        def replace: (untyped arr) -> Array[untyped]
+        def append: (untyped item) -> Array[untyped]
+        def remove: (untyped id) -> Array[untyped]
+        def last: () -> untyped
+        def last_id: () -> untyped
+        def size: () -> Integer
+        def clear: () -> nil
+        def expired?: () -> bool
+        def same_tail?: (untyped other) -> bool
+
+        private def key_proc: () -> ^(untyped) -> untyped
+        private def cap: (Array[untyped] arr) -> Array[untyped]
+        private def append_to: (Array[untyped] arr, untyped item) -> Array[untyped]
+        private def read: () -> untyped
+        private def write: (Array[untyped] items) -> Hash[String, untyped]
+        private def erase: () -> nil
+      end
+    end
+  end
+end

data/sig/store_singleton.rbs

@@ -0,0 +1,19 @@
+module Funicular
+  class Store
+    class Singleton < Funicular::Store
+      def self.scope_class: () -> singleton(Funicular::Store::Singleton::Scope)
+
+      class Scope < Funicular::Store::Scope
+        def value: () -> untyped
+        def value=: (untyped v) -> untyped
+        def delete: () -> nil
+        def present?: () -> bool
+        def expired?: () -> bool
+
+        private def read: () -> untyped
+        private def write: (untyped v) -> Hash[String, untyped]
+        private def erase: () -> nil
+      end
+    end
+  end
+end

data/sig/validations.rbs

@@ -0,0 +1,103 @@
+module Funicular
+  class Model
+    # Validation error collection (a small slice of ActiveModel::Errors).
+    class Errors
+      @messages: Hash[Symbol, Array[String]]
+
+      def initialize: () -> void
+      def add: (Symbol | String attribute, String message) -> String
+      def []: (Symbol | String attribute) -> Array[String]
+      def added?: (Symbol | String attribute) -> bool
+      def messages: () -> Hash[Symbol, Array[String]]
+      def full_messages: () -> Array[String]
+      def clear: () -> void
+      def empty?: () -> bool
+      def any?: () -> bool
+
+      private
+      def humanize: (Symbol | String attribute) -> String
+    end
+
+    # ActiveModel-style validation, mixed into Model.
+    module Validations
+      def self.included: (untyped base) -> void
+
+      # Base class for attribute validators.
+      class EachValidator
+        @attributes: Array[Symbol]
+        @options: Hash[Symbol, untyped]
+
+        attr_reader attributes: Array[Symbol]
+        attr_reader options: Hash[Symbol, untyped]
+
+        def initialize: (attributes: Array[Symbol], **untyped options) -> void
+        def kind: () -> Symbol
+        def validate: (untyped record) -> void
+        def validate_each: (untyped record, Symbol attribute, untyped value) -> void
+
+        private
+        def blank?: (untyped value) -> bool
+        def present?: (untyped value) -> bool
+      end
+
+      module ClassMethods
+        @validators: Array[EachValidator]
+
+        SHARED_OPTIONS: Array[Symbol]
+
+        def validators: () -> Array[EachValidator]
+        def validators_on: (Symbol | String attribute) -> Array[EachValidator]
+        def validates: (*Symbol | String attributes, **untyped options) -> void
+        def add_schema_validator: (Symbol | String attribute, Symbol | String kind, untyped opts) -> void
+
+        private
+        def validator_class_for: (Symbol | String key) -> singleton(EachValidator)?
+        def symbolize_keys: (untyped hash) -> Hash[Symbol, untyped]
+      end
+
+      # Instance API (mixed into Model).
+      @errors: Errors
+      def errors: () -> Errors
+      def read_attribute_for_validation: (Symbol attribute) -> untyped
+      def valid?: () -> bool
+      def invalid?: () -> bool
+
+      # --- concrete validators ---
+
+      class PresenceValidator < EachValidator
+      end
+
+      class AbsenceValidator < EachValidator
+      end
+
+      class LengthValidator < EachValidator
+        private
+        def range_include?: (untyped range, Integer length) -> bool
+      end
+
+      class FormatValidator < EachValidator
+      end
+
+      class NumericalityValidator < EachValidator
+        CHECKS: Hash[Symbol, String]
+
+        private
+        def compare: (Numeric number, Symbol option, untyped target) -> bool
+        def message_for: (Symbol option, untyped target) -> String
+        def to_number: (untyped value) -> (Numeric | nil)
+      end
+
+      class InclusionValidator < EachValidator
+      end
+
+      class ExclusionValidator < EachValidator
+      end
+
+      class AcceptanceValidator < EachValidator
+      end
+
+      class ConfirmationValidator < EachValidator
+      end
+    end
+  end
+end

data/sig/vdom.rbs

@@ -32,18 +32,18 @@ module Funicular
     class Renderer
       @error_boundary_stack: Array[Funicular::ErrorBoundary]
 
-      def initialize: (?JS::Object? doc) -> void
-      def render: (VDOM::VNode | VDOM::Text | nil vnode, ?JS::Object? parent) -> JS::Object
+      def initialize: (?JS::Element? doc) -> void
+      def render: (VDOM::VNode | VDOM::Text | nil vnode, ?JS::Element? parent) -> JS::Element
 
       private def current_error_boundary: () -> ErrorBoundary?
-      private def render_element: (Element element, JS::Object? parent) -> JS::Object
-      private def render_text: (VDOM::Text text, JS::Object? parent) -> JS::Object
-      private def render_component: (VDOM::Component component_vnode, JS::Object? parent) -> JS::Object
+      private def render_element: (Element element, JS::Element? parent) -> JS::Element
+      private def render_text: (VDOM::Text text, JS::Element? parent) -> JS::Element
+      private def render_component: (VDOM::Component component_vnode, JS::Element? parent) -> JS::Element
     end
 
     def self.create_element: (String tag, ?Hash[Symbol, untyped] props, *child_t children) -> Element
     def self.create_text: (String content) -> Text
-    def self.render: (VNode vnode, JS::Object container) -> void
+    def self.render: (VNode vnode, JS::Element container) -> void
     def self.diff: (VNode? old_vnode, VNode? new_vnode) -> Array[patch_t]
     def self.patch: (JS::Object element, Array[patch_t] patches) -> JS::Object