@spatika/react 1.0.0 → 1.2.0

package/src/composites/CareerCard.tsx

@@ -0,0 +1,111 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Badge } from "../primitives/Badge";
+import { Card } from "./Card";
+import { Tag } from "./Tag";
+
+export type CareerCardProps = {
+  role: ReactNode;
+  company: ReactNode;
+  location?: ReactNode;
+  period?: ReactNode;
+  current?: boolean;
+  bullets?: ReactNode[];
+  tags?: string[];
+  className?: string;
+};
+
+export type CareerTimelineProps = {
+  children: ReactNode;
+  className?: string;
+};
+
+/** Vertical career rail with a hairline and slot for CareerCard rows. */
+export function CareerTimeline({ children, className }: CareerTimelineProps) {
+  return (
+    <div data-slot="career-timeline" className={cn("relative", className)}>
+      <div className="absolute top-2 bottom-2 left-[5px] hidden w-px bg-border sm:block" aria-hidden />
+      <div className="space-y-3">{children}</div>
+    </div>
+  );
+}
+
+/** Resume / experience card: role, company, period pill, bullets, tech tags. */
+export function CareerCard({
+  role,
+  company,
+  location,
+  period,
+  current = false,
+  bullets = [],
+  tags = [],
+  className,
+}: CareerCardProps) {
+  return (
+    <article data-slot="career-card" className={cn("relative sm:pl-8", className)}>
+      <div
+        className={cn(
+          "absolute top-4 left-0 hidden h-2.5 w-2.5 rounded-full border-2 sm:block",
+          current ? "border-primary bg-primary" : "border-border bg-background",
+        )}
+        aria-hidden
+      />
+      <Card
+        variant="panel"
+        padding="md"
+        className={
+          current
+            ? "border-primary/25 bg-gradient-to-br from-[var(--background)] to-primary/[0.04] shadow-[0_8px_28px_color-mix(in_srgb,var(--primary)_7%,transparent)]"
+            : "hover:border-primary/20"
+        }
+      >
+        <div className="mb-2.5 flex flex-wrap items-start justify-between gap-2">
+          <div className="min-w-0">
+            <h3 className="text-[15px] font-[900] leading-snug text-foreground sm:text-[16px]">{role}</h3>
+            <p className="mt-0.5 text-[13px] font-bold text-primary">
+              {company}
+              {location ? (
+                <span className="font-semibold text-muted-foreground"> · {location}</span>
+              ) : null}
+            </p>
+          </div>
+          {period ? (
+            <Badge
+              variant={current ? "default" : "secondary"}
+              className={
+                current
+                  ? "rounded-full border-primary bg-primary px-2.5 py-1 text-[11px] font-black text-primary-foreground"
+                  : "rounded-full px-2.5 py-1 text-[11px] font-black text-muted-foreground"
+              }
+            >
+              {current ? <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-primary-foreground" /> : null}
+              {period}
+            </Badge>
+          ) : null}
+        </div>
+
+        {bullets.length > 0 ? (
+          <ul className="mb-3 space-y-1.5">
+            {bullets.map((bullet, index) => (
+              <li
+                key={index}
+                className="flex gap-2 text-[13px] leading-relaxed text-muted-foreground"
+              >
+                <span className="mt-[7px] h-1 w-1 shrink-0 rounded-full bg-primary/50" />
+                {bullet}
+              </li>
+            ))}
+          </ul>
+        ) : null}
+
+        {tags.length > 0 ? (
+          <div className="flex flex-wrap gap-1.5">
+            {tags.map((tag) => (
+              <Tag key={tag}>{tag}</Tag>
+            ))}
+          </div>
+        ) : null}
+      </Card>
+    </article>
+  );
+}

package/src/composites/ChartDataGrid.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+import { ChartDataGrid, renderChartCell } from "./ChartDataGrid";
+
+describe("ChartDataGrid", () => {
+  it("renders a linked table and highlights a selected row", async () => {
+    const user = userEvent.setup();
+    const { container } = render(
+      <ChartDataGrid
+        height={140}
+        categoryField="name"
+        valueField="views"
+        rows={[
+          { id: "web", name: "Web", views: 10, trend: [1, 2, 3] },
+          { id: "ios", name: "iOS", views: 6, trend: [2, 2, 1] },
+        ]}
+        columns={[
+          { field: "name", headerName: "Channel" },
+          { field: "views", headerName: "Views", type: "number" },
+          { field: "trend", headerName: "Trend", type: "sparkline" },
+        ]}
+      />,
+    );
+    expect(container.querySelector('[data-slot="chart-data-grid"]')).toBeTruthy();
+    expect(screen.getByText("Channel")).toBeInTheDocument();
+    const row = container.querySelector(
+      '[data-slot="chart-data-grid"] tbody [data-slot="table-row"]:nth-child(2)',
+    );
+    await user.click(row!);
+    expect(row).toHaveAttribute("data-state", "selected");
+  });
+
+  it("hides the chart when requested", () => {
+    const { container } = render(
+      <ChartDataGrid
+        hideChart
+        categoryField="name"
+        valueField="views"
+        rows={[{ id: "web", name: "Web", views: 10 }]}
+        columns={[{ field: "name", headerName: "Channel" }]}
+      />,
+    );
+    expect(container.querySelector('[data-slot="chart-container"]')).toBeNull();
+  });
+});
+
+describe("renderChartCell", () => {
+  it("returns a dash for non-numeric values", () => {
+    expect(renderChartCell("n/a")).toBe("—");
+  });
+
+  it("renders a sparkline for numeric arrays", () => {
+    const { container } = render(<>{renderChartCell([1, 4, 2], { variant: "sparkline" })}</>);
+    expect(container.querySelector('[data-slot="sparkline"]')).toBeTruthy();
+  });
+});

package/src/composites/ChartDataGrid.tsx

@@ -0,0 +1,196 @@
+import { useState, type ReactNode } from "react";
+import { chartColor, formatChartNumber } from "../lib/charts";
+import { cn } from "../lib/cn";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "../primitives/Table";
+import { ChartContainer } from "./chart-composition";
+import { SparkLineChart } from "./cartesian-charts";
+import { PieChart } from "./radial-charts";
+
+export type ChartGridColumnType = "text" | "number" | "sparkline" | "bar";
+
+export type ChartGridColumn = {
+  field: string;
+  headerName: string;
+  type?: ChartGridColumnType;
+  width?: number;
+};
+
+export type ChartDataGridRow = { id: string } & Record<string, unknown>;
+
+export type ChartDataGridProps = {
+  rows: ChartDataGridRow[];
+  columns: ChartGridColumn[];
+  chartType?: "bar" | "line" | "pie";
+  categoryField: string;
+  valueField: string;
+  height?: number;
+  className?: string;
+  selectedIds?: string[];
+  defaultSelectedIds?: string[];
+  onSelectionChange?: (ids: string[]) => void;
+  hideChart?: boolean;
+  hideLegend?: boolean;
+};
+
+export function renderChartCell(
+  value: unknown,
+  options?: {
+    variant?: "sparkline" | "bar";
+    color?: string;
+    height?: number;
+    max?: number;
+  },
+): ReactNode {
+  const color = options?.color ?? "var(--chart-1)";
+  if (Array.isArray(value) && value.every((item) => typeof item === "number")) {
+    return (
+      <SparkLineChart
+        data={value as number[]}
+        plotType={options?.variant === "bar" ? "bar" : "line"}
+        color={color}
+        height={options?.height ?? 32}
+        showHighlight={false}
+        area={options?.variant !== "bar"}
+      />
+    );
+  }
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return "—";
+  const max = options?.max && options.max > 0 ? options.max : Math.max(n, 1);
+  const pct = Math.max(0, Math.min(100, (n / max) * 100));
+  return (
+    <div className="spk-chart-cell-bar" title={formatChartNumber(n)}>
+      <span style={{ width: `${pct}%`, background: color }} />
+    </div>
+  );
+}
+
+export function ChartDataGrid({
+  rows,
+  columns,
+  chartType = "bar",
+  categoryField,
+  valueField,
+  height = 200,
+  className,
+  selectedIds,
+  defaultSelectedIds,
+  onSelectionChange,
+  hideChart,
+  hideLegend = true,
+}: ChartDataGridProps) {
+  const [internal, setInternal] = useState<string[]>(defaultSelectedIds ?? []);
+  const selected = selectedIds ?? internal;
+  const setSelected = (ids: string[]) => {
+    if (selectedIds == null) setInternal(ids);
+    onSelectionChange?.(ids);
+  };
+  const selectedIndex = selected.length ? rows.findIndex((row) => row.id === selected[0]) : -1;
+  const categories = rows.map((row) => String(row[categoryField] ?? row.id));
+  const values = rows.map((row) => Number(row[valueField] ?? 0));
+  const maxByField = new Map<string, number>();
+  for (const col of columns) {
+    if (col.type === "bar" || col.type === "number") {
+      const nums = rows.map((row) => Number(row[col.field] ?? 0)).filter((n) => Number.isFinite(n));
+      maxByField.set(col.field, nums.length ? Math.max(...nums) : 1);
+    }
+  }
+
+  const toggleRow = (id: string) => {
+    setSelected(selected[0] === id ? [] : [id]);
+  };
+
+  return (
+    <div data-slot="chart-data-grid" className={cn("spk-chart-data-grid", className)}>
+      {hideChart ? null : chartType === "pie" ? (
+        <PieChart
+          height={height}
+          hideLegend={hideLegend}
+          series={[
+            {
+              innerRadius: 36,
+              paddingAngle: 2,
+              data: rows.map((row, i) => ({
+                id: row.id,
+                value: values[i] ?? 0,
+                label: categories[i],
+                color:
+                  selected.length && !selected.includes(row.id)
+                    ? `color-mix(in srgb, ${chartColor(i)} 28%, transparent)`
+                    : undefined,
+              })),
+            },
+          ]}
+        />
+      ) : (
+        <ChartContainer
+          height={height}
+          hideLegend={hideLegend}
+          highlightScope="item"
+          selected={
+            selectedIndex >= 0 ? { seriesId: "value", dataIndex: selectedIndex } : null
+          }
+          xAxis={[{ data: categories }]}
+          series={[{ type: chartType, id: "value", label: valueField, data: values }]}
+          aria-label="Linked chart"
+        />
+      )}
+      <Table containerClassName="spk-chart-grid-table">
+        <TableHeader>
+          <TableRow>
+            {columns.map((col) => (
+              <TableHead key={col.field} style={col.width ? { width: col.width } : undefined}>
+                {col.headerName}
+              </TableHead>
+            ))}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map((row, rowIndex) => (
+            <TableRow
+              key={row.id}
+              data-state={selected.includes(row.id) ? "selected" : undefined}
+              onClick={() => toggleRow(row.id)}
+              style={{ cursor: "pointer" }}
+            >
+              {columns.map((col, colIndex) => {
+                const value = row[col.field];
+                const color = chartColor(rowIndex);
+                let content: ReactNode;
+                if (col.type === "sparkline") {
+                  content = renderChartCell(value, { variant: "sparkline", color, height: 32 });
+                } else if (col.type === "bar") {
+                  content = renderChartCell(value, {
+                    variant: "bar",
+                    color,
+                    max: maxByField.get(col.field),
+                  });
+                } else if (col.type === "number" && typeof value === "number") {
+                  content = formatChartNumber(value);
+                } else {
+                  content = value == null ? "—" : String(value);
+                }
+                return (
+                  <TableCell key={col.field} data-field={col.field}>
+                    {colIndex === 0 ? (
+                      <span className="spk-chart-grid-name">{content}</span>
+                    ) : (
+                      content
+                    )}
+                  </TableCell>
+                );
+              })}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

package/src/composites/ContactLink.tsx

@@ -0,0 +1,66 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Card } from "./Card";
+
+export type ContactLinkProps = {
+  href: string;
+  name: ReactNode;
+  label?: ReactNode;
+  icon: ReactNode;
+  iconBg?: string;
+  iconColor?: string;
+  className?: string;
+  target?: string;
+  rel?: string;
+};
+
+/** Contact / social row: tinted icon well, name, handle, trailing arrow. */
+export function ContactLink({
+  href,
+  name,
+  label,
+  icon,
+  iconBg,
+  iconColor,
+  className,
+  target,
+  rel,
+}: ContactLinkProps) {
+  const external = href.startsWith("http");
+  return (
+    <a
+      data-slot="contact-link"
+      href={href}
+      target={target ?? (external ? "_blank" : undefined)}
+      rel={rel ?? (external ? "noopener noreferrer" : undefined)}
+      className={cn("group block rounded-2xl", className)}
+    >
+      <Card
+        variant="panel"
+        padding="md"
+        className="flex items-center gap-4 p-4 group-hover:border-primary/25 group-hover:shadow-[0_8px_28px_color-mix(in_srgb,var(--chart-3)_18%,transparent)]"
+      >
+        <div
+          className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl transition-transform duration-200 group-hover:scale-110"
+          style={{ background: iconBg, color: iconColor }}
+        >
+          {icon}
+        </div>
+        <div className="min-w-0 flex-1">
+          <p className="text-[13px] font-semibold text-foreground">{name}</p>
+          {label ? <p className="truncate text-[12px] text-muted-foreground">{label}</p> : null}
+        </div>
+        <svg
+          className="h-4 w-4 shrink-0 text-muted-foreground transition-colors group-hover:text-primary"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={2}
+          aria-hidden
+        >
+          <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12h15m0 0l-6.75-6.75M19.5 12l-6.75 6.75" />
+        </svg>
+      </Card>
+    </a>
+  );
+}

package/src/composites/CoverHero.test.tsx

@@ -0,0 +1,38 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { CoverHero } from "./CoverHero";
+
+describe("CoverHero", () => {
+  it("renders title, kicker, facts, and avatars", () => {
+    render(
+      <CoverHero
+        title="Friday night"
+        kicker={<span>Meetup</span>}
+        facts={[{ key: "when", label: "When", value: "Fri 14 Mar" }]}
+        avatars={[{ name: "Alex Rivera" }, { name: "Sam Lee" }, { name: "Jo Park" }, { name: "Riley" }]}
+        bleed={false}
+      />,
+    );
+    expect(screen.getByRole("heading", { name: "Friday night" })).toBeInTheDocument();
+    expect(screen.getByText("Meetup")).toBeInTheDocument();
+    expect(screen.getByText("When")).toBeInTheDocument();
+    expect(screen.getByText("Fri 14 Mar")).toBeInTheDocument();
+    expect(screen.getByLabelText("Alex Rivera")).toBeInTheDocument();
+    expect(screen.getByText("+1")).toBeInTheDocument();
+  });
+
+  it("calls onBack from the floating control and skips bleed attributes when disabled", async () => {
+    const user = userEvent.setup();
+    const onBack = vi.fn();
+    const { container } = render(
+      <CoverHero title="Studio" onBack={onBack} backLabel="Go back" bleed={false} />,
+    );
+    expect(container.querySelector("[data-slot='cover-hero']")).not.toHaveAttribute(
+      "data-cover-bleed",
+    );
+    expect(screen.queryByRole("button", { name: "Go back" })).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Go back" }));
+    expect(onBack).toHaveBeenCalledTimes(1);
+  });
+});

package/src/composites/CoverHero.tsx

@@ -60,7 +60,7 @@ export type CoverHeroProps = {
   className?: string;
   /** Offset used when the compact bar pins under app chrome. */
   compactOffsetClassName?: string;
-  /** When false, skip writing cover-bleed attributes on `<html>` (catalog previews). */
+  /** When false, keep the cover inside this frame (docs / device previews). */
   bleed?: boolean;
 };
 
@@ -141,9 +141,14 @@ export function CoverHero({
       <header
         ref={heroRef}
         data-slot="cover-hero"
-        className={cn("relative z-10 w-full overflow-visible", className)}
+        data-cover-bleed={bleed ? "true" : undefined}
+        className={cn(
+          "relative z-10 w-full",
+          bleed ? "overflow-visible" : "overflow-hidden rounded-[1.35rem] sm:rounded-[1.75rem]",
+          className,
+        )}
       >
-        <div className={cn(mediaClass, "sm:rounded-b-[1.75rem]")} aria-hidden>
+        <div className={cn(mediaClass, bleed && "sm:rounded-b-[1.75rem]")} aria-hidden>
           {!hideImages && coverUrl ? (
             <img src={coverUrl} alt="" className="absolute inset-0 size-full object-cover" />
           ) : (
@@ -332,26 +337,28 @@ export function CoverHero({
         </div>
       </header>
 
-      <div className={cn("sticky z-[60] h-0", compactOffsetClassName)}>
-        {!heroInView ? (
-          <div className="glass-header cover-chrome-bar absolute inset-x-0 top-0 border-b border-border/50 bg-background/85 backdrop-blur-md dark:bg-background/94">
-            <div className="app-frame-pad flex items-center gap-2 py-1.5 sm:py-2">
-              {onBack ? (
-                <button
-                  type="button"
-                  onClick={onBack}
-                  aria-label={backLabel}
-                  className="flex h-8 w-8 shrink-0 items-center justify-center rounded-xl text-foreground transition-colors hover:bg-muted"
-                >
-                  <ChevronLeft className="h-4 w-4" aria-hidden />
-                </button>
-              ) : null}
-              <h2 className="page-header-title min-w-0 flex-1 truncate">{title}</h2>
-              {compactActions}
+      {bleed ? (
+        <div className={cn("sticky z-[60] h-0", compactOffsetClassName)}>
+          {!heroInView ? (
+            <div className="glass-header cover-chrome-bar absolute inset-x-0 top-0 border-b border-border/50 bg-background/85 backdrop-blur-md dark:bg-background/94">
+              <div className="app-frame-pad flex items-center gap-2 py-1.5 sm:py-2">
+                {onBack ? (
+                  <button
+                    type="button"
+                    onClick={onBack}
+                    aria-label={backLabel}
+                    className="flex h-8 w-8 shrink-0 items-center justify-center rounded-xl text-foreground transition-colors hover:bg-muted"
+                  >
+                    <ChevronLeft className="h-4 w-4" aria-hidden />
+                  </button>
+                ) : null}
+                <h2 className="page-header-title min-w-0 flex-1 truncate">{title}</h2>
+                {compactActions}
+              </div>
             </div>
-          </div>
-        ) : null}
-      </div>
+          ) : null}
+        </div>
+      ) : null}
     </>
   );
 }

package/src/composites/DisplayHeading.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type DisplayHeadingProps = {
+  children: ReactNode;
+  as?: "h1" | "h2";
+  className?: string;
+};
+
+/** Oversized marketing hero title. Compose with Wordmark / GradientText. */
+export function DisplayHeading({
+  children,
+  as: Tag = "h1",
+  className,
+}: DisplayHeadingProps) {
+  return (
+    <Tag
+      data-slot="display-heading"
+      className={cn(
+        "text-[clamp(2.5rem,8vw,5.5rem)] font-[900] leading-[0.95] tracking-tight",
+        className,
+      )}
+    >
+      {children}
+    </Tag>
+  );
+}

package/src/composites/EntityMediaCard.test.tsx

@@ -0,0 +1,58 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { EntityMediaCard } from "./EntityMediaCard";
+
+describe("EntityMediaCard", () => {
+  it("renders title, subtitle, and status on a stacked tile", () => {
+    const { container } = render(
+      <EntityMediaCard title="Alex Chen" subtitle="Product designer" statusLine="Active" />,
+    );
+    expect(screen.getByText("Alex Chen")).toBeInTheDocument();
+    expect(screen.getByText("Product designer")).toBeInTheDocument();
+    expect(screen.getByText("Active")).toBeInTheDocument();
+    expect(screen.getByText("AC")).toBeInTheDocument();
+    const card = container.querySelector("[data-slot='entity-media-card']");
+    expect(card).toHaveAttribute("data-size", "large");
+    expect(card).toHaveAttribute("data-orientation", "stack");
+    expect(container.querySelector("[data-cover-pattern]")).toBeTruthy();
+  });
+
+  it("uses a photo when imageUrl is set", () => {
+    const { container } = render(
+      <EntityMediaCard title="Jordan Lee" imageUrl="/jordan.jpg" />,
+    );
+    expect(container.querySelector("img")).toHaveAttribute("src", "/jordan.jpg");
+    expect(screen.queryByText("JL")).not.toBeInTheDocument();
+  });
+
+  it("renders as a link and calls onClick on a button card", async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    const { rerender } = render(
+      <EntityMediaCard title="Alex Chen" href="/people/alex" />,
+    );
+    expect(screen.getByRole("link", { name: /Alex Chen/ })).toHaveAttribute(
+      "href",
+      "/people/alex",
+    );
+
+    rerender(<EntityMediaCard title="Alex Chen" onClick={onClick} />);
+    await user.click(screen.getByRole("button", { name: /Alex Chen/ }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps row cards stretched so the photo matches the copy height", () => {
+    const { container } = render(
+      <EntityMediaCard
+        title="Jordan Lee"
+        subtitle="Account lead"
+        orientation="row"
+        size="small"
+      />,
+    );
+    const card = container.querySelector("[data-slot='entity-media-card']");
+    expect(card).toHaveAttribute("data-orientation", "row");
+    expect(card).toHaveClass("items-stretch");
+  });
+});