@hraness/design-kit 0.31.1

package/src/browser/artifact-share.ts

@@ -0,0 +1,164 @@
+export interface ArtifactShareIntent {
+  readonly text: string;
+  readonly url: string;
+}
+
+export type NativeFileShareResult =
+  | Readonly<{ kind: "shared" }>
+  | Readonly<{ kind: "cancelled" }>
+  | Readonly<{ kind: "unavailable" }>
+  | Readonly<{ error: unknown; kind: "failed" }>;
+
+function nonblank(value: string, label: string): string {
+  if (value.trim().length === 0) {
+    throw new RangeError(`${label} must contain a non-whitespace character.`);
+  }
+  return value;
+}
+
+function publicWebUrl(value: string): string {
+  const normalized = nonblank(value, "An artifact share URL").trim();
+  let url: URL;
+  try {
+    url = new URL(normalized);
+  } catch {
+    throw new RangeError("An artifact share URL must be an absolute URL.");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new RangeError("An artifact share URL must use HTTP or HTTPS.");
+  }
+  return url.href;
+}
+
+function normalizedIntent(input: ArtifactShareIntent): ArtifactShareIntent {
+  return {
+    text: nonblank(input.text, "Artifact share text"),
+    url: publicWebUrl(input.url),
+  };
+}
+
+/** Builds an X compose intent without opening a window or posting content. */
+export function buildXShareIntentUrl(input: ArtifactShareIntent): string {
+  const { text, url } = normalizedIntent(input);
+  const intent = new URL("https://x.com/intent/post");
+  intent.searchParams.set("text", text);
+  intent.searchParams.set("url", url);
+  return intent.href;
+}
+
+/** Builds LinkedIn's URL-only offsite share dialog. */
+export function buildLinkedInShareIntentUrl(url: string): string {
+  const intent = new URL("https://www.linkedin.com/sharing/share-offsite/");
+  intent.searchParams.set("url", publicWebUrl(url));
+  return intent.href;
+}
+
+/** Builds a Bluesky compose intent with the URL on its own editable line. */
+export function buildBlueskyShareIntentUrl(input: ArtifactShareIntent): string {
+  const { text, url } = normalizedIntent(input);
+  const intent = new URL("https://bsky.app/intent/compose");
+  intent.searchParams.set("text", `${text}\n${url}`);
+  return intent.href;
+}
+
+/** Copies exact caller-prepared text through the secure-context Clipboard API. */
+export async function copyTextToClipboard(text: string): Promise<void> {
+  const clipboard = globalThis.navigator?.clipboard;
+  if (clipboard === undefined || typeof clipboard.writeText !== "function") {
+    throw new Error("Clipboard text writing is unavailable in this environment.");
+  }
+  await clipboard.writeText(text);
+}
+
+/**
+ * Starts a browser download and releases the temporary object URL in the next
+ * task, after the synthetic link activation has been dispatched.
+ */
+export function downloadBlob(blob: Blob, filename: string): void {
+  const normalizedFilename = nonblank(filename, "A download filename").trim();
+  const document = globalThis.document;
+  if (
+    document === undefined
+    || typeof URL.createObjectURL !== "function"
+    || typeof URL.revokeObjectURL !== "function"
+  ) {
+    throw new Error("Blob downloads are unavailable in this environment.");
+  }
+
+  const objectUrl = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.download = normalizedFilename;
+  anchor.hidden = true;
+  anchor.href = objectUrl;
+  anchor.rel = "noopener";
+  document.body.append(anchor);
+  try {
+    anchor.click();
+  } finally {
+    anchor.remove();
+    globalThis.setTimeout(() => URL.revokeObjectURL(objectUrl), 0);
+  }
+}
+
+function isAbortError(error: unknown): boolean {
+  return typeof error === "object"
+    && error !== null
+    && "name" in error
+    && error.name === "AbortError";
+}
+
+function filesOnlyShareData(file: File): ShareData {
+  return { files: [file] };
+}
+
+function nativeFileShareNavigator(): Navigator | undefined {
+  const shareNavigator = globalThis.navigator;
+  if (
+    shareNavigator === undefined
+    || typeof shareNavigator.canShare !== "function"
+    || typeof shareNavigator.share !== "function"
+  ) {
+    return undefined;
+  }
+  return shareNavigator;
+}
+
+function canShareFileWithNavigator(
+  shareNavigator: Navigator,
+  file: File,
+): boolean {
+  try {
+    return shareNavigator.canShare(filesOnlyShareData(file));
+  } catch {
+    return false;
+  }
+}
+
+/** Checks native file-share support using a files-only Web Share payload. */
+export function canShareFileNatively(file: File): boolean {
+  const shareNavigator = nativeFileShareNavigator();
+  return shareNavigator !== undefined
+    && canShareFileWithNavigator(shareNavigator, file);
+}
+
+/**
+ * Opens the native share sheet with one already-prepared file. No text, title,
+ * or URL is added to either capability detection or the share call.
+ */
+export async function shareFileNatively(file: File): Promise<NativeFileShareResult> {
+  const shareNavigator = nativeFileShareNavigator();
+  if (
+    shareNavigator === undefined
+    || !canShareFileWithNavigator(shareNavigator, file)
+  ) {
+    return { kind: "unavailable" };
+  }
+
+  try {
+    await shareNavigator.share(filesOnlyShareData(file));
+    return { kind: "shared" };
+  } catch (error) {
+    if (isAbortError(error)) return { kind: "cancelled" };
+    return { error, kind: "failed" };
+  }
+}

package/src/browser/design-palette.ts

@@ -0,0 +1,197 @@
+import { designThemeStorageKey, isDesignTheme, type ConcreteDesignTheme } from "../appearance.js";
+import {
+  designPaletteStorageKey,
+  normalizeDesignPalettePreference,
+  parseDesignPalettePreference,
+  resolveDesignPalettePreference,
+  type ConcreteDesignPalettePreference,
+  type DesignPalettePreference,
+} from "../palette-appearance.js";
+import { getDesignPaletteTheme } from "../palette-themes.js";
+import { designPalettes } from "../palettes.js";
+import type { AppearanceStorage } from "./appearance-menu.js";
+import { acquireThemeColorMeta } from "./theme-color-sync.js";
+
+export interface DesignPaletteSnapshot {
+  readonly preference: DesignPalettePreference;
+  readonly resolvedMode: ConcreteDesignTheme;
+  readonly className: string;
+  readonly background: string;
+  readonly isForced: boolean;
+}
+
+export interface DesignPaletteOptions {
+  readonly document?: Document;
+  readonly storage?: AppearanceStorage | null;
+  readonly storageKey?: string;
+  readonly legacyStorageKey?: string | null;
+  readonly defaultPreference?: DesignPalettePreference;
+  readonly forcedPreference?: ConcreteDesignPalettePreference;
+}
+
+export interface DesignPaletteController {
+  readonly getSnapshot: () => DesignPaletteSnapshot;
+  readonly subscribe: (listener: () => void) => () => void;
+  readonly setPreference: (preference: DesignPalettePreference) => boolean;
+  readonly dispose: () => void;
+}
+
+interface PaletteInstallation {
+  readonly version: 1;
+  readonly configuration: string;
+  readonly acquire: () => DesignPaletteController;
+}
+
+// A document property lets the head bootstrap and a separately bundled React
+// client adopt the same controller. Importing this module does not install it.
+const installationKey = Symbol.for("hraness.design-palette.controller.v1");
+type PaletteDocument = Document & { [installationKey]?: PaletteInstallation };
+const darkQuery = "(prefers-color-scheme: dark)";
+
+export function designPaletteSnapshot(
+  preference: DesignPalettePreference,
+  systemPrefersDark: boolean,
+  isForced = false,
+): DesignPaletteSnapshot {
+  const resolved = resolveDesignPalettePreference(preference, systemPrefersDark);
+  const theme = getDesignPaletteTheme(resolved.palette, resolved.mode);
+  return Object.freeze({
+    preference: Object.freeze({ ...preference }),
+    resolvedMode: resolved.mode,
+    className: theme.className,
+    background: theme.background,
+    isForced,
+  });
+}
+
+function readStorage(storage: AppearanceStorage | null, key: string): unknown {
+  try { return storage?.getItem(key); } catch { return undefined; }
+}
+
+function writeStorage(storage: AppearanceStorage | null, key: string, preference: DesignPalettePreference): void {
+  try { storage?.setItem(key, JSON.stringify(preference)); } catch { /* Persistence is optional. */ }
+}
+
+/** Installs palette selection explicitly; it never injects scripts or inline styles. */
+export function initDesignPalette(options: DesignPaletteOptions = {}): DesignPaletteController {
+  const document = options.document ?? globalThis.document;
+  if (document === undefined || document.documentElement === null || document.head === null) {
+    throw new Error("initDesignPalette requires an HTML document with a head.");
+  }
+  const view = document.defaultView;
+  const storageKey = options.storageKey ?? designPaletteStorageKey;
+  const legacyStorageKey = options.legacyStorageKey === undefined ? designThemeStorageKey : options.legacyStorageKey;
+  if (storageKey.trim() === "" || legacyStorageKey?.trim() === "") throw new Error("Appearance storage keys must not be blank.");
+  const fallback = normalizeDesignPalettePreference(options.defaultPreference);
+  const forced = options.forcedPreference === undefined ? null : parseDesignPalettePreference(options.forcedPreference);
+  if (options.forcedPreference !== undefined && (forced === null || forced.mode === "system")) {
+    throw new Error("A forced palette requires a valid palette and a light or dark mode.");
+  }
+  const configuration = JSON.stringify({ storageKey, legacyStorageKey, fallback, forced });
+  const ownerDocument = document as PaletteDocument;
+  const previous = ownerDocument[installationKey];
+  if (previous !== undefined) {
+    if (previous.version !== 1 || previous.configuration !== configuration) {
+      throw new Error("This document already has a different palette configuration.");
+    }
+    return previous.acquire();
+  }
+
+  let storage = options.storage ?? null;
+  const usesDefaultStorage = options.storage === undefined;
+  if (usesDefaultStorage && forced === null) {
+    try { storage = view?.localStorage ?? null; } catch { /* Storage can be denied. */ }
+  }
+  let media: MediaQueryList | null = null;
+  try { media = view?.matchMedia?.(darkQuery) ?? null; } catch { /* Explicit modes remain available. */ }
+  const readPreference = (): DesignPalettePreference => {
+    if (forced !== null) return forced;
+    const raw = readStorage(storage, storageKey);
+    const saved = parseDesignPalettePreference(raw);
+    if (saved !== null) return saved;
+    if ((raw === null || raw === undefined) && legacyStorageKey !== null) {
+      const legacy = readStorage(storage, legacyStorageKey);
+      if (isDesignTheme(legacy)) return Object.freeze({ palette: fallback.palette, mode: legacy });
+    }
+    return fallback;
+  };
+  let snapshot = designPaletteSnapshot(readPreference(), media?.matches ?? false, forced !== null);
+  const listeners = new Set<() => void>();
+  const ownedClasses = new Set(designPalettes.flatMap((palette) =>
+    (["light", "dark"] as const).flatMap((mode) => getDesignPaletteTheme(palette, mode).className.split(/\s+/u))));
+  const themeColor = acquireThemeColorMeta(document, "theme-color", Symbol("palette-theme-color"), snapshot.background);
+  const apply = (): void => {
+    const root = document.documentElement;
+    const nextClasses = new Set(snapshot.className.split(/\s+/u).filter(Boolean));
+    for (const token of ownedClasses) if (token !== "" && !nextClasses.has(token)) root.classList.remove(token);
+    for (const token of nextClasses) root.classList.add(token);
+    root.setAttribute("data-palette", snapshot.preference.palette);
+    root.setAttribute("data-theme", snapshot.resolvedMode);
+    themeColor.update(snapshot.background);
+  };
+  const update = (preference: DesignPalettePreference): boolean => {
+    const next = designPaletteSnapshot(preference, media?.matches ?? false, forced !== null);
+    if (next.preference.palette === snapshot.preference.palette
+      && next.preference.mode === snapshot.preference.mode
+      && next.resolvedMode === snapshot.resolvedMode) return false;
+    snapshot = next;
+    apply();
+    for (const listener of listeners) listener();
+    return true;
+  };
+  const onMedia = (): void => { update(snapshot.preference); };
+  const onStorage = (event: StorageEvent): void => {
+    if (forced !== null || (event.key !== storageKey && event.key !== null)) return;
+    if (usesDefaultStorage && event.storageArea !== null && event.storageArea !== undefined && event.storageArea !== storage) return;
+    update(readPreference());
+  };
+  if (forced === null) {
+    writeStorage(storage, storageKey, snapshot.preference);
+    view?.addEventListener("storage", onStorage);
+    media?.addEventListener("change", onMedia);
+  }
+  let owners = 0;
+  const installation: PaletteInstallation = {
+    version: 1,
+    configuration,
+    acquire: () => {
+      // An error document can replace the root or reset its server attributes.
+      // Restore the current choice without another controller or storage read.
+      apply();
+      owners += 1;
+      let disposed = false;
+      const subscriptions = new Set<() => void>();
+      return {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+          if (disposed) return () => undefined;
+          const subscription = (): void => { listener(); };
+          subscriptions.add(subscription);
+          listeners.add(subscription);
+          return () => { subscriptions.delete(subscription); listeners.delete(subscription); };
+        },
+        setPreference: (value) => {
+          if (disposed || forced !== null) return false;
+          const preference = parseDesignPalettePreference(value);
+          if (preference === null) throw new Error("Choose a supported palette and appearance mode.");
+          writeStorage(storage, storageKey, preference);
+          return update(preference);
+        },
+        dispose: () => {
+          if (disposed) return;
+          disposed = true;
+          for (const listener of subscriptions) listeners.delete(listener);
+          subscriptions.clear();
+          owners -= 1;
+          if (owners !== 0) return;
+          view?.removeEventListener("storage", onStorage);
+          media?.removeEventListener("change", onMedia);
+          themeColor.release();
+          if (ownerDocument[installationKey] === installation) Reflect.deleteProperty(ownerDocument, installationKey);
+        },
+      };
+    },
+  };
+  ownerDocument[installationKey] = installation;
+  return installation.acquire();
+}

package/src/browser/foil.ts

@@ -0,0 +1,124 @@
+/** Version 2: moving light over a steady material. Safe to snapshot without imports. */
+const REST = 50;
+const SETTLE = 0.05;
+const RESPONSE_MS = 85;
+const MIN_LIGHT = 8;
+const MAX_LIGHT = 92;
+const INPUTS = ["--hraness-foil-x", "--hraness-foil-y"] as const;
+type Light = { x: number; y: number };
+const clampLight = (value: number) => Math.max(MIN_LIGHT, Math.min(MAX_LIGHT, value));
+
+/**
+ * One damped light source per outermost [data-foil] lockup. Nested marks inherit
+ * its coordinates. Shapes and material direction never rotate. Resting CSS is
+ * complete without this enhancement; touch, reduced motion and forced colors
+ * leave it untouched. Return the cleanup function when the owning root unmounts.
+ */
+export function attachFoil(root: HTMLElement): () => void {
+  const document = root.ownerDocument;
+  const view = document.defaultView;
+  if (!view || typeof view.matchMedia !== "function"
+    || typeof view.requestAnimationFrame !== "function"
+    || typeof view.cancelAnimationFrame !== "function") return () => {};
+  const preference = view.matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference) and (forced-colors: none)");
+  const states = new Map<HTMLElement, Light>();
+  let targets: HTMLElement[] = [];
+  let needsTargets = true;
+  let pointer: Light | undefined;
+  let frame: number | null = null;
+  let previousTime: number | undefined;
+  let detached = false;
+  const restore = (target: HTMLElement) => {
+    for (const input of INPUTS) target.style.removeProperty(input);
+  };
+  const reset = () => {
+    if (frame !== null) view.cancelAnimationFrame(frame);
+    frame = null;
+    previousTime = undefined;
+    pointer = undefined;
+    for (const target of states.keys()) restore(target);
+    states.clear();
+    targets = [];
+    needsTargets = true;
+  };
+  const refreshTargets = () => {
+    targets = [...(root.matches("[data-foil]") ? [root] : []), ...root.querySelectorAll<HTMLElement>("[data-foil]")]
+      .filter((target) => {
+        const ancestor = target.parentElement?.closest("[data-foil]");
+        return !ancestor || !root.contains(ancestor);
+      });
+    const live = new Set(targets);
+    for (const target of states.keys()) {
+      if (!live.has(target)) { restore(target); states.delete(target); }
+    }
+    needsTargets = false;
+  };
+  const paint = (time: number) => {
+    frame = null;
+    if (detached || !preference.matches || document.hidden || !pointer) { reset(); return; }
+    if (needsTargets) refreshTargets();
+    const elapsed = previousTime === undefined ? 1000 / 60 : Math.max(0, Math.min(64, time - previousTime));
+    previousTime = time;
+    const ease = 1 - Math.exp(-elapsed / RESPONSE_MS);
+    // Read every rectangle before writing styles; there is no read/write/read loop.
+    const measured = targets.map((target) => ({ target, bounds: target.getBoundingClientRect() }));
+    let moving = false;
+    for (const { target, bounds } of measured) {
+      if (!target.isConnected || !root.contains(target) || bounds.width <= 0 || bounds.height <= 0
+        || bounds.bottom <= 0 || bounds.right <= 0 || bounds.top >= view.innerHeight || bounds.left >= view.innerWidth) {
+        if (states.has(target)) { restore(target); states.delete(target); }
+        continue;
+      }
+      // A minimum light field avoids tiny marks behaving like a pointer joystick.
+      const goal = {
+        x: clampLight(REST + (pointer.x - bounds.left - bounds.width / 2) / Math.max(160, bounds.width) * 60),
+        y: clampLight(REST + (pointer.y - bounds.top - bounds.height / 2) / Math.max(120, bounds.height) * 50),
+      };
+      const light = states.get(target) ?? { x: REST, y: REST };
+      for (const axis of ["x", "y"] as const) {
+        const distance = goal[axis] - light[axis];
+        if (Math.abs(distance) > SETTLE) { light[axis] += distance * ease; moving = true; }
+        else light[axis] = goal[axis];
+      }
+      states.set(target, light);
+      for (const axis of ["x", "y"] as const) {
+        const input = `--hraness-foil-${axis}`;
+        const value = `${light[axis].toFixed(2)}%`;
+        if (target.style.getPropertyValue(input) !== value) target.style.setProperty(input, value);
+      }
+    }
+    if (moving) frame = view.requestAnimationFrame(paint);
+    else previousTime = undefined;
+  };
+  const move = (event: PointerEvent) => {
+    if (!preference.matches || document.hidden || event.pointerType === "touch") { reset(); return; }
+    if (!Number.isFinite(event.clientX) || !Number.isFinite(event.clientY)) return;
+    pointer = { x: event.clientX, y: event.clientY };
+    needsTargets = true;
+    if (frame === null) frame = view.requestAnimationFrame(paint);
+  };
+  const leave = (event: PointerEvent) => { if (event.relatedTarget === null) reset(); };
+  const visibility = () => { if (document.hidden) reset(); };
+  view.addEventListener("pointermove", move, { passive: true });
+  view.addEventListener("pointerdown", move, { passive: true });
+  view.addEventListener("pointerout", leave, { passive: true });
+  view.addEventListener("pointercancel", reset);
+  view.addEventListener("blur", reset);
+  view.addEventListener("scroll", reset, { passive: true, capture: true });
+  view.addEventListener("resize", reset, { passive: true });
+  document.addEventListener("visibilitychange", visibility);
+  preference.addEventListener("change", reset);
+  return () => {
+    detached = true;
+    reset();
+    view.removeEventListener("pointermove", move);
+    view.removeEventListener("pointerdown", move);
+    view.removeEventListener("pointerout", leave);
+    view.removeEventListener("pointercancel", reset);
+    view.removeEventListener("blur", reset);
+    view.removeEventListener("scroll", reset, true);
+    view.removeEventListener("resize", reset);
+    document.removeEventListener("visibilitychange", visibility);
+    preference.removeEventListener("change", reset);
+  };
+}

package/src/browser/hero-light.ts

@@ -0,0 +1,11 @@
+/**
+ * @deprecated Retired with the Quiet marketing direction. Marketing heroes no
+ * longer have a pointer-driven light field, drift, or `data-hraness-hero-item`
+ * proximity. The function stays exported so existing callers compile; it
+ * attaches no listeners, writes no styles, schedules no frames, and returns an
+ * idempotent disposer. Remove the call when convenient.
+ */
+export function attachHeroLight(root: HTMLElement): () => void {
+  void root;
+  return () => {};
+}

package/src/browser/index.ts

@@ -0,0 +1,29 @@
+import * as appearance from "../appearance.js";
+import { installAppearanceMenus as installMenus } from "./appearance-menu.js";
+
+export * from "./artifact-share.js";
+export * from "./design-palette.js";
+export * from "./foil.js";
+export * from "./hero-light.js";
+export * from "./status-page.js";
+export * from "./sticky-offset.js";
+export * from "../palette-appearance.js";
+
+export type {
+  ConcreteDesignTheme,
+  DesignTheme,
+  DesignThemeLabels,
+} from "../appearance.js";
+export type {
+  AppearanceMenuInstallation,
+  AppearanceMenuOptions,
+  AppearanceStorage,
+} from "./appearance-menu.js";
+export const defaultDesignTheme = appearance.defaultDesignTheme;
+export const designThemeLabel = appearance.designThemeLabel;
+export const designThemes = appearance.designThemes;
+export const designThemeStorageKey = appearance.designThemeStorageKey;
+export const installAppearanceMenus = installMenus;
+export const isDesignTheme = appearance.isDesignTheme;
+export const normalizeDesignTheme = appearance.normalizeDesignTheme;
+export const resolveDesignTheme = appearance.resolveDesignTheme;