create-ncblock 0.0.34 → 0.0.36

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-ncblock",
-	"version": "0.0.34",
+	"version": "0.0.36",
 	"description": "Create a Notion custom view block project.",
 	"type": "module",
 	"bin": {

package/scripts/scaffold-assets/AGENTS.md

@@ -15,8 +15,9 @@ That writes `custom_blocks.json`, `.notion/target.json`, and PATCHes any blocks
 ## Talking to the host
 
 - Always use the React hooks from `ncblock/react`. Never call `window.parent.postMessage` directly — the SDK owns the protocol.
-- Render app code inside `<NotionCustomBlock>` so the handshake completes before hooks run.
-- `<NotionCustomBlock>` runs `useCustomBlockAutoResize` for you by default — no extra wiring needed. Pass `autoResize={false}` for full-bleed views.
+- Render app code inside `<NotionCustomBlock>` so the handshake completes before hooks like `useTheme` or `useBlockId` run.
+
+`<NotionCustomBlock>` runs `useCustomBlockAutoResize` for you by default — no extra wiring needed. Pass `autoResize={false}` for full-bleed views. Read `node_modules/ncblock/README.md` and the `.d.ts` files for current APIs and signatures.
 
 ## Sizing
 
@@ -49,7 +50,7 @@ Two options:
 
 - `node_modules/ncblock/README.md` — landing page with a TOC into the per-category docs below.
 - `node_modules/ncblock/docs/lifecycle.md` — `<NotionCustomBlock>`, init, sizing, auto-resize.
-- `node_modules/ncblock/docs/context.md` — `useCustomBlockContext`, `useTheme`.
+- `node_modules/ncblock/docs/block-location.md` — `useBlockId`, `useParent`, `usePage`, `useTheme`.
 - `node_modules/ncblock/docs/data-sources.md` — `useDataSource`, row/property/date types, worked example.
 - `node_modules/ncblock/docs/pages.md` — `pages.create / get / update / delete`.
 - `node_modules/ncblock/docs/users.md` — `users.list / get`, `NotionUser`.

package/sdk-version.json

@@ -1 +1 @@
-{"version":"0.0.32"}
+{"version":"0.0.34"}

package/templates/debug/README.md

@@ -28,9 +28,6 @@ Vite bundles `src/index.tsx` into `dist/`. When embedded in Notion, the SDK hook
 
 The debug template includes a message log that intercepts and displays all incoming and outgoing `postMessage` events, making it useful for understanding the Notion host communication protocol.
 
-### SDK hooks
+### SDK docs
 
-- **`useCustomBlockContext()`** -- returns `{ customBlockId, parent, page }` describing the block's location in the document tree
-- **`useTheme()`** -- returns the host's current theme (`"light"` or `"dark"`)
-- **`useManifest()`** -- returns the declared manifest (data-source keys + property declarations)
-- **`useDataSource(key)`** -- returns `{ items, collectionSchema, propertySchemasById, propertySchemasByKey, isLoading, hasMore, fetchMore, error }`. Each `item` has `{ id, propertiesById, propertiesByKey }`. The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) appear in `propertiesById` / `propertySchemasById`, never in the `*ByKey` views.
+This project uses the public `ncblock` React hooks and data source APIs. After installing dependencies, see `node_modules/ncblock/README.md` for the current API reference and links to the per-category docs.

package/templates/debug/src/index.tsx

@@ -1,6 +1,6 @@
 import {
+	type NotionBlockId,
 	type NotionCreatePagePosition,
-	type NotionCustomBlockContext,
 	type NotionDataSourceId,
 	type NotionPage,
 	type NotionPageId,
@@ -8,9 +8,11 @@ import {
 } from "ncblock"
 import {
 	NotionCustomBlock,
+	useBlockId,
 	useCurrentUser,
-	useCustomBlockContext,
 	useManifest,
+	usePage,
+	useParent,
 	useTheme,
 } from "ncblock/react"
 import React, {
@@ -55,7 +57,9 @@ const metaTextClass =
 const HOST_NO_READY_ERROR_DELAY_SECONDS = 5
 
 function App() {
-	const ctx = useCustomBlockContext()
+	const blockId = useBlockId()
+	const parent = useParent()
+	const page = usePage()
 	const currentUser = useCurrentUser()
 	const hostThemeValue = useTheme()
 	const manifest = useManifest()
@@ -84,11 +88,11 @@ function App() {
 		"--status-color": status.color,
 	} as React.CSSProperties
 
-	const contextValue = {
+	const blockLocationValue = {
 		theme: hostThemeValue,
-		customBlockId: ctx?.customBlockId,
-		parent: ctx?.parent,
-		page: ctx?.page,
+		blockId,
+		parent,
+		page,
 		currentUser,
 		manifest,
 	}
@@ -158,32 +162,36 @@ function App() {
 				</div>
 			</CollapsibleCard>
 
-			{/* Context state */}
+			{/* Init state */}
 			<CollapsibleCard
 				label="Init payload"
 				headerExtra={
 					<span className={metaTextClass}>
-						{Object.keys(contextValue).length} keys
+						{Object.keys(blockLocationValue).length} keys
 					</span>
 				}
 				headerActions={
 					<IconButton
-						label="Copy context JSON"
-						onClick={() => copy(serializeForCopy(contextValue))}
+						label="Copy init JSON"
+						onClick={() => copy(serializeForCopy(blockLocationValue))}
 					>
 						<CopyIcon />
 					</IconButton>
 				}
 			>
 				<JsonPanel
-					value={contextValue}
+					value={blockLocationValue}
 					onCopy={copy}
 					defaultExpandedDepth={2}
 				/>
 			</CollapsibleCard>
 
 			{/* Create page */}
-			<CreatePageCard context={ctx} dataSourceKeys={dataSourceKeys} />
+			<CreatePageCard
+				blockId={blockId}
+				currentPage={page}
+				dataSourceKeys={dataSourceKeys}
+			/>
 
 			{/* Send message */}
 			<SendMessageCard onSend={send} />
@@ -1655,7 +1663,8 @@ class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
 }
 
 type CreatePageCardProps = {
-	context: NotionCustomBlockContext | undefined
+	blockId: NotionBlockId | undefined
+	currentPage: { id: NotionPageId } | undefined
 	dataSourceKeys: string[]
 }
 
@@ -1666,7 +1675,7 @@ type CreatePagePreset = {
 }
 
 function presetPositions(
-	customBlockId: string | undefined,
+	customBlockId: NotionBlockId | undefined,
 ): CreatePagePreset[] {
 	const presets: CreatePagePreset[] = [
 		{
@@ -1775,7 +1784,7 @@ function pageIconFromInput(raw: string): NotionPage["icon"] | undefined {
 /**
  * Buttons that exercise `sdk.pages.create` at each of the supported positions. Every preset creates
  * a page whose `parent.page_id` is the nearest page ancestor. `position` demonstrates append,
- * prepend, and inserting directly above or below the custom block via `context.customBlockId`.
+ * prepend, and inserting directly above or below the custom block via `useBlockId()`.
  *
  * Two extra affordances exercise the data-source-backed parents:
  * - A free-form input accepts a data source ID and uses `parent: { type: "data_source_id", ... }`
@@ -1784,34 +1793,38 @@ function pageIconFromInput(raw: string): NotionPage["icon"] | undefined {
  *   SDK resolve the key to the configured data source ID locally before sending the request to the
  *   Notion host.
  */
-function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
+function CreatePageCard({
+	blockId,
+	currentPage,
+	dataSourceKeys,
+}: CreatePageCardProps) {
 	const [status, setStatus] = useState<string | null>(null)
 	const [busy, setBusy] = useState(false)
 	const [dataSourceId, setDataSourceId] = useState("")
 	const [pageId, setPageId] = useState("")
 	const [trackedPages, setTrackedPages] = useState<TrackedPage[]>([])
-	const presets = presetPositions(context?.customBlockId)
-	const disabled = context === undefined || busy
+	const presets = presetPositions(blockId)
+	const disabled = currentPage === undefined || busy
 	const trimmedDataSourceId = dataSourceId.trim()
 	const dataSourceDisabled = disabled || trimmedDataSourceId === ""
 	const trimmedPageId = pageId.trim()
 	const fetchDisabled = busy || trimmedPageId === ""
 
 	useEffect(() => {
-		if (context?.page.id && pageId === "") {
-			setPageId(context.page.id)
+		if (currentPage !== undefined && pageId === "") {
+			setPageId(currentPage.id)
 		}
-	}, [context?.page.id, pageId])
+	}, [currentPage, pageId])
 
 	const handleCreate = async (preset: CreatePagePreset) => {
-		if (context === undefined || busy) {
+		if (currentPage === undefined || busy) {
 			return
 		}
 		setBusy(true)
 		setStatus(`Creating (${preset.label})\u2026`)
 		const title = `New page (${preset.label.toLowerCase()}) ${new Date().toLocaleTimeString()}`
 		const result = await pages.create({
-			parent: { type: "page_id", page_id: context.page.id },
+			parent: { type: "page_id", page_id: currentPage.id },
 			properties: {
 				title: {
 					id: "title",
@@ -1825,13 +1838,13 @@ function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 			setTrackedPages(prev => trackPage(prev, result.page))
 			setStatus(`\u2713 ${preset.label}: ${result.page.id}`)
 		} else {
-			setStatus(`\u2717 ${preset.label}: ${result.error}`)
+			setStatus(`\u2717 ${preset.label}: ${result.error.message}`)
 		}
 		setBusy(false)
 	}
 
 	const handleCreateInDataSource = async () => {
-		if (context === undefined || busy || trimmedDataSourceId === "") {
+		if (currentPage === undefined || busy || trimmedDataSourceId === "") {
 			return
 		}
 		setBusy(true)
@@ -1854,13 +1867,13 @@ function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 			setTrackedPages(prev => trackPage(prev, result.page))
 			setStatus(`\u2713 Data source: ${result.page.id}`)
 		} else {
-			setStatus(`\u2717 Data source: ${result.error}`)
+			setStatus(`\u2717 Data source: ${result.error.message}`)
 		}
 		setBusy(false)
 	}
 
 	const handleCreateForKey = async (key: string) => {
-		if (context === undefined || busy) {
+		if (disabled) {
 			return
 		}
 		setBusy(true)
@@ -1880,7 +1893,7 @@ function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 			setTrackedPages(prev => trackPage(prev, result.page))
 			setStatus(`\u2713 Key "${key}": ${result.page.id}`)
 		} else {
-			setStatus(`\u2717 Key "${key}": ${result.error}`)
+			setStatus(`\u2717 Key "${key}": ${result.error.message}`)
 		}
 		setBusy(false)
 	}
@@ -1896,7 +1909,7 @@ function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 			setTrackedPages(prev => trackPage(prev, result.page))
 			setStatus(`\u2713 Loaded ${result.page.id}`)
 		} else {
-			setStatus(`\u2717 Fetch failed: ${result.error}`)
+			setStatus(`\u2717 Fetch failed: ${result.error.message}`)
 		}
 		setBusy(false)
 	}
@@ -1912,7 +1925,7 @@ function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 			setTrackedPages(prev => trackPage(prev, result.page))
 			setStatus(`\u2713 Refreshed ${result.page.id}`)
 		} else {
-			setStatus(`\u2717 Refresh failed: ${result.error}`)
+			setStatus(`\u2717 Refresh failed: ${result.error.message}`)
 		}
 		setBusy(false)
 	}
@@ -1961,7 +1974,7 @@ function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 			setTrackedPages(prev => trackPage(prev, result.page))
 			setStatus(`\u2713 Saved ${result.page.id}`)
 		} else {
-			setStatus(`\u2717 Save failed: ${result.error}`)
+			setStatus(`\u2717 Save failed: ${result.error.message}`)
 		}
 		setBusy(false)
 	}
@@ -1977,7 +1990,7 @@ function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 			setTrackedPages(prev => trackPage(prev, result.page))
 			setStatus(`\u2713 Deleted ${result.page.id}`)
 		} else {
-			setStatus(`\u2717 Delete failed: ${result.error}`)
+			setStatus(`\u2717 Delete failed: ${result.error.message}`)
 		}
 		setBusy(false)
 	}
@@ -2047,7 +2060,7 @@ function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 					type="text"
 					value={pageId}
 					onChange={event => setPageId(event.target.value)}
-					placeholder={context?.page.id ?? "page_id"}
+					placeholder={currentPage?.id ?? "page_id"}
 					spellCheck={false}
 					className="min-w-0 flex-1 rounded-md border border-(--border) bg-(--app-bg) px-2 py-1 font-mono text-[11px] outline-none transition-colors focus:border-(--foreground)"
 				/>

package/templates/radar-chart/README.md

@@ -47,9 +47,6 @@ Example row shape:
 
 If the mapped collection is missing any of those fields, the template shows a setup hint and falls back to built-in sample data so you can still preview the chart locally.
 
-## SDK hooks
+## SDK docs
 
-- **`useCustomBlockContext()`** -- returns `{ customBlockId, parent, page }` describing the block's location in the document tree
-- **`useTheme()`** -- returns the host's current theme (`"light"` or `"dark"`)
-- **`useManifest()`** -- returns the declared manifest (data-source keys + property declarations)
-- **`useDataSource(key)`** -- returns `{ items, collectionSchema, propertySchemasById, propertySchemasByKey, isLoading, hasMore, fetchMore, error }`. Each `item` has `{ id, propertiesById, propertiesByKey }`. The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) appear in `propertiesById` / `propertySchemasById`, never in the `*ByKey` views.
+This project uses the public `ncblock` React hooks and data source APIs. After installing dependencies, see `node_modules/ncblock/README.md` for the current API reference and links to the per-category docs.

package/templates/radar-chart/src/index.tsx

@@ -33,7 +33,11 @@ function makeFakeItem(
 		propertiesByKey: properties,
 		update: async () => ({
 			status: "error",
-			error: "Sample rows are read-only",
+			error: {
+				code: "update_page_failed",
+				message: "Sample rows are read-only",
+				isRetryable: false,
+			},
 		}),
 	}
 }
@@ -515,7 +519,7 @@ function App() {
 				items={items}
 				isUsingFallbackData={isUsingFallbackData}
 				analysis={analysis}
-				queryError={query.error}
+				queryError={query.error?.message}
 				hasMore={query.hasMore}
 				isLoading={query.isLoading}
 				onFetchMore={query.fetchMore}

package/templates/table-view/README.md

@@ -35,9 +35,6 @@ string arrays, and relations. It also includes search, column visibility
 controls, density switching, and relation pills that render `-> title` when a
 related page is loaded or `-> uuid` when it is not.
 
-## SDK hooks
+## SDK docs
 
-- **`useCustomBlockContext()`** -- returns `{ customBlockId, parent, page }` describing the block's location in the document tree
-- **`useTheme()`** -- returns the host's current theme (`"light"` or `"dark"`)
-- **`useManifest()`** -- returns the declared manifest (data-source keys + property declarations)
-- **`useDataSource(key)`** -- returns `{ items, collectionSchema, propertySchemasById, propertySchemasByKey, isLoading, hasMore, fetchMore, error }`. Each `item` has `{ id, propertiesById, propertiesByKey }`. The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) appear in `propertiesById` / `propertySchemasById`, never in the `*ByKey` views.
+This project uses the public `ncblock` React hooks and data source APIs. After installing dependencies, see `node_modules/ncblock/README.md` for the current API reference and links to the per-category docs.

package/templates/table-view/src/index.tsx

@@ -1162,7 +1162,7 @@ function DataWorkspace(props: {
 				})
 				return
 			}
-			setUpdateStatus({ type: "error", message: result.error })
+			setUpdateStatus({ type: "error", message: result.error.message })
 		} catch (error) {
 			setUpdateStatus({
 				type: "error",
@@ -1212,7 +1212,7 @@ function DataWorkspace(props: {
 				setCreatingDraft(emptyDraftByKey(writableColumns))
 				return
 			}
-			setCreateStatus({ type: "error", message: result.error })
+			setCreateStatus({ type: "error", message: result.error.message })
 		} catch (error) {
 			setCreateStatus({
 				type: "error",
@@ -1803,7 +1803,7 @@ function App() {
 					onFetchMore={query.fetchMore}
 					isUsingFallbackData={isUsingFallbackData}
 					isCollectionEmpty={isCollectionEmpty}
-					queryError={query.error}
+					queryError={query.error?.message}
 				/>
 			</div>
 		</div>

package/templates/table-view/src/table-model.ts

@@ -82,7 +82,11 @@ function makeSampleRow(
 		propertiesByKey: properties,
 		update: async () => ({
 			status: "error",
-			error: "Sample rows are read-only",
+			error: {
+				code: "update_page_failed",
+				message: "Sample rows are read-only",
+				isRetryable: false,
+			},
 		}),
 	}
 }