@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 framed without a 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. The URL is cross-origin, so the same-origin policy still stands between the document and this page. Everything else framed in place keeps the sandbox.
• 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.

Write your own 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.