@spatika/react 1.0.0 → 1.2.0

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/SectionHeading.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { AccentRule } from "./AccentRule";
+import { GradientText } from "./GradientText";
+
+export type SectionHeadingProps = {
+  eyebrow?: ReactNode;
+  title: ReactNode;
+  subtitle?: ReactNode;
+  align?: "left" | "center";
+  className?: string;
+  /** Hide the accent rule under the copy. */
+  showRule?: boolean;
+};
+
+/**
+ * Marketing / page-section title: optional eyebrow, heading, subtitle, and accent rule.
+ * Renders a `div` (not `<header>`) so it never competes with the site navbar.
+ */
+export function SectionHeading({
+  eyebrow,
+  title,
+  subtitle,
+  align = "left",
+  className,
+  showRule = true,
+}: SectionHeadingProps) {
+  const centered = align === "center";
+
+  return (
+    <div
+      data-slot="section-heading"
+      className={cn("mb-8 sm:mb-10", centered && "text-center", className)}
+    >
+      {eyebrow ? (
+        <p
+          className={cn(
+            "mb-2 text-[11px] font-bold uppercase tracking-[0.14em]",
+            centered && "text-center",
+          )}
+        >
+          <GradientText>{eyebrow}</GradientText>
+        </p>
+      ) : null}
+      <h2 className="text-[clamp(1.6rem,3.6vw,2.1rem)] font-[800] leading-[1.12] tracking-tight text-foreground">
+        {title}
+      </h2>
+      {subtitle ? (
+        <p
+          className={cn(
+            "mt-2 text-[14px] leading-relaxed text-muted-foreground",
+            centered ? "mx-auto max-w-xl" : "max-w-lg",
+          )}
+        >
+          {subtitle}
+        </p>
+      ) : null}
+      {showRule ? <AccentRule className={cn("mt-4", centered && "mx-auto")} /> : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,79 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import type { SiteNavLink } from "./SiteNav";
+
+export type SiteFooterProps = {
+  brand?: ReactNode;
+  copyright?: ReactNode;
+  links?: SiteNavLink[];
+  /** Render each link (e.g. Next.js `<Link>`). Defaults to `<a>`. */
+  renderLink?: (link: SiteNavLink, className: string) => ReactNode;
+  /** Trailing meta row (badges, “powered by”, etc.). */
+  meta?: ReactNode;
+  className?: string;
+};
+
+const linkClass =
+  "font-semibold text-muted-foreground transition-colors hover:text-primary";
+
+/**
+ * Marketing-site footer: brand, copyright, links, optional meta chips.
+ * Frosted surface bar with a primary hairline.
+ */
+export function SiteFooter({
+  brand,
+  copyright,
+  links = [],
+  renderLink,
+  meta,
+  className,
+}: SiteFooterProps) {
+  const renderItem = (link: SiteNavLink) => {
+    if (renderLink) return renderLink(link, linkClass);
+    return (
+      <a href={link.href} className={linkClass}>
+        {link.label}
+      </a>
+    );
+  };
+
+  return (
+    <footer
+      data-slot="site-footer"
+      className={cn(
+        "relative border-t border-border/80 bg-[color-mix(in_srgb,var(--background)_85%,transparent)] backdrop-blur-md",
+        className,
+      )}
+    >
+      <div
+        className="pointer-events-none absolute inset-x-0 top-0 h-px bg-gradient-to-r from-transparent via-primary/35 to-transparent"
+        aria-hidden
+      />
+      <div className="mx-auto max-w-6xl px-6 py-12 lg:px-8">
+        <div className="flex flex-col items-center justify-between gap-6 md:flex-row">
+          <div className="flex items-center gap-3">
+            {brand}
+            {brand && copyright ? (
+              <span className="text-border" aria-hidden>
+                |
+              </span>
+            ) : null}
+            {copyright ? (
+              <span className="text-[13px] text-muted-foreground">{copyright}</span>
+            ) : null}
+          </div>
+
+          {links.length > 0 ? (
+            <nav className="flex flex-wrap items-center justify-center gap-x-5 gap-y-2 text-[12px] text-muted-foreground">
+              {links.map((link) => (
+                <span key={`${link.href}-${link.label}`}>{renderItem(link)}</span>
+              ))}
+            </nav>
+          ) : null}
+
+          {meta}
+        </div>
+      </div>
+    </footer>
+  );
+}

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

@@ -0,0 +1,150 @@
+import { useEffect, useId, useState, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type SiteNavLink = {
+  href: string;
+  label: string;
+};
+
+export type SiteNavProps = {
+  brand: ReactNode;
+  links: SiteNavLink[];
+  /** Render each link (e.g. Next.js `<Link>`). Defaults to `<a>`. */
+  renderLink?: (link: SiteNavLink, className: string) => ReactNode;
+  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 =
+  "relative rounded-full px-3.5 py-2 text-[13px] font-bold text-muted-foreground transition-colors hover:bg-primary/5 hover:text-foreground";
+
+const mobileLinkClass =
+  "flex items-center rounded-2xl px-4 py-4 text-xl font-bold text-muted-foreground transition-colors hover:bg-primary/5 hover:text-primary";
+
+/**
+ * Marketing-site navbar: fixed bar, brand, desktop links, and a 3-line mobile menu.
+ * Transparent at rest, frosted surface after scroll.
+ */
+export function SiteNav({
+  brand,
+  links,
+  renderLink,
+  className,
+  innerClassName,
+  contained = false,
+}: SiteNavProps) {
+  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;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setOpen(false);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open]);
+
+  const renderItem = (link: SiteNavLink, itemClass: string) => {
+    const close = () => setOpen(false);
+    if (renderLink) {
+      return (
+        <span className="contents" onClick={close}>
+          {renderLink(link, itemClass)}
+        </span>
+      );
+    }
+    return (
+      <a href={link.href} className={itemClass} onClick={close}>
+        {link.label}
+      </a>
+    );
+  };
+
+  return (
+    <nav
+      data-slot="site-nav"
+      data-scrolled={scrolled ? "true" : "false"}
+      className={cn(
+        "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",
+        className,
+      )}
+    >
+      <div className={cn("mx-auto max-w-6xl px-4 sm:px-6 lg:px-8", innerClassName)}>
+        <div className="flex h-14 items-center justify-between sm:h-16">
+          <div className="flex min-w-0 items-center">{brand}</div>
+
+          <div className="hidden items-center gap-0.5 md:flex">
+            {links.map((link) => (
+              <span key={`${link.href}-${link.label}`}>{renderItem(link, desktopLinkClass)}</span>
+            ))}
+          </div>
+
+          <button
+            type="button"
+            className="spk-touch-target -mr-2 p-2 md:hidden"
+            aria-label="Toggle menu"
+            aria-expanded={open}
+            aria-controls={menuId}
+            onClick={() => setOpen((value) => !value)}
+          >
+            <span className="flex h-4 w-6 flex-col justify-between" aria-hidden>
+              <span
+                className={cn(
+                  "block h-[2px] w-6 rounded-full bg-foreground transition-transform duration-200",
+                  open && "translate-y-[7px] rotate-45",
+                )}
+              />
+              <span
+                className={cn(
+                  "block h-[2px] w-6 rounded-full bg-foreground transition-opacity duration-200",
+                  open && "opacity-0",
+                )}
+              />
+              <span
+                className={cn(
+                  "block h-[2px] w-6 rounded-full bg-foreground transition-transform duration-200",
+                  open && "-translate-y-[7px] -rotate-45",
+                )}
+              />
+            </span>
+          </button>
+        </div>
+      </div>
+
+      {open ? (
+        <div
+          id={menuId}
+          className="border-b border-border bg-[color-mix(in_srgb,var(--background)_95%,transparent)] shadow-2xl backdrop-blur-2xl md:hidden"
+        >
+          <div className="flex flex-col gap-2 px-6 py-8">
+            {links.map((link) => (
+              <div key={`${link.href}-${link.label}`}>{renderItem(link, mobileLinkClass)}</div>
+            ))}
+          </div>
+        </div>
+      ) : null}
+    </nav>
+  );
+}

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();
+  });
+});

package/src/composites/StatCard.tsx

@@ -6,11 +6,45 @@ export type StatCardProps = {
   value: string | number;
   hint?: string;
   icon?: ReactNode;
+  chart?: ReactNode;
   className?: string;
+  /**
+   * `app` — elevated app-card tile (label then value).
+   * `metric` — centered value-first tile for marketing stats.
+   */
+  variant?: "app" | "metric";
 };
 
 /** Compact metric tile using elevated app-card surface. */
-export function StatCard({ label, value, hint, icon, className }: StatCardProps) {
+export function StatCard({
+  label,
+  value,
+  hint,
+  icon,
+  chart,
+  className,
+  variant = "app",
+}: StatCardProps) {
+  if (variant === "metric") {
+    return (
+      <div
+        data-slot="stat-card"
+        data-variant="metric"
+        className={cn(
+          "flex flex-col items-center justify-center gap-1 rounded-[1.35rem] border border-border/80 bg-background/90 px-2 py-6 text-center shadow-[0_4px_24px_rgba(15,13,18,0.04)] backdrop-blur-sm",
+          className,
+        )}
+      >
+        <p className="text-xl font-black text-primary sm:text-2xl">{value}</p>
+        <p className="text-[10px] font-bold leading-none text-muted-foreground sm:text-[11px]">
+          {label}
+        </p>
+        {hint ? <p className="text-[10px] text-muted-foreground">{hint}</p> : null}
+        {chart ? <div className="mt-3 w-full min-w-0">{chart}</div> : null}
+      </div>
+    );
+  }
+
   return (
     <div data-slot="stat-card" className={cn("app-stat-card p-4 sm:p-5", className)}>
       <div className="flex items-start justify-between gap-3">
@@ -21,6 +55,7 @@ export function StatCard({ label, value, hint, icon, className }: StatCardProps)
       </div>
       <p className="mt-2 text-2xl font-black tracking-tight text-foreground">{value}</p>
       {hint ? <p className="mt-1 text-xs font-medium text-muted-foreground">{hint}</p> : null}
+      {chart ? <div className="mt-3 min-w-0">{chart}</div> : null}
     </div>
   );
 }

package/src/composites/Tag.tsx

@@ -0,0 +1,50 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/cn";
+
+const tagVariants = cva(
+  "inline-flex items-center gap-1.5 whitespace-nowrap border font-bold",
+  {
+    variants: {
+      variant: {
+        default:
+          "border-border/80 bg-[color-mix(in_srgb,var(--foreground)_4.5%,var(--background))] text-foreground",
+        primary: "border-primary/15 bg-primary/10 text-primary",
+        outline: "border-border/80 bg-transparent text-foreground",
+        muted: "border-transparent bg-secondary text-secondary-foreground",
+        red: "border-red-100 bg-red-50 text-red-700",
+        green: "border-green-200 bg-green-50 text-green-700",
+        orange: "border-orange-200 bg-orange-50 text-orange-700",
+        blue: "border-blue-200 bg-blue-50 text-blue-700",
+        purple: "border-purple-200 bg-purple-50 text-purple-700",
+        cyan: "border-cyan-200 bg-cyan-50 text-cyan-700",
+      },
+      size: {
+        sm: "rounded-md px-2 py-0.5 text-[11px]",
+        md: "rounded-lg px-2.5 py-1 text-[12px]",
+        lg: "rounded-xl px-3 py-1.5 text-[13px]",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "sm",
+    },
+  },
+);
+
+export type TagProps = React.ComponentProps<"span"> & VariantProps<typeof tagVariants>;
+
+/** Static label pill for skills, tech stacks, and metadata. */
+const Tag = React.forwardRef<HTMLSpanElement, TagProps>(
+  ({ className, variant, size, ...props }, ref) => (
+    <span
+      ref={ref}
+      data-slot="tag"
+      className={cn(tagVariants({ variant, size }), className)}
+      {...props}
+    />
+  ),
+);
+Tag.displayName = "Tag";
+
+export { Tag, tagVariants };

package/src/composites/Wordmark.test.tsx

@@ -0,0 +1,23 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Wordmark } from "./Wordmark";
+
+describe("Wordmark", () => {
+  it("renders a gradient accent after the name", () => {
+    render(<Wordmark name="Acme" accent=".io" />);
+    expect(screen.getByText("Acme")).toBeInTheDocument();
+    expect(screen.getByText(".io")).toBeInTheDocument();
+  });
+
+  it("renders as a heading with a mark and rest, and omits unused slots", () => {
+    const { rerender } = render(
+      <Wordmark name="Acme" mark="." rest="io" as="h1" />,
+    );
+    expect(screen.getByRole("heading", { name: /Acme/ })).toBeInTheDocument();
+    expect(screen.getByText(".")).toBeInTheDocument();
+    expect(screen.getByText("io")).toBeInTheDocument();
+
+    rerender(<Wordmark name="Acme" />);
+    expect(screen.queryByText(".io")).not.toBeInTheDocument();
+  });
+});

package/src/composites/Wordmark.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { GradientText } from "./GradientText";
+
+export type WordmarkProps = {
+  /** Primary name, rendered in foreground. */
+  name: ReactNode;
+  /** Trailing bit (`.io`, last name) in the marketing gradient. */
+  accent?: ReactNode;
+  /** Extra punctuation in primary (the period in `Name.`). */
+  mark?: ReactNode;
+  /** Unstyled trailing copy after the mark (`io` in `Acme.io`). */
+  rest?: ReactNode;
+  size?: "sm" | "md" | "lg" | "display";
+  as?: "span" | "h1";
+  className?: string;
+};
+
+const sizeClass = {
+  sm: "text-[14px] font-semibold tracking-tight",
+  md: "text-xl font-[900] tracking-tight",
+  lg: "text-[clamp(1.6rem,3.6vw,2.1rem)] font-[800] tracking-tight",
+  display: "text-[clamp(2.5rem,8vw,5.5rem)] font-[900] leading-[0.95] tracking-tight",
+} as const;
+
+/**
+ * Marketing wordmark: solid name, optional gradient accent, optional primary mark.
+ */
+export function Wordmark({
+  name,
+  accent,
+  mark,
+  rest,
+  size = "md",
+  as: Tag = "span",
+  className,
+}: WordmarkProps) {
+  return (
+    <Tag data-slot="wordmark" className={cn(sizeClass[size], className)}>
+      <span className="text-foreground">{name}</span>
+      {accent ? <GradientText>{accent}</GradientText> : null}
+      {mark ? <span className="text-primary">{mark}</span> : null}
+      {rest ? <span className="text-foreground">{rest}</span> : null}
+    </Tag>
+  );
+}