stimulus_grid_rails 0.1.0

data/app/assets/stylesheets/stimulus_grid_rails.css

@@ -0,0 +1,47 @@
+/* Visual states for cells managed by stimulus_grid_rails. Loaded on top of
+   stimulus_grid.css. */
+
+.sgr-cell-pending {
+  background: linear-gradient(
+    90deg,
+    rgba(59, 130, 246, 0.08) 25%,
+    rgba(59, 130, 246, 0.18) 50%,
+    rgba(59, 130, 246, 0.08) 75%
+  );
+  background-size: 200% 100%;
+  animation: sgr-cell-pulse 1.2s linear infinite;
+}
+
+@keyframes sgr-cell-pulse {
+  0%   { background-position: 100% 0; }
+  100% { background-position:   0% 0; }
+}
+
+.sgr-cell-just-confirmed {
+  background-color: rgba(16, 185, 129, 0.18);
+  transition: background-color 0.5s ease-out;
+}
+
+.sgr-cell-error {
+  background-color: rgba(239, 68, 68, 0.15);
+  outline: 1px solid #ef4444;
+}
+
+.sgr-cell-conflict {
+  background-color: rgba(245, 158, 11, 0.18);
+  outline: 1px dashed #f59e0b;
+}
+
+.sgr-presence {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px; height: 16px;
+  border-radius: 8px;
+  background: #6366f1;
+  color: white;
+  font-size: 9px;
+  font-weight: 700;
+  margin-left: 4px;
+  vertical-align: middle;
+}

data/app/controllers/stimulus_grid_rails/base_controller.rb

@@ -0,0 +1,51 @@
+module StimulusGridRails
+  # Base for all gem controllers. Inherits the host's configured controller
+  # (default ApplicationController) so Devise's authenticate_user! and
+  # ActsAsTenant's set_current_tenant_through_filter run for grid endpoints
+  # too — without that, these actions would execute unauthenticated and
+  # outside any tenant scope, leaking rows across tenants.
+  #
+  # Configure with `StimulusGridRails.parent_controller = "ApplicationController"`.
+  class BaseController < StimulusGridRails.parent_controller.constantize
+    # Tokens are sent in the X-CSRF-Token header by the grid-sync controller, so
+    # forgery protection stays on (inherited). Nothing is skipped.
+
+    private
+
+    def grid_for(resource)
+      StimulusGridRails.lookup_grid(resource).new(user: current_grid_user)
+    end
+
+    # Scoped lookup — never a bare Model.find. Goes through grid.scope(user) so
+    # ActsAsTenant (or a custom scope override) constrains what this user can
+    # reach. A row outside the scope raises RecordNotFound, not a silent leak.
+    def find_row!(grid, id)
+      grid.scope(current_grid_user).find(id)
+    end
+
+    # Devise's current_user when present; nil otherwise.
+    def current_grid_user
+      respond_to?(:current_user) ? current_user : nil
+    end
+
+    def turbo_stream_render(body, status: :ok)
+      render plain: body, content_type: "text/vnd.turbo-stream.html", status: status
+    end
+
+    # Record one undoable mutation (RAILS.md §16). No-op if the audit table
+    # hasn't been installed, so undo/redo is opt-in via the migration.
+    def record_audit(resource:, row_id:, column:, prior:, current:)
+      return unless StimulusGridRails::Audit.available?
+      StimulusGridRails::Audit.create!(
+        resource:    resource.to_s,
+        row_id:      row_id.to_s,
+        column:      column.to_s,
+        prior_value: prior.nil? ? nil : prior.to_s,
+        new_value:   current.nil? ? nil : current.to_s,
+        user_id:     current_grid_user&.id,
+      )
+    rescue => e
+      Rails.logger.warn("[stimulus_grid_rails] audit insert failed: #{e.message}")
+    end
+  end
+end

data/app/controllers/stimulus_grid_rails/cells_controller.rb

@@ -0,0 +1,113 @@
+require_dependency "stimulus_grid_rails/turbo_streams_helper"
+
+module StimulusGridRails
+  # Single cell-mutation endpoint — RAILS.md §8.
+  #
+  # PATCH /grids/:resource/:row_id/cells/:column
+  #   body:    { "value": <new value>, "optimistic_id": "...", "lock_version": N? }
+  #
+  # The save fires the model's after_update_commit, which AUTOMATICALLY
+  # broadcasts the changed cell(s) (RAILS.md §1/§4) — this controller does not
+  # broadcast. It only returns the optimistic reconcile (cell-confirm or
+  # cell-revert) directly to the originator and records an undo audit.
+  class CellsController < BaseController
+    def update
+      grid    = grid_for(params[:resource])
+      column  = grid.class.resolve_column!(params[:column])
+      row     = find_row!(grid, params[:row_id])
+
+      head :forbidden and return unless column.editable_for?(row, current_grid_user)
+
+      raw_value     = params[:value]
+      optimistic_id = params[:optimistic_id] || request.headers["X-Optimistic-Id"]
+      lock_version  = params[:lock_version]
+
+      if stale_version?(column, row, lock_version)
+        turbo_stream_render(TurboStreams.cell_conflict(
+          grid: params[:resource], row_id: row.id, column: column.name,
+          server_value: grid.cell_value(row, column), client_value: raw_value,
+          optimistic_id: optimistic_id,
+        ))
+        return
+      end
+
+      value, coerce_err = column.coerce(raw_value)
+      return render_revert(grid, row, column, [coerce_err], optimistic_id) if coerce_err
+
+      prior = grid.cell_value(row, column)
+      row._sgr_optimistic_id = optimistic_id   # carried into the auto-broadcast
+      ok, errors, mutations = grid.apply_cell!(row, column, value)
+
+      if ok
+        record_audit(resource: params[:resource], row_id: row.id, column: column.name,
+                     prior: prior, current: value)
+        turbo_stream_render(build_response_stream(params[:resource], mutations, optimistic_id))
+      else
+        render_revert(grid, row, column, errors, optimistic_id)
+      end
+    end
+
+    def bulk
+      grid      = grid_for(params[:resource])
+      mutations = []
+
+      params.require(:mutations).each do |m|
+        column = grid.class.resolve_column!(m[:column])
+        row    = find_row!(grid, m[:row_id])
+        next unless column.editable_for?(row, current_grid_user)
+
+        value, err = column.coerce(m[:value])
+        next if err
+
+        prior = grid.cell_value(row, column)
+        row._sgr_optimistic_id = params[:optimistic_id]
+        ok, _errs, ms = grid.apply_cell!(row, column, value)
+        if ok
+          record_audit(resource: params[:resource], row_id: row.id, column: column.name,
+                       prior: prior, current: value)
+          mutations.concat(ms)
+        end
+      end
+
+      streams = mutations.map do |row_id, col, val, _opts|
+        TurboStreams.cell_confirm(grid: params[:resource], row_id: row_id, column: col,
+                                  value: val, optimistic_id: params[:optimistic_id])
+      end
+      turbo_stream_render(TurboStreams.bulk(grid: params[:resource], streams: streams))
+    end
+
+    private
+
+    def stale_version?(column, row, lock_version)
+      column.concurrency == :version_checked &&
+        lock_version.present? &&
+        row.respond_to?(:lock_version) &&
+        lock_version.to_i != row.lock_version
+    end
+
+    def render_revert(grid, row, column, errors, optimistic_id)
+      turbo_stream_render(
+        TurboStreams.cell_revert(
+          grid: params[:resource], row_id: row.id, column: column.name,
+          value: grid.cell_value(row, column), errors: errors, optimistic_id: optimistic_id,
+        ),
+        status: :unprocessable_entity,
+      )
+    end
+
+    # Originator response: confirm the edited cell, push cascaded computed cells
+    # as plain `cell` updates. (Other clients get all of these via broadcast.)
+    def build_response_stream(resource, mutations, optimistic_id)
+      streams = mutations.map.with_index do |(row_id, col, val, _opts), i|
+        if i.zero?
+          TurboStreams.cell_confirm(grid: resource, row_id: row_id, column: col,
+                                    value: val, optimistic_id: optimistic_id)
+        else
+          TurboStreams.cell(grid: resource, row_id: row_id, column: col,
+                            value: val, optimistic_id: optimistic_id)
+        end
+      end
+      streams.length > 1 ? TurboStreams.bulk(grid: resource, streams: streams) : streams.first
+    end
+  end
+end

data/app/controllers/stimulus_grid_rails/history_controller.rb

@@ -0,0 +1,53 @@
+require_dependency "stimulus_grid_rails/turbo_streams_helper"
+
+module StimulusGridRails
+  # Undo / redo — RAILS.md §16.
+  #
+  #   POST /grids/:resource/undo   → revert the user's last mutation
+  #   POST /grids/:resource/redo   → re-apply the last undone mutation
+  #
+  # Each replays the prior/new value through grid.apply_cell!, so it goes
+  # through the same save → validation → cascade → auto-broadcast path as a
+  # normal edit. Scoped per current_user + resource. Audits whose row has since
+  # been deleted are skipped (and marked) rather than failing the request.
+  class HistoryController < BaseController
+    SCAN_LIMIT = 50
+
+    def undo
+      step(Audit.undoable(params[:resource], current_grid_user&.id),
+           value: :prior_value, undone: true)
+    end
+
+    # `redo` is a Ruby keyword, so the action is named redo_change.
+    def redo_change
+      step(Audit.redoable(params[:resource], current_grid_user&.id),
+           value: :new_value, undone: false)
+    end
+
+    private
+
+    def step(audits, value:, undone:)
+      return head(:not_implemented) unless Audit.available?
+      audits.limit(SCAN_LIMIT).each do |audit|
+        applied = apply(audit, audit.public_send(value))
+        # Mark the audit's new state regardless: applied → flip undone flag;
+        # skipped (row gone) → also flip so it doesn't block the next one.
+        audit.update!(undone: undone, undone_at: undone ? Time.current : nil)
+        return head(:ok) if applied
+      end
+      head :no_content
+    end
+
+    def apply(audit, raw_value)
+      grid   = grid_for(audit.resource)
+      column = grid.class.resolve_column!(audit.column)
+      row    = find_row!(grid, audit.row_id)
+      value, err = column.coerce(raw_value)
+      return false if err
+      ok, = grid.apply_cell!(row, column, value)   # saves → after_update_commit auto-broadcasts
+      ok
+    rescue ActiveRecord::RecordNotFound, ArgumentError
+      false
+    end
+  end
+end

data/app/controllers/stimulus_grid_rails/rows_controller.rb

@@ -0,0 +1,98 @@
+require_dependency "stimulus_grid_rails/turbo_streams_helper"
+
+module StimulusGridRails
+  # Row search / create / destroy — RAILS.md §14/§15/§21.
+  #
+  #   GET    /grids/:resource/rows?q=&filters=   → index (server-side search/filter, JSON)
+  #   POST   /grids/:resource/rows               → create
+  #   DELETE /grids/:resource/rows/bulk          → destroy_bulk (ids[])
+  #   DELETE /grids/:resource/rows/:row_id       → destroy
+  #
+  # Create/destroy broadcast AUTOMATICALLY via the model's commit callbacks
+  # (Broadcastable) — these actions just persist and return an empty 200; the
+  # originating tab applies the change when the broadcast lands.
+  class RowsController < BaseController
+    MAX_ROWS = 5_000
+
+    def index
+      grid     = grid_for(params[:resource])
+      relation = grid.search_and_filter(grid.scope(current_grid_user),
+                                        q: params[:q], filters: parse_filters)
+      relation = grid.apply_sort(relation, parse_sort)
+      total    = relation.count
+
+      if params[:page].present?
+        # Server-side row model: return just the requested window.
+        page      = params[:page].to_i
+        page_size = (params[:page_size].presence || 25).to_i.clamp(1, 1000)
+        window    = relation.offset(page * page_size).limit(page_size)
+        rows      = window.map { |r| grid.row_to_h(r) }
+        render json: { rows: rows, total: total, page: page, page_size: page_size, limited: false }
+      else
+        # Client-side model: the capped full (filtered) set.
+        rows = relation.limit(MAX_ROWS).map { |r| grid.row_to_h(r) }
+        render json: { rows: rows, total: total, limited: total > MAX_ROWS }
+      end
+    end
+
+    def create
+      grid = grid_for(params[:resource])
+      row  = grid.build_new_row(create_attributes)
+      # Stamp the tenant if the host uses ActsAsTenant and the model is scoped —
+      # otherwise a created row could escape the tenant. ActsAsTenant normally
+      # sets this automatically when current_tenant is present.
+      if row.save
+        head :ok   # after_create_commit broadcasts row-insert-sorted to everyone
+      else
+        render json: { errors: row.errors.full_messages }, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      grid = grid_for(params[:resource])
+      find_row!(grid, params[:row_id]).destroy   # after_destroy_commit broadcasts row-remove
+      head :ok
+    end
+
+    def destroy_bulk
+      grid = grid_for(params[:resource])
+      params.require(:ids)
+      # Scoped where (not find) so ids outside the user's scope are simply
+      # ignored rather than raising — each destroy fires its own broadcast.
+      grid.scope(current_grid_user).where(id: params[:ids]).find_each(&:destroy)
+      head :ok
+    end
+
+    private
+
+    def create_attributes
+      raw = params[:attributes]
+      return {} if raw.blank?
+      raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw.to_h
+    end
+
+    # `filters` arrives as a JSON string (query param) or a nested hash.
+    def parse_filters
+      raw = params[:filters]
+      return {} if raw.blank?
+      if raw.is_a?(String)
+        JSON.parse(raw)
+      elsif raw.respond_to?(:to_unsafe_h)
+        raw.to_unsafe_h
+      else
+        raw.to_h
+      end
+    rescue JSON::ParserError
+      {}
+    end
+
+    # `sort` arrives as a JSON string: [{ "colId":, "sort":"asc"|"desc" }, …].
+    def parse_sort
+      raw = params[:sort]
+      return [] if raw.blank?
+      raw.is_a?(String) ? JSON.parse(raw) : raw
+    rescue JSON::ParserError
+      []
+    end
+  end
+end

data/app/models/stimulus_grid_rails/audit.rb

@@ -0,0 +1,32 @@
+module StimulusGridRails
+  # One undoable cell mutation (RAILS.md §16). Recorded per successful cell
+  # commit; undo/redo replay the inverse/forward value as a normal mutation so
+  # validations re-run, cascades cascade, and broadcasts fire. Scoped per
+  # user + resource (not global).
+  #
+  # Install the table with the migration shipped in the gem (or copy it):
+  #   rails stimulus_grid_rails:install:migrations && rails db:migrate
+  class Audit < ActiveRecord::Base
+    self.table_name = "stimulus_grid_audits"
+
+    # True once the table is installed. Auditing (and undo/redo) is a no-op
+    # until then, so the rest of the gem works without the migration.
+    def self.available?
+      table_exists?
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+
+    # Most-recent not-yet-undone mutation for this user + resource.
+    def self.undoable(resource, user_id)
+      where(resource: resource.to_s, user_id: user_id, undone: false)
+        .order(created_at: :desc, id: :desc)
+    end
+
+    # Most-recently-undone mutation, ready to redo.
+    def self.redoable(resource, user_id)
+      where(resource: resource.to_s, user_id: user_id, undone: true)
+        .order(undone_at: :desc, id: :desc)
+    end
+  end
+end

data/app/views/stimulus_grid_rails/grids/_grid.html.erb

@@ -0,0 +1,107 @@
+<%#
+  Renders a server-driven grid for the given resource.
+
+  Required locals:
+    grid:  an instance of an ApplicationGrid subclass
+    rows:  the collection of model instances to render
+
+  Optional locals:
+    id:           DOM id for the grid element (default: "<resource>-grid")
+    css_class:    extra CSS classes on the grid wrapper
+    pagination:   true|false (default true)
+    page_size:    default 25
+    row_selection: nil | "single" | "multiple"
+%>
+<%
+  resource     = grid.class.resource_name
+  grid_id      = local_assigns[:id] || "#{resource}-grid"
+  pagination   = local_assigns.fetch(:pagination, true)
+  page_size    = local_assigns.fetch(:page_size, 25)
+  row_selection = local_assigns[:row_selection]
+
+  # Server-side row model (RAILS.md §21). Pass `server_side: true` + `total:`
+  # (the full row count) and render only the first page as `rows:`. The grid then
+  # fetches windows from rows#index on page/sort/filter changes.
+  server_side  = local_assigns.fetch(:server_side, false)
+  total_rows   = local_assigns[:total] || (rows.respond_to?(:size) ? rows.size : 0)
+
+  # Optional left gutter for row selection:
+  #   row_gutter: :numbers   → 1-based row numbers (click # = select row)
+  #   row_gutter: :checkbox  → a checkbox per row + select-all in the header
+  #   row_gutter: false      → none (default)
+  # (true is treated as :numbers for convenience.)
+  row_gutter   = local_assigns.fetch(:row_gutter, false)
+  row_gutter   = :numbers if row_gutter == true
+
+  # Drag selected rows by the gutter to reorder them (ghost preview).
+  row_drag     = local_assigns.fetch(:row_drag, false)
+
+  # Client endpoints are built from the configured mount path (default "/grids"),
+  # so namespacing the engine (e.g. StimulusGridRails.mount_path = "/admin/grids")
+  # is reflected here without depending on the engine's route-helper name. :row_id
+  # and :column stay as placeholders the grid-sync controller substitutes.
+  base = StimulusGridRails.mount_path
+%>
+
+<div id="<%= grid_id %>"
+     class="<%= local_assigns[:css_class] %> sgr-panel"
+     data-controller="grid grid-sync"
+     data-grid-name="<%= resource %>"
+     data-grid-row-selection-value="<%= row_selection %>"
+     data-grid-pagination-value="<%= pagination %>"
+     data-grid-page-size-value="<%= page_size %>"
+     data-grid-server-side-value="<%= server_side %>"
+     data-grid-row-count-value="<%= total_rows %>"
+     data-grid-row-drag-value="<%= row_drag %>"
+     data-grid-sync-server-side-value="<%= server_side %>"
+     data-grid-sync-resource-value="<%= resource %>"
+     data-grid-sync-cells-path-template-value="<%= "#{base}/:resource/:row_id/cells/:column" %>"
+     data-grid-sync-rows-path-value="<%= "#{base}/#{resource}/rows" %>"
+     data-grid-sync-row-path-template-value="<%= "#{base}/#{resource}/rows/:row_id" %>"
+     data-grid-sync-bulk-rows-path-value="<%= "#{base}/#{resource}/rows/bulk" %>"
+     data-grid-sync-cells-bulk-path-value="<%= "#{base}/#{resource}/bulk" %>"
+     data-grid-sync-undo-path-value="<%= "#{base}/#{resource}/undo" %>"
+     data-grid-sync-redo-path-value="<%= "#{base}/#{resource}/redo" %>">
+  <table>
+    <thead>
+      <tr>
+        <% if row_gutter == :checkbox %>
+          <th data-controller="header-cell" data-header-cell-field-value="_select"
+              data-header-cell-checkbox-value="true" data-header-cell-pinned-value="left"
+              data-header-cell-width-value="40"></th>
+        <% elsif row_gutter == :numbers %>
+          <th data-controller="header-cell" data-header-cell-field-value="_rownum"
+              data-header-cell-row-number-value="true" data-header-cell-pinned-value="left"
+              data-header-cell-width-value="46"></th>
+        <% end %>
+        <% grid.columns.each do |col| %>
+          <th <% col.header_data_attrs.each do |k, v| %><%= k %>="<%= v %>" <% end %>><%= col.header %></th>
+        <% end %>
+      </tr>
+    </thead>
+    <tbody>
+      <% rows.each do |row| %>
+        <%= render partial: "stimulus_grid_rails/grids/row", locals: { grid: grid, row: row } %>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+
+<% if pagination %>
+  <nav class="sg-pagination"
+       data-controller="pagination"
+       data-pagination-grid-outlet="#<%= grid_id %>">
+    <button data-pagination-target="first" data-action="pagination#first">«</button>
+    <button data-pagination-target="prev"  data-action="pagination#prev">‹</button>
+    <span class="sg-spacer"></span>
+    <span data-pagination-target="pageInfo">…</span>
+    <span class="sg-spacer"></span>
+    <button data-pagination-target="next"  data-action="pagination#next">›</button>
+    <button data-pagination-target="last"  data-action="pagination#last">»</button>
+  </nav>
+<% end %>
+
+<%# Turbo Stream subscription. Tenant-scoped via streamables_for, so a tenant
+    only ever receives its own broadcasts (RAILS.md §2). The broadcaster (model
+    commit callbacks) derives the same streamables, so they match. %>
+<%= turbo_stream_from(*StimulusGridRails.streamables_for(resource)) %>

data/app/views/stimulus_grid_rails/grids/_row.html.erb

@@ -0,0 +1,15 @@
+<%#
+  One row. Cell editability and editor metadata flow from the column
+  registry. We emit data-editable only for columns the user can actually
+  edit — Stimulus refuses to enter edit mode otherwise (RAILS.md §17).
+%>
+<tr data-row-id="<%= grid.row_id(row) %>"
+    <% if row.respond_to?(:lock_version) %>data-lock-version="<%= row.lock_version %>"<% end %>>
+  <% grid.columns.each do |col| %>
+    <%
+      attrs = col.client_data_attrs(row, local_assigns[:current_user])
+      attrs["data-pinned"] = col.pinned if col.pinned
+    %>
+    <td <% attrs.each do |k, v| %><%= k %>="<%= v %>" <% end %>><%= grid.format_cell(row, col) %></td>
+  <% end %>
+</tr>

data/config/importmap.rb

@@ -0,0 +1,6 @@
+# Importmap pins exposed to host apps. Loaded by the engine initializer.
+#
+# The host app's bin/importmap.rb pins are merged on top of these, so a host
+# can override any pin by re-declaring it.
+pin "stimulus_grid",       to: "stimulus_grid.js",       preload: true
+pin "stimulus_grid_rails", to: "stimulus_grid_rails.js", preload: true

data/config/routes.rb

@@ -0,0 +1,24 @@
+StimulusGridRails::Engine.routes.draw do
+  # Single cell mutation — RAILS.md §8.
+  patch "/:resource/:row_id/cells/:column",
+        to: "cells#update",
+        as: :cell,
+        constraints: { row_id: /[^\/]+/, column: /[^\/]+/ }
+
+  # Bulk cell paste — RAILS.md §9 fill-down / bulk paste.
+  post "/:resource/bulk", to: "cells#bulk", as: :bulk
+
+  # Undo / redo — RAILS.md §16.
+  post "/:resource/undo", to: "history#undo",        as: :undo
+  post "/:resource/redo", to: "history#redo_change", as: :redo
+
+  # Server-side search/filter — RAILS.md §21. Returns matching rows as JSON.
+  get "/:resource/rows", to: "rows#index", as: :index_rows
+
+  # Row create/destroy — RAILS.md §14/§15. `rows/bulk` must precede the
+  # `:row_id` route so "bulk" isn't captured as an id.
+  post   "/:resource/rows",         to: "rows#create",       as: :rows
+  delete "/:resource/rows/bulk",    to: "rows#destroy_bulk",  as: :bulk_rows
+  delete "/:resource/rows/:row_id", to: "rows#destroy",      as: :row,
+         constraints: { row_id: /[^\/]+/ }
+end

data/db/migrate/20260520000001_create_stimulus_grid_audits.rb

@@ -0,0 +1,18 @@
+class CreateStimulusGridAudits < ActiveRecord::Migration[7.0]
+  def change
+    create_table :stimulus_grid_audits do |t|
+      t.string   :resource,    null: false
+      t.string   :row_id,      null: false
+      t.string   :column,      null: false
+      t.text     :prior_value
+      t.text     :new_value
+      t.string   :user_id
+      t.boolean  :undone,      null: false, default: false
+      t.datetime :undone_at
+
+      t.timestamps
+    end
+    add_index :stimulus_grid_audits, %i[resource user_id undone created_at],
+              name: "idx_sgr_audits_undo"
+  end
+end