@bytetrade/files-picker-wc
Self-contained <olares-folder-picker> custom element for picking a folder (or files) from an Olares Files tree. Built with Vue 3 custom elements and a Shadow DOM; styles are injected via the styles option so any host bundler works.
Two build entries
| Import | Bundle | When to use |
|---|---|---|
@bytetrade/files-picker-wc | Peer build (~58 kB). Externalises vue and @bytetrade/files-core. | Hosts that already own those packages (the Quasar app). Required so configureFiles({ browser }) and the picker's getFilesConfig().browser share one files-core singleton. |
@bytetrade/files-picker-wc/standalone | Fully self-contained (~323 kB). | Hosts without Vue / files-core (e.g. React). |
Run these from the repository root; files-core must be built first because
the peer build compiles against its output.
npm install
npm run build # files-core, then this package's peer + standalone bundles
npm run smoke # jsdom checklist against the standalone artefact
npm run lint
Attributes
| Attribute | Prop | Default | Notes |
|---|---|---|---|
origins | origins | Drive,Sync,External,Cache,Data,Common | Comma-separated DriveType values |
pick-type | pickType | FOLDER | FOLDER or FILE |
icon-base | iconBase | /img | Base URL for file/folder SVG artwork |
locale | locale | en-US | Hot-updates labels when changed |
theme | theme | light | light / dark (data-theme) |
mobile-root-title | mobileRootTitle | current pick title | Host-localized mobile storage-page title |
mobile-root-label | mobileRootLabel | empty | Host-localized heading above storage locations |
mobile-sync-title | mobileSyncTitle | Sync group label | Host-localized library-page title |
mobile | mobile | auto | auto picks the layout from a max-width: 720px query; true / false force the mobile page stack or the desktop dialog. See MOBILE_SHARD.md |
master-node | masterNode | false | Restricts to master-node drives |
base-url | baseUrl | (config) | Optional override |
| — | token | (config) | Property, not attribute |
| — | transport | (config) | Property, not attribute |
Events
| Event | Detail |
|---|---|
pick | FOLDER: a FilePath (Vue may wrap as [FilePath]). FILE: FileItem[]. |
cancel | none |
Required: inject FilesBrowserClient
The element never talks to the Files HTTP API itself. Before opening it, the host must configure files-core:
import { configureFiles } from '@bytetrade/files-core/base';
import { registerOlaresFolderPicker } from '@bytetrade/files-picker-wc';
configureFiles({ browser: myClient /* + token, transport, … */ });
registerOlaresFolderPicker();
const el = document.createElement('olares-folder-picker');
el.setAttribute('pick-type', 'FOLDER');
el.setAttribute('locale', 'zh-CN');
el.addEventListener('pick', e => {
/* … */
});
document.body.appendChild(el);
If browser is missing, the picker boots empty (boot() returns early).
Two layouts
The desktop layout is a resizable dialog (side menu + breadcrumb + sortable columns). The mobile layout is a full-screen bottom sheet with a page stack: the drive list first, then the listing. A tap opens folders there (touch has no dblclick), so only files toggle selection. Choose with mobile.
Icon font
Icons are Material Symbols ligatures rendered through a document-level @font-face that aliases whatever the host has installed (local(...)). Hosts that subset their icon font must keep the ligatures the picker uses — close, arrow_back, arrow_forward, chevron_left, keyboard_arrow_right, check_circle — or those glyphs render as raw text. A subset script that only scans the host's own sources will not see them, since they live in this package's bundle. In TermiPass they are listed in packages/app/scripts/icons/icons.allowlist.txt.
i18n
Standalone catalogs cover en and zh only. Inside the Quasar app, setFilesI18n forwards to the app translator so every language works.
Peer vs second Vue / files-core copy
Do not ship the peer build into a host that resolves a different @bytetrade/files-core than the one configureFiles was called on — the picker will see browser === undefined. The TermiPass Quasar app consumes the peer entry and installs @bytetrade/files-core itself, so both resolve to one copy; external React apps should use ./standalone and call configureFiles from that same module graph (re-exported from the package).