@vestow/vue 0.1.0

package/src/variants/components/timeline.ts

@@ -0,0 +1,45 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+
+/**
+ * Dòng thời gian: nhật ký hoạt động, lịch sử đơn hàng, các bước đã chạy.
+ *
+ * P cho đặt nội dung ở **cả hai** phía đường kẻ (`align="alternate"`). Ở đây bỏ
+ * hẳn kiểu đó: nội dung so le hai bên đọc theo hình zíc zắc, mà nhật ký quản trị
+ * thì người ta quét dọc bằng mắt. Chỉ giữ một cột nội dung.
+ */
+export const timelineVariants = cva('flex w-full flex-col', {
+  variants: {
+    size: {
+      sm: 'gap-0',
+      default: 'gap-0',
+    },
+  },
+  defaultVariants: { size: 'default' },
+})
+
+/** Chấm mốc. Màu mang NGHĨA nên đi theo bộ variant chung của repo. */
+export const timelineMarkerVariants = cva(
+  'grid shrink-0 place-items-center rounded-full border-2 bg-background [&_svg]:size-3',
+  {
+    variants: {
+      variant: {
+        default: 'border-border text-muted-foreground',
+        primary: 'border-primary bg-primary text-primary-foreground',
+        success: 'border-success bg-success text-success-foreground',
+        warning: 'border-warning bg-warning text-warning-foreground',
+        destructive: 'border-destructive bg-destructive text-destructive-foreground',
+        info: 'border-info bg-info text-info-foreground',
+      },
+      size: {
+        sm: 'size-4',
+        default: 'size-6',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'default' },
+  },
+)
+
+export type TimelineVariants = VariantProps<typeof timelineVariants>
+
+export type TimelineMarkerVariants = VariantProps<typeof timelineMarkerVariants>

package/src/variants/components/toggle.ts

@@ -0,0 +1,58 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+import { focusRing } from '../lib/focus'
+
+/**
+ * Nút giữ trạng thái bật/tắt. Thang cỡ lấy **đúng** của Button (24 / 28 / 32 /
+ * 36px, kèm bốn cỡ vuông) chứ không khai riêng: toggle với button hay đứng cùng
+ * một thanh công cụ, lệch chiều cao là thấy ngay.
+ *
+ * Hai `variant`:
+ * - `ghost` — không viền, chỉ đổi nền khi bật. Dùng trong thanh công cụ dày đặc.
+ * - `outline` — có viền, đọc ra như một nút thật. Dùng khi nó đứng một mình.
+ *
+ * Trạng thái bật đọc từ `data-state=on` của reka, không phải từ prop.
+ */
+export const toggleVariants = cva(
+  [
+    'ui-button inline-flex items-center justify-center gap-1.5 whitespace-nowrap rounded-lg',
+    'text-sm font-medium',
+    'transition-[color,background-color,border-color,opacity,transform] duration-(--ui-control-duration)',
+    'active:scale-[0.97] active:duration-(--ui-control-duration-press) motion-reduce:active:scale-100',
+    focusRing,
+    'disabled:pointer-events-none disabled:opacity-50',
+    '[&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+  ],
+  {
+    variants: {
+      variant: {
+        ghost: [
+          'bg-transparent hover:bg-accent hover:text-accent-foreground',
+          'data-[state=on]:bg-accent data-[state=on]:text-accent-foreground',
+        ],
+        outline: [
+          'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+          'data-[state=on]:bg-accent data-[state=on]:text-accent-foreground',
+        ],
+      },
+
+      size: {
+        'xs': 'h-(--ui-control-height-xs) gap-1 rounded-md px-(--ui-control-padding-x-xs) text-xs [&_svg]:size-3',
+        'sm': 'h-(--ui-control-height-sm) gap-1 rounded-md px-(--ui-control-padding-x) text-[0.8rem]',
+        'default': 'h-(--ui-control-height-md) px-(--ui-control-padding-x)',
+        'lg': 'h-(--ui-control-height-lg) px-(--ui-control-padding-x)',
+        'icon-xs': 'size-(--ui-control-height-xs) rounded-md [&_svg]:size-3',
+        'icon-sm': 'size-(--ui-control-height-sm) rounded-md',
+        'icon': 'size-(--ui-control-height-md)',
+        'icon-lg': 'size-(--ui-control-height-lg)',
+      },
+    },
+
+    defaultVariants: {
+      variant: 'ghost',
+      size: 'default',
+    },
+  },
+)
+
+export type ToggleVariants = VariantProps<typeof toggleVariants>

package/src/variants/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Barrel cho bên nào muốn lấy cả bộ một lần.
+ *
+ * Bên trong repo thì nhập theo subpath (`src/variants/components/button`): bộ dò
+ * token của trang docs đi theo import để biết component nào đọc bảng nào, và
+ * một file barrel sẽ làm cả 18 bảng dính vào nhau — trang Select mượn
+ * `badgeVariants` cho một cái chip sẽ kéo luôn năm màu trạng thái vào bảng.
+ */
+
+export * from './components/accordion'
+export * from './components/alert'
+export * from './components/badge'
+export * from './components/button'
+export * from './components/button-group'
+export * from './components/checkbox'
+export * from './components/code-block'
+export * from './components/dialog'
+export * from './components/empty'
+export * from './components/field'
+export * from './components/float-label'
+export * from './components/input-group'
+export * from './components/input-password'
+export * from './components/kbd'
+export * from './components/picker-trigger'
+export * from './components/radio-group'
+export * from './components/sheet'
+export * from './components/sidebar'
+export * from './components/slider'
+export * from './components/timeline'
+export * from './components/toggle'
+export * from './lib/focus'
+export * from './lib/highlight'
+export * from './lib/menu-styles'
+export * from './lib/platform'
+export * from './lib/utils'

package/src/variants/lib/chart/polar.ts

@@ -0,0 +1,139 @@
+/**
+ * Hình học cực, dùng chung cho RadialChart và RadarChart.
+ *
+ * Hai loại này Unovis KHÔNG có (`nested-donut` là sunburst phân cấp, không phải
+ * vòng đồng tâm; radar thì không có gì cả), nên vẽ tay bằng SVG. Đổi lại được
+ * một thứ: mọi màu là `var(--color-…)` đặt thẳng vào thuộc tính SVG, nên vẫn đi
+ * theo token y hệt phần còn lại — không phải uốn theo API của thư viện.
+ *
+ * Quy ước góc: 0 ở đỉnh (12 giờ), chạy THEO chiều kim đồng hồ, đơn vị độ.
+ * Chọn vậy vì cả radial lẫn radar đều đọc từ đỉnh xuống, còn `Math.cos/sin`
+ * mặc định lấy 0 ở hướng 3 giờ và chạy ngược kim đồng hồ.
+ */
+
+export interface Point {
+  x: number
+  y: number
+}
+
+/** Đổi (góc, bán kính) sang toạ độ Descartes quanh tâm. */
+export function polarToCartesian(cx: number, cy: number, radius: number, angleDeg: number): Point {
+  const rad = ((angleDeg - 90) * Math.PI) / 180
+  return { x: cx + radius * Math.cos(rad), y: cy + radius * Math.sin(rad) }
+}
+
+/**
+ * Path của một cung VÀNH (có bề dày), tức hình quạt bị khoét ruột.
+ *
+ * Cung tròn 360° phải tách làm HAI cung 180°: cờ `large-arc-flag` của SVG chỉ
+ * phân biệt được cung lớn hay nhỏ, nên một cung đúng 360° có điểm đầu trùng
+ * điểm cuối và trình duyệt vẽ ra… không gì cả.
+ */
+export function annularArcPath(
+  cx: number,
+  cy: number,
+  outerRadius: number,
+  innerRadius: number,
+  startAngle: number,
+  endAngle: number,
+): string {
+  const sweep = Math.abs(endAngle - startAngle)
+  if (sweep < 0.01)
+    return ''
+
+  if (sweep >= 359.99) {
+    const mid = startAngle + 180
+    return `${annularArcPath(cx, cy, outerRadius, innerRadius, startAngle, mid)} ${annularArcPath(cx, cy, outerRadius, innerRadius, mid, startAngle + 359.98)}`
+  }
+
+  const largeArc = sweep > 180 ? 1 : 0
+  const o1 = polarToCartesian(cx, cy, outerRadius, startAngle)
+  const o2 = polarToCartesian(cx, cy, outerRadius, endAngle)
+  const i2 = polarToCartesian(cx, cy, innerRadius, endAngle)
+  const i1 = polarToCartesian(cx, cy, innerRadius, startAngle)
+
+  return [
+    `M ${o1.x} ${o1.y}`,
+    `A ${outerRadius} ${outerRadius} 0 ${largeArc} 1 ${o2.x} ${o2.y}`,
+    `L ${i2.x} ${i2.y}`,
+    `A ${innerRadius} ${innerRadius} 0 ${largeArc} 0 ${i1.x} ${i1.y}`,
+    'Z',
+  ].join(' ')
+}
+
+/** Các đỉnh của một đa giác đều `sides` cạnh, đỉnh đầu ở 12 giờ. */
+export function polygonPoints(cx: number, cy: number, radius: number, sides: number): Point[] {
+  return Array.from({ length: sides }, (_, i) => polarToCartesian(cx, cy, radius, (360 / sides) * i))
+}
+
+/** Chuỗi `points` cho `<polygon>`. */
+export function toPointsAttr(points: Point[]): string {
+  return points.map(p => `${p.x.toFixed(2)},${p.y.toFixed(2)}`).join(' ')
+}
+
+/**
+ * Khung bao của một cung vành, tính đúng chứ không lấy cả hình vuông.
+ *
+ * Cần nó vì một cung nửa vòng chỉ chiếm nửa khung: để nguyên khung vuông thì
+ * biểu đồ bán nguyệt bị dạt lên trên và bỏ trống nửa dưới. Điểm cực trị của
+ * cung tròn chỉ rơi vào hai đầu mút HOẶC các mốc 0/90/180/270 nằm trong khoảng,
+ * nên chỉ cần thử chừng ấy điểm.
+ */
+export function arcBounds(
+  cx: number,
+  cy: number,
+  outerRadius: number,
+  innerRadius: number,
+  startAngle: number,
+  endAngle: number,
+  includeCenter = false,
+): { x: number, y: number, width: number, height: number } {
+  const lo = Math.min(startAngle, endAngle)
+  const hi = Math.max(startAngle, endAngle)
+
+  const angles = [lo, hi]
+  for (let a = Math.ceil(lo / 90) * 90; a <= hi; a += 90)
+    angles.push(a)
+
+  const points: Point[] = []
+  for (const a of angles) {
+    points.push(polarToCartesian(cx, cy, outerRadius, a))
+    points.push(polarToCartesian(cx, cy, innerRadius, a))
+  }
+  if (includeCenter)
+    points.push({ x: cx, y: cy })
+
+  const xs = points.map(p => p.x)
+  const ys = points.map(p => p.y)
+  const minX = Math.min(...xs)
+  const minY = Math.min(...ys)
+  return { x: minX, y: minY, width: Math.max(...xs) - minX, height: Math.max(...ys) - minY }
+}
+
+/**
+ * Path của một cung MỞ (chỉ đường, không khép kín) chạy trên bán kính `radius`.
+ *
+ * Dùng cho radial bar: thay vì tô một hình quạt vành, ta VẼ NÉT dày bằng đúng
+ * bề dày vành dọc theo đường tâm của nó. Nhờ vậy `stroke-linecap="round"` cho ra
+ * hai đầu cung bo tròn miễn phí — thứ mà tô hình quạt phải dựng path phức tạp
+ * mới có (Recharts gọi là `cornerRadius`).
+ *
+ * Cung 360° vẫn phải tách đôi, cùng lý do như `annularArcPath`.
+ */
+export function arcPath(cx: number, cy: number, radius: number, startAngle: number, endAngle: number): string {
+  const sweep = Math.abs(endAngle - startAngle)
+  if (sweep < 0.01)
+    return ''
+
+  if (sweep >= 359.99) {
+    const mid = startAngle + 180
+    const a = polarToCartesian(cx, cy, radius, startAngle)
+    const b = polarToCartesian(cx, cy, radius, mid)
+    return `M ${a.x} ${a.y} A ${radius} ${radius} 0 0 1 ${b.x} ${b.y} A ${radius} ${radius} 0 0 1 ${a.x} ${a.y}`
+  }
+
+  const largeArc = sweep > 180 ? 1 : 0
+  const from = polarToCartesian(cx, cy, radius, startAngle)
+  const to = polarToCartesian(cx, cy, radius, endAngle)
+  return `M ${from.x} ${from.y} A ${radius} ${radius} 0 ${largeArc} 1 ${to.x} ${to.y}`
+}

package/src/variants/lib/chart/tooltip.ts

@@ -0,0 +1,101 @@
+import type { ChartTooltipOptions, ChartTooltipRow } from './types'
+
+/**
+ * Unovis nhận `template` trả về CHUỖI HTML, không nhận component của framework
+ * nào — nên hàm này dùng chung được cho cả hai cây, và ở đây là chỗ của nó.
+ *
+ * shadcn-vue giải bài này bằng `createApp(ChartTooltip).mount(div)` cho từng
+ * điểm dữ liệu rồi cache `innerHTML` vào một WeakMap. Cách đó có hai chỗ hỏng:
+ * mount hẳn một app mỗi lần rê chuột là quá nặng, và HTML đã cache thì KHÔNG
+ * đổi theo theme nữa — đổi sang chế độ tối xong tooltip vẫn giữ màu cũ.
+ *
+ * Ở đây chỉ ghép chuỗi. Vì nó là DOM thật trong trang nên utility Tailwind và
+ * token vẫn áp bình thường, và màu lấy qua `var(--color-<key>)` nên đổi theme
+ * hay đổi bảng màu là tooltip đổi theo ngay, không có gì để mà cũ.
+ */
+
+/** Chặn nhãn do người dùng truyền vào phá cấu trúc HTML. */
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+/**
+ * Ba kiểu chỉ báo của shadcn. `dashed` cố ý KHÔNG có nền — nó là hai nét gạch
+ * nên phải để trong suốt, nếu tô nền thì nhìn hệt `line` bị dày lên.
+ */
+const INDICATOR_CLASS: Record<NonNullable<ChartTooltipOptions['indicator']>, string> = {
+  dot: 'size-2.5 rounded-[2px]',
+  line: 'h-3 w-1 rounded-[2px]',
+  dashed: 'h-3 w-0 border-[1.5px] border-dashed',
+}
+
+function indicatorHtml(color: string, options: ChartTooltipOptions): string {
+  if (options.hideIndicator)
+    return ''
+  const kind = options.indicator ?? 'dot'
+  const style = kind === 'dashed'
+    ? `border-color:${color}`
+    : `background:${color}`
+  return `<div class="shrink-0 ${INDICATOR_CLASS[kind]}" style="${style}"></div>`
+}
+
+/**
+ * Ghép hộp tooltip theo đúng bố cục của shadcn: dòng tiêu đề đậm, dưới là từng
+ * chuỗi với chỉ báo màu, tên mờ bên trái và số bên phải.
+ *
+ * Số dùng `tabular-nums` + `font-mono` để cột giá trị không nhảy khi rê chuột
+ * qua các điểm có độ dài chữ số khác nhau.
+ */
+export function renderTooltip(
+  title: string,
+  rows: ChartTooltipRow[],
+  options: ChartTooltipOptions = {},
+): string {
+  const heading = options.labelFormatter ? options.labelFormatter(title) : title
+  const head = heading && !options.hideLabel
+    ? `<div class="font-medium text-popover-foreground">${escapeHtml(heading)}</div>`
+    : ''
+
+  const body = rows.map(row => `
+    <div class="flex w-full items-center gap-2">
+      ${indicatorHtml(row.color, options)}
+      <div class="flex flex-1 items-center justify-between gap-4 leading-none">
+        <span class="text-muted-foreground">${escapeHtml(row.label)}</span>
+        <span class="font-mono font-medium tabular-nums text-foreground">${escapeHtml(row.value)}</span>
+      </div>
+    </div>`).join('')
+
+  // Dòng tổng ngăn bằng một đường kẻ, và KHÔNG có chỉ báo màu: nó không phải
+  // một chuỗi, gắn ô màu vào là đọc nhầm thành chuỗi thứ n+1.
+  const totalRow = options.showTotal && rows.length > 1
+    ? `<div class="mt-1.5 flex items-center justify-between gap-4 border-t border-border/50 pt-1.5">
+        <span class="text-muted-foreground">${escapeHtml(options.totalLabel ?? 'Total')}</span>
+        <span class="font-mono font-medium tabular-nums text-foreground">${escapeHtml(sumOf(rows))}</span>
+      </div>`
+    : ''
+
+  return `<div class="grid min-w-[8rem] items-start gap-1.5 rounded-lg border border-border/50 bg-popover px-2.5 py-1.5 text-xs shadow-xl">
+    ${head}
+    <div class="grid gap-1.5">${body}</div>
+    ${totalRow}
+  </div>`
+}
+
+/**
+ * Tổng của các dòng. Cộng lại từ CHUỖI đã định dạng thì sai, nên mỗi dòng giữ
+ * thêm `raw` để cộng; thiếu `raw` thì bỏ qua dòng đó.
+ */
+function sumOf(rows: ChartTooltipRow[]): string {
+  const total = rows.reduce((sum, r) => sum + (r.raw ?? 0), 0)
+  return formatChartValue(total)
+}
+
+/** Định dạng số mặc định: phân nhóm hàng nghìn theo locale của trình duyệt. */
+export function formatChartValue(value: number): string {
+  return Number.isFinite(value) ? value.toLocaleString() : '—'
+}

package/src/variants/lib/chart/types.ts

@@ -0,0 +1,172 @@
+/**
+ * Kiểu dùng chung cho cả bộ biểu đồ — KHÔNG dính framework nào.
+ *
+ * Nằm ở đây vì nó mô tả DỮ LIỆU và các tuỳ chọn hiển thị, mà cả hai cây đọc
+ * đúng một hình dạng: `ChartConfig` của shadcn, cùng prop của Recharts mà bộ
+ * này soi theo. Hai bản là hai cơ hội để một bên thêm prop rồi bên kia không
+ * biết.
+ *
+ * Phần CÓ dính framework — icon của legend, và context mà `ChartContainer`
+ * chuyền xuống — nằm ở `types.ts` của từng cây.
+ */
+
+/**
+ * Mô tả một chuỗi số liệu: nhãn, màu, icon.
+ *
+ * Đây là `ChartConfig` của shadcn, giữ nguyên hình dạng để người đã quen bên đó
+ * không phải học lại. Khoá của object chính là khoá trong dữ liệu, nên chỉ khai
+ * một lần là legend, tooltip và màu vẽ đều dùng chung.
+ */
+export interface ChartSeriesConfig {
+  /** Nhãn người dùng nhìn thấy trong legend và tooltip. */
+  label: string
+  /**
+   * Màu của chuỗi. Bỏ trống thì lấy `--chart-1`…`--chart-5` theo đúng thứ tự
+   * khai báo trong config, quay vòng khi có hơn năm chuỗi.
+   */
+  color?: string
+  /**
+   * Icon đứng trước nhãn trong legend.
+   *
+   * Kiểu để `unknown` ở tầng dùng chung: bên Vue nó là một `Component`, bên
+   * React là một `ComponentType` — mỗi cây thu hẹp lại trong `ChartConfig` của
+   * chính nó. Đây là trường DUY NHẤT của bộ type này dính tới framework.
+   */
+  icon?: unknown
+}
+
+/** Khoá của object là khoá trong dữ liệu. */
+export type ChartConfig = Record<string, ChartSeriesConfig>
+
+/**
+ * Lề trong của khung vẽ.
+ *
+ * Khai lại ở đây chứ không import `Spacing` của `@unovis/ts`: `src/variants`
+ * không được phụ thuộc một thư viện biểu đồ — nó là tầng không biết framework
+ * VÀ không biết thư viện vẽ. Hình dạng trùng khít nên vẫn truyền thẳng xuống
+ * Unovis được nhờ structural typing.
+ */
+export interface ChartSpacing {
+  top?: number
+  right?: number
+  bottom?: number
+  left?: number
+}
+
+/** Hàm định dạng nhãn trục, nhận đúng chữ ký `tickFormat` của Unovis. */
+export type ChartTickFormatter = (tick: number | Date, i: number, ticks: number[] | Date[]) => string
+
+/** Định dạng giá trị hiện trong tooltip và legend. */
+export type ChartValueFormatter = (value: number, key: string) => string
+
+/**
+ * Kiểu nối điểm. Rút gọn từ `CurveType` của Unovis xuống bốn lựa chọn mà gallery
+ * của shadcn thật sự dùng — bày cả mười tám kiểu chỉ tổ làm người đọc phân vân.
+ *
+ * `natural` là kiểu shadcn dùng nhiều nhất (8 ô area, 6 ô line); `monotone` chỉ
+ * ở `line-multiple` và `line-interactive`. Hai kiểu này nhìn gần giống nhau —
+ * khác ở chỗ `natural` (spline tự nhiên) được phép vọt qua giá trị điểm dữ liệu,
+ * còn `monotone` thì không bao giờ.
+ */
+export type ChartCurve = 'monotone' | 'natural' | 'linear' | 'step'
+
+/**
+ * Nhãn in trên cột / lát / điểm lấy nội dung ở đâu: con SỐ, hay TÊN hạng mục.
+ *
+ * `'name'` tra qua `config` trước — nhờ vậy dữ liệu ghi `chrome` mà nhãn hiện
+ * ra `Chrome`, đúng cách shadcn dùng `formatter` của `LabelList`. Không có
+ * trong config thì in nguyên giá trị.
+ */
+export type ChartLabelKey = 'value' | 'name'
+
+/** Prop dùng chung của mọi biểu đồ trục XY trong bộ này. */
+export interface ChartBaseProps<
+  T extends Record<string, unknown>,
+  TConfig extends Record<string, ChartSeriesConfig> = ChartConfig,
+> {
+  /** Dữ liệu nguồn, mỗi phần tử là một điểm trên trục hoành. */
+  data: T[]
+  /** Khoá dùng làm nhãn trục hoành, ví dụ `'month'`. */
+  index: Extract<keyof T, string>
+  /**
+   * Các chuỗi cần vẽ. Bỏ trống thì vẽ đúng những khoá có trong `config`, theo
+   * thứ tự khai báo — nên thường không phải truyền.
+   */
+  categories?: Extract<keyof T, string>[]
+  /** Nhãn, màu và icon của từng chuỗi. */
+  config: TConfig
+  /** Lề trong của khung vẽ. */
+  margin?: ChartSpacing
+  /** Định dạng nhãn trục hoành. */
+  xFormatter?: ChartTickFormatter
+  /** Định dạng nhãn trục tung. */
+  yFormatter?: ChartTickFormatter
+  /** Định dạng giá trị trong tooltip. Mặc định là `toLocaleString('vi-VN')`. */
+  valueFormatter?: ChartValueFormatter
+  /** Tuỳ chọn hiển thị của tooltip: kiểu chỉ báo, ẩn nhãn, ẩn chỉ báo. */
+  tooltip?: ChartTooltipOptions
+  /** @default true */
+  showXAxis?: boolean
+  /** @default true */
+  showYAxis?: boolean
+  /** @default true */
+  showTooltip?: boolean
+  /** @default false — shadcn để legend tắt sẵn, bật khi có từ hai chuỗi trở lên. */
+  showLegend?: boolean
+  /** Đường kẻ ngang nền. @default true */
+  showGridLine?: boolean
+  /**
+   * Vạch dóng dọc và chấm bám trên chuỗi khi rê chuột.
+   *
+   * shadcn tắt nó ở 58/65 ô (`cursor={false}`) — nhưng đó là quy ước TRÌNH BÀY của
+   * trang gallery, không phải mặc định hợp lý cho một component: mặc định của
+   * Recharts cũng là bật, họ phải khai tắt từng ô. Giữ `true`, ai cần thì tắt.
+   * @default true
+   */
+  showCursor?: boolean
+  /**
+   * Ghim tooltip mở sẵn ở điểm dữ liệu thứ mấy, không cần rê chuột.
+   *
+   * Dành cho trang tài liệu: cả chín biến thể ở trang Tooltips của shadcn đều
+   * khai `defaultIndex={1}`, vì tooltip là THỨ ĐANG ĐƯỢC TRƯNG BÀY — bắt người
+   * đọc rê chuột lên từng ô mới thấy thì xem như không trưng bày gì.
+   *
+   * Rê chuột lên vẫn đè được; bỏ chuột ra thì nó quay về điểm đã ghim.
+   */
+  defaultIndex?: number
+}
+
+/** Tuỳ chọn hiển thị của tooltip, theo đúng bộ prop của shadcn. */
+export interface ChartTooltipOptions {
+  /** Kiểu chỉ báo màu đứng trước tên chuỗi. @default 'dot' */
+  indicator?: 'dot' | 'line' | 'dashed'
+  /** Bỏ dòng tiêu đề (nhãn trục hoành). */
+  hideLabel?: boolean
+  /** Bỏ hẳn ô/vạch màu, chỉ còn tên và số. */
+  hideIndicator?: boolean
+  /**
+   * Lấy dòng tiêu đề từ `config[labelKey].label` thay vì từ nhãn trục hoành.
+   *
+   * Khoá này KHÔNG phải một chuỗi số liệu — nó chỉ có `label`. Vì `categories`
+   * mặc định là mọi khoá của `config`, biểu đồ dùng nó phải khai `categories`
+   * tường minh, nếu không sẽ mọc thêm một chuỗi rỗng.
+   */
+  labelKey?: string
+  /** Đổi cách viết dòng tiêu đề, ví dụ đổi 'January' thành 'Tháng 1'. */
+  labelFormatter?: (label: string) => string
+  /** Thêm một dòng tổng ở cuối. Chỉ có nghĩa khi tooltip liệt kê nhiều chuỗi. */
+  showTotal?: boolean
+  /** Nhãn của dòng tổng. @default 'Total' */
+  totalLabel?: string
+}
+
+/** Một dòng trong tooltip, đã resolve xong nhãn và màu. */
+export interface ChartTooltipRow {
+  key: string
+  label: string
+  color: string
+  /** Đã định dạng, dùng để hiển thị. */
+  value: string
+  /** Số thô, dùng để cộng dòng tổng. */
+  raw?: number
+}

package/src/variants/lib/chart/xy-label.ts

@@ -0,0 +1,42 @@
+import { escapeHtml } from './tooltip'
+
+/**
+ * Đẩy nhãn của `VisXYLabels` LỆCH khỏi điểm dữ liệu, bằng `<tspan>`.
+ *
+ * `VisXYLabels` KHÔNG có tuỳ chọn lệch theo pixel: `x`/`y` là toạ độ trong
+ * không gian dữ liệu, và chữ luôn nằm ĐÚNG TÂM điểm đó
+ * (`text-anchor: middle; dominant-baseline: central`, đặt bằng inline style nên
+ * CSS thường không đè được). Nhưng shadcn thì đặt nhãn cách cột 12px phía trên,
+ * hoặc 8px ngoài đầu cột ngang — tức phải lệch theo PIXEL, thứ không quy được
+ * về đơn vị dữ liệu nếu không biết thang đo.
+ *
+ * Lối ra nằm ở chỗ Unovis gán nội dung nhãn bằng `text.html(labelText)`, tức
+ * chuỗi trả về được nhét thẳng vào `<text>` dưới dạng markup. Ba điều khiến
+ * cách này chạy đúng, cả ba đều là SVG chuẩn chứ không phải mẹo:
+ *
+ * 1. `<tspan y="-12">` dời cả chữ lên 12px — đã ĐO: tâm chữ lệch đúng 12px, và
+ *    `dominant-baseline: central` của thẻ cha vẫn được kế thừa.
+ * 2. `text-anchor` khai TRÊN CHÍNH tspan thắng giá trị kế thừa từ inline style
+ *    của `<text>` — thuộc tính khai trực tiếp luôn hơn kế thừa.
+ * 3. Nhưng `text-anchor` chỉ có hiệu lực ở ĐẦU một text chunk, mà chunk mới chỉ
+ *    mở ra khi có toạ độ TUYỆT ĐỐI. Vì vậy luôn phát cả `x` lẫn `y`, kể cả khi
+ *    bằng 0 — thiếu `x` là anchor bị bỏ qua và chữ vẫn nằm giữa.
+ *
+ * Kèm một hệ quả phải nhớ: `getLabelRenderProps` ước lượng bề rộng nền theo
+ * `labelText.length`, mà chuỗi giờ có cả markup nên con số đó vô nghĩa. Không
+ * sao vì nền để `none`, NHƯNG nó làm phép gom cụm (`clustering`) tính sai —
+ * luôn đặt `:clustering="false"` ở mọi chỗ dùng hàm này.
+ */
+export interface XYLabelOffset {
+  /** Lệch ngang, pixel. Dương là sang phải. */
+  dx?: number
+  /** Lệch dọc, pixel. Âm là lên trên. */
+  dy?: number
+  /** Căn chữ so với điểm neo sau khi đã lệch. @default 'middle' */
+  anchor?: 'start' | 'middle' | 'end'
+}
+
+export function xyLabelHtml(text: string, offset: XYLabelOffset = {}): string {
+  const { dx = 0, dy = 0, anchor = 'middle' } = offset
+  return `<tspan x="${dx}" y="${dy}" text-anchor="${anchor}">${escapeHtml(text)}</tspan>`
+}

package/src/variants/lib/focus.ts

@@ -0,0 +1,66 @@
+/**
+ * Vòng focus dùng chung cho control NHẬP LIỆU.
+ *
+ * Tách ra một chỗ vì trước đây mười ba file cùng chép một chuỗi class, và
+ * chúng đã trôi khỏi nhau: có chỗ `ring-offset-1`, có chỗ `ring-offset-2`, có
+ * chỗ quên hẳn. Sửa một kiểu focus mà phải mở mười ba file thì kiểu gì cũng sót.
+ *
+ * Hình dạng (xem `--focus-ring` trong `tokens.css` để biết vì sao hai lớp):
+ *
+ * | trạng thái | viền | bóng |
+ * |---|---|---|
+ * | thường | `--input` | `shadow-xs` |
+ * | focus | `--ring` | hai lớp, sắc `--ring` |
+ * | không hợp lệ | `--destructive` | **không** — chỉ đổi viền |
+ * | không hợp lệ + focus | `--destructive` | hai lớp, sắc `--destructive` |
+ *
+ * Dòng cuối bảng là chỗ dễ làm sai nhất. Người dùng chỉ yêu cầu "invalid thì
+ * đổi viền thôi", nhưng đó là nói về trạng thái **tĩnh**; bỏ luôn cả quầng lúc
+ * đang focus thì field sai lại thành field khó thấy con trỏ đang ở đâu nhất.
+ *
+ * Vì sao `data-[invalid]:focus-visible:*` chắc chắn thắng `focus-visible:*`:
+ * biến thể ghép sinh ra selector có thêm một attribute selector, tức
+ * specificity (0,3,0) so với (0,2,0). Nó thắng nhờ **specificity**, không phải
+ * nhờ thứ tự trong file — nên không phụ thuộc vào cách Tailwind sắp xếp.
+ */
+
+/** Bỏ outline mặc định của trình duyệt. Luôn đi kèm một trong hai bộ dưới. */
+const noOutline = 'focus-visible:outline-none'
+
+/** Control mà chính nó nhận focus: input, textarea, trigger của select… */
+export const focusRing = [
+  noOutline,
+  'focus-visible:border-ring focus-visible:shadow-focus',
+].join(' ')
+
+/**
+ * Vỏ bọc quanh control thật: InputGroup, InputNumber, vùng thả của FileUpload.
+ * Focus nằm ở `<input>` bên trong nên vỏ phải bắt bằng `focus-within`, còn ô
+ * nhập bên trong thì bị lột sạch viền và vòng focus của nó.
+ */
+export const focusRingWithin = [
+  'focus-within:outline-none',
+  'focus-within:border-ring focus-within:shadow-focus',
+].join(' ')
+
+/** Trạng thái không hợp lệ, đọc từ `data-invalid` trên chính element. */
+export const invalidRing = [
+  'data-[invalid]:border-destructive',
+  'data-[invalid]:focus-visible:border-destructive data-[invalid]:focus-visible:shadow-focus-invalid',
+].join(' ')
+
+/** Bản `focus-within` của `invalidRing`, cho vỏ bọc. */
+export const invalidRingWithin = [
+  'data-[invalid]:border-destructive',
+  'data-[invalid]:focus-within:border-destructive data-[invalid]:focus-within:shadow-focus-invalid',
+].join(' ')
+
+/**
+ * Cho control không đọc được `data-invalid` từ DOM mà phải nhận qua prop —
+ * chủ yếu là các wrapper của reka, nơi thuộc tính không xuống tới element
+ * đang vẽ viền.
+ */
+export const invalidRingStatic = [
+  'border-destructive',
+  'focus-visible:border-destructive focus-visible:shadow-focus-invalid',
+].join(' ')