Consent preferences button appears in a page when it is explicity defined.

Author: koculu

frontend/purestack.studio/components/site/consent/consent.mdx

@@ -1,6 +1,6 @@
 ---
 title: Consent
-description: "A consent banner and preference panel driven by the site’s categories, policy version and service configuration."
+description: "Let visitors choose which optional cookies and services your site may use, and change their preferences later."
 template: doc
 layout:
   showNav: true
@@ -16,11 +16,66 @@ nav:
 <ComponentHeader
   name="Consent"
   kind="Privacy preferences"
-  summary="A consent banner and preference panel driven by the site’s categories, policy version and service configuration."
+  summary="Let visitors choose which optional cookies and services your site may use, and change their preferences later."
   source="https://github.com/PureStackStudio/PureStack/blob/main/packages/ts-components/src/standard/consent/consent.ts"
   section="Site navigation &amp; services"
   sectionHref="/components/site/"/>
 
+Consent gives visitors control over optional cookies and services, such as
+analytics or marketing. Its banner offers **Accept all**, **Reject non-essential**,
+and **Manage preferences**. The preferences panel lets visitors choose individual
+categories while required categories stay enabled.
+
+Consent remembers the saved choice and loads configured optional services only
+after permission is granted. Visitors can reopen preferences using either option
+above, change their choices, and save again.
+
+## Open privacy preferences
+
+With consent enabled in your site configuration, Consent is included
+automatically. Choose either of these two ways to let visitors reopen their
+preferences after making a choice.
+
+### 1. Use your own button or link
+
+Add `data-consent-action="open-panel"` to a `Btn` or `BtnLink` in your footer,
+navigation, or page content. Clicking it opens the privacy preferences panel.
+
+For a button:
+
+```html
+<Btn tone="neutral" variant="outline" data-consent-action="open-panel">
+  Manage privacy settings
+</Btn>
+```
+
+For a link:
+
+```html
+<BtnLink
+  href="/legal/privacy/"
+  tone="neutral"
+  variant="link"
+  data-consent-action="open-panel"
+>
+  Privacy settings
+</BtnLink>
+```
+
+### 2. Use the default teleport area
+
+Place this empty element where you want the default **Privacy settings** button
+to appear:
+
+```html
+<span class="consent-settings-teleport-area"></span>
+```
+
+Consent automatically places its settings button inside that element.
+SiteFooter already provides this area. If the area is absent, Consent does not
+add a settings button.
+
+
 ## Make and revise a choice
 
 This preview uses this site's real consent settings and shares its saved privacy choice. Open settings to review the configured categories.
@@ -124,47 +179,35 @@ Use the working example to open, save, close, and reopen this site's real privac
   </div>
 </ComponentExample>
 
-## Configuration and service activation
+## Configuration
 
 | Configuration | Visible role |
 | --- | --- |
 | enabled | Determines whether the component renders. |
-| storageKey, policyVersion | Keep the example separate and invalidate outdated choices. |
+| storageKey, policyVersion | Set where choices are saved and when visitors must make a fresh choice. |
 | categories | Give each category an ID, label, description, and required flag. |
-| services | Associate a service with its consent category; optional services wait for permission. The example uses no tracking services. |
+| services | Associate each optional service with the category that gives it permission to load. |
 | Banner, action, and settings labels | Customize the language of the banner, buttons, and preferences. |
 | privacyPolicyUrl, privacyPolicyLabel | Add the policy destination beside the banner copy. |
-| Footer settings target | The settings control teleports to .consent-settings-teleport-area. |
-
-Appearance galleries show the actual banner markup with every treatment. They are static comparisons; the isolated example above runs the full consent flow.
-
-## Feature map
-
-| Feature | Where to explore it |
-| --- | --- |
-| Banner choices, required and optional categories, saved settings, and services | Context preview, feature comparisons, and original copyable source examples. |
-| Public appearance options | Complete galleries above. Only options supported by this component are shown. |
-| Native semantics and integration | Behavior notes and API contracts below explain the component’s roots, slots, and runtime dependencies. |
-
-## Behavior and accessibility
 
-Consent renders only when site.consent.enabled is true. The runtime opens the banner when no current saved choice exists, persists choices under storageKey and uses policyVersion to identify the policy. Necessary categories remain selected. Keep labels and descriptions specific to the services your site actually runs.
+Keep category labels and descriptions specific to the services your site uses.
 
 ## API reference
 
 <div class="api-overview">
   <p class="text-eyebrow">Consent contract</p>
   <p>
-    The three public props style the component. Banner copy, categories,
-    storage, policy version and services come from site.consent, not markup
-    props.
+    Appearance props style the component; settingsTeleport places its settings
+    button. Banner copy, categories, storage, policy version and services come
+    from site.consent, not markup props.
   </p>
 </div>
 
 <nav class="api-index" aria-label="Consent properties">
   <a href="#consent-prop-tone">tone</a>
   <a href="#consent-prop-variant">variant</a>
   <a href="#consent-prop-variantMode">variantMode</a>
+  <a href="#consent-prop-settingsTeleport">settingsTeleport</a>
 </nav>
 
 <ApiProperty
@@ -204,28 +247,30 @@ Consent renders only when site.consent.enabled is true. The runtime opens the ba
   </p>
 </ApiProperty>
 
+<ApiProperty
+  anchor="consent-prop-settingsTeleport"
+  name="settingsTeleport"
+  valueType="string"
+  defaultValue=".consent-settings-teleport-area"
+>
+  <p>
+    CSS selector for the built-in settings button's destination. Provide the
+    target before Consent renders. An empty selector or a missing target omits
+    the button; the banner and preference panel remain available.
+  </p>
+</ApiProperty>
+
 ### Composition
 
 <div class="api-contract">
   <p>
-    No public slots. The settings button teleports to
-    .consent-settings-teleport-area, provided by SiteFooter or by your own
-    template. Register defineConsentComponents with Panel, Flex, Btn, BtnLink
-    and FormCheck. Include the standard consent runtime with the same resolved
-    configuration.
+    Consent is included automatically when enabled. Use a Btn or BtnLink with
+    data-consent-action="open-panel" to open preferences, or provide
+    .consent-settings-teleport-area for the default settings button. No public
+    slots.
   </p>
 </div>
 
-### Configuration responsibilities
-
-- `enabled` controls whether the component exists.
-- `storageKey` isolates saved choices; `policyVersion` identifies the current policy.
-- `categories` define IDs, visible labels, descriptions and required state.
-- `services` describe the services controlled by those categories.
-- Banner, button and policy-link copy belong in the consent configuration.
-
-The preview source shows the complete scoped override used by the working example.
-
 ## Related components
 
 - [SiteFooter](/components/site/site-footer/)

frontend/purestack.studio/components/site/consent/preview.mdx

@@ -8,7 +8,17 @@ title: consent preview
   title="Privacy settings example"
   titleTag="h2"
   subtitle="Make a choice, then reopen settings to change it."/>
-<div class="consent-settings-teleport-area"></div>
-<Consent/>
-<Btn variant="outline" class="mt-3" data-consent-open
-  >Manage privacy settings</Btn>
+<Consent settingsTeleport=""/>
+<Flex wrap="true" class="mt-3">
+  <Btn tone="neutral" variant="outline" data-consent-action="open-panel">
+    Manage privacy settings
+  </Btn>
+  <BtnLink
+    href="/legal/privacy/"
+    tone="neutral"
+    variant="link"
+    data-consent-action="open-panel"
+  >
+    Privacy settings
+  </BtnLink>
+</Flex>

frontend/purestack.studio/components/site/page-toc/_playground.mdx

@@ -3,7 +3,3 @@
   class="d-block min-w-0"
   data-toc-playground
   src="./app.ts"/>
-<noscript
-  >Enable JavaScript to try client refresh. The rest of this guide works without
-  it.</noscript>
-<span class="consent-settings-teleport-area hidden"></span>

package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "purestack-repo",
-  "version": "1.1.27",
+  "version": "1.1.28",
   "packageManager": "yarn@4.18.1",
   "type": "module",
   "sideEffects": false,

packages/purestack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purestack",
-  "version": "1.1.27",
+  "version": "1.1.28",
   "packageManager": "yarn@4.9.2",
   "module": "./dist/purestack.mjs",
   "types": "./dist/purestack.d.mts",

packages/purestack/src/index.ts

@@ -1,3 +1,3 @@
-export const version: string = '1.1.27'
+export const version: string = '1.1.28'
 
 export * from '@purestack/ts-ssg'

packages/ts-common/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purestack/ts-common",
-  "version": "1.1.27",
+  "version": "1.1.28",
   "packageManager": "yarn@4.9.2",
   "module": "./dist/ts-common.mjs",
   "types": "./dist/ts-common.d.mts",

packages/ts-components/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purestack/ts-components",
-  "version": "1.1.27",
+  "version": "1.1.28",
   "packageManager": "yarn@4.9.2",
   "module": "./dist/ts-components.mjs",
   "types": "./dist/ts-components.d.mts",

packages/ts-components/src/standard/consent/consent.test.ts

@@ -1,6 +1,6 @@
 import { ensureDomGlobals } from '@purestack/ts-minidom'
 import { renderApp } from '@purestack/ts-render'
-import { describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { createTestContext } from '../../test/testContext'
 import { defineButtonComponents } from '../btn/btn'
 import { defineFlexComponents } from '../flex/flex'
@@ -9,8 +9,13 @@ import { definePanelComponents } from '../panel/panel'
 import { defineConsentComponents } from './consent'
 
 describe('Consent component rendering', () => {
+  let cleanup: () => void
+  beforeEach(() => {
+    cleanup = ensureDomGlobals()
+  })
+  afterEach(() => cleanup())
+
   it('renders consent shell and categories when enabled', async () => {
-    const cleanup = ensureDomGlobals()
     const components = {
       ...defineButtonComponents(),
       ...defineFlexComponents(),
@@ -39,14 +44,49 @@ describe('Consent component rendering', () => {
         },
       }),
     })
-    cleanup()
 
     expect(html).toContain('data-consent-root')
     expect(html).toContain('data-consent-banner')
     expect(html).toContain('data-consent-panel')
-    expect(html).toContain('data-consent-settings')
+    expect(html).not.toContain('data-consent-settings')
     expect(html).toContain('data-consent-category-id="necessary"')
     expect(html).toContain('data-consent-category-id="analytics"')
     expect(html).toContain('Reject non-essential')
   })
+
+  it.each([
+    ['<Consent />', '.consent-settings-teleport-area', true],
+    ['<Consent settingsTeleport="#privacy" />', '#privacy', true],
+    ['<Consent settingsTeleport="#missing" />', '#privacy', false],
+    [
+      '<Consent settingsTeleport="" />',
+      '.consent-settings-teleport-area',
+      false,
+    ],
+  ])(
+    'renders settings only at an available target: %s',
+    async (markup, target, expected) => {
+      const html = await renderApp(
+        `<div ${target.startsWith('#') ? `id="${target.slice(1)}"` : `class="${target.slice(1)}"`}></div>${markup}`,
+        {
+          components: {
+            ...defineButtonComponents(),
+            ...defineFlexComponents(),
+            ...defineFormComponents(),
+            ...definePanelComponents(),
+            ...defineConsentComponents(),
+          },
+          context: createTestContext({ site: { consent: { enabled: true } } }),
+          onRendered(document) {
+            const button = document.querySelector('[data-consent-settings]')
+            expect(!!button).toBe(expected)
+            if (expected) {
+              expect(button?.parentElement).toBe(document.querySelector(target))
+            }
+          },
+        },
+      )
+      expect(html).toContain('data-consent-panel')
+    },
+  )
 })

packages/ts-components/src/standard/consent/consent.ts

@@ -16,6 +16,7 @@ export interface ConsentCategoryState extends ConsentCategory {
 }
 
 export interface Consent extends Partial<ConsentConfig> {
+  /** Settings button target selector. Empty or unmatched selectors omit the button. */
   settingsTeleport?: string
   categories: ConsentCategoryState[]
   tone?: RefOrValue<SemanticTone>
@@ -130,6 +131,7 @@ const consentTemplate = html`<section class="consent" data-consent-root r-if="en
   </section>
 
   <Btn
+    r-if="settingsTeleport && hasSettingsTarget()"
     tone="ghost"
     size="sm"
     data-consent-settings
@@ -143,16 +145,18 @@ const consentTemplate = html`<section class="consent" data-consent-root r-if="en
 
 function defineConsentComponent() {
   return defineComponent<Consent>(consentTemplate, {
-    props: ['tone', 'variant', 'variantMode'],
+    props: ['tone', 'variant', 'variantMode', 'settingsTeleport'],
     context: (head) => resolveConsent(resolvePageContext(head), head.props),
   })
 }
 
 function resolveConsent(
   context: PageContext,
   props: Partial<Consent>,
-): Consent {
+): Consent & { hasSettingsTarget: () => boolean } {
   const consent = context.site.consent
+  const settingsTeleport =
+    props.settingsTeleport ?? '.consent-settings-teleport-area'
   const categories = (consent?.categories ?? []).map((category) => ({
     id: category.id,
     label: category.label,
@@ -165,7 +169,8 @@ function resolveConsent(
     tone: props.tone,
     variant: props.variant,
     variantMode: props.variantMode,
-    settingsTeleport: '.consent-settings-teleport-area',
+    settingsTeleport,
+    hasSettingsTarget: () => !!document.querySelector(settingsTeleport),
     categories,
   }
 }