@object-ui/react 2.0.0 → 3.0.0

package/dist/hooks/useViewTransition.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+export interface ViewTransitionConfig {
+    /** Enable view transitions (default: true) */
+    enabled?: boolean;
+    /** Fallback animation class when View Transitions API is unsupported */
+    fallbackClass?: string;
+    /** Transition duration in ms (default: 300) */
+    duration?: number;
+    /** Called before transition starts */
+    onTransitionStart?: () => void;
+    /** Called after transition completes */
+    onTransitionEnd?: () => void;
+}
+export interface ViewTransitionResult {
+    /** Whether the View Transitions API is supported */
+    isSupported: boolean;
+    /** Whether a transition is currently in progress */
+    isTransitioning: boolean;
+    /** Execute a callback with a view transition */
+    startTransition: (callback: () => void | Promise<void>) => Promise<void>;
+    /** CSS class to apply during transitions */
+    transitionClass: string;
+}
+/**
+ * Hook for integrating with the browser View Transitions API.
+ *
+ * Uses the native `document.startViewTransition()` when available and
+ * falls back to a temporary CSS class for animation when unsupported.
+ * Respects `prefers-reduced-motion`.
+ *
+ * @example
+ * ```tsx
+ * function ViewSwitcher({ onViewChange }: { onViewChange: (v: string) => void }) {
+ *   const { startTransition, transitionClass, isTransitioning } = useViewTransition();
+ *
+ *   const handleChange = (view: string) => {
+ *     startTransition(() => onViewChange(view));
+ *   };
+ *
+ *   return (
+ *     <div className={transitionClass}>
+ *       ...
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useViewTransition(config?: ViewTransitionConfig): ViewTransitionResult;

package/dist/hooks/useViewTransition.js

@@ -0,0 +1,83 @@
+/**
+ * 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 { useState, useCallback, useMemo } from 'react';
+import { useReducedMotion } from './useReducedMotion';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_DURATION = 300;
+const DEFAULT_FALLBACK_CLASS = 'oui-view-transition-fallback';
+function supportsViewTransitions() {
+    return (typeof document !== 'undefined' &&
+        'startViewTransition' in document);
+}
+// ---------------------------------------------------------------------------
+// useViewTransition hook
+// ---------------------------------------------------------------------------
+/**
+ * Hook for integrating with the browser View Transitions API.
+ *
+ * Uses the native `document.startViewTransition()` when available and
+ * falls back to a temporary CSS class for animation when unsupported.
+ * Respects `prefers-reduced-motion`.
+ *
+ * @example
+ * ```tsx
+ * function ViewSwitcher({ onViewChange }: { onViewChange: (v: string) => void }) {
+ *   const { startTransition, transitionClass, isTransitioning } = useViewTransition();
+ *
+ *   const handleChange = (view: string) => {
+ *     startTransition(() => onViewChange(view));
+ *   };
+ *
+ *   return (
+ *     <div className={transitionClass}>
+ *       ...
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useViewTransition(config = {}) {
+    const { enabled = true, fallbackClass = DEFAULT_FALLBACK_CLASS, duration = DEFAULT_DURATION, onTransitionStart, onTransitionEnd, } = config;
+    const reducedMotion = useReducedMotion();
+    const [isTransitioning, setIsTransitioning] = useState(false);
+    const isSupported = useMemo(() => supportsViewTransitions(), []);
+    const startTransition = useCallback(async (callback) => {
+        // Skip transition when disabled or user prefers reduced motion
+        if (!enabled || reducedMotion) {
+            await callback();
+            return;
+        }
+        onTransitionStart?.();
+        setIsTransitioning(true);
+        try {
+            if (isSupported) {
+                // Use native View Transitions API
+                const transition = document.startViewTransition(callback);
+                await transition.finished;
+            }
+            else {
+                // Fallback: apply class, run callback, remove class after duration
+                await callback();
+                await new Promise((resolve) => setTimeout(resolve, duration));
+            }
+        }
+        finally {
+            setIsTransitioning(false);
+            onTransitionEnd?.();
+        }
+    }, [enabled, reducedMotion, isSupported, duration, onTransitionStart, onTransitionEnd]);
+    const transitionClass = isTransitioning && !isSupported ? fallbackClass : '';
+    return {
+        isSupported,
+        isTransitioning,
+        startTransition,
+        transitionClass,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/react",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "type": "module",
   "license": "MIT",
   "description": "React bindings and SchemaRenderer component for Object UI",
@@ -23,19 +23,19 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^2.0.7",
+    "@objectstack/spec": "^3.0.2",
     "react-hook-form": "^7.71.1",
-    "@object-ui/core": "2.0.0",
-    "@object-ui/i18n": "2.0.0",
-    "@object-ui/types": "2.0.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.13",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "19.2.13",
+    "@types/react-dom": "19.2.3",
     "typescript": "^5.9.3"
   },
   "scripts": {

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__/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();
+  });
+});