@spatika/react 1.1.0 → 1.2.0

package/src/primitives/ClickAwayListener.tsx

@@ -0,0 +1,46 @@
+import * as React from "react";
+import { composeRefs } from "../lib/compose-refs";
+
+export type ClickAwayListenerProps = {
+  onClickAway: (event: MouseEvent | TouchEvent) => void;
+  children: React.ReactElement;
+  mouseEvent?: "mousedown" | "mouseup" | "click" | false;
+  touchEvent?: "touchstart" | "touchend" | false;
+};
+
+/**
+ * Invokes `onClickAway` when a pointer event occurs outside the child.
+ */
+function ClickAwayListener({
+  onClickAway,
+  children,
+  mouseEvent = "mousedown",
+  touchEvent = "touchstart",
+}: ClickAwayListenerProps) {
+  const ref = React.useRef<HTMLElement | null>(null);
+
+  React.useEffect(() => {
+    const handler = (event: MouseEvent | TouchEvent) => {
+      const node = ref.current;
+      const target = event.target as Node | null;
+      if (!node || !target || node.contains(target)) return;
+      onClickAway(event);
+    };
+
+    if (mouseEvent) document.addEventListener(mouseEvent, handler);
+    if (touchEvent) document.addEventListener(touchEvent, handler);
+    return () => {
+      if (mouseEvent) document.removeEventListener(mouseEvent, handler);
+      if (touchEvent) document.removeEventListener(touchEvent, handler);
+    };
+  }, [onClickAway, mouseEvent, touchEvent]);
+
+  const childRef = (children as { ref?: React.Ref<HTMLElement> }).ref;
+
+  return React.cloneElement(children, {
+    ref: composeRefs(ref, childRef),
+  } as Partial<unknown>);
+}
+ClickAwayListener.displayName = "ClickAwayListener";
+
+export { ClickAwayListener };

package/src/primitives/Collapse.tsx

@@ -0,0 +1,39 @@
+import * as React from "react";
+import { cn } from "../lib/cn";
+
+export type CollapseProps = Omit<React.ComponentPropsWithoutRef<"div">, "in"> & {
+  /** When true, the child is expanded. */
+  in?: boolean;
+  /** Keep children mounted while collapsed. Defaults to true so height can animate. */
+  unmountOnExit?: boolean;
+};
+
+/**
+ * Height collapse used by Accordion and other expandable regions.
+ * Animates `grid-template-rows` (transform-safe; no `transition-all`).
+ */
+const Collapse = React.forwardRef<HTMLDivElement, CollapseProps>(
+  ({ in: open = false, unmountOnExit = false, className, children, ...props }, ref) => {
+    if (unmountOnExit && !open) return null;
+
+    return (
+      <div
+        ref={ref}
+        data-slot="collapse"
+        data-state={open ? "open" : "closed"}
+        aria-hidden={!open}
+        className={cn(
+          "grid transition-[grid-template-rows] duration-300 ease-out",
+          open ? "grid-rows-[1fr]" : "grid-rows-[0fr]",
+          className,
+        )}
+        {...props}
+      >
+        <div className="min-h-0 overflow-hidden">{children}</div>
+      </div>
+    );
+  },
+);
+Collapse.displayName = "Collapse";
+
+export { Collapse };

package/src/primitives/Container.tsx

@@ -0,0 +1,40 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/cn";
+
+const containerVariants = cva("mx-auto w-full", {
+  variants: {
+    maxWidth: {
+      sm: "max-w-screen-sm",
+      md: "max-w-screen-md",
+      lg: "max-w-screen-lg",
+      xl: "max-w-screen-xl",
+      full: "max-w-none",
+    },
+    disableGutters: {
+      true: "px-0",
+      false: "px-4 sm:px-6",
+    },
+  },
+  defaultVariants: {
+    maxWidth: "lg",
+    disableGutters: false,
+  },
+});
+
+export type ContainerProps = React.ComponentPropsWithoutRef<"div"> &
+  VariantProps<typeof containerVariants>;
+
+const Container = React.forwardRef<HTMLDivElement, ContainerProps>(
+  ({ className, maxWidth, disableGutters, ...props }, ref) => (
+    <div
+      ref={ref}
+      data-slot="container"
+      className={cn(containerVariants({ maxWidth, disableGutters }), className)}
+      {...props}
+    />
+  ),
+);
+Container.displayName = "Container";
+
+export { Container, containerVariants };

package/src/primitives/Fab.tsx

@@ -0,0 +1,62 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Slot } from "../lib/slot";
+import { cn } from "../lib/cn";
+
+const fabVariants = cva(
+  "inline-flex items-center justify-center gap-2 font-bold shadow-[0_10px_28px_color-mix(in_srgb,var(--foreground)_16%,transparent)] outline-none transition-[color,background-color,box-shadow,transform] duration-150 focus-visible:ring-ring/50 focus-visible:ring-[3px] active:scale-[0.98] disabled:pointer-events-none disabled:opacity-50 [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5",
+  {
+    variants: {
+      variant: {
+        circular: "rounded-full",
+        extended: "rounded-full px-5",
+      },
+      color: {
+        primary: "bg-primary text-primary-foreground hover:bg-primary/90",
+        glass: "glass border-border/50 text-foreground hover:border-primary/30 hover:text-primary",
+        default: "bg-card text-foreground border border-border/50 hover:bg-muted/60",
+      },
+      size: {
+        sm: "size-10 text-sm",
+        md: "size-14 text-base",
+        lg: "size-16 text-lg",
+      },
+    },
+    compoundVariants: [
+      { variant: "extended", size: "sm", className: "h-10 w-auto min-w-10" },
+      { variant: "extended", size: "md", className: "h-12 w-auto min-w-12 size-auto" },
+      { variant: "extended", size: "lg", className: "h-14 w-auto min-w-14 size-auto" },
+    ],
+    defaultVariants: {
+      variant: "circular",
+      color: "primary",
+      size: "md",
+    },
+  },
+);
+
+export type FabProps = Omit<React.ComponentPropsWithoutRef<"button">, "color"> &
+  VariantProps<typeof fabVariants> & {
+    asChild?: boolean;
+  };
+
+/**
+ * Floating action button. Use `variant="extended"` for a labeled FAB.
+ */
+const Fab = React.forwardRef<HTMLButtonElement, FabProps>(
+  ({ className, variant, color, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        ref={ref}
+        type={asChild ? undefined : "button"}
+        data-slot="fab"
+        className={cn(fabVariants({ variant, color, size }), className)}
+        {...props}
+      />
+    );
+  },
+);
+Fab.displayName = "Fab";
+
+export { Fab, fabVariants };

package/src/primitives/FormControl.tsx

@@ -0,0 +1,90 @@
+import * as React from "react";
+import { cn } from "../lib/cn";
+import { Label } from "./Label";
+
+type FormControlContextValue = {
+  error?: boolean;
+  disabled?: boolean;
+  required?: boolean;
+  fullWidth?: boolean;
+};
+
+const FormControlContext = React.createContext<FormControlContextValue | null>(null);
+
+export type FormControlProps = React.ComponentPropsWithoutRef<"div"> & {
+  error?: boolean;
+  disabled?: boolean;
+  required?: boolean;
+  fullWidth?: boolean;
+};
+
+function FormControl({
+  error,
+  disabled,
+  required,
+  fullWidth,
+  className,
+  ...props
+}: FormControlProps) {
+  return (
+    <FormControlContext.Provider value={{ error, disabled, required, fullWidth }}>
+      <div
+        data-slot="form-control"
+        data-error={error ? "" : undefined}
+        data-disabled={disabled ? "" : undefined}
+        className={cn("flex flex-col gap-1.5", fullWidth && "w-full", className)}
+        {...props}
+      />
+    </FormControlContext.Provider>
+  );
+}
+FormControl.displayName = "FormControl";
+
+function FormLabel({ className, children, ...props }: React.ComponentPropsWithoutRef<"label">) {
+  const ctx = React.useContext(FormControlContext);
+  return (
+    <Label
+      data-slot="form-label"
+      className={cn(ctx?.error && "text-destructive", className)}
+      {...props}
+    >
+      {children}
+      {ctx?.required ? <span className="text-destructive">*</span> : null}
+    </Label>
+  );
+}
+FormLabel.displayName = "FormLabel";
+
+function FormHelperText({ className, ...props }: React.ComponentPropsWithoutRef<"p">) {
+  const ctx = React.useContext(FormControlContext);
+  return (
+    <p
+      data-slot="form-helper-text"
+      className={cn(
+        "text-xs font-medium",
+        ctx?.error ? "text-destructive" : "text-muted-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+FormHelperText.displayName = "FormHelperText";
+
+function FormGroup({
+  row,
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<"div"> & { row?: boolean }) {
+  return (
+    <div
+      data-slot="form-group"
+      role="group"
+      className={cn("flex", row ? "flex-row flex-wrap gap-4" : "flex-col gap-2", className)}
+      {...props}
+    />
+  );
+}
+FormGroup.displayName = "FormGroup";
+
+export { FormControl, FormLabel, FormHelperText, FormGroup };

package/src/primitives/FormControlLabel.tsx

@@ -0,0 +1,51 @@
+import * as React from "react";
+import { cn } from "../lib/cn";
+import { Label } from "./Label";
+
+export type FormControlLabelProps = Omit<React.ComponentPropsWithoutRef<"label">, "control"> & {
+  control: React.ReactElement<{ disabled?: boolean }>;
+  label: React.ReactNode;
+  labelPlacement?: "end" | "start" | "top" | "bottom";
+  disabled?: boolean;
+};
+
+const placementClass = {
+  end: "flex-row",
+  start: "flex-row-reverse",
+  top: "flex-col-reverse items-center",
+  bottom: "flex-col items-center",
+} as const;
+
+/**
+ * Pairs a checkbox, radio, or switch with its visible label.
+ */
+function FormControlLabel({
+  control,
+  label,
+  labelPlacement = "end",
+  disabled,
+  className,
+  ...props
+}: FormControlLabelProps) {
+  const controlDisabled = disabled || control.props.disabled;
+
+  return (
+    <Label
+      data-slot="form-control-label"
+      data-disabled={controlDisabled ? "" : undefined}
+      className={cn(
+        "inline-flex w-fit cursor-pointer items-center gap-2",
+        placementClass[labelPlacement],
+        controlDisabled && "cursor-not-allowed opacity-50",
+        className,
+      )}
+      {...props}
+    >
+      {React.cloneElement(control, { disabled: controlDisabled })}
+      <span className="text-sm font-medium">{label}</span>
+    </Label>
+  );
+}
+FormControlLabel.displayName = "FormControlLabel";
+
+export { FormControlLabel };

package/src/primitives/Grid.tsx

@@ -0,0 +1,101 @@
+import * as React from "react";
+import { Slot } from "../lib/slot";
+import { cn } from "../lib/cn";
+
+export type BoxProps = React.ComponentPropsWithoutRef<"div"> & {
+  component?: React.ElementType;
+  asChild?: boolean;
+};
+
+/**
+ * Generic layout primitive. Prefer Stack / Grid / Paper for structured layouts.
+ */
+const Box = React.forwardRef<HTMLDivElement, BoxProps>(
+  ({ className, component = "div", asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : component;
+    return <Comp ref={ref} data-slot="box" className={cn(className)} {...props} />;
+  },
+);
+Box.displayName = "Box";
+
+const gapClass: Record<number, string> = {
+  0: "gap-0",
+  1: "gap-1",
+  2: "gap-2",
+  3: "gap-3",
+  4: "gap-4",
+  5: "gap-5",
+  6: "gap-6",
+  8: "gap-8",
+};
+
+const spanClass: Record<number, string> = {
+  1: "col-span-1",
+  2: "col-span-2",
+  3: "col-span-3",
+  4: "col-span-4",
+  5: "col-span-5",
+  6: "col-span-6",
+  7: "col-span-7",
+  8: "col-span-8",
+  9: "col-span-9",
+  10: "col-span-10",
+  11: "col-span-11",
+  12: "col-span-12",
+};
+
+export type GridProps = React.ComponentPropsWithoutRef<"div"> & {
+  container?: boolean;
+  item?: boolean;
+  spacing?: number;
+  columns?: 12;
+  xs?: number | "auto";
+  sm?: number | "auto";
+  md?: number | "auto";
+  lg?: number | "auto";
+  size?: number | "grow";
+};
+
+function spanFor(value?: number | "auto" | "grow") {
+  if (value == null || value === "auto" || value === "grow") return undefined;
+  return spanClass[value] ?? "col-span-12";
+}
+
+/**
+ * 12-column CSS grid. Use `container` on the parent and breakpoint spans on items.
+ */
+function Grid({
+  container,
+  item: _item,
+  spacing = 2,
+  columns: _columns = 12,
+  xs,
+  sm,
+  md,
+  lg,
+  size,
+  className,
+  ...props
+}: GridProps) {
+  const span = spanFor(typeof size === "number" ? size : xs);
+  return (
+    <div
+      data-slot="grid"
+      data-container={container ? "" : undefined}
+      data-item={_item || !container ? "" : undefined}
+      className={cn(
+        container && "grid grid-cols-12",
+        container && (gapClass[spacing] ?? "gap-2"),
+        !container && (span ?? (size === "grow" ? "col-span-12" : "col-span-12")),
+        sm && typeof sm === "number" && spanClass[sm]?.replace("col-span", "sm:col-span"),
+        md && typeof md === "number" && spanClass[md]?.replace("col-span", "md:col-span"),
+        lg && typeof lg === "number" && spanClass[lg]?.replace("col-span", "lg:col-span"),
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+Grid.displayName = "Grid";
+
+export { Box, Grid };

package/src/primitives/IconButton.tsx

@@ -0,0 +1,59 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Slot } from "../lib/slot";
+import { cn } from "../lib/cn";
+
+const iconButtonVariants = cva(
+  "inline-flex shrink-0 items-center justify-center outline-none transition-[color,background-color,border-color,transform] duration-150 focus-visible:ring-ring/50 focus-visible:ring-[3px] active:scale-[0.98] disabled:pointer-events-none disabled:opacity-50 [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        ghost: "text-muted-foreground hover:bg-muted/40 hover:text-foreground",
+        outline: "border border-border/60 bg-background/80 text-foreground hover:bg-muted/40",
+        glass: "glass border-border/50 text-foreground hover:border-primary/30 hover:text-primary",
+        filled: "bg-primary text-primary-foreground hover:bg-primary/90",
+      },
+      size: {
+        sm: "size-8 rounded-lg",
+        md: "size-10 rounded-xl",
+        lg: "size-12 rounded-xl",
+        touch: "size-11 rounded-xl",
+      },
+      shape: {
+        rounded: "",
+        circular: "rounded-full",
+      },
+    },
+    defaultVariants: {
+      variant: "ghost",
+      size: "md",
+      shape: "rounded",
+    },
+  },
+);
+
+export type IconButtonProps = React.ComponentPropsWithoutRef<"button"> &
+  VariantProps<typeof iconButtonVariants> & {
+    asChild?: boolean;
+  };
+
+/**
+ * Compact icon-only control. Prefer {@link HeaderIconButton} inside app chrome.
+ */
+const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
+  ({ className, variant, size, shape, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        ref={ref}
+        type={asChild ? undefined : "button"}
+        data-slot="icon-button"
+        className={cn(iconButtonVariants({ variant, size, shape }), className)}
+        {...props}
+      />
+    );
+  },
+);
+IconButton.displayName = "IconButton";
+
+export { IconButton, iconButtonVariants };

package/src/primitives/ImageList.test.tsx

@@ -0,0 +1,48 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { ImageList, ImageListItem, ImageListItemBar } from "./ImageList";
+
+describe("ImageList", () => {
+  it("lays out items in a full-width grid with overlay titles", () => {
+    const { container } = render(
+      <ImageList cols={3} rowHeight={148} gap={10}>
+        <ImageListItem>
+          <img src="/coast.jpg" alt="Coast" />
+          <ImageListItemBar title="Coast" subtitle="Pacific" />
+        </ImageListItem>
+        <ImageListItem>
+          <img src="/dawn.jpg" alt="Dawn" />
+          <ImageListItemBar title="Dawn" />
+        </ImageListItem>
+      </ImageList>,
+    );
+
+    const list = container.querySelector("[data-slot='image-list']");
+    expect(list).toHaveAttribute("data-variant", "standard");
+    expect(list).toHaveClass("w-full");
+    expect(list).toHaveStyle({
+      gridTemplateColumns: "repeat(3, minmax(0, 1fr))",
+      gridAutoRows: "148px",
+    });
+    expect(screen.getByText("Coast")).toBeInTheDocument();
+    expect(screen.getByText("Pacific")).toBeInTheDocument();
+    expect(screen.getByRole("img", { name: "Coast" })).toBeInTheDocument();
+    const item = container.querySelector("[data-slot='image-list-item']");
+    expect(item).not.toHaveStyle({ marginBottom: "8px" });
+  });
+
+  it("switches to masonry columns without a css grid", () => {
+    const { container } = render(
+      <ImageList variant="masonry" cols={2} gap={12}>
+        <ImageListItem>
+          <img src="/dusk.jpg" alt="Dusk" />
+        </ImageListItem>
+      </ImageList>,
+    );
+    const list = container.querySelector("[data-slot='image-list']");
+    expect(list).toHaveAttribute("data-variant", "masonry");
+    expect(list).toHaveClass("block");
+    expect(list).not.toHaveClass("grid");
+    expect(list).toHaveStyle({ columnCount: "2" });
+  });
+});

package/src/primitives/ImageList.tsx

@@ -0,0 +1,112 @@
+import * as React from "react";
+import { cn } from "../lib/cn";
+
+export type ImageListProps = React.ComponentPropsWithoutRef<"ul"> & {
+  cols?: number;
+  gap?: number;
+  variant?: "standard" | "quilted" | "masonry";
+  rowHeight?: number;
+};
+
+function ImageList({
+  cols = 2,
+  gap = 8,
+  variant = "standard",
+  rowHeight = 180,
+  className,
+  style,
+  children,
+  ...props
+}: ImageListProps) {
+  return (
+    <ul
+      data-slot="image-list"
+      data-variant={variant}
+      className={cn(
+        "m-0 w-full list-none p-0",
+        variant === "masonry"
+          ? "block [&>[data-slot=image-list-item]]:mb-2 [&>[data-slot=image-list-item]]:h-auto"
+          : "grid",
+        className,
+      )}
+      style={{
+        gap,
+        ...(variant === "masonry"
+          ? { columnCount: cols, columnGap: gap }
+          : {
+              gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`,
+              gridAutoRows: rowHeight,
+            }),
+        ...style,
+      }}
+      {...props}
+    >
+      {children}
+    </ul>
+  );
+}
+ImageList.displayName = "ImageList";
+
+export type ImageListItemProps = React.ComponentPropsWithoutRef<"li"> & {
+  cols?: number;
+  rows?: number;
+};
+
+function ImageListItem({ cols = 1, rows = 1, className, style, ...props }: ImageListItemProps) {
+  return (
+    <li
+      data-slot="image-list-item"
+      className={cn(
+        "relative h-full min-h-0 overflow-hidden rounded-xl [&_img]:absolute [&_img]:inset-0 [&_img]:size-full [&_img]:object-cover",
+        className,
+      )}
+      style={{
+        gridColumn: `span ${cols}`,
+        gridRow: `span ${rows}`,
+        breakInside: "avoid",
+        ...style,
+      }}
+      {...props}
+    />
+  );
+}
+ImageListItem.displayName = "ImageListItem";
+
+export type ImageListItemBarProps = React.ComponentPropsWithoutRef<"div"> & {
+  title?: React.ReactNode;
+  subtitle?: React.ReactNode;
+  actionIcon?: React.ReactNode;
+  position?: "bottom" | "top";
+};
+
+function ImageListItemBar({
+  title,
+  subtitle,
+  actionIcon,
+  position = "bottom",
+  className,
+  ...props
+}: ImageListItemBarProps) {
+  return (
+    <div
+      data-slot="image-list-item-bar"
+      className={cn(
+        "absolute inset-x-0 z-10 flex items-end justify-between gap-2 p-3 text-white",
+        position === "top"
+          ? "top-0 bg-gradient-to-b from-black/70 to-transparent"
+          : "bottom-0 bg-gradient-to-t from-black/70 to-transparent",
+        className,
+      )}
+      {...props}
+    >
+      <div className="min-w-0">
+        <div className="truncate text-sm font-bold">{title}</div>
+        {subtitle ? <div className="truncate text-xs opacity-80">{subtitle}</div> : null}
+      </div>
+      {actionIcon}
+    </div>
+  );
+}
+ImageListItemBar.displayName = "ImageListItemBar";
+
+export { ImageList, ImageListItem, ImageListItemBar };