gaugeit.js 0.1.0 → 0.1.1

package/docs/ai/troubleshooting.md

@@ -0,0 +1,1024 @@
+# Gaugeit.js troubleshooting guide for AI agents
+
+This guide diagnoses common Gaugeit.js 0.1.1 integration, rendering, lifecycle,
+packaging, and contribution failures. Start from the observed symptom. Do not guess at
+new API names to work around a configuration mistake.
+
+## Gauge does not appear
+
+### Check that the host exists
+
+This fails when creation runs before the element exists:
+
+```js
+Gaugeit.createGauge('#gauge', {
+  value: 50
+});
+```
+
+Verify:
+
+```js
+const host = document.querySelector('#gauge');
+
+if (!host) {
+  throw new Error('Gauge host was not found.');
+}
+
+const gauge = Gaugeit.createGauge(host, {
+  value: 50
+});
+```
+
+Place the script after the host, use `defer`, use a module script, or wait for
+`DOMContentLoaded`.
+
+### Check the selector
+
+`createGauge()` accepts an element or valid CSS selector. A selector typo throws a
+target-not-found error. Do not pass a React component, jQuery wrapper, NodeList, or
+plain object.
+
+### Check host layout
+
+The SVG is responsive to the host. Verify that the host and its ancestors are not
+collapsed, hidden by CSS, or assigned zero width/height.
+
+For contain mode, provide both dimensions:
+
+```css
+#gauge {
+  width: 320px;
+  height: 220px;
+}
+```
+
+```js
+layout: {
+  mode: 'contain'
+}
+```
+
+### Check CSS
+
+UMD, ESM, CommonJS, React, custom element, and Composer two-file usage require Gaugeit
+CSS.
+
+Browser:
+
+```html
+<link rel="stylesheet" href="./dist/gaugeit.min.css">
+```
+
+npm:
+
+```js
+import 'gaugeit.js/css';
+```
+
+Standalone already injects CSS. Missing CSS may produce incorrect sizing or animation
+behavior even when SVG nodes exist.
+
+## `Gaugeit is not defined`
+
+Possible causes:
+
+- UMD/standalone script failed to load;
+- application script executes before the distribution;
+- wrong global spelling;
+- ESM file was loaded as a classic script;
+- a CDN URL is wrong.
+
+Correct UMD order:
+
+```html
+<script src="./dist/gaugeit.umd.min.js"></script>
+<script>
+  Gaugeit.createGauge('#gauge', {
+    value: 50
+  });
+</script>
+```
+
+The global is exactly:
+
+```text
+Gaugeit
+```
+
+Not:
+
+```text
+GaugeIt
+GaugeIT
+gaugeit
+```
+
+## `Gaugeit` versus `GaugeIt` filename or symbol confusion
+
+Project files and exports intentionally use:
+
+```text
+Gaugeit
+```
+
+Examples:
+
+```text
+adapters/react/Gaugeit.js
+import Gaugeit from 'gaugeit.js/react'
+window.Gaugeit
+```
+
+Windows may hide case-only filename mistakes that fail on Linux CI. Preserve exact
+case in imports and package exports.
+
+## ESM import fails in a browser
+
+This bare import does not work in a normal browser without a resolver:
+
+```js
+import { createGauge } from 'gaugeit.js';
+```
+
+Use one of:
+
+- a bundler;
+- an import map;
+- a server resolver;
+- an explicit browser path:
+
+```js
+import { createGauge } from './dist/gaugeit.esm.js';
+```
+
+Load the file as a module:
+
+```html
+<script type="module" src="./app.js"></script>
+```
+
+Do not load ESM as a classic script.
+
+## CommonJS works but gauge is unstyled
+
+The CommonJS entry resolves JavaScript only:
+
+```js
+const { createGauge } = require('gaugeit.js');
+```
+
+Add the CSS to the application bundle or page. The `require()` call does not inject it.
+
+## Standalone and separate CSS are both loaded
+
+This is usually unnecessary. Standalone injects the canonical stylesheet. Loading
+separate Gaugeit CSS as well can make debugging overrides harder.
+
+Choose either:
+
+```text
+UMD + CSS
+```
+
+or:
+
+```text
+standalone JavaScript
+```
+
+unless duplicate inclusion is intentional and understood.
+
+## CDN installation changes unexpectedly
+
+Use an exact version:
+
+```text
+gaugeit.js@0.1.1
+```
+
+Do not use an unversioned URL in production. Verify the complete file path:
+
+```text
+dist/gaugeit.umd.min.js
+dist/gaugeit.min.css
+dist/gaugeit.standalone.min.js
+```
+
+CDN propagation may take a short time after npm publication. Check the npm package
+first when a newly published CDN file is missing.
+
+## npm import path is rejected
+
+Use package exports:
+
+```js
+import { createGauge } from 'gaugeit.js';
+import 'gaugeit.js/css';
+import Gaugeit from 'gaugeit.js/react';
+import { defineGaugeitElement } from 'gaugeit.js/web-component';
+```
+
+Do not import private repository paths such as:
+
+```js
+import { createGauge } from 'gaugeit.js/src/index.js';
+```
+
+Package export maps intentionally limit supported subpaths.
+
+## React gauge keeps rebuilding
+
+The React adapter replaces the complete options object when its identity changes.
+This creates a new object every render:
+
+```jsx
+<Gaugeit options={{ type: 'arc', min: 0, max: 100 }} />
+```
+
+Prefer:
+
+```jsx
+const options = useMemo(() => ({
+  type: 'arc',
+  min: 0,
+  max: 100
+}), []);
+
+return <Gaugeit options={options} />;
+```
+
+A changing options object is valid when the configuration truly changes. Stabilization
+is a performance and lifecycle decision, not a requirement for correctness.
+
+## React value does not match `options.value`
+
+An explicit `value` prop is authoritative:
+
+```jsx
+<Gaugeit
+  value={72}
+  options={{
+    value: 10
+  }}
+/>
+```
+
+The displayed target is 72. Avoid duplicating value in both places.
+
+## React ref is null
+
+The forwarded ref becomes the live instance after mount. Do not read it during initial
+render. Use it from effects or event handlers:
+
+```jsx
+const gaugeRef = useRef(null);
+
+function update() {
+  gaugeRef.current?.setValue(80);
+}
+```
+
+## Gauge updates inefficiently
+
+For numeric samples, use:
+
+```js
+gauge.setValue(nextValue);
+```
+
+Do not repeatedly do:
+
+```js
+gauge.updateOptions({
+  value: nextValue
+});
+```
+
+unless static configuration also needs rebuilding.
+
+## `updateOptions()` leaves old styling behind
+
+`updateOptions()` deep-merges a patch. Omitted keys remain from earlier user options.
+
+Use `replaceOptions()` for a complete declarative mode switch:
+
+```js
+gauge.replaceOptions({
+  type: 'classic',
+  value: 50
+});
+```
+
+## Zone list does not append
+
+Arrays are replaced, not concatenated:
+
+```js
+gauge.updateOptions({
+  zones: newZones
+});
+```
+
+replaces the previous list. Build the complete desired array in application code.
+
+## Transparent zone still shows a track
+
+Check:
+
+```js
+track: {
+  showUnderZones: false
+}
+```
+
+A transparent or missing zone color produces a true gap only when the base track is not
+painted under zones.
+
+Accepted gap colors include:
+
+```text
+transparent
+none
+empty or missing color
+```
+
+## Overlapping zone color is unexpected
+
+Later matching zones win. Reorder the zone list or make ranges non-overlapping.
+
+This also affects color-by-zone pointer, indicator, and tape behavior.
+
+## Pointer moves in the wrong direction
+
+Use:
+
+```js
+invert: true
+```
+
+Do not reverse zones manually. Inversion changes visual mapping while numeric zones
+stay attached to their values.
+
+Verify the configured `startAngle` and `endAngle` if a custom radial sweep is also
+present.
+
+## Linear scale moves vertically in the wrong direction
+
+Public linear Y coordinates increase upward from `linear.originY`.
+
+Correct mental model:
+
+```text
+positive public Y -> visually upward
+negative public Y -> visually downward
+```
+
+Do not use raw SVG downward-positive assumptions in `startY`, `endY`,
+`labelOffset`, `zoneOffset`, readout Y, or `centerOffset`.
+
+## Linear axis disappears or has invalid geometry
+
+The start and end points must differ. Runtime repairs a zero-length axis to one unit,
+but the resulting visual is unlikely to match intent.
+
+Check:
+
+```js
+linear: {
+  startX,
+  startY,
+  endX,
+  endY
+}
+```
+
+## Center-zero reference is not centered
+
+Verify:
+
+- range contains `centerZero.zeroValue`;
+- `symmetric: true` is enabled when equal magnitude is required;
+- selected type is `center-zero` or `classic-linear-zero`;
+- marker visibility and coordinates were not overridden incorrectly.
+
+Example:
+
+```js
+{
+  type: 'center-zero',
+  min: -100,
+  max: 100,
+  centerZero: {
+    zeroValue: 0,
+    symmetric: true
+  }
+}
+```
+
+## Rolling tape behaves like the wrong instrument
+
+Use exact type:
+
+```js
+type: 'rolling-tape'
+```
+
+The tape has a moving strip and fixed reference line. It does not use radial pointer
+options.
+
+Adjust `tape.interval`, `minorSubdivisions`, and `majorSpacing`, not
+`pointer.length`.
+
+## Readout is missing
+
+This is insufficient:
+
+```js
+readout: {
+  visible: true
+}
+```
+
+Enable each required child:
+
+```js
+readout: {
+  visible: true,
+  title: {
+    visible: true,
+    text: 'PRESSURE'
+  },
+  value: {
+    visible: true
+  },
+  unit: {
+    visible: true,
+    text: 'bar'
+  }
+}
+```
+
+## Readout automatic position is unexpected
+
+`x: 'auto'` centers. `y: 'auto'` uses `position` and `margin`.
+
+`offsetX` and `offsetY` refine automatic coordinates only. Numeric coordinates are
+final and do not inherit automatic offsets.
+
+Type presets may supply different fallback coordinates. Read the selected type defaults
+when exact placement matters.
+
+## Light does not turn on
+
+Check trigger mode.
+
+Manual:
+
+```js
+light: {
+  visible: true,
+  on: true,
+  trigger: {
+    mode: 'manual'
+  }
+}
+```
+
+Threshold:
+
+```js
+light: {
+  visible: true,
+  trigger: {
+    mode: 'above',
+    value: 80
+  }
+}
+```
+
+`on` is ignored by `below`, `above`, and `between`.
+
+Also verify `visible: true`.
+
+## Light does not pulse
+
+Pulse is visible only while the light is active.
+
+Check:
+
+```js
+light: {
+  visible: true,
+  pulse: true,
+  blink: false,
+  trigger: {
+    mode: 'manual'
+  },
+  on: true
+}
+```
+
+Blink takes precedence over pulse. If both are true, the light blinks instead of
+pulsing.
+
+Reduced-motion preference suppresses motion. Test system/browser accessibility
+settings before treating this as a rendering defect.
+
+## Light does not blink
+
+Verify:
+
+- active trigger;
+- `blink: true`;
+- `blinkInterval >= 100`;
+- reduced-motion is not active.
+
+The off half-cycle shows the physical unlit lens rather than making the whole lamp
+transparent.
+
+## Light flicker is not visible
+
+Verify:
+
+```js
+flicker: true
+```
+
+and at least one of:
+
+```js
+flickerIntensity > 0
+flickerGlowRadius > 0
+```
+
+Flicker runs only while active and is disabled under reduced motion.
+
+The default effect is intentionally subtle.
+
+## Glow size does not follow lamp size
+
+In 0.1.1, `glowRadius` is independent:
+
+```js
+light: {
+  radius: 8,
+  glowRadius: 24
+}
+```
+
+Set:
+
+```js
+glowRadius: null
+```
+
+to derive `radius * 1.82`.
+
+Changing only `radius` does not automatically change an explicit numeric
+`glowRadius`.
+
+## Glow is clipped
+
+This should not happen with normalized built-in options because bounds reserve halo
+and blur.
+
+For repository changes, compare rendering math in `src/layers/light.js` with bounds in
+`src/geometry/bounds.js`. A new halo extent, blur formula, or flicker variation requires
+matching bounds changes and tests.
+
+For application custom layers, add correct geometry within the instrument or create a
+type that provides enough layout padding/bounds support.
+
+## Animation does not run
+
+Check:
+
+```js
+animation: {
+  enabled: true,
+  duration: 850
+}
+```
+
+Per update, do not pass:
+
+```js
+{ animate: false }
+```
+
+Reduced-motion may suppress animation when `respectReducedMotion` is true.
+
+No animation is visible when source and target values are identical.
+
+## Startup animation begins from the wrong point
+
+Configure:
+
+```js
+animation: {
+  animateOnInit: true,
+  startFrom: 'min'
+}
+```
+
+Allowed values:
+
+```text
+min
+max
+value
+numeric value
+```
+
+`startFrom: 'value'` intentionally starts at the target and therefore has no visible
+startup travel.
+
+## Jitter changes application data
+
+It should not. Verify application code is reading:
+
+```js
+gauge.getValue()
+gauge.getDisplayedValue()
+```
+
+and not parsing generated pointer transforms.
+
+Jitter is visual-only. If readout or ARIA values jitter after a repository change, the
+dynamic layer is using `state.pointerValue` in the wrong place.
+
+## Gauge continues work offscreen
+
+Defaults are:
+
+```js
+performance: {
+  pauseWhenHidden: true,
+  pauseWhenOffscreen: true
+}
+```
+
+IntersectionObserver may be unavailable in some environments. Manual `pause()` remains
+available.
+
+Repository tests should use controlled lifecycle stubs rather than assuming browser
+observer availability.
+
+## Instance leaks after component removal
+
+An application that creates a gauge manually must destroy it:
+
+```js
+const gauge = Gaugeit.createGauge(host, options);
+
+// component cleanup
+gauge.destroy();
+```
+
+The React adapter and custom element already own cleanup.
+
+Custom layers with timers or observers must return a controller with `destroy()`.
+
+## Auto mounting creates duplicates
+
+`Gaugeit.autoMount()` is duplicate-safe for managed elements. Duplicate SVG usually
+means application code also called `createGauge()` independently or cloned generated
+content.
+
+Use:
+
+```js
+Gaugeit.getMountedGauge(host)
+```
+
+to inspect ownership.
+
+## Custom element options do not update
+
+Observed attributes:
+
+```text
+value
+min
+max
+type
+options
+```
+
+The `options` attribute must be valid JSON. Attribute changes replace the declarative
+option object.
+
+Property assignment for value:
+
+```js
+element.value = 72;
+```
+
+## Laravel or Twig JSON parsing fails
+
+Encode data as JSON and escape it for the HTML attribute context.
+
+Blade:
+
+```blade
+data-options='@json($options)'
+```
+
+Twig:
+
+```twig
+data-options="{{ options|json_encode|e('html_attr') }}"
+```
+
+Plain PHP:
+
+```php
+htmlspecialchars(json_encode($options, JSON_THROW_ON_ERROR), ENT_QUOTES, 'UTF-8')
+```
+
+Do not render PHP array syntax into a browser JSON parser.
+
+## Composer command is missing
+
+Confirm installation:
+
+```bash
+composer show kasperi/gaugeit-js
+```
+
+Use the platform-appropriate vendor binary:
+
+Unix-like:
+
+```bash
+vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit
+```
+
+Windows Composer normally exposes a callable wrapper under `vendor\bin`.
+
+Verify PHP 8.1 or newer.
+
+## Composer assets are installed but browser returns 404
+
+The installer writes to the filesystem path you provide. The web server must expose
+that path.
+
+Check:
+
+- destination is under the actual public document root;
+- framework asset helper matches the destination;
+- deployment included generated public assets;
+- URL casing matches filesystem casing.
+
+## `npm run test:chromium` fails with `spawn chromium ENOENT`
+
+The optional test expects a globally available executable named `chromium`.
+
+This does not mean the library test failed in a browser. It means the process could not
+start Chromium.
+
+Options:
+
+- install Chromium and add it to PATH;
+- adjust the local environment to expose the expected executable;
+- rely on `npm run check` for the portable required suite.
+
+Do not weaken CI because an optional local executable is missing.
+
+## Local `npm run check` passes but GitHub CI fails at reproducibility
+
+Typical symptom:
+
+```text
+git diff --exit-code -- dist package-lock.json
+```
+
+shows source-map differences.
+
+Check:
+
+- source files use LF, not CRLF;
+- Git `core.autocrlf` did not rewrite canonical inputs;
+- generated files do not contain absolute paths;
+- file ordering is deterministic;
+- no timestamps or randomness enter build output;
+- local `dist/` was rebuilt after the final source edit.
+
+Repository policy:
+
+```text
+.editorconfig -> LF
+.gitattributes -> text eol=lf
+```
+
+Run:
+
+```bash
+npm run check
+git diff -- dist package-lock.json
+```
+
+and inspect the generated changes before pushing. To reproduce CI's exit-code check
+locally, stage the intended generated artifacts first and then run:
+
+```bash
+git diff --exit-code -- dist package-lock.json
+```
+
+CI performs this check from a clean checkout, so any post-build diff there is
+unexpected.
+
+## `dist/` changes after a documentation-only edit
+
+Ordinary docs should not change runtime distribution. If `npm run check` changes
+`dist/`, either:
+
+- canonical source had uncommitted changes;
+- previous generated output was stale;
+- line endings or build environment changed;
+- a build script includes documentation unexpectedly.
+
+Inspect the diff before committing.
+
+## Generated files were edited manually
+
+Discard manual generated edits, change canonical source, and rebuild:
+
+```bash
+git restore dist
+npm run build
+```
+
+If canonical source changes are already present, do not restore those. The goal is to
+remove only hand edits from `dist/`.
+
+## TypeScript declarations do not match runtime
+
+Canonical core declarations are:
+
+```text
+src/index.d.ts
+```
+
+The React adapter has a separate canonical declaration:
+
+```text
+adapters/react/Gaugeit.d.ts
+```
+
+Generated core copy:
+
+```text
+dist/gaugeit.d.ts
+```
+
+Update the declaration that owns the affected API, then run:
+
+```bash
+npm run typecheck
+npm run build
+```
+
+and add package-usage tests when an export or option changes.
+
+## Package dry run omits expected files
+
+Check `package.json` `files` and `exports`.
+
+Run:
+
+```bash
+npm pack --dry-run
+```
+
+AI documentation under `docs/` is included because the package publishes `docs`.
+Top-level files not listed in `files` may be absent from the npm tarball even when they
+exist in GitHub.
+
+## npm publication returns 403 requiring 2FA
+
+The package contents may be valid even though publication is rejected.
+
+Use an npm account with publication 2FA or an appropriate granular token. A failed
+403 attempt does not publish the version.
+
+After successful publication, verify:
+
+```bash
+npm view gaugeit.js@0.1.1 name version
+npm view gaugeit.js dist-tags
+```
+
+## Packagist does not show the release
+
+Composer package versions come from Git tags.
+
+Verify:
+
+- GitHub repository is public and correct;
+- `composer.json` is valid;
+- tag exists remotely;
+- Packagist package points to the correct repository;
+- tag corresponds to the intended commit.
+
+Do not add a hard-coded `version` field to `composer.json` merely to fix tag discovery.
+
+## Custom type is not found
+
+Register before instance creation:
+
+```js
+Gaugeit.registerGaugeType('my-type', definition);
+Gaugeit.createGauge('#gauge', {
+  type: 'my-type'
+});
+```
+
+Verify non-empty `layers`. Every layer must expose `render(context)`.
+
+## Custom layer is behind or above the wrong content
+
+Layer array order is SVG paint order. Reorder layers.
+
+For example, pointer above readout:
+
+```js
+layers: [
+  Gaugeit.layers.face,
+  Gaugeit.layers.zones,
+  Gaugeit.layers.ticks,
+  Gaugeit.layers.labels,
+  Gaugeit.layers.readout,
+  Gaugeit.layers.pointer
+]
+```
+
+Do not use numeric CSS z-index as a substitute.
+
+## Custom layer ignores clipping
+
+Create its group through:
+
+```js
+renderer.group('my-layer')
+```
+
+and place it after a face layer that establishes clipping. Appending directly to an
+unmanaged SVG node can bypass renderer ownership and clip-path application.
+
+## Custom timer survives `destroy()`
+
+Return cleanup:
+
+```js
+return {
+  update() {
+    // ...
+  },
+
+  destroy() {
+    clearInterval(timer);
+  }
+};
+```
+
+Test destruction explicitly.
+
+## A bug fix has no regression test
+
+Add the smallest test that demonstrates the defect. Choose the nearest suite:
+
+```text
+options.test.js
+geometry.test.js
+zones.test.js
+linear.test.js
+light.test.js
+lifecycle.test.js
+distribution.test.js
+react-adapter.test.js
+```
+
+A bug fix is incomplete when only the implementation changed.
+
+## Final diagnostic sequence
+
+For application integration:
+
+1. verify distribution and CSS;
+2. verify exact global/import name;
+3. verify host exists and has layout;
+4. reduce options to `{ type, min, max, value }`;
+5. add nested options back one section at a time;
+6. inspect host-scoped Gaugeit events;
+7. test destruction and recreation.
+
+For repository changes:
+
+1. inspect canonical source;
+2. run focused tests;
+3. update declarations and docs;
+4. run `npm run check`;
+5. run reproducibility diff;
+6. inspect `git diff` for accidental files.