funicular 0.0.1 → 0.1.0

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,65 @@
+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
+    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

data/sig/component.rbs

@@ -0,0 +1,141 @@
+module Funicular
+  class Component
+    class StateAccessor
+      def initialize: (Hash[Symbol, untyped] state_hash) -> void
+      def []: (Symbol key) -> untyped
+      def method_missing: (Symbol method, *untyped args) -> untyped
+      def respond_to_missing?: (Symbol method, ?bool include_private) -> bool
+      def errors: () -> Hash[Symbol, String]
+    end
+
+    HTML_TAGS: Array[String]
+
+    attr_accessor props: Hash[Symbol, untyped]
+    attr_accessor vdom: VDOM::VNode | VDOM::Text | nil
+    attr_accessor dom_element: JS::Object
+    attr_accessor mounted: bool
+    attr_reader refs: Hash[Symbol, JS::Object]
+    @event_listeners: Array[Integer]
+    @child_components: Array[Component]
+    @suspense_data: Hash[Symbol, untyped]
+    @suspense_states: Hash[Symbol, Symbol]
+    @suspense_errors: Hash[Symbol, untyped]
+    @suspense_pending_timers: Array[Integer]
+    self.@suspense_definitions: Hash[Symbol, suspense_definition]
+
+    def initialize: (?Hash[Symbol, untyped] props) -> void
+
+    # Styles DSL class methods
+    def self.styles: () { (StyleBuilder) -> void } -> void
+    def self.styles_definitions: () -> Hash[Symbol, Hash[Symbol, untyped]]
+
+    # Suspense DSL class methods
+    # Note: Using untyped for Proc types to avoid instance_exec block type mismatch warnings
+    type suspense_definition = { loader: untyped, on_resolve: untyped, min_delay: Integer? }
+    def self.use_suspense: (Symbol name, untyped loader, ?on_resolve: untyped, ?min_delay: Integer) -> void
+    def self.suspense_definitions: () -> Hash[Symbol, suspense_definition]
+
+    def state: () -> StateAccessor
+
+    # Styles DSL instance method
+    def s: () -> StyleAccessor
+
+    # Public API
+    def initialize_state: () -> Hash[Symbol, untyped]
+
+    # Suspense instance methods
+    def load_suspense_data: () -> void
+    def load_single_suspense: (Symbol name, ?suspense_definition? definition) -> void
+    def reload_suspense: (Symbol name) -> void
+    def suspense_loading?: (*Symbol names) -> bool
+    def suspense_error?: (Symbol name) -> bool
+    def suspense_error: (Symbol name) -> untyped
+    def suspense: (fallback: ^() -> void, ?error: ^(untyped) -> void) { () -> void } -> void
+
+    def patch: (Hash[Symbol, untyped] new_state) -> void
+    def mount: (JS::Object container) -> void
+    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 build_vdom: () -> (VDOM::VNode | VDOM::Text | nil)
+
+    # Lifecycle hooks (public, can be overridden in subclasses)
+    def component_will_mount: () -> void
+    def component_mounted: () -> void
+    def component_will_update: () -> void
+    def component_updated: () -> void
+    def component_will_unmount: () -> void
+    def component_unmounted: () -> void
+    def component_raised: (Exception e) -> void
+
+    # Child component helper
+    def component: (Class component_class, ?Hash[Symbol, untyped] props) ?{ () -> untyped } -> VDOM::Component
+
+    # Rails-style form helper
+    def form_for: (Symbol model_key, ?Hash[Symbol, untyped] options) { (FormBuilder) -> void } -> VDOM::Element
+
+    # Rails-style routing helpers
+    def link_to: (String path, ?method: Symbol, ?navigate: bool, **untyped options) { -> untyped } -> VDOM::Element
+    def method_missing: (Symbol method, *untyped args) -> untyped
+    def respond_to_missing?: (Symbol method, ?bool include_private) -> bool
+
+    # Transition helpers
+    def remove_via: (String element_id, String from, String to, ?duration: Integer) ?{ () -> void } -> void
+    def add_via: (String element_id, String from, String to, ?duration: Integer) ?{ () -> void } -> void
+
+    # Private methods
+    private def handle_link_click: (String path) -> void
+    private def handle_link_with_method: (String path, Symbol method) -> void
+    private def handle_link_response: (HTTP::Response response, String path, Symbol method) -> void
+    private def normalize_state_value: (untyped value) -> untyped
+    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 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
+
+    # HTML element methods (DSL)
+    def div: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def span: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def p: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def a: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def h1: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def h2: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def h3: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def h4: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def h5: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def h6: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def ul: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def ol: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def li: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def table: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def thead: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def tbody: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def tr: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def th: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def td: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def form: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def input: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def textarea: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def button: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def select: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def option: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def label: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def header: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def footer: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def nav: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def section: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def article: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def aside: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def img: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def video: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def audio: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def canvas: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def br: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+    def hr: (?Hash[Symbol, untyped] props) ?{ -> untyped } -> VDOM::Element
+  end
+end

data/sig/debug.rbs

@@ -0,0 +1,28 @@
+$__funicular_debug__: Funicular::Debug
+
+module Funicular
+  module Debug
+    self.@error_registry: Array[Hash[Symbol, untyped]]
+
+    def self.enabled?: () -> bool
+    def self.component_registry: () -> Hash[Integer, Funicular::Component]
+    def self.register_component: (Funicular::Component) -> Integer?
+    def self.unregister_component: (Integer) -> void
+    def self.get_component: (Integer) -> Funicular::Component?
+    def self.all_components: () -> Array[Funicular::Component]
+    def self.component_tree: () -> String
+    def self.get_component_state: (Integer) -> String
+    def self.get_component_instance_variables: (Integer) -> String
+    def self.expose_to_global: () -> void
+    def self.report_error: (ErrorBoundary boundary, Exception error, ?(Hash[Symbol, Component] | nil) error_info) -> Hash[Symbol, untyped]?
+    def self.clear_errors: () -> void
+    def self.error_list: () -> String
+    def self.last_error: () -> Hash[Symbol, untyped]?
+    def self.error_count: () -> Integer
+
+    private def self.error_registry: () -> Array[Hash[Symbol, untyped]]
+    private def self.get_state_keys: (Funicular::Component) -> Array[String]
+    private def self.get_child_ids: (Funicular::Component) -> Array[Integer]
+    private def self.collect_direct_children: (Funicular::VDOM::VNode, Array[Funicular::Component]) -> void
+  end
+end

data/sig/differ.rbs

@@ -0,0 +1,18 @@
+module Funicular
+  module VDOM
+    class Differ
+      type children_t = Array[child_t]
+      def self.diff: (untyped old_node, untyped new_node) -> Array[patch_t]
+
+      private def self.diff_text: (Text old_node, Text new_node) -> Array[patch_t]
+      private def self.diff_element: (Element old_node, Element new_node) -> Array[patch_t]
+      private def self.diff_props: (Hash[Symbol, untyped] old_props, Hash[Symbol, untyped] new_props) -> Hash[Symbol, untyped]
+      private def self.diff_children: (children_t old_children, children_t new_children) -> Array[patch_t]
+      private def self.diff_children_with_keys: (children_t old_children, children_t new_children) -> Array[patch_t]
+      private def self.diff_children_by_index: (children_t old_children, children_t new_children) -> Array[patch_t]
+      private def self.diff_component: (VDOM::Component old_node, VDOM::Component new_node) -> Array[patch_t]
+
+      private def self.props_changed_excluding_procs?: (Hash[Symbol, untyped] old_props, Hash[Symbol, untyped] new_props) -> bool
+    end
+  end
+end

data/sig/environment_iquirer.rbs

@@ -0,0 +1,10 @@
+module Funicular
+  class EnvironmentInquirer
+    def initialize: (EnvironmentInquirer | String env) -> void
+    def to_s: () -> String
+    def inspect: () -> String
+    def ==: (String other) -> bool
+    def development?: () -> bool
+  end
+end
+

data/sig/error_boundary.rbs

@@ -0,0 +1,14 @@
+module Funicular
+  class ErrorBoundary < Component
+    attr_accessor error_caught_during_render: bool?
+
+    def initialize_state: () -> Hash[Symbol, untyped]
+    def catch_error: (Exception error, ?Hash[Symbol, untyped]? error_info) -> bool
+    def reset: () -> void
+    def render: () -> (VDOM::VNode | String | Integer | Float | Array[untyped] | nil)
+
+    private def render_fallback: () -> (VDOM::VNode | String)
+    private def default_fallback: () -> VDOM::VNode
+    private def render_children: () -> VDOM::VNode
+  end
+end

data/sig/file_upload.rbs

@@ -0,0 +1,18 @@
+module Funicular
+  module FileUpload
+    self.@callback_counters: Array[Integer]
+
+    JS_HELPER_CODE: String
+
+    def self.mount: () -> void
+    def self.select_file_with_preview: (String input_id) { (JS::Object? file, String? preview_url) -> void } -> void
+    def self.upload_with_formdata: (
+      String url,
+      ?fields: Hash[untyped, untyped],
+      ?file_field: String?,
+      ?file: JS::Object?
+    ) { (Hash[untyped, untyped] result) -> void } -> void
+    def self.store_file: (String input_id, ?String storage_key) -> JS::Object?
+    def self.retrieve_file: (?String storage_key) -> JS::Object?
+  end
+end

data/sig/form_builder.rbs

@@ -0,0 +1,29 @@
+module Funicular
+  class FormBuilder
+    attr_reader component: Component
+    attr_reader model_key: Symbol
+    attr_reader options: Hash[Symbol, untyped]
+
+    def initialize: (Component component, Symbol model_key, ?Hash[Symbol, untyped] options) -> void
+
+    # Field builder methods
+    def text_field: (Symbol field_name, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def password_field: (Symbol field_name, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def email_field: (Symbol field_name, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def number_field: (Symbol field_name, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def textarea: (Symbol field_name, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def checkbox: (Symbol field_name, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def select: (Symbol field_name, Array[untyped] choices, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def file_field: (Symbol field_name, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def submit: (?String label, ?Hash[Symbol, untyped] options) -> VDOM::Element
+    def label: (Symbol field_name, ?String? text, ?Hash[Symbol, untyped] options) -> VDOM::Element
+
+    # Generic field builder
+    private def build_field: (Symbol field_name, String field_type, Hash[Symbol, untyped] field_options) -> VDOM::Element
+
+    # Helper methods for nested state access
+    private def get_nested_value: (Component::StateAccessor state, String key_path) -> untyped
+    private def set_nested_value: (Symbol model_key, String field_key, untyped new_value) -> void
+    private def deep_merge_value: (Hash[Symbol, untyped] hash, Array[String] keys, untyped value) -> Hash[Symbol, untyped]
+  end
+end

data/sig/funicular.rbs

@@ -1,4 +1,14 @@
 module Funicular
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  def self.version: () -> String
+  def self.env: () -> EnvironmentInquirer
+  def self.env=: (EnvironmentInquirer | String environment) -> EnvironmentInquirer?
+  def self.router: () -> Router?
+  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.configure_forms: () ?{ (Hash[Symbol, String]) -> void } -> void
+  def self.configure_debug: () ?{ (self) -> void } -> void
+  def self.export_debug_config: () -> void
+
 end

data/sig/http.rbs

@@ -0,0 +1,22 @@
+module Funicular
+  module HTTP
+    class Response
+      attr_reader data: untyped
+      attr_reader status: Integer
+      attr_reader ok: bool
+
+      def initialize: (Integer status, untyped data) -> void
+      def error?: () -> bool
+      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.csrf_token: () -> String?
+
+    private def self.request: (String method, String url, Hash[untyped, untyped]? body) { (Response) -> void } -> void
+  end
+end

data/sig/model.rbs

@@ -0,0 +1,23 @@
+module Funicular
+  class Model
+    attr_reader id: untyped
+    @changed_attributes: Hash[String, untyped]
+
+    def self.schema: () -> Hash[String, Hash[String, untyped]]
+    def self.schema=: (Hash[String, Hash[String, untyped]] schema) -> Hash[String, Hash[String, untyped]]
+    def self.endpoints: () -> Hash[String, Hash[String, String]]
+    def self.endpoints=: (Hash[String, Hash[String, String]] endpoints) -> Hash[String, Hash[String, String]]
+
+    def initialize: (?Hash[untyped, untyped] attributes) -> void
+    def self.load_schema: (Hash[String, untyped] schema_data) -> void
+
+    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.destroy: (?untyped id) ?{ (bool success, untyped result) -> void } -> void
+
+    def update: (?Hash[untyped, untyped]? attrs) ?{ (bool success, untyped result) -> void } -> void
+    def destroy: () ?{ (bool success, untyped result) -> void } -> void
+    def reload: () ?{ (Model? instance, String? error) -> void } -> void
+  end
+end