@opencosmos/ui 1.3.1

package/src/components/feedback/Skeleton.tsx

@@ -0,0 +1,45 @@
+import * as React from "react"
+import { cn } from "../../lib/utils"
+
+export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Variant of the skeleton
+   * @default "default"
+   */
+  variant?: "default" | "circular" | "rectangular" | "text"
+  /**
+   * Width of the skeleton (CSS value)
+   */
+  width?: string | number
+  /**
+   * Height of the skeleton (CSS value)
+   */
+  height?: string | number
+}
+
+function Skeleton({ className, variant = "default", width, height, style, ...props }: SkeletonProps) {
+  const variantStyles = {
+    default: "rounded-md",
+    circular: "rounded-full",
+    rectangular: "rounded-none",
+    text: "rounded-xs h-4",
+  }
+
+  return (
+    <div
+      className={cn(
+        "animate-pulse bg-muted",
+        variantStyles[variant],
+        className
+      )}
+      style={{
+        width,
+        height: variant === "text" ? undefined : height,
+        ...style,
+      }}
+      {...props}
+    />
+  )
+}
+
+export { Skeleton }

package/src/components/feedback/Sonner.tsx

@@ -0,0 +1,28 @@
+"use client"
+
+import { Toaster as Sonner } from "sonner"
+
+type ToasterProps = React.ComponentProps<typeof Sonner>
+
+const Toaster = ({ ...props }: ToasterProps) => {
+  return (
+    <Sonner
+      theme="system"
+      className="toaster group"
+      toastOptions={{
+        classNames: {
+          toast:
+            "group toast group-[.toaster]:bg-background group-[.toaster]:text-foreground group-[.toaster]:border-border group-[.toaster]:shadow-lg",
+          description: "group-[.toast]:text-muted-foreground",
+          actionButton:
+            "group-[.toast]:bg-primary group-[.toast]:text-primary-foreground",
+          cancelButton:
+            "group-[.toast]:bg-muted group-[.toast]:text-muted-foreground",
+        },
+      }}
+      {...props}
+    />
+  )
+}
+
+export { Toaster }

package/src/components/feedback/Spinner.test.tsx

@@ -0,0 +1,33 @@
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect } from 'vitest'
+import { Spinner } from './Spinner'
+
+describe('Spinner', () => {
+  it('renders with status role', () => {
+    render(<Spinner />)
+    expect(screen.getByRole('status')).toBeInTheDocument()
+  })
+
+  it('has default loading label for screen readers', () => {
+    render(<Spinner />)
+    expect(screen.getByRole('status')).toHaveAttribute('aria-label', 'Loading...')
+    expect(screen.getByText('Loading...')).toHaveClass('sr-only')
+  })
+
+  it('accepts custom label', () => {
+    render(<Spinner label="Saving data..." />)
+    expect(screen.getByRole('status')).toHaveAttribute('aria-label', 'Saving data...')
+  })
+
+  it('renders SVG spinner', () => {
+    render(<Spinner />)
+    const svg = screen.getByRole('status').querySelector('svg')
+    expect(svg).toBeInTheDocument()
+    expect(svg).toHaveClass('animate-spin')
+  })
+
+  it('applies custom className', () => {
+    render(<Spinner className="custom-spinner" />)
+    expect(screen.getByRole('status')).toHaveClass('custom-spinner')
+  })
+})

package/src/components/feedback/Spinner.tsx

@@ -0,0 +1,99 @@
+import React from 'react';
+
+export interface SpinnerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Size of the spinner
+   * @default 'md'
+   */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+  /**
+   * Color variant
+   * @default 'primary'
+   */
+  variant?: 'primary' | 'secondary' | 'inherit';
+
+  /**
+   * Optional label for screen readers
+   */
+  label?: string;
+}
+
+/**
+ * Spinner Component
+ *
+ * A loading indicator with smooth animation.
+ *
+ * Features:
+ * - Five size variants
+ * - Theme-aware colors
+ * - Uses current text color option
+ * - Accessible label for screen readers
+ * - Respects reduced motion preferences
+ *
+ * Example:
+ * ```tsx
+ * <Spinner />
+ * <Spinner size="lg" variant="primary" label="Loading content..." />
+ * <Spinner size="sm" variant="inherit" />
+ * ```
+ */
+export const Spinner = (
+  {
+    ref,
+    size = 'md',
+    variant = 'primary',
+    label = 'Loading...',
+    className = '',
+    ...props
+  }: SpinnerProps & {
+    ref?: React.Ref<HTMLDivElement>;
+  }
+) => {
+  const sizes = {
+    xs: 'w-4 h-4',
+    sm: 'w-5 h-5',
+    md: 'w-6 h-6',
+    lg: 'w-8 h-8',
+    xl: 'w-12 h-12',
+  };
+
+  const variants = {
+    primary: 'text-[var(--color-primary)]',
+    secondary: 'text-[var(--color-text-secondary)]',
+    inherit: 'text-current',
+  };
+
+  return (
+    <div
+      ref={ref}
+      className={`inline-block ${className}`}
+      role="status"
+      aria-label={label}
+      {...props}
+    >
+      <svg
+        className={`${sizes[size]} ${variants[variant]} animate-spin`}
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+        aria-hidden="true"
+      >
+        <circle
+          className="opacity-25"
+          cx="12"
+          cy="12"
+          r="10"
+          stroke="currentColor"
+          strokeWidth="4"
+        />
+        <path
+          className="opacity-75"
+          fill="currentColor"
+          d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+        />
+      </svg>
+      <span className="sr-only">{label}</span>
+    </div>
+  );
+};

package/src/components/feedback/Stepper.tsx

@@ -0,0 +1,307 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "../../lib/utils"
+
+const stepperVariants = cva("flex", {
+  variants: {
+    orientation: {
+      horizontal: "flex-row items-start",
+      vertical: "flex-col",
+    },
+    size: {
+      sm: "gap-2",
+      default: "gap-3",
+      lg: "gap-4",
+    },
+  },
+  defaultVariants: {
+    orientation: "horizontal",
+    size: "default",
+  },
+})
+
+const stepperIndicatorVariants = cva(
+  "flex items-center justify-center rounded-full border-2 shrink-0 font-medium transition-colors",
+  {
+    variants: {
+      status: {
+        pending: "border-border bg-muted text-foreground-secondary",
+        active: "border-primary bg-primary text-primary-foreground",
+        completed: "border-primary bg-primary text-primary-foreground",
+        error: "border-destructive bg-destructive text-destructive-foreground",
+      },
+      size: {
+        sm: "h-7 w-7 text-xs",
+        default: "h-9 w-9 text-sm",
+        lg: "h-11 w-11 text-base",
+      },
+    },
+    defaultVariants: {
+      status: "pending",
+      size: "default",
+    },
+  }
+)
+
+export interface StepperProps
+  extends React.HTMLAttributes<HTMLOListElement>,
+    VariantProps<typeof stepperVariants> {
+  /** Zero-based index of the current step */
+  currentStep: number
+  /** Called when a step is clicked (only when clickable is true) */
+  onStepClick?: (step: number) => void
+  /** Allow clicking steps to navigate */
+  clickable?: boolean
+}
+
+export interface StepperStepProps
+  extends React.HTMLAttributes<HTMLLIElement> {
+  /** Step label text */
+  label: string
+  /** Optional description below the label */
+  description?: string
+  /** Custom icon for the indicator */
+  icon?: React.ReactNode
+  /** Status (auto-computed from currentStep if not provided) */
+  status?: "pending" | "active" | "completed" | "error"
+  /** Mark step as optional */
+  optional?: boolean
+}
+
+const CheckIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2.5"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <polyline points="20 6 9 17 4 12" />
+  </svg>
+)
+
+const XIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2.5"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <line x1="18" y1="6" x2="6" y2="18" />
+    <line x1="6" y1="6" x2="18" y2="18" />
+  </svg>
+)
+
+interface StepperContextValue {
+  currentStep: number
+  orientation: "horizontal" | "vertical"
+  size: "sm" | "default" | "lg"
+  clickable: boolean
+  onStepClick?: (step: number) => void
+}
+
+const StepperContext = React.createContext<StepperContextValue>({
+  currentStep: 0,
+  orientation: "horizontal",
+  size: "default",
+  clickable: false,
+})
+
+function Stepper({
+  className,
+  orientation = "horizontal",
+  size = "default",
+  currentStep,
+  onStepClick,
+  clickable = false,
+  children,
+  ...props
+}: StepperProps) {
+  return (
+    <StepperContext.Provider
+      value={{ currentStep, orientation: orientation ?? "horizontal", size: size ?? "default", clickable, onStepClick }}
+    >
+      <ol
+        data-slot="stepper"
+        className={cn(stepperVariants({ orientation, size }), className)}
+        aria-label="Progress"
+        {...props}
+      >
+        {React.Children.map(children, (child, index) => {
+          if (!React.isValidElement(child)) return child
+
+          const totalSteps = React.Children.count(children)
+          const isLast = index === totalSteps - 1
+
+          const childStatus =
+            (child.props as StepperStepProps).status ??
+            (index < currentStep
+              ? "completed"
+              : index === currentStep
+                ? "active"
+                : "pending")
+
+          return (
+            <StepperStepInternal
+              {...(child.props as StepperStepProps)}
+              status={childStatus}
+              stepIndex={index}
+              isLast={isLast}
+            />
+          )
+        })}
+      </ol>
+    </StepperContext.Provider>
+  )
+}
+
+interface StepperStepInternalProps extends StepperStepProps {
+  stepIndex: number
+  isLast: boolean
+}
+
+function StepperStepInternal({
+  className,
+  label,
+  description,
+  icon,
+  status = "pending",
+  optional = false,
+  stepIndex,
+  isLast,
+  ...props
+}: StepperStepInternalProps) {
+  const { orientation, size, clickable, onStepClick } = React.useContext(StepperContext)
+
+  const indicatorContent = (() => {
+    if (icon) return icon
+    if (status === "completed") return <CheckIcon />
+    if (status === "error") return <XIcon />
+    return stepIndex + 1
+  })()
+
+  const isHorizontal = orientation === "horizontal"
+
+  const handleClick = () => {
+    if (clickable && onStepClick) {
+      onStepClick(stepIndex)
+    }
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (clickable && onStepClick && (e.key === "Enter" || e.key === " ")) {
+      e.preventDefault()
+      onStepClick(stepIndex)
+    }
+  }
+
+  return (
+    <li
+      data-slot="stepper-step"
+      className={cn(
+        "flex",
+        isHorizontal ? "flex-1 items-start" : "items-start",
+        className
+      )}
+      aria-current={status === "active" ? "step" : undefined}
+      {...props}
+    >
+      <div
+        className={cn(
+          "flex",
+          isHorizontal ? "flex-col items-center flex-1" : "flex-row items-start gap-3"
+        )}
+      >
+        {/* Indicator + Separator row */}
+        <div
+          className={cn(
+            "flex items-center",
+            isHorizontal ? "w-full" : "flex-col"
+          )}
+        >
+          {/* Indicator */}
+          <button
+            type="button"
+            className={cn(
+              stepperIndicatorVariants({ status, size: size ?? "default" }),
+              clickable
+                ? "cursor-pointer hover:opacity-80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+                : "cursor-default"
+            )}
+            onClick={handleClick}
+            onKeyDown={handleKeyDown}
+            tabIndex={clickable ? 0 : -1}
+            aria-label={`Step ${stepIndex + 1}: ${label}${status === "completed" ? " (completed)" : status === "active" ? " (current)" : status === "error" ? " (error)" : ""}`}
+          >
+            {indicatorContent}
+          </button>
+
+          {/* Separator */}
+          {!isLast && isHorizontal && (
+            <div
+              data-slot="stepper-separator"
+              className={cn(
+                "h-0.5 flex-1 mx-2",
+                status === "completed" ? "bg-primary" : "bg-border"
+              )}
+              aria-hidden="true"
+            />
+          )}
+          {!isLast && !isHorizontal && (
+            <div
+              data-slot="stepper-separator"
+              className={cn(
+                "w-0.5 min-h-6 my-1",
+                status === "completed" ? "bg-primary" : "bg-border"
+              )}
+              aria-hidden="true"
+            />
+          )}
+        </div>
+
+        {/* Label + Description */}
+        <div
+          className={cn(
+            isHorizontal ? "mt-2 text-center" : "",
+            "min-w-0"
+          )}
+        >
+          <p
+            className={cn(
+              "text-sm font-medium",
+              status === "active" ? "text-foreground" : "text-foreground-secondary"
+            )}
+          >
+            {label}
+          </p>
+          {(description || optional) && (
+            <p className="text-xs text-foreground-secondary mt-0.5">
+              {description}
+              {optional && !description && "Optional"}
+              {optional && description && " (Optional)"}
+            </p>
+          )}
+        </div>
+      </div>
+    </li>
+  )
+}
+
+/** Public sub-component for declaring steps */
+function StepperStep(_props: StepperStepProps) {
+  // Rendered internally by Stepper - this is just for the public API
+  return null
+}
+
+export { Stepper, StepperStep, stepperVariants }