@notionhq/custom-blocks 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {
@@ -18,6 +18,7 @@
 			"import": "./dist/index.js",
 			"types": "./dist/index.d.ts"
 		},
+		"./nds.css": "./dist/styles/nds.css",
 		"./react": {
 			"import": "./dist/react/index.js",
 			"types": "./dist/react/index.d.ts"

package/src/bridge/SandboxBridge.ts

@@ -14,6 +14,7 @@ import type {
 } from "../types.js"
 import { unreachable } from "../utils.js"
 import { CUSTOM_BLOCKS_SDK_VERSION } from "../version.js"
+import { DEFAULT_CONTRAST_MODE } from "./contrast.js"
 import type {
 	NotionDataSource,
 	NotionDataSourceBindings,
@@ -79,6 +80,7 @@ export class SandboxBridge {
 	private hostState: CustomBlockHostState = {
 		status: "uninitialized",
 		theme: "light",
+		contrastMode: DEFAULT_CONTRAST_MODE,
 	}
 	private listeners = new Set<() => void>()
 	private messageLog: MessageLogEntry[] = []
@@ -301,6 +303,15 @@ export class SandboxBridge {
 				return
 			}
 
+			case "contrastModeChanged": {
+				this.hostState = {
+					...hostState,
+					contrastMode: message.contrastMode,
+				}
+				this.notify()
+				return
+			}
+
 			case "parentChanged": {
 				this.hostState = {
 					...hostState,
@@ -538,6 +549,7 @@ export class SandboxBridge {
 		this.hostState = {
 			status: "initialized",
 			theme: message.theme,
+			contrastMode: message.contrastMode,
 			blockId,
 			parent,
 			page,

package/src/bridge/contrast.ts

@@ -0,0 +1,6 @@
+import * as v from "valibot"
+
+export const notionContrastModeSchema = v.picklist(["standard", "high"])
+export type NotionContrastMode = v.InferOutput<typeof notionContrastModeSchema>
+
+export const DEFAULT_CONTRAST_MODE: NotionContrastMode = "standard"

package/src/bridge/hostState.ts

@@ -1,3 +1,4 @@
+import type { NotionContrastMode } from "./contrast.js"
 import type { NotionDataSource } from "./dataSources/dataSource.js"
 import type {
 	NotionDataSourcePage,
@@ -20,11 +21,13 @@ export type CustomBlockHostState = UninitializedHostState | InitializedHostState
 export type UninitializedHostState = {
 	status: "uninitialized"
 	theme: NotionTheme
+	contrastMode: NotionContrastMode
 }
 
 export type InitializedHostState = {
 	status: "initialized"
 	theme: NotionTheme
+	contrastMode: NotionContrastMode
 	blockId: NotionBlockId
 	parent: NotionParent
 	page: CustomBlockPage

package/src/bridge/loadManifest.ts

@@ -4,13 +4,12 @@ import { type CustomBlockManifest, manifestSchema } from "./manifest.js"
 
 const MANIFEST_URL = "custom_blocks.json"
 
-export type CustomBlockConnectErrorCode =
+type CustomBlockConnectErrorCode =
 	| "manifest_unavailable"
 	| "manifest_invalid"
 	| (string & {})
 
-export type CustomBlockConnectError =
-	CustomBlockErrorInfo<CustomBlockConnectErrorCode>
+type CustomBlockConnectError = CustomBlockErrorInfo<CustomBlockConnectErrorCode>
 
 export type ManifestLoadResult =
 	| {
@@ -23,21 +22,13 @@ export type ManifestLoadResult =
 	  }
 
 /**
- * Attempts to load a `custom_blocks.json` manifest co-located with the bundle.
- * A missing manifest means the block has no declared data requirements.
- * Other failures return a structured error so the host can reject the manifest.
- * The SDK validates the manifest locally for author feedback; the host still
- * validates the connect message as the iframe trust boundary.
+ * Attempts to load the custom block's optional self-hosted manifest, co-located with the bundle at
+ * `/custom_blocks.json`. This is to support local development where the block is served from a
+ * local dev server.
+ *
+ * It is up to the host to decide whether to use this manifest or provide its own persisted manifest.
  */
-export async function loadManifest(): Promise<ManifestLoadResult> {
-	if (typeof fetch !== "function") {
-		const message = `No fetch API available; cannot load ${MANIFEST_URL}.`
-		console.warn(`[custom-blocks-sdk] ${message}`)
-		return {
-			manifest: null,
-			error: { code: "manifest_unavailable", message, isRetryable: true },
-		}
-	}
+export async function attemptToLoadSelfHostedManifest(): Promise<ManifestLoadResult> {
 	let response: Response
 	try {
 		response = await fetch(MANIFEST_URL, { credentials: "omit" })

package/src/bridge/manifest.ts

@@ -1,15 +1,6 @@
 import * as v from "valibot"
 import { notionPropertyTypeSchema } from "./dataSources/propertySchema.js"
 
-/**
- * User-authored manifest declaring the data sources the custom block expects.
- * Lives at `custom_blocks.json` in the project root. The sandbox may send it in
- * `connect`, and the host returns the authoritative manifest in `init`. The
- * `notionCustomBlock` Vite plugin from
- * `@notionhq/custom-blocks/vite` wires the JSON file into the dev server and
- * the build output.
- */
-
 /**
  * Decorative icon attached to a manifest data source. Mirrors the
  * `emoji` / `external` icon variants the public Notion API uses, so the host
@@ -50,4 +41,7 @@ export const manifestSchema = v.object({
 	dataSources: v.record(v.string(), manifestDataSourceSchema),
 })
 
+/**
+ * Manifest declaring the data sources required by a custom block.
+ */
 export type CustomBlockManifest = v.InferOutput<typeof manifestSchema>

package/src/bridge/messages/contrastModeChanged.ts

@@ -0,0 +1,12 @@
+import * as v from "valibot"
+import { notionContrastModeSchema } from "../contrast.js"
+
+/** Message sent by the host when contrast changes after initialization. */
+export const contrastModeChangedMessageSchema = v.object({
+	type: v.literal("contrastModeChanged"),
+	contrastMode: notionContrastModeSchema,
+})
+
+export type ContrastModeChangedMessage = v.InferOutput<
+	typeof contrastModeChangedMessageSchema
+>

package/src/bridge/messages/hostToSandbox.ts

@@ -1,4 +1,5 @@
 import * as v from "valibot"
+import { contrastModeChangedMessageSchema } from "./contrastModeChanged.js"
 import { createPageResultMessageSchema } from "./createPageResult.js"
 import { currentUserChangedMessageSchema } from "./currentUserChanged.js"
 import { dataSourcesChangedMessageSchema } from "./dataSourcesChanged.js"
@@ -19,6 +20,7 @@ import { updatePageResultMessageSchema } from "./updatePageResult.js"
 export const hostToSandboxMessageSchema = v.variant("type", [
 	initMessageSchema,
 	themeChangedMessageSchema,
+	contrastModeChangedMessageSchema,
 	parentChangedMessageSchema,
 	pageChangedMessageSchema,
 	currentUserChangedMessageSchema,

package/src/bridge/messages/init.ts

@@ -1,4 +1,5 @@
 import * as v from "valibot"
+import { DEFAULT_CONTRAST_MODE, notionContrastModeSchema } from "../contrast.js"
 import { notionDataSourceBindingsSchema } from "../dataSources/dataSource.js"
 import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 import { notionBlockIdSchema } from "../ids.js"
@@ -66,7 +67,9 @@ export class CustomBlockInitializationError
 /**
  * Initialization message sent by the host to the sandbox exactly once, in response to the
  * sandbox's `connect` message. The sandbox echoes `initializationId` in `initResult`. After
- * successful initialization, live updates flow through narrower messages.
+ * successful initialization, live updates flow through narrower messages
+ * (`themeChanged`, `contrastModeChanged`, `parentChanged`, `pageChanged`,
+ * `dataSourcesChanged`).
  */
 export const initMessageSchema = v.variant("status", [
 	v.object({
@@ -74,6 +77,8 @@ export const initMessageSchema = v.variant("status", [
 		initializationId: v.string(),
 		status: v.literal("success"),
 		theme: notionThemeSchema,
+		// TODO(custom-blocks): Make this required when next bumping the protocol version.
+		contrastMode: v.optional(notionContrastModeSchema, DEFAULT_CONTRAST_MODE),
 		blockId: notionBlockIdSchema,
 		parent: notionParentSchema,
 		page: customBlockPageSchema,

package/src/customBlock.ts

@@ -1,4 +1,5 @@
 import { autoResize } from "./autoResize.js"
+import type { NotionContrastMode } from "./bridge/contrast.js"
 import type { NotionDataSource } from "./bridge/dataSources/dataSource.js"
 import type {
 	CustomBlockHostState,
@@ -13,10 +14,15 @@ import type { NotionTheme } from "./bridge/theme.js"
 import type { NotionUser } from "./bridge/users/user.js"
 
 export type CustomBlockState =
-	| { status: "uninitialized"; theme: NotionTheme }
+	| {
+			status: "uninitialized"
+			theme: NotionTheme
+			contrastMode: NotionContrastMode
+	  }
 	| {
 			status: "initialized"
 			theme: NotionTheme
+			contrastMode: NotionContrastMode
 			blockId: NotionBlockId
 			parent: NotionParent
 			page: CustomBlockPage
@@ -45,6 +51,10 @@ export const customBlock = {
 		return getInitializedHostState("getTheme").theme
 	},
 
+	getContrastMode(): NotionContrastMode {
+		return getInitializedHostState("getContrastMode").contrastMode
+	},
+
 	getBlockId(): NotionBlockId {
 		return getInitializedHostState("getBlockId").blockId
 	},
@@ -76,12 +86,14 @@ function toPublicState(hostState: CustomBlockHostState): CustomBlockState {
 		lastPublicState = {
 			status: "uninitialized",
 			theme: hostState.theme,
+			contrastMode: hostState.contrastMode,
 		}
 		return lastPublicState
 	}
 	lastPublicState = {
 		status: "initialized",
 		theme: hostState.theme,
+		contrastMode: hostState.contrastMode,
 		blockId: hostState.blockId,
 		parent: hostState.parent,
 		page: hostState.page,

package/src/host/createCustomBlockHost.ts

@@ -1,7 +1,12 @@
 import * as v from "valibot"
+import {
+	DEFAULT_CONTRAST_MODE,
+	type NotionContrastMode,
+} from "../bridge/contrast.js"
 import type { NotionDataSourceId } from "../bridge/ids.js"
 import type { CustomBlockManifest } from "../bridge/manifest.js"
 import type { ConnectMessage } from "../bridge/messages/connect.js"
+import type { ContrastModeChangedMessage } from "../bridge/messages/contrastModeChanged.js"
 import type { CreatePageMessage } from "../bridge/messages/createPage.js"
 import type { CreatePageResultMessage } from "../bridge/messages/createPageResult.js"
 import type { DataSourcesChangedMessage } from "../bridge/messages/dataSourcesChanged.js"
@@ -71,6 +76,7 @@ export type CustomBlockHostHandle = {
 	stop: () => void
 	post: (message: HostToSandboxMessage) => void
 	setTheme: (theme: NotionTheme) => void
+	setContrastMode: (contrastMode: NotionContrastMode) => void
 	setParent: (parent: NotionParent) => void
 	setPage: (page: CustomBlockPage) => void
 	setDataSources: (dataSources: CustomBlockHostDataSourcesPayload) => void
@@ -108,6 +114,7 @@ export function createCustomBlockHost(
 	)
 
 	let theme = initialState.theme
+	let contrastMode = initialState.contrastMode ?? DEFAULT_CONTRAST_MODE
 	let parent = initialState.parent
 	let page = initialState.page
 	let dataSources = initialState.dataSources
@@ -119,6 +126,7 @@ export function createCustomBlockHost(
 	let activeInitializationId: string | undefined
 	let connectedSandbox: ConnectSuccessMessage | undefined
 	let pendingThemeChange = false
+	let pendingContrastModeChange = false
 	let pendingParentChange = false
 	let pendingPageChange = false
 	let pendingDataSourcesChange: CustomBlockHostDataSourcesPayload | undefined
@@ -201,6 +209,7 @@ export function createCustomBlockHost(
 			initializationId: connect.initializationId,
 			status: "success",
 			theme,
+			contrastMode,
 			blockId: initialState.blockId,
 			parent,
 			page,
@@ -376,6 +385,10 @@ export function createCustomBlockHost(
 			pendingThemeChange = false
 			post({ type: "themeChanged", theme })
 		}
+		if (pendingContrastModeChange) {
+			pendingContrastModeChange = false
+			post({ type: "contrastModeChanged", contrastMode })
+		}
 		if (pendingParentChange) {
 			pendingParentChange = false
 			post({ type: "parentChanged", parent })
@@ -527,6 +540,20 @@ export function createCustomBlockHost(
 			const message: ThemeChangedMessage = { type: "themeChanged", theme }
 			post(message)
 		},
+		setContrastMode(nextContrastMode) {
+			contrastMode = nextContrastMode
+			if (initStatus !== "success") {
+				if (initStatus === "waitingForInitResult") {
+					pendingContrastModeChange = true
+				}
+				return
+			}
+			const message: ContrastModeChangedMessage = {
+				type: "contrastModeChanged",
+				contrastMode,
+			}
+			post(message)
+		},
 		setParent(nextParent) {
 			parent = nextParent
 			if (initStatus !== "success") {

package/src/host/lifecycle/types.ts

@@ -1,3 +1,4 @@
+import type { NotionContrastMode } from "../../bridge/contrast.js"
 import type { NotionDataSourceBindings } from "../../bridge/dataSources/dataSource.js"
 import type { NotionBlockId } from "../../bridge/ids.js"
 import type { CustomBlockManifest } from "../../bridge/manifest.js"
@@ -28,6 +29,8 @@ export type CustomBlockHostInitialDataSources =
 
 export type CustomBlockHostInitialState = {
 	theme: NotionTheme
+	// TODO(custom-blocks): Make this required when next bumping the protocol version.
+	contrastMode?: NotionContrastMode
 	blockId: NotionBlockId
 	parent: NotionParent
 	page: CustomBlockPage

package/src/host.ts

@@ -10,6 +10,8 @@
  * surface lives in the default `@notionhq/custom-blocks` entrypoint.
  */
 
+export type { NotionContrastMode } from "./bridge/contrast.js"
+export { notionContrastModeSchema } from "./bridge/contrast.js"
 export type {
 	NotionDataSourceBinding,
 	NotionDataSourceBindings,
@@ -40,6 +42,8 @@ export {
 export { readIncomingType } from "./bridge/incomingType.js"
 export type { ConnectMessage } from "./bridge/messages/connect.js"
 export { connectMessageSchema } from "./bridge/messages/connect.js"
+export type { ContrastModeChangedMessage } from "./bridge/messages/contrastModeChanged.js"
+export { contrastModeChangedMessageSchema } from "./bridge/messages/contrastModeChanged.js"
 export type { CreatePageMessage } from "./bridge/messages/createPage.js"
 export { createPageMessageSchema } from "./bridge/messages/createPage.js"
 export type {

package/src/index.ts

@@ -7,6 +7,7 @@
  * should import hooks and components from `@notionhq/custom-blocks/react`.
  */
 
+export type { NotionContrastMode } from "./bridge/contrast.js"
 export type {
 	NotionCollectionSchema,
 	NotionDataSource,

package/src/init.ts

@@ -1,6 +1,7 @@
+import type { NotionContrastMode } from "./bridge/contrast.js"
 import type { NotionDataSource } from "./bridge/dataSources/dataSource.js"
 import type { NotionBlockId } from "./bridge/ids.js"
-import { loadManifest } from "./bridge/loadManifest.js"
+import { attemptToLoadSelfHostedManifest } from "./bridge/loadManifest.js"
 import { CustomBlockInitializationError } from "./bridge/messages/init.js"
 import type { CustomBlockPage } from "./bridge/pages/page.js"
 import type { NotionParent } from "./bridge/parent.js"
@@ -14,6 +15,7 @@ import { unreachable } from "./utils.js"
  */
 export type CustomBlockInitPayload = {
 	theme: NotionTheme
+	contrastMode: NotionContrastMode
 	blockId: NotionBlockId
 	parent: NotionParent
 	page: CustomBlockPage
@@ -61,26 +63,35 @@ const NOT_IN_IFRAME_MESSAGE =
 let initPromise: Promise<CustomBlockInitPayload> | undefined
 
 /**
- * Performs the SDK <-> host handshake: loads `custom_blocks.json`, posts
- * `connect`, then awaits the host's `init` message. Resolves after the sandbox
- * applies the payload and returns `initResult.success`.
+ * Initializes the custom block by running the SDK <-> host handshake.
  *
- * Rejects with a `CustomBlockInitializationError` if initialization fails.
+ * Resolves with the block's initial context (theme, block location, current
+ * user, data sources) once the host has initialized the block. Rejects with a
+ * `CustomBlockInitializationError` if initialization fails.
  *
  * Idempotent: subsequent calls return the same promise as the first and ignore any new options.
- * Mount your React tree (or call any SDK hook / `customBlock.subscribe`) only after the
- * returned promise resolves.
+ * Mount your React tree (or call any SDK hook) only after the returned promise resolves.
  */
 export function initCustomBlock(
 	opts: InitCustomBlockOptions = {},
 ): Promise<CustomBlockInitPayload> {
 	if (initPromise === undefined) {
-		initPromise = initializeCustomBlock(opts)
+		initPromise = performHandshake(opts)
 	}
 	return initPromise
 }
 
-async function initializeCustomBlock(
+/**
+ * Performs the host <-> sandbox SDK handshake:
+ * 1. Attempts to load an optional self-hosted `custom_blocks.json`
+ * 2. Sends `connect` with the manifest
+ * 3. Awaits the host's `init` message
+ * 4. Applies the `init` payload and acknowledges with `initResult` (fire-and-forget)
+ *
+ * Resolves with the `init` payload after the process above. Rejects with a
+ * `CustomBlockInitializationError` if any step fails.
+ */
+async function performHandshake(
 	opts: InitCustomBlockOptions,
 ): Promise<CustomBlockInitPayload> {
 	try {
@@ -92,7 +103,7 @@ async function initializeCustomBlock(
 		}
 
 		// Load the manifest and send it to the host.
-		const manifestResult = await loadManifest()
+		const manifestResult = await attemptToLoadSelfHostedManifest()
 		customBlockHost.sendConnect(manifestResult)
 
 		const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS
@@ -103,6 +114,7 @@ async function initializeCustomBlock(
 			case "initialized":
 				return {
 					theme: hostState.theme,
+					contrastMode: hostState.contrastMode,
 					blockId: hostState.blockId,
 					parent: hostState.parent,
 					page: hostState.page,

package/src/react/NotionTokenScope.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react"
+import { useContrastMode, useTheme } from "./useRuntimeState.js"
+
+export type NotionTokenScopeProps = {
+	children: ReactNode
+}
+
+/**
+ * Makes Notion design tokens available to descendants and keeps their
+ * host-controlled appearance in sync.
+ */
+export function NotionTokenScope({ children }: NotionTokenScopeProps) {
+	const theme = useTheme()
+	const contrastMode = useContrastMode()
+
+	return (
+		<div
+			className="nds"
+			data-display-mode={theme}
+			data-contrast-mode={contrastMode}
+		>
+			{children}
+		</div>
+	)
+}

package/src/react/index.ts

@@ -11,6 +11,10 @@ export {
 	NotionCustomBlock,
 	type NotionCustomBlockProps,
 } from "./NotionCustomBlock.js"
+export {
+	NotionTokenScope,
+	type NotionTokenScopeProps,
+} from "./NotionTokenScope.js"
 export { useCustomBlockAutoResize } from "./useCustomBlockAutoResize.js"
 export {
 	type UseCustomBlockInitResult,
@@ -19,6 +23,7 @@ export {
 export { useDataSource } from "./useDataSource.js"
 export {
 	useBlockId,
+	useContrastMode,
 	useCurrentUser,
 	useManifest,
 	usePage,

package/src/react/standalonePreview.ts

@@ -1,4 +1,5 @@
 import * as v from "valibot"
+import { DEFAULT_CONTRAST_MODE } from "../bridge/contrast.js"
 import { notionBlockIdSchema, notionPageIdSchema } from "../bridge/ids.js"
 import { customBlockHost } from "../bridge/sandboxClient.js"
 
@@ -11,6 +12,7 @@ export function seedStandalonePreviewState() {
 		initializationId: "standalone-preview",
 		status: "success",
 		theme: "light",
+		contrastMode: DEFAULT_CONTRAST_MODE,
 		blockId: previewBlockId,
 		parent: { type: "page_id", page_id: previewPageId },
 		page: { id: previewPageId, parent: { type: "workspace", workspace: true } },

package/src/react/useRuntimeState.ts

@@ -1,4 +1,5 @@
 import { useSyncExternalStore } from "react"
+import type { NotionContrastMode } from "../bridge/contrast.js"
 import type { NotionBlockId } from "../bridge/ids.js"
 import type { CustomBlockManifest } from "../bridge/manifest.js"
 import type { CustomBlockPage } from "../bridge/pages/page.js"
@@ -57,6 +58,22 @@ export function useTheme(): NotionTheme {
 	return useSyncExternalStore(customBlock.subscribe, customBlock.getTheme)
 }
 
+/**
+ * Returns the host's contrast preference. Re-renders on every protocol-v3
+ * `contrastModeChanged` message from the host.
+ *
+ * Throws if called before `initCustomBlock` has resolved.
+ *
+ * @example
+ * const contrastMode = useContrastMode()
+ */
+export function useContrastMode(): NotionContrastMode {
+	return useSyncExternalStore(
+		customBlock.subscribe,
+		customBlock.getContrastMode,
+	)
+}
+
 /**
  * Returns the viewing user's Notion profile. Re-renders whenever the host sends a
  * `currentUserChanged` message.