studio-engine 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0dff947db7bda136b0fcca271b86347449fa0d5f259c102ba5fe50e8e29dea8
-  data.tar.gz: 898fb4de879042127da3c85ee072603a8cf4d02125037d13d16793ecc8579e17
+  metadata.gz: 251aa22a7a41f33e6cab5a4f1f1c38a714aa4a14f2f4b08567c27340e1563f24
+  data.tar.gz: 2f8b5ec4901d403c1ffdaf42dee430c69f1c31625c926e8deb43c021a41eb6a9
 SHA512:
-  metadata.gz: 91f96cfc96d999ef6ea31aa7d427fb903c538da72470768891dd1e3667d7e5380bf8f931089c24548b9ad844b4c7815e0a9167231dd989c36fd674f04391e831
-  data.tar.gz: dc439df4fc3125f2a98c1511606008f74df5dc869c98a72ca0c4fe6a8ba4e082d093d5093de211e9b6534e280140cb35a6ba31952dc40b667e5fbe5de1b04552
+  metadata.gz: 1c8fa01470ce96a17550dac1d2d70db086b1acf0c6f6ed97a8b31679f2f3559dbb8549687bb79e806b2148a058ab700154bc330f4b94eb6b4216480fb0831d67
+  data.tar.gz: 4ae572b5cadc0734b1ef69a8d0ec0d4331c57f3545be08e850dcd2b0d53c0f6d30d5e1b2d287a65542d46dec4b1d803cad6611471f24c533143118daa0fc75b4

data/CHANGELOG.md

@@ -4,6 +4,24 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## v0.7.0 (2026-06-20)
+
+### Added
+- **`admin_model_table` helper** (`Studio::AdminModelsTableHelper`) — a shared
+  shell for `/admin/models` tables (overflow wrapper, `thead`, hover rows,
+  colspan empty state). Each consumer `_<key>_table` partial now declares only
+  its columns via `headers:` plus a per-row block; the helper is exposed
+  automatically through the `Studio::AdminModels` concern. Removes the duplicated
+  table boilerplate across mcritchie-studio and turf-monster.
+
+## v0.6.2 (2026-06-19)
+
+### Added
+- **`Studio.sticky_table_headers` opt-in** for shared sticky table headers. The
+  flag defaults off and, when enabled by a consumer app, loads the engine-owned
+  `studio/sticky_table_header.css` and `studio/sticky_table_header.js` assets
+  from the shared Studio head partial.
+
 ## v0.6.1 (2026-06-18)
 
 ### Added

data/app/assets/javascripts/studio/sticky_table_header.js

@@ -0,0 +1,194 @@
+(() => {
+  if (window.StudioStickyTableHeaders?.loaded) return;
+
+  const MANUAL_TABLE_SELECTOR = "table[data-sticky-table-header]";
+  const AUTO_TABLE_SELECTOR = "table";
+  const SKIP_CONTAINER_SELECTOR = "[data-sticky-table-skip]";
+
+  let stickyTables = [];
+  let scheduled = false;
+  let bootScheduled = false;
+  let navResizeObserver = null;
+  let tableMutationObserver = null;
+
+  window.StudioStickyTableHeaders = { loaded: true };
+
+  function navOffset() {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue("--nav-h");
+    return Number.parseFloat(raw) || 0;
+  }
+
+  function scheduleUpdate() {
+    if (scheduled) return;
+    scheduled = true;
+    requestAnimationFrame(() => {
+      scheduled = false;
+      stickyTables.forEach((stickyTable) => stickyTable.update());
+    });
+  }
+
+  function scheduleBoot() {
+    if (bootScheduled) return;
+    bootScheduled = true;
+    requestAnimationFrame(() => {
+      bootScheduled = false;
+      bootStickyTables();
+    });
+  }
+
+  class StickyTableHeader {
+    constructor(table) {
+      this.table = table;
+      this.prepareTable();
+      this.scroller = table.closest("[data-sticky-table-scroll]") || table.parentElement;
+      this.cloneShell = document.createElement("div");
+      this.cloneShell.className = "sticky-table-header-clone";
+      this.cloneShell.setAttribute("aria-hidden", "true");
+
+      this.cloneTable = document.createElement("table");
+      this.cloneTable.className = table.className;
+      this.cloneTable.innerHTML = table.tHead ? table.tHead.outerHTML : "";
+      this.cloneShell.appendChild(this.cloneTable);
+      document.body.appendChild(this.cloneShell);
+
+      this.scroller?.addEventListener("scroll", scheduleUpdate, { passive: true });
+    }
+
+    prepareTable() {
+      this.table.classList.add("sticky-data-table");
+      if (!this.table.hasAttribute("data-sticky-table-header")) {
+        this.table.setAttribute("data-sticky-table-header", "auto");
+      }
+
+      const scroller = this.table.closest("[data-sticky-table-scroll]") || this.table.parentElement;
+      if (scroller && !scroller.hasAttribute("data-sticky-table-scroll")) {
+        scroller.setAttribute("data-sticky-table-scroll", "auto");
+      }
+    }
+
+    destroy() {
+      this.scroller?.removeEventListener("scroll", scheduleUpdate);
+      this.cloneShell.remove();
+    }
+
+    syncColumnWidths() {
+      const originalCells = this.table.tHead?.querySelectorAll("th") || [];
+      const cloneCells = this.cloneTable.tHead?.querySelectorAll("th") || [];
+      originalCells.forEach((cell, index) => {
+        if (!cloneCells[index]) return;
+        cloneCells[index].style.width = `${cell.getBoundingClientRect().width}px`;
+      });
+    }
+
+    update() {
+      if (!document.body.contains(this.table) || !this.table.tHead || !this.scroller) {
+        this.destroy();
+        stickyTables = stickyTables.filter((stickyTable) => stickyTable !== this);
+        return;
+      }
+
+      const offset = navOffset();
+      const headerRect = this.table.tHead.getBoundingClientRect();
+      const tableRect = this.table.getBoundingClientRect();
+      const scrollerRect = this.scroller.getBoundingClientRect();
+      const cloneHeight = headerRect.height || this.cloneShell.getBoundingClientRect().height;
+      const active = headerRect.top <= offset && tableRect.bottom > offset;
+
+      if (!active) {
+        this.cloneShell.style.display = "none";
+        this.table.removeAttribute("data-sticky-table-active");
+        return;
+      }
+
+      this.syncColumnWidths();
+
+      const top = Math.min(offset, tableRect.bottom - cloneHeight);
+      const translateX = tableRect.left - scrollerRect.left;
+
+      this.cloneShell.style.display = "block";
+      this.cloneShell.style.left = `${scrollerRect.left}px`;
+      this.cloneShell.style.top = `${top}px`;
+      this.cloneShell.style.width = `${scrollerRect.width}px`;
+      this.cloneShell.style.height = `${cloneHeight}px`;
+      this.cloneTable.style.width = `${tableRect.width}px`;
+      this.cloneTable.style.transform = `translateX(${translateX}px)`;
+      this.table.setAttribute("data-sticky-table-active", "true");
+    }
+  }
+
+  function bootStickyTables() {
+    startTableObserver();
+
+    if (navResizeObserver) navResizeObserver.disconnect();
+    if (window.ResizeObserver) {
+      const header = document.querySelector("header");
+      if (header) {
+        navResizeObserver = new ResizeObserver(scheduleUpdate);
+        navResizeObserver.observe(header);
+      }
+    }
+
+    stickyTables.forEach((stickyTable) => stickyTable.destroy());
+    stickyTables = stickyTableCandidates().map((table) => new StickyTableHeader(table));
+    scheduleUpdate();
+  }
+
+  function startTableObserver() {
+    if (!window.MutationObserver || tableMutationObserver || !document.body) return;
+
+    tableMutationObserver = new MutationObserver((mutations) => {
+      const shouldReboot = mutations.some((mutation) => (
+        Array.from(mutation.addedNodes).some(nodeContainsCandidateTable) ||
+        Array.from(mutation.removedNodes).some(nodeContainsCandidateTable)
+      ));
+
+      if (shouldReboot) scheduleBoot();
+    });
+
+    tableMutationObserver.observe(document.body, { childList: true, subtree: true });
+  }
+
+  function nodeContainsCandidateTable(node) {
+    if (node.nodeType !== Node.ELEMENT_NODE) return false;
+    if (node.matches(".sticky-table-header-clone") || node.closest(".sticky-table-header-clone")) return false;
+
+    return node.matches("table, thead, th") || Boolean(node.querySelector("table, thead, th"));
+  }
+
+  function stickyTableCandidates() {
+    const candidates = [];
+    const seen = new Set();
+
+    document.querySelectorAll(`${MANUAL_TABLE_SELECTOR}, ${AUTO_TABLE_SELECTOR}`).forEach((table) => {
+      if (seen.has(table) || !shouldEnhanceTable(table)) return;
+      seen.add(table);
+      candidates.push(table);
+    });
+
+    return candidates;
+  }
+
+  function shouldEnhanceTable(table) {
+    if (table.getAttribute("data-sticky-table-header") === "false") return false;
+    if (table.closest(SKIP_CONTAINER_SELECTOR)) return false;
+    if (table.closest(".sticky-table-header-clone")) return false;
+    if (table.closest("template")) return false;
+    if (table.getAttribute("role")?.toLowerCase() === "presentation") return false;
+    if (!table.tHead || !table.tHead.querySelector("th")) return false;
+
+    return true;
+  }
+
+  document.addEventListener("turbo:load", bootStickyTables);
+  document.addEventListener("DOMContentLoaded", bootStickyTables);
+  document.addEventListener("turbo:before-cache", () => {
+    if (navResizeObserver) navResizeObserver.disconnect();
+    if (tableMutationObserver) tableMutationObserver.disconnect();
+    navResizeObserver = null;
+    tableMutationObserver = null;
+    stickyTables.forEach((stickyTable) => stickyTable.destroy());
+    stickyTables = [];
+  });
+  window.addEventListener("scroll", scheduleUpdate, { passive: true });
+  window.addEventListener("resize", scheduleUpdate, { passive: true });
+})();

data/app/assets/stylesheets/studio/sticky_table_header.css

@@ -0,0 +1,48 @@
+.sticky-data-table {
+  border-collapse: separate;
+  border-spacing: 0;
+}
+
+.sticky-data-table thead th {
+  background: var(--color-surface-alt);
+  box-shadow:
+    inset 0 -1px 0 var(--color-border),
+    0 10px 18px -18px rgba(15, 23, 42, 0.55);
+  transition:
+    background-color 200ms ease,
+    box-shadow 200ms ease,
+    top 200ms ease;
+}
+
+.dark .sticky-data-table thead th {
+  box-shadow:
+    inset 0 -1px 0 var(--color-border),
+    0 12px 22px -18px rgba(0, 0, 0, 0.85);
+}
+
+.sticky-table-header-clone {
+  position: fixed;
+  display: none;
+  overflow: hidden;
+  pointer-events: none;
+  z-index: 45;
+}
+
+.sticky-table-header-clone table {
+  border-collapse: separate;
+  border-spacing: 0;
+}
+
+.sticky-table-header-clone thead th {
+  position: static;
+  background: var(--color-surface-alt);
+  box-shadow:
+    inset 0 -1px 0 var(--color-border),
+    0 12px 22px -18px rgba(15, 23, 42, 0.65);
+}
+
+.dark .sticky-table-header-clone thead th {
+  box-shadow:
+    inset 0 -1px 0 var(--color-border),
+    0 14px 24px -18px rgba(0, 0, 0, 0.9);
+}

data/app/controllers/concerns/studio/admin_models.rb

@@ -13,6 +13,7 @@ module Studio
 
     included do
       before_action :set_model_config, only: :show
+      helper Studio::AdminModelsTableHelper
       helper_method :team_sort_url, :team_sort_indicator, :team_sport_emoji,
                     :team_record_json, :admin_models_table_partial
     end

data/app/helpers/studio/admin_models_table_helper.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Studio
+  # Shared shell for /admin/models tables. Renders the overflow wrapper + thead +
+  # tbody + empty state so each consumer `_<key>_table` partial only declares its
+  # columns. Exposed to consumer admin/models views via the AdminModels concern.
+  #
+  #   <%= admin_model_table(records, key: "users", min_width: 760,
+  #         headers: ["User", "Role", "Created"], empty: "No users found.") do |user| %>
+  #     <td class="px-4 py-3"><%= user.display_name %></td>
+  #     <td class="px-4 py-3"><%= user.role %></td>
+  #     <td class="px-4 py-3"><%= time_ago_in_words(user.created_at) %> ago</td>
+  #   <% end %>
+  #
+  # The block yields each record and returns that row's <td> cells. Output matches
+  # the long-standing markup (id="models-<key>-table", overflow wrapper, hover
+  # rows, colspan empty state) so existing view assertions keep passing.
+  module AdminModelsTableHelper
+    def admin_model_table(records, key:, headers:, min_width: 940, empty: "No records found.", &row)
+      header_row = content_tag(:tr, safe_join(headers.map { |label|
+        content_tag(:th, label, class: "px-4 py-3 text-left font-semibold")
+      }))
+
+      body =
+        if records.any?
+          safe_join(records.map { |record|
+            content_tag(:tr, capture(record, &row), class: "hover:bg-surface-alt/60 transition")
+          })
+        else
+          content_tag(:tr, content_tag(:td, empty,
+            colspan: headers.size, class: "px-4 py-10 text-center text-muted"))
+        end
+
+      table = content_tag(:table,
+        content_tag(:thead, header_row, class: "bg-surface-alt text-muted text-xs uppercase tracking-wide") +
+          content_tag(:tbody, body, class: "divide-y divide-subtle"),
+        id: "models-#{key}-table", class: "w-full min-w-[#{min_width}px] text-sm")
+
+      content_tag(:div, table, class: "overflow-x-auto")
+    end
+  end
+end

data/app/views/layouts/studio/_head.html.erb

@@ -107,4 +107,10 @@
 
 <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %>
 <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+<% if Studio.sticky_table_headers %>
+  <%= stylesheet_link_tag "studio/sticky_table_header", "data-turbo-track": "reload" %>
+<% end %>
 <%= javascript_importmap_tags %>
+<% if Studio.sticky_table_headers %>
+  <%= javascript_include_tag "studio/sticky_table_header", defer: true, "data-turbo-track": "reload" %>
+<% end %>

data/lib/studio/engine.rb

@@ -1,5 +1,12 @@
 module Studio
   class Engine < ::Rails::Engine
+    initializer "studio.assets" do |app|
+      app.config.assets.precompile += %w[
+        studio/sticky_table_header.css
+        studio/sticky_table_header.js
+      ]
+    end
+
     rake_tasks do
       load File.expand_path("../tasks/studio_email.rake", __dir__)
       load File.expand_path("../tasks/studio_ses.rake", __dir__)

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/studio.rb

@@ -20,6 +20,7 @@ module Studio
   mattr_accessor :sso_logo,            default: nil
   mattr_accessor :wallet_address_method, default: nil
   mattr_accessor :theme_logos,         default: []
+  mattr_accessor :sticky_table_headers, default: false
 
   # ---- Authentication ------------------------------------------------------
   # Which sign-in methods this app offers. The shared login/signup views render

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -142,6 +142,8 @@ files:
 - README.md
 - app/assets/images/resend-favicon.png
 - app/assets/images/ses-favicon.png
+- app/assets/javascripts/studio/sticky_table_header.js
+- app/assets/stylesheets/studio/sticky_table_header.css
 - app/controllers/concerns/solana/session_auth.rb
 - app/controllers/concerns/studio/admin_models.rb
 - app/controllers/concerns/studio/error_handling.rb
@@ -156,6 +158,7 @@ files:
 - app/controllers/solana_sessions_controller.rb
 - app/controllers/studio/local_emails_controller.rb
 - app/controllers/theme_settings_controller.rb
+- app/helpers/studio/admin_models_table_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
 - app/helpers/studio_theme_helper.rb
 - app/jobs/error_log_cleanup_job.rb