@dragonworks/ngx-dashboard-widgets 20.0.5 → 20.1.0

package/index.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { AfterViewInit, OnDestroy } from '@angular/core';
+import { AfterViewInit } from '@angular/core';
 import * as _angular_platform_browser from '@angular/platform-browser';
 import { Widget, WidgetMetadata } from '@dragonworks/ngx-dashboard';
 
@@ -69,6 +69,30 @@ declare class ClockWidgetComponent implements Widget {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ClockWidgetComponent, "ngx-dashboard-clock-widget", never, {}, {}, never, never, true, never>;
 }
 
+interface RadialGaugeWidgetState {
+    value?: number;
+    colorProfile?: 'dynamic' | 'static';
+    active?: boolean;
+    hasBackground?: boolean;
+    showValueLabel?: boolean;
+}
+declare class RadialGaugeWidgetComponent implements Widget {
+    #private;
+    static metadata: WidgetMetadata;
+    readonly safeSvgIcon: _angular_platform_browser.SafeHtml;
+    readonly state: _angular_core.WritableSignal<RadialGaugeWidgetState>;
+    readonly segments: _angular_core.Signal<{
+        from: number;
+        to: number;
+        color: string;
+    }[]>;
+    dashboardSetState(state?: unknown): void;
+    dashboardGetState(): RadialGaugeWidgetState;
+    dashboardEditState(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RadialGaugeWidgetComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RadialGaugeWidgetComponent, "ngx-dashboard-radial-gauge-widget", never, {}, {}, never, never, true, never>;
+}
+
 /**
  * Directive that automatically adjusts font size to fit text within its parent container.
  * Uses canvas-based measurement for performance and DOM verification for accuracy.
@@ -78,7 +102,7 @@ declare class ClockWidgetComponent implements Widget {
  *   <span responsiveText [minFontSize]="12" [maxFontSize]="72">Dynamic text here</span>
  * </div>
  */
-declare class ResponsiveTextDirective implements AfterViewInit, OnDestroy {
+declare class ResponsiveTextDirective implements AfterViewInit {
     /** Minimum font-size in pixels (accessibility floor) */
     minFontSize: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Maximum font-size in pixels (layout ceiling) */
@@ -105,8 +129,8 @@ declare class ResponsiveTextDirective implements AfterViewInit, OnDestroy {
     private lastMaxW;
     private lastMaxH;
     private lastFontSize;
+    constructor();
     ngAfterViewInit(): void;
-    ngOnDestroy(): void;
     /**
      * Debounced fit handler to prevent excessive recalculations
      */
@@ -144,8 +168,365 @@ declare class ResponsiveTextDirective implements AfterViewInit, OnDestroy {
      */
     private cleanup;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ResponsiveTextDirective, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ResponsiveTextDirective, "[responsiveText]", never, { "minFontSize": { "alias": "minFontSize"; "required": false; "isSignal": true; }; "maxFontSize": { "alias": "maxFontSize"; "required": false; "isSignal": true; }; "lineHeight": { "alias": "lineHeight"; "required": false; "isSignal": true; }; "observeMutations": { "alias": "observeMutations"; "required": false; "isSignal": true; }; "debounceMs": { "alias": "debounceMs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ResponsiveTextDirective, "[libResponsiveText]", never, { "minFontSize": { "alias": "minFontSize"; "required": false; "isSignal": true; }; "maxFontSize": { "alias": "maxFontSize"; "required": false; "isSignal": true; }; "lineHeight": { "alias": "lineHeight"; "required": false; "isSignal": true; }; "observeMutations": { "alias": "observeMutations"; "required": false; "isSignal": true; }; "debounceMs": { "alias": "debounceMs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+interface RadialGaugeSegment {
+    from: number;
+    to: number;
+    color: string;
+}
+/**
+ * Responsive radial gauge component with hybrid sizing and thickness control.
+ *
+ * This component provides a highly flexible gauge system with three independent
+ * control dimensions that can be mixed and matched for different use cases:
+ *
+ * ## Size Control:
+ * - **Fixed Size**: Use manual `size` input (traditional behavior)
+ * - **Container Responsive**: Enable `fitToContainer` for automatic sizing
+ *
+ * ## Thickness Control:
+ * - **Manual Thickness**: Use individual thickness inputs (traditional behavior)
+ * - **Proportional Thickness**: Enable `responsiveMode` for size-based scaling
+ *
+ * ## Usage Scenarios:
+ *
+ * ### 1. Dashboard Widgets (Recommended)
+ * ```html
+ * <ngx-radial-gauge
+ *   [value]="cpuUsage"
+ *   [fitToContainer]="true"
+ *   [responsiveMode]="true"
+ *   [sizeToThicknessRatio]="12" />
+ * ```
+ * **Best for**: Grid layouts, dashboard panels, adaptive containers
+ * **Behavior**: Automatically resizes to fit available space while maintaining
+ * consistent proportional appearance across all sizes.
+ *
+ * ### 2. Fixed Layouts (Traditional)
+ * ```html
+ * <ngx-radial-gauge
+ *   [value]="temperature"
+ *   [size]="300"
+ *   [outerThickness]="36"
+ *   [innerThickness]="12" />
+ * ```
+ * **Best for**: Static designs, precise sizing requirements, print layouts
+ * **Behavior**: Exact pixel control over all dimensions, predictable appearance.
+ *
+ * ### 3. Scalable Designs
+ * ```html
+ * <ngx-radial-gauge
+ *   [value]="batteryLevel"
+ *   [size]="gaugeSize"
+ *   [responsiveMode]="true"
+ *   [sizeToThicknessRatio]="20" />
+ * ```
+ * **Best for**: User-configurable sizing, responsive breakpoints, zoom interfaces
+ * **Behavior**: Manual size control with automatic thickness scaling. As size
+ * increases/decreases, ring thickness scales proportionally to maintain visual balance.
+ *
+ * ## Mathematical Relationships:
+ *
+ * When `responsiveMode=true`, thickness follows this formula:
+ * ```
+ * baseThickness = effectiveSize / sizeToThicknessRatio
+ * outerThickness = baseThickness × responsiveProportions.outer (default: 3)
+ * innerThickness = baseThickness × responsiveProportions.inner (default: 1)
+ * gap = baseThickness × responsiveProportions.gap (default: 0.5)
+ * totalThickness = baseThickness × 4.5 (outer + inner + gap)
+ * ```
+ *
+ * Example with 300px gauge and ratio=20 (ultra-thin):
+ * - baseThickness = 15px
+ * - outerThickness = 45px (15×3)
+ * - innerThickness = 15px (15×1)
+ * - gap = 7.5px (15×0.5)
+ * - totalThickness = 67.5px (22.5% of diameter)
+ *
+ * ## Container Responsiveness:
+ *
+ * When `fitToContainer=true`, the component uses ResizeObserver to:
+ * 1. Monitor parent container dimension changes
+ * 2. Calculate maximum diameter maintaining 2:1 aspect ratio (width:height)
+ * 3. Apply containerPadding for safe margins
+ * 4. Update gauge size in real-time
+ *
+ * This provides true responsive behavior for dashboard widgets, grid layouts,
+ * and adaptive interfaces.
+ *
+ * ## Accessibility:
+ *
+ * The component implements ARIA meter role with proper labeling:
+ * - `role="meter"` for semantic meaning
+ * - `aria-valuemin/max/now` for screen readers
+ * - `aria-label` with contextual information
+ * - Internationalized number formatting
+ *
+ */
+declare class RadialGaugeComponent {
+    private readonly valueTextEl;
+    private readonly valueGroupEl;
+    private readonly refTextEl;
+    readonly value: _angular_core.InputSignal<number>;
+    readonly min: _angular_core.InputSignal<number>;
+    readonly max: _angular_core.InputSignal<number>;
+    readonly segments: _angular_core.InputSignal<RadialGaugeSegment[] | undefined>;
+    readonly title: _angular_core.InputSignal<string>;
+    readonly description: _angular_core.InputSignal<string>;
+    readonly segmentGapPx: _angular_core.InputSignal<number>;
+    /**
+     * Whether the gauge should display with a background.
+     * Affects text color contrast and other visual elements.
+     * @default false
+     */
+    readonly hasBackground: _angular_core.InputSignal<boolean>;
+    /**
+     * Whether to display the numeric value label in the center of the gauge.
+     * @default true
+     */
+    readonly showValueLabel: _angular_core.InputSignal<boolean>;
+    /**
+     * Base gauge diameter in pixels. Used as fallback when fitToContainer is false.
+     * @default 300
+     */
+    readonly size: _angular_core.InputSignal<number>;
+    /**
+     * Automatically resize gauge to fit its container dimensions.
+     * When true, the gauge will observe container size changes and adjust accordingly.
+     * Maintains semicircle aspect ratio (2:1 width:height).
+     * @default false
+     */
+    readonly fitToContainer: _angular_core.InputSignal<boolean>;
+    /**
+     * Padding in pixels to maintain from container edges when fitToContainer is true.
+     * @default 10
+     */
+    readonly containerPadding: _angular_core.InputSignal<number>;
+    /**
+     * Use proportional thickness scaling based on gauge size.
+     * When true, all thickness values are calculated as multiples of baseThickness.
+     * Overrides manual outerThickness, innerThickness, and gap inputs.
+     * @default false
+     */
+    readonly responsiveMode: _angular_core.InputSignal<boolean>;
+    /**
+     * Ratio used to calculate base thickness from gauge size.
+     * baseThickness = effectiveSize / sizeToThicknessRatio
+     * Higher values create thinner gauge rings for ultra-thin appearance.
+     * @default 20
+     * @example
+     * - ratio=15: thicker rings (bt = size/15)
+     * - ratio=20: ultra-thin balanced appearance (bt = size/20)
+     * - ratio=30: extremely thin rings (bt = size/30)
+     */
+    readonly sizeToThicknessRatio: _angular_core.InputSignal<number>;
+    /**
+     * Proportional multipliers for responsive thickness calculations.
+     * - outer: Multiplier for outer ring thickness (default: 3)
+     * - inner: Multiplier for inner ring thickness (default: 1)
+     * - gap: Multiplier for gap between rings (default: 0.5)
+     * Total thickness = baseThickness × (outer + inner + gap) = bt × 4.5
+     * @default { outer: 3, inner: 1, gap: 0.5 }
+     */
+    readonly responsiveProportions: _angular_core.InputSignal<{
+        outer: number;
+        inner: number;
+        gap: number;
+    }>;
+    /**
+     * Manual outer ring thickness in pixels. Ignored when responsiveMode is true.
+     * @default 36
+     */
+    readonly outerThickness: _angular_core.InputSignal<number>;
+    /**
+     * Manual inner ring thickness in pixels. Ignored when responsiveMode is true.
+     * @default 12
+     */
+    readonly innerThickness: _angular_core.InputSignal<number>;
+    /**
+     * Manual gap between rings in pixels. Ignored when responsiveMode is true.
+     * @default 8
+     */
+    readonly gap: _angular_core.InputSignal<number>;
+    readonly titleId: string;
+    readonly descId: string;
+    readonly clipId: string;
+    private readonly locale;
+    private readonly elementRef;
+    private readonly destroyRef;
+    private readonly nf;
+    /**
+     * Tracks the container's available size for responsive sizing.
+     * Updated by ResizeObserver when fitToContainer is enabled.
+     * @private
+     */
+    private readonly containerSize;
+    /**
+     * ResizeObserver instance for monitoring container size changes.
+     * Created when fitToContainer is enabled, destroyed on component cleanup.
+     * @private
+     */
+    private resizeObserver;
+    readonly viewReady: _angular_core.Signal<boolean>;
+    readonly fontsReady: _angular_core.Signal<boolean>;
+    constructor();
+    /**
+     * Effect that manages ResizeObserver lifecycle based on fitToContainer input.
+     * Automatically connects/disconnects observer when the input changes.
+     * @private
+     */
+    private readonly containerObserverEffect;
+    referenceString: _angular_core.Signal<string>;
+    valueTransform: _angular_core.Signal<string>;
+    /** Guarded getBBox that avoids 0/NaN on detached or invisible nodes. */
+    safeBBox(node: SVGGraphicsElement): DOMRect;
+    /**
+     * The effective gauge diameter, accounting for container sizing and manual size input.
+     * Priority: containerSize (when fitToContainer=true) > manual size input
+     * @returns Effective diameter in pixels
+     *
+     * @example
+     * // Fixed size mode
+     * fitToContainer=false, size=300 → effectiveSize=300
+     *
+     * // Container responsive mode
+     * fitToContainer=true, container=400px wide → effectiveSize=380 (minus padding)
+     */
+    private readonly effectiveSize;
+    /**
+     * Base thickness calculated from effective size for proportional scaling.
+     * Only used when responsiveMode is enabled.
+     * Formula: baseThickness = effectiveSize / sizeToThicknessRatio
+     * @returns Base thickness in pixels, or 0 when responsiveMode is false
+     *
+     * @example
+     * // effectiveSize=300, sizeToThicknessRatio=12
+     * baseThickness = 300/12 = 25px
+     * // Total ring thickness = 25 × 4.5 = 112.5px (37.5% of diameter)
+     */
+    private readonly baseThickness;
+    /**
+     * Effective outer ring thickness, supporting both manual and responsive modes.
+     * - Responsive mode: baseThickness × responsiveProportions.outer
+     * - Manual mode: outerThickness input value
+     * @returns Outer ring thickness in pixels
+     */
+    readonly effectiveOuterThickness: _angular_core.Signal<number>;
+    /**
+     * Effective inner ring thickness, supporting both manual and responsive modes.
+     * - Responsive mode: baseThickness × responsiveProportions.inner
+     * - Manual mode: innerThickness input value
+     * @returns Inner ring thickness in pixels
+     */
+    readonly effectiveInnerThickness: _angular_core.Signal<number>;
+    /**
+     * Effective gap between rings, supporting both manual and responsive modes.
+     * - Responsive mode: baseThickness × responsiveProportions.gap
+     * - Manual mode: gap input value
+     * @returns Gap between rings in pixels
+     */
+    readonly effectiveGap: _angular_core.Signal<number>;
+    private readonly svgPadding;
+    readonly svgWidth: _angular_core.Signal<number>;
+    readonly svgHeight: _angular_core.Signal<number>;
+    readonly centerX: _angular_core.Signal<number>;
+    readonly centerY: _angular_core.Signal<number>;
+    /**
+     * If a string is provided, we measure it and allocate space for that width.
+     * If a number is provided, we build a string of that many `referenceGlyph`s.
+     * If omitted, we fall back to measuring the actual label.
+     */
+    labelReference: _angular_core.InputSignal<string | number | undefined>;
+    /** Glyph to repeat when labelReference is a number (defaults to '0'). */
+    referenceGlyph: _angular_core.InputSignal<string>;
+    /** Extra breathing room inside the inner semicircle box (in px). */
+    labelPadding: _angular_core.InputSignal<number>;
+    /** Safety multiplier to avoid clipping ascenders/descenders. */
+    baselineSafety: _angular_core.InputSignal<number>;
+    readonly outerRadius: _angular_core.Signal<number>;
+    readonly innerRadius: _angular_core.Signal<number>;
+    readonly legendOuterRadius: _angular_core.Signal<number>;
+    readonly legendInnerRadius: _angular_core.Signal<number>;
+    private readonly startAngle;
+    private readonly endAngle;
+    readonly clampedValue: _angular_core.Signal<number>;
+    readonly percentage: _angular_core.Signal<number>;
+    readonly percent: _angular_core.Signal<number>;
+    private readonly defaultSegments;
+    readonly actualSegments: _angular_core.Signal<RadialGaugeSegment[]>;
+    readonly formattedLabel: _angular_core.Signal<string>;
+    readonly valueColor: _angular_core.Signal<string>;
+    readonly backgroundArcPath: _angular_core.Signal<string>;
+    readonly segmentPaths: _angular_core.Signal<{
+        path: string;
+        color: string;
+    }[]>;
+    readonly ariaLabel: _angular_core.Signal<string>;
+    private clamp;
+    /**
+     * Converts a percentage (0-1) to an angle position on the gauge arc.
+     * The gauge spans from startAngle (-180°) to endAngle (0°), creating a semicircle.
+     * @param p - Percentage value between 0 and 1
+     * @returns Angle in degrees for the given percentage along the gauge arc
+     * @example
+     * angleForPercentage(0) => -180° (start of gauge)
+     * angleForPercentage(0.5) => -90° (middle of gauge)
+     * angleForPercentage(1) => 0° (end of gauge)
+     */
+    private angleForPercentage;
+    /**
+     * Converts polar coordinates (radius, angle) to Cartesian coordinates (x, y).
+     * Uses standard trigonometric conversion where angle 0° points to the right (3 o'clock).
+     * @param cx - Center X coordinate of the circle
+     * @param cy - Center Y coordinate of the circle
+     * @param r - Radius distance from center
+     * @param angle - Angle in degrees (0° = right, 90° = down, 180° = left, -90° = up)
+     * @returns Object with x and y Cartesian coordinates
+     * @example
+     * polarToCartesian(100, 100, 50, 0) => {x: 150, y: 100} // 3 o'clock
+     * polarToCartesian(100, 100, 50, -90) => {x: 100, y: 50} // 12 o'clock
+     */
+    private polarToCartesian;
+    /**
+     * Creates an SVG path string for a circular arc segment.
+     * Uses SVG arc path commands to draw an arc from start angle to end angle.
+     * @param r - Radius of the arc
+     * @param a0 - Starting angle in degrees
+     * @param a1 - Ending angle in degrees
+     * @returns SVG path string defining the arc
+     * @example
+     * createArcPath(50, -180, 0) => "M cx-50 cy A 50 50 0 1 1 cx+50 cy"
+     * This creates a semicircle from left (-180°) to right (0°)
+     *
+     * SVG Arc Parameters:
+     * - rx, ry: Radii (equal for circular arc)
+     * - x-axis-rotation: 0 (no rotation for circles)
+     * - large-arc-flag: 1 if arc > 180°, 0 otherwise
+     * - sweep-flag: 1 for clockwise, 0 for counter-clockwise
+     */
+    private createArcPath;
+    /**
+     * Calculates the angular gap in degrees needed for a specific pixel gap at a given radius.
+     * Used to create visual separation between legend segments.
+     * @param px - Desired gap size in pixels
+     * @param r - Radius at which the gap will appear
+     * @returns Gap size in degrees, clamped between 0° and 180°
+     * @example
+     * For a 4px gap on a radius of 100px:
+     * Arc length = π * 100 = 314.16px (semicircle)
+     * Degrees = 180 * (4 / 314.16) ≈ 2.3°
+     *
+     * Mathematical basis:
+     * - Semicircle arc length = π * r
+     * - Ratio of gap to semicircle = px / (π * r)
+     * - Convert ratio to degrees by multiplying by 180°
+     */
+    private gapDegreesForRadius;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RadialGaugeComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RadialGaugeComponent, "ngx-radial-gauge", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "segments": { "alias": "segments"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "segmentGapPx": { "alias": "segmentGapPx"; "required": false; "isSignal": true; }; "hasBackground": { "alias": "hasBackground"; "required": false; "isSignal": true; }; "showValueLabel": { "alias": "showValueLabel"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "fitToContainer": { "alias": "fitToContainer"; "required": false; "isSignal": true; }; "containerPadding": { "alias": "containerPadding"; "required": false; "isSignal": true; }; "responsiveMode": { "alias": "responsiveMode"; "required": false; "isSignal": true; }; "sizeToThicknessRatio": { "alias": "sizeToThicknessRatio"; "required": false; "isSignal": true; }; "responsiveProportions": { "alias": "responsiveProportions"; "required": false; "isSignal": true; }; "outerThickness": { "alias": "outerThickness"; "required": false; "isSignal": true; }; "innerThickness": { "alias": "innerThickness"; "required": false; "isSignal": true; }; "gap": { "alias": "gap"; "required": false; "isSignal": true; }; "labelReference": { "alias": "labelReference"; "required": false; "isSignal": true; }; "referenceGlyph": { "alias": "referenceGlyph"; "required": false; "isSignal": true; }; "labelPadding": { "alias": "labelPadding"; "required": false; "isSignal": true; }; "baselineSafety": { "alias": "baselineSafety"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { ArrowWidgetComponent, ClockWidgetComponent, LabelWidgetComponent, ResponsiveTextDirective };
-export type { ArrowWidgetState, ClockWidgetState, LabelWidgetState };
+export { ArrowWidgetComponent, ClockWidgetComponent, LabelWidgetComponent, RadialGaugeComponent, RadialGaugeWidgetComponent, ResponsiveTextDirective };
+export type { ArrowWidgetState, ClockWidgetState, LabelWidgetState, RadialGaugeSegment, RadialGaugeWidgetState };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dragonworks/ngx-dashboard-widgets",
-  "version": "20.0.5",
+  "version": "20.1.0",
   "description": "Widget collection for ngx-dashboard with Material Design 3 compliance including arrow, label, clock widgets and responsive text directive",
   "peerDependencies": {
-    "@angular/common": "^20.0.0",
-    "@angular/core": "^20.0.0",
+    "@angular/common": "^20.2.0",
+    "@angular/core": "^20.2.0",
     "@dragonworks/ngx-dashboard": "^20.0.0"
   },
   "dependencies": {