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

package/registry/ui/kpi-card.tsx

@@ -0,0 +1,907 @@
+// Copied by `vantage add ui kpi-card`. This file is yours to edit.
+// Generated from @squadbase/squadkit registry/components/kpi-card.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
+/**
+ * KpiCard — one metric as a card of its own (label, value, delta, target, history), so do not put it in `DashboardCardPreset`.
+ *
+ * Five tiers, following shadcn dashboard-01 SectionCards:
+ *
+ *   1. label            (CardDescription, muted)
+ *   2. value            (CardTitle, tabular-nums; text-4xl once the card is ≥ 320px wide (a comparison label is ~180px, so narrower cards would overlap the value))
+ *   3. delta            (CardAction: arrow + sign + colour + comparison label — `Delta`)
+ *   4. previous actual  ("前月 ¥4,290万"; on by default, `showPrevious={false}` hides it)
+ *   5. conclusion       (`summary`: a *template* whose placeholders the card fills)
+ *
+ * with optional extras: a target bar under the value (a 6px straight bar — actual
+ * in `--chart-1`, the pace projection in `--chart-1/30` (`/45` in dark: 1.33:1 → 1.6:1 against the track, as light has), a 1px tick at the target —
+ * and one line "目標の 49%・このペースなら 98%"), then in the footer a record badge
+ * from `history`, the data source footnote, the last update time and, with ≥ 6
+ * points of `history`, an axis-less sparkline (`showHistory={false}` hides it).
+ *
+ * Everything derivable is computed here — direction, rate, colour, remaining,
+ * achievement, projection, record — so no two props can disagree. Pass enums and
+ * numbers only. `history` is the series ending at the current period: its last
+ * point should equal `value`.
+ *
+ * - **Cards in a row line up by subgrid, not by fixed heights.** The card spans two rows of its
+ *   parent grid (`row-span-2` + `grid-template-rows: subgrid`): row 1 is the body (label, value,
+ *   delta, previous actual, target bar), row 2 the footer. Cards placed directly in one grid
+ *   (`grid grid-cols-2 lg:grid-cols-4 gap-4`) therefore share the value baseline and the footer's
+ *   top edge, and the sparkline sits at the footer's bottom. Outside such a grid the card is a
+ *   plain grid of the same two rows. The label is one line (truncated, full text in `title`).
+ *   When the card is narrower than 250px the delta moves from the right of the value to
+ *   under it (container query, no prop).
+ * - **Nothing empty is drawn.** A card with no summary, record badge, target line, source,
+ *   update time or sparkline has no footer in the DOM; there is no placeholder for the target
+ *   bar either. No `h-*` / `min-h-*` is used to line cards up.
+ * - **`size="sm"`** is for two cards side by side in a narrow place (a Sheet): one step smaller
+ *   value and padding, and no sparkline.
+ * - **`source` is at most two lines** (`line-clamp-2`, full text in `title`).
+ * - **Labels follow the grain.** The grain is `comparison.grain`, else
+ *   `historyGrain`, else inferred from `period`; a monthly card reads "前月比" /
+ *   "前年同月比" and projects to "月末". Without any of them it reads "前期比".
+ *   Any other baseline is `vs: "custom"` with a `label` ("昨日比"); the previous
+ *   line takes its name from it ("昨日 617"), the same way a `label` on any `vs` does.
+ * - **Two or more comparisons sit under the value**, not beside it, so the value
+ *   keeps its place and its width whatever the card holds.
+ * - **`betterWhen` drives everything.** With `betterWhen="down"` the target
+ *   is met at or below it, and the record badge marks the lowest value.
+ * - **Rates change in points.** With a `percent` format the delta and
+ *   `{difference}` are in percentage points ("-0.5pt"); `change="relative"` opts
+ *   back into the change rate. The target line follows: "目標 95% まであと 2.8pt"
+ *   instead of a ratio of rates ("97.1% 達成"); `targetDisplay="achievement"` opts back.
+ * - **The value has a fixed size.** It never shrinks to fit: a long value wraps its
+ *   速報 badge instead of truncating, so neighbouring cards keep one baseline.
+ * - **A summary longer than 2 lines is clamped** (full text in `title`), so keep it to one fact.
+ *
+ * Summary placeholders: `{value}` `{delta}` `{difference}` `{previous}` `{label}`
+ * `{target}` `{achievement}` `{remaining}`. Unknown placeholders are left as-is.
+ * If a placeholder's value is missing (e.g. no previous period), the whole
+ * sentence is replaced with "前月の実績がないため、比較できません。" — or dropped
+ * when there is no comparison — so "—" never lands inside a sentence. Write the
+ * sentence around them and never put numbers in the template itself.
+ *
+ * The summary says one fact *beyond* the comparison — composition, target, record,
+ * rate. A template made only of `{delta}` / `{difference}` repeats what the badge
+ * and the previous actual already say, so it logs a dev warning (once).
+ *
+ * @example
+ * import { KpiCard } from "@/components/kpi-card"
+ * // Vantage: import { KpiCard } from "@squadbase/vantage/components"
+ *
+ * <KpiCard
+ *   label="売上（今月）"
+ *   value={48_200_000}
+ *   format="currency"
+ *   comparison={{ previous: 42_900_000, vs: "prior-period" }}
+ *   summary="{label}は前月から {difference}（{delta}）伸びています。"
+ *   target={60_000_000}
+ *   period={{ start: "2026-10-01", end: "2026-11-01" }}
+ * />
+ */
+import type { ComponentProps } from "react"
+
+import { cn } from "@squadbase/vantage/ui"
+import {
+  comparisonBaseline,
+  computeComparison,
+  defaultChangeDisplay,
+  formatChange,
+  type ChangeDisplay,
+  type Comparison,
+  type PeriodGrain,
+  type Polarity,
+} from "@squadbase/vantage/components"
+import { EMPTY_VALUE, formatDate, formatDatesInText, formatDelta, formatKind, formatPoints, formatValue, type ValueFormat } from "@squadbase/vantage/components"
+import { computeTargetProgress, detectRecord, inferPeriodGrain, type KpiPeriod } from "@squadbase/vantage/components"
+import { formatRelativeTime } from "@squadbase/vantage/components"
+import { Sparkline } from "@squadbase/vantage/components"
+import { Badge } from "@squadbase/vantage/ui"
+import { Card, CardAction, CardDescription, CardFooter, CardHeader, CardTitle } from "@squadbase/vantage/ui"
+import { Skeleton } from "@squadbase/vantage/ui"
+import { Delta } from "@squadbase/vantage/components"
+import { SampleBadge, useSampleMark } from "@squadbase/vantage/components"
+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 ---------- */
+
+export interface KpiCardSource {
+  /** Period the data covers (e.g. "2023-04 以降"). ISO year-months / dates in it are written by the card ("2023年4月 以降"). */
+  period?: string
+  /** Number of rows aggregated; formatted by the card ("48,210件から集計"). */
+  count?: number
+  /**
+   * 集計から除いた行数。出典の脚注に「12件を除外」と添える（ja 以外は「12 excluded」）。0 や負の値は出さない。
+   * 除外の理由（テスト用アカウント、欠損など）は `note` に書く。
+   * @example source={{ count: 48_210, excluded: 12, note: "テスト用アカウントを除外" }}
+   */
+  excluded?: number
+  /** Data source name (e.g. "Snowflake"). */
+  name?: string
+  /** 換算・税抜などの脚注。フッターに出す。例: `note: "税抜、1 ドル=150 円で換算"`。数字を使う説明は summary ではなくここへ。 */
+  note?: string
+}
+
+export interface KpiCardProps extends Omit<ComponentProps<"div">, "children"> {
+  /** Metric name (tier 1). */
+  label: string
+  /** Current value (tier 2). null / undefined renders "—". */
+  value: number | null | undefined
+  /**
+   * Value format, also used for previous / target / remaining. Default `"compact"`.
+   * `"currency"` is JPY in 万・億 on a ja page (USD in K・M・B otherwise); `"percent"` takes a ratio (0.021 → 2.1%) and
+   * switches the delta to points. See `formatValue` for the full table.
+   */
+  format?: ValueFormat
+  /** Locale of the numbers and the built-in wording. Default: the page's (`<html lang>`, else `"en-US"`). */
+  locale?: string
+  /**
+   * What the value is compared against; drives the delta (tier 3) and previous line (tier 4).
+   * 前期・前年・目標以外は `vs: "custom"` + `label`（バッジの呼び名。末尾の「比」を外した語が前期実績行の呼び名になる）。
+   * @example comparison={{ previous: 617, vs: "custom", label: "昨日比" }}
+   */
+  comparison?: Comparison
+  /**
+   * 前年比と前月比など、複数の比較を併記する。先頭だけが前期実績行と summary に使われ、2 つ目以降は Delta 行のみ。`comparison` も渡したらそれが先頭。バッジは値の下に並ぶ。
+   * @example comparisons={[{ previous: 4_290, vs: "prior-period", grain: "month" }, { previous: 3_900, vs: "prior-year", grain: "month" }]}  /  comparisons={[{ previous: 617, vs: "custom", label: "昨日比" }, { previous: 590, vs: "custom", label: "先週の同じ曜日比" }]}
+   */
+  comparisons?: Comparison[]
+  /**
+   * 確定前の値。値の隣に「速報」バッジを出し、目標の「達成」を言い切らず、最高記録の判定も出さない。
+   * @example provisional  /  provisional={{ label: "暫定" }}
+   */
+  provisional?: boolean | { label?: string }
+  /** Which direction is good: `"up"` (default) or `"down"` (churn, error rate). Wins over `polarity`. */
+  betterWhen?: "up" | "down"
+  /** @deprecated Older name of `betterWhen` (`"higher-is-better"` / `"lower-is-better"`). `"neutral"` (never colours the change, skips the target and record logic) is only reachable here. `betterWhen` wins if both are given. */
+  polarity?: Polarity
+  /** `"relative"` ("+12.4%"), `"points"` ("-0.5pt") or `"difference"` ("+¥530万", in `format`). Default: points for a `percent` format, else relative. */
+  change?: ChangeDisplay
+  /** Absolute ratio below which the change reads as flat. Default 0.01. */
+  neutralBand?: number
+  /** Show the previous actual ("前月 400"). Default true; needs `comparison`. */
+  showPrevious?: boolean
+  /** Conclusion sentence template (tier 5); see the placeholders above. */
+  summary?: string
+  /**
+   * Target for the current period. Under the value it adds a 6px bar (actual, the pace
+   * projection, a tick at the target) and one line "目標の 49%・このペースなら 98%"
+   * (the projection only while `period` is in progress). With `betterWhen="down"`
+   * or a rate target (points) there is no bar: "目標 … まであと …" in the footer.
+   */
+  target?: number
+  /**
+   * 目標行・見込み行での目標の呼び名。既定「目標」。予算・計画・ノルマなど業務の言葉に合わせる。
+   * @example targetLabel="予算"  // 予算まであと ¥2,934万（98.1% 達成）
+   */
+  targetLabel?: string
+  /**
+   * 目標に対する進み具合の出し方。`"achievement"` は達成率（現在値 ÷ 目標。「98.1% 達成」）、`"points"` は目標との差（「あと 2.8pt」）。
+   * 既定は `format` から決まる: `percent`（率）は `"points"`（率を率で割った達成度は読めない）、それ以外は `"achievement"`。
+   * `"points"` のとき `{achievement}` は目標との符号付きの差（"-2.8pt"）になり、見込み行は出ない。
+   */
+  targetDisplay?: "achievement" | "points"
+  /** Current period; with `target`, adds a pace projection while the period is in progress. */
+  period?: KpiPeriod
+  /** Series ending at the current period (last point = `value`); adds a record badge. */
+  history?: ReadonlyArray<number | null | undefined>
+  /** Grain of `history` (and of the comparison labels). Default: inferred from `period`, else `"month"` for the record. */
+  historyGrain?: PeriodGrain
+  /**
+   * `history` が 6 点以上あるとき、フッター末尾に軸なしのスパークライン（高さ 32px・`--chart-1`・最新点だけドット）を出す。既定 true。
+   * 推移を出したくないカードは `showHistory={false}`（記録バッジは `history` があれば出る）。
+   * @example showHistory={false}
+   */
+  showHistory?: boolean
+  /** Data source footnote. */
+  source?: KpiCardSource
+  /** When the data was last refreshed: "3 分前に更新". 出し方は `updatedAtDisplay`。 */
+  updatedAt?: Date | string | number
+  /**
+   * `updatedAt` の出し方。`"relative"`（既定）は「3 分前に更新」、`"absolute"` は「2026/10/20 14:30 に更新」、
+   * `"both"` は「2026/10/20 14:30 に更新（3 分前）」。絶対時刻は実行環境のタイムゾーンで出す（`timeZone` で固定できる）。
+   * 画面を印刷・スクリーンショットで残すなら、時間が経っても読める `"absolute"` か `"both"`。
+   * @example updatedAtDisplay="absolute"
+   */
+  updatedAtDisplay?: "relative" | "absolute" | "both"
+  /**
+   * `updatedAt` の絶対時刻（`updatedAtDisplay` が `"absolute"` / `"both"`）を出すタイムゾーン（IANA 名。例 `"Asia/Tokyo"`）。
+   * 既定は実行環境（ブラウザ）のタイムゾーン。サーバーとブラウザで表示が食い違う（SSR）なら固定する。「3 分前」には影響しない。
+   * @example updatedAtDisplay="absolute" timeZone="Asia/Tokyo"
+   */
+  timeZone?: string
+  /** Reference time for the projection and relative time (for deterministic rendering). */
+  now?: Date | number
+  /** Render a skeleton with the final shape instead of the values. */
+  isLoading?: boolean
+  /**
+   * `"sm"` は Sheet の中など狭い場所で 2 枚を横に並べるときの小さいサイズ。値の文字と余白が一段小さくなり、スパークラインは出さない。既定 `"default"`。
+   * @example size="sm"
+   */
+  size?: "default" | "sm"
+}
+
+/** Points of `history` from which the footer shows a sparkline (the same bar as the record badge). */
+const SPARKLINE_MIN_POINTS = 6
+
+/** Height of the footer sparkline, in px. */
+const SPARKLINE_HEIGHT = 32
+
+/**
+ * The delta sits right of the value once the card is ≥ 320px wide (a comparison label is ~180px, so narrower cards would overlap the value) (the shadcn
+ * `CardAction` slot) and drops under the value below that — a container query,
+ * so a narrow card needs no prop.
+ */
+const DELTA_PLACEMENT =
+  "col-start-1 row-span-1 row-start-3 justify-self-start @[288px]/card:col-start-2 @[288px]/card:row-span-2 @[288px]/card:row-start-1 @[288px]/card:justify-self-end"
+
+/**
+ * The header is the size container (`@container/card`), not the card: a container sets layout containment, which turns the
+ * card's `grid-rows-subgrid` into a plain grid and the rows stop lining up. Its content box is the card minus both paddings
+ * (32px; 24px for `sm`), so 218px / 288px here are the 250px / 320px card widths. It also owns the gap above the footer.
+ */
+const HEADER_CLASS = "@container/card pb-(--card-spacing)"
+/** A value this long (a huge standard-notation currency) may wrap between digit groups, and its delta then moves under it so the number gets the full row. Ordinary values stay on one line beside the delta. */
+const LONG_VALUE_CHARS = 10
+const DELTA_UNDER_PLACEMENT = "col-start-1 row-span-1 row-start-3 justify-self-start"
+// No grey footer band: value, comparison and notes share one surface, 8px apart (the footer only keeps its subgrid row).
+const KPI_FOOTER_CLASS = "flex-col items-start gap-2 rounded-none border-t-0 bg-transparent pt-0 text-sm"
+
+const PLACEHOLDER = /\{(\w+)\}/g
+
+const TEXT = {
+  ja: {
+    target: "目標",
+    provisional: "速報",
+    joiner: "・",
+    countFrom: (count: string) => `${count}件から集計`,
+    excluded: (count: string) => `${count}件を除外`,
+    noBaseline: (baseline: string) => `${baseline}の実績がないため、比較できません。`,
+    previous: (baseline: string, value: string) => `${baseline} ${value}`,
+    noPrevious: (baseline: string) => `${baseline}の実績なし`,
+    barLead: (tl: string, pct: string) => `${tl}の ${pct}`,
+    pace: (pct: string) => `このペースなら ${pct}`,
+    provisionalSuffix: "（確定前）",
+    provisionalReached: (tl: string, target: string) => `${tl} ${target} に到達（確定前）`,
+    provisionalSoFar: (tl: string, target: string, pct: string) => `${tl} ${target} に対して現時点 ${pct}（確定前）`,
+    provisionalToGo: (tl: string, target: string, distance: string) => `${tl} ${target} まであと ${distance}（確定前）`,
+    provisionalToGoRate: (tl: string, distance: string, pct: string) => `${tl}まであと ${distance}（現時点 ${pct}・確定前）`,
+    met: (tl: string, target: string) => `${tl} ${target} を達成`,
+    toGo: (tl: string, target: string, distance: string) => `${tl} ${target} まであと ${distance}`,
+    reached: (tl: string, target: string) => `${tl} ${target} に到達`,
+    reachedRate: (tl: string, target: string, pct: string) => `${tl} ${target} に到達（${pct} 達成）`,
+    toGoRate: (tl: string, distance: string, pct: string) => `${tl}まであと ${distance}（${pct} 達成）`,
+    progressLabel: (tl: string) => `${tl}に対する進捗`,
+    progressValue: (tl: string, target: string, value: string, pct: string) => `${tl} ${target} に対して ${value}（${pct}）`,
+    history: (label: string, points: number) => `${label}の推移（直近 ${points} 点）`,
+    updatedRelative: (relative: string) => `${relative}に更新`,
+    updatedAbsolute: (absolute: string) => `${absolute} に更新`,
+    updatedBoth: (absolute: string, relative: string) => `${absolute} に更新（${relative}）`,
+    summaryExample: "{label}は目標の {achievement} まで来ています。",
+  },
+  en: {
+    target: "Target",
+    provisional: "Preliminary",
+    joiner: " · ",
+    countFrom: (count: string) => `Based on ${count} records`,
+    excluded: (count: string) => `${count} excluded`,
+    noBaseline: (baseline: string) => `No ${baseline} data to compare against.`,
+    previous: (baseline: string, value: string) => `${capitalize(baseline)}: ${value}`,
+    noPrevious: (baseline: string) => `No ${baseline} data`,
+    barLead: (tl: string, pct: string) => `${tl}: ${pct}`,
+    pace: (pct: string) => `On pace for ${pct}`,
+    provisionalSuffix: " (preliminary)",
+    provisionalReached: (tl: string, target: string) => `${tl} ${target}: reached (preliminary)`,
+    provisionalSoFar: (tl: string, target: string, pct: string) => `${tl} ${target}: ${pct} so far (preliminary)`,
+    provisionalToGo: (tl: string, target: string, distance: string) => `${tl} ${target}: ${distance} to go (preliminary)`,
+    provisionalToGoRate: (tl: string, distance: string, pct: string) => `${tl}: ${distance} to go (${pct} so far, preliminary)`,
+    met: (tl: string, target: string) => `${tl} ${target}: met`,
+    toGo: (tl: string, target: string, distance: string) => `${tl} ${target}: ${distance} to go`,
+    reached: (tl: string, target: string) => `${tl} ${target}: reached`,
+    reachedRate: (tl: string, target: string, pct: string) => `${tl} ${target}: reached (${pct} achieved)`,
+    toGoRate: (tl: string, distance: string, pct: string) => `${tl}: ${distance} to go (${pct} achieved)`,
+    progressLabel: (tl: string) => `Progress toward ${tl}`,
+    progressValue: (tl: string, target: string, value: string, pct: string) => `${value} of ${tl} ${target} (${pct})`,
+    history: (label: string, points: number) => `${label} trend (last ${points} points)`,
+    updatedRelative: (relative: string) => `Updated ${relative}`,
+    updatedAbsolute: (absolute: string) => `Updated ${absolute}`,
+    updatedBoth: (absolute: string, relative: string) => `Updated ${absolute} (${relative})`,
+    summaryExample: "{label} is at {achievement} of target.",
+  },
+} satisfies Record<UiLanguage, unknown>
+
+type KpiText = (typeof TEXT)[UiLanguage]
+
+function capitalize(text: string): string {
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+const isMissing = (v: string | null | undefined) => v === null || v === undefined || v === ""
+
+/**
+ * Fill `{name}` placeholders from `values`. Unknown names stay as written.
+ *
+ * Without `fallback`, a known name whose value is null / undefined / empty
+ * becomes "—". With `fallback`, any such missing value replaces the whole
+ * sentence with `fallback` (which may be null to drop it).
+ */
+export function fillKpiTemplate(template: string, values: Readonly<Record<string, string | null | undefined>>): string
+export function fillKpiTemplate(
+  template: string,
+  values: Readonly<Record<string, string | null | undefined>>,
+  fallback: string | null,
+): string | null
+export function fillKpiTemplate(
+  template: string,
+  values: Readonly<Record<string, string | null | undefined>>,
+  fallback?: string | null,
+): string | null {
+  let missing = false
+  const filled = template.replace(PLACEHOLDER, (match, name: string) => {
+    if (!Object.prototype.hasOwnProperty.call(values, name)) return match
+    const v = values[name]
+    if (isMissing(v)) {
+      missing = true
+      return EMPTY_VALUE
+    }
+    return v as string
+  })
+  return missing && fallback !== undefined ? fallback : filled
+}
+
+const SHALLOW_SUMMARY_PLACEHOLDERS = new Set(["delta", "difference"])
+
+let shallowSummaryWarned = false
+
+/** @internal Lets tests observe the once-only dev warning again. */
+export function resetKpiSummaryWarning() {
+  shallowSummaryWarned = false
+}
+
+/** True when every placeholder is `{delta}` / `{difference}` — the template only restates the badge. */
+function isShallowSummary(template: string): boolean {
+  const names = Array.from(template.matchAll(PLACEHOLDER), (m) => m[1] as string)
+  return names.length > 0 && names.every((n) => SHALLOW_SUMMARY_PLACEHOLDERS.has(n))
+}
+
+// Bundlers replace `process.env.NODE_ENV` textually; a browser without that define has no `process`.
+declare const process: { env: { NODE_ENV?: string } }
+
+function isProduction(): boolean {
+  try {
+    return process.env.NODE_ENV === "production"
+  } catch {
+    return true
+  }
+}
+
+function warnShallowSummary(template: string, t: KpiText) {
+  if (shallowSummaryWarned || isProduction() || !isShallowSummary(template)) return
+  shallowSummaryWarned = true
+  console.warn(
+    `[KpiCard] summary="${template}" only repeats the delta badge and the previous actual. Say one fact beyond the comparison — composition, target, record or rate (e.g. "${t.summaryExample}").`,
+  )
+}
+
+/** Splits formatted text after each thousands separator so a huge standard-notation value wraps between digit groups instead of clipping. The text itself is unchanged. */
+function digitGroups(text: string): string[] {
+  return text.match(/[^,，]*[,，]|[^,，]+$/g) ?? [text]
+}
+
+export function KpiCard({
+  label,
+  value,
+  format,
+  locale: localeProp,
+  comparison: comparisonProp,
+  comparisons,
+  provisional,
+  betterWhen,
+  polarity: polarityProp,
+  change,
+  neutralBand,
+  showPrevious = true,
+  summary,
+  target,
+  targetLabel,
+  targetDisplay,
+  period,
+  history,
+  historyGrain,
+  showHistory = true,
+  source,
+  updatedAt,
+  updatedAtDisplay = "relative",
+  timeZone,
+  now,
+  isLoading = false,
+  size = "default",
+  className,
+  ...props
+}: KpiCardProps) {
+  const locale = useLocale(localeProp)
+  const t = TEXT[uiLanguage(locale)]
+  const allComparisons = [...(comparisonProp ? [comparisonProp] : []), ...(comparisons ?? [])]
+  const comparison = allComparisons[0]
+  const isProvisional = provisional !== undefined && provisional !== false
+  const provisionalLabel = typeof provisional === "object" && provisional.label ? provisional.label : t.provisional
+  const sample = useSampleMark()
+  // `betterWhen` is the documented name and wins over the older `polarity`.
+  const polarity: Polarity | undefined = betterWhen ? (betterWhen === "down" ? "lower-is-better" : "higher-is-better") : polarityProp
+  const neutral = polarity === "neutral"
+  const hasPrevious = comparison !== undefined && showPrevious
+  // Two or more badges would squeeze the value from the right; they get their own row under it instead.
+  const stacked = allComparisons.length > 1
+  const hasTarget = target !== undefined
+  const grain = comparison?.grain ?? historyGrain ?? inferPeriodGrain(period)
+  const record = isProvisional || neutral ? null : detectRecord(history, historyGrain ?? grain, polarity, locale)
+  const sourceParts = source
+    ? [
+        source.period !== undefined ? formatDatesInText(source.period, locale) : undefined,
+        source.count !== undefined ? t.countFrom(formatValue(source.count, "number", locale)) : undefined,
+        source.excluded !== undefined && Number.isFinite(source.excluded) && source.excluded > 0
+          ? t.excluded(formatValue(source.excluded, "number", locale))
+          : undefined,
+        source.name,
+        source.note,
+      ].filter((p): p is string => typeof p === "string" && p !== "")
+    : []
+  const hasUpdated = updatedAt !== undefined
+  const historyPoints = (history ?? []).filter((v): v is number => typeof v === "number" && Number.isFinite(v))
+  const small = size === "sm"
+  const showSparkline = !small && showHistory && historyPoints.length >= SPARKLINE_MIN_POINTS
+  const isRate = formatKind(format) === "percent"
+  const byPoints = (targetDisplay ?? (isRate ? "points" : "achievement")) === "points"
+  const lower = polarity === "lower-is-better"
+  // The bar reads "how far toward the target"; a rate (points) or a lower-is-better target has no such fill.
+  const targetBar = hasTarget && !neutral && !byPoints && !lower
+  if (summary !== undefined) warnShallowSummary(summary, t)
+  // Two rows of the parent grid (body, footer), shared by subgrid; a plain two-row grid when standalone.
+  const cardClass = cn("row-span-2 grid content-start gap-y-0 grid-rows-subgrid", className)
+  const valueSize = small ? "text-xl @[218px]/card:text-2xl" : "text-2xl @[218px]/card:text-4xl"
+
+  if (isLoading) {
+    return (
+      <Card
+        data-slot="kpi-card"
+        data-loading=""
+        aria-busy="true"
+        size={size}
+        className={cardClass}
+        {...props}
+      >
+        <CardHeader className={HEADER_CLASS}>
+          <CardDescription className="col-start-1">
+            <span className="sr-only">{label}</span>
+            <Skeleton aria-hidden="true" className="h-5 w-24" />
+          </CardDescription>
+          <CardTitle className="col-start-1 flex items-center gap-2">
+            <Skeleton aria-hidden="true" className={small ? "h-7 w-28 @[218px]/card:h-8" : "h-8 w-32 @[218px]/card:h-9"} />
+            {/* The mark stays while loading, so the header does not shift when the values arrive. */}
+            {sample && <SampleBadge label={sample.label} />}
+          </CardTitle>
+          {comparison &&
+            (stacked ? (
+              <div className="flex flex-wrap gap-1">
+                {allComparisons.map((_, i) => (
+                  <Skeleton key={i} aria-hidden="true" className="h-5 w-24 rounded-4xl" />
+                ))}
+              </div>
+            ) : (
+              <CardAction className={DELTA_PLACEMENT}>
+                <Skeleton aria-hidden="true" className="h-5 w-24 rounded-4xl" />
+              </CardAction>
+            ))}
+          {hasPrevious && <Skeleton aria-hidden="true" className="h-5 w-16" />}
+          {targetBar ? (
+            <div className="col-span-full mt-1 flex flex-col gap-1.5">
+              <Skeleton aria-hidden="true" className="h-2 w-full rounded-full" />
+              <Skeleton aria-hidden="true" className="h-5 w-3/5" />
+            </div>
+          ) : null}
+        </CardHeader>
+        {(summary || record || (hasTarget && !targetBar) || sourceParts.length > 0 || hasUpdated || showSparkline) && (
+          <CardFooter className={KPI_FOOTER_CLASS}>
+            {summary && <Skeleton aria-hidden="true" className="h-5 w-4/5" />}
+            {record && <Skeleton aria-hidden="true" className="h-5 w-28 rounded-4xl" />}
+            {hasTarget && !targetBar && <Skeleton aria-hidden="true" className="h-5 w-3/5" />}
+            {sourceParts.length > 0 && <Skeleton aria-hidden="true" className="h-4 w-3/4" />}
+            {hasUpdated && <Skeleton aria-hidden="true" className="h-4 w-20" />}
+            {showSparkline && <Skeleton aria-hidden="true" className="mt-auto h-8 w-full" />}
+          </CardFooter>
+        )}
+      </Card>
+    )
+  }
+
+  const fmt = (v: number | null | undefined) => formatValue(v, format, locale)
+  /** An unsigned distance in the metric's unit — points for a rate. */
+  const fmtDistance = (v: number) => (isRate ? formatPoints(v, locale, { signDisplay: "never" }) : fmt(v))
+  const pct = (v: number) => formatValue(v, { type: "percent", digits: 0 }, locale)
+  const tl = targetLabel ?? t.target
+  const display = change ?? defaultChangeDisplay(format)
+  // Value digits only carry over to a change in points; a relative change keeps its own fixed digits.
+  const digits =
+    display === "points" && typeof format === "object" && format !== null && "digits" in format ? format.digits : undefined
+  const graded = comparison ? { ...comparison, grain } : undefined
+  const result = graded ? computeComparison(value, graded, { polarity, neutralBand, locale }) : null
+  const baseline = graded ? comparisonBaseline(graded.vs, grain, graded.label, graded.toDate, locale) : null
+  const progress = hasTarget && !neutral ? computeTargetProgress(value, target, { period, now, polarity }) : null
+  // A linear pace only makes sense for an accumulating total, not for a rate.
+  const projectedValue =
+    !isRate && !byPoints && progress?.projected != null && progress.elapsed ? (value as number) / progress.elapsed : null
+
+  const summaryText = summary
+    ? fillKpiTemplate(
+        summary,
+        {
+          value: fmt(value),
+          label,
+          delta: result ? formatChange(result, display, locale, format, digits) : null,
+          difference:
+            result?.difference != null
+              ? isRate
+                ? formatPoints(result.difference, locale)
+                : formatDelta(result.difference, format, locale)
+              : null,
+          previous: result?.previous != null ? fmt(result.previous) : null,
+          target: hasTarget ? fmt(target) : null,
+          achievement: progress
+            ? byPoints
+              ? formatPoints((value as number) - (target as number), locale)
+              : pct(progress.achievement)
+            : null,
+          remaining: progress ? fmtDistance(progress.remaining) : null,
+        },
+        result && result.direction === "none" && baseline ? t.noBaseline(baseline) : null,
+      )
+    : null
+
+  // Target bar: actual, the pace projection and a tick at the target on one scale.
+  const bar = targetBar && progress ? progressBar() : null
+
+  function progressBar() {
+    const actual = Math.max(value as number, 0)
+    const projected = projectedValue !== null && projectedValue > actual ? projectedValue : actual
+    const scale = Math.max(target as number, actual, projected)
+    const at = (v: number) => (scale > 0 ? (v / scale) * 100 : 0)
+    const parts = [t.barLead(tl, pct(progress!.achievement))]
+    if (projectedValue !== null && progress!.projected != null)
+      parts.push(t.pace(formatValue(progress!.projected, { type: "percent", digits: 0 }, locale)))
+    return {
+      actualAt: at(actual),
+      projectedAt: at(projected),
+      targetAt: at(target as number),
+      lead: parts[0] as string,
+      pace: parts[1] ?? null,
+    }
+  }
+
+  let targetText: string | null = null
+  if (hasTarget && !bar) {
+    if (!progress) targetText = `${tl} ${fmt(target)}`
+    else if (isProvisional)
+      targetText = progress.achieved
+        ? byPoints
+          ? t.provisionalReached(tl, fmt(target))
+          : t.provisionalSoFar(tl, fmt(target), pct(progress.achievement))
+        : byPoints
+          ? t.provisionalToGo(tl, fmt(target), fmtDistance(progress.remaining))
+          : t.provisionalToGoRate(tl, fmtDistance(progress.remaining), pct(progress.achievement))
+    else if (lower)
+      targetText = progress.achieved
+        ? t.met(tl, fmt(target))
+        : t.toGo(tl, fmt(target), fmtDistance(progress.remaining))
+    else if (byPoints)
+      targetText = progress.achieved
+        ? t.reached(tl, fmt(target))
+        : t.toGo(tl, fmt(target), fmtDistance(progress.remaining))
+    else
+      targetText = progress.achieved
+        ? t.reachedRate(tl, fmt(target), pct(progress.achievement))
+        : t.toGoRate(tl, fmtDistance(progress.remaining), pct(progress.achievement))
+  }
+
+  const hasFooter =
+    Boolean(summaryText) || record !== null || Boolean(targetText) || sourceParts.length > 0 || hasUpdated || showSparkline
+
+  const deltas = allComparisons.map((c, i) => (
+    <Delta
+      key={i}
+      value={value}
+      comparison={i === 0 ? (graded ?? c) : { ...c, grain: c.grain ?? grain }}
+      polarity={polarity}
+      neutralBand={neutralBand}
+      format={format}
+      change={display}
+      digits={digits}
+      locale={locale}
+    />
+  ))
+
+  const valueText = fmt(value)
+  const longValue = valueText.length > LONG_VALUE_CHARS
+
+  return (
+    <Card data-slot="kpi-card" size={size} className={cardClass} {...props}>
+      <CardHeader className={HEADER_CLASS}>
+        <CardDescription data-slot="kpi-card-label" title={label} className="col-start-1 min-w-0 truncate text-[13px] leading-snug font-medium text-muted-foreground">
+          {label}
+        </CardDescription>
+        <CardTitle
+          data-slot="kpi-card-value"
+          title={valueText}
+          className={cn(
+            "col-start-1 flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 leading-none font-semibold tracking-tight tabular-nums",
+            // Fixed size: the step follows the card width only, never the length of the value.
+            valueSize,
+          )}
+        >
+          <span data-slot="kpi-card-value-text" className={longValue ? "min-w-0 break-words" : "whitespace-nowrap"}>
+            {longValue
+              ? digitGroups(valueText).map((group, i) => (
+                  <span key={i} className="whitespace-nowrap">
+                    {group}
+                    <wbr />
+                  </span>
+                ))
+              : valueText}
+          </span>
+          {isProvisional && (
+            <Badge data-slot="kpi-card-provisional" variant="outline" className="align-middle">
+              {provisionalLabel}
+            </Badge>
+          )}
+          {sample && <SampleBadge label={sample.label} />}
+        </CardTitle>
+        {comparison &&
+          (stacked ? (
+            <div data-slot="kpi-card-comparisons" className="flex flex-wrap items-center gap-1">
+              {deltas}
+            </div>
+          ) : (
+            <CardAction className={longValue ? DELTA_UNDER_PLACEMENT : DELTA_PLACEMENT}>{deltas}</CardAction>
+          ))}
+        {hasPrevious && comparison && (
+          <div data-slot="kpi-card-previous" className="col-span-full text-sm text-muted-foreground tabular-nums">
+            {result?.previous != null ? t.previous(baseline ?? "", fmt(result.previous)) : t.noPrevious(baseline ?? "")}
+          </div>
+        )}
+        {bar && progress && (
+          <div data-slot="kpi-card-target-progress" className="col-span-full mt-1 flex min-w-0 flex-col gap-1.5">
+            <div
+              data-slot="kpi-card-target-bar"
+              role="progressbar"
+              aria-label={t.progressLabel(tl)}
+              aria-valuemin={0}
+              aria-valuemax={target}
+              aria-valuenow={Math.min(Math.max(value as number, 0), target as number)}
+              aria-valuetext={t.progressValue(tl, fmt(target), fmt(value), pct(progress.achievement))}
+              className="relative h-2 w-full overflow-hidden rounded-full bg-muted"
+            >
+              <div className="absolute inset-y-0 left-0 bg-chart-1" style={{ width: `${bar.actualAt}%` }} />
+              {bar.projectedAt > bar.actualAt && (
+                <div
+                  data-slot="kpi-card-target-bar-projection"
+                  className="absolute inset-y-0 bg-chart-1/30 dark:bg-chart-1/45"
+                  style={{ left: `${bar.actualAt}%`, width: `${bar.projectedAt - bar.actualAt}%` }}
+                />
+              )}
+              <div
+                data-slot="kpi-card-target-bar-tick"
+                className="absolute inset-y-0 w-px bg-foreground"
+                style={{ left: `${bar.targetAt}%`, transform: bar.targetAt >= 100 ? "translateX(-1px)" : undefined }}
+              />
+            </div>
+            <p
+              data-slot="kpi-card-target"
+              title={[bar.lead, bar.pace].filter(Boolean).join(t.joiner)}
+              className="truncate text-sm text-muted-foreground tabular-nums"
+            >
+              {bar.lead}
+              {bar.pace && (
+                <>
+                  {t.joiner}
+                  <span data-slot="kpi-card-projection" data-estimate="">{bar.pace}</span>
+                </>
+              )}
+              {isProvisional && t.provisionalSuffix}
+            </p>
+          </div>
+        )}
+      </CardHeader>
+      {hasFooter && (
+        <CardFooter className={KPI_FOOTER_CLASS}>
+          {summaryText && (
+            <p data-slot="kpi-card-summary" title={summaryText} className="line-clamp-2 text-sm leading-relaxed text-muted-foreground tabular-nums">
+              {summaryText}
+            </p>
+          )}
+          {record && (
+            <Badge data-slot="kpi-card-record" variant="outline">
+              {record.label}
+            </Badge>
+          )}
+          {targetText && (
+            <p data-slot="kpi-card-target" className="text-muted-foreground tabular-nums">
+              {targetText}
+            </p>
+          )}
+          {sourceParts.length > 0 && (
+            <p
+              data-slot="kpi-card-source"
+              title={sourceParts.join(t.joiner)}
+              className="line-clamp-2 w-full text-xs leading-normal text-muted-foreground tabular-nums"
+            >
+              {sourceParts.join(t.joiner)}
+            </p>
+          )}
+          {hasUpdated && (
+            <p data-slot="kpi-card-updated" className="text-xs leading-normal text-muted-foreground">
+              {updatedAtText(updatedAt, updatedAtDisplay, locale, t, now, timeZone)}
+            </p>
+          )}
+          {showSparkline && (
+            // mt-auto: the footers of a row are as tall as the tallest, so the sparklines share one bottom edge.
+            <div data-slot="kpi-card-history" className="mt-auto w-full pt-2 text-chart-1">
+              <Sparkline
+                data={historyPoints.map((v) => ({ value: v }))}
+                height={SPARKLINE_HEIGHT}
+                color="text-chart-1"
+                highlight="latest"
+                aria-label={t.history(label, historyPoints.length)}
+              />
+            </div>
+          )}
+        </CardFooter>
+      )}
+    </Card>
+  )
+}
+
+/** 「3 分前に更新」「2026/10/20 14:30 に更新」「2026/10/20 14:30 に更新（3 分前）」（英語は "Updated 3 minutes ago" など）。 */
+function updatedAtText(
+  updatedAt: Date | string | number,
+  display: "relative" | "absolute" | "both",
+  locale: string,
+  t: KpiText,
+  now: Date | number | undefined,
+  timeZone?: string,
+): string {
+  const relative = formatRelativeTime(updatedAt, { now, locale })
+  if (display === "relative") return t.updatedRelative(relative)
+  const absolute = formatDate(updatedAt, "datetime", locale, { timeZone })
+  return display === "absolute" ? t.updatedAbsolute(absolute) : t.updatedBoth(absolute, relative)
+}