@notionhq/custom-blocks 0.1.41 → 0.1.42

package/README.md

@@ -5,7 +5,12 @@
 
 SDK for building Notion custom blocks.
 
-A custom block runs as a sandboxed `<iframe>` inside the Notion app that has no direct access to the internet. The only channel between your block and Notion is a local `postMessage` bridge. This library implements the sandbox side of the bridge protocol and wraps it in a framework-neutral TypeScript API (`@notionhq/custom-blocks`) and typed React hooks (`@notionhq/custom-blocks/react`).
+A custom block runs in a sandboxed `<iframe>` inside Notion. It has no direct
+access to the internet. A local `postMessage` bridge connects the block to
+Notion.
+
+This package provides the sandbox side of the bridge. It exports a
+framework-neutral TypeScript API and typed React hooks.
 
 ## Bundle tooling
 
@@ -14,17 +19,18 @@ Node build tools can import `build` and `upload` from
 
 ## Install
 
-Create a worker project with `ntn workers new --template custom` and use the dependencies and
-entrypoint it generates. In this repository, fixtures depend on the SDK through
-the workspace. React is optional unless the block imports
-`@notionhq/custom-blocks/react`. React blocks need `react` and `react-dom`.
+Create a worker project with `ntn workers new --template custom`. Use the
+dependencies and entrypoint that the Notion CLI generates.
+
+React is optional. Blocks that import `@notionhq/custom-blocks/react` need
+`react` and `react-dom`. This repository's fixtures use the workspace SDK.
 
-For local preview, run `ntn customblocks dev` from the worker project, then
-open `http://localhost:9873`. Install
+For local preview, run `ntn workers customblocks dev` from the worker project.
+Then open `http://localhost:9873`. Install
 [`@notionhq/custom-blocks-dev-shell`](https://www.npmjs.com/package/@notionhq/custom-blocks-dev-shell)
 as a devDependency to pin the shell and get its reference docs in
-`node_modules`; see [`docs/deployment.md`](./docs/deployment.md) for how local
-serving works.
+`node_modules`. See [`docs/deployment.md`](./docs/deployment.md) for local
+serving details.
 
 ## Quick start
 
@@ -43,7 +49,7 @@ worker.customBlock("hello", {
 });
 ```
 
-In the block's entry point defined above, wrap your React code in `<NotionCustomBlock>` so the SDK connects with Notion before anything renders:
+Wrap your React app in `<NotionCustomBlock>` at the block's entry point:
 
 ```tsx
 // blocks/hello/src/index.tsx
@@ -52,10 +58,14 @@ import {
   NotionCustomBlock,
   NotionTokenScope,
 } from "@notionhq/custom-blocks/react";
-import ReactDOM from "react-dom/client";
+import { createRoot } from "react-dom/client";
 import { App } from "./App";
+import "./style.css";
 
-ReactDOM.createRoot(document.getElementById("root")!).render(
+const root = document.getElementById("root");
+if (!root) throw new Error("The root element is missing.");
+
+createRoot(root).render(
   <NotionCustomBlock>
     <NotionTokenScope>
       <App />
@@ -76,6 +86,8 @@ export function App() {
 }
 ```
 
+Save these styles in `blocks/hello/src/style.css`:
+
 ```css
 .app {
   color: var(--content-primary);
@@ -86,24 +98,34 @@ export function App() {
 }
 ```
 
-`<NotionCustomBlock>` runs the SDK ↔ host handshake (`connect` → `init` → `initResult`) and only mounts `children` once the host state is available. It measures the initial content before sending `initResult`, so the host can reveal the iframe at its correct height. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It continues observing content height changes automatically.
+`<NotionCustomBlock>` connects the SDK to the host and waits for host state before rendering its children.
+It reports the initial content height so the host can size the iframe before displaying it.
+It also reports later height changes automatically.
 
 ## Notion design tokens
 
-The optional `@notionhq/custom-blocks/nds.css` stylesheet provides the colors, spacing, typography, borders, and other design tokens used by Notion. Import it once, then put token-consuming UI inside `<NotionTokenScope>` as shown above.
+The optional `@notionhq/custom-blocks/nds.css` stylesheet provides Notion CSS variables for matching Notion's UI.
+These variables cover colors, spacing, typography, and borders.
+Import the stylesheet once. Place components that use the variables inside `<NotionTokenScope>`, as shown above.
 
-`<NotionTokenScope>` applies the display and contrast modes selected by the host, so variables such as `--content-primary` and `--bg-base` stay in sync with Notion automatically. Hosts that do not provide a contrast mode use standard contrast.
+`<NotionTokenScope>` applies the host's display and contrast modes to these variables.
+Hosts that omit a contrast mode use standard contrast.
 
 `NotionTokenScopeProps` has one required `children` prop.
 
-The stylesheet is scoped rather than installed globally. Render portals inside `<NotionTokenScope>`, or wrap the portal container in another scope. Framework-neutral renderers can read the current appearance with `customBlock.getTheme()` and `customBlock.getContrastMode()`; see [Block Location & Appearance](./docs/block-location.md).
+The CSS variables apply within the scope, not globally.
+Place portal containers inside `<NotionTokenScope>`, or wrap the portal content in another `<NotionTokenScope>`.
+Framework-neutral renderers can read the current appearance with `customBlock.getTheme()` and `customBlock.getContrastMode()`.
+See [Block location and appearance](./docs/block-location.md).
 
 ## Reference
 
-API surface, one page per category. Import framework-neutral APIs from `@notionhq/custom-blocks`; import React hooks and components from `@notionhq/custom-blocks/react`. Hover docs in your editor cover the per-field detail; these pages cover usage shape and the gotchas.
+Each page covers one API category. Import framework-neutral APIs from
+`@notionhq/custom-blocks`. Import React hooks and components from
+`@notionhq/custom-blocks/react`.
 
 - [`docs/lifecycle.md`](./docs/lifecycle.md) — `<NotionCustomBlock>`, `useCustomBlockInit`, `initCustomBlock`, `NotInIframeError`, `useCustomBlockAutoResize`. The handshake, the React wrapper, sizing.
-- [`docs/block-location.md`](./docs/block-location.md) — `useBlockId`, `useParent`, `usePage`, `useTheme`, and `useContrastMode`. Where the block sits and how to read the host's appearance.
+- [`docs/block-location.md`](./docs/block-location.md) — `useBlockId`, `useParent`, `usePage`, `useTheme`, `useContrastMode`, `NotionTokenScope`, and `NotionTokenScopeProps`. Where the block sits and how to read the host's appearance.
 - [`docs/data-sources.md`](./docs/data-sources.md) — `useDataSource`, `useManifest`, `customBlock.getManifest`, the row, property, and date-value types, plus a worked example.
 - [`docs/pages.md`](./docs/pages.md) — `pages.create / get / update / delete`, parent variants (including the recommended `data_source_key`), property input shapes.
 - [`docs/users.md`](./docs/users.md) — `users.list / get`, the `NotionUser` shape, paging.

package/dist/react/NotionCustomBlock.js

@@ -75,7 +75,7 @@ export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorF
         if (host.status !== "initialized") {
             return _jsx(_Fragment, { children: fallback });
         }
-        return (_jsxs(_Fragment, { children: [_jsx("div", { role: "status", className: "custom-blocks-standalone-banner", children: "Host not detected \u2014 running in standalone preview. Try `ntn customblocks dev` to run the block in a local development environment." }), children] }));
+        return (_jsxs(_Fragment, { children: [_jsx("div", { role: "status", className: "custom-blocks-standalone-banner", children: "Host not detected \u2014 running in standalone preview. Try `ntn workers customblocks dev` to run the block in a local development environment." }), children] }));
     }
     if (!init.isLoaded) {
         return _jsx(_Fragment, { children: fallback });

package/dist/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.41"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.42"

package/docs/block-location.md

@@ -118,7 +118,7 @@ const theme = customBlock.getTheme();
 ```
 
 ```tsx
-import { usePage, useTheme } from "@notionhq/custom-blocks";
+import { usePage, useTheme } from "@notionhq/custom-blocks/react";
 
 export function Header() {
   const page = usePage();
@@ -137,4 +137,4 @@ function useContrastMode(): NotionContrastMode; // "standard" | "high"
 
 For non-React renderers, use `customBlock.getContrastMode()` after `initCustomBlock()` resolves.
 
-For React apps, `<NotionTokenScope>` applies both appearance values to the bundled Notion design tokens automatically. Setup and portal guidance live in the [package README](../README.md#notion-design-tokens).
+For React apps, `<NotionTokenScope>` applies both appearance values to the bundled Notion CSS variables automatically.

package/docs/data-sources.md

@@ -137,9 +137,10 @@ renderManifest(customBlock.getManifest());
 
 ## Example: querying a data source
 
-A typical data-driven view picks a key, calls `useDataSource`, schema-checks the rows, and surfaces a setup hint when the mapped collection is missing the expected fields:
+This example calls `useDataSource` with a declared key. It validates each row’s values before rendering:
 
 ```tsx
+import { useState } from "react";
 import type { NotionDataSourcePage } from "@notionhq/custom-blocks";
 import { useDataSource } from "@notionhq/custom-blocks/react";
 
@@ -163,10 +164,7 @@ export function ScoreList() {
   const displayItems = items.filter(isComplete);
   if (displayItems.length === 0) {
     return (
-      <div>
-        Map a data source with key <code>{KEY}</code> exposing <code>name</code>{" "}
-        (text) and <code>score</code> (number).
-      </div>
+      <div>No rows have both a text name and a finite score.</div>
     );
   }
 
@@ -198,9 +196,9 @@ export function ScoreList() {
 
 ### Rows & values
 
-- `NotionDataSource` — a resolved data source: semantic key, `collectionSchema`, `propertyIdsByKey`, `propertySchemasById`.
+- `NotionDataSource` — a resolved data source: semantic key, optional `collectionSchema`, `propertyIdsByKey`, and `propertySchemasById`.
 - `NotionDataSourcePage` — a single row exposed to app code: `{ id, propertiesById, propertiesByKey, update }`.
-- `NotionDataSourceValue` — the discriminated union of values that can appear inside `propertiesById[propertyId]`. Date values branch into the `NotionDateValue` union below.
+- `NotionDataSourceValue` — the value union for `propertiesById` and `propertiesByKey`.
 - `NotionDataSourcePageUpdateArgs` / `UpdatePageResult` — arguments and result for the per-page `update` helper.
 - `NotionDataSourcePageUpdateInput` — deprecated alias for `NotionDataSourcePageUpdateArgs`.
 - `NotionDataSourcePageUpdateResult` — deprecated alias for `UpdatePageResult`.

package/docs/deployment.md

@@ -7,9 +7,11 @@ A custom block manifest describes the data sources a block requires, including t
 - **Deployed** — deploying persists the manifest on the block's definition record in Notion. The host reads it from there and sends it to the SDK during initialization.
 - **Local development** — the dev shell extracts the same worker declaration at runtime and serves the selected block's manifest dynamically at `/manifest`.
 
+Notion reconciles custom block definitions by their Worker capability keys during deployment.
+
 ## Local development
 
-Run `ntn customblocks dev` from a worker. It builds the worker, extracts its custom block declarations, starts one localhost Vite server per block, and renders them in the mock host at http://localhost:9873.
+Run `ntn workers customblocks dev` from a worker. It builds the worker, extracts its custom block declarations, starts one localhost Vite server per block, and renders them in the mock host at http://localhost:9873.
 
 At startup, the SDK fetches the page-relative `manifest` path only when the bundle's hostname is exactly `localhost`, then forwards the response in `connect`. On every other hostname, the SDK skips this fetch and relies on the host-provided manifest from `init`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.41",
+	"version": "0.1.42",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {

package/src/react/NotionCustomBlock.tsx

@@ -119,7 +119,7 @@ export function NotionCustomBlock({
 		return (
 			<>
 				<div role="status" className="custom-blocks-standalone-banner">
-					Host not detected — running in standalone preview. Try `ntn
+					Host not detected — running in standalone preview. Try `ntn workers
 					customblocks dev` to run the block in a local development environment.
 				</div>
 				{children}