@object-ui/react 17.6.0 → 17.7.0

package/README.md

@@ -25,10 +25,11 @@ npm install @object-ui/react @object-ui/core
 
 ```tsx
 import { SchemaRenderer } from '@object-ui/react'
+import type { DeclaredNode } from '@object-ui/types'
 
-const schema = {
+const schema: DeclaredNode = {
   type: 'text',
-  value: 'Hello, Object UI!'
+  content: 'Hello, Object UI!'
 }
 
 function App() {
@@ -36,29 +37,57 @@ function App() {
 }
 ```
 
+`schema` takes a `DeclaredNode` from `@object-ui/types`, a bare string, or nothing. A
+`DeclaredNode` is a node of a declared type, keyed by its `type`: a component schema that
+package declares, a spec page block such as `element:text` with its typed `properties` bag, a
+stored page document under its page kind, or a type your application registers and declares
+in `CustomNodeRegistry`. Each node, nested ones included, is checked against its own type; a
+`type` nothing declares is refused.
+
 ### With Data
 
+Expression scope reaches the renderer through `PredicateScopeProvider`, never through a prop
+on the element: `SchemaRenderer` declares only `schema`, so anything else is forwarded to the
+component the schema names (see the open forwarding surface below). Every key of the `scope`
+you publish becomes a root the evaluator can read.
+
+⛔ `SchemaRendererProvider`'s `dataSource` is **not** an expression root. It carries the
+host's `DataSource` adapter, and objectui#9308 removed the binding that used to publish that
+adapter under the name `data` — an adapter answers no `data.*` path, so the root was constant
+for every conformant host.
+
 ```tsx
-import { SchemaRenderer } from '@object-ui/react'
+import { SchemaRenderer, PredicateScopeProvider } from '@object-ui/react'
+import type { DeclaredNode } from '@object-ui/types'
 
-const schema = {
+const schema: DeclaredNode = {
   type: 'form',
-  body: [
+  children: [
+    {
+      // `content` is evaluated on every component type. `input` has no row in
+      // the spec's expression carriage map, so a `${…}` in ITS `value` would be
+      // rendered as those characters rather than resolved.
+      type: 'text',
+      content: 'Editing ${user.name}'
+    },
     {
       type: 'input',
       name: 'name',
-      label: 'Name',
-      value: '${user.name}'
+      label: 'Name'
     }
   ]
 }
 
-const data = {
+const scope = {
   user: { name: 'John Doe' }
 }
 
 function App() {
-  return <SchemaRenderer schema={schema} data={data} />
+  return (
+    <PredicateScopeProvider scope={scope}>
+      <SchemaRenderer schema={schema} />
+    </PredicateScopeProvider>
+  )
 }
 ```
 
@@ -66,14 +95,19 @@ function App() {
 
 ```tsx
 import { SchemaRenderer } from '@object-ui/react'
+import type { DeclaredNode } from '@object-ui/types'
+
+declare const formSchema: DeclaredNode
 
 function App() {
-  const handleSubmit = (data) => {
+  const handleSubmit = (data: Record<string, unknown>) => {
     console.log('Form submitted:', data)
   }
 
+  // `onSubmit` is not a prop `SchemaRenderer` reads: it is forwarded to the
+  // component the schema names, which is why the props type stays open.
   return (
-    <SchemaRenderer 
+    <SchemaRenderer
       schema={formSchema}
       onSubmit={handleSubmit}
     />
@@ -87,7 +121,13 @@ Injects the host's data source (and optional capabilities) into every renderer
 below it:
 
 ```tsx
-import { SchemaRendererProvider } from '@object-ui/react'
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react'
+import type { ApiFetch } from '@object-ui/react'
+import type { DataSource, DeclaredNode } from '@object-ui/types'
+
+declare const adapter: DataSource
+declare const authenticatedFetch: ApiFetch
+declare const schema: DeclaredNode
 
 <SchemaRendererProvider
   dataSource={adapter}
@@ -101,6 +141,16 @@ import { SchemaRendererProvider } from '@object-ui/react'
 </SchemaRendererProvider>
 ```
 
+`dataSource` carries the host's adapter as the published `DataSource` contract
+(`@object-ui/types`), typed `DataSource | null | undefined`: a host either hands
+over an adapter or states that it has none — a Studio preview, a page rendered
+before the host's adapter has connected, or a widget probe driving `apiFetch`
+alone. Both spellings of "none" are accepted because every reader in the tree
+guards for it. The prop used to be typed `any`, so a string passed where the
+adapter belongs — the shape of a config value read from the wrong place —
+raised nothing until the first `find()` at runtime (objectui#7912).
+`useSchemaContext()` hands the same type back to every consumer.
+
 Nested providers inherit `apiFetch` from their parent when they don't supply
 their own, so re-wrapped subtrees (embedded pages, preview surfaces) keep the
 host's authentication.
@@ -109,15 +159,23 @@ host's authentication.
 
 ### useSchemaContext
 
-Access the current schema context:
+Access what `SchemaRendererProvider` injected — `dataSource`, `debug`,
+`debugFlags` and `apiFetch`. It does **not** carry the page's values: read those
+with `useDataScope`, which addresses the ambient expression scope by path. The
+two are different channels on purpose — `dataSource` is the adapter a renderer
+queries, `useDataScope` is what a node's `bind` resolves against
+(objectui#9308).
 
 ```tsx
-import { useSchemaContext } from '@object-ui/react'
+import { useDataScope, useSchemaContext } from '@object-ui/react'
 
 function MyComponent() {
-  const { data, updateData } = useSchemaContext()
-  
-  return <div>{data.value}</div>
+  const { dataSource, debug } = useSchemaContext()
+  // Resolves `scope.value` from the nearest PredicateScopeProvider above.
+  const value = useDataScope('value')
+
+  if (!dataSource) return null
+  return <div data-debug={debug}>{String(value)}</div>
 }
 ```
 
@@ -130,25 +188,56 @@ 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 type { FC } from 'react'
 import { ElementDataSourceGate } from '@object-ui/react'
+import type { ElementDataSourceMapping } from '@object-ui/react'
+// The seam is imported from CORE, not from here — see the note below.
+import { elementDataSourceBlock } from '@object-ui/core'
+import type { BaseSchema } from '@object-ui/types'
+
+// The block this renderer wraps — whatever the registry resolves for its type.
+declare const ObjectGrid: FC<{ schema: BaseSchema }>
 
 // `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 = {
+const OBJECT_GRID_BINDING: ElementDataSourceMapping = {
   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,
 }
 
-const ObjectGridRenderer = ({ schema, ...props }) => (
+// `elementDataSourceBlock` is not optional decoration — see below.
+const ObjectGridRenderer = elementDataSourceBlock<FC<{ schema: BaseSchema }>>(({ schema, ...props }) => (
   <ElementDataSourceGate schema={schema} mapping={OBJECT_GRID_BINDING} testId="object-grid">
     {(bound) => <ObjectGrid schema={bound} {...props} />}
   </ElementDataSourceGate>
-)
+))
 ```
 
+**Wrap the registered renderer in `elementDataSourceBlock`.** It is what makes
+`ComponentRegistry.register` emit the `dataSource` input on that block's
+authoring surface, so the key the gate READS is also the key the manifest, the
+save gate, the generated JSX types and the designer DECLARE. Skip it and the
+binding still works at runtime while the html tier reports `dataSource` as a prop
+that does not exist — the one spelling that resolves a saved view, reported
+exactly like the spellings that do nothing (objectui#6678). The declaration is
+emitted from this one seam, so never hand-write a `dataSource` entry in a block's
+`inputs`. `pnpm check:element-data-source-declaration` fails any source that
+consumes the gate without reaching the seam.
+
+⚠️ **Import the seam from `@object-ui/core`, not from this package** — it is one
+function under one name, re-exported here for discoverability, and the check
+above enforces the core import at call sites. The reason is measured, not
+stylistic: a registration runs at MODULE SCOPE, 101 suites in this repo partially
+mock `@object-ui/react` by hand-listing the exports they return, and a
+module-scope read of a name absent from such a list throws at COLLECTION time —
+the importing test file dies before running a single assertion. Taking the seam
+from `@object-ui/react` reddened 17 files across all four CI shards with zero
+failed assertions among them. Nothing mocks `@object-ui/core`, and every
+registration module already imports `ComponentRegistry` from it.
+
 `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
@@ -157,6 +246,180 @@ 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.
+That form still reads `dataSource`, so it still owes the seam: mark the renderer
+at its registration, `register('x', elementDataSourceBlock(XRenderer), { … })` —
+again importing `elementDataSourceBlock` from `@object-ui/core`.
+
+### useSettledSchema
+
+The settled-schema RESOLUTION half, shared by every view that gates a record
+query on its object definition — `ObjectKanban`, `ObjectView`,
+`ObjectCalendar`, `ObjectTree` and `ObjectGantt` (objectui#6482, converged in
+objectui#7225). Tracks whether an object's definition has finished resolving
+FOR THE KEY THE CURRENT RENDER IS ASKING ABOUT — `ready` and `def` are two views of one piece of state, so a
+stale key can never read as ready. GATE PLACEMENT — which effect actually
+waits on `ready` — stays a per-component decision; this hook only owns the
+resolution.
+
+```tsx
+import { useEffect } from 'react'
+import { useSettledSchema } from '@object-ui/react'
+import type { DataSource } from '@object-ui/types'
+
+function ObjectSomething({
+  schema,
+  dataSource,
+}: {
+  schema: { objectName?: string }
+  dataSource: DataSource
+}) {
+  const key = schema.objectName ?? ''
+  const { ready, def } = useSettledSchema(key, dataSource)
+
+  useEffect(() => {
+    if (!ready) return // gate placement is local to this component
+    // issue the record query, e.g. buildExpandFields(def?.fields)
+  }, [ready, def])
+}
+```
+
+Pass `dataSource: undefined` for a render that should settle immediately with
+no definition (e.g. a provider that issues no metadata read at all) instead of
+adding a separate enable flag.
+
+### useFilterScope / useResolvedFilter
+
+A data node that sends its own authored `filter` into a query resolves the
+spec's context tokens in it first: `{current_user_id}`, `{current_org_id}`,
+`{record_id}` and the date macros such as `{today}` (objectui#10666).
+`useFilterScope()` reads the session scope a host mounts with
+`FilterScopeProvider`, plus the id of the record in view when a
+`RecordContextProvider` is mounted above the node (objectui#7297);
+`useResolvedFilter(filter, scope)` resolves the filter through
+`@object-ui/core`'s `resolveFilterPlaceholders` and HOLDS the result.
+
+`{record_id}` is the id of the record a `type: 'record'` page shows, taken from
+that page's mounted record context and never from a URL parameter or a page
+variable: on a person's record page, `{ assignee: '{record_id}' }` counts that
+person's tasks. With no record in context (a list view, a dashboard, a page
+that is not a record page) it is refused by name, with the same warning an
+unresolved `{current_user_id}` gets, and left as written, so the filter never
+widens. It scopes what a component shows; it is not access control, which
+stays with the server's row-level security. `FilterScopeProvider` carries the
+session values only.
+
+```tsx
+import { useEffect } from 'react'
+import { useFilterScope, useResolvedFilter } from '@object-ui/react'
+import type { DataSource, QueryParams } from '@object-ui/types'
+
+function ObjectSomething({
+  schema,
+  dataSource,
+}: {
+  schema: { objectName: string; filter?: QueryParams['$filter'] }
+  dataSource: DataSource
+}) {
+  const filterScope = useFilterScope()
+  const filter = useResolvedFilter(schema.filter, filterScope)
+
+  useEffect(() => {
+    // Query with the held value and key the effect on it, never on schema.filter.
+    void dataSource.find(schema.objectName, { $filter: filter })
+  }, [dataSource, schema.objectName, filter])
+}
+```
+
+The held value keeps its reference while the authored filter is structurally
+equal (a filter rebuilt inline on every render included) and the scope's user,
+organization, record and `onUnresolved` are unchanged, so the effect above runs
+once. A structurally different filter, a new signed-in user or organization, or
+another record in view resolves again. A filter with no token to resolve is handed back as the value
+passed in. A token the scope cannot resolve is left in place, and the resolver
+logs one warning naming it.
+
+### NON_GRID_ROW_CEILING
+
+The platform's hard row ceiling for a NON-GRID visualisation — gantt, calendar,
+map and tree (objectui#7210). Those four fetch the whole FILTERED result set,
+because a truthful range or layout needs all of it, but the fetch is bounded:
+past the ceiling they draw the first N rows and say so.
+
+The mechanism lives in `@object-ui/core` (objectui#7508): `NON_GRID_ROW_CEILING`,
+`nonGridRowCeilingQuery` and `applyNonGridRowCeiling`, with the result type
+`NonGridCeilingResult`. This package re-exports `NON_GRID_ROW_CEILING`,
+`applyNonGridRowCeiling` and `NonGridCeilingResult`, and owns the React half —
+the footnote, `NonGridRowCeilingNote`.
+
+```tsx
+import { NonGridRowCeilingNote, applyNonGridRowCeiling } from '@object-ui/react'
+import { nonGridRowCeilingQuery } from '@object-ui/core'
+import type { DataSource, QueryParams } from '@object-ui/types'
+
+declare const dataSource: DataSource
+declare const objectName: string
+declare const schema: { filter?: QueryParams['$filter'] }
+
+const result = await dataSource.find(objectName, {
+  $filter: schema.filter,
+  ...nonGridRowCeilingQuery(), // `$top`: the ceiling plus ONE probe row
+})
+// The semicolon is load-bearing: the next statement opens with `<`, so without
+// it the call above is parsed as the left side of a relational expression.
+const capped = applyNonGridRowCeiling(result);
+// …draw `capped.rows`, then hand the note the whole result:
+<NonGridRowCeilingNote result={capped} />
+```
+
+`nonGridRowCeilingQuery()` is the one place the probe row is written: `$top` is
+the ceiling plus one, because the extra row is what makes truncation a fact about
+the rows in hand — `QueryResult.total` is optional and a bare-array response
+carries none. Spread it into the query; never spell the `+ 1` at a call site.
+
+`NonGridRowCeilingNote` takes the `NonGridCeilingResult` and nothing else. The
+count it prints is `result.rows.length` and the total is `result.total`, so the
+footnote cannot name numbers that disagree with the rows drawn. It renders `null`
+when nothing was truncated, so it can be mounted whenever a result is in hand.
+
+⛔ The ceiling is not authorable and must not become so. Silent truncation is
+the failure it exists to prevent — a cut-off schedule still looks like a
+schedule — so a view that caps rows without rendering the note is a defect, not
+an optimisation.
+
+### resolveInlineAriaProps
+
+Maps the spec's nested `aria` bag (`AriaPropsSchema`, the `aria` prop a block
+such as `element:text` declares) to the DOM attributes it names
+(objectui#11051):
+
+- `ariaLabel` → `aria-label`. A plain string is used as written; an inline
+  locale map (`{ en: 'Order total', 'zh-CN': '订单合计' }`) gives the entry for
+  `locale`, through the spec's own `resolveI18nLabel`.
+- `ariaDescribedBy` → `aria-describedby`.
+- `role` → `role`.
+
+Only attributes that have a value are returned, so the result can be spread
+onto an element directly. It is a pure function: pass the locale yourself, in
+React from `useDisplayLocale()`.
+
+```tsx
+import { resolveInlineAriaProps } from '@object-ui/react'
+import { useDisplayLocale } from '@object-ui/i18n'
+import type { AriaProps } from '@object-ui/types'
+
+function CloseButton({ aria, onClose }: { aria?: AriaProps; onClose: () => void }) {
+  const locale = useDisplayLocale()
+  return (
+    <button type="button" onClick={onClose} {...resolveInlineAriaProps(aria, locale)}>
+      ×
+    </button>
+  )
+}
+```
+
+This is not the reader `SchemaRenderer` applies to a node's FLAT `ariaLabel`,
+which is objectui's keyed `{ key, defaultValue }` form. Each resolver returns
+nothing useful for the other's shape, so the two stay separate (objectui#4580).
 
 ### ComponentRegistry
 
@@ -176,7 +439,7 @@ function MyComponent(props: Record<string, unknown>) {
 
 ### useDiscovery
 
-Access server discovery information including preview mode detection:
+Access server discovery information — service availability and server identity:
 
 ```tsx
 import { useDiscovery } from '@object-ui/react'
@@ -184,11 +447,6 @@ import { useDiscovery } from '@object-ui/react'
 function MyComponent() {
   const { discovery, isLoading, isAuthEnabled, isAiEnabled } = useDiscovery()
   
-  // Check if the server is in preview mode
-  if (discovery?.mode === 'preview') {
-    console.log('Preview mode active:', discovery.previewMode)
-  }
-
   // Check if AI service is available
   if (isAiEnabled) {
     console.log('AI service route:', discovery?.services?.ai?.route)
@@ -204,21 +462,17 @@ function MyComponent() {
 | --- | --- | --- |
 | `name` | `string` | Server name |
 | `version` | `string` | Server version |
-| `mode` | `string` | Runtime mode (e.g. `'development'`, `'production'`, `'preview'`) |
-| `previewMode` | `object` | Preview mode configuration (present when mode is `'preview'`) |
+| `mode` | `string` | Runtime mode the server reports (`RuntimeMode` in `@objectstack/spec`) |
 | `services` | `object` | Service availability status (auth, data, metadata, ai) |
 | `capabilities` | `string[]` | API capabilities |
 
-The `previewMode` object contains:
-
-| Property | Type | Default | Description |
-| --- | --- | --- | --- |
-| `autoLogin` | `boolean` | `true` | Skip login/registration pages |
-| `simulatedRole` | `'admin' \| 'user' \| 'viewer'` | `'admin'` | Simulated user role |
-| `simulatedUserName` | `string` | `'Preview User'` | Display name |
-| `readOnly` | `boolean` | `false` | Read-only mode |
-| `expiresInSeconds` | `number` | `0` | Session duration (0 = no expiry) |
-| `bannerMessage` | `string` | — | UI banner message |
+> The `previewMode` block and the `'preview'` runtime mode were retired in
+> objectui#6654, following their retirement in `@objectstack/spec`
+> (objectstack#11846). A server that still sends them is read as any other
+> payload: authentication follows `services.auth` alone, so a preview
+> deployment requires login rather than silently running with auth off.
+> `AuthProvider`'s `previewMode` **prop** in `@object-ui/auth` is a separate,
+> host-supplied capability and is unaffected.
 
 ### useNotifications / useNotificationsByPresentation
 
@@ -240,6 +494,8 @@ belong (a banner is in flow, an inline notification sits next to its raiser).
 why every type looked like a toast.
 
 ```tsx
+import { useNotifications } from '@object-ui/react'
+
 const { notify } = useNotifications()
 
 notify({ title: 'Saved', severity: 'success' })                     // toast (spec default)

package/dist/SchemaRenderer.d.ts

@@ -6,7 +6,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React, { Component, type ForwardRefExoticComponent, type RefAttributes } from 'react';
-import type { BaseSchema } from '@object-ui/types';
+import type { DeclaredNode } from '@object-ui/types';
+/**
+ * The `properties` evaluation of the {@link SchemaRenderer} memo, for a config
+ * bag that does not pass through `SchemaRenderer` (objectui#10290): the same
+ * per-key rule, the same `ExpressionEvaluator`, and the same scope, built from
+ * the same three inputs. It is not a second template engine.
+ *
+ * The plain half of `useConfigBagEvaluator()` (`hooks/useConfigBagEvaluator`),
+ * which reads those inputs from the contexts the memo reads them from. Call
+ * the hook; this function exists because the rule it applies is this module's.
+ * (The hook is not declared in this module: a hook here puts this file under
+ * the React Compiler lint, which then reports the render-time
+ * `performance.now()` / `Date.now()` debug probes below.)
+ *
+ * A value that is not a config bag is returned unchanged; a bag comes back as a
+ * new, evaluated object and the authored one is never mutated.
+ */
+export declare function evaluateConfigBagInScope(bag: unknown, predicateScope: Record<string, unknown>, boundRecord: unknown, pageVariables: unknown): unknown;
 /**
  * Per-component Error Boundary for SchemaRenderer.
  * Catches render errors in individual components, preventing one broken
@@ -35,9 +52,9 @@ export declare class SchemaErrorBoundary extends Component<{
  *
  * ## 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
+ * The repo carried two competing `SchemaNode` types: `@object-ui/core`'s
+ * interface (which requires `type: string`) and `@object-ui/types`' union (then
+ * `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.
@@ -48,11 +65,25 @@ export declare class SchemaErrorBoundary extends Component<{
  * 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.
+ * author should be invited to pass them; `toRenderableSchema` (`./schema-input`)
+ * is the bridge from a `SchemaNode` that may hold one.
+ *
+ * ## The object member is `DeclaredNode` (objectui#11466)
+ *
+ * The object member is `DeclaredNode` from `@object-ui/types`, the same type a
+ * node slot takes: the discriminated union, keyed by the literal `type`, of the
+ * component schemas that package declares, the spec-declared `AuthoringNode`s
+ * (objectui#11364: public blocks, `element:text_input` /
+ * `element:record_picker`, a stored page document under its page kind), and
+ * the types an application declares in `CustomNodeRegistry`. It has no
+ * `type: string` arm, so a node whose `type` no declaration names is refused
+ * here, and each node's own keys are judged: once objectui#8347 removes
+ * `BaseSchema`'s index signature, a misspelled key is refused while the
+ * declared spelling compiles. ⛔ The prop is widened by declared types only,
+ * never by an index signature, a `Record` or a `type: string` arm.
  */
 export interface SchemaRendererProps {
-    schema: BaseSchema | string | null | undefined;
+    schema: DeclaredNode | string | null | undefined;
 }
 /**
  * The open forwarding surface, named once so it reads as the decision it is.