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

package/DS1/0-face/generated/toast-assets.ts

@@ -0,0 +1,18 @@
+/**
+ * Generated by scripts/toast-assets.mjs from 2-core/styles/ds-toast.css (with the
+ * sheets it imports) and the x-icon files it names. Never edit it: change those
+ * files and run `vp run generate:toast-assets`.
+ */
+
+/** The toast's stylesheet, the same one `<ds-toast>` imports. */
+export const toastStyles: string = "[data-ds-shape=\"square\"], :host([data-ds-shape=\"square\"]){--ds-corner-size: 0px;--ds-corner-shape: round;--ds-button-inset: 0.5px}[data-ds-shape=\"rounded\"], :host([data-ds-shape=\"rounded\"]){--ds-corner-size: 4px;--ds-corner-shape: round;--ds-button-inset: 2.5px}[data-ds-shape=\"circular\"], :host([data-ds-shape=\"circular\"]){--ds-corner-size: 999px;--ds-corner-shape: round;--ds-button-inset: 5px}@supports (corner-shape: squircle){[data-ds-shape=\"rounded\"], :host([data-ds-shape=\"rounded\"]){--ds-corner-size: 8px;--ds-corner-shape: squircle}}:root, :host, :where([data-ds-surface]){--ds-unit: calc(var(--ds-1, 20px) * var(--ds-sf, 1));--ds-control-height: calc(var(--ds-control-size, var(--ds-08, 16px)) * var(--ds-sf, 1));--ds-row-height: calc(var(--ds-row-size, var(--ds-1, 20px)) * var(--ds-sf, 1));--ds-type-size-default: calc(var(--ds-text-size, 14px) * var(--ds-sf, 1));--ds-type-size-small: calc(var(--ds-small-text-size, 10px) * var(--ds-sf, 1));--ds-type-size-heading: calc(var(--ds-heading-text-size, 13px) * var(--ds-sf, 1));--ds-type-size-display: calc(var(--ds-display-text-size, 20px) * var(--ds-sf, 1));--ds-type-lineheight-default: calc(var(--ds-text-leading, 16px) * var(--ds-sf, 1));--ds-type-letterspacing-default: calc(var(--ds-text-tracking, -0.3px) * var(--ds-sf, 1));--ds-radius: calc(var(--ds-corner-size, 4px) * var(--ds-sf, 1));--ds-radius-card: calc(var(--ds-card-corner-size, 4px) * var(--ds-sf, 1))}:host{--ds-toast-width: calc(16 * var(--ds-unit));--ds-toast-offset: var(--ds-unit);--ds-toast-gap: calc(var(--ds-unit) - var(--ds-control-height));--ds-toast-background: var(--ds-tooltip-background, light-dark(var(--ds-black, #2a2a2a), var(--ds-white, #ffffff)));--ds-toast-color: var(--ds-tooltip-color, light-dark(var(--ds-white, #ffffff), var(--ds-black, #2a2a2a)));display: contents}section{display: contents}ol{--lift: -1;position: fixed;z-index: 2147483000;box-sizing: border-box;width: min(var(--ds-toast-width), calc(100% - 2 * var(--ds-toast-offset)));height: calc(var(--height) + var(--gaps) * var(--ds-toast-gap));margin: 0;padding: 0;list-style: none;outline: none;pointer-events: none}ol[data-y=\"top\"]{--lift: 1;top: calc(var(--ds-toast-offset) + env(safe-area-inset-top, 0px))}ol[data-y=\"bottom\"]{bottom: calc(var(--ds-toast-offset) + env(safe-area-inset-bottom, 0px))}ol[data-x=\"left\"]{left: var(--ds-toast-offset)}ol[data-x=\"right\"]{right: var(--ds-toast-offset)}ol[data-x=\"center\"]{left: 50%;transform: translateX(-50%)}:host([contained]) ol{position: absolute;z-index: var(--ds-toast-z-index, 60)}:host([contained]) ol[data-y=\"top\"]{top: var(--ds-toast-offset)}:host([contained]) ol[data-y=\"bottom\"]{bottom: var(--ds-toast-offset)}.toast{--swipe: 0px;position: absolute;left: 0;right: 0;box-sizing: border-box;width: max-content;max-width: 100%;overflow: hidden;border-radius: var(--ds-radius);background: var(--ds-toast-background);color: var(--ds-toast-color);font-family: var(--ds-typeface-regular);font-feature-settings: var(--ds-font-features);font-size: var(--ds-type-size-default);line-height: var(--ds-control-height);letter-spacing: var(--ds-type-letterspacing-default);outline: none;touch-action: none;user-select: none;pointer-events: auto;opacity: 0;transition: transform 400ms ease, opacity 400ms ease}ol[data-y=\"bottom\"] .toast{bottom: 0}ol[data-y=\"top\"] .toast{top: 0}ol[data-x=\"center\"] .toast{margin-inline: auto}ol[data-x=\"left\"] .toast{margin-right: auto}ol[data-x=\"right\"] .toast{margin-left: auto}.toast:focus-visible{outline: 2px solid var(--ds-focus-ring);outline-offset: 1px}.toast[data-mounted=\"false\"]{transform: translateY(calc(var(--lift) * -100%))}.toast[data-mounted=\"true\"]{opacity: 1}ol[data-expanded=\"false\"] .toast[data-mounted=\"true\"]{transform: translateY(calc(var(--lift) * var(--index) * var(--ds-toast-gap) + var(--swipe))) scale(calc(1 - var(--index) * 0.05))}ol[data-expanded=\"false\"] .toast[data-front=\"false\"]{height: var(--front-height)}ol[data-expanded=\"false\"] .toast[data-front=\"false\"] .body{opacity: 0}ol[data-expanded=\"true\"] .toast[data-mounted=\"true\"]{transform: translateY(calc(var(--lift) * (var(--offset) + var(--index) * var(--ds-toast-gap)) + var(--swipe)))}.toast[data-visible=\"false\"]{opacity: 0;pointer-events: none}.toast[data-swiping=\"true\"]{transition: none}.toast[data-removed=\"true\"]{opacity: 0;pointer-events: none}.toast[data-removed=\"true\"][data-front=\"true\"]{transform: translateY(calc(var(--lift) * -100%))}.toast[data-swipe-out=\"true\"]{transform: translateY(calc(var(--swipe) + var(--lift) * -100%))}.body{display: flex;align-items: flex-start;gap: calc(4px * var(--ds-sf));box-sizing: border-box;min-height: var(--ds-control-height);padding-inline: calc(4px * var(--ds-sf));transition: opacity 400ms ease}.icon{display: inline-flex;flex: 0 0 auto;align-items: center;justify-content: center;width: var(--ds-control-height);height: var(--ds-control-height);--ds-icon-color: currentColor}.icon:first-child{margin-left: calc(-4px * var(--ds-sf))}.icon > svg, .close > svg{width: calc(14px * var(--ds-sf));height: calc(14px * var(--ds-sf))}.content{flex: 1 1 auto;min-width: 0}.title, .description{white-space: normal;overflow-wrap: anywhere}.description{opacity: 0.7}.button{flex: 0 0 auto;margin: 0 0 0 calc(4px * var(--ds-sf));padding: 0;border: 0;background: none;color: inherit;font: inherit;letter-spacing: inherit;text-decoration: underline;text-underline-offset: 2px;cursor: pointer}a.button{display: inline-block}.button.cancel{opacity: 0.7}.button:focus-visible, .close:focus-visible{outline: 1px solid currentColor;outline-offset: 1px;border-radius: 1px}.close{display: inline-flex;flex: 0 0 auto;align-items: center;justify-content: center;width: var(--ds-control-height);height: var(--ds-control-height);margin: 0 calc(-4px * var(--ds-sf)) 0 0;padding: 0;border: 0;background: none;color: inherit;cursor: pointer;--ds-icon-color: currentColor}.spinner{width: calc(10px * var(--ds-sf));height: calc(10px * var(--ds-sf));box-sizing: border-box;border: 1px solid color-mix(in srgb, currentColor 25%, transparent);border-top-color: currentColor;border-radius: 50%;animation: ds-toast-spin 720ms linear infinite}@keyframes ds-toast-spin{to{transform: rotate(360deg)}}:host([rich-colors]) .toast[data-type=\"success\"]{--ds-toast-background: var(--ds-apple-green)}:host([rich-colors]) .toast[data-type=\"info\"]{--ds-toast-background: var(--ds-zenith-blue)}:host([rich-colors]) .toast[data-type=\"warning\"]{--ds-toast-background: var(--ds-orange)}:host([rich-colors]) .toast[data-type=\"error\"]{--ds-toast-background: var(--ds-tuned-red)}:host([rich-colors]) .toast:is([data-type=\"success\"], [data-type=\"info\"], [data-type=\"warning\"], [data-type=\"error\"]){--ds-toast-color: var(--ds-black)}@media (prefers-reduced-motion: reduce){.toast, .body{transition: none}.spinner{animation: none}}";
+
+export type ToastIconName = "check" | "close" | "notifications" | "warning";
+
+/** The icons the page toaster draws: the toast types' own and the close button's. */
+export const toastIcons: Readonly<Record<ToastIconName, string>> = {
+  "check": "<svg width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M6.68649 11.884L12.443 6.13601L11.736 5.42715L6.68835 10.4827L4.26399 8.0501L3.55696 8.74525L6.68649 11.884Z\" fill=\"currentColor\"/>\n</svg>\n",
+  "close": "<svg width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M12.1215 4.58087L8.70453 7.99397L12.1176 11.4169L11.4106 12.112L7.99847 8.69108L4.58636 12.112L3.87836 11.4031L7.29535 7.99005L3.88226 4.56716L4.58929 3.87201L8.0014 7.29294L11.4145 3.87201L12.1215 4.58087Z\" fill=\"currentColor\"/>\n</svg>\n",
+  "notifications": "<svg width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M4.5 11.5V7.5C4.5 5.567 6.067 4 8 4C9.933 4 11.5 5.567 11.5 7.5V11.5M3 11.5H13M8 2.5V4M6.5 13.5H9.5\" stroke=\"currentColor\" stroke-width=\"0.92\"/>\n</svg>\n",
+  "warning": "<svg width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M8 1.8L15.2 14.3H0.8L8 1.8ZM8 3.8L2.53 13.3H13.47L8 3.8ZM7.5 6.3H8.5V10.3H7.5V6.3ZM7.5 11.3H8.5V12.3H7.5V11.3Z\" fill=\"#1E1E1E\"/>\n</svg>\n",
+};

package/DS1/0-face/grid-fit.ts

@@ -7,7 +7,7 @@ export function initGridFit(): void {
   const measure = document.createElement('div');
   measure.setAttribute('aria-hidden', 'true');
   measure.style.cssText = 'position:fixed;left:0;top:0;width:0;height:var(--ds-grid-unit,20px);visibility:hidden;pointer-events:none;contain:strict';
-  document.body.append(measure);
+  document.body.appendChild(measure);
   const originalMinimums = new Map<HTMLElement, string>();
   const observed = new Set<HTMLElement>();
   let frame = 0;

package/DS1/0-face/grid.ts

@@ -41,7 +41,7 @@ export function initGridShortcut(): void {
     }
     @media print { :host { display: none !important; } }
   </style><div class="grid"></div>`;
-  document.body.append(overlay);
+  document.body.appendChild(overlay);
   const layout = createLayoutInspector();
 
   const updatePosition = () => {
@@ -67,7 +67,8 @@ export function initGridShortcut(): void {
   if (preview.get('grid') === '1') setVisible(true);
   if (preview.get('layout') === '1') layout.toggle();
 
-  if (import.meta.env?.DEV) {
+  // A bundler's development flag (Vite's import.meta.env.DEV); absent elsewhere.
+  if ((import.meta as ImportMeta & { env?: { DEV?: boolean } }).env?.DEV) {
     const mobile = window.matchMedia('(max-width: 768px)');
     let taps = 0;
     let lastTap = 0;

package/DS1/0-face/header.ts

@@ -0,0 +1,78 @@
+/**
+ * The site header's script for pages without Lit: plain TypeScript, no
+ * framework. Loading it starts every `.ds-header` on the page (1-root/header.css
+ * draws them); call `startHeaders()` again for one added later.
+ *
+ * Each header's menu button (`.ds-header__toggle`) opens its navigation and
+ * actions in a drawer (`0-face/drawer.ts`): a panel over the screen with focus
+ * kept inside, closed by Escape, its close button, a link or the screen
+ * widening, the page's scroll held behind it. The close button is named by the
+ * toggle's `data-close-label`, "Close" without one; the page writes both names
+ * in its own language. A navigation where no link is marked `aria-current`
+ * gets `aria-current="page"` on the link to the address being read.
+ *
+ * @example
+ * <header class="ds-header">
+ *   <a class="ds-header__brand" href="/">Name</a>
+ *   <nav class="ds-header__nav" id="site-nav" aria-label="Main">
+ *     <a href="/">Home</a> <a href="/help">Help</a>
+ *   </nav>
+ *   <button class="ds-button ds-button--icon ds-header__toggle" type="button"
+ *     aria-label="Menu" aria-controls="site-nav" data-close-label="Close">
+ *     <span class="ds-icon" style="--ds-icon: url(/ds1/icons/menu.svg)" aria-hidden="true"></span>
+ *     <span class="ds-icon" style="--ds-icon: url(/ds1/icons/close.svg)" aria-hidden="true"></span>
+ *   </button>
+ * </header>
+ * <script type="module">import "/ds1/0-face/header.ts";</script>
+ */
+import { attachDrawer, type Drawer } from "./drawer";
+
+const started = new WeakMap<Element, Drawer>();
+
+/** A path without a trailing slash or an index file, for comparing addresses. */
+function normalise(path: string): string {
+  return path.replace(/\/index\.html?$/, "/").replace(/\.html?$/, "").replace(/\/+$/, "") || "/";
+}
+
+/**
+ * Marks the link to the address being read with `aria-current="page"`, unless
+ * one of the links is marked already. Returns the marked link, if any.
+ */
+export function markCurrentLink(links: Iterable<HTMLAnchorElement>, location: { href: string } = globalThis.location): HTMLAnchorElement | null {
+  const all = [...links];
+  const marked = all.find(link => link.hasAttribute("aria-current") && link.getAttribute("aria-current") !== "false");
+  if (marked || !location) return marked ?? null;
+  const here = new URL(location.href);
+  const match = all.find(link => {
+    if (!link.getAttribute("href") || link.getAttribute("href")!.startsWith("#")) return false;
+    const target = new URL(link.href, here);
+    return target.origin === here.origin && normalise(target.pathname) === normalise(here.pathname);
+  });
+  match?.setAttribute("aria-current", "page");
+  return match ?? null;
+}
+
+/** Starts every `.ds-header` inside `root` that has not started yet, and returns their drawers. */
+export function startHeaders(root: ParentNode = document): Drawer[] {
+  const drawers: Drawer[] = [];
+  for (const header of root.querySelectorAll<HTMLElement>(".ds-header")) {
+    const nav = header.querySelector<HTMLElement>(":scope > .ds-header__nav");
+    if (nav) markCurrentLink(nav.querySelectorAll<HTMLAnchorElement>("a[href]"));
+    if (started.has(header)) continue;
+    const toggle = header.querySelector<HTMLElement>(":scope > .ds-header__toggle");
+    if (!toggle) continue;
+    const drawer = attachDrawer({
+      toggle,
+      content: () => [...header.querySelectorAll(":scope > :is(.ds-header__nav, .ds-header__actions)")],
+      closeLabel: toggle.dataset.closeLabel,
+    });
+    started.set(header, drawer);
+    drawers.push(drawer);
+  }
+  return drawers;
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", () => startHeaders(), { once: true });
+  else startHeaders();
+}

package/DS1/0-face/i18n.ts

@@ -7,7 +7,7 @@ import {
   normalizeLanguage,
 } from "./languages";
 import type { Language } from "./languages";
-import { configureLanguageRouting } from "./language-routing";
+import { configureLanguageRouting, parseLanguagePath } from "./language-routing";
 import type { LanguageRoutingOptions } from "./language-routing";
 import { readLanguageFile, resolveText } from "./translations-format";
 import type {
@@ -38,6 +38,8 @@ export type TranslationMap = Record<string, TranslationData>;
 export type I18nOptions = {
   /** Fetch external words at startup. Disable when the product supplies them in code. */
   autoLoad?: boolean;
+  /** Ignore saved choices and avoid writes on browser-managed surfaces. */
+  persist?: boolean;
   /**
    * Every language the product speaks. When set, the picker offers these
    * whether or not their words have arrived yet, which matters when a page
@@ -81,6 +83,31 @@ export type I18nOptions = {
    * here, the product's `languages` get a prefix.
    */
   routing?: LanguageRoutingOptions;
+  /**
+   * Take the language from the address: on a page whose path starts with a
+   * language prefix (`/ja/…`, by `routing`), that language is the current one
+   * from the start, and it is not stored, so following a link to `/ja/…`
+   * never overwrites the choice a person made. `setLanguage` still stores
+   * what a person chooses. The theme bootstrap reads it too, so `lang` is
+   * right before the first paint. Off by default.
+   */
+  languageFromAddress?: boolean;
+  /**
+   * Where the language is written as `lang`: the document's root element by
+   * default; an element (an embedded surface, such as a prototype in another
+   * language than the page around it) to keep it there; `false` to write it
+   * nowhere. The theme bootstrap writes the root's `lang` only by default.
+   */
+  langTarget?: HTMLElement | false;
+};
+
+/** What `setLanguage` does besides changing the language. */
+export type SetLanguageOptions = {
+  /**
+   * Store the choice, so the next visit opens in it. On by default; `false`
+   * keeps it to this page (a language an address names, a preview).
+   */
+  remember?: boolean;
 };
 
 // Bundled translations (keys.json may not exist - will use external translations if not available)
@@ -142,6 +169,7 @@ function storageKey(): string {
 }
 
 function readStoredLanguage(): LanguageCode | null {
+  if (i18nOptions.persist === false) return null;
   try {
     return (storage()?.getItem(storageKey()) as LanguageCode | null) || null;
   } catch {
@@ -150,6 +178,7 @@ function readStoredLanguage(): LanguageCode | null {
 }
 
 function storeLanguage(language: LanguageCode): void {
+  if (i18nOptions.persist === false) return;
   try {
     storage()?.setItem(storageKey(), language);
   } catch {
@@ -684,7 +713,7 @@ export function getBrowserLanguage(): LanguageCode {
 // ============================================================================
 
 function dispatchLanguageChanged(language: LanguageCode): void {
-  if (typeof window === "undefined") {
+  if (typeof window === "undefined" || typeof window.dispatchEvent !== "function") {
     return;
   }
   window.dispatchEvent(
@@ -696,17 +725,42 @@ function dispatchLanguageChanged(language: LanguageCode): void {
   );
 }
 
+/** The language the address names (`/ja/…`), when the product takes it from there. */
+function addressLanguage(): LanguageCode | null {
+  if (!i18nOptions.languageFromAddress || typeof window === "undefined") {
+    return null;
+  }
+  const path = window.location?.pathname;
+  // The product's routing, also before configureI18n has passed it on.
+  return path ? parseLanguagePath(path, routingOptions()).language : null;
+}
+
+/** The element whose `lang` follows the language, or null when none does. */
+function langElement(): HTMLElement | null {
+  const target = i18nOptions.langTarget;
+  if (target === false) {
+    return null;
+  }
+  if (target) {
+    return target;
+  }
+  return typeof document !== "undefined" ? (document.documentElement ?? null) : null;
+}
+
 // Create a reactive signal for the current language (Portfolio pattern)
 export const currentLanguage = {
-  value: readStoredLanguage() || getBrowserLanguage(),
-  set: function (lang: LanguageCode) {
+  value: addressLanguage() || readStoredLanguage() || getBrowserLanguage(),
+  set: function (lang: LanguageCode, options: SetLanguageOptions = {}) {
     this.value = lang;
-    storeLanguage(lang);
+    if (options.remember !== false) {
+      storeLanguage(lang);
+    }
     void loadLanguage(lang);
     // What reads the document's language (dates, screen readers, hyphenation)
     // follows too, rather than keeping the language the page was opened in.
-    if (typeof document !== "undefined" && document.documentElement) {
-      document.documentElement.lang = lang;
+    const element = langElement();
+    if (element) {
+      element.lang = lang;
     }
     dispatchLanguageChanged(lang);
   },
@@ -719,23 +773,30 @@ export const currentLanguage = {
  * language's file if one is now configured.
  */
 export function configureI18n(next: I18nOptions): void {
+  const previousPersist = i18nOptions.persist;
   const previousKey = storageKey();
   const previousLanguages = i18nOptions.languages;
+  const previousAddress = i18nOptions.languageFromAddress;
+  const previousRouting = i18nOptions.routing;
   i18nOptions = { ...i18nOptions, ...next };
 
   applyRouting();
 
   if (
+    i18nOptions.persist !== previousPersist ||
     storageKey() !== previousKey ||
-    i18nOptions.languages !== previousLanguages
+    i18nOptions.languages !== previousLanguages ||
+    i18nOptions.languageFromAddress !== previousAddress ||
+    (i18nOptions.languageFromAddress && i18nOptions.routing !== previousRouting)
   ) {
-    // The stored choice under the new key, or the browser's language, as one
-    // the product speaks
+    // The language the address names, else the stored choice under the new
+    // key, or the browser's language, as one the product speaks
     const stored = readStoredLanguage();
     let language: LanguageCode = stored || getBrowserLanguage();
     if (stored && configuredLanguages()) {
       language = resolvePreferredLanguage(stored) ?? defaultLanguage;
     }
+    language = addressLanguage() ?? language;
     if (language !== currentLanguage.value) {
       currentLanguage.value = language;
       dispatchLanguageChanged(language);
@@ -756,10 +817,14 @@ function applyRouting(): void {
   if (!i18nOptions.routing && !i18nOptions.languages) {
     return;
   }
-  configureLanguageRouting({
+  configureLanguageRouting(routingOptions());
+}
+
+function routingOptions(): LanguageRoutingOptions {
+  return {
     ...(i18nOptions.languages ? { languages: i18nOptions.languages } : {}),
     ...i18nOptions.routing,
-  });
+  };
 }
 
 let sharedWordsLoad: Promise<void> | null = null;
@@ -801,8 +866,11 @@ if (typeof window !== "undefined" && typeof document !== "undefined") {
   }
 }
 
-// Listen for external translations being loaded
-if (typeof window !== "undefined") {
+// Listen for external translations being loaded. Only where window takes events:
+// a server or worker runtime may define a window without them, and the timer
+// below would otherwise throw after the code that imported this has finished.
+const eventful = () => typeof window !== "undefined" && typeof window.addEventListener === "function" && typeof window.dispatchEvent === "function";
+if (eventful()) {
   window.addEventListener("translations-ready", () => {
     // Dispatch that translations are loaded
     window.dispatchEvent(new CustomEvent("translations-loaded"));
@@ -814,7 +882,7 @@ if (typeof window !== "undefined") {
   // Initialize translations on module load
   // Use setTimeout to give other parts of the app time to set up event listeners first
   setTimeout(() => {
-    if (typeof window === "undefined") {
+    if (!eventful()) {
       return;
     }
     window.dispatchEvent(new CustomEvent("translations-loaded"));
@@ -892,6 +960,10 @@ export function translate(key: string, params?: TranslationParams): string {
   return textInLanguage(key, currentLanguage.value, params);
 }
 
+// The feedback module (`./feedback-words.ts`) reads its default words through
+// this when the page loads the language module, and English without it.
+(globalThis as unknown as Record<symbol, unknown>)[Symbol.for("design-system-1.translate")] = translate;
+
 /**
  * A key's text in a given language, whatever the page's own language is (a
  * drawing made for one language, say). The fallback order: the language, its
@@ -1016,8 +1088,11 @@ export function loadTranslations(
   }
 }
 
-// Set language (Portfolio pattern)
-export function setLanguage(language: LanguageCode): void {
+/**
+ * Change the language: store it (unless `remember: false`), fetch its words,
+ * write it as `lang` (see `langTarget`) and announce `language-changed`.
+ */
+export function setLanguage(language: LanguageCode, options?: SetLanguageOptions): void {
   // The signal owns persistence, loading, document language and notification.
-  currentLanguage.set(language);
+  currentLanguage.set(language, options);
 }

package/DS1/0-face/keys.ts

@@ -0,0 +1,276 @@
+/**
+ * Keyboard shortcuts on every platform: the platform's command key, a guard
+ * that leaves typing alone, the label a shortcut is written with, and one call
+ * that binds a shortcut. Plain TypeScript with no framework and no language
+ * runtime, for any page.
+ *
+ * A shortcut is written once, in lower case, its parts joined with `+`:
+ * `"mod+shift+d"`, `"mod+enter"`, `"alt+arrowup"`, `"escape"`, `"?"`. `mod`
+ * is ⌘ on a Mac, iPhone or iPad and Ctrl everywhere else; `ctrl`, `meta`,
+ * `alt` and `shift` name a key as it is. The key is a letter, a digit, a
+ * symbol or one of the named keys (`enter`, `escape`, `tab`, `space`,
+ * `backspace`, `delete`, `home`, `end`, `pageup`, `pagedown`, the arrows
+ * `arrowup` … `arrowright`, `f1` … `f12`; `plus` for `+`).
+ *
+ * - `modKey()` is the command key's label: ⌘, or Ctrl.
+ * - `isTyping(event)` is true while focus is in a text field, a select, a
+ *   contenteditable or a textbox, or a composition (an input method) is open.
+ * - `shortcutLabel("mod+shift+d")` writes it as the platform does: ⇧⌘D on
+ *   Apple platforms, in Apple's order (⌃ ⌥ ⇧ ⌘), and Ctrl+Shift+D elsewhere.
+ *   Arrows are drawn as arrows (↑), which every DS1 typeface sets in Inter.
+ * - `ariaKeyShortcuts("mod+shift+d")` is the value for `aria-keyshortcuts`
+ *   on the control the shortcut presses: Meta+Shift+D or Control+Shift+D.
+ * - `matchesShortcut(event, "mod+d")` reads a keydown; a letter matches by
+ *   its physical key too, so it works on other layouts and with ⌥ held.
+ * - `onShortcut("mod+k", handler)` listens for it on the document (or a
+ *   `target`), leaves it alone while typing unless `typing: true`, prevents
+ *   the browser's own action, and returns the function that unbinds it.
+ *
+ * The key names written as words (Ctrl, Shift, Alt, Enter, Esc, Tab, Space,
+ * Backspace, Del, Home, End, PgUp, PgDn) are the shared words (`key.ctrl` …)
+ * in the page's language where the page loads the language module with
+ * `configureI18n({ sharedWords: true })`, and English otherwise;
+ * `setKeyWords()` gives a product's own.
+ */
+
+export type KeyPlatform = "apple" | "other";
+
+export interface ShortcutOptions {
+  /** The platform to write or read the shortcut for; the device's own by default. */
+  platform?: KeyPlatform;
+}
+
+/** A shortcut taken apart: its modifiers as keys on this platform, and its key. */
+export interface Shortcut {
+  ctrl: boolean;
+  meta: boolean;
+  alt: boolean;
+  shift: boolean;
+  /** The key, in lower case as written (`d`, `enter`, `arrowup`, `?`). */
+  key: string;
+}
+
+/** The ids of the key names written as words, each a shared word. */
+export type KeyWord =
+  | "key.ctrl" | "key.shift" | "key.alt" | "key.enter" | "key.escape" | "key.tab" | "key.space"
+  | "key.backspace" | "key.delete" | "key.home" | "key.end" | "key.pageup" | "key.pagedown";
+/** A table of the words to change, or a function that gives each word. */
+export type KeyWords = Partial<Record<KeyWord, string>> | ((word: KeyWord) => string);
+
+const ENGLISH: Record<KeyWord, string> = {
+  "key.ctrl": "Ctrl", "key.shift": "Shift", "key.alt": "Alt", "key.enter": "Enter", "key.escape": "Esc",
+  "key.tab": "Tab", "key.space": "Space", "key.backspace": "Backspace", "key.delete": "Del",
+  "key.home": "Home", "key.end": "End", "key.pageup": "PgUp", "key.pagedown": "PgDn",
+};
+
+/** Where the language module leaves its `translate()`; on `globalThis`, so every copy of either module finds it. */
+const TRANSLATOR = Symbol.for("design-system-1.translate");
+let words: KeyWords | null = null;
+
+/** Give the key names of a product's own, or `null` to go back to the shared words (or English). */
+export function setKeyWords(next: KeyWords | null): void {
+  words = next;
+}
+
+/** A key's name as a word, in the page's language. */
+export function keyWord(word: KeyWord): string {
+  if (typeof words === "function") return words(word);
+  const own = words?.[word];
+  if (own !== undefined) return own;
+  const translate = (globalThis as unknown as Record<symbol, unknown>)[TRANSLATOR];
+  if (typeof translate === "function") {
+    const text = String(translate(word));
+    // Without the shared words the language module answers with the id itself.
+    if (text && text !== word) return text;
+  }
+  return ENGLISH[word];
+}
+
+/** True on a Mac, iPhone or iPad, where ⌘ is the command key and Ctrl-click is the right click. */
+export function isApplePlatform(): boolean {
+  if (typeof navigator === "undefined") return false;
+  const data = (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData;
+  const platform = data?.platform || navigator.platform || "";
+  return /mac|iphone|ipad|ipod|ios/i.test(platform);
+}
+
+const platformOf = (options?: ShortcutOptions): KeyPlatform => options?.platform ?? (isApplePlatform() ? "apple" : "other");
+
+/** The command key's label: ⌘ on Apple platforms, Ctrl (in the page's language) elsewhere. */
+export function modKey(options?: ShortcutOptions): string {
+  return platformOf(options) === "apple" ? "⌘" : keyWord("key.ctrl");
+}
+
+/** True when the command key is held: ⌘ on Apple platforms, Ctrl elsewhere. */
+export function isModKey(event: { metaKey: boolean; ctrlKey: boolean }, options?: ShortcutOptions): boolean {
+  return platformOf(options) === "apple" ? event.metaKey : event.ctrlKey;
+}
+
+/** Input types a person types into; a checkbox or a button leaves shortcuts alone. */
+const TEXT_INPUTS = new Set(["", "text", "search", "email", "url", "tel", "password", "number", "date", "datetime-local", "month", "time", "week"]);
+
+/** The element an event started on, inside open shadow roots too. */
+function origin(event: Event): Element | null {
+  const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+  const first = path.find(node => node instanceof Element) ?? event.target;
+  return first instanceof Element ? first : null;
+}
+
+/**
+ * True while a person is typing: focus is in a text field, a textarea, a
+ * select, a contenteditable or an element with a textbox, searchbox or
+ * combobox role, or an input method is composing. A shortcut ignores it.
+ */
+export function isTyping(event: Event): boolean {
+  const keyboard = event as KeyboardEvent;
+  if (keyboard.isComposing || keyboard.keyCode === 229) return true;
+  let element = origin(event);
+  // The event's origin is the field; a host that forwards focus has it in its shadow root.
+  while (element?.shadowRoot?.activeElement) element = element.shadowRoot.activeElement;
+  if (!element) return false;
+  if (element instanceof HTMLInputElement) return TEXT_INPUTS.has(element.type.toLowerCase()) && !element.readOnly;
+  if (element instanceof HTMLTextAreaElement) return !element.readOnly;
+  if (element instanceof HTMLSelectElement) return true;
+  if (element instanceof HTMLElement && element.isContentEditable) return true;
+  // Some DOMs (and tests) leave isContentEditable unset; read the attribute along the way up.
+  if (element.closest('[contenteditable]:not([contenteditable="false"])')) return true;
+  return Boolean(element.closest('[role="textbox"], [role="searchbox"], [role="combobox"]'));
+}
+
+const ALIASES: Record<string, string> = {
+  esc: "escape", return: "enter", del: "delete", up: "arrowup", down: "arrowdown", left: "arrowleft", right: "arrowright",
+  spacebar: "space", " ": "space", pgup: "pageup", pgdn: "pagedown", cmd: "meta", command: "meta", control: "ctrl", option: "alt", opt: "alt",
+};
+
+/** Take a shortcut apart; `mod` becomes ⌘ (meta) on Apple platforms and Ctrl elsewhere. */
+export function parseShortcut(shortcut: string, options?: ShortcutOptions): Shortcut {
+  const apple = platformOf(options) === "apple";
+  const parts = shortcut.trim().toLowerCase().split("+").map(part => part.trim());
+  // "mod++" and a trailing "+" name the plus key.
+  const raw = parts[parts.length - 1] === "" ? "plus" : parts.pop()!;
+  const result: Shortcut = { ctrl: false, meta: false, alt: false, shift: false, key: ALIASES[raw] ?? raw };
+  for (const part of parts) {
+    const name = ALIASES[part] ?? part;
+    if (name === "mod") result[apple ? "meta" : "ctrl"] = true;
+    else if (name === "ctrl" || name === "meta" || name === "alt" || name === "shift") result[name] = true;
+    else if (name !== "") throw new Error(`Unknown modifier in shortcut "${shortcut}": ${part}`);
+  }
+  if (!result.key) throw new Error(`A shortcut names a key: "${shortcut}"`);
+  return result;
+}
+
+/** Named keys as KeyboardEvent.key gives them. */
+const EVENT_KEYS: Record<string, string> = {
+  enter: "Enter", escape: "Escape", tab: "Tab", space: " ", backspace: "Backspace", delete: "Delete",
+  home: "Home", end: "End", pageup: "PageUp", pagedown: "PageDown", insert: "Insert",
+  arrowup: "ArrowUp", arrowdown: "ArrowDown", arrowleft: "ArrowLeft", arrowright: "ArrowRight", plus: "+",
+};
+
+/** Keys whose character already needs Shift on most layouts, so Shift is not asked of them. */
+const shifted = (key: string) => key.length === 1 && !/[a-z0-9]/.test(key);
+
+/** True when a keydown is the shortcut. */
+export function matchesShortcut(event: KeyboardEvent, shortcut: string | Shortcut, options?: ShortcutOptions): boolean {
+  const wanted = typeof shortcut === "string" ? parseShortcut(shortcut, options) : shortcut;
+  if (event.ctrlKey !== wanted.ctrl || event.metaKey !== wanted.meta || event.altKey !== wanted.alt) return false;
+  if (!shifted(wanted.key) && event.shiftKey !== wanted.shift) return false;
+  if (shifted(wanted.key) && wanted.shift && !event.shiftKey) return false;
+  const key = wanted.key;
+  if (/^[a-z]$/.test(key)) return event.key.toLowerCase() === key || event.code === `Key${key.toUpperCase()}`;
+  if (/^[0-9]$/.test(key)) return event.key === key || event.code === `Digit${key}`;
+  if (/^f([1-9]|1[0-9]|2[0-4])$/.test(key)) return event.key.toLowerCase() === key;
+  const named = EVENT_KEYS[key];
+  if (named) return event.key === named || (key === "space" && event.code === "Space");
+  return event.key.toLowerCase() === key;
+}
+
+/** Apple's symbols for its modifiers and keys, as its menus write them. */
+const APPLE_KEYS: Record<string, string> = {
+  enter: "↩", escape: "⎋", tab: "⇥", backspace: "⌫", delete: "⌦", home: "↖", end: "↘", pageup: "⇞", pagedown: "⇟",
+};
+const ARROWS: Record<string, string> = { arrowup: "↑", arrowdown: "↓", arrowleft: "←", arrowright: "→" };
+const WORDS: Record<string, KeyWord> = {
+  enter: "key.enter", escape: "key.escape", tab: "key.tab", space: "key.space", backspace: "key.backspace",
+  delete: "key.delete", home: "key.home", end: "key.end", pageup: "key.pageup", pagedown: "key.pagedown",
+};
+
+function keyLabel(key: string, apple: boolean): string {
+  if (ARROWS[key]) return ARROWS[key]!;
+  if (key === "plus") return "+";
+  if (apple && APPLE_KEYS[key]) return APPLE_KEYS[key]!;
+  if (WORDS[key]) return keyWord(WORDS[key]!);
+  if (/^f\d{1,2}$/.test(key)) return key.toUpperCase();
+  if (key === "insert") return "Ins";
+  return key.length === 1 ? key.toUpperCase() : key[0]!.toUpperCase() + key.slice(1);
+}
+
+/**
+ * A shortcut as the platform writes it: ⇧⌘D on Apple platforms (⌃ ⌥ ⇧ ⌘,
+ * then the key, with no space between), Ctrl+Shift+D elsewhere (Ctrl, Alt,
+ * Shift, then the key, joined with +).
+ */
+export function shortcutLabel(shortcut: string, options?: ShortcutOptions): string {
+  const apple = platformOf(options) === "apple";
+  const parts = parseShortcut(shortcut, options);
+  const key = keyLabel(parts.key, apple);
+  if (apple) return `${parts.ctrl ? "⌃" : ""}${parts.alt ? "⌥" : ""}${parts.shift ? "⇧" : ""}${parts.meta ? "⌘" : ""}${key}`;
+  return [
+    parts.meta ? "Meta" : "",
+    parts.ctrl ? keyWord("key.ctrl") : "",
+    parts.alt ? keyWord("key.alt") : "",
+    parts.shift ? keyWord("key.shift") : "",
+    key,
+  ].filter(Boolean).join("+");
+}
+
+/** The value for `aria-keyshortcuts`: the modifiers and key by their KeyboardEvent names, `Meta+Shift+D`. */
+export function ariaKeyShortcuts(shortcut: string, options?: ShortcutOptions): string {
+  const parts = parseShortcut(shortcut, options);
+  const key = parts.key === "space" ? "Space" : EVENT_KEYS[parts.key] ?? parts.key.toUpperCase();
+  return [parts.ctrl && "Control", parts.alt && "Alt", parts.shift && "Shift", parts.meta && "Meta", key].filter(Boolean).join("+");
+}
+
+export interface OnShortcutOptions extends ShortcutOptions {
+  /** Where to listen: the document by default; a panel or a field listens to its own keys. */
+  target?: EventTarget;
+  /** Also while typing in a field (a save shortcut, say); left alone by default. */
+  typing?: boolean;
+  /** Prevent the browser's own action for the shortcut; on by default. */
+  preventDefault?: boolean;
+  /** Also on a held key's repeats; on by default. */
+  repeat?: boolean;
+  /** Listen in the capture phase, before the page's own handlers. */
+  capture?: boolean;
+  /** Unbind when this signal aborts. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Run `handler` when a shortcut, or one of several, is pressed. A keydown
+ * already handled (`defaultPrevented`) is left alone. Returns the function
+ * that unbinds it.
+ */
+export function onShortcut(shortcut: string | string[], handler: (event: KeyboardEvent) => void, options: OnShortcutOptions = {}): () => void {
+  const target = options.target ?? (typeof document === "undefined" ? undefined : document);
+  if (!target) return () => {};
+  const shortcuts = (Array.isArray(shortcut) ? shortcut : [shortcut]).map(text => text.trim());
+  const listener = (event: Event) => {
+    const keyboard = event as KeyboardEvent;
+    if (keyboard.defaultPrevented) return;
+    if (keyboard.repeat && options.repeat === false) return;
+    if (!options.typing && isTyping(keyboard)) return;
+    // Read the platform per press, so a test or a product that sets it later is followed.
+    if (!shortcuts.some(text => matchesShortcut(keyboard, text, options))) return;
+    if (options.preventDefault !== false) keyboard.preventDefault();
+    handler(keyboard);
+  };
+  const capture = Boolean(options.capture);
+  target.addEventListener("keydown", listener, { capture });
+  const off = () => {
+    target.removeEventListener("keydown", listener, { capture });
+    options.signal?.removeEventListener("abort", off);
+  };
+  options.signal?.addEventListener("abort", off, { once: true });
+  if (options.signal?.aborted) off();
+  return off;
+}