shared-lib-web 0.0.2 → 0.0.3

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 (186) hide show
  1. package/README.md +381 -127
  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/settings-menu.d.ts +4 -0
  13. package/dist/components/settings-menu.d.ts.map +1 -1
  14. package/dist/components/settings-menu.js +15 -2
  15. package/dist/components/settings-menu.js.map +1 -1
  16. package/dist/context/use-ui.d.ts.map +1 -1
  17. package/dist/context/use-ui.js +4 -3
  18. package/dist/context/use-ui.js.map +1 -1
  19. package/dist/i18n/browser-language.d.ts +9 -0
  20. package/dist/i18n/browser-language.d.ts.map +1 -0
  21. package/dist/i18n/browser-language.js +89 -0
  22. package/dist/i18n/browser-language.js.map +1 -0
  23. package/dist/i18n/default-messages.d.ts.map +1 -1
  24. package/dist/i18n/default-messages.js +3 -0
  25. package/dist/i18n/default-messages.js.map +1 -1
  26. package/dist/i18n/locale-groups.d.ts +18 -0
  27. package/dist/i18n/locale-groups.d.ts.map +1 -0
  28. package/dist/i18n/locale-groups.js +74 -0
  29. package/dist/i18n/locale-groups.js.map +1 -0
  30. package/dist/i18n/locale-service.d.ts +22 -4
  31. package/dist/i18n/locale-service.d.ts.map +1 -1
  32. package/dist/i18n/locale-service.js +95 -27
  33. package/dist/i18n/locale-service.js.map +1 -1
  34. package/dist/i18n/locale-signal.d.ts +18 -0
  35. package/dist/i18n/locale-signal.d.ts.map +1 -0
  36. package/dist/i18n/locale-signal.js +142 -0
  37. package/dist/i18n/locale-signal.js.map +1 -0
  38. package/dist/i18n/translator.d.ts +8 -1
  39. package/dist/i18n/translator.d.ts.map +1 -1
  40. package/dist/i18n/translator.js +36 -12
  41. package/dist/i18n/translator.js.map +1 -1
  42. package/dist/index.d.ts +21 -10
  43. package/dist/index.d.ts.map +1 -1
  44. package/dist/index.js +19 -8
  45. package/dist/index.js.map +1 -1
  46. package/dist/interfaces/app-types.d.ts +6 -0
  47. package/dist/interfaces/app-types.d.ts.map +1 -1
  48. package/dist/interfaces/ui-config.d.ts +162 -15
  49. package/dist/interfaces/ui-config.d.ts.map +1 -1
  50. package/dist/interfaces/ui-context.d.ts +1 -1
  51. package/dist/interfaces/ui-context.d.ts.map +1 -1
  52. package/dist/layouts/auth-layout.js +1 -1
  53. package/dist/layouts/auth-layout.js.map +1 -1
  54. package/dist/providers/provider-effects.d.ts +2 -2
  55. package/dist/providers/provider-effects.d.ts.map +1 -1
  56. package/dist/providers/provider-effects.js +4 -1
  57. package/dist/providers/provider-effects.js.map +1 -1
  58. package/dist/providers/register-config.d.ts.map +1 -1
  59. package/dist/providers/register-config.js +2 -0
  60. package/dist/providers/register-config.js.map +1 -1
  61. package/dist/providers/shared-web-ui-provider.d.ts +7 -19
  62. package/dist/providers/shared-web-ui-provider.d.ts.map +1 -1
  63. package/dist/providers/shared-web-ui-provider.js +21 -22
  64. package/dist/providers/shared-web-ui-provider.js.map +1 -1
  65. package/dist/query/query-param.d.ts +4 -1
  66. package/dist/query/query-param.d.ts.map +1 -1
  67. package/dist/query/query-param.js +6 -3
  68. package/dist/query/query-param.js.map +1 -1
  69. package/dist/state/api-loader.d.ts +19 -0
  70. package/dist/state/api-loader.d.ts.map +1 -0
  71. package/dist/state/api-loader.js +187 -0
  72. package/dist/state/api-loader.js.map +1 -0
  73. package/dist/state/auth-service.d.ts +4 -0
  74. package/dist/state/auth-service.d.ts.map +1 -1
  75. package/dist/state/auth-service.js +47 -3
  76. package/dist/state/auth-service.js.map +1 -1
  77. package/dist/state/branch-service.d.ts +1 -1
  78. package/dist/state/branch-service.js +3 -3
  79. package/dist/state/branch-service.js.map +1 -1
  80. package/dist/state/company-service.d.ts +16 -0
  81. package/dist/state/company-service.d.ts.map +1 -0
  82. package/dist/state/company-service.js +97 -0
  83. package/dist/state/company-service.js.map +1 -0
  84. package/dist/state/language-service.d.ts +5 -2
  85. package/dist/state/language-service.d.ts.map +1 -1
  86. package/dist/state/language-service.js +12 -7
  87. package/dist/state/language-service.js.map +1 -1
  88. package/dist/state/layout-choice-service.d.ts +10 -0
  89. package/dist/state/layout-choice-service.d.ts.map +1 -0
  90. package/dist/state/layout-choice-service.js +34 -0
  91. package/dist/state/layout-choice-service.js.map +1 -0
  92. package/dist/state/menu-service.d.ts +1 -1
  93. package/dist/state/menu-service.js +2 -2
  94. package/dist/state/menu-service.js.map +1 -1
  95. package/dist/state/preference-sync.d.ts +1 -1
  96. package/dist/state/preference-sync.d.ts.map +1 -1
  97. package/dist/state/preference-sync.js +11 -3
  98. package/dist/state/preference-sync.js.map +1 -1
  99. package/dist/state/signals.d.ts +9 -1
  100. package/dist/state/signals.d.ts.map +1 -1
  101. package/dist/state/signals.js +28 -4
  102. package/dist/state/signals.js.map +1 -1
  103. package/dist/theme/custom-themes.d.ts +28 -0
  104. package/dist/theme/custom-themes.d.ts.map +1 -0
  105. package/dist/theme/custom-themes.js +218 -0
  106. package/dist/theme/custom-themes.js.map +1 -0
  107. package/dist/theme/dark-themes.d.ts +9 -1
  108. package/dist/theme/dark-themes.d.ts.map +1 -1
  109. package/dist/theme/dark-themes.js +74 -2
  110. package/dist/theme/dark-themes.js.map +1 -1
  111. package/dist/theme/logo.d.ts +6 -3
  112. package/dist/theme/logo.d.ts.map +1 -1
  113. package/dist/theme/logo.js +17 -3
  114. package/dist/theme/logo.js.map +1 -1
  115. package/dist/theme/theme-service.d.ts +14 -3
  116. package/dist/theme/theme-service.d.ts.map +1 -1
  117. package/dist/theme/theme-service.js +64 -10
  118. package/dist/theme/theme-service.js.map +1 -1
  119. package/dist/utils/app-http.d.ts +29 -1
  120. package/dist/utils/app-http.d.ts.map +1 -1
  121. package/dist/utils/app-http.js +113 -11
  122. package/dist/utils/app-http.js.map +1 -1
  123. package/dist/utils/content-util.d.ts +6 -0
  124. package/dist/utils/content-util.d.ts.map +1 -0
  125. package/dist/utils/content-util.js +45 -0
  126. package/dist/utils/content-util.js.map +1 -0
  127. package/dist/utils/error-util.d.ts +3 -0
  128. package/dist/utils/error-util.d.ts.map +1 -0
  129. package/dist/utils/error-util.js +58 -0
  130. package/dist/utils/error-util.js.map +1 -0
  131. package/dist/utils/language-util.d.ts +3 -3
  132. package/dist/utils/language-util.d.ts.map +1 -1
  133. package/dist/utils/language-util.js +7 -7
  134. package/dist/utils/language-util.js.map +1 -1
  135. package/dist/utils/menu-util.js +1 -1
  136. package/dist/utils/menu-util.js.map +1 -1
  137. package/dist/utils/signal-source.d.ts +4 -0
  138. package/dist/utils/signal-source.d.ts.map +1 -0
  139. package/dist/utils/signal-source.js +13 -0
  140. package/dist/utils/signal-source.js.map +1 -0
  141. package/dist/utils/storage-keys.d.ts +5 -0
  142. package/dist/utils/storage-keys.d.ts.map +1 -1
  143. package/dist/utils/storage-keys.js +5 -0
  144. package/dist/utils/storage-keys.js.map +1 -1
  145. package/package.json +3 -3
  146. package/src/components/app-brand.tsx +9 -5
  147. package/src/components/coming-soon.tsx +3 -2
  148. package/src/components/language-switcher.tsx +26 -7
  149. package/src/components/settings-menu.tsx +28 -2
  150. package/src/context/use-ui.ts +4 -3
  151. package/src/i18n/browser-language.ts +98 -0
  152. package/src/i18n/default-messages.ts +3 -0
  153. package/src/i18n/locale-groups.ts +87 -0
  154. package/src/i18n/locale-service.ts +99 -27
  155. package/src/i18n/locale-signal.ts +173 -0
  156. package/src/i18n/translator.ts +38 -12
  157. package/src/index.ts +71 -3
  158. package/src/interfaces/app-types.ts +6 -0
  159. package/src/interfaces/ui-config.ts +168 -15
  160. package/src/interfaces/ui-context.ts +1 -1
  161. package/src/layouts/auth-layout.tsx +1 -1
  162. package/src/providers/provider-effects.ts +5 -2
  163. package/src/providers/register-config.ts +2 -0
  164. package/src/providers/shared-web-ui-provider.tsx +26 -43
  165. package/src/query/query-param.ts +6 -2
  166. package/src/state/api-loader.ts +205 -0
  167. package/src/state/auth-service.ts +58 -3
  168. package/src/state/branch-service.ts +3 -3
  169. package/src/state/company-service.ts +107 -0
  170. package/src/state/language-service.ts +12 -7
  171. package/src/state/layout-choice-service.ts +40 -0
  172. package/src/state/menu-service.ts +2 -2
  173. package/src/state/preference-sync.ts +11 -3
  174. package/src/state/signals.ts +36 -4
  175. package/src/theme/custom-themes.ts +236 -0
  176. package/src/theme/dark-themes.ts +80 -3
  177. package/src/theme/logo.ts +19 -4
  178. package/src/theme/org-themes.json +70 -0
  179. package/src/theme/theme-service.ts +70 -10
  180. package/src/utils/app-http.ts +125 -11
  181. package/src/utils/content-util.ts +49 -0
  182. package/src/utils/error-util.ts +64 -0
  183. package/src/utils/language-util.ts +7 -7
  184. package/src/utils/menu-util.ts +1 -1
  185. package/src/utils/signal-source.ts +15 -0
  186. package/src/utils/storage-keys.ts +6 -0
@@ -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. */
package/src/index.ts CHANGED
@@ -21,6 +21,18 @@ export type {
21
21
  NavItem,
22
22
  NavigationMode,
23
23
  ScreenPermissions,
24
+ ApiSource,
25
+ AppType,
26
+ ValueSignal,
27
+ CompanyDetails,
28
+ CompanySource,
29
+ CustomTheme,
30
+ CustomThemeEntry,
31
+ CustomThemeMap,
32
+ CustomThemes,
33
+ CustomThemesModule,
34
+ LocaleBundle,
35
+ ThemesLoader,
24
36
  Theme,
25
37
  PageMode,
26
38
  ToastPosition,
@@ -77,6 +89,9 @@ export {
77
89
  queryParamsSignal,
78
90
  progressSignal,
79
91
  themeSignal,
92
+ appTypeSignal,
93
+ customThemesSignal,
94
+ companyDetailsSignal,
80
95
  toastsSignal,
81
96
  translationSignal,
82
97
  uiConfigSignal,
@@ -113,19 +128,52 @@ export {
113
128
  changeLanguage,
114
129
  loadLocaleMessages,
115
130
  readDefaultLanguage,
131
+ readFallbackLanguage,
132
+ readBrowserLanguage,
133
+ readStartLanguageCandidates,
116
134
  unwrapLocaleModule,
117
135
  } from "./i18n/locale-service.ts";
118
- export { translate, interpolate, lookupMessage } from "./i18n/translator.ts";
136
+ export { MAX_KEY_PARTS, findDeepLocaleKeys, interpolate, lookupMessage, translate } from "./i18n/translator.ts";
119
137
  export { RTL_LANGUAGE_CODES, findLanguageOption, resolveDirection } from "./i18n/direction.ts";
138
+ export { matchLanguageCode, readBrowserLanguageCodes } from "./i18n/browser-language.ts";
139
+ export { isSignalSource } from "./utils/signal-source.ts";
140
+ export {
141
+ LOCALE_WAIT_MS,
142
+ fillLocaleBundle,
143
+ requestedLocalesSignal,
144
+ type WritableLocaleBundleSignal,
145
+ } from "./i18n/locale-signal.ts";
146
+ export {
147
+ ROOT_LOCALE_GROUP,
148
+ loadLocaleGroups,
149
+ readLocaleFilePath,
150
+ type LocaleFileLoader,
151
+ type LocaleGroupFiles,
152
+ } from "./i18n/locale-groups.ts";
120
153
  export { DEFAULT_UI_MESSAGES } from "./i18n/default-messages.ts";
121
154
  export {
122
155
  changeTheme,
123
156
  isDarkThemeName,
124
157
  readDarkThemeNames,
158
+ readThemeNames,
125
159
  splitThemesByMode,
126
160
  type ThemeGroups,
127
161
  } from "./theme/theme-service.ts";
128
- export { DEFAULT_DARK_THEMES } from "./theme/dark-themes.ts";
162
+ export { DAISYUI_THEMES, DEFAULT_DARK_THEMES } from "./theme/dark-themes.ts";
163
+ export {
164
+ buildCustomThemeCss,
165
+ isValidCustomTheme,
166
+ followConfigThemes,
167
+ loadConfigThemes,
168
+ mergeCustomThemes,
169
+ setCustomThemes,
170
+ toCustomThemeList,
171
+ unwrapThemesModule,
172
+ } from "./theme/custom-themes.ts";
173
+ export { isCompanyPending, readAppNameLabel, readCompanyDetails, setCompanyDetails } from "./state/company-service.ts";
174
+ export { readLogoUrl } from "./theme/logo.ts";
175
+ export { readContent } from "./utils/content-util.ts";
176
+ export { readErrorMessage } from "./utils/error-util.ts";
129
177
  export { ShowToast, clearToasts, removeToast } from "./state/toast-service.ts";
130
178
  export { ShowProgress } from "./state/progress-service.ts";
131
179
  export { closeSidebar, toggleSidebar } from "./state/sidebar-service.ts";
@@ -144,6 +192,8 @@ export {
144
192
  AUTH_USER_KEY,
145
193
  authUserSignal,
146
194
  endSession,
195
+ handleSessionEvent,
196
+ startSessionSync,
147
197
  redirectToLogoutUrl,
148
198
  isAuthenticatedSignal,
149
199
  readAccessToken,
@@ -156,9 +206,12 @@ export {
156
206
  export {
157
207
  API_BASE_URL_ENV,
158
208
  AppHttp,
209
+ isHttpUrl,
210
+ joinUrl,
159
211
  readJwtToken,
160
212
  toAbsoluteUrl,
161
213
  uploadToSignedUrl,
214
+ clearSharedGetCache,
162
215
  type HttpHeaders,
163
216
  type HttpParams,
164
217
  } from "./utils/app-http.ts";
@@ -206,6 +259,7 @@ export {
206
259
  REGEN_EXPIRES_AT,
207
260
  REMEMBER_ME,
208
261
  PREFERENCE_EVENT,
262
+ SESSION_EVENT,
209
263
  ACTIVE_SESSION_ID,
210
264
  LAYOUT_CHOICE,
211
265
  SCREEN_ACCESS,
@@ -231,6 +285,20 @@ export {
231
285
  } from "./utils/menu-util.ts";
232
286
  export { clearMenu, setMenu, setMenuLoading } from "./state/menu-service.ts";
233
287
  export { setLanguages } from "./state/language-service.ts";
288
+ export {
289
+ applySavedLayoutChoice,
290
+ changeLayoutChoice,
291
+ layoutChoiceSignal,
292
+ toLayoutChoice,
293
+ type LayoutChoice,
294
+ } from "./state/layout-choice-service.ts";
295
+ export {
296
+ callApiSource,
297
+ clearSessionData,
298
+ loadConfigCompany,
299
+ loadConfigLanguages,
300
+ loadSessionData,
301
+ } from "./state/api-loader.ts";
234
302
  export {
235
303
  readDefaultLanguageCode,
236
304
  readLanguageRows,
@@ -272,7 +340,7 @@ export { findNavTrail, isNavItemActive, isPathMatch } from "./layouts/navigation
272
340
 
273
341
  // ---- Components ----
274
342
  export { AppBrand, type AppBrandProps } from "./components/app-brand.tsx";
275
- export { LanguageSwitcher } from "./components/language-switcher.tsx";
343
+ export { LanguageSwitcher, type LanguageSwitcherProps } from "./components/language-switcher.tsx";
276
344
  export { ThemeSwitcher } from "./components/theme-switcher.tsx";
277
345
  export { ToastContainer } from "./components/toast-container.tsx";
278
346
  export { UserMenu, readInitials, type UserMenuItem, type UserMenuProps } from "./components/user-menu.tsx";
@@ -83,11 +83,15 @@ export interface LanguageRowType {
83
83
  code?: string;
84
84
  langCode?: string;
85
85
  languageCode?: string;
86
+ /** The code as sor /load/LANG sends it: { "key": "en-US", "label": "English", "locale": "English", "disabled": false }. */
87
+ key?: string;
86
88
  id?: string;
87
89
  /** Name shown in the switcher (usually in that language, "Français"). */
88
90
  name?: string;
89
91
  label?: string;
90
92
  nameLang?: Record<string, string>;
93
+ /** The language's own name ("Français", "हिन्दी"); shown when label and name are missing. */
94
+ locale?: string;
91
95
  /** Flag emoji or short text. */
92
96
  flag?: string;
93
97
  /** "ltr" or "rtl". When missing: rtl for ar, he, fa, ur. */
@@ -98,6 +102,8 @@ export interface LanguageRowType {
98
102
  default?: boolean;
99
103
  /** false hides the language. */
100
104
  active?: boolean;
105
+ /** true hides the language (sor /load/LANG). */
106
+ disabled?: boolean;
101
107
  /** Lower numbers come first. */
102
108
  priority?: number;
103
109
  }
@@ -13,6 +13,75 @@ export type Direction = LangDirType;
13
13
  /** A DaisyUI theme name, for example "light", "dark", "corporate", "dracula". */
14
14
  export type Theme = string;
15
15
 
16
+ /**
17
+ * A custom DaisyUI theme as plain data, so it can live in a JSON file or come from an API:
18
+ * { "name": "org-light", "isDark": false, "variables": { "color-primary": "oklch(55.8% 0.154 249.1)" } }
19
+ * The library turns it into [data-theme="org-light"] { color-scheme: light; --color-primary: ...; }.
20
+ * Several themes are an object keyed by theme name (see CustomThemeMap).
21
+ */
22
+ export interface CustomTheme {
23
+ /** data-theme name: lowercase letters, digits and "-", for example "org-light". */
24
+ name: Theme;
25
+ /** true for a dark theme (color-scheme: dark, dark logo, dark markdown editor). Default false. */
26
+ isDark?: boolean;
27
+ /**
28
+ * DaisyUI theme variables, with or without "--" (the same names as in a DaisyUI theme):
29
+ * color-base-100/200/300, color-base-content, color-primary, color-primary-content, color-secondary(-content),
30
+ * color-accent(-content), color-neutral(-content), color-info/success/warning/error(-content),
31
+ * radius-selector, radius-field, radius-box, size-selector, size-field, border, depth, noise.
32
+ */
33
+ variables: Record<string, string>;
34
+ }
35
+
36
+ /** Texts per language code for a loadLocale signal: { "en-US": {...}, "fr-FR": {...} }; null = no texts. */
37
+ export type LocaleBundle = Record<string, LocaleMessages | null>;
38
+
39
+ /** One entry of a CustomThemeMap: "name" may be left out (the key is the name). */
40
+ export type CustomThemeEntry = Omit<CustomTheme, "name"> & { name?: Theme };
41
+
42
+ /**
43
+ * The custom themes as an object keyed by theme name (the JSON format of a themes file / API reply):
44
+ * { "org-dark": { "isDark": true, "name": "org-dark", "variables": { ... } },
45
+ * "org-light": { "isDark": false, "name": "org-light", "variables": { ... } } }
46
+ */
47
+ export type CustomThemeMap = Record<Theme, CustomThemeEntry>;
48
+
49
+ /** Custom themes: the object keyed by theme name (CustomThemeMap), or a plain list. */
50
+ export type CustomThemes = CustomThemeMap | CustomTheme[];
51
+
52
+ /** What a themes loader may return: the themes (object or list), or a JSON module with a default export. */
53
+ export type CustomThemesModule = CustomThemes | { default: CustomThemes };
54
+
55
+ /**
56
+ * Loads the custom themes lazily (like loadLocale), from a JSON file or an API:
57
+ * function loadThemes(): Promise<CustomThemesModule> { return import("./theme/org-themes.json"); }
58
+ * async function loadThemes(): Promise<CustomThemesModule> { const reply = await fetch("/themes.json"); return reply.json(); }
59
+ */
60
+ export type ThemesLoader = () => Promise<CustomThemesModule>;
61
+
62
+ /**
63
+ * Company / brand details from the backend (config.loadCompanyDetails or setCompanyDetails):
64
+ * { "appName": "YourAppName", "companyName": "YourBrandName",
65
+ * "faviconUrl": "https://www.w3.org/favicon.ico", "logoUrl": "https://www.w3.org/Icons/w3c_home.png",
66
+ * "logoDarkUrl": "https://www.w3.org/Icons/w3c_home.png" }
67
+ * Every field is optional; a missing field keeps the config value (appName, logoUrl / logoDarkUrl).
68
+ */
69
+ export interface CompanyDetails {
70
+ /** App label in the header, sidebar and login, and the browser tab title. Wins over config.appName. */
71
+ appName?: string;
72
+ /** Company / brand name: alt text of the logo; read it with companyDetailsSignal (for example in a footer). */
73
+ companyName?: string;
74
+ /** Browser tab icon: written to <link rel="icon">. */
75
+ faviconUrl?: string;
76
+ /** Logo image URL (light themes; also dark themes without logoDarkUrl). Wins over config.logoUrl / config.logoDarkUrl. */
77
+ logoUrl?: string;
78
+ /** Logo image URL on dark themes. Default: logoUrl. Wins over config.logoDarkUrl. */
79
+ logoDarkUrl?: string;
80
+ }
81
+
82
+ /** What a company details reply may be: the details, or { data: details }; null = not here yet. */
83
+ export type CompanySource = CompanyDetails | { data: CompanyDetails } | null;
84
+
16
85
  /**
17
86
  * Translations for one language.
18
87
  * Values are text or nested groups: { "nav": { "home": "Home" } } is read with t("nav.home").
@@ -95,6 +164,11 @@ export interface LayoutConfig {
95
164
  isSidebarCollapsible?: boolean;
96
165
  /** "inline": language and theme switchers in the header. "menu": one settings button that opens them. Default "inline". */
97
166
  headerSettings?: "inline" | "menu";
167
+ /**
168
+ * Show the layout choice (App layout / Aside layout) in the settings dialog — for apps that render AppLayout or
169
+ * AsideLayout from layoutChoiceSignal (a shell). Saved as LAYOUT_CHOICE. Default false.
170
+ */
171
+ showLayoutChoice?: boolean;
98
172
  /** Where toasts appear. Default "top-end". */
99
173
  toastPosition?: ToastPosition;
100
174
  /** Show a "scroll to top" button on long pages. Default true. */
@@ -103,12 +177,40 @@ export interface LayoutConfig {
103
177
  pageParam?: string;
104
178
  /**
105
179
  * Where the current page lives in the address:
106
- * "query" (default) http://host/?page=profiles
107
- * "path" http://host/profiles (the server must answer every path with index.html)
180
+ * "query" http://host/?page=profiles (default for type "spa")
181
+ * "path" http://host/profiles (default for type "shell"; the server must answer every path
182
+ * with index.html)
108
183
  */
109
184
  pageMode?: PageMode;
110
185
  }
111
186
 
187
+ /**
188
+ * What the app is, passed as <SharedWebUiProvider type="...">:
189
+ * "spa" a normal single app (default): layouts, menu, login, ?page=... pages
190
+ * "shell" the root app that hosts microfrontends: like "spa", but pages are paths by default (/settings)
191
+ * "mfe" a microfrontend inside a shell: page layouts only. The shell owns the menu, branches, logos and app name,
192
+ * so loadMenuNavigation / loadBranches are not called and appName, logoUrl, logoDarkUrl, homePath and
193
+ * branchLabel are not used.
194
+ */
195
+ export type AppType = "spa" | "shell" | "mfe";
196
+
197
+ /** Anything with a reactive value: a @preact/signals signal or computed (read only). */
198
+ export interface ValueSignal<TValue = unknown> {
199
+ readonly value: TValue;
200
+ peek(): TValue;
201
+ subscribe(listener: (value: TValue) => void): () => void;
202
+ }
203
+
204
+ /**
205
+ * A backend source of the config, one of:
206
+ * - your function that returns the reply (like loadThemes / loadLocale)
207
+ * - a URL / path (sent with AppHttp.Get; a path gets the base URL, see AppHttp)
208
+ * - a signal you fill yourself: null = not here yet (menu: skeleton, branches: no switcher), then the reply;
209
+ * every new value is applied at once (the provider does not call anything for a signal)
210
+ * Replies may be { data: [...], meta } or the list.
211
+ */
212
+ export type ApiSource = string | (() => Promise<unknown>) | ValueSignal<unknown>;
213
+
112
214
  /** "query" = ?page=profiles, "path" = /profiles. */
113
215
  export type PageMode = "query" | "path";
114
216
 
@@ -125,7 +227,7 @@ export interface HttpConfig {
125
227
  tokenKey?: string;
126
228
  /** Extra headers sent with every request. */
127
229
  headers?: Record<string, string>;
128
- /** URL of the options loader used by AppHttp.Load(id) — the id is added: `${loadUrl}/${id}`. Default: base URL + "/load". */
230
+ /** URL (or path, added to the base URL) of the options loader used by AppHttp.Load(id) — the id is added: `${loadUrl}/${id}`. Default: "/load". */
129
231
  loadUrl?: string;
130
232
  /** Show the top progress bar during requests. Default true. */
131
233
  showProgress?: boolean;
@@ -139,6 +241,30 @@ export interface UiConfig {
139
241
  * - window.env names: REACT_APP_ORG_API_BASE_URL (AppStorage.envData("API_BASE_URL"))
140
242
  */
141
243
  appNameKey: string;
244
+ /**
245
+ * Loads the supported languages (backend list): called once when the provider mounts, like loadThemes.
246
+ * On an error the default language stays. By hand: setLanguages(reply).
247
+ */
248
+ loadSupportLanguages?: ApiSource;
249
+ /**
250
+ * Loads the branches of the signed-in user: called after sign in (and on start when a session is restored),
251
+ * BEFORE loadMenuNavigation, so the menu request already sends x-branch-id. Removed on sign out.
252
+ * Not called for type "mfe". By hand: setBranches(reply).
253
+ */
254
+ loadBranches?: ApiSource;
255
+ /**
256
+ * Loads the menu of the signed-in user: called after sign in (and on start when a session is restored); the menu
257
+ * shows a skeleton until it answers, an error shows an empty menu. Removed on sign out. Not called for type "mfe".
258
+ * Without it the menu is config.navigation. By hand: setMenuLoading() -> setMenu(reply).
259
+ */
260
+ loadMenuNavigation?: ApiSource;
261
+ /**
262
+ * Loads the company details ({ appName, companyName, faviconUrl, logoUrl, logoDarkUrl }): called once when the provider mounts,
263
+ * like loadSupportLanguages. Its values win over appName / logoUrl / logoDarkUrl; faviconUrl sets the tab icon.
264
+ * Type "mfe": usually not set (the shell owns the brand); an MFE that shows the brand (an auth MFE) may set it.
265
+ * By hand: setCompanyDetails(reply).
266
+ */
267
+ loadCompanyDetails?: ApiSource;
142
268
  /** Label shown in the header, sidebar and login: t(appName), so plain text or a translation key. Default: appNameKey. */
143
269
  appName?: string;
144
270
  /** Optional logo image URL (light themes). */
@@ -147,24 +273,51 @@ export interface UiConfig {
147
273
  logoDarkUrl?: string;
148
274
  /**
149
275
  * Static language list. Not needed when the languages come from the backend:
150
- * pass them with <SharedWebUiProvider lang={langResponse}> or setLanguages(langResponse).
276
+ * pass them with config.loadSupportLanguages or setLanguages(langResponse).
151
277
  */
152
278
  languages?: LanguageOption[];
153
- /** Loads locales/{code}.json for any code ("en-US" -> en-US.json). Needed for backend languages. */
154
- loadLocale?: LocaleCodeLoader;
155
- /** Language code used on the first visit and before the backend list arrives. Optional, default "en-US". */
279
+ /**
280
+ * The texts of a language: a function loadLocale(code) (lazy JSON / API), or a SIGNAL with a LocaleBundle
281
+ * ({ "en-US": {...} }) that the app fills — the library adds the codes it needs to requestedLocalesSignal and
282
+ * waits; fillLocaleBundle(signal, loader) does the filling.
283
+ */
284
+ loadLocale?: LocaleCodeLoader | ValueSignal<LocaleBundle | null>;
285
+ /**
286
+ * Language code used on the first visit (nothing saved; a backend isDefault language still wins).
287
+ * Optional: without it the browser / system language (navigator.languages matched to the list,
288
+ * "fr-CA" -> "fr-FR"), else "en-US". Keys missing in a language are shown in defaultLanguage (else "en-US").
289
+ */
156
290
  defaultLanguage?: string;
157
- /** Language used when a key is missing in the current language. Default: defaultLanguage ("en-US"). */
158
- fallbackLanguage?: string;
159
- /** DaisyUI themes offered in the theme switcher. They must also be enabled in your CSS @plugin "daisyui". */
160
- themes: Theme[];
161
- /** Theme used on the first visit. */
162
- defaultTheme: Theme;
163
- /** Which of the themes are dark (used for dark logos and the markdown editor). Default: DaisyUI dark themes. */
291
+ /**
292
+ * DaisyUI themes offered in the theme switcher. Optional, default: all 35 DaisyUI themes
293
+ * (enable them in your CSS: @plugin "daisyui" { themes: all; }). The customThemes are always listed first.
294
+ */
295
+ themes?: Theme[];
296
+ /**
297
+ * Your own themes as data (for example imported from a JSON file), an object keyed by theme name
298
+ * ({ "org-light": {...}, "org-dark": {...} }) or a list; no CSS file needed. Themes that arrive later
299
+ * (fetched JSON) go through setCustomThemes(json).
300
+ */
301
+ customThemes?: CustomThemes;
302
+ /**
303
+ * Custom themes loaded when the provider mounts (JSON file or API), like loadLocale — or a SIGNAL with the themes
304
+ * (null = not here yet; every new value replaces them). They are added to customThemes (same name: the loaded one
305
+ * wins). A saved custom theme stays on screen while they load.
306
+ */
307
+ loadThemes?: ThemesLoader | ValueSignal<CustomThemesModule | null>;
308
+ /**
309
+ * Theme used on the first visit (nothing saved yet). Optional: without it the browser preference decides,
310
+ * "dark" when it prefers a dark colour scheme, otherwise "light".
311
+ */
312
+ defaultTheme?: Theme;
313
+ /**
314
+ * Which of the themes are dark (used for dark logos and the markdown editor). Default: the DaisyUI dark themes.
315
+ * Custom themes with isDark: true are always added.
316
+ */
164
317
  darkThemes?: Theme[];
165
318
  /**
166
319
  * Static navigation items. Optional when the menu comes from the backend:
167
- * pass it with <SharedWebUiProvider nav={menuResponse}> or setMenu(menuResponse).
320
+ * pass it with config.loadMenuNavigation or setMenu(menuResponse).
168
321
  */
169
322
  navigation?: NavItem[];
170
323
  /** How backend menus are converted (root group flattening). */
@@ -23,7 +23,7 @@ export interface UiContextValue {
23
23
  isReady: boolean;
24
24
  /** Languages from the config. */
25
25
  languages: LanguageOption[];
26
- /** Themes from the config. */
26
+ /** Themes of the switcher: the custom themes first, then config.themes (default: all DaisyUI themes). */
27
27
  themes: Theme[];
28
28
  /** themes without the dark ones (config order). */
29
29
  lightThemes: Theme[];
@@ -25,7 +25,7 @@ export function AuthLayout(props: AuthLayoutProps) {
25
25
  return (
26
26
  <div className="flex min-h-screen flex-col bg-base-200">
27
27
  <header className="flex justify-end gap-1 p-3">
28
- <LanguageSwitcher />
28
+ <LanguageSwitcher isFullName />
29
29
  <ThemeSwitcher />
30
30
  </header>
31
31
  <main className="flex flex-1 items-center justify-center p-4">