gaugeit.js 0.1.0

package/docs/architecture.md

@@ -0,0 +1,224 @@
+# Architecture
+
+## Design goals
+
+Gaugeit.js is designed around five constraints:
+
+1. the runtime must remain dependency-free and small;
+2. a gauge must work in server-rendered HTML without a framework;
+3. rendering must be responsive and resolution-independent;
+4. gauge types must be replaceable without changing animation or lifecycle code;
+5. expensive work must be static whenever possible.
+
+## Runtime layers
+
+### Public API
+
+`src/index.js` exposes the stable application API:
+
+- instance creation and automatic mounting;
+- gauge-type registration;
+- the optional custom element;
+- built-in layers and geometry helpers;
+- the default type registry.
+
+### Gauge core
+
+`src/core/gauge.js` owns state and lifecycle:
+
+- stable target value;
+- currently displayed value;
+- startup and update animation;
+- optional visual jitter;
+- pause, resume, refresh, option replacement, and destroy;
+- page visibility and offscreen pausing with observer reconfiguration;
+- accessibility attributes and DOM events.
+
+The core does not know how an arc, face, scale, or pointer should look.
+
+### Type registry
+
+`GaugeTypeRegistry` maps a type name to:
+
+- type-specific defaults;
+- an ordered list of rendering layers;
+- a human-readable description.
+
+Built-in types are registered during module initialization. Applications may register additional types or replace a built-in type intentionally.
+
+### Shared annunciator-light layer
+
+`src/layers/light.js` is a reusable dynamic layer backed by the pure helpers in
+`src/geometry/light.js`. Trigger evaluation is separated from rendering, while the
+layer owns only SVG nodes and CSS state classes. This lets any built-in or custom type
+insert the same component at its preferred paint position without duplicating timers,
+threshold logic, gradients, or responsive calculations. Thresholds may read the stable
+target, animated display, or jittered pointer value. Blinking is CSS-driven and respects
+`prefers-reduced-motion`.
+
+### Rendering layers
+
+A layer receives a render context and adds SVG elements. Static layers return nothing. Dynamic layers return a controller:
+
+```js
+{
+  update(value, state) {
+    // Update only the generated nodes owned by this layer.
+  },
+  destroy() {
+    // Optional cleanup.
+  }
+}
+```
+
+The radial pointer, linear indicator, rolling tape, and readout are dynamic. Faces, zones, ticks, labels, and fixed reference markers are static until options change.
+Layer-array order is also the SVG paint order. Built-in types place readouts before
+their pointer or linear-indicator layer, so the moving visual stays above all text.
+Center caps use the type-specific `cap.stackOrder` option to paint either above or
+below their owning pointer/indicator without relying on unsupported numeric SVG
+`z-index` behavior.
+Controller `value` is always the rendered base value. The optional `state.pointerValue`
+contains the pointer-only visual value after jitter and should be used only by pointer-like artwork.
+
+### SVG renderer
+
+`SvgRenderer` owns the generated subtree, dynamic-controller list, small reference registry, and the final content-aware viewport. It avoids `innerHTML`, creates all SVG nodes through `createElementNS`, and replaces only the content inside the supplied host.
+
+Before the SVG is exposed, the renderer combines deterministic geometry bounds with a browser `getBBox()` measurement when available. Intrinsic layout grows with that viewport; contain layout scales the same viewport into a fixed host. This keeps all layers inside the component without coupling gauge types to page-specific card dimensions.
+
+SVG provides:
+
+- one coordinate system through `viewBox`;
+- crisp rendering at any pixel density;
+- CSS and custom-property compatibility;
+- accessible normal DOM nodes;
+- cheap pointer rotation through one group transform.
+
+### Geometry
+
+Pure geometry helpers map values to radial angles, two-point linear axes, and rolling-tape displacement. They also calculate points, ticks, zones, closed-scale endpoints, tape windows, and visual bounds. The helpers are DOM-independent and covered by Node tests.
+
+Transparent-zone handling is performed by splitting the full range at every zone boundary. Each resulting interval is assigned either a zone, the base track, or no visual stroke. This ensures that a transparent zone is a real gap rather than a transparent stroke over a visible track.
+
+The radial zone layer selects one of two renderers per resolved interval. Uniform zones
+remain compact SVG strokes. A zone with `taper` becomes a sampled, filled annular path
+whose inner and outer boundaries interpolate independently from `startWidth` to
+`endWidth`. The bounds system reserves the widest endpoint, and overlapping-zone splits
+preserve the taper ratio across the original numeric zone instead of restarting it.
+
+### Radial and linear layer families
+
+Radial types compose `zones`, `ticks`, `labels`, and `pointer`. Linear types compose
+`linearZones`, `linearTicks`, `linearLabels`, and `linearIndicator`. Both families use
+the same face, readout, type registry, animation state, zone semantics, option merge,
+accessibility, and renderer. This prevents linear geometry from being forced through
+radial angle helpers while keeping the lifecycle and public API shared.
+
+The built-in `classic-linear` type is therefore a preset, not a separate rendering
+engine. Its straight axis is configured by start and end points, which also permits
+vertical or diagonal custom types without changing the core. The shared indicator
+model uses `centerOffset` for an orientation-independent positive-up control and keeps
+the older raw axis-normal `offset` as a compatibility alias. Public linear Y coordinates
+are Cartesian around `linear.originY`: positive values move upward even though SVG's
+internal Y axis points downward. Labels and zones use the same positive-up convention.
+
+Framed presets register an SVG clip path that matches the inner bezel. The renderer
+applies it to every later non-face layer, so custom pointer or indicator geometry can
+enter from outside the face without affecting document layout or leaking past the
+instrument frame. Content-fitted faces still size themselves from conservative
+unclipped bounds before the clip is applied.
+
+### Specialized gauge families
+
+Gaugeit keeps one lifecycle and registry while allowing specialized geometry families:
+
+- `center-zero` remains radial and reuses the ordinary zones, ticks, labels, pointer,
+  and readout layers. Its only additional layer is a fixed configurable zero marker.
+- `classic-linear-zero` reuses the complete classic linear family and inserts the same
+  zero-marker layer between the scale and readout. The marker resolves its geometry
+  from the active axis rather than duplicating a linear renderer.
+- `rolling-tape` uses a clipped, bounded set of recyclable tape slots. A fixed
+  edge-to-edge reference line stays in place while labels and ticks move behind it.
+  Slot reuse keeps DOM size independent of the configured numeric range.
+
+These families expose normal option objects (`centerZero` and `tape`) and
+ordinary color properties. Type presets provide polished fallback themes, while an
+instance may override every face, scale, label, fill, strip, indicator, fade, and zone
+color through the same recursive option merge used by existing gauges.
+
+## Configuration resolution
+
+Configuration uses three ordered sources:
+
+1. base library defaults;
+2. selected gauge-type defaults;
+3. instance options.
+
+Plain objects are merged recursively. Arrays are replaced. Functions are preserved.
+`updateOptions()` merges a partial patch; `replaceOptions()` discards earlier instance
+overrides and resolves a complete declarative option object from fresh type defaults.
+A type may optionally expose `configure(options, context)` after merging and before
+validation. The built-in resizable linear and tape presets use this hook to scale only
+their fallback coordinates from `geometry.width`, `geometry.height`, or
+`geometry.aspectRatio`; explicit instance coordinates are never overwritten. The result
+is then normalized and validated before rendering.
+
+This allows a type to define nearly every visual choice while an application supplies only `value`, `min`, and `max`.
+
+## Animation model
+
+A stable base value is animated between the previous and requested values. Jitter is an optional visual offset supplied only to the pointer controller after base animation. Consequently:
+
+- `getValue()` returns the stable requested value;
+- `getDisplayedValue()` returns the rendered base value and may include animation, but never jitter;
+- changing jitter never mutates application data;
+- readout, events, and ARIA values do not jitter;
+- pointer-like visuals and the rolling tape read their visual value from `state.pointerValue`.
+
+One `requestAnimationFrame` loop per active gauge is used. The loop stops when no
+animation or jitter remains. Visibility and intersection observers prevent unnecessary
+background work and are reconfigured when performance options change.
+
+## Events
+
+Instances dispatch namespaced DOM events from the host:
+
+- `gaugeit:render`;
+- `gaugeit:change`;
+- `gaugeit:displaychange`;
+- `gaugeit:animationstart`;
+- `gaugeit:animationend`;
+- `gaugeit:settled`;
+- `gaugeit:typechange`;
+- `gaugeit:pause`;
+- `gaugeit:resume`;
+- `gaugeit:destroy`.
+
+Events enable framework adapters and independent components without unscoped global
+callbacks. Managed instances also register an internal destroy callback, so calling
+`gauge.destroy()` directly removes the stale entry used by `getMountedGauge()` and
+duplicate-safe auto mounting.
+
+## Distribution model
+
+The source remains normal ES modules. A dependency-free build script creates:
+
+- ESM bundle for modern bundlers and direct module use;
+- UMD bundle for classic script tags and AMD;
+- CommonJS bundle for tooling;
+- compact UMD build;
+- normal and compact CSS;
+- TypeScript declarations for the core and React adapter;
+- a file-size manifest.
+
+The prebuilt UMD package exposes one `Gaugeit` global. Internal modules do not leak global names.
+
+## Framework boundaries
+
+The core never imports React, Laravel, Twig, Bootstrap, jQuery, or a transport library. Framework adapters own only lifecycle translation:
+
+- React creates and destroys an instance from effects;
+- Blade or Twig emits a stable host and data configuration;
+- the custom element translates attributes into normal options.
+
+This boundary keeps the rendering engine portable and testable.

package/docs/creating-gauge-types.md

@@ -0,0 +1,286 @@
+# Creating gauge types and layers
+
+## Reusing built-in layers
+
+The easiest type changes defaults while reusing all standard layers:
+
+```js
+Gaugeit.registerGaugeType('compact-status', {
+  description: 'Compact status gauge for dashboard cards.',
+  defaults: {
+    geometry: {
+      width: 260,
+      height: 150,
+      centerX: 130,
+      centerY: 132,
+      startAngle: 200,
+      endAngle: 340
+    },
+    pointer: {
+      type: 'arrow',
+      length: 75,
+      width: 6
+    },
+    readout: {
+      value: { x: 130, y: 35, fontSize: 28 }
+    }
+  },
+  layers: [
+    Gaugeit.layers.face,
+    Gaugeit.layers.zones,
+    Gaugeit.layers.ticks,
+    Gaugeit.layers.labels,
+    Gaugeit.layers.pointer,
+    Gaugeit.layers.readout
+  ]
+});
+```
+
+Layer order is paint order. Later SVG layers appear above earlier layers.
+
+For a standard warning or status lamp, include `Gaugeit.layers.light` and provide a
+normal `light` option block. The shared component already supplies threshold/range
+conditions, realistic palettes, blinking, custom colors, and responsive positioning.
+A custom lamp layer is only necessary when the visual itself is fundamentally different.
+
+Any custom radial type that includes `Gaugeit.layers.zones` automatically supports both
+uniform and tapered sectors. A tapered zone uses the same public zone object:
+
+```js
+zones: [{
+  min: 0,
+  max: 100,
+  color: '#06b6d4',
+  width: 18,
+  taper: { startWidth: 0, endWidth: 36, segments: 48 }
+}]
+```
+
+No type-specific layout code is required; automatic bounds use the widest taper endpoint.
+
+## Reusing the linear layer family
+
+A linear type uses the same lifecycle and option system without routing straight
+geometry through radial angle helpers:
+
+```js
+Gaugeit.registerGaugeType('vertical-level', {
+  description: 'Vertical classic level instrument.',
+  defaults: {
+    geometry: { mode: 'linear', width: 180, height: 320 },
+    linear: {
+      originY: 270,
+      startX: 90,
+      startY: 0,
+      endX: 90,
+      endY: 220,
+      tickSide: 'positive',
+      labelOffset: 34,
+      zoneOffset: -16
+    },
+    pointer: { visible: false },
+    indicator: {
+      visible: true,
+      type: 'hairline',
+      position: 'cross',
+      length: 70,
+      centerOffset: 0
+    }
+  },
+  layers: [
+    Gaugeit.layers.face,
+    Gaugeit.layers.linearZones,
+    Gaugeit.layers.linearTicks,
+    Gaugeit.layers.linearLabels,
+    Gaugeit.layers.linearIndicator,
+    Gaugeit.layers.readout
+  ]
+});
+```
+
+The axis start and end points define the complete orientation. X increases rightward;
+Y is measured from `linear.originY` and increases upward. The linear indicator reads
+`state.pointerValue`, so animation and jitter work without a separate lifecycle.
+Use `indicator.centerOffset` to move the indicator center across the axis; positive
+values move toward the visual upper side of a left-to-right horizontal axis. Tick
+lengths are shared with radial types through `scale.major.length` and
+`scale.minor.length`.
+
+A framed custom type can set `face.clipContent: true` when the face layer is first in
+paint order. The face layer then defines the inner-bezel clip path and the renderer
+applies it to subsequent layers automatically.
+
+## A custom static layer
+
+A static layer may use normal SVG DOM methods:
+
+```js
+const targetMarkerLayer = {
+  id: 'target-marker',
+  render({ options, renderer }) {
+    const group = renderer.group('target-marker', { 'aria-hidden': 'true' });
+    const angle = Gaugeit.geometry.valueToAngle(options.targetMarker.value, options);
+    const inner = Gaugeit.geometry.polarPoint(
+      options.geometry.centerX,
+      options.geometry.centerY,
+      options.targetMarker.radius - options.targetMarker.length,
+      angle
+    );
+    const outer = Gaugeit.geometry.polarPoint(
+      options.geometry.centerX,
+      options.geometry.centerY,
+      options.targetMarker.radius,
+      angle
+    );
+
+    const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
+    line.setAttribute('x1', inner.x);
+    line.setAttribute('y1', inner.y);
+    line.setAttribute('x2', outer.x);
+    line.setAttribute('y2', outer.y);
+    line.setAttribute('stroke', options.targetMarker.color);
+    line.setAttribute('stroke-width', options.targetMarker.width);
+    group.append(line);
+  }
+};
+```
+
+## A dynamic custom layer
+
+A layer may return a controller. The following indicator changes opacity when the displayed value crosses a threshold:
+
+```js
+const warningLampLayer = {
+  id: 'warning-lamp',
+  render({ options, renderer }) {
+    const group = renderer.group('warning-lamp');
+    const lamp = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+    lamp.setAttribute('cx', options.warningLamp.x);
+    lamp.setAttribute('cy', options.warningLamp.y);
+    lamp.setAttribute('r', options.warningLamp.radius);
+    lamp.setAttribute('fill', options.warningLamp.color);
+    group.append(lamp);
+
+    return {
+      update(value) {
+        lamp.setAttribute('opacity', value >= options.warningLamp.threshold ? '1' : '0.16');
+      }
+    };
+  }
+};
+```
+
+The controller's `value` argument excludes jitter, so readouts, lamps, and other
+meaningful indicators remain stable. A custom pointer that intentionally participates
+in the visual effect can read `state.pointerValue`:
+
+```js
+update(value, state) {
+  const pointerValue = Number.isFinite(state.pointerValue) ? state.pointerValue : value;
+  // Rotate only the custom pointer using pointerValue.
+}
+```
+
+Register it with type defaults:
+
+```js
+Gaugeit.registerGaugeType('warning-meter', {
+  defaults: {
+    warningLamp: {
+      x: 285,
+      y: 25,
+      radius: 8,
+      threshold: 80,
+      color: '#dc2626'
+    }
+  },
+  layers: [
+    Gaugeit.layers.face,
+    Gaugeit.layers.zones,
+    Gaugeit.layers.ticks,
+    Gaugeit.layers.labels,
+    warningLampLayer,
+    Gaugeit.layers.pointer,
+    Gaugeit.layers.readout
+  ]
+});
+```
+
+## Layer rules
+
+A well-behaved layer should:
+
+- append content only below a group created through `renderer.group()`;
+- avoid changing application-owned nodes outside the generated gauge root;
+- keep static geometry out of `update()`;
+- release timers or observers through an optional controller `destroy()` method;
+- treat `options` as read-only runtime configuration;
+- avoid global event listeners unless ownership and cleanup are explicit;
+- include a textual alternative when it introduces new meaning not represented by the gauge value.
+
+Layer order is SVG paint order: later layers appear above earlier layers. Place a
+pointer layer after a readout layer when the pointer must cross over the text. The
+built-in radial types do this explicitly. Pointer and linear-indicator caps also
+support `cap.stackOrder: 'above' | 'below'`, allowing each gauge type to choose the
+cap-to-pointer relationship independently.
+
+
+### Optional type configuration hook
+
+A type definition may provide `configure(options, context)`. It runs after base, type,
+and instance options have been merged but before validation. `context.requested` contains
+the raw instance options and `context.typeDefaults` contains the preset defaults. This is
+the correct place to derive fallback geometry from a requested aspect ratio or size.
+Never replace coordinates explicitly supplied by the instance.
+
+```js
+registerGaugeType('wide-linear', {
+  defaults,
+  configure(options, { requested, typeDefaults }) {
+    // Derive only unspecified fallback coordinates here.
+  },
+  layers
+});
+```
+
+## Completely different gauge shapes
+
+A type may ignore every built-in geometry family and render its own SVG composition.
+Keep application data in options, create generated nodes only through the renderer,
+and return a controller only for parts that change with the value. The core still
+provides option resolution, animation state, events, accessibility updates, lifecycle
+cleanup, and framework integration.
+
+## Reusing the specialized built-in families
+
+The public `Gaugeit.layers` and `Gaugeit.geometry` collections also expose the
+specialized pieces used by the advanced built-ins:
+
+- `Gaugeit.layers.zeroMarker` for a fixed radial or linear reference mark;
+- `Gaugeit.layers.linearZones`, `linearTicks`, `linearLabels`, and `linearIndicator`
+  for straight-axis instruments;
+- `Gaugeit.layers.rollingTape` for fixed-line moving-tape instruments;
+- `Gaugeit.layers.light` for reusable warning and status lamps;
+- linear helpers such as `linearAxis()` and `valueToLinearPoint()`;
+- tape helpers such as `tapeWindowBox()`, `resolveTapeInterval()`, and
+  `tapeValueOffset()`.
+
+A custom type can therefore reuse a complete geometry family while changing only
+preset defaults and layer order. Keep family-specific options below a namespaced
+object such as `tape`, `centerZero`, or a new plugin-owned key. Colors belong in options,
+not hard-coded CSS, so every instance can override the preset theme.
+
+For moving artwork, use `state.pointerValue` only when it should participate in the
+visual jitter effect. Use `state.targetValue` for stable application intent and the
+controller's base `value` for animated display semantics. The shared light layer exposes
+this choice through `light.trigger.source`.
+
+A type does not need to use any built-in layer. It can render a vertical meter, dual pointer instrument, compass, clock, or bar-style visualization while retaining:
+
+- instance lifecycle;
+- option resolution;
+- value animation;
+- jitter;
+- events;
+- accessibility updates;
+- framework adapters.

package/docs/development.md

@@ -0,0 +1,56 @@
+# Development and release process
+
+Gaugeit.js `0.1.0` is the first release line. The repository is structured so the same
+canonical sources produce every npm, Composer, GitHub, and CDN-facing artifact.
+Publishing remains an explicit maintainer action; CI validates but does not publish.
+
+## Source of truth
+
+Maintain JavaScript and canonical CSS in `src/`. Maintain the React adapter, PHP asset
+installer, tests, documentation, and build configuration in their respective source
+directories. Never edit generated files in `dist/`, including minified files, source
+maps, copied declarations, or standalone embedded CSS.
+
+`src/gaugeit.css` is the only maintained stylesheet. Both separate CSS files and the
+standalone JavaScript bundles are generated from it.
+
+## Commands
+
+```bash
+npm ci
+npm run clean
+npm run build
+npm run typecheck
+npm test
+npm run test:browser
+npm run check
+```
+
+`npm run dev` starts the esbuild watcher. `npm run check` performs a clean rebuild,
+validates declarations, runs unit and DOM smoke tests, checks npm package contents with
+a dry run, and runs strict Composer validation when Composer is available.
+
+The optional `npm run test:chromium` check requires a globally available Chromium
+executable and is separate from portable CI.
+
+## Why `dist/` is committed
+
+The complete `dist/` directory is intentionally committed because browser users,
+GitHub source downloads, Composer consumers, npm packages, and CDN endpoints require
+ready-to-use files. Consumers do not need Node.js or a build step. CI rebuilds `dist/`
+from canonical sources and verifies that committed output remains reproducible.
+
+## Release checklist
+
+1. Confirm the version in `package.json`, `src/index.js`, `CHANGELOG.md`, and generated
+   `dist/manifest.json`.
+2. Run `npm ci` and `npm run check`.
+3. Run `npm pack --dry-run` and inspect the included files.
+4. Run `npm publish --dry-run`.
+5. Run `composer validate --strict`.
+6. Test the npm archive and Composer package from isolated consumer projects.
+7. Confirm that regenerated `dist/` files and declarations are committed.
+8. Review the working tree for local exports, patches, credentials, and editor files.
+9. Create the Git tag and GitHub release, publish npm, and update Packagist manually.
+
+No automatic publishing workflow or credential-dependent release step is included.

package/docs/framework-integration.md

@@ -0,0 +1,84 @@
+# Framework integration
+
+## Plain HTML
+
+Use `dist/gaugeit.umd.min.js` and `dist/gaugeit.min.css`. The UMD build creates one
+`Gaugeit` global.
+
+## Native ES modules
+
+Use `dist/gaugeit.esm.js`. Import CSS separately or copy it into the application
+stylesheet.
+
+## React
+
+Use `adapters/react/Gaugeit.js` or the package export `gaugeit.js/react`. Import
+`gaugeit.js/css` once in the application entry point. The published adapter is ordinary
+ESM JavaScript, so the consuming toolchain does not need to compile JSX from
+`node_modules`. Keep the options object stable with `useMemo` in frequently rendering
+components. The adapter replaces the complete options object when it changes, keeps an
+explicit `value` prop authoritative, forwards a ref to the live `Gauge` instance, and
+destroys the instance on unmount.
+
+## Laravel Blade
+
+Install the recommended prebuilt assets:
+
+```bash
+vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit/0.1.0
+```
+
+The default command installs `gaugeit.umd.min.js` and `gaugeit.min.css`. Pass
+`--standalone` for the one-file browser build or `--all` for every browser asset.
+Composer consumers use committed prebuilt files and do not need Node.js.
+
+Recommended application structure:
+
+1. install assets into a versioned public vendor path;
+2. render a stable host and JSON configuration from Blade;
+3. include the vendor CSS and script once;
+4. initialize matching hosts with a duplicate-safe selector;
+5. keep surrounding layout in application CSS.
+
+See `examples/laravel-blade.blade.php` for an executable UMD-based example. It uses
+JSON hex-escaping for safe HTML attributes, Blade `@once` blocks to avoid duplicate
+asset tags, and a `DOMContentLoaded` initializer so every server-rendered occurrence is
+available before the single initialization pass runs. The initializer is also exposed
+as `window.initGaugeitStatGauges(root)` for fragments inserted later.
+
+## Twig and other server-rendered templates
+
+A reusable initializer can keep instances in a `WeakMap`:
+
+```js
+import { createGauge } from './vendor/gaugeit/0.1.0/gaugeit.esm.js';
+
+const instances = new WeakMap();
+
+export function initStatGauges(root = document) {
+  root.querySelectorAll('[data-stat-gauge]').forEach((element) => {
+    if (instances.has(element)) return;
+
+    const options = JSON.parse(element.dataset.statGaugeOptions || '{}');
+    const gauge = createGauge(element, options);
+    instances.set(element, gauge);
+
+    element.addEventListener('gaugeit:destroy', () => {
+      instances.delete(element);
+    }, { once: true });
+  });
+}
+```
+
+## Vue, Svelte, and other frameworks
+
+The lifecycle pattern is the same:
+
+- create the gauge after the host mounts;
+- call `setValue` for value-only changes;
+- call `updateOptions` for partial visual changes;
+- call `replaceOptions` when a declarative options object should replace earlier
+  overrides;
+- call `destroy` before the host unmounts.
+
+No framework-specific rendering assumptions exist in the core.