@kubohiroya/turbowarp-plus-editor-project-folder 0.6.0 → 0.8.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.
- package/README.ja.md +24 -2
- package/README.md +18 -2
- package/dist/THIRD_PARTY_NOTICES.md +5 -1
- package/dist/explorer.d.ts +52 -0
- package/dist/explorer.js +1059 -0
- package/dist/folder-registry.d.ts +13 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +390 -621
- package/dist/session.d.ts +11 -3
- package/dist/shared-DlmcdO1_.js +458 -0
- package/dist/source.d.ts +34 -3
- package/package.json +24 -1
- package/src/explorer.tsx +410 -0
- package/src/folder-registry.ts +45 -0
- package/src/index.ts +23 -2
- package/src/session.ts +115 -68
- package/src/source.ts +235 -50
- package/tsconfig.json +2 -1
- package/vite.config.ts +12 -2
package/README.ja.md
CHANGED
|
@@ -9,8 +9,30 @@ TurboWarp Plus Editor で既存の sb3-toolchain v1 の作品フォルダを開
|
|
|
9
9
|
- `mountProjectFolder({vm, document, host})` でワークスペースに接続します。ワークスペースの切り替え時には `dispose()` を呼びます。
|
|
10
10
|
- `renderProjectFolderMenu(createElement, props)` は既存の開く・保存コマンドをホストのファイルメニューに渡します。
|
|
11
11
|
- 接続後の `openDirectory(handle, confirmReplace)` には、ホストが選択済みのディレクトリハンドルを渡せます。ファイルメニューと同じ作品検証・未保存編集の確認を経て開き、保存先にはその作品フォルダを使います。
|
|
12
|
+
- 接続後の `directory` は、読み込んだ作品のフォルダーのハンドルです。別の作品を読み込むか、フォルダーとの接続を外すと `null` になります。ホストは作品を見分けるのに使えます。
|
|
12
13
|
|
|
13
|
-
ホストは VM、メニューコンポーネント、作品状態を扱うコールバックを渡します。メニューからフォルダを開くには、ブラウザーが File System Access のフォルダ選択に対応している必要があります。ブロック、変数・リスト、スプライトの位置や大きさなどの項目、モニター、組み込みの拡張機能の編集を作品データ(`project.source.json`)に保存し、作品の実行で変わった状態も含みます。スプライトの追加・削除・名前の変更と、コスチューム・音の追加・削除も保存します。新しいアセットのファイルを先に書き、`sb3-source.json`
|
|
14
|
+
ホストは VM、メニューコンポーネント、作品状態を扱うコールバックを渡します。メニューからフォルダを開くには、ブラウザーが File System Access のフォルダ選択に対応している必要があります。ブロック、変数・リスト、スプライトの位置や大きさなどの項目、モニター、組み込みの拡張機能の編集を作品データ(`project.source.json`)に保存し、作品の実行で変わった状態も含みます。スプライトの追加・削除・名前の変更と、コスチューム・音の追加・削除も保存します。新しいアセットのファイルを先に書き、`sb3-source.json` と作品データを書いてから、参照されなくなったアセットのファイルを消します。 [Editor #305](https://github.com/kubohiroya/turbowarp-plus-editor/issues/305) · [Editor #308](https://github.com/kubohiroya/turbowarp-plus-editor/issues/308)
|
|
15
|
+
|
|
16
|
+
システムフォントと Web フォントの参照は作品データに保持し、埋め込みフォントは `assets/` に保存します。 [Editor #495](https://github.com/kubohiroya/turbowarp-plus-editor/issues/495)
|
|
17
|
+
|
|
18
|
+
## 拡張機能
|
|
19
|
+
|
|
20
|
+
埋め込み拡張の参照は、フォルダを開く際に `extensions/<id>.js` の内容とマニフェストから data URL に復元します。URL で指定されたカスタム拡張も、Editor の既存の許可画面を経て読み込みます。 `turboWarpPlus` のマニフェストとカスタムフォントを含む作品フォルダは対象外です。 [Editor #496](https://github.com/kubohiroya/turbowarp-plus-editor/issues/496)
|
|
21
|
+
|
|
22
|
+
保存時は変更のあったスクリプト、拡張のマニフェスト、作品データの順に書き、参照がなくなったファイルを最後に削除します。変更のないスクリプトと拡張のマニフェストはバイト列を保ちます。差し替えで `source` と対応する API マニフェストを外した場合は、保存時に該当する ID を通知します。2 件未満になったバンドル設定は削除します。module バンドルは管理対象の npm モジュールを必要とするため、差し替えで `source` を失った拡張も設定から外れます。
|
|
23
|
+
|
|
24
|
+
切り戻す場合は、Editor の依存を project-folder 0.6.0 と security-dialog 0.8.8 に戻して再ビルドします。保存済みのフォルダは `sb3-toolchain build` で SB3 にできます。
|
|
25
|
+
|
|
26
|
+
## フォルダの一覧
|
|
27
|
+
|
|
28
|
+
`./explorer`(`@kubohiroya/turbowarp-plus-editor-project-folder/explorer`)は、エディターのサイドパネルに置くフォルダのツリーです。[Headless Tree](https://headless-tree.lukasbach.com/) を同梱しています。描画にはホストの React 16.14〜18 を使います(省略可能な peer dependency)。メインの入口は React を使いません。
|
|
29
|
+
|
|
30
|
+
- `ProjectFolderExplorer` は `directory`(作品フォルダまたはリポジトリのルート)を表示します。フォルダは開いたときに読み込み、ファイルより先に並べます。`.git` は表示しません。矢印キー・Home・End で移動と開閉をします。ファイルで Enter・Space を押すかクリックすると `onOpen({path, name, kind})` を呼びます。props は `directory`、`locale`(`ja…` で日本語、それ以外は英語)、`descriptions` と `marks`(Git の状態: `added`・`modified`・`deleted`・`untracked`、どちらも `directory` からの相対パスがキー)、`onOpen`、`label`(ツリーのアクセシブルな名前)です。読み込めないフォルダは、ツリーの中にメッセージを表示します。
|
|
31
|
+
- `renderProjectFolderExplorer(createElement, {vm, locale, marks})` は、`vm` で開いているプロジェクトフォルダのツリーを Editor の横のパネル向けに描きます。説明はフォルダの `project.source.json` と `sb3-source.json` から作り、保存のたびに読み直します。`marks(directory, update)` はそのフォルダの印を追い、止める関数を返します(Git パッケージの `followChangeMarks` など)。フォルダを開いていないときは **プロジェクトフォルダを開く…** を出し、`vm` にプロジェクトフォルダを組み込んでいないときは何も描きません。`followProjectFolder(vm, listener)` は、組み込んだフォルダと開いているディレクトリの変化を知らせます。
|
|
32
|
+
- 各行には文字色で描いたアイコンが付きます。開いた・閉じたフォルダ、作品データ(`project.source.json`・`sb3-source.json`)、JSON、画像、音、コード(`.js`・`.mjs`・`.ts`)、テキスト(`.md`・`.txt`)、その他のファイルです。画像(`.svg`・`.png`・`.jpg`・`.jpeg`・`.gif`・`.bmp`・`.webp`)は、行が画面に入るとサムネイルを表示します。2 MiB を超えるファイルと読み込めない画像はアイコンのままです。サムネイルは装飾用の `<img>` で、オブジェクト URL は行がなくなると解放します。
|
|
33
|
+
- `describeProjectFolder(project, locale, {manifest, folder})` は `descriptions` を作ります。`project.source.json`・`sb3-source.json`・`embedded-extensions.json` の説明と、各アセットのファイルを使うコスチューム・背景・音を返します。`manifest` から `assetsDirectory` を読みます。`folder` はツリーのルートから見た作品フォルダのパスです。
|
|
34
|
+
|
|
35
|
+
読み取り専用です。ファイルの作成・削除・名前の変更はできません。文字入力による検索もありません。
|
|
14
36
|
|
|
15
37
|
## 外部変更
|
|
16
38
|
|
|
@@ -28,7 +50,7 @@ TurboWarp Plus Editor で既存の sb3-toolchain v1 の作品フォルダを開
|
|
|
28
50
|
|
|
29
51
|
## 開発
|
|
30
52
|
|
|
31
|
-
Node.js 26 で `npm ci` と `npm test` を実行します。Vite で JavaScript、TypeScript で型宣言を生成します。ホストとの接続検証には `npm pack` で作る tarball を使います。`npm run test:browser` は、最小 editor runtime(`@kubohiroya/turbowarp-plus-editor-test-runtime`)の上で、フォルダの外部変更と本物の VM・ワークスペースとの結合を Chromium で試します。Editor が固定する VM と Scratch Blocks を使い、Editor
|
|
53
|
+
Node.js 26 で `npm ci` と `npm test` を実行します。Vite で JavaScript、TypeScript で型宣言を生成します。ホストとの接続検証には `npm pack` で作る tarball を使います。`npm run test:browser` は、最小 editor runtime(`@kubohiroya/turbowarp-plus-editor-test-runtime`)の上で、フォルダの外部変更と本物の VM・ワークスペースとの結合を Chromium で試します。Editor が固定する VM と Scratch Blocks を使い、Editor のビルドは要りません。フォルダの一覧も、React 16.14 で実際の一時フォルダを表示して試します。`TWPF_EXPLORER_SCREENSHOT` にファイルのパスを入れると、その画面を保存します。
|
|
32
54
|
|
|
33
55
|
Editor のヘッドレス統合テストは実ディスク上のフォルダを使い、選択画面の操作を差し替えます。OS のフォルダ選択画面を確認するときは、使い捨ての sb3-toolchain v1 作品を **ファイル → プロジェクトフォルダを開く…** から選び、読み書きを許可します。標準ブロックを変更し、**ファイル → プロジェクトフォルダに保存** を選びます。選んだフォルダの `project.source.json` が更新されたことを確かめ、同じフォルダを開き直して編集が反映されることを確認します。
|
|
34
56
|
|
package/README.md
CHANGED
|
@@ -9,8 +9,24 @@ This package opens and saves existing sb3-toolchain v1 project folders in TurboW
|
|
|
9
9
|
- `mountProjectFolder({vm, document, host})` attaches the folder session to a workspace. Call `dispose()` when the workspace is replaced.
|
|
10
10
|
- `renderProjectFolderMenu(createElement, props)` supplies the existing open and save commands to the host's file menu.
|
|
11
11
|
- The mounted session's `openDirectory(handle, confirmReplace)` accepts a directory handle already selected by the host. It uses the same project validation and unsaved-edit confirmation as the file menu. Save still targets the opened folder.
|
|
12
|
+
- The mounted session's `directory` is the folder the loaded project came from. It becomes `null` once another project loads or the folder is detached, so a host can tell projects apart by it.
|
|
12
13
|
|
|
13
|
-
The host supplies the VM, menu components, and project state callbacks. The browser must support the File System Access picker for the built-in open command. Save writes block, variable, list, sprite property, monitor and built-in extension edits to the project file, including state that changes while the project runs. Sprites can be added, removed and renamed, and costumes and sounds added or removed: new asset files are written first, then `sb3-source.json` and the project file, and asset files nothing refers to are deleted last.
|
|
14
|
+
The host supplies the VM, menu components, and project state callbacks. The browser must support the File System Access picker for the built-in open command. Save writes block, variable, list, sprite property, monitor and built-in extension edits to the project file, including state that changes while the project runs. Sprites can be added, removed and renamed, and costumes and sounds added or removed: new asset files are written first, then `sb3-source.json` and the project file, and asset files nothing refers to are deleted last. See [Editor issue #305](https://github.com/kubohiroya/turbowarp-plus-editor/issues/305) and [issue #308](https://github.com/kubohiroya/turbowarp-plus-editor/issues/308).
|
|
15
|
+
|
|
16
|
+
The project file keeps system and web font references. Embedded font files are saved in `assets/`.
|
|
17
|
+
|
|
18
|
+
Folders can contain embedded extension scripts and custom extension URLs. Opening a folder restores embedded scripts as data URLs and uses the Editor's extension review. Saving preserves unchanged extension files and metadata, and reports when replacing a script removes its recorded source. See [拡張機能](README.ja.md#拡張機能).
|
|
19
|
+
|
|
20
|
+
## Folder explorer
|
|
21
|
+
|
|
22
|
+
The `./explorer` entry (`@kubohiroya/turbowarp-plus-editor-project-folder/explorer`) is a tree of a folder for the Editor's side panel, built on [Headless Tree](https://headless-tree.lukasbach.com/), which is bundled. It renders with the host's React 16.14–18 (an optional peer dependency); the main entry does not use React.
|
|
23
|
+
|
|
24
|
+
- `ProjectFolderExplorer` shows `directory` (a project folder or a repository root). Folders load when expanded and sort before files, and `.git` is hidden. Arrow keys, Home and End move and expand; Enter, Space or a click on a file calls `onOpen({path, name, kind})`. Props: `directory`, `locale` (`ja…` for Japanese, otherwise English), `descriptions` and `marks` (Git status: `added`, `modified`, `deleted` or `untracked`), both keyed by the path relative to `directory`, `onOpen` and `label` (the tree's accessible name). A folder that cannot be read shows a message in the tree.
|
|
25
|
+
- `renderProjectFolderExplorer(createElement, {vm, locale, marks})` renders that explorer on the project folder open for `vm`, for the Editor's side panel, with descriptions from the folder's `project.source.json` and `sb3-source.json` (read again after each save). `marks(directory, update)` follows marks for the directory and returns the function that stops it, such as the Git package's `followChangeMarks`. With no folder open it offers **Open Project Folder…**; it renders nothing while no project folder is mounted for `vm`. `followProjectFolder(vm, listener)` reports the mounted folder and its open directory as they change.
|
|
26
|
+
- Each row has an icon drawn in the text color: an open or closed folder, project data (`project.source.json`, `sb3-source.json`), JSON, image, sound, code (`.js`, `.mjs`, `.ts`), text (`.md`, `.txt`) or another file. Images (`.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`) show a thumbnail once their row is on screen; files over 2 MiB, and images that cannot be read, keep the icon. Thumbnails are decorative `<img>` elements from object URLs, which are revoked when the row goes away.
|
|
27
|
+
- `describeProjectFolder(project, locale, {manifest, folder})` builds `descriptions`: what `project.source.json`, `sb3-source.json` and `embedded-extensions.json` are, and which costumes, backdrops and sounds use each asset file. `manifest` supplies `assetsDirectory`; `folder` is the project folder's path under the tree's root.
|
|
28
|
+
|
|
29
|
+
The explorer only reads. It does not create, delete or rename files, and has no type-ahead search.
|
|
14
30
|
|
|
15
31
|
## External changes
|
|
16
32
|
|
|
@@ -28,7 +44,7 @@ Script replacements are checked against the VM before any change, and every targ
|
|
|
28
44
|
|
|
29
45
|
## Development
|
|
30
46
|
|
|
31
|
-
Use Node.js 26, then run `npm ci` and `npm test`. Vite builds the JavaScript library, and TypeScript emits the declarations. `npm pack` creates a tarball for host integration checks. `npm run test:browser` runs the folder's external changes against a real VM and workspace in Chromium on the minimal editor runtime (`@kubohiroya/turbowarp-plus-editor-test-runtime`), with the Editor's pinned VM and Scratch Blocks and without building the Editor.
|
|
47
|
+
Use Node.js 26, then run `npm ci` and `npm test`. Vite builds the JavaScript library, and TypeScript emits the declarations. `npm pack` creates a tarball for host integration checks. `npm run test:browser` runs the folder's external changes against a real VM and workspace in Chromium on the minimal editor runtime (`@kubohiroya/turbowarp-plus-editor-test-runtime`), with the Editor's pinned VM and Scratch Blocks and without building the Editor. It also renders the explorer with React 16.14 over a real temporary folder; set `TWPF_EXPLORER_SCREENSHOT` to a file path to save a screenshot of it.
|
|
32
48
|
|
|
33
49
|
The Editor's headless integration test uses an actual disk directory and substitutes the picker interaction. To verify the native picker separately, open a disposable sb3-toolchain v1 project with **File → Open Project Folder…**, accept read/write access, edit a standard block, and select **File → Save to Project Folder**. Check that `project.source.json` changed in the chosen directory and reopen the same folder to confirm the edit.
|
|
34
50
|
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import * as React from 'react';
|
|
2
|
+
import type { Json, Project } from './source.js';
|
|
3
|
+
export type ExplorerMark = 'added' | 'modified' | 'deleted' | 'untracked';
|
|
4
|
+
export type ExplorerEntry = {
|
|
5
|
+
path: string;
|
|
6
|
+
name: string;
|
|
7
|
+
kind: 'file' | 'directory';
|
|
8
|
+
};
|
|
9
|
+
export type ProjectFolderExplorerProps = {
|
|
10
|
+
/** The folder to show: a project folder or a repository root. It is only read. */
|
|
11
|
+
directory: FileSystemDirectoryHandle;
|
|
12
|
+
/** 'ja…' shows Japanese text; anything else shows English. */
|
|
13
|
+
locale?: string;
|
|
14
|
+
/** Extra text for an entry, by path relative to `directory`, such as `assets/<md5>.svg`. */
|
|
15
|
+
descriptions?: ReadonlyMap<string, string>;
|
|
16
|
+
/** Git status for an entry, by path relative to `directory`. */
|
|
17
|
+
marks?: ReadonlyMap<string, ExplorerMark>;
|
|
18
|
+
/** Called when a file is opened with Enter, Space or a click. */
|
|
19
|
+
onOpen?(entry: ExplorerEntry): void;
|
|
20
|
+
/** The tree's accessible name. Defaults to "Project folder". */
|
|
21
|
+
label?: string;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Describes the files of a project folder for `ProjectFolderExplorer`'s `descriptions`: the project, manifest and
|
|
25
|
+
* extension files, and each asset file with the costumes and sounds that use it. `folder` is the project folder's
|
|
26
|
+
* path inside the explorer's root ('' when the root is the project folder). Malformed entries are skipped.
|
|
27
|
+
*/
|
|
28
|
+
export declare function describeProjectFolder(project: Project, locale?: string, { manifest, folder }?: {
|
|
29
|
+
manifest?: Json;
|
|
30
|
+
folder?: string;
|
|
31
|
+
}): Map<string, string>;
|
|
32
|
+
/**
|
|
33
|
+
* A read-only tree of a folder for the Editor's side panel, built on Headless Tree. Folders load when expanded, folders
|
|
34
|
+
* sort before files, and `.git` is hidden. Keyboard: arrow keys, Home and End move and expand; Enter or Space opens a
|
|
35
|
+
* file. Needs React 16.14–18 from the host.
|
|
36
|
+
*/
|
|
37
|
+
export declare function ProjectFolderExplorer(props: ProjectFolderExplorerProps): React.JSX.Element;
|
|
38
|
+
/** Follows marks for the files under `directory`, by path relative to it. Returns the function that stops it. */
|
|
39
|
+
export type FollowMarks = (directory: FileSystemDirectoryHandle, update: (marks: ReadonlyMap<string, ExplorerMark>) => void) => () => void;
|
|
40
|
+
type FolderViewProps = {
|
|
41
|
+
vm: object;
|
|
42
|
+
locale?: string;
|
|
43
|
+
marks?: FollowMarks;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* Renders the explorer of the project folder open for `vm`, for a side panel of the host: its files with what each is
|
|
47
|
+
* for, and `marks` (such as the Git status) when given. It follows the folder as it opens, closes and saves; with no
|
|
48
|
+
* folder open it offers Open Project Folder…, and it renders nothing while no project folder is mounted for `vm`.
|
|
49
|
+
* Pass the same `marks` function across renders, or the marks are followed again.
|
|
50
|
+
*/
|
|
51
|
+
export declare function renderProjectFolderExplorer(createElement: (component: any, props: any, ...children: any[]) => any, { vm, locale, marks }: FolderViewProps): any;
|
|
52
|
+
export {};
|