@kubohiroya/turbowarp-plus-editor-git 0.17.0 → 0.18.0

package/README.ja.md

@@ -2,7 +2,9 @@
 
 [English](README.md)
 
-TurboWarp Plus Editor のファイルメニューに「ローカル Git」を追加します。リポジトリルートを一度選び、配下の sb3-toolchain v1 作品フォルダをパネルから開きます。作品の編集と保存には Editor の project-folder 接続を使います。
+TurboWarp Plus Editor に「ローカル Git」パネルを追加します。リポジトリルートを一度選び、配下の sb3-toolchain v1 作品フォルダをパネルから開きます。作品の編集と保存には Editor の project-folder 接続を使います。
+
+パネルは、Editor のメニューバーのブランチのボタンから開きます。`mountGitPanel({vm, document, host})` はパネルを組み込み、`{open(locale), refresh(), dispose()}` を返します。`renderBranchButton(createElement, {vm, locale})` は、`vm` に組み込んだパネルのボタンを描きます。パネルがないとき（ホストがローカル Git を出さないときなど）は何も描きません。ボタンはブランチのアイコン、現在のブランチ名、▾ を表示します。リポジトリを選ぶ前は **Git** と表示し、**リポジトリを選択…** に進みます。detached HEAD ではコミットの短い ID を、記録がまだないブランチではそのことを表示します。メニュー（`role="menu"`。矢印キー・Home・End・Enter で操作し、Escape でボタンに戻ります）には、ローカルブランチ（現在のブランチに印）、`origin` にあってローカルにないブランチの **… を作って切り替える**、**新しいブランチ…**（HEAD からブランチを作る小さな欄。既定で作ったら切り替えます）、**ローカル Git を開く** を並べます。ボタンとパネルは同じリポジトリと同じ操作を使うので、メニューからの切り替えも、パネルのボタンと同じく確かめ、同じ理由で断ります。切り替えた後は、パネルを開いて結果（**作品を再読込** の案内など）を示します。`localWrite` がなければ、メニューはブランチを示すだけです。ボタンは、パネルやほかのツールでのブランチの変更に追従します。パネルが見えていない間は、下のパネルの確認と同じ契機で、HEAD とブランチの参照だけを読みます。`BranchButton` は、状態をホストが持つ場合のためのボタン単体です。
 
 ステージ済み・未ステージ・未追跡の変更、現在のブランチ、HEAD、ローカルブランチと履歴を表示します。ファイルを選ぶとテキスト差分またはバイナリのサイズを確認できます。作品データ（`project.source.json`）は、ホストがブロックの描画関数を渡していればステージ・スプライト別、コード別のブロックで比べ、「テキスト」に切り替えると行単位の差分を表示します。ステージ・スプライトの見出しには、その版の現在のコスチューム（ステージは背景）のサムネイルを添えます。素材は比較する版から読みます（ステージ済みは HEAD とインデックス、未ステージはインデックスと作業ツリー、未追跡は作業ツリー、コミットは第一親とそのコミット）。素材のフォルダはその版の `sb3-source.json` の `assetsDirectory`（既定は `assets`）です。読めない版では名前だけを示します。コミットを選ぶと第一親との差分を表示します。作品を選んでいるときは、変更一覧と差分をそのフォルダに絞ります。
 
@@ -14,7 +16,7 @@ TurboWarp Plus Editor のファイルメニューに「ローカル Git」を追
 
 File System Access に対応する Chromium 系ブラウザーが必要です。初版は通常の `.git` ディレクトリとファイル内容の変更を扱います。linked worktree、サブモジュール、シンボリックリンクは対象外です。作業ツリーの実行権限の変更はブラウザーから検出できません。Git に記録済みのファイルモードは表示します。バイナリアセットはサイズを示し、テキスト差分の生成には上限があります。
 
-Node.js 26 で `npm ci` と `npm test` を実行します。Vite でライブラリとスタイルシート、TypeScript で型宣言を生成します。`npm pack` で Editor 用の配布物を作成します。`npm run test:browser` は、最小 editor runtime（`@kubohiroya/turbowarp-plus-editor-test-runtime`）の上で、履歴グラフのキーボード操作と操作メニュー、比較ダイアログのブロックの描画を Chromium で試します。Editor が固定する VM と Scratch Blocks を使い、Editor のビルドは要りません。Editor では既定で有効です。起動 URL に `twPlusLocalGit=0` を指定するとパネルの接続を解除できます。
+Node.js 26 で `npm ci` と `npm test` を実行します。Vite でライブラリとスタイルシート、TypeScript で型宣言を生成します。`npm pack` で Editor 用の配布物を作成します。`npm run test:browser` は、最小 editor runtime（`@kubohiroya/turbowarp-plus-editor-test-runtime`）の上で、ブランチのボタンのメニューとキーボード操作（実際のリポジトリでパネルと並べた場合も）、履歴グラフのキーボード操作と操作メニュー、比較ダイアログのブロックの描画を Chromium で試します。Editor が固定する VM と Scratch Blocks を使い、Editor のビルドは要りません。Editor では既定で有効です。起動 URL に `twPlusLocalGit=0` を指定するとパネルの接続を解除でき、ブランチのボタンも出ません。
 
 パネルの構成とローカル Git の扱いは [duff](https://github.com/chigichan24/duff) を参考にしました。実装には [isomorphic-git](https://github.com/isomorphic-git/isomorphic-git) と [react-diff-view](https://github.com/otakustay/react-diff-view) を使用し、同梱依存のライセンスはビルド時の第三者ライセンス一覧に収録します。
 

package/README.md

@@ -4,6 +4,8 @@
 
 Local Git adds a panel to the TurboWarp Plus Editor File menu. Select the repository root once, then browse to an sb3-toolchain v1 project folder inside it. Project editing and saving are supplied by the Editor's project-folder integration.
 
+The panel opens from a branch button in the Editor's menu bar. `mountGitPanel({vm, document, host})` mounts the panel and returns `{open(locale), refresh(), dispose()}`; `renderBranchButton(createElement, {vm, locale})` renders the button for the panel mounted for `vm`, and renders nothing while there is none (such as when the host does not offer local Git). The button shows a branch icon, the current branch and ▾. Before a repository is chosen it reads **Git** and offers **Choose Repository…**; a detached HEAD shows its short commit ID, and a branch without records yet says so. Its menu (`role="menu"`; arrow keys, Home and End, Enter, Escape back to the button) lists the local branches with the current one checked, then **Create and switch to …** for `origin` branches without a local one, **New Branch…** (a small form that creates a branch at HEAD, switching to it by default) and **Open Local Git**. The button and the panel share one repository and the same operations, so switching from the menu asks and refuses exactly as the panel's own buttons do; the panel then opens with the result, such as the hint to **Reload Project**. Without `localWrite` the menu lists the branches only. The button follows branch changes made in the panel or by other tools: while the panel is out of view, the panel's checks below read only HEAD and the branch refs. `BranchButton` is the button on its own, for hosts that keep the state themselves.
+
 The panel separates staged, unstaged, and untracked changes. It shows the current branch, HEAD, local branches, and the history. Select a file to inspect its text diff or binary size. When the host supplies a block renderer, project data (`project.source.json`) is compared as blocks by stage, sprite and code, and **Text** switches to the line diff. Each stage and sprite heading shows a thumbnail of its current costume (the backdrop for the stage) in each version. Assets are read from the compared versions: HEAD and the index for staged changes, the index and the working tree for unstaged changes, the working tree for untracked files, and the first parent and the commit for history. The assets folder is the `assetsDirectory` of that version's `sb3-source.json` (`assets` by default). When an asset cannot be read, only the name is shown. Pull request reviews read the same thumbnails from raw.githubusercontent.com at the merge base and head, without using the GitHub API rate limit. A review's **Reviewed** marks are kept in browser storage per repository and pull request, together with each script's content: they survive closing the panel and reloading the Editor, and only the marks of scripts whose content changed are cleared when the pull request head moves. They are never written to project files or Git. Select a commit to compare its files with its first parent. The selected project limits the file list and diffs to that folder.
 
 While the panel is open, it checks the repository every two seconds, when the window regains focus, and on `FileSystemObserver` notifications where available. It compares the sizes and modification times of HEAD, the index, `packed-refs`, `config`, the current branch ref, and the files in the selected project folder (the whole work tree when no project is selected, up to 5,000 files). When something changed and no diff or commit is open, the panel reads the repository again. While a diff, a commit or a pull request review is open, it keeps the view and asks you to **Refresh** instead. Checks wait while Git holds a lock on its metadata. **Reload Project** opens the selected project again using the Editor's unsaved-edit confirmation. Git inspection uses a read-only adapter and isomorphic-git with index refresh disabled. If the repository changes during a read, refresh after the other operation completes.
@@ -14,7 +16,7 @@ The history is a graph of the commits reachable from the local branches, `origin
 
 A Chromium-based browser with File System Access support is required. The first version supports ordinary `.git` directories and content changes. Linked worktrees, submodules, and symbolic links are outside this scope. The browser cannot detect working-tree executable-bit changes. Recorded index and tree modes remain visible. Binary assets show sizes, and text diff generation is bounded.
 
-Use Node.js 26, run `npm ci`, then `npm test`. Vite builds the library and stylesheet, and TypeScript emits declarations. `npm pack` prepares the artifact used by the Editor build. `npm run test:browser` runs the history graph's keyboard and actions, and the comparison dialog's block drawing, 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. The Editor enables the panel by default. Start it with `twPlusLocalGit=0` in its URL to disable the integration.
+Use Node.js 26, run `npm ci`, then `npm test`. Vite builds the library and stylesheet, and TypeScript emits declarations. `npm pack` prepares the artifact used by the Editor build. `npm run test:browser` runs the branch button's menu and keyboard (also beside the panel on a real repository), the history graph's keyboard and actions, and the comparison dialog's block drawing, 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. The Editor enables the panel by default. Start it with `twPlusLocalGit=0` in its URL to disable the integration; the branch button is then not shown.
 
 The panel structure and local Git approach were informed by [duff](https://github.com/chigichan24/duff). The implementation uses [isomorphic-git](https://github.com/isomorphic-git/isomorphic-git) and [react-diff-view](https://github.com/otakustay/react-diff-view). Bundled licenses are listed in the build's third-party notices.
 

package/dist/branch-button.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { HistoryActionResult } from './history-graph-view.js';
+import type { BranchRefs } from './repository.js';
+/** What the branch button shows: the branches of the chosen repository as the Git panel last read them. */
+export interface BranchButtonState extends BranchRefs {
+    /** Whether a repository has been chosen. */
+    repository: boolean;
+    /** Whether the host lets the panel switch and create branches. */
+    writable: boolean;
+    /** Whether the panel is running an operation. */
+    busy: boolean;
+}
+/** What the branch button asks the Git panel to do. Branch operations resolve as the panel's own buttons do. */
+export interface BranchButtonActions {
+    open(): void;
+    choose(): void;
+    switchBranch(name: string): Promise<HistoryActionResult>;
+    /** Creates a branch at HEAD. */
+    createBranch(name: string, checkout: boolean): Promise<HistoryActionResult>;
+    /** Creates a local branch from `origin/<name>` and switches to it. */
+    createFromRemote(name: string): Promise<HistoryActionResult>;
+}
+export interface BranchButtonProps extends BranchButtonActions {
+    state: BranchButtonState;
+    locale?: string;
+}
+/**
+ * The current branch as a menu button for the host's menu bar, with the menu of branches. Before a repository is
+ * chosen it reads "Git" and offers to choose one. A detached HEAD shows its short commit ID. The menu moves with the
+ * arrow keys, Home and End; Escape closes it and returns to the button. Without `writable` it lists the branches only.
+ */
+export declare function BranchButton({ state, locale, ...actions }: BranchButtonProps): React.JSX.Element;

package/dist/index.d.ts

@@ -11,7 +11,9 @@ export { openProjectComparison } from './project-comparison.js';
 export { openProjectSourceTabs } from './project-source-tabs.js';
 export type { ProjectSourceTabsFile, ProjectSourceTabsOptions } from './project-source-tabs.js';
 export type { ProjectComparisonAction, ProjectComparisonOptions, ProjectComparisonSection } from './project-comparison.js';
-export type { PullRequestBase, PullRequestFetch, PullRequestFiles, Repository, Snapshot, FileChange, FileDiff, HistoryCommit, HistoryCursor, HistoryPage, HistoryRef } from './repository.js';
+export type { BranchRefs, PullRequestBase, PullRequestFetch, PullRequestFiles, Repository, Snapshot, FileChange, FileDiff, HistoryCommit, HistoryCursor, HistoryPage, HistoryRef } from './repository.js';
+export { BranchButton } from './branch-button.js';
+export type { BranchButtonActions, BranchButtonProps, BranchButtonState } from './branch-button.js';
 export { HistoryGraph, laneColors } from './history-graph-view.js';
 export type { HistoryActionResult, HistoryGraphProps } from './history-graph-view.js';
 export { layoutHistory } from './history-graph.js';
@@ -72,12 +74,15 @@ export declare function mountGitPanel({ vm, document, host }: {
     host: GitHost;
 }): {
     refresh: () => Promise<void>;
+    open: (locale: string) => void;
     dispose(): void;
 } | null;
-export declare function renderGitMenu(createElement: (component: any, props: any, ...children: any[]) => any, { vm, locale, MenuItem, MenuSection, onRequestClose }: {
+/**
+ * Renders the button for the host's menu bar that shows the current branch of the panel mounted for `vm` and opens the
+ * menu of branches, the panel and the repository choice. It renders nothing while no panel is mounted for `vm`, such as
+ * when the host does not offer local Git, and shares the panel's repository, operations and checks.
+ */
+export declare function renderBranchButton(createElement: (component: any, props: any, ...children: any[]) => any, { vm, locale }: {
     vm: object;
     locale?: string;
-    MenuItem: any;
-    MenuSection: any;
-    onRequestClose(): void;
 }): any;