@stacksjs/defaults 0.74.40 → 0.74.42

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.40",
+  "version": "0.74.42",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.74.40",
+    "@stacksjs/mobile": "^0.74.42",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }

package/resources/components/CookieConsent.stx

@@ -0,0 +1,146 @@
+<script client>
+/**
+ * Cookie consent banner (stacksjs/stacks#365).
+ *
+ * The decision logic is `useCookieConsent` in `@stacksjs/composables`, which
+ * is where the rule that matters lives: every optional category is declined
+ * until the visitor says otherwise, and there is no way to ask for a
+ * permissive default.
+ *
+ * This is the surface. Three things about it are compliance decisions rather
+ * than design ones, and each is easy to get wrong:
+ *
+ * - **"Decline" is as prominent as "Accept".** A banner where refusing is a
+ *   greyed-out link and accepting is the primary button is the pattern
+ *   regulators call out, and it is what most implementations ship.
+ * - **Nothing is preselected.** The per-category toggles start off, because
+ *   the stored decision starts empty.
+ * - **The banner does not block the page.** It is a dialog in the
+ *   accessibility sense but not a modal that traps the visitor until they
+ *   choose - consent obtained by making the site unusable is not freely given.
+ *
+ * `onChange` is where an app loads what a category gates, and where it records
+ * a `ConsentEvent` if it wants the audit trail.
+ */
+
+import type { ConsentCategory } from '@stacksjs/composables'
+import { useCookieConsent } from '@stacksjs/composables'
+
+interface CookieConsentProps {
+  /**
+   * Bump this when the cookie policy changes. Every stored decision under a
+   * previous version is discarded and the banner asks again, because consent
+   * to a previous policy is not consent to this one.
+   * @default '1.0'
+   */
+  policyVersion?: string
+  /** Where "read our policy" points. */
+  policyUrl?: string
+  /** Heading text. */
+  title?: string
+  /** Body text. Keep it about what is collected and why. */
+  message?: string
+}
+
+const {
+  policyVersion = '1.0',
+  policyUrl = '/privacy',
+  title = 'Cookies',
+  message = 'We use necessary cookies to make this site work. With your permission we would also like to use optional ones to understand how it is used and to improve it.',
+} = defineProps<CookieConsentProps>()
+
+const { needsDecision, allows, acceptAll, declineAll, accept } = useCookieConsent({ policyVersion })
+
+// Per-category toggles for the "choose" panel, starting from what is actually
+// consented - which on a first visit is nothing.
+const showChoices = state(false)
+const preferences = state(allows('preferences'))
+const analytics = state(allows('analytics'))
+const marketing = state(allows('marketing'))
+
+function saveChoices() {
+  const chosen: ConsentCategory[] = []
+  if (preferences()) chosen.push('preferences')
+  if (analytics()) chosen.push('analytics')
+  if (marketing()) chosen.push('marketing')
+  accept(chosen)
+}
+</script>
+
+<template>
+  @if(needsDecision)
+    <div
+      role="region"
+      aria-label="Cookie consent"
+      class="fixed bottom-0 inset-x-0 z-50 p-4 sm:p-6"
+    >
+      <div class="mx-auto max-w-3xl rounded-lg border border-gray-200 bg-white p-4 shadow-lg dark:border-neutral-700 dark:bg-neutral-900 sm:p-6">
+        <h2 class="text-base font-semibold text-gray-900 dark:text-white">{{ title }}</h2>
+
+        <p class="mt-2 text-sm text-gray-600 dark:text-neutral-300">
+          {{ message }}
+          <a :href="policyUrl" class="underline hover:no-underline">Read our policy</a>.
+        </p>
+
+        @if(showChoices())
+          <fieldset class="mt-4 space-y-3">
+            <legend class="sr-only">Cookie categories</legend>
+
+            <label class="flex items-start gap-3 text-sm">
+              <input type="checkbox" checked disabled class="mt-0.5" />
+              <span>
+                <span class="font-medium text-gray-900 dark:text-white">Necessary</span>
+                <span class="block text-gray-600 dark:text-neutral-400">Required for the site to work. Cannot be turned off.</span>
+              </span>
+            </label>
+
+            <label class="flex items-start gap-3 text-sm">
+              <input type="checkbox" :checked="preferences()" @change="preferences.set(!preferences())" class="mt-0.5" />
+              <span>
+                <span class="font-medium text-gray-900 dark:text-white">Preferences</span>
+                <span class="block text-gray-600 dark:text-neutral-400">Remembers choices such as language and theme.</span>
+              </span>
+            </label>
+
+            <label class="flex items-start gap-3 text-sm">
+              <input type="checkbox" :checked="analytics()" @change="analytics.set(!analytics())" class="mt-0.5" />
+              <span>
+                <span class="font-medium text-gray-900 dark:text-white">Analytics</span>
+                <span class="block text-gray-600 dark:text-neutral-400">Helps us understand how the site is used.</span>
+              </span>
+            </label>
+
+            <label class="flex items-start gap-3 text-sm">
+              <input type="checkbox" :checked="marketing()" @change="marketing.set(!marketing())" class="mt-0.5" />
+              <span>
+                <span class="font-medium text-gray-900 dark:text-white">Marketing</span>
+                <span class="block text-gray-600 dark:text-neutral-400">Used to measure and target campaigns.</span>
+              </span>
+            </label>
+          </fieldset>
+        @endif
+
+        {{-- Decline is a peer of Accept, not a lesser link. --}}
+        <div class="mt-4 flex flex-col gap-2 sm:flex-row sm:justify-end">
+          @if(showChoices())
+            <button type="button" @click="saveChoices()" class="rounded-md bg-gray-900 px-4 py-2 text-sm font-medium text-white hover:bg-gray-700 dark:bg-white dark:text-gray-900 dark:hover:bg-neutral-200">
+              Save choices
+            </button>
+          @else
+            <button type="button" @click="showChoices.set(true)" class="rounded-md border border-gray-300 px-4 py-2 text-sm font-medium text-gray-900 hover:bg-gray-50 dark:border-neutral-600 dark:text-white dark:hover:bg-neutral-800">
+              Choose
+            </button>
+          @endif
+
+          <button type="button" @click="declineAll()" class="rounded-md border border-gray-300 px-4 py-2 text-sm font-medium text-gray-900 hover:bg-gray-50 dark:border-neutral-600 dark:text-white dark:hover:bg-neutral-800">
+            Decline
+          </button>
+
+          <button type="button" @click="acceptAll()" class="rounded-md border border-gray-300 px-4 py-2 text-sm font-medium text-gray-900 hover:bg-gray-50 dark:border-neutral-600 dark:text-white dark:hover:bg-neutral-800">
+            Accept all
+          </button>
+        </div>
+      </div>
+    </div>
+  @endif
+</template>

package/resources/components/CookieConsent.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The banner's compliance contract (stacksjs/stacks#365).
+ *
+ * These are the properties a reviewer would check, and each is the kind of
+ * thing a later styling pass removes without noticing: the decline button
+ * becomes a text link, a checkbox picks up `checked`, the banner gains a
+ * backdrop. Asserted against the source because they are facts about the
+ * markup, not about the render.
+ *
+ * The decision logic itself is tested in
+ * `core/composables/tests/use-cookie-consent.test.ts`.
+ */
+
+const source = readFileSync(join(import.meta.dir, 'CookieConsent.stx'), 'utf8')
+
+describe('CookieConsent', () => {
+  it('gives Decline the same treatment as Accept', () => {
+    // A banner where refusing is a greyed-out link and accepting is the
+    // primary button is the pattern regulators call out.
+    const classesOf = (label: string): string => {
+      const match = source.match(new RegExp(`<button[^>]*class="([^"]*)"[^>]*>\\s*${label}`, 's'))
+        ?? source.match(new RegExp(`<button[^>]*class="([^"]*)"[^>]*>\\s*\\n\\s*${label}`, 's'))
+      return match?.[1] ?? ''
+    }
+
+    const decline = classesOf('Decline')
+    const accept = classesOf('Accept all')
+
+    expect(decline).not.toBe('')
+    expect(decline).toBe(accept)
+  })
+
+  it('preselects no optional category', () => {
+    // Every optional checkbox binds to state that starts from what is
+    // consented, which on a first visit is nothing. A literal `checked` on one
+    // of them would silently opt the visitor in.
+    const optional = [...source.matchAll(/<input type="checkbox"([^>]*)\/>/g)]
+      .map(match => match[1]!)
+      .filter(attrs => !attrs.includes('disabled'))
+
+    expect(optional.length).toBe(3)
+    for (const attrs of optional) {
+      expect(attrs).toContain(':checked=')
+      expect(attrs).not.toMatch(/\schecked[\s/]/)
+    }
+  })
+
+  it('marks the necessary category as checked AND disabled', () => {
+    // It cannot be declined, so showing it as a live choice would be a lie.
+    expect(source).toMatch(/<input type="checkbox" checked disabled/)
+  })
+
+  it('does not trap the visitor in a modal', () => {
+    // Consent obtained by making the site unusable is not freely given, so
+    // this is a region rather than a modal dialog with a backdrop.
+    expect(source).toContain('role="region"')
+    expect(source).not.toContain('role="dialog"')
+    expect(source).not.toContain('aria-modal')
+  })
+
+  it('labels the region and the category group for screen readers', () => {
+    expect(source).toContain('aria-label="Cookie consent"')
+    expect(source).toContain('<legend class="sr-only">')
+  })
+
+  it('links to the policy', () => {
+    expect(source).toContain(':href="policyUrl"')
+  })
+
+  it('renders nothing once a decision exists', () => {
+    // The whole banner is behind `needsDecision`; a visitor who has decided
+    // must not see it again on every page.
+    expect(source).toMatch(/@if\(needsDecision\)/)
+  })
+})