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

package/dist/0-face/grid-fit.js

@@ -7,7 +7,7 @@ export function initGridFit() {
     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();
     const observed = new Set();
     let frame = 0;

package/dist/0-face/grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../../DS1/0-face/grid.ts"],"names":[],"mappings":"AAGA,uEAAuE;AACvE,wBAAgB,gBAAgB,IAAI,IAAI,CAmIvC"}
+{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../../DS1/0-face/grid.ts"],"names":[],"mappings":"AAGA,uEAAuE;AACvE,wBAAgB,gBAAgB,IAAI,IAAI,CAoIvC"}

package/dist/0-face/grid.js

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

package/dist/0-face/header.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { type Drawer } from "./drawer";
+/**
+ * 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 declare function markCurrentLink(links: Iterable<HTMLAnchorElement>, location?: {
+    href: string;
+}): HTMLAnchorElement | null;
+/** Starts every `.ds-header` inside `root` that has not started yet, and returns their drawers. */
+export declare function startHeaders(root?: ParentNode): Drawer[];
+//# sourceMappingURL=header.d.ts.map

package/dist/0-face/header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../DS1/0-face/header.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AASrD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,GAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAwB,GAAG,iBAAiB,GAAG,IAAI,CAY9I;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,IAAI,GAAE,UAAqB,GAAG,MAAM,EAAE,CAiBlE"}

package/dist/0-face/header.js

@@ -0,0 +1,80 @@
+/**
+ * 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 } from "./drawer";
+const started = new WeakMap();
+/** A path without a trailing slash or an index file, for comparing addresses. */
+function normalise(path) {
+    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, location = globalThis.location) {
+    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 = document) {
+    const drawers = [];
+    for (const header of root.querySelectorAll(".ds-header")) {
+        const nav = header.querySelector(":scope > .ds-header__nav");
+        if (nav)
+            markCurrentLink(nav.querySelectorAll("a[href]"));
+        if (started.has(header))
+            continue;
+        const toggle = header.querySelector(":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/dist/0-face/i18n.d.ts

@@ -17,6 +17,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
@@ -60,6 +62,30 @@ 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;
 };
 /**
  * Every language Design system 1 orders, names and maps browser languages to:
@@ -94,7 +120,7 @@ export declare function getLanguageDisplayName(code: LanguageCode, options?: {
 export declare function getBrowserLanguage(): LanguageCode;
 export declare const currentLanguage: {
     value: string;
-    set: (lang: LanguageCode) => void;
+    set: (lang: LanguageCode, options?: SetLanguageOptions) => void;
 };
 /**
  * Set the language module up for a product (see `I18nOptions`). Call it
@@ -134,5 +160,9 @@ export declare function getAvailableLanguagesSync(): LanguageCode[];
  */
 export declare function loadTranslations(language: LanguageCode, translations: TranslationTable): void;
 export declare function loadTranslations(translations: TranslationsFile): void;
-export declare 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 declare function setLanguage(language: LanguageCode, options?: SetLanguageOptions): void;
 //# sourceMappingURL=i18n.d.ts.map

package/dist/0-face/i18n.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../DS1/0-face/i18n.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../DS1/0-face/i18n.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAGlC,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB,CAAC;AAGF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACpC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,YAAY,KAAK,MAAM,CAAC,GAAG,IAAI,CAAC;IACpE;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IAC9C;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAClC,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAMF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,QAAQ,EAAc,CAAC;AAMlE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QACtD,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B;CACF;AAyVD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BlE;AAiFD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,MAAM,CA6CR;AAqCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAqBjD;AA0CD,eAAO,MAAM,eAAe;;gBAEL,YAAY,YAAW,kBAAkB;CAc/D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAsCrD;AAmBD;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAU/C;AA4GD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAEzE;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAmBR;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,YAAoC,GAC7C,OAAO,CAkBT;AAGD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAEvE;AAGD,wBAAgB,qBAAqB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAE/D;AAGD,wBAAgB,yBAAyB,IAAI,YAAY,EAAE,CAW1D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,YAAY,EAAE,gBAAgB,GAC7B,IAAI,CAAC;AACR,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;AAmCvE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAGtF"}

package/dist/0-face/i18n.js

@@ -1,5 +1,5 @@
 import { LANGUAGES, LANGUAGE_METADATA, fallbackLanguages, isLanguage, languageOrder, normalizeLanguage, } from "./languages";
-import { configureLanguageRouting } from "./language-routing";
+import { configureLanguageRouting, parseLanguagePath } from "./language-routing";
 import { readLanguageFile, resolveText } from "./translations-format";
 // Bundled translations (keys.json may not exist - will use external translations if not available)
 // This is a fallback for when external translations aren't loaded
@@ -40,6 +40,8 @@ function storageKey() {
     return i18nOptions.storageKey || DEFAULT_STORAGE_KEY;
 }
 function readStoredLanguage() {
+    if (i18nOptions.persist === false)
+        return null;
     try {
         return storage()?.getItem(storageKey()) || null;
     }
@@ -48,6 +50,8 @@ function readStoredLanguage() {
     }
 }
 function storeLanguage(language) {
+    if (i18nOptions.persist === false)
+        return;
     try {
         storage()?.setItem(storageKey(), language);
     }
@@ -457,7 +461,7 @@ export function getBrowserLanguage() {
 // Current language
 // ============================================================================
 function dispatchLanguageChanged(language) {
-    if (typeof window === "undefined") {
+    if (typeof window === "undefined" || typeof window.dispatchEvent !== "function") {
         return;
     }
     window.dispatchEvent(new CustomEvent("language-changed", {
@@ -466,17 +470,40 @@ function dispatchLanguageChanged(language) {
         composed: true,
     }));
 }
+/** The language the address names (`/ja/…`), when the product takes it from there. */
+function addressLanguage() {
+    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() {
+    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) {
+    value: addressLanguage() || readStoredLanguage() || getBrowserLanguage(),
+    set: function (lang, options = {}) {
         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);
     },
@@ -488,19 +515,26 @@ export const currentLanguage = {
  * language's file if one is now configured.
  */
 export function configureI18n(next) {
+    const previousPersist = i18nOptions.persist;
     const previousKey = storageKey();
     const previousLanguages = i18nOptions.languages;
+    const previousAddress = i18nOptions.languageFromAddress;
+    const previousRouting = i18nOptions.routing;
     i18nOptions = { ...i18nOptions, ...next };
     applyRouting();
-    if (storageKey() !== previousKey ||
-        i18nOptions.languages !== previousLanguages) {
-        // The stored choice under the new key, or the browser's language, as one
-        // the product speaks
+    if (i18nOptions.persist !== previousPersist ||
+        storageKey() !== previousKey ||
+        i18nOptions.languages !== previousLanguages ||
+        i18nOptions.languageFromAddress !== previousAddress ||
+        (i18nOptions.languageFromAddress && i18nOptions.routing !== previousRouting)) {
+        // 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 = stored || getBrowserLanguage();
         if (stored && configuredLanguages()) {
             language = resolvePreferredLanguage(stored) ?? defaultLanguage;
         }
+        language = addressLanguage() ?? language;
         if (language !== currentLanguage.value) {
             currentLanguage.value = language;
             dispatchLanguageChanged(language);
@@ -518,10 +552,13 @@ function applyRouting() {
     if (!i18nOptions.routing && !i18nOptions.languages) {
         return;
     }
-    configureLanguageRouting({
+    configureLanguageRouting(routingOptions());
+}
+function routingOptions() {
+    return {
         ...(i18nOptions.languages ? { languages: i18nOptions.languages } : {}),
         ...i18nOptions.routing,
-    });
+    };
 }
 let sharedWordsLoad = null;
 /**
@@ -560,8 +597,11 @@ if (typeof window !== "undefined" && typeof document !== "undefined") {
         setTimeout(start, 0);
     }
 }
-// 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"));
@@ -571,7 +611,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"));
@@ -639,6 +679,9 @@ function reportMissingKey(key, language) {
 export function translate(key, params) {
     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[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
@@ -718,8 +761,11 @@ export function loadTranslations(languageOrMap, translations) {
         window.dispatchEvent(new CustomEvent("translations-ready"));
     }
 }
-// Set language (Portfolio pattern)
-export function setLanguage(language) {
+/**
+ * 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, options) {
     // The signal owns persistence, loading, document language and notification.
-    currentLanguage.set(language);
+    currentLanguage.set(language, options);
 }

package/dist/0-face/keys.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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);
+/** Give the key names of a product's own, or `null` to go back to the shared words (or English). */
+export declare function setKeyWords(next: KeyWords | null): void;
+/** A key's name as a word, in the page's language. */
+export declare function keyWord(word: KeyWord): string;
+/** True on a Mac, iPhone or iPad, where ⌘ is the command key and Ctrl-click is the right click. */
+export declare function isApplePlatform(): boolean;
+/** The command key's label: ⌘ on Apple platforms, Ctrl (in the page's language) elsewhere. */
+export declare function modKey(options?: ShortcutOptions): string;
+/** True when the command key is held: ⌘ on Apple platforms, Ctrl elsewhere. */
+export declare function isModKey(event: {
+    metaKey: boolean;
+    ctrlKey: boolean;
+}, options?: ShortcutOptions): boolean;
+/**
+ * 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 declare function isTyping(event: Event): boolean;
+/** Take a shortcut apart; `mod` becomes ⌘ (meta) on Apple platforms and Ctrl elsewhere. */
+export declare function parseShortcut(shortcut: string, options?: ShortcutOptions): Shortcut;
+/** True when a keydown is the shortcut. */
+export declare function matchesShortcut(event: KeyboardEvent, shortcut: string | Shortcut, options?: ShortcutOptions): boolean;
+/**
+ * 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 declare function shortcutLabel(shortcut: string, options?: ShortcutOptions): string;
+/** The value for `aria-keyshortcuts`: the modifiers and key by their KeyboardEvent names, `Meta+Shift+D`. */
+export declare function ariaKeyShortcuts(shortcut: string, options?: ShortcutOptions): string;
+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 declare function onShortcut(shortcut: string | string[], handler: (event: KeyboardEvent) => void, options?: OnShortcutOptions): () => void;
+//# sourceMappingURL=keys.d.ts.map

package/dist/0-face/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../DS1/0-face/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qEAAqE;AACrE,MAAM,MAAM,OAAO,GACf,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,GAC3F,eAAe,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,cAAc,CAAC;AAC5F,0EAA0E;AAC1E,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;AAYtF,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAEvD;AAED,sDAAsD;AACtD,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAW7C;AAED,mGAAmG;AACnG,wBAAgB,eAAe,IAAI,OAAO,CAKzC;AAID,8FAA8F;AAC9F,wBAAgB,MAAM,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAExD;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,KAAK,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAE1G;AAYD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAc9C;AAOD,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,CAcnF;AAYD,2CAA2C;AAC3C,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAYrH;AAsBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAYjF;AAED,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAIpF;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,4FAA4F;IAC5F,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,IAAI,CAuB5I"}