@mmstack/translate 20.5.4 → 20.5.6

package/index.d.ts

@@ -1,5 +1,6 @@
 import * as i0 from '@angular/core';
-import { WritableSignal, Signal, Provider } from '@angular/core';
+import { Signal, WritableSignal, Provider } from '@angular/core';
+import { ResolveFn, ActivatedRouteSnapshot, CanMatchFn } from '@angular/router';
 import * as _formatjs_intl from '@formatjs/intl';
 import { IntlConfig } from '@formatjs/intl';
 
@@ -64,7 +65,226 @@ type TranslationNamespace<TNS extends string, T extends CompiledTranslation<Unkn
 };
 declare function createNamespace<const T extends UnknownStringKeyObject, TNS extends string>(ns: TNS, translation: T): TranslationNamespace<TNS, CompiledTranslation<T, TNS, string>, inferTranslationShape<T>>;
 
-declare function provideIntlConfig(config: Omit<IntlConfig, 'locale' | 'messages'>): Provider;
+declare const FORMAT_PRESETS: Record<string, Intl.DateTimeFormatOptions>;
+type DateFormat = keyof typeof FORMAT_PRESETS;
+/**
+ * Supported date inputs
+ */
+type SupportedDateInput = Date | string | number | null | undefined;
+/**
+ * Options for formatting a date
+ */
+type FormatDateOptions = {
+    /**
+     * Timezone to use for formatting
+     */
+    tz?: string;
+    /**
+     * Format to use for formatting
+     * @default 'medium'
+     */
+    format?: DateFormat;
+    /**
+     * Locale to use for formatting, opts out to dynamic locale changes
+     */
+    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
+ */
+declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, opt?: FormatDateOptions | Signal<FormatDateOptions>): string;
+
+/**
+ * Options for formatting a display name
+ */
+type FormatDisplayNameOptions = {
+    /**
+     * The display style for the result set
+     */
+    style: Intl.RelativeTimeFormatStyle;
+    /**
+     * Locale to use for formatting, opts out to dynamic locale changes
+     */
+    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
+ */
+declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, opt?: FormatDisplayNameOptions | Signal<FormatDisplayNameOptions>): string;
+
+type ListType = 'conjunction' | 'disjunction' | 'unit';
+type ListStyle = 'long' | 'short' | 'narrow';
+type SupportedListInput = string[] | null | undefined;
+/**
+ * Options for formatting a list
+ */
+type FormatListOptions = {
+    /**
+     * The type of list to format
+     */
+    type?: ListType;
+    /**
+     * The style of list to format
+     */
+    style?: ListStyle;
+    /**
+     * Locale to use for formatting, opts out to dynamic locale changes
+     */
+    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
+ */
+declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, opt?: FormatListOptions | Signal<FormatListOptions>): string;
+
+type NumberNotation = 'standard' | 'scientific' | 'engineering' | 'compact';
+type SupportedNumberValue = number | null | undefined;
+/**
+ * Options for formatting a number
+ */
+type FormatNumberOptions = {
+    /**
+     * The notation to use for formatting
+     */
+    notation?: NumberNotation;
+    /**
+     * Minimum number of fraction digits to use
+     */
+    minFractionDigits?: number;
+    /**
+     * Maximum number of fraction digits to use
+     */
+    maxFractionDigits?: number;
+    /**
+     * Whether to use grouping
+     */
+    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;
+};
+/**
+ * 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
+ */
+declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: FormatNumberOptions | Signal<FormatNumberOptions>): string;
+/**
+ * Options for formatting a percentage value
+ */
+type FormatPercentOptions = {
+    /**
+     * Minimum number of fraction digits to use
+     */
+    minFractionDigits?: number;
+    /**
+     * 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;
+};
+/**
+ * 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
+ */
+declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: FormatPercentOptions | Signal<FormatPercentOptions>): string;
+type CurrencyDisplay = 'symbol' | 'narrowSymbol' | 'code' | 'name';
+/**
+ * Options for formatting a currency
+ */
+type FormatCurrencyOptions = {
+    display?: CurrencyDisplay;
+    /**
+     * 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;
+};
+declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, opt?: FormatCurrencyOptions | Signal<FormatCurrencyOptions>): string;
+
+/**
+ * Options for formatting a relative time value
+ */
+type FormatRelativeTimeOptions = {
+    /**
+     * The length of the internationalized message.
+     * @default 'long'
+     */
+    style?: Intl.RelativeTimeFormatStyle;
+    /**
+     * Controls whether to use numeric values in the output.
+     * @default 'always'
+     */
+    numeric?: Intl.RelativeTimeFormatNumeric;
+    /**
+     * Locale to use for formatting, opts out to dynamic locale changes
+     */
+    locale?: string;
+};
+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
+ */
+declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, opt?: FormatRelativeTimeOptions | Signal<FormatRelativeTimeOptions>): string;
+
+declare function provideIntlConfig(config: Omit<IntlConfig, 'locale' | 'messages'> & {
+    /** Checks next locale is in provided array before switching locales */
+    supportedLocales?: string[];
+    /** Preloads the default locale ensuring sync fallback, not necessary for most cases as it will lazily load automatically when needed */
+    preloadDefaultLocale?: boolean;
+    /** Auto-resolution when using a locale parameter via angular router */
+    localeParamName?: string;
+}): Provider[];
+declare function injectSupportedLocales(): string[];
 declare function injectIntl(): Signal<_formatjs_intl.IntlShape<string>>;
 /**
  * Inject a dynamic locale signal that supports runtime language switching.
@@ -97,8 +317,74 @@ type TFunctionWithSignalConstructor<TMap extends AnyStringRecord, TFN extends TF
 };
 declare function registerNamespace<TDefault extends CompiledTranslation<UnknownStringKeyObject, string>>(defaultTranslation: () => Promise<TDefault>, other: Record<string, () => Promise<CompiledTranslation<UnknownStringKeyObject, inferCompiledTranslationNamespace<TDefault>, string>>>): {
     injectNamespaceT: () => TFunctionWithSignalConstructor<inferCompiledTranslationMap<TDefault>, TFunction<inferCompiledTranslationMap<TDefault>>>;
-    resolveNamespaceTranslation: () => Promise<void>;
+    resolveNamespaceTranslation: ResolveFn<void>;
+};
+type UntypedTFunction<TNS extends string> = {
+    (key: `${TNS}.${string}`, args?: Record<string, string>): string;
+    asSignal: (key: `${TNS}.${string}`, args?: () => Record<string, string>) => Signal<string>;
 };
+/**
+ * Registers a type-unsafe namespace, meant for remote loading of unknown key-value pairs using mmstack/translate infrastructure
+ * The resolver & t function work the same as they would with typed namespaces, but without type safety
+ */
+declare function registerRemoteNamespace<TNS extends string>(ns: TNS, defaultTranslation: () => Promise<Record<string, string>>, other: Record<string, () => Promise<Record<string, string>>>): {
+    injectNamespaceT: () => UntypedTFunction<TNS>;
+    resolveNamespaceTranslation: ResolveFn<void>;
+};
+
+declare function injectResolveParamLocale(snapshot: ActivatedRouteSnapshot): string;
+
+/**
+ * Guard that validates the locale parameter against supported locales.
+ * Redirects to default locale if the locale is invalid.
+ *
+ * @param prefixSegments Optional array of path segments preceding the locale segment.
+ * if (you wanted to match /app/:locale/... you would pass ['app'] here) & the function would match the second parameter + redirect accordingly
+ *
+ * @example
+ * ```typescript
+ * {
+ *   path: ':locale',
+ *   canMatch: [canMatchLocale()],
+ *   children: [...]
+ * }
+ * ```
+ */
+declare function canMatchLocale(prefixSegments?: string[]): CanMatchFn;
+
+/**
+ * Options designed to feed into the mock translations function.
+ */
+interface MockTranslationOptions {
+    /**
+     * If provided, allows overriding the default behavior of simply echoing translation keys back.
+     * Format: Record of namespace -> (Translation shape similar to what you pass to `createNamespace`)
+     *
+     * Example:
+     * ```ts
+     * {
+     *   home: { title: 'Mocked Title' },
+     *   auth: { error: 'Mocked Error' }
+     * }
+     * ```
+     */
+    translations?: Record<string, UnknownStringKeyObject>;
+}
+/**
+ * Provides an isolated mock `TranslationStore` usable across testing modules that use components
+ * depending on `@mmstack/translate` APIs (like `Translate` directive, `Translator` pipe, or `injectNamespaceT`).
+ *
+ * This provider intercepts all translation logic, bypassing chunk loaders and Intl.
+ * When a custom configuration isn't provided, formatMessage simply echoes the translation key, using dots `.`.
+ *
+ * ### Usage
+ * ```typescript
+ * TestBed.configureTestingModule({
+ *   providers: [provideMockTranslations()]
+ * });
+ * ```
+ */
+declare function provideMockTranslations(options?: MockTranslationOptions): Provider[];
 
 declare abstract class Translate<TInput extends string, T extends CompiledTranslation<UnknownStringKeyObject, string>, TMap extends inferCompiledTranslationMap<T> = inferCompiledTranslationMap<T>, TKey extends TInput & keyof TMap & string = TInput & keyof TMap & string> {
     private readonly t;
@@ -115,5 +401,5 @@ declare abstract class Translator<T extends CompiledTranslation<UnknownStringKey
     transform<K extends keyof TMap & string>(key: K, ...args: TMap[K] extends void ? [locale?: string] : [TMap[K], locale?: string]): string;
 }
 
-export { Translate, Translator, compileTranslation, createNamespace, injectDynamicLocale, injectIntl, provideIntlConfig, registerNamespace };
-export type { CompiledTranslation, inferCompiledTranslationMap, inferCompiledTranslationNamespace, inferCompiledTranslationShape, mergeTranslationMaps };
+export { Translate, Translator, canMatchLocale, compileTranslation, createNamespace, formatCurrency, formatDate, formatDisplayName, formatList, formatNumber, formatPercent, formatRelativeTime, injectDynamicLocale, injectIntl, injectResolveParamLocale, injectSupportedLocales, provideIntlConfig, provideMockTranslations, registerNamespace, registerRemoteNamespace };
+export type { CompiledTranslation, FormatCurrencyOptions, FormatDateOptions, FormatDisplayNameOptions, FormatListOptions, FormatNumberOptions, FormatPercentOptions, FormatRelativeTimeOptions, RelativeTimeUnit, SupportedDateInput, SupportedListInput, inferCompiledTranslationMap, inferCompiledTranslationNamespace, inferCompiledTranslationShape, mergeTranslationMaps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/translate",
-  "version": "20.5.4",
+  "version": "20.5.6",
   "keywords": [
     "angular",
     "localize",
@@ -15,7 +15,8 @@
   },
   "peerDependencies": {
     "@angular/core": ">=20 <21",
-    "@formatjs/intl": "~3.1.6"
+    "@angular/router": ">=20 <21",
+    "@formatjs/intl": "~3.1.8 || ^4.0.0"
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/translate",
   "sideEffects": false,