@htmlbricks/hb-gauge 0.71.36 → 0.72.0

package/README.md

@@ -1,109 +1,53 @@
-## `hb-gauge` — gauge
+# hb-gauge
 
-**Category:** data  
-**Tags:** data, chart
+**Category:** data · **Tags:** data, chart
 
-### Overview
+## Summary
 
-`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.
+**JustGage** SVG gauge inside the shadow root: pass **`options`** as JSON (or object from JS). Created on mount, destroyed on teardown, recreated on window **resize** (200 ms debounce) and when **`options`** is reparsed from a string.
 
-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
+## Custom element
 
 `hb-gauge`
 
-### Attributes (snake_case; string values from HTML)
+## Attributes
 
-| Attribute | Required | Description |
+| Attribute | Type (logical) | HTML / notes |
 | --- | --- | --- |
-| `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.
-
-### 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
+| `options` | `string` \| `GaugeOptions` | **Required** for a useful chart. Merged with `{ element: #gauge }` before JustGage. Minimum: **`value`**, **`min`**, **`max`**; extra keys follow JustGage. |
+| `id` | `string` (optional) | |
+| `style` | `string` (optional) | Typings only; host `style` still applies to `<hb-gauge>`. |
 
-None declared for this component.
+## Custom events
 
-### Styling
+**None** — `Events` is `{}`.
 
-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.
+## Styling
 
-#### CSS custom properties
+### CSS custom properties (`extra/docs.ts`)
 
-| Variable | Description |
+| Variable | Role |
 | --- | --- |
-| `--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. |
+| `--hb-gauge-min-height` | Reserved vertical space on `:host` before paint. |
 
-#### CSS parts
+### CSS parts (`extra/docs.ts`)
 
-| Part | Description |
+| Part | Role |
 | --- | --- |
-| `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**
+| `gauge` | Mount node `#gauge` (`width: 100%`). |
 
-```html
-<hb-gauge options='{"value":25,"min":0,"max":100}'></hb-gauge>
-```
+### Slots
 
-**Wider numeric range**
+**None.**
 
-```html
-<hb-gauge options='{"value":250,"min":0,"max":500}'></hb-gauge>
-```
+Bulma is bundled for consistency; the visible dial is SVG from JustGage.
 
-**Value at the upper bound**
+## TypeScript
 
-```html
-<hb-gauge options='{"value":100,"min":0,"max":100}'></hb-gauge>
-```
+`types/webcomponent.type.d.ts` — `Component`, `IGauge`, `GaugeOptions`, `Events`.
 
-**Host sizing and minimum height**
+## Minimal HTML example
 
 ```html
-<hb-gauge
-  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>
+<hb-gauge options='{"value":50,"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

@@ -21,7 +21,15 @@
               "type": "string"
             },
             "options": {
-              "$ref": "#/definitions/IGauge"
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "$ref": "#/definitions/GaugeOptions"
+                }
+              ],
+              "description": "JSON string from HTML, or an object when set from JavaScript."
             },
             "style": {
               "type": "string"
@@ -32,8 +40,8 @@
           ],
           "type": "object"
         },
-        "IGauge": {
-          "additionalProperties": false,
+        "GaugeOptions": {
+          "description": "JustGage constructor options merged with `{ element }` in the component.",
           "properties": {
             "max": {
               "type": "number"
@@ -46,9 +54,9 @@
             }
           },
           "required": [
-            "value",
+            "max",
             "min",
-            "max"
+            "value"
           ],
           "type": "object"
         }
@@ -148,5 +156,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-gauge",
-  "version": "0.71.36"
+  "version": "0.72.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-gauge",
-  "version": "0.71.36",
+  "version": "0.72.0",
   "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": [

package/types/webcomponent.type.d.json

@@ -9,7 +9,15 @@
           "type": "string"
         },
         "options": {
-          "$ref": "#/definitions/IGauge"
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "$ref": "#/definitions/GaugeOptions"
+            }
+          ],
+          "description": "JSON string from HTML, or an object when set from JavaScript."
         },
         "style": {
           "type": "string"
@@ -20,8 +28,8 @@
       ],
       "type": "object"
     },
-    "IGauge": {
-      "additionalProperties": false,
+    "GaugeOptions": {
+      "description": "JustGage constructor options merged with `{ element }` in the component.",
       "properties": {
         "max": {
           "type": "number"
@@ -34,9 +42,9 @@
         }
       },
       "required": [
-        "value",
+        "max",
         "min",
-        "max"
+        "value"
       ],
       "type": "object"
     }

package/types/webcomponent.type.d.ts

@@ -4,10 +4,14 @@ export type IGauge = {
 	max: number;
 };
 
+/** JustGage constructor options merged with `{ element }` in the component. */
+export type GaugeOptions = IGauge & Record<string, unknown>;
+
 export type Component = {
 	id?: string;
 	style?: string;
-	options: IGauge;
+	/** JSON string from HTML, or an object when set from JavaScript. */
+	options: string | GaugeOptions;
 };
 
 export type Events = {};