/** * Pure, string-returning locale formatters over the library's own memoized `Intl` formatter * cache (`internal/intl-cache.ts`) and locale resolution -- the same cache and fallback-locale * behavior ``, ``, ``, and `` * render through. Reach for these when a caller needs a formatted *string* rather than a rendered * element: interpolating into a message template, populating a text-only property on another * component (a stat tile's value, a chart tick label, a badge's cost text), building a search * predicate, or composing an accessibility announcement. * * Every call shares one instance per distinct locale + options pair across the whole page, * including with the elements above -- constructing an `Intl` formatter performs an ICU * locale-data lookup that is orders of magnitude slower than reusing an existing instance. */ import{type LyraFormatBytesUnit,type LyraFormatDisplay,type LyraRelativeTimeNumeric,type LyraRelativeTimeUnit}from'../components/utility/format/format-options.js'; /** A number, `bigint`, or decimal/integer string. Passing a `bigint` or string preserves every * digit through formatting -- a plain `number` is IEEE-754 float64 and cannot exactly represent * an integer beyond `Number.MAX_SAFE_INTEGER` or most decimal fractions. */ export type LyraFormattableNumber=number|bigint|string; /** * Locale-aware `Intl.NumberFormat` output, sharing the library's memoized formatter cache. `value` * may be a `bigint` or a decimal string for exact-precision input (large ids, monetary amounts) -- * see {@link LyraFormattableNumber}. Invalid `options` (for example an unsupported currency code) * throw the same `RangeError`/`TypeError` `Intl.NumberFormat`'s own constructor would. * * An omitted `locale` (or `'auto'`) resolves to the page's active `setLyraLocale()` locale, * matching every rendered `` component -- see {@link resolveActiveOrExplicitLocale}. Falls * back to `'en'` only once no active locale has ever been set, so a caller that never calls * `setLyraLocale()` sees no change. An explicit tag always stays authoritative. */ export declare function formatNumber(value:LyraFormattableNumber,locale?:string,options?:Intl.NumberFormatOptions):string; /** * Locale-aware `Intl.DateTimeFormat` output, sharing the library's memoized formatter cache. `value` * accepts the same sources as ``'s `date` property: an ISO/date string, epoch * milliseconds, or a `Date`. Returns `undefined` for an unresolvable source (an invalid string, a * non-finite epoch, or a non-`Date` object) instead of throwing -- mirroring `resolveCssLength()`'s * "unsupported input returns `undefined`" convention for a pure helper. Invalid `options` still * throw, matching `Intl.DateTimeFormat`'s own constructor. * * An omitted `locale` (or `'auto'`) resolves the same way {@link formatNumber} does: to the page's * active `setLyraLocale()` locale, falling back to `'en'` only once none has been set; an explicit * tag always stays authoritative. See {@link resolveActiveOrExplicitLocale}. */ export declare function formatDate(value:string|number|Date,locale?:string,options?:Intl.DateTimeFormatOptions):string|undefined;export interface LyraFormatRelativeTimeOptions{ /** An explicit unit, or `'auto'` (default) to pick the largest unit the magnitude clears -- * the same heuristic `` uses. */ readonly unit?:LyraRelativeTimeUnit|'auto';readonly format?:LyraFormatDisplay;readonly numeric?:LyraRelativeTimeNumeric; /** The reference instant (epoch milliseconds) `value` is relative to. Defaults to `Date.now()`; * pass a fixed instant for a deterministic test or an "as of" report. */ readonly now?:number;} /** * Locale-aware relative-time text (`"3 days ago"`, `"in 2 hours"`) for a target date, sharing the * library's memoized `Intl.RelativeTimeFormat` cache and the same auto-unit selection * `` renders with. `value` accepts the same sources as `formatDate()`. Returns * `undefined` for an unresolvable source. This is a one-shot computation against `options.now` (or * the current instant); it does not schedule a refresh -- pair it with your own timer, or use * ``, for text that must stay current while displayed. * * An omitted `locale` (or `'auto'`) resolves the same way {@link formatNumber} does: to the page's * active `setLyraLocale()` locale, falling back to `'en'` only once none has been set; an explicit * tag always stays authoritative. See {@link resolveActiveOrExplicitLocale}. */ export declare function formatRelativeTime(value:string|number|Date,locale?:string,options?:LyraFormatRelativeTimeOptions):string|undefined;export interface LyraFormatBytesOptions{readonly unit?:LyraFormatBytesUnit;readonly display?:LyraFormatDisplay; /** The magnitude ladder step between units (`kilobyte` = 1000 bytes; pass `1024` for the binary * ladder). Default `1000`, matching ``. */ readonly unitStep?:number;readonly decimals?:number;} /** * Locale-aware byte/bit-size output (`"1.5 MB"`), sharing the library's memoized formatter cache * and the same unit-ladder selection `` renders with. `value` may be a `bigint` * or a decimal string: the unit ladder is still selected from an approximate magnitude (which * unit is only ever a display choice), but the displayed amount itself is computed with exact * `bigint` division, so a byte count beyond `Number.MAX_SAFE_INTEGER` -- an exact file size, a * cumulative transfer counter -- never gets rounded away. Returns `undefined` for a non-finite or * unparseable `value`, matching `formatDate()`/`formatRelativeTime()`'s "unresolvable input" * convention -- `Intl.NumberFormat` throws for `style: 'unit'` paired with the undefined unit a * `NaN` magnitude would otherwise select. * * An omitted `locale` (or `'auto'`) resolves the same way {@link formatNumber} does (this function * delegates the actual number formatting to it): to the page's active `setLyraLocale()` locale, * falling back to `'en'` only once none has been set; an explicit tag always stays authoritative. */ export declare function formatBytes(value:LyraFormattableNumber,locale?:string,options?:LyraFormatBytesOptions):string|undefined;