@rivinia/i18n 0.7.1 → 0.8.0

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/CHANGELOG.md CHANGED
@@ -2,6 +2,86 @@
2
2
 
3
3
  Pre-1.0 policy: a minor bump may break, a patch is a bug fix.
4
4
 
5
+ ## 0.8.0 - 2026-10-31
6
+
7
+ The language picker: a third entry point, `@rivinia/i18n/select`, composed from
8
+ `@rivinia/select` instead of re-implementing a listbox. Additive — no core or `/ui`
9
+ signature changed, and no new dependency for consumers that do not import it.
10
+
11
+ - **`@rivinia/i18n/select` entry point.** Own FESM and types chunk, exported as
12
+ `exports["./select"]`. `@rivinia/select` (`^0.7.0`) is declared as an **optional**
13
+ peer: the core and `/ui` entry points never import it, so an application that does
14
+ not import `@rivinia/i18n/select` neither installs the peer nor pays for its code.
15
+ The core and `/ui` FESMs in this tarball are byte-identical to 0.7.2's.
16
+ - **`RiviniaLanguageSelect` (`rv-language-select`).** One trigger, one option per
17
+ configured language, in declared order, showing the native name. Managed
18
+ (`[manager]`, structurally satisfied by `RiviniaI18n`) or presentational
19
+ (`[languages]` + `[current]`); a manager wins over the presentational inputs. The
20
+ managed path goes through `setLanguageAsync()`, which never rejects, so the trigger
21
+ never keeps a failed pick: after a failure it falls back to the manager's current
22
+ language.
23
+ - **A later intent outvotes a switch still in flight.** Managed picks are
24
+ last-wins: resolving an older `setLanguageAsync()` after the user has picked again
25
+ emits nothing. That includes re-picking the language that is _currently_ current —
26
+ no manager call is made for it, but it still supersedes the pending switch, whose
27
+ confirmation must not surface as a change the user never asked for
28
+ (`projects/i18n/tests/language-select.spec.ts`, holds the manager's promise open and
29
+ re-picks the current language; it fails without the guard).
30
+ - **Each row name carries `lang` and `dir`.** `العربية` is pronounced as Arabic and
31
+ laid out right-to-left even while the page runs `en`; the language id is an
32
+ accessible hint when the native name differs from it. The closed trigger is
33
+ `rv-select`'s own value span and inherits the page language — the marking starts at
34
+ the panel (documented in the README).
35
+ - **`languageSelectOptions(languages)` and `LanguageSelectOption`.** The pure mapper
36
+ the component uses, exported for consumers who want `rv-select` with their own
37
+ trigger or row. It preserves order and resolves each name as `nativeName` →
38
+ `Intl.DisplayNames` → id, the same rule as `/ui`.
39
+ - **`RiviniaLanguageManager` and `LanguageLike` are re-exported** from this entry, so
40
+ a consumer importing only `/select` does not need `@rivinia/i18n/ui` on the side.
41
+ - **The picker owns a width floor.** The host is `inline-block` with
42
+ `min-inline-size: 14rem`. `rv-select`'s own `min-width: min(14rem, 100%)` cannot
43
+ supply it: inside a shrink-to-fit host that `100%` resolves to `0`, so a bare
44
+ `<rv-language-select [manager]="i18n" />` rendered the trigger, the panel and every
45
+ row one character wide, and `English` wrapped as `En / gli / sh`. Caught in the
46
+ packed build in a browser, not by a build or a test double; the `i18n-e2e` suite now
47
+ measures the host, the panel and the row line count in Chromium and Firefox, and both
48
+ geometry tests fail when the floor is removed.
49
+ - Packaging/build: the new entry consumes `@rivinia/select/ui` from dist, so
50
+ `build:select` runs before `build:i18n`. No new byte budget for anyone else: the
51
+ tarball grows by the `/select` FESM, its map and its types, and the pack gate checks
52
+ the built FESM — only `fesm2022/rivinia-i18n-select.mjs` may mention
53
+ `@rivinia/select/ui`.
54
+ - Proven end-to-end: 371 tests in 35 files; the repo's `i18n-e2e` Playwright suite
55
+ green (96 tests across Chromium, system Chrome and Firefox, four of them the new
56
+ `/select` page); two clean consumers built from the packed tarball — one without the
57
+ peer (its JS contains no select code at all) and one with the peer and a lazy route
58
+ (the picker lands in a 45.71 kB / 10.72 kB chunk, zero occurrences of
59
+ `rv-language-select` in the initial bundle); and a real-browser run of the packed
60
+ build in Chromium and Firefox, 30 checks each over a three-language `ar`/`en`/`de`
61
+ demo: rows' `lang`/`dir`, managed pick flipping `<html lang>` to the locale
62
+ (`de-DE`) and `dir`, a presentational pick leaving the manager untouched, and no
63
+ console, page or network errors. WebKit was **not run** — the host is missing
64
+ `libavif.so.16`, so MiniBrowser cannot launch.
65
+
66
+ ## 0.7.2 - 2026-10-30
67
+
68
+ - **Fixed: a view-transition switch kept the previous dictionary.** With
69
+ `viewTransition.enabled`, `applyLanguage()` started the dictionary load
70
+ before the transition callback changed `currentLanguage`. A cached
71
+ dictionary applies synchronously, and `DictionaryStore._apply()` publishes
72
+ only the dictionary whose language is current — so the new dictionary was
73
+ discarded and the UI stayed in the old language. The first switch worked
74
+ when `skipInitialTransition` ran it synchronously; every later switch did
75
+ not. The load and `ensureFallback()` now run inside the transition callback,
76
+ after `_currentLanguageId.set(id)`.
77
+ - Two regression tests hold the transition callback and switch twice — one
78
+ through `setLanguage()`, one through the preload-first `setLanguageAsync()`
79
+ path (`projects/i18n/tests/view-transition-switch.spec.ts`); both fail on
80
+ the pre-fix code. The packed build was
81
+ also exercised in the `rv-tailwind` demo with `viewTransition` enabled:
82
+ `ar → en → ar → en → ar → en`, with the heading, `<html lang>` and persisted
83
+ language correct on every step and no console errors. No API change.
84
+
5
85
  ## 0.7.1 - 2026-10-29
6
86
 
7
87
  0.7.0 was never published; this release ships it unchanged and adds one option and one
package/README.md CHANGED
@@ -3,6 +3,10 @@
3
3
  [![npm version](https://img.shields.io/npm/v/@rivinia/i18n.svg)](https://www.npmjs.com/package/@rivinia/i18n)
4
4
  [![license](https://img.shields.io/npm/l/@rivinia/i18n.svg)](https://www.npmjs.com/package/@rivinia/i18n)
5
5
 
6
+ <p align="center">
7
+ <img src="https://raw.githubusercontent.com/abdelfattahqandil21-oss/Revinia/main/assets/rivinia-abstract-mark-light.svg" alt="Rivinia" width="140" />
8
+ </p>
9
+
6
10
  A headless Angular language manager built on signals. Key-based JSON
7
11
  dictionaries, inline translations, RTL/LTR document attributes, lazy loaders,
8
12
  ICU plural/select messages, browser-language detection, and `Intl` number/date
@@ -13,10 +17,12 @@ Concretely: the text lives in JSON files, components ask for a key, and the whol
13
17
  app — text, direction, dates, numbers — follows the language the user picked.
14
18
  Arabic is a first-class target, not an afterthought of an English layout.
15
19
 
16
- - Package version: **0.7.1**
17
- - Peer dependency: **`@angular/core` `^22.0.0`** (plus `@angular-devkit/schematics` for `ng add`)
18
- - Entry points: **`@rivinia/i18n`** (headless core) and **`@rivinia/i18n/ui`**
19
- (the standalone language toggle)
20
+ - Package version: **0.8.0**
21
+ - Peer dependency: **`@angular/core` `^22.0.0`** (plus `@angular-devkit/schematics` for `ng add`,
22
+ and an optional `@rivinia/select` `^0.7.0` for the `/select` entry point)
23
+ - Entry points: **`@rivinia/i18n`** (headless core), **`@rivinia/i18n/ui`**
24
+ (the standalone language toggle) and **`@rivinia/i18n/select`** (the
25
+ multi-language picker)
20
26
  - `sideEffects: false`; no runtime import beyond `@angular/core`; loaders are lazy chunks
21
27
  - No `HttpClient` peer — the built-in loaders use `fetch`
22
28
 
@@ -507,6 +513,33 @@ button, and works with the service (`[manager]`) or without it (`[languages]` +
507
513
  templates, presentational mode, styling hooks and the accessibility contract are in the
508
514
  [toggle reference](#toggle-reference).
509
515
 
516
+ ### The language select
517
+
518
+ The toggle flips between exactly two languages. For `ar`, `en`, `de`, … use the
519
+ third entry point, which composes `@rivinia/select` into a list:
520
+
521
+ ```bash
522
+ npm install @rivinia/select
523
+ ```
524
+
525
+ ```ts
526
+ import { RiviniaLanguageSelect } from '@rivinia/i18n/select';
527
+ // <rv-language-select [manager]="i18n" label="Language" />
528
+ ```
529
+
530
+ Every language becomes one row, in the order declared, with its native name. Each row
531
+ name carries `lang` and `dir`, so `العربية` is pronounced as Arabic even while the page
532
+ runs `en`. The closed trigger is `rv-select`'s own text and carries no `lang`, so the
533
+ marking starts at the panel. Managed mode (`[manager]`) calls `setLanguageAsync` and emits
534
+ `(languageChange)` only after the switch is confirmed; presentational mode
535
+ (`[languages]` + `[current]`) emits synchronously. `searchable` adds the filter box for
536
+ long lists, and `variant="premium"` applies the select's premium skin.
537
+
538
+ `@rivinia/select` is an **optional peer**: the core and `/ui` entry points never
539
+ import it, so an application that does not import `@rivinia/i18n/select` does not
540
+ install it and its bundle does not grow. The full contract is in the
541
+ [select reference](#select-reference).
542
+
510
543
  ### Server-side rendering
511
544
 
512
545
  The default loader works on the server: `REQUEST` plus `<base href>` produce an absolute
@@ -1089,8 +1122,9 @@ supported shape for three or more languages, not something the toggle turns into
1089
1122
  - **Inside a menu.** The toggle is a plain `<button>` in normal flow, so it can sit in a
1090
1123
  panel that already exists — `@rivinia/menu/ui` ships the menu primitives. The menu's
1091
1124
  focus trap and keyboard model with this control inside it have **not** been tested.
1092
- - **Beside a native `<select>`.** For three or more languages, bind the select to the
1093
- service and leave the toggle out:
1125
+ - **Beside a native `<select>`.** For three or more languages, prefer the ready-made
1126
+ [language select](#select-reference) and leave the toggle out. If you need a native
1127
+ element instead, bind it to the service:
1094
1128
 
1095
1129
  ```html
1096
1130
  <select (change)="i18n.setLanguage($any($event.target).value)">
@@ -1113,6 +1147,149 @@ A globe does not name a language it cannot represent, and it says "switch langua
1113
1147
  without saying which. An app that wants its own mark passes `[icon]`, or draws one
1114
1148
  inside `rvLanguageTrigger`; either way the accessible name is unaffected.
1115
1149
 
1150
+ ### Select reference
1151
+
1152
+ The `@rivinia/i18n/select` entry point ships the multi-language picker and the pure
1153
+ mapper behind it:
1154
+
1155
+ ```ts
1156
+ import { RiviniaLanguageSelect, languageSelectOptions } from '@rivinia/i18n/select';
1157
+ ```
1158
+
1159
+ **Every export of this entry point is Experimental in 0.8.0**:
1160
+ `RiviniaLanguageSelect`, `languageSelectOptions`, `LanguageSelectOption`, and the
1161
+ re-exported `LanguageLike` / `RiviniaLanguageManager`. The select is a composition over
1162
+ `@rivinia/select/ui`; its public surface may follow that package's pre-1.0 changes.
1163
+
1164
+ #### Managed, with `RiviniaI18n`
1165
+
1166
+ ```ts
1167
+ import { Component, inject } from '@angular/core';
1168
+ import { RiviniaI18n } from '@rivinia/i18n';
1169
+ import { RiviniaLanguageSelect } from '@rivinia/i18n/select';
1170
+
1171
+ @Component({
1172
+ selector: 'app-header',
1173
+ imports: [RiviniaLanguageSelect],
1174
+ template: `<rv-language-select
1175
+ [manager]="i18n"
1176
+ [label]="label()"
1177
+ [searchable]="true"
1178
+ (languageChange)="onLanguage($event)"
1179
+ />`,
1180
+ })
1181
+ export class Header {
1182
+ readonly i18n = inject(RiviniaI18n<'ar' | 'en' | 'de'>);
1183
+ readonly label = this.i18n.t('common.language');
1184
+ }
1185
+ ```
1186
+
1187
+ `RiviniaI18n` satisfies `RiviniaLanguageManager` structurally, so pass the service
1188
+ directly. Managed state wins: `[languages]`, `[current]` and `[busy]` are ignored while
1189
+ `manager` is set. The trigger shows the current language's native name; the panel lists
1190
+ every language in declaration order.
1191
+
1192
+ `(languageChange)` fires **after** `setLanguageAsync` confirms the id, matching the
1193
+ toggle's contract. A manager that leaves the language unchanged emits nothing and the
1194
+ trigger returns to the real current language. While the manager reports
1195
+ `loadingState() === 'loading'`, the control is disabled, so a second pick cannot race the
1196
+ first.
1197
+
1198
+ #### Presentational, without a manager
1199
+
1200
+ ```html
1201
+ <rv-language-select
1202
+ [languages]="languages"
1203
+ [current]="language()"
1204
+ [busy]="switching()"
1205
+ label="Language"
1206
+ (languageChange)="language.set($event)"
1207
+ />
1208
+ ```
1209
+
1210
+ With no manager, `languages` + `current` describe the state and `languageChange` is the
1211
+ only side effect. Presentational mode is synchronous; the picked row stays selected until
1212
+ `[current]` changes, then the trigger follows the new value.
1213
+
1214
+ #### Inputs and output
1215
+
1216
+ | Input | Type | Default | Meaning |
1217
+ | ------------------- | ------------------------- | ------------------ | --------------------------------------------------------------------------------- |
1218
+ | `manager` | `RiviniaLanguageManager` | — | Managed mode; wins over `languages` / `current` / `busy`. |
1219
+ | `languages` | `readonly LanguageLike[]` | `[]` | Presentational language list. |
1220
+ | `current` | `string` | — | Presentational current id. |
1221
+ | `label` | `string \| null` | `null` | Visible caption; also the trigger's accessible name and the panel's default name. |
1222
+ | `ariaLabel` | `string \| null` | `null` | Accessible name when there is no visible caption. |
1223
+ | `popupLabel` | `string \| null` | `null` | Explicit panel name; defaults to `label`, then `ariaLabel`. |
1224
+ | `placeholder` | `string` | `'Select…'` | Trigger text when nothing is selected. |
1225
+ | `searchable` | `boolean` | `false` | Show the filter box. |
1226
+ | `searchLabel` | `string` | `'Search options'` | Filter box accessible name. |
1227
+ | `searchPlaceholder` | `string` | `'Search…'` | Filter box placeholder. |
1228
+ | `emptyLabel` | `string` | `'No results'` | Shown when the filter matches nothing. |
1229
+ | `variant` | `'simple' \| 'premium'` | `'simple'` | Passed to `rv-select`. |
1230
+ | `disabled` | `boolean` | `false` | Blocks opening and picking. |
1231
+ | `busy` | `boolean` | `false` | Presentational loading state. |
1232
+
1233
+ | Output | Payload | When |
1234
+ | ---------------- | -------- | ------------------------------------------------------------------------- |
1235
+ | `languageChange` | `string` | After a managed switch confirms, or synchronously in presentational mode. |
1236
+
1237
+ #### Sizing
1238
+
1239
+ The host is `inline-block` with a `min-inline-size: 14rem` floor. `rv-select` cannot
1240
+ supply it: its own `min-width: min(14rem, 100%)` resolves that `100%` to `0` inside a
1241
+ shrink-to-fit host, so without the floor the trigger, the panel and every row collapse to
1242
+ one character per line (`English` becomes `En / gli / sh`). Widen it with ordinary CSS —
1243
+ `rv-language-select { inline-size: 100% }` in a form row — and the panel follows the
1244
+ trigger within `rv-select`'s own limits. The `i18n-e2e` suite measures this in Chromium
1245
+ and Firefox.
1246
+
1247
+ #### Rows and accessibility
1248
+
1249
+ Each row carries `lang` and `dir` on the visible name, so a screen reader pronounces
1250
+ `العربية` as Arabic even when the page runs `en`, and the name lays out in its own
1251
+ direction. The closed trigger is `rv-select`'s value span and has no `lang`/`dir` hook of
1252
+ its own, so it inherits the page's language — the marking lives in the panel. The row's
1253
+ accessible name is its visible text: the native name, plus the
1254
+ language id as a hint when the two differ. The id is not repeated when the label already
1255
+ is the id.
1256
+
1257
+ `languageSelectOptions(languages)` is the pure mapper used by the component. It preserves
1258
+ order, resolves the name with the same rule as `/ui` (`nativeName` → `Intl.DisplayNames` →
1259
+ id), and returns:
1260
+
1261
+ ```ts
1262
+ interface LanguageSelectOption extends RiviniaSelectOption {
1263
+ readonly lang: string;
1264
+ readonly dir?: 'ltr' | 'rtl';
1265
+ }
1266
+ ```
1267
+
1268
+ Use it directly when you want `rv-select` with your own trigger or row:
1269
+
1270
+ ```ts
1271
+ import { languageSelectOptions } from '@rivinia/i18n/select';
1272
+
1273
+ readonly options = computed(() => languageSelectOptions(this.i18n.languages()));
1274
+ ```
1275
+
1276
+ #### Optional peer and bundle isolation
1277
+
1278
+ `@rivinia/select` is declared as an **optional peer** of `@rivinia/i18n`:
1279
+
1280
+ ```json
1281
+ {
1282
+ "peerDependencies": { "@rivinia/select": "^0.7.0" },
1283
+ "peerDependenciesMeta": { "@rivinia/select": { "optional": true } }
1284
+ }
1285
+ ```
1286
+
1287
+ The core and `/ui` entry points never import it. Only
1288
+ `fesm2022/rivinia-i18n-select.mjs` contains `@rivinia/select/ui`, so an application that
1289
+ does not import `@rivinia/i18n/select` neither installs the peer nor pays for its code.
1290
+ The unit surface spec checks the sources for this; the release gates then inspect the
1291
+ built FESM.
1292
+
1116
1293
  ### SSR reference
1117
1294
 
1118
1295
  The default loader works on the server: `REQUEST` plus `<base href>` produce an absolute
@@ -1157,6 +1334,9 @@ import {
1157
1334
  customLoader,
1158
1335
  formatIcu,
1159
1336
  } from '@rivinia/i18n';
1337
+
1338
+ import { RiviniaLanguageToggle, RiviniaLanguageTrigger } from '@rivinia/i18n/ui';
1339
+ import { RiviniaLanguageSelect, languageSelectOptions } from '@rivinia/i18n/select';
1160
1340
  ```
1161
1341
 
1162
1342
  ### API stability
@@ -1165,26 +1345,30 @@ Every export is classified so the 1.0 freeze is predictable. **Internal** symbol
1165
1345
  exist only so the package's own tests can import them; they may move to an
1166
1346
  `@rivinia/i18n/internal` entry point (or disappear) before 1.0.
1167
1347
 
1168
- | Export | Kind | Tier |
1169
- | ---------------------------------------------------------------------------------------------- | ---------------- | ------------ |
1170
- | `RiviniaI18n` | service | Stable |
1171
- | `provideRiviniaI18n`, `defineRiviniaI18n`, `injectRiviniaI18n` | providers | Stable |
1172
- | `RvTranslatePipe` (`rvTranslate`) | pipe | Stable |
1173
- | `RiviniaI18nConfig` | type | Stable |
1174
- | `Language`, `Direction`, `Translation`, `TranslateParams`, `StorageStrategy`, `SwitchStrategy` | types | Stable |
1175
- | `RiviniaLoadError` | class | Stable |
1176
- | `MissingKeyEvent`, `MissingParamEvent` | types | Stable |
1177
- | `TranslationLoader`, `LoaderDescriptor`, `LoaderContext` | types | Stable |
1178
- | `jsonLoader`, `httpLoader`, `remoteLoader`, `customLoader` | loader factories | Stable |
1179
- | `HttpLoaderOptions`, `RemoteLoaderOptions` | types | Stable |
1180
- | `formatIcu`, `IcuFormatOptions` | ICU API | Stable |
1181
- | `RegisteredI18nKey`, `RiviniaI18nKeyRegistry` | typed-keys types | Stable |
1182
- | `ViewTransitionConfig`, `ViewTransitionInfo` | types | Experimental |
1183
- | `ViewTransitionService` | service | Internal |
1184
- | `parseCookie`, `serializeCookie` | cookie helpers | Internal |
1185
- | `browserLanguages`, `detectBrowserLanguage` | helpers | Internal |
1186
- | `RiviniaLanguageToggle` (`rv-language-toggle`), `RiviniaLanguageTrigger` (`rvLanguageTrigger`) | `/ui` components | Experimental |
1187
- | `RiviniaLanguageManager`, `LanguageLike`, `RiviniaLanguageTriggerContext` | `/ui` types | Experimental |
1348
+ | Export | Kind | Tier |
1349
+ | ---------------------------------------------------------------------------------------------- | ------------------- | ------------ |
1350
+ | `RiviniaI18n` | service | Stable |
1351
+ | `provideRiviniaI18n`, `defineRiviniaI18n`, `injectRiviniaI18n` | providers | Stable |
1352
+ | `RvTranslatePipe` (`rvTranslate`) | pipe | Stable |
1353
+ | `RiviniaI18nConfig` | type | Stable |
1354
+ | `Language`, `Direction`, `Translation`, `TranslateParams`, `StorageStrategy`, `SwitchStrategy` | types | Stable |
1355
+ | `RiviniaLoadError` | class | Stable |
1356
+ | `MissingKeyEvent`, `MissingParamEvent` | types | Stable |
1357
+ | `TranslationLoader`, `LoaderDescriptor`, `LoaderContext` | types | Stable |
1358
+ | `jsonLoader`, `httpLoader`, `remoteLoader`, `customLoader` | loader factories | Stable |
1359
+ | `HttpLoaderOptions`, `RemoteLoaderOptions` | types | Stable |
1360
+ | `formatIcu`, `IcuFormatOptions` | ICU API | Stable |
1361
+ | `RegisteredI18nKey`, `RiviniaI18nKeyRegistry` | typed-keys types | Stable |
1362
+ | `ViewTransitionConfig`, `ViewTransitionInfo` | types | Experimental |
1363
+ | `ViewTransitionService` | service | Internal |
1364
+ | `parseCookie`, `serializeCookie` | cookie helpers | Internal |
1365
+ | `browserLanguages`, `detectBrowserLanguage` | helpers | Internal |
1366
+ | `RiviniaLanguageToggle` (`rv-language-toggle`), `RiviniaLanguageTrigger` (`rvLanguageTrigger`) | `/ui` components | Experimental |
1367
+ | `RiviniaLanguageManager`, `LanguageLike`, `RiviniaLanguageTriggerContext` | `/ui` types | Experimental |
1368
+ | `RiviniaLanguageSelect` (`rv-language-select`) | `/select` component | Experimental |
1369
+ | `languageSelectOptions` | `/select` helper | Experimental |
1370
+ | `LanguageSelectOption` | `/select` type | Experimental |
1371
+ | `LanguageLike`, `RiviniaLanguageManager` (re-exported) | `/select` types | Experimental |
1188
1372
 
1189
1373
  ### Migration 0.5.0 to 0.6.0
1190
1374