create-ncblock 0.0.21 → 0.0.23

package/package.json

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

package/scripts/scaffold-assets/AGENTS.md

@@ -22,7 +22,7 @@ Hooks at a glance:
 - `useCustomBlockContext()` — `{ customBlockId, parent, page }`.
 - `useTheme()` — `"light" | "dark"`.
 - `useDataSource(key, initialLimit?)` — `{ items, isLoading, hasMore, fetchMore, error }`.
-- `useDataSourceDefinitions()` — resolved data-source definitions (for debug/schema-driven UIs).
+- `useManifest()` — the declared manifest: data-source keys plus their property declarations.
 - `pages.create(input)` — creates a page; pass `parent: { type: "data_source_key", key }` to target the block's wired data source.
 
 `<NotionCustomBlock>` runs `useCustomBlockAutoResize` for you by default — no extra wiring needed. Pass `autoResize={false}` for full-bleed views. Full signatures live in `node_modules/ncblock/docs/*.md` and the `.d.ts` files.

package/sdk-version.json

@@ -1 +1 @@
-{"version":"0.0.19"}
+{"version":"0.0.21"}

package/templates/debug/README.md

@@ -32,5 +32,5 @@ The debug template includes a message log that intercepts and displays all incom
 
 - **`useCustomBlockContext()`** -- returns `{ customBlockId, parent, page }` describing the block's location in the document tree
 - **`useTheme()`** -- returns the host's current theme (`"light"` or `"dark"`)
-- **`useDataSourceDefinitions()`** -- returns resolved data-source definitions
+- **`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.

package/templates/debug/src/index.tsx

@@ -2,14 +2,13 @@ import {
 	type NotionCreatePagePosition,
 	NotionCustomBlock,
 	type NotionCustomBlockContext,
-	type NotionDataSource,
 	type NotionDataSourceId,
 	type NotionPage,
 	type NotionPageId,
 	pages,
 	useCurrentUser,
 	useCustomBlockContext,
-	useDataSourceDefinitions,
+	useManifest,
 	useTheme,
 } from "ncblock"
 import React, {
@@ -33,6 +32,11 @@ type LogEntry = {
 }
 
 type ThemeOverride = "host" | "light" | "dark"
+type NotionInitFixture =
+	| "normal"
+	| "no-ready"
+	| "invalid-ready"
+	| "invalid-manifest"
 type TrackedPage = {
 	page: NotionPage
 	draftTitle: string
@@ -45,12 +49,14 @@ const labelClass =
 	"text-[10px] font-semibold uppercase tracking-[0.06em] text-(--muted)"
 const metaTextClass =
 	"font-mono text-[11px] font-normal normal-case tracking-normal text-(--muted)"
+const HOST_NO_READY_ERROR_DELAY_SECONDS = 5
 
 function App() {
 	const ctx = useCustomBlockContext()
 	const currentUser = useCurrentUser()
 	const hostThemeValue = useTheme()
-	const dataSources = useDataSourceDefinitions()
+	const manifest = useManifest()
+	const dataSourceKeys = Object.keys(manifest?.dataSources ?? {})
 	const [isPaused, setIsPaused] = useState(false)
 	const { log, initData, send, clearLog } = useMessageLog(isPaused)
 	const [themeOverride, setThemeOverride] = useState<ThemeOverride>("host")
@@ -81,7 +87,7 @@ function App() {
 		parent: ctx?.parent,
 		page: ctx?.page,
 		currentUser,
-		dataSources,
+		manifest,
 	}
 
 	const metadataRows: Array<[string, string]> = [
@@ -174,7 +180,7 @@ function App() {
 			</CollapsibleCard>
 
 			{/* Create page */}
-			<CreatePageCard context={ctx} dataSources={dataSources} />
+			<CreatePageCard context={ctx} dataSourceKeys={dataSourceKeys} />
 
 			{/* Send message */}
 			<SendMessageCard onSend={send} />
@@ -198,6 +204,162 @@ function App() {
 	)
 }
 
+function DevOnlyNoReadyFixture() {
+	return (
+		<div className="min-h-screen bg-(--app-bg) p-8 text-(--foreground)">
+			<div className={cardClass}>
+				<div className={labelClass}>Local init fixture</div>
+				<h1 className="mt-2 text-[24px] font-semibold">No ready message</h1>
+				<p className="mt-2 text-sm leading-6 text-(--muted)">
+					This dev-only fixture intentionally skips the SDK provider, so the
+					sandbox loads but never sends the initial <code>ready</code> message.
+					Use it only for local manual testing of Notion host init error UI.
+				</p>
+				<DevOnlyHostErrorExpectation>
+					This page is the pre-error fixture, not the Notion error state. In the
+					Notion host, wait about {HOST_NO_READY_ERROR_DELAY_SECONDS} seconds
+					after the iframe loads; the host-owned{" "}
+					<span className="font-mono">Custom block didn't connect</span> error
+					should then cover this page.
+				</DevOnlyHostErrorExpectation>
+			</div>
+		</div>
+	)
+}
+
+function DevOnlyInvalidReadyFixture() {
+	useEffect(() => {
+		if (window.parent === window) {
+			return
+		}
+
+		// Dev-only fixture for local manual testing of Notion host init error UI.
+		// This intentionally bypasses the SDK so the host receives a malformed
+		// ready message that is missing the manifest and protocol fields.
+		window.parent.postMessage({ type: "ready" }, "*")
+	}, [])
+
+	return (
+		<div className="min-h-screen bg-(--app-bg) p-8 text-(--foreground)">
+			<div className={cardClass}>
+				<div className={labelClass}>Local init fixture</div>
+				<h1 className="mt-2 text-[24px] font-semibold">
+					Invalid ready message
+				</h1>
+				<p className="mt-2 text-sm leading-6 text-(--muted)">
+					This dev-only fixture posts malformed{" "}
+					<code>{'{ type: "ready" }'}</code> to the parent window and does not
+					mount the SDK provider. Use it only for local manual testing of Notion
+					host init error UI.
+				</p>
+				<DevOnlyHostErrorExpectation>
+					This page is the pre-error fixture, not the Notion error state. In the
+					Notion host, the host-owned invalid setup message error should cover
+					this page as soon as Notion processes the malformed <code>ready</code>{" "}
+					message.
+				</DevOnlyHostErrorExpectation>
+			</div>
+		</div>
+	)
+}
+
+function DevOnlyInvalidManifestFixture() {
+	useEffect(() => {
+		if (window.parent === window) {
+			return
+		}
+
+		// Dev-only fixture for local manual testing of Notion host init error UI.
+		// This intentionally bypasses the SDK so the host receives a ready message
+		// with a manifest schema the bridge validator must reject.
+		window.parent.postMessage(
+			{
+				type: "ready",
+				bridgeProtocolVersion: 1,
+				manifest: {
+					version: 1,
+					dataSources: {
+						default: {
+							name: "Invalid fixture data source",
+							properties: {
+								unsupportedProperty: {
+									name: "Unsupported property",
+									type: "unsupported_manual_fixture_property_type",
+								},
+							},
+						},
+					},
+				},
+			},
+			"*",
+		)
+	}, [])
+
+	return (
+		<div className="min-h-screen bg-(--app-bg) p-8 text-(--foreground)">
+			<div className={cardClass}>
+				<div className={labelClass}>Local init fixture</div>
+				<h1 className="mt-2 text-[24px] font-semibold">Invalid manifest</h1>
+				<p className="mt-2 text-sm leading-6 text-(--muted)">
+					This dev-only fixture posts a <code>ready</code> message with an
+					unsupported manifest property type and does not mount the SDK
+					provider. Use it only for local manual testing of Notion host init
+					error UI.
+				</p>
+				<DevOnlyHostErrorExpectation>
+					This page is the pre-error fixture, not the Notion error state. In the
+					Notion host, the host-owned invalid manifest error should cover this
+					page as soon as Notion validates the <code>ready</code> message.
+				</DevOnlyHostErrorExpectation>
+			</div>
+		</div>
+	)
+}
+
+function DevOnlyHostErrorExpectation(props: { children: React.ReactNode }) {
+	return (
+		<div className="mt-3 rounded-md border border-(--border) bg-(--app-bg) px-3 py-2 text-sm leading-6 text-(--foreground)">
+			<span className="font-semibold">Expected host behavior: </span>
+			{props.children}
+		</div>
+	)
+}
+
+function DebugInitErrorFallback(error: Error) {
+	return (
+		<div className="min-h-screen bg-(--app-bg) p-8 text-(--foreground)">
+			<div className={cardClass} role="alert">
+				<div className={labelClass}>Custom block init</div>
+				<h1 className="mt-2 text-[24px] font-semibold">
+					Couldn&apos;t connect to Notion
+				</h1>
+				<p className="mt-2 text-sm leading-6 text-(--muted)">
+					The debug template waited for the host handshake, but it did not
+					complete. This fallback is only for local manual testing; host-owned
+					error UI should normally cover known Notion init failures first.
+				</p>
+				<pre className="mt-3 overflow-auto rounded-md border border-(--border) bg-(--app-bg) p-3 font-mono text-[11px] text-(--muted)">
+					{error.message}
+				</pre>
+			</div>
+		</div>
+	)
+}
+
+function getNotionInitFixture(): NotionInitFixture {
+	const fixture = new URLSearchParams(window.location.search).get(
+		"notionInitFixture",
+	)
+	if (
+		fixture === "no-ready" ||
+		fixture === "invalid-ready" ||
+		fixture === "invalid-manifest"
+	) {
+		return fixture
+	}
+	return "normal"
+}
+
 // --- Hooks ---
 
 function useMessageLog(isPaused: boolean) {
@@ -1448,7 +1610,7 @@ class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
 
 type CreatePageCardProps = {
 	context: NotionCustomBlockContext | undefined
-	dataSources: NotionDataSource[]
+	dataSourceKeys: string[]
 }
 
 type CreatePagePreset = {
@@ -1576,7 +1738,7 @@ 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, dataSources }: CreatePageCardProps) {
+function CreatePageCard({ context, dataSourceKeys }: CreatePageCardProps) {
 	const [status, setStatus] = useState<string | null>(null)
 	const [busy, setBusy] = useState(false)
 	const [dataSourceId, setDataSourceId] = useState("")
@@ -1813,27 +1975,23 @@ function CreatePageCard({ context, dataSources }: CreatePageCardProps) {
 					Create in data source
 				</button>
 			</div>
-			{dataSources.length > 0 && (
+			{dataSourceKeys.length > 0 && (
 				<div className="mb-2 flex flex-wrap items-center gap-1.5">
 					<span className="font-mono text-[11px] text-(--muted)">
 						by data source key:
 					</span>
-					{dataSources.map(source => (
+					{dataSourceKeys.map(key => (
 						<button
-							key={source.key}
+							key={key}
 							type="button"
 							disabled={disabled}
-							title={
-								source.collectionPointer !== undefined
-									? `Create a page in data source ${source.collectionPointer.id} via key "${source.key}"`
-									: `Key "${source.key}" has no collection pointer yet; request will resolve with an error`
-							}
+							title={`Create a page via data source key "${key}" (resolves to an error if the key is not mapped to a database yet)`}
 							className="rounded-md border border-(--border) bg-transparent px-2 py-1 font-mono text-[11px] text-(--muted) transition-colors hover:border-(--foreground)/20 hover:bg-(--hover-bg) hover:text-(--foreground) disabled:cursor-not-allowed disabled:opacity-50"
 							onClick={() => {
-								void handleCreateForKey(source.key)
+								void handleCreateForKey(key)
 							}}
 						>
-							{source.key}
+							{key}
 						</button>
 					))}
 				</div>
@@ -1960,10 +2118,19 @@ function CreatePageCard({ context, dataSources }: CreatePageCardProps) {
 
 // --- Mount ---
 
+const notionInitFixture = getNotionInitFixture()
+
 ReactDOM.createRoot(document.getElementById("root")!).render(
 	<ErrorBoundary>
-		<NotionCustomBlock>
-			<App />
-		</NotionCustomBlock>
+		{notionInitFixture === "no-ready" && <DevOnlyNoReadyFixture />}
+		{notionInitFixture === "invalid-ready" && <DevOnlyInvalidReadyFixture />}
+		{notionInitFixture === "invalid-manifest" && (
+			<DevOnlyInvalidManifestFixture />
+		)}
+		{notionInitFixture === "normal" && (
+			<NotionCustomBlock errorFallback={DebugInitErrorFallback}>
+				<App />
+			</NotionCustomBlock>
+		)}
 	</ErrorBoundary>,
 )

package/templates/radar-chart/README.md

@@ -51,5 +51,5 @@ If the mapped collection is missing any of those fields, the template shows a se
 
 - **`useCustomBlockContext()`** -- returns `{ customBlockId, parent, page }` describing the block's location in the document tree
 - **`useTheme()`** -- returns the host's current theme (`"light"` or `"dark"`)
-- **`useDataSourceDefinitions()`** -- returns resolved data-source definitions
+- **`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.

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

@@ -3,7 +3,7 @@ import {
 	type NotionDataSourcePage,
 	type NotionPageId,
 	useDataSource,
-	useDataSourceDefinitions,
+	useManifest,
 	useTheme,
 } from "ncblock"
 import React from "react"
@@ -445,8 +445,9 @@ function SetupHint(props: {
 
 function App() {
 	const theme = useTheme()
-	const dataSources = useDataSourceDefinitions()
-	const activeDataSourceKey = dataSources[0]?.key ?? "default"
+	const manifest = useManifest()
+	const activeDataSourceKey =
+		Object.keys(manifest?.dataSources ?? {})[0] ?? "default"
 	const query = useDataSource(activeDataSourceKey)
 	const colorTheme = theme === "dark" ? "dark" : "light"
 	const mappedAnalysis = analyzeRadarSchema(query.items)

package/templates/table-view/README.md

@@ -39,5 +39,5 @@ related page is loaded or `-> uuid` when it is not.
 
 - **`useCustomBlockContext()`** -- returns `{ customBlockId, parent, page }` describing the block's location in the document tree
 - **`useTheme()`** -- returns the host's current theme (`"light"` or `"dark"`)
-- **`useDataSourceDefinitions()`** -- returns resolved data-source definitions
+- **`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.

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

@@ -8,13 +8,12 @@ import {
 } from "@tanstack/react-table"
 import {
 	NotionCustomBlock,
-	type NotionDataSource,
 	type NotionPagePropertyInputMap,
 	type NotionPagePropertyInputValue,
 	type NotionPropertySchema,
 	pages,
 	useDataSource,
-	useDataSourceDefinitions,
+	useManifest,
 	useTheme,
 } from "ncblock"
 import React from "react"
@@ -1004,7 +1003,7 @@ function DataWorkspace(props: {
 	onColumnOrderChange: (next: string[]) => void
 	onHiddenColumnsChange: (next: Set<string>) => void
 	activeDataSourceKey: string
-	dataSources: NotionDataSource[]
+	dataSourceKeys: string[]
 	onSelectDataSource: (key: string) => void
 	hasMore: boolean
 	isLoading: boolean
@@ -1023,7 +1022,7 @@ function DataWorkspace(props: {
 		onColumnOrderChange,
 		onHiddenColumnsChange,
 		activeDataSourceKey,
-		dataSources,
+		dataSourceKeys,
 		onSelectDataSource,
 		hasMore,
 		isLoading,
@@ -1417,7 +1416,7 @@ function DataWorkspace(props: {
 					<span className="eyebrow ml-1.5">rows</span>
 				</div>
 
-				{dataSources.length > 1 ? (
+				{dataSourceKeys.length > 1 ? (
 					<label className="block">
 						<span className="sr-only">Choose data source</span>
 						<select
@@ -1425,9 +1424,9 @@ function DataWorkspace(props: {
 							onChange={event => onSelectDataSource(event.target.value)}
 							className="field-control min-h-9 w-full rounded-md border border-(--line) bg-(--surface-bg) px-2 text-sm text-(--foreground) outline-none hover:border-(--line-strong)"
 						>
-							{dataSources.map(dataSource => (
-								<option key={dataSource.key} value={dataSource.key}>
-									{dataSource.key}
+							{dataSourceKeys.map(key => (
+								<option key={key} value={key}>
+									{key}
 								</option>
 							))}
 						</select>
@@ -1682,30 +1681,32 @@ function DataWorkspace(props: {
 
 function App() {
 	const theme = useTheme()
-	const dataSources = useDataSourceDefinitions()
+	const manifest = useManifest()
+	const dataSourceKeys = React.useMemo(
+		() => Object.keys(manifest?.dataSources ?? {}),
+		[manifest],
+	)
 	const [activeDataSourceKey, setActiveDataSourceKey] = React.useState(
-		dataSources[0]?.key ?? "default",
+		dataSourceKeys[0] ?? "default",
 	)
 
 	React.useEffect(() => {
-		if (dataSources.length === 0) {
+		if (dataSourceKeys.length === 0) {
 			setActiveDataSourceKey("default")
 			return
 		}
 
-		if (
-			!dataSources.some(dataSource => dataSource.key === activeDataSourceKey)
-		) {
-			setActiveDataSourceKey(dataSources[0].key)
+		if (!dataSourceKeys.includes(activeDataSourceKey)) {
+			setActiveDataSourceKey(dataSourceKeys[0])
 		}
-	}, [activeDataSourceKey, dataSources])
+	}, [activeDataSourceKey, dataSourceKeys])
 
-	const queryKey = dataSources.length === 0 ? "default" : activeDataSourceKey
+	const queryKey = dataSourceKeys.length === 0 ? "default" : activeDataSourceKey
 	const query = useDataSource(queryKey)
 	const colorTheme = theme === "dark" ? "dark" : "light"
 
 	const mappedItems = query.items as TableRow[]
-	const isUsingFallbackData = dataSources.length === 0
+	const isUsingFallbackData = dataSourceKeys.length === 0
 	const isCollectionEmpty =
 		!isUsingFallbackData && !query.isLoading && mappedItems.length === 0
 	const items = isUsingFallbackData ? SAMPLE_ITEMS : mappedItems
@@ -1793,7 +1794,7 @@ function App() {
 					onColumnOrderChange={setColumnOrder}
 					onHiddenColumnsChange={setHiddenColumns}
 					activeDataSourceKey={queryKey}
-					dataSources={dataSources}
+					dataSourceKeys={dataSourceKeys}
 					onSelectDataSource={setActiveDataSourceKey}
 					hasMore={query.hasMore}
 					isLoading={query.isLoading}