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

package/DS1/0-face/languages.ts

@@ -1,5 +1,5 @@
 /**
- * The languages every 0001 product chooses from: one list, with the name of
+ * The languages every 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.
  *
@@ -105,8 +105,8 @@ export const LANGUAGE_METADATA: Readonly<Record<Language, LanguageMetadata>> = {
 
 /**
  * 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
+ * that speaks only one of them gets it for the others (one that speaks `nb`
+ * reads `no` and `nn` as `nb`; one that speaks `pt-BR` reads `pt` as it), and
  * a missing word is looked up in them before English.
  */
 const RELATED_LANGUAGES: Readonly<Partial<Record<Language, readonly Language[]>>> = {
@@ -150,7 +150,7 @@ function within(language: Language, allowed: ReadonlySet<Language>): Language |
  * `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
+ * `nb` and `pt-BR` among them, `no` and `nn` read as `nb`, and `pt` as `pt-BR`. Returns
  * `fallback` when nothing matches (`null` to tell).
  */
 export function normalizeLanguage(

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

@@ -66,7 +66,7 @@ export function createLayoutInspector() {
     }
     @media print { :host { display: none !important; } }
   </style><div class="veil"></div><div class="areas"></div>`;
-  document.body.append(overlay);
+  document.body.appendChild(overlay);
   const layer = shadow.querySelector<HTMLDivElement>('.areas')!;
   const colors = ['#efc9dc', '#d5c9ef', '#c2d9eb', '#bfe0cd', '#eee3b7', '#efcfb8'];
   let frame = 0;
@@ -115,7 +115,7 @@ export function createLayoutInspector() {
       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]);
+      panel.style.setProperty('--pastel', colors[index % colors.length] ?? null);
       const label = document.createElement('span');
       label.className = 'name';
       const areaName = element.dataset.dsArea || element.getAttribute('aria-label') ||
@@ -124,7 +124,7 @@ export function createLayoutInspector() {
       const dimensions = document.createElement('span');
       dimensions.className = 'dimensions';
       dimensions.textContent = `${Number(rect.width.toFixed(1))} × ${Number(rect.height.toFixed(1))} px`;
-      label.append(dimensions);
+      label.appendChild(dimensions);
       const ratio = document.createElement('span');
       ratio.className = 'dimensions';
       // Reduce dimensions measured to a tenth of a CSS pixel; use a decimal
@@ -141,9 +141,9 @@ export function createLayoutInspector() {
       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);
+      label.appendChild(ratio);
+      panel.appendChild(label);
+      fragments.appendChild(panel);
     });
     layer.replaceChildren(fragments);
   };

package/DS1/0-face/library-styles.ts

@@ -0,0 +1,33 @@
+/** A published library owns appearance; its last published snapshot covers offline starts. */
+export function connectLibraryStyles(options: {
+  url: string;
+  fallback: string;
+  document?: Document;
+}): () => void {
+  const doc = options.document ?? document;
+  const fallback = doc.createElement("style");
+  fallback.dataset.designLibrary = "fallback";
+  fallback.textContent = options.fallback;
+  const published = doc.createElement("link");
+  published.rel = "stylesheet";
+  published.href = options.url;
+  published.dataset.designLibrary = "published";
+  const loaded = () => {
+    // Replace, rather than layer: deleting a library rule must really delete it.
+    fallback.disabled = true;
+    published.dataset.state = "published";
+  };
+  const failed = () => {
+    fallback.disabled = false;
+    published.dataset.state = "fallback";
+  };
+  published.addEventListener("load", loaded);
+  published.addEventListener("error", failed);
+  doc.head.append(fallback, published);
+  return () => {
+    published.removeEventListener("load", loaded);
+    published.removeEventListener("error", failed);
+    published.remove();
+    fallback.remove();
+  };
+}

package/DS1/0-face/load-toaster.ts

@@ -0,0 +1,7 @@
+/**
+ * The page toaster as copyText loads it, when it shows a toast and nothing in
+ * the page draws toasts yet. Its own module, so a bundler splits the toaster
+ * off for a page that imports copyText alone (`./copy-text.ts`), and keeps it
+ * where the page imports it anyway (`./feedback.ts`) without a warning.
+ */
+export { pageToaster } from "./toaster";

package/DS1/0-face/preference-options.ts

@@ -0,0 +1,29 @@
+/**
+ * The options a page sets on `window.DS_ONE_PREFERENCES` before the theme
+ * and preference modules load: product storage names and the theme's
+ * defaults. Product storage names are configuration; the implementation stays
+ * shared. It imports nothing, so the theme module travels with it alone.
+ */
+export interface PreferenceOptions {
+  storageKey?: string;
+  themeStorageKey?: string;
+  /** Follow system appearance without reading or writing a saved theme. */
+  themeMode?: "system";
+  /**
+   * The theme a visitor who has chosen nothing sees: `"system"` (the
+   * default) follows the system, `"light"` or `"dark"` keeps that theme until
+   * they choose. A stored choice always wins; `themeMode: "system"` wins over
+   * both.
+   */
+  themeDefault?: "light" | "dark" | "system";
+  /**
+   * The canvas behind the page and the browser's theme-color, per theme, set
+   * by the theme runtime before the first paint: Design system 1's paper
+   * (`--background`) by default. `false` leaves both to the page.
+   */
+  themePaper?: { light: string; dark: string } | false;
+}
+
+declare global {
+  interface Window { DS_ONE_PREFERENCES?: PreferenceOptions; }
+}

package/DS1/0-face/preferences.ts

@@ -1,21 +1,13 @@
 import type { LanguageCode } from "./i18n";
-import type { ThemeType } from "./theme";
+import type { ThemeMode } from "./theme";
 
 export type Preferences = {
   language?: LanguageCode;
-  theme?: ThemeType;
+  theme?: ThemeMode;
   [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 type { PreferenceOptions } from "./preference-options";
 
 export function preferenceStorageKey(kind: "preferences" | "theme"): string {
   const options = typeof window === "undefined" ? undefined : window.DS_ONE_PREFERENCES;

package/DS1/0-face/pricing.ts

@@ -1,57 +1,112 @@
 /**
- * Currency label utilities for regional price display
- *
- * Note: This module provides currency symbols/labels based on language and region.
- * Consider moving this functionality into i18n.ts as it's region/locale-related.
- * Actual price values will be stored in a database or managed via Stripe.
+ * The currency a reader is most likely to think in, from their language or
+ * country, and prices written in it. The amounts themselves come from the
+ * product's billing (a payment service or its database); this only says how
+ * they read. Writing them is `formatMoney` in `./format`.
  */
-
+import { currencySymbol, formatMoney } from "./format";
+import type { MoneyOptions } from "./format";
+import { currentLanguage } from "./i18n";
 import type { LanguageCode } from "./i18n";
 
 type PriceLabelOptions = {
-  language: LanguageCode;
+  /** The reader's language. Defaults to the current language. */
+  language?: LanguageCode;
+  /** The reader's country, when known (`US`, `GB`, `JP`); it wins over the language. */
   country?: string;
 };
 
-// Simple price label mapping based on language/country
+/** The currency each language's readers most often pay in. */
+const LANGUAGE_CURRENCIES: Record<string, string> = {
+  da: "DKK",
+  de: "EUR",
+  en: "USD",
+  es: "EUR",
+  fi: "EUR",
+  fr: "EUR",
+  is: "ISK",
+  it: "EUR",
+  ja: "JPY",
+  ko: "KRW",
+  nb: "NOK",
+  nn: "NOK",
+  no: "NOK",
+  pt: "EUR",
+  "pt-br": "BRL",
+  sv: "SEK",
+  zh: "CNY",
+};
+
+const COUNTRY_CURRENCIES: Record<string, string> = {
+  US: "USD",
+  USA: "USD",
+  GB: "GBP",
+  UK: "GBP",
+  JP: "JPY",
+  JPN: "JPY",
+  CN: "CNY",
+  CHN: "CNY",
+  KR: "KRW",
+  KOR: "KRW",
+};
+
+/**
+ * The short labels `getPriceLabel` has always given. Other currencies read
+ * the symbol the language writes them with.
+ */
 const PRICE_LABELS: Record<string, string> = {
-  da: "kr.",
-  nb: "kr.",
-  sv: "kr.",
-  de: "€",
-  en: "$",
-  pt: "€",
-  es: "€",
-  zh: "¥",
-  ja: "¥",
-  ko: "₩",
+  DKK: "kr.",
+  NOK: "kr.",
+  SEK: "kr.",
+  ISK: "kr.",
+  EUR: "€",
+  USD: "$",
+  GBP: "£",
+  JPY: "¥",
+  CNY: "¥",
+  KRW: "₩",
+  BRL: "R$",
 };
 
-export function getPriceLabel(options: PriceLabelOptions): string {
-  const { language, country } = options;
-
-  // If country is provided, try to map it to a currency
-  if (country) {
-    const countryUpper = country.toUpperCase();
-    // Add country-specific mappings if needed
-    if (countryUpper === "US" || countryUpper === "USA") {
-      return "$";
-    }
-    if (countryUpper === "GB" || countryUpper === "UK") {
-      return "£";
-    }
-    if (countryUpper === "JP" || countryUpper === "JPN") {
-      return "¥";
-    }
-    if (countryUpper === "CN" || countryUpper === "CHN") {
-      return "¥";
-    }
-    if (countryUpper === "KR" || countryUpper === "KOR") {
-      return "₩";
-    }
+/**
+ * The currency (ISO 4217 code) for a reader: their country's when it is
+ * known, else their language's, else USD. `pt-BR` reads BRL.
+ */
+export function getPriceCurrency(options: PriceLabelOptions = {}): string {
+  const country = options.country?.toUpperCase();
+  if (country && COUNTRY_CURRENCIES[country]) {
+    return COUNTRY_CURRENCIES[country];
   }
 
-  // Fall back to language-based mapping
-  const primaryLang = language.toLowerCase().split(/[-_]/)[0];
-  return PRICE_LABELS[primaryLang] || "$";
+  const language = String(options.language || currentLanguage.value || "en")
+    .toLowerCase()
+    .replace(/_/g, "-");
+  const primary = language.split("-")[0] ?? "";
+  return LANGUAGE_CURRENCIES[language] ?? LANGUAGE_CURRENCIES[primary] ?? "USD";
+}
+
+/** The currency label for a reader: `kr.`, `€`, `$`, `£`, `¥`, `₩`. */
+export function getPriceLabel(options: PriceLabelOptions = {}): string {
+  const currency = getPriceCurrency(options);
+  return (
+    PRICE_LABELS[currency] ??
+    currencySymbol(currency, { language: options.language })
+  );
+}
+
+/**
+ * A price for a reader: in `currency`, or the reader's currency
+ * (`getPriceCurrency`) when none is given, written in their language.
+ * `minor` reads the amount in cents, as payment services send it.
+ */
+export function formatPrice(
+  amount: number,
+  options: PriceLabelOptions & MoneyOptions & { currency?: string } = {}
+): string {
+  const { country, currency, ...money } = options;
+  return formatMoney(
+    amount,
+    currency ?? getPriceCurrency({ language: options.language, country }),
+    money
+  );
 }

package/DS1/0-face/scaling.ts

@@ -1,15 +1,64 @@
-/* Design system 1 responsive scale calculation, shared with native HTML sites */
+/**
+ * Design system 1's scale, `--sf`: every measure is multiplied by it.
+ *
+ * A computer stays at 1, however narrow its window. A phone or a tablet (a
+ * mobile browser, or a touch screen whose shorter side is at most 820px) is
+ * drawn as if the screen were 280 units wide: the scale is the page's width
+ * over 280, never under 0.75 or over 2, so a 375px phone draws everything a
+ * third larger.
+ *
+ * `startScaling()` puts the scale on the page and keeps it there through
+ * resizes and turns; `applyScaling()` does it once. Both set `--sf` and, on a
+ * phone or tablet, `data-mobile` on the root element. The module imports
+ * nothing, so a page without the components copies it alone (Sync 1's `root`
+ * export with `"modules": ["scaling"]`). Call it before the page renders, and
+ * the first paint is already to scale.
+ *
+ * A surface, such as a phone drawn on a page, scales to its own width
+ * instead: `startScaling({ surface: element })`, or `surface: true` for every
+ * `[data-ds-surface]` element. The same rule and snapping apply, on any
+ * device, and `--sf` and `--ds-sf` go on the surface alone.
+ */
 export type ScalingMode = "auto" | "fixed" | "fluid";
 
+/**
+ * How the scale is rounded. `"layout"`: a square (20 units) is a whole number
+ * of the 1/64px steps browsers lay pages out in, so a long run of rows stays on
+ * ruled lines drawn exactly. `"pixel"`: a square is a whole number of device
+ * pixels, rounded down, so every grid line and hairline stays sharp.
+ * Without it the scale keeps three decimals.
+ */
+export type ScalingSnap = "layout" | "pixel" | false;
+
 export interface ScalingConfig {
   mode: ScalingMode;
   baseWidth: number;
   minScale: number;
   maxScale: number;
+  snap?: ScalingSnap;
+}
+
+export interface ScalingOptions extends Partial<ScalingConfig> {
+  /**
+   * The element that receives `--sf` and `data-mobile`; the document's root by
+   * default. With an element `surface`, the element that receives that
+   * surface's `--sf` (the surface itself by default).
+   */
+  root?: HTMLElement;
+  /**
+   * Scale to a surface's own width rather than the page's: an element (a
+   * phone drawn on a page), or `true` for every element marked
+   * `data-ds-surface` in the document when the call is made. A surface is
+   * measured by its `clientWidth` and scaled on any device, a computer too,
+   * with the same rule and snapping; `--sf` and `--ds-sf` (for the shared
+   * components inside) go on the surface, the page and `data-mobile` are left
+   * alone. Its width must not depend on its own scale.
+   */
+  surface?: HTMLElement | boolean;
 }
 
 // ============================================================================
-// Configuration & Signals
+// Configuration
 // ============================================================================
 
 export const defaultScalingConfig: ScalingConfig = {
@@ -19,7 +68,114 @@ export const defaultScalingConfig: ScalingConfig = {
   maxScale: 2.0,
 };
 
-export function calculateScalingFactor(viewportWidth: number, config: ScalingConfig = defaultScalingConfig): number {
+/** One square in units. */
+const SQUARE = 20;
+/** Browsers lay pages out in 1/64px steps. */
+const LAYOUT_STEPS = 64;
+
+/** The factor, rounded so that a square is a whole number of 1/64px layout steps. */
+export function toLayoutStep(factor: number): number {
+  return Math.round(factor * SQUARE * LAYOUT_STEPS) / (SQUARE * LAYOUT_STEPS);
+}
+
+/** The factor, rounded down so that a square is a whole number of device pixels. */
+export function toDevicePixel(factor: number, pixelRatio = 1): number {
+  const ratio = pixelRatio > 0 ? pixelRatio : 1;
+  return Math.floor(factor * SQUARE * ratio) / (SQUARE * ratio);
+}
+
+export function calculateScalingFactor(viewportWidth: number, config: ScalingConfig = defaultScalingConfig, pixelRatio = 1): number {
   if (config.mode === "fixed") return 1;
-  return Number(Math.max(config.minScale, Math.min(config.maxScale, viewportWidth / config.baseWidth)).toFixed(3));
+  const factor = Math.max(config.minScale, Math.min(config.maxScale, viewportWidth / config.baseWidth));
+  if (config.snap === "layout") return toLayoutStep(factor);
+  if (config.snap === "pixel") return toDevicePixel(factor, pixelRatio);
+  return Number(factor.toFixed(3));
+}
+
+// ============================================================================
+// Device
+// ============================================================================
+
+/**
+ * Whether the page is on a phone or a tablet, the screens that scale: the
+ * browser says it is mobile, or the screen takes touch and its shorter side
+ * is at most 820px. A computer is never one, however narrow its window.
+ */
+export function detectMobileDevice(): boolean {
+  if (typeof navigator === "undefined" || typeof window === "undefined") return false;
+  const agent = navigator.userAgent || navigator.vendor || "";
+  const byAgent = /Mobile|Android|iP(ad|hone|od)|IEMobile|BlackBerry|Kindle|Silk-Accelerated|(hpw|web)OS|Opera M(obi|ini)|Windows Phone|Phone|Tablet/i.test(agent);
+  const touch = (navigator.maxTouchPoints || 0) > 1;
+  const narrow = Math.min(window.innerWidth || 0, window.innerHeight || 0) <= 820;
+  return byAgent || (touch && narrow);
+}
+
+// ============================================================================
+// Applying the scale
+// ============================================================================
+
+/** The surfaces a call scales: the element given, or every `[data-ds-surface]` for `true`. */
+function surfacesOf(surface: ScalingOptions["surface"]): HTMLElement[] {
+  if (!surface) return [];
+  if (surface === true) return Array.from(document.querySelectorAll<HTMLElement>("[data-ds-surface]"));
+  return [surface];
+}
+
+/** Scales one surface to its own width, whatever the device. */
+function applySurface(surface: HTMLElement, target: HTMLElement, config: Partial<ScalingConfig>): number {
+  const factor = calculateScalingFactor(surface.clientWidth || 0, { ...defaultScalingConfig, ...config }, window.devicePixelRatio || 1);
+  // Shared components inside read --ds-sf, resolved at their own host, so they draw at the surface's scale too.
+  target.style.setProperty("--sf", String(factor));
+  target.style.setProperty("--ds-sf", String(factor));
+  return factor;
+}
+
+/**
+ * Puts the scale on the page once: `--sf`, and `data-mobile` on a phone or
+ * tablet. With `surface`, puts each surface's own scale on it instead. Returns
+ * the factor (the first surface's, or 1 when there is none).
+ */
+export function applyScaling(options: ScalingOptions = {}): number {
+  if (typeof document === "undefined" || typeof window === "undefined") return 1;
+  const { root, surface, ...config } = options;
+  if (surface) {
+    const factors = surfacesOf(surface).map(element => applySurface(element, (surface !== true && root) || element, config));
+    return factors[0] ?? 1;
+  }
+  return applyPage(root ?? document.documentElement, config);
+}
+
+function applyPage(root: HTMLElement, config: Partial<ScalingConfig>): number {
+  const mobile = detectMobileDevice();
+  // The page's width without its scroll bar.
+  const width = document.documentElement.clientWidth || window.innerWidth || 0;
+  const factor = mobile ? calculateScalingFactor(width, { ...defaultScalingConfig, ...config }, window.devicePixelRatio || 1) : 1;
+  root.style.setProperty("--sf", String(factor));
+  root.toggleAttribute("data-mobile", mobile);
+  return factor;
+}
+
+/**
+ * Puts the scale on the page now and again on every resize and turn; a
+ * surface is followed as its own size changes. Returns a function that stops
+ * following.
+ */
+export function startScaling(options: ScalingOptions = {}): () => void {
+  if (typeof window === "undefined" || typeof document === "undefined") return () => {};
+  const { root, surface, ...config } = options;
+  // Surfaces are found once, so the same ones are followed until stopped.
+  const surfaces = surfacesOf(surface);
+  const apply = surface
+    ? () => { for (const element of surfaces) applySurface(element, (surface !== true && root) || element, config); }
+    : () => { applyPage(root ?? document.documentElement, config); };
+  apply();
+  const observer = surfaces.length && typeof ResizeObserver === "function" ? new ResizeObserver(apply) : null;
+  for (const element of surfaces) observer?.observe(element);
+  window.addEventListener("resize", apply);
+  window.addEventListener("orientationchange", apply);
+  return () => {
+    observer?.disconnect();
+    window.removeEventListener("resize", apply);
+    window.removeEventListener("orientationchange", apply);
+  };
 }

package/DS1/0-face/shared-words.ts

@@ -1,8 +1,13 @@
 /**
- * The interface words every product shares: common buttons, sign-in, empty
- * states, dates, the settings ds-cycle shows, ds-banner's words and the
- * names of the languages. Keyed by the English sentence, in the translations
- * file format, one file per language in `./translations/`.
+ * The interface words every product shares: common buttons and actions (Try
+ * again, Undo, Redo, Copy, Copy link, Remove, Rename, Duplicate, Download,
+ * Refresh, Open, Send, Clear), Saved, Saving…, Untitled, Account, sign-in,
+ * empty states, dates, the settings ds-cycle shows, ds-notice's words, the
+ * carousel's and slide's (Carousel, Slide, Previous slide, Next slide, Pause, Play…), the feedback module's (OK, Copied, Could not copy, Notifications), a meter's
+ * words ("7 of 10") and a step's (Done, Failed), the site chrome's (Menu,
+ * Contents), the key names keys.ts writes as words (`key.ctrl`, `key.shift` …)
+ * and the names of the languages. Keyed by the English sentence,
+ * in the translations file format, one file per language in `./translations/`.
  *
  * A product turns them on with `configureI18n({ sharedWords: true })`; they
  * sit beneath the product's own words, so the product's text wins. `nn` and