biscuit-rails 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2cbbeb961e7c378e000b1e9406a080b4abb744427c0cf54e06f41520f3db858
+  data.tar.gz: ba4ca1917c1a017958c53b9682721ac506a49924253e9f72db6dc88aca90377f
+SHA512:
+  metadata.gz: 610e88154f02e24a8a9e32f075bc1ee406c1cbba9d161dc4bf84cd3266711c61337da365aed1865520b87390aae30f70746ec17eea7149894aa26171212f866f
+  data.tar.gz: 7dc949957ecc062fd0266780414039c0b146f36073d6e3fb7c1b7b7bb2de4451b3129cf548735b1b08e9b827d6ee716c51e14364229bf9fb66ee5852ca38b893

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-03-19
+
+### Added
+
+- `reload_on_consent` option for `biscuit_banner` — when `true`, triggers a
+  `Turbo.visit` page reload after consent is saved so conditionally-loaded
+  scripts are evaluated with the updated cookie
+
+---
+
+## [0.1.0] - 2026-03-19
+
+### Added
+
+- GDPR-compliant cookie consent banner for Rails 8+
+- Configurable banner position (top or bottom)
+- Cookie categories with per-category consent tracking (necessary, analytics, marketing, preferences)
+- Stimulus controller for accept all, reject all, manage preferences, and reopen flows
+- Preferences panel with per-category checkboxes, pre-populated from existing consent state
+- Persistent "Cookie settings" reopener link shown after consent is given
+- Consent stored as a versioned JSON cookie (`biscuit_consent`)
+- `biscuit_banner` view helper for rendering the banner in any layout
+- `biscuit_allowed?(:category)` helper for conditional script/content loading in views
+- `Biscuit::Consent.new(cookies).allowed?(:category)` for controller-level consent checks
+- Full configuration API via `Biscuit.configure` initializer
+- i18n support with English and French translations included
+- CSS custom property theming — all visual tokens overridable without touching gem CSS
+- Rails engine with isolated namespace, auto-mounted routes at `/biscuit/consent`
+- No runtime dependencies beyond Rails itself
+- No asset pipeline (Sprockets) dependency — assets served via Propshaft
+- No JavaScript build step — delivered as a plain ES module for import maps

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth James
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,413 @@
+# Biscuit
+
+GDPR-compliant cookie consent banner for Rails 8. Renders a configurable
+bottom/top banner, manages consent state via a browser cookie, and exposes a
+Stimulus controller for interactivity. Supports i18n and CSS custom property
+theming with no external runtime dependencies.
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|---|---|
+| Ruby | >= 3.2 |
+| Rails | >= 8.0 |
+| Stimulus | Any (via `@hotwired/stimulus`) |
+| Import maps | Rails default (`importmap-rails`) |
+
+No Sprockets, no build step. Assets are served via **Propshaft** (Rails 8
+default).
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "biscuit-rails"
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+---
+
+## Setup
+
+### 1. Mount the engine
+
+In `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Biscuit::Engine, at: "/biscuit"
+  # ... your other routes
+end
+```
+
+### 2. Pin the Stimulus controller
+
+In `config/importmap.rb`:
+
+```ruby
+pin "biscuit/biscuit_controller", to: "biscuit/biscuit_controller.js"
+```
+
+### 3. Register the Stimulus controller
+
+In `app/javascript/controllers/index.js`:
+
+```javascript
+import BiscuitController from "biscuit/biscuit_controller"
+application.register("biscuit", BiscuitController)
+```
+
+### 4. Include the stylesheet
+
+In your layout (`app/views/layouts/application.html.erb`):
+
+```erb
+<%= stylesheet_link_tag "biscuit/biscuit" %>
+```
+
+### 5. Render the banner
+
+In your layout, inside `<body>`:
+
+```erb
+<%= biscuit_banner %>
+```
+
+That's it. The banner renders on every page. Once a user makes a consent
+choice it hides itself and shows a small "Cookie settings" link so they can
+revisit their preferences at any time.
+
+---
+
+## Banner Options
+
+`biscuit_banner` accepts keyword options to control behaviour per-page:
+
+### `reload_on_consent`
+
+When `true`, the page reloads via `Turbo.visit` after the user saves their
+consent choice, instead of just hiding the banner. This is useful when your
+layout conditionally loads scripts based on consent — a reload ensures those
+scripts are evaluated with the new cookie in place.
+
+```erb
+<%= biscuit_banner(reload_on_consent: true) %>
+```
+
+Default: `false` — the banner hides in place without a page reload.
+
+---
+
+## Configuration
+
+Create an initializer at `config/initializers/biscuit.rb`:
+
+```ruby
+Biscuit.configure do |config|
+  # Cookie categories — see "Custom categories" below
+  config.categories = {
+    necessary:   { required: true },
+    analytics:   { required: false },
+    preferences: { required: false },
+    marketing:   { required: false }
+  }
+
+  # Name of the browser cookie that stores consent state
+  # Default: "biscuit_consent"
+  config.cookie_name = "biscuit_consent"
+
+  # How long the consent cookie lasts, in days
+  # Default: 365
+  config.cookie_expires_days = 365
+
+  # Cookie path
+  # Default: "/"
+  config.cookie_path = "/"
+
+  # Cookie domain — nil means current domain
+  # Default: nil
+  config.cookie_domain = nil
+
+  # SameSite attribute
+  # Default: "Lax"
+  config.cookie_same_site = "Lax"
+
+  # Banner position: :bottom or :top
+  # Default: :bottom
+  config.position = :bottom
+
+  # URL for the "Learn more" privacy policy link
+  # Default: "#"
+  config.privacy_policy_url = "/privacy"
+end
+```
+
+### All options at a glance
+
+| Option | Default | Description |
+|---|---|---|
+| `categories` | `{necessary: {required: true}, analytics: {required: false}, marketing: {required: false}}` | Cookie categories shown to the user |
+| `cookie_name` | `"biscuit_consent"` | Browser cookie name |
+| `cookie_expires_days` | `365` | Cookie lifetime in days |
+| `cookie_path` | `"/"` | Cookie path |
+| `cookie_domain` | `nil` | Cookie domain (nil = current domain) |
+| `cookie_same_site` | `"Lax"` | SameSite cookie attribute |
+| `position` | `:bottom` | Banner position (`:bottom` or `:top`) |
+| `privacy_policy_url` | `"#"` | "Learn more" link URL |
+
+---
+
+## Custom Cookie Categories
+
+Define any categories you need. Each entry requires a `:required` key.
+Categories with `required: true` are shown as permanently checked and
+non-toggleable (necessary cookies). All others are opt-in checkboxes.
+
+```ruby
+config.categories = {
+  necessary:   { required: true },
+  analytics:   { required: false },
+  preferences: { required: false },
+  marketing:   { required: false }
+}
+```
+
+Add matching i18n keys for each custom category. For example, to add a
+`preferences` category, add to `config/locales/en.yml`:
+
+```yaml
+en:
+  biscuit:
+    categories:
+      preferences:
+        name:        "Preferences"
+        description: "Remember your settings and personalisation choices."
+```
+
+Biscuit ships with built-in translations for `necessary`, `analytics`,
+`marketing`, and `preferences` in English and French. Any other category
+requires you to add your own keys.
+
+---
+
+## CSS Theming
+
+All styles are scoped under `.biscuit-banner`. Every visual property is
+expressed as a CSS custom property, so you can override the entire look
+without touching the gem.
+
+### Available custom properties
+
+| Property | Default | Description |
+|---|---|---|
+| `--biscuit-bg` | `Canvas` | Banner background colour (browser default background) |
+| `--biscuit-color` | `CanvasText` | Banner text colour (browser default text) |
+| `--biscuit-muted` | `GrayText` | Secondary / description text colour |
+| `--biscuit-accent` | `#4f46e5` | Primary button background |
+| `--biscuit-accent-hover` | `#4338ca` | Primary button hover background |
+| `--biscuit-border` | `rgba(0,0,0,0.12)` | Divider / border colour |
+| `--biscuit-radius` | `0.375rem` | Button / panel border radius |
+| `--biscuit-font-size` | `0.875rem` | Base font size |
+| `--biscuit-font-family` | `inherit` | Font family |
+| `--biscuit-z-index` | `9999` | Stack order |
+| `--biscuit-padding` | `1rem 1.5rem` | Banner padding |
+| `--biscuit-shadow-bottom` | `0 -2px 12px rgba(0,0,0,0.12)` | Shadow when `position: bottom` |
+| `--biscuit-shadow-top` | `0 2px 12px rgba(0,0,0,0.12)` | Shadow when `position: top` |
+| `--biscuit-max-width` | `64rem` | Inner content max-width |
+
+### Override example
+
+In your application's CSS, after including the biscuit stylesheet:
+
+```css
+.biscuit-banner {
+  --biscuit-accent:       #0070f3;
+  --biscuit-accent-hover: #005bb5;
+  --biscuit-border:       rgba(0, 0, 0, 0.08);
+}
+```
+
+---
+
+## Checking Consent in Views
+
+Use the `biscuit_allowed?` helper, which is available in all views and
+layouts:
+
+```erb
+<% if biscuit_allowed?(:analytics) %>
+  <!-- Google Analytics or similar -->
+  <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXX"></script>
+<% end %>
+
+<% if biscuit_allowed?(:marketing) %>
+  <!-- Marketing pixel -->
+<% end %>
+```
+
+`:necessary` always returns `true` regardless of cookie state.
+
+---
+
+## Checking Consent in Controllers
+
+```ruby
+class ApplicationController < ActionController::Base
+  def analytics_enabled?
+    Biscuit::Consent.new(cookies).allowed?(:analytics)
+  end
+end
+```
+
+---
+
+## Cookie Format
+
+The consent cookie stores a JSON payload:
+
+```json
+{
+  "v": 1,
+  "consented_at": "2026-03-19T10:00:00Z",
+  "categories": {
+    "necessary": true,
+    "analytics": false,
+    "marketing": true
+  }
+}
+```
+
+- `v` — schema version (currently `1`). Biscuit ignores cookies from
+  unknown versions.
+- `consented_at` — UTC ISO 8601 timestamp of when consent was recorded.
+- `categories` — per-category boolean map. `necessary` is always `true`.
+
+The cookie is **not** `httponly` so that client-side JavaScript can read
+consent state for lazy-loading scripts.
+
+---
+
+## GDPR Notes
+
+Biscuit provides the consent UI and storage mechanism. You are responsible for:
+
+### What Biscuit does
+
+- Renders a banner that requires an explicit user action before dismissal
+  (no auto-dismiss)
+- Offers equally prominent "Accept all" and "Reject non-essential" buttons
+- Records granular, timestamped consent per category
+- Allows the user to withdraw or amend consent at any time via the
+  "Cookie settings" link
+- Marks `:necessary` cookies as non-toggleable and clearly labelled
+- Writes no non-essential cookies itself — only the consent cookie, which
+  is a functional/necessary cookie
+
+### What Biscuit does NOT do
+
+- **It does not block third-party scripts automatically.** You must
+  conditionally load scripts based on `biscuit_allowed?(:category)`.
+  See the pattern below.
+- It does not implement geo-targeting (showing the banner only to EU
+  visitors).
+- It does not store consent in a database (v1 is cookie-only).
+- It does not provide a legal opinion on whether your implementation
+  meets GDPR requirements. Consult a lawyer.
+
+### Pattern: blocking non-essential scripts until consent
+
+```erb
+<%# In your layout — only load analytics after consent %>
+<% if biscuit_allowed?(:analytics) %>
+  <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXX"></script>
+  <script>
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+    gtag('config', 'G-XXXXXX');
+  </script>
+<% end %>
+```
+
+For scripts that must load on the client side after a user accepts consent
+during their current session (without a page reload), listen for the Fetch
+response in your own JavaScript and initialise scripts there, or use a
+lightweight Turbo visit to reload the page after the consent POST succeeds.
+(Turbo Stream support for post-consent injection is planned for v2.)
+
+### GDPR compliance checklist
+
+- [x] No non-essential cookies set before consent
+- [x] Consent is freely given — equal prominence for accept and reject
+- [x] No pre-ticked boxes for non-required categories
+- [x] No dark patterns
+- [x] User can withdraw or amend consent at any time
+- [x] Consent is granular — recorded per category
+- [x] Consent is timestamped
+- [x] Necessary cookies are clearly labelled and non-toggleable
+- [x] Banner does not auto-dismiss
+
+---
+
+## i18n
+
+Biscuit ships with English (`en`) and French (`fr`) translations. To add
+another locale, create `config/locales/biscuit.<locale>.yml` in your app:
+
+```yaml
+de:
+  biscuit:
+    banner:
+      aria_label:  "Cookie-Zustimmung"
+      message:     "Wir verwenden Cookies, um Ihr Erlebnis auf dieser Website zu verbessern."
+      learn_more:  "Mehr erfahren"
+      accept_all:  "Alle akzeptieren"
+      reject_all:  "Nicht wesentliche ablehnen"
+      manage:      "Einstellungen verwalten"
+      save:        "Einstellungen speichern"
+      reopen:      "Cookie-Einstellungen"
+    categories:
+      necessary:
+        name:        "Notwendig"
+        description: "Für die Funktion der Website erforderlich. Kann nicht deaktiviert werden."
+      analytics:
+        name:        "Analyse"
+        description: "Helfen uns zu verstehen, wie Besucher die Website nutzen."
+      marketing:
+        name:        "Marketing"
+        description: "Werden verwendet, um personalisierte Werbung anzuzeigen."
+      preferences:
+        name:        "Präferenzen"
+        description: "Speichern Ihre Einstellungen und Personalisierungsoptionen."
+```
+
+---
+
+## Engine Routes
+
+The engine mounts two endpoints:
+
+| Method | Path | Action |
+|---|---|---|
+| `POST` | `/biscuit/consent` | Record consent for all categories |
+| `DELETE` | `/biscuit/consent` | Clear the consent cookie |
+
+Both endpoints require a valid CSRF token. The Stimulus controller
+reads the token from the `data-biscuit-csrf-token-value` attribute
+(set automatically by the banner partial from `form_authenticity_token`).
+
+---
+
+## License
+
+MIT

data/app/assets/javascripts/biscuit/biscuit_controller.js

@@ -0,0 +1,89 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["preferencesPanel", "categoryCheckbox", "manageLink"]
+  static values  = {
+    endpoint:         String,
+    csrfToken:        String,
+    position:         { type: String, default: "bottom" },
+    alreadyConsented: { type: Boolean, default: false },
+    reloadOnConsent:  { type: Boolean, default: false }
+  }
+
+  connect() {
+    if (this.alreadyConsentedValue) {
+      this.#hideBanner()
+      this.#showManageLink()
+    }
+  }
+
+  acceptAll() {
+    this.#post(this.#allCategories(true))
+  }
+
+  rejectAll() {
+    this.#post(this.#allCategories(false))
+  }
+
+  togglePreferences() {
+    const panel  = this.preferencesPanelTarget
+    const isOpen = panel.classList.contains("biscuit-preferences--open")
+    panel.classList.toggle("biscuit-preferences--open", !isOpen)
+    panel.hidden = isOpen
+
+    // Update aria-expanded on the toggle button
+    const btn = this.element.querySelector("[data-action~='biscuit#togglePreferences']")
+    if (btn) btn.setAttribute("aria-expanded", String(!isOpen))
+  }
+
+  savePreferences() {
+    const categories = {}
+    this.categoryCheckboxTargets.forEach(cb => {
+      categories[cb.dataset.category] = cb.checked
+    })
+    this.#post(categories)
+  }
+
+  reopen() {
+    this.#showBanner()
+    this.#hideManageLink()
+  }
+
+  // Private
+
+  #allCategories(value) {
+    const categories = {}
+    this.categoryCheckboxTargets.forEach(cb => {
+      categories[cb.dataset.category] = value
+    })
+    return categories
+  }
+
+  async #post(categories) {
+    try {
+      const response = await fetch(this.endpointValue, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-CSRF-Token":  this.csrfTokenValue
+        },
+        body: JSON.stringify({ categories })
+      })
+      if (response.ok) {
+        if (this.reloadOnConsentValue) {
+          Turbo.visit(window.location.href)
+        } else {
+          this.#hideBanner()
+          this.#showManageLink()
+        }
+      }
+    } catch (error) {
+      console.error("[Biscuit] Failed to save consent:", error)
+    }
+  }
+
+  #hideBanner()     { this.element.hidden = true;  this.element.setAttribute("aria-hidden", "true") }
+  #showBanner()     { this.element.hidden = false; this.element.removeAttribute("aria-hidden") }
+  #showManageLink() { if (this.hasManageLinkTarget) this.manageLinkTarget.hidden = false }
+  #hideManageLink() { if (this.hasManageLinkTarget) this.manageLinkTarget.hidden = true }
+}

data/app/assets/stylesheets/biscuit/biscuit.css

@@ -0,0 +1,123 @@
+.biscuit-banner {
+  /* Tokens — override in your app's CSS */
+  --biscuit-bg:              Canvas;
+  --biscuit-color:           CanvasText;
+  --biscuit-muted:           GrayText;
+  --biscuit-accent:          #4f46e5;
+  --biscuit-accent-hover:    #4338ca;
+  --biscuit-border:          rgba(0,0,0,0.12);
+  --biscuit-radius:          0.375rem;
+  --biscuit-font-size:       0.875rem;
+  --biscuit-font-family:     inherit;
+  --biscuit-z-index:         9999;
+  --biscuit-padding:         1rem 1.5rem;
+  --biscuit-shadow-bottom:   0 -2px 12px rgba(0,0,0,0.12);
+  --biscuit-shadow-top:      0 2px 12px rgba(0,0,0,0.12);
+  --biscuit-max-width:       64rem;
+
+  position:    fixed;
+  left:        0;
+  right:       0;
+  z-index:     var(--biscuit-z-index);
+  background:  var(--biscuit-bg);
+  color:       var(--biscuit-color);
+  font-size:   var(--biscuit-font-size);
+  font-family: var(--biscuit-font-family);
+  padding:     var(--biscuit-padding);
+}
+
+.biscuit-banner[data-biscuit-position-value="bottom"] {
+  bottom:     0;
+  box-shadow: var(--biscuit-shadow-bottom);
+}
+
+.biscuit-banner[data-biscuit-position-value="top"] {
+  top:        0;
+  box-shadow: var(--biscuit-shadow-top);
+}
+
+.biscuit-banner__inner {
+  max-width:   var(--biscuit-max-width);
+  margin:      0 auto;
+  display:     flex;
+  flex-wrap:   wrap;
+  align-items: center;
+  gap:         0.75rem;
+}
+
+.biscuit-banner__message { flex: 1 1 20rem; }
+
+.biscuit-banner__actions {
+  display:   flex;
+  flex-wrap: wrap;
+  gap:       0.5rem;
+}
+
+.biscuit-btn {
+  display:       inline-flex;
+  align-items:   center;
+  padding:       0.4rem 0.9rem;
+  border-radius: var(--biscuit-radius);
+  font-size:     var(--biscuit-font-size);
+  font-weight:   500;
+  cursor:        pointer;
+  border:        1px solid transparent;
+  transition:    background 0.15s, color 0.15s;
+  white-space:   nowrap;
+}
+
+.biscuit-btn--primary {
+  background: var(--biscuit-accent);
+  color:      #fff;
+}
+.biscuit-btn--primary:hover  { background: var(--biscuit-accent-hover); }
+
+.biscuit-btn--secondary {
+  background:   transparent;
+  color:        var(--biscuit-color);
+  border-color: var(--biscuit-border);
+}
+.biscuit-btn--secondary:hover { background: rgba(0,0,0,0.05); }
+
+.biscuit-preferences { width: 100%; margin-top: 0.75rem; border-top: 1px solid var(--biscuit-border); padding-top: 0.75rem; }
+.biscuit-preferences:not(.biscuit-preferences--open) { display: none; }
+
+.biscuit-preference-row {
+  display:       flex;
+  align-items:   flex-start;
+  gap:           0.75rem;
+  padding:       0.5rem 0;
+  border-bottom: 1px solid var(--biscuit-border);
+}
+.biscuit-preference-row:last-child    { border-bottom: none; }
+.biscuit-preference-row__label       { flex: 1; }
+.biscuit-preference-row__name        { font-weight: 600; display: block; }
+.biscuit-preference-row__description { color: var(--biscuit-muted); font-size: 0.8rem; }
+
+.biscuit-preferences__footer {
+  margin-top: 0.75rem;
+}
+
+.biscuit-manage-link {
+  position:        fixed;
+  z-index:         var(--biscuit-z-index);
+  font-size:       0.75rem;
+  color:           var(--biscuit-muted);
+  background:      transparent;
+  border:          none;
+  cursor:          pointer;
+  padding:         0.25rem 0.5rem;
+  text-decoration: underline;
+}
+.biscuit-manage-link[data-biscuit-position-value="bottom"] { bottom: 0.5rem; left: 1rem; }
+.biscuit-manage-link[data-biscuit-position-value="top"]    { top: 0.5rem;    left: 1rem; }
+
+.biscuit-learn-more {
+  color: var(--biscuit-color);
+}
+
+@media (max-width: 640px) {
+  .biscuit-banner__inner   { flex-direction: column; align-items: flex-start; }
+  .biscuit-banner__actions { width: 100%; }
+  .biscuit-btn             { flex: 1 1 auto; justify-content: center; }
+}

data/app/controllers/biscuit/consent_controller.rb

@@ -0,0 +1,18 @@
+module Biscuit
+  class ConsentController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    def update
+      categories = params.require(:categories).permit(
+        Biscuit.configuration.categories.keys.map(&:to_s)
+      ).to_h
+      Biscuit::Consent.write(cookies, categories)
+      render json: { ok: true }
+    end
+
+    def destroy
+      Biscuit::Consent.clear(cookies)
+      render json: { ok: true }
+    end
+  end
+end

data/app/helpers/biscuit/biscuit_helper.rb

@@ -0,0 +1,18 @@
+module Biscuit
+  module BiscuitHelper
+    # Renders the consent banner.
+    # If consent has already been given, renders only the minimal
+    # "Cookie settings" reopener link (hidden banner state).
+    def biscuit_banner(**options)
+      consent = Biscuit::Consent.new(cookies)
+      render partial: "biscuit/banner/banner",
+             locals: { consent: consent, options: options }
+    end
+
+    # Returns true if the user has consented to the given category.
+    # Safe to call even when no cookie exists — returns false.
+    def biscuit_allowed?(category)
+      Biscuit::Consent.new(cookies).allowed?(category)
+    end
+  end
+end

data/app/views/biscuit/banner/_banner.html.erb

@@ -0,0 +1,104 @@
+<div class="biscuit-banner"
+     data-controller="biscuit"
+     data-biscuit-position-value="<%= Biscuit.configuration.position %>"
+     data-biscuit-csrf-token-value="<%= form_authenticity_token %>"
+     data-biscuit-endpoint-value="<%= biscuit.consent_path %>"
+     data-biscuit-already-consented-value="<%= consent.given? %>"
+     data-biscuit-reload-on-consent-value="<%= options[:reload_on_consent] ? 'true' : 'false' %>"
+     role="dialog"
+     aria-label="<%= t("biscuit.banner.aria_label") %>"
+     aria-modal="false">
+
+  <div class="biscuit-banner__inner">
+    <p class="biscuit-banner__message">
+      <%= t("biscuit.banner.message") %>
+      <a href="<%= Biscuit.configuration.privacy_policy_url %>" class="biscuit-learn-more">
+        <%= t("biscuit.banner.learn_more") %>
+      </a>
+    </p>
+
+    <div class="biscuit-banner__actions">
+      <button type="button"
+              class="biscuit-btn biscuit-btn--primary"
+              data-action="click->biscuit#acceptAll"
+              aria-label="<%= t("biscuit.banner.accept_all") %>">
+        <%= t("biscuit.banner.accept_all") %>
+      </button>
+
+      <button type="button"
+              class="biscuit-btn biscuit-btn--secondary"
+              data-action="click->biscuit#rejectAll"
+              aria-label="<%= t("biscuit.banner.reject_all") %>">
+        <%= t("biscuit.banner.reject_all") %>
+      </button>
+
+      <button type="button"
+              class="biscuit-btn biscuit-btn--secondary"
+              data-action="click->biscuit#togglePreferences"
+              aria-expanded="false"
+              aria-controls="biscuit-preferences-panel">
+        <%= t("biscuit.banner.manage") %>
+      </button>
+    </div>
+
+    <div id="biscuit-preferences-panel"
+         class="biscuit-preferences"
+         data-biscuit-target="preferencesPanel"
+         hidden
+         aria-label="<%= t("biscuit.banner.manage") %>">
+
+      <% Biscuit.configuration.categories.each do |key, opts| %>
+        <div class="biscuit-preference-row">
+          <% checkbox_id = "biscuit-category-#{key}" %>
+
+          <% if opts[:required] %>
+            <input type="checkbox"
+                   id="<%= checkbox_id %>"
+                   checked
+                   disabled
+                   aria-label="<%= t("biscuit.categories.#{key}.name") %>"
+                   aria-describedby="<%= checkbox_id %>-desc">
+          <% else %>
+            <input type="checkbox"
+                   id="<%= checkbox_id %>"
+                   data-biscuit-target="categoryCheckbox"
+                   data-category="<%= key %>"
+                   <%= consent.given? && consent.allowed?(key) ? "checked" : "" %>
+                   aria-label="<%= t("biscuit.categories.#{key}.name") %>"
+                   aria-describedby="<%= checkbox_id %>-desc">
+          <% end %>
+
+          <div class="biscuit-preference-row__label">
+            <label for="<%= checkbox_id %>" class="biscuit-preference-row__name">
+              <%= t("biscuit.categories.#{key}.name") %>
+              <% if opts[:required] %>
+                <span aria-hidden="true"> (required)</span>
+              <% end %>
+            </label>
+            <span id="<%= checkbox_id %>-desc" class="biscuit-preference-row__description">
+              <%= t("biscuit.categories.#{key}.description") %>
+            </span>
+          </div>
+        </div>
+      <% end %>
+
+      <div class="biscuit-preferences__footer">
+        <button type="button"
+                class="biscuit-btn biscuit-btn--primary"
+                data-action="click->biscuit#savePreferences">
+          <%= t("biscuit.banner.save") %>
+        </button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<button type="button"
+        class="biscuit-manage-link"
+        data-biscuit-target="manageLink"
+        data-biscuit-position-value="<%= Biscuit.configuration.position %>"
+        data-action="click->biscuit#reopen"
+        hidden
+        aria-label="<%= t("biscuit.banner.reopen") %>">
+  <%= t("biscuit.banner.reopen") %>
+</button>

data/config/locales/en.yml

@@ -0,0 +1,24 @@
+en:
+  biscuit:
+    banner:
+      aria_label:  "Cookie consent"
+      message:     "We use cookies to improve your experience on this site."
+      learn_more:  "Learn more"
+      accept_all:  "Accept all"
+      reject_all:  "Reject non-essential"
+      manage:      "Manage preferences"
+      save:        "Save preferences"
+      reopen:      "Cookie settings"
+    categories:
+      necessary:
+        name:        "Necessary"
+        description: "Required for the site to function. Cannot be disabled."
+      analytics:
+        name:        "Analytics"
+        description: "Help us understand how visitors use the site."
+      marketing:
+        name:        "Marketing"
+        description: "Used to show personalised advertisements."
+      preferences:
+        name:        "Preferences"
+        description: "Remember your settings and personalisation choices."

data/config/locales/fr.yml

@@ -0,0 +1,24 @@
+fr:
+  biscuit:
+    banner:
+      aria_label:  "Consentement aux cookies"
+      message:     "Nous utilisons des cookies pour améliorer votre expérience sur ce site."
+      learn_more:  "En savoir plus"
+      accept_all:  "Tout accepter"
+      reject_all:  "Refuser les non-essentiels"
+      manage:      "Gérer les préférences"
+      save:        "Enregistrer les préférences"
+      reopen:      "Paramètres des cookies"
+    categories:
+      necessary:
+        name:        "Nécessaires"
+        description: "Indispensables au fonctionnement du site. Ne peuvent pas être désactivés."
+      analytics:
+        name:        "Analytiques"
+        description: "Nous aident à comprendre comment les visiteurs utilisent le site."
+      marketing:
+        name:        "Marketing"
+        description: "Utilisés pour afficher des publicités personnalisées."
+      preferences:
+        name:        "Préférences"
+        description: "Mémorisent vos paramètres et vos choix de personnalisation."

data/config/routes.rb

@@ -0,0 +1,4 @@
+Biscuit::Engine.routes.draw do
+  post   "/consent", to: "consent#update"
+  delete "/consent", to: "consent#destroy"
+end

data/lib/biscuit/configuration.rb

@@ -0,0 +1,48 @@
+module Biscuit
+  class Configuration
+    # Cookie categories. Each key is the category identifier (symbol).
+    # :necessary is always present and always true — cannot be disabled by the user.
+    # Additional categories are shown to the user and default to opt-out.
+    # Each category accepts:
+    #   required: true/false  — if true, shown as disabled/checked in the UI
+    attr_accessor :categories
+
+    # Name of the browser cookie storing consent state.
+    # Default: "biscuit_consent"
+    attr_accessor :cookie_name
+
+    # Consent cookie lifetime in days.
+    # Default: 365
+    attr_accessor :cookie_expires_days
+
+    # Cookie path. Default: "/"
+    attr_accessor :cookie_path
+
+    # Cookie domain. nil means current domain. Default: nil
+    attr_accessor :cookie_domain
+
+    # SameSite attribute. Default: "Lax"
+    attr_accessor :cookie_same_site
+
+    # Banner position: :bottom or :top. Default: :bottom
+    attr_accessor :position
+
+    # URL for the "Learn more" / privacy policy link. Default: "#"
+    attr_accessor :privacy_policy_url
+
+    def initialize
+      @categories = {
+        necessary:  { required: true },
+        analytics:  { required: false },
+        marketing:  { required: false }
+      }
+      @cookie_name         = "biscuit_consent"
+      @cookie_expires_days = 365
+      @cookie_path         = "/"
+      @cookie_domain       = nil
+      @cookie_same_site    = "Lax"
+      @position            = :bottom
+      @privacy_policy_url  = "#"
+    end
+  end
+end

data/lib/biscuit/consent.rb

@@ -0,0 +1,61 @@
+module Biscuit
+  class Consent
+    CURRENT_VERSION = 1
+
+    # cookies: ActionDispatch::Cookies::CookieJar
+    def initialize(cookies)
+      @cookies = cookies
+      @data    = self.class.parse(cookies[Biscuit.configuration.cookie_name])
+    end
+
+    # True if a valid consent decision has been recorded.
+    def given?
+      !@data.nil?
+    end
+
+    # True if the user has consented to this category.
+    # :necessary always returns true regardless of cookie state.
+    def allowed?(category)
+      return true if category.to_sym == :necessary
+      return false unless given?
+      @data.dig("categories", category.to_s) == true
+    end
+
+    # Write consent cookie to the jar.
+    def self.write(cookies, categories)
+      value  = build_value(categories)
+      config = Biscuit.configuration
+      cookies[config.cookie_name] = {
+        value:     value.to_json,
+        expires:   config.cookie_expires_days.days.from_now,
+        path:      config.cookie_path,
+        domain:    config.cookie_domain,
+        same_site: config.cookie_same_site,
+        httponly:  false   # Must be readable by JS for client-side consent checks
+      }
+    end
+
+    # Clear the consent cookie.
+    def self.clear(cookies)
+      cookies.delete(Biscuit.configuration.cookie_name)
+    end
+
+    # Build the cookie value hash. Always forces necessary: true.
+    def self.build_value(categories)
+      cats = categories.transform_keys(&:to_s)
+                       .transform_values { |v| v == true || v == "true" }
+      cats["necessary"] = true
+      { "v" => CURRENT_VERSION, "consented_at" => Time.now.utc.iso8601, "categories" => cats }
+    end
+
+    # Parse raw cookie string. Returns nil if blank, invalid JSON, or wrong version.
+    def self.parse(raw)
+      return nil if raw.blank?
+      data = JSON.parse(raw)
+      return nil unless data.is_a?(Hash) && data["v"] == CURRENT_VERSION && data["categories"].is_a?(Hash)
+      data
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/biscuit/engine.rb

@@ -0,0 +1,17 @@
+module Biscuit
+  class Engine < ::Rails::Engine
+    isolate_namespace Biscuit
+
+    # Make helper available in all host app views
+    initializer "biscuit.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include Biscuit::BiscuitHelper
+      end
+    end
+
+    # Register i18n locale files
+    initializer "biscuit.i18n" do
+      config.i18n.load_path += Dir[Engine.root.join("config/locales/*.yml")]
+    end
+  end
+end

data/lib/biscuit/rails.rb

@@ -0,0 +1 @@
+require "biscuit"

data/lib/biscuit/version.rb

@@ -0,0 +1,3 @@
+module Biscuit
+  VERSION = "0.1.1"
+end

data/lib/biscuit.rb

@@ -0,0 +1,20 @@
+require "biscuit/version"
+require "biscuit/configuration"
+require "biscuit/consent"
+require "biscuit/engine"
+
+module Biscuit
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: biscuit-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Gareth James
+bindir: bin
+cert_chain: []
+date: 2026-03-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Biscuit provides a configurable GDPR cookie consent banner for Rails
+  8+ applications. It manages consent state via a browser cookie, exposes a Stimulus
+  controller for interactivity, and supports i18n and CSS custom property theming
+  with no build step required.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/assets/javascripts/biscuit/biscuit_controller.js
+- app/assets/stylesheets/biscuit/biscuit.css
+- app/controllers/biscuit/consent_controller.rb
+- app/helpers/biscuit/biscuit_helper.rb
+- app/views/biscuit/banner/_banner.html.erb
+- config/locales/en.yml
+- config/locales/fr.yml
+- config/routes.rb
+- lib/biscuit.rb
+- lib/biscuit/configuration.rb
+- lib/biscuit/consent.rb
+- lib/biscuit/engine.rb
+- lib/biscuit/rails.rb
+- lib/biscuit/version.rb
+homepage: https://github.com/garethfr/biscuit-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://bemused.org/projects/biscuit-rails
+  source_code_uri: https://github.com/garethfr/biscuit-rails
+  changelog_uri: https://github.com/garethfr/biscuit-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/garethfr/biscuit-rails/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: GDPR-compliant cookie consent banner for Rails 8
+test_files: []