@notionhq/custom-blocks 0.0.58

package/src/react/NotionCustomBlock.tsx

@@ -0,0 +1,151 @@
+import { type ReactNode, useEffect, useState } from "react"
+import { type InitCustomBlockOptions, NotInIframeError } from "../index.js"
+import { DebugMessageLog } from "./DebugMessageLog.js"
+import { seedStandalonePreviewState } from "./standalonePreview.js"
+import { useCustomBlockAutoResize } from "./useCustomBlockAutoResize.js"
+import { useCustomBlockInit } from "./useCustomBlockInit.js"
+import { useCustomBlockHost } from "./useHostState.js"
+import "./NotionCustomBlock.css"
+
+/**
+ * Props accepted by {@link NotionCustomBlock}.
+ */
+export type NotionCustomBlockProps = InitCustomBlockOptions & {
+	children: ReactNode
+	/**
+	 * Rendered while the SDK ↔ host handshake is in progress. Defaults to
+	 * `null` (nothing).
+	 */
+	fallback?: ReactNode
+	/**
+	 * Rendered when the handshake fails. Either a node, or a function that
+	 * receives the `Error`. When omitted, a friendly default error card is
+	 * rendered with developer details — replace it for production templates.
+	 */
+	errorFallback?: ReactNode | ((error: Error) => ReactNode)
+	/**
+	 * Whether the provider should automatically post resize messages so the
+	 * host iframe matches the content height of `#root`. Defaults to `true`.
+	 * Pass `false` when you want to use the default block size and are ok
+	 * with scrollbars within the Notion client.
+	 *
+	 * @default true
+	 */
+	autoResize?: boolean
+}
+
+/**
+ * Top-level wrapper that runs the SDK ↔ host handshake and gates `children`
+ * until it resolves. Passes `timeoutMs` straight through to
+ * {@link initCustomBlock}.
+ *
+ * Templates that prefer not to write a `Root` gating component (or top-level
+ * `await`) can mount their app entirely inside this provider:
+ *
+ * ```tsx
+ * ReactDOM.createRoot(root).render(
+ *   <NotionCustomBlock>
+ *     <App />
+ *   </NotionCustomBlock>,
+ * )
+ * ```
+ *
+ * Inside `children`, every SDK hook is guaranteed to return a populated
+ * value. Outside the provider (or during the loading window), they throw.
+ */
+export function NotionCustomBlock({
+	children,
+	timeoutMs,
+	fallback = null,
+	errorFallback,
+	autoResize = true,
+}: NotionCustomBlockProps) {
+	const init = useCustomBlockInit({ timeoutMs })
+	useCustomBlockAutoResize({ enabled: autoResize })
+	const isStandalone = init.error instanceof NotInIframeError
+	const host = useCustomBlockHost()
+	const [debugOpen, setDebugOpen] = useState(false)
+
+	useEffect(() => {
+		const onKeyDown = (e: KeyboardEvent) => {
+			if (e.key === "\\") {
+				setDebugOpen(prev => !prev)
+			}
+		}
+		window.addEventListener("keydown", onKeyDown)
+		return () => window.removeEventListener("keydown", onKeyDown)
+	}, [])
+
+	useEffect(() => {
+		if (!isStandalone) {
+			return
+		}
+		console.warn(`[notion-custom-sdk] ${init.error?.message}`)
+		seedStandalonePreviewState()
+	}, [isStandalone, init.error])
+
+	if (debugOpen) {
+		return <DebugMessageLog />
+	}
+	if (init.error && !isStandalone) {
+		if (errorFallback === undefined) {
+			return <DefaultInitErrorFallback error={init.error} />
+		}
+		return (
+			<>
+				{typeof errorFallback === "function"
+					? errorFallback(init.error)
+					: errorFallback}
+			</>
+		)
+	}
+	if (isStandalone) {
+		// Wait for the effect to seed placeholder host state; otherwise hooks
+		// in `children` would throw.
+		if (host.status !== "initialized") {
+			return <>{fallback}</>
+		}
+		return (
+			<>
+				<div role="status" className="ncblock-standalone-banner">
+					Notion host not detected — running in standalone preview. SDK hooks
+					return placeholder values until embedded in Notion.
+				</div>
+				{children}
+			</>
+		)
+	}
+	if (!init.isLoaded) {
+		return <>{fallback}</>
+	}
+	return <>{children}</>
+}
+
+// TODO(custom-blocks): Align the styling of this with the host-side error states.
+function DefaultInitErrorFallback({ error }: { error: Error }) {
+	useEffect(() => {
+		console.warn(
+			`[notion-custom-sdk] Custom block init failed: ${error.message}`,
+		)
+	}, [error])
+
+	return (
+		<div role="alert" className="ncblock-default-init-error">
+			<div className="ncblock-default-init-error__card">
+				<div className="ncblock-default-init-error__eyebrow">Custom block</div>
+				<h2 className="ncblock-default-init-error__title">
+					Couldn&apos;t connect to Notion
+				</h2>
+				<p className="ncblock-default-init-error__body">
+					This custom block loaded, but the setup handshake didn&apos;t finish.
+					Try again from Notion. If this keeps happening, check the browser
+					console for SDK details.
+				</p>
+				<details className="ncblock-default-init-error__details">
+					<summary>Developer details</summary>
+					<pre className="ncblock-default-init-error__pre">{error.message}</pre>
+				</details>
+			</div>
+		</div>
+	)
+}

package/src/react/index.ts

@@ -0,0 +1,28 @@
+/**
+ * React entrypoint for `@notionhq/custom-blocks/react`.
+ *
+ * Exposes only the React surface — components and hooks. Framework-neutral
+ * values and types (clients, manifest/data-source types, etc.) live on the
+ * `@notionhq/custom-blocks` entrypoint and are intentionally NOT re-exported
+ * here, so the two public surfaces stay disjoint.
+ */
+
+export {
+	NotionCustomBlock,
+	type NotionCustomBlockProps,
+} from "./NotionCustomBlock.js"
+export { useCustomBlockAutoResize } from "./useCustomBlockAutoResize.js"
+export {
+	type CustomBlockInitFailure,
+	type UseCustomBlockInitResult,
+	useCustomBlockInit,
+} from "./useCustomBlockInit.js"
+export { useDataSource } from "./useDataSource.js"
+export {
+	useBlockId,
+	useCurrentUser,
+	useManifest,
+	usePage,
+	useParent,
+	useTheme,
+} from "./useRuntimeState.js"

package/src/react/standalonePreview.ts

@@ -0,0 +1,28 @@
+import * as v from "valibot"
+import { notionBlockIdSchema, notionPageIdSchema } from "../bridge/ids.js"
+import { customBlockHost } from "../bridge/sandboxClient.js"
+
+const previewBlockId = v.parse(notionBlockIdSchema, "")
+const previewPageId = v.parse(notionPageIdSchema, "")
+
+export function seedStandalonePreviewState() {
+	customBlockHost.setMockState({
+		type: "init",
+		status: "success",
+		theme: "light",
+		blockId: previewBlockId,
+		parent: { type: "page_id", page_id: previewPageId },
+		page: { id: previewPageId },
+		dataSources: { bindings: {} },
+		currentUser: {
+			object: "user",
+			id: "",
+			name: "Preview User",
+			avatar_url: null,
+			type: "person",
+			person: {
+				email: "preview@example.com",
+			},
+		},
+	})
+}

package/src/react/useCustomBlockAutoResize.ts

@@ -0,0 +1,46 @@
+import { useEffect } from "react"
+import { customBlock } from "../index.js"
+
+/**
+ * Measures the sandbox's `#root` element and posts `resize` messages so the host iframe
+ * matches the block's border-box height. Unchanged values are deduped.
+ *
+ * `<NotionCustomBlock>` calls this hook for you by default — only reach for it directly
+ * when you need to drive `enabled` yourself (e.g. behind a debug toggle). In that case,
+ * pass `autoResize={false}` to the provider to avoid running it twice. For full-bleed
+ * views that should fill their slot, pass `autoResize={false}` and skip the hook.
+ *
+ * @example
+ * <NotionCustomBlock autoResize={false}>
+ *   <App />
+ * </NotionCustomBlock>
+ *
+ * function App() {
+ *   const [enabled, setEnabled] = useState(true)
+ *   useCustomBlockAutoResize({ enabled })
+ *   return <div>…</div>
+ * }
+ */
+export function useCustomBlockAutoResize(
+	args: {
+		/**
+		 * Whether or not the hook is enabled. To disable this behavior, pass `false`. This is
+		 * provided as an argument to allow for conditional disabling of the hook.
+		 *
+		 * @default true
+		 */
+		enabled?: boolean
+	} = {},
+): void {
+	const { enabled = true } = args
+	useEffect(() => {
+		if (!enabled) {
+			return
+		}
+		if (typeof window === "undefined") {
+			return
+		}
+		const target = document.getElementById("root")
+		return customBlock.autoResize({ target })
+	}, [enabled])
+}

package/src/react/useCustomBlockInit.ts

@@ -0,0 +1,91 @@
+import { useEffect, useState } from "react"
+import { CustomBlockInitError } from "../bridge/messages/init.js"
+import {
+	type CustomBlockInitial,
+	type InitCustomBlockOptions,
+	initCustomBlock,
+	NotInIframeError,
+} from "../init.js"
+
+export type CustomBlockInitFailure = CustomBlockInitError | NotInIframeError
+
+/**
+ * Discriminated state returned by {@link useCustomBlockInit}.
+ *
+ * Branch on `isLoaded`/`error`:
+ * - `{ isLoaded: false, error: undefined }` — handshake in progress.
+ * - `{ isLoaded: false, error: CustomBlockInitFailure }` — handshake failed (most commonly a
+ *   `CustomBlockInitError` with code `init_timeout` because the host never sent `init`).
+ * - `{ isLoaded: true, initial }` — handshake complete; safe to render
+ *   children that call `useTheme`, `useBlockId`, etc.
+ */
+export type UseCustomBlockInitResult =
+	| { isLoaded: false; error: undefined }
+	| { isLoaded: false; error: CustomBlockInitFailure }
+	| { isLoaded: true; error: undefined; initial: CustomBlockInitial }
+
+/**
+ * React wrapper around {@link initCustomBlock}. Kicks off the SDK ↔ host
+ * handshake on mount and returns a discriminated state object so the rest of
+ * the tree can render inside the `isLoaded === true` branch (where every
+ * other SDK hook is guaranteed to return a populated value).
+ *
+ * Idempotent — multiple components can call this; they share the same
+ * underlying handshake promise.
+ *
+ * @example
+ * function Root() {
+ *   const init = useCustomBlockInit()
+ *   if (init.error) return <p role="alert">Init failed: {init.error.message}</p>
+ *   if (!init.isLoaded) return null
+ *   return <App />
+ * }
+ */
+export function useCustomBlockInit(
+	opts?: InitCustomBlockOptions,
+): UseCustomBlockInitResult {
+	const [state, setState] = useState<UseCustomBlockInitResult>({
+		isLoaded: false,
+		error: undefined,
+	})
+	useEffect(() => {
+		let cancelled = false
+		initCustomBlock(opts).then(
+			initial => {
+				if (!cancelled) {
+					setState({ isLoaded: true, error: undefined, initial })
+				}
+			},
+			err => {
+				if (!cancelled) {
+					setState({
+						isLoaded: false,
+						error: normalizeInitError(err),
+					})
+				}
+			},
+		)
+		return () => {
+			cancelled = true
+		}
+		// `initCustomBlock` caches its result, so options after the first call
+		// are ignored — re-running on opts changes would be misleading.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [])
+	return state
+}
+
+function normalizeInitError(error: unknown): CustomBlockInitFailure {
+	if (
+		error instanceof CustomBlockInitError ||
+		error instanceof NotInIframeError
+	) {
+		return error
+	}
+	const message = error instanceof Error ? error.message : String(error)
+	return new CustomBlockInitError({
+		code: "unknown_error",
+		message,
+		isRetryable: false,
+	})
+}

package/src/react/useDataSource.ts

@@ -0,0 +1,47 @@
+import { useEffect } from "react"
+import { customBlockDataSources } from "../bridge/sandboxClient.js"
+import type { UseDataSourceOptions, UseDataSourceResult } from "../types.js"
+import { useCustomBlockHost } from "./useHostState.js"
+
+/**
+ * Reads from the data source mapped to the given semantic `key`.
+ *
+ * @param key - The semantic data-source key the block is wired to (e.g. `"people"`).
+ * @param options - Optional live snapshot options. `limit` defaults to 20 and
+ *   is capped at 999.
+ *
+ * @example
+ * const { items, isLoading, hasMore, error } = useDataSource("default", { limit: 25 })
+ */
+export function useDataSource(
+	key: string,
+	options?: UseDataSourceOptions,
+): UseDataSourceResult {
+	const host = useCustomBlockHost()
+	const limit = options?.limit
+	const matchingDataSource =
+		host.status === "initialized"
+			? host.dataSources.find(dataSource => dataSource.key === key)
+			: undefined
+
+	const isInitialized = host.status === "initialized"
+	useEffect(() => {
+		if (!isInitialized) {
+			return
+		}
+
+		customBlockDataSources.query(key, { limit })
+	}, [matchingDataSource, isInitialized, key, limit])
+
+	const view = customBlockDataSources.getView(host, key)
+
+	return {
+		items: view.items,
+		collectionSchema: view.collectionSchema,
+		propertySchemasById: view.propertySchemasById,
+		propertySchemasByKey: view.propertySchemasByKey,
+		isLoading: view.isLoading,
+		hasMore: view.hasMore,
+		error: view.error,
+	}
+}

package/src/react/useHostState.ts

@@ -0,0 +1,9 @@
+import { useSyncExternalStore } from "react"
+import { customBlockHost } from "../bridge/sandboxClient.js"
+
+export function useCustomBlockHost() {
+	return useSyncExternalStore(
+		customBlockHost.subscribe,
+		customBlockHost.getState,
+	)
+}

package/src/react/useRuntimeState.ts

@@ -0,0 +1,85 @@
+import { useSyncExternalStore } from "react"
+import type { NotionBlockId } from "../bridge/ids.js"
+import type { CustomBlockManifest } from "../bridge/manifest.js"
+import type { CustomBlockPage } from "../bridge/pages/page.js"
+import type { NotionParent } from "../bridge/parent.js"
+import type { NotionTheme } from "../bridge/theme.js"
+import type { NotionUser } from "../bridge/users/user.js"
+import { customBlock } from "../customBlock.js"
+
+/**
+ * Returns this custom block's ID. This is stable throughout the block's lifetime.
+ *
+ * Throws if called before `initCustomBlock` has resolved.
+ *
+ * @example
+ * const blockId = useBlockId()
+ */
+export function useBlockId(): NotionBlockId {
+	return useSyncExternalStore(customBlock.subscribe, customBlock.getBlockId)
+}
+
+/**
+ * Returns the block's parent in the document tree. Re-renders when the host sends
+ * a parent location update (e.g. the block moves into a different container).
+ *
+ * Throws if called before `initCustomBlock` has resolved.
+ *
+ * @example
+ * const parent = useParent()
+ */
+export function useParent(): NotionParent {
+	return useSyncExternalStore(customBlock.subscribe, customBlock.getParent)
+}
+
+/**
+ * Returns the nearest enclosing page ancestor. Re-renders when the host sends
+ * a page location update.
+ *
+ * Throws if called before `initCustomBlock` has resolved.
+ *
+ * @example
+ * const page = usePage()
+ */
+export function usePage(): CustomBlockPage {
+	return useSyncExternalStore(customBlock.subscribe, customBlock.getPage)
+}
+
+/**
+ * Returns the host's current theme. Re-renders on every `themeChanged` message from the host.
+ *
+ * Throws if called before `initCustomBlock` has resolved.
+ *
+ * @example
+ * const theme = useTheme()
+ */
+export function useTheme(): NotionTheme {
+	return useSyncExternalStore(customBlock.subscribe, customBlock.getTheme)
+}
+
+/**
+ * Returns the viewing user's Notion profile. Re-renders whenever the host sends a
+ * `currentUserChanged` message.
+ *
+ * Throws if called before `initCustomBlock` has resolved. `await` it before mounting.
+ *
+ * @example
+ * const me = useCurrentUser()
+ * console.log(me.id, me.name, me.person.email)
+ */
+export function useCurrentUser(): NotionUser {
+	return useSyncExternalStore(customBlock.subscribe, customBlock.getCurrentUser)
+}
+
+/**
+ * Returns the author-declared manifest loaded from `custom_blocks.json` — the semantic
+ * data-source keys plus their declared `name`, `description`, and property declarations.
+ * `null` when the block ships no manifest.
+ *
+ * This is the configuration the block declared, not host-resolved bindings: use
+ * `useDataSource(key)` for rows and resolved schema. Handy for enumerating the declared
+ * data-source keys (e.g. picking a default key, or rendering a key switcher).
+ */
+export function useManifest(): CustomBlockManifest | null {
+	return useSyncExternalStore(customBlock.subscribe, customBlock.getManifest)
+}

package/src/types.ts

@@ -0,0 +1,175 @@
+import type { NotionCollectionSchema } from "./bridge/dataSources/dataSource.js"
+import type {
+	NotionDataSourcePage,
+	NotionDataSourcePageUpdateInput,
+	NotionDataSourcePageUpdateResult,
+} from "./bridge/dataSources/dataSourcePage.js"
+import type { NotionPropertySchema } from "./bridge/dataSources/propertySchema.js"
+import type { CustomBlockErrorInfo } from "./bridge/errors.js"
+import type { NotionDataSourceId } from "./bridge/ids.js"
+import type { NotionCreatePagePosition } from "./bridge/messages/createPage.js"
+import type { CustomBlockCreatePageErrorInfo } from "./bridge/messages/createPageResult.js"
+import type { CustomBlockGetPageErrorInfo } from "./bridge/messages/getPage.js"
+import type { CustomBlockGetUserErrorInfo } from "./bridge/messages/getUser.js"
+import type { CustomBlockListUsersErrorInfo } from "./bridge/messages/listUsers.js"
+import type { CustomBlockQueryDataSourceErrorInfo } from "./bridge/messages/queryDataSourceResult.js"
+import type { CustomBlockUpdatePageErrorInfo } from "./bridge/messages/updatePageResult.js"
+import type {
+	NotionPage,
+	NotionPageCover,
+	NotionPageIcon,
+	NotionPageId,
+	NotionPagePropertyInputMap,
+	NotionPagePropertyWriteMap,
+} from "./bridge/pages/page.js"
+import type { NotionUser, NotionUserList } from "./bridge/users/user.js"
+
+export type { NotionDataSourceId, NotionSpaceId } from "./bridge/ids.js"
+export type { NotionPageId } from "./bridge/pages/page.js"
+export type {
+	NotionUser,
+	NotionUserId,
+	NotionUserList,
+} from "./bridge/users/user.js"
+export type {
+	CustomBlockCreatePageErrorInfo,
+	CustomBlockErrorInfo,
+	CustomBlockGetPageErrorInfo,
+	CustomBlockGetUserErrorInfo,
+	CustomBlockListUsersErrorInfo,
+	CustomBlockQueryDataSourceErrorInfo,
+	CustomBlockUpdatePageErrorInfo,
+	NotionDataSourcePageUpdateInput,
+	NotionDataSourcePageUpdateResult,
+}
+
+/**
+ * Return shape of `useDataSource`.
+ *
+ * - `items` — the rows the host has returned so far. Empty until the first response arrives.
+ * - `isLoading` — `true` while a query is in flight.
+ * - `hasMore` — `true` if the host indicated more rows are available beyond the current page.
+ * - `error` — structured error information if the most recent query failed.
+ */
+export type UseDataSourceResult = {
+	items: NotionDataSourcePage[]
+	/**
+	 * Collection/data-source schema for the bound Notion data source, including raw property
+	 * schemas. Undefined when the semantic data-source key has not been bound.
+	 */
+	collectionSchema?: NotionCollectionSchema
+	/**
+	 * Per-property schemas keyed by raw property ID, including the four synthetic built-ins
+	 * (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`).
+	 */
+	propertySchemasById: { [propertyId: string]: NotionPropertySchema }
+	/**
+	 * Per-property schemas keyed by user-defined keys from the data source's `propertyIdsByKey`.
+	 * Built-ins are NOT included here. Keys mapped to `undefined` indicate a declared-but-unbound
+	 * slot.
+	 */
+	propertySchemasByKey: { [key: string]: NotionPropertySchema | undefined }
+	isLoading: boolean
+	hasMore: boolean
+	error?: CustomBlockQueryDataSourceErrorInfo
+}
+
+export type UseDataSourceOptions = {
+	/**
+	 * Maximum number of rows to request from the host. Defaults to 20.
+	 */
+	limit?: number
+}
+
+/**
+ * Parent reference accepted by `sdk.pages.create`. Mirrors Notion's public `POST /v1/pages`
+ * parent shape; see https://developers.notion.com/reference/data-source.
+ *
+ * - `page_id`: Create a child page under the given Notion page.
+ * - `data_source_id`: Create a row inside the given Notion data source (aka the internal
+ *   collection). The public API's `data_source_id` is the same UUID as the `collectionPointer.id`
+ *   exposed in `dataSources`, so either value works here.
+ * - `data_source_key`: Create a row inside the data source that the custom block was configured with
+ *   under this semantic key. The SDK resolves the key to a `data_source_id` locally before
+ *   sending the request to the host.
+ */
+export type CreatePageParent =
+	| { type: "page_id"; page_id: NotionPageId }
+	| { type: "data_source_id"; data_source_id: NotionDataSourceId }
+	| { type: "data_source_key"; key: string }
+
+/**
+ * Input accepted by `sdk.pages.create`. Mirrors the Notion public API `POST /v1/pages` API.
+ */
+export type CreatePageInput = {
+	parent: CreatePageParent
+	properties: NotionPagePropertyInputMap
+	icon?: NotionPageIcon
+	cover?: NotionPageCover
+	position?: NotionCreatePagePosition
+}
+
+/**
+ * The result of a `sdk.pages.create` API call.
+ */
+export type CreatePageResult =
+	| {
+			status: "success"
+			/** The newly created page. */
+			page: NotionPage
+	  }
+	| { status: "error"; error: CustomBlockCreatePageErrorInfo }
+
+/**
+ * Input accepted by `sdk.pages.update`.
+ *
+ * `properties` is keyed by raw Notion property ID. To update a row with configured
+ * custom-block property keys, use the `update` helper on pages returned from
+ * `useDataSource`.
+ */
+export type UpdatePageInput = {
+	pageId: NotionPageId
+	properties?: NotionPagePropertyWriteMap
+	icon?: NotionPageIcon
+	cover?: NotionPageCover
+	archived?: boolean
+}
+
+/**
+ * Result of `sdk.pages.get`.
+ */
+export type GetPageResult =
+	| {
+			status: "success"
+			page: NotionPage
+	  }
+	| { status: "error"; error: CustomBlockGetPageErrorInfo }
+
+/**
+ * Result of `sdk.pages.update` / `sdk.pages.delete`.
+ */
+export type UpdatePageResult =
+	| {
+			status: "success"
+			page: NotionPage
+	  }
+	| { status: "error"; error: CustomBlockUpdatePageErrorInfo }
+
+export type ListUsersInput = {
+	startCursor?: string
+	pageSize?: number
+}
+
+export type ListUsersResult =
+	| {
+			status: "success"
+			list: NotionUserList
+	  }
+	| { status: "error"; error: CustomBlockListUsersErrorInfo }
+
+export type GetUserResult =
+	| {
+			status: "success"
+			user: NotionUser
+	  }
+	| { status: "error"; error: CustomBlockGetUserErrorInfo }

package/src/utils.ts

@@ -0,0 +1,13 @@
+/**
+ * Internal helpers shared across the SDK.
+ */
+
+/**
+ * Throws an error when an unexpected value is encountered. This is used to ensure all code paths
+ * are covered when using discriminated unions.
+ */
+export function unreachable(value: never): never {
+	throw new Error(
+		`[notion-custom-sdk] Unexpected value encountered: ${JSON.stringify(value)}`,
+	)
+}

package/src/version.ts

@@ -0,0 +1,8 @@
+/**
+ * Runtime SDK package version. Sent over the bridge for host-side analytics only. Business logic
+ * should compare against the bridge protocol version instead of this value.
+ *
+ * This checked-in value intentionally stays generic for local development. The SDK publish build
+ * overwrites the compiled runtime module with package.json's semver before publishing.
+ */
+export const NCBLOCK_SDK_VERSION: string = "0.0.0"