studio-engine 0.88.0 → 0.89.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e16f65ea44055886fea1ffb0743a9415caa612f858caa0ff7dabb7c87beeeb15
-  data.tar.gz: 9690ad40a9e766646995ddfa1c69c8c22191e3509bb944d5c184ea5c1a1b21e2
+  metadata.gz: eeb8af5c3521e31b4bda82538bc2053bf4ff364008f616454ce89aa267d30643
+  data.tar.gz: b4374bb37c27468e3b20df3656973a1818df2445aa7b0a0b6c242dc2d67f08fd
 SHA512:
-  metadata.gz: ae4786abebc9f1d9dc86cc3992f4a6f4225c4fceaa20b73fca12ddd43afad1e4d6ef2807a8d3302bdf2d811792995fdac42961a02c6b70637f8923e841e61402
-  data.tar.gz: 3ba6c43faf9e1f7a03596b70924fc099469d8c95ce967f63e4a2ba8f4f0da0112db6068e701e739fa7e3ce5435bd07ee456b2982fec91ebb9561a4bc3dd18b09
+  metadata.gz: c107ea4e17a719e1612a243550c0427bc5868e5ebc0219ab913e12312d4580fee715788afd80cdb6617f7ef4b8df799e67e8507fd3851db2d2f71e85fcf07bd0
+  data.tar.gz: f41f199936bd5bd48bf226b0df833679c956ca84671c86971f9a115b88c666885ebe4229814fd17b240cf8bed981da5660315dc75bdd8185ee9df4c51f185a1a

data/CHANGELOG.md

@@ -4,6 +4,22 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.89.0 — 2026-10-05
+
+### Changed
+
+- **A survey opens on question 1.** The intro screen and its Start button are
+  gone: a respondent lands on "Question 1 of N" with the progress bar started,
+  and question 1 shows no Back button. The definition's `intro` becomes a quiet
+  lead line above question 1, and its `title` stays the page's `h1`; when the
+  title repeats question 1 (`Studio::Survey#title_repeats_first_question?`), the
+  stepper hides it visually so the same words are not painted twice. Number keys
+  and Enter work from the first paint. Returning respondents still resume on
+  their first unanswered question, and the no-JavaScript form shows the title
+  and intro at the top. No host change is needed.
+- **The survey's "Press a number to choose" hint** no longer shows at phone width
+  (under 640px), as well as on touch screens.
+
 ## 0.88.0 — 2026-10-05
 
 ### Added

data/app/views/studio/surveys/_script.html.erb

@@ -19,7 +19,9 @@
 
     var form = root.querySelector("[data-survey-form]");
     var steps = Array.prototype.slice.call(root.querySelectorAll("[data-survey-step]"));
-    var total = steps.length - 1;
+    // 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]");
@@ -128,21 +130,23 @@
         }
       });
       current = index;
-      var onIntro = index === 0;
+      var first = index === 0;
       var last = index === steps.length - 1;
-      back.hidden = onIntro;
+      // 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;
-      next.textContent = onIntro ? "Start" : "Next";
       submit.hidden = !last;
+      // The title and intro lead question 1 only; later screens are the question alone.
+      if (head) head.hidden = !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 = onIntro ? 0 : index;
+      var position = index + 1;
       fill.style.width = (total ? (position / total) * 100 : 0) + "%";
       bar.setAttribute("aria-valuenow", String(position));
-      // The intro already says how many questions there are.
-      count.textContent = onIntro ? "" : "Question " + index + " of " + total;
+      count.textContent = "Question " + position + " of " + total;
 
       var focusTarget = steps[index].querySelector("[data-survey-focus]");
       if (focusTarget && direction) focusTarget.focus({ preventScroll: true });
@@ -182,7 +186,7 @@
     // 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 = 1; i < steps.length; i++) {
+      for (var i = 0; i < steps.length; i++) {
         if (steps[i].dataset.required === "true" && !answered(steps[i])) {
           event.preventDefault();
           go(i);
@@ -230,7 +234,7 @@
       timers[step.dataset.key] = setTimeout(function () { save(step); }, 900);
     });
 
-    root.addEventListener("keydown", function (event) {
+    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.
@@ -256,15 +260,29 @@
       option.focus({ preventScroll: true });
       pointerPick = isChoice(step);
       option.dispatchEvent(new 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) { document.removeEventListener("keydown", onPageKey); return; }
+      var target = event.target;
+      if (target === document.body || target === document.documentElement) onKey(event);
+    }
+    document.addEventListener("keydown", onPageKey);
 
     var resume = root.dataset.resumeIndex;
-    var start = resume === "" || resume === undefined ? 0 : parseInt(resume, 10) + 1;
+    // resume-index is the question's own index, and every step is a question.
+    var start = resume === "" || resume === undefined ? 0 : parseInt(resume, 10);
+    if (!(start >= 0 && start < steps.length)) start = 0;
     var hasErrors = root.dataset.hasErrors === "true";
-    // A fresh visitor sees the intro; a returning one lands on their next
+    // A fresh visitor lands on question 1; a returning one on their next
     // question, and a failed submit on the first question it flagged.
     if (restored >= 0) start = restored;
-    render(start > 0 ? start : 0, null);
+    render(start, null);
     if (restored < 0 && (start > 0 || hasErrors)) {
       var focusTarget = steps[current].querySelector("[data-survey-focus]");
       if (focusTarget) focusTarget.focus({ preventScroll: true });

data/app/views/studio/surveys/_styles.html.erb

@@ -18,6 +18,15 @@
   .studio-survey__title { margin: 0 0 .75rem; font-size: 1.75rem; line-height: 1.2; font-weight: 800; color: var(--color-text); outline: none; }
   .studio-survey__intro-copy { margin: 0 0 1rem; font-size: 1.0625rem; line-height: 1.55; color: var(--color-text-body); white-space: pre-line; }
   .studio-survey__meta { margin: 0; font-size: .8125rem; color: var(--color-text-muted); }
+  .studio-survey__head { margin: 0 0 2.25rem; }
+  /* Stepped, the head leads question 1 quietly: a small title (or none, when it
+     repeats question 1, kept for screen readers), the intro as one lead line,
+     and no meta, since the count above already says "Question 1 of N". */
+  .studio-survey.is-enhanced .studio-survey__head { margin-bottom: 1.25rem; }
+  .studio-survey.is-enhanced .studio-survey__title { margin: 0 0 .375rem; font-size: 1rem; line-height: 1.4; font-weight: 700; color: var(--color-text-secondary); }
+  .studio-survey.is-enhanced .studio-survey__head--echo .studio-survey__title { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
+  .studio-survey.is-enhanced .studio-survey__intro-copy { margin: 0; font-size: .9375rem; line-height: 1.5; color: var(--color-text-secondary); }
+  .studio-survey.is-enhanced .studio-survey__meta { display: none; }
   .studio-survey__question { display: block; width: 100%; padding: 0; margin: 0 0 .5rem; font-size: 1.375rem; line-height: 1.3; font-weight: 700; color: var(--color-text); outline: none; }
   .studio-survey__qnum { display: block; margin-bottom: .375rem; font-size: .75rem; font-weight: 600; letter-spacing: .06em; text-transform: uppercase; color: var(--color-text-muted); }
   .studio-survey.is-enhanced .studio-survey__qnum { display: none; }
@@ -68,7 +77,9 @@
   .studio-survey__forward { margin-left: auto; }
   .studio-survey__status { min-height: 1.25rem; margin: .5rem 0 0; font-size: .75rem; text-align: center; color: var(--color-text-muted); }
   .studio-survey__hint { margin: .25rem 0 0; font-size: .75rem; text-align: center; color: var(--color-text-muted); }
-  @media (hover: none), (pointer: coarse) { .studio-survey__hint { display: none; } }
+  /* The hint speaks to a keyboard. A touch screen has none, and a phone-width
+     window is a phone more often than not, so neither shows it. */
+  @media (hover: none), (pointer: coarse), (max-width: 639px) { .studio-survey__hint { display: none; } }
 
   .studio-survey__card { padding: 2rem 1.5rem; text-align: center; border: 1px solid var(--color-border); border-radius: 1.25rem; background: var(--color-surface); }
   .studio-survey__burst { font-size: 3rem; line-height: 1; margin-bottom: .75rem; }
@@ -86,7 +97,7 @@
   @media (min-width: 640px) {
     .studio-survey { padding-top: 3rem; }
     .studio-survey__question { font-size: 1.625rem; }
-    .studio-survey__title { font-size: 2.125rem; }
+    .studio-survey:not(.is-enhanced) .studio-survey__title { font-size: 2.125rem; }
     .studio-survey__scale { gap: .75rem; }
     .studio-survey__tile { min-height: 5.5rem; }
     .studio-survey__face { font-size: 2.5rem; }

data/app/views/studio/surveys/show.html.erb

@@ -1,9 +1,10 @@
 <%# /surveys/:slug — the survey (Studio::SurveysController#show, docs/SURVEYS.md).
 
     ONE FORM, TWO PRESENTATIONS. Without JavaScript every question renders in
-    order and the Submit button posts the lot. The script below adds
-    .is-enhanced and turns the same markup into one question per screen, with a
-    progress bar, Back and Next, number-key and Enter shortcuts, and an
+    order under the title and intro, and the Submit button posts the lot. The
+    script below adds .is-enhanced and turns the same markup into one question
+    per screen, opening on question 1 with no intro screen, with a progress
+    bar, Back (from question 2 on) and Next, number-key and Enter shortcuts, and an
     autosave on each answer. Submit is still the same POST either way, so the
     server's validation is the one rule. %>
 <% total = @survey.questions.size %>
@@ -28,10 +29,14 @@
 
     <%= form_with url: studio_survey_path(@survey.slug), method: :post, local: true,
                   html: { class: "studio-survey__form", data: { survey_form: true } } do %>
-      <section class="studio-survey__step" data-survey-step data-intro aria-labelledby="studio-survey-title">
-        <h1 class="studio-survey__title" id="studio-survey-title" tabindex="-1" data-survey-focus><%= @survey.title %></h1>
+      <%# The head is not a step: the survey opens straight on question 1. The
+          title stays the page's h1 for a screen reader; when it says what
+          question 1 asks, the stepper hides it visually rather than paint the
+          same words twice. The intro is a quiet lead line over question 1. %>
+      <header class="studio-survey__head<%= " studio-survey__head--echo" if @survey.title_repeats_first_question? %>" data-survey-head>
+        <h1 class="studio-survey__title" id="studio-survey-title"><%= @survey.title %></h1>
         <% if @survey.intro %>
-          <p class="studio-survey__intro-copy"><%= @survey.intro %></p>
+          <p class="studio-survey__intro-copy" data-survey-intro><%= @survey.intro %></p>
         <% end %>
         <p class="studio-survey__meta">
           <%= pluralize(total, "question") %> · about <%= pluralize(minutes, "minute") %><% if @survey.required_keys.any? %> · <span aria-hidden="true">*</span> required<% end %>
@@ -39,7 +44,7 @@
         <% if @errors.any? %>
           <p class="studio-survey__error" role="alert">A few answers need another look before this can be sent.</p>
         <% end %>
-      </section>
+      </header>
 
       <% @survey.questions.each_with_index do |question, index| %>
         <%= render "studio/surveys/question", question: question, index: index, total: total,
@@ -48,7 +53,7 @@
 
       <div class="studio-survey__nav">
         <button type="button" class="btn btn-neutral" data-survey-back hidden>Back</button>
-        <button type="button" class="btn btn-primary studio-survey__forward" data-survey-next hidden>Start</button>
+        <button type="button" class="btn btn-primary studio-survey__forward" data-survey-next hidden>Next</button>
         <button type="submit" class="btn btn-primary studio-survey__forward" data-survey-submit>Submit</button>
       </div>
       <p class="studio-survey__status" aria-live="polite" data-survey-status></p>

data/lib/studio/survey.rb

@@ -241,6 +241,15 @@ module Studio
     def keys = questions.map(&:key)
     def required_keys = questions.select(&:required?).map(&:key)
 
+    # True when the title says what the first question asks ("How was your
+    # first game?" twice). The survey opens on that question, so the stepper
+    # keeps the title as the page's heading for a screen reader but does not
+    # paint it twice. Compared on letters and digits alone, ignoring case.
+    def title_repeats_first_question?
+      squash = ->(text) { text.to_s.downcase.gsub(/[^[:alnum:]]/, "") }
+      squash.call(title) == squash.call(questions.first.label)
+    end
+
     private
 
     def validate!

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.88.0"
+  VERSION = "0.89.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.88.0
+  version: 0.89.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails