funicular 0.4.0 → 0.5.1

data/mrblib/patcher.rb

@@ -31,9 +31,13 @@ module Funicular
             # Apply internal patches and get the potentially new root element
             new_dom_element = Patcher.new(@doc, instance.runtime).apply(old_dom_element, internal_patches)
 
-            # Update the instance's reference to its root DOM element if it changed
+            # Update the instance's reference to its root DOM element if it
+            # changed. The new root must also become this apply's return
+            # value; otherwise a caller that stores the result (for example
+            # the keyed_children snapshot) keeps pointing at a detached node.
             if new_dom_element != old_dom_element && new_dom_element.is_a?(JS::Element)
               instance.dom_element = new_dom_element
+              result = new_dom_element
             end
 
             # Update the instance's VDOM to the new one AFTER applying patches
@@ -65,18 +69,23 @@ module Funicular
             #   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
+            #   2. apply content updates to kept children. 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.
+            #      regardless of removals.
+            #   3. place kept and new children at their new_index using
+            #      insertBefore on the live DOM. Ops are already in ascending
+            #      new_index order, so each placement fixes the next position.
+            #
+            # Phase 3 tracks the live child order in a Ruby array instead of
+            # re-reading childNodes per op. Every childNodes.to_a allocates a
+            # fresh JS::Object wrapper per node, so wrappers of the same DOM
+            # node never compare equal and the read itself is O(n) across the
+            # wasm boundary. Identity is therefore decided with equal? on the
+            # snapshot objects, which is both exact and free.
             ops = patch[1]
             removes = patch[2]
 
-            child_nodes = element[:childNodes]
-            snapshot = child_nodes.is_a?(JS::Object) ? child_nodes.to_a : [] #: Array[untyped]
+            snapshot = child_nodes_array(element)
 
             # Phase 1: removes (descending old_index)
             sorted_removes = removes.sort { |a, b| b[0] <=> a[0] }
@@ -88,9 +97,10 @@ module Funicular
               unmount_component(old_vnode)
               parent_el = target.parentElement
               parent_el.removeChild(target) if parent_el
+              snapshot[old_index] = nil
             end
 
-            # Phase 2: updates against the snapshot (no movement)
+            # Phase 2: updates against the snapshot
             ops.each do |op|
               next unless op[0] == :keep
               old_index = op[1]
@@ -98,31 +108,45 @@ module Funicular
               next if child_patches.empty?
               target = snapshot[old_index]
               next if target.nil?
-              apply(target, child_patches)
+              snapshot[old_index] = apply(target, child_patches)
             end
 
-            # Phase 3: inserts in ascending new_index order
+            # Phase 3: moves and inserts in ascending new_index order.
+            # `live` mirrors the DOM child order after phases 1 and 2 and is
+            # updated alongside every DOM mutation, so a node already sitting
+            # at new_index is left untouched (no detach/re-attach).
+            live = snapshot.compact #: Array[untyped]
             ops.each do |op|
-              next unless op[0] == :insert
-              new_index = op[1]
-              new_vnode = op[2]
-              new_node = create_element(new_vnode)
+              case op[0]
+              when :keep
+                new_node = snapshot[op[1]]
+                new_index = op[2]
+              when :insert
+                new_index = op[1]
+                new_node = create_element(op[2])
+              else
+                next
+              end
               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)
+              current = live[new_index]
+              next if current.equal?(new_node)
+              live.delete_if { |n| n.equal?(new_node) }
+              if new_index < live.length
+                live.insert(new_index, new_node)
               else
-                element.insertBefore(new_node, ref) if element.is_a?(JS::Element)
+                live << new_node
+              end
+              next unless element.is_a?(JS::Element)
+              if current.nil?
+                element.appendChild(new_node)
+              else
+                element.insertBefore(new_node, current)
               end
             end
           when Integer
             child_index = patch[0]
             child_patches = patch[1]
-            # Use childNodes instead of children to include text nodes
-            child_nodes = element[:childNodes]
-            children = child_nodes.is_a?(JS::Object) ? child_nodes.to_a : [] #: Array[JS::Object]
+            children = child_nodes_array(element)
             child_element = children[child_index]
             if child_element.nil?
               # No existing child at this index - we need to create new elements
@@ -150,6 +174,14 @@ module Funicular
 
       private
 
+      # childNodes (not children) so that text nodes are included. Each call
+      # crosses the wasm boundary once per child, so callers should read it
+      # once and work on the returned array.
+      def child_nodes_array(element)
+        child_nodes = element[:childNodes]
+        child_nodes.is_a?(JS::Object) ? child_nodes.to_a : [] #: Array[untyped]
+      end
+
       def unmount_component(vnode)
         return unless vnode.is_a?(VDOM::Component) && vnode.instance
         vnode.instance.unmount

data/mrblib/relation.rb

@@ -0,0 +1,342 @@
+# A lazy, chainable query over one local table (docs/local_database.md,
+# "Querying"). Chain builders (where/order/limit/offset) each return a NEW
+# Relation; SQL executes once, in a materializer.
+#
+# The `model` handed to the constructor is the query's metadata + row
+# factory. Relation calls exactly these methods on it:
+#
+#   table_name          -> String
+#   local_columns       -> Hash[String => Symbol]  (column name -> declared type)
+#   local_db            -> handle responding to execute(sql, binds) -> rows
+#   replica?            -> bool (delete_all guard)
+#   build_from_local    -> (Hash) -> model instance (attrs already decoded)
+#   local_table_changed -> void; called after a framework-managed write
+#                          (delete_all here) so the model can fire change
+#                          events and schedule snapshot persistence
+#
+# Identifiers in hash conditions and order() are validated against
+# local_columns and double-quoted; values cross into SQL through
+# Funicular::DB::Codec. Raw SQL fragments pass through untouched, their
+# binds encoded by value (Codec.encode_bind).
+
+module Funicular
+  class Relation
+    # The trailing arguments are internal: chain builders use them to spawn
+    # derived relations. Application code passes only `model`.
+    def initialize(model, where_sql = [], where_binds = [], order_sql = [],
+                   limit = nil, offset = nil)
+      @model = model
+      @where_sql = where_sql
+      @where_binds = where_binds
+      @order_sql = order_sql
+      @limit = limit
+      @offset = offset
+    end
+
+    # ---- chain builders --------------------------------------------------
+
+    # where(title: "x")              equality (nil -> IS NULL)
+    # where(id: [1, 2])              IN (empty array -> WHERE 1=0)
+    # where(id: 1..9)                BETWEEN (exclusive end -> >= AND <)
+    # where("title LIKE ?", "a%")    raw fragment with placeholders
+    # Multiple where calls AND together.
+    def where(conditions = nil, *binds)
+      w = @where_sql.dup
+      b = @where_binds.dup
+      if conditions.is_a?(Hash)
+        keys = conditions.keys
+        i = 0
+        while i < keys.size
+          append_condition(w, b, keys[i], conditions[keys[i]])
+          i += 1
+        end
+      elsif conditions.is_a?(String)
+        w << "(#{conditions})"
+        i = 0
+        while i < binds.size
+          b << Funicular::DB::Codec.encode_bind(binds[i])
+          i += 1
+        end
+      else
+        raise ArgumentError,
+          "where expects a Hash or a SQL fragment String, got #{conditions.inspect}"
+      end
+      Relation.new(@model, w, b, @order_sql, @limit, @offset)
+    end
+
+    # order(:created_at)                 ASC
+    # order(created_at: :desc)
+    # order(:pinned, created_at: :desc)  multiple keys
+    def order(*args)
+      if args.empty?
+        raise ArgumentError, "order requires at least one column"
+      end
+      o = @order_sql.dup
+      i = 0
+      while i < args.size
+        arg = args[i]
+        if arg.is_a?(Hash)
+          keys = arg.keys
+          j = 0
+          while j < keys.size
+            o << order_term(keys[j], arg[keys[j]])
+            j += 1
+          end
+        else
+          o << order_term(arg, :asc)
+        end
+        i += 1
+      end
+      Relation.new(@model, @where_sql, @where_binds, o, @limit, @offset)
+    end
+
+    def limit(n)
+      Relation.new(@model, @where_sql, @where_binds, @order_sql,
+                   slice_arg(n, "limit"), @offset)
+    end
+
+    def offset(n)
+      Relation.new(@model, @where_sql, @where_binds, @order_sql,
+                   @limit, slice_arg(n, "offset"))
+    end
+
+    # ---- materializers ---------------------------------------------------
+
+    def to_a
+      rows = @model.local_db.execute(select_sql, @where_binds)
+      cols = @model.local_columns.keys
+      # @type var out: Array[untyped]
+      out = []
+      i = 0
+      while i < rows.size
+        out << @model.build_from_local(decode_row(cols, rows[i]))
+        i += 1
+      end
+      out
+    end
+
+    def each
+      list = to_a
+      i = 0
+      while i < list.size
+        yield list[i]
+        i += 1
+      end
+      list
+    end
+
+    # Instance or nil. Narrows the window to one row (never widens: a
+    # relation already limited to 0 stays empty).
+    def first
+      lim = @limit
+      lim = (lim.nil? || 1 <= lim) ? 1 : lim
+      Relation.new(@model, @where_sql, @where_binds, @order_sql,
+                   lim, @offset).to_a[0]
+    end
+
+    # SELECT COUNT(*); on a limited/offset relation it counts the window
+    # (COUNT over a subquery), matching ActiveRecord.
+    def count
+      sql = if @limit || @offset
+        "SELECT COUNT(*) FROM (#{select_sql})"
+      else
+        "SELECT COUNT(*) FROM #{quoted_table}#{where_clause}"
+      end
+      single_value(sql)
+    end
+
+    def exists?
+      if @limit || @offset
+        0 < count
+      else
+        sql = "SELECT 1 FROM #{quoted_table}#{where_clause} LIMIT 1"
+        !@model.local_db.execute(sql, @where_binds).empty?
+      end
+    end
+
+    def find(id)
+      record = find_by(id: id)
+      unless record
+        raise Funicular::RecordNotFound,
+          "Couldn't find #{model_label} with id=#{id}"
+      end
+      record
+    end
+
+    def find_by(conditions)
+      where(conditions).first
+    end
+
+    # Bulk delete, `storage :local` models only; returns the number of
+    # deleted rows. Raises on a relation carrying order/limit/offset (say
+    # what you mean with a plain condition).
+    def delete_all
+      if @model.replica?
+        raise Funicular::DB::ReplicaWriteError,
+          "delete_all is not available on replica models; the server owns " \
+          "replica rows (deletions reach the replica through destroy)"
+      end
+      if @limit || @offset || !@order_sql.empty?
+        raise ArgumentError,
+          "delete_all does not support order/limit/offset"
+      end
+      # RETURNING counts the deletions inside the one statement; reading
+      # SELECT changes() afterwards would race other Tasks writing on the
+      # same connection between the two calls.
+      rows = @model.local_db.execute(
+        "DELETE FROM #{quoted_table}#{where_clause} RETURNING \"id\"",
+        @where_binds)
+      count = rows.size
+      # Framework-managed writes must notify (docs, "Querying"); a delete
+      # that removed nothing changed nothing.
+      @model.local_table_changed if 0 < count
+      count
+    end
+
+    # The SELECT this relation will run (debugging aid; binds not inlined).
+    def to_sql
+      select_sql
+    end
+
+    # Internal (Component#watch): where change events for this
+    # relation's rows come from, as [role, table].
+    def __event_source
+      m = @model
+      [m.replica? ? :replica : :local, m.table_name]
+    end
+
+    # ---- internal --------------------------------------------------------
+
+    private
+
+    def append_condition(w, b, col, value)
+      name = validate_column(col)
+      q = quote(name)
+      type = @model.local_columns[name]
+      codec = Funicular::DB::Codec
+      if value.nil?
+        w << "#{q} IS NULL"
+      elsif value.is_a?(Array)
+        if value.empty?
+          w << "1=0"
+        else
+          # @type var marks: Array[String]
+          marks = []
+          i = 0
+          while i < value.size
+            marks << "?"
+            b << codec.encode(type, value[i])
+            i += 1
+          end
+          w << "#{q} IN (#{marks.join(", ")})"
+        end
+      elsif value.is_a?(Range)
+        b << codec.encode(type, value.begin)
+        b << codec.encode(type, value.end)
+        if value.exclude_end?
+          w << "(#{q} >= ? AND #{q} < ?)"
+        else
+          w << "#{q} BETWEEN ? AND ?"
+        end
+      else
+        w << "#{q} = ?"
+        b << codec.encode(type, value)
+      end
+    end
+
+    def order_term(col, dir)
+      d = dir.to_s.downcase
+      unless d == "asc" || d == "desc"
+        raise ArgumentError,
+          "order direction must be :asc or :desc, got #{dir.inspect}"
+      end
+      "#{quote(validate_column(col))} #{d == "asc" ? "ASC" : "DESC"}"
+    end
+
+    def validate_column(col)
+      name = col.to_s
+      unless @model.local_columns.has_key?(name)
+        raise ArgumentError,
+          "unknown column #{name.inspect} for table \"#{@model.table_name}\""
+      end
+      name
+    end
+
+    def quote(name)
+      "\"#{name}\""
+    end
+
+    def quoted_table
+      quote(@model.table_name)
+    end
+
+    def select_sql
+      cols = @model.local_columns.keys
+      # @type var quoted: Array[String]
+      quoted = []
+      i = 0
+      while i < cols.size
+        quoted << quote(cols[i])
+        i += 1
+      end
+      "SELECT #{quoted.join(", ")} FROM #{quoted_table}" \
+        "#{where_clause}#{order_clause}#{slice_clause}"
+    end
+
+    def where_clause
+      w = @where_sql
+      w.empty? ? "" : " WHERE #{w.join(" AND ")}"
+    end
+
+    def order_clause
+      o = @order_sql
+      o.empty? ? "" : " ORDER BY #{o.join(", ")}"
+    end
+
+    # LIMIT -1 OFFSET n is how SQLite spells offset-without-limit.
+    def slice_clause
+      lim = @limit
+      off = @offset
+      if lim
+        off ? " LIMIT #{lim} OFFSET #{off}" : " LIMIT #{lim}"
+      elsif off
+        " LIMIT -1 OFFSET #{off}"
+      else
+        ""
+      end
+    end
+
+    def slice_arg(n, label)
+      return nil if n.nil?
+      unless n.is_a?(Integer) && 0 <= n
+        raise ArgumentError, "#{label} must be a non-negative Integer, got #{n.inspect}"
+      end
+      n
+    end
+
+    def decode_row(cols, row)
+      codec = Funicular::DB::Codec
+      columns = @model.local_columns
+      # @type var attrs: Hash[String, untyped]
+      attrs = {}
+      i = 0
+      while i < cols.size
+        name = cols[i]
+        raw = row.is_a?(Hash) ? row[name] : row[i]
+        attrs[name] = codec.decode(columns[name], raw)
+        i += 1
+      end
+      attrs
+    end
+
+    def single_value(sql)
+      row = @model.local_db.execute(sql, @where_binds)[0]
+      row.is_a?(Hash) ? row.values[0] : row[0]
+    end
+
+    def model_label
+      m = @model
+      m.respond_to?(:name) ? m.name : m.table_name
+    end
+  end
+end

data/mrblib/router.rb

@@ -9,6 +9,7 @@ module Funicular
       @current_component = nil
       @current_path = nil
       @popstate_callback_id = nil
+      @beforeunload_callback_id = nil
       @url_helpers = Module.new
       @route_helpers = Object.new
       @route_helpers.extend(@url_helpers)
@@ -62,15 +63,38 @@ module Funicular
 
       @hydrate_initial = hydrate
 
-      # Clean up existing listener if any (prevents duplicate registration)
+      # Clean up existing listeners if any (prevents duplicate registration)
       if @popstate_callback_id
         JS::Object.removeEventListener(@popstate_callback_id)
         @popstate_callback_id = nil
       end
+      if @beforeunload_callback_id
+        JS::Object.removeEventListener(@beforeunload_callback_id)
+        @beforeunload_callback_id = nil
+      end
 
-      # Set up popstate listener
+      # Set up popstate listener. The history entry has already moved by
+      # the time popstate fires; when the current component's navigation
+      # guard vetoes leaving, push the guarded path back (the one thing
+      # popstate cannot cancel).
       @popstate_callback_id = JS.global.addEventListener('popstate') do |event|
-        handle_route_change
+        if leave_allowed?
+          handle_route_change
+        elsif (guarded_path = @current_path)
+          # Local binding: the type checker does not narrow ivars
+          # through elsif.
+          JS.global.history.pushState(JS::Bridge.to_js({}), '', guarded_path)
+        end
+      end
+
+      # Reload / tab close: ask through the browser's native dialog when
+      # a guard is active. sync: the decision must be made on the JS
+      # event dispatch stack, so the guard must not suspend.
+      @beforeunload_callback_id = JS.global.addEventListener('beforeunload', sync: true) do |event|
+        if @current_component&.navigation_guard
+          event.preventDefault
+          event[:returnValue] = ''
+        end
       end
 
       # Handle initial route. Skip the default-route redirect when hydrating
@@ -90,16 +114,33 @@ module Funicular
         @popstate_callback_id = nil
       end
 
+      if @beforeunload_callback_id
+        JS::Object.removeEventListener(@beforeunload_callback_id)
+        @beforeunload_callback_id = nil
+      end
+
       unmount_current_component
     end
 
-    # Navigate to a path programmatically using History API
+    # Navigate to a path programmatically using History API. A vetoing
+    # navigation guard on the current component cancels the navigation
+    # before any history change.
     def navigate(path)
+      return unless leave_allowed?
       JS.global.history.pushState(JS::Bridge.to_js({}), '', path)
       # Manually trigger route change because pushState doesn't fire popstate
       handle_route_change
     end
 
+    # Ask the current component's navigation guard whether leaving is
+    # allowed; a String from the guard prompts the user via
+    # Funicular.confirm. True when no component or no guard.
+    def leave_allowed?
+      message = @current_component&.navigation_guard
+      return true unless message
+      Funicular.confirm(message)
+    end
+
     # Get current path from location
     def current_location_path
       js_path_obj = JS.global.location.pathname

data/mrblib/styles.rb

@@ -20,6 +20,26 @@ module Funicular
       end
     end
 
+    # String-like concatenation: styles.field + " col-span-2". No space
+    # is inserted and non-String operands raise TypeError, matching
+    # String#+ (a silent to_s would hide mistakes like `+ 123`); use |
+    # to join with a space.
+    # to_str is deliberately not defined: the mruby client's String#+
+    # never coerces (no implicit to_str call), so defining it on CRuby
+    # would let SSR accept "base " + styles.field while the browser
+    # raises. Both VMs reject the reversed form the same way instead.
+    def +(other)
+      case other
+      when StyleValue
+        StyleValue.new(@value + other.value)
+      when String
+        StyleValue.new(@value + other)
+      else
+        other = other #: untyped
+        raise TypeError, "no implicit conversion of #{other.class} into String"
+      end
+    end
+
     def to_s
       @value
     end

data/mrblib/vdom.rb

@@ -100,6 +100,11 @@ module Funicular
         @children = normalize_children(children || [])
       end
 
+      def ==(other)
+        return false unless other.is_a?(Element)
+        @tag == other.tag && @props == other.props && @children == other.children
+      end
+
       private
 
       def normalize_children(children)
@@ -124,11 +129,6 @@ module Funicular
         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

data/mrblib/version.rb

@@ -0,0 +1,11 @@
+# Single source of truth for the Funicular version.
+#
+# This file lives in mrblib so that it is compiled into PicoRuby.wasm along
+# with the rest of the runtime. The CRuby gem reuses it via
+# lib/funicular/version.rb, so the version is defined in exactly one place.
+#
+# Keep this file free of any dependency: it must evaluate standalone in
+# both PicoRuby and CRuby, regardless of load order.
+module Funicular
+  VERSION = '0.5.1'
+end

data/sig/component.rbs

@@ -47,6 +47,11 @@ module Funicular
     def initialize_state: () -> Hash[Symbol, untyped]
     def seed_state: (Hash[untyped, untyped]? state_hash) -> self
 
+    @__watches: Hash[Symbol, Integer]?
+    def watch: (Symbol key) { () -> untyped } -> nil
+    def evaluate_watch: (Symbol key, untyped block) -> nil
+    def cleanup_watches: () -> nil
+
     def load_suspense_data: () -> void
     def load_single_suspense: (Symbol name, ?suspense_definition? definition) -> void
     def reload_suspense: (Symbol name) -> void
@@ -55,6 +60,7 @@ module Funicular
     def suspense_error: (Symbol name) -> untyped
     def render_suspense: (Symbol name, fallback: untyped, ?error: untyped) { (ResourceAccessor) -> untyped } -> untyped
 
+    def navigation_guard: () -> String?
     def patch: (Hash[Symbol, untyped] new_state) -> void
     def mount: (JS::Element container) -> void
     def hydrate: (JS::Element dom_element) -> void
@@ -63,6 +69,7 @@ module Funicular
     def build_vdom: () -> (VDOM::VNode | VDOM::Text | nil)
 
     def bind_events: (JS::Element dom_element, VDOM::VNode | VDOM::Text | nil vnode) -> void
+    def report_handler_error: (String event_name, String handler, StandardError error) -> void
     def collect_refs: (JS::Element dom_element, VDOM::VNode | VDOM::Text | nil vnode, ?Hash[Symbol, JS::Element] refs_map) -> Hash[Symbol, JS::Element]
     def normalize_vnode_for_view: (untyped value) -> (VDOM::Element | VDOM::Text | VDOM::Component | nil)
     def __view__: () -> ViewContext