@vestow/vue 0.1.0

package/src/components/chart/BarChart.vue

@@ -0,0 +1,389 @@
+<script setup lang="ts" generic="T extends Record<string, unknown>">
+import type { ClassProps } from '../../lib/types'
+import type { ChartBaseProps, ChartLabelKey } from './types'
+import { GroupedBar, StackedBar } from '@unovis/ts'
+import { VisAxis, VisGroupedBar, VisStackedBar, VisXYContainer, VisXYLabels } from '@unovis/vue'
+import { computed, ref } from 'vue'
+import { cn } from '../../lib/utils'
+import ChartContainer from './ChartContainer.vue'
+import ChartCrosshair from './ChartCrosshair.vue'
+import ChartLegend from './ChartLegend.vue'
+import { useChartSeries } from './useChartSeries'
+import { xyLabelHtml } from './xy-label'
+
+const props = withDefaults(defineProps<ClassProps & ChartBaseProps<T> & {
+  /** Xếp chồng thay vì đặt cạnh nhau. @default false */
+  stacked?: boolean
+  /** Bo góc trên của cột, tính bằng pixel. @default 4 */
+  radius?: number
+  /** Chặn bề rộng tối đa của một nhóm cột. */
+  barMaxWidth?: number
+  /** Cột nằm ngang: hạng mục chạy theo trục tung. @default false */
+  horizontal?: boolean
+  /**
+   * Tô mỗi CỘT một màu theo thứ tự hạng mục, thay vì mỗi CHUỖI một màu.
+   * Chỉ có nghĩa khi vẽ đúng một chuỗi — khoá tra màu khi đó là giá trị của
+   * `index`, giống cách PieChart lấy màu.
+   * @default false
+   */
+  colorByIndex?: boolean
+  /**
+   * Chỉ số cột được đánh dấu là đang chọn.
+   *
+   * Đánh dấu bằng **viền đứt nét** màu của chính cột đó, cộng nền còn 80% —
+   * đúng cách shadcn làm (`chart-bar-active`). Các cột khác giữ NGUYÊN.
+   *
+   * Bản trước làm ngược: để cột được chọn nguyên vẹn rồi pha loãng mọi cột khác
+   * xuống 28%. Nhìn ra là "năm cột bị mờ" chứ không ra "một cột được chọn", và
+   * ở biểu đồ nhiều cột thì phần lớn dữ liệu tự dưng khó đọc.
+   */
+  activeIndex?: number
+  /**
+   * In nhãn ở đầu cột — trên đỉnh khi cột đứng, ngoài mũi cột khi cột nằm ngang.
+   * @default false
+   */
+  showLabels?: boolean
+  /** Nhãn đó in giá trị hay tên hạng mục. @default 'value' */
+  labelKey?: ChartLabelKey
+  /**
+   * Thêm nhãn TÊN hạng mục nằm trong lòng cột, sát gốc.
+   *
+   * Chỉ có nghĩa với `horizontal`: đó là khuôn "bar list" của shadcn — tên nằm
+   * trong cột, số nằm ngoài mũi cột, và cả hai trục đều ẩn. Cột đứng thì trong
+   * lòng cột không đủ bề ngang cho một cái tên.
+   * @default false
+   */
+  showIndexLabels?: boolean
+  /** Bấm vào legend để ẩn/hiện chuỗi. @default false */
+  interactiveLegend?: boolean
+  /**
+   * Thời lượng animation vào trang, mili giây. Mặc định **0**: 68 biểu đồ cùng
+   * mount một lúc, animation từ 0 làm cả trang trông như cột bị nén dí xuống
+   * đáy trong ~0,7 giây đầu — đã đo, và đã khiến chính tôi lẫn người dùng tưởng
+   * là lỗi hình học. Đặt 400–600 nếu muốn hiệu ứng ở màn dashboard chỉ có vài
+   * biểu đồ.
+   * @default 0
+   */
+  duration?: number
+}>(), {
+  duration: 0,
+  stacked: false,
+  radius: 4,
+  horizontal: false,
+  colorByIndex: false,
+  showLabels: false,
+  labelKey: 'value',
+  showIndexLabels: false,
+  showXAxis: true,
+  showYAxis: true,
+  showTooltip: true,
+  showLegend: false,
+  showGridLine: true,
+  showCursor: true,
+  interactiveLegend: false,
+  margin: () => ({ top: 8, right: 8, bottom: 0, left: 0 }),
+})
+
+const hidden = ref<string[]>([])
+
+// Bar KHÔNG dùng phần xếp chồng tính sẵn của `useChartSeries`: `VisStackedBar`
+// tự chồng khi nhận mảng accessor `y`, mà cột thì không cần gradient riêng cho
+// từng lớp nên cũng không có lý do gì phải tách ra.
+const { categories, plotData, xTicks, isMounted } = useChartSeries(props)
+
+/** Chuỗi đang hiện — chuỗi bị legend tắt bị bỏ hẳn ra để cột co lại đúng chỗ. */
+const visible = computed(() => categories.value.filter(key => !hidden.value.includes(key)))
+
+const yAccessors = computed(() => visible.value.map(
+  key => (d: Record<string, unknown>): number => Number(d[key]) || 0,
+))
+
+const colors = computed(() => visible.value.map(key => `var(--color-${key})`))
+
+function colorOf(key: string): string {
+  return `var(--color-${key})`
+}
+
+function labelOf(key: string): string {
+  return props.config[key]?.label ?? key
+}
+
+/**
+ * Mặc định Unovis gọi accessor màu với chỉ số LỚP (chuỗi thứ mấy).
+ * `colorByIndex` đổi nghĩa sang chỉ số HÀNG: mỗi cột một màu, dùng cho biểu đồ
+ * một chuỗi mà từng hạng mục cần màu riêng.
+ */
+function barColor(d: Record<string, unknown>, i: number): string {
+  if (props.colorByIndex)
+    return `var(--color-${String(d?.[props.index] ?? '')})`
+  return colors.value[i] ?? 'transparent'
+}
+
+/**
+ * Gắn móc `data-active-bar` lên cột đang chọn để CSS bắt được.
+ *
+ * `attributes` của Unovis chỉ gọi `selection.attr()`, mà thuộc tính trình bày
+ * thì yếu hơn mọi rule CSS — nên viền phải khai bằng CSS (xem `index.css`), ở
+ * đây chỉ đánh dấu.
+ *
+ * Bars của Unovis được bind vào chính HÀNG dữ liệu, nên đọc `__i` là ra chỉ số
+ * hàng. Tham số thứ hai là chỉ số CHUỖI trong nhóm, không dùng được.
+ *
+ * Trả về chuỗi rỗng thay vì `null` cho cột không được chọn: selector khoá theo
+ * `="true"` nên thuộc tính rỗng vô hại, mà kiểu của `StringAccessor` thì không
+ * nhận `null`.
+ */
+const barAttributes = computed(() => {
+  const selector = props.stacked ? StackedBar.selectors.bar : GroupedBar.selectors.bar
+  return {
+    [selector]: {
+      'data-active-bar': (d: Record<string, unknown>): string =>
+        props.activeIndex !== undefined && Number(d.__i) === props.activeIndex ? 'true' : '',
+    },
+  }
+})
+
+/**
+ * Vị trí của một hàng trên trục hạng mục.
+ *
+ * Cột NGANG phải ĐẢO: thang trục tung của Unovis chạy từ dưới lên, nên hàng đầu
+ * tiên rơi xuống đáy và bảng đọc ngược hẳn so với dữ liệu — shadcn (và mọi bảng
+ * ngang khác) xếp hàng đầu ở TRÊN CÙNG. Đảo bằng chỉ số chứ không đảo domain:
+ * đảo domain thì bề dày cột tính ra âm.
+ *
+ * Mọi chỗ đọc vị trí hàng đều phải đi qua đây — cột, nhãn, và cả nhãn trục.
+ */
+function rowPos(i: number): number {
+  return props.horizontal ? props.data.length - 1 - i : i
+}
+
+/** Chuỗi được gắn nhãn. Chỉ chuỗi ĐẦU — chồng nhãn lên cột nhóm là không đọc được. */
+const labelled = computed(() => visible.value[0] ?? '')
+
+/**
+ * Màu viền của cột đang chọn — chính màu của cột đó, đúng cách shadcn lấy
+ * `props.payload.fill`. Phải tính ở đây rồi truyền xuống qua biến CSS, vì CSS
+ * không có cách nào đọc `fill` của một element để dùng lại cho `stroke`.
+ */
+const activeBarColor = computed(() => {
+  if (props.activeIndex === undefined)
+    return undefined
+
+  const row = props.data[props.activeIndex]
+  if (row === undefined)
+    return undefined
+
+  const key = props.colorByIndex ? String(row[props.index] ?? '') : labelled.value
+  return key ? `var(--color-${key})` : undefined
+})
+
+/** Tên hạng mục của một hàng, tra qua config trước. */
+function indexTextOf(d: Record<string, unknown>): string {
+  const raw = String(d[props.index] ?? '')
+  return props.config[raw]?.label ?? raw
+}
+
+function valueTextOf(d: Record<string, unknown>): string {
+  const key = labelled.value
+  const raw = Number(d[key]) || 0
+  return props.valueFormatter ? props.valueFormatter(raw, key) : String(raw)
+}
+
+/**
+ * Vị trí neo nhãn trên trục trị số.
+ *
+ * Kẹp về phía vạch KHÔNG khi giá trị âm. Recharts đặt `position="top"` ở mép
+ * TRÊN của hình chữ nhật, mà cột âm chạy từ vạch 0 xuống dưới nên mép trên của
+ * nó chính là vạch 0 — nhãn nằm ngay trên vạch, không rơi xuống đáy cột.
+ *
+ * Không đụng gì tới cột dương: `max(v, 0)` bằng đúng `v`.
+ */
+function labelAnchor(d: Record<string, unknown>): number {
+  return Math.max(Number(d[labelled.value]) || 0, 0)
+}
+
+/**
+ * Nhãn ở đầu cột. Lệch theo PIXEL, nên phải đi qua `xyLabelHtml` — xem ghi chú
+ * ở `xy-label.ts` về việc `VisXYLabels` không có tuỳ chọn lệch nào.
+ *
+ * Cột ngang thì nhãn ra ngoài mũi cột, cột đứng thì lên trên đỉnh — 8px và
+ * 12px, đúng hai con số shadcn dùng cho `position="right"` và `position="top"`.
+ *
+ * Nhưng `offset` của Recharts đo MÉP CHỮ tới mép cột, còn `dy` ở đây đo TÂM
+ * chữ, nên chiều dọc phải cộng thêm nửa chiều cao chữ. Chiều ngang thì không:
+ * căn trái nên mép trái chữ rơi đúng vào `dx`.
+ */
+const LABEL_GAP_Y = 12 + 12 / 2
+function labelAt(d: Record<string, unknown>): string {
+  if (!labelled.value)
+    return ''
+  const text = props.labelKey === 'name' ? indexTextOf(d) : valueTextOf(d)
+  return props.horizontal
+    ? xyLabelHtml(text, { dx: 8, anchor: 'start' })
+    : xyLabelHtml(text, { dy: -LABEL_GAP_Y })
+}
+
+/** Nhãn tên nằm trong lòng cột, cách gốc 8px. */
+function indexLabelAt(d: Record<string, unknown>): string {
+  return xyLabelHtml(indexTextOf(d), { dx: 8, anchor: 'start' })
+}
+
+/**
+ * Chữ nằm ĐÈ lên màu cột nên phải lấy màu chữ dẫn xuất của chính chuỗi đó, chứ
+ * không phải `--foreground`. shadcn khai cứng `var(--background)`; ở đây
+ * `--color-<key>-foreground` tự chọn đen hay trắng theo độ sáng của màu nền —
+ * cần thiết vì thang màu chuỗi cố ý trải rộng độ sáng.
+ */
+const indexLabelColor = computed(() => `var(--color-${labelled.value}-foreground)`)
+
+/**
+ * Kẻ lưới KHÔNG đi kèm việc có hiện trục hay không.
+ *
+ * Unovis chỉ vẽ lưới qua `VisAxis`, nên bỏ trục là mất luôn lưới — trong khi
+ * `CartesianGrid` của Recharts là component độc lập, và gần như mọi biểu đồ
+ * trong gallery shadcn đều có lưới mà KHÔNG có trục tung. Cách xử lý: vẫn dựng
+ * trục đó nhưng cho nhãn rỗng. Bleed của Unovis tính theo bề rộng nhãn thật nên
+ * nhãn rỗng gần như không chiếm chỗ.
+ *
+ * Trục mang lưới: cột đứng thì trục tung, cột ngang thì trục hoành.
+ */
+const showX = computed(() => props.showXAxis || (props.showGridLine && props.horizontal))
+const showY = computed(() => props.showYAxis || (props.showGridLine && !props.horizontal))
+
+function formatX(tick: number | Date, i: number, ticks: number[] | Date[]): string {
+  // `tick` là VỊ TRÍ trên trục, phải đổi ngược về chỉ số hàng trước khi tra.
+  const row = rowPos(Number(tick))
+  if (props.xFormatter)
+    return props.xFormatter(row, i, ticks)
+  return String(props.data[row]?.[props.index] ?? '')
+}
+
+/** Nhãn rỗng cho trục chỉ tồn tại để mang kẻ lưới. */
+function blankTick(): string {
+  return ''
+}
+
+function toggle(key: string): void {
+  hidden.value = hidden.value.includes(key)
+    ? hidden.value.filter(k => k !== key)
+    : [...hidden.value, key]
+}
+</script>
+
+<template>
+  <ChartContainer
+    :config="props.config"
+    :show-cursor="props.showCursor"
+    :class="cn(props.class)"
+    :style="activeBarColor ? { '--chart-active-bar': activeBarColor } : undefined"
+  >
+    <VisXYContainer
+      :data="plotData"
+      :margin="props.margin"
+      :duration="props.duration"
+      :style="{ height: isMounted ? '100%' : 'auto' }"
+    >
+      <VisStackedBar
+        v-if="props.stacked"
+        :x="(_d: Record<string, unknown>, i: number) => rowPos(i)"
+        :y="yAccessors"
+        :color="barColor"
+        :rounded-corners="props.radius"
+        :bar-max-width="props.barMaxWidth"
+        :bar-padding="0.2"
+        :orientation="props.horizontal ? 'horizontal' : 'vertical'"
+        :attributes="barAttributes"
+      />
+      <VisGroupedBar
+        v-else
+        :x="(_d: Record<string, unknown>, i: number) => rowPos(i)"
+        :y="yAccessors"
+        :color="barColor"
+        :rounded-corners="props.radius"
+        :group-max-width="props.barMaxWidth"
+        :group-padding="0.2"
+        :orientation="props.horizontal ? 'horizontal' : 'vertical'"
+        :attributes="barAttributes"
+      />
+
+      <!--
+        Cột ngang thì HAI TRỤC ĐỔI VAI, nên accessor của nhãn cũng phải đổi theo:
+        trị số chạy trên trục hoành, chỉ số hàng trên trục tung. Giữ nguyên cách
+        khai sẽ ra nhãn nằm rải rác giữa khung, không dính vào cột nào.
+      -->
+      <VisXYLabels
+        v-if="props.showLabels"
+        :x="props.horizontal
+          ? labelAnchor
+          : (d: Record<string, unknown>) => rowPos(Number(d.__i))"
+        :y="props.horizontal
+          ? (d: Record<string, unknown>) => rowPos(Number(d.__i))
+          : labelAnchor"
+        :label="labelAt"
+        :label-font-size="12"
+        :clustering="false"
+        background-color="none"
+        color="var(--foreground)"
+      />
+
+      <!-- Neo ở giá trị 0, tức mép gốc của cột — không phải mép trái khung vẽ. -->
+      <VisXYLabels
+        v-if="props.showIndexLabels && props.horizontal"
+        :x="() => 0"
+        :y="(d: Record<string, unknown>) => rowPos(Number(d.__i))"
+        :label="indexLabelAt"
+        :label-font-size="12"
+        :clustering="false"
+        background-color="none"
+        :color="indexLabelColor"
+      />
+
+      <ChartCrosshair
+        v-if="props.showTooltip"
+        :index="props.index"
+        :categories="categories as Extract<keyof T, string>[]"
+        :hidden="hidden"
+        :color-of="colorOf"
+        :label-of="labelOf"
+        :value-formatter="props.valueFormatter"
+        :options="props.tooltip"
+        :default-index="props.defaultIndex"
+        :show-cursor="props.showCursor"
+      />
+
+      <!--
+        Nằm ngang thì HAI TRỤC ĐỔI VAI: hạng mục chạy theo trục tung, còn trị số
+        theo trục hoành. Giữ nguyên cách khai sẽ ra nhãn tháng nằm dưới trong khi
+        cột lại kéo ngang — nhìn là biết sai ngay.
+      -->
+      <VisAxis
+        v-if="showX"
+        type="x"
+        :tick-values="props.horizontal ? undefined : xTicks"
+        :tick-format="props.showXAxis ? (props.horizontal ? props.yFormatter : formatX) : blankTick"
+        :grid-line="props.horizontal ? props.showGridLine : false"
+        :tick-line="false"
+        :domain-line="false"
+      />
+      <VisAxis
+        v-if="showY"
+        type="y"
+        :tick-values="props.horizontal ? xTicks : undefined"
+        :tick-format="props.showYAxis ? (props.horizontal ? formatX : props.yFormatter) : blankTick"
+        :grid-line="props.horizontal ? false : props.showGridLine"
+        :tick-line="false"
+        :domain-line="false"
+      />
+
+      <slot />
+    </VisXYContainer>
+
+    <ChartLegend
+      v-if="props.showLegend"
+      :categories="categories"
+      :hidden="hidden"
+      :interactive="props.interactiveLegend"
+      @toggle="toggle"
+    />
+  </ChartContainer>
+</template>

package/src/components/chart/ChartContainer.vue

@@ -0,0 +1,127 @@
+<script setup lang="ts">
+import type { ClassProps } from '../../lib/types'
+import type { ChartConfig, ChartContext } from './types'
+import { computed, provide, ref } from 'vue'
+import { cn } from '../../lib/utils'
+import { CHART_CONTEXT_KEY } from './types'
+
+const props = withDefaults(defineProps<ClassProps & {
+  config: ChartConfig
+  /** Vạch dóng dọc khi rê chuột. @default true */
+  showCursor?: boolean
+}>(), {
+  showCursor: true,
+})
+
+const keys = computed(() => Object.keys(props.config))
+
+/**
+ * `var(--color-<key>)` chứ không phải màu đã resolve — xem ghi chú ở `ChartContext`.
+ * Unovis vốn thiết kế theo hướng CSS variable (mặc định của nó là
+ * `var(--vis-colorN)`), nên chuỗi này đi thẳng vào thuộc tính SVG được.
+ */
+function colorOf(key: string): string {
+  return `var(--color-${key})`
+}
+
+function labelOf(key: string): string {
+  return props.config[key]?.label ?? key
+}
+
+/**
+ * Biến CSS đặt ngay trên thẻ bọc, hai nhóm:
+ *
+ * 1. `--color-<key>` cho từng chuỗi — đúng cách shadcn làm, nhờ vậy khai màu một
+ *    chỗ rồi dùng lại ở đường vẽ, chấm tooltip và ô legend.
+ * 2. `--vis-*` để nối diện mạo của Unovis vào token của repo.
+ *
+ * Cơ chế dark theme SẴN CÓ của Unovis cố tình không dùng: nó bắt theo
+ * `html[data-theme="dark"]` / `html.theme-dark`, mà repo này dùng `html.dark` —
+ * không selector nào khớp. Khai thẳng token ở đây thì chart đi theo cả năm bảng
+ * màu, hai chế độ sáng/tối và cả `data-surface="glass"` mà không cần một dòng JS.
+ */
+const styleVars = computed<Record<string, string>>(() => {
+  const vars: Record<string, string> = {
+    '--vis-font-family': 'var(--font-sans)',
+    '--vis-axis-font-family': 'var(--font-sans)',
+
+    // Trục: chữ mờ một nấc so với nội dung, kẻ nền dùng đúng màu viền chung.
+    '--vis-axis-tick-label-color': 'var(--muted-foreground)',
+    '--vis-axis-label-color': 'var(--muted-foreground)',
+    '--vis-axis-tick-label-font-size': '12px',
+    '--vis-axis-grid-color': 'var(--border)',
+    '--vis-axis-domain-color': 'var(--border)',
+    '--vis-axis-tick-color': 'var(--border)',
+    '--vis-axis-grid-line-width': '1',
+
+    // Vạch dóng khi rê chuột. Tắt bằng ĐỘ ĐỤC chứ không bằng màu: Unovis tô vạch
+    // qua một class emotion đọc `--vis-crosshair-line-stroke-opacity`, nên đây là
+    // chỗ duy nhất giấu được nó mà không phải đụng vào DOM sau khi vẽ.
+    '--vis-crosshair-line-stroke-color': 'var(--border)',
+    '--vis-crosshair-line-stroke-width': '1',
+    '--vis-crosshair-line-stroke-opacity': props.showCursor ? '1' : '0',
+    '--vis-crosshair-circle-stroke-color': 'var(--background)',
+
+    // Hộp tooltip của Unovis bị làm cho TÀNG HÌNH: nền, viền, bóng và padding
+    // đều do markup của mình vẽ bằng utility Tailwind (xem `tooltip.ts`), nhờ
+    // vậy tooltip dùng đúng token như Popover chứ không phải một hộp riêng.
+    '--vis-tooltip-background-color': 'transparent',
+    '--vis-tooltip-border-color': 'transparent',
+    '--vis-tooltip-box-shadow': 'none',
+    '--vis-tooltip-backdrop-filter': 'none',
+    '--vis-tooltip-padding': '0',
+    '--vis-tooltip-border-radius': '0',
+  }
+
+  // Lưới màu dự phòng của Unovis (`--vis-color0`…`--vis-color5`) cho trường hợp
+  // một component con quên truyền `color` — đỡ ra hình trong suốt.
+  for (let i = 0; i < 6; i += 1) {
+    vars[`--vis-color${i}`] = `var(--chart-${(i % 5) + 1})`
+  }
+
+  keys.value.forEach((key, i) => {
+    const color = props.config[key]?.color ?? `var(--chart-${(i % 5) + 1})`
+    vars[`--color-${key}`] = color
+    // Màu chữ đặt TRỰC TIẾP trên màu chuỗi đó (nhãn trong cột, trong lát, trên
+    // vòng radial). Không thể dùng chung một màu chữ cho cả bộ vì thang màu cố ý
+    // trải rộng độ sáng — cùng cơ chế và cùng ngưỡng với `--chart-N-foreground`
+    // trong tokens.css; xem ghi chú ở đó về vì sao hệ số phải là 1000.
+    vars[`--color-${key}-foreground`] = `oklch(from ${color} clamp(0, (0.58 - l) * 1000, 1) 0 h)`
+  })
+
+  return vars
+})
+
+/**
+ * Con trỏ có đang ở trong khung không. Theo dõi ở ĐÂY chứ không ở từng biểu đồ
+ * vì đây là thẻ bọc duy nhất dùng chung, và `ChartCrosshair` thì không có phần
+ * tử DOM nào của riêng nó để gắn sự kiện.
+ */
+const hovered = ref(false)
+
+provide<ChartContext>(CHART_CONTEXT_KEY, {
+  get config() {
+    return props.config
+  },
+  colorOf,
+  labelOf,
+  hovered,
+})
+</script>
+
+<template>
+  <!--
+    Chiều cao đặt ở thẻ bọc này. Unovis tự tiêm stylesheet KHÔNG nằm trong
+    cascade layer, nên nó thắng utility của Tailwind bất kể specificity — đúng
+    cái bẫy mà `vue-echarts` từng gây ra. Cứ để container giữ kích thước và
+    Unovis đo theo nó thì không đụng độ.
+  -->
+  <div
+    :class="cn('ui-chart flex h-64 w-full min-w-0 flex-col text-xs', props.class)"
+    :style="styleVars"
+    @pointerenter="hovered = true"
+    @pointerleave="hovered = false"
+  >
+    <slot />
+  </div>
+</template>

package/src/components/chart/ChartCrosshair.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts" generic="T extends Record<string, unknown>">
+import type { ChartTooltipOptions, ChartTooltipRow, ChartValueFormatter } from './types'
+import { VisCrosshair, VisTooltip } from '@unovis/vue'
+import { computed, inject } from 'vue'
+import { formatChartValue, renderTooltip } from './tooltip'
+import { CHART_CONTEXT_KEY } from './types'
+
+const props = defineProps<{
+  /** Khoá làm nhãn trục hoành — cũng là tiêu đề của tooltip. */
+  index: Extract<keyof T, string>
+  /** Các chuỗi cần liệt kê, theo đúng thứ tự vẽ. */
+  categories: Extract<keyof T, string>[]
+  /** Chuỗi đang bị legend tắt — vẫn vẽ mờ nhưng không hiện trong tooltip. */
+  hidden?: string[]
+  colorOf: (key: string) => string
+  labelOf: (key: string) => string
+  valueFormatter?: ChartValueFormatter
+  options?: ChartTooltipOptions
+  /** Ghim tooltip mở sẵn ở điểm thứ mấy khi con trỏ chưa vào khung. */
+  defaultIndex?: number
+  /** Vạch dóng và chấm bám. Vạch do ChartContainer giấu, chấm thì ở đây. @default true */
+  showCursor?: boolean
+}>()
+
+const chart = inject(CHART_CONTEXT_KEY, undefined)
+
+/**
+ * `forceShowAt` của Unovis nhận toạ độ trong KHÔNG GIAN DỮ LIỆU, mà trục hoành
+ * của bộ này chạy theo chỉ số hàng — nên truyền thẳng `defaultIndex` là đúng.
+ *
+ * Phải NHẢ ra khi con trỏ vào khung, không thì tooltip đứng im: `_render` của
+ * Crosshair đọc `forceShowAt` TRƯỚC vị trí chuột, đặt sẵn là rê chuột không
+ * nhúc nhích. Bỏ chuột ra thì nó quay lại điểm ghim — đúng cách Recharts xử lý
+ * `defaultIndex`.
+ */
+const forceShowAt = computed(() => (chart?.hovered.value ? undefined : props.defaultIndex))
+
+function template(d: T): string {
+  const format = props.valueFormatter
+  const rows: ChartTooltipRow[] = props.categories
+    .filter(key => !props.hidden?.includes(key))
+    .map((key) => {
+      const raw = Number(d[key])
+      return {
+        key,
+        label: props.labelOf(key),
+        color: props.colorOf(key),
+        value: format ? format(raw, key) : formatChartValue(raw),
+        raw,
+      }
+    })
+
+  // `labelKey` trỏ vào một khoá trong `config` chứ không phải một cột dữ liệu:
+  // tiêu đề khi đó là một nhãn CỐ ĐỊNH cho cả biểu đồ ("Activities"), không đổi
+  // theo điểm đang rê. Vẫn cho `labelFormatter` chạy tiếp bên trong `renderTooltip`.
+  const title = props.options?.labelKey
+    ? props.labelOf(props.options.labelKey)
+    : String(d[props.index] ?? '')
+
+  return renderTooltip(title, rows, props.options ?? {})
+}
+
+/** Màu của chấm tròn bám trên từng đường, khớp thứ tự với `categories`. */
+function color(_d: unknown, i: number): string {
+  return props.colorOf(props.categories[i] ?? '')
+}
+</script>
+
+<template>
+  <VisTooltip :horizontal-shift="20" :vertical-shift="20" />
+  <!--
+    HAI prop dưới đây phải viết camelCase, KHÔNG được gạch nối. `VisCrosshair`
+    của @unovis/vue 1.6.7 là component DUY NHẤT không khai `props` (mọi wrapper
+    khác đều có), nên Vue đẩy tất cả xuống `attrs` và giữ nguyên tên gạch nối;
+    `useForwardProps` thì camel-hoá từ danh sách props — vốn rỗng — nên config
+    nhận được `forceShowAt: undefined` cạnh `'force-show-at': 1`. Không lỗi,
+    không cảnh báo, prop chỉ đơn giản là không có tác dụng.
+
+    `visibilityThreshold: 0` khi có điểm ghim: mặc định Unovis đòi khung lộ ra ít
+    nhất 35% viewport, mà nó KHÔNG theo dõi cuộn trang — ô nằm dưới màn hình lúc
+    mount sẽ không bao giờ vẽ tooltip, kể cả sau khi cuộn tới.
+  -->
+  <!-- eslint-disable vue/attribute-hyphenation -->
+  <VisCrosshair
+    :template="template"
+    :color="color"
+    :forceShowAt="forceShowAt"
+    :circleRadius="props.showCursor === false ? 0 : undefined"
+    :visibilityThreshold="props.defaultIndex === undefined ? undefined : 0"
+  />
+  <!-- eslint-enable vue/attribute-hyphenation -->
+</template>

package/src/components/chart/ChartLegend.vue

@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import type { ClassProps } from '../../lib/types'
+import { computed, inject } from 'vue'
+import { cn } from '../../lib/utils'
+import { CHART_CONTEXT_KEY } from './types'
+
+/**
+ * Legend viết bằng HTML thường, KHÔNG dùng `VisBulletLegend`.
+ *
+ * shadcn-vue để Unovis render legend rồi sau khi mount mới `querySelector` và
+ * nhét class của Button vào từng mục. Cách đó phụ thuộc vào class nội bộ của
+ * thư viện và chạy lệch một nhịp sau khi vẽ. Tự render thì markup nằm trong tay
+ * mình: đúng bố cục shadcn, có chỗ cho icon, và bấm để ẩn/hiện chuỗi.
+ */
+const props = defineProps<ClassProps & {
+  /** Các chuỗi hiện trong legend, theo thứ tự vẽ. */
+  categories: string[]
+  /** Chuỗi đang bị tắt. */
+  hidden?: string[]
+  /** Cho bấm vào mục để ẩn/hiện chuỗi. @default false */
+  interactive?: boolean
+}>()
+
+const emit = defineEmits<{
+  toggle: [key: string]
+}>()
+
+const chart = inject(CHART_CONTEXT_KEY)
+
+const items = computed(() => props.categories.map(key => ({
+  key,
+  label: chart?.labelOf(key) ?? key,
+  color: chart?.colorOf(key) ?? 'transparent',
+  icon: chart?.config[key]?.icon,
+  inactive: props.hidden?.includes(key) ?? false,
+})))
+</script>
+
+<template>
+  <div :class="cn('flex flex-wrap items-center justify-center gap-4 pt-3', props.class)">
+    <component
+      :is="props.interactive ? 'button' : 'div'"
+      v-for="item in items"
+      :key="item.key"
+      :type="props.interactive ? 'button' : undefined"
+      :aria-pressed="props.interactive ? !item.inactive : undefined"
+      :class="cn(
+        'flex items-center gap-1.5 text-xs text-muted-foreground transition-opacity',
+        props.interactive && 'cursor-pointer hover:opacity-80',
+        item.inactive && 'opacity-40',
+      )"
+      @click="props.interactive && emit('toggle', item.key)"
+    >
+      <component :is="item.icon" v-if="item.icon" class="size-3 shrink-0" />
+      <span
+        v-else
+        class="size-2 shrink-0 rounded-[2px]"
+        :style="{ background: item.color }"
+      />
+      {{ item.label }}
+    </component>
+  </div>
+</template>