hb-uploader — integrator guide

Category: utilities · Tags: utilities, files · Package: @htmlbricks/hb-uploader

Web component that wraps an inner hb-dialog and runs a fetch upload when the dialog opens. It shows a Bulma <progress> bar: indeterminate while the request is starting or when byte-level progress is not available, then determinate with a percentage when the body is streamed and a known size exists. Upload parameters come from fetch_data (url, data, optional method, optional headers). The component forwards modalShow from the dialog and emits uploadComplete or uploadError when the request finishes or fails.

Dependencies

• hb-dialog — modal shell, title slot, and open/close lifecycle. The uploader sets the dialog’s show attribute from fetch_data.url and upload state (see Behavior).

Custom element

hb-uploader

Attributes and properties

In HTML, attributes are snake_case and values are strings (project convention: booleans as yes / no on elements that expose them, objects as JSON strings, numbers as string digits). fetch_data is always provided to the component as serialized JSON when using attributes.

| Name | Required | Description | | --- | --- | --- | | fetch_data | No (see behavior) | JSON string describing the upload: url (string), data (any JSON-serializable value, string, or structure your runtime assigns via properties), optional method (string; default POST, uppercased when sent), optional headers (plain object of string values). If the attribute/property value is a string, the component attempts JSON.parse inside an effect. | | upload_id | No | Identifier used in CustomEvent detail and passed to the inner dialog as id. If omitted, it defaults to ${id}_dialog (see id below). | | id | No | Host id; when upload_id is not set, upload_id becomes id + "_dialog". | | style | No | Present in typings for parity with other components; not wired in the current implementation. |

fetch_data shape

| Field | Required | Description | | --- | --- | --- | | url | Yes, to perform an upload | Request URL passed to fetch. When the dialog opens with a non-empty URL, the upload runs. | | data | Yes for a real request | Request body source. At runtime (e.g. from script), this may be FormData, Blob, ArrayBuffer, a typed array, a string, or a plain object (serialized as JSON with default Content-Type: application/json unless you set Content-Type in headers). From HTML attributes alone, use JSON-compatible values inside the JSON string. | | method | No | HTTP method; defaults to POST. | | headers | No | Extra request headers as a plain object { "Header-Name": "value" }. Empty or missing values are skipped when building Headers. |

Slots

| Slot | Description | | --- | --- | | title | Light-DOM content for the dialog title. Default text: Uploading. |

Events

All events are DOM CustomEvent instances dispatched on hb-uploader.

| Event | detail shape | When it fires | | --- | --- | --- | | modalShow | { id: string; show: boolean } | Forwarded from the inner hb-dialog whenever modal visibility changes. | | uploadComplete | { completed: boolean; id: string } | After a successful response (response.ok). | | uploadError | { completed: boolean; id: string; error: Error } | On missing fetch_data, fetch failure, non-OK HTTP status, or thrown errors during the upload path. |

Listen with addEventListener('uploadComplete', ...) or the corresponding onuploadcomplete style in frameworks that map event names.

CSS custom properties

These Bulma variables theme spacing and typography for the percentage line under the progress bar (see Bulma CSS variables).

| Variable | Role | | --- | --- | | --bulma-column-gap | Space between stacked labels and the progress control (default fallback in SCSS: 0.5rem). | | --bulma-size-small | Supporting text size for the percentage label (fallback: 0.875rem). | | --bulma-text | Primary label / percentage color (fallback: #4a4a4a). |

Progress bar colors use Bulma’s primary progress styles from the forwarded elements/progress module.

CSS ::part

None on this host (styleSetup.parts is empty). Dialog chrome and any dialog-level parts belong to hb-dialog.

Behavior and integration notes

1. When the upload runs — On modalShow with show: true, if fetch_data?.url is set, the component starts onModalOpened: resets loaded, builds Headers, resolves a Blob (or stream) from fetch_data.data, and calls fetch(url, { method, headers, body }).

2. Method — fetch_data.method defaults to POST and is normalized with .toUpperCase().

3. Body and progress — FormData is sent as-is; byte streaming progress is not tracked, so the UI uses an indeterminate bar until completion, then treats the upload as done. For string, Blob, ArrayBuffer, ArrayBufferView, or JSON-serialized object bodies with non-zero size, the component wraps the blob in a ReadableStream that updates loaded / total for a determinate bar and percentage. Zero-byte non-FormData bodies skip stream progress; the UI jumps to completed state when the response is OK.

4. Errors — Non-OK responses read response.text() when possible and throw with that text, statusText, or a status-based message. Errors are shown as plain text in the dialog body; uploadError is dispatched with the Error.

5. Missing configuration — If fetch_data is missing when the dialog triggers an upload, the component sets an error message and dispatches uploadError.

6. Inner dialog visibility — The inner hb-dialog receives show="yes" when fetch_data.url is truthy or when both loaded and total are truthy (so the dialog can remain visible around completion states). Actual fetch execution is gated on fetch_data?.url when the modal opens.

7. Storybook — extra/docs.ts maps Storybook actions to uploadComplete, uploadError, and modalShow (same names as runtime CustomEvent types).

Examples

Minimal HTML (placeholder URL)

Replace the URL with your API endpoint and adjust data to match your server contract.

<hb-uploader
  fetch_data='{"url":"https://api.example.com/upload","data":{},"method":"POST"}'
  upload_id="my-upload-dialog"
></hb-uploader>

POST with custom headers (JSON fetch_data)

<hb-uploader
  upload_id="job-post-1"
  fetch_data='{"url":"https://httpbin.org/post","method":"POST","data":{"batch":"2026-03-30"},"headers":{"X-Upload-Client":"my-app"}}'
></hb-uploader>

Custom title slot

<hb-uploader fetch_data='{"url":"https://api.example.com/v1/files","data":{}}'>
  <span slot="title">Sending files…</span>
</hb-uploader>

Listening for completion in JavaScript

const el = document.querySelector('hb-uploader');
el.addEventListener('uploadComplete', (e) => {
  console.log('upload id:', e.detail.id, 'completed flag:', e.detail.completed);
});
el.addEventListener('uploadError', (e) => {
  console.error(e.detail.error);
});

Package

@htmlbricks/hb-uploader — ensure your bundle registers hb-dialog (and this package’s main.iife.js) per your HTML Bricks / app setup.