#File Explorer

File Explorer combines workspace identity, file search, hierarchical navigation, file state, and contextual actions in one bounded tool. Filesystem reads, writes, authorization, and source control remain the trusted host's responsibility.

npm install @a3s-lab/ui@0.4.1

<section class="file-explorer" aria-labelledby="files-title">
  <header>
    <div data-file-explorer-identity>
      <h2 id="files-title">Project files</h2>
    </div>
  </header>
  <div data-file-explorer-toolbar>
    <input
      class="input"
      type="search"
      data-file-explorer-search
      aria-label="Filter files"
    />
  </div>
  <div data-file-explorer-viewport>
    <div class="tree" role="tree" aria-label="Project file tree">...</div>
  </div>
  <footer><span data-file-explorer-summary>5 files</span></footer>
</section>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

#Usage

File Explorer reuses Tree for focus, selection, disclosure, and typeahead. Context Menu supplies contextual commands.

<section class="file-explorer" aria-labelledby="files-title">
  <header>
    <div data-file-explorer-identity>
      <h2 id="files-title">Project files</h2>
    </div>
  </header>
  <div data-file-explorer-toolbar>
    <input
      class="input"
      type="search"
      data-file-explorer-search
      aria-label="Filter files"
    />
  </div>
  <div data-file-explorer-viewport>
    <div class="tree" role="tree" aria-label="Project file tree">...</div>
  </div>
  <footer><span data-file-explorer-summary>5 files</span></footer>
</section>

#Parameters

#JavaScript API

Load the runtime before Tree, Context Menu, and File Explorer controllers, or use the complete bundle.

const explorer = document.querySelector(".file-explorer");
explorer.select("src/components/App.tsx");
explorer.setFilter("status");
explorer.setReadonly(false);
explorer.beginRename();

explorer.addEventListener("a3s:file-rename", async ({ detail }) => {
  try {
    await renameFile(detail.value, detail.name);
  } catch (error) {
    explorer.setRenameError(error.message);
  }
});

getSelection() and select() control one file without bypassing unsaved-change guards. getFilter(), setFilter(), and clearFilter() preserve expansion state, reveal matching ancestors, announce the match count, and restore the original tree when cleared. getState(), setState(), and setReadonly() control loading, error, permission, and write visibility. beginRename(), commitRename(), cancelRename(), and setRenameError() provide a reversible optimistic rename; runAction() and refresh() complete the host integration.

Cancelable hooks are a3s:file-before-selection-change, a3s:file-before-filter-change, a3s:file-before-action, and a3s:file-before-rename. Completed selection, filter, action, rename, rename-cancel, and state events include the source, original event, stable file value, and relevant snapshots. The host may reject navigation with unsaved work, reject a write synchronously, or reopen the editor with an asynchronous error.

#States and variants

Read-only mode preserves selection, filtering, copy path, and open actions while removing write commands instead of disabling everything. Filter counts include leaf files rather than directory nodes. Rename uses data-file-editor in the current row: F2 starts rename on the focused or selected item, Enter submits and returns focus to the item, Escape cancels, and blur commits unless data-rename-blur="cancel" is set. Context Menu rename remains available for pointer users. The controller rejects empty names and path separators; the host validates duplicates, platform rules, authorization, and persistence.

Source status may appear as a short trailing file marker. Commit, stage, branch creation, and remote synchronization are separate workflows composed from Toolbar, Tree, Alert, and Dialog; they do not belong in File Explorer's base public contract.

#Accessibility

Follow Tree's roving tabindex and arrow-key contract. A cancelable selection hook protects unsaved work before focus or selection moves. Filtering announces the count and keeps focus in search when a focused result disappears. Rename errors stay associated with the inline input. Show async loading or error state inside the affected branch. A trusted host performs every file write.