studio-engine 0.141.3 → 0.142.0

data/config/studio_tricks.yml

@@ -211,19 +211,23 @@ glass:
   name: Glass
   group: Glass
   token: "config.surface_style = :glass"
-  note: "Frosts the cards and lights the controls from above; opt-in per app."
+  note: "Frosts the cards and lights the controls; the standard for a new app."
   resolve: [config:surface_style, css:surface-glass-blur]
   variants:
     lit:
       token: ".btn, .badge, .input-field under surface_style = :glass"
       note: "Buttons, badges and inputs lit from above, in every state."
       resolve: [config:surface_style]
+    tile:
+      token: ".lit-tile, .lit-tile-soft under surface_style = :glass"
+      note: "An app's own call-to-action tile, lit like a button."
+      resolve: [css:lit-tile, css:lit-tile-soft]
 
 glass_sidebar:
   name: Glass Sidebar
   group: Glass
   token: "config.sidebar_style = :glass"
-  note: "A frosted link sidebar; opt-in per app."
+  note: "A frosted link sidebar in the app's colours; the standard for a new app."
   resolve: [config:sidebar_style]
 
 icon:

data/db/migrate/20261109180000_add_engine_not_null_checks.rb

@@ -0,0 +1,148 @@
+# The second half of the engine's slug standard and of the role standard: the
+# database refuses a NULL `slug` on error_logs, theme_settings,
+# studio_geo_settings and studio_site_identities, and a NULL `role` on the
+# host's users (database audit 2026-11-07; the steps
+# RequireSlugsOnEngineTables and AddUsersRoleKnownCheck deferred to a later
+# release, engine-not-null-next-release).
+#
+# THE FORM: a validated CHECK named `<table>_<column>_present`, holding
+# `<column> IS NOT NULL`, not a column-level NOT NULL.
+#
+#   * It is the same rule to every write: Postgres refuses the NULL insert or
+#     update either way.
+#   * It is the one form the release's schema-dump guard
+#     (Release::EngineMigrationInstall.schema_dump_safe?) accepts. The sweep
+#     migrates each host's throwaway database and diffs db/schema.rb; the guard
+#     passes a diff that only ADDS lines. `change_column_null` rewrites the
+#     existing `t.string "slug"` line to `t.string "slug", null: false`, a
+#     removed line, and the guard refuses it by design. A CHECK adds one
+#     `t.check_constraint` line and removes nothing.
+#   * Its dump is stable. Postgres deparses `slug IS NOT NULL` to
+#     `(slug IS NOT NULL)` and deparses that to itself again, so a host's dump
+#     after this migrate equals its dump after a schema load, byte for byte
+#     (unlike an `IN (...)` list, see AddUsersRoleKnownCheck#expression).
+#   * On Postgres 12 and later, a validated `CHECK (x IS NOT NULL)` lets a
+#     later `SET NOT NULL` skip its table scan, if that form is ever wanted.
+#
+# ROLLBACK SAFETY. A column that is NOT NULL breaks every insert that leaves it
+# NULL, and Heroku runs this migration while the previous release's dynos still
+# serve, and a `heroku rollback` keeps the constraint. So this migration ships
+# only once every host already runs code that never writes a NULL here:
+#
+#   * error_logs: ErrorLog includes Sluggable from 0.138.0 (first shipped in
+#     0.141.0), which writes a placeholder slug before the insert. Up to 0.137.0,
+#     ErrorLog.capture! inserted a NULL slug and filled it after.
+#   * theme_settings, studio_geo_settings, studio_site_identities: Sluggable
+#     since 0.129.0.
+#   * users.role: the column's default is "viewer" on every host, and no engine
+#     or host code writes an explicit NULL role.
+#
+# The error_logs line is the floor: a host must have run 0.141.0 or later in
+# production for one release before it installs this migration. A host that
+# jumps from 0.137.0 or older straight to this version in one release breaks
+# its own error writes while the old dynos drain, and again on a rollback.
+#
+# Each step, per table, and a table or column the host does not have is skipped:
+#
+#   1. A column that is already NOT NULL (the hub's and Turf's users.role) needs
+#      no CHECK: skipped.
+#   2. A CHECK of this name already there: skipped, so a second run is a no-op.
+#   3. Backfill. A NULL or blank slug gets the one its model would write (the
+#      same rule as RequireSlugsOnEngineTables, copied, since a migration must
+#      not depend on another migration's class); a NULL role becomes "viewer".
+#   4. Add the CHECK, validated.
+#
+# Production on 2026-11-08 held no NULL slug and no NULL role. On Postgres each
+# ALTER waits at most LOCK_TIMEOUT for its lock; a migrate that cannot get it
+# fails whole, changes nothing, and runs again on the next release.
+class AddEngineNotNullChecks < ActiveRecord::Migration[7.2]
+  LOCK_TIMEOUT = "10s"
+
+  # table => the slug prefix its model's name_slug writes before the app name.
+  # error_logs has no app name: its slug is the id.
+  NAMED = {
+    "theme_settings" => "theme",
+    "studio_geo_settings" => "geo",
+    "studio_site_identities" => "site-identity"
+  }.freeze
+  SLUG_TABLES = ([ "error_logs" ] + NAMED.keys).freeze
+
+  # [table, column] pairs, in the order `up` runs them.
+  COLUMNS = (SLUG_TABLES.map { |table| [ table, "slug" ] } + [ %w[users role] ]).freeze
+
+  def self.constraint_name(table, column) = "#{table}_#{column}_present"
+
+  def up
+    set_lock_timeout
+    COLUMNS.each do |table, column|
+      next unless nullable_column?(table, column)
+
+      name = self.class.constraint_name(table, column)
+      next if check_constraint_exists?(table, name: name)
+
+      column == "role" ? backfill_role : backfill_slug(table)
+      add_check_constraint table, "#{column} IS NOT NULL", name: name
+    end
+  end
+
+  # Removes only the CHECKs `up` adds. Backfilled values stay: they are valid
+  # either way. Run it before a rollback to a release older than 0.141.0 (see
+  # the changelog): that code inserts a NULL error_logs slug.
+  def down
+    COLUMNS.each do |table, column|
+      next unless table_exists?(table)
+
+      remove_check_constraint table, name: self.class.constraint_name(table, column), if_exists: true
+    end
+  end
+
+  private
+
+  def postgres? = connection.adapter_name.downcase.include?("postgres")
+
+  def set_lock_timeout
+    return unless postgres?
+
+    execute "SET LOCAL lock_timeout = '#{LOCK_TIMEOUT}'"
+  end
+
+  def nullable_column?(table, column)
+    return false unless table_exists?(table)
+
+    found = columns(table).find { |c| c.name == column }
+    found.present? && found.null
+  end
+
+  def quoted(table) = connection.quote_table_name(table)
+
+  def backfill_role
+    execute "UPDATE users SET role = 'viewer' WHERE role IS NULL"
+  end
+
+  def backfill_slug(table)
+    rows = connection.select_rows(<<~SQL.squish)
+      SELECT id#{', app_name' if NAMED.key?(table)} FROM #{quoted(table)}
+      WHERE slug IS NULL OR slug = '' ORDER BY id
+    SQL
+    rows.each do |id, app_name|
+      derived = derived_slug(table, id, app_name)
+      derived = "#{derived}-#{id}" if taken?(table, derived, id)
+      connection.update(<<~SQL.squish, "#{self.class.name} backfill")
+        UPDATE #{quoted(table)} SET slug = #{connection.quote(derived)} WHERE id = #{Integer(id)}
+      SQL
+    end
+  end
+
+  def derived_slug(table, id, app_name)
+    return "error-log-#{id}" unless NAMED.key?(table)
+
+    name = ActiveSupport::Inflector.parameterize(app_name.to_s)
+    name.empty? ? "#{NAMED.fetch(table)}-#{id}" : "#{NAMED.fetch(table)}-#{name}"
+  end
+
+  def taken?(table, slug, id)
+    connection.select_value(<<~SQL.squish).present?
+      SELECT 1 FROM #{quoted(table)} WHERE slug = #{connection.quote(slug)} AND id <> #{Integer(id)} LIMIT 1
+    SQL
+  end
+end

data/lib/studio/modals.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Studio
+  # The on-demand modal registry: modals the shared host (studio/modals/_host)
+  # fetches the first time they open, instead of the layout rendering every
+  # template into every page.
+  #
+  #   # config/initializers/studio.rb
+  #   Studio.modals.register :contest_rules, partial: "modals/contest_rules"
+  #   Studio.modals.register :wallet_setup,  partial: "modals/wallet_setup",
+  #                          auth: :user, locals: :wallet_setup_modal_locals
+  #   Studio.modals.register :auth,          partial: "modals/auth", prefetch: true
+  #
+  # A registered id is served by GET /_studio/modals/:id
+  # (Studio::ModalsController) and opened with the same
+  # $store.modals.open(id, props) call as before. Render it ONLY through the
+  # registry: an id that the layout still renders AND the registry names would
+  # mount twice. Every id the registry does not name behaves as it always did.
+  #
+  # Options:
+  #   partial:  the content partial, rendered exactly as the layout rendered it
+  #             (one root element; see the README's "Modal host" rules).
+  #   auth:     :any (default) or :user. A :user modal answers 401 to a
+  #             signed-out request, and is never prefetched for one.
+  #   prefetch: true fetches the modal when the browser idles after load, for a
+  #             modal that should open with no wait (the sign-in card).
+  #   locals:   the partial's locals. A Hash, a Symbol naming a helper the view
+  #             answers (Turf's existing *_modal_locals helpers), or a callable
+  #             taking the view. Resolved per request, inside the view.
+  module Modals
+    AUTH_LEVELS = %i[any user].freeze
+
+    # The id lands inside a single-quoted JavaScript string in the host's x-if,
+    # and in a URL path segment, so it is held to a shape that needs no escaping
+    # in either place.
+    ID_FORMAT = /\A[a-z0-9][a-z0-9_-]*\z/
+
+    Entry = Struct.new(:id, :partial, :auth, :prefetch, :locals, keyword_init: true) do
+      def user_only? = auth == :user
+
+      # The locals for one render, resolved in that render's view.
+      def locals_for(view)
+        resolved =
+          case locals
+          when nil then {}
+          when Hash then locals
+          when Symbol, String then view.public_send(locals)
+          else locals.arity.zero? ? view.instance_exec(&locals) : locals.call(view)
+          end
+        raise ArgumentError, "Studio.modals #{id}: locals must resolve to a Hash, got #{resolved.class}" unless resolved.is_a?(Hash)
+
+        resolved
+      end
+    end
+
+    class Registry
+      def initialize
+        @entries = {}
+      end
+
+      def register(id, partial:, auth: :any, prefetch: false, locals: nil)
+        key = id.to_s
+        raise ArgumentError, "Studio.modals: id #{id.inspect} must match #{ID_FORMAT.inspect}" unless key.match?(ID_FORMAT)
+        raise ArgumentError, "Studio.modals #{key}: partial is required" if partial.to_s.strip.empty?
+        raise ArgumentError, "Studio.modals #{key}: auth must be one of #{AUTH_LEVELS.inspect}" unless AUTH_LEVELS.include?(auth)
+        unless locals.nil? || locals.is_a?(Hash) || locals.is_a?(Symbol) || locals.is_a?(String) || locals.respond_to?(:call)
+          raise ArgumentError, "Studio.modals #{key}: locals must be a Hash, a helper name or a callable"
+        end
+
+        @entries[key] = Entry.new(id: key, partial: partial.to_s, auth: auth, prefetch: prefetch == true, locals: locals)
+      end
+
+      def [](id) = @entries[id.to_s]
+      def registered?(id) = @entries.key?(id.to_s)
+      def ids = @entries.keys
+      def entries = @entries.values
+      def any? = @entries.any?
+      def empty? = @entries.empty?
+
+      # Removes one id, or every id. For tests and for a host that registers
+      # conditionally on reload.
+      def unregister(id) = @entries.delete(id.to_s)
+      def clear! = @entries.clear
+
+      # What the host template advertises to studio/modal_host. Every id, so a
+      # signed-out open of a :user modal still reaches the endpoint and shows
+      # the error card; prefetch only what this viewer may load.
+      def client_config(url_template:, logged_in:)
+        {
+          url: url_template,
+          ids: ids,
+          prefetch: entries.select { |e| e.prefetch && (!e.user_only? || logged_in) }.map(&:id)
+        }
+      end
+    end
+  end
+
+  def self.modals
+    @modals ||= Modals::Registry.new
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.141.3"
+  VERSION = "0.142.0"
 end

data/lib/studio.rb

@@ -33,6 +33,7 @@ require "studio/js_literal"
 require "studio/js_identifier"
 require "studio/hold_button"
 require "studio/partial_block"
+require "studio/modals"
 require "studio/sidebar_sections"
 require "studio/icons"
 require "studio/site_footer"
@@ -306,6 +307,7 @@ module Studio
   # today. :glass floats an inset, translucent panel over the page, with line icons
   # (a link's icon:), a marked current page and no separate blurred edge. It is opt-in,
   # so an app moves only when it asks. engine.css, THE GLASS SIDEBAR, holds the look.
+  # :glass is the standard for a NEW app (docs/NEW_APP_SETUP.md); the default stays put.
   mattr_reader :sidebar_style, default: :default
 
   def self.sidebar_style=(value)
@@ -316,6 +318,7 @@ module Studio
   # How cards look. :glass makes them translucent over a soft ambient page, once the host
   # layout says so on its root: <html data-surface-style="<%= Studio.surface_style %>">.
   # :default is what every app has today. engine.css, THE GLASS SURFACES, holds the look.
+  # :glass is the standard for a NEW app (docs/NEW_APP_SETUP.md); the default stays put.
   SURFACE_STYLES = %i[default glass].freeze
   mattr_reader :surface_style, default: :default
 
@@ -2192,6 +2195,14 @@ module Studio
       get "_studio/health_report", to: "studio/health_reports#show", as: :studio_health_report,
           defaults: { format: :json }
 
+      # The on-demand modal fragments (Studio::ModalsController, Studio.modals).
+      # Drawn for every app: the controller is the gate, answering 404 for any
+      # id the registry does not name, so an app that registers nothing serves
+      # nothing. HTML only; studio/modal_host is its one caller.
+      get "_studio/modals/:id", to: "studio/modals#show", as: :studio_modal,
+          constraints: { id: /[a-z0-9][a-z0-9_-]*/ },
+          defaults: { format: :html }
+
       # Developer-desk tools. Drawn outside production, and each controller
       # re-checks Studio.local_tool_enabled? per request (loopback only) — the
       # route being absent is the outer gate, not the only one.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.141.3
+  version: 0.142.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -439,8 +439,24 @@ files:
 - app/components/previews/studio/badge_component_preview.rb
 - app/components/previews/studio/badge_component_preview/schemes.html.erb
 - app/components/previews/studio/badge_component_preview/tones.html.erb
+- app/components/previews/studio/button_component_preview.rb
+- app/components/previews/studio/button_component_preview/disabled.html.erb
+- app/components/previews/studio/button_component_preview/icon_and_link.html.erb
+- app/components/previews/studio/button_component_preview/loading.html.erb
+- app/components/previews/studio/button_component_preview/sizes.html.erb
+- app/components/previews/studio/button_component_preview/tones.html.erb
+- app/components/previews/studio/empty_state_component_preview.rb
+- app/components/previews/studio/empty_state_component_preview/with_icon_and_action.html.erb
+- app/components/previews/studio/table_component_preview.rb
+- app/components/previews/studio/table_component_preview/rows.html.erb
 - app/components/studio/badge_component.html.erb
 - app/components/studio/badge_component.rb
+- app/components/studio/button_component.html.erb
+- app/components/studio/button_component.rb
+- app/components/studio/empty_state_component.html.erb
+- app/components/studio/empty_state_component.rb
+- app/components/studio/table_component.html.erb
+- app/components/studio/table_component.rb
 - app/controllers/concerns/solana/session_auth.rb
 - app/controllers/concerns/studio/admin_models.rb
 - app/controllers/concerns/studio/board/reorderable.rb
@@ -474,6 +490,7 @@ files:
 - app/controllers/studio/local_emails_controller.rb
 - app/controllers/studio/local_reviews_controller.rb
 - app/controllers/studio/marketing_kit_controller.rb
+- app/controllers/studio/modals_controller.rb
 - app/controllers/studio/models_controller.rb
 - app/controllers/studio/not_found_controller.rb
 - app/controllers/studio/onboarding_controller.rb
@@ -779,6 +796,7 @@ files:
 - app/views/studio/modals/blocks/_success_card.html.erb
 - app/views/studio/modals/blocks/_wallet_brand_sprite.html.erb
 - app/views/studio/modals/onboarding/_first_name.html.erb
+- app/views/studio/modals/remote.html.erb
 - app/views/studio/modals/shared/_age_attestation.html.erb
 - app/views/studio/modals/shared/_email_field.html.erb
 - app/views/studio/modals/templates/_action.html.erb
@@ -838,6 +856,7 @@ files:
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
 - app/views/style/_pages.html.erb
+- app/views/style/_primitives.html.erb
 - app/views/style/_scrims.html.erb
 - app/views/style/_site_footer.html.erb
 - app/views/style/_specimen.html.erb
@@ -892,6 +911,7 @@ files:
 - db/migrate/20261108160000_require_slugs_on_engine_tables.rb
 - db/migrate/20261108160001_add_engine_state_checks.rb
 - db/migrate/20261108170000_add_users_role_known_check.rb
+- db/migrate/20261109180000_add_engine_not_null_checks.rb
 - docs/BOOKING.md
 - docs/SITE_FOOTER.md
 - lib/active_storage/service/studio_trash_s3_service.rb
@@ -965,6 +985,7 @@ files:
 - lib/studio/mail_sender.rb
 - lib/studio/mail_transport.rb
 - lib/studio/marketing_kit.rb
+- lib/studio/modals.rb
 - lib/studio/name_parts.rb
 - lib/studio/navbar_account_sidebar.rb
 - lib/studio/navbar_brand.rb