@spatika/react 1.0.0

package/src/composites/QuickSettings.tsx

@@ -0,0 +1,120 @@
+import type { ReactNode } from "react";
+import { X } from "lucide-react";
+import { cn } from "../lib/cn";
+import { Button } from "../primitives/Button";
+
+export type QuickSettingsProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title?: string;
+  description?: string;
+  children: ReactNode;
+  /** side sheet from right (default) or bottom drawer-like panel */
+  side?: "right" | "left";
+  className?: string;
+};
+
+/**
+ * Sliding quick-settings panel — appearance, density, toggles, etc.
+ */
+export function QuickSettings({
+  open,
+  onOpenChange,
+  title = "Quick settings",
+  description,
+  children,
+  side = "right",
+  className,
+}: QuickSettingsProps) {
+  if (!open) return null;
+
+  return (
+    <div data-slot="quick-settings" className="fixed inset-0 z-50">
+      <button
+        type="button"
+        aria-label="Close settings"
+        className="absolute inset-0 bg-[var(--modal-overlay-bg)] backdrop-blur-[var(--modal-overlay-blur)]"
+        onClick={() => onOpenChange(false)}
+      />
+      <aside
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        className={cn(
+          "glass-menu absolute top-0 flex h-full w-full max-w-sm flex-col shadow-2xl",
+          side === "right" ? "right-0 border-l" : "left-0 border-r",
+          "border-border/40",
+          className,
+        )}
+      >
+        <div className="flex items-start justify-between gap-3 border-b border-border/40 px-4 py-4">
+          <div>
+            <h2 className="text-base font-black tracking-tight">{title}</h2>
+            {description ? (
+              <p className="mt-0.5 text-xs font-medium text-muted-foreground">{description}</p>
+            ) : null}
+          </div>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            aria-label="Close"
+            onClick={() => onOpenChange(false)}
+          >
+            <X className="size-4" />
+          </Button>
+        </div>
+        <div className="flex-1 space-y-5 overflow-y-auto px-4 py-4">{children}</div>
+      </aside>
+    </div>
+  );
+}
+
+export function QuickSettingsGroup({
+  title,
+  children,
+  className,
+}: {
+  title: string;
+  children: ReactNode;
+  className?: string;
+}) {
+  return (
+    <div data-slot="quick-settings-group" className={cn("space-y-3", className)}>
+      <p className="text-[10px] font-black uppercase tracking-widest text-muted-foreground/70">
+        {title}
+      </p>
+      <div className="space-y-2">{children}</div>
+    </div>
+  );
+}
+
+export function QuickSettingsRow({
+  label,
+  description,
+  control,
+  className,
+}: {
+  label: string;
+  description?: string;
+  control: ReactNode;
+  className?: string;
+}) {
+  return (
+    <div
+      data-slot="quick-settings-row"
+      className={cn(
+        "flex items-center justify-between gap-3 rounded-xl border border-border/40 bg-background/30 px-3 py-2.5",
+        className,
+      )}
+    >
+      <div className="min-w-0">
+        <p className="text-sm font-bold">{label}</p>
+        {description ? (
+          <p className="text-xs text-muted-foreground">{description}</p>
+        ) : null}
+      </div>
+      <div className="shrink-0">{control}</div>
+    </div>
+  );
+}

package/src/composites/RichTextEditor.tsx

@@ -0,0 +1,103 @@
+import { useEffect, useRef } from "react";
+import {
+  Bold,
+  Italic,
+  List,
+  ListOrdered,
+  Underline as UnderlineIcon,
+} from "lucide-react";
+import { cn } from "../lib/cn";
+import { Button } from "../primitives/Button";
+
+export type RichTextEditorProps = {
+  value?: string;
+  onChange?: (html: string) => void;
+  placeholder?: string;
+  className?: string;
+  minHeightClassName?: string;
+};
+
+/**
+ * Lightweight rich-text surface (contenteditable) for notes and captions.
+ * Pair with TipTap or another full editor in your app when you need tables or advanced media.
+ */
+export function RichTextEditor({
+  value = "",
+  onChange,
+  placeholder = "Write something…",
+  className,
+  minHeightClassName = "min-h-40",
+}: RichTextEditorProps) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (ref.current && value !== ref.current.innerHTML) {
+      ref.current.innerHTML = value;
+    }
+  }, [value]);
+
+  const exec = (command: string) => {
+    document.execCommand(command);
+    onChange?.(ref.current?.innerHTML ?? "");
+    ref.current?.focus();
+  };
+
+  return (
+    <div
+      data-slot="rich-text-editor"
+      className={cn(
+        "overflow-hidden rounded-[var(--radius-card)] border border-border/50 bg-input-background",
+        className,
+      )}
+    >
+      <div className="flex flex-wrap gap-1 border-b border-border/40 bg-muted/30 p-1.5">
+        <Button type="button" variant="ghost" size="icon" aria-label="Bold" onClick={() => exec("bold")}>
+          <Bold className="size-4" />
+        </Button>
+        <Button type="button" variant="ghost" size="icon" aria-label="Italic" onClick={() => exec("italic")}>
+          <Italic className="size-4" />
+        </Button>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          aria-label="Underline"
+          onClick={() => exec("underline")}
+        >
+          <UnderlineIcon className="size-4" />
+        </Button>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          aria-label="Bullet list"
+          onClick={() => exec("insertUnorderedList")}
+        >
+          <List className="size-4" />
+        </Button>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          aria-label="Numbered list"
+          onClick={() => exec("insertOrderedList")}
+        >
+          <ListOrdered className="size-4" />
+        </Button>
+      </div>
+      <div
+        ref={ref}
+        role="textbox"
+        aria-multiline="true"
+        contentEditable
+        suppressContentEditableWarning
+        data-placeholder={placeholder}
+        className={cn(
+          "px-3 py-2 text-sm outline-none empty:before:text-muted-foreground empty:before:content-[attr(data-placeholder)]",
+          minHeightClassName,
+        )}
+        onInput={() => onChange?.(ref.current?.innerHTML ?? "")}
+      />
+    </div>
+  );
+}

package/src/composites/SearchField.tsx

@@ -0,0 +1,38 @@
+import type { ComponentProps, ReactNode } from "react";
+import { Search } from "lucide-react";
+import { cn } from "../lib/cn";
+import { Input } from "../primitives/Input";
+
+export type SearchFieldProps = ComponentProps<"input"> & {
+  containerClassName?: string;
+  leading?: ReactNode;
+};
+
+/** Search input with leading icon — mobile-friendly min height. */
+export function SearchField({
+  className,
+  containerClassName,
+  leading,
+  ...props
+}: SearchFieldProps) {
+  return (
+    <div
+      data-slot="search-field"
+      className={cn("relative w-full", containerClassName)}
+    >
+      {/* inset-y + flex centers the icon without translate utilities (more reliable across app Tailwind scans) */}
+      <span className="pointer-events-none absolute inset-y-0 left-0 z-10 flex items-center pl-3 text-muted-foreground">
+        {leading ?? <Search className="h-4 w-4 shrink-0" aria-hidden />}
+      </span>
+      <Input
+        className={cn(
+          "h-11 py-0 pl-9 leading-none",
+          "[&::-webkit-search-decoration]:appearance-none [&::-webkit-search-cancel-button]:appearance-none [&::-webkit-search-results-button]:appearance-none [&::-webkit-search-results-decoration]:appearance-none",
+          className,
+        )}
+        type="search"
+        {...props}
+      />
+    </div>
+  );
+}

package/src/composites/SectionPanel.tsx

@@ -0,0 +1,59 @@
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type SectionPanelProps = {
+  icon: LucideIcon;
+  title: string;
+  subtitle?: string;
+  children: ReactNode;
+  className?: string;
+  fullWidth?: boolean;
+  trailing?: ReactNode;
+};
+
+/**
+ * Glassmorphic settings / admin section with icon tile and uppercase subtitle.
+ */
+export function SectionPanel({
+  icon: Icon,
+  title,
+  subtitle,
+  children,
+  className,
+  fullWidth = false,
+  trailing,
+}: SectionPanelProps) {
+  return (
+    <section
+      data-slot="section-panel"
+      className={cn(
+        "group relative flex flex-col gap-5 overflow-hidden border border-border/30 bg-card/60 p-5 shadow-2xl backdrop-blur-md sm:gap-6 sm:p-6",
+        "rounded-[var(--radius-card)]",
+        fullWidth && "md:col-span-2",
+        className,
+      )}
+    >
+      <div className="pointer-events-none absolute -right-12 -top-12 h-48 w-48 rounded-full bg-primary/5 blur-3xl transition-colors duration-700 group-hover:bg-primary/10" />
+
+      <div className="relative flex items-start justify-between gap-3">
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="shrink-0 rounded-xl border border-primary/20 bg-primary/10 p-2 shadow-inner">
+            <Icon className="h-4 w-4 text-primary" />
+          </div>
+          <div className="min-w-0">
+            <h2 className="text-lg font-black tracking-tight text-foreground">{title}</h2>
+            {subtitle ? (
+              <p className="mt-0.5 text-[10px] font-black uppercase tracking-widest text-muted-foreground/60">
+                {subtitle}
+              </p>
+            ) : null}
+          </div>
+        </div>
+        {trailing ? <div className="relative shrink-0">{trailing}</div> : null}
+      </div>
+
+      <div className="relative">{children}</div>
+    </section>
+  );
+}

package/src/composites/SegmentedControl.tsx

@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type SegmentedControlOption<T extends string = string> = {
+  value: T;
+  label: ReactNode;
+  disabled?: boolean;
+};
+
+export type SegmentedControlProps<T extends string = string> = {
+  options: SegmentedControlOption<T>[];
+  value: T;
+  onChange: (value: T) => void;
+  className?: string;
+  size?: "sm" | "md";
+  "aria-label"?: string;
+};
+
+/** Single-select segmented toggle (income/expense, period, etc.). */
+export function SegmentedControl<T extends string = string>({
+  options,
+  value,
+  onChange,
+  className,
+  size = "md",
+  "aria-label": ariaLabel,
+}: SegmentedControlProps<T>) {
+  return (
+    <div
+      data-slot="segmented-control"
+      role="radiogroup"
+      aria-label={ariaLabel}
+      className={cn(
+        "inline-flex items-center rounded-xl border border-border/50 bg-muted/25 p-1",
+        className,
+      )}
+    >
+      {options.map((opt) => {
+        const active = opt.value === value;
+        return (
+          <button
+            key={opt.value}
+            type="button"
+            role="radio"
+            aria-checked={active}
+            disabled={opt.disabled}
+            onClick={() => onChange(opt.value)}
+            className={cn(
+              "rounded-lg font-bold transition-colors disabled:pointer-events-none disabled:opacity-40",
+              size === "sm" ? "px-2.5 py-1 text-xs" : "px-3.5 py-1.5 text-sm",
+              active
+                ? "bg-background text-foreground shadow-sm"
+                : "text-muted-foreground hover:text-foreground",
+            )}
+          >
+            {opt.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/composites/StatCard.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type StatCardProps = {
+  label: string;
+  value: string | number;
+  hint?: string;
+  icon?: ReactNode;
+  className?: string;
+};
+
+/** Compact metric tile using elevated app-card surface. */
+export function StatCard({ label, value, hint, icon, className }: StatCardProps) {
+  return (
+    <div data-slot="stat-card" className={cn("app-stat-card p-4 sm:p-5", className)}>
+      <div className="flex items-start justify-between gap-3">
+        <p className="text-[10px] font-black uppercase tracking-widest text-muted-foreground">
+          {label}
+        </p>
+        {icon ? <div className="text-primary">{icon}</div> : null}
+      </div>
+      <p className="mt-2 text-2xl font-black tracking-tight text-foreground">{value}</p>
+      {hint ? <p className="mt-1 text-xs font-medium text-muted-foreground">{hint}</p> : null}
+    </div>
+  );
+}

package/src/composites/StatusDot.tsx

@@ -0,0 +1,40 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/cn";
+
+const statusDotVariants = cva("inline-block size-2 shrink-0 rounded-full", {
+  variants: {
+    tone: {
+      neutral: "bg-muted-foreground/50",
+      success: "bg-[var(--accent-info)]",
+      warning: "bg-[var(--accent-warm)]",
+      danger: "bg-destructive",
+      primary: "bg-primary",
+    },
+    pulse: {
+      true: "animate-pulse",
+      false: "",
+    },
+  },
+  defaultVariants: { tone: "neutral", pulse: false },
+});
+
+export function StatusDot({
+  className,
+  tone,
+  pulse,
+  label,
+}: VariantProps<typeof statusDotVariants> & {
+  className?: string;
+  label?: string;
+}) {
+  return (
+    <span
+      data-slot="status-dot"
+      role={label ? "img" : undefined}
+      aria-label={label}
+      className={cn(statusDotVariants({ tone, pulse }), className)}
+    />
+  );
+}
+
+export { statusDotVariants };

package/src/composites/SurfaceCard.tsx

@@ -0,0 +1,44 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/cn";
+import {
+  surfaceDetailClass,
+  surfacePrimaryClass,
+  surfaceSecondaryClass,
+  surfaceTertiaryClass,
+} from "../lib/surfaces";
+
+const surfaceCardVariants = cva("", {
+  variants: {
+    tone: {
+      primary: surfacePrimaryClass,
+      secondary: surfaceSecondaryClass,
+      detail: surfaceDetailClass,
+      tertiary: surfaceTertiaryClass,
+    },
+  },
+  defaultVariants: {
+    tone: "primary",
+  },
+});
+
+export type SurfaceCardProps = React.ComponentProps<"div"> &
+  VariantProps<typeof surfaceCardVariants>;
+
+/**
+ * Profile / hierarchy surface card (primary → tertiary visual weight).
+ */
+const SurfaceCard = React.forwardRef<HTMLDivElement, SurfaceCardProps>(
+  ({ className, tone, ...props }, ref) => (
+    <div
+      ref={ref}
+      data-slot="surface-card"
+      data-tone={tone ?? "primary"}
+      className={cn(surfaceCardVariants({ tone }), className)}
+      {...props}
+    />
+  ),
+);
+SurfaceCard.displayName = "SurfaceCard";
+
+export { SurfaceCard, surfaceCardVariants };

package/src/composites/Timeline.tsx

@@ -0,0 +1,70 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type TimelineItemProps = {
+  title: string;
+  meta?: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  trailing?: ReactNode;
+  active?: boolean;
+  className?: string;
+};
+
+/** Single activity / journal row inside a Timeline. */
+export function TimelineItem({
+  title,
+  meta,
+  description,
+  icon,
+  trailing,
+  active,
+  className,
+}: TimelineItemProps) {
+  return (
+    <li
+      data-slot="timeline-item"
+      className={cn("relative flex gap-3 pb-5 last:pb-0", className)}
+    >
+      <div className="flex w-8 shrink-0 flex-col items-center">
+        <div
+          className={cn(
+            "flex h-8 w-8 items-center justify-center rounded-xl border text-muted-foreground",
+            active
+              ? "border-primary/35 bg-primary/10 text-primary"
+              : "border-border/50 bg-muted/20",
+          )}
+        >
+          {icon ?? <span className="h-1.5 w-1.5 rounded-full bg-current" />}
+        </div>
+        <div className="mt-1 w-px flex-1 bg-border/50" aria-hidden />
+      </div>
+      <div className="min-w-0 flex-1 pt-0.5">
+        <div className="flex items-start gap-2">
+          <div className="min-w-0 flex-1">
+            <p className="text-sm font-bold text-foreground">{title}</p>
+            {meta ? <div className="mt-0.5 text-xs text-muted-foreground">{meta}</div> : null}
+          </div>
+          {trailing ? <div className="shrink-0">{trailing}</div> : null}
+        </div>
+        {description ? (
+          <div className="mt-1.5 text-sm text-muted-foreground">{description}</div>
+        ) : null}
+      </div>
+    </li>
+  );
+}
+
+export type TimelineProps = {
+  children: ReactNode;
+  className?: string;
+};
+
+/** Vertical activity / journal feed. */
+export function Timeline({ children, className }: TimelineProps) {
+  return (
+    <ul data-slot="timeline" className={cn("space-y-0", className)}>
+      {children}
+    </ul>
+  );
+}