@htmlbricks/hb-bundle/agents/docs/AGENT_WEBCOMPONENTS_REFERENCE.md

Single IIFE loader for all HTML Bricks hb-* web components from the jsDelivr CDN, with optional Subresource Integrity; includes agent/LLM docs and theme CSS variables.

# 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.76.5**). 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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/README.md) · [same text in this document](#wc-chartjs)
- **`hb-checkout` — `checkout`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-checkout@0.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/README.md) · [same text in this document](#wc-dialogform)
- **`hb-downloader` — `downloader`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-downloader@0.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/README.md) · [same text in this document](#wc-footer)
- **`hb-form` — `form`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-form@0.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/README.md) · [same text in this document](#wc-navbar)
- **`hb-offcanvas` — `offcanvas`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-offcanvas@0.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/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.76.5/README.md) · [same text in this document](#wc-toast)
- **`hb-tooltip` — `tooltip`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-tooltip@0.76.5/README.md) · [same text in this document](#wc-tooltip)
- **`hb-uploader` — `uploader`** — [README on jsDelivr](https://cdn.jsdelivr.net/npm/@htmlbricks/hb-uploader@0.76.5/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.76.5/README.md) · [same text in this document](#wc-vertical-img-txt-archive)

---

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

# hb-area-code

**Category:** utilities · **Tags:** utilities, developer

## Summary

`hb-area-code` renders `content` in a **frameless** root (no Bulma **`box`**): copy + optional “Copied” tag are **positioned top-right over** the **`<pre><code>`** snippet. Copy uses **`navigator.clipboard.writeText`** and emits **`clipboardCopyText`** with **`{ text }`**. The host and root wrapper have **no extra margin or padding**; spacing around the snippet is up to the parent or **`::part(content)`**.

## Behaviour

1. **Copy:** each click writes **`content`** to the clipboard, shows confirmation (~1.6s, timer resets on repeat), and dispatches **`clipboardCopyText`** with **`detail.text`**.
2. **`content`:** single source for display and clipboard.
3. **`id`:** optional; when set, it is applied to the root **`hb-area-code`** wrapper inside the shadow tree.

## Markup

- Root: **`hb-area-code`** (no **`box`** / outer card frame; **no margin or padding** on the host root wrapper).
- Wrapper **`hb-area-code-body`** (`position: relative`): floating **`hb-area-code-float`** (absolute top-right) with optional **`tag is-success is-size-7`**, then **`button is-small`** (theme-default fill, no **`is-light`**) with Bootstrap Icons **`bi-clipboard`** / **`bi-clipboard-check`**.
- Snippet: **`<pre part="content" class="hb-area-code-snippet">`** and **`<code class="hb-area-code-snippet-code">`** (uniform insets; extra **`padding-inline-end`** keeps long first lines clear of the copy controls).

## Custom element

`hb-area-code`

## Attributes

| Attribute | Notes |
| --- | --- |
| `content` | Shown in the snippet and copied (string). |
| `id` | Optional string on the inner root **`hb-area-code`** element. |

## Events

| Event | `detail` |
| --- | --- |
| `clipboardCopyText` | `{ text: string }` |

## Styling

- **Parts:** `content` → `<pre>` (see `extra/docs.ts`).
- **Theme:** same stack as other hb-* components (`bulma-wc-host-theme-tokens` on the shadow `:host`): system **`prefers-color-scheme`**, then **`data-theme` / `.theme-*`** on **`html`**, **`body`**, or the custom element host. **`color-scheme`** on the host follows that order so native chrome stays coherent. The snippet background and border are built with **`hsl(var(--bulma-scheme-h), var(--bulma-scheme-s), var(--bulma-scheme-main-bis-l))`** and **`border-l`** primitives so the surface stays valid in the shadow tree; text prefers **`--bulma-text`** with the same **`hsl(…, --bulma-text-l)`** fallback.
- **Corners:** snippet, copy **button**, and **tag** use **`border-radius: 0`** (no rounded corners inside this component).
- **Dark mode:** the default strip follows Bulma tokens on the shadow `:host` (system **`prefers-color-scheme`** is handled by **`bulma-wc-host-theme-tokens`**, so **`main-bis-l`** is already a dark gray on a dark scheme). The deeper “well” (**`scheme-main-l`**, **`border-l`**, inset highlight) applies **only** when dark is **explicit** — **`data-theme="dark"`** or **`.theme-dark`** on **`html`**, **`body`**, or the host — so we never mix OS dark with light-token **`scheme-main-l`** (that would read as **white**).

## TypeScript

`types/webcomponent.type.d.ts`

## Example

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

---

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

# `hb-auth`

**Category:** auth · **Tags:** auth · **Package:** `@htmlbricks/hb-auth`

## Summary

`hb-auth` is a self-contained authentication card for the shadow DOM. It switches between **login**, **register**, **forgot password**, **mail recovery info**, **account activation**, and **password recovery** flows based on the `type` property. It can call optional HTTP endpoints for login and registration, persist session payloads under a configurable storage key, embed **OAuth2** providers via `hb-auth-social-login-button`, and emit **custom events** so the host app can handle credentials, recovery, and OAuth steps. Strings are **internationalized** (Italian and English) when `i18nlang` is set.

## What it does

- **Local auth UI:** email and password fields (with optional HTML `pattern` via `passwordpattern`), “remember me” on login, full-width primary actions, and ghost links to switch modes (register / login / forgot password) according to `disableregister`, `enable_recover_password`, and the active `type`.
- **Server-assisted login/register:** If `loginuri` or `registeruri` is set, the component performs `fetch` with `requestmethod` (default `POST`, normalized to uppercase). **POST** sends JSON (`email`, `password`, and `rememberMe` for login). **GET** omits a body. Optional `appendbodyparams` must be a **JSON object string** merged into the body. On success, the JSON response is stored in **localStorage** (when “remember me” is checked) or **sessionStorage** under `sessionkey` (default `_auth`), then `redirectonlogin` / `redirectoncreate` may run as a full navigation. The **`login`** or **`register`** event is dispatched with the server payload (or a minimal local payload if no URI is configured).
- **Recovery / activation:** For `type` `activate` or `recover`, the user enters recovery code, email, new password, and repeat password; submitting dispatches **`recoverOrActivate`** with `{ password, recoverycode, email }`. **`forgotpassword`** collects email and dispatches **`recoverPassword`**. **`mailrecoverinfo`** shows informational copy and a link back to login.
- **OAuth:** When `oauth2providers` is a non-empty list, a row of **`hb-auth-social-login-button`** instances is rendered. The host receives **`oauthFlowRedirectStart`**, **`oauthFlowInit`**, **`oauthFlowSuccess`**, and **`oauthFlowCustom`** bubbled from the child. While a flow is in progress, an **opaque overlay** matching the card surface covers the card and shows **only a centered CSS spinner** (no copy); after success, a **dismissible success notification** appears above the card (hidden again during a subsequent OAuth load).
- **URL hints:** If `recoverycode`, `email`, or `type` are not set, the component may read `recoverycode=`, `recoveryemail=`, and `recoverytype=` from `location.href` (query segment after each key, up to `&`).
- **OAuth-only layout:** With `disablelocal` true (and providers configured), the divider and “credentials” subtitle are omitted; only social buttons show for supported `type` values.

The `Component` type also allows `type` values **`otp`**, **`2fa_code`**, and **`2fa_config`**, and includes **`activateuri`** and **`recoveruri`**. In the current markup, **only** `login`, `register`, `forgotpassword`, `mailrecoverinfo`, `activate`, and `recover` drive complete titles, fields, and actions. Other `type` strings are accepted at the type level but **do not** map to dedicated UI blocks in `component.wc.svelte`; **`activateuri` / `recoveruri`** are declared on the component but are **not** read by this file’s logic (hosts can still use them in their own layers).

## Appearance and layout

- **Host:** Block-level, full width of the parent, default text color `var(--bulma-text)`.
- **Width:** Inner wrapper `max-width: 24rem`, centered (`margin-inline: auto`).
- **Card:** Main content uses Bulma’s **`box`** on `.hb-auth` with an extra **1px** border using `var(--bulma-border-weak)` for contrast in light and dark schemes.
- **Header:** Default slot fills with a centered logo image when `logouri` is non-empty; consumers can replace the whole header with the **`header`** slot.
- **Titles:** Centered `title is-4` for login, register, forgot password, and recover/activate headings (i18n strings).
- **OAuth row:** Flex-wrapped, centered list of provider tiles. Each **`hb-auth-social-login-button`** is **5rem × 5rem**, bordered, rounded with `var(--bulma-radius)`, background `var(--bulma-scheme-main-ter)`, with hover ring and focus-visible outline using `var(--bulma-link)`.
- **Divider:** When both OAuth and local form are shown, a horizontal rule (`hb-auth__divider`) separates providers from the “credentials” subtitle and fields.
- **Fields:** Bulma `field` / `control` / `input` patterns; validation toggles Bulma **`is-success` / `is-danger`** on inputs after submit attempts.
- **Overlay:** Absolutely positioned over the **card shell** (`inset: 0`), same background as the Bulma **`box`** (`var(--bulma-box-background-color)` with fallback to `var(--bulma-scheme-main)`), matching **border radius** to the card; **no** extra border or shadow on the overlay. Only **`.hb-auth__spinner`** is visible (track from `color-mix` on `var(--bulma-text)`, accent `var(--bulma-link)`). `aria-busy` on `<main>` reflects loading state.
- **Success banner:** Bulma `notification is-success is-light` above the card when OAuth completes successfully (not shown while OAuth loading is active).
- **Icons:** **Bootstrap Icons** are loaded inside the shadow tree from `styles/webcomponent.scss` (required because `<svelte:head>` link tags do not apply inside shadow roots).

## Logic (sign-in and related flows)

| Mode | Primary action | Event / side effects |
| --- | --- | --- |
| `login` | Validates email/password (length and simple email shape). | With `loginuri`: `fetch`, then storage + optional `redirectonlogin`, then **`login`**. Without `loginuri`: **`login`** with `{ email, password, rememberMe }` only. |
| `register` | Same base validation as login. | With `registeruri`: `fetch`, augments answer with `requestSent`, optional `redirectoncreate`, **`register`**. Without: **`register`** with `{ email, password }`. |
| `forgotpassword` | Email validation. | **`recoverPassword`** with `{ email }`. |
| `activate` / `recover` | Requires `recoverycode`, valid email, password, matching repeat password. | **`recoverOrActivate`** with `{ password, recoverycode, email }`. Recovery code or email read from URL may lock those inputs as disabled. |
| `mailrecoverinfo` | Navigation via footer link. | Switches `type` to `login` in UI only (no dispatch listed for that click beyond user changing mode). |

**Query/body extras:** `appendqueryparams` is appended to `loginuri` and `registeruri` when set (as `?` or `&` depending on whether the path already contains `?`). If unset internally, it becomes `undefined` after the effect.

**Booleans from attributes:** For web components, use string **`yes`** / **`no`** where applicable. `enable_recover_password` is also treated as true when the string is **`true`** or **empty** (`""`) in the effect’s coercion.

**OAuth list:** `oauth2providers` may arrive as a **JSON string** (from attributes); it is parsed and normalized (default scopes for named providers when `url` is empty and `params` exist; `redirect_url` may get a `provider=` query suffix).

**Enter key:** Inside the card, **Enter** triggers the primary action for `login`, `register`, `forgotpassword`, `activate`, and `recover`.

## Custom element

| Item | Value |
| --- | --- |
| Tag name | **`hb-auth`** |
| Svelte option | `customElement="hb-auth"` |
| Dependency | Registers **`hb-auth-social-login-button`** at runtime (`addComponent`) for OAuth tiles. |

## Attributes

All reflected / HTML-facing names use **snake_case**. Complex values (`oauth2providers`, `appendbodyparams`) are **JSON strings** in markup. Booleans follow project convention **`yes`** / **`no`** unless noted.

| Attribute | Purpose |
| --- | --- |
| `id` | Optional host element id. |
| `style` | Optional inline style on the host (standard HTML). |
| `type` | Screen mode: `login` \| `register` \| `activate` \| `recover` \| `forgotpassword` \| `mailrecoverinfo` \| `otp` \| `2fa_code` \| `2fa_config` (see note above on UI coverage). Defaults to `login` when omitted and not taken from URL. |
| `email` | Initial or bound email; may be filled from `recoveryemail=` in the URL. |
| `i18nlang` | Language code (e.g. `en`, `it`) for built-in strings. |
| `sessionkey` | Storage key for persisted auth JSON (default `_auth`). Passed to social login as `auth_cookie_name`. |
| `social_auth_server_url` | Optional base URL forwarded to each **`hb-auth-social-login-button`**. |
| `redirectonlogin` | Optional full navigation after successful stored login; also passed to social buttons. |
| `redirectoncreate` | Optional full navigation after successful registration. |
| `loginuri` | Login API URL for `fetch`. |
| `registeruri` | Register API URL for `fetch`. |
| `activateuri` | Declared on the component type; not used by `component.wc.svelte` logic in this version. |
| `recoveruri` | Declared on the component type; not used by `component.wc.svelte` logic in this version. |
| `requestmethod` | HTTP verb for login/register `fetch` (default `POST`). |
| `appendqueryparams` | String appended to `loginuri` and `registeruri` as query parameters. |
| `appendbodyparams` | JSON object string merged into POST bodies for login/register. |
| `logouri` | Logo image URL for the default header. |
| `oauth2providers` | JSON array of provider objects (`name`, optional `url`, optional `params`) compatible with **`hb-auth-social-login-button`** expectations. |
| `disableregister` | When enabled, hides registration entry points and related UI. |
| `enable_recover_password` | When enabled, shows “forgot password” on the login screen. |
| `passwordpattern` | Optional HTML `pattern` on password inputs. |
| `recoverycode` | Recovery/activation code; may be locked if present in URL. |
| `disablelocal` | When `yes`, hides local email/password block when OAuth providers are present (OAuth-only card). |

## Events

Listen with `addEventListener` or framework bindings; names are **exactly** as below. **`detail`** shapes match `types/webcomponent.type.d.ts` (`Events`).

| Event | `detail` (TypeScript shape) |
| --- | --- |
| `login` | `{ token?: string; email?: string; password?: string; rememberMe?: boolean }` — server response fields when `loginuri` succeeds; otherwise credential payload. |
| `register` | `Record<string, unknown> & { email?: string; password?: string; requestSent?: { email: string; password: string } }` — server JSON when `registeruri` succeeds (component adds `requestSent`); `{ email, password }` when no `registeruri`. |
| `recoverOrActivate` | `{ password: string; recoverycode: string; email: string }` |
| `recoverPassword` | `{ email: string }` |
| `oauthFlowInit` | `{ token?: string; provider: "facebook" \| "google" \| "gitlab" \| "github" \| "authentik"; tmpCode?: string; redirect_uri?: string }` |
| `oauthFlowRedirectStart` | `{ provider: "facebook" \| "google" \| "gitlab" \| "github" \| "authentik" }` |
| `oauthFlowSuccess` | `{ token: string }` |
| `oauthFlowCustom` | `{ provider: "facebook" \| "google" \| "gitlab" \| "github" \| "authentik" }` |

The `provider` literals match `auth-social-login-button`’s `types/webcomponent.type.d.ts` (`IProvider`), which the auth `Events` type reuses for these fields.

## Styling

### CSS custom properties (`:host` / theme)

Documented in `extra/docs.ts` (`styleSetup.vars`). They align with **Bulma 1** tokens; see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).

| Variable | Role |
| --- | --- |
| `--bulma-scheme-main` | Card surface; fallback for OAuth overlay fill when box vars are unavailable. |
| `--bulma-box-background-color` | OAuth overlay fill (matches Bulma `box` when defined on the theme). |
| `--bulma-box-radius` | OAuth overlay corner radius (matches Bulma `box` when defined). |
| `--bulma-scheme-main-ter` | OAuth tile background. |
| `--bulma-border-weak` | Card, tiles, divider. |
| `--bulma-radius` | Social tiles and related rounding. |
| `--bulma-shadow` | Bulma `box` elevation on the card. |
| `--bulma-text` | Default text on `:host`; spinner track tint (`color-mix`). |
| `--bulma-text-strong` | Headings. |
| `--bulma-link` | Ghost links, tile hover ring, focus-visible outlines, spinner accent. |

**Light / dark:** `styles/bulma.scss` installs Bulma light theme on `:host`, dark theme under `prefers-color-scheme: dark`, and overrides when `html` / `body` use `data-theme` / `.theme-light` / `.theme-dark`, or when the host element sets `data-theme`.

### CSS parts

None (`cssParts` is empty in `extra/docs.ts`).

### Slots

| Slot | Description |
| --- | --- |
| `header` | Optional branding above the form; **replaces** the default logo block when content is provided. |

## Typings

Authoring types for consumers and wrappers:

`src/wc/auth/types/webcomponent.type.d.ts`

- **`Component`** — props interface.  
- **`Events`** — custom event name → `detail` map.

## Minimal HTML example

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

OAuth-only example (attributes as strings):

```html
<hb-auth
  type="login"
  disablelocal="yes"
  oauth2providers='[{"name":"google","url":"https://accounts.google.com/o/oauth2/v2/auth?..."}]'
  sessionkey="_auth"
></hb-auth>
```

---

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

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

## Summary

Web component: a square, keyboard-accessible control that starts an OAuth-style redirect for a configured provider (built-in SVGs for GitLab, GitHub, Facebook, Google, and Authentik), or emits a custom event when the provider cannot be started from built-in URL rules. On return to the same page, it can detect tokens or codes in `location.href` and exchange them via `simple-serverless-auth-client` when a server URL and cookie name are set.

## What it does

- Renders a clickable `#icon-content` region (`role="button"`, `tabindex="0"`) that runs `socialLogin()` on click or Enter/Space.
- If `provider.url` is set, dispatches `oauthFlowRedirectStart` and sets `location.href` to that URL.
- Else, if `provider.params` includes `client_id` and `redirect_url`, builds a provider-specific authorize URL (see Logic), dispatches `oauthFlowRedirectStart`, then redirects.
- Else logs a warning and dispatches `oauthFlowCustom`.
- On mount, `detectByUri()` inspects `location.href` for provider-specific return patterns; when matched, dispatches `oauthFlowInit` and may call `Authorize.socialLoginOauthAnswer` if both `social_auth_server_url` and `auth_cookie_name` are truthy. On success, either navigates to `redirectonlogin` or dispatches `oauthFlowSuccess` with `{ token }`.

## Appearance

| Aspect | Behavior |
| --- | --- |
| Host | `display: block`, fixed size `2.5rem` × `2.5rem`, padding `0.625rem`. |
| `#icon` | Fills host, transparent background, `position: relative`. |
| `#icon-content` | Absolutely positioned, vertically centered, `cursor: pointer`, transparent background. |
| Default artwork | Inline SVGs with `part="provider_icon"` for known `provider.name` values; unknown name shows literal text `btn` inside the default slot fallback. |
| Focus | `:focus-visible` uses outline and radius from CSS variables (see Styling). |

## Logic

| Step | Condition | Action |
| --- | --- | --- |
| Parse `provider` | `provider` is a string | `JSON.parse` in an `$effect` (errors logged to console). |
| Start login | Missing `provider.name`, or both `provider.url` and `provider.params` missing | `console.error`, return. |
| Prebuilt URL | `provider.url` set | `oauthFlowRedirectStart`, then `location.href = provider.url`. |
| Composed URL | `provider.params.client_id` and `provider.params.redirect_url` | Build URL by `provider.name`, then `oauthFlowRedirectStart` and redirect. |
| No URL | Otherwise | `console.warn`, `oauthFlowCustom`. |
| Google URL | `google` | `https://accounts.google.com/o/oauth2/v2/auth` with `response_type=token`, `scope`, `client_id`, `redirect_uri`, etc. |
| GitHub URL | `github` | `https://github.com/login/oauth/authorize` with `scope`, `client_id`, `redirect_uri`. |
| GitLab URL | `gitlab` | `https://gitlab.com/oauth/authorize` with `response_type=code`, `state`, `scope`, `client_id`, `redirect_uri`. |
| Facebook URL | `facebook` | Same host/path pattern as GitLab in code: `https://gitlab.com/oauth/authorize?...` (same query shape as `gitlab`). |
| Authentik URL | `authentik` | `` `${provider.params.auth_server_url}/application/o/authorize/?` `` plus `scope`, `response_type=code`, `state`, `client_id`, `redirect_uri`. |
| Return: Google | `provider.name === "google"`, URL contains `access_token=` and `google` | Extract token after `access_token=`, call server exchange with `{ provider, token }`, dispatch `oauthFlowInit` with `{ provider, token }`. |
| Return: GitHub | `github`, `code=`, `provider=github` | Code as `token` / `tmpCode`, server exchange, `oauthFlowInit` with `token` and `tmpCode`. |
| Return: Facebook | `facebook`, `code=`, `provider=facebook` | Derives `redirect_uri` by stripping `state` and `code` segments from `location.href`, server exchange, `oauthFlowInit` includes `redirect_uri`. |
| Return: GitLab | `gitlab`, `code=`, `provider=gitlab` | Same style of `redirect_uri` derivation and `oauthFlowInit` as other code-based providers. |
| Return: Authentik | `authentik`, `code=`, `provider=authentik` | Same pattern as GitLab/Facebook for exchange and `oauthFlowInit`. |
| Server exchange | `auth_cookie_name` and `social_auth_server_url` both truthy | `Authorize.socialLoginOauthAnswer(providerPayload, { authUrl: social_auth_server_url, authCookieName: auth_cookie_name })`. |
| After exchange | `redirectonlogin` truthy | `location.href = redirectonlogin`. |
| After exchange | No `redirectonlogin` | `oauthFlowSuccess` with `{ token: resolvedToken }`. |

## Custom element

| Tag |
| --- |
| `hb-auth-social-login-button` |

## Attributes

Web component attributes are strings; complex values use JSON strings. Boolean-like project rules elsewhere do not apply to the props used here beyond normal string attributes.

| Attribute | Role in code |
| --- | --- |
| `id` | Bound to `id`; default `""` in destructuring. |
| `provider` | Provider config; coerced from JSON string if passed as string. Must include `name` and either `url` or `params` (see Logic). |
| `social_auth_server_url` | Passed to `Authorize.socialLoginOauthAnswer` as `authUrl` when set with `auth_cookie_name`. |
| `auth_cookie_name` | Passed as `authCookieName`; default `"hb_session"` in destructuring. |
| `redirectonlogin` | If set after successful exchange, full-page redirect to this URL instead of emitting `oauthFlowSuccess`. |

The TypeScript `Component` type also includes optional `style`, which is not read from `$props()` in `component.wc.svelte` (the `style` binding is commented out).

## Events

All events are `CustomEvent` dispatched on the host element.

| Event | `detail` |
| --- | --- |
| `oauthFlowRedirectStart` | `{ provider: IProvider }` |
| `oauthFlowInit` | `{ token?: string; provider: IProvider; tmpCode?: string; redirect_uri?: string }` |
| `oauthFlowSuccess` | `{ token: string }` |
| `oauthFlowCustom` | `{ provider: IProvider }` |

`IProvider` in types: `"facebook" \| "google" \| "gitlab" \| "github" \| "authentik"`.

## Styling (vars / parts / slots)

### CSS custom properties

| Variable | Used in | Fallback in SCSS |
| --- | --- | --- |
| `--bulma-link` | `#icon-content:focus-visible` outline color | `#485fc7` |
| `--bulma-radius` | `#icon-content:focus-visible` border radius | `0.25rem` |

### `::part`

| Part | Target |
| --- | --- |
| `provider_icon