File browser
Location navigation and a filterable native file table with bounded host actions.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
- All files
- Source
| 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@4.0.0import '@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.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy file-browser --out ./vendor/j3w1/file-browserThe 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
File browser file-browser
Location navigation and a filterable native file table with bounded host actions.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
root.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
root.border | color.border.controlapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
heading.text | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
secondary.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
control.bg | color.surface.inputapproveduse | #000000 | Form-control fill. |
control.focus | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
button.bg | color.action.secondary.bgobserveduse | rgb(0 0 0 / 0%) | Secondary button has no fill. |
button.text | color.action.secondary.textapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
button.border | color.action.secondary.borderapproveduse | #986f72 | D-041 action.secondary.border: color.primitive.modern.control. |
button.bg-hover | color.action.secondary.hover-bgobserveduse | #630f0d | Secondary button hover. |
button.bg-active | color.action.secondary.pressed-bgobserveduse | #420f0c | Secondary button pressed. |
button.border-active | color.border.activeobserveduse | #e53935 | Active or focused control border. |
button.focus | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
dependency.role-border-width-default | border.width.defaultobserveduse | 1px | Every border is 1px. |
dependency.role-border-width-emphasis | border.width.emphasisobserveduse | 2px | Selected indicator, sticky header rule, invalid border. |
dependency.role-color-border-divider | color.border.dividerapproveduse | #482b2b | D-041 border.divider: color.primitive.modern.divider. |
dependency.role-color-border-selected-indicator | color.border.selected-indicatorobserveduse | #e53935 | 2px indicator bar on the selected tab or nav item. |
dependency.role-density-comfortable-control-height | density.comfortable.control-heightobserveduse | 32px | |
dependency.role-density-compact-control-height | density.compact.control-heightobserveduse | 24px | |
dependency.role-focus-offset | focus.offsetobserveduse | -2px | outline-offset for controls. |
dependency.role-radius-none | radius.noneobserveduse | 0px | The only radius. Nothing is rounded. |
dependency.role-space-12 | space.12observeduse | 12px | |
dependency.role-space-16 | space.16observeduse | 16px | |
dependency.role-space-8 | space.8observeduse | 8px |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Default | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
default |
2 files | |||||||||
selected | ||||||||||
empty | ||||||||||
no-results | ||||||||||
focus-visible |
Purpose
Finds a file by location and name; every file operation belongs to the caller.
Anatomy
Parts as listed in the anatomy.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | Locations and native file rows. Button controls are the secondary button (button.md); inputs keep the input look. | 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
As in the key table.
Accessibility
Keep the complete nested tree behaviour and semantic table headers. Filtering does not move focus. Announce counts, and keep the search field available after zero results. File actions never imply access beyond the host’s actual permissions.
Portability
Follows the shared component defaults in spec/portability.md (section
“Shared component defaults”).
Non-examples
Unlabelled controls, color-only status, drag-only operations, hidden required instructions, stolen focus or an invented service success.
Contrast report
7 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| file-browser default text | default | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| file-browser default border | default | ui | color.border.control #c81a1a | color.surface.default #0d0707 | 3.44 | 3 | pass |
| Primary content | — | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| Supporting content | — | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| Control boundary | — | ui | color.border.control #c81a1a | color.surface.default #0d0707 | 3.44 | 3 | pass |
| Button label | — | text | color.action.secondary.text #ffa2a7 | color.surface.default #0d0707 | 10.45 | 4.5 | pass |
| Button label on hover | — | text | color.action.secondary.text #ffa2a7 | color.action.secondary.hover-bg #630f0d | 6.84 | 4.5 | pass |
Keys
| Key | Action |
|---|---|
| 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. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: tree table search-field
Stress fixtures: FX-320 FX-360 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-TOUCH FX-DENSITY FX-STATE-MATRIX