rails_consent 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 19e1554e153f613453261717b4d18b77bc83664efe9e35fb178553d45802ad97
+  data.tar.gz: df90bf179fe78aab0df69a290aa097c40bdedc21295d24523e6db492e53bd7be
+SHA512:
+  metadata.gz: 35f2aaa9ed70c1a70e79769b0f45d03be70bddf0abf3e3ff9e5441867a6c1ddc8ef7d7c51c56dc6aa8547ddaf911a616f1083ebdb7f519e3893267f8e9cf2d1b
+  data.tar.gz: 24b811e64f10bdaaf9aab27aa48a130430caf7fb93576b99a07bb1b1a527eac8fe54b15453f1718c8ade2ab3538d437d02d568289d49d08d4b18d11ab3c8d6b8

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## Unreleased
+
+- Relaxed the development baseline to Ruby 3.4.7 and Rails 7.1+
+- Simplified the gem contract so consent persistence stays in the host application
+- Refreshed the documentation application into a richer documentation-first Rails app with enhanced live consent demos
+
+## 0.1.0
+
+- Initial release of `rails_consent`
+- Added the Rails Engine, helpers, generators, templates, JavaScript runtime, specs, and the documentation application

data/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Thanks for considering a contribution to `rails_consent`.
+
+## Development Setup
+
+1. Install the bundle:
+
+   ```bash
+   bundle install
+   ```
+
+2. Run the test suite:
+
+   ```bash
+   bundle exec rspec
+   ```
+
+3. Verify changes against the public documentation site and reference integration before opening a pull request.
+
+## Contribution Guidelines
+
+- Keep consent behavior in the library and presentation choices in the host app whenever possible.
+- Add or update specs around the public contract of the gem.
+- Favor extension points over one-off conditionals.
+- Avoid introducing database persistence to the gem itself.
+- Update documentation and examples when public behavior changes.
+
+## Pull Requests
+
+Please include:
+
+- A clear description of the problem and the chosen solution
+- Tests covering the public behavior you changed
+- Documentation updates when relevant

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhairya Gabhawala
+
+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,264 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dhairyagabha/rails_consent/main/.github/assets/rails-consent-lockup.png" alt="Rails Consent" width="420">
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/rails_consent">
+    <img src="https://img.shields.io/gem/v/rails_consent.svg" alt="RubyGems version">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://rails-consent.dhairyagabhawala.com">Documentation</a>
+  ·
+  <a href="https://rails-consent.dhairyagabhawala.com/docs/example-integrations">See the demo</a>
+  ·
+  <a href="https://github.com/dhairyagabha/rails_consent/blob/main/CHANGELOG.md">Changelog</a>
+  ·
+  <a href="https://rubygems.org/gems/rails_consent">RubyGems</a>
+  ·
+  <a href="https://github.com/dhairyagabha/rails_consent">GitHub</a>
+</p>
+
+# Rails Consent
+
+`rails_consent` is a Rails engine for cookie consent in Rails applications, built around locale-backed categories, a built-in signed cookie flow, small helper APIs, and a minimal JavaScript runtime.
+
+## Features
+
+- Cookie consent banner and preferences modal
+- Built-in signed cookie persistence with optional `:db` storage hooks
+- Locale-backed category definitions and interface copy
+- Helpers for views, controllers, and layouts
+- Minimal browser runtime with lifecycle events and a small client-side API
+- Overrideable templates without copying runtime assets
+- Importmap and Turbo-friendly integration
+
+## Installation
+
+Add the gem to your Rails app:
+
+```ruby
+gem "rails_consent"
+```
+
+Then install it:
+
+```bash
+bundle install
+bin/rails generate rails_consent:install
+```
+
+The installer creates:
+
+- `config/initializers/rails_consent.rb`
+- `config/locales/rails_consent.en.yml`
+
+In the default `:cookie` mode, that generated setup is enough to render the UI and persist consent through a signed Rails cookie.
+
+## Define Categories and Copy
+
+Rails Consent keeps banner copy, modal copy, and category definitions in one locale file:
+
+```yaml
+en:
+  rails_consent:
+    banner:
+      eyebrow: Privacy settings
+      title: Review cookie choices
+      description: Necessary cookies stay enabled. Optional categories can be updated at any time.
+      accept_all: Allow all
+      reject_optional: Reject optional
+      manage_preferences: Privacy preferences
+    modal:
+      eyebrow: Cookie preferences
+      title: Review cookie categories
+      save_preferences: Save settings
+    categories:
+      necessary:
+        label: Necessary
+        required: true
+        description: Essential cookies required for site functionality
+      analytics:
+        label: Analytics
+        required: false
+        description: Used to understand visitor behavior
+      marketing:
+        label: Marketing
+        required: false
+        description: Used for advertising and remarketing
+```
+
+Display order follows the locale file order.
+
+## Configure Rails Consent
+
+The initializer defines where consent lives, how the banner behaves by default, and how category checks should resolve:
+
+```ruby
+RailsConsent.configure do |config|
+  config.storage = :cookie
+  config.banner_position = :bottom
+  config.prompt_dismissible = true
+  config.cookie_name = "rails_consent_preferences"
+  config.cookie_expiration_days = 180
+  # config.cookie_same_site = :lax
+  # config.cookie_http_only = true
+  # config.cookie_secure = ->(request) { request.ssl? || Rails.env.production? }
+  config.consent_resolver = RailsConsent::DefaultConsentResolver.new
+end
+```
+
+`consent_resolver` is required. Start with `RailsConsent::DefaultConsentResolver.new` when each optional category maps directly to a boolean consent decision, then replace it when your application needs additional rules.
+
+## Render the Consent UI
+
+Load the gem assets in your layout and keep the banner mounted near the bottom of the page:
+
+```erb
+<head>
+  <%= rails_consent_assets %>
+</head>
+
+<body>
+  <%= yield %>
+  <%= rails_consent_banner %>
+</body>
+```
+
+`rails_consent_assets` loads only the gem's core runtime assets: `rails_consent.js` and the minimal `rails_consent/application.css` stylesheet used for runtime visibility utilities.
+
+If one page needs different behavior, override it locally:
+
+```erb
+<%= rails_consent_banner position: :top, dismissible: false %>
+```
+
+## Reopen Preferences Later
+
+Use the shared helper anywhere you want to reopen the preferences modal:
+
+```erb
+<%= rails_consent_preferences_button "Privacy preferences", class: "footer-button" %>
+```
+
+That helper is a good fit for footers, privacy pages, and account settings screens.
+
+## Gate Optional Behavior
+
+Use `consent_given?` anywhere you need to align server-rendered behavior with the current consent state:
+
+```erb
+<% if consent_given?(:analytics) %>
+  <%= render "analytics_script" %>
+<% end %>
+```
+
+The public helper surface is:
+
+```ruby
+rails_consent_assets
+rails_consent_banner
+rails_consent_preferences_button
+consent_given?(:analytics)
+consent_preferences
+consent_recorded?
+reset_consent!
+```
+
+## Client-side API
+
+Rails Consent also exposes a small browser API through `window.RailsConsent`:
+
+```javascript
+window.RailsConsent.preferences()
+window.RailsConsent.consentGiven("analytics")
+window.RailsConsent.consentRecorded()
+window.RailsConsent.sessionId()
+window.RailsConsent.openPreferences()
+```
+
+Lifecycle events are dispatched on `document` so host apps can react without modifying the gem runtime:
+
+- `rails-consent:banner-shown`
+- `rails-consent:preferences-opened`
+- `rails-consent:preferences-saved`
+- `rails-consent:preferences-updated`
+- `rails-consent:accepted-all`
+- `rails-consent:rejected-optional`
+- `rails-consent:dismissed`
+
+## Storage Modes
+
+### Signed Cookie Storage
+
+`config.storage = :cookie` uses the built-in persistence route and a signed cookie payload keyed by category name. This is the default integration path.
+
+If you want to wrap the built-in cookie flow without replacing it, provide `cookie_reader`, `cookie_writer`, or `cookie_destroyer` hooks around `RailsConsent::CookieStore`.
+
+### Database-backed Storage
+
+When consent should live alongside a user or account record, switch only the storage hooks:
+
+```ruby
+RailsConsent.configure do |config|
+  config.storage = :db
+  config.banner_position = :bottom
+  config.prompt_dismissible = true
+  config.consent_resolver = RailsConsent::DefaultConsentResolver.new
+
+  config.preferences_provider = ->(context:, **) do
+    context.current_user&.consent_preferences || {}
+  end
+
+  config.preferences_writer = ->(preferences:, context:, **) do
+    user = context.current_user
+    raise "current_user is required for db-backed consent" unless user
+
+    user.update!(consent_preferences: preferences)
+    user.consent_preferences
+  end
+
+  config.preferences_destroyer = ->(context:, **) do
+    context.current_user&.update!(consent_preferences: {})
+  end
+end
+```
+
+Most applications pair that initializer with a JSON or JSONB column such as `users.consent_preferences`.
+
+## Customize Presentation
+
+Override any shipped partial from your host app by creating:
+
+```text
+app/views/rails_consent/_banner.html.erb
+app/views/rails_consent/_preferences_modal.html.erb
+app/views/rails_consent/_category_toggle.html.erb
+app/views/rails_consent/_cookie_table.html.erb
+```
+
+Keep wording changes in locale YAML when the markup stays the same. Reach for template overrides only when the structure itself needs to change.
+
+## Troubleshooting
+
+- If the banner never appears, confirm `rails_consent_banner` is mounted in your layout and consent has not already been recorded.
+- If the UI opens without styles or behavior, confirm `rails_consent_assets` is loaded in `<head>`.
+- If boot fails with a configuration error, compare your initializer to the generated file and restore any required lines that were removed.
+- If a custom category never enables, review `consent_resolver` after changing `config/locales/rails_consent.en.yml`.
+- If `:db` mode does not persist updates, confirm `preferences_provider`, `preferences_writer`, and `preferences_destroyer` are all configured and return hashes keyed by category name.
+- If client-side integrations cannot read consent, keep `rails_consent_banner` mounted on the page so `window.RailsConsent` has a rendered boundary to read from.
+
+## Documentation
+
+Full guides, live demos, and integration examples are available at:
+
+- https://rails-consent.dhairyagabhawala.com/
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development and contribution guidelines.
+
+## License
+
+Released under the MIT license. See [`LICENSE`](LICENSE).

data/app/assets/config/rails_consent_manifest.js

@@ -0,0 +1,2 @@
+//= link rails_consent/application.css
+//= link rails_consent.js