@exegia/corpora-ui 2.0.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {
@@ -60,6 +60,7 @@
     "clsx": "^2.1.1",
     "cn": "^0.2.6",
     "cuelume": "^0.2.2",
+    "echarts": "^6.1.0",
     "frimousse": "^0.3.0",
     "fumadocs-core": "^16.15.10",
     "fumadocs-mdx": "^15.4.0",

package/src/components/composed/chat/__tests__/chart.test.tsx

@@ -1,7 +1,31 @@
 import { describe, expect, mock, test } from "bun:test"
 import { fireEvent, render, screen } from "@testing-library/react"
 
-import { Chart } from "../chart"
+import {
+  Chart,
+  useChartActions,
+  useChartState,
+  removeChartInstance,
+} from "../chart"
+import { StrictMode } from "react"
+import { Provider, createStore } from "jotai"
+import { chartSelectedKeyAtom } from "../chart/chart-atom"
+import { buildChartConfig } from "../chart/utils"
+import { createChartTooltip } from "../chart/chart-tooltip"
+
+function Controls({ id }: { id: string }) {
+  const actions = useChartActions(id)
+  const { selectedKey } = useChartState(id)
+  return (
+    <>
+      <output data-testid={`${id}-selection`}>{selectedKey ?? "none"}</output>
+      <button onClick={() => actions.select("v")}>Select {id}</button>
+      <button onClick={actions.clearSelection}>Clear {id}</button>
+      <button onClick={actions.reset}>Reset {id}</button>
+      <button onClick={() => actions.select("missing")}>Invalid {id}</button>
+    </>
+  )
+}
 
 const data = [
   { label: "A", v: 1 },
@@ -60,3 +84,233 @@ describe("Chart", () => {
     expect(onClick).toHaveBeenCalledTimes(1)
   })
 })
+
+describe("Chart selection", () => {
+  test("named instances stay isolated and external actions update legend selection", () => {
+    const onChange = mock(() => {})
+    render(
+      <Provider>
+        <Chart
+          chartId="one"
+          type="bar"
+          data={data}
+          series={series}
+          interactive
+          onSelectionChange={onChange}
+        />
+        <Chart
+          chartId="two"
+          type="line"
+          data={data}
+          series={series}
+          interactive
+        />
+        <Controls id="one" />
+        <Controls id="two" />
+      </Provider>
+    )
+    fireEvent.click(screen.getByText("Select one"))
+    expect(screen.getByTestId("one-selection").textContent).toBe("v")
+    expect(screen.getByTestId("two-selection").textContent).toBe("none")
+    expect(
+      screen
+        .getAllByRole("button", { name: "Value" })[0]
+        .getAttribute("aria-pressed")
+    ).toBe("true")
+    expect(onChange).toHaveBeenCalledTimes(1)
+    fireEvent.click(screen.getByText("Invalid one"))
+    expect(onChange).toHaveBeenCalledTimes(1)
+    fireEvent.click(screen.getByText("Clear one"))
+    expect(screen.getByTestId("one-selection").textContent).toBe("none")
+  })
+  test("controlled props remain authoritative until parent accepts selection", () => {
+    const onChange = mock(() => {})
+    const { rerender } = render(
+      <Chart
+        type="area"
+        data={data}
+        series={series}
+        interactive
+        selectedKey={null}
+        onSelectionChange={onChange}
+      />
+    )
+    fireEvent.click(screen.getByRole("button", { name: "Value" }))
+    expect(onChange).toHaveBeenCalledWith("v")
+    expect(
+      screen.getByRole("button", { name: "Value" }).getAttribute("aria-pressed")
+    ).toBe("false")
+    rerender(
+      <Chart
+        type="area"
+        data={data}
+        series={series}
+        interactive
+        selectedKey="v"
+        onSelectionChange={onChange}
+      />
+    )
+    expect(
+      screen.getByRole("button", { name: "Value" }).getAttribute("aria-pressed")
+    ).toBe("true")
+  })
+  test("reset restores the default and removed series clear selection", () => {
+    const store = createStore()
+    const { rerender } = render(
+      <Provider store={store}>
+        <Chart
+          chartId="reset"
+          type="bar"
+          data={data}
+          series={series}
+          defaultSelectedKey="v"
+        />
+        <Controls id="reset" />
+      </Provider>
+    )
+    fireEvent.click(screen.getByText("Clear reset"))
+    fireEvent.click(screen.getByText("Reset reset"))
+    expect(store.get(chartSelectedKeyAtom("reset"))).toBe("v")
+    rerender(
+      <Provider store={store}>
+        <Chart
+          chartId="reset"
+          type="bar"
+          data={data}
+          series={[]}
+          defaultSelectedKey="v"
+        />
+      </Provider>
+    )
+    expect(store.get(chartSelectedKeyAtom("reset"))).toBeNull()
+  })
+  test("generated identity survives StrictMode effect replay", async () => {
+    render(
+      <StrictMode>
+        <Chart type="line" data={data} series={series} interactive />
+      </StrictMode>
+    )
+    await Promise.resolve()
+    fireEvent.click(screen.getByRole("button", { name: "Value" }))
+    expect(
+      screen.getByRole("button", { name: "Value" }).getAttribute("aria-pressed")
+    ).toBe("true")
+  })
+  test("pie selection uses category labels", () => {
+    const callback = mock(() => {})
+    render(
+      <Chart
+        type="pie"
+        data={data}
+        series={series}
+        interactive
+        onSelectionChange={callback}
+      />
+    )
+    fireEvent.click(screen.getByRole("button", { name: "A 1" }))
+    expect(callback).toHaveBeenCalledWith("A")
+  })
+  test("instance removal releases the atom family", () => {
+    const original = chartSelectedKeyAtom("removed")
+    removeChartInstance("removed")
+    expect(chartSelectedKeyAtom("removed")).not.toBe(original)
+  })
+})
+describe("Chart adapters", () => {
+  test("config preserves CSS tokens and custom series colors", () => {
+    expect(
+      buildChartConfig("bar", data, [{ ...series[0], color: "var(--primary)" }])
+        .v.colors?.light
+    ).toEqual(["var(--primary)"])
+    expect(Object.keys(buildChartConfig("pie", data, series))).toEqual([
+      "A",
+      "B",
+    ])
+  })
+  test("tooltip escapes data and preserves React formatters", () => {
+    const tooltip = createChartTooltip("bar", data, [
+      {
+        key: "v",
+        label: "<script>",
+        format: (value) => <strong>{value}%</strong>,
+      },
+    ])
+    const html = tooltip({ seriesIndex: 0, dataIndex: 1 })
+    expect(html).toContain("&lt;script&gt;")
+    expect(html).toContain("<strong>2%</strong>")
+  })
+})
+
+test("tooltip defaults to frosted glass with one surface shadow", () => {
+  const params = { seriesIndex: 0, dataIndex: 1 }
+  const html = createChartTooltip("bar", data, series)(params)
+  expect(html).toContain("bg-background/50")
+  expect(html).toContain("backdrop-blur-md")
+  expect(html).toContain("box-shadow:0 4px 12px rgb(0 0 0 / 0.12)")
+  const solid = createChartTooltip("bar", data, series, { variant: "default" })(
+    params
+  )
+  expect(solid).not.toContain("backdrop-blur-md")
+})
+
+describe("Chart consumer layout", () => {
+  test("accepts CSS dimensions and replaces the framed root", () => {
+    const { container } = render(
+      <Chart
+        type="bar"
+        data={[]}
+        series={series}
+        width="100%"
+        height={360}
+        render={<section aria-label="Research chart" />}
+      />
+    )
+    const root = screen.getByRole("region", { name: "Research chart" })
+    expect(root.getAttribute("data-slot")).toBe("chart")
+    expect(root.style.width).toBe("100%")
+    expect(root.style.height).toBe("360px")
+    expect(
+      (container.querySelector('[role="group"]') as HTMLElement).style.height
+    ).toBe("100%")
+  })
+  test("explicit plot height and consumer styles take precedence", () => {
+    const { container } = render(
+      <Chart
+        type="bar"
+        data={[]}
+        series={series}
+        width={320}
+        height={360}
+        plotHeight="12rem"
+        style={{ width: "90%" }}
+      />
+    )
+    expect(
+      (container.querySelector('[data-slot="chart"]') as HTMLElement).style
+        .width
+    ).toBe("90%")
+    expect(
+      (container.querySelector('[role="group"]') as HTMLElement).style.height
+    ).toBe("12rem")
+  })
+  test("custom components receive props and children in headerless mode", () => {
+    function Surface(props: React.ComponentProps<"section">) {
+      return <section {...props} data-surface="custom" />
+    }
+    render(
+      <Chart
+        type="pie"
+        data={[]}
+        series={series}
+        headerless
+        render={<Surface aria-label="Bare chart" />}
+        width={480}
+        height={240}
+      />
+    )
+    const root = screen.getByRole("region", { name: "Bare chart" })
+    expect(root.getAttribute("data-surface")).toBe("custom")
+    expect(root.style.width).toBe("480px")
+    expect(screen.getByRole("status").textContent).toBe("No data")
+  })
+})

package/src/components/composed/chat/chart/chart-atom.ts

@@ -0,0 +1,55 @@
+import { atom } from "jotai"
+import type { IChartState, TChartInstanceId } from "./type"
+
+function createChartAtoms(id: TChartInstanceId) {
+  const selected = atom<string | null>(null)
+  selected.debugLabel = `chart/${id}/selectedKey`
+  const config = atom<{
+    controlled: boolean
+    initial: string | null
+    keys: readonly string[]
+    onChange?: (key: string | null) => void
+  }>({ controlled: false, initial: null, keys: [] })
+  const select = atom(null, (get, set, key: string | null) => {
+    const settings = get(config)
+    if (key !== null && !settings.keys.includes(key)) return
+    if (get(selected) === key) return
+    if (!settings.controlled) set(selected, key)
+    settings.onChange?.(key)
+  })
+  const toggle = atom(null, (get, set, key: string) =>
+    set(select, get(selected) === key ? null : key)
+  )
+  const reset = atom(null, (get, set) => {
+    const { initial, keys } = get(config)
+    set(select, initial !== null && keys.includes(initial) ? initial : null)
+  })
+  const state = atom<IChartState>((get) => ({ selectedKey: get(selected) }))
+  return { selected, config, select, toggle, reset, state }
+}
+const instances = new Map<
+  TChartInstanceId,
+  ReturnType<typeof createChartAtoms>
+>()
+function chartAtoms(id: TChartInstanceId) {
+  let atoms = instances.get(id)
+  if (!atoms) {
+    atoms = createChartAtoms(id)
+    instances.set(id, atoms)
+  }
+  return atoms
+}
+export const chartSelectedKeyAtom = (id: TChartInstanceId) =>
+  chartAtoms(id).selected
+export const chartStateAtom = (id: TChartInstanceId) => chartAtoms(id).state
+export const selectChartKeyAtom = (id: TChartInstanceId) =>
+  chartAtoms(id).select
+export const toggleChartKeyAtom = (id: TChartInstanceId) =>
+  chartAtoms(id).toggle
+export const resetChartAtom = (id: TChartInstanceId) => chartAtoms(id).reset
+/** @internal Mounted root projects configuration and controlled props. */
+export const chartConfigAtom = (id: TChartInstanceId) => chartAtoms(id).config
+/** Call only after all consumers of a named instance have unmounted. */
+export function removeChartInstance(id: TChartInstanceId) {
+  instances.delete(id)
+}

package/src/components/composed/chat/chart/chart-context.ts

@@ -0,0 +1,9 @@
+"use client"
+import { createContext, useContext } from "react"
+export const ChartContext = createContext<string | null>(null)
+export function useChartContext() {
+  const id = useContext(ChartContext)
+  if (id === null)
+    throw new Error("useChartContext must be used within <Chart>")
+  return id
+}

package/src/components/composed/chat/chart/chart-legend.tsx

@@ -0,0 +1,75 @@
+"use client"
+import type { CSSProperties } from "react"
+import { LegendItem, type TDotTone } from "@/components/ui/chat"
+import { cn } from "@/lib/utils"
+import { chartSeriesColor, formatChartValue } from "./utils"
+import type { IChartProps } from "./type"
+export function ChartLegend({
+  type,
+  data,
+  series,
+  selectedKey,
+  interactive,
+  onSelect,
+}: Pick<
+  IChartProps,
+  "type" | "data" | "series" | "selectedKey" | "interactive"
+> & { onSelect: (key: string) => void }) {
+  const entries =
+    type === "pie"
+      ? data.map((row, i) => ({
+          key: row.label,
+          label: row.label,
+          value: formatChartValue(series[0], row[series[0].key]),
+          color: `var(--chart-series-${(i % 5) + 1})`,
+        }))
+      : series.map((s, i) => ({
+          key: s.key,
+          label: s.label,
+          value: undefined,
+          color: chartSeriesColor(s, i),
+        }))
+  return (
+    <ul
+      data-slot="chart-legend"
+      className={cn(
+        "gap-3 flex flex-wrap",
+        type === "pie" && "min-w-24 flex-1 flex-col"
+      )}
+    >
+      {entries.map((entry, i) => (
+        <li
+          key={entry.key}
+          style={{ "--legend-color": entry.color } as CSSProperties}
+          className={cn(
+            "min-w-0 [&_[data-slot=dot]]:bg-(--legend-color)",
+            selectedKey && selectedKey !== entry.key && "opacity-40"
+          )}
+        >
+          {interactive ? (
+            <button
+              type="button"
+              aria-pressed={selectedKey === entry.key}
+              className="w-full rounded-sm text-left focus-visible:outline-2 focus-visible:outline-ring"
+              onClick={() => onSelect(entry.key)}
+            >
+              <LegendItem
+                tone={`series-${(i % 5) + 1}` as TDotTone}
+                value={entry.value}
+              >
+                {entry.label}
+              </LegendItem>
+            </button>
+          ) : (
+            <LegendItem
+              tone={`series-${(i % 5) + 1}` as TDotTone}
+              value={entry.value}
+            >
+              {entry.label}
+            </LegendItem>
+          )}
+        </li>
+      ))}
+    </ul>
+  )
+}

package/src/components/composed/chat/chart/chart-plot.tsx

@@ -0,0 +1,233 @@
+"use client"
+import { useMemo, useEffect, useRef, useState } from "react"
+import { EChartsAreaChart as Area } from "./evilcharts/echarts-area-chart"
+import { EChartsLineChart as Line } from "./evilcharts/echarts-line-chart"
+import { EChartsBarChart as Bar } from "./evilcharts/echarts-bar-chart"
+import { EChartsPieChart as Pie } from "./evilcharts/echarts-pie-chart"
+import { resolveTooltipPosition } from "./evilcharts/echarts-tooltip"
+import { buildChartConfig } from "./utils"
+import { createChartTooltip } from "./chart-tooltip"
+import type { IChartProps } from "./type"
+
+/** Wait for layout before initializing ECharts (also supports hidden tabs and SSR). */
+export function ChartPlot(props: IChartProps) {
+  const host = useRef<HTMLDivElement>(null)
+  const [ready, setReady] = useState(false)
+  useEffect(() => {
+    const node = host.current
+    if (!node) return
+    const observer = new ResizeObserver((entries) => {
+      if (
+        entries.some(
+          (entry) => entry.contentRect.width > 0 && entry.contentRect.height > 0
+        )
+      )
+        setReady(true)
+    })
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [])
+  return (
+    <div ref={host} className="h-full w-full">
+      {ready && <ChartRenderer {...props} />}
+    </div>
+  )
+}
+
+function ChartRenderer({
+  type,
+  data,
+  series,
+  variant = "default",
+  renderer = "canvas",
+  animation = true,
+  loading = false,
+  interactive = false,
+  selectedKey = null,
+  onSelectionChange,
+  curveType = "monotone",
+  grid = true,
+  xAxis = true,
+  yAxis = false,
+  tooltip = true,
+  brush = false,
+  pie,
+  chartOptions,
+}: IChartProps) {
+  const config = useMemo(
+    () => buildChartConfig(type, data, series),
+    [type, data, series]
+  )
+  const options = useMemo(
+    () => ({
+      ...(tooltip
+        ? {
+            tooltip: {
+              show: !loading,
+              trigger: type === "pie" ? "item" : "axis",
+              confine: true,
+              padding: 0,
+              borderWidth: 0,
+              backgroundColor: "transparent",
+              // Only the inner tooltip owns a shadow; ECharts adds one otherwise.
+              extraCssText: "box-shadow:none;",
+              axisPointer: {
+                type:
+                  typeof tooltip === "object" && tooltip.cursor === false
+                    ? "none"
+                    : "line",
+              },
+              position: resolveTooltipPosition(
+                typeof tooltip === "object"
+                  ? (tooltip.position ?? "variable")
+                  : "variable"
+              ),
+              formatter: createChartTooltip(
+                type,
+                data,
+                series,
+                typeof tooltip === "object" ? tooltip : {}
+              ),
+            },
+          }
+        : {}),
+      ...chartOptions,
+    }),
+    [tooltip, loading, type, data, series, chartOptions]
+  )
+  const common = {
+    data,
+    config,
+    renderer,
+    animation,
+    isLoading: loading,
+    chartOptions: options,
+    className: "h-full w-full",
+  }
+  const selection = { selectedDataKey: selectedKey, onSelectionChange }
+  const tooltipProps = typeof tooltip === "object" ? tooltip : {}
+  const xProps = typeof xAxis === "object" ? xAxis : {}
+  const yProps = typeof yAxis === "object" ? yAxis : {}
+  const brushProps = typeof brush === "object" ? brush : {}
+  if (type === "pie")
+    return (
+      <Pie
+        {...common}
+        dataKey={series[0]?.key ?? "value"}
+        nameKey="label"
+        selectedSector={selectedKey}
+        onSelectionChange={(value) =>
+          onSelectionChange?.(value?.dataKey ?? null)
+        }
+      >
+        <Pie.Pie
+          innerRadius={variant === "donut" || variant === "default" ? "66%" : 0}
+          outerRadius="95%"
+          paddingAngle={2}
+          cornerRadius={8}
+          isClickable={interactive}
+          {...pie}
+        />
+        {tooltip && <Pie.Tooltip {...tooltipProps} />}
+      </Pie>
+    )
+  if (type === "bar")
+    return (
+      <Bar
+        {...common}
+        {...selection}
+        xDataKey="label"
+        barRadius={8}
+        layout={variant === "horizontal" ? "horizontal" : "vertical"}
+        stackType={
+          variant === "percent"
+            ? "percent"
+            : variant === "stacked"
+              ? "stacked"
+              : "default"
+        }
+      >
+        {series.map((s) => (
+          <Bar.Bar
+            key={s.key}
+            dataKey={s.key}
+            isClickable={interactive}
+            {...s.bar}
+          />
+        ))}
+        {xAxis && <Bar.XAxis {...xProps} />}
+        {yAxis && (
+          <Bar.YAxis
+            {...yProps}
+            tickFormatter={
+              yProps.tickFormatter
+                ? (value, index) => yProps.tickFormatter!(Number(value), index)
+                : undefined
+            }
+          />
+        )}
+        {grid && <Bar.Grid />}
+        {tooltip && <Bar.Tooltip {...tooltipProps} />}
+        {brush && variant !== "horizontal" && <Bar.Brush {...brushProps} />}
+      </Bar>
+    )
+  if (type === "line")
+    return (
+      <Line
+        {...common}
+        {...selection}
+        xDataKey="label"
+        curveType={curveType}
+        enableHoverHighlight={interactive}
+      >
+        {series.map((s) => (
+          <Line.Line
+            key={s.key}
+            dataKey={s.key}
+            isClickable={interactive}
+            {...s.line}
+          >
+            <Line.Dot />
+            <Line.ActiveDot />
+          </Line.Line>
+        ))}
+        {xAxis && <Line.XAxis {...xProps} />}
+        {yAxis && <Line.YAxis {...yProps} />}
+        {grid && <Line.Grid />}
+        {tooltip && <Line.Tooltip {...tooltipProps} />}
+        {brush && <Line.Brush {...brushProps} />}
+      </Line>
+    )
+  return (
+    <Area
+      {...common}
+      {...selection}
+      xDataKey="label"
+      curveType={curveType}
+      enableHoverHighlight={interactive}
+      stackType={
+        variant === "percent"
+          ? "expanded"
+          : variant === "stacked"
+            ? "stacked"
+            : "default"
+      }
+    >
+      {series.map((s) => (
+        <Area.Area
+          key={s.key}
+          dataKey={s.key}
+          isClickable={interactive}
+          {...s.area}
+        >
+          <Area.ActiveDot />
+        </Area.Area>
+      ))}
+      {xAxis && <Area.XAxis {...xProps} />}
+      {yAxis && <Area.YAxis {...yProps} />}
+      {grid && <Area.Grid />}
+      {tooltip && <Area.Tooltip {...tooltipProps} />}
+      {brush && <Area.Brush {...brushProps} />}
+    </Area>
+  )
+}