@besaitech/ng-design-system 0.0.58 → 0.0.60

package/README.md

@@ -203,6 +203,50 @@ Import names are the `Sl…` classes; the markup selectors are `sds-…`.
 | `SdsTopbar` | `<sds-topbar>` | `appName`, `user`, `(logout)`; `[sdsLogo]` slot |
 | `SdsSidebar` + `SdsNavGroup` + `SdsNavItem` | `<sds-sidebar>` … | Collapsible nav rail; collapse state via root-provided `SidebarStore`; items render `routerLink` or `<button>` |
 
+## Theme & cross-app preferences
+
+`SdsThemeService` holds the person's **mode** — `'system' | 'light' | 'dark'`, persisted to `localStorage`
+under `sds-theme` — and resolves it to the painted **theme** (`light`/`dark`); `system` follows the OS live.
+`toggle()` / `setTheme()` set an explicit theme, `setMode('system')` goes back to following the OS.
+
+Apps of one product can carry the person's language and theme in the URL when they link to each other, so the
+page that opens matches. Sending side:
+
+```ts
+import { appendUiPrefs } from '@besaitech/ng-design-system';
+
+appendUiPrefs('https://auth.example/continue#token=abc', { lang: translate.getCurrentLang(), theme: theme.mode() });
+// → https://auth.example/continue?lang=fr&theme=dark#token=abc
+```
+
+Never put them inside a nested redirect a server matches exactly (`return_to`, `redirect_uri`) — append them to
+the outer URL. Receiving side: an inline script in `<head>` of `index.html` applies, persists and strips them
+**before first paint** (no flash, and no import of this library at the root). `LANG_KEY` is the app's own
+language storage key; keep `LANGS` in step with the app's languages. `readUiPrefs` / `stripUiPrefs` are the same
+logic for code and tests.
+
+```html
+<script>
+  (function () {
+    var LANG_KEY = 'app.lang', LANGS = ['en', 'fr', 'nl'], THEME_KEY = 'sds-theme', MODES = ['system', 'light', 'dark'];
+    var url = new URL(location.href), q = url.searchParams, lang = q.get('lang'), mode = q.get('theme');
+    try {
+      if (LANGS.indexOf(lang) >= 0) localStorage.setItem(LANG_KEY, lang);
+      if (MODES.indexOf(mode) >= 0) localStorage.setItem(THEME_KEY, mode);
+    } catch (e) {}
+    try { lang = localStorage.getItem(LANG_KEY) || lang; mode = localStorage.getItem(THEME_KEY) || mode; } catch (e) {}
+    if (LANGS.indexOf(lang) >= 0) document.documentElement.lang = lang;
+    var dark = mode === 'dark' || (mode !== 'light' && matchMedia('(prefers-color-scheme: dark)').matches);
+    document.documentElement.classList.toggle('dark', dark);
+    document.documentElement.style.colorScheme = dark ? 'dark' : 'light';
+    if (q.has('lang') || q.has('theme')) {
+      q.delete('lang'); q.delete('theme');
+      history.replaceState(history.state, '', url.pathname + url.search + url.hash);
+    }
+  })();
+</script>
+```
+
 ## Labels & languages
 
 The library ships **no translations of its own**. Every visible or spoken string — placeholders,