@mmstack/translate 19.3.5 → 19.3.7

package/lib/format/date.d.ts

@@ -1,5 +1,46 @@
 import { type Signal } from '@angular/core';
-declare const FORMAT_PRESETS: Record<string, Intl.DateTimeFormatOptions>;
+declare const FORMAT_PRESETS: {
+    short: {
+        dateStyle: "short";
+        timeStyle: "short";
+    };
+    medium: {
+        dateStyle: "medium";
+        timeStyle: "medium";
+    };
+    long: {
+        dateStyle: "long";
+        timeStyle: "long";
+    };
+    full: {
+        dateStyle: "full";
+        timeStyle: "full";
+    };
+    shortDate: {
+        dateStyle: "short";
+    };
+    mediumDate: {
+        dateStyle: "medium";
+    };
+    longDate: {
+        dateStyle: "long";
+    };
+    fullDate: {
+        dateStyle: "full";
+    };
+    shortTime: {
+        timeStyle: "short";
+    };
+    mediumTime: {
+        timeStyle: "medium";
+    };
+    longTime: {
+        timeStyle: "long";
+    };
+    fullTime: {
+        timeStyle: "full";
+    };
+};
 type DateFormat = keyof typeof FORMAT_PRESETS;
 /**
  * Supported date inputs
@@ -17,19 +58,44 @@ export type FormatDateOptions = {
      * Format to use for formatting
      * @default 'medium'
      */
-    format?: DateFormat;
+    format?: DateFormat | Intl.DateTimeFormatOptions;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * Locale to use for formatting
      */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+export type UnsafeFormatDateOptions = Omit<FormatDateOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
     locale?: string;
 };
 /**
- * Format a date using the current or provided locale & timezone
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param date - Date to format
- * @param opt - Options for formatting
- * @returns Formatted date string
+ * @example formatDate(this.date, this.locale)
+ */
+export declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, locale: string | Signal<string>): string;
+/**
+ * @example formatDate(this.date, { locale: 'sl-SI', format: 'shortDate' })
+ */
+export declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, opt: FormatDateOptions | Signal<FormatDateOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatDate()` instead, or pass locale explicitly.
+ * @example formatDate(this.date)
+ */
+export declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, opt?: UnsafeFormatDateOptions | Signal<UnsafeFormatDateOptions>): string;
+declare const provideFormatDateDefaults: (valueOrFn: Omit<Partial<FormatDateOptions>, "locale"> | (() => Omit<Partial<FormatDateOptions>, "locale"> | Signal<Omit<Partial<FormatDateOptions>, "locale">>)) => import("@angular/core").Provider;
+/**
+ * Provide application-wide defaults for date formatting presets and timezones.
+ * @example provideFormatDateDefaults({ format: 'shortDate'})
+ */
+export { provideFormatDateDefaults };
+/**
+ * Inject a context-safe date formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatDate = injectFormatDate();
+ * readonly displayDate = computed(() => formatDate(this.date()));
  */
-export declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, opt?: FormatDateOptions | Signal<FormatDateOptions>): string;
-export {};
+export declare function injectFormatDate(): (date: SupportedDateInput | Signal<SupportedDateInput>, optOrLocale?: Partial<FormatDateOptions> | Signal<Partial<FormatDateOptions>> | string | Signal<string>) => string;

package/lib/format/display-name.d.ts

@@ -1,26 +1,51 @@
-import { Signal } from '@angular/core';
+import { type Signal } from '@angular/core';
 /**
  * Options for formatting a display name
  */
 export type FormatDisplayNameOptions = {
     /**
      * The display style for the result set
+     * @default 'long'
      */
-    style: Intl.RelativeTimeFormatStyle;
+    style?: Intl.RelativeTimeFormatStyle;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * Locale to use for formatting
      */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+export type UnsafeFormatDisplayNameOptions = Omit<FormatDisplayNameOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
     locale?: string;
 };
 type SupportedCode = string | null | undefined;
 /**
- * Format a display name using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param value - The code to format
- * @param type - The type of display name to format
- * @param opt - Options for formatting
- * @returns Formatted display name string
+ * @example formatDisplayName(this.value, 'region', this.locale)
+ */
+export declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, locale: string | Signal<string>): string;
+/**
+ * @example formatDisplayName(this.value, 'region', {locale: 'en-US', style: 'long'})
+ */
+export declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, opt: FormatDisplayNameOptions | Signal<FormatDisplayNameOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatDisplayName()` instead, or pass locale explicitly.
+ * @example formatDisplayName(this.value)
+ */
+export declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, opt?: UnsafeFormatDisplayNameOptions | Signal<UnsafeFormatDisplayNameOptions>): string;
+declare const provideFormatDisplayNameDefaults: (valueOrFn: Omit<Partial<FormatDisplayNameOptions>, "locale"> | (() => Omit<Partial<FormatDisplayNameOptions>, "locale"> | Signal<Omit<Partial<FormatDisplayNameOptions>, "locale">>)) => import("@angular/core").Provider;
+/**
+ * Provide application-wide defaults for display name formatting presets and timezones.
+ * @example provideFormatDisplayNameDefaults({ style: 'long'})
+ */
+export { provideFormatDisplayNameDefaults };
+/**
+ * Inject a context-safe date formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatDisplayName = injectFormatDisplayName();
+ * readonly region = computed(() => formatDisplayName('US', 'region'));
  */
-export declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, opt?: FormatDisplayNameOptions | Signal<FormatDisplayNameOptions>): string;
-export {};
+export declare function injectFormatDisplayName(): (value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, localeOrOpt?: FormatDisplayNameOptions | Signal<FormatDisplayNameOptions> | string | Signal<string>) => string;

package/lib/format/index.d.ts

@@ -1,5 +1,6 @@
 export * from './date';
 export * from './display-name';
+export * from './injection';
 export * from './list';
 export * from './numeric';
 export * from './relative-time';

package/lib/format/injection.d.ts

@@ -0,0 +1,27 @@
+import type { Provider } from '@angular/core';
+import { provideFormatDateDefaults } from './date';
+import { provideFormatDisplayNameDefaults } from './display-name';
+import { provideFormatListDefaults } from './list';
+import { provideFormatCurrencyDefaults, provideFormatNumberDefaults, provideFormatPercentDefaults } from './numeric';
+import type { inferProvideParameter } from './provide-defaults';
+import { provideFormatRelativeTimeDefaults } from './relative-time';
+type FormatDefaults = {
+    date?: inferProvideParameter<typeof provideFormatDateDefaults>;
+    displayName?: inferProvideParameter<typeof provideFormatDisplayNameDefaults>;
+    list?: inferProvideParameter<typeof provideFormatListDefaults>;
+    relativeTime?: inferProvideParameter<typeof provideFormatRelativeTimeDefaults>;
+    number?: inferProvideParameter<typeof provideFormatNumberDefaults>;
+    percent?: inferProvideParameter<typeof provideFormatPercentDefaults>;
+    currency?: inferProvideParameter<typeof provideFormatCurrencyDefaults>;
+};
+export declare function provideFormatDefaults(cfg: FormatDefaults): Provider[];
+export declare function injectFormatters(): {
+    date: (date: import("@mmstack/translate").SupportedDateInput | import("@angular/core").Signal<import("@mmstack/translate").SupportedDateInput>, optOrLocale?: Partial<import("@mmstack/translate").FormatDateOptions> | import("@angular/core").Signal<Partial<import("@mmstack/translate").FormatDateOptions>> | string | import("@angular/core").Signal<string>) => string;
+    displayName: (value: (string | null | undefined) | import("@angular/core").Signal<string | null | undefined>, type: Intl.DisplayNamesType | import("@angular/core").Signal<Intl.DisplayNamesType>, localeOrOpt?: import("@mmstack/translate").FormatDisplayNameOptions | import("@angular/core").Signal<import("@mmstack/translate").FormatDisplayNameOptions> | string | import("@angular/core").Signal<string>) => string;
+    list: (value: import("@mmstack/translate").SupportedListInput | import("@angular/core").Signal<import("@mmstack/translate").SupportedListInput>, optOrLocale?: Partial<import("@mmstack/translate").FormatListOptions> | import("@angular/core").Signal<Partial<import("@mmstack/translate").FormatListOptions>> | string | import("@angular/core").Signal<string>) => string;
+    relativeTime: (value: (number | null | undefined) | import("@angular/core").Signal<number | null | undefined>, unit: import("@mmstack/translate").RelativeTimeUnit | import("@angular/core").Signal<import("@mmstack/translate").RelativeTimeUnit>, optOrLocale?: Partial<import("@mmstack/translate").FormatRelativeTimeOptions> | import("@angular/core").Signal<Partial<import("@mmstack/translate").FormatRelativeTimeOptions>> | string | import("@angular/core").Signal<string>) => string;
+    number: (value: (number | null | undefined) | import("@angular/core").Signal<number | null | undefined>, optOrLocale?: Partial<import("@mmstack/translate").FormatNumberOptions> | import("@angular/core").Signal<Partial<import("@mmstack/translate").FormatNumberOptions>> | string | import("@angular/core").Signal<string>) => string;
+    percent: (value: (number | null | undefined) | import("@angular/core").Signal<number | null | undefined>, optOrLocale?: Partial<import("@mmstack/translate").FormatPercentOptions> | import("@angular/core").Signal<Partial<import("@mmstack/translate").FormatPercentOptions>> | string | import("@angular/core").Signal<string>) => string;
+    currency: (value: (number | null | undefined) | import("@angular/core").Signal<number | null | undefined>, currency: string | import("@angular/core").Signal<string>, optOrLocale?: Partial<import("@mmstack/translate").FormatCurrencyOptions> | import("@angular/core").Signal<Partial<import("@mmstack/translate").FormatCurrencyOptions>> | string | import("@angular/core").Signal<string>) => string;
+};
+export {};

package/lib/format/list.d.ts

@@ -8,24 +8,51 @@ export type SupportedListInput = string[] | null | undefined;
 export type FormatListOptions = {
     /**
      * The type of list to format
+     * @default 'conjunction'
      */
     type?: ListType;
     /**
      * The style of list to format
+     * @default 'long'
      */
     style?: ListStyle;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * Locale to use for formatting
      */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+export type UnsafeFormatListOptions = Omit<FormatListOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
     locale?: string;
 };
 /**
- * Format a list using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param value - The list to format
- * @param opt - Options for formatting
- * @returns Formatted list string
+ * @example formatList(this.items, this.locale)
+ */
+export declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, locale: string | Signal<string>): string;
+/**
+ * @example formatList(this.items, { locale: 'sl-SI', type: 'disjunction' })
+ */
+export declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, opt: FormatListOptions | Signal<FormatListOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatList()` instead, or pass locale explicitly.
+ * @example formatList(this.items)
+ */
+export declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, opt?: UnsafeFormatListOptions | Signal<UnsafeFormatListOptions>): string;
+declare const provideFormatListDefaults: (valueOrFn: Omit<Partial<FormatListOptions>, "locale"> | (() => Omit<Partial<FormatListOptions>, "locale"> | Signal<Omit<Partial<FormatListOptions>, "locale">>)) => import("@angular/core").Provider;
+/**
+ * Provide application-wide defaults for list formatting presets.
+ * @example provideFormatListDefaults({ type: 'disjunction' })
+ */
+export { provideFormatListDefaults };
+/**
+ * Inject a context-safe list formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatList = injectFormatList();
+ * readonly displayList = computed(() => formatList(this.items()));
  */
-export declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, opt?: FormatListOptions | Signal<FormatListOptions>): string;
-export {};
+export declare function injectFormatList(): (value: SupportedListInput | Signal<SupportedListInput>, optOrLocale?: Partial<FormatListOptions> | Signal<Partial<FormatListOptions>> | string | Signal<string>) => string;

package/lib/format/numeric.d.ts

@@ -7,6 +7,7 @@ type SupportedNumberValue = number | null | undefined;
 export type FormatNumberOptions = {
     /**
      * The notation to use for formatting
+     * @default 'standard'
      */
     notation?: NumberNotation;
     /**
@@ -19,27 +20,54 @@ export type FormatNumberOptions = {
     maxFractionDigits?: number;
     /**
      * Whether to use grouping
+     * @default true
      */
     useGrouping?: boolean;
-    /**
-     * Locale to use for formatting, opts out to dynamic locale changes
-     */
-    locale?: string;
     /**
      * If the number is not a valid number, return formatted 0. By default formatter returns an empty string
      * @default false
      */
     fallbackToZero?: boolean;
+    /**
+     * Locale to use for formatting
+     */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+export type UnsafeFormatNumberOptions = Omit<FormatNumberOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
+    locale?: string;
 };
 /**
- * Format a number using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param number - Number to format
- * @param opt - Options for formatting
- * @returns Formatted number string
+ * @example formatNumber(this.value, this.locale)
+ */
+export declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, locale: string | Signal<string>): string;
+/**
+ * @example formatNumber(this.value, { locale: 'de-DE', notation: 'compact' })
  */
-export declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: FormatNumberOptions | Signal<FormatNumberOptions>): string;
+export declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt: FormatNumberOptions | Signal<FormatNumberOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatNumber()` instead, or pass locale explicitly.
+ * @example formatNumber(this.value)
+ */
+export declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: UnsafeFormatNumberOptions | Signal<UnsafeFormatNumberOptions>): string;
+declare const provideFormatNumberDefaults: (valueOrFn: Omit<Partial<FormatNumberOptions>, "locale"> | (() => Omit<Partial<FormatNumberOptions>, "locale"> | Signal<Omit<Partial<FormatNumberOptions>, "locale">>)) => import("@angular/core").Provider;
+/**
+ * Provide application-wide defaults for number formatting presets.
+ * @example provideFormatNumberDefaults({ notation: 'compact' })
+ */
+export { provideFormatNumberDefaults };
+/**
+ * Inject a context-safe number formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatNumber = injectFormatNumber();
+ * readonly display = computed(() => formatNumber(this.value()));
+ */
+export declare function injectFormatNumber(): (value: SupportedNumberValue | Signal<SupportedNumberValue>, optOrLocale?: Partial<FormatNumberOptions> | Signal<Partial<FormatNumberOptions>> | string | Signal<string>) => string;
 /**
  * Options for formatting a percentage value
  */
@@ -52,40 +80,97 @@ export type FormatPercentOptions = {
      * Maximum number of fraction digits to use
      */
     maxFractionDigits?: number;
-    /**
-     * Locale to use for formatting, opts out to dynamic locale changes
-     */
-    locale?: string;
     /**
      * If the number is not a valid number, return formatted 0. By default formatter returns an empty string
      * @default false
      */
     fallbackToZero?: boolean;
+    /**
+     * Locale to use for formatting
+     */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+export type UnsafeFormatPercentOptions = Omit<FormatPercentOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
+    locale?: string;
 };
 /**
- * Format a percentage using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param number - Number to format
- * @param opt - Options for formatting
- * @returns Formatted percentage string
+ * @example formatPercent(this.value, this.locale)
  */
-export declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: FormatPercentOptions | Signal<FormatPercentOptions>): string;
+export declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, locale: string | Signal<string>): string;
+/**
+ * @example formatPercent(this.value, { locale: 'de-DE', maxFractionDigits: 2 })
+ */
+export declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt: FormatPercentOptions | Signal<FormatPercentOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatPercent()` instead, or pass locale explicitly.
+ * @example formatPercent(this.value)
+ */
+export declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: UnsafeFormatPercentOptions | Signal<UnsafeFormatPercentOptions>): string;
+declare const provideFormatPercentDefaults: (valueOrFn: Omit<Partial<FormatPercentOptions>, "locale"> | (() => Omit<Partial<FormatPercentOptions>, "locale"> | Signal<Omit<Partial<FormatPercentOptions>, "locale">>)) => import("@angular/core").Provider;
+/**
+ * Provide application-wide defaults for percent formatting presets.
+ * @example provideFormatPercentDefaults({ maxFractionDigits: 1 })
+ */
+export { provideFormatPercentDefaults };
+/**
+ * Inject a context-safe percent formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ */
+export declare function injectFormatPercent(): (value: SupportedNumberValue | Signal<SupportedNumberValue>, optOrLocale?: Partial<FormatPercentOptions> | Signal<Partial<FormatPercentOptions>> | string | Signal<string>) => string;
 type CurrencyDisplay = 'symbol' | 'narrowSymbol' | 'code' | 'name';
 /**
  * Options for formatting a currency
  */
 export type FormatCurrencyOptions = {
-    display?: CurrencyDisplay;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * The display type for the currency format
+     * @default 'symbol'
      */
-    locale?: string;
+    display?: CurrencyDisplay;
     /**
      * If the number is not a valid number, return formatted 0. By default formatter returns an empty string
      * @default false
      */
     fallbackToZero?: boolean;
+    /**
+     * Locale to use for formatting
+     */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+export type UnsafeFormatCurrencyOptions = Omit<FormatCurrencyOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
+    locale?: string;
 };
-export declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, opt?: FormatCurrencyOptions | Signal<FormatCurrencyOptions>): string;
-export {};
+/**
+ * @example formatCurrency(this.value, 'USD', this.locale)
+ */
+export declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, locale: string | Signal<string>): string;
+/**
+ * @example formatCurrency(this.value, 'EUR', { locale: 'de-DE', display: 'code' })
+ */
+export declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, opt: FormatCurrencyOptions | Signal<FormatCurrencyOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatCurrency()` instead, or pass locale explicitly.
+ * @example formatCurrency(this.value, 'USD')
+ */
+export declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, opt?: UnsafeFormatCurrencyOptions | Signal<UnsafeFormatCurrencyOptions>): string;
+declare const provideFormatCurrencyDefaults: (valueOrFn: Omit<Partial<FormatCurrencyOptions>, "locale"> | (() => Omit<Partial<FormatCurrencyOptions>, "locale"> | Signal<Omit<Partial<FormatCurrencyOptions>, "locale">>)) => import("@angular/core").Provider;
+/**
+ * Provide application-wide defaults for currency formatting presets.
+ * @example provideFormatCurrencyDefaults({ display: 'code' })
+ */
+export { provideFormatCurrencyDefaults };
+/**
+ * Inject a context-safe currency formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ */
+export declare function injectFormatCurrency(): (value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, optOrLocale?: Partial<FormatCurrencyOptions> | Signal<Partial<FormatCurrencyOptions>> | string | Signal<string>) => string;

package/lib/format/provide-defaults.d.ts

@@ -0,0 +1,5 @@
+import { type Provider, type Signal } from '@angular/core';
+export declare function createFormatterProvider<T extends {
+    locale: string;
+}>(formatterName: string, libraryDefaults: Omit<T, 'locale'>, nonLocaleEqual: (a: Omit<T, 'locale'>, b: Omit<T, 'locale'>) => boolean): readonly [(valueOrFn: Omit<Partial<T>, "locale"> | (() => Omit<Partial<T>, "locale"> | Signal<Omit<Partial<T>, "locale">>)) => Provider, () => Signal<T>];
+export type inferProvideParameter<T extends ReturnType<typeof createFormatterProvider>[0]> = Parameters<T>[0];

package/lib/format/relative-time.d.ts

@@ -14,20 +14,44 @@ export type FormatRelativeTimeOptions = {
      */
     numeric?: Intl.RelativeTimeFormatNumeric;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * Locale to use for formatting
      */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+export type UnsafeFormatRelativeTimeOptions = Omit<FormatRelativeTimeOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
     locale?: string;
 };
 export type RelativeTimeUnit = Intl.RelativeTimeFormatUnit;
 type SupportedRelativeTimeInput = number | null | undefined;
 /**
- * Format a relative time using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param value - The numeric value to use in the relative time internationalization message
- * @param unit - The unit to use in the relative time internationalization message
- * @param opt - Options for formatting
- * @returns Formatted relative time string
+ * @example formatRelativeTime(this.value, this.unit, this.locale)
+ */
+export declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, locale: string | Signal<string>): string;
+/**
+ * @example formatRelativeTime(this.value, 'day', { locale: 'sl-SI', numeric: 'auto' })
+ */
+export declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, opt: FormatRelativeTimeOptions | Signal<FormatRelativeTimeOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatRelativeTime()` instead, or pass locale explicitly.
+ * @example formatRelativeTime(this.value, 'day')
+ */
+export declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, opt?: UnsafeFormatRelativeTimeOptions | Signal<UnsafeFormatRelativeTimeOptions>): string;
+declare const provideFormatRelativeTimeDefaults: (valueOrFn: Omit<Partial<FormatRelativeTimeOptions>, "locale"> | (() => Omit<Partial<FormatRelativeTimeOptions>, "locale"> | Signal<Omit<Partial<FormatRelativeTimeOptions>, "locale">>)) => import("@angular/core").Provider;
+/**
+ * Provide application-wide defaults for relative time formatting presets.
+ * @example provideFormatRelativeTimeDefaults({ numeric: 'auto' })
+ */
+export { provideFormatRelativeTimeDefaults };
+/**
+ * Inject a context-safe relative time formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatRelativeTime = injectFormatRelativeTime();
+ * readonly relativeAge = computed(() => formatRelativeTime(this.delta(), 'day'));
  */
-export declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, opt?: FormatRelativeTimeOptions | Signal<FormatRelativeTimeOptions>): string;
-export {};
+export declare function injectFormatRelativeTime(): (value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, optOrLocale?: Partial<FormatRelativeTimeOptions> | Signal<Partial<FormatRelativeTimeOptions>> | string | Signal<string>) => string;

package/lib/parameterize.type.d.ts

@@ -15,7 +15,28 @@ export type extractParams<T extends string> = T extends `${infer _Start}{${infer
 type mergeParams<TExtracted extends [string, any]> = {
     [K in TExtracted as K[0]]: K[1];
 };
-type flattenParams<TKey extends string, TVal> = TVal extends UnknownStringKeyObject ? inferParamTupples<TVal, `${TKey}.`> : TVal extends string ? extractParams<TVal> extends never ? [TKey] : [TKey, mergeParams<extractParams<TVal>>] : never;
+declare const PARAM_BRAND: unique symbol;
+/**
+ * Branded string type produced by `withParams<P>(message)`. The brand carries
+ * both the declared parameter shape `P` and the original literal message `S` —
+ * the literal lives inside the brand (not just on the intersection) so the
+ * inference machinery can recover it without going through template-literal
+ * pattern matching on a branded intersection (which widens `infer` slots to
+ * `string` and breaks auto-extraction). Module-local `unique symbol`, so the
+ * brand is not constructible outside this package.
+ */
+export type WithParams<P extends Record<string, unknown>, S extends string = string> = S & {
+    readonly [PARAM_BRAND]: {
+        params: P;
+        literal: S;
+    };
+};
+type flattenParams<TKey extends string, TVal> = TVal extends {
+    readonly [PARAM_BRAND]: {
+        params: infer P;
+        literal: infer S extends string;
+    };
+} ? P extends Record<string, unknown> ? extractParams<S> extends never ? [TKey, P] : [TKey, Omit<mergeParams<extractParams<S>>, keyof P> & P] : [TKey] : TVal extends UnknownStringKeyObject ? inferParamTupples<TVal, `${TKey}.`> : TVal extends string ? extractParams<TVal> extends never ? [TKey] : [TKey, mergeParams<extractParams<TVal>>] : never;
 type inferParamTupples<T extends UnknownStringKeyObject, TPrefix extends string = ''> = Simplify<{
     [K in keyof T]: K extends string ? flattenParams<`${TPrefix}${K}`, T[K]> : never;
 }[keyof T]>;
@@ -27,6 +48,8 @@ type TypeEnsuringAllPlaceholders<PlaceholdersUnion extends string> = StringConta
 export type extractParamString<T extends string> = T extends `${infer _Start}{${infer Var}}${infer End}` ? Var extends `${infer VarName},${string}` ? `{${VarName}, ${string}}` | extractParamString<End> : `{${Var}}` | extractParamString<End> : never;
 type inferParamsFromValue<V extends string> = extractParamString<V> extends never ? string : TypeEnsuringAllPlaceholders<extractParamString<V>>;
 export type inferTranslationShape<T extends UnknownStringKeyObject> = {
-    [K in keyof T]: T[K] extends UnknownStringKeyObject ? inferTranslationShape<T[K]> : T[K] extends string ? inferParamsFromValue<T[K]> : never;
+    [K in keyof T]: T[K] extends {
+        readonly [PARAM_BRAND]: any;
+    } ? string : T[K] extends UnknownStringKeyObject ? inferTranslationShape<T[K]> : T[K] extends string ? inferParamsFromValue<T[K]> : never;
 };
 export {};

package/lib/register-namespace.d.ts

@@ -3,6 +3,7 @@ import { ResolveFn } from '@angular/router';
 import { type CompiledTranslation, type inferCompiledTranslationMap, type inferCompiledTranslationNamespace } from './compile';
 import { type AnyStringRecord, type UnknownStringKeyObject } from './string-key-object.type';
 import { TranslationStore } from './translation-store';
+import * as i0 from "@angular/core";
 type TFunction<TMap extends AnyStringRecord> = <TKey extends keyof TMap & string>(key: TKey, ...args: TMap[TKey] extends void ? [] : [TMap[TKey]]) => string;
 type SignalTFunction<TMap extends AnyStringRecord> = <TKey extends keyof TMap & string>(key: TKey, ...args: TMap[TKey] extends void ? [] : [() => TMap[TKey]]) => Signal<string>;
 type TFunctionWithSignalConstructor<TMap extends AnyStringRecord, TFN extends TFunction<TMap>> = TFN & {
@@ -26,4 +27,26 @@ export declare function registerRemoteNamespace<TNS extends string>(ns: TNS, def
     injectNamespaceT: () => UntypedTFunction<TNS>;
     resolveNamespaceTranslation: ResolveFn<void>;
 };
+export declare class UnsafeTKeyMap {
+    readonly map: Map<string, string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UnsafeTKeyMap, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UnsafeTKeyMap>;
+}
+/**
+ * Power-user escape hatch that returns a fully untyped translation function.
+ * Intended for use alongside {@link injectAddTranslations} when translations
+ * are added imperatively (e.g. from a remote API), or for cross-namespace
+ * lookups where the typed API would be impractical.
+ *
+ * @example
+ * ```ts
+ * const t = injectUnsafeT();
+ * t('any.namespace.key', { name: 'Alice', count: 3 });
+ * const sig = t.asSignal('any.namespace.key', () => ({ name: name() }));
+ * ```
+ */
+export declare function injectUnsafeT(): {
+    (key: string, params?: Record<string, string | number>): string;
+    asSignal(key: string, params?: () => Record<string, string | number>): Signal<string>;
+};
 export {};

package/lib/translation-store.d.ts

@@ -28,6 +28,11 @@ export declare function provideIntlConfig(config: Config): Provider[];
 export declare function injectIntlConfig(): Config | undefined;
 export declare function injectDefaultLocale(): string;
 export declare function injectSupportedLocales(): string[];
+/**
+ * @internal
+ * @deprecated will be removed when ng23 drops
+ */
+export declare function readLocaleUnsafe(): string;
 export declare function injectLocaleInternal(): WritableSignal<string>;
 export declare class TranslationStore {
     private readonly simpleKeyMap;
@@ -82,4 +87,22 @@ export declare function injectIntl(): Signal<import("@formatjs/intl").IntlShape<
 export declare function injectDynamicLocale(): WritableSignal<string> & {
     isLoading: Signal<boolean>;
 };
+/**
+ * Power-user escape hatch for adding translations imperatively (e.g. content
+ * loaded from a remote API after bootstrap). Returns a function that registers
+ * a flat per-locale map of keys under a given namespace
+ *
+ * Pair with {@link injectUnsafeT} to read the added keys without compile-time
+ * constraints.
+ *
+ * @example
+ * ```ts
+ * const addTranslations = injectAddTranslations();
+ * addTranslations('remote', {
+ *   'en-US': { greeting: 'Hi {name}' },
+ *   'sl-SI': { greeting: 'Zdravo {name}' },
+ * });
+ * ```
+ */
+export declare function injectAddTranslations(): (ns: string, translations: Record<string, Record<string, string>>) => void;
 export {};