@spatika/react 1.0.0

package/src/index.ts

@@ -0,0 +1,355 @@
+/**
+ * @spatika/react — Spatika React package
+ *
+ * Import tokens separately:
+ *   import "@spatika/tokens/styles.css";
+ */
+
+export { cn } from "./lib/cn";
+export {
+  OVERLAY_Z_INDEX,
+  fixedLayerStyle,
+  createSelectEvent,
+} from "./lib/overlay-stack";
+export {
+  typographyEyebrow,
+  typographyBandEyebrow,
+  typographySectionLabel,
+  typographyPageTitle,
+  typographyPageSubtitle,
+  typographyBodyDense,
+} from "./lib/typography";
+export {
+  surfaceRadiusCard,
+  surfaceRadiusControl,
+  surfaceRadiusPill,
+  surfaceRadiusProfile,
+  surfacePrimaryClass,
+  surfaceSecondaryClass,
+  surfaceDetailClass,
+  surfaceTertiaryClass,
+} from "./lib/surfaces";
+export {
+  filterChipClass,
+  preferenceChipClass,
+  layoutToggleClass,
+  listRowToggleClass,
+  nativeSelectClass,
+} from "./lib/chips";
+export {
+  duration,
+  transition,
+  motionCardHover,
+  motionCardHoverEmphasis,
+  motionPress,
+  pageEnter,
+  cardEnter,
+} from "./lib/animations";
+export {
+  THEME_IDS,
+  THEME_LABELS,
+  DEFAULT_THEME,
+  SPATIKA_THEME_STORAGE_KEY,
+  applyTheme,
+  isDarkTheme,
+  isThemeId,
+  type ThemeId,
+} from "./lib/themes";
+export { getAvatarColor, getAvatarFallbackHue, getInitials } from "./lib/avatar-utils";
+export {
+  COVER_PATTERN_KINDS,
+  getCoverPattern,
+  getCoverPatternKind,
+  getCoverPatternStyle,
+  isCoverPatternKind,
+  type CoverHeaderInk,
+  type CoverPatternInput,
+  type CoverPatternKind,
+  type CoverScene,
+} from "./lib/cover-pattern";
+export {
+  coverFloatingIconClass,
+  coverFloatingShellClass,
+  coverMutedClass,
+  coverPlateClass,
+  coverTitleClass,
+} from "./lib/cover-chrome";
+export { useCoverChromeBleed, type CoverChromeInk } from "./lib/use-cover-chrome-bleed";
+export { useIsMobile, useMediaQuery } from "./lib/use-media-query";
+export {
+  SpatikaThemeProvider,
+  useSpatikaTheme,
+  type SpatikaThemeContextValue,
+  type SpatikaThemeProviderProps,
+} from "./theme/SpatikaThemeProvider";
+
+export { Button, buttonVariants } from "./primitives/Button";
+export { Badge, badgeVariants } from "./primitives/Badge";
+export { Input } from "./primitives/Input";
+export { Textarea } from "./primitives/Textarea";
+export { Label } from "./primitives/Label";
+export { Separator } from "./primitives/Separator";
+export { Skeleton } from "./primitives/Skeleton";
+export { Checkbox } from "./primitives/Checkbox";
+export { Switch } from "./primitives/Switch";
+export { RadioGroup, RadioGroupItem } from "./primitives/RadioGroup";
+export { Progress } from "./primitives/Progress";
+export { Slider } from "./primitives/Slider";
+export { Avatar, AvatarImage, AvatarFallback, InitialsAvatar } from "./primitives/Avatar";
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "./primitives/Select";
+export { NativeSelect } from "./primitives/NativeSelect";
+export { Spinner } from "./primitives/Spinner";
+export { Alert, AlertTitle, AlertDescription, alertVariants } from "./primitives/Alert";
+export { Kbd } from "./primitives/Kbd";
+export { Tabs, TabsList, TabsTrigger, TabsContent } from "./primitives/Tabs";
+export { Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption } from "./primitives/Table";
+export {
+  Dialog,
+  DialogTrigger,
+  DialogPortal,
+  DialogClose,
+  DialogOverlay,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+} from "./primitives/Dialog";
+export {
+  AlertDialog,
+  AlertDialogPortal,
+  AlertDialogOverlay,
+  AlertDialogTrigger,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from "./primitives/AlertDialog";
+export {
+  Sheet,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+} from "./primitives/Sheet";
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor } from "./primitives/Popover";
+export {
+  DropdownMenu,
+  DropdownMenuPortal,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+} from "./primitives/DropdownMenu";
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+} from "./primitives/Command";
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "./primitives/Tooltip";
+export {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from "./primitives/Accordion";
+export { StarRating } from "./primitives/StarRating";
+
+export { GlassCard, glassCardVariants, type GlassCardProps } from "./composites/GlassCard";
+export { SurfaceCard, surfaceCardVariants, type SurfaceCardProps } from "./composites/SurfaceCard";
+export { PageStickyHeader, PageHeaderBadge, type PageStickyHeaderProps } from "./composites/PageStickyHeader";
+export { PageShell, type PageShellProps } from "./composites/PageShell";
+export { SectionPanel, type SectionPanelProps } from "./composites/SectionPanel";
+export { Chip, chipVariants, type ChipProps } from "./composites/Chip";
+export {
+  ChipGroup,
+  isOptionSelected,
+  toggleOptionValue,
+  type ChipGroupProps,
+  type ChipOption,
+} from "./composites/ChipGroup";
+export { EmptyState, type EmptyStateProps } from "./composites/EmptyState";
+export { FormField, type FormFieldProps } from "./composites/FormField";
+export { PageHeader, type PageHeaderProps } from "./composites/PageHeader";
+export { StatCard, type StatCardProps } from "./composites/StatCard";
+export { SearchField, type SearchFieldProps } from "./composites/SearchField";
+export { Toolbar } from "./composites/Toolbar";
+export { StatusDot, statusDotVariants } from "./composites/StatusDot";
+export { ListRow } from "./composites/ListRow";
+export { Breadcrumb, type BreadcrumbItem } from "./composites/Breadcrumb";
+export { Pagination } from "./composites/Pagination";
+export { Callout } from "./composites/Callout";
+export { ActionBar } from "./composites/ActionBar";
+export { DividerLabel } from "./composites/DividerLabel";
+export {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+  type CardProps,
+} from "./composites/Card";
+export { AppHeader, type AppHeaderProps } from "./composites/AppHeader";
+export {
+  ChromeAttachedCaret,
+  FloatingPageChromeBar,
+  FloatingPageChromeIdentity,
+  FloatingPageChromeSearchField,
+  FloatingPageChromeShell,
+  FLOATING_PAGE_CHROME_HEIGHT_CLASS,
+  FLOATING_PAGE_CHROME_POPOVER_OFFSET,
+  appChromeActionClusterClass,
+  appChromeClusterButtonClass,
+  floatingPageChromeAttachedPopoverClass,
+  floatingPageChromeClusterClass,
+  floatingPageChromeIconPillClass,
+  floatingPageChromeIdentityClass,
+  floatingPageChromePillClass,
+  floatingPageChromePrimaryClass,
+  floatingPageChromeSearchInputClass,
+  floatingPageChromeSearchWrapClass,
+  floatingPageChromeShellClass,
+  floatingPageChromeTrayClass,
+  type FloatingPageChromeBarProps,
+  type FloatingPageChromeIdentityProps,
+  type FloatingPageChromeSearchFieldProps,
+} from "./composites/FloatingPageChrome";
+export { CoverPattern, ProfileCoverPattern, type CoverPatternProps } from "./composites/CoverPattern";
+export {
+  CoverHero,
+  type CoverHeroAvatar,
+  type CoverHeroFact,
+  type CoverHeroProps,
+} from "./composites/CoverHero";
+export {
+  AppSidebar,
+  type AppSidebarProps,
+  type SidebarNavItem,
+  type SidebarNavSection,
+} from "./composites/AppSidebar";
+export {
+  QuickSettings,
+  QuickSettingsGroup,
+  QuickSettingsRow,
+  type QuickSettingsProps,
+} from "./composites/QuickSettings";
+export {
+  PhotoViewer,
+  type PhotoViewerProps,
+  type PhotoViewerItem,
+} from "./composites/PhotoViewer";
+export { RichTextEditor, type RichTextEditorProps } from "./composites/RichTextEditor";
+export { HeaderIconButton, type HeaderIconButtonProps } from "./composites/HeaderIconButton";
+export {
+  QuickFilterRail,
+  type QuickFilterRailProps,
+  type QuickFilterGroup,
+  type QuickFilterItem,
+} from "./composites/QuickFilterRail";
+export {
+  BottomSheet,
+  Drawer,
+  DrawerTrigger,
+  DrawerClose,
+  DrawerPortal,
+  DrawerOverlay,
+  DrawerContent,
+  DrawerHeader,
+  DrawerFooter,
+  DrawerTitle,
+  DrawerDescription,
+  type BottomSheetProps,
+} from "./composites/BottomSheet";
+export { ViewFiltersPanel, type ViewFiltersPanelProps } from "./composites/ViewFiltersPanel";
+export { FilterSheet, type FilterSheetProps } from "./composites/FilterSheet";
+export {
+  NotificationBell,
+  type NotificationBellProps,
+  type NotificationItem,
+} from "./composites/NotificationBell";
+export {
+  CommandSearchField,
+  type CommandSearchFieldProps,
+  type CommandSearchResult,
+} from "./composites/CommandSearchField";
+export {
+  PinPad,
+  LockOverlay,
+  type PinPadProps,
+  type LockOverlayProps,
+} from "./composites/PinPad";
+export { MediaEntryCard, type MediaEntryCardProps } from "./composites/MediaEntryCard";
+export { EntityMediaCard, type EntityMediaCardProps } from "./composites/EntityMediaCard";
+export {
+  EntityCard,
+  EntityCardTitle,
+  EntityCardMeta,
+  EntityCardChip,
+  type EntityCardProps,
+  type EntityCardTitleProps,
+  type EntityCardMetaProps,
+} from "./composites/EntityCard";
+export {
+  MobileTabBar,
+  APP_TABBAR_CLEARANCE_CLASS,
+  type MobileTabBarProps,
+  type MobileTabItem,
+} from "./composites/MobileTabBar";
+export { ProfileHero, type ProfileHeroProps } from "./composites/ProfileHero";
+
+export { AmountInput, type AmountInputProps } from "./composites/AmountInput";
+export {
+  SegmentedControl,
+  type SegmentedControlProps,
+  type SegmentedControlOption,
+} from "./composites/SegmentedControl";
+export {
+  Toaster,
+  useToast,
+  type ToasterProps,
+  type ToastItem,
+  type ToastTone,
+} from "./composites/Toast";
+export {
+  Timeline,
+  TimelineItem,
+  type TimelineProps,
+  type TimelineItemProps,
+} from "./composites/Timeline";
+export {
+  DataTableToolbar,
+  type DataTableToolbarProps,
+} from "./composites/DataTableToolbar";

package/src/lib/animations.ts

@@ -0,0 +1,47 @@
+/**
+ * Animation language for Spatika.
+ *
+ * Micro  — hover/focus/active (CSS only, ≤150ms)
+ * Meso   — element entrances (200–300ms)
+ * Macro  — page transitions / overlays (300–400ms)
+ *
+ * Never use transition-all on glass / backdrop-blur surfaces.
+ */
+
+const easeOut: [number, number, number, number] = [0, 0, 0.2, 1];
+
+export const duration = {
+  instant: 0.15,
+  fast: 0.2,
+  normal: 0.3,
+  slow: 0.4,
+} as const;
+
+export const transition = {
+  fast: { duration: duration.fast, ease: easeOut },
+  normal: { duration: duration.normal, ease: easeOut },
+  slow: { duration: duration.slow, ease: easeOut },
+} as const;
+
+/** Standard card hover — transform + shadow only. */
+export const motionCardHover =
+  "transition-[transform,box-shadow,border-color] duration-200 ease-out hover:-translate-y-0.5 hover:shadow-lg hover:border-primary/20";
+
+/** Emphasized card hover for hero / ranked cards. */
+export const motionCardHoverEmphasis =
+  "transition-[transform,box-shadow,border-color] duration-200 ease-out hover:-translate-y-1 hover:shadow-xl hover:border-primary/30";
+
+/** Interactive press feedback. */
+export const motionPress = "active:scale-[0.98]";
+
+export const pageEnter = {
+  initial: { opacity: 0 },
+  animate: { opacity: 1 },
+  transition: transition.normal,
+};
+
+export const cardEnter = {
+  initial: { opacity: 0, y: 8 },
+  animate: { opacity: 1, y: 0 },
+  transition: transition.normal,
+};

package/src/lib/avatar-utils.ts

@@ -0,0 +1,52 @@
+/**
+ * Stable avatar color class derived from a name hash.
+ * Used by InitialsAvatar for consistent tinting across renders.
+ */
+export function getAvatarColor(name: string): string {
+  const colors = [
+    "bg-rose-500",
+    "bg-pink-500",
+    "bg-fuchsia-500",
+    "bg-purple-500",
+    "bg-violet-500",
+    "bg-indigo-500",
+    "bg-blue-500",
+    "bg-sky-500",
+    "bg-cyan-500",
+    "bg-teal-500",
+    "bg-emerald-500",
+    "bg-green-500",
+    "bg-orange-500",
+    "bg-amber-500",
+  ];
+
+  let hash = 0;
+  const safeName = name || "User";
+  for (let i = 0; i < safeName.length; i++) {
+    hash = safeName.charCodeAt(i) + ((hash << 5) - hash);
+  }
+
+  const index = Math.abs(hash) % colors.length;
+  return colors[index];
+}
+
+/** Stable 0–359 hue from a display name — used to tint generated covers. */
+export function getAvatarFallbackHue(name: string): number {
+  let hash = 0;
+  const safeName = name || "User";
+  for (let i = 0; i < safeName.length; i++) {
+    hash = safeName.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return Math.abs(hash) % 360;
+}
+
+/** First two initials from a display name (uppercase). */
+export function getInitials(name: string): string {
+  if (!name) return "";
+  return name
+    .split(" ")
+    .map((n) => n[0])
+    .join("")
+    .substring(0, 2)
+    .toUpperCase();
+}

package/src/lib/chips.ts

@@ -0,0 +1,58 @@
+/**
+ * Chip / toggle class recipes shared by filters and preference groups.
+ */
+import { cn } from "./cn";
+
+const filterChipBase =
+  "inline-flex min-h-7 max-w-full items-center justify-center rounded-full border px-2 py-0.5 text-left text-[10px] font-bold leading-snug shadow-sm transition-colors active:scale-[0.98] sm:min-h-8 sm:px-2.5 sm:py-1 sm:text-xs";
+
+/** Soft filter pill (directory / history filters). */
+export function filterChipClass(active: boolean, className?: string) {
+  return cn(
+    filterChipBase,
+    active
+      ? "border-primary/50 bg-primary/15 text-primary"
+      : "border-border/60 bg-background/80 text-foreground hover:bg-muted/40",
+    className,
+  );
+}
+
+/** Uppercase preference toggle chip (admin / settings). */
+export function preferenceChipClass(active: boolean, className?: string) {
+  return cn(
+    "touch-manipulation rounded-xl border px-3 py-2 text-[10px] font-black uppercase tracking-widest shadow-sm transition-all active:scale-95",
+    active
+      ? "scale-[1.02] border-primary bg-primary text-primary-foreground shadow-primary/20"
+      : "border-border/50 bg-background/40 text-muted-foreground hover:border-primary/30 hover:text-primary",
+    className,
+  );
+}
+
+/** Layout mode toggle (grid / list / kanban). */
+export function layoutToggleClass(active: boolean, className?: string) {
+  return cn(
+    "flex min-h-11 items-center justify-center gap-2 rounded-xl border px-3 text-sm font-bold shadow-sm transition-colors active:scale-[0.98]",
+    active
+      ? "border-primary/50 bg-primary/15 text-primary"
+      : "border-border/60 bg-background/80 text-foreground hover:bg-muted/40",
+    className,
+  );
+}
+
+/** Full-width selectable list row. */
+export function listRowToggleClass(active: boolean, className?: string) {
+  return cn(
+    "flex min-h-11 w-full items-center justify-between gap-3 rounded-xl border px-3 py-2.5 text-left text-sm font-semibold shadow-sm transition-colors active:scale-[0.99]",
+    active
+      ? "border-primary/50 bg-primary/15 text-primary"
+      : "border-border/60 bg-background/80 text-foreground hover:bg-muted/40",
+    className,
+  );
+}
+
+export const nativeSelectClass = cn(
+  "mt-1 w-full min-h-11 px-3 rounded-xl border border-border/60 bg-background/80 text-sm font-semibold shadow-sm",
+  "text-foreground transition-colors",
+  "focus:outline-none focus:border-primary/40 focus:ring-2 focus:ring-primary/20",
+  "disabled:cursor-not-allowed disabled:opacity-50",
+);

package/src/lib/cn.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { cn } from "./cn";
+
+describe("cn", () => {
+  it("merges class names", () => {
+    expect(cn("px-2", "py-1")).toBe("px-2 py-1");
+  });
+
+  it("resolves Tailwind conflicts via twMerge", () => {
+    expect(cn("px-2", "px-4")).toBe("px-4");
+  });
+
+  it("ignores falsy values", () => {
+    expect(cn("base", false && "hidden", undefined, null, "ok")).toBe("base ok");
+  });
+});

package/src/lib/cn.ts

@@ -0,0 +1,7 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/** Merge Tailwind class names without conflicts. */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/lib/compose-refs.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+type PossibleRef<T> = React.Ref<T> | undefined;
+
+/** Assigns a value to a React ref (callback or object ref). */
+function setRef<T>(ref: PossibleRef<T>, value: T) {
+  if (typeof ref === "function") {
+    ref(value);
+  } else if (ref != null) {
+    (ref as React.MutableRefObject<T>).current = value;
+  }
+}
+
+/** Merges multiple refs into a single callback ref. */
+export function composeRefs<T>(...refs: PossibleRef<T>[]) {
+  return (node: T) => {
+    for (const ref of refs) {
+      setRef(ref, node);
+    }
+  };
+}

package/src/lib/cover-chrome.ts

@@ -0,0 +1,31 @@
+import { cn } from "./cn";
+import type { CoverHeaderInk } from "./cover-pattern";
+
+/** Floating glass pill sitting on a generated / photo cover. */
+export function coverFloatingShellClass(_ink: CoverHeaderInk, className?: string): string {
+  return cn("cover-floating-shell", className);
+}
+
+export function coverFloatingIconClass(ink: CoverHeaderInk): string {
+  return ink === "light"
+    ? "text-white/90 hover:bg-white/20 hover:text-white"
+    : "text-zinc-800 hover:bg-zinc-950/[0.08] hover:text-zinc-950";
+}
+
+export function coverPlateClass(ink: CoverHeaderInk): string {
+  return ink === "light"
+    ? "border border-white/18 bg-black/40 backdrop-blur-[24px] backdrop-saturate-150 shadow-[0_8px_36px_rgba(0,0,0,0.45),inset_0_1px_0_rgba(255,255,255,0.18)]"
+    : "border border-white/60 bg-white/55 backdrop-blur-[20px] backdrop-saturate-150 shadow-[0_8px_32px_rgba(0,0,0,0.08),inset_0_1px_0_rgba(255,255,255,0.8)]";
+}
+
+export function coverTitleClass(ink: CoverHeaderInk): string {
+  return ink === "light"
+    ? "text-white [text-shadow:0_1px_10px_rgba(0,0,0,0.4)]"
+    : "text-zinc-950";
+}
+
+export function coverMutedClass(ink: CoverHeaderInk): string {
+  return ink === "light" ? "text-white/70" : "text-zinc-600";
+}
+
+export type { CoverHeaderInk };