npm - @notionhq/custom-blocks-dev-shell - Versions diffs - 0.1.1 → 0.1.3 - Mend

@notionhq/custom-blocks-dev-shell 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +10 -0
package/dist/assets/{index-DvRqSoqY.css → index-CzXh8_H1.css} +1 -1
package/dist/assets/index-a8PSkfam.js +9 -0
package/dist/index.html +2 -2
package/dist-cli/data-sources.js +106 -0
package/dist-cli/main.js +14 -0
package/dist-cli/materialize.js +104 -0
package/dist-cli/worker-manifest.js +3 -1
package/docs/data-sources.md +88 -0
package/package.json +4 -2
package/dist/assets/index-xG6RNJPx.js +0 -9

package/dist/index.html CHANGED Viewed

@@ -4,8 +4,8 @@
 		<meta charset="UTF-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<title>Workers local shell</title>
-		<script type="module" crossorigin src="/assets/index-xG6RNJPx.js"></script>
-		<link rel="stylesheet" crossorigin href="/assets/index-DvRqSoqY.css">
+		<script type="module" crossorigin src="/assets/index-a8PSkfam.js"></script>
+		<link rel="stylesheet" crossorigin href="/assets/index-CzXh8_H1.css">
 	</head>
 	<body>
 		<div id="root"></div>

package/dist-cli/data-sources.js ADDED Viewed

@@ -0,0 +1,106 @@
+/**
+ * Load a worker's dev-shell data sources from `<dataDir>/*.json` — one source
+ * per file, hand-authored. Every file is validated here, before it reaches
+ * the shell, so a malformed source fails spin-up naming the file and the
+ * problem instead of breaking the UI.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import * as v from "valibot";
+const DEV_SHELL_DATA_SOURCE_TYPES = [
+    "built-in",
+    "worker",
+    "manual",
+    "syncedFromProd",
+];
+// Local copy of the SDK's NOTION_PROPERTY_TYPES: the compiled CLI runs under
+// plain node, which can't import the SDK's published TS source at runtime.
+// The `satisfies` below plus the type-only import keep the two lists locked
+// together — a drift on either side fails typecheck.
+const NOTION_PROPERTY_TYPES = [
+    "title",
+    "rich_text",
+    "number",
+    "checkbox",
+    "url",
+    "email",
+    "phone_number",
+    "select",
+    "multi_select",
+    "status",
+    "date",
+    "people",
+    "files",
+    "unique_id",
+    "relation",
+    "place",
+    "formula",
+    "rollup",
+    "button",
+    "verification",
+    "last_visited_time",
+    "location",
+    "created_time",
+    "last_edited_time",
+    "created_by",
+    "last_edited_by",
+];
+const _allPropertyTypesListed = true;
+void _allPropertyTypesListed;
+export function readDataSources(dataDir) {
+    if (!existsSync(dataDir)) {
+        return [];
+    }
+    return readdirSync(dataDir)
+        .filter(name => name.endsWith(".json"))
+        .map(name => readSource(resolve(dataDir, name)))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+const nonEmptyString = v.pipe(v.string(), v.nonEmpty());
+const sourceFileSchema = v.object({
+    type: v.optional(v.literal("worker"), "worker"),
+    key: v.optional(nonEmptyString),
+    name: v.optional(nonEmptyString),
+    icon: v.optional(v.string()),
+    schema: v.optional(v.record(v.string(), v.object({
+        name: v.optional(v.string()),
+        type: v.picklist(NOTION_PROPERTY_TYPES),
+    })), {}),
+    rows: v.optional(v.array(v.looseObject({ id: nonEmptyString })), []),
+});
+/**
+ * Parse and validate one source file. Structural mistakes throw with the file
+ * and problem named; omitted `key`/`name` fall back to the filename, and
+ * omitted `schema`/`rows` to empty — so the minimal valid file is `{}`.
+ */
+function readSource(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch (error) {
+        throw new Error(`${file}: not valid JSON — ${error.message}`);
+    }
+    if (Array.isArray(parsed)) {
+        throw new Error(`${file}: must be a JSON object`);
+    }
+    const result = v.safeParse(sourceFileSchema, parsed);
+    if (!result.success) {
+        const issue = result.issues[0];
+        const path = v.getDotPath(issue);
+        throw new Error(`${file}: ${path ? `${path}: ` : ""}${issue.message}`);
+    }
+    const { type, icon, schema, rows } = result.output;
+    const key = result.output.key ?? basename(file, ".json");
+    return {
+        type,
+        key,
+        name: result.output.name ?? key,
+        ...(icon !== undefined ? { icon } : {}),
+        schema: Object.fromEntries(Object.entries(schema).map(([propertyKey, property]) => [
+            propertyKey,
+            { name: property.name ?? propertyKey, type: property.type },
+        ])),
+        rows,
+    };
+}

package/dist-cli/main.js CHANGED Viewed

@@ -11,6 +11,8 @@ import { createRequire } from "node:module";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { BLOCK_BASE_PORT, buildBlockRegistry, SHELL_2_PORT, writeBlockViteConfig, } from "./block-server.js";
+import { readDataSources } from "./data-sources.js";
+import { materializeWorkerSchemaDataSources } from "./materialize.js";
 import { serveUi } from "./serve-ui.js";
 import { blockCapabilities, findWorkerDir, generateWorkerManifest, } from "./worker-manifest.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -114,6 +116,17 @@ async function main() {
         // Not an error — start the shell anyway; it shows "None" under Blocks.
         console.log(`${label(basename(workerDir))} Worker declares no custom blocks.`);
     }
+    // Materialize schema-only files for the worker's declared sources, then
+    // load the directory. Files are validated before injection; a malformed
+    // file fails spin-up with the problem named.
+    materializeWorkerSchemaDataSources(manifest, resolve(workerDir, "src/data"));
+    const dataSources = readDataSources(resolve(workerDir, "src/data"));
+    console.log(dataSources.length > 0
+        ? `${label(basename(workerDir))} Data sources from src/data: ${dataSources
+            .map(source => source.name)
+            .join(", ")}`
+        : `${label(basename(workerDir))} No data sources — create src/data/<key>.json files ` +
+            `(format: node_modules/@notionhq/custom-blocks-dev-shell/docs/data-sources.md).`);
     if (blocks.length > 0 &&
         cliArgs.shellPort >= cliArgs.blockBasePort &&
         cliArgs.shellPort < cliArgs.blockBasePort + blocks.length) {
@@ -161,6 +174,7 @@ async function main() {
         await serveUi(distDir, cliArgs.shellPort, {
             mode: "worker",
             blocks: registry,
+            dataSources,
         });
     }
     catch (error) {

package/dist-cli/materialize.js ADDED Viewed

@@ -0,0 +1,104 @@
+/**
+ * Materialize a worker's declared data sources as `<dataDir>/worker_<key>.json`
+ * files: the schema with no rows, mirroring a managed database before any
+ * sync. Rows are added by editing the file; `data-sources.ts` reads and
+ * validates whatever ends up in the directory.
+ *
+ * A block's data source can come from a `worker.database` or from an inline
+ * schema declared on the block (`worker.customBlock({ dataSources })`); both
+ * are materialized so all sources are treated equivalently — just files in
+ * `src/data/`. The `worker_` prefix keeps generated sources from ever colliding
+ * with hand-authored files, so both can coexist.
+ *
+ * Files are written only when absent, so hand-edited or hand-authored sources
+ * survive across restarts; delete a file to regenerate it from the schema.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { blockCapabilities } from "./worker-manifest.js";
+// Worker authoring type names → public data-source (NotionPropertyType) names.
+const TYPE_ALIASES = {
+    text: "rich_text",
+    file: "files",
+};
+/**
+ * Generated files are namespaced so they never shadow authored files. The
+ * filename and `key` carry the prefix — keys must stay unique for bindings to
+ * be unambiguous — while the display name stays as declared, so the sidebar
+ * shows the clean name.
+ */
+const GENERATED_PREFIX = "worker_";
+export function materializeWorkerSchemaDataSources(manifest, dataDir) {
+    mkdirSync(dataDir, { recursive: true });
+    // One descriptor per data source key: databases first (source of truth for
+    // anything they back), then inline block schemas for keys no database
+    // provides.
+    const descriptors = new Map();
+    for (const database of manifest.databases) {
+        descriptors.set(database.key, {
+            name: database.config.initialTitle ?? database.key,
+            properties: (database.config.schema?.properties ?? {}),
+        });
+    }
+    for (const block of blockCapabilities(manifest)) {
+        for (const [key, slot] of Object.entries(block.config.manifest.dataSources)) {
+            const properties = (slot.properties ?? {});
+            const existing = descriptors.get(key);
+            if (existing !== undefined) {
+                // Same key from two blocks with different shapes: slot keys are only
+                // unique per block, so one file can't serve both. First block wins;
+                // say so instead of leaving the loser silently unbindable.
+                if (existing.blockKey !== undefined &&
+                    !samePropertySchemas(existing.properties, properties)) {
+                    console.warn(`Blocks "${existing.blockKey}" and "${block.key}" both declare data source ` +
+                        `"${key}" with different schemas; ${GENERATED_PREFIX}${key}.json uses the ` +
+                        `schema from "${existing.blockKey}". Author a src/data file for "${block.key}" by hand.`);
+                }
+                continue;
+            }
+            descriptors.set(key, {
+                name: slot.name ?? key,
+                properties,
+                blockKey: block.key,
+            });
+        }
+    }
+    for (const [key, descriptor] of descriptors) {
+        // The key is the worker's contract and lands verbatim in the file's
+        // `key`; the filename is ours, so path-hostile characters (`/`, `..`)
+        // are encoded rather than allowed to leave `dataDir` or crash the write.
+        const file = resolve(dataDir, `${GENERATED_PREFIX}${fileSafe(key)}.json`);
+        if (existsSync(file)) {
+            continue;
+        }
+        writeFileSync(file, `${JSON.stringify(buildSource(key, descriptor), null, 2)}\n`);
+    }
+}
+function fileSafe(key) {
+    return key.replace(/[^a-zA-Z0-9_-]/g, "-");
+}
+function samePropertySchemas(left, right) {
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return (leftKeys.length === rightKeys.length &&
+        leftKeys.every((key, index) => key === rightKeys[index] &&
+            left[key].type === right[key].type &&
+            (left[key].name ?? key) === (right[key].name ?? key)));
+}
+function buildSource(key, descriptor) {
+    const { name, properties } = descriptor;
+    const schema = {};
+    for (const [propertyKey, property] of Object.entries(properties)) {
+        schema[propertyKey] = {
+            name: property.name ?? propertyKey,
+            type: TYPE_ALIASES[property.type] ?? property.type,
+        };
+    }
+    return {
+        type: "worker",
+        key: `${GENERATED_PREFIX}${key}`,
+        name,
+        schema,
+        rows: [],
+    };
+}

package/dist-cli/worker-manifest.js CHANGED Viewed

@@ -96,7 +96,9 @@ export async function extractWorkerManifest(workerDir, options = {}) {
     // (per the localhost verification doc's `w.manifest || w.capabilities`).
     const raw = worker.manifest ?? worker.capabilities;
     if (isManifestShape(raw)) {
-        return raw;
+        // The shape check only guarantees `capabilities`; older manifests omit
+        // the other arrays.
+        return { ...raw, databases: raw.databases ?? [], pacers: raw.pacers ?? [] };
     }
     if (Array.isArray(raw)) {
         return { databases: [], pacers: [], capabilities: raw };

package/docs/data-sources.md ADDED Viewed

@@ -0,0 +1,88 @@
+# Dev-shell data sources
+Data sources come in kinds, marked by their `type`, and all live in the
+worker's `src/data/*.json` — one source per file, read at spin-up. The shell
+supports the following types today:
+- `worker` — hand-authored JSON files. This is how you give your blocks data,
+  and what this document describes.
+- `manual` — sources a user creates themselves in the shell.
+- `built-in` — sources we provide.
+## File format
+```json
+{
+	"type": "worker",
+	"key": "tasks",
+	"name": "Tasks",
+	"icon": "✅",
+	"schema": {
+		"title": { "name": "Title", "type": "title" },
+		"status": { "name": "Status", "type": "select" },
+		"dueDate": { "name": "Due date", "type": "date" },
+		"done": { "name": "Done", "type": "checkbox" }
+	},
+	"rows": [
+		{
+			"id": "tasks-1",
+			"title": "Ship the block",
+			"status": "In progress",
+			"dueDate": { "type": "date", "start_date": "2026-08-01" },
+			"done": false
+		}
+	]
+}
+```
+- `type` — the source's kind; `"worker"`, the only kind these files can
+  declare today, is the default.
+- `key` — what blocks bind against; make it match a `dataSources` key from
+  `worker.customBlock(...)` so properties auto-match. Defaults to the
+  filename.
+- `name` — the label shown in the shell sidebar. Defaults to `key`.
+- `icon` — optional emoji shown alongside the name.
+- `schema` — property key → `{ name, type }`. Use the same property keys and
+  types the block declares. Types: `title`, `rich_text`, `number`, `select`,
+  `multi_select`, `status`, `date`, `checkbox`, `url`, `email`,
+  `phone_number`, `people`, `files`, `relation`.
+- `rows` — each row needs a unique string `id`; property values live under
+  their schema keys.
+Value shapes by property type:
+| Type | Value |
+| --- | --- |
+| `title`, `rich_text`, `select`, `status`, `url`, `email`, `phone_number` | string |
+| `multi_select` | array of strings |
+| `number` | number |
+| `checkbox` | boolean |
+| `date` | `{ "type": "date", "start_date": "YYYY-MM-DD" }`; ranges and datetimes use `"daterange"` / `"datetime"` / `"datetimerange"` with `end_date`, `start_time`, `end_time` |
+| `people` | array of `{ "id": "...", "table": "notion_user" }` pointers |
+| `relation` | array of `{ "id": "...", "table": "block" }` pointers |
+| `files` | string (the host serializes file properties as text today) |
+## Validation
+Files are validated at spin-up, before they reach the shell UI. A malformed
+file fails the run with the file and problem named, e.g.
+`src/data/tasks.json: rows.0.id: Invalid key: Expected "id" but received undefined`.
+Omitted `key`/`name` fall back to the filename; omitted `schema`/`rows` to
+empty.
+## Materialization
+You don't have to write these files from scratch. At spin-up the shell
+materializes a file for every data source the worker declares — both
+`worker.database(...)` entries and inline `worker.customBlock({ dataSources })`
+schemas — that doesn't already have one: `worker_<key>.json`, the declared
+schema with empty `rows`, mirroring a managed database before any sync.
+- The `worker_` prefix on the filename and `key` namespaces generated files
+  away from ones you author yourself, so both coexist; the display `name`
+  stays as declared, so the sidebar shows the clean name.
+- Files are only ever written when absent: fill in `rows` freely and your
+  edits survive restarts. Delete a generated file to regenerate it from the
+  schema.
+The shell shows exactly the sources in `src/data/`, nothing else.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-dev-shell",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local preview shell for Notion custom block workers.",
   "license": "MIT",
   "repository": {
@@ -19,12 +19,14 @@
     "bin",
     "dist",
     "dist-cli",
+    "docs",
     "README.md"
   ],
   "dependencies": {
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "@notionhq/custom-blocks": "0.1.0"
+    "valibot": "^1.3.1",
+    "@notionhq/custom-blocks": "0.1.1"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.2.4",