banhaten 0.4.0 → 0.5.0

package/registry/components/echart-theme.ts

@@ -0,0 +1,246 @@
+import type { EChartsOption } from "echarts"
+
+export type EChartTheme = {
+  palette: string[]
+  foreground: string
+  muted: string
+  border: string
+  surface: string
+  subtle: string
+  neutral: string
+  fontFamily: string
+  fontSize: number
+  fontWeight: number
+  lineHeight: number
+  letterSpacing: number
+  labelFontSize: number
+  mediumWeight: number
+  headingFontSize: number
+  headingLineHeight: number
+  headingWeight: number
+  space: { xs: number; sm: number; md: number; lg: number; xl: number; xxl: number; axis: number }
+  radius: number
+  markRadius: number
+  radii?: { sm: number; md: number; lg: number; xl: number }
+  translucentOpacity?: number
+  borderWidth: number
+  lineWidth: number
+  opacity: { area: number; muted: number; soft: number }
+  duration: number
+  reducedMotion: boolean
+  rtl: boolean
+}
+
+const paletteTokens = [
+  "--bh-chart-categorical-brand",
+  "--bh-chart-categorical-success",
+  "--bh-chart-categorical-warning",
+  "--bh-chart-categorical-danger",
+  "--bh-chart-categorical-information",
+  "--bh-chart-categorical-purple",
+  "--bh-chart-categorical-aqua",
+  "--bh-chart-categorical-fuchsia",
+] as const
+
+/** Canvas-style APIs need resolved values, read from this chart's inherited theme. */
+export function readEChartTheme(element: HTMLElement, reducedMotion: boolean): EChartTheme {
+  const styles = getComputedStyle(element)
+  const read = (token: string) => {
+    const value = styles.getPropertyValue(token).trim()
+    if (!value) throw new Error(`EChart requires the Banhaten token ${token}.`)
+    return value
+  }
+  const number = (token: string) => {
+    const value = Number.parseFloat(read(token))
+    if (!Number.isFinite(value)) throw new Error(`EChart requires a numeric Banhaten token ${token}.`)
+    return value
+  }
+  const duration = read("--bh-duration-default")
+
+  return {
+    palette: paletteTokens.map(read),
+    foreground: read("--bh-content-default"),
+    muted: read("--bh-content-muted"),
+    border: read("--bh-border-subtle"),
+    surface: read("--bh-bg-raised"),
+    subtle: read("--bh-bg-neutral-subtle"),
+    neutral: read("--bh-chart-neutral-default"),
+    fontFamily: read("--bh-font-family"),
+    fontSize: number("--bh-text-body-xs-regular-font-size"),
+    fontWeight: number("--bh-text-body-xs-regular-font-weight"),
+    lineHeight: number("--bh-text-body-xs-regular-line-height"),
+    letterSpacing: number("--bh-text-body-xs-regular-letter-spacing"),
+    labelFontSize: number("--bh-text-body-3xs-regular-font-size"),
+    mediumWeight: number("--bh-text-body-xs-medium-font-weight"),
+    headingFontSize: number("--bh-text-heading-md-semibold-font-size"),
+    headingLineHeight: number("--bh-text-heading-md-semibold-line-height"),
+    headingWeight: number("--bh-text-heading-md-semibold-font-weight"),
+    space: {
+      xs: number("--bh-space-xs-4"),
+      sm: number("--bh-space-sm-6"),
+      md: number("--bh-space-md-8"),
+      lg: number("--bh-space-xl-12"),
+      xl: number("--bh-space-3xl-16"),
+      xxl: number("--bh-space-5xl-24"),
+      axis: number("--bh-space-7xl-40"),
+    },
+    radius: number("--bh-radius-lg-8"),
+    markRadius: number("--bh-radius-sm-4"),
+    radii: {
+      sm: number("--bh-radius-sm-4"),
+      md: number("--bh-radius-md-6"),
+      lg: number("--bh-radius-lg-8"),
+      xl: number("--bh-radius-xl-10"),
+    },
+    translucentOpacity: number("--bh-opacity-90"),
+    borderWidth: number("--bh-border-width-default"),
+    lineWidth: number("--bh-icon-stroke-200"),
+    opacity: {
+      area: number("--bh-opacity-15"),
+      muted: number("--bh-opacity-muted"),
+      soft: number("--bh-opacity-30"),
+    },
+    duration: Number.parseFloat(duration) * (duration.endsWith("ms") ? 1 : 1000),
+    reducedMotion,
+    rtl: styles.direction === "rtl",
+  }
+}
+
+/** Shared defaults also cover native ECharts labels that a block does not specify. */
+export function createEChartTheme(theme: EChartTheme) {
+  const textStyle = {
+    color: theme.foreground,
+    fontFamily: theme.fontFamily,
+    fontSize: theme.fontSize,
+    fontWeight: theme.fontWeight,
+    lineHeight: theme.lineHeight,
+    textShadowBlur: 0,
+    textShadowOffsetX: 0,
+    textShadowOffsetY: 0,
+  }
+  const axis = {
+    axisLine: { lineStyle: { color: theme.border, width: theme.borderWidth } },
+    axisTick: { show: false, lineStyle: { color: theme.border, width: theme.borderWidth } },
+    axisLabel: { ...textStyle, color: theme.muted, fontSize: theme.labelFontSize, margin: theme.space.md },
+    nameTextStyle: { ...textStyle, color: theme.muted },
+    splitLine: { lineStyle: { color: theme.border, width: theme.borderWidth } },
+    splitArea: { areaStyle: { color: [theme.surface, theme.subtle] } },
+  }
+  const label = { ...textStyle, fontSize: theme.labelFontSize }
+  const shadowless = { shadowBlur: 0, shadowOffsetX: 0, shadowOffsetY: 0 }
+  const seriesStates = {
+    emphasis: { label, itemStyle: { color: "inherit", ...shadowless } },
+    select: { label, itemStyle: { color: "inherit", borderColor: theme.border, borderWidth: theme.borderWidth, ...shadowless } },
+    blur: { label: { ...label, opacity: theme.opacity.muted }, itemStyle: { opacity: theme.opacity.muted, ...shadowless } },
+  }
+  const axisPointer = {
+    lineStyle: { color: theme.muted, width: theme.borderWidth },
+    shadowStyle: { color: theme.subtle, shadowBlur: 0 },
+    label: { ...textStyle, backgroundColor: theme.surface, borderColor: theme.border, borderWidth: theme.borderWidth, padding: theme.space.sm },
+  }
+
+  return {
+    color: theme.palette,
+    backgroundColor: "transparent",
+    textStyle,
+    categoryAxis: axis,
+    valueAxis: axis,
+    logAxis: axis,
+    timeAxis: axis,
+    angleAxis: axis,
+    radiusAxis: axis,
+    axisPointer,
+    legend: {
+      textStyle,
+      itemWidth: theme.space.lg,
+      itemHeight: theme.space.md,
+      itemGap: theme.space.xl,
+      padding: theme.space.xs,
+      inactiveColor: theme.neutral,
+      inactiveBorderColor: theme.neutral,
+      pageTextStyle: textStyle,
+      pageIconColor: theme.foreground,
+      pageIconInactiveColor: theme.neutral,
+    },
+    tooltip: {
+      ...shadowless,
+      textStyle,
+      backgroundColor: theme.surface,
+      borderColor: theme.border,
+      borderWidth: theme.borderWidth,
+      borderRadius: theme.radius,
+      padding: [theme.space.md, theme.space.lg],
+      axisPointer,
+    },
+    line: {
+      ...seriesStates,
+      symbolSize: theme.space.sm,
+      lineStyle: { width: theme.lineWidth, shadowBlur: 0 },
+      areaStyle: { opacity: theme.opacity.area, shadowBlur: 0 },
+      label,
+    },
+    bar: { ...seriesStates, label, itemStyle: { shadowBlur: 0, borderWidth: 0 } },
+    pictorialBar: { ...seriesStates, label, itemStyle: { shadowBlur: 0, borderWidth: 0 } },
+    pie: { ...seriesStates, label, labelLine: { lineStyle: { width: theme.borderWidth } }, itemStyle: { borderColor: theme.surface, shadowBlur: 0 } },
+    radar: {
+      ...seriesStates,
+      axisName: label,
+      axisLine: axis.axisLine,
+      splitLine: axis.splitLine,
+      splitArea: axis.splitArea,
+      lineStyle: { width: theme.lineWidth, shadowBlur: 0 },
+      areaStyle: { opacity: theme.opacity.area, shadowBlur: 0 },
+      symbolSize: theme.space.sm,
+      label,
+    },
+    sankey: { ...seriesStates, label, lineStyle: { color: "source", opacity: theme.opacity.soft, shadowBlur: 0 }, itemStyle: { borderWidth: 0, shadowBlur: 0 } },
+    gauge: {
+      ...seriesStates,
+      title: textStyle,
+      detail: { ...textStyle, fontSize: theme.headingFontSize, fontWeight: theme.headingWeight },
+      axisLine: { lineStyle: { color: [[1, theme.neutral]], width: theme.space.lg } },
+      axisLabel: label,
+      axisTick: { lineStyle: { color: theme.border, width: theme.borderWidth } },
+      splitLine: { lineStyle: { color: theme.border, width: theme.borderWidth } },
+      pointer: { itemStyle: { color: theme.palette[0], shadowBlur: 0 } },
+      progress: { itemStyle: { color: theme.palette[0], shadowBlur: 0 } },
+    },
+    dataZoom: {
+      backgroundColor: theme.subtle,
+      borderColor: theme.border,
+      textStyle,
+      fillerColor: theme.subtle,
+      handleStyle: { color: theme.surface, borderColor: theme.border, borderWidth: theme.borderWidth, shadowBlur: 0 },
+      moveHandleStyle: { color: theme.neutral },
+      dataBackground: { lineStyle: { color: theme.neutral }, areaStyle: { color: theme.neutral, opacity: theme.opacity.area } },
+      selectedDataBackground: { lineStyle: { color: theme.palette[0] }, areaStyle: { color: theme.palette[0], opacity: theme.opacity.area } },
+    },
+  }
+}
+
+export function createEChartBaseOption(theme: EChartTheme): EChartsOption {
+  return {
+    color: theme.palette,
+    backgroundColor: "transparent",
+    textStyle: {
+      color: theme.foreground,
+      fontFamily: theme.fontFamily,
+      fontSize: theme.fontSize,
+      fontWeight: theme.fontWeight,
+    },
+    animation: !theme.reducedMotion,
+    animationDuration: theme.duration,
+    animationDurationUpdate: theme.duration,
+    // The labelled figure and optional data table provide the accessible content.
+    aria: { enabled: false },
+    tooltip: {
+      confine: true,
+      className: "bh-echart__tooltip",
+      shadowBlur: 0,
+      shadowOffsetX: 0,
+      shadowOffsetY: 0,
+      extraCssText: "box-shadow: none;",
+      transitionDuration: 0,
+    },
+  }
+}

package/registry/components/echart.css

@@ -0,0 +1,49 @@
+.bh-echart {
+  position: relative;
+  width: 100%;
+  height: var(--bh-space-17xl-288);
+  min-width: 0;
+  color: var(--bh-content-default);
+  font-family: var(--bh-font-family);
+  font-size: var(--bh-text-body-xs-regular-font-size);
+  font-weight: var(--bh-text-body-xs-regular-font-weight);
+  line-height: var(--bh-text-body-xs-regular-line-height);
+  letter-spacing: var(--bh-text-body-xs-regular-letter-spacing);
+}
+
+.bh-echart__viewport {
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+}
+
+/* ECharts positions text in physical SVG coordinates; axes handle RTL order. */
+.bh-echart__viewport svg {
+  direction: ltr;
+}
+
+.bh-echart .bh-echart__tooltip {
+  box-shadow: none !important;
+  font-family: var(--bh-font-family) !important;
+  letter-spacing: var(--bh-text-body-xs-regular-letter-spacing);
+}
+
+.bh-echart__status {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-content: center;
+  padding: var(--bh-space-3xl-16);
+  color: var(--bh-content-muted);
+  text-align: center;
+}
+
+.bh-echart__description {
+  position: absolute;
+  width: var(--bh-space-xxxs-1);
+  height: var(--bh-space-xxxs-1);
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}

package/registry/components/echart.tsx

@@ -0,0 +1,178 @@
+"use client"
+
+import * as React from "react"
+import { init, use, type ECharts } from "echarts/core"
+import { BarChart, GaugeChart, LineChart, PictorialBarChart, PieChart, RadarChart, SankeyChart } from "echarts/charts"
+import { AriaComponent, DataZoomComponent, GraphicComponent, GridComponent, LegendComponent, PolarComponent, TooltipComponent } from "echarts/components"
+import { SVGRenderer } from "echarts/renderers"
+import type { EChartsOption } from "echarts"
+
+import { cn } from "@/lib/utils"
+import { createEChartBaseOption, createEChartTheme, readEChartTheme, type EChartTheme } from "./echart-theme"
+import "./echart.css"
+
+use([BarChart, GaugeChart, LineChart, PictorialBarChart, PieChart, RadarChart, SankeyChart, AriaComponent, DataZoomComponent, GraphicComponent, GridComponent, LegendComponent, PolarComponent, TooltipComponent, SVGRenderer])
+
+export type EChartProps = Omit<React.ComponentProps<"div">, "children"> & {
+  /** Build all chart styling from the resolved, inherited Banhaten tokens. */
+  option: (theme: EChartTheme) => EChartsOption
+  label: string
+  description?: string
+  /** Optional instance interactions; return a cleanup for listeners and timers. */
+  onReady?: (chart: ECharts, theme: EChartTheme) => void | (() => void)
+}
+
+export function EChart({ className, option, label, description, onReady, ...props }: EChartProps) {
+  const viewportRef = React.useRef<HTMLDivElement>(null)
+  const refreshRef = React.useRef<(() => void) | null>(null)
+  const latest = React.useRef({ option, onReady })
+  latest.current = { option, onReady }
+  const descriptionId = React.useId()
+  const [error, setError] = React.useState(false)
+
+  React.useEffect(() => {
+    const viewport = viewportRef.current
+    if (!viewport) return
+
+    let instance: ECharts | undefined
+    let cleanupInteraction: void | (() => void)
+    let themeSignature = ""
+    let frame: number | undefined
+    let visible = typeof IntersectionObserver === "undefined"
+    let disposed = false
+    const motion = window.matchMedia("(prefers-reduced-motion: reduce)")
+
+    const paint = () => {
+      frame = undefined
+      if (disposed || !visible || viewport.clientWidth === 0 || viewport.clientHeight === 0) return
+
+      try {
+        const theme = readEChartTheme(viewport, motion.matches)
+        const nextSignature = JSON.stringify(theme)
+        const viewState = instance ? readViewState(instance) : undefined
+        cleanupInteraction?.()
+        cleanupInteraction = undefined
+        if (!instance || themeSignature !== nextSignature) {
+          instance?.dispose()
+          instance = init(viewport, createEChartTheme(theme), { renderer: "svg" })
+          themeSignature = nextSignature
+        }
+        const requested = latest.current.option(theme)
+        const base = createEChartBaseOption(theme)
+        const series = requested.series
+          ? (Array.isArray(requested.series) ? requested.series : [requested.series])
+          : []
+        const duration = theme.reducedMotion ? 0 : theme.duration
+        const shadowlessTooltip = { shadowBlur: 0, shadowOffsetX: 0, shadowOffsetY: 0, extraCssText: "box-shadow: none;" }
+        instance.setOption({
+          ...base,
+          ...requested,
+          animation: theme.reducedMotion ? false : requested.animation ?? base.animation,
+          animationDuration: duration,
+          animationDurationUpdate: duration,
+          // Native series have their own durations, which override global defaults.
+          series: series.map((item) => ({
+            ...item,
+            animation: !theme.reducedMotion && requested.animation !== false && item.animation !== false,
+            animationDuration: duration,
+            animationDurationUpdate: duration,
+            stateAnimation: { ...item.stateAnimation, duration },
+          })),
+          tooltip: requested.tooltip === undefined
+            ? base.tooltip
+            : Array.isArray(requested.tooltip)
+              ? requested.tooltip.map((tooltip) => ({ ...base.tooltip, ...tooltip, ...shadowlessTooltip }))
+              : { ...base.tooltip, ...requested.tooltip, ...shadowlessTooltip },
+        }, { notMerge: true })
+        if (viewState) instance.setOption(viewState, { silent: true })
+        instance.resize()
+        cleanupInteraction = latest.current.onReady?.(instance, theme)
+        setError(false)
+      } catch (cause) {
+        instance?.dispose()
+        instance = undefined
+        setError(true)
+        console.error("Unable to render Banhaten chart.", cause)
+      }
+    }
+    const schedule = () => {
+      if (!disposed && frame === undefined) frame = window.requestAnimationFrame(paint)
+    }
+    refreshRef.current = schedule
+
+    const intersection = typeof IntersectionObserver === "undefined" ? undefined : new IntersectionObserver((entries) => {
+      visible = entries.some((entry) => entry.isIntersecting)
+      if (visible) schedule()
+    })
+    intersection?.observe(viewport)
+
+    const resizeChart = () => { if (instance) instance.resize(); else schedule() }
+    const resize = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(resizeChart)
+    resize?.observe(viewport)
+    window.addEventListener("resize", resizeChart)
+    motion.addEventListener("change", schedule)
+
+    // Observe only this chart's ancestry, avoiding rerenders from SVG mutations.
+    const mutations = new MutationObserver(schedule)
+    let ancestor: HTMLElement | null = viewport.parentElement
+    while (ancestor) {
+      mutations.observe(ancestor, {
+        attributes: true,
+        attributeFilter: [
+          "class", "style", "dir", "data-theme", "data-color-mode",
+          "data-english-font", "data-arabic-font", "data-radius",
+        ],
+      })
+      ancestor = ancestor.parentElement
+    }
+    document.fonts?.addEventListener("loadingdone", schedule)
+    void document.fonts?.ready.then(schedule)
+    schedule()
+
+    return () => {
+      disposed = true
+      refreshRef.current = null
+      if (frame !== undefined) window.cancelAnimationFrame(frame)
+      intersection?.disconnect()
+      resize?.disconnect()
+      mutations.disconnect()
+      window.removeEventListener("resize", resizeChart)
+      motion.removeEventListener("change", schedule)
+      document.fonts?.removeEventListener("loadingdone", schedule)
+      cleanupInteraction?.()
+      instance?.dispose()
+    }
+  }, [])
+
+  React.useEffect(() => { refreshRef.current?.() }, [option, onReady])
+
+  return (
+    <div
+      role="figure"
+      aria-label={label}
+      aria-describedby={description ? descriptionId : undefined}
+      data-slot="echart"
+      className={cn("bh-echart", className)}
+      {...props}
+    >
+      <div ref={viewportRef} className="bh-echart__viewport" aria-hidden="true" />
+      {description ? <span id={descriptionId} className="bh-echart__description">{description}</span> : null}
+      {error ? <span className="bh-echart__status" role="status">Chart preview unavailable.</span> : null}
+    </div>
+  )
+}
+
+/** Theme refreshes retain the user's selected series and viewport. */
+function readViewState(instance: ECharts): EChartsOption {
+  const current = instance.getOption()
+  const result: EChartsOption = {}
+  if (Array.isArray(current.legend)) {
+    result.legend = current.legend.map((legend: { selected?: Record<string, boolean> }) => ({ selected: legend.selected }))
+  }
+  if (Array.isArray(current.dataZoom)) {
+    result.dataZoom = current.dataZoom.map((zoom: { start?: number; end?: number }) => ({ start: zoom.start, end: zoom.end }))
+  }
+  return result
+}
+
+export type { EChartTheme }