studio-engine 0.87.0 → 0.88.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3bc2b4fbaacbbcb3895cdcc95f4caa6421df1cc1cf16c9e53d8bdd5aa19f3a7
-  data.tar.gz: b453a06ef41d2bd56b23a56e2f80bc29f19bd793702dbf23e6b1f7236f0cfb37
+  metadata.gz: e16f65ea44055886fea1ffb0743a9415caa612f858caa0ff7dabb7c87beeeb15
+  data.tar.gz: 9690ad40a9e766646995ddfa1c69c8c22191e3509bb944d5c184ea5c1a1b21e2
 SHA512:
-  metadata.gz: f88b17d347d21f137b61a91d0e1d0e70c67e3b464e36f1f0de7bb198798c914fd9a09af6a567639cae488ae67aabebdbac811c6a2a55f1ba02f9bdada74bb8bc
-  data.tar.gz: 975c4a433ea0dac45d70a683afc799984ee027c27a33e6cf823467cc545f01dda4575ef6623efd830b4bdf486cb4a29b53cee7e0886b441681a30af3b7f4ff38
+  metadata.gz: ae4786abebc9f1d9dc86cc3992f4a6f4225c4fceaa20b73fca12ddd43afad1e4d6ef2807a8d3302bdf2d811792995fdac42961a02c6b70637f8923e841e61402
+  data.tar.gz: 3ba6c43faf9e1f7a03596b70924fc099469d8c95ce967f63e4a2ba8f4f0da0112db6068e701e739fa7e3ce5435bd07ee456b2982fec91ebb9561a4bc3dd18b09

data/CHANGELOG.md

@@ -4,6 +4,34 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.88.0 — 2026-10-05
+
+### Added
+
+- **Surveys.** Define a survey in app code — `Studio.define_survey "first-game"
+  do ... end` in `config/surveys/*.rb`, loaded on boot and each reload — with six
+  question types (`emoji_scale`, `rating`, `choice`, `multi_choice`,
+  `short_text`, `long_text`), each with `required:` and `help:`. The engine
+  serves it at `GET /surveys/:slug`: one question per screen with a progress
+  bar, tap-to-advance, number keys and Enter, autosave of every answer, resume
+  where the respondent left off, a thank-you screen with the survey's
+  `next_action`, `prefers-reduced-motion` support, and a single-form fallback
+  without JavaScript. Answers are stored in the new `studio_survey_responses`
+  table (`Studio::SurveyResponse`) with a snapshot of each question's label and
+  the chosen option's label, so editing a survey never rewrites old responses.
+  **Opt in** with `config.draw_survey_routes = true`; **run
+  `bin/rails studio_engine:install:migrations && bin/rails db:migrate`** first.
+- **`config.survey_ref_resolver`** (`->(controller) { ref }`) attributes an email
+  arrival, and **`config.on_survey_completed`** (`->(response) { ... }`) runs once
+  when a response completes; a raising hook is logged, never shown. A survey
+  answers to a signed-in user, an attributed email arrival, or anyone when it
+  declares `allow_anonymous true`.
+- **The survey results panel at `/admin/surveys`**, admin-only: started,
+  completed and completion rate per survey; per-question distribution bars and
+  averages, a scrolling list of text answers with the respondent's username or
+  "anonymous"; date-range and completed-only filters; CSV export. **Opt in**
+  with `config.draw_admin_survey_routes = true`. See `docs/SURVEYS.md`.
+
 ## 0.87.0 — 2026-10-04
 
 ### Changed

data/README.md

@@ -43,6 +43,7 @@ resolved.
 - **Transactional emails**: `Studio::EmailCatalog` — every email an app sends, its type, a live preview, and its banner — plus the shared `/admin/emails` page. Every app inherits the standard emails and their artwork on day one, and can register its own workflows and upload its own banners. See [Transactional emails](#transactional-emails).
 - **Site footer**: `<%= studio_site_footer %>` in the layout renders the public site's footer. It is on by default: with nothing configured it prints the app's name, logo and the legal links the app has routes for, and no address. `config.site_footer` declares the app's own facts (brand, social profiles, link columns, an address with a live map, legal links), every part optional; `config.site_footer_address` adds a location in one setting; `config.site_footer = false` turns the footer off. Leaflet is vendored and served by the engine. See [`docs/SITE_FOOTER.md`](docs/SITE_FOOTER.md).
 - **Booking**: a simple scheduler on Google Calendar appointment schedules, with or without the footer. With `config.booking_url`, `studio_booking_frame` embeds Google's booking page, `studio_booking_link` opens it in a popup, and `config.draw_booking_routes = true` draws `/schedule` (or name the app's own page with `config.booking_path`). `config.booking_crop` crops the frame to the slot picker at rest, from numbers `bin/booking-crop-measure` reads off the app's own schedule. See [`docs/BOOKING.md`](docs/BOOKING.md).
+- **Surveys**: define a survey in app code (`config/surveys/*.rb`, `Studio.define_survey`) with six question types — emoji scale, 1–5 rating, single and multiple choice, short and long text — and the engine serves it at `/surveys/:slug`: one question per screen, autosave, resume, keyboard shortcuts, and a no-JavaScript fallback. `config.on_survey_completed` and `config.survey_ref_resolver` let the app fire its own goals and attribute email arrivals. An admin panel at `/admin/surveys` breaks results down per question and exports CSV. Opt in with `config.draw_survey_routes = true` and `config.draw_admin_survey_routes = true`. See [`docs/SURVEYS.md`](docs/SURVEYS.md).
 
 ## Configuration
 
@@ -137,6 +138,8 @@ Set `Studio.draw_session_routes = true` to add the session-drift rehydrate endpo
 
 Set `Studio.draw_booking_routes = true` to add the booking page (`GET /schedule`, helper `studio_booking_path`) — off by default because mcritchie-studio draws its own `/schedule` until it adopts this one. An app that keeps its own booking page names it with `Studio.booking_path` instead ([`docs/BOOKING.md`](docs/BOOKING.md)).
 
+Set `Studio.draw_survey_routes = true` to add the public survey pages (`/surveys/:slug`, helper `studio_survey_path`) and `Studio.draw_admin_survey_routes = true` to add the admin results panel (`/admin/surveys`, helpers `admin_surveys_path` / `admin_survey_path`) — both off by default because an app may already own those paths. Both need the `studio_survey_responses` table ([`docs/SURVEYS.md`](docs/SURVEYS.md)).
+
 **Magic links need the `studio_links` table.** Install it with `bin/rails studio_engine:install:migrations && bin/rails db:migrate` (install all of them) before enabling `:magic_link` — never by hand-copying the migration, which collides with the task's own copy on `class CreateStudioLinks`. Without the table, the first sign-in raises `Studio::Link::MissingTable`.
 
 In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.

data/app/controllers/studio/admin_surveys_controller.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Studio
+  # The survey results panel (docs/SURVEYS.md). Admin-only, drawn only when
+  # Studio.draw_admin_survey_routes is on.
+  #
+  #   GET /admin/surveys                every survey: started, completed, rate
+  #   GET /admin/surveys/:slug          per-question breakdown, filterable
+  #   GET /admin/surveys/:slug/export   the same filtered responses as CSV
+  #
+  # A slug with stored responses but no definition left in app code still lists
+  # and exports (its breakdown needs the definition, so its page says so).
+  class AdminSurveysController < ::ApplicationController
+    before_action :require_admin
+    before_action :require_table
+
+    def index
+      started = Studio::SurveyResponse.group(:survey_slug).count
+      completed = Studio::SurveyResponse.completed.group(:survey_slug).count
+      slugs = (Studio.surveys.map(&:slug) + started.keys).uniq.sort
+      @rows = slugs.map do |slug|
+        s = started.fetch(slug, 0)
+        c = completed.fetch(slug, 0)
+        { slug: slug, survey: Studio.survey(slug), started: s, completed: c,
+          rate: Studio::Survey::Breakdown.percent(c, s) }
+      end
+    end
+
+    def show
+      @slug = params[:slug].to_s
+      @survey = Studio.survey(@slug)
+      @filters = filters
+      scope = filtered_scope
+      @started = scope.count
+      @completed = scope.completed.count
+      return unless @survey
+
+      @breakdown = Studio::Survey::Breakdown.new(@survey, breakdown_rows(scope))
+    end
+
+    def export
+      slug = params[:slug].to_s
+      survey = Studio.survey(slug)
+      @filters = filters
+      @slug = slug
+      rows = filtered_scope.includes(:user).order(:id).map do |r|
+        { response_id: r.id, survey_version: r.survey_version, status: r.completed? ? "completed" : "in_progress",
+          started_at: r.started_at, completed_at: r.completed_at, respondent: r.respondent_label,
+          user_id: r.user_id, email_ref: r.email_ref, user_agent_class: r.user_agent_class, answers: r.answers }
+      end
+      csv = Studio::Survey::Export.new(survey, rows).to_csv
+      send_data csv, type: "text/csv; charset=utf-8",
+                     filename: "survey-#{slug.parameterize}-#{Time.current.strftime("%Y%m%d")}.csv"
+    end
+
+    private
+
+    def require_table
+      return if Studio::SurveyResponse.table_ready?
+
+      raise Studio::SurveyResponse::MissingTable,
+            "studio_survey_responses is not installed — run bin/rails studio_engine:install:migrations && bin/rails db:migrate"
+    end
+
+    def filters
+      {
+        from: parse_date(params[:from]),
+        to: parse_date(params[:to]),
+        completed: params[:completed] == "1"
+      }
+    end
+
+    def parse_date(value)
+      Date.iso8601(value.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # Dates filter on started_at, inclusive of both whole days.
+    def filtered_scope
+      scope = Studio::SurveyResponse.for_survey(@slug)
+      scope = scope.where(started_at: @filters[:from].beginning_of_day..) if @filters[:from]
+      scope = scope.where(started_at: ..@filters[:to].end_of_day) if @filters[:to]
+      scope = scope.completed if @filters[:completed]
+      scope
+    end
+
+    def breakdown_rows(scope)
+      scope.includes(:user).order(:id).map do |r|
+        { answers: r.answers, respondent: r.respondent_label, at: r.completed_at || r.updated_at }
+      end
+    end
+  end
+end

data/app/controllers/studio/surveys_controller.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Studio
+  # The public survey pages (docs/SURVEYS.md). Drawn only when
+  # Studio.draw_survey_routes is on.
+  #
+  #   GET   /surveys/:slug               the survey: one question per screen with JS,
+  #                                      a single form without it
+  #   PATCH /surveys/:slug/answers/:key  autosave one answer (JSON)
+  #   POST  /surveys/:slug               submit: store every answer, complete, thank
+  #   GET   /surveys/:slug/thanks        the thank-you screen and next action
+  #
+  # A response row is created on the FIRST ANSWER, not on page view, so a link
+  # preview bot or a bounce never counts as "started".
+  class SurveysController < ::ApplicationController
+    skip_before_action :require_authentication, raise: false
+
+    before_action :load_survey
+    before_action :require_table
+    before_action :require_respondent
+
+    def show
+      @response = locate_response
+      return redirect_to(studio_survey_thanks_path(@survey.slug), status: :see_other) if @response&.completed?
+
+      @errors = {}
+      render_survey
+    end
+
+    def answer
+      question = @survey.question(params[:key])
+      return render(json: { error: "unknown question" }, status: :not_found) unless question
+
+      response = open_response!
+      return render(json: { error: "already complete" }, status: :conflict) unless response
+
+      ok, error = rescue_survey_write(response) { response.record_answer(question, params[:value]) }
+      if ok
+        render json: { saved: true, key: question.key, answered: response.answers.keys & @survey.keys }
+      else
+        render json: { saved: false, error: error }, status: :unprocessable_entity
+      end
+    end
+
+    def submit
+      response = open_response!
+      return redirect_to(studio_survey_thanks_path(@survey.slug), status: :see_other) unless response
+
+      submitted = submitted_answers
+      @errors = {}
+      Studio::SurveyResponse.transaction do
+        @survey.questions.each do |question|
+          next unless submitted.key?(question.key)
+
+          ok, error = response.record_answer(question, submitted[question.key])
+          @errors[question.key] = error unless ok
+        end
+      end
+      response.missing_required(@survey).each { |key| @errors[key] ||= "This one is required." }
+
+      if @errors.empty? && response.complete!(@survey)
+        run_completed_hook(response)
+        redirect_to studio_survey_thanks_path(@survey.slug), status: :see_other
+      elsif response.completed?
+        # A racing submit completed it first; that one fired the hook.
+        redirect_to studio_survey_thanks_path(@survey.slug), status: :see_other
+      else
+        @response = response
+        render_survey(status: :unprocessable_entity)
+      end
+    end
+
+    def thanks
+      @response = locate_response
+      redirect_to(studio_survey_path(@survey.slug), status: :see_other) unless @response&.completed?
+    end
+
+    private
+
+    def load_survey
+      @survey = Studio.survey(params[:slug])
+      render :not_found, status: :not_found unless @survey
+    end
+
+    def require_table
+      return if Studio::SurveyResponse.table_ready?
+
+      raise Studio::SurveyResponse::MissingTable,
+            "studio_survey_responses is not installed — run bin/rails studio_engine:install:migrations && bin/rails db:migrate"
+    end
+
+    # Signed in, arrived by an attributed email link, or an anonymous survey.
+    def require_respondent
+      return if @survey.allow_anonymous? || survey_user || survey_ref.present?
+
+      render :sign_in_required, status: :unauthorized
+    end
+
+    def render_survey(status: :ok)
+      @resume_key = @errors.keys.first || @response&.resume_key(@survey)
+      @resume_index = @resume_key ? @survey.keys.index(@resume_key) : nil
+      render :show, status: status
+    end
+
+    def survey_user
+      return @survey_user if defined?(@survey_user)
+
+      @survey_user = respond_to?(:current_user, true) ? current_user : nil
+    end
+
+    def survey_ref
+      return @survey_ref if defined?(@survey_ref)
+
+      @survey_ref = begin
+        Studio.survey_ref_resolver&.call(self).to_s.strip.presence
+      rescue StandardError => e
+        log_survey_error(e)
+        nil
+      end
+    end
+
+    def token_key = "studio_survey_#{@survey.slug}"
+
+    def session_token
+      session[token_key] ||= SecureRandom.urlsafe_base64(24)
+    end
+
+    def locate_response
+      Studio::SurveyResponse.locate(@survey, user: survey_user, token: session[token_key])
+    end
+
+    # The visitor's open response, created on demand; nil if theirs is complete.
+    def open_response!
+      existing = locate_response
+      return nil if existing&.completed?
+
+      response = existing || Studio::SurveyResponse.open_for!(
+        @survey, user: survey_user, token: session_token, email_ref: survey_ref, user_agent: request.user_agent
+      )
+      response.update!(email_ref: survey_ref.first(255)) if response.email_ref.blank? && survey_ref.present?
+      response
+    end
+
+    def submitted_answers
+      raw = params[:answers]
+      return {} unless raw.respond_to?(:permit)
+
+      permitted = @survey.questions.map { |q| q.multi? ? { q.key => [] } : q.key }
+      raw.permit(*permitted).to_h
+    end
+
+    def rescue_survey_write(target)
+      yield
+    rescue ActiveRecord::ActiveRecordError => e
+      log_survey_error(e, target: target)
+      [false, "Couldn't save that answer. Please try again."]
+    end
+
+    def run_completed_hook(response)
+      Studio.on_survey_completed&.call(response)
+    rescue StandardError => e
+      log_survey_error(e, target: response)
+    end
+
+    def log_survey_error(error, target: nil)
+      log = defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!) ? ::ErrorLog.capture!(error) : nil
+      log.update(target: target) if log && target && log.respond_to?(:target=)
+      Rails.logger.error("[studio-survey] #{error.class}: #{error.message}")
+    rescue StandardError
+      Rails.logger.error("[studio-survey] #{error.class}: #{error.message}")
+    end
+  end
+end

data/app/models/studio/survey_response.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Studio
+  # One respondent's answers to one Studio::Survey (docs/SURVEYS.md).
+  #
+  # The survey is app code; this row is the only thing stored. Each answer is a
+  # self-describing snapshot — value, question label, type, and the option
+  # label(s) chosen — so a response stays readable after its survey changes.
+  class SurveyResponse < ApplicationRecord
+    self.table_name = "studio_survey_responses"
+
+    class MissingTable < StandardError; end
+
+    belongs_to :user, class_name: "::User", optional: true
+
+    validates :survey_slug, presence: true
+    validates :started_at, presence: true
+
+    scope :completed, -> { where.not(completed_at: nil) }
+    scope :in_progress, -> { where(completed_at: nil) }
+    scope :for_survey, ->(slug) { where(survey_slug: slug.to_s) }
+
+    before_validation { self.started_at ||= Time.current }
+
+    UA_BOT = /bot|crawl|spider|slurp|preview|facebookexternalhit|curl|wget|python|headless/i
+    UA_TABLET = /ipad|tablet|kindle|silk|(android(?!.*mobile))/i
+    UA_MOBILE = /mobi|iphone|ipod|android|blackberry|opera mini|iemobile/i
+
+    class << self
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError, NameError
+        false
+      end
+
+      # The coarse device class stored instead of the raw user agent.
+      def user_agent_class(user_agent)
+        ua = user_agent.to_s
+        return "unknown" if ua.strip.empty?
+        return "bot" if ua.match?(UA_BOT)
+        return "tablet" if ua.match?(UA_TABLET)
+        return "mobile" if ua.match?(UA_MOBILE)
+
+        "desktop"
+      end
+
+      # The visitor's open response, or their latest completed one: by user
+      # first, then by the session token. An anonymous response found by token
+      # is claimed by the user who signs in mid-survey, and the claim drops the
+      # token: logout keeps the survey session key, so a token on a user's row
+      # would hand it to the next person to sign in on that browser.
+      def locate(survey, user: nil, token: nil)
+        scope = for_survey(survey.slug)
+        found = user && scope.where(user_id: user.id).order(completed_at: :desc, id: :desc).find_by(completed_at: nil)
+        found ||= token.present? && scope.where(session_token: token, user_id: nil).order(id: :desc).first
+        found ||= user && scope.where(user_id: user.id).order(id: :desc).first
+        return nil unless found
+
+        found.update!(user_id: user.id, session_token: nil) if user && found.user_id.nil? && found.open?
+        found
+      end
+
+      # Find the visitor's open response or start one. The partial unique
+      # indexes make a double-click race lose to the row that won.
+      def open_for!(survey, user: nil, token:, email_ref: nil, user_agent: nil)
+        existing = locate(survey, user: user, token: token)
+        return existing if existing&.open?
+
+        create!(survey_slug: survey.slug, survey_version: survey.version, user_id: user&.id,
+                session_token: (token unless user), email_ref: email_ref.to_s.strip.presence&.first(255),
+                user_agent_class: user_agent_class(user_agent), answers: {})
+      rescue ActiveRecord::RecordNotUnique
+        locate(survey, user: user, token: token) || raise
+      end
+    end
+
+    def open? = completed_at.nil?
+    def completed? = completed_at.present?
+
+    def answer_entry(key) = (answers || {})[key.to_s]
+    def answer_value(key) = answer_entry(key)&.dig("value")
+
+    def answered?(question)
+      entry = answer_entry(question.key)
+      entry.is_a?(Hash) && !question.blank_value?(entry["value"])
+    end
+
+    # Stores one answer (or clears it, for a blank). Returns [ok, error]. Never
+    # touches a completed response: a finished survey is a record, not a draft.
+    def record_answer(question, raw)
+      return [false, "This survey is already complete."] if completed?
+
+      value, error = question.normalize(raw)
+      return [false, error] if error
+
+      next_answers = (answers || {}).dup
+      if value.nil?
+        next_answers.delete(question.key)
+      else
+        next_answers[question.key] = {
+          "value" => value, "label" => question.label, "type" => question.type.to_s,
+          "display" => question.display(value), "answered_at" => Time.current.utc.iso8601
+        }
+      end
+      self.answers = next_answers
+      self.current_key = question.key
+      save!
+      [true, nil]
+    end
+
+    def missing_required(survey)
+      survey.questions.select { |q| q.required? && !answered?(q) }.map(&:key)
+    end
+
+    # The first unanswered question — where a returning respondent resumes.
+    def resume_key(survey)
+      survey.questions.find { |q| !answered?(q) }&.key || survey.questions.last.key
+    end
+
+    # Completes the response if every required question is answered. Returns
+    # true only when THIS call completed it (false if incomplete or already
+    # done). The flip is one conditional UPDATE, so two racing submits (a no-JS
+    # double click) cannot both win and fire on_survey_completed twice; the
+    # loser reloads and sees the winner's completed_at.
+    def complete!(survey)
+      return false if completed? || missing_required(survey).any?
+
+      now = Time.current
+      flipped = self.class.where(id: id, completed_at: nil)
+                          .update_all(completed_at: now, survey_version: survey.version, updated_at: now)
+      unless flipped == 1
+        reload
+        return false
+      end
+
+      self.completed_at = now
+      self.survey_version = survey.version
+      self.updated_at = now
+      clear_attribute_changes(%w[completed_at survey_version updated_at])
+      true
+    end
+
+    # "username" for a signed-in respondent, "anonymous" otherwise.
+    def respondent_label
+      return "anonymous" unless user
+
+      user.try(:username).presence || user.try(:display_name).presence || "user ##{user.id}"
+    end
+  end
+end

data/app/views/studio/admin_surveys/index.html.erb

@@ -0,0 +1,41 @@
+<%# /admin/surveys — every survey with its funnel (Studio::AdminSurveysController).
+    "Started" counts responses with at least one answer: a row is created on the
+    first answer, never on a page view. %>
+<% content_for(:title, "Surveys") %>
+<div class="max-w-4xl mx-auto px-4 py-6" data-admin-surveys>
+  <h1 class="text-2xl font-extrabold text-heading mb-1">Surveys</h1>
+  <p class="text-sm text-secondary mb-6">Defined in <code>config/surveys/</code>. A response counts as started at its first answer.</p>
+
+  <% if @rows.empty? %>
+    <div class="empty-state">
+      <p class="text-heading font-semibold mb-1">No surveys yet</p>
+      <p class="text-sm text-muted">Define one with <code>Studio.define_survey</code> — see the engine's docs/SURVEYS.md.</p>
+    </div>
+  <% else %>
+    <div class="card overflow-x-auto">
+      <table class="w-full text-sm">
+        <thead>
+          <tr class="text-left border-b border-subtle">
+            <th scope="col" class="px-4 py-3 label-upper font-medium">Survey</th>
+            <th scope="col" class="px-4 py-3 label-upper font-medium text-right">Started</th>
+            <th scope="col" class="px-4 py-3 label-upper font-medium text-right">Completed</th>
+            <th scope="col" class="px-4 py-3 label-upper font-medium text-right">Completion</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @rows.each do |row| %>
+            <tr class="border-b border-subtle last:border-0" data-admin-survey-row="<%= row[:slug] %>">
+              <td class="px-4 py-3">
+                <a href="<%= admin_survey_path(row[:slug]) %>" class="font-semibold text-heading hover:underline"><%= row[:survey]&.title || row[:slug] %></a>
+                <div class="text-xs text-muted font-mono">/surveys/<%= row[:slug] %><% unless row[:survey] %> · definition removed<% end %></div>
+              </td>
+              <td class="px-4 py-3 text-right tabular-nums text-body" data-stat="started"><%= row[:started] %></td>
+              <td class="px-4 py-3 text-right tabular-nums text-body" data-stat="completed"><%= row[:completed] %></td>
+              <td class="px-4 py-3 text-right tabular-nums font-semibold text-heading" data-stat="rate"><%= row[:started].zero? ? "—" : "#{row[:rate]}%" %></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% end %>
+</div>

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

@@ -0,0 +1,99 @@
+<%# /admin/surveys/:slug — one survey's results (Studio::AdminSurveysController).
+    Distribution bars for scale and choice questions (percent of those who
+    answered that question), a scrolling list for text answers, and filters
+    that the CSV export carries along. %>
+<% title = @survey&.title || @slug %>
+<% content_for(:title, "#{title} · Surveys") %>
+<% filter_params = { from: @filters[:from]&.iso8601, to: @filters[:to]&.iso8601, completed: (@filters[:completed] ? "1" : nil) }.compact %>
+<div class="max-w-4xl mx-auto px-4 py-6" data-admin-survey="<%= @slug %>">
+  <a href="<%= admin_surveys_path %>" class="text-sm text-secondary hover:underline">&larr; All surveys</a>
+  <div class="flex flex-wrap items-end justify-between gap-3 mt-2 mb-6">
+    <div>
+      <h1 class="text-2xl font-extrabold text-heading"><%= title %></h1>
+      <p class="text-xs text-muted font-mono">/surveys/<%= @slug %><% if @survey %> · version <%= @survey.version %><% end %></p>
+    </div>
+    <a href="<%= admin_survey_export_path(@slug, **filter_params) %>" class="btn btn-neutral btn-sm" data-survey-export>Export CSV</a>
+  </div>
+
+  <form method="get" action="<%= admin_survey_path(@slug) %>" class="card p-4 mb-6 flex flex-wrap items-end gap-4" data-survey-filters>
+    <label class="flex flex-col gap-1 text-sm">
+      <span class="label-upper">From</span>
+      <input type="date" name="from" value="<%= @filters[:from]&.iso8601 %>" class="input-field py-2">
+    </label>
+    <label class="flex flex-col gap-1 text-sm">
+      <span class="label-upper">To</span>
+      <input type="date" name="to" value="<%= @filters[:to]&.iso8601 %>" class="input-field py-2">
+    </label>
+    <label class="flex items-center gap-2 text-sm text-body py-2">
+      <input type="checkbox" name="completed" value="1" <%= "checked" if @filters[:completed] %>>
+      Completed only
+    </label>
+    <button type="submit" class="btn btn-primary btn-sm">Apply</button>
+    <% if filter_params.any? %><a href="<%= admin_survey_path(@slug) %>" class="text-sm text-secondary hover:underline py-2">Clear</a><% end %>
+  </form>
+
+  <div class="grid grid-cols-3 gap-3 mb-6">
+    <div class="card p-4 text-center">
+      <div class="label-upper mb-1">Started</div>
+      <div class="text-2xl font-bold text-heading tabular-nums" data-stat="started"><%= @started %></div>
+    </div>
+    <div class="card p-4 text-center">
+      <div class="label-upper mb-1">Completed</div>
+      <div class="text-2xl font-bold text-heading tabular-nums" data-stat="completed"><%= @completed %></div>
+    </div>
+    <div class="card p-4 text-center">
+      <div class="label-upper mb-1">Completion</div>
+      <div class="text-2xl font-bold text-heading tabular-nums" data-stat="rate"><%= @started.zero? ? "—" : "#{Studio::Survey::Breakdown.percent(@completed, @started)}%" %></div>
+    </div>
+  </div>
+
+  <% if @breakdown.nil? %>
+    <div class="empty-state">
+      <p class="text-heading font-semibold mb-1">This survey's definition was removed</p>
+      <p class="text-sm text-muted">Its responses are still stored — the CSV export lists every answer under its original question key.</p>
+    </div>
+  <% else %>
+    <div class="flex flex-col gap-4">
+      <% @breakdown.results.each_with_index do |result, i| %>
+        <% q = result.question %>
+        <section class="card p-5" data-survey-question="<%= q.key %>">
+          <div class="flex flex-wrap items-baseline justify-between gap-2 mb-4">
+            <h2 class="text-base font-bold text-heading"><span class="text-muted font-medium mr-1"><%= i + 1 %>.</span><%= q.label %></h2>
+            <p class="text-xs text-muted">
+              <%= pluralize(result.answered, "answer") %><% if result.average %> · average <span class="font-semibold text-heading" data-survey-average><%= result.average %></span> / 5<% end %>
+            </p>
+          </div>
+
+          <% if result.text? %>
+            <% if result.entries.empty? %>
+              <p class="text-sm text-muted">No answers yet.</p>
+            <% else %>
+              <ul class="flex flex-col gap-2 overflow-y-auto pr-1" style="max-height: 22rem;" data-survey-text-answers>
+                <% result.entries.each do |entry| %>
+                  <li class="bg-inset rounded-lg px-3 py-2">
+                    <p class="text-sm text-body whitespace-pre-line break-words"><%= entry.text %></p>
+                    <p class="text-xs text-muted mt-1"><%= entry.respondent %><% if entry.at %> · <%= entry.at.strftime("%b %-d, %Y") %><% end %></p>
+                  </li>
+                <% end %>
+              </ul>
+            <% end %>
+          <% else %>
+            <ul class="flex flex-col gap-2" data-survey-buckets>
+              <% result.buckets.each do |bucket| %>
+                <li class="grid items-center gap-3" style="grid-template-columns: minmax(6rem, 11rem) 1fr 4.5rem;" data-survey-bucket="<%= bucket.value %>">
+                  <span class="text-sm text-body truncate" title="<%= bucket.label %>">
+                    <% if bucket.face %><span aria-hidden="true" class="mr-1"><%= bucket.face %></span><% end %><%= bucket.label %><% end_label = { 1 => q.low_label, 5 => q.high_label }[bucket.value] if q.type == :rating %><% if end_label %> <span class="text-xs text-muted">· <%= end_label %></span><% end %><% if bucket.retired %> <span class="text-xs text-muted">(retired)</span><% end %>
+                  </span>
+                  <span class="h-3 rounded-full bg-inset overflow-hidden" role="img" aria-label="<%= bucket.percent %> percent">
+                    <span class="block h-full rounded-full" style="width: <%= bucket.percent %>%; background: var(--color-cta);"></span>
+                  </span>
+                  <span class="text-sm tabular-nums text-right text-heading"><span data-survey-percent><%= bucket.percent %>%</span> <span class="text-xs text-muted">(<span data-survey-count><%= bucket.count %></span>)</span></span>
+                </li>
+              <% end %>
+            </ul>
+          <% end %>
+        </section>
+      <% end %>
+    </div>
+  <% end %>
+</div>