The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Expose the selected records filter to front components (#27404)
Charles Bochetb2a48824c94e
diff --git a/packages/twenty-agent-skills/references/develop-app/front-components.md b/packages/twenty-agent-skills/references/develop-app/front-components.mdindex 477c3b7ee62..0e4b60186b0 100644--- a/packages/twenty-agent-skills/references/develop-app/front-components.md+++ b/packages/twenty-agent-skills/references/develop-app/front-components.md@@ -48,6 +48,7 @@ Prefer Twenty UI icons from `twenty-ui/icon` when one exists. Use inline SVG onlFor record-page components, read selection from front component context:- Use `useSelectedRecordIds()` for single, bulk, or empty selection; derive one id only when the array length is 1.+- Under Select all, `useSelectedRecordIds()` is empty. Use `useSelectedRecordsFilter()` for bulk commands: it returns a filter matching exactly the selection in every case; query records with it or pass it to a logic function.- Use `useSelectedObjectMetadata()` from `twenty-sdk/front-component` to identify the object for a record-page widget, a custom timeline row, an object-scoped command, or a front component opened in the side panel with an object (from a command, or through `openSidePanelPage` with an `objectNameSingular`). It returns `{ id, nameSingular, namePlural }` or `null`. The `id` is the workspace's object-metadata UUID, and the names are metadata names such as `person` and `people`, not display labels.Object metadata belongs to the front component's own context, so a side panel can expose a different object from the main page. It can be available even when no records are selected and updates when that context changes. The hook returns `null` when no object context is supplied, when the object cannot be resolved, or when an older host does not provide object metadata. Use it to select object-specific templates or configuration without searching every object for a record ID.diff --git a/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/developers/extend/apps/layout/front-components.mdxindex 64d52b8d3df..583632a0863 100644--- a/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx@@ -460,6 +460,7 @@ Available hooks:| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- || `useUserId()` | `string` or `null` | The current user's ID || `useSelectedRecordIds()` | `string[]` | All selected record IDs (empty array if none selected) |+| `useSelectedRecordsFilter()` | `RecordGqlOperationFilter` or `null` | Filter matching exactly the selected records, including under Select all || `useSelectedObjectMetadata()` | `FrontComponentSelectedObjectMetadata` or `null` | The object metadata associated with this front component's record context || `useRecordId()` | `string` or `null` | **Deprecated.** Use `useSelectedRecordIds()` instead || `useFrontComponentId()` | `string` | This component instance's ID |@@ -749,6 +750,36 @@ export default defineCommandMenuItem({});```+#### Select all++When the user selects all records of a view, `useSelectedRecordIds()` returns an empty array: the selection is defined by the view's filters, search and unticked rows, and can hold far more records than fit in memory. `useSelectedRecordsFilter()` returns a filter matching exactly the selected records in every case, so query with it instead of listing IDs:++```tsx+import { Command, useSelectedRecordsFilter } from 'twenty-sdk/front-component';+import { CoreApiClient } from 'twenty-client-sdk/core';++const MarkExported = () => {+ const selectedRecordsFilter = useSelectedRecordsFilter();++ const execute = async () => {+ if (selectedRecordsFilter === null) {+ return;+ }++ await new CoreApiClient().mutation({+ updateTasks: {+ __args: { filter: selectedRecordsFilter, data: { exported: true } },+ id: true,+ },+ });+ };++ return <Command execute={execute} />;+};+```++For large selections, pass the filter to a [logic function](/developers/extend/apps/logic/logic-functions) and process the records there, page by page.+## Public assetsFront components can access files from the app's `public/` directory using `getPublicAssetUrl`:diff --git a/packages/twenty-front/src/modules/command-menu-item/engine-command/components/HeadlessFrontComponentRendererEngineCommand.tsx b/packages/twenty-front/src/modules/command-menu-item/engine-command/components/HeadlessFrontComponentRendererEngineCommand.tsxindex 3350745a79f..64753afecc2 100644--- a/packages/twenty-front/src/modules/command-menu-item/engine-command/components/HeadlessFrontComponentRendererEngineCommand.tsx+++ b/packages/twenty-front/src/modules/command-menu-item/engine-command/components/HeadlessFrontComponentRendererEngineCommand.tsx@@ -32,6 +32,7 @@ export const HeadlessFrontComponentRendererEngineCommand = () => {frontComponentId={context.frontComponentId}commandMenuItemId={commandMenuItemId}selectedRecordIds={selectedRecordIds}+ selectedRecordsFilter={context.graphqlFilter}objectNameSingular={context.objectMetadataItem?.nameSingular}/></Suspense>diff --git a/packages/twenty-front/src/modules/command-menu-item/engine-command/components/__tests__/HeadlessFrontComponentRendererEngineCommand.test.tsx b/packages/twenty-front/src/modules/command-menu-item/engine-command/components/__tests__/HeadlessFrontComponentRendererEngineCommand.test.tsxindex e435cfabb26..772762637c7 100644--- a/packages/twenty-front/src/modules/command-menu-item/engine-command/components/__tests__/HeadlessFrontComponentRendererEngineCommand.test.tsx+++ b/packages/twenty-front/src/modules/command-menu-item/engine-command/components/__tests__/HeadlessFrontComponentRendererEngineCommand.test.tsx@@ -4,6 +4,7 @@ import { HeadlessFrontComponentRendererEngineCommand } from '@/command-menu-itemimport { CommandComponentInstanceContext } from '@/command-menu-item/engine-command/states/contexts/CommandComponentInstanceContext';import { type HeadlessFrontComponentCommandContextApi } from '@/command-menu-item/engine-command/types/HeadlessCommandContextApi';import { type EnrichedObjectMetadataItem } from '@/object-metadata/types/EnrichedObjectMetadataItem';+import { type RecordGqlOperationFilter } from 'twenty-shared/types';let mockHeadlessCommandContextApi: HeadlessFrontComponentCommandContextApi;@@ -19,15 +20,17 @@ jest.mock('@/front-components/components/FrontComponentRenderer', () => ({frontComponentId,commandMenuItemId,selectedRecordIds,+ selectedRecordsFilter,objectNameSingular,}: {frontComponentId: string;commandMenuItemId?: string;selectedRecordIds?: string[];+ selectedRecordsFilter?: RecordGqlOperationFilter | null;objectNameSingular?: string;}) => (<div data-testid="front-component">- {`${frontComponentId}:${commandMenuItemId}:${objectNameSingular ?? 'no object'}:${selectedRecordIds?.join(',') || 'no records'}`}+ {`${frontComponentId}:${commandMenuItemId}:${objectNameSingular ?? 'no object'}:${selectedRecordIds?.join(',') || 'no records'}:${JSON.stringify(selectedRecordsFilter ?? null)}`}</div>),}));@@ -35,14 +38,17 @@ jest.mock('@/front-components/components/FrontComponentRenderer', () => ({const renderHeadlessFrontComponentCommand = ({objectMetadataItem,selectedRecordIds,+ graphqlFilter = null,}: {objectMetadataItem: EnrichedObjectMetadataItem | null;selectedRecordIds: string[];+ graphqlFilter?: RecordGqlOperationFilter | null;}) => {mockHeadlessCommandContextApi = {frontComponentId: 'front-component-id',objectMetadataItem,selectedRecords: selectedRecordIds.map((id) => ({ id })),+ graphqlFilter,} as HeadlessFrontComponentCommandContextApi;render(@@ -64,7 +70,7 @@ describe('HeadlessFrontComponentRendererEngineCommand', () => {});expect(await screen.findByTestId('front-component')).toHaveTextContent(- 'front-component-id:command-menu-item-id:company:record-1,record-2',+ 'front-component-id:command-menu-item-id:company:record-1,record-2:null',);});@@ -75,7 +81,28 @@ describe('HeadlessFrontComponentRendererEngineCommand', () => {});expect(await screen.findByTestId('front-component')).toHaveTextContent(- 'front-component-id:command-menu-item-id:no object:no records',+ 'front-component-id:command-menu-item-id:no object:no records:null',+ );+ });++ it('hands the component the filter matching a Select all selection', async () => {+ const selectAllFilter: RecordGqlOperationFilter = {+ and: [+ { name: { ilike: '%acme%' } },+ { not: { id: { in: ['record-3'] } } },+ ],+ };++ renderHeadlessFrontComponentCommand({+ objectMetadataItem: {+ nameSingular: 'company',+ } as EnrichedObjectMetadataItem,+ selectedRecordIds: [],+ graphqlFilter: selectAllFilter,+ });++ expect(await screen.findByTestId('front-component')).toHaveTextContent(+ `front-component-id:command-menu-item-id:company:no records:${JSON.stringify(selectAllFilter)}`,);});});diff --git a/packages/twenty-front/src/modules/front-components/components/FrontComponentRenderer.tsx b/packages/twenty-front/src/modules/front-components/components/FrontComponentRenderer.tsxindex 0d58a255a4c..e421f85ce39 100644--- a/packages/twenty-front/src/modules/front-components/components/FrontComponentRenderer.tsx+++ b/packages/twenty-front/src/modules/front-components/components/FrontComponentRenderer.tsx@@ -16,6 +16,7 @@ import { t } from '@lingui/core/macro';import { type ReactNode, useCallback, useMemo, useState } from 'react';import { FrontComponentRenderer as SharedFrontComponentRenderer } from 'twenty-front-component-renderer';import { type FrontComponentToolCall } from 'twenty-sdk/front-component';+import { type RecordGqlOperationFilter } from 'twenty-shared/types';import { isDefined } from 'twenty-shared/utils';import { useToast } from 'twenty-ui/components/feedback';import { useThemeColorScheme } from 'twenty-ui/theme';@@ -30,6 +31,7 @@ type FrontComponentRendererProps = {frontComponentId: string;commandMenuItemId?: string;selectedRecordIds?: string[];+ selectedRecordsFilter?: RecordGqlOperationFilter | null;objectNameSingular?: string;timelineActivityId?: string;toolCall?: FrontComponentToolCall;@@ -45,6 +47,7 @@ type FrontComponentRendererContentProps = {frontComponent: ResolvedFrontComponent;commandMenuItemId?: string;selectedRecordIds?: string[];+ selectedRecordsFilter?: RecordGqlOperationFilter | null;objectNameSingular?: string;timelineActivityId?: string;toolCall?: FrontComponentToolCall;@@ -56,6 +59,7 @@ export const FrontComponentRenderer = ({frontComponentId,commandMenuItemId,selectedRecordIds,+ selectedRecordsFilter,objectNameSingular,timelineActivityId,toolCall,@@ -85,6 +89,7 @@ export const FrontComponentRenderer = ({frontComponent={frontComponent}commandMenuItemId={commandMenuItemId}selectedRecordIds={selectedRecordIds}+ selectedRecordsFilter={selectedRecordsFilter}objectNameSingular={objectNameSingular}timelineActivityId={timelineActivityId}toolCall={toolCall}@@ -100,6 +105,7 @@ const FrontComponentRendererContent = ({frontComponent,commandMenuItemId,selectedRecordIds,+ selectedRecordsFilter,objectNameSingular,timelineActivityId,toolCall,@@ -127,6 +133,7 @@ const FrontComponentRendererContent = ({applicationId,commandMenuItemId,selectedRecordIds,+ selectedRecordsFilter,objectNameSingular,timelineActivityId,toolCall,diff --git a/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx b/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsxindex f9036146854..20414a28b85 100644--- a/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx+++ b/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx@@ -253,6 +253,7 @@ describe('useFrontComponentExecutionContext', () => {userId: 'user-123',recordId: 'record-456',selectedRecordIds: ['record-456'],+ selectedRecordsFilter: null,selectedObjectMetadata: null,timelineActivityId: null,colorScheme: 'light',@@ -260,6 +261,25 @@ describe('useFrontComponentExecutionContext', () => {});});+ it('should pass the selected records filter through', () => {+ const selectedRecordsFilter = {+ and: [+ { name: { ilike: '%acme%' } },+ { not: { id: { in: ['record-3'] } } },+ ],+ };++ const { result } = renderUseFrontComponentExecutionContext({+ frontComponentId: FRONT_COMPONENT_ID,+ selectedRecordIds: [],+ selectedRecordsFilter,+ });++ expect(result.current.executionContext.selectedRecordsFilter).toEqual(+ selectedRecordsFilter,+ );+ });+it('should return null recordId when multiple selectedRecordIds provided', () => {const { result } = renderUseFrontComponentExecutionContext({frontComponentId: FRONT_COMPONENT_ID,@@ -271,6 +291,7 @@ describe('useFrontComponentExecutionContext', () => {userId: 'user-123',recordId: null,selectedRecordIds: ['record-1', 'record-2', 'record-3'],+ selectedRecordsFilter: null,selectedObjectMetadata: null,timelineActivityId: null,colorScheme: 'light',diff --git a/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts b/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.tsindex 7a758254f79..e1a319fab02 100644--- a/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts+++ b/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts@@ -23,6 +23,7 @@ import {OpenRecordIn,SidePanelPages,type EnqueueSnackbarParams,+ type RecordGqlOperationFilter,} from 'twenty-shared/types';import { serializePlainTextAsAdvancedTextEditorDocument } from '@/advanced-text-editor/utils/serializePlainTextAsAdvancedTextEditorDocument';@@ -122,6 +123,7 @@ export const useFrontComponentExecutionContext = ({applicationId,commandMenuItemId,selectedRecordIds,+ selectedRecordsFilter,objectNameSingular,timelineActivityId,toolCall,@@ -131,6 +133,7 @@ export const useFrontComponentExecutionContext = ({applicationId: string;commandMenuItemId?: string;selectedRecordIds?: string[];+ selectedRecordsFilter?: RecordGqlOperationFilter | null;objectNameSingular?: string;timelineActivityId?: string;toolCall?: FrontComponentToolCall;@@ -436,6 +439,7 @@ export const useFrontComponentExecutionContext = ({userId: currentUser?.id ?? null,recordId: selectedRecordIds?.length === 1 ? selectedRecordIds[0] : null,selectedRecordIds: selectedRecordIds ?? [],+ selectedRecordsFilter: selectedRecordsFilter ?? null,selectedObjectMetadata: isDefined(selectedObjectMetadataItem)? {id: selectedObjectMetadataItem.id,diff --git a/packages/twenty-sdk/CHANGELOG.md b/packages/twenty-sdk/CHANGELOG.mdindex f846d439b6b..516b178dee6 100644--- a/packages/twenty-sdk/CHANGELOG.md+++ b/packages/twenty-sdk/CHANGELOG.md@@ -32,6 +32,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and### Added+- **`useSelectedRecordsFilter` in `twenty-sdk/front-component`.** Returns a record filter matching exactly the records the user selected, or `null` when there is no selection context. Under Select all, `useSelectedRecordIds()` is empty because the selection is defined by the view's filters, search and unticked rows; query the records with this filter, or pass it to a logic function. Twenty servers that predate it return `null`.++ ```tsx+ import { useSelectedRecordsFilter } from 'twenty-sdk/front-component';++ const selectedRecordsFilter = useSelectedRecordsFilter();+ ```+- **`enqueueJobs` in `twenty-sdk/logic-function`.** Enqueues one run per payload of a single logic function in one call (up to 200 payloads per batch). `retryLimit` and `delayMs` apply to every run in the batch.```tsdiff --git a/packages/twenty-sdk/src/sdk/front-component/hooks/__tests__/useSelectedRecordsFilter.spec.tsx b/packages/twenty-sdk/src/sdk/front-component/hooks/__tests__/useSelectedRecordsFilter.spec.tsxnew file mode 100644index 00000000000..372033e5efb--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/hooks/__tests__/useSelectedRecordsFilter.spec.tsx@@ -0,0 +1,61 @@+import { renderToStaticMarkup } from 'react-dom/server';+import { type RecordGqlOperationFilter } from 'twenty-shared/types';+import { afterEach, describe, expect, it } from 'vitest';++import { FRONT_COMPONENT_CONTEXT_KEY } from '@/sdk/front-component/constants/front-component-context-key';+import { useSelectedRecordsFilter } from '@/sdk/front-component/hooks/useSelectedRecordsFilter';+import { type FrontComponentExecutionContext } from '@/sdk/front-component/types/FrontComponentExecutionContext';++const EXECUTION_CONTEXT: FrontComponentExecutionContext = {+ frontComponentId: 'front-component-id',+ userId: 'user-id',+ recordId: null,+ selectedRecordIds: [],+ timelineActivityId: null,+ colorScheme: 'light',+};++const renderUseSelectedRecordsFilter = (+ executionContext: FrontComponentExecutionContext,+): RecordGqlOperationFilter | null => {+ (globalThis as Record<string, unknown>)[FRONT_COMPONENT_CONTEXT_KEY] =+ executionContext;++ let selectedRecordsFilter: RecordGqlOperationFilter | null = null;++ const SelectedRecordsFilterReader = () => {+ selectedRecordsFilter = useSelectedRecordsFilter();++ return null;+ };++ renderToStaticMarkup(<SelectedRecordsFilterReader />);++ return selectedRecordsFilter;+};++afterEach(() => {+ delete (globalThis as Record<string, unknown>)[FRONT_COMPONENT_CONTEXT_KEY];+});++describe('useSelectedRecordsFilter', () => {+ it('returns null when the host does not provide a selection filter', () => {+ expect(renderUseSelectedRecordsFilter(EXECUTION_CONTEXT)).toBeNull();+ });++ it('returns the selection filter provided by the host', () => {+ const selectAllFilter: RecordGqlOperationFilter = {+ and: [+ { name: { ilike: '%acme%' } },+ { not: { id: { in: ['excluded-record-id'] } } },+ ],+ };++ expect(+ renderUseSelectedRecordsFilter({+ ...EXECUTION_CONTEXT,+ selectedRecordsFilter: selectAllFilter,+ }),+ ).toEqual(selectAllFilter);+ });+});diff --git a/packages/twenty-sdk/src/sdk/front-component/hooks/useSelectedRecordsFilter.ts b/packages/twenty-sdk/src/sdk/front-component/hooks/useSelectedRecordsFilter.tsnew file mode 100644index 00000000000..017eb058056--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/hooks/useSelectedRecordsFilter.ts@@ -0,0 +1,12 @@+import { type RecordGqlOperationFilter } from 'twenty-shared/types';++import { type FrontComponentExecutionContext } from '../types/FrontComponentExecutionContext';+import { useFrontComponentExecutionContext } from './useFrontComponentExecutionContext';++const selectSelectedRecordsFilter = (+ context: FrontComponentExecutionContext,+): RecordGqlOperationFilter | null => context.selectedRecordsFilter ?? null;++export const useSelectedRecordsFilter = (): RecordGqlOperationFilter | null => {+ return useFrontComponentExecutionContext(selectSelectedRecordsFilter);+};diff --git a/packages/twenty-sdk/src/sdk/front-component/index.ts b/packages/twenty-sdk/src/sdk/front-component/index.tsindex 9d9d530c049..2aeb2ed8aa1 100644--- a/packages/twenty-sdk/src/sdk/front-component/index.ts+++ b/packages/twenty-sdk/src/sdk/front-component/index.ts@@ -19,6 +19,7 @@ export { useLocale } from './hooks/useLocale';export { useRecordId } from './hooks/useRecordId';export { useToolCall } from './hooks/useToolCall';export { useSelectedRecordIds } from './hooks/useSelectedRecordIds';+export { useSelectedRecordsFilter } from './hooks/useSelectedRecordsFilter';export { useSelectedObjectMetadata } from './hooks/useSelectedObjectMetadata';export { useTimelineActivityId } from './hooks/useTimelineActivityId';export { useUserId } from './hooks/useUserId';diff --git a/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts b/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.tsindex d0d9a8018a9..866bab59dff 100644--- a/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts+++ b/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts@@ -1,4 +1,5 @@import { type AppLocale } from 'twenty-shared/translations';+import { type RecordGqlOperationFilter } from 'twenty-shared/types';import { type FrontComponentSelectedObjectMetadata } from './FrontComponentSelectedObjectMetadata';import { type FrontComponentToolCall } from './FrontComponentToolCall';@@ -12,6 +13,11 @@ export type FrontComponentExecutionContext = {recordId: string | null;/** All selected record IDs */selectedRecordIds: string[];+ /**+ * Filter matching exactly the selected records. Under Select all,+ * `selectedRecordIds` is empty and only this filter describes the selection.+ */+ selectedRecordsFilter?: RecordGqlOperationFilter | null;selectedObjectMetadata?: FrontComponentSelectedObjectMetadata | null;timelineActivityId: string | null;/** Resolved color scheme of the host UI ('System' is already resolved) */