From f37e73f40ba5e41b9bbbfa501c3de981d4e88fac Mon Sep 17 00:00:00 2001 From: woksin Date: Wed, 16 Sep 2026 15:58:33 +0200 Subject: [PATCH] Forward explicit arguments through Scene query tables Preserve the registered query and supplied argument object, omit absent arguments, and reject malformed values visibly before mounting the table. Keep missing bindings unresolved and the existing lazy runtime boundary intact. Affected model/engine/react/components builds, all 125 component tests and non-fixing lint passed; independent review approved the scoped adapter. This remains collection-query support, not optional-single lookup or standalone full-stack acceptance. --- .../components/cratisComponentsPackage.ts | 2 +- .../components/data/SceneDataTable.tsx | 12 ++- .../when_forwarding_query_arguments.tsx | 102 ++++++++++++++++++ .../when_describing_query_arguments.ts | 15 +++ 4 files changed, 129 insertions(+), 2 deletions(-) create mode 100644 Source/JavaScript/components/data/for_SceneDataTable/when_forwarding_query_arguments.tsx create mode 100644 Source/JavaScript/components/for_cratisComponentsPackage/when_describing_query_arguments.ts diff --git a/Source/JavaScript/components/cratisComponentsPackage.ts b/Source/JavaScript/components/cratisComponentsPackage.ts index d7fdbec1..b191c7bf 100644 --- a/Source/JavaScript/components/cratisComponentsPackage.ts +++ b/Source/JavaScript/components/cratisComponentsPackage.ts @@ -88,7 +88,7 @@ export const cratisComponentsPackageManifest: ScenePackage = { themes: [], displayName: 'Cratis Components', - description: "Cratis' Arc-bound data, form and dialog composites, built on PrimeReact and Tailwind.", + description: "Cratis' Arc-bound data, form and dialog composites, built on PrimeReact and Tailwind. dataTable and table accept optional object-valued queryArguments for collection queries.", module: '@cratis/scene.components', license: 'MIT', licenseUrl: 'https://github.com/Cratis/Scene/blob/main/LICENSE', diff --git a/Source/JavaScript/components/data/SceneDataTable.tsx b/Source/JavaScript/components/data/SceneDataTable.tsx index 98349f3f..226eb13f 100644 --- a/Source/JavaScript/components/data/SceneDataTable.tsx +++ b/Source/JavaScript/components/data/SceneDataTable.tsx @@ -4,7 +4,8 @@ import { lazy } from 'react'; import { RegisteredComponentProps } from '@cratis/scene.react'; import { ArcRuntimeBoundary, BindingKind, MissingBinding, resolveElementBinding } from '../bindings'; -import { stringArrayProperty, stringProperty } from '../properties'; +import { objectProperty, stringArrayProperty, stringProperty } from '../properties'; +import { Placeholder } from '../bindings/Placeholder'; const DataTableForQuery = lazy(async () => ({ default: (await import('@cratis/components/DataTables')).DataTableForQuery })); @@ -19,6 +20,9 @@ const DataTableForQuery = lazy(async () => ({ default: (await import('@cratis/co * back into it, where PrimeReact's `DataTable` is handed rows and knows nothing about where they came from. * * The `query` property names an Arc query proxy; the columns come from the `content` slot. + * Optional `queryArguments` is an explicit object forwarded unchanged to that proxy. Invalid values + * render a placeholder rather than accidentally executing a query without its arguments. This remains + * a collection table; forwarding arguments does not make optional single-result queries compatible. * * There is deliberately no `clientFiltering` property. `@cratis/components` 3.0.0 still accepts the prop * so existing call sites compile, but it no longer does anything - filtering is always applied to the @@ -30,10 +34,16 @@ export function SceneDataTable({ element, slots }: RegisteredComponentProps) { const { name, target } = resolveElementBinding(element, BindingKind.Query); if (!target) return ; + const queryArguments = objectProperty(element.properties, 'queryArguments'); + if (element.properties.queryArguments !== undefined && queryArguments === undefined) { + return ; + } + return ( { + const suppliedId = 'project-with-an-explicit-id'; + const received = vi.fn<(properties: Record) => void>(); + let SceneDataTable: typeof import('../SceneDataTable').SceneDataTable; + let bindings: typeof import('../../bindings'); + + beforeEach(async () => { + vi.resetModules(); + received.mockClear(); + vi.doMock('@cratis/components/DataTables', () => ({ + DataTableForQuery: (properties: Record) => { + received(properties); + return
; + }, + })); + bindings = await import('../../bindings'); + bindings.clearBindings(); + bindings.registerQuery('InvoicesForProject', InvoicesForProject); + bindings.registerQuery('AnotherQuery', AnotherQuery); + ({ SceneDataTable } = await import('../SceneDataTable')); + }); + + afterEach(() => { + cleanup(); + bindings.clearBindings(); + vi.doUnmock('@cratis/components/DataTables'); + vi.resetModules(); + }); + + async function renderTable(properties: Record) { + const element = externalComponent('Cratis.Components:dataTable', properties); + await act(async () => { + render(); + }); + } + + it('should pass the exact registered constructor and explicit projectId object through the runtime boundary', async () => { + const queryArguments = { projectId: suppliedId }; + await renderTable({ query: 'InvoicesForProject', queryArguments }); + await screen.findByTestId('query-table'); + const properties = received.mock.lastCall![0]; + (properties.query === InvoicesForProject).should.equal(true); + (properties.queryArguments === queryArguments).should.equal(true); + properties.should.have.property('queryArguments').that.deep.equals({ projectId: suppliedId }); + }); + + it('should preserve all supplied keys and values without normalization or defaults', async () => { + const queryArguments = { projectId: suppliedId, ProjectID: 'distinct', limit: 0, enabled: false, optional: null, filter: { names: ['one'] } }; + await renderTable({ query: 'InvoicesForProject', queryArguments }); + await screen.findByTestId('query-table'); + (received.mock.lastCall![0].queryArguments === queryArguments).should.equal(true); + }); + + it('should leave omitted arguments absent from the underlying component props', async () => { + await renderTable({ query: 'InvoicesForProject' }); + await screen.findByTestId('query-table'); + Object.prototype.hasOwnProperty.call(received.mock.lastCall![0], 'queryArguments').should.equal(false); + (received.mock.lastCall![0].query === InvoicesForProject).should.equal(true); + }); + + it('should treat undefined arguments as omitted like the existing property readers', async () => { + await renderTable({ query: 'InvoicesForProject', queryArguments: undefined }); + await screen.findByTestId('query-table'); + Object.prototype.hasOwnProperty.call(received.mock.lastCall![0], 'queryArguments').should.equal(false); + }); + + it('should pass an explicitly empty argument object unchanged', async () => { + const queryArguments = {}; + await renderTable({ query: 'InvoicesForProject', queryArguments }); + await screen.findByTestId('query-table'); + (received.mock.lastCall![0].queryArguments === queryArguments).should.equal(true); + }); + + for (const queryArguments of [[], ['project'], 'project', '{"projectId":"project"}', 42, false, null]) { + it(`should visibly reject ${JSON.stringify(queryArguments)} without mounting a query table`, async () => { + await renderTable({ query: 'InvoicesForProject', queryArguments }); + (screen.getByText("Invalid queryArguments: expected an object on Cratis.Components:dataTable") !== null).should.equal(true); + received.mock.calls.should.have.lengthOf(0); + (screen.queryByTestId('query-table') === null).should.equal(true); + }); + } + + for (const queryArguments of [{ projectId: suppliedId }, null, []]) { + it(`should retain MissingBinding precedence and never choose another registered query with ${JSON.stringify(queryArguments)}`, async () => { + await renderTable({ query: 'UnregisteredQuery', queryArguments }); + (screen.getByText("Unresolved query binding 'UnregisteredQuery' on Cratis.Components:dataTable") !== null).should.equal(true); + received.mock.calls.should.have.lengthOf(0); + (screen.queryByText(/Invalid queryArguments/) === null).should.equal(true); + }); + } +}); diff --git a/Source/JavaScript/components/for_cratisComponentsPackage/when_describing_query_arguments.ts b/Source/JavaScript/components/for_cratisComponentsPackage/when_describing_query_arguments.ts new file mode 100644 index 00000000..0f64cfe2 --- /dev/null +++ b/Source/JavaScript/components/for_cratisComponentsPackage/when_describing_query_arguments.ts @@ -0,0 +1,15 @@ +// Copyright (c) Cratis. All rights reserved. +// Licensed under the MIT license. See LICENSE file in the project root for full license information. + +import { cratisComponentsPackageManifest } from '../cratisComponentsPackage'; + +describe('when describing query arguments', () => { + it('should keep both collection table names in the manifest', () => { + cratisComponentsPackageManifest.components.should.include('dataTable'); + cratisComponentsPackageManifest.components.should.include('table'); + }); + + it('should describe the optional object property without promising single-result support', () => { + (cratisComponentsPackageManifest.description ?? '').should.contain('dataTable and table accept optional object-valued queryArguments for collection queries'); + }); +});