@squadbase/vantage 0.6.2-dev1.9365dcd → 0.6.2-dev1.9d7130b

package/registry/ui/date-range-picker.tsx

@@ -5,7 +5,8 @@
 /**
  * DateRangePicker — a range calendar in a popover with quick presets down the
  * side. On mobile the presets stack above a single month; on desktop they sit
- * beside a two-month view.
+ * beside a two-month view. The labels, the date format, the fiscal year start and the
+ * first day of the week follow the page (`<html lang>`) unless `locale` is given.
  */
 import { forwardRef, useCallback, useMemo, useState } from "react"
 import { CalendarIcon } from "lucide-react"
@@ -14,7 +15,6 @@ import {
   endOfDay,
   endOfMonth,
   endOfWeek,
-  format,
   isSameDay,
   startOfDay,
   startOfMonth,
@@ -28,30 +28,169 @@ import type { DateRange as RdpDateRange } from "react-day-picker"
 
 import { cn } from "@squadbase/vantage/ui"
 import { useIsMobile } from "@squadbase/vantage/ui"
+import { formatDate } from "@squadbase/vantage/components"
 import { Button } from "@squadbase/vantage/ui"
 import { Calendar } from "@squadbase/vantage/ui"
 import { Popover, PopoverContent, PopoverTrigger } from "@squadbase/vantage/ui"
 import type { DateRange, PresetItem } from "@squadbase/vantage/components"
+import { useSyncExternalStore } from "react"
 
-/** 会計年度の開始月の既定（4 月始まり）。 */
-export const DEFAULT_FISCAL_YEAR_START_MONTH = 4
+/* ---------- inlined from @squadbase/squadkit registry/lib/locale.ts (internal to @squadbase/vantage) ---------- */
 
 /**
- * ラベルの言語の既定（英語）。他部品の `DEFAULT_LOCALE`（ja-JP）とは違い、この部品だけ英語を既定にしている。
- * 従来のプリセットが英語で、既存の利用者の見た目を変えないため。日本語にするなら `locale="ja-JP"` を渡す。
+ * 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.
  */
-export const DEFAULT_DATE_PICKER_LOCALE = "en-US"
+function useDocumentLocale(): string {
+  return useSyncExternalStore(subscribe, documentLocale, serverLocale)
+}
 
-/** 1〜12 の整数だけを開始月として受け、それ以外は既定の 4 月に戻す。 */
-export function normalizeFiscalYearStartMonth(month: number | undefined): number {
+/** 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 ---------- */
+
+/**
+ * 会計年度の開始月のフォールバック（1 月始まり）。ロケールから決まる既定は `defaultFiscalYearStartMonth`
+ * （`<html lang>` が ja なら 4 月、それ以外は 1 月）。
+ */
+export const DEFAULT_FISCAL_YEAR_START_MONTH = 1
+
+/** ラベルの言語のフォールバック（英語）。`locale` を渡さなければ、ほかの部品と同じくページの `<html lang>` に従う。 */
+export const DEFAULT_DATE_PICKER_LOCALE = FALLBACK_LOCALE
+
+/**
+ * 1〜12 の整数だけを開始月として受け、それ以外は `locale` の既定（ja は 4 月、それ以外は 1 月）に戻す。
+ * `locale` の既定はページのロケール（`<html lang>`）。
+ */
+export function normalizeFiscalYearStartMonth(month: number | undefined, locale?: string): number {
   return typeof month === "number" && Number.isInteger(month) && month >= 1 && month <= 12
     ? month
-    : DEFAULT_FISCAL_YEAR_START_MONTH
+    : defaultFiscalYearStartMonth(locale)
 }
 
 /**
  * `date` を含む年度（または年度基準の四半期）の全期間。`offset` で前後にずらす（`-1` が前の年度/四半期）。
  * 年度は `fiscalYearStartMonth`（1-12）の 1 日に始まり 12 か月続く。四半期は年度の初日から 3 か月ごと。
+ * `fiscalYearStartMonth` を省くと `locale`（既定はページのロケール）の既定（ja は 4 月、それ以外は 1 月）。
  *
  * @example
  * // 4 月始まりで 2026-02-10 は 2025 年度（2025-04-01〜2026-03-31）
@@ -59,9 +198,14 @@ export function normalizeFiscalYearStartMonth(month: number | undefined): number
  */
 export function fiscalPeriodRange(
   date: Date,
-  { unit, fiscalYearStartMonth, offset = 0 }: { unit: "year" | "quarter"; fiscalYearStartMonth?: number; offset?: number },
+  {
+    unit,
+    fiscalYearStartMonth,
+    offset = 0,
+    locale,
+  }: { unit: "year" | "quarter"; fiscalYearStartMonth?: number; offset?: number; locale?: string },
 ): { from: Date; to: Date } {
-  const startMonth = normalizeFiscalYearStartMonth(fiscalYearStartMonth)
+  const startMonth = normalizeFiscalYearStartMonth(fiscalYearStartMonth, locale)
   const length = unit === "year" ? 12 : 3
   const sinceYearStart = (date.getMonth() - (startMonth - 1) + 12) % 12
   const into = unit === "year" ? sinceYearStart : sinceYearStart % 3
@@ -106,29 +250,33 @@ const PRESET_LABELS = {
   },
 } as const
 
-const isJapanese = (locale: string) => locale.toLowerCase().startsWith("ja")
-
-/** 週の始まり（月曜）。日本のビジネス慣習に合わせ、「今週」「先週」はどの locale でも月曜始まり。 */
-const WEEK_OPTIONS = { weekStartsOn: 1 } as const
+const TEXT = {
+  ja: { placeholder: "期間を選択", rangeSeparator: " - " },
+  en: { placeholder: "Pick a date range", rangeSeparator: " – " },
+}
 
 /** カレンダーに渡す date-fns の locale。`ja*` なら日本語、それ以外は react-day-picker の既定（英語）。 */
-const calendarLocale = (locale: string) => (isJapanese(locale) ? ja : undefined)
+const calendarLocale = (locale: string) => (uiLanguage(locale) === "ja" ? ja : undefined)
 
 /**
  * 既定のプリセット一覧を作る。ラベルは `locale`（`ja*` なら日本語、それ以外は英語）、
- * 「今四半期」「前四半期」「今年度」「前年度」は `fiscalYearStartMonth` を基準にする。
- * 「今〜」は期の初日から今日まで、「前〜」「先月」「先週」は前の期の全期間。週は月曜始まり。`getValue` は押した時点の日付で計算する。
+ * 「今四半期」「前四半期」「今年度」「前年度」は `fiscalYearStartMonth`（省くと ja は 4 月、それ以外は 1 月）を基準にする。
+ * 「今〜」は期の初日から今日まで、「前〜」「先月」「先週」は前の期の全期間。週の始まりは `locale` の慣習
+ * （ja は月曜、`en-US` は日曜、`en-GB` は月曜。`weekStartsOn`）。`getValue` は押した時点の日付で計算する。
+ * `locale` の既定はページのロケール（`<html lang>`、無ければ `"en-US"`）。
  *
  * @example
  * createDatePresets({ locale: "ja-JP", fiscalYearStartMonth: 4 })
  */
 export function createDatePresets({
-  locale = DEFAULT_DATE_PICKER_LOCALE,
-  fiscalYearStartMonth = DEFAULT_FISCAL_YEAR_START_MONTH,
+  locale: localeArg,
+  fiscalYearStartMonth,
   now = () => new Date(),
 }: { locale?: string; fiscalYearStartMonth?: number; now?: () => Date } = {}): PresetItem[] {
-  const t = PRESET_LABELS[isJapanese(locale) ? "ja" : "en"]
-  const startMonth = normalizeFiscalYearStartMonth(fiscalYearStartMonth)
+  const locale = resolveLocale(localeArg)
+  const t = PRESET_LABELS[uiLanguage(locale)]
+  const startMonth = normalizeFiscalYearStartMonth(fiscalYearStartMonth, locale)
+  const WEEK_OPTIONS = { weekStartsOn: weekStartsOn(locale) }
   const lastDays = (days: number) => () => {
     const today = now()
     return { from: startOfDay(subDays(today, days - 1)), to: endOfDay(today) }
@@ -204,8 +352,12 @@ export function findMatchingPreset(presets: PresetItem[], value: DateRange | und
   })
 }
 
-/** 既定のプリセット（英語・4 月始まり）。`locale` / `fiscalYearStartMonth` を変えるなら `createDatePresets` か DateRangePicker の同名 props。 */
-export const defaultPresets: PresetItem[] = createDatePresets()
+/**
+ * フォールバック（`en-US`：英語・1 月始まり・日曜始まり）のプリセット。DateRangePicker は `presets` を渡さなければ
+ * ページのロケールからプリセットを作るので、これを渡す必要はない。`locale` / `fiscalYearStartMonth` を変えるなら
+ * `createDatePresets` か DateRangePicker の同名 props。
+ */
+export const defaultPresets: PresetItem[] = createDatePresets({ locale: FALLBACK_LOCALE })
 
 export interface DateRangePickerProps {
   /**
@@ -231,16 +383,16 @@ export interface DateRangePickerProps {
   presets?: PresetItem[]
   showPresets?: boolean
   /**
-   * プリセットのラベルとカレンダーの月名・曜日の言語。`ja*` なら日本語、それ以外は英語。既定 `"en-US"`（英語）。
-   * 他部品の既定は ja-JP だが、この部品は従来のプリセットが英語だったので既存の見た目を保つため英語を既定にしている。
+   * プリセットのラベル・日付の書式・カレンダーの月名と曜日・週の始まりのロケール。`ja*` なら日本語、それ以外は英語。
+   * 既定はページのロケール（`<html lang>`、無ければ `"en-US"`）。
    *
    * @example
    * <DateRangePicker locale="ja-JP" />
    */
   locale?: string
   /**
-   * 年度の開始月（1-12）。「今年度」「前年度」と、年度基準の「今四半期」「前四半期」の区切りになる。既定 `4`（4 月始まり）。
-   * 範囲外・整数でない値は 4 として扱う。
+   * 年度の開始月（1-12）。「今年度」「前年度」と、年度基準の「今四半期」「前四半期」の区切りになる。
+   * 既定はロケールで決まる（ja は `4`、それ以外は `1`）。範囲外・整数でない値はその既定として扱う。
    *
    * @example
    * <DateRangePicker fiscalYearStartMonth={1} />
@@ -261,11 +413,11 @@ export const DateRangePicker = forwardRef<HTMLDivElement, DateRangePickerProps>(
       onChange,
       presets: presetsProp,
       showPresets = true,
-      locale = DEFAULT_DATE_PICKER_LOCALE,
-      fiscalYearStartMonth = DEFAULT_FISCAL_YEAR_START_MONTH,
+      locale: localeProp,
+      fiscalYearStartMonth,
       maxDate,
       minDate,
-      placeholder = "期間を選択",
+      placeholder,
       disabled = false,
       className,
       align = "start",
@@ -274,6 +426,8 @@ export const DateRangePicker = forwardRef<HTMLDivElement, DateRangePickerProps>(
   ) {
     const [open, setOpen] = useState(false)
     const isMobile = useIsMobile()
+    const locale = useLocale(localeProp)
+    const t = TEXT[uiLanguage(locale)]
     const presets = useMemo(
       () => presetsProp ?? createDatePresets({ locale, fiscalYearStartMonth }),
       [presetsProp, locale, fiscalYearStartMonth],
@@ -295,9 +449,9 @@ export const DateRangePicker = forwardRef<HTMLDivElement, DateRangePickerProps>(
     )
 
     const formatDateRange = () => {
-      if (!value?.from) return placeholder
-      if (!value.to) return format(value.from, "yyyy/MM/dd")
-      return `${format(value.from, "yyyy/MM/dd")} - ${format(value.to, "yyyy/MM/dd")}`
+      if (!value?.from) return placeholder ?? t.placeholder
+      if (!value.to) return formatDate(value.from, "date", locale)
+      return `${formatDate(value.from, "date", locale)}${t.rangeSeparator}${formatDate(value.to, "date", locale)}`
     }
     // 選んだ期間がプリセットの結果と一致するときは、日付の前にそのプリセット名を出す。
     const selectedPreset = findMatchingPreset(presets, value)
@@ -368,7 +522,7 @@ export const DateRangePicker = forwardRef<HTMLDivElement, DateRangePickerProps>(
                 mode="range"
                 defaultMonth={defaultMonth}
                 locale={calendarLocale(locale)}
-                weekStartsOn={isJapanese(locale) ? 1 : undefined}
+                weekStartsOn={weekStartsOn(locale)}
                 numberOfMonths={isMobile ? 1 : 2}
                 selected={calendarSelected}
                 onSelect={handleCalendarSelect}

package/registry/ui/delta.tsx

@@ -4,12 +4,13 @@
 
 /**
  * Delta — the change of a value against a comparison, rendered as arrow + signed
- * change + comparison label ("↑ +12.4% 前月比") on one line.
+ * change + comparison label ("↑ +12.4% vs. prior month"; ja: "↑ +12.4% 前月比") on one line, in the page's
+ * language (`<html lang>`) unless `locale` is given.
  *
  * Direction, rate, colour and wording are all derived here from `value` and
  * `comparison` (via `computeComparison`); none of them can be passed in, so they
  * cannot contradict each other. Colour is never the only signal: the arrow and
- * the sign always accompany it. Set `polarity="lower-is-better"` for metrics
+ * the sign always accompany it. Set `betterWhen="down"` for metrics
  * where a rise is bad (churn, error rate).
  *
  * - A flat change (inside `neutralBand`) uses a right arrow (→), never a minus-like dash, so it cannot
@@ -31,7 +32,7 @@
  * // Vantage: import { Delta } from "@squadbase/vantage/components"
  *
  * <Delta value={48_200_000} comparison={{ previous: 42_900_000, vs: "prior-period", grain: "month" }} />
- * <Delta value={0.021} format="percent" polarity="lower-is-better"
+ * <Delta value={0.021} format="percent" betterWhen="down"
  *   comparison={{ previous: 0.026, vs: "prior-year", grain: "month" }} />
  */
 import { forwardRef, type HTMLAttributes } from "react"
@@ -49,14 +50,148 @@ import {
   type ComparisonResult,
   type Polarity,
 } from "@squadbase/vantage/components"
-import { DEFAULT_LOCALE, EMPTY_VALUE, type ValueFormat } from "@squadbase/vantage/components"
+import { EMPTY_VALUE, type ValueFormat } 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 ---------- */
 
 const deltaVariants = cva(
   "inline-flex w-fit shrink-0 items-center gap-1 font-medium whitespace-nowrap tabular-nums",
   {
     variants: {
       variant: {
-        badge: "h-5 rounded-4xl px-2 py-0.5 text-xs font-semibold [&>svg]:size-3",
+        badge: "h-5 rounded-md border px-2 py-0.5 text-xs font-medium [&>svg]:size-3",
         inline: "text-sm [&>svg]:size-3.5",
       },
       sentiment: {
@@ -66,9 +201,9 @@ const deltaVariants = cva(
       },
     },
     compoundVariants: [
-      { variant: "badge", sentiment: "positive", className: "bg-positive-subtle" },
-      { variant: "badge", sentiment: "negative", className: "bg-negative-subtle" },
-      { variant: "badge", sentiment: "neutral", className: "bg-neutral-subtle" },
+      { variant: "badge", sentiment: "positive", className: "border-positive/20 bg-positive-subtle dark:border-positive/25" },
+      { variant: "badge", sentiment: "negative", className: "border-negative/20 bg-negative-subtle dark:border-negative/25" },
+      { variant: "badge", sentiment: "neutral", className: "border-neutral/20 bg-neutral-subtle dark:border-neutral/25" },
     ],
     defaultVariants: {
       variant: "badge",
@@ -85,7 +220,9 @@ export interface DeltaProps
   value: number | null | undefined
   /** What the value is compared against. Required so the delta always carries its label. */
   comparison: Comparison
-  /** Whether a rise is good. Default `"higher-is-better"`. */
+  /** 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"` is only reachable here. `betterWhen` wins if both are given. */
   polarity?: Polarity
   /** Absolute ratio below which the change reads as flat (0.01 = 1%). Default 0.01. */
   neutralBand?: number
@@ -101,7 +238,7 @@ export interface DeltaProps
    * 同じカード群で桁がばらつかないよう、全部に同じ値を渡す。未指定は 1 桁（"+14.0%"）。`"points"` は未指定のとき `format.digits` に従う。
    */
   digits?: number
-  /** Locale for the change. Default `"ja-JP"`. */
+  /** Locale for the change and its label. Default: the page's (`<html lang>`, else `"en-US"`). */
   locale?: string
   /** Show the comparison label ("前月比") after the change. Default true. */
   showLabel?: boolean
@@ -110,23 +247,42 @@ export interface DeltaProps
 /** Text shown when the values cannot be compared (no previous value, or a zero baseline): the same "—" as every missing value. */
 export const DELTA_NOT_COMPARABLE = EMPTY_VALUE
 
+const ARIA_TEXT = {
+  ja: {
+    none: (label: string) => `${label} 比較できません`,
+    flat: (label: string) => `${label} 横ばい`,
+    points: " ポイント",
+    change: (label: string, amount: string, up: boolean) => `${label} ${amount} ${up ? "増加" : "減少"}`,
+  },
+  en: {
+    none: (label: string) => `${label}: not comparable`,
+    flat: (label: string) => `Flat ${label}`,
+    points: " points",
+    change: (label: string, amount: string, up: boolean) => `${up ? "Up" : "Down"} ${amount} ${label}`,
+  },
+}
+
 /**
- * Screen-reader text, e.g. "前月比 12.4% 増加" / "前月比 0.5 ポイント 減少" / "前月比 横ばい" / "前月比 比較できません".
+ * Screen-reader text, e.g. "Up 12.4% vs. prior month" / "Down 0.5 points vs. prior month" / "Flat vs. prior month" /
+ * "vs. prior month: not comparable" (ja: "前月比 12.4% 増加" / "前月比 0.5 ポイント 減少" / "前月比 横ばい" / "前月比 比較できません").
  * The amount carries no sign, since the verb already says the direction ("−0.5 ポイント 減少" would negate twice).
+ * `locale` defaults to the page's (`<html lang>`).
  */
 export function deltaAriaLabel(
   result: ComparisonResult,
-  locale: string = DEFAULT_LOCALE,
+  locale?: string,
   change: ChangeDisplay = "relative",
   format?: ValueFormat,
   digits?: number,
 ): string {
+  const resolved = resolveLocale(locale)
+  const t = ARIA_TEXT[uiLanguage(resolved)]
   const { label, direction, ratio } = result
-  if (direction === "none" || ratio === null) return `${label} 比較できません`
-  if (direction === "flat") return `${label} 横ばい`
-  const amount = formatChangeAmount(result, change, locale, format, digits)
-  if (amount === null) return `${label} 比較できません`
-  return `${label} ${change === "points" ? amount.replace(/pt$/, " ポイント") : amount} ${direction === "up" ? "増加" : "減少"}`
+  if (direction === "none" || ratio === null) return t.none(label)
+  if (direction === "flat") return t.flat(label)
+  const amount = formatChangeAmount(result, change, resolved, format, digits)
+  if (amount === null) return t.none(label)
+  return t.change(label, change === "points" ? amount.replace(/pt$/, t.points) : amount, direction === "up")
 }
 
 export const Delta = forwardRef<HTMLSpanElement, DeltaProps>(
@@ -134,12 +290,13 @@ export const Delta = forwardRef<HTMLSpanElement, DeltaProps>(
     {
       value,
       comparison,
+      betterWhen,
       polarity,
       neutralBand,
       format,
       change,
       digits,
-      locale = DEFAULT_LOCALE,
+      locale: localeProp,
       showLabel = true,
       variant = "badge",
       className,
@@ -147,9 +304,14 @@ export const Delta = forwardRef<HTMLSpanElement, DeltaProps>(
     },
     ref,
   ) => {
+    const locale = useLocale(localeProp)
     // Nothing to compare against yet (a draft fills props in steps).
     if (!comparison) return null
-    const result = computeComparison(value, comparison, { polarity, neutralBand })
+    const result = computeComparison(value, comparison, {
+      polarity: betterWhen ? (betterWhen === "down" ? "lower-is-better" : "higher-is-better") : polarity,
+      neutralBand,
+      locale,
+    })
     const display = change ?? defaultChangeDisplay(format)
     const formatDigits = typeof format === "object" && format !== null && "digits" in format ? format.digits : undefined
     const changeDigits = display === "points" ? (digits ?? formatDigits) : digits