@notionhq/custom-blocks 0.1.43 → 0.1.44

package/docs/data-sources.md

@@ -1,47 +1,74 @@
 # Data sources
 
-A custom block declares its **data sources** — semantic keys like `people` or `tasks` — in the worker's `worker.customBlock(...)` configuration.
+Read the Notion rows your block needs with filters, sorts, and row limits. Your subscription keeps them current as the data changes.
 
-The mapping from those semantic keys to concrete Notion data sources is stored on each block instance and configured in Notion.
+Use `customBlock.subscribeToDataSource(...)` with any TypeScript UI framework. For React, `useDataSource(key, options)` provides the latest snapshot and handles subscription cleanup.
 
-Use `ManifestDataSource`, `ManifestProperty`, and `ManifestIcon` when code needs the corresponding definition metadata types.
+Each snapshot contains rows, property schemas, loading and error state, and `hasMore`. Each query result replaces the previous rows in the snapshot. Subscriptions remain independent, even when they query the same data source.
 
-At runtime, your code references the semantic key and the SDK handles the lookup for you. Use `useDataSource(key)` for the rows themselves (it also exposes the resolved schema), and use `useManifest()` when the UI must enumerate declared data sources, such as a dynamic key switcher. For non-React renderers, `customBlock.getManifest()` exposes the same manifest, but row querying is currently only exposed through the React `useDataSource` hook.
+Queries default to 20 rows and support up to 999. See [Known limitations](#known-limitations) for pagination, filter, and sort restrictions.
 
-## Pages within a data source
+## Bind a data source
 
-Each row returned by `useDataSource` is a `NotionDataSourcePage` — `{ id, propertiesById, propertiesByKey, update, archive, unarchive }`. Read property values through either of the two views:
+Declare the data your block needs under `dataSources` in `worker.customBlock(...)`. Give each declaration a key, such as `people`, and declare the properties your block uses.
 
-- `propertiesByKey[key]` — keyed by the semantic property keys you declared in the manifest.
-- `propertiesById[propertyId]` — keyed by the raw Notion property ID.
+When someone adds the block to Notion, they bind each declaration to a data source and map its properties. Your code queries the declared key and the SDK resolves the binding. This lets the same block work with different data sources across workspaces.
 
-The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) are always present in `propertiesById` (and `collectionSchema.propertiesById`), never in the `*ByKey` views — they don't have semantic keys.
+Prefer `propertiesByKey` when reading declared properties. These keys stay the same across bindings. `propertiesById` exposes values keyed by the bound data source's raw property IDs.
 
-### Updating a row
+Use `ManifestDataSource`, `ManifestProperty`, and `ManifestIcon` for declaration metadata. To list declared keys, use `useManifest()` in React or `customBlock.getManifest()` in TypeScript. These APIs are useful for a data source switcher.
 
-Each page carries its own `update` helper:
+## Subscribe to rows
+
+### `customBlock.subscribeToDataSource(args)`
 
 ```ts
-await row.update({
-  properties: {
-    score: { type: "number", number: 8 }, // semantic key
-  },
-  icon: { type: "emoji", emoji: "✅" },
-});
+function customBlock.subscribeToDataSource(
+  args: SubscribeToDataSourceArgs,
+): () => void;
+
+type SubscribeToDataSourceArgs = {
+  key: string;
+  onSnapshot: (snapshot: DataSourceSnapshot) => void;
+  options?: DataSourceQueryOptions;
+};
+
+type DataSourceQueryOptions = {
+  limit?: number;
+  filter?: NotionDataSourceFilter;
+  sorts?: NotionDataSourceSort[];
+};
 ```
 
-Property values can be keyed by **either** semantic keys or raw IDs. The SDK resolves semantic keys to IDs before sending the request.
+Each call registers the `onSnapshot` listener. When you unsubscribe that listener, other listeners remain subscribed. Queries start only after SDK initialization.
 
-Use `row.update(...)` whenever you already have a row in hand. For pages you don't have a row for (e.g. you only have a `pageId`), drop down to the top-level [`pages` API](./pages.md) — it covers create / get / update / archive / unarchive and accepts raw property IDs only.
+The listener receives the current snapshot immediately and receives later updates. Unrelated host changes do not trigger the listener. A new query result can trigger the listener even if its row values are unchanged. Each snapshot contains rows, schema, loading state, and row methods for updating, archiving, and unarchiving.
 
-### Archiving and unarchiving a row
+The SDK calls `onSnapshot` immediately with the current snapshot, before `subscribeToDataSource` returns.
 
-`row.archive()` is shorthand for calling `row.update({ is_archived: true })`.
-`row.unarchive()` is shorthand for calling `row.update({ is_archived: false })`.
-Both methods return an `UpdatePageResult`.
-Use `row.update` to change archive status and other fields in one request.
+```ts
+import { customBlock, initCustomBlock } from "@notionhq/custom-blocks";
+
+await initCustomBlock();
 
-## API
+const unsubscribe = customBlock.subscribeToDataSource({
+  key: "people",
+  onSnapshot: (snapshot) => render(snapshot),
+  options: {
+    limit: 50,
+    sorts: [{ key: "name", direction: "ascending" }],
+  },
+});
+
+// When the renderer unmounts:
+unsubscribe();
+```
+
+To change the query or request more rows, unsubscribe and create a new subscription with different options.
+
+Both APIs accept the [query options](#query-options) below. The SDK copies options when you subscribe. Later changes to the supplied object do not affect the subscription. A change to the data source definition repeats the query with the current options.
+
+`unsubscribe()` removes this SDK subscription and its listener, then sends `unsubscribeDataSourceQuery` to the host. The host stops future refreshes and ignores pending results for that subscription. Other subscriptions remain active. Repeated calls have no effect.
 
 ### `useDataSource(key, options?)`
 
@@ -67,80 +94,148 @@ type UseDataSourceResult = {
 };
 ```
 
-Reads the data source mapped to `key`. The SDK uses a default `limit` of 20 and caps it at 999. To request more rows, store the limit in component state and pass it to `useDataSource` again. Each request is bounded. The hook does not provide cursor pagination.
+Reads the data source mapped to `key`. To request more rows, store the limit in component state and pass it to `useDataSource` again.
+
+`propertyIdsByKey` maps manifest property keys to raw Notion property IDs; unbound keys map to `undefined`. `propertySchemasByKey` exposes the corresponding schemas and is likewise `undefined` for declared-but-unbound slots.
+
+`useDataSource` uses `customBlock.subscribeToDataSource` and returns its latest snapshot. A change to the key, limit, filter, or sorts replaces the subscription.
+
+Each consumer has its own host subscription. On unmount, the SDK removes its local query state and sends an unsubscribe message. The host stops future refreshes and ignores pending results. Other consumers remain subscribed.
+
+Query failures follow the SDK's [error-handling contract](./errors.md).
+
+## Query options
+
+Both subscription APIs accept `limit`, `filter`, and `sorts`.
 
-`filter` accepts one property condition or one shallow `and` group. Use `key` for a semantic property key. Use `propertyId` for a raw Notion property ID. The SDK resolves semantic keys before it sends the bridge request. The SDK reports local errors for unknown or unbound keys, property-type mismatches, unsupported filter fields, invalid operators, and invalid values.
+### Row limits
+
+`limit` defaults to 20 and must be a positive integer. The SDK caps values above 999. Each query reads from the start of the matching rows. A larger limit replaces the previous snapshot with a larger result.
+
+`hasMore` indicates that more matching rows exist beyond the result. It does not provide a cursor or guarantee that increasing the limit can retrieve every row.
+
+### Filters
+
+Use `filter` to select matching rows. Filters do not support every property type yet. Check [Property support](#property-support) before choosing a property.
+
+Use a single condition to match unfinished tasks:
+
+```ts
+filter: {
+  key: "done",
+  checkbox: { equals: false },
+}
+```
+
+Use `and` to match unfinished tasks whose titles also contain "launch":
+
+```ts
+filter: {
+  and: [
+    { key: "title", title: { contains: "launch" } },
+    { key: "done", checkbox: { equals: false } },
+  ],
+}
+```
+
+Here, `title` and `done` are declared property keys. Use `propertyId` instead of `key` when you have a raw property ID. The condition type, such as `checkbox`, must match the property's schema.
+
+Pass a single condition directly, or combine up to 25 conditions with `and`. Nested groups and `or` are unsupported. An empty `and` group applies no conditions. Both APIs accept the same filter shape.
+
+The SDK reports invalid keys, types, operators, and values through the snapshot's `error` field.
+
+<details>
+<summary>Filter operators and values</summary>
+
+| Property types | Filter operators |
+| --- | --- |
+| `title`, `rich_text`, `url`, `email`, `phone_number` | `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty` |
+| `number` | `equals`, `does_not_equal`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` |
+| `checkbox` | `equals`, `does_not_equal` |
+| `select`, `status` | `equals`, `does_not_equal`, `is_empty`, `is_not_empty` |
+| `multi_select` | `contains`, `contains_all`, `does_not_contain`, `is_empty`, `is_not_empty` |
+| `date` | `equals`, `before`, `after`, `on_or_before`, `on_or_after`, `is_empty`, `is_not_empty` |
+
+Select, multi-select, and status values can be one option name or an array of option names. For multi-select properties, `contains` matches any supplied option and `contains_all` requires every supplied option. Empty checks use `{ is_empty: true }` or `{ is_not_empty: true }`. Date comparisons accept ISO dates or ISO timestamps.
+
+</details>
+
+### Sorts
+
+Use `sorts` to order matching rows. Sorts do not support every property type yet, including some types that support filters. Check [Property support](#property-support) before choosing a property.
+
+This example sorts tasks by due date, with the earliest first. Tasks with the same due date use their creation time, newest first:
 
 ```tsx
 const query = useDataSource("tasks", {
-  filter: {
-    and: [
-      { key: "title", title: { contains: "launch" } },
-      { key: "done", checkbox: { equals: false } },
-    ],
-  },
-  sorts: [{ key: "due", direction: "ascending" }],
+  sorts: [
+    { key: "due", direction: "ascending" },
+    { propertyId: "created_time", direction: "descending" },
+  ],
   limit: 50,
 });
 ```
 
-Filters support these property types:
+Here, `due` is a declared date property key and `created_time` is a built-in property ID. Sorts apply in array order, with the first property taking priority. Empty values sort last in both directions.
 
-- Text properties: `title`, `rich_text`, `url`, `email`, and `phone_number`. They support `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, and `is_not_empty`.
-- `number`: `equals`, `does_not_equal`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, and `is_not_empty`.
-- `checkbox`: `equals` and `does_not_equal`.
-- `select` and `status`: `equals`, `does_not_equal`, `is_empty`, and `is_not_empty`.
-- `multi_select`: `contains`, `contains_all`, `does_not_contain`, `is_empty`, and `is_not_empty`.
-- `date`: `equals`, `before`, `after`, `on_or_before`, `on_or_after`, `is_empty`, and `is_not_empty`.
+You can sort by up to 10 unique properties. Both APIs accept the same sort shape, and you can combine `sorts` with `filter`.
 
-Select, multi-select, and status values can be one option name or an array of option names. For multi-select properties, `contains` matches any supplied option and `contains_all` requires every supplied option. Empty checks use `{ is_empty: true }` or `{ is_not_empty: true }`. Date comparisons accept ISO dates or ISO timestamps.
+## Pages within a data source
 
-The `and` group can contain up to 25 conditions. An empty group is valid. Nested groups and `or` groups are not supported.
+Each row returned by either API is a `NotionDataSourcePage` — `{ id, propertiesById, propertiesByKey, update, archive, unarchive }`. Read property values through either of the two views:
 
-`sorts` accepts a list of property addresses and directions. Use `key` for a
-semantic property key or `propertyId` for a raw Notion property ID. The SDK
-resolves semantic keys before it sends the bridge request. The host applies
-sorts in array order. The first sort has the highest priority. The list can
-contain up to ten unique properties. Empty values sort last in either
-direction. Sorts currently support title, rich text, number, checkbox, URL,
-email, phone number, date, created time, and last edited time properties.
-Other property types are rejected until their sort values are supported.
+- `propertiesByKey[key]` — keyed by the semantic property keys you declared in the manifest.
+- `propertiesById[propertyId]` — keyed by the raw Notion property ID.
 
-`propertyIdsByKey` maps manifest property keys to raw Notion property IDs; unbound keys map to `undefined`. `propertySchemasByKey` exposes the corresponding schemas and is likewise `undefined` for declared-but-unbound slots.
+The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) are always present in `propertiesById` and `collectionSchema.propertiesById`. They have no semantic keys, so they do not appear in the `*ByKey` views.
 
-Query failures follow the SDK's [error-handling contract](./errors.md).
+### Updating a row
 
-### `useManifest()`
+Each page carries its own `update` helper:
 
 ```ts
-function useManifest(): CustomBlockManifest;
+await row.update({
+  properties: {
+    score: { type: "number", number: 8 }, // semantic key
+  },
+  icon: { type: "emoji", emoji: "✅" },
+});
 ```
 
-Returns the authoritative block manifest received from the host during initialization, including the semantic data source keys plus their declared `name`, `description`, and property declarations. Most blocks should query a declared key directly:
+Property values can be keyed by **either** semantic keys or raw IDs. The SDK resolves semantic keys to IDs before sending the request.
 
-```tsx
-const query = useDataSource("tasks");
-```
+Use `row.update(...)` whenever you already have a row in hand. For pages you don't have a row for (e.g. you only have a `pageId`), drop down to the top-level [`pages` API](./pages.md) — it covers create / get / update / archive / unarchive and accepts raw property IDs only.
 
-Use `useManifest()` when the UI must enumerate declarations, such as a switcher that supports multiple data sources.
+### Archiving and unarchiving a row
 
-This API throws if called before initialization. This does not include host-resolved bindings nor does it include any actual data rows.
+`row.archive()` is shorthand for calling `row.update({ is_archived: true })`.
+`row.unarchive()` is shorthand for calling `row.update({ is_archived: false })`.
+Both methods return an `UpdatePageResult`.
+Use `row.update` to change archive status and other fields in one request.
 
-### `customBlock.getManifest()`
+## Read declarations
+
+Use the manifest when your UI needs to discover which data sources and properties the block declares. For example, build a data source switcher from the declared keys or table headings from the declared property names.
+
+Both APIs below return the declaration from `worker.customBlock(...)`, including its keys, names, descriptions, and property definitions. To query a selected data source, pass its key to either subscription API. Read resolved property IDs from the query snapshot's `propertyIdsByKey` map.
+
+Both APIs return synchronously and throw if called before `initCustomBlock()` resolves.
+
+### `useManifest()`
 
 ```ts
-function customBlock.getManifest(): CustomBlockManifest;
+function useManifest(): CustomBlockManifest;
 ```
 
-Framework-neutral getter for the same manifest returned by `useManifest()`. Throws if called before `initCustomBlock()` resolves. The manifest is static for the lifetime of the sandbox, so there is nothing to subscribe to.
+Returns the block manifest received from the host during initialization. The manifest contains declarations only. Resolved bindings and rows are available through query snapshots.
 
-```ts
-await initCustomBlock();
+### `customBlock.getManifest()`
 
-renderManifest(customBlock.getManifest());
+```ts
+function customBlock.getManifest(): CustomBlockManifest;
 ```
 
-`customBlock` does not yet expose a non-React equivalent of `useDataSource(key)`: querying rows, tracking `isLoading` / `hasMore`, and using row-level `update` helpers still require the React hook.
+Framework-neutral getter for the same manifest returned by `useManifest()`. The manifest is static for the lifetime of the sandbox, so there is nothing to subscribe to.
 
 ## Example: querying a data source
 
@@ -185,10 +280,10 @@ export function ScoreList() {
           </li>
         ))}
       </ul>
-      {hasMore ? (
+      {hasMore && limit < 999 ? (
         <button
           type="button"
-          onClick={() => setLimit(limit + 20)}
+          onClick={() => setLimit(Math.min(limit + 20, 999))}
           disabled={isLoading}
         >
           {isLoading ? "Loading…" : "Load more"}
@@ -199,6 +294,50 @@ export function ScoreList() {
 }
 ```
 
+## Known limitations
+
+- **Row limits and pagination:** `limit` defaults to 20 and is capped at 999. Queries have no cursor or offset. Increasing the limit repeats the query from the start and replaces the snapshot. `hasMore` can remain true at the cap, so use filters to narrow larger data sources.
+- **Filter and sort rules:** Use one property condition or one `and` group with up to 25 conditions. Nested groups and `or` are unsupported. Sort by up to 10 unique properties. Empty values sort last in both directions. See the table below for property support and [Filters](#filters) for operators.
+- **Changing a query:** TypeScript subscriptions copy their options when they start. To change them, unsubscribe and create a new subscription. React replaces the subscription when the key or options change. Previous rows are cleared while the new query loads.
+- **Updates:** Callbacks receive complete snapshots, not individual row changes. A new result can trigger a callback even when its row values are unchanged.
+
+### Property support
+
+The table shows the values returned by the Notion host and whether each property type supports filtering and sorting. ✅ means supported. ❌ means unsupported. ⚠️ marks a text fallback that does not preserve the property's structured value. Missing values can be `undefined`.
+
+| Property type | Query result | Filter | Sort |
+| --- | --- | :---: | :---: |
+| `title` | Plain text | ✅ | ✅ |
+| `rich_text` | Plain text | ✅ | ✅ |
+| `number` | Number | ✅ | ✅ |
+| `checkbox` | Boolean | ✅ | ✅ |
+| `url` | String | ✅ | ✅ |
+| `email` | String | ✅ | ✅ |
+| `phone_number` | String | ✅ | ✅ |
+| `select` | Option name | ✅ | ❌ |
+| `multi_select` | Array of option names | ✅ | ❌ |
+| `status` | Option name | ✅ | ❌ |
+| `date` | `NotionDateValue` | ✅ | ✅ |
+| `people` | Array of record pointers | ❌ | ❌ |
+| `files` | ⚠️ Text fallback | ❌ | ❌ |
+| `unique_id` | ⚠️ Text fallback | ❌ | ❌ |
+| `relation` | Array of record pointers | ❌ | ❌ |
+| `place` | ⚠️ Text fallback | ❌ | ❌ |
+| `formula` | ⚠️ Text fallback | ❌ | ❌ |
+| `rollup` | ⚠️ Text fallback | ❌ | ❌ |
+| `button` | ⚠️ Text fallback | ❌ | ❌ |
+| `verification` | ⚠️ Text fallback | ❌ | ❌ |
+| `last_visited_time` | ⚠️ Text fallback | ❌ | ❌ |
+| `location` | ⚠️ Text fallback | ❌ | ❌ |
+| `created_time` | `NotionDateTime` in UTC | ❌ | ✅ |
+| `last_edited_time` | `NotionDateTime` in UTC | ❌ | ✅ |
+| `created_by` | Array of record pointers | ❌ | ❌ |
+| `last_edited_by` | Array of record pointers | ❌ | ❌ |
+
+Text values omit formatting, mention tokens, and annotations. Record pointers contain a table name and a record ID.
+
+Use `propertyId: "created_time"` or `propertyId: "last_edited_time"` to sort by these built-in timestamps.
+
 ## Types
 
 ### Rows & values
@@ -207,14 +346,15 @@ export function ScoreList() {
 - `NotionDataSourcePage` — a single row exposed to app code: `{ id, propertiesById, propertiesByKey, update, archive, unarchive }`.
 - `NotionDataSourceValue` — the value union for `propertiesById` and `propertiesByKey`.
 - `NotionDataSourcePageUpdateArgs` / `UpdatePageResult` — arguments and result for the per-page `update` helper.
-- `NotionDataSourcePageUpdateInput` — deprecated alias for `NotionDataSourcePageUpdateArgs`.
-- `NotionDataSourcePageUpdateResult` — deprecated alias for `UpdatePageResult`.
 - `UseDataSourceOptions` — options accepted by `useDataSource`: `limit?: number`, `filter?: NotionDataSourceFilter`, and `sorts?: NotionDataSourceSort[]`.
 - `NotionDataSourceFilter` — one property condition or one shallow `and` group.
 - `NotionDataSourcePropertyFilter` — one property address combined with a type-specific operator.
 - `NotionDataSourcePropertyAddress` — either a semantic property `key` or a raw `propertyId`.
 - `NotionDataSourceSort` — a property address with an `ascending` or `descending` direction.
 - `NotionDataSourceTextFilterOperator`, `NotionDataSourceNumberFilterOperator`, `NotionDataSourceCheckboxFilterOperator`, `NotionDataSourceOptionFilterOperator`, `NotionDataSourceContainsFilterOperator`, and `NotionDataSourceDateFilterOperator` — the operators accepted for each property type.
+- `DataSourceSnapshot` — current rows, schema, and status for one live data-source query.
+- `DataSourceQueryOptions` — the row limit, filter, and sorts shared by both query APIs.
+- `SubscribeToDataSourceArgs` — the key, `onSnapshot` listener, and optional query options for `customBlock.subscribeToDataSource`.
 
 ### Property schemas
 

package/docs/lifecycle.md

@@ -150,7 +150,7 @@ All code types are open string unions, so keep a default branch. Use `isRetryabl
 
 Framework-neutral runtime APIs for renderers that do not use React hooks. `customBlock.getState()` returns a `CustomBlockState` snapshot that includes `theme` and `contrastMode` while hiding internal query cache details. All getters that read host state — `getTheme`, `getContrastMode`, `getBlockId`, `getParent`, `getPage`, `getCurrentUser`, and `getManifest` — throw until `initCustomBlock()` resolves. `getManifest()` then returns the authoritative manifest supplied by the host.
 
-`customBlock` covers runtime state and sizing. Row querying still goes through `useDataSource`, while imperative APIs such as `pages.*` and `users.*` are already framework-neutral functions.
+`customBlock` covers runtime state, live data source snapshots, and sizing. Imperative APIs such as `pages.*` and `users.*` are also framework-neutral functions.
 
 ```ts
 await initCustomBlock();
@@ -177,16 +177,6 @@ stopAutoResize();
 
 Thrown when `initCustomBlock` is called in a top-level tab (no parent frame). It extends `CustomBlockInitializationError`, has `code: "not_in_iframe"` and `isRetryable: false`, and can be detected specifically with `instanceof NotInIframeError`. `<NotionCustomBlock>` catches it and falls back to a standalone preview with a warning banner.
 
-### `useCustomBlockAutoResize({ enabled? })`
-
-Deprecated. Blocks resize automatically. Use CSS `max-height` and `overflow` to set a shorter height.
-
-```ts
-function useCustomBlockAutoResize(args?: { enabled?: boolean }): void;
-```
-
-Deprecated React wrapper around `customBlock.autoResize({ target: document.getElementById("root") })`. It measures `#root`'s height and posts `resize` messages, deduping unchanged values. `<NotionCustomBlock>` runs this automatically.
-
 ## Debug console
 
 Press `\` while focused in a custom block to toggle a debug overlay that replaces the block's children with a `<pre>` log of every `postMessage` sent and received over the bridge. Each line is formatted as:

package/docs/pages.md

@@ -161,7 +161,5 @@ Do **not** send `{ type: "file_upload", file_upload: { id } }`; the host will re
 - `NotionPagePropertyWriteMap` — input map for `pages.update` (raw property IDs only).
 - `NotionCreatePagePosition` — `start` / `end` / `before` / `after` insertion variants.
 - `CreatePageArgs` / `CreatePageParent` / `CreatePageResult`.
-- `CreatePageInput` — deprecated alias for `CreatePageArgs`.
 - `GetPageResult`.
 - `UpdatePageArgs` / `UpdatePageResult`.
-- `UpdatePageInput` — deprecated alias for `UpdatePageArgs`.

package/docs/users.md

@@ -78,5 +78,4 @@ if (result.status === "success") {
 - `useCurrentUser()` — hook that returns the viewer's `NotionUser`.
 - `customBlock.getCurrentUser()` — framework-neutral getter for the viewer's `NotionUser`.
 - `ListUsersArgs` / `ListUsersResult`.
-- `ListUsersInput` — deprecated alias for `ListUsersArgs`.
 - `GetUserResult`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.43",
+	"version": "0.1.44",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {

package/src/bridge/SandboxBridge.ts

@@ -32,6 +32,7 @@ import type { ListUsersMessage } from "@notionhq/custom-blocks-protocol/messages
 import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import type { CustomBlockQueryDataSourceErrorInfo } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
 import type { ResizeMessage } from "@notionhq/custom-blocks-protocol/messages/resize.js"
+import type { UnsubscribeDataSourceQueryMessage } from "@notionhq/custom-blocks-protocol/messages/unsubscribeDataSourceQuery.js"
 import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
 import { CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/protocolVersion.js"
 import type { NotionTheme } from "@notionhq/custom-blocks-protocol/theme.js"
@@ -40,6 +41,7 @@ import { globalPrimedResponsesCache } from "../testing.js"
 import type {
 	CreatePageArgs,
 	CreatePageResult,
+	DataSourceQueryOptions,
 	GetPageResult,
 	GetUserResult,
 	ListUsersArgs,
@@ -48,7 +50,6 @@ import type {
 	NotionUserId,
 	UpdatePageArgs,
 	UpdatePageResult,
-	UseDataSourceOptions,
 } from "../types.js"
 import { unreachable } from "../utils.js"
 import { CUSTOM_BLOCKS_SDK_VERSION } from "../version.js"
@@ -65,6 +66,7 @@ import {
 	type DataSourceQueryState,
 } from "./hostState.js"
 import type { ManifestLoadResult } from "./loadManifest.js"
+import { notifyListener } from "./notifyListener.js"
 import { PendingRequests } from "./pendingRequests.js"
 
 /**
@@ -88,6 +90,14 @@ const RESPONSE_TYPE_BY_REQUEST = new Map([
 
 const INIT_RESULT_TIMER_FALLBACK_MS = 100
 
+export type QueryDataSourceArgs = {
+	subscriptionId: string
+	key: string
+	options?: DataSourceQueryOptions
+	/** Send the query even if an identical query is already loading. */
+	forceRequery?: boolean
+}
+
 export class SandboxBridge {
 	private hostState: CustomBlockHostState = {
 		status: "uninitialized",
@@ -281,7 +291,7 @@ export class SandboxBridge {
 
 	private notify = () => {
 		for (const listener of this.listeners) {
-			listener()
+			notifyListener(listener)
 		}
 	}
 
@@ -437,15 +447,27 @@ export class SandboxBridge {
 					nextBindings,
 				})
 				this.latestDataSourceBindings = nextBindings
-				// Drop cached query state for subscriptions whose key no longer exists.
-				const nextKeys = new Set(dataSources.map(s => s.key))
+				// Preserve rows only while the key still refers to the same backing data source.
+				const previousSourcesByKey = new Map(
+					hostState.dataSources.map(source => [source.key, source]),
+				)
+				const nextSourcesByKey = new Map(
+					dataSources.map(source => [source.key, source]),
+				)
 				const prunedState: Record<string, DataSourceQueryState> = {}
 				for (const [subscriptionId, state] of Object.entries(
 					hostState.dataSourceState,
 				)) {
-					if (nextKeys.has(state.dataSourceKey)) {
-						prunedState[subscriptionId] = state
+					const nextSource = nextSourcesByKey.get(state.dataSourceKey)
+					if (nextSource === undefined) {
+						continue
 					}
+					const previousSource = previousSourcesByKey.get(state.dataSourceKey)
+					prunedState[subscriptionId] =
+						previousSource?.collectionPointer?.id ===
+						nextSource.collectionPointer?.id
+							? state
+							: createEmptyDataSourceQueryState(state.dataSourceKey)
 				}
 				this.hostState = {
 					...hostState,
@@ -720,11 +742,12 @@ export class SandboxBridge {
 		return `data-source:${globalThis.crypto.randomUUID()}`
 	}
 
-	queryDataSource(
-		subscriptionId: string,
-		key: string,
-		options: UseDataSourceOptions = {},
-	) {
+	queryDataSource({
+		subscriptionId,
+		key,
+		options = {},
+		forceRequery = false,
+	}: QueryDataSourceArgs) {
 		if (this.hostState.status !== "initialized") {
 			return
 		}
@@ -770,6 +793,7 @@ export class SandboxBridge {
 		const query = resolvedQuery.query
 
 		if (
+			!forceRequery &&
 			currentState.isLoading &&
 			currentState.latestQueryIdentity === query.identity
 		) {
@@ -790,8 +814,6 @@ export class SandboxBridge {
 				},
 			},
 		}
-		this.notify()
-
 		const outbound: QueryDataSourceMessage = {
 			type: "queryDataSource",
 			subscriptionId,
@@ -801,6 +823,7 @@ export class SandboxBridge {
 			...(query.sorts !== undefined ? { sorts: query.sorts } : {}),
 		}
 		this.postToHost(outbound)
+		this.notify()
 	}
 
 	private setDataSourceQueryError(
@@ -840,6 +863,11 @@ export class SandboxBridge {
 			...this.hostState,
 			dataSourceState,
 		}
+		const outbound: UnsubscribeDataSourceQueryMessage = {
+			type: "unsubscribeDataSourceQuery",
+			subscriptionId,
+		}
+		this.postToHost(outbound)
 	}
 
 	postResize(height: number) {