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

package/DS1/0-face/sidebar.ts

@@ -0,0 +1,201 @@
+/**
+ * The keyboard and pointer of a tree of rows, shared by `<ds-sidebar tree>`
+ * and the native `.ds-sidebar` classes of `row.css`.
+ *
+ * A tree is one stop for Tab: the row that has the focus (the selected row
+ * at first, otherwise the first) carries `tabindex="0"` and every other row
+ * `-1`. Up and Down move between rows that are not disabled, Home and End to
+ * the first and last; Right opens a closed row and enters an open one; Left
+ * closes an open row and moves to its parent; a printed character moves to
+ * the next row whose label starts with it. Space selects the row, Enter
+ * selects and activates it, as a double click does.
+ *
+ * `treeStep()` is that model alone, on the visible rows. `connectSidebar()`
+ * puts it on a native tree: rows with `role="treeitem"` and `aria-level`,
+ * flat, in order, inside an element with `role="tree"`. It dispatches the
+ * same events as `<ds-sidebar tree>` (`sidebar-toggle`, `sidebar-select`,
+ * `sidebar-activate`, each with `{ id }`), and unless the page cancels one
+ * it does what the event asks: opens or closes the row, hiding the rows
+ * inside it, or selects it.
+ */
+
+/** A visible row of a tree, as the keyboard sees it. */
+export interface TreeRow {
+  /** 1 for a row at the root. */
+  level: number;
+  /** `true` open, `false` closed; a leaf has none. */
+  expanded?: boolean;
+  disabled?: boolean;
+  /** The words the type-ahead matches. */
+  label?: string;
+}
+
+/** What a key asks of the tree: move the focus to a row, open or close the row, select or activate it. */
+export interface TreeStep {
+  focus?: number;
+  toggle?: boolean;
+  select?: boolean;
+  activate?: boolean;
+}
+
+const available = (rows: readonly TreeRow[], from: number, step: 1 | -1) => {
+  for (let index = from; index >= 0 && index < rows.length; index += step) if (!rows[index]!.disabled) return index;
+  return undefined;
+};
+
+/** The next row after `index` whose label starts with `letter`, from the top again after the last. */
+function typeahead(rows: readonly TreeRow[], index: number, letter: string) {
+  const wanted = letter.toLocaleLowerCase();
+  for (let offset = 1; offset <= rows.length; offset++) {
+    const at = (index + offset) % rows.length;
+    const row = rows[at]!;
+    if (!row.disabled && (row.label ?? "").trim().toLocaleLowerCase().startsWith(wanted)) return at;
+  }
+  return undefined;
+}
+
+/**
+ * What `key` does on the row at `index` of the visible `rows`, or
+ * `undefined` when the tree leaves the key alone.
+ */
+export function treeStep(rows: readonly TreeRow[], index: number, key: string): TreeStep | undefined {
+  const row = rows[index];
+  if (!row) return undefined;
+  switch (key) {
+    case "ArrowDown": return { focus: available(rows, index + 1, 1) ?? index };
+    case "ArrowUp": return { focus: available(rows, index - 1, -1) ?? index };
+    case "Home": return { focus: available(rows, 0, 1) ?? index };
+    case "End": return { focus: available(rows, rows.length - 1, -1) ?? index };
+    case "ArrowRight":
+      if (row.expanded === false) return row.disabled ? {} : { toggle: true };
+      if (row.expanded && (rows[index + 1]?.level ?? 0) > row.level) return { focus: available(rows, index + 1, 1) ?? index };
+      return {};
+    case "ArrowLeft": {
+      if (row.expanded && !row.disabled) return { toggle: false };
+      for (let at = index - 1; at >= 0; at--) if (rows[at]!.level < row.level) return rows[at]!.disabled ? {} : { focus: at };
+      return {};
+    }
+    case "Enter": return row.disabled ? {} : { select: true, activate: true };
+    case " ": return row.disabled ? {} : { select: true };
+    default: {
+      // One printed character, a letter outside the basic plane included; named keys are longer.
+      if (!/^\S$/u.test(key)) return undefined;
+      const at = typeahead(rows, index, key);
+      return at === undefined ? {} : { focus: at };
+    }
+  }
+}
+
+/** The events a tree sends, the same from `<ds-sidebar tree>` and a native tree. */
+export interface SidebarEvents {
+  "sidebar-toggle": CustomEvent<{ id: string; expanded: boolean }>;
+  "sidebar-select": CustomEvent<{ id: string }>;
+  "sidebar-activate": CustomEvent<{ id: string }>;
+}
+
+const ITEM = '[role="treeitem"]';
+const level = (item: Element) => Math.max(1, Number.parseInt(item.getAttribute("aria-level") ?? "1", 10) || 1);
+const expandedOf = (item: Element) => {
+  const value = item.getAttribute("aria-expanded");
+  return value === null ? undefined : value === "true";
+};
+const disabledOf = (item: Element) => item.getAttribute("aria-disabled") === "true";
+const labelOf = (item: Element) => (item.querySelector(".ds-sidebar__label") ?? item).textContent ?? "";
+/** A row's name in the events: `data-id`, else its `id`. */
+const idOf = (item: HTMLElement) => item.dataset.id ?? item.id;
+
+/**
+ * Gives a native tree its keyboard and pointer. Returns a function that
+ * takes them away again.
+ *
+ *   <ul class="ds-sidebar" role="tree" aria-label="Files">
+ *     <li class="ds-sidebar__item" role="treeitem" aria-level="1" aria-expanded="true" data-id="src">
+ *       <span class="ds-sidebar__disclosure" aria-hidden="true"></span>
+ *       <span class="ds-sidebar__label">src</span>
+ *     </li>
+ *     <li class="ds-sidebar__item" role="treeitem" aria-level="2" data-id="main">…</li>
+ *   </ul>
+ */
+export function connectSidebar(tree: HTMLElement): () => void {
+  const items = () => [...tree.querySelectorAll<HTMLElement>(ITEM)];
+  const visible = () => items().filter(item => !item.hidden && !item.closest("[hidden]"));
+
+  /** Exactly one visible row is the Tab stop: the focused one, else the selected one, else the first available. */
+  const rove = (focus?: HTMLElement) => {
+    const rows = visible();
+    const current = focus ?? rows.find(item => item.tabIndex === 0 && !disabledOf(item)) ?? rows.find(item => item.getAttribute("aria-selected") === "true") ?? rows.find(item => !disabledOf(item)) ?? rows[0];
+    for (const item of items()) item.tabIndex = item === current ? 0 : -1;
+    return current;
+  };
+
+  const send = <K extends keyof SidebarEvents>(name: K, detail: SidebarEvents[K]["detail"]) =>
+    tree.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true, cancelable: true }));
+
+  /** Opens or closes a row and shows or hides the rows inside it, keeping closed rows inside it closed. */
+  const toggle = (item: HTMLElement, expanded: boolean) => {
+    if (!send("sidebar-toggle", { id: idOf(item), expanded })) return;
+    item.setAttribute("aria-expanded", String(expanded));
+    const all = items();
+    const own = level(item);
+    let closedAt = Infinity;
+    for (const row of all.slice(all.indexOf(item) + 1)) {
+      const depth = level(row);
+      if (depth <= own) break;
+      if (depth <= closedAt) closedAt = Infinity;
+      row.hidden = !expanded || depth > closedAt;
+      if (expanded && !row.hidden && row.getAttribute("aria-expanded") === "false") closedAt = depth;
+    }
+    rove(item);
+  };
+
+  const select = (item: HTMLElement) => {
+    if (!send("sidebar-select", { id: idOf(item) })) return;
+    for (const row of items()) if (row.hasAttribute("aria-selected") || row === item) row.setAttribute("aria-selected", String(row === item));
+  };
+
+  const focus = (item: HTMLElement) => { rove(item); item.focus(); };
+
+  const keydown = (event: KeyboardEvent) => {
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
+    const item = (event.target as Element | null)?.closest<HTMLElement>(ITEM);
+    if (!item || !tree.contains(item)) return;
+    const rows = visible();
+    const step = treeStep(rows.map(row => ({ level: level(row), expanded: expandedOf(row), disabled: disabledOf(row), label: labelOf(row) })), rows.indexOf(item), event.key);
+    if (!step) return;
+    event.preventDefault();
+    if (step.toggle !== undefined) toggle(item, step.toggle);
+    if (step.select) select(item);
+    if (step.activate) send("sidebar-activate", { id: idOf(item) });
+    if (step.focus !== undefined && rows[step.focus]) focus(rows[step.focus]!);
+  };
+
+  const click = (event: MouseEvent) => {
+    const item = (event.target as Element | null)?.closest<HTMLElement>(ITEM);
+    if (!item || !tree.contains(item) || disabledOf(item)) return;
+    const disclosure = (event.target as Element).closest(".ds-sidebar__disclosure");
+    if (disclosure && expandedOf(item) !== undefined) toggle(item, !expandedOf(item));
+    else select(item);
+    focus(item);
+  };
+
+  const dblclick = (event: MouseEvent) => {
+    const item = (event.target as Element | null)?.closest<HTMLElement>(ITEM);
+    if (!item || !tree.contains(item) || disabledOf(item) || (event.target as Element).closest(".ds-sidebar__disclosure")) return;
+    send("sidebar-activate", { id: idOf(item) });
+  };
+
+  if (!tree.hasAttribute("role")) tree.setAttribute("role", "tree");
+  rove();
+  // Rows the page adds or removes keep one Tab stop.
+  const observer = typeof MutationObserver === "undefined" ? undefined : new MutationObserver(() => { if (!items().some(item => item.tabIndex === 0 && !item.hidden)) rove(); });
+  observer?.observe(tree, { childList: true, subtree: true });
+  tree.addEventListener("keydown", keydown);
+  tree.addEventListener("click", click);
+  tree.addEventListener("dblclick", dblclick);
+  return () => {
+    observer?.disconnect();
+    tree.removeEventListener("keydown", keydown);
+    tree.removeEventListener("click", click);
+    tree.removeEventListener("dblclick", dblclick);
+  };
+}

package/DS1/0-face/theme-bootstrap.js

@@ -0,0 +1,184 @@
+/**
+ * Design system 1's theme, on before the first paint.
+ *
+ * A classic script for the <head>: inline it before the stylesheets, or load it
+ * there with a plain <script src> (not a module), which holds rendering until
+ * it has run. It needs nothing else and waits for nothing.
+ *
+ * It reads the stored choice, light, dark or system, and puts the theme on
+ * the root element at once (with nothing stored, `themeDefault`: system
+ * unless the product says light or dark):
+ * - the class `light-theme` or `dark-theme`, the canonical mark the
+ *   stylesheets key on;
+ * - `data-theme="light"` or `"dark"`, the same, for pages that key on it;
+ * - `color-scheme`, so light-dark() tokens and the browser's controls follow;
+ * - `--lightningcss-light` and `--lightningcss-dark`, so CSS compiled with
+ *   Lightning CSS's light-dark() fallback follows the choice, not the system;
+ * - the canvas behind the page and the theme-color meta, in the paper.
+ * It also sets `lang` from the language module's stored choice, or from the
+ * address when the product takes the language from there.
+ *
+ * Then it keeps the page right: in system mode it follows
+ * prefers-color-scheme as it changes, and it applies the choice again when
+ * another tab stores one and when a page returns from the back-forward cache.
+ * A change after the first paint crosses over in a view transition of the
+ * root, unless the reader asks for reduced motion.
+ *
+ * `window.DS_ONE_THEME` is the runtime: `mode()`, `theme()`, `set(mode)` and
+ * `apply()`; a change dispatches `theme-changed` on window with
+ * `{ theme, mode }`. `0-face/theme.ts` runs this same file, so the components
+ * and a page without them share one implementation, whichever loads first.
+ *
+ * Set options before it on `window.DS_ONE_PREFERENCES`: `themeStorageKey`
+ * (`"ds-one:theme"` by default), `themeDefault` (`"light"`, `"dark"` or
+ * `"system"`, the default) for a visitor who has chosen nothing yet,
+ * `themeMode: "system"` to follow the system and never read or write a stored
+ * choice, and `themePaper` as `{ light, dark }` colours for the canvas, or
+ * `false` to leave the background and theme-color to the page. The language
+ * follows `window.DS_ONE_I18N`: `storageKey` (`"language"`), `persist: false`,
+ * `languages`, `routing` with `languageFromAddress: true` (a prefix such as
+ * `/ja/…` wins over the stored choice), and `langTarget` (set, the root's
+ * `lang` is left alone).
+ */
+(function () {
+  if (typeof window === "undefined" || typeof document === "undefined" || window.DS_ONE_THEME) return;
+  var root = document.documentElement;
+  var MODES = ["light", "dark", "system"];
+  // Design system 1's languages (0-face/languages.ts), the prefixes an address may carry by default.
+  var LANGUAGES = ["da", "de", "en", "es", "fi", "fr", "is", "it", "ja", "ko", "nb", "nn", "no", "pt", "pt-BR", "sv", "zh"];
+  var PAPER = { light: "#ffffff", dark: "#2a2a2a" };
+  // A choice that cannot be stored, or one made while the page follows the system, lasts for this page.
+  var session = null;
+  var shown = null;
+  var shownMode = null;
+  var crossing = null;
+
+  function options() { return window.DS_ONE_PREFERENCES || {}; }
+  function key() { return options().themeStorageKey || "ds-one:theme"; }
+  function query(media) {
+    try { return window.matchMedia ? window.matchMedia(media) : null; } catch { return null; }
+  }
+
+  function mode() {
+    if (session) return session;
+    if (options().themeMode === "system") return "system";
+    try {
+      var stored = window.localStorage.getItem(key());
+      if (MODES.indexOf(stored) >= 0) return stored;
+    } catch { /* Storage can be blocked. */ }
+    var first = options().themeDefault;
+    return MODES.indexOf(first) >= 0 ? first : "system";
+  }
+
+  function resolve(choice) {
+    if (choice !== "system") return choice;
+    var system = query("(prefers-color-scheme: dark)");
+    return system && system.matches ? "dark" : "light";
+  }
+
+  function paint(theme) {
+    root.classList.remove(theme === "dark" ? "light-theme" : "dark-theme");
+    root.classList.add(theme + "-theme");
+    root.setAttribute("data-theme", theme);
+    root.style.colorScheme = theme;
+    root.style.setProperty("--lightningcss-light", theme === "light" ? "initial" : " ");
+    root.style.setProperty("--lightningcss-dark", theme === "dark" ? "initial" : " ");
+    var paper = options().themePaper;
+    if (paper === false) return;
+    var colour = (paper && paper[theme]) || PAPER[theme];
+    root.style.backgroundColor = colour;
+    var meta = document.querySelector('meta[name="theme-color"]:not([media])');
+    if (!meta && document.head) {
+      meta = document.createElement("meta");
+      meta.setAttribute("name", "theme-color");
+      document.head.appendChild(meta);
+    }
+    if (meta) meta.setAttribute("content", colour);
+  }
+
+  // The two themes are two pictures of one page: cross from one to the other.
+  function cross(theme) {
+    var reduced = query("(prefers-reduced-motion: reduce)");
+    if (typeof document.startViewTransition !== "function" || (reduced && reduced.matches) || document.visibilityState === "hidden") {
+      paint(theme);
+      return;
+    }
+    if (crossing) crossing.skipTransition();
+    var painted = false;
+    var once = function () { if (!painted) { painted = true; paint(theme); } };
+    try {
+      var transition = document.startViewTransition(once);
+      crossing = transition;
+      // A skipped crossing rejects all three promises; none may swallow the change.
+      void transition.ready.catch(function () {});
+      void transition.updateCallbackDone.catch(once);
+      void transition.finished.catch(function () {}).then(function () { if (crossing === transition) crossing = null; });
+    } catch {
+      once();
+    }
+  }
+
+  function apply() {
+    var choice = mode();
+    var theme = resolve(choice);
+    var first = shown === null;
+    var moved = theme !== shown || choice !== shownMode;
+    if (!first && theme !== shown) cross(theme);
+    else paint(theme);
+    shown = theme;
+    shownMode = choice;
+    if (!first && moved) window.dispatchEvent(new CustomEvent("theme-changed", { detail: { theme: theme, mode: choice } }));
+  }
+
+  function set(choice) {
+    if (MODES.indexOf(choice) < 0) return;
+    session = null;
+    if (options().themeMode === "system") {
+      if (choice !== "system") session = choice;
+    } else {
+      try { window.localStorage.setItem(key(), choice); } catch { session = choice; }
+    }
+    apply();
+  }
+
+  var i18n = window.DS_ONE_I18N || {};
+  // The language an address names in its first segment (`/pt-br/…` gives pt-BR), as the language module reads it.
+  function addressLanguage() {
+    if (!i18n.languageFromAddress) return null;
+    var routing = i18n.routing || {};
+    var prefixed = (routing.languages && routing.languages.length ? routing.languages : null) || (i18n.languages && i18n.languages.length ? i18n.languages : null) || LANGUAGES;
+    var segment = String((window.location && window.location.pathname) || "").split("/")[1] || "";
+    var slug = segment.toLowerCase().replace(/_/g, "-");
+    if (!slug) return null;
+    for (var index = 0; index < prefixed.length; index++) {
+      if (String(prefixed[index]).toLowerCase().replace(/_/g, "-") === slug) return String(prefixed[index]);
+    }
+    return null;
+  }
+  function storedLanguage() {
+    if (i18n.persist === false) return null;
+    try {
+      var language = window.localStorage.getItem(i18n.storageKey || "language");
+      if (language && (!i18n.languages || i18n.languages.indexOf(language) >= 0)) return language;
+    } catch { /* Storage can be blocked. */ }
+    return null;
+  }
+  if (i18n.langTarget === undefined) {
+    var language = addressLanguage() || storedLanguage();
+    if (language && /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(language)) root.lang = language;
+  }
+
+  window.DS_ONE_THEME = {
+    mode: function () { return shownMode; },
+    theme: function () { return shown; },
+    set: set,
+    apply: function () { apply(); },
+  };
+  apply();
+
+  var system = query("(prefers-color-scheme: dark)");
+  if (system && system.addEventListener) system.addEventListener("change", function () { apply(); });
+  else if (system && system.addListener) system.addListener(function () { apply(); });
+  window.addEventListener("storage", function (event) { if (event.key === null || event.key === key()) apply(); });
+  window.addEventListener("pageshow", function () { apply(); });
+})();

package/DS1/0-face/theme.ts

@@ -1,58 +1,100 @@
+/**
+ * Light, dark or system, remembered in one stored choice.
+ *
+ * The runtime is `theme-bootstrap.js`, the classic script a page inlines in
+ * its <head> so the first paint is already in the chosen theme. Imported here
+ * as well, it installs itself when the page did not inline it, so the
+ * components and a page without them share one implementation. This module
+ * mirrors it in signals for the components.
+ *
+ * The theme is marked on the root element by the class `light-theme` or
+ * `dark-theme` (canonical), `data-theme="light|dark"` (for pages that key on
+ * the attribute) and `color-scheme`. In system mode it follows
+ * prefers-color-scheme as it changes. A visitor who has chosen nothing sees
+ * `themeDefault` from `window.DS_ONE_PREFERENCES` (system unless the product
+ * says light or dark).
+ *
+ * A page without the components copies it with Sync 1's `root` export,
+ * `"modules": ["theme"]` (this file, the head script and the options type);
+ * it needs `@lit-labs/signals`.
+ */
 import { signal } from "@lit-labs/signals";
-import { preferenceStorageKey } from "./preferences";
+import "./theme-bootstrap.js";
+import type { PreferenceOptions } from "./preference-options";
 
+/** The theme on the page. */
 export type ThemeType = "light" | "dark";
+/** The stored choice: a theme, or the system's. */
+export type ThemeMode = ThemeType | "system";
+export const THEME_MODES: readonly ThemeMode[] = ["light", "dark", "system"];
 
-function getInitialTheme(): ThemeType {
-  if (typeof window === "undefined") {
-    return "light";
-  }
+/** `window.DS_ONE_THEME`, installed by `theme-bootstrap.js`. */
+export interface ThemeRuntime {
+  /** The choice in effect: light, dark or system. */
+  mode(): ThemeMode;
+  /** The theme on the page. */
+  theme(): ThemeType;
+  /** Choose and remember light, dark or system, and put it on the page. */
+  set(mode: ThemeMode): void;
+  /** Read the stored choice, the options and the system again, and put them on the page. */
+  apply(): void;
+}
+
+declare global {
+  interface Window { DS_ONE_THEME?: ThemeRuntime; }
+}
+
+function runtime(): ThemeRuntime | undefined {
+  return typeof window === "undefined" ? undefined : window.DS_ONE_THEME;
+}
+
+// Options set since the head script ran (a product's storage key, system mode) take effect now.
+runtime()?.apply();
 
-  let storedTheme: string | null = null;
-  try { storedTheme = window.localStorage?.getItem(preferenceStorageKey("theme")); } catch { /* Storage can be unavailable. */ }
-  if (storedTheme === "light" || storedTheme === "dark") {
-    return storedTheme;
-  }
+export const currentTheme = signal<ThemeType>(runtime()?.theme() ?? "light");
+export const currentThemeMode = signal<ThemeMode>(runtime()?.mode() ?? "system");
 
-  // Check system preference
-  const prefersDark = window.matchMedia?.("(prefers-color-scheme: dark)").matches;
-  return prefersDark ? "dark" : "light";
+function sync(): void {
+  const theme = runtime();
+  if (!theme) return;
+  currentTheme.set(theme.theme());
+  currentThemeMode.set(theme.mode());
 }
 
-export const currentTheme = signal<ThemeType>(getInitialTheme());
+if (typeof window !== "undefined") window.addEventListener("theme-changed", sync);
 
+export function getThemeMode(): ThemeMode {
+  return runtime()?.mode() ?? currentThemeMode.get();
+}
+
+/** Choose light, dark or system, store it and put it on the page; `theme-changed` follows a change. */
+export function setThemeMode(mode: ThemeMode): void {
+  runtime()?.set(mode);
+  sync();
+}
+
+/** Choose light or dark. `setThemeMode("system")` hands the choice back to the system. */
 export function setTheme(theme: ThemeType): void {
-  if (theme === currentTheme.get()) {
-    return;
-  }
-
-  currentTheme.set(theme);
-
-  if (typeof window !== "undefined") {
-    try {
-      window.localStorage?.setItem(preferenceStorageKey("theme"), theme);
-    } catch (error) {
-      console.warn("ds-one: unable to persist theme preference", error);
-    }
-
-    const root = window.document?.documentElement;
-    if (root) {
-      root.classList.remove("light-theme", "dark-theme");
-      root.classList.add(`${theme}-theme`);
-    }
-
-    window.dispatchEvent(
-      new CustomEvent("theme-changed", { detail: { theme } })
-    );
-  }
-}
-
-// Initialize theme on load
-if (typeof window !== "undefined") {
-  const theme = currentTheme.get();
-  const root = window.document?.documentElement;
-  if (root) {
-    root.classList.remove("light-theme", "dark-theme");
-    root.classList.add(`${theme}-theme`);
-  }
+  setThemeMode(theme);
+}
+
+/**
+ * Bind an automatic surface to system appearance, leaving stored choices
+ * intact: nothing is read from or written to storage until the returned
+ * function hands the page back to its stored choice.
+ */
+export function followSystemTheme(): () => void {
+  if (typeof window === "undefined") return () => {};
+  const previous = window.DS_ONE_PREFERENCES?.themeMode;
+  const following: PreferenceOptions = { ...window.DS_ONE_PREFERENCES, themeMode: "system" };
+  window.DS_ONE_PREFERENCES = following;
+  setThemeMode("system");
+  return () => {
+    const options = { ...window.DS_ONE_PREFERENCES };
+    if (previous) options.themeMode = previous;
+    else delete options.themeMode;
+    window.DS_ONE_PREFERENCES = options;
+    runtime()?.apply();
+    sync();
+  };
 }