@htmlbricks/hb-contact-item 0.71.35 → 0.71.36

package/README.md

@@ -4,7 +4,9 @@
 
 ### 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).
+Renders a single contact row: one of **phone**, **postal address**, **email**, **website**, or **social** profile. Each variant shows a Bootstrap Icon (when enabled) and optional label text. Behavior is controlled by a JSON **`config`** object: show or hide the icon column, show or hide text, and choose whether a click should **`window.open`** a URL or dispatch a **`contactClick`** custom event with the active mode and payload.
+
+Evaluation order is fixed: if multiple inputs are present, **phone** wins, then **social**, **address**, **email**, and **site**. In practice you should pass only one contact type per instance.
 
 ### Custom element
 
@@ -12,35 +14,111 @@ Single contact line (mutually exclusive props): phone, postal address, email, we
 
 ### Attributes / props (snake_case)
 
-| Property | Type | Notes |
+Web component attributes are **strings**. Objects must be passed as **JSON** (single-line attribute values are typical). Property names on the element use **snake_case**; keys **inside** the JSON payloads follow the TypeScript shapes below (camelCase where noted).
+
+| Attribute | Type | Description |
 | --- | --- | --- |
-| `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?. |
+| `id` | string (optional) | Host-controlled identifier; forwarded like any HTML id when set by the runtime. |
+| `style` | string (optional) | Inline style string on the host element. |
+| `phone` | JSON (optional) | **`IPhone`**: `number` (required), `callOnClick` (optional boolean). The value is included in `contactClick` detail; the component does not open `tel:` URLs by itself—handle dialing or navigation in your listener if needed. |
+| `address` | JSON (optional) | **`IAddress`**: `address` (required), `shortAddress` (optional), `mapUri` (optional), `latLang` (optional number array `[lat, lng]`). If `mapUri` or `latLang` is set, a click opens a map URL (`latLang` becomes a Google Maps query URL; if both `latLang` and `mapUri` exist, **`mapUri` wins**). |
+| `email` | JSON (optional) | **`IEmail`**: `address` (required), `mailLink` (optional boolean). If `mailLink` is true, a click calls `window.open` with **`address` as the URL string**—use a full URL (for example `mailto:support@example.com`) so the browser can open the mail client. |
+| `site` | JSON (optional) | **`ISite`**: `uri` (optional), `label` (optional), `open` (optional boolean). Display text is `label` if set, otherwise `uri`. If `open` is true and `uri` is set, a click opens `uri` in a new window. |
+| `social` | JSON (optional) | **`ISocial`**: `name` (required), `label` (optional), `pageUri` (optional). The icon class is `bi bi-{name}` (Bootstrap Icons suffix only, without the `bi-` prefix). If `pageUri` is set, a click opens that URL. |
+| `config` | JSON (optional) | **`IConfig`**: `icon` (optional object with optional `fill` boolean), `text` (optional boolean), `dispatcher` (optional boolean). Defaults applied in logic: `icon.fill` defaults to false if `icon` exists; `text` defaults to true unless explicitly `false`; `dispatcher` defaults to true unless explicitly `false`. The **`fill`** flag is accepted for forward compatibility but **does not** currently switch icon classes in markup. |
+
+### Click behavior (summary)
+
+1. If the row is configured to open a window (**social** `pageUri`, **address** map link, **email** with `mailLink`, or **site** with `open` + `uri`), the first click runs **`window.open`** with the resolved URL. **`contactClick` is not fired** in that branch.
+2. Otherwise, if **`config.dispatcher`** is not disabled, a click dispatches **`contactClick`** with detail **`{ action, options }`**:
+   - **`action`**: `"phone"` | `"social"` | `"address"` | `"email"` | `"site"` (whichever branch is active).
+   - **`options`**: the parsed object for that branch (same shape as the corresponding prop).
+
+The root span gets a clickable affordance (Bulma `is-clickable`) when a window URL will be used on click.
+
+### CSS custom properties
+
+None are declared for this component in `styleSetup`. The shadow tree loads Bulma helpers for layout and Bootstrap Icons for glyphs. Surrounding page typography and colors affect only the host, not inner defaults beyond Bulma utilities.
+
+### CSS parts (`::part`)
+
+| Part | Description |
+| --- | --- |
+| `iconcell` | Wrapper around the leading icon column (when `config.icon` is truthy). |
+| `prop` | Text span for the visible value (when `config.text` is enabled). |
+
+### HTML slots
 
-No CSS vars, parts, or slots in metadata.
+None.
 
-### Events (`CustomEvent` names)
+### Events (`CustomEvent`)
 
-- **`contactclick`** — `{ action: string; options: any }` — Exact event name is lowercase in types.
+| Event | `detail` | When it fires |
+| --- | --- | --- |
+| **`contactClick`** | `{ action: string; options: ... }` — `options` matches the active **`phone` / `address` / `email` / `site` / `social`** object | On click when **no** `window.open` URL is resolved for that row and **`config.dispatcher`** is true (default). |
+
+Authoring typings may list a lowercase `contactclick` key for tooling compatibility; the **DOM event type emitted at runtime is `contactClick`**.
 
 ### 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`.
+- Prefer **one** of `phone`, `address`, `email`, `site`, or `social` per element to avoid surprising precedence.
+- Escape JSON correctly in HTML attributes when needed (for example use single quotes around the attribute value and double quotes inside the JSON string).
+- Social **`name`** must be a valid Bootstrap Icons glyph name fragment (for example `facebook`, `linkedin`, `twitter-x`).
+- Bootstrap Icons CSS is injected from the component (`svelte:head` / shadow stylesheet); no extra icon font link is required on the host page for the shadow tree.
+- There is **no** built-in i18n catalog for this package; labels come entirely from your JSON props.
+
+### Minimal HTML examples
 
-### Minimal HTML example
+**Email row (click opens mail client via `mailto:`):**
 
 ```html
 <hb-contact-item
-  email='{"address":"hello@example.com","mailLink":true}'
+  email='{"address":"mailto:hello@example.com","mailLink":true}'
   config='{"text":true,"dispatcher":true}'
 ></hb-contact-item>
 ```
+
+**Email row (no automatic navigation—handle `contactClick`):**
+
+```html
+<hb-contact-item
+  email='{"address":"hello@example.com"}'
+  config='{"dispatcher":true}'
+></hb-contact-item>
+```
+
+**Phone row (integrator handles `contactClick`):**
+
+```html
+<hb-contact-item
+  phone='{"number":"+39 02 1234567","callOnClick":true}'
+></hb-contact-item>
+```
+
+**Address with external map link:**
+
+```html
+<hb-contact-item
+  address='{"address":"Via Example 42, Milan, Italy","shortAddress":"Milan HQ","mapUri":"https://www.openstreetmap.org/search?query=Milan"}'
+></hb-contact-item>
+```
+
+**Website with new-tab behavior:**
+
+```html
+<hb-contact-item
+  site='{"label":"Company site","uri":"https://example.com","open":true}'
+  config='{"text":true,"icon":{"fill":false}}'
+></hb-contact-item>
+```
+
+### Listening from JavaScript
+
+```javascript
+const el = document.querySelector("hb-contact-item");
+el.addEventListener("contactClick", (e) => {
+  const { action, options } = e.detail;
+  // action: "phone" | "address" | "email" | "site" | "social"
+  // options: payload object for that action
+});
+```

package/manifest.json

@@ -288,5 +288,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-contact-item",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-contact-item",
-  "version": "0.71.35",
+  "version": "0.71.36",
   "contributors": [],
   "description": "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).",
   "licenses": [