@kubohiroya/turbowarp-plus-editor-project-folder 0.7.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 CHANGED
@@ -9,12 +9,15 @@ 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
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)
14
15
 
16
+ システムフォントと Web フォントの参照は作品データに保持し、埋め込みフォントは `assets/` に保存します。 [Editor #495](https://github.com/kubohiroya/turbowarp-plus-editor/issues/495)
17
+
15
18
  ## 拡張機能
16
19
 
17
- 埋め込み拡張の参照は、フォルダを開く際に `extensions/<id>.js` の内容とマニフェストから data URL に復元します。URL で指定されたカスタム拡張も、Editor の既存の許可画面を経て読み込みます。 `turboWarpPlus` のマニフェストとカスタムフォントを含む作品フォルダは対象外です。 [Editor #496](https://github.com/kubohiroya/turbowarp-plus-editor/issues/496) · [Editor #495](https://github.com/kubohiroya/turbowarp-plus-editor/issues/495)
20
+ 埋め込み拡張の参照は、フォルダを開く際に `extensions/<id>.js` の内容とマニフェストから data URL に復元します。URL で指定されたカスタム拡張も、Editor の既存の許可画面を経て読み込みます。 `turboWarpPlus` のマニフェストとカスタムフォントを含む作品フォルダは対象外です。 [Editor #496](https://github.com/kubohiroya/turbowarp-plus-editor/issues/496)
18
21
 
19
22
  保存時は変更のあったスクリプト、拡張のマニフェスト、作品データの順に書き、参照がなくなったファイルを最後に削除します。変更のないスクリプトと拡張のマニフェストはバイト列を保ちます。差し替えで `source` と対応する API マニフェストを外した場合は、保存時に該当する ID を通知します。2 件未満になったバンドル設定は削除します。module バンドルは管理対象の npm モジュールを必要とするため、差し替えで `source` を失った拡張も設定から外れます。
20
23
 
@@ -25,6 +28,7 @@ TurboWarp Plus Editor で既存の sb3-toolchain v1 の作品フォルダを開
25
28
  `./explorer`(`@kubohiroya/turbowarp-plus-editor-project-folder/explorer`)は、エディターのサイドパネルに置くフォルダのツリーです。[Headless Tree](https://headless-tree.lukasbach.com/) を同梱しています。描画にはホストの React 16.14〜18 を使います(省略可能な peer dependency)。メインの入口は React を使いません。
26
29
 
27
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)` は、組み込んだフォルダと開いているディレクトリの変化を知らせます。
28
32
  - 各行には文字色で描いたアイコンが付きます。開いた・閉じたフォルダ、作品データ(`project.source.json`・`sb3-source.json`)、JSON、画像、音、コード(`.js`・`.mjs`・`.ts`)、テキスト(`.md`・`.txt`)、その他のファイルです。画像(`.svg`・`.png`・`.jpg`・`.jpeg`・`.gif`・`.bmp`・`.webp`)は、行が画面に入るとサムネイルを表示します。2 MiB を超えるファイルと読み込めない画像はアイコンのままです。サムネイルは装飾用の `<img>` で、オブジェクト URL は行がなくなると解放します。
29
33
  - `describeProjectFolder(project, locale, {manifest, folder})` は `descriptions` を作ります。`project.source.json`・`sb3-source.json`・`embedded-extensions.json` の説明と、各アセットのファイルを使うコスチューム・背景・音を返します。`manifest` から `assetsDirectory` を読みます。`folder` はツリーのルートから見た作品フォルダのパスです。
30
34
 
package/README.md CHANGED
@@ -9,9 +9,12 @@ 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
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).
14
15
 
16
+ The project file keeps system and web font references. Embedded font files are saved in `assets/`.
17
+
15
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#拡張機能).
16
19
 
17
20
  ## Folder explorer
@@ -19,6 +22,7 @@ Folders can contain embedded extension scripts and custom extension URLs. Openin
19
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.
20
23
 
21
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.
22
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.
23
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.
24
28
 
@@ -35,3 +35,18 @@ export declare function describeProjectFolder(project: Project, locale?: string,
35
35
  * file. Needs React 16.14–18 from the host.
36
36
  */
37
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 {};