@speles7172/file-console

The file browser, and the attachment panel. React, over a transport you supply.

npm install @speles7172/file-console

Two components over one transport:

import { FileExplorer, FileAttachments } from '@speles7172/file-console';
import '@speles7172/file-console/styles.css';

<FileExplorer transport={transport} />                            {/* the Files page */}
<FileExplorer transport={transport} rootNodeId="project:7" embedded />
<FileAttachments transport={transport} entityType="invoice" entityId="i1" />
<FileTypesAdmin transport={transport} entityTypes={['invoice', 'vendor']} />

The browser renders identically wherever it is put — only rootNodeId changes. Scope, permissions and the shape of the tree are decided on the server, so embedding really is one prop.

What you get

• A folder tree, breadcrumbs, and folders/albums/records as cards.
• Three views: list, grid and gallery. An album is always a gallery.
• Upload by drag or by picking, straight to the store, with progress.
• Preview in place — images, video, audio, PDF — with paging, arrow keys and a details panel. A PDF is fetched and framed from a blob: URL, so whether it displays does not depend on the object store returning Content-Disposition: inline: a store that drops the disposition makes the browser download the file and leave an empty dialog behind, and every other download in the console still works, so it is an easy one to get wrong. Where the bucket has no CORS rule for your origin the fetch is refused and the frame falls back to the presigned URL. The frame carries no sandbox attribute, deliberately: Chrome refuses to run its PDF viewer inside a sandboxed frame whatever the allow-list, so the alternative is not a safer preview but no preview — and the blob is built as application/pdf whatever the response said, which is what keeps a same-origin frame from parsing the bytes as a document that can run. Everything else framed in place keeps the sandbox and the presigned URL. A .pdf whose stored type is application/octet-stream previews too; a type that says something else is believed over the extension.
• A declared entity root draws itself: icon: 'backup' on an EntityRootSpec makes the Backups folder look like backups instead of like People.
• New folder, rename, move, copy, delete, and a metadata editor (caption, date taken, location, people, tags, notes, type), one file at a time or several.
• Search across folders and files, debounced.

Every button it draws comes from a permission the server computed. It never decides for itself what someone may do — and a console given no deleteFile renders no delete button, which is how you build a read-only view.

Administering the tags

<FileTypesAdmin> maintains the per-entity-type tags the details dialog offers — W-9, Contract, Receipt. It takes the entity types it may administer as a prop, because the package cannot know them, and that list doubles as the boundary: an administrator can retag what you name and cannot discover the rest by typing.

Two things the form encodes. name is the handle your code refers to and the key the upsert matches on, so it is fixed once created — only the label and the ordering are editable. And deleting a tag does not delete the files carrying it: file_type_id is ON DELETE SET NULL, so they survive and lose the label, which the confirmation says out loud.

It is not privileged in itself; the endpoints behind upsertFileType and deleteFileType are where an administrator check belongs.

Where files come from

The Upload button takes files from the computer. Give it sources and it becomes a split button with a menu:

import { createGoogleUploadSources } from '@speles7172/file-console/google';

const sources = useMemo(
  () => createGoogleUploadSources({ apiKey, clientId }),
  [apiKey, clientId],
);
<FileExplorer transport={transport} sources={sources} />

Optional in three ways, so one package fits an application that has a Google project and one that does not yet: the code is a separate entry point, so not importing it means none of it is in your bundle; createGoogleUploadSources({}) returns nothing, so missing credentials produce a plain Upload button rather than a broken menu; and nothing loads from Google until a source is actually picked. Credentials that appear later are just a later render.

Which Drive scope

import { DRIVE_SCOPES, createGoogleUploadSources } from '@speles7172/file-console/google';

createGoogleUploadSources({ apiKey, clientId, driveScope: DRIVE_SCOPES.file });

The default is drive.readonly, which reads everything in the person's Drive and which Google classes as a restricted scope: an application requesting it in production goes through OAuth verification, and plausibly an annual third-party security assessment. That is a real cost, paid by every consumer, for a feature whose whole job is "let me pick a file to attach".

DRIVE_SCOPES.file (drive.file) is not restricted. It grants access only to files the person opened with this app, which the Picker is the documented way of doing — the same shape as this flow: somebody picks, and only what they picked is readable.

⚠️ drive.file needs the Picker to know which app is asking. That is the Cloud project number, and it is taken from the leading segment of your client id (<project-number>-<random>.apps.googleusercontent.com) unless you pass appId yourself. Get it wrong and the picker opens, somebody chooses a file, and the download that follows is refused — which reads as a broken download rather than a missing setting.

⚠️ The default stays readonly on purpose. Changing it would move every existing consumer onto a different OAuth scope on a minor upgrade, silently, and possibly onto one their Cloud project is not configured to grant. Choosing the scope is the consuming application's decision, not a patch note's.

Write your own source with an id, a label, an optional icon and a pick() returning { blob, filename, contentType }[].

The transport

const transport: FileTransport = {
  tree: (nodeId) => api(`/files/tree?node=${encodeURIComponent(nodeId)}`),
  search: (term) => api(`/files/search?q=${encodeURIComponent(term)}`),
  createUploadUrl: (input) => api('/files/upload-url', { method: 'POST', body: JSON.stringify(input) }),
  completeUpload: (input) => api('/files/complete', { method: 'POST', body: JSON.stringify(input) }),
  createDownloadUrl: (input) => api('/files/download-url', { method: 'POST', body: JSON.stringify(input) }),
  // …and the folder/file operations you want to offer
};

Every one of those is a method on @speles7172/file-client in front of your own authentication. Only tree is required; the rest are capabilities.

Hold the transport still. The components reload when its identity changes, so an object literal written inline in JSX is a new transport on every render — and therefore an endless reload. Put it in a module constant or behind useMemo.

Styling

Plain semantic HTML with filec- class names and no styling dependency. The stylesheet is optional and entirely driven by custom properties:

.filec {
  --filec-accent: #7c3aed;
  --filec-radius: 4px;
}

Nothing in it outranks a host that overrides them — the theme selectors are wrapped in :where(), and a test fails the build if that stops being true. Light is the default, because the page around it is yours; theme="dark" picks the dark palette and theme="auto" follows prefers-color-scheme.

The published stylesheet already includes @speles7172/controls' own, because the details dialog renders its pickers — one import, no half-unstyled dialog.

Without the markup

const state = useFileExplorer({ transport, rootNodeId: 'project:7' });

Everything the browser does — navigation, search, uploads, the mutations — with none of the HTML. For an application with its own design system.

Licence

MIT.