@cratis/scene.components 3.3.1 → 3.5.0

package/README.md

@@ -72,7 +72,8 @@ unbound table costs one dashed box, not the whole screen.
 ### Arc is loaded lazily
 
 `@cratis/arc`, `@cratis/arc.react` and `@cratis/fundamentals` are peer dependencies of `@cratis/components`
-that the *host* supplies. They are not installed in this repository, and a design surface is not a host.
+that the *host* supplies. This package also declares Arc and Arc React as optional peers and pins
+22.16.1 as development dependencies for native integration tests. A design surface is not a host.
 
 Every adapter that reaches them does so through a dynamic `import()` inside `React.lazy`, wrapped in
 `ArcRuntimeBoundary` (`Suspense` + the library's own `ErrorBoundary`). A screen built only from the library's
@@ -87,6 +88,54 @@ This splits the library cleanly, and the split is the library's own:
 The Storybook build externalizes the Arc packages (`.storybook/main.ts`) so the lazy chunk can be emitted
 with its imports left bare. No story loads that chunk, because no story registers a binding.
 
+## Optional single-result view (read-only)
+
+`Cratis.Components:singleResult` is a narrow adapter for an optional **single model**, not a collection.
+For example, a host registers its generated `ProjectName` proxy and supplies these ExternalComponent
+properties (the identifier comes from the host's committed input, never a guessed project):
+
+```typescript
+registerQuery('ProjectName', ProjectName);
+const properties = {
+    query: 'ProjectName',
+    queryArguments: Object.freeze({ projectId: committedProjectId }),
+    enabled: true,
+    resultField: 'name',
+};
+```
+
+Use the actual own-field name of the generated model. `resultField` selects exactly one own data field:
+no dotted-path traversal, getters, inherited members, expressions, JSON display or result-binding DSL.
+Strings, finite numbers and booleans render as escaped text, including `0`, `false` and empty strings.
+An absent/non-scalar field is a visible failure, not a missing model. A successful null/undefined model
+is `Not found`; unsuccessful, unauthorized, invalid and exception envelopes are `Unable to load result`.
+Idle, loading and failure states never display server exception messages or stacks.
+
+`enabled` defaults to false and must be exactly true; the element must also be enabled. The host owns
+input controls, validation feedback and committing/replacing immutable `queryArguments` objects. Even
+parameterless queries require an explicit `{}`. Missing bindings take precedence over all other checks
+and never import Arc. Disabled or malformed adapter properties do not import the lazy runtime either.
+Native Arc `perform` owns required-parameter and generated-validator checks before HTTP; Scene adds no
+business validation and forwards the argument object by identity.
+
+The private lazy runtime creates a fresh native proxy per request generation, configures all four Arc
+context connection/header values, and aborts on replacement or unmount. It also ignores late completion
+when cancellation is ignored, masks previous results on the input-changing render, and responds to
+header-callback identity and `queryVersion` changes. Hosts must replace the callback or bump the version
+when credentials change invisibly inside a stable callback. There is no shared cache, command-triggered
+refresh, polling, retry button, or observable-query subscription.
+
+Published Arc 22.16.1 itself normalizes top-level falsy primitive payloads to null in `QueryResult`.
+This adapter therefore promises scalar **fields of models**, not top-level primitive queries; it does
+not fork Arc deserialization to recover those payloads. `isReady: false` is a failure for this one-shot
+view rather than an invented retry protocol. Enumerable proxies are rejected before execution.
+
+Tests use a real `QueryFor` subclass with unmodified `perform`, native validation and only the HTTP
+boundary replaced. Separate lazy-boundary doubles test Arc-free gating, not native client correctness.
+They do not prove a generated server route, backend persistence or end-to-end editable input. Scene #39
+must remain open: editable Scene parameter binding, input/commit semantics, cross-component binding and
+a general result-binding model are still unimplemented. No default profile, generator or schema changed.
+
 ## Naming and shadowing
 
 Bare names are `lowerCamelCase` and abstract — `dataTable`, not `DataTableForQuery` — registered under
@@ -149,7 +198,7 @@ both packages write themes in one language: `primary.color`, `primary.contrastCo
 ```
 bindings/    the registry, BindingKind, BoundConstructor, MissingBinding, ArcRuntimeBoundary
 pages/       page, dataPage, formElement
-data/        dataTable, table, observableDataTable
+data/        dataTable, table, observableDataTable, singleResult
 forms/       commandForm; forms/fields/ the twelve field types
 dialogs/     dialog, confirmationDialog, busyIndicatorDialog, commandDialog, stepperCommandDialog
 common/      icon, tooltip, dropdown, errorBoundary

package/bindings/ArcBoundComponents.tsx

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Runtime-only module: import dynamically beneath ArcRuntimeBoundary, never through the barrel.
+import type { ComponentProps } from 'react';
+import { QueryFor, ObservableQueryFor } from '@cratis/arc/queries';
+import { Command } from '@cratis/arc/commands';
+import { DataTableForQuery, DataTableForObservableQuery } from '@cratis/components/DataTables';
+import { DataPage } from '@cratis/components/DataPage';
+import { CommandDialog, StepperCommandDialog } from '@cratis/components/CommandDialog';
+import type { BoundConstructor } from './BoundConstructor';
+import { requireArcProxy } from './requireArcProxy';
+
+type QueryProps<T> = Omit<T, 'query'> & { query: BoundConstructor };
+type CommandProps<T> = Omit<T, 'command'> & { command: BoundConstructor };
+
+// Scene carries property names and argument objects, not compile-time row schemas. These adapters
+// support generated object/collection queries, as required by the Components public prop contracts.
+export function BoundDataTable({ query, ...props }: QueryProps<ComponentProps<typeof DataTableForQuery>>) {
+    return <DataTableForQuery {...props} query={requireArcProxy(query, QueryFor<object, object>, 'query')} />;
+}
+
+export function BoundObservableDataTable({ query, ...props }: QueryProps<ComponentProps<typeof DataTableForObservableQuery>>) {
+    return <DataTableForObservableQuery {...props} query={requireArcProxy(query, ObservableQueryFor<object, object>, 'observable query')} />;
+}
+
+export function BoundDataPage({ query, ...props }: QueryProps<ComponentProps<typeof DataPage>>) {
+    const base = query.prototype instanceof ObservableQueryFor ? ObservableQueryFor<object, object> : QueryFor<object, object>;
+    // This chooses only the kind of the supplied constructor, never another registered binding.
+    const proxy = requireArcProxy<QueryFor<object, object> | ObservableQueryFor<object, object>>(query, base, 'query');
+    return <DataPage {...props} query={proxy} />;
+}
+
+export function BoundCommandDialog({ command, ...props }: CommandProps<ComponentProps<typeof CommandDialog>>) {
+    return <CommandDialog {...props} command={requireArcProxy(command, Command<object, object>, 'command')} />;
+}
+
+export function BoundStepperCommandDialog({ command, ...props }: CommandProps<ComponentProps<typeof StepperCommandDialog>>) {
+    return <StepperCommandDialog {...props} command={requireArcProxy(command, Command<object, object>, 'command')} />;
+}

package/bindings/BoundConstructor.ts

@@ -6,14 +6,14 @@
  * `[ReadModel]` and `[Command]` types.
  *
  * `@cratis/components` types these as `Constructor<T>` from `@cratis/fundamentals`, constrained to
- * `IQueryFor<T>` / a command shape. This package cannot use those types: `@cratis/arc` and
- * `@cratis/fundamentals` are peer dependencies of `@cratis/components` that the *host* provides, and
- * Scene deliberately does not depend on Arc - a Scene screen is a UI model, and the whole point of the
- * registry is that Scene never needs to know what an Arc proxy is.
+ * `IQueryFor<T>` / a command shape. This registry intentionally does not use those types: optional
+ * Arc peers must not make an Arc-free preview load Arc. The lazy Components bridge validates native
+ * proxy inheritance and the zero-argument constructor convention before passing a binding on.
  *
  * So the registry stores the widest honest shape: something that can be constructed. Whether a
  * registered class really is a query or a command is the host's responsibility, and it is checkable
- * where the host registers it, with the real Arc types in scope - which is exactly where it should be.
+ * where the host registers it, with the real Arc types in scope. Arbitrary registrations remain usable
+ * by other consumers; the lazy Arc bridge rejects unsupported constructors visibly.
  *
  * `never[]` rather than `unknown[]` for the parameters so that any constructor is assignable, regardless
  * of what it takes; `unknown[]` would only accept constructors whose parameters accept anything.

package/bindings/for_requireArcProxy/NativeProxies.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryFor, ObservableQueryFor } from '@cratis/arc/queries';
+import { Command } from '@cratis/arc/commands';
+
+export class Snapshot extends QueryFor<object[], { projectId: string }> {
+    readonly route = '/projects';
+    readonly parameterDescriptors = [];
+    readonly requiredRequestParameters = ['projectId'];
+    defaultValue = [];
+    constructor() { super(Object, true); throw new Error('Must not construct during binding'); }
+}
+
+export class Live extends ObservableQueryFor<object[], object> {
+    readonly route = '/projects';
+    readonly parameterDescriptors = [];
+    readonly requiredRequestParameters = [];
+    readonly defaultValue = [];
+    constructor() { super(Object, true); throw new Error('Must not construct during binding'); }
+}
+
+export class Save extends Command {
+    readonly route = '/save';
+    readonly propertyDescriptors = [];
+    readonly requestParameters = [];
+    constructor() { super(Object, false); throw new Error('Must not construct during binding'); }
+}

package/bindings/for_requireArcProxy/when_mounting_bound_adapters.tsx

@@ -0,0 +1,71 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { act, cleanup, render, screen } from '@testing-library/react';
+import { expect, vi } from 'vitest';
+import { externalComponent } from '../../given';
+
+// Keep the real Arc base classes; replace only the final Components renderers.
+describe('when mounting bound adapters', () => {
+    const received = vi.fn<(props: Record<string, unknown>) => void>();
+    let bindings: typeof import('../bindingRegistry');
+    let proxies: typeof import('./NativeProxies');
+    let adapters: typeof import('../ArcBoundComponents');
+    let Boundary: typeof import('../ArcRuntimeBoundary').ArcRuntimeBoundary;
+
+    beforeEach(async () => {
+        vi.resetModules();
+        received.mockClear();
+        const component = (props: Record<string, unknown>) => { received(props); return <span>Mounted native adapter</span>; };
+        vi.doMock('@cratis/components/DataTables', () => ({ DataTableForQuery: component, DataTableForObservableQuery: component }));
+        vi.doMock('@cratis/components/DataPage', () => ({ DataPage: component }));
+        vi.doMock('@cratis/components/CommandDialog', () => ({ CommandDialog: component, StepperCommandDialog: component }));
+        bindings = await import('../bindingRegistry');
+        bindings.clearBindings();
+        proxies = await import('./NativeProxies');
+        adapters = await import('../ArcBoundComponents');
+        ({ ArcRuntimeBoundary: Boundary } = await import('../ArcRuntimeBoundary'));
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    });
+
+    afterEach(() => {
+        cleanup();
+        bindings.clearBindings();
+        vi.restoreAllMocks();
+        vi.doUnmock('@cratis/components/DataTables');
+        vi.doUnmock('@cratis/components/DataPage');
+        vi.doUnmock('@cratis/components/CommandDialog');
+        vi.resetModules();
+    });
+
+    it('should pass both supported page kinds and both command dialog constructors unchanged', () => {
+        const { BoundDataPage, BoundObservableDataTable, BoundCommandDialog, BoundStepperCommandDialog } = adapters;
+        render(<><BoundDataPage query={proxies.Snapshot} title='' emptyMessage='' children={undefined} />
+            <BoundDataPage query={proxies.Live} title='' emptyMessage='' children={undefined} />
+            <BoundObservableDataTable query={proxies.Live} emptyMessage='' />
+            <BoundCommandDialog command={proxies.Save} title='' visible />
+            <BoundStepperCommandDialog command={proxies.Save} title='' visible /></>);
+        expect(received.mock.calls.map(([props]) => props.query ?? props.command)).toEqual([proxies.Snapshot, proxies.Live, proxies.Live, proxies.Save, proxies.Save]);
+    });
+
+    it('should visibly reject a wrong-kind registered query without selecting another query', async () => {
+        bindings.registerQuery('wrong', proxies.Save);
+        bindings.registerQuery('valid', proxies.Snapshot);
+        const { SceneDataTable } = await import('../../data/SceneDataTable');
+        await act(async () => {
+            render(<SceneDataTable element={externalComponent('Cratis.Components:dataTable', { query: 'wrong' })} slots={{}} />);
+        });
+        expect(screen.getByText("Invalid query binding 'Save': expected a zero-argument Arc query proxy")).toBeTruthy();
+        expect(received).not.toHaveBeenCalled();
+    });
+
+    it('should visibly reject snapshot bindings in observable tables and query bindings in dialogs', () => {
+        const { BoundObservableDataTable, BoundCommandDialog, BoundStepperCommandDialog, BoundDataPage } = adapters;
+        render(<><Boundary><BoundObservableDataTable query={proxies.Snapshot} emptyMessage='' /></Boundary>
+            <Boundary><BoundCommandDialog command={proxies.Snapshot} title='' visible /></Boundary>
+            <Boundary><BoundStepperCommandDialog command={proxies.Live} title='' visible /></Boundary>
+            <Boundary><BoundDataPage query={proxies.Save} title='' emptyMessage='' children={undefined} /></Boundary></>);
+        expect(screen.getAllByText('Error')).toHaveLength(4);
+        expect(received).not.toHaveBeenCalled();
+    });
+});

package/bindings/for_requireArcProxy/when_previewing_without_arc.tsx

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { act, cleanup, render, screen } from '@testing-library/react';
+import { expect, vi } from 'vitest';
+import { externalComponent } from '../../given';
+
+describe('when previewing bound adapters without Arc', () => {
+    const loaded = vi.fn();
+
+    afterEach(() => {
+        cleanup();
+        vi.doUnmock('../ArcBoundComponents');
+        vi.resetModules();
+    });
+
+    it('should show missing bindings without importing the Arc runtime module', async () => {
+        vi.resetModules();
+        vi.doMock('../ArcBoundComponents', () => {
+            loaded();
+            throw new Error('Arc is unavailable in preview');
+        });
+        const { clearBindings } = await import('../bindingRegistry');
+        clearBindings();
+        const { SceneDataTable } = await import('../../data/SceneDataTable');
+        const { SceneObservableDataTable } = await import('../../data/SceneObservableDataTable');
+        const { SceneDataPage } = await import('../../pages/SceneDataPage');
+        const { SceneCommandDialog } = await import('../../dialogs/SceneCommandDialog');
+        const { SceneStepperCommandDialog } = await import('../../dialogs/SceneStepperCommandDialog');
+        await act(async () => {
+            render(<>{[SceneDataTable, SceneObservableDataTable, SceneDataPage, SceneCommandDialog, SceneStepperCommandDialog].map((Adapter, index) =>
+                <Adapter key={index} element={externalComponent('Cratis.Components:preview', { query: 'missing', command: 'missing' })} slots={{}} />)}</>);
+        });
+        expect(screen.getAllByText(/Unresolved .* binding 'missing'/)).toHaveLength(5);
+        expect(loaded).not.toHaveBeenCalled();
+    });
+});

package/bindings/for_requireArcProxy/when_validating_a_proxy.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { expect } from 'vitest';
+import { QueryFor, ObservableQueryFor } from '@cratis/arc/queries';
+import { Command } from '@cratis/arc/commands';
+import type { ComponentProps } from 'react';
+import type { DataTableForQuery, DataTableForObservableQuery } from '@cratis/components/DataTables';
+import type { CommandDialog } from '@cratis/components/CommandDialog';
+import { requireArcProxy } from '../requireArcProxy';
+import { registerQuery, resolveQuery, clearBindings } from '../bindingRegistry';
+import { Snapshot, Live, Save } from './NativeProxies';
+
+describe('when validating a proxy at the lazy Arc boundary', () => {
+    afterEach(clearBindings);
+
+    it('should preserve native constructors without constructing them and satisfy public component props', () => {
+        const query: ComponentProps<typeof DataTableForQuery>['query'] = requireArcProxy(Snapshot, QueryFor<object, object>, 'query');
+        const observable: ComponentProps<typeof DataTableForObservableQuery>['query'] = requireArcProxy(Live, ObservableQueryFor<object, object>, 'observable query');
+        const command: ComponentProps<typeof CommandDialog>['command'] = requireArcProxy(Save, Command<object, object>, 'command');
+        expect(query).toBe(Snapshot);
+        expect(observable).toBe(Live);
+        expect(command).toBe(Save);
+    });
+
+    it('should reject wrong kinds rather than perform an observable query as a snapshot', () => {
+        expect(() => requireArcProxy(Live, QueryFor<object, object>, 'query')).toThrow('Invalid query binding');
+        expect(() => requireArcProxy(Snapshot, ObservableQueryFor<object, object>, 'observable query')).toThrow('Invalid observable query binding');
+        expect(() => requireArcProxy(Snapshot, Command<object, object>, 'command')).toThrow('Invalid command binding');
+        expect(() => requireArcProxy(Save, QueryFor<object, object>, 'query')).toThrow('Invalid query binding');
+    });
+
+    it('should preserve arbitrary constructor registration but reject it at an Arc adapter', () => {
+        class Arbitrary { constructor(readonly input: string) {} }
+        registerQuery('arbitrary', Arbitrary);
+        expect(resolveQuery('arbitrary')).toBe(Arbitrary);
+        expect(() => requireArcProxy(Arbitrary, QueryFor<object, object>, 'query')).toThrow('Invalid query binding');
+    });
+
+    it('should reject a native subclass requiring constructor arguments without invoking it', () => {
+        class NeedsArguments extends Snapshot { constructor(readonly input: string) { super(); } }
+        expect(() => requireArcProxy(NeedsArguments, QueryFor<object, object>, 'query')).toThrow('zero-argument Arc');
+    });
+});

package/bindings/requireArcProxy.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { BoundConstructor } from './BoundConstructor';
+
+/**
+ * Bridge for the generated, zero-argument Arc proxies consumed by Components. The registry remains
+ * open to arbitrary constructors; only mounting an Arc adapter requires this narrower contract.
+ * Check inheritance without constructing a proxy (constructors can have side effects).
+ *
+ * This is not structural interface validation: the host still owns the generated subclass's data,
+ * argument and implementation correctness. Prototype identity deliberately rejects duck-typed proxies
+ * and proxies from a second Arc installation. The arity check enforces the generated convention,
+ * not general JavaScript constructor safety (defaults/rest parameters can hide requirements).
+ * The single assertion bridges the registry under that host-owned generated-proxy contract; it is
+ * not a proof of arbitrary subclass behavior or of erased row/argument types.
+ */
+export function requireArcProxy<T extends object>(target: BoundConstructor, base: { prototype: T }, kind: string): new () => T {
+    const prototype: unknown = target.prototype;
+    if (target.length !== 0 || typeof prototype !== 'object' || prototype === null || !Object.prototype.isPrototypeOf.call(base.prototype, prototype)) {
+        throw new Error(`Invalid ${kind} binding '${target.name}': expected a zero-argument Arc ${kind} proxy`);
+    }
+    return target as new () => T;
+}

package/cratisComponents.ts

@@ -3,7 +3,7 @@
 
 import { ComponentRegistry, componentRegistryKey } from '@cratis/scene.react';
 import { SceneDataPage, SceneFormElement, ScenePage } from './pages';
-import { SceneDataTable, SceneObservableDataTable } from './data';
+import { SceneDataTable, SceneObservableDataTable, SceneSingleResult } from './data';
 import {
     SceneCalendarField,
     SceneCheckboxField,
@@ -49,6 +49,7 @@ export const cratisComponents: ComponentRegistry = {
     [componentRegistryKey(cratisComponentsPackageName, 'dataPage')]: SceneDataPage,
     [componentRegistryKey(cratisComponentsPackageName, 'formElement')]: SceneFormElement,
 
+    [componentRegistryKey(cratisComponentsPackageName, 'singleResult')]: SceneSingleResult,
     [componentRegistryKey(cratisComponentsPackageName, 'dataTable')]: SceneDataTable,
     [componentRegistryKey(cratisComponentsPackageName, 'table')]: SceneDataTable,
     [componentRegistryKey(cratisComponentsPackageName, 'observableDataTable')]: SceneObservableDataTable,

package/cratisComponentsPackage.ts

@@ -36,6 +36,7 @@ export const cratisComponentsPackageManifest: ScenePackage = {
         'page',
         'dataPage',
         'formElement',
+        'singleResult',
         'dataTable',
         'table',
         'observableDataTable',
@@ -88,7 +89,7 @@ export const cratisComponentsPackageManifest: ScenePackage = {
     themes: [],
 
     displayName: 'Cratis Components',
-    description: "Cratis' Arc-bound data, form and dialog composites, built on PrimeReact and Tailwind.",
+    description: "Cratis' Arc-bound data, form and dialog composites, built on PrimeReact and Tailwind. dataTable and table accept optional object-valued queryArguments for collection queries. singleResult displays one read-only scalar own resultField of an optional model using an explicit query, object queryArguments and enabled: true.",
     module: '@cratis/scene.components',
     license: 'MIT',
     licenseUrl: 'https://github.com/Cratis/Scene/blob/main/LICENSE',

package/data/SceneDataTable.tsx

@@ -4,9 +4,10 @@
 import { lazy } from 'react';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { ArcRuntimeBoundary, BindingKind, MissingBinding, resolveElementBinding } from '../bindings';
-import { stringArrayProperty, stringProperty } from '../properties';
+import { objectProperty, stringArrayProperty, stringProperty } from '../properties';
+import { Placeholder } from '../bindings/Placeholder';
 
-const DataTableForQuery = lazy(async () => ({ default: (await import('@cratis/components/DataTables')).DataTableForQuery }));
+const DataTableForQuery = lazy(async () => ({ default: (await import('../bindings/ArcBoundComponents')).BoundDataTable }));
 
 /**
  * The `Cratis.Components:dataTable` component, also registered as `table` - `DataTableForQuery` from
@@ -19,6 +20,9 @@ const DataTableForQuery = lazy(async () => ({ default: (await import('@cratis/co
  * back into it, where PrimeReact's `DataTable` is handed rows and knows nothing about where they came from.
  *
  * The `query` property names an Arc query proxy; the columns come from the `content` slot.
+ * Optional `queryArguments` is an explicit object forwarded unchanged to that proxy. Invalid values
+ * render a placeholder rather than accidentally executing a query without its arguments. This remains
+ * a collection table; forwarding arguments does not make optional single-result queries compatible.
  *
  * There is deliberately no `clientFiltering` property. `@cratis/components` 3.0.0 still accepts the prop
  * so existing call sites compile, but it no longer does anything - filtering is always applied to the
@@ -30,10 +34,16 @@ export function SceneDataTable({ element, slots }: RegisteredComponentProps) {
     const { name, target } = resolveElementBinding(element, BindingKind.Query);
     if (!target) return <MissingBinding element={element} kind={BindingKind.Query} name={name} />;
 
+    const queryArguments = objectProperty(element.properties, 'queryArguments');
+    if (element.properties.queryArguments !== undefined && queryArguments === undefined) {
+        return <Placeholder element={element} problem='Invalid queryArguments: expected an object' />;
+    }
+
     return (
         <ArcRuntimeBoundary>
             <DataTableForQuery
                 query={target}
+                {...(queryArguments === undefined ? {} : { queryArguments })}
                 emptyMessage={stringProperty(element.properties, 'emptyMessage') ?? ''}
                 dataKey={stringProperty(element.properties, 'dataKey')}
                 globalFilterFields={stringArrayProperty(element.properties, 'globalFilterFields')}

package/data/SceneObservableDataTable.tsx

@@ -7,7 +7,7 @@ import { ArcRuntimeBoundary, BindingKind, MissingBinding, resolveElementBinding
 import { stringArrayProperty, stringProperty } from '../properties';
 
 const DataTableForObservableQuery = lazy(async () => ({
-    default: (await import('@cratis/components/DataTables')).DataTableForObservableQuery,
+    default: (await import('../bindings/ArcBoundComponents')).BoundObservableDataTable,
 }));
 
 /**

package/data/SceneSingleResult.tsx

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { lazy } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { ArcRuntimeBoundary, BindingKind, MissingBinding, resolveElementBinding } from '../bindings';
+import { booleanProperty, objectProperty, stringProperty } from '../properties';
+import { SingleResultStatus } from './SingleResultStatus';
+
+const SingleResultRuntime = lazy(() => import('./SingleResultRuntime'));
+
+/** Read-only scalar field of an optional single model; the host owns and commits the input. */
+export function SceneSingleResult({ element }: RegisteredComponentProps) {
+    const { name, target } = resolveElementBinding(element, BindingKind.Query);
+    if (!target) return <MissingBinding element={element} kind={BindingKind.Query} name={name} />;
+
+    // Nothing, including loading Arc, happens until the host explicitly commits its input.
+    if (!element.isEnabled || booleanProperty(element.properties, 'enabled') !== true) {
+        return <SingleResultStatus state='idle' />;
+    }
+
+    const queryArguments = objectProperty(element.properties, 'queryArguments');
+    const resultField = stringProperty(element.properties, 'resultField');
+    if (!queryArguments || !resultField) return <SingleResultStatus state='failure' />;
+
+    return <ArcRuntimeBoundary>
+        <SingleResultRuntime query={target} queryArguments={queryArguments} resultField={resultField} />
+    </ArcRuntimeBoundary>;
+}

package/data/SingleResultRuntime.tsx

@@ -0,0 +1,89 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useContext, useEffect, useMemo, useState } from 'react';
+import { ArcContext } from '@cratis/arc.react';
+import type { QueryFor } from '@cratis/arc/queries';
+import type { BoundConstructor } from '../bindings/BoundConstructor';
+import { SingleResultStatus } from './SingleResultStatus';
+
+interface Props {
+    query: BoundConstructor;
+    queryArguments: Record<string, unknown>;
+    resultField: string;
+}
+
+type Outcome = { state: 'failure' | 'notFound' } | { state: 'success'; value: string };
+
+/**
+ * Private execution owner. Arc owns validation, routing, HTTP and deserialization; this component
+ * owns only request lifetime and presentation. No shared cache can hand B the result belonging to A.
+ */
+export default function SingleResultRuntime({ query, queryArguments, resultField }: Props) {
+    const arc = useContext(ArcContext);
+    const { microservice, apiBasePath, origin, httpHeadersCallback, queryVersion } = arc;
+    // Identity is deliberate: hosts replace immutable committed arguments rather than mutating them.
+    const request = useMemo(() => ({ query, queryArguments, resultField, microservice, apiBasePath, origin, httpHeadersCallback, queryVersion }),
+        [query, queryArguments, resultField, microservice, apiBasePath, origin, httpHeadersCallback, queryVersion]);
+    const [settled, setSettled] = useState<{ request: typeof request; outcome: Outcome }>();
+
+    useEffect(() => {
+        // Each effect setup is a generation, including StrictMode's setup/cleanup/setup replay.
+        let current = true;
+        let instance: QueryFor<unknown, Record<string, unknown>> | undefined;
+        const publish = (outcome: Outcome) => {
+            if (current) setSettled({ request, outcome });
+        };
+        const execute = async () => {
+            try {
+                // The registry intentionally stores constructors without an eager Arc dependency.
+                instance = new request.query() as QueryFor<unknown, Record<string, unknown>>;
+                if (instance.enumerable !== false) {
+                    publish({ state: 'failure' });
+                    return;
+                }
+                instance.setMicroservice(request.microservice);
+                instance.setApiBasePath(request.apiBasePath ?? '');
+                instance.setOrigin(request.origin ?? '');
+                instance.setHttpHeadersCallback(request.httpHeadersCallback ?? (() => ({})));
+                // Native perform validates required arguments and proxy rules before HTTP. No copying,
+                // defaults, business validation, route construction or array wrapping happens here.
+                const result = await instance.perform(request.queryArguments);
+                if (!current) return;
+                if (result.isSuccess !== true || result.isAuthorized !== true || result.isValid !== true || result.hasExceptions !== false || result.isReady === false) {
+                    publish({ state: 'failure' });
+                    return;
+                }
+                if (result.data === null || result.data === undefined) {
+                    publish({ state: 'notFound' });
+                    return;
+                }
+                if (typeof result.data !== 'object' || Array.isArray(result.data)) {
+                    publish({ state: 'failure' });
+                    return;
+                }
+                // Only one own data field, never a path, inherited member, getter or expression.
+                const descriptor = Object.getOwnPropertyDescriptor(result.data, request.resultField);
+                const value: unknown = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+                if (typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))) {
+                    publish({ state: 'success', value: String(value) });
+                } else {
+                    publish({ state: 'failure' });
+                }
+            } catch {
+                // Includes native AbortError rejections. Disposed generations cannot publish or leak
+                // an unhandled promise, even when the HTTP boundary ignores cancellation.
+                publish({ state: 'failure' });
+            }
+        };
+        void execute();
+        return () => {
+            current = false;
+            instance?.abortController?.abort();
+        };
+    }, [request]);
+
+    // Mask old data during the render that changes inputs, before effect cleanup/setup runs.
+    if (settled?.request !== request) return <SingleResultStatus state='loading' />;
+    return <SingleResultStatus {...settled.outcome} />;
+}

package/data/SingleResultStatus.tsx

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+type State = 'idle' | 'loading' | 'notFound' | 'failure' | 'success';
+
+const messages = { idle: 'Idle', loading: 'Loading', notFound: 'Not found', failure: 'Unable to load result', success: '' };
+
+/** Internal shared presentation; never exposes query exception messages or server stack traces. */
+export function SingleResultStatus({ state, value }: { state: State; value?: string }) {
+    return <span role={state === 'failure' ? 'alert' : 'status'} data-scene-single-result={state}>
+        {state === 'success' ? value : messages[state]}
+    </span>;
+}