@squadbase/vantage 0.6.2-stg.3a2ba98 → 0.7.0-dev1.1197de7

package/registry/ui/data-table.tsx

@@ -1,6 +1,11 @@
 // Copied by `vantage add ui data-table`. This file is yours to edit.
+// Generated from @squadbase/squadkit registry/components/data-table.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
 /**
- * DataTable — a compound table over TanStack Table. `<DataTable>` owns the
+ * DataTablePreset — a table (toolbar, body, pagination) over TanStack Table.
+ *
+ * `DataTable` is the compound form: `<DataTable>` owns the
  * table instance and publishes it on context; the toolbar, body, pagination and
  * column-visibility parts read from that context, so a page composes only the
  * pieces it wants. `DataTablePreset` assembles the usual arrangement.
@@ -14,7 +19,9 @@ import {
   forwardRef,
   useCallback,
   useContext,
+  useEffect,
   useMemo,
+  useRef,
   useState,
   type HTMLAttributes,
   type ReactNode,
@@ -27,43 +34,375 @@ import {
   getPaginationRowModel,
   getSortedRowModel,
   useReactTable,
+  type Column,
   type ColumnDef,
   type ColumnFiltersState,
   type OnChangeFn,
   type PaginationState,
+  type RowData,
   type RowSelectionState,
   type SortingState,
   type Table as TanstackTable,
   type TableMeta,
   type VisibilityState,
 } from "@tanstack/react-table"
-import { ArrowDown, ArrowUp, ArrowUpDown, Columns3, Search } from "lucide-react"
-
 import {
-  Button,
-  Checkbox,
+  ArrowDown,
+  ArrowUp,
+  ArrowUpDown,
+  CircleCheck,
+  CircleX,
+  Columns3,
+  Download,
+  Minus,
+  Search,
+  TriangleAlert,
+  type LucideIcon,
+} from "lucide-react"
+
+import { Sparkline } from "@squadbase/vantage/components"
+import { toneForValue } from "@squadbase/vantage/components"
+import { EMPTY_VALUE, formatDate, formatValue, type DateStyle, type ValueFormat } from "@squadbase/vantage/components"
+import type { ChartThreshold, ChartTone } from "@squadbase/vantage/components"
+import { cn } from "@squadbase/vantage/ui"
+import { Button } from "@squadbase/vantage/ui"
+import { Checkbox } from "@squadbase/vantage/ui"
+import {
   DropdownMenu,
   DropdownMenuCheckboxItem,
   DropdownMenuContent,
   DropdownMenuTrigger,
-  Input,
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-  Table,
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow,
-  cn,
 } from "@squadbase/vantage/ui"
+import { Input } from "@squadbase/vantage/ui"
+import { Skeleton } from "@squadbase/vantage/ui"
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@squadbase/vantage/ui"
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@squadbase/vantage/ui"
+import { useSyncExternalStore } from "react"
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/locale.ts (internal to @squadbase/vantage) ---------- */
+
+/**
+ * The display language of the parts and the defaults that follow it.
+ *
+ * The language comes from `<html lang>`: a tag starting with `ja` reads Japanese, anything else English.
+ * Without a usable `lang` (missing, invalid, or no `document` — SSR, Node) the locale is `FALLBACK_LOCALE`
+ * (`en-US`). A `locale` passed explicitly (a prop, an argument) always wins.
+ *
+ * Parts read the locale through `useLocale` (`hooks/use-locale`) and pass it down; the pure helpers here
+ * and in `format` / `comparison` / `chart-*` take it as an argument and fall back to `documentLocale()`.
+ */
+
+/** The language of the built-in wording: Japanese or English. */
+type UiLanguage = "ja" | "en"
+
+/** The locale used when `<html lang>` gives none (and on the server). */
+const FALLBACK_LOCALE = "en-US"
+
+/** `"ja"` when `locale` starts with `ja` (`ja`, `ja-JP`), else `"en"`. A missing locale is `"en"`. */
+function uiLanguage(locale: string | null | undefined): UiLanguage {
+  return typeof locale === "string" && locale.trim().toLowerCase().startsWith("ja") ? "ja" : "en"
+}
+
+/** A BCP 47 tag in its canonical form (`en-gb` → `en-GB`), or `FALLBACK_LOCALE` when it is empty or invalid. */
+function normalizeLocale(tag: string | null | undefined): string {
+  const value = tag?.trim()
+  if (!value) return FALLBACK_LOCALE
+  try {
+    return Intl.getCanonicalLocales(value)[0] ?? FALLBACK_LOCALE
+  } catch {
+    return FALLBACK_LOCALE
+  }
+}
+
+/**
+ * The locale of the page: `document.documentElement.lang`, canonicalized. `FALLBACK_LOCALE` when it is empty or
+ * invalid, or there is no `document`. Parts read it through `useLocale`, never while rendering.
+ */
+function documentLocale(): string {
+  if (typeof document === "undefined") return FALLBACK_LOCALE
+  return normalizeLocale(document.documentElement?.getAttribute("lang"))
+}
+
+/** `locale` when given, else the page's locale (`documentLocale()`). */
+function resolveLocale(locale?: string | null): string {
+  return locale || documentLocale()
+}
+
+/** Picks the wording table of the locale's language. */
+function pickLocale<T>(table: { ja: T; en: T }, locale?: string | null): T {
+  return table[uiLanguage(resolveLocale(locale))]
+}
+
+/** The currency `format="currency"` uses without a `currency`: JPY for Japanese, USD otherwise. */
+function defaultCurrency(locale?: string | null): string {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? "JPY" : "USD"
+}
+
+/** The month a fiscal year starts in (1–12) when none is given: April for Japanese, January otherwise. */
+function defaultFiscalYearStartMonth(locale?: string | null): number {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? 4 : 1
+}
+
+/** A day of the week, 0 = Sunday … 6 = Saturday (the `Date#getDay` / date-fns numbering). */
+type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6
 
+/** Locales whose week starts on Sunday when the runtime has no week data. */
+const SUNDAY_FIRST = new Set(["en", "en-US", "en-CA"])
+
+/**
+ * The first day of the week: Monday for Japanese; otherwise the locale's convention from `Intl.Locale`
+ * (`en-US` Sunday, `en-GB` Monday). Without week data in the runtime: Sunday for `en` / `en-US` / `en-CA`,
+ * Monday for the rest.
+ */
+function weekStartsOn(locale?: string | null): WeekDay {
+  const tag = normalizeLocale(resolveLocale(locale))
+  if (uiLanguage(tag) === "ja") return 1
+  try {
+    const info = new Intl.Locale(tag) as Intl.Locale & {
+      getWeekInfo?: () => { firstDay: number }
+      weekInfo?: { firstDay: number }
+    }
+    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay
+    if (typeof firstDay === "number" && firstDay >= 1 && firstDay <= 7) return (firstDay % 7) as WeekDay
+  } catch {
+    // Fall through to the table below.
+  }
+  return SUNDAY_FIRST.has(tag) ? 0 : 1
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/hooks/use-locale.ts (internal to @squadbase/vantage) ---------- */
+
+const listeners = new Set<() => void>()
+let observer: MutationObserver | null = null
+
+/** One observer on `<html lang>` for every subscribed part. */
+function subscribe(onChange: () => void): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") return () => {}
+  listeners.add(onChange)
+  if (!observer) {
+    observer = new MutationObserver(() => {
+      for (const listener of [...listeners]) listener()
+    })
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["lang"] })
+  }
+  return () => {
+    listeners.delete(onChange)
+    if (listeners.size === 0 && observer) {
+      observer.disconnect()
+      observer = null
+    }
+  }
+}
+
+const serverLocale = () => FALLBACK_LOCALE
+
+/**
+ * The page's locale (`<html lang>`), following changes made while the page runs. On the server and during
+ * hydration it is `FALLBACK_LOCALE` (`en-US`), so the markup matches; it switches right after.
+ */
+function useDocumentLocale(): string {
+  return useSyncExternalStore(subscribe, documentLocale, serverLocale)
+}
+
+/** The locale a part renders in: its `locale` prop when given, else the page's (`useDocumentLocale`). */
+function useLocale(locale?: string | null): string {
+  const page = useDocumentLocale()
+  return locale || page
+}
+
+/* ---------- end of inlined code ---------- */
 
 /* ------------------------------------------------------------------- types */
 
+declare module "@tanstack/react-table" {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnMeta<TData extends RowData, TValue> {
+    /**
+     * Classes put on the column's header and body cells — e.g.
+     * `"hidden md:table-cell"` to drop a column on narrow screens.
+     */
+    className?: string
+    /**
+     * 列の数値書式。`cell` を持たない列だけに効き、右寄せ・tabular-nums で描く。
+     * 行ごとに通貨が変わるときは関数で行を受ける。CSV の「表示」値にも使われる。
+     *
+     * @example
+     * meta: { format: "currency" }
+     * meta: { format: (row) => ({ type: "currency", currency: row.currency, notation: "standard" }) }
+     */
+    format?: ValueFormat | ((row: TData) => ValueFormat)
+    /**
+     * 日付の列の書式（`formatDate` の `style`）。`cell` を持たない列だけに効く。左寄せ・tabular-nums で描き、
+     * 値は `Date`・エポックミリ秒・日付文字列（`"2026-10-20"`、ISO 8601）。CSV の「表示」値にも使われる。
+     * `format`（数値）とは併用しない。
+     *
+     * @example
+     * meta: { dateFormat: "date" }
+     * meta: { dateFormat: "datetime", nullLabel: "未更新" }
+     */
+    dateFormat?: DateStyle
+    /**
+     * `dateFormat` の列の日時を出すタイムゾーン（IANA 名。例 `"Asia/Tokyo"`）。既定は実行環境（ブラウザ）のタイムゾーン。
+     * サーバーとブラウザで表示が食い違う（SSR）なら固定する。`dateFormat` の列だけに効き、CSV の「表示」値にも同じ値を使う。
+     * `"2026-10-20"` のような日付だけの文字列は、どのタイムゾーンでもその暦日のまま。
+     *
+     * @example
+     * meta: { dateFormat: "datetime", timeZone: "Asia/Tokyo" }
+     */
+    timeZone?: string
+    /**
+     * 値が無いときの表示。既定 `"—"`。null / undefined（数値は NaN も）に効き、文字列の列では空文字 `""` も値なしとして扱う。
+     * `format` / `dateFormat` を持つ列と、書式なしの文字列の列に効く。`cell` を自前で書いた列には効かない（`cell` の中で扱う）。
+     * CSV の「表示」値は、書式付き・日付の列だけ `nullLabel` で書き、書式なしの文字列の列は空欄のまま。
+     *
+     * @example
+     * meta: { format: "number", nullLabel: "未集計" }
+     * meta: { nullLabel: "未設定" }  // 書式なしの文字列の列
+     */
+    nullLabel?: string
+    /**
+     * 値の範囲でセルを意味色に塗り分ける規則（最初に当たった規則。どれにも当たらない値は通常色）。
+     * `cell` を持たない列だけに効き、BarChart / BarList の `thresholds` と同じ型・同じ判定。
+     * 色だけに頼らず、色に応じた記号（○ / △ / × / −）を値の前に添える。CSV は生の値のまま。
+     *
+     * @example
+     * meta: { format: { type: "percent", divisor: 100 }, thresholds: [{ lt: 40, tone: "negative" }, { lt: 70, tone: "warning" }] }
+     */
+    thresholds?: ChartThreshold[]
+    /**
+     * 狭い幅で列を隠す順。数が小さい列から隠れる(表の置き場の幅が 1 は 640px 未満、2 は 520px 未満、3 は 400px 未満)。
+     * 書かない列と 4 以上の列は、どの幅でも出す(部署名・離職率のような肝心の列に使う)。
+     * 画面の幅ではなく、表を置いた場所の幅(コンテナ幅)で決まる。隠した列は DOM にも読み上げにも出ず、CSV の出力には含まれる。
+     *
+     * @example
+     * meta: { format: "number", priority: 1 }  // 幅が足りないときに最初に隠す
+     */
+    priority?: number
+    /**
+     * true にすると、増減(`Delta`)など「直前の列の値との比較」を表示する列になる。表の置き場が 320px 未満に狭まると、
+     * この列は隠れる代わりに、直前の列(値の列)のセルの下に同じ内容を小さく(text-xs)積んで出す。比較は消えない。
+     * `priority` で隠す順は最後(どの列よりも後)になり、この列の `priority` は無視される。直前の列も `priority` に関わらず残る。
+     * 列の `cell` に `<Delta variant="inline" … />` を書く。直前に列が無いときは積まず、通常の列として出す。CSV には通常の列として含まれる。
+     *
+     * @example
+     * { accessorKey: "revenue", header: "売上", meta: { format: "currency" } },
+     * { id: "revenueDelta", header: "前月比", meta: { comparison: true }, cell: ({ row }) => <Delta variant="inline" value={row.original.revenue} comparison={{ previous: row.original.prev, vs: "prior-period", grain: "month" }} /> }
+     */
+    comparison?: boolean
+    /**
+     * 列の寄せ。見出し(ソートボタンを含む)とセルの両方に効く。既定は、`format` / `thresholds` の列と
+     * `comparison` の列(増減 `Delta`)が `"right"`、それ以外は `"left"`。右寄せの列は tabular-nums で描く。
+     *
+     * @example
+     * meta: { align: "right" }
+     */
+    align?: "left" | "right"
+  }
+}
+
+/* ------------------------------------------------------------ wording */
+
+const TEXT = {
+  ja: {
+    tones: { positive: "良好", warning: "注意", negative: "要対応", neutral: "中立" } as Record<ChartTone, string>,
+    toneNote: (label: string) => `（${label}）`,
+    selectAll: "全て選択",
+    selectRow: "行を選択",
+    trend: (points: number, first: string, last: string, min: string, max: string) =>
+      `${points}点の推移、${first}から${last}、最小${min}、最大${max}`,
+    noData: "データがありません",
+    pageSize: (size: number) => `${size}件`,
+    range: (total: number, start: number, end: number) => `${total}件中 ${start} - ${end} を表示`,
+    first: "最初",
+    previous: "前へ",
+    next: "次へ",
+    last: "最後",
+    columns: "表示する列",
+    exportCsv: "CSV を書き出す",
+  },
+  en: {
+    tones: { positive: "Good", warning: "Caution", negative: "Needs action", neutral: "Neutral" } as Record<ChartTone, string>,
+    toneNote: (label: string) => ` (${label})`,
+    selectAll: "Select all",
+    selectRow: "Select row",
+    trend: (points: number, first: string, last: string, min: string, max: string) =>
+      `Trend over ${points} points: ${first} to ${last}, min ${min}, max ${max}`,
+    noData: "No results.",
+    pageSize: (size: number) => `${size} / page`,
+    range: (total: number, start: number, end: number) => `Showing ${start}–${end} of ${total}`,
+    first: "First",
+    previous: "Previous",
+    next: "Next",
+    last: "Last",
+    columns: "Columns",
+    exportCsv: "Export CSV",
+  },
+} satisfies Record<UiLanguage, unknown>
+
+const useText = () => TEXT[uiLanguage(useLocale())]
+
+/* ------------------------------------------------------------ cell formatting */
+
+/** Resolve a column's `meta.format` for one row. */
+function resolveFormat<TData>(
+  format: ValueFormat | ((row: TData) => ValueFormat) | undefined,
+  row: TData,
+): ValueFormat | undefined {
+  return typeof format === "function" ? format(row) : format
+}
+
+/** 値なし: null / undefined / NaN / 空文字。 */
+function isMissingCell(value: unknown): boolean {
+  return value === null || value === undefined || value === "" || (typeof value === "number" && Number.isNaN(value))
+}
+
+/**
+ * Display string of a column's value (`meta.format` / `meta.dateFormat` / plain);
+ * a missing value renders as `nullLabel` (default `—`).
+ */
+function formatCellText<TData>(
+  value: unknown,
+  row: TData,
+  meta: { format?: ValueFormat | ((row: TData) => ValueFormat); dateFormat?: DateStyle; timeZone?: string; nullLabel?: string },
+  locale: string,
+): string {
+  if (isMissingCell(value)) return meta.nullLabel ?? EMPTY_VALUE
+  if (meta.dateFormat && (value instanceof Date || typeof value === "string" || typeof value === "number")) {
+    const text = formatDate(value, meta.dateFormat, locale, { timeZone: meta.timeZone })
+    return text === EMPTY_VALUE ? String(value) : text
+  }
+  if (typeof value !== "number") return String(value)
+  return formatValue(value, resolveFormat(meta.format, row), locale)
+}
+
+/** 意味色ごとの記号と色クラス。Tailwind が拾えるよう、クラスはリテラルで書く。 */
+const THRESHOLD_TONE_STYLES: Record<ChartTone, { Icon: LucideIcon; text: string }> = {
+  positive: { Icon: CircleCheck, text: "text-positive" },
+  warning: { Icon: TriangleAlert, text: "text-warning" },
+  negative: { Icon: CircleX, text: "text-negative" },
+  neutral: { Icon: Minus, text: "text-neutral" },
+}
+
+/** `meta.thresholds` 列のセル。当たった規則の意味色と記号を値に添える（当たらなければ値だけ）。 */
+function ThresholdCell({ value, text, thresholds }: { value: unknown; text: string; thresholds: ChartThreshold[] }) {
+  const t = useText()
+  const tone = typeof value === "number" ? toneForValue(value, thresholds) : undefined
+  if (!tone) return <div className="text-right tabular-nums">{text}</div>
+  const { Icon, text: toneClass } = THRESHOLD_TONE_STYLES[tone]
+  const label = t.tones[tone]
+  return (
+    <div
+      data-slot="data-table-threshold-cell"
+      data-tone={tone}
+      className={cn("flex items-center justify-end gap-1.5 tabular-nums", toneClass)}
+    >
+      <Icon className="size-3.5 shrink-0" aria-hidden="true" />
+      <span>{text}</span>
+      <span className="sr-only">{t.toneNote(label)}</span>
+    </div>
+  )
+}
+
 interface DataTableContextValue<TData> {
   table: TanstackTable<TData>
   selectedRows: TData[]
@@ -74,6 +413,7 @@ interface DataTableContextValue<TData> {
   enablePagination: boolean
   enableRowSelection: boolean
   visibleColumnCount: number
+  isLoading: boolean
 }
 
 /**
@@ -89,7 +429,8 @@ export interface DataTableProps<TData, TValue> {
    * literal が `string` に拡張され型エラーになる。
    *
    * @example
-   * import type { ColumnDef } from "@squadbase/vantage/components"
+   * import { DataTable, type ColumnDef } from "@/components/data-table"
+   * // Vantage: import { DataTable, type ColumnDef } from "@squadbase/vantage/components"
    *
    * const columns: ColumnDef<User>[] = [
    *   { accessorKey: "id", header: "ID" },
@@ -116,7 +457,42 @@ export interface DataTableProps<TData, TValue> {
   enablePagination?: boolean
   pagination?: PaginationState
   onPaginationChange?: OnChangeFn<PaginationState>
+  /**
+   * サーバー側ページング時の総ページ数。指定すると manualPagination になる。
+   *
+   * @example
+   * <DataTable pageCount={data.pageCount} … />
+   */
   pageCount?: number
+  /**
+   * サーバー側ページング時の総件数。指定すると manualPagination になり、ページ数は
+   * `rowCount / pageSize` から導かれ、「N件中」もこの値を使う（`pageCount` を同時に渡せばそちらが優先）。
+   *
+   * @example
+   * <DataTable rowCount={1240} pagination={pagination} onPaginationChange={setPagination} … />
+   */
+  rowCount?: number
+  /**
+   * true にすると絞り込みを表では行わず、`data` をそのまま使う（サーバー側で絞り込む）。
+   *
+   * @example
+   * <DataTable manualFiltering globalFilter={q} onGlobalFilterChange={setQ} … />
+   */
+  manualFiltering?: boolean
+  /**
+   * true にすると並べ替えを表では行わず、`data` の順をそのまま使う（サーバー側で並べ替える）。
+   *
+   * @example
+   * <DataTable manualSorting sorting={sorting} onSortingChange={setSorting} … />
+   */
+  manualSorting?: boolean
+  /**
+   * 読み込み中。Content はスケルトン行、Pagination のボタンは無効、表は aria-busy になる。
+   *
+   * @example
+   * <DataTable isLoading={query.isFetching} … />
+   */
+  isLoading?: boolean
 
   // Row selection
   enableRowSelection?: boolean
@@ -127,6 +503,13 @@ export interface DataTableProps<TData, TValue> {
   columnVisibility?: VisibilityState
   onColumnVisibilityChange?: OnChangeFn<VisibilityState>
 
+  /**
+   * TanStack Table の `meta`。表全体で共有する値(行を更新する関数など)を渡し、列定義の `cell` から
+   * `table.options.meta` で読む。列ごとの書式は列定義の `meta.format` に書く(こちらではない)。
+   *
+   * @example
+   * <DataTable meta={{ updateRow: (id, patch) => mutate({ id, patch }) }} … />
+   */
   meta?: TableMeta<TData>
   className?: string
 
@@ -142,6 +525,33 @@ export interface DataTableToolbarProps extends HTMLAttributes<HTMLDivElement> {
 
 export interface DataTableContentProps extends HTMLAttributes<HTMLDivElement> {}
 
+export interface DataTableExportProps {
+  /**
+   * 保存するファイル名。既定 `"export.csv"`。
+   *
+   * @example
+   * <DataTableExport fileName="sales-2025.csv" />
+   */
+  fileName?: string
+  /**
+   * `"display"`（既定）は `meta.format` どおりの表示文字列、`"raw"` は生の値を書き出す。
+   *
+   * @example
+   * <DataTableExport values="raw" />
+   */
+  values?: CsvValues
+  /**
+   * `"filtered"`（既定）は並べ替え・絞り込み後の全ページ、`"page"` は表示中のページだけ。
+   *
+   * @example
+   * <DataTableExport scope="page" />
+   */
+  scope?: CsvScope
+  /** ボタンの文言。既定はページの言語で `"CSV を書き出す"`（英語は `"Export CSV"`）。 */
+  children?: ReactNode
+  className?: string
+}
+
 export interface DataTablePaginationProps extends HTMLAttributes<HTMLDivElement> {
   pageSizeOptions?: number[]
 }
@@ -152,40 +562,31 @@ export interface DataTableColumnVisibilityProps {
   className?: string
 }
 
-export interface DataTablePresetProps<TData, TValue> {
-  columns: ColumnDef<TData, TValue>[]
-  data: TData[]
-
-  enableSorting?: boolean
-  sorting?: SortingState
-  onSortingChange?: OnChangeFn<SortingState>
-
-  enableFiltering?: boolean
-  columnFilters?: ColumnFiltersState
-  onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>
-  globalFilter?: string
-  onGlobalFilterChange?: OnChangeFn<string>
-
-  enablePagination?: boolean
-  pagination?: PaginationState
-  onPaginationChange?: OnChangeFn<PaginationState>
-  pageCount?: number
-
-  enableRowSelection?: boolean
-  rowSelection?: RowSelectionState
-  onRowSelectionChange?: OnChangeFn<RowSelectionState>
-
+/** The preset takes every `DataTable` prop except `children`, plus a few slots. */
+export type DataTablePresetProps<TData, TValue> = Omit<
+  DataTableProps<TData, TValue>,
+  "children"
+> & {
   enableColumnVisibility?: boolean
-  columnVisibility?: VisibilityState
-  onColumnVisibilityChange?: OnChangeFn<VisibilityState>
   columnLabels?: Record<string, string>
+  /**
+   * true にすると toolbar に CSV 書き出しボタン（`DataTableExport`）を置く。既定 false。
+   *
+   * @example
+   * <DataTablePreset exportable … />
+   */
+  exportable?: boolean
+  /**
+   * `exportable` のときの保存ファイル名。既定 `"export.csv"`。
+   *
+   * @example
+   * <DataTablePreset exportable exportFileName="sales.csv" … />
+   */
+  exportFileName?: string
 
   /** Extension slots */
   toolbar?: ReactNode
   bulkActions?: (selectedRows: TData[]) => ReactNode
-
-  meta?: TableMeta<TData>
-  className?: string
 }
 
 /* ------------------------------------------------------------------ helper */
@@ -226,9 +627,12 @@ export function useDataTable<TData>(): DataTableContextValue<TData> {
 
 /* -------------------------------------------------------------------- root */
 
+/** Columns / rows not given yet (a draft fills props in steps): draw the empty state, keep the same array between renders. */
+const NO_ROWS: never[] = []
+
 export function DataTable<TData, TValue>({
-  columns,
-  data,
+  columns = NO_ROWS,
+  data = NO_ROWS,
   enableSorting = true,
   sorting: sortingProp,
   onSortingChange,
@@ -241,6 +645,10 @@ export function DataTable<TData, TValue>({
   pagination: paginationProp,
   onPaginationChange,
   pageCount,
+  rowCount,
+  manualFiltering,
+  manualSorting,
+  isLoading = false,
   enableRowSelection = false,
   rowSelection: rowSelectionProp,
   onRowSelectionChange,
@@ -250,6 +658,8 @@ export function DataTable<TData, TValue>({
   className,
   children,
 }: DataTableProps<TData, TValue>) {
+  const locale = useLocale()
+  const t = TEXT[uiLanguage(locale)]
   const [sorting, setSorting] = useControlledState<SortingState>(sortingProp, [], onSortingChange)
 
   const [columnFilters, setColumnFilters] = useControlledState<ColumnFiltersState>(
@@ -284,7 +694,29 @@ export function DataTable<TData, TValue>({
 
   // Row selection prepends a checkbox column that the caller never declares.
   const allColumns = useMemo<ColumnDef<TData, TValue>[]>(() => {
-    if (!enableRowSelection) return columns
+    // A column with `meta.format` / `meta.thresholds` and no `cell` gets a formatted, right-aligned
+    // cell; thresholds add the tone colour plus a symbol. `meta.dateFormat` gives a left-aligned date.
+    // A plain accessor column (no `cell`) shows `nullLabel` / `—` for a missing value.
+    const formatted = columns.map((column) => {
+      const meta = column.meta
+      if (column.cell !== undefined) return column
+      const hasAccessor = "accessorKey" in column || "accessorFn" in column
+      if (!(meta?.format || meta?.thresholds || meta?.dateFormat) && !hasAccessor) return column
+      const thresholds = meta?.thresholds
+      const aligned = Boolean(meta?.format || thresholds)
+      return {
+        ...column,
+        cell: ({ row, getValue }) => {
+          const value = getValue()
+          const text = formatCellText(value, row.original, meta ?? {}, locale)
+          if (thresholds) return <ThresholdCell value={value} text={text} thresholds={thresholds} />
+          if (aligned) return <div className="text-right tabular-nums">{text}</div>
+          if (meta?.dateFormat) return <span className="tabular-nums">{text}</span>
+          return text
+        },
+      } as ColumnDef<TData, TValue>
+    })
+    if (!enableRowSelection) return formatted
 
     const selectionColumn: ColumnDef<TData, TValue> = {
       id: "_select",
@@ -293,24 +725,40 @@ export function DataTable<TData, TValue>({
           checked={table.getIsAllPageRowsSelected()}
           indeterminate={table.getIsSomePageRowsSelected()}
           onCheckedChange={(checked) => table.toggleAllPageRowsSelected(checked)}
-          aria-label="全て選択"
+          aria-label={t.selectAll}
         />
       ),
       cell: ({ row }) => (
         <Checkbox
           checked={row.getIsSelected()}
           onCheckedChange={(checked) => row.toggleSelected(checked)}
-          aria-label="行を選択"
+          aria-label={t.selectRow}
         />
       ),
       enableSorting: false,
       enableHiding: false,
     }
 
-    return [selectionColumn, ...columns]
-  }, [columns, enableRowSelection])
+    return [selectionColumn, ...formatted]
+  }, [columns, enableRowSelection, locale, t])
+
+  // TanStack's own `autoResetPageIndex` queues `resetPageIndex()` from inside a render-time memo, which
+  // can fire before the component has mounted ("Can't perform a React state update on a component that
+  // hasn't mounted yet"). Turn it off and send the page back to 1 from an effect instead, so it only
+  // runs after mount and only when the sort / filter / data actually changed.
+  const autoResetPage = enablePagination && pageCount === undefined && rowCount === undefined
+  const resetKey = useRef<readonly unknown[] | null>(null)
+  useEffect(() => {
+    const next = [data, sorting, columnFilters, globalFilter]
+    const prev = resetKey.current
+    resetKey.current = next
+    if (!autoResetPage || prev === null) return
+    if (prev.every((value, i) => value === next[i])) return
+    setPagination((old) => (old.pageIndex === 0 ? old : { ...old, pageIndex: 0 }))
+  }, [autoResetPage, data, sorting, columnFilters, globalFilter, setPagination])
 
   const table = useReactTable({
+    autoResetPageIndex: false,
     data,
     columns: allColumns,
     state: {
@@ -329,7 +777,11 @@ export function DataTable<TData, TValue>({
     onRowSelectionChange: setRowSelection,
     onColumnVisibilityChange: setColumnVisibility,
     ...(enablePagination ? { onPaginationChange: setPagination } : {}),
-    ...(pageCount !== undefined ? { pageCount, manualPagination: true } : {}),
+    ...(pageCount !== undefined || rowCount !== undefined
+      ? { pageCount, rowCount, manualPagination: true }
+      : {}),
+    ...(manualFiltering ? { manualFiltering: true } : {}),
+    ...(manualSorting ? { manualSorting: true } : {}),
     getCoreRowModel: getCoreRowModel(),
     getSortedRowModel: getSortedRowModel(),
     getFilteredRowModel: getFilteredRowModel(),
@@ -357,6 +809,7 @@ export function DataTable<TData, TValue>({
       enablePagination,
       enableRowSelection,
       visibleColumnCount: allColumns.length,
+      isLoading,
     }),
     // `useReactTable` returns the same object every render, so each piece of
     // table state has to be tracked explicitly to re-render the consumers.
@@ -371,6 +824,8 @@ export function DataTable<TData, TValue>({
       enablePagination,
       enableRowSelection,
       allColumns.length,
+      isLoading,
+      rowCount,
       sorting,
       columnFilters,
       columnVisibility,
@@ -381,7 +836,7 @@ export function DataTable<TData, TValue>({
 
   return (
     <DataTableContext.Provider value={contextValue as DataTableContextValue<unknown>}>
-      <div data-slot="data-table" className={cn("space-y-4", className)}>
+      <div data-slot="data-table" aria-busy={isLoading || undefined} className={cn("space-y-4", className)}>
         {children}
       </div>
     </DataTableContext.Provider>
@@ -389,6 +844,76 @@ export function DataTable<TData, TValue>({
 }
 DataTable.displayName = "DataTable"
 
+/* ------------------------------------------------------ sparkline column */
+
+/** Fewest points a row needs for a trend (one point has no direction). */
+const SPARKLINE_MIN_POINTS = 2
+
+export interface SparklineColumnOptions<TData> {
+  /** 列 ID（CSV・列の表示切り替えで使う）。 */
+  id: string
+  /** 見出し。 */
+  header: string
+  /**
+   * 行の数列を返す（古い順。例: 直近 8 週の売上）。null / undefined / 2 点未満の行は「—」。
+   * NaN などの有限でない値は取り除いてから数える。
+   */
+  values: (row: TData) => readonly (number | null | undefined)[] | null | undefined
+  /** スクリーンリーダー向けの数値の書式（`meta.format` と同じ語彙）。既定は `"number"`。 */
+  format?: ValueFormat
+}
+
+/**
+ * 行の数列をセルの小さなトレンド（Sparkline）にする列。色は `--chart-1` 固定、軸・ツールチップ・ラベルなし。
+ * 図は読み上げず、同じセルの sr-only に「N 点、最初 → 最後、最小、最大」を書式付きで添える。
+ * 数列の並べ替えは意味が無いので無効。DataTable 本体の props は増やさず、`columns` に置くだけで使う。
+ *
+ * @example
+ * const columns: ColumnDef<Store>[] = [
+ *   { accessorKey: "store", header: "店舗" },
+ *   sparklineColumn<Store>({ id: "trend", header: "直近 8 週", values: (r) => r.weekly, format: "currency" }),
+ * ]
+ */
+export function sparklineColumn<TData>({
+  id,
+  header,
+  values,
+  format = "number",
+}: SparklineColumnOptions<TData>): ColumnDef<TData, unknown> {
+  return {
+    id,
+    header,
+    accessorFn: (row) => values(row) ?? null,
+    enableSorting: false,
+    cell: ({ getValue }) => {
+      const raw = getValue() as readonly (number | null | undefined)[] | null
+      const series = (raw ?? []).filter((v): v is number => typeof v === "number" && Number.isFinite(v))
+      if (series.length < SPARKLINE_MIN_POINTS) return <span className="text-muted-foreground">{EMPTY_VALUE}</span>
+      return (
+        <div data-slot="data-table-sparkline-cell" className="flex h-5 items-center">
+          <div aria-hidden="true" className="h-5 w-24 shrink-0">
+            <Sparkline data={series.map((value) => ({ value }))} height={20} />
+          </div>
+          <SparklineSummary series={series} format={format} />
+        </div>
+      )
+    },
+  }
+}
+
+/** The sparkline cell's screen-reader text, in the page's language. */
+function SparklineSummary({ series, format }: { series: number[]; format: ValueFormat }) {
+  const locale = useLocale()
+  const f = (v: number) => formatValue(v, format, locale)
+  const first = series[0] as number
+  const last = series[series.length - 1] as number
+  return (
+    <span className="sr-only">
+      {TEXT[uiLanguage(locale)].trend(series.length, f(first), f(last), f(Math.min(...series)), f(Math.max(...series)))}
+    </span>
+  )
+}
+
 /* ----------------------------------------------------------------- toolbar */
 
 export const DataTableToolbar = forwardRef<HTMLDivElement, DataTableToolbarProps>(
@@ -431,63 +956,200 @@ DataTableToolbar.displayName = "DataTableToolbar"
 
 /* ----------------------------------------------------------------- content */
 
+/**
+ * `meta.priority` → the classes that hide the column below a container width (`@container` on the content wrapper).
+ * The class strings are literals so Tailwind picks them up.
+ */
+const PRIORITY_CLASS: Record<number, string> = {
+  1: "hidden @min-[640px]:table-cell",
+  2: "hidden @min-[520px]:table-cell",
+  3: "hidden @min-[400px]:table-cell",
+}
+
+/**
+ * A `meta.comparison` column is the last tier: it stays as its own column down to 320px, below which it is hidden and its
+ * content is stacked under the value cell instead (`COMPARISON_STACK_CLASS`, visible only below the same width).
+ */
+const COMPARISON_CLASS = "hidden @min-[320px]:table-cell"
+const COMPARISON_STACK_CLASS = "@min-[320px]:hidden"
+
+/** A column's hide-on-narrow classes: none without a priority (or at 4 and above), the lowest tier for anything below 1. */
+export function priorityClassName(priority: number | undefined): string | undefined {
+  if (priority === undefined || !Number.isFinite(priority) || priority >= 4) return undefined
+  return PRIORITY_CLASS[Math.max(1, Math.floor(priority))]
+}
+
+type CellMeta = {
+  className?: string
+  format?: unknown
+  thresholds?: unknown
+  priority?: number
+  comparison?: boolean
+  align?: "left" | "right"
+}
+
+/** `meta.align` wins; otherwise numeric columns (`format` / `thresholds`) and Delta (`comparison`) columns are right-aligned, header included. */
+function isRightAligned(meta: CellMeta | undefined): boolean {
+  if (meta?.align) return meta.align === "right"
+  return Boolean(meta?.format || meta?.thresholds || meta?.comparison)
+}
+
+/**
+ * A column that carries a stacked comparison (`isHost`) never hides, and a comparison column ignores its own
+ * `priority` and takes the last tier.
+ */
+function columnClassName(meta: CellMeta | undefined, options: { isComparison?: boolean; isHost?: boolean } = {}) {
+  const tier = options.isComparison
+    ? COMPARISON_CLASS
+    : options.isHost
+      ? undefined
+      : priorityClassName(meta?.priority)
+  return cn(tier, meta?.className, isRightAligned(meta) ? "text-right tabular-nums" : undefined) || undefined
+}
+
+/**
+ * Pair every `meta.comparison` column with the visible column right before it (the value it compares).
+ * A comparison column with nothing before it stays an ordinary column.
+ */
+function pairComparisons<TData>(columns: Column<TData, unknown>[]) {
+  const comparisonOf = new Map<string, Column<TData, unknown>>() // host column id → its comparison column
+  const comparisonIds = new Set<string>()
+  columns.forEach((column, i) => {
+    if (i > 0 && column.columnDef.meta?.comparison && !columns[i - 1]!.columnDef.meta?.comparison) {
+      comparisonOf.set(columns[i - 1]!.id, column)
+      comparisonIds.add(column.id)
+    }
+  })
+  return { comparisonOf, comparisonIds }
+}
+
+const SORT_ICON_CLASS = "size-4 shrink-0"
+
+/** The sort icon: always shown on the sorted column, only on hover / keyboard focus on the others. */
+function SortIcon({ sorted }: { sorted: false | "asc" | "desc" }) {
+  if (sorted === "asc") return <ArrowUp className={SORT_ICON_CLASS} aria-hidden="true" />
+  if (sorted === "desc") return <ArrowDown className={SORT_ICON_CLASS} aria-hidden="true" />
+  return (
+    <ArrowUpDown
+      className={cn(
+        SORT_ICON_CLASS,
+        "text-muted-foreground opacity-0 group-hover/sort:opacity-100 group-focus-visible/sort:opacity-100",
+      )}
+      aria-hidden="true"
+    />
+  )
+}
+
 export const DataTableContent = forwardRef<HTMLDivElement, DataTableContentProps>(
   ({ className, ...props }, ref) => {
-    const { table, visibleColumnCount } = useDataTable()
+    const { table, visibleColumnCount, isLoading, enablePagination } = useDataTable()
+    const t = useText()
+    const { comparisonOf, comparisonIds } = pairComparisons(table.getVisibleLeafColumns())
 
     return (
       <div
         ref={ref}
         data-slot="data-table-content"
-        className={cn("overflow-x-auto", className)}
+        aria-busy={isLoading || undefined}
+        className={cn("@container overflow-x-auto", className)}
         {...props}
       >
-        <Table>
+        <Table className="[&_th:first-child]:pl-0 [&_td:first-child]:pl-0 [&_th:last-child]:pr-0 [&_td:last-child]:pr-0">
           <TableHeader>
             {table.getHeaderGroups().map((headerGroup) => (
               <TableRow key={headerGroup.id}>
-                {headerGroup.headers.map((header) => (
-                  <TableHead key={header.id}>
-                    {header.isPlaceholder ? null : header.column.getCanSort() ? (
-                      <button
-                        type="button"
-                        className="inline-flex items-center gap-1 rounded hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:outline-none"
-                        onClick={header.column.getToggleSortingHandler()}
-                        aria-sort={
-                          header.column.getIsSorted() === "asc"
+                {headerGroup.headers.map((header) => {
+                  const column = header.column
+                  const meta = column.columnDef.meta
+                  const sorted = column.getIsSorted()
+                  const canSort = column.getCanSort()
+                  const label = header.isPlaceholder ? null : flexRender(column.columnDef.header, header.getContext())
+                  return (
+                    <TableHead
+                      key={header.id}
+                      className={columnClassName(meta, {
+                        isComparison: comparisonIds.has(column.id),
+                        isHost: comparisonOf.has(column.id),
+                      })}
+                      aria-sort={
+                        canSort && !header.isPlaceholder
+                          ? sorted === "asc"
                             ? "ascending"
-                            : header.column.getIsSorted() === "desc"
+                            : sorted === "desc"
                               ? "descending"
                               : "none"
-                        }
-                      >
-                        {flexRender(header.column.columnDef.header, header.getContext())}
-                        {header.column.getIsSorted() === "asc" ? (
-                          <ArrowUp className="size-4" />
-                        ) : header.column.getIsSorted() === "desc" ? (
-                          <ArrowDown className="size-4" />
-                        ) : (
-                          <ArrowUpDown className="size-4 text-muted-foreground" />
-                        )}
-                      </button>
-                    ) : (
-                      flexRender(header.column.columnDef.header, header.getContext())
-                    )}
-                  </TableHead>
-                ))}
+                          : undefined
+                      }
+                    >
+                      {header.isPlaceholder ? null : canSort ? (
+                        <button
+                          type="button"
+                          className={cn(
+                            "group/sort relative items-center gap-1 rounded leading-5 after:absolute after:inset-x-0 after:top-1/2 after:h-6 after:-translate-y-1/2 hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:outline-none",
+                            isRightAligned(meta) ? "flex w-full justify-end" : "inline-flex",
+                          )}
+                          onClick={column.getToggleSortingHandler()}
+                        >
+                          {isRightAligned(meta) && <SortIcon sorted={sorted} />}
+                          {label}
+                          {!isRightAligned(meta) && <SortIcon sorted={sorted} />}
+                        </button>
+                      ) : (
+                        label
+                      )}
+                    </TableHead>
+                  )
+                })}
               </TableRow>
             ))}
           </TableHeader>
 
           <TableBody>
-            {table.getRowModel().rows.length ? (
+            {isLoading ? (
+              Array.from({ length: enablePagination ? table.getState().pagination.pageSize : 5 }).map(
+                (_, i) => (
+                  <TableRow key={i} data-slot="data-table-skeleton-row">
+                    {Array.from({ length: visibleColumnCount }).map((__, j) => (
+                      <TableCell key={j}>
+                        <Skeleton className="h-4 w-full" />
+                      </TableCell>
+                    ))}
+                  </TableRow>
+                ),
+              )
+            ) : table.getRowModel().rows.length ? (
               table.getRowModel().rows.map((row) => (
                 <TableRow key={row.id} data-state={row.getIsSelected() ? "selected" : undefined}>
-                  {row.getVisibleCells().map((cell) => (
-                    <TableCell key={cell.id}>
-                      {flexRender(cell.column.columnDef.cell, cell.getContext())}
-                    </TableCell>
-                  ))}
+                  {row.getVisibleCells().map((cell) => {
+                    const meta = cell.column.columnDef.meta
+                    const comparisonColumn = comparisonOf.get(cell.column.id)
+                    const comparisonCell = comparisonColumn
+                      ? row.getVisibleCells().find((c) => c.column.id === comparisonColumn.id)
+                      : undefined
+                    return (
+                      <TableCell
+                        key={cell.id}
+                        className={columnClassName(meta, {
+                          isComparison: comparisonIds.has(cell.column.id),
+                          isHost: comparisonOf.has(cell.column.id),
+                        })}
+                      >
+                        {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                        {comparisonCell && (
+                          <div
+                            data-slot="data-table-stacked-comparison"
+                            className={cn(
+                              COMPARISON_STACK_CLASS,
+                              "mt-0.5 text-xs [&_[data-slot=delta]]:text-xs",
+                              isRightAligned(meta) ? "text-right" : undefined,
+                            )}
+                          >
+                            {flexRender(comparisonCell.column.columnDef.cell, comparisonCell.getContext())}
+                          </div>
+                        )}
+                      </TableCell>
+                    )
+                  })}
                 </TableRow>
               ))
             ) : (
@@ -496,7 +1158,7 @@ export const DataTableContent = forwardRef<HTMLDivElement, DataTableContentProps
                   colSpan={visibleColumnCount}
                   className="h-24 text-center text-muted-foreground"
                 >
-                  データがありません
+                  {t.noData}
                 </TableCell>
               </TableRow>
             )}
@@ -512,37 +1174,46 @@ DataTableContent.displayName = "DataTableContent"
 
 export const DataTablePagination = forwardRef<HTMLDivElement, DataTablePaginationProps>(
   ({ pageSizeOptions = [10, 20, 50], className, ...props }, ref) => {
-    const { table } = useDataTable()
+    const { table, isLoading } = useDataTable()
+    const t = useText()
 
-    const totalRows = table.getFilteredRowModel().rows.length
+    const totalRows =
+      table.options.rowCount !== undefined
+        ? table.getRowCount()
+        : table.getFilteredRowModel().rows.length
     const currentPageSize = table.getState().pagination.pageSize
     const currentPageIndex = table.getState().pagination.pageIndex
     const rangeStart = currentPageIndex * currentPageSize + 1
     const rangeEnd = Math.min((currentPageIndex + 1) * currentPageSize, totalRows)
+    // One list feeds both the menu and `items`, so the trigger shows "10 / page" (ja: "10件")
+    // rather than the raw "10" under Base UI's SelectValue.
+    const pageSizeItems = pageSizeOptions.map((size) => ({
+      value: String(size),
+      label: t.pageSize(size),
+    }))
 
     return (
       <div
         ref={ref}
         data-slot="data-table-pagination"
+        aria-busy={isLoading || undefined}
         className={cn("flex flex-wrap items-center justify-between gap-4", className)}
         {...props}
       >
         <div className="flex items-center gap-2 text-sm text-muted-foreground">
-          <span>
-            {totalRows}件中 {rangeStart} - {rangeEnd} を表示
-          </span>
+          <span>{t.range(totalRows, rangeStart, rangeEnd)}</span>
           <Select
-            items={Object.fromEntries(pageSizeOptions.map((size) => [String(size), `${size}件`]))}
+            items={pageSizeItems}
             value={String(currentPageSize)}
             onValueChange={(value) => table.setPageSize(Number(value))}
           >
-            <SelectTrigger size="sm" className="w-[80px]">
+            <SelectTrigger size="sm" className="min-w-[80px]">
               <SelectValue />
             </SelectTrigger>
             <SelectContent>
-              {pageSizeOptions.map((size) => (
-                <SelectItem key={size} value={String(size)}>
-                  {size}件
+              {pageSizeItems.map((item) => (
+                <SelectItem key={item.value} value={item.value}>
+                  {item.label}
                 </SelectItem>
               ))}
             </SelectContent>
@@ -554,33 +1225,33 @@ export const DataTablePagination = forwardRef<HTMLDivElement, DataTablePaginatio
             variant="outline"
             size="sm"
             onClick={() => table.firstPage()}
-            disabled={!table.getCanPreviousPage()}
+            disabled={isLoading || !table.getCanPreviousPage()}
           >
-            最初
+            {t.first}
           </Button>
           <Button
             variant="outline"
             size="sm"
             onClick={() => table.previousPage()}
-            disabled={!table.getCanPreviousPage()}
+            disabled={isLoading || !table.getCanPreviousPage()}
           >
-            前へ
+            {t.previous}
           </Button>
           <Button
             variant="outline"
             size="sm"
             onClick={() => table.nextPage()}
-            disabled={!table.getCanNextPage()}
+            disabled={isLoading || !table.getCanNextPage()}
           >
-            次へ
+            {t.next}
           </Button>
           <Button
             variant="outline"
             size="sm"
             onClick={() => table.lastPage()}
-            disabled={!table.getCanNextPage()}
+            disabled={isLoading || !table.getCanNextPage()}
           >
-            最後
+            {t.last}
           </Button>
         </div>
       </div>
@@ -596,6 +1267,7 @@ export const DataTableColumnVisibility = forwardRef<
   DataTableColumnVisibilityProps
 >(({ columnLabels, className }, ref) => {
   const { table } = useDataTable()
+  const t = useText()
 
   const hideableColumns = table.getAllColumns().filter((column) => column.getCanHide())
 
@@ -607,8 +1279,9 @@ export const DataTableColumnVisibility = forwardRef<
         ref={ref}
         render={<Button variant="outline" size="sm" className={cn(className)} />}
         data-slot="data-table-column-visibility"
+        aria-label={t.columns}
       >
-        <Columns3 className="size-4" />
+        <Columns3 className="size-4" aria-hidden="true" />
       </DropdownMenuTrigger>
       <DropdownMenuContent align="end" className="min-w-[10rem]">
         {hideableColumns.map((column) => {
@@ -631,75 +1304,143 @@ export const DataTableColumnVisibility = forwardRef<
 })
 DataTableColumnVisibility.displayName = "DataTableColumnVisibility"
 
+/* ------------------------------------------------------------------ export */
+
+export type CsvCell = string | number | null | undefined
+export type CsvValues = "display" | "raw"
+export type CsvScope = "filtered" | "page"
+
+// A signed number with an optional short currency / unit ("-¥1,200", "+530万", "-12.5%").
+const SIGNED_NUMBER = /^[+-]\s?[^\d\s=+\-@]{0,3}\d[\d,.]*[^\d\s=+\-@]{0,4}$/
+
+/**
+ * CSV 文字列を作る純関数（RFC 4180: CRLF、`,` `"` 改行を含む欄は `"` で囲み `"` は二重化）。
+ * 既定で BOM 付き UTF-8（Excel で文字化けしない）。`guardFormulas` が true の間、先頭が
+ * `= + - @` の文字列欄には `'` を付けて数式として実行されないようにする（数値と符号付きの数値表記は除く）。
+ *
+ * @example
+ * toCsv(["月", "売上"], [["2025-01", 1200], ["2025-02", null]])
+ * // "\uFEFF月,売上\r\n2025-01,1200\r\n2025-02,"
+ */
+export function toCsv(
+  header: string[],
+  rows: CsvCell[][],
+  options: { bom?: boolean; guardFormulas?: boolean } = {},
+): string {
+  const { bom = true, guardFormulas = false } = options
+  const field = (cell: CsvCell, guard: boolean): string => {
+    let text = cell === null || cell === undefined ? "" : String(cell)
+    if (guard && typeof cell === "string" && /^[=+\-@]/.test(text) && !SIGNED_NUMBER.test(text)) {
+      text = `'${text}`
+    }
+    return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text
+  }
+  const lines = [
+    header.map((h) => field(h, false)).join(","),
+    ...rows.map((row) => row.map((cell) => field(cell, guardFormulas)).join(",")),
+  ]
+  return (bom ? "\uFEFF" : "") + lines.join("\r\n")
+}
+
+/**
+ * 表の現在の状態から CSV を作る。行は画面と同じ並べ替え・絞り込み後の順、列は表示中の列のみ。
+ * `"display"` の書式のロケールは `locale`（既定はページのロケール、`<html lang>`）。
+ *
+ * @example
+ * const csv = tableToCsv(table, { values: "raw", scope: "page" })
+ */
+export function tableToCsv<TData>(
+  table: TanstackTable<TData>,
+  { values = "display", scope = "filtered", locale: localeArg }: { values?: CsvValues; scope?: CsvScope; locale?: string } = {},
+): string {
+  const locale = resolveLocale(localeArg)
+  const columns = table.getVisibleLeafColumns().filter((column) => column.id !== "_select")
+  const rows = scope === "page" ? table.getRowModel().rows : table.getSortedRowModel().rows
+  const header = columns.map((column) =>
+    typeof column.columnDef.header === "string" ? column.columnDef.header : column.id,
+  )
+  const body = rows.map((row) =>
+    columns.map((column): CsvCell => {
+      const value = row.getValue(column.id)
+      const meta = column.columnDef.meta
+      if (values === "display" && (meta?.format || meta?.dateFormat)) return formatCellText(value, row.original, meta, locale)
+      if (value === null || value === undefined) return ""
+      if (typeof value === "number" || typeof value === "string") return value
+      if (value instanceof Date) return value.toISOString()
+      return String(value)
+    }),
+  )
+  return toCsv(header, body, { guardFormulas: values === "display" })
+}
+
+/** toolbar に置く CSV 書き出しボタン。`useDataTable()` の table から画面と同じ順・同じ集合を書き出す。 */
+export function DataTableExport({
+  fileName = "export.csv",
+  values = "display",
+  scope = "filtered",
+  children,
+  className,
+}: DataTableExportProps) {
+  const { table, isLoading } = useDataTable()
+  const locale = useLocale()
+
+  const onClick = () => {
+    const csv = tableToCsv(table, { values, scope, locale })
+    const url = URL.createObjectURL(new Blob([csv], { type: "text/csv;charset=utf-8" }))
+    const a = document.createElement("a")
+    a.href = url
+    a.download = fileName
+    a.click()
+    URL.revokeObjectURL(url)
+  }
+
+  return (
+    <Button
+      type="button"
+      variant="outline"
+      size="sm"
+      className={className}
+      data-slot="data-table-export"
+      onClick={onClick}
+      disabled={isLoading}
+    >
+      <Download className="size-4" aria-hidden="true" />
+      {children ?? TEXT[uiLanguage(locale)].exportCsv}
+    </Button>
+  )
+}
+DataTableExport.displayName = "DataTableExport"
+
 /* ------------------------------------------------------------------ preset */
 
 /** The usual arrangement — toolbar, body and pagination — in one component. */
 export function DataTablePreset<TData, TValue>({
-  columns,
-  data,
-  enableSorting,
-  sorting,
-  onSortingChange,
-  enableFiltering,
-  columnFilters,
-  onColumnFiltersChange,
-  globalFilter,
-  onGlobalFilterChange,
-  enablePagination,
-  pagination,
-  onPaginationChange,
-  pageCount,
-  enableRowSelection,
-  rowSelection,
-  onRowSelectionChange,
   enableColumnVisibility = false,
-  columnVisibility,
-  onColumnVisibilityChange,
   columnLabels,
+  exportable = false,
+  exportFileName,
   toolbar,
   bulkActions,
-  meta,
-  className,
+  ...tableProps
 }: DataTablePresetProps<TData, TValue>) {
   const toolbarSlot =
-    toolbar || enableColumnVisibility ? (
+    toolbar || enableColumnVisibility || exportable ? (
       <>
         {toolbar}
+        {exportable && <DataTableExport fileName={exportFileName} />}
         {enableColumnVisibility && <DataTableColumnVisibility columnLabels={columnLabels} />}
       </>
     ) : undefined
 
   return (
-    <DataTable<TData, TValue>
-      columns={columns}
-      data={data}
-      enableSorting={enableSorting}
-      sorting={sorting}
-      onSortingChange={onSortingChange}
-      enableFiltering={enableFiltering}
-      columnFilters={columnFilters}
-      onColumnFiltersChange={onColumnFiltersChange}
-      globalFilter={globalFilter}
-      onGlobalFilterChange={onGlobalFilterChange}
-      enablePagination={enablePagination}
-      pagination={pagination}
-      onPaginationChange={onPaginationChange}
-      pageCount={pageCount}
-      enableRowSelection={enableRowSelection}
-      rowSelection={rowSelection}
-      onRowSelectionChange={onRowSelectionChange}
-      columnVisibility={columnVisibility}
-      onColumnVisibilityChange={onColumnVisibilityChange}
-      meta={meta}
-      className={className}
-    >
+    <DataTable<TData, TValue> {...tableProps}>
       <DataTableToolbar
-        showSearch={enableFiltering}
+        showSearch={tableProps.enableFiltering}
         toolbar={toolbarSlot}
         bulkActions={bulkActions as ((selectedRows: unknown[]) => ReactNode) | undefined}
       />
       <DataTableContent />
-      {enablePagination && <DataTablePagination />}
+      {tableProps.enablePagination && <DataTablePagination />}
     </DataTable>
   )
 }