gaugeit.js 0.1.0 → 0.1.1

package/docs/ai/contributor-guide.md

@@ -0,0 +1,928 @@
+# Gaugeit.js contributor guide for coding agents
+
+This guide explains how to modify and extend Gaugeit.js 0.1.1 without breaking its
+public API, distribution model, responsive layout, or cross-platform reproducibility.
+
+Read root `AGENTS.md` first. Existing human-oriented references remain important:
+
+- `docs/architecture.md`
+- `docs/creating-gauge-types.md`
+- `docs/development.md`
+- `docs/api.md`
+- `CONTRIBUTING.md`
+
+## Architecture summary
+
+Gaugeit.js separates application state from visual composition:
+
+```text
+public API
+  -> managed instance creation
+  -> Gauge lifecycle and animation core
+  -> option resolution and selected type
+  -> ordered rendering layers
+  -> SVG renderer and dynamic controllers
+  -> generated responsive instrument
+```
+
+The core owns values, animation, jitter, lifecycle, events, accessibility, and cleanup.
+Types own defaults and ordered layer lists. Layers own SVG. Geometry helpers own
+deterministic math. This separation is a project invariant.
+
+## Canonical source and generated output
+
+Canonical files:
+
+```text
+src/index.js
+src/core/
+src/geometry/
+src/layers/
+src/renderer/
+src/types/
+src/gaugeit.css
+src/index.d.ts
+adapters/
+bin/
+scripts/
+tests/
+README.md
+docs/
+```
+
+Generated files:
+
+```text
+dist/gaugeit.cjs
+dist/gaugeit.cjs.map
+dist/gaugeit.min.cjs
+dist/gaugeit.min.cjs.map
+dist/gaugeit.esm.js
+dist/gaugeit.esm.js.map
+dist/gaugeit.esm.min.js
+dist/gaugeit.esm.min.js.map
+dist/gaugeit.umd.js
+dist/gaugeit.umd.js.map
+dist/gaugeit.umd.min.js
+dist/gaugeit.umd.min.js.map
+dist/gaugeit.standalone.js
+dist/gaugeit.standalone.js.map
+dist/gaugeit.standalone.min.js
+dist/gaugeit.standalone.min.js.map
+dist/gaugeit.css
+dist/gaugeit.min.css
+dist/gaugeit.d.ts
+dist/manifest.json
+```
+
+Never hand-edit generated files. A source change is incomplete until the generated
+distribution is rebuilt and committed.
+
+## Option resolution pipeline
+
+The runtime resolves options in `src/core/options.js`.
+
+### Stage 1: determine type
+
+The requested `type` is converted to a string and looked up in the registry. Unknown
+types do not receive a silent fallback because a typo would otherwise hide an
+integration error.
+
+### Stage 2: merge defaults
+
+Resolution order:
+
+```text
+BASE_DEFAULTS
+  + selected type defaults
+  + raw instance options
+```
+
+The merge rules in `src/core/utils.js` are:
+
+- plain objects merge recursively;
+- arrays are replaced;
+- callback functions are preserved;
+- unsafe keys `__proto__`, `prototype`, and `constructor` are ignored;
+- cross-realm plain objects remain accepted.
+
+### Stage 3: restore nested shapes
+
+Malformed nested values are restored from fallback objects. This prevents common
+configuration mistakes such as:
+
+```js
+{ pointer: null }
+```
+
+from crashing later layer code.
+
+### Stage 4: optional type configuration
+
+A type may expose:
+
+```js
+configure(options, {
+  requested,
+  typeDefaults
+})
+```
+
+This runs after merge and before final validation.
+
+Use the hook only to derive unspecified fallback values. The resizable built-in linear
+and tape types use it to scale preset geometry from requested dimensions. Do not
+overwrite coordinates explicitly provided by the instance.
+
+### Stage 5: validate and normalize
+
+Validation:
+
+- repairs invalid numeric ranges;
+- clamps sizes and opacity;
+- checks enum values;
+- normalizes zones;
+- swaps reversed trigger bounds;
+- derives light glow radius when null;
+- enforces minimum intervals;
+- preserves compatibility aliases.
+
+Do not move ordinary defensive normalization into rendering layers. Layers should
+receive resolved runtime options.
+
+## User option ownership
+
+`Gauge` stores two related configurations:
+
+- `userOptions`: original declarative overrides;
+- `options`: fully resolved runtime configuration.
+
+`updateOptions(patch)` deep-merges into `userOptions`.
+
+`replaceOptions(options)` replaces `userOptions` with a fresh object.
+
+Both re-resolve the selected type, reconfigure lifecycle observers, render static
+content again, and preserve the current target value unless an explicit new value is
+provided.
+
+When adding a public option, consider both patch and replacement semantics.
+
+## Type registry
+
+`GaugeTypeRegistry` stores:
+
+```js
+{
+  name,
+  defaults,
+  layers,
+  description,
+  configure
+}
+```
+
+Registration validates:
+
+- non-empty type name;
+- plain-object definition;
+- non-empty layer array;
+- every layer exposes `render(context)`.
+
+Public registry operations:
+
+```js
+registry.register(name, definition)
+registry.get(name)
+registry.has(name)
+registry.names()
+registry.describe()
+```
+
+Built-ins are registered in `src/types/register-builtins.js` during module
+initialization.
+
+When adding a built-in type:
+
+1. create `src/types/<name>.js`;
+2. provide description, defaults, layers, and optional configure hook;
+3. register it in `register-builtins.js`;
+4. expose it through `builtInTypes`;
+5. ensure all public colors and dimensions remain overridable;
+6. add type-specific tests;
+7. update README, API and AI docs;
+8. rebuild `dist/`.
+
+## Type defaults
+
+A type should express its visual identity through defaults, not custom branches in the
+core.
+
+Prefer:
+
+```js
+export const exampleGaugeType = {
+  description: '...',
+  defaults: {
+    geometry: { ... },
+    face: { ... },
+    pointer: { ... }
+  },
+  layers: [ ... ]
+};
+```
+
+Avoid:
+
+```js
+if (options.type === 'example') {
+  // special behavior in the generic core
+}
+```
+
+A new geometry family may require new pure helpers and layers, but the lifecycle core
+should remain type-agnostic.
+
+## Layer execution and paint order
+
+A layer has the public shape:
+
+```js
+{
+  id: 'layer-name',
+
+  render(context) {
+    // append static SVG
+
+    return {
+      update(value, state) {
+        // optional dynamic work
+      },
+
+      destroy() {
+        // optional cleanup
+      }
+    };
+  }
+}
+```
+
+Render context contains:
+
+```js
+{
+  gauge,
+  options,
+  renderer,
+  registry
+}
+```
+
+Layer-array order is SVG paint order. Later groups appear above earlier groups.
+
+Built-in radial types intentionally order:
+
+```text
+face
+zones
+ticks
+labels
+light
+readout
+pointer
+```
+
+so the pointer paints above the readout.
+
+Built-in linear types place the indicator after readout for the same reason.
+
+Do not attempt to solve SVG stacking with a numeric CSS `z-index`. Use layer order and
+the existing pointer/indicator cap `stackOrder`.
+
+## Static versus dynamic work
+
+Static layer examples:
+
+- face;
+- zones;
+- ticks;
+- labels;
+- fixed zero marker.
+
+Dynamic layer examples:
+
+- radial pointer;
+- linear indicator;
+- rolling tape slots;
+- readout value;
+- light state.
+
+Static geometry should be computed once during `render()`. `update()` should mutate
+only the smallest owned set of nodes.
+
+Avoid rebuilding whole SVG groups in every animation frame.
+
+## Renderer ownership
+
+`SvgRenderer`:
+
+- creates the generated root and SVG;
+- creates unique IDs for definitions;
+- owns layer groups;
+- owns controller registration;
+- owns a small reference map;
+- applies content clipping;
+- calculates and applies final viewBox;
+- removes generated content on destruction.
+
+Use:
+
+```js
+const group = renderer.group('my-layer', {
+  'aria-hidden': 'true'
+});
+```
+
+instead of appending directly to the host or another application-owned node.
+
+The renderer may apply a face clip path to groups created after the face layer. Bypass
+of `renderer.group()` can break clipping and ownership.
+
+## Renderer references
+
+A layer may store generated nodes or values:
+
+```js
+renderer.setReference('name', value);
+const value = renderer.getReference('name');
+```
+
+Use references sparingly for coordination within one generated instrument. Do not use
+global registries for per-instance SVG nodes.
+
+## Dynamic controller state
+
+Controller signature:
+
+```js
+update(value, state)
+```
+
+`value` is the rendered base value after animation and precision handling.
+
+State fields:
+
+```js
+{
+  gauge,
+  targetValue,
+  baseValue,
+  pointerValue,
+  animated,
+  jitterOffset
+}
+```
+
+Choose intentionally:
+
+- `targetValue`: stable application intent;
+- `value` or `baseValue`: animated displayed semantics;
+- `pointerValue`: animated value plus visual jitter.
+
+Readouts and accessibility should not use `pointerValue`. A realistic moving needle or
+tape should.
+
+The shared light exposes this decision as `light.trigger.source`.
+
+## Gauge lifecycle
+
+Construction:
+
+1. resolve target;
+2. resolve user options;
+3. create renderer;
+4. establish initial target/base/display/pointer state;
+5. render static layers;
+6. install lifecycle observers;
+7. perform startup animation if enabled.
+
+### `setValue()`
+
+- normalizes according to overflow;
+- updates target and resolved value;
+- updates immediately or creates one animation;
+- emits `gaugeit:change`;
+- schedules the frame loop only when needed.
+
+### Frame loop
+
+One `requestAnimationFrame` loop per active gauge:
+
+1. advance base animation;
+2. choose a new jitter target at configured frequency;
+3. smooth jitter offset;
+4. calculate displayed and pointer-only values;
+5. update dynamic controllers;
+6. update accessibility and display events;
+7. stop when no animation or jitter remains.
+
+### Pause and lifecycle suspension
+
+Manual `pause()` and `resume()` preserve elapsed animation time.
+
+Page visibility and intersection observers suspend work when configured. Option
+replacement reconfigures observers.
+
+### Destruction
+
+`destroy()` must:
+
+- cancel animation frame;
+- clear animation;
+- disconnect observers;
+- remove listeners;
+- call controller cleanup;
+- remove generated DOM;
+- remove managed-instance mapping;
+- emit destruction event.
+
+Any new layer timer, observer, or listener must be released by its controller
+`destroy()`.
+
+## Animation model
+
+Application value and visual realism are separate:
+
+```text
+target value
+  -> base animation
+  -> displayed value
+  -> optional jitter offset
+  -> pointer value
+```
+
+This ensures:
+
+- `getValue()` is stable;
+- `getDisplayedValue()` may animate but never jitters;
+- readout and ARIA values never jitter;
+- meaningful events never jitter;
+- moving artwork may jitter.
+
+Do not merge jitter into the application value.
+
+## Easing
+
+Named easing resolution belongs in `src/core/easing.js`. Public `easingNames` expose
+supported names. A caller may also provide a callback.
+
+When adding an easing:
+
+- keep input/output semantics compatible with progress `0 ... 1`;
+- update tests and documentation;
+- do not add an animation dependency.
+
+## Radial geometry
+
+Primary helpers in `src/geometry/scale.js` include:
+
+```text
+degreesToRadians
+polarPoint
+gaugeSweep
+centeredArcAngles
+valueToAngle
+angleToValue
+arcPath
+taperedArcPath
+niceInterval
+buildScaleValues
+buildMinorValues
+resolveZoneSegments
+findZoneForValue
+```
+
+Important invariants:
+
+- clockwise and counter-clockwise sweeps work;
+- sweep is limited to one full revolution;
+- complete circles use two SVG arc commands;
+- closed scales may deduplicate one endpoint;
+- inversion changes mapping, not numeric zone definitions;
+- later overlapping zones win;
+- transparent intervals remain true gaps;
+- tapered zones preserve width progression across split intervals.
+
+Keep pure helpers DOM-independent.
+
+## Linear geometry
+
+Primary helpers in `src/geometry/linear.js` include:
+
+```text
+linearYToSvg
+linearAxis
+valueToLinearRatio
+valueToLinearPoint
+linearPointToValue
+offsetLinearPoint
+linearNormalOffset
+linearIndicatorNormalOffset
+linearNormalSpan
+```
+
+Public Y semantics are positive-up around `linear.originY`.
+
+The two-point axis supports horizontal, vertical, and diagonal instruments. Do not
+assume a horizontal axis in new layers.
+
+Use tangent and normal vectors from `linearAxis()` instead of special-casing
+orientation.
+
+## Rolling-tape geometry
+
+Primary helpers in `src/geometry/tape.js` include:
+
+```text
+tapeWindowBox
+resolveTapeInterval
+tapeMinorStep
+tapeMinorSpacing
+tapeValueOffset
+```
+
+The rolling-tape layer uses a bounded recyclable slot set around the current value.
+Never render one node per possible numeric value.
+
+The fixed indicator remains stationary. The strip and labels move.
+
+## Light geometry and timing
+
+Pure helpers in `src/geometry/light.js` resolve:
+
+- logical position;
+- manual, below, above, and between trigger state.
+
+The layer owns:
+
+- palettes;
+- gradients and blur;
+- physical unlit lens;
+- active lens;
+- halo;
+- blink/pulse CSS state;
+- randomized flicker timer;
+- controller cleanup.
+
+Version 0.1.1 separates:
+
+- physical `radius`;
+- halo `glowRadius`;
+- lens `opacity`;
+- halo `glowOpacity`;
+- halo `glowSharpness`.
+
+Bounds must reserve the rendered halo plus blur. If rendering math changes, update
+`includeLight()` in `src/geometry/bounds.js` and tests.
+
+Blink wins over pulse. Flicker may overlay either. All moving effects respect reduced
+motion.
+
+## Intrinsic bounds
+
+Bounds are a correctness feature, not cosmetic metadata.
+
+`calculateGaugeBounds()` conservatively includes:
+
+- configured logical geometry when requested;
+- face and shadow;
+- track and zones;
+- ticks;
+- labels;
+- pointer or indicator travel;
+- zero marker;
+- rolling-tape window;
+- readout text estimates;
+- light hardware, halo, and blur.
+
+The renderer may union deterministic bounds with `getBBox()` when available.
+
+When adding a visual extent:
+
+1. identify every position it may occupy;
+2. include stroke width, blur, cap, shadow, and animation variation;
+3. update deterministic bounds;
+4. test finite responsive layout;
+5. verify no clipping in intrinsic and contain modes.
+
+Do not rely solely on browser `getBBox()` because Node tests and some environments do
+not provide it.
+
+## Face clipping
+
+A face with `clipContent: true` defines a reusable inner-bezel clip path. Subsequent
+groups inherit it through the renderer.
+
+Content-fitted faces calculate their size from conservative content bounds before the
+clip is applied.
+
+When adding a new custom layer to a clipped type:
+
+- create it with `renderer.group()`;
+- place it after the face layer;
+- do not let intentionally clipped geometry inflate document layout beyond the face.
+
+## Accessibility
+
+The generated root is a meter:
+
+```text
+role="meter"
+aria-label
+aria-valuemin
+aria-valuemax
+aria-valuenow
+aria-valuetext, when configured
+```
+
+The SVG also receives title and optional description nodes.
+
+New meaningful visual state must be represented by existing value semantics or an
+additional accessible description. Decorative layers should be `aria-hidden`.
+
+Do not use visual jitter, flicker, or animation as the only carrier of information.
+
+## DOM events
+
+Events emitted from the host:
+
+```text
+gaugeit:render
+gaugeit:change
+gaugeit:displaychange
+gaugeit:animationstart
+gaugeit:animationend
+gaugeit:settled
+gaugeit:typechange
+gaugeit:pause
+gaugeit:resume
+gaugeit:destroy
+```
+
+Keep event names namespaced. When changing detail payloads, consider compatibility and
+update declarations/docs/tests where applicable.
+
+## Auto mounting and managed instances
+
+`createGauge()` and `autoMount()` use managed instance ownership. A new managed gauge
+on the same host destroys the old one. Repeated auto-mounting returns the existing
+instance.
+
+Keep the WeakMap lifecycle safe:
+
+- a destroyed instance must remove itself;
+- an old replaced instance must not remove a newer mapping;
+- custom element disconnection destroys its instance.
+
+## React adapter boundary
+
+The React adapter:
+
+- imports the ESM distribution;
+- creates one gauge on mount;
+- replaces options when prop identity changes;
+- applies explicit value changes separately;
+- forwards the live instance;
+- destroys on unmount.
+
+The core must never import React.
+
+When changing adapter behavior:
+
+- preserve browser-ready ESM output;
+- update `adapters/react/Gaugeit.d.ts`;
+- test controlled values and forwarded ref;
+- avoid stale-instance cleanup races.
+
+## Composer boundary
+
+The Composer package distributes prebuilt browser assets and one PHP command-line
+installer.
+
+The installer:
+
+- supports default, standalone, and all modes;
+- creates destination directories;
+- handles spaces in paths;
+- replaces assets atomically through temporary files;
+- cleans only known assets;
+- preserves unrelated files;
+- returns meaningful exit codes.
+
+Do not add automatic public-directory writes to dependency installation.
+
+## Adding a new option
+
+Use this checklist:
+
+1. Add the base default in `src/core/defaults.js` unless it is type-only.
+2. Add validation and normalization in `src/core/options.js`.
+3. Add TypeScript declaration in `src/index.d.ts`.
+4. Consume the resolved value in the correct layer, geometry, renderer, or core.
+5. Update bounds if visual extents change.
+6. Update CSS if the option controls styling.
+7. Add focused option tests.
+8. Add rendering/lifecycle tests.
+9. Update `docs/api.md`, README examples, and `docs/ai/options-reference.md`.
+10. Rebuild all distributions.
+11. Run `npm run check`.
+12. Verify clean reproducibility.
+
+For compatibility, use explicit aliases only when preserving an established public
+contract. Do not create undocumented aliases for convenience.
+
+## Adding a new layer
+
+1. Decide whether the layer is static or dynamic.
+2. Create `src/layers/<name>.js`.
+3. Use `renderer.group()`.
+4. Use `svgElement()` or `createElementNS`; never `innerHTML`.
+5. Return a controller only if dynamic state exists.
+6. Clean all owned resources in controller `destroy()`.
+7. Add pure geometry helpers if calculations can be DOM-independent.
+8. Add bounds support.
+9. Export through `src/index.js` if intended for custom types.
+10. Add declarations when public.
+11. Insert into type arrays at the intended paint position.
+12. Add unit and DOM tests.
+13. Document usage.
+
+## Adding a new gauge type
+
+1. Reuse an existing geometry family if possible.
+2. Express visual identity in defaults.
+3. Add a `configure()` hook only for derived fallback geometry.
+4. Select layers in exact paint order.
+5. Include the shared light layer if normal annunciator support is desired.
+6. Keep all colors and principal dimensions overridable.
+7. Register and expose the type.
+8. Test default rendering, option override, finite bounds, and distribution behavior.
+9. Add screenshot/example/documentation.
+10. Rebuild and validate.
+
+## TypeScript declarations
+
+`src/index.d.ts` is canonical for the core package API.
+`adapters/react/Gaugeit.d.ts` is canonical for React props and the forwarded ref.
+
+Update `src/index.d.ts` when changing:
+
+- option keys;
+- accepted enum values;
+- public methods;
+- event-facing types if added;
+- layer contexts;
+- geometry exports;
+- registry definitions.
+
+Update `adapters/react/Gaugeit.d.ts` when changing React props or the forwarded ref
+type.
+
+Run:
+
+```bash
+npm run typecheck
+```
+
+The build copies declarations into `dist/gaugeit.d.ts`. Do not edit that copy.
+
+## Test selection
+
+Use focused tests while iterating.
+
+| Change | Likely tests |
+| --- | --- |
+| defaults or normalization | `tests/options.test.js` |
+| radial geometry | `tests/geometry.test.js`, `tests/zones.test.js` |
+| linear behavior | `tests/linear.test.js`, `tests/advanced-types.test.js` |
+| light behavior | `tests/light.test.js`, `tests/advanced-types.test.js` |
+| lifecycle | `tests/lifecycle.test.js` |
+| registry/type exposure | `tests/registry.test.js` |
+| CSS hooks | `tests/css.test.js` |
+| output inventory/build | `tests/distribution.test.js` |
+| npm/Composer metadata | `tests/package-metadata.test.js` |
+| React adapter | `tests/react-adapter.test.js` |
+| examples | `tests/example-page.test.js`, `tests/framework-examples.test.js` |
+| repository rules | `tests/repository-hygiene.test.js` |
+
+The main Node test command includes `tests/*.test.js` with concurrency one:
+
+```bash
+npm test
+```
+
+DOM smoke:
+
+```bash
+npm run test:browser
+```
+
+Optional real Chromium smoke:
+
+```bash
+npm run test:chromium
+```
+
+## Build output
+
+Run:
+
+```bash
+npm run clean
+npm run build
+```
+
+or use the full:
+
+```bash
+npm run check
+```
+
+The build must remain deterministic:
+
+- stable file ordering;
+- no timestamps in generated content;
+- no random output;
+- normalized LF inputs;
+- no absolute local paths;
+- same source-map contents on Linux and Windows;
+- manifest sizes matching files.
+
+CI performs:
+
+```bash
+npm ci
+npm run check
+git diff --exit-code -- dist package-lock.json
+```
+
+A build that passes locally but changes generated source maps on Linux is not complete.
+
+## Documentation changes
+
+Update only the smallest set of authoritative documents, but do not leave contradictory
+copies.
+
+When changing public options:
+
+```text
+README.md
+docs/api.md
+src/index.d.ts
+docs/ai/options-reference.md
+relevant recipes and troubleshooting
+```
+
+When changing architecture:
+
+```text
+docs/architecture.md
+docs/creating-gauge-types.md
+docs/ai/contributor-guide.md
+AGENTS.md, if repository rules changed
+```
+
+`docs/ai/ai-full.md` is the single-file context bundle and must be regenerated or
+updated whenever its component AI guides change.
+
+## Release-aware changes
+
+Do not rewrite an already published npm version. A released version is immutable.
+
+For a new release:
+
+- update package version and public version constant consistently;
+- update changelog;
+- update exact CDN examples;
+- rebuild `dist/`;
+- run all validation;
+- create and push the Git tag only after green CI;
+- publish npm;
+- update Packagist from the Git tag.
+
+Release mechanics remain explicit maintainer actions. CI validates but does not publish.
+
+## Definition of done for contributors
+
+A coding agent may say a task is complete only when:
+
+- behavior is implemented in canonical source;
+- public compatibility is preserved or intentionally documented;
+- focused tests and regression tests pass;
+- full `npm run check` passes;
+- declarations match runtime;
+- docs and examples match behavior;
+- visual bounds cover new extents;
+- cleanup covers all new resources;
+- generated distribution is rebuilt;
+- reproducibility diff is clean;
+- no accidental files or unrelated edits are present.