ncblock 0.0.1

package/README.md

@@ -0,0 +1,286 @@
+# ncblock
+
+> Internal alias for the Notion Custom Block SDK. Published under this name to keep the package off general discovery surfaces.
+
+React SDK for building [Notion custom view](https://app.dev.notion.com/p/notion/Custom-Blocks-Sandbox-Capabilities-APIs-33eb35e6e67f80e387e3e74499ba0d42) blocks.
+
+A custom view runs as a sandboxed `<iframe>` inside a Notion block on iOS, Android, and desktop. The only channel between your view and Notion is a `postMessage` bridge — this SDK wraps it in a small set of typed React hooks.
+
+> **Pre-release.** Breaking changes may land at any time before 1.0.
+
+## Quick start
+
+```tsx
+// src/index.tsx
+import { NotionCustomBlock } from "ncblock";
+import ReactDOM from "react-dom/client";
+import { App } from "./App";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <NotionCustomBlock>
+    <App />
+  </NotionCustomBlock>,
+);
+```
+
+```tsx
+// src/App.tsx
+import { useCustomBlockContext, useTheme } from "ncblock";
+
+export function App() {
+  const context = useCustomBlockContext();
+  const theme = useTheme();
+  return <div data-theme={theme}>Hello from {context.customBlockId}.</div>;
+}
+```
+
+`<NotionCustomBlock>` runs the SDK ↔ host handshake (sends `ready` with the manifest, awaits `init`) and only mounts `children` once it resolves. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It also runs `useCustomBlockAutoResize` for you by default; pass `autoResize={false}` to opt out.
+
+## Concepts
+
+### Bridge & lifecycle
+
+`initCustomBlock()` posts `ready` to `window.parent` and awaits the host's `init` (theme, context, and `dataSources: { bindings }` keyed by semantic data-source key, which the SDK resolves against the manifest). The promise resolves with the normalized initial state — `await` it before mounting React so hooks always see populated state.
+
+- Default `timeoutMs` is 2000; rejects with `TimeoutError` if the host doesn't respond.
+- In a top-level browser tab (no parent frame), rejects with `NotInIframeError`. `<NotionCustomBlock>` catches this, seeds placeholders, and renders `children` behind a warning banner so dev-time previews still work.
+- After init, `themeChanged`, `contextChanged`, and `dataSourcesChanged` push updates and the relevant hooks re-render.
+- `initCustomBlock` is idempotent; subsequent calls return the same promise.
+
+### Sizing
+
+The host owns width and height. Inside the iframe, `100vh` ≠ a screen and there's no meaningful "device width" — only iframe width. Layouts must reflow from a phone column to a desktop block.
+
+- **Self-sizing content** is the default — `<NotionCustomBlock>` measures `#root` and posts `resize` messages so the iframe tracks your content. Pass `autoResize={false}` for full-bleed views, or to drive `useCustomBlockAutoResize` yourself.
+- Prefer container queries (`@container`) over viewport queries.
+
+### Data sources
+
+A custom block is wired to one or more "data sources" — semantic keys (e.g. `people`, `default`) that map to Notion collections. Read through `useDataSource(key)` and key off the semantic name; never reach into `collectionPointer` / `propertyIdsByKey` directly.
+
+Each row is a `NotionDataSourcePage` of the form `{ id, propertiesById, propertiesByKey, update }`. Read via `propertiesByKey[key]` (semantic) or `propertiesById[propertyId]` (raw). Call `update(input)` to write back through the same data-source mapping; `NotionDataSourcePageUpdateInput` and `NotionDataSourcePageUpdateResult` describe that helper. The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) are always present in `propertiesById` and `collectionSchema.propertiesById`.
+
+### Manifest
+
+A custom view declares its required data sources in `custom_blocks.json` at the project root:
+
+```json
+{
+  "version": 1,
+  "dataSources": {
+    "tasks": {
+      "name": "Tasks",
+      "description": "The collection of tasks to render",
+      "properties": {
+        "title": { "name": "Title", "type": "title" },
+        "dueDate": { "name": "Due date", "type": "date" }
+      }
+    }
+  }
+}
+```
+
+`initCustomBlock()` fetches `custom_blocks.json` and forwards it with `ready`. The `notionCustomBlock()` Vite plugin from `ncblock/vite` serves it in dev and emits it into `dist/` on build. If the file is missing or invalid, the SDK sends `manifest: null`.
+
+### Forbidden APIs
+
+No top-level navigation, `window.open`, or auth redirects. Cross-origin work goes through the host (and is exposed via SDK hooks).
+
+## Hook reference
+
+All hooks assume `initCustomBlock()` has resolved — they throw if called before that. Inside `<NotionCustomBlock>` (or past the `isLoaded` gate of `useCustomBlockInit`), single-value hooks return non-nullable values.
+
+### `<NotionCustomBlock>`
+
+```ts
+type NotionCustomBlockProps = InitCustomBlockOptions & {
+  children: ReactNode;
+  fallback?: ReactNode;
+  errorFallback?: ReactNode | ((error: Error) => ReactNode);
+  autoResize?: boolean; // defaults to true
+};
+```
+
+Top-level wrapper. Runs the handshake, gates `children`, and (by default) drives auto-resize. `fallback` replaces the loading view (default `null`); `errorFallback` replaces the inline `<p role="alert">` shown if init rejects. `timeoutMs` flows through to `initCustomBlock`. Pass `autoResize={false}` for full-bleed views or to call `useCustomBlockAutoResize` yourself.
+
+### `useCustomBlockInit(opts?)`
+
+```ts
+function useCustomBlockInit(opts?: InitCustomBlockOptions): UseCustomBlockInitResult;
+
+type UseCustomBlockInitResult =
+  | { isLoaded: false; error: undefined }
+  | { isLoaded: false; error: Error }
+  | { isLoaded: true;  error: undefined; initial: CustomBlockInitial };
+```
+
+React wrapper around `initCustomBlock` for templates that prefer not to use top-level `await`. Multiple components calling it share the same handshake.
+
+```tsx
+function Root() {
+  const init = useCustomBlockInit();
+  if (init.error) return <p role="alert">Init failed: {init.error.message}</p>;
+  if (!init.isLoaded) return null;
+  return <App />;
+}
+```
+
+### `useCustomBlockContext()`
+
+```ts
+function useCustomBlockContext(): NotionCustomBlockContext;
+```
+
+Returns `{ customBlockId, parent: { id, type }, page: { id, type } }`. Re-renders on `contextChanged` (e.g. the block moves containers).
+
+### `useTheme()`
+
+```ts
+function useTheme(): NotionTheme; // "light" | "dark"
+```
+
+Re-renders on every `themeChanged` message.
+
+### `useDataSourceDefinitions()`
+
+```ts
+function useDataSourceDefinitions(): NotionDataSource[];
+```
+
+Resolved data-source definitions (semantic key plus `collectionPointer`, `collectionSchema`, `propertyIdsByKey`, derived `propertySchemasById`). Most templates use `useDataSource` instead — reach for this hook only when rendering the configuration itself (debug panels, schema-driven UIs).
+
+### `useDataSource(key, initialLimit?)`
+
+```ts
+function useDataSource(key: string, initialLimit?: number): UseDataSourceResult;
+
+type UseDataSourceResult = {
+  items: NotionDataSourcePage[];
+  collectionSchema?: NotionCollectionSchema;
+  propertySchemasById: { [propertyId: string]: NotionPropertySchema };
+  propertySchemasByKey: { [key: string]: NotionPropertySchema | undefined };
+  isLoading: boolean;
+  hasMore: boolean;
+  fetchMore: () => void;
+  error?: string;
+};
+```
+
+Reads the data source mapped to `key`. `initialLimit` defaults to 20. `fetchMore()` re-requests a larger prefix (no cursors yet); page growth tracks `initialLimit`, so pass a larger value to opt into bigger batches. `propertySchemasByKey` is `undefined` for declared-but-unbound slots. The hook resets to `initialLimit` when the underlying definition changes.
+
+### `useCustomBlockAutoResize({ enabled? })`
+
+```ts
+function useCustomBlockAutoResize(args?: { enabled?: boolean }): void;
+```
+
+Measures `#root` with `Math.ceil(scrollHeight)` and posts `resize` messages, deduping unchanged values. `<NotionCustomBlock>` runs this for you — only call it directly when you want to drive `enabled` yourself (e.g. a debug toggle), and pair with `autoResize={false}` so it doesn't run twice.
+
+```tsx
+<NotionCustomBlock autoResize={false}>
+  <App />
+</NotionCustomBlock>;
+
+function App() {
+  const [enabled, setEnabled] = useState(true);
+  useCustomBlockAutoResize({ enabled });
+  return <div>…</div>;
+}
+```
+
+## 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. Trimmed from `templates/radar-chart`:
+
+```tsx
+import {
+  type NotionDataSourcePage,
+  useDataSource,
+} from "ncblock";
+
+const KEY = "people";
+
+function isComplete(item: NotionDataSourcePage): boolean {
+  return (
+    typeof item.propertiesByKey.name === "string" &&
+    typeof item.propertiesByKey.score === "number" &&
+    Number.isFinite(item.propertiesByKey.score)
+  );
+}
+
+export function ScoreList() {
+  const { items, isLoading, hasMore, fetchMore, error } = useDataSource(KEY);
+
+  if (error) return <div role="alert">Couldn't load: {error}</div>;
+  if (isLoading && items.length === 0) return <div>Loading…</div>;
+
+  const ready = items.filter(isComplete);
+  if (ready.length === 0) {
+    return (
+      <div>
+        Map a data source with key <code>{KEY}</code> exposing{" "}
+        <code>name</code> (text) and <code>score</code> (number).
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <ul>
+        {ready.map((item) => (
+          <li key={item.id}>
+            {String(item.propertiesByKey.name)} —{" "}
+            {Number(item.propertiesByKey.score)}
+          </li>
+        ))}
+      </ul>
+      {hasMore ? (
+        <button type="button" onClick={fetchMore} disabled={isLoading}>
+          {isLoading ? "Loading…" : "Load more"}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+```
+
+## `pages` API
+
+```ts
+import { pages } from "ncblock";
+
+await pages.create({ parent, properties, icon?, cover?, position? });
+await pages.get(pageId);
+await pages.update({ pageId, properties?, icon?, cover?, archived? });
+await pages.delete(pageId); // soft-delete (archive); thin wrapper around update
+```
+
+Mirrors the public Notion API. Each call resolves to either `{ status: "success", page }` or `{ status: "error", error }`.
+
+For `pages.create`, `parent` accepts:
+
+```ts
+type CreatePageParent =
+  | { type: "page_id"; page_id: NotionPageId }
+  | { type: "data_source_id"; data_source_id: NotionDataSourceId }
+  | { type: "data_source_key"; key: string };
+```
+
+`type: "data_source_key"` is the recommended form inside a custom view — pass the semantic key (e.g. `"default"`) and the SDK resolves it before sending the request. Page write inputs use `NotionPagePropertyInputMap`: keys may be raw property IDs or data-source property keys, and each `NotionPagePropertyInputValue` may omit `id` because the SDK fills the final raw ID before sending a bridge message.
+
+File upload references aren't enabled for custom blocks yet. For page icons, covers, and file properties, use `external.url` or an existing `file.url`; do not send `{ type: "file_upload", file_upload: { id } }`.
+
+## Types reference
+
+Re-exported from `ncblock`. Hover docs in your editor cover the per-field detail.
+
+- **Init / lifecycle:** `CustomBlockInitial`, `InitCustomBlockOptions`, `UseCustomBlockInitResult`, `NotionCustomBlockProps`.
+- **Context & theme:** `NotionTheme`, `NotionCustomBlockContext`.
+- **Data sources:** `NotionDataSource`, `NotionDataSourcePage`, `NotionDataSourcePageUpdateInput`, `NotionDataSourcePageUpdateResult`, `NotionDataSourceValue`, `NotionCollectionSchema`, `NotionPropertySchema`, `NotionPropertyOption`, `NotionPropertyColor`, `NotionStatusGroup`, `NotionDualProperty`, `UseDataSourceResult`.
+- **Property types:** `NotionPropertyType` / `NOTION_PROPERTY_TYPES` (string-literal union + runtime list), `NotionBuiltinPropertyId` / `NOTION_BUILTIN_PROPERTY_IDS` (the four synthetic IDs).
+- **Manifest:** `CustomBlockManifest`, `ManifestDataSource`, `ManifestProperty`, `ManifestIcon`.
+- **Pages API:** `NotionPage`, `NotionPageCover`, `NotionPageIcon`, `NotionPageParent`, `NotionPagePropertyValue`, `NotionPagePropertyInputValue`, `NotionPagePropertyInputMap`, `NotionPagePropertyWriteMap`, `NotionCreatePagePosition`, `CreatePageInput`, `CreatePageParent`, `CreatePageResult`, `GetPageResult`, `UpdatePageInput`, `UpdatePageResult`.
+- **IDs & pointers:** `NotionRecordPointer`, `NotionPageId`, `NotionDataSourceId`, `NotionSpaceId` (branded strings).
+- **Date/reminder values:** `NotionDate`, `NotionDateRange`, `NotionDateTime`, `NotionDateTimeRange`, `NotionDateValue`, `NotionDateReminder`, `NotionDateTimeReminder`, `NotionTimeReminder`, `NotionNoReminder`.
+
+The bridge speaks a versioned `postMessage` protocol (`CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION`, currently `1`). You shouldn't need to read protocol-level details to build a view — see `CLAUDE.md` if you're extending the SDK itself.

package/dist/bridge/context.d.ts

@@ -0,0 +1,44 @@
+import * as v from "valibot";
+import type { NotionPageId } from "./pages/page";
+/**
+ * Context about the custom block and its location in the block tree.
+ * Delivered as part of the `init` message and then re-sent via `contextChanged`
+ * whenever the host detects a change (e.g. the block moves into a different
+ * container or its enclosing page changes).
+ */
+export declare const notionCustomBlockContextSchema: v.ObjectSchema<{
+    /**
+     * ID of the custom block itself, the one hosting this sandboxed iframe.
+     */
+    readonly customBlockId: v.StringSchema<undefined>;
+    /**
+     * The block that directly parents this custom block.
+     */
+    readonly parent: v.ObjectSchema<{
+        /**
+         * The ID of the block that directly parents this custom block.
+         */
+        readonly id: v.StringSchema<undefined>;
+        /**
+         * The block type of the block that directly parents this custom block. This could be many
+         * different types, including: page, toggle, column, and callout.
+         */
+        readonly type: v.StringSchema<undefined>;
+    }, undefined>;
+    /**
+     * The nearest page ancestor to this custom block.
+     */
+    readonly page: v.ObjectSchema<{
+        /**
+         * The ID of the nearest page ancestor to this custom block.
+         */
+        readonly id: v.StringSchema<undefined>;
+    }, undefined>;
+}, undefined>;
+export type NotionCustomBlockContext = Omit<v.InferOutput<typeof notionCustomBlockContextSchema>, "page"> & {
+    page: {
+        id: NotionPageId;
+    };
+};
+export declare function parseNotionCustomBlockContext(value: unknown): NotionCustomBlockContext | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/bridge/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../bridge/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B;IAC1C;;OAEG;;IAGH;;OAEG;;QAEF;;WAEG;;QAEH;;;WAGG;;;IAIJ;;OAEG;;QAEF;;WAEG;;;aAGH,CAAA;AAEF,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAC1C,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,EACpD,MAAM,CACN,GAAG;IACH,IAAI,EAAE;QACL,EAAE,EAAE,YAAY,CAAA;KAChB,CAAA;CACD,CAAA;AAED,wBAAgB,6BAA6B,CAC5C,KAAK,EAAE,OAAO,GACZ,wBAAwB,GAAG,SAAS,CAKtC"}

package/dist/bridge/context.js

@@ -0,0 +1,42 @@
+import * as v from "valibot";
+/**
+ * Context about the custom block and its location in the block tree.
+ * Delivered as part of the `init` message and then re-sent via `contextChanged`
+ * whenever the host detects a change (e.g. the block moves into a different
+ * container or its enclosing page changes).
+ */
+export const notionCustomBlockContextSchema = v.object({
+    /**
+     * ID of the custom block itself, the one hosting this sandboxed iframe.
+     */
+    customBlockId: v.string(),
+    /**
+     * The block that directly parents this custom block.
+     */
+    parent: v.object({
+        /**
+         * The ID of the block that directly parents this custom block.
+         */
+        id: v.string(),
+        /**
+         * The block type of the block that directly parents this custom block. This could be many
+         * different types, including: page, toggle, column, and callout.
+         */
+        type: v.string(),
+    }),
+    /**
+     * The nearest page ancestor to this custom block.
+     */
+    page: v.object({
+        /**
+         * The ID of the nearest page ancestor to this custom block.
+         */
+        id: v.string(),
+    }),
+});
+export function parseNotionCustomBlockContext(value) {
+    const parsed = v.safeParse(notionCustomBlockContextSchema, value);
+    return parsed.success
+        ? parsed.output
+        : undefined;
+}