xtralab 0.15.0 → 0.15.2

package/lib/fileBrowser/gitignore.d.ts

@@ -8,22 +8,9 @@ import type { GitStatusEntry } from '@pierre/trees';
  */
 export declare function loadGitignoreMatcher(contentsManager: Contents.IManager): Promise<Ignore | null>;
 /**
- * Build `GitStatusEntry`s for the canonical paths that match the given
- * gitignore matcher.
- *
- * `@pierre/trees` propagates the `ignored` style from a directory entry
- * down to every descendant via its internal `ignoredDirectoryPaths` set, so
- * we only emit one entry per ignored subtree root: emitting descendants
- * would also pollute the library's `directoriesWithChanges` set, causing
- * parent directories of nested ignored items to render a "contains git
- * status items" dot.
- *
- * Paths are sorted lexicographically so a directory always precedes its
- * descendants, allowing a simple ancestor-suppression check via
- * `path.startsWith(dir)`. The trailing slash on canonical directory paths
- * (required by `@pierre/trees`, also recognized by `ignore` as the
- * "directory" indicator) keeps the prefix check from accidentally matching
- * sibling paths that happen to share a name prefix (e.g. `node_modules_old`
- * vs `node_modules/`).
+ * One `GitStatusEntry` per ignored subtree root: descendant entries would
+ * pollute the tree's `directoriesWithChanges` set (bogus dots on parents),
+ * and `ignored` already propagates downward. The trailing slash on directory
+ * paths keeps the sorted `startsWith` ancestor check off name-prefix siblings.
  */
 export declare function buildIgnoredEntries(matcher: Ignore, canonicalPaths: Iterable<string>): GitStatusEntry[];

package/lib/fileBrowser/gitignore.js

@@ -1,9 +1,4 @@
 import ignore from 'ignore';
-/**
- * The path of the workspace `.gitignore` file. Loaded relative to the
- * Jupyter contents root, which matches the directory the gitignore patterns
- * are evaluated against — patterns and tested paths share the same base.
- */
 const GITIGNORE_PATH = '.gitignore';
 /**
  * Load the workspace `.gitignore` and return an `ignore` matcher built from
@@ -20,9 +15,6 @@ export async function loadGitignoreMatcher(contentsManager) {
         });
     }
     catch (_a) {
-        // The most common failure here is `.gitignore` simply not existing.
-        // Other transient errors (permission denied, server unreachable) are
-        // also treated as "no matcher" so the file browser still works.
         return null;
     }
     if (model.type !== 'file' || typeof model.content !== 'string') {
@@ -34,23 +26,10 @@ export async function loadGitignoreMatcher(contentsManager) {
     return ignore().add(model.content);
 }
 /**
- * Build `GitStatusEntry`s for the canonical paths that match the given
- * gitignore matcher.
- *
- * `@pierre/trees` propagates the `ignored` style from a directory entry
- * down to every descendant via its internal `ignoredDirectoryPaths` set, so
- * we only emit one entry per ignored subtree root: emitting descendants
- * would also pollute the library's `directoriesWithChanges` set, causing
- * parent directories of nested ignored items to render a "contains git
- * status items" dot.
- *
- * Paths are sorted lexicographically so a directory always precedes its
- * descendants, allowing a simple ancestor-suppression check via
- * `path.startsWith(dir)`. The trailing slash on canonical directory paths
- * (required by `@pierre/trees`, also recognized by `ignore` as the
- * "directory" indicator) keeps the prefix check from accidentally matching
- * sibling paths that happen to share a name prefix (e.g. `node_modules_old`
- * vs `node_modules/`).
+ * One `GitStatusEntry` per ignored subtree root: descendant entries would
+ * pollute the tree's `directoriesWithChanges` set (bogus dots on parents),
+ * and `ignored` already propagates downward. The trailing slash on directory
+ * paths keeps the sorted `startsWith` ancestor check off name-prefix siblings.
  */
 export function buildIgnoredEntries(matcher, canonicalPaths) {
     const sorted = Array.from(canonicalPaths).sort();

package/lib/fileBrowser/icons.d.ts

@@ -1,26 +1,16 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 import type { FileTreeIconConfig } from '@pierre/trees';
 /**
- * The glyph used as the xtralab file browser's sidebar tab icon. Defined as a
- * `LabIcon` (rather than the default `folderIcon` from
- * `@jupyterlab/ui-components`) so the xtralab browser is visually distinguishable
- * from JupyterLab's built-in file browser, which also lives in the left
- * sidebar.
- *
- * Source: `file-tree` from SVG Repo (https://www.svgrepo.com/svg/371275/file-tree).
- * The original `fill="#444"` is replaced with `fill="currentColor"` and the
- * root element is given the `jp-icon3` class so the icon picks up JupyterLab's
- * theme color and the sidebar's inverse-color painting automatically.
+ * Sidebar tab icon, distinct from the core `folderIcon` so the xtralab
+ * browser is distinguishable from the built-in one. `file-tree` from SVG Repo
+ * (https://www.svgrepo.com/svg/371275/file-tree), refit to follow the theme
+ * (`currentColor`, `jp-icon3`) and padded to the size of the stock glyphs.
  */
 export declare const xtralabFileBrowserIcon: LabIcon;
 /**
- * Icon configuration for the xtralab file browser. Keeps the default `complete`
- * built-in icon set (the colored language icons) and layers a Jupyter notebook
- * symbol on top so `.ipynb` files render with the JupyterLab notebook glyph.
- *
- * `set` must be set explicitly: when a config object includes any custom
- * overrides without `set`, `@pierre/trees` defaults `set` to `'none'`, which
- * disables the built-in icons entirely.
+ * Icon config: the built-in `complete` set plus the Jupyter notebook symbol
+ * for `.ipynb`. `set` must be explicit — with any custom overrides present,
+ * `@pierre/trees` defaults it to `'none'`, disabling the built-in icons.
  */
 export declare const FILE_BROWSER_ICONS: FileTreeIconConfig;
 /**

package/lib/fileBrowser/icons.js

@@ -2,36 +2,22 @@ var _a;
 import { LabIcon, fileIcon } from '@jupyterlab/ui-components';
 import { createFileTreeIconResolver, getBuiltInSpriteSheet } from '@pierre/trees';
 /**
- * The glyph used as the xtralab file browser's sidebar tab icon. Defined as a
- * `LabIcon` (rather than the default `folderIcon` from
- * `@jupyterlab/ui-components`) so the xtralab browser is visually distinguishable
- * from JupyterLab's built-in file browser, which also lives in the left
- * sidebar.
- *
- * Source: `file-tree` from SVG Repo (https://www.svgrepo.com/svg/371275/file-tree).
- * The original `fill="#444"` is replaced with `fill="currentColor"` and the
- * root element is given the `jp-icon3` class so the icon picks up JupyterLab's
- * theme color and the sidebar's inverse-color painting automatically.
+ * Sidebar tab icon, distinct from the core `folderIcon` so the xtralab
+ * browser is distinguishable from the built-in one. `file-tree` from SVG Repo
+ * (https://www.svgrepo.com/svg/371275/file-tree), refit to follow the theme
+ * (`currentColor`, `jp-icon3`) and padded to the size of the stock glyphs.
  */
 export const xtralabFileBrowserIcon = new LabIcon({
     name: 'xtralab:file-browser',
-    svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="jp-icon3" fill="currentColor">
+    svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="-2 -2 20 20" class="jp-icon3" fill="currentColor">
   <path d="M16 10v-4h-11v1h-2v-3h9v-4h-12v4h2v10h3v2h11v-4h-11v1h-2v-5h2v2z"/>
 </svg>`
 });
 /**
- * Sprite sheet injected into the `@pierre/trees` shadow DOM. Contains a single
- * `<symbol>` for the Jupyter notebook icon, drawn from the JupyterLab core
- * notebook icon (`@jupyterlab/ui-components/style/icons/filetype/notebook.svg`).
- *
- * `@pierre/trees` does not ship a Jupyter token, so `.ipynb` files would
- * otherwise fall through to the generic file icon. The symbol id below is
- * referenced from `byFileExtension` in {@link FILE_BROWSER_ICONS}.
- *
- * The orange `#EF6C00` fill is set as a presentation attribute on the inner
- * `<g>` so it survives the `fill: currentColor` rule the tree applies on the
- * icon container — the inherited color does not override a presentation
- * attribute set directly on a child.
+ * Sprite sheet injected into the tree's shadow DOM: the JupyterLab notebook
+ * glyph, since `@pierre/trees` ships no Jupyter token. The `#EF6C00` fill is
+ * a presentation attribute on the inner `<g>` so it survives the tree's
+ * `fill: currentColor` rule on the icon container.
  */
 const JUPYTER_NOTEBOOK_SPRITE_SHEET = `<svg data-icon-sprite aria-hidden="true" width="0" height="0">
   <symbol id="jupyter-notebook" viewBox="0 0 22 22">
@@ -42,13 +28,9 @@ const JUPYTER_NOTEBOOK_SPRITE_SHEET = `<svg data-icon-sprite aria-hidden="true"
   </symbol>
 </svg>`;
 /**
- * Icon configuration for the xtralab file browser. Keeps the default `complete`
- * built-in icon set (the colored language icons) and layers a Jupyter notebook
- * symbol on top so `.ipynb` files render with the JupyterLab notebook glyph.
- *
- * `set` must be set explicitly: when a config object includes any custom
- * overrides without `set`, `@pierre/trees` defaults `set` to `'none'`, which
- * disables the built-in icons entirely.
+ * Icon config: the built-in `complete` set plus the Jupyter notebook symbol
+ * for `.ipynb`. `set` must be explicit — with any custom overrides present,
+ * `@pierre/trees` defaults it to `'none'`, disabling the built-in icons.
  */
 export const FILE_BROWSER_ICONS = {
     set: 'complete',
@@ -58,39 +40,19 @@ export const FILE_BROWSER_ICONS = {
         ipynb: 'jupyter-notebook'
     }
 };
-/**
- * Concatenated sprite-sheet text. Combines the built-in sheet for the active
- * icon set with our custom Jupyter notebook sheet so {@link extractSymbol}
- * can find the body of any symbol the tree itself can render.
- */
 const COMBINED_SPRITE_SHEETS = [
     getBuiltInSpriteSheet((_a = FILE_BROWSER_ICONS.set) !== null && _a !== void 0 ? _a : 'complete'),
     JUPYTER_NOTEBOOK_SPRITE_SHEET
 ].join('\n');
-/**
- * Resolver instance reused across calls to {@link getTreeIcon}. The resolver
- * is pure relative to the icon config, so building it once at module load
- * avoids re-walking the icon rules on every diff that opens.
- */
 const treeIconResolver = createFileTreeIconResolver(FILE_BROWSER_ICONS);
 /**
- * Cache of LabIcons keyed by the resolved sprite symbol id (e.g.
- * `file-tree-builtin-python`). All Python files share the same icon, so
- * caching by symbol id prevents repeated LabIcon registration warnings and
- * keeps the JupyterLab icon registry small.
+ * LabIcons keyed by resolved symbol id — re-registering a LabIcon under the
+ * same name logs warnings.
  */
 const TREE_ICON_CACHE = new Map();
-/**
- * Extract the inner SVG markup and viewBox of the `<symbol>` with the given
- * id from {@link COMBINED_SPRITE_SHEETS}. Returns `null` if no matching
- * symbol exists, in which case the caller falls back to JupyterLab's default
- * file icon.
- */
 function extractSymbol(symbolId) {
     var _a;
-    // Match a `<symbol>` whose `id` attribute equals `symbolId` (allowing other
-    // attributes in any order). The `[\s\S]*?` body is non-greedy so we stop
-    // at the first matching `</symbol>` even when multiple symbols sit
+    // Non-greedy body: stop at the first `</symbol>` when symbols sit
     // back-to-back in the sheet.
     const escaped = symbolId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const symbolRegex = new RegExp(`<symbol\\b[^>]*\\bid="${escaped}"[^>]*>([\\s\\S]*?)</symbol>`, 'i');
@@ -105,14 +67,10 @@ function extractSymbol(symbolId) {
     };
 }
 /**
- * Fallback colors for the built-in file icons, keyed by the icon token
- * `@pierre/trees` resolves for a path (e.g. `python`, `typescript`).
- *
- * The tree only exposes these as `--trees-file-icon-color-<token>` CSS
- * variables scoped to its shadow host, so they resolve to nothing for the
- * standalone {@link LabIcon}s {@link getTreeIcon} builds for main-area tabs.
- * Mirroring them here lets {@link getBuiltInFileIconColor} bottom out in a
- * real color. Each is a `light-dark(…)` pair for dark themes.
+ * Fallback colors keyed by the tree's icon token. The tree exposes its colors
+ * only as `--trees-file-icon-color-*` vars scoped to its shadow host, so the
+ * standalone LabIcons built for main-area tabs need these literals;
+ * `light-dark(…)` covers dark themes.
  */
 const BUILT_IN_FILE_ICON_COLOR_FALLBACKS = {
     astro: 'light-dark(#a631be, #d568ea)',
@@ -167,11 +125,8 @@ const BUILT_IN_FILE_ICON_COLOR_FALLBACKS = {
     zip: 'light-dark(#d47628, #ffa359)'
 };
 /**
- * Color the file tree would paint for the built-in icon `token`, as a
- * self-contained CSS value usable outside the tree's shadow DOM: the tree's
- * `--trees-file-icon-color-*` properties when in scope, else the literal from
- * {@link BUILT_IN_FILE_ICON_COLOR_FALLBACKS}. Returns `undefined` for unknown
- * tokens.
+ * The tree's color for `token` as a self-contained CSS value: its CSS vars
+ * when in scope, else the mirrored literal. `undefined` for unknown tokens.
  */
 function getBuiltInFileIconColor(token) {
     const fallback = BUILT_IN_FILE_ICON_COLOR_FALLBACKS[token];
@@ -180,9 +135,6 @@ function getBuiltInFileIconColor(token) {
     }
     return `var(--trees-file-icon-color-${token}, var(--trees-file-icon-color, ${fallback}))`;
 }
-/**
- * Resolve a tree glyph into a standalone `LabIcon`.
- */
 function resolveTreeIcon(filePath) {
     var _a;
     const resolved = treeIconResolver.resolveIcon('file-tree-icon-file', filePath);
@@ -196,22 +148,15 @@ function resolveTreeIcon(filePath) {
     if (symbol === null) {
         return { icon: null, specific };
     }
-    // Built-in language icons paint with `fill="currentColor"` so the colored
-    // tier of the tree can recolor them by setting `color` on the host
-    // element. Reproduce that here by setting the same color value as an
-    // inline `style="color: …"` on the outer `<svg>`. `getBuiltInFileIconColor`
-    // returns a `var(--trees-…)` chain that bottoms out in `light-dark(…)`,
-    // which respects the page's `color-scheme` declaration so dark themes pick
-    // up the brighter variants automatically.
+    // Built-in glyphs paint with `fill="currentColor"`; an inline `color`
+    // style reproduces the tree's colored tier outside its shadow DOM.
     const colored = FILE_BROWSER_ICONS.colored === true;
     const color = colored && resolved.token !== undefined
         ? getBuiltInFileIconColor(resolved.token)
         : undefined;
     const styleAttr = color !== undefined ? ` style="color: ${color};"` : '';
-    // Prefer a viewBox the resolver supplies (custom sprite overrides may set
-    // one), then fall back to the symbol's own viewBox so 22x22 sprites like
-    // the Jupyter notebook glyph render at the right scale rather than being
-    // cropped to a 16x16 box.
+    // Prefer the resolver's viewBox, then the symbol's own, so 22x22 sprites
+    // like the notebook glyph aren't cropped to a 16x16 box.
     const viewBox = (_a = resolved.viewBox) !== null && _a !== void 0 ? _a : symbol.viewBox;
     const svgstr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}"${styleAttr}>${symbol.inner}</svg>`;
     const icon = new LabIcon({

package/lib/fileBrowser/index.js

@@ -31,10 +31,8 @@ const plugin = {
             },
             translator: translator !== null && translator !== void 0 ? translator : undefined
         });
-        // Ranks just under the Terminals panel in the left sidebar. The shipped
-        // `layout` setting assigns the default ranks (rank only, no area pin),
-        // so this browser stays movable via the "Move Widget" context menu; the
-        // `rank` here is the in-code fallback for when that setting is absent.
+        // Rank-only fallback for when the shipped `layout` setting is absent;
+        // no area pin, so the browser stays movable via "Move Widget".
         app.shell.add(browser, 'left', { rank: 2 });
         if (restorer) {
             restorer.add(browser, browser.id);

package/lib/fileBrowser/widget.d.ts

@@ -5,11 +5,28 @@ import { ITranslator } from '@jupyterlab/translation';
 import { Toolbar } from '@jupyterlab/ui-components';
 import { ISignal } from '@lumino/signaling';
 import { AccordionPanel, Widget } from '@lumino/widgets';
+import type { IFileChange } from '../git/tokens';
 export declare const FILE_BROWSER_ID = "xtralab:file-browser";
+/**
+ * The options used to create an {@link XtralabFileBrowser}.
+ */
 interface IXtralabFileBrowserOptions {
+    /**
+     * The contents manager backing the tree.
+     */
     contentsManager: Contents.IManager;
+    /**
+     * The document manager used to open files from the tree.
+     */
     docManager: IDocumentManager;
+    /**
+     * Callback invoked with a file's server path when its row is
+     * double-clicked. No double-click handler is installed when absent.
+     */
     onOpenFile?: (serverPath: string) => void;
+    /**
+     * The application language translator.
+     */
     translator?: ITranslator;
 }
 /**
@@ -19,72 +36,57 @@ interface IXtralabFileBrowserOptions {
  */
 export interface IXtralabFileBrowser {
     /**
-     * The contents manager backing the tree. Exposed so command handlers can
-     * issue contents operations (rename, delete, copy, …) against the same
-     * drive the tree was loaded from.
+     * The contents manager backing the tree; command handlers issue rename,
+     * delete, copy, … against the same drive.
      */
     readonly contentsManager: Contents.IManager;
     /**
-     * The toolbar shown above the tree. Plugin code populates it with command
-     * buttons after the widget is constructed.
+     * The toolbar above the tree, populated by plugin code after construction.
      */
     readonly toolbar: Toolbar;
     /**
-     * Canonical paths of the items currently selected in the tree. Folder
-     * paths carry a trailing slash; file paths do not.
+     * Canonical selected paths; folder paths carry a trailing slash.
      */
     readonly selectedPaths: readonly string[];
     /**
-     * Emits when the tree's selection changes. Commands that have an
-     * `isVisible` / `isEnabled` predicate should listen so they re-evaluate.
+     * Emits when the tree's selection changes.
      */
     readonly selectionChanged: ISignal<IXtralabFileBrowser, readonly string[]>;
     /**
-     * Emits when {@link refresh} is called. The React component listens and
-     * re-fetches the directories that were previously loaded so the tree
-     * matches the contents on disk again.
+     * Git changes from the latest status poll, one per staged or unstaged
+     * change; paths are repo-relative.
+     */
+    readonly gitChanges: readonly IFileChange[];
+    /**
+     * Emits when {@link refresh} is called.
      */
     readonly refreshRequested: ISignal<IXtralabFileBrowser, void>;
     /**
-     * Emits when the widget is asked to surface a newly-created path
-     * (for example, after the toolbar's "new folder" command). The React
-     * component listens and inserts the path into the model so the user
-     * sees the new item without a full refresh.
+     * Emits a newly-created canonical path so the tree inserts it without a
+     * full refresh.
      */
     readonly pathAdded: ISignal<IXtralabFileBrowser, string>;
     /**
-     * Emits when an external caller asks the tree to scroll to and select
-     * the given canonical path. The React component listens, lazily loads
-     * any unloaded ancestor directories, expands them, and selects the
-     * target. Used by the editor breadcrumbs to jump back to a file or
-     * folder shown in the breadcrumb trail.
+     * Emits a canonical path to load, expand, select, and scroll to. Used by
+     * the editor breadcrumbs.
      */
     readonly revealRequested: ISignal<IXtralabFileBrowser, string>;
     /**
-     * Emits when an external caller asks the tree to return to the
-     * workspace root: clear any current selection and scroll back to the
-     * first row. Distinct from {@link revealRequested} because the
-     * workspace root has no tree row of its own — it cannot be reached
-     * by passing a path.
+     * Emits when the tree should return to the workspace root — the root has
+     * no tree row of its own, so it cannot be revealed by path.
      */
     readonly rootRequested: ISignal<IXtralabFileBrowser, void>;
     /**
-     * Emits when an external caller asks the tree to collapse every
-     * expanded folder. The React component listens and walks the loaded
-     * directories, calling `.collapse()` on each expanded one.
+     * Emits when every expanded folder should collapse.
      */
     readonly collapseAllRequested: ISignal<IXtralabFileBrowser, void>;
     /**
-     * Whether the filter box above the tree is shown. Mirrors the default
-     * file browser's `showFileFilter`: hidden on startup and flipped by the
-     * toolbar toggle. Also forced to `true` when the tree opens a search
-     * session on its own — typing a letter while the tree has focus.
+     * Whether the filter box above the tree is shown; also forced `true` when
+     * the tree opens a search session itself (typing while it has focus).
      */
     readonly fileFilterVisible: boolean;
     /**
-     * Emits when {@link fileFilterVisible} changes. The React component
-     * listens to show or hide the filter box; the toggle command listens
-     * to refresh its toggled state.
+     * Emits when {@link fileFilterVisible} changes.
      */
     readonly fileFilterVisibleChanged: ISignal<IXtralabFileBrowser, boolean>;
     /**
@@ -92,22 +94,17 @@ export interface IXtralabFileBrowser {
      */
     refresh(): void;
     /**
-     * Notify the React component that a new path was created and should
-     * appear in the tree. `canonicalPath` follows the `@pierre/trees`
-     * convention: directories carry a trailing slash, files do not.
+     * Notify the React component that a new canonical path was created and
+     * should appear in the tree.
      */
     notifyPathAdded(canonicalPath: string): void;
     /**
-     * Ask the tree to reveal {@link canonicalPath}: load and expand any
-     * unloaded ancestor directories, then select and scroll the target
-     * into view. `canonicalPath` follows the `@pierre/trees` convention
-     * (directories carry a trailing slash, files do not). Must be a
-     * non-empty path — use {@link scrollToRoot} for the root gesture.
+     * Reveal a non-empty canonical path: load and expand ancestors, then
+     * select and scroll to it. Use {@link scrollToRoot} for the root gesture.
      */
     reveal(canonicalPath: string): void;
     /**
-     * Ask the tree to return to the workspace root: clear any current
-     * selection and scroll back to the top of the tree.
+     * Return to the workspace root: clear the selection and scroll to the top.
      */
     scrollToRoot(): void;
     /**
@@ -122,6 +119,10 @@ export interface IXtralabFileBrowser {
      * Toggle the filter box above the tree.
      */
     toggleFileFilter(): void;
+    /**
+     * The DOM node of the movable "Files" section, used to locate the panel
+     * currently hosting the tree.
+     */
     readonly sectionNode: HTMLElement;
 }
 /**
@@ -131,41 +132,128 @@ export interface IXtralabFileBrowser {
  */
 export declare class XtralabFileBrowser extends Widget implements IXtralabFileBrowser, IMovableSectionSource, IMovableSectionDestination {
     constructor(options: IXtralabFileBrowserOptions);
+    /**
+     * The contents manager backing the tree.
+     */
     get contentsManager(): Contents.IManager;
+    /**
+     * The toolbar above the tree.
+     */
     get toolbar(): Toolbar;
+    /**
+     * Canonical selected paths; folder paths carry a trailing slash.
+     */
     get selectedPaths(): readonly string[];
+    /**
+     * A signal emitted when the tree's selection changes.
+     */
     get selectionChanged(): ISignal<this, readonly string[]>;
+    /**
+     * Git changes from the latest status poll.
+     */
+    get gitChanges(): readonly IFileChange[];
+    /**
+     * A signal emitted when {@link refresh} is called.
+     */
     get refreshRequested(): ISignal<this, void>;
+    /**
+     * A signal emitting a newly-created canonical path for the tree to insert.
+     */
     get pathAdded(): ISignal<this, string>;
+    /**
+     * A signal emitting a canonical path to load, expand, select, and scroll to.
+     */
     get revealRequested(): ISignal<this, string>;
+    /**
+     * A signal emitted when the tree should return to the workspace root.
+     */
     get rootRequested(): ISignal<this, void>;
+    /**
+     * A signal emitted when every expanded folder should collapse.
+     */
     get collapseAllRequested(): ISignal<this, void>;
+    /**
+     * Whether the filter box above the tree is shown.
+     */
     get fileFilterVisible(): boolean;
+    /**
+     * A signal emitted when {@link fileFilterVisible} changes.
+     */
     get fileFilterVisibleChanged(): ISignal<this, boolean>;
     /**
-     * Update the cached selection. Called from the React tree when the
-     * underlying `@pierre/trees` model emits a selection change.
+     * Update the cached selection from the React tree.
      */
     updateSelection(paths: readonly string[]): void;
+    /**
+     * Update the cached git changes from the React tree's status poll.
+     */
+    updateGitChanges(changes: readonly IFileChange[]): void;
+    /**
+     * Trigger a refresh of every loaded directory in the tree.
+     */
     refresh(): void;
+    /**
+     * Notify the tree that a new canonical path was created.
+     */
     notifyPathAdded(canonicalPath: string): void;
+    /**
+     * Reveal a non-empty canonical path in the tree; use {@link scrollToRoot}
+     * for the workspace root, which has no tree row of its own.
+     */
     reveal(canonicalPath: string): void;
+    /**
+     * Return to the workspace root: clear the selection and scroll to the top.
+     */
     scrollToRoot(): void;
+    /**
+     * Ask the tree to collapse every currently expanded folder.
+     */
     collapseAll(): void;
+    /**
+     * Show or hide the filter box above the tree.
+     */
     setFileFilterVisible(visible: boolean): void;
+    /**
+     * Toggle the filter box above the tree.
+     */
     toggleFileFilter(): void;
+    /**
+     * The DOM node of the movable "Files" section.
+     */
     get sectionNode(): HTMLElement;
+    /**
+     * Whether the panel currently holds no sections, its own tree included.
+     */
     get isEmpty(): boolean;
+    /**
+     * A signal emitted when a section is added to or removed from the panel.
+     */
     get contentChanged(): ISignal<this, void>;
+    /**
+     * A signal emitting each section entry announced to the move plugin.
+     */
     get sectionAdded(): ISignal<this, ISectionEntry>;
+    /**
+     * The accordion hosting the sections, or `null` while the tree sits alone.
+     */
     get accordionPanel(): AccordionPanel | null;
+    /**
+     * Section widgets hosted from other panels; the tree section is excluded.
+     */
     get sections(): ReadonlyArray<Widget>;
     /**
      * The toolbar is the section's title node: it is the tree's header row at
      * home, and an accordion host renders it inside the section title.
      */
     getSections(): ReadonlyArray<ISectionEntry>;
+    /**
+     * Detach and return the tree section so the move plugin can re-host it;
+     * `null` for any other id or when the section is already away from home.
+     */
     removeSectionById(sectionId: string): Widget | null;
+    /**
+     * Re-attach the tree section after a move back to this panel.
+     */
     reinsertSection(widget: Widget): void;
     /**
      * The move plugin reconciles persisted moves only against sections announced
@@ -176,6 +264,10 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
      * The first hosted section moves the tree into an accordion.
      */
     addSection(widget: Widget): void;
+    /**
+     * Remove a hosted section; the accordion is torn down once only the
+     * panel's own tree section (or nothing) remains.
+     */
     removeSectionWidget(widget: Widget): void;
     private _isSectionHome;
     /**
@@ -189,6 +281,7 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
     private _translator;
     private _selectedPaths;
     private _selectionChanged;
+    private _gitChanges;
     private _refreshRequested;
     private _pathAdded;
     private _revealRequested;