@kubohiroya/turbowarp-plus-editor-project-folder 0.17.0 → 0.19.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 +43 -4
- package/README.md +43 -4
- package/dist/browser-project-dialog.d.ts +1 -1
- package/dist/browser-projects.d.ts +6 -3
- package/dist/explorer.js +2 -2
- package/dist/folder-registry.d.ts +2 -2
- package/dist/index.d.ts +71 -8
- package/dist/index.js +261 -35
- package/dist/not-project-dialog.d.ts +20 -0
- package/dist/session.d.ts +14 -5
- package/dist/{shared-h5VGx9Jp.js → shared-CLo1e5zK.js} +18 -37
- package/dist/{shared-CwQoV7xd.js → shared-DkIVN2xk.js} +1 -1
- package/dist/source.d.ts +6 -6
- package/package.json +1 -1
- package/src/browser-project-dialog.ts +3 -2
- package/src/browser-projects.ts +6 -3
- package/src/folder-registry.ts +2 -2
- package/src/index.ts +171 -21
- package/src/not-project-dialog.ts +81 -0
- package/src/session.ts +24 -11
- package/src/source.ts +12 -32
package/README.ja.md
CHANGED
|
@@ -8,10 +8,10 @@ TurboWarp Plus Editor で sb3-toolchain の作品フォルダ(展開ソース
|
|
|
8
8
|
|
|
9
9
|
- `mountProjectFolder({vm, document, host})` でワークスペースに接続します。ワークスペースの切り替え時には `dispose()` を呼びます。
|
|
10
10
|
- `renderProjectFolderMenu(createElement, props)` は既存の開く・保存コマンドをホストのファイルメニューに渡します。
|
|
11
|
-
-
|
|
12
|
-
- 接続後の `openDirectory(handle, confirmReplace, root?)`
|
|
11
|
+
- 一つのフォルダには一つの作品を、フォルダのルートに置きます。ルートに `project.source.json`・`sb3-source.json`・`embedded-extensions.json` があるフォルダがプロジェクトフォルダです。ユーザーが開こうとしたフォルダ(**フォルダを開く…**、**ブラウザーに保存したフォルダを開く…**、ホストの `openDirectory`)がプロジェクトフォルダでないときは、エラーのダイアログに「このフォルダはプロジェクトフォルダではありません。」(英語では “This folder is not a project folder.”)と、その操作の言語で出し、何も開きません。開いている作品はそのまま残り、未保存の編集の確認も出さず、`followProjectFolder` の listener も呼びません。ダイアログはモーダルの `<dialog>`(`role="alertdialog"`、`data-project-folder-error="not-project"`)で、タイトルと **OK** ボタンがあり、OK で閉じるとフォーカスを元の場所に戻します。ファイルが壊れている、または対応していない形式のプロジェクトフォルダは、これまでどおり状態表示にエラーを出します。`createFromSnapshot` で新しいプロジェクトフォルダに保存する操作は変わりません。
|
|
12
|
+
- 接続後の `openDirectory(handle, confirmReplace, root?, options?)` には、ホストが選択済みのディレクトリハンドルを渡せます。ファイルメニューと同じ作品検証・未保存編集の確認を経て開き、`'opened'`・`'cancelled'`・`'not-project'`(`OpenResult`)のどれかで終わります。`'not-project'` のときは何も変わっていません。エラーのダイアログを出しますが、ホストが自分の方法で知らせるときは `options.notProjectDialog` に `false` を渡すと出しません。`options.locale` はダイアログの言語で、省略すると `mountProjectFolder` の `locale` です。保存先にはその作品フォルダを使います。`root` には、ホストが作品を見つけたフォルダとして、ユーザーが選んだフォルダを渡します。省略すると `handle` です(`options` だけを渡すときは `undefined` を渡します)。ダイアログを出さなかったホスト向けに、ダイアログを出す `showNotProjectFolderDialog({document, locale})` と、その文言を返す `notProjectFolderMessage(locale)` もあります。
|
|
13
13
|
- 接続後の `directory` は、読み込んだ作品のフォルダーのハンドルです。別の作品を読み込むか、フォルダーとの接続を外すと `null` になります。ホストは作品を見分けるのに使えます。
|
|
14
|
-
- 接続後の `root`
|
|
14
|
+
- 接続後の `root` は、その作品のためにユーザーが選んだフォルダーです。ホストが `openDirectory` に別のフォルダを渡したとき以外は `directory` そのものです。`directory` が `null` のときは `null` です。ブラウザーではフォルダーの親を読めないので、ホストは Git のリポジトリを `root` に結び付けます。
|
|
15
15
|
- `host.screenState` を渡すと、Editor の画面状態をフォルダーに保存します。渡すものは workbench の `installProjectScreenState` が返すものです。作品フォルダーは SB3 ではないので、状態は `.tw-plus/workspace.json` に入れます。フォルダーを開くと、作品を読み込む前にこれを読み、`prepareLoad(text)` で渡します。保存時は、作品が変わっていなくても `serialize()` の結果を書きます。保存時刻だけが違うときは書きません。読み書きに失敗しても、開く操作と保存は失敗にしません。セッションは `projectFolder` スライス(ツリーで開いたフォルダーと選択中の項目)も登録します。SB3 から作品フォルダを作るとき、sb3-toolchain(0.26.0 以降)が展開したスナップショットに `.tw-plus/workspace.json` があれば、そのままフォルダーに書くので、作ったフォルダーは同じ画面で開きます。スナップショットにないときは、上書きするフォルダーの古い `workspace.json` を消します。`.tw-plus` のほかのファイルは残します。
|
|
16
16
|
|
|
17
17
|
ホストは 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)
|
|
@@ -29,7 +29,7 @@ Safari と Firefox にはフォルダ選択(`showDirectoryPicker`)があり
|
|
|
29
29
|
- 作品フォルダをまだ開いていないパネルには、利用できる保存方式の説明と作成ボタンを出します。`always` でフォルダ選択と OPFS の両方が使える場合は2方式、Safari・Firefox ではブラウザー内保存の説明を出します。説明には、ボタンを押した後の操作、外部アプリからの見え方、ブラウザー内の作品を残すための書き出し方法を含めます。
|
|
30
30
|
- `renderProjectFolderExplorer` の `createFolder(location)` には、選んだ保存先(`device` または `browser`)が渡ります。ホストはこれを `createFromSnapshot({location, ...})` に渡します。`location` を省略した場合は従来どおりフォルダ選択を優先し、利用できない保存先を明示した場合は別の保存先に切り替えずエラーにします。
|
|
31
31
|
- 一覧のダイアログでは、作品フォルダを開く、ZIP で書き出す、削除することができます。保存領域の使用量と、ブラウザーが消さずに残すか(`persisted`)も表示します。閉じるボタンは X のアイコンで、名前は表示の言語に合わせます。
|
|
32
|
-
- 作品フォルダは `turbowarp-plus/projects/<id>/` に置き、表示名と時刻は `turbowarp-plus/project-info/<id>.json` に置きます。作品フォルダの外に置くので、Git
|
|
32
|
+
- 作品フォルダは `turbowarp-plus/projects/<id>/` に置き、表示名と時刻は `turbowarp-plus/project-info/<id>.json` に置きます。作品フォルダの外に置くので、Git の管理対象には入りません。フォルダを開くときは、保存したフォルダのルートの作品を読みます。`create(title, {projectPath})` と `directory(id)` は互換のために `projectPath` を受け付けて解決しますが、Editor はその下のフォルダを開きません。
|
|
33
33
|
- 同じ作品フォルダへの保存は、`navigator.locks` で作品ごとに排他します。WebKit は `createWritable({mode: 'exclusive'})` を重ねても拒否しないので、タブ間の排他はロックで行います。保存すると一覧の更新時刻が変わります。
|
|
34
34
|
- `openBrowserProjects(window)` は一覧・作成・削除・保存領域の状態を扱う口です。`chooseBrowserProject` は一覧のダイアログを、`exportBrowserProject` と `zipDirectory` は ZIP の書き出しを、ホストが直接使うためのものです。ZIP は圧縮せず、名前を UTF-8 で書きます。
|
|
35
35
|
|
|
@@ -37,6 +37,45 @@ Safari と Firefox にはフォルダ選択(`showDirectoryPicker`)があり
|
|
|
37
37
|
|
|
38
38
|
保存先選択の導入は、このパッケージを先に公開し、Editor の依存をその版へ固定してからホストの結線を反映します。切り戻すときは Editor の結線と依存の固定を一緒に戻します。OPFS に作成済みの作品は削除せず、ブラウザー内の一覧から開く・ZIP で書き出す経路を維持します。
|
|
39
39
|
|
|
40
|
+
## フォルダの作成・写し・改名
|
|
41
|
+
|
|
42
|
+
新しい作品を作る、写しを保存する、作品名を変えるホストは、自前の補助関数の代わりに、マウントしたセッションの次のメンバーを使います。[Editor の issue #679](https://github.com/kubohiroya/turbowarp-plus-editor/issues/679) を参照してください。
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
type ProjectFolderDestination = 'browser' | FileSystemDirectoryHandle;
|
|
46
|
+
createFromSnapshot({prepareFiles, collectEdits?, current?, title?, destination?, directory?, location?}): Promise<OpenResult>;
|
|
47
|
+
copyToFolder({destination, prepareFiles, collectEdits?, current?, title?}): Promise<FileSystemDirectoryHandle | null>;
|
|
48
|
+
pickEmptyFolder({locale?, id?}?): Promise<FileSystemDirectoryHandle | null>;
|
|
49
|
+
renameCurrentBrowserFolder(title: string): Promise<boolean>;
|
|
50
|
+
readonly location: 'browser' | 'device' | null;
|
|
51
|
+
readonly locations: readonly ('device' | 'browser')[];
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
- `createFromSnapshot({destination})` は、新しいプロジェクトフォルダを作成先に書き、`destination` がないときと同じく開きます。`'browser'` はブラウザーの保存領域に `browserProjects.create(title, {projectPath: ''})` で新しいフォルダを作り(`title` の既定は `Project`)、そこから作品が開かなかったとき、つまりユーザーが断ったとき、`current()` が偽になったとき、準備や書き込みに失敗したときには、そのフォルダを消します。ディレクトリのハンドルは、ホストが端末で選んだフォルダです。フォルダ選択は開きません。空でないフォルダは、これまでどおりユーザーが確かめたときだけ上書きします。ブラウザー内のフォルダが使えないときの `'browser'` は、`prepareFiles` を呼ぶ前に `unsupported` で失敗します。`destination` がなければ、`directory` と `location` はこれまでどおりです。
|
|
55
|
+
- `copyToFolder({destination, title, prepareFiles})` は、プロジェクトフォルダを書くだけで開きません(プロジェクトのコピーを保存)。開いている作品、`directory`・`root`・`location` は変わらず、`followProjectFolder` の listener も呼びません。`collectEdits`、`prepareFiles` の順に呼び、`createProjectFolder` で書いて、書いたフォルダを返します。`'browser'` は `title` という名前の新しいフォルダを作り、何も書かなかったときは消します。端末の空でないフォルダは、ユーザーが確かめたときだけ上書きします。ユーザーが断ったときや `current()` が偽になったときは、何も書かずに `null` を返します。開いているプロジェクトフォルダそのものとその `root`(`isSameEntry` で比べます)は、何も尋ねず何も書かずに `conflict` で断ります。そこへ書くのは保存です。
|
|
56
|
+
- `pickEmptyFolder({locale, id})` は端末のフォルダ選択(`showDirectoryPicker({id, mode: 'readwrite'})`、`id` の既定は `turbowarp-plus-project-folder`)を開き、空のフォルダならそれを返します。ユーザーが取り消したときと、空でないフォルダを選んだときは `null` を返し、後者ではモーダルのダイアログに「このフォルダは使えません」「空のフォルダを選んでください。」(英語では “Cannot Use This Folder”、“Choose an empty folder.”)を `locale` の言語で出します。ダイアログはプロジェクトフォルダでないときと同じ `<dialog>` で、`data-project-folder-error="not-empty"` を持ち、閉じてから `null` を返します。ブラウザーはクリックの処理中にしかフォルダ選択を開かないので、クリックを処理している間に呼びます。端末のフォルダを選べないブラウザーでは `unsupported` で失敗します。
|
|
57
|
+
- `renameCurrentBrowserFolder(title)` は、開いているフォルダの、このブラウザーのフォルダ一覧での名前を `title` にし(`browserProjects.find` と `rename`)、`true` を返します。フォルダが開いていないときや、開いているのが端末のフォルダのとき(ブラウザーからは名前を変えられません)は、何も変えずに `false` を返します。
|
|
58
|
+
- `location` は開いているフォルダの場所です。このブラウザー内なら `browser`、それ以外は `device`、開いていなければ `null` です。`locations` は新しいフォルダを作れる場所の一覧で、`followProjectFolder` が伝えるものと同じです。
|
|
59
|
+
|
|
60
|
+
自前の補助関数を持つホストは、次のように置き換えます。
|
|
61
|
+
|
|
62
|
+
| ホストの補助関数 | 置き換え先 |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| ホストが新しいブラウザー内のフォルダを作って消す `createFolder(…, destination)` | `createFromSnapshot({destination, title, prepareFiles, collectEdits, current})` |
|
|
65
|
+
| 選んだフォルダや新しいブラウザー内のフォルダに `createProjectFolder` で書くコピーの保存 | `copyToFolder({destination, title, prepareFiles, collectEdits, current})` |
|
|
66
|
+
| 空でないフォルダを断るフォルダ選択 | `pickEmptyFolder({locale})` |
|
|
67
|
+
| ホストが自分で調べた `{browser, device}` | `locations.includes('browser')`、`locations.includes('device')` |
|
|
68
|
+
| 作品名の変更後の `browserProjects.find(root)` と `rename` | `renameCurrentBrowserFolder(title)`。`false` ならフォルダ名は変わりません |
|
|
69
|
+
|
|
70
|
+
## 0.17.0 の後の互換性のない変更: 作品はフォルダのルートに置く
|
|
71
|
+
|
|
72
|
+
0.16.0 では、選んだフォルダの直下に作品がないとき、その中の `project` フォルダの作品を開きました(Project Starter が作るリポジトリの形)。この切り替えはなくしました。一つの Git リポジトリには一つの作品を、そのルートに置きます。
|
|
73
|
+
|
|
74
|
+
- 作品を `project/` に置いたリポジトリは、プロジェクトフォルダではなくなります。開くとエラーのダイアログを出します。作品のファイルをリポジトリのルートに移すか、`project` フォルダそのものを開いてください。
|
|
75
|
+
- 古い形でブラウザーに保存したフォルダ(`projectPath: 'project'` の項目)も、ほかと同じく保存したフォルダのルートを開くので、エラーのダイアログを出します。このパッケージは移し替えをしません。ZIP で書き出して残し、その `project` フォルダを端末のフォルダとして開くか、sb3-toolchain で SB3 にしてから、ブラウザーの新しいフォルダに保存し直してください。
|
|
76
|
+
- `root` は、ホストが `openDirectory` に `root` を渡したとき以外は、作品フォルダそのものです。
|
|
77
|
+
- `OpenResult` に `'not-project'` が加わりました。結果を `'opened'` と `'cancelled'` だけで見分けていたホストは、これも扱ってください。
|
|
78
|
+
|
|
40
79
|
## ブロックパレットの設定
|
|
41
80
|
|
|
42
81
|
TurboWarp Plus Editor は、ブロックパレットの設定を画面状態(`.tw-plus/workspace.json`)に保存するようになりました。この節の形式 2 の読み書きは、それ以前に作られた作品フォルダのために残しています。
|
package/README.md
CHANGED
|
@@ -8,10 +8,10 @@ This package opens and saves sb3-toolchain project folders (source formats 1 and
|
|
|
8
8
|
|
|
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
|
-
-
|
|
12
|
-
- The mounted session's `openDirectory(handle, confirmReplace, root?)` accepts a directory handle already selected by the host. It uses the same project validation
|
|
11
|
+
- One folder holds one project, at its root. A folder is a project folder when its root has `project.source.json`, `sb3-source.json` and `embedded-extensions.json`. When the folder the user opens (with **Open Folder…**, **Open Folder Saved in This Browser…** or a host's `openDirectory`) is not a project folder, an error dialog says “This folder is not a project folder.” (Japanese: 「このフォルダはプロジェクトフォルダではありません。」) in the locale of the command, and nothing opens: the open project stays, unsaved edits are not asked about, and `followProjectFolder` listeners are not called. The dialog is a modal `<dialog>` (`role="alertdialog"`, `data-project-folder-error="not-project"`) with a title and an **OK** button that closes it and returns the focus. A project folder whose files are broken or of an unsupported format reports its error in the status line as before. Saving a new project folder with `createFromSnapshot` is not affected.
|
|
12
|
+
- The mounted session's `openDirectory(handle, confirmReplace, root?, options?)` accepts a directory handle already selected by the host. It uses the same project validation and unsaved-edit confirmation as the file menu, and resolves with `'opened'`, `'cancelled'` or `'not-project'` (`OpenResult`). With `'not-project'` nothing changed, and the error dialog is shown unless `options.notProjectDialog` is `false`, for a host that tells the user in its own way; `options.locale` sets the dialog's locale, which defaults to the `locale` of `mountProjectFolder`. Save still targets the opened project folder. `root` names the folder the user chose, for a host that located the project in it; it defaults to `handle` (pass `undefined` to give only `options`). `showNotProjectFolderDialog({document, locale})` shows the dialog, and `notProjectFolderMessage(locale)` gives its message, for hosts that opted out.
|
|
13
13
|
- 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.
|
|
14
|
-
- The mounted session's `root` is the folder the user chose for that project: `directory` itself,
|
|
14
|
+
- The mounted session's `root` is the folder the user chose for that project: `directory` itself, unless a host gave another folder to `openDirectory`. It is `null` whenever `directory` is. The browser cannot read a folder's parent, so a host binds a Git repository to `root`.
|
|
15
15
|
- `host.screenState` keeps the Editor's screen state in the folder, as the workbench's `installProjectScreenState` provides it. A project folder is not an SB3, so the state goes into `.tw-plus/workspace.json`. Opening the folder reads it and passes it with `prepareLoad(text)` before the project loads. Saving writes `serialize()`, even when the project itself is unchanged, and skips the write when only the save time differs. A failure to read or write it never fails the open or the save. The session also registers the `projectFolder` slice: the expanded folders and the selected entry of the explorer. When a folder is created from an SB3, a `.tw-plus/workspace.json` in the snapshot sb3-toolchain (0.26.0 or later) unpacked is written into the folder as it is, so the new folder opens with the same screen. A snapshot without one removes the old `workspace.json` of the folder it overwrites, and keeps the other files in `.tw-plus`.
|
|
16
16
|
|
|
17
17
|
The host supplies the VM, menu components, and project state callbacks. The built-in open command needs the File System Access folder picker or [project folders in the browser](#project-folders-in-the-browser). 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).
|
|
@@ -31,12 +31,51 @@ Safari and Firefox have no folder picker (`showDirectoryPicker`). In these brows
|
|
|
31
31
|
- Before a folder is open, the explorer explains each available destination and offers its creation button. With `always`, browsers supporting both the picker and OPFS show both choices; Safari and Firefox explain browser storage. The text describes the next step, access from other apps, and how to keep an exported copy.
|
|
32
32
|
- The explorer calls its host's `createFolder(location)` with `device` or `browser`. Forward this to `createFromSnapshot({location, ...})`. Omitting `location` preserves the existing picker-first behavior. An explicitly unavailable destination fails instead of silently switching storage.
|
|
33
33
|
- The dialog opens, exports as a ZIP, and deletes the folders. It shows how much storage is used and whether the browser keeps it (`persisted`). Its close button is an X icon named in the display language.
|
|
34
|
-
- A folder lives at `turbowarp-plus/projects/<id>/`, and its name and times at `turbowarp-plus/project-info/<id>.json`, outside the folder, so Git never tracks them.
|
|
34
|
+
- A folder lives at `turbowarp-plus/projects/<id>/`, and its name and times at `turbowarp-plus/project-info/<id>.json`, outside the folder, so Git never tracks them. Opening a folder reads the project at the root of that stored folder. `create(title, {projectPath})` and `directory(id)` still accept and resolve `projectPath` for compatibility, but the Editor does not open the folder below it.
|
|
35
35
|
- Saves to the same folder are serialized per folder with `navigator.locks`. WebKit does not refuse a second `createWritable({mode: 'exclusive'})`, so the lock is what keeps tabs apart. A save updates the folder's time in the list.
|
|
36
36
|
- `openBrowserProjects(window)` lists, creates and deletes the folders and reports the storage. `chooseBrowserProject` shows the dialog, and `exportBrowserProject` and `zipDirectory` write the ZIP, for hosts that use them directly. The ZIP is stored without compression and names entries in UTF-8.
|
|
37
37
|
|
|
38
38
|
The browser may delete these folders when site data is cleared or the site is not used for a while (seven days in Safari). Creating the first folder asks for `navigator.storage.persist()`, which is not a guarantee. The dialog tells the user to export a ZIP or push to GitHub with Git to keep a copy.
|
|
39
39
|
|
|
40
|
+
## Creating, copying and renaming folders
|
|
41
|
+
|
|
42
|
+
A host that makes new projects, saves copies or renames projects uses these members of the mounted session instead of its own helpers. See [Editor issue #679](https://github.com/kubohiroya/turbowarp-plus-editor/issues/679).
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
type ProjectFolderDestination = 'browser' | FileSystemDirectoryHandle;
|
|
46
|
+
createFromSnapshot({prepareFiles, collectEdits?, current?, title?, destination?, directory?, location?}): Promise<OpenResult>;
|
|
47
|
+
copyToFolder({destination, prepareFiles, collectEdits?, current?, title?}): Promise<FileSystemDirectoryHandle | null>;
|
|
48
|
+
pickEmptyFolder({locale?, id?}?): Promise<FileSystemDirectoryHandle | null>;
|
|
49
|
+
renameCurrentBrowserFolder(title: string): Promise<boolean>;
|
|
50
|
+
readonly location: 'browser' | 'device' | null;
|
|
51
|
+
readonly locations: readonly ('device' | 'browser')[];
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
- `createFromSnapshot({destination})` writes the new project folder to the destination and opens it, as without `destination`. `'browser'` makes a new folder in the browser's storage with `browserProjects.create(title, {projectPath: ''})` (`title` defaults to `Project`) and removes it again unless the project opens from it: when the user declines, `current()` turns false, or preparing or writing fails. A directory handle is a folder the host picked on the device; no picker opens. A folder that is not empty is overwritten only when the user confirms it, as before. `'browser'` without the browser's folders rejects with `unsupported` before `prepareFiles` runs. Without `destination`, `directory` and `location` work as before.
|
|
55
|
+
- `copyToFolder({destination, title, prepareFiles})` writes a project folder and does not open it (Save a Copy): the open project, `directory`, `root` and `location` stay, and `followProjectFolder` listeners are not called. It calls `collectEdits` and then `prepareFiles`, writes with `createProjectFolder`, and resolves with the folder written. `'browser'` makes a new folder named `title`, removed again when nothing is written. A folder on the device that is not empty is overwritten only when the user confirms it; when the user declines or `current()` turns false, it resolves with `null` and writes nothing. The open project folder itself and its `root` (compared with `isSameEntry`) are refused with `conflict` before anything is asked or written; Save writes there.
|
|
56
|
+
- `pickEmptyFolder({locale, id})` opens the device's folder picker (`showDirectoryPicker({id, mode: 'readwrite'})`, `id` defaults to `turbowarp-plus-project-folder`) and resolves with the folder when it is empty. It resolves with `null` when the user cancelled, and when the folder is not empty, which a modal dialog tells in `locale`: “Cannot Use This Folder” with “Choose an empty folder.” (Japanese: 「このフォルダは使えません」, 「空のフォルダを選んでください。」). The dialog is the same `<dialog>` as the not-project one, with `data-project-folder-error="not-empty"`, and the call resolves once it closes. Call it while handling the user's click, because the browser opens the picker only then. Where the browser cannot pick folders on the device it rejects with `unsupported`.
|
|
57
|
+
- `renameCurrentBrowserFolder(title)` gives the open folder the title in the list of folders kept in this browser (`browserProjects.find` and `rename`) and resolves with `true`. It resolves with `false` and changes nothing when no folder is open or the open folder is on the device, whose name the browser cannot change.
|
|
58
|
+
- `location` is where the open folder is: `browser` for a folder kept in this browser, `device` for another, and `null` while none is open. `locations` lists where new folders can be made, as `followProjectFolder` reports it.
|
|
59
|
+
|
|
60
|
+
A host that had its own helpers replaces them like this:
|
|
61
|
+
|
|
62
|
+
| Host helper | Replacement |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| `createFolder(…, destination)` with a new browser folder made and removed by the host | `createFromSnapshot({destination, title, prepareFiles, collectEdits, current})` |
|
|
65
|
+
| Save a Copy writing with `createProjectFolder` into a picked or new browser folder | `copyToFolder({destination, title, prepareFiles, collectEdits, current})` |
|
|
66
|
+
| A picker that refuses a folder that is not empty | `pickEmptyFolder({locale})` |
|
|
67
|
+
| `{browser, device}` from the host's own checks | `locations.includes('browser')`, `locations.includes('device')` |
|
|
68
|
+
| `browserProjects.find(root)` and `rename` after the title changes | `renameCurrentBrowserFolder(title)`; `false` means the folder keeps its name |
|
|
69
|
+
|
|
70
|
+
## Breaking change after 0.17.0: the project is at the folder's root
|
|
71
|
+
|
|
72
|
+
0.16.0 opened the `project` folder of a chosen folder that had no project of its own, as in a repository made by Project Starter. That fallback is removed: one Git repository holds one project, at its root.
|
|
73
|
+
|
|
74
|
+
- A repository with its project in `project/` is not a project folder any more. Opening it shows the error dialog. Move the project files to the repository root, or open the `project` folder itself.
|
|
75
|
+
- A folder kept in the browser with the old layout (its entry has `projectPath: 'project'`) is opened at its stored folder like any other, so it shows the error dialog too. The package has no migration: export it as a ZIP to keep it, and open its `project` folder as a folder on the device, or build it into an SB3 with sb3-toolchain and save that as a new folder in the browser.
|
|
76
|
+
- `root` is the project folder itself unless a host passes `root` to `openDirectory`.
|
|
77
|
+
- `OpenResult` has the new value `'not-project'`. A host that compared the result with `'opened'` and `'cancelled'` only should handle it.
|
|
78
|
+
|
|
40
79
|
## Block palette settings
|
|
41
80
|
|
|
42
81
|
TurboWarp Plus Editor now saves block palette settings in its screen state (`.tw-plus/workspace.json`). Reading and writing format 2, described here, stays for project folders made before that.
|
|
@@ -9,7 +9,7 @@ export type BrowserProjectChoice = {
|
|
|
9
9
|
};
|
|
10
10
|
/**
|
|
11
11
|
* Shows the project folders kept in this browser. With `purpose: 'open'` the user picks one; with `'create'` the user
|
|
12
|
-
* names a new empty one. Resolves with the chosen folder, or `null` when the dialog closes without one.
|
|
12
|
+
* names a new empty one. Resolves with the chosen stored folder, or `null` when the dialog closes without one.
|
|
13
13
|
*/
|
|
14
14
|
export declare function chooseBrowserProject({ document, projects, locale, purpose, title }: {
|
|
15
15
|
document: Document;
|
|
@@ -4,13 +4,16 @@
|
|
|
4
4
|
* browser may delete them; a user keeps a copy by exporting a ZIP or pushing to GitHub.
|
|
5
5
|
*
|
|
6
6
|
* Layout under the OPFS root:
|
|
7
|
-
* turbowarp-plus/projects/<id>/ the folder
|
|
7
|
+
* turbowarp-plus/projects/<id>/ the folder, a project folder with the project at its root
|
|
8
8
|
* turbowarp-plus/project-info/<id>.json its title and times, kept outside the folder so Git never sees them
|
|
9
9
|
*/
|
|
10
10
|
export interface BrowserProject {
|
|
11
11
|
id: string;
|
|
12
12
|
title: string;
|
|
13
|
-
/**
|
|
13
|
+
/**
|
|
14
|
+
* A folder inside the stored folder, `''` for the stored folder itself. Only for compatibility: the Editor opens the
|
|
15
|
+
* project at the root of the stored folder, so an entry with another path is not a project folder there.
|
|
16
|
+
*/
|
|
14
17
|
projectPath: string;
|
|
15
18
|
createdAt: number;
|
|
16
19
|
updatedAt: number;
|
|
@@ -30,7 +33,7 @@ export interface BrowserProjects {
|
|
|
30
33
|
}>;
|
|
31
34
|
/** The stored folder, or `null` when it was deleted. */
|
|
32
35
|
root(id: string): Promise<FileSystemDirectoryHandle | null>;
|
|
33
|
-
/** The
|
|
36
|
+
/** The folder `projectPath` inside the entry's stored folder. Opening uses `root` instead. */
|
|
34
37
|
directory(id: string): Promise<FileSystemDirectoryHandle | null>;
|
|
35
38
|
/** The entry that holds `handle`, or `null` when it is not in the browser's storage. */
|
|
36
39
|
find(handle: FileSystemHandle): Promise<BrowserProject | null>;
|
package/dist/explorer.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { C as isObject, I as _asyncIterator, R as _objectSpread2, T as manifestFile, a as projectFolderOverwriteWarning, d as subscribeExplorerState, f as writeExplorerState, j as projectFile, l as readExplorerState, p as FolderError, s as hiddenEntry, t as followProjectFolder } from "./shared-CLo1e5zK.js";
|
|
2
2
|
import * as React from "react";
|
|
3
3
|
import { useEffect, useState } from "react";
|
|
4
4
|
import { createPortal } from "react-dom";
|
|
@@ -1463,7 +1463,7 @@ function createFilePreview(directory, documentId, { name, path }, locale, readBa
|
|
|
1463
1463
|
status.textContent = message.large;
|
|
1464
1464
|
return;
|
|
1465
1465
|
}
|
|
1466
|
-
const [bytes, { decodeText, mountTextFile }] = await Promise.all([file.arrayBuffer(), import("./shared-
|
|
1466
|
+
const [bytes, { decodeText, mountTextFile }] = await Promise.all([file.arrayBuffer(), import("./shared-DkIVN2xk.js")]);
|
|
1467
1467
|
if (disposed) return;
|
|
1468
1468
|
const content = decodeText(bytes);
|
|
1469
1469
|
if (content === null) {
|
|
@@ -3,7 +3,7 @@ export type ExplorerMutation = (guard: () => void) => Promise<void>;
|
|
|
3
3
|
export type ProjectFolderLocation = 'device' | 'browser';
|
|
4
4
|
export interface FollowedFolder {
|
|
5
5
|
readonly directory: FileSystemDirectoryHandle | null;
|
|
6
|
-
/** The folder the user chose for `directory`: itself,
|
|
6
|
+
/** The folder the user chose for `directory`: itself, unless a host gave another one to `openDirectory`. */
|
|
7
7
|
readonly root?: FileSystemDirectoryHandle | null;
|
|
8
8
|
/** Storage choices available when creating a project folder. */
|
|
9
9
|
readonly locations?: readonly ProjectFolderLocation[];
|
|
@@ -17,7 +17,7 @@ export interface FollowedFolder {
|
|
|
17
17
|
export declare function registerFolder(vm: object, folder: FollowedFolder): () => void;
|
|
18
18
|
/**
|
|
19
19
|
* Calls `listener` with the project folder mounted for `vm`, the directory open in it and the folder the user chose for
|
|
20
|
-
* it (`root`, the directory itself
|
|
20
|
+
* it (`root`, the directory itself unless a host gave another one), now and whenever a folder is
|
|
21
21
|
* mounted, opened, closed or saved. `directory` and `root` are `null` while no folder is open. Returns the function
|
|
22
22
|
* that stops it.
|
|
23
23
|
*/
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { ProjectFolderLocation } from './folder-registry.js';
|
|
2
2
|
import type { BrowserProjects } from './browser-projects.js';
|
|
3
|
-
import type { FolderHost, FolderVM } from './session.js';
|
|
3
|
+
import type { FolderHost, FolderVM, OpenResult } from './session.js';
|
|
4
4
|
export type { Comparison, ComparisonRequest, ComparisonSection, FolderHost, FolderScreenState, FolderVM, OpenResult } from './session.js';
|
|
5
5
|
export type { ReloadTarget } from './block-reload.js';
|
|
6
6
|
export { followProjectFolder } from './folder-registry.js';
|
|
@@ -11,6 +11,7 @@ export { openBrowserProjects } from './browser-projects.js';
|
|
|
11
11
|
export type { BrowserProject, BrowserProjects, BrowserStorageState } from './browser-projects.js';
|
|
12
12
|
export { chooseBrowserProject, exportBrowserProject, zipFileName } from './browser-project-dialog.js';
|
|
13
13
|
export type { BrowserProjectChoice } from './browser-project-dialog.js';
|
|
14
|
+
export { notProjectFolderMessage, showNotProjectFolderDialog } from './not-project-dialog.js';
|
|
14
15
|
export { zipDirectory } from './zip.js';
|
|
15
16
|
type MenuElement = (component: any, props: any, ...children: any[]) => any;
|
|
16
17
|
interface MenuProps {
|
|
@@ -28,6 +29,21 @@ interface MenuProps {
|
|
|
28
29
|
* - `off`: only folders on the device.
|
|
29
30
|
*/
|
|
30
31
|
export type BrowserStorageMode = 'fallback' | 'always' | 'off';
|
|
32
|
+
/** Options of `openDirectory`. */
|
|
33
|
+
export interface OpenDirectoryOptions {
|
|
34
|
+
/**
|
|
35
|
+
* Whether a folder that is not a project folder is told to the user in the error dialog (default true). A host
|
|
36
|
+
* that tells the user in its own way passes false and acts on the `not-project` result.
|
|
37
|
+
*/
|
|
38
|
+
notProjectDialog?: boolean;
|
|
39
|
+
/** The locale of the dialog; defaults to the `locale` given to `mountProjectFolder`. */
|
|
40
|
+
locale?: string;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Where `createFromSnapshot` and `copyToFolder` write: `browser` for a new folder in the browser's own storage, or a
|
|
44
|
+
* folder on the device that the host already picked, for example with `pickEmptyFolder`.
|
|
45
|
+
*/
|
|
46
|
+
export type ProjectFolderDestination = 'browser' | FileSystemDirectoryHandle;
|
|
31
47
|
/**
|
|
32
48
|
* `autoReload` (default true) applies value and position changes without a click when the Editor has no unsaved
|
|
33
49
|
* edits and the project is stopped. Other changes always wait for the reload command.
|
|
@@ -40,7 +56,13 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
|
|
|
40
56
|
autoReload?: boolean;
|
|
41
57
|
browserStorage?: BrowserStorageMode;
|
|
42
58
|
}): {
|
|
43
|
-
|
|
59
|
+
/**
|
|
60
|
+
* Opens the project at the root of `directory`, as the user's Open would, and resolves with the result. A folder
|
|
61
|
+
* that is not a project folder changes nothing, shows the error dialog unless `options.notProjectDialog` is
|
|
62
|
+
* false, and resolves with `not-project`. `root` is the folder the user chose, for a host that located the
|
|
63
|
+
* project in it; it defaults to `directory`.
|
|
64
|
+
*/
|
|
65
|
+
openDirectory: (directory: FileSystemDirectoryHandle, confirmReplace: () => boolean, root?: FileSystemDirectoryHandle | null, options?: OpenDirectoryOptions) => Promise<OpenResult>;
|
|
44
66
|
unsavedPaths: () => ReadonlySet<string> | null;
|
|
45
67
|
readUnsavedFile: (path: string) => Uint8Array<ArrayBufferLike> | null | undefined;
|
|
46
68
|
subscribeEdits: (listener: () => void) => () => void;
|
|
@@ -51,10 +73,14 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
|
|
|
51
73
|
/** The folders kept in this browser, when they are offered, for a host that lists or exports them. */
|
|
52
74
|
browserProjects: BrowserProjects | null;
|
|
53
75
|
/**
|
|
54
|
-
* Creates a project folder from a snapshot. `
|
|
55
|
-
*
|
|
76
|
+
* Creates a project folder from a snapshot and opens it. `destination` writes to a new folder in the browser's
|
|
77
|
+
* storage (`browser`, named by `title`; it is removed again unless the project opens from it) or to a folder the
|
|
78
|
+
* host picked on the device (see `pickEmptyFolder`). Without it, `directory` is the folder the host picked, and
|
|
79
|
+
* otherwise `location` (or the device picker where there is one) asks the user: `title` then names a folder
|
|
80
|
+
* made in the browser, where the user names a new folder instead of picking one. A folder that is not empty is
|
|
81
|
+
* overwritten only when the user confirms it.
|
|
56
82
|
*/
|
|
57
|
-
createFromSnapshot({ prepareFiles, collectEdits, directory, current, title, location }: {
|
|
83
|
+
createFromSnapshot({ prepareFiles, collectEdits, directory, current, title, location, destination }: {
|
|
58
84
|
prepareFiles: () => Promise<ReadonlyMap<string, Uint8Array>>;
|
|
59
85
|
collectEdits?: () => Promise<void>;
|
|
60
86
|
directory?: FileSystemDirectoryHandle;
|
|
@@ -62,15 +88,52 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
|
|
|
62
88
|
title?: string;
|
|
63
89
|
/** Explicit destination; omitted uses the device picker when available. */
|
|
64
90
|
location?: ProjectFolderLocation;
|
|
65
|
-
|
|
91
|
+
destination?: ProjectFolderDestination;
|
|
92
|
+
}): Promise<OpenResult>;
|
|
93
|
+
/**
|
|
94
|
+
* Writes a project folder from a snapshot to `destination` and leaves the open project as it is: nothing is
|
|
95
|
+
* opened or attached, `directory` and `root` stay, and `followProjectFolder` listeners are not called (Save a
|
|
96
|
+
* Copy). `browser` makes a new folder in the browser's storage named by `title`, removed again when nothing is
|
|
97
|
+
* written; a folder on the device that is not empty is overwritten only when the user confirms it. Resolves
|
|
98
|
+
* with the folder written, or `null` when the user declined or `current()` turned false. The open project
|
|
99
|
+
* folder and its `root` are refused with `conflict` before anything is asked or written.
|
|
100
|
+
*/
|
|
101
|
+
copyToFolder({ destination, prepareFiles, collectEdits, current, title }: {
|
|
102
|
+
destination: ProjectFolderDestination;
|
|
103
|
+
prepareFiles: () => Promise<ReadonlyMap<string, Uint8Array>>;
|
|
104
|
+
collectEdits?: () => Promise<void>;
|
|
105
|
+
current?: () => boolean;
|
|
106
|
+
title?: string;
|
|
107
|
+
}): Promise<FileSystemDirectoryHandle | null>;
|
|
108
|
+
/**
|
|
109
|
+
* Asks the user for an empty folder on the device, for a new project. Call it while handling the user's click,
|
|
110
|
+
* as the browser lets the folder picker open only then. Resolves with `null` when the user cancelled, or chose
|
|
111
|
+
* a folder that is not empty, which a modal dialog then tells (“Choose an empty folder.”); it resolves once the
|
|
112
|
+
* dialog closes. Rejects with
|
|
113
|
+
* `unsupported` where the browser cannot pick folders on the device.
|
|
114
|
+
*/
|
|
115
|
+
pickEmptyFolder({ locale: language, id }?: {
|
|
116
|
+
locale?: string;
|
|
117
|
+
id?: string;
|
|
118
|
+
}): Promise<FileSystemDirectoryHandle | null>;
|
|
119
|
+
/**
|
|
120
|
+
* Gives the open folder the title `title` in the list of folders kept in this browser. Resolves with `false`,
|
|
121
|
+
* changing nothing, when no folder is open or the open folder is not kept in this browser: a folder on the
|
|
122
|
+
* device keeps its name, as the browser cannot rename it.
|
|
123
|
+
*/
|
|
124
|
+
renameCurrentBrowserFolder(title: string): Promise<boolean>;
|
|
125
|
+
/** Where the open folder is: `browser` for a folder kept in this browser, `device`, or `null` with none open. */
|
|
126
|
+
readonly location: ProjectFolderLocation | null;
|
|
127
|
+
/** Where new project folders can be made: `device` with the folder picker, and `browser` with the browser's folders. */
|
|
128
|
+
locations: readonly ProjectFolderLocation[];
|
|
66
129
|
/**
|
|
67
130
|
* The folder the loaded project came from, or `null` once another project loaded or the folder was
|
|
68
131
|
* detached. A host can tell projects apart by it, for example to keep the layout of each one.
|
|
69
132
|
*/
|
|
70
133
|
readonly directory: FileSystemDirectoryHandle | null;
|
|
71
134
|
/**
|
|
72
|
-
* The folder the user chose for the loaded project, or `null` like `directory`. It is `directory` itself,
|
|
73
|
-
*
|
|
135
|
+
* The folder the user chose for the loaded project, or `null` like `directory`. It is `directory` itself, the
|
|
136
|
+
* project folder, unless the host gave another folder to `openDirectory`.
|
|
74
137
|
*/
|
|
75
138
|
readonly root: FileSystemDirectoryHandle | null;
|
|
76
139
|
dispose(): void;
|