@geenius/tools 0.1.0

package/packages/errors/react/README.md

@@ -0,0 +1 @@
+# ✦ @geenius-tools/errors-react\n\n> React error handling UI — boundaries, displays, analytics dashboard, hooks & utilities\n\n---\n\n## Overview\nBuilt with Steve Jobs-level minimalism and Jony Ive-level craftsmanship, this package is designed to deliver unparalleled developer experience (DX) and rock-solid performance.\n\n## Installation\n\n```bash\npnpm add @geenius-tools/errors-react\n```\n\n## Usage\n\n```typescript\nimport { init } from '@geenius-tools/errors-react';\n\n// Initialize the module with absolute precision\ninit({\n  mode: 'premium',\n});\n```\n\n## Architecture\n- **Zero-config**: It just works.\n- **Strictly Typed**: Fully written in TypeScript for flawless IntelliSense.\n- **Framework Agnostic**: seamlessly integrates into the Geenius ecosystem.\n\n---\n\n*Designed by Antigravity HQ*\n

package/packages/errors/react/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@geenius-tools/errors-react",
+  "version": "0.1.0",
+  "private": false,
+  "description": "React error handling UI \u2014 boundaries, displays, analytics dashboard, hooks & utilities",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics.d.ts",
+      "import": "./dist/analytics.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@geenius-tools/convex": "workspace:*"
+  },
+  "devDependencies": {
+    "@geenius-ui/react": "workspace:*",
+    "@tanstack/react-query": "^5.91.3",
+    "@tanstack/react-router": "^1.168.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "convex": "^1.34.0",
+    "lucide-react": "^0.577.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3"
+  },
+  "peerDependencies": {
+    "lucide-react": ">=0.300.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@geenius-ui/react": {
+      "optional": true
+    },
+    "@tanstack/react-router": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "convex": {
+      "optional": true
+    }
+  },
+  "author": "Antigravity HQ",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/errors/react/src/analytics.ts

@@ -0,0 +1,16 @@
+// @geenius-tools/errors-react/analytics
+// Convex-dependent error analytics (separate entry point)
+// Requires: convex, @tanstack/react-query as peer deps
+
+// Re-export analytics types
+export type {
+    ErrorAnalyticsFilters,
+    ErrorAnalyticsEntry,
+    ErrorMute,
+    ErrorTrend,
+} from './types'
+
+// Note: ErrorAnalyticsService, useErrorAnalytics hooks, and ErrorAnalyticsDashboard
+// are tightly bound to a specific Convex API shape (api.library.system.errorAnalytics).
+// They will be added here once we define a generic analytics adapter pattern.
+// For now, consumers should copy these from the boilerplate and adapt to their Convex schema.

package/packages/errors/react/src/components/ErrorBoundary.tsx

@@ -0,0 +1,248 @@
+// @geenius-tools/errors-react — src/components/ErrorBoundary.tsx
+
+import { Component, ReactNode, ErrorInfo } from 'react'
+import { AlertTriangle } from 'lucide-react'
+
+export interface ErrorBoundaryProps {
+    children: ReactNode
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode)
+    onError?: (error: Error, errorInfo: ErrorInfo) => void
+    name?: string
+}
+
+interface ErrorBoundaryState {
+    hasError: boolean
+    error: Error | null
+}
+
+/**
+ * Error Boundary Component
+ *
+ * React error boundary for catching component-level errors.
+ * Prevents entire app from crashing when a component throws an error.
+ *
+ * @example
+ * <ErrorBoundary name="Dashboard">
+ *   <Dashboard />
+ * </ErrorBoundary>
+ */
+export class ErrorBoundary extends Component<
+    ErrorBoundaryProps,
+    ErrorBoundaryState
+> {
+    constructor(props: ErrorBoundaryProps) {
+        super(props)
+        this.state = {
+            hasError: false,
+            error: null,
+        }
+    }
+
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+        return { hasError: true, error }
+    }
+
+    componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+        try {
+            if (typeof globalThis !== 'undefined' && (globalThis as any).process?.env?.NODE_ENV === 'development') {
+                console.error('ErrorBoundary caught error:', error, errorInfo)
+            }
+        } catch { /* ignore */ }
+        this.props.onError?.(error, errorInfo)
+    }
+
+    reset = () => {
+        this.setState({ hasError: false, error: null })
+    }
+
+    render() {
+        if (this.state.hasError && this.state.error) {
+            if (this.props.fallback) {
+                if (typeof this.props.fallback === 'function') {
+                    return this.props.fallback(this.state.error, this.reset)
+                }
+                return this.props.fallback
+            }
+
+            return (
+                <DefaultErrorFallback
+                    error={this.state.error}
+                    reset={this.reset}
+                    boundaryName={this.props.name}
+                />
+            )
+        }
+
+        return this.props.children
+    }
+}
+
+function DefaultErrorFallback({
+    error,
+    reset,
+    boundaryName,
+}: {
+    error: Error
+    reset: () => void
+    boundaryName?: string
+}) {
+    let isDevelopment = false
+    try {
+        isDevelopment = typeof globalThis !== 'undefined' && (globalThis as any).process?.env?.NODE_ENV === 'development'
+    } catch { /* ignore */ }
+
+    return (
+        <div style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            minHeight: '400px',
+            padding: '24px',
+        }}>
+            <div style={{
+                maxWidth: '28rem',
+                width: '100%',
+                borderRadius: '8px',
+                border: '1px solid var(--border, #e5e7eb)',
+                backgroundColor: 'var(--panel, #fff)',
+                padding: '24px',
+                display: 'flex',
+                flexDirection: 'column',
+                gap: '16px',
+            }}>
+                <div style={{ display: 'flex', alignItems: 'flex-start', gap: '16px' }}>
+                    <div style={{
+                        height: '48px',
+                        width: '48px',
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        borderRadius: '12px',
+                        backgroundColor: 'rgba(239, 68, 68, 0.1)',
+                        flexShrink: 0,
+                    }}>
+                        <AlertTriangle
+                            style={{ height: '24px', width: '24px', color: '#dc2626' }}
+                            aria-hidden
+                        />
+                    </div>
+
+                    <div style={{ flex: 1, display: 'flex', flexDirection: 'column', gap: '8px' }}>
+                        <div>
+                            <p style={{
+                                fontSize: '12px',
+                                fontWeight: 600,
+                                textTransform: 'uppercase',
+                                letterSpacing: '0.18em',
+                                color: '#dc2626',
+                                margin: 0,
+                            }}>
+                                Component Error
+                            </p>
+                            {boundaryName && (
+                                <p style={{
+                                    fontSize: '12px',
+                                    color: 'var(--muted-foreground, #6b7280)',
+                                    marginTop: '4px',
+                                    margin: '4px 0 0',
+                                }}>
+                                    in {boundaryName}
+                                </p>
+                            )}
+                        </div>
+                        <h2 style={{
+                            fontSize: '20px',
+                            fontWeight: 700,
+                            color: 'var(--foreground, #111)',
+                            margin: 0,
+                        }}>
+                            Something went wrong
+                        </h2>
+                        <p style={{
+                            fontSize: '14px',
+                            color: 'var(--muted-foreground, #6b7280)',
+                            margin: 0,
+                        }}>
+                            An error occurred in this component. Try again or contact support.
+                        </p>
+                    </div>
+                </div>
+
+                {isDevelopment && (
+                    <div style={{
+                        borderRadius: '8px',
+                        border: '1px solid var(--border, #e5e7eb)',
+                        backgroundColor: 'var(--bg-muted, #f9fafb)',
+                        padding: '12px',
+                    }}>
+                        <p style={{
+                            fontSize: '12px',
+                            fontWeight: 600,
+                            margin: '0 0 8px',
+                            opacity: 0.8,
+                        }}>
+                            Error details (development only)
+                        </p>
+                        <p style={{
+                            fontSize: '12px',
+                            fontFamily: 'monospace',
+                            color: '#dc2626',
+                            margin: '0 0 8px',
+                        }}>
+                            {error.message}
+                        </p>
+                        {error.stack && (
+                            <pre style={{
+                                fontSize: '12px',
+                                fontFamily: 'monospace',
+                                color: 'var(--muted-foreground, #6b7280)',
+                                whiteSpace: 'pre-wrap',
+                                wordBreak: 'break-word',
+                                maxHeight: '160px',
+                                overflow: 'auto',
+                                margin: 0,
+                            }}>
+                                {error.stack}
+                            </pre>
+                        )}
+                    </div>
+                )}
+
+                <div style={{ display: 'flex', gap: '12px' }}>
+                    <button
+                        onClick={reset}
+                        style={{
+                            flex: 1,
+                            padding: '8px 16px',
+                            borderRadius: '6px',
+                            border: 'none',
+                            backgroundColor: 'var(--primary, #3b82f6)',
+                            color: '#fff',
+                            fontWeight: 500,
+                            cursor: 'pointer',
+                            fontSize: '14px',
+                        }}
+                    >
+                        Try Again
+                    </button>
+                    <button
+                        onClick={() => window.location.reload()}
+                        style={{
+                            flex: 1,
+                            padding: '8px 16px',
+                            borderRadius: '6px',
+                            border: '1px solid var(--border, #e5e7eb)',
+                            backgroundColor: 'transparent',
+                            color: 'var(--foreground, #111)',
+                            fontWeight: 500,
+                            cursor: 'pointer',
+                            fontSize: '14px',
+                        }}
+                    >
+                        Reload Page
+                    </button>
+                </div>
+            </div>
+        </div>
+    )
+}

package/packages/errors/react/src/components/ErrorDisplay.tsx

@@ -0,0 +1,328 @@
+// @geenius-tools/errors-react — src/components/ErrorDisplay.tsx
+
+import { FC } from 'react'
+import { RefreshCw } from 'lucide-react'
+import {
+    extractAppError,
+    extractRequestId,
+    normalizeErrorMessage,
+} from '../utils/extractAppError'
+import {
+    getErrorTitle,
+    getFallbackMessage,
+    getErrorAction,
+} from '../utils/errorMessages'
+import {
+    ERROR_CODE_ICONS,
+    ERROR_CODE_BG_COLORS,
+    ERROR_CODE_COLORS,
+} from '../constants'
+import { ValidationErrors } from './ValidationErrors'
+import type { ErrorDisplayVariant } from '../types'
+
+export interface ErrorDisplayProps {
+    error: unknown
+    onRetry?: () => void
+    variant?: ErrorDisplayVariant
+    compact?: boolean
+    showRequestId?: boolean
+    customAction?: {
+        label: string
+        onClick?: () => void
+        href?: string
+    }
+    className?: string
+}
+
+/**
+ * Error Display Component
+ *
+ * Displays errors with appropriate styling based on error code.
+ * Integrates tightly with backend error structure.
+ *
+ * @example
+ * <ErrorDisplay
+ *   error={error}
+ *   onRetry={() => refetch()}
+ *   showRequestId
+ * />
+ */
+export const ErrorDisplay: FC<ErrorDisplayProps> = ({
+    error,
+    onRetry,
+    variant = 'card',
+    compact = false,
+    showRequestId = false,
+    customAction,
+    className = '',
+}) => {
+    const appError = extractAppError(error)
+    const requestId = extractRequestId(error)
+
+    if (!appError) {
+        return (
+            <GenericErrorDisplay
+                error={error}
+                onRetry={onRetry}
+                compact={compact}
+            />
+        )
+    }
+
+    const Icon = ERROR_CODE_ICONS[appError.code]
+    const colorClass = ERROR_CODE_COLORS[appError.code]
+    const bgClass = ERROR_CODE_BG_COLORS[appError.code]
+    const title = getErrorTitle(appError.code)
+    const message = appError.message ?? getFallbackMessage(appError.code)
+    const action = getErrorAction(appError.code)
+
+    if (variant === 'inline') {
+        return (
+            <div className={className} style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: '8px',
+                padding: compact ? '8px' : '12px',
+                borderRadius: '8px',
+                border: '1px solid var(--border, #e5e7eb)',
+            }}>
+                {Icon && <Icon style={{ height: '16px', width: '16px', flexShrink: 0 }} className={colorClass} />}
+                <span style={{ fontSize: '14px', color: 'var(--foreground, #111)' }}>
+                    {message}
+                </span>
+                {onRetry && (
+                    <button
+                        onClick={onRetry}
+                        style={{
+                            marginLeft: 'auto',
+                            padding: '4px',
+                            border: 'none',
+                            background: 'none',
+                            cursor: 'pointer',
+                            borderRadius: '4px',
+                        }}
+                        title="Retry"
+                    >
+                        <RefreshCw style={{ height: '14px', width: '14px' }} />
+                    </button>
+                )}
+            </div>
+        )
+    }
+
+    // Card variant (default)
+    return (
+        <div className={className} style={{
+            borderRadius: '8px',
+            border: '1px solid var(--border, #e5e7eb)',
+            backgroundColor: 'var(--panel, #fff)',
+            overflow: 'hidden',
+        }}>
+            <div style={{
+                padding: compact ? '16px' : '24px',
+                display: 'flex',
+                flexDirection: 'column',
+                gap: '16px',
+            }}>
+                <div style={{ display: 'flex', alignItems: 'flex-start', gap: '16px' }}>
+                    {Icon && (
+                        <div
+                            className={bgClass}
+                            style={{
+                                height: compact ? '32px' : '40px',
+                                width: compact ? '32px' : '40px',
+                                display: 'flex',
+                                alignItems: 'center',
+                                justifyContent: 'center',
+                                borderRadius: '10px',
+                                flexShrink: 0,
+                            }}
+                        >
+                            <Icon
+                                className={colorClass}
+                                style={{
+                                    height: compact ? '16px' : '20px',
+                                    width: compact ? '16px' : '20px',
+                                }}
+                            />
+                        </div>
+                    )}
+
+                    <div style={{ flex: 1, minWidth: 0 }}>
+                        <h3 style={{
+                            fontSize: compact ? '14px' : '16px',
+                            fontWeight: 600,
+                            color: 'var(--foreground, #111)',
+                            margin: '0 0 4px',
+                        }}>
+                            {title}
+                        </h3>
+                        <p style={{
+                            fontSize: compact ? '13px' : '14px',
+                            color: 'var(--muted-foreground, #6b7280)',
+                            margin: 0,
+                        }}>
+                            {message}
+                        </p>
+                    </div>
+                </div>
+
+                {appError.validationErrors && appError.validationErrors.length > 0 && (
+                    <ValidationErrors errors={appError.validationErrors} />
+                )}
+
+                {showRequestId && requestId && (
+                    <p style={{
+                        fontSize: '12px',
+                        fontFamily: 'monospace',
+                        color: 'var(--muted-foreground, #6b7280)',
+                        margin: 0,
+                    }}>
+                        Request ID: {requestId}
+                    </p>
+                )}
+
+                <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+                    {onRetry && (
+                        <button
+                            onClick={onRetry}
+                            style={{
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: '6px',
+                                padding: '6px 12px',
+                                borderRadius: '6px',
+                                border: '1px solid var(--border, #e5e7eb)',
+                                backgroundColor: 'transparent',
+                                cursor: 'pointer',
+                                fontSize: '13px',
+                                fontWeight: 500,
+                            }}
+                        >
+                            <RefreshCw style={{ height: '14px', width: '14px' }} />
+                            Retry
+                        </button>
+                    )}
+                    {customAction && (
+                        customAction.href ? (
+                            <a
+                                href={customAction.href}
+                                style={{
+                                    padding: '6px 12px',
+                                    borderRadius: '6px',
+                                    border: '1px solid var(--border, #e5e7eb)',
+                                    backgroundColor: 'transparent',
+                                    textDecoration: 'none',
+                                    fontSize: '13px',
+                                    fontWeight: 500,
+                                    color: 'var(--foreground, #111)',
+                                }}
+                            >
+                                {customAction.label}
+                            </a>
+                        ) : (
+                            <button
+                                onClick={customAction.onClick}
+                                style={{
+                                    padding: '6px 12px',
+                                    borderRadius: '6px',
+                                    border: '1px solid var(--border, #e5e7eb)',
+                                    backgroundColor: 'transparent',
+                                    cursor: 'pointer',
+                                    fontSize: '13px',
+                                    fontWeight: 500,
+                                }}
+                            >
+                                {customAction.label}
+                            </button>
+                        )
+                    )}
+                    {!onRetry && !customAction && (
+                        <p style={{
+                            fontSize: '13px',
+                            color: 'var(--muted-foreground, #6b7280)',
+                            margin: 0,
+                        }}>
+                            {action}
+                        </p>
+                    )}
+                </div>
+            </div>
+        </div>
+    )
+}
+
+/**
+ * Generic error display for non-app errors
+ */
+function GenericErrorDisplay({
+    error,
+    onRetry,
+    compact,
+}: {
+    error: unknown
+    onRetry?: () => void
+    compact: boolean
+}) {
+    const message = normalizeErrorMessage(error)
+
+    return (
+        <div style={{
+            borderRadius: '8px',
+            border: '1px solid var(--border, #e5e7eb)',
+            backgroundColor: 'var(--panel, #fff)',
+            padding: compact ? '16px' : '24px',
+        }}>
+            <div style={{ display: 'flex', alignItems: 'flex-start', gap: '12px' }}>
+                <div style={{
+                    height: '32px',
+                    width: '32px',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    borderRadius: '8px',
+                    backgroundColor: 'rgba(239, 68, 68, 0.1)',
+                    flexShrink: 0,
+                }}>
+                    <RefreshCw style={{ height: '16px', width: '16px', color: '#dc2626' }} />
+                </div>
+                <div style={{ flex: 1 }}>
+                    <h3 style={{
+                        fontSize: '14px',
+                        fontWeight: 600,
+                        color: 'var(--foreground, #111)',
+                        margin: '0 0 4px',
+                    }}>
+                        Error
+                    </h3>
+                    <p style={{
+                        fontSize: '14px',
+                        color: 'var(--muted-foreground, #6b7280)',
+                        margin: 0,
+                    }}>
+                        {message}
+                    </p>
+                </div>
+                {onRetry && (
+                    <button
+                        onClick={onRetry}
+                        style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: '6px',
+                            padding: '6px 12px',
+                            borderRadius: '6px',
+                            border: '1px solid var(--border, #e5e7eb)',
+                            backgroundColor: 'transparent',
+                            cursor: 'pointer',
+                            fontSize: '13px',
+                        }}
+                    >
+                        <RefreshCw style={{ height: '14px', width: '14px' }} />
+                        Retry
+                    </button>
+                )}
+            </div>
+        </div>
+    )
+}