ncblock 0.0.2 → 0.0.3

package/README.md

@@ -34,251 +34,21 @@ export function App() {
 
 `<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
+## Reference
 
-### Bridge & lifecycle
+API surface, one page per category. Hover docs in your editor cover the per-field detail; these pages cover usage shape and the gotchas.
 
-`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.
+- [`docs/lifecycle.md`](./docs/lifecycle.md) — `<NotionCustomBlock>`, `useCustomBlockInit`, `initCustomBlock`, `NotInIframeError`, `useCustomBlockAutoResize`. The handshake, the React wrapper, sizing.
+- [`docs/context.md`](./docs/context.md) — `useCustomBlockContext`, `useTheme`. Where the block sits in the document tree and the host's color scheme.
+- [`docs/data-sources.md`](./docs/data-sources.md) — `useDataSource`, `useDataSourceDefinitions`, 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.
+- [`docs/manifest.md`](./docs/manifest.md) — `custom_blocks.json`, the Vite plugin, manifest types.
 
-- 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.
+## Forbidden APIs
 
-### Sizing
+No top-level navigation, `window.open`, or auth redirects. No direct network requests — cross-origin work goes through the host (and is exposed via SDK hooks).
 
-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.
+## Bridge protocol
 
-- **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.
+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. If you're extending the SDK itself or implementing a host, see `HOST.md` and the repo-root `CLAUDE.md`.

package/dist/bridge/SandboxBridge.d.ts

@@ -0,0 +1,64 @@
+import type { CreatePageInput, CreatePageResult, GetPageResult, GetUserResult, ListUsersInput, ListUsersResult, NotionPageId, NotionUserId, UpdatePageInput, UpdatePageResult } from "../types";
+import type { NotionDataSource } from "./dataSources/dataSource";
+import type { NotionDataSourcePageUpdateInput, NotionDataSourcePageUpdateResult } from "./dataSources/dataSourcePage";
+import { type CustomBlockHostState } from "./hostState";
+import type { CustomBlockManifest } from "./manifest";
+import type { InitMessage } from "./messages/init";
+/**
+ * Used to ensure that the host and client are using the same version of the bridge protocol. A
+ * single host needs to support multiple custom blocks built with different versions of the bridge
+ * protocol. Increment this number any time a breaking change is made to the bridge protocol.
+ */
+export declare const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 1;
+export declare class SandboxBridge {
+    private hostState;
+    private listeners;
+    private nextRequestId;
+    private readonly pendingCreatePage;
+    private readonly pendingGetPage;
+    private readonly pendingGetUser;
+    private readonly pendingListUsers;
+    private readonly pendingUpdatePage;
+    private resolveInit;
+    private readonly initMessage;
+    private manifest;
+    constructor();
+    awaitInit(signal?: AbortSignal): Promise<InitMessage>;
+    sendReady(manifest: CustomBlockManifest | null): void;
+    private notify;
+    private handleMessage;
+    subscribe(listener: () => void): () => boolean;
+    getHostState(): CustomBlockHostState;
+    /**
+     * Apply an `init` payload as if it had arrived from the host. Lets callers
+     * seed the bridge directly (e.g. the React provider's standalone preview
+     * fallback) without going through `postMessage`. The bridge stays unaware
+     * of why it's being seeded.
+     */
+    setMockState(message: InitMessage): void;
+    private applyInit;
+    queryDataSource(key: string, limit: number): void;
+    postResize(height: number): void;
+    createPage(input: CreatePageInput): Promise<CreatePageResult>;
+    getPage(pageId: NotionPageId): Promise<GetPageResult>;
+    getUser(userId: NotionUserId): Promise<GetUserResult>;
+    listUsers(input?: ListUsersInput): Promise<ListUsersResult>;
+    updatePage(input: UpdatePageInput): Promise<UpdatePageResult>;
+    /**
+     * Updates a page on a known data source, resolving any property keys against the data source's
+     * `propertyIdsByKey` before sending the bridge message. Used by the per-row `update` callback
+     * returned from {@link getDataSourceQueryView}.
+     */
+    updateDataSourcePage(args: {
+        dataSource: NotionDataSource;
+        pageId: NotionPageId;
+        input: NotionDataSourcePageUpdateInput;
+    }): Promise<NotionDataSourcePageUpdateResult>;
+    /**
+     * Translates the public `CreatePageInput["parent"]` into the bridge-native
+     * `CreatePageMessageParent`. The `data_source_key` variant is resolved sandbox-side against
+     * the data source mapping the host delivered in `init` / `dataSourcesChanged`.
+     */
+    private resolveCreatePageParent;
+}
+//# sourceMappingURL=SandboxBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxBridge.d.ts","sourceRoot":"","sources":["../../bridge/SandboxBridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,EACd,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,MAAM,UAAU,CAAA;AAGjB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,KAAK,EACX,+BAA+B,EAC/B,gCAAgC,EAChC,MAAM,8BAA8B,CAAA;AAGrC,OAAO,EACN,KAAK,oBAAoB,EAGzB,MAAM,aAAa,CAAA;AAEpB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAOrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAUlD;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,IAAI,CAAA;AAErD,qBAAa,aAAa;IACzB,OAAO,CAAC,SAAS,CAGhB;IACD,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAEjC;IACD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAE9B;IACD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAE9B;IACD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAEhC;IACD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAEjC;IACD,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAE1B;IACF,OAAO,CAAC,QAAQ,CAAmC;;IAWnD,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAwBrD,SAAS,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAc9C,OAAO,CAAC,MAAM,CAIb;IAED,OAAO,CAAC,aAAa,CAwMpB;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI;IAK9B,YAAY,IAAI,oBAAoB;IAIpC;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,WAAW;IAIjC,OAAO,CAAC,SAAS;IAsBjB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAuC1C,UAAU,CAAC,MAAM,EAAE,MAAM;IAczB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqC7D,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAarD,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAarD,SAAS,CAAC,KAAK,GAAE,cAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAc/D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwC7D;;;;OAIG;IACH,oBAAoB,CAAC,IAAI,EAAE;QAC1B,UAAU,EAAE,gBAAgB,CAAA;QAC5B,MAAM,EAAE,YAAY,CAAA;QACpB,KAAK,EAAE,+BAA+B,CAAA;KACtC,GAAG,OAAO,CAAC,gCAAgC,CAAC;IAuB7C;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;CAsD/B"}