stimulus_grid_rails 0.1.0

data/lib/stimulus_grid_rails/column.rb

@@ -0,0 +1,239 @@
+module StimulusGridRails
+  # One column on a Grid. Captures everything the server needs to authorise,
+  # coerce, validate, and broadcast changes for this field — plus everything
+  # the client needs to choose an editor and render a cell.
+  #
+  # Created via the `column` DSL inside an ApplicationGrid subclass; not
+  # instantiated directly. See StimulusGridRails::Grid for usage.
+  class Column
+    TYPES = %i[string text integer bigint decimal money boolean enum date datetime reference].freeze
+
+    attr_reader :name, :type, :editor, :editor_config, :enum_values, :concurrency,
+                :depends_on, :validators, :header, :width, :pinned, :cell_renderer,
+                :cell_editor
+
+    def initialize(name, type:, editable: false, editor: nil, editor_config: {},
+                   enum_values: nil, concurrency: :last_write_wins,
+                   computed: false, depends_on: [], validate: nil,
+                   header: nil, width: nil, pinned: nil, cell_renderer: nil,
+                   cell_editor: nil, sortable: true, filterable: true, searchable: nil)
+      raise ArgumentError, "Unknown column type #{type.inspect}" unless TYPES.include?(type)
+      @name          = name.to_sym
+      @type          = type
+      @editable      = editable                       # may be `true`, `false`, or a Proc(row, user)
+      @editor        = editor || default_editor_for(type)
+      @editor_config = editor_config
+      @enum_values   = enum_values
+      @concurrency   = concurrency
+      @computed      = computed
+      @depends_on    = Array(depends_on)
+      @validators    = Array(validate)
+      @header        = header || name.to_s.humanize
+      @width         = width
+      @pinned        = pinned
+      @cell_renderer = cell_renderer
+      @cell_editor   = cell_editor
+      @sortable      = sortable
+      @filterable    = filterable
+      # Global search defaults to text-ish columns; numeric/date/boolean opt in.
+      @searchable    = searchable.nil? ? %i[string text enum reference].include?(type) : searchable
+    end
+
+    # Per-row, per-user editable check. RAILS.md §17 — server re-evaluates on
+    # every PATCH (never trust the client's data-editable attribute).
+    def editable_for?(row, user)
+      case @editable
+      when true, false then @editable
+      when Proc then !!@editable.call(row, user)
+      else !!@editable
+      end
+    end
+
+    def editable_static?
+      @editable == true
+    end
+
+    def computed?  = @computed
+    def cascades?  = !@depends_on.empty?
+
+    # Coerce a string value (from a form submission) to this column's Ruby type.
+    # Returns [value, error] — error is a string if coercion failed.
+    def coerce(raw)
+      case @type
+      when :string, :text, :enum, :reference then [raw.to_s, nil]
+      when :integer, :bigint
+        Integer(raw.to_s, 10).then { |i| [i, nil] }
+      when :decimal, :money
+        [BigDecimal(raw.to_s), nil]
+      when :boolean
+        [%w[1 true yes on t].include?(raw.to_s.downcase), nil]
+      when :date
+        [Date.parse(raw.to_s), nil]
+      when :datetime
+        [Time.zone.parse(raw.to_s), nil]
+      else
+        [raw, nil]
+      end
+    rescue ArgumentError, TypeError => e
+      [nil, "invalid #{@type}: #{e.message}"]
+    end
+
+    def searchable? = @searchable && !@computed && !name.to_s.start_with?("_")
+
+    # Arel predicate for the global search term, or nil if this column doesn't
+    # participate. Case-insensitive contains over the column's text. Computed
+    # and action columns never match (no DB column to query).
+    def search_predicate(arel_table, term)
+      return nil unless searchable?
+      pattern = "%#{like_escape(term.to_s.downcase)}%"
+      arel_table[@name].lower.matches(pattern)
+    end
+
+    # Arel predicate for a per-column filter. `criteria` mirrors the client
+    # filterModel shape: { "type" => op, "value" => v, "value2" => v2 }.
+    # Returns nil for computed/unknown columns or unparseable values.
+    def filter_predicate(arel_table, criteria)
+      return nil if @computed || name.to_s.start_with?("_")
+      col = arel_table[@name]
+      op  = (criteria["type"] || criteria[:type]).to_s
+      raw = criteria["value"]  || criteria[:value]
+      raw2 = criteria["value2"] || criteria[:value2]
+
+      case @type
+      when :string, :text, :enum, :reference
+        text_predicate(col, op, raw.to_s)
+      when :integer, :bigint, :decimal, :money
+        numeric_predicate(col, op, raw, raw2)
+      when :date, :datetime
+        date_predicate(col, op, raw, raw2)
+      when :boolean
+        v, err = coerce(raw)
+        err ? nil : col.eq(v)
+      end
+    end
+
+    # Run client-defined validators. Returns Array of error strings.
+    def validate(value, row)
+      @validators.flat_map do |v|
+        result = v.call(value, row)
+        case result
+        when nil, true then []
+        when String    then [result]
+        when Array     then result
+        else [result.to_s]
+        end
+      end
+    end
+
+    # Serialized into the rendered cell's data-* attributes so the client-side
+    # editor controller can mount the right editor with the right config.
+    def client_data_attrs(row, user)
+      attrs = {
+        "data-col-id" => name,
+        "data-editor" => @editor,
+      }
+      attrs["data-editable"] = "true" if editable_for?(row, user)
+      attrs["data-enum-values"] = JSON.generate(@enum_values) if @enum_values
+      attrs["data-editor-config"] = JSON.generate(@editor_config) unless @editor_config.empty?
+      attrs
+    end
+
+    # Serialized into the column's <th> so header_cell_controller picks it up.
+    def header_data_attrs
+      {
+        "data-controller" => "header-cell",
+        "data-header-cell-field-value" => name,
+        "data-header-cell-type-value" => header_cell_type,
+        "data-header-cell-sortable-value" => @sortable.to_s,
+        "data-header-cell-filter-value" => (@filterable ? filter_type_for_client : nil),
+        "data-header-cell-editable-value" => editable_static?.to_s,
+        "data-header-cell-pinned-value" => @pinned,
+        "data-header-cell-width-value" => @width,
+        "data-header-cell-cell-renderer-value" => @cell_renderer,
+        "data-header-cell-cell-editor-value" => @cell_editor,
+      }.compact
+    end
+
+    private
+
+    # Escape LIKE wildcards so a literal % or _ in the search term isn't treated
+    # as a pattern. Arel still quotes the value, so this is only about semantics.
+    def like_escape(str)
+      str.gsub(/[\\%_]/) { |c| "\\#{c}" }
+    end
+
+    def text_predicate(col, op, val)
+      lc = col.lower
+      v  = val.downcase
+      case op
+      when "equals"     then lc.eq(v)
+      when "notEqual"   then lc.not_eq(v)
+      when "startsWith" then lc.matches("#{like_escape(v)}%")
+      when "endsWith"   then lc.matches("%#{like_escape(v)}")
+      when "blank"      then col.eq(nil).or(col.eq(""))
+      when "notBlank"   then col.not_eq(nil).and(col.not_eq(""))
+      else                   lc.matches("%#{like_escape(v)}%")   # contains (default)
+      end
+    end
+
+    def numeric_predicate(col, op, raw, raw2)
+      v, err = coerce(raw)
+      return nil if err
+      case op
+      when "greaterThan"        then col.gt(v)
+      when "greaterThanOrEqual" then col.gteq(v)
+      when "lessThan"           then col.lt(v)
+      when "lessThanOrEqual"    then col.lteq(v)
+      when "notEqual"           then col.not_eq(v)
+      when "inRange"
+        v2, e2 = coerce(raw2)
+        e2 ? col.gteq(v) : col.between(v..v2)
+      else col.eq(v)
+      end
+    end
+
+    def date_predicate(col, op, raw, raw2)
+      v, err = coerce(raw)
+      return nil if err
+      case op
+      when "greaterThan" then col.gt(v)
+      when "lessThan"    then col.lt(v)
+      when "notEqual"    then col.not_eq(v)
+      when "inRange"
+        v2, e2 = coerce(raw2)
+        e2 ? col.gteq(v) : col.between(v..v2)
+      else col.eq(v)
+      end
+    end
+
+    def default_editor_for(t)
+      case t
+      when :string, :text, :reference then "text"
+      when :integer, :bigint, :decimal, :money then "number"
+      when :boolean                   then "checkbox"
+      when :enum                      then "select"
+      when :date                      then "date"
+      when :datetime                  then "datetime-local"
+      else "text"
+      end
+    end
+
+    def header_cell_type
+      case @type
+      when :integer, :bigint, :decimal, :money then "number"
+      when :date, :datetime           then "date"
+      when :boolean                   then "boolean"
+      else "text"
+      end
+    end
+
+    def filter_type_for_client
+      case @type
+      when :integer, :bigint, :decimal, :money then "number"
+      when :date, :datetime           then "date"
+      when :boolean                   then "boolean"
+      else "text"
+      end
+    end
+  end
+end

data/lib/stimulus_grid_rails/concerns/broadcastable.rb

@@ -0,0 +1,91 @@
+require "active_support/concern"
+
+module StimulusGridRails
+  # Mixin for Active Record models backing a grid. Once included and wired with
+  # `broadcasts_grid`, every create / update / destroy AUTOMATICALLY broadcasts
+  # the right Turbo Stream action to the grid's tenant-scoped stream — no manual
+  # broadcast calls anywhere:
+  #
+  #   create  → row-insert-sorted   (the full row as JSON)
+  #   update  → cell                (each changed registered column + any
+  #                                   computed column whose deps changed)
+  #   destroy → row-remove
+  #
+  # Usage:
+  #
+  #     class Athlete < ApplicationRecord
+  #       include StimulusGridRails::Broadcastable
+  #       broadcasts_grid AthleteGrid
+  #     end
+  #
+  # Streams are tenant-scoped via StimulusGridRails.streamables_for, so with
+  # ActsAsTenant a tenant's changes never reach another tenant's subscribers.
+  module Broadcastable
+    extend ActiveSupport::Concern
+
+    included do
+      # Set by the cells controller before a grid-driven save so the broadcast
+      # carries the originating client's optimistic id (RAILS.md §4) and that
+      # client suppresses its own echo. nil for changes made outside the grid
+      # (console, jobs) — those broadcast to everyone with no suppression.
+      attr_accessor :_sgr_optimistic_id
+    end
+
+    class_methods do
+      def broadcasts_grid(grid_class)
+        @stimulus_grid_class = grid_class
+        after_create_commit  { stimulus_grid_broadcast_insert }
+        after_update_commit  { stimulus_grid_broadcast_changes }
+        after_destroy_commit { stimulus_grid_broadcast_remove }
+      end
+
+      def stimulus_grid_class
+        @stimulus_grid_class
+      end
+    end
+
+    def stimulus_grid_streamables
+      StimulusGridRails.streamables_for(self.class.stimulus_grid_class.resource_name)
+    end
+
+    def stimulus_grid_broadcast_insert
+      grid = self.class.stimulus_grid_class.new
+      message = StimulusGridRails::TurboStreams.row_insert_sorted(
+        grid: grid.class.resource_name, row_id: id, payload: grid.row_to_json(self),
+      )
+      stimulus_grid_broadcast(message)
+    end
+
+    def stimulus_grid_broadcast_changes
+      grid_class = self.class.stimulus_grid_class
+      grid       = grid_class.new
+      registry   = grid_class.columns_registry || {}
+      changed    = previous_changes.keys.map(&:to_sym)
+
+      direct   = registry.values.select { |c| !c.computed? && !c.name.to_s.start_with?("_") && changed.include?(c.name) }
+      computed = registry.values.select { |c| c.computed? && (c.depends_on & changed).any? }
+
+      (direct + computed).each do |col|
+        message = StimulusGridRails::TurboStreams.cell(
+          grid: grid_class.resource_name, row_id: id, column: col.name,
+          value: grid.cell_value(self, col), optimistic_id: _sgr_optimistic_id,
+        )
+        stimulus_grid_broadcast(message)
+      end
+    end
+
+    def stimulus_grid_broadcast_remove
+      grid_class = self.class.stimulus_grid_class
+      message = StimulusGridRails::TurboStreams.row_remove(
+        grid: grid_class.resource_name, row_id: id,
+      )
+      stimulus_grid_broadcast(message)
+    end
+
+    private
+
+    def stimulus_grid_broadcast(message)
+      ::Turbo::StreamsChannel.broadcast_stream_to(*stimulus_grid_streamables, content: message)
+    end
+  end
+end

data/lib/stimulus_grid_rails/engine.rb

@@ -0,0 +1,39 @@
+require "rails/engine"
+require "turbo-rails"
+require "stimulus-rails"
+require "importmap-rails"
+
+module StimulusGridRails
+  class Engine < ::Rails::Engine
+    isolate_namespace StimulusGridRails
+
+    # Precompile the gem-shipped JS so the asset pipeline finds it.
+    initializer "stimulus_grid_rails.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.precompile += %w[
+          stimulus_grid.js
+          stimulus_grid_rails.js
+          stimulus_grid.css
+          stimulus_grid_rails.css
+        ]
+      end
+    end
+
+    # Make the gem's importmap manifest available to host apps.
+    # The host app's bin/importmap.rb is *augmented* with our pins below; users
+    # don't need to add `pin "stimulus_grid", ...` themselves.
+    initializer "stimulus_grid_rails.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << Engine.root.join("app/assets/javascripts")
+      end
+    end
+
+    # Make the gem's view partials resolvable from host apps.
+    initializer "stimulus_grid_rails.view_paths" do |app|
+      ActiveSupport.on_load(:action_controller) do
+        append_view_path StimulusGridRails::Engine.root.join("app/views")
+      end
+    end
+  end
+end

data/lib/stimulus_grid_rails/grid.rb

@@ -0,0 +1,221 @@
+require "bigdecimal"
+require "json"
+
+module StimulusGridRails
+  # Base class for declaring a server-side grid. RAILS.md §7 — one source of
+  # truth per resource. All editor selection, auth, coercion, validation,
+  # broadcasting flows through here.
+  #
+  # Subclass and declare:
+  #
+  #   class AthleteGrid < StimulusGridRails::Grid
+  #     resource :athletes
+  #     model    Athlete
+  #
+  #     column :athlete,  type: :string,  editable: true, width: 200, pinned: :left
+  #     column :country,  type: :string,  editable: ->(row, user) { user.admin? }
+  #     column :age,      type: :integer, editable: true, validate: ->(v, _r) { "must be > 0" if v <= 0 }
+  #     column :sport,    type: :enum,    editable: true, enum_values: %w[Swimming Cycling Gymnastics]
+  #     column :date,     type: :date,    editable: true
+  #     column :gold,     type: :integer, editable: true
+  #     column :silver,   type: :integer, editable: true
+  #     column :bronze,   type: :integer, editable: true
+  #     column :total,    type: :integer, computed: true, depends_on: %i[gold silver bronze]
+  #
+  #     def compute_total(row) = row.gold + row.silver + row.bronze
+  #   end
+  class Grid
+    class << self
+      attr_reader :resource_name, :model_class, :columns_registry
+
+      def resource(name)
+        @resource_name = name.to_s
+        StimulusGridRails.register_grid(@resource_name, self)
+      end
+
+      def model(klass)
+        @model_class = klass
+      end
+
+      def column(name, **opts)
+        @columns_registry ||= {}
+        @columns_registry[name.to_sym] = Column.new(name, **opts)
+      end
+
+      # Used by the controller after deserializing the URL.
+      def resolve_column!(col_id)
+        column = columns_registry[col_id.to_sym]
+        raise ArgumentError, "Unknown column #{col_id} on #{name}" unless column
+        column
+      end
+    end
+
+    attr_reader :user
+
+    def initialize(user: nil)
+      @user = user
+    end
+
+    def columns
+      self.class.columns_registry.values
+    end
+
+    def visible_columns_for(_row)
+      columns
+    end
+
+    # Called from the controller after a successful coercion + permission check.
+    # Returns [success?, mutations_to_broadcast] where mutations is an array of
+    # [row_id, col_id, value, opts]. For computed cascade, runs the dependent
+    # column's compute_X methods and includes those too.
+    def apply_cell!(row, column, value)
+      errors = column.validate(value, row)
+      return [false, errors, []] if errors.any?
+
+      old_value = row.send(column.name)
+      row.send("#{column.name}=", value)
+      mutations = [[row_id(row), column.name.to_s, value, {}]]
+
+      # Cascade — recompute every column declared as depending on this one.
+      self.class.columns_registry.each_value do |c|
+        next unless c.computed? && c.depends_on.include?(column.name)
+        compute_method = "compute_#{c.name}"
+        if respond_to?(compute_method)
+          new_val = public_send(compute_method, row)
+          row.send("#{c.name}=", new_val) if row.respond_to?("#{c.name}=")
+          mutations << [row_id(row), c.name.to_s, new_val, {}]
+        end
+      end
+
+      saved = row.respond_to?(:save) ? row.save : true
+      if saved
+        [true, [], mutations]
+      else
+        # Restore old value so the in-memory row doesn't carry the failed write.
+        row.send("#{column.name}=", old_value)
+        [false, Array(row.respond_to?(:errors) ? row.errors.full_messages : ["save failed"]), []]
+      end
+    end
+
+    def row_id(row)
+      row.respond_to?(:id) ? row.id : row[:id]
+    end
+
+    # ----- Row create/destroy support (RAILS.md §14/§15) -----
+
+    # Default attributes for a freshly-created row. Override in subclasses.
+    def new_row_defaults
+      {}
+    end
+
+    # Build (unsaved) a new model instance merging defaults with caller overrides.
+    def build_new_row(overrides = {})
+      attrs = new_row_defaults.merge((overrides || {}).symbolize_keys)
+      self.class.model_class.new(attrs)
+    end
+
+    # Serialize a row to the JSON shape the client grid expects: { id, <col>: <value>, … }
+    # including computed columns. Used as the row-insert-sorted payload.
+    def row_to_h(row)
+      h = { "id" => row_id(row) }
+      self.class.columns_registry.each_value do |col|
+        next if col.name.to_s.start_with?("_")   # skip action/renderer-only columns
+        h[col.name.to_s] = serialize_value(cell_value(row, col), col)
+      end
+      h
+    end
+
+    def row_to_json(row)
+      JSON.generate(row_to_h(row))
+    end
+
+    # ----- Server-side search / filter (RAILS.md §21) -----
+
+    # The base relation a request may see. Override for per-user authorization
+    # scoping (e.g. `model_class.where(team: user.team)`).
+    def scope(_user = user)
+      self.class.model_class.all
+    end
+
+    # Apply a global search term + per-column filters to a relation. `filters`
+    # is { col_name => { "type" =>, "value" =>, "value2" => } } (the client
+    # filterModel shape). Unknown columns and unparseable values are ignored.
+    def search_and_filter(relation, q: nil, filters: {})
+      relation = apply_search(relation, q)
+      relation = apply_filters(relation, filters)
+      relation
+    end
+
+    def apply_search(relation, q)
+      return relation if q.blank?
+      table = self.class.model_class.arel_table
+      preds = columns.filter_map { |c| c.search_predicate(table, q) }
+      return relation if preds.empty?
+      relation.where(preds.reduce(:or))
+    end
+
+    def apply_filters(relation, filters)
+      return relation if filters.blank?
+      table = self.class.model_class.arel_table
+      filters.each do |col_name, criteria|
+        next if criteria.blank?
+        col = self.class.columns_registry[col_name.to_sym]
+        next unless col
+        pred = col.filter_predicate(table, criteria)
+        relation = relation.where(pred) if pred
+      end
+      relation
+    end
+
+    # Server-side sort (RAILS.md §21). `sort_model` is the client shape:
+    # [{ "colId" =>, "sort" => "asc"|"desc" }, …]. Only real (non-computed,
+    # non-underscore) columns that exist on the model are honored.
+    def apply_sort(relation, sort_model)
+      return relation if sort_model.blank?
+      table  = self.class.model_class.arel_table
+      names  = self.class.model_class.column_names
+      orders = Array(sort_model).filter_map do |entry|
+        col_id = (entry["colId"] || entry[:colId]).to_s
+        col    = self.class.columns_registry[col_id.to_sym]
+        next unless col && !col.computed? && !col_id.start_with?("_") && names.include?(col_id)
+        dir = (entry["sort"] || entry[:sort]).to_s.downcase == "desc" ? :desc : :asc
+        table[col_id.to_sym].public_send(dir)
+      end
+      orders.empty? ? relation : relation.reorder(*orders)
+    end
+
+    def cell_value(row, column)
+      if column.computed?
+        method = "compute_#{column.name}"
+        return respond_to?(method) ? public_send(method, row) : nil
+      end
+      row.respond_to?(column.name) ? row.send(column.name) : row[column.name]
+    end
+
+    # Renders the value into the DOM. Override per-column or per-type in
+    # subclasses for richer renderers.
+    def format_cell(row, column)
+      v = cell_value(row, column)
+      case column.type
+      when :money   then ActiveSupport::NumberHelper.number_to_currency(v) rescue v.to_s
+      when :date    then v.respond_to?(:to_date) ? v.to_date.iso8601 : v.to_s
+      when :datetime then v.respond_to?(:iso8601) ? v.iso8601 : v.to_s
+      when :boolean then v ? "✓" : ""
+      else v.to_s
+      end
+    end
+
+    # JSON-friendly value for row_to_h — numbers stay numeric, dates become
+    # ISO strings, everything else stringifies sensibly.
+    def serialize_value(v, column)
+      case column.type
+      when :integer, :bigint then v.to_i
+      when :decimal, :money then v.to_f
+      when :boolean        then !!v
+      when :date           then v.respond_to?(:to_date) ? v.to_date.iso8601 : v
+      when :datetime       then v.respond_to?(:iso8601) ? v.iso8601 : v
+      else v
+      end
+    end
+  end
+end

data/lib/stimulus_grid_rails/turbo_streams_helper.rb

@@ -0,0 +1,105 @@
+module StimulusGridRails
+  # Custom Turbo Stream actions (RAILS.md §1) — generates <turbo-stream> tags
+  # whose `action=` is one of: cell, cell-attr, cell-confirm, cell-revert,
+  # cell-conflict, row-insert-sorted, row-remove, aggregate, bulk.
+  #
+  # The matching client-side StreamActions are registered by
+  # app/assets/javascripts/stimulus_grid_rails.js (registerStreamActions).
+  #
+  # Use directly:
+  #   render turbo_stream: StimulusGridRails::TurboStreams.cell(
+  #     grid: "athletes", row_id: athlete.id, column: :age,
+  #     value: athlete.age, optimistic_id: params[:optimistic_id],
+  #   )
+  module TurboStreams
+    module_function
+
+    # Update one cell — value rendered inline as the cell's textContent.
+    # `optimistic_id` is echoed back so the originating client can suppress
+    # its own broadcast.
+    def cell(grid:, row_id:, column:, value:, optimistic_id: nil)
+      tag("cell", grid: grid, row_id: row_id, column: column,
+                  optimistic_id: optimistic_id) do
+        # Plain HTML — the StreamAction handler reads this as the new cell content.
+        ERB::Util.html_escape(value.to_s)
+      end
+    end
+
+    # Set an attribute on a cell (e.g. data-dirty="false").
+    def cell_attr(grid:, row_id:, column:, attr:, value:)
+      tag("cell-attr", grid: grid, row_id: row_id, column: column,
+                       attr: attr, value: value)
+    end
+
+    # Clear pending/optimistic state on a cell after a successful save.
+    def cell_confirm(grid:, row_id:, column:, value:, optimistic_id:)
+      tag("cell-confirm", grid: grid, row_id: row_id, column: column,
+                          optimistic_id: optimistic_id) do
+        ERB::Util.html_escape(value.to_s)
+      end
+    end
+
+    # Restore prior server value + render inline error.
+    def cell_revert(grid:, row_id:, column:, value:, errors:, optimistic_id:)
+      tag("cell-revert", grid: grid, row_id: row_id, column: column,
+                         optimistic_id: optimistic_id,
+                         errors: errors.to_json) do
+        ERB::Util.html_escape(value.to_s)
+      end
+    end
+
+    # Conflict — server value differs from client base value.
+    def cell_conflict(grid:, row_id:, column:, server_value:, client_value:, optimistic_id:)
+      tag("cell-conflict", grid: grid, row_id: row_id, column: column,
+                           optimistic_id: optimistic_id,
+                           server_value: server_value, client_value: client_value)
+    end
+
+    # Insert a row, respecting the client's current sort order. `payload` is a
+    # JSON row object; it's HTML-escaped here and decoded by the client's
+    # textContent read, so names containing & or < stay valid JSON.
+    def row_insert_sorted(grid:, row_id:, payload:)
+      tag("row-insert-sorted", grid: grid, row_id: row_id) do
+        ERB::Util.html_escape(payload)
+      end
+    end
+
+    # Remove a row by id.
+    def row_remove(grid:, row_id:)
+      tag("row-remove", grid: grid, row_id: row_id)
+    end
+
+    # Update a footer aggregate (sum/avg/count/etc.).
+    def aggregate(grid:, column:, kind:, value:)
+      tag("aggregate", grid: grid, column: column, kind: kind) do
+        ERB::Util.html_escape(value.to_s)
+      end
+    end
+
+    # Atomic batched stream — wraps N inner streams so the client applies them
+    # in a single DOM reflow. Pass an array of already-built turbo-stream
+    # strings (other helpers return strings).
+    def bulk(grid:, streams:)
+      inner = streams.join
+      tag("bulk", grid: grid) { inner }
+    end
+
+    # Per-user editing indicator on a cell.
+    def presence(grid:, row_id:, column:, user_id:, user_label:, active:)
+      tag("presence", grid: grid, row_id: row_id, column: column,
+                      user_id: user_id, user_label: user_label,
+                      active: active.to_s)
+    end
+
+    # Internal — build a <turbo-stream> element. Keys with nil values are
+    # dropped. Block content becomes the <template> payload.
+    def tag(action, **attrs)
+      attrs[:action] = action
+      kept = attrs.compact
+      attr_str = kept.map { |k, v| %(#{k.to_s.tr("_", "-")}="#{ERB::Util.html_escape(v)}") }.join(" ")
+      payload = block_given? ? yield : nil
+      template = payload ? "<template>#{payload}</template>" : ""
+      %(<turbo-stream #{attr_str}>#{template}</turbo-stream>)
+    end
+  end
+end