@kubohiroya/turbowarp-react-islands 0.2.0

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.
@@ -0,0 +1,33 @@
1
+ export type JsonPrimitive = string | number | boolean | null;
2
+ export type JsonValue = JsonPrimitive | JsonValue[] | {
3
+ [key: string]: JsonValue;
4
+ };
5
+ export type JsonObject = {
6
+ [key: string]: JsonValue;
7
+ };
8
+ export interface ReactComponentRegistration {
9
+ component: string;
10
+ module: string;
11
+ }
12
+ export interface ReactIslandDescriptor {
13
+ kind: 'react-island';
14
+ version: 1;
15
+ component: string;
16
+ mountId: string;
17
+ props: JsonObject;
18
+ }
19
+ export interface ReactIslandInput {
20
+ component: string;
21
+ mountId: string;
22
+ props?: JsonObject;
23
+ }
24
+ export declare class ComponentRegistry {
25
+ private readonly components;
26
+ register(component: string, module: string): ReactComponentRegistration;
27
+ list(): ReactComponentRegistration[];
28
+ toJSON(): ReactComponentRegistration[];
29
+ }
30
+ export declare function createReactIslandDescriptor(input: ReactIslandInput): ReactIslandDescriptor;
31
+ export declare function parsePropsJson(value: string): JsonObject;
32
+ export declare function serializeReactIslandDescriptor(descriptor: ReactIslandDescriptor): string;
33
+ export declare function renderReactIslandHtml(descriptor: ReactIslandDescriptor): string;
package/dist/island.js ADDED
@@ -0,0 +1,78 @@
1
+ export class ComponentRegistry {
2
+ constructor() {
3
+ this.components = new Map();
4
+ }
5
+ register(component, module) {
6
+ const registration = {
7
+ component: validateComponentName(component),
8
+ module: validateModuleSpecifier(module)
9
+ };
10
+ this.components.set(registration.component, registration);
11
+ return registration;
12
+ }
13
+ list() {
14
+ return [...this.components.values()].sort((left, right) => left.component.localeCompare(right.component));
15
+ }
16
+ toJSON() {
17
+ return this.list();
18
+ }
19
+ }
20
+ export function createReactIslandDescriptor(input) {
21
+ return {
22
+ kind: 'react-island',
23
+ version: 1,
24
+ component: validateComponentName(input.component),
25
+ mountId: validateMountId(input.mountId),
26
+ props: input.props ?? {}
27
+ };
28
+ }
29
+ export function parsePropsJson(value) {
30
+ const trimmed = value.trim();
31
+ if (trimmed.length === 0)
32
+ return {};
33
+ const parsed = JSON.parse(trimmed);
34
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
35
+ throw new TypeError('React island props must be a JSON object.');
36
+ }
37
+ return parsed;
38
+ }
39
+ export function serializeReactIslandDescriptor(descriptor) {
40
+ return JSON.stringify(descriptor);
41
+ }
42
+ export function renderReactIslandHtml(descriptor) {
43
+ const propsJson = JSON.stringify(descriptor.props).replace(/</g, '\\u003c');
44
+ return [
45
+ `<div id="${escapeHtmlAttribute(descriptor.mountId)}" data-tw-react-island="${escapeHtmlAttribute(descriptor.component)}">`,
46
+ `<script type="application/json" data-tw-react-props>${propsJson}</script>`,
47
+ '</div>'
48
+ ].join('');
49
+ }
50
+ function validateComponentName(value) {
51
+ const component = value.trim();
52
+ if (!/^[A-Z][A-Za-z0-9]*(?:[.:/-][A-Z]?[A-Za-z0-9]+)*$/.test(component)) {
53
+ throw new TypeError(`Invalid React component name: ${value}`);
54
+ }
55
+ return component;
56
+ }
57
+ function validateMountId(value) {
58
+ const mountId = value.trim();
59
+ if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(mountId)) {
60
+ throw new TypeError(`Invalid React island mount ID: ${value}`);
61
+ }
62
+ return mountId;
63
+ }
64
+ function validateModuleSpecifier(value) {
65
+ const module = value.trim();
66
+ if (module.length === 0) {
67
+ throw new TypeError('React component module must be non-empty.');
68
+ }
69
+ return module;
70
+ }
71
+ function escapeHtmlAttribute(value) {
72
+ return value
73
+ .replace(/&/g, '&amp;')
74
+ .replace(/"/g, '&quot;')
75
+ .replace(/</g, '&lt;')
76
+ .replace(/>/g, '&gt;');
77
+ }
78
+ //# sourceMappingURL=island.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"island.js","sourceRoot":"","sources":["../src/island.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,152 @@
1
+ // Name: TurboWarp React Islands
2
+ // ID: kubohiroyareactislands
3
+ // Description: Describe React islands from TurboWarp blocks for turbowarp-http-server HTML responses.
4
+ // By: Hiroya Kubo
5
+ // License: MPL-2.0
6
+
7
+ (function (Scratch) {
8
+ 'use strict';
9
+
10
+ const extensionConfig = {
11
+ id: "kubohiroyareactislands",
12
+ docsURI: "https://kubohiroya.github.io/turbowarp-react-islands/",
13
+ blockIconURI: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCI+PHJlY3QgeD0iNCIgeT0iOCIgd2lkdGg9IjE4IiBoZWlnaHQ9IjE0IiByeD0iMyIgZmlsbD0iIzRDOTdGRiIvPjxyZWN0IHg9IjI2IiB5PSI4IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjNTlDMDU5Ii8+PHJlY3QgeD0iMTUiIHk9IjI2IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjRkZBQjE5Ii8+PC9zdmc+"
14
+ };
15
+ const extensionName = "TurboWarp React Islands";
16
+ const blocks = [{ "opcode": "registerComponent", "blockType": "COMMAND", "text": "register React component [COMPONENT] from [MODULE]", "description": "Registers a React component name and the browser module that will hydrate it later.", "arguments": { "COMPONENT": { "type": "STRING", "defaultValue": "Counter" }, "MODULE": { "type": "STRING", "defaultValue": "/assets/react-islands.js" } } }, { "opcode": "reactIsland", "blockType": "REPORTER", "text": "React island [COMPONENT] at [MOUNT_ID] props [PROPS_JSON]", "description": "Returns a JSON mount descriptor for a React island.", "arguments": { "COMPONENT": { "type": "STRING", "defaultValue": "Counter" }, "MOUNT_ID": { "type": "STRING", "defaultValue": "counter-root" }, "PROPS_JSON": { "type": "STRING", "defaultValue": '{"initialCount":0}' } } }, { "opcode": "reactIslandHtml", "blockType": "REPORTER", "text": "React island HTML [COMPONENT] at [MOUNT_ID] props [PROPS_JSON]", "description": "Returns a safe HTML fragment that marks where a React island should be mounted.", "arguments": { "COMPONENT": { "type": "STRING", "defaultValue": "Counter" }, "MOUNT_ID": { "type": "STRING", "defaultValue": "counter-root" }, "PROPS_JSON": { "type": "STRING", "defaultValue": '{"initialCount":0}' } } }, { "opcode": "componentRegistryJson", "blockType": "REPORTER", "text": "React component registry JSON", "description": "Returns the registered React component registry as JSON.", "arguments": {} }];
17
+ const definitions = {
18
+ extensionName,
19
+ blocks
20
+ };
21
+ class ComponentRegistry {
22
+ constructor() {
23
+ this.components = /* @__PURE__ */ new Map();
24
+ }
25
+ register(component, module) {
26
+ const registration = {
27
+ component: validateComponentName(component),
28
+ module: validateModuleSpecifier(module)
29
+ };
30
+ this.components.set(registration.component, registration);
31
+ return registration;
32
+ }
33
+ list() {
34
+ return [...this.components.values()].sort(
35
+ (left, right) => left.component.localeCompare(right.component)
36
+ );
37
+ }
38
+ toJSON() {
39
+ return this.list();
40
+ }
41
+ }
42
+ function createReactIslandDescriptor(input) {
43
+ return {
44
+ kind: "react-island",
45
+ version: 1,
46
+ component: validateComponentName(input.component),
47
+ mountId: validateMountId(input.mountId),
48
+ props: input.props ?? {}
49
+ };
50
+ }
51
+ function parsePropsJson(value) {
52
+ const trimmed = value.trim();
53
+ if (trimmed.length === 0) return {};
54
+ const parsed = JSON.parse(trimmed);
55
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
56
+ throw new TypeError("React island props must be a JSON object.");
57
+ }
58
+ return parsed;
59
+ }
60
+ function serializeReactIslandDescriptor(descriptor) {
61
+ return JSON.stringify(descriptor);
62
+ }
63
+ function renderReactIslandHtml(descriptor) {
64
+ const propsJson = JSON.stringify(descriptor.props).replace(/</g, "\\u003c");
65
+ return [
66
+ `<div id="${escapeHtmlAttribute(descriptor.mountId)}" data-tw-react-island="${escapeHtmlAttribute(
67
+ descriptor.component
68
+ )}">`,
69
+ `<script type="application/json" data-tw-react-props>${propsJson}<\/script>`,
70
+ "</div>"
71
+ ].join("");
72
+ }
73
+ function validateComponentName(value) {
74
+ const component = value.trim();
75
+ if (!/^[A-Z][A-Za-z0-9]*(?:[.:/-][A-Z]?[A-Za-z0-9]+)*$/.test(component)) {
76
+ throw new TypeError(`Invalid React component name: ${value}`);
77
+ }
78
+ return component;
79
+ }
80
+ function validateMountId(value) {
81
+ const mountId = value.trim();
82
+ if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(mountId)) {
83
+ throw new TypeError(`Invalid React island mount ID: ${value}`);
84
+ }
85
+ return mountId;
86
+ }
87
+ function validateModuleSpecifier(value) {
88
+ const module = value.trim();
89
+ if (module.length === 0) {
90
+ throw new TypeError("React component module must be non-empty.");
91
+ }
92
+ return module;
93
+ }
94
+ function escapeHtmlAttribute(value) {
95
+ return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
96
+ }
97
+ const blockDefinitions = definitions.blocks;
98
+ class TurboWarpHttpServerReactExtension {
99
+ constructor() {
100
+ this.registry = new ComponentRegistry();
101
+ }
102
+ getInfo() {
103
+ return {
104
+ id: extensionConfig.id,
105
+ name: Scratch.translate(definitions.extensionName),
106
+ docsURI: extensionConfig.docsURI,
107
+ blockIconURI: extensionConfig.blockIconURI,
108
+ blocks: blockDefinitions.map((block) => this.toScratchBlock(block))
109
+ };
110
+ }
111
+ registerComponent(args) {
112
+ this.registry.register(
113
+ Scratch.Cast.toString(args.COMPONENT),
114
+ Scratch.Cast.toString(args.MODULE)
115
+ );
116
+ }
117
+ reactIsland(args) {
118
+ return serializeReactIslandDescriptor(this.createDescriptor(args));
119
+ }
120
+ reactIslandHtml(args) {
121
+ return renderReactIslandHtml(this.createDescriptor(args));
122
+ }
123
+ componentRegistryJson() {
124
+ return JSON.stringify(this.registry.toJSON());
125
+ }
126
+ toScratchBlock(block) {
127
+ return {
128
+ opcode: block.opcode,
129
+ blockType: Scratch.BlockType[block.blockType],
130
+ text: Scratch.translate(block.text),
131
+ arguments: Object.fromEntries(
132
+ Object.entries(block.arguments).map(([name, argument]) => [
133
+ name,
134
+ {
135
+ type: Scratch.ArgumentType[argument.type],
136
+ defaultValue: argument.defaultValue
137
+ }
138
+ ])
139
+ )
140
+ };
141
+ }
142
+ createDescriptor(args) {
143
+ return createReactIslandDescriptor({
144
+ component: Scratch.Cast.toString(args.COMPONENT),
145
+ mountId: Scratch.Cast.toString(args.MOUNT_ID),
146
+ props: parsePropsJson(Scratch.Cast.toString(args.PROPS_JSON))
147
+ });
148
+ }
149
+ }
150
+ Scratch.extensions.register(new TurboWarpHttpServerReactExtension());
151
+
152
+ })(Scratch);
@@ -0,0 +1,87 @@
1
+ # アーキテクチャ
2
+
3
+ [English](architecture.md)
4
+
5
+ ## 目的
6
+
7
+ `turbowarp-react-islands` は、TurboWarpで書いたHTTP/HTML生成ロジックからReact componentを直接実行するのではなく、React islandを埋め込むための中間記述を作るパッケージです。
8
+
9
+ 教育的には、ブロックプログラミングからReactプログラミングへ段階的に移行する橋渡しを狙います。実用面では、MUIなどの成熟したReact componentを使いながら、ページ構成やprops指定の一部をブロックで扱えるようにします。
10
+
11
+ ## 役割分担
12
+
13
+ ```text
14
+ TurboWarp blocks
15
+ -> component name / mount id / JSON props
16
+ -> React island descriptor
17
+ -> HTML fragment
18
+ -> turbowarp-html
19
+ -> turbowarp-http-server response
20
+
21
+ React component source
22
+ -> hooks and logic in TypeScript
23
+ -> Vite dev/build
24
+ -> browser bundle
25
+ -> hydrate island
26
+ ```
27
+
28
+ TurboWarp側は宣言的な接続面を担当します。React component、hooks、effects、状態更新、MUI theme、CSS、bundle分割はTypeScript/Vite側に置きます。
29
+
30
+ ## island descriptor
31
+
32
+ descriptorは次の形のJSONです。
33
+
34
+ ```json
35
+ {
36
+ "kind": "react-island",
37
+ "version": 1,
38
+ "component": "Counter",
39
+ "mountId": "counter-root",
40
+ "props": {"initialCount": 0}
41
+ }
42
+ ```
43
+
44
+ `component` はregistryに登録されたReact component名です。`mountId` はHTML内のmount先IDです。`props` はJSON objectに限定します。
45
+
46
+ ## HTML断片
47
+
48
+ `reactIslandHtml` ブロックは、次のようなHTML断片を返します。
49
+
50
+ ```html
51
+ <div id="counter-root" data-tw-react-island="Counter">
52
+ <script type="application/json" data-tw-react-props>{"initialCount":0}</script>
53
+ </div>
54
+ ```
55
+
56
+ この断片を `turbowarp-html` でページに組み込み、ブラウザ側bundleが `data-tw-react-island` を探してhydrateします。MVPではhydrate scriptそのものはこのパッケージに含めません。
57
+
58
+ ## component registry
59
+
60
+ `registerComponent` ブロックは、component名とブラウザmodule specifierを登録します。
61
+
62
+ ```json
63
+ [
64
+ {"component": "Counter", "module": "/assets/react-islands.js"}
65
+ ]
66
+ ```
67
+
68
+ このregistryは、後続のCLIやVite pluginが「どのcomponentをどのbundleからhydrateするか」を決めるための入力になります。
69
+
70
+ ## Vite dev/build連携
71
+
72
+ 想定する開発体験は次の通りです。
73
+
74
+ - TurboWarpでHTML構造とReact island配置を書く。
75
+ - VS CodeでReact componentとhooksを書く。
76
+ - Vite dev serverがReact側bundleを提供する。
77
+ - `turbowarp-http-server` のHTMLレスポンスにViteの開発用scriptまたはbuild済みassetを組み込む。
78
+
79
+ このリポジトリのMVPは、Vite pluginやdev server proxyまでは実装しません。ただし、descriptorとregistryの形を固定することで、後続パッケージがその上にbuild連携を実装できるようにします。
80
+
81
+ ## 限界
82
+
83
+ - TurboWarpブロックからhooks本体は生成しません。
84
+ - propsはJSON objectだけです。関数やイベントhandlerはcomponent側で定義します。
85
+ - React/MUIはpeer application側の依存です。この拡張bundleには同梱しません。
86
+ - SSR、streaming、partial hydration最適化はMVP外です。
87
+ - island descriptorを信頼境界として扱い、HTML生成時は属性とJSON scriptをエスケープします。
@@ -0,0 +1,47 @@
1
+ # Architecture
2
+
3
+ [日本語](architecture.ja.md)
4
+
5
+ ## Goal
6
+
7
+ `turbowarp-react-islands` describes React islands from TurboWarp blocks. It does not execute React inside TurboWarp. The output is a stable descriptor and HTML fragment that `turbowarp-html`, `turbowarp-http-server`, and a later Vite build step can consume.
8
+
9
+ ## Responsibilities
10
+
11
+ ```text
12
+ TurboWarp blocks
13
+ -> component name / mount id / JSON props
14
+ -> React island descriptor
15
+ -> HTML fragment
16
+ -> turbowarp-html
17
+ -> turbowarp-http-server response
18
+
19
+ React component source
20
+ -> hooks and logic in TypeScript
21
+ -> Vite dev/build
22
+ -> browser bundle
23
+ -> hydrate island
24
+ ```
25
+
26
+ Blocks cover declarative placement and serializable props. React components, hooks, effects, state updates, MUI themes, CSS, and code splitting stay in TypeScript and Vite.
27
+
28
+ ## Island descriptor
29
+
30
+ ```json
31
+ {
32
+ "kind": "react-island",
33
+ "version": 1,
34
+ "component": "Counter",
35
+ "mountId": "counter-root",
36
+ "props": {"initialCount": 0}
37
+ }
38
+ ```
39
+
40
+ The MVP fixes this shape so future CLI and Vite integrations can consume it without depending on TurboWarp runtime internals.
41
+
42
+ ## Limits
43
+
44
+ - The package does not bundle React, React DOM, MUI, or user components.
45
+ - Blocks do not generate hook bodies.
46
+ - Props are JSON objects only.
47
+ - Hydration script generation, dev server proxying, CSS loading, SSR, and streaming are outside the MVP.
@@ -0,0 +1,37 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width,initial-scale=1">
6
+ <title>TurboWarp React Islands</title>
7
+ <style>
8
+ body{font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;max-width:900px;margin:0 auto;padding:2rem;line-height:1.6;color:#222}
9
+ code{background:#f3f3f3;padding:.1em .3em;border-radius:.25em}
10
+ pre{background:#f6f8fa;padding:1rem;overflow:auto;border-radius:.5rem}
11
+ </style>
12
+ </head>
13
+ <body>
14
+ <h1>TurboWarp React Islands</h1>
15
+ <p>This extension describes React islands for HTML responses produced by turbowarp-http-server and turbowarp-html.</p>
16
+
17
+ <h2>Blocks</h2>
18
+ <ul>
19
+ <li><code>register React component [COMPONENT] from [MODULE]</code></li>
20
+ <li><code>React island [COMPONENT] at [MOUNT_ID] props [PROPS_JSON]</code></li>
21
+ <li><code>React island HTML [COMPONENT] at [MOUNT_ID] props [PROPS_JSON]</code></li>
22
+ <li><code>React component registry JSON</code></li>
23
+ </ul>
24
+
25
+ <h2>MVP boundary</h2>
26
+ <p>The extension returns descriptors and HTML fragments. React, React DOM, MUI, hooks, CSS, hydration, and Vite dev/build integration belong to the application bundle.</p>
27
+
28
+ <h2>Descriptor shape</h2>
29
+ <pre><code>{
30
+ "kind": "react-island",
31
+ "version": 1,
32
+ "component": "Counter",
33
+ "mountId": "counter-root",
34
+ "props": {"initialCount": 0}
35
+ }</code></pre>
36
+ </body>
37
+ </html>
package/package.json ADDED
@@ -0,0 +1,73 @@
1
+ {
2
+ "name": "@kubohiroya/turbowarp-react-islands",
3
+ "version": "0.2.0",
4
+ "description": "TurboWarp extension and helpers for describing React islands in turbowarp-http-server HTML responses.",
5
+ "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
6
+ "license": "MPL-2.0",
7
+ "homepage": "https://github.com/kubohiroya/turbowarp-react-islands#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/kubohiroya/turbowarp-react-islands.git"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/kubohiroya/turbowarp-react-islands/issues"
14
+ },
15
+ "keywords": [
16
+ "turbowarp",
17
+ "scratch",
18
+ "extension",
19
+ "react",
20
+ "islands",
21
+ "html",
22
+ "turbowarp-http-server",
23
+ "vite",
24
+ "typescript"
25
+ ],
26
+ "type": "module",
27
+ "files": [
28
+ "dist/",
29
+ "docs/",
30
+ "schemas/",
31
+ "src/",
32
+ "README.md",
33
+ "README.ja.md",
34
+ "LICENSE"
35
+ ],
36
+ "exports": {
37
+ "./island": {
38
+ "types": "./dist/island.d.ts",
39
+ "import": "./dist/island.js"
40
+ }
41
+ },
42
+ "publishConfig": {
43
+ "access": "public",
44
+ "registry": "https://registry.npmjs.org/"
45
+ },
46
+ "packageManager": "pnpm@11.11.0",
47
+ "engines": {
48
+ "node": ">=22"
49
+ },
50
+ "scripts": {
51
+ "dev": "vite build --watch",
52
+ "typecheck": "tsc --noEmit",
53
+ "build": "vite build && tsc -p tsconfig.lib.json",
54
+ "lint": "eslint src tests vite.config.ts",
55
+ "test": "vitest run",
56
+ "docs": "node scripts/generate-readme.mjs",
57
+ "docs:check": "pnpm run docs && git diff --exit-code -- README.md",
58
+ "repo:check": "node scripts/check-repo.mjs",
59
+ "pack:check": "npm pack --dry-run --ignore-scripts",
60
+ "check": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run docs:check && pnpm run check:dist && pnpm run repo:check && pnpm run pack:check",
61
+ "check:dist": "pnpm run build && node scripts/check-dist.mjs"
62
+ },
63
+ "devDependencies": {
64
+ "@eslint/js": "^9.39.5",
65
+ "@kubohiroya/vite-plugin-turbowarp-extension": "0.1.1",
66
+ "@types/node": "^24.13.3",
67
+ "eslint": "^9.39.5",
68
+ "typescript": "^5.9.3",
69
+ "typescript-eslint": "^8.66.0",
70
+ "vite": "^7.3.6",
71
+ "vitest": "^4.1.10"
72
+ }
73
+ }
@@ -0,0 +1,49 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://raw.githubusercontent.com/kubohiroya/turbowarp-react-islands/main/schemas/extension-manifest.schema.json",
4
+ "title": "TurboWarp Extension API Manifest",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": ["formatVersion", "id", "blocks", "menus"],
8
+ "properties": {
9
+ "formatVersion": {"const": 1},
10
+ "id": {"type": "string", "pattern": "^[a-z0-9]+$"},
11
+ "blocks": {
12
+ "type": "array",
13
+ "items": {
14
+ "type": "object",
15
+ "additionalProperties": false,
16
+ "required": ["opcode", "blockType", "arguments"],
17
+ "properties": {
18
+ "opcode": {"type": "string", "minLength": 1},
19
+ "blockType": {"type": "string", "minLength": 1},
20
+ "arguments": {
21
+ "type": "array",
22
+ "items": {
23
+ "type": "object",
24
+ "additionalProperties": false,
25
+ "required": ["id", "type"],
26
+ "properties": {
27
+ "id": {"type": "string", "minLength": 1},
28
+ "type": {"type": "string", "minLength": 1},
29
+ "menu": {"type": "string", "minLength": 1}
30
+ }
31
+ }
32
+ }
33
+ }
34
+ }
35
+ },
36
+ "menus": {
37
+ "type": "array",
38
+ "items": {
39
+ "type": "object",
40
+ "additionalProperties": false,
41
+ "required": ["id", "acceptReporters"],
42
+ "properties": {
43
+ "id": {"type": "string", "minLength": 1},
44
+ "acceptReporters": {"type": "boolean"}
45
+ }
46
+ }
47
+ }
48
+ }
49
+ }
@@ -0,0 +1,44 @@
1
+ {
2
+ "extensionName": "TurboWarp React Islands",
3
+ "blocks": [
4
+ {
5
+ "opcode": "registerComponent",
6
+ "blockType": "COMMAND",
7
+ "text": "register React component [COMPONENT] from [MODULE]",
8
+ "description": "Registers a React component name and the browser module that will hydrate it later.",
9
+ "arguments": {
10
+ "COMPONENT": {"type": "STRING", "defaultValue": "Counter"},
11
+ "MODULE": {"type": "STRING", "defaultValue": "/assets/react-islands.js"}
12
+ }
13
+ },
14
+ {
15
+ "opcode": "reactIsland",
16
+ "blockType": "REPORTER",
17
+ "text": "React island [COMPONENT] at [MOUNT_ID] props [PROPS_JSON]",
18
+ "description": "Returns a JSON mount descriptor for a React island.",
19
+ "arguments": {
20
+ "COMPONENT": {"type": "STRING", "defaultValue": "Counter"},
21
+ "MOUNT_ID": {"type": "STRING", "defaultValue": "counter-root"},
22
+ "PROPS_JSON": {"type": "STRING", "defaultValue": "{\"initialCount\":0}"}
23
+ }
24
+ },
25
+ {
26
+ "opcode": "reactIslandHtml",
27
+ "blockType": "REPORTER",
28
+ "text": "React island HTML [COMPONENT] at [MOUNT_ID] props [PROPS_JSON]",
29
+ "description": "Returns a safe HTML fragment that marks where a React island should be mounted.",
30
+ "arguments": {
31
+ "COMPONENT": {"type": "STRING", "defaultValue": "Counter"},
32
+ "MOUNT_ID": {"type": "STRING", "defaultValue": "counter-root"},
33
+ "PROPS_JSON": {"type": "STRING", "defaultValue": "{\"initialCount\":0}"}
34
+ }
35
+ },
36
+ {
37
+ "opcode": "componentRegistryJson",
38
+ "blockType": "REPORTER",
39
+ "text": "React component registry JSON",
40
+ "description": "Returns the registered React component registry as JSON.",
41
+ "arguments": {}
42
+ }
43
+ ]
44
+ }
package/src/config.ts ADDED
@@ -0,0 +1,12 @@
1
+ export const extensionConfig = {
2
+ id: 'kubohiroyareactislands',
3
+ slug: 'turbowarp-react-islands',
4
+ name: 'TurboWarp React Islands',
5
+ description: 'Describe React islands from TurboWarp blocks for turbowarp-http-server HTML responses.',
6
+ author: 'Hiroya Kubo',
7
+ license: 'MPL-2.0',
8
+ unsandboxed: false,
9
+ docsURI: 'https://kubohiroya.github.io/turbowarp-react-islands/',
10
+ blockIconURI:
11
+ 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCI+PHJlY3QgeD0iNCIgeT0iOCIgd2lkdGg9IjE4IiBoZWlnaHQ9IjE0IiByeD0iMyIgZmlsbD0iIzRDOTdGRiIvPjxyZWN0IHg9IjI2IiB5PSI4IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjNTlDMDU5Ii8+PHJlY3QgeD0iMTUiIHk9IjI2IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjRkZBQjE5Ii8+PC9zdmc+'
12
+ } as const;