@spatika/react 1.0.0

package/src/composites/Pagination.tsx

@@ -0,0 +1,41 @@
+import { cn } from "../lib/cn";
+import { Button } from "../primitives/Button";
+
+export function Pagination({
+  page,
+  pageCount,
+  onPageChange,
+  className,
+}: {
+  page: number;
+  pageCount: number;
+  onPageChange: (page: number) => void;
+  className?: string;
+}) {
+  return (
+    <div
+      data-slot="pagination"
+      className={cn("flex items-center justify-center gap-2", className)}
+    >
+      <Button
+        variant="outline"
+        size="sm"
+        disabled={page <= 1}
+        onClick={() => onPageChange(page - 1)}
+      >
+        Prev
+      </Button>
+      <span className="min-w-16 text-center text-xs font-bold text-muted-foreground">
+        {page} / {pageCount}
+      </span>
+      <Button
+        variant="outline"
+        size="sm"
+        disabled={page >= pageCount}
+        onClick={() => onPageChange(page + 1)}
+      >
+        Next
+      </Button>
+    </div>
+  );
+}

package/src/composites/PhotoViewer.tsx

@@ -0,0 +1,142 @@
+import { useCallback, useEffect, useState } from "react";
+import { ChevronLeft, ChevronRight, X, ZoomIn, ZoomOut } from "lucide-react";
+import { cn } from "../lib/cn";
+import { Button } from "../primitives/Button";
+
+export type PhotoViewerItem = {
+  src: string;
+  alt?: string;
+  caption?: string;
+};
+
+export type PhotoViewerProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  items: PhotoViewerItem[];
+  index?: number;
+  onIndexChange?: (index: number) => void;
+  className?: string;
+};
+
+/**
+ * Full-screen photo viewer / lightbox with zoom and prev/next.
+ */
+export function PhotoViewer({
+  open,
+  onOpenChange,
+  items,
+  index: controlledIndex,
+  onIndexChange,
+  className,
+}: PhotoViewerProps) {
+  const [internalIndex, setInternalIndex] = useState(0);
+  const [zoom, setZoom] = useState(1);
+  const index = controlledIndex ?? internalIndex;
+
+  const setIndex = useCallback(
+    (next: number) => {
+      const clamped = Math.max(0, Math.min(items.length - 1, next));
+      setInternalIndex(clamped);
+      onIndexChange?.(clamped);
+      setZoom(1);
+    },
+    [items.length, onIndexChange],
+  );
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onOpenChange(false);
+      if (e.key === "ArrowLeft") setIndex(index - 1);
+      if (e.key === "ArrowRight") setIndex(index + 1);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, index, onOpenChange, setIndex]);
+
+  if (!open || items.length === 0) return null;
+  const item = items[index];
+
+  return (
+    <div
+      data-slot="photo-viewer"
+      role="dialog"
+      aria-modal="true"
+      aria-label={item?.alt || "Photo viewer"}
+      className={cn("fixed inset-0 z-[60] flex flex-col bg-black/90", className)}
+    >
+      <div className="flex items-center justify-between gap-2 px-3 py-2 text-white">
+        <p className="truncate text-sm font-bold">
+          {index + 1} / {items.length}
+          {item?.caption ? ` · ${item.caption}` : ""}
+        </p>
+        <div className="flex items-center gap-1">
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="text-white hover:bg-white/10"
+            onClick={() => setZoom((z) => Math.max(1, z - 0.25))}
+            aria-label="Zoom out"
+          >
+            <ZoomOut className="size-4" />
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="text-white hover:bg-white/10"
+            onClick={() => setZoom((z) => Math.min(3, z + 0.25))}
+            aria-label="Zoom in"
+          >
+            <ZoomIn className="size-4" />
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="text-white hover:bg-white/10"
+            onClick={() => onOpenChange(false)}
+            aria-label="Close"
+          >
+            <X className="size-4" />
+          </Button>
+        </div>
+      </div>
+
+      <div className="relative flex flex-1 items-center justify-center overflow-hidden px-12">
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          className="absolute left-2 text-white hover:bg-white/10"
+          disabled={index <= 0}
+          onClick={() => setIndex(index - 1)}
+          aria-label="Previous"
+        >
+          <ChevronLeft className="size-6" />
+        </Button>
+        {item ? (
+          <img
+            src={item.src}
+            alt={item.alt || ""}
+            className="max-h-full max-w-full object-contain transition-transform duration-200"
+            style={{ transform: `scale(${zoom})` }}
+            draggable={false}
+          />
+        ) : null}
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          className="absolute right-2 text-white hover:bg-white/10"
+          disabled={index >= items.length - 1}
+          onClick={() => setIndex(index + 1)}
+          aria-label="Next"
+        >
+          <ChevronRight className="size-6" />
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/composites/PinPad.tsx

@@ -0,0 +1,163 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { Delete, X } from "lucide-react";
+import { cn } from "../lib/cn";
+
+export type PinPadProps = {
+  onComplete: (pin: string) => void;
+  title?: string;
+  error?: string;
+  loading?: boolean;
+  length?: number;
+  className?: string;
+};
+
+/**
+ * Numeric PIN pad with dot indicators. Length, copy, and styles are customizable.
+ */
+export function PinPad({
+  onComplete,
+  title = "Enter PIN",
+  error,
+  loading,
+  length = 6,
+  className,
+}: PinPadProps) {
+  const [pin, setPin] = useState<string[]>([]);
+
+  const handleNumber = (n: string) => {
+    if (loading || pin.length >= length) return;
+    const next = [...pin, n];
+    setPin(next);
+    if (next.length === length) onComplete(next.join(""));
+  };
+
+  useEffect(() => {
+    if (error) {
+      const t = setTimeout(() => setPin([]), 400);
+      return () => clearTimeout(t);
+    }
+  }, [error]);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (loading) return;
+      if (e.key >= "0" && e.key <= "9") handleNumber(e.key);
+      if (e.key === "Backspace") setPin((p) => p.slice(0, -1));
+      if (e.key === "Escape") setPin([]);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  });
+
+  const keys = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "clear", "0", "del"];
+
+  return (
+    <div
+      data-slot="pin-pad"
+      className={cn("flex w-full max-w-xs flex-col items-center gap-8", className)}
+    >
+      <div className="space-y-2 text-center">
+        <h2 className="text-2xl font-black uppercase tracking-tighter text-foreground">{title}</h2>
+        {error ? <p className="text-sm font-bold text-destructive">{error}</p> : null}
+      </div>
+      <div className="flex gap-3">
+        {Array.from({ length }, (_, i) => (
+          <span
+            key={i}
+            className={cn(
+              "size-4 rounded-full border-2 transition-all",
+              i < pin.length
+                ? "border-primary bg-primary shadow-[0_0_15px_color-mix(in_srgb,var(--primary)_50%,transparent)]"
+                : "border-border/60 bg-transparent",
+            )}
+          />
+        ))}
+      </div>
+      <div className="grid grid-cols-3 gap-4">
+        {keys.map((key) => {
+          if (key === "clear") {
+            return (
+              <button
+                key={key}
+                type="button"
+                disabled={loading}
+                aria-label="Clear"
+                className="flex size-16 items-center justify-center rounded-full text-destructive active:scale-95"
+                onClick={() => setPin([])}
+              >
+                <X className="size-6" />
+              </button>
+            );
+          }
+          if (key === "del") {
+            return (
+              <button
+                key={key}
+                type="button"
+                disabled={loading}
+                aria-label="Delete"
+                className="flex size-16 items-center justify-center rounded-full text-muted-foreground active:scale-95"
+                onClick={() => setPin((p) => p.slice(0, -1))}
+              >
+                <Delete className="size-6" />
+              </button>
+            );
+          }
+          return (
+            <button
+              key={key}
+              type="button"
+              disabled={loading}
+              className="flex size-16 items-center justify-center rounded-full text-2xl font-black text-foreground transition-colors hover:bg-muted/40 active:scale-95 active:bg-primary/20"
+              onClick={() => handleNumber(key)}
+            >
+              {key}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+export type LockOverlayProps = {
+  open: boolean;
+  title?: string;
+  error?: string;
+  loading?: boolean;
+  onComplete: (pin: string) => void;
+  branding?: ReactNode;
+  secondaryAction?: ReactNode;
+  className?: string;
+  length?: number;
+};
+
+/**
+ * Full-screen lock overlay wrapping PinPad.
+ */
+export function LockOverlay({
+  open,
+  title = "Unlock",
+  error,
+  loading,
+  onComplete,
+  branding,
+  secondaryAction,
+  className,
+  length,
+}: LockOverlayProps) {
+  if (!open) return null;
+  return (
+    <div
+      data-slot="lock-overlay"
+      className={cn(
+        "fixed inset-0 z-[200] flex flex-col items-center justify-center gap-8 bg-background/80 px-6 backdrop-blur-xl",
+        className,
+      )}
+    >
+      {branding}
+      <PinPad title={title} error={error} loading={loading} onComplete={onComplete} length={length} />
+      {secondaryAction}
+    </div>
+  );
+}

package/src/composites/ProfileHero.tsx

@@ -0,0 +1,163 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { getInitials } from "../lib/avatar-utils";
+import {
+  coverMutedClass,
+  coverPlateClass,
+  coverTitleClass,
+} from "../lib/cover-chrome";
+import { getCoverPattern, type CoverPatternKind } from "../lib/cover-pattern";
+import { CoverPattern } from "./CoverPattern";
+
+export type ProfileHeroProps = {
+  name: string;
+  alias?: string;
+  coverUrl?: string;
+  avatarUrl?: string;
+  hideImages?: boolean;
+  statusBadges?: ReactNode;
+  metaLines?: ReactNode;
+  stats?: ReactNode;
+  tags?: ReactNode;
+  topLeading?: ReactNode;
+  topActions?: ReactNode;
+  avatarAccessory?: ReactNode;
+  onAvatarClick?: () => void;
+  className?: string;
+  coverClassName?: string;
+  identityClassName?: string;
+  children?: ReactNode;
+  /** Seed for the generated cover when no photo is set. */
+  coverSeed?: string;
+  coverHue?: number;
+  coverKind?: CoverPatternKind | null;
+  dark?: boolean;
+  warm?: 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).
+ */
+export function ProfileHero({
+  name,
+  alias,
+  coverUrl,
+  avatarUrl,
+  hideImages,
+  statusBadges,
+  metaLines,
+  stats,
+  tags,
+  topLeading,
+  topActions,
+  avatarAccessory,
+  onAvatarClick,
+  className,
+  coverClassName,
+  identityClassName,
+  children,
+  coverSeed,
+  coverHue = 210,
+  coverKind,
+  dark,
+  warm,
+}: ProfileHeroProps) {
+  const initials = getInitials(name);
+  const seed = coverSeed ?? name;
+  const scene = getCoverPattern({ seed, hue: coverHue, dark, warm, kind: coverKind });
+  const ink = scene.headerInk;
+
+  return (
+    <div data-slot="profile-hero" className={cn("relative overflow-visible", className)}>
+      <div
+        className={cn(
+          "relative min-h-[9rem] overflow-hidden sm:min-h-[12rem] lg:min-h-[13rem]",
+          coverClassName,
+        )}
+      >
+        <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} />
+          )}
+          <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>
+      </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)",
+                }}
+              >
+                {!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>
+          </div>
+          {children ? <div className="relative z-10 px-3 pb-3 sm:px-6">{children}</div> : null}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/composites/QuickFilterRail.tsx

@@ -0,0 +1,92 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Chip } from "./Chip";
+
+export type QuickFilterItem = {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  count?: number;
+};
+
+export type QuickFilterGroup = {
+  id?: string;
+  label?: string;
+  items: QuickFilterItem[];
+};
+
+export type QuickFilterRailProps = {
+  groups: QuickFilterGroup[];
+  value?: string | string[];
+  onChange?: (id: string) => void;
+  /** solid = filled primary when active (directory style); soft = tinted (default chip) */
+  activeStyle?: "solid" | "soft";
+  className?: string;
+};
+
+/**
+ * Horizontal scroll filter rail with optional grouped sections.
+ */
+export function QuickFilterRail({
+  groups,
+  value,
+  onChange,
+  activeStyle = "soft",
+  className,
+}: QuickFilterRailProps) {
+  const selected = Array.isArray(value) ? value : value ? [value] : [];
+
+  return (
+    <div
+      data-slot="quick-filter-rail"
+      className={cn(
+        "flex gap-2 overflow-x-auto pb-1 [-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden",
+        className,
+      )}
+    >
+      {groups.map((group, gi) => (
+        <div key={group.id ?? group.label ?? gi} className="flex shrink-0 items-center gap-2">
+          {gi > 0 ? <div className="h-6 w-px shrink-0 bg-border/50" /> : null}
+          {group.label ? (
+            <span className="shrink-0 text-[10px] font-black uppercase tracking-widest text-muted-foreground/70">
+              {group.label}
+            </span>
+          ) : null}
+          {group.items.map((item) => {
+            const active = selected.includes(item.id);
+            return (
+              <Chip
+                key={item.id}
+                variant="filter"
+                active={activeStyle === "soft" ? active : false}
+                onClick={() => onChange?.(item.id)}
+                className={cn(
+                  "shrink-0 gap-1.5",
+                  activeStyle === "solid" &&
+                    (active
+                      ? "border-primary/60 bg-primary text-primary-foreground hover:bg-primary"
+                      : "border-border/40 bg-card/40"),
+                )}
+              >
+                {item.icon}
+                {item.label}
+                {typeof item.count === "number" ? (
+                  <span
+                    className={cn(
+                      "ml-0.5 inline-flex h-4 min-w-4 items-center justify-center rounded-full px-1 text-[9px] font-black",
+                      active && activeStyle === "solid"
+                        ? "bg-primary-foreground/20 text-primary-foreground"
+                        : "bg-primary/15 text-primary",
+                    )}
+                  >
+                    {item.count}
+                  </span>
+                ) : null}
+              </Chip>
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}