studio-engine 0.97.0 → 0.98.0

data/app/javascript/studio/style_guide.js

@@ -0,0 +1,13 @@
+// studio/style_guide: the living style guide's own controllers, registered on
+// the engine's Stimulus application. style/_modals loads this module by its
+// own nonced module tag, so only the style guide fetches it and it stays out of
+// the every-page boot graph.
+//
+// A module tag and not an entry in studio/stimulus's LAZY table: the tag runs
+// with the page, in document order, so the section's controller is connected
+// by the time the document has loaded, and a script or a spec that drives the
+// demos the moment the page is up finds them there.
+import { application } from "studio/stimulus"
+import StyleModalsController from "studio/controllers/style_modals_controller"
+
+application.register("style-modals", StyleModalsController)

data/app/javascript/studio/style_modals.js

@@ -0,0 +1,214 @@
+// studio/style_modals: what drives the living style guide's Modals section
+// (style/_modals): the stack-behaviour demos, the enter/leave simulator whose
+// controls are built from the live animation registry, and the stubs the
+// wallet specimens need to run with no wallet.
+//
+// The section's own modal host is the engine's stack under the name dsModals
+// (studio/modal_host registers it from the overlay's data attributes), so what
+// the guide shows is the store an app runs. The style-modals controller binds
+// this module to the section.
+//
+// It imports nothing; test/javascript/style_modals.test.mjs loads it as a
+// data: module.
+
+// The card the stack demos drive: style/modals/_ds_stack_demo, which belongs
+// to the guide and to nothing that ships.
+export const VEHICLE = "ds-stack-demo"
+
+// The card the enter/leave simulator opens, so only the motion varies.
+export const ANIM_DEMO_ID = "email-change-pending"
+export const ANIM_DEMO_PROPS = { currentEmail: "you@example.com", newEmail: "new@example.com" }
+
+// The four containers the simulator fills.
+export const ANIM_CONTROL_IDS = {
+  enterButtons: "modal-anim-enter-buttons",
+  exitButtons: "modal-anim-exit-buttons",
+  enterSelect: "modal-anim-enter-select",
+  exitSelect: "modal-anim-exit-select"
+}
+
+// A pending operation, as the vehicle opens: not dismissible, like a real one.
+export const PENDING = {
+  state: "processing",
+  title: "Submitting entry",
+  message: "Awaiting confirmation",
+  dismissible: false
+}
+
+export const SUCCESS = {
+  state: "success",
+  title: "Entry confirmed",
+  message: "Resolved in place — this is the same stack entry you opened.",
+  dismissible: true
+}
+
+export const FAILURE = {
+  state: "error",
+  title: "Submission failed",
+  message: "The error face of that same entry, patched in by advance().",
+  dismissible: true
+}
+
+// How long the wallet stub takes to answer, so the picker's connecting state
+// is visible.
+export const WALLET_CONNECT_MS = 1100
+
+// "Pop (default)", "Shake": a registry key as a control's label.
+export function animationLabel(key) {
+  return key.charAt(0).toUpperCase() + key.slice(1) + (key === "pop" ? " (default)" : "")
+}
+
+// The registry the page holds, read when asked and never copied: a key an app
+// registers later grows a control on the next build.
+export function animationRegistry(win) {
+  const registry = win.ModalAnimations || {}
+  return { enter: registry.enter || {}, exit: registry.exit || {} }
+}
+
+// How long a round trip holds the card before closing it: its entrance's own
+// registry duration plus a beat.
+export function roundTripHoldMs(win, enterAnim) {
+  const entrance = animationRegistry(win).enter[enterAnim] || {}
+  return (entrance.ms || 320) + 700
+}
+
+// The stubs solana-studio's wallet picker needs on a page with no wallet:
+// a connect that performs none and answers success after a beat, and a
+// provider that lists two wallets and has neither. A page that ships a real
+// one keeps it.
+export function installWalletStubs(win) {
+  win.dsWalletConnectDemo = win.dsWalletConnectDemo || function () {
+    return new Promise(function (resolve) {
+      win.setTimeout(function () { resolve({ success: true }) }, WALLET_CONNECT_MS)
+    })
+  }
+  win.walletProvider = win.walletProvider || {
+    available: function () { return [{ name: "Phantom" }, { name: "Solflare" }] },
+    isMobile: function () { return false },
+    isAvailable: function () { return false }
+  }
+}
+
+// The demo drivers. env: { win, doc, store } — the window, the document the
+// simulator's controls live in, and the name of the section's modal store.
+export function createModalDemos(env) {
+  const win = env.win
+  const doc = env.doc
+  const storeName = env.store || "dsModals"
+  const store = () => win.Alpine.store(storeName)
+  const element = (id) => doc.getElementById(id)
+
+  function openDemo(props) {
+    store().open(VEHICLE, Object.assign({}, PENDING, props || {}))
+  }
+
+  // A state change on the card already open. advance() patches props without
+  // replacing the stack entry, so the vehicle's scope survives. Only a
+  // still-open vehicle is patched: a timer that fires after the card closed
+  // does nothing to whatever is on top now.
+  function advanceDemo(patch) {
+    const current = store().current()
+    if (!current || current.id !== VEHICLE || current._closing) return
+    store().advance(patch)
+  }
+
+  function animOpen(enterAnim, exitAnim) {
+    store().open(ANIM_DEMO_ID, Object.assign({}, ANIM_DEMO_PROPS, { enterAnim, exitAnim }))
+  }
+
+  // Open, let the entrance settle, then close, so the chosen exit is what
+  // plays.
+  function animRoundTrip(enterAnim, exitAnim) {
+    animOpen(enterAnim, exitAnim)
+    win.setTimeout(function () { store().close() }, roundTripHoldMs(win, enterAnim))
+  }
+
+  // Builds the quick buttons and the select options from the live registry.
+  // Each container is emptied first, so building again doubles nothing.
+  function buildAnimControls() {
+    const registry = animationRegistry(win)
+    const enterButtons = element(ANIM_CONTROL_IDS.enterButtons)
+    const exitButtons = element(ANIM_CONTROL_IDS.exitButtons)
+    const enterSelect = element(ANIM_CONTROL_IDS.enterSelect)
+    const exitSelect = element(ANIM_CONTROL_IDS.exitSelect)
+
+    const addOption = function (select, key) {
+      if (!select) return
+      const option = doc.createElement("option")
+      option.value = key
+      option.textContent = animationLabel(key)
+      if (key === "pop") option.selected = true
+      select.appendChild(option)
+    }
+    const addButton = function (container, key, onClick, suffix) {
+      if (!container) return
+      const button = doc.createElement("button")
+      button.type = "button"
+      button.className = "btn btn-outline btn-sm"
+      button.textContent = animationLabel(key) + (suffix || "")
+      button.onclick = onClick
+      container.appendChild(button)
+    }
+
+    ;[enterButtons, exitButtons, enterSelect, exitSelect].forEach(function (node) {
+      if (node) node.innerHTML = ""
+    })
+
+    Object.keys(registry.enter).forEach(function (key) {
+      addButton(enterButtons, key, function () { animOpen(key, "pop") }, " ↗")
+      addOption(enterSelect, key)
+    })
+    Object.keys(registry.exit).forEach(function (key) {
+      addButton(exitButtons, key, function () { animRoundTrip("pop", key) })
+      addOption(exitSelect, key)
+    })
+  }
+
+  return {
+    buildAnimControls,
+
+    // Stack behaviour
+    processing: function () { openDemo({}) },
+    success: function () { openDemo(SUCCESS) },
+    error: function () { openDemo(FAILURE) },
+    processThenSuccess: function () {
+      openDemo({ message: "Awaiting RPC confirmation" })
+      win.setTimeout(function () { advanceDemo(SUCCESS) }, 3000)
+    },
+    processThenError: function () {
+      openDemo({ message: "Awaiting RPC confirmation" })
+      win.setTimeout(function () { advanceDemo(FAILURE) }, 3000)
+    },
+    dismissible: function () {
+      openDemo({
+        dismissible: true,
+        title: "Dismissible processing",
+        message: "Escape and click-outside both close this one."
+      })
+    },
+    fastWithHold: function () {
+      openDemo({ title: "Fast operation", message: "Holding the spinner for at least 1500ms" })
+      win.StudioModals.holdAtLeast(1500).then(function () { advanceDemo(SUCCESS) })
+    },
+    fastNoHold: function () {
+      openDemo({ title: "Fast operation", message: "No hold, so this flashes past" })
+      win.setTimeout(function () { advanceDemo(SUCCESS) }, 50)
+    },
+    stackTwo: function () {
+      openDemo({
+        dismissible: true,
+        title: "Bottom of the stack",
+        message: "A second card is about to push in front of this one."
+      })
+      win.setTimeout(function () { store().open(ANIM_DEMO_ID, ANIM_DEMO_PROPS) }, 700)
+    },
+
+    // Enter / leave simulator
+    animOpenSelected: function () {
+      animOpen(element(ANIM_CONTROL_IDS.enterSelect).value, element(ANIM_CONTROL_IDS.exitSelect).value)
+    },
+    animRoundTripSelected: function () {
+      animRoundTrip(element(ANIM_CONTROL_IDS.enterSelect).value, element(ANIM_CONTROL_IDS.exitSelect).value)
+    }
+  }
+}

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

@@ -8,6 +8,9 @@
     Distinct from imageUploadHost (immediate-save): this STAGES the file and
     lets the enclosing form own the submit (signup / profile edit).
 
+    The scope, avatarCropperHost(), is studio/image_upload, published on every
+    page by studio/alpine_scopes.
+
     Locals: form_field_name (e.g. "user[avatar]"). %>
 
 <%= render "studio/cropper_assets" %>
@@ -41,41 +44,3 @@
   <input type="file" x-ref="filePicker" @change="onFileSelected($event)" accept="image/*" class="hidden">
 </div>
 
-<script>
-function avatarCropperHost() {
-  return {
-    croppedUrl: null,
-
-    onFileSelected(event) {
-      var file = event.target.files[0];
-      if (!file) return;
-      var self = this;
-      var reader = new FileReader();
-      reader.onload = function(e) {
-        // Hand the raw image to the shared modal host; the crop-photo modal
-        // owns the cropper UI and posts back via 'crop-photo-confirmed'.
-        Alpine.store('modals').open('crop-photo', { imageUrl: e.target.result });
-      };
-      reader.readAsDataURL(file);
-      event.target.value = '';  // allow re-selecting the same file
-    },
-
-    applyCrop(blob) {
-      if (!blob) return;
-      if (this.croppedUrl) URL.revokeObjectURL(this.croppedUrl);
-      this.croppedUrl = URL.createObjectURL(blob);
-      var file = new File([blob], 'avatar.png', { type: 'image/png' });
-      var dt = new DataTransfer();
-      dt.items.add(file);
-      this.$refs.hiddenFileInput.files = dt.files;
-    },
-
-    removePhoto() {
-      if (this.croppedUrl) URL.revokeObjectURL(this.croppedUrl);
-      this.croppedUrl = null;
-      var dt = new DataTransfer();
-      this.$refs.hiddenFileInput.files = dt.files;
-    }
-  };
-}
-</script>

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

@@ -1,4 +1,4 @@
-<%# The request's CSP nonce, for the two inline scripts left in this head and
+<%# The request's CSP nonce, for the three inline scripts left in this head and
     for javascript_import_module_tag below (importmap-rails nonces its own tags).
     nil when the host sets no nonce generator, and then no attribute renders. %>
 <% studio_script_nonce = (content_security_policy_nonce if respond_to?(:content_security_policy_nonce)) %>
@@ -12,10 +12,14 @@
     }
   })();
 <% end %>
-<%# THE HOLD BUTTON'S GUARD. Inline, and the other inline script this head keeps:
+<%# THE HOLD BUTTON'S GUARD. Inline, one of the two guards this head keeps:
     it reports a hold button whose modules failed to load, so it can share no
     request with them (studio/_hold_button_guard). %>
 <%= render "studio/hold_button_guard", nonce: studio_script_nonce %>
+<%# THE X-DATA FACTORIES' GUARD. Inline for the same reason: it reports a profile
+    form, a birthday card or an upload whose factory failed to load
+    (studio/_alpine_scopes_guard), and shows the form's plain Save. %>
+<%= render "studio/alpine_scopes_guard", nonce: studio_script_nonce %>
 
 <meta name="viewport" content="width=device-width,initial-scale=1">
 <%# Studio.nav_spinner_min_ms, read by the nav spinner in studio/head_chrome. %>
@@ -198,6 +202,12 @@
     the document click and Escape handlers. It imports nothing, and the
     link-sidebar controller imports it. %>
 <%= javascript_import_module_tag "studio/link_sidebar" %>
+<%# THE X-DATA FACTORIES, BY THEIR OWN DOOR, for the same reason.
+    studio/alpine_scopes publishes the factories a page binds by name
+    (cropPhotoModal, imageUploadHost, submitFormWithProgress), each from the
+    module that owns it. Its imports import nothing, and studio/alpine_shims
+    imports it, so a failed boot leaves a page its uploads. %>
+<%= javascript_import_module_tag "studio/alpine_scopes" %>
 <%# ALPINE LOADS AFTER THE MODULE TAGS, and the order is the contract. Deferred
     classic scripts and module scripts execute in document order, so by the time
     Alpine starts, studio/application has defined the shims it evaluates

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

@@ -0,0 +1,178 @@
+<%#
+  THE X-DATA FACTORIES' GUARD: says so when a page's factories did not load.
+
+  The photo crop, the upload hosts, the birthday card and row and the profile
+  form bind an x-data factory by name (cropPhotoModal, imageUploadHost,
+  avatarCropperHost, birthdayModal, studioBirthdayFields, studioProfileForm),
+  and all six are published by studio/alpine_scopes from four modules
+  (studio/cropper, studio/image_upload, studio/birthday, studio/profile_form).
+  A browser keeps a failed module request for the life of the document, so one
+  failure among the five at page load leaves every name undefined until a
+  reload: the profile page with no Save, the birthday card with nothing to
+  press. This script is what speaks then, so it is INLINE and imports nothing:
+  it shares no request with the modules whose failure it reports.
+
+  Once the page's boot is over, an element whose x-data names a factory that is
+  not on window is marked, and a line is put first inside it:
+
+    <div x-data="studioProfileForm({...})" data-studio-scope-failed="studioProfileForm">
+      <p class="studio-scope-notice" role="status">This did not load. Reload the page.</p>
+
+  The line carries its own few styles (the danger ink, a border, weight), set
+  from here, so it reads as a notice in a host whose stylesheet has never heard
+  of it; .studio-scope-notice is there for a host that wants to restyle it. A
+  card a modal mounts later is marked when it arrives. A factory that turns up
+  afterwards takes the mark and the line away again.
+
+  A FORM IS NOT LEFT WITH NO WAY TO SUBMIT. Inside a marked element:
+    - every [data-studio-scope-fallback] is shown (its x-cloak and hidden come
+      off): the profile form's plain Save button is one, so a person can still
+      save;
+    - a text field Alpine emptied goes back to the value the server rendered,
+      unless the person is in it, so that Save sends what was on file and not
+      blanks.
+  The birthday card has no plain path (its submit is a fetch the factory
+  makes), so its line is the whole of what it offers: reload.
+
+  WHEN THE BOOT IS OVER. The engine's modules are module scripts in the head,
+  so DOMContentLoaded waits for them, however slow, and each has run or failed
+  by then. The 1.5 s after it is margin for a host that defines a factory of
+  the same name from a script of its own, not a race the page has to win.
+
+  Locals:
+    nonce - the request's CSP nonce, or nil (layouts/studio/_head passes it)
+%>
+<%= tag.script(nonce: local_assigns[:nonce]) do %>
+  (function () {
+    if (window.studioScopesGuard) return;
+
+    var NAMES = ["cropPhotoModal", "imageUploadHost", "avatarCropperHost", "birthdayModal", "studioBirthdayFields", "studioProfileForm"];
+    var BOUND = "[x-data]";
+    var FAILED = "data-studio-scope-failed";
+    var FALLBACK = "data-studio-scope-fallback";
+    var NOTICE_CLASS = "studio-scope-notice";
+    var NOTICE = "This did not load. Reload the page.";
+    // The danger ink is the theme's, held to AA on every surface; a host with
+    // no such token keeps the text colour around the line.
+    var NOTICE_STYLE = "display:block;margin:0 0 0.75rem;padding:0.5rem 0.75rem;" +
+      "border:1px solid currentColor;border-radius:0.5rem;font-size:0.875rem;font-weight:600;" +
+      "line-height:1.35;text-align:center;color:var(--color-danger-ink, var(--color-danger, inherit))";
+    var CALL = /^\s*([A-Za-z_$][\w$]*)\s*\(/;
+    var GRACE_MS = 1500;
+    var SETTLE_MS = 250;
+
+    var deadline = null;
+    var reported = false;
+
+    // The factory an x-data expression calls, when it is one of ours.
+    function scopeName(expression) {
+      var match = CALL.exec(expression || "");
+      return match && NAMES.indexOf(match[1]) !== -1 ? match[1] : null;
+    }
+
+    // What to do with one element. `deadline` is null until the page's boot has
+    // an end, and nothing is marked before it.
+    function verdict(state) {
+      if (!state.name) return "leave";
+      if (state.defined) return state.marked ? "clear" : "leave";
+      if (state.marked) return "leave";
+      if (state.deadline == null || state.now < state.deadline) return "wait";
+      return "mark";
+    }
+
+    function notice(element) {
+      for (var i = 0; i < element.children.length; i++) {
+        if (element.children[i].classList.contains(NOTICE_CLASS)) return element.children[i];
+      }
+      return null;
+    }
+
+    function each(element, selector, visit) {
+      var found = element.querySelectorAll(selector);
+      for (var i = 0; i < found.length; i++) visit(found[i]);
+    }
+
+    function mark(element, name) {
+      element.setAttribute(FAILED, name);
+      if (!notice(element)) {
+        var line = document.createElement("p");
+        line.className = NOTICE_CLASS;
+        line.setAttribute("role", "status");
+        line.style.cssText = NOTICE_STYLE;
+        line.textContent = NOTICE;
+        element.insertBefore(line, element.firstChild);
+      }
+      each(element, "[" + FALLBACK + "]", function (fallback) {
+        fallback.removeAttribute("x-cloak");
+        fallback.hidden = false;
+        fallback.style.display = "";
+        fallback.setAttribute(FALLBACK, "shown");
+      });
+      each(element, "input, textarea", function (field) {
+        if (field === document.activeElement) return;
+        if (field.type === "file" || field.type === "password" || field.type === "hidden") return;
+        if (field.type === "checkbox" || field.type === "radio") return;
+        if (field.value === "" && field.defaultValue !== "") field.value = field.defaultValue;
+      });
+      if (!reported) {
+        reported = true;
+        console.error("[studio] the page's x-data factories failed to load and stay unavailable until the page is reloaded");
+      }
+    }
+
+    function clear(element) {
+      var line = notice(element);
+      element.removeAttribute(FAILED);
+      if (line) element.removeChild(line);
+      each(element, "[" + FALLBACK + '="shown"]', function (fallback) {
+        fallback.setAttribute(FALLBACK, "");
+        fallback.setAttribute("x-cloak", "");
+      });
+    }
+
+    function judge(element) {
+      var name = scopeName(element.getAttribute("x-data"));
+      var answer = verdict({
+        name: name,
+        defined: !!name && typeof window[name] === "function",
+        marked: element.hasAttribute(FAILED),
+        now: Date.now(),
+        deadline: deadline
+      });
+      if (answer === "mark") mark(element, name);
+      if (answer === "clear") clear(element);
+      return answer;
+    }
+
+    function sweep() {
+      var bound = document.querySelectorAll(BOUND);
+      for (var i = 0; i < bound.length; i++) judge(bound[i]);
+    }
+
+    function binds(node) {
+      return node.nodeType === 1 && (node.matches(BOUND) || node.querySelector(BOUND) !== null);
+    }
+
+    function booted() {
+      deadline = Date.now() + GRACE_MS;
+      setTimeout(sweep, GRACE_MS);
+      // Read off window under a local name: a host page that counts the
+      // observers its own inline scripts construct does not count this one.
+      var Observer = window.MutationObserver;
+      if (!Observer) return;
+      new Observer(function (records) {
+        for (var i = 0; i < records.length; i++) {
+          for (var j = 0; j < records[i].addedNodes.length; j++) {
+            if (binds(records[i].addedNodes[j])) return void setTimeout(sweep, SETTLE_MS);
+          }
+        }
+      }).observe(document.documentElement, { childList: true, subtree: true });
+    }
+
+    if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", booted);
+    else booted();
+    document.addEventListener("turbo:load", function () { setTimeout(sweep, SETTLE_MS); });
+
+    window.studioScopesGuard = { names: NAMES, scopeName: scopeName, verdict: verdict, sweep: sweep, graceMs: GRACE_MS };
+  })();
+<% end %>