@purestack/ts-components 1.1.0

package/src/standard/doughnutChart/doughnutChart.ts

@@ -0,0 +1,527 @@
+import type { SemanticTone } from '@purestack/ts-style'
+import {
+  type ComputedRef,
+  computed,
+  defineComponent,
+  type RefOrValue,
+  svg,
+  unref,
+} from 'regor'
+import { createAutoId } from '../autoId'
+import {
+  DEFAULT_CHART_COLORS,
+  DEFAULT_CHART_EMPTY_LABEL,
+  DEFAULT_CHART_SIZE,
+} from '../chart/chartDefaults'
+import {
+  clampChartNumber,
+  formatChartNumber,
+  formatChartPoint,
+  formatChartValue,
+  readChartNumber,
+  resolveChartCssSize,
+  resolveChartSize,
+  resolveChartText,
+} from '../chart/chartUtils'
+import type {
+  ComponentVariant,
+  ComponentVariantMode,
+} from '../componentVariant'
+import { resolveComponentClasses } from '../componentVariant'
+
+export interface DoughnutChartSegment {
+  label?: RefOrValue<string>
+  value?: RefOrValue<number | string>
+  color?: RefOrValue<string>
+}
+
+export interface ResolvedDoughnutChartSegment {
+  label: string
+  value: number
+  percent: number
+  formattedValue: string
+  path: string
+  color: string
+}
+
+export interface ResolvedDoughnutChartSeparator {
+  path: string
+}
+
+export interface DoughnutChart {
+  segments?: RefOrValue<Array<RefOrValue<DoughnutChartSegment>>>
+  title?: RefOrValue<string>
+  description?: RefOrValue<string>
+  ariaLabel?: RefOrValue<string>
+  centerLabel?: RefOrValue<string>
+  centerValue?: RefOrValue<string>
+  centerLabelSize?: RefOrValue<number | string>
+  centerValueSize?: RefOrValue<number | string>
+  emptyLabel?: RefOrValue<string>
+  valueSuffix?: RefOrValue<string>
+  size?: RefOrValue<number | string>
+  thickness?: RefOrValue<number | string>
+  gap?: RefOrValue<number | string>
+  startAngle?: RefOrValue<number | string>
+  animated?: RefOrValue<boolean | string>
+  tone?: RefOrValue<SemanticTone>
+  variant?: RefOrValue<ComponentVariant>
+  variantMode?: RefOrValue<ComponentVariantMode>
+  classes?: ComputedRef<string>
+  resolvedSize?: ComputedRef<string | number>
+  resolvedAriaLabel?: ComputedRef<string>
+  resolvedEmptyLabel?: ComputedRef<string>
+  chartSegments?: ComputedRef<ResolvedDoughnutChartSegment[]>
+  separators?: ComputedRef<ResolvedDoughnutChartSeparator[]>
+  hasSeparators?: ComputedRef<boolean>
+  separatorMaskId?: string
+  separatorMaskUrl?: ComputedRef<string | undefined>
+  hasSegments?: ComputedRef<boolean>
+  total?: ComputedRef<number>
+  centerValueText?: ComputedRef<string>
+  centerLabelStyle?: ComputedRef<Record<string, string> | undefined>
+  centerValueStyle?: ComputedRef<Record<string, string> | undefined>
+  trackPath?: ComputedRef<string>
+}
+
+const CHART_CENTER = 50
+const CHART_OUTER_RADIUS = 46
+const DEFAULT_CHART_THICKNESS = 14
+const DEFAULT_CHART_GAP = 2
+const DEFAULT_CHART_START_ANGLE = -90
+const FULL_CIRCLE = 360
+const MAX_SEPARATOR_SEGMENT_SHARE = 0.15
+const MIN_SEPARATOR_WIDTH = 0.25
+const SEPARATOR_MASK_BLEED = 0.35
+const resolveDoughnutChartMaskId = createAutoId('doughnut-chart-mask')
+
+const doughnutChartTemplate = svg`<svg
+  class="doughnut-chart"
+  :class="classes"
+  viewBox="0 0 100 100"
+  :width="resolvedSize"
+  :height="resolvedSize"
+  role="img"
+  :aria-label="resolvedAriaLabel"
+>
+  <title r-if="title">{{ title }}</title>
+  <desc r-if="description">{{ description }}</desc>
+  <defs r-if="hasSeparators">
+    <mask
+      class="doughnut-chart__separator-mask"
+      :id="separatorMaskId"
+      maskUnits="userSpaceOnUse"
+      x="0"
+      y="0"
+      width="100"
+      height="100"
+    >
+      <rect x="0" y="0" width="100" height="100" fill="white"/>
+      <path
+        r-for="separator in separators"
+        class="doughnut-chart__separator"
+        :d="separator.path"
+        fill="black"/>
+    </mask>
+  </defs>
+  <g class="doughnut-chart__plot" :mask="separatorMaskUrl">
+    <animate
+      r-if="animated"
+      attributeName="opacity"
+      from="0"
+      to="1"
+      dur="560ms"
+      fill="freeze"/>
+    <animateTransform
+      r-if="animated"
+      attributeName="transform"
+      type="rotate"
+      from="-90 50 50"
+      to="0 50 50"
+      dur="1760ms"
+      calcMode="spline"
+      keyTimes="0;1"
+      keySplines="0.16 1 0.3 1"
+      fill="freeze"/>
+    <path class="doughnut-chart__track" :d="trackPath" fill-rule="evenodd"/>
+    <g class="doughnut-chart__segments" r-if="hasSegments">
+      <path
+        r-for="segment in chartSegments"
+        class="doughnut-chart__segment"
+        :d="segment.path"
+        :fill="segment.color"
+        :aria-label="segment.label + ': ' + segment.formattedValue"
+        fill-rule="evenodd"
+      >
+        <title>{{ segment.label + ': ' + segment.formattedValue }}</title>
+      </path>
+    </g>
+  </g>
+  <g class="doughnut-chart__center" r-if="centerValueText || centerLabel">
+    <animate
+      r-if="animated"
+      attributeName="opacity"
+      from="0"
+      to="1"
+      dur="360ms"
+      fill="freeze"/>
+    <text
+      class="doughnut-chart__center-value"
+      x="50"
+      :y="centerLabel ? 48 : 52"
+      text-anchor="middle"
+      :style="centerValueStyle"
+    >
+      {{ centerValueText }}
+    </text>
+    <text
+      r-if="centerLabel"
+      class="doughnut-chart__center-label"
+      x="50"
+      y="61"
+      text-anchor="middle"
+      :style="centerLabelStyle"
+    >
+      {{ centerLabel }}
+    </text>
+  </g>
+  <text
+    r-if="!hasSegments && !centerValueText && !centerLabel"
+    class="doughnut-chart__empty"
+    x="50"
+    y="52"
+    text-anchor="middle"
+  >
+    {{ resolvedEmptyLabel }}
+  </text>
+</svg>`
+
+function defineDoughnutChartComponent() {
+  return defineComponent<DoughnutChart>(doughnutChartTemplate, {
+    props: [
+      'segments',
+      'title',
+      'description',
+      'ariaLabel',
+      'centerLabel',
+      'centerValue',
+      'centerLabelSize',
+      'centerValueSize',
+      'emptyLabel',
+      'valueSuffix',
+      'size',
+      'thickness',
+      'gap',
+      'startAngle',
+      'animated',
+      'tone',
+      'variant',
+      'variantMode',
+    ],
+    context: (head) => resolveDoughnutChart(head.props),
+  })
+}
+
+export function defineDoughnutChartComponents() {
+  return {
+    doughnutChart: defineDoughnutChartComponent(),
+  }
+}
+
+function resolveDoughnutChart(props: DoughnutChart): DoughnutChart {
+  const separatorMaskId = resolveDoughnutChartMaskId()
+  const thickness = computed(() =>
+    clampChartNumber(props.thickness, DEFAULT_CHART_THICKNESS, 2, 40),
+  )
+  const innerRadius = computed(() => CHART_OUTER_RADIUS - thickness())
+  const total = computed(() => resolveTotal(props.segments))
+  const chartSegments = computed(() =>
+    resolveChartSegments(props, total(), innerRadius()),
+  )
+  const separators = computed(() =>
+    resolveSeparators(props, chartSegments(), innerRadius()),
+  )
+
+  return {
+    animated: true,
+    ...props,
+    classes: computed(() =>
+      resolveComponentClasses(props, {
+        defaultVariant: 'none',
+        defaultVariantMode: 'stateless',
+      }),
+    ),
+    resolvedSize: computed(() =>
+      resolveChartSize(props.size, DEFAULT_CHART_SIZE),
+    ),
+    resolvedAriaLabel: computed(() => resolveAriaLabel(props)),
+    resolvedEmptyLabel: computed(
+      () => resolveChartText(props.emptyLabel) || DEFAULT_CHART_EMPTY_LABEL,
+    ),
+    total,
+    chartSegments,
+    separators,
+    hasSeparators: computed(() => separators().length > 0),
+    separatorMaskId,
+    separatorMaskUrl: computed(() =>
+      separators().length > 0 ? `url(#${separatorMaskId})` : undefined,
+    ),
+    hasSegments: computed(() => chartSegments().length > 0),
+    centerValueText: computed(() => resolveCenterValue(props, total())),
+    centerLabelStyle: computed<Record<string, string> | undefined>(() =>
+      resolveFontSizeStyle(props.centerLabelSize),
+    ),
+    centerValueStyle: computed<Record<string, string> | undefined>(() =>
+      resolveFontSizeStyle(props.centerValueSize),
+    ),
+    trackPath: computed(() => fullRingPath(CHART_OUTER_RADIUS, innerRadius())),
+  }
+}
+
+function resolveChartSegments(
+  props: DoughnutChart,
+  total: number,
+  innerRadius: number,
+): ResolvedDoughnutChartSegment[] {
+  if (total <= 0) return []
+
+  const startAngle = readChartNumber(
+    props.startAngle,
+    DEFAULT_CHART_START_ANGLE,
+  )
+  const valueSuffix = resolveChartText(props.valueSuffix)
+  let cursor = startAngle
+
+  return resolvePositiveSegments(props.segments).map((segment, index) => {
+    const span = (segment.value / total) * FULL_CIRCLE
+    const segmentStart = cursor
+    const segmentEnd = cursor + span
+    cursor += span
+
+    return {
+      ...segment,
+      percent: segment.value / total,
+      formattedValue: formatSegmentValue(segment.value, valueSuffix),
+      color:
+        segment.color ||
+        DEFAULT_CHART_COLORS[index % DEFAULT_CHART_COLORS.length],
+      path:
+        segmentEnd - segmentStart >= FULL_CIRCLE - 0.001
+          ? fullRingPath(CHART_OUTER_RADIUS, innerRadius)
+          : ringSegmentPath(
+              CHART_OUTER_RADIUS,
+              innerRadius,
+              segmentStart,
+              segmentEnd,
+            ),
+    }
+  })
+}
+
+function resolveSeparators(
+  props: DoughnutChart,
+  segments: ResolvedDoughnutChartSegment[],
+  innerRadius: number,
+): ResolvedDoughnutChartSeparator[] {
+  if (segments.length < 2) return []
+
+  const gap = clampChartNumber(props.gap, DEFAULT_CHART_GAP, 0, 24)
+  if (gap <= 0) return []
+
+  let cursor = readChartNumber(props.startAngle, DEFAULT_CHART_START_ANGLE)
+  return segments.flatMap((segment, index) => {
+    const previousSegment = segments.at(index - 1) || segment
+    const width = resolveAdaptiveSeparatorWidth(
+      gap,
+      innerRadius,
+      CHART_OUTER_RADIUS,
+      previousSegment,
+      segment,
+    )
+    if (width < MIN_SEPARATOR_WIDTH) {
+      cursor += segment.percent * FULL_CIRCLE
+      return []
+    }
+
+    const path = separatorPath(
+      cursor,
+      Math.max(0, innerRadius - SEPARATOR_MASK_BLEED),
+      CHART_OUTER_RADIUS + SEPARATOR_MASK_BLEED,
+      width,
+    )
+    cursor += segment.percent * FULL_CIRCLE
+    return [{ path }]
+  })
+}
+
+function resolveAdaptiveSeparatorWidth(
+  maxWidth: number,
+  innerRadius: number,
+  outerRadius: number,
+  previousSegment: ResolvedDoughnutChartSegment,
+  nextSegment: ResolvedDoughnutChartSegment,
+) {
+  const smallerSegmentSpan =
+    Math.min(previousSegment.percent, nextSegment.percent) * FULL_CIRCLE
+  const maxSeparatorAngle = smallerSegmentSpan * MAX_SEPARATOR_SEGMENT_SHARE
+  const midRadius = (innerRadius + outerRadius) / 2
+  const adaptiveWidth = chordWidth(midRadius, maxSeparatorAngle)
+  return Math.min(maxWidth, adaptiveWidth)
+}
+
+function chordWidth(radius: number, angle: number) {
+  if (radius <= 0 || angle <= 0) return 0
+  const radians = (angle * Math.PI) / 180
+  return 2 * radius * Math.sin(radians / 2)
+}
+
+function separatorPath(
+  angle: number,
+  innerRadius: number,
+  outerRadius: number,
+  width: number,
+) {
+  const halfWidth = Math.min(
+    width / 2,
+    innerRadius - 0.001,
+    outerRadius - 0.001,
+  )
+  if (halfWidth <= 0) return ''
+
+  const radians = (angle * Math.PI) / 180
+  const ux = Math.cos(radians)
+  const uy = Math.sin(radians)
+  const px = -uy
+  const py = ux
+  const outerDistance = Math.sqrt(outerRadius ** 2 - halfWidth ** 2)
+  const innerDistance = Math.sqrt(innerRadius ** 2 - halfWidth ** 2)
+  const outerStart = offsetPoint(ux, uy, px, py, outerDistance, halfWidth)
+  const outerEnd = offsetPoint(ux, uy, px, py, outerDistance, -halfWidth)
+  const innerEnd = offsetPoint(ux, uy, px, py, innerDistance, -halfWidth)
+  const innerStart = offsetPoint(ux, uy, px, py, innerDistance, halfWidth)
+
+  return [
+    `M ${formatPoint(outerStart)}`,
+    `A ${fmt(outerRadius)} ${fmt(outerRadius)} 0 0 0 ${formatPoint(outerEnd)}`,
+    `L ${formatPoint(innerEnd)}`,
+    `A ${fmt(innerRadius)} ${fmt(innerRadius)} 0 0 1 ${formatPoint(innerStart)}`,
+    'Z',
+  ].join(' ')
+}
+
+function offsetPoint(
+  ux: number,
+  uy: number,
+  px: number,
+  py: number,
+  radialDistance: number,
+  offset: number,
+) {
+  return {
+    x: CHART_CENTER + ux * radialDistance + px * offset,
+    y: CHART_CENTER + uy * radialDistance + py * offset,
+  }
+}
+
+function resolvePositiveSegments(
+  segments: DoughnutChart['segments'],
+): Array<
+  Omit<ResolvedDoughnutChartSegment, 'percent' | 'formattedValue' | 'path'>
+> {
+  return (unref(segments) || [])
+    .map((segmentInput, index) => {
+      const segment = unref(segmentInput)
+      const value = readChartNumber(segment?.value, 0)
+      return {
+        label: resolveChartText(segment?.label) || `Segment ${index + 1}`,
+        value: value > 0 ? value : 0,
+        color: resolveChartText(segment?.color),
+      }
+    })
+    .filter((segment) => segment.value > 0)
+}
+
+function resolveTotal(segments: DoughnutChart['segments']) {
+  return resolvePositiveSegments(segments).reduce(
+    (total, segment) => total + segment.value,
+    0,
+  )
+}
+
+function resolveCenterValue(props: DoughnutChart, total: number) {
+  const explicit = resolveChartText(props.centerValue)
+  if (explicit) return explicit
+  if (total <= 0) return ''
+  return formatSegmentValue(total, resolveChartText(props.valueSuffix))
+}
+
+function resolveAriaLabel(props: DoughnutChart) {
+  return (
+    resolveChartText(props.ariaLabel) ||
+    resolveChartText(props.title) ||
+    'Doughnut chart'
+  )
+}
+
+function resolveFontSizeStyle(size?: RefOrValue<number | string>) {
+  const fontSize = resolveChartCssSize(size)
+  return fontSize ? { fontSize } : undefined
+}
+
+function fullRingPath(outerRadius: number, innerRadius: number) {
+  const topOuter = pointAtAngle(outerRadius, -90)
+  const bottomOuter = pointAtAngle(outerRadius, 90)
+  const topInner = pointAtAngle(innerRadius, -90)
+  const bottomInner = pointAtAngle(innerRadius, 90)
+
+  return [
+    `M ${formatPoint(topOuter)}`,
+    `A ${fmt(outerRadius)} ${fmt(outerRadius)} 0 1 1 ${formatPoint(bottomOuter)}`,
+    `A ${fmt(outerRadius)} ${fmt(outerRadius)} 0 1 1 ${formatPoint(topOuter)}`,
+    `M ${formatPoint(topInner)}`,
+    `A ${fmt(innerRadius)} ${fmt(innerRadius)} 0 1 0 ${formatPoint(bottomInner)}`,
+    `A ${fmt(innerRadius)} ${fmt(innerRadius)} 0 1 0 ${formatPoint(topInner)}`,
+    'Z',
+  ].join(' ')
+}
+
+function ringSegmentPath(
+  outerRadius: number,
+  innerRadius: number,
+  startAngle: number,
+  endAngle: number,
+) {
+  const outerStart = pointAtAngle(outerRadius, startAngle)
+  const outerEnd = pointAtAngle(outerRadius, endAngle)
+  const innerEnd = pointAtAngle(innerRadius, endAngle)
+  const innerStart = pointAtAngle(innerRadius, startAngle)
+  const largeArc = endAngle - startAngle > 180 ? 1 : 0
+
+  return [
+    `M ${formatPoint(outerStart)}`,
+    `A ${fmt(outerRadius)} ${fmt(outerRadius)} 0 ${largeArc} 1 ${formatPoint(outerEnd)}`,
+    `L ${formatPoint(innerEnd)}`,
+    `A ${fmt(innerRadius)} ${fmt(innerRadius)} 0 ${largeArc} 0 ${formatPoint(innerStart)}`,
+    'Z',
+  ].join(' ')
+}
+
+function pointAtAngle(radius: number, angle: number) {
+  const radians = (angle * Math.PI) / 180
+  return {
+    x: CHART_CENTER + radius * Math.cos(radians),
+    y: CHART_CENTER + radius * Math.sin(radians),
+  }
+}
+
+function formatPoint(point: { x: number; y: number }) {
+  return formatChartPoint(point, { precision: 3 })
+}
+
+function formatSegmentValue(value: number, suffix: string) {
+  return formatChartValue(value, suffix, { precision: 3 })
+}
+
+function fmt(value: number) {
+  return formatChartNumber(value, { precision: 3 })
+}

package/src/standard/doughnutChart/doughnutChartStyle.ts

@@ -0,0 +1,64 @@
+import {
+  styleBuilder,
+  type ThemeMode,
+  type ThemePalette,
+  themes,
+} from '@purestack/ts-style'
+
+export function registerDoughnutChartStyles() {
+  themes.forEach((theme, palette) => {
+    registerDoughnutChartBaseStyles(theme)
+    registerDoughnutChartPaintStyles(theme, palette)
+  })
+}
+
+function registerDoughnutChartBaseStyles(theme: ThemeMode) {
+  styleBuilder
+    .select('.doughnut-chart__segment', theme)
+    .transition('opacity 180ms ease, filter 180ms ease, transform 180ms ease')
+    .transformOrigin('50px 50px')
+
+  styleBuilder
+    .select('.doughnut-chart__segments:hover .doughnut-chart__segment', theme)
+    .opacity('0.72')
+
+  styleBuilder
+    .select(
+      '.doughnut-chart__segments:hover .doughnut-chart__segment:hover',
+      theme,
+    )
+    .opacity('1')
+    .filter('brightness(1.08)')
+
+  styleBuilder
+    .select('.doughnut-chart__center, .doughnut-chart__empty', theme)
+    .pointerEvents('none')
+}
+
+function registerDoughnutChartPaintStyles(
+  theme: ThemeMode,
+  palette: ThemePalette,
+) {
+  styleBuilder
+    .select('.doughnut-chart__track', theme)
+    .fill(palette.current.surfaceAlt.rest.bgcolor)
+
+  styleBuilder
+    .select('.doughnut-chart__center-value', theme)
+    .fill(palette.current.text.default)
+    .apply(palette.applyFont(palette.font.size.body, palette.font.weight.w700))
+    .set('dominant-baseline', 'middle')
+
+  styleBuilder
+    .select('.doughnut-chart__center-label', theme)
+    .fill(palette.current.text.subtle)
+    .apply(palette.applyFont(palette.font.size.xxxs, palette.font.weight.w700))
+    .textTransform('uppercase')
+    .set('dominant-baseline', 'middle')
+
+  styleBuilder
+    .select('.doughnut-chart__empty', theme)
+    .fill(palette.current.text.subtle)
+    .apply(palette.applyFont(palette.font.size.xxs, palette.font.weight.w700))
+    .set('dominant-baseline', 'middle')
+}