@tempots/beatui 1.4.0 → 1.6.0

package/dist/types/components/form/input/text-input.d.ts

@@ -32,7 +32,7 @@ export type TextInputOptions = Merge<InputOptions<string>, {
  * const name = prop('John')
  * TextInput({
  *   value: name,
- *   onChange: name.set,
+ *   onChange: v => name.set(v),
  *   placeholder: 'Enter your name',
  *   size: 'md',
  * })

package/dist/types/components/form/input/time-format.d.ts

@@ -0,0 +1,31 @@
+/** Any object with hour/minute/second — covers PlainTime and PlainDateTime. */
+interface TimeLike {
+    hour: number;
+    minute: number;
+    second: number;
+}
+/**
+ * Format a time-like value as a 12-hour string (e.g. "2:30 PM").
+ */
+export declare function formatTime12(t: TimeLike): string;
+/**
+ * Format a time-like value as a 24-hour string (e.g. "14:30").
+ */
+export declare function formatTime24(t: TimeLike): string;
+/**
+ * Format a time-like value as a 12-hour string with seconds (e.g. "2:30:15 PM").
+ */
+export declare function formatTime12WithSeconds(t: TimeLike): string;
+/**
+ * Format a time-like value as a 24-hour string with seconds (e.g. "14:30:15").
+ */
+export declare function formatTime24WithSeconds(t: TimeLike): string;
+/**
+ * Pick the correct formatter based on 12-hour and seconds flags.
+ */
+export declare function formatTimeAuto(t: TimeLike, is12Hour: boolean, withSeconds: boolean): string;
+/**
+ * Detect whether a locale uses 12-hour time format.
+ */
+export declare function localeUses12Hour(locale: string): boolean;
+export {};

package/dist/types/components/form/input/time-select-base.d.ts

@@ -0,0 +1,23 @@
+import { TNode, Value } from '@tempots/dom';
+import { CommonInputOptions } from './input-options';
+/**
+ * Internal base options for the time select shell (trigger + flyout).
+ * The actual picker content is provided via `panelContent`.
+ */
+export interface TimeSelectShellOptions extends CommonInputOptions {
+    /** The display text shown in the trigger. */
+    displayText: Value<string>;
+    /** The content to render inside the flyout panel. */
+    panelContent: TNode;
+    /** Callback invoked on blur. */
+    onBlur?: () => void;
+    /** Content to render before the display text. */
+    before?: TNode;
+    /** Content to render after the display text. */
+    after?: TNode;
+}
+/**
+ * Shared shell for time selectors: trigger button + flyout panel.
+ * Used by both TimeSelect and NullableTimeSelect.
+ */
+export declare function TimeSelectShell(options: TimeSelectShellOptions): TNode;

package/dist/types/components/form/input/time-select.d.ts

@@ -0,0 +1,61 @@
+import { type TNode, Value, type Merge } from '@tempots/dom';
+import { CommonInputOptions } from './input-options';
+import type { PlainTime } from '../../../temporal/types';
+import { ThemeColorName } from '../../../tokens';
+/**
+ * Configuration options for the {@link TimeSelect} component.
+ */
+export type TimeSelectOptions = Merge<CommonInputOptions, {
+    /** The selected time. */
+    value: Value<PlainTime>;
+    /** Callback invoked when the time changes. */
+    onChange?: (time: PlainTime) => void;
+    /** Callback invoked on blur. */
+    onBlur?: () => void;
+    /** Theme color. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /** Whether to show seconds. @default false */
+    showSeconds?: Value<boolean>;
+    /** Whether to use 12-hour format. When omitted, auto-detected from the current locale. */
+    use12Hour?: Value<boolean>;
+    /** Step for minutes column. @default 1 */
+    minuteStep?: Value<number>;
+    /** Step for seconds column. @default 1 */
+    secondStep?: Value<number>;
+    /** Whether to show a "Now" button. @default false */
+    showNow?: Value<boolean>;
+    /** Format a PlainTime for display. When omitted, uses locale-aware 12/24-hour format. */
+    formatTime?: (time: PlainTime) => string;
+    /** Content to render before the display text. */
+    before?: TNode;
+    /** Content to render after the display text. */
+    after?: TNode;
+}>;
+/**
+ * A dropdown time selector.
+ *
+ * Displays the selected time in a styled trigger button. Clicking opens a
+ * flyout panel with a {@link TimePicker} for selecting a time.
+ *
+ * When no custom `formatTime` is provided, the display adapts to the
+ * locale's 12/24-hour convention (or the explicit `use12Hour` prop).
+ *
+ * Use {@link NullableTimeSelect} when the time can be null/unset.
+ *
+ * @param options - Configuration for the time selector
+ * @returns A time selector element
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { TimeSelect } from '@tempots/beatui'
+ * import { Temporal } from '@js-temporal/polyfill'
+ *
+ * const time = prop(Temporal.PlainTime.from('14:30'))
+ * TimeSelect({
+ *   value: time,
+ *   onChange: v => time.set(v),
+ * })
+ * ```
+ */
+export declare function TimeSelect(options: TimeSelectOptions): TNode;

package/dist/types/components/form/input/transfer-list.d.ts

@@ -0,0 +1,56 @@
+import { TNode, Value } from '@tempots/dom';
+import { ControlSize } from '../../theme';
+import { ThemeColorName } from '../../../tokens';
+/** Configuration options for the {@link TransferList} component. */
+export interface TransferListOptions<T> {
+    /** Items available for selection (left panel). */
+    available: Value<T[]>;
+    /** Items currently selected (right panel). */
+    selected: Value<T[]>;
+    /** Callback invoked with the new selected items array after a transfer. */
+    onChange: (selected: T[]) => void;
+    /** Render function for each item. */
+    renderItem: (item: T) => TNode;
+    /** Extract a unique key from an item. */
+    keyOf: (item: T) => string;
+    /** Extract searchable text from an item. Defaults to {@link keyOf}. */
+    searchField?: (item: T) => string;
+    /** Whether to show search inputs on each panel. @default false */
+    searchable?: Value<boolean>;
+    /** Whether the component is disabled. @default false */
+    disabled?: Value<boolean>;
+    /** Size variant. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Theme color. @default 'primary' */
+    color?: Value<ThemeColorName>;
+}
+/**
+ * A dual-list component for transferring items between "available" and
+ * "selected" lists. Generic in `T` with user-provided render and key functions.
+ *
+ * Supports multi-select via checkboxes, move-selected / move-all actions
+ * in both directions, and optional search filtering per panel.
+ *
+ * @typeParam T - The item type
+ * @param options - Configuration for the transfer list
+ * @returns A transfer list element
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { TransferList } from '@tempots/beatui'
+ *
+ * const available = prop(['Apple', 'Banana', 'Cherry', 'Date'])
+ * const selected = prop<string[]>([])
+ *
+ * TransferList({
+ *   available,
+ *   selected,
+ *   onChange: v => selected.set(v),
+ *   renderItem: item => html.span(item),
+ *   keyOf: item => item,
+ *   searchable: true,
+ * })
+ * ```
+ */
+export declare function TransferList<T>(options: TransferListOptions<T>): TNode;

package/dist/types/components/form/input/tri-state-checkbox-input.d.ts

@@ -49,7 +49,7 @@ export type TriStateCheckboxInputOptions = InputOptions<CheckboxState> & {
  * const state = prop<CheckboxState>('unchecked')
  * TriStateCheckboxInput({
  *   value: state,
- *   onChange: state.set,
+ *   onChange: v => state.set(v),
  *   placeholder: 'Select all',
  * })
  * ```

package/dist/types/components/form/input/url-input.d.ts

@@ -17,7 +17,7 @@ import { InputOptions } from './input-options';
  * const website = prop('https://')
  * UrlInput({
  *   value: website,
- *   onChange: website.set,
+ *   onChange: v => website.set(v),
  *   placeholder: 'https://example.com',
  * })
  * ```

package/dist/types/components/format/format-bigint.d.ts

@@ -0,0 +1,64 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Options for the {@link FormatBigInt} component.
+ *
+ * Separate from FormatNumber because `bigint` values cannot use `percent`,
+ * `compact`, or significant digit options with `Intl.NumberFormat`.
+ */
+export interface FormatBigIntOptions {
+    /** The bigint value to format. @default 9007199254740993 */
+    value: Value<bigint>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Formatting style. @default 'decimal' */
+    style?: Value<'decimal' | 'currency' | 'unit'>;
+    /** ISO 4217 currency code (required when style is 'currency'). @default undefined */
+    currency?: Value<string>;
+    /** How to display the currency. @default 'symbol' */
+    currencyDisplay?: Value<'symbol' | 'narrowSymbol' | 'code' | 'name'>;
+    /** Sign display mode. @default 'auto' */
+    signDisplay?: Value<'auto' | 'never' | 'always' | 'exceptZero'>;
+    /** Unit identifier (e.g., 'kilometer') for style 'unit'. @default undefined */
+    unit?: Value<string>;
+    /** Unit display mode. @default 'short' */
+    unitDisplay?: Value<'short' | 'long' | 'narrow'>;
+    /** Use grouping separators. @default true */
+    useGrouping?: Value<boolean>;
+    /** Minimum integer digits. @default undefined */
+    minimumIntegerDigits?: Value<number>;
+    /** Minimum fraction digits. @default undefined */
+    minimumFractionDigits?: Value<number>;
+    /** Maximum fraction digits. @default undefined */
+    maximumFractionDigits?: Value<number>;
+}
+/**
+ * Formats a bigint value with locale and Intl options.
+ *
+ * @param value - The bigint to format
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Intl.NumberFormat options
+ * @returns The formatted bigint string
+ *
+ * @example
+ * ```ts
+ * formatBigInt(9007199254740993n, 'en-US') // '9,007,199,254,740,993'
+ * formatBigInt(123456789n, 'en-US', { style: 'currency', currency: 'JPY' }) // '¥123,456,789'
+ * ```
+ */
+export declare function formatBigInt(value: bigint, locale?: string, options?: Intl.NumberFormatOptions): string;
+/**
+ * Locale-aware bigint formatting component.
+ *
+ * Renders a formatted bigint as a `<span>` that automatically updates when
+ * the locale or value changes. Supports decimal, currency, and unit styles.
+ *
+ * @param options - Configuration for the bigint format
+ * @returns A reactive `<span>` containing the formatted bigint
+ *
+ * @example
+ * ```ts
+ * FormatBigInt({ value: 9007199254740993n })
+ * FormatBigInt({ value: 123456789n, style: 'currency', currency: 'JPY' })
+ * ```
+ */
+export declare function FormatBigInt(options: FormatBigIntOptions): TNode;

package/dist/types/components/format/format-date-time.d.ts

@@ -0,0 +1,54 @@
+import { TNode, Value } from '@tempots/dom';
+import type { DateValue, DateFormatStyle } from './format-date';
+import type { TimeFormatStyle } from './format-time';
+/**
+ * Options for the {@link FormatDateTime} component.
+ */
+export interface FormatDateTimeOptions {
+    /** The date/time value to format. @default '2026-03-17T14:30:00' */
+    value: Value<DateValue>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Date portion style. @default 'medium' */
+    dateStyle?: Value<DateFormatStyle>;
+    /** Time portion style. @default 'short' */
+    timeStyle?: Value<TimeFormatStyle>;
+    /** Time zone. @default undefined (browser default) */
+    timeZone?: Value<string>;
+    /** Calendar system. @default undefined */
+    calendar?: Value<string>;
+    /** Whether to use 12-hour time. @default undefined (locale default) */
+    hour12?: Value<boolean>;
+    /** Hour cycle override. @default undefined */
+    hourCycle?: Value<'h11' | 'h12' | 'h23' | 'h24'>;
+}
+/**
+ * Formats a date and time value with locale and Intl options.
+ *
+ * @param value - The date/time value to format
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Intl.DateTimeFormat options
+ * @returns The formatted date-time string
+ *
+ * @example
+ * ```ts
+ * formatDateTime(new Date(), 'en-US') // 'Mar 17, 2026, 2:30 PM'
+ * ```
+ */
+export declare function formatDateTime(value: DateValue, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Locale-aware date and time formatting component.
+ *
+ * Renders a formatted date-time as a `<span>` that automatically updates when
+ * the locale or value changes.
+ *
+ * @param options - Configuration for the date-time format
+ * @returns A reactive `<span>` containing the formatted date-time
+ *
+ * @example
+ * ```ts
+ * FormatDateTime({ value: new Date() })
+ * FormatDateTime({ value: zonedDateTime, dateStyle: 'full', timeStyle: 'long' })
+ * ```
+ */
+export declare function FormatDateTime(options: FormatDateTimeOptions): TNode;

package/dist/types/components/format/format-date.d.ts

@@ -0,0 +1,82 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Any object with a `toLocaleString` method compatible with `Intl.DateTimeFormat` options.
+ * This covers all Temporal types (PlainDate, PlainDateTime, Instant, ZonedDateTime,
+ * PlainYearMonth, PlainMonthDay) without importing the polyfill.
+ */
+export type TemporalDateLike = {
+    toLocaleString(locale?: string, options?: Intl.DateTimeFormatOptions): string;
+};
+/**
+ * Accepted date value types.
+ * - `Date` — native JavaScript Date
+ * - `string` — ISO 8601 date string
+ * - `number` — Unix timestamp in milliseconds
+ * - `TemporalDateLike` — any Temporal type with `toLocaleString`
+ */
+export type DateValue = Date | string | number | TemporalDateLike;
+/**
+ * Preset date format styles matching `Intl.DateTimeFormat` dateStyle.
+ */
+export type DateFormatStyle = 'full' | 'long' | 'medium' | 'short';
+/**
+ * Options for the {@link FormatDate} component.
+ */
+export interface FormatDateOptions {
+    /** The date value to format. @default '2026-03-17' */
+    value: Value<DateValue>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Date format preset. @default 'medium' */
+    dateStyle?: Value<DateFormatStyle>;
+    /** Calendar system (e.g., 'gregory', 'islamic', 'hebrew'). @default undefined */
+    calendar?: Value<string>;
+    /** Numbering system (e.g., 'arab', 'latn'). @default undefined */
+    numberingSystem?: Value<string>;
+    /** Time zone for date interpretation. @default undefined (browser default) */
+    timeZone?: Value<string>;
+    /** Weekday representation (mutually exclusive with dateStyle). @default undefined */
+    weekday?: Value<'long' | 'short' | 'narrow'>;
+    /** Year representation (mutually exclusive with dateStyle). @default undefined */
+    year?: Value<'numeric' | '2-digit'>;
+    /** Month representation (mutually exclusive with dateStyle). @default undefined */
+    month?: Value<'numeric' | '2-digit' | 'long' | 'short' | 'narrow'>;
+    /** Day representation (mutually exclusive with dateStyle). @default undefined */
+    day?: Value<'numeric' | '2-digit'>;
+    /** Era representation (mutually exclusive with dateStyle). @default undefined */
+    era?: Value<'long' | 'short' | 'narrow'>;
+}
+/**
+ * Formats a date value with locale and Intl options.
+ * Supports native Date, ISO strings, timestamps, and Temporal types.
+ *
+ * @param value - The date value to format
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Intl.DateTimeFormat options
+ * @returns The formatted date string
+ *
+ * @example
+ * ```ts
+ * formatDate(new Date(), 'en-US', { dateStyle: 'full' }) // 'Monday, March 17, 2026'
+ * formatDate('2026-03-17', 'de-DE', { dateStyle: 'short' }) // '17.03.26'
+ * ```
+ */
+export declare function formatDate(value: DateValue, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Locale-aware date formatting component.
+ *
+ * Renders a formatted date as a `<span>` that automatically updates when
+ * the locale or value changes. Supports preset styles, fine-grained part
+ * selection, calendar systems, and Temporal types.
+ *
+ * @param options - Configuration for the date format
+ * @returns A reactive `<span>` containing the formatted date
+ *
+ * @example
+ * ```ts
+ * FormatDate({ value: new Date(), dateStyle: 'full' })
+ * FormatDate({ value: plainDate, dateStyle: 'long' })
+ * FormatDate({ value: '2026-03-17', weekday: 'short', month: 'short', day: 'numeric' })
+ * ```
+ */
+export declare function FormatDate(options: FormatDateOptions): TNode;

package/dist/types/components/format/format-display-name.d.ts

@@ -0,0 +1,70 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Type of display name to resolve.
+ */
+export type DisplayNameType = 'language' | 'region' | 'script' | 'currency' | 'calendar' | 'dateTimeField';
+/**
+ * Format verbosity for display names.
+ */
+export type DisplayNameStyle = 'long' | 'short' | 'narrow';
+/**
+ * Language display style (only for type 'language').
+ */
+export type DisplayNameLanguageDisplay = 'dialect' | 'standard';
+/**
+ * Options for the {@link FormatDisplayName} component.
+ */
+export interface FormatDisplayNameOptions {
+    /** The code to look up (e.g., 'en-US', 'USD', 'Latn'). @default 'en-US' */
+    value: Value<string>;
+    /** The type of display name to resolve. @default 'language' */
+    type: Value<DisplayNameType>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Format verbosity. @default 'long' */
+    style?: Value<DisplayNameStyle>;
+    /** Language display style (only for type 'language'). @default 'dialect' */
+    languageDisplay?: Value<DisplayNameLanguageDisplay>;
+    /** Fallback behavior when code is not found. @default 'code' */
+    fallback?: Value<'code' | 'none'>;
+}
+/**
+ * Formats a display name for a language, region, script, currency, calendar,
+ * or dateTimeField code.
+ *
+ * @param value - The code to look up
+ * @param type - The type of display name
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Additional display name options
+ * @returns The formatted display name string, or the code itself if not found
+ *
+ * @example
+ * ```ts
+ * formatDisplayName('en-US', 'language', 'en')  // 'American English'
+ * formatDisplayName('USD', 'currency', 'en')    // 'US Dollar'
+ * formatDisplayName('JP', 'region', 'en')       // 'Japan'
+ * ```
+ */
+export declare function formatDisplayName(value: string, type: DisplayNameType, locale?: string, options?: {
+    style?: DisplayNameStyle;
+    languageDisplay?: DisplayNameLanguageDisplay;
+    fallback?: 'code' | 'none';
+}): string;
+/**
+ * Locale-aware display name formatting component.
+ *
+ * Renders the locale-aware name for a language, region, script, currency,
+ * calendar, or dateTimeField code as a `<span>` that automatically updates
+ * when the locale or value changes.
+ *
+ * @param options - Configuration for the display name format
+ * @returns A reactive `<span>` containing the formatted display name
+ *
+ * @example
+ * ```ts
+ * FormatDisplayName({ value: 'en-US', type: 'language' })
+ * FormatDisplayName({ value: 'USD', type: 'currency' })
+ * FormatDisplayName({ value: 'JP', type: 'region' })
+ * ```
+ */
+export declare function FormatDisplayName(options: FormatDisplayNameOptions): TNode;

package/dist/types/components/format/format-file-size.d.ts

@@ -0,0 +1,30 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Options for the {@link FormatFileSize} component.
+ */
+export interface FormatFileSizeComponentOptions {
+    /** Byte count to format. @default 1536000 */
+    value: Value<number | bigint>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Unit labels. @default ['B', 'KB', 'MB', 'GB', 'TB'] */
+    units?: string[];
+    /** Decimal places for non-byte units. @default 0 */
+    decimalPlaces?: Value<number>;
+}
+/**
+ * Locale-aware file size formatting component.
+ *
+ * Wraps the existing {@link formatFileSize} utility as a reactive component
+ * that reads the locale from the Locale provider.
+ *
+ * @param options - Configuration for the file size format
+ * @returns A reactive `<span>` containing the formatted file size
+ *
+ * @example
+ * ```ts
+ * FormatFileSize({ value: 1024 })          // '1 KB'
+ * FormatFileSize({ value: 1536, decimalPlaces: 1 }) // '1.5 KB'
+ * ```
+ */
+export declare function FormatFileSize(options: FormatFileSizeComponentOptions): TNode;

package/dist/types/components/format/format-list.d.ts

@@ -0,0 +1,61 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * List semantics type for `Intl.ListFormat`.
+ */
+export type FormatListType = 'conjunction' | 'disjunction' | 'unit';
+/**
+ * Format verbosity for list formatting.
+ */
+export type FormatListStyle = 'long' | 'short' | 'narrow';
+/**
+ * Options for `Intl.ListFormat` (polyfill for ES2020 lib).
+ */
+interface ListFormatOptions {
+    type?: FormatListType;
+    style?: FormatListStyle;
+}
+/**
+ * Options for the {@link FormatList} component.
+ */
+export interface FormatListOptions {
+    /** Array of string items to join. @default undefined */
+    value: Value<string[]>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** List semantics. @default 'conjunction' */
+    type?: Value<FormatListType>;
+    /** Format verbosity. @default 'long' */
+    style?: Value<FormatListStyle>;
+}
+/**
+ * Formats a list of strings with locale and Intl options.
+ *
+ * @param value - Array of strings to join
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - ListFormat options
+ * @returns The formatted list string
+ *
+ * @example
+ * ```ts
+ * formatList(['Red', 'Green', 'Blue'], 'en-US')          // 'Red, Green, and Blue'
+ * formatList(['A', 'B'], 'en-US', { type: 'disjunction' }) // 'A or B'
+ * ```
+ */
+export declare function formatList(value: string[], locale?: string, options?: ListFormatOptions): string;
+/**
+ * Locale-aware list formatting component.
+ *
+ * Renders a formatted list (e.g., "A, B, and C") as a `<span>` that
+ * automatically updates when the locale or value changes.
+ *
+ * @param options - Configuration for the list format
+ * @returns A reactive `<span>` containing the formatted list
+ *
+ * @example
+ * ```ts
+ * FormatList({ value: ['Red', 'Green', 'Blue'] })
+ * FormatList({ value: ['A', 'B'], type: 'disjunction' })
+ * ```
+ */
+export declare function FormatList(options: FormatListOptions): TNode;
+export {};

package/dist/types/components/format/format-number.d.ts

@@ -0,0 +1,88 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Style of number formatting.
+ */
+export type FormatNumberStyle = 'decimal' | 'currency' | 'percent' | 'unit';
+/**
+ * Currency display mode when style is 'currency'.
+ */
+export type FormatNumberCurrencyDisplay = 'symbol' | 'narrowSymbol' | 'code' | 'name';
+/**
+ * How to display the sign for the number.
+ */
+export type FormatNumberSignDisplay = 'auto' | 'never' | 'always' | 'exceptZero';
+/**
+ * Notation style for number formatting.
+ */
+export type FormatNumberNotation = 'standard' | 'scientific' | 'engineering' | 'compact';
+/**
+ * Options for the {@link FormatNumber} component.
+ */
+export interface FormatNumberOptions {
+    /** The number to format. @default 1234.56 */
+    value: Value<number>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Formatting style. @default 'decimal' */
+    style?: Value<FormatNumberStyle>;
+    /** ISO 4217 currency code (required when style is 'currency'). @default undefined */
+    currency?: Value<string>;
+    /** How to display the currency. @default 'symbol' */
+    currencyDisplay?: Value<FormatNumberCurrencyDisplay>;
+    /** Sign display mode. @default 'auto' */
+    signDisplay?: Value<FormatNumberSignDisplay>;
+    /** Notation. @default 'standard' */
+    notation?: Value<FormatNumberNotation>;
+    /** Compact display mode (used when notation is 'compact'). @default undefined */
+    compactDisplay?: Value<'short' | 'long'>;
+    /** Unit identifier (e.g., 'kilometer', 'liter') for style 'unit'. @default undefined */
+    unit?: Value<string>;
+    /** Unit display mode. @default 'short' */
+    unitDisplay?: Value<'short' | 'long' | 'narrow'>;
+    /** Use grouping separators (e.g., thousand commas). @default true */
+    useGrouping?: Value<boolean>;
+    /** Minimum integer digits. @default undefined */
+    minimumIntegerDigits?: Value<number>;
+    /** Minimum fraction digits. @default undefined */
+    minimumFractionDigits?: Value<number>;
+    /** Maximum fraction digits. @default undefined */
+    maximumFractionDigits?: Value<number>;
+    /** Minimum significant digits. @default undefined */
+    minimumSignificantDigits?: Value<number>;
+    /** Maximum significant digits. @default undefined */
+    maximumSignificantDigits?: Value<number>;
+}
+/**
+ * Formats a number with locale and Intl options.
+ *
+ * @param value - The number to format
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Intl.NumberFormat options
+ * @returns The formatted number string
+ *
+ * @example
+ * ```ts
+ * formatNumber(1234.5, 'en-US')              // '1,234.5'
+ * formatNumber(1234, 'en-US', { style: 'currency', currency: 'EUR' }) // '€1,234.00'
+ * formatNumber(0.85, 'en-US', { style: 'percent' }) // '85%'
+ * ```
+ */
+export declare function formatNumber(value: number, locale?: string, options?: Intl.NumberFormatOptions): string;
+/**
+ * Locale-aware number formatting component.
+ *
+ * Renders a formatted number as a `<span>` that automatically updates when
+ * the locale or value changes. Supports decimal, currency, percent, unit,
+ * and compact notation styles.
+ *
+ * @param options - Configuration for the number format
+ * @returns A reactive `<span>` containing the formatted number
+ *
+ * @example
+ * ```ts
+ * FormatNumber({ value: 1234.5 })
+ * FormatNumber({ value: 1234, style: 'currency', currency: 'EUR' })
+ * FormatNumber({ value: 0.85, style: 'percent' })
+ * ```
+ */
+export declare function FormatNumber(options: FormatNumberOptions): TNode;