basalt-ui 1.27.0 → 1.29.0

package/src/format/date.ts

@@ -0,0 +1,184 @@
+/**
+ * Date/time/duration formatting. `fmtAxisDate`/`fmtTooltipDate` moved here from
+ * `src/charts/utils/format.ts` (C5 consolidation) — that file now re-exports from this module.
+ * The rest (`clock`/`weekday`/`relativeTime`/`duration`/`durationClock`) are new, seeded from argo
+ * consumers (`features/{walking-pad,reading,astro-window,garmin-health}/{formatters,format,
+ * formulas}.ts` — read those files' own JSDoc for the exact call sites this generalizes).
+ */
+import { dateFormat, NON_FINITE, toDate } from './shared'
+import type { LocaleOption } from './shared'
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+const SHORT_DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+
+/** Axis-friendly short date: DD.MM. A non-finite or invalid date prints {@link NON_FINITE}. */
+export function fmtAxisDate(value: unknown): string {
+  if (typeof value === 'number' && !Number.isFinite(value)) return NON_FINITE
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return NON_FINITE
+    const dd = String(value.getDate()).padStart(2, '0')
+    const mm = String(value.getMonth() + 1).padStart(2, '0')
+    return `${dd}.${mm}`
+  }
+  const s = String(value ?? '')
+  const match = s.match(/(\d{4})-(\d{2})-(\d{2})/)
+  if (match) return `${match[3]}.${match[2]}`
+  return s
+}
+
+/** Tooltip-friendly long date: "Mon Apr 21 2026". A non-finite or invalid date prints
+ * {@link NON_FINITE}. */
+export function fmtTooltipDate(date: unknown): string {
+  if (typeof date === 'number' && !Number.isFinite(date)) return NON_FINITE
+  if (date instanceof Date) {
+    if (Number.isNaN(date.getTime())) return NON_FINITE
+    return `${SHORT_DAYS[date.getDay()]} ${MONTHS[date.getMonth()]} ${date.getDate()} ${date.getFullYear()}`
+  }
+  const s = String(date ?? '')
+  const match = s.match(/(\d{4})-(\d{2})-(\d{2})/)
+  if (!match) return s
+  const d = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]))
+  return `${SHORT_DAYS[d.getDay()]} ${MONTHS[d.getMonth()]} ${d.getDate()} ${d.getFullYear()}`
+}
+
+export type ClockOptions = LocaleOption & {
+  /** IANA zone (`'Europe/Vienna'`). Default the runtime's own zone — the same "local" argo's
+   * `d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })` call sites meant. */
+  timeZone?: string
+  /** Render `:ss` too. Default false. */
+  seconds?: boolean
+}
+
+/** A local clock reading — `"09:41"`. Seeds: `m365-explorer/explorer-page.tsx`,
+ * `walking-pad/session-history.tsx` (both `toLocaleTimeString([...], { hour: '2-digit', minute:
+ * '2-digit' })`). A non-finite/unparseable input prints {@link NON_FINITE}. */
+export function clock(value: Date | number | string, options: ClockOptions = {}): string {
+  const date = toDate(value)
+  if (date === null) return NON_FINITE
+  const { locale, timeZone, seconds = false } = options
+  return dateFormat(locale, {
+    hour: '2-digit',
+    minute: '2-digit',
+    ...(seconds && { second: '2-digit' }),
+    hour12: false,
+    ...(timeZone !== undefined && { timeZone }),
+  }).format(date)
+}
+
+export type WeekdayOptions = LocaleOption & {
+  /** `Intl.DateTimeFormat`'s own weekday widths. Default `'short'` (`"Mon"`). */
+  format?: 'short' | 'long' | 'narrow'
+}
+
+/** Weekday name — seeded from `astro-window/formulas.ts#fmtWeekday`. A plain `YYYY-MM-DD` string
+ * is parsed as a LOCAL calendar date (never UTC), matching that seed's own rationale: the weekday
+ * must not shift a day depending on the reader's timezone. A non-finite/unparseable input prints
+ * {@link NON_FINITE}. */
+export function weekday(value: Date | number | string, options: WeekdayOptions = {}): string {
+  const date =
+    typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)
+      ? (() => {
+          const [y, m, d] = value.split('-').map(Number)
+          return new Date(y ?? 1970, (m ?? 1) - 1, d ?? 1)
+        })()
+      : toDate(value)
+  if (date === null) return NON_FINITE
+  const { locale, format = 'short' } = options
+  return dateFormat(locale, { weekday: format }).format(date)
+}
+
+export type RelativeTimeOptions = LocaleOption & {
+  /** The reference "now" instant, epoch ms. Default `Date.now()` — mainly for tests. */
+  now?: number
+}
+
+const RELATIVE_TIME_UNITS: readonly {
+  readonly unit: Intl.RelativeTimeFormatUnit
+  readonly ms: number
+}[] = [
+  { unit: 'year', ms: 31_536_000_000 },
+  { unit: 'month', ms: 2_628_000_000 },
+  { unit: 'week', ms: 604_800_000 },
+  { unit: 'day', ms: 86_400_000 },
+  { unit: 'hour', ms: 3_600_000 },
+  { unit: 'minute', ms: 60_000 },
+]
+
+const relativeTimeFormatterCache = new Map<string, Intl.RelativeTimeFormat>()
+
+function relativeTimeFormat(locale: string | undefined): Intl.RelativeTimeFormat {
+  const key = locale ?? ''
+  const cached = relativeTimeFormatterCache.get(key)
+  if (cached !== undefined) return cached
+  const created = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+  relativeTimeFormatterCache.set(key, created)
+  return created
+}
+
+/**
+ * Short relative phrase — `"3 hours ago"`, `"in 2 days"`, `"just now"`. Seeded from
+ * `agent-chat/relative-time.ts#formatRelativeTime` (epoch-ms, 'en'-hardcoded), generalized with a
+ * `locale` option and accepting `Date`/ISO-string inputs too (argo's
+ * `reading/format.ts#relativeTime` and `garmin-health/formulas.ts#formatRelativeTime` both take an
+ * ISO string). A non-finite/unparseable input prints {@link NON_FINITE} rather than throwing —
+ * `Intl.RelativeTimeFormat.format` throws a `RangeError` on non-finite input, and this is
+ * render-path code where one bad timestamp must not blank a whole list.
+ */
+export function relativeTime(
+  value: number | Date | string,
+  options: RelativeTimeOptions = {},
+): string {
+  const { locale, now = Date.now() } = options
+  const timestamp =
+    value instanceof Date ? value.getTime() : typeof value === 'number' ? value : Date.parse(value)
+  if (!Number.isFinite(timestamp)) return NON_FINITE
+  const diffMs = timestamp - now
+  const absMs = Math.abs(diffMs)
+  if (absMs < 60_000) return 'just now'
+  const unit = RELATIVE_TIME_UNITS.find(({ ms }) => absMs >= ms) ?? RELATIVE_TIME_UNITS.at(-1)!
+  return relativeTimeFormat(locale).format(Math.round(diffMs / unit.ms), unit.unit)
+}
+
+export type DurationUnit = 'seconds' | 'minutes'
+
+export type DurationOptions = {
+  /** Unit of the input value. Default `'seconds'`. */
+  unit?: DurationUnit
+}
+
+/**
+ * Human duration — `"1h 02m"`, `"5m"`, `"42s"`. Minutes zero-pad once an hour is present (`"1h
+ * 02m"`, a clock-reading convention); alone they don't (`"5m"`). Seconds show only under a minute
+ * (`"42s"`). A non-finite value prints {@link NON_FINITE}.
+ *
+ * The one signature standing in for argo's four duration spellings: `walking-pad/
+ * formatters.ts#formatDuration` (seconds, `<60s` → `"Ns"` — this IS that shape),
+ * `reading/format.ts#formatReadTime` (seconds, no `<60s` branch, floors at `"0m"` — pass a value
+ * `>= 60` and the shapes match), `astro-window/formulas.ts#fmtMinutes` (minutes as input — pass
+ * `{ unit: 'minutes' }`). The fourth, `walking-pad/formatters.ts#formatDurationClock` (`h:mm:ss`),
+ * is {@link durationClock} below, not this.
+ */
+export function duration(value: number, options: DurationOptions = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { unit = 'seconds' } = options
+  const totalSeconds = Math.max(0, Math.round(unit === 'minutes' ? value * 60 : value))
+  if (totalSeconds < 60) return `${totalSeconds}s`
+  const totalMinutes = Math.round(totalSeconds / 60)
+  const h = Math.floor(totalMinutes / 60)
+  const m = totalMinutes % 60
+  if (h === 0) return `${m}m`
+  return `${h}h ${String(m).padStart(2, '0')}m`
+}
+
+/** Clock-style duration — `"1:02:03"`, `"04:12"`. Seeded from `walking-pad/
+ * formatters.ts#formatDurationClock`. A non-finite value prints {@link NON_FINITE}. */
+export function durationClock(seconds: number): string {
+  if (!Number.isFinite(seconds)) return NON_FINITE
+  const total = Math.max(0, Math.round(seconds))
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const s = total % 60
+  const mm = String(m).padStart(2, '0')
+  const ss = String(s).padStart(2, '0')
+  return h > 0 ? `${h}:${mm}:${ss}` : `${mm}:${ss}`
+}

package/src/format/index.ts

@@ -0,0 +1,69 @@
+/**
+ * `basalt-ui/format` — Mantine-free, React-free `Intl`-backed formatting. One implementation for
+ * numbers/percentages/money, dates/times/durations and the two measurement units argo needed
+ * (`km`/`kcal`) — replacing argo's `features/*\/{formatters,formulas,format}.ts` (~350 of 643
+ * lines across four duration spellings) and the chart layer's own `charts/utils/format.ts`, which
+ * now re-exports from here.
+ *
+ * Every formatter takes `(value, opts?)`; `locale` on every `opts` defaults to `undefined` —
+ * `Intl`'s own "use the runtime's locale". Every non-finite/unparseable input prints the same
+ * {@link NON_FINITE} em dash rather than `"NaN"` or throwing.
+ *
+ * @example
+ * import { money, percent, duration, weekday, relativeTime } from 'basalt-ui/format'
+ *
+ * money(1234, { currency: 'USD' })        // "$1,234"
+ * percent(0.42)                            // "42%"
+ * duration(3_723)                          // "1h 02m"
+ * weekday('2026-09-02')                    // "Wed"
+ * relativeTime(Date.now() - 3_600_000)     // "1 hour ago"
+ */
+export {
+  compact,
+  deltaPct,
+  type DeltaPctOptions,
+  fmtCompact,
+  type FmtCompactOptions,
+  fmtCurrency,
+  type FmtCurrencyOptions,
+  fmtInt,
+  fmtPercent,
+  type FmtPercentOptions,
+  integer,
+  type LocaleOption,
+  money,
+  NON_FINITE,
+  percent,
+} from './number'
+export {
+  clock,
+  type ClockOptions,
+  duration,
+  durationClock,
+  type DurationOptions,
+  type DurationUnit,
+  fmtAxisDate,
+  fmtTooltipDate,
+  relativeTime,
+  type RelativeTimeOptions,
+  weekday,
+  type WeekdayOptions,
+} from './date'
+export { kcal, type KcalOptions, km, type KmOptions } from './measure'
+
+import { fmtCompact, fmtCurrency, fmtInt, fmtPercent } from './number'
+import { fmtAxisDate, fmtTooltipDate } from './date'
+
+/**
+ * Every shipped chart-facing formatter under one name, so a chart can be handed the whole set
+ * (`format={formatters.compact}`). Unchanged shape from `charts/utils/format.ts` — this is the
+ * SAME object, not a second one, so an existing `formatters.x` call site keeps working verbatim.
+ */
+export const formatters = {
+  compact: fmtCompact,
+  percent: fmtPercent,
+  currency: fmtCurrency,
+  int: fmtInt,
+  axisDate: fmtAxisDate,
+  tooltipDate: fmtTooltipDate,
+} as const

package/src/format/measure.ts

@@ -0,0 +1,31 @@
+/**
+ * Distance/energy formatting — seeded from `walking-pad/formatters.ts#formatKm`/`#formatKcal`.
+ */
+import { NON_FINITE } from './shared'
+
+export type KmOptions = {
+  /** Fraction digits. Default 2 (`"5.30 km"`). */
+  digits?: number
+}
+
+/** Meters as kilometers — `"5.30 km"`. A non-finite value prints {@link NON_FINITE}. */
+export function km(meters: number, options: KmOptions = {}): string {
+  if (!Number.isFinite(meters)) return NON_FINITE
+  const { digits = 2 } = options
+  return `${(meters / 1000).toFixed(digits)} km`
+}
+
+export type KcalOptions = {
+  /** Fraction digits once compacted to `k cal`. Default 2. Below 1000 kcal always rounds to a
+   * whole number, matching the seed (`formatKcal`). */
+  digits?: number
+}
+
+/** Kilocalories, compacting to `"k cal"` above 1000 — `"842 kcal"`, `"1.24 k cal"`. A non-finite
+ * value prints {@link NON_FINITE}. */
+export function kcal(value: number, options: KcalOptions = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { digits = 2 } = options
+  if (value >= 1000) return `${(value / 1000).toFixed(digits)} k cal`
+  return `${Math.round(value)} kcal`
+}

package/src/format/number.ts

@@ -0,0 +1,129 @@
+/**
+ * Number formatting — `Intl.NumberFormat` with the arguments already decided, so a caller states
+ * WHAT a number is rather than how to punctuate it. Moved here from `src/charts/utils/format.ts`
+ * (C5 consolidation) — that file now re-exports from this module so charts keep working through
+ * one implementation.
+ *
+ * `money`/`percent`/`integer`/`compact`/`deltaPct` are the argo-facing names (seeded from
+ * `features/*\/{formatters,formulas}.ts`); `fmtCurrency`/`fmtPercent`/`fmtInt`/`fmtCompact` are the
+ * original chart-formatter names, kept for source compatibility and delegated to by the new names.
+ */
+import { NON_FINITE, numberFormat } from './shared'
+import type { LocaleOption } from './shared'
+
+export type { LocaleOption }
+export { NON_FINITE }
+
+/** The compact `K` suffix, matched only where it follows the digits it qualifies — so a currency
+ * prefix that happens to contain one (`HK$`) survives the lowercasing. */
+const COMPACT_K = /(\d\s?)K/
+
+export type FmtCompactOptions = LocaleOption & {
+  /** Significant-ish fraction digits on the compacted number. Default 1 (`1.2k`, `3.4M`). */
+  digits?: number
+}
+
+/**
+ * Compact notation: `1.2k`, `3.4M`, `-820`. The axis formatter for any count whose range spans
+ * more than three digits. A non-finite value prints {@link NON_FINITE}.
+ *
+ * Note `Intl`'s compact notation is LOCALE text, not a suffix table: `en` gives `1.2K`, and this
+ * lowercases the `K` to match the package's own numeral style while leaving every other locale's
+ * word (`1,2 Mio.`) untouched.
+ */
+export function fmtCompact(value: number, options: FmtCompactOptions = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { digits = 1, locale } = options
+  return numberFormat(locale, {
+    notation: 'compact',
+    compactDisplay: 'short',
+    maximumFractionDigits: digits,
+  })
+    .format(value)
+    .replace(COMPACT_K, '$1k')
+}
+
+/** `compact` — the `basalt-ui/format` name for {@link fmtCompact}. */
+export const compact = fmtCompact
+
+export type FmtPercentOptions = LocaleOption & {
+  /** Fraction digits. Default 0 (`42%`). */
+  digits?: number
+  /**
+   * What the incoming number MEANS. `'ratio'` (default) is `0.42 → 42%`; `'percent'` is
+   * `42 → 42%`. Required as an explicit option rather than guessed from magnitude.
+   */
+  input?: 'ratio' | 'percent'
+}
+
+/** Percentages, from either a ratio or an already-scaled percentage. A non-finite value prints
+ * {@link NON_FINITE}. */
+export function fmtPercent(value: number, options: FmtPercentOptions = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { digits = 0, input = 'ratio', locale } = options
+  return numberFormat(locale, {
+    style: 'percent',
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  }).format(input === 'percent' ? value / 100 : value)
+}
+
+/** `percent` — the `basalt-ui/format` name for {@link fmtPercent}. */
+export const percent = fmtPercent
+
+export type DeltaPctOptions = FmtPercentOptions
+
+/**
+ * A signed percentage delta: `+4%`, `-12%`, `0%` — argo's `walking-pad/formatters.ts#formatPct`
+ * (a `+`-prefixed ratio) generalized onto `Intl`'s own `signDisplay: 'exceptZero'`, which adds the
+ * `+`/`-` sign the same way `Intl`'s own minus sign already does, and adds nothing for zero. A
+ * non-finite value prints {@link NON_FINITE}.
+ */
+export function deltaPct(value: number, options: DeltaPctOptions = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { digits = 0, input = 'ratio', locale } = options
+  return numberFormat(locale, {
+    style: 'percent',
+    signDisplay: 'exceptZero',
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  }).format(input === 'percent' ? value / 100 : value)
+}
+
+export type FmtCurrencyOptions = LocaleOption & {
+  /** ISO 4217 code — required. There is no default currency. */
+  currency: string
+  /** Compact notation for the amount (`$1.2k`). Default false. */
+  compact?: boolean
+  /** Fraction digits. Default 0 compacted, else the currency's own default (`undefined`). */
+  digits?: number
+}
+
+/** Money. `fmtCurrency(1234, { currency: 'USD' })` → `$1,234`. A non-finite amount prints
+ * {@link NON_FINITE}. */
+export function fmtCurrency(value: number, options: FmtCurrencyOptions): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { currency, compact: isCompact = false, digits, locale } = options
+  const fractionDigits = digits ?? (isCompact ? 1 : 0)
+  return numberFormat(locale, {
+    style: 'currency',
+    currency,
+    ...(isCompact && { notation: 'compact', compactDisplay: 'short' }),
+    minimumFractionDigits: isCompact ? 0 : fractionDigits,
+    maximumFractionDigits: fractionDigits,
+  })
+    .format(value)
+    .replace(COMPACT_K, '$1k')
+}
+
+/** `money` — the `basalt-ui/format` name for {@link fmtCurrency}. */
+export const money = fmtCurrency
+
+/** Grouped integer: `12,480`. Rounds. A non-finite value prints {@link NON_FINITE}. */
+export function fmtInt(value: number, options: LocaleOption = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  return numberFormat(options.locale, { maximumFractionDigits: 0 }).format(value)
+}
+
+/** `integer` — the `basalt-ui/format` name for {@link fmtInt}. */
+export const integer = fmtInt

package/src/format/shared.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared low-level pieces of `basalt-ui/format` — the em-dash sentinel and the memoized
+ * `Intl.NumberFormat` cache every number formatter in this module reuses. Moved here (out of
+ * `src/charts/utils/format.ts`, C5 consolidation) so the subpath is the single implementation and
+ * `charts/utils/format.ts` becomes a thin re-export (`docs/CHARTS-SPEC.md` still calls it home for
+ * chart callers, but the code lives here now).
+ */
+
+/**
+ * What EVERY formatter in this module prints for input it cannot represent — `NaN`, `±Infinity`,
+ * an `Invalid Date`. An em dash (U+2014). A formatter may say it does not know; it may not print a
+ * number that is not one.
+ */
+export const NON_FINITE = '—'
+
+/** Options every number formatter here accepts. */
+export type LocaleOption = {
+  /** BCP-47 tag. Default `undefined` — the runtime's own locale. */
+  locale?: string
+}
+
+/**
+ * `Intl.NumberFormat` construction is the expensive half of formatting and a chart formats one
+ * label per tick per frame, so instances are memoized on their own arguments. The key is the
+ * serialized options because that is exactly what identifies an instance.
+ */
+const formatterCache = new Map<string, Intl.NumberFormat>()
+
+export function numberFormat(
+  locale: string | undefined,
+  options: Intl.NumberFormatOptions,
+): Intl.NumberFormat {
+  const key = `${locale ?? ''}|${JSON.stringify(options)}`
+  const cached = formatterCache.get(key)
+  if (cached !== undefined) return cached
+  const created = new Intl.NumberFormat(locale, options)
+  formatterCache.set(key, created)
+  return created
+}
+
+const dateFormatterCache = new Map<string, Intl.DateTimeFormat>()
+
+export function dateFormat(
+  locale: string | undefined,
+  options: Intl.DateTimeFormatOptions,
+): Intl.DateTimeFormat {
+  const key = `${locale ?? ''}|${JSON.stringify(options)}`
+  const cached = dateFormatterCache.get(key)
+  if (cached !== undefined) return cached
+  const created = new Intl.DateTimeFormat(locale, options)
+  dateFormatterCache.set(key, created)
+  return created
+}
+
+/** Coerces the flexible `Date | number | string` inputs this module's date formatters accept into
+ * a `Date`. A `number` is treated as epoch milliseconds (matching `Date`'s own constructor and
+ * `agent-chat/relative-time.ts`'s prior contract) — a caller with epoch seconds multiplies by
+ * 1000 first. Returns `null` for a non-finite/unparseable input so every caller can share one
+ * {@link NON_FINITE} guard instead of re-deriving one. */
+export function toDate(value: Date | number | string): Date | null {
+  const date = value instanceof Date ? value : new Date(value)
+  return Number.isNaN(date.getTime()) ? null : date
+}

package/src/forms/FormErrorSummary.tsx

@@ -4,12 +4,14 @@
  */
 import { Alert, List, Text } from '@mantine/core'
 import type { UseFormReturnType } from '@mantine/form'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import { alpha, VX } from '../tokens'
 
 // ── FormErrorSummary ──────────────────────────────────────────────────────────
 
 /** Props for FormErrorSummary. */
-export type FormErrorSummaryProps<Values extends Record<string, unknown>> = {
+export type FormErrorSummaryProps<Values extends Record<string, unknown>> = BasaltProps & {
   form: UseFormReturnType<Values>
   /** Accessible heading shown above the error list. Defaults to "Please fix the following errors". */
   title?: string
@@ -30,15 +32,18 @@ export type FormErrorSummaryProps<Values extends Record<string, unknown>> = {
  *   return (
  *     <form onSubmit={form.onSubmit(console.log)}>
  *       <FormErrorSummary form={form} title="Fix these before submitting" />
- *       <TextInput {...field(form, 'email')} label="Email" />
+ *       <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} label="Email" />
  *     </form>
  *   )
  * }
  */
-export function FormErrorSummary<Values extends Record<string, unknown>>({
-  form,
-  title = 'Please fix the following errors',
-}: FormErrorSummaryProps<Values>) {
+export function FormErrorSummary<Values extends Record<string, unknown>>(
+  props: FormErrorSummaryProps<Values>,
+) {
+  // F-ERR-1: without this, a missing `form` fails deep inside `Object.entries(form.errors)` as a
+  // raw `TypeError` caught by `BasaltErrorBoundary` — a blank subtree with no message naming it.
+  assertRequiredProps('FormErrorSummary', props, ['form'])
+  const { form, title = 'Please fix the following errors', className, style } = props
   const errorEntries = Object.entries(form.errors)
   if (errorEntries.length === 0) return null
 
@@ -46,6 +51,8 @@ export function FormErrorSummary<Values extends Record<string, unknown>>({
     <Alert
       role="alert"
       title={<Text fw={600}>{title}</Text>}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
       styles={{
         root: {
           backgroundColor: alpha(VX.status.bad, 0.13),

package/src/forms/create-form.ts

@@ -29,14 +29,14 @@ export type UseBasaltFormOptions<Values extends Record<string, unknown>> = Omit<
  *
  * @example
  * import * as v from 'valibot'
- * import { useBasaltForm, field } from 'basalt-ui/forms'
+ * import { useBasaltForm, inputProps, fieldKey } from 'basalt-ui/forms'
  *
  * const Schema = v.object({ name: v.pipe(v.string(), v.minLength(2)), email: v.string() })
  * type Values = v.InferOutput<typeof Schema>
  *
  * function MyForm() {
  *   const form = useBasaltForm({ initialValues: { name: '', email: '' }, schema: Schema })
- *   return <TextInput {...field(form, 'name')} label="Name" />
+ *   return <TextInput key={fieldKey(form, 'name')} {...inputProps(form, 'name')} label="Name" />
  * }
  */
 export function useBasaltForm<Values extends Record<string, unknown>>(

package/src/forms/field.ts

@@ -1,30 +1,59 @@
 /**
- * ./forms — field: DX helper for Mantine v9 uncontrolled fields.
+ * ./forms — inputProps + fieldKey: the two-call idiom every Mantine v9 uncontrolled field needs.
  * Mantine-coupled. Optional peer: @mantine/form.
+ *
+ * **`key` is NOT in `inputProps`' return, and that is the whole point of this file's shape.**
+ * It used to be — one object holding `getInputProps(path)` and `form.key(path)` together, so a
+ * single spread covered both. React 19 logs
+ * `A props object containing a "key" prop is being spread into JSX` on every such render: a spread
+ * `key` is read as the element key but the warning says it is deprecated, and three fields meant
+ * three warnings per page. The bundle was basalt's own invention; Mantine's documented idiom is
+ * `key={form.key(path)} {...form.getInputProps(path)}`, and this is that idiom with basalt's names.
+ *
+ * The `@deprecated` `field` alias that used to live here is removed (1.29.0, C1 consolidation) —
+ * `basalt-ui/forms`' `field` collided in name with the `field` store builder on `basalt-ui/state`,
+ * which was the whole reason for the rename in the first place. Write
+ * `key={fieldKey(form, path)} {...inputProps(form, path)}`.
  */
 import type { LooseKeys, UseFormReturnType } from '@mantine/form'
 
-// ── field ─────────────────────────────────────────────────────────────────────
+// ── inputProps ────────────────────────────────────────────────────────────────
 
 /**
- * Bundles the two props every Mantine v9 uncontrolled field needs — `getInputProps` spread
- * plus the reconciler `key` — into a single object. Eliminates the two-call boilerplate at
- * every field site.
+ * The spread half: `form.getInputProps(path)`, and nothing else.
+ *
+ * Pair it with {@link fieldKey} — an uncontrolled field renders from a `defaultValue`, so without
+ * the reconciler key React reuses the DOM node and `form.reset()` / `setValues()` / a removed list
+ * row leave the old text on screen.
  *
  * @example
- * import { useBasaltForm, field } from 'basalt-ui/forms'
+ * import { useBasaltForm, inputProps, fieldKey } from 'basalt-ui/forms'
  *
  * function MyForm() {
  *   const form = useBasaltForm({ initialValues: { email: '' } })
- *   return <TextInput {...field(form, 'email')} label="Email" />
+ *   return <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} label="Email" />
  * }
  */
-export function field<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(
+export function inputProps<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(
+  form: UseFormReturnType<Values>,
+  path: Path,
+): ReturnType<UseFormReturnType<Values>['getInputProps']> {
+  return form.getInputProps(path)
+}
+
+/**
+ * The key half: `form.key(path)`, as a JSX `key` attribute — never spread.
+ *
+ * A separate call rather than a second member of {@link inputProps}' object, because an object
+ * carrying `key` cannot be spread without React 19 warning about it. Two calls on one line is the
+ * cost; a clean console and a reconciler that actually resets its inputs is what it buys.
+ *
+ * @example
+ * <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} />
+ */
+export function fieldKey<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(
   form: UseFormReturnType<Values>,
   path: Path,
-): ReturnType<UseFormReturnType<Values>['getInputProps']> & { key: string } {
-  return {
-    ...form.getInputProps(path),
-    key: form.key(path),
-  }
+): string {
+  return form.key(path)
 }