@componyx/ui 0.0.0-stage → 1.0.3

package/PieChart/PieChart.js

@@ -0,0 +1,820 @@
+/*! Componyx.UI | (c) E.H. Daanen / Componyx | BUSL-1.1 | componyx.com/license */
+import '../Base/Base.js';
+import '../Base/Library.js';
+import '../TooltipManager/TooltipManager.js';
+
+(function ()
+{
+    /**
+     * PieChart CSS Variables.
+     * @typedef {Object} CSSVariables
+     * @memberof componyx.UI.PieChart
+     * @property {string} ["--donut-inner-stop"]                                    - This CSS value is based on the donutInnerRatio setting.
+     * @property {string} ["--chart-size"]                                          - The rendered chart size in pixels (half-pie only), used to align the legend with the semicircle.
+     */
+
+    /**
+    * PieChart class.
+    * @class
+    * @memberof componyx.UI
+    * @augments componyx.UI.base.WebComponent
+    * @mixes componyx.UI.base.methods
+    * @param {String} id The id of the component.
+    * @param {Object|HTMLElement} properties The properties used to initialize the component or the container element.
+    * @returns {componyx.UI.PieChart} An instance of the component.
+    */
+    class PieChart extends componyx.UI.base.WebComponent 
+    {
+        #chart;
+        #segmentOverlay;
+        #legend;
+        #size;
+        #totalAngleDeg;
+        #startAngleDeg;
+        #totalValue;
+        #segmentAngleRanges = []; // Cache for segment angle ranges
+        #currentHoveredIndex = null;
+        #tooltipManager;
+        #leaveTimerId;
+        #segmentLabels = []; // label elements with their mid angle, for repositioning
+        #resizeObserver;
+        #outsidePointerDown;
+
+        /**
+        * Internal CSS class name constants.
+        * You can override any of these classes on the Component instance by defining a property named
+        * `cssClass<Key>` where <Key> is the PascalCase key from this object.
+        * Example:
+        *  'PANEL' -> 'cssClassPanel'
+        * Be cautious: overriding these classes without including the default names may break styling and functionality.
+        * @constant
+        * @type {Readonly<Object<string, string>>}
+        */
+        classOption =
+            {
+                CHART: 'chart',
+                HALF: 'half-pie',
+                DONUT: 'donut',
+                LEGEND: 'legend',
+                LEGEND_ITEM: 'legend-item',
+                LEGEND_ITEM_COLOR: 'legend-item-color',
+                LEGEND_ITEM_LABEL: 'legend-item-label',
+                SEGMENT_LABEL: 'segment-label',
+                SEGMENT_OVERLAY: 'segment-overlay',
+                SEGMENT_HOVER: 'segment-hover'
+            };
+
+        constructor(id, properties)
+        {
+            super(id, properties);
+
+            /**
+             * Gets or sets the shape of the pie chart (PIE or DONUT).
+             * @type {componyx.UI.PieChart.ShapeOption}
+             */
+            this.shape = PieChart.ShapeOption.PIE;
+
+            /**
+             * Gets or sets where the segment labels are displayed (NONE, INNER, or OUTER).
+             * @type {componyx.UI.PieChart.SegmentLabelDisplayOption}
+             */
+            this.segmentLabelDisplay = PieChart.SegmentLabelDisplayOption.OUTER;
+
+            /**
+             * Gets or sets the content of the segment labels (VALUE, LABEL, LABEL_VALUE).
+             * @type {componyx.UI.PieChart.SegmentLabelContentOption}
+             */
+            this.segmentLabelContent = PieChart.SegmentLabelContentOption.VALUE;
+
+            /**
+             * Gets or sets a value indicating whether the chart spans half a circle.
+             * @type {Boolean}
+             */
+            this.isHalf = false;
+
+            /**
+             * Gets or sets a value indicating whether the legend is displayed.
+             * @type {Boolean}
+             */
+            this.showLegend = true;
+
+            /**
+             *  Gets or sets a value indicating whether segment values are shown in the legend labels.
+             * @type {Boolean}
+             */
+            this.showValuesInLegend = false;
+
+            /**
+             * Gets or sets the start angle in degrees (0 = top, clockwise). Only applies to FULL variant.
+             * @type {Number}
+             */
+            this.startAngle = 0;
+
+            /**
+             * Gets or sets the inner hole size for DONUT variant as a ratio (0-1, where 0.6 = 60% hole).
+             * @type {Number}
+             */
+            this.donutInnerRatio = 0.6;
+
+            /**
+             * Gets or sets the base HEX color used for segments without a specified color. The colors of such segments are generated by shifting the hue of the base color.
+             * @type {String}
+             */
+            this.baseColor = '#3b82f6';
+
+            /**
+             * Gets or sets the segment label positioning offset.
+             * For OUTER labels: distance in pixels from chart edge (default: 20).
+             * For INNER labels: position ratio from 0 (inner edge) to 1 (outer edge) (default: 0.5).
+             * @type {Number}
+             */
+            this.segmentLabelOffset = null;
+
+            /**
+             * Gets or sets the list of segments.
+             * @type {componyx.UI.PieChart.Segment[]}
+             */
+            this.segments = [];
+
+            /**
+             * Gets or sets the id of the component from which the settings are cloned for the tooltip manager used by the PieChart component.
+             * @type {string}
+             */
+            this.tooltipManagerId = null;
+
+            /**
+            * @class
+            * @augments componyx.UI.base.Events
+            * @memberof componyx.UI.PieChart
+            * @property {componyx.UI.base.Event} onSegmentEnter          - Fires when the pointer enters a segment. @see {@link componyx.UI.PieChart.PieChartEventArgs}
+            * @property {componyx.UI.base.Event} onSegmentLeave          - Fires when the pointer leaves a segment. @see {@link componyx.UI.PieChart.PieChartEventArgs}
+            * @property {componyx.UI.base.Event} onSegmentClick          - Fires when a segment is clicked. @see {@link componyx.UI.PieChart.PieChartEventArgs}
+            * @property {componyx.UI.base.Event} onRenderSegmentLabel    - Fires when a segment label is rendered. @see {@link componyx.UI.PieChart.PieChartLabelRenderEventArgs}
+            * @property {componyx.UI.base.Event} onRenderLegendLabel     - Fires when a legend label is rendered. @see {@link componyx.UI.PieChart.PieChartLabelRenderEventArgs}
+            * @see {@link componyx.UI.base.Events}
+            */
+            function PieChartEvents(events)
+            {
+                Object.assign(this, events);
+
+                this.onSegmentEnter = $base.static.createEvent('onSegmentEnter');
+                this.onSegmentLeave = $base.static.createEvent('onSegmentLeave');
+                this.onSegmentClick = $base.static.createEvent('onSegmentClick');
+                this.onRenderSegmentLabel = $base.static.createEvent('onRenderSegmentLabel');
+                this.onRenderLegendLabel = $base.static.createEvent('onRenderLegendLabel');
+            }
+            /**
+             * PieChart events
+             * @type {componyx.UI.PieChart.PieChartEvents}
+             */
+            this.events = new PieChartEvents(this.events);
+
+            /**
+            * @typedef {Object} componyx.UI.PieChart.PieChartEventArgs
+            * @property {componyx.UI.PieChart} PieChart - The PieChart instance.
+            * @property {Object} eventArgs - The event object containing more detailed information about the event.
+            * @property {componyx.UI.PieChart.Segment} eventArgs.segment - The data segment.
+            * @property {Event} eventArgs.event - The original event object.
+            */
+
+            /**
+             * @typedef {Object} componyx.UI.PieChart.PieChartLabelRenderEventArgs
+             * @property {componyx.UI.PieChart} PieChart - The PieChart instance.
+             * @property {componyx.UI.PieChart.Segment} segment - The data segment.
+             * @property {HTMLElement} element - The label DOM element (segment label or legend label) that can be customized.
+             */
+        }
+
+        /**
+        * Renders the component.
+        */
+        render()
+        {
+            if (this.renderState != $base.static.RenderState.RENDERING)
+            {
+                super.render(this.#preRender, 'pie-chart');
+                return;
+            }
+
+            // render logic after loading resources
+            this.#draw();
+            this.renderChildren();
+        }
+
+        /**
+         * Executes post render tasks.
+        * @private
+        */
+        async postRender()
+        {
+            if (this.renderState != $base.static.RenderState.RENDERING) // extra safety to never execute a postRender when the component state is incorrect
+                return;
+
+            super.postRender();
+            this.#positionSegmentLabels();
+        }
+
+        /**
+        * Destroys the component.
+        * @param {Boolean} keepEvents A value indicating if component events should be kept.
+        * @param {Boolean} removeElement=true A value indicating if the corresponding HTML Element should be removed.
+        * @see {@link componyx.UI.base.methods#destroy}
+        * @function
+        */
+        destroy(keepEvents, removeElement = true)
+        {
+            this.#dispose();
+            super.destroy(keepEvents, removeElement);
+        }
+
+        /**
+        * Gets the css class if it exists and otherwise the default css class.
+        * @returns {String} The css class.
+        */
+        getCssClass(cssClassValue)
+        {
+            return super.getCssClass(this.classOption, cssClassValue);
+        }
+
+        #preRender()
+        {
+            let script = [];
+
+            script.push('TooltipManager');
+            return ['PieChart', script];
+        }
+
+        #draw()
+        {
+            // Sum values for normalization
+            this.#totalValue = this.segments.reduce((sum, seg) => sum + seg.value, 0);
+
+            // For HALF variant, we'll start at 270° (bottom/6 o'clock) and go 180° clockwise to 90° (top/12 o'clock)
+            // This way the semicircle goes from left to right across the top
+            if (this.isHalf)
+            {
+                this.classList.add(this.getCssClass(this.classOption.HALF));
+                this.#startAngleDeg = 270; // Start at bottom
+                this.#totalAngleDeg = 180; // Half circle
+            }
+            else
+            {
+                this.#startAngleDeg = this.startAngle ?? 0;
+                this.#totalAngleDeg = 360; // Full circle
+            }
+
+            if (this.shape === PieChart.ShapeOption.DONUT)
+            {
+                this.classList.add(this.getCssClass(this.classOption.DONUT));
+                this.style.setProperty('--donut-inner-stop', `${this.donutInnerRatio * 100}%`);
+            }
+
+            this.#tooltipManager = this.#createTooltipManager(this, this.id + '_TooltipManager', this.tooltipManagerId);
+            this.#buildSegmentAngleRanges();
+            this.#generateSegmentColors();
+            this.#createChart();
+
+            if (this.showLegend)
+                this.#createLegend();
+
+            this.style.removeProperty('--chart-size');
+
+            if (this.isHalf)
+            {
+                this.style.setProperty('--chart-size', `${this.#size}px`); // used by the CSS to align the legend with the semicircle
+            }
+        }
+
+        #createTooltipManager(container, id, cloneId)
+        {
+            const tooltipBox = $UI.createComponent(componyx.UI.Box, {
+                id: id + '_TooltipManagerBox',
+                containerElement: container,
+                trackPointer: true,
+                alignX: componyx.UI.Box.AlignXOption.CENTER,
+                alignY: componyx.UI.Box.AlignYOption.BOTTOM,
+                expandDirection: componyx.UI.Box.ExpandDirectionOption.UP,
+                autoInvertFit: true,
+                animation: { showType: 0, hideType: 0 }
+            });
+
+            return this.#createComponent(container, componyx.UI.TooltipManager, id, cloneId, {
+                boxId: tooltipBox.id,
+                selectableTooltipContent: false,
+                arrowless: true
+            });
+        }
+
+        #createComponent(container, type, id, cloneId, config = {})
+        {
+            const component = $UI.createComponent(type, { id: id, containerElement: container });
+
+            component.clone($UI.store[cloneId], this);
+            Object.assign(component, Object.fromEntries(Object.entries(config).filter(([k, v]) => v !== undefined))); // don't assign undefined properties
+            component.showing = true;
+            component.events.onPostRender.priorityAdd(() => { this.isReady.apply(this); }, null, true);
+
+            return component;
+        }
+
+        /**
+         * Assign colors to segments if not already set.
+         * Colors are based on this.baseColor and evenly shifted in hue.
+         * @private
+         */
+        #generateSegmentColors()
+        {
+            const segments = this.#segmentAngleRanges.map(r => r.segment),
+                segmentCount = segments.length,
+                [baseR, baseG, baseB] = $lib.hexToRgb(this.baseColor),
+                [baseHue, baseSaturation, baseValue] = $lib.rgbToHsv(baseR, baseG, baseB),
+                hueStep = (this.isHalf ? 0.5 : 1) / segmentCount; // Calculate hue step per segment, 0.5 = half pie, 1 = full pie
+
+            segments.forEach((segment, index) =>
+            {
+                if (!segment.color)
+                {
+                    const newHue = (baseHue + index * hueStep) % 1, // Shift hue for this segment
+                        saturation = Math.max(baseSaturation, 0.6), // clamp saturation/value for nicer colors
+                        value = Math.max(baseValue, 0.75),
+                        [r, g, b] = $lib.hsvToRgb(newHue, saturation, value);
+
+                    segment.color = '#' + $lib.rgbToHex(r, g, b);
+                }
+            });
+        }
+
+        #createChart()
+        {
+            this.#chart = $lib.element({ container: this, attrs: { class: this.getCssClass(this.classOption.CHART) } });
+            this.#chart.style.background = this.#createConicGradient();
+
+            this.classList.remove('hidden');
+            this.#size = this.#chart.getBoundingClientRect().width;
+            this.classList.add('hidden');
+
+            if (this.segmentLabelDisplay !== PieChart.SegmentLabelDisplayOption.NONE)
+                this.#createSegmentLabels();
+
+            this.#segmentOverlay = $lib.element({ container: this.#chart, attrs: { class: this.getCssClass(this.classOption.SEGMENT_OVERLAY) } });
+            this.#bindEvents();
+            this.#observeResize();
+        }
+
+        #createSegmentLabels()
+        {
+            let currentAngleDeg = this.#startAngleDeg;
+            this.#segmentLabels = [];
+
+            this.segments.forEach(segment =>
+            {
+                const segmentAngleDeg = this.#getSegmentAngleDeg(segment.value),
+                    midAngleDeg = this.#getMidAngleDeg(currentAngleDeg, segmentAngleDeg),
+                    label = {
+                        element: $lib.element({ container: this, attrs: { class: this.getCssClass(this.classOption.SEGMENT_LABEL) } }),
+                        midAngleRad: this.#degToRad(this.#cssNormalize(midAngleDeg))
+                    },
+                    value = `${segment.value}${segment.valueSuffix || ''}`;
+
+                if (this.segmentLabelContent == PieChart.SegmentLabelContentOption.LABEL_VALUE)
+                    label.element.innerText = `${segment.label} (${value})`;
+                else if (this.segmentLabelContent == PieChart.SegmentLabelContentOption.LABEL)
+                    label.element.innerText = segment.label;
+                else // default to VALUE
+                    label.element.innerText = value;
+
+                this.#segmentLabels.push(label);
+                this.#positionSegmentLabel(label);
+                this.events.onRenderSegmentLabel.fire(this, { segment, element: label.element });
+
+                currentAngleDeg += segmentAngleDeg;
+            });
+        }
+
+        #positionSegmentLabels()
+        {
+            this.#segmentLabels.forEach(label => this.#positionSegmentLabel(label));
+        }
+
+        #positionSegmentLabel(label)
+        {
+            const outerChartRadius = this.#size / 2,
+                innerChartRadius = this.shape === PieChart.ShapeOption.DONUT ? outerChartRadius * this.donutInnerRatio : 0,
+                isInnerLabel = (this.segmentLabelDisplay === PieChart.SegmentLabelDisplayOption.INNER),
+                labelOffset = this.segmentLabelOffset ?? (isInnerLabel ? 0.5 : 20),
+                labelRadius = isInnerLabel
+                    ? innerChartRadius + (outerChartRadius - innerChartRadius) * labelOffset // ratio (0-1) of the ring width
+                    : outerChartRadius + labelOffset, // pixels from the outer edge
+                chartRect = this.#chart.getBoundingClientRect(), // rendered position of the chart, including any CSS transforms
+                hostRect = this.getBoundingClientRect(),
+                centerX = chartRect.left - hostRect.left + outerChartRadius,
+                centerY = chartRect.top - hostRect.top + outerChartRadius;
+
+            label.element.style.left = `${centerX + (labelRadius * Math.cos(label.midAngleRad))}px`;
+            label.element.style.top = `${centerY + (labelRadius * Math.sin(label.midAngleRad))}px`;
+        }
+
+        #observeResize()
+        {
+            this.#resizeObserver?.disconnect();
+            this.#resizeObserver = new ResizeObserver(() =>
+            {
+                const size = this.#chart?.getBoundingClientRect().width;
+
+                if (!size || size === this.#size) // hidden (0) or unchanged
+                    return;
+
+                this.#size = size;
+                this.#positionSegmentLabels();
+
+                if (this.isHalf)
+                {
+                    this.style.setProperty('--chart-size', `${size}px`);
+                }
+            });
+
+            this.#resizeObserver.observe(this.#chart);
+        }
+
+        #createLegend()
+        {
+            this.#legend = $lib.element({ container: this, attrs: { class: this.getCssClass(this.classOption.LEGEND) } });
+
+            this.segments.forEach(segment =>
+            {
+                const itemEl = $lib.element({ container: this.#legend, attrs: { class: this.getCssClass(this.classOption.LEGEND_ITEM) } }),
+                    colorEl = $lib.element({ tag: 'span', container: itemEl, attrs: { class: this.getCssClass(this.classOption.LEGEND_ITEM_COLOR) } }),
+                    labelEl = $lib.element({ tag: 'span', container: itemEl, attrs: { class: this.getCssClass(this.classOption.LEGEND_ITEM_LABEL) } });
+
+                colorEl.style.backgroundColor = segment.color;
+
+                if (this.showValuesInLegend)
+                    labelEl.innerText = `${segment.label} (${segment.value}${segment.valueSuffix})`;
+                else
+                    labelEl.innerText = segment.label;
+
+                this.events.onRenderLegendLabel.fire(this, { segment, element: labelEl });
+            });
+        }
+
+        #bindEvents()
+        {
+            $lib.on(this.#chart, 'pointermove pointerdown', (e) =>
+            {
+                clearTimeout(this.#leaveTimerId);
+                const segmentIndex = this.#getSegmentAtPointer(e);
+
+                if (segmentIndex !== this.#currentHoveredIndex)
+                {
+                    this.#currentHoveredIndex = segmentIndex;
+                    this.#hoverSegment(segmentIndex);
+
+                    if (segmentIndex !== null)
+                    {
+                        this.#chart.style.cursor = 'pointer';
+                        this.events.onSegmentEnter.fire(this, { segment: this.segments[segmentIndex], event: e });
+                    }
+                    else
+                    {
+                        this.#chart.style.cursor = 'default';
+                        this.events.onSegmentLeave.fire(this, { segment: null, event: e });
+                    }
+                }
+            });
+
+            $lib.on(this.#chart, 'click', (e) =>
+            {
+                const segmentIndex = this.#getSegmentAtPointer(e);
+                if (segmentIndex !== null)
+                {
+                    this.events.onSegmentClick.fire(this, { segment: this.segments[segmentIndex], event: e });
+                }
+            });
+
+            $lib.on(this.#chart, 'pointerleave', (e) =>
+            {
+                if (e.pointerType === 'touch') // a touch pointer "leaves" when the finger lifts, the tooltip stays until a tap elsewhere
+                    return;
+
+                this.#leaveTimerId = setTimeout(() => this.#clearHover(e));
+            });
+
+            // on touch, a tap outside the chart dismisses the hovered segment
+            this.#outsidePointerDown = (e) =>
+            {
+                if (e.pointerType === 'touch' && !this.#chart?.contains(e.target))
+                    this.#clearHover(e);
+            };
+
+            this.ownerDocument.addEventListener('pointerdown', this.#outsidePointerDown);
+        }
+
+        #clearHover(e)
+        {
+            if (this.#currentHoveredIndex !== null)
+            {
+                this.#currentHoveredIndex = null;
+                this.#hoverSegment(null);
+                this.#chart.style.cursor = 'default';
+                this.events.onSegmentLeave.fire(this, { segment: null, event: e });
+            }
+        }
+
+        #buildSegmentAngleRanges()
+        {
+            this.#segmentAngleRanges = [];
+            let currentAngleDeg = 0;
+
+            this.segments.forEach((segment, index) =>
+            {
+                const segmentAngleDeg = this.#getSegmentAngleDeg(segment.value);
+                const nextAngleDeg = currentAngleDeg + segmentAngleDeg;
+
+                this.#segmentAngleRanges.push({
+                    startAngle: currentAngleDeg,
+                    endAngle: nextAngleDeg,
+                    segment
+                });
+
+                currentAngleDeg = nextAngleDeg;
+            });
+        }
+
+        #createConicGradient()
+        {
+            let gradientParts = [];
+
+            this.#segmentAngleRanges.forEach((range) =>
+            {
+                const endColor = range.segment.endColor || range.segment.color;
+                gradientParts.push(`${range.segment.color} ${range.startAngle}deg, ${endColor} ${range.endAngle}deg`);
+            });
+
+            // For half-pie, fill the rest of the circle with transparent
+            if (this.isHalf)
+                gradientParts.push(`transparent ${this.#totalAngleDeg}deg 360deg`);
+
+            // Use 'from' to set where the gradient starts
+            return `conic-gradient(from ${this.#startAngleDeg}deg, ${gradientParts.join(', ')})`;
+        }
+
+        #hoverSegment(hoveredIndex)
+        {
+            this.#tooltipManager.removeTooltip(this.id);
+
+            if (hoveredIndex === null)
+            {
+                this.#segmentOverlay.style.background = 'transparent';
+                this.#segmentOverlay.classList.remove(this.getCssClass(this.classOption.SEGMENT_HOVER));
+                return;
+            }
+
+            const range = this.#segmentAngleRanges[hoveredIndex];
+
+            // Simple 3-stop gradient: transparent before, color on segment (the color is lightened with CSS), transparent after
+            this.#segmentOverlay.style.background = `conic-gradient(from ${this.#startAngleDeg}deg, transparent 0deg ${range.startAngle}deg, ${range.segment.color} ${range.startAngle}deg ${range.endAngle}deg, transparent ${range.endAngle}deg 360deg)`;
+            this.#segmentOverlay.classList.add(this.getCssClass(this.classOption.SEGMENT_HOVER));
+
+            if (range.segment.tooltip)
+            {
+                this.#tooltipManager.addTooltip(this.id, range.segment.tooltip);
+                this.#tooltipManager.addTrigger(this.#segmentOverlay, this.id);
+                this.#tooltipManager.showTooltip(this.#segmentOverlay, true);
+            }
+        }
+
+        #getSegmentAtPointer(event)
+        {
+            const rect = this.#chart.getBoundingClientRect(),
+                size = rect.width,
+                x = event.clientX - rect.left,
+                y = event.clientY - rect.top,
+                centerX = size / 2,
+                centerY = size / 2,
+                dx = x - centerX,
+                dy = y - centerY,
+                distance = Math.hypot(dx, dy), // calculates Euclidean distance (same as sqrt(dx*dx + dy*dy)) using Pythagorean theorem
+                outerRadius = size / 2,
+                innerRadius = this.shape === PieChart.ShapeOption.DONUT ? outerRadius * this.donutInnerRatio : 0;
+
+            if (distance < innerRadius || distance > outerRadius)
+            {
+                return null;
+            }
+
+            // Calculate angle from mouse position
+            let angleRad = Math.atan2(dy, dx);
+            let angleDeg = (angleRad * 180 / Math.PI);
+            if (angleDeg < 0) angleDeg += 360;
+
+            // Adjust for CSS coordinate system (0° = top, clockwise)
+            angleDeg = (angleDeg + 90) % 360;
+
+            // Adjust for startAngle to get relative angle
+            let relativeAngle = angleDeg - this.#startAngleDeg;
+            if (relativeAngle < 0) relativeAngle += 360;
+
+            // For HALF variant, check if in visible range
+            if (this.isHalf && relativeAngle > this.#totalAngleDeg)
+            {
+                return null;
+            }
+
+            // Binary search through cached angle ranges
+            let left = 0;
+            let right = this.#segmentAngleRanges.length - 1;
+
+            while (left <= right)
+            {
+                const mid = Math.floor((left + right) / 2);
+                const range = this.#segmentAngleRanges[mid];
+
+                if (relativeAngle >= range.startAngle && relativeAngle < range.endAngle)
+                {
+                    return mid;
+                }
+                else if (relativeAngle < range.startAngle)
+                {
+                    right = mid - 1; // Search left half
+                }
+                else
+                {
+                    left = mid + 1; // Search right half
+                }
+            }
+
+            return null;
+        }
+
+        /**
+         * Convert degrees to radians
+         * @private
+         */
+        #degToRad(degrees)
+        {
+            return (degrees / 180) * Math.PI;
+        }
+
+        /**
+         * Calculate the angle (in degrees) that a segment should occupy
+         * @private
+         */
+        #getSegmentAngleDeg(segmentValue)
+        {
+            return (segmentValue / this.#totalValue) * this.#totalAngleDeg;
+        }
+
+        /**
+         * Find the middle angle of a segment given its start angle and size
+         * @private
+         */
+        #getMidAngleDeg(startAngleDeg, segmentAngleDeg)
+        {
+            return startAngleDeg + segmentAngleDeg / 2;
+        }
+
+        /**
+         * Convert CSS conic-gradient angle (0° = top, clockwise) to standard math angle
+         * Math uses 0° = right, counterclockwise, so we need to adjust
+         * @private
+         */
+        #cssNormalize(cssAngleDeg)
+        {
+            return cssAngleDeg - 90;
+        }
+
+        #dispose()
+        {
+            // Clean up references
+            this.#resizeObserver?.disconnect();
+            this.#resizeObserver = null;
+            this.#chart = null;
+            this.#segmentOverlay = null;
+            this.#legend = null;
+            this.#segmentAngleRanges = [];
+            this.#segmentLabels = [];
+            this.#currentHoveredIndex = null;
+            this.#tooltipManager = null;
+            this.ownerDocument.removeEventListener('pointerdown', this.#outsidePointerDown);
+            this.#outsidePointerDown = null;
+        }
+    }
+
+
+
+    /**
+     * Represents a chart segment.
+     * @class
+     * @memberof componyx.UI.PieChart
+     */
+    class Segment
+    {
+        /**
+         * @param {Object} [properties] The properties used to initialize the object.
+         * @param {string} [properties.id] - Gets or sets the id of the segment.
+         * @param {string} [properties.label] - Gets or sets the label of the segment
+         * @param {string} [properties.tooltip] - Gets or sets the tooltip of the segment
+         * @param {any} [properties.color] - Gets or sets the CSS color value of the segment.
+         * @param {any} [properties.value] - Gets or sets the value of the segment.
+         * @param {any} [properties.valueSuffix] - Gets or sets the value suffix (e.g. %) of the segment.
+         */
+        constructor(properties)
+        {
+            /**
+             * Gets or sets the id of the segment.
+             * @type {String}
+             */
+            this.id = null;
+
+            /**
+             * Gets or sets the label of the segment
+             * @type {String}
+             */
+            this.label = null;
+
+            /**
+             * Gets or sets the tooltip of the segment
+             * @type {String}
+             */
+            this.tooltip = null;
+
+            /**
+             * Gets or sets the CSS color value of the segment.
+             * @type {String}
+             */
+            this.color = null;
+
+            /**
+             * Gets or sets the optional CSS end color value of the segment.
+             * @type {String}
+             */
+            this.endColor = null;
+
+            /**
+            * Gets or sets the value of the segment.
+            * @type {Number}
+            */
+            this.value = null;
+
+            /**
+            * Gets or sets the value suffix (e.g. %) of the segment.
+            * @type {Number}
+            */
+            this.valueSuffix = '';
+
+            _clone(this, properties);
+        }
+    }
+
+    PieChart.Segment = Segment;
+
+    /**
+    * ShapeOption
+    * @readonly
+    * @enum {string}
+    */
+    PieChart.ShapeOption =
+    {
+        PIE: 'pie',
+        DONUT: 'donut'
+    };
+
+    /**
+    * SegmentLabelDisplayOption
+    * @readonly
+    * @enum {string}
+    */
+    PieChart.SegmentLabelDisplayOption =
+    {
+        NONE: 'none',
+        INNER: 'inner',
+        OUTER: 'outer'
+    };
+
+    /**
+    * SegmentLabelContentOption
+    * @readonly
+    * @enum {string}
+    */
+    PieChart.SegmentLabelContentOption =
+    {
+        VALUE: 'value',
+        LABEL: 'label',
+        LABEL_VALUE: 'label_value'
+    };
+
+
+    // Preserve HTMLElement prototype and extend it with $base.methods
+    Object.assign(PieChart.prototype, Object.fromEntries(Object.entries($base.methods).filter(([key]) => !['render', 'postRender', 'destroy', 'getCssClass'].includes(key))));
+
+    // Restore the constructor reference
+    PieChart.prototype.constructor = PieChart;
+    componyx.UI.PieChart = PieChart;
+
+    // Define the custom element
+    customElements.define(`${componyx.UI.tagPrefix}${PieChart.name.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '')}`, PieChart); // cui-pie-chart
+})();
+
+const PieChart = componyx.UI.PieChart;
+
+export { PieChart };