studio-engine 0.96.2.rc1 → 0.97.0.rc1

data/app/javascript/studio/survey.js

@@ -0,0 +1,316 @@
+// studio/survey: the survey stepper, a progressive enhancement over
+// studio/surveys/show. It adds .is-enhanced and turns the page's own markup
+// into one question at a time, with autosave. Plain DOM, no Alpine.
+//
+// IDEMPOTENT PER ROOT, so a second connect never double-binds. Bound roots are
+// tracked in a WeakSet, never in a DOM attribute: Turbo's snapshot cache clones
+// the page, and a clone keeps every attribute but none of the listeners, so a
+// marker in the DOM would make a restored page look set up while it is dead.
+//
+// AUTOSAVE IS BEST EFFORT: the final Submit posts the whole form, so a failed
+// autosave loses nothing. Without this module the page is the plain form, every
+// question on one page, and it submits the same answers.
+//
+// It imports nothing; test/javascript/survey.test.mjs loads it as a data:
+// module. Bound to the page by the survey controller.
+
+var bound = new WeakSet();
+
+export function typeOf(step) { return step.dataset.type || ""; }
+export function isChoice(step) { return /^(emoji_scale|rating|choice)$/.test(typeOf(step)); }
+export function isMulti(step) { return typeOf(step) === "multi_choice"; }
+export function inputs(step) { return Array.prototype.slice.call(step.querySelectorAll("input.studio-survey__input")); }
+
+// A step's answer: the checked values of a multi-choice, the checked value of
+// a choice or scale, or the trimmed text. Blank is "" (or [] for a
+// multi-choice).
+export function valueOf(step) {
+  if (isMulti(step)) return inputs(step).filter(function (i) { return i.checked; }).map(function (i) { return i.value; });
+  if (isChoice(step)) {
+    var picked = inputs(step).filter(function (i) { return i.checked; })[0];
+    return picked ? picked.value : "";
+  }
+  var field = step.querySelector("[data-survey-text]");
+  return field ? field.value.trim() : "";
+}
+
+export function answered(step) {
+  var v = valueOf(step);
+  return Array.isArray(v) ? v.length > 0 : v !== "";
+}
+
+// The progress bar's width for question `position` of `total`.
+export function progressWidth(position, total) {
+  return (total ? (position / total) * 100 : 0) + "%";
+}
+
+// Where the stepper opens. A fresh visitor lands on question 1; a returning
+// one on their next question (resume-index is the question's own index, and
+// every step is a question); a page restored from Turbo's cache on the step it
+// was left on (`restored`, -1 when it was not restored).
+export function startIndex(resume, total, restored) {
+  var start = resume === "" || resume === undefined ? 0 : parseInt(resume, 10);
+  if (!(start >= 0 && start < total)) start = 0;
+  if (restored >= 0) start = restored;
+  return start;
+}
+
+// Enhances one [data-studio-survey] root. Answers false for a root it has
+// already bound.
+export function enhanceSurvey(root, win = window, doc = document) {
+  if (bound.has(root)) return false;
+  bound.add(root);
+
+  var form = root.querySelector("[data-survey-form]");
+  var steps = Array.prototype.slice.call(root.querySelectorAll("[data-survey-step]"));
+  // Every step is a question: the survey opens on question 1, no intro screen.
+  var total = steps.length;
+  var head = root.querySelector("[data-survey-head]");
+  var back = root.querySelector("[data-survey-back]");
+  var next = root.querySelector("[data-survey-next]");
+  var submit = root.querySelector("[data-survey-submit]");
+  var top = root.querySelector("[data-survey-top]");
+  var bar = root.querySelector("[data-survey-progress]");
+  var fill = root.querySelector("[data-survey-progress-fill]");
+  var count = root.querySelector("[data-survey-count]");
+  var status = root.querySelector("[data-survey-status]");
+  var hint = root.querySelector("[data-survey-hint]");
+  // A page restored from Turbo's cache comes back on the step it was left
+  // on; resume there rather than at the server's original resume point.
+  var restored = -1;
+  // The GLOBAL token, not the form's: with per_form_csrf_tokens on, the
+  // form's hidden token is bound to the POST and refused on the PATCH.
+  var csrf = root.dataset.csrf || "";
+  var reduce = win.matchMedia && win.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  var saved = {};
+  var timers = {};
+  var current = -1;
+  var pointerPick = false;
+  var submitting = false;
+
+  form.noValidate = true;
+  if (root.classList.contains("is-enhanced")) {
+    Array.prototype.forEach.call(root.querySelectorAll("[data-survey-step]"), function (step, i) {
+      if (step.classList.contains("is-active")) restored = i;
+    });
+  }
+  root.classList.add("is-enhanced");
+  top.hidden = false;
+
+  function setError(step, message) {
+    var el = step.querySelector("[data-survey-error]");
+    if (!el) return;
+    el.textContent = message || "";
+    el.hidden = !message;
+    step.classList.toggle("is-invalid", !!message);
+  }
+
+  function save(step) {
+    var key = step.dataset.key;
+    if (!key || submitting) return Promise.resolve(true);
+    var value = valueOf(step);
+    var fingerprint = JSON.stringify(value);
+    if (saved[key] === fingerprint) return Promise.resolve(true);
+
+    var body = new win.FormData();
+    if (Array.isArray(value)) {
+      if (value.length === 0) body.append("value[]", "");
+      value.forEach(function (v) { body.append("value[]", v); });
+    } else {
+      body.append("value", value);
+    }
+    var url = root.dataset.answerBase + encodeURIComponent(key);
+    status.textContent = "Saving…";
+    return win.fetch(url, {
+      method: "PATCH",
+      body: body,
+      credentials: "same-origin",
+      headers: { "Accept": "application/json", "X-CSRF-Token": csrf }
+    }).then(function (res) {
+      // fetch resolves on a 4xx/5xx — the status is the only signal.
+      if (!res.ok) {
+        return res.json().catch(function () { return {}; }).then(function (data) {
+          if (res.status === 422 && data.error) setError(step, data.error);
+          status.textContent = "Not saved yet — your answers still go in when you submit.";
+          return false;
+        });
+      }
+      saved[key] = fingerprint;
+      status.textContent = "Saved";
+      return true;
+    }).catch(function () {
+      status.textContent = "Offline? Your answers still go in when you submit.";
+      return false;
+    });
+  }
+
+  function render(index, direction) {
+    steps.forEach(function (step, i) {
+      var active = i === index;
+      step.hidden = !active;
+      step.classList.toggle("is-active", active);
+      if (active) {
+        if (direction && !reduce) step.dataset.dir = direction; else delete step.dataset.dir;
+      }
+    });
+    current = index;
+    var first = index === 0;
+    var last = index === steps.length - 1;
+    // Nothing comes before question 1, so it has no Back. Next keeps the
+    // right edge on its own (margin-left: auto), so the row does not shift.
+    back.hidden = first;
+    next.hidden = last;
+    submit.hidden = !last;
+    // The title and intro lead question 1 only; later screens show the
+    // question alone. The head steps into a visual clip rather than
+    // `hidden`, so the page keeps its h1 for a screen reader on every step.
+    if (head) head.classList.toggle("studio-survey__head--later", !first);
+    // The number-key shortcut only means something on a choice or scale.
+    var step = steps[index];
+    hint.hidden = !(step.dataset.key && (isChoice(step) || isMulti(step)));
+
+    var position = index + 1;
+    fill.style.width = progressWidth(position, total);
+    bar.setAttribute("aria-valuenow", String(position));
+    count.textContent = "Question " + position + " of " + total;
+
+    var focusTarget = steps[index].querySelector("[data-survey-focus]");
+    if (focusTarget && direction) focusTarget.focus({ preventScroll: true });
+    if (direction) win.scrollTo({ top: 0, behavior: reduce ? "auto" : "smooth" });
+  }
+
+  function go(index) {
+    if (index < 0 || index >= steps.length || index === current) return;
+    render(index, index > current ? "fwd" : "back");
+  }
+
+  function forward() {
+    var step = steps[current];
+    if (step.dataset.key) {
+      if (step.dataset.required === "true" && !answered(step)) {
+        setError(step, "This one is required.");
+        var first = step.querySelector("input:not([type=hidden]), textarea");
+        if (first) first.focus();
+        return;
+      }
+      setError(step, "");
+    }
+    if (current === steps.length - 1) {
+      // No autosave here: the POST carries every answer, and a PATCH racing
+      // it would land after completion and be refused.
+      submitForm();
+    } else {
+      if (step.dataset.key) save(step);
+      go(current + 1);
+    }
+  }
+
+  function submitForm() {
+    if (form.requestSubmit) form.requestSubmit(submit); else form.submit();
+  }
+
+  // The first required question still missing an answer, for a Submit that
+  // jumps ahead (Enter on the last step, or a mid-survey reload).
+  form.addEventListener("submit", function (event) {
+    for (var i = 0; i < steps.length; i++) {
+      if (steps[i].dataset.required === "true" && !answered(steps[i])) {
+        event.preventDefault();
+        go(i);
+        setError(steps[i], "This one is required.");
+        return;
+      }
+    }
+    Object.keys(timers).forEach(function (key) { win.clearTimeout(timers[key]); });
+    submitting = true;
+    submit.disabled = true;
+    submit.textContent = "Sending…";
+  });
+
+  back.addEventListener("click", function () { go(current - 1); });
+  next.addEventListener("click", forward);
+
+  root.addEventListener("pointerdown", function (event) {
+    pointerPick = !!event.target.closest("[data-survey-choice]");
+  });
+
+  root.addEventListener("change", function (event) {
+    var step = event.target.closest("[data-survey-step]");
+    if (!step || !step.dataset.key || step.hidden) return;
+    setError(step, "");
+    if (isChoice(step)) {
+      save(step);
+      // Advance on a tap or a number key, never on arrow keys: arrows move
+      // through a radio group and must not jump the reader off the question.
+      if (pointerPick) {
+        pointerPick = false;
+        win.setTimeout(function () { if (steps[current] === step) forward(); }, reduce ? 0 : 260);
+      }
+    } else if (isMulti(step)) {
+      save(step);
+    }
+  });
+
+  root.addEventListener("input", function (event) {
+    var field = event.target.closest("[data-survey-text]");
+    if (!field) return;
+    var step = field.closest("[data-survey-step]");
+    var counter = step.querySelector("[data-survey-counter]");
+    if (counter) counter.textContent = String(field.value.length);
+    win.clearTimeout(timers[step.dataset.key]);
+    timers[step.dataset.key] = win.setTimeout(function () { save(step); }, 900);
+  });
+
+  function onKey(event) {
+    if (event.defaultPrevented || event.altKey) return;
+    // A tap on an already-chosen option fires pointerdown but no change, so
+    // the flag would outlive it and make the next arrow key advance.
+    pointerPick = false;
+    var step = steps[current];
+    var target = event.target;
+    var inText = target.matches && target.matches("textarea, input[type=text]");
+
+    if (event.key === "Enter") {
+      if (target.tagName === "BUTTON" || target.tagName === "A") return;
+      if (target.tagName === "TEXTAREA" && !(event.metaKey || event.ctrlKey)) return;
+      event.preventDefault();
+      forward();
+      return;
+    }
+
+    if (inText || event.metaKey || event.ctrlKey || !/^[1-9]$/.test(event.key)) return;
+    if (!step.dataset.key || !(isChoice(step) || isMulti(step))) return;
+    var option = inputs(step)[parseInt(event.key, 10) - 1];
+    if (!option) return;
+    event.preventDefault();
+    option.checked = isMulti(step) ? !option.checked : true;
+    option.focus({ preventScroll: true });
+    pointerPick = isChoice(step);
+    option.dispatchEvent(new win.Event("change", { bubbles: true }));
+  }
+
+  root.addEventListener("keydown", onKey);
+  // The survey opens on question 1 with nothing focused, so a first key
+  // lands on <body>, outside the root. Take those keys too, and only those:
+  // a key aimed at any other control on the page is not the survey's. The
+  // listener retires itself once a Turbo visit has taken this root away.
+  function onPageKey(event) {
+    if (!root.isConnected) { doc.removeEventListener("keydown", onPageKey); return; }
+    var target = event.target;
+    if (target === doc.body || target === doc.documentElement) onKey(event);
+  }
+  doc.addEventListener("keydown", onPageKey);
+
+  var hasErrors = root.dataset.hasErrors === "true";
+  // A failed submit lands on the first question it flagged: the server sets
+  // resume-index to it.
+  var start = startIndex(root.dataset.resumeIndex, steps.length, restored);
+  render(start, null);
+  if (restored < 0 && (start > 0 || hasErrors)) {
+    var focusTarget = steps[current].querySelector("[data-survey-focus]");
+    if (focusTarget) focusTarget.focus({ preventScroll: true });
+    if (start > 0 && !hasErrors) status.textContent = "Welcome back — picking up where you left off.";
+  }
+  // Answers already on the page are already stored.
+  steps.forEach(function (step) { if (step.dataset.key) saved[step.dataset.key] = JSON.stringify(valueOf(step)); });
+  return true;
+}

data/app/javascript/studio/theme_editor.js

@@ -0,0 +1,197 @@
+// studio/theme_editor: the two live-preview theme editors, as the Alpine
+// factories their templates bind.
+//
+//   themeEditor(colors)    theme_settings/edit, the standalone /admin/theme page
+//   dsThemeEditor(seed)    style/_theme, the Theme section of the style guide
+//
+// Both are seeded with the server-resolved role colours and write the themeable
+// role variables on the document as the operator types, so every specimen on
+// the page restyles at once. The inputs still carry the real values.
+//
+// studio/alpine_shims publishes both as window globals before Alpine starts,
+// because x-data="themeEditor(...)" is evaluated the moment Alpine does.
+//
+// It imports nothing; test/javascript/theme_editor.test.mjs loads it as a
+// data: module.
+
+// The seven roles the standalone editor edits, in the order it lists them.
+export const ROLES = ["primary", "success", "accent", "warning", "danger", "dark", "light"]
+
+// A typed colour as #rrggbb: a missing # is added and a 3-digit hex is doubled.
+// Answers null for anything that is not a 3- or 6-digit hex.
+export function normalizeHex(value) {
+  let hex = String(value == null ? "" : value).trim()
+  if (!hex.startsWith("#")) hex = "#" + hex
+  if (/^#[0-9a-fA-F]{3}$/.test(hex)) {
+    hex = "#" + hex[1] + hex[1] + hex[2] + hex[2] + hex[3] + hex[3]
+  }
+  return /^#[0-9a-fA-F]{6}$/.test(hex) ? hex : null
+}
+
+// `hex` (#rrggbb) moved `amount` (0..1) of the way to white.
+export function lightenColor(hex, amount) {
+  hex = hex.replace("#", "")
+  const r = parseInt(hex.substring(0, 2), 16)
+  const g = parseInt(hex.substring(2, 4), 16)
+  const b = parseInt(hex.substring(4, 6), 16)
+  const nr = Math.round(r + (255 - r) * amount)
+  const ng = Math.round(g + (255 - g) * amount)
+  const nb = Math.round(b + (255 - b) * amount)
+  return "#" + [nr, ng, nb].map((c) => c.toString(16).padStart(2, "0")).join("")
+}
+
+// The standalone editor's colours: every role present, blank when the server
+// resolved none.
+export function seededColors(seed) {
+  const colors = {}
+  ROLES.forEach((role) => { colors[role] = (seed && seed[role]) || "" })
+  return colors
+}
+
+// What the standalone editor writes on the root for `colors`, as
+// [property, value] pairs; a null value removes the property.
+//
+// btn-warning and btn-danger paint --color-<role>-fill first (the resolver
+// emits it for the engine defaults), so a typed colour sets it too or the
+// specimens keep the default fill. A cleared colour drops the override.
+export function previewProperties(colors) {
+  const properties = [
+    ["--color-cta", colors.primary],
+    ["--color-success", colors.success],
+    ["--color-warning", colors.warning || "#FF7C47"],
+    ["--color-danger", colors.danger || "#EF4444"]
+  ]
+  for (const role of ["warning", "danger"]) {
+    properties.push([`--color-${role}-fill`, colors[role] ? colors[role] : null])
+  }
+  return properties
+}
+
+// What the style guide's editor writes on the root for `colors`. It sets only
+// what has a value and removes nothing.
+export function stylePreviewProperties(colors) {
+  const properties = [
+    ["--color-cta", colors.primary],
+    ["--color-cta-fill", colors.primary]
+  ]
+  if (colors.success) properties.push(["--color-success", colors.success])
+  if (colors.warning) properties.push(["--color-warning", colors.warning], ["--color-warning-fill", colors.warning])
+  if (colors.danger) properties.push(["--color-danger", colors.danger], ["--color-danger-fill", colors.danger])
+  return properties
+}
+
+function applyProperties(style, properties) {
+  for (const [name, value] of properties) {
+    if (value === null) style.removeProperty(name)
+    else style.setProperty(name, value)
+  }
+}
+
+// x-data="themeEditor({...})": theme_settings/edit.
+export function themeEditor(seed) {
+  return {
+    colors: seededColors(seed),
+
+    resetColor(role, defaultVal) {
+      this.colors[role] = defaultVal
+      this.updatePreview()
+    },
+
+    normalizeHex(role) {
+      const hex = normalizeHex(this.colors[role])
+      if (hex) this.colors[role] = hex
+      this.updatePreview()
+    },
+
+    // Live CSS variables on the document, for immediate feedback.
+    updatePreview() {
+      applyProperties(document.documentElement.style, previewProperties(this.colors))
+    },
+
+    darkPreviewStyle() {
+      return { backgroundColor: this.colors.dark, borderRadius: "0" }
+    },
+
+    darkSurfaceStyle() {
+      return {
+        backgroundColor: this.lightenColor(this.colors.dark, 0.3),
+        border: "1px solid rgba(255,255,255,0.1)"
+      }
+    },
+
+    lightPreviewStyle() {
+      return { backgroundColor: this.colors.light, borderRadius: "0" }
+    },
+
+    lightSurfaceStyle() {
+      return { backgroundColor: "#ffffff", border: "1px solid #e2e8f0" }
+    },
+
+    lightenColor(hex, amount) {
+      return lightenColor(hex, amount)
+    }
+  }
+}
+
+// The method a form really sends, and its body without Rails' _method override.
+// The editor's form carries _method=patch, and sending the real method means
+// nothing depends on Rack::MethodOverride parsing a multipart fetch body.
+//
+// THE REDIRECT IS NOT FOLLOWED. The controller answers a save with a 302 back
+// to /admin/theme, and a fetch that follows a 302 keeps a PATCH a PATCH: it
+// sends the save again on every hop until the browser gives up.
+export function formRequest(data) {
+  const override = data.get("_method")
+  if (override) data.delete("_method")
+  return { method: override ? String(override).toUpperCase() : "POST", body: data, redirect: "manual" }
+}
+
+// Whether the server took the save: a 2xx, or its own redirect (which a fetch
+// told not to follow reports as an opaque redirect). A failed save is rendered
+// in place with a 422.
+export function saved(response) {
+  return response.ok || response.type === "opaqueredirect"
+}
+
+// x-data="dsThemeEditor({...})": style/_theme.
+//
+// SAVE IN PLACE. Save and Regenerate submit by fetch and stay on the style
+// guide: the form's @submit.prevent stops the browser navigating to
+// /admin/theme, the live preview persists, and the outcome is a toast (the
+// engine's `toast` window event). The form's own POST still works when Alpine
+// never loads.
+export function dsThemeEditor(seed) {
+  return {
+    colors: Object.assign({
+      primary: "#000", dark: "#0f172a", light: "#ffffff",
+      success: "#367E3A", warning: "#FF7C47", danger: "#EF4444",
+      accent: "#6366F1"
+    }, seed || {}),
+    saving: false,
+
+    updatePreview() {
+      applyProperties(document.documentElement.style, stylePreviewProperties(this.colors))
+    },
+
+    persist(form, label) {
+      if (this.saving) return
+      this.saving = true
+      const request = formRequest(new FormData(form))
+      fetch(form.action, request)
+        .then((res) => {
+          if (!saved(res)) throw new Error("HTTP " + res.status)
+          return res
+        })
+        .then(() => { this.toast("notice", label, "Saved in place — the page stayed put.") })
+        .catch((err) => { this.toast("alert", "Save failed", String((err && err.message) || err)) })
+        .finally(() => { this.saving = false })
+    },
+
+    toast(type, title, message) {
+      window.dispatchEvent(new CustomEvent("toast", { detail: { type: type, title: title, message: message } }))
+    },
+
+    saveTheme(e) { this.persist(e.target, "Theme saved") },
+    regenerate(e) { this.persist(e.target, "Theme cache cleared") }
+  }
+}