@cratis/scene.components 3.5.0 → 3.7.0

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);
+    });
+});

package/forms/for_SceneCommandForm/when_submitting_explicit_inputs.tsx

@@ -0,0 +1,189 @@
+// 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 { ArcContext } from '@cratis/arc.react';
+import { SceneElementView } from '@cratis/scene.react';
+import { clearBindings, registerCommand } from '../../bindings';
+import { cratisComponents } from '../../cratisComponents';
+import { externalComponent } from '../../given';
+import { AmbiguousProject, OptionalUnsupported, RequiredUnsupported, RestrictedProject, StartProject } from './given/StartProject';
+import { RecordNote, successfulResponse } from './given/RecordNote';
+
+const inputs = [{ property: 'projectId', type: 'guid', label: 'Project ID' }, { property: 'name', type: 'string', label: 'Name' }];
+const guid = 'AABBCCDD-1234-5678-9ABC-001122334455';
+
+function view(properties: Record<string, unknown> = {}, explicit = true) {
+    return <ArcContext.Provider value={{ origin: 'https://example.test', apiBasePath: '/backend', microservice: 'projects', httpHeadersCallback: () => ({ 'x-host': 'scene' }) }}>
+        <SceneElementView element={externalComponent('Cratis.Components:commandForm', { command: 'StartProject', ...(explicit ? { inputs } : {}), submitLabel: 'Create project', ...properties })}
+            registry={cratisComponents} resolveBinding={() => undefined} />
+    </ArcContext.Provider>;
+}
+
+describe('explicit Scene command form using native Arc proxy and execution', () => {
+    const fetch = vi.fn<typeof globalThis.fetch>();
+    beforeEach(() => { clearBindings(); registerCommand('StartProject', StartProject); fetch.mockReset(); fetch.mockResolvedValue(successfulResponse()); vi.stubGlobal('fetch', fetch); });
+    afterEach(() => { cleanup(); clearBindings(); vi.unstubAllGlobals(); });
+
+    it('rejects untouched, blank and malformed GUIDs, and blank name without HTTP; corrected fields submit the typed payload', async () => {
+        render(view());
+        const button = await screen.findByRole<HTMLButtonElement>('button', { name: 'Create project' });
+        const id = screen.getByRole<HTMLInputElement>('textbox', { name: 'Project ID' });
+        const name = screen.getByRole<HTMLInputElement>('textbox', { name: 'Name' });
+        (button.form === id.closest('form')).should.equal(true);
+        await act(async () => { fireEvent.submit(button.form!); });
+        (await screen.findAllByText('Project ID is required')).length.should.be.greaterThan(0);
+        fetch.mock.calls.should.have.lengthOf(0);
+        fireEvent.change(id, { target: { value: 'not-a-guid' } });
+        fireEvent.change(name, { target: { value: '' } });
+        await act(async () => { fireEvent.submit(button.form!); });
+        (await screen.findAllByText('Project ID must be a valid GUID')).length.should.be.greaterThan(0);
+        fetch.mock.calls.should.have.lengthOf(0);
+        fireEvent.change(id, { target: { value: guid } });
+        await act(async () => { fireEvent.submit(button.form!); });
+        (await screen.findAllByText('Name is required')).length.should.be.greaterThan(0);
+        fetch.mock.calls.should.have.lengthOf(0);
+        fireEvent.change(name, { target: { value: '  My Project  ' } });
+        await act(async () => { fireEvent.click(button); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(1));
+        const [url, request] = fetch.mock.calls[0];
+        String(url).should.equal('https://example.test/backend/synthetic/projects');
+        request!.method!.should.equal('POST');
+        JSON.parse(String(request!.body)).should.deep.equal({ projectId: guid.toLowerCase(), name: '  My Project  ' });
+        new Headers(request!.headers).get('x-host')!.should.equal('scene');
+        new Headers(request!.headers).get('x-cratis-microservice')!.should.equal('projects');
+        fireEvent.change(id, { target: { value: 'broken again' } });
+        await act(async () => { fireEvent.submit(button.form!); });
+        fetch.mock.calls.should.have.lengthOf(1);
+    });
+
+    it('keeps a typed Guid valid across a label change and executes exactly once', async () => {
+        const result = render(view());
+        await screen.findByRole('button', { name: 'Create project' });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Project ID' }), { target: { value: guid } });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Name' }), { target: { value: 'Renamed label' } });
+        result.rerender(view({ inputs: [{ ...inputs[0], label: 'Project identifier' }, inputs[1]] }));
+        const id = screen.getByRole('textbox', { name: 'Project identifier' });
+        (id as HTMLInputElement).value.should.equal(guid);
+        await act(async () => { fireEvent.click(screen.getByRole('button', { name: 'Create project' })); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(1));
+        JSON.parse(String(fetch.mock.calls[0][1]!.body)).should.deep.equal({ projectId: guid.toLowerCase(), name: 'Renamed label' });
+    });
+
+    it('keeps a malformed Guid blocked when its label changes, then submits the corrected typed value', async () => {
+        const result = render(view());
+        await screen.findByRole('button', { name: 'Create project' });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Name' }), { target: { value: 'After correction' } });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Project ID' }), { target: { value: 'not-a-guid' } });
+        (await screen.findAllByText('Project ID must be a valid GUID')).length.should.be.greaterThan(0);
+        result.rerender(view({ inputs: [{ ...inputs[0], label: 'Project identifier' }, inputs[1]] }));
+        const id = screen.getByRole<HTMLInputElement>('textbox', { name: 'Project identifier' });
+        id.value.should.equal('not-a-guid');
+        (await screen.findAllByText('Project identifier must be a valid GUID')).length.should.be.greaterThan(0);
+        (screen.queryByText('Project ID must be a valid GUID') === null).should.equal(true);
+        await act(async () => { fireEvent.submit(id.closest('form')!); });
+        fetch.mock.calls.should.have.lengthOf(0);
+        fireEvent.change(id, { target: { value: guid } });
+        await act(async () => { fireEvent.submit(id.closest('form')!); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(1));
+        JSON.parse(String(fetch.mock.calls[0][1]!.body)).should.deep.equal({ projectId: guid.toLowerCase(), name: 'After correction' });
+    });
+
+    it('remounts the native explicit proxy on a binding switch and same-name hot replacement', async () => {
+        class MovedProject extends StartProject { readonly route = '/synthetic/moved-projects'; }
+        class HotProject extends StartProject { readonly route = '/synthetic/hot-projects'; }
+        registerCommand('MovedProject', MovedProject);
+        const result = render(view());
+        await screen.findByRole('button', { name: 'Create project' });
+        result.rerender(view({ command: 'MovedProject' }));
+        await screen.findByRole('textbox', { name: 'Project ID' });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Project ID' }), { target: { value: guid } });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Name' }), { target: { value: 'Moved' } });
+        await act(async () => { fireEvent.click(screen.getByRole('button', { name: 'Create project' })); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(1));
+        String(fetch.mock.calls[0][0]).should.equal('https://example.test/backend/synthetic/moved-projects');
+        registerCommand('MovedProject', RestrictedProject);
+        result.rerender(view({ command: 'MovedProject' }));
+        const denied = await screen.findByRole<HTMLButtonElement>('button', { name: 'Create project' });
+        denied.disabled.should.equal(true);
+        fireEvent.click(denied);
+        fetch.mock.calls.should.have.lengthOf(1);
+        registerCommand('MovedProject', HotProject);
+        result.rerender(view({ command: 'MovedProject' }));
+        const allowed = await screen.findByRole<HTMLButtonElement>('button', { name: 'Create project' });
+        allowed.disabled.should.equal(false);
+        fireEvent.change(screen.getByRole('textbox', { name: 'Project ID' }), { target: { value: guid } });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Name' }), { target: { value: 'Hot' } });
+        await act(async () => { fireEvent.click(allowed); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(2));
+        String(fetch.mock.calls[1][0]).should.equal('https://example.test/backend/synthetic/hot-projects');
+    });
+
+    it('uses native authorization and executing state', async () => {
+        registerCommand('StartProject', RestrictedProject);
+        render(view());
+        const button = await screen.findByRole<HTMLButtonElement>('button', { name: 'Create project' });
+        button.disabled.should.equal(true);
+        fireEvent.click(button);
+        fetch.mock.calls.should.have.lengthOf(0);
+    });
+
+    it('reflects native execution state and blocks a second button click while pending', async () => {
+        let complete!: (response: Response) => void;
+        fetch.mockReturnValueOnce(new Promise<Response>(resolve => { complete = resolve; }));
+        render(view());
+        const button = await screen.findByRole<HTMLButtonElement>('button', { name: 'Create project' });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Project ID' }), { target: { value: guid } });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Name' }), { target: { value: 'Pending' } });
+        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));
+    });
+
+    it('blocks malformed declarations, unknown names, mismatches, uncovered and ambiguous required descriptors', async () => {
+        const invalid = [
+            { inputs: [] }, { inputs: [{ property: 'name', type: 'string', label: 'Name' }, { property: 'name', type: 'string', label: 'Again' }] },
+            { inputs: [{ property: 'PROJECTID', type: 'guid', label: 'ID' }, inputs[1]] },
+            { inputs: [{ ...inputs[0], type: 'string' }, inputs[1]] },
+            { inputs: [inputs[1]] }, { inputs: [{ ...inputs[0], type: 'number' }, inputs[1]] },
+        ];
+        for (const properties of invalid) {
+            const result = render(view(properties));
+            (await screen.findByRole('alert')).textContent!.length.should.be.greaterThan(0);
+            (screen.queryByRole('button', { name: 'Create project' }) === null).should.equal(true);
+            result.unmount();
+        }
+        registerCommand('StartProject', AmbiguousProject);
+        render(view());
+        (await screen.findByRole('alert')).textContent!.should.contain('Ambiguous');
+        fetch.mock.calls.should.have.lengthOf(0);
+    });
+
+    it('accepts optional unsupported descriptors when unbound but rejects required unsupported descriptors', async () => {
+        registerCommand('StartProject', OptionalUnsupported);
+        const result = render(view());
+        Boolean(await screen.findByRole('button', { name: 'Create project' })).should.equal(true);
+        result.unmount();
+        registerCommand('StartProject', RequiredUnsupported);
+        render(view());
+        (await screen.findByRole('alert')).textContent!.should.contain("Required command property 'details'");
+    });
+
+    it('refuses automatic forms with required GUID rather than silently dropping it', async () => {
+        render(view({}, false));
+        (await screen.findByRole('alert')).textContent!.should.contain("Required command property 'projectId'");
+        fetch.mock.calls.should.have.lengthOf(0);
+    });
+
+    it('does not allow auto exclusions to hide required supported fields', async () => {
+        registerCommand('StartProject', RecordNote);
+        render(view({ exclude: ['subject'] }, false));
+        (await screen.findByRole('alert')).textContent!.should.contain("Required command property 'subject'");
+        fetch.mock.calls.should.have.lengthOf(0);
+    });
+});

package/forms/for_SceneCommandForm/when_submitting_the_native_form.tsx

@@ -0,0 +1,120 @@
+// 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 { ArcContext } from '@cratis/arc.react';
+import { SceneElementView } from '@cratis/scene.react';
+import { clearBindings, registerCommand } from '../../bindings';
+import { cratisComponents } from '../../cratisComponents';
+import { externalComponent } from '../../given';
+import { RecordNote, RestrictedNote, successfulResponse } from './given/RecordNote';
+
+function view(properties: Record<string, unknown> = {}) {
+    return <ArcContext.Provider value={{ origin: 'https://example.test', apiBasePath: '/backend', microservice: 'notes', httpHeadersCallback: () => ({ 'x-host': 'scene' }) }}>
+        <SceneElementView element={externalComponent('Cratis.Components:commandForm', {
+            command: 'RecordNote', exclude: ['internalValue'], ...properties,
+        })} registry={cratisComponents} resolveBinding={() => undefined} />
+    </ArcContext.Provider>;
+}
+
+// No Components/form/context doubles. Components <=4.12 ignores footer: these tests MUST fail there,
+// not skip or pass by recreating the forthcoming upstream behavior. Only HTTP is substituted.
+describe('when submitting a Scene command form through native AutoCommandForm', () => {
+    const fetch = vi.fn<typeof globalThis.fetch>();
+
+    beforeEach(() => {
+        clearBindings();
+        registerCommand('RecordNote', RecordNote);
+        fetch.mockReset();
+        fetch.mockResolvedValue(successfulResponse());
+        vi.stubGlobal('fetch', fetch);
+    });
+
+    afterEach(() => { cleanup(); clearBindings(); vi.unstubAllGlobals(); });
+
+    it('should submit the actual form with a labeled button and preserve native payload and context', async () => {
+        render(view({ submitLabel: 'Record note' }));
+        const button = await screen.findByRole<HTMLButtonElement>('button', { name: 'Record note' });
+        button.type.should.equal('submit');
+        (button.form === screen.getByRole('textbox', { name: 'Subject' }).closest('form')).should.equal(true);
+        screen.queryAllByRole('textbox').should.have.lengthOf(1);
+        fireEvent.change(screen.getByRole('textbox', { name: 'Subject' }), { target: { value: 'A synthetic note' } });
+        fetch.mock.calls.should.have.lengthOf(0);
+        await act(async () => { fireEvent.click(button); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(1));
+        const [url, request] = fetch.mock.calls[0];
+        String(url).should.equal('https://example.test/backend/synthetic/notes');
+        request!.method!.should.equal('POST');
+        JSON.parse(String(request!.body)).should.deep.equal({ subject: 'A synthetic note', internalValue: 'proxy default' });
+        new Headers(request!.headers).get('x-host')!.should.equal('scene');
+        new Headers(request!.headers).get('x-cratis-microservice')!.should.equal('notes');
+    });
+
+    it('should allow untouched invalid submit to reveal native feedback and correction to execute', async () => {
+        render(view());
+        const button = await screen.findByRole<HTMLButtonElement>('button', { name: 'Submit' });
+        button.disabled.should.equal(false);
+        (screen.queryByText('Subject is required') === null).should.equal(true);
+        await act(async () => { fireEvent.click(button); });
+        (await screen.findAllByText('Subject is required')).length.should.be.greaterThan(0);
+        fetch.mock.calls.should.have.lengthOf(0);
+        button.disabled.should.equal(false);
+        fireEvent.change(screen.getByRole('textbox', { name: 'Subject' }), { target: { value: 'Corrected' } });
+        await act(async () => { fireEvent.click(button); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(1));
+    });
+
+    it('should reflect native execution until HTTP settles and prevent a second button click', async () => {
+        let complete!: (response: Response) => void;
+        fetch.mockReturnValueOnce(new Promise<Response>(resolve => { complete = resolve; }));
+        render(view());
+        const button = await screen.findByRole<HTMLButtonElement>('button', { name: 'Submit' });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Subject' }), { target: { value: 'Pending' } });
+        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('remounts the automatic native form on binding switches and same-name hot replacement', async () => {
+        class MovedNote extends RecordNote { readonly route = '/synthetic/moved-notes'; }
+        class HotNote extends RecordNote { readonly route = '/synthetic/hot-notes'; }
+        registerCommand('MovedNote', MovedNote);
+        const result = render(view());
+        await screen.findByRole('button', { name: 'Submit' });
+        result.rerender(view({ command: 'MovedNote' }));
+        await screen.findByRole('textbox', { name: 'Subject' });
+        fireEvent.change(screen.getByRole('textbox', { name: 'Subject' }), { target: { value: 'Moved' } });
+        await act(async () => { fireEvent.click(screen.getByRole('button', { name: 'Submit' })); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(1));
+        String(fetch.mock.calls[0][0]).should.equal('https://example.test/backend/synthetic/moved-notes');
+        registerCommand('MovedNote', RestrictedNote);
+        result.rerender(view({ command: 'MovedNote' }));
+        const denied = await screen.findByRole<HTMLButtonElement>('button', { name: 'Submit' });
+        denied.disabled.should.equal(true);
+        fireEvent.click(denied);
+        fetch.mock.calls.should.have.lengthOf(1);
+        registerCommand('MovedNote', HotNote);
+        result.rerender(view({ command: 'MovedNote' }));
+        const allowed = await screen.findByRole<HTMLButtonElement>('button', { name: 'Submit' });
+        allowed.disabled.should.equal(false);
+        fireEvent.change(screen.getByRole('textbox', { name: 'Subject' }), { target: { value: 'Hot' } });
+        await act(async () => { fireEvent.click(allowed); });
+        await waitFor(() => fetch.mock.calls.should.have.lengthOf(2));
+        String(fetch.mock.calls[1][0]).should.equal('https://example.test/backend/synthetic/hot-notes');
+    });
+
+    it('should disable the button when native command authorization denies the identity', async () => {
+        registerCommand('RecordNote', RestrictedNote);
+        render(view());
+        const button = await screen.findByRole<HTMLButtonElement>('button', { name: 'Submit' });
+        button.disabled.should.equal(true);
+        fireEvent.click(button);
+        fetch.mock.calls.should.have.lengthOf(0);
+    });
+});

package/forms/for_SceneQueryInputForm/ProjectLookup.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Canonical Projects/Registration/ProjectLookup/ProjectLookup.ts generated consumer shape.
+// Keep Guid parameters, descriptors, model decorators, default value and native methods intact.
+import { QueryFor, QueryResultWithState } from '@cratis/arc/queries';
+import { useQuery, useSuspenseQuery, PerformQuery, SetSorting, QueryWhen } from '@cratis/arc.react/queries';
+import { ParameterDescriptor } from '@cratis/arc/reflection';
+import { Guid, field } from '@cratis/fundamentals';
+
+export interface ProjectByIdParameters {
+    projectId: Guid;
+}
+
+export class ProjectById extends QueryFor<ProjectSummary, ProjectByIdParameters> {
+    readonly route: string = '/api/projects/registration/project-lookup/project-by-id';
+    readonly queryName: string = 'CanonicalProjects.Projects.Registration.ProjectLookup.ProjectSummary.ProjectById';
+    readonly treatWarningsAsErrors: boolean = false;
+    readonly roles: string[] = [];
+    readonly defaultValue: ProjectSummary = {} as ProjectSummary;
+
+    constructor() {
+        super(ProjectSummary, false);
+    }
+
+    get requiredRequestParameters(): string[] {
+        return ['projectId'];
+    }
+
+    readonly parameterDescriptors: ParameterDescriptor[] = [
+        new ParameterDescriptor('projectId', Guid, false),
+    ];
+
+    projectId!: Guid;
+
+    static use(args?: ProjectByIdParameters): [QueryResultWithState<ProjectSummary>, PerformQuery<ProjectByIdParameters>, SetSorting] {
+        return useQuery<ProjectSummary, ProjectById, ProjectByIdParameters>(ProjectById, args);
+    }
+
+    static useSuspense(args?: ProjectByIdParameters): [QueryResultWithState<ProjectSummary>, PerformQuery<ProjectByIdParameters>, SetSorting] {
+        return useSuspenseQuery<ProjectSummary, ProjectById, ProjectByIdParameters>(ProjectById, args);
+    }
+
+    static when(condition: boolean): QueryWhen<ProjectById, ProjectSummary, ProjectByIdParameters> {
+        return new QueryWhen<ProjectById, ProjectSummary, ProjectByIdParameters>(ProjectById, condition);
+    }
+}
+
+export class ProjectSummary {
+    @field(String)
+    name!: string;
+    @field(Guid)
+    projectId!: Guid;
+}

package/forms/for_SceneQueryInputForm/when_submitting_generated_guid_parameters.tsx

@@ -0,0 +1,188 @@
+// 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 { expect, vi } from 'vitest';
+import { ArcContext } from '@cratis/arc.react';
+import { QueryFor } from '@cratis/arc/queries';
+import { ParameterDescriptor } from '@cratis/arc/reflection';
+import { Guid } from '@cratis/fundamentals';
+import { SceneElementView } from '@cratis/scene.react';
+import { clearBindings, registerQuery, registerQueryIdentity, unregisterQueryIdentity } from '../../bindings';
+import { cratisComponents } from '../../cratisComponents';
+import { externalComponent } from '../../given';
+import { ProjectById, ProjectByIdParameters } from './ProjectLookup';
+
+const projectId = 'AB123456-7890-4ABC-8DEF-1234567890AB';
+const input = { parameter: 'projectId', type: 'string', label: 'Project identifier' };
+const identity = 'Projects/Registration/ProjectLookup/ProjectLookup.ts:ProjectById';
+const context = { microservice: 'projects', origin: 'https://example.test', apiBasePath: '' };
+
+function response(data: unknown) {
+    return { ok: true, status: 200, json: async () => ({
+        data, isSuccess: true, isAuthorized: true, isValid: true, hasExceptions: false,
+        validationResults: [], exceptionMessages: [], exceptionStackTrace: '',
+        paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+    }) } as Response;
+}
+
+function view(properties: Record<string, unknown> = {}, component = 'queryInputForm') {
+    return <ArcContext.Provider value={context}>
+        <SceneElementView element={externalComponent(`Cratis.Components:${component}`, {
+            query: 'ProjectById', inputs: [input], resultField: 'name', ...properties,
+        })} registry={cratisComponents} resolveBinding={() => undefined} />
+    </ArcContext.Provider>;
+}
+
+async function submit(value = projectId) {
+    fireEvent.change(screen.getByRole('textbox', { name: input.label }), { target: { value } });
+    await act(async () => { fireEvent.submit(screen.getByRole('form')); });
+}
+
+describe('when submitting the canonical generated Guid proxy shape through SceneElementView', () => {
+    const fetch = vi.fn<typeof globalThis.fetch>();
+
+    beforeEach(() => {
+        clearBindings();
+        registerQueryIdentity('ProjectById', identity, ProjectById);
+        fetch.mockReset();
+        fetch.mockResolvedValue(response({ name: 'Canonical project', projectId }));
+        vi.stubGlobal('fetch', fetch);
+    });
+
+    afterEach(() => { cleanup(); clearBindings(); vi.unstubAllGlobals(); });
+
+    it('keeps the generated Guid contract and inherited native perform, sending exact entered text', async () => {
+        const proxy = new ProjectById();
+        expect(proxy.perform).toBe(QueryFor.prototype.perform);
+        expect(proxy.parameterDescriptors).toEqual([new ParameterDescriptor('projectId', Guid, false)]);
+        expect(proxy.requiredRequestParameters).toEqual(['projectId']);
+        expect(proxy.defaultValue).toEqual({});
+        expect(proxy.queryName).toBe('CanonicalProjects.Projects.Registration.ProjectLookup.ProjectSummary.ProjectById');
+        render(view());
+        expect(fetch).not.toHaveBeenCalled();
+        await submit();
+        expect(await screen.findByText('Canonical project')).not.toBeNull();
+        expect(fetch).toHaveBeenCalledTimes(1);
+        const [url, init] = fetch.mock.calls[0];
+        expect(String(url)).toBe(`https://example.test/api/projects/registration/project-lookup/project-by-id?projectId=${projectId}`);
+        expect(init?.method).toBe('GET');
+        expect(new URL(String(url)).searchParams.get('projectId')).toBe(projectId);
+        expect(screen.getByRole('textbox')).toHaveProperty('value', projectId);
+    });
+
+    for (const data of [null, undefined]) {
+        it(`preserves native absence (${String(data)}) despite the generated empty-object default`, async () => {
+            fetch.mockResolvedValue(response(data));
+            render(view()); await submit();
+            expect(await screen.findByText('Not found')).not.toBeNull();
+            expect(fetch).toHaveBeenCalledTimes(1);
+        });
+    }
+
+    it('does not claim Guid descriptors enforce format: native perform sends an unformatted string unchanged', async () => {
+        render(view()); await submit(' not-a-guid ');
+        expect(await screen.findByText('Canonical project')).not.toBeNull();
+        expect(new URL(String(fetch.mock.calls[0][0])).searchParams.get('projectId')).toBe(' not-a-guid ');
+    });
+
+    it('lets an explicitly supplied pattern reject invalid Guid text before HTTP and permit correction', async () => {
+        render(view({ inputs: [{ ...input, pattern: '[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}' }] }));
+        await submit('not-a-guid');
+        expect(screen.getByRole('alert').textContent).toBe('Project identifier has an invalid format');
+        expect(fetch).not.toHaveBeenCalled();
+        expect(screen.getByRole('textbox')).toHaveProperty('value', 'not-a-guid');
+        await submit();
+        expect(await screen.findByText('Canonical project')).not.toBeNull();
+        expect(new URL(String(fetch.mock.calls[0][0])).searchParams.get('projectId')).toBe(projectId);
+    });
+
+    it('retains native required-argument validation when the form permits an empty string', async () => {
+        render(view({ inputs: [{ ...input, required: false }] })); await submit('');
+        expect(await screen.findByRole('alert')).toHaveProperty('textContent', 'Unable to load result');
+        expect(fetch).not.toHaveBeenCalled();
+    });
+
+    for (const descriptors of [
+        [new ParameterDescriptor('projectId', Number, false)],
+        [new ParameterDescriptor('projectId', Boolean, false)],
+        [new ParameterDescriptor('projectId', Object, false)],
+        [new ParameterDescriptor('projectId', Guid, true)],
+        [new ParameterDescriptor('projectId', String, true)],
+        [new ParameterDescriptor('ProjectID', Guid, false)],
+        [],
+        [new ParameterDescriptor('projectId', Guid, false), new ParameterDescriptor('projectId', String, false)],
+    ]) {
+        it(`rejects unsupported descriptor mapping before HTTP: ${descriptors.map(d => `${d.name}:${d.type.name}:${d.isEnumerable}`).join(',')}`, async () => {
+            class Incompatible extends ProjectById { readonly parameterDescriptors = descriptors; }
+            registerQueryIdentity('ProjectById', identity, Incompatible);
+            render(view()); await submit();
+            expect(await screen.findByRole('alert')).toHaveProperty('textContent', 'Unable to load result');
+            expect(screen.getByRole('textbox')).toHaveProperty('value', projectId);
+            expect(fetch).not.toHaveBeenCalled();
+        });
+    }
+
+    it('rejects an unknown extra parameter even when every required native argument is present', async () => {
+        render(view({ inputs: [input, { parameter: 'unknown', type: 'string', label: 'Unknown', required: false }] }));
+        await submit();
+        expect(await screen.findByRole('alert')).toHaveProperty('textContent', 'Unable to load result');
+        expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('demonstrates why native descriptor mapping alone cannot protect the form', async () => {
+        class Numeric extends ProjectById {
+            readonly parameterDescriptors = [new ParameterDescriptor('projectId', Number, false)];
+        }
+        const proxy = new Numeric();
+        proxy.setOrigin(context.origin);
+        // Deliberate runtime mismatch, NOT a change to the emitted consumer's parameter interface.
+        const args = { projectId: 'not-a-number', unknown: 'extra' } as unknown as ProjectByIdParameters;
+        const result = await proxy.perform(args);
+        expect(result.isSuccess).toBe(true);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        const url = new URL(String(fetch.mock.calls[0][0]));
+        expect(url.searchParams.get('projectId')).toBe('not-a-number');
+        expect(url.searchParams.get('unknown')).toBe('extra');
+    });
+
+    it('allows an identity-only registration to serve an existing singleResult with the same semantic name', async () => {
+        render(view({ queryArguments: { projectId }, enabled: true }, 'singleResult'));
+        expect(await screen.findByText('Canonical project')).not.toBeNull();
+        expect(new URL(String(fetch.mock.calls[0][0])).searchParams.get('projectId')).toBe(projectId);
+    });
+
+    it('fails visibly without selecting an ambiguous identity in an existing singleResult', () => {
+        registerQueryIdentity('ProjectById', 'Other/ProjectById', ProjectById);
+        render(view({ queryArguments: { projectId }, enabled: true }, 'singleResult'));
+        expect(screen.getByText("Unresolved query binding 'ProjectById' on Cratis.Components:singleResult")).not.toBeNull();
+        expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('resolves identity replacement and removal on an existing adapter host rerender', async () => {
+        const mounted = render(view({ queryArguments: { projectId }, enabled: true }, 'singleResult'));
+        expect(await screen.findByText('Canonical project')).not.toBeNull();
+        class Replacement extends ProjectById { readonly route = '/replacement'; }
+        act(() => { registerQueryIdentity('ProjectById', identity, Replacement); });
+        mounted.rerender(view({ queryArguments: { projectId }, enabled: true }, 'singleResult'));
+        await screen.findByText('Canonical project');
+        expect(fetch).toHaveBeenCalledTimes(2);
+        expect(new URL(String(fetch.mock.calls[1][0])).pathname).toBe('/replacement');
+        act(() => { unregisterQueryIdentity('ProjectById', identity); });
+        mounted.rerender(view({ queryArguments: { projectId }, enabled: true }, 'singleResult'));
+        expect(screen.getByText("Unresolved query binding 'ProjectById' on Cratis.Components:singleResult")).not.toBeNull();
+        expect(fetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('keeps legacy replacement authoritative for singleResult while queryInputForm rejects mixed candidates', async () => {
+        class Legacy extends ProjectById { readonly route = '/legacy'; }
+        registerQuery('ProjectById', ProjectById);
+        registerQuery('ProjectById', Legacy);
+        const mounted = render(view({ queryArguments: { projectId }, enabled: true }, 'singleResult'));
+        expect(await screen.findByText('Canonical project')).not.toBeNull();
+        expect(new URL(String(fetch.mock.calls[0][0])).pathname).toBe('/legacy');
+        mounted.rerender(view());
+        expect(screen.getByRole('alert').textContent).toContain("Ambiguous query binding 'ProjectById'");
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+});