studio-engine 0.132.0 → 0.133.0

data/app/javascript/studio/page_header.js

@@ -29,3 +29,20 @@ export function revealBy(box, tab, margin = 32) {
   if (tab.right > box.right) return tab.right - box.right + margin
   return 0
 }
+
+// Where the quick-links list goes when the browser has no anchor positioning: under the
+// button, its right edge on the button's, and kept on the screen with a gap of `gap`. It
+// opens above the button when there is no room below and more room above. Fixed
+// coordinates, as the list is a popover in the top layer.
+export function menuPlacement(button, list, viewport, gap = 8) {
+  const below = viewport.height - button.bottom
+  const above = button.top
+  const top = below < list.height + gap && above > below
+    ? Math.max(gap, button.top - list.height - 4)
+    : button.bottom + 4
+  const left = Math.min(
+    Math.max(gap, button.right - list.width),
+    Math.max(gap, viewport.width - list.width - gap)
+  )
+  return { top, left }
+}

data/app/views/studio/_carousel.html.erb

@@ -1,4 +1,4 @@
-<%# locals: (label:, items:, per_view: 3, id: nil, slide_label: nil, data: {}, class_name: nil, style: :standard, caption: nil, start: nil) %>
+<%# locals: (label:, items:, per_view: 3, id: nil, slide_label: nil, data: {}, class_name: nil, style: :standard, caption: nil, start: nil, autoplay: nil, loop: false) %>
 <%# THE CAROUSEL: one sideways row of slides, the apps' standard for a set too
     long to grid. Render it as a layout, so each slide is your own block:
 
@@ -31,6 +31,17 @@
                    it has scroll-initial-target; elsewhere the controller sets it
                    when it connects, with no glide and nothing announced. A link
                    to an id inside the row (#fragment) wins over the start.
+      loop         true wraps the row: Next at the last slide goes to the first,
+                   Previous at the first to the last, and neither arrow is ever
+                   disabled. No slide is cloned, so a screen reader reads each once.
+      autoplay     seconds between moves (a number above 0); nil, the default, is
+                   off. The row moves one slide each interval and holds still while
+                   the pointer is over the slides, while keyboard focus is in it,
+                   while the tab is hidden or the row is off screen, and after a
+                   swipe or press until the reader leaves it alone a while. A pause
+                   button sits beside the arrows (WCAG 2.2.2). Under reduced motion
+                   the row starts stopped, and Play starts it. Without loop it
+                   stops at the last slide; Play then starts again from the first.
 
     THE SPOTLIGHT (engine.css, carousel-spotlight) snaps each slide to the centre.
     Where the browser has scroll-driven animations, each slide's own view timeline
@@ -52,7 +63,7 @@
     slide a group with aria-roledescription slide and its own label, named arrows
     that set aria-disabled at an end (not disabled, so focus stays on the arrow),
     and a polite, atomic status line that speaks only after a press that moves the
-    row. A key pressed in a form field, an arrow-key widget (a slider, a tab list,
+    row (a looping row's arrows are never disabled; autoplay never speaks). A key pressed in a form field, an arrow-key widget (a slider, a tab list,
     a listbox...) or a nested carousel stays that element's. %>
 <%
   per_view = per_view.to_f.clamp(1, 6)
@@ -70,6 +81,13 @@
                 when Integer then start.clamp(0, [total - 1, 0].max)
                 else raise ArgumentError, "studio/carousel start: #{start.inspect} is not an index or :middle"
                 end
+  autoplay = nil if autoplay == false
+  unless autoplay.nil? || (autoplay.is_a?(Numeric) && autoplay.positive? && autoplay.finite?)
+    raise ArgumentError, "studio/carousel autoplay: #{autoplay.inspect} is not a number of seconds above 0 or nil"
+  end
+  autoplay = autoplay.to_i if autoplay && autoplay == autoplay.floor
+  loop = loop ? true : false
+  wraps = loop && total > 1
   arrow_noun = spotlight ? "slide" : "slides"
   track_id = id.presence || "carousel-#{label.to_s.parameterize.presence || 'slides'}"
 %>
@@ -77,7 +95,8 @@
       role: "region",
       aria: { roledescription: "carousel", label: label },
       style: "--carousel-per-view: #{per_view}",
-      data: { studio_controller: "carousel", studio_action: "keydown->carousel#key", carousel_start: (start_index.to_s if start_index.positive?) }.compact.merge(data)) do %>
+      data: { studio_controller: "carousel", studio_action: "keydown->carousel#key", carousel_start: (start_index.to_s if start_index.positive?),
+              carousel_autoplay: (autoplay.to_s if autoplay), carousel_loop: ("" if loop) }.compact.merge(data)) do %>
   <%# The track takes focus for the keys, so it carries a name: a group, since a
       bare div may not be named. %>
   <div id="<%= track_id %>" class="carousel-track" tabindex="0" role="group"
@@ -98,12 +117,21 @@
       <% end %>
     </div>
     <div class="carousel-arrows">
+      <% if autoplay %>
+        <%# The pause button (WCAG 2.2.2). The controller renames it "Play slideshow"
+            and swaps the icon when the reader stops the row. %>
+        <button type="button" class="carousel-button carousel-autoplay" aria-label="Pause slideshow" aria-controls="<%= track_id %>"
+                data-carousel-target="toggle" data-studio-action="click->carousel#toggle">
+          <svg class="carousel-autoplay-pause" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><rect x="5.5" y="4.5" width="3" height="11" rx="1"/><rect x="11.5" y="4.5" width="3" height="11" rx="1"/></svg>
+          <svg class="carousel-autoplay-play" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M7 4.8v10.4a.8.8 0 0 0 1.2.7l8.2-5.2a.8.8 0 0 0 0-1.4L8.2 4.1A.8.8 0 0 0 7 4.8Z"/></svg>
+        </button>
+      <% end %>
       <button type="button" class="carousel-button" aria-label="Previous <%= arrow_noun %>" aria-controls="<%= track_id %>"
-              aria-disabled="<%= start_index.zero? %>" data-carousel-target="prev" data-studio-action="click->carousel#prev">
+              aria-disabled="<%= !wraps && start_index.zero? %>" data-carousel-target="prev" data-studio-action="click->carousel#prev">
         <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12.5 15 7.5 10l5-5" stroke-linecap="round" stroke-linejoin="round"/></svg>
       </button>
       <button type="button" class="carousel-button" aria-label="Next <%= arrow_noun %>" aria-controls="<%= track_id %>"
-              <%= 'aria-disabled="true" '.html_safe if total.positive? && start_index == total - 1 %>data-carousel-target="next" data-studio-action="click->carousel#next">
+              <%= 'aria-disabled="true" '.html_safe if !wraps && total.positive? && start_index == total - 1 %>data-carousel-target="next" data-studio-action="click->carousel#next">
         <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m7.5 5 5 5-5 5" stroke-linecap="round" stroke-linejoin="round"/></svg>
       </button>
     </div>

data/app/views/studio/_page_header.html.erb

@@ -1,4 +1,4 @@
-<%# locals: (title:, crumbs: [], crumb_label: nil, meta: nil, meta_title: nil, label: nil, tabs: [], tabs_data: {}, actions_html: nil, links: [], links_label: "More links", data: {}, row_class: "-mx-4 px-4") %>
+<%# locals: (title:, crumbs: [], crumb_label: nil, meta: nil, meta_title: nil, label: nil, tabs: [], anchors: [], tabs_data: {}, menu: [], menu_label: "Links", action: nil, tools_html: nil, actions_html: nil, links: [], links_label: "More links", data: {}, row_class: "-mx-4 px-4") %>
 <%# THE PAGE HEADER: the second layer of the pinned stack (docs/PAGE_HEADER.md).
     navbar, then this row, then a section's header (studio/_section_header), then a
     table's sticky header, each below the last.
@@ -19,12 +19,25 @@
       meta          short text beside the title, such as the version. Hidden on a
                     phone, where the tabs need the width.
       meta_title    the meta's title attribute.
-      label         the tabs' nav's accessible name. A row with tabs needs it.
-      tabs          [{ label:, href:, current:, data: }]. `current` is the
-                    aria-current value ("page" or "true"), and blank on the others.
-      tabs_data     data attributes for the tabs' scroller.
-      actions_html  a control on the right, such as the page's one primary action.
-                    After the tabs, when the row has both.
+      label         the pill group's nav's accessible name. A row with tabs or
+                    anchors needs it.
+
+    THE FOUR KINDS OF CONTROL on the right (docs/PAGE_HEADER.md, "The four kinds of
+    control"), always in this order and at the one height of .btn-sm:
+
+      tabs          views of the same thing (Deployments | Triage), [{ label:, href:,
+                    current:, data: }]. One pill group with the gliding pill. `current`
+                    is the aria-current value ("page" or "true"), blank on the others.
+      anchors       sections of this page, [{ label:, href: "#id", current:, data: }].
+                    The same pill group; a same-page link scrolls, with no visit. A row
+                    takes tabs or anchors, never both: it has one pill group.
+      tabs_data     data attributes for the pill group's scroller.
+      menu          related pages elsewhere, [{ label:, href:, data: }]: one neutral
+                    button, menu_label ("Links"), that opens a list of them.
+      action        the page's one primary action, { label:, href:, data: }. Rightmost.
+      tools_html    local-only and dev controls, after the action, muted.
+      actions_html  DEPRECATED: free HTML after the pill group. It renders for one
+                    release and warns once per call site in development.
       links         the page's other links, [{ label:, href:, current: }], on a line of
                     their own at the foot of the row, so they stick with it.
       links_label   that line's accessible name.
@@ -79,13 +92,16 @@
       <p class="page-header-meta label-upper"<%= %( title="#{ERB::Util.h(meta_title)}").html_safe if meta_title.present? %>><%= meta %></p>
     <% end %>
   </div>
-  <% if tabs.any? %>
-    <%= tag.nav(class: "page-header-tabs", aria: { label: label.presence }, data: tabs_data) do %>
+  <% raise ArgumentError, "studio/_page_header takes tabs: or anchors:, not both (one pill group)" if tabs.any? && anchors.any? %>
+  <% raise ArgumentError, "studio/_page_header takes one action: a Hash { label:, href: }" unless action.nil? || action.is_a?(Hash) %>
+  <% pills, pill_kind = tabs.any? ? [tabs, "tabs"] : [anchors, "anchors"] %>
+  <% if pills.any? %>
+    <%= tag.nav(class: "page-header-tabs", aria: { label: label.presence }, data: { page_header_kind: pill_kind }.merge(tabs_data)) do %>
       <%# The glide: one pill, drawn once, that CSS anchors to the tab with aria-current and
           slides from tab to tab (engine.css, "The gliding pill"). Each tab keeps its own
           fill where the browser has no anchor positioning. %>
       <div class="page-header-track">
-        <% tabs.each do |tab| %>
+        <% pills.each do |tab| %>
           <%= link_to tab.fetch(:href),
                 class: "page-header-tab btn btn-sm #{tab[:current].present? ? 'btn-primary' : 'btn-neutral'}",
                 aria: { current: tab[:current].presence },
@@ -95,8 +111,44 @@
       </div>
     <% end %>
   <% end %>
-  <% if actions_html.present? %>
-    <div class="page-header-actions"><%= actions_html %></div>
+  <% if actions_html.present? && defined?(Studio::PageHeader) && Studio::PageHeader.warning_enabled? %>
+    <% site = caller_locations.find { |loc| loc.path.to_s.end_with?(".erb") && !loc.path.to_s.end_with?("_page_header.html.erb") } %>
+    <% Studio::PageHeader.deprecate_actions_html(site: site && "#{site.path}:#{site.lineno}") %>
+  <% end %>
+  <% if [actions_html, tools_html].any?(&:present?) || menu.any? || action.present? %>
+    <%# One cluster, in the fixed order: the old free HTML where it always stood, then
+        the menu, then the action, then the tools. Each control is .btn-sm, so all
+        four kinds share one height. %>
+    <div class="page-header-actions">
+      <%= actions_html if actions_html.present? %>
+      <% if menu.any? %>
+        <%# A disclosure, not role="menu": a list of links that Tab walks. The browser's
+            popover opens it from the button, closes it on Escape or a click outside,
+            and gives focus back to the button, with no script. The page-header
+            controller adds aria-expanded, and places the list where the browser has
+            no anchor positioning. %>
+        <% menu_id = "page-header-menu-#{SecureRandom.hex(4)}" %>
+        <div class="page-header-menu" data-page-header-kind="menu">
+          <button type="button" class="page-header-menu-button btn btn-sm btn-neutral"
+                  popovertarget="<%= menu_id %>" aria-controls="<%= menu_id %>"><%= menu_label %><span class="page-header-menu-caret" aria-hidden="true"></span></button>
+          <div id="<%= menu_id %>" class="page-header-menu-list" popover="auto">
+            <ul>
+              <% menu.each do |item| %>
+                <li><%= link_to item.fetch(:label), item.fetch(:href), class: "page-header-menu-item", data: item.fetch(:data, {}) %></li>
+              <% end %>
+            </ul>
+          </div>
+        </div>
+      <% end %>
+      <% if action.present? %>
+        <%= link_to action.fetch(:label), action.fetch(:href),
+              class: "page-header-action btn btn-sm btn-primary",
+              data: { page_header_kind: "action" }.merge(action.fetch(:data, {})) %>
+      <% end %>
+      <% if tools_html.present? %>
+        <div class="page-header-tools" data-page-header-kind="tools"><%= tools_html %></div>
+      <% end %>
+    </div>
   <% end %>
   <% if links.any? %>
     <nav class="page-header-links" aria-label="<%= links_label %>">

data/app/views/studio/auth/_sign_in_body.html.erb

@@ -0,0 +1,236 @@
+<%#
+  The inside of the engine's standard sign-in card: Google, then "or", then the
+  email magic link, then the link-sent step with the resend footer. The page
+  card (studio/auth/_sign_in_card) and the modal (studio/auth/_sign_in_modal)
+  both render this, so the two cannot drift apart. Render one of those two, not
+  this one; the locals are theirs, documented in docs/SIGN_IN_CARD.md.
+
+  ONE ALPINE SCOPE, AND ITS SHAPE IS A CONTRACT. studio/modals/auth/_resend_footer
+  reads props.submitting, props.resendCooldown and props.resendError and calls
+  resendMagicLink() from the ENCLOSING x-data. This root is that x-data. Keep
+  those four names.
+
+  THE CONFIG RIDES A DATA ATTRIBUTE, NOT THE EXPRESSION. The endpoint, the
+  return path and the copy are server values. They go in as JSON in
+  data-sign-in-card, which ERB escapes, and the x-data reads them with
+  JSON.parse. No server value is spliced into JavaScript source.
+
+  DEMO MODE (demo: true) POSTS NOTHING. The style guide renders it. Google is a
+  plain type=button with no form around it. The email form has no action, and
+  send() waits on a timer instead of fetch(). The link-sent step and the resend
+  cooldown play as they do for real (cooldown 5s, not 60s). Guarded by
+  test/views/sign_in_card_test.rb and e2e/style_sign_in_card.spec.js.
+
+  REAL MODE posts as the hub's and Turf's cards do. Google is a button_to POST
+  to /auth/google_oauth2 with Turbo off; OmniAuth owns that path, and its
+  request phase is POST-only and CSRF-checked. When the app has no OAuth client
+  yet, studio/google_sign_in/_button draws its setup modal instead. The email
+  form is a real form_tag to the magic-link endpoint, so it still works with no
+  JavaScript; with JavaScript, send() posts the same fields by fetch() as JSON
+  and flips to the link-sent step only after the server says success.
+%>
+<%
+  demo           = local_assigns.fetch(:demo, false) ? true : false
+  dom_id         = local_assigns.fetch(:dom_id, "sign-in-card")
+  # Kept to a plain in-app path, as the server keeps it (Studio::LinkToken.sanitize_path).
+  return_to      = Studio::LocalPath.local?(local_assigns[:return_to]) ? local_assigns[:return_to].to_s : nil
+  modal_store    = local_assigns[:modal_store]
+  show_google    = local_assigns.fetch(:google, demo || Studio.auth_method?(:google))
+  show_email     = local_assigns.fetch(:magic_link, demo || Studio.auth_method?(:magic_link))
+  magic_link_path = local_assigns[:magic_link_path].presence ||
+                    ((respond_to?(:main_app) && main_app.respond_to?(:magic_link_request_path)) ? main_app.magic_link_request_path : "/magic_link")
+  google_path    = return_to ? "#{Studio::GoogleSignIn::REQUEST_PATH}?#{{ return_to: return_to }.to_query}" : Studio::GoogleSignIn::REQUEST_PATH
+  google_label   = local_assigns.fetch(:google_label, "Continue with Google")
+  link_noun      = Studio::AuthLabels.link_noun(Studio.sign_in_label)
+  send_label     = local_assigns.fetch(:send_label, "Email me a #{link_noun}")
+  ttl_minutes    = (Studio.magic_link_ttl.to_i / 60).clamp(1, 24 * 60)
+  # A slot entry is a partial path, or { partial:, locals: }. A named local, not a
+  # block: see Studio::PartialBlock for why a partial cannot trust block_given?.
+  slot = lambda do |entries|
+    Array(entries).filter_map do |entry|
+      entry = { partial: entry } if entry.is_a?(String)
+      render(partial: entry.fetch(:partial), locals: entry.fetch(:locals, {})) if entry.is_a?(Hash)
+    end.join.html_safe
+  end
+  preamble_html = slot.call(local_assigns[:preamble])
+  extras_html   = slot.call(local_assigns[:extras])
+  config = {
+    demo: demo,
+    endpoint: (demo ? nil : magic_link_path),
+    returnTo: return_to,
+    cooldown: (demo ? 5 : 60),
+    email: local_assigns[:email].to_s,
+    sendLabel: send_label,
+    messages: {
+      generic: "We could not send the link. Check your connection and try again.",
+      throttled: "Too many requests. Wait a minute, then try again.",
+      delivery_failed: Studio::MagicLinkIssuing::DELIVERY_FAILED
+    }
+  }
+%>
+<div data-sign-in-card="<%= config.to_json %>"
+     data-sign-in-card-mode="<%= demo ? "demo" : "live" %>"
+     x-data="{
+       cfg: JSON.parse($el.dataset.signInCard),
+       step: 'email',
+       email: '',
+       init() { this.email = this.cfg.email || ''; },
+       error: '',
+       demoNote: '',
+       props: { submitting: null, resendCooldown: 0, resendError: '' },
+       _timer: null,
+       get sending() { return this.props.submitting === 'magic-link'; },
+       async post() {
+         if (this.cfg.demo) { await new Promise((r) => setTimeout(r, 700)); return; }
+         const body = new URLSearchParams();
+         body.set('email', this.email.trim());
+         if (this.cfg.returnTo) body.set('return_to', this.cfg.returnTo);
+         const token = document.querySelector('meta[name=csrf-token]');
+         const resp = await fetch(this.cfg.endpoint, {
+           method: 'POST', credentials: 'same-origin',
+           headers: { 'Accept': 'application/json', 'Content-Type': 'application/x-www-form-urlencoded', 'X-CSRF-Token': token ? token.content : '' },
+           body: body.toString()
+         });
+         let payload = {};
+         try { payload = await resp.json(); } catch (e) { payload = {}; }
+         if (resp.ok && payload.success !== false) return;
+         if (resp.status === 429) throw new Error(this.cfg.messages.throttled);
+         if (payload.error === 'delivery_failed') throw new Error(this.cfg.messages.delivery_failed);
+         throw new Error(this.cfg.messages.generic);
+       },
+       startCooldown() {
+         clearInterval(this._timer);
+         this.props.resendCooldown = this.cfg.cooldown;
+         this._timer = setInterval(() => {
+           this.props.resendCooldown -= 1;
+           if (this.props.resendCooldown <= 0) { this.props.resendCooldown = 0; clearInterval(this._timer); }
+         }, 1000);
+       },
+       async send() {
+         if (!this.email.trim() || this.props.submitting) return;
+         this.error = '';
+         this.props.submitting = 'magic-link';
+         try {
+           await this.post();
+           this.step = 'sent';
+           this.startCooldown();
+           this.focusSoon(() => this.$refs.sentHeading);
+         } catch (e) {
+           this.error = e.message || this.cfg.messages.generic;
+         } finally { this.props.submitting = null; }
+       },
+       async resendMagicLink() {
+         if (this.props.submitting || this.props.resendCooldown > 0) return;
+         this.props.resendError = '';
+         this.props.submitting = 'magic-link';
+         try { await this.post(); this.startCooldown(); }
+         catch (e) { this.props.resendError = e.message || this.cfg.messages.generic; }
+         finally { this.props.submitting = null; }
+       },
+       useAnotherEmail() {
+         clearInterval(this._timer);
+         this.props.resendCooldown = 0;
+         this.props.resendError = '';
+         this.step = 'email';
+         this.focusSoon(() => this.$refs.emailForm && this.$refs.emailForm.querySelector('input[type=email]'));
+       },
+       // Focus follows the step, for a keyboard or screen-reader user: the
+       // pressed button is hidden with its step. A hidden node cannot take
+       // focus, and x-show can reveal the new step a frame or more after the
+       // change (measured: still display none in the first frame), so wait
+       // frame by frame until it is rendered, ten frames at most.
+       focusSoon(target, tries = 10) {
+         requestAnimationFrame(() => {
+           const el = target();
+           if (el && el.offsetParent !== null) el.focus();
+           else if (tries > 1) this.focusSoon(target, tries - 1);
+         });
+       },
+       destroy() { clearInterval(this._timer); }
+     }">
+
+  <%# ---- Step 1: the ways in ---- %>
+  <div x-show="step === 'email'" data-sign-in-step="email">
+    <% if preamble_html.present? %>
+      <div class="mb-4" data-sign-in-slot="preamble"><%= preamble_html %></div>
+    <% end %>
+
+    <% if show_google %>
+      <% if demo %>
+        <button type="button" class="btn btn-google btn-lg w-full gap-3" data-sign-in-google="demo"
+                @click="demoNote = 'Demo only: Google sign-in does not run on the style guide.'">
+          <%= render "components/google_logo" %>
+          <%= google_label %>
+        </button>
+      <% elsif Studio::GoogleSignIn.button_posts? %>
+        <%= button_to google_path, method: :post,
+              form: { data: { sign_in_google: "ready" } },
+              data: { turbo: false },
+              class: "btn btn-google btn-lg w-full gap-3" do %>
+          <%= render "components/google_logo" %>
+          <%= google_label %>
+        <% end %>
+      <% else %>
+        <%= render "studio/google_sign_in/button", label: google_label %>
+      <% end %>
+    <% end %>
+
+    <% if extras_html.present? %>
+      <div class="mt-3 space-y-3" data-sign-in-slot="extras"><%= extras_html %></div>
+    <% end %>
+
+    <% if show_email && (show_google || extras_html.present?) %>
+      <div class="flex items-center gap-3 my-5 text-sm" aria-hidden="true">
+        <div class="flex-1 border-t border-strong"></div>
+        <span class="text-secondary">or</span>
+        <div class="flex-1 border-t border-strong"></div>
+      </div>
+    <% end %>
+
+    <% if show_email %>
+      <% form_attrs = { "x-ref" => "emailForm", "@submit.prevent" => "send()", novalidate: true, data: { sign_in_email_form: (demo ? "demo" : "live") } } %>
+      <% email_form_body = capture do %>
+        <label for="<%= dom_id %>-email" class="block text-sm text-secondary mb-2 font-medium">Email</label>
+        <%= render "studio/modals/shared/email_field",
+              name: "email", id: "#{dom_id}-email", required: true,
+              x_model: "email",
+              disabled_expr: "props.submitting === 'magic-link'" %>
+        <% if return_to %><input type="hidden" name="return_to" value="<%= return_to %>"><% end %>
+        <button type="submit" class="btn btn-primary btn-lg w-full mt-4 disabled:cursor-wait disabled:opacity-60"
+                :disabled="sending || !email.trim()">
+          <span x-text="sending ? 'Sending…' : cfg.sendLabel"><%= send_label %></span>
+        </button>
+        <p role="alert" x-show="error" x-cloak class="text-xs text-danger-ink text-center mt-2" x-text="error"></p>
+        <p class="text-xs text-muted text-center mt-2">One tap from your inbox. No password.</p>
+      <% end %>
+      <% if demo %>
+        <%= tag.form(**form_attrs) { email_form_body } %>
+      <% else %>
+        <%= form_tag(magic_link_path, method: :post, **form_attrs) { email_form_body } %>
+      <% end %>
+    <% end %>
+
+    <p x-show="demoNote" x-cloak class="text-xs text-muted text-center mt-3" x-text="demoNote" data-sign-in-demo-note></p>
+  </div>
+
+  <%# ---- Step 2: the link is on its way ---- %>
+  <div x-show="step === 'sent'" x-cloak class="text-center" data-sign-in-step="sent">
+    <div class="text-3xl leading-none mb-3" aria-hidden="true">📬</div>
+    <h3 x-ref="sentHeading" tabindex="-1" class="text-heading font-bold text-lg leading-tight outline-none">Check your email</h3>
+    <p class="text-sm text-body mt-2">
+      We sent a <%= link_noun %> to <strong class="text-heading" x-text="email.trim()"></strong>.
+      It works once and expires in <%= ttl_minutes %> minutes.
+    </p>
+    <div class="border-t border-subtle mt-5 pt-4">
+      <% if modal_store %>
+        <%= render "studio/modals/auth/resend_footer", modal_store: modal_store %>
+      <% else %>
+        <%= render "studio/modals/auth/resend_footer", close: false %>
+      <% end %>
+    </div>
+    <button type="button" @click="useAnotherEmail()"
+            class="block mx-auto mt-3 text-xs text-muted hover:text-secondary underline underline-offset-2">
+      Use a different email
+    </button>
+  </div>
+</div>

data/app/views/studio/auth/_sign_in_card.html.erb

@@ -0,0 +1,50 @@
+<%#
+  The engine's standard sign-in card, for a page: the app's heading, then one
+  card with Google, "or", and the email magic link. Sending the link flips the
+  same card to its link-sent step, with the resend footer. No modal is needed.
+
+    render "studio/auth/sign_in_card"
+    render "studio/auth/sign_in_card", return_to: "/contests/42",
+          subheading: "Sign in to play",
+          preamble: "studio/modals/shared/age_attestation",
+          extras: "shared/solana_wallet_connect"
+
+  Locals (all optional):
+    heading      — default "Sign in to <Studio.app_name>" (Studio::AuthLabels.to_app)
+    subheading   — default "New here? The same step creates your account."
+    logo         — default true: Studio.logo_for("Auth Logo"), when the app has one
+    return_to    — an in-app path the visitor lands on after sign-in. Anything
+                   but a plain local path is dropped. Rides the magic-link POST
+                   and the Google request URL (?return_to=).
+    preamble     — a partial (or { partial:, locals: }, or an Array) above Google
+    extras       — the same, after Google and before "or": extra providers
+    google       — default Studio.auth_method?(:google)
+    magic_link   — default Studio.auth_method?(:magic_link)
+    magic_link_path — default the engine's POST /magic_link
+    email        — prefill for the email field
+    demo         — default false. true posts nothing (the style guide).
+    dom_id       — id prefix for the email field. Default "sign-in-card".
+
+  The body is studio/auth/_sign_in_body; docs/SIGN_IN_CARD.md has the contract.
+%>
+<%
+  heading    = local_assigns[:heading].presence || Studio::AuthLabels.to_app(Studio.sign_in_label, Studio.app_name)
+  subheading = local_assigns.key?(:subheading) ? local_assigns[:subheading] : "New here? The same step creates your account."
+  logo_path  = local_assigns.fetch(:logo, true) ? Studio.logo_for("Auth Logo") : nil
+  body_locals = local_assigns.slice(:return_to, :preamble, :extras, :google, :magic_link, :magic_link_path,
+                                    :email, :demo, :dom_id, :google_label, :send_label)
+%>
+<div class="min-h-[70vh] flex items-center justify-center" data-sign-in-card-page>
+  <div class="w-full max-w-md">
+    <div class="text-center mb-8">
+      <% if logo_path %>
+        <img src="<%= logo_path %>" alt="" class="w-20 h-20 rounded-full shadow-lg mx-auto mb-4">
+      <% end %>
+      <h1 class="text-3xl font-extrabold text-heading tracking-tight"><%= heading %></h1>
+      <% if subheading.present? %><p class="text-secondary mt-2"><%= subheading %></p><% end %>
+    </div>
+    <div class="card shadow p-8">
+      <%= render "studio/auth/sign_in_body", **body_locals %>
+    </div>
+  </div>
+</div>

data/app/views/studio/auth/_sign_in_modal.html.erb

@@ -0,0 +1,36 @@
+<%#
+  The engine's standard sign-in card, as a modal: the same body as
+  studio/auth/_sign_in_card (studio/auth/_sign_in_body), under a modal header
+  and a ×. Single root, for a modal host's <template x-if>:
+
+    <template x-if="$store.modals.current()?.id === 'sign-in'">
+      <div>render "studio/auth/sign_in_modal", return_to: request.path</div>
+    </template>
+
+    $store.modals.open('sign-in')
+
+  Locals: every local of studio/auth/_sign_in_card except logo, plus
+    modal_store — the Alpine store the × and the resend footer's Close close.
+                  Default "modals". VALIDATED as a JS identifier
+                  (Studio::JsIdentifier): it is spliced as a bare name.
+  dom_id defaults to "sign-in-modal", so a page can carry the page card and the
+  modal at once with no duplicate ids.
+%>
+<%
+  # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
+  modal_store = Studio::JsIdentifier.validate!(
+                local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
+  heading    = local_assigns[:heading].presence || Studio::AuthLabels.to_app(Studio.sign_in_label, Studio.app_name)
+  subheading = local_assigns.key?(:subheading) ? local_assigns[:subheading] : "New here? The same step creates your account."
+  body_locals = local_assigns.slice(:return_to, :preamble, :extras, :google, :magic_link, :magic_link_path,
+                                    :email, :demo, :google_label, :send_label)
+                             .merge(dom_id: local_assigns.fetch(:dom_id, "sign-in-modal"), modal_store: modal_store)
+%>
+<div class="relative text-left" data-sign-in-modal>
+  <%= render "studio/modals/blocks/close_x", modal_store: modal_store %>
+  <div class="mb-5 pr-6">
+    <h3 class="text-heading font-bold text-xl leading-tight"><%= heading %></h3>
+    <% if subheading.present? %><p class="text-secondary text-sm mt-1"><%= subheading %></p><% end %>
+  </div>
+  <%= render "studio/auth/sign_in_body", **body_locals %>
+</div>

data/app/views/studio/modals/auth/_resend_footer.html.erb

@@ -10,6 +10,9 @@
 
   Locals:
     modal_store — Alpine store name backing close(). Default "modals".
+    close       — default true. false drops the Close button, for a host that
+                  is not a modal (studio/auth/_sign_in_card on a page), where
+                  there is no store to close.
 
   ERROR INK, not a static red. The error paragraph is text-danger-ink, the
   per-theme red Studio::ThemeResolver derives to a 4.5:1 target. It replaced
@@ -38,6 +41,7 @@
   # IDENTIFIER position ($store.<name>) — VALIDATED, never escaped: Studio::JsIdentifier.
   modal_store = Studio::JsIdentifier.validate!(
                 local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
+  show_close = local_assigns.fetch(:close, true)
 %>
 <button @click="resendMagicLink()" :disabled="props.submitting === 'magic-link' || (props.resendCooldown || 0) > 0"
         class="block mx-auto text-sm text-primary hover:text-primary-300 underline underline-offset-2 disabled:opacity-50 disabled:no-underline">
@@ -48,4 +52,6 @@
   </span>
 </button>
 <p role="alert" x-show="props.resendError" x-cloak class="text-xs text-danger-ink mt-3 text-center" x-text="props.resendError"></p>
+<% if show_close %>
 <button @click="$store.<%= modal_store %>.close()" class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">Close</button>
+<% end %>

data/app/views/style/_glass.html.erb

@@ -15,8 +15,7 @@
   </div>
   <div class="grid gap-4 md:grid-cols-2">
     <%= render layout: "style/specimen",
-          locals: { klass: "Studio.surface_style = :glass",
-                    usage: %(config.surface_style = :glass, and <html data-surface-style="glass">),
+          locals: { trick: "glass",
                     disabled: !surface_on, disabled_label: "surface style is off on this app" } do %>
       <div class="<%= glass_backing %> w-full space-y-2" data-test="style-glass-surfaces">
         <div class="card p-3 text-sm text-heading">.card, the dense tier: no blur</div>
@@ -24,8 +23,7 @@
       </div>
     <% end %>
     <%= render layout: "style/specimen",
-          locals: { klass: "Studio.sidebar_style = :glass",
-                    usage: %(config.sidebar_style = :glass),
+          locals: { trick: "glass_sidebar",
                     disabled: !sidebar_on, disabled_label: "glass sidebar is off on this app" } do %>
       <div class="<%= glass_backing %> w-full" data-test="style-glass-sidebar">
         <div class="flex flex-col" data-sidebar-glass-shell>
@@ -42,8 +40,7 @@
       <% end %>
     <% end %>
     <%= render layout: "style/specimen",
-          locals: { klass: "Lit from above, under surface_style = :glass",
-                    usage: %(.btn-primary, .btn-danger, .btn-neutral, .badge, .input-field),
+          locals: { trick: "glass", variant: "lit",
                     disabled: !surface_on, disabled_label: "surface style is off on this app" } do %>
       <div class="w-full overflow-x-auto" data-test="style-lit-states">
         <table class="text-xs text-muted">
@@ -68,8 +65,7 @@
       </div>
     <% end %>
     <%= render layout: "style/specimen",
-          locals: { klass: "studio_icon(name, size: 18)",
-                    usage: %(studio_icon("rocket", size: 22)) } do %>
+          locals: { trick: "icon" } do %>
       <ul class="grid grid-cols-4 gap-3 w-full text-heading" data-test="style-glass-icons">
         <% Studio::Icons.names.each do |name| %>
           <li class="flex flex-col items-center gap-1 min-w-0" title="<%= name %>">