# HTML Bricks `hb-*` web components — agent & LLM reference

## What this document is

A **consumer-oriented reference** for **`hb-*` custom elements**: tags, attributes, events, slots, and how to theme and interact with them from **HTML, JavaScript, or any UI stack**. It does **not** describe how to build or publish the library.

## How to use these components

1. **Attributes** — Public property **names** use **snake_case**. **Values are always strings** from HTML or `setAttribute`: you cannot pass native objects, numbers, or booleans. **Objects** (and structured data) must be **serialized** (typically **JSON strings**). **Numbers** must be passed as their **string form** (e.g. `"42"`). **Booleans** must be the strings **`yes`** or **`no`**. Arrays are also passed as **strings** (usually JSON). A component’s README is authoritative if it documents a special encoding.
2. **Custom events (listening)** — Outputs are **`CustomEvent`** instances fired on the **host element**. The **event `type` string** is the key from that component’s **`Events`** contract (same names as in `list.json` → `definitions.events` and in each README): usually **camelCase** (e.g. `clipboardCopyText`, `footerClick`).
   - **HTML / vanilla JavaScript** — Call **`element.addEventListener(<eventType>, handler)`** with that exact string. Read the payload from **`event.detail`** (shape matches the JSON Schema for that event in the manifest). Use **`removeEventListener`** or **`{ once: true }`** as usual.
   - **Svelte 5** — On **`<hb-…>`** (or any DOM element), use an **attribute named `on` + the exact event type** (case-sensitive). Examples: **`onclick={…}`** for `click`; **`onfooterClick={…}`** for `footerClick`; **`onclipboardCopyText={…}`** for `clipboardCopyText`. This follows Svelte’s element event rules ([Basic markup → Events](https://svelte.dev/docs/svelte/basic-markup#Events)): listener attributes start with `on`, and casing distinguishes e.g. `click` from `Click`. Shorthand **`{onfooterClick}`** works when the handler variable name matches. With **`svelte-elements.d.ts`** from each package (or **hb-bundle**), **`on<EventKey>`**, **`on<EventKey>capture`**, and **`'on:<EventKey>'`** are typed per tag.
3. **Theming** — The layout/CSS framework is **Bulma 1.x**; icons use **Bootstrap Icons**. To change appearance (colors, theme, spacing where exposed), set **Bulma CSS custom properties** (`--bulma-*`, see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/)) on the **host element**, a parent wrapper, or higher in the cascade. Those variables typically flow into **shadow DOM** content. Prefer **`--bulma-*`** (and any **component-documented** custom properties) over unrelated ad-hoc rules. Each component section below may list extra **CSS variables** and **`::part(...)`** names when exposed.
4. **Shadow DOM** — Most hosts attach a **shadow root**. Style via inherited **variables** and documented **`::part(...)`** selectors; use **`addEventListener`** or Svelte **`on…`** attributes on the host for outputs described in each section.
5. **Reading the entries** — Sections may use tables or TypeScript-like snippets for props and events; treat those as the **public contract** for that tag.

### Machine-readable contracts: `list.json` (per-component JSON Schema)

The published **@htmlbricks/hb-bundle** file `list.json` has shape `{ "version": "…", "packages": [ … ] }`. Each `packages[]` item is a **component manifest** (same shape as `manifest.json` on npm, minus `iifeIntegrity`). Use it when you need **exact** typings beyond prose.

#### How to find **custom events** and **`detail`** types

1. Pick the manifest where `name` matches the tag (e.g. `"hb-area-code"`).
2. Open `definitions.events`: it is a **JSON Schema** document (draft-07) generated from the component’s `Events` TypeScript type.
3. Inside that document, locate the schema for the `Events` object — typically `definitions.events.definitions.Events` (an object with `type: "object"` and `properties`).
4. **Each property name under `properties` is the `CustomEvent` name** (the string passed to `addEventListener` and emitted as `event.type`). Example: `clipboardCopyText`, `footerClick`.
5. The **value** for that property is the JSON Schema for **`event.detail`**: usually `type: "object"` with its own `properties`, `required`, and nested `$ref` to `#/definitions/...` for structured payloads. Resolve `$ref` inside the same `definitions.events` document.

Human-readable event names and examples still appear in each component’s README section below; use `list.json` when you need the **schema-level** breakdown.

#### How to find **property** types (`Component` props)

1. Same manifest entry; open `definitions.component` (JSON Schema for the `Component` TypeScript interface).
2. Locate `definitions.component.definitions.Component` (or the object referenced by the root `$ref` for `Component`).
3. Under **`properties`**, each key is a **prop name as in TypeScript** (often **camelCase**). The schema gives `type`, `enum`, `items` (arrays), and `$ref` to shared shapes (`ICompany`, `IColumn`, …) in the same document’s `definitions` map.
4. For **HTML markup**, this library documents **attribute names** in each README (**snake_case** on the host). **All attribute values are strings**: numbers as string digits, booleans as **`yes`/`no`**, objects/arrays as **JSON strings** (or another encoding only if that README says so). When the schema uses camelCase (`companyName`) and the README shows a snake_case attribute (`disable_expanding_small`), **follow the README for attribute names** and use the schema for **structure and types** inside JSON-valued props (e.g. shape of `company`).

Cross-check: README table (authoritative for attributes) + `definitions.component` (authoritative for JSON types and nesting).

### TypeScript & Svelte typings (`types/` on each npm package)

Every published **`@htmlbricks/hb-<folder>`** tarball includes a **`types/`** folder next to the IIFE (generated on `npm run build:wc`, not committed under `src/wc`):

| File | Role |
|------|------|
| `webcomponent.type.d.ts` | Authoring types: `Component`, `Events`, and shared interfaces (same logical model as `list.json` schemas). |
| `webcomponent.type.d.json`, `webcomponent_events.type.d.json` | JSON Schema for props and custom-event `detail` (machine-readable). |
| `html-elements.d.ts` | **DOM**: augments `HTMLElementTagNameMap` and listener overloads for `querySelector` / `createElement` / `addEventListener` in plain TypeScript. Package `types` field points here. Subpath: `@htmlbricks/hb-<folder>/types/html-elements`. |
| `svelte-elements.d.ts` | **Svelte**: augments `SvelteHTMLElements` for **`<hb-…>`** in **`.svelte`**: host attributes from `Component` (optional strings, excluding DOM key clashes) and **custom events** from `Events` as `on<EventKey>`, `on<EventKey>capture`, and `'on:<EventKey>'` with typed `CustomEvent` / `detail`. Requires **`svelte`**. Subpath: `@htmlbricks/hb-<folder>/types/svelte-elements`. |

**`@htmlbricks/hb-bundle`** publishes **`types/html-elements.d.ts`** and **`types/svelte-elements.d.ts`**, each aggregating all tags via `/// <reference path="./elements/<folder>/…" />` and copied `webcomponent.type.d.ts` shims under `types/elements/` (imports rewritten for the flat layout).

**Usage (examples):** `compilerOptions.types`: `["@htmlbricks/hb-bundle"]` for bundle DOM typings; in a Svelte app add `import "@htmlbricks/hb-bundle/types/svelte-elements"` (or the matching `@htmlbricks/hb-<folder>` path) in `app.d.ts` or a global `.d.ts` so the compiler loads `SvelteHTMLElements` augmentations.

### Table of contents — how to use this with LLMs

- The **full text** of each component’s `README.md` is **included later in this same document**, under an HTML anchor `id="wc-<folder>"` (Markdown link: `#wc-<folder>`).
- The **jsDelivr** URL is the **canonical** `README.md` from npm (`@htmlbricks/hb-<folder>` at version **0.71.10**). The prose merged **below this TOC** is the **same document body** (duplicate for single-file reading).
- When answering **from this file only**, use the **in-document** link (`#wc-…`) so the model stays in one context. Use the **jsDelivr** link when you need the standalone README URL (e.g. fetching from the CDN).

## Table of contents

Each line lists: **tag — folder**, then **canonical README (npm/jsDelivr)**, then **same content inside this file**.

- **`hb-area-code` — `area-code`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-area-code@0.71.10/README.md) · [same text in this document](#wc-area-code)
- **`hb-auth` — `auth`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-auth@0.71.10/README.md) · [same text in this document](#wc-auth)
- **`hb-auth-social-login-button` — `auth-social-login-button`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-auth-social-login-button@0.71.10/README.md) · [same text in this document](#wc-auth-social-login-button)
- **`hb-banner` — `banner`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-banner@0.71.10/README.md) · [same text in this document](#wc-banner)
- **`hb-calendar-appointments` — `calendar-appointments`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-calendar-appointments@0.71.10/README.md) · [same text in this document](#wc-calendar-appointments)
- **`hb-calendar-events` — `calendar-events`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-calendar-events@0.71.10/README.md) · [same text in this document](#wc-calendar-events)
- **`hb-captcha-google-recaptcha-v2-invisible` — `captcha-google-recaptcha-v2-invisible`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-captcha-google-recaptcha-v2-invisible@0.71.10/README.md) · [same text in this document](#wc-captcha-google-recaptcha-v2-invisible)
- **`hb-card-video` — `card-video`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-card-video@0.71.10/README.md) · [same text in this document](#wc-card-video)
- **`hb-chartjs` — `chartjs`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-chartjs@0.71.10/README.md) · [same text in this document](#wc-chartjs)
- **`hb-checkout` — `checkout`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-checkout@0.71.10/README.md) · [same text in this document](#wc-checkout)
- **`hb-checkout-shopping-cart` — `checkout-shopping-cart`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-checkout-shopping-cart@0.71.10/README.md) · [same text in this document](#wc-checkout-shopping-cart)
- **`hb-contact-card` — `contact-card`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-contact-card@0.71.10/README.md) · [same text in this document](#wc-contact-card)
- **`hb-contact-item` — `contact-item`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-contact-item@0.71.10/README.md) · [same text in this document](#wc-contact-item)
- **`hb-cookie-law-banner` — `cookie-law-banner`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-cookie-law-banner@0.71.10/README.md) · [same text in this document](#wc-cookie-law-banner)
- **`hb-dashboard-card1` — `dashboard-card1`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-dashboard-card1@0.71.10/README.md) · [same text in this document](#wc-dashboard-card1)
- **`hb-dashboard-counter-lines` — `dashboard-counter-lines`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-dashboard-counter-lines@0.71.10/README.md) · [same text in this document](#wc-dashboard-counter-lines)
- **`hb-dashboard-indicator` — `dashboard-indicator`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-dashboard-indicator@0.71.10/README.md) · [same text in this document](#wc-dashboard-indicator)
- **`hb-dialog` — `dialog`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-dialog@0.71.10/README.md) · [same text in this document](#wc-dialog)
- **`hb-dialog-loader` — `dialog-loader`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-dialog-loader@0.71.10/README.md) · [same text in this document](#wc-dialog-loader)
- **`hb-dialogform` — `dialogform`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-dialogform@0.71.10/README.md) · [same text in this document](#wc-dialogform)
- **`hb-downloader` — `downloader`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-downloader@0.71.10/README.md) · [same text in this document](#wc-downloader)
- **`hb-dropdown-notifications` — `dropdown-notifications`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-dropdown-notifications@0.71.10/README.md) · [same text in this document](#wc-dropdown-notifications)
- **`hb-dropdown-simple` — `dropdown-simple`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-dropdown-simple@0.71.10/README.md) · [same text in this document](#wc-dropdown-simple)
- **`hb-editor-video` — `editor-video`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-editor-video@0.71.10/README.md) · [same text in this document](#wc-editor-video)
- **`hb-faq-component` — `faq-component`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-faq-component@0.71.10/README.md) · [same text in this document](#wc-faq-component)
- **`hb-footer` — `footer`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-footer@0.71.10/README.md) · [same text in this document](#wc-footer)
- **`hb-form` — `form`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-form@0.71.10/README.md) · [same text in this document](#wc-form)
- **`hb-form-composer` — `form-composer`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-form-composer@0.71.10/README.md) · [same text in this document](#wc-form-composer)
- **`hb-form-contact` — `form-contact`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-form-contact@0.71.10/README.md) · [same text in this document](#wc-form-contact)
- **`hb-funnel` — `funnel`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-funnel@0.71.10/README.md) · [same text in this document](#wc-funnel)
- **`hb-gallery-video` — `gallery-video`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-gallery-video@0.71.10/README.md) · [same text in this document](#wc-gallery-video)
- **`hb-gauge` — `gauge`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-gauge@0.71.10/README.md) · [same text in this document](#wc-gauge)
- **`hb-input-area` — `input-area`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-area@0.71.10/README.md) · [same text in this document](#wc-input-area)
- **`hb-input-array-objects` — `input-array-objects`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-array-objects@0.71.10/README.md) · [same text in this document](#wc-input-array-objects)
- **`hb-input-array-tags` — `input-array-tags`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-array-tags@0.71.10/README.md) · [same text in this document](#wc-input-array-tags)
- **`hb-input-checkbox` — `input-checkbox`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-checkbox@0.71.10/README.md) · [same text in this document](#wc-input-checkbox)
- **`hb-input-color` — `input-color`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-color@0.71.10/README.md) · [same text in this document](#wc-input-color)
- **`hb-input-coords` — `input-coords`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-coords@0.71.10/README.md) · [same text in this document](#wc-input-coords)
- **`hb-input-date` — `input-date`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-date@0.71.10/README.md) · [same text in this document](#wc-input-date)
- **`hb-input-datetime` — `input-datetime`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-datetime@0.71.10/README.md) · [same text in this document](#wc-input-datetime)
- **`hb-input-email` — `input-email`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-email@0.71.10/README.md) · [same text in this document](#wc-input-email)
- **`hb-input-file` — `input-file`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-file@0.71.10/README.md) · [same text in this document](#wc-input-file)
- **`hb-input-number` — `input-number`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-number@0.71.10/README.md) · [same text in this document](#wc-input-number)
- **`hb-input-radio` — `input-radio`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-radio@0.71.10/README.md) · [same text in this document](#wc-input-radio)
- **`hb-input-range` — `input-range`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-range@0.71.10/README.md) · [same text in this document](#wc-input-range)
- **`hb-input-select` — `input-select`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-select@0.71.10/README.md) · [same text in this document](#wc-input-select)
- **`hb-input-text` — `input-text`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-input-text@0.71.10/README.md) · [same text in this document](#wc-input-text)
- **`hb-json-viewer` — `json-viewer`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-json-viewer@0.71.10/README.md) · [same text in this document](#wc-json-viewer)
- **`hb-layout` — `layout`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-layout@0.71.10/README.md) · [same text in this document](#wc-layout)
- **`hb-layout-desktop` — `layout-desktop`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-layout-desktop@0.71.10/README.md) · [same text in this document](#wc-layout-desktop)
- **`hb-layout-mobile` — `layout-mobile`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-layout-mobile@0.71.10/README.md) · [same text in this document](#wc-layout-mobile)
- **`hb-map` — `map`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-map@0.71.10/README.md) · [same text in this document](#wc-map)
- **`hb-markdown-viewer` — `markdown-viewer`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-markdown-viewer@0.71.10/README.md) · [same text in this document](#wc-markdown-viewer)
- **`hb-matrix-video` — `matrix-video`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-matrix-video@0.71.10/README.md) · [same text in this document](#wc-matrix-video)
- **`hb-messages-box` — `messages-box`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-messages-box@0.71.10/README.md) · [same text in this document](#wc-messages-box)
- **`hb-messages-list` — `messages-list`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-messages-list@0.71.10/README.md) · [same text in this document](#wc-messages-list)
- **`hb-messages-send` — `messages-send`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-messages-send@0.71.10/README.md) · [same text in this document](#wc-messages-send)
- **`hb-messages-topics-card` — `messages-topics-card`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-messages-topics-card@0.71.10/README.md) · [same text in this document](#wc-messages-topics-card)
- **`hb-modal-video` — `modal-video`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-modal-video@0.71.10/README.md) · [same text in this document](#wc-modal-video)
- **`hb-navbar` — `navbar`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-navbar@0.71.10/README.md) · [same text in this document](#wc-navbar)
- **`hb-offcanvas` — `offcanvas`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-offcanvas@0.71.10/README.md) · [same text in this document](#wc-offcanvas)
- **`hb-order-list` — `order-list`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-order-list@0.71.10/README.md) · [same text in this document](#wc-order-list)
- **`hb-pad-joystick` — `pad-joystick`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-pad-joystick@0.71.10/README.md) · [same text in this document](#wc-pad-joystick)
- **`hb-page-checkout` — `page-checkout`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-page-checkout@0.71.10/README.md) · [same text in this document](#wc-page-checkout)
- **`hb-page-invoice` — `page-invoice`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-page-invoice@0.71.10/README.md) · [same text in this document](#wc-page-invoice)
- **`hb-paginate` — `paginate`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-paginate@0.71.10/README.md) · [same text in this document](#wc-paginate)
- **`hb-paragraps-around-image` — `paragraps-around-image`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-paragraps-around-image@0.71.10/README.md) · [same text in this document](#wc-paragraps-around-image)
- **`hb-paragraps-around-image-cell` — `paragraps-around-image-cell`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-paragraps-around-image-cell@0.71.10/README.md) · [same text in this document](#wc-paragraps-around-image-cell)
- **`hb-payment-paypal` — `payment-paypal`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-payment-paypal@0.71.10/README.md) · [same text in this document](#wc-payment-paypal)
- **`hb-player-input-streaming` — `player-input-streaming`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-player-input-streaming@0.71.10/README.md) · [same text in this document](#wc-player-input-streaming)
- **`hb-player-live` — `player-live`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-player-live@0.71.10/README.md) · [same text in this document](#wc-player-live)
- **`hb-player-live-camera-ptz` — `player-live-camera-ptz`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-player-live-camera-ptz@0.71.10/README.md) · [same text in this document](#wc-player-live-camera-ptz)
- **`hb-product-comparison` — `product-comparison`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-product-comparison@0.71.10/README.md) · [same text in this document](#wc-product-comparison)
- **`hb-range-slider` — `range-slider`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-range-slider@0.71.10/README.md) · [same text in this document](#wc-range-slider)
- **`hb-searchbar` — `searchbar`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-searchbar@0.71.10/README.md) · [same text in this document](#wc-searchbar)
- **`hb-shop-item-cell` — `shop-item-cell`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-shop-item-cell@0.71.10/README.md) · [same text in this document](#wc-shop-item-cell)
- **`hb-shop-item-row` — `shop-item-row`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-shop-item-row@0.71.10/README.md) · [same text in this document](#wc-shop-item-row)
- **`hb-sidebar-cards-navigator` — `sidebar-cards-navigator`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-sidebar-cards-navigator@0.71.10/README.md) · [same text in this document](#wc-sidebar-cards-navigator)
- **`hb-sidebar-desktop` — `sidebar-desktop`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-sidebar-desktop@0.71.10/README.md) · [same text in this document](#wc-sidebar-desktop)
- **`hb-sidenav-button` — `sidenav-button`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-sidenav-button@0.71.10/README.md) · [same text in this document](#wc-sidenav-button)
- **`hb-sidenav-link` — `sidenav-link`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-sidenav-link@0.71.10/README.md) · [same text in this document](#wc-sidenav-link)
- **`hb-site-contacts-row` — `site-contacts-row`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-site-contacts-row@0.71.10/README.md) · [same text in this document](#wc-site-contacts-row)
- **`hb-site-paragraph-with-image` — `site-paragraph-with-image`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-site-paragraph-with-image@0.71.10/README.md) · [same text in this document](#wc-site-paragraph-with-image)
- **`hb-site-slideshow` — `site-slideshow`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-site-slideshow@0.71.10/README.md) · [same text in this document](#wc-site-slideshow)
- **`hb-site-slideshow-horizontal` — `site-slideshow-horizontal`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-site-slideshow-horizontal@0.71.10/README.md) · [same text in this document](#wc-site-slideshow-horizontal)
- **`hb-skeleton-component` — `skeleton-component`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-skeleton-component@0.71.10/README.md) · [same text in this document](#wc-skeleton-component)
- **`hb-stylus-notebook` — `stylus-notebook`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-stylus-notebook@0.71.10/README.md) · [same text in this document](#wc-stylus-notebook)
- **`hb-stylus-paper` — `stylus-paper`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-stylus-paper@0.71.10/README.md) · [same text in this document](#wc-stylus-paper)
- **`hb-table` — `table`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-table@0.71.10/README.md) · [same text in this document](#wc-table)
- **`hb-terms-doc-templates` — `terms-doc-templates`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-terms-doc-templates@0.71.10/README.md) · [same text in this document](#wc-terms-doc-templates)
- **`hb-toast` — `toast`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-toast@0.71.10/README.md) · [same text in this document](#wc-toast)
- **`hb-tooltip` — `tooltip`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-tooltip@0.71.10/README.md) · [same text in this document](#wc-tooltip)
- **`hb-uploader` — `uploader`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-uploader@0.71.10/README.md) · [same text in this document](#wc-uploader)
- **`hb-vertical-img-txt-archive` — `vertical-img-txt-archive`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-vertical-img-txt-archive@0.71.10/README.md) · [same text in this document](#wc-vertical-img-txt-archive)

---

<a id="wc-area-code"></a>

## `hb-area-code` — area-code

**Category:** utilities | **Tags:** utilities, developer

### What it does

Displays arbitrary text inside a `<code>` block with a themed background. A copy button copies the content to the clipboard, shows brief confirmation, and dispatches a `clipboardCopyText` custom event with the copied string.

### Custom element

`hb-area-code`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `content` | string (required) | Text shown inside the code block. |

**Style / theming:** CSS custom property `--hb-area-code-background` (color). **CSS part:** `content` (the code element). No HTML slots.

### Events (`CustomEvent` names)

- **`clipboardCopyText`** — `{ text: string }` — Fired after a successful clipboard copy with the copied text.

### Usage notes

- Uses Bootstrap-aligned theming patterns; primary styling is the component SCSS and `--hb-area-code-background`.
- Icons: not central to this component (copy UI is internal).
- Shadow DOM: `::part(content)` can target the code element.
- No i18n entries in `docs.ts`.

### Minimal HTML example

```html
<hb-area-code content="npm install @htmlbricks/hb-area-code"></hb-area-code>
```

---

<a id="wc-auth"></a>

## `hb-auth` — auth

**Category:** auth | **Tags:** auth

### What it does

Full authentication UI driven by the `type` attribute: local login and registration (with optional “remember me”), email activation, password recovery and related notices, OTP and two-factor setup/verification. Supports OAuth2 social providers via embedded social-login buttons, configurable backend URIs and HTTP options, optional i18n, and dispatches events for login, registration, recovery/activation, and OAuth flow steps.

### Custom element

`hb-auth`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `type` | union (optional) | `"login"` \| `"register"` \| `"activate"` \| `"recover"` \| `"forgotpassword"` \| `"mailrecoverinfo"` \| `"otp"` \| `"2fa_code"` \| `"2fa_config"` — which screen to show. |
| `email` | string (optional) | Pre-filled or context email. |
| `i18nlang` | string (optional) | Language key (e.g. `en`, `it`). |
| `sessionkey` | string (optional) | Session-related key for flows. |
| `social_auth_server_url` | string (optional) | Base URL for social auth server. |
| `redirectonlogin` | string (optional) | Redirect after login. |
| `redirectoncreate` | string (optional) | Redirect after registration. |
| `loginuri` | string (optional) | Backend login endpoint. |
| `registeruri` | string (optional) | Backend register endpoint. |
| `activateuri` | string (optional) | Activation endpoint. |
| `recoveruri` | string (optional) | Recovery endpoint. |
| `requestmethod` | string (optional) | HTTP method for API calls. |
| `appendqueryparams` | string (optional) | Extra query params (often JSON string in HTML). |
| `appendbodyparams` | string (optional) | Extra body params (often JSON string in HTML). |
| `logouri` | string (optional) | Logo image URL. |
| `oauth2providers` | array (optional) | JSON array of `{ name, url?, params? }` provider configs (see `hb-auth-social-login-button` provider shape). |
| `disableregister` | boolean (optional) | Hide or disable registration. |
| `enable_recover_password` | boolean (optional) | Enable recover-password UI. |
| `passwordpattern` | string (optional) | Password validation pattern. |
| `recoverycode` | string (optional) | Recovery/activation code. |
| `disablelocal` | boolean (optional) | OAuth-only mode when true. |

**Slots:** `header`. **i18n:** Italian and English declared in metadata.

### Events (`CustomEvent` names)

- **`login`** — `{ token?: string; email?: string; password?: string; rememberMe?: boolean }`
- **`register`** — Intersection of `any` with `{ requestSent: { email: string; password: string }; email: string; password: string }` (types).
- **`recoverOrActivate`** — `{ password: string; recoverycode: string; email: string }`
- **`recoverPassword`** — `{ email: string }`
- **`oauthFlowInit`** — `{ token?: string; provider: "facebook" \| "google" \| "gitlab" \| "github" \| "authentik"; tmpCode?: string; redirect_uri?: string }`
- **`oauthFlowSuccess`** — `{ token: string }`
- **`oauthFlowCustom`** — `{ provider: ... }` (same provider union as above)

### Usage notes

- Built with Bulma 1 (Sass) inside the shadow root; theme variables apply on `:host`.
- Uses bootstrap-icons where the UI shows icons.
- Shadow DOM: slot `header` for custom branding; social buttons are composed internally.
- Set `i18nlang` for Italian or English strings where supported.

### Minimal HTML example

```html
<hb-auth
  type="login"
  i18nlang="en"
  logouri="https://example.com/logo.svg"
  loginuri="https://api.example.com/auth/login"
></hb-auth>
```

---

<a id="wc-auth-social-login-button"></a>

## `hb-auth-social-login-button` — auth-social-login-button

**Category:** auth | **Tags:** auth, oauth

### What it does

Clickable OAuth provider tile (default SVGs for Google, GitHub, GitLab, Facebook, Authentik; overridable via slot). Builds the provider authorization URL from `provider` params or uses a prebuilt `url`, then parses the return URL to exchange code/token with `simple-serverless-auth-client` when `social_auth_server_url` and `auth_cookie_name` are set. Emits `oauthFlowInit`, `oauthFlowSuccess`, or `oauthFlowCustom` for custom flows.

### Custom element

`hb-auth-social-login-button`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `social_auth_server_url` | string (optional) | Server URL for token exchange. |
| `auth_cookie_name` | string (optional) | Cookie name used by the auth client. |
| `redirectonlogin` | string (optional) | Post-login redirect. |
| `provider` | object (optional) | JSON: `{ url?: string; name: "facebook" \| "google" \| "gitlab" \| "github" \| "authentik"; params?: { redirect_url; client_id; scope; auth_server_url? } }`. |

**Slots:** `header`. **i18n:** Italian and English in metadata.

### Events (`CustomEvent` names)

- **`oauthFlowSuccess`** — `{ token: string }`
- **`oauthFlowInit`** — `{ token?: string; provider: IProvider; tmpCode?: string; redirect_uri?: string }` (`IProvider` = facebook \| google \| gitlab \| github \| authentik)
- **`oauthFlowCustom`** — `{ provider: IProvider }`

### Usage notes

- Bootstrap 5 theme variables (`--bs-*`) apply to layout/button styling.
- Provider artwork aligns with common OAuth brands; slot `header` can override presentation.
- Shadow DOM encapsulates default SVGs; configure via attributes and slots.
- Use `i18nlang` on parent `hb-auth` or this component’s i18n metadata where wired.

### Minimal HTML example

```html
<hb-auth-social-login-button
  provider='{"name":"google","url":"https://accounts.google.com/o/oauth2/v2/auth?..."}'
  social_auth_server_url="https://auth.example.com"
  auth_cookie_name="session"
></hb-auth-social-login-button>
```

---

<a id="wc-banner"></a>

## `hb-banner` — banner

**Category:** content | **Tags:** content, marketing

### What it does

Marketing-style hero strip: logo image beside a title and subtitle, using **Bulma** `container is-fluid`, `columns`, and `title` / `subtitle`. Desktop layout uses `is-hidden-touch`; compact layout uses `is-hidden-desktop`.

### Custom element

`hb-banner`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `title` | string (optional) | Main heading text. |
| `description` | string (optional) | Subtitle or body text. |
| `logouri` | string (optional) | Logo image URL. |

No CSS vars or slots in style setup metadata.

### Events (`CustomEvent` names)

None declared in types (`Events` is an empty object).

### Usage notes

- Relies on Bulma grid, visibility helpers (`is-hidden-touch`, `is-hidden-desktop`), and typography helpers (`has-text-right`, `has-text-centered`).
- Icons are not bundled; extend the markup if you need icon fonts.
- Shadow DOM keeps typography/spacing internal unless slotted content is added in implementation.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-banner
  title="Welcome"
  description="Build faster with our component library."
  logouri="https://example.com/logo.svg"
></hb-banner>
```

---

<a id="wc-calendar-appointments"></a>

## `hb-calendar-appointments` — calendar-appointments

**Category:** calendar | **Tags:** calendar, appointments

### What it does

Month agenda view: events for the current month are grouped by calendar day and listed chronologically with weekday, day number, time, and colored markers. Optional header with month navigation; changing month or selecting a day dispatches `changeCalendarDate`, `changeSelectedDate`, and clicking a row dispatches `calendarEventClick`. Uses Italian public holidays metadata; `events` is supplied as JSON.

### Custom element

`hb-calendar-appointments`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `date` | Date (optional) | Current calendar month context; pass as ISO string / parsed JSON in HTML. |
| `events` | array (optional) | JSON array of `{ date: Date; label: string; id: string; link?; icon?; color? }`. |
| `selected` | Date (optional) | Selected day. |
| `disable_header` | boolean (optional) | Hide the navigation header when true. |

**Theme:** `--hb-calendar-selected`, `--hb-calendar-hover`, `--hb-calendar-today`. **Parts:** `calendar-header`, `calendar-current-time-header`, `cell`. **Slots:** `header_month_icon_prev`, `header_month_icon_next`, `header`, `calendar_month`.

### Events (`CustomEvent` names)

- **`calendarEventClick`** — `{ eventId: string }`
- **`changeCalendarDate`** — `{ date: Date }`
- **`changeSelectedDate`** — `{ selectedDate: Date }`

### Usage notes

- Bootstrap 5–oriented colors via CSS variables above.
- Italian holiday data is built in; adjust expectations for non-IT locales.
- Shadow DOM exposes named parts for deeper styling.
- Pass `events` and dates as JSON strings from HTML attributes; runtime parsing depends on the web component bridge.

### Minimal HTML example

```html
<hb-calendar-appointments
  disable_header="false"
  events='[{"id":"1","label":"Meeting","date":"2026-03-15T10:00:00.000Z"}]'
></hb-calendar-appointments>
```

---

<a id="wc-calendar-events"></a>

## `hb-calendar-events` — calendar-events

**Category:** calendar | **Tags:** calendar

### What it does

Classic month grid (7-day week header and variable rows) with selectable cells, “today” styling, and event chips inside each day. Supports adjacent-month padding cells, Italian holidays, JSON `events`, and the same navigation/selection events as the appointments calendar.

### Custom element

`hb-calendar-events`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `date` | Date (optional) | Visible month anchor. |
| `events` | array (optional) | JSON array of `{ date: Date; label: string; id: string; link?; icon?; color? }`. |
| `selected` | Date (optional) | Highlighted date. |
| `disable_header` | boolean (optional) | Hide month navigation when true. |

**Theme:** `--hb-calendar-selected`, `--hb-calendar-hover`, `--hb-calendar-today`. **Parts:** `calendar-header`, `calendar-current-time-header`, `cell`. **Slots:** `header_month_icon_prev`, `header_month_icon_next`, `header`, `calendar_month`.

### Events (`CustomEvent` names)

- **`calendarEventClick`** — `{ eventId: string }`
- **`changeCalendarDate`** — `{ date: Date }`
- **`changeSelectedDate`** — `{ selectedDate: Date }`

### Usage notes

- Styling aligns with Bootstrap-themed CSS variables on the host.
- Shares behavior with `hb-calendar-appointments` for events and navigation.
- Shadow DOM + parts allow styling cells and headers.
- No i18n entries in `docs.ts`; holidays skew Italian.

### Minimal HTML example

```html
<hb-calendar-events
  events='[{"id":"a","label":"Launch","date":"2026-03-01T09:00:00.000Z","color":"#0d6efd"}]'
></hb-calendar-events>
```

---

<a id="wc-captcha-google-recaptcha-v2-invisible"></a>

## `hb-captcha-google-recaptcha-v2-invisible` — captcha-google-recaptcha-v2-invisible

**Category:** utilities | **Tags:** utilities, security

### What it does

Loads the Google reCAPTCHA v2 invisible SDK, renders the widget with your `api_key`, and exposes `grecaptcha.execute()` / reset when the `get` attribute changes after render. Dispatches `googleRecaptchaRendered` once mounted and `googleRecaptchaV2Response` with the token from the verification callback.

### Custom element

`hb-captcha-google-recaptcha-v2-invisible`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `api_key` | string (optional) | Google reCAPTCHA site key. |
| `get` | any (optional) | Trigger prop: changing after render drives execute/reset (see component behavior). |

**Bootstrap theme vars** in metadata. **CSS part:** `invalid-feedback`. No slots.

### Events (`CustomEvent` names)

- **`googleRecaptchaV2Response`** — `{ response: string }` — Verification token from Google.
- **`googleRecaptchaRendered`** — `{ render: true }` — Widget finished rendering.

### Usage notes

- Uses Bootstrap form-feedback styling via the `invalid-feedback` part.
- Requires loading Google’s script; CSP and domain allowlisting apply outside the component.
- Shadow DOM wraps the widget; style invalid states through the exposed part.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-captcha-google-recaptcha-v2-invisible api_key="YOUR_SITE_KEY"></hb-captcha-google-recaptcha-v2-invisible>
```

---

<a id="wc-card-video"></a>

## `hb-card-video` — card-video

**Category:** media | **Tags:** media, video

### What it does

**Bulma** `card` with a 16:9 `image` frame: YouTube embed when `provider` is `youtube`, otherwise an HTML5 `<video>` with MP4 source. Optional title, truncated description, formatted `time` via Day.js (`dateformat`), “read more” `button is-primary`, and social share placeholders when `pageuri` is set. Bootstrap Icons for the clock in the footer.

### Custom element

`hb-card-video`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `title` | string (optional) | Card title. |
| `description` | string (optional) | Body text (truncated in UI). |
| `videosrc` | string (required) | Video URL or embed source. |
| `provider` | union (optional) | `"youtube"` or `""` for native video. |
| `pageuri` | string (optional) | Page URL for share widgets. |
| `linklabel` | string (optional) | Label for the “read more” style link. |
| `time` | Date (optional) | Publication or event time; pass parseable date string in HTML. |
| `dateformat` | string (optional) | Day.js format string for `time`. |

**Slot:** `card-footer`. No CSS vars in metadata.

### Events (`CustomEvent` names)

None declared in types (`Events` is an empty object).

### Usage notes

- Card layout follows Bulma `card` / `card-image` / `card-content` / `card-footer` patterns.
- YouTube vs file video is selected only via `provider`; ensure `videosrc` matches the mode.
- Shadow DOM contains the player and share UI; slot `card-footer` extends the card.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-card-video
  videosrc="https://example.com/media/clip.mp4"
  title="Product tour"
  description="A short walkthrough of the dashboard."
  time="2026-03-01T12:00:00.000Z"
  dateformat="MMM D, YYYY"
></hb-card-video>
```

---

<a id="wc-chartjs"></a>

## `hb-chartjs` — chartjs

**Category:** data | **Tags:** data, chart

### What it does

Embeds Chart.js (line, bar, pie, radar, time scales, etc.) inside the shadow DOM. Pass a JSON `data` object with `type`, `data`, and optional `options`; the chart is recreated on data changes and when the container resizes. Clicking the canvas dispatches `chartClick` with the nearest point’s label and value.

### Custom element

`hb-chartjs`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `data` | any (required) | JSON Chart.js configuration: `{ type, data, options? }`. |

**CSS part:** `container`. No slots.

### Events (`CustomEvent` names)

- **`chartClick`** — `{ label?: string; value?: any }[]` — Per types, payload is an **array** of point-like objects (label/value pairs from the hit detection).

### Usage notes

- Chart.js runs inside shadow DOM; global Chart defaults may not apply unless duplicated.
- Bootstrap is not required for the canvas itself; host page can still use BS layout around the element.
- ResizeObserver + debounced window resize keep charts responsive.
- Pass `data` as a JSON string attribute from plain HTML.

### Minimal HTML example

```html
<hb-chartjs
  data='{"type":"bar","data":{"labels":["A","B"],"datasets":[{"label":"K","data":[1,2]}]},"options":{}}'
></hb-chartjs>
```

---

<a id="wc-checkout"></a>

## `hb-checkout` — checkout

**Category:** commerce | **Tags:** commerce, checkout

### What it does

End-to-end checkout flow: editable billing/shipping user profile (`hb-form`), shipment method choice, optional card form, Google Pay, and PayPal via `hb-payment-paypal` according to `gateways` and `payment` JSON. Parses string props into objects, merges card network defaults, and tracks `completed` to switch between editable steps and a read-only confirmation summary with events for payment and form submissions.

### Custom element

`hb-checkout`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `shipments` | array (required) | JSON `IShipment[]`: price, selected?, standard?, arriveDate, available, id, label, currency. |
| `user` | object (optional) | JSON `IUser`: fullName, address fields, nationality, fixed?. |
| `gateways` | array (required) | JSON `IGateway[]`: id `google` \| `paypal`, label, fees, PayPal/Google Pay fields. |
| `payment` | object (required) | JSON `IPayment`: merchantName, total, currencyCode, countryCode, type?, shipmentFee?. |
| `completed` | union (optional) | `"yes"` \| `"no"` — controls summary vs edit flow. |

**CSS vars:** `--edit-color`, `--paypal-button-color`, `--hb-checkout-border`, Bulma `--bulma-*` (see `extra/docs.ts`). **Parts:** `title`, `subtitle`, `payment_terms_note`. **Slots:** `payment_terms`, `payment_completed`, `userinfo`, `title`.

### Events (`CustomEvent` names)

- **`paymentCompleted`** — `{ total: number; method: string; completed: true }`
- **`saveUser`** — `IUser` payload
- **`saveShipment`** — `IShipment` payload
- **`completed`** — `"yes"` \| `"no"` (listed in `Events` interface)

### Usage notes

### Styling (Bulma)

Chrome uses **Bulma** `button`, `title`, and `subtitle`. Theme on `:host` via Bulma’s CSS variables; set **`--bulma-*`** (and optional `--edit-color`) from the page. **Bootstrap Icons** load from `<svelte:head>` for delivery/payment icons.

- Nested `hb-form` / payment elements carry their own shadow styles.
- Nested web components (`hb-form`, payment elements) live inside the flow.
- Large JSON props are typical; validate shapes before setting attributes.
- No i18n array in `docs.ts` for this component.

### Minimal HTML example

```html
<hb-checkout
  completed="no"
  payment='{"merchantName":"Acme","total":49.99,"currencyCode":"EUR","countryCode":"IT","type":"buy"}'
  shipments='[{"id":"std","label":"Standard","price":5,"arriveDate":"2026-04-01T00:00:00.000Z","available":true,"currency":"€"}]'
  gateways='[{"id":"paypal","label":"PayPal","paypalid":"sandbox"}]'
></hb-checkout>
```

---

<a id="wc-checkout-shopping-cart"></a>

## `hb-checkout-shopping-cart` — checkout-shopping-cart

**Category:** commerce | **Tags:** commerce, cart

### What it does

Order summary built on `hb-table`: maps `payment.items` into rows (name, quantity, line total), computes subtotal, tax, and grand total from item prices, and shows country/currency. When `completed` is enabled it switches to a compact “order placed” state; `payment` can be supplied as JSON.

### Custom element

`hb-checkout-shopping-cart`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `payment` | object (required) | JSON `IShoppingPayment`: countryCode `IT` \| `US` \| `EU`, currencySymbol?, shipmentFee?, items: `IShopItem[]` (id, name, unitaryPrice, taxPercentage, quantity?, unit?). |
| `completed` | union (optional) | `"yes"` \| `"no"` — order-placed compact UI when enabled. |

**CSS vars:** `--hb-checkout-border`, Bulma `--bulma-*` (see `extra/docs.ts`). No slots or parts in metadata.

### Styling (Bulma)

Uses **Bulma** `container`, `columns` / `column`, and `title`. Theme tokens on `:host`; override with **`--bulma-*`**. **Bootstrap Icons** load from `<svelte:head>` for the cart icon.

### Events (`CustomEvent` names)

None declared in types (`Events` is an empty object).

### Usage notes

- Styling uses Bulma theme variables on `:host` (`--bulma-*`); see `extra/docs.ts`.
- Depends on `hb-table` internally for row layout.
- Shadow DOM encapsulates the table presentation.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-checkout-shopping-cart
  payment='{"countryCode":"IT","currencySymbol":"€","items":[{"id":"sku1","name":"T-shirt","unitaryPrice":19.99,"taxPercentage":22,"quantity":2}]}'
  completed="no"
></hb-checkout-shopping-cart>
```

---

<a id="wc-contact-card"></a>

## `hb-contact-card` — contact-card

**Category:** content | **Tags:** content, contact

### What it does

A comprehensive contact card: personal, contact, company, and social information in a Bulma-styled card. Uses one `data` object with structured arrays for phones, addresses, and social profiles. Features include avatar placeholder, clickable contact rows, social links, collapsible sections, and an actions dropdown with grouping, badges, and links.

### Custom element

`hb-contact-card`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `data` | object (required) | JSON `ContactData`: names, title, emails[], phones[], website, addresses[], company fields, notes, avatar, lat/long, socialMedia[], clickable?. |
| `actions_list` | array (optional) | JSON `IDropDownMenuListItem[]`: key, label, badge?, group?, linkHref?. |
| `i18nlang` | string (optional) | `en` \| `it` (storybook). |
| `show_header_collapse_button` | union (optional) | `"yes"` \| `"no"` — default `"yes"`. |
| `start_collapsed` | union (optional) | `"yes"` \| `"no"` — default `"no"`. |

**CSS vars:** `--hb--contact-card-*` (colors, radius, shadows). **Parts:** `card`, `header`, `body`, `avatar`, `actions`. No HTML slots.

### Events (`CustomEvent` names)

- **`contactClick`** — `{ id: string; contact: Component }` (`Component` = this element’s prop bag type)
- **`contactEdit`** — `{ id: string; contact: Component }`
- **`contactDelete`** — `{ id: string; contact: Component }`
- **`phoneClick`** — `{ id: string; phone: PhoneNumber }`
- **`emailClick`** — `{ id: string; email: EmailAddress }`
- **`websiteClick`** — `{ id: string; website: string }`
- **`socialClick`** — `{ id: string; social: SocialMedia }`
- **`addressClick`** — `{ id: string; address: Address }`
- **`collapseChange`** — `{ id: string; collapsed: boolean }`

### Usage notes

- Colors use custom properties aligned with the card skin; Bulma theme variables apply on `:host`.
- Icons use bootstrap-icons for contact and social affordances.
- Shadow DOM exposes `::part()` hooks for card regions.
- Set `i18nlang` for English or Italian strings.

### Minimal HTML example

```html
<hb-contact-card
  id="c1"
  i18nlang="en"
  data='{"fullName":"Alex Doe","emails":[{"address":"alex@example.com","type":"work"}],"clickable":true}'
  actions_list='[{"key":"edit","label":"Edit"}]'
></hb-contact-card>
```

---

<a id="wc-contact-item"></a>

## `hb-contact-item` — contact-item

**Category:** content | **Tags:** content, contact

### What it does

Single contact line (mutually exclusive props): phone, postal address, email, website, or social network. Renders a Bootstrap Icon and optional visible text; JSON `config` toggles icons (filled/outline), label text, and whether clicks dispatch `contactclick` with `{ action, options }` vs opening a window (maps URL, `mailto`, external site, or social page).

### Custom element

`hb-contact-item`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `phone` | object (optional) | JSON `IPhone`: number, callOnClick?. |
| `address` | object (optional) | JSON `IAddress`: mapUri?, latLang?, address, shortAddress?. |
| `email` | object (optional) | JSON `IEmail`: mailLink?, address. |
| `site` | object (optional) | JSON `ISite`: label?, uri?, open?. |
| `social` | object (optional) | JSON `ISocial`: label?, pageUri?, name. |
| `config` | object (optional) | JSON `IConfig`: icon?.fill, text?, dispatcher?. |

No CSS vars, parts, or slots in metadata.

### Events (`CustomEvent` names)

- **`contactclick`** — `{ action: string; options: any }` — Exact event name is lowercase in types.

### Usage notes

- Icons come from bootstrap-icons naming conventions.
- Only one of phone/address/email/site/social should be primary per row (per description).
- Shadow DOM wraps the row; no theme variables declared in docs.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-contact-item
  email='{"address":"hello@example.com","mailLink":true}'
  config='{"text":true,"dispatcher":true}'
></hb-contact-item>
```

---

<a id="wc-cookie-law-banner"></a>

## `hb-cookie-law-banner` — cookie-law-banner

**Category:** layout | **Tags:** layout, compliance

### What it does

Bootstrap alert cookie notice until the user accepts or declines; the choice is stored in `localStorage` under `cookielaw`. Supports i18n via `i18nlang`, optional `cookielawuri4more` link, JSON `capabilities` for extended consent, slots to override title/text, and dispatches `acceptCookieLaw` with `{ accepted: "yes" | "no" }`.

### Custom element

`hb-cookie-law-banner`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `allowdecline` | union (optional) | `"yes"` \| `"no"` — show decline action. |
| `i18nlang` | string (optional) | Language key (e.g. `en`, `it`). |
| `capabilities` | object (optional) | JSON `ICapabilities`: cookie groups and items with scopes, mandatory flags, etc. |
| `cookielawuri4more` | string (optional) | “Learn more” URL. |

**Slots:** `title`, `text`. **i18n:** Italian and English in metadata.

### Events (`CustomEvent` names)

- **`acceptCookieLaw`** — `{ accepted: "yes" | "no" }`

### Usage notes

- Uses Bootstrap alert styling patterns.
- Fullscreen layout size hint in metadata for Storybook-style hosts.
- Shadow DOM; override copy via `title` and `text` slots.
- Set `i18nlang` to match declared languages.

### Minimal HTML example

```html
<hb-cookie-law-banner
  allowdecline="yes"
  i18nlang="en"
  cookielawuri4more="https://example.com/cookies"
></hb-cookie-law-banner>
```

---

<a id="wc-dashboard-card1"></a>

## `hb-dashboard-card1` — dashboard-card1

**Category:** data | **Tags:** data, dashboard

### What it does

Bulma card shell for dashboards: JSON `header` supplies optional Bootstrap Icon name, title label, and right-aligned tag; JSON `body` can remove inner padding with `noborder`. Slots let you inject markup (`header_content`, `content`). Bootstrap Icons are loaded from the CDN in `svelte:head` for `bi` classes on the optional header icon.

### Custom element

`hb-dashboard-card1`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `header` | object (optional) | JSON `{ icon?: string; label: string; badge?: string }`. |
| `body` | object (optional) | JSON `{ noborder?: boolean }`. |

**Bulma `--bulma-*` theme vars** (see `extra/docs.ts`). **Parts:** `text_placeholder`, `badge`, `card`. **Slots:** `header_content`, `content`.

### Events (`CustomEvent` names)

None declared in types (`Events` is an empty object).

### Styling (Bulma)

The component uses Bulma `card`, `card-header`, `card-header-title`, `card-content`, and `tag`. Theme defaults are applied on `:host` via Bulma’s light theme and `setup-theme`. Override card look with public `--bulma-*` properties (for example `--bulma-card-background-color`, `--bulma-card-shadow`, `--bulma-card-header-color`). Bootstrap Icons remain a separate stylesheet for `header.icon`.

### Usage notes

- `header.icon` should be a bootstrap-icons icon name string (without the `bi-` prefix).
- Use `::part(card)` and related parts for host-level theming inside shadow root.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-dashboard-card1
  header='{"label":"Revenue","icon":"graph-up","badge":"+12%"}'
  body='{"noborder":false}'
></hb-dashboard-card1>
```

---

<a id="wc-dashboard-counter-lines"></a>

## `hb-dashboard-counter-lines` — dashboard-counter-lines

**Category:** data | **Tags:** data, dashboard

### What it does

Vertical list of metric rows from JSON `lines`: each row shows optional Bootstrap Icon, label text, and a Bulma light rounded tag for the counter value. `link.type` chooses behavior—open URI in a new tab, same-window navigation, custom `counterClick` event with a key, or a static row with no click handler.

### Styling (Bulma)

The component bundles **Bulma 1.x** in the shadow root: **`elements/tag`** only, with theme defaults on `:host` (`--bulma-hb-def-*`). Set public **`--bulma-*`** on `body` or `:root` so they inherit onto the host. Icons remain **Bootstrap Icons** (loaded via `<svelte:head>`); use icon names in the `icon` field. See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).

**Shadow markup (simplified):**

- **`div.item`** — row; optional click for `tab` / `page` / `event` links.
- **`div.item_content`** / **`div.text`** — label + optional **`i.bi`**.
- **`div.value.tag.is-light.is-rounded`** — counter (exposed as part **`value`**).

### Custom element

`hb-dashboard-counter-lines`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `lines` | array (optional) | JSON `Line[]`: text, value, link?: `{ type: "tab" \| "page" \| "event"; uri: string }`, index?, icon?. |

**Parts:** `item`, `icon`, `text`, `value`. No slots.

### Events (`CustomEvent` names)

- **`counterClick`** — `{ key: string }` — Used when a line’s `link.type` is `"event"` (per docs behavior).

### Usage notes

- Icons use bootstrap-icons names in the `icon` field.
- Rows are dashboard-style metrics, not a navigation menu.
- Shadow DOM exposes granular parts per row segment.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-dashboard-counter-lines
  lines='[{"text":"Active users","value":"1.2k","icon":"people"},{"text":"Errors","value":"3","icon":"exclamation-triangle"}]'
></hb-dashboard-counter-lines>
```

---

<a id="wc-dashboard-indicator"></a>

## `hb-dashboard-indicator` — dashboard-indicator

**Category:** data | **Tags:** data, dashboard

### What it does

Compact KPI tile: large `number`, caption `text`, configurable Bootstrap Icon, and `karma` accent from Bulma semantic colors. When `link_label` is set, a footer strip is shown and clicks dispatch `dashboardIndicatorClick` with the component `id`.

### Custom element

`hb-dashboard-indicator`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier (used in click payload). |
| `style` | string (optional) | Inline style string. |
| `number` | number (required) | Main KPI value. |
| `text` | string (optional) | Caption under the number. |
| `icon` | string (required) | Bootstrap Icons name. |
| `link_label` | string (optional) | If set, shows footer and enables click dispatch. |
| `karma` | string (optional) | Accent: Bulma semantics `success`, `danger`, `warning`, `primary`, `secondary`, `info` (`secondary` uses Bulma’s `dark` palette), or `none` to use the host CSS variable below. Default `success`. |

**CSS var (with `karma="none"`):** `--hb--dashboard-indicator-background` — header background and footer accent (any valid CSS color). If omitted while `karma` is `none`, falls back to Bulma `success`. With any other `karma`, this variable is ignored. No slots or parts in metadata.

### Events (`CustomEvent` names)

- **`dashboardIndicatorClick`** — `{ id: string }`

### Usage notes

- With Bulma `karma` values, accent comes from `--bulma-*` tokens on `:host`. With `karma="none"`, set `--hb--dashboard-indicator-background` on `hb-dashboard-indicator` (e.g. `style="--hb--dashboard-indicator-background: #6366f1"`).
- Icon name must match bootstrap-icons.
- Shadow DOM wraps the tile; pass `id` when using click events.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-dashboard-indicator
  id="kpi-sales"
  number="128"
  text="Orders today"
  icon="cart-check"
  link_label="View details"
  karma="success"
></hb-dashboard-indicator>
```

### Custom color (`karma="none"`)

```html
<hb-dashboard-indicator
  karma="none"
  style="--hb--dashboard-indicator-background: #6366f1"
  number="12"
  text="Custom"
  icon="stars"
></hb-dashboard-indicator>
```

---

<a id="wc-dialog"></a>

## `hb-dialog` — dialog

**Category:** overlays | **Tags:** overlays, modal

### What it does

**Bulma**-styled modal controlled by string `show` (`yes`/`no`): optional backdrop click to close, Escape when `keyboard` is enabled, and `modal-open` on `document.body`. Slots replace title, body, footer, and button labels; default footer emits `modalConfirm` with `{ id, confirm }` and toggles visibility. Also emits `modalShow` when opened or closed.

### Custom element

`hb-dialog`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier (included in events). |
| `style` | string (optional) | Inline style string. |
| `show` | union (optional) | `"yes"` \| `"no"` — visibility. |
| `confirm_btn_class` | string (optional) | Bulma button color name for confirm (default `primary` → `is-primary`). |
| `title` | string (optional) | Default title text if slot unused. |
| `backdrop` | boolean (optional) | Show backdrop. |
| `ignoreBackdrop` | boolean (optional) | Ignore backdrop interactions when true. |
| `keyboard` | boolean (optional) | Escape to close. |
| `describedby` | string (optional) | ARIA describedby id. |
| `labelledby` | string (optional) | ARIA labelledby id. |
| `content` | string (optional) | Default body string if slot unused. |
| `closelabel` | string (optional) | Close button label. |
| `confirmlabel` | string (optional) | Confirm button label. |
| `disable_confirm` | boolean (optional) | Disable confirm button. |
| `close_btn_class` | string (optional) | Bulma button color name for close (default `secondary` → `is-light` / mapped modifier). |
| `hide_close` | boolean (optional) | Hide close control. |
| `hide_confirm` | boolean (optional) | Hide confirm control. |

**CSS vars:** Bulma `--bulma-*`, `--hb-modal-max-width`; the host sets compact defaults for `--bulma-modal-card-head-padding`, `--bulma-modal-card-body-padding`, `--bulma-modal-card-title-size`, `--bulma-modal-card-title-line-height`, and `--bulma-modal-card-spacing` (override on the element or an ancestor to taste). **Part:** `modal-dialog`. **Slots:** `header`, `modal-footer`, `body-content`, `footer`, `close-button-label`, `confirm-button-label`.

### Events (`CustomEvent` names)

- **`modalConfirm`** — `{ id: string; confirm: boolean }`
- **`modalShow`** — `{ id: string; show: boolean }`

### Usage notes

- Modal behavior (body scroll lock, backdrop) matches typical overlay patterns.
- Optional icons depend on implementation; load Bootstrap Icons if you add `bi-*` markup.
- Teleports/focus live in shadow DOM; test accessibility with real browsers.
- No i18n array in `docs.ts`.

### Minimal HTML example

```html
<hb-dialog
  id="confirm-delete"
  show="yes"
  title="Delete item?"
  content="This cannot be undone."
  confirmlabel="Delete"
  closelabel="Cancel"
  keyboard="true"
></hb-dialog>
```

---

<a id="wc-dialog-loader"></a>

## `hb-dialog-loader` — dialog-loader

**Category:** overlays | **Tags:** overlays, modal, loading

### What it does

Thin wrapper around `hb-dialog` that opens automatically while numeric `percentage` is non-zero and shows a **Bulma** `<progress class="progress">` filled to that value. Forwards `modalShow` from the inner dialog; slots allow overriding the dialog title.

### Custom element

`hb-dialog-loader`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `title` | string (optional) | Dialog title text. |
| `percentage` | number (required) | 0 hides/closes behavior; non-zero shows progress (per description). |

**Bulma `--bulma-*` vars** (see `extra/docs.ts`). **Slot:** `title`. No parts in metadata.

### Events (`CustomEvent` names)

- **`modalShow`** — `{ id: string; show: boolean }` — Forwarded from inner `hb-dialog`.

### Usage notes

- Progress UI uses Bulma `elements/progress` (`is-primary`); percentage is shown below the bar.
- Parent should drive `percentage` from async task state.
- Nested `hb-dialog` means the same overlay constraints as `hb-dialog`.
- No i18n in `docs.ts`.

### Minimal HTML example

```html
<hb-dialog-loader title="Uploading…" percentage="45"></hb-dialog-loader>
```

---

<a id="wc-dialogform"></a>

## `hb-dialogform` — dialogform

**Category:** forms | **Tags:** forms, overlays

### What it does

Modal that embeds `hb-form` with the same `schema` contract: live form updates mirror validity and values via `updateForm`, and the confirm button dispatches `modalFormConfirm` with the last valid payload or `modalFormCancel` when dismissed or invalid. Composes `hb-dialog` (Bulma modal, backdrop/keyboard, `show`) and re-dispatches `modalShow`.

### Custom element

`hb-dialogform`

### Attributes / props (snake_case)

| Property | Type | Notes |
| --- | --- | --- |
| `id` | string (optional) | Element identifier. |
| `style` | string (optional) | Inline style string. |
| `show` | union (optional) | `"yes"` \| `"no"`. |
| `dialogclasses` | string (optional) | Reserved on the type; not yet applied in the template. |
| `title` | string (optional) | Modal title. |
| `backdrop` | boolean (optional) | Backdrop toggle. |
| `keyboard` | boolean (optional) | Escape closes when true. |
| `describedby` | string (optional) | ARIA describedby. |
| `labelledby` | string (optional) | ARIA labelledby. |
| `content` | string (optional) | Supplemental content string. |
| `closelabel` | string (optional) | Close button label. |
| `confirmlabel` | string (optional) | Confirm button label. |
| `schema` | array (required) | JSON form schema (same shape as `hb-form` `schema`). |

**Bulma / theme:** CSS variables follow `hb-dialog` and `hb-form` (see those components). **Slots:** `form-header`, `form-footer`, `header`, `modal-footer`, `footer`, `close-button-label`, `confirm-button-label`.

### Events (`CustomEvent` names)

- **`modalFormConfirm`** — `{ [key: string]: any }` — Submitted field map / payload (types use open object).
- **`modalShow`** — `{ id: string; show: boolean }`
- **`modalFormCancel`** — `{ id: string; error?: string }`
- **`updateForm`** — same detail shape as `hb-form` `update` (see form event types).

### Usage notes

- Built on Bulma modal + form patterns shared with `hb-dialog` and `hb-form`.
- `schema` is typically a JSON string in HTML; validate against `hb-form` field types.
- Shadow DOM composes nested components; slots map to form and modal regions.
- No i18n array in `docs.ts` for this component.

### Minimal HTML example

```html
<hb-dialogform
  show="yes"
  title="Edit profile"
  schema='[{"type":"text","id":"name","label":"Name","required":true,"value":""}]'
  confirmlabel="Save"
  closelabel="Cancel"
></hb-dialogform>
```

---

<a id="wc-downloader"></a>

## `hb-downloader` — downloader

**Category:** utilities  
**Tags:** utilities, files

### What it does

Opens `hb-dialog` while `uri` is set and downloads the resource with `XMLHttpRequest` as a blob: optional JSON `headers`, inferred or explicit `targetfilename`, `Content-Disposition` parsing when exposed by CORS, **Bulma** `<progress>` from `onprogress`, then triggers a browser file save. Dispatches `downloadComplete` or `downloadError` (with `downloadid`) and propagates `modalShow`; clears/aborts when the dialog closes.

### Custom element

`hb-downloader`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `uri` — required string (resource URL)  
- `downloadid` — optional string (correlates emitted events)  
- `headers` — optional string (JSON object of request headers)  
- `targetfilename` — optional string (suggested download filename)

### Events

- `downloadError` — `{ downloaded: boolean; id: string; error: Error }`  
- `downloadComplete` — `{ downloaded: boolean; id: string }`  
- `modalShow` — `{ id: string; show: boolean }`

### Usage notes

Pass complex objects (`headers`) as JSON strings on attributes. Requires CORS and appropriate headers for progress and filename hints. Slot: `title` (dialog title). Progress styling uses Bulma `elements/progress` (`is-primary`); indeterminate bar while total length is unknown.

### Minimal HTML example

```html
<hb-downloader
  uri="https://example.com/file.pdf"
  targetfilename="document.pdf"
  headers="{&quot;Authorization&quot;:&quot;Bearer token&quot;}"
></hb-downloader>
```

---

<a id="wc-dropdown-notifications"></a>

## `hb-dropdown-notifications` — dropdown-notifications

**Category:** overlays  
**Tags:** overlays, menu, notifications

### What it does

Bell control that toggles a Bulma `dropdown` (active state): header row with optional “Clear all” (`clearurl`), default slot for notification rows (`dropdown-item` rows work well), and optional footer link “View all” (`viewurl`). Set `align` to `"right"` for `is-right` menu alignment.

### Custom element

`hb-dropdown-notifications`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `clearurl` — string (URL for clear-all; empty disables)  
- `viewurl` — string (URL for view-all; empty disables)  
- `align` — `"left"` | `"right"`

### Events

None declared on the component type.

### Usage notes

Slot: `title` (dropdown header). Default slot holds notification row content.

### Minimal HTML example

```html
<hb-dropdown-notifications
  clearurl=""
  viewurl="/notifications"
  align="right"
>
  <span slot="title">Notifications</span>
  <div class="dropdown-item">Sample notification</div>
</hb-dropdown-notifications>
```

---

<a id="wc-dropdown-simple"></a>

## `hb-dropdown-simple` — dropdown-simple

**Category:** overlays  
**Tags:** overlays, menu

### What it does

Bootstrap dropdown menu: `list` is a JSON array of items with `key` (and labels per your schema). Toggle open state with the trigger; choosing an item emits `dropDownClick` with the item `key` and closes the menu. `open` accepts boolean or string (`yes`/`no`); `position` aligns the menu left or right (defaults from host `float: right` when unset). Emits `dropdownSwitch` when toggled.

### Custom element

`hb-dropdown-simple`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string (e.g. `float: right` influences default `position`)  
- `list` — string (JSON array of `{ key, label, … }`; optional `linkHref`, `badge`, `group`)  
- `open` — optional boolean or `"yes"` / `"no"`  
- `position` — optional `"left"` | `"right"`

### Events

- `dropdownSwitch` — `{ open: boolean; id: string }`  
- `dropDownClick` — `{ key: string }`

### Usage notes

CSS parts: `dropdown`, `dropdownbutton`, `dropdowncontent`.

### Minimal HTML example

```html
<hb-dropdown-simple
  list="[{&quot;key&quot;:&quot;a&quot;,&quot;label&quot;:&quot;Option A&quot;},{&quot;key&quot;:&quot;b&quot;,&quot;label&quot;:&quot;Option B&quot;}]"
  position="left"
></hb-dropdown-simple>
```

---

<a id="wc-editor-video"></a>

## `hb-editor-video` — editor-video

**Category:** media  
**Tags:** media, video, editor

### What it does

Video trimmer UI: plays `src` with an `hb-range-slider` synced to the playhead and in/out bounds (`track` min/max seconds). Numeric time fields, cue-to-current-time buttons, and optional `hb-form` gate final submission. Emits `changeTrackValues`, `dispatchTrack` when no form is used, and form-driven submit when metadata is valid. The UI uses **Bulma** `card`, `image is-16by9`, `button`, and `input` controls (Bootstrap Icons for play/pause).

### Custom element

`hb-editor-video`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `src` — required string (video URL)  
- `form` — optional string (JSON / schema for embedded `hb-form` when gating submit)  
- `track` — optional string (JSON `{ minValue, maxValue }` in seconds)

### Events

- `changeTrackValues` — `{ minVaule: number; maxValue: number }` (note: first key is spelled `minVaule` in the implementation)  
- `dispatchTrack` — `ITrack` or track merged with form submit payload when `form` is set

### Usage notes

Registers `hb-range-slider` and `hb-form`. Without `form`, use `dispatchTrack` for the trimmed range; with `form`, submission dispatches `dispatchTrack` including validated form fields.

### Minimal HTML example

```html
<hb-editor-video
  src="https://example.com/video.mp4"
  track="{&quot;minValue&quot;:0,&quot;maxValue&quot;:120}"
></hb-editor-video>
```

---

<a id="wc-faq-component"></a>

## `hb-faq-component` — faq-component

**Category:** content  
**Tags:** content

### What it does

FAQ layout with a horizontal topic strip (Bootstrap Icons + labels) that sets an optional `filter` key, and an accordion list built from JSON `info` entries (`title`, `topic`, HTML `text`). Checkbox hack expands/collapses answers; topics with `catchAll` clear the filter.

### Custom element

`hb-faq-component`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `info` — optional string (JSON array of `{ topic?, title, text }`; `text` may contain HTML)  
- `topics` — optional string (JSON array of `{ key, label, icon, catchAll?, index? }`)  
- `filter` — optional string (active topic key)

### Events

None declared on the component type.

### Usage notes

Drive content via `info` and `topics` as JSON strings. Icon names use Bootstrap Icons.

### Minimal HTML example

```html
<hb-faq-component
  topics="[{&quot;key&quot;:&quot;general&quot;,&quot;label&quot;:&quot;General&quot;,&quot;icon&quot;:&quot;question-circle&quot;}]"
  info="[{&quot;topic&quot;:&quot;general&quot;,&quot;title&quot;:&quot;First question&quot;,&quot;text&quot;:&quot;&lt;p&gt;Answer here.&lt;/p&gt;&quot;}]"
></hb-faq-component>
```

---

<a id="wc-footer"></a>

## `hb-footer` — footer

**Category:** layout  
**Tags:** layout, navigation

### What it does

Site footer in `small`, `regular`, or `large` layouts: company block, optional brand/contacts column, link columns, social icons, `hb-contact-item` rows, and policy links—all driven by JSON props. **Bulma** `container`, `columns` / `column`, `title`, and `button` style the regular layout; equal-width sections use a shared CSS variable for column flex-basis. On small layouts the body can expand/collapse unless `disable_expanding_small` is set; slots `footerheader`, `footercontent`, and `footerbottom` wrap major regions.

### Custom element

`hb-footer`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `company` — required string (JSON: logo, names, description, VAT, etc.)  
- `brandandcontacts` — optional string (JSON)  
- `columns` — optional string (JSON array of titled link columns / cells)  
- `policies` — optional string (JSON array of `{ label, key, link? }`)  
- `contacts` — optional string (JSON: phones, addresses, emails, sites)  
- `socials` — optional string (JSON: facebook, youtube, …)  
- `type` — optional `"small"` | `"regular"` | `"large"`  
- `disable_expanding_small` — optional boolean (string in HTML)

### Events

- `footerClick` — `{ elClick: string }`

### Usage notes

Slots: `footerpolicy`, `footerheader`, `footercontent`, `footerbottom`, `footer_small`. CSS part: `column-cell-button-content`. Layout size metadata in docs: `fullscreen`.

### Minimal HTML example

```html
<hb-footer
  type="regular"
  company="{&quot;logoUri&quot;:&quot;https://example.com/logo.svg&quot;,&quot;siteName&quot;:&quot;Site&quot;,&quot;companyName&quot;:&quot;ACME&quot;,&quot;description&quot;:&quot;Tagline&quot;}"
  columns="[]"
  policies="[]"
></hb-footer>
```

---

<a id="wc-form"></a>

## `hb-form` — form

**Category:** forms  
**Tags:** forms

### What it does

JSON `schema`-driven form engine: each entry’s `type` maps to an `hb-input-*` web component (text, select, date, file, arrays, coords, etc.) or layout `row`. Handles grouping, conditional visibility, validation messages, disabled state, and dispatches rich `update` payloads (field values + `_valid`) plus submit lifecycle events for programmatic backends.

### Custom element

`hb-form`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schema` — required string (JSON array of field definitions: `type`, `id`, `label`, `value`, `required`, `params`, `dependencies`, etc.)  
- `submitted` — optional `"yes"` | `"no"` | null  
- `getvals` — optional `"yes"` | `"no"` | null (trigger read values)  
- `show_validation` — optional `"yes"` | `"no"`  
- `hide_submit` — optional boolean  
- `i18nlang` — optional string (`en`, `it`, …)

### Events

- `submit` — submitted values as `Record<string, …>` plus `_valid`, `_id`  
- `submitinvalid` — fired when a submit is attempted (including `submitted="yes"`) but the form fails validation; `show_validation` is turned on so errors are visible  
- `getValues` — `{ _valid: boolean; values: Record<string, …> }`  
- `update` — `{ _valid: boolean; _id: string; values: Record<string, …> }`

### Usage notes

`schema` is the primary API; pass it as a single JSON string on the element. Slots: `submit_button`, `submit_label`, `other_buttons`. Supports i18n via `i18nlang`.

### Minimal HTML example

```html
<hb-form
  schema="[{&quot;type&quot;:&quot;text&quot;,&quot;id&quot;:&quot;name&quot;,&quot;label&quot;:&quot;Name&quot;,&quot;required&quot;:true}]"
  show_validation="no"
  submitted="no"
></hb-form>
```

---

<a id="wc-form-composer"></a>

## `hb-form-composer` — form-composer

**Category:** forms  
**Tags:** forms, builder

### What it does

Visual form-schema builder: internal `hb-form` defines field types, validation flags, and options, mirrored into an `hb-table` preview and editable via `hb-dialogform`. Accumulates `output_schema` as the composed `hb-form` schema array and emits `done` when the schema is finalized (e.g. via the UI save action).

### Custom element

`hb-form-composer`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `debug` — optional boolean (string in HTML)  
- `output_schema` — optional string (JSON array of generator field descriptors; seed or inspect composed schema)

### Events

- `done` — `{ schema: any; id: string }`

### Usage notes

Uses nested `hb-form`, `hb-table`, and `hb-dialogform`. `output_schema` mirrors the live composed schema suitable for `hb-form`. The table slot “done” control uses a Bulma outline button from `styles/bulma.scss`.

### Minimal HTML example

```html
<hb-form-composer debug="no"></hb-form-composer>
```

---

<a id="wc-form-contact"></a>

## `hb-form-contact` — form-contact

**Category:** forms  
**Tags:** forms, contact

### What it does

Opinionated contact form: JSON `informations` toggles and labels fields (name, email, phone, subject, message, etc.) and builds the `hb-form` schema at runtime, including privacy-policy checkbox from `privacy_policy`. Optional `captcha` config embeds `hb-captcha-google-recaptcha-v2-invisible` before submit; success UI uses Svelte transitions.

### Custom element

`hb-form-contact`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `informations` — optional string (JSON: which fields exist and their `required`, `label`, `placeholder`, `value`)  
- `privacy_policy` — optional string (JSON: `input`, `link?`, `policyId?`, `required?`)  
- `captcha` — optional string (JSON: `type` `googlev_recaptchav2_invisible` | `googlev_recaptchav3`, `siteKey`)

### Events

- `formContactSubmit` — `{ _valid: boolean; values: Record<string, string | number | boolean> }`  
- `formContactSubmitWithCaptcha` — same as above plus `response: string`

### Usage notes

CSS part: `container`. Bootstrap theme variables apply via component styles.

### Minimal HTML example

```html
<hb-form-contact
  informations="{&quot;email&quot;:{&quot;required&quot;:true},&quot;message&quot;:{}}"
  privacy_policy="{&quot;input&quot;:&quot;I agree&quot;,&quot;required&quot;:true}"
></hb-form-contact>
```

---

<a id="wc-funnel"></a>

## `hb-funnel` — funnel

**Category:** forms  
**Tags:** forms, multistep

### What it does

Multi-step funnel over stacked `hb-form` instances: JSON `schemes` supplies one schema per step (or derive step count from `steps`), tracks per-step validity, merges values as the user advances, and optionally shows a final submit step when `submitstep` is `yes`. Dispatches step navigation and aggregated form updates for the active index.

### Custom element

`hb-funnel`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemes` — required string (JSON array of `hb-form`-compatible schemas, one per step)  
- `steps` — optional number (string in HTML)  
- `step` — optional number (current step index; string in HTML)  
- `submitstep` — optional `"yes"` | `"no"` (final submit step)

### Events

- `update` — `{ step: number; scheme: { schema; valid }; valid: boolean }`  
- `submit` — `{ schemes: { schema; valid }[]; steps: number; step: number }`

### Usage notes

Each entry in `schemes` is a full form schema array like `hb-form`’s `schema`. CSS part: `invalid-feedback` (from inner form styling).

**Next / Save:** the outer buttons set `submitted="yes"` on the inner `hb-form`. The funnel advances (or emits `submit` on the last step) only after that form dispatches `submit` with a valid payload. If validation fails, the inner form emits `submitinvalid`, turns on field validation UI, and the step does not change.

The inner form’s `schema` attribute is refreshed when schemes are first loaded or when the step index changes. `field.value` entries in the funnel’s copy of the schema are updated when you leave a step with a **valid** submit (Avanti / Salva), not on each debounced `update`, so the DOM is not forced to re-sync on every keystroke.

### Minimal HTML example

```html
<hb-funnel
  submitstep="yes"
  schemes="[[{&quot;type&quot;:&quot;text&quot;,&quot;id&quot;:&quot;name&quot;,&quot;label&quot;:&quot;Name&quot;,&quot;required&quot;:true}]]"
></hb-funnel>
```

---

<a id="wc-gallery-video"></a>

## `hb-gallery-video` — gallery-video

**Category:** media  
**Tags:** media, video, gallery

### What it does

Paginated grid of `hb-card-video` tiles built from JSON `cards`, with `hb-paginate` for page/size and optional text or date-range filtering (`initialdate`/`lastdate`, `filter`, `externalfilter`). Passes date format, link label, and primary color into each card; listens to paginator events to sync `page`/`pages` and emits host events for paging and filters.

### Custom element

`hb-gallery-video`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `cards` — required string (JSON array: `videoSrc`, `title?`, `time?`, `provider?`, `dateformat?`, …)  
- `size` — optional number (items per page; string in HTML)  
- `page` — optional number (0-based; string in HTML)  
- `pages` — optional number (total pages when using external filter; string in HTML)  
- `link_label` — optional string  
- `dateformat` — optional string (day.js format)  
- `primarycolor` — optional string  
- `filter` — optional string (text filter)  
- `externalfilter` — optional string (truthy enables external pagination/filter behavior)  
- `disabletextfilter` — optional `"yes"` to disable text filter UI  
- `initialdate` — optional (ISO/date string when passed from host)  
- `lastdate` — optional (ISO/date string when passed from host)

### Events

- `pageChange` — `{ page: number; cards: ICard[] }`  
- `textFilterVideos` — `{ filter?: string }` (when `externalfilter` is set and filter changes)  
- `dateFilterVideos` — `{ start?: Date; end?: Date; dateKey: string }`

### Usage notes

CSS part: `container`. Registers `hb-paginate` and `hb-card-video`. `cards` must be valid JSON on the attribute. Layout and filters use **Bulma** (`container`, `columns`, `field` / `control`, `input`, visibility helpers).

### Minimal HTML example

```html
<hb-gallery-video
  cards="[{&quot;title&quot;:&quot;Clip&quot;,&quot;videoSrc&quot;:&quot;https://example.com/video.mp4&quot;}]"
  size="12"
  page="0"
></hb-gallery-video>
```

---

<a id="wc-gauge"></a>

## `hb-gauge` — gauge

**Category:** data  
**Tags:** data, chart

### What it does

SVG gauge wrapper around JustGage: pass JustGage-compatible options as JSON (`value`, min/max, labels, colors, etc.). The gauge is created on the shadow host after mount, destroyed on teardown, and recreated when `options` changes or the window resizes (debounced) so it stays sized correctly.

### Custom element

`hb-gauge`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `options` — required string (JSON object; at minimum `value`, `min`, `max`; additional keys follow JustGage)

### Events

None declared on the component type.

### Usage notes

CSS part: `gauge`. `options` may be passed as a JSON string; the component parses it when needed.

### Minimal HTML example

```html
<hb-gauge
  options="{&quot;value&quot;:50,&quot;min&quot;:0,&quot;max&quot;:100}"
></hb-gauge>
```

---

<a id="wc-input-area"></a>

## `hb-input-area` — input-area

**Category:** inputs  
**Tags:** inputs

### What it does

Multi-line `<textarea>` with Bulma `textarea` + optional `is-success` / `is-danger` and `help is-danger`. Same `schemaentry` validation as text (`validationRegex`, `params` min/max, required). Theme via `--bulma-*` on `:host`. Dispatches `setVal` and `clickEnter` when Enter is pressed without Shift (Shift+Enter inserts a newline).

### Styling (Bulma)

Bundles **Bulma 1.x** `form/shared`, `form/input-textarea`, and `form/tools` in the shadow root.

### Custom element

`hb-input-area`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `label?`, `placeholder?`, `required?`, `value?`, `validationTip?`, `validationRegex?`, `params?`)  
- `show_validation` — optional `"yes"` | `"no"`

### Events

- `setVal` — `{ value: string; valid: boolean; id: string }`  
- `clickEnter` — `{ value: string; valid: boolean; id?: string }`

### Usage notes

CSS parts: `invalid-feedback`, `input`. Nested `schemaentry` fields follow the shared form-schema shape used by `hb-form`.

### Minimal HTML example

```html
<hb-input-area
  schemaentry="{&quot;id&quot;:&quot;notes&quot;,&quot;label&quot;:&quot;Notes&quot;,&quot;placeholder&quot;:&quot;Type here…&quot;}"
  show_validation="no"
></hb-input-area>
```

---

<a id="wc-input-array-objects"></a>

## `hb-input-array-objects` — input-array-objects

**Category:** inputs  
**Tags:** inputs

### What it does

Repeating records editor: `hb-table` lists existing rows (with delete actions), and `hb-form` renders the next row from `schemaentry.params.schema`; submitting appends to the array and updates the table. Registers `hb-form` and `hb-table`; optional `add-object-label` slot customizes the add button (`button is-info`). Dispatches `setVal` with the objects array, `valid`, and `id`, and shows `validationTip` as Bulma `help is-danger` when `show_validation` is enabled and invalid.

### Styling (Bulma)

Shadow bundle: `form/tools`, `form/shared`, `form/input-textarea`, `elements/button`. Container border uses `--bulma-border` on `:host`.

### Custom element

`hb-input-array-objects`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `params.schema` as nested form schema, optional `value` as row array with `_objId`, `validationTip?`, `required?`, …)  
- `show_validation` — optional `"yes"` | `"no"`

### Events

- `setVal` — `{ value: string; valid: boolean; id: string }` (payload `value` is the serialized array/object representation used by the component)

### Usage notes

CSS parts: `properties-container`, `invalid-feedback`. Slot: `add-object-label`.

### Minimal HTML example

```html
<hb-input-array-objects
  schemaentry="{&quot;id&quot;:&quot;people&quot;,&quot;params&quot;:{&quot;schema&quot;:[{&quot;type&quot;:&quot;text&quot;,&quot;id&quot;:&quot;name&quot;,&quot;label&quot;:&quot;Name&quot;}]}}"
  show_validation="no"
></hb-input-array-objects>
```

---

<a id="wc-input-array-tags"></a>

## `hb-input-array-tags` — input-array-tags

**Category:** inputs  
**Tags:** inputs

### What it does

Tag list stored as objects `{ id, label }` (optional per-tag `colorVarName`); users add tags via free text or a dropdown from `params.availableTags`, with optional `freeTag` and `_custom` flow, removable Bulma `tag` + `delete` controls when `allowRemove` is set, and styling via `params.colorVarName` or the `add-tag-label` slot. Dispatches `setVal` with the array `value`, `valid`, and `id`.

### Styling (Bulma)

Shadow bundle: `form` inputs/select/tools, `elements/tag`, `elements/delete`, `elements/button`. Tags use Bulma `tags` / `tag`; add control uses `button.tag` or styled `tag`.

### Custom element

`hb-input-array-tags`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `params` with `availableTags?`, `freeTag?`, `allowRemove?`, `colorVarName?`, `addTagLabel?`, optional `value` as tag array)  
- `show_validation` — optional `"yes"` | `"no"`

### Events

- `setVal` — `{ value: string; valid: boolean; id: string }` (tag list is serialized for the custom event payload)

### Usage notes

Optional slot: `add-tag-label` for the add control label. CSS part: `invalid-feedback`.

### Minimal HTML example

```html
<hb-input-array-tags
  schemaentry="{&quot;id&quot;:&quot;tags&quot;,&quot;params&quot;:{&quot;freeTag&quot;:true,&quot;allowRemove&quot;:true}}"
  show_validation="no"
></hb-input-array-tags>
```

---

<a id="wc-input-checkbox"></a>

## `hb-input-checkbox` — input-checkbox

**Category:** inputs  
**Tags:** inputs

### What it does

Checkbox or, when `schemaentry.params.type` is `switch`, a switch styled in the shadow tree (Bulma colors on `:host`), labeled from `schemaentry.label` with a required asterisk when needed. Boolean `value` is parsed from stringified `schemaentry`; required fields must be checked to be valid. Dispatches `setVal` with `{ value, valid, id }` and shows `validationTip` as Bulma `help is-danger` when `show_validation` is `yes` and invalid.

### Styling (Bulma)

Shadow bundle: `form/shared`, `form/input-textarea`, `form/checkbox-radio`, `form/tools`. Switch uses host SCSS (`hb-input-checkbox-switch`).

### Custom element

`hb-input-checkbox`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `label?`, `required?`, `value?`, `validationTip?`, `params.type` optional `"switch"`, …)  
- `show_validation` — optional `"yes"` | `"no"`

### Events

- `setVal` — `{ value: boolean; valid: boolean; id: string }`

### Usage notes

CSS parts: `input`, `invalid-feedback`.

### Minimal HTML example

```html
<hb-input-checkbox
  schemaentry="{&quot;id&quot;:&quot;accept&quot;,&quot;label&quot;:&quot;I agree&quot;,&quot;required&quot;:true}"
  show_validation="no"
></hb-input-checkbox>
```

---

<a id="wc-input-color"></a>

## `hb-input-color` — input-color

**Category:** inputs  
**Tags:** inputs

### What it does

Color input that normalizes named HTML colors and `rgb(...)` strings into a hex value for the native picker, with debounced syncing back to the bound value. Driven by `schemaentry` (including required and optional `validationTip` with `show_validation`). Dispatches `setVal` with the string `value`, `valid`, and `id`.

### Styling (Bulma)

Shadow bundle: `form/shared`, `form/input-textarea`, `form/tools`. The native `type="color"` control uses host SCSS (border / outline with `--bulma-*`). Validation uses `help is-danger`. Theme variables on `:host`.

### Custom element

`hb-input-color`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `label?`, `required?`, `value?`, `validationTip?`, `placeholder?`, …)  
- `show_validation` — optional `"yes"` | `"no"`

### Events

- `setVal` — `{ value: string; valid: boolean; id: string }`

### Usage notes

CSS parts: `input`, `invalid-feedback`.

### Minimal HTML example

```html
<hb-input-color
  schemaentry="{&quot;id&quot;:&quot;accent&quot;,&quot;required&quot;:true,&quot;value&quot;:&quot;#07689f&quot;}"
  show_validation="no"
></hb-input-color>
```

---

<a id="wc-input-coords"></a>

## `hb-input-coords` — input-coords

**Category:** inputs  
**Tags:** inputs, maps

### What it does

Latitude/longitude editor that embeds `hb-map` (marker and map `source` / `options` from `schemaentry.params`) and two `hb-input-number` fields, with labels translated via optional `i18nlang`. Supports initial `value` and `params` such as `zoom` and `center`. Registers `hb-map` and `hb-input-number` and dispatches `setVal` with `{ lat, lon }` as `value`, plus `valid` and `id`. Layout uses flex columns in the shadow root; validation uses Bulma `help is-danger`. Required validation treats `(0, 0)` as unset (same as the previous `lat && lon` check).

### Styling (Bulma)

Shadow bundle: `form/shared`, `form/input-textarea`, `form/tools`. Map and number fields keep their own styles.

### Custom element

`hb-input-coords`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `label?`, `required?`, `value` as `{ lat, lon }`, `validationTip?`, `params` for map/zoom/center/labels/placeholders)  
- `show_validation` — optional `"yes"` | `"no"`  
- `i18nlang` — optional string

### Events

- `setVal` — `{ value: { lat: number; lon: number }; valid: boolean; id: string }`

### Usage notes

CSS part: `invalid-feedback`. Ensure map-related `params` match your deployment (tiles/source).

### Minimal HTML example

```html
<hb-input-coords
  schemaentry="{&quot;id&quot;:&quot;loc&quot;,&quot;required&quot;:true,&quot;value&quot;:{&quot;lat&quot;:45.4,&quot;lon&quot;:9.2}}"
  show_validation="no"
></hb-input-coords>
```

---

<a id="wc-input-date"></a>

## `hb-input-date` — input-date

**Category:** inputs  
**Tags:** inputs

### What it does

Native `type="date"` with Bulma `input` + `is-success` / `is-danger`, native `min`/`max` from `params` when valid dates, and `help is-danger` for tips. `schemaentry` as JSON string or object. Theme `--bulma-*` on `:host`. Dispatches `setVal` and `clickEnter`.

### Styling (Bulma)

Shadow bundle: `form/shared`, `form/input-textarea`, `form/tools`.

### Custom element

`hb-input-date`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `label?`, `required?`, `value?` as ISO date string, `validationTip?`, `params.min` / `params.max` as ISO strings, …)  
- `show_validation` — optional `"yes"` | `"no"`

### Events

- `setVal` — `{ value: string; valid: boolean; id: string }`  
- `clickEnter` — `{ value: string; valid: boolean; id?: string }`

### Usage notes

CSS part: `invalid-feedback`.

### Minimal HTML example

```html
<hb-input-date
  schemaentry="{&quot;id&quot;:&quot;birth&quot;,&quot;label&quot;:&quot;Birth date&quot;,&quot;required&quot;:true}"
  show_validation="no"
></hb-input-date>
```

---

<a id="wc-input-datetime"></a>

## `hb-input-datetime` — input-datetime

**Category:** inputs  
**Tags:** inputs

### What it does

Composes `hb-input-date` and `hb-input-number` to edit date, hours, minutes, and (unless `params.removeSeconds`) seconds, then combines them into a single ISO string `value`. Honors `schemaentry.params.min` / `max` as date bounds when required. Registers `hb-input-date` and `hb-input-number` and dispatches `setVal` with `{ value, valid, id }`.

### Styling (Bulma)

Shadow bundle: `form/shared`, `form/input-textarea`, `form/tools`. Layout uses Bulma `field is-grouped` / `control`; invalid state uses `help is-danger` and a host outline. Child WCs ship their own input styles. Theme `--bulma-*` on `:host`.

### Custom element

`hb-input-datetime`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `label?`, `required?`, `value?` as ISO datetime string, `validationTip?`, `params.removeSeconds?`, `params.min` / `params.max`, …)  
- `show_validation` — optional `"yes"` | `"no"`

### Events

- `setVal` — `{ value: string; valid: boolean; id: string }`

### Usage notes

CSS part: `invalid-feedback` on the validation message. Child inputs carry their own parts. Child components must be registered in the bundle.

### Minimal HTML example

```html
<hb-input-datetime
  schemaentry="{&quot;id&quot;:&quot;starts_at&quot;,&quot;label&quot;:&quot;Start&quot;,&quot;required&quot;:true,&quot;params&quot;:{&quot;removeSeconds&quot;:true}}"
  show_validation="no"
></hb-input-datetime>
```

---

<a id="wc-input-email"></a>

# hb-input-email

## Description

`type="email"` field using `schemaentry` for id, value, placeholder, readonly, and required, with extra checks for a sensible address shape plus optional `validationRegex` and `params` min/max length. Bulma `input` + `is-success` / `is-danger` and `help is-danger` with `show_validation`. Theme via `--bulma-*` on `:host`. Dispatches `setVal` and `clickEnter` on Enter.

## Styling (Bulma)

Bundles **Bulma 1.x** `form/shared`, `form/input-textarea`, and `form/tools` in the shadow root; theme on `:host`.

## Types

```typescript
export type FormSchemaEntry = {
  /**
   * This will be both the key of the object when submitting the form's data,
   * and also the id in the DOM.
   */
  id: string;

  /**
   * The descriptive label that will show alongside the form control.
   */
  label?: string;

  /**
   * Optional default value.
   */
  value?: string | number | boolean;

  readonly?: boolean;

  /**
   * This doesn't matter if the dependencies requirements aren't met.
   */
  required?: boolean;

  validationRegex?: string;
  /**
   * Shows if value is not valid.
   */
  validationTip?: string;

  placeholder?: string;

  /**
   * Other parameters that may be specific to a certain kind of form control.
   */
  params?: Record<string, any>;
};

export type Component = {
  id?: string;
  style?: string;

  show_validation?: "yes" | "no";
  schemaentry: FormSchemaEntry;
};

export type Events = {
  setVal: { value: string; valid: boolean; id: string };
  clickEnter: { value: string; valid: boolean; id?: string };
};
```

---

<a id="wc-input-file"></a>

# hb-input-file

## Description

File picker with `accept` from `schemaentry.params.accept` (defaults to any file). **Standard mode** uses Bulma `file has-name`: CTA → **clear** (`×`) → filename strip (MIME icon + name) as one continuous control inside the same `file-label`. The clear button uses `preventDefault` / `stopPropagation` so it does not open the file dialog. **Placeholder image mode** (`params.placeHolderImage`) keeps the clickable image + translated “select image” copy and, after selection, preview (or MIME icon), filename, and clear. Set **`i18nlang`** (e.g. `en`, `it`) for UI strings; `hb-form` forwards its `i18nlang` to this control. Validates required fields against an actual chosen file. Dispatches `setVal` with `{ value, valid, id }`.

## Styling (Bulma)

Shadow bundle: `form/shared`, `form/input-textarea`, `form/file`, `form/tools`, `elements/button`. Bootstrap Icons CSS is `@import`ed from `styles/webcomponent.scss` so glyph rules and `@font-face` apply inside the shadow root (document-level `<link>` / `<svelte:head>` would not).

## Types

```typescript
export type FormSchemaEntry = {
	/**
	 * This will be both the key of the object when submitting the form's data,
	 * and also the id in the DOM.
	 */
	id: string;

	/**
	 * The descriptive label that will show alongside the form control.
	 */
	label?: string;

	/**
	 * Optional default value.
	 */
	value?: string | number | boolean;

	readonly?: boolean;

	/**
	 * This doesn't matter if the dependencies requirements aren't met.
	 */
	required?: boolean;

	validationRegex?: string;
	/**
	 * Shows if value is not valid.
	 */
	validationTip?: string;

	placeholder?: string;

	/**
	 * Other parameters that may be specific to a certain kind of form control.
	 */
	params?: Record<string, any>;
};

export type Component = {
	id?: string;
	style?: string;

	show_validation?: "yes" | "no";
	schemaentry: FormSchemaEntry;
	i18nlang?: string;
};

export type Events = { setVal: { value: string; valid: boolean; id: string } };
```

---

<a id="wc-input-number"></a>

# hb-input-number

## Description

Native `<input type="number">` bound to `schemaentry` with optional `min` / `max` from `params` (attributes are set only when the corresponding key exists on `params`). Validates required fields and range; with no `min`/`max` params it dispatches `clickEnter` on Enter. Emits `setVal` with `{ value, valid, id }`. With `show_validation === "yes"` and `required`, the field uses Bulma `input.is-success` / `input.is-danger` and shows `validationTip` as `help is-danger` when invalid. Use `is_small="yes"` for Bulma **`input.is-small`** (compact control, e.g. next to **`hb-paginate`**). On **`type="number"`**, spin buttons are hidden so the control height matches compact selects (values are still editable with the keyboard).

## Styling (Bulma)

The component bundles **Bulma 1.x** form styles (`form/shared`, `form/input-textarea`, `form/tools`) scoped to the shadow root, with theme defaults on `:host` (`--bulma-hb-def-*`). Set public **`--bulma-*`** on `body` or `:root`; they inherit onto the custom element host.

Markup pattern:

- Wrapper: `div.hb-input-number-root` around **`input.input`** (Bulma control styling).
- Validation: `is-success` / `is-danger` on the input when `show_validation === "yes"` and `schemaentry.required` is set.
- Help: `p.help.is-danger` with `part="invalid-feedback"` when `show_validation === "yes"` and the value is invalid.

## Types

```typescript
export type FormSchemaEntry = {
  id: string;
  label?: string;
  value?: number;
  readonly?: boolean;
  required?: boolean;
  validationRegex?: string;
  validationTip?: string;
  placeholder?: string;
  params?: Record<string, any>;
};

export type Component = {
  id?: string;
  style?: string;
  show_validation?: "yes" | "no";
  is_small?: "yes" | "no";
  schemaentry: FormSchemaEntry | undefined;
};

export type Events = {
  setVal: { value: number; valid: boolean; id: string };
  clickEnter: { value: string; valid: boolean; id?: string };
};
```

---

<a id="wc-input-radio"></a>

# hb-input-radio

## Description

Radio group built from `schemaentry.params.options` with a shared `name` derived from the field id. Parses JSON `schemaentry` for initial `value` and supports required validation with Bulma `help is-danger` when `show_validation` is `yes` and invalid. Dispatches `setVal` with the selected string `value`, `valid`, and `id` whenever the choice changes.

## Styling (Bulma)

Shadow bundle: `form/shared`, `form/input-textarea`, `form/checkbox-radio`, `form/tools`. Markup uses Bulma `radios` / `radio` and host outline when invalid.

## Types

```typescript
export type FormSchemaEntry = {
  /**
   * This will be both the key of the object when submitting the form's data,
   * and also the id in the DOM.
   */
  id: string;

  /**
   * The descriptive label that will show alongside the form control.
   */
  label?: string;

  /**
   * Optional default value.
   */
  value?: string | number | boolean;

  readonly?: boolean;

  /**
   * This doesn't matter if the dependencies requirements aren't met.
   */
  required?: boolean;

  validationRegex?: string;
  /**
   * Shows if value is not valid.
   */
  validationTip?: string;

  placeholder?: string;

  /**
   * Other parameters that may be specific to a certain kind of form control.
   */
  params?: Record<string, any>;
};

export type Component = {
  id?: string;
  style?: string;

  show_validation?: "yes" | "no";
  schemaentry: FormSchemaEntry | undefined;
};

export type Events = {
  setVal: { value: string | undefined; valid: boolean; id: string | undefined };
};
```

---

<a id="wc-input-range"></a>

## `hb-input-range` — input-range

**Category:** inputs  
**Tags:** inputs

### What it does

Range slider (`type="range"`) whose bounds come from `schemaentry.params.min` and/or `max` when those keys exist. Parses stringified `schemaentry` when needed and enforces required / min / max on the numeric value. Dispatches `setVal` with `{ value, valid, id }` and shows `validationTip` as Bulma `help is-danger` when `show_validation` is `yes` and the field is invalid.

### Styling (Bulma)

Shadow bundle: `form/shared`, `form/input-textarea`, `form/tools`. The native range uses `accent-color` mapped to Bulma link / success / danger via `--bulma-*` on `:host` (not the text `input` class, which does not suit range controls).

### Custom element

`hb-input-range`

### Attributes (snake_case; use string values in HTML)

- `id` — optional string  
- `style` — optional string  
- `schemaentry` — required string (JSON: `id`, `label?`, `required?`, `value?` (number), `validationTip?`, `params.min` / `params.max`, …)  
- `show_validation` — optional `"yes"` | `"no"`

### Events

- `setVal` — `{ value: number; valid: boolean; id: string }`

### Usage notes

CSS parts: `input`, `invalid-feedback`.

### Minimal HTML example

```html
<hb-input-range
  schemaentry="{&quot;id&quot;:&quot;volume&quot;,&quot;required&quot;:true,&quot;params&quot;:{&quot;min&quot;:0,&quot;max&quot;:100},&quot;value&quot;:50}"
  show_validation="no"
></hb-input-range>
```

---

<a id="wc-input-select"></a>

# hb-input-select

## Description

Native `<select>` bound to `schemaentry` options from `params.options` (each option has `id`, `value`, and optional `label`). Supports JSON string or object `schemaentry`, optional required state, and `show_validation` for Bulma validation styling on the wrapper (`select.is-success` / `select.is-danger`) plus a `validationTip` shown as `help is-danger`. Dispatches `setVal` with `{ value, valid, id }` on every change. Use `is_small="yes"` for Bulma **`select.is-small`** (compact control, e.g. next to **`hb-paginate`**).

## Styling (Bulma)

The component bundles **Bulma 1.x** form styles (`form/shared`, `form/select`, `form/tools`) scoped to the shadow root, with theme defaults on `:host` (`--bulma-hb-def-*`). To align with the rest of the app, set public **`--bulma-*`** variables on `body` or `:root`; they inherit onto the custom element host.

Markup pattern:

- Wrapper: `div.select` around the native `<select>` (Bulma arrow and control height).
- Validation: `is-success` / `is-danger` modifiers on `div.select` when `show_validation === "yes"` and `schemaentry.required` is set.
- Help text: `p.help.is-danger` with `part="invalid-feedback"` for theming (only when `show_validation === "yes"` and the value is invalid).
- `schemaentry.readonly` maps to the native `disabled` attribute on `<select>` (HTML does not support `readonly` on selects).

## Types

```typescript
export type FormSchemaEntry = {
  /**
   * This will be both the key of the object when submitting the form's data,
   * and also the id in the DOM.
   */
  id: string;

  /**
   * The descriptive label that will show alongside the form control.
   */
  label?: string;

  /**
   * Optional default value.
   */
  value?: string | number | boolean;

  /** When true, the native `<select>` is `disabled` (HTML has no `readonly` on `<select>`). */
  readonly?: boolean;

  /**
   * This doesn't matter if the dependencies requirements aren't met.
   */
  required?: boolean;

  validationRegex?: string;
  /**
   * Shows if value is not valid.
   */
  validationTip?: string;

  placeholder?: string;

  /**
   * Other parameters that may be specific to a certain kind of form control.
   */
  params?: Record<string, any>;
};

export type Component = {
  id?: string;
  style?: string;

  show_validation?: "yes" | "no";
  is_small?: "yes" | "no";
  schemaentry: FormSchemaEntry | undefined;
};

export type Events = {
  setVal: { value: string; valid: boolean; id: string };
};
```

---

<a id="wc-input-text"></a>

# hb-input-text

## Description

Single-line text field driven by a JSON `schemaentry` (id, value, placeholder, readonly, required, optional `validationRegex`, and `params` min/max length). With `show_validation`, uses Bulma `input.is-success` / `is-danger` and `help is-danger` for tips. Theme via inherited `--bulma-*` on `:host`. Dispatches `setVal` whenever the value or validity changes, and `clickEnter` on Enter.

## Styling (Bulma)

Bundles **Bulma 1.x** `form/shared`, `form/input-textarea`, and `form/tools` in the shadow root; theme defaults on `:host` (`--bulma-hb-def-*`). Override public **`--bulma-*`** from `body` / `:root`.

## Types

```typescript
export type FormSchemaEntry = {
  /**
   * This will be both the key of the object when submitting the form's data,
   * and also the id in the DOM.
   */
  id: string;

  /**
   * Optional default value.
   */
  value?: string | number | boolean;

  readonly?: boolean;

  /**
   * This doesn't matter if the dependencies requirements aren't met.
   */
  required?: boolean;

  validationRegex?: string;
  /**
   * Shows if value is not valid.
   */
  validationTip?: string;

  placeholder?: string;

  /**
   * Other parameters that may be specific to a certain kind of form control.
   */
  params?: Record<string, any>;
};

export type Component = {
  id?: string;
  style?: string;

  show_validation?: "yes" | "no";
  schemaentry: FormSchemaEntry;
};

export type Events = {
  setVal: { value: string, valid: boolean, id: string };
};
```

---

<a id="wc-json-viewer"></a>

# hb-json-viewer

## Description

Renders JSON as an expandable, syntax-colored tree. Accepts a parsed object or a JSON string and supports initial expand modes (open, closed, or first level only).

## Styling (Bulma)

The shadow root loads **Bulma 1.x** theme tokens on `:host` only (no Bulma layout classes on the tree). Override **`--bulma-*`** from the light DOM for consistency with the app. **String** values use the success accent (`--jn-string` → Bulma success `*-on-scheme`); other primitives use **`--bulma-text`** / **`--bulma-text-weak`**. **Object** / **Array** type labels use **`--jn-type-object`** (danger) and **`--jn-type-array`** (warning). All tokens are Bulma `var(--bulma-*, var(--bulma-hb-def-*))` chains—no hardcoded hex. Dark mode follows `prefers-color-scheme: dark`, or `data-theme="dark"` / `.theme-dark` on `html`/`body`, or `data-theme="dark"` on the host.

## Types

```typescript

export type Component = {
  id?: string;
  json: any;
  status?: "open" | "closed" | "first";
};

export type Events = {
};
```

---

<a id="wc-layout"></a>

# hb-layout

## Description

Responsive application shell: below 800px viewport width it mounts the mobile layout; otherwise the desktop layout. Forwards navigation slots, page content, cookie-law options, and layout events from the active child.

## Navigation `navlinks` and Bootstrap Icons

Set `navlinks` on `hb-layout` as a serialized JSON array (HTML attribute) or as an array in JS. The active child forwards it to either `hb-layout-desktop` (sidebar with `hb-sidebar-desktop`) or `hb-layout-mobile` (offcanvas with the same navigation model).

Use the same `icon` field on each link as for `hb-sidebar-desktop`: Bootstrap Icons **name only** after `bi-` (e.g. `"gear"`, not `"bi bi-gear"`). Details and copy-paste examples: [`hb-sidebar-desktop` README](../sidebar-desktop/README.md#navigation-icons-bootstrap-icons).

## Types

```typescript
import type {
  IContacts,
  ISocials,
  ICompany,
  IColumn,
  IPolicies,
} from "../../footer/types/webcomponent.type";
import type { IUserMenu } from "../../navbar/types/webcomponent.type";
import type { INavLink } from "../../sidenav-link/types/webcomponent.type";

export type Component = {
  i18nlang?: string;
  id?: string;
  style?: string;
  page_title?: string;
  socials?: ISocials;
  contacts?: IContacts;
  company?: ICompany;
  navlinks?: INavLink[];
  pagename?: string;
  usermenu?: IUserMenu;
  cookielaw?: string;
  columns?: IColumn[];
  single_screen?: boolean;
  cookielawuri4more?: string;
  cookielawallowdecline?: boolean;
  cookielawlanguage?: string;
  sidebar?: { title?: string; logo?: string; type?: string };
  footer?: {
    type?: "auto" | "small" | "regular" | "large";
    disable_expanding_small?: boolean;
  };
  policies?: IPolicies[];
  heders?: {
    name?: string;
    content: string;
    property?: string;
  }[];
};

export type Events = {
  offcanvasswitch: { isOpen: boolean };
  pageChange: { page: string };
  navbarDropDownClick: { key: string };
  footerClick: { elClick: string };
  navbarSlotClick: { side: "left" | "right" | "center" };

  // layoutStatus: { width: number; size: "large" | "small" };
};
```

---

<a id="wc-layout-desktop"></a>

# hb-layout-desktop

## Description

Desktop layout with top navbar, optional left sidebar (sidebar-desktop) when navigation links are present, main page area, optional cookie-law banner, and footer. Without `single_screen`, the page column scrolls and the cookie banner and footer are inside that scroll (footer appears after the slot when you scroll down). With `single_screen`, the cookie banner and footer stay fixed at the bottom of the main column (always visible); only the page slot area scrolls, and `footer.type` `auto` uses the compact footer. The sidebar rail is capped to the viewport band. Forwards navigation and footer events.

## Passing `navlinks` and sidebar icons

When `navlinks` is non-empty, this layout renders `hb-sidebar-desktop` and forwards your navigation data to it.

- **Property / attribute:** set `navlinks` on `hb-layout-desktop` the same way as on `hb-sidebar-desktop`: in HTML use a **JSON string** (serialized `INavLink[]`). In JavaScript you may assign an array of objects directly if your binding supports it.
- **Icons:** each link object can include optional `icon` with the Bootstrap Icons **glyph name only** (the part after `bi-` in the official class, e.g. `house-door` for `bi-house-door`). See the [`hb-sidebar-desktop` README](../sidebar-desktop/README.md#navigation-icons-bootstrap-icons) for the full rules, examples, and `subLinks` behavior.

## Types

```typescript
import type {
  IContacts,
  ISocials,
  ICompany,
  IColumn,
  IPolicies,
} from "../../footer/types/webcomponent.type";
import type { IUserMenu } from "../../navbar/types/webcomponent.type";
import type { INavLink } from "../../sidenav-link/types/webcomponent.type";

export type Component = {
  i18nlang?: string;
  id?: string;
  style?: string;
  socials?: ISocials;
  contacts?: IContacts;
  company?: ICompany;
  navlinks?: INavLink[];
  pagename?: string;
  page_title?: string;
  usermenu?: IUserMenu;
  cookielaw?: string;
  columns?: IColumn[];
  single_screen?: boolean;
  cookielawuri4more?: string;
  cookielawallowdecline?: boolean;
  cookielawlanguage?: string;
  sidebar?: { title?: string; logo?: string; type?: string };
  footer?: {
    type?: "auto" | "small" | "regular" | "large";
    disable_expanding_small?: boolean;
  };
  policies?: IPolicies[];
};

export type Events = {
  offcanvasswitch: { isOpen: boolean };
  pageChange: { page: string };
  navbarDropDownClick: { key: string };
  footerClick: { elClick: string };
  layoutStatus: { width: number; size: "large" | "small" };
  navbarSlotClick: { side: "left" | "right" | "center" };
};
```

---

<a id="wc-layout-mobile"></a>

# hb-layout-mobile

## Description

Mobile layout with optional offcanvas sidebar navigation, top navbar, main page slot, optional cookie-law banner, and footer. Without `single_screen`, the main column scrolls and includes the cookie banner and footer after the slot. With `single_screen`, cookie and footer stay at the bottom of the shell (always visible) and only the page slot area scrolls. Forwards navbar, footer, and navigation events.

## Passing `navlinks` and sidebar icons

When `navlinks` is non-empty, navigation is shown inside `hb-offcanvas`, which hosts `hb-sidebar-desktop`. Set `navlinks` on `hb-layout-mobile` as a JSON string (in HTML) or array (in JS), same shape as for `hb-sidebar-desktop`.

For each link, optional `icon` must be the Bootstrap Icons **glyph name only** (suffix after `bi-`, e.g. `house-door`). See [`hb-sidebar-desktop` README](../sidebar-desktop/README.md#navigation-icons-bootstrap-icons).

## Types

```typescript
import type {
  IContacts,
  ISocials,
  ICompany,
  IColumn,
  IPolicies,
} from "../../footer/types/webcomponent.type";
import type { IUserMenu } from "../../navbar/types/webcomponent.type";
import type { INavLink } from "../../sidenav-link/types/webcomponent.type";

export type Component = {
  id?: string;
  style?: string;
  socials?: ISocials;
  contacts?: IContacts;
  company?: ICompany;
  navlinks?: INavLink[];
  pagename?: string;
  page_title?: string;
  usermenu?: IUserMenu;
  cookielaw?: string;
  columns?: IColumn[];
  single_screen?: boolean;
  cookielawuri4more?: string;
  cookielawallowdecline?: boolean;
  cookielawlanguage?: string;
  sidebar?: { title?: string; logo?: string; type?: string };
  footer?: {
    type?: "auto" | "small" | "regular" | "large";
    disable_expanding_small?: boolean;
  };
  policies?: IPolicies[];
  i18nlang?: string;
};

export type Events = {
  offcanvasswitch: { isOpen: boolean };
  pageChange: { page: string };
  navbarDropDownClick: { key: string };
  footerClick: { elClick: string };
  layoutStatus: { width: number; size: "large" | "small" };
  navbarSlotClick: { side: "left" | "right" | "center" };
};
```

---

<a id="wc-map"></a>

# hb-map

## Description

Interactive map: `center`, `zoom`, `source` (OSM or CARTO vector styles), `options` (e.g. `centerFromGeometries`, marker text layout), and `data` with markers (lng/lat, icon, popup HTML, text). Set `screenshot` to capture; emits map clicks, marker clicks, and screenshot payloads.

## Types

```typescript
export type Component = {
  id?: string;
  style?: string;
  zoom: number;
  center: number[];
  data: {
    marker?: {
      lngLat: number[];
      icon?: {
        uri: string;
        scale?: number;
        anchor?: number[];
        opacity?: number;
        color?: string;
      };
      id?: string;
      popupHtml?: string;
      text?: string;
      text_position?: "top" | "right" | "bottom" | "left";
      text_offset?: number;
    };
    point?: {
      lngLat: number[];
      icon?: {
        uri: string;
        scale?: number;
        anchor?: number[];
        opacity?: number;
        color?: string;
      };
      id?: string;
      popupHtml?: string;
    };
    line?: {
      lngLat: number[];
      icon?: {
        uri: string;
        scale?: number;
        anchor?: number[];
        opacity?: number;
        color?: string;
      };
      id?: string;
      popupHtml?: string;
    }[];
  }[];
  source: { type: string; url?: string; style?: "positron" | "dark_matter" | "voyager" };
  options: {
    centerFromGeometries?: boolean;
    text_position?: "top" | "right" | "bottom" | "left";
    text_offset?: number;
    text_scale?: number;
  };
  screenshot?: string;
};

export type Events = {
  pointClickCoordinates: {
    coordinates: { latitude: number; longitude: number };
    zoom: number;
    center: number[];
  };
  markerClick: {
    coordinates: { latitude: number; longitude: number };
    id: string;
  };
  screenshotTaken: {
    base64: string;
  };
};
```

---

<a id="wc-markdown-viewer"></a>

# hb-markdown-viewer

## Description

Renders Markdown from a data object (typically with a content string) using marked with GFM and line breaks, and normalizes compact single-line Markdown for clearer lists and headings.

## Styling (Bulma)

Uses **Bulma** `container is-fluid`, `columns`, and `column` for layout; prose styles live in `styles/webcomponent.scss` (`.markdown-body`). Theme tokens: **`--bulma-*`** on `:host` (see `extra/docs.ts`).

## Types

```typescript
export type Component = {
  id?: string;
  style?: string;
  data: {
    content: string;
  };
};

export type Events = {
  // event: { test: boolean };
};
```

---

<a id="wc-matrix-video"></a>

# hb-matrix-video

## Description

Responsive video wall: lays out `items` in a **Bulma** `columns` / `column` grid (gapless rows) sized from the viewport (16:9-friendly). Each cell can be an iframe, plain MP4 `<video>`, `hb-player-live` (WHEP), or `hb-player-live-camera-ptz`. Tracks hover selection and emits `hoverItem` and `clickItem` with the focused tile id.

## Types

```typescript
export type Component = {
	id?: string;
	style?: string;
	items: { type: "video" | "iframe" | "mediamtx-webrtc" | "mediamtx-webrtc-ptz"; id: string; uri: string; title?: string }[];
};

export type Events = {
	hoverItem: { id?: string; selected: boolean };
	clickItem: { id: string };
};
```

---

<a id="wc-messages-box"></a>

# hb-messages-box

## Description

Chat shell combining `hb-messages-list` (thread from `messages`, `authors`, `options`) and `hb-messages-send` (composer). Optional `message` JSON can seed the draft text. Forwards the child `sendMessage` event (text, files, tags) to the host as `sendMessage` for your transport layer.

## Types

```typescript
// type that is used to define a chat message
export type TMessage = {
	id: string;
	text: string;
	timestamp: Date;
	type: "text" | "image" | "video" | "audio" | "file";
	status?: "pending" | "sent" | "received" | "read";
	system?: boolean;
	reply?: boolean;
	quotedMessageId?: string;
	authorId?: string;
	uri?: string;
};

// type that is used to define a chat partecipant
export type TAuthor = {
	id: string;
	name: string;
	avatar?: string;
	status: "online" | "offline" | "away" | "busy";
	me?: boolean;
};

export type TMessageSend = {
	text?: string;
	file?: File;
};

export type Component = {
	id?: string;
	style?: string;
	messages: TMessage[];
	authors: TAuthor[];
	options?: {};
	message?: TMessageSend;
};

export type Events = {
	sendMessage: { text?: string; id: string; file?: File };
};
```

---

<a id="wc-messages-list"></a>

# hb-messages-list

## Description

Renders a conversation from `messages` joined to `authors`: aligned bubbles for self vs others, optional avatars and names, timestamps, and code blocks with language badges when `type` is `code`. `options` toggle bubbles, avatars, names, and time; `actions` adds per-message icon buttons that dispatch `action` with `messageId` and action name. Consecutive messages from the same author collapse avatar spacing within a short time window.

## Types

```typescript
// type that is used to define a chat message
export type TMessage = {
	id: string;
	text: string;
	timestamp: Date;
	type: "text" | "image" | "video" | "audio" | "file" | "code";
	status?: "pending" | "sent" | "received" | "read";
	system?: boolean;
	reply?: boolean;
	quotedMessageId?: string;
	authorId?: string;
	uri?: string;
	language?: string; // For code messages
};

// type that is used to define a chat partecipant
export type TAuthor = {
	id: string;
	name: string;
	avatar?: string;
	status: "online" | "offline" | "away" | "busy";
	me?: boolean;
	isAI?: boolean; // Special flag for AI author
};

export type Component = {
	id?: string;
	style?: string;
	messages: TMessage[];
	authors: TAuthor[];
	options?: {
		showTimestamp?: boolean;
		showAvatar?: boolean;
		showName?: boolean;
		bubbles?: boolean;
	};
	actions?: {
		icon: string;
		name: string;
	}[]
};

export type Events = {
	action: { messageId: string; action: string };
};
```

### Styling (Bulma)

The shadow root bundles **Bulma 1.x** (buttons, tags, flex/spacing/typography/color helpers, image rounding). Theme defaults apply on `:host` via Bulma’s light theme and `setup-theme`. Override from the page with public **`--bulma-*`** (see `extra/docs.ts`). **Bootstrap Icons** load from `<svelte:head>` for action `bi-*` icons.

---

<a id="wc-messages-send"></a>

# hb-messages-send

## Description

Message composer with auto-growing textarea (optional `expandable` and maximize control), Enter-to-send, file attachments with previews (`files.mode` single or multiple), and optional `tags` as toggleable chips. Dispatches `sendMessage` with `text`, selected `tags`, and staged `files` when the user sends.

## Types

```typescript
export type Component = {
	id?: string;
	style?: string;
	text?: string;
	expandable?: boolean;
	tags?: {
		label?: string;
		icon?: string;
		id: string
		color?: string;
	}[]
	files?: {
		mode: "single" | "multiple";
	}
};

export type Events = {
	sendMessage: { text?: string; id: string; tags: string[]; files: File[] };
};
```

### Styling (Bulma)

Bundles **Bulma 1.x** (`container` grid via `columns` / `column`, buttons, tags, helpers). Theme defaults on `:host` via Bulma light + `setup-theme`. Override with **`--bulma-*`** from the page (see `extra/docs.ts`). **Bootstrap Icons** load from `<svelte:head>` for attach, tags, send, and file-type icons.

---

<a id="wc-messages-topics-card"></a>

# hb-messages-topics-card

## Description

Lists chat or channel previews from `chats`: avatar, title, last message snippet, derived time label, and unread `counter` as a Bulma tag. Clicking a row marks it selected (`_selected`) and dispatches `select` with that chat payload for opening a thread or switching context.

## Styling (Bulma)

The component bundles **Bulma 1.x** in the shadow root: **`elements/tag`** (unread counter), with theme defaults on `:host` (`--bulma-hb-def-*`). Set public **`--bulma-*`** on `body` or `:root` so they inherit onto the host. Row hover and selected backgrounds default from **`--bulma-scheme-main-bis`** and **`--bulma-scheme-main-ter`**; override with **`--hb-topics-card-hover-background-color`** and **`--hb-topics-card-selected-background-color`** if needed. See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).

**Shadow markup (simplified):**

- **`div.grid`** — one row per chat (click selects).
- **`img`**, **`div.header`** (title + time), **`div.details`** (snippet + **`span.tag.is-light.is-rounded`** counter).

**Host-level tokens (existing):** `--hb-topics-card-size`, `--hb-topics-card-padding`, derived `--hb-topics-card-double-*`, plus the selected/hover background variables above.

## Types

```typescript
export type IChat = {
	time: Date;
	title: string;
	text: string;
	img_uri: string;
	is_group?: boolean;
	chat_name?: string;
	chat_img?: string;
	chat_id: string;
	last_message_author?: string;
	last_message_author_img?: string;
	last_message_time?: Date;
	last_message_text?: string;
	counter?: number;
	localeTimeString?: string;
	_selected?: boolean;
};

export type Component = {
	id?: string;
	style?: string;

	chats: IChat[];
};

export type Events = {
	select: IChat;
};
```

---

<a id="wc-modal-video"></a>

# hb-modal-video

## Description

Video modal built on hb-dialog: when uri is set the dialog opens with either a YouTube iframe (provider youtube) or an HTML5 video element, optional title slot, and videoModalEvent when visibility changes.

## Types

```typescript
export type Component = {
	id?: string;
	style?: string;
	item?: string;
	uri: string;
	title?: string;
	provider?: string;
};

export type Events = {
	videoModalEvent: { id: string; show: boolean };
};
```

---

<a id="wc-navbar"></a>

# hb-navbar

## Description

Top navigation bar with optional hamburger to toggle an offcanvas menu, brand name and logo, slottable left, center, and right areas, and an optional user avatar dropdown (hb-dropdown-simple) with item click events.

## Types

```typescript
interface IUserMenuListItem {
	key: string;
	label: string;
	badge?: number;
	group?: string;
}
export interface IUserMenu {
	imgUri: string;
	list?: IUserMenuListItem[];
}
export type Component = {
	id?: string;
	style?: string;
	companybrandname: string;
	companylogouri: string;
	// pagetitle: string;
	switchopen?: "yes" | "no";
	usermenu?: IUserMenu;
	noburger?: string;
};

export type Events = {
	navbarDropDownClick: { key: string };
	navmenuswitch: { isOpen: boolean };
	navbarSlotClick: { side: "left" | "right" | "center" };
};
```

---

<a id="wc-offcanvas"></a>

## `hb-offcanvas` — offcanvas

**Category:** layout  
**Tags:** layout, navigation

### What it does

Slide-in sidebar panel that hosts `hb-sidebar-desktop`. Uses a fixed panel plus Bulma’s `modal-background` as the dimmed backdrop when `type` is `autohide`. Can start open or closed; dispatches page changes and open/close state.

### Custom element

`hb-offcanvas`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `opened` (optional): boolean string — panel starts open.
- `companylogouri`, `companytitle` (optional): strings.
- `groups` (optional): JSON string — `{ key; label }[]` for nav grouping.
- `enablefooter` (optional): boolean string.
- `type` (optional): `"open"` | `"autohide"` | `"small"` — backdrop and sizing.
- `navpage` (optional): string — active page key.
- `navlinks` (optional): JSON string — `INavLink[]` (label, key, optional `icon` for Bootstrap Icons, badge, subLinks, etc.). Icon values follow the same rules as `hb-sidebar-desktop`; see [Navigation icons (Bootstrap Icons)](../sidebar-desktop/README.md#navigation-icons-bootstrap-icons).

### Events

- `offcanvasswitch`: `{ isOpen: boolean }`.
- `pageChange`: `{ page: string }`.

### Usage notes

- **Slots:** `test`, `header`, `footer`.
- **CSS parts:** `header` (on nested `hb-sidebar-desktop`).
- Bulma theme variables apply inside each web component’s shadow root; Bootstrap Icons CSS is loaded for nested nav icons.
- The panel embeds `hb-sidebar-desktop`; pass `navlinks` on `hb-offcanvas` exactly as you would on `hb-sidebar-desktop` (including each item’s optional `icon` string: Bootstrap glyph name only, e.g. `house-door`).
- Pair with `hb-sidebar-desktop` / `hb-sidenav-link`; see Storybook examples in `extra/docs.ts`.

### Minimal HTML example

```html
<hb-offcanvas
  opened="true"
  type="autohide"
  companytitle="Acme"
  navpage="home"
  navlinks='[{"label":"Home","key":"home","icon":"house-door"}]'
></hb-offcanvas>
```

---

<a id="wc-order-list"></a>

## `hb-order-list` — order list

**Category:** commerce  
**Tags:** commerce, order

### What it does

Order summary view driven by a payment JSON object: order number header, optional tracking area, list of line items with image and name, and a footer showing the order total including tax and optional shipment fee. Exposes the item image via the `item_image` CSS part.

### Custom element

`hb-order-list`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `payment` (required): JSON string — `OrderPayment` with `orderNumber`, `countryCode`, `items` (shop line items plus `image` per row), plus cart/tax fields from shared checkout types.

### Events

None declared.

### Styling (Bulma)

Layout uses Bulma `container` and `columns` / `column` with fractional widths (`is-10`, `is-2`, etc.). Theme tokens are registered on `:host` via Bulma’s light theme and `setup-theme`. Customize colors and spacing from the page by setting `--bulma-*` variables (for example `--bulma-text`, `--bulma-scheme-main`, `--bulma-column-gap`); see `extra/docs.ts` and `styles/bulma.scss`.

### Usage notes

- **CSS parts:** `item_image`.
- Serialize `payment` as a single JSON attribute; see `builder/src/wc/order-list/types/webcomponent.type.d.ts` and examples in `extra/docs.ts`.

### Minimal HTML example

```html
<hb-order-list
  payment='{"orderNumber":"1001","countryCode":"EU","items":[{"id":"1","name":"Item","unitaryPrice":10,"taxPercentage":22,"image":"https://example.com/a.jpg"}]}'
></hb-order-list>
```

---

<a id="wc-pad-joystick"></a>

## `hb-pad-joystick` — pad joystick

**Category:** utilities  
**Tags:** utilities, controls

### What it does

Touch-friendly directional control: either a four-way D-pad that emits cardinal directions or an analog joystick that streams position and cardinal direction with customizable colors.

### Custom element

`hb-pad-joystick`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `pad_or_joystick` (optional): `"dpad"` | `"joystick"` (default pad-style behavior when omitted per examples).
- `joystick_parameters` (optional): JSON string — `internalFillColor`, `internalLineWidth`, `internalStrokeColor`, `externalLineWidth`, `externalStrokeColor`.

### Events

- `sendDirection`: `{ direction: "up" | "right" | "down" | "left"; id: string }`.
- `sendJoystickPosition`: `{ x; y; cardinalDirection; id: string }` (cardinal set per `CardinalDirection` in types).

### Usage notes

- **CSS variables:** `--hb-pad-joystick-size` (default `200px`).
- Use `pad_or_joystick="joystick"` for analog mode; see `extra/docs.ts`.

### Minimal HTML example

```html
<hb-pad-joystick pad_or_joystick="dpad"></hb-pad-joystick>
```

---

<a id="wc-page-checkout"></a>

## `hb-page-checkout` — page checkout

**Category:** commerce  
**Tags:** commerce, checkout, page

### What it does

Checkout page layout that embeds the payment flow and shopping cart: left column uses `hb-checkout` (user, shipments, gateways, payment) and right column uses `hb-checkout-shopping-cart`. Recomputes line totals, tax, shipment fee, and payment total from JSON props; updates shipment selection internally and forwards `paymentCompleted` and `saveUser` to the host.

### Custom element

`hb-page-checkout`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `shipments` (required): JSON string — `IShipment[]` (see `hb-checkout` types).
- `user` (required): JSON string — `IUser` (address, nationality, zip, `fixed`, etc.).
- `payment` (required): JSON string — shopping payment + `IPayment` fields (currency, items, totals, merchant, country).
- `gateways` (required): JSON string — `IGateway[]` (e.g. PayPal id, Google Pay ids).
- `completed` (optional): `"yes"` | `"no"` — completion state for UI.

### Events

- `saveUser`: detail is `IUser` (updated user payload).
- `paymentCompleted`: `{ total: number; method: string; completed: true }`.

### Usage notes

- **CSS variables:** `--hb-checkout-border`, Bulma `--bulma-*` (see `extra/docs.ts`).
- Compose gateways and payment objects like Storybook `extra/docs.ts`; shared types live under `hb-checkout` / `hb-checkout-shopping-cart`.

### Styling (Bulma)

Layout uses **Bulma** `container`, `columns`, and fractional `column` widths (`is-7` / `is-5`). Theme tokens apply on `:host`; child web components inherit public **`--bulma-*`** variables.

### Minimal HTML example

```html
<hb-page-checkout
  shipments="[]"
  user='{"fullName":"Jane Doe","addressWithNumber":"Main 1","city":"Rome","nationality":"IT","zip":"00100","fixed":true}'
  payment='{"countryCode":"IT","merchantName":"Shop","currencyCode":"EUR","total":100,"items":[{"id":"a","name":"A","unitaryPrice":10,"taxPercentage":22}]}'
  gateways='[{"id":"paypal","label":"PayPal","paypalid":"YOUR_CLIENT_ID"}]'
></hb-page-checkout>
```

---

<a id="wc-page-invoice"></a>

## `hb-page-invoice` — page invoice

**Category:** commerce  
**Tags:** commerce, invoice, page

### What it does

Printable invoice page: shows seller and buyer from headers, invoice date and serial, line items in `hb-table` with price, quantity, VAT and row totals, plus subtotal, tax and grand total in the invoice currency. When `printer` is not `yes`, offers print and open-in-window actions.

### Custom element

`hb-page-invoice`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `printer` (optional): `"yes"` | `"no"` — print-only / interactive mode.
- `headers` (required): JSON string — `IHeaders` (`serial`, `from` with `logo` and `shortName`, `to`, optional `country`, `date`, `category`, etc.).
- `items` (required): JSON string — `IItem[]` (`desc`, `unitaryPrice`, `taxPercentage`, optional `quantity`, `unit`, `discount`).

### Events

None declared.

### Usage notes

- **CSS variables:** Bulma `--bulma-*` (see `extra/docs.ts`).
- Align `headers` / `items` with `builder/src/wc/page-invoice/types/webcomponent.type.d.ts`.

### Styling (Bulma)

Layout uses **Bulma** `container`, `columns` / `column`, and `button is-light` for toolbar actions. **Bootstrap Icons** load from `<svelte:head>` for print / fullscreen icons (`bi-*`).

### Minimal HTML example

```html
<hb-page-invoice
  printer="no"
  headers='{"serial":"INV-1","from":{"piva":"IT1","name":"Seller","address":"Via 1","email":"a@b.co","phone":"0","logo":"https://example.com/logo.svg","shortName":"Seller"},"to":{"piva":"IT2","name":"Buyer","address":"Via 2","email":"b@b.co","phone":"1"}}'
  items='[{"desc":"Service","unitaryPrice":100,"taxPercentage":22,"quantity":1}]'
></hb-page-invoice>
```

---

<a id="wc-paginate"></a>

# hb-paginate

**Category:** utilities · **Tags:** utilities, navigation

## Description

Pagination controls (first / previous / numbered pages / next / last), optional “showing X–Y of total” text, optional page-size via **`hb-input-number`** or **`hb-input-select`**, and optional sort field + direction with i18n. Dispatches `pageChange`, `changePageSize`, and `changeSort`.

## Styling (Bulma)

The component bundles **Bulma 1.x** in the shadow root: **`form/shared`**, **`form/select`** (sort dropdown), and **`form/pagination`**, with theme defaults on `:host` (`--bulma-hb-def-*`). Set public **`--bulma-*`** on `body` or `:root` so they inherit onto the host and match the rest of the app. Relevant tokens include pagination, controls, text, and borders — see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).

**Shadow markup (simplified):**

- **`div.hb-paginate`** — single horizontal row: optional info/size block + **`nav.pagination`**.
- **`div.paginate-bar`** — rendered only when range text and/or page-size UI is needed (avoids extra flex gap when only pagination is shown).
- **`ul.pagination-list`** / **`button.pagination-link`** — Bulma pagination; list uses **`gap`** instead of doubled per-link horizontal margins.
- Sort UI: **`div.select.is-small`** + native **`select`**, and a direction **`button.pagination-link`**.

**Host-level overrides (optional):**

| Variable | Purpose |
|----------|---------|
| `--hb-paginate-height` | Fixed host height (default: `--bulma-control-height`, fallback `2.5rem`). |
| `--hb-paginate-bar-padding-inline-start` | Left inset for the info/size bar (default: `--bulma-pagination-item-padding-left`, fallback `0.5em`). |
| `--hb-paginate-list-gap` | Horizontal gap between pagination list items (default: half of `--bulma-pagination-item-margin`). |

## Custom element

`hb-paginate`

## Attributes (snake_case; string values in HTML)

- `id`, `style` (optional): strings.
- `page`, `pages` (required): current page index and total pages, as strings.
- `info` (optional): JSON string — `total`, `size`, `page_size_type` (`"number"` \| `"select"`), `page_size_options`, `sort_fields`, `sort_by`, `sort_direction`, `sort_disabled`, `sort_direction_disabled`, `sort_strict_direction`, `sort_default_value`, `sort_default_label`.
- `i18nlang` (optional): e.g. `en`, `it`.

## Events

- `pageChange`: `{ page: number; pages: number }`
- `changePageSize`: `{ page_size: number }`
- `changeSort`: `{ sort_by: string; sort_direction: string }`

## Usage notes

- **i18n:** Italian and English in metadata; set `i18nlang` accordingly.
- **`hb-table`:** while the table is in **`is_loading`**, **`hb-paginate`** remains mounted but hidden; an inline Bulma skeleton overlay mimics the bar. Use **`hb-paginate`** directly when you embed it outside the table.
- **Combined examples** (sort + page size): see `extra/docs.ts`.

## Types

```typescript
export type Component = {
  id?: string;
  style?: string;
  pages: number;
  page: number;
  info?: {
    total?: number;
    size?: number;
    page_size_type?: "number" | "select";
    page_size_options?: string;
    sort_fields?: { value: string; label?: string }[];
    sort_by?: string;
    sort_direction?: "asc" | "desc" | "default";
    sort_disabled?: boolean;
    sort_direction_disabled?: boolean;
    sort_strict_direction?: boolean;
    sort_default_value?: string;
    sort_default_label?: string;
  };
  i18nlang?: string;
};

export type Events = {
  pageChange: { page: number; pages: number };
  changePageSize: { page_size: number };
  changeSort: { sort_by: string; sort_direction: string };
};
```

## Minimal HTML example

```html
<hb-paginate page="0" pages="5" i18nlang="en"></hb-paginate>
```

---

<a id="wc-paragraps-around-image"></a>

## `hb-paragraps-around-image` — paragraphs around image

**Category:** content  
**Tags:** content

### What it does

Editorial block with a central image and up to six text blocks in two side columns using `hb-paragraps-around-image-cell` (indices 0, 2, 4 left; 1, 3, 5 right). Parses `paragraphs` from JSON and bubbles `paragraphPressed` when a cell fires it.

### Custom element

`hb-paragraps-around-image`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `img` (required): string — image URL.
- `paragraphs` (required): JSON string — array of `{ text; title?; icon?; link?; key? }`.

### Events

- `paragraphPressed`: `{ key: string }`.

### Usage notes

- **Slots:** `skelcontent`.
- **CSS parts:** `testpart`.
- Up to six paragraph objects; layout alternates columns per index.

### Minimal HTML example

```html
<hb-paragraps-around-image
  img="https://placehold.co/300x200"
  paragraphs='[{"text":"Hello body","title":"Title","icon":"globe","link":"https://example.com"}]'
></hb-paragraps-around-image>
```

---

<a id="wc-paragraps-around-image-cell"></a>

## `hb-paragraps-around-image-cell` — paragraph cell around image

**Category:** content  
**Tags:** content

### What it does

One paragraph tile with Bootstrap icon, optional title as external link or key-triggered control (dispatches `paragraphPressed` with `key`), and body text clamped to `max_lines` for consistent height inside `hb-paragraps-around-image` layouts.

### Custom element

`hb-paragraps-around-image-cell`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `paragraph` (required): JSON string — `{ text; title?; icon?; link?; key? }`.
- `max_lines` (optional): number as string — line clamp for body text.

### Events

- `paragraphPressed`: `{ key: string }`.

### Usage notes

- **Slots:** `skelcontent`.
- **CSS parts:** `testpart`.
- Typically embedded by `hb-paragraps-around-image`; usable alone for Storybook-style tiles (no separate image prop on this cell).

### Minimal HTML example

```html
<hb-paragraps-around-image-cell
  paragraph='{"text":"Body copy","title":"Read more","icon":"globe","key":"section-1"}'
  max_lines="4"
></hb-paragraps-around-image-cell>
```

---

<a id="wc-payment-paypal"></a>

## `hb-payment-paypal` — payment PayPal

**Category:** commerce  
**Tags:** commerce, payment

### What it does

Loads the PayPal JS SDK with your client id and currency, renders PayPal Buttons for a fixed order total, captures payment on approval, and dispatches `paymentCompleted` when the order is captured successfully.

### Custom element

`hb-payment-paypal`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `paypalid` (required): string — PayPal client / app id.
- `currency` (required): `"EUR"` | `"USD"` (string).
- `total` (required): number as string — order amount.

### Events

- `paymentCompleted`: `{ method: "paypal"; total: number }`.

### Usage notes

- **CSS variables:** `--hb-checkout-border`, Bulma `--bulma-*` (see `extra/docs.ts`).
- **CSS parts:** `btn` (PayPal button surface).
- Ensure CSP and PayPal script loading match your host app; totals are fixed for the rendered session.

### Styling (Bulma)

**Bulma** theme tokens are applied on `:host` only; the PayPal SDK injects its own button UI into `#paypalbtn`. Use **`--bulma-*`** for consistency with sibling checkout components.

### Minimal HTML example

```html
<hb-payment-paypal paypalid="YOUR_CLIENT_ID" currency="EUR" total="40"></hb-payment-paypal>
```

---

<a id="wc-player-input-streaming"></a>

## `hb-player-input-streaming` — player input streaming

**Category:** media  
**Tags:** media, video, camera

### What it does

Requests camera and microphone with `getUserMedia`, binds the stream to a `<video>` element, and exposes basic controls (play/pause, fullscreen, enable/disable video and audio tracks). Emits `AudioVideoAccess` with grant result and `VideoInitialized` with the video element reference once the stream is attached.

### Custom element

`hb-player-input-streaming`

### Attributes (snake_case; use string values in HTML)

- `id` (optional): string — echoed on dispatched events.

### Events

- `AudioVideoAccess`: `{ granted: boolean; id: string }`.
- `VideoInitialized`: `{ videoElement; id: string }`.
- `event`: `{ test: boolean }` (test hook in source).

### Usage notes

- Requires secure context and user permission for camera/microphone.
- Types in `webcomponent.type.d.ts` only list `event`; runtime also dispatches `AudioVideoAccess` and `VideoInitialized` (see `component.wc.svelte`).

### Minimal HTML example

```html
<hb-player-input-streaming id="cam1"></hb-player-input-streaming>
```

---

<a id="wc-player-live"></a>

## `hb-player-live` — player live

**Category:** media  
**Tags:** media, video, streaming

### What it does

Live streaming `<video>` player for HLS (hls.js or native), WebSocket WebRTC (`simple-webrtc-element`), or WHEP (MediaMTX). Polls the manifest for HLS liveness, exposes the element via `getVideoElement`, and emits `liveStatus` and `htmlVideoInit`. When the stream is offline or missing, shows optional title/subtitle/text from `replacewithtext`, `forcecover`, or fallback labels.

### Custom element

`hb-player-live`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `mediauri` (required): string — stream URL (HLS, WebRTC, WHEP as configured).
- `media_type` (optional): `"hls"` | `"webrtc"` | `"auto"` | `"whep"` (empty string allowed in examples).
- `forcecover` (optional): string — e.g. `"yes"` to force cover layout with placeholder text.
- `replacewithtext` (optional): JSON string — `{ title; subtitle?; text? }` when offline.
- `no_controls` (optional): boolean string — hide native/custom controls.

### Events

- `liveStatus`: `{ live: boolean; id: string }`.
- `htmlVideoInit`: `{ video; id: string }`.

### Usage notes

- **CSS parts:** `container`, `replacewithtext`, `video`.
- Pick `media_type` to match your pipeline (`whep` for WHEP examples in docs).

### Minimal HTML example

```html
<hb-player-live
  mediauri="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
  media_type="hls"
></hb-player-live>
```

---

<a id="wc-player-live-camera-ptz"></a>

## `hb-player-live-camera-ptz` — player live camera PTZ

**Category:** media  
**Tags:** media, video, streaming, camera

### What it does

Live camera view built on `hb-player-live` with a configurable PTZ panel: D-pad or analog joystick, zoom in/out, go home, click-to-center region on the video, optional grid overlay, fullscreen, mute, and play/pause. Manages camera presets in dialogs with `hb-table` (add, go to, delete). Feature flags live in `configuration`; PTZ and UI state are driven by `is_ptz_connected`, `is_ptz_panel_opened`, and `is_home`. Toolbar controls use **Bulma** `button` / `buttons has-addons`. Dispatches movement, preset, and video-init events for the host app to wire to your backend.

### Custom element

`hb-player-live-camera-ptz`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `live_uri` (required): string — stream URI for the embedded player.
- `media_type` (optional): `"hls"` | `"webrtc"` | `"auto"` | `"whep"` | `""`.
- `is_ptz_connected`, `is_ptz_panel_opened`, `is_home` (optional): boolean strings.
- `presets` (optional): JSON string — `TPreset[]` (`token`, `name`, `x`, `y`, `z`).
- `current_preset` (optional): string — active preset token.
- `position` (optional): `"top"` | `"right-bottom"` | `"left-bottom"` | `"bottom"` | `"right-top"` | `"left-top"`.
- `configuration` (optional): JSON string — toggles for joystick, presets, zoom, pan, tilt, click-to-center, settings, etc.

### Events

- `initVideo`: `{ id; time; htmlVideoElement }`.
- `panelMove`: `{ id; opened: boolean }`.
- `goToHome`, `goToSelectedArea`, `setPreset`, `goToPreset`, `deletePreset`, `zoomAction`, `sendJoystickPosition`, `sendDirection` — see `builder/src/wc/player-live-camera-ptz/types/webcomponent.type.d.ts` for full payloads (`movementSettings`, geometry, presets, etc.).

### Usage notes

- **CSS variables:** Bulma theme tokens on `:host` (e.g. `--bulma-primary`, `--bulma-danger`); see `extra/docs.ts`.
- Host must implement PTZ API calls in response to movement and preset events.

### Minimal HTML example

```html
<hb-player-live-camera-ptz
  live_uri="https://example.com/stream.m3u8"
  media_type="auto"
  is_ptz_connected="true"
  is_ptz_panel_opened="true"
></hb-player-live-camera-ptz>
```

---

<a id="wc-product-comparison"></a>

## `hb-product-comparison` — product comparison

**Category:** commerce  
**Tags:** commerce, product

### What it does

Product comparison matrix: columns per product (model, description, promotion, price, purchase button) and rows per feature header with icons or text from each product’s characteristics. Supports preferred product and sale styling; dispatches `purchaseClick` with product id. Desktop table vs stacked mobile layout.

### Custom element

`hb-product-comparison`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `headers` (required): JSON string — `{ id; label }[]` feature rows.
- `products` (required): JSON string — `Product[]` (`id`, `model`, `price`, `characteristics` map, optional `description`, `note`, `promotion`, `columnColor`).
- `options` (required): JSON string — `Options` (`currency`, optional `preferredProductId`).

### Events

- `purchaseClick`: `{ id: string }` — product id for checkout handoff.

### Usage notes

- **CSS parts:** `container`, `col`, `row`.
- Characteristic values drive per-cell visuals (`valid`, `disabled`, `blocked`, etc. per examples in `extra/docs.ts`).

### Styling (Bulma)

Desktop matrix uses **Bulma** `container`, `columns` / `column`, `button is-primary`, and visibility helpers (`is-hidden-touch` / `is-hidden-desktop`) to swap layouts. Set **`--bulma-*`** on `:host` (see `extra/docs.ts`). **Bootstrap Icons** load from `<svelte:head>` for feature cell icons.

### Minimal HTML example

```html
<hb-product-comparison
  headers='[{"id":"f1","label":"Feature 1"}]'
  products='[{"id":"p1","model":"Basic","price":10,"characteristics":{"f1":"valid"}}]'
  options='{"currency":"€"}'
></hb-product-comparison>
```

---

<a id="wc-range-slider"></a>

## `hb-range-slider` — range slider

**Category:** inputs  
**Tags:** inputs, slider

### What it does

Dual-handle range slider mapping a min–max domain to thumb positions, with optional value bubbles and a third handle for a single marker position; emits `changeRangeValues` with real and percentage values on change.

### Custom element

`hb-range-slider`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `min`, `max` (optional): numbers as strings — domain bounds.
- `minval`, `maxval` (optional): numbers as strings — selected range endpoints.
- `position_value` (optional): number as string — marker handle value.
- `withbubbles` (optional): boolean string — show value bubbles.

### Events

- `changeRangeValues`: `{ minValue; maxValue; minPercent; maxPercent; positionPercent; positionValReal }`.

### Usage notes

- **CSS variables:** `--hb-slider-background-color`.
- **CSS parts:** `inverse`, `the-range`, `the-thumb`, `sign`.

### Minimal HTML example

```html
<hb-range-slider min="0" max="100" minval="20" maxval="80" withbubbles="true"></hb-range-slider>
```

---

<a id="wc-searchbar"></a>

## `hb-searchbar` — searchbar

**Category:** utilities  
**Tags:** utilities, search

### What it does

Search field with optional dropdown `searchlist` (id, text, icons, badges, tags, URLs). Configure `value`, `searchlabel`, `textarea`, `minlength`, `disable_preview`, `disabled`, and CSS parts for the input and menu. Dispatches `search` and `clear`.

### Custom element

`hb-searchbar`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `value` (required): string — current query text.
- `searchlabel` (optional): string — placeholder for the input (search is triggered by the in-field magnifier or Enter).
- `minlength` (optional): number as string.
- `searchlist` (optional): JSON string — `TSearchListItem[]` (`id`, `text`, optional `url`, `icon`, `tags`, `badge`, `number_of_results`, `fixed`).
- `input_info` (optional): JSON string — single `TSearchListItem` for input adornment.
- `textarea` (optional): `"yes"` | `"true"` | `""` — multiline input mode.
- `disable_preview` (optional): `"yes"` | `"no"` | `"true"` | `"false"` | `"on"` | `"off"`.
- `disabled` (optional): `"yes"` | `"no"` — when `"yes"`, the input/textarea and action buttons are disabled.

### Events

- `search`: `{ input: string; by: "button" | "input" | "searchlist" }`.
- `clear`: `{ id: string }`.

### Usage notes

- **Browser autofill:** the search field uses `autocomplete="off"` so native address/password suggestions and similar do not target this control (browser support varies; password managers may still offer fills).

- **CSS parts:** `dropdown-menu`, `search-input`, `search-input-glass` (frosted layer under the field when the input is focused), `search-submit` (magnifier button inside the field).
- **Styling:** Bulma `field` with a single expanded control; the search icon sits on the right as a `search-submit` control. Dropdown and field styles live in the shadow root (`styles/bulma.scss` + `webcomponent.scss`). Prefer [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) on the host or ancestors: e.g. `--bulma-primary` (focus glow, search-button hover, suggestion row accents), `--bulma-background`, `--bulma-border`, and `--bulma-primary` (host strip: default resting/focus tints on `hb-searchbar` itself; input/textarea are transparent at rest so that shows through), `--bulma-scheme-main`, `--bulma-border-weak`, `--bulma-text`, `--bulma-text-strong`, `--bulma-input-placeholder-color`, `--bulma-danger` (clear button), `--bulma-radius`, `--bulma-radius-small`, `--bulma-dropdown-content-z`. Component-only: `--hb-searchbar-host-background`, `--hb-searchbar-host-background-focus` (:host), `--hb-searchbar-input-strip-background` (darker input row at rest), `--hb-searchbar-dropdown-panel-background` (lighter list panel), `--hb-searchbar-input-glass-blur`, `--hb-searchbar-input-glass-saturate` (frosted layer on input focus only). The primary-colored diffuse glow while the input/textarea is focused wraps the whole root (including the open dropdown) as one outline.
- Storybook may list `initial_value`; runtime props follow `webcomponent.type.d.ts` (`value` is required).

### Minimal HTML example

```html
<hb-searchbar
  value=""
  searchlabel="Search"
  searchlist='[{"id":"1","text":"Suggestion"}]'
></hb-searchbar>
```

---

<a id="wc-shop-item-cell"></a>

## `hb-shop-item-cell` — shop item cell

**Category:** commerce  
**Tags:** commerce, product

### What it does

Vertical shop product card: top image with optional badge, then the same body as `hb-shop-item-row` (title, subtitle, text, stars, reviews, prices, footer) with **Bulma** `card`, `tag`, `title` / `subtitle`, and matching slots.

### Custom element

`hb-shop-item-cell`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `img`, `url`, `badge`, `title`, `subtitle`, `text`, `reviews`, `reviewsurl`, `price`, `regularprice`, `footer` (required in types): strings (use `""` when empty).
- `rating`, `ratingscale` (required): numbers as strings.

### Events

None declared.

### Styling (Bulma)

Bundles **Bulma 1.x** (`card`, `image`, `content`, `title`, `tag`, helpers). Set **`--bulma-*`** on the light DOM to match your theme. Star icons still use Bootstrap Icons SVG class names in markup (no icon font required for the default stars).

### Usage notes

- **Slots:** `badge`, `title`, `subtitle`, `text`, `reviews`, `price`, `footer`, `regularprice`.
- Mirror `hb-shop-item-row` content model for consistent catalog UI.

### Minimal HTML example

```html
<hb-shop-item-cell
  img="https://placehold.co/120"
  url="/p/1"
  badge=""
  title="Product"
  subtitle="Short line"
  text="Description"
  rating="4"
  ratingscale="5"
  reviews="12 reviews"
  reviewsurl="/p/1#reviews"
  price="€19"
  regularprice=""
  footer=""
></hb-shop-item-cell>
```

---

<a id="wc-shop-item-row"></a>

## `hb-shop-item-row` — shop item row

**Category:** commerce  
**Tags:** commerce, product

### What it does

Horizontal shop product card: image with optional badge, linked title and metadata, description, star rating scale with numeric rating and reviews link, current and strikethrough prices, and optional footer—all overridable via named slots.

### Custom element

`hb-shop-item-row`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `img`, `url`, `badge`, `title`, `subtitle`, `text`, `reviews`, `reviewsurl`, `price`, `regularprice`, `footer` (required in types): strings.
- `rating`, `ratingscale` (required): numbers as strings.

### Events

None declared.

### Styling (Bulma)

The component bundles cherry-picked Bulma 1 Sass modules scoped to `:host` (see `styles/bulma.scss`). Theme defaults are applied via Bulma’s light theme and `setup-theme`. Override appearance from the light DOM by setting public `--bulma-*` custom properties on `body` or `:root`; they inherit into the shadow root. Documented tokens include `--bulma-primary`, `--bulma-text`, `--bulma-card-background-color`, `--bulma-border`, and `--bulma-shadow` (see `extra/docs.ts`).

### Usage notes

- **Slots:** `badge`, `title`, `subtitle`, `text`, `reviews`, `price`, `footer`, `regularprice`.
- Storybook exposes `action` for demos only; it is not on the `Component` type.

### Minimal HTML example

```html
<hb-shop-item-row
  img="https://placehold.co/96"
  url="/p/1"
  badge="New"
  title="Product"
  subtitle="Vendor"
  text="One line pitch."
  rating="5"
  ratingscale="5"
  reviews="3"
  reviewsurl="/p/1#reviews"
  price="€9"
  regularprice="€12"
  footer=""
></hb-shop-item-row>
```

---

<a id="wc-sidebar-cards-navigator"></a>

## `hb-sidebar-cards-navigator` — sidebar cards navigator

**Category:** layout  
**Tags:** layout, navigation

### What it does

Stacked sidebar navigator: picks an active panel from JSON `panels` (main or first without parent), shows `hb-navbar` with back when `parentPanelId` exists, then cards of rows rendered as `hb-sidenav-button`. Emits `itemClick` with panel, card and row context; rows can switch panels via `switchToPanelId`.

### Custom element

`hb-sidebar-cards-navigator`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `panels` (optional): JSON string — `Panel[]` (`id`, optional `title`, `parentPanelId`, `cards` with `rows` of `CardRow`: `key`, `text`, optional `bootstrapIcon`, `switchToPanelId`, `type`, `badge`, etc.).

### Events

- `itemClick`: detail matches selected row context (panel, card, row, `id`) as built in `component.wc.svelte` — see types `CardRowSelected` in `webcomponent.type.d.ts`.

### Usage notes

- **Slots:** `skelcontent`.
- **CSS parts:** `testpart`.
- Type file lists a nested `event.itemClick` shape; the element dispatches the event name `itemClick` at the top level.

### Minimal HTML example

```html
<hb-sidebar-cards-navigator
  panels='[{"id":"1","title":"Home","cards":[{"id":"c1","rows":[{"key":"a","text":"Item","bootstrapIcon":"house-door"}]}]}]'
></hb-sidebar-cards-navigator>
```

---

<a id="wc-sidebar-desktop"></a>

## `hb-sidebar-desktop` — sidebar desktop

**Category:** layout  
**Tags:** layout, navigation

### What it does

Fixed-width desktop sidebar: optional company logo and title, header/footer slots, and a vertical nav list built from `hb-sidenav-link` entries with optional JSON groups. Uses Bulma (flex, spacing, `title`, `menu-label`, `has-background-light`). Parses `navlinks` and `groups` from strings; emits `pageChange` when a link selects a page.

### Custom element

`hb-sidebar-desktop`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `companylogouri`, `companytitle` (optional): strings.
- `groups` (optional): JSON string — `{ key; label }[]`.
- `enablefooter` (optional): boolean string.
- `navpage` (optional): string — active page key.
- `navlinks` (optional): JSON string — `INavLink[]` for `hb-sidenav-link` (see **Navigation icons** below).
- `cookielawallowdecline`, `cookielawlanguage`, `cookielawuri4more` (optional): strings for cookie banner integration.
- `single_screen` (optional): `"yes"` | `"no"` | empty — layout mode flag.

### Events

- `pageChange`: `{ page: string }`.

### Navigation icons (Bootstrap Icons)

Each entry in `navlinks` (and each item in `subLinks`, if any) may include an optional string property `icon`. Icons use the [Bootstrap Icons](https://icons.getbootstrap.com/) web font; this component loads `bootstrap-icons.css` for the nested `hb-sidenav-link` elements.

**What value to pass:** pass only the **icon name** (the suffix of the official class), not the full class list.

- On the Bootstrap Icons site, an icon is used as `<i class="bi bi-house-door"></i>`. In `navlinks` JSON, set `"icon": "house-door"`.
- Do **not** prefix with `bi` or `bi-`, and do **not** pass a full class string like `bi bi-house-door`. The child link renders `class="bi bi-{icon}"`; extra prefixes would break the class name.

**HTML example** (attribute must be a JSON string):

```html
navlinks='[{"label":"Home","key":"home","icon":"house-door"},{"label":"Settings","key":"settings","icon":"gear"}]'
```

**JavaScript** (property can be an array of objects):

```js
el.navlinks = [
  { label: "Home", key: "home", icon: "house-door" },
  { label: "Settings", key: "settings", icon: "gear" },
];
```

Grouped links and expandable rows use the same `icon` field on each object.

### Usage notes

- **Slots:** `test`, `header`, `footer`.
- **CSS parts:** `header`.
- Matches the navigation model used inside `hb-offcanvas` (same `navlinks` / `icon` rules).

### Minimal HTML example

```html
<hb-sidebar-desktop
  companytitle="Acme"
  navpage="home"
  navlinks='[{"label":"Home","key":"home","icon":"house-door"}]'
></hb-sidebar-desktop>
```

---

<a id="wc-sidenav-button"></a>

## `hb-sidenav-button` — sidenav button

**Category:** layout  
**Tags:** layout, navigation

### What it does

Compact sidebar row as a nav button: optional Bootstrap Icons (`bi-*`) via `bootstrapIcon`, Bulma `tag` badge (optional `badge.class` / `badge.classcolor` modifiers), or visual types (`switch`, `checkbox`, `radio`) from `navlink` JSON; dispatches `pageChange` with the row `key` on click. Used by `hb-sidebar-cards-navigator` and similar stacked menus.

### Custom element

`hb-sidenav-button`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `navlink` (required): JSON string — `INavLink` (`key`, `text`, optional `bootstrapIcon`, `badge`, `value`, `type`, `selected`).

### Events

- `pageChange`: `{ page: string }` — typically the link `key`.

### Usage notes

- **CSS parts:** `li`.
- Styling uses Bulma inside the shadow root (buttons and tags); theme CSS variables follow Bulma’s scheme (e.g. `--bulma-link`).
- Include [Bootstrap Icons](https://icons.getbootstrap.com/) if you use `bootstrapIcon` or the switch/checkbox/radio icons.
- Storybook `nav_type` is a control helper; the shape lives on `navlink.type`.

### Minimal HTML example

```html
<hb-sidenav-button
  navlink='{"text":"Home","key":"home","bootstrapIcon":"house-door"}'
></hb-sidenav-button>
```

---

<a id="wc-sidenav-link"></a>

## `hb-sidenav-link` — sidenav link

**Category:** layout  
**Tags:** layout, navigation

### What it does

Sidebar nav item: Bootstrap Icons (`bi-*`), label, optional Bulma `tag` badge (`badge.class` / `badge.classcolor` modifiers such as `is-light`, `is-primary`) rendered as **outlined** pills (transparent fill, border/text from the tag color), and either a flat button that dispatches `pageChange` on click or an expandable group of `subLinks` with active state when `navpage` or `selected` matches. Intended for use inside `hb-sidebar-desktop` lists.

### Custom element

`hb-sidenav-link`

### Attributes (snake_case; use string values in HTML)

- `id`, `style` (optional): strings.
- `navlink` (required): JSON string — `INavLink` (`label`, `key`, optional `icon`, `group`, `badge`, `subLinks`, `active`, `open`).
- `navpage` (optional): string — current app page key for active styling.
- `selected` (optional): boolean string — force selected appearance.

### Events

- `pageChange`: `{ page: string }`.

### Usage notes

- **CSS parts:** `li`.
- **Layout:** labels share a flexible middle column; the right column is fixed width (`--hb-sidenav-trail-width`, default `3.5rem`) so titles stay aligned whether a badge or chevron is present. Long badge text truncates with an ellipsis. Badges use an outline treatment so they stay visible on ghost (unselected) rows.
- Bulma buttons and tags are scoped inside the component; include Bootstrap Icons CSS for `icon` / `subLinks[].icon`.
- Export type `INavLink` is shared with `hb-offcanvas` / `hb-sidebar-desktop` `navlinks` arrays.

### Minimal HTML example

```html
<hb-sidenav-link
  navpage="home"
  navlink='{"label":"Home","key":"home","icon":"house-door"}'
></hb-sidenav-link>
```

---

<a id="wc-site-contacts-row"></a>

## `hb-site-contacts-row` — site-contacts-row

**Category:** content  
**Tags:** content, contact

### What it does

Contact strip for addresses (with optional `latLng`), phones, emails, websites, and `availability` (times, appointment flag). `model` `big` / `small` or omit for auto layouts that adapt to which fields you pass.

### Custom element

`hb-site-contacts-row`

### Attributes (snake_case; use string values in HTML)

- `id` (optional): string.
- `style` (optional): string (inline style).
- `availability` (optional): JSON string — `{ icon?, times: string[], title?, appointment? }`.
- `addresses` (optional): JSON string — `{ icon?, addresses: Address[], title? }` (`Address`: `address`, optional `latLng`, `link`, `name`).
- `phones` (optional): JSON string — `{ icon?, phones: { name?, number }[], title? }`.
- `emails` (optional): JSON string — `{ icon?, emails: { label?, address, name? }[], title? }`.
- `websites` (optional): JSON string — `{ icon?, websites: { label?, url, name? }[], title? }`.
- `model` (optional): `"big"` | `"small"`.

### Events

- `event`: `{ test: boolean }` (integration hook per typings).

### Usage notes

- No named slots in `extra/docs.ts`. Pass complex blocks as JSON attributes or bind after custom element upgrade.

### Minimal HTML example

```html
<hb-site-contacts-row
  model="small"
  emails='{"emails":[{"label":"Info","address":"info@example.com","name":"main"}]}'
></hb-site-contacts-row>
```

---

<a id="wc-site-paragraph-with-image"></a>

## `hb-site-paragraph-with-image` — site-paragraph-with-image

**Category:** content  
**Tags:** content

### What it does

Marketing block pairing an image (`img`: `src`, optional `alt`) with rich text (`text`: optional `title`, `body`, optional `link` with `label` and optional `src`, `key`, colors). Use `text_side` (`left` / `right`) and `half_space` for layout; CSS parts cover mobile and desktop. CTA uses a **Bulma** `button is-primary` (custom link colors still applied inline). Fires `elClick` when the link is activated.

### Custom element

`hb-site-paragraph-with-image`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `img` (required): JSON string — `{ src: string; alt?: string }`.
- `text` (required): JSON string — `{ title?, body?, link?: { label; src?; key?; bgColor?; textColor? } }`.
- `text_side` (optional): `"left"` | `"right"`.
- `half_space` (optional): boolean as string when used from HTML.

### Events

- `elClick`: `{ key: string }`.

### Usage notes

- **CSS parts:** `mobile_text_content`, `mobile_title`, `mobile_text_body`, `mobile_link_button`, `mobile_image_content`, `image_content`, `text_content`, `link_button`, `title`, `text_body`.
- No `htmlSlots` in docs; structure is prop-driven.

### Minimal HTML example

```html
<hb-site-paragraph-with-image
  img='{"src":"https://example.com/image.png","alt":"Logo"}'
  text='{"title":"Heading","body":"Short copy.","link":{"label":"Read more"}}'
  text_side="right"
></hb-site-paragraph-with-image>
```

---

<a id="wc-site-slideshow"></a>

## `hb-site-slideshow` — site-slideshow

**Category:** content  
**Tags:** content, media

### What it does

Full-viewport image slideshow: pass `data` as an array of slides (`href`, optional `caption`). Supports optional `index` and `timer`, dots and captions via CSS parts, and slots `overlay`, `prev`, `next`, `cover_on_images`. Dispatches slide change and hover events.

### Custom element

`hb-site-slideshow`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `data` (required): JSON string — `{ href: string; caption?; index? }[]`.
- `index` (optional): number as string — initial slide.
- `timer` (optional): number as string — autoplay interval.

### Events

- `changeSlide`: `{ index: number }`.
- `changeHover`: `{ index: number; hover: boolean }`.

### Usage notes

- **CSS parts:** `dot`, `caption_container`, `caption_content`, `cover_on_images`.
- **Slots:** `overlay`, `prev`, `next`, `cover_on_images`.
- Declared **size** metadata: fullscreen layout.

### Minimal HTML example

```html
<hb-site-slideshow
  data='[{"href":"https://example.com/a.jpg","caption":"A"},{"href":"https://example.com/b.jpg","caption":"B"}]'
  index="0"
></hb-site-slideshow>
```

---

<a id="wc-site-slideshow-horizontal"></a>

## `hb-site-slideshow-horizontal` — site-slideshow-horizontal

**Category:** content  
**Tags:** content, media

### What it does

Horizontal media strip: `data` lists slides with `href`, `caption`, and optional `link`, `externalLink`, `key`, or `duration` for video-style rows. Set `type` to `videos` for that layout; optional `slide` index and `size`. Emits `slideClick` when a slide is activated.

### Custom element

`hb-site-slideshow-horizontal`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `data` (required): JSON string — array of `{ href; caption?; externalLink?; link?; key?; duration?; index? }`.
- `type` (optional): `"images"` | `"videos"`.
- `slide` (optional): number as string (current slide).
- `size` (optional): number as string.

### Events

- `slideClick`: `{ key: string }`.

### Usage notes

- **CSS parts:** `video_sub_title`, `caption_content` (see `extra/docs.ts` for full list).

### Minimal HTML example

```html
<hb-site-slideshow-horizontal
  data='[{"href":"https://placehold.co/600x400","caption":"Slide 1"},{"href":"https://placehold.co/600x401","caption":"Slide 2"}]'
></hb-site-slideshow-horizontal>
```

---

<a id="wc-skeleton-component"></a>

## `hb-skeleton-component` — skeleton-component

**Category:** data  
**Tags:** data, loading

### What it does

Development scaffold: accepts arbitrary `json`, `string`, and `boolean` props to test bindings, exposes a `skelcontent` slot and a `testpart` CSS part, and emits a generic `event` for wiring demos.

### Custom element

`hb-skeleton-component`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `json` (optional): JSON string — any JSON-serializable value.
- `string` (required per typings): string.
- `boolean` (optional): boolean as string when used from HTML.

### Events

- `event`: `{ test: boolean }`.

### Styling (Bulma)

Bundles **Bulma 1.x** (`button`, `base/skeleton`, animations) in the shadow root. Set **`--bulma-*`** on `body` / `:root` to align with your app.

### Usage notes

- **Slot:** `skelcontent`.
- **CSS part:** `testpart`.

### Minimal HTML example

```html
<hb-skeleton-component string="demo" json='{"a":0}' boolean="no"></hb-skeleton-component>
```

---

<a id="wc-stylus-notebook"></a>

## `hb-stylus-notebook` — stylus-notebook

**Category:** inputs  
**Tags:** inputs, drawing

### What it does

Notebook-sized stylus canvas: optional `load_draw` restores saved stroke JSON; `save` configures persistence target (`name`, `type`: pdf/json/png/svg/jpg); `debug` toggles diagnostics (`yes` / `no`). Same `skelcontent` slot and `testpart` CSS part as the skeleton dev component; emits `event` on user actions.

### Custom element

`hb-stylus-notebook`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `load_draw` (optional): JSON string — saved draw payload (`type`, `draw`, `id`, `draw_id`, `name`, `version`).
- `save` (optional): JSON string — `{ name: string; type: "pdf" | "json" | "png" | "svg" | "jpg" }`.
- `debug` (optional): `"yes"` | `"no"`.

### Events

- `event`: `{ test: boolean }`.

### Usage notes

- **Slot:** `skelcontent`.
- **CSS part:** `testpart`.
- Declared **size** metadata: fullscreen layout.

### Minimal HTML example

```html
<hb-stylus-notebook debug="no"></hb-stylus-notebook>
```

---

<a id="wc-stylus-paper"></a>

## `hb-stylus-paper` — stylus-paper

**Category:** inputs  
**Tags:** inputs, drawing

### What it does

Freehand drawing surface with modes (`draw`, `eraser`, `select`), brush `options`, `background_color` / `pen_color` / `pen_opacity`, and optional `load_draw`, `insert_image`, or `insert_text`. Supports `save_as`, paper `size`, `view` (zoom/pan locks), `goto` page index, and rich events for strokes, selection, history, save, and asset load.

### Custom element

`hb-stylus-paper`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional), `draw_id` (optional): strings.
- `background_color`, `pen_color` (optional): strings (CSS colors).
- `pen_opacity` (optional): number as string.
- `mode` (optional): `"eraser"` | `"draw"` | `"select"`.
- `debug` (optional): `"yes"` | `"no"`.
- `options` (optional): JSON string — brush options (`size`, `thinning`, `smoothing`, `streamline`, `simulatePressure`, etc.).
- `load_draw` (optional): JSON string — full save document with `draw`, `size.paperSize`, ids, version.
- `save_as` (optional): JSON string — `{ name; type: TSaveType }`.
- `insert_image` (optional): JSON string — `{ name; type; uri?; base64? }`.
- `insert_text` (optional): JSON string — `{ name; content }`.
- `size` (optional): JSON string — paper dimensions / `paperSize` enum.
- `view` (optional): JSON string — `{ lockPan; lockZoom; zoom; pan }`.
- `goto` (optional): number as string.

### Events

- `beginStroke`, `startStroke`, `endStroke`: stroke lifecycle with ids, timestamps, geometry, and `draw_id`.
- `selection`: bounding box and selected strokes.
- `historyIndex`, `changeIndex`: undo/redo index changes.
- `save`: full `TSave` payload.
- `drawLoaded`, `imageLoaded`, `txtLoaded`: load outcomes.

### Usage notes

- No slots or CSS parts in `extra/docs.ts` for this component.
- Declared **size** metadata: fullscreen layout.

### Minimal HTML example

```html
<hb-stylus-paper mode="draw" pen_color="rgb(0,0,0)" debug="no"></hb-stylus-paper>
```

---

<a id="wc-table"></a>

## `hb-table` — table

**Category:** data  
**Tags:** data, table

### What it does

Bulma-styled data table driven by JSON `headers` and `rows` (`_id` required): column sort, header search (text, enum, date range), formatted values (nested keys, datetime via dayjs), copy-to-clipboard, row highlight and `selectrow` clicks. Global `actions` and per-row `_actions` can open confirm or schema dialogs (`hb-dialog` / `hb-dialogform`). Optional multi-select with `selectactions`, `add_item` slot, and `hb-paginate` for page size, sort sync, and server-style `externalfilter` / `total` workflows.

While **`is_loading`** is enabled, the tbody shows **Bulma skeleton** rows (`skeleton-lines`, **`checkbox.is-skeleton`**, **`button.is-skeleton`**; count follows **`size`**, capped at 100). **`hb-paginate`** stays mounted but is hidden; a single **`skeleton-block`** covers the pagination area so **`page` / `pages`** stay in sync. Optional on the host: **`--hb-table-sk-pagination-height`**, **`--hb-table-sk-pagination-min-width`** (default `min(28rem, 100%)`), **`--hb-table-sk-pagination-offset-inline-end`** (extra end margin while loading, nudges skeleton inward; default `0.65rem`). i18n via `i18nlang`.

### Custom element

`hb-table`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `rows` (required): JSON string — row objects with `_id` and column keys; optional `_actions`, `_evidenced`.
- `headers` (required): JSON string — `ITableHeader[]` (`label`, `key`, optional `type`, `format`, `search`, `click`, `select`, `nosort`, `sortBy`, `truncateAt`, `copyTxt`, `tooltip`).
- `actions` (optional): JSON string — global row `IActionButton[]` (see **Actions** below).
- `selectactions` (optional): JSON string — toolbar buttons when multi-select is enabled (different shape from `actions`; see **Multi-select**).
- `selectrow`, `enableselect`, `selected` (optional): strings (selection mode / ids).
- `size`, `page`, `pages`, `total` (optional): numbers as strings for pagination / server totals.
- `externalfilter` (optional): boolean string — host-driven filters.
- `disablepagination` (optional): boolean string.
- `add_item` (optional): boolean string — show the **Add** button (see **Add button** below).
- `i18nlang` (optional): string (`it`, `en`, … per registered i18n).
- `page_size_type` (optional): `"number"` | `"select"`.
- `page_size_options` (optional): comma-separated sizes, e.g. `"10,25,50,100"`.
- `sort_default` (optional): string — column key for initial sort.
- `sort_default_label` (optional): string — label for default sort option.
- `disable_paginate_sort` (optional): boolean string.
- `sort_strict_direction` (optional): boolean string.
- `sort_direction` (optional): string — current sort direction.
- **`is_loading` (optional):** boolean string (`"yes"` / `"true"`) or boolean in frameworks — Bulma skeleton rows in the tbody (row count = `size`) and one **`skeleton-block`** over hidden **`hb-paginate`**.
- **`fixed_columns` (optional):** `"yes"` or `"no"` (default `"no"`). When `"yes"`, columns use `table-layout: fixed` with equal widths and text overflow is handled with ellipsis. When `"no"`, columns size dynamically based on content (`table-layout: auto`).

### Actions (`actions` and `_actions`)

Use **`actions`** for a column of buttons that is the same for every row (one set per row, same definitions). Use **`_actions`** on a single row object for buttons only on that row (e.g. variable actions per record). Both use the same **`IActionButton`** shape.

Pass **`actions`** / per-row **`_actions`** as JSON (HTML attribute string or parsed array in JS). Each entry can drive a **text** or **icon** button; icon buttons use [Bootstrap Icons](https://icons.getbootstrap.com/) and optional **`btnClass`** for Bulma-coloured hosts (see below).

| Field | Purpose |
| --- | --- |
| `name` | Stable id for the action; emitted in events as `action`. |
| `type` | `"text"` — show `iconOrText` as the button label; `"icon"` — show a Bootstrap Icon (see **Action icons (Bootstrap Icons)**). |
| `iconOrText` | If `type: "text"`, the visible label. If `type: "icon"`, the icon glyph name only (see **Action icons (Bootstrap Icons)**). |
| `btnClass` | Optional colour/style token (see **Button colours (`btnClass`)**). If omitted, the button is **`is-link`** — **outlined** unless `btnFill` is true. |
| `btnFill` | Boolean; when `true` the button is **filled**. When `btnClass` is omitted, default is **`is-link is-outlined`**. For explicit **ghost** / **light** tokens, outlined is not applied. |
| `disabled` | If true, the control is disabled. |
| `confirm` | If set, clicking opens **`hb-dialog`** confirm; on confirm the table emits `tableaction` / related confirm events. |
| `edit` | If set (and no `confirm`), clicking opens **`hb-dialogform`** with the given `schema`. |
| `tooltip` | Optional; passed to **`hb-tooltip`** for icon buttons. |

**Behaviour without `confirm` / `edit`:** the table dispatches **`tableaction`** with `{ itemId, action }` where `action` is the button `name`. For **`_actions`** on a row, the same flow applies but the event **`tableCustomActionClick`** is also fired with `{ itemId, action }` so you can distinguish custom per-row actions if needed.

#### Action icons (Bootstrap Icons)

For `type: "icon"`, set **`iconOrText`** to the **glyph name** from Bootstrap Icons: the segment that appears **after** `bi-` in the official class name.

- Docs show `<i class="bi bi-pencil"></i>` → use `"iconOrText": "pencil"`.
- For hyphenated names (e.g. `house-door`) use the full slug: `"house-door"`.
- Do **not** repeat the `bi-` prefix in the value (use `"pencil"`, not `"bi-pencil"`). The table renders `<i class="bi-{iconOrText}"></i>` (e.g. `class="bi-pencil"`).

**Global `actions` (HTML):**

```html
actions='[{"name":"edit","type":"icon","iconOrText":"pencil","btnClass":"primary"}]'
```

**Per-row `_actions` inside `rows`:**

```json
{
  "_id": "1",
  "name": "Alice",
  "_actions": [
    { "name": "preview", "type": "icon", "iconOrText": "eye", "btnClass": "info" },
    { "name": "remove", "type": "icon", "iconOrText": "trash", "btnClass": "danger" }
  ]
}
```

The component loads Bootstrap Icons CSS via `<svelte:head>` so the font is available for those `<i>` elements.

#### Button colours (`btnClass`)

The table maps **`btnClass`** to **Bulma** `button` modifiers on the hosting control (not literal Bootstrap `btn btn-*` classes in the DOM).

| You pass (`btnClass`) | Button classes applied |
| --- | --- |
| `primary` | `button is-primary` |
| `secondary` | `button is-light` |
| `success` | `button is-success` |
| `danger` | `button is-danger` |
| `warning` | `button is-warning` |
| `info` | `button is-info` |
| `light` | `button is-light` |
| `dark` | `button is-dark` |
| `link` | `button is-link` (outlined when not `btnFill`, like other colours) |

Matching is case-insensitive; an optional `btn-` prefix is stripped (e.g. `btn-danger` and `danger` are equivalent). If **`btnClass` is omitted**, actions use **`button is-link is-outlined`**; with **`btnFill: true`**, **`button is-link`**. By default all colour buttons (except **ghost** and **light**) are **outlined** (`is-outlined`); set **`btnFill: true`** for a filled button.

**Legacy:** if you pass a string that already starts with `button ` (e.g. `button is-warning`), it is used as-is. Strings like `btn btn-danger` are normalised to the same mapping as `danger`.

**Example (icons + colours):**

```html
<hb-table
  headers='[{"label":"Name","key":"name"},{"label":"Tools","key":"x","type":"actions","nosort":true}]'
  rows='[{"_id":"1","name":"Alice","_actions":[{"name":"star","type":"icon","iconOrText":"star","btnClass":"warning"}]}]'
  actions='[
    {"name":"edit","type":"icon","iconOrText":"pencil","btnClass":"primary"},
    {"name":"delete","type":"icon","iconOrText":"trash","btnClass":"danger"}
  ]'
></hb-table>
```

### Multi-select (`enableselect`, `selectactions`)

- Set **`enableselect`** to `"yes"` / `"true"` and pass **`selectactions`**: an array of `{ name, type, iconOrText }` used for bulk actions on checked rows. **`actiononselected`** fires with `{ key: name, selectedItems }`.
- Row checkboxes appear only when **`selectactions`** has entries.

### Add button (`add_item`)

Set **`add_item`** to `"yes"` / `"true"` (or boolean `true` in frameworks) to show an **Add** control in the toolbar below the table (`part="table-actions"`): it is placed **right after the multi-select settings (gear) button** when **`selectactions`** is set; if there is no gear, it is the first control in that strip. Toolbar controls use the same Bulma **`pagination-link`** styling as **`hb-paginate`**. The gear uses **`is-current`** when multi-select mode is on; the **Add** control uses **`is-current`** when visible so its colors match the **current page** link in **`hb-paginate`** (Bulma pagination selected / **`--bulma-link`** chain). It is meant to let the user start creating a **new row**; the table does not insert data by itself.

- **Visibility:** the button is rendered only when **`enableselect`** is *not* active (multi-select gear mode hides it).
- **Click:** dispatches the **`addItem`** custom event with payload **`{ id }`**, where **`id`** is the table’s own **`id`** attribute (empty string if unset). The host should listen for `addItem` and open a form, navigate to a create page, call an API, etc.
- **Label / icon:** default content is a Bootstrap **plus** icon (`bi-plus`). Override with the **`add-button-content`** slot if you need text or a different icon.

```html
<hb-table
  id="my-list"
  add_item="yes"
  headers='[{"label":"Title","key":"title"}]'
  rows='[{"_id":"1","title":"A"}]'
></hb-table>
<script>
  document.querySelector("hb-table").addEventListener("addItem", (e) => {
    console.log("Create new item for table:", e.detail.id); // "my-list"
  });
</script>
```

### Events

- `pageChange`: `{ page; pages }`.
- `changePageSize`: `{ page_size: number }`.
- `removeFilter`: `{ key: string }`.
- `changeFilter`: `{ filter: IFilter }`.
- `tableCustomActionClick` / `tableaction`: `{ itemId; action }`.
- `cellclick`: `{ rowId; cellId }`.
- `actiononselected`: `{ key; selectedItems: string[] }`.
- `clickonrow`: `{ itemId }`.
- `changeSort`: `{ sortedBy; sortedDirection }`.
- `showConfirmModal` / `showConfirmModalForm`: modal visibility payloads with `action` and `detail: { id; show }`.
- `confirmActionModal` / `confirmActionModalForm`: `{ action; id; confirm }`.
- `clipboardCopyText`: `{ text: string }`.
- **`addItem`:** `{ id: string }` — fired when the **Add** button is clicked; `id` is the table `id` attribute (see **Add button**).

### Usage notes

- **Slots:** `add-button-content` (Add button body), `buttons-container` (extra toolbar content).
- **CSS parts:** `table`, `table-actions`, `selected-row`, `common-row`.
- **Toolbar order:** **settings** (gear) → **Add** (when `add_item` and not in multi-select mode) → bulk **select actions** (when enabled) → **`buttons-container`** slot → **`hb-paginate`** (inline-end). The first **`nav.pagination.is-small`** group uses **`margin-inline-start`** from **`--hb-table-toolbar-settings-margin-inline-start`** (default `--bulma-block-spacing`). Optional **`--hb-paginate-list-gap`** on the host also applies between toolbar **`pagination-link`** items, matching **`hb-paginate`**.
- **i18n:** Italian and English in docs metadata; set `i18nlang` accordingly.
- **`hb-paginate`:** embedded when pagination is enabled; while **`is_loading`**, it stays in the DOM (hidden) under the skeleton overlay so props stay aligned — user interaction is blocked until loading ends.
- **Pagination while loading:** `is_loading` does not recalculate `page` / `pages` by itself. With **client-side** pagination, if you clear `rows` during a refresh, the `$effect` that derives `pages` from row count does not run on an empty list, so **`pages` can stay at the previous value** until new rows arrive — keep `page`, `pages`, and `total` aligned with your API if needed.
- See `extra/docs.ts` for Storybook-style examples.

### Bulma light / dark theme

The shadow root sets Bulma’s palette on `:host`. **Dark mode** follows `prefers-color-scheme: dark`. To **force** a palette when that does not match your app shell, set **`data-theme`** or **`.theme-dark` / `.theme-light`** on **`html` or `body`** (not only an inner layout node — inner `data-theme` is ignored so wrappers do not lock the table to light), or set **`data-theme`** on **`hb-table`** itself. Otherwise the host can keep the light-only `--bulma-*` set and **filled** / default **`is-light`** actions look wrong in real dark UIs. Action icons in cells use **`color: inherit`** so they match the button’s Bulma foreground in both themes.

### Minimal HTML example

```html
<hb-table
  headers='[{"label":"Title","key":"title","type":"string"},{"label":"When","key":"time","type":"datetime"}]'
  rows='[{"_id":"1","title":"Row A","time":"2024-01-01T12:00:00.000Z"}]'
  page="1"
  pages="1"
></hb-table>
```

### Loading example

```html
<hb-table
  is_loading="yes"
  size="10"
  headers='[{"label":"Title","key":"title"}]'
  rows='[]'
  total="0"
  page="0"
  pages="0"
></hb-table>
```

### Actions — handling clicks

Use the **`actions`** / **`_actions`** JSON shape and icon / `btnClass` rules in the **Actions** section above. Listen for **`tableaction`** with `{ itemId, action }`; for per-row **`_actions`**, **`tableCustomActionClick`** is also emitted if you need to separate custom row tools from the global column.

---

<a id="wc-terms-doc-templates"></a>

## `hb-terms-doc-templates` — terms-doc-templates

**Category:** content  
**Tags:** content, compliance

### What it does

Renders legal-style documents from `data`: privacy templates with site, company, admin, and collected-data fields, or cookie policies with a `cookies` list. Use `i18nlang` with registered languages (`it`, `en`) for localized copy; emits `event` for integrations. Includes `skelcontent` slot and `testpart` CSS part (scaffold-style hooks).

### Custom element

`hb-terms-doc-templates`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `i18nlang` (optional): string — e.g. `it`, `en`.
- `data` (required): JSON string — `ITPrivacy` or `CookieContent` shape (see `types/webcomponent.type.d.ts`).

### Events

- `event`: `{ test: boolean }`.

### Usage notes

- **Slot:** `skelcontent`.
- **CSS part:** `testpart`.
- Large **`data`** payloads should be JSON strings in HTML.

### Minimal HTML example

```html
<hb-terms-doc-templates
  i18nlang="en"
  data='{"id":"cookie-doc-english","site":{"name":"Example","url":"https://example.com","privacyPolicyUri":"https://example.com/privacy","cookiePolicyUri":"https://example.com/cookies"},"company":{"name":"Co","address":"1 St"},"cookies":[]}'
></hb-terms-doc-templates>
```

---

<a id="wc-toast"></a>

## `hb-toast` — toast

**Category:** overlays  
**Tags:** overlays, notifications

### What it does

Bulma-styled notification toast: `show` (`yes` / `no`), `title`, `content`, optional `img`, `small`, `level`, `position`, `timeout`, string `progress` for a progress bar, and `buttons` for actions. Slots customize header and body; dispatches visibility and button `action` events. Theme uses Bulma variables on `:host`.

### Custom element

`hb-toast`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `show` (required): `"yes"` | `"no"`.
- `title` (required), `content` (required), `img` (required per typings): strings (`img` may be URL or data URI).
- `small` (optional): string (e.g. timestamp line).
- `level` (optional): `"primary"` | `"secondary"` | `"success"` | `"danger"` | `"warning"` | `"info"` | `"light"` | `"dark"`.
- `position` (optional): `"top-left"` | `"top-center"` | `"top-right"` | `"bottom-left"` | `"bottom-center"` | `"bottom-right"`.
- `timeout` (optional): number or string — auto-hide ms.
- `progress` (optional): string — progress bar value/label semantics per Storybook.
- `buttons` (optional): JSON string — `TToastButton[]` (`type` confirm/cancel, optional `action`, `text`, `icon`, colors).

### Events

- `changeVisibility`: `{ id: string; show: boolean; disappear?: boolean }`.
- `action`: `{ id: string; action?: string }`.

### Usage notes

- **Slots:** `header_icon` (top-left badge), `header_strong`, `header_small` (overrides the status chip under the title), `body`.
- **CSS parts:** `toast` (root), `status` (chip row for time / percentage / timeout).
- **Theming:** Bulma Sass is forwarded from `styles/bulma.scss`; override `--bulma-*` on the host or document root as needed. The `level` attribute maps to Bulma `notification` tints (`is-*` + `is-light`, except `light` which uses the palette’s light variant).

### Minimal HTML example

```html
<hb-toast
  show="yes"
  title="Notice"
  content="Hello, world!"
  img="https://via.placeholder.com/64"
  level="primary"
></hb-toast>
```

---

<a id="wc-tooltip"></a>

## `hb-tooltip` — tooltip

**Category:** overlays  
**Tags:** overlays, tooltip

### What it does

Wrapper that adds a Bootstrap tooltip around slotted content. Configure via `tooltip` object: `title`, optional `description`, `placement`, `html`, `delay`, `trigger`, `style`, `maxWidth`, etc. Optional `show` can drive visibility; emits `visualizationChange` when the tooltip opens or closes.

### Custom element

`hb-tooltip`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `tooltip` (optional): JSON string — `TTooltip` (`title`, `description?`, `placement?`, `html?`, `animation?`, `delay?`, `trigger?`, `customClass?`, `offset?`, `style?`, `maxWidth?`, `maxHeight?`) or plain string title per typings.
- `show` (optional): boolean as string when used from HTML.

### Events

- `visualizationChange`: `{ id: string; show: boolean }`.

### Usage notes

- **Slot:** `default` — element(s) to wrap with the tooltip.

### Minimal HTML example

```html
<hb-tooltip tooltip='{"title":"Help text","placement":"bottom"}'>
  <button type="button">Hover me</button>
</hb-tooltip>
```

---

<a id="wc-uploader"></a>

## `hb-uploader` — uploader

**Category:** utilities  
**Tags:** utilities, files

### What it does

Upload progress UI driven by `fetch_data` (`url`, `data`, optional `method`, `headers`): wraps `hb-dialog`, shows an indeterminate **Bulma** `progress` bar while starting, then fills `progress` from streamed upload bytes. Optional `upload_id` identifies the nested dialog; `title` slot labels the dialog. Forwards dialog `modalShow` and emits `uploadComplete` / `uploadError` when the request finishes or fails.

### Custom element

`hb-uploader`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `upload_id` (optional): string — dialog id (defaults from `id` + `_dialog` in component).
- `fetch_data` (optional): JSON string — `{ url: string; data: any; method?; headers? }`.

### Events

- `uploadError`: `{ completed: boolean; id: string; error: Error }`.
- `uploadComplete`: `{ completed: boolean; id: string }`.
- `modalShow`: forwarded from `hb-dialog` — `{ id: string; show: boolean }` (see dialog typings).

### Usage notes

- **Slot:** `title` — dialog title (default “Uploading”).
- Storybook arg names may say “download”; runtime events are **`uploadError`** / **`uploadComplete`**.
- **CSS vars** in docs reference Bulma semantic colors (`--bulma-*`) for progress and labels.

### Minimal HTML example

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

---

<a id="wc-vertical-img-txt-archive"></a>

## `hb-vertical-img-txt-archive` — vertical-img-txt-archive

**Category:** content  
**Tags:** content, archive

### What it does

Vertical archive grid: `collection` items with `title`, `text`, `image`, and `link` (`type`: `tab` | `page` | `event`, `uri`). Optional `subtitle` on items; optional `size` sets column count. CSS parts style `container`, `item`, `image`, `title`, and `text`. Emits `collectionItemClick` with the item `uri` when an entry is activated.

### Custom element

`hb-vertical-img-txt-archive`

### Attributes (snake_case; use string values in HTML)

- `id` (optional), `style` (optional): strings.
- `collection` (required): JSON string — `Item[]` (`title`, `text`, `image`, `link`, optional `subtitle`, `index`).
- `size` (optional): number as string — column count.

### Events

- `collectionItemClick`: `{ uri: string }`.

### Usage notes

- **CSS parts:** `container`, `item`, `image`, `title`, `text`.
- No named content slots in `extra/docs.ts`.

### Minimal HTML example

```html
<hb-vertical-img-txt-archive
  collection='[{"title":"One","text":"Body","image":"https://placehold.co/300x200","link":{"type":"tab","uri":"https://example.com"}}]'
  size="3"
></hb-vertical-img-txt-archive>
```