funicular 0.3.0 → 0.5.0

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,30 +20,67 @@ 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
   end
 
-  class StyleAccessor
+  # Read-side accessor. One subclass is generated per component class with a
+  # real method per declared style name (see accessor_for), so lookups never
+  # go through method_missing at render time and a typo raises loudly.
+  # BasicObject keeps Object/Kernel names (display, hash, ...) usable as
+  # style names on both mruby and CRuby.
+  class StyleAccessor < BasicObject
+    def self.accessor_for(definitions)
+      klass = ::Class.new(self) #: singleton(StyleAccessor)
+      definitions.each_key do |name|
+        klass.__send__(:define_method, name) do |variant = nil|
+          self[name, variant] # steep:ignore
+        end
+      end
+      klass
+    end
+
     def initialize(definitions)
       @definitions = definitions
     end
 
     def [](name, variant = nil)
       style = @definitions[name]
-      return StyleValue.new("") unless style
+      unless style
+        ::Kernel.raise ::ArgumentError,
+          "unknown style :#{name} (declared: #{@definitions.keys.map { |k| ":#{k}" }.join(', ')})"
+      end
 
       if variant.nil?
         # No arguments: return base or value
         StyleValue.new(style[:base] || style[:value] || "")
       elsif variant == true || variant == false
         # Boolean argument: base + active (if true)
-        # JS::Object#== now supports direct comparison with Ruby true/false
         base = style[:base] || ""
         active_class = (variant == true) ? (style[:active] || "") : ""
         StyleValue.new("#{base} #{active_class}".strip)
-      elsif variant.is_a?(Symbol)
+      elsif ::Symbol === variant
         # Symbol argument: base + variants[symbol]
         base = style[:base] || ""
         variant_class = style[:variants] ? (style[:variants][variant] || "") : ""
@@ -53,27 +90,100 @@ module Funicular
         StyleValue.new(style[:base] || style[:value] || "")
       end
     end
+
+    def method_missing(name, *_args)
+      ::Kernel.raise ::NoMethodError,
+        "unknown style '#{name}' (declared: #{@definitions.keys.map { |k| ":#{k}" }.join(', ')})"
+    end
+
+    def respond_to_missing?(name, _include_private = false)
+      @definitions.key?(name)
+    end
   end
 
-  class StyleBuilder
+  # Definition-side builder. The class-level `styles do ... end` block is
+  # instance_exec'd on an instance, so barewords define styles:
+  #
+  #   styles do
+  #     shell "app-shell"
+  #     button base: "btn", variants: { primary: "btn--primary" }
+  #   end
+  #
+  # BasicObject keeps the bareword namespace clean on both VMs; the block
+  # also receives the builder as an argument for the explicit form
+  # `styles { |css| css.define(:name, ...) }`, needed when a value is
+  # computed (a bareword helper call inside the block would be captured as
+  # a style definition, and its nil return raises via validation below).
+  class StyleBuilder < BasicObject
+    # Style names that would clobber the builder/accessor internals.
+    RESERVED_NAMES = %i[
+      initialize method_missing respond_to_missing? define to_definitions
+      validate_options
+      == != ! [] equal? __send__ __id__ instance_eval instance_exec
+    ]
+
     def initialize
-      @definitions = {}
+      @definitions = {} #: Hash[Symbol, untyped]
     end
 
     def define(name, value = nil, **options)
-      if value.is_a?(String)
+      if RESERVED_NAMES.include?(name)
+        ::Kernel.raise ::ArgumentError, "style name :#{name} is reserved"
+      end
+      if @definitions.key?(name)
+        ::Kernel.raise ::ArgumentError, "style :#{name} is already defined"
+      end
+
+      if ::String === value
         @definitions[name] = { value: value }
-      elsif value.is_a?(Hash)
-        @definitions[name] = value
-      elsif !options.empty?
-        @definitions[name] = options
+      elsif ::Hash === value
+        @definitions[name] = validate_options(name, value)
+      elsif (::NilClass === value) && !options.empty?
+        @definitions[name] = validate_options(name, options)
       else
-        raise ArgumentError, "Invalid style definition for #{name}"
+        ::Kernel.raise ::ArgumentError,
+          "invalid style definition for :#{name}; expected a String, a " \
+          "Hash, or keyword options. Note: helper methods cannot be called " \
+          "bareword inside a styles block; use " \
+          "`styles { |css| css.define(...) }` for computed values."
       end
+      self
+    end
+
+    def validate_options(name, options)
+      options.each do |key, val|
+        case key
+        when :value, :base, :active
+          unless ::String === val
+            ::Kernel.raise ::ArgumentError,
+              "style :#{name} option #{key}: must be a String. Note: helper " \
+              "methods cannot be called bareword inside a styles block; use " \
+              "`styles { |css| css.define(...) }` for computed values."
+          end
+        when :variants
+          unless (::Hash === val) && val.all? { |_k, v| ::String === v }
+            ::Kernel.raise ::ArgumentError,
+              "style :#{name} option variants: must be a Hash of Symbol => String"
+          end
+        else
+          ::Kernel.raise ::ArgumentError,
+            "style :#{name} has unknown option #{key.inspect} " \
+            "(allowed: value, base, active, variants)"
+        end
+      end
+      options
     end
 
     def to_definitions
       @definitions
     end
+
+    def method_missing(name, value = nil, **options)
+      define(name, value, **options)
+    end
+
+    def respond_to_missing?(_name, _include_private = false)
+      true
+    end
   end
 end

data/mrblib/view_context.rb

@@ -1,40 +1,11 @@
 module Funicular
   class ViewContext
-    HTML_TAGS = %w[
-      div span p a data
-      h1 h2 h3 h4 h5 h6
-      ul ol li
-      table thead tbody tr th td
-      form input textarea button select option label
-      header footer nav section article aside
-      img video audio canvas
-      br hr
-    ]
+    HTML_TAGS = Funicular::Tags::HTML_TAGS
 
     def initialize(component)
       @component = component
     end
 
-    def state
-      @component.state
-    end
-
-    def props
-      @component.props
-    end
-
-    def resources
-      @component.resources
-    end
-
-    def styles
-      @component.styles
-    end
-
-    def routes
-      @component.runtime.routes
-    end
-
     def tag(name, props = {}, &block)
       build_element(name, props, &block)
     end
@@ -66,7 +37,7 @@ module Funicular
     end
 
     def suspense(name, fallback:, error: nil, &block)
-      @component.render_suspense(self, name, fallback: fallback, error: error, &block)
+      @component.render_suspense(name, fallback: fallback, error: error, &block)
     end
 
     def link_to(path, **options, &block)
@@ -81,7 +52,7 @@ module Funicular
       children = [] #: Array[Funicular::VDOM::child_t]
       previous = @component.current_children
       @component.current_children = children
-      result = block.call(self)
+      result = block.call
       @component.current_children = previous
 
       if result && !result.equal?(children) && children.empty?