Gauge Chart
gauge-chartuiReact mirror of @uipkge/gauge-chart — see the Vue registry item for the canonical description.
Installation
$pnpm dlx shadcn@latest add https://uipkge.dev/r/lit/gauge-chart.json$npx shadcn@latest add https://uipkge.dev/r/lit/gauge-chart.json$yarn dlx shadcn@latest add https://uipkge.dev/r/lit/gauge-chart.json$bunx shadcn@latest add https://uipkge.dev/r/lit/gauge-chart.jsonManifest:
https://uipkge.dev/r/lit/gauge-chart.jsonInstalls to:src/uip/components/charts/Examples
Loading interactive previews…
Loading interactive previews…
Props
| Name | Type / Values | Default | Required |
|---|---|---|---|
value | number | 0 | optional |
min | number | 0 | optional |
max | number | 100 | optional |
unit | string | — | optional |
label | string | — | optional |
thresholds | [number, string][] | — | optional |
option | any | — | optional |
Schema
Type aliases from this item's source — use them to shape the data you pass in.
HTMLElementTagNameMapinterface HTMLElementTagNameMap {
'uip-gauge-chart': UipGaugeChart
}
}ChartThemeinterface ChartTheme {
colors: string[]
textColor: string
axisColor: string
splitLineColor: string
tooltipBg: string
tooltipBorder: string
tooltipText: string
bgColor: string
accentColor: string
dangerColor: string
/** `--card`: cell borders and inside-label text, so they read as gaps /
* contrast on light and dark surfaces (never '#fff'). */
surfaceColor: string
/** `--foreground`: primary numbers drawn on the canvas (gauge value). */
foregroundColor: string
/** Gauge stoplight from the status tokens, same rule as <uip-usage-bar>:
* < 70% success, 70-89% warning, >= 90% destructive. */
semanticGaugeThresholds: [number, string][]
}Used by
Files installed (4)
src/uip/components/charts/gauge-chart.ts3.6 kB
import { ChartElement } from './lib/chart-element' /** * Static fallback stoplight: teal (safe) -> amber (warning) -> red (danger). * Verbatim from React's `gaugeThresholds` in useChartTheme. The element's * default is the theme's `semanticGaugeThresholds` (status tokens) instead. */ export const gaugeThresholds: [number, string][] = [ [0.6, '#14b8a6'], [0.85, '#f59e0b'], [1, '#dc2626'], ] /** * <uip-gauge-chart> — the registry GaugeChart (React `GaugeChart`) as a web * component. Builds the same ECharts option as React for the same props. * * Properties (React props): `value` (number), `min` (default 0), `max` * (default 100), `unit` (default ''), `label`, `height` (default 220), * `thresholds` ([fraction, color][]; property or JSON attribute; defaults to * the theme's success -> warning -> destructive tokens at 70% / 90%), `option` (ECharts escape hatch, merged like React), * `aria-label` (React `ariaLabel`). React's `className` → host classes. */ export class UipGaugeChart extends ChartElement { static properties = { value: { type: Number }, min: { type: Number }, max: { type: Number }, unit: {}, label: {}, thresholds: { type: Array }, option: { type: Object }, } value = 0 min = 0 max = 100 unit = '' label?: string thresholds?: [number, string][] option?: any protected readonly chartSlot = 'gauge-chart' constructor() { super() this.height = 220 } protected buildOption() { const theme = this.chartTheme const { value, min, max, unit, label, thresholds } = this const series = [ { type: 'gauge', min, max, center: ['50%', '60%'], radius: '85%', startAngle: 200, endAngle: -20, progress: { show: true, width: 14, itemStyle: { color: theme.colors[0] } }, pointer: { show: true, length: '55%', width: 4, itemStyle: { color: theme.colors[0] } }, axisLine: { lineStyle: { width: 14, color: (thresholds ?? theme.semanticGaugeThresholds).map(([stop, color]) => [stop, color] as [number, string]), }, }, axisTick: { distance: -22, length: 4, lineStyle: { color: theme.textColor, width: 1 } }, splitLine: { distance: -26, length: 8, lineStyle: { color: theme.textColor, width: 2 } }, axisLabel: { color: theme.textColor, fontSize: 11, distance: -34 }, anchor: { show: false }, title: { offsetCenter: [0, '88%'], color: theme.textColor, fontSize: 12, fontWeight: 500, }, detail: { valueAnimation: true, formatter: `{value}${unit ? ' ' + unit : ''}`, color: theme.foregroundColor, fontSize: 28, fontWeight: 600, offsetCenter: [0, '40%'], }, data: [{ value, name: label ?? '' }], }, ] const userOption: any = this.option ?? {} const { series: userSeries, ...userRest } = userOption const mergedSeries = Array.isArray(userSeries) ? series.map((s, i) => ({ ...s, ...(userSeries[i] ?? {}) })) : series return { tooltip: { formatter: '{b}: {c}' + (unit ? ` ${unit}` : ''), backgroundColor: theme.tooltipBg, borderColor: theme.tooltipBorder, textStyle: { color: theme.tooltipText, fontSize: 12 }, }, series: mergedSeries, ...userRest, } } } customElements.get('uip-gauge-chart') || customElements.define('uip-gauge-chart', UipGaugeChart) declare global { interface HTMLElementTagNameMap { 'uip-gauge-chart': UipGaugeChart } }src/uip/components/charts/lib/chart-element.ts4.9 kB
import { LitElement, css, html, type PropertyDeclarations, type PropertyValues } from 'lit' import { styleMap } from 'lit/directives/style-map.js' import type { ECharts } from 'echarts/core' import { tailwind } from '../../../lib/styles' import { ThemeController } from '../../../lib/theme' import { heightToStyle, resolveChartTheme, subscribeChartTheme, type ChartTheme } from './chart-theme' /** * Attribute converter for booleans whose React default is `true` * (`showLabels`, `autoresize`): Lit's `type: Boolean` can't be switched off * from markup, so `show-labels="false"` turns it off and anything else * (including removing the attribute) means true. */ export const defaultTrue = { fromAttribute: (v: string | null) => v !== 'false', toAttribute: (v: boolean) => (v ? '' : 'false'), } /** * `yField="value"` from markup, `yField=['north', 'south']` from markup as a * JSON array or from JS as a property. */ export const stringOrArray = { fromAttribute: (v: string | null) => (v?.trim().startsWith('[') ? (JSON.parse(v) as string[]) : v), } /** * Shared base for every ECharts-backed element — the Lit stand-in for React's * `ChartFrame` + `EChart` + `useChartTheme()`: * * - renders React's ChartFrame chrome (role="img", tabindex, focus ring, * `height`) with a full-size inner container for the canvas; * - resolves the chart theme from the CSS tokens and re-resolves it (and * re-sets the option) whenever <html> class/style/data-theme changes; * - lazily `import()`s echarts in firstUpdated (SSR-safe: nothing runs on the * server), resizes with a ResizeObserver and disposes on disconnect; * - applies `buildOption()` with `{ notMerge: true, lazyUpdate: true }`, * exactly like React's EChart. * * Subclasses implement `buildOption()` (React's `mergedOption` useMemo) and * set `chartSlot` (the host's data-slot). `instance` exposes the ECharts * instance (undefined until initialised) for getOption()/dispatchAction(). */ export abstract class ChartElement extends LitElement { // :host display can't be a utility class (the host has no template of its own). static styles = [tailwind, css`:host { display: block; }`] static properties: PropertyDeclarations = { height: {}, // role="img" lives on the inner frame, so the host's aria-label is forwarded. accessibleLabel: { attribute: 'aria-label' }, chartTheme: { state: true }, } height: number | string = 300 accessibleLabel?: string protected chartTheme: ChartTheme = resolveChartTheme() /** Resize with the container. Only RawChart exposes it as a property. */ protected autoresize = true protected abstract readonly chartSlot: string protected abstract buildOption(): any private chart?: ECharts private resizeObserver?: ResizeObserver private unsubscribeTheme?: () => void constructor() { super() new ThemeController(this) } /** The ECharts instance, once initialised in the browser. */ get instance(): ECharts | undefined { return this.chart } connectedCallback() { super.connectedCallback() this.setAttribute('data-uipkge', '') this.setAttribute('data-slot', this.chartSlot) this.chartTheme = resolveChartTheme() this.unsubscribeTheme = subscribeChartTheme(() => { this.chartTheme = resolveChartTheme() }) // Re-attached after a move: firstUpdated won't run again. if (this.hasUpdated) void this.initChart() } disconnectedCallback() { super.disconnectedCallback() this.unsubscribeTheme?.() this.resizeObserver?.disconnect() this.resizeObserver = undefined this.chart?.dispose() this.chart = undefined } protected firstUpdated() { void this.initChart() } protected updated(changed: PropertyValues) { if (!this.chart) return if (changed.has('autoresize')) this.observeResize() this.chart.setOption(this.buildOption(), { notMerge: true, lazyUpdate: true }) } private get container() { return this.renderRoot.querySelector<HTMLDivElement>('[data-chart]') } private async initChart() { const { echarts } = await import('./echarts') const el = this.container if (!this.isConnected || this.chart || !el) return this.chart = echarts.init(el) this.chart.setOption(this.buildOption(), { notMerge: true, lazyUpdate: true }) this.observeResize() } private observeResize() { this.resizeObserver?.disconnect() this.resizeObserver = undefined const el = this.container if (!this.autoresize || !el) return this.resizeObserver = new ResizeObserver(() => this.chart?.resize()) this.resizeObserver.observe(el) } render() { return html`<div part="base" role="img" aria-label=${this.accessibleLabel || 'Chart'} tabindex="0" style=${styleMap({ height: heightToStyle(this.height) })} class="focus-visible:ring-ring w-full focus-visible:ring-2 focus-visible:outline-none" > <div data-chart class="h-full w-full"></div> </div>` } }src/uip/components/charts/lib/chart-theme.ts7.1 kB
import { isServer } from 'lit' // Port of packages/registry-react/components/charts/useChartTheme.ts. // // The chart palette is driven by the design tokens (`--chart-1`..`--chart-5`, // `--muted-foreground`, `--border`, `--popover`, …). They are resolved with // getComputedStyle on <html> and re-resolved whenever <html> class / style / // data-theme changes, so a light/dark flip re-colours every chart. Instead of // React's useChartTheme() hook, elements call subscribeChartTheme(). const listeners = new Set<() => void>() let observing = false function bump() { listeners.forEach((l) => l()) } /** Call `cb` whenever the page theme changes. Returns the unsubscribe fn. */ export function subscribeChartTheme(cb: () => void): () => void { listeners.add(cb) if (!observing && !isServer) { observing = true // Same as React: one bump on the first frame (tokens resolved after the // stylesheet applies), then on every <html> class/style/data-theme change. requestAnimationFrame(bump) new MutationObserver(bump).observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'style', 'data-theme'], }) } return () => listeners.delete(cb) } // ECharts' canvas renderer does not accept OKLCH in every browser. Assigning // one of our Tailwind tokens to `fillStyle` can silently leave the sentinel // colour in place, turning a whole chart black. Convert OKLCH ourselves and // let the canvas normalize older CSS colour formats. let _hexCanvas: CanvasRenderingContext2D | null = null export function toCanvasColor(cssColor: string): string { const value = cssColor.trim() const match = value.match( /^oklch\(\s*([+-]?(?:\d+\.?\d*|\.\d+))(%?)\s+([+-]?(?:\d+\.?\d*|\.\d+))\s+([+-]?(?:\d+\.?\d*|\.\d+))(?:deg)?(?:\s*\/\s*([+-]?(?:\d+\.?\d*|\.\d+))(%?))?\s*\)$/i, ) if (match) { const lightness = Number(match[1]) / (match[2] === '%' ? 100 : 1) const chroma = Number(match[3]) const hue = (Number(match[4]) * Math.PI) / 180 const alpha = match[5] == null ? 1 : Number(match[5]) / (match[6] === '%' ? 100 : 1) const a = chroma * Math.cos(hue) const b = chroma * Math.sin(hue) const l = Math.pow(lightness + 0.3963377774 * a + 0.2158037573 * b, 3) const m = Math.pow(lightness - 0.1055613458 * a - 0.0638541728 * b, 3) const s = Math.pow(lightness - 0.0894841775 * a - 1.291485548 * b, 3) const linear = [ 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s, -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s, ] const rgb = linear.map((channel) => { const encoded = channel <= 0.0031308 ? 12.92 * channel : 1.055 * Math.pow(channel, 1 / 2.4) - 0.055 return Math.round(Math.min(1, Math.max(0, encoded)) * 255) }) return alpha < 1 ? `rgba(${rgb.join(', ')}, ${alpha})` : `rgb(${rgb.join(', ')})` } if (isServer) return cssColor if (!_hexCanvas) { _hexCanvas = document.createElement('canvas').getContext('2d') } if (!_hexCanvas) return cssColor _hexCanvas.fillStyle = '#010203' _hexCanvas.fillStyle = value const normalized = _hexCanvas.fillStyle as string return normalized === '#010203' && value.toLowerCase() !== '#010203' ? value : normalized } // Convert any CSS color (hex, rgb, oklch, color()) + alpha 0..1 to a // canvas-safe rgba(r,g,b,a). export function toRgba(cssColor: string, alpha: number): string { const normalized = toCanvasColor(cssColor) if (normalized.startsWith('#') && normalized.length === 7) { const r = parseInt(normalized.slice(1, 3), 16) const g = parseInt(normalized.slice(3, 5), 16) const b = parseInt(normalized.slice(5, 7), 16) return `rgba(${r},${g},${b},${alpha})` } if (normalized.startsWith('rgba(')) { return normalized.replace(/,\s*[\d.]+\s*\)$/, `,${alpha})`) } if (normalized.startsWith('rgb(')) { return normalized.replace(/^rgb\(/, 'rgba(').replace(/\)$/, `,${alpha})`) } return cssColor } export function resolveVar(name: string, fallback: string): string { if (isServer) return fallback const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim() if (!v) return fallback return toCanvasColor(v) } // SSR / pre-hydration fallback palette (same values as React). const CHART_FALLBACK = ['#f59e0b', '#14b8a6', '#3b82f6', '#f97316', '#eab308'] /** The resolved chart theme tokens. All values are canvas-safe hex/rgba. */ export interface ChartTheme { colors: string[] textColor: string axisColor: string splitLineColor: string tooltipBg: string tooltipBorder: string tooltipText: string bgColor: string accentColor: string dangerColor: string /** `--card`: cell borders and inside-label text, so they read as gaps / * contrast on light and dark surfaces (never '#fff'). */ surfaceColor: string /** `--foreground`: primary numbers drawn on the canvas (gauge value). */ foregroundColor: string /** Gauge stoplight from the status tokens, same rule as <uip-usage-bar>: * < 70% success, 70-89% warning, >= 90% destructive. */ semanticGaugeThresholds: [number, string][] } export function resolveChartTheme(): ChartTheme { return { colors: Array.from({ length: 5 }, (_, i) => resolveVar(`--chart-${i + 1}`, CHART_FALLBACK[i]!)), textColor: resolveVar('--muted-foreground', '#888888'), axisColor: resolveVar('--border', '#e5e5e5'), splitLineColor: resolveVar('--border', '#f0f0f0'), tooltipBg: resolveVar('--popover', 'rgba(255,255,255,0.96)'), tooltipBorder: resolveVar('--border', '#e5e5e5'), tooltipText: resolveVar('--popover-foreground', '#333333'), bgColor: resolveVar('--card', resolveVar('--background', '#ffffff')), accentColor: resolveVar('--primary', '#38bdf8'), dangerColor: resolveVar('--destructive', '#dc2626'), surfaceColor: resolveVar('--card', '#ffffff'), foregroundColor: resolveVar('--foreground', '#171717'), semanticGaugeThresholds: [ [0.7, resolveVar('--success', '#14b8a6')], [0.9, resolveVar('--warning', '#f59e0b')], [1, resolveVar('--destructive', '#dc2626')], ], } } // Two-level deep merge for ECharts option blocks (verbatim from React): top-level // keys merge shallowly, and one nested level (axisLabel, splitLine, …) merges // shallowly too. Arrays + primitives replace outright — including a whole // block given as an array (e.g. `xAxis: [a, b]` for two axes). export function mergeOptionBlock<T extends Record<string, any>>(base: T, user: Partial<T> | undefined): T { if (!user) return base if (Array.isArray(user)) return user as unknown as T const out: any = { ...base } for (const k of Object.keys(user)) { const bv = (base as any)[k] const uv = (user as any)[k] if ( bv != null && uv != null && typeof bv === 'object' && typeof uv === 'object' && !Array.isArray(bv) && !Array.isArray(uv) ) { out[k] = { ...bv, ...uv } } else { out[k] = uv } } return out } /** `height` prop → CSS: bare digits are px, anything else is raw CSS. */ export function heightToStyle(height: number | string): string { return /^\d+$/.test(String(height)) ? `${height}px` : String(height) }src/uip/components/charts/lib/echarts.ts1.9 kB
// ECharts core with every chart type / component the React wrappers register // (same list as packages/registry-react/components/charts/shared.tsx), so // <uip-raw-chart> can render any of them. Only ever loaded with a dynamic // import() from ChartElement.firstUpdated — never at module scope — so the // elements stay SSR-safe and echarts stays out of the initial bundle. // (Lives in charts/lib/ so src/index.ts's components/*/*.ts glob skips it.) import * as echarts from 'echarts/core' import { CanvasRenderer } from 'echarts/renderers' import { LineChart, BarChart, PieChart, ScatterChart, EffectScatterChart, PictorialBarChart, RadarChart, GaugeChart, HeatmapChart, TreemapChart, FunnelChart, BoxplotChart, CandlestickChart, CustomChart, ChordChart, MapChart, GraphChart, ParallelChart, SankeyChart, SunburstChart, ThemeRiverChart, TreeChart, } from 'echarts/charts' import { GridComponent, PolarComponent, TooltipComponent, LegendComponent, MarkLineComponent, MarkAreaComponent, MarkPointComponent, GraphicComponent, RadarComponent, VisualMapComponent, CalendarComponent, DataZoomComponent, ParallelComponent, SingleAxisComponent, TitleComponent, } from 'echarts/components' echarts.use([ CanvasRenderer, LineChart, BarChart, PieChart, ScatterChart, EffectScatterChart, PictorialBarChart, RadarChart, GaugeChart, HeatmapChart, TreemapChart, FunnelChart, BoxplotChart, CandlestickChart, CustomChart, ChordChart, MapChart, GraphChart, ParallelChart, SankeyChart, SunburstChart, ThemeRiverChart, TreeChart, GridComponent, PolarComponent, TooltipComponent, LegendComponent, MarkLineComponent, MarkAreaComponent, MarkPointComponent, GraphicComponent, RadarComponent, VisualMapComponent, CalendarComponent, DataZoomComponent, ParallelComponent, SingleAxisComponent, TitleComponent, ]) export { echarts }
Raw manifest:https://uipkge.dev/r/lit/gauge-chart.json