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
package/README.md CHANGED
@@ -14,11 +14,10 @@ single parts, or skip `shared-lib-web/layout` completely and write the whole lay
14
14
 
15
15
  An app keeps **only**:
16
16
 
17
- 1. `config.ts` – app name, default language + locale loader, themes, logos, layout and http
18
- (no menu, no language list)
19
- 2. two backend inputs passed to the provider, `null` first and the reply later:
20
- `nav` (the menu) and `lang` (the languages)
21
- 3. `locales/{code}.json` – its texts (`en-US.json`, `ar-SA.json` …)
17
+ 1. `config.ts` – app name, logos, layout, http and the loaders: `loadLocale`, `loadThemes`, `loadSupportLanguages`,
18
+ `loadBranches`, `loadMenuNavigation` (the provider calls them itself)
19
+ 2. `<SharedWebUiProvider type="spa" | "shell" | "mfe" config={config}>
20
+ 3. `locales/<code>/<group>.json` – its texts, one folder per language and one file per group (`en-US/nav.json` …)
22
21
  4. its pages / modules
23
22
 
24
23
  Everything else lives in the library: components and (optionally) layouts, header, sidebar (with icon rail),
@@ -50,44 +49,144 @@ npm install @uiw/react-md-editor
50
49
  @import "tailwindcss";
51
50
  @import "shared-lib-web/styles.css"; /* lets Tailwind find the classes used inside the library */
52
51
  @plugin "daisyui" {
53
- themes: light --default, dark --prefersdark, corporate, dracula;
52
+ themes: all; /* all 35 DaisyUI themes; or list the ones you need */
54
53
  }
55
54
  ```
56
55
 
57
- Every theme in `config.themes` must also be enabled in `@plugin "daisyui"` (or defined as a custom theme), and the
58
- dark ones listed in `config.darkThemes` (dark logo, dark markdown editor). Use `themes: all` or list the ones you need.
56
+ `config.themes` is optional: without it the theme switcher offers all 35 DaisyUI themes (enable them with
57
+ `themes: all`, or list the ones you need and pass the same names in `config.themes`). The dark ones (dark logo,
58
+ dark markdown editor) default to the DaisyUI dark themes; `config.darkThemes` replaces that list.
59
59
 
60
- Custom themes use DaisyUI's theme plugin, one file per theme in a `theme/` folder (the example has
61
- `example/src/theme/org-light.css` and `org-dark.css`, and the theme names in `example/src/theme/themes.ts`):
60
+ ### Custom themes as JSON (no CSS file, no rebuild)
62
61
 
63
- ```css
64
- /* src/index.css */
65
- @import "tailwindcss";
66
- @import "./theme/org-light.css";
67
- @import "./theme/org-dark.css";
62
+ Your own themes are plain data: an **object keyed by theme name**, each with `isDark`, `name` and the DaisyUI theme
63
+ variables (`name` may be left out — the key is the name; a plain list `[{ name, ... }]` still works). Pass them with
64
+ `config.loadThemes` (or `config.customThemes`); they are listed first in the switcher, and `isDark: true` adds them to the dark themes.
65
+ The library writes one `<style>` with `[data-theme="org-dark"] { color-scheme: dark; --color-primary: …; }`, which
66
+ DaisyUI's components read like a built-in theme.
67
+
68
+ ```json
69
+ // src/theme/org-themes.json
70
+ {
71
+ "org-dark": {
72
+ "isDark": true,
73
+ "name": "org-dark",
74
+ "variables": {
75
+ "border": "1px",
76
+ "color-accent": "oklch(70.4% 0.04 256.8)",
77
+ "color-accent-content": "oklch(12.9% 0.042 264.7)",
78
+ "color-base-100": "oklch(25.5% 0.04 264.5)",
79
+ "color-base-200": "oklch(20.8% 0.042 265.8)",
80
+ "color-base-300": "oklch(32% 0.04 262)",
81
+ "color-base-content": "oklch(92.9% 0.013 255.5)",
82
+ "color-error": "oklch(70.4% 0.191 22.2)",
83
+ "color-error-content": "oklch(25.8% 0.092 26)",
84
+ "color-info": "oklch(78.9% 0.154 211.5)",
85
+ "color-info-content": "oklch(30.2% 0.056 229.7)",
86
+ "color-neutral": "oklch(37.2% 0.044 257.3)",
87
+ "color-neutral-content": "oklch(96.8% 0.007 247.9)",
88
+ "color-primary": "oklch(74.6% 0.16 232.7)",
89
+ "color-primary-content": "oklch(29.3% 0.066 243.2)",
90
+ "color-secondary": "oklch(82.8% 0.189 84.4)",
91
+ "color-secondary-content": "oklch(27.9% 0.077 45.6)",
92
+ "color-success": "oklch(79.2% 0.209 151.7)",
93
+ "color-success-content": "oklch(26.6% 0.065 152.9)",
94
+ "color-warning": "oklch(75% 0.183 55.9)",
95
+ "color-warning-content": "oklch(26.6% 0.079 36.3)",
96
+ "depth": "1",
97
+ "noise": "0",
98
+ "radius-box": "0.75rem",
99
+ "radius-field": "0.5rem",
100
+ "radius-selector": "1rem",
101
+ "size-field": "0.25rem",
102
+ "size-selector": "0.25rem"
103
+ }
104
+ },
105
+ "org-light": {
106
+ "isDark": false,
107
+ "name": "org-light",
108
+ "variables": {
109
+ "border": "1px",
110
+ "color-accent": "oklch(55.4% 0.046 257.4)",
111
+ "color-accent-content": "oklch(98.4% 0.003 247.9)",
112
+ "color-base-100": "oklch(100% 0 0)",
113
+ "color-base-200": "oklch(96.8% 0.007 247.9)",
114
+ "color-base-300": "oklch(92.9% 0.013 255.5)",
115
+ "color-base-content": "oklch(20.8% 0.042 265.8)",
116
+ "color-error": "oklch(55% 0.23 27.3)",
117
+ "color-error-content": "oklch(97.1% 0.013 17.4)",
118
+ "color-info": "oklch(71.5% 0.143 215.2)",
119
+ "color-info-content": "oklch(30.2% 0.056 229.7)",
120
+ "color-neutral": "oklch(27.9% 0.041 260)",
121
+ "color-neutral-content": "oklch(98.4% 0.003 247.9)",
122
+ "color-primary": "oklch(55.8% 0.154 249.1)",
123
+ "color-primary-content": "oklch(98.5% 0.01 240)",
124
+ "color-secondary": "oklch(76.9% 0.188 70.1)",
125
+ "color-secondary-content": "oklch(27.9% 0.077 45.6)",
126
+ "color-success": "oklch(52.7% 0.154 150.1)",
127
+ "color-success-content": "oklch(98.2% 0.018 155.8)",
128
+ "color-warning": "oklch(75% 0.183 55.9)",
129
+ "color-warning-content": "oklch(26.6% 0.079 36.3)",
130
+ "depth": "1",
131
+ "noise": "0",
132
+ "radius-box": "0.75rem",
133
+ "radius-field": "0.5rem",
134
+ "radius-selector": "1rem",
135
+ "size-field": "0.25rem",
136
+ "size-selector": "0.25rem"
137
+ }
138
+ }
139
+ }
68
140
  ```
69
141
 
70
- ```css
71
- /* src/theme/org-dark.css */
72
- @plugin "daisyui/theme" {
73
- name: "org-dark";
74
- default: false;
75
- color-scheme: dark;
76
- --color-base-100: oklch(22% 0.03 264);
77
- --color-base-content: oklch(92% 0.015 264);
78
- --color-primary: oklch(70% 0.16 277);
79
- /* ... all --color-*, --radius-*, --size-*, --border, --depth, --noise variables */
142
+ Load them lazily with `loadThemes`, the same way as `loadLocale` (its own chunk, loaded when the provider mounts):
143
+
144
+ ```ts
145
+ // config.ts
146
+ import type { CustomThemesModule, UiConfig } from "shared-lib-web";
147
+
148
+ function loadThemes(): Promise<CustomThemesModule> {
149
+ return import("./theme/org-themes.json");
80
150
  }
151
+
152
+ export const config: UiConfig = {
153
+ appNameKey: "ORG",
154
+ loadThemes: loadThemes, // + all 35 DaisyUI themes (themes is optional)
155
+ };
81
156
  ```
82
157
 
158
+ `loadThemes` can also read from your API or a file deployed next to the app (change the themes without a build):
159
+
160
+ ```ts
161
+ async function loadThemes(): Promise<CustomThemesModule> {
162
+ const response = await fetch("/themes.json");
163
+ return response.json();
164
+ }
165
+ ```
166
+
167
+ While they load, a saved custom theme stays on screen (no flash of the default theme); when the load fails or the
168
+ saved theme is not in the result, the default theme is used. Themes you already have in code can go straight into
169
+ `customThemes: orgThemes` (no loading; the object keyed by name, or a list); both together are merged, and a loaded theme replaces one with the same name.
170
+
171
+ The variable names are the DaisyUI ones, with or without `--`: `color-base-100/200/300`, `color-base-content`,
172
+ `color-primary`, `color-primary-content`, `color-secondary`, `color-accent`, `color-neutral`, `color-info`,
173
+ `color-success`, `color-warning`, `color-error` (each with `-content`), `radius-selector`, `radius-field`,
174
+ `radius-box`, `size-selector`, `size-field`, `border`, `depth`, `noise`. Theme names may use lowercase letters,
175
+ digits and `-`; values with `; { } < > " \` are skipped (safe for JSON from a server).
176
+
177
+ **Or a signal:** `loadThemes: themesSignal` (`signal<CustomThemesModule | null>(null)`). `null` = not here yet (a
178
+ saved custom theme stays on screen); every new value replaces the loaded themes:
179
+
83
180
  ```ts
84
- // src/theme/themes.ts → config.ts: themes: THEMES, darkThemes: DARK_THEMES
85
- export const THEMES: Theme[] = ["org-light", "org-dark", "light", "dark", /* ... */];
86
- export const DARK_THEMES: Theme[] = ["org-dark", "dark", /* ... */];
181
+ const themeModule = await import("./theme/org-themes.json");
182
+ themesSignal.value = themeModule;
87
183
  ```
88
184
 
185
+ Any time later (for example after the user signs in) `setCustomThemes(themes)` replaces the custom themes (the object
186
+ keyed by name or a list). `toCustomThemeList(themes)` turns the object into a list (`CustomTheme[]`, key order).
187
+
89
188
  The theme dropdown, the ⚙ settings dialog and the example Settings page show **Light themes** and **Dark themes**
90
- as two groups (split by `config.darkThemes`). In your own UI: `const { lightThemes, darkThemes } = useUi();`
189
+ as two groups (split by the dark themes). In your own UI: `const { lightThemes, darkThemes } = useUi();`
91
190
  or `splitThemesByMode(themes)`, `isDarkThemeName(theme)`. Texts: `ui.lightThemes`, `ui.darkThemes`.
92
191
 
93
192
  ## App bundler (Vite example)
@@ -107,39 +206,43 @@ export default defineConfig({
107
206
  ## 1. config.ts
108
207
 
109
208
  ```ts
110
- import { readEnvData, toAbsoluteUrl, type LocaleModule, type UiConfig } from "shared-lib-web";
209
+ import { loadLocaleGroups, readEnvData, toAbsoluteUrl, type CustomThemesModule, type UiConfig } from "shared-lib-web";
111
210
 
112
211
  const APP_NAME_KEY = "ORG";
212
+ const APP_API_KEY = APP_NAME_KEY.toLowerCase(); // "org" -> /org-api, /org-sor ...
113
213
 
114
214
  // window.env.REACT_APP_ORG_API_BASE_URL (env.js), else the default
115
215
  const envBaseUrl = readEnvData(APP_NAME_KEY, "API_BASE_URL");
116
216
  const API_BASE_URL = toAbsoluteUrl(envBaseUrl ?? "https://api.example.com/api");
117
217
 
118
- // Service URLs are PROJECT level (not part of AppHttp)
218
+ // Service paths are PROJECT level (not part of AppHttp). AppHttp adds the base URL to a path:
219
+ // AppHttp.Get(`${MsUrl.main}/menu-access`) -> https://api.example.com/api/org-api/menu-access
119
220
  export const MsUrl = {
120
- api: `${API_BASE_URL}/xxx-api`,
121
- main: `${API_BASE_URL}/xxx-api`,
122
- sor: `${API_BASE_URL}/xxx-sor`,
123
- events: `${API_BASE_URL}/xxx-events`,
124
- tms: `${API_BASE_URL}/xxx-tms`,
125
- utils: `${API_BASE_URL}/xxx-util`,
221
+ api: `/${APP_API_KEY}-api`,
222
+ main: `/${APP_API_KEY}-api`,
223
+ sor: `/${APP_API_KEY}-sor`,
224
+ events: `/${APP_API_KEY}-events`,
225
+ tms: `/${APP_API_KEY}-tms`,
226
+ utils: `/${APP_API_KEY}-util`,
126
227
  };
127
228
 
128
- /** locales/{code}.json, loaded only when that language is used: "en-US" -> locales/en-US.json */
129
- function loadLocale(languageCode: string): Promise<LocaleModule> {
130
- return import(`./locales/${languageCode}.json`);
229
+ /** locales/<code>/<group>.json — lazy: only the files of the language in use are downloaded (see section 2) */
230
+ const localeFiles = import.meta.glob("./locales/*/*.json");
231
+
232
+ /** theme/org-themes.json, loaded lazily like the locale files (see "Custom themes as JSON") */
233
+ function loadThemes(): Promise<CustomThemesModule> {
234
+ return import("./theme/org-themes.json");
131
235
  }
132
236
 
133
237
  export const config: UiConfig = {
134
238
  appNameKey: APP_NAME_KEY, // key: storage ORG-TOKEN, env REACT_APP_ORG_API_BASE_URL
135
- appName: "app.name", // label: t("app.name") (default: appNameKey)
136
- logoUrl: "/logo-light.svg",
137
- logoDarkUrl: "/logo-dark.svg",
138
- defaultLanguage: "en-US", // shown before the backend list arrives
139
- loadLocale: loadLocale,
140
- defaultTheme: "light",
141
- themes: ["light", "dark", "corporate", "dracula"],
142
- darkThemes: ["dark", "dracula"],
239
+ loadCompanyDetails: `${MsUrl.sor}/company-details`, // app name, logos, favicon from the backend (see "Company details")
240
+ // appName / logoUrl / logoDarkUrl: only for apps WITHOUT company details (static brand)
241
+ // defaultLanguage: "en-US", // optional: without it the browser / system language, else en-US
242
+ loadLocale: loadLocaleGroups.bind(null, localeFiles),
243
+ // defaultTheme: "light", // optional: without it the browser preference picks "dark" or "light"
244
+ loadThemes: loadThemes, // optional: your own themes as JSON (see "Custom themes as JSON")
245
+ // themes: ["light", "dark"], // optional: default all 35 DaisyUI themes
143
246
  layout: { menuMode: "sidebar", isSidebarCollapsible: true },
144
247
  http: { baseUrl: API_BASE_URL, logoutUrl: "/login" },
145
248
  };
@@ -147,63 +250,142 @@ export const config: UiConfig = {
147
250
 
148
251
  | Setting | What it does |
149
252
  | --- | --- |
150
- | `defaultLanguage`, `fallbackLanguage` | Optional language codes like `en-US` (default `"en-US"`). The default is shown before the `lang` list arrives (and when a file is missing). Without `defaultLanguage`, `languages`, `loadLocale` and `lang` the app runs in en-US with the library's built-in English texts and no language switcher. |
151
- | `loadLocale(code)` | Loads `locales/{code}.json` lazily for any language code. |
152
- | `languages` | Not needed: the list comes from `lang` (below). Only for apps with a fixed list (`{ code, label, flag?, direction?, load? }`). |
153
- | `themes`, `darkThemes` | Listed by the theme switcher. Dark themes switch to `logoDarkUrl` and dark markdown. |
253
+ | `defaultLanguage` | Optional. Language of the first visit (nothing saved). Without it the **browser / system language** is used: `navigator.languages` matched to the language list (exact code, else the same base language: `fr-CA` → `fr-FR`); without a list each browser code is tried and a missing locale file is skipped. Nothing matches → `"en-US"`. Keys missing in a language are shown in `defaultLanguage` (else en-US). Without `defaultLanguage`, `languages`, `loadLocale` and `loadSupportLanguages` the app runs in en-US with the library's built-in English texts and no language switcher. |
254
+ | `loadLocale(code)` | Loads the texts of a language lazily (dynamic `import()` / `import.meta.glob`): `loadLocaleGroups.bind(null, localeFiles)` for `locales/<code>/<group>.json`, or your own function returning one JSON. |
255
+ | `languages` | Not needed: the list comes from `loadSupportLanguages` (below). Only for apps with a fixed list (`{ code, label, flag?, direction?, load? }`). |
256
+ | `themes`, `darkThemes` | Optional. The theme switcher list (default: all 35 DaisyUI themes) and the dark ones (default: the DaisyUI dark themes). Dark themes switch to `logoDarkUrl` and dark markdown. |
257
+ | `customThemes`, `loadThemes` | Optional. Your own themes as data / JSON — an object keyed by theme name (`{ "org-dark": { isDark, name, variables }, ... }`) or a list — listed first: `customThemes` directly, or `loadThemes()` lazily like `loadLocale` (JSON file or API). Later ones: `setCustomThemes(json)`. |
258
+ | `defaultTheme` | Optional. Theme of the first visit (nothing saved yet). Without it the browser preference decides: `"dark"` when it prefers a dark colour scheme, otherwise `"light"`. |
154
259
  | `layout.headerSettings` | `"inline"` (language + theme switchers in the header) or `"menu"` (one ⚙ button opening a settings dialog with language, theme and navigation style). |
260
+ | `layout.showLayoutChoice` | Optional (default `false`). Adds **Layout** (App layout / Aside layout) to the ⚙ settings dialog — for a shell that renders `AppLayout` or `AsideLayout` from `layoutChoiceSignal`. Saved as `LAYOUT_CHOICE`; `<SettingsMenu showLayoutChoice />` does the same for one menu. |
155
261
  | `layout.toastPosition`, `layout.showScrollToTop` | Toast corner (`top-end` …) and the scroll-to-top button. |
156
262
  | `layout.showMenu` | Menu shown at start (default `true`); switch at runtime with `setMenuVisible()` / `toggleMenuVisible()`. |
157
263
  | `layout.menuMode` | `"sidebar"` (drawer + collapsible icon rail) or `"megamenu"` (top bar + full-width panels). Users can switch with `changeNavigationMode()`; the choice is saved. |
158
264
  | `homePath`, `layout.pageParam` | The page shown when `?page` is missing (default `/`) and the name of the page parameter (default `page`). |
159
265
  | `http.baseUrl` | API base URL of `AppHttp` (`window.env.REACT_APP_<APPNAMEKEY>_API_BASE_URL` wins when set; a relative `/api` becomes absolute). |
160
266
  | `http.logoutUrl` | Where the browser goes after `endSession()` (log out), for example `/login` or an SSO logout URL. `endSession(keepKeys, false)` stays on the page. |
161
- | `http.tokenKey`, `http.headers`, `http.loadUrl`, `http.showProgress` | Optional: AppStorage key of the token (default `TOKEN`), extra headers, `AppHttp.Load` URL (default base + `/load`), progress bar (default `true`). |
267
+ | `http.tokenKey`, `http.headers`, `http.loadUrl`, `http.showProgress` | Optional: AppStorage key of the token (default `TOKEN`), extra headers, `AppHttp.Load` URL or path (default `/load` on the base URL), progress bar (default `true`). |
162
268
  | `appNameKey` | Key of the app (`ENV_BASE_NAME`): prefix of every AppStorage key (`ORG-TOKEN`, `ORG-LANG`) and of the `window.env` names (`REACT_APP_ORG_…`). The key names are fixed constants — no `storage` / `languageKey` / `themeKey` settings. |
163
- | `appName` | Label shown in header, sidebar and login: `t(config.appName)` (plain text or a translation key). Default: `appNameKey`. |
164
-
165
- | `navigation` | Not needed: the menu comes from `nav` (below). Only for apps with a fixed menu and no backend (`NavItem[]`). |
269
+ | `appName`, `logoUrl`, `logoDarkUrl` | Optional static brand, for apps without `loadCompanyDetails`: label in header, sidebar and login (`t(config.appName)`, default `appNameKey`) and the logos. Not needed when the company details come from the backend. |
270
+ | `loadCompanyDetails` | Optional. Company / brand details from the backend (`{ appName, companyName, faviconUrl, logoUrl, logoDarkUrl }`), loaded once on start; they win over `appName`, `logoUrl`, `logoDarkUrl`. See "Company details" below. |
271
+ | `loadSupportLanguages`, `loadBranches`, `loadMenuNavigation` | Backend loaders the provider calls (like `loadThemes`): languages on start, branches then menu after sign in. See "Backend data" below. |
272
+ | `navigation` | Not needed: the menu comes from `loadMenuNavigation` (below). Only for apps with a fixed menu and no backend (`NavItem[]`). |
166
273
  | `navOptions` | How the backend menu is converted: `rootMenuIds` (default: groups named "Root" or ids ending in `_ROOT`), `isRootFlattened` (default `true`). |
167
274
 
168
- ### Second config: `nav` (menu from the backend)
275
+ ### Backend data: `loadSupportLanguages`, `loadBranches`, `loadMenuNavigation`
169
276
 
170
- The menu is passed separately from `config` and can change at any time (login, persona switch, refresh).
171
- Pass the backend reply as it is — `{ data: [...], meta }` or only the list:
277
+ Like `loadThemes`, these are loaders in the config, and the provider calls them itself — no `nav` / `lang` /
278
+ `branch` props. A loader is your function returning the reply (or just a URL / path, sent with `AppHttp.Get`).
279
+ Replies may be `{ data: [...], meta }` or only the list.
172
280
 
173
- ```tsx
174
- const menuResponse = await AppHttp.Get(menuUrl); // { data: [...], meta: {...} }
281
+ ```ts
282
+ // config.ts
283
+ function loadSupportLanguages(): Promise<unknown> {
284
+ return AppHttp.Get(`${MsUrl.main}/languages`); // { data: [{ code: "en-US", name: "English", isDefault: true }] }
285
+ }
286
+
287
+ function loadBranches(): Promise<unknown> {
288
+ return AppHttp.Get(`${MsUrl.main}/branches`);
289
+ }
175
290
 
176
- <SharedWebUiProvider config={config} nav={menuResponse}> // null = skeleton, then the reply
177
- <App />
178
- </SharedWebUiProvider>
291
+ function loadMenuNavigation(): Promise<unknown> {
292
+ return AppHttp.Get(`${MsUrl.main}/menu-access`, { persona: "admin" });
293
+ }
294
+
295
+ export const config: UiConfig = {
296
+ appNameKey: "ORG",
297
+ loadLocale: loadLocale,
298
+ loadThemes: loadThemes,
299
+ loadSupportLanguages: loadSupportLanguages, // on start -> language switchers
300
+ loadBranches: loadBranches, // after sign in -> branch switcher (before the menu)
301
+ loadMenuNavigation: loadMenuNavigation, // after sign in -> menu (skeleton until it answers)
302
+ };
179
303
  ```
180
304
 
181
- Typical flow — the value starts as `null` and the reply arrives later:
305
+ | When | What happens |
306
+ | --- | --- |
307
+ | Provider mounts | `loadSupportLanguages` runs once; on an error the default language stays. |
308
+ | Sign in (`startSession`) or a restored session on start | `loadBranches`, then `loadMenuNavigation` (so the menu request sends `x-branch-id`). A menu error shows an empty menu, a branch error no switcher. |
309
+ | Sign out (`endSession`) | Branches removed; the menu goes back to the skeleton for the next user. |
310
+
311
+ **Or pass signals.** Each of the three can also be a signal you fill yourself (`null` first, then the reply). The
312
+ provider follows it: every new value is shown at once, and nothing is called for it (no sign-in rule — your code
313
+ decides when it changes):
182
314
 
183
- ```tsx
315
+ ```ts
184
316
  // nav.service.ts
185
- export const navSignal = signal<MenuSource | null>(null); // null = menu skeleton
317
+ export const navSignal = signal<MenuSource | null>(null); // null = menu skeleton
318
+ export const branchSignal = signal<BranchSource | null>(null); // null = no branch switcher
319
+ export const supportLangSignal = signal<LangSource | null>(null); // null = no list yet
186
320
 
187
321
  export async function loadNav(): Promise<void> {
188
- navSignal.value = null;
189
- const reply = await AppHttp.Get(menuUrl);
190
- navSignal.value = reply; // menu appears; a new reply replaces it
322
+ navSignal.value = await AppHttp.Get(`${MsUrl.main}/menu-access`) as MenuSource;
191
323
  }
192
324
 
193
- // root.tsx
194
- export function Root() {
195
- useSignals();
196
- const nav = navSignal.value;
197
- return (
198
- <SharedWebUiProvider config={config} nav={nav}>
199
- <App />
200
- </SharedWebUiProvider>
201
- );
325
+ // config.ts
326
+ loadSupportLanguages: supportLangSignal,
327
+ loadBranches: branchSignal,
328
+ loadMenuNavigation: navSignal,
329
+ ```
330
+
331
+ Functions, URLs and signals can be mixed (for example languages as a function, the menu as a signal).
332
+
333
+ Without `loadMenuNavigation` the menu is `config.navigation` (static). By hand, without loaders: `setLanguages(reply)`,
334
+ `setBranches(reply)`, `setMenuLoading()` → `setMenu(reply)`, `clearMenu()`.
335
+
336
+ ### Company details: `loadCompanyDetails`
337
+
338
+ The app name, company name, favicon and logos can come from the backend:
339
+
340
+ ```json
341
+ // GET /org-api/company-details (or { "data": { ... } })
342
+ {
343
+ "appName": "YourAppName",
344
+ "companyName": "YourBrandName",
345
+ "faviconUrl": "https://www.w3.org/favicon.ico",
346
+ "logoUrl": "https://www.w3.org/Icons/w3c_home.png",
347
+ "logoDarkUrl": "https://www.w3.org/Icons/w3c_home.png"
202
348
  }
203
349
  ```
204
350
 
205
- On an API error set `[]` (empty menu), otherwise the skeleton stays. On logout set `null` again.
206
- Without the prop: `setMenuLoading()` → `setMenu(menuResponse)`; `clearMenu()` on logout.
351
+ ```ts
352
+ // config.ts — a function, a URL / path (AppHttp.Get) or a signal, like the other loaders
353
+ loadCompanyDetails: `${MsUrl.sor}/company-details`,
354
+ // or: loadCompanyDetails: companySignal, // signal<CompanySource | null>(null); null = config values for now
355
+ ```
356
+
357
+ | Field | Used for |
358
+ | --- | --- |
359
+ | `appName` | Label in the header, sidebar and login (wins over `config.appName`) and the browser tab title |
360
+ | `companyName` | Alt text of the logo; read `companyDetailsSignal.value?.companyName` to show it anywhere (footer, login) |
361
+ | `faviconUrl` | `<link rel="icon">` (created when the page has none) |
362
+ | `logoUrl` | Logo on light themes, and on dark themes without `logoDarkUrl` (wins over `config.logoUrl` / `logoDarkUrl`) |
363
+ | `logoDarkUrl` | Logo on dark themes (wins over `config.logoDarkUrl`) |
364
+
365
+ **No `appName`, `logoUrl` or `logoDarkUrl` in the config is needed** — the brand comes from this reply (the example
366
+ apps have none in their config). Until it arrives no app name and no logo are shown (the app key does not flash);
367
+ on an error the app key is shown. Every field is optional: a missing one keeps the config value, when the config
368
+ has one. Loaded once when the provider mounts; on an error the
369
+ config values stay. For type `"mfe"` only when the MFE sets it (the shell owns the brand; an auth MFE with the brand on its login sets it). By hand: `setCompanyDetails(reply)`.
370
+ Helpers: `readLogoUrl(config, isDarkTheme, details)`, `readAppNameLabel(config, details)`, `readCompanyDetails(reply)`.
371
+ The example apps load sor `/company-details` into `companySignal` on start.
372
+
373
+ ### Layout choice (shell with microfrontends)
374
+
375
+ `layoutChoiceSignal` (`"app"` | `"aside"`) and `changeLayoutChoice(choice)` keep the picked app layout in
376
+ `LAYOUT_CHOICE` (localStorage). The provider reads it on start, and every copy of the library on the page (shell and
377
+ MFEs) follows a change at once, like the theme. The shell renders `AppLayout` or `AsideLayout` from it; an MFE uses
378
+ it to know whether the shell shows a header (`isAsideLayoutSignal`).
379
+
380
+ ### App type: `<SharedWebUiProvider type="...">`
381
+
382
+ | `type` | For | Differences |
383
+ | --- | --- | --- |
384
+ | `"spa"` (default) | a normal app | layouts, menu, login; pages in `?page=...` |
385
+ | `"shell"` | the root app that hosts microfrontends | like `spa`, but pages are paths by default (`/settings`) |
386
+ | `"mfe"` | a microfrontend inside a shell | page layouts only: no menu (no skeleton), `loadMenuNavigation` / `loadBranches` not called (the shell owns them; `loadCompanyDetails` only when the MFE sets it); `appName`, `logoUrl`, `logoDarkUrl`, `homePath`, `branchLabel` are not used. `loadSupportLanguages` still works. |
387
+
388
+ `layout.pageMode` set in the config always wins over the type.
207
389
 
208
390
  What happens to the reply (`MenuAccessType`: `id`, `name`, `nameLang`, `href`, `icon`, `type`, `priority`,
209
391
  `read/create/update/delete` or `permissions`, `active`, `children`):
@@ -216,31 +398,20 @@ What happens to the reply (`MenuAccessType`: `id`, `name`, `nameLang`, `href`, `
216
398
 
217
399
  `toNavigation(menuResponse, options)` does the conversion if you need the `NavItem[]` yourself.
218
400
 
219
- ### Third input: `lang` (languages from the backend)
220
-
221
- Passed the same way as `nav`: `null` first, the reply later. Texts come from `locales/{code}.json` via `loadLocale`.
401
+ ### Languages from the backend (`loadSupportLanguages`)
222
402
 
223
- ```tsx
224
- // lang.service.ts
225
- export const langSignal = signal<LangSource | null>(null);
226
-
227
- export async function loadLanguages(): Promise<void> {
228
- const reply = await AppHttp.Get(languagesUrl); // { data: [{ code: "en-US", name: "English", isDefault: true }, ...] }
229
- langSignal.value = reply;
230
- }
231
-
232
- // root.tsx
233
- <SharedWebUiProvider config={config} nav={navSignal.value} lang={langSignal.value}>
234
- ```
403
+ Called once on start (see above). Texts come from `locales/<code>/<group>.json` via `loadLocale`.
235
404
 
236
405
  - Row fields: `code` (or `langCode` / `languageCode` / `id`), `name` or `label`, `flag`, `direction` or `dir`,
237
406
  `isDefault` (or `default`), `active` (false hides it), `priority`. RTL is automatic for `ar`, `he`, `fa`, `ur`.
238
- - While `lang` is `null`: `defaultLanguage` (or the language the user saved) is shown; the switchers have no list yet.
239
- - When the list arrives: the user's saved language stays if it is listed; otherwise the row with `isDefault`
240
- (else `defaultLanguage`, else the first) is loaded. Only a language the user picks is saved to localStorage.
407
+ - Until the reply arrives: the saved language, else `defaultLanguage`, else the browser language (when its file
408
+ loads), else `en-US` is shown; the switchers have no list yet.
409
+ - When the list arrives: the user's saved language stays if it is listed; otherwise the row with `isDefault`,
410
+ else `defaultLanguage`, else the browser / system language (matched to the list), else `en-US`,
411
+ else the first is loaded. Only a language the user picks is saved to localStorage.
241
412
  - `TypeLang` / `TypeLangMd` fields get one entry per listed language: `{ "en-US": "...", "ar-SA": "..." }`;
242
413
  backend `nameLang` with the same codes is shown by `trans()` and the menu.
243
- - Without the prop: `setLanguages(reply)`. Conversion only: `toLanguageOptions(reply)`, `readDefaultLanguageCode(reply)`.
414
+ - By hand: `setLanguages(reply)`. Conversion only: `toLanguageOptions(reply)`, `readDefaultLanguageCode(reply)`.
244
415
 
245
416
  ### AppStorage and AppHttp
246
417
 
@@ -258,6 +429,31 @@ AppStorage.envData("API_BASE_URL"); // window.env.REACT_APP_ORG_AP
258
429
 
259
430
  // MsUrl comes from the project's config.ts (see section 1)
260
431
  const rows = await AppHttp.Get(`${MsUrl.main}/profile/search`, params);
432
+
433
+ // A path works too: it is appended to http.baseUrl (or window.env API_BASE_URL)
434
+ const same = await AppHttp.Get("/org-api/profile/search", params); // -> https://api.example.com/api/org-api/profile/search
435
+ ```
436
+
437
+ **URLs in every AppHttp method** (`Get`, `Post`, `Put`, `Delete`, `Patch`, `Load`, `Media`, `CloudUpload`, `DownloadFile`): a URL that
438
+ starts with `http://` or `https://` is used as it is; anything else is appended to the base URL with one `/` between
439
+ (`"/items"` and `"items"` both become `<baseUrl>/items`). `AppHttp.FullUrl(url)` returns the URL a request would use.
440
+
441
+ **Shared requests (shell + microfrontends):** `AppHttp.GetShared(url, params?)` is a GET that runs **once per page**
442
+ for every copy of the library: the shell and each MFE bundle their own copy, and the same URL + params (running or
443
+ answered) gives the same promise, so the languages, themes, texts and company details are not loaded again by each MFE.
444
+ An MFE that runs alone still loads them itself. Only for data that is the same for everyone (not the menu or branches);
445
+ a failed request is not kept; `clearSharedGetCache()` empties it.
446
+
447
+ ```ts
448
+ const reply = await AppHttp.GetShared(`${MsUrl.sor}/load/LANG`, { active: true });
449
+ ```
450
+
451
+ **Binary files:** `AppHttp.Media(url, params?)` is a GET that returns the body as a `Blob` (images, video, audio, any
452
+ file), with the same headers (token, `x-session-id`, `x-branch-id`, no `Content-Type`) and no progress bar:
453
+
454
+ ```ts
455
+ const blob = await AppHttp.Media(`${MsUrl.utils}/files/${fileId}`);
456
+ const objectUrl = URL.createObjectURL(blob); // <img src={objectUrl} />; URL.revokeObjectURL(objectUrl) when done
261
457
  ```
262
458
 
263
459
  **Which storage:** decided only by the key (no argument).
@@ -270,6 +466,9 @@ const rows = await AppHttp.Get(`${MsUrl.main}/profile/search`, params);
270
466
  On start the provider removes old app values from localStorage that are not preferences (`AppStorage.cleanLocalStorage()`).
271
467
  Saving a preference (`THEME`, `LANG` …) also fires the window event `PREFERENCE_EVENT`; every copy of the library on the
272
468
  page (microfrontends) and every other tab applies the new theme / language at once.
469
+ `startSession` / `endSession` fire `SESSION_EVENT` the same way: every other library copy on the page reads the session
470
+ from AppStorage (sign in) or clears it (sign out). So an **auth microfrontend** can sign in and the shell (its own
471
+ library copy) is signed in at once — the shell needs no login of its own (see `example-mfe/auth`).
273
472
 
274
473
  Key constants (also as `StorageKeys.*`): `TOKEN`, `AUTH_USER`, `SESSION_INFO`, `SCREEN_ACCESS`, `SCREEN_ACTION`, `NAV`,
275
474
  `REMEMBER_ME`, `TRANS`, `DIR`, `LANG`, `THEME`, `LAYOUT_CHOICE`, `MENU_MODE`, `SIDEBAR_COLLAPSED`, `OTP_ID`, `BRANCH_ID`, `BRANCH_NAME`,
@@ -281,37 +480,75 @@ AppHttp headers on every request: `Content-Type`, `Authorization: Bearer <TOKEN>
281
480
  Pick the branch with `setBranch(branch.id, branch.name)` (saved as `BRANCH_ID` / `BRANCH_NAME`, read back with
282
481
  `readBranchId()` or `branchIdSignal`); `clearBranch()` removes it and `endSession()` clears it too.
283
482
 
284
- **Branch switcher** – pass the user's branches like `lang` (null first, the reply later); the default and disabled
483
+ **Branch switcher** – `config.loadBranches` (called after sign in, before the menu); the default and disabled
285
484
  branches come with the rows:
286
485
 
287
- ```tsx
288
- <SharedWebUiProvider config={config} nav={nav} lang={lang} branch={branchReply}>
289
- // config.branchLabel = "branch.title" -> title of the switcher, shown with t() (default "ui.branch" = "Branch")
486
+ ```ts
487
+ loadBranches: loadBranches, // () => AppHttp.Get(`${MsUrl.main}/branches`)
488
+ branchLabel: "branch.title", // title of the switcher, shown with t() (default "ui.branch" = "Branch")
290
489
  ```
291
490
 
292
491
  - Rows: `{ id | branchId | code, name | branchName | label, nameLang?, isDefault?, disabled?, active?, priority? }`, as `{ data: [...] }` or the list.
293
492
  - `disabled: true` shows the branch greyed out; it can not be selected. `active: false` hides it.
294
493
  - Selected when the list arrives: the saved `BRANCH_ID` (if listed and not disabled) → the row with `isDefault` → the first one that is not disabled.
295
494
  - Shown as a dropdown in the `Header` and as the first section of the settings dialog. `null` or `[]` = no switcher.
296
- - `setBranches(reply)` does the same without the provider (call it before the menu request so it already
495
+ - `setBranches(reply)` does the same by hand (call it before the menu request so it already
297
496
  sends `x-branch-id`). Own layouts: `<BranchSwitcher />`. Helpers: `toBranchOptions`, `pickBranch`, `branchesSignal`.
298
497
  The token is read from AppStorage (`TOKEN`, sessionStorage then localStorage).
299
498
 
300
499
  `AppHttp` and `AppStorage` use no signals: they read the config saved by `<SharedWebUiProvider>`.
301
500
  Code that runs before the provider (for example at module load) calls `setAppConfig(config)` first, in `main.tsx`.
302
501
 
303
- ## 2. locales/en-US.json
502
+ ## 2. locales: one folder per language, one file per group
304
503
 
305
- ```json
306
- {
307
- "app": { "name": "My App" },
308
- "nav": { "dashboard": "Dashboard", "users": "Users", "usersText": "Everyone who uses the app" },
309
- "greeting": "Hello {{name}}",
310
- "REQUIRED": "This field is required"
311
- }
312
504
  ```
505
+ locales/
506
+ en-US/
507
+ app.json { "name": "My App" } -> t("app.name")
508
+ nav.json { "dashboard": "Dashboard", "users": "Users" } -> t("nav.users")
509
+ roles.json { "admin": "Admin", "viewer": "Viewer" } -> t("roles.admin")
510
+ root.json { "greeting": "Hello {{name}}", "REQUIRED": "..." } -> t("greeting"), t("REQUIRED") (top level)
511
+ fr-FR/
512
+ app.json …
513
+ ```
514
+
515
+ ```ts
516
+ // config.ts
517
+ import { loadLocaleGroups } from "shared-lib-web";
313
518
 
314
- Lookup order: current language → `fallbackLanguage` → library defaults (`ui.*` and dff-util `ConstMessages`) → the key.
519
+ const localeFiles = import.meta.glob("./locales/*/*.json"); // lazy: nothing is downloaded yet
520
+
521
+ export const config: UiConfig = {
522
+ loadLocale: loadLocaleGroups.bind(null, localeFiles), // fr-FR used -> only locales/fr-FR/*.json load
523
+ };
524
+ ```
525
+
526
+ - **Dynamic:** `import.meta.glob` (without `eager`) gives one lazy loader per file; `loadLocaleGroups` runs only
527
+ the files of the language that is used, in parallel, and merges them (the file name is the group, `root.json`
528
+ stays at the top level). The default language (en-US) is loaded too, for keys missing in the current one.
529
+ - **Several folders:** merge them, `{ ...sharedFiles, ...ownFiles }` (MFEs: shared groups + the MFE's own); the same
530
+ group in two folders is merged, the later file wins per key.
531
+ - **Or a signal:** `loadLocale: localeSignal`, a `LocaleBundle` (`{ "en-US": {...}, "fr-FR": {...} }`) your app fills.
532
+ The library adds the codes it needs to `requestedLocalesSignal` and waits; `fillLocaleBundle` loads them for you
533
+ (a code set to `null` = no texts for that language, the next one is tried):
534
+
535
+ ```ts
536
+ export const localeSignal = signal<LocaleBundle | null>(null);
537
+ const loadTexts = loadLocaleGroups.bind(null, import.meta.glob("./locales/*/*.json"));
538
+ loadLocale: localeSignal, // config.ts
539
+ useEffect(() => fillLocaleBundle(localeSignal, loadTexts)); // start once (returns the stop function)
540
+ ```
541
+
542
+ This `localeSignal` is your app's own signal. The library also exports a `localeSignal` (the current language
543
+ code); in a file that needs both, import the library one with an alias:
544
+ `import { localeSignal as currentLanguageSignal } from "shared-lib-web"`.
545
+ - One JSON per language still works: `loadLocale: (code) => import(\`./locales/${code}.json\`)`.
546
+
547
+ **One sublevel only:** a key is `"key"` or `"group.key"` (`t("user.title")`, `t("branch.title")`). Deeper keys like
548
+ `user.role.admin` are not looked up, and the library warns in the console when a locale file has them — use
549
+ `role.admin` or `user.roleAdmin` instead.
550
+
551
+ Lookup order: current language → `defaultLanguage` (else en-US) → library defaults (`ui.*` and dff-util `ConstMessages`) → the key.
315
552
  Shell texts to translate: `ui.language, theme, openMenu, expandMenu, collapseMenu, home, loading, close, noData,
316
553
  selectOption, search, navigation, account, logout, confirm, cancel, translate, permissionDenied,
317
554
  permissionDeniedText, pageNotFound, pageNotFoundText, backToHome, goBack, reloadPage, comingSoon, comingSoonText,
@@ -320,13 +557,10 @@ openPreview, playVideo, mediaError`.
320
557
  ## 3. main.tsx and app.tsx
321
558
 
322
559
  ```tsx
323
- // root.tsx – the three inputs: static config + two backend replies (null first)
560
+ // root.tsx – one input: the config (menu, languages, branches come from its loaders)
324
561
  export function Root() {
325
- useSignals();
326
- const nav = navSignal.value;
327
- const lang = langSignal.value;
328
562
  return (
329
- <SharedWebUiProvider config={config} nav={nav} lang={lang}>
563
+ <SharedWebUiProvider type="spa" config={config}>
330
564
  <App />
331
565
  </SharedWebUiProvider>
332
566
  );
@@ -419,7 +653,7 @@ isMenuVisibleSignal.value // current state (re-renders components)
419
653
  | `AppLayout` | `headerEnd`, `sidebarFooter`, `showHeader`, `showSidebar` (default: `isMenuVisibleSignal`), `header`, `sidebar`, `footer` |
420
654
  | `Header` | `endContent`, `startContent`, `showMenuButtons`, `showSwitchers`, `isStandalone` |
421
655
  | `Sidebar` | `footer`, `showBrand` |
422
- | `SidebarNav` | `className`, `isAlwaysExpanded`, `isAlwaysShown` (menu list only, follows permissions and the menu on/off switch, skeleton while `nav` is `null`) |
656
+ | `SidebarNav` | `className`, `isAlwaysExpanded`, `isAlwaysShown` (menu list only, follows permissions and the menu on/off switch, skeleton until `loadMenuNavigation` answers) |
423
657
 
424
658
  The example app shows both: Settings → *App layout* switches between `AppLayout` and
425
659
  `MainLayout` in `example/src/layout/main-layout.tsx`.
@@ -555,7 +789,9 @@ const headActions = (
555
789
  | `AppStorage.getData / getText / setData / removeData / clearData / envData`, `TOKEN`, `LANG`, `THEME`, `BRANCH_ID` … `StorageKeys` | Prefixed session/local storage, shared key constants, `window.env` settings |
556
790
  | `openPage`, `setQueryParam(s)`, `removeQueryParam`, `readQueryParam(s)`, `useQueryParam`, `useCurrentPage`, `PageLink`, `currentPageSignal`, `queryParamsSignal` | Pages and query parameters (no router) |
557
791
  | `setLanguages(reply)`, `toLanguageOptions(reply)`, `languagesSignal`, `LangSource`, `LanguageRowType`, `setMenu(reply)`, `setMenuLoading()`, `clearMenu()`, `toNavigation(reply)`, `toNavItems(menus)`, `unwrapRootMenu(menus, "ADMIN_ROOT")`, `MenuAccessType`, `MenuResponseType`, `MenuSource`, `MenuOptions`, `ScreenAccessType`, `TranslationType`, `AuthUser` | Backend menus and shared app types (menu icons are fixed with `resolveLucideIcon`) |
558
- | `AppHttp.Get / Post / Put / Patch / Delete / Load / CloudUpload (uploadFile) / DownloadFile`, `AppHttp.BaseUrl()`, `AppHttp.setHeader`, `readEnvData(appNameKey, key)`, `uploadToSignedUrl`, `setAppConfig` / `readAppConfig` | HTTP client on dff-util `Http`: bearer token, session id, branch, extra headers, progress bar |
792
+ | `AppHttp.Get / GetShared / Post / Put / Patch / Delete / Load / Media / CloudUpload (uploadFile) / DownloadFile`, `clearSharedGetCache()`, `AppHttp.BaseUrl()`, `AppHttp.FullUrl(url)`, `AppHttp.setHeader`, `readEnvData(appNameKey, key)`, `uploadToSignedUrl`, `setAppConfig` / `readAppConfig` | HTTP client on dff-util `Http`: bearer token, session id, branch, extra headers, progress bar |
793
+ | `setCompanyDetails(reply)`, `companyDetailsSignal`, `readCompanyDetails(reply)`, `readAppNameLabel(config, details)`, `readLogoUrl(config, isDark, details)`, `CompanyDetails`, `CompanySource` | Company / brand details (app name, company name, favicon, logos) |
794
+ | `setCustomThemes(themes)`, `toCustomThemeList(themes)`, `customThemesSignal`, `CustomThemeMap`, `CustomThemes` | Custom themes as data (object keyed by theme name, or a list) |
559
795
  | `setBranch(id, name)`, `readBranchId()`, `clearBranch()`, `branchIdSignal`, `branchNameSignal` | Selected branch, sent as `x-branch-id` |
560
796
  | `startSession(token, user, isRemembered)`, `restoreSession()`, `endSession(keepKeys)`, `authUserSignal`, `isAuthenticatedSignal` | Login state (restored on reload) |
561
797
  | `toOptionTypes(rows)`, `readResponseRows(response)` | Backend option rows → `OptionType[]` |
@@ -575,9 +811,9 @@ There are two examples, each its own small Vite app that uses the library source
575
811
 
576
812
  | Folder | Port | Shows |
577
813
  | --- | --- | --- |
578
- | `example-basic/` | 5174 | **One language** (en-US, `defaultLanguage` + `loadLocale`, no `lang`) and **no branches** (no `branch`): login, dashboard, users CRUD, settings (theme, menu mode, menu on/off). The smallest real setup to copy. |
579
- | `example-mfe/` | 5175 | **Microfrontends**: 4 separate Vite projects — `shell` (the only `AppLayout`, login, single-spa routing from `env.mfe.js`, event-based menu after a session) and 3 MFEs `settings`, `forms`, `profile` (page layouts only; theme and language from localStorage, kept in sync between bundles). See `example-mfe/README.md`. |
580
- | `example/` | 5173 | **11 languages** (`lang` from the backend, 4 RTL) and **stores** (`branch` from the backend, `isDefault` / `disabled`), plus every component, 3 layouts and all themes. |
814
+ | `example-basic/` | 5174 | **One language** (en-US, `defaultLanguage` + `loadLocale`, no `loadSupportLanguages`) and **no branches** (no `loadBranches`): login, dashboard, users CRUD, settings (theme, menu mode, menu on/off). The smallest real setup to copy. |
815
+ | `example-mfe/` | 9000 | **Microfrontends**: 4 separate Vite projects — `shell` (the only `AppLayout`, login, single-spa routing from `env.mfe.js`, menu as a signal (`loadMenuNavigation: navSignal`), `type="shell"`) and 3 MFEs `settings`, `forms`, `profile` (`type="mfe"`, page layouts only; theme and language from localStorage, kept in sync between bundles). No shared folder: each project has its own config, texts and theme. See `example-mfe/README.md`. |
816
+ | `example/` | 5173 | **10 languages** (`loadSupportLanguages`, 3 RTL) and **stores** (`loadBranches`, `isDefault` / `disabled`), plus every component, 3 layouts and all themes. |
581
817
 
582
818
  ```bash
583
819
  npm run example-basic:install
@@ -588,9 +824,27 @@ npm run example-basic:dev # http://localhost:5174
588
824
 
589
825
  `example/` is its own small app package (Vite is used only there — an app needs a bundler; the library does not).
590
826
  It shows login, dashboard, users CRUD (drawer + confirm + permissions), a **Components** section with every control,
591
- upload, overlay, skeleton and state, and settings for language (11, including 4 RTL and Telugu, Kannada, Tamil), theme (all 35 DaisyUI themes + custom `org-light` / `org-dark`) and navigation style.
592
- All pages live in one `App` component (`example/src/app.tsx`) and are picked by `?page`; the menu (`nav`) and the
593
- languages (`lang`) come from fake backend replies. It uses the library source directly, so changes show up without a build.
827
+ upload, overlay, skeleton and state, and settings for language (10, including 3 RTL and Telugu, Kannada, Tamil), theme (all 35 DaisyUI themes + custom `org-light` / `org-dark`) and navigation style.
828
+ All pages live in one `App` component (`example/src/app.tsx`) and are picked by `?page`; the languages, branches and
829
+ menu are signals in the config (`example/src/app-init/app-init-signals.ts`), filled from the sor replies by
830
+ `app-init/app-init.service.ts`. It uses the library source directly, so changes show up without a build.
831
+
832
+ The example loads everything from the **sor** service (`MsUrl.sor` → `/api/org-sor`), except the menu, which comes
833
+ from **utils** (`MsUrl.utils` → `/api/org-util`):
834
+
835
+ | Data | Request | Signal |
836
+ | --- | --- | --- |
837
+ | Company details | `GET /company-details` | `companySignal` (on start) |
838
+ | Languages | `GET /load/LANG?active=true` | `supportLangSignal` (on start) |
839
+ | Themes | `GET /content-load?query=theme` | `themesSignal` (on start) |
840
+ | Texts of a language | `GET /content-load?query=locales.<code>` (all languages: `?query=locales`) | `localeSignal` (languages the library asks for) |
841
+ | Menu (utils) | `GET /authorization/<persona>?roles=<roles joined with ",">` (from the signed-in user) | `navSignal` (after sign in) |
842
+ | Branches | `GET /load/BRANCHS?profile=<user id>` | `branchSignal` (after sign in, before the menu) |
843
+
844
+ `readContent(reply, query)` takes the content out of a `content-load` reply (`{ data }` and the query path are
845
+ optional: `readContent(reply, "locales.en-US")`). The examples have no fake backend: they call these services at
846
+ `http.baseUrl` (`/api`) or `window.env.REACT_APP_ORG_API_BASE_URL` (`public/env.js`), so point that at your backend.
847
+ example-basic and the MFE shell work the same way (no branches).
594
848
 
595
849
  ```bash
596
850
  npm run example:install