@htmlbricks/hb-site-contacts-row 0.71.35 → 0.71.36

package/README.md

@@ -1,36 +1,133 @@
-## `hb-site-contacts-row` — site-contacts-row
+# `hb-site-contacts-row` (site-contacts-row)
 
 **Category:** content  
-**Tags:** content, contact
+**Tags:** content, contact  
+**Package:** `@htmlbricks/hb-site-contacts-row`
 
-### What it does
+## Overview
 
-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.
+`hb-site-contacts-row` is a contact strip that groups **addresses**, **phones**, **emails**, **websites**, and **availability** (opening hours plus an optional appointment note) into a responsive Bulma layout. Each group can have its own **title**, **Bootstrap Icons** glyph, and list content.
 
-### Custom element
+The component registers the custom element **`hb-site-contacts-row`**. It runs inside a **shadow root** with Bulma layout and typography, and loads the **Bootstrap Icons** font from jsDelivr in `<svelte:head>`.
 
-`hb-site-contacts-row`
+## Layout: `model`
 
-### Attributes (snake_case; use string values in HTML)
+- **`small`** — Compact blocks: addresses use an inline “icon + content” row; phones, emails, websites, and availability use column halves on tablet and full width on mobile.
+- **`big`** — Larger “card-style” columns (`col_big`) with a prominent icon row, title, and list.
 
-- `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"`.
+**Default:** If you omit `model`, the implementation defaults to **`small`**.
 
-### Events
+**Invalid values:** Any `model` other than `small` or `big` renders the fallback text `wrong model provided` plus the value you passed (still inside the shadow tree).
 
-- `event`: `{ test: boolean }` (integration hook per typings).
+> The metadata description mentions “auto” layouts; the current Svelte implementation only supports **`big`** and **`small`**. Omitting `model` is the same as **`small`**, not a separate adaptive mode.
 
-### Usage notes
+## Attributes (HTML)
 
-- No named slots in `extra/docs.ts`. Pass complex blocks as JSON attributes or bind after custom element upgrade.
+Use **snake_case** attribute names. From plain HTML, pass **objects as JSON strings** (single-quoted in HTML, escaped quotes inside JSON).
 
-### Minimal HTML example
+| Attribute | Required | Description |
+| --- | --- | --- |
+| `id` | No | Optional host element id (forwarded as a normal attribute / prop). |
+| `style` | No | Present in the TypeScript `Component` shape; **not** wired into the template in the current implementation. |
+| `model` | No | `"small"` \| `"big"`. Defaults to `"small"`. |
+| `addresses` | No | JSON: `{ "icon"?: string, "title"?: string, "addresses": Address[] }`. |
+| `phones` | No | JSON: `{ "icon"?: string, "title"?: string, "phones": Phone[] }`. |
+| `emails` | No | JSON: `{ "icon"?: string, "title"?: string, "emails": Email[] }`. |
+| `websites` | No | JSON: `{ "icon"?: string, "title"?: string, "websites": Website[] }`. |
+| `availability` | No | JSON: `{ "icon"?: string, "title"?: string, "times": string[], "appointment"?: boolean }`. |
+
+### JSON shapes (TypeScript reference)
+
+```ts
+type Address = {
+  address: string;
+  latLng?: number[];  // [lat, lng] → Google Maps link when no `link`
+  link?: string;      // external URL; takes precedence over `latLng`
+  name?: string;      // shown as a prefix in `big` mode only
+};
+
+type Phone = {
+  number: string;
+  name?: string;      // prefix in `big` mode only
+};
+
+type Email = {
+  address: string;
+  label?: string;     // link text in `small`; in `big`, link text vs address
+  name?: string;      // prefix in `big` mode only
+};
+
+type Website = {
+  url: string;
+  label?: string;
+  name?: string;      // prefix in `big` mode only
+};
+```
+
+**Parsing:** When any of `addresses`, `phones`, `emails`, `websites`, or `availability` arrives as a **string**, the component attempts `JSON.parse` inside an effect. Malformed JSON is logged to the console and leaves the previous value behavior up to the runtime.
+
+### Icons
+
+Each block accepts an optional `icon` string: the **Bootstrap Icons** short name **without** the `bi-` prefix (the markup adds `class="bi bi-{icon}"`). Defaults if omitted:
+
+| Block | Default icon |
+| --- | --- |
+| addresses | `geo-alt` |
+| phones | `telephone` |
+| emails | `envelope` |
+| websites | `globe` |
+| availability | `clock` |
+
+### Addresses: links
+
+For each address with non-empty `address`:
+
+1. If `link` is set → `<a href="{link}" target="_blank">`.
+2. Else if `latLng` has length → Google Maps URL `https://www.google.com/maps/@{lat},{lng},15z` in a new tab.
+3. Else → plain text.
+
+### Emails and websites
+
+- **Emails:** `mailto:` links. In **`small`** mode, the list shows `label` as the link text when set, otherwise the address. In **`big`** mode, optional `name:` prefix, then a single mailto link using `label` or the address as visible text.
+- **Websites:** External `<a href="{url}">` with `label` or URL as text, with the same `small` / `big` differences as emails for prefixes.
+
+### Availability
+
+- Renders when `availability.times` is a non-empty array; each string is one list item.
+- When `availability.appointment` is truthy, an extra line is shown **in Italian** (implementation detail): `*riceve per appuntamento` in `small` mode and `riceve per appuntamento` in `big` mode.
+
+## Events
+
+`types/webcomponent.type.d.ts` declares an `Events` map with a generic `event` payload `{ test: boolean }`. The current `component.wc.svelte` **does not call** the local `dispatch` helper, so **no custom events are emitted** from this revision of the component. Keep the typings in mind if you extend the implementation.
+
+## Styling
+
+The component forwards **`styles/bulma.scss`** (Bulma 1.x CSS variables on `:host`) and **`styles/webcomponent.scss`**.
+
+### CSS custom properties (`:host`)
+
+| Variable | Role |
+| --- | --- |
+| `--bulma-text` | Body copy in lists and labels. |
+| `--bulma-link` | Linked addresses, phones, emails, and websites. |
+| `--bulma-block-spacing` | Vertical rhythm between stacked blocks and icon sizing. |
+| `--bulma-column-gap` | Inline gaps in rows and list spacing. |
+| `--bulma-size-small` | Appointment line and small meta text. |
+| `--bulma-weight-bold` | Section titles and appointment emphasis. |
+
+See Bulma’s [CSS variables](https://bulma.io/documentation/features/css-variables/) documentation for value types and inheritance.
+
+### CSS parts
+
+| Part | Description |
+| --- | --- |
+| `container` | Root `columns is-multiline` wrapper (`part="container"`). Use for layout, max-width, or background overrides. |
+
+### Slots
+
+None. All content is supplied via JSON attributes.
+
+## Minimal example
 
 ```html
 <hb-site-contacts-row
@@ -38,3 +135,18 @@ Contact strip for addresses (with optional `latLng`), phones, emails, websites,
   emails='{"emails":[{"label":"Info","address":"info@example.com","name":"main"}]}'
 ></hb-site-contacts-row>
 ```
+
+### Example with multiple groups
+
+```html
+<hb-site-contacts-row
+  model="big"
+  addresses='{"title":"Locations","addresses":[{"address":"1 Example Rd","latLng":[51.5,-0.12],"name":"HQ"}]}'
+  phones='{"phones":[{"name":"Desk","number":"+1 555 0100"}]}'
+  availability='{"times":["Mon–Fri 9–18"],"appointment":true}'
+></hb-site-contacts-row>
+```
+
+## Authoring types
+
+For Svelte or TypeScript consumers, see `types/webcomponent.type.d.ts` for the full `Component`, `Address`, `Phone`, `Email`, `Website`, and `Events` definitions.

package/manifest.json

@@ -270,8 +270,50 @@
     }
   },
   "styleSetup": {
-    "vars": [],
-    "parts": []
+    "vars": [
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Default body copy in list blocks and labels."
+      },
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Linked addresses, phones, emails, and websites."
+      },
+      {
+        "name": "--bulma-block-spacing",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Vertical rhythm between stacked blocks and icon sizing."
+      },
+      {
+        "name": "--bulma-column-gap",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Inline gaps in inline rows and list item spacing."
+      },
+      {
+        "name": "--bulma-size-small",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Appointment line and small meta text."
+      },
+      {
+        "name": "--bulma-weight-bold",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Section titles and appointment emphasis."
+      }
+    ],
+    "parts": [
+      {
+        "name": "container",
+        "description": "Root `columns is-multiline` wrapper; target for layout, max-width, or background overrides."
+      }
+    ]
   },
   "contributors": [],
   "htmlSlots": [],
@@ -692,5 +734,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-site-contacts-row",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

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