@notionhq/custom-blocks 0.1.0 → 0.1.2

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/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,3 +1,4 @@
+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"
@@ -14,6 +15,7 @@ import { unreachable } from "./utils.js"
  */
 export type CustomBlockInitPayload = {
 	theme: NotionTheme
+	contrastMode: NotionContrastMode
 	blockId: NotionBlockId
 	parent: NotionParent
 	page: CustomBlockPage
@@ -103,6 +105,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.