astro-consent 1.0.17 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to `astro-consent` will be documented in this file.
+
+The format follows a simple Keep a Changelog style, with semantic versioning.
+
+## [2.0.0] - 2026-04-01
+
+### Breaking
+
+- Changed the package to a major release after the CLI and integration workflow were expanded.
+- The installer now writes a marked `astro-consent` block into `astro.config.*` so `init` and `remove` can target only the plugin stanza.
+
+### Added
+
+- `init`, `remove`, `doctor`, and `status` CLI commands
+- `--dry-run` support for install and remove
+- `--json` output for `doctor` and `status`
+- `banner` and `overlay` presentation modes
+- Configurable display timing with `displayUntilIdle` and `displayIdleDelayMs`
+- Configurable copy with `headline`, `description`, `acceptLabel`, `rejectLabel`, and `manageLabel`
+- Separate `cookiePolicyUrl` and `privacyPolicyUrl` support with backwards-compatible `policyUrl` fallback
+- Overlay accessibility improvements, including focus trapping, `Escape` to close, and focus return
+- Generated editable stylesheet at `src/cookiebanner/styles.css`
+
+### Changed
+
+- Updated default copy to be more professional and concise
+- Improved banner and overlay motion and spacing
+- Reworked the README into a full onboarding guide
+- Updated package branding to `Velohost UK Limited`
+- Bumped the package major version to `2.0.0`
+
+### Fixed
+
+- Safer install and removal behavior for `astro.config.*`
+- Removed older CSS injection path in favor of a real generated stylesheet
+- Improved CLI diagnostics and install/status reporting

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Velohost
+Copyright (c) 2026 Velohost UK Limited
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,90 +1,52 @@
 # astro-consent
 
-A **privacy-first, zero-dependency cookie consent banner** for Astro projects — built for speed, compliance, and total visual control.
+`astro-consent` is a privacy-first cookie consent integration for Astro. It adds a polished consent banner or overlay, generates an editable stylesheet in your project, and exposes a tiny runtime API for managing stored consent.
 
-Designed and maintained by **Velohost**.
+## What You Get
 
----
+- A banner or overlay consent UI
+- A generated `src/cookiebanner/styles.css` file you can edit directly
+- Idle-based display with a configurable fade-in delay
+- Focus trapping, `Escape` to close, and focus return for the overlay
+- CLI setup, removal, and diagnostics commands
+- TypeScript support
+- Compatibility with Astro 4, 5, and 6
 
-## Why astro-consent?
+## Quick Start
 
-Most cookie consent solutions are bloated, opaque, or tied to third-party services.
-
-**astro-consent** is built differently:
-
-- No trackers  
-- No remote calls  
-- No analytics SDKs  
-- No vendor lock-in  
-- No runtime dependencies  
-
-Just a **fast, deterministic, developer-controlled consent layer** that respects user privacy and legal boundaries.
-
----
-
-## ✨ Features
-
-- ✅ GDPR / UK GDPR friendly
-- 🍪 Consent categories: Essential, Analytics, Marketing
-- 🎛️ Preferences modal with toggle switches
-- ⚡ Zero runtime dependencies
-- 🎨 Fully themeable via CSS variables
-- 🧠 Frontend-controlled script loading
-- 🧩 Native Astro integration
-- 🧾 Built-in TypeScript declarations
-- 🛠️ CLI installer & remover
-- 🔁 Clean uninstall with no residue
-- 🌍 Framework-agnostic frontend API
-
----
-
-## 📦 Installation (Required)
-
-This package uses **both an Astro integration and a CLI installer**.
-
-### 1️⃣ Install the package
+### 1. Install the package
 
 ```bash
 npm install astro-consent
 ```
 
-This step is **required** so Astro can import the integration at build time.
+### 2. Add the integration
 
----
-
-### 2️⃣ Run the installer
+Use the CLI to wire everything into your Astro project:
 
 ```bash
-npx astro-consent
+npx astro-consent init
 ```
 
-This will automatically:
+That will:
 
-- Inject the Astro integration into `astro.config.*`
-- Create `src/cookiebanner.css` for theme control
-- Enable the consent banner across your site
+- add `astro-consent` to `astro.config.*`
+- create `src/cookiebanner/styles.css` if it is missing
+- add a starter configuration block with placeholder values
 
-No manual wiring required.
+### 3. Edit the generated CSS
 
----
+Open `src/cookiebanner/styles.css` in your project and customize the banner or modal visually. The package does not inject CSS through JavaScript, so this file is the single source of truth for styling.
 
-### ❌ Uninstall
+### 4. Run your Astro app
 
 ```bash
-npx astro-consent remove
+npm run dev
 ```
 
-This cleanly removes:
-
-- The integration entry
-- Generated files
-- All banner logic
-
-No orphaned config. No hidden state.
-
----
+## Recommended Setup
 
-## 🔧 Astro Integration Usage
+The default install is designed to be easy to understand and safe to customise. A typical configuration looks like this:
 
 ```ts
 import astroConsent from "astro-consent";
@@ -93,108 +55,247 @@ export default {
   integrations: [
     astroConsent({
       siteName: "My Website",
-      policyUrl: "https://example.com/privacy-policy",
+      headline: "Manage cookie preferences for My Website",
+      description:
+        "We use cookies to improve site performance, measure traffic, and support marketing.",
+      acceptLabel: "Accept all",
+      rejectLabel: "Reject all",
+      manageLabel: "Manage preferences",
+      cookiePolicyUrl: "/cookie-policy",
+      privacyPolicyUrl: "/privacy",
+      displayUntilIdle: true,
+      displayIdleDelayMs: 1000,
+      presentation: "banner",
       consent: {
         days: 30,
-        storageKey: "astro-cookie-consent"
-      },
-      categories: {
-        analytics: false,
-        marketing: false
+        storageKey: "astro-consent"
       }
     })
   ]
 };
 ```
 
-### Configuration notes
+## CLI Commands
 
-- **policyUrl**  
-  A full, public URL to your Privacy or Cookie Policy page.  
-  This is linked directly from the consent banner.
+### `init`
 
-- **consent.days**  
-  How long (in days) consent is stored before the user is asked again.
+```bash
+npx astro-consent init
+```
 
-- **consent.storageKey**  
-  The `localStorage` key used to persist consent.  
-  You may change this freely if you need per-site or per-environment isolation.
+Adds the integration import and a marked configuration block to `astro.config.*`, then creates `src/cookiebanner/styles.css` if the file does not already exist.
 
-- **categories.analytics**  
-  Allows analytics scripts to load only after consent.  
-  Typical use: Plausible, self-hosted analytics, Google Analytics.
+### `remove`
 
-- **categories.marketing**  
-  Allows marketing and advertising scripts to load only after consent.  
-  Typical use: ad pixels, remarketing tags, embedded social trackers.
+```bash
+npx astro-consent remove
+```
 
-Scripts outside the **essential** category must be conditionally loaded.
+Removes the marked `astro-consent` block from `astro.config.*`, removes the import, and deletes `src/cookiebanner/styles.css` if it exists.
 
----
+### `doctor`
 
-## 🧠 Frontend API
+```bash
+npx astro-consent doctor
+```
 
-```js
-window.cookieConsent.get();
-window.cookieConsent.set({ essential: true, analytics: true });
-window.cookieConsent.reset();
+Checks the following:
+
+- Astro config import wiring
+- `astroConsent(...)` integration wiring
+- `src/cookiebanner/styles.css` existence
+- `src/layouts/BaseLayout.astro` importing the stylesheet
+
+Use JSON output for automation:
+
+```bash
+npx astro-consent doctor --json
 ```
 
-## 🧾 TypeScript
+### `status`
 
-TypeScript declarations are included in the package.
+```bash
+npx astro-consent status
+```
 
-No separate `@types` install is required.
+Reports the current install state:
 
----
+- whether the Astro config is wired
+- whether the stylesheet exists
+- whether the package is linked into `node_modules`
+- which consent storage key is configured
+- a note explaining that actual consent state is browser-side
 
-## 🎨 Theming
+JSON output is also available:
 
-All visuals are controlled via:
+```bash
+npx astro-consent status --json
+```
+
+### Dry Run
+
+Preview changes without writing files:
 
+```bash
+npx astro-consent init --dry-run
+npx astro-consent remove --dry-run
 ```
-src/cookiebanner.css
+
+## Presentation Modes
+
+You can choose how the consent UI appears:
+
+- `banner` for a standard bottom-of-page consent banner
+- `overlay` for a centered modal-first experience
+
+Example:
+
+```ts
+astroConsent({
+  presentation: "overlay"
+});
 ```
 
-You must ensure this file is included globally.
+## Display Timing
+
+The consent UI can wait until the browser is idle before appearing, then fade in after a short pause.
+
+### `displayUntilIdle`
+
+When `true`, the banner or overlay waits for browser idle before showing.
+
+### `displayIdleDelayMs`
 
-### Recommended import (Astro)
+Adds a delay after idle before the UI becomes visible.
 
-Import the stylesheet once in your main layout or entry file:
+Example:
 
 ```ts
-import "../cookiebanner.css";
+astroConsent({
+  displayUntilIdle: true,
+  displayIdleDelayMs: 1000
+});
+```
+
+## Copy Customisation
+
+These options let you tune the wording without editing the runtime:
+
+- `siteName` sets the site name used in fallback copy
+- `headline` sets the banner or dialog title
+- `description` sets the explanatory text
+- `acceptLabel` sets the primary action
+- `rejectLabel` sets the reject action
+- `manageLabel` sets the preferences action
+
+Example:
+
+```ts
+astroConsent({
+  siteName: "Escape Zone",
+  headline: "Manage cookie preferences for Escape Zone",
+  description:
+    "We use cookies to improve site performance, measure traffic, and support marketing.",
+  acceptLabel: "Accept all",
+  rejectLabel: "Reject all",
+  manageLabel: "Manage preferences"
+});
+```
+
+## Policy Links
+
+The consent UI supports separate links for cookie and privacy policy pages.
+
+- `cookiePolicyUrl` controls the cookie policy link
+- `privacyPolicyUrl` controls the privacy policy link
+
+If you still pass `policyUrl`, it will be used for both links as a backwards-compatible fallback.
+
+## Runtime API
+
+The integration exposes a small browser API on `window.astroConsent`:
+
+```js
+window.astroConsent.get();
+window.astroConsent.set({ essential: true, analytics: true, marketing: false });
+window.astroConsent.reset();
 ```
 
-This guarantees the banner styles are available on every page.
+- `get()` returns the stored consent object if one exists and is still valid
+- `set(...)` stores a new consent state
+- `reset()` clears consent and reloads the page
+
+## Styling
+
+The generated `src/cookiebanner/styles.css` file is meant to be edited directly.
+
+It uses `cb-*` custom properties so you can change the visual style without rewriting selectors. The most useful tokens are:
+
+- `--cb-bg`
+- `--cb-text`
+- `--cb-muted`
+- `--cb-border`
+- `--cb-accent`
+- `--cb-accent-strong`
+- `--cb-success`
+- `--cb-shadow`
+- `--cb-banner-radius`
+- `--cb-modal-width`
+- `--cb-button-bg`
+- `--cb-button-secondary-bg`
+
+## File Layout
+
+The installer creates the stylesheet here:
+
+```txt
+src/cookiebanner/styles.css
+```
 
-- This file is never overwritten
-- All colours, spacing, radius, and animations are controlled via CSS variables
-- Full visual control with zero JavaScript theming
+That file is intentionally local to your project. It is not injected from the package at runtime, which keeps styling under your control and avoids overwriting custom work.
 
----
+## Notes
 
-## 🔐 Privacy
+- Consent is stored in `localStorage`
+- The stored value expires after the configured TTL
+- Optional categories default to checked in the UI, but users can still reject them
+- The overlay uses accessible dialog behavior, including focus trapping, `Escape` to close, and focus return to the trigger
 
-- No cookies before consent
-- No tracking without permission
-- No external requests
-- Stored locally with TTL
+## Troubleshooting
 
----
+### The banner does not appear
 
-## 🙏 Acknowledgements
+Check the following:
 
-Thanks to [@magicspon](https://github.com/magicspon) for assisting with the PR and issue triage.
+1. `npx astro-consent init` has been run in the Astro project root
+2. `astro.config.*` includes the `astro-consent` integration
+3. `src/layouts/BaseLayout.astro` imports `../cookiebanner/styles.css`
+4. You have not already stored consent in `localStorage`
 
----
+### The CLI says the stylesheet is missing
+
+Run:
+
+```bash
+npx astro-consent init
+```
+
+### The CLI says the config is not wired
+
+Run:
+
+```bash
+npx astro-consent doctor
+```
 
-## 📄 License
+and follow the fix instructions it prints.
 
-MIT © Velohost
+## Why the Package Works This Way
 
----
+The design is intentionally simple:
 
-## 🏢 Velohost
+- the runtime handles consent logic and UI behavior
+- the generated stylesheet handles appearance
+- the CLI wires setup and removal cleanly
 
-https://velohost.co.uk/
+That separation keeps the plugin predictable, easier to debug, and safer to customise.