@sondor-technology/sondor-components 1.0.8 → 1.0.10

package/src/components/consent/consent.ts

@@ -0,0 +1,312 @@
+import {LitElement, html, css, nothing, PropertyValues} from "lit";
+import {customElement, property, state} from "lit/decorators.js";
+import {resetStyles} from "../../styles/reset.js";
+import "../button/button.js";
+import "../switch/switch.js";
+import {
+  ConsentCategory,
+  ConsentChoices,
+  ConsentRecord,
+  DEFAULT_CATEGORIES,
+  DEFAULT_STORAGE_KEY,
+  choicesFor,
+  isRecordValid,
+  normaliseChoices,
+  readRecord,
+  writeRecord,
+} from "./consent.utils.js";
+
+export type ConsentSource = "accept-all" | "reject-all" | "custom";
+
+/**
+ * A cookie and tracking consent banner. Visitors can accept all, reject all, or choose by
+ * category. Accept and reject are shown as equals, nothing is pre-selected, and the choice can be
+ * changed later from any element carrying a `data-consent-open` attribute (such as a footer link).
+ *
+ * It does not load or block scripts itself. Listen for the events, or call `getConsent()`, and
+ * only start analytics or marketing tools the visitor has allowed.
+ *
+ * Slots: default (the message shown on the banner).
+ * Events:
+ *  - `st-consent-ready` `{choices}`: a valid saved choice was found on load.
+ *  - `st-consent-change` `{choices, source}`: the visitor made a choice.
+ */
+@customElement("st-consent")
+export class StConsent extends LitElement {
+  @property({type: Array}) categories: ConsentCategory[] = DEFAULT_CATEGORIES;
+  @property({type: String, attribute: "storage-key"}) storageKey = DEFAULT_STORAGE_KEY;
+  /** Change this when what you collect changes, to ask every visitor again. */
+  @property({type: String}) version = "1";
+  /** How long a choice is remembered, in days. */
+  @property({type: Number, attribute: "expires-days"}) expiresDays = 180;
+  @property({type: String}) heading = "Your privacy choices";
+  @property({type: String, attribute: "policy-href"}) policyHref = "";
+  @property({type: String, attribute: "policy-label"}) policyLabel = "Read our cookie policy";
+  @property({type: String, attribute: "accept-label"}) acceptLabel = "Accept all";
+  @property({type: String, attribute: "reject-label"}) rejectLabel = "Reject all";
+  @property({type: String, attribute: "customise-label"}) customiseLabel = "Customise";
+  @property({type: String, attribute: "save-label"}) saveLabel = "Save choices";
+
+  @state() private _open = false;
+  @state() private _view: "summary" | "preferences" = "summary";
+  @state() private _draft: ConsentChoices = {};
+  @state() private _record: ConsentRecord | null = null;
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        position: fixed;
+        inset: auto 0 0 0;
+        z-index: var(--st-consent-z, 1000);
+        display: flex;
+        justify-content: center;
+        padding: var(--st-spacing-md);
+        pointer-events: none;
+      }
+
+      .panel {
+        pointer-events: auto;
+        width: 100%;
+        max-width: 40rem;
+        max-height: calc(100dvh - 2 * var(--st-spacing-md));
+        overflow-y: auto;
+        padding: var(--st-spacing-lg);
+        border: 1px solid var(--st-color-border);
+        border-radius: var(--st-radius-lg);
+        background: var(--st-color-surface);
+        color: var(--st-color-text);
+        box-shadow: var(--st-shadow-xl);
+      }
+
+      h2 {
+        margin: 0 0 var(--st-spacing-sm);
+        font-size: var(--st-font-size-lg);
+      }
+
+      h2:focus {
+        outline: none;
+      }
+
+      .message {
+        margin: 0 0 var(--st-spacing-md);
+        color: var(--st-color-text-muted);
+        font-size: var(--st-font-size-sm);
+      }
+
+      .message a,
+      .policy {
+        color: var(--st-color-primary-text);
+      }
+
+      .actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--st-spacing-sm);
+      }
+
+      /* Accept and reject share one width so neither is easier to press. */
+      .actions .decision {
+        flex: 1 1 8rem;
+      }
+
+      .categories {
+        display: grid;
+        gap: var(--st-spacing-md);
+        margin: 0 0 var(--st-spacing-md);
+        padding: 0;
+        list-style: none;
+      }
+
+      .category {
+        padding-bottom: var(--st-spacing-md);
+        border-bottom: 1px solid var(--st-color-border);
+      }
+
+      .category p {
+        margin: var(--st-spacing-xs) 0 0;
+        color: var(--st-color-text-muted);
+        font-size: var(--st-font-size-sm);
+      }
+
+      .required {
+        color: var(--st-color-text-muted);
+        font-size: var(--st-font-size-sm);
+      }
+
+      [hidden] {
+        display: none !important;
+      }
+
+      @media print {
+        :host {
+          display: none;
+        }
+      }
+    `,
+  ];
+
+  /** The saved choices, or null until the visitor has chosen. */
+  get choices(): ConsentChoices | null {
+    return this._record?.choices ?? null;
+  }
+
+  /** Whether the visitor allowed a category. False until they choose. */
+  allows(id: string): boolean {
+    return this._record?.choices[id] === true;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    document.addEventListener("click", this._onDocumentClick);
+    document.addEventListener("keydown", this._onKeydown);
+    this._load();
+  }
+
+  disconnectedCallback() {
+    document.removeEventListener("click", this._onDocumentClick);
+    document.removeEventListener("keydown", this._onKeydown);
+    super.disconnectedCallback();
+  }
+
+  protected willUpdate(changed: PropertyValues<this>) {
+    // Never leave the visitor with a stale choice when the categories or version change.
+    if (this.hasUpdated && (changed.has("categories") || changed.has("version"))) this._load();
+  }
+
+  /** Opens the preferences so the visitor can review or change their choice. */
+  open() {
+    this._draft = normaliseChoices(this.categories, this._record?.choices ?? {});
+    this._view = "preferences";
+    this._open = true;
+    void this.updateComplete.then(() => this.renderRoot.querySelector<HTMLElement>("h2")?.focus());
+  }
+
+  acceptAll() {
+    this._commit(choicesFor(this.categories, true), "accept-all");
+  }
+
+  rejectAll() {
+    this._commit(choicesFor(this.categories, false), "reject-all");
+  }
+
+  // ------------------------------------------------------------------ storage
+
+  private _load() {
+    const record = readRecord(this.storageKey);
+    if (isRecordValid(record, this.version, this.categories, this.expiresDays)) {
+      this._record = record;
+      this._open = false;
+      this.dispatchEvent(
+        new CustomEvent("st-consent-ready", {detail: {choices: record.choices}, bubbles: true, composed: true}),
+      );
+    } else {
+      this._record = null;
+      this._view = "summary";
+      this._open = true;
+    }
+  }
+
+  private _commit(choices: ConsentChoices, source: ConsentSource) {
+    const normalised = normaliseChoices(this.categories, choices);
+    this._record = {version: this.version, savedAt: Date.now(), choices: normalised};
+    writeRecord(this._record, this.storageKey);
+    this._open = false;
+    this._view = "summary";
+    this.dispatchEvent(
+      new CustomEvent("st-consent-change", {detail: {choices: normalised, source}, bubbles: true, composed: true}),
+    );
+  }
+
+  // ------------------------------------------------------------------- events
+
+  private _onDocumentClick = (e: MouseEvent) => {
+    const trigger = e.composedPath().find((el) => el instanceof Element && el.hasAttribute("data-consent-open"));
+    if (!trigger) return;
+    e.preventDefault();
+    this.open();
+  };
+
+  private _onKeydown = (e: KeyboardEvent) => {
+    // Escape only dismisses a reopened panel: a first-time visitor must still choose.
+    if (e.key === "Escape" && this._open && this._record) this._open = false;
+  };
+
+  private _toggle(id: string, on: boolean) {
+    this._draft = {...this._draft, [id]: on};
+  }
+
+  // ------------------------------------------------------------------- render
+
+  private _renderSummary() {
+    return html`
+      <h2 id="consent-title" tabindex="-1">${this.heading}</h2>
+      <p class="message">
+        <slot>
+          We use cookies to make this site work and, with your permission, to understand how it is
+          used. You can accept everything, reject everything, or choose.
+        </slot>
+        ${this.policyHref
+          ? html` <a class="policy" href=${this.policyHref}>${this.policyLabel}</a>`
+          : nothing}
+      </p>
+      <div class="actions">
+        <st-button class="decision" block color="primary" @click=${this.acceptAll}>${this.acceptLabel}</st-button>
+        <st-button class="decision" block color="primary" @click=${this.rejectAll}>${this.rejectLabel}</st-button>
+        <st-button variant="secondary" @click=${() => this.open()}>${this.customiseLabel}</st-button>
+      </div>
+    `;
+  }
+
+  private _renderPreferences() {
+    return html`
+      <h2 id="consent-title" tabindex="-1">${this.heading}</h2>
+      <ul class="categories">
+        ${this.categories.map(
+          (category) => html`
+            <li class="category">
+              ${category.required
+                ? html`<strong>${category.label}</strong> <span class="required">Always on</span>`
+                : html`
+                    <st-switch
+                      .checked=${this._draft[category.id] === true}
+                      @change=${(e: Event) => this._toggle(category.id, (e.target as HTMLInputElement).checked)}
+                    >
+                      ${category.label}
+                    </st-switch>
+                  `}
+              ${category.description ? html`<p>${category.description}</p>` : nothing}
+            </li>
+          `,
+        )}
+      </ul>
+      <div class="actions">
+        <st-button class="decision" block color="primary" @click=${() => this._commit(this._draft, "custom")}>
+          ${this.saveLabel}
+        </st-button>
+        <st-button class="decision" block color="primary" @click=${this.acceptAll}>${this.acceptLabel}</st-button>
+        <st-button class="decision" block color="primary" @click=${this.rejectAll}>${this.rejectLabel}</st-button>
+      </div>
+    `;
+  }
+
+  render() {
+    return html`
+      <div
+        class="panel"
+        role="dialog"
+        aria-modal="false"
+        aria-labelledby="consent-title"
+        ?hidden=${!this._open}
+      >
+        ${this._view === "preferences" ? this._renderPreferences() : this._renderSummary()}
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-consent": StConsent;
+  }
+}

package/src/components/consent/consent.utils.ts

@@ -0,0 +1,110 @@
+/** Cookie and storage consent: the record kept, and how it is read and written. */
+
+export interface ConsentCategory {
+  id: string;
+  label: string;
+  description?: string;
+  /** Always on and not switchable, for things the site cannot work without. */
+  required?: boolean;
+}
+
+export type ConsentChoices = Record<string, boolean>;
+
+export interface ConsentRecord {
+  /** Increase your `version` when what you collect changes, to ask everyone again. */
+  version: string;
+  /** Milliseconds since the epoch when the choice was made. */
+  savedAt: number;
+  choices: ConsentChoices;
+}
+
+export const DEFAULT_STORAGE_KEY = "st-consent";
+export const DEFAULT_CATEGORIES: ConsentCategory[] = [
+  {
+    id: "necessary",
+    label: "Necessary",
+    description: "Needed for the site to work. These cannot be switched off.",
+    required: true,
+  },
+  {id: "analytics", label: "Analytics", description: "Help us understand how the site is used."},
+  {id: "marketing", label: "Marketing", description: "Used to show relevant content and measure campaigns."},
+];
+
+const DAY_MS = 86_400_000;
+
+/** Every category set to the same answer; required categories are always on. */
+export function choicesFor(categories: ConsentCategory[], value: boolean): ConsentChoices {
+  return Object.fromEntries(categories.map((c) => [c.id, c.required ? true : value]));
+}
+
+/** Keeps only known categories, forces required ones on, and treats anything missing as off. */
+export function normaliseChoices(categories: ConsentCategory[], choices: ConsentChoices): ConsentChoices {
+  return Object.fromEntries(categories.map((c) => [c.id, c.required ? true : choices[c.id] === true]));
+}
+
+/** True when a stored record is current: same version, not expired, covers every category. */
+export function isRecordValid(
+  record: ConsentRecord | null,
+  version: string,
+  categories: ConsentCategory[],
+  expiresDays: number,
+  now = Date.now(),
+): record is ConsentRecord {
+  if (!record || record.version !== version) return false;
+  if (now - record.savedAt > expiresDays * DAY_MS) return false;
+  return categories.every((c) => typeof record.choices?.[c.id] === "boolean");
+}
+
+export function parseRecord(raw: string | null): ConsentRecord | null {
+  if (!raw) return null;
+  try {
+    const value = JSON.parse(raw);
+    if (
+      value &&
+      typeof value.version === "string" &&
+      typeof value.savedAt === "number" &&
+      value.choices &&
+      typeof value.choices === "object"
+    ) {
+      return value as ConsentRecord;
+    }
+  } catch {
+    // Fall through: a corrupt record is the same as no record.
+  }
+  return null;
+}
+
+export function readRecord(key = DEFAULT_STORAGE_KEY): ConsentRecord | null {
+  try {
+    return parseRecord(window.localStorage.getItem(key));
+  } catch {
+    return null; // storage can be blocked
+  }
+}
+
+export function writeRecord(record: ConsentRecord, key = DEFAULT_STORAGE_KEY): boolean {
+  try {
+    window.localStorage.setItem(key, JSON.stringify(record));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function clearRecord(key = DEFAULT_STORAGE_KEY) {
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * The visitor's saved choices, or null if they have not chosen yet. Use it to decide whether to
+ * load an analytics script:
+ *
+ *   if (getConsent()?.analytics) loadAnalytics();
+ */
+export function getConsent(key = DEFAULT_STORAGE_KEY): ConsentChoices | null {
+  return readRecord(key)?.choices ?? null;
+}

package/src/components/contact/contact.ts

@@ -0,0 +1,83 @@
+import {html, css} from "lit";
+import {customElement, property} from "lit/decorators.js";
+import {StSection} from "../section/section.js";
+
+/**
+ * A "get in touch" row: your contact details beside a form. The columns stack on narrow screens,
+ * details first. The row only lays things out: the form is yours, so it can post wherever you
+ * choose.
+ *
+ * Slots: `eyebrow`, `title`, `lead`, the default slot (addresses, email, opening hours) and
+ * `form` (usually an `st-form`).
+ */
+@customElement("st-contact")
+export class StContact extends StSection {
+  /** Puts the form on the left on wide screens. */
+  @property({type: Boolean, reflect: true}) reverse = false;
+
+  constructor() {
+    super();
+    this.align = "start";
+  }
+
+  static styles = [
+    ...StSection.styles,
+    css`
+      .contact {
+        display: grid;
+        gap: var(--st-spacing-2xl);
+        align-items: start;
+      }
+
+      @media (min-width: 52rem) {
+        .contact {
+          grid-template-columns: repeat(2, minmax(0, 1fr));
+        }
+
+        :host([reverse]) .form {
+          order: -1;
+        }
+      }
+
+      .header {
+        margin-bottom: var(--st-spacing-lg);
+      }
+
+      .details {
+        color: var(--st-color-text-muted);
+      }
+
+      .details ::slotted(*) {
+        margin: 0 0 var(--st-spacing-md);
+      }
+
+      .form {
+        padding: var(--st-spacing-lg);
+        border: 1px solid var(--st-color-border);
+        border-radius: var(--st-radius-lg);
+        background: var(--st-row-card-bg, var(--st-color-surface));
+      }
+    `,
+  ];
+
+  render() {
+    return this.frame(
+      html`
+        <div class="contact">
+          <div class="text">
+            ${this.renderHeader()}
+            ${this.animateIn(html`<div class="details"><slot @slotchange=${this._onItemsChange}></slot></div>`, 100)}
+          </div>
+          <div class="form">${this.animateIn(html`<slot name="form"></slot>`, 150)}</div>
+        </div>
+      `,
+      {header: false, animated: false},
+    );
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-contact": StContact;
+  }
+}

package/src/components/container/container.ts

@@ -0,0 +1,60 @@
+import {LitElement, html, css} from "lit";
+import {customElement, property} from "lit/decorators.js";
+import {resetStyles} from "../../styles/reset.js";
+
+export const containerSizes = ["sm", "md", "lg", "xl", "full"] as const;
+export type ContainerSize = (typeof containerSizes)[number];
+
+/**
+ * Centres content and limits its line length, with side padding that grows with the screen.
+ * Use `size` to pick the maximum width; `full` removes the limit. Set `flush` to drop the side
+ * padding (for example to let an image touch the screen edges).
+ */
+@customElement("st-container")
+export class StContainer extends LitElement {
+  @property({type: String, reflect: true}) size: ContainerSize = "lg";
+  @property({type: Boolean, reflect: true}) flush = false;
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        display: block;
+        width: 100%;
+        max-width: var(--_max, var(--st-container-lg));
+        margin-inline: auto;
+        padding-inline: var(--st-gutter);
+      }
+
+      :host([flush]) {
+        padding-inline: 0;
+      }
+
+      :host([size="sm"]) {
+        --_max: var(--st-container-sm);
+      }
+      :host([size="md"]) {
+        --_max: var(--st-container-md);
+      }
+      :host([size="lg"]) {
+        --_max: var(--st-container-lg);
+      }
+      :host([size="xl"]) {
+        --_max: var(--st-container-xl);
+      }
+      :host([size="full"]) {
+        --_max: none;
+      }
+    `,
+  ];
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-container": StContainer;
+  }
+}

package/src/components/content-card/content-card.ts

@@ -22,7 +22,7 @@ export class StContentCard extends LitElement {
         height: 100%;
         background-color: var(--st-color-surface);
         border: 1px solid var(--st-color-border);
-        border-radius: var(--st-radius-md, 0.5rem);
+        border-radius: var(--st-radius-md);
         overflow: hidden;
         text-decoration: none;
         color: inherit;
@@ -45,7 +45,7 @@ export class StContentCard extends LitElement {
           Safari fix: WebKit ignores :host-context. 
           Set --st-card-shadow-hover in your global dark mode CSS instead! 
         */
-        box-shadow: var(--st-card-shadow-hover, 0 4px 12px rgba(0, 0, 0, 0.05)); 
+        box-shadow: var(--st-card-shadow-hover, var(--st-shadow-md)); 
       }
 
       /* ==========================================================
@@ -76,8 +76,8 @@ export class StContentCard extends LitElement {
       .content {
         display: flex;
         flex-direction: column;
-        padding: var(--st-spacing-md, 1.25rem);
-        gap: var(--st-spacing-sm, 0.5rem);
+        padding: var(--st-spacing-md);
+        gap: var(--st-spacing-sm);
         flex: 1;
       }