@spatika/react 1.0.0

package/src/composites/EntityMediaCard.tsx

@@ -0,0 +1,118 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type EntityMediaCardProps = {
+  title: string;
+  subtitle?: string;
+  statusLine?: string;
+  imageUrl?: string;
+  hideImage?: boolean;
+  /** Initials when no image */
+  fallbackLabel?: string;
+  tags?: ReactNode;
+  overlays?: ReactNode;
+  menu?: ReactNode;
+  meta?: ReactNode;
+  href?: string;
+  onClick?: () => void;
+  size?: "large" | "small" | "compact";
+  orientation?: "stack" | "row";
+  className?: string;
+  imageClassName?: string;
+};
+
+/**
+ * Entity card with photo (or initials fallback) — contact / directory style.
+ */
+export function EntityMediaCard({
+  title,
+  subtitle,
+  statusLine,
+  imageUrl,
+  hideImage,
+  fallbackLabel,
+  tags,
+  overlays,
+  menu,
+  meta,
+  href,
+  onClick,
+  size = "large",
+  orientation = "stack",
+  className,
+  imageClassName,
+}: EntityMediaCardProps) {
+  const Comp: "a" | "button" | "div" = href ? "a" : onClick ? "button" : "div";
+  const initials =
+    fallbackLabel ||
+    title
+      .split(/\s+/)
+      .slice(0, 2)
+      .map((w) => w[0]?.toUpperCase() ?? "")
+      .join("") ||
+    "?";
+
+  const photoAspect =
+    size === "compact" ? "aspect-square" : size === "small" ? "aspect-[4/3]" : "aspect-square";
+
+  return (
+    <Comp
+      href={href}
+      type={onClick && !href ? "button" : undefined}
+      onClick={onClick}
+      data-slot="entity-media-card"
+      className={cn(
+        "group flex overflow-hidden rounded-2xl border border-white/45 bg-card text-left shadow-[0_8px_30px_rgb(0,0,0,0.04)] transition-[transform,border-color] duration-200 dark:border-white/12",
+        "hover:-translate-y-0.5 hover:border-primary/15",
+        orientation === "row" ? "flex-row" : "flex-col",
+        className,
+      )}
+    >
+      <div
+        className={cn(
+          "relative shrink-0 overflow-hidden bg-muted",
+          orientation === "row" ? "w-[42%] min-w-[7rem]" : "w-full",
+          orientation === "stack" && photoAspect,
+          imageClassName,
+        )}
+      >
+        {!hideImage && imageUrl ? (
+          <img
+            src={imageUrl}
+            alt=""
+            className="size-full object-cover transition-transform duration-700 group-hover:scale-110"
+          />
+        ) : (
+          <div className="flex size-full items-center justify-center bg-gradient-to-br from-primary/20 via-muted to-accent-highlight/20 text-2xl font-black text-primary">
+            {initials}
+          </div>
+        )}
+        {overlays ? <div className="absolute inset-0 p-2">{overlays}</div> : null}
+      </div>
+
+      <div
+        className={cn(
+          "relative flex min-w-0 flex-1 flex-col bg-white dark:bg-card",
+          size === "compact" ? "gap-1 p-2.5" : "gap-1.5 p-3 sm:p-4",
+        )}
+      >
+        <div className="flex items-start justify-between gap-2">
+          <div className="min-w-0">
+            <h3 className="truncate font-bold tracking-tight group-hover:text-primary">{title}</h3>
+            {subtitle ? (
+              <p className="truncate text-xs font-medium text-muted-foreground">{subtitle}</p>
+            ) : null}
+            {statusLine ? (
+              <p className="mt-0.5 text-[9px] font-bold uppercase tracking-widest text-muted-foreground/80">
+                {statusLine}
+              </p>
+            ) : null}
+          </div>
+          {menu}
+        </div>
+        {meta}
+        {tags ? <div className="mt-auto flex flex-wrap gap-1 pt-1">{tags}</div> : null}
+      </div>
+    </Comp>
+  );
+}

package/src/composites/FilterSheet.tsx

@@ -0,0 +1,178 @@
+/**
+ * FilterSheet — shared filter chrome for floating page toolbars.
+ *
+ * Popover on desktop / tablet, bottom drawer on small screens.
+ * Feature pages supply trigger + body content; this shell owns layout,
+ * clear/close, and the mobile Done footer.
+ */
+import * as React from "react";
+import { X } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useIsMobile } from "../lib/use-media-query";
+import { Button } from "../primitives/Button";
+import { Popover, PopoverContent, PopoverTrigger } from "../primitives/Popover";
+import {
+  Drawer,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHeader,
+  DrawerTitle,
+} from "./BottomSheet";
+import {
+  ChromeAttachedCaret,
+  FLOATING_PAGE_CHROME_POPOVER_OFFSET,
+  floatingPageChromeAttachedPopoverClass,
+} from "./FloatingPageChrome";
+
+export type FilterSheetProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Desktop / `md+` control — typically a `Button` using `floatingPageChromePillClass`. */
+  trigger: React.ReactElement<{ onClick?: React.MouseEventHandler }>;
+  /** Optional compact control for small screens; defaults to `trigger` if omitted. */
+  mobileTrigger?: React.ReactElement<{ onClick?: React.MouseEventHandler }>;
+  title: string;
+  description?: string;
+  hasActiveFilters?: boolean;
+  onClear?: () => void;
+  clearLabel?: string;
+  doneLabel?: string;
+  children: React.ReactNode;
+  contentClassName?: string;
+  popoverClassName?: string;
+};
+
+function mergeMobileTriggerClick(
+  trigger: React.ReactElement<{ onClick?: React.MouseEventHandler }>,
+  openDrawer: () => void,
+): React.ReactElement {
+  return React.cloneElement(trigger, {
+    onClick: (e: React.MouseEvent) => {
+      trigger.props.onClick?.(e);
+      openDrawer();
+    },
+  });
+}
+
+/**
+ * Responsive filter panel used by directory, history, and similar list pages.
+ */
+export function FilterSheet({
+  open,
+  onOpenChange,
+  trigger,
+  mobileTrigger,
+  title,
+  description,
+  hasActiveFilters = false,
+  onClear,
+  clearLabel = "Clear",
+  doneLabel = "Done",
+  children,
+  contentClassName,
+  popoverClassName,
+}: FilterSheetProps) {
+  const isMobile = useIsMobile();
+  const mobileControl = mobileTrigger ?? trigger;
+
+  const clearControl =
+    hasActiveFilters && onClear ? (
+      <button
+        type="button"
+        onClick={onClear}
+        className="flex items-center gap-1 rounded-lg px-2 py-1 text-muted-foreground/80 transition-colors hover:bg-muted/50 hover:text-foreground"
+      >
+        <X className="h-3.5 w-3.5" />
+        <span className="text-[10px] font-semibold uppercase tracking-wider">
+          {clearLabel}
+        </span>
+      </button>
+    ) : null;
+
+  if (isMobile) {
+    return (
+      <>
+        {mergeMobileTriggerClick(mobileControl, () => onOpenChange(true))}
+        <Drawer open={open} onOpenChange={onOpenChange}>
+          <DrawerContent
+            className={cn(
+              "glass-panel max-h-[92vh] rounded-t-2xl border-border/60 bg-background/90 pb-0 backdrop-blur-xl sm:hidden",
+              contentClassName,
+            )}
+          >
+            <DrawerHeader className="flex flex-row items-start justify-between gap-3 space-y-0 border-b border-border/40 px-4 pb-3 pt-2 text-left">
+              <div className="min-w-0 space-y-1 pr-8">
+                <DrawerTitle className="text-base font-bold tracking-tight text-foreground">
+                  {title}
+                </DrawerTitle>
+                {description ? (
+                  <DrawerDescription className="text-xs text-muted-foreground">
+                    {description}
+                  </DrawerDescription>
+                ) : null}
+              </div>
+              <div className="flex shrink-0 items-center gap-1">{clearControl}</div>
+            </DrawerHeader>
+            <div className="max-h-[min(65vh,32rem)] overflow-y-auto px-0">
+              <div className="flex flex-col gap-3 p-3 pt-1">{children}</div>
+            </div>
+            <div className="flex justify-end gap-2 border-t border-border/40 p-4 pb-[calc(1rem+env(safe-area-inset-bottom))]">
+              <Button
+                type="button"
+                variant="outline"
+                onClick={() => onOpenChange(false)}
+                className="h-9 rounded-xl px-4 text-xs font-semibold uppercase tracking-wider"
+              >
+                {doneLabel}
+              </Button>
+            </div>
+          </DrawerContent>
+        </Drawer>
+      </>
+    );
+  }
+
+  return (
+    <Popover open={open} onOpenChange={onOpenChange}>
+      <PopoverTrigger asChild>{trigger}</PopoverTrigger>
+      <PopoverContent
+        align="end"
+        side="bottom"
+        sideOffset={FLOATING_PAGE_CHROME_POPOVER_OFFSET}
+        className={cn(
+          floatingPageChromeAttachedPopoverClass,
+          "w-[min(calc(100vw-1rem),24rem)]",
+          popoverClassName,
+          contentClassName,
+        )}
+        onOpenAutoFocus={(e) => e.preventDefault()}
+      >
+        <ChromeAttachedCaret align="end" />
+        <div className="border-b border-border/40 px-3 py-2.5 text-left">
+          <div className="flex items-start justify-between gap-2">
+            <div className="min-w-0 pr-2">
+              <p className="text-sm font-bold tracking-tight text-foreground">{title}</p>
+              {description ? (
+                <p className="text-xs text-muted-foreground">{description}</p>
+              ) : null}
+            </div>
+            <div className="flex shrink-0 items-center gap-1">
+              {clearControl}
+              <button
+                type="button"
+                onClick={() => onOpenChange(false)}
+                className="flex h-7 w-7 items-center justify-center rounded-lg text-muted-foreground/60 transition-colors hover:bg-muted/50 hover:text-foreground"
+                aria-label="Close"
+              >
+                <X className="h-4 w-4" />
+              </button>
+            </div>
+          </div>
+        </div>
+        <div className="flex max-h-[min(70vh,28rem)] flex-col gap-3 overflow-y-auto p-3">
+          {children}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/composites/FloatingPageChrome.tsx

@@ -0,0 +1,294 @@
+/**
+ * Floating page chrome — Apple liquid-glass toolbar under the app nav.
+ *
+ * Back and the page title share an identity control; search, filters, and
+ * actions sit on the same frosted tray. Pair with `app-page-chrome` (or pass
+ * `children` to `FloatingPageChromeBar`) so page content scrolls below the
+ * bar instead of under it.
+ */
+import type { ReactNode, Ref } from "react";
+import { ChevronLeft, Search, X } from "lucide-react";
+import { cn } from "../lib/cn";
+import { Input } from "../primitives/Input";
+
+/** Shared control height for the sticky chrome row. */
+export const FLOATING_PAGE_CHROME_HEIGHT_CLASS = "h-9";
+
+/**
+ * Pinned rail below the fixed app chrome. Not sticky — pair with
+ * `app-page-chrome` so page content scrolls in `.app-page-chrome-body`.
+ */
+export const floatingPageChromeShellClass =
+  "shrink-0 app-frame-pad pt-2 pb-1.5";
+
+/** Inner Apple glass capsule that holds identity, search, and actions. */
+export const floatingPageChromeTrayClass =
+  "glass-page-toolbar flex w-full min-w-0 flex-col gap-2 px-1.5 py-1 sm:px-2";
+
+/** App-bar utility island (settings + notifications) — still a standalone chip. */
+const glassChip =
+  "border border-border/50 bg-card/80 shadow-lg backdrop-blur-xl dark:border-white/10 dark:bg-zinc-900/70 dark:shadow-black/30";
+
+/** Inset control sitting on the page toolbar glass (not a second chip). */
+const pageToolbarControl =
+  "border border-white/35 bg-white/20 shadow-none backdrop-blur-sm dark:border-white/10 dark:bg-white/[0.07]";
+
+/** Combined back + page name — flat on the glass tray. */
+export const floatingPageChromeIdentityClass =
+  "flex h-9 min-w-0 shrink items-center rounded-full";
+
+/** Search field as an inset pill on the glass tray. */
+export const floatingPageChromeSearchWrapClass = cn(
+  "relative flex h-9 w-full max-w-md items-center rounded-full",
+  pageToolbarControl,
+);
+
+export const floatingPageChromeSearchInputClass =
+  "h-9 w-full rounded-full border-0 bg-transparent py-0 pl-9 pr-8 text-sm leading-none shadow-none focus-visible:ring-0";
+
+/** View & filters / sort — inset on the glass tray, same height as search. */
+export const floatingPageChromePillClass = cn(
+  "h-9 gap-1.5 rounded-full px-2.5 text-xs font-semibold hover:bg-white/40 data-[state=open]:bg-white/50 dark:hover:bg-white/10 dark:data-[state=open]:bg-white/12",
+  pageToolbarControl,
+);
+
+/** Icon-only control (mobile search, mobile sort). */
+export const floatingPageChromeIconPillClass = cn(
+  "h-9 w-9 shrink-0 rounded-full hover:bg-white/40 data-[state=open]:bg-white/50 dark:hover:bg-white/10 dark:data-[state=open]:bg-white/12",
+  pageToolbarControl,
+);
+
+/** Cluster of related icon actions (add / layout / more). */
+export const floatingPageChromeClusterClass = cn(
+  "inline-flex h-9 w-fit items-center gap-0.5 rounded-full p-0.5",
+  pageToolbarControl,
+);
+
+/** App-bar utility island (settings + notifications). */
+export const appChromeActionClusterClass = cn(
+  "inline-flex h-10 w-fit items-center gap-0.5 rounded-full p-0.5",
+  glassChip,
+);
+
+/** Primary CTA in the chrome row. */
+export const floatingPageChromePrimaryClass =
+  "h-9 gap-1.5 rounded-full px-3 text-xs font-semibold shadow-lg";
+
+/** Gap between a trigger pill and its attached menu (leaves room for the caret). */
+export const FLOATING_PAGE_CHROME_POPOVER_OFFSET = 10;
+
+export const floatingPageChromeAttachedPopoverClass =
+  "overflow-visible rounded-2xl border border-border/50 bg-card/95 p-0 shadow-[0_16px_40px_-18px_rgba(15,23,42,0.42)] backdrop-blur-xl dark:border-white/10 dark:bg-zinc-900/92";
+
+/** Inner buttons sitting inside a glass cluster (no second chip). */
+export const appChromeClusterButtonClass =
+  "relative z-[70] h-8 w-8 shrink-0 rounded-full px-0 text-muted-foreground transition-colors hover:bg-muted/70 hover:text-foreground data-[state=open]:bg-muted/80 data-[state=open]:text-foreground";
+
+/**
+ * Small pointer that visually joins a popover to its trigger.
+ * `align="end"` matches popover `align="end"` (caret sits under the right-hand control).
+ */
+export function ChromeAttachedCaret({
+  align = "end",
+}: {
+  align?: "start" | "end";
+}) {
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        "pointer-events-none absolute -top-[7px] h-3.5 w-3.5 rotate-45 border-l border-t border-border/50 bg-card/95 dark:border-white/10 dark:bg-zinc-900/92",
+        align === "end" ? "right-5" : "left-5",
+      )}
+    />
+  );
+}
+
+export type FloatingPageChromeIdentityProps = {
+  onBack?: () => void;
+  title: ReactNode;
+  count?: ReactNode;
+  /** Spoken name for the count badge, e.g. "253 people". */
+  countLabel?: string;
+  backLabel?: string;
+  className?: string;
+};
+
+export function FloatingPageChromeIdentity({
+  onBack,
+  title,
+  count,
+  countLabel,
+  backLabel = "Go back",
+  className,
+}: FloatingPageChromeIdentityProps) {
+  const backClassName =
+    "flex h-9 w-9 shrink-0 items-center justify-center rounded-full text-foreground transition-colors hover:bg-muted/70 active:scale-[0.96]";
+
+  return (
+    <div
+      data-slot="floating-page-chrome-identity"
+      className={cn(
+        floatingPageChromeIdentityClass,
+        "max-w-[min(28rem,calc(100%-6.5rem))]",
+        className,
+      )}
+    >
+      {onBack ? (
+        <button type="button" onClick={onBack} aria-label={backLabel} className={backClassName}>
+          <ChevronLeft className="h-4 w-4" aria-hidden />
+        </button>
+      ) : (
+        <span className="w-2.5 shrink-0" aria-hidden />
+      )}
+      <h1 className="min-w-0 truncate text-sm font-semibold tracking-tight text-foreground">
+        {title}
+      </h1>
+      {count != null && count !== false ? (
+        <span
+          className="page-header-count ml-1.5 mr-2.5"
+          aria-label={countLabel}
+        >
+          {count}
+        </span>
+      ) : (
+        <span className="w-2.5 shrink-0" aria-hidden />
+      )}
+    </div>
+  );
+}
+
+export type FloatingPageChromeSearchFieldProps = {
+  value: string;
+  onChange: (value: string) => void;
+  onClear?: () => void;
+  placeholder: string;
+  inputRef?: Ref<HTMLInputElement>;
+  className?: string;
+  fullWidth?: boolean;
+  type?: "search" | "text";
+  "aria-label"?: string;
+};
+
+/** Search pill used in the chrome row and the mobile reveal row. */
+export function FloatingPageChromeSearchField({
+  value,
+  onChange,
+  onClear,
+  placeholder,
+  inputRef,
+  className,
+  fullWidth = false,
+  type = "search",
+  "aria-label": ariaLabel,
+}: FloatingPageChromeSearchFieldProps) {
+  return (
+    <div
+      data-slot="floating-page-chrome-search"
+      className={cn(floatingPageChromeSearchWrapClass, fullWidth && "max-w-none", className)}
+    >
+      <Search className="pointer-events-none absolute left-3 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground/50" />
+      <Input
+        ref={inputRef}
+        type={type}
+        enterKeyHint="search"
+        placeholder={placeholder}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className={floatingPageChromeSearchInputClass}
+        autoComplete="off"
+        aria-label={ariaLabel}
+      />
+      {value ? (
+        <button
+          type="button"
+          onClick={onClear}
+          className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+          aria-label="Clear search"
+        >
+          <X className="h-3.5 w-3.5" />
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export type FloatingPageChromeBarProps = {
+  identity: ReactNode;
+  search?: ReactNode;
+  actions?: ReactNode;
+  below?: ReactNode;
+  /** Page body — scrolls independently so it cannot pass under the toolbar. */
+  children?: ReactNode;
+  className?: string;
+};
+
+/**
+ * Shared chrome row: identity, optional centered search, trailing actions.
+ * `below` is a second row (mobile search, compact TOC) and is not itself a full-bleed bar.
+ * Pass `children` to pin this bar above a nested scroller (content never slides under it).
+ */
+export function FloatingPageChromeBar({
+  identity,
+  search,
+  actions,
+  below,
+  children,
+  className,
+}: FloatingPageChromeBarProps) {
+  const bar = (
+    <div
+      data-slot="floating-page-chrome"
+      className={cn(floatingPageChromeShellClass, children == null && className)}
+    >
+      <div className={floatingPageChromeTrayClass}>
+        <div className="flex h-9 w-full min-w-0 items-center gap-2">
+          {identity}
+          {search ? (
+            <>
+              <div className="min-w-0 flex-1 md:hidden" aria-hidden />
+              <div className="hidden min-w-0 flex-1 justify-center px-0.5 sm:px-2 md:flex">
+                {search}
+              </div>
+            </>
+          ) : (
+            <div className="min-w-0 flex-1" aria-hidden />
+          )}
+          {actions ? (
+            <div className="flex h-9 shrink-0 items-center justify-end gap-1.5">{actions}</div>
+          ) : null}
+        </div>
+        {below}
+      </div>
+    </div>
+  );
+
+  if (children == null) return bar;
+
+  return (
+    <div className={cn("app-page-chrome", className)}>
+      {bar}
+      <div className="app-page-chrome-body">{children}</div>
+    </div>
+  );
+}
+
+/** Shell + glass tray for pages that compose the chrome row by hand. */
+export function FloatingPageChromeShell({
+  children,
+  below,
+  className,
+}: {
+  children: ReactNode;
+  below?: ReactNode;
+  className?: string;
+}) {
+  return (
+    <div data-slot="floating-page-chrome-shell" className={cn(floatingPageChromeShellClass, className)}>
+      <div className={floatingPageChromeTrayClass}>
+        {children}
+        {below}
+      </div>
+    </div>
+  );
+}

package/src/composites/FormField.tsx

@@ -0,0 +1,44 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Label } from "../primitives/Label";
+
+export type FormFieldProps = {
+  id: string;
+  label: string;
+  description?: string;
+  error?: string;
+  children: ReactNode;
+  className?: string;
+  required?: boolean;
+};
+
+/**
+ * Label + control + helper/error stack for consistent form density.
+ */
+export function FormField({
+  id,
+  label,
+  description,
+  error,
+  children,
+  className,
+  required,
+}: FormFieldProps) {
+  return (
+    <div data-slot="form-field" className={cn("space-y-2", className)}>
+      <Label htmlFor={id}>
+        {label}
+        {required ? <span className="text-destructive">*</span> : null}
+      </Label>
+      {children}
+      {description && !error ? (
+        <p className="text-xs font-medium text-muted-foreground">{description}</p>
+      ) : null}
+      {error ? (
+        <p className="text-xs font-semibold text-destructive" role="alert">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/src/composites/GlassCard.tsx

@@ -0,0 +1,47 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/cn";
+
+const glassCardVariants = cva("relative overflow-hidden", {
+  variants: {
+    variant: {
+      default: "glass rounded-[var(--radius-card)]",
+      panel: "glass-panel rounded-[var(--radius-card)]",
+      subtle: "glass-subtle rounded-[var(--radius-card)]",
+      header: "glass-header",
+      menu: "glass-menu rounded-[var(--radius-card)]",
+      app: "app-card",
+    },
+    padding: {
+      none: "p-0",
+      sm: "p-3 sm:p-4",
+      md: "p-4 sm:p-5",
+      lg: "p-5 sm:p-6",
+    },
+  },
+  defaultVariants: {
+    variant: "default",
+    padding: "md",
+  },
+});
+
+export type GlassCardProps = React.ComponentProps<"div"> &
+  VariantProps<typeof glassCardVariants>;
+
+/**
+ * Opinionated glass surface — prefer this over raw `.glass*` class strings.
+ */
+const GlassCard = React.forwardRef<HTMLDivElement, GlassCardProps>(
+  ({ className, variant, padding, ...props }, ref) => (
+    <div
+      ref={ref}
+      data-slot="glass-card"
+      data-variant={variant ?? "default"}
+      className={cn(glassCardVariants({ variant, padding }), className)}
+      {...props}
+    />
+  ),
+);
+GlassCard.displayName = "GlassCard";
+
+export { GlassCard, glassCardVariants };