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