npm - @notionhq/custom-blocks-dev-shell - Versions diffs - 0.1.65 → 0.1.67 - Mend

@notionhq/custom-blocks-dev-shell 0.1.65 → 0.1.67

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 (16) hide show

package/README.md +3 -0
package/data/people.json +0 -1
package/data/radar.json +0 -1
package/data/tasks.json +0 -1
package/dist/assets/{index-BtBedBtp.js → index-jvcNWLYF.js} +3 -3
package/dist/index.html +1 -1
package/dist-cli/convert.js +3 -10
package/dist-cli/data-sources.js +3 -5
package/dist-cli/dev-shell-launcher.js +14 -1
package/dist-cli/materialize.js +4 -8
package/dist-cli/prebuilt.js +2 -5
package/dist-cli/resolve-bindings.js +39 -0
package/dist-cli/source-bindings.js +17 -0
package/docs/bindings.md +43 -19
package/docs/data-sources.md +29 -11
package/package.json +1 -1

package/dist/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
 		<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-BtBedBtp.js"></script>
+		<script type="module" crossorigin src="/assets/index-jvcNWLYF.js"></script>
 		<link rel="stylesheet" crossorigin href="/assets/index-BOt07-3a.css">
 	</head>
 	<body>

package/dist-cli/convert.js CHANGED Viewed

@@ -17,11 +17,10 @@ const UNSUPPORTED_TYPE_FALLBACK = "rich_text";
 export function parseConvertArgs(argv) {
     const args = {
         input: undefined,
-        key: undefined,
         name: undefined,
     };
     const rejectUnknown = (arg) => {
-        throw new Error(`Unknown convert option "${arg}". Supported: --in <file>, --key <key>, --name <name>.`);
+        throw new Error(`Unknown convert option "${arg}". Supported: --in <file>, --name <name>.`);
     };
     parseCliArgs({
         argv,
@@ -29,9 +28,6 @@ export function parseConvertArgs(argv) {
             "--in": value => {
                 args.input = value;
             },
-            "--key": value => {
-                args.key = value;
-            },
             "--name": value => {
                 args.name = value;
             },
@@ -68,16 +64,14 @@ export function convertSample(input, overrides = {}) {
     const sample = parsed.output;
     const warnings = [];
     const mappings = buildPropertyMappings(sample.properties, sample.results, warnings);
-    const key = overrides.key ?? slugify(sample.name ?? "") ?? "data_source";
-    const name = overrides.name ?? (sample.name || undefined) ?? key;
+    const name = overrides.name ?? (sample.name || undefined);
     const schema = {};
     for (const mapping of mappings.values()) {
         schema[mapping.key] = { name: mapping.name, type: mapping.type };
     }
     const source = {
         type: "syncedFromProd",
-        key,
-        name,
+        ...(name !== undefined ? { name } : {}),
         schema,
         rows: (sample.results ?? []).map(row => convertRow(row, mappings)),
     };
@@ -207,7 +201,6 @@ export async function runConvert(argv) {
         throw new Error(`Input is not valid JSON — ${formatUnknownError(error)}`);
     }
     const { source, warnings } = convertSample(parsed, {
-        ...(args.key !== undefined ? { key: args.key } : {}),
         ...(args.name !== undefined ? { name: args.name } : {}),
     });
     for (const warning of warnings) {

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

@@ -60,7 +60,6 @@ export function readDataSources(dataDir) {
 const nonEmptyString = v.pipe(v.string(), v.nonEmpty());
 export const sourceFileSchema = v.object({
     type: v.optional(v.picklist(DEV_SHELL_DATA_SOURCE_TYPES), "worker"),
-    key: v.optional(nonEmptyString),
     name: v.optional(nonEmptyString),
     icon: v.optional(v.string()),
     schema: v.optional(v.record(v.string(), v.object({
@@ -71,7 +70,7 @@ export const sourceFileSchema = v.object({
 });
 /**
  * Parse and validate one source file. Structural mistakes throw with the file
- * and problem named; omitted `key`/`name` fall back to the filename, and
+ * and problem named; the filename defines identity and the default `name`, and
  * omitted `schema`/`rows` to empty — so the minimal valid file is `{}`.
  */
 function readSource(file) {
@@ -93,12 +92,11 @@ function readSource(file) {
     }
     const { type, icon, schema, rows } = result.output;
     const filename = basename(file, ".json");
-    const key = result.output.key ?? filename;
     return {
         type,
-        key,
+        key: filename,
         filename,
-        name: result.output.name ?? key,
+        name: result.output.name ?? filename,
         ...(icon !== undefined ? { icon } : {}),
         schema: Object.fromEntries(Object.entries(schema).map(([propertyKey, property]) => [
             propertyKey,

package/dist-cli/dev-shell-launcher.js CHANGED Viewed

@@ -14,6 +14,8 @@ import { formatUnknownErrorWithStack } from "./errors.js";
 import { materializeWorkerSchemaDataSources } from "./materialize.js";
 import { BLOCK_BASE_PORT, parsePort, SHELL_PORT, validateBlockPortRange, validateShellPort, } from "./ports.js";
 import { installProcessSignalHandlers, ProcessSupervisor, } from "./process-supervisor.js";
+import { resolveLaunchBindings } from "./resolve-bindings.js";
+import { parseBindingOverride, } from "./source-bindings.js";
 import { parseCliArgs } from "./utils.js";
 import { writeBlockViteConfig } from "./vite-block-server.js";
 import { blockCapabilities, findWorkerDir, generateWorkerManifest, } from "./worker-manifest.js";
@@ -59,11 +61,15 @@ export function parseWorkerLaunchArgs(argv) {
         worker: undefined,
         shellPort: SHELL_PORT,
         blockBasePort: BLOCK_BASE_PORT,
+        bindings: [],
     };
     let hasPositionalWorker = false;
     parseCliArgs({
         argv,
         handlers: {
+            "--bind": value => {
+                args.bindings.push(parseBindingOverride(value));
+            },
             "--worker": value => {
                 if (value.length === 0) {
                     throw new Error("--worker requires a path to a worker directory.");
@@ -83,7 +89,7 @@ export function parseWorkerLaunchArgs(argv) {
         },
         onUnknown: arg => {
             throw new Error(`Unknown dev shell option "${arg}". Supported: --worker <dir>, ` +
-                `--port <port>, --block-base-port <port>.`);
+                `--port <port>, --block-base-port <port>, --bind <capabilityKey>.<dataSourceKey>=<sampleDataFileName>.`);
         },
         onPositional: arg => {
             // The published launcher passes its optional worker path positionally.
@@ -186,6 +192,13 @@ async function prepareWorkerLaunch(options) {
     const plan = await prepareWorkerLaunchPlan(workerDir, {
         blockBasePort: args.blockBasePort,
     });
+    const { registryBindings } = resolveLaunchBindings(plan.blocks.map(block => block.capability), plan.dataSources, args.bindings);
+    for (const entry of plan.registry) {
+        const bindings = registryBindings.get(entry.key);
+        if (bindings !== undefined) {
+            entry.sampleFilesByDataSource = bindings;
+        }
+    }
     logWorkerPlan(workerName, plan);
     validateShellPort(args.shellPort, args.blockBasePort, plan.blocks.length);
     const shell = await options.createShellLaunch({

package/dist-cli/materialize.js CHANGED Viewed

@@ -23,8 +23,7 @@ const TYPE_ALIASES = {
 };
 /**
  * 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
+ * filename carries the prefix, while the display name stays as declared, so the sidebar
  * shows the clean name.
  */
 const WORKER_PREFIX = "worker_";
@@ -69,14 +68,12 @@ export function materializeWorkerSchemaDataSources(manifest, dataDir) {
     }
     mkdirSync(dataDir, { recursive: true });
     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.
+        // Replace path-hostile characters so the filename stays inside `dataDir`.
         const file = resolve(dataDir, `${WORKER_PREFIX}${fileSafe(key)}.json`);
         if (existsSync(file)) {
             continue;
         }
-        writeFileSync(file, `${JSON.stringify(buildSource(key, descriptor), null, 2)}\n`);
+        writeFileSync(file, `${JSON.stringify(buildSource(descriptor), null, 2)}\n`);
     }
 }
 function fileSafe(key) {
@@ -90,7 +87,7 @@ function samePropertySchemas(left, right) {
             left[key].type === right[key].type &&
             (left[key].name ?? key) === (right[key].name ?? key)));
 }
-function buildSource(key, descriptor) {
+function buildSource(descriptor) {
     const { name, properties } = descriptor;
     const schema = {};
     for (const [propertyKey, property] of Object.entries(properties)) {
@@ -101,7 +98,6 @@ function buildSource(key, descriptor) {
     }
     return {
         type: "worker",
-        key: `${WORKER_PREFIX}${key}`,
         name,
         schema,
         rows: [],

package/dist-cli/prebuilt.js CHANGED Viewed

@@ -2,21 +2,18 @@
  * Copy the shell's pre-built sources (`data/*.json`, shipped in the
  * package) into a worker's data directory. Like materialization, existing
  * worker data always wins: a bundled source is skipped when its filename is
- * already taken, and also when its `key` is already claimed by any existing
- * source — `key` is a source's binding/lookup identity, so a duplicate would
- * make one of the two ambiguous.
+ * already taken. The filename defines the source identity.
  */
 import { copyFileSync, existsSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
 import { readDataSources } from "./data-sources.js";
 export function copyPrebuiltDataSources(prebuiltDir, dataDir) {
     mkdirSync(dataDir, { recursive: true });
-    const existingKeys = new Set(readDataSources(dataDir).map(source => source.key));
     const written = [];
     for (const source of readDataSources(prebuiltDir)) {
         const filename = `${source.filename}.json`;
         const target = resolve(dataDir, filename);
-        if (existsSync(target) || existingKeys.has(source.key)) {
+        if (existsSync(target)) {
             continue;
         }
         copyFileSync(resolve(prebuiltDir, filename), target);

package/dist-cli/resolve-bindings.js ADDED Viewed

@@ -0,0 +1,39 @@
+/** Validate explicit file selections before servers start. */
+export function resolveLaunchBindings(blocks, sources, overrides) {
+    const targets = blocks.flatMap(block => Object.entries(block.config.manifest.dataSources).map(([slotKey]) => ({
+        blockKey: block.key,
+        slotKey,
+        target: `${block.key}.${slotKey}`,
+    })));
+    const explicit = validateOverrides(targets.map(candidate => candidate.target), sources, overrides);
+    const registryBindings = new Map();
+    for (const { blockKey, slotKey, target } of targets) {
+        const source = explicit.get(target);
+        if (source === undefined) {
+            continue;
+        }
+        const bindings = registryBindings.get(blockKey) ??
+            Object.create(null);
+        bindings[slotKey] = `${source.filename}.json`;
+        registryBindings.set(blockKey, bindings);
+    }
+    return { registryBindings };
+}
+function validateOverrides(targets, sources, overrides) {
+    const explicit = new Map();
+    for (const { target, filename } of overrides) {
+        const matches = targets.filter(candidate => candidate === target);
+        if (matches.length !== 1) {
+            throw new Error(`${matches.length === 0 ? "Unknown" : "Ambiguous"} binding target "${target}". Available targets: ${targets.join(", ") || "(none)"}.`);
+        }
+        if (explicit.has(target)) {
+            throw new Error(`Duplicate --bind target "${target}". Specify each target once.`);
+        }
+        const source = sources.find(candidate => `${candidate.filename}.json` === filename);
+        if (source === undefined) {
+            throw new Error(`Cannot bind ${target}: data/${filename} does not exist. Available files: ${sources.map(candidate => `${candidate.filename}.json`).join(", ") || "(none)"}.`);
+        }
+        explicit.set(target, source);
+    }
+    return explicit;
+}

package/dist-cli/source-bindings.js ADDED Viewed

@@ -0,0 +1,17 @@
+export function parseBindingOverride(value) {
+    const separator = value.indexOf("=");
+    const target = value.slice(0, separator);
+    const filename = value.slice(separator + 1);
+    const dot = target.indexOf(".");
+    if (separator < 0 ||
+        dot <= 0 ||
+        dot === target.length - 1 ||
+        target !== target.trim() ||
+        filename !== filename.trim() ||
+        !filename.endsWith(".json") ||
+        filename === ".json" ||
+        /[\\/\0]/.test(filename)) {
+        throw new Error("--bind requires <capabilityKey>.<dataSourceKey>=<sampleDataFileName.json>. Use a filename in data/.");
+    }
+    return { target, filename };
+}

package/docs/bindings.md CHANGED Viewed

@@ -1,36 +1,60 @@
-# Dev-shell bindings
+# Dev shell bindings
-The shell lists your worker's blocks in the sidebar and renders the selected
-block in a mock Notion host. Blocks start fully unbound: nothing renders
-until every data source slot the block declares is connected to a source and
-every declared property is mapped.
+The dev shell previews your worker's custom blocks with local data from
+`data/*.json`. Each data source selects its file in this order:
+1. The explicit `--bind` selection.
+2. `data/worker_<dataSourceKey>.json`, if it exists.
+3. `data/<dataSourceKey>.json`, if it exists.
+4. Otherwise, it stays unbound. The shell starts, but the block cannot initialize
+   until you connect the source in **Data**.
+An invalid explicit selection stops startup instead of falling back to another
+file. An empty file still takes precedence over later choices.
+## Choose sample data
+Use `--bind <capabilityKey>.<dataSourceKey>=<sampleDataFileName>` to choose a source:
+```bash
+ntn workers customblocks dev -- --bind task-board.tasks=sample_tasks.json
+```
+This connects the `tasks` data source on `task-board` to `data/sample_tasks.json`.
+Use a filename from `data/`, including `.json`.
+Repeat `--bind` for additional data sources. Sources without an override keep
+their defaults. When running `custom-blocks-dev-shell` directly, omit the `--`
+separator.
+An unknown target, duplicate target, or missing file stops startup.
+Invalid JSON or an invalid source file also stops startup.
+The browser maps compatible properties automatically. Incomplete mappings do
+not stop the shell. Open **Data** to finish connecting the block.
+Empty rows are valid.
 ## Connecting data
-**Connect data** in the toolbar opens the bindings modal: one section
+**Data** in the toolbar opens the bindings modal: one section
 per slot from the block's `worker.customBlock({ dataSources })` declaration,
 each with a source picker and a per-property mapping. The sources on offer
 are the ones in your worker's `data/*.json`
-(format: [`data-sources.md`](./data-sources.md)); the toolbar shows a chip
-per slot with its current binding state.
+(format: [`data-sources.md`](./data-sources.md)). The modal shows each slot
+and its property mappings.
-Picking a source auto-maps its properties. For each manifest property, only
-schema properties of the same type are candidates. A property is a candidate
-on an exact ID/key match (no trim or case folding) or a display name match
-after trim and lowercasing. Bind when there is exactly one candidate;
-anything ambiguous or absent stays unmapped. Re-picking a source resets the
-slot's mappings and re-runs auto-map. Manual mapping offers only source
-properties of exactly the required type — no coercion.
+Properties map automatically when there is a unique source property with a
+matching key or name and the same type. Use the property pickers to adjust
+mappings. Selecting a different source resets its property mappings.
 ## Initialization & binding edits
 Once every slot is bound and every property mapped, the block initializes and
-renders. Any binding edit restarts the block: the shell recreates the block's
-iframe, and the fresh initialization carries the new bindings. A block that
-failed to initialize recovers the same way — fix its bindings and save.
+renders. Saving binding changes restarts the block with the updated data.
+If initialization fails, fix the bindings and save.
 Bindings last for the page load, per block: refresh the shell and every block
-returns to unbound.
+returns to its CLI selection or filename default.
 The shell reads `data/*.json` once at spin-up. To pick up file edits,
 restart the dev-shell command; a browser refresh is not enough.

package/docs/data-sources.md CHANGED Viewed

@@ -11,10 +11,11 @@ supports the following types today:
 ## File format
+For example, `data/tasks.json`:
 ```json
 {
   "type": "worker",
-  "key": "tasks",
   "name": "Tasks",
   "icon": "✅",
   "schema": {
@@ -37,17 +38,16 @@ supports the following types today:
 - `type` — the source's kind. Hand-authored files declare `"worker"` (the
   default); the pre-built sources the shell adds carry `"built-in"`.
-- `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`.
+- `name` — the label shown in the shell sidebar. If omitted, it defaults to
+  the filename without `.json`.
 - `icon` — optional emoji shown alongside the name.
-- `schema` — property key → `{ name, type }`. Use the same property keys and
+- `schema` — maps each property key to `{ name, type }`. If omitted, it defaults
+  to `{}`. 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.
+- `rows` — the source records. If omitted, it defaults to `[]`. Each row needs
+  a unique string `id`. Store property values under their schema keys.
 Value shapes by property type:
@@ -67,8 +67,8 @@ Value shapes by property type:
 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.
 `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.
+The filename without `.json` is the source identity used by bindings and
+source pickers. Renaming a file changes its identity.
 ## Querying
@@ -86,7 +86,7 @@ materializes a file for every data source the worker declares — both
 schemas — that doesn't already have one: `data/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
+- The `worker_` prefix on the filename 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
@@ -94,3 +94,21 @@ schema with empty `rows`, mirroring a managed database before any sync.
   schema.
 The shell shows exactly the sources in `data/`, nothing else.
+## Sample rows into a generated source
+To populate a declared slot, use the generated file as the sample target:
+```bash
+ntn workers customblocks sample <url-or-data-source-id> \
+  --out data/worker_tasks.json --row-only
+```
+Run the dev shell once to create the generated file, then stop it before sampling.
+`--row-only` preserves the schema and appends rows with new IDs. Add `--overwrite`
+to replace existing rows.
+Sampled property keys must match the generated schema. If they differ, sample
+into a separate file and select it with [`--bind`](./bindings.md#choose-sample-data).
+Restart the dev shell after sampling to load the updated data.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-dev-shell",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "Local preview shell for Notion custom block workers.",
   "license": "MIT",
   "type": "module",