ncblock 0.0.4 → 0.0.6

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Public entrypoint for `ncblock`.
+ *
+ * Everything re-exported here is part of the SDK's public API. Anything not
+ * re-exported is internal and may change without notice. Consumers should
+ * import exclusively from `ncblock`, never from deeper paths,
+ * so internal files (e.g. `./bridge/*`) can be refactored without breaking
+ * downstream code.
+ */
+
+export type { NotionCustomBlockContext } from "./bridge/context"
+export type {
+	NotionCollectionSchema,
+	NotionDataSource,
+} from "./bridge/dataSources/dataSource"
+export type {
+	NotionDataSourcePage,
+	NotionDataSourcePageUpdateInput,
+	NotionDataSourcePageUpdateResult,
+} from "./bridge/dataSources/dataSourcePage"
+export type { NotionDataSourceValue } from "./bridge/dataSources/dataSourceValue"
+export type {
+	NotionDate,
+	NotionDateRange,
+	NotionDateReminder,
+	NotionDateTime,
+	NotionDateTimeRange,
+	NotionDateTimeReminder,
+	NotionDateValue,
+	NotionNoReminder,
+	NotionTimeReminder,
+} from "./bridge/dataSources/dateValue"
+export type {
+	NotionBuiltinPropertyId,
+	NotionDualProperty,
+	NotionPropertyColor,
+	NotionPropertyOption,
+	NotionPropertySchema,
+	NotionPropertyType,
+	NotionStatusGroup,
+} from "./bridge/dataSources/propertySchema"
+export {
+	NOTION_BUILTIN_PROPERTY_IDS,
+	NOTION_PROPERTY_TYPES,
+} from "./bridge/dataSources/propertySchema"
+export type { NotionRecordPointer } from "./bridge/dataSources/recordPointer"
+export type { NotionDataSourceId, NotionSpaceId } from "./bridge/ids"
+export type {
+	CustomBlockManifest,
+	ManifestDataSource,
+	ManifestIcon,
+	ManifestProperty,
+} from "./bridge/manifest"
+export type { NotionCreatePagePosition } from "./bridge/messages/createPage"
+export type {
+	NotionPage,
+	NotionPageCover,
+	NotionPageIcon,
+	NotionPageId,
+	NotionPageParent,
+	NotionPagePropertyInputMap,
+	NotionPagePropertyInputValue,
+	NotionPagePropertyValue,
+	NotionPagePropertyWriteMap,
+} from "./bridge/pages/page"
+export { pages } from "./bridge/sandboxClient"
+export type { NotionTheme } from "./bridge/theme"
+export {
+	type CustomBlockInitial,
+	type InitCustomBlockOptions,
+	initCustomBlock,
+	NotInIframeError,
+} from "./init"
+export {
+	NotionCustomBlock,
+	type NotionCustomBlockProps,
+	type UseCustomBlockInitResult,
+	useCustomBlockAutoResize,
+	useCustomBlockContext,
+	useCustomBlockInit,
+	useDataSource,
+	useDataSourceDefinitions,
+	useTheme,
+} from "./react"
+export * from "./types"
+export { users } from "./users"

package/src/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/src/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])
+}