@cratis/scene.components 3.4.0 → 3.6.0

package/for_cratisComponentsPackage/when_describing_query_input_form.ts

@@ -0,0 +1,17 @@
+// 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 { SceneQueryInputForm, cratisComponents, cratisComponentsPackageManifest, registerQueryIdentity, resolveExactQuery, type QueryInput } from '../index';
+
+describe('when describing the query input form public API', () => {
+    it('exports and registers the component advertised by the manifest', () => {
+        expect(cratisComponentsPackageManifest.components).toContain('queryInputForm');
+        expect(cratisComponents['Cratis.Components:queryInputForm']).toBe(SceneQueryInputForm);
+        expect(cratisComponentsPackageManifest.description).toContain('commits explicit string inputs on submit');
+        expect(registerQueryIdentity).toBeTypeOf('function');
+        expect(resolveExactQuery).toBeTypeOf('function');
+        const input: QueryInput = { parameter: 'projectId', type: 'string', label: 'Project identifier' };
+        expect(input.type).toBe('string');
+    });
+});

package/for_cratisComponentsPackage/when_describing_single_result.ts

@@ -0,0 +1,20 @@
+// 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 { componentRegistryKey } from '@cratis/scene.react';
+import { cratisComponents, cratisComponentsPackageName } from '../cratisComponents';
+import { cratisComponentsPackageManifest } from '../cratisComponentsPackage';
+import { SceneSingleResult } from '../data/SceneSingleResult';
+
+describe('when describing the single result view', () => {
+    it('registers the same component advertised by the manifest', () => {
+        expect(cratisComponentsPackageManifest.components).toContain('singleResult');
+        expect(cratisComponents[componentRegistryKey(cratisComponentsPackageName, 'singleResult')]).toBe(SceneSingleResult);
+    });
+
+    it('describes an explicitly enabled read-only own-field capability', () => {
+        expect(cratisComponentsPackageManifest.description).toContain('read-only scalar own resultField');
+        expect(cratisComponentsPackageManifest.description).toContain('enabled: true');
+    });
+});

package/forms/SceneQueryInputForm.tsx

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { lazy, useId, useState, useSyncExternalStore } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { ArcRuntimeBoundary, BindingKind, BoundConstructor, MissingBinding, resolveExactQuery, subscribeQueryBindings } from '../bindings';
+import { stringProperty } from '../properties';
+import { SingleResultStatus } from '../data/SingleResultStatus';
+import { QueryInput, queryInputError, queryInputs } from './queryInputs';
+
+const SingleResultRuntime = lazy(() => import('../data/SingleResultRuntime'));
+
+/** Opt-in, form-local string drafts around the existing optional-single execution owner. */
+export function SceneQueryInputForm({ element }: RegisteredComponentProps) {
+    const name = stringProperty(element.properties, 'query');
+    const target = useSyncExternalStore(subscribeQueryBindings, () => name ? resolveExactQuery(name) : undefined);
+    if (target === 'ambiguous') return <div role='alert'>Ambiguous query binding '{name}' on {element.componentName}</div>;
+    if (!target) return <MissingBinding element={element} kind={BindingKind.Query} name={name} />;
+
+    const inputs = queryInputs(element.properties);
+    const resultField = stringProperty(element.properties, 'resultField');
+    if (!inputs || !resultField) return <div role='alert'>Invalid query input form configuration</div>;
+    if (!element.isEnabled) return <SingleResultStatus state='idle' />;
+
+    // A different form declaration starts a new session; ordinary host rerenders retain drafts.
+    return <QueryInputForm key={JSON.stringify([name, inputs, resultField])}
+        query={target} inputs={inputs} resultField={resultField}
+        label={stringProperty(element.properties, 'label') ?? 'Query input'}
+        submitLabel={stringProperty(element.properties, 'submitLabel') ?? 'Search'} />;
+}
+
+interface Props {
+    query: BoundConstructor;
+    inputs: QueryInput[];
+    resultField: string;
+    label: string;
+    submitLabel: string;
+}
+
+function QueryInputForm({ query, inputs, resultField, label, submitLabel }: Props) {
+    const id = useId();
+    const [drafts, setDrafts] = useState<Record<string, string>>(() => Object.fromEntries(inputs.map(input => [input.parameter, ''])));
+    const [errors, setErrors] = useState<Record<string, string | undefined>>({});
+    const [committed, setCommitted] = useState<Record<string, string>>();
+
+    return <form aria-label={label} noValidate onSubmit={event => {
+        event.preventDefault();
+        const validation = Object.fromEntries(inputs.map(input => [input.parameter, queryInputError(input, drafts[input.parameter])]));
+        setErrors(validation);
+        if (Object.values(validation).some(Boolean)) {
+            setCommitted(undefined);
+            return;
+        }
+        // New identity even for unchanged values: repeat submit is an explicit retry. No trimming,
+        // coercion, generated identifier, property-path evaluation or query while typing.
+        setCommitted(Object.freeze(Object.fromEntries(inputs.map(input => [input.parameter, drafts[input.parameter]]))));
+    }}>
+        {inputs.map((input, index) => {
+            const controlId = `${id}-${index}`;
+            const error = Object.hasOwn(errors, input.parameter) ? errors[input.parameter] : undefined;
+            return <div key={input.parameter}>
+                <label htmlFor={controlId}>{input.label}</label>
+                <input id={controlId} name={input.parameter} type='text' required={input.required}
+                    value={drafts[input.parameter]} aria-invalid={!!error} aria-describedby={error ? `${controlId}-error` : undefined}
+                    onChange={event => {
+                        setDrafts({ ...drafts, [input.parameter]: event.currentTarget.value });
+                        setErrors({ ...errors, [input.parameter]: undefined });
+                        // Unmount synchronously on edit: runtime cleanup aborts and masks late replies.
+                        setCommitted(undefined);
+                    }} />
+                {error && <div id={`${controlId}-error`} role='alert'>{error}</div>}
+            </div>;
+        })}
+        <button type='submit'>{submitLabel}</button>
+        {committed ? <ArcRuntimeBoundary>
+            <SingleResultRuntime query={query} queryArguments={committed} resultField={resultField} stringInputs />
+        </ArcRuntimeBoundary> : <SingleResultStatus state='idle' />}
+    </form>;
+}

package/forms/fields/SceneRadioButtonField.tsx

@@ -20,13 +20,16 @@ const RadioButtonField = lazy(async () => ({ default: (await import('@cratis/com
  * numeric code is common enough that forcing it through as `'1'` would bind the wrong value.
  */
 export function SceneRadioButtonField({ element }: RegisteredComponentProps) {
+    // Use the same reader as CommandFormField's binding gate; that gate owns missing-property feedback.
+    const name = stringProperty(element.properties, 'property');
     const buttonValue = stringProperty(element.properties, 'buttonValue') ?? numberProperty(element.properties, 'buttonValue') ?? '';
 
     return (
         <CommandFormField element={element}>
-            {binding => (
+            {binding => name !== undefined && (
                 <RadioButtonField
                     {...binding}
+                    name={name}
                     buttonValue={buttonValue}
                     label={stringProperty(element.properties, 'label')}
                     className={stringProperty(element.properties, 'className')}

package/forms/fields/for_SceneRadioButtonField/when_mapping_the_group_name.tsx

@@ -0,0 +1,45 @@
+// 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';
+
+// The public Components radio props require a native group name independently of the display title.
+describe('when mapping the radio group name', () => {
+    const received = vi.fn<(props: { name: string; title: string; value: (instance: Record<string, unknown>) => unknown }) => void>();
+    let SceneRadioButtonField: typeof import('../SceneRadioButtonField').SceneRadioButtonField;
+
+    beforeEach(async () => {
+        vi.resetModules();
+        received.mockClear();
+        vi.doMock('@cratis/components/CommandForm', () => ({
+            RadioButtonField: (props: Parameters<typeof received>[0]) => { received(props); return <input type='radio' name={props.name} />; },
+        }));
+        ({ SceneRadioButtonField } = await import('../SceneRadioButtonField'));
+    });
+
+    afterEach(() => {
+        cleanup();
+        vi.doUnmock('@cratis/components/CommandForm');
+        vi.resetModules();
+    });
+
+    it('should group options by the explicit property, regardless of titles or labels', async () => {
+        await act(async () => {
+            render(<>{['First title', 'Second title'].map((title, index) => <SceneRadioButtonField key={title} element={externalComponent('Cratis.Components:radioButtonField', { property: 'choice', title, label: 'Display label', buttonValue: index })} slots={{}} />)}</>);
+        });
+        expect(screen.getAllByRole('radio').map(radio => radio.getAttribute('name'))).toEqual(['choice', 'choice']);
+        expect(received.mock.calls.map(([props]) => props.value({ choice: 2 }))).toEqual([2, 2]);
+    });
+
+    for (const property of [undefined, 42, null, {}, []]) {
+        it(`should visibly reject malformed property ${JSON.stringify(property)} instead of using the title`, async () => {
+            await act(async () => {
+                render(<SceneRadioButtonField element={externalComponent('Cratis.Components:radioButtonField', { property, title: 'Not a binding' })} slots={{}} />);
+            });
+            expect(screen.getByText("Missing 'property' on Cratis.Components:radioButtonField")).toBeTruthy();
+            expect(received).not.toHaveBeenCalled();
+        });
+    }
+});

package/forms/fields/for_resolveFieldBinding/when_resolving_a_field_binding.ts

@@ -3,8 +3,14 @@
 
 import { externalComponent } from '../../../given';
 import { resolveFieldBinding } from '../resolveFieldBinding';
+import type { FieldBinding } from '../FieldBinding';
 
 describe('when resolving a field binding', () => {
+    it('should preserve manually constructed field bindings without a native group name', () => {
+        const binding: FieldBinding = { value: instance => instance.customerName, title: 'Customer' };
+        binding.value({ customerName: 'Acme' })!.should.equal('Acme');
+    });
+
     describe('and the element names a property with a title and description', () => {
         const binding = resolveFieldBinding(
             externalComponent('Cratis.Components:inputTextField', {

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