clickwrap 0.0.0 → 0.1.0

data/app/views/clickwrap/shared/_statement.html.erb

@@ -0,0 +1,105 @@
+<%#
+  ONE CONTROL: one checkbox or one choice group, one label carrying the exact
+  words the server offered, the documents it is about, and its own error.
+
+  It renders two things, the same way. A single statement — an optional consent,
+  a recorded yes/no, an assertion the application worded itself, anything a
+  policy's composed line could not honestly absorb — and the composed line
+  itself, which is one control standing for several statements at once. Both
+  answer the same questions about a control (name, id, required, choices, error)
+  and this file asks nothing else of them.
+
+  Rules this file exists to keep:
+
+    * a control means exactly what the server signed it means. The composed line
+      is one box for several statements ONLY because the manifest says which
+      ones and the server answers all of them from it; two boxes answering one
+      statement each is the shape nothing can reconstruct later;
+    * the control is REAL and starts EMPTY. There is no `checked` anywhere in
+      this file and there never will be: a pre-ticked box records the page's
+      default rather than a person's action;
+    * the label contains the words and is tied to the control, so pressing them
+      works and assistive technology announces them together;
+    * document links come BEFORE the action and carry the document's own name
+      (not "click here");
+    * `required` is progressive enhancement only. THE SERVER DECIDES. A browser
+      that ignores it, a client that never sends the field, and a script that
+      posts by hand all meet the same server-side check at capture — which is
+      also why nothing here prints the word "Required" beside a control.
+
+  Locals: statement, error
+%>
+<%
+  error = local_assigns[:error].presence
+  described_by = error ? statement.error_id : nil
+  statement_classes = ["clickwrap-statement", "clickwrap-statement--#{statement.kind}"]
+  statement_classes << "clickwrap-statement--invalid" if error
+%>
+<div class="<%= statement_classes.join(" ") %>">
+  <% if statement.choices.present? %>
+    <%# An explicit yes/no decision: every option unselected, so the answer is
+        one the person actually made rather than one the page made for them. %>
+    <%
+      fieldset_options = { class: "clickwrap-statement__choices" }
+      fieldset_options[:"aria-invalid"] = "true" if error
+      fieldset_options[:"aria-describedby"] = described_by if described_by
+    %>
+    <%= tag.fieldset(**fieldset_options) do %>
+      <legend class="clickwrap-statement__legend"><%= statement.assertion %></legend>
+
+      <% statement.choices.each_key do |choice| %>
+        <%
+          choice_id = "#{statement.control_id}_#{choice}"
+          choice_options = { id: choice_id, class: "clickwrap-statement__radio" }
+          choice_options[:required] = true if statement.requires_an_explicit_choice?
+          choice_options[:"aria-describedby"] = described_by if described_by
+        %>
+        <span class="clickwrap-statement__choice">
+          <%= radio_button_tag statement.control_name, choice, false, choice_options %>
+          <%= label_tag choice_id,
+                t("clickwrap.choices.#{choice}", default: choice.to_s.humanize),
+                class: "clickwrap-statement__choice-label" %>
+        </span>
+      <% end %>
+    <% end %>
+  <% else %>
+    <%
+      control_options = { id: statement.control_id, class: "clickwrap-statement__checkbox" }
+      control_options[:required] = true if statement.required?
+      control_options[:"aria-invalid"] = "true" if error
+      control_options[:"aria-describedby"] = described_by if described_by
+    %>
+    <div class="clickwrap-statement__control">
+      <%= check_box_tag statement.control_name, "1", false, control_options %>
+      <%= label_tag statement.control_id, clickwrap_statement_label(statement),
+            class: "clickwrap-statement__label" %>
+    </div>
+  <% end %>
+
+  <%# Only for a statement standing on its own. The composed line's links are
+      inside its sentence, so it has none to list here. %>
+  <% if statement.documents.any? %>
+    <ul class="clickwrap-documents">
+      <% statement.documents.each do |document| %>
+        <li class="clickwrap-documents__item"><%= clickwrap_document_link(document) %></li>
+      <% end %>
+    </ul>
+  <% end %>
+
+  <% if error %>
+    <%# Announced through aria-describedby above, and readable as ordinary text
+        here: the meaning is in the words, not in the color they are printed in. %>
+    <p class="clickwrap-statement__error" id="<%= statement.error_id %>">
+      <span class="clickwrap-statement__error-prefix"><%= t("clickwrap.ui.error_prefix") %></span>
+      <%= Array(error).join(" ") %>
+    </p>
+  <% end %>
+
+  <% if statement.withdrawal_path.present? %>
+    <p class="clickwrap-statement__withdrawal">
+      <%= link_to t("clickwrap.ui.withdrawal_link", purpose: statement.purpose_key.humanize.downcase),
+            statement.withdrawal_path,
+            class: "clickwrap-statement__withdrawal-link" %>
+    </p>
+  <% end %>
+</div>

data/app/views/clickwrap/withdrawals/new.html.erb

@@ -0,0 +1,30 @@
+<%#
+  Withdrawing one consent purpose: one sentence, one button.
+
+  Nothing is added to this page. Withdrawal must be no harder than granting was,
+  and every extra step here would be a step someone did not have to take to say
+  yes.
+%>
+<%= clickwrap_styles %>
+
+<div class="clickwrap clickwrap-screen">
+  <header class="clickwrap-screen__header">
+    <h1 class="clickwrap-screen__title">
+      <%= t("clickwrap.withdrawals.title", purpose: @purpose_key.humanize.downcase) %>
+    </h1>
+    <p class="clickwrap-screen__intro"><%= t("clickwrap.withdrawals.explanation") %></p>
+  </header>
+
+  <% if flash.now[:alert].present? || flash[:alert].present? %>
+    <p class="clickwrap-flash clickwrap-flash--alert" role="alert"><%= flash[:alert] %></p>
+  <% end %>
+
+  <%= form_with url: clickwrap_routes.withdrawal_path(@purpose_key),
+        method: :post,
+        class: "clickwrap-screen__form" do %>
+    <%= hidden_field_tag :return_to, @return_to, id: nil %>
+    <%= submit_tag t("clickwrap.withdrawals.confirm_button"), class: "clickwrap-submit" %>
+  <% end %>
+
+  <p class="clickwrap-note"><%= t("clickwrap.withdrawals.what_this_does") %></p>
+</div>

data/config/locales/en.yml

@@ -0,0 +1,160 @@
+# The gem's own English strings.
+#
+# Two things to know before changing anything in here:
+#
+#   1. Wording is product design, and some of these sentences carry meaning the
+#      rest of the gem depends on. A person AGREES TO Terms and ACKNOWLEDGES a
+#      Privacy Notice — a privacy notice is information someone is entitled to,
+#      not a bargain they strike, and "I agree to the privacy policy" quietly
+#      turns one into the other. Keep the verbs matched to the kinds.
+#   2. Nothing here may claim, or read as claiming, that anything is compliant,
+#      enforceable, legally binding, court-proof, or that a person read or
+#      understood a document. These strings appear on screens and in receipts,
+#      which is exactly where an overclaim would do damage.
+#
+# Hosts override any of this by defining the same key in their own locale files
+# (the application's translations load last and win), and a policy can name its
+# own key or literal text instead.
+en:
+  clickwrap:
+    # Conventional first-person assertions. `agree_to :terms` with no
+    # `statement:` resolves to clickwrap.statements.agreement.terms; a policy
+    # that says something more specific passes its own text or key.
+    statements:
+      agreement:
+        terms: "I agree to the Terms."
+      acknowledgment:
+        privacy_notice: "I acknowledge the Privacy Notice."
+
+    # The composed one-line offer. When every statement in a policy is an
+    # ordinary, required, default-worded agreement or acknowledgment, they
+    # render as ONE control carrying ONE sentence, with the documents linked
+    # inside it:
+    #
+    #   I agree to the Terms of Service and I acknowledge the Privacy Policy.
+    #
+    # One fragment per kind, and the verbs stay matched to the kinds for the
+    # reason at the top of this file. `%{documents}` is where the links go;
+    # a fragment without it composes nothing and the statements render on
+    # lines of their own, which is also what happens in any locale that has
+    # not translated these four keys.
+    sentence:
+      agreement: "I agree to the %{documents}"
+      acknowledgment: "I acknowledge the %{documents}"
+      # Between two documents on ONE statement ("the Terms and the Schedules"),
+      # between two fragments, and at the end of the whole line.
+      documents_joiner: " and the "
+      joiner: " and "
+      terminator: "."
+
+    ui:
+      error_summary_heading: "Check these before continuing"
+      error_prefix: "Error:"
+      # Announced, never drawn. A sighted person can see the icon their browser
+      # gives a new tab; a screen-reader user cannot, and neither of them needs
+      # the words printed beside every link. Rendered only when the link really
+      # does open a new tab, because a same-window link claiming otherwise would
+      # be the page lying about itself.
+      opens_in_new_tab: "(opens in a new tab)"
+      # Receipts only. A version label beside a checkbox is a fact nobody can
+      # act on; a version label on the record is the whole point of the record.
+      document_version: "Version %{version}"
+      withdrawal_link: "Withdraw %{purpose} at any time"
+
+    # Labels for an explicit yes/no consent choice. Quoted because unquoted
+    # `yes:` and `no:` are booleans in YAML, not the words.
+    choices:
+      "yes": "Yes"
+      "no": "No"
+      grant: "Yes"
+      decline: "No"
+
+    errors:
+      required_statement: "You need to answer this before continuing."
+      answer_not_accepted: "This answer was not accepted. Please check it and try again."
+      presentation_no_longer_valid: "This page expired before it was submitted, so it has been
+        offered again. Please check your answers and submit once more."
+      temporarily_unavailable: "This could not be recorded because the database was temporarily
+        busy. Nothing was accepted. Please check your answers and try again."
+
+    captures:
+      title: "Before you continue"
+      intro: "Please look over the documents below and make your choices. Nothing is selected for
+        you."
+      submit_button_text: "Continue"
+      recorded: "Thank you — that has been recorded."
+
+    withdrawals:
+      title: "Withdraw %{purpose}"
+      explanation: "You can withdraw this at any time, and it takes one press — the same as giving
+        it did."
+      confirm_button: "Withdraw"
+      confirmed: "That purpose has been withdrawn."
+      already_withdrawn: "That purpose was already withdrawn."
+      recorded_reason: "The person withdrew this purpose from the consent withdrawal screen."
+      what_this_does: "Withdrawing records that you have withdrawn this purpose from now on. It
+        adds a new record rather than deleting the earlier one, so the history stays accurate."
+
+    receipts:
+      index_title: "Your records"
+      show_title: "Record"
+      empty: "There is nothing here yet."
+      policy: "Policy"
+      event_id: "Record ID"
+      event_type: "What happened"
+      recorded_at_by_server: "Recorded by the server at"
+      submit_button_text: "Call to action in the server offer"
+      combined_sentence: "Sentence the server offered, in one control"
+      acts: "Recorded statements and answers"
+      documents: "Document versions bound to this record"
+      offered_and_not_taken: "offered, not taken"
+      canonical_json: "Download the canonical JSON"
+      what_this_records: "This record shows the exact wording and document versions this application
+        generated as an offer, and what was submitted back. It does not show that anyone read or
+        understood the documents, and it is not a legal opinion about them."
+
+    # The six kinds, for display. This taxonomy is product design; naming an act
+    # an agreement or a consent does not decide its legal effect.
+    kinds:
+      agreement: "Agreement"
+      acknowledgment: "Acknowledgment"
+      consent: "Consent"
+      declaration: "Declaration"
+      attestation: "Attestation"
+      authorization: "Authorization"
+
+    actions:
+      agreed: "Agreed"
+      acknowledged: "Acknowledged"
+      granted: "Granted"
+      declined: "Declined"
+      declared: "Declared"
+      attested: "Attested"
+      authorized: "Authorized"
+      withdrawn: "Withdrawn"
+      renewed: "Renewed"
+      scope_changed: "Scope changed"
+      superseded: "Superseded"
+      expired: "Expired"
+      consumed: "Used"
+      revoked: "Revoked"
+      corrected: "Corrected"
+
+    event_types:
+      capture: "Submitted"
+      withdrawal: "Withdrawn"
+      correction: "Corrected"
+      supersession: "Superseded"
+      expiry: "Expired"
+      consumption: "Used"
+      revocation: "Revoked"
+      renewal: "Renewed"
+      scope_change: "Scope changed"
+      exemption: "Recorded exemption — no human action"
+      imported_legacy: "Imported from earlier records"
+      external_receipt: "Recorded by another provider"
+      disposition: "Disposed of under a retention rule"
+      legal_hold_placed: "Placed on hold"
+      legal_hold_released: "Hold released"
+      receipt_access: "Record accessed"
+      provider_outcome: "Provider outcome recorded"

data/config/locales/es.yml

@@ -0,0 +1,138 @@
+# The gem's own Spanish strings.
+#
+# The same two rules as en.yml, which is the reference file:
+#
+#   1. Verbs stay matched to the kinds. A person AGREES TO Terms ("acepto") and
+#      ACKNOWLEDGES a Privacy Notice ("doy por recibida") — a privacy notice is
+#      information someone is entitled to, not a bargain they strike, and
+#      "acepto la política de privacidad" quietly turns one into the other
+#      (this is the AEPD's own distinction; see the request-evidence guide).
+#   2. Nothing here may claim, or read as claiming, that anything is compliant,
+#      enforceable, legally binding, or that a person read or understood a
+#      document. "He leído..." is deliberately absent.
+#
+# Grammatical gender: forms address the person directly ("tú") and avoid
+# gendered self-descriptions ("informado/a"), so every string works for
+# everyone without slashed suffixes.
+es:
+  clickwrap:
+    statements:
+      agreement:
+        terms: "Acepto los Términos."
+      acknowledgment:
+        privacy_notice: "Doy por recibida la Política de Privacidad."
+
+    # La frase de una sola línea. En español el artículo concuerda con el
+    # documento ("los Términos", "la Política"), y solo la aplicación sabe qué
+    # documento nombra, así que el artículo vive en la etiqueta del enlace y no
+    # en estas plantillas — por eso `documents_joiner` es " y " y no " y el ".
+    sentence:
+      agreement: "Acepto %{documents}"
+      acknowledgment: "He recibido %{documents}"
+      documents_joiner: " y "
+      joiner: " y "
+      terminator: "."
+
+    ui:
+      error_summary_heading: "Revisa esto antes de continuar"
+      error_prefix: "Error:"
+      opens_in_new_tab: "(se abre en una pestaña nueva)"
+      document_version: "Versión %{version}"
+      withdrawal_link: "Retira %{purpose} cuando quieras"
+
+    choices:
+      "yes": "Sí"
+      "no": "No"
+      grant: "Sí"
+      decline: "No"
+
+    errors:
+      required_statement: "Debes responder esto antes de continuar."
+      answer_not_accepted: "Esta respuesta no se ha aceptado. Revísala e inténtalo de nuevo."
+      presentation_no_longer_valid: "Esta página caducó antes de enviarse, así que se ha vuelto
+        a mostrar. Revisa tus respuestas y envíala otra vez."
+      temporarily_unavailable: "No se ha podido registrar porque la base de datos estaba
+        temporalmente ocupada. No se ha aceptado nada. Revisa tus respuestas e inténtalo de nuevo."
+
+    captures:
+      title: "Antes de continuar"
+      intro: "Revisa los documentos siguientes y marca tus respuestas. No hay nada seleccionado
+        de antemano."
+      submit_button_text: "Continuar"
+      recorded: "Gracias — ha quedado registrado."
+
+    withdrawals:
+      title: "Retirar %{purpose}"
+      explanation: "Puedes retirarlo cuando quieras, y cuesta una sola pulsación — igual que
+        costó darlo."
+      confirm_button: "Retirar"
+      confirmed: "Ese permiso ha quedado retirado."
+      already_withdrawn: "Ese permiso ya estaba retirado."
+      recorded_reason: "La persona retiró este permiso desde la pantalla de retirada de
+        consentimiento."
+      what_this_does: "Retirarlo registra que a partir de ahora has retirado este permiso. Se
+        añade un registro nuevo en lugar de borrar el anterior, así el historial sigue siendo
+        exacto."
+
+    receipts:
+      index_title: "Tus registros"
+      show_title: "Registro"
+      empty: "Aquí no hay nada todavía."
+      policy: "Política"
+      event_id: "ID del registro"
+      event_type: "Qué ocurrió"
+      recorded_at_by_server: "Registrado por el servidor el"
+      submit_button_text: "Botón de acción de la oferta del servidor"
+      combined_sentence: "Frase que ofreció el servidor, en una sola casilla"
+      acts: "Declaraciones y respuestas registradas"
+      documents: "Versiones de documentos vinculadas a este registro"
+      offered_and_not_taken: "ofrecido, no marcado"
+      canonical_json: "Descargar el JSON canónico"
+      what_this_records: "Este registro muestra la redacción y las versiones de documentos
+        exactas que esta aplicación generó como oferta, y lo que se envió de vuelta. No
+        demuestra que nadie leyera o entendiera los documentos, y no es una opinión legal
+        sobre ellos."
+
+    kinds:
+      agreement: "Acuerdo"
+      acknowledgment: "Acuse de recibo"
+      consent: "Consentimiento"
+      declaration: "Declaración"
+      attestation: "Certificación"
+      authorization: "Autorización"
+
+    actions:
+      agreed: "Aceptado"
+      acknowledged: "Recibido"
+      granted: "Concedido"
+      declined: "Rechazado"
+      declared: "Declarado"
+      attested: "Certificado"
+      authorized: "Autorizado"
+      withdrawn: "Retirado"
+      renewed: "Renovado"
+      scope_changed: "Alcance modificado"
+      superseded: "Sustituido"
+      expired: "Caducado"
+      consumed: "Utilizado"
+      revoked: "Revocado"
+      corrected: "Corregido"
+
+    event_types:
+      capture: "Enviado"
+      withdrawal: "Retirado"
+      correction: "Corregido"
+      supersession: "Sustituido"
+      expiry: "Caducado"
+      consumption: "Utilizado"
+      revocation: "Revocado"
+      renewal: "Renovado"
+      scope_change: "Alcance modificado"
+      exemption: "Exención registrada — sin acción humana"
+      imported_legacy: "Importado de registros anteriores"
+      external_receipt: "Registrado por otro proveedor"
+      disposition: "Eliminado según una regla de retención"
+      legal_hold_placed: "Puesto en retención legal"
+      legal_hold_released: "Retención legal levantada"
+      receipt_access: "Registro consultado"
+      provider_outcome: "Resultado del proveedor registrado"

data/config/routes.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# The engine's own routes, drawn under whatever the host mounted it at:
+#
+#   mount Clickwrap::Engine => "/agreements"
+#
+# Four surfaces, and nothing else: complete a policy, read a receipt, withdraw a
+# consent, read a document version. They exist so that a required agreement, an
+# expired declaration, or a consent someone wants back is resolvable IN PLACE
+# instead of turning into a support ticket.
+#
+# Every screen has BOTH a GET and a form-action path at the same URL. That is
+# deliberate: a validation failure re-renders under the address the browser is
+# already on, so a no-JavaScript submission, a Turbo Drive visit, and a Hotwire
+# Native web screen all stay in the navigation context the host intended,
+# instead of landing on a POST-only URL that cannot be reloaded or shared.
+Clickwrap::Engine.routes.draw do
+  # Policy keys, consent purposes, and document version ids are plain
+  # identifiers. Constraining them keeps a path segment from carrying something
+  # shaped like a path.
+  identifier = %r{[^/.]+}
+
+  get "policies/:policy_key", to: "captures#show", as: :capture,
+                              constraints: { policy_key: identifier }
+  post "policies/:policy_key", to: "captures#create", as: :capture_submission,
+                               constraints: { policy_key: identifier }
+
+  get "consents/:purpose_key/withdrawal", to: "withdrawals#new", as: :withdrawal,
+                                          constraints: { purpose_key: identifier }
+  post "consents/:purpose_key/withdrawal", to: "withdrawals#create", as: :withdrawal_submission,
+                                           constraints: { purpose_key: identifier }
+
+  resources :receipts, only: %i[index show]
+
+  # What every document link in every presentation points at, and what an
+  # auditor opens years later: one immutable published version, by id.
+  get "documents/:id", to: "document_versions#show", as: :document_version,
+                       constraints: { id: identifier }
+
+  root to: "receipts#index"
+end