studio-engine 0.86.0 → 0.88.0

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

@@ -0,0 +1,15 @@
+<%# A survey without allow_anonymous, opened by a visitor who is neither
+    signed in nor arriving by an attributed email link. %>
+<% content_for(:title, @survey.title) %>
+<%= render "studio/surveys/styles" %>
+<main class="studio-survey" data-studio-survey-sign-in>
+  <div class="studio-survey__shell">
+    <div class="studio-survey__card">
+      <h1 class="studio-survey__title"><%= @survey.title %></h1>
+      <p class="studio-survey__intro-copy">Sign in to answer this survey.</p>
+      <% if respond_to?(:login_path) %>
+        <a href="<%= login_path %>" class="btn btn-primary btn-lg">Sign in</a>
+      <% end %>
+    </div>
+  </div>
+</main>

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

@@ -0,0 +1,16 @@
+<%# /surveys/:slug/thanks — shown once a response completes. The next action is
+    the survey's own (next_action label:, url:), when it declares one. %>
+<% content_for(:title, "Thank you") %>
+<%= render "studio/surveys/styles" %>
+<main class="studio-survey" data-studio-survey-thanks>
+  <div class="studio-survey__shell">
+    <div class="studio-survey__card">
+      <div class="studio-survey__burst" aria-hidden="true">&#x1F64C;</div>
+      <h1 class="studio-survey__title" tabindex="-1" autofocus>Thank you!</h1>
+      <p class="studio-survey__intro-copy"><%= @survey.thank_you %></p>
+      <% if @survey.next_action %>
+        <a href="<%= @survey.next_action[:url] %>" class="btn btn-primary btn-lg" data-survey-next-action><%= @survey.next_action[:label] %></a>
+      <% end %>
+    </div>
+  </div>
+</main>

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

@@ -12,7 +12,9 @@
      whose box runs from 200 to 600), cropped by the same arithmetic the real
      wrapper uses (Studio::Booking.crop). No real schedule's numbers are here. %>
 <%
-  own_facts    = studio_site_footer_facts
+  # The app's OWN facts only. An app on the default footer (nothing declared)
+  # sees the sample, which shows every kind of row the default does not have.
+  own_facts    = Studio.site_footer_declared? ? studio_site_footer_facts : nil
   sample       = {
     name: Studio.site_identity[:title], tagline: "What this app is, in a line",
     email: "team@example.com",
@@ -42,7 +44,7 @@
     </p>
     <p class="text-muted text-sm" data-site-footer-status>
       This app:
-      footer <strong class="text-body"><%= own_facts ? "declared" : "not declared" %></strong> &middot;
+      footer <strong class="text-body"><%= own_facts ? "declared" : (Studio.site_footer_enabled? ? "default (not declared)" : "off") %></strong> &middot;
       booking <strong class="text-body"><%= booking ? "on" : "off" %></strong> &middot;
       booking page <strong class="text-body"><%= Studio.draw_booking_routes ? "drawn" : "not drawn" %></strong> &middot;
       frame <strong class="text-body"><%= own_crop ? "cropped at rest" : "whole at rest" %></strong>

data/db/migrate/20261005120000_create_studio_survey_responses.rb

@@ -0,0 +1,47 @@
+# One respondent's answers to one survey (Studio::SurveyResponse,
+# docs/SURVEYS.md). Surveys themselves are defined in app code, not stored; the
+# row keys on the survey's slug and stamps the definition version it was taken
+# under.
+#
+# `answers` is { question_key => { "value", "label", "type", "display",
+# "answered_at" } }: each answer carries the question label and option label it
+# was given under, so a later edit to the definition never rewrites history.
+#
+# No raw IP and no raw user agent: user_agent_class is mobile / tablet /
+# desktop / bot / unknown, which is all the results panel reads.
+#
+# The two partial unique indexes enforce ONE IN-PROGRESS response per signed-in
+# user, and per anonymous session token, for each survey. Completed rows fall
+# out of both, so a respondent's history is unconstrained.
+class CreateStudioSurveyResponses < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_survey_responses do |t|
+      t.string :survey_slug, null: false
+      t.string :survey_version
+      if connection.adapter_name.match?(/postg/i)
+        t.jsonb :answers, null: false, default: {}
+      else
+        t.json :answers, null: false, default: {}
+      end
+      t.bigint :user_id
+      t.string :email_ref
+      t.string :session_token
+      t.string :user_agent_class
+      t.string :current_key
+      t.datetime :started_at, null: false
+      t.datetime :completed_at
+
+      t.timestamps
+    end
+
+    add_index :studio_survey_responses, %i[survey_slug completed_at]
+    add_index :studio_survey_responses, :user_id
+    add_index :studio_survey_responses, :email_ref
+    add_index :studio_survey_responses, %i[survey_slug user_id], unique: true,
+              where: "completed_at IS NULL AND user_id IS NOT NULL",
+              name: "index_studio_survey_responses_one_open_per_user"
+    add_index :studio_survey_responses, %i[survey_slug session_token], unique: true,
+              where: "completed_at IS NULL AND session_token IS NOT NULL",
+              name: "index_studio_survey_responses_one_open_per_session"
+  end
+end

data/docs/SITE_FOOTER.md

@@ -14,6 +14,79 @@ studio-engine | grep docs/` finds them. The repository copy is
 
 ## Adopt it
 
+The app owns its layout, so the footer is one line the app writes. The engine
+never injects it.
+
+```erb
+<%# app/views/layouts/application.html.erb, at the end of <body> %>
+<%= studio_site_footer %>
+```
+
+**The footer is on by default.** That line, with nothing configured, renders
+the default footer. `config.site_footer` has three states:
+
+| `config.site_footer` | What `studio_site_footer` renders |
+|----------------------|-----------------------------------|
+| unset (`nil`) | The default footer |
+| a Hash, or a callable receiving the view | The app's own facts ([Your own facts](#your-own-facts)) |
+| `false` | Nothing: the opt-out |
+
+### The default footer
+
+```ruby
+# config/initializers/studio.rb
+Studio.configure do |config|
+  config.app_name = "Example Co"   # nothing about the footer: it is already on
+end
+```
+
+It prints only what the engine knows to be true of the app:
+
+- **The name**, as the wordmark and the © line: the site identity's title
+  (`Studio.site_identity[:title]`), which is `config.app_name` until the
+  operator or `config.site_title` says otherwise.
+- **The logo**: the app's "Footer Logo" in `config.theme_logos`, else its
+  navbar logo. None configured, none shown.
+- **A legal line**, for the routes the host has: "Privacy Policy" when it has a
+  route named `privacy`, "Terms of Service" when it has one named `terms`
+  (`get "privacy", to: "legal#privacy", as: :privacy`). A route is linked only
+  when a GET reaches it and its path needs no arguments. A host with neither
+  gets the © line alone.
+
+It has no address, no map, no phone, no email, no tagline, no social row and no
+link columns, and the page names no Leaflet. The engine cannot know those, and
+a guessed link is a dead one. For any of them, add a location (below) or
+declare [your own facts](#your-own-facts).
+
+### A location, in one setting
+
+```ruby
+Studio.configure do |config|
+  config.site_footer_address = { street: "123 Example St", city_line: "Washington, DC 20024",
+                                 lat: 38.8894, lng: -77.0352 }
+end
+```
+
+That adds the Location band, and the map when `lat:` and `lng:` are both there,
+to the default footer. The keys are the facts' `address:` keys
+([The address and the map](#the-address-and-the-map)). It also gives a location
+to an app's own facts that carry none. **An address in the app's own facts
+wins**, whole, and `address: false` there shows none.
+
+### Turning it off
+
+```ruby
+Studio.configure do |config|
+  config.site_footer = false   # no footer on any page; unset (nil) is the default footer
+end
+```
+
+To keep the footer off some pages rather than all of them, narrow
+[where it shows](#where-it-shows) instead. A facts callable that answers `nil`
+for a request renders no footer for that request.
+
+### Your own facts
+
 ```ruby
 # config/initializers/studio.rb
 Studio.configure do |config|
@@ -39,11 +112,6 @@ Studio.configure do |config|
 end
 ```
 
-```erb
-<%# app/views/layouts/application.html.erb, at the end of <body> %>
-<%= studio_site_footer %>
-```
-
 That is the whole adoption. Nothing is copied into the app's `public/`, and
 nothing is added to its asset manifest or its Tailwind build.
 
@@ -78,6 +146,10 @@ end
 <%= studio_site_footer %>
 ```
 
+Leave `config.site_footer` unset and the same app gets
+[the default footer](#the-default-footer), its name read from `config.app_name`
+since there is no site-identity table to ask.
+
 Do not call `Studio.routes(self)`: everything it draws (sign-in, admin, error
 logs) needs a database. The app also needs an asset pipeline (Propshaft or
 Sprockets), as every Rails 8 app has, and a mapping of the theme tokens onto its
@@ -107,8 +179,9 @@ development and with `eager_load = true`.
 ## The facts
 
 `config.site_footer` is a Hash, or a callable that receives the view (so it can
-use route helpers). `nil`, the default, means the app has no footer and
-`studio_site_footer` renders nothing.
+use route helpers). Unset (`nil`), the facts are the default footer's; `false`
+means the app has no footer and `studio_site_footer` renders nothing
+([Adopt it](#adopt-it)).
 
 Every key is optional. A missing key removes its part of the footer.
 
@@ -121,7 +194,7 @@ Every key is optional. A missing key removes its part of the footer.
 | `home_path` | Where the logo and wordmark link | `/` |
 | `tagline` | A line under the wordmark | No line |
 | `email` | A `mailto:` link under the tagline | No line. (To list the email in a column instead, write it as a column link.) |
-| `address` | The Location band, and the map | No Location band, no map, and Leaflet is never requested |
+| `address` | The Location band, and the map | `config.site_footer_address`; with neither, no Location band, no map, and Leaflet is never requested. `address: false` shows none even with the setting |
 | `social` | A row of round icons | No row |
 | `columns` | Link columns under bold headings. A column may carry a width hint: `[ "Contact", links, { width: 1.5 } ]` | Brand only |
 | `legal` | The centred line above the © | The © alone |
@@ -356,14 +429,19 @@ link. Those rules are more specific than the engine's and still apply.
 
 ## Tests
 
-- `test/lib/studio/site_footer_test.rb`: the facts' rules and the visibility rule.
+- `test/lib/studio/site_footer_test.rb`: the facts' rules, the default facts, the
+  address setting's precedence, and the visibility rule.
 - `test/lib/vendored_leaflet_test.rb`: Leaflet is vendored, precompiled, and
   addressed through the asset pipeline.
 - `test/integration/site_footer_test.rb`: what a host renders, with and without
-  each fact, signed in and out.
+  each fact, signed in and out; the default footer with nothing set, the
+  `false` opt-out, `config.site_footer_address` on the default footer and
+  against an app's own address, and the default legal links with and without
+  the host's routes.
 - `test/integration/footer_only_consumer_test.rb`: an app with no ActiveRecord
   boots (development and eager-loaded), renders the footer with no Leaflet, and
-  runs `studio_engine:install:migrations` to a clean exit.
+  runs `studio_engine:install:migrations` to a clean exit; with nothing set it
+  renders the default footer.
 - `test/lib/site_footer_link_contrast_test.rb`: the link ink clears 4.5:1 on the
   band, on the default tokens, in both themes.
 - `e2e/site_footer.spec.js`: the map's script and the footer's layout, in a
@@ -372,4 +450,5 @@ link. Those rules are more specific than the engine's and still apply.
   line inside its column at each, and the line heights. These lab pages load Turbo, so the map's remount after a Turbo visit is
   covered.
 
-`/admin/style` shows the footer under Tricks, with this app's facts or a sample.
+`/admin/style` shows the footer under Tricks, with this app's own facts, or a
+sample when it has declared none (the default footer or `false`).

data/lib/studio/engine.rb

@@ -170,6 +170,15 @@ module Studio
 
     public
 
+    # Survey definitions (docs/SURVEYS.md): every *.rb under
+    # Studio.survey_definitions_path, loaded on boot and again on each
+    # development reload so an edited definition takes effect without a restart.
+    # Surveys defined in an initializer instead stay registered either way.
+    config.to_prepare do
+      dir = Studio.survey_definitions_path
+      Studio::Survey.load_definitions!(Rails.root.join(dir)) if dir.present? && Rails.root
+    end
+
     config.after_initialize do
       # Configure the IP -> location provider for every app that has the gem,
       # so geo detection works the same way everywhere: HTTPS (without which

data/lib/studio/site_footer.rb

@@ -7,7 +7,8 @@ require "cgi"
 # booting the dummy app. See docs/SITE_FOOTER.md.
 #
 # The declared value is a Hash, or a callable that receives the view (for route
-# helpers). EVERY KEY IS OPTIONAL, and a missing key removes its part of the
+# helpers). Unset (nil) is the DEFAULT footer (`default_facts`), and `false` is
+# no footer. EVERY KEY IS OPTIONAL, and a missing key removes its part of the
 # footer rather than printing a placeholder:
 #
 #   config.site_footer = ->(view) {
@@ -105,21 +106,73 @@ module Studio
     end
 
     def validate!(declared)
-      return if declared.nil? || declared.is_a?(Hash) || declared.respond_to?(:call)
+      return if declared.nil? || declared == false || declared.is_a?(Hash) || declared.respond_to?(:call)
 
       raise ArgumentError,
-            "Studio.site_footer must be nil, a Hash, or a callable receiving the view " \
+            "Studio.site_footer must be nil (the default footer), false (no footer), a Hash, or a " \
+            "callable receiving the view (got #{declared.class}). See docs/SITE_FOOTER.md."
+    end
+
+    def validate_address!(declared)
+      return if declared.nil? || declared == false || declared.is_a?(Hash)
+
+      raise ArgumentError,
+            "Studio.site_footer_address must be nil or a Hash of street:, city_line:, lat:, lng: " \
             "(got #{declared.class}). See docs/SITE_FOOTER.md."
     end
 
-    # The normalized facts, or nil when the app declared no footer.
+    # THE DEFAULT FOOTER'S FACTS: what an app that sets nothing gets. Only what
+    # is known to be true of the host: a legal line linking the routes in
+    # DEFAULT_LEGAL that the host really has. The name and the logo come from
+    # `resolve`'s own fallbacks. No address, no email, no tagline, no social row
+    # and no link columns: the engine cannot know them, and a guessed link is a
+    # dead one.
+    #
+    #   routes: the host's route set (Rails.application.routes), or nil to ask
+    #           the view alone.
+    DEFAULT_LEGAL = [["Privacy Policy", :privacy], ["Terms of Service", :terms]].freeze
+
+    def default_facts(view, routes: nil)
+      legal = DEFAULT_LEGAL.filter_map do |label, route_name|
+        path = host_path(view, route_name, routes)
+        [label, path] unless path.nil?
+      end
+      { legal: legal }
+    end
+
+    # The path of the host's route `name`, or nil unless the view can build it
+    # with no arguments and (when the route set is given) a GET reaches it.
+    def host_path(view, name, routes = nil)
+      helper = :"#{name}_path"
+      return nil unless view.respond_to?(helper)
+      return nil unless routes.nil? || get_route?(routes, name)
+
+      text(view.public_send(helper))
+    rescue StandardError
+      nil
+    end
+
+    def get_route?(routes, name)
+      route = routes.named_routes[name]
+      return false if route.nil? || route.required_parts.any?
+
+      verbs = route.verb.to_s
+      verbs.empty? || verbs.split("|").include?("GET")
+    rescue StandardError
+      false
+    end
+
+    # The normalized facts, or nil when there is no footer (the declared value,
+    # or what its callable answered, is nil or false).
     #
     #   name:         the site name the engine resolved (the site identity's title)
     #   logo:         the logo the engine resolved (the navbar logo), or nil
     #   booking_path: the booking page's path (Studio.booking_path_for), or nil
-    def resolve(declared, view, name: nil, logo: nil, booking_path: nil)
+    #   address:      Studio.site_footer_address: the address of facts that
+    #                 carry none of their own
+    def resolve(declared, view, name: nil, logo: nil, booking_path: nil, address: nil)
       raw = declared.respond_to?(:call) ? declared.call(view) : declared
-      return nil if raw.nil?
+      return nil if raw.nil? || raw == false
 
       facts = symbolize(raw)
       site_name = text(facts[:name]) || text(name)
@@ -133,7 +186,7 @@ module Studio
         home_path: safe_href(facts[:home_path], "home_path") || "/",
         tagline: text(facts[:tagline]),
         email: text(facts[:email]),
-        address: address(facts),
+        address: address_for(facts, address),
         social: Array(facts[:social]).filter_map { |row| social(row) },
         columns: Array(facts[:columns]).filter_map { |row| column(row, booking_path) },
         legal: Array(facts[:legal]).filter_map { |row| link(row, booking_path) },
@@ -205,7 +258,7 @@ module Studio
     # no address at all: no Location band and no map.
     def address(facts)
       declared = facts[:address]
-      source = declared.nil? ? facts : symbolize(declared)
+      source = declared.nil? || declared == false ? facts : symbolize(declared)
       street = text(source[:street])
       city_line = text(source[:city_line])
       return nil if street.nil? && city_line.nil?
@@ -228,6 +281,16 @@ module Studio
       }
     end
 
+    # The facts' own address, else the configured one (Studio.site_footer_address).
+    # The facts win: an address of their own is used whole, and an `address:` key
+    # they wrote, even nil or false, is their answer.
+    def address_for(facts, configured)
+      own = address(facts)
+      return own if !own.nil? || facts.key?(:address) || configured.nil? || configured == false
+
+      address(symbolize(configured))
+    end
+
     def coordinate(value)
       return nil if value.nil? || value.to_s.strip.empty?
 

data/lib/studio/survey/breakdown.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Studio
+  class Survey
+    # The per-question results the admin panel draws. Pure Ruby over plain rows,
+    # so the arithmetic is unit-tested without a database.
+    #
+    #   rows: an Enumerable of hashes { answers: {key => {"value" => ...}},
+    #                                   respondent: "alex" | "anonymous",
+    #                                   at: Time }
+    #
+    # Counts are over the rows that ANSWERED the question, not all rows — a
+    # skipped optional question does not dilute its own distribution. A stored
+    # value whose option was later removed from the definition still counts,
+    # under its label snapshot and marked retired, so editing a survey never
+    # silently drops answers from the totals.
+    class Breakdown
+      Bucket = Struct.new(:value, :label, :face, :count, :percent, :retired, keyword_init: true)
+      TextEntry = Struct.new(:text, :respondent, :at, keyword_init: true)
+      Result = Struct.new(:question, :answered, :buckets, :average, :entries, keyword_init: true) do
+        def text? = question.text?
+      end
+
+      def initialize(survey, rows)
+        @survey = survey
+        @rows = rows.to_a
+      end
+
+      def results
+        @results ||= @survey.questions.map { |q| result_for(q) }
+      end
+
+      def self.percent(count, total)
+        return 0 if total.to_i.zero?
+
+        ((count.to_f / total) * 100).round
+      end
+
+      private
+
+      def answers_for(question)
+        @rows.filter_map do |row|
+          entry = (row[:answers] || {})[question.key]
+          next unless entry.is_a?(Hash) && !question.blank_value?(entry["value"])
+
+          [entry, row]
+        end
+      end
+
+      def result_for(question)
+        found = answers_for(question)
+        return text_result(question, found) if question.text?
+
+        counts = Hash.new(0)
+        snapshots = {}
+        found.each do |entry, _row|
+          displays = Array(entry["display"])
+          Array(entry["value"]).each_with_index do |v, i|
+            counts[v.to_s] += 1
+            snapshots[v.to_s] ||= displays[i]
+          end
+        end
+
+        total = found.size
+        buckets = question.options.map do |opt|
+          n = counts.delete(opt.value.to_s) || 0
+          Bucket.new(value: opt.value, label: opt.label, face: opt.face, count: n,
+                     percent: self.class.percent(n, total), retired: false)
+        end
+        counts.sort.each do |value, n|
+          buckets << Bucket.new(value: value, label: snapshots[value].presence || value, count: n,
+                                percent: self.class.percent(n, total), retired: true)
+        end
+
+        Result.new(question: question, answered: total, buckets: buckets, average: average(question, found), entries: [])
+      end
+
+      def average(question, found)
+        return nil unless question.scale?
+
+        nums = found.map { |entry, _| Integer(entry["value"].to_s, exception: false) }.compact
+        return nil if nums.empty?
+
+        (nums.sum.to_f / nums.size).round(2)
+      end
+
+      def text_result(question, found)
+        entries = found.map do |entry, row|
+          TextEntry.new(text: entry["value"].to_s, respondent: row[:respondent].presence || "anonymous", at: row[:at])
+        end
+        entries.sort_by! { |e| e.at || Time.at(0) }.reverse!
+        Result.new(question: question, answered: entries.size, buckets: [], average: nil, entries: entries)
+      end
+    end
+  end
+end

data/lib/studio/survey/export.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Studio
+  class Survey
+    # CSV for one survey's responses. One row per response; one column per
+    # question key in the CURRENT definition, then any retired key a stored
+    # answer still carries, so an export never drops data the definition forgot.
+    #
+    # Written without the csv gem (a bundled, not default, gem from Ruby 3.4):
+    # RFC 4180 quoting, plus a leading apostrophe on any cell a spreadsheet
+    # would execute as a formula (=, +, -, @, tab, CR) — respondents type these
+    # cells, so they are untrusted.
+    class Export
+      META = %w[response_id survey_version status started_at completed_at respondent user_id email_ref user_agent_class].freeze
+      FORMULA_LEAD = /\A[=+\-@\t\r]/
+
+      # rows: hashes with the META keys (as symbols) plus :answers. survey may be
+      # nil for a slug whose definition was deleted; its stored keys still export.
+      def initialize(survey, rows)
+        @survey = survey
+        @rows = rows.to_a
+      end
+
+      def keys
+        @keys ||= begin
+          current = @survey ? @survey.keys : []
+          retired = @rows.flat_map { |r| (r[:answers] || {}).keys }.uniq - current
+          current + retired.sort
+        end
+      end
+
+      def to_csv
+        lines = [line(META + keys)]
+        @rows.each do |row|
+          answers = row[:answers] || {}
+          cells = META.map { |k| format_time(row[k.to_sym]) }
+          cells += keys.map { |k| answer_cell(answers[k]) }
+          lines << line(cells)
+        end
+        lines.join
+      end
+
+      def self.cell(value)
+        text = value.to_s
+        text = "'#{text}" if text.match?(FORMULA_LEAD)
+        text.match?(/[",\n\r]/) || text != text.strip ? %("#{text.gsub('"', '""')}") : text
+      end
+
+      private
+
+      def line(cells) = "#{cells.map { |c| self.class.cell(c) }.join(",")}\r\n"
+
+      def format_time(value)
+        value.respond_to?(:iso8601) ? value.iso8601 : value
+      end
+
+      def answer_cell(entry)
+        return nil unless entry.is_a?(Hash)
+
+        value = entry["value"]
+        value.is_a?(Array) ? value.join("; ") : value
+      end
+    end
+  end
+end