keystone_ui-pages 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebfd45f732eefa22bd08b4a5abd3c13ff88a2fa65c55a5309c89c8b21468c69c
-  data.tar.gz: bb309abcbff6e6d5a12aa1096db65c1a3d298ca1db781ed4c3110a5b4e6334a3
+  metadata.gz: 4b2fa7cf313f2a2a1683f81cf2596fd0a8ad2cb2054a0f3deb54909f0e9fd34c
+  data.tar.gz: 8b35ba167349c28f76a01d1f24b0934e2f1e9aa336267380a3b8ad7a0c86db88
 SHA512:
-  metadata.gz: 845983515d8a34e9d1c4ef3faff043e2ec832461b4fbf9be78b246d9fc9aba12c9823b69f3b573879df2755dd30e7041a7b1865939cab16d53ee1dad64f6a94e
-  data.tar.gz: dc35e48a37f83ed5b6e61d0d41b22e92139017c8b0fa9cb1cabb458e33bb61a69b38d625800a6f7f7113fe5f3ae80689691f5c2b4a2eafbef3f2db8753b3c4cf
+  metadata.gz: 9a43808d3e942184d341e70ac5cb67b5f28b1ee5164382333b12489554e1d245fc076b609da9394180b39bdc409ac4566d219cde722c0b03d9dfdb6640efe95e
+  data.tar.gz: d42a1af97b0bc8b2f45c21484eed8b6964b00c7b404ad8f9d3de80a26eacda1a776cd070800ae111aa52a0eb9e4b5b6eeb4c2ffb13b065b2114fcfb27882cde3

data/app/assets/builds/keystone_ui_pages/forms.js

@@ -0,0 +1 @@
+(()=>{document.addEventListener("turbo:frame-missing",t=>{t.target.id.startsWith("keystone-ui-pages-form-")&&(t.preventDefault(),t.detail.visit(t.detail.response))});})();

data/app/assets/builds/keystone_ui_pages/reporting.js

@@ -0,0 +1 @@
+(()=>{function d(e,t,n={}){document.dispatchEvent(new CustomEvent(`keystone-ui-pages:${t}`,{detail:{slug:e.dataset.pageSlug,place:e.dataset.pagePlace,...n}})),fetch(e.dataset.pageEvents,{method:"POST",body:new URLSearchParams({kind:t,element:n.element??""}),credentials:"same-origin",keepalive:!0}).catch(()=>{})}function a(){if(document.prerendering)return document.addEventListener("prerenderingchange",a,{once:!0});document.querySelectorAll("[data-page-events]:not([data-page-viewed])").forEach(e=>{e.dataset.pageViewed="",d(e,"view")})}function o(e){let t=e.target.closest("a, button"),n=t?.closest("[data-page-events]"),c=t?.closest("[data-page-element]");n&&c&&d(n,"click",{element:c.dataset.pageElement,href:t.href??null})}document.addEventListener("DOMContentLoaded",a);document.addEventListener("turbo:load",a);document.addEventListener("click",o);})();

data/app/controllers/concerns/keystone_ui/pages/host_checks.rb

@@ -15,6 +15,12 @@ module KeystoneUi
         send(KeystoneUi::Pages.owner_method) if KeystoneUi::Pages.owner_method
       end
 
+      def viewable?(page)
+        return true unless KeystoneUi::Pages.view_check_method
+
+        send(KeystoneUi::Pages.view_check_method, page)
+      end
+
       def refuse
         return head(:not_found) unless KeystoneUi::Pages.refusal_method
 

data/app/controllers/keystone_ui/pages/events_controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "keystone_ui/pages/event"
+require "keystone_ui/pages/operations"
+
+module KeystoneUi
+  module Pages
+    class EventsController < KeystoneUi::Pages.base_controller.constantize
+      include HostChecks
+      skip_forgery_protection
+
+      def create
+        page = owned_pages.find_by(slug: params[:slug])
+        return refuse unless page&.reporting? && viewable?(page) && described?(page)
+
+        Rails.error.handle(context: { page_id: page.id, kind: kind }) do
+          KeystoneUi::Pages.place_settings.dig(page.place, :events).call(Event.new(page: page, place: page.place, kind: kind, element: element, request: request))
+        end
+        head :no_content
+      end
+
+      private
+
+      def described?(page)
+        kind == "view" || (kind == "click" && on_live_version?(page))
+      end
+
+      def on_live_version?(page)
+        Operations.elements(page.live_version.document).any? { |placed| placed["id"] == element }
+      end
+
+      def kind
+        params.fetch(:kind, "view")
+      end
+
+      def element
+        params[:element].presence if kind == "click"
+      end
+    end
+  end
+end

data/app/controllers/keystone_ui/pages/manage/elements_controller.rb

@@ -7,7 +7,7 @@ module KeystoneUi
         include EditsPages
 
         def create
-          changed(Operations.add(page.document, params.require(:key), column_id: params.require(:column_id)))
+          changed(Operations.add(page.document, params.require(:key), column_id: params.require(:column_id), catalog: KeystoneUi::Pages.offered_catalog(page.place)))
         end
 
         def bind

data/app/controllers/keystone_ui/pages/pages_controller.rb

@@ -11,9 +11,10 @@ module KeystoneUi
       def show
         page = owned_pages.find_by(slug: params[:slug])
         @version = page&.live_version
-        return refuse if @version.nil? || !viewable?(page)
+        return refuse if @version.nil? || !KeystoneUi::Pages.slugged?(page.place) || !viewable?(page)
 
         @values = visitor_values(page)
+        @page = page
       end
 
       private
@@ -21,12 +22,6 @@ module KeystoneUi
       def visitor_values(page)
         send(KeystoneUi::Pages.values_method, page) if KeystoneUi::Pages.values_method
       end
-
-      def viewable?(page)
-        return true unless KeystoneUi::Pages.view_check_method
-
-        send(KeystoneUi::Pages.view_check_method, page)
-      end
     end
   end
 end

data/app/controllers/keystone_ui/pages/submissions_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "keystone_ui/pages/submission"
+require "keystone_ui/pages/submissions"
+require "keystone_ui/pages/turnstile"
+require "keystone_ui/pages/operations"
+
+module KeystoneUi
+  module Pages
+    class SubmissionsController < KeystoneUi::Pages.base_controller.constantize
+      include HostChecks
+      helper KeystoneUiHelper
+      helper FormHelper
+      layout -> { KeystoneUi::Pages.layout }
+
+      def create
+        page = owned_pages.find_by(slug: params[:slug])
+        version = page&.versions&.find_by(number: params[:number])
+        form = version && Operations.elements(version.document).find { |element| element["id"] == params[:element_id] && element["key"] == "form" }
+        handler = form && KeystoneUi::Pages.submission_handler(page.place)
+        return head(:not_found) unless handler
+        return refuse unless viewable?(page)
+
+        values = Submissions.accepted(form, params)
+        problems = Submissions.problems(form, values)
+        return render(:refused, status: :unprocessable_entity, locals: { form: form, version: version, problems: problems, values: values }) if problems.any?
+
+        begin
+          handler.call(Submission.new(page: page, version: version, form_name: Submissions.form_name(form), element_id: form["id"], values: Submissions.delivered(form, values), request: request, bot: bot?))
+        rescue StandardError => error
+          Rails.error.report(error, handled: true, context: { page_id: page.id, form_name: Submissions.form_name(form) })
+          return render(:failed, status: :internal_server_error, locals: { form: form, version: version, values: values })
+        end
+        return redirect_to(Submissions.next_address(form), status: :see_other, allow_other_host: true) if Submissions.next_address(form)
+
+        @element_id = form["id"]
+        @thank_you = Submissions.thank_you(form)
+      end
+
+      private
+
+      def bot?
+        Submissions.bot?(params) || (Turnstile.on? && !Turnstile.confirmed?(params["cf-turnstile-response"], request.remote_ip))
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui/pages/drawing_helper.rb

@@ -5,10 +5,13 @@ require "keystone_ui/pages/operations"
 module KeystoneUi
   module Pages
     module DrawingHelper
+      include FormHelper
+
       NARROW_SPANS = { "1/1" => "col-span-12", "3/4" => "col-span-9", "2/3" => "col-span-8", "1/2" => "col-span-6", "1/3" => "col-span-4", "1/4" => "col-span-3" }.freeze
       WIDE_SPANS = { "1/1" => "@sm:col-span-12", "3/4" => "@sm:col-span-9", "2/3" => "@sm:col-span-8", "1/2" => "@sm:col-span-6", "1/3" => "@sm:col-span-4", "1/4" => "@sm:col-span-3" }.freeze
       ELEMENT_ALIGNMENTS = { "stretch" => "flex flex-col", "start" => "flex justify-start", "center" => "flex justify-center", "end" => "flex justify-end" }.freeze
       COLUMN_ALIGNMENTS = { "top" => "justify-start", "center" => "justify-center", "bottom" => "justify-end" }.freeze
+      DRAWING_FORMAT = 2
       SIZED_SECTION_PADDING = "py-[calc(var(--ks-spacing)*16)] lg:py-[calc(var(--ks-spacing)*24)]"
       SHADED_CLASSES = "bg-(color:--ks-color-fill-muted) dark:bg-(color:--ks-color-fill-muted-dark)"
       PLAIN_FIGURE_DIVIDER = "@sm:[.ks-pages-column:has(.ks-metric-plain)+&:has(.ks-metric-plain)]:border-l-(length:--ks-border-width) " \
@@ -16,9 +19,18 @@ module KeystoneUi
                              "dark:@sm:[.ks-pages-column:has(.ks-metric-plain)+&:has(.ks-metric-plain)]:border-(color:--ks-color-border-dark)"
 
       def drawn_version(version, values: {})
-        key = [ "keystone_ui_pages", version.id, Operations.digest(values.to_h.stringify_keys) ]
+        key = [ "keystone_ui_pages", DRAWING_FORMAT, KeystoneUi::Pages.turnstile_site_key, version.id, Operations.digest(values.to_h.stringify_keys) ]
         @drawn_page_id = version.page_id
-        Rails.cache.fetch(key) { drawn_document(version.document, values: values).to_str }.html_safe
+        @drawn_version = version
+        load_forms_script(version)
+        with_visitor_token(Rails.cache.fetch(key) { without_visitor_tokens(drawn_document(version.document, values: values).to_str) }).html_safe
+      end
+
+      def reporting_data(page)
+        return {} unless page.reporting?
+
+        content_for :head, javascript_include_tag("keystone_ui_pages/reporting", defer: true)
+        { page_events: keystone_ui_pages.page_events_path(page.slug), page_slug: page.slug, page_place: page.place }
       end
 
       def pages_paragraph(text:)
@@ -29,11 +41,20 @@ module KeystoneUi
 
       def drawn_document(document, editing: false, values: {})
         @drawn_values = values.to_h.stringify_keys
+        @drawn_version = nil if editing
         safe_join(document["sections"].map { |section| drawn_section(section, editing) })
       end
 
       private
 
+      def load_forms_script(version)
+        return if @forms_script_loaded || Operations.elements(version.document).none? { |element| element["key"] == "form" }
+
+        @forms_script_loaded = true
+        content_for :head, javascript_include_tag("keystone_ui_pages/forms", defer: true)
+        content_for :head, javascript_include_tag("https://challenges.cloudflare.com/turnstile/v0/api.js", async: true, defer: true) if KeystoneUi::Pages.turnstile_site_key.present?
+      end
+
       def rich_paragraphs(html)
         stored = Nokogiri::HTML5.fragment(html)
         stored.css("script, style").each(&:remove)
@@ -99,7 +120,7 @@ module KeystoneUi
       def drawn_element(element)
         return reported_missing(element) unless KeystoneUi::Pages.catalog.find(element["key"])
 
-        wrapped_element(element) unless hidden?(element)
+        wrapped_element(element, data: { page_element: element["id"] }) unless hidden?(element)
       end
 
       def hidden?(node)
@@ -149,6 +170,7 @@ module KeystoneUi
       def component_for(element)
         definition = KeystoneUi::Pages.catalog.find(element["key"])
         values = definition.fields.reject { |field| field[:classes] }.to_h { |field| [ field[:key].to_sym, field_value(field, filled(element["fields"][field[:key].to_s]) || field[:default]) ] }
+        values.merge!(element_id: element["id"], version: @drawn_version) if definition.placed
         return send(definition.component, **values) unless definition.body
 
         body = values.delete(definition.body)

data/app/helpers/keystone_ui/pages/editor_helper.rb

@@ -7,7 +7,7 @@ module KeystoneUi
     module EditorHelper
       def editor_props(page)
         {
-          elements: KeystoneUi::Pages.catalog.elements.map { |element| element.to_h.slice(:key, :name, :fields, :icon, :group, :align) },
+          elements: KeystoneUi::Pages.offered_elements(page.place).map { |element| element.to_h.slice(:key, :name, :fields, :icon, :group, :align) },
           canvas: editor_canvas(page),
           document: page.document,
           elements_url: manage_page_elements_path(page),

data/app/helpers/keystone_ui/pages/form_helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "keystone_ui/pages/submissions"
+require "keystone_ui/pages/form_field_kinds"
+
+module KeystoneUi
+  module Pages
+    module FormHelper
+      TOKEN_PLACEHOLDER = "keystone-ui-pages-form-token"
+
+      def pages_form(form_name:, fields:, submit_label:, thank_you:, element_id:, version:, after_submitting: nil, next_address: nil, problems: {}, values: {}, failure: nil)
+        content = safe_join([ (ui_alert(message: failure, type: :error) if failure) ].compact + fields.map { |field| form_field(field, problems, values) } + [ trap_field, turnstile_widget, ui_button(label: submit_label) ].compact)
+        return tag.div(content, class: "ks-form") unless version
+
+        content_tag("turbo-frame", ui_form(action: keystone_ui_pages.page_form_path(version.page.slug, version.number, element_id)) { token_placeholder + content }, id: form_frame_id(element_id), class: "print:hidden")
+      end
+
+      def redrawn_form(form, version, problems: {}, values: {}, failure: nil)
+        drawn = pages_form(**Submissions.drawing_settings(form), element_id: form["id"], version: version, problems: problems, values: values, failure: failure)
+        with_visitor_token(drawn.to_str).html_safe
+      end
+
+      def form_frame_id(element_id)
+        "keystone-ui-pages-form-#{element_id}"
+      end
+
+      def without_visitor_tokens(html)
+        html.gsub(/<input type="hidden" name="#{request_forgery_protection_token}" value="(?!#{TOKEN_PLACEHOLDER})[^"]*"[^>]*>/, "")
+      end
+
+      def with_visitor_token(html)
+        html.gsub(TOKEN_PLACEHOLDER) { protect_against_forgery? ? form_authenticity_token : "" }
+      end
+
+      private
+
+      def turnstile_widget
+        tag.div(class: "cf-turnstile", data: { sitekey: KeystoneUi::Pages.turnstile_site_key }) if KeystoneUi::Pages.turnstile_site_key.present?
+      end
+
+      def trap_field
+        tag.div(tag.input(type: "text", name: Submissions::TRAP_NAME, tabindex: -1, autocomplete: "off"), class: "absolute -left-[10000px] h-px w-px overflow-hidden", aria: { hidden: true })
+      end
+
+      def token_placeholder
+        tag.input(type: "hidden", name: request_forgery_protection_token, value: TOKEN_PLACEHOLDER, autocomplete: "off")
+      end
+
+      def form_field(field, problems, values)
+        name = field[:name].to_s
+        ui_form_field(attribute: name, label: field[:label], type: FormFieldKinds.find(field[:kind]).drawn_as, required: field[:required].to_s == "true",
+          errors: Array(problems[name]), value: values[name], options: FormFieldKinds.choices(field[:choices]).map { |choice| [ choice, choice ] })
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui/pages/host_helper.rb

@@ -10,7 +10,7 @@ module KeystoneUi
         version = version ? page.versions.find_by(number: version) : page.live_version
         return if version.nil?
 
-        tag.div(drawn_version(version, values: values), class: "@container")
+        tag.div(drawn_version(version, values: values), class: "@container", data: version == page.live_version ? reporting_data(page) : {})
       end
     end
   end

data/app/javascript/keystone_ui_pages/forms.js

@@ -0,0 +1,6 @@
+document.addEventListener("turbo:frame-missing", (event) => {
+  if (!event.target.id.startsWith("keystone-ui-pages-form-")) return
+
+  event.preventDefault()
+  event.detail.visit(event.detail.response)
+})

data/app/javascript/keystone_ui_pages/reporting.js

@@ -0,0 +1,24 @@
+function report(drawn, kind, details = {}) {
+  document.dispatchEvent(new CustomEvent(`keystone-ui-pages:${kind}`, { detail: { slug: drawn.dataset.pageSlug, place: drawn.dataset.pagePlace, ...details } }))
+  fetch(drawn.dataset.pageEvents, { method: "POST", body: new URLSearchParams({ kind, element: details.element ?? "" }), credentials: "same-origin", keepalive: true }).catch(() => {})
+}
+
+function reportViews() {
+  if (document.prerendering) return document.addEventListener("prerenderingchange", reportViews, { once: true })
+
+  document.querySelectorAll("[data-page-events]:not([data-page-viewed])").forEach((drawn) => {
+    drawn.dataset.pageViewed = ""
+    report(drawn, "view")
+  })
+}
+
+function reportClick(event) {
+  const clicked = event.target.closest("a, button")
+  const drawn = clicked?.closest("[data-page-events]")
+  const element = clicked?.closest("[data-page-element]")
+  if (drawn && element) report(drawn, "click", { element: element.dataset.pageElement, href: clicked.href ?? null })
+}
+
+document.addEventListener("DOMContentLoaded", reportViews)
+document.addEventListener("turbo:load", reportViews)
+document.addEventListener("click", reportClick)

data/app/models/keystone_ui/pages/page.rb

@@ -2,6 +2,7 @@
 
 require "securerandom"
 require "keystone_ui/pages/document"
+require "keystone_ui/pages/operations"
 
 module KeystoneUi
   module Pages
@@ -25,7 +26,8 @@ module KeystoneUi
 
       validates :name, :slug, presence: true
       validates :slug, uniqueness: { scope: %i[owner_type owner_id] }
-      validates :place, inclusion: { in: -> { KeystoneUi::Pages.places.keys } }, allow_nil: true, if: -> { KeystoneUi::Pages.places.any? }
+      validates :place, inclusion: { in: -> { KeystoneUi::Pages.places.keys } }, if: -> { KeystoneUi::Pages.places.any? }
+      validate :place_offers_its_elements, if: :will_save_change_to_place?
       validates :access_exception, inclusion: { in: -> { KeystoneUi::Pages.access_exceptions.keys } }, allow_nil: true, if: -> { KeystoneUi::Pages.access_exceptions.any? }
 
       def publish
@@ -84,6 +86,10 @@ module KeystoneUi
         versions.find_by(status: :live)
       end
 
+      def reporting?
+        live_version.present? && KeystoneUi::Pages.reported?(place)
+      end
+
       def next_number
         (versions.maximum(:number) || 0) + 1
       end
@@ -93,6 +99,16 @@ module KeystoneUi
         used = Page.where(owner: owner, place: place).pluck(:name).filter_map { |taken| taken[/\A#{Regexp.escape(word)} (\d+)\z/, 1]&.to_i }
         "#{word} #{(used.max || 0) + 1}"
       end
+
+      private
+
+      def place_offers_its_elements
+        offered = KeystoneUi::Pages.offered_catalog(place)
+        held = Operations.elements(document).map { |element| element["key"] }.uniq
+        held.reject { |key| offered.find(key) }.filter_map { |key| KeystoneUi::Pages.catalog.find(key) }.each do |element|
+          errors.add(:place, "#{KeystoneUi::Pages.places[place]} does not offer #{element.name}")
+        end
+      end
     end
   end
 end

data/app/views/keystone_ui/pages/pages/show.html.erb

@@ -1,4 +1,2 @@
 <% content_for(:title, @version.title) if @version.title %>
-<div data-live-page class="@container print:bg-white print:[print-color-adjust:exact]">
-  <%= drawn_version(@version, values: @values.to_h) %>
-</div>
+<%= tag.div drawn_version(@version, values: @values.to_h), data: { live_page: "", **(@page ? reporting_data(@page) : {}) }, class: "@container print:bg-white print:[print-color-adjust:exact]" %>

data/app/views/keystone_ui/pages/submissions/create.html.erb

@@ -0,0 +1 @@
+<%= content_tag "turbo-frame", ui_paragraph(text: @thank_you), id: form_frame_id(@element_id) %>

data/app/views/keystone_ui/pages/submissions/failed.html.erb

@@ -0,0 +1 @@
+<%= redrawn_form(form, version, values: values, failure: "Your form was not sent. Please try again.") %>

data/app/views/keystone_ui/pages/submissions/refused.html.erb

@@ -0,0 +1 @@
+<%= redrawn_form(form, version, problems: problems, values: values) %>

data/config/routes.rb

@@ -32,5 +32,7 @@ KeystoneUi::Pages::Engine.routes.draw do
     end
   end
 
+  post ":slug/events", to: "events#create", as: :page_events
+  post ":slug/versions/:number/forms/:element_id", to: "submissions#create", as: :page_form
   get ":slug", to: "pages#show", as: :page
 end

data/lib/keystone_ui/pages/catalog.rb

@@ -3,20 +3,24 @@
 module KeystoneUi
   module Pages
     class Catalog
-      Element = Data.define(:key, :name, :component, :fields, :body, :icon, :group, :align)
+      Element = Data.define(:key, :name, :component, :fields, :body, :icon, :group, :align, :placed)
 
       def initialize
         @elements = {}
       end
 
-      def register(key:, name:, component:, fields:, body: nil, icon: nil, group: nil, align: nil)
-        @elements[key.to_sym] = Element.new(key: key.to_sym, name: name, component: component, fields: fields, body: body, icon: icon, group: group, align: align)
+      def register(key:, name:, component:, fields:, body: nil, icon: nil, group: nil, align: nil, placed: false)
+        @elements[key.to_sym] = Element.new(key: key.to_sym, name: name, component: component, fields: fields, body: body, icon: icon, group: group, align: align, placed: placed)
       end
 
       def leave_out(*keys)
         keys.each { |key| @elements.delete(key.to_sym) }
       end
 
+      def without(*keys)
+        Catalog.new.tap { |copy| elements.each { |element| copy.add(element) unless keys.include?(element.key) } }
+      end
+
       def elements
         @elements.values
       end
@@ -24,6 +28,12 @@ module KeystoneUi
       def find(key)
         @elements[key.to_sym]
       end
+
+      protected
+
+      def add(element)
+        @elements[element.key] = element
+      end
     end
   end
 end

data/lib/keystone_ui/pages/engine.rb

@@ -14,6 +14,10 @@ module KeystoneUi
         ActiveSupport.on_load(:action_view) { include KeystoneUi::Pages::HostHelper }
       end
 
+      initializer "keystone_ui_pages.check_places", after: :load_config_initializers do |app|
+        app.config.after_initialize { KeystoneUi::Pages.check_places! }
+      end
+
       initializer "keystone_ui_pages.tailwind" do
         KeystoneUi.configuration.tailwind_sources << root.join("app/views/**/*.erb").to_s
         KeystoneUi.configuration.tailwind_sources << root.join("app/helpers/**/*.rb").to_s

data/lib/keystone_ui/pages/event.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  module Pages
+    Event = Data.define(:page, :place, :kind, :element, :request)
+  end
+end

data/lib/keystone_ui/pages/form_field_kinds.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module KeystoneUi
+  module Pages
+    module FormFieldKinds
+      Kind = Data.define(:drawn_as, :limit, :check, :delivered)
+
+      KINDS = {
+        "text" => Kind.new(drawn_as: :text, limit: 200, check: nil, delivered: nil),
+        "email" => Kind.new(drawn_as: :email, limit: 254, delivered: nil,
+          check: ->(value, _field) { "Enter an email address" unless value.match?(URI::MailTo::EMAIL_REGEXP) }),
+        "long_text" => Kind.new(drawn_as: :textarea, limit: 5000, check: nil, delivered: nil),
+        "choice" => Kind.new(drawn_as: :select, limit: 200, delivered: nil,
+          check: ->(value, field) { "Choose one of the options" unless FormFieldKinds.choices(field["choices"]).include?(value) }),
+        "checkbox" => Kind.new(drawn_as: :checkbox, limit: 1, check: nil, delivered: ->(value) { value.to_s == "1" })
+      }.freeze
+
+      module_function
+
+      def keys
+        KINDS.keys
+      end
+
+      def find(key)
+        KINDS.fetch(key.to_s.presence || "text", KINDS["text"])
+      end
+
+      def choices(text)
+        text.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/keystone_ui/pages/keystone_elements.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "keystone_ui/pages/form_field_kinds"
+
 module KeystoneUi
   module Pages
     module KeystoneElements
@@ -71,6 +73,19 @@ module KeystoneUi
                       default: [ { "title" => "Fast", "description" => "Pages load quickly." },
                                  { "title" => "Clear", "description" => "Every page reads plainly." },
                                  { "title" => "Yours", "description" => "Built from your own components." } ] } ])
+        catalog.register(key: :form, name: "Form", component: :pages_form, icon: :card, group: "Content", placed: true,
+          fields: [ { key: :form_name, label: "Form name", kind: :text, default: "Contact" },
+                    { key: :fields, label: "Fields", kind: :list,
+                      entry: [ { key: :label, label: "Label", kind: :text }, { key: :name, label: "Field name", kind: :text },
+                               { key: :kind, label: "Kind", kind: :one_of, options: FormFieldKinds.keys, default: "text" },
+                               { key: :choices, label: "Choices, separated by commas", kind: :text },
+                               { key: :required, label: "Required", kind: :yes_or_no } ],
+                      default: [ { "label" => "Name", "name" => "name", "kind" => "text" },
+                                 { "label" => "Email", "name" => "email", "kind" => "email", "required" => "true" } ] },
+                    { key: :submit_label, label: "Submit label", kind: :text, default: "Send" },
+                    { key: :thank_you, label: "Thank-you message", kind: :long_text, default: "Thanks, we will be in touch." },
+                    { key: :after_submitting, label: "After submitting", kind: :one_of, options: %w[thank_you address], default: "thank_you" },
+                    { key: :next_address, label: "Address to send the visitor to", kind: :address } ])
         catalog.register(key: :accordion, name: "Accordion", component: :ui_accordion, icon: :code, group: "Text",
           fields: [ { key: :items, label: "Questions", kind: :list,
                       entry: [ { key: :question, label: "Question", kind: :text }, { key: :answer, label: "Answer", kind: :long_text } ],

data/lib/keystone_ui/pages/submission.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  module Pages
+    Submission = Data.define(:page, :version, :form_name, :element_id, :values, :request, :bot)
+  end
+end

data/lib/keystone_ui/pages/submissions.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "keystone_ui/pages/form_field_kinds"
+
+module KeystoneUi
+  module Pages
+    module Submissions
+      TRAP_NAME = "keystone_ui_pages_trap"
+
+      module_function
+
+      def bot?(submitted)
+        submitted[TRAP_NAME].present?
+      end
+
+      def form_name(form, catalog: Pages.catalog)
+        setting(form, :form_name, catalog)
+      end
+
+      def thank_you(form, catalog: Pages.catalog)
+        setting(form, :thank_you, catalog)
+      end
+
+      def drawing_settings(form, catalog: Pages.catalog)
+        fields = Array(setting(form, :fields, catalog)).map { |field| { kind: "text" }.merge(field.to_h.symbolize_keys.compact_blank) }
+        { form_name: form_name(form, catalog: catalog), fields: fields, submit_label: setting(form, :submit_label, catalog), thank_you: thank_you(form, catalog: catalog) }
+      end
+
+      def next_address(form, catalog: Pages.catalog)
+        setting(form, :next_address, catalog).presence if setting(form, :after_submitting, catalog) == "address"
+      end
+
+      def accepted(form, submitted, catalog: Pages.catalog)
+        names = Array(setting(form, :fields, catalog)).map { |field| field["name"].to_s }
+        submitted.to_unsafe_h.slice(*names)
+      end
+
+      def delivered(form, values, catalog: Pages.catalog)
+        converted = Array(setting(form, :fields, catalog)).filter_map do |field|
+          kind = FormFieldKinds.find(field["kind"])
+          [ field["name"].to_s, kind.delivered.call(values[field["name"].to_s]) ] if kind.delivered
+        end
+        values.merge(converted.to_h)
+      end
+
+      def problems(form, values, catalog: Pages.catalog)
+        Array(setting(form, :fields, catalog)).each_with_object({}) do |field, found|
+          message = problem(field, values[field["name"].to_s].to_s)
+          found[field["name"].to_s] = message if message
+        end
+      end
+
+      private_class_method def problem(field, value)
+        kind = FormFieldKinds.find(field["kind"])
+        return "Keep this to #{kind.limit} characters or fewer" if value.length > kind.limit
+        return "Fill this in" if field["required"].to_s == "true" && value.blank?
+
+        kind.check&.call(value, field) if value.present?
+      end
+
+      private_class_method def setting(form, key, catalog)
+        form["fields"].fetch(key.to_s) { catalog.find(:form).fields.find { |field| field[:key] == key }[:default] }
+      end
+    end
+  end
+end

data/lib/keystone_ui/pages/turnstile.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+
+module KeystoneUi
+  module Pages
+    module Turnstile
+      VERIFY_ADDRESS = URI("https://challenges.cloudflare.com/turnstile/v0/siteverify")
+
+      module_function
+
+      def on?
+        Pages.turnstile_site_key.present? && Pages.turnstile_secret_key.present?
+      end
+
+      def confirmed?(token, remote_ip)
+        answer = Net::HTTP.post_form(VERIFY_ADDRESS, secret: Pages.turnstile_secret_key, response: token.to_s, remoteip: remote_ip.to_s)
+        JSON.parse(answer.body)["success"] == true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/keystone_ui/pages/version.rb

@@ -2,6 +2,6 @@
 
 module KeystoneUi
   module Pages
-    VERSION = "0.8.0"
+    VERSION = "0.9.0"
   end
 end

data/lib/keystone_ui/pages.rb

@@ -10,7 +10,8 @@ module KeystoneUi
   module Pages
     class << self
       attr_writer :base_controller, :layout, :editor_layout, :pdf_stylesheet, :access_exceptions
-      attr_accessor :edit_check_method, :view_check_method, :values_method, :owner_method, :refusal_method, :chrome_path
+      attr_accessor :edit_check_method, :view_check_method, :values_method, :owner_method, :refusal_method, :chrome_path,
+                    :turnstile_site_key, :turnstile_secret_key
 
       def base_controller
         @base_controller || "ActionController::Base"
@@ -37,8 +38,8 @@ module KeystoneUi
         @place_settings = {}
       end
 
-      def register_place(key, label:, default_name: "Page", slug: true)
-        place_settings[key.to_s] = { label: label, default_name: default_name, slug: slug }
+      def register_place(key, label:, default_name: "Page", slug: true, events: nil, submissions: nil, leaves_out: [])
+        place_settings[key.to_s] = { label: label, default_name: default_name, slug: slug, events: events, submissions: submissions, leaves_out: leaves_out.map(&:to_sym) }
       end
 
       def place_settings
@@ -49,6 +50,30 @@ module KeystoneUi
         place_settings.dig(place.to_s, :slug) != false
       end
 
+      def check_places!
+        place_settings.each do |place, settings|
+          unknown = settings[:leaves_out].reject { |key| catalog.find(key) }
+          raise ArgumentError, "The place #{place} leaves out #{unknown.join(", ")}, which no catalog element has" if unknown.any?
+          raise ArgumentError, "The place #{place} offers the Form element but has no submissions handler" if offered_catalog(place).find(:form) && !settings[:submissions]
+        end
+      end
+
+      def offered_catalog(place)
+        catalog.without(*Array(place_settings.dig(place.to_s, :leaves_out)))
+      end
+
+      def offered_elements(place)
+        offered_catalog(place).elements
+      end
+
+      def submission_handler(place)
+        place_settings.dig(place.to_s, :submissions)
+      end
+
+      def reported?(place)
+        !place_settings.dig(place.to_s, :events).nil?
+      end
+
       def access_exceptions
         @access_exceptions || {}
       end

data/the_local/agents/keystone_ui-pages-develop.md

@@ -48,8 +48,8 @@ inherit from the base controller, so define it there.
   at `/pages/:slug`. Unset, every published page is shown.
 - `KeystoneUi::Pages.places = { "marketing" => "Marketing site" }` — a hash of
   the places a page can belong to, each stored value to the label editors see.
-  When it is not empty, the New page form offers them, a page with a place not
-  in it is refused, and the page list shows each page's place. The view check
+  When it is not empty, the New page form offers them with no blank choice, a
+  page with no place or a place not in it is refused, and the page list shows each page's place. The view check
   reads it as `page.place`. Unset, pages have no place.
 - `KeystoneUi::Pages.register_place("client_report", label: "Client report", default_name: "Report template", slug: false)`
   — adds one place with its own settings, so each part of a host app registers
@@ -58,8 +58,78 @@ inherit from the base controller, so define it there.
   starts with, followed by the next number among that owner's pages in that
   place, so "Report template 1", then "Report template 2"; it defaults to
   "Page". `slug:` says whether the place's pages have a URL slug; it defaults to
-  true. Registered places are offered alongside any set with `places =`, and
+  true. A page in a place registered with `slug: false` is never served at
+  `/pages/:slug`, whatever the view check says. `events:` takes a handler the
+  gem calls for each accepted view of the place's live pages; a place with no
+  handler reports nothing. `submissions:` takes a handler the gem calls with a
+  `KeystoneUi::Pages::Submission` for each accepted form submission from the
+  place's pages; a place with no handler refuses every submission as not found.
+  `leaves_out:` takes catalog keys the place does not offer, such as
+  `[ :form ]`; every other catalog element is offered there, including ones
+  registered later. The builder's element list and adding an element use only
+  what the place offers, and moving a page to a place that leaves out an
+  element it holds is refused on its settings page. A key no catalog element
+  has raises an `ArgumentError` when the app boots, checked after every
+  initializer and `after_initialize` block has run, and so does a registered
+  place that offers the Form element without a `submissions:` handler.
+  Registered places are offered alongside any set with `places =`, and
   `places = nil` clears both.
+- **Form submissions handed to the host**: `POST /pages/:slug/versions/:number/forms/:element_id`
+  finds the form in that version, live or older, and calls the place's
+  `submissions:` handler with a `Submission` holding `page`, `version`,
+  `form_name`, `element_id`, `values` (only the field names that version's form
+  lists, with each checkbox as `true` or `false`), `request` and `bot`. Every
+  form carries a trap field people cannot see, reach by keyboard, hear or have
+  autofilled; a submission that fills it arrives with `bot: true`, and the
+  visitor still gets the normal answer, so the handler decides what to drop.
+  A handler that raises is reported through `Rails.error` with `page_id` and
+  `form_name`, and the visitor gets the form back in place, with their values,
+  under a message saying it was not sent, never the thank-you or the address.
+- `KeystoneUi::Pages.turnstile_site_key = "..."` — the Cloudflare Turnstile
+  site key. With it set, every form shows Cloudflare's widget and a page holding
+  a form loads `https://challenges.cloudflare.com/turnstile/v0/api.js` through
+  `content_for :head`, so the host's content security policy must allow it.
+  Unset, nothing is loaded from Cloudflare.
+- `KeystoneUi::Pages.turnstile_secret_key = "..."` — the Cloudflare Turnstile
+  secret key. With both keys set, each submission's token is confirmed with
+  Cloudflare, and one it does not confirm arrives with `bot: true` while the
+  visitor gets the normal answer. Unset, no submission is sent to Cloudflare. It keeps the host's forgery protection, refuses a
+  visitor the view check refuses the way the page is refused, and answers 404
+  when the form is not in the version or the place has no handler. A required
+  field left empty, an email field holding no email address, or a choice
+  that is not one of the field's choices, or a value longer than its kind
+  allows (text and choice 200 characters, email 254, long text 5000, checkbox
+  1), is refused with
+  422 and the form drawn again in its frame with an error under each failed
+  field and the visitor's values, never reaching the handler. It otherwise answers
+  with the form's thank-you message in a `turbo-frame` named after the form,
+  inside the host's page layout, so a page running Turbo swaps only the form.
+  A form set to `address` answers a successful submission with a 303 redirect
+  there, after the handler runs. A page whose drawing holds a form adds the
+  forms script to `content_for :head`, which turns that redirect into a whole
+  page visit on a page running Turbo; refusals still answer in place.
+  The gem stores nothing.
+- **Views and clicks handed to the host**: a page opened at `/pages/:slug` whose place has
+  a handler loads the reporting script, which sends its view once it loads and
+  a click on any link or button with the id of the element it sits in. Each
+  element on a live drawing carries its id as `data-page-element`. The script
+  also fires `keystone-ui-pages:view` (`detail`: `slug`, `place`) and
+  `keystone-ui-pages:click` (`detail`: `slug`, `place`, `element`, `href`) on
+  `document`, whatever the event address answers, for a tag in the host layout.
+  View live and PDFs send nothing. `POST /pages/:slug/events` calls the page's
+  place's `events:` handler with a `KeystoneUi::Pages::Event` holding `page`,
+  `place`, `kind` (`"view"` or `"click"`), `element` (the element id for a
+  click, nil for a view) and `request`. The gem stores nothing;
+  what is kept, counted or shown is the host's to decide. The handler runs inside
+  the event request, so slow work belongs in a job it enqueues. A handler that
+  raises is reported through `Rails.error` with `page_id` and `kind`, and the
+  browser still gets 204. An event whose `kind` is given and is not `view` or
+  `click` is refused, and so is a click whose `element` is missing or not on the
+  live version; a request with no `kind` is a view. A prerendered page sends its
+  view when it is opened. It needs no form
+  token. It is refused the way the public page refuses a page when the page has
+  no live version, is another owner's, fails the view check, or its place has
+  no handler.
 - `KeystoneUi::Pages.access_exceptions = { "public_preview" => "Public preview" }`
   — a hash of the exceptions an editor can set on a page, each stored value to
   its label. When it is not empty, the builder's top bar has an Access exception
@@ -124,6 +194,10 @@ inherit from the base controller, so define it there.
   in every host view, that draws the page's live version with the values given,
   inside a `<div class="@container">`. It returns nil when no version is live.
   `values:` takes value names to values, with string or symbol keys.
+  When it draws the live version of a page whose place has an `events:`
+  handler, it adds the reporting script to `content_for :head` and the page's
+  view is sent from the browser once it loads, so the host layout must call
+  `yield :head`. An older version drawn by number sends nothing.
   `version:` takes a published version's number and draws that version
   instead, whether it is live or superseded and whether the page is
   unpublished or archived. It returns nil when the page has no version with
@@ -155,7 +229,7 @@ inherit from the base controller, so define it there.
 
 ### The element catalog
 
-- `KeystoneUi::Pages.catalog.register(key:, name:, component:, fields:, body: nil, icon: nil, group: nil, align: nil)`
+- `KeystoneUi::Pages.catalog.register(key:, name:, component:, fields:, body: nil, icon: nil, group: nil, align: nil, placed: false)`
   — adds an element to the builder's palette, or replaces the one with the same
   key. `key:` is a symbol stored in page documents. `name:` is the label in the
   palette. `component:` is the name of a method the drawing calls with one
@@ -166,6 +240,18 @@ inherit from the base controller, so define it there.
   `:number` `:progress`, and any other value shows a box. `group:` is the
   palette heading it sits under, `"Other"` when unset. `align:` is the default
   placement in its column: `"stretch"`, `"start"`, `"center"` or `"end"`.
+  `placed: true` also passes `element_id:` and `version:` (nil in the builder)
+  to the method, which the Form element uses to build its address.
+- The built-in Form element (`:form`) holds a form name, a list of fields (each
+  a label, a field name, a kind of `text`, `email`, `long_text`, `choice` or
+  `checkbox`, the choices of a `choice` field separated by commas, and whether
+  it is required), a submit label, a thank-you message, and what happens after a
+  successful submission: `thank_you` (the default) or `address`, which sends the
+  visitor to the address the editor sets. A published form
+  posts to `POST /pages/:slug/versions/:number/forms/:element_id`. Its drawing
+  is cached with a placeholder token, and each request puts in the visitor's
+  own forgery token, so the host's forgery protection stays on. A published form
+  is hidden in print, so no PDF and no page printed from the browser shows it.
 - `KeystoneUi::Pages.catalog.leave_out(:copy_button)` — removes elements from
   the palette by key. Takes several keys.
 

data/the_local/interface.yml

@@ -19,6 +19,8 @@ develop:
   - KeystoneUi::Pages.editor_layout
   - KeystoneUi::Pages.chrome_path
   - KeystoneUi::Pages.pdf_stylesheet
+  - KeystoneUi::Pages.turnstile_site_key
+  - KeystoneUi::Pages.turnstile_secret_key
   - KeystoneUi::Pages::Values.names
   - KeystoneUi::Pages::Values.chooser
   - KeystoneUi::Pages::Values.provider

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui-pages
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -75,8 +75,11 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - app/assets/builds/keystone_ui_pages/editor.js
+- app/assets/builds/keystone_ui_pages/forms.js
+- app/assets/builds/keystone_ui_pages/reporting.js
 - app/controllers/concerns/keystone_ui/pages/edits_pages.rb
 - app/controllers/concerns/keystone_ui/pages/host_checks.rb
+- app/controllers/keystone_ui/pages/events_controller.rb
 - app/controllers/keystone_ui/pages/manage/access_exceptions_controller.rb
 - app/controllers/keystone_ui/pages/manage/base_controller.rb
 - app/controllers/keystone_ui/pages/manage/columns_controller.rb
@@ -93,8 +96,10 @@ files:
 - app/controllers/keystone_ui/pages/manage/titles_controller.rb
 - app/controllers/keystone_ui/pages/manage/versions_controller.rb
 - app/controllers/keystone_ui/pages/pages_controller.rb
+- app/controllers/keystone_ui/pages/submissions_controller.rb
 - app/helpers/keystone_ui/pages/drawing_helper.rb
 - app/helpers/keystone_ui/pages/editor_helper.rb
+- app/helpers/keystone_ui/pages/form_helper.rb
 - app/helpers/keystone_ui/pages/host_helper.rb
 - app/javascript/keystone_ui_pages/AccessExceptionChoice.jsx
 - app/javascript/keystone_ui_pages/DeviceWidth.jsx
@@ -113,7 +118,9 @@ files:
 - app/javascript/keystone_ui_pages/ThemeMode.jsx
 - app/javascript/keystone_ui_pages/document.js
 - app/javascript/keystone_ui_pages/editor.jsx
+- app/javascript/keystone_ui_pages/forms.js
 - app/javascript/keystone_ui_pages/operations.js
+- app/javascript/keystone_ui_pages/reporting.js
 - app/jobs/keystone_ui/pages/pdf_job.rb
 - app/models/keystone_ui/pages/page.rb
 - app/models/keystone_ui/pages/pdf.rb
@@ -126,6 +133,9 @@ files:
 - app/views/keystone_ui/pages/manage/versions/show.html.erb
 - app/views/keystone_ui/pages/pages/show.html.erb
 - app/views/keystone_ui/pages/pdfs/show.html.erb
+- app/views/keystone_ui/pages/submissions/create.html.erb
+- app/views/keystone_ui/pages/submissions/failed.html.erb
+- app/views/keystone_ui/pages/submissions/refused.html.erb
 - config/routes.rb
 - db/migrate/20261014120000_create_keystone_ui_pages_pages.rb
 - db/migrate/20261014120001_create_keystone_ui_pages_versions.rb
@@ -138,11 +148,16 @@ files:
 - lib/keystone_ui/pages/catalog.rb
 - lib/keystone_ui/pages/document.rb
 - lib/keystone_ui/pages/engine.rb
+- lib/keystone_ui/pages/event.rb
+- lib/keystone_ui/pages/form_field_kinds.rb
 - lib/keystone_ui/pages/keystone_elements.rb
 - lib/keystone_ui/pages/operations.rb
 - lib/keystone_ui/pages/pdf_document.rb
 - lib/keystone_ui/pages/pdfs.rb
 - lib/keystone_ui/pages/printer.rb
+- lib/keystone_ui/pages/submission.rb
+- lib/keystone_ui/pages/submissions.rb
+- lib/keystone_ui/pages/turnstile.rb
 - lib/keystone_ui/pages/values.rb
 - lib/keystone_ui/pages/version.rb
 - the_local/agents/keystone_ui-pages-develop.md