@object-ui/react 0.5.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/react",
-  "version": "0.5.0",
+  "version": "3.0.0",
   "type": "module",
   "license": "MIT",
   "description": "React bindings and SchemaRenderer component for Object UI",
@@ -23,17 +23,19 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^0.9.1",
+    "@objectstack/spec": "^3.0.2",
     "react-hook-form": "^7.71.1",
-    "@object-ui/core": "0.5.0"
+    "@object-ui/core": "3.0.0",
+    "@object-ui/types": "3.0.0",
+    "@object-ui/i18n": "3.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.2.10",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "19.2.13",
+    "@types/react-dom": "19.2.3",
     "typescript": "^5.9.3"
   },
   "scripts": {

package/src/LazyPluginLoader.tsx

@@ -6,13 +6,83 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, { lazy, Suspense } from 'react';
+import React, { lazy, Suspense, Component } from 'react';
 
 export interface LazyPluginOptions {
   /**
    * Fallback component to show while loading
    */
   fallback?: React.ReactNode;
+  /**
+   * Number of retry attempts on load failure (default: 2)
+   */
+  retries?: number;
+  /**
+   * Delay in ms between retries (default: 1000)
+   */
+  retryDelay?: number;
+  /**
+   * Custom error fallback component
+   */
+  errorFallback?: React.ComponentType<{ error: Error; retry: () => void }>;
+}
+
+/**
+ * Error boundary for lazy-loaded plugins
+ */
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+class PluginErrorBoundary extends Component<
+  { fallback?: React.ComponentType<{ error: Error; retry: () => void }>; children: React.ReactNode },
+  ErrorBoundaryState
+> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  handleRetry = () => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    if (this.state.hasError && this.state.error) {
+      const FallbackComponent = this.props.fallback;
+      if (FallbackComponent) {
+        return <FallbackComponent error={this.state.error} retry={this.handleRetry} />;
+      }
+      return null;
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * Create a lazy-loaded import function with retry support
+ */
+function createRetryImport<P extends object>(
+  importFn: () => Promise<{ default: React.ComponentType<P> }>,
+  retries: number,
+  retryDelay: number,
+): () => Promise<{ default: React.ComponentType<P> }> {
+  return () => {
+    let attempt = 0;
+    const tryImport = (): Promise<{ default: React.ComponentType<P> }> =>
+      importFn().catch((err) => {
+        attempt++;
+        if (attempt <= retries) {
+          return new Promise((resolve) =>
+            setTimeout(() => resolve(tryImport()), retryDelay),
+          );
+        }
+        throw err;
+      });
+    return tryImport();
+  };
 }
 
 /**
@@ -34,19 +104,71 @@ export interface LazyPluginOptions {
  *   () => import('@object-ui/plugin-grid'),
  *   { fallback: <div>Loading grid...</div> }
  * );
+ * 
+ * // With retry and error handling
+ * const ObjectGrid = createLazyPlugin(
+ *   () => import('@object-ui/plugin-grid'),
+ *   {
+ *     retries: 3,
+ *     errorFallback: ({ error, retry }) => (
+ *       <div>
+ *         <p>Failed to load: {error.message}</p>
+ *         <button onClick={retry}>Retry</button>
+ *       </div>
+ *     ),
+ *   }
+ * );
  * ```
  */
 export function createLazyPlugin<P extends object = any>(
   importFn: () => Promise<{ default: React.ComponentType<P> }>,
   options?: LazyPluginOptions
 ): React.ComponentType<P> {
-  const LazyComponent = lazy(importFn);
+  const { retries = 2, retryDelay = 1000, errorFallback } = options || {};
+
+  const retryImport = retries > 0
+    ? createRetryImport(importFn, retries, retryDelay)
+    : importFn;
+
+  const LazyComponent = lazy(retryImport);
   
-  const PluginWrapper: React.FC<P> = (props) => (
-    <Suspense fallback={options?.fallback || null}>
-      <LazyComponent {...props} />
-    </Suspense>
-  );
+  const PluginWrapper: React.FC<P> = (props) => {
+    const content = (
+      <Suspense fallback={options?.fallback || null}>
+        <LazyComponent {...props} />
+      </Suspense>
+    );
+
+    if (errorFallback) {
+      return (
+        <PluginErrorBoundary fallback={errorFallback}>
+          {content}
+        </PluginErrorBoundary>
+      );
+    }
+
+    return content;
+  };
   
   return PluginWrapper;
 }
+
+/**
+ * Preload a plugin module without rendering it.
+ * Useful for preloading plugins that will be needed soon.
+ *
+ * @param importFn - Dynamic import function
+ * @returns Promise that resolves when the module is loaded
+ *
+ * @example
+ * ```tsx
+ * // Preload on hover
+ * const loadGrid = () => import('@object-ui/plugin-grid');
+ * <button onMouseEnter={() => preloadPlugin(loadGrid)}>Show Grid</button>
+ * ```
+ */
+export function preloadPlugin<T = unknown>(
+  importFn: () => Promise<T>,
+): Promise<T> {
+  return importFn();
+}

package/src/SchemaRenderer.tsx

@@ -6,9 +6,100 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, { forwardRef, useContext, useMemo } from 'react';
-import { SchemaNode, ComponentRegistry, ExpressionEvaluator } from '@object-ui/core';
+import React, { forwardRef, useContext, useMemo, Component } from 'react';
+import {
+  SchemaNode,
+  ComponentRegistry,
+  ExpressionEvaluator,
+  isObjectUIError,
+  type ObjectUIError,
+  ERROR_CODES,
+  debugLog,
+  debugTime,
+  debugTimeEnd,
+} from '@object-ui/core';
 import { SchemaRendererContext } from './context/SchemaRendererContext';
+import { resolveI18nLabel } from './utils/i18n';
+
+/**
+ * Extract AriaPropsSchema properties from a schema node and convert
+ * them to standard HTML ARIA attributes.
+ *
+ * @objectstack/spec AriaPropsSchema defines:
+ *   ariaLabel: string | I18nLabel (→ aria-label)
+ *   ariaDescribedBy: string (→ aria-describedby)
+ *   role: string (→ role)
+ */
+function resolveAriaProps(schema: Record<string, any>): Record<string, string | undefined> {
+  const aria: Record<string, string | undefined> = {};
+  if (schema.ariaLabel) {
+    aria['aria-label'] = resolveI18nLabel(schema.ariaLabel);
+  }
+  if (schema.ariaDescribedBy) {
+    aria['aria-describedby'] = schema.ariaDescribedBy;
+  }
+  if (schema.role) {
+    aria['role'] = schema.role;
+  }
+  return aria;
+}
+
+/**
+ * Per-component Error Boundary for SchemaRenderer.
+ * Catches render errors in individual components, preventing one broken
+ * component from crashing the entire page.
+ */
+interface SchemaErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class SchemaErrorBoundary extends Component<
+  { componentType?: string; children: React.ReactNode },
+  SchemaErrorBoundaryState
+> {
+  state: SchemaErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): SchemaErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  handleRetry = () => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    if (this.state.hasError && this.state.error) {
+      const error = this.state.error;
+      const isDev = process.env.NODE_ENV !== 'production';
+      const objuiError = isObjectUIError(error) ? error as ObjectUIError : null;
+
+      return (
+        <div className="p-4 border border-orange-400 rounded bg-orange-50 text-orange-700 my-2" role="alert">
+          <p className="font-medium">
+            Component{this.props.componentType ? ` "${this.props.componentType}"` : ''} failed to render
+          </p>
+          <p className="text-sm mt-1">{error.message}</p>
+          {isDev && objuiError?.code && (
+            <p className="text-xs mt-1 text-orange-500">
+              Error code: {objuiError.code}
+              {objuiError.details?.suggestion ? (
+                <span className="block mt-0.5">💡 {String(objuiError.details.suggestion)}</span>
+              ) : null}
+            </p>
+          )}
+          <button
+            onClick={this.handleRetry}
+            className="mt-2 text-sm underline hover:no-underline"
+          >
+            Retry
+          </button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
 
 export const SchemaRenderer = forwardRef<any, { schema: SchemaNode } & Record<string, any>>(({ schema, ...props }, _ref) => {
   const context = useContext(SchemaRendererContext);
@@ -48,13 +139,20 @@ export const SchemaRenderer = forwardRef<any, { schema: SchemaNode } & Record<st
   if (!evaluatedSchema) return null;
   // If schema is just a string, render it as text
   if (typeof evaluatedSchema === 'string') return <>{evaluatedSchema}</>;
+
+  debugLog('schema', 'Rendering schema node', { type: evaluatedSchema.type, id: evaluatedSchema.id });
   
   const Component = ComponentRegistry.get(evaluatedSchema.type);
 
   if (!Component) {
+    debugLog('schema', 'Component not found in registry', { type: evaluatedSchema.type });
+    const errorInfo = ERROR_CODES['OBJUI-001'];
     return (
-      <div className="p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2">
-        Unknown component type: <strong>{evaluatedSchema.type}</strong>
+      <div className="p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2" role="alert">
+        <p className="font-medium">Unknown component type: <strong>{evaluatedSchema.type}</strong></p>
+        {process.env.NODE_ENV !== 'production' && (
+          <p className="text-xs mt-1">💡 {errorInfo.suggestion} (OBJUI-001)</p>
+        )}
         <pre className="text-xs mt-2 overflow-auto">{JSON.stringify(evaluatedSchema, null, 2)}</pre>
       </div>
     );
@@ -78,14 +176,25 @@ export const SchemaRenderer = forwardRef<any, { schema: SchemaNode } & Record<st
     ...componentProps
   } = evaluatedSchema;
 
-  return React.createElement(Component, {
-    schema: evaluatedSchema,
-    ...componentProps,  // Spread non-metadata schema properties as props
-    ...(evaluatedSchema.props || {}),  // Override with explicit props if provided
-    className: evaluatedSchema.className,
-    'data-obj-id': evaluatedSchema.id,
-    'data-obj-type': evaluatedSchema.type,
-    ...props
-  });
+  // Extract AriaPropsSchema properties for accessibility
+  const ariaProps = resolveAriaProps(evaluatedSchema);
+
+  debugTime(`render:${evaluatedSchema.type}:${evaluatedSchema.id ?? 'anon'}`);
+  const rendered = (
+    <SchemaErrorBoundary componentType={evaluatedSchema.type}>
+      {React.createElement(Component, {
+        schema: evaluatedSchema,
+        ...componentProps,  // Spread non-metadata schema properties as props
+        ...(evaluatedSchema.props || {}),  // Override with explicit props if provided
+        ...ariaProps,  // Inject ARIA attributes from AriaPropsSchema
+        className: evaluatedSchema.className,
+        'data-obj-id': evaluatedSchema.id,
+        'data-obj-type': evaluatedSchema.type,
+        ...props
+      })}
+    </SchemaErrorBoundary>
+  );
+  debugTimeEnd(`render:${evaluatedSchema.type}:${evaluatedSchema.id ?? 'anon'}`);
+  return rendered;
 });
 SchemaRenderer.displayName = 'SchemaRenderer';

package/src/__tests__/LazyPluginLoader.test.tsx

@@ -9,7 +9,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import React from 'react';
-import { createLazyPlugin } from '../LazyPluginLoader';
+import { createLazyPlugin, preloadPlugin } from '../LazyPluginLoader';
 
 describe('createLazyPlugin', () => {
   it('should create a lazy-loaded component', async () => {
@@ -77,4 +77,100 @@ describe('createLazyPlugin', () => {
     // Restore console.error
     console.error = originalError;
   });
+
+  it('should preload a plugin without rendering', async () => {
+    const TestComponent = () => <div>Preloaded</div>;
+    const importFn = vi.fn(() => Promise.resolve({ default: TestComponent }));
+
+    const result = await preloadPlugin(importFn);
+
+    expect(importFn).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({ default: TestComponent });
+  });
+
+  it('should render errorFallback when component fails to load', async () => {
+    const originalError = console.error;
+    console.error = vi.fn();
+
+    const ErrorFallback = ({ error, retry }: { error: Error; retry: () => void }) => (
+      <div>
+        <span>Error: {error.message}</span>
+        <button onClick={retry}>Retry</button>
+      </div>
+    );
+
+    const LazyComponent = createLazyPlugin(
+      () => Promise.reject(new Error('chunk failed')),
+      { retries: 0, errorFallback: ErrorFallback }
+    );
+
+    render(<LazyComponent />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Error: chunk failed')).toBeInTheDocument();
+    });
+
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument();
+
+    console.error = originalError;
+  });
+
+  it('should not retry when retries=0', async () => {
+    const originalError = console.error;
+    console.error = vi.fn();
+
+    const importFn = vi.fn(() => Promise.reject(new Error('fail')));
+
+    const ErrorFallback = ({ error }: { error: Error; retry: () => void }) => (
+      <div>Error: {error.message}</div>
+    );
+
+    const LazyComponent = createLazyPlugin(importFn, {
+      retries: 0,
+      errorFallback: ErrorFallback,
+    });
+
+    render(<LazyComponent />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Error: fail')).toBeInTheDocument();
+    });
+
+    // Called only once — no retries
+    expect(importFn).toHaveBeenCalledTimes(1);
+
+    console.error = originalError;
+  });
+
+  it('should retry on failure then succeed', async () => {
+    const originalError = console.error;
+    console.error = vi.fn();
+
+    const TestComponent = () => <div>Success after retry</div>;
+
+    let callCount = 0;
+    const importFn = vi.fn(() => {
+      callCount++;
+      if (callCount <= 2) {
+        return Promise.reject(new Error('transient error'));
+      }
+      return Promise.resolve({ default: TestComponent as React.ComponentType });
+    });
+
+    const LazyComponent = createLazyPlugin(importFn, {
+      retries: 3,
+      retryDelay: 10,
+    });
+
+    render(<LazyComponent />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Success after retry')).toBeInTheDocument();
+    }, { timeout: 5000 });
+
+    // First call + 2 retries (fails) + 1 success = called 3 times
+    expect(importFn).toHaveBeenCalledTimes(3);
+
+    console.error = originalError;
+  });
 });

package/src/__tests__/SchemaRenderer.aria.test.tsx

@@ -0,0 +1,118 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { ComponentRegistry } from '@object-ui/core';
+import { SchemaRenderer } from '../SchemaRenderer';
+
+// A simple test component that forwards ARIA attributes
+const TestWidget: React.FC<any> = (props) => (
+  <div
+    data-testid="test-widget"
+    aria-label={props['aria-label']}
+    aria-describedby={props['aria-describedby']}
+    role={props['role']}
+  >
+    {props.content || 'Test'}
+  </div>
+);
+
+describe('SchemaRenderer AriaProps injection', () => {
+  beforeEach(() => {
+    ComponentRegistry.register('test-widget', TestWidget);
+  });
+
+  afterEach(() => {
+    ComponentRegistry.unregister?.('test-widget');
+  });
+
+  it('should inject aria-label from ariaLabel string', () => {
+    render(
+      <SchemaRenderer
+        schema={{
+          type: 'test-widget',
+          ariaLabel: 'Close dialog',
+        }}
+      />
+    );
+    const el = screen.getByTestId('test-widget');
+    expect(el).toHaveAttribute('aria-label', 'Close dialog');
+  });
+
+  it('should resolve ariaLabel from I18nLabel object', () => {
+    render(
+      <SchemaRenderer
+        schema={{
+          type: 'test-widget',
+          ariaLabel: { key: 'dialog.close', defaultValue: 'Close dialog' },
+        }}
+      />
+    );
+    const el = screen.getByTestId('test-widget');
+    expect(el).toHaveAttribute('aria-label', 'Close dialog');
+  });
+
+  it('should inject aria-describedby from ariaDescribedBy', () => {
+    render(
+      <SchemaRenderer
+        schema={{
+          type: 'test-widget',
+          ariaDescribedBy: 'help-text-1',
+        }}
+      />
+    );
+    const el = screen.getByTestId('test-widget');
+    expect(el).toHaveAttribute('aria-describedby', 'help-text-1');
+  });
+
+  it('should inject role from schema', () => {
+    render(
+      <SchemaRenderer
+        schema={{
+          type: 'test-widget',
+          role: 'navigation',
+        }}
+      />
+    );
+    const el = screen.getByTestId('test-widget');
+    expect(el).toHaveAttribute('role', 'navigation');
+  });
+
+  it('should inject all ARIA props together', () => {
+    render(
+      <SchemaRenderer
+        schema={{
+          type: 'test-widget',
+          ariaLabel: 'Main nav',
+          ariaDescribedBy: 'nav-desc',
+          role: 'navigation',
+        }}
+      />
+    );
+    const el = screen.getByTestId('test-widget');
+    expect(el).toHaveAttribute('aria-label', 'Main nav');
+    expect(el).toHaveAttribute('aria-describedby', 'nav-desc');
+    expect(el).toHaveAttribute('role', 'navigation');
+  });
+
+  it('should not inject ARIA attrs when not in schema', () => {
+    render(
+      <SchemaRenderer
+        schema={{
+          type: 'test-widget',
+          content: 'Hello',
+        }}
+      />
+    );
+    const el = screen.getByTestId('test-widget');
+    expect(el).not.toHaveAttribute('aria-label');
+    expect(el).not.toHaveAttribute('aria-describedby');
+  });
+});

package/src/__tests__/SchemaRenderer.errorBoundary.test.tsx

@@ -0,0 +1,114 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import React from 'react';
+import { ComponentRegistry } from '@object-ui/core';
+import { SchemaRenderer, SchemaErrorBoundary } from '../SchemaRenderer';
+
+// Suppress console.error from React error boundary during tests
+const originalConsoleError = console.error;
+beforeEach(() => {
+  console.error = vi.fn();
+});
+afterEach(() => {
+  console.error = originalConsoleError;
+});
+
+const CrashingWidget: React.FC = () => {
+  throw new Error('Widget exploded!');
+};
+
+const StableWidget: React.FC<any> = (props) => (
+  <div data-testid="stable-widget">{props.content || 'Stable'}</div>
+);
+
+describe('SchemaErrorBoundary', () => {
+  it('should render children normally when no error', () => {
+    render(
+      <SchemaErrorBoundary>
+        <div data-testid="child">OK</div>
+      </SchemaErrorBoundary>
+    );
+    expect(screen.getByTestId('child')).toBeInTheDocument();
+  });
+
+  it('should catch render errors and display fallback', () => {
+    render(
+      <SchemaErrorBoundary componentType="crashing-widget">
+        <CrashingWidget />
+      </SchemaErrorBoundary>
+    );
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+    expect(screen.getByText(/failed to render/i)).toBeInTheDocument();
+    expect(screen.getByText(/"crashing-widget"/)).toBeInTheDocument();
+    expect(screen.getByText('Widget exploded!')).toBeInTheDocument();
+  });
+
+  it('should display retry button that resets the error', () => {
+    render(
+      <SchemaErrorBoundary>
+        <CrashingWidget />
+      </SchemaErrorBoundary>
+    );
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+    const retryButton = screen.getByText('Retry');
+    expect(retryButton).toBeInTheDocument();
+  });
+
+  it('should work without componentType prop', () => {
+    render(
+      <SchemaErrorBoundary>
+        <CrashingWidget />
+      </SchemaErrorBoundary>
+    );
+    expect(screen.getByText(/failed to render/i)).toBeInTheDocument();
+  });
+});
+
+describe('SchemaRenderer error boundary integration', () => {
+  beforeEach(() => {
+    ComponentRegistry.register('crashing-widget', CrashingWidget);
+    ComponentRegistry.register('stable-widget', StableWidget);
+  });
+
+  afterEach(() => {
+    ComponentRegistry.unregister?.('crashing-widget');
+    ComponentRegistry.unregister?.('stable-widget');
+  });
+
+  it('should catch errors from a crashing component', () => {
+    render(
+      <SchemaRenderer schema={{ type: 'crashing-widget' }} />
+    );
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+    expect(screen.getByText('Widget exploded!')).toBeInTheDocument();
+  });
+
+  it('should not affect stable components', () => {
+    render(
+      <SchemaRenderer schema={{ type: 'stable-widget', content: 'Hello' }} />
+    );
+    expect(screen.getByTestId('stable-widget')).toBeInTheDocument();
+    expect(screen.getByText('Hello')).toBeInTheDocument();
+  });
+
+  it('should isolate crashes between multiple renderers', () => {
+    render(
+      <div>
+        <SchemaRenderer schema={{ type: 'crashing-widget' }} />
+        <SchemaRenderer schema={{ type: 'stable-widget', content: 'Still works' }} />
+      </div>
+    );
+    // Crashing one should not affect the other
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+    expect(screen.getByTestId('stable-widget')).toBeInTheDocument();
+    expect(screen.getByText('Still works')).toBeInTheDocument();
+  });
+});