studio-engine 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9e4f490c1b36a67d00f603bee9cf9849fd36103fff17a6e348ed98b138f4987
-  data.tar.gz: 5003c6176d386ae82f129b749bd9d914a65e258b40587ff82ec3d7a5c2c3509f
+  metadata.gz: bc7a335b47486105708b2b7739c6a567e1486c6a68b2bf6d2e5e5abd8bc8d6a1
+  data.tar.gz: a0ab08402099d51e7fa059f6171cd83a7ad175c7a6ba2ae983e59dba9a36672f
 SHA512:
-  metadata.gz: 0ea8405b0e80d57f6d69df6a96dfdb835859e581076b9182d01a88a7b0517f63210835265ce4691549ee0f5c52444cbb504f97e173af4b27a46d99c17c51838c
-  data.tar.gz: '080e131c86404755936a99ae1e41f10a143a32b7401170639ad0251bac7d787c5308bc9cb818db92446576f73b368764c7eef9570764651a015ef295c8e64856'
+  metadata.gz: f4b8203aa82fb630a33c0c12b3cc77f2f51cfe3cbbb8328354c6743a43643758403d570ecfb78569b386b614ca12cedeb29b81b1c122b1f1104fa7ab3ba83998
+  data.tar.gz: e568830a6432462d083ad833d75f999a9447f3547f97a83fbb7b9f9ea9fdfcdc2b05566e0f77159b72bb4a84d8395e5aaeef61e3a1ebbae7f931167bcf36df9b

data/CHANGELOG.md

@@ -4,6 +4,21 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 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
+- **`components/emoji_swap` UI primitive** plus shared CSS for nav/sidebar
+  emoji hover and focus transitions, including reduced-motion fallback and
+  aliases for the existing `nav-emoji-*` class names.
+
 ## v0.6.0 (2026-06-16)
 
 ### Changed

data/README.md

@@ -11,7 +11,7 @@ Shared Rails engine for McRitchie apps. Provides authentication, error handling,
 gem "studio-engine", "~> 0.6"
 ```
 
-Then `bundle install`. The current release is **v0.6.0**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
+Then `bundle install`. The current release is **v0.6.1**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
 
 > Published to RubyGems as of v0.4.0 (2026-05-17). New installs should use the RubyGems form, which the consumer Rails apps (`mcritchie-studio`, `turf-monster`) already use.
 
@@ -20,6 +20,7 @@ Then `bundle install`. The current release is **v0.6.0**; see [`CHANGELOG.md`](.
 - **Authentication**: Passwordless magic-link auth, optional password auth, Google OAuth via OmniAuth, Solana wallet sign-in, and optional one-way SSO patterns
 - **Error handling**: `Studio::ErrorHandling` concern with `rescue_and_log`, `ErrorLog` model with `capture!`, error log viewer at `/error_logs`
 - **Theme system**: Dynamic CSS custom properties generated from 7 role colors (primary, dark, light, success, accent, warning, danger). Dark/light mode toggle. Admin theme editor at `/admin/theme`.
+- **UI primitives**: Shared component partials and CSS primitives such as `components/emoji_swap` for nav/sidebar emoji hover transitions.
 - **Operator tooling**: Shared `studio/banners/environment` banner with Dev Mode + email connector controls, `studio/banners/impersonation`, and an opt-in `Studio::Impersonation` concern for Act As session conventions.
 - **Sluggable concern**: `before_save :set_slug` with `to_param` for human-readable URLs
 - **ThemeSetting model**: Per-app DB overrides with fallback to config defaults
@@ -111,6 +112,19 @@ audit log, enter/exit controller actions, and any app-specific safeguards such
 as binding session-token checks to `true_user` or disabling wallet-only
 privileges while impersonating.
 
+## UI Primitives
+
+Render `components/emoji_swap` inside a link or button with the `group` class to
+slide between two emoji on hover and keyboard focus. The CSS ships through
+`studio_theme_css_tag`, including a reduced-motion fade fallback.
+
+```erb
+<%= link_to root_path, class: "group inline-flex items-center gap-2" do %>
+  <%= render "components/emoji_swap", base: "📊", hover: "✨" %>
+  <span>Dashboard</span>
+<% end %>
+```
+
 ## Overriding Views
 
 This is a non-isolated engine -- app views at the same path automatically override engine views. For example, placing `app/views/sessions/new.html.erb` in the consuming app replaces the engine's login page.

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/helpers/studio_theme_helper.rb

@@ -10,6 +10,6 @@ module StudioThemeHelper
       Studio::ThemeResolver.new(colors).to_css
     end
 
-    tag.style(css.html_safe, nonce: content_security_policy_nonce)
+    tag.style("#{css}\n#{Studio::UiPrimitives.css}".html_safe, nonce: content_security_policy_nonce)
   end
 end

data/app/views/components/_emoji_swap.html.erb

@@ -0,0 +1,17 @@
+<%# locals: (base:, hover:, aria_label: nil, class_name: nil) %>
+<%
+  wrapper_classes = ["studio-emoji-swap", "flex-shrink-0", local_assigns[:class_name]].compact_blank.join(" ")
+  attrs = { class: wrapper_classes }
+
+  if local_assigns[:aria_label].present?
+    attrs[:role] = "img"
+    attrs["aria-label"] = aria_label
+  else
+    attrs["aria-hidden"] = "true"
+  end
+%>
+
+<%= tag.span(**attrs) do %>
+  <span class="studio-emoji-swap-base" aria-hidden="true"><%= base %></span>
+  <span class="studio-emoji-swap-hover" aria-hidden="true"><%= hover %></span>
+<% 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/ui_primitives.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Studio
+  module UiPrimitives
+    EMOJI_SWAP_CSS = <<~CSS
+      .studio-emoji-swap,
+      .nav-emoji-swap {
+        position: relative;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        vertical-align: middle;
+        width: 1.5rem;
+        height: 1.25rem;
+        overflow: hidden;
+      }
+
+      .studio-emoji-swap > span,
+      .nav-emoji-swap > span {
+        position: absolute;
+        inset: 0;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        transition: transform 240ms cubic-bezier(0.34, 1.2, 0.5, 1), opacity 180ms ease;
+      }
+
+      .studio-emoji-swap-base,
+      .nav-emoji-base {
+        transform: translateX(0);
+        opacity: 1;
+      }
+
+      .studio-emoji-swap-hover,
+      .nav-emoji-hover {
+        transform: translateX(-110%);
+        opacity: 0;
+      }
+
+      .group:hover .studio-emoji-swap-base,
+      .group:focus-visible .studio-emoji-swap-base,
+      .group:focus-within .studio-emoji-swap-base,
+      .group:hover .nav-emoji-base,
+      .group:focus-visible .nav-emoji-base,
+      .group:focus-within .nav-emoji-base {
+        transform: translateX(110%);
+        opacity: 0;
+      }
+
+      .group:hover .studio-emoji-swap-hover,
+      .group:focus-visible .studio-emoji-swap-hover,
+      .group:focus-within .studio-emoji-swap-hover,
+      .group:hover .nav-emoji-hover,
+      .group:focus-visible .nav-emoji-hover,
+      .group:focus-within .nav-emoji-hover {
+        transform: translateX(0);
+        opacity: 1;
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        .studio-emoji-swap > span,
+        .nav-emoji-swap > span {
+          transition: opacity 120ms ease;
+        }
+
+        .studio-emoji-swap-base,
+        .studio-emoji-swap-hover,
+        .nav-emoji-base,
+        .nav-emoji-hover,
+        .group:hover .studio-emoji-swap-base,
+        .group:focus-visible .studio-emoji-swap-base,
+        .group:focus-within .studio-emoji-swap-base,
+        .group:hover .studio-emoji-swap-hover,
+        .group:focus-visible .studio-emoji-swap-hover,
+        .group:focus-within .studio-emoji-swap-hover,
+        .group:hover .nav-emoji-base,
+        .group:focus-visible .nav-emoji-base,
+        .group:focus-within .nav-emoji-base,
+        .group:hover .nav-emoji-hover,
+        .group:focus-visible .nav-emoji-hover,
+        .group:focus-within .nav-emoji-hover {
+          transform: none;
+        }
+      }
+    CSS
+
+    def self.css
+      EMOJI_SWAP_CSS
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.6.0"
+  VERSION = "0.6.2"
 end

data/lib/studio.rb

@@ -2,6 +2,7 @@ require "studio/version"
 require "studio/engine"
 require "studio/color_scale"
 require "studio/theme_resolver"
+require "studio/ui_primitives"
 require "studio/username_generator"
 require "studio/s3"
 require "studio/image_cache"
@@ -19,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.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-06-19 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
@@ -177,6 +179,7 @@ files:
 - app/views/components/_badge.html.erb
 - app/views/components/_card.html.erb
 - app/views/components/_copy_button.html.erb
+- app/views/components/_emoji_swap.html.erb
 - app/views/components/_empty_state.html.erb
 - app/views/components/_google_logo.html.erb
 - app/views/components/_input.html.erb
@@ -230,6 +233,7 @@ files:
 - lib/studio/mail_transport.rb
 - lib/studio/s3.rb
 - lib/studio/theme_resolver.rb
+- lib/studio/ui_primitives.rb
 - lib/studio/username_generator.rb
 - lib/studio/version.rb
 - lib/tasks/studio_email.rake