@startsimpli/ui 0.1.0 → 0.1.3

package/src/components/loading/DashboardSkeleton.tsx

@@ -0,0 +1,27 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export interface DashboardSkeletonProps {
+  cards?: number
+  className?: string
+}
+
+export function DashboardSkeleton({
+  cards = 4,
+  className,
+}: DashboardSkeletonProps) {
+  return (
+    <div className={cn('grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4', className)}>
+      {Array.from({ length: cards }).map((_, i) => (
+        <div key={i} className="rounded-lg border bg-background p-6">
+          <div className="flex items-center justify-between mb-4">
+            <div className="h-4 w-24 animate-pulse rounded-md bg-gray-200" />
+            <div className="h-8 w-8 animate-pulse rounded-md bg-gray-200" />
+          </div>
+          <div className="h-8 w-20 animate-pulse rounded-md bg-gray-200 mb-2" />
+          <div className="h-3 w-32 animate-pulse rounded-md bg-gray-200" />
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/components/loading/TableSkeleton.tsx

@@ -0,0 +1,63 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export interface TableSkeletonProps {
+  rows?: number
+  columns?: number
+  className?: string
+}
+
+export function TableSkeleton({
+  rows = 5,
+  columns = 4,
+  className,
+}: TableSkeletonProps) {
+  return (
+    <div className={cn('bg-background rounded-lg border', className)}>
+      {/* Header skeleton */}
+      <div className="p-4 border-b">
+        <div className="flex justify-between items-center gap-4">
+          <div className="h-10 w-full max-w-sm animate-pulse rounded-md bg-gray-200" />
+          <div className="flex gap-2">
+            <div className="h-10 w-24 animate-pulse rounded-md bg-gray-200" />
+          </div>
+        </div>
+      </div>
+
+      {/* Table body skeleton */}
+      <div className="overflow-x-auto">
+        <table className="w-full">
+          <thead className="border-b bg-muted/50">
+            <tr>
+              {Array.from({ length: columns }).map((_, i) => (
+                <th key={i} className="p-4 text-left">
+                  <div className="h-4 w-24 animate-pulse rounded-md bg-gray-200" />
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {Array.from({ length: rows }).map((_, rowIndex) => (
+              <tr key={rowIndex} className="border-b last:border-b-0">
+                {Array.from({ length: columns }).map((_, colIndex) => (
+                  <td key={colIndex} className="p-4">
+                    <div className="h-4 w-full max-w-[200px] animate-pulse rounded-md bg-gray-200" />
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {/* Pagination skeleton */}
+      <div className="p-4 border-t flex justify-between items-center">
+        <div className="h-4 w-40 animate-pulse rounded-md bg-gray-200" />
+        <div className="flex gap-2">
+          <div className="h-9 w-20 animate-pulse rounded-md bg-gray-200" />
+          <div className="h-9 w-20 animate-pulse rounded-md bg-gray-200" />
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/loading/index.ts

@@ -0,0 +1,4 @@
+export { TableSkeleton } from './TableSkeleton'
+export type { TableSkeletonProps } from './TableSkeleton'
+export { DashboardSkeleton } from './DashboardSkeleton'
+export type { DashboardSkeletonProps } from './DashboardSkeleton'

package/src/components/safe-html.tsx

@@ -0,0 +1,18 @@
+import DOMPurify from 'isomorphic-dompurify';
+import { type ElementType, type HTMLAttributes } from 'react';
+
+interface SafeHtmlProps extends HTMLAttributes<HTMLElement> {
+  html: string;
+  as?: ElementType;
+}
+
+/**
+ * Renders user-supplied or external HTML safely by running it through DOMPurify.
+ * Strips script tags, event handlers, javascript: URLs, and other XSS vectors.
+ * Use this instead of dangerouslySetInnerHTML anywhere app content is rendered.
+ */
+export function SafeHtml({ html, as: Tag = 'div', ...props }: SafeHtmlProps) {
+  const sanitized = DOMPurify.sanitize(html, { ALLOW_DATA_ATTR: false });
+  // eslint-disable-next-line react/no-danger
+  return <Tag {...props} dangerouslySetInnerHTML={{ __html: sanitized }} />;
+}

package/src/components/states/EmptyState.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export interface EmptyStateAction {
+  label: string
+  onClick: () => void
+}
+
+export interface EmptyStateProps {
+  title: string
+  description?: string
+  action?: EmptyStateAction
+  className?: string
+}
+
+export function EmptyState({
+  title,
+  description,
+  action,
+  className,
+}: EmptyStateProps) {
+  return (
+    <div
+      className={cn(
+        'flex flex-col items-center justify-center py-12 px-4 text-center',
+        className
+      )}
+      role="status"
+      aria-live="polite"
+    >
+      <h3 className="text-xl font-semibold text-foreground mb-3">{title}</h3>
+      {description && (
+        <p className="text-base text-muted-foreground mb-8 max-w-md leading-relaxed">
+          {description}
+        </p>
+      )}
+      {action && (
+        <button
+          onClick={action.onClick}
+          className="inline-flex items-center justify-center rounded-md text-sm font-medium bg-primary text-primary-foreground shadow hover:bg-primary/90 h-9 px-4 py-2 transition-colors"
+          aria-label={action.label}
+        >
+          {action.label}
+        </button>
+      )}
+    </div>
+  )
+}

package/src/components/states/ErrorState.tsx

@@ -0,0 +1,76 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export interface ErrorStateProps {
+  title?: string
+  message: string
+  onRetry?: () => void
+  className?: string
+}
+
+export function ErrorState({
+  title = 'Something went wrong',
+  message,
+  onRetry,
+  className,
+}: ErrorStateProps) {
+  return (
+    <div
+      className={cn(
+        'flex flex-col items-center justify-center py-12 px-4 text-center',
+        className
+      )}
+      role="alert"
+      aria-live="assertive"
+    >
+      <div
+        className="w-16 h-16 mb-4 rounded-full bg-red-50 flex items-center justify-center"
+        aria-hidden="true"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="32"
+          height="32"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          className="text-red-500"
+        >
+          <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+          <line x1="12" y1="9" x2="12" y2="13" />
+          <line x1="12" y1="17" x2="12.01" y2="17" />
+        </svg>
+      </div>
+      <h3 className="text-lg font-semibold text-foreground mb-2">{title}</h3>
+      <p className="text-sm text-muted-foreground mb-6 max-w-sm">{message}</p>
+      {onRetry && (
+        <button
+          onClick={onRetry}
+          className="inline-flex items-center justify-center rounded-md text-sm font-medium border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground h-9 px-4 py-2 transition-colors"
+          aria-label="Retry loading content"
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="16"
+            height="16"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className="mr-2"
+            aria-hidden="true"
+          >
+            <path d="M21 12a9 9 0 1 1-9-9c2.52 0 4.93 1 6.74 2.74L21 8" />
+            <path d="M21 3v5h-5" />
+          </svg>
+          Try Again
+        </button>
+      )}
+    </div>
+  )
+}

package/src/components/states/index.ts

@@ -0,0 +1,4 @@
+export { ErrorState } from './ErrorState'
+export type { ErrorStateProps } from './ErrorState'
+export { EmptyState } from './EmptyState'
+export type { EmptyStateProps, EmptyStateAction } from './EmptyState'

package/src/components/toast/Toaster.tsx

@@ -0,0 +1,72 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { useToast, type ToastVariant } from './use-toast'
+
+const variantClasses: Record<ToastVariant, string> = {
+  default: 'bg-background border-border text-foreground',
+  destructive: 'bg-destructive border-destructive text-destructive-foreground',
+  success: 'bg-green-50 border-green-200 text-green-900',
+  warning: 'bg-yellow-50 border-yellow-200 text-yellow-900',
+  info: 'bg-blue-50 border-blue-200 text-blue-900',
+}
+
+export function Toaster() {
+  const { toasts, dismiss } = useToast()
+
+  if (toasts.length === 0) return null
+
+  return (
+    <div
+      className="fixed bottom-4 right-4 z-[100] flex flex-col gap-2 w-full max-w-sm"
+      role="region"
+      aria-label="Notifications"
+    >
+      {toasts.map((t) => (
+        <div
+          key={t.id}
+          className={cn(
+            'rounded-lg border p-4 shadow-lg transition-all animate-in slide-in-from-bottom-2 fade-in-0',
+            variantClasses[t.variant ?? 'default']
+          )}
+          role="status"
+          aria-live="polite"
+        >
+          <div className="flex items-start justify-between gap-2">
+            <div className="flex-1">
+              {t.title && (
+                <div className="text-sm font-semibold">{t.title}</div>
+              )}
+              {t.description && (
+                <div className="text-sm opacity-90 mt-1">{t.description}</div>
+              )}
+            </div>
+            <button
+              onClick={() => dismiss(t.id)}
+              className="shrink-0 rounded-sm opacity-70 hover:opacity-100 transition-opacity"
+              aria-label="Dismiss notification"
+            >
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="16"
+                height="16"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                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>
+            </button>
+          </div>
+          {t.action && <div className="mt-2">{t.action}</div>}
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/components/toast/index.ts

@@ -0,0 +1,5 @@
+export { useToast, toast, clearAllToasts } from './use-toast'
+export type { ToasterToast, ToastVariant } from './use-toast'
+export { Toaster } from './Toaster'
+export { useNotify, notify } from './use-notify'
+export type { NotifyOptions } from './use-notify'

package/src/components/toast/use-notify.ts

@@ -0,0 +1,45 @@
+import { toast } from './use-toast'
+
+export interface NotifyOptions {
+  title?: string
+  description?: string
+  duration?: number
+}
+
+function success(messageOrOptions: string | NotifyOptions) {
+  const opts =
+    typeof messageOrOptions === 'string'
+      ? { title: messageOrOptions }
+      : messageOrOptions
+  return toast({ variant: 'success', ...opts })
+}
+
+function error(messageOrOptions: string | NotifyOptions) {
+  const opts =
+    typeof messageOrOptions === 'string'
+      ? { title: messageOrOptions }
+      : messageOrOptions
+  return toast({ variant: 'destructive', ...opts })
+}
+
+function warning(messageOrOptions: string | NotifyOptions) {
+  const opts =
+    typeof messageOrOptions === 'string'
+      ? { title: messageOrOptions }
+      : messageOrOptions
+  return toast({ variant: 'warning', ...opts })
+}
+
+function info(messageOrOptions: string | NotifyOptions) {
+  const opts =
+    typeof messageOrOptions === 'string'
+      ? { title: messageOrOptions }
+      : messageOrOptions
+  return toast({ variant: 'info', ...opts })
+}
+
+export const notify = { success, error, warning, info }
+
+export function useNotify() {
+  return notify
+}

package/src/components/toast/use-toast.ts

@@ -0,0 +1,150 @@
+import * as React from 'react'
+
+const TOAST_LIMIT = 5
+const TOAST_AUTO_DISMISS = 5000
+
+export type ToastVariant = 'default' | 'destructive' | 'success' | 'warning' | 'info'
+
+export interface ToasterToast {
+  id: string
+  title?: string
+  description?: string
+  action?: React.ReactNode
+  variant?: ToastVariant
+  duration?: number
+}
+
+type Action =
+  | { type: 'ADD_TOAST'; toast: ToasterToast }
+  | { type: 'UPDATE_TOAST'; toast: Partial<ToasterToast> & { id: string } }
+  | { type: 'DISMISS_TOAST'; toastId?: string }
+  | { type: 'REMOVE_TOAST'; toastId?: string }
+
+interface State {
+  toasts: ToasterToast[]
+}
+
+const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>()
+
+function addToRemoveQueue(toastId: string, delay: number) {
+  if (toastTimeouts.has(toastId)) {
+    return
+  }
+
+  const timeout = setTimeout(() => {
+    toastTimeouts.delete(toastId)
+    dispatch({ type: 'REMOVE_TOAST', toastId })
+  }, delay)
+
+  toastTimeouts.set(toastId, timeout)
+}
+
+export function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'ADD_TOAST':
+      return {
+        ...state,
+        toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
+      }
+
+    case 'UPDATE_TOAST':
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === action.toast.id ? { ...t, ...action.toast } : t
+        ),
+      }
+
+    case 'DISMISS_TOAST': {
+      const { toastId } = action
+
+      if (toastId) {
+        addToRemoveQueue(toastId, 300)
+      } else {
+        state.toasts.forEach((t) => addToRemoveQueue(t.id, 300))
+      }
+
+      return state
+    }
+
+    case 'REMOVE_TOAST':
+      if (action.toastId === undefined) {
+        return { ...state, toasts: [] }
+      }
+      return {
+        ...state,
+        toasts: state.toasts.filter((t) => t.id !== action.toastId),
+      }
+  }
+}
+
+const listeners: Array<(state: State) => void> = []
+
+let memoryState: State = { toasts: [] }
+
+function dispatch(action: Action) {
+  memoryState = reducer(memoryState, action)
+  listeners.forEach((listener) => listener(memoryState))
+}
+
+let count = 0
+
+function genId() {
+  count = (count + 1) % Number.MAX_VALUE
+  return count.toString()
+}
+
+type ToastInput = Omit<ToasterToast, 'id'>
+
+function toast(props: ToastInput) {
+  const id = genId()
+  const duration = props.duration ?? TOAST_AUTO_DISMISS
+
+  dispatch({
+    type: 'ADD_TOAST',
+    toast: { ...props, id },
+  })
+
+  // Auto-dismiss
+  if (duration > 0) {
+    addToRemoveQueue(id, duration)
+  }
+
+  const update = (updateProps: Partial<ToasterToast>) =>
+    dispatch({ type: 'UPDATE_TOAST', toast: { ...updateProps, id } })
+
+  const dismiss = () => dispatch({ type: 'DISMISS_TOAST', toastId: id })
+
+  return { id, dismiss, update }
+}
+
+function clearAllToasts() {
+  // Clear all pending timeouts
+  toastTimeouts.forEach((timeout) => clearTimeout(timeout))
+  toastTimeouts.clear()
+  dispatch({ type: 'REMOVE_TOAST', toastId: undefined })
+}
+
+function useToast() {
+  const [state, setState] = React.useState<State>(memoryState)
+
+  React.useEffect(() => {
+    listeners.push(setState)
+    return () => {
+      const index = listeners.indexOf(setState)
+      if (index > -1) {
+        listeners.splice(index, 1)
+      }
+    }
+  }, [state])
+
+  return {
+    ...state,
+    toast,
+    dismiss: (toastId?: string) =>
+      dispatch({ type: 'DISMISS_TOAST', toastId }),
+    clear: clearAllToasts,
+  }
+}
+
+export { useToast, toast, clearAllToasts }

package/src/components/ui/api-error-boundary.tsx

@@ -0,0 +1,64 @@
+"use client"
+
+import * as React from "react"
+import { ErrorState } from "../states/ErrorState"
+
+interface ApiErrorBoundaryState {
+  hasError: boolean
+  error: Error | null
+}
+
+interface ApiErrorBoundaryProps {
+  children: React.ReactNode
+  /** Custom fallback to render on error. Receives error and reset function. */
+  fallback?: (props: { error: Error; reset: () => void }) => React.ReactNode
+  /** Called when the error boundary catches an error. */
+  onError?: (error: Error, info: React.ErrorInfo) => void
+}
+
+/**
+ * Error boundary for API-driven page content.
+ *
+ * Catches unhandled errors from children and renders ErrorState with a retry button.
+ *
+ * @example
+ * <ApiErrorBoundary>
+ *   <InvestorsTable />
+ * </ApiErrorBoundary>
+ */
+export class ApiErrorBoundary extends React.Component<
+  ApiErrorBoundaryProps,
+  ApiErrorBoundaryState
+> {
+  constructor(props: ApiErrorBoundaryProps) {
+    super(props)
+    this.state = { hasError: false, error: null }
+  }
+
+  static getDerivedStateFromError(error: Error): ApiErrorBoundaryState {
+    return { hasError: true, error }
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    this.props.onError?.(error, info)
+  }
+
+  reset = () => {
+    this.setState({ hasError: false, error: null })
+  }
+
+  render() {
+    if (this.state.hasError && this.state.error) {
+      if (this.props.fallback) {
+        return this.props.fallback({ error: this.state.error, reset: this.reset })
+      }
+      return (
+        <ErrorState
+          message={this.state.error.message || "An unexpected error occurred"}
+          onRetry={this.reset}
+        />
+      )
+    }
+    return this.props.children
+  }
+}

package/src/components/ui/feature-gate.tsx

@@ -0,0 +1,87 @@
+"use client"
+
+import * as React from "react"
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip"
+import { cn } from "../../lib/utils"
+
+export interface FeatureGateProps {
+  /** Whether the feature is available. When false, applies mode behavior. */
+  enabled: boolean
+  /**
+   * How to render when enabled=false:
+   * - 'disable' (default): renders children as disabled with a tooltip
+   * - 'hide': renders nothing
+   * - 'badge': renders children with a 'Coming soon' badge overlay
+   */
+  mode?: "disable" | "hide" | "badge"
+  /** Tooltip text shown in 'disable' mode. Defaults to 'Coming soon'. */
+  tooltip?: string
+  children: React.ReactNode
+  className?: string
+}
+
+/**
+ * Gates a UI element behind a feature flag.
+ *
+ * Use this to wrap any button, link, or UI section that is not yet implemented.
+ * This prevents shipping clickable elements with no handlers.
+ *
+ * @example
+ * // Disable a button with a tooltip
+ * <FeatureGate enabled={false}>
+ *   <Button onClick={handleReply}>Reply</Button>
+ * </FeatureGate>
+ *
+ * @example
+ * // Hide completely
+ * <FeatureGate enabled={false} mode="hide">
+ *   <Button>Archive</Button>
+ * </FeatureGate>
+ */
+export function FeatureGate({
+  enabled,
+  mode = "disable",
+  tooltip = "Coming soon",
+  children,
+  className,
+}: FeatureGateProps) {
+  if (enabled) {
+    return <>{children}</>
+  }
+
+  if (mode === "hide") {
+    return null
+  }
+
+  if (mode === "badge") {
+    return (
+      <div className={cn("relative inline-flex", className)}>
+        <div className="opacity-60 pointer-events-none select-none">{children}</div>
+        <span className="absolute -top-1.5 -right-1.5 rounded-full bg-muted text-muted-foreground text-[10px] font-medium px-1.5 py-0.5 leading-none border">
+          Soon
+        </span>
+      </div>
+    )
+  }
+
+  // mode === 'disable' (default): wrap in tooltip, disable interaction
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <span
+            className={cn("inline-flex cursor-not-allowed", className)}
+            aria-disabled="true"
+          >
+            <span className="pointer-events-none opacity-50 select-none">
+              {children}
+            </span>
+          </span>
+        </TooltipTrigger>
+        <TooltipContent>
+          <p>{tooltip}</p>
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}

package/src/components/ui/index.ts

@@ -22,3 +22,7 @@ export * from './table'
 export * from './tabs'
 export * from './textarea'
 export * from './tooltip'
+export * from './feature-gate'
+export * from './api-error-boundary'
+export * from './page-loader'
+export * from './query-provider'