Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Shared database editor
DatabaseProvider owns one editor controller. A host supplies DatabaseApi with a
stable cache key, schema reads, paginated row reads, and atomic operation batches.
DatabaseRecords supplies the standard column controls, grid, board, timeline and
record panel. The host supplies presentation slots and navigation when needed.
const [view, setView] = createSignal<DatabaseViewState>({
query: { filter: null },
layout: { kind: 'table', columns: [] },
});
<DatabaseProvider
api={api}
tableId={tableId}
view={view()}
capabilities={{ editRows: canEdit, editColumns: canEditSchema }}
>
<DatabaseRecords
view={view()}
stored={false}
onViewChange={(change) => setView((view) => ({ ...view, ...change }))}
renderMentionPicker={HostMentionPicker}
/>
</DatabaseProvider>
Mount under the application's QueryClientProvider, or supply one for a standalone
surface. Remount the database provider when its API identity or table changes;
views and permission changes are reactive within that lifetime. useDatabase()
exposes the controller to other controls inside this editor. Small presentation
components remain usable with props and without this context.
API semantics
readTablereturns normalized editor columns, with names, types, options and protections. Hosts convert their transport DTOs at the adapter boundary.readRowsapplies the requested filter and sort before pagination. Every page carries its table version. The shared source restarts inconsistent reads rather than combining pages from different versions.rowIdsreads retained records outside the active filter, so an open record remains available.applyOpsuses the existingDatabaseOpprotocol and optionalbaseVersions. It must commit the batch atomically. The shared row writer adds missing options in the same batch and distinguishes a refused insert from an unknown outcome.- A successful commit remains successful if a subsequent refresh fails. The queries own refresh errors; retrying the mutation could duplicate an insert.
The API does not require SQL reads, a Macro database entity, Soup, app block
context, or a particular URL layout. DatabaseApi.key must identify the host and
resource within the query cache. Authentication and resource authorization belong
to the host's API/service; UI capabilities only determine which controls appear.
Host capabilities
onComposeRecord lets a host collect required fields for board and timeline
creation. It receives the selected lane/group and date-range values before any
row is written; hosts without a composer retain direct row creation.
onOpenRecord takes over opening a record someone clicks (a row's open button,
a board card, a timeline bar, a saved-record notice), in place of the record
panel, and returns whether it opened it; when it could not, the panel opens. A
document's database card opens the full database at that row, and keeps the panel
where there are no splits (call chat). Records the view opens itself, such as one
just created, keep the panel.
editRows and editColumns enable their respective controls. Optional record-view
props supply persisted board positions, conversion previews, relationships,
presence, and stored-view changes. Omit an unsupported action. A board can render
without a position writer; it cannot offer card moves that pretend to persist.
Pending card moves use the board overlay; update saved positions only after a
successful response so refusals preserve the prior order and other pending moves.
Hosts load saved positions for the selected view before enabling moves and keep
the position cache scoped to that view. Hosts that switch boards supply a stable
BoardPositions.viewId so pending visual moves and sort prompts retire when the
selected board changes. Reading move and setPositions must bind those
capabilities to the originating view; a pending response must not update the
newly selected view's cache. Cards reuse GridCell with wrapping
enabled, labels above each value, and an explicit empty-value dash. Keep the
drag grip outside CardActions, whose descendants opt out of dragging.
onComposeRecord replaces a board lane's inline card with the host's own form,
seeded with the lane's values; the form creates its row with the actions'
createRow. A GridCell rendered inside a modal dialog takes popupMount so
its menus stay inside the dialog, which blocks the page around it.
View preferences in the example are local; hosts that save views pass their own
view state and authorized persistence callback. Shared filter, sort, toolbar and
view components are in components/.
The Macro app's DatabaseGrid supplies an optimized DatabaseDataSource to the
same provider, preserving SQL caching, incremental updates and first-value type
inference. Normal API hosts use the provider's built-in paginated source. Both
paths share row-op construction and the schema controller. The app keeps its
sharing, navigation, Forms integration and concrete network clients in
features/block-database/.
The API-only browser fixture is in
../block-database/browser-test/api.tsx. It exercises pagination, row edits,
column creation, permission changes and board rendering without app providers
beyond the query client. The CRM feature uses createPipelineApi and the same provider/controller; its
browser fixture is ../crm/browser-test/editor.tsx.