gaugeit.js 0.1.0 → 0.1.1

package/docs/ai/library-usage.md

@@ -0,0 +1,875 @@
+# Using Gaugeit.js effectively
+
+This guide is written for an AI that must generate working Gaugeit.js 0.1.1
+integration code without guessing. It focuses on selecting the correct distribution,
+creating and updating gauges, integrating lifecycle ownership, and avoiding the most
+common package and browser mistakes.
+
+For individual option fields, read `options-reference.md`. For complete copy-ready
+files, read `integration-recipes.md`.
+
+## Fast decision tree
+
+Use this decision order:
+
+1. **React application?**
+   - Import the component from `gaugeit.js/react`.
+   - Import `gaugeit.js/css` once.
+   - Keep frequently recreated option objects stable with `useMemo`.
+   - Use a ref when imperative instance methods are needed.
+
+2. **Bundler or native ESM application?**
+   - Import from `gaugeit.js`.
+   - Import `gaugeit.js/css`.
+   - In a browser without a package resolver, import `dist/gaugeit.esm.js` by URL and
+     include `dist/gaugeit.css`.
+
+3. **CommonJS application?**
+   - `require('gaugeit.js')`.
+   - Ensure the application also loads or bundles the CSS.
+
+4. **Plain HTML with two cacheable files?**
+   - Include `gaugeit.min.css`.
+   - Include `gaugeit.umd.min.js`.
+   - Use the global `Gaugeit`.
+
+5. **Plain HTML that must use one JavaScript file?**
+   - Include `gaugeit.standalone.min.js`.
+   - Do not add separate Gaugeit CSS unless intentionally overriding it.
+   - Use the global `Gaugeit`.
+
+6. **PHP or Composer-managed server-rendered application?**
+   - Install `kasperi/gaugeit-js`.
+   - Run `vendor/bin/gaugeit-install-assets`.
+   - Include the copied CSS and UMD bundle from a public path.
+   - Render normal host elements and initialize in browser JavaScript.
+
+7. **Declarative custom element?**
+   - Load a normal Gaugeit distribution.
+   - Call `Gaugeit.defineGaugeitElement()` or import
+     `defineGaugeitElement` from `gaugeit.js/web-component`.
+   - Use `<gauge-it>` attributes.
+
+8. **Declarative data attributes?**
+   - Add `data-gaugeit`.
+   - Load a normal Gaugeit distribution.
+   - Call `Gaugeit.autoMount()` after the elements exist.
+
+## Package and distribution matrix
+
+| Environment | JavaScript | CSS | API name |
+| --- | --- | --- | --- |
+| npm ESM | `gaugeit.js` | `gaugeit.js/css` | named exports or default `Gaugeit` |
+| npm CommonJS | `require('gaugeit.js')` | load separately | returned exports |
+| npm React | `gaugeit.js/react` | `gaugeit.js/css` | component `Gaugeit` |
+| npm custom element | `gaugeit.js/web-component` | `gaugeit.js/css` | `defineGaugeitElement` |
+| Browser UMD | `dist/gaugeit.umd.min.js` | `dist/gaugeit.min.css` | `window.Gaugeit` |
+| Browser standalone | `dist/gaugeit.standalone.min.js` | embedded | `window.Gaugeit` |
+| Browser ESM | `dist/gaugeit.esm.js` | `dist/gaugeit.css` | module exports |
+| Composer | copied UMD and CSS | copied CSS | `window.Gaugeit` |
+
+The UMD build does **not** inject CSS. The standalone build injects canonical CSS once
+using the stable `#gaugeit-styles` marker.
+
+## Installation
+
+### npm
+
+```bash
+npm install gaugeit.js@0.1.1
+```
+
+Recommended ESM usage:
+
+```js
+import { createGauge } from 'gaugeit.js';
+import 'gaugeit.js/css';
+
+const gauge = createGauge('#speed', {
+  type: 'arc',
+  min: 0,
+  max: 240,
+  value: 88
+});
+```
+
+Default-object usage:
+
+```js
+import Gaugeit from 'gaugeit.js';
+import 'gaugeit.js/css';
+
+const gauge = Gaugeit.createGauge('#speed', {
+  type: 'classic',
+  value: 42
+});
+```
+
+### CommonJS
+
+```js
+const { createGauge } = require('gaugeit.js');
+
+const gauge = createGauge(document.querySelector('#speed'), {
+  type: 'line-scale',
+  value: 42
+});
+```
+
+CommonJS resolves the JavaScript entry. CSS still belongs to the consuming application's
+asset pipeline or page.
+
+### Native browser ESM
+
+```html
+<link rel="stylesheet" href="./dist/gaugeit.css">
+<div id="temperature"></div>
+
+<script type="module">
+  import { createGauge } from './dist/gaugeit.esm.js';
+
+  createGauge('#temperature', {
+    type: 'classic',
+    min: -20,
+    max: 120,
+    value: 68
+  });
+</script>
+```
+
+A native browser cannot resolve the bare package specifier `gaugeit.js` unless an
+import map, bundler, or server-side package resolver is present.
+
+### UMD with separate CSS
+
+```html
+<link rel="stylesheet" href="./dist/gaugeit.min.css">
+
+<div id="score"></div>
+
+<script src="./dist/gaugeit.umd.min.js"></script>
+<script>
+  const gauge = Gaugeit.createGauge('#score', {
+    type: 'arc',
+    min: 0,
+    max: 100,
+    value: 64
+  });
+</script>
+```
+
+The global name is exactly `Gaugeit`. It is not `GaugeIt`, `GaugeIT`, or `gaugeit`.
+
+### Standalone one-file browser build
+
+```html
+<div id="score"></div>
+
+<script src="./dist/gaugeit.standalone.min.js"></script>
+<script>
+  Gaugeit.createGauge('#score', {
+    type: 'classic',
+    value: 64
+  });
+</script>
+```
+
+Standalone is appropriate when one JavaScript file is more important than separately
+cacheable CSS. It contains the same public API as UMD.
+
+### jsDelivr
+
+Use exact versions in production:
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/gaugeit.js@0.1.1/dist/gaugeit.min.css"
+>
+<script
+  src="https://cdn.jsdelivr.net/npm/gaugeit.js@0.1.1/dist/gaugeit.umd.min.js"
+></script>
+```
+
+One-file form:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/gaugeit.js@0.1.1/dist/gaugeit.standalone.min.js"
+></script>
+```
+
+### UNPKG
+
+```html
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/gaugeit.js@0.1.1/dist/gaugeit.min.css"
+>
+<script
+  src="https://unpkg.com/gaugeit.js@0.1.1/dist/gaugeit.umd.min.js"
+></script>
+```
+
+One-file form:
+
+```html
+<script
+  src="https://unpkg.com/gaugeit.js@0.1.1/dist/gaugeit.standalone.min.js"
+></script>
+```
+
+Do not omit the version in production examples. An unpinned CDN URL may change after a
+new release.
+
+### Composer
+
+```bash
+composer require kasperi/gaugeit-js:^0.1
+vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit
+```
+
+Default installed assets:
+
+```text
+gaugeit.umd.min.js
+gaugeit.min.css
+```
+
+Other modes:
+
+```bash
+vendor/bin/gaugeit-install-assets --standalone public/assets/vendor/gaugeit
+vendor/bin/gaugeit-install-assets --all public/assets/vendor/gaugeit
+vendor/bin/gaugeit-install-assets --clean public/assets/vendor/gaugeit
+```
+
+`--clean` removes only known Gaugeit.js assets from the destination. It preserves
+unrelated files. Composer consumers use prebuilt assets and do not need Node.js.
+
+Gaugeit.js does not write into an application's public directory automatically during
+dependency installation. The consuming project owns the explicit asset-copy command.
+
+## Built-in types
+
+Use one of these exact names:
+
+| Type | Geometry family | Intended use |
+| --- | --- | --- |
+| `arc` | radial | lightweight semicircular zones and pointer |
+| `classic` | radial | framed vintage analog instrument |
+| `heritage-round` | radial | circular glass-fronted 270-degree instrument |
+| `line-scale` | radial | dense configurable tick-focused scale |
+| `classic-linear` | linear | framed straight scale with moving indicator |
+| `classic-linear-zero` | linear | signed straight scale with fixed zero marker |
+| `center-zero` | radial | signed heritage dial around a center reference |
+| `rolling-tape` | tape | moving numeric strip behind a fixed reference line |
+
+Do not infer geometry solely from the visual name. The selected type supplies the
+correct geometry mode and layer family.
+
+## Minimal creation
+
+The target may be an element or a CSS selector:
+
+```js
+const gauge = Gaugeit.createGauge('#gauge', {
+  type: 'arc',
+  value: 72
+});
+```
+
+Equivalent element form:
+
+```js
+const host = document.querySelector('#gauge');
+const gauge = Gaugeit.createGauge(host, {
+  type: 'arc',
+  value: 72
+});
+```
+
+The target must exist before creation. Creating another managed gauge on the same host
+destroys the previous managed instance.
+
+## A practical configuration pattern
+
+```js
+const gauge = Gaugeit.createGauge('#engine-load', {
+  type: 'arc',
+  min: 0,
+  max: 100,
+  value: 38,
+  zones: [
+    { min: 0, max: 60, color: '#22c55e' },
+    { min: 60, max: 85, color: '#facc15' },
+    { min: 85, max: 100, color: '#ef4444' }
+  ],
+  readout: {
+    title: {
+      visible: true,
+      text: 'ENGINE LOAD'
+    },
+    value: {
+      visible: true,
+      suffix: '%'
+    }
+  },
+  accessibility: {
+    label: 'Engine load',
+    valueText: (value) => `${Math.round(value)} percent`
+  }
+});
+```
+
+Prefer normal option objects over DOM manipulation of generated SVG.
+
+## Updating values
+
+Use `setValue()` for ordinary numeric updates:
+
+```js
+gauge.setValue(76);
+gauge.setValue(18, {
+  duration: 1400,
+  easing: 'easeInOutCubic'
+});
+gauge.setValue(50, {
+  animate: false
+});
+```
+
+`set()` is an alias:
+
+```js
+gauge.set(64);
+```
+
+Do not call `updateOptions({ value })` for a high-frequency value stream unless the
+configuration must also be rebuilt. `setValue()` updates dynamic controllers without
+re-rendering static layers.
+
+## Updating options
+
+Deep-merge a partial patch:
+
+```js
+gauge.updateOptions({
+  pointer: {
+    type: 'line',
+    color: '#dc2626'
+  },
+  labels: {
+    fractionDigits: 1
+  }
+});
+```
+
+`setOptions()` is an alias for `updateOptions()`.
+
+Replace all earlier instance overrides:
+
+```js
+gauge.replaceOptions({
+  type: 'classic',
+  min: 0,
+  max: 100,
+  value: 42
+});
+```
+
+Arrays are replaced, not concatenated. Therefore:
+
+```js
+gauge.updateOptions({
+  zones: [
+    { min: 0, max: 100, color: '#22c55e' }
+  ]
+});
+```
+
+replaces the previous complete zone list.
+
+When `updateOptions()` or `replaceOptions()` includes `value`, the value is applied
+immediately by default. Pass `{ animateToValue: true }` as the second argument to
+animate after the rebuild:
+
+```js
+gauge.updateOptions(
+  {
+    value: 90,
+    pointer: { color: '#dc2626' }
+  },
+  {
+    animateToValue: true
+  }
+);
+```
+
+## Reading values
+
+```js
+const requested = gauge.getValue();
+const displayed = gauge.getDisplayedValue();
+```
+
+- `getValue()` returns the stable requested target.
+- `getDisplayedValue()` returns the current animated base value.
+- Neither method returns the jittered pointer-only visual value.
+
+## Lifecycle
+
+```js
+gauge.pause();
+gauge.resume();
+gauge.refresh();
+gauge.destroy();
+```
+
+- `pause()` stops active animation and jitter work.
+- `resume()` continues pending visual work without counting paused time.
+- `refresh()` rebuilds the gauge from current options. Use it after relevant fonts,
+  CSS variables, or external plugin state changes.
+- `destroy()` releases animation frames, observers, listeners, controller resources,
+  and generated content.
+
+Do not call instance methods after `destroy()`.
+
+## Overflow behavior
+
+```js
+overflow: 'clamp'
+```
+
+- `clamp`: incoming values are constrained to `min ... max`.
+- `expand`: an incoming out-of-range value expands the configured range and re-renders.
+- `allow`: stores and renders out-of-range values without changing the configured
+  range; display clamping is disabled.
+
+Use `clamp` unless the application explicitly needs one of the other contracts.
+
+## Inversion
+
+```js
+invert: true
+```
+
+Inversion reverses visual direction without changing the numeric definitions. Zones
+remain attached to their numeric values. Do not reverse zone arrays or swap their
+numeric endpoints to implement inversion.
+
+## Responsive layout
+
+Default layout is intrinsic and responsive:
+
+```js
+layout: {
+  mode: 'intrinsic',
+  padding: 8,
+  includeGeometry: true
+},
+responsive: true
+```
+
+The host should have an available width. Gaugeit.js applies responsive SVG sizing and
+calculates a content-aware viewBox.
+
+For a fixed-size card area, constrain the host with CSS and use contain mode:
+
+```css
+.dashboard-gauge {
+  width: 320px;
+  height: 220px;
+}
+```
+
+```js
+Gaugeit.createGauge('.dashboard-gauge', {
+  type: 'heritage-round',
+  layout: {
+    mode: 'contain'
+  }
+});
+```
+
+Do not set only a zero or collapsed parent size and expect SVG to invent page layout.
+
+## Readouts
+
+The readout group is enabled by default, but individual parts are not all visible:
+
+```js
+readout: {
+  visible: true,
+  title: {
+    visible: true,
+    text: 'PRESSURE'
+  },
+  value: {
+    visible: true,
+    fractionDigits: 1
+  },
+  unit: {
+    visible: true,
+    text: 'bar'
+  }
+}
+```
+
+`readout.visible: true` alone does not enable `title`, `value`, or `unit`.
+
+## Lights
+
+Every built-in type includes the shared light layer. A partial object inherits shared
+defaults:
+
+```js
+light: {
+  visible: true
+}
+```
+
+A threshold light:
+
+```js
+light: {
+  visible: true,
+  color: 'red',
+  trigger: {
+    mode: 'above',
+    source: 'target',
+    value: 85
+  }
+}
+```
+
+Trigger sources:
+
+- `target`: stable requested value; default and usually best for warnings;
+- `displayed`: current animated base value;
+- `pointer`: animated value plus visual jitter.
+
+Effect interaction:
+
+- blink takes precedence over pulse;
+- flicker may overlay blink or pulse;
+- pulse and flicker run only while the light is active;
+- reduced-motion preference suppresses the motion effects;
+- `glowRadius` is independent from lamp `radius` in 0.1.1;
+- `glowOpacity` is independent from illuminated-lens `opacity`.
+
+For a deterministic steady light, disable all motion:
+
+```js
+light: {
+  visible: true,
+  glow: true,
+  pulse: false,
+  blink: false,
+  flicker: false,
+  trigger: {
+    mode: 'manual'
+  },
+  on: true
+}
+```
+
+## Data-attribute mounting
+
+```html
+<div
+  data-gaugeit
+  data-gaugeit-type="arc"
+  data-gaugeit-min="0"
+  data-gaugeit-max="100"
+  data-gaugeit-value="63"
+  data-gaugeit-options='{"animation":{"startFrom":"value"}}'
+></div>
+
+<script src="./dist/gaugeit.umd.min.js"></script>
+<script>
+  Gaugeit.autoMount();
+</script>
+```
+
+Supported dataset fields are translated into normal options. The JSON in
+`data-gaugeit-options` must be valid JSON, not JavaScript object syntax. Auto-mounting
+is duplicate-safe.
+
+A custom selector and root are supported:
+
+```js
+Gaugeit.autoMount('[data-dashboard-gauge]', document.querySelector('#dashboard'));
+```
+
+Managed-instance helpers:
+
+```js
+const host = document.querySelector('#gauge');
+const instance = Gaugeit.getMountedGauge(host);
+const existed = Gaugeit.unmountGauge(host);
+```
+
+## Custom element
+
+```html
+<script src="./dist/gaugeit.umd.min.js"></script>
+<script>
+  Gaugeit.defineGaugeitElement();
+</script>
+
+<gauge-it
+  type="classic"
+  min="0"
+  max="240"
+  value="88"
+  options='{"readout":{"title":{"visible":true,"text":"VOLTAGE"}}}'
+></gauge-it>
+```
+
+Observed attributes are `value`, `min`, `max`, `type`, and `options`. Attribute changes
+replace the complete declarative option object. The element destroys its instance when
+disconnected.
+
+With npm:
+
+```js
+import { defineGaugeitElement } from 'gaugeit.js/web-component';
+import 'gaugeit.js/css';
+
+defineGaugeitElement();
+```
+
+## React
+
+```jsx
+import { useMemo, useState } from 'react';
+import Gaugeit from 'gaugeit.js/react';
+import 'gaugeit.js/css';
+
+export default function LoadGauge() {
+  const [value, setValue] = useState(62);
+
+  const options = useMemo(() => ({
+    type: 'arc',
+    min: 0,
+    max: 100,
+    zones: [
+      { min: 0, max: 60, color: '#22c55e' },
+      { min: 60, max: 85, color: '#facc15' },
+      { min: 85, max: 100, color: '#ef4444' }
+    ]
+  }), []);
+
+  return (
+    <Gaugeit
+      value={value}
+      options={options}
+      className="load-gauge"
+    />
+  );
+}
+```
+
+React owns the host element. Gaugeit.js owns only the generated content inside it. The
+adapter:
+
+- creates an instance on mount;
+- replaces the complete options object when `options` identity changes;
+- keeps explicit `value` authoritative;
+- forwards a ref to the live `Gauge` instance;
+- destroys the instance on unmount.
+
+Do not import the source adapter by repository-relative path from an installed package.
+Use `gaugeit.js/react`.
+
+## Laravel Blade
+
+After Composer asset installation, a Blade page may include:
+
+```blade
+@push('styles')
+  <link
+    rel="stylesheet"
+    href="{{ asset('assets/vendor/gaugeit/gaugeit.min.css') }}"
+  >
+@endpush
+
+<div
+  id="pressure-gauge"
+  data-gauge-options='@json([
+    "type" => "classic",
+    "min" => 0,
+    "max" => 10,
+    "value" => $pressure,
+  ])'
+></div>
+
+@push('scripts')
+  <script src="{{ asset('assets/vendor/gaugeit/gaugeit.umd.min.js') }}"></script>
+  <script>
+    document.addEventListener('DOMContentLoaded', () => {
+      const host = document.querySelector('#pressure-gauge');
+      const options = JSON.parse(host.dataset.gaugeOptions);
+      Gaugeit.createGauge(host, options);
+    });
+  </script>
+@endpush
+```
+
+The PHP layer emits data. Browser JavaScript creates the SVG gauge.
+
+## Twig
+
+```twig
+<link
+  rel="stylesheet"
+  href="{{ asset('assets/vendor/gaugeit/gaugeit.min.css') }}"
+>
+
+<div
+  id="temperature-gauge"
+  data-options="{{ {
+    type: 'classic',
+    min: -20,
+    max: 120,
+    value: temperature
+  }|json_encode|e('html_attr') }}"
+></div>
+
+<script src="{{ asset('assets/vendor/gaugeit/gaugeit.umd.min.js') }}"></script>
+<script>
+  const host = document.querySelector('#temperature-gauge');
+  Gaugeit.createGauge(host, JSON.parse(host.dataset.options));
+</script>
+```
+
+Escape JSON for an HTML attribute. Do not place unescaped application data directly
+inside executable JavaScript.
+
+## Plain PHP
+
+```php
+<?php
+$options = [
+    'type' => 'arc',
+    'min' => 0,
+    'max' => 100,
+    'value' => $value,
+];
+?>
+
+<link rel="stylesheet" href="/assets/vendor/gaugeit/gaugeit.min.css">
+
+<div
+  id="status-gauge"
+  data-options="<?= htmlspecialchars(
+      json_encode($options, JSON_THROW_ON_ERROR),
+      ENT_QUOTES,
+      'UTF-8'
+  ) ?>"
+></div>
+
+<script src="/assets/vendor/gaugeit/gaugeit.umd.min.js"></script>
+<script>
+  const host = document.querySelector('#status-gauge');
+  Gaugeit.createGauge(host, JSON.parse(host.dataset.options));
+</script>
+```
+
+## DOM events
+
+Events are dispatched from the host element:
+
+```js
+const host = document.querySelector('#gauge');
+
+host.addEventListener('gaugeit:change', (event) => {
+  console.log(event.detail.value);
+});
+
+host.addEventListener('gaugeit:settled', (event) => {
+  console.log(event.detail.displayedValue);
+});
+```
+
+Available event names:
+
+```text
+gaugeit:render
+gaugeit:change
+gaugeit:displaychange
+gaugeit:animationstart
+gaugeit:animationend
+gaugeit:settled
+gaugeit:typechange
+gaugeit:pause
+gaugeit:resume
+gaugeit:destroy
+```
+
+Use namespaced events instead of global callbacks.
+
+## Custom types
+
+Register a type before creating instances that use it:
+
+```js
+Gaugeit.registerGaugeType('compact-status', {
+  description: 'Compact dashboard status gauge.',
+  defaults: {
+    geometry: {
+      width: 260,
+      height: 150,
+      centerX: 130,
+      centerY: 132,
+      startAngle: 200,
+      endAngle: 340
+    },
+    pointer: {
+      type: 'arrow',
+      length: 75,
+      width: 6
+    }
+  },
+  layers: [
+    Gaugeit.layers.face,
+    Gaugeit.layers.zones,
+    Gaugeit.layers.ticks,
+    Gaugeit.layers.labels,
+    Gaugeit.layers.light,
+    Gaugeit.layers.readout,
+    Gaugeit.layers.pointer
+  ]
+});
+```
+
+Layer order is paint order. In the example, the pointer is last so it paints above the
+readout.
+
+## Accessibility
+
+Always provide a meaningful label for production gauges:
+
+```js
+accessibility: {
+  label: 'Battery charge',
+  description: 'Remaining charge in the main battery.',
+  valueText: (value) => `${Math.round(value)} percent`
+}
+```
+
+The generated root uses `role="meter"` and updates `aria-valuemin`,
+`aria-valuemax`, `aria-valuenow`, and optional `aria-valuetext`.
+
+A visually decorative gauge still needs an intentional accessibility decision. Do not
+silently remove meter semantics from the library.
+
+## Browser support assumptions
+
+Gaugeit.js uses modern browser APIs and targets ES2018-compatible runtime behavior.
+When generating code for an older environment, do not mutate Gaugeit.js source
+arbitrarily. Add an application-level transpilation or compatibility plan.
+
+The optional `test:chromium` development command expects a globally available
+`chromium` executable. That requirement does not apply to normal library consumers.