@hraness/design-kit 0.31.1

package/src/react/phaser-dots.tsx

@@ -0,0 +1,501 @@
+"use client";
+
+import { useEffect, useRef, type CSSProperties, type HTMLAttributes } from "react";
+import { cn } from "@hraness/ui";
+import * as stylex from "@stylexjs/stylex";
+
+import { effectsStyles } from "./effects.stylex.js";
+
+export interface PhaserDotsProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  | "aria-hidden"
+  | "children"
+  | "contentEditable"
+  | "inert"
+  | "role"
+  | "suppressContentEditableWarning"
+  | "tabIndex"
+> {
+  fadeDirection?: "top" | "bottom" | "left" | "right" | "none";
+  mouseGlow?: boolean;
+  /** Override the static dot layer's color/opacity classes. */
+  dotClassName?: string;
+  /** Override the mouse-trail canvas color class. */
+  trailClassName?: string;
+}
+
+const DOT_PATTERN = "hraness-design-phaser-dots__static";
+
+const INERT_PROPS = { inert: true } as unknown as HTMLAttributes<HTMLDivElement>;
+
+export function PhaserDots({
+  className,
+  fadeDirection = "none",
+  mouseGlow = false,
+  dotClassName,
+  trailClassName,
+  style,
+  ...props
+}: PhaserDotsProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    if (!mouseGlow) return;
+    // Motion accessibility: the pointer-trail is a JS/canvas animation the
+    // global prefers-reduced-motion CSS block can't reach, so gate it here.
+    // The static dot layer still renders; only the animated trail is skipped.
+    if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+    const container = containerRef.current;
+    const canvas = canvasRef.current;
+    if (!container || !canvas) return;
+
+    const ctx = canvas.getContext("2d", { alpha: true });
+    if (!ctx) return;
+
+    const DOT_STEP = 6;
+    const PRIMARY_TRAIL_ALPHA = 0.48;
+    const PRIMARY_TRAIL_DECAY_MS = 3800;
+    const SECONDARY_TRAIL_ALPHA = 0.34;
+    const SECONDARY_TRAIL_DECAY_MS = 10500;
+    const MAX_TRAIL_POINTS = 160;
+    const POINT_SPACING = DOT_STEP;
+    const MAX_INTERPOLATION_STEPS = 2;
+    const MAX_RENDERED_PRIMARY_TRAIL_POINTS = 24;
+    const MAX_RENDERED_SECONDARY_TRAIL_POINTS = 16;
+    const CLICK_TRAIL_STAMP = [
+      { dx: 0, dy: 0 },
+      { dx: DOT_STEP, dy: 0 },
+      { dx: -DOT_STEP, dy: 0 },
+      { dx: 0, dy: DOT_STEP },
+      { dx: 0, dy: -DOT_STEP },
+    ] as const;
+
+    const HOVER_BRUSH_RADIUS = 54;
+    const HOVER_BRUSH_ALPHA = 0.6;
+    const HOVER_BRUSH_DECAY_MS = 900;
+    const MAX_HOVER_POINTS = 6;
+
+    const INTERACTION_PAD = HOVER_BRUSH_RADIUS;
+    const RECT_CACHE_MS = 180;
+    const FRAME_MIN_INTERVAL_MS = 33;
+    const COLOR_CACHE_MS = 1000;
+    const DOT_KEY_STRIDE = 8192;
+    const CANVAS_DOT_SIZE = 2;
+    const CANVAS_DOT_HALF = CANVAS_DOT_SIZE / 2;
+
+    const trail: { x: number; y: number; t: number }[] = [];
+    const hoverBrush: { x: number; y: number; t: number }[] = [];
+    const dotAlpha = new Map<number, number>();
+    const hoverOffsets: Array<{ dx: number; dy: number; weight: number }> = [];
+
+    let lastPoint: { x: number; y: number } | null = null;
+    let lastHoverPoint: { x: number; y: number } | null = null;
+    let pendingMove: { x: number; y: number } | null = null;
+    let pendingDown: { x: number; y: number } | null = null;
+    let cachedRect = container.getBoundingClientRect();
+    let lastRectRead = 0;
+    let lastFrameTime = 0;
+    let lastColorRead = 0;
+    let drawColor = getComputedStyle(canvas).color;
+    let raf = 0;
+    let dpr = Math.max(1, window.devicePixelRatio || 1);
+    let canvasWidth = Math.max(1, Math.round(cachedRect.width));
+    let canvasHeight = Math.max(1, Math.round(cachedRect.height));
+
+    const snapToGrid = (value: number) =>
+      Math.round(value / DOT_STEP) * DOT_STEP;
+
+    const resizeCanvas = () => {
+      const rect = container.getBoundingClientRect();
+      cachedRect = rect;
+      const width = Math.max(1, Math.round(rect.width));
+      const height = Math.max(1, Math.round(rect.height));
+      const nextDpr = Math.max(1, window.devicePixelRatio || 1);
+      if (
+        width === canvasWidth &&
+        height === canvasHeight &&
+        nextDpr === dpr &&
+        canvas.width === Math.round(width * nextDpr) &&
+        canvas.height === Math.round(height * nextDpr)
+      ) {
+        return;
+      }
+      canvasWidth = width;
+      canvasHeight = height;
+      dpr = nextDpr;
+      canvas.width = Math.round(canvasWidth * dpr);
+      canvas.height = Math.round(canvasHeight * dpr);
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      ctx.clearRect(0, 0, canvasWidth, canvasHeight);
+    };
+
+    for (
+      let dx = -HOVER_BRUSH_RADIUS;
+      dx <= HOVER_BRUSH_RADIUS;
+      dx += DOT_STEP
+    ) {
+      for (
+        let dy = -HOVER_BRUSH_RADIUS;
+        dy <= HOVER_BRUSH_RADIUS;
+        dy += DOT_STEP
+      ) {
+        const dist = Math.hypot(dx, dy);
+        if (dist > HOVER_BRUSH_RADIUS) continue;
+        hoverOffsets.push({
+          dx,
+          dy,
+          weight: 1 - dist / HOVER_BRUSH_RADIUS,
+        });
+      }
+    }
+
+    resizeCanvas();
+    const resizeObserver = new ResizeObserver(() => {
+      resizeCanvas();
+    });
+    resizeObserver.observe(container);
+
+    const getContainerRect = (now: number) => {
+      if (now - lastRectRead > RECT_CACHE_MS) {
+        cachedRect = container.getBoundingClientRect();
+        lastRectRead = now;
+      }
+      return cachedRect;
+    };
+
+    const getLocalPoint = (clientX: number, clientY: number, now: number) => {
+      const rect = getContainerRect(now);
+      const nearContainer =
+        clientX >= rect.left - INTERACTION_PAD &&
+        clientX <= rect.right + INTERACTION_PAD &&
+        clientY >= rect.top - INTERACTION_PAD &&
+        clientY <= rect.bottom + INTERACTION_PAD;
+      if (!nearContainer) return null;
+
+      return {
+        x: snapToGrid(clientX - rect.left),
+        y: snapToGrid(clientY - rect.top),
+      };
+    };
+
+    const putDot = (x: number, y: number, alpha: number) => {
+      if (alpha <= 0) return;
+      const sx = snapToGrid(x);
+      const sy = snapToGrid(y);
+      if (sx < 0 || sy < 0 || sx > canvasWidth || sy > canvasHeight) return;
+      const key = sx + sy * DOT_KEY_STRIDE;
+      const prev = dotAlpha.get(key);
+      if (prev === undefined || alpha > prev) {
+        dotAlpha.set(key, alpha);
+      }
+    };
+
+    const pushHoverBrushPoint = (x: number, y: number) => {
+      if (lastHoverPoint?.x === x && lastHoverPoint.y === y) return;
+      hoverBrush.push({ x, y, t: performance.now() });
+      if (hoverBrush.length > MAX_HOVER_POINTS) {
+        hoverBrush.splice(0, hoverBrush.length - MAX_HOVER_POINTS);
+      }
+      lastHoverPoint = { x, y };
+    };
+
+    const pushTrailPoint = (x: number, y: number) => {
+      const now = performance.now();
+      if (!lastPoint) {
+        trail.push({ x, y, t: now });
+      } else {
+        const dx = x - lastPoint.x;
+        const dy = y - lastPoint.y;
+        const dist = Math.hypot(dx, dy);
+        if (dist < POINT_SPACING) return;
+        const steps = Math.min(
+          MAX_INTERPOLATION_STEPS,
+          Math.max(1, Math.floor(dist / POINT_SPACING)),
+        );
+        for (let i = 1; i <= steps; i += 1) {
+          const ratio = i / steps;
+          const px = snapToGrid(lastPoint.x + dx * ratio);
+          const py = snapToGrid(lastPoint.y + dy * ratio);
+          if (
+            trail[trail.length - 1]?.x === px &&
+            trail[trail.length - 1]?.y === py
+          ) {
+            continue;
+          }
+          trail.push({ x: px, y: py, t: now });
+        }
+      }
+      if (trail.length > MAX_TRAIL_POINTS) {
+        trail.splice(0, trail.length - MAX_TRAIL_POINTS);
+      }
+      lastPoint = { x, y };
+    };
+
+    const stampClickTrail = (x: number, y: number, t: number) => {
+      for (const offset of CLICK_TRAIL_STAMP) {
+        trail.push({
+          x: snapToGrid(x + offset.dx),
+          y: snapToGrid(y + offset.dy),
+          t,
+        });
+      }
+      if (trail.length > MAX_TRAIL_POINTS) {
+        trail.splice(0, trail.length - MAX_TRAIL_POINTS);
+      }
+    };
+
+    const renderDots = (now: number) => {
+      dotAlpha.clear();
+
+      for (let i = hoverBrush.length - 1; i >= 0; i -= 1) {
+        const p = hoverBrush[i];
+        if (p === undefined) continue;
+        const baseAlpha =
+          HOVER_BRUSH_ALPHA *
+          Math.max(0, 1 - (now - p.t) / HOVER_BRUSH_DECAY_MS);
+        if (baseAlpha <= 0) continue;
+        for (let j = 0; j < hoverOffsets.length; j += 1) {
+          const off = hoverOffsets[j];
+          if (off === undefined) continue;
+          putDot(p.x + off.dx, p.y + off.dy, baseAlpha * off.weight);
+        }
+      }
+
+      let primaryCount = 0;
+      let secondaryCount = 0;
+      let sampledPrimaryCounter = 0;
+      let sampledSecondaryCounter = 0;
+      for (
+        let i = trail.length - 1;
+        i >= 0 &&
+        (primaryCount < MAX_RENDERED_PRIMARY_TRAIL_POINTS ||
+          secondaryCount < MAX_RENDERED_SECONDARY_TRAIL_POINTS);
+        i -= 1
+      ) {
+        const p = trail[i];
+        if (p === undefined) continue;
+        const agePrimary = (now - p.t) / PRIMARY_TRAIL_DECAY_MS;
+        const ageSecondary = (now - p.t) / SECONDARY_TRAIL_DECAY_MS;
+        if (ageSecondary > 1) continue;
+
+        if (
+          primaryCount < MAX_RENDERED_PRIMARY_TRAIL_POINTS &&
+          agePrimary <= 1
+        ) {
+          if (agePrimary > 0.35) {
+            const stride = agePrimary > 0.75 ? 4 : 2;
+            if (sampledPrimaryCounter % stride !== 0) {
+              sampledPrimaryCounter += 1;
+            } else {
+              putDot(
+                p.x,
+                p.y,
+                PRIMARY_TRAIL_ALPHA * Math.max(0, 1 - agePrimary),
+              );
+              primaryCount += 1;
+              sampledPrimaryCounter += 1;
+            }
+          } else {
+            putDot(p.x, p.y, PRIMARY_TRAIL_ALPHA * Math.max(0, 1 - agePrimary));
+            primaryCount += 1;
+          }
+        }
+
+        if (secondaryCount < MAX_RENDERED_SECONDARY_TRAIL_POINTS) {
+          if (ageSecondary > 0.3) {
+            const stride = ageSecondary > 0.75 ? 5 : 3;
+            if (sampledSecondaryCounter % stride !== 0) {
+              sampledSecondaryCounter += 1;
+              continue;
+            }
+            sampledSecondaryCounter += 1;
+          }
+          putDot(
+            p.x,
+            p.y,
+            SECONDARY_TRAIL_ALPHA * Math.max(0, 1 - ageSecondary),
+          );
+          secondaryCount += 1;
+        }
+      }
+
+      if (dotAlpha.size === 0) {
+        ctx.clearRect(0, 0, canvasWidth, canvasHeight);
+        return;
+      }
+
+      if (now - lastColorRead > COLOR_CACHE_MS) {
+        drawColor = getComputedStyle(canvas).color;
+        lastColorRead = now;
+      }
+
+      ctx.clearRect(0, 0, canvasWidth, canvasHeight);
+      ctx.fillStyle = drawColor;
+      for (const [key, alpha] of dotAlpha) {
+        const x = key % DOT_KEY_STRIDE;
+        const y = (key - x) / DOT_KEY_STRIDE;
+        ctx.globalAlpha = alpha;
+        ctx.fillRect(
+          x - CANVAS_DOT_HALF,
+          y - CANVAS_DOT_HALF,
+          CANVAS_DOT_SIZE,
+          CANVAS_DOT_SIZE,
+        );
+      }
+      ctx.globalAlpha = 1;
+    };
+
+    const tick = (frameTime: number) => {
+      if (
+        lastFrameTime !== 0 &&
+        frameTime - lastFrameTime < FRAME_MIN_INTERVAL_MS
+      ) {
+        raf = requestAnimationFrame(tick);
+        return;
+      }
+      lastFrameTime = frameTime;
+      const now = performance.now();
+
+      if (pendingDown) {
+        const point = getLocalPoint(pendingDown.x, pendingDown.y, now);
+        pendingDown = null;
+        if (point) {
+          pushHoverBrushPoint(point.x, point.y);
+          stampClickTrail(point.x, point.y, now);
+          pushTrailPoint(point.x, point.y);
+        }
+      }
+
+      if (pendingMove) {
+        const point = getLocalPoint(pendingMove.x, pendingMove.y, now);
+        pendingMove = null;
+        if (point) {
+          pushHoverBrushPoint(point.x, point.y);
+          pushTrailPoint(point.x, point.y);
+        } else {
+          lastPoint = null;
+          lastHoverPoint = null;
+        }
+      }
+
+      while (true) {
+        const oldest = hoverBrush[0];
+        if (oldest === undefined || now - oldest.t <= HOVER_BRUSH_DECAY_MS) break;
+        hoverBrush.shift();
+      }
+      while (true) {
+        const oldest = trail[0];
+        if (oldest === undefined || now - oldest.t <= SECONDARY_TRAIL_DECAY_MS) break;
+        trail.shift();
+      }
+
+      if (hoverBrush.length === 0 && trail.length === 0) {
+        ctx.clearRect(0, 0, canvasWidth, canvasHeight);
+        raf = 0;
+        return;
+      }
+
+      renderDots(now);
+      raf = requestAnimationFrame(tick);
+    };
+
+    const handleMove = (e: PointerEvent) => {
+      pendingMove = { x: e.clientX, y: e.clientY };
+      if (!raf) raf = requestAnimationFrame(tick);
+    };
+
+    const handleDown = (e: PointerEvent) => {
+      if (e.pointerType === "mouse" && e.button !== 0) return;
+      pendingDown = { x: e.clientX, y: e.clientY };
+      if (!raf) raf = requestAnimationFrame(tick);
+    };
+
+    const handleUp = () => {
+      lastPoint = null;
+    };
+
+    const passive = { passive: true };
+    document.addEventListener("pointermove", handleMove, passive);
+    document.addEventListener("pointerdown", handleDown, passive);
+    document.addEventListener("pointerup", handleUp, passive);
+    document.addEventListener("pointercancel", handleUp, passive);
+
+    return () => {
+      document.removeEventListener("pointermove", handleMove);
+      document.removeEventListener("pointerdown", handleDown);
+      document.removeEventListener("pointerup", handleUp);
+      document.removeEventListener("pointercancel", handleUp);
+      resizeObserver.disconnect();
+      if (raf) cancelAnimationFrame(raf);
+      ctx.clearRect(0, 0, canvasWidth, canvasHeight);
+    };
+  }, [mouseGlow]);
+
+  const maskGradient =
+    fadeDirection === "top"
+      ? "linear-gradient(to top, rgba(0,0,0,1) 0%, rgba(0,0,0,0) 100%)"
+      : fadeDirection === "bottom"
+        ? "linear-gradient(to bottom, rgba(0,0,0,1) 0%, rgba(0,0,0,0) 100%)"
+        : fadeDirection === "left"
+          ? "linear-gradient(to left, rgba(0,0,0,1) 0%, rgba(0,0,0,0) 100%)"
+          : fadeDirection === "right"
+            ? "linear-gradient(to right, rgba(0,0,0,1) 0%, rgba(0,0,0,0) 100%)"
+            : undefined;
+
+  const mergedStyle: CSSProperties | undefined = maskGradient
+    ? {
+        WebkitMaskImage: maskGradient,
+        maskImage: maskGradient,
+        ...style,
+      }
+    : style;
+  const rootPresentation = stylex.props(
+    effectsStyles.phaserSlot,
+    effectsStyles.phaserRoot,
+  );
+  const staticPresentation = stylex.props(
+    effectsStyles.phaserSlot,
+    effectsStyles.phaserStatic,
+    !dotClassName && effectsStyles.phaserStaticDefault,
+  );
+  const trailPresentation = stylex.props(
+    effectsStyles.phaserSlot,
+    effectsStyles.phaserTrail,
+    !trailClassName && effectsStyles.phaserTrailDefault,
+  );
+
+  return (
+    <div
+      {...props}
+      {...INERT_PROPS}
+      ref={containerRef}
+      role="presentation"
+      aria-hidden="true"
+      className={cn(
+        "hraness-design-phaser-dots",
+        rootPresentation.className,
+        className,
+      )}
+      style={mergedStyle}
+    >
+      <div
+        className={cn(
+          DOT_PATTERN,
+          staticPresentation.className,
+          dotClassName,
+        )}
+      />
+      {mouseGlow && (
+        <canvas
+          ref={canvasRef}
+          className={cn(
+            "hraness-design-phaser-dots__trail",
+            trailPresentation.className,
+            trailClassName,
+          )}
+        />
+      )}
+    </div>
+  );
+}

package/src/react/platform-icons.tsx

@@ -0,0 +1,94 @@
+import type { ReactNode } from "react";
+
+import { isPlatformId, platformLabel, platformMark, type PlatformId } from "../platforms.js";
+import { platformInstallClassName } from "./platform-install.stylex.js";
+
+export type PlatformIconSize = "sm" | "md" | "lg" | "inherit";
+
+export interface PlatformIconProps {
+  readonly platform: PlatformId;
+  readonly className?: string;
+  /**
+   * Decorative by default: pair the icon with a visible platform name. Pass a
+   * label only when the icon stands alone; it then renders as a named image.
+   */
+  readonly label?: string;
+  /** `inherit` (the default) follows the surrounding font size; `sm`, `md`, and `lg` are 1, 1.25, and 1.5rem. */
+  readonly size?: PlatformIconSize;
+}
+
+const sizeParts = { inherit: undefined, lg: "iconLg", md: "iconMd", sm: "iconSm" } as const;
+
+/**
+ * A monochrome platform mark drawn in `currentColor`: the Apple logo for
+ * macOS, Tux for Linux, the four-pane window for Windows, and a neutral
+ * terminal glyph for any other id.
+ */
+export function PlatformIcon({ className, label, platform, size = "inherit" }: PlatformIconProps) {
+  if (!isPlatformId(platform)) throw new RangeError(`Platform ids are lowercase slugs; received ${JSON.stringify(platform)}.`);
+  if (!(size in sizeParts)) throw new RangeError(`Unknown platform icon size: ${String(size)}.`);
+  if (label !== undefined && label.trim() === "") throw new RangeError("A platform icon label must not be blank.");
+  const mark = platformMark(platform);
+  return (
+    <svg
+      aria-hidden={label === undefined ? true : undefined}
+      aria-label={label}
+      className={platformInstallClassName(["icon", sizeParts[size]], className)}
+      data-platform={platform}
+      fill="currentColor"
+      focusable="false"
+      role={label === undefined ? undefined : "img"}
+      viewBox={mark.viewBox}
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d={mark.path} />
+    </svg>
+  );
+}
+
+export interface PlatformBadge {
+  readonly id: PlatformId;
+  /** Defaults to the known display name (`macOS`, `Linux`, `Windows`) or the id. */
+  readonly label?: string;
+  /** A short qualifier shown after the name, such as "Apple silicon". */
+  readonly note?: ReactNode;
+}
+
+export interface PlatformBadgesProps {
+  /** Platform ids or badge records, in display order. */
+  readonly platforms: readonly (PlatformId | PlatformBadge)[];
+  readonly className?: string;
+  /** The visible lead-in and list name. Defaults to "Runs on"; pass `null` to omit the visible text. */
+  readonly label?: string | null;
+}
+
+function toBadge(entry: PlatformId | PlatformBadge): PlatformBadge {
+  return typeof entry === "string" ? { id: entry } : entry;
+}
+
+/** A compact "Runs on" row: one icon and name per supported platform. */
+export function PlatformBadges({ className, label = "Runs on", platforms }: PlatformBadgesProps) {
+  const badges = platforms.map(toBadge);
+  if (badges.length === 0) throw new RangeError("PlatformBadges needs at least one platform.");
+  const seen = new Set<string>();
+  for (const badge of badges) {
+    if (!isPlatformId(badge.id)) throw new RangeError(`Platform ids are lowercase slugs; received ${JSON.stringify(badge.id)}.`);
+    if (seen.has(badge.id)) throw new RangeError(`Duplicate platform id: ${badge.id}.`);
+    seen.add(badge.id);
+  }
+  const listName = label ?? "Supported platforms";
+  return (
+    <div className={platformInstallClassName(["badges"], className)} data-hraness-platform-badges="">
+      {label === null ? null : <span aria-hidden="true" className={platformInstallClassName(["badgesLabel"])}>{label}</span>}
+      <ul aria-label={listName} className={platformInstallClassName(["badgesList"])}>
+        {badges.map((badge) => (
+          <li className={platformInstallClassName(["badge"])} data-platform={badge.id} key={badge.id}>
+            <PlatformIcon platform={badge.id} />
+            <span>{badge.label ?? platformLabel(badge.id)}</span>
+            {badge.note === undefined ? null : <span className={platformInstallClassName(["badgeNote"])}>{badge.note}</span>}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}