@hraness/design-kit 0.31.1

package/src/react/foil-mark.tsx

@@ -0,0 +1,35 @@
+import type { CSSProperties, ReactNode } from "react";
+import { foilMarkClassName } from "./foil.stylex.js";
+
+export interface FoilMarkProps {
+  /** Transparent, same-origin or data-URL artwork; its alpha defines the mark. */
+  readonly src: string;
+  readonly className?: string;
+  /** Decorative by default; name the enclosing link instead when possible. */
+  readonly label?: string;
+  readonly size?: number;
+  /** Optional original inline vector for a currentColor forced-color fallback. */
+  readonly fallback?: ReactNode;
+}
+
+/** Static metallic paint over the exact source silhouette, with an intact fallback. */
+export function FoilMark({ src, className, label, size = 24, fallback }: FoilMarkProps) {
+  if (!Number.isFinite(size) || size <= 0) throw new RangeError("FoilMark size must be positive and finite.");
+  return (
+    <span
+      aria-hidden={label === undefined ? true : undefined}
+      aria-label={label}
+      className={foilMarkClassName("root", className)}
+      data-foil=""
+      role={label === undefined ? undefined : "img"}
+      style={{ "--hraness-foil-size": `${size}px` } as CSSProperties}
+    >
+      {fallback ?? <img alt="" className={foilMarkClassName("image")} decoding="async" height={size} src={src} width={size} />}
+      <span
+        aria-hidden="true"
+        className={foilMarkClassName("paint")}
+        style={{ "--hraness-foil-mask": `url(${JSON.stringify(src)})` } as CSSProperties}
+      />
+    </span>
+  );
+}

package/src/react/foil.stylex.ts

@@ -0,0 +1,163 @@
+import * as stylex from "@stylexjs/stylex";
+
+// Shared metallic-chrome contract projected from the authored material in
+// ../foil-material.ts, mirrored by the handwritten product-marketing.css
+// grammar and by @hraness/site-footer's holographic recipe. attachFoil() from
+// @hraness/design-kit/browser eases the two bounded pointer inputs
+// --hraness-foil-x and --hraness-foil-y on the outermost [data-foil] lockup;
+// shapes never rotate, only the light moves. --hraness-foil-glow stays
+// CSS-owned on hover-capable pointers. Each recipe resolves the public
+// --hraness-foil-* spectrum into private scheme-conditioned stops so product
+// overrides inherit while the darker dark palette keeps the pointer sheen
+// visible on standalone surfaces. Bordered surfaces paint a flat fill under
+// the theme-aware monochrome --hraness-foil-edge instead of the spectrum.
+const foilStops = {
+  "--_hraness-foil-1": {
+    "default": "var(--hraness-foil-1, oklch(0.89 0.065 337))",
+    "@media (prefers-color-scheme: dark)": "var(--hraness-foil-1, oklch(0.56 0.16 340))",
+  },
+  "--_hraness-foil-2": {
+    "default": "var(--hraness-foil-2, oklch(0.875 0.05 277))",
+    "@media (prefers-color-scheme: dark)": "var(--hraness-foil-2, oklch(0.52 0.15 285))",
+  },
+  "--_hraness-foil-3": {
+    "default": "var(--hraness-foil-3, oklch(0.92 0.05 170))",
+    "@media (prefers-color-scheme: dark)": "var(--hraness-foil-3, oklch(0.66 0.14 175))",
+  },
+  "--_hraness-foil-4": {
+    "default": "var(--hraness-foil-4, oklch(0.95 0.045 96))",
+    "@media (prefers-color-scheme: dark)": "var(--hraness-foil-4, oklch(0.72 0.13 100))",
+  },
+  "--_hraness-foil-5": {
+    "default": "var(--hraness-foil-5, oklch(0.9 0.05 55))",
+    "@media (prefers-color-scheme: dark)": "var(--hraness-foil-5, oklch(0.55 0.15 45))",
+  },
+  "--_hraness-foil-6": {
+    "default": "var(--hraness-foil-6, oklch(0.875 0.06 305))",
+    "@media (prefers-color-scheme: dark)": "var(--hraness-foil-6, oklch(0.62 0.16 305))",
+  },
+};
+
+// Bordered surfaces resolve the edge through a private scheme-conditioned stop
+// so a product's public --hraness-foil-edge override wins ahead of either scheme
+// default, exactly like the --_hraness-foil-* spectrum stops.
+const foilEdgeStops = {
+  "--_hraness-foil-edge": {
+    "default": "var(--hraness-foil-edge, light-dark(black, white))",
+    "@media (prefers-color-scheme: dark)": "var(--hraness-foil-edge, white)",
+  },
+};
+
+/** Theme-aware monochrome emphasis edge for bordered foil surfaces. */
+export const foilEdge = "var(--_hraness-foil-edge, light-dark(black, white))";
+
+export const foilTextImage = "var(--hraness-foil-image, radial-gradient(ellipse 24% 85% at var(--hraness-foil-x, 50%) var(--hraness-foil-y, 50%), color-mix(in oklch, var(--hraness-foil-text-base, var(--foreground, CanvasText)) 80%, var(--background, Canvas)) 0%, transparent 68%), radial-gradient(ellipse 65% 160% at calc(100% - var(--hraness-foil-x, 50%)) calc(100% - var(--hraness-foil-y, 50%)), color-mix(in oklch, var(--hraness-foil-text-base, var(--foreground, CanvasText)) 98%, var(--background, Canvas)) 0%, transparent 72%), linear-gradient(115deg, color-mix(in srgb, var(--_hraness-foil-1) var(--hraness-foil-reflection, 14%), transparent), color-mix(in srgb, var(--_hraness-foil-2) var(--hraness-foil-reflection, 14%), transparent), color-mix(in srgb, var(--_hraness-foil-3) var(--hraness-foil-reflection, 14%), transparent), color-mix(in srgb, var(--_hraness-foil-4) var(--hraness-foil-reflection, 14%), transparent), color-mix(in srgb, var(--_hraness-foil-5) var(--hraness-foil-reflection, 14%), transparent), color-mix(in srgb, var(--_hraness-foil-6) var(--hraness-foil-reflection, 14%), transparent)), linear-gradient(115deg, color-mix(in oklch, var(--hraness-foil-text-base, var(--foreground, CanvasText)) 90%, var(--background, Canvas)) 0%, color-mix(in oklch, var(--hraness-foil-text-base, var(--foreground, CanvasText)) 100%, var(--background, Canvas)) 24%, color-mix(in oklch, var(--hraness-foil-text-base, var(--foreground, CanvasText)) 86%, var(--background, Canvas)) 39%, color-mix(in oklch, var(--hraness-foil-text-base, var(--foreground, CanvasText)) 100%, var(--background, Canvas)) 56%, color-mix(in oklch, var(--hraness-foil-text-base, var(--foreground, CanvasText)) 84%, var(--background, Canvas)) 82%, color-mix(in oklch, var(--hraness-foil-text-base, var(--foreground, CanvasText)) 100%, var(--background, Canvas)) 100%))";
+
+export const foilHalo = "0 1px 4px color-mix(in srgb, var(--foreground, CanvasText) 12%, transparent)";
+
+export const foilTextHalo = "none";
+
+export const foilStyles = stylex.create({
+  surface: {
+    ...foilEdgeStops,
+    "--hraness-foil-glow": {
+      "default": "0",
+      "@media (hover: hover)": { ":hover:not(:disabled)": "1" },
+    },
+    "border-top-width": "2px",
+    "border-right-width": "2px",
+    "border-bottom-width": "2px",
+    "border-left-width": "2px",
+    "border-top-style": "solid",
+    "border-right-style": "solid",
+    "border-bottom-style": "solid",
+    "border-left-style": "solid",
+    "border-top-color": { "default": foilEdge, "@media (forced-colors: active)": "ButtonText" },
+    "border-right-color": { "default": foilEdge, "@media (forced-colors: active)": "ButtonText" },
+    "border-bottom-color": { "default": foilEdge, "@media (forced-colors: active)": "ButtonText" },
+    "border-left-color": { "default": foilEdge, "@media (forced-colors: active)": "ButtonText" },
+    "background-color": {
+      "default": "var(--hraness-foil-surface, var(--surface, var(--background, Canvas)))",
+      "@media (forced-colors: active)": "Canvas",
+    },
+    "box-shadow": { "default": foilHalo, "@media (forced-colors: active)": "none" },
+    "color": { "default": null, "@media (forced-colors: active)": "CanvasText" },
+  },
+  text: {
+    ...foilStops,
+    "--hraness-foil-glow": {
+      "default": "0",
+      "@media (hover: hover)": { ":hover": "1" },
+    },
+    "background-image": {
+      "default": foilTextImage,
+      "@media (forced-colors: active)": "none",
+    },
+    "-webkit-background-clip": "text",
+    "background-clip": "text",
+    "color": { "default": "transparent", "@media (forced-colors: active)": "CanvasText" },
+    "-webkit-text-fill-color": { "default": "transparent", "@media (forced-colors: active)": "CanvasText" },
+    "filter": "none",
+  },
+});
+
+const foilHooks = {
+  surface: "hraness-foil",
+  text: "hraness-foil-text",
+} as const;
+
+export type FoilKind = keyof typeof foilHooks;
+
+/** Stable hook plus compiled atoms; caller classes stay last and win conflicts. */
+export function foilClassName(kind: FoilKind, caller?: string): string {
+  const hook = foilHooks[kind];
+  return [hook, stylex.props(foilStyles[kind]).className, caller]
+    .filter((value) => value !== undefined && value.length > 0).join(" ");
+}
+
+
+const markStyles = stylex.create({
+  root: {
+    "display": "inline-flex",
+    "position": "relative",
+    "flex-shrink": "0",
+    "color": "var(--foreground, CanvasText)",
+    "line-height": "0",
+    "vertical-align": "middle",
+    "inline-size": "var(--hraness-foil-size, 1.5rem)",
+    "block-size": "var(--hraness-foil-size, 1.5rem)",
+  },
+  image: {
+    "display": "block",
+    "inline-size": "100%",
+    "block-size": "100%",
+    "object-fit": "contain",
+  },
+  paint: {
+    ...foilStops,
+    // A generic display:none atom can be repeated by a later package layer and
+    // override our supported-mask state. Keep the conditional state mark-owned.
+    "display": "var(--_hraness-foil-mark-display)",
+    "--_hraness-foil-mark-display": {
+      "default": "none",
+      "@supports (mask-image: linear-gradient(black, black))": {
+        "default": "block",
+        "@media (forced-colors: active)": "none",
+      },
+    },
+    "position": "absolute",
+    "inset": "0",
+    "pointer-events": "none",
+    "background-image": foilTextImage,
+    "mask-image": "var(--hraness-foil-mask, linear-gradient(transparent, transparent))",
+    "mask-mode": "alpha",
+    "mask-repeat": "no-repeat",
+    "mask-position": "center",
+    "mask-size": "contain",
+  },
+});
+
+export function foilMarkClassName(part: keyof typeof markStyles, caller?: string): string {
+  const hook = part === "root" ? "hraness-foil-mark" : `hraness-foil-mark__${part}`;
+  return [hook, stylex.props(markStyles[part]).className, caller].filter(Boolean).join(" ");
+}

package/src/react/haptics.ts

@@ -0,0 +1,228 @@
+"use client";
+
+import { useCallback, useEffect } from "react";
+import type { WebHaptics } from "web-haptics";
+
+export type HapticFeedback = "error" | "press" | "selection" | "success" | "warning";
+export type HapticFeedbackInput = "error" | "medium" | "selection" | "success" | "warning";
+
+/**
+ * Browser-only proof seam emitted after Web Haptics accepts and completes a
+ * semantic trigger. Product behavior must never depend on this event.
+ */
+export const HAPTIC_FEEDBACK_EVENT_NAME = "hraness-design:haptic-feedback";
+
+export interface HapticFeedbackEventDetail {
+  readonly feedback: HapticFeedback;
+  readonly input: HapticFeedbackInput;
+}
+
+export interface HapticBrowserEnvironment {
+  readonly document?: unknown;
+  readonly navigator?: unknown;
+  readonly window?: unknown;
+}
+
+type HapticEngine = Pick<WebHaptics, "cancel" | "destroy" | "trigger">;
+type HapticEngineConstructor = new (
+  options?: Readonly<{ debug?: boolean; showSwitch?: boolean }>,
+) => HapticEngine;
+
+export interface HapticModule {
+  readonly WebHaptics: HapticEngineConstructor;
+}
+
+export interface HapticFeedbackController {
+  readonly cancel: () => boolean;
+  readonly dispose: () => void;
+  readonly prepare: () => Promise<boolean>;
+  readonly trigger: (feedback?: HapticFeedback) => Promise<boolean>;
+}
+
+/** The adapter is deliberately inert during SSR and other DOM-less runtimes. */
+export function isHapticBrowserEnvironment(
+  environment: HapticBrowserEnvironment = globalThis,
+): boolean {
+  return typeof environment.window === "object"
+    && typeof environment.document === "object"
+    && typeof environment.navigator === "object";
+}
+
+/** Maps product-neutral intent to WebHaptics' short semantic presets. */
+export function hapticInputForFeedback(feedback: HapticFeedback): HapticFeedbackInput {
+  switch (feedback) {
+    case "error":
+      return "error";
+    case "press":
+      return "medium";
+    case "selection":
+      return "selection";
+    case "success":
+      return "success";
+    case "warning":
+      return "warning";
+  }
+}
+
+function hasCustomEventConstructor(
+  candidate: unknown,
+): candidate is Readonly<{ CustomEvent: typeof CustomEvent }> {
+  return typeof candidate === "object"
+    && candidate !== null
+    && "CustomEvent" in candidate
+    && typeof candidate.CustomEvent === "function";
+}
+
+function hasEventDispatcher(
+  candidate: unknown,
+): candidate is Readonly<{ dispatchEvent: (event: Event) => boolean }> {
+  return typeof candidate === "object"
+    && candidate !== null
+    && "dispatchEvent" in candidate
+    && typeof candidate.dispatchEvent === "function";
+}
+
+function dispatchHapticFeedbackEvent(
+  environment: HapticBrowserEnvironment,
+  detail: HapticFeedbackEventDetail,
+): void {
+  if (!hasCustomEventConstructor(environment.window)
+    || !hasEventDispatcher(environment.document)) return;
+  try {
+    environment.document.dispatchEvent(
+      new environment.window.CustomEvent<HapticFeedbackEventDetail>(
+        HAPTIC_FEEDBACK_EVENT_NAME,
+        { detail },
+      ),
+    );
+  } catch {
+    // The verification signal is observational and must not affect feedback.
+  }
+}
+
+function cancelAndDestroy(candidate: HapticEngine): void {
+  try {
+    candidate.cancel();
+  } catch {
+    // Continue into destroy even if a browser backend rejects cancellation.
+  }
+  try {
+    candidate.destroy();
+  } catch {
+    // Optional feedback must never make application teardown fail.
+  }
+}
+
+/**
+ * Isolated lifecycle controller. Passing the environment and loader keeps the
+ * browser path deterministic in tests without installing or mutating globals.
+ */
+export function createHapticFeedbackController(
+  environment: HapticBrowserEnvironment,
+  loadModule: () => Promise<HapticModule>,
+): HapticFeedbackController {
+  let engine: HapticEngine | null = null;
+  let enginePromise: Promise<HapticEngine | null> | null = null;
+  let engineGeneration = 0;
+
+  const loadEngine = async (): Promise<HapticEngine | null> => {
+    if (!isHapticBrowserEnvironment(environment)) return null;
+    if (engine !== null) return engine;
+    if (enginePromise !== null) return enginePromise;
+
+    const generation = engineGeneration;
+    const pendingEngine = loadModule()
+      .then(({ WebHaptics }) => {
+        if (!isHapticBrowserEnvironment(environment)) return null;
+        const candidate = new WebHaptics({ debug: false, showSwitch: false });
+        if (generation !== engineGeneration) {
+          cancelAndDestroy(candidate);
+          return null;
+        }
+        engine = candidate;
+        return candidate;
+      })
+      .catch(() => null);
+    enginePromise = pendingEngine;
+    void pendingEngine.finally(() => {
+      if (enginePromise === pendingEngine) enginePromise = null;
+    });
+
+    return pendingEngine;
+  };
+
+  return {
+    cancel() {
+      if (engine === null) return false;
+      try {
+        engine.cancel();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    dispose() {
+      engineGeneration += 1;
+      const activeEngine = engine;
+      engine = null;
+      enginePromise = null;
+      if (activeEngine !== null) cancelAndDestroy(activeEngine);
+    },
+    async prepare() {
+      return await loadEngine() !== null;
+    },
+    async trigger(feedback: HapticFeedback = "press") {
+      try {
+        const activeEngine = await loadEngine();
+        if (activeEngine === null) return false;
+        const input = hapticInputForFeedback(feedback);
+        await activeEngine.trigger(input);
+        dispatchHapticFeedbackEvent(environment, { feedback, input });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+const browserHaptics = createHapticFeedbackController(globalThis, async () => {
+  const { WebHaptics } = await import("web-haptics");
+  return { WebHaptics };
+});
+
+/** Warms the browser-only engine so a later user gesture can trigger synchronously. */
+export async function prepareHapticFeedback(): Promise<boolean> {
+  return await browserHaptics.prepare();
+}
+
+/** Triggers semantic feedback and degrades to a no-op when unavailable or blocked. */
+export async function triggerHapticFeedback(
+  feedback: HapticFeedback = "press",
+): Promise<boolean> {
+  return await browserHaptics.trigger(feedback);
+}
+
+export function cancelHapticFeedback(): boolean {
+  return browserHaptics.cancel();
+}
+
+export function disposeHapticFeedback(): void {
+  browserHaptics.dispose();
+}
+
+/** Opt-in React adapter. Disabled callers do not preload the package. */
+export function useHapticFeedback(enabled = true): (
+  feedback?: HapticFeedback,
+) => Promise<boolean> {
+  useEffect(() => {
+    if (enabled) void prepareHapticFeedback();
+  }, [enabled]);
+
+  return useCallback(
+    async (feedback: HapticFeedback = "press") => enabled
+      ? await triggerHapticFeedback(feedback)
+      : false,
+    [enabled],
+  );
+}

package/src/react/hero-backdrop.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+/** @deprecated Hero backdrops are retired; `HeroBackdrop` renders nothing. */
+export interface HeroBackdropProps {
+  /** @deprecated Ignored. */
+  readonly seed: string;
+  /** @deprecated Ignored. Decorative artwork no longer renders; put real product proof in the hero `frame`. */
+  readonly children?: ReactNode;
+}
+
+/**
+ * @deprecated Retired with the Quiet marketing direction. The component stays
+ * exported so existing callers compile, but it renders nothing: no light
+ * field, drift, blur, or product artwork. Remove it when convenient and show
+ * real product proof in `ProductHero`'s `frame` instead.
+ */
+export function HeroBackdrop(props: HeroBackdropProps): null {
+  void props;
+  return null;
+}

package/src/react/index.ts

@@ -0,0 +1,38 @@
+export * from "./animated-rail-stage.js";
+export * from "./app-shell.js";
+export * from "./article.js";
+export * from "./aurora-dots-background.js";
+export * from "./charts.js";
+export * from "./chat.js";
+export * from "./design-theme-context.js";
+export * from "./design-palette.js";
+export * from "./design-gallery.js";
+export * from "./fader.js";
+export * from "./foil-card-math.js";
+export * from "./foil-card-surface.js";
+export * from "./foil.stylex.js";
+export * from "./haptics.js";
+export * from "./hero-backdrop.js";
+export * from "./keyboard-shortcuts.js";
+export * from "./lantern-material.stylex.js";
+export * from "./lantern-material-gallery.js";
+export * from "./navigation-rail.js";
+export * from "./particle-halo.js";
+export * from "./phaser-dots.js";
+export * from "./playback-transport.js";
+export * from "./procedural-backdrop.js";
+export * from "./procedural-recipe.js";
+export * from "./relative-time.js";
+export * from "./production-data-preview-notice.js";
+export * from "./product-marketing.js";
+export * from "./route-state.js";
+export * from "./sticky-offset.js";
+export * from "./surfaces.js";
+export * from "./syntax-code.js";
+export * from "./theme.js";
+export * from "./foil-mark.js";
+export * from "./provider-mark.js";
+export * from "./launch-beats.js";
+export * from "./social-kit-panel.js";
+export * from "./platform-icons.js";
+export * from "./platform-install.js";