@rivinia/i18n 0.6.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rivinia/i18n",
3
- "version": "0.6.0",
3
+ "version": "0.7.2",
4
4
  "description": "Headless Angular language manager: signals, RTL, SSR-safe loaders, fallback language, missing-key reporting, ICU plurals, typed keys.",
5
5
  "keywords": [
6
6
  "angular",
@@ -50,6 +50,10 @@
50
50
  ".": {
51
51
  "types": "./types/rivinia-i18n.d.ts",
52
52
  "default": "./fesm2022/rivinia-i18n.mjs"
53
+ },
54
+ "./ui": {
55
+ "types": "./types/rivinia-i18n-ui.d.ts",
56
+ "default": "./fesm2022/rivinia-i18n-ui.mjs"
53
57
  }
54
58
  },
55
59
  "type": "module",
@@ -0,0 +1,112 @@
1
+ import { Direction } from "@rivinia/i18n";
2
+ import * as i0 from "@angular/core";
3
+ import { TemplateRef } from "@angular/core";
4
+ /** The slice of a language entry the toggle needs. Structurally satisfied by
5
+ * `Language` from @rivinia/i18n (which requires `dir`). */
6
+ interface LanguageLike {
7
+ readonly id: string;
8
+ readonly nativeName?: string;
9
+ readonly dir?: Direction;
10
+ readonly locale?: string;
11
+ }
12
+ /** The structural slice of `RiviniaI18n` the toggle drives (D30 shape).
13
+ * `RiviniaI18n` satisfies it with no import from core at runtime. */
14
+ interface RiviniaLanguageManager {
15
+ readonly languages: () => readonly LanguageLike[];
16
+ readonly currentLanguage: () => string;
17
+ readonly loadingState: () => 'idle' | 'loading' | 'error';
18
+ setLanguageAsync(id: string): Promise<void>;
19
+ }
20
+ /**
21
+ * The language toggle: one inner `<button>` that switches to the other language
22
+ * of a two-language manager (or presentational pair). The host is the API; the
23
+ * button owns the name, `lang` and `dir`.
24
+ */
25
+ export declare class RiviniaLanguageToggle {
26
+ readonly manager: import("@angular/core").InputSignal<RiviniaLanguageManager | undefined>;
27
+ readonly languages: import("@angular/core").InputSignal<readonly LanguageLike[]>;
28
+ readonly current: import("@angular/core").InputSignal<string | undefined>;
29
+ readonly label: import("@angular/core").InputSignal<string | undefined>;
30
+ readonly busy: import("@angular/core").InputSignal<boolean>;
31
+ readonly disabled: import("@angular/core").InputSignal<boolean>;
32
+ /** Replaces the default globe. Rendered as-is, so size it with the icon box. */
33
+ readonly icon: import("@angular/core").InputSignal<TemplateRef<unknown> | null>;
34
+ readonly languageChange: import("@angular/core").OutputEmitterRef<string>;
35
+ readonly template: import("@angular/core").Signal<TemplateRef<any> | undefined>;
36
+ private readonly slot;
37
+ private readonly iconSlot;
38
+ private readonly sourceLanguages;
39
+ readonly languageCount: import("@angular/core").Signal<number>;
40
+ readonly manyLanguages: import("@angular/core").Signal<boolean>;
41
+ private readonly currentId;
42
+ /** The language activating the button switches to; `undefined` when nothing renders. */
43
+ readonly target: import("@angular/core").Signal<LanguageLike | undefined>;
44
+ readonly isBusy: import("@angular/core").Signal<boolean>;
45
+ readonly visibleName: import("@angular/core").Signal<string>;
46
+ readonly accessibleName: import("@angular/core").Signal<string>;
47
+ readonly dataLanguages: import("@angular/core").Signal<"2" | "many" | null>;
48
+ private rendered;
49
+ private renderedIcon;
50
+ private warnedMany;
51
+ private warnedLabel;
52
+ ngAfterViewChecked(): void;
53
+ activate(targetId: string): Promise<void>;
54
+ private warn;
55
+ private renderIcon;
56
+ private renderTrigger;
57
+ static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaLanguageToggle, never>;
58
+ static ɵcmp: i0.ɵɵComponentDeclaration<RiviniaLanguageToggle, "rv-language-toggle", never, {
59
+ "manager": {
60
+ "alias": "manager";
61
+ "required": false;
62
+ "isSignal": true;
63
+ };
64
+ "languages": {
65
+ "alias": "languages";
66
+ "required": false;
67
+ "isSignal": true;
68
+ };
69
+ "current": {
70
+ "alias": "current";
71
+ "required": false;
72
+ "isSignal": true;
73
+ };
74
+ "label": {
75
+ "alias": "label";
76
+ "required": false;
77
+ "isSignal": true;
78
+ };
79
+ "busy": {
80
+ "alias": "busy";
81
+ "required": false;
82
+ "isSignal": true;
83
+ };
84
+ "disabled": {
85
+ "alias": "disabled";
86
+ "required": false;
87
+ "isSignal": true;
88
+ };
89
+ "icon": {
90
+ "alias": "icon";
91
+ "required": false;
92
+ "isSignal": true;
93
+ };
94
+ }, {
95
+ "languageChange": "languageChange";
96
+ }, ["template"], never, true, never>;
97
+ }
98
+ interface RiviniaLanguageTriggerContext {
99
+ $implicit: LanguageLike;
100
+ busy: boolean;
101
+ }
102
+ /**
103
+ * Marks the `<ng-template>` rendered inside the button in place of the default
104
+ * name span. The toggle captures it with `contentChild(..., { read: TemplateRef })`
105
+ * and renders it through `ViewContainerRef`, so the template is created only when
106
+ * the button is — and never on the server beyond the same pass.
107
+ */
108
+ export declare class RiviniaLanguageTrigger {
109
+ static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaLanguageTrigger, never>;
110
+ static ɵdir: i0.ɵɵDirectiveDeclaration<RiviniaLanguageTrigger, "[rvLanguageTrigger]", never, {}, {}, never, never, true, never>;
111
+ }
112
+ export type { LanguageLike, RiviniaLanguageManager, RiviniaLanguageTriggerContext };
@@ -123,7 +123,13 @@ interface MissingParamEvent<T extends string = string> {
123
123
  */
124
124
  interface RiviniaI18nConfig<T extends string = string> {
125
125
  readonly languages: readonly Language<T>[];
126
- readonly defaultLanguage: T;
126
+ /**
127
+ * Language used on a first visit (no stored preference, detection off).
128
+ * Defaults to the first entry of `languages`. When provided it must be a
129
+ * non-empty id present in `languages` — anything else throws at construction
130
+ * instead of resolving to an undefined language.
131
+ */
132
+ readonly defaultLanguage?: T;
127
133
  /**
128
134
  * Language used when a key is absent from the current dictionary. Must be
129
135
  * one of `languages`. The fallback dictionary is loaded silently (it never
@@ -146,6 +152,13 @@ interface RiviniaI18nConfig<T extends string = string> {
146
152
  readonly switchStrategy?: SwitchStrategy;
147
153
  /** Called when a dictionary load fails. The service still falls back safely. */
148
154
  readonly onLoadError?: (language: T, error: unknown) => void;
155
+ /**
156
+ * Log a `console.error` when a dictionary fails to load and no `onLoadError`
157
+ * handler is configured. A failed load leaves every key unresolved, so the
158
+ * page renders raw key names; the warning fires once per language per session.
159
+ * @default isDevMode() && !onLoadError
160
+ */
161
+ readonly warnOnLoadError?: boolean;
149
162
  /**
150
163
  * Called when `translate()` cannot resolve a key (absent from the current
151
164
  * dictionary, from the fallback dictionary, and with no `defaultValue`).
@@ -332,8 +345,23 @@ export declare class RiviniaI18n<L extends string = string> {
332
345
  readonly loaderContext: LoaderContext;
333
346
  /** Declared before the storage collaborator: it reads this during setup. */
334
347
  private readonly _languages;
348
+ /**
349
+ * Resolved before the storage collaborator reads it: the explicit
350
+ * `defaultLanguage`, else the first configured language. A malformed value
351
+ * throws here instead of letting `undefined` become the current language.
352
+ */
353
+ private readonly _defaultLanguageId;
335
354
  private readonly _languageStorage;
336
355
  private readonly _currentLanguageId;
356
+ /** Languages already reported by the default load-error warning. */
357
+ private readonly _warnedLoadErrors;
358
+ /**
359
+ * Routes every dictionary load failure to the consumer handler, or — when
360
+ * none is configured — to the dev-mode warning. Warnings are deduped per
361
+ * language because a retry loop would otherwise flood the console; the
362
+ * consumer handler keeps firing per failure for telemetry.
363
+ */
364
+ private readonly _onDictionaryLoadError;
337
365
  private readonly _store;
338
366
  private _initialized;
339
367
  private readonly _tasks;
@@ -463,15 +491,38 @@ export declare class RiviniaI18n<L extends string = string> {
463
491
  static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaI18n<any>, never>;
464
492
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
465
493
  }
494
+ /**
495
+ * Type-level scan for a repeated language id. It only sees a tuple, i.e. a
496
+ * `languages` list written inline in the config. A hoisted `const LANGS = […]`
497
+ * widens to an array, where this resolves to `never` — there the runtime check
498
+ * thrown from `RiviniaI18n`'s constructor is the guarantee.
499
+ */
500
+ type DuplicateLanguageId<T extends readonly {
501
+ readonly id: string;
502
+ }[], Seen extends string = never> = T extends readonly [infer Head extends {
503
+ readonly id: string;
504
+ }, ...infer Rest extends readonly {
505
+ readonly id: string;
506
+ }[]] ? Head['id'] extends Seen ? Head['id'] | DuplicateLanguageId<Rest, Seen | Head['id']> : DuplicateLanguageId<Rest, Seen | Head['id']> : never;
507
+ type AssertUniqueLanguageIds<T extends readonly {
508
+ readonly id: string;
509
+ }[]> = DuplicateLanguageId<T> extends (infer Duplicate) ? [Duplicate] extends [never] ? unknown : {
510
+ readonly duplicateLanguageId: Duplicate;
511
+ } : never;
466
512
  /**
467
513
  * Configures `@rivinia/i18n` for the application. Call once at bootstrap.
468
514
  * Also registers an app initializer that loads the initial language before
469
515
  * first paint (opt out with `preload: false`).
470
516
  *
517
+ * A repeated id written inline (`languages: [AR, EN, AR]`) is a compile error.
518
+ * The check needs the array literal, so it is skipped when the call supplies
519
+ * the language union explicitly (`<'ar' | 'en'>`) or passes a hoisted list —
520
+ * both still fail at bootstrap with the runtime error. `Language` in TS terms
521
+ * (not this guard) is what requires `dir`.
522
+ *
471
523
  * @example
472
524
  * ```ts
473
525
  * provideRiviniaI18n({
474
- * defaultLanguage: 'ar',
475
526
  * languages: [
476
527
  * { id: 'ar', nativeName: 'العربية', dir: 'rtl' },
477
528
  * { id: 'en', nativeName: 'English', dir: 'ltr' },
@@ -481,25 +532,29 @@ export declare class RiviniaI18n<L extends string = string> {
481
532
  *
482
533
  * @example
483
534
  * ```ts
484
- * const AR = { id: 'ar', nativeName: 'العربية', dir: 'rtl' };
485
- * const EN = { id: 'en', nativeName: 'English', dir: 'ltr' };
486
- * provideRiviniaI18n({
487
- * defaultLanguage: 'ar',
535
+ * // `as const` keeps `id` and `dir` literal — hoisted objects would
536
+ * // otherwise widen to `string` and fail the `Language` check.
537
+ * const AR = { id: 'ar', nativeName: 'العربية', dir: 'rtl' } as const;
538
+ * const EN = { id: 'en', nativeName: 'English', dir: 'ltr' } as const;
539
+ * provideRiviniaI18n<'ar' | 'en'>({
488
540
  * languages: [AR, EN],
489
541
  * })
490
542
  * ```
491
543
  */
492
- export declare function provideRiviniaI18n<L extends string>(config: RiviniaI18nConfig<L>): EnvironmentProviders;
544
+ export declare function provideRiviniaI18n<L extends string, const C extends RiviniaI18nConfig<L> = RiviniaI18nConfig<L>>(config: C & AssertUniqueLanguageIds<C['languages']> & RiviniaI18nConfig<L>): EnvironmentProviders;
493
545
  /** Shorthand for `inject(RiviniaI18n)` — preserves the configured language union. */
494
546
  export declare function injectRiviniaI18n<L extends string = string>(): RiviniaI18n<L>;
495
547
  /**
496
548
  * Binds a config and its typed accessors together so `L` is inferred once
497
549
  * from the configuration instead of being lost at the injection site.
498
550
  *
551
+ * Like `provideRiviniaI18n`, a repeated id in an inline `languages` list is a
552
+ * compile error; supplying the union explicitly or hoisting the list keeps the
553
+ * runtime check as the guard.
554
+ *
499
555
  * @example
500
556
  * ```ts
501
557
  * export const i18n = defineRiviniaI18n({
502
- * defaultLanguage: 'ar',
503
558
  * languages: [
504
559
  * { id: 'ar', nativeName: 'العربية', dir: 'rtl' },
505
560
  * { id: 'en', nativeName: 'English', dir: 'ltr' },
@@ -511,10 +566,10 @@ export declare function injectRiviniaI18n<L extends string = string>(): RiviniaI
511
566
  * const lang = i18n.inject();
512
567
  * ```
513
568
  */
514
- export declare function defineRiviniaI18n<L extends string>(config: RiviniaI18nConfig<L>): {
515
- readonly config: RiviniaI18nConfig<L>;
569
+ export declare function defineRiviniaI18n<L extends string, const C extends RiviniaI18nConfig<L> = RiviniaI18nConfig<L>>(config: C & AssertUniqueLanguageIds<C['languages']> & RiviniaI18nConfig<L>): {
570
+ readonly config: C;
516
571
  provide: () => EnvironmentProviders;
517
- inject: () => RiviniaI18n<L>;
572
+ inject: () => RiviniaI18n<C['languages'][number]['id']>;
518
573
  };
519
574
  /**
520
575
  * Progressive-enhancement wrapper around the View Transition API.