studio-engine 0.86.0 → 0.88.0

data/lib/studio/survey.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require "digest"
+require "active_support/core_ext/object/blank"
+
+module Studio
+  # A SURVEY, defined in app code (docs/SURVEYS.md).
+  #
+  #   # config/surveys/first_game.rb — loaded by the engine on boot and reload
+  #   Studio.define_survey "first-game" do
+  #     title "How was your first game?"
+  #     intro "Two minutes, six questions. It shapes what we build next."
+  #     thank_you "We read every answer."
+  #     next_action label: "Play another game", url: "/play"
+  #     allow_anonymous true
+  #
+  #     emoji_scale :overall, "How was your first game?", required: true
+  #     rating :rules, "How clear were the rules?", low_label: "Lost", high_label: "Crystal clear"
+  #     choice :found_us, "How did you find us?", options: ["Email", "A friend", "Search", "Other"]
+  #     multi_choice :liked, "What did you enjoy?", options: ["The board", "The pace", "The art"]
+  #     short_text :one_word, "Describe it in one word."
+  #     long_text :anything_else, "Anything else?", help: "Bugs, ideas, complaints — all welcome."
+  #   end
+  #
+  # The definition is the CURRENT shape of the survey, nothing more. A stored
+  # answer carries its own question key, type and label snapshot (and the chosen
+  # option's label), so editing or removing a question never rewrites what an
+  # earlier respondent was asked. `version` defaults to a digest of the questions
+  # and is stamped on every response.
+  class Survey
+    class DefinitionError < ArgumentError; end
+
+    SLUG_FORMAT = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+    KEY_FORMAT = /\A[a-z][a-z0-9_]{0,62}\z/
+    # The same two shapes, unanchored, for route constraints.
+    ROUTE_SLUG = /[a-z0-9]+(?:-[a-z0-9]+)*/
+    ROUTE_KEY = /[a-z][a-z0-9_]{0,62}/
+    TYPES = %i[emoji_scale rating choice multi_choice short_text long_text].freeze
+    SCALE_TYPES = %i[emoji_scale rating].freeze
+    SELECT_TYPES = %i[emoji_scale rating choice].freeze
+    TEXT_TYPES = %i[short_text long_text].freeze
+
+    EMOJI_FACES = ["\u{1F61E}", "\u{1F615}", "\u{1F610}", "\u{1F642}", "\u{1F60D}"].freeze
+    DEFAULT_EMOJI_LABELS = ["Awful", "Not great", "Okay", "Good", "Loved it"].freeze
+    TEXT_LIMITS = { short_text: 280, long_text: 5000 }.freeze
+
+    Option = Struct.new(:value, :label, :face, keyword_init: true)
+
+    # One question. Immutable once built.
+    class Question
+      attr_reader :key, :type, :label, :help, :options, :low_label, :high_label, :placeholder, :max_length
+
+      def initialize(key:, type:, label:, required: false, help: nil, options: nil, labels: nil,
+                     low_label: nil, high_label: nil, placeholder: nil, max_length: nil)
+        @key = key.to_s
+        @type = type.to_sym
+        @label = label.to_s.strip
+        @required = required == true
+        @help = help.to_s.strip.presence
+        @low_label = low_label.to_s.strip.presence
+        @high_label = high_label.to_s.strip.presence
+        @placeholder = placeholder.to_s.strip.presence
+        validate_shape!(options, labels, max_length)
+        @options = build_options(options, labels).freeze
+        @max_length = text? ? Integer(max_length || TEXT_LIMITS.fetch(@type)) : nil
+        freeze
+      end
+
+      def required? = @required
+      def scale? = SCALE_TYPES.include?(type)
+      def select? = SELECT_TYPES.include?(type)
+      def multi? = type == :multi_choice
+      def text? = TEXT_TYPES.include?(type)
+      def numbered? = !text?
+
+      def option(value)
+        options.find { |o| o.value.to_s == value.to_s }
+      end
+
+      def blank_value?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?) || value.to_s.strip.empty?
+      end
+
+      # [normalized_value, error_message]. A blank input normalizes to nil, which
+      # the response stores as "unanswered".
+      def normalize(raw)
+        raw = Array(raw).map(&:to_s).reject { |v| v.strip.empty? } if multi?
+        return [nil, nil] if blank_value?(raw)
+
+        case type
+        when :emoji_scale, :rating
+          int = Integer(raw.to_s.strip, exception: false)
+          return [nil, "Pick one of the options."] unless int && option(int)
+
+          [int, nil]
+        when :choice
+          opt = option(raw.to_s)
+          opt ? [opt.value, nil] : [nil, "Pick one of the options."]
+        when :multi_choice
+          values = raw.uniq
+          return [nil, "Pick from the listed options."] unless values.all? { |v| option(v) }
+
+          # Keep the definition's order, not the click order.
+          [options.map(&:value).select { |v| values.include?(v) }, nil]
+        else
+          text = raw.to_s.strip.gsub("\r\n", "\n")
+          return [nil, "Keep it under #{max_length} characters."] if text.length > max_length
+
+          [text, nil]
+        end
+      end
+
+      # The human snapshot of an answer: the option label(s), or the text itself.
+      def display(value)
+        return nil if value.nil?
+        return Array(value).map { |v| option(v)&.label || v.to_s } if multi?
+        return value.to_s if text?
+
+        option(value)&.label || value.to_s
+      end
+
+      def to_h
+        { key: key, type: type, label: label, required: required?, help: help,
+          options: options.map { |o| [o.value, o.label] }, low_label: low_label, high_label: high_label }
+      end
+
+      private
+
+      def validate_shape!(options, labels, max_length)
+        raise DefinitionError, "question key #{key.inspect} must match #{KEY_FORMAT.inspect}" unless key.match?(KEY_FORMAT)
+        raise DefinitionError, "question #{key}: unknown type #{type.inspect} (one of #{TYPES.join(", ")})" unless TYPES.include?(type)
+        raise DefinitionError, "question #{key}: label is required" if label.empty?
+
+        if %i[choice multi_choice].include?(type)
+          raise DefinitionError, "question #{key}: #{type} needs at least two options" if Array(options).size < 2
+        elsif options
+          raise DefinitionError, "question #{key}: options: is only for choice and multi_choice"
+        end
+
+        if labels && type != :emoji_scale
+          raise DefinitionError, "question #{key}: labels: is only for emoji_scale"
+        end
+        if labels && Array(labels).size != 5
+          raise DefinitionError, "question #{key}: emoji_scale takes exactly five labels"
+        end
+        if (low_label || high_label) && type != :rating
+          raise DefinitionError, "question #{key}: low_label/high_label are only for rating"
+        end
+        if max_length && !text?
+          raise DefinitionError, "question #{key}: max_length: is only for short_text and long_text"
+        end
+        return unless max_length && !(Integer(max_length, exception: false).to_i.between?(1, TEXT_LIMITS[:long_text]))
+
+        raise DefinitionError, "question #{key}: max_length must be 1..#{TEXT_LIMITS[:long_text]}"
+      end
+
+      def build_options(options, labels)
+        case type
+        when :emoji_scale
+          names = Array(labels || DEFAULT_EMOJI_LABELS).map { |l| l.to_s.strip }
+          raise DefinitionError, "question #{key}: emoji labels cannot be blank" if names.any?(&:empty?)
+
+          names.each_with_index.map { |name, i| Option.new(value: i + 1, label: name, face: EMOJI_FACES[i]) }
+        when :rating
+          (1..5).map { |n| Option.new(value: n, label: n.to_s) }
+        when :choice, :multi_choice
+          opts = Array(options).map { |o| coerce_option(o) }
+          values = opts.map(&:value)
+          raise DefinitionError, "question #{key}: option values must be unique" if values.uniq.size != values.size
+
+          opts
+        else
+          []
+        end
+      end
+
+      def coerce_option(raw)
+        label, value =
+          case raw
+          when Hash then [raw[:label] || raw["label"], raw[:value] || raw["value"]]
+          when Array then [raw[1], raw[0]]
+          else [raw, nil]
+          end
+        label = label.to_s.strip
+        raise DefinitionError, "question #{key}: option labels cannot be blank" if label.empty?
+
+        value = (value.presence || label.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_+|_+\z/, "")).to_s
+        raise DefinitionError, "question #{key}: option #{label.inspect} has no usable value" if value.empty?
+
+        Option.new(value: value, label: label)
+      end
+    end
+
+    # The block DSL. Every setter is a plain method so `title "x"` reads well.
+    class Builder
+      def initialize(slug)
+        @attrs = { slug: slug.to_s, questions: [] }
+      end
+
+      def title(text) = @attrs[:title] = text
+      def intro(text) = @attrs[:intro] = text
+      def thank_you(text) = @attrs[:thank_you] = text
+      def allow_anonymous(flag = true) = @attrs[:allow_anonymous] = flag
+      def version(value) = @attrs[:version] = value
+
+      def next_action(label:, url:)
+        @attrs[:next_action] = { label: label.to_s.strip, url: url.to_s.strip }
+      end
+
+      TYPES.each do |type|
+        define_method(type) do |key, label, **opts|
+          @attrs[:questions] << Question.new(key: key, type: type, label: label, **opts)
+        end
+      end
+
+      def build = Survey.new(**@attrs)
+    end
+
+    attr_reader :slug, :title, :intro, :thank_you, :next_action, :questions, :version
+
+    def initialize(slug:, title: nil, intro: nil, thank_you: nil, next_action: nil, allow_anonymous: false,
+                   version: nil, questions: [])
+      @slug = slug.to_s
+      @title = title.to_s.strip
+      @intro = intro.to_s.strip.presence
+      @thank_you = thank_you.to_s.strip.presence || "We appreciate you taking the time."
+      @next_action = next_action
+      @allow_anonymous = allow_anonymous == true
+      @questions = questions.dup.freeze
+      validate!
+      @version = (version.presence || fingerprint).to_s
+      freeze
+    end
+
+    def allow_anonymous? = @allow_anonymous
+
+    def question(key)
+      questions.find { |q| q.key == key.to_s }
+    end
+
+    def keys = questions.map(&:key)
+    def required_keys = questions.select(&:required?).map(&:key)
+
+    private
+
+    def validate!
+      raise DefinitionError, "survey slug #{slug.inspect} must be lowercase words joined by hyphens" unless slug.match?(SLUG_FORMAT)
+      raise DefinitionError, "survey #{slug}: title is required" if title.empty?
+      raise DefinitionError, "survey #{slug}: needs at least one question" if questions.empty?
+
+      dupes = keys.group_by(&:itself).select { |_, v| v.size > 1 }.keys
+      raise DefinitionError, "survey #{slug}: duplicate question keys #{dupes.join(", ")}" if dupes.any?
+
+      validate_next_action!
+    end
+
+    def validate_next_action!
+      return if next_action.nil?
+
+      label, url = next_action.values_at(:label, :url)
+      raise DefinitionError, "survey #{slug}: next_action needs a label and a url" if label.to_s.empty? || url.to_s.empty?
+      # A relative path or an http(s) URL — never javascript: or a protocol-relative //host.
+      return if url.match?(%r{\A/(?!/)}) || url.match?(%r{\Ahttps?://}i)
+
+      raise DefinitionError, "survey #{slug}: next_action url must be a /path or an http(s) URL"
+    end
+
+    def fingerprint
+      Digest::SHA256.hexdigest(questions.map(&:to_h).inspect)[0, 12]
+    end
+
+    # --- registry --------------------------------------------------------------
+
+    @registry = {}
+    @mutex = Mutex.new
+
+    class << self
+      def define(slug, &block)
+        raise DefinitionError, "define_survey needs a block" unless block
+
+        builder = Builder.new(slug)
+        builder.instance_eval(&block)
+        survey = builder.build
+        @mutex.synchronize { @registry[survey.slug] = survey }
+        survey
+      end
+
+      def find(slug) = @registry[slug.to_s]
+
+      def all = @registry.values.sort_by(&:slug)
+
+      def reset! = @mutex.synchronize { @registry.clear }
+
+      # Loads every *.rb under the app's survey directory. `load`, not `require`,
+      # so a development reload picks up an edited definition.
+      def load_definitions!(dir)
+        return [] unless dir && File.directory?(dir.to_s)
+
+        Dir[File.join(dir.to_s, "**", "*.rb")].sort.each { |path| load path }
+      end
+    end
+  end
+end

data/lib/studio/version.rb

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

data/lib/studio.rb

@@ -49,6 +49,9 @@ require "studio/email_smoke"
 require "studio/mail_transport"
 require "studio/redis"
 require "studio/cable"
+require "studio/survey"
+require "studio/survey/breakdown"
+require "studio/survey/export"
 
 module Studio
   mattr_accessor :app_name,            default: "Studio"
@@ -582,10 +585,16 @@ module Studio
   # primitives: Google Calendar's appointment page inline, in a popup, and on a
   # page. See docs/SITE_FOOTER.md and docs/BOOKING.md.
 
-  # The footer's facts: a Hash, or a callable receiving the view. nil (the
-  # default) means this app has no footer, and `studio_site_footer` renders
-  # nothing, so a layout can call it before the app declares one. Every key is
-  # optional; shape and rules: lib/studio/site_footer.rb.
+  # The footer's facts. THE FOOTER IS ON BY DEFAULT: left unset (nil), the
+  # layout line `studio_site_footer` renders the DEFAULT footer, built from what
+  # the engine already knows (the site name, the footer or navbar logo, and a
+  # legal line linking the host's `privacy` and `terms` routes when it has
+  # them). No address, no map, no email, no link columns.
+  #
+  #   nil (unset)   the default footer
+  #   false         NO footer: the one opt-out
+  #   a Hash, or a callable receiving the view: the app's own facts. Every key
+  #   is optional; shape and rules: lib/studio/site_footer.rb.
   #
   #   config.site_footer = ->(view) {
   #     { tagline: "Everything, by example",
@@ -601,6 +610,35 @@ module Studio
     @@site_footer = declared
   end
 
+  # True unless the app turned the footer off (`config.site_footer = false`).
+  def self.site_footer_enabled?
+    site_footer != false
+  end
+
+  # True when the app wrote its own facts, as against taking the default footer
+  # (unset) or none (false).
+  def self.site_footer_declared?
+    !site_footer.nil? && site_footer != false
+  end
+
+  # THE LOCATION, AS ONE SETTING: the address the footer prints in its Location
+  # band, and maps when it carries lat: and lng:. nil (the default) is no
+  # location. It is how an app on the default footer adds one without writing
+  # the facts callable:
+  #
+  #   config.site_footer_address = { street: "123 Example St", city_line: "Washington, DC 20024",
+  #                                  lat: 38.8894, lng: -77.0352 }
+  #
+  # The keys are the facts' `address:` keys (docs/SITE_FOOTER.md). An app's own
+  # facts WIN: when they carry an address this is not read, and `address: false`
+  # there shows none.
+  mattr_reader :site_footer_address, default: nil
+
+  def self.site_footer_address=(declared)
+    SiteFooter.validate_address!(declared)
+    @@site_footer_address = declared || nil
+  end
+
   # Controllers whose pages keep the footer for a SIGNED-IN viewer, by
   # controller name ("landing") or path ("admin/reports"). A visitor gets the
   # footer on every page; a signed-in viewer gets it only here, because every
@@ -673,6 +711,48 @@ module Studio
     Booking.path_for(booking_path, view, drawn: draw_booking_routes)
   end
 
+  # ── Surveys (docs/SURVEYS.md) ──────────────────────────────────────────────
+  # The public survey pages, /surveys/:slug (Studio::SurveysController). OPT-IN:
+  # `/surveys` is a path an app may already own, and a duplicate helper name
+  # raises while the host's routes.rb loads, which kills every route in it.
+  #
+  #   config.draw_survey_routes = true
+  mattr_accessor :draw_survey_routes, default: false
+
+  # The admin results panel, /admin/surveys (Studio::AdminSurveysController).
+  # OPT-IN for the same reason, and independent of the public pages, so an app
+  # can read results it collects elsewhere.
+  #
+  #   config.draw_admin_survey_routes = true
+  mattr_accessor :draw_admin_survey_routes, default: false
+
+  # Where the app's survey definitions live, relative to Rails.root. Every *.rb
+  # in it is loaded at boot and on each development reload.
+  mattr_accessor :survey_definitions_path, default: "config/surveys"
+
+  # Attribution for an email arrival: ->(controller) { String | nil }. Called on
+  # every survey request; its answer is stamped on the response as email_ref the
+  # first time one is present. Cyvasse passes its EmailReferral ref here.
+  mattr_accessor :survey_ref_resolver, default: ->(_controller) {}
+
+  # Called once, after a response completes: ->(response) { ... }. A raise is
+  # logged and swallowed — the respondent still lands on the thank-you screen.
+  mattr_accessor :on_survey_completed, default: ->(_response) {}
+
+  # Define a survey in app code. See Studio::Survey for the DSL.
+  def self.define_survey(slug, &block)
+    Survey.define(slug, &block)
+  end
+
+  # Every defined survey, by slug.
+  def self.surveys
+    Survey.all
+  end
+
+  def self.survey(slug)
+    Survey.find(slug)
+  end
+
   # THE FRAME'S CROP AT REST: nil or false (the default) shows Google's whole
   # page; a Hash of the schedule's measured box crops the frame to the slot
   # picker until it is used. The numbers belong to ONE schedule, so there is no
@@ -1207,14 +1287,25 @@ module Studio
   end
 
   # The site footer's facts resolved for a view (lib/studio/site_footer.rb), or
-  # nil when the app declared none. The name defaults to the site identity's
-  # title and the logo to the navbar logo, so an app that has set those up says
-  # them once.
+  # nil when the app turned the footer off (or its own callable answered nil).
+  # Unset, the facts are the default footer's. The name defaults to the site
+  # identity's title and the logo to the navbar logo, so an app that has set
+  # those up says them once; Studio.site_footer_address is the address of any
+  # facts that carry none.
   def self.site_footer_for(view)
-    return nil if site_footer.nil?
+    return nil unless site_footer_enabled?
 
-    SiteFooter.resolve(site_footer, view, name: site_identity[:title], logo: logo_for("Footer Logo"),
-                                          booking_path: booking_path_for(view))
+    declared = site_footer.nil? ? SiteFooter.default_facts(view, routes: host_route_set) : site_footer
+    SiteFooter.resolve(declared, view, name: site_identity[:title], logo: logo_for("Footer Logo"),
+                                       booking_path: booking_path_for(view), address: site_footer_address)
+  end
+
+  # The host's route set, for the default footer's legal links. nil outside a
+  # booted Rails app.
+  def self.host_route_set
+    return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+    ::Rails.application.routes
   end
 
   # Navbar links resolved for a view context (lib/studio/navbar_links.rb).
@@ -1512,6 +1603,25 @@ module Studio
       patch "admin/email_images/:variant", to: "studio/email_images#update", as: :admin_email_image,
             constraints: { variant: /[a-z_]+/ }
 
+      # Surveys (docs/SURVEYS.md). Both halves OPT-IN — see
+      # Studio.draw_survey_routes and Studio.draw_admin_survey_routes.
+      if Studio.draw_survey_routes
+        slug = { slug: Studio::Survey::ROUTE_SLUG }
+        get   "surveys/:slug",              to: "studio/surveys#show",   as: :studio_survey, constraints: slug
+        post  "surveys/:slug",              to: "studio/surveys#submit", constraints: slug
+        patch "surveys/:slug/answers/:key", to: "studio/surveys#answer", as: :studio_survey_answer,
+              constraints: slug.merge(key: Studio::Survey::ROUTE_KEY)
+        get   "surveys/:slug/thanks",       to: "studio/surveys#thanks", as: :studio_survey_thanks, constraints: slug
+      end
+
+      if Studio.draw_admin_survey_routes
+        get "admin/surveys",              to: "studio/admin_surveys#index",  as: :admin_surveys
+        get "admin/surveys/:slug/export", to: "studio/admin_surveys#export", as: :admin_survey_export,
+            constraints: { slug: %r{[^/.]+} }, defaults: { format: :csv }
+        get "admin/surveys/:slug",        to: "studio/admin_surveys#show",   as: :admin_survey,
+            constraints: { slug: %r{[^/.]+} }
+      end
+
       # Model-page protocol (v1) — a reusable per-record inspector. Drawn into
       # every consuming app: /models/:model/:id renders one record as pretty JSON
       # plus a copy/paste rails-console command; /models/:model/random bounces to

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.86.0
+  version: 0.88.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -336,6 +336,7 @@ files:
 - app/controllers/schema_controller.rb
 - app/controllers/sessions_controller.rb
 - app/controllers/solana_sessions_controller.rb
+- app/controllers/studio/admin_surveys_controller.rb
 - app/controllers/studio/bookings_controller.rb
 - app/controllers/studio/email_images_controller.rb
 - app/controllers/studio/emails_controller.rb
@@ -350,6 +351,7 @@ files:
 - app/controllers/studio/public_users_controller.rb
 - app/controllers/studio/session_states_controller.rb
 - app/controllers/studio/site_identities_controller.rb
+- app/controllers/studio/surveys_controller.rb
 - app/controllers/style_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio/admin_models_table_helper.rb
@@ -386,6 +388,7 @@ files:
 - app/models/studio/link.rb
 - app/models/studio/model_page.rb
 - app/models/studio/site_identity.rb
+- app/models/studio/survey_response.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
 - app/services/studio/banner.rb
@@ -439,6 +442,8 @@ files:
 - app/views/studio/admin_models/_teams_table.html.erb
 - app/views/studio/admin_models/index.html.erb
 - app/views/studio/admin_models/show.html.erb
+- app/views/studio/admin_surveys/index.html.erb
+- app/views/studio/admin_surveys/show.html.erb
 - app/views/studio/banners/_app_banner.html.erb
 - app/views/studio/banners/_button.html.erb
 - app/views/studio/banners/_dev_mode_button.html.erb
@@ -544,6 +549,13 @@ files:
 - app/views/studio/site_footer/_map_assets.html.erb
 - app/views/studio/site_footer/_social_icon.html.erb
 - app/views/studio/site_identities/edit.html.erb
+- app/views/studio/surveys/_question.html.erb
+- app/views/studio/surveys/_script.html.erb
+- app/views/studio/surveys/_styles.html.erb
+- app/views/studio/surveys/not_found.html.erb
+- app/views/studio/surveys/show.html.erb
+- app/views/studio/surveys/sign_in_required.html.erb
+- app/views/studio/surveys/thanks.html.erb
 - app/views/style/_host.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
@@ -585,6 +597,7 @@ files:
 - db/migrate/20260902000001_create_studio_knowledge_expectations.rb
 - db/migrate/20260902000002_add_expectation_to_studio_knowledge_docs.rb
 - db/migrate/20260930120000_create_studio_site_identities.rb
+- db/migrate/20261005120000_create_studio_survey_responses.rb
 - docs/BOOKING.md
 - docs/SITE_FOOTER.md
 - lib/active_storage/service/studio_trash_s3_service.rb
@@ -627,6 +640,9 @@ files:
 - lib/studio/session_state.rb
 - lib/studio/sidebar_sections.rb
 - lib/studio/site_footer.rb
+- lib/studio/survey.rb
+- lib/studio/survey/breakdown.rb
+- lib/studio/survey/export.rb
 - lib/studio/theme_resolver.rb
 - lib/studio/ui_primitives.rb
 - lib/studio/username_generator.rb