@0001-labs/design-system-1 0.0.0-stage → 0.3.0-alpha.13

package/DS1/0-face/language-routing.ts

@@ -0,0 +1,135 @@
+/**
+ * Addresses that carry a language: `/ja/pricing` is the pricing page in
+ * Japanese, `/pricing` the same page in the default language.
+ *
+ * Pure functions on paths, with no window access, so they run in a browser,
+ * a Worker or a test alike. A product says which languages get a prefix and
+ * whether the default language has one, through `configureLanguageRouting`
+ * (or `configureI18n({ routing })`), or per call.
+ */
+import { DEFAULT_LANGUAGE, LANGUAGES } from "./languages";
+
+export type LanguageRoutingOptions = {
+  /** The languages that get a prefix. Defaults to every language in the list. */
+  languages?: readonly string[];
+  /** The language of an address without a prefix. Defaults to `en`. */
+  defaultLanguage?: string;
+  /**
+   * Whether the default language has a prefix too (`/en/pricing`). Off by
+   * default: the default language's addresses carry none.
+   */
+  prefixDefaultLanguage?: boolean;
+};
+
+export type LanguagePath = {
+  /** The language the address names, as configured (`pt-BR`), or null */
+  language: string | null;
+  /** The address without the prefix, always starting with `/` */
+  restPath: string;
+};
+
+let routing: LanguageRoutingOptions = {};
+
+/** Set which languages get a prefix, and whether the default language has one. */
+export function configureLanguageRouting(options: LanguageRoutingOptions): void {
+  routing = { ...routing, ...options };
+}
+
+/** The routing options in force, with the defaults filled in. */
+export function getLanguageRoutingOptions(): Required<LanguageRoutingOptions> {
+  return resolve();
+}
+
+function resolve(options?: LanguageRoutingOptions): Required<LanguageRoutingOptions> {
+  const merged = { ...routing, ...options };
+  return {
+    languages: merged.languages?.length ? merged.languages : LANGUAGES,
+    defaultLanguage: merged.defaultLanguage || DEFAULT_LANGUAGE,
+    prefixDefaultLanguage: merged.prefixDefaultLanguage ?? false,
+  };
+}
+
+/** A language's segment in an address: its code in lower case (`pt-br`). */
+export function languageSlug(language: string): string {
+  return String(language ?? "").toLowerCase().replace(/_/g, "-");
+}
+
+/**
+ * The configured language a path segment names (`pt-br` gives `pt-BR`), or
+ * null. Matching ignores case.
+ */
+export function languageFromSlug(
+  segment: string,
+  languages: readonly string[] = resolve().languages
+): string | null {
+  const slug = languageSlug(segment);
+  if (!slug) {
+    return null;
+  }
+  return languages.find((code) => languageSlug(code) === slug) ?? null;
+}
+
+/** Whether a path segment names one of the languages that get a prefix. */
+export function isLanguageSlug(segment: string, languages?: readonly string[]): boolean {
+  return languageFromSlug(segment, languages) !== null;
+}
+
+/** Split an address into its path and what follows (`?query#hash`). */
+function splitSuffix(path: string): [string, string] {
+  const index = path.search(/[?#]/);
+  return index === -1 ? [path, ""] : [path.slice(0, index), path.slice(index)];
+}
+
+/**
+ * The language an address names in its first segment, and the address
+ * without it: `/ja/pricing` gives `{ language: "ja", restPath: "/pricing" }`,
+ * `/pricing` gives `{ language: null, restPath: "/pricing" }`. A query and
+ * hash stay on the rest.
+ */
+export function parseLanguagePath(
+  pathname: string,
+  options?: LanguageRoutingOptions
+): LanguagePath {
+  const { languages } = resolve(options);
+  const [path, suffix] = splitSuffix(pathname || "/");
+  const absolute = path.startsWith("/") ? path : `/${path}`;
+  const first = absolute.split("/")[1] ?? "";
+  const language = languageFromSlug(first, languages);
+
+  if (!language) {
+    return { language: null, restPath: `${absolute}${suffix}` };
+  }
+
+  const rest = absolute.slice(first.length + 1) || "/";
+  return { language, restPath: `${rest}${suffix}` };
+}
+
+/** The address without a language prefix: `/ja/pricing` gives `/pricing`. */
+export function stripLanguagePrefix(path: string, options?: LanguageRoutingOptions): string {
+  return parseLanguagePath(path, options).restPath;
+}
+
+/**
+ * The address in `language`: `withLanguagePrefix("/pricing", "ja")` gives
+ * `/ja/pricing`. A prefix already there is replaced, never doubled. The
+ * default language, and languages without a prefix, give the bare address
+ * (unless `prefixDefaultLanguage` is on).
+ */
+export function withLanguagePrefix(
+  path: string,
+  language: string,
+  options?: LanguageRoutingOptions
+): string {
+  const resolved = resolve(options);
+  const rest = stripLanguagePrefix(path, options);
+  const configured = languageFromSlug(language, resolved.languages);
+  const isDefault = languageSlug(language) === languageSlug(resolved.defaultLanguage);
+
+  if (!configured || (isDefault && !resolved.prefixDefaultLanguage)) {
+    return rest;
+  }
+
+  const [restPath, suffix] = splitSuffix(rest);
+  const tail = restPath === "/" ? "" : restPath;
+  return `/${languageSlug(configured)}${tail}${suffix}`;
+}

package/DS1/0-face/language-validator.ts

@@ -0,0 +1,46 @@
+/**
+ * The server's check that a value is a language, for a product's Convex
+ * functions and schema. Built from the list in `./languages`, so it cannot
+ * drift from what the interface offers.
+ *
+ * Import it by path, from a product's `convex/` folder:
+ *
+ *   import { languageValidator } from "@0001-labs/design-system-1/DS1/0-face/language-validator.ts";
+ *
+ * It is not exported from `DS1/index.ts`, so the browser bundle stays free of
+ * `convex/values`.
+ */
+import { v } from "convex/values";
+import type { VLiteral, VUnion } from "convex/values";
+import { LANGUAGES, isLanguage } from "./languages";
+import type { Language } from "./languages";
+
+export type LanguageValidator<L extends Language = Language> = VUnion<
+  L,
+  VLiteral<L, "required">[],
+  "required",
+  never
+>;
+
+/**
+ * A validator for some of the languages: the ones a product saves, say. Every
+ * code must be in the list, and there must be at least one.
+ */
+export function languageValidatorFor<L extends Language>(
+  languages: readonly L[]
+): LanguageValidator<L> {
+  if (languages.length === 0) {
+    throw new Error("languageValidatorFor needs at least one language.");
+  }
+  const unknown = languages.filter((code) => !isLanguage(code));
+  if (unknown.length > 0) {
+    throw new Error(
+      `languageValidatorFor got codes that are not in the language list: ${unknown.join(", ")}`
+    );
+  }
+  const unique = [...new Set(languages)];
+  return v.union(...unique.map((code) => v.literal(code))) as LanguageValidator<L>;
+}
+
+/** Accepts every language in the list (`LANGUAGES`). */
+export const languageValidator: LanguageValidator = languageValidatorFor(LANGUAGES);

package/DS1/0-face/languages.ts

@@ -0,0 +1,242 @@
+/**
+ * The languages every 0001 product chooses from: one list, with the name of
+ * each in English and in itself, and how to read whatever a browser, a URL or
+ * a saved setting calls a language.
+ *
+ * No browser code, so a product's backend (Convex, Node) imports it as well.
+ * Each product turns on the subset it translates (`configureI18n({ languages })`).
+ */
+
+/** Every language Design system 1 knows, in the order pickers show them. */
+export const LANGUAGES = [
+  "da",
+  "de",
+  "en",
+  "es",
+  "fi",
+  "fr",
+  "is",
+  "it",
+  "ja",
+  "ko",
+  "nb",
+  "nn",
+  "no",
+  "pt",
+  "pt-BR",
+  "sv",
+  "zh",
+] as const;
+
+export type Language = (typeof LANGUAGES)[number];
+
+/** The language every product falls back to. */
+export const DEFAULT_LANGUAGE: Language = "en";
+
+export type LanguageMetadata = {
+  code: Language;
+  /** The name in English */
+  label: string;
+  /** The name in the language itself, as a picker shows it */
+  nativeLabel: string;
+  /** Other tags that mean this language, lower case (`da-dk`) */
+  aliases: readonly string[];
+};
+
+export const LANGUAGE_METADATA: Readonly<Record<Language, LanguageMetadata>> = {
+  da: { code: "da", label: "Danish", nativeLabel: "Dansk", aliases: ["da-dk"] },
+  de: {
+    code: "de",
+    label: "German",
+    nativeLabel: "Deutsch",
+    aliases: ["de-de", "de-at", "de-ch"],
+  },
+  en: {
+    code: "en",
+    label: "English",
+    nativeLabel: "English",
+    aliases: ["en-us", "en-gb", "en-ca", "en-au", "en-nz", "en-ie"],
+  },
+  es: {
+    code: "es",
+    label: "Spanish",
+    nativeLabel: "Español",
+    aliases: ["es-es", "es-mx", "es-ar", "es-cl", "es-co"],
+  },
+  fi: { code: "fi", label: "Finnish", nativeLabel: "Suomi", aliases: ["fi-fi"] },
+  fr: {
+    code: "fr",
+    label: "French",
+    nativeLabel: "Français",
+    aliases: ["fr-fr", "fr-ca", "fr-be", "fr-ch"],
+  },
+  is: { code: "is", label: "Icelandic", nativeLabel: "Íslenska", aliases: ["is-is"] },
+  it: { code: "it", label: "Italian", nativeLabel: "Italiano", aliases: ["it-it", "it-ch"] },
+  ja: { code: "ja", label: "Japanese", nativeLabel: "日本語", aliases: ["ja-jp"] },
+  ko: { code: "ko", label: "Korean", nativeLabel: "한국어", aliases: ["ko-kr"] },
+  nb: {
+    code: "nb",
+    label: "Norwegian Bokmål",
+    nativeLabel: "Norsk bokmål",
+    aliases: ["nb-no"],
+  },
+  nn: {
+    code: "nn",
+    label: "Norwegian Nynorsk",
+    nativeLabel: "Norsk nynorsk",
+    aliases: ["nn-no"],
+  },
+  no: { code: "no", label: "Norwegian", nativeLabel: "Norsk", aliases: ["no-no"] },
+  pt: { code: "pt", label: "Portuguese", nativeLabel: "Português", aliases: ["pt-pt"] },
+  "pt-BR": {
+    code: "pt-BR",
+    label: "Brazilian Portuguese",
+    nativeLabel: "Português (Brasil)",
+    aliases: ["pt-br"],
+  },
+  sv: { code: "sv", label: "Swedish", nativeLabel: "Svenska", aliases: ["sv-se", "sv-fi"] },
+  zh: {
+    code: "zh",
+    label: "Chinese",
+    nativeLabel: "中文",
+    aliases: ["zh-cn", "zh-tw", "zh-hk", "zh-sg", "zh-hans", "zh-hant"],
+  },
+};
+
+/**
+ * Languages close enough to stand in for each other, nearest first. A product
+ * that speaks only one of them gets it for the others (Link speaks `nb`, so
+ * `no` and `nn` read as `nb`; it speaks `pt-BR`, so `pt` reads as `pt-BR`), and
+ * a missing word is looked up in them before English.
+ */
+const RELATED_LANGUAGES: Readonly<Partial<Record<Language, readonly Language[]>>> = {
+  nb: ["no", "nn"],
+  no: ["nb", "nn"],
+  nn: ["nb", "no"],
+  pt: ["pt-BR"],
+  "pt-BR": ["pt"],
+};
+
+/** Every tag, lower case, to the language it means. */
+const ALIASES = new Map<string, Language>();
+for (const code of LANGUAGES) {
+  ALIASES.set(code.toLowerCase(), code);
+  for (const alias of LANGUAGE_METADATA[code].aliases) {
+    ALIASES.set(alias, code);
+  }
+}
+
+const ORDER = new Map<string, number>(LANGUAGES.map((code, index) => [code, index]));
+
+/** Whether a value is one of the list's codes, exactly as written there. */
+export function isLanguage(value: unknown): value is Language {
+  return typeof value === "string" && ORDER.has(value);
+}
+
+function primarySubtag(tag: string): string {
+  return tag.split("-")[0] ?? "";
+}
+
+/** The first of `language` and its relatives that `allowed` holds. */
+function within(language: Language, allowed: ReadonlySet<Language>): Language | null {
+  if (allowed.has(language)) {
+    return language;
+  }
+  return RELATED_LANGUAGES[language]?.find((related) => allowed.has(related)) ?? null;
+}
+
+/**
+ * Read any way of naming a language as one of the list: `da-DK`, `nb_NO`,
+ * `pt-br`, or a browser's list (`"nl-NL,da;q=0.8"`, the first language it
+ * knows wins). Pass the product's languages to land on one it speaks: a
+ * relative stands in where the product lacks the language itself, so with
+ * Link's languages `no` and `nn` read as `nb`, and `pt` as `pt-BR`. Returns
+ * `fallback` when nothing matches (`null` to tell).
+ */
+export function normalizeLanguage(
+  input: string | null | undefined,
+  fallback?: Language,
+  languages?: readonly Language[]
+): Language;
+export function normalizeLanguage(
+  input: string | null | undefined,
+  fallback: null,
+  languages?: readonly Language[]
+): Language | null;
+export function normalizeLanguage(
+  input: string | null | undefined,
+  fallback: Language | null = DEFAULT_LANGUAGE,
+  languages: readonly Language[] = LANGUAGES
+): Language | null {
+  const allowed = new Set(languages);
+  const tokens = String(input ?? "")
+    .split(",")
+    .map((token) => token.split(";")[0]?.trim().toLowerCase().replace(/_/g, "-") ?? "")
+    .filter(Boolean);
+
+  for (const token of tokens) {
+    const exact = ALIASES.get(token);
+    const match = exact ? within(exact, allowed) : null;
+    if (match) {
+      return match;
+    }
+    const base = ALIASES.get(primarySubtag(token));
+    const baseMatch = base ? within(base, allowed) : null;
+    if (baseMatch) {
+      return baseMatch;
+    }
+  }
+
+  return fallback;
+}
+
+/**
+ * The languages of `subset` that the list knows, in the list's order, each
+ * once. Codes are matched whatever their case (`pt-br` is `pt-BR`); others are
+ * left out.
+ */
+export function pickLanguages(subset: Iterable<string>): Language[] {
+  const wanted = new Set<Language>();
+  for (const code of subset) {
+    const member = ALIASES.get(String(code).toLowerCase().replace(/_/g, "-"));
+    if (member && member.toLowerCase() === String(code).toLowerCase().replace(/_/g, "-")) {
+      wanted.add(member);
+    }
+  }
+  return LANGUAGES.filter((code) => wanted.has(code));
+}
+
+/**
+ * Where a language sits in the list's order, for sorting: the code itself,
+ * else its primary subtag; codes the list does not know come last.
+ */
+export function languageOrder(code: string): number {
+  const normalized = String(code ?? "").toLowerCase().replace(/_/g, "-");
+  const member = ALIASES.get(normalized) ?? ALIASES.get(primarySubtag(normalized));
+  return member ? (ORDER.get(member) ?? LANGUAGES.length) : LANGUAGES.length;
+}
+
+/**
+ * The languages to look a word up in for `language`, before English: the
+ * language as given, its primary subtag (`ja-JP` reads `ja`), then its
+ * relatives (`nn` reads `nb`, `pt-BR` reads `pt`).
+ */
+export function fallbackLanguages(language: string): string[] {
+  const codes: string[] = [];
+  const add = (code: string | undefined) => {
+    if (code && !codes.includes(code)) {
+      codes.push(code);
+    }
+  };
+
+  add(language);
+  const normalized = String(language ?? "").toLowerCase().replace(/_/g, "-");
+  const member = ALIASES.get(normalized);
+  add(member);
+  add(primarySubtag(normalized));
+  const related = member ?? ALIASES.get(primarySubtag(normalized));
+  for (const code of related ? (RELATED_LANGUAGES[related] ?? []) : []) {
+    add(code);
+  }
+  return codes;
+}

package/DS1/0-face/layout-inspector.ts

@@ -0,0 +1,184 @@
+/** Inspect named page areas without changing their size, opacity, or interaction. */
+export function createLayoutInspector() {
+  const root = document.documentElement;
+  const overlay = document.createElement('div');
+  overlay.setAttribute('data-ds-layout-overlay', '');
+  overlay.setAttribute('aria-hidden', 'true');
+  overlay.hidden = true;
+  const shadow = overlay.attachShadow({ mode: 'open' });
+  shadow.innerHTML = `<style>
+    :host {
+      all: initial !important;
+      display: block !important;
+      position: fixed !important;
+      inset: 0 !important;
+      z-index: 2147483646 !important;
+      pointer-events: none !important;
+      color-scheme: inherit !important;
+    }
+    :host([hidden]) { display: none !important; }
+    .veil, .areas { position: absolute; inset: 0; overflow: hidden; }
+    .veil { background: color-mix(in srgb, var(--page-background, Canvas) 78%, transparent); }
+    .area {
+      position: absolute;
+      box-sizing: border-box;
+      display: grid;
+      place-items: center;
+      background: color-mix(in srgb, var(--pastel) 40%, transparent);
+      border: 1px solid color-mix(in srgb, var(--pastel) 65%, #82718d);
+    }
+    .name {
+      box-sizing: border-box;
+      max-width: 100%;
+      padding: 3px 8px;
+      background: var(--page-background, Canvas);
+      color: var(--base-slate, CanvasText);
+      font: 400 14px/20px var(--font-regular, var(--typeface-regular, sans-serif));
+      text-align: center;
+      overflow-wrap: anywhere;
+    }
+    .area[data-container] {
+      background: transparent;
+    }
+    .area[data-container] > .name {
+      position: absolute;
+      top: 0;
+      left: 0;
+    }
+    .area[data-compact] .name {
+      position: absolute;
+      bottom: 100%;
+      left: 50%;
+      transform: translateX(-50%);
+      width: max-content;
+      max-width: none;
+      padding: 2px 4px;
+      font-size: 12px;
+      line-height: 16px;
+      white-space: nowrap;
+    }
+    .dimensions {
+      display: block;
+      font-size: 12px;
+      line-height: 16px;
+      font-variant-numeric: tabular-nums;
+      white-space: nowrap;
+    }
+    @media print { :host { display: none !important; } }
+  </style><div class="veil"></div><div class="areas"></div>`;
+  document.body.append(overlay);
+  const layer = shadow.querySelector<HTMLDivElement>('.areas')!;
+  const colors = ['#efc9dc', '#d5c9ef', '#c2d9eb', '#bfe0cd', '#eee3b7', '#efcfb8'];
+  let frame = 0;
+  let visible = false;
+  const observed = new Set<HTMLElement>();
+  const observedRoots = new Set<ShadowRoot>();
+
+  const getAreas = () => {
+    const named: HTMLElement[] = [];
+    const collect = (scope: Document | ShadowRoot | HTMLElement) => {
+      named.push(...scope.querySelectorAll<HTMLElement>('[data-ds-area]'));
+      scope.querySelectorAll<HTMLElement>('[data-ds-layout-root]').forEach((host) => {
+        if (!host.shadowRoot) return;
+        if (!observedRoots.has(host.shadowRoot)) {
+          mutations.observe(host.shadowRoot, { subtree: true, childList: true, characterData: true });
+          observedRoots.add(host.shadowRoot);
+        }
+        collect(host.shadowRoot);
+      });
+    };
+    collect(document.querySelector<HTMLElement>('[data-ds-inspect-active]') ?? document);
+    if (named.length) return named;
+    // Semantic fallback for pages that have not supplied their own area names.
+    return Array.from(document.querySelectorAll<HTMLElement>('header, main, section, footer, one-footer'))
+      .filter((element) => !element.querySelector('section, header, footer, one-footer'));
+  };
+  const render = () => {
+    frame = 0;
+    if (!visible) return;
+    const areas = getAreas();
+    const current = new Set(areas);
+    for (const element of observed) {
+      if (!current.has(element)) { resize.unobserve(element); observed.delete(element); }
+    }
+    const fragments = document.createDocumentFragment();
+    areas.forEach((element, index) => {
+      if (!observed.has(element)) { resize.observe(element); observed.add(element); }
+      const rect = element.getBoundingClientRect();
+      if (!rect.width || !rect.height || rect.bottom <= 0 || rect.top >= innerHeight || rect.right <= 0 || rect.left >= innerWidth) return;
+      if (getComputedStyle(element).visibility === 'hidden') return;
+      const panel = document.createElement('div');
+      panel.className = 'area';
+      panel.toggleAttribute('data-container', !!element.shadowRoot?.querySelector('[data-ds-area]'));
+      panel.toggleAttribute('data-compact', rect.width < 80 || rect.height < 24);
+      panel.style.left = `${rect.left}px`;
+      panel.style.top = `${rect.top}px`;
+      panel.style.width = `${rect.width}px`;
+      panel.style.height = `${rect.height}px`;
+      panel.style.setProperty('--pastel', colors[index % colors.length]);
+      const label = document.createElement('span');
+      label.className = 'name';
+      const areaName = element.dataset.dsArea || element.getAttribute('aria-label') ||
+        (element.localName === 'one-footer' ? 'footer' : element.localName);
+      label.textContent = areaName.replace(/[-_]/g, ' ').replace(/^./, (letter) => letter.toUpperCase());
+      const dimensions = document.createElement('span');
+      dimensions.className = 'dimensions';
+      dimensions.textContent = `${Number(rect.width.toFixed(1))} × ${Number(rect.height.toFixed(1))} px`;
+      label.append(dimensions);
+      const ratio = document.createElement('span');
+      ratio.className = 'dimensions';
+      // Reduce dimensions measured to a tenth of a CSS pixel; use a decimal
+      // for fluid shapes whose exact fraction would be too long to read.
+      const width = Math.max(1, Math.round(rect.width * 10));
+      const height = Math.max(1, Math.round(rect.height * 10));
+      let divisor = width;
+      let remainder = height;
+      while (remainder) {
+        [divisor, remainder] = [remainder, divisor % remainder];
+      }
+      const horizontal = width / divisor;
+      const vertical = height / divisor;
+      ratio.textContent = horizontal <= 100 && vertical <= 100
+        ? `${horizontal}:${vertical}`
+        : `≈ ${Number((rect.width / rect.height).toFixed(2))}:1`;
+      label.append(ratio);
+      panel.append(label);
+      fragments.append(panel);
+    });
+    layer.replaceChildren(fragments);
+  };
+  const schedule = () => { if (visible && !frame) frame = requestAnimationFrame(render); };
+  const resize = new ResizeObserver(schedule);
+  const mutations = new MutationObserver(schedule);
+  const setVisible = (next: boolean) => {
+    if (next === visible) return;
+    visible = next;
+    overlay.hidden = !visible;
+    root.toggleAttribute('data-ds-layout-visible', visible);
+    if (visible) {
+      resize.observe(document.body);
+      mutations.observe(document.body, { subtree: true, childList: true, characterData: true });
+      window.addEventListener('scroll', schedule, { passive: true, capture: true });
+      window.addEventListener('resize', schedule);
+      window.addEventListener('scaling-changed', schedule);
+      window.addEventListener('design-system-layout-sized', schedule);
+      window.addEventListener('design-system-layout-ready', schedule);
+      schedule();
+    } else {
+      resize.disconnect();
+      observed.clear();
+      mutations.disconnect();
+      observedRoots.clear();
+      window.removeEventListener('scroll', schedule, true);
+      window.removeEventListener('resize', schedule);
+      window.removeEventListener('scaling-changed', schedule);
+      window.removeEventListener('design-system-layout-sized', schedule);
+      window.removeEventListener('design-system-layout-ready', schedule);
+      cancelAnimationFrame(frame);
+      frame = 0;
+      layer.replaceChildren();
+    }
+    window.dispatchEvent(new CustomEvent('design-system-layout-changed', { detail: { visible } }));
+  };
+  return { toggle: () => setVisible(!visible), hide: () => setVisible(false) };
+}

package/DS1/0-face/preferences.ts

@@ -0,0 +1,39 @@
+import type { LanguageCode } from "./i18n";
+import type { ThemeType } from "./theme";
+
+export type Preferences = {
+  language?: LanguageCode;
+  theme?: ThemeType;
+  [key: string]: unknown;
+};
+
+/** Product storage names are configuration; the implementation stays shared. */
+export interface PreferenceOptions {
+  storageKey?: string;
+  themeStorageKey?: string;
+}
+
+declare global {
+  interface Window { DS_ONE_PREFERENCES?: PreferenceOptions; }
+}
+
+export function preferenceStorageKey(kind: "preferences" | "theme"): string {
+  const options = typeof window === "undefined" ? undefined : window.DS_ONE_PREFERENCES;
+  return (kind === "theme" ? options?.themeStorageKey : options?.storageKey) || `ds-one:${kind}`;
+}
+
+export function savePreferences(preferences: Preferences): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  try {
+    const key = preferenceStorageKey("preferences");
+    const raw = window.localStorage?.getItem(key);
+    const existing = raw ? (JSON.parse(raw) as Record<string, unknown>) : {};
+    const next = { ...existing, ...preferences };
+    window.localStorage?.setItem(key, JSON.stringify(next));
+  } catch (error) {
+    console.warn("ds-one: unable to persist preferences", error);
+  }
+}