shared-lib-web 0.0.2 → 0.0.4

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.
Files changed (206) hide show
  1. package/README.md +192 -528
  2. package/dist/components/app-brand.d.ts.map +1 -1
  3. package/dist/components/app-brand.js +9 -5
  4. package/dist/components/app-brand.js.map +1 -1
  5. package/dist/components/coming-soon.d.ts.map +1 -1
  6. package/dist/components/coming-soon.js +3 -2
  7. package/dist/components/coming-soon.js.map +1 -1
  8. package/dist/components/language-switcher.d.ts +5 -1
  9. package/dist/components/language-switcher.d.ts.map +1 -1
  10. package/dist/components/language-switcher.js +20 -7
  11. package/dist/components/language-switcher.js.map +1 -1
  12. package/dist/components/otp-modal.d.ts +5 -0
  13. package/dist/components/otp-modal.d.ts.map +1 -0
  14. package/dist/components/otp-modal.js +77 -0
  15. package/dist/components/otp-modal.js.map +1 -0
  16. package/dist/components/settings-menu.d.ts +4 -0
  17. package/dist/components/settings-menu.d.ts.map +1 -1
  18. package/dist/components/settings-menu.js +15 -2
  19. package/dist/components/settings-menu.js.map +1 -1
  20. package/dist/context/use-ui.d.ts.map +1 -1
  21. package/dist/context/use-ui.js +4 -3
  22. package/dist/context/use-ui.js.map +1 -1
  23. package/dist/i18n/browser-language.d.ts +9 -0
  24. package/dist/i18n/browser-language.d.ts.map +1 -0
  25. package/dist/i18n/browser-language.js +89 -0
  26. package/dist/i18n/browser-language.js.map +1 -0
  27. package/dist/i18n/default-messages.d.ts.map +1 -1
  28. package/dist/i18n/default-messages.js +15 -0
  29. package/dist/i18n/default-messages.js.map +1 -1
  30. package/dist/i18n/locale-groups.d.ts +18 -0
  31. package/dist/i18n/locale-groups.d.ts.map +1 -0
  32. package/dist/i18n/locale-groups.js +74 -0
  33. package/dist/i18n/locale-groups.js.map +1 -0
  34. package/dist/i18n/locale-service.d.ts +22 -4
  35. package/dist/i18n/locale-service.d.ts.map +1 -1
  36. package/dist/i18n/locale-service.js +95 -27
  37. package/dist/i18n/locale-service.js.map +1 -1
  38. package/dist/i18n/locale-signal.d.ts +18 -0
  39. package/dist/i18n/locale-signal.d.ts.map +1 -0
  40. package/dist/i18n/locale-signal.js +142 -0
  41. package/dist/i18n/locale-signal.js.map +1 -0
  42. package/dist/i18n/translator.d.ts +8 -1
  43. package/dist/i18n/translator.d.ts.map +1 -1
  44. package/dist/i18n/translator.js +36 -12
  45. package/dist/i18n/translator.js.map +1 -1
  46. package/dist/index.d.ts +24 -11
  47. package/dist/index.d.ts.map +1 -1
  48. package/dist/index.js +21 -8
  49. package/dist/index.js.map +1 -1
  50. package/dist/interfaces/app-types.d.ts +6 -0
  51. package/dist/interfaces/app-types.d.ts.map +1 -1
  52. package/dist/interfaces/ui-config.d.ts +184 -15
  53. package/dist/interfaces/ui-config.d.ts.map +1 -1
  54. package/dist/interfaces/ui-context.d.ts +1 -1
  55. package/dist/interfaces/ui-context.d.ts.map +1 -1
  56. package/dist/layouts/auth-layout.js +1 -1
  57. package/dist/layouts/auth-layout.js.map +1 -1
  58. package/dist/providers/provider-effects.d.ts +2 -2
  59. package/dist/providers/provider-effects.d.ts.map +1 -1
  60. package/dist/providers/provider-effects.js +4 -1
  61. package/dist/providers/provider-effects.js.map +1 -1
  62. package/dist/providers/register-config.d.ts.map +1 -1
  63. package/dist/providers/register-config.js +2 -0
  64. package/dist/providers/register-config.js.map +1 -1
  65. package/dist/providers/shared-web-ui-provider.d.ts +7 -19
  66. package/dist/providers/shared-web-ui-provider.d.ts.map +1 -1
  67. package/dist/providers/shared-web-ui-provider.js +21 -22
  68. package/dist/providers/shared-web-ui-provider.js.map +1 -1
  69. package/dist/query/query-param.d.ts +4 -1
  70. package/dist/query/query-param.d.ts.map +1 -1
  71. package/dist/query/query-param.js +6 -3
  72. package/dist/query/query-param.js.map +1 -1
  73. package/dist/state/api-loader.d.ts +19 -0
  74. package/dist/state/api-loader.d.ts.map +1 -0
  75. package/dist/state/api-loader.js +187 -0
  76. package/dist/state/api-loader.js.map +1 -0
  77. package/dist/state/auth-service.d.ts +9 -0
  78. package/dist/state/auth-service.d.ts.map +1 -1
  79. package/dist/state/auth-service.js +70 -3
  80. package/dist/state/auth-service.js.map +1 -1
  81. package/dist/state/branch-service.d.ts +1 -1
  82. package/dist/state/branch-service.js +3 -3
  83. package/dist/state/branch-service.js.map +1 -1
  84. package/dist/state/company-service.d.ts +16 -0
  85. package/dist/state/company-service.d.ts.map +1 -0
  86. package/dist/state/company-service.js +97 -0
  87. package/dist/state/company-service.js.map +1 -0
  88. package/dist/state/language-service.d.ts +5 -2
  89. package/dist/state/language-service.d.ts.map +1 -1
  90. package/dist/state/language-service.js +12 -7
  91. package/dist/state/language-service.js.map +1 -1
  92. package/dist/state/layout-choice-service.d.ts +10 -0
  93. package/dist/state/layout-choice-service.d.ts.map +1 -0
  94. package/dist/state/layout-choice-service.js +34 -0
  95. package/dist/state/layout-choice-service.js.map +1 -0
  96. package/dist/state/menu-service.d.ts +1 -1
  97. package/dist/state/menu-service.js +2 -2
  98. package/dist/state/menu-service.js.map +1 -1
  99. package/dist/state/otp-service.d.ts +69 -0
  100. package/dist/state/otp-service.d.ts.map +1 -0
  101. package/dist/state/otp-service.js +212 -0
  102. package/dist/state/otp-service.js.map +1 -0
  103. package/dist/state/preference-sync.d.ts +1 -1
  104. package/dist/state/preference-sync.d.ts.map +1 -1
  105. package/dist/state/preference-sync.js +11 -3
  106. package/dist/state/preference-sync.js.map +1 -1
  107. package/dist/state/signals.d.ts +9 -1
  108. package/dist/state/signals.d.ts.map +1 -1
  109. package/dist/state/signals.js +28 -4
  110. package/dist/state/signals.js.map +1 -1
  111. package/dist/theme/custom-themes.d.ts +28 -0
  112. package/dist/theme/custom-themes.d.ts.map +1 -0
  113. package/dist/theme/custom-themes.js +218 -0
  114. package/dist/theme/custom-themes.js.map +1 -0
  115. package/dist/theme/dark-themes.d.ts +9 -1
  116. package/dist/theme/dark-themes.d.ts.map +1 -1
  117. package/dist/theme/dark-themes.js +74 -2
  118. package/dist/theme/dark-themes.js.map +1 -1
  119. package/dist/theme/logo.d.ts +6 -3
  120. package/dist/theme/logo.d.ts.map +1 -1
  121. package/dist/theme/logo.js +17 -3
  122. package/dist/theme/logo.js.map +1 -1
  123. package/dist/theme/theme-service.d.ts +14 -3
  124. package/dist/theme/theme-service.d.ts.map +1 -1
  125. package/dist/theme/theme-service.js +64 -10
  126. package/dist/theme/theme-service.js.map +1 -1
  127. package/dist/types/field-wrapper.d.ts +2 -0
  128. package/dist/types/field-wrapper.d.ts.map +1 -1
  129. package/dist/types/field-wrapper.js +3 -2
  130. package/dist/types/field-wrapper.js.map +1 -1
  131. package/dist/types/type.otp.d.ts +2 -0
  132. package/dist/types/type.otp.d.ts.map +1 -1
  133. package/dist/types/type.otp.js +2 -2
  134. package/dist/types/type.otp.js.map +1 -1
  135. package/dist/utils/app-http.d.ts +41 -1
  136. package/dist/utils/app-http.d.ts.map +1 -1
  137. package/dist/utils/app-http.js +188 -12
  138. package/dist/utils/app-http.js.map +1 -1
  139. package/dist/utils/content-util.d.ts +6 -0
  140. package/dist/utils/content-util.d.ts.map +1 -0
  141. package/dist/utils/content-util.js +45 -0
  142. package/dist/utils/content-util.js.map +1 -0
  143. package/dist/utils/error-util.d.ts +3 -0
  144. package/dist/utils/error-util.d.ts.map +1 -0
  145. package/dist/utils/error-util.js +58 -0
  146. package/dist/utils/error-util.js.map +1 -0
  147. package/dist/utils/language-util.d.ts +3 -3
  148. package/dist/utils/language-util.d.ts.map +1 -1
  149. package/dist/utils/language-util.js +7 -7
  150. package/dist/utils/language-util.js.map +1 -1
  151. package/dist/utils/menu-util.js +1 -1
  152. package/dist/utils/menu-util.js.map +1 -1
  153. package/dist/utils/signal-source.d.ts +4 -0
  154. package/dist/utils/signal-source.d.ts.map +1 -0
  155. package/dist/utils/signal-source.js +13 -0
  156. package/dist/utils/signal-source.js.map +1 -0
  157. package/dist/utils/storage-keys.d.ts +5 -0
  158. package/dist/utils/storage-keys.d.ts.map +1 -1
  159. package/dist/utils/storage-keys.js +5 -0
  160. package/dist/utils/storage-keys.js.map +1 -1
  161. package/package.json +3 -3
  162. package/src/components/app-brand.tsx +9 -5
  163. package/src/components/coming-soon.tsx +3 -2
  164. package/src/components/language-switcher.tsx +26 -7
  165. package/src/components/otp-modal.tsx +154 -0
  166. package/src/components/settings-menu.tsx +28 -2
  167. package/src/context/use-ui.ts +4 -3
  168. package/src/i18n/browser-language.ts +98 -0
  169. package/src/i18n/default-messages.ts +15 -0
  170. package/src/i18n/locale-groups.ts +87 -0
  171. package/src/i18n/locale-service.ts +99 -27
  172. package/src/i18n/locale-signal.ts +173 -0
  173. package/src/i18n/translator.ts +38 -12
  174. package/src/index.ts +102 -4
  175. package/src/interfaces/app-types.ts +6 -0
  176. package/src/interfaces/ui-config.ts +191 -15
  177. package/src/interfaces/ui-context.ts +1 -1
  178. package/src/layouts/auth-layout.tsx +1 -1
  179. package/src/providers/provider-effects.ts +5 -2
  180. package/src/providers/register-config.ts +2 -0
  181. package/src/providers/shared-web-ui-provider.tsx +26 -43
  182. package/src/query/query-param.ts +6 -2
  183. package/src/state/api-loader.ts +205 -0
  184. package/src/state/auth-service.ts +84 -3
  185. package/src/state/branch-service.ts +3 -3
  186. package/src/state/company-service.ts +107 -0
  187. package/src/state/language-service.ts +12 -7
  188. package/src/state/layout-choice-service.ts +40 -0
  189. package/src/state/menu-service.ts +2 -2
  190. package/src/state/otp-service.ts +283 -0
  191. package/src/state/preference-sync.ts +11 -3
  192. package/src/state/signals.ts +36 -4
  193. package/src/theme/custom-themes.ts +236 -0
  194. package/src/theme/dark-themes.ts +80 -3
  195. package/src/theme/logo.ts +19 -4
  196. package/src/theme/org-themes.json +70 -0
  197. package/src/theme/theme-service.ts +70 -10
  198. package/src/types/field-wrapper.tsx +5 -2
  199. package/src/types/type.otp.tsx +11 -2
  200. package/src/utils/app-http.ts +205 -12
  201. package/src/utils/content-util.ts +49 -0
  202. package/src/utils/error-util.ts +64 -0
  203. package/src/utils/language-util.ts +7 -7
  204. package/src/utils/menu-util.ts +1 -1
  205. package/src/utils/signal-source.ts +15 -0
  206. package/src/utils/storage-keys.ts +6 -0
@@ -0,0 +1,98 @@
1
+ // browser-language.ts
2
+ // The languages the user's browser / operating system asks for, and the best match in a language list.
3
+ //
4
+ // navigator.languages = ["fr-CA", "fr", "en-US"] + list en-US, fr-FR, ar-SA -> "fr-FR"
5
+ //
6
+ // Order of the browser codes: navigator.languages, navigator.language, then the Intl locale (system setting).
7
+ // A code matches exactly (case does not matter), else by its base language ("fr-CA" or "fr" -> "fr-FR").
8
+
9
+ import type { LanguageOption } from "../interfaces/ui-config.ts";
10
+
11
+ const CODE_SEPARATOR = "-";
12
+
13
+ /** Adds a code once (codes like "fr_CA" become "fr-CA"). */
14
+ function addCode(codes: string[], code: string | undefined): void {
15
+ if (!code) {
16
+ return;
17
+ }
18
+ const normalizedCode = code.replace("_", CODE_SEPARATOR);
19
+ const isAdded = codes.includes(normalizedCode);
20
+ if (!isAdded) {
21
+ codes.push(normalizedCode);
22
+ }
23
+ }
24
+
25
+ /** The system locale from Intl ("" when it is not available). */
26
+ function readIntlLocale(): string {
27
+ if (typeof Intl === "undefined") {
28
+ return "";
29
+ }
30
+ const dateFormat = new Intl.DateTimeFormat();
31
+ const options = dateFormat.resolvedOptions();
32
+ return options.locale;
33
+ }
34
+
35
+ /** The language codes the browser / system prefers, best first. [] when there is no browser. */
36
+ export function readBrowserLanguageCodes(): string[] {
37
+ const codes: string[] = [];
38
+ if (typeof navigator === "undefined") {
39
+ return codes;
40
+ }
41
+ const preferredCodes = navigator.languages ?? [];
42
+ for (const code of preferredCodes) {
43
+ addCode(codes, code);
44
+ }
45
+ addCode(codes, navigator.language);
46
+ const intlLocale = readIntlLocale();
47
+ addCode(codes, intlLocale);
48
+ return codes;
49
+ }
50
+
51
+ /** The base language of a code: "fr-CA" -> "fr". */
52
+ function toBaseLanguage(code: string): string {
53
+ const parts = code.split(CODE_SEPARATOR);
54
+ const baseLanguage = parts[0] ?? "";
55
+ return baseLanguage.toLowerCase();
56
+ }
57
+
58
+ /** The list code that equals the code (any case). */
59
+ function findExactCode(code: string, languages: LanguageOption[]): string | undefined {
60
+ const lowerCode = code.toLowerCase();
61
+ for (const language of languages) {
62
+ const lowerListCode = language.code.toLowerCase();
63
+ if (lowerListCode === lowerCode) {
64
+ return language.code;
65
+ }
66
+ }
67
+ return undefined;
68
+ }
69
+
70
+ /** The first list code with the same base language ("fr" -> "fr-FR"). */
71
+ function findBaseLanguageCode(code: string, languages: LanguageOption[]): string | undefined {
72
+ const baseLanguage = toBaseLanguage(code);
73
+ for (const language of languages) {
74
+ const listBaseLanguage = toBaseLanguage(language.code);
75
+ if (listBaseLanguage === baseLanguage) {
76
+ return language.code;
77
+ }
78
+ }
79
+ return undefined;
80
+ }
81
+
82
+ /**
83
+ * The best list code for the browser codes: for each browser code (best first) an exact match, else the same base
84
+ * language. undefined when nothing matches.
85
+ */
86
+ export function matchLanguageCode(browserCodes: string[], languages: LanguageOption[]): string | undefined {
87
+ for (const browserCode of browserCodes) {
88
+ const exactCode = findExactCode(browserCode, languages);
89
+ if (exactCode) {
90
+ return exactCode;
91
+ }
92
+ const baseLanguageCode = findBaseLanguageCode(browserCode, languages);
93
+ if (baseLanguageCode) {
94
+ return baseLanguageCode;
95
+ }
96
+ }
97
+ return undefined;
98
+ }
@@ -45,6 +45,9 @@ export const DEFAULT_UI_MESSAGES: LocaleMessages = {
45
45
  sidebar: "Sidebar",
46
46
  megaMenu: "Mega menu",
47
47
  navigationMode: "Navigation",
48
+ layout: "Layout",
49
+ appLayout: "App layout",
50
+ asideLayout: "Aside layout",
48
51
  scrollToTop: "Scroll to top",
49
52
  branch: "Branch",
50
53
  openPreview: "Open preview",
@@ -60,6 +63,18 @@ export const DEFAULT_UI_MESSAGES: LocaleMessages = {
60
63
  uploadTypeError: "\"{{name}}\" is not an allowed file type. Please upload {{types}}.",
61
64
  uploadSizeError: "\"{{name}}\" ({{size}}) is larger than the allowed {{max}}.",
62
65
  uploadTotalError: "Total size {{size}} is larger than the allowed {{max}}.",
66
+ otpTitle: "Verification code",
67
+ otpText: "Please enter the OTP sent to your registered id to verify your identity.",
68
+ otpCode: "OTP",
69
+ otpNoCode: "Didn't receive the code?",
70
+ otpResend: "Resend code",
71
+ otpResendIn: "Resend in {{time}}",
72
+ otpVerify: "Verify",
73
+ otpSent: "The code was sent.",
74
+ otpSendFailed: "Could not send the code. Please try again.",
75
+ otpVerified: "Verified.",
76
+ otpInvalid: "The code is not valid. Please try again.",
77
+ otpSessionMissing: "Please send a new code first.",
63
78
  },
64
79
  };
65
80
 
@@ -0,0 +1,87 @@
1
+ // locale-groups.ts
2
+ // Locale files split by group: one folder per language, one file per group (the file name is the group).
3
+ //
4
+ // locales/en-US/app.json { "name": "My App" } -> t("app.name")
5
+ // locales/en-US/nav.json { "users": "Users" } -> t("nav.users")
6
+ // locales/en-US/root.json { "REQUIRED": "This field is required" } -> t("REQUIRED") (top-level keys)
7
+ //
8
+ // // config.ts (Vite: import.meta.glob is lazy, only the files of the language in use are downloaded)
9
+ // const localeFiles = import.meta.glob("./locales/*/*.json");
10
+ // loadLocale: loadLocaleGroups.bind(null, localeFiles)
11
+ //
12
+ // Several folders can be merged ({ ...sharedFiles, ...ownFiles }): the same group in two folders is merged,
13
+ // the later file wins per key. Each file is flat, so the "group.key" rule (one sublevel) holds by itself.
14
+
15
+ import type { LocaleMessages, LocaleModule } from "../interfaces/ui-config.ts";
16
+ import { unwrapLocaleModule } from "./locale-service.ts";
17
+
18
+ /** One lazy file loader, as import.meta.glob returns them. */
19
+ export type LocaleFileLoader = () => Promise<unknown>;
20
+
21
+ /** path -> loader, for example the result of import.meta.glob("./locales/*\/*.json"). */
22
+ export type LocaleGroupFiles = Record<string, LocaleFileLoader>;
23
+
24
+ /** The file whose keys stay at the top level (dff-util messages like REQUIRED, or "greeting"). */
25
+ export const ROOT_LOCALE_GROUP = "root";
26
+
27
+ const JSON_EXTENSION = ".json";
28
+
29
+ /** Language code and group of a file path: "./locales/en-US/nav.json" -> { languageCode: "en-US", group: "nav" }. */
30
+ export function readLocaleFilePath(path: string): { languageCode: string; group: string } | undefined {
31
+ const parts = path.split("/");
32
+ const fileName = parts[parts.length - 1] ?? "";
33
+ const languageCode = parts[parts.length - 2] ?? "";
34
+ const isJsonFile = fileName.endsWith(JSON_EXTENSION);
35
+ if (!isJsonFile || languageCode.length === 0) {
36
+ return undefined;
37
+ }
38
+ const groupLength = fileName.length - JSON_EXTENSION.length;
39
+ const group = fileName.slice(0, groupLength);
40
+ return { languageCode: languageCode, group: group };
41
+ }
42
+
43
+ /** Loads one group file and takes the messages out of the JSON module. */
44
+ async function loadGroupFile(loadFile: LocaleFileLoader): Promise<LocaleMessages> {
45
+ const fileModule = await loadFile();
46
+ return unwrapLocaleModule(fileModule as LocaleModule);
47
+ }
48
+
49
+ /** Adds one group file to the messages (the root file goes to the top level). */
50
+ function addGroupMessages(messages: LocaleMessages, group: string, groupMessages: LocaleMessages): void {
51
+ if (group === ROOT_LOCALE_GROUP) {
52
+ Object.assign(messages, groupMessages);
53
+ return;
54
+ }
55
+ const existingGroup = messages[group];
56
+ const isExistingGroup = typeof existingGroup === "object" && existingGroup !== null;
57
+ messages[group] = isExistingGroup ? { ...existingGroup, ...groupMessages } : groupMessages;
58
+ }
59
+
60
+ /**
61
+ * Loads all group files of one language (in parallel) and returns one messages object, ready for loadLocale.
62
+ * Throws when the language has no files, so the next language is tried (browser language -> en-US).
63
+ */
64
+ export async function loadLocaleGroups(files: LocaleGroupFiles, languageCode: string): Promise<LocaleMessages> {
65
+ const groups: string[] = [];
66
+ const loadings: Array<Promise<LocaleMessages>> = [];
67
+ const entries = Object.entries(files);
68
+ for (const [path, loadFile] of entries) {
69
+ const fileInfo = readLocaleFilePath(path);
70
+ if (fileInfo?.languageCode !== languageCode) {
71
+ continue;
72
+ }
73
+ groups.push(fileInfo.group);
74
+ const loading = loadGroupFile(loadFile);
75
+ loadings.push(loading);
76
+ }
77
+ if (groups.length === 0) {
78
+ throw new Error(`shared-lib-web: no locale files for ${languageCode}`);
79
+ }
80
+ const groupContents = await Promise.all(loadings);
81
+ const messages: LocaleMessages = {};
82
+ for (const [index, group] of groups.entries()) {
83
+ const groupMessages = groupContents[index] ?? {};
84
+ addGroupMessages(messages, group, groupMessages);
85
+ }
86
+ return messages;
87
+ }
@@ -5,6 +5,9 @@
5
5
  //
6
6
  // The loader is the language's own load() or config.loadLocale(code) (locales/{code}.json).
7
7
  // The languages are config.languages or the backend list (languagesSignal). Loaded files are cached.
8
+ //
9
+ // First visit (nothing saved): config.defaultLanguage, else the browser / system language (navigator.languages,
10
+ // matched to the list: "fr-CA" -> "fr-FR"), else "en-US".
8
11
 
9
12
  import type { LanguageOption, LocaleMessages, LocaleModule, UiConfig } from "../interfaces/ui-config.ts";
10
13
  import {
@@ -17,7 +20,11 @@ import {
17
20
  } from "../state/signals.ts";
18
21
  import { AppStorage } from "../utils/app-storage.ts";
19
22
  import { LANG } from "../utils/storage-keys.ts";
23
+ import { matchLanguageCode, readBrowserLanguageCodes } from "./browser-language.ts";
24
+ import { isSignalSource } from "../utils/signal-source.ts";
20
25
  import { findLanguageOption } from "./direction.ts";
26
+ import { waitForSignalLocale } from "./locale-signal.ts";
27
+ import { findDeepLocaleKeys } from "./translator.ts";
21
28
 
22
29
  const UI_CONFIG_MISSING = "shared-lib-web: config is missing. Wrap your app in <SharedWebUiProvider config={config}>.";
23
30
 
@@ -67,9 +74,21 @@ export function runLocaleLoader(languageCode: string): Promise<LocaleModule> | u
67
74
  if (!loadLocale) {
68
75
  return undefined;
69
76
  }
77
+ if (isSignalSource(loadLocale)) {
78
+ return waitForSignalLocale(loadLocale, languageCode);
79
+ }
70
80
  return loadLocale(languageCode);
71
81
  }
72
82
 
83
+ /** Locale files allow one sublevel ("group.key"); deeper groups are never shown, so say so once per file. */
84
+ function warnAboutDeepKeys(languageCode: string, messages: LocaleMessages): void {
85
+ const deepKeys = findDeepLocaleKeys(messages);
86
+ if (deepKeys.length > 0) {
87
+ const keyList = deepKeys.join(", ");
88
+ console.warn(`shared-lib-web: ${languageCode}.json is deeper than "group.key" (one sublevel); not used: ${keyList}`);
89
+ }
90
+ }
91
+
73
92
  /** Loads (or reads from cache) the messages of one language. undefined when it cannot be loaded. */
74
93
  export async function loadLocaleMessages(languageCode: string): Promise<LocaleMessages | undefined> {
75
94
  const cachedMessages = loadedMessagesCache.get(languageCode);
@@ -83,6 +102,7 @@ export async function loadLocaleMessages(languageCode: string): Promise<LocaleMe
83
102
  try {
84
103
  const localeModule = await loading;
85
104
  const messages = unwrapLocaleModule(localeModule);
105
+ warnAboutDeepKeys(languageCode, messages);
86
106
  loadedMessagesCache.set(languageCode, messages);
87
107
  return messages;
88
108
  } catch {
@@ -100,36 +120,87 @@ export function readIsLanguageChosen(): boolean {
100
120
  return isLanguageChosen;
101
121
  }
102
122
 
103
- /** Language used when the app sets none (config.defaultLanguage missing). */
123
+ /** Language used when nothing else is set (no defaultLanguage, no browser match). */
104
124
  export const DEFAULT_LANGUAGE = "en-US";
105
125
 
106
- /** config.defaultLanguage, or "en-US" when it is not set. */
107
- export function readDefaultLanguage(config: UiConfig | null | undefined): string {
126
+ /**
127
+ * The language for keys missing in the current language, and the last default:
128
+ * config.defaultLanguage, else "en-US".
129
+ */
130
+ export function readFallbackLanguage(config: UiConfig | null | undefined): string {
108
131
  return config?.defaultLanguage || DEFAULT_LANGUAGE;
109
132
  }
110
133
 
111
- /** Picks the language to start with: the saved one if it may be used, else the default. */
112
- export function readInitialLanguageCode(config: UiConfig): string {
113
- const storedCode = AppStorage.getText(LANG);
114
- if (storedCode) {
115
- const isStoredAvailable = isLanguageAvailable(storedCode);
116
- if (isStoredAvailable) {
117
- return storedCode;
118
- }
134
+ /** The browser / system language that is in the language list (undefined without a list or a match). */
135
+ export function readBrowserLanguage(): string | undefined {
136
+ const languages = languagesSignal.peek();
137
+ if (languages.length === 0) {
138
+ return undefined;
119
139
  }
120
- const defaultLanguage = readDefaultLanguage(config);
121
- const isDefaultAvailable = isLanguageAvailable(defaultLanguage);
122
- if (isDefaultAvailable) {
123
- return defaultLanguage;
140
+ const browserCodes = readBrowserLanguageCodes();
141
+ return matchLanguageCode(browserCodes, languages);
142
+ }
143
+
144
+ /**
145
+ * The default language: config.defaultLanguage, else the browser / system language (when it is in the list),
146
+ * else "en-US".
147
+ */
148
+ export function readDefaultLanguage(config: UiConfig | null | undefined): string {
149
+ if (config?.defaultLanguage) {
150
+ return config.defaultLanguage;
124
151
  }
152
+ const browserLanguage = readBrowserLanguage();
153
+ return browserLanguage ?? readFallbackLanguage(config);
154
+ }
155
+
156
+ /** Adds a code once. */
157
+ function addCandidate(candidates: string[], code: string | undefined): void {
158
+ if (code && !candidates.includes(code)) {
159
+ candidates.push(code);
160
+ }
161
+ }
162
+
163
+ /**
164
+ * The languages to try on start, in order: the saved one, config.defaultLanguage, the browser / system languages
165
+ * (matched to the list; without a list all of them, a missing locale file is skipped), the fallback, the first listed.
166
+ */
167
+ export function readStartLanguageCandidates(config: UiConfig): string[] {
168
+ const candidates: string[] = [];
169
+ const storedCode = AppStorage.getText(LANG);
170
+ addCandidate(candidates, storedCode);
171
+ addCandidate(candidates, config.defaultLanguage);
125
172
  const languages = languagesSignal.peek();
173
+ const browserCodes = readBrowserLanguageCodes();
174
+ if (languages.length > 0) {
175
+ const browserLanguage = matchLanguageCode(browserCodes, languages);
176
+ addCandidate(candidates, browserLanguage);
177
+ } else {
178
+ for (const browserCode of browserCodes) {
179
+ addCandidate(candidates, browserCode);
180
+ }
181
+ }
182
+ const fallbackLanguage = readFallbackLanguage(config);
183
+ addCandidate(candidates, fallbackLanguage);
126
184
  const firstLanguage = languages[0];
127
- return firstLanguage ? firstLanguage.code : defaultLanguage;
185
+ addCandidate(candidates, firstLanguage?.code);
186
+ return candidates;
187
+ }
188
+
189
+ /** Picks the language to start with: the first start candidate that may be used. */
190
+ export function readInitialLanguageCode(config: UiConfig): string {
191
+ const candidates = readStartLanguageCandidates(config);
192
+ for (const candidate of candidates) {
193
+ const isAvailable = isLanguageAvailable(candidate);
194
+ if (isAvailable) {
195
+ return candidate;
196
+ }
197
+ }
198
+ return readFallbackLanguage(config);
128
199
  }
129
200
 
130
201
  /** Loads the fallback language messages into fallbackTranslationSignal. */
131
202
  export async function loadFallbackMessages(config: UiConfig): Promise<void> {
132
- const fallbackCode = config.fallbackLanguage ?? readDefaultLanguage(config);
203
+ const fallbackCode = readFallbackLanguage(config);
133
204
  const fallbackMessages = await loadLocaleMessages(fallbackCode);
134
205
  if (fallbackMessages) {
135
206
  fallbackTranslationSignal.value = fallbackMessages;
@@ -168,20 +239,21 @@ export async function changeLanguage(languageCode: string): Promise<void> {
168
239
  await applyLanguage(languageCode, true);
169
240
  }
170
241
 
171
- /** Loads the saved (or default) language and the fallback language. Called once by TranslationProvider. */
242
+ /**
243
+ * Loads the start language and the fallback language. Called once by TranslationProvider.
244
+ * Tries readStartLanguageCandidates in order; a language whose file cannot be loaded is skipped.
245
+ */
172
246
  export async function initializeLanguage(): Promise<void> {
173
247
  const config = readActiveConfig();
174
248
  const storedCode = AppStorage.getText(LANG);
175
249
  isLanguageChosen = Boolean(storedCode);
176
250
  await loadFallbackMessages(config);
177
- const languageCode = readInitialLanguageCode(config);
178
- const isApplied = await applyLanguage(languageCode, false);
179
- if (isApplied) {
180
- return;
181
- }
182
- const defaultLanguage = readDefaultLanguage(config);
183
- const isDefaultApplied = await applyLanguage(defaultLanguage, false);
184
- if (!isDefaultApplied) {
185
- isTranslationReadySignal.value = true;
251
+ const candidates = readStartLanguageCandidates(config);
252
+ for (const candidate of candidates) {
253
+ const isApplied = await applyLanguage(candidate, false);
254
+ if (isApplied) {
255
+ return;
256
+ }
186
257
  }
258
+ isTranslationReadySignal.value = true;
187
259
  }
@@ -0,0 +1,173 @@
1
+ // locale-signal.ts
2
+ // config.loadLocale as a SIGNAL: a bundle of texts per language code, filled by the app.
3
+ //
4
+ // const localeSignal = signal<LocaleBundle | null>(null); // { "en-US": {...}, "fr-FR": {...} }
5
+ // (the app's own signal — not the library's localeSignal, which holds the current language code)
6
+ // loadLocale: localeSignal,
7
+ //
8
+ // The library asks for a language by adding its code to requestedLocalesSignal and waits until the bundle has it
9
+ // (null for a code = that language has no texts: the next language is tried). The app fills the bundle:
10
+ // fillLocaleBundle(localeSignal, loadLocaleGroups.bind(null, localeFiles)); // loads every requested code
11
+ // Without an answer within LOCALE_WAIT_MS the language counts as missing.
12
+
13
+ import { effect, signal } from "@preact/signals-react";
14
+ import type { LocaleBundle, LocaleCodeLoader, LocaleMessages, LocaleModule, ValueSignal } from "../interfaces/ui-config.ts";
15
+
16
+ /** How long the library waits for a requested language before it tries the next one. */
17
+ export const LOCALE_WAIT_MS = 15000;
18
+
19
+ /** The language codes the library needs texts for (in the order it asked). */
20
+ export const requestedLocalesSignal = signal<string[]>([]);
21
+
22
+ /** A promise and its resolve / reject, so a later bundle value can settle it. */
23
+ interface PendingLocale {
24
+ promise: Promise<LocaleMessages>;
25
+ resolve: (messages: LocaleMessages) => void;
26
+ reject: (reason: Error) => void;
27
+ }
28
+
29
+ /** A bundle signal the app writes. */
30
+ export interface WritableLocaleBundleSignal {
31
+ value: LocaleBundle | null;
32
+ peek(): LocaleBundle | null;
33
+ }
34
+
35
+ const pendingLocales = new Map<string, PendingLocale>();
36
+
37
+ let followedSource: ValueSignal<LocaleBundle | null> | undefined = undefined;
38
+ let stopFollowingSource: (() => void) | undefined = undefined;
39
+
40
+ /** Codes being loaded per bundle signal (fillLocaleBundle), so a code is loaded once. */
41
+ const loadingCodes = new WeakMap<WritableLocaleBundleSignal, Set<string>>();
42
+
43
+ /** Stores resolve / reject of a new promise on the pending entry. */
44
+ function captureResolvers(
45
+ pending: PendingLocale,
46
+ resolve: (messages: LocaleMessages) => void,
47
+ reject: (reason: Error) => void,
48
+ ): void {
49
+ pending.resolve = resolve;
50
+ pending.reject = reject;
51
+ }
52
+
53
+ /** A new pending entry with its promise. */
54
+ function createPendingLocale(): PendingLocale {
55
+ const pending = {} as PendingLocale;
56
+ const capture = captureResolvers.bind(null, pending);
57
+ pending.promise = new Promise<LocaleMessages>(capture);
58
+ return pending;
59
+ }
60
+
61
+ /** Settles every waiting language that the bundle now answers (texts, or null = missing). */
62
+ function settlePendingLocales(bundle: LocaleBundle | null): void {
63
+ if (!bundle) {
64
+ return;
65
+ }
66
+ for (const [code, pending] of pendingLocales) {
67
+ if (!(code in bundle)) {
68
+ continue;
69
+ }
70
+ pendingLocales.delete(code);
71
+ const messages = bundle[code];
72
+ if (messages) {
73
+ pending.resolve(messages);
74
+ } else {
75
+ const missingError = new Error(`shared-lib-web: no texts for ${code} in the loadLocale signal`);
76
+ pending.reject(missingError);
77
+ }
78
+ }
79
+ }
80
+
81
+ /** Follows the bundle signal (once per signal). */
82
+ function followBundleSource(source: ValueSignal<LocaleBundle | null>): void {
83
+ if (followedSource === source) {
84
+ return;
85
+ }
86
+ stopFollowingSource?.();
87
+ followedSource = source;
88
+ stopFollowingSource = source.subscribe(settlePendingLocales);
89
+ }
90
+
91
+ /** No answer in time: the language counts as missing. */
92
+ function rejectLateLocale(code: string): void {
93
+ const pending = pendingLocales.get(code);
94
+ if (!pending) {
95
+ return;
96
+ }
97
+ pendingLocales.delete(code);
98
+ const timeoutError = new Error(`shared-lib-web: the loadLocale signal did not answer ${code} in time`);
99
+ pending.reject(timeoutError);
100
+ }
101
+
102
+ /** Adds the code to requestedLocalesSignal (once). */
103
+ function requestLocale(code: string): void {
104
+ const requestedCodes = requestedLocalesSignal.peek();
105
+ if (!requestedCodes.includes(code)) {
106
+ requestedLocalesSignal.value = [...requestedCodes, code];
107
+ }
108
+ }
109
+
110
+ /** The texts of one language from a loadLocale signal: now when the bundle has them, else after the app adds them. */
111
+ export function waitForSignalLocale(source: ValueSignal<LocaleBundle | null>, code: string): Promise<LocaleModule> {
112
+ const bundle = source.peek();
113
+ const readyMessages = bundle?.[code];
114
+ if (readyMessages) {
115
+ return Promise.resolve(readyMessages);
116
+ }
117
+ if (bundle && code in bundle) {
118
+ const missingError = new Error(`shared-lib-web: no texts for ${code} in the loadLocale signal`);
119
+ return Promise.reject(missingError);
120
+ }
121
+ followBundleSource(source);
122
+ let pending = pendingLocales.get(code);
123
+ if (!pending) {
124
+ pending = createPendingLocale();
125
+ pendingLocales.set(code, pending);
126
+ const rejectLater = rejectLateLocale.bind(null, code);
127
+ setTimeout(rejectLater, LOCALE_WAIT_MS);
128
+ }
129
+ requestLocale(code);
130
+ return pending.promise;
131
+ }
132
+
133
+ /** Loads one requested code into the bundle (null when it fails: that language is missing). */
134
+ async function loadIntoBundle(target: WritableLocaleBundleSignal, loader: LocaleCodeLoader, code: string): Promise<void> {
135
+ let messages: LocaleMessages | null = null;
136
+ try {
137
+ const localeModule = await loader(code);
138
+ const hasDefault = typeof localeModule === "object" && localeModule !== null && "default" in localeModule;
139
+ messages = (hasDefault ? (localeModule as { default: LocaleMessages }).default : localeModule) as LocaleMessages;
140
+ } catch {
141
+ messages = null;
142
+ }
143
+ const currentBundle = target.peek() ?? {};
144
+ target.value = { ...currentBundle, [code]: messages };
145
+ }
146
+
147
+ /** Loads every requested code that the bundle does not have yet (a signals effect). */
148
+ function followRequestedLocales(target: WritableLocaleBundleSignal, loader: LocaleCodeLoader): void {
149
+ const requestedCodes = requestedLocalesSignal.value;
150
+ const bundle = target.peek() ?? {};
151
+ let codesInProgress = loadingCodes.get(target);
152
+ if (!codesInProgress) {
153
+ codesInProgress = new Set<string>();
154
+ loadingCodes.set(target, codesInProgress);
155
+ }
156
+ for (const code of requestedCodes) {
157
+ const isKnown = code in bundle || codesInProgress.has(code);
158
+ if (isKnown) {
159
+ continue;
160
+ }
161
+ codesInProgress.add(code);
162
+ void loadIntoBundle(target, loader, code);
163
+ }
164
+ }
165
+
166
+ /**
167
+ * Fills a loadLocale signal: every language the library asks for is loaded with your loader (for example
168
+ * loadLocaleGroups.bind(null, localeFiles)) and added to the bundle. Returns the stop function (for useEffect).
169
+ */
170
+ export function fillLocaleBundle(target: WritableLocaleBundleSignal, loader: LocaleCodeLoader): () => void {
171
+ const followRequests = followRequestedLocales.bind(null, target, loader);
172
+ return effect(followRequests);
173
+ }
@@ -4,6 +4,9 @@
4
4
  // t("nav.users") -> looks up { "nav": { "users": "..." } }
5
5
  // t("greeting", { name: "Asha" }) -> "Hello {{name}}" becomes "Hello Asha"
6
6
  //
7
+ // Locale files have at most ONE sublevel: "key" or "group.key" ({ "user": { "title": "..." } }).
8
+ // Deeper keys ("user.role.admin") are not looked up; use "role.admin" or "user.roleAdmin" instead.
9
+ //
7
10
  // Search order: current language -> fallback language -> package defaults -> the key itself.
8
11
 
9
12
  import { ConstValue } from "dff-util";
@@ -14,26 +17,49 @@ import { DEFAULT_CONST_MESSAGES, DEFAULT_UI_MESSAGES } from "./default-messages.
14
17
 
15
18
  const PLACEHOLDER_PATTERN = /\{\{\s*(\w+)\s*\}\}/g;
16
19
 
17
- /** Finds a text in a messages object by a dotted key. Returns undefined when not found. */
20
+ /** The deepest key: "group.key" (one sublevel). */
21
+ export const MAX_KEY_PARTS = 2;
22
+
23
+ /**
24
+ * Finds a text in a messages object by a key: "key" or "group.key" (one sublevel only).
25
+ * Returns undefined when not found or when the key is deeper ("a.b.c").
26
+ */
18
27
  export function lookupMessage(messages: LocaleMessages, key: string): string | undefined {
19
28
  const directValue = messages[key];
20
29
  if (typeof directValue === "string") {
21
30
  return directValue;
22
31
  }
23
32
  const keyParts = key.split(ConstValue.PERIOD);
24
- let currentValue: string | LocaleMessages | undefined = messages;
25
- for (const keyPart of keyParts) {
26
- const isGroup = typeof currentValue === "object" && currentValue !== null;
27
- if (!isGroup) {
28
- return undefined;
29
- }
30
- const group = currentValue as LocaleMessages;
31
- currentValue = group[keyPart];
33
+ if (keyParts.length !== MAX_KEY_PARTS) {
34
+ return undefined;
35
+ }
36
+ const groupName = keyParts[0] ?? ConstValue.EMPTY;
37
+ const itemName = keyParts[1] ?? ConstValue.EMPTY;
38
+ const group = messages[groupName];
39
+ const isGroup = typeof group === "object" && group !== null;
40
+ if (!isGroup) {
41
+ return undefined;
32
42
  }
33
- if (typeof currentValue === "string") {
34
- return currentValue;
43
+ const value = group[itemName];
44
+ return typeof value === "string" ? value : undefined;
45
+ }
46
+
47
+ /** The keys of a locale file that are deeper than "group.key" (they are never shown). [] when the file is fine. */
48
+ export function findDeepLocaleKeys(messages: LocaleMessages): string[] {
49
+ const deepKeys: string[] = [];
50
+ const groupEntries = Object.entries(messages);
51
+ for (const [groupName, group] of groupEntries) {
52
+ if (typeof group !== "object" || group === null) {
53
+ continue;
54
+ }
55
+ const itemEntries = Object.entries(group);
56
+ for (const [itemName, value] of itemEntries) {
57
+ if (typeof value === "object" && value !== null) {
58
+ deepKeys.push(`${groupName}.${itemName}.*`);
59
+ }
60
+ }
35
61
  }
36
- return undefined;
62
+ return deepKeys;
37
63
  }
38
64
 
39
65
  /** Replaces {{name}} placeholders with values from params. Unknown placeholders stay as they are. */