J3W1 / DESIGN SYSTEM

File browser

Location navigation and a filterable native file table with bounded host actions.

stable · LIGHT DOM · 1.1.0

Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

All files
Source

Search files

Local file examples
Name	Kind	Size
	Vue component	4 KB
	Documentation	2 KB

2 files

<j3w1-file-browser id="example-file-browser-default"><section class="file-browser" aria-label="Workspace files"><div class="file-browser-locations"><j3w1-tree><ul class="tree" role="tree" aria-label="Locations"><li role="treeitem" tabindex="0" aria-selected="true" data-location="all" id="example-file-browser-default-files-all" data-demo-focus-target=""><span data-tree-label="">All files</span></li><li role="treeitem" tabindex="-1" aria-selected="false" data-location="source" id="example-file-browser-default-files-source"><span data-tree-label="">Source</span></li></ul></j3w1-tree></div><div><label for="example-file-browser-default-files-query">Search files</label><input class="file-browser-control" id="example-file-browser-default-files-query" type="search" data-file-query=""><table><caption>Local file examples</caption><thead><tr><th scope="col">Name</th><th scope="col">Kind</th><th scope="col">Size</th></tr></thead><tbody><tr data-file-id="app" data-location="source"><td><button class="file-browser-control" type="button" data-file-open="app">App.vue</button></td><td>Vue component</td><td>4 KB</td></tr><tr data-file-id="readme" data-location="docs"><td><button class="file-browser-control" type="button" data-file-open="readme">README.md</button></td><td>Documentation</td><td>2 KB</td></tr></tbody></table><p role="status" data-file-status="">2 files</p></div></section></j3w1-file-browser>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@1.1.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/file-browser.css';
import '@j3w1/ui/register/file-browser';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy file-browser --out ./vendor/j3w1/file-browser

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.

events

Name	Type / signature	Meaning
`j3w1-open-file`	`CustomEvent`	Request opening an existing file identity.

Dependencies and verification

Registered components: tree. Style dependencies: table, tree.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Purpose

Compose hierarchical location navigation with a filterable file table. Opening an entry emits its stable identity. The caller owns file access, upload, deletion and permissions. The supplied names and sizes are synthetic local examples.

Anatomy

locations: Tree navigation selects a location filter.
query: Labelled native search filters visible rows.
table: Native rows show names, kinds and sizes with explicit Open actions.

States

State	Presentation	Non-colour channel
default	Locations and native file rows.	Explicit names, kinds and sizes.
selected	Selected location follows the tree contract.	aria-selected plus location filter.
empty	No file rows.	Explicit zero-files text.
no-results	Filtered rows are hidden.	Matching count and retained search query.
focus-visible	Dashed control outline.	Native focus and tree roving focus.

Keyboard

Tab / Shift+Tab: Move among tree navigation, search and row actions.
Arrow keys: Use the tree contract inside navigation.
Enter / Space: Request opening the chosen file through an event.

Accessibility

Keep the complete nested tree behavior and semantic table headers. Filtering does not move focus. Announce counts, and keep the search field available after zero results. File actions must not imply access beyond the host’s actual permissions.

Portability

Wrap labels and actions without changing source order. Use logical spacing in RTL. Preserve native target sizes at both densities; only bounded data regions may scroll horizontally. Use equivalent native semantics and approved roles; record any unsupported behavior as a mapping deviation. The host owns application data, persistence, permissions and services.

Non-examples

Unlabelled controls, color-only status, drag-only operations, hidden required instructions, stolen focus or an invented service success.