ncblock 0.0.4 → 0.0.5

package/init.ts

@@ -0,0 +1,92 @@
+import type { NotionCustomBlockContext } from "./bridge/context"
+import type { NotionDataSource } from "./bridge/dataSources/dataSource"
+import { loadManifest } from "./bridge/loadManifest"
+import {
+	awaitCustomBlockInit,
+	getCustomBlockHostState,
+	sendCustomBlockReady,
+} from "./bridge/sandboxClient"
+import type { NotionTheme } from "./bridge/theme"
+
+/**
+ * The payload sent by the host in the `init` message in response to the sandbox's `ready` message.
+ */
+export type CustomBlockInitial = {
+	theme: NotionTheme
+	context: NotionCustomBlockContext
+	dataSources: NotionDataSource[]
+}
+
+/**
+ * Error thrown when the SDK is loaded in a top-level standalone window with no parent frame.
+ * `postMessage` would just hit the same window and the handshake can never complete.
+ * `<NotionCustomBlock>` catches this specifically and falls back to a standalone preview with a
+ * warning banner. Direct callers can `instanceof` it to apply their own policy.
+ */
+export class NotInIframeError extends Error {
+	constructor(message: string = NOT_IN_IFRAME_MESSAGE) {
+		super(message)
+		this.name = "NotInIframeError"
+	}
+}
+
+/**
+ * Options for {@link initCustomBlock}.
+ */
+export type InitCustomBlockOptions = {
+	/**
+	 * How long to wait for the host's `init` response before rejecting with an error.
+	 *
+	 * @default 2000 - Short enough that a misconfigured embed surfaces quickly, long enough to
+	 * absorb a real host's worst-case init latency.
+	 */
+	timeoutMs?: number
+}
+
+const DEFAULT_INIT_TIMEOUT_MS = 2000
+
+const NOT_IN_IFRAME_MESSAGE =
+	"<NotionCustomBlock> only works inside an iframe — use the dev shell or deploy to Notion."
+
+let initPromise: Promise<CustomBlockInitial> | undefined
+
+/**
+ * Performs the SDK <-> host handshake: loads `custom_blocks.json`, posts
+ * `ready`, then awaits the host's `init` message. Resolves with that payload.
+ *
+ * Rejects with a `TimeoutError` if the host doesn't respond inside `timeoutMs`.
+ *
+ * Idempotent: subsequent calls return the same promise as the first and ignore any new options.
+ * Mount your React tree (or call any SDK hook / `subscribeToCustomBlockHost`) only after the
+ * returned promise resolves.
+ */
+export function initCustomBlock(
+	opts: InitCustomBlockOptions = {},
+): Promise<CustomBlockInitial> {
+	initPromise ??= (async () => {
+		// Fail fast with a typed error when rendered as a standalone tab and not in a parent frame.
+		// Otherwise, it would eventually hit the timeout, since `postMessage` to `window.parent`
+		// would just hit the same window and never arrive.
+		if (typeof window !== "undefined" && window.parent === window) {
+			throw new NotInIframeError()
+		}
+
+		// Load the manifest and send it to the host.
+		const manifest = await loadManifest()
+
+		sendCustomBlockReady(manifest)
+
+		const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS
+		const message = await awaitCustomBlockInit(AbortSignal.timeout(timeoutMs))
+
+		const hostState = getCustomBlockHostState()
+
+		return {
+			theme: message.theme,
+			context: message.context as NotionCustomBlockContext,
+			dataSources:
+				hostState.status === "initialized" ? hostState.dataSources : [],
+		}
+	})()
+	return initPromise
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ncblock",
-	"version": "0.0.4",
+	"version": "0.0.5",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -15,16 +15,26 @@
 			"types": "./dist/./host.d.ts"
 		},
 		"./vite": {
-			"import": "./dist/./vite-plugin/index.js",
-			"types": "./dist/./vite-plugin/index.d.d.ts"
+			"import": "./vite-plugin/index.js",
+			"types": "./vite-plugin/index.d.ts"
 		}
 	},
 	"scripts": {
 		"test": "vitest run --environment jsdom"
 	},
 	"files": [
-		"dist",
-		"README.md"
+		"index.ts",
+		"host.ts",
+		"HOST.md",
+		"docs",
+		"react.tsx",
+		"init.ts",
+		"users.ts",
+		"types.ts",
+		"utils.ts",
+		"vite-plugin",
+		"bridge",
+		"dist"
 	],
 	"peerDependencies": {
 		"react": "^19.2.5"

package/react.tsx

@@ -0,0 +1,418 @@
+import {
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useState,
+	useSyncExternalStore,
+} from "react"
+import type { NotionCustomBlockContext } from "./bridge/context"
+import type { NotionDataSource } from "./bridge/dataSources/dataSource"
+import type { CustomBlockHostState } from "./bridge/hostState"
+import {
+	getCustomBlockHostState,
+	getDataSourceQueryView,
+	postCustomBlockResize,
+	queryCustomBlockDataSource,
+	setMockCustomBlockState,
+	subscribeToCustomBlockHost,
+} from "./bridge/sandboxClient"
+import type { NotionTheme } from "./bridge/theme"
+import {
+	type CustomBlockInitial,
+	type InitCustomBlockOptions,
+	initCustomBlock,
+	NotInIframeError,
+} from "./init"
+import type { UseDataSourceResult } from "./types"
+
+const DEFAULT_DATA_SOURCE_QUERY_LIMIT = 20
+
+function useCustomBlockHost() {
+	return useSyncExternalStore(
+		subscribeToCustomBlockHost,
+		getCustomBlockHostState,
+	)
+}
+
+function assertInitialized(
+	host: CustomBlockHostState,
+	hookName: string,
+): asserts host is Extract<CustomBlockHostState, { status: "initialized" }> {
+	if (host.status !== "initialized") {
+		throw new Error(
+			`${hookName} called before \`initCustomBlock\` resolved. Await it before mounting your tree.`,
+		)
+	}
+}
+
+/**
+ * Discriminated state returned by {@link useCustomBlockInit}.
+ *
+ * Branch on `isLoaded`/`error`:
+ * - `{ isLoaded: false, error: undefined }` — handshake in progress.
+ * - `{ isLoaded: false, error: Error }` — handshake failed (most commonly a
+ *   `TimeoutError` because the host never sent `init`).
+ * - `{ isLoaded: true, initial }` — handshake complete; safe to render
+ *   children that call `useTheme`, `useCustomBlockContext`, etc.
+ */
+export type UseCustomBlockInitResult =
+	| { isLoaded: false; error: undefined }
+	| { isLoaded: false; error: Error }
+	| { 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: err instanceof Error ? err : new Error(String(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
+}
+
+/**
+ * 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 small inline `<p role="alert">` is
+	 * rendered with the error message — 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()
+
+	useEffect(() => {
+		if (!isStandalone) {
+			return
+		}
+		console.warn(`[notion-custom-sdk] ${init.error?.message}`)
+		setMockCustomBlockState({
+			type: "init",
+			theme: "light",
+			context: {
+				customBlockId: "",
+				parent: { id: "", type: "" },
+				page: { id: "" },
+			},
+			dataSources: { bindings: {} },
+		})
+	}, [isStandalone, init.error])
+
+	if (init.error && !isStandalone) {
+		if (errorFallback === undefined) {
+			return (
+				<p role="alert">Notion custom view init failed: {init.error.message}</p>
+			)
+		}
+		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" style={STANDALONE_BANNER_STYLE}>
+					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}</>
+}
+
+const STANDALONE_BANNER_STYLE = {
+	padding: "8px 12px",
+	background: "#fff8e1",
+	color: "#5d4200",
+	borderBottom: "1px solid #f0d77b",
+	fontSize: 13,
+	fontFamily: "system-ui, sans-serif",
+	lineHeight: 1.4,
+} as const
+
+/**
+ * Returns the block's location in the document tree. Re-renders when the host sends
+ * `contextChanged` (e.g. the block moves into a different container or its enclosing
+ * page changes).
+ *
+ * Throws if called before `initCustomBlock` has resolved — `await` it before mounting.
+ *
+ * @example
+ * const ctx = useCustomBlockContext()
+ * console.log(ctx.customBlockId, ctx.parent.type)
+ */
+export function useCustomBlockContext(): NotionCustomBlockContext {
+	const host = useCustomBlockHost()
+	assertInitialized(host, "useCustomBlockContext")
+	return host.context
+}
+
+/**
+ * Returns the host's current theme. Re-renders on every `themeChanged` message from the host.
+ *
+ * Throws if called before `initCustomBlock` has resolved — `await` it before mounting.
+ *
+ * @example
+ * const theme = useTheme()
+ */
+export function useTheme(): NotionTheme {
+	const host = useCustomBlockHost()
+	assertInitialized(host, "useTheme")
+	return host.theme
+}
+
+/**
+ * Returns the raw data-source definitions — semantic keys plus optional `collectionPointer`,
+ * `collectionSchema`, `propertyIdsByKey`, and derived `propertySchemasById`. Most templates should use
+ * `useDataSource(key)` instead — this hook is for views that render the configuration
+ * itself (debug panels, schema-driven UIs).
+ *
+ * Throws if called before `initCustomBlock` has resolved.
+ */
+export function useDataSourceDefinitions(): NotionDataSource[] {
+	const host = useCustomBlockHost()
+	assertInitialized(host, "useDataSourceDefinitions")
+	return host.dataSources
+}
+
+/**
+ * Reads from the data source mapped to the given semantic `key`.
+ *
+ * The first render kicks off a query for the first `initialLimit` items. Calling
+ * `fetchMore()` re-requests a larger prefix (the bridge does not expose cursors yet);
+ * page growth tracks `initialLimit`. The hook automatically resets to `initialLimit`
+ * when the underlying data source definition changes.
+ *
+ * @param key - The semantic data-source key the block is wired to (e.g. `"people"`).
+ * @param initialLimit - Page size for the first query, and the increment used by
+ *   `fetchMore`. Defaults to 20.
+ *
+ * @example
+ * const { items, isLoading, hasMore, fetchMore, error } = useDataSource("default")
+ */
+export function useDataSource(
+	key: string,
+	initialLimit: number = DEFAULT_DATA_SOURCE_QUERY_LIMIT,
+): UseDataSourceResult {
+	const host = useCustomBlockHost()
+	const [limit, setLimit] = useState(initialLimit)
+	const matchingDataSource =
+		host.status === "initialized"
+			? host.dataSources.find(dataSource => dataSource.key === key)
+			: undefined
+	// Serialize to avoid re-querying when `dataSourcesChanged` rebuilds the array with equal entries.
+	const matchingSignature = matchingDataSource
+		? JSON.stringify(matchingDataSource)
+		: null
+
+	useEffect(() => {
+		// A new key or source definition means we should restart from the initial page size.
+		setLimit(initialLimit)
+	}, [matchingSignature, key, initialLimit])
+
+	const isInitialized = host.status === "initialized"
+	useEffect(() => {
+		if (!isInitialized) {
+			return
+		}
+
+		queryCustomBlockDataSource(key, limit)
+	}, [matchingSignature, isInitialized, key, limit])
+
+	const view = getDataSourceQueryView(host, key)
+	const fetchMore = useCallback(() => {
+		if (!view.hasMore || view.isLoading) {
+			return
+		}
+
+		// The bridge does not expose cursors yet, so "fetch more" means re-requesting a
+		// larger prefix of items and letting the host return the expanded result set.
+		// Page growth tracks the caller-provided `initialLimit` so templates can opt
+		// into larger batches.
+		setLimit(currentLimit => currentLimit + initialLimit)
+	}, [view.hasMore, view.isLoading, initialLimit])
+
+	return {
+		items: view.items,
+		collectionSchema: view.collectionSchema,
+		propertySchemasById: view.propertySchemasById,
+		propertySchemasByKey: view.propertySchemasByKey,
+		isLoading: view.isLoading,
+		hasMore: view.hasMore,
+		fetchMore,
+		error: view.error,
+	}
+}
+
+/**
+ * Measures the sandbox's `#root` element and posts `resize` messages so the host iframe
+ * matches the block's content height. Uses `Math.ceil(scrollHeight)` and dedupes
+ * unchanged values.
+ *
+ * `<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.
+ *
+ * @param args.enabled - When `false`, suspends measurement. Useful for conditional
+ *   measurement (e.g. while a debug toggle is off). Defaults to `true`.
+ *
+ * @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")
+		if (!(target instanceof HTMLElement)) {
+			return
+		}
+
+		let lastHeight = -1
+		const post = () => {
+			const next = Math.ceil(target.scrollHeight)
+			if (next === lastHeight) {
+				return
+			}
+			lastHeight = next
+			postCustomBlockResize(next)
+		}
+
+		post()
+
+		if (typeof ResizeObserver === "undefined") {
+			return
+		}
+		const observer = new ResizeObserver(post)
+		observer.observe(target)
+		return () => {
+			observer.disconnect()
+		}
+	}, [enabled])
+}

package/types.ts

@@ -0,0 +1,157 @@
+import type { NotionCollectionSchema } from "./bridge/dataSources/dataSource"
+import type {
+	NotionDataSourcePage,
+	NotionDataSourcePageUpdateInput,
+	NotionDataSourcePageUpdateResult,
+} from "./bridge/dataSources/dataSourcePage"
+import type { NotionPropertySchema } from "./bridge/dataSources/propertySchema"
+import type { NotionDataSourceId } from "./bridge/ids"
+import type { NotionCreatePagePosition } from "./bridge/messages/createPage"
+import type {
+	NotionPage,
+	NotionPageCover,
+	NotionPageIcon,
+	NotionPageId,
+	NotionPagePropertyInputMap,
+	NotionPagePropertyWriteMap,
+} from "./bridge/pages/page"
+import type { NotionUser, NotionUserList } from "./bridge/users/user"
+
+export type { NotionDataSourceId, NotionSpaceId } from "./bridge/ids"
+export type { NotionPageId } from "./bridge/pages/page"
+export type {
+	NotionUser,
+	NotionUserId,
+	NotionUserList,
+} from "./bridge/users/user"
+export type {
+	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.
+ * - `fetchMore` — re-requests a larger prefix of items (no-op while loading or when
+ *   `hasMore` is `false`). The page grows by `initialLimit` per call.
+ * - `error` — a human-readable error string 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
+	fetchMore: () => void
+	error?: string
+}
+
+/**
+ * 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: string }
+
+/**
+ * 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: string }
+
+/**
+ * Result of `sdk.pages.update` / `sdk.pages.delete`.
+ */
+export type UpdatePageResult =
+	| {
+			status: "success"
+			page: NotionPage
+	  }
+	| { status: "error"; error: string }
+
+export type ListUsersInput = {
+	startCursor?: string
+	pageSize?: number
+}
+
+export type ListUsersResult =
+	| {
+			status: "success"
+			list: NotionUserList
+	  }
+	| { status: "error"; error: string }
+
+export type GetUserResult =
+	| {
+			status: "success"
+			user: NotionUser
+	  }
+	| { status: "error"; error: string }