rails_consent 0.1.0

data/app/assets/javascripts/rails_consent.js

@@ -0,0 +1,379 @@
+(function(global) {
+  const SESSION_KEY = "rails_consent_session_id";
+  const BOUNDARY_SELECTOR = "[data-rails-consent]";
+  const FOCUSABLE_SELECTOR = [
+    "a[href]",
+    "area[href]",
+    "button:not([disabled])",
+    "input:not([disabled]):not([type='hidden'])",
+    "select:not([disabled])",
+    "textarea:not([disabled])",
+    "[tabindex]:not([tabindex='-1'])"
+  ].join(", ");
+
+  function now() {
+    return Math.floor(Date.now() / 1000);
+  }
+
+  let fallbackSessionId = null;
+
+  function sessionStorageRef() {
+    try {
+      return global.sessionStorage || null;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  function generateSessionId() {
+    return typeof global.crypto !== "undefined" && global.crypto.randomUUID ?
+      global.crypto.randomUUID() :
+      "rc-" + Math.random().toString(36).slice(2, 12);
+  }
+
+  function ensureSessionId() {
+    const storage = sessionStorageRef();
+    if (storage) {
+      const existing = storage.getItem(SESSION_KEY);
+      if (existing) return existing;
+
+      const generated = generateSessionId();
+      storage.setItem(SESSION_KEY, generated);
+      return generated;
+    }
+
+    if (fallbackSessionId) return fallbackSessionId;
+
+    fallbackSessionId = generateSessionId();
+    return fallbackSessionId;
+  }
+
+  function eventDetail(sessionId, preferences) {
+    const detailPreferences = Object.assign({}, preferences);
+    const timestamp = detailPreferences.timestamp || now();
+    detailPreferences.timestamp = timestamp;
+
+    return {
+      session_id: sessionId,
+      preferences: detailPreferences,
+      timestamp: timestamp
+    };
+  }
+
+  function dispatch(element, name, detail) {
+    element.dispatchEvent(new global.CustomEvent(name, {
+      bubbles: true,
+      detail: detail
+    }));
+  }
+
+  function preferenceKey(toggle) {
+    return toggle.name.replace(/^preferences\[|\]$/g, "");
+  }
+
+  function csrfToken() {
+    const meta = global.document && global.document.querySelector("meta[name='csrf-token']");
+    return meta ? meta.getAttribute("content") : "";
+  }
+
+  function normalizedPreferences(container, valueOverride) {
+    const preferences = {};
+
+    container.querySelectorAll("[data-rails-consent-category-toggle]").forEach(function(toggle) {
+      preferences[preferenceKey(toggle)] = toggle.disabled ? true : (valueOverride === undefined ? toggle.checked : valueOverride);
+    });
+
+    return preferences;
+  }
+
+  function resolveContainer(container) {
+    if (container) return container;
+    if (!global.document || typeof global.document.querySelector !== "function") return null;
+
+    return global.document.querySelector(BOUNDARY_SELECTOR);
+  }
+
+  function applyPreferences(container, preferences) {
+    container.dataset.railsConsentRecorded = "true";
+
+    container.querySelectorAll("[data-rails-consent-category-toggle]").forEach(function(toggle) {
+      toggle.checked = !!preferences[preferenceKey(toggle)];
+    });
+
+    hideBanner(container);
+  }
+
+  async function persistPreferences(container, preferences) {
+    const url = container.dataset.railsConsentPersistUrl;
+    if (!url || typeof global.fetch !== "function") return preferences;
+
+    const response = await global.fetch(url, {
+      method: "POST",
+      credentials: "same-origin",
+      headers: {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "X-CSRF-Token": csrfToken()
+      },
+      body: JSON.stringify({ preferences: preferences })
+    });
+
+    if (!response.ok) {
+      throw new Error("Rails Consent persistence failed with status " + response.status);
+    }
+
+    if (typeof response.json !== "function") return preferences;
+
+    const payload = await response.json();
+    return payload && payload.preferences ? payload.preferences : preferences;
+  }
+
+  function isDismissible(container) {
+    return container.dataset.railsConsentDismissible !== "false";
+  }
+
+  function hideBanner(container) {
+    const banner = container.querySelector("[data-rails-consent-banner]");
+    if (banner) banner.hidden = true;
+  }
+
+  function showModal(container) {
+    const modal = container.querySelector("[data-rails-consent-modal]");
+    if (!modal) return;
+
+    const focusable = modal.querySelectorAll(FOCUSABLE_SELECTOR);
+    modal.hidden = false;
+    modal.setAttribute("aria-hidden", "false");
+    modal.__railsConsentPreviouslyFocused = global.document.activeElement;
+
+    if (focusable.length > 0) focusable[0].focus();
+  }
+
+  function closeModal(container, options) {
+    const modal = container.querySelector("[data-rails-consent-modal]");
+    if (!modal) return;
+    if (!(options && options.force) && !isDismissible(container)) return;
+
+    modal.hidden = true;
+    modal.setAttribute("aria-hidden", "true");
+
+    if (modal.__railsConsentPreviouslyFocused && typeof modal.__railsConsentPreviouslyFocused.focus === "function") {
+      modal.__railsConsentPreviouslyFocused.focus();
+    }
+  }
+
+  function trapFocus(container, event) {
+    const modal = container.querySelector("[data-rails-consent-modal]");
+    if (!modal || modal.hidden) return;
+
+    if (event.key === "Escape") {
+      closeModal(container);
+      return;
+    }
+
+    if (event.key !== "Tab") return;
+
+    const focusable = Array.from(modal.querySelectorAll(FOCUSABLE_SELECTOR));
+    if (focusable.length === 0) return;
+
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+
+    if (event.shiftKey && global.document.activeElement === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && global.document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+
+  async function recordPreferences(container, sessionId, preferences, eventName) {
+    const lifecycleEventName = container.dataset.railsConsentRecorded === "true" ?
+      "rails-consent:preferences-updated" :
+      "rails-consent:preferences-saved";
+    const requestedPreferences = Object.assign({}, preferences, { timestamp: now() });
+    let recordedPreferences = requestedPreferences;
+
+    try {
+      const persistedPreferences = await persistPreferences(container, requestedPreferences);
+      recordedPreferences = Object.assign({}, requestedPreferences, persistedPreferences);
+    } catch (error) {
+      if (global.console && typeof global.console.error === "function") {
+        global.console.error("[Rails Consent] Failed to persist preferences", error);
+      }
+      return null;
+    }
+
+    applyPreferences(container, recordedPreferences);
+    closeModal(container, { force: true });
+
+    const detail = eventDetail(sessionId, recordedPreferences);
+    dispatch(container, lifecycleEventName, detail);
+
+    if (eventName !== lifecycleEventName) {
+      dispatch(container, eventName, detail);
+    }
+
+    return recordedPreferences;
+  }
+
+  function setupContainer(container) {
+    if (container.dataset.railsConsentInitialized === "true") return;
+
+    container.dataset.railsConsentInitialized = "true";
+    const sessionId = ensureSessionId();
+    const modal = container.querySelector("[data-rails-consent-modal]");
+    const banner = container.querySelector("[data-rails-consent-banner]");
+
+    if (banner && !banner.hidden) {
+      dispatch(container, "rails-consent:banner-shown", eventDetail(sessionId, normalizedPreferences(container)));
+    }
+
+    container.addEventListener("keydown", function(event) {
+      trapFocus(container, event);
+    });
+
+    container.querySelectorAll("[data-rails-consent-open-preferences]").forEach(function(trigger) {
+      trigger.addEventListener("click", function() {
+        showModal(container);
+        dispatch(container, "rails-consent:preferences-opened", eventDetail(sessionId, normalizedPreferences(container)));
+      });
+    });
+
+    container.querySelectorAll("[data-rails-consent-close-preferences]").forEach(function(trigger) {
+      trigger.addEventListener("click", function() {
+        closeModal(container);
+      });
+    });
+
+    container.querySelectorAll("[data-rails-consent-dismiss]").forEach(function(trigger) {
+      trigger.addEventListener("click", function() {
+        if (!isDismissible(container)) return;
+        hideBanner(container);
+        dispatch(container, "rails-consent:dismissed", eventDetail(sessionId, normalizedPreferences(container)));
+      });
+    });
+
+    container.querySelectorAll("[data-rails-consent-accept-all]").forEach(function(trigger) {
+      trigger.addEventListener("click", function() {
+        void recordPreferences(container, sessionId, normalizedPreferences(container, true), "rails-consent:accepted-all");
+      });
+    });
+
+    container.querySelectorAll("[data-rails-consent-reject-optional]").forEach(function(trigger) {
+      trigger.addEventListener("click", function() {
+        void recordPreferences(container, sessionId, normalizedPreferences(container, false), "rails-consent:rejected-optional");
+      });
+    });
+
+    const saveButton = container.querySelector("[data-rails-consent-save-preferences]");
+    if (saveButton) {
+      saveButton.addEventListener("click", function() {
+        void recordPreferences(container, sessionId, normalizedPreferences(container), "rails-consent:preferences-saved");
+      });
+    }
+
+    if (modal) {
+      modal.addEventListener("click", function(event) {
+        if (event.target === modal) closeModal(container);
+      });
+    }
+  }
+
+  function bindGlobalPreferenceTriggers(documentRef) {
+    if (documentRef.documentElement.dataset.railsConsentGlobalBound === "true") return;
+
+    documentRef.documentElement.dataset.railsConsentGlobalBound = "true";
+
+    documentRef.addEventListener("click", function(event) {
+      const trigger = event.target.closest("[data-rails-consent-open-preferences-global]");
+      if (!trigger) return;
+
+      const container = documentRef.querySelector(BOUNDARY_SELECTOR);
+      if (!container) return;
+
+      event.preventDefault();
+      showModal(container);
+      dispatch(container, "rails-consent:preferences-opened", eventDetail(
+        ensureSessionId(),
+        normalizedPreferences(container)
+      ));
+    });
+  }
+
+  function init(documentRef) {
+    const doc = documentRef || global.document;
+    if (!doc) return;
+
+    bindGlobalPreferenceTriggers(doc);
+    doc.querySelectorAll(BOUNDARY_SELECTOR).forEach(setupContainer);
+  }
+
+  function openPreferences(container) {
+    const target = resolveContainer(container);
+    if (!target) return;
+
+    showModal(target);
+    dispatch(target, "rails-consent:preferences-opened", eventDetail(
+      ensureSessionId(),
+      normalizedPreferences(target)
+    ));
+  }
+
+  function closePreferences(container, options) {
+    const target = resolveContainer(container);
+    if (!target) return;
+
+    closeModal(target, options);
+  }
+
+  function preferences(container) {
+    const target = resolveContainer(container);
+    if (!target) return {};
+
+    return normalizedPreferences(target);
+  }
+
+  function consentGiven(categoryName, container) {
+    const target = resolveContainer(container);
+    if (!target) return false;
+
+    const categoryKey = String(categoryName);
+    return preferences(target)[categoryKey] === true;
+  }
+
+  function consentRecorded(container) {
+    const target = resolveContainer(container);
+    if (!target) return false;
+
+    return target.dataset.railsConsentRecorded === "true";
+  }
+
+  function sessionId() {
+    return ensureSessionId();
+  }
+
+  const Runtime = {
+    init: init,
+    openPreferences: openPreferences,
+    closePreferences: closePreferences,
+    preferences: preferences,
+    consentGiven: consentGiven,
+    consentRecorded: consentRecorded,
+    sessionId: sessionId,
+    ensureSessionId: ensureSessionId,
+    eventDetail: eventDetail
+  };
+
+  if (typeof module !== "undefined" && module.exports) {
+    module.exports = Runtime;
+  }
+
+  global.RailsConsent = Runtime;
+
+  if (typeof document !== "undefined") {
+    document.addEventListener("DOMContentLoaded", function() { init(document); });
+    document.addEventListener("turbo:load", function() { init(document); });
+  }
+})(typeof window !== "undefined" ? window : globalThis);

data/app/assets/stylesheets/rails_consent/application.css

@@ -0,0 +1,21 @@
+/*
+ * rails_consent intentionally keeps styling minimal so host applications can
+ * own presentation. These classes exist primarily as semantic hooks.
+ */
+
+.rails-consent-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.rails-consent-banner[hidden],
+.rails-consent-modal[hidden] {
+  display: none !important;
+}

data/app/controllers/concerns/rails_consent/controller_helpers.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RailsConsent
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :consent_given?, :consent_preferences, :consent_recorded?, :reset_consent!
+    end
+
+    def consent_given?(category_name)
+      category = rails_consent_categories.find { |item| item.key == category_name.to_sym }
+      return false unless category
+
+      rails_consent_configuration.consent_resolver.call(
+        category: category,
+        preferences: consent_preferences,
+        categories: rails_consent_categories,
+        context: self,
+        storage: rails_consent_configuration.storage
+      )
+    end
+
+    def consent_preferences
+      @rails_consent_preferences ||= RailsConsent::PreferenceSet.new(
+        categories: rails_consent_categories,
+        source: rails_consent_raw_preferences
+      ).to_h
+    end
+
+    def consent_recorded?
+      return @rails_consent_recorded unless @rails_consent_recorded.nil?
+
+      @rails_consent_recorded = ActiveModel::Type::Boolean.new.cast(
+        rails_consent_configuration.consent_recorded_provider.call(
+          context: self,
+          categories: rails_consent_categories,
+          cookies: send(:cookies),
+          preferences: consent_preferences,
+          request: request,
+          raw_preferences: rails_consent_raw_preferences,
+          storage: rails_consent_configuration.storage
+        )
+      )
+    end
+
+    def reset_consent!
+      rails_consent_configuration.preferences_destroyer.call(
+        context: self,
+        categories: rails_consent_categories,
+        cookies: send(:cookies),
+        request: request,
+        storage: rails_consent_configuration.storage
+      )
+
+      @rails_consent_preferences = nil
+      @rails_consent_raw_preferences = nil
+      @rails_consent_recorded = nil
+      true
+    end
+
+    private
+
+    def rails_consent_categories
+      @rails_consent_categories ||= RailsConsent::CategoryLoader.new(locale: I18n.locale).categories
+    end
+
+    def rails_consent_configuration
+      @rails_consent_configuration ||= RailsConsent.configuration.tap(&:validate!)
+    end
+
+    def rails_consent_raw_preferences
+      @rails_consent_raw_preferences ||= begin
+        value = rails_consent_configuration.preferences_provider.call(
+          context: self,
+          categories: rails_consent_categories,
+          cookies: send(:cookies),
+          request: request,
+          storage: rails_consent_configuration.storage
+        )
+
+        value.nil? ? {} : value
+      end
+    end
+  end
+end

data/app/controllers/rails_consent/preferences_controller.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RailsConsent
+  class PreferencesController < ::ApplicationController
+    def create
+      payload = configuration.preferences_writer.call(
+        context: self,
+        categories: categories,
+        cookies: cookies,
+        preferences: preferences_params.to_h,
+        request: request,
+        storage: configuration.storage
+      )
+
+      render json: {
+        preferences: normalized_preferences(payload || preferences_params.to_h)
+      }
+    end
+
+    def destroy
+      configuration.preferences_destroyer.call(
+        context: self,
+        categories: categories,
+        cookies: cookies,
+        request: request,
+        storage: configuration.storage
+      )
+
+      head :no_content
+    end
+
+    private
+
+    def categories
+      @categories ||= RailsConsent::CategoryLoader.new(locale: I18n.locale).categories
+    end
+
+    def configuration
+      @configuration ||= RailsConsent.configuration.tap(&:validate!)
+    end
+
+    def normalized_preferences(payload)
+      RailsConsent::PreferenceSet.new(
+        categories: categories,
+        source: payload
+      ).to_h
+    end
+
+    def preferences_params
+      params.fetch(:preferences, ActionController::Parameters.new).permit(
+        *categories.map { |category| category.key.to_s }
+      )
+    end
+  end
+end

data/app/helpers/rails_consent/application_helper.rb

@@ -0,0 +1,44 @@
+module RailsConsent
+  module ApplicationHelper
+    def rails_consent_assets
+      safe_join(
+        [
+          stylesheet_link_tag("rails_consent/application", media: "all", "data-turbo-track": "reload"),
+          javascript_include_tag("rails_consent", "data-turbo-track": "reload", defer: true, nonce: true)
+        ],
+        "\n"
+      )
+    end
+
+    def rails_consent_banner(position: nil, dismissible: nil)
+      configuration = controller.send(:rails_consent_configuration)
+
+      render partial: "rails_consent/banner", locals: {
+        categories: controller.send(:rails_consent_categories),
+        preferences: consent_preferences,
+        position: (position || configuration.banner_position).to_sym,
+        dismissible: dismissible.nil? ? configuration.prompt_dismissible : dismissible,
+        consent_recorded: consent_recorded?,
+        persist_url: rails_consent_preferences_path
+      }
+    end
+
+    def rails_consent_preferences_button(label = nil, **options, &block)
+      if label.is_a?(Hash)
+        options = label
+        label = nil
+      end
+
+      html_options = {
+        type: "button",
+        data: { rails_consent_open_preferences_global: true }
+      }.deep_merge(options)
+
+      if block_given?
+        button_tag(**html_options, &block)
+      else
+        button_tag(label || t("rails_consent.banner.manage_preferences"), **html_options)
+      end
+    end
+  end
+end

data/app/views/rails_consent/_banner.html.erb

@@ -0,0 +1,45 @@
+<section
+  class="rails-consent rails-consent--<%= position %>"
+  data-rails-consent
+  data-rails-consent-dismissible="<%= dismissible %>"
+  data-rails-consent-persist-url="<%= persist_url %>"
+  data-rails-consent-recorded="<%= consent_recorded %>">
+  <div
+    class="rails-consent-banner"
+    data-rails-consent-banner
+    <%= %(hidden="hidden") if consent_recorded %>>
+    <div class="rails-consent-banner__content">
+      <p class="rails-consent-banner__eyebrow"><%= t("rails_consent.banner.eyebrow") %></p>
+      <h2 class="rails-consent-banner__title"><%= t("rails_consent.banner.title") %></h2>
+      <p class="rails-consent-banner__text">
+        <%= t("rails_consent.banner.description") %>
+      </p>
+    </div>
+
+    <div class="rails-consent-banner__actions">
+      <button type="button" class="rails-consent-banner__button" data-rails-consent-accept-all>
+        <%= t("rails_consent.banner.accept_all") %>
+      </button>
+      <button type="button" class="rails-consent-banner__button" data-rails-consent-reject-optional>
+        <%= t("rails_consent.banner.reject_optional") %>
+      </button>
+      <button type="button" class="rails-consent-banner__button" data-rails-consent-open-preferences>
+        <%= t("rails_consent.banner.manage_preferences") %>
+      </button>
+      <% if dismissible %>
+        <button
+          type="button"
+          class="rails-consent-banner__button"
+          data-rails-consent-dismiss>
+          <%= t("rails_consent.banner.dismiss") %>
+        </button>
+      <% end %>
+    </div>
+  </div>
+
+  <%= render partial: "rails_consent/preferences_modal", locals: {
+    categories: categories,
+    preferences: preferences,
+    dismissible: dismissible
+  } %>
+</section>

data/app/views/rails_consent/_category_toggle.html.erb

@@ -0,0 +1,32 @@
+<% key = category.key.to_s %>
+<% input_id = "rails-consent-category-#{index}-#{key}" %>
+<% description_id = "#{input_id}-description" %>
+
+<article class="rails-consent-category">
+  <div class="rails-consent-category__header">
+    <div>
+      <h3 class="rails-consent-category__title"><%= category.label %></h3>
+      <p id="<%= description_id %>" class="rails-consent-category__description"><%= category.description %></p>
+    </div>
+
+    <div class="rails-consent-category__toggle">
+      <input
+        id="<%= input_id %>"
+        type="checkbox"
+        name="preferences[<%= key %>]"
+        value="true"
+        class="rails-consent-category__checkbox"
+        aria-describedby="<%= description_id %>"
+        data-rails-consent-category-toggle
+        <%= %(checked="checked") if preferences[key] %>
+        <%= %(disabled="disabled") if category.required? %>>
+      <label for="<%= input_id %>" class="rails-consent-category__label">
+        <%= category.required? ? t("rails_consent.category.always_enabled") : t("rails_consent.category.allow_category", category: category.label.downcase) %>
+      </label>
+    </div>
+  </div>
+
+  <% if category.cookies.any? %>
+    <%= render partial: "rails_consent/cookie_table", locals: { category: category } %>
+  <% end %>
+</article>

data/app/views/rails_consent/_cookie_table.html.erb

@@ -0,0 +1,19 @@
+<table class="rails-consent-cookie-table">
+  <caption class="rails-consent-visually-hidden"><%= t("rails_consent.category.cookies_caption", category: category.label) %></caption>
+  <thead>
+    <tr>
+      <th scope="col"><%= t("rails_consent.category.table.cookie") %></th>
+      <th scope="col"><%= t("rails_consent.category.table.provider") %></th>
+      <th scope="col"><%= t("rails_consent.category.table.purpose") %></th>
+    </tr>
+  </thead>
+  <tbody>
+    <% category.cookies.each do |cookie| %>
+      <tr>
+        <th scope="row"><%= cookie.name %></th>
+        <td><%= cookie.provider || t("rails_consent.category.not_specified") %></td>
+        <td><%= cookie.purpose || t("rails_consent.category.not_specified") %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>