@spatika/react 1.0.0

package/src/lib/use-cover-chrome-bleed.ts

@@ -0,0 +1,33 @@
+import { useLayoutEffect } from "react";
+
+/** Foreground ink the app chrome should use while it floats over a cover surface. */
+export type CoverChromeInk = "light" | "dark";
+
+/**
+ * Tells the fixed app header to go transparent so a page cover (profile hero,
+ * story hero, …) can paint through it. Cleared on unmount and whenever the
+ * cover has scrolled away.
+ */
+export function useCoverChromeBleed(active: boolean, ink: CoverChromeInk): void {
+  useLayoutEffect(() => {
+    const root = document.documentElement;
+    if (!active) {
+      root.removeAttribute("data-cover-chrome-bleed");
+      root.removeAttribute("data-cover-chrome-ink");
+      root.removeAttribute("data-profile-cover-bleed");
+      root.removeAttribute("data-profile-cover-ink");
+      return;
+    }
+
+    root.setAttribute("data-cover-chrome-bleed", "true");
+    root.setAttribute("data-cover-chrome-ink", ink);
+    root.setAttribute("data-profile-cover-bleed", "true");
+    root.setAttribute("data-profile-cover-ink", ink);
+    return () => {
+      root.removeAttribute("data-cover-chrome-bleed");
+      root.removeAttribute("data-cover-chrome-ink");
+      root.removeAttribute("data-profile-cover-bleed");
+      root.removeAttribute("data-profile-cover-ink");
+    };
+  }, [active, ink]);
+}

package/src/lib/use-dismissable.ts

@@ -0,0 +1,49 @@
+import * as React from "react";
+
+type UseDismissableOptions = {
+  enabled?: boolean;
+  onDismiss: () => void;
+  /** Refs whose nodes count as "inside" (content + trigger). */
+  refs: React.RefObject<HTMLElement | null>[];
+};
+
+/**
+ * Closes on Escape and pointer-down outside the provided refs.
+ */
+export function useDismissable({
+  enabled = true,
+  onDismiss,
+  refs,
+}: UseDismissableOptions) {
+  const onDismissRef = React.useRef(onDismiss);
+  onDismissRef.current = onDismiss;
+
+  React.useEffect(() => {
+    if (!enabled) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.stopPropagation();
+        onDismissRef.current();
+      }
+    };
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target as Node | null;
+      if (!target) return;
+
+      const isInside = refs.some((ref) => ref.current?.contains(target));
+      if (!isInside) {
+        onDismissRef.current();
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    document.addEventListener("pointerdown", handlePointerDown, true);
+
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+      document.removeEventListener("pointerdown", handlePointerDown, true);
+    };
+  }, [enabled, refs]);
+}

package/src/lib/use-floating-position.ts

@@ -0,0 +1,168 @@
+import * as React from "react";
+
+export type FloatingSide = "top" | "right" | "bottom" | "left";
+export type FloatingAlign = "start" | "center" | "end";
+
+export type FloatingPosition = {
+  top: number;
+  left: number;
+  side: FloatingSide;
+  /** Measured trigger size for consumers that match width. */
+  triggerWidth: number;
+  triggerHeight: number;
+};
+
+type UseFloatingPositionOptions = {
+  open: boolean;
+  triggerRef: React.RefObject<HTMLElement | null>;
+  contentRef: React.RefObject<HTMLElement | null>;
+  side?: FloatingSide;
+  align?: FloatingAlign;
+  sideOffset?: number;
+  collisionPadding?: number;
+};
+
+/**
+ * Positions floating content relative to a trigger using getBoundingClientRect.
+ * Returns fixed-position coordinates suitable for `position: fixed` portals.
+ */
+export function useFloatingPosition({
+  open,
+  triggerRef,
+  contentRef,
+  side = "bottom",
+  align = "center",
+  sideOffset = 4,
+  collisionPadding = 8,
+}: UseFloatingPositionOptions): FloatingPosition | null {
+  const [position, setPosition] = React.useState<FloatingPosition | null>(null);
+
+  const update = React.useCallback(() => {
+    const trigger = triggerRef.current;
+    const content = contentRef.current;
+    if (!trigger || !content) return;
+
+    const triggerRect = trigger.getBoundingClientRect();
+    // Prefer laid-out size; fall back to trigger size (min 1) so first paint /
+    // happy-dom still yields a position — avoids `visibility: hidden` menus that
+    // testing-library cannot query by role.
+    const contentWidth =
+      content.offsetWidth > 0 ? content.offsetWidth : Math.max(triggerRect.width, 1);
+    const contentHeight =
+      content.offsetHeight > 0 ? content.offsetHeight : Math.max(triggerRect.height, 1);
+
+    let resolvedSide = side;
+    const viewportW = window.innerWidth;
+    const viewportH = window.innerHeight;
+
+    // Prefer requested side; flip if clearly overflowing.
+    if (
+      side === "bottom" &&
+      triggerRect.bottom + sideOffset + contentHeight > viewportH - collisionPadding
+    ) {
+      if (triggerRect.top - sideOffset - contentHeight > collisionPadding) {
+        resolvedSide = "top";
+      }
+    } else if (
+      side === "top" &&
+      triggerRect.top - sideOffset - contentHeight < collisionPadding
+    ) {
+      if (
+        triggerRect.bottom + sideOffset + contentHeight <
+        viewportH - collisionPadding
+      ) {
+        resolvedSide = "bottom";
+      }
+    } else if (
+      side === "right" &&
+      triggerRect.right + sideOffset + contentWidth > viewportW - collisionPadding
+    ) {
+      if (triggerRect.left - sideOffset - contentWidth > collisionPadding) {
+        resolvedSide = "left";
+      }
+    } else if (
+      side === "left" &&
+      triggerRect.left - sideOffset - contentWidth < collisionPadding
+    ) {
+      if (
+        triggerRect.right + sideOffset + contentWidth <
+        viewportW - collisionPadding
+      ) {
+        resolvedSide = "right";
+      }
+    }
+
+    let top = 0;
+    let left = 0;
+
+    if (resolvedSide === "bottom") {
+      top = triggerRect.bottom + sideOffset;
+    } else if (resolvedSide === "top") {
+      top = triggerRect.top - contentHeight - sideOffset;
+    } else if (resolvedSide === "left" || resolvedSide === "right") {
+      if (align === "start") top = triggerRect.top;
+      else if (align === "end") top = triggerRect.bottom - contentHeight;
+      else top = triggerRect.top + (triggerRect.height - contentHeight) / 2;
+    }
+
+    if (resolvedSide === "right") {
+      left = triggerRect.right + sideOffset;
+    } else if (resolvedSide === "left") {
+      left = triggerRect.left - contentWidth - sideOffset;
+    } else if (align === "start") {
+      left = triggerRect.left;
+    } else if (align === "end") {
+      left = triggerRect.right - contentWidth;
+    } else {
+      left = triggerRect.left + (triggerRect.width - contentWidth) / 2;
+    }
+
+    // Keep the panel fully inside the viewport.
+    left = Math.min(
+      Math.max(collisionPadding, left),
+      Math.max(collisionPadding, viewportW - contentWidth - collisionPadding),
+    );
+    top = Math.min(
+      Math.max(collisionPadding, top),
+      Math.max(collisionPadding, viewportH - contentHeight - collisionPadding),
+    );
+
+    setPosition({
+      top,
+      left,
+      side: resolvedSide,
+      triggerWidth: triggerRect.width,
+      triggerHeight: triggerRect.height,
+    });
+  }, [align, collisionPadding, contentRef, side, sideOffset, triggerRef]);
+
+  React.useLayoutEffect(() => {
+    if (!open) {
+      setPosition(null);
+      return;
+    }
+
+    update();
+
+    // Remeasure after paint in case fonts/layout settle one frame later.
+    const raf = window.requestAnimationFrame(() => update());
+
+    const handle = () => update();
+    window.addEventListener("resize", handle);
+    window.addEventListener("scroll", handle, true);
+
+    const ro =
+      typeof ResizeObserver !== "undefined" ? new ResizeObserver(handle) : null;
+    if (contentRef.current && ro) ro.observe(contentRef.current);
+    if (triggerRef.current && ro) ro.observe(triggerRef.current);
+
+    return () => {
+      window.cancelAnimationFrame(raf);
+      window.removeEventListener("resize", handle);
+      window.removeEventListener("scroll", handle, true);
+      ro?.disconnect();
+    };
+  }, [open, update, contentRef, triggerRef]);
+
+  return position;
+}

package/src/lib/use-focus-trap.ts

@@ -0,0 +1,73 @@
+import * as React from "react";
+
+const FOCUSABLE_SELECTOR =
+  'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+
+/**
+ * Locks body scroll and restores focus to the previously focused element on cleanup.
+ * Also traps Tab within the container while enabled.
+ */
+export function useFocusTrap(
+  containerRef: React.RefObject<HTMLElement | null>,
+  enabled: boolean,
+) {
+  React.useEffect(() => {
+    if (!enabled) return;
+
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+
+    const focusFirst = () => {
+      const container = containerRef.current;
+      if (!container) return;
+      const focusable = container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+      if (focusable.length > 0) {
+        focusable[0].focus();
+      } else {
+        container.focus();
+      }
+    };
+
+    // Defer so portal content is mounted.
+    const id = window.setTimeout(focusFirst, 0);
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Tab") return;
+      const container = containerRef.current;
+      if (!container) return;
+
+      const focusable = Array.from(
+        container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+      ).filter((el) => !el.hasAttribute("disabled") && el.tabIndex !== -1);
+
+      if (focusable.length === 0) {
+        event.preventDefault();
+        return;
+      }
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      const active = document.activeElement as HTMLElement | null;
+
+      if (event.shiftKey) {
+        if (active === first || !container.contains(active)) {
+          event.preventDefault();
+          last.focus();
+        }
+      } else if (active === last || !container.contains(active)) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+
+    return () => {
+      window.clearTimeout(id);
+      document.removeEventListener("keydown", handleKeyDown);
+      document.body.style.overflow = previousOverflow;
+      previouslyFocused?.focus?.();
+    };
+  }, [containerRef, enabled]);
+}

package/src/lib/use-media-query.ts

@@ -0,0 +1,22 @@
+import { useEffect, useState } from "react";
+
+/** Subscribe to a CSS media query. Defaults to `false` until mounted. */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(false);
+
+  useEffect(() => {
+    if (typeof window.matchMedia !== "function") return;
+    const media = window.matchMedia(query);
+    const update = () => setMatches(media.matches);
+    update();
+    media.addEventListener("change", update);
+    return () => media.removeEventListener("change", update);
+  }, [query]);
+
+  return matches;
+}
+
+/** True when the viewport is below the `md` breakpoint (768px). */
+export function useIsMobile(): boolean {
+  return useMediaQuery("(max-width: 767px)");
+}

package/src/primitives/Accordion.tsx

@@ -0,0 +1,114 @@
+import * as React from "react";
+import { ChevronDown } from "lucide-react";
+import { cn } from "../lib/cn";
+
+type AccordionContextValue = {
+  open: string[];
+  toggle: (id: string) => void;
+  type: "single" | "multiple";
+};
+
+const AccordionContext = React.createContext<AccordionContextValue | null>(null);
+
+function Accordion({
+  type = "single",
+  defaultValue,
+  className,
+  children,
+}: {
+  type?: "single" | "multiple";
+  defaultValue?: string | string[];
+  className?: string;
+  children: React.ReactNode;
+}) {
+  const initial = Array.isArray(defaultValue)
+    ? defaultValue
+    : defaultValue
+      ? [defaultValue]
+      : [];
+  const [open, setOpen] = React.useState<string[]>(initial);
+  const toggle = (id: string) => {
+    setOpen((prev) => {
+      const isOpen = prev.includes(id);
+      if (type === "single") return isOpen ? [] : [id];
+      return isOpen ? prev.filter((x) => x !== id) : [...prev, id];
+    });
+  };
+  return (
+    <AccordionContext.Provider value={{ open, toggle, type }}>
+      <div data-slot="accordion" className={cn("space-y-2", className)}>
+        {children}
+      </div>
+    </AccordionContext.Provider>
+  );
+}
+
+function AccordionItem({
+  value,
+  className,
+  children,
+}: {
+  value: string;
+  className?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div
+      data-slot="accordion-item"
+      data-value={value}
+      className={cn("overflow-hidden rounded-xl border border-border/40 bg-card/40", className)}
+    >
+      {children}
+    </div>
+  );
+}
+
+function AccordionTrigger({
+  value,
+  className,
+  children,
+}: {
+  value: string;
+  className?: string;
+  children: React.ReactNode;
+}) {
+  const ctx = React.useContext(AccordionContext);
+  const isOpen = ctx?.open.includes(value);
+  return (
+    <button
+      type="button"
+      data-slot="accordion-trigger"
+      aria-expanded={isOpen}
+      className={cn(
+        "flex w-full items-center justify-between gap-2 px-4 py-3 text-left text-sm font-bold",
+        className,
+      )}
+      onClick={() => ctx?.toggle(value)}
+    >
+      {children}
+      <ChevronDown
+        className={cn("size-4 shrink-0 transition-transform", isOpen && "rotate-180")}
+      />
+    </button>
+  );
+}
+
+function AccordionContent({
+  value,
+  className,
+  children,
+}: {
+  value: string;
+  className?: string;
+  children: React.ReactNode;
+}) {
+  const ctx = React.useContext(AccordionContext);
+  if (!ctx?.open.includes(value)) return null;
+  return (
+    <div data-slot="accordion-content" className={cn("border-t border-border/30 px-4 py-3 text-sm", className)}>
+      {children}
+    </div>
+  );
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };

package/src/primitives/Alert.tsx

@@ -0,0 +1,57 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/cn";
+
+const alertVariants = cva(
+  "relative w-full rounded-[var(--radius-card)] border px-4 py-3 text-sm",
+  {
+    variants: {
+      variant: {
+        default: "border-border/50 bg-card/60 text-foreground",
+        info: "border-[color-mix(in_srgb,var(--accent-info)_35%,transparent)] bg-[var(--accent-info-bg)] text-[var(--accent-info)]",
+        warm: "border-[color-mix(in_srgb,var(--accent-warm)_35%,transparent)] bg-[var(--accent-warm-bg)] text-[var(--accent-warm)]",
+        highlight:
+          "border-[color-mix(in_srgb,var(--accent-highlight)_35%,transparent)] bg-[var(--accent-highlight-bg)] text-[var(--accent-highlight)]",
+        danger: "border-destructive/40 bg-[var(--accent-danger-bg)] text-destructive",
+      },
+    },
+    defaultVariants: { variant: "default" },
+  },
+);
+
+function Alert({
+  className,
+  variant,
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      role="alert"
+      data-slot="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<"h5">) {
+  return (
+    <h5
+      data-slot="alert-title"
+      className={cn("mb-1 font-black tracking-tight", className)}
+      {...props}
+    />
+  );
+}
+
+function AlertDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn("text-sm font-medium opacity-90", className)}
+      {...props}
+    />
+  );
+}
+
+export { Alert, AlertTitle, AlertDescription, alertVariants };