@notionhq/custom-blocks 0.1.33 → 0.1.34

package/docs/data-sources.md

@@ -41,7 +41,10 @@ Use `row.update(...)` whenever you already have a row in hand. For pages you don
 ```ts
 function useDataSource(
   key: string,
-  options?: { limit?: number },
+  options?: {
+    limit?: number;
+    filter?: NotionDataSourceFilter;
+  },
 ): UseDataSourceResult;
 
 type UseDataSourceResult = {
@@ -56,7 +59,36 @@ type UseDataSourceResult = {
 };
 ```
 
-Reads the data source mapped to `key`. `limit` defaults to 20 and is capped at 999. To show more rows, keep the desired limit in your own component state and pass the larger value back into `useDataSource(key, { limit })`. `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.
+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.
+
+`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.
+
+```tsx
+const query = useDataSource("tasks", {
+  filter: {
+    and: [
+      { key: "title", title: { contains: "launch" } },
+      { key: "done", checkbox: { equals: false } },
+    ],
+  },
+  limit: 50,
+});
+```
+
+Filters support these property types:
+
+- 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`.
+
+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.
+
+The `and` group can contain up to 25 conditions. An empty group is valid. Nested groups and `or` groups are not supported.
+
+`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.
 
 Query failures follow the SDK's [error-handling contract](./errors.md).
 
@@ -161,7 +193,11 @@ export function ScoreList() {
 - `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`, currently `{ limit?: number }`.
+- `UseDataSourceOptions` — options accepted by `useDataSource`: `limit?: number` and `filter?: NotionDataSourceFilter`.
+- `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`.
+- `NotionDataSourceTextFilterOperator`, `NotionDataSourceNumberFilterOperator`, `NotionDataSourceCheckboxFilterOperator`, `NotionDataSourceOptionFilterOperator`, `NotionDataSourceContainsFilterOperator`, and `NotionDataSourceDateFilterOperator` — the operators accepted for each property type.
 
 ### Property schemas
 

package/package.json

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

package/src/bridge/SandboxBridge.ts

@@ -52,6 +52,7 @@ import {
 	NOTION_DARK_BACKGROUND_BASE,
 	NOTION_LIGHT_BACKGROUND_BASE,
 } from "./appearance.js"
+import { resolveDataSourceQuery } from "./dataSources/query.js"
 import { resolveDataSources } from "./dataSources/resolve.js"
 import { resolvePropertyWriteMapForDataSource } from "./dataSources/resolveProperty.js"
 import {
@@ -393,12 +394,14 @@ export class SandboxBridge {
 					nextBindings,
 				})
 				this.latestDataSourceBindings = nextBindings
-				// Drop cached query state for keys that no longer exist in the mapping.
+				// Drop cached query state for subscriptions whose key no longer exists.
 				const nextKeys = new Set(dataSources.map(s => s.key))
 				const prunedState: Record<string, DataSourceQueryState> = {}
-				for (const [key, state] of Object.entries(hostState.dataSourceState)) {
-					if (nextKeys.has(key)) {
-						prunedState[key] = state
+				for (const [subscriptionId, state] of Object.entries(
+					hostState.dataSourceState,
+				)) {
+					if (nextKeys.has(state.dataSourceKey)) {
+						prunedState[subscriptionId] = state
 					}
 				}
 				this.hostState = {
@@ -476,13 +479,10 @@ export class SandboxBridge {
 			}
 
 			case "queryDataSourceResult": {
-				const queryEntry = Object.entries(hostState.dataSourceState).find(
-					([, state]) => state.subscriptionId === message.subscriptionId,
-				)
-				if (queryEntry === undefined) {
+				const currentState = hostState.dataSourceState[message.subscriptionId]
+				if (currentState === undefined) {
 					return
 				}
-				const [key, currentState] = queryEntry
 				const queryResult =
 					message.status === "error"
 						? {
@@ -499,13 +499,14 @@ export class SandboxBridge {
 					...hostState,
 					dataSourceState: {
 						...hostState.dataSourceState,
-						[key]: {
+						[message.subscriptionId]: {
+							dataSourceKey: currentState.dataSourceKey,
 							items: queryResult.items,
 							isLoading: false,
 							hasMore: queryResult.hasMore,
 							error: queryResult.error,
-							subscriptionId: message.subscriptionId,
 							latestLimit: currentState.latestLimit,
+							latestQueryIdentity: currentState.latestQueryIdentity,
 						},
 					},
 				}
@@ -672,7 +673,15 @@ export class SandboxBridge {
 		}
 	}
 
-	queryDataSource(key: string, options: UseDataSourceOptions = {}) {
+	createDataSourceSubscriptionId(): string {
+		return `data-source:${globalThis.crypto.randomUUID()}`
+	}
+
+	queryDataSource(
+		subscriptionId: string,
+		key: string,
+		options: UseDataSourceOptions = {},
+	) {
 		if (this.hostState.status !== "initialized") {
 			return
 		}
@@ -680,10 +689,13 @@ export class SandboxBridge {
 		const dataSource = this.hostState.dataSources.find(
 			entry => entry.key === key,
 		)
+		const subscriptionState = this.hostState.dataSourceState[subscriptionId]
 		const currentState =
-			this.hostState.dataSourceState[key] ?? createEmptyDataSourceQueryState()
+			subscriptionState?.dataSourceKey === key
+				? subscriptionState
+				: createEmptyDataSourceQueryState(key)
 		if (dataSource === undefined) {
-			this.setDataSourceQueryError(key, currentState, {
+			this.setDataSourceQueryError(subscriptionId, currentState, {
 				code: "unknown_data_source_key",
 				message: `Unknown data source key "${key}". Known keys: [${this.hostState.dataSources.map(entry => entry.key).join(", ")}].`,
 				isRetryable: false,
@@ -691,7 +703,7 @@ export class SandboxBridge {
 			return
 		}
 		if (dataSource.collectionPointer === undefined) {
-			this.setDataSourceQueryError(key, currentState, {
+			this.setDataSourceQueryError(subscriptionId, currentState, {
 				code: "unmapped_data_source",
 				message: `Data source "${key}" has not been mapped to a database yet.`,
 				isRetryable: false,
@@ -699,15 +711,24 @@ export class SandboxBridge {
 			return
 		}
 
-		const limit = resolveDataSourceQueryLimit(options.limit)
-		const subscriptionId = makeDataSourceSubscriptionId({
+		const resolvedQuery = resolveDataSourceQuery({
+			dataSources: this.hostState.dataSources,
 			key,
+			options,
 		})
+		if (resolvedQuery.status === "error") {
+			this.setDataSourceQueryError(subscriptionId, currentState, {
+				code: "invalid_data_source_query",
+				message: resolvedQuery.error,
+				isRetryable: false,
+			})
+			return
+		}
+		const query = resolvedQuery.query
 
 		if (
 			currentState.isLoading &&
-			currentState.subscriptionId === subscriptionId &&
-			currentState.latestLimit === limit
+			currentState.latestQueryIdentity === query.identity
 		) {
 			return
 		}
@@ -716,12 +737,13 @@ export class SandboxBridge {
 			...this.hostState,
 			dataSourceState: {
 				...this.hostState.dataSourceState,
-				[key]: {
+				[subscriptionId]: {
 					...currentState,
+					dataSourceKey: key,
 					isLoading: true,
 					error: undefined,
-					subscriptionId,
-					latestLimit: limit,
+					latestLimit: query.limit,
+					latestQueryIdentity: query.identity,
 				},
 			},
 		}
@@ -730,14 +752,15 @@ export class SandboxBridge {
 		const outbound: QueryDataSourceMessage = {
 			type: "queryDataSource",
 			subscriptionId,
-			dataSourceId: dataSource.collectionPointer.id,
-			limit,
+			dataSourceId: query.dataSourceId,
+			limit: query.limit,
+			...(query.filter !== undefined ? { filter: query.filter } : {}),
 		}
 		this.postToHost(outbound)
 	}
 
 	private setDataSourceQueryError(
-		key: string,
+		subscriptionId: string,
 		currentState: DataSourceQueryState,
 		error: CustomBlockQueryDataSourceErrorInfo,
 	) {
@@ -748,18 +771,33 @@ export class SandboxBridge {
 			...this.hostState,
 			dataSourceState: {
 				...this.hostState.dataSourceState,
-				[key]: {
+				[subscriptionId]: {
 					...currentState,
 					isLoading: false,
 					error,
-					subscriptionId: undefined,
 					latestLimit: undefined,
+					latestQueryIdentity: undefined,
 				},
 			},
 		}
 		this.notify()
 	}
 
+	releaseDataSourceSubscription(subscriptionId: string) {
+		if (
+			this.hostState.status !== "initialized" ||
+			this.hostState.dataSourceState[subscriptionId] === undefined
+		) {
+			return
+		}
+		const { [subscriptionId]: _, ...dataSourceState } =
+			this.hostState.dataSourceState
+		this.hostState = {
+			...this.hostState,
+			dataSourceState,
+		}
+	}
+
 	postResize(height: number) {
 		if (typeof window === "undefined") {
 			return
@@ -1054,36 +1092,6 @@ function reuseDataSourcesForUnchangedBindings(args: {
 	})
 }
 
-// The default number of items to return in a live snapshot response if no limit is provided.
-const DEFAULT_DATA_SOURCE_QUERY_LIMIT = 20
-
-// The maximum number of items to return in a single live snapshot response.
-const MAX_DATA_SOURCE_QUERY_LIMIT = 999
-
-function resolveDataSourceQueryLimit(limit: number | undefined): number {
-	if (limit === undefined) {
-		return DEFAULT_DATA_SOURCE_QUERY_LIMIT
-	}
-	if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1) {
-		console.warn(
-			`[custom-blocks-sdk] useDataSource limit must be a positive integer; using ${DEFAULT_DATA_SOURCE_QUERY_LIMIT}.`,
-		)
-		return DEFAULT_DATA_SOURCE_QUERY_LIMIT
-	}
-	if (limit > MAX_DATA_SOURCE_QUERY_LIMIT) {
-		console.warn(
-			`[custom-blocks-sdk] useDataSource limit is capped at ${MAX_DATA_SOURCE_QUERY_LIMIT}.`,
-		)
-		return MAX_DATA_SOURCE_QUERY_LIMIT
-	}
-	return limit
-}
-
-function makeDataSourceSubscriptionId(args: { key: string }): string {
-	const { key } = args
-	return `data-source:${encodeURIComponent(key)}`
-}
-
 function invalidInitPayloadError(
 	issues: readonly v.BaseIssue<unknown>[],
 ): CustomBlockInitResultErrorInfo {