@cratis/scene.components 3.6.0 → 3.7.0

package/for_cratisComponentsPackage/when_declaring_command_form_peers.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { expect } from 'vitest';
+
+// The workspace test command runs from this package root; do not rely on Vite's virtual import.meta.url.
+const packageJson = JSON.parse(readFileSync('package.json', 'utf8')) as {
+    name: string;
+    peerDependencies: Record<string, string>;
+    peerDependenciesMeta: Record<string, { optional?: boolean }>;
+};
+
+describe('when declaring native command form peers', () => {
+    it('requires the published footer and native custom-error execution contracts', () => {
+        expect(packageJson.name).toBe('@cratis/scene.components');
+        expect(packageJson.peerDependencies['@cratis/components']).toBe('^4.13.0');
+        expect(packageJson.peerDependencies['@cratis/arc']).toBe('^22.19.1');
+        expect(packageJson.peerDependencies['@cratis/arc.react']).toBe('^22.19.1');
+    });
+
+    it('keeps Arc optional for an unbound design-time preview', () => {
+        expect(packageJson.peerDependenciesMeta['@cratis/arc'].optional).toBe(true);
+        expect(packageJson.peerDependenciesMeta['@cratis/arc.react'].optional).toBe(true);
+    });
+});

package/forms/CommandFormRuntime.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 type { ComponentType, ReactNode } from 'react';
+import { AutoCommandForm } from '@cratis/components/CommandForm';
+import { CommandForm } from '@cratis/arc.react/commands';
+import { Guid } from '@cratis/fundamentals';
+import type { BoundConstructor } from '../bindings';
+import type { CommandInput } from './commandInputs';
+import { CommandFormSubmit } from './CommandFormSubmit';
+import { ExplicitCommandField } from './ExplicitCommandField';
+
+interface CommandFormRuntimeProps {
+    command: BoundConstructor;
+    inputs?: CommandInput[];
+    exclude?: string[];
+    submitLabel: string;
+}
+
+// Runtime bindings erase the proxy's keys; the optional footer is a Components >=4.13 contract.
+const NativeAutoCommandForm = AutoCommandForm as unknown as ComponentType<{
+    command: BoundConstructor;
+    exclude?: string[];
+    footer?: ReactNode;
+}>;
+
+type Descriptor = { name: string; type: unknown; isOptional: boolean };
+
+/** Verify the whole command before mounting any native form: partial forms must never execute. */
+function capability(command: BoundConstructor, inputs?: CommandInput[], exclude?: string[]): string | undefined {
+    let descriptors: unknown;
+    try { descriptors = (new command() as { propertyDescriptors?: unknown }).propertyDescriptors; }
+    catch { return 'Unable to inspect command proxy'; }
+    if (!Array.isArray(descriptors)) return 'Command proxy has no property descriptors';
+    const byName = new Map<string, Descriptor>();
+    for (const descriptor of descriptors) {
+        if (!descriptor || typeof descriptor.name !== 'string' || !descriptor.name ||
+            typeof descriptor.isOptional !== 'boolean' || byName.has(descriptor.name)) return 'Ambiguous or invalid command property descriptors';
+        byName.set(descriptor.name, descriptor);
+    }
+    if (inputs) {
+        for (const input of inputs) {
+            const descriptor = byName.get(input.property);
+            if (!descriptor) return `Unknown command property '${input.property}'`;
+            if (descriptor.type !== (input.type === 'guid' ? Guid : String)) return `Command property '${input.property}' type does not match '${input.type}'`;
+        }
+        for (const descriptor of byName.values()) {
+            if (!descriptor.isOptional && !inputs.some(input => input.property === descriptor.name)) return `Required command property '${descriptor.name}' has no input`;
+        }
+    } else {
+        for (const descriptor of byName.values()) {
+            if (!descriptor.isOptional && (exclude?.includes(descriptor.name) ||
+                ![String, Number, Boolean, Date].includes(descriptor.type as typeof String))) {
+                return `Required command property '${descriptor.name}' has no supported automatic field; declare inputs`;
+            }
+        }
+    }
+    return undefined;
+}
+
+/** Private lazy entry point: importing the Scene registry must not import Arc. */
+export default function CommandFormRuntime({ command, inputs, exclude, submitLabel }: CommandFormRuntimeProps) {
+    const error = capability(command, inputs, exclude);
+    if (error) return <div role='alert'>{error}</div>;
+    // The registry's never-argument constructor is erased; Arc creates this checked proxy with no args.
+    if (inputs) return <CommandForm command={command as unknown as new () => object} showTitles={false}>
+        {inputs.map(input => <ExplicitCommandField key={input.property} input={input} />)}
+        <CommandFormSubmit label={submitLabel} />
+    </CommandForm>;
+    return <NativeAutoCommandForm command={command} exclude={exclude} footer={<CommandFormSubmit label={submitLabel} />} />;
+}

package/forms/CommandFormSubmit.tsx

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useCommandFormContext } from '@cratis/arc.react/commands';
+
+interface CommandFormSubmitProps {
+    label: string;
+}
+
+/** Internal footer child; only rendered under the native form's context. */
+export function CommandFormSubmit({ label }: CommandFormSubmitProps) {
+    const { isExecuting, isAuthorized } = useCommandFormContext();
+    // Do not gate on isValid: submitting untouched invalid fields must reveal native validation.
+    // No click handler: the containing Arc form owns submission, validation and execution.
+    return <button type='submit' disabled={isExecuting || !isAuthorized} aria-busy={isExecuting}>{label}</button>;
+}

package/forms/ExplicitCommandField.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useId, useLayoutEffect, useRef, useState } from 'react';
+import { asCommandFormField, useCommandFormContext } from '@cratis/arc.react/commands';
+import { Guid } from '@cratis/fundamentals';
+import type { CommandInput } from './commandInputs';
+
+interface TextProps {
+    value: unknown;
+    onChange: (value: unknown) => void;
+    onBlur?: () => void;
+    invalid: boolean;
+    required: boolean;
+    errors: string[];
+    label: string;
+    property: string;
+    guid: boolean;
+}
+
+function TextControl({ value, onChange, onBlur, invalid, required, errors, label, property, guid }: TextProps) {
+    const id = useId();
+    const context = useCommandFormContext();
+    const { setCustomFieldError } = context;
+    // Keep the latest native getter: the context snapshot can be stale when another field sets an
+    // error and this field unmounts in the same event.
+    const contextRef = useRef(context);
+    contextRef.current = context;
+    // The draft is intentionally independent of the typed proxy value: malformed text must never
+    // reappear as a stale previously valid Guid in the command's serialized payload.
+    const [draft, setDraft] = useState(() => value instanceof Guid && !value.equals(Guid.empty) ? value.toString() : '');
+    const draftRef = useRef(draft);
+    const ownedError = useRef<string | undefined>(undefined);
+    const updateError = (error: string | undefined) => {
+        const current = contextRef.current.getFieldError(property);
+        // Do not replace or erase another producer's error for this field.
+        if (ownedError.current !== undefined && current !== ownedError.current) {
+            ownedError.current = undefined;
+            return;
+        }
+        if (ownedError.current === undefined && Object.hasOwn(contextRef.current.customFieldErrors, property)) return;
+        if (error === undefined && ownedError.current === undefined) return;
+        ownedError.current = error;
+        setCustomFieldError(property, error);
+    };
+    // A label/required change must recalculate the message without disposing the field's error.
+    // Only a different field/type or an actual unmount relinquishes ownership.
+    useLayoutEffect(() => () => {
+        if (ownedError.current !== undefined && contextRef.current.getFieldError(property) === ownedError.current) {
+            contextRef.current.setCustomFieldError(property, undefined);
+        }
+        ownedError.current = undefined;
+    }, [property, guid]);
+    useLayoutEffect(() => {
+        if (guid) {
+            const current = draftRef.current || (value instanceof Guid && !value.equals(Guid.empty) ? value.toString() : '');
+            updateError(!current ? required ? `${label} is required` : undefined :
+                !Guid.isGuid(current) ? `${label} must be a valid GUID` : undefined);
+        }
+    }, [guid, required, property, label, setCustomFieldError]);
+    const text = guid ? draft : typeof value === 'string' ? value : '';
+    return <div>
+        <label htmlFor={id}>{label}</label>
+        <input id={id} name={property} type='text' required={required} value={text}
+            aria-invalid={invalid} aria-describedby={errors.length ? `${id}-error` : undefined}
+            onBlur={onBlur} onChange={event => {
+                const next = event.currentTarget.value;
+                if (!guid) { onChange(next); return; }
+                draftRef.current = next;
+                setDraft(next);
+                const error = !next ? required ? `${label} is required` : undefined : !Guid.isGuid(next) ? `${label} must be a valid GUID` : undefined;
+                // A malformed draft clears the previously typed value, not just its display.
+                onChange(error || !next ? undefined : Guid.parse(next));
+                updateError(error);
+            }} />
+        {errors.length > 0 && <div id={`${id}-error`} role='alert'>{errors[0]}</div>}
+    </div>;
+}
+
+const NativeTextField = asCommandFormField<TextProps>(TextControl, { defaultValue: '' });
+
+/** Opaque child is self-bound by Arc's native runtime binding, with an exact fieldName. */
+export function ExplicitCommandField({ input }: { input: CommandInput }) {
+    return <NativeTextField fieldName={input.property} value={(command: Record<string, unknown>) => command[input.property]}
+        property={input.property} guid={input.type === 'guid'} label={input.label} title={input.label} />;
+}

package/forms/SceneCommandForm.tsx

@@ -1,45 +1,48 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { ComponentType, lazy } from 'react';
+import { lazy } from 'react';
 import { RegisteredComponentProps } from '@cratis/scene.react';
-import { ArcRuntimeBoundary, BindingKind, BoundConstructor, MissingBinding, resolveElementBinding } from '../bindings';
-import { stringArrayProperty } from '../properties';
+import { ArcRuntimeBoundary, BindingKind, MissingBinding, resolveElementBinding } from '../bindings';
+import type { BoundConstructor } from '../bindings';
+import { stringArrayProperty, stringProperty } from '../properties';
+import { commandInputs } from './commandInputs';
 
-interface AutoCommandFormElementProps {
-    command: BoundConstructor;
-    exclude?: string[];
-}
+const CommandFormRuntime = lazy(() => import('./CommandFormRuntime'));
 
-/**
- * `AutoCommandForm` types `exclude` as `(keyof TCommand)[]`, which collapses to `never[]` when the
- * command type is only known at runtime - as it always is here, since the class arrives from the binding
- * registry rather than from a type annotation. The conversion states the shape this adapter actually
- * passes; the underlying component reads `exclude` as property names either way.
- */
-const AutoCommandForm = lazy(async () => ({
-    default: (await import('@cratis/components/CommandForm')).AutoCommandForm as unknown as ComponentType<AutoCommandFormElementProps>,
-}));
+// Arc's useCommand constructs the proxy only on mount. Key by the actual registered class,
+// not its Scene name (which may be re-registered with a different route or roles).
+const commandKeys = new WeakMap<BoundConstructor, number>();
+let nextCommandKey = 0;
+function commandKey(command: BoundConstructor): number {
+    let key = commandKeys.get(command);
+    if (key === undefined) {
+        key = ++nextCommandKey;
+        commandKeys.set(command, key);
+    }
+    return key;
+}
 
 /**
- * The `Cratis.Components:commandForm` component - `AutoCommandForm` from `@cratis/components/CommandForm`.
- *
- * `AutoCommandForm` rather than `CommandForm`, because a screen that had to list every field by hand
- * would go stale the moment a property is added to the command on the backend. `AutoCommandForm` reads
- * the command's own property descriptors and picks a field component per property type, so the form
- * follows the command - which is the same guarantee Arc's generated proxies give the rest of the stack.
- *
- * A screen that does want to place fields itself puts the field components from this package in the
- * `content` slot and names them individually; `exclude` keeps `AutoCommandForm` from generating a second
- * copy of anything placed that way.
+ * Auto mode follows supported native proxy descriptors; opt-in inputs bind exactly named fields
+ * inside a single native Arc form. Neither mode consumes the content slot.
  */
 export function SceneCommandForm({ element }: RegisteredComponentProps) {
     const { name, target } = resolveElementBinding(element, BindingKind.Command);
     if (!target) return <MissingBinding element={element} kind={BindingKind.Command} name={name} />;
 
+    const inputs = Object.hasOwn(element.properties, 'inputs') ? commandInputs(element.properties) : undefined;
+    if (Object.hasOwn(element.properties, 'inputs') && !inputs) return <div role='alert'>Invalid command form inputs declaration</div>;
+
     return (
         <ArcRuntimeBoundary>
-            <AutoCommandForm command={target} exclude={stringArrayProperty(element.properties, 'exclude')} />
+            <CommandFormRuntime
+                key={commandKey(target)}
+                command={target}
+                inputs={inputs}
+                exclude={stringArrayProperty(element.properties, 'exclude')}
+                submitLabel={stringProperty(element.properties, 'submitLabel') ?? 'Submit'}
+            />
         </ArcRuntimeBoundary>
     );
 }

package/forms/commandInputs.ts

@@ -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 { arrayProperty, objectProperty, stringProperty } from '../properties';
+
+/** Exact, case-sensitive names from a generated command's propertyDescriptors. */
+export interface CommandInput {
+    property: string;
+    type: 'string' | 'guid';
+    label: string;
+}
+
+/** An absent declaration selects legacy auto mode; a present but invalid declaration never does. */
+export function commandInputs(properties: Record<string, unknown>): CommandInput[] | undefined {
+    const values = arrayProperty(properties, 'inputs');
+    if (!values?.length) return undefined;
+    const inputs: CommandInput[] = [];
+    const seen = new Set<string>();
+    for (const value of values) {
+        const input = objectProperty({ value }, 'value');
+        if (!input || Object.keys(input).some(key => !['property', 'type', 'label'].includes(key))) return undefined;
+        const property = stringProperty(input, 'property');
+        const label = stringProperty(input, 'label');
+        if (!property?.trim() || !label?.trim() || (input.type !== 'string' && input.type !== 'guid') || seen.has(property)) return undefined;
+        seen.add(property);
+        inputs.push({ property, type: input.type, label });
+    }
+    return inputs;
+}

package/forms/for_SceneCommandForm/given/RecordNote.ts

@@ -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 { Command, CommandValidator } from '@cratis/arc/commands';
+import { PropertyDescriptor } from '@cratis/arc/reflection';
+
+class NoteValidator extends CommandValidator<{ subject: string }> {
+    constructor() {
+        super();
+        this.ruleFor(command => command.subject).notEmpty().withMessage('Subject is required');
+    }
+}
+
+/** Synthetic proxy: execution, serialization and validation are all native Arc. */
+export class RecordNote extends Command {
+    readonly route: string = '/synthetic/notes';
+    readonly propertyDescriptors = [
+        new PropertyDescriptor('subject', String),
+        new PropertyDescriptor('internalValue', String, true),
+    ];
+    readonly requestParameters = [];
+    readonly validation = new NoteValidator();
+    subject = '';
+    internalValue = 'proxy default';
+    constructor() { super(Object, false); }
+}
+
+export class RestrictedNote extends RecordNote {
+    readonly roles = ['note-writer'];
+}
+
+export function successfulResponse() {
+    return { status: 200, json: async () => ({
+        isSuccess: true, isAuthorized: true, isValid: true, hasExceptions: false,
+        validationResults: [], exceptionMessages: [], exceptionStackTrace: '', response: {},
+    }) } as Response;
+}

package/forms/for_SceneCommandForm/given/StartProject.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Command, CommandValidator } from '@cratis/arc/commands';
+import { PropertyDescriptor } from '@cratis/arc/reflection';
+import { Guid } from '@cratis/fundamentals';
+
+class ProjectValidator extends CommandValidator<{ name: string }> {
+    constructor() {
+        super();
+        this.ruleFor(command => command.name).notEmpty().withMessage('Name is required');
+    }
+}
+
+/** Generated-shape proxy: native execution and serialization, only fetch is substituted. */
+export class StartProject extends Command {
+    readonly route: string = '/synthetic/projects';
+    readonly propertyDescriptors = [new PropertyDescriptor('projectId', Guid), new PropertyDescriptor('name', String)];
+    readonly requestParameters = [];
+    readonly validation = new ProjectValidator();
+    projectId: Guid = Guid.empty;
+    name = '';
+    constructor() { super(Object, false); }
+}
+
+export class RestrictedProject extends StartProject {
+    readonly roles = ['project-writer'];
+}
+
+export class OptionalUnsupported extends StartProject {
+    readonly propertyDescriptors = [new PropertyDescriptor('projectId', Guid), new PropertyDescriptor('name', String), new PropertyDescriptor('details', Object, true)];
+    details?: object;
+}
+
+export class RequiredUnsupported extends OptionalUnsupported {
+    readonly propertyDescriptors = [new PropertyDescriptor('projectId', Guid), new PropertyDescriptor('name', String), new PropertyDescriptor('details', Object)];
+}
+
+export class AmbiguousProject extends StartProject {
+    readonly propertyDescriptors = [new PropertyDescriptor('projectId', Guid), new PropertyDescriptor('name', String), new PropertyDescriptor('projectId', Guid)];
+}

package/forms/for_SceneCommandForm/when_forwarding_to_the_lazy_runtime.tsx

@@ -0,0 +1,69 @@
+// 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 { vi } from 'vitest';
+import { externalComponent } from '../../given';
+
+// This seam captures adapter inputs only. It does not simulate AutoCommandForm or its footer.
+describe('when forwarding command forms to the lazy runtime', () => {
+    const received = vi.fn<(props: Record<string, unknown>) => void>();
+    const loaded = vi.fn();
+    let bindings: typeof import('../../bindings/bindingRegistry');
+    let Form: typeof import('../SceneCommandForm').SceneCommandForm;
+    class Original {}
+    class Replacement {}
+
+    beforeEach(async () => {
+        vi.resetModules();
+        received.mockClear();
+        loaded.mockClear();
+        vi.doMock('../CommandFormRuntime', () => {
+            loaded();
+            return { default: (props: Record<string, unknown>) => { received(props); return <span>Runtime boundary</span>; } };
+        });
+        bindings = await import('../../bindings/bindingRegistry');
+        bindings.clearBindings();
+        ({ SceneCommandForm: Form } = await import('../SceneCommandForm'));
+    });
+
+    afterEach(() => {
+        cleanup();
+        bindings.clearBindings();
+        vi.doUnmock('../CommandFormRuntime');
+        vi.resetModules();
+    });
+
+    it('should preserve the exact registered constructor, exclusions and explicit label', async () => {
+        bindings.registerCommand('RecordNote', Original);
+        const exclude = ['internalValue'];
+        await act(async () => { render(<Form element={externalComponent('Cratis.Components:commandForm', {
+            command: 'RecordNote', exclude, submitLabel: 'Record note',
+        })} slots={{}} />); });
+        received.mock.calls.at(-1)![0].should.deep.equal({ command: Original, exclude, inputs: undefined, submitLabel: 'Record note' });
+    });
+
+    for (const submitLabel of [undefined, 42, false]) {
+        it(`should default a missing or non-string label (${String(submitLabel)}) to Submit`, async () => {
+            bindings.registerCommand('RecordNote', Original);
+            await act(async () => { render(<Form element={externalComponent('Cratis.Components:commandForm', {
+                command: 'RecordNote', exclude: 'not-an-array', submitLabel,
+            })} slots={{}} />); });
+            received.mock.calls.at(-1)![0].should.deep.equal({ command: Original, exclude: undefined, inputs: undefined, submitLabel: 'Submit' });
+        });
+    }
+
+    it('should preserve legacy last-registration-wins command binding', async () => {
+        bindings.registerCommand('RecordNote', Original);
+        bindings.registerCommand('RecordNote', Replacement);
+        await act(async () => { render(<Form element={externalComponent('Cratis.Components:commandForm', { command: 'RecordNote' })} slots={{}} />); });
+        (received.mock.calls.at(-1)![0].command === Replacement).should.equal(true);
+    });
+
+    it('should keep an unbound preview Arc-free even when a query has that name', async () => {
+        bindings.registerQuery('RecordNote', Original);
+        await act(async () => { render(<Form element={externalComponent('Cratis.Components:commandForm', { command: 'RecordNote' })} slots={{}} />); });
+        Boolean(screen.getByText("Unresolved command binding 'RecordNote' on Cratis.Components:commandForm")).should.equal(true);
+        loaded.mock.calls.should.have.lengthOf(0);
+    });
+});

package/forms/for_SceneCommandForm/when_native_custom_field_errors_block_submission.tsx

@@ -0,0 +1,33 @@
+// 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, fireEvent, render, screen } from '@testing-library/react';
+import { vi } from 'vitest';
+import { CommandForm } from '@cratis/arc.react/commands';
+import { InputTextField } from '@cratis/components/CommandForm';
+import { CommandFormSubmit } from '../CommandFormSubmit';
+import { RecordNote, successfulResponse } from './given/RecordNote';
+
+// Independent native prerequisite gate: Arc PR #2724 (expected 22.19.1), not a Scene workaround.
+// This does not exercise or simulate AutoCommandForm's forthcoming footer seam.
+describe('when native custom field errors block submission', () => {
+    const fetch = vi.fn<typeof globalThis.fetch>();
+    beforeEach(() => { fetch.mockReset(); fetch.mockResolvedValue(successfulResponse()); vi.stubGlobal('fetch', fetch); });
+    afterEach(() => { cleanup(); vi.unstubAllGlobals(); });
+
+    it('should leave submit enabled for feedback but let the native form reject a custom field error', async () => {
+        await act(async () => { render(<CommandForm command={RecordNote}
+            onFieldValidate={() => 'Subject is rejected by the field'}>
+            <InputTextField value={(command: RecordNote) => command.subject} title='Subject' />
+            <CommandFormSubmit label='Record note' />
+        </CommandForm>); });
+        const input = screen.getByRole('textbox', { name: 'Subject' });
+        fireEvent.change(input, { target: { value: 'Passes the command validator' } });
+        await act(async () => { fireEvent.blur(input); });
+        (await screen.findAllByText('Subject is rejected by the field')).length.should.be.greaterThan(0);
+        const button = screen.getByRole<HTMLButtonElement>('button', { name: 'Record note' });
+        button.disabled.should.equal(false);
+        await act(async () => { fireEvent.click(button); });
+        fetch.mock.calls.should.have.lengthOf(0);
+    });
+});

package/forms/for_SceneCommandForm/when_preserving_guid_error_ownership.tsx

@@ -0,0 +1,50 @@
+// 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, fireEvent, render, screen } from '@testing-library/react';
+import { CommandForm, useCommandFormContext } from '@cratis/arc.react/commands';
+import { Guid } from '@cratis/fundamentals';
+import { PropertyDescriptor } from '@cratis/arc/reflection';
+import { ExplicitCommandField } from '../ExplicitCommandField';
+import { StartProject } from './given/StartProject';
+
+class OptionalProject extends StartProject {
+    readonly propertyDescriptors = [new PropertyDescriptor('projectId', Guid, true), new PropertyDescriptor('name', String)];
+}
+
+const input = { property: 'projectId', type: 'guid' as const, label: 'Project ID' };
+
+describe('native explicit Guid field error ownership', () => {
+    afterEach(cleanup);
+
+    it('leaves a caller-owned error intact when the invalid field unmounts in the same event', async () => {
+        let context!: ReturnType<typeof useCommandFormContext>;
+        function Capture() { context = useCommandFormContext(); return null; }
+        function form(show: boolean) {
+            return <CommandForm command={StartProject}><Capture />{show && <ExplicitCommandField input={input} />}</CommandForm>;
+        }
+        const result = render(form(true));
+        fireEvent.change(screen.getByRole('textbox', { name: 'Project ID' }), { target: { value: 'bad' } });
+        context.getFieldError('projectId')!.should.equal('Project ID must be a valid GUID');
+        await act(async () => {
+            context.setCustomFieldError('projectId', 'Caller-owned error');
+            result.rerender(form(false));
+        });
+        context.getFieldError('projectId')!.should.equal('Caller-owned error');
+    });
+
+    it('clears its own malformed optional Guid error on unmount', async () => {
+        let context!: ReturnType<typeof useCommandFormContext>;
+        function Capture() { context = useCommandFormContext(); return null; }
+        function form(show: boolean) {
+            return <CommandForm command={OptionalProject}><Capture />{show && <ExplicitCommandField input={input} />}</CommandForm>;
+        }
+        const result = render(form(true));
+        await act(async () => {
+            fireEvent.change(screen.getByRole('textbox', { name: 'Project ID' }), { target: { value: 'bad' } });
+            context.getFieldError('projectId')!.should.equal('Project ID must be a valid GUID');
+            result.rerender(form(false));
+        });
+        (Object.hasOwn(context.customFieldErrors, 'projectId')).should.equal(false);
+    });
+});

package/forms/for_SceneCommandForm/when_rendering_submit_in_native_context.tsx

@@ -0,0 +1,56 @@
+// 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, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { vi } from 'vitest';
+import { CommandForm } from '@cratis/arc.react/commands';
+import { InputTextField } from '@cratis/components/CommandForm';
+import { CommandFormSubmit } from '../CommandFormSubmit';
+import { RecordNote, RestrictedNote, successfulResponse } from './given/RecordNote';
+
+// Exercise the private child with REAL Arc context. This does not claim AutoCommandForm footer support.
+describe('when rendering the submit child inside native CommandForm', () => {
+    const fetch = vi.fn<typeof globalThis.fetch>();
+    beforeEach(() => { fetch.mockReset(); fetch.mockResolvedValue(successfulResponse()); vi.stubGlobal('fetch', fetch); });
+    afterEach(() => { cleanup(); vi.unstubAllGlobals(); });
+
+    it('should let native submit expose invalid untouched fields without HTTP', async () => {
+        await act(async () => { render(<CommandForm command={RecordNote}>
+            <InputTextField value={(command: RecordNote) => command.subject} title='Subject' />
+            <CommandFormSubmit label='Record note' />
+        </CommandForm>); });
+        const button = screen.getByRole<HTMLButtonElement>('button', { name: 'Record note' });
+        button.disabled.should.equal(false);
+        await act(async () => { fireEvent.click(button); });
+        (await screen.findAllByText('Subject is required')).length.should.be.greaterThan(0);
+        fetch.mock.calls.should.have.lengthOf(0);
+    });
+
+    it('should follow native busy state through completion without executing directly', async () => {
+        let complete!: (response: Response) => void;
+        fetch.mockReturnValueOnce(new Promise<Response>(resolve => { complete = resolve; }));
+        await act(async () => { render(<CommandForm command={RecordNote} initialValues={{ subject: 'Valid' }}>
+            <CommandFormSubmit label='Record note' />
+        </CommandForm>); });
+        const button = screen.getByRole<HTMLButtonElement>('button', { name: 'Record note' });
+        button.disabled.should.equal(false);
+        await act(async () => { fireEvent.click(button); });
+        await waitFor(() => button.disabled.should.equal(true));
+        button.getAttribute('aria-busy')!.should.equal('true');
+        fireEvent.click(button);
+        fetch.mock.calls.should.have.lengthOf(1);
+        await act(async () => { complete(successfulResponse()); });
+        await waitFor(() => button.disabled.should.equal(false));
+        button.getAttribute('aria-busy')!.should.equal('false');
+    });
+
+    it('should respect native role authorization instead of deriving it in Scene', async () => {
+        await act(async () => { render(<CommandForm command={RestrictedNote}>
+            <CommandFormSubmit label='Record note' />
+        </CommandForm>); });
+        const button = screen.getByRole<HTMLButtonElement>('button', { name: 'Record note' });
+        button.disabled.should.equal(true);
+        fireEvent.click(button);
+        fetch.mock.calls.should.have.lengthOf(0);
+    });
+});