@object-ui/react 17.3.0 → 17.6.0

package/README.md

@@ -121,18 +121,56 @@ function MyComponent() {
 }
 ```
 
-### useRegistry
+### useElementDataSourceSchema / ElementDataSourceGate
 
-Access the component registry:
+Consume `PageComponentSchema.dataSource` — the spec's per-element data binding
+(`{ object, view?, filter?, sort?, limit? }`) — in a block that has its own key
+names. `useElementDataSource` resolves the binding (fetching the object's saved
+views so `view` can be matched); these two apply the composed result to the
+block's schema and render the two non-final states.
 
 ```tsx
-import { useRegistry } from '@object-ui/react'
+import { ElementDataSourceGate } from '@object-ui/react'
+
+// `mapping` names ONLY the keys this block reads. A composed value written onto
+// a key the block ignores would be accepted and silently dropped — the defect
+// the binding exists to remove.
+const OBJECT_GRID_BINDING = {
+  columns: true,          // the view's FIELD list may fill `schema.columns`
+  filter: true,           // AND-combined, never replaced ("additional criteria")
+  sort: true,
+  limit: 'pagination.pageSize' as const,
+}
 
-function MyComponent() {
-  const registry = useRegistry()
-  const Component = registry.get('button')
-  
-  return <Component {...props} />
+const ObjectGridRenderer = ({ schema, ...props }) => (
+  <ElementDataSourceGate schema={schema} mapping={OBJECT_GRID_BINDING} testId="object-grid">
+    {(bound) => <ObjectGrid schema={bound} {...props} />}
+  </ElementDataSourceGate>
+)
+```
+
+`object` lands on `objectName` by default (pass `object: 'apiName'` for another
+key, or `object: false` for a block that reads the composed binding itself).
+Precedence: binding keys beat the component's own, view-sourced values are only a
+baseline the component's own key overrides, and `filter` AND-combines all three.
+A `view` name that does not resolve renders a configuration error rather than
+falling back to the object's full scope. Use `useElementDataSourceSchema` (plus
+the exported `ElementDataSourceErrorPanel` / `ElementDataSourceLoadingPanel`) when
+a block cannot be wrapped — a renderer whose hooks must run before the panels.
+
+### ComponentRegistry
+
+There is no registry hook: the registry is a process-level singleton exported
+by `@object-ui/core`, so read it directly. Subscribe to it only when a lazily
+registered plugin must trigger a re-render.
+
+```tsx
+import { ComponentRegistry } from '@object-ui/core'
+
+function MyComponent(props: Record<string, unknown>) {
+  const Component = ComponentRegistry.get('button')
+
+  return Component ? <Component {...props} /> : null
 }
 ```
 
@@ -225,22 +263,11 @@ leaves the surface on its own anchor), `visibleNotificationStack` (`maxVisible`
 
 ## API Reference
 
-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)
+See [full documentation](https://objectui.org/docs/core/schema-renderer) for detailed API reference.
 
 ## Links
 
-- 📚 [Documentation](https://www.objectui.org/docs/packages/react)
+- 📚 [Documentation](https://www.objectui.org/docs/core/schema-renderer)
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/react)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

package/dist/LazyPluginLoader.d.ts

@@ -30,26 +30,33 @@ export interface LazyPluginOptions {
 /**
  * Create a lazy-loaded plugin component with Suspense wrapper
  *
- * @param importFn - Dynamic import function that returns a module with default export
+ * @param importFn - Dynamic import function resolving to a module whose
+ *   `default` is the component to render. ObjectUI plugin packages export
+ *   their components by NAME and have no `default`, so a bare
+ *   `() => import('@object-ui/plugin-<x>')` does NOT satisfy this — it hands
+ *   over the module namespace object, which is neither a component at runtime
+ *   nor assignable here. Name the component you want, as the examples do.
  * @param options - Configuration options for the lazy plugin
  * @returns A component that lazy loads the plugin
  *
  * @example
  * ```tsx
- * // Basic usage
+ * // Basic usage. `@object-ui/plugin-grid` has no default export, so unwrap the
+ * // named component. Use the `async` form: the `.then((m) => ({ default: m.X }))`
+ * // spelling infers `P` as `never` on one branch of the `then` overload.
  * const ObjectGrid = createLazyPlugin(
- *   () => import('@object-ui/plugin-grid')
+ *   async () => ({ default: (await import('@object-ui/plugin-grid')).ObjectGrid })
  * );
  *
  * // With custom fallback
- * const ObjectGrid = createLazyPlugin(
- *   () => import('@object-ui/plugin-grid'),
+ * const ObjectGridWithFallback = createLazyPlugin(
+ *   async () => ({ default: (await import('@object-ui/plugin-grid')).ObjectGrid }),
  *   { fallback: <div>Loading grid...</div> }
  * );
  *
  * // With retry and error handling
- * const ObjectGrid = createLazyPlugin(
- *   () => import('@object-ui/plugin-grid'),
+ * const ObjectGridWithRetry = createLazyPlugin(
+ *   async () => ({ default: (await import('@object-ui/plugin-grid')).ObjectGrid }),
  *   {
  *     retries: 3,
  *     errorFallback: ({ error, retry }) => (

package/dist/LazyPluginLoader.js

@@ -58,26 +58,33 @@ function createRetryImport(importFn, retries, retryDelay) {
 /**
  * Create a lazy-loaded plugin component with Suspense wrapper
  *
- * @param importFn - Dynamic import function that returns a module with default export
+ * @param importFn - Dynamic import function resolving to a module whose
+ *   `default` is the component to render. ObjectUI plugin packages export
+ *   their components by NAME and have no `default`, so a bare
+ *   `() => import('@object-ui/plugin-<x>')` does NOT satisfy this — it hands
+ *   over the module namespace object, which is neither a component at runtime
+ *   nor assignable here. Name the component you want, as the examples do.
  * @param options - Configuration options for the lazy plugin
  * @returns A component that lazy loads the plugin
  *
  * @example
  * ```tsx
- * // Basic usage
+ * // Basic usage. `@object-ui/plugin-grid` has no default export, so unwrap the
+ * // named component. Use the `async` form: the `.then((m) => ({ default: m.X }))`
+ * // spelling infers `P` as `never` on one branch of the `then` overload.
  * const ObjectGrid = createLazyPlugin(
- *   () => import('@object-ui/plugin-grid')
+ *   async () => ({ default: (await import('@object-ui/plugin-grid')).ObjectGrid })
  * );
  *
  * // With custom fallback
- * const ObjectGrid = createLazyPlugin(
- *   () => import('@object-ui/plugin-grid'),
+ * const ObjectGridWithFallback = createLazyPlugin(
+ *   async () => ({ default: (await import('@object-ui/plugin-grid')).ObjectGrid }),
  *   { fallback: <div>Loading grid...</div> }
  * );
  *
  * // With retry and error handling
- * const ObjectGrid = createLazyPlugin(
- *   () => import('@object-ui/plugin-grid'),
+ * const ObjectGridWithRetry = createLazyPlugin(
+ *   async () => ({ default: (await import('@object-ui/plugin-grid')).ObjectGrid }),
  *   {
  *     retries: 3,
  *     errorFallback: ({ error, retry }) => (

package/dist/SchemaRenderer.d.ts

@@ -5,8 +5,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, { Component } from 'react';
-import { SchemaNode } from '@object-ui/core';
+import React, { Component, type ForwardRefExoticComponent, type RefAttributes } from 'react';
+import type { BaseSchema } from '@object-ui/types';
 /**
  * Per-component Error Boundary for SchemaRenderer.
  * Catches render errors in individual components, preventing one broken
@@ -30,7 +30,80 @@ export declare class SchemaErrorBoundary extends Component<{
     handleRetry: () => void;
     render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 }
-export declare const SchemaRenderer: React.ForwardRefExoticComponent<Omit<{
-    schema: SchemaNode;
-} & Record<string, any>, "ref"> & React.RefAttributes<any>>;
+/**
+ * The props `SchemaRenderer` DECLARES and reads itself (objectui#4548).
+ *
+ * ## Why `schema` is spelled as this union and not as a `SchemaNode`
+ *
+ * The repo carries two competing `SchemaNode` types: `@object-ui/core`'s
+ * interface (which requires `type: string`) and `@object-ui/types`' union
+ * (`BaseSchema | string | number | boolean | null | undefined`). This component
+ * matched NEITHER. It declared core's — narrower than what it accepts, so every
+ * caller holding the types union was wrong and could not be told — while its
+ * runtime returns early for strings and nullish, which core's interface forbids.
+ * The erasure below hid the mismatch completely: with props collapsed to an
+ * index signature, `schema` resolved to `any` and no call site was ever checked.
+ *
+ * So the contract is STATED HERE, by this component, as what it actually
+ * handles: an object schema, a bare string (rendered as text), or nothing at
+ * all. `number` / `boolean` are deliberately excluded — the runtime tolerates
+ * them defensively (see the primitive guard in the evaluation memo) but no
+ * author should be invited to pass them. Reconciling the two repo-wide
+ * `SchemaNode` spellings is a separate concern and deliberately not done here.
+ */
+export interface SchemaRendererProps {
+    schema: BaseSchema | string | null | undefined;
+}
+/**
+ * The open forwarding surface, named once so it reads as the decision it is.
+ *
+ * `SchemaRenderer` passes every prop it does not itself read straight through to
+ * the component the schema names, which is resolved at RUNTIME from a
+ * plugin-extensible registry — so the set of valid keys is not knowable here,
+ * and `packages/react/README.md` documents callers relying on it. The `any` is
+ * the point: this is a pass-through channel, not a typed prop.
+ */
+type ForwardedProps = Record<string, any>;
+/**
+ * The renderer loop.
+ *
+ * ## The explicit type annotation is the contract, and it is deliberate
+ *
+ * `forwardRef< T, P >` routes `P` through React's `PropsWithoutRef`:
+ *
+ *     Props extends any ? ('ref' extends keyof Props ? Omit< Props, 'ref' > : Props) : Props
+ *
+ * A string index signature on `P` puts `string` into `keyof Props`, so
+ * `'ref' extends keyof Props` is ALWAYS true, the `Omit` branch always runs, and
+ * `Omit` over a type carrying a string index signature keeps ONLY the index
+ * signature. Every declared prop is erased — on both sides. This component used
+ * to hand `forwardRef` a props type of `{ schema: SchemaNode } & Record< string,
+ * any >`, so its own `schema` resolved to `any` at every one of the ~376 call
+ * sites in this repo, and was not even REQUIRED: `< SchemaRenderer / >` with no
+ * schema at all type-checked (objectui#4548, measured).
+ *
+ * The fix is NOT to close the surface. This is the renderer loop: it forwards
+ * every prop it does not read to the component the schema names, resolved at
+ * RUNTIME from a plugin-extensible `ComponentRegistry`. That forwarding is a
+ * documented, load-bearing feature — `packages/react/README.md` shows
+ * `< SchemaRenderer schema={formSchema} onSubmit={handleSubmit} / >`, and
+ * `@object-ui/components`' form renderer consumes that `onSubmit` as a React
+ * prop. A closed props type would state a FALSE contract and would force every
+ * leaf plugin's props into this package to stay usable.
+ *
+ * So the two halves are separated deliberately:
+ *
+ *   * the `forwardRef` TYPE ARGUMENT is the honest `SchemaRendererProps`, with
+ *     no index signature — nothing for `PropsWithoutRef` to collapse, so
+ *     `schema` survives to the call site typed and required; and
+ *   * the open forwarding surface is stated ONCE, here, in this export
+ *     annotation. Because the annotation is applied to the already-built
+ *     component, `PropsWithoutRef` never runs over it, so `Record< string, any >`
+ *     widens the surface WITHOUT erasing anything.
+ *
+ * The repo-wide guard (`scripts/__tests__/forwardref-props-erasure.guard.test.ts`)
+ * judges the TYPE ARGUMENT only, for exactly this reason: an index signature
+ * there is an accidental eraser, whereas one here is a stated contract.
+ */
+export declare const SchemaRenderer: ForwardRefExoticComponent<SchemaRendererProps & ForwardedProps & RefAttributes<unknown>>;
 export {};