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