@notionhq/custom-blocks-dev-shell 0.1.4 → 0.1.5

package/README.md

@@ -1,24 +1,24 @@
 # Notion custom blocks dev shell
 
-A local preview shell for Notion custom block workers. It builds your worker,
+A local dev shell for Notion custom block workers. It builds your worker,
 reads the manifest declared by your `worker.customBlock(...)` calls, serves each
 block with your project's own Vite, and renders them in a mock Notion host with
 sample data sources you can bind against.
 
 ## Usage
 
-From anywhere inside your worker project:
+From anywhere inside your worker project, with the Notion CLI (v0.20.0+):
 
 ```bash
-npx @notionhq/custom-blocks-dev-shell
+ntn customblocks dev
 ```
 
 Then open http://localhost:9873.
 
 Options:
 
-- `--worker <dir>` — point at a worker directory explicitly instead of
-  detecting one from the current directory.
+- `[path]` — point at a worker directory explicitly instead of detecting one
+  from the current directory.
 - `--port <port>` — serve the shell UI somewhere other than 9873.
 - `--block-base-port <port>` — first port handed to the per-block dev servers
   (default 9876; blocks count up from there).
@@ -28,6 +28,9 @@ Options:
 One page per topic, shipped in this package's `docs/` so they're readable
 from `node_modules`:
 
+- [`docs/bindings.md`](./docs/bindings.md) — connecting blocks to data
+  sources: auto-mapping and compatibility rules, initialization, and live
+  rebinding.
 - [`docs/data-sources.md`](./docs/data-sources.md) — local data sources: the
   `src/data/*.json` file format, value shapes per property type, validation,
   and how missing sources are materialized from the worker's declared

package/docs/bindings.md

@@ -0,0 +1,41 @@
+# 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.
+
+## Connecting data
+
+**Connect 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 `src/data/*.json`
+(format: [`data-sources.md`](./data-sources.md)); the toolbar shows a chip
+per slot with its current binding state.
+
+Picking a source auto-maps its properties: a source property whose key
+equals the manifest key and matches its type wins; otherwise exactly one
+type-compatible property with the same name (case-insensitive); 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.
+
+## Initialization & live edits
+
+Once every slot is bound and every property mapped, the block initializes and
+renders. From then on, binding edits reach the running block through
+`dataSourcesChanged` without reloading it. Crossing between incomplete and
+complete bindings restarts the block instead — initialization is terminal, so
+a block that failed to initialize can only recover through a reload.
+
+Bindings last for the page load, per block: refresh the shell and every block
+returns to unbound.
+
+The shell reads `src/data/*.json` once at spin-up. To pick up file edits,
+restart the dev-shell command; a browser refresh is not enough.
+
+## Data view
+
+Click a data source in the sidebar to inspect its schema and rows, read-only.
+The shell shows exactly the sources in `src/data/`, nothing else.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-dev-shell",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Local preview shell for Notion custom block workers.",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "valibot": "^1.3.1",
-    "@notionhq/custom-blocks": "0.1.1"
+    "@notionhq/custom-blocks": "0.1.4"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.2.4",