@htmlbricks/hb-gauge 0.71.34 → 0.71.36

package/README.md

@@ -3,32 +3,107 @@
 **Category:** data  
 **Tags:** data, chart
 
-### What it does
+### Overview
 
-SVG gauge wrapper around JustGage: pass JustGage-compatible options as JSON (`value`, min/max, labels, colors, etc.). The gauge is created on the shadow host after mount, destroyed on teardown, and recreated when `options` changes or the window resizes (debounced) so it stays sized correctly.
+`hb-gauge` is a web component that embeds **JustGage** (SVG gauges via Raphael; vendored as `libs/justgage.js` in this package) inside the shadow root. You pass a single JSON payload that mirrors JustGage’s configuration object. After mount, the library instantiates the gauge on an internal mount node; on destroy it tears the instance down cleanly.
+
+The gauge is **recreated** when the window is resized (handled with a **200 ms debounce**) so the SVG keeps a sensible size relative to the host. When `options` is supplied as a **string**, the component parses it with `JSON.parse`; if a gauge instance already exists, that parse path triggers a **rebuild** so the new JSON takes effect. (If you bind `options` as an object in a Svelte host, rely on resize or remount for full redraw unless your integration matches the string-based update path.)
+
+There are **no custom events** on this element (`Events` is empty in the public typings).
 
 ### Custom element
 
 `hb-gauge`
 
-### Attributes (snake_case; use string values in HTML)
+### Attributes (snake_case; string values from HTML)
+
+| Attribute | Required | Description |
+| --- | --- | --- |
+| `options` | yes | JSON string describing the gauge. Merged with `{ element }` pointing at the internal `#gauge` node before constructing JustGage. You must include at least **`value`**, **`min`**, and **`max`** for a sensible dial; any additional keys supported by your bundled JustGage build (labels, colors, `gaugeWidthScale`, donut mode, etc.) can be added in the same object. |
+| `id` | no | Optional string identifier (forwarded through the component props). |
+
+From HTML, **`options` is always a string**: pass a serialized JSON object (see examples below). The implementation may parse that string when it runs as a web component.
+
+The authoring TypeScript type `Component` also lists optional `style`; the current Svelte implementation does not wire a dedicated `style` prop—you can still apply ordinary host styling (for example `width`, `height`, or `min-height`) on `<hb-gauge>` itself, and use **`--hb-gauge-min-height`** for layout reserve before paint.
 
-- `id` — optional string  
-- `style` — optional string  
-- `options` — required string (JSON object; at minimum `value`, `min`, `max`; additional keys follow JustGage)
+### TypeScript shape (`Component`)
+
+For editors and wrappers that import `Component` from `types/webcomponent.type.d.ts`:
+
+- **`options`** — in typings this is modeled as `IGauge` (`value`, `min`, `max`). At runtime the same object is spread into JustGage, so real configs are often richer than `IGauge`; treat the type as a **minimum** contract and refer to JustGage for the full option surface.
+- **`id`** — optional string.
+- **`style`** — optional string in the type file only; see note above for styling the host.
 
 ### Events
 
-None declared on the component type.
+None declared for this component.
+
+### Styling
+
+Bulma styles are included in the shadow bundle for consistency with other HTML Bricks components, but the visible gauge is drawn by JustGage (SVG), not Bulma layout primitives. Theme your app with **`--bulma-*`** tokens on the document if you want host-level consistency with the rest of the library.
+
+#### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--hb-gauge-min-height` | Minimum height of the `:host` element (default `0` in `styles/webcomponent.scss`). Use it when you need reserved vertical space before the gauge finishes laying out. |
+
+#### CSS parts
+
+| Part | Description |
+| --- | --- |
+| `gauge` | The JustGage mount node (`#gauge`). It is `width: 100%` by default; you can target this part to adjust width, height, or overflow behavior around the SVG. |
+
+#### Slots
+
+None.
+
+### Examples
+
+**Minimal 0–100 gauge**
+
+```html
+<hb-gauge options='{"value":50,"min":0,"max":100}'></hb-gauge>
+```
+
+**Quarter of the scale**
+
+```html
+<hb-gauge options='{"value":25,"min":0,"max":100}'></hb-gauge>
+```
 
-### Usage notes
+**Wider numeric range**
 
-CSS part: `gauge`. `options` may be passed as a JSON string; the component parses it when needed.
+```html
+<hb-gauge options='{"value":250,"min":0,"max":500}'></hb-gauge>
+```
 
-### Minimal HTML example
+**Value at the upper bound**
+
+```html
+<hb-gauge options='{"value":100,"min":0,"max":100}'></hb-gauge>
+```
+
+**Host sizing and minimum height**
 
 ```html
 <hb-gauge
-  options="{&quot;value&quot;:50,&quot;min&quot;:0,&quot;max&quot;:100}"
+  style="width: 280px; height: 200px;"
+  options='{"value":72,"min":0,"max":100}'
 ></hb-gauge>
 ```
+
+```html
+<hb-gauge
+  style="width: 100%;"
+  options='{"value":10,"min":0,"max":100}'
+></hb-gauge>
+```
+
+(Combine `style` on the custom element with `--hb-gauge-min-height` in your page CSS if you need a stable block size before the gauge renders.)
+
+### Implementation notes
+
+- The mount target is `<div part="gauge" id="gauge" style="width:100%">` inside the shadow tree; JustGage receives `Object.assign({ element: gaugeEl }, options)`.
+- If `options` arrives as a string, it is `JSON.parse`’d in an effect; when both the mount node and an existing instance exist, the gauge is **recreated** to pick up the new config.
+- Console logging is present in the source around mount for debugging (`gaugeEl`); remove or silence in production builds if that matters for your environment.

package/manifest.json

@@ -64,11 +64,18 @@
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--hb-gauge-min-height",
+        "valueType": "number",
+        "defaultValue": "0",
+        "description": "Minimum height of the host element before JustGage draws."
+      }
+    ],
     "parts": [
       {
         "name": "gauge",
-        "description": ""
+        "description": "JustGage mount node (`#gauge`); style width/height or overflow for the SVG gauge."
       }
     ]
   },
@@ -141,5 +148,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-gauge",
-  "version": "0.71.34"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-gauge",
-  "version": "0.71.34",
+  "version": "0.71.36",
   "contributors": [],
   "description": "SVG gauge wrapper around JustGage: pass JustGage-compatible options as JSON (`value`, min/max, labels, colors, etc.). The gauge is created on the shadow host after mount, destroyed on teardown, and recreated when `options` changes or the window resizes (debounced) so it stays sized correctly.",
   "licenses": [