gaugeit.js 0.1.0

package/dist/manifest.json

@@ -0,0 +1,24 @@
+{
+  "version": "0.1.0",
+  "files": {
+    "gaugeit.cjs": 162825,
+    "gaugeit.cjs.map": 302482,
+    "gaugeit.css": 7164,
+    "gaugeit.d.ts": 12569,
+    "gaugeit.esm.js": 163099,
+    "gaugeit.esm.js.map": 302721,
+    "gaugeit.esm.min.js": 85299,
+    "gaugeit.esm.min.js.map": 310871,
+    "gaugeit.min.cjs": 84896,
+    "gaugeit.min.cjs.map": 310031,
+    "gaugeit.min.css": 6024,
+    "gaugeit.standalone.js": 181580,
+    "gaugeit.standalone.js.map": 312102,
+    "gaugeit.standalone.min.js": 93212,
+    "gaugeit.standalone.min.js.map": 321180,
+    "gaugeit.umd.js": 173940,
+    "gaugeit.umd.js.map": 303897,
+    "gaugeit.umd.min.js": 86026,
+    "gaugeit.umd.min.js.map": 311361
+  }
+}

package/docs/api.md

@@ -0,0 +1,456 @@
+# API reference
+
+## Top-level functions
+
+### `createGauge(target, options?)`
+
+Creates a gauge and returns a `Gauge` instance. `target` may be an element or CSS selector. Creating another managed gauge on the same host destroys the earlier managed instance.
+
+### `registerGaugeType(name, definition)`
+
+Registers or replaces a type in the default registry.
+
+### `autoMount(selector = '[data-gaugeit]', root = document)`
+
+Creates gauges from matching elements. Repeated calls return existing auto-mounted instances instead of initializing them twice.
+
+### `defineGaugeitElement(tagName = 'gauge-it')`
+
+Defines an optional custom element and returns its constructor. Returns `null` when custom elements are unavailable.
+
+### `getMountedGauge(element)`
+
+Returns a managed instance or `null`.
+
+### `unmountGauge(element)`
+
+Destroys and removes a managed instance. Returns whether an instance existed.
+
+## Gauge methods
+
+### `setValue(value, options?)`
+
+Options:
+
+- `animate`: defaults to the instance animation setting;
+- `duration`: overrides duration for this update;
+- `easing`: overrides easing for this update.
+
+### `set(value, options?)`
+
+Alias for `setValue`.
+
+### `updateOptions(patch, behavior?)`
+
+Deeply merges a partial configuration into the original user options, validates the result, and re-renders. Arrays such as `zones` are replaced. Supplying `patch.value` updates the displayed value immediately unless `behavior.animateToValue` is enabled.
+
+`behavior.animateToValue` may be used to animate after the rebuild.
+
+### `setOptions(patch, behavior?)`
+
+Alias for `updateOptions`.
+
+### `replaceOptions(options, behavior?)`
+
+Replaces the complete user-option object instead of recursively merging a patch.
+The current target value is preserved unless `options.value` is supplied. An explicit
+value is displayed immediately unless `behavior.animateToValue` is enabled. This method
+is useful for declarative framework adapters and custom elements where removed keys
+must return to the selected type's fallback values.
+
+### `getValue()`
+
+Returns the stable requested value.
+
+### `getDisplayedValue()`
+
+Returns the current rendered base value, including animation but excluding pointer or indicator jitter.
+
+### `pause()` / `resume()`
+
+Stops or resumes active visual work.
+
+### `refresh()`
+
+Rebuilds the gauge from current options.
+
+### `destroy()`
+
+Cancels work, disconnects observers, removes listeners, and removes generated content.
+
+## Top-level options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `type` | `arc` | Registered gauge type name. |
+| `min` | `0` | Minimum scale value. |
+| `max` | `100` | Maximum scale value. |
+| `value` | `0` | Initial value. |
+| `invert` | `false` | Reverse the visual value direction without changing the numeric range. |
+| `overflow` | `clamp` | `clamp`, `expand`, or `allow`. |
+| `precision` | `3` | Internal displayed-value decimal precision. |
+| `className` | empty | Extra class on the generated root. |
+| `layout` | intrinsic | Content-aware sizing and fixed-host containment. |
+| `responsive` | `true` | Use width `100%` with SVG viewBox scaling. |
+
+
+## `layout`
+
+- `mode`: `intrinsic` or `contain`;
+- `padding`: extra SVG viewBox padding;
+- `includeGeometry`: retain the type's configured logical width and height as the minimum drawing area.
+
+`intrinsic` is the default. The renderer calculates conservative bounds for the face,
+arc, zones, scale, labels, pointer, and readouts, then expands the SVG viewBox. A
+360-degree gauge therefore occupies more document height instead of overflowing the
+next element. `contain` uses the same viewBox but fills a host whose CSS width and
+height are explicitly constrained.
+
+## `geometry`
+
+`Gaugeit.geometry.centeredArcAngles(sweep, centerAngle)` is a convenience helper for
+controls and presets. `centerAngle: 0` means the normal upright orientation, equivalent
+to SVG angle 270; positive values rotate clockwise. It returns `{ startAngle, endAngle }`.
+
+| Option | Purpose |
+| --- | --- |
+| `mode` | `radial`, `linear`, or `tape`; built-in types choose the correct mode. |
+| `width`, `height` | Logical SVG dimensions. Resizable linear and tape presets scale their fallback geometry from these values. |
+| `aspectRatio` | Optional positive ratio used by resizable presets to derive a missing width or height. |
+| `centerX`, `centerY` | Pointer pivot and arc center. |
+| `radius` | General type radius available to layers. |
+| `startAngle`, `endAngle` | Scale angles in SVG degrees. `180` to `360` is an upper semicircle from left to right. |
+| `preserveAspectRatio` | SVG aspect-ratio behavior. |
+
+The sweep may be clockwise or counter-clockwise and is limited to one full revolution.
+For `classic-linear`, `classic-linear-zero`, and `rolling-tape`, logical width and height
+also control the preset composition. CSS may independently constrain the rendered host;
+use `layout.mode: 'contain'` for a fixed-width and fixed-height host.
+
+## `linear`
+
+Linear gauge types define their axis independently from radial geometry:
+
+| Option | Purpose |
+| --- | --- |
+| `originY` | Internal SVG baseline used as public linear `y = 0`. |
+| `startX`, `startY` | Minimum-side axis point before applying `invert`; X increases rightward and Y upward. |
+| `endX`, `endY` | Maximum-side axis point before applying `invert`; X increases rightward and Y upward. |
+| `tickSide` | `negative`, `positive`, or `cross` relative to the axis normal. |
+| `labelOffset` | Label distance from the axis; positive is visually upward on a left-to-right axis. |
+| `zoneOffset` | Default track and zone distance; positive is visually upward on a left-to-right axis. |
+
+The two-point axis supports horizontal, vertical, and diagonal custom linear types.
+The built-in classic-linear preset uses `originY: 142`, `startY: 0`, and `endY: 0`, so
+changing Axis Y to a positive value moves the whole scale upward. Numeric linear readout
+Y coordinates use the same origin and positive-up convention; its title fallback is
+`y: 60`. `Gaugeit.geometry.valueToLinearPoint()`, `linearPointToValue()`, and
+`linearYToSvg()` expose the mapping used by the built-in layers.
+
+## `invert`
+
+`invert: true` mirrors value placement across the configured sweep: the maximum uses
+the normal minimum endpoint and the minimum uses the normal maximum endpoint. Pointer
+movement, ticks, labels, and zones all use the same mapping. Zone definitions remain
+numeric and unchanged, so a `{ min: 0, max: 15 }` low-value zone follows the low end of
+an inverted scale automatically.
+
+## `light`
+
+The optional shared annunciator lamp is available to every built-in type and to custom
+types that include `Gaugeit.layers.light`. It is disabled by default.
+
+```js
+light: {
+  visible: true,
+  x: 108,
+  y: 110,
+  radius: 10,
+  color: 'amber',
+  customColor: '',
+  offColor: '#f3ead6',
+  offEdgeColor: '#817768',
+  bezelColor: '#4b5563',
+  bezelHighlightColor: '#f8fafc',
+  opacity: 1,
+  on: false,
+  glow: true,
+  pulse: true,
+  pulseInterval: 2600,
+  blink: true,
+  blinkInterval: 1000,
+  trigger: { mode: 'below', source: 'target', value: 15, min: 0, max: 15 }
+}
+```
+
+- `visible`: render or omit the component;
+- `x`, `y`: logical SVG coordinates; linear Y values use the positive-up convention;
+- `radius`: bulb radius in logical gauge units;
+- `color`: `red`, `green`, `blue`, `amber`, `yellow`, `orange`, `white`, `halogen`, `cyan`, or `brown`;
+- `customColor`: optional CSS color overriding the selected active palette;
+- `offColor`, `offEdgeColor`: unlit diffused-lens center and edge colors;
+- `bezelColor`, `bezelHighlightColor`: panel-mount bezel colors;
+- `opacity`: total bulb opacity;
+- `on`: manual state used by `trigger.mode: 'manual'`;
+- `glow`: enable the active halo;
+- `pulse`, `pulseInterval`: subtle steady-light breathing effect and period;
+- `blink`: blink while the condition is active; the off half-cycle renders the full normal unlit-lens appearance instead of fading the whole lamp;
+- `blinkInterval`: complete blink period in milliseconds, minimum 100;
+- `trigger.mode`: `manual`, `below`, `above`, or `between`;
+- `trigger.value`: inclusive threshold for `below` and `above`;
+- `trigger.min`, `trigger.max`: inclusive bounds for `between`.
+
+The lamp evaluates the stable target value by default, preventing threshold delays during
+pointer animation. Set `trigger.source` to `displayed` to follow the animated value or to
+`pointer` to include visual jitter. Gradient stops use resolved color values rather than
+unresolved SVG custom-property references, keeping the lens rendering consistent across
+browsers and DOM test environments.
+
+## `face`
+
+`face` controls the optional old-style instrument background.
+
+Important fields:
+
+- `visible`;
+- `shape`: `panel` or `circle`;
+- `fit`: `geometry` or `content`;
+- `contentPadding`: spacing used when a content-fitted face expands;
+- `minWidth`, `minHeight`: optional lower limits for `fit: 'content'`;
+- `clipContent`: clip every later non-face layer to the inner bezel;
+- `x`, `y`, `width`, `height`;
+- `cornerRadius`;
+- `color`;
+- `strokeColor`, `strokeWidth`;
+- `innerStrokeColor`, `innerStrokeWidth`;
+- `shadow`;
+- `glass`.
+
+## `track`
+
+- `visible`;
+- `color`;
+- `width`;
+- `radius`;
+- `opacity`;
+- `lineCap`;
+- `showUnderZones`.
+
+When `showUnderZones` is `false`, transparent zones are gaps. When it is `true`, the base track remains visible below every zone.
+
+## `zones`
+
+Each zone supports:
+
+```js
+{
+  min: 0,
+  max: 25,
+  color: '#ef4444',
+  width: 20,
+  taper: {
+    startWidth: 0,
+    endWidth: 32,
+    segments: 48
+  },
+  radius: 112,
+  opacity: 1,
+  lineCap: 'butt',
+  className: 'application-warning-zone',
+  offset: 0 // optional linear-axis normal offset
+}
+```
+
+`strokeStyle` is accepted as a compatibility alias for `color`.
+
+For radial gauges, `taper.startWidth` and `taper.endWidth` define variable thickness at
+the zone's numeric `min` and `max` endpoints. Missing taper widths fall back to `width`,
+and `taper.segments` controls smoothness between 2 and 256 samples. Tapered zones are
+filled SVG annular paths; uniform zones remain normal strokes. The taper follows numeric
+value direction automatically when `invert` is enabled.
+
+Zones are clamped to the gauge range. When zones overlap, the last matching zone wins for the overlapping segment and for `pointer.colorByZone`.
+
+## `scale`
+
+### Shared
+
+- `endpointMode`: `auto`, `both`, or `dedupe`; `auto` removes the duplicate maximum endpoint on a closed 360-degree scale;
+- `radius`;
+- `position`: `inside`, `outside`, or `cross`.
+
+### `scale.major`
+
+- `visible`;
+- `interval`: explicit value spacing;
+- `divisions`: desired division count when interval is not supplied;
+- `length`;
+- `width`;
+- `color`;
+- `opacity`.
+
+### `scale.minor`
+
+- `visible`;
+- `subdivisions`: minor tick count between adjacent major ticks;
+- `length`;
+- `width`;
+- `color`;
+- `opacity`.
+
+Major and minor ticks are each rendered as one combined SVG path, reducing DOM node count for dense scales.
+
+## `labels`
+
+- `visible`;
+- `interval`: independent label interval, or the major tick interval when omitted;
+- `radius`;
+- `color`;
+- `fontFamily`, `fontSize`, `fontWeight`;
+- `fractionDigits`;
+- `rotation`: `horizontal`, `radial`, or `tangent`;
+- `formatter(value, context)`.
+
+## `pointer`
+
+- `visible`;
+- `type`: `needle`, `line`, `arrow`, or `spear`;
+- `length`;
+- `shaftLength`: optional straight-body length before an arrow, spear, or needle tip; `null` keeps the type fallback;
+- `tailLength`;
+- `width`;
+- `color`;
+- `strokeColor`, `strokeWidth`;
+- `opacity`;
+- `colorByZone`;
+- `cap.visible`, `cap.radius`, `cap.color`, `cap.strokeColor`, `cap.strokeWidth`;
+- `cap.stackOrder`: `above` (default) or `below`, relative to the pointer shape.
+
+SVG stacking follows document paint order rather than a numeric CSS `z-index`.
+Built-in radial types place the readout layer before the pointer layer, so the pointer
+always paints above title, value, and unit text. Each type explicitly chooses its cap
+stack order. A custom type can place `readoutLayer` and `pointerLayer` in a different
+order and can set `pointer.cap.stackOrder: 'below'` when the pointer must paint over
+its center cap.
+
+## `indicator`
+
+Linear types use `indicator` instead of the radial `pointer` layer:
+
+- `visible`;
+- `type`: `hairline`, `marker`, or `carriage`;
+- `position`: `negative`, `positive`, or `cross`;
+- `length`;
+- `centerOffset`: signed center shift across the axis; positive is visually upward for a left-to-right horizontal axis;
+- deprecated `offset`: retained as a compatibility alias with its original axis-normal sign;
+- `width`, `color`, `strokeColor`, `strokeWidth`, `opacity`, and `lineCap`;
+- `colorByZone`;
+- `markerSize`;
+- `carriageWidth`, `carriageRadius`;
+- `cap.visible`, `cap.radius`, `cap.color`, `cap.strokeColor`, `cap.strokeWidth`;
+- `cap.stackOrder`: `above` (default) or `below`, relative to the indicator shape.
+
+The indicator consumes `state.pointerValue`, so existing animation and jitter remain
+pointer-only visual effects and do not change the readout, API value, events, or ARIA
+value. The classic-linear fallback does not draw a center cap; applications may opt in
+with `indicator.cap.visible: true`.
+The built-in linear type paints its indicator layer after the readout layer, matching
+the radial pointer-over-readout behavior.
+
+
+## `centerZero`
+
+Both `center-zero` and `classic-linear-zero` use the reusable zero marker. The first is
+a radial heritage dial; the second composes the existing classic linear layers.
+
+- `zeroValue`: the numeric reference represented by the center position;
+- `symmetric`: expand the resolved range equally around `zeroValue`;
+- `marker.visible`;
+- `marker.radius` for radial gauges;
+- `marker.position` and `marker.centerOffset` for linear gauges;
+- `marker.length`, `marker.width`;
+- `marker.color`, `marker.opacity`, `marker.lineCap`.
+
+The preset defaults to `-100 ... 100`, but both the range and all colors remain
+overridable.
+
+## `tape`
+
+`rolling-tape` uses a fixed edge-to-edge reference line and a moving scale strip:
+
+- `orientation`: `vertical` or `horizontal`;
+- `x`, `y`, `width`, `height`, `cornerRadius`;
+- `windowColor`, `windowStrokeColor`, `windowStrokeWidth`;
+- `windowInnerStrokeColor`, `windowInnerStrokeWidth`;
+- `stripColor`, `textColor`, `tickColor`, `minorTickColor`;
+- `majorTickWidth`, `minorTickWidth`, `majorTickLength`, `minorTickLength`;
+- `tickInset`, `labelOffset`;
+- `interval`, `minorSubdivisions`, `majorSpacing`;
+- `indicatorColor`, `indicatorWidth`;
+- `fadeSize`, `fadeColor`;
+- `colorByZone`.
+
+The strip is generated from reusable slots around the current value, so a large numeric
+range does not create an unbounded SVG tree. `invert` reverses tape travel while zones
+remain attached to their numeric values. `Gaugeit.geometry.tapeWindowBox()`,
+`resolveTapeInterval()`, `tapeMinorStep()`, and `tapeValueOffset()` are exported for
+custom implementations.
+
+## `readout`
+
+`readout.visible` controls the full group. `title`, `value`, and `unit` each support position, typography, color, and visibility.
+`value.visible` and `unit.visible` default to `false`. Their content never needs to be
+rendered when the surrounding application already presents the numeric value.
+
+Each part supports independent numeric `x` and `y` coordinates in the configured SVG viewBox. `x: 'auto'` centers the part. `y: 'auto'` uses `position: 'top'`, `center`, or `bottom`; `margin`, `offsetX`, and `offsetY` refine automatic placement only. Numeric coordinates are final absolute SVG positions.
+The built-in `arc` title position defaults to `('auto', 35)`. Its value position defaults to `(160, 130)` so an enabled value sits
+inside the arc instead of overlapping its colored sectors. The radial `center-zero`
+title defaults to `('auto', 205)`, between the pointer hub and lower value readout.
+The rolling-tape separate value supports the same independent `x` and `y` coordinates.
+
+The value configuration additionally supports:
+
+- `fractionDigits`;
+- `prefix` and `suffix`;
+- `locale` passed to `Intl.NumberFormat`;
+- `formatter(value, context)`.
+
+A formatter takes precedence over locale and fraction settings.
+
+## `animation`
+
+- `enabled`;
+- `duration` in milliseconds;
+- `easing`: named easing or callback;
+- `animateOnInit`;
+- `startFrom`: `min`, `max`, `value`, or a number;
+- `respectReducedMotion`.
+
+Built-in easing names are exported through `Gaugeit.easingNames`.
+
+## `effects.jitter`
+
+Jitter randomizes only the active moving visual: radial pointer angle, linear indicator position, or rolling-tape position. It does not affect readouts, API values, events, or accessibility attributes.
+
+- `enabled`;
+- `amplitude`;
+- `amplitudeUnit`: `value` or `percent`;
+- `frequency`: new random target changes per second;
+- `smoothing`: higher values create slower movement;
+- `whenIdleOnly`: suppress jitter during a stable-value animation.
+
+## `accessibility`
+
+- `label`;
+- `description`;
+- `valueText`: string or callback.
+
+The generated root has meter semantics and updated numeric attributes.
+
+## `performance`
+
+- `pauseWhenHidden`;
+- `pauseWhenOffscreen`.
+
+Both default to `true`. Runtime changes through `updateOptions()` or
+`replaceOptions()` reconfigure the corresponding observers.