@spatika/react 1.1.0 → 1.2.0

package/src/composites/MapChart.tsx

@@ -0,0 +1,130 @@
+import { chartColor, formatChartNumber, type ChartMargin } from "../lib/charts";
+import {
+  featureId,
+  fitFeatures,
+  geoPath,
+  type GeoJsonFeatureCollection,
+  type GeoProjectionKind,
+} from "../lib/geo";
+import { ChartFrame, useChartHover } from "./chart-ui";
+
+export type MapShapeDatum = {
+  id: string | number;
+  value: number;
+  label?: string;
+  color?: string;
+};
+
+export type MapChartProps = {
+  geoData: GeoJsonFeatureCollection;
+  series?: Array<{ data: MapShapeDatum[] }>;
+  idProperty?: string;
+  projection?: GeoProjectionKind;
+  height?: number;
+  width?: number;
+  colors?: string[];
+  hideLegend?: boolean;
+  margin?: ChartMargin;
+  className?: string;
+};
+
+export function MapChart({
+  geoData,
+  series,
+  idProperty = "id",
+  projection = "mercator",
+  height = 280,
+  width,
+  colors,
+  hideLegend,
+  margin,
+  className,
+}: MapChartProps) {
+  const features = geoData.features ?? [];
+  const data = series?.[0]?.data ?? [];
+  const byId = new Map(data.map((item) => [String(item.id), item]));
+  const values = data.map((item) => item.value);
+  const min = values.length ? Math.min(...values) : 0;
+  const max = values.length ? Math.max(...values) : 1;
+  const { hover, setHover, clear } = useChartHover();
+  const legend = hideLegend
+    ? undefined
+    : data.slice(0, 8).map((item, i) => ({
+        id: String(item.id),
+        label: item.label ?? String(item.id),
+        color: item.color ?? choroplethFill(item.value, min, max, i, colors),
+      }));
+
+  return (
+    <ChartFrame
+      slot="map-chart"
+      className={className}
+      width={width}
+      height={height}
+      margin={margin ?? { top: 8, right: 8, bottom: 8, left: 8 }}
+      legend={legend}
+      hover={hover}
+      aria-label="Map chart"
+    >
+      {({ width: w, height: h, m }) => {
+        const pad = Math.min(m.left, m.right, m.top, m.bottom);
+        const project = fitFeatures(features, w, h, pad, projection);
+        return (
+          <svg width={w} height={h} viewBox={`0 0 ${w} ${h}`}>
+            {features.map((feature, i) => {
+              if (!feature.geometry) return null;
+              const id = featureId(feature, idProperty) || String(i);
+              const datum = byId.get(id);
+              const label =
+                datum?.label ??
+                (feature.properties?.name != null ? String(feature.properties.name) : id);
+              const fill = datum
+                ? (datum.color ?? choroplethFill(datum.value, min, max, i, colors))
+                : "color-mix(in srgb, var(--muted) 55%, transparent)";
+              const d = geoPath(feature.geometry, project);
+              if (!d) return null;
+              return (
+                <path
+                  key={id}
+                  d={d}
+                  fill={fill}
+                  className="spk-chart-map-region spk-chart-mark"
+                  onMouseEnter={(event) =>
+                    setHover({
+                      x: event.nativeEvent.offsetX,
+                      y: event.nativeEvent.offsetY,
+                      title: label,
+                      items: datum
+                        ? [
+                            {
+                              color: fill,
+                              label: label,
+                              value: formatChartNumber(datum.value),
+                            },
+                          ]
+                        : [{ color: fill, label: label, value: "—" }],
+                    })
+                  }
+                  onMouseLeave={clear}
+                />
+              );
+            })}
+          </svg>
+        );
+      }}
+    </ChartFrame>
+  );
+}
+
+function choroplethFill(
+  value: number,
+  min: number,
+  max: number,
+  index: number,
+  colors?: string[],
+): string {
+  const t = max === min ? 0.6 : (value - min) / (max - min);
+  const base = chartColor(index, colors);
+  const mix = Math.round(28 + t * 72);
+  return `color-mix(in srgb, ${base} ${mix}%, var(--muted))`;
+}

package/src/composites/ProfileHero.test.tsx

@@ -0,0 +1,33 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { ProfileHero } from "./ProfileHero";
+
+describe("ProfileHero", () => {
+  it("renders name, alias, and a notched identity plate", () => {
+    const { container } = render(
+      <ProfileHero name="Alex Chen" alias="Product designer" coverSeed="alex" bleed={false} />,
+    );
+    expect(screen.getByRole("heading", { name: "Alex Chen" })).toBeInTheDocument();
+    expect(screen.getByText("Product designer")).toBeInTheDocument();
+    expect(container.querySelector(".profile-identity")).toBeTruthy();
+    expect(container.querySelector(".profile-identity__plate")).toBeTruthy();
+    expect(container.querySelector("[data-slot='profile-hero']")).not.toHaveAttribute(
+      "data-cover-bleed",
+    );
+    expect(container.querySelector("[data-slot='profile-hero']")).toHaveClass("w-full");
+  });
+
+  it("keeps the avatar inert until onAvatarClick is provided", async () => {
+    const user = userEvent.setup();
+    const onAvatarClick = vi.fn();
+    const { rerender } = render(<ProfileHero name="Alex Chen" bleed={false} />);
+    expect(screen.getByRole("button", { name: "Alex Chen" })).toBeDisabled();
+
+    rerender(<ProfileHero name="Alex Chen" onAvatarClick={onAvatarClick} bleed={false} />);
+    const avatar = screen.getByRole("button", { name: "Alex Chen" });
+    expect(avatar).toBeEnabled();
+    await user.click(avatar);
+    expect(onAvatarClick).toHaveBeenCalledTimes(1);
+  });
+});

package/src/composites/ProfileHero.tsx

@@ -33,12 +33,14 @@ export type ProfileHeroProps = {
   coverKind?: CoverPatternKind | null;
   dark?: boolean;
   warm?: boolean;
+  /** When false, keep the cover inside this frame (catalog previews). */
+  bleed?: boolean;
 };
 
 /**
- * Profile / entity hero: cover bleeds into app chrome, overlapping avatar
- * notches the frosted identity plate. Stacked in a narrow column; left-notched
- * once the plate is wide enough (container query, not viewport).
+ * Profile / entity hero: cover fills the frame, overlapping avatar notches
+ * the frosted identity plate. Stacked in a narrow column; left-notched once
+ * the plate is wide enough (container query, not viewport).
  */
 export function ProfileHero({
   name,
@@ -63,6 +65,7 @@ export function ProfileHero({
   coverKind,
   dark,
   warm,
+  bleed = true,
 }: ProfileHeroProps) {
   const initials = getInitials(name);
   const seed = coverSeed ?? name;
@@ -70,92 +73,106 @@ export function ProfileHero({
   const ink = scene.headerInk;
 
   return (
-    <div data-slot="profile-hero" className={cn("relative overflow-visible", className)}>
+    <div
+      data-slot="profile-hero"
+      data-cover-bleed={bleed ? "true" : undefined}
+      className={cn(
+        "relative w-full",
+        bleed ? "overflow-visible" : "overflow-hidden rounded-[1.35rem] sm:rounded-[1.75rem]",
+        className,
+      )}
+    >
       <div
-        className={cn(
-          "relative min-h-[9rem] overflow-hidden sm:min-h-[12rem] lg:min-h-[13rem]",
-          coverClassName,
-        )}
+        className={cn("cover-media cover-media--profile", bleed && "sm:rounded-b-[2rem]")}
+        aria-hidden
       >
-        <div className="cover-media cover-media--profile sm:rounded-b-[2rem]" aria-hidden>
-          {!hideImages && coverUrl ? (
-            <img src={coverUrl} alt="" className="absolute inset-0 size-full object-cover" />
-          ) : (
-            <CoverPattern seed={seed} hue={coverHue} dark={dark} warm={warm} kind={coverKind} />
+        {!hideImages && coverUrl ? (
+          <img src={coverUrl} alt="" className="absolute inset-0 size-full object-cover" />
+        ) : (
+          <CoverPattern seed={seed} hue={coverHue} dark={dark} warm={warm} kind={coverKind} />
+        )}
+        <div className="absolute inset-x-0 top-0 h-8 bg-gradient-to-b from-black/[0.04] to-transparent dark:from-black/12" />
+        <div className="absolute inset-x-0 bottom-0 h-[22%] bg-gradient-to-t from-black/[0.03] via-transparent to-transparent dark:from-black/10" />
+      </div>
+
+      <div className="relative z-10 flex flex-col">
+        <div
+          className={cn(
+            "relative min-h-[8.5rem] sm:min-h-[11rem] lg:min-h-[12rem]",
+            coverClassName,
           )}
-          <div className="absolute inset-x-0 top-0 h-8 bg-gradient-to-b from-black/[0.04] to-transparent dark:from-black/12" />
-          <div className="absolute inset-x-0 bottom-0 h-[22%] bg-gradient-to-t from-black/[0.03] via-transparent to-transparent dark:from-black/10" />
-        </div>
-        <div className="relative z-10 flex min-h-[9rem] items-start justify-between gap-2 p-3 sm:min-h-[12rem] sm:p-4 lg:min-h-[13rem]">
-          <div>{topLeading}</div>
-          {topActions ? (
-            <div
-              data-cover-ink={ink}
-              className="cover-floating-shell flex items-center gap-1 p-1"
-            >
-              {topActions}
-            </div>
-          ) : null}
+        >
+          <div className="absolute inset-x-0 top-0 z-30 flex items-start justify-between gap-2 p-3 sm:p-4">
+            <div>{topLeading}</div>
+            {topActions ? (
+              <div
+                data-cover-ink={ink}
+                className="cover-floating-shell flex items-center gap-1 p-1"
+              >
+                {topActions}
+              </div>
+            ) : null}
+          </div>
         </div>
-      </div>
 
-      <div className="relative z-10 px-3 pb-4 sm:px-4 sm:pb-5 lg:px-8">
-        <div className={cn("profile-identity", identityClassName)}>
-          <div
-            aria-hidden
-            className={cn(
-              "pointer-events-none absolute inset-0 rounded-[1.35rem] profile-identity__plate",
-              coverPlateClass(ink),
-            )}
-          />
-          <div className="profile-identity__body">
-            <button
-              type="button"
-              disabled={!onAvatarClick}
-              onClick={onAvatarClick}
-              aria-label={name}
-              className="profile-identity__avatar"
-            >
-              <span
-                className="flex items-center justify-center overflow-hidden rounded-full border-[3px] border-white bg-muted text-lg font-black leading-none text-primary shadow-[0_16px_40px_rgba(0,0,0,0.38)] dark:border-white/30"
-                style={{
-                  width: "var(--profile-avatar-size)",
-                  height: "var(--profile-avatar-size)",
-                }}
+        <div className="relative z-20 px-3 pb-4 sm:px-4 sm:pb-5 lg:px-6">
+          <div className={cn("profile-identity", identityClassName)}>
+            <div
+              aria-hidden
+              className={cn(
+                "pointer-events-none absolute inset-0 rounded-[1.35rem] profile-identity__plate",
+                coverPlateClass(ink),
+              )}
+            />
+            <div className="profile-identity__body">
+              <button
+                type="button"
+                disabled={!onAvatarClick}
+                onClick={onAvatarClick}
+                aria-label={name}
+                className="profile-identity__avatar"
               >
-                {!hideImages && avatarUrl ? (
-                  <img src={avatarUrl} alt="" className="size-full object-cover" />
-                ) : (
-                  initials
-                )}
-              </span>
-              {avatarAccessory}
-            </button>
-            <div className="profile-identity__copy">
-              <div className="profile-identity__heading">
-                <h1
-                  className={cn(
-                    "truncate text-[1.15rem] font-black leading-tight tracking-tight sm:text-2xl",
-                    coverTitleClass(ink),
-                  )}
+                <span
+                  className="flex items-center justify-center overflow-hidden rounded-full border-[3px] border-white bg-muted text-lg font-black leading-none text-primary shadow-[0_16px_40px_rgba(0,0,0,0.38)] dark:border-white/30"
+                  style={{
+                    width: "var(--profile-avatar-size)",
+                    height: "var(--profile-avatar-size)",
+                  }}
                 >
-                  {name}
-                </h1>
-                {statusBadges}
+                  {!hideImages && avatarUrl ? (
+                    <img src={avatarUrl} alt="" className="size-full object-cover" />
+                  ) : (
+                    initials
+                  )}
+                </span>
+                {avatarAccessory}
+              </button>
+              <div className="profile-identity__copy">
+                <div className="profile-identity__heading">
+                  <h1
+                    className={cn(
+                      "truncate text-[1.15rem] font-black leading-tight tracking-tight sm:text-2xl",
+                      coverTitleClass(ink),
+                    )}
+                  >
+                    {name}
+                  </h1>
+                  {statusBadges}
+                </div>
+                {alias ? (
+                  <p className={cn("mt-0.5 truncate text-sm font-medium", coverMutedClass(ink))}>
+                    {alias}
+                  </p>
+                ) : null}
+                {metaLines ? (
+                  <div className={cn("mt-2 space-y-1 text-sm", coverMutedClass(ink))}>{metaLines}</div>
+                ) : null}
+                {stats ? <div className="mt-3">{stats}</div> : null}
+                {tags ? <div className="profile-identity__tags">{tags}</div> : null}
               </div>
-              {alias ? (
-                <p className={cn("mt-0.5 truncate text-sm font-medium", coverMutedClass(ink))}>
-                  {alias}
-                </p>
-              ) : null}
-              {metaLines ? (
-                <div className={cn("mt-2 space-y-1 text-sm", coverMutedClass(ink))}>{metaLines}</div>
-              ) : null}
-              {stats ? <div className="mt-3">{stats}</div> : null}
-              {tags ? <div className="profile-identity__tags">{tags}</div> : null}
             </div>
+            {children ? <div className="relative z-10 px-3 pb-3 sm:px-6">{children}</div> : null}
           </div>
-          {children ? <div className="relative z-10 px-3 pb-3 sm:px-6">{children}</div> : null}
         </div>
       </div>
     </div>

package/src/composites/ScatterWebGL.test.tsx

@@ -0,0 +1,25 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { ScatterWebGLLayer } from "./ScatterWebGL";
+
+describe("ScatterWebGLLayer", () => {
+  it("renders a canvas layer and reports when WebGL is unavailable", () => {
+    const onUnavailable = vi.fn();
+    const { container } = render(
+      <ScatterWebGLLayer
+        width={120}
+        height={80}
+        series={[{ data: [{ x: 1, y: 2 }] }]}
+        meta={[{ id: "a", label: "A", color: "#2563eb" }]}
+        hidden={new Set()}
+        xAt={(value) => value}
+        yAt={(value) => value}
+        sizeAt={(z) => z}
+        bubble={false}
+        onUnavailable={onUnavailable}
+      />,
+    );
+    expect(container.querySelector('[data-slot="scatter-webgl"]')).toBeTruthy();
+    expect(onUnavailable).toHaveBeenCalled();
+  });
+});

package/src/composites/ScatterWebGL.tsx

@@ -0,0 +1,79 @@
+import { useEffect, useRef } from "react";
+import { createScatterGL, destroyScatterGL, drawScatterGL, type ScatterGL } from "../lib/webgl-scatter";
+import type { ChartLegendItem } from "./chart-ui";
+
+type ScatterSeriesLike = {
+  data: Array<{ x: number; y: number; z?: number }>;
+};
+
+export function ScatterWebGLLayer({
+  width,
+  height,
+  series,
+  meta,
+  hidden,
+  xAt,
+  yAt,
+  sizeAt,
+  bubble,
+  onUnavailable,
+}: {
+  width: number;
+  height: number;
+  series: ScatterSeriesLike[];
+  meta: ChartLegendItem[];
+  hidden: Set<string>;
+  xAt: (value: number) => number;
+  yAt: (value: number) => number;
+  sizeAt: (z: number) => number;
+  bubble: boolean;
+  onUnavailable?: () => void;
+}) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const gpuRef = useRef<ScatterGL | null>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const gpu = createScatterGL(canvas);
+    if (!gpu) {
+      onUnavailable?.();
+      return;
+    }
+    gpuRef.current = gpu;
+    return () => {
+      destroyScatterGL(gpu);
+      gpuRef.current = null;
+    };
+  }, [onUnavailable]);
+
+  useEffect(() => {
+    const gpu = gpuRef.current;
+    const canvas = canvasRef.current;
+    if (!gpu || !canvas) return;
+    const batches = series.flatMap((item, s) => {
+      const info = meta[s]!;
+      if (hidden.has(info.id)) return [];
+      return [
+        {
+          color: info.color,
+          positions: item.data.map((point) => ({
+            x: xAt(point.x),
+            y: yAt(point.y),
+            size: bubble ? sizeAt(point.z ?? 1) * 2 : 9,
+          })),
+        },
+      ];
+    });
+    drawScatterGL(gpu, canvas, width, height, batches);
+  });
+
+  return (
+    <canvas
+      ref={canvasRef}
+      className="spk-chart-webgl"
+      data-slot="scatter-webgl"
+      aria-hidden
+    />
+  );
+}

package/src/composites/SiteFooter.test.tsx

@@ -0,0 +1,37 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { SiteFooter } from "./SiteFooter";
+
+describe("SiteFooter", () => {
+  it("renders brand, copyright, links, and meta", () => {
+    render(
+      <SiteFooter
+        brand={<span>Acme</span>}
+        copyright="© 2026"
+        links={[{ href: "#about", label: "About" }]}
+        meta={<span>Powered by Spatika</span>}
+      />,
+    );
+    expect(screen.getByText("Acme")).toBeInTheDocument();
+    expect(screen.getByText("© 2026")).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "About" })).toHaveAttribute("href", "#about");
+    expect(screen.getByText("Powered by Spatika")).toBeInTheDocument();
+  });
+
+  it("omits the nav when there are no links and uses renderLink when provided", () => {
+    const { rerender } = render(<SiteFooter brand={<span>Acme</span>} />);
+    expect(screen.queryByRole("navigation")).not.toBeInTheDocument();
+
+    rerender(
+      <SiteFooter
+        links={[{ href: "/docs", label: "Docs" }]}
+        renderLink={(link, className) => (
+          <a href={link.href} className={className} data-custom="true">
+            {link.label}
+          </a>
+        )}
+      />,
+    );
+    expect(screen.getByRole("link", { name: "Docs" })).toHaveAttribute("data-custom", "true");
+  });
+});

package/src/composites/SiteFooter.tsx

@@ -18,7 +18,7 @@ const linkClass =
 
 /**
  * Marketing-site footer: brand, copyright, links, optional meta chips.
- * Frosted surface bar with a primary hairline — matches sreelal.me.
+ * Frosted surface bar with a primary hairline.
  */
 export function SiteFooter({
   brand,

package/src/composites/SiteNav.test.tsx

@@ -0,0 +1,46 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+import { SiteNav } from "./SiteNav";
+
+describe("SiteNav", () => {
+  it("renders brand and links and opens the mobile menu", async () => {
+    const user = userEvent.setup();
+    render(
+      <SiteNav
+        brand={<a href="/">Brand</a>}
+        links={[
+          { href: "#about", label: "About" },
+          { href: "/blog", label: "Blog" },
+        ]}
+      />,
+    );
+    expect(screen.getByText("Brand")).toBeInTheDocument();
+    expect(screen.getAllByText("About").length).toBeGreaterThan(0);
+    expect(screen.getByRole("navigation").className).toContain("spk-site-nav");
+    const toggle = screen.getByRole("button", { name: "Toggle menu" });
+    expect(toggle).toHaveAttribute("aria-expanded", "false");
+    await user.click(toggle);
+    expect(toggle).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("does not pin to the viewport when contained and closes the menu on Escape", async () => {
+    const user = userEvent.setup();
+    render(
+      <SiteNav
+        contained
+        brand={<a href="/">Brand</a>}
+        links={[{ href: "#about", label: "About" }]}
+      />,
+    );
+    const nav = screen.getByRole("navigation");
+    expect(nav.className).toContain("absolute");
+    expect(nav.className).not.toMatch(/\bfixed\b/);
+
+    const toggle = screen.getByRole("button", { name: "Toggle menu" });
+    await user.click(toggle);
+    expect(toggle).toHaveAttribute("aria-expanded", "true");
+    await user.keyboard("{Escape}");
+    expect(toggle).toHaveAttribute("aria-expanded", "false");
+  });
+});

package/src/composites/SiteNav.tsx

@@ -14,6 +14,11 @@ export type SiteNavProps = {
   className?: string;
   /** Extra classes for the inner max-width row. */
   innerClassName?: string;
+  /**
+   * Pin the bar to a relatively positioned parent instead of the viewport.
+   * Use this in docs previews and embedded shells.
+   */
+  contained?: boolean;
 };
 
 const desktopLinkClass =
@@ -24,7 +29,7 @@ const mobileLinkClass =
 
 /**
  * Marketing-site navbar: fixed bar, brand, desktop links, and a 3-line mobile menu.
- * Matches the sreelal.me chrome: transparent at rest, frosted surface after scroll.
+ * Transparent at rest, frosted surface after scroll.
  */
 export function SiteNav({
   brand,
@@ -32,17 +37,19 @@ export function SiteNav({
   renderLink,
   className,
   innerClassName,
+  contained = false,
 }: SiteNavProps) {
-  const [scrolled, setScrolled] = useState(false);
+  const [scrolled, setScrolled] = useState(contained);
   const [open, setOpen] = useState(false);
   const menuId = useId();
 
   useEffect(() => {
+    if (contained) return;
     const onScroll = () => setScrolled(window.scrollY > 20);
     onScroll();
     window.addEventListener("scroll", onScroll, { passive: true });
     return () => window.removeEventListener("scroll", onScroll);
-  }, []);
+  }, [contained]);
 
   useEffect(() => {
     if (!open) return;
@@ -74,7 +81,10 @@ export function SiteNav({
       data-slot="site-nav"
       data-scrolled={scrolled ? "true" : "false"}
       className={cn(
-        "spk-site-nav fixed inset-x-0 top-0 z-50 transition-all duration-500",
+        "inset-x-0 top-0 transition-all duration-500",
+        contained
+          ? "absolute z-10"
+          : "spk-site-nav fixed z-50",
         scrolled
           ? "border-b border-border/90 bg-[color-mix(in_srgb,var(--background)_88%,transparent)] shadow-[0_8px_30px_rgba(15,13,18,0.06)] backdrop-blur-xl"
           : "bg-transparent",

package/src/composites/StatCard.test.tsx

@@ -0,0 +1,30 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { StatCard } from "./StatCard";
+
+describe("StatCard", () => {
+  it("renders label, value, and hint", () => {
+    render(<StatCard label="Users" value="144k" hint="+12 this week" />);
+    expect(screen.getByText("Users")).toBeInTheDocument();
+    expect(screen.getByText("144k")).toBeInTheDocument();
+    expect(screen.getByText("+12 this week")).toBeInTheDocument();
+  });
+
+  it("renders an optional chart under the value", () => {
+    render(<StatCard label="Users" value="144k" chart={<span>trend</span>} />);
+    expect(screen.getByText("144k")).toBeInTheDocument();
+    expect(screen.getByText("trend")).toBeInTheDocument();
+  });
+
+  it("renders value-first metric layout", () => {
+    render(<StatCard variant="metric" label="Uptime" value="99.9%" />);
+    expect(screen.getByText("99.9%")).toBeInTheDocument();
+    expect(screen.getByText("Uptime")).toBeInTheDocument();
+  });
+
+  it("omits the chart slot when none is provided", () => {
+    render(<StatCard label="Users" value="144k" />);
+    expect(screen.queryByText("trend")).not.toBeInTheDocument();
+    expect(screen.getByText("144k")).toBeInTheDocument();
+  });
+});