Client record and productivity experiences
The client record experience gives users one place to find, understand, update, and act on workspace data. It joins record collections, record pages, activity, files, imports, editors, place selection, dashboards, and page layouts. It also supports email and app chat threads in the same record context. It is a child experience of the web client and uses the navigation and surface model from the client application shell. The log console is a related support surface.
Record workspaces
Record collections
The record collection experience helps users scan and manage many records for one object. A view can present the same work set as a table, board, calendar, or list. View settings shape the work set through visible fields, names and icons, grouping, sorting, calendar fields and periods, compact display, and group load limits. Sorts use the selected field or related target field and keep empty values last; local objects use position as a final tie-breaker, while remote objects do not. Shared record actions let users open, create, edit, move, select, merge, update, and export records without leaving it.
Creation follows the current view, group, relation, soft-delete, object, and field rules. A new record can inherit its group's value or its calendar date. A board or calendar does not offer creation when the view is read-only, the object or date field is not writable, the view includes deleted records, or the needed grouping or date field is missing. Record tables can also add a visible field from the current object's active fields or send the user to field settings. A table can add a lookup column when the workspace enables the feature and the current view can persist the extra column.
The collection keeps the visible work set distinct from its loading and access states. It can tell the user that an object is empty, a filter has no match, records were deleted, data is remote, creation is not allowed, or a related field is not readable. Large tables load rows and columns as needed while keeping visible rows, totals, focus, scroll position, and selection aligned. Grouped views can load a bounded number of records per section. Tabbed groups load the active group without applying the section load limit.
Table fields are part of the view work set. Users can add eligible fields, hide fields, move fields, resize columns, and choose field-level summaries when the surface allows it. A lookup column adds one readable, non-relation field from a related record. The table keeps its header, body, empty state, aggregate footer, and virtual columns aligned as these choices change. Board and calendar cards also show the selected fields inline and keep restricted or read-only values non-editable.
Grouped table and list views can show groups as sections or as tabs. The tab view narrows the displayed and selectable records to the active group while an All tab can represent the configured visible groups. Hidden groups, empty-group rules, group counts, group filters, and group ordering stay linked to the same view state. A tab change resets record selection so actions do not carry into another group.
Collection export follows the work set under review. It includes record IDs, keeps supported relation identifiers, expands composite values into readable columns, and sanitizes values before the CSV is produced. Export progress can show a count or a percentage while the client reads the current view.
References: packages/…/RecordTableContent.tsx• L1-180 packages/…/RecordTableColumnWidthEffect.tsx• L23-118 packages/…/RecordTableColumnAggregateFooterDropdownContent.tsx• L15-81 packages/…/RecordIndexEmptyState.tsx• L43-143 packages/…/useHandleToggleColumnSort.ts• L35-72 packages/…/useHandleToggleTrashColumnFilter.ts• L42-88 packages/…/getNonReadableInfoForViewField.ts• L8-85 packages/…/RecordGroupTabs.tsx• L95-180 packages/…/useFindManyRecordIndexTableParams.ts• L70-108 packages/…/useRecordIndexGroupsAggregatesGroupBy.ts• L61-143 packages/…/useObjectOptionsForBoard.ts• L46-126 packages/…/useSetViewTypeFromLayoutOptionsMenu.ts• L54-145 packages/…/RecordTableLookupTargetFieldSelectMenu.tsx• L18-75 packages/…/useCanAddRecordTableLookupColumns.ts• L8-20 packages/…/turnSortsIntoOrderBy.ts• L23-103 packages/…/turnSortsIntoOrderBy.test.ts• L78-397
Collection interaction
Collection views let users work on records in place. A shared selection model supports individual selection, range selection, select-all, drag selection, keyboard navigation, bulk updates, merging, and export across table, list, board, and calendar surfaces.
The same movement model covers a record position, group, or calendar date. Calendar views group events by day and show the date beside the events for that day. The query range follows the selected day, week, or month and preserves the view's other filters in the user's time zone. Moving a calendar card also shifts its date or date-time value in that time zone. Moving a board card or record group updates its position and keeps the saved group order aligned with the visible order. List rows can move only when the user can update the object.
New records can inherit the active group's value when the view is grouped. The collection hides creation where the view, the user's access, a soft-delete filter, or the field used for grouping does not allow it. Multi-record update and merge actions use a side panel, show progress, and require confirmation before they change selected records. The bulk editor limits its fields to values that the selected records and their current permissions can change.
Table cells can expose compact controls for actions that are available in the current context. Controls without an action remain disabled, so the table can show the possible action without suggesting that it can run. List rows also show only populated fields that fit the row and expose the rest through an overflow count. Column menus can filter, sort, move, or hide fields, and resizing changes the saved view or page-layout draft that owns the table.
Column layout changes are kept local while the table responds, then saved to the owning view or page-layout draft. Column movement clears cell focus before it changes order. Resizing keeps the table's empty space and rendered column range usable, including during horizontal scroll and while a page-layout table is still a draft. Aggregate choices use the field type and remain read-only when the table surface does not permit interaction.
Merge review lets the user choose which selected record has priority when fields conflict. A preview does not change cached records, while a confirmed merge refreshes the merged record, duplicate results, and aggregate totals before the client opens the surviving record.
References: packages/…/useRecordGroupActions.ts• L64-155 packages/…/useProcessCalendarCardDrop.ts• L25-180 packages/…/RecordCalendarCardBody.tsx• L80-142 packages/…/useRecordCalendarQueryDateRangeFilter.test.tsx• L80-102 packages/…/RecordTableColumnHeadDropdownMenu.tsx• L74-140 packages/…/useResizeTableHeader.ts• L182-239 packages/…/RecordTableColumnVirtualizationEffect.tsx• L53-131 packages/…/RecordTableAggregateFooterCell.tsx• L84-147 packages/…/useViewFieldAggregateOperation.tsx• L18-101 packages/…/MergeRecordsContainer.tsx• L44-104 packages/…/RecordIndexFiltersToContextStoreEffect.tsx• L72-151 packages/…/RecordListDraggableRow.tsx• L36-89 packages/…/getFieldsEditableInMultiEditForm.ts• L1-80
Advanced filtering
Advanced filtering lets users describe a work set with nested groups and logical operators. A rule can target a normal field, a field reached through a relation, a part of a composite field, or a structured value such as a country, currency, select option, actor source, or record.
The filter editor guides the user from a field to any required relation target or composite sub-field, then to a valid operand and value. It chooses the input from the target field type. Text and number rules use direct inputs, select rules use searchable options, relation rules use record search, and date rules show date or date-time controls. It separates fields that are visible in the current view from other filterable fields. Actor and relation values can include the current member and selected records. Date operands show the relevant time zone, while workflow record searches use UTC. Relative dates keep their time-zone context when the user changes an operand or views the filter label.
Filter state has a small saved form and a metadata-based working form. When a saved filter is read, the client restores its type and label from current field metadata. A relation rule can keep the source field as its stored path while applying the operand to a readable target field. Filters whose fields, relation targets, or target objects no longer resolve stay marked as unresolved instead of becoming active rules with guessed meaning. Read-only filter surfaces show the rule but do not allow edits. The same operand meanings are shared with row-level permission filters so a rule remains consistent across product surfaces.
The following flow shows how a saved rule becomes a usable filter or an explicit unresolved state.
flowchart LR
A[Saved filter] --> B[Current field metadata]
B --> C{Field and relation targets resolve?}
C -->|Yes| D[Typed operand and value editor]
C -->|No| E[Unresolved rule]
D --> F[Filtered record work set]
References: packages/…/AdvancedFilterFieldSelectMenu.tsx• L37-142 packages/…/AdvancedFilterCompositeSubFieldSelectMenu.tsx• L31-92 packages/…/AdvancedFilterRecordFilterOperandSelectContent.tsx• L45-101 packages/…/useApplyAdvancedFilterRelationTargetField.ts• L62-124 packages/…/AdvancedFilterSidePanelValueFormInput.tsx• L114-253 packages/…/ObjectFilterDropdownFilterInput.tsx• L27-135 packages/…/ObjectFilterDropdownInnerSelectOperandDropdown.tsx• L41-100 packages/…/filterValueFieldMetadataItemUsedInDropdownComponentSelector.ts• L10-34 packages/…/mapRLSOperandToRecordFilterOperand.ts• L7-45 packages/…/hydrateRecordFiltersFromFieldMetadata.ts• L8-57
Record pages
The record page focuses work on one record. It presents fields, related records, activity, files, and actions through a page layout. The same experience can run in a side panel so a user can inspect or update a record without losing the collection or page that opened it.
Neighbor navigation follows the parent collection's filters and sort order. It keeps a usable rank and total while data reloads, handles soft-deleted records when the view includes them, and returns to the collection through the current side-panel route when needed. A deleted or unavailable record remains represented by a clear unavailable state instead of becoming a blank page.
Record creation can start from a collection, a side-panel form, or a record picker. A creation request keeps its draft and returns the new record to the caller after success. This lets a picker connect a newly created record to the active relation. A failed save leaves the creation surface open for correction. The same request can create another record without closing the form, or cancel without creating anything.
The field area shows editable values in place. Related records use their own expandable list so a user can inspect fields on the related record and detach or delete it when access allows. One-to-many and polymorphic relations use the shared multiple-record picker, which can search across permitted target objects and create a target when the relation supports it. Junction relations expose only permitted target fields and keep the relation path tied to the current metadata. When a picker creates a junction target, the target form can stay open for repeated creation and each saved target is linked to the source record.
Record pages select their layout from the target record and keep deleted-record information above the page content. In a side panel, the footer provides record actions except for app chat threads, where the message surface owns the controls after its channel is known. An app chat thread is a conversation channel with chat-style messages, rather than an email thread with mailbox actions.
References: packages/…/useRecordShowPage.ts• L7-29 packages/…/useRecordShowPagePagination.ts• L31-313 packages/…/PageLayoutRecordPageRenderer.tsx• L43-115 packages/…/RecordCreationFormProvider.tsx• L33-201 packages/…/RecordDetailRelationRecordsListItem.tsx• L167-271 packages/…/categorizeRelationFields.ts• L58-95 packages/…/MultipleRecordPicker.tsx• L124-235 packages/…/useMultipleRecordPickerPerformSearch.ts• L101-137 packages/…/useDisplaySidePanelFooter.test.tsx• L64-92
Record data lifecycle
Record data moves from metadata-shaped queries into shared client state and then into visible collection, page, chip, lookup-column, and widget surfaces. Query fields are selected from the fields and permissions needed by each surface. Relations carry enough identity and connection data for the surface that requested them, while invalid or unreadable junction targets are left out. Lookup columns add the chosen target field to the relation query and make normalized related records available to table cells.
Record changes use an optimistic path so the screen can respond before the server result returns. Create, update, and delete operations place the expected result in the cache and shared record state, then reconcile it with the server result. A failed mutation removes, restores, or rolls back the optimistic data and refreshes affected aggregates. Relation attach and detach actions also update visible connections so the page does not wait for a full reload.
Batch creation and destruction use incremental fetch, progress, and cancellation for imports and other large changes. They report processed records, stop without hiding already-processed records when aborted, refresh aggregate values, and announce the object change to other client surfaces. Metadata field deletion or rename also evicts the related record and group queries so old query shapes do not remain visible.
Aggregate surfaces use metadata to map count and field measures to query fields. The query builder emits only the requested record fields and keeps relation sorting tied to the related object's label field. If the related object is not available, sorting falls back to the relation identifier. Local records use position as the final order, while remote objects do not receive local position ordering. Cursor pagination adds an ID tie-breaker so adjacent pages remain stable and removes duplicate cursors when pages join. Lazy and combined reads stop at the permission boundary, so a surface does not query objects the viewer cannot read.
The following flow shows how metadata, cache state, and a record mutation stay aligned.
flowchart LR
A[Object metadata and permissions] --> B[Selected record query]
B --> C[Shared cache and record state]
C --> D[Collection, page, chip, and widget]
D --> E[Optimistic record change]
E --> F{Server result}
F -->|Success| G[Reconciled cache and aggregates]
F -->|Failure| H[Rollback and restored surface]
References: packages/…/useFindManyRecords.ts• L39-151 packages/…/useLazyFindManyRecords.ts• L31-170 packages/…/useLazyFindManyRecordsWithOffset.ts• L22-109 packages/…/generateDepthRecordGqlFieldsFromFields.ts• L17-166 packages/…/useGenerateCombinedFindManyRecordsQuery.ts• L20-140 packages/…/useCreateManyRecords.ts• L94-261 packages/…/useUpdateOneRecord.ts• L47-309 packages/…/useDestroyOneRecord.ts• L43-123 packages/…/useIncrementalFetchAndMutateRecords.ts• L48-158 packages/…/useAggregateRecords.ts• L23-85 packages/…/filterUniqueRecordEdgesByCursor.ts• L3-18 packages/…/modifyRecordFromCache.ts• L7-33 packages/…/addLookupTargetsToRecordGqlFields.ts• L5-32 packages/…/getRecordsWithLookupRelatedRecords.ts• L10-40
Record fields and relations
Record fields use their definition to choose a display or edit surface. The same field model works in a record page, collection cell, creation form, import, and page-layout widget. It covers simple values as well as files, rich text, selections, links, phones, addresses, email values, currency, and other structured values. A canonical field is the active view of a field when old or duplicate field entries exist, and each view type uses only field types that it can display.
Editability is a shared product rule. An object is read-only when the user cannot update its records, when its metadata is not UI-editable, or when it is remote. A record is also read-only when it is deleted. A field can add a field-level restriction, and a one-to-many relation is read-only when its target or inverse field cannot be updated. Layout customization also temporarily makes the object read-only so editing a record cannot compete with layout work.
Relation fields use single- and multiple-record pickers. They retain selected records while searching, search across permitted object types, load more results, and offer record creation only where object access allows it. A picker can accept a variable in form contexts. Junction and polymorphic relations expose terminal records rather than internal junction rows when possible, and they exclude target types that the user cannot read or update. A relation with no readable target shows a restricted or empty state instead of a misleading picker. File, select, phone, and structured field inputs validate their value shape and can route a new select option to field settings. Date values keep date-only and date-time meaning in the user's time zone. Workflow filters use UTC. Record updates can also apply row-level rules that prefill or restrict values, and active validation rules can open a side-panel form to complete required fields before the update continues.
Select fields show active choices and keep an inactive choice visible when it is already set on the record so the user can remove it. New choices are offered only when the user can add them, and their name cannot reuse an existing label or value. Multi-select fields keep the same search and add-choice behavior while allowing several selected values.
Sharing gives eligible records their own access state: a record can be private, shared with named principals, or covered by general access. Role-managed objects keep access at the role level, and system objects are not shareable. The client also explains when only the creator, full-access users, or admins can change sharing. Viewer-scoped record permissions refresh in bounded batches and discard answers that belong to an older workspace, member, role, or request. A direct record link can still be read when record-level sharing permits it even if the viewer cannot read the whole object.
The following flow shows how field metadata becomes a permitted field surface.
flowchart LR
A[Field definition] --> B[Display or editor]
B --> C{Object, field, record, and relation access}
C -->|Allowed| D[User action and validated value]
C -->|Read only| E[Read-only value]
C -->|Not readable| F[Hidden or restricted state]
References: packages/…/isObjectMetadataReadOnly.ts• L8-29 packages/…/isRecordFieldReadOnly.ts• L13-57 packages/…/isOneToManyRelationFieldReadOnlyDueToTargetUpdatePermission.ts• L15-88 packages/…/FormDateFieldInput.tsx• L81-123 packages/…/FormDateTimeFieldInput.tsx• L75-119 packages/…/FormMorphRelationToOneFieldInput.tsx• L74-181 packages/…/SelectFieldInput.tsx• L15-90 packages/…/MultiSelectFieldInput.tsx• L14-69 packages/…/filterSelectableFieldOptions.ts• L1-17 packages/…/isSelectOptionNameTaken.ts• L1-19 packages/…/findCanonicalRecordField.ts• L1-80 packages/…/isRecordFieldSupportedByViewType.ts• L1-80 packages/…/RecordDetailRelationRecordsListItem.tsx• L167-270 packages/…/categorizeRelationFields.ts• L58-95 packages/…/getNonReadableInfoForViewField.ts• L11-87 packages/…/useCanReadObjectRecordsOrSharedRecords.ts• L8-28 packages/…/usePersistField.ts• L64-190 packages/…/useCompleteRecordUpdate.ts• L70-194
Lookup columns
Lookup columns let a collection show one field from a related record beside the source record. The user selects a relation and then a readable, active, non-relation field on the related object. The column label keeps both parts of that path visible so the value remains clear in the collection.
The feature is available only when the workspace enables it and the current view can save column changes. It is not added to widget views, whose columns follow their own field set. The client adds the selected target field to the relation read and uses the normalized related record for display or edit access. The related record's permissions still control whether the lookup value is readable or writable.
References: packages/…/RecordTableCellLookupFieldContext.tsx• L23-85 packages/…/RecordTableLookupTargetFieldSelectMenu.tsx• L18-75 packages/…/useGetLookupRelationFieldNames.ts• L8-31 packages/…/useGetRecordFieldLookupTarget.ts• L8-27 packages/…/addLookupTargetsToRecordGqlFields.ts• L5-32 packages/…/getLookupTargetFieldMetadataItems.ts• L5-23 packages/…/getRecordFieldColumnHeader.ts• L10-32 packages/…/getRecordsWithLookupRelatedRecords.ts• L10-40 packages/…/isLookupColumnsEnabledSelector.ts• L5-12 packages/…/useCanAddRecordTableLookupColumns.ts• L8-20
Activity and productivity context
Activity history
The activity timeline gives a record a time-ordered history of work and change. It loads only when the target object has a supported timeline relation, refreshes when database, browser, or live message events change the target, and groups entries by the time they happened rather than the time they were stored.
Change entries resolve their field meaning from current metadata. The timeline removes change details for fields the user cannot read and keeps a readable activity when only some diff entries remain. Restricted message bodies, calendar details, files, and unavailable records remain visibly private instead of exposing content. File diffs reuse current file URLs when possible and mark files that are no longer available.
Timeline rows link to the right record surface. Message rows open the message thread when its content is available. Calendar rows show the event date and time in the user's time zone and open the event side panel. A missing, forbidden, or restricted item gets a clear state instead of an empty row. Participant groups can represent people, workspace members, and call recorders in the same event surface. Thread rows also carry the channel type and conversation style so the record page can choose email or app chat behavior.
References: packages/…/useTimelineActivities.ts• L19-123 packages/…/groupEventsByMonth.ts• L10-36 packages/…/EventCardCalendarEvent.tsx• L91-210 packages/…/EventCardMessage.tsx• L55-146 packages/…/EventFieldDiffValueEffect.tsx• L17-88 packages/…/CalendarEventParticipantsAvatarGroup.tsx• L12-87 packages/…/timelineThreadFragment.ts• L5-28
Tasks notes and calendar events
Tasks, notes, and calendar events turn the record page into a work surface. Each activity stays next to the record it supports and provides clear empty, loading, count, and create states. Tasks expose completion and due-date context. Notes provide a direct writing path. Calendar events group work by month and day.
Activity creation first checks whether the target object can be updated. It then creates the activity and links every target supported by the current relation metadata. Unsupported targets are ignored, while a new task or note opens in the side panel with its valid links already in place. Tasks group by their current status and can be completed from the row.
The event composer checks account access, required data, guests, dates, place, time zone, and record context before it permits creation. It supports all-day and timed events, invitations, video links, descriptions, and links to related records. The target picker derives searchable objects from the event relation metadata, so one event can target every permitted related object through the same multi-record search model. Event links use an upsert path because participant matching may have created the same link already. Participant and call-recorder avatars stay visible in the event summary.
A successful event is closed as created even if its follow-up record links fail. This prevents a retry from creating a duplicate event. The timeline refreshes after links succeed. Event rows show only the title detail allowed by the event's sharing level.
The following flow shows how a record action becomes a linked calendar event.
flowchart LR
A[Record action] --> B{Account, access, and event data ready?}
B -->|No| C[Show setup or correction state]
B -->|Yes| D[Open event composer]
D --> E[Choose guests, place, dates, and related records]
E --> F[Create calendar event]
F --> G[Link records and refresh activity]
References: packages/…/useCreateActivityForTargetRecord.ts• L15-39 packages/…/useOpenCreateActivityDrawer.ts• L52-115 packages/…/useActivityLinkConfig.ts• L19-95 packages/…/TaskGroupsContent.tsx• L42-92 packages/…/useCalendarEventComposer.ts• L102-289 packages/…/CalendarEventLocationInput.tsx• L17-69
Email threads and app chat
Message activity keeps email threads and app chat threads in the same record context while preserving their different work models. Email threads use mailbox sender and reply rules. App chat threads use a channel recipient, chat-style messages, reactions, and direct message sending. A thread preview shows the amount of detail allowed by its sharing level, and restricted threads stay visibly restricted.
The thread view loads messages in time order and can refresh when new messages arrive or the live connection is restored. It groups adjacent messages by sender and marks messages as incoming or outgoing from the viewer's message channels. Sender headers show the participant and received time. Text supports links, while reactions show counts and the people who used each emoji. Attachments can appear as images, video, audio voice notes, or file chips. Failed media returns to a file chip, and a refreshed signed URL can receive another load attempt.
Email reply uses the channel of the last message's connected account, including a shared mailbox, and refuses to guess when the viewer cannot access the channel. The reply context supplies recipients, subject, and the original message ID. Email composition supports sender choice, recipient search, attachments, rich message content, and Cc/Bcc. Recipient chips show resolved identity, flag invalid addresses, support edit and remove actions, and can be moved between recipient fields.
App chat composition requires a channel and at least one recipient. It accepts text or files, keeps pending messages visible while they send, and lets the user retry or discard a failed message. App-channel email replies use the app channel as the sender, carry an idempotency key across a retry, and refresh the record timeline after sending. The channel logo and conversation style distinguish an installed app channel from a built-in mailbox.
Page-layout message widgets choose their surface from the thread channel. A thread widget loads older messages, refreshes when new messages arrive, marks an owned app channel as read when allowed, and shows a clear missing-thread state when the data is incomplete. Email replies can open or close from widget actions, attach files when enabled, and return to the thread after a successful send. Record message widgets can also show all conversations or filter them by channel, link email threads, and open a new composer.
Campaigns join sender settings, a recipient list, an optional unsubscribe topic, a subject, and a rich body in one widget. A campaign can send now or schedule a future send. Draft changes persist while the user edits and refresh preview data after a successful save. Once sending starts, the campaign becomes read-only from the stored or optimistic status.
Sent campaigns keep their stored list, topic, subject, body, and scheduled time readable when a referenced list or topic is later unavailable. The sent view shows an explicit unavailable state instead of dropping the stored relationship. Campaign variables use current person fields and preserve existing fallback values in the subject or body.
Campaign body editing uses the shared email canvas. It supports rich blocks, campaign variables, images, and block style settings. The active campaign editor is registered with the campaign surface so variable and style actions apply to the current body.
The following flow shows how a thread chooses its message surface and keeps a new message visible until the server confirms it.
flowchart LR
A[Timeline thread] --> B[Channel and conversation style]
B --> C{Email or app chat?}
C -->|Email| D[Mailbox reply composer]
C -->|App chat| E[Chat composer with recipients and files]
D --> F[Send through connected account]
E --> G[Send with idempotency key]
F --> H[Refresh thread activity]
G --> H
E --> I{Send result}
I -->|Failure| J[Pending message with retry or discard]
References: packages/…/ChatThreadComposer.tsx• L71-267 packages/…/ChatThreadMessageGroup.tsx• L56-163 packages/…/ChatThreadMessageReactions.tsx• L21-53 packages/…/ChatThreadMessageVoiceNote.tsx• L26-108 packages/…/ChatThreadPendingMessage.tsx• L42-97 packages/…/ChatThreadMessages.tsx• L22-57 packages/…/EmailComposerFields.tsx• L74-296 packages/…/useEmailThread.ts• L24-231 packages/…/useReplyContext.ts• L14-85 packages/…/useEmailComposerState.ts• L38-237 packages/…/useSendAppChannelMessage.ts• L11-32 packages/…/useSubscribeToMessageThreadMessages.ts• L13-129 packages/…/isChatTimelineThreadChannel.ts• L7-22 packages/…/getAppReplyTarget.ts• L6-40 packages/…/getEmailComposerSenderPicker.ts• L7-47 packages/…/EmailRecipientsFieldChipCell.tsx• L51-141 packages/…/getMessageThreadChannel.ts• L3-12 packages/…/MessageThreadWidget.tsx• L31-119 packages/…/ChatThreadWidgetContent.tsx• L52-167 packages/…/EmailThreadComposer.tsx• L1-120 packages/…/WidgetActionMessagesFilter.tsx• L1-100
Files and attachments
The file experience keeps documents attached to the record or activity that uses them. Direct field uploads create an upload target, transfer the file, and finalize it before the field receives the completed file. Activity uploads use the same completed file to create an attachment link for the target activity object.
Users with upload access can add files from a picker or drop them into an empty state. Attachment rows show a safe link, file type, date, and preview or open action. Users can rename or delete an attachment when the owning surface is writable, and can download it only when download access allows. Unsupported files, failed previews, private URLs, or disabled preview use a file chip or download fallback instead.
The document viewer previews supported images, PDFs, text, spreadsheets, office files, CSV data, and video. It gives a clear download path when a type cannot be previewed or an office file is hosted on a private local address. A failed video load uses the same unavailable-preview state and hides download when the viewer lacks permission.
Rich-text activity edits keep attachment state aligned with the body. Removed files are deleted, restored files can be recovered from soft-deleted attachments, and renamed files follow the name in the content. Attachment matching compares the stable host and attachment path so changing a signed URL does not create a false remove-and-add. File fields reuse the viewer in page-layout widgets and enforce their maximum item count. Chat messages use the same file categories and preview path, with failed or deleted media falling back to a file chip.
References: packages/…/DocumentViewer.tsx• L188-347 packages/…/UnavailableFilePreview.tsx• L34-63 packages/…/useUploadAttachmentFile.tsx• L12-70 packages/…/AttachmentRow.tsx• L80-251 packages/…/useAttachmentSync.ts• L15-100 packages/…/compareUrls.ts• L4-25 packages/…/FilesFieldInput.tsx• L50-134 packages/…/ChatThreadMessageAttachment.tsx• L47-99 packages/…/EmailThreadMessageAttachments.tsx• L45-113
Import and content authoring
Spreadsheet import
Spreadsheet import brings outside rows into a selected object while giving the user a review point before data enters the workspace. The flow selects a sheet, identifies the header row, matches source columns to workspace fields, validates values, and submits only valid rows with progress information.
The review moves through four stages:
- The user chooses the sheet and header row.
- The user matches, ignores, or remaps source columns and can choose a structured sub-field.
- The client converts values and reports row errors.
- The user corrects or removes bad rows and confirms the valid-row count.
Relations use unique values to find existing records. Composite sub-fields keep stable keys during mapping. The object-record entry point builds import fields from the current object's updatable metadata, excludes field types that cannot be imported, and exposes relation connection fields from target unique values. It validates numbers, dates, URLs, email values, phone values, JSON, arrays, ratings, and UUIDs before submission. It checks duplicate values against unique indexes, submits valid rows in batches with upsert behavior, supports abort, reports partial progress, and refreshes object data after completion.
References: packages/…/useBuildSpreadSheetImportFields.ts• L38-329 packages/…/buildRecordFromImportedStructuredRow.ts• L126-432 packages/…/getSpreadSheetFieldValidationDefinitions.ts• L42-289 packages/…/useOpenObjectRecordsSpreadsheetImportDialog.ts• L18-103 packages/…/useCreateManyRecords.ts• L94-261 packages/…/ValidationStep.tsx• L108-285
Rich text editing
Rich text provides one structured writing model for record fields, tasks, notes, email content, and standalone page content. It supports common formatting, links, blocks, images, variables, tables, indentation, and drag-and-drop. Each use selects an editor profile that sets its content features, visual style, minimum size, and legacy-content handling.
Record rich text uses a draft while the user types. It updates the visible record quickly, saves after a short pause, flushes on blur, and keeps attachments in step with image changes. Activity editors persist task and note bodies through the activity record, while focus handling keeps the editor and record title from competing for keyboard input. A read-only rule blocks persistence. Older content remains read-only when the current editor cannot safely interpret its blocks.
The editor supports nested indentation with keyboard controls and lets users resize images within the editor width. Text variable inputs can preserve line breaks, format pasted JSON for the selected mode, and turn supported template strings into variable tags. Email content uses an email canvas. Campaign editing keeps details and body in one widget, while a sent campaign uses the same canvas as a read-only preview.
References: packages/…/ActivityRichTextEditor.tsx• L30-136 packages/…/AdvancedTextEditorProfile.ts• L5-19 packages/…/AdvancedTextEditor.tsx• L561-618 packages/…/RichTextFieldEditor.tsx• L117-299 packages/…/useTextVariableEditor.test.ts• L60-214 packages/…/useCampaignEmailEditorVariables.ts• L16-67
Place selection
Place selection helps users enter a readable address or event location from a place suggestion list. The owning field or event composer receives the selected value while the user sees a stable place name. Calendar event creation uses the same location experience as record editing.
References: packages/…/PlaceAutocompleteSelect.tsx• L16-71 packages/…/usePlaceAutocomplete.ts• L23-141 packages/…/CalendarEventLocationInput.tsx• L17-69
Dashboards and page layouts
Dashboard views
Dashboard views turn workspace data into a compact surface for review and decisions. Graph widgets show aggregate, ratio, pie, bar, or line values. Record-table widgets connect a summary to the records behind it. Rich text adds headings, notes, and guidance.
The dashboard joins measurement, source records, and explanation in one view. Current filters and field meaning shape aggregate values. Users can inspect a value, focus or hide a series, open related work through drilldown, and duplicate a dashboard as a starting point for a similar view. Duplication adds the new dashboard to the local record view and reports metadata errors separately from general failures.
Chart drilldown carries the chart filters, clicked bucket, grouping, sort, view, time zone, and week-start rules into the record collection. This lets a chart answer both “what is the value?” and “which records make up the value?”. Aggregate display values follow the field type and the user's number, date, and time settings.
References: packages/…/useGraphWidgetQueryCommon.ts• L18-66 packages/…/useGraphWidgetAggregateQuery.ts• L20-155 packages/…/buildChartDrilldownQueryParams.ts• L10-78 packages/…/transformAggregateRawValueIntoAggregateDisplayValue.ts• L21-119 packages/…/useDuplicateDashboard.ts• L14-59
Page layout composition
Page layouts define which widgets a user sees and how they are arranged. A layout has tabs and can use a grid, vertical list, or canvas. Record pages, record forms, standalone pages, and dashboards share the composition model while choosing different content for their target.
Normal rendering uses active widgets that match the target record, available fields, device, surface, feature access, and relation context. Record pages choose the layout for the target object and record. Dashboard targets use the dashboard layout type. Deleted records keep a visible notice above the layout, and side-panel pages can add actions below it.
Edit mode keeps layout content available for repair and change. Layout changes stay in a draft until saved. Widget positions use the layout mode that owns them, and widget configuration uses the content type that owns its behavior. Saving first prepares pending field and record-table views, removes chart filters that no longer match active metadata, sends the tab and widget changes, and replaces the local persisted layout only after success. Individual widget changes apply each successful result without claiming that a failed update succeeded.
The layout also gives activity widgets direct actions. Calendar widgets can link or create events. Email widgets can link threads or open a composer. Field widgets can reveal more fields, and the editor can add or resize a widget within the active layout mode.
The following diagram shows how a layout draft becomes a user-facing page.
flowchart TD
L[Page layout draft] --> S[Metadata-aware save]
S --> T[Tabs and widgets]
T --> A[Active tab]
A --> M{Layout mode}
M --> G[Grid]
M --> Q[Vertical list]
M --> C[Canvas]
G --> W[Widgets]
Q --> W
C --> W
W --> R[Record fields and activity]
W --> D[Charts and tables]
W --> P[Written content and files]
References: packages/…/PageLayoutRecordPageRenderer.tsx• L61-115 packages/…/useSavePageLayout.ts• L20-109 packages/…/useUpdatePageLayoutWidgets.ts• L15-81 packages/…/WidgetActionCalendar.tsx• L7-23 packages/…/WidgetActionEmails.tsx• L7-23 packages/…/RecordTableWidgetProvider.tsx• L40-191 packages/…/PageLayoutRecordPageRendererEmailThread.stories.tsx• L247-371
Layout widget behavior
Widgets keep common page behavior around different kinds of content. The set includes record fields, relations, activity, files, email, calendar, charts, written content, workflows, embedded content, record tables, chat, campaigns, and call recording.
Field widgets use active and eligible fields. Existing field groups remain ordered, while new eligible fields are added for the editor to place. Restricted and read-only values do not become editable. Rich-text field widgets load the activity editor for note and task content, while standalone rich-text widgets use a widget-specific document profile.
Record-table widgets can show a limited related work set and can add nested relation or junction records. The widget keeps its table view in the page-layout draft while the record surface keeps normal view state. Chat widgets show conversations linked to the target record. They distinguish loading, empty, error, and loaded states. Users can open a conversation in the side panel, detach it from the record, retry a failed load, and load more conversations when another page exists.
Graph widgets apply metadata-aware filters before they query data. They support aggregate and ratio measures, chart grouping, field-aware formats, sorted buckets, and drilldown to records. Call-recording widgets request only readable fields and keep summary, transcript, media, loading, and access states separate.
References: packages/…/useFieldsWidgetEditorGroupsData.ts• L20-220 packages/…/FieldRichTextCard.tsx• L45-71 packages/…/ChatThreadsCardContent.tsx• L63-121 packages/…/useGraphWidgetQueryCommon.ts• L18-66 packages/…/useCallRecordingForWidget.ts• L19-91 packages/…/RecordTableWidgetProvider.tsx• L40-191
Change checklist
When these files or sections are changed, remember to consider these:
- Keep collection views aligned with record selection, grouping, group tabs, visible-group filters, calendar date ranges and time zones, aggregates, virtualization, export columns, remote-object sorting, view options, merge priority, cell controls, lookup columns, column persistence, and record creation rules.
- Keep table and card field controls aligned with active metadata, canonical fields, view support, select-option visibility, field order, width, aggregate operation, read-only state, drag and resize behavior, page-layout draft persistence, and column virtualization.
- Keep advanced filter metadata aligned with persisted filter shape, unresolved filter state, nested relation and composite traversal, structured value editors, actor sources, date operand conversion, time zones, read-only mode, local filter matching, and the query that consumes the filter.
- Keep record form and field rules aligned across inline edits, creation forms, variable values, relation and morph pickers, pagination, junction creation, file values, select options, validation, row-level permission defaults, read-only access, and the side-panel creation contract.
- Keep optimistic record changes aligned with metadata-selected query fields, lookup target fields, cache fragments, cursor pagination, cache eviction after metadata changes, batch progress and abort, aggregate views, relation links, rollback, browser events, and the surfaces that open the changed record.
- Keep record sharing aligned with object shareability, private state, managed general access, direct-link reads, viewer-scoped permission refresh, request ordering, principal type, recipient ordering, and role access notes.
- Keep group tabs aligned with visible groups, the All tab, active-group fallback, selection reset, group counts, responsive overflow, hidden groups, and the query limit used by section and tab views.
- Keep record queries aligned with object and relation permissions, requested relation identifiers, lookup target fields, junction validity, combined-object inputs, lazy-query retention, offset reads, aggregate operation names, stable cursors, and duplicate edge removal.
- Keep field surfaces aligned with object update access, field access, remote objects, deleted records, inverse relation update access, polymorphic target visibility, junction target visibility, canonical field selection, view support, and date or date-time time-zone rules.
- Keep activity creation and retrieval aligned with target junction metadata, target permissions, supported object types, status grouping, pagination, timeline event refresh, live message updates, happens-at grouping, file diff values, participant display, thread channel and conversation style, and activity row access states.
- Keep calendar creation aligned across account access, dates, time zones, place suggestions, target metadata, participant matching, target-link upsert, duplicate prevention, avatar context, and activity refresh.
- Keep email and app chat behavior aligned across channel type, conversation style, sender access, recipient context, message subscription, reply rules, idempotency, pending-send state, reactions, voice notes, attachment fields, visibility levels, preview and download permission, image upload, editor profile, scheduling, stored sent context, and read-only preview.
- Keep page-layout message widgets aligned with thread channel choice, pagination, live refresh, read state, connection recovery, widget filters, thread linking, composer actions, attachment flags, and side-panel navigation.
- Keep file actions aligned across upload initiation and completion, safe URLs, preview availability, private-host handling, video and audio load failure, download permission, attachment linking, soft-delete restore, renamed content, stable URL matching, removable chips, and field-widget file limits.
- Keep rich-text profiles aligned with supported blocks, indentation, image sizing, legacy parsing, controlled value synchronization, attachments, mention search, variable paste behavior, typography, and owner-specific save behavior.
- Keep page-layout drafts aligned with active metadata, widget states, table-widget view drafts, chat pagination, rich-text profiles, chart filter cleanup, widget configuration types, layout-mode positions, record target type, side-panel actions, and persisted local state.
- Keep chart drilldown and dashboard duplication aligned with chart filters, bucket values, group fields, sorts, view context, time zone, collection query parameters, cache insertion, aggregate formatting, and metadata error handling.
- Keep import field definitions aligned with writable metadata, composite sub-fields, relation unique keys, validation, value conversion, batch upsert, abort progress, and post-import cache refresh.
Refresh changed files:
- M packages/twenty-front/src/modules/command-menu/hooks/tests/useWorkflowCommandMenu.test.tsx
- M packages/twenty-front/src/modules/object-record/advanced-filter/hooks/useApplyAdvancedFilterRelationTargetField.ts
- M packages/twenty-front/src/modules/object-record/hooks/useCreateManyRecords.ts
- M packages/twenty-front/src/modules/object-record/object-filter-dropdown/components/ObjectFilterDropdownContentWrapper.tsx
- M packages/twenty-front/src/modules/object-record/object-filter-dropdown/components/ObjectFilterDropdownFilterInput.tsx
- M packages/twenty-front/src/modules/object-record/object-filter-dropdown/components/ObjectFilterDropdownInnerSelectOperandDropdown.tsx
- M packages/twenty-front/src/modules/object-record/object-filter-dropdown/components/ObjectFilterDropdownNumberInput.tsx
- M packages/twenty-front/src/modules/object-record/object-filter-dropdown/components/ObjectFilterDropdownOptionSelect.tsx
- M packages/twenty-front/src/modules/object-record/object-filter-dropdown/components/ObjectFilterDropdownTextInput.tsx
- A packages/twenty-front/src/modules/object-record/object-filter-dropdown/states/filterValueFieldMetadataItemUsedInDropdownComponentSelector.ts
- M packages/twenty-front/src/modules/object-record/object-options-dropdown/hooks/useObjectOptionsForBoard.ts
- M packages/twenty-front/src/modules/object-record/object-options-dropdown/hooks/useSetViewTypeFromLayoutOptionsMenu.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/components/RecordTableCellLookupFieldContext.tsx
- A packages/twenty-front/src/modules/object-record/record-column-lookup/components/RecordTableLookupTargetFieldSelectMenu.tsx
- A packages/twenty-front/src/modules/object-record/record-column-lookup/hooks/useGetLookupRelationFieldNames.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/hooks/useGetRecordFieldLookupTarget.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/hooks/useRecordFieldLookupTarget.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/states/isLookupColumnsEnabledSelector.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/states/recordFieldLookupTargetFamilySelector.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/tests/addLookupTargetsToRecordGqlFields.test.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/tests/getLookupTargetFieldMetadataItems.test.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/tests/getRecordFieldColumnHeader.test.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/tests/getRecordsWithLookupRelatedRecords.test.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/addLookupTargetsToRecordGqlFields.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/getLookupTargetFieldMetadataItems.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/getRecordFieldColumnHeader.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/getRecordFieldLookupTarget.ts
- A packages/twenty-front/src/modules/object-record/record-column-lookup/utils/getRecordsWithLookupRelatedRecords.ts
- M packages/twenty-front/src/modules/object-record/record-field/hooks/useChangeRecordFieldVisibility.ts
- M packages/twenty-front/src/modules/object-record/record-field/hooks/useRelevantRecordsGqlFields.ts
- M packages/twenty-front/src/modules/object-record/record-field/types/RecordField.ts
- A packages/twenty-front/src/modules/object-record/record-field/utils/tests/findCanonicalRecordField.test.ts
- A packages/twenty-front/src/modules/object-record/record-field/utils/tests/isCanonicalRecordField.test.ts
- A packages/twenty-front/src/modules/object-record/record-field/utils/tests/isRecordFieldSupportedByViewType.test.ts
- A packages/twenty-front/src/modules/object-record/record-field/utils/findCanonicalRecordField.ts
- A packages/twenty-front/src/modules/object-record/record-field/utils/isCanonicalRecordField.ts
- A packages/twenty-front/src/modules/object-record/record-field/utils/isRecordFieldSupportedByViewType.ts
- A packages/twenty-front/src/modules/object-record/record-filter/hooks/tests/useCreateEmptyRecordFilterFromFieldMetadataItem.test.tsx
- M packages/twenty-front/src/modules/object-record/record-filter/hooks/useCreateEmptyRecordFilterFromFieldMetadataItem.ts
- M packages/twenty-front/src/modules/object-record/record-filter/utils/getRecordFilterTypeAndLabelFromFieldMetadata.ts
- M packages/twenty-front/src/modules/object-record/record-index/export/hooks/useRecordIndexExportParameters.ts
- M packages/twenty-front/src/modules/object-record/record-index/export/hooks/useRecordIndexLazyFetchRecords.ts
- A packages/twenty-front/src/modules/object-record/record-index/hooks/tests/useHandleToggleColumnSort.test.tsx
- M packages/twenty-front/src/modules/object-record/record-index/hooks/useHandleToggleColumnSort.ts
- M packages/twenty-front/src/modules/object-record/record-index/hooks/useLoadRecordIndexStates.ts
- M packages/twenty-front/src/modules/object-record/record-table/components/RecordTableContextProvider.tsx
- M packages/twenty-front/src/modules/object-record/record-table/contexts/RecordTableUpdateContext.ts
- M packages/twenty-front/src/modules/object-record/record-table/empty-state/utils/tests/getEmptyStateSubTitle.test.ts
- M packages/twenty-front/src/modules/object-record/record-table/empty-state/utils/tests/getEmptyStateTitle.test.ts
- M packages/twenty-front/src/modules/object-record/record-table/empty-state/utils/getEmptyStateSubTitle.ts
- M packages/twenty-front/src/modules/object-record/record-table/empty-state/utils/getEmptyStateTitle.ts
- A packages/twenty-front/src/modules/object-record/record-table/hooks/tests/useDeleteRecordTableColumn.test.tsx
- M packages/twenty-front/src/modules/object-record/record-table/hooks/internal/useSetRecordTableData.ts
- A packages/twenty-front/src/modules/object-record/record-table/hooks/useCanAddRecordTableLookupColumns.ts
- A packages/twenty-front/src/modules/object-record/record-table/hooks/useDeleteRecordTableColumn.ts
- M packages/twenty-front/src/modules/object-record/record-table/record-table-cell/components/RecordTableCellDisplayMode.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-cell/components/RecordTableCellFieldContextGeneric.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-cell/components/RecordTableCellFieldContextLabelIdentifier.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-cell/components/RecordTableCellFieldContextWrapper.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-cell/components/RecordTableCellHotkeysEffect.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-cell/hooks/useOpenRecordTableCell.ts
- M packages/twenty-front/src/modules/object-record/record-table/record-table-cell/hooks/useOpenRecordTableCellFromCell.ts
- M packages/twenty-front/src/modules/object-record/record-table/record-table-footer/components/RecordTableAggregateFooterCell.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-header/components/RecordTableColumnHead.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-header/components/RecordTableColumnHeadDropdownMenu.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-header/components/RecordTableHeaderPlusButtonContent.tsx
- M packages/twenty-front/src/modules/object-record/record-table/record-table-header/hooks/useOpenRecordFilterChipFromTableHeader.ts
- A packages/twenty-front/src/modules/object-record/record-table/record-table-header/utils/tests/findNonAdvancedRecordFilterForColumn.test.ts
- A packages/twenty-front/src/modules/object-record/record-table/record-table-header/utils/findNonAdvancedRecordFilterForColumn.ts
- M packages/twenty-front/src/modules/object-record/record-table/types/OpenTableCellArgs.ts
- A packages/twenty-front/src/modules/object-record/record-table/types/RecordTableCellFieldTarget.ts
- A packages/twenty-front/src/modules/object-record/record-table/utils/getRecordTableCellInputIdPrefix.ts
- M packages/twenty-front/src/modules/object-record/record-table/virtualization/hooks/useGetShouldResetTableVirtualizationForUpdateInputs.ts
- M packages/twenty-front/src/modules/object-record/record-table/virtualization/hooks/useTriggerFetchPages.ts
- M packages/twenty-front/src/modules/object-record/record-table/virtualization/hooks/useTriggerInitialRecordTableDataLoad.ts
- M packages/twenty-front/src/modules/object-record/record-update-multiple/components/UpdateMultipleRecordsForm.tsx
- A packages/twenty-front/src/modules/object-record/record-update-multiple/utils/tests/getFieldsEditableInMultiEditForm.test.ts
- A packages/twenty-front/src/modules/object-record/record-update-multiple/utils/getFieldsEditableInMultiEditForm.ts
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A saved filter field, relation target, or target object no longer exists | The UI shows a rule that the query cannot use | Hydrate from current metadata and keep unresolved rules out of the active filter |
| A relation filter uses a target field that is not readable | The filter editor offers a path that cannot return valid values | Resolve the target field from current metadata and permissions before selecting its operands |
| A group tab changes the displayed rows but selection still uses all group rows | Bulk actions affect records outside the user's active group | Derive displayed and selectable IDs from the active tab and reset selection when the tab changes |
| A date operand changes from date-only to date-time without converting its value | The filter shifts by a day or uses an invalid instant | Rebuild the value in the user's time zone and use UTC for workflow record searches |
| A remote or non-editable object is treated as writable | The client offers an action that cannot succeed | Apply object metadata, field, view, and permission rules before showing create or edit controls |
| A lookup column is added to a widget view or without a related target field | The column cannot be persisted or its cells have no value source | Gate lookup columns by feature access, view persistence, active relation metadata, and readable target fields |
| A relation picker includes a target that the role cannot read or update | The user sees a record or link action that cannot be completed | Build searchable and pickable targets from current object and field permissions |
| A junction is invalid or its terminal targets are unreadable | A relation appears to support a link that cannot be shown or saved | Resolve junction metadata and require a usable junction with at least one readable target |
| A record query omits a relation target or label field needed by a surface | A chip, sort, group, lookup column, or widget shows an empty or unstable value | Generate fields from metadata and permissions for the requesting surface |
| A lazy query is replaced while metadata or permissions change | An in-flight read is aborted and its page state is lost | Retain the lazy query and update cursor state only from the completed result |
| An optimistic batch mutation fails after cache insertion | New or changed records remain visible although the server rejected them | Roll back the affected cache and shared-store entries, then refresh aggregates |
| A cursor query has no stable ID tie-breaker or page edges reuse a cursor | Adjacent pages can repeat or skip records | Add ID to cursor order and remove duplicate cursors when pages join |
| An activity target is not supported by the current junction metadata | A task, note, or event appears without the intended record link | Resolve target fields from current metadata and create only supported links |
| A calendar event is created but target linking fails | A retry creates a duplicate event | Close event creation after event persistence and report link failure separately |
| A message thread reconnects after more than one page was loaded | Refetching drops older messages from the open thread | Refresh only single-page threads and retain loaded pages for larger threads |
| The thread channel is unknown while the side-panel record footer renders | Chat actions and record actions appear in the wrong surface | Wait for channel loading and hide the footer for an app chat thread |
| A reply uses the first connected account instead of the thread channel | The reply is sent from the wrong mailbox or cannot be sent | Resolve the account from the last accessible message channel and fail closed when it is not visible |
| An app-channel retry creates a new send key | The same message can be delivered twice | Reuse the idempotency key for the same email payload |
| A pending chat message disappears before a refetch confirms it | The user cannot see or retry a send that failed | Keep pending messages local until the send or refetch settles |
| A restricted thread or message body is rendered as normal content | Private email or chat data is exposed | Gate opening, body rendering, reactions, and attachments on message visibility and restricted field values |
| A file media URL fails, points to a private host, or a file is deleted | The activity surface shows broken media or an unusable control | Fall back to a file chip or unavailable-preview state and expose download only when allowed |
| An attachment edit is not synced with rich-text content | Removed, restored, or renamed files drift from the activity body | Compare stable attachment paths and delete, restore, or rename attachments from the saved content paths |
| A campaign's list or topic is later deleted or hidden | A sent campaign loses the context of what it used | Read the stored IDs with soft-delete support and show unavailable values explicitly |
| A draft save updates the source but not default-value inputs | The composer shows stale list, subject, or body values | Resync seeded inputs after draft persistence and keep the draft state local until save |
| A relation diff clears a value but still renders the old record | Activity history reports a false relation state | Treat a null after value as Empty and keep the before value in the hover detail |
| A timeline groups by storage time instead of event time | History appears in the wrong month | Group entries by happensAt and sort groups from most recent to oldest |
| A chart keeps filters for deleted or inactive fields | The dashboard fails or reports values from an invalid filter | Sanitize chart filters against current field metadata before save and query |
| A field rename or deletion leaves old root record queries in the cache | Collections or groups continue to use stale field data | Evict the object's record and group queries on the metadata operation |
| A table column changes order or width without updating its owning view or draft | The visible table and saved layout disagree | Apply the same field change to local table state and the API or page-layout draft target |
| An inactive selected option is filtered out of a field picker | The user cannot see or remove the current value | Keep selected inactive options visible while excluding them from new choices |
| A page-layout thread widget treats an app channel as an email thread | The widget shows the wrong actions or sends through the wrong path | Resolve the channel before rendering the chat or email surface |
| A message widget refetches without retaining loaded pages | Older messages disappear after a live update or send | Preserve paged messages and fetch only the missing or new data |
Key files
| File | Why to read it |
|---|---|
| packages/…/RecordIndexContainer.tsx | Shows how a view selects the table, board, calendar, or list surface |
| packages/…/RecordIndexContainerGater.tsx | Shows the read-access boundary around a record collection |
| packages/…/RecordGroupTabs.tsx | Shows grouped view tabs, active-group selection, counts, and responsive display |
| packages/…/getActiveRecordGroupTabId.ts | Shows active-tab fallback when groups change |
| packages/…/useFindManyRecordIndexTableParams.ts | Shows how view filters, group filters, sort, and group limits form a record query |
| packages/…/useRecordIndexGroupsAggregatesGroupBy.ts | Shows how grouped totals use the current filters and visible groups |
| packages/…/RecordIndexEmptyState.tsx | Shows how empty, remote, deleted, filtered, and non-creatable states differ |
| packages/…/RecordTable.tsx | Shows the visible collection surface and empty-state boundary |
| packages/…/RecordTableColumnHeadDropdownMenu.tsx | Shows table filter, sort, move, hide, and lookup-column actions |
| packages/…/useResizeTableHeader.ts | Shows column resize feedback and persistence targets |
| packages/…/RecordTableColumnAggregateFooterDropdownContent.tsx | Shows field-type-aware table summaries |
| packages/…/RecordTableLookupTargetFieldSelectMenu.tsx | Shows how a related field becomes a lookup-column target |
| packages/…/RecordTableCellLookupFieldContext.tsx | Shows lookup-cell access and editability boundaries |
| packages/…/SelectFieldInput.tsx | Shows permission-aware select values and add-option behavior |
| packages/…/MultiSelectFieldInput.tsx | Shows multi-value selection and option filtering |
| packages/…/RecordTableRecordGroupSectionLoadMore.tsx | Shows automatic and manual loading for grouped records |
| packages/…/AdvancedFilterFieldSelectMenu.tsx | Shows metadata-aware filter field selection |
| packages/…/AdvancedFilterSidePanelValueFormInput.tsx | Shows type-aware filter values, relations, composite fields, and time zones |
| packages/…/useApplyAdvancedFilterRelationTargetField.ts | Shows filters that traverse from a relation to a target field |
| packages/…/ObjectFilterDropdownFilterInput.tsx | Shows the type-specific filter value surfaces |
| packages/…/PageLayoutRecordPageRenderer.tsx | Shows record-page layout selection, deleted-record notice, and side-panel actions |
| packages/…/useRecordShowPagePagination.ts | Shows neighbor navigation within the parent view |
| packages/…/useFindManyRecords.ts | Shows permission-aware record loading and cursor pagination |
| packages/…/generateDepthRecordGqlFieldsFromFields.ts | Shows metadata-driven relation and junction fields for record reads |
| packages/…/useGenerateCombinedFindManyRecordsQuery.ts | Shows permission-aware reads across several object types |
| packages/…/useUpdateOneRecord.ts | Shows optimistic update, rollback, aggregate refresh, and browser events |
| packages/…/useCreateManyRecords.ts | Shows batch creation, optimistic cache state, abort support, and cleanup |
| packages/…/useIncrementalFetchAndMutateRecords.ts | Shows progress and cancellation for large record changes |
| packages/…/FormMorphRelationToOneFieldInput.tsx | Shows readable target selection for polymorphic relations |
| packages/…/isRecordFieldReadOnly.ts | Shows the shared field editability rule |
| packages/…/useCompleteRecordUpdate.ts | Shows validation-aware completion before a record update |
| packages/…/useRefreshRecordPermissions.ts | Shows viewer-scoped permission refresh and stale-response protection |
| packages/…/useTimelineActivities.ts | Shows timeline filtering, live refresh, and linked-record loading |
| packages/…/useCalendarEventComposer.ts | Shows calendar validation, target linking, and duplicate-safe creation feedback |
| packages/…/useEmailThread.ts | Shows message loading, sender resolution, pagination, and reply-channel selection |
| packages/…/ChatThreadMessageGroup.tsx | Shows app chat grouping, visibility, reactions, and attachment display |
| packages/…/ChatThreadComposer.tsx | Shows pending app chat sends, file selection, retry, and discard behavior |
| packages/…/useEmailComposerState.ts | Shows email and app-channel send state, recipient checks, and idempotency |
| packages/…/EmailComposerFields.tsx | Shows sender choice, recipient fields, rich body, and attachments |
| packages/…/useSubscribeToMessageThreadMessages.ts | Shows live refresh for newly created thread messages and attachments |
| packages/…/MessageThreadWidget.tsx | Shows channel-based email or app chat widget selection |
| packages/…/ChatThreadWidgetContent.tsx | Shows app chat loading, reconnect, paging, and send access |
| packages/…/EmailThreadComposer.tsx | Shows widget email reply actions and attachment flow |
| packages/…/WidgetActionMessagesFilter.tsx | Shows conversation channel filtering in record widgets |
| packages/…/DocumentViewer.tsx | Shows supported previews and safe unavailable-file fallbacks |
| packages/…/useAttachmentSync.ts | Shows attachment delete, restore, and rename synchronization |
| packages/…/useBuildSpreadSheetImportFields.ts | Shows metadata-aware import fields and relation connection keys |
| packages/…/buildRecordFromImportedStructuredRow.ts | Shows import value conversion for structured fields and relations |
| packages/…/AdvancedTextEditor.tsx | Shows the shared rich-text writing surface |
| packages/…/RichTextFieldEditor.tsx | Shows record rich-text drafts, persistence, and attachment sync |
| packages/…/useSavePageLayout.ts | Shows layout draft validation and persisted state |
| packages/…/RecordTableWidgetProvider.tsx | Shows how record tables run inside page layouts |
| packages/…/buildChartDrilldownQueryParams.ts | Shows the path from a chart bucket to record work |
| packages/…/useDuplicateDashboard.ts | Shows dashboard duplication, cache insertion, and error handling |