gaugeit.js 0.1.0

package/dist/gaugeit.d.ts

@@ -0,0 +1,442 @@
+export type GaugeTarget = Element | string;
+export type GaugeOverflow = 'clamp' | 'expand' | 'allow';
+export type GaugePointerType = 'needle' | 'line' | 'arrow' | 'spear';
+export type GaugeScalePosition = 'inside' | 'outside' | 'cross';
+export type GaugeLabelRotation = 'horizontal' | 'radial' | 'tangent';
+export type GaugeLayoutMode = 'intrinsic' | 'contain';
+export type GaugeGeometryMode = 'radial' | 'linear' | 'tape';
+export type GaugeLinearTickSide = 'negative' | 'positive' | 'cross';
+export type GaugeLinearIndicatorType = 'hairline' | 'marker' | 'carriage';
+export type GaugeLinearIndicatorPosition = 'negative' | 'positive' | 'cross';
+export type GaugeScaleEndpointMode = 'auto' | 'both' | 'dedupe';
+export type GaugeReadoutPosition = 'top' | 'center' | 'bottom';
+export type GaugeCapStackOrder = 'above' | 'below';
+export type GaugeOrientation = 'vertical' | 'horizontal';
+export type GaugeLightColor = 'red' | 'green' | 'blue' | 'amber' | 'yellow' | 'orange' | 'white' | 'halogen' | 'cyan' | 'brown';
+export type GaugeLightTriggerMode = 'manual' | 'below' | 'above' | 'between';
+export type GaugeLightTriggerSource = 'target' | 'displayed' | 'pointer';
+export type GaugeEasing = string | ((progress: number) => number);
+
+export interface GaugeReadoutTextOptions {
+  visible?: boolean;
+  text?: string;
+  x?: number | 'auto';
+  y?: number | 'auto';
+  position?: GaugeReadoutPosition;
+  margin?: number;
+  offsetX?: number;
+  offsetY?: number;
+  color?: string;
+  fontFamily?: string;
+  fontSize?: number;
+  fontWeight?: string | number;
+  letterSpacing?: number;
+}
+
+export interface GaugeReadoutValueOptions extends GaugeReadoutTextOptions {
+  fractionDigits?: number;
+  prefix?: string;
+  suffix?: string;
+  locale?: string | string[];
+  formatter?: (value: number, context: GaugeFormatterContext) => string;
+}
+
+export interface GaugeLightOptions {
+  visible?: boolean;
+  x?: number;
+  y?: number;
+  radius?: number;
+  color?: GaugeLightColor;
+  customColor?: string;
+  /** Cream-toned unlit lens color. */
+  offColor?: string;
+  /** Darker unlit lens edge color. */
+  offEdgeColor?: string;
+  bezelColor?: string;
+  bezelHighlightColor?: string;
+  opacity?: number;
+  on?: boolean;
+  glow?: boolean;
+  /** Enables a very subtle steady-light breathing effect. */
+  pulse?: boolean;
+  pulseInterval?: number;
+  blink?: boolean;
+  blinkInterval?: number;
+  trigger?: {
+    mode?: GaugeLightTriggerMode;
+    /** Value stream used by threshold evaluation. Defaults to the requested target value. */
+    source?: GaugeLightTriggerSource;
+    value?: number;
+    min?: number;
+    max?: number;
+  };
+}
+
+export interface GaugeZone {
+  min: number;
+  max: number;
+  color?: string;
+  strokeStyle?: string;
+  width?: number;
+  /** Optional variable-width radial segment. Widths are measured at min and max. */
+  taper?: {
+    startWidth?: number;
+    endWidth?: number;
+    segments?: number;
+  };
+  radius?: number;
+  opacity?: number;
+  lineCap?: string;
+  className?: string;
+  offset?: number;
+}
+
+export interface GaugeOptions {
+  type?: string;
+  min?: number;
+  max?: number;
+  value?: number;
+  invert?: boolean;
+  overflow?: GaugeOverflow;
+  precision?: number;
+  className?: string;
+  layout?: {
+    mode?: GaugeLayoutMode;
+    padding?: number;
+    includeGeometry?: boolean;
+  };
+  geometry?: {
+    mode?: GaugeGeometryMode;
+    width?: number;
+    height?: number;
+    centerX?: number;
+    centerY?: number;
+    radius?: number;
+    startAngle?: number;
+    endAngle?: number;
+    preserveAspectRatio?: string;
+    /** Optional intrinsic design ratio. Resizable presets derive a missing dimension from it. */
+    aspectRatio?: number | null;
+  };
+  linear?: {
+    /** SVG Y coordinate used as the public Cartesian y=0 baseline. */
+    originY?: number;
+    startX?: number;
+    /** Positive values move upward from originY. */
+    startY?: number;
+    endX?: number;
+    /** Positive values move upward from originY. */
+    endY?: number;
+    tickSide?: GaugeLinearTickSide;
+    /** Positive values move toward the visual upper side of a left-to-right axis. */
+    labelOffset?: number;
+    /** Positive values move toward the visual upper side of a left-to-right axis. */
+    zoneOffset?: number;
+  };
+  centerZero?: {
+    zeroValue?: number;
+    symmetric?: boolean;
+    marker?: {
+      visible?: boolean;
+      radius?: number | null;
+      position?: GaugeLinearIndicatorPosition;
+      /** Positive values move upward on a left-to-right linear axis. */
+      centerOffset?: number;
+      length?: number;
+      width?: number;
+      color?: string;
+      opacity?: number;
+      lineCap?: string;
+    };
+  };
+  tape?: {
+    orientation?: GaugeOrientation;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    cornerRadius?: number;
+    windowColor?: string;
+    windowStrokeColor?: string;
+    windowStrokeWidth?: number;
+    windowInnerStrokeColor?: string;
+    windowInnerStrokeWidth?: number;
+    stripColor?: string;
+    textColor?: string;
+    tickColor?: string;
+    minorTickColor?: string;
+    minorTickOpacity?: number;
+    majorTickWidth?: number;
+    minorTickWidth?: number;
+    majorTickLength?: number;
+    minorTickLength?: number;
+    tickInset?: number;
+    labelOffset?: number;
+    interval?: number | null;
+    minorSubdivisions?: number;
+    majorSpacing?: number;
+    indicatorColor?: string;
+    indicatorWidth?: number;
+    fadeSize?: number;
+    fadeColor?: string;
+    colorByZone?: boolean;
+  };
+  face?: {
+    visible?: boolean;
+    shape?: 'panel' | 'circle';
+    fit?: 'geometry' | 'content';
+    contentPadding?: number;
+    minWidth?: number | null;
+    minHeight?: number | null;
+    clipContent?: boolean;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    cornerRadius?: number;
+    color?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    innerStrokeColor?: string;
+    innerStrokeWidth?: number;
+    shadow?: boolean;
+    glass?: boolean;
+  };
+  track?: {
+    visible?: boolean;
+    color?: string;
+    width?: number;
+    radius?: number;
+    opacity?: number;
+    lineCap?: string;
+    showUnderZones?: boolean;
+  };
+  zones?: GaugeZone[];
+  scale?: {
+    endpointMode?: GaugeScaleEndpointMode;
+    radius?: number;
+    position?: GaugeScalePosition;
+    major?: {
+      visible?: boolean;
+      interval?: number | null;
+      divisions?: number;
+      length?: number;
+      width?: number;
+      color?: string;
+      opacity?: number;
+    };
+    minor?: {
+      visible?: boolean;
+      subdivisions?: number;
+      length?: number;
+      width?: number;
+      color?: string;
+      opacity?: number;
+    };
+  };
+  labels?: {
+    visible?: boolean;
+    interval?: number | null;
+    radius?: number;
+    color?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string | number;
+    fractionDigits?: number;
+    rotation?: GaugeLabelRotation;
+    formatter?: (value: number, context: GaugeFormatterContext) => string;
+  };
+  pointer?: {
+    visible?: boolean;
+    type?: GaugePointerType;
+    length?: number;
+    shaftLength?: number | null;
+    tailLength?: number;
+    width?: number;
+    color?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    colorByZone?: boolean;
+    cap?: {
+      visible?: boolean;
+      /** SVG paint order relative to the pointer shape. */
+      stackOrder?: GaugeCapStackOrder;
+      radius?: number;
+      color?: string;
+      strokeColor?: string;
+      strokeWidth?: number;
+    };
+  };
+  indicator?: {
+    visible?: boolean;
+    type?: GaugeLinearIndicatorType;
+    position?: GaugeLinearIndicatorPosition;
+    length?: number;
+    centerOffset?: number;
+    /** @deprecated Use centerOffset. Positive legacy offsets moved toward the positive axis normal. */
+    offset?: number;
+    width?: number;
+    color?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    lineCap?: string;
+    colorByZone?: boolean;
+    markerSize?: number;
+    carriageWidth?: number;
+    carriageRadius?: number;
+    cap?: {
+      visible?: boolean;
+      /** SVG paint order relative to the linear indicator shape. */
+      stackOrder?: GaugeCapStackOrder;
+      radius?: number;
+      color?: string;
+      strokeColor?: string;
+      strokeWidth?: number;
+    };
+  };
+  light?: GaugeLightOptions;
+  readout?: {
+    visible?: boolean;
+    title?: GaugeReadoutTextOptions;
+    value?: GaugeReadoutValueOptions;
+    unit?: GaugeReadoutTextOptions;
+  };
+  animation?: {
+    enabled?: boolean;
+    duration?: number;
+    easing?: GaugeEasing;
+    animateOnInit?: boolean;
+    startFrom?: 'min' | 'max' | 'value' | number;
+    respectReducedMotion?: boolean;
+  };
+  effects?: {
+    jitter?: {
+      enabled?: boolean;
+      amplitude?: number;
+      amplitudeUnit?: 'value' | 'percent';
+      frequency?: number;
+      smoothing?: number;
+      whenIdleOnly?: boolean;
+    };
+  };
+  accessibility?: {
+    label?: string;
+    description?: string;
+    valueText?: string | ((value: number, options: GaugeOptions) => string);
+  };
+  performance?: {
+    pauseWhenHidden?: boolean;
+    pauseWhenOffscreen?: boolean;
+  };
+  responsive?: boolean;
+}
+
+export interface GaugeFormatterContext {
+  min: number;
+  max: number;
+  options: GaugeOptions;
+}
+
+export interface GaugeValueUpdateOptions {
+  animate?: boolean;
+  duration?: number;
+  easing?: GaugeEasing;
+}
+
+export interface GaugeLayer {
+  id?: string;
+  render(context: GaugeRenderContext): void | GaugeLayerController;
+}
+
+export interface GaugeLayerController {
+  update(value: number, state: GaugeRenderState): void;
+  destroy?(): void;
+}
+
+export interface GaugeRenderState {
+  gauge: Gauge;
+  targetValue: number;
+  baseValue: number;
+  pointerValue: number;
+  animated: boolean;
+  jitterOffset: number;
+}
+
+export interface GaugeTypeDefinition {
+  description?: string;
+  defaults?: GaugeOptions;
+  /** Optional type-level normalization hook used by resizable or specialized presets. */
+  configure?: (
+    options: GaugeOptions,
+    context: { requested: GaugeOptions; typeDefaults: GaugeOptions }
+  ) => GaugeOptions | void;
+  layers: GaugeLayer[];
+}
+
+export interface GaugeRenderContext {
+  gauge: Gauge;
+  options: GaugeOptions;
+  renderer: unknown;
+  registry: GaugeTypeRegistry;
+}
+
+export class Gauge {
+  constructor(target: GaugeTarget, options: GaugeOptions, registry: GaugeTypeRegistry);
+  render(): this;
+  setValue(value: number, options?: GaugeValueUpdateOptions): this;
+  set(value: number, options?: GaugeValueUpdateOptions): this;
+  updateOptions(options: GaugeOptions, behavior?: { animateToValue?: boolean }): this;
+  replaceOptions(options: GaugeOptions, behavior?: { animateToValue?: boolean }): this;
+  setOptions(options: GaugeOptions, behavior?: { animateToValue?: boolean }): this;
+  getValue(): number;
+  getDisplayedValue(): number;
+  pause(): this;
+  resume(): this;
+  refresh(): this;
+  destroy(): void;
+}
+
+export class GaugeTypeRegistry {
+  register(name: string, definition: GaugeTypeDefinition): this;
+  get(name: string): GaugeTypeDefinition;
+  has(name: string): boolean;
+  names(): string[];
+  describe(): Array<{ name: string; description: string }>;
+}
+
+export function createGauge(target: GaugeTarget, options?: GaugeOptions): Gauge;
+export function registerGaugeType(name: string, definition: GaugeTypeDefinition): typeof Gaugeit;
+export function autoMount(selector?: string, root?: ParentNode): Gauge[];
+export function defineGaugeitElement(tagName?: string): CustomElementConstructor | null;
+export function getMountedGauge(element: Element): Gauge | null;
+export function unmountGauge(element: Element): boolean;
+
+export const VERSION: string;
+export const layers: Record<string, GaugeLayer>;
+export const types: Record<string, GaugeTypeDefinition>;
+export const geometry: Record<string, (...args: any[]) => any>;
+export const easingNames: readonly string[];
+export const gaugeTypeRegistry: GaugeTypeRegistry;
+export const deepMerge: (base: unknown, override: unknown) => unknown;
+
+declare const Gaugeit: {
+  VERSION: string;
+  Gauge: typeof Gauge;
+  GaugeTypeRegistry: typeof GaugeTypeRegistry;
+  createGauge: typeof createGauge;
+  registerGaugeType: typeof registerGaugeType;
+  autoMount: typeof autoMount;
+  defineGaugeitElement: typeof defineGaugeitElement;
+  getMountedGauge: typeof getMountedGauge;
+  unmountGauge: typeof unmountGauge;
+  registry: GaugeTypeRegistry;
+  types: typeof types;
+  layers: typeof layers;
+  geometry: typeof geometry;
+  deepMerge: typeof deepMerge;
+  easingNames: typeof easingNames;
+};
+
+export default Gaugeit;