pict-section-upload

A themeable, pict-native dropzone file-upload control. Drag-and-drop or browse, single & multi file, per-file progress + status, and a host-agnostic UploadTarget seam: read files entirely in the browser (for client-side parsing) or stream/POST them up to a server.

Built to the Pict conventions: a provider exposes the API + registers themed CSS, a view renders the dropzone, and the destination of the bytes is a swappable target — mirroring the DataProvider seam in pict-section-picker.

Install

npm install pict-section-upload

Depends only on pict-provider + pict-view.

Usage

const libPictSectionUpload = require('pict-section-upload');

// Register the provider (once).
pict.addProvider('Pict-Section-Upload', libPictSectionUpload.default_configuration, libPictSectionUpload);
const tmpUpload = pict.providers['Pict-Section-Upload'];

// A read-in-browser uploader (the bytes never leave the page):
tmpUpload.createUploader('MyUploader',
{
    DestinationAddress: '#MyUploader',
    ValueAddress:       'AppData.MyForm.File',   // receives the file handle
    Accept:             '.csv,.tsv,text/csv',     // <input accept>-style filter
    MaxSize:            10 * 1024 * 1024,         // bytes (0 = unbounded)
    Multiple:           false,
    OnComplete: (pHandle) =>
    {
        pHandle.getText((pError, pText) => { /* parse pText client-side */ });
    },
});
pict.views['MyUploader'].render();

Stream to a server

tmpUpload.createUploader('ServerUploader',
{
    UploadTarget: { Type: 'server', Endpoint: '/1.0/Upload', Method: 'POST', FieldName: 'file' },
    OnProgress: (pHandle, pPercent) => { /* ... */ },
    OnComplete: (pHandle) => { /* pHandle.ServerId / pHandle.ServerURL */ },
});

Set Raw: true on the server target to stream the raw file body (e.g. a PUT to object storage) instead of multipart FormData. Supply ResponseHandle(xhr) to map a custom response into { ServerId, ServerURL, ServerResponse }.

The file handle (downstream contract)

ValueAddress (and getFiles()) yield handles shaped like:

{
    Hash, Name, Size, Type,
    Status: 'pending' | 'reading' | 'uploading' | 'complete' | 'error',
    Progress, Error, ServerId, ServerURL, ServerResponse,
    getText(cb), getArrayBuffer(cb), getDataURL(cb), getFile()
}

The read methods are non-enumerable, so a handle JSON.stringifys to just its data fields (safe to stash in AppData) while staying callable on the live object.

Custom targets

UploadTarget may be 'browser', 'server', a { Type:'server', ... } object, or any object implementing the seam:

{
    supportsUpload: boolean,
    read(pFile, 'text'|'arraybuffer'|'dataurl', fCallback),
    upload(pHandle, pFile, fProgress, fCallback) -> { abort() }
}

Provider API

| Method | Purpose | |---|---| | createUploader(hash, config) | Create (or reconfigure + reuse) an uploader view. | | createBrowserTarget(config) / createServerTarget(config) | Build a target directly. | | wrapFile(file, target?) | Build a file handle from a native File without a view. | | PictProviderUpload.formatBytes(bytes) | Human-readable size helper. |

Theming

All control CSS uses var(--theme-color-*, fallback) tokens (registered at CSS priority 500), so the dropzone, progress bar, and status badges follow the host theme. See pict-section-theme for the token set.

Demo

example_applications/upload_demo — four uploaders (read-text, multi-image thumbnails, mock-server-with-progress, and Accept/MaxSize rejection). Build with npm run build, then serve dist/.

Test

npm test     # mocha TDD