@kubohiroya/turbowarp-plus-editor-project-folder 0.9.2 → 0.10.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
@@ -10,6 +10,7 @@ TurboWarp Plus Editor で既存の sb3-toolchain v1 の作品フォルダを開
10
10
  - `renderProjectFolderMenu(createElement, props)` は既存の開く・保存コマンドをホストのファイルメニューに渡します。
11
11
  - 接続後の `openDirectory(handle, confirmReplace)` には、ホストが選択済みのディレクトリハンドルを渡せます。ファイルメニューと同じ作品検証・未保存編集の確認を経て開き、保存先にはその作品フォルダを使います。
12
12
  - 接続後の `directory` は、読み込んだ作品のフォルダーのハンドルです。別の作品を読み込むか、フォルダーとの接続を外すと `null` になります。ホストは作品を見分けるのに使えます。
13
+ - `host.screenState` を渡すと、Editor の画面状態をフォルダーに保存します。渡すものは workbench の `installProjectScreenState` が返すものです。作品フォルダーは SB3 ではないので、状態は `.tw-plus/workspace.json` に入れます。フォルダーを開くと、作品を読み込む前にこれを読み、`prepareLoad(text)` で渡します。保存時は、作品が変わっていなくても `serialize()` の結果を書きます。保存時刻だけが違うときは書きません。読み書きに失敗しても、開く操作と保存は失敗にしません。セッションは `projectFolder` スライス(ツリーで開いたフォルダーと選択中の項目)も登録します。
13
14
 
14
15
  ホストは 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
 
@@ -27,7 +28,7 @@ TurboWarp Plus Editor で既存の sb3-toolchain v1 の作品フォルダを開
27
28
 
28
29
  `./explorer`(`@kubohiroya/turbowarp-plus-editor-project-folder/explorer`)は、エディターのサイドパネルに置くフォルダのツリーです。[Headless Tree](https://headless-tree.lukasbach.com/) を同梱しています。描画にはホストの React 16.14〜18 を使います(省略可能な peer dependency)。メインの入口は React を使いません。
29
30
 
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
+ - `ProjectFolderExplorer` は `directory`(作品フォルダまたはリポジトリのルート)を表示します。フォルダは開いたときに読み込み、ファイルより先に並べます。`.git` と `.tw-plus` は表示しません。フォルダーごとの開いたフォルダーと選択中の項目はページの中で保持するので、横のパネルを開き直すと、前と同じツリーに戻ります。矢印キー・Home・End で移動と開閉をします。ファイルで Enter・Space を押すかクリックすると `onOpen({path, name, kind})` を呼びます。props は `directory`、`locale`(`ja…` で日本語、それ以外は英語)、`descriptions` と `marks`(Git の状態: `added`・`modified`・`deleted`・`untracked`、どちらも `directory` からの相対パスがキー)、`onOpen`、`label`(ツリーのアクセシブルな名前)です。読み込めないフォルダは、ツリーの中にメッセージを表示します。
31
32
  - `renderProjectFolderExplorer(createElement, {vm, locale, marks})` は、`vm` で開いているプロジェクトフォルダのツリーを Editor の横のパネル向けに描きます。説明はフォルダの `project.source.json` と `sb3-source.json` から作り、保存のたびに読み直します。`marks(directory, update)` はそのフォルダの印を追い、止める関数を返します(Git パッケージの `followChangeMarks` など)。フォルダを開いていないときは **プロジェクトフォルダを開く…** を出し、`vm` にプロジェクトフォルダを組み込んでいないときは何も描きません。`followProjectFolder(vm, listener)` は、組み込んだフォルダと開いているディレクトリの変化を知らせます。
32
33
  - 各行には文字色で描いたアイコンが付きます。開いた・閉じたフォルダ、作品データ(`project.source.json`・`sb3-source.json`)、JSON、画像、音、コード(`.js`・`.mjs`・`.ts`)、テキスト(`.md`・`.txt`)、その他のファイルです。画像(`.svg`・`.png`・`.jpg`・`.jpeg`・`.gif`・`.bmp`・`.webp`)は、行が画面に入るとサムネイルを表示します。2 MiB を超えるファイルと読み込めない画像はアイコンのままです。サムネイルは装飾用の `<img>` で、オブジェクト URL は行がなくなると解放します。
33
34
  - `describeProjectFolder(project, locale, {manifest, folder})` は `descriptions` を作ります。`project.source.json`・`sb3-source.json`・`embedded-extensions.json` の説明と、各アセットのファイルを使うコスチューム・背景・音を返します。`manifest` から `assetsDirectory` を読みます。`folder` はツリーのルートから見た作品フォルダのパスです。
package/README.md CHANGED
@@ -10,6 +10,7 @@ This package opens and saves existing sb3-toolchain v1 project folders in TurboW
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
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.
13
+ - `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.
13
14
 
14
15
  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
 
@@ -21,7 +22,7 @@ Folders can contain embedded extension scripts and custom extension URLs. Openin
21
22
 
22
23
  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
 
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
+ - `ProjectFolderExplorer` shows `directory` (a project folder or a repository root). Folders load when expanded and sort before files, and `.git` and `.tw-plus` are hidden. The expanded folders and the selected entry of each folder are kept for the page, so the tree comes back as it was when the side panel shows it again. 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
26
  - `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
27
  - 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
28
  - `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.
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The expanded folders and the selected entry of each project folder's explorer, for this page. It outlives the
3
+ * explorer, which unmounts whenever the side panel shows another view, so the tree comes back as it was left, and
4
+ * the Editor's screen state reads it from here when a project is saved.
5
+ */
6
+ export interface ExplorerTreeState {
7
+ /** Folder paths relative to the project folder, such as `assets`. */
8
+ expanded: readonly string[];
9
+ /** The selected entry, a path relative to the project folder. */
10
+ selected?: string;
11
+ }
12
+ /** The folder the Editor keeps its own files in. The explorer and its search leave it out, like `.git`. */
13
+ export declare const editorDirectory = ".tw-plus";
14
+ /** The screen state of the Editor, inside `editorDirectory`. */
15
+ export declare const screenStateFile = "workspace.json";
16
+ export declare const hiddenEntry: (name: string) => boolean;
17
+ /** Read a tree state saved in a file, keeping only well-formed paths. */
18
+ export declare function parseExplorerState(value: unknown): ExplorerTreeState | undefined;
19
+ export declare const readExplorerState: (directory: FileSystemDirectoryHandle) => ExplorerTreeState | undefined;
20
+ /** Remember the tree of `directory`. With `notify`, a mounted explorer of that folder shows it too. */
21
+ export declare function writeExplorerState(directory: FileSystemDirectoryHandle, state: ExplorerTreeState, notify?: boolean): void;
22
+ export declare function subscribeExplorerState(directory: FileSystemDirectoryHandle, listener: (state: ExplorerTreeState) => void): () => void;
@@ -34,6 +34,8 @@ export type ProjectFolderExplorerProps = {
34
34
  unsavedPaths?: ReadonlySet<string>;
35
35
  /** Changes after the folder contents have been saved or reloaded. */
36
36
  refreshKey?: number;
37
+ /** Case-insensitive search by file name or relative path. */
38
+ query?: string;
37
39
  /** Called when a file is opened with Enter, Space or a click. */
38
40
  onOpen?(entry: ExplorerEntry): void;
39
41
  /** The tree's accessible name. Defaults to "Project folder". */
@@ -68,6 +70,9 @@ type FolderViewProps = {
68
70
  createFolder?(): Promise<unknown>;
69
71
  marks?: FollowMarks;
70
72
  fileStatuses?: FollowFileStatuses;
73
+ /** Reports unsaved text edits in open file tabs for the given folder. */
74
+ followFileEdits?(directory: FileSystemDirectoryHandle, update: (paths: readonly string[]) => void): () => void;
75
+ query?: string;
71
76
  git?: FollowExplorerGit;
72
77
  /** Opens a transient file tab in the host workspace. */
73
78
  openFile?(request: FilePreviewRequest): boolean;