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

package/DS1/0-face/focus.ts

@@ -0,0 +1,181 @@
+/**
+ * Image focus: where a photo's subject is, so a picture cut to its box
+ * (`object-fit: cover`) keeps it in view instead of its middle. A person's
+ * face first, then whatever in the picture holds the most detail. Plain
+ * TypeScript with no imports, for the browser and for a build script alike.
+ *
+ * The focus is a point of the picture, across and down from 0 to 1, and it is
+ * written as the picture's `object-position` (`objectPosition()`), so a
+ * cover crop of any shape keeps that point in view. Work it out once, where
+ * the page is built, and write it into the markup, so the first paint is
+ * already cut right. On a Mac, `focus-vision.swift` finds the faces and the
+ * salient part with Apple's Vision framework, and `focusFromRegions()` turns
+ * them into the focus; elsewhere, or where it finds nothing, `focusOf()`
+ * reads the pixels:
+ *
+ * ```ts
+ * // swift 0-face/focus-vision.swift *.jpg > regions.json
+ * import { focusFromRegions, focusOf, objectPosition } from "./0-face/focus.ts";
+ * const focus = focusFromRegions(regions[name]) ?? focusOf(data, info.width, info.height, info.channels);
+ * // <img src="…" style="object-position: 50% 18%">
+ * ```
+ *
+ * A page with no build step marks a picture `data-ds-focus="auto"` and calls
+ * `startFocus()`: once the picture has loaded, its focus is found and kept in
+ * the browser, so it is right from the first paint on the next visit. A
+ * picture whose focus a person chose says so, `data-ds-focus="40% 20%"`, and
+ * is never measured. A picture from another host without CORS cannot be read
+ * and keeps its middle.
+ */
+
+/** A point of a picture, across (`x`) and down (`y`), each from 0 to 1. */
+export interface Focus { x: number; y: number }
+
+export const CENTRE: Focus = { x: 0.5, y: 0.5 };
+
+/** The width a picture is measured at; enough to find a face, and cheap. */
+export const FOCUS_SAMPLE = 64;
+
+/** Whether a pixel's colour is skin, in YCbCr, for any skin tone. */
+function isSkin(r: number, g: number, b: number): boolean {
+  const y = 0.299 * r + 0.587 * g + 0.114 * b;
+  const cb = 128 - 0.168736 * r - 0.331264 * g + 0.5 * b;
+  const cr = 128 + 0.5 * r - 0.418688 * g - 0.081312 * b;
+  return y > 40 && cb >= 77 && cb <= 127 && cr >= 137 && cr <= 173 && r > g && r > b;
+}
+
+const clamp = (value: number) => Math.min(1, Math.max(0, value));
+
+/**
+ * The focus of a picture from its pixels (RGB or RGBA, row by row), measured
+ * small (about `FOCUS_SAMPLE` across). Skin that gathers into a face wins:
+ * the highest band of rows dense with skin, since a face stands above hands
+ * and arms. Without one, the centre of the picture's detail (where neighbouring
+ * pixels differ most), drawn a little towards the middle so a busy edge does
+ * not take the crop.
+ */
+export function focusOf(pixels: ArrayLike<number>, width: number, height: number, channels = 4): Focus {
+  if (width < 2 || height < 2) return CENTRE;
+  const at = (x: number, y: number) => (y * width + x) * channels;
+  const luma = new Float32Array(width * height);
+  const skin = new Uint8Array(width * height);
+  let skinCount = 0;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = at(x, y);
+      const r = pixels[i]!, g = pixels[i + 1]!, b = pixels[i + 2]!;
+      luma[y * width + x] = 0.299 * r + 0.587 * g + 0.114 * b;
+      if (isSkin(r, g, b)) { skin[y * width + x] = 1; skinCount++; }
+    }
+  }
+
+  // A face: skin over at least half a percent of the picture, in a band of rows.
+  if (skinCount >= width * height * 0.005) {
+    const band = Math.max(2, Math.round(height / 10));
+    const rows = new Float32Array(height);
+    for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) rows[y] += skin[y * width + x]!;
+    let densest = 0;
+    const bands: number[] = [];
+    for (let y = 0; y + band <= height; y++) {
+      let sum = 0;
+      for (let k = 0; k < band; k++) sum += rows[y + k]!;
+      bands.push(sum);
+      densest = Math.max(densest, sum);
+    }
+    const top = bands.findIndex(sum => sum >= densest * 0.45);
+    if (top >= 0) {
+      let sx = 0, sy = 0, n = 0;
+      for (let y = top; y < Math.min(height, top + band * 2); y++) {
+        for (let x = 0; x < width; x++) if (skin[y * width + x]) { sx += x; sy += y; n++; }
+      }
+      if (n) return { x: clamp((sx / n + 0.5) / width), y: clamp((sy / n + 0.5) / height) };
+    }
+  }
+
+  // Otherwise the picture's detail.
+  let sx = 0, sy = 0, total = 0;
+  for (let y = 1; y < height - 1; y++) {
+    for (let x = 1; x < width - 1; x++) {
+      const i = y * width + x;
+      const energy = Math.abs(luma[i + 1]! - luma[i - 1]!) + Math.abs(luma[i + width]! - luma[i - width]!);
+      sx += x * energy; sy += y * energy; total += energy;
+    }
+  }
+  if (!total) return CENTRE;
+  const pull = 0.35;
+  return {
+    x: clamp(((sx / total + 0.5) / width) * (1 - pull) + 0.5 * pull),
+    y: clamp(((sy / total + 0.5) / height) * (1 - pull) + 0.5 * pull),
+  };
+}
+
+/** A part of a picture, as fractions of it from its top left corner. */
+export interface Region { x: number; y: number; w: number; h: number }
+
+/**
+ * The focus from what a detector found (`focus-vision.swift`: Apple's face
+ * detection and attention-based saliency), or `undefined` when it found
+ * nothing. Faces win: the point between them across, and down a little above
+ * the top of the highest, so a crop keeps the heads whole with room above
+ * them. Otherwise the middle of everything salient.
+ */
+export function focusFromRegions(found: { faces?: Region[]; salient?: Region[] }): Focus | undefined {
+  const faces = (found.faces ?? []).filter(face => face.w * face.h > 0.0005);
+  if (faces.length) {
+    const biggest = Math.max(...faces.map(face => face.w * face.h));
+    const kept = faces.filter(face => face.w * face.h >= biggest * 0.25);
+    const left = Math.min(...kept.map(face => face.x));
+    const right = Math.max(...kept.map(face => face.x + face.w));
+    const top = Math.min(...kept.map(face => face.y));
+    const height = Math.max(...kept.map(face => face.h));
+    return { x: clamp((left + right) / 2), y: clamp(top - height * 0.35) };
+  }
+  const salient = found.salient ?? [];
+  if (!salient.length) return undefined;
+  const left = Math.min(...salient.map(r => r.x));
+  const right = Math.max(...salient.map(r => r.x + r.w));
+  const top = Math.min(...salient.map(r => r.y));
+  const bottom = Math.max(...salient.map(r => r.y + r.h));
+  return { x: clamp((left + right) / 2), y: clamp((top + bottom) / 2) };
+}
+
+/** The focus as CSS `object-position`, in whole percents. */
+export function objectPosition(focus: Focus): string {
+  return `${Math.round(focus.x * 100)}% ${Math.round(focus.y * 100)}%`;
+}
+
+const KEY = "ds-focus:";
+
+/** Finds and sets the focus of one picture marked `data-ds-focus="auto"`, once it has loaded. */
+export function focusImage(image: HTMLImageElement): void {
+  const chosen = image.dataset.dsFocus;
+  if (chosen && chosen !== "auto") { image.style.objectPosition = chosen; return; }
+  const source = image.currentSrc || image.src;
+  try {
+    const kept = localStorage.getItem(KEY + source);
+    if (kept) { image.style.objectPosition = kept; return; }
+  } catch { /* Storage can be blocked. */ }
+  const measure = () => {
+    if (!image.naturalWidth) return;
+    const width = FOCUS_SAMPLE;
+    const height = Math.max(2, Math.round((image.naturalHeight / image.naturalWidth) * width));
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext("2d", { willReadFrequently: true });
+    if (!context) return;
+    try {
+      context.drawImage(image, 0, 0, width, height);
+      const position = objectPosition(focusOf(context.getImageData(0, 0, width, height).data, width, height, 4));
+      image.style.objectPosition = position;
+      try { localStorage.setItem(KEY + source, position); } catch { /* Storage can be blocked. */ }
+    } catch { /* A picture from another host without CORS cannot be read; it keeps its middle. */ }
+  };
+  if (image.complete) measure();
+  else image.addEventListener("load", measure, { once: true });
+}
+
+/** Sets the focus of every picture marked `data-ds-focus` in `root`. */
+export function startFocus(root: ParentNode = document): void {
+  for (const image of root.querySelectorAll<HTMLImageElement>("img[data-ds-focus]")) focusImage(image);
+}

package/DS1/0-face/google-face-metrics.json

@@ -0,0 +1,102 @@
+{
+  "DM Sans": {
+    "ascent": 0.992,
+    "descent": 0.31,
+    "capHeight": 0.7
+  },
+  "Inter": {
+    "ascent": 0.9688,
+    "descent": 0.2412,
+    "capHeight": 0.7275
+  },
+  "JetBrains Mono": {
+    "ascent": 1.02,
+    "descent": 0.3,
+    "capHeight": 0.73
+  },
+  "Lora": {
+    "ascent": 1.006,
+    "descent": 0.274,
+    "capHeight": 0.7
+  },
+  "Manrope": {
+    "ascent": 1.066,
+    "descent": 0.3,
+    "capHeight": 0.72
+  },
+  "Montserrat": {
+    "ascent": 0.968,
+    "descent": 0.251,
+    "capHeight": 0.7
+  },
+  "Noto Sans": {
+    "ascent": 1.069,
+    "descent": 0.293,
+    "capHeight": 0.714
+  },
+  "Noto Sans JP": {
+    "ascent": 1.16,
+    "descent": 0.288,
+    "capHeight": 0.733
+  },
+  "Nunito": {
+    "ascent": 1.011,
+    "descent": 0.353,
+    "capHeight": 0.705
+  },
+  "Open Sans": {
+    "ascent": 1.0688,
+    "descent": 0.293,
+    "capHeight": 0.7139
+  },
+  "Outfit": {
+    "ascent": 1,
+    "descent": 0.26,
+    "capHeight": 0.694
+  },
+  "Playfair Display": {
+    "ascent": 1.082,
+    "descent": 0.251,
+    "capHeight": 0.708
+  },
+  "Poppins": {
+    "ascent": 1.05,
+    "descent": 0.35,
+    "capHeight": 0.698
+  },
+  "Raleway": {
+    "ascent": 0.94,
+    "descent": 0.234,
+    "capHeight": 0.71
+  },
+  "Roboto": {
+    "ascent": 0.9277,
+    "descent": 0.2441,
+    "capHeight": 0.7109
+  },
+  "Rubik": {
+    "ascent": 0.935,
+    "descent": 0.25,
+    "capHeight": 0.7
+  },
+  "Source Sans 3": {
+    "ascent": 1.024,
+    "descent": 0.4,
+    "capHeight": 0.66
+  },
+  "Source Serif 4": {
+    "ascent": 1.036,
+    "descent": 0.335,
+    "capHeight": 0.67
+  },
+  "Urbanist": {
+    "ascent": 0.95,
+    "descent": 0.25,
+    "capHeight": 0.7
+  },
+  "Work Sans": {
+    "ascent": 0.93,
+    "descent": 0.243,
+    "capHeight": 0.66
+  }
+}

package/DS1/0-face/grid.ts

@@ -1,7 +1,19 @@
 import { createLayoutInspector } from './layout-inspector';
 import { initGridFit } from './grid-fit';
+import { initConstraintShortcut } from './constraint-panel';
 
-/** Triple G toggles the grid; triple L inspects named layout areas. */
+/** The presses of one key, each within 800ms of the last, that toggle an overlay. */
+export const GRID_PRESSES = 5;
+
+/**
+ * Five presses of G toggle the grid and five of L inspect the layout, on every
+ * page that loads this module and for everyone who reads it: never put them
+ * behind a user, an owner or a development check. Escape hides both. Presses
+ * typed into a field, with a modifier or held down never count, and any other
+ * key starts the count again.
+ * A nested scrolling viewport opts in with data-ds-grid-scroll: its grid follows
+ * its content while the page grid remains aligned outside the viewport.
+ */
 export function initGridShortcut(): void {
   if (typeof document === "undefined") return;
   const root = document.documentElement;
@@ -9,6 +21,8 @@ export function initGridShortcut(): void {
   root.setAttribute("data-ds-grid-ready", "");
   root.setAttribute("data-design-system", "1");
   initGridFit();
+  // Five presses of C, for the page's owner alone (constraint-panel.ts).
+  initConstraintShortcut();
 
   const overlay = document.createElement("div");
   overlay.setAttribute("data-ds-grid-overlay", "");
@@ -44,18 +58,61 @@ export function initGridShortcut(): void {
   document.body.appendChild(overlay);
   const layout = createLayoutInspector();
 
+  const pageGrid = shadow.querySelector<HTMLElement>('.grid')!;
+  const scopedGrids = new Map<HTMLElement, HTMLElement>();
+  let tracking = false;
+  const resize = new ResizeObserver(() => { if (tracking) updatePosition(); });
+  const regionsChanged = new MutationObserver(() => { if (tracking) updatePosition(); });
   const updatePosition = () => {
     overlay.style.setProperty("--ds-grid-scroll-x", `${window.scrollX}px`);
     overlay.style.setProperty("--ds-grid-scroll-y", `${window.scrollY}px`);
+    const present = new Set<HTMLElement>();
+    const holes: string[] = [];
+    document.querySelectorAll<HTMLElement>('[data-ds-grid-scroll]').forEach(element => {
+      const rect = element.getBoundingClientRect();
+      let left = rect.left + element.clientLeft, top = rect.top + element.clientTop;
+      let right = left + element.clientWidth, bottom = top + element.clientHeight;
+      // The overlay must respect enclosing scroll viewports as the content does.
+      for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+        const style = getComputedStyle(parent), box = parent.getBoundingClientRect();
+        if (/(auto|scroll|hidden|clip)/.test(style.overflowX)) { left = Math.max(left, box.left + parent.clientLeft); right = Math.min(right, box.left + parent.clientLeft + parent.clientWidth); }
+        if (/(auto|scroll|hidden|clip)/.test(style.overflowY)) { top = Math.max(top, box.top + parent.clientTop); bottom = Math.min(bottom, box.top + parent.clientTop + parent.clientHeight); }
+      }
+      left = Math.max(0, left); top = Math.max(0, top); right = Math.min(innerWidth, right); bottom = Math.min(innerHeight, bottom);
+      if (right <= left || bottom <= top || !element.getClientRects().length) return;
+      present.add(element);
+      let grid = scopedGrids.get(element);
+      if (!grid) { grid = document.createElement('div'); grid.className = 'grid'; grid.setAttribute('data-ds-grid-region', ''); shadow.append(grid); scopedGrids.set(element, grid); resize.observe(element); }
+      const style = getComputedStyle(element);
+      for (const property of ['--ds-grid-unit', '--unit', '--sf', '--ds-grid-color', '--ds-grid-origin-x', '--ds-grid-origin-y', '--ds-grid-line-offset']) {
+        const value = style.getPropertyValue(property); if (value) grid.style.setProperty(property, value); else grid.style.removeProperty(property);
+      }
+      Object.assign(grid.style, { inset: 'auto', left: `${left}px`, top: `${top}px`, width: `${right - left}px`, height: `${bottom - top}px` });
+      grid.style.setProperty('--ds-grid-scroll-x', `${window.scrollX + left + element.scrollLeft}px`);
+      grid.style.setProperty('--ds-grid-scroll-y', `${window.scrollY + top + element.scrollTop}px`);
+      // Opposite winding makes each viewport a hole in the page grid.
+      holes.push(`M${left},${top}V${bottom}H${right}V${top}Z`);
+    });
+    scopedGrids.forEach((grid, element) => { if (!present.has(element)) { resize.unobserve(element); grid.remove(); scopedGrids.delete(element); } });
+    pageGrid.style.clipPath = holes.length ? `path("M0,0H${innerWidth}V${innerHeight}H0Z ${holes.join(' ')}")` : '';
   };
   const setVisible = (visible: boolean) => {
     overlay.hidden = !visible;
     root.toggleAttribute("data-ds-grid-visible", visible);
     if (visible) {
+      tracking = true;
       updatePosition();
-      window.addEventListener("scroll", updatePosition, { passive: true });
+      document.addEventListener('scroll', updatePosition, { passive: true, capture: true });
+      window.addEventListener('scroll', updatePosition, { passive: true });
+      window.addEventListener('resize', updatePosition, { passive: true });
+      regionsChanged.observe(document.body, { childList: true, subtree: true });
     } else {
-      window.removeEventListener("scroll", updatePosition);
+      tracking = false;
+      document.removeEventListener('scroll', updatePosition, true);
+      window.removeEventListener('scroll', updatePosition);
+      window.removeEventListener('resize', updatePosition);
+      regionsChanged.disconnect(); resize.disconnect();
+      scopedGrids.forEach(grid => grid.remove()); scopedGrids.clear(); pageGrid.style.clipPath = '';
     }
     window.dispatchEvent(new CustomEvent("design-system-grid-changed", { detail: { visible } }));
   };
@@ -128,7 +185,7 @@ export function initGridShortcut(): void {
     presses = key === lastKey && now - lastPress <= 800 ? presses + 1 : 1;
     lastKey = key;
     lastPress = now;
-    if (presses === 3) {
+    if (presses === GRID_PRESSES) {
       reset();
       if (key === 'g') setVisible(overlay.hidden !== false);
       else layout.toggle();

package/DS1/0-face/i18n.ts

@@ -846,17 +846,46 @@ export function loadSharedWords(): Promise<void> {
   return sharedWordsLoad;
 }
 
+/**
+ * The words a page loads as it starts (the shared words, the translations file), announced once
+ * between them: each announcement redraws every translated word on the page, so three arrivals in
+ * the first half second used to redraw it three times. A load that never ends holds the
+ * announcement back no longer than `STARTUP_WAIT`.
+ */
+const startupLoads: Promise<unknown>[] = [];
+const STARTUP_WAIT = 1000;
+let announcement: Promise<void> | null = null;
+let announced = false;
+/** The window this module loaded into, which hears its announcements. */
+const page: Window | undefined = typeof window !== "undefined" ? window : undefined;
+
+function announceTranslations(): void {
+  if (announcement) return;
+  const wait = new Promise<void>((resolve) => setTimeout(resolve, STARTUP_WAIT));
+  announcement = Promise.race([Promise.allSettled(startupLoads.splice(0)), wait]).then(() => {
+    announcement = null;
+    announced = true;
+    if (!eventful() || !page) return;
+    page.dispatchEvent(new CustomEvent("translations-loaded"));
+    // Dispatch language-changed to update all components
+    dispatchLanguageChanged(currentLanguage.value);
+  });
+}
+
 applyRouting();
 if (i18nOptions.sharedWords) {
-  void loadSharedWords();
+  startupLoads.push(loadSharedWords());
 }
 
 // Auto-load translations when this module is imported (for CDN bundle).
 // Waits a task, so a product can configure the module first, even after a
 // dynamic import.
 if (typeof window !== "undefined" && typeof document !== "undefined") {
+  let started: () => void = () => {};
+  startupLoads.push(new Promise<void>((resolve) => (started = resolve)));
   const start = () => {
-    if (i18nOptions.autoLoad !== false) void loadExternalTranslations();
+    if (i18nOptions.autoLoad !== false) void loadExternalTranslations().finally(started);
+    else started();
   };
   if (document.readyState === "loading") {
     document.addEventListener("DOMContentLoaded", start);
@@ -871,24 +900,13 @@ if (typeof window !== "undefined" && typeof document !== "undefined") {
 // 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"));
+  // New words: translations-loaded and language-changed, once for everything still arriving.
+  window.addEventListener("translations-ready", announceTranslations);
 
-    // Dispatch language-changed to update all components
-    dispatchLanguageChanged(currentLanguage.value);
-  });
-
-  // Initialize translations on module load
-  // Use setTimeout to give other parts of the app time to set up event listeners first
+  // A page whose words were all there at once still hears translations-loaded once, after its
+  // listeners have had a moment to attach; one already announced or on its way is enough.
   setTimeout(() => {
-    if (!eventful()) {
-      return;
-    }
-    window.dispatchEvent(new CustomEvent("translations-loaded"));
-
-    // Also dispatch language-changed with the current language
-    dispatchLanguageChanged(currentLanguage.value);
+    if (eventful() && !announced && window === page) announceTranslations();
   }, 100);
 }