@notionhq/custom-blocks-dev-shell 0.1.4 → 0.1.5
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.
- package/README.md +8 -5
- package/docs/bindings.md +41 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,24 +1,24 @@
|
|
|
1
1
|
# Notion custom blocks dev shell
|
|
2
2
|
|
|
3
|
-
A local
|
|
3
|
+
A local dev shell for Notion custom block workers. It builds your worker,
|
|
4
4
|
reads the manifest declared by your `worker.customBlock(...)` calls, serves each
|
|
5
5
|
block with your project's own Vite, and renders them in a mock Notion host with
|
|
6
6
|
sample data sources you can bind against.
|
|
7
7
|
|
|
8
8
|
## Usage
|
|
9
9
|
|
|
10
|
-
From anywhere inside your worker project:
|
|
10
|
+
From anywhere inside your worker project, with the Notion CLI (v0.20.0+):
|
|
11
11
|
|
|
12
12
|
```bash
|
|
13
|
-
|
|
13
|
+
ntn customblocks dev
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
Then open http://localhost:9873.
|
|
17
17
|
|
|
18
18
|
Options:
|
|
19
19
|
|
|
20
|
-
-
|
|
21
|
-
|
|
20
|
+
- `[path]` — point at a worker directory explicitly instead of detecting one
|
|
21
|
+
from the current directory.
|
|
22
22
|
- `--port <port>` — serve the shell UI somewhere other than 9873.
|
|
23
23
|
- `--block-base-port <port>` — first port handed to the per-block dev servers
|
|
24
24
|
(default 9876; blocks count up from there).
|
|
@@ -28,6 +28,9 @@ Options:
|
|
|
28
28
|
One page per topic, shipped in this package's `docs/` so they're readable
|
|
29
29
|
from `node_modules`:
|
|
30
30
|
|
|
31
|
+
- [`docs/bindings.md`](./docs/bindings.md) — connecting blocks to data
|
|
32
|
+
sources: auto-mapping and compatibility rules, initialization, and live
|
|
33
|
+
rebinding.
|
|
31
34
|
- [`docs/data-sources.md`](./docs/data-sources.md) — local data sources: the
|
|
32
35
|
`src/data/*.json` file format, value shapes per property type, validation,
|
|
33
36
|
and how missing sources are materialized from the worker's declared
|
package/docs/bindings.md
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Dev-shell bindings
|
|
2
|
+
|
|
3
|
+
The shell lists your worker's blocks in the sidebar and renders the selected
|
|
4
|
+
block in a mock Notion host. Blocks start fully unbound: nothing renders
|
|
5
|
+
until every data-source slot the block declares is connected to a source and
|
|
6
|
+
every declared property is mapped.
|
|
7
|
+
|
|
8
|
+
## Connecting data
|
|
9
|
+
|
|
10
|
+
**Connect data** in the toolbar opens the bindings modal: one section
|
|
11
|
+
per slot from the block's `worker.customBlock({ dataSources })` declaration,
|
|
12
|
+
each with a source picker and a per-property mapping. The sources on offer
|
|
13
|
+
are the ones in your worker's `src/data/*.json`
|
|
14
|
+
(format: [`data-sources.md`](./data-sources.md)); the toolbar shows a chip
|
|
15
|
+
per slot with its current binding state.
|
|
16
|
+
|
|
17
|
+
Picking a source auto-maps its properties: a source property whose key
|
|
18
|
+
equals the manifest key and matches its type wins; otherwise exactly one
|
|
19
|
+
type-compatible property with the same name (case-insensitive); anything
|
|
20
|
+
ambiguous or absent stays unmapped. Re-picking a source resets the slot's
|
|
21
|
+
mappings and re-runs auto-map. Manual mapping offers only source properties
|
|
22
|
+
of exactly the required type — no coercion.
|
|
23
|
+
|
|
24
|
+
## Initialization & live edits
|
|
25
|
+
|
|
26
|
+
Once every slot is bound and every property mapped, the block initializes and
|
|
27
|
+
renders. From then on, binding edits reach the running block through
|
|
28
|
+
`dataSourcesChanged` without reloading it. Crossing between incomplete and
|
|
29
|
+
complete bindings restarts the block instead — initialization is terminal, so
|
|
30
|
+
a block that failed to initialize can only recover through a reload.
|
|
31
|
+
|
|
32
|
+
Bindings last for the page load, per block: refresh the shell and every block
|
|
33
|
+
returns to unbound.
|
|
34
|
+
|
|
35
|
+
The shell reads `src/data/*.json` once at spin-up. To pick up file edits,
|
|
36
|
+
restart the dev-shell command; a browser refresh is not enough.
|
|
37
|
+
|
|
38
|
+
## Data view
|
|
39
|
+
|
|
40
|
+
Click a data source in the sidebar to inspect its schema and rows, read-only.
|
|
41
|
+
The shell shows exactly the sources in `src/data/`, nothing else.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@notionhq/custom-blocks-dev-shell",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"description": "Local preview shell for Notion custom block workers.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"react": "^19.2.5",
|
|
27
27
|
"react-dom": "^19.2.5",
|
|
28
28
|
"valibot": "^1.3.1",
|
|
29
|
-
"@notionhq/custom-blocks": "0.1.
|
|
29
|
+
"@notionhq/custom-blocks": "0.1.4"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
32
|
"@tailwindcss/vite": "^4.2.4",
|