@htmlbricks/hb-dashboard-indicator 0.71.35 → 0.71.37

package/README.md

@@ -1,41 +1,185 @@
-## `hb-dashboard-indicator` — dashboard-indicator
+# `hb-dashboard-indicator` — Dashboard indicator
 
-**Category:** data | **Tags:** data, dashboard
+**Package folder:** `dashboard-indicator`  
+**Category:** data  
+**Tags:** data, dashboard  
+**NPM scope (distribution):** `@htmlbricks/hb-dashboard-indicator`
 
-### 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`.
+## Summary
 
-### Custom element
+`hb-dashboard-indicator` is a compact KPI tile for dashboards: a colored **header** shows a large **metric** (`number`), an optional **caption** (`text`), and a **Bootstrap Icon**; an optional **footer** appears when `link_label` is set and acts as a single **click target** that emits a **`dashboardIndicatorClick`** custom event carrying the element’s `id`.
 
-`hb-dashboard-indicator`
+Accent color (“karma”) is either a **Bulma semantic palette** on `:host` (`success`, `danger`, `warning`, `primary`, `secondary`, `info`) or **`none`** to drive header background and footer text color from **`--hb--dashboard-indicator-background`** on the host.
 
-### Attributes / props (snake_case)
+---
 
-| Property | Type | Notes |
+## Behavior
+
+### Rendering
+
+- **`number`:** Shown as the main value (Bulma `title is-3`, with tightened line-height for a compact header). In markup, pass it as a **string** (web component attributes are always strings); the component coerces to a number internally (default **`0`** when omitted).
+- **`text`:** Optional subtitle under the number (Bulma `subtitle is-7`). Empty string hides the subtitle line container content but the layout still reserves flow; empty caption is visually minimal.
+- **`icon`:** Bootstrap Icons **glyph name only** (no `bi-` prefix). Rendered as `<i class="bi bi-{icon}">`. Implementation default if unset is **`hypnotize`**; the authoring type marks `icon` as optional to mirror HTML usage.
+- **`link_label`:** If **non-empty**, a **footer** strip is rendered with the label and a right-pointing circle arrow icon. If empty or unset, **no footer** and **no** `dashboardIndicatorClick` from this control (there is nothing to click).
+- **`id`:** Optional string forwarded in **`dashboardIndicatorClick`** detail as `{ id: string }`. If unset, detail is `{ id: "" }`.
+
+### `karma` (accent)
+
+Allowed values: `success`, `danger`, `warning`, `primary`, `secondary`, `info`, `none`.
+
+- **`secondary`:** Not a separate Bulma palette in this component; it is **mapped to Bulma `dark`** HSL tokens (`--bulma-dark-h` / `-s` / `-l` with defaults), same as the SCSS comment in the repo.
+- **Semantic values (`success` … `info` except `none`):** Header **background** and footer **text color** use `hsl(var(--bulma-<token>-h), …)` resolved from `:host` (Bulma 1.x CSS variables). **`--hb--dashboard-indicator-background` is ignored** for these values.
+- **`none`:** Header background and footer link/icon color use **`var(--hb--dashboard-indicator-background, <fallback>)`** where fallback is Bulma **success** semantic HSL. Set the variable on **`hb-dashboard-indicator`** (inline `style`, stylesheet, or design token layer).
+
+If `karma` is **not** one of the allowed literals (e.g. typo), the component **normalizes to `success`** (`karmaResolved`).
+
+### Interaction
+
+- **Click:** Only the **footer** (`link_label` visible) calls `dispatch("dashboardIndicatorClick", { id })`. The header is **not** clickable for this event.
+- **Implementation note:** The footer uses a click handler without an equivalent keyboard handler in source; for strict accessibility, integrators may wrap the tile or add host-level keyboard handling if needed.
+
+### Assets and shadow DOM
+
+- **Bootstrap Icons** are loaded for the shadow tree (stylesheet link in the component head **and** a font import in `styles/webcomponent.scss` in the build). Integrators should use **valid icon names** compatible with the Bootstrap Icons version pinned by the bundle.
+- **Bulma** card, title, and helper utilities are included via `styles/bulma.scss` with `:host` variable forwarding so **`--bulma-*`** tokens on the custom element affect the tile.
+
+---
+
+## Layout
+
+- **Root:** Bulma **`card`** with class `hb-dashboard-indicator` and `data-karma={resolved}` for styling hooks.
+- **Header (`card-header`):** Single **`card-header-title`** row (`hb-dashboard-indicator-header-inner`) as a flex row: **`nowrap`**, **space-between**, vertically centered.
+  - **Left:** Icon wrapper (`hb-dashboard-indicator-icon`) — large icon (~`4rem`), white glyph on semantic header background.
+  - **Right:** Flex column aligned **end** (`has-text-right`): **number** then **text**, white text, `min-width: 0` to avoid overflow blowout in tight grids.
+- **Header padding:** Vertical `0.5rem`; horizontal **`var(--bulma-block-spacing, 1rem)`**. Inner title padding is reset to avoid double padding with Bulma’s defaults.
+- **Footer (`card-footer`):** Only when `link_label` is set. Flex **space-between**, **clickable** (`is-clickable`), vertical padding `py-2`. Surface color from **`--bulma-background`** with scheme fallbacks; top border matches surface for a flush edge. First/last children get horizontal margins from **`--bulma-block-spacing`**.
+
+---
+
+## Logic (implementation reference)
+
+| Concern | Rule |
+| --- | --- |
+| Valid `karma` set | `success`, `danger`, `warning`, `primary`, `secondary`, `info`, `none` |
+| Invalid `karma` | Treated as **`success`** |
+| Event emission | `new CustomEvent("dashboardIndicatorClick", { detail: { id } })` on `$host()` |
+| Footer visibility | `{#if link_label}` — truthy string required |
+
+The `style` field exists on the **TypeScript `Component`** type for authoring, but the Svelte props block does **not** destructure `style`; host styling still works by setting the standard **`style`** attribute on `<hb-dashboard-indicator>` (especially for CSS variables).
+
+---
+
+## Custom element tag
+
+```html
+<hb-dashboard-indicator …></hb-dashboard-indicator>
+```
+
+---
+
+## Attributes / properties (snake_case, string values in HTML)
+
+Web components reflect **string** attributes. Use JSON only where a future API requires it (not used here). Numbers and enums are plain strings.
+
+| Attribute | Required | Default (behavior) | Description |
+| --- | --- | --- | --- |
+| `id` | No | `""` | Passed through in `dashboardIndicatorClick` detail. |
+| `number` | No | `0` | Main KPI; pass as string, e.g. `"42"`. |
+| `text` | No | `""` | Caption under the number. |
+| `icon` | No | `"hypnotize"` in implementation | Bootstrap Icons name without `bi-` prefix. |
+| `link_label` | No | `""` | If set, shows footer and enables click + event. |
+| `karma` | No | `"success"` | Accent mode; see Behavior. |
+| `style` | No | — | Standard HTML: useful to set `--hb--dashboard-indicator-background` and other variables on the host. |
+
+---
+
+## Events
+
+Listen with `addEventListener` or framework equivalents.
+
+| Event name | `event.detail` | When it fires |
 | --- | --- | --- |
-| `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`. |
+| **`dashboardIndicatorClick`** | `{ id: string }` | User **clicks** the **footer** while `link_label` is set. `id` matches the element’s `id` attribute / property (empty string if unset). |
+
+TypeScript (consumer-side):
+
+```ts
+el.addEventListener("dashboardIndicatorClick", (e: CustomEvent<{ id: string }>) => {
+  console.log(e.detail.id);
+});
+```
+
+---
+
+## CSS custom properties
+
+Documented in `extra/docs.ts` / `styleSetup.vars`. Set on **`hb-dashboard-indicator`** (`:host`) unless your bundler wraps the element.
 
-**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.
+| Variable | Role |
+| --- | --- |
+| **`--hb--dashboard-indicator-background`** | When **`karma="none"`**: header **background** and footer **foreground** (label + arrow). If unset, falls back to Bulma **success** semantic color. **Ignored** when `karma` is any Bulma semantic value. |
+| **`--bulma-block-spacing`** | Horizontal padding in header and footer row (default `1rem` in CSS). |
+| **`--bulma-background`** | Footer strip **surface** color; when unset, SCSS uses scheme HSL fallbacks (`--bulma-scheme-h`, `--bulma-scheme-s`, `--bulma-background-l`, etc.). |
 
-### Events (`CustomEvent` names)
+Additional **`--bulma-*-h` / `-s` / `-l`** (and defaults `--bulma-hb-def-*`) on `:host` control semantic karma colors per [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).
 
-- **`dashboardIndicatorClick`** — `{ id: string }`
+### `::part` names
 
-### Usage notes
+**None** — `cssParts` is empty.
 
-- 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`.
+### Slots
 
-### Minimal HTML example
+**None** — `htmlSlots` is empty; all content is props-driven.
+
+---
+
+## Typings (`types/webcomponent.type.d.ts`)
+
+### `Karma`
+
+```ts
+export type Karma =
+  | "success"
+  | "danger"
+  | "warning"
+  | "primary"
+  | "secondary"
+  | "info"
+  /** Use `--hb--dashboard-indicator-background` on the host instead of Bulma `karma` tokens. */
+  | "none";
+```
+
+### `Component`
+
+```ts
+export type Component = {
+  id?: string;
+  style?: string;
+  number?: number;
+  text?: string;
+  icon?: string;
+  link_label?: string;
+  karma?: Karma;
+};
+```
+
+### `Events`
+
+```ts
+export type Events = {
+  dashboardIndicatorClick: { id: string };
+};
+```
+
+Generated builds also emit **`types/html-elements.d.ts`** and **`types/svelte-elements.d.ts`** under the package output for DOM and Svelte typings.
+
+---
+
+## Examples
+
+### Minimal tile with footer and Bulma success accent
 
 ```html
 <hb-dashboard-indicator
@@ -48,14 +192,66 @@ Compact KPI tile: large `number`, caption `text`, configurable Bootstrap Icon, a
 ></hb-dashboard-indicator>
 ```
 
-### Custom color (`karma="none"`)
+### Danger accent (queue / errors)
+
+```html
+<hb-dashboard-indicator
+  id="kpi-failures"
+  number="3"
+  text="Failed jobs"
+  icon="exclamation-triangle"
+  link_label="Open queue"
+  karma="danger"
+></hb-dashboard-indicator>
+```
+
+### Custom brand color (`karma="none"`)
 
 ```html
 <hb-dashboard-indicator
+  id="kpi-custom"
   karma="none"
   style="--hb--dashboard-indicator-background: #6366f1"
   number="12"
-  text="Custom"
+  text="Custom metric"
   icon="stars"
+  link_label="Details"
+></hb-dashboard-indicator>
+```
+
+### No footer (display-only KPI)
+
+```html
+<hb-dashboard-indicator
+  number="11"
+  text="Active sessions"
+  icon="window"
+  karma="primary"
 ></hb-dashboard-indicator>
 ```
+
+### Vanilla JS: handle navigation by `id`
+
+```html
+<hb-dashboard-indicator
+  id="orders"
+  number="54"
+  text="Open orders"
+  icon="inbox"
+  link_label="Go to inbox"
+  karma="warning"
+></hb-dashboard-indicator>
+<script>
+  document.querySelector("hb-dashboard-indicator").addEventListener("dashboardIndicatorClick", (e) => {
+    if (e.detail.id === "orders") {
+      location.assign("/inbox");
+    }
+  });
+</script>
+```
+
+---
+
+## i18n
+
+None configured in `extra/docs.ts` (`i18nLanguages` is empty). All visible strings are supplied by the host via attributes.

package/manifest.json

@@ -57,10 +57,6 @@
               "type": "string"
             }
           },
-          "required": [
-            "number",
-            "icon"
-          ],
           "type": "object"
         },
         "Karma": {
@@ -124,7 +120,19 @@
         "name": "--hb--dashboard-indicator-background",
         "valueType": "color",
         "defaultValue": "",
-        "description": "Header background and footer accent color. Used when `karma=\"none\"` (any valid CSS color). If unset with `karma=\"none\"`, falls back to Bulma `success`. Ignored when `karma` is a Bulma semantic value."
+        "description": "Header background and footer link color when `karma` is `none` (any valid CSS color). If unset, falls back to Bulma semantic `success`. Ignored for other `karma` values (those use Bulma `--bulma-*-h/s/l` palettes)."
+      },
+      {
+        "name": "--bulma-block-spacing",
+        "valueType": "number",
+        "defaultValue": "1rem",
+        "description": "Horizontal padding in the card header and footer strip."
+      },
+      {
+        "name": "--bulma-background",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Footer strip surface color (with scheme fallbacks in CSS when unset)."
       }
     ],
     "parts": []
@@ -195,5 +203,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-dashboard-indicator",
-  "version": "0.71.35"
+  "version": "0.71.37"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-dashboard-indicator",
-  "version": "0.71.35",
+  "version": "0.71.37",
   "contributors": [],
   "description": "Compact KPI tile: large `number`, caption `text`, configurable Bootstrap Icon, and `karma` accent (`success` | `danger` | `warning` | `primary` | `secondary` | `info`) using Bulma theme tokens (`secondary` maps to Bulma `dark`), or `karma=\"none\"` with host CSS variable `--hb--dashboard-indicator-background` for a custom color. When `link_label` is set, a footer strip is shown and clicks dispatch `dashboardIndicatorClick` with the component `id`.",
   "licenses": [

package/types/webcomponent.type.d.json

@@ -28,10 +28,6 @@
           "type": "string"
         }
       },
-      "required": [
-        "number",
-        "icon"
-      ],
       "type": "object"
     },
     "Karma": {

package/types/webcomponent.type.d.ts

@@ -11,9 +11,9 @@ export type Karma =
 export type Component = {
 	id?: string;
 	style?: string;
-	number: number;
+	number?: number;
 	text?: string;
-	icon: string;
+	icon?: string;
 	link_label?: string;
 	/**
 	 * Semantic accent from Bulma (`secondary` → `dark` tokens), or `none` for a custom host color via