@htmlbricks/hb-dashboard-counter-lines 0.71.35 → 0.71.37

package/README.md

@@ -1,50 +1,138 @@
-## `hb-dashboard-counter-lines` — dashboard-counter-lines
+# `hb-dashboard-counter-lines`
 
-**Category:** data | **Tags:** data, dashboard
+**Category:** data · **Tags:** data, dashboard
 
-### What it does
+## Overview
 
-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.
+`hb-dashboard-counter-lines` renders a vertical list of dashboard-style metrics. Each row can show an optional Bootstrap Icon, a primary label, and a compact counter value in a Bulma light, rounded tag. Rows may be static or clickable depending on an optional `link` object.
 
-### Styling (Bulma)
+The custom element is registered as **`hb-dashboard-counter-lines`**.
 
-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/).
+## When to use it
 
-**Shadow markup (simplified):**
+Use this component when you need a simple, scannable summary of several numeric or textual KPIs (counts, rates, totals) with optional navigation or a custom click action per row.
 
-- **`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`**).
+## Data model (`lines`)
 
-### Custom element
+The `lines` prop is a **`Line[]`** array. From HTML, pass it as a **JSON string** (serialized array).
 
-`hb-dashboard-counter-lines`
+Each line object supports:
 
-### Attributes / props (snake_case)
+| Field | Type | Description |
+| --- | --- | --- |
+| `text` | string | Primary label shown on the row (truncated with an ellipsis when space is tight). |
+| `value` | string | Counter text rendered inside the Bulma `tag is-light is-rounded` pill. |
+| `icon` | string (optional) | Bootstrap Icons **glyph name only** (without the `bi-` prefix), e.g. `"people"`, `"clock"`. Renders as `class="bi bi-{icon}"`. |
+| `link` | object (optional) | When present and valid, the whole row becomes clickable. See [Link behavior](#link-behavior) below. |
+| `index` | number (optional) | Reserved in the type for ordering or metadata; the current markup does not display it. |
+
+### Parsing rules
+
+- If `lines` is omitted, `null`, or an empty string after trim, nothing is rendered.
+- If `lines` is a string, the component **`JSON.parse`s** it once (synchronously) before paint. Invalid JSON logs an error to the console and results in an empty list.
+- Non-array JSON or an empty array also yields no visible content.
+
+## Attributes and properties (snake_case)
+
+Web component attributes are strings. Complex values must be JSON strings.
+
+| Name | Required | Description |
+| --- | --- | --- |
+| `id` | No | Optional; present on the authoring `Component` type for integrations that set it from JavaScript. |
+| `style` | No | Optional on the authoring `Component` type; the implementation does not forward a `style` prop into the shadow tree—use Bulma variables, `::part`, or the native HTML `style` attribute on the host element if you need one-off host styling. |
+| `lines` | No | JSON string representing `Line[]`, e.g. `[{"text":"Users","value":"42","icon":"people"}]`. |
+
+## Link behavior
+
+When `link` is set and includes both `type` and `uri`, the row is interactive (`cursor`/click styling from your theme and `::part(item)`).
+
+| `link.type` | Effect |
+| --- | --- |
+| `"tab"` | Opens `link.uri` in a new browser tab (`window.open(..., "_blank")`). |
+| `"page"` | Navigates the current window to `link.uri` (`window.location.href`). |
+| `"event"` | Dispatches a **`counterClick`** custom event with **`detail.key`** equal to `link.uri` (use `uri` as your logical event key). |
+
+If `link` is missing, incomplete, or `uri` is empty, the row is **not** clickable.
+
+## Events
+
+| Event name | `detail` shape | When it fires |
+| --- | --- | --- |
+| `counterClick` | `{ key: string }` | When the user activates a row whose `link.type` is `"event"`. `key` is the line’s `link.uri`. |
+
+Listen with `addEventListener("counterClick", ...)` or the equivalent in your framework.
+
+## Layout and styling
+
+- **Host:** `:host` is a column flex container with spacing between rows, full width, `min-width: 0` so flex children can shrink inside tight layouts.
+- **Row:** Label cluster (icon + text) grows/shrinks; the value tag stays on the right and does not shrink.
+- **Typography:** Long labels use a single line with ellipsis overflow.
+
+Theming uses **Bulma CSS variables** inside the shadow root. You can also target exposed **CSS parts** from the light DOM.
+
+### CSS custom properties (`--bulma-*`)
 
-| Property | Type | Notes |
+| Variable | Default | Role |
 | --- | --- | --- |
-| `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?. |
+| `--bulma-primary` | `#00d1b2` | Primary brand color (e.g. tag accents when using Bulma color modifiers). |
+| `--bulma-text` | `#363636` | Main label text color. |
+| `--bulma-text-weak` | `#7a7a7a` | Muted supporting text where applicable. |
+| `--bulma-radius` | `0.375rem` | Base radius for components that depend on Bulma radius tokens. |
+| `--bulma-radius-rounded` | `9999px` | Pill radius for `.tag.is-rounded`. |
 
-**Parts:** `item`, `icon`, `text`, `value`. No slots.
+Set `--bulma-*` on `html`, `body`, or on the element / its ancestors so values inherit into the shadow tree. See the [Bulma CSS variables documentation](https://bulma.io/documentation/features/css-variables/).
 
-### Events (`CustomEvent` names)
+### CSS parts (`::part(...)`)
 
-- **`counterClick`** — `{ key: string }` — Used when a line’s `link.type` is `"event"` (per docs behavior).
+| Part | Description |
+| --- | --- |
+| `item` | Outer row container; meaningful for hover, cursor, padding, or background when the row has a `link`. |
+| `icon` | Bootstrap Icon `<i>` element for that row. |
+| `text` | Primary label `<span>`. |
+| `value` | Bulma tag showing the counter value (`tag is-light is-rounded`). |
 
-### Usage notes
+### Slots
 
-- 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`.
+None.
 
-### Minimal HTML example
+## Dependencies (runtime)
+
+- **Bootstrap Icons** font (loaded for icon classes used in the shadow tree).
+- **Bulma** (Sass modules forwarded in the component styles).
+
+## Examples
+
+### Several static metrics
+
+```html
+<hb-dashboard-counter-lines
+  lines='[{"text":"Active users","value":"1.2k","icon":"people"},{"text":"Errors","value":"3","icon":"exclamation-triangle"},{"text":"Latency p95","value":"120ms","icon":"speedometer2"}]'
+></hb-dashboard-counter-lines>
+```
+
+### Row that opens a URL in a new tab
 
 ```html
 <hb-dashboard-counter-lines
-  lines='[{"text":"Active users","value":"1.2k","icon":"people"},{"text":"Errors","value":"3","icon":"exclamation-triangle"}]'
+  lines='[{"text":"Open reports","value":"12","icon":"graph-up-arrow","link":{"type":"tab","uri":"https://example.com/reports"}}]'
 ></hb-dashboard-counter-lines>
 ```
+
+### Row that emits `counterClick`
+
+```html
+<hb-dashboard-counter-lines
+  id="kpi-block"
+  lines='[{"text":"Drill down","value":"99+","link":{"type":"event","uri":"open-details"}}]'
+></hb-dashboard-counter-lines>
+
+<script>
+  document.getElementById("kpi-block").addEventListener("counterClick", (e) => {
+    console.log("key:", e.detail.key); // "open-details"
+  });
+</script>
+```
+
+## Internationalization
+
+No built-in i18n strings; pass already-translated `text` and `value` values in `lines`.

package/manifest.json

@@ -124,7 +124,7 @@
         "name": "--bulma-text-weak",
         "valueType": "color",
         "defaultValue": "#7a7a7a",
-        "description": "Muted text."
+        "description": "Tints supplementary or secondary copy on each metric row so supporting labels and hints recede visually behind the primary label column."
       },
       {
         "name": "--bulma-radius",
@@ -141,16 +141,20 @@
     ],
     "parts": [
       {
-        "name": "item"
+        "name": "item",
+        "description": "Clickable row container when a `link` is present; use for spacing, cursor, or hover background from the host."
       },
       {
-        "name": "icon"
+        "name": "icon",
+        "description": "Bootstrap Icon element for the row; adjust size or color without touching inner markup."
       },
       {
-        "name": "text"
+        "name": "text",
+        "description": "Primary label column for the metric line."
       },
       {
-        "name": "value"
+        "name": "value",
+        "description": "Bulma `tag is-light is-rounded` showing the counter value; style pill colors and weight here."
       }
     ]
   },
@@ -249,5 +253,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-dashboard-counter-lines",
-  "version": "0.71.35"
+  "version": "0.71.37"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-dashboard-counter-lines",
-  "version": "0.71.35",
+  "version": "0.71.37",
   "contributors": [],
   "description": "Vertical list of metric rows from JSON `lines`: each row shows optional Bootstrap Icon, label text, and a Bulma `tag is-light is-rounded` counter. `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.",
   "licenses": [