ncblock 0.0.4 → 0.0.6

package/docs/data-sources.md

@@ -0,0 +1,161 @@
+# Data sources
+
+A custom block declares its **data sources** — semantic keys like `people` or `tasks` — in `custom_blocks.json`. When the block is added to a Notion page, a user maps each key to a real Notion database. Inside the block, you read by the semantic key and the SDK handles the lookup for you. Use `useDataSource(key)` for the rows themselves, and `useDataSourceDefinitions()` when you need the schema (debug panels, schema-driven UIs).
+
+## Pages within a data source
+
+Each row returned by `useDataSource` is a `NotionDataSourcePage` — `{ id, propertiesById, propertiesByKey, update }`. Read property values through either of the two views:
+
+- `propertiesByKey[key]` — keyed by the semantic property keys you declared in the manifest.
+- `propertiesById[propertyId]` — keyed by the raw Notion property ID.
+
+The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) are always present in `propertiesById` (and `collectionSchema.propertiesById`), never in the `*ByKey` views — they don't have semantic keys.
+
+### Updating a row
+
+Each page carries its own `update` helper:
+
+```ts
+await row.update({
+  properties: {
+    score: { type: "number", number: 8 }, // semantic key
+  },
+  icon: { type: "emoji", emoji: "✅" },
+});
+```
+
+Because the helper is bound to its data source, you can write property values keyed by **either** semantic keys or raw IDs — the SDK resolves them before sending the request. The input and result shapes are `NotionDataSourcePageUpdateInput` and `NotionDataSourcePageUpdateResult`.
+
+Use `row.update(...)` whenever you already have a row in hand. For pages you don't have a row for (e.g. you only have a `pageId`), drop down to the top-level [`pages` API](./pages.md) — it covers create / get / update / delete and accepts raw property IDs only.
+
+## API
+
+### `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.
+
+### `useDataSourceDefinitions()`
+
+```ts
+function useDataSourceDefinitions(): NotionDataSource[];
+```
+
+Resolved data-source definitions (semantic key plus `collectionSchema`, `propertyIdsByKey`, derived `propertySchemasById`). Most templates use `useDataSource` instead — reach for this hook only when rendering the configuration itself (debug panels, schema-driven UIs).
+
+## 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>
+  );
+}
+```
+
+## Types
+
+### Rows & values
+
+- `NotionDataSource` — a resolved data source: semantic key, `collectionSchema`, `propertyIdsByKey`, `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.
+- `NotionDataSourcePageUpdateInput` / `NotionDataSourcePageUpdateResult` — input and result for the per-page `update` helper.
+
+### Property schemas
+
+- `NotionPropertySchema` — schema for a single property (type plus type-specific config like `select` options).
+- `NotionPropertyType` — string-literal union of every supported property type.
+- `NOTION_PROPERTY_TYPES` — runtime list of those literals (handy for switch coverage and validation).
+- `NotionPropertyOption` — a single `select` / `multi_select` / `status` option (`{ id, name, color }`).
+- `NotionPropertyColor` — the color literal used by options and groups.
+- `NotionStatusGroup` — the `status` property's "To do / In progress / Done" grouping.
+- `NotionDualProperty` — properties that have both a primary and a secondary axis (e.g. `unique_id` prefix + number).
+- `NotionBuiltinPropertyId` — string-literal union of the four synthetic property IDs (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`).
+- `NOTION_BUILTIN_PROPERTY_IDS` — runtime list of the four built-in IDs.
+
+### Collection schema & pointers
+
+- `NotionCollectionSchema` — host-supplied schema for the bound collection, including raw property schemas.
+- `NotionRecordPointer` — `{ id, table }`. Generic reference to any Notion record (page, block, collection row). Exported for convenience; `useDataSource` and the `pages` API don't take one as input.
+
+### IDs
+
+Branded string types — they're plain strings at runtime but TypeScript distinguishes them.
+
+- `NotionDataSourceId`
+- `NotionSpaceId`
+
+### Date values
+
+Returned wherever a date / date-range value appears (e.g. inside `propertiesByKey` for a `date` property). All-day values use `NotionDate*` shapes; values with a time component use `NotionDateTime*`.
+
+- `NotionDateValue` — discriminated union covering every date-shaped value below.
+- `NotionDate`
+- `NotionDateRange`
+- `NotionDateTime`
+- `NotionDateTimeRange`
+- `NotionDateReminder`
+- `NotionDateTimeReminder`
+- `NotionTimeReminder`
+- `NotionNoReminder`

package/docs/lifecycle.md

@@ -0,0 +1,92 @@
+# Lifecycle
+
+The SDK ↔ host handshake, the React wrapper that runs it, and the auto-resize hook that keeps the iframe in sync with your content.
+
+## Handshake
+
+`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, captured in `CustomBlockInitial` — `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.
+
+## API
+
+All hooks below 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 />;
+}
+```
+
+### `initCustomBlock(opts?)`
+
+```ts
+function initCustomBlock(opts?: InitCustomBlockOptions): Promise<CustomBlockInitial>;
+
+type InitCustomBlockOptions = { timeoutMs?: number };
+```
+
+The lower-level promise API. `<NotionCustomBlock>` and `useCustomBlockInit` both call it for you. Reach for it directly only when you want to `await` init at module scope (e.g. before `ReactDOM.createRoot`).
+
+### `NotInIframeError`
+
+Thrown when `initCustomBlock` is called in a top-level tab (no parent frame). `<NotionCustomBlock>` catches it and falls back to a standalone preview with a warning banner; direct callers can `instanceof NotInIframeError` to apply their own policy.
+
+### `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>;
+}
+```

package/docs/manifest.md

@@ -0,0 +1,42 @@
+# Manifest
+
+A custom view declares its required data sources in `custom_blocks.json` at the project root. Notion uses the manifest to know what semantic keys the block expects, what shape each property should be, and what to show when an admin is configuring the block.
+
+```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`.
+
+## Vite plugin
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { notionCustomBlock } from "ncblock/vite";
+
+export default defineConfig({
+  plugins: [react(), notionCustomBlock()],
+});
+```
+
+In dev, the plugin serves `custom_blocks.json` from the project root so HMR + the SDK handshake see the same file. On `vite build`, it emits `custom_blocks.json` into `dist/` as a separate asset alongside the bundled HTML and JS.
+
+## Types
+
+- `CustomBlockManifest` — the parsed shape of `custom_blocks.json`.
+- `ManifestDataSource` — a single entry in `dataSources` (name, description, properties).
+- `ManifestProperty` — a single property declaration inside a `ManifestDataSource`.
+- `ManifestIcon` — the icon variant accepted on a `ManifestDataSource`.

package/docs/pages.md

@@ -0,0 +1,143 @@
+# `pages` API
+
+Helpers for creating, reading, updating, and archiving Notion pages from inside a custom block. The SDK forwards each call to Notion on your behalf.
+
+```ts
+import { pages } from "ncblock";
+```
+
+Every helper returns a discriminated result instead of throwing:
+
+```ts
+const result = await pages.get(pageId);
+if (result.status === "success") {
+  // result.page is a NotionPage
+} else {
+  // result.error is a human-readable string
+}
+```
+
+Always check `result.status` before reading `result.page`.
+
+## Creating pages
+
+`pages.create` mirrors Notion's [`POST /v1/pages`](https://developers.notion.com/reference/post-page). Pass a parent, a property map, and (optionally) an `icon`, `cover`, or `position`:
+
+```ts
+const result = await pages.create({
+  parent: { type: "data_source_key", key: "tasks" },
+  properties: {
+    title: {
+      type: "title",
+      title: [{ type: "text", text: { content: "New task" } }],
+    },
+    dueDate: { type: "date", date: { start: "2026-06-01" } },
+  },
+  icon: { type: "emoji", emoji: "📝" },
+  position: { type: "end" },
+});
+
+if (result.status === "success") {
+  console.log("created", result.page.id);
+}
+```
+
+### Choosing a parent
+
+`parent` is a `CreatePageParent`:
+
+```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 you declared in `custom_blocks.json` (e.g. `"tasks"`) and the SDK looks up the corresponding data source for you. The other two variants exist for the rarer case where you already have a raw Notion ID in hand.
+
+### Property keys
+
+`properties` is a `NotionPagePropertyInputMap`. Two niceties versus the raw API:
+
+- **Keys** can be either raw Notion property IDs _or_ the data-source property keys you declared in the manifest. The SDK resolves keys → IDs before forwarding the request.
+- **Values** (`NotionPagePropertyInputValue`) may omit `id` — the SDK fills in the final raw ID for you.
+
+So if your manifest declares `title` and `dueDate`, you can write them by name (as in the example above) instead of looking up the raw IDs.
+
+### Where the new page lands
+
+`position` is a `NotionCreatePagePosition` and controls placement inside the parent:
+
+- `{ type: "start" }` / `{ type: "end" }` — prepend or append (default).
+- `{ type: "before", blockId }` / `{ type: "after", blockId }` — insert as a sibling of the given block (which can be nested anywhere under the parent).
+
+## Reading pages
+
+`pages.get(pageId)` fetches a single page by ID:
+
+```ts
+const result = await pages.get(pageId);
+if (result.status === "error") return;
+
+const page = result.page; // NotionPage
+console.log(page.properties);
+```
+
+`page` mirrors Notion's public API shape, with `id`, `parent`, `properties`, optional `icon` / `cover`, etc. — see `NotionPage` in the types list below.
+
+## Updating pages
+
+`pages.update` writes back to a page. The optional fields (`properties`, `icon`, `cover`, `archived`) are independent — supply only what you want to change:
+
+```ts
+const result = await pages.update({
+  pageId,
+  properties: {
+    "%5C%3FX%3D": {
+      id: "%5C%3FX%3D",
+      type: "checkbox",
+      checkbox: true,
+    },
+  },
+  icon: { type: "emoji", emoji: "✅" },
+});
+```
+
+The `properties` map (a `NotionPagePropertyWriteMap`) is keyed by **raw Notion property ID**, and each value must repeat that ID as its own `id` field — semantic data-source keys aren't accepted here. To update a row by configured custom-block key without writing out the raw IDs, use the `update` helper on the row returned from `useDataSource` instead; the SDK handles the key → ID resolution for you.
+
+If you call `pages.update` with no fields to change, it short-circuits and resolves with `{ status: "error", error: "updatePage requires at least one of: properties, icon, cover, archived." }` — no request is sent.
+
+## Deleting (archiving) pages
+
+`pages.delete(pageId)` is a thin wrapper around `pages.update({ pageId, archived: true })`. Notion treats archive and trash the same way for pages:
+
+```ts
+await pages.delete(pageId);
+```
+
+To restore a page, call `pages.update({ pageId, archived: false })`.
+
+## Icons, covers, and file uploads
+
+File-upload references aren't enabled for custom blocks yet. For icons, covers, and file properties, use one of:
+
+- An emoji icon — `{ type: "emoji", emoji: "🟢" }`
+- An external URL — `{ type: "external", external: { url: "https://example.com/cover.png" } }`
+- An existing hosted file URL returned by Notion — `{ type: "file", file: { url: existingUrl } }`
+
+Do **not** send `{ type: "file_upload", file_upload: { id } }`; the host will reject it.
+
+## Types
+
+- `NotionPage` — the page record returned by every successful call.
+- `NotionPageId` — branded string ID for a page.
+- `NotionPageIcon` / `NotionPageCover` — icon and cover variants Notion supports.
+- `NotionPageParent` — the page's parent reference as returned by the API.
+- `NotionPagePropertyValue` — a single property value as returned on a `NotionPage`.
+- `NotionPagePropertyInputValue` — a single property value as accepted by `pages.create` / `pages.update` (may omit `id` for `create`).
+- `NotionPagePropertyInputMap` — input map for `pages.create` (keys can be raw property IDs or semantic keys).
+- `NotionPagePropertyWriteMap` — input map for `pages.update` (raw property IDs only).
+- `NotionCreatePagePosition` — `start` / `end` / `before` / `after` insertion variants.
+- `CreatePageInput` / `CreatePageParent` / `CreatePageResult`.
+- `GetPageResult`.
+- `UpdatePageInput` / `UpdatePageResult`.

package/docs/users.md

@@ -0,0 +1,61 @@
+# `users` API
+
+Helpers for reading workspace users from inside a custom block. The SDK forwards each call to Notion on your behalf.
+
+```ts
+import { users, type NotionUserId } from "ncblock"
+```
+
+Every helper returns a discriminated result instead of throwing:
+
+```ts
+const result = await users.get(userId)
+if (result.status === "success") {
+	// result.user is a NotionUser
+} else {
+	// result.error is a human-readable string
+}
+```
+
+Always check `result.status` before reading `result.user` / `result.list`.
+
+## Listing users
+
+`users.list(input?)` returns workspace users visible to the current custom block, mirroring Notion's [`GET /v1/users`](https://developers.notion.com/reference/get-users) shape.
+
+```ts
+const result = await users.list({ pageSize: 50 })
+if (result.status === "error") return
+
+for (const user of result.list.results) {
+	console.log(user.id, user.name, user.person.email)
+}
+
+if (result.list.has_more && result.list.next_cursor) {
+	const next = await users.list({ startCursor: result.list.next_cursor })
+	// ...
+}
+```
+
+`ListUsersInput` accepts `pageSize` and `startCursor`; both are optional. `ListUsersResult` resolves to either `{ status: "success", list }` or `{ status: "error", error }`, where `list` is a `NotionUserList` (with `results`, `next_cursor`, `has_more`).
+
+## Reading a single user
+
+`users.get(userId)` fetches one `NotionUser` by `NotionUserId`:
+
+```ts
+const result = await users.get(userId)
+if (result.status === "success") {
+	console.log(result.user.name)
+}
+```
+
+`GetUserResult` follows the same success/error shape and returns `{ status: "success", user }` when the host resolves the user.
+
+## Types
+
+- `NotionUser` — the user record returned by `users.get` and inside `NotionUserList.results`.
+- `NotionUserId` — branded string ID for a user.
+- `NotionUserList` — paginated list shape returned by `users.list`.
+- `ListUsersInput` / `ListUsersResult`.
+- `GetUserResult`.

package/package.json

@@ -1,30 +1,33 @@
 {
 	"name": "ncblock",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"exports": {
 		".": {
-			"import": "./dist/./index.js",
-			"types": "./dist/./index.d.ts"
+			"import": "././dist/index.js",
+			"types": "././dist/index.d.ts"
 		},
 		"./host": {
-			"import": "./dist/./host.js",
-			"types": "./dist/./host.d.ts"
+			"import": "././dist/host.js",
+			"types": "././dist/host.d.ts"
 		},
 		"./vite": {
-			"import": "./dist/./vite-plugin/index.js",
-			"types": "./dist/./vite-plugin/index.d.d.ts"
+			"import": "./vite-plugin/index.js",
+			"types": "./vite-plugin/index.d.ts"
 		}
 	},
 	"scripts": {
 		"test": "vitest run --environment jsdom"
 	},
 	"files": [
-		"dist",
-		"README.md"
+		"src",
+		"HOST.md",
+		"docs",
+		"vite-plugin",
+		"dist"
 	],
 	"peerDependencies": {
 		"react": "^19.2.5"