@object-ui/react 3.3.0 → 3.3.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @object-ui/react
 
+## 3.3.1
+
+### Patch Changes
+
+- @object-ui/types@3.3.1
+- @object-ui/core@3.3.1
+- @object-ui/i18n@3.3.1
+- @object-ui/data-objectstack@3.3.1
+
 ## 3.3.0
 
 ### Patch Changes

package/README.md

@@ -162,6 +162,26 @@ The `previewMode` object contains:
 
 See [full documentation](https://objectui.org/api/react) for detailed API reference.
 
+<!-- release-metadata:v3.3.0 -->
+
+## Compatibility
+
+- **React:** 18.x or 19.x
+- **Node.js:** ≥ 18
+- **TypeScript:** ≥ 5.0 (strict mode)
+- **`@objectstack/spec`:** ^3.3.0
+- **`@objectstack/client`:** ^3.3.0
+- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
+
+## Links
+
+- 📚 [Documentation](https://www.objectui.org/docs/packages/react)
+- 📦 [npm package](https://www.npmjs.com/package/@object-ui/react)
+- 📝 [Changelog](./CHANGELOG.md)
+- 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)
+- 🤝 [Contributing Guide](https://github.com/objectstack-ai/objectui/blob/main/CONTRIBUTING.md)
+- 🗺️ [Roadmap](https://github.com/objectstack-ai/objectui/blob/main/ROADMAP.md)
+
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).

package/dist/context/AppShellContext.d.ts

@@ -0,0 +1,26 @@
+import type { ObjectStackAdapter } from '@object-ui/data-objectstack';
+export declare const AdapterCtx: import("react").Context<ObjectStackAdapter<unknown> | null>;
+export declare function useAdapter(): ObjectStackAdapter | null;
+export interface MetadataState {
+    apps: any[];
+    objects: any[];
+    dashboards: any[];
+    reports: any[];
+    pages: any[];
+    loading: boolean;
+    error: Error | null;
+}
+export interface MetadataContextValue extends MetadataState {
+    refresh: (type?: string) => Promise<void>;
+    invalidate: (type: string, name?: string) => void;
+    ensureType: (type: string) => Promise<any[]>;
+    getItem: (type: string, name: string) => Promise<any | null>;
+    getItemsByType: (type: string) => any[];
+}
+export declare const MetadataCtx: import("react").Context<MetadataContextValue | null>;
+export declare function useMetadata(): MetadataContextValue;
+export declare function useMetadataItem(type: string, name: string | undefined | null): {
+    item: any | null;
+    loading: boolean;
+    error: Error | null;
+};

package/dist/context/AppShellContext.js

@@ -0,0 +1,67 @@
+import { createContext, useContext, useEffect, useState } from 'react';
+// ---------------------------------------------------------------------------
+// AdapterContext
+// ---------------------------------------------------------------------------
+export const AdapterCtx = createContext(null);
+export function useAdapter() {
+    return useContext(AdapterCtx);
+}
+export const MetadataCtx = createContext(null);
+export function useMetadata() {
+    const ctx = useContext(MetadataCtx);
+    if (!ctx) {
+        // Graceful fallback: when a consumer is rendered outside a MetadataProvider
+        // (common in unit tests that only need to assert on rendering), return an
+        // empty no-op implementation rather than crash. Production code paths
+        // should always wrap in <MetadataProvider>.
+        return {
+            apps: [],
+            objects: [],
+            dashboards: [],
+            reports: [],
+            pages: [],
+            loading: false,
+            error: null,
+            refresh: async () => { },
+            invalidate: () => { },
+            ensureType: async () => [],
+            getItem: async () => null,
+            getItemsByType: () => [],
+        };
+    }
+    return ctx;
+}
+export function useMetadataItem(type, name) {
+    const { getItem } = useMetadata();
+    const [state, setState] = useState({
+        item: null,
+        loading: !!name,
+        error: null,
+    });
+    useEffect(() => {
+        if (!name) {
+            setState({ item: null, loading: false, error: null });
+            return;
+        }
+        let cancelled = false;
+        setState(s => ({ ...s, loading: true, error: null }));
+        getItem(type, name)
+            .then(item => {
+            if (!cancelled)
+                setState({ item, loading: false, error: null });
+        })
+            .catch(err => {
+            if (!cancelled) {
+                setState({
+                    item: null,
+                    loading: false,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [type, name, getItem]);
+    return state;
+}

package/dist/context/index.d.ts

@@ -1,12 +1,6 @@
-/**
- * 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 * from './SchemaRendererContext';
 export * from './ActionContext';
 export * from './ThemeContext';
 export * from './NotificationContext';
 export * from './DndContext';
+export * from './AppShellContext';

package/dist/context/index.js

@@ -1,12 +1,6 @@
-/**
- * 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 * from './SchemaRendererContext';
 export * from './ActionContext';
 export * from './ThemeContext';
 export * from './NotificationContext';
 export * from './DndContext';
+export * from './AppShellContext';

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@object-ui/react",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "type": "module",
   "license": "MIT",
   "description": "React bindings and SchemaRenderer component for Object UI",
-  "homepage": "https://www.objectui.org",
+  "homepage": "https://www.objectui.org/docs/packages/react",
   "repository": {
     "type": "git",
-    "url": "https://github.com/objectstack-ai/objectui.git",
+    "url": "git+https://github.com/objectstack-ai/objectui.git",
     "directory": "packages/react"
   },
   "bugs": {
@@ -24,11 +24,12 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^4.0.3",
-    "react-hook-form": "^7.72.1",
-    "@object-ui/core": "3.3.0",
-    "@object-ui/i18n": "3.3.0",
-    "@object-ui/types": "3.3.0"
+    "@objectstack/spec": "^4.0.4",
+    "react-hook-form": "^7.75.0",
+    "@object-ui/core": "3.3.1",
+    "@object-ui/data-objectstack": "3.3.1",
+    "@object-ui/i18n": "3.3.1",
+    "@object-ui/types": "3.3.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -37,8 +38,30 @@
   "devDependencies": {
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   },
+  "keywords": [
+    "objectui",
+    "sdui",
+    "schema-driven-ui",
+    "react",
+    "tailwind",
+    "shadcn",
+    "objectstack",
+    "renderer",
+    "schema-renderer",
+    "hooks"
+  ],
+  "author": "ObjectStack Team <team@objectstack.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "vitest run",

package/.turbo/turbo-build.log

@@ -1,4 +0,0 @@
-
-> @object-ui/react@3.3.0 build /home/runner/work/objectui/objectui/packages/react
-> tsc
-

package/src/LazyPluginLoader.tsx

@@ -1,174 +0,0 @@
-/**
- * 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 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();
-  };
-}
-
-/**
- * Create a lazy-loaded plugin component with Suspense wrapper
- * 
- * @param importFn - Dynamic import function that returns a module with default export
- * @param options - Configuration options for the lazy plugin
- * @returns A component that lazy loads the plugin
- * 
- * @example
- * ```tsx
- * // Basic usage
- * const ObjectGrid = createLazyPlugin(
- *   () => import('@object-ui/plugin-grid')
- * );
- * 
- * // With custom fallback
- * const ObjectGrid = createLazyPlugin(
- *   () => 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 { 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) => {
-    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

@@ -1,266 +0,0 @@
-/**
- * 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 React, { forwardRef, useContext, useMemo, Component } from 'react';
-import {
-  SchemaNode,
-  ComponentRegistry,
-  ExpressionEvaluator,
-  isObjectUIError,
-  type ObjectUIError,
-  ERROR_CODES,
-  debugLog,
-  debugTime,
-  debugTimeEnd,
-  DebugCollector,
-} 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 = (globalThis as any).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);
-  const dataSource = context?.dataSource || {};
-
-  // Evaluate schema expressions against the data source
-  const evaluatedSchema = useMemo(() => {
-    if (!schema || typeof schema === 'string') return schema;
-
-    const evaluator = new ExpressionEvaluator({ data: dataSource });
-    // Shallow copy
-    const newSchema = { ...schema };
-
-    // COMPAT: Hoist 'properties' up to schema level
-    // This allows support for strict configs that wrap all props in 'properties'
-    if (newSchema.properties) {
-        Object.assign(newSchema, newSchema.properties);
-    }
-
-    // Evaluate 'content' (common in Text, Button)
-    if (typeof newSchema.content === 'string') {
-      newSchema.content = evaluator.evaluate(newSchema.content);
-    }
-    
-    // Evaluate 'props'
-    if (newSchema.props) {
-      const newProps = { ...newSchema.props };
-      for (const [key, val] of Object.entries(newProps)) {
-        newProps[key] = evaluator.evaluate(val as any);
-      }
-      newSchema.props = newProps;
-    }
-
-    // Evaluate visibility: visible / visibleOn / hidden / hiddenOn
-    const shouldHide = (() => {
-      if (newSchema.visible !== undefined) {
-        return !evaluator.evaluateCondition(newSchema.visible);
-      }
-      if (newSchema.visibleOn !== undefined) {
-        return !evaluator.evaluateCondition(newSchema.visibleOn);
-      }
-      if (newSchema.hidden !== undefined) {
-        return evaluator.evaluateCondition(newSchema.hidden);
-      }
-      if (newSchema.hiddenOn !== undefined) {
-        return evaluator.evaluateCondition(newSchema.hiddenOn);
-      }
-      return false;
-    })();
-
-    if (shouldHide) {
-      newSchema._hidden = true;
-    }
-
-    // Evaluate disabled: disabled / disabledOn
-    const isDisabled = (() => {
-      if (newSchema.disabled !== undefined) {
-        return evaluator.evaluateCondition(newSchema.disabled);
-      }
-      if (newSchema.disabledOn !== undefined) {
-        return evaluator.evaluateCondition(newSchema.disabledOn);
-      }
-      return false;
-    })();
-
-    if (isDisabled) {
-      newSchema._disabled = true;
-    }
-
-    return newSchema;
-  }, [schema, dataSource]);
-
-  if (!evaluatedSchema) return null;
-  // Handle visibility: if evaluated schema is hidden, render nothing
-  if (evaluatedSchema?._hidden) 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" role="alert">
-        <p className="font-medium">Unknown component type: <strong>{evaluatedSchema.type}</strong></p>
-        {(globalThis as any).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>
-    );
-  }
-
-  // Note: We don't forward the ref to the Component because components in the registry
-  // may not support refs. The SchemaRenderer itself can still receive refs for its own use.
-  
-  // Extract schema metadata properties that should NOT be passed as React props
-  const {
-    type: _type,
-    children: _children,
-    body: _body,
-    schema: _schema,
-    visible: _visible,
-    visibleOn: _visibleOn,
-    hidden: _hidden,
-    hiddenOn: _hiddenOn,
-    disabled: _disabled,
-    disabledOn: _disabledOn,
-    _hidden: __hidden,    // stripped: internal visibility flag
-    _disabled: __disabled, // stripped: internal disabled flag
-    ...componentProps
-  } = evaluatedSchema;
-
-  // Extract AriaPropsSchema properties for accessibility
-  const ariaProps = resolveAriaProps(evaluatedSchema);
-
-  // Debug-mode enhancements: extra data attributes + perf tracking
-  const isDebug = context?.debug || context?.debugFlags?.enabled;
-  const debugAttrs: Record<string, string> = {};
-  if (isDebug) {
-    debugAttrs['data-debug-type'] = evaluatedSchema.type;
-    if (evaluatedSchema.id) {
-      debugAttrs['data-debug-id'] = evaluatedSchema.id;
-    }
-  }
-
-  debugTime(`render:${evaluatedSchema.type}:${evaluatedSchema.id ?? 'anon'}`);
-  const renderStart = isDebug ? performance.now() : 0;
-  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
-        ...debugAttrs, // Debug-mode data attributes
-        disabled: __disabled || undefined,
-        className: evaluatedSchema.className,
-        'data-obj-id': evaluatedSchema.id,
-        'data-obj-type': evaluatedSchema.type,
-        ...props
-      })}
-    </SchemaErrorBoundary>
-  );
-  debugTimeEnd(`render:${evaluatedSchema.type}:${evaluatedSchema.id ?? 'anon'}`);
-
-  // Report render perf to DebugCollector when debug mode is active
-  if (isDebug && renderStart) {
-    const durationMs = performance.now() - renderStart;
-    DebugCollector.getInstance().addPerf({
-      type: evaluatedSchema.type,
-      id: evaluatedSchema.id,
-      durationMs,
-      timestamp: Date.now(),
-    });
-  }
-
-  return rendered;
-});
-SchemaRenderer.displayName = 'SchemaRenderer';