@besaitech/ng-design-system 0.0.59 → 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,

package/fesm2022/besaitech-ng-design-system.mjs

@@ -15837,7 +15837,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.25", ngImpo
                 }]
         }], propDecorators: { closeLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "closeLabel", required: false }] }] } });
 
-const STORAGE_KEY = 'sds-theme';
+/** The localStorage key the mode is persisted under. Also read by the pre-paint boot script (see README). */
+const SDS_THEME_STORAGE_KEY = 'sds-theme';
+/** `true` for the three values {@link SdsThemeMode} accepts — for validating stored or URL-supplied input. */
+function isSdsThemeMode(value) {
+    return value === 'system' || value === 'light' || value === 'dark';
+}
 /**
  * Light/dark theme state for the whole app. It owns exactly one thing: the presence of the `.dark`
  * class on the document root, which flips every design token defined under `.dark` in the theme CSS
@@ -15848,53 +15853,80 @@ const STORAGE_KEY = 'sds-theme';
  *
  * ```ts
  * private readonly theme = inject(SdsThemeService);
- * this.theme.toggle();            // flip
+ * this.theme.toggle();            // flip (to an explicit light/dark)
+ * this.theme.setMode('system');   // follow the OS again
  * this.theme.isDark();            // read (a signal)
+ * this.theme.mode();              // 'system' | 'light' | 'dark'
  * ```
  *
- * Initial value: a previously stored choice wins; otherwise the OS `prefers-color-scheme` is honoured,
- * so a first-time visitor already in dark at the OS level lands in dark. The choice is persisted to
- * `localStorage` and re-applied on the next visit. Every browser access is guarded, so the service is
- * safe under SSR / prerender (it simply no-ops without a DOM).
+ * Two layers: {@link mode} is the choice (persisted to `localStorage` under `sds-theme`), {@link theme} is
+ * what that resolves to. With no stored choice the mode is `system`, which tracks the OS setting live —
+ * a first-time visitor in dark at the OS level lands in dark, and follows the OS if it flips. Every
+ * browser access is guarded, so the service is safe under SSR / prerender (it simply no-ops without a DOM).
  */
 class SdsThemeService {
     document = inject(DOCUMENT);
-    theme = signal(this.initialTheme(), ...(ngDevMode ? [{ debugName: "theme" }] : []));
+    /** The person's choice. */
+    mode = signal(this.initialMode(), ...(ngDevMode ? [{ debugName: "mode" }] : []));
+    /** The OS preference, kept live by a `matchMedia` listener. */
+    systemDark = signal(this.queryDark()?.matches ?? false, ...(ngDevMode ? [{ debugName: "systemDark" }] : []));
+    /** The theme painted: the explicit choice, or the OS one under `system`. */
+    theme = computed(() => {
+        const mode = this.mode();
+        return mode === 'system' ? (this.systemDark() ? 'dark' : 'light') : mode;
+    }, ...(ngDevMode ? [{ debugName: "theme" }] : []));
     isDark = computed(() => this.theme() === 'dark', ...(ngDevMode ? [{ debugName: "isDark" }] : []));
     constructor() {
-        // Keep the DOM class and the stored preference in lockstep with the signal — one effect, so any
-        // caller that sets the signal (toggle, setTheme, or a future settings screen) applies uniformly.
-        effect(() => this.apply(this.theme()));
+        // Keep the DOM class and the stored choice in lockstep with the signals — one effect, so any caller
+        // (toggle, setTheme, setMode, or the OS flipping under `system`) applies uniformly.
+        effect(() => this.apply(this.theme(), this.mode()));
+        const query = this.queryDark();
+        if (query) {
+            const onChange = (event) => this.systemDark.set(event.matches);
+            query.addEventListener?.('change', onChange);
+            inject(DestroyRef).onDestroy(() => query.removeEventListener?.('change', onChange));
+        }
     }
-    /** Flip between light and dark. */
+    /** Flip between light and dark (an explicit choice, leaving `system`). */
     toggle() {
-        this.theme.update((t) => (t === 'light' ? 'dark' : 'light'));
+        this.mode.set(this.theme() === 'light' ? 'dark' : 'light');
     }
     /** Set an explicit theme. */
     setTheme(theme) {
-        this.theme.set(theme);
+        this.mode.set(theme);
     }
-    initialTheme() {
+    /** Set the choice, `system` included. */
+    setMode(mode) {
+        this.mode.set(mode);
+    }
+    initialMode() {
         try {
-            const stored = this.readStorage()?.getItem(STORAGE_KEY);
-            if (stored === 'light' || stored === 'dark')
+            const stored = this.readStorage()?.getItem(SDS_THEME_STORAGE_KEY);
+            if (isSdsThemeMode(stored))
                 return stored;
-            const win = this.document.defaultView;
-            if (win?.matchMedia('(prefers-color-scheme: dark)').matches)
-                return 'dark';
         }
         catch {
-            /* no storage / no matchMedia (SSR, privacy mode) — fall through to the light default */
+            /* no storage (SSR, privacy mode) — fall through to following the OS */
+        }
+        return 'system';
+    }
+    queryDark() {
+        try {
+            return this.document.defaultView?.matchMedia?.('(prefers-color-scheme: dark)') ?? null;
+        }
+        catch {
+            return null;
         }
-        return 'light';
     }
-    apply(theme) {
+    apply(theme, mode) {
         const root = this.document.documentElement;
         root.classList.toggle('dark', theme === 'dark');
         // Let the UA paint form controls / scrollbars to match.
         root.style.colorScheme = theme;
         try {
-            this.readStorage()?.setItem(STORAGE_KEY, theme);
+            // The CHOICE is stored, not the resolved theme — `system` must stay `system`, or the first visit
+            // would freeze whatever the OS happened to be set to.
+            this.readStorage()?.setItem(SDS_THEME_STORAGE_KEY, mode);
         }
         catch {
             /* storage unavailable — the class is still applied; only persistence is skipped */
@@ -15984,6 +16016,69 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.25", ngImpo
                 }]
         }], propDecorators: { size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], appearance: [{ type: i0.Input, args: [{ isSignal: true, alias: "appearance", required: false }] }], darkLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "darkLabel", required: false }] }], lightLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "lightLabel", required: false }] }] } });
 
+const SDS_UI_PREF_LANG_PARAM = 'lang';
+const SDS_UI_PREF_THEME_PARAM = 'theme';
+const ABSOLUTE = /^[a-z][a-z0-9+.-]*:/i;
+const PLACEHOLDER_ORIGIN = 'http://sds.invalid';
+/**
+ * `url` with `lang` / `theme` set on its query (overwriting any present), the fragment kept. Accepts an
+ * absolute URL or a root-relative path (returned root-relative). Invalid themes are dropped, not sent.
+ *
+ * ```ts
+ * appendUiPrefs('https://auth.example/continue#token=abc', { lang: 'fr', theme: 'dark' })
+ * // → 'https://auth.example/continue?lang=fr&theme=dark#token=abc'
+ * ```
+ */
+function appendUiPrefs(url, prefs) {
+    const absolute = ABSOLUTE.test(url);
+    let parsed;
+    try {
+        parsed = new URL(url, PLACEHOLDER_ORIGIN);
+    }
+    catch {
+        return url;
+    }
+    const lang = prefs.lang?.trim();
+    if (lang) {
+        parsed.searchParams.set(SDS_UI_PREF_LANG_PARAM, lang);
+    }
+    if (isSdsThemeMode(prefs.theme)) {
+        parsed.searchParams.set(SDS_UI_PREF_THEME_PARAM, prefs.theme);
+    }
+    return absolute ? parsed.toString() : parsed.pathname + parsed.search + parsed.hash;
+}
+/**
+ * The prefs carried by a query string (`location.search`), validated: `lang` only if it is one of
+ * `supportedLangs`, `theme` only if it is a {@link SdsThemeMode}. Anything else reads as absent.
+ */
+function readUiPrefs(search, supportedLangs) {
+    const params = new URLSearchParams(search);
+    const lang = params.get(SDS_UI_PREF_LANG_PARAM);
+    const theme = params.get(SDS_UI_PREF_THEME_PARAM);
+    return {
+        lang: lang && supportedLangs.includes(lang) ? lang : null,
+        theme: isSdsThemeMode(theme) ? theme : null,
+    };
+}
+/** `url` without the `lang` / `theme` params (everything else, fragment included, untouched). */
+function stripUiPrefs(url) {
+    const absolute = ABSOLUTE.test(url);
+    let parsed;
+    try {
+        parsed = new URL(url, PLACEHOLDER_ORIGIN);
+    }
+    catch {
+        return url;
+    }
+    if (!parsed.searchParams.has(SDS_UI_PREF_LANG_PARAM) &&
+        !parsed.searchParams.has(SDS_UI_PREF_THEME_PARAM)) {
+        return url;
+    }
+    parsed.searchParams.delete(SDS_UI_PREF_LANG_PARAM);
+    parsed.searchParams.delete(SDS_UI_PREF_THEME_PARAM);
+    return absolute ? parsed.toString() : parsed.pathname + parsed.search + parsed.hash;
+}
+
 /**
  * Shared collapse state for the sidebar and its nav items.
  *
@@ -18322,5 +18417,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.25", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { SDS_ALLERGENS, SDS_ALLERGEN_ICONS, SDS_ALLERGEN_LABELS_EN, SDS_ICONS, SDS_PHONE_COUNTRIES, SdsAccordion, SdsAccordionContent, SdsAccordionHeader, SdsAccordionPanel, SdsAccordionStore, SdsAddressAutocomplete, SdsAddressExtra, SdsAllergenIcon, SdsAvatar, SdsBadge, SdsBulkBar, SdsButton, SdsCalendar, SdsCard, SdsCheckbox, SdsChecklistRow, SdsChip, SdsChipGroup, SdsDatePicker, SdsFileDrop, SdsIcon, SdsImageCropper, SdsInput, SdsInputNumber, SdsLanguageSwitcher, SdsLocalizedInput, SdsMenu, SdsMenuItem, SdsMenuTrigger, SdsMultiSelect, SdsNavGroup, SdsNavItem, SdsOtpInput, SdsPaginator, SdsPhoneInput, SdsRadio, SdsScore, SdsSearchCommand, SdsSegmented, SdsSelect, SdsSelectEmpty, SdsSelectFooter, SdsSelectOption, SdsShell, SdsSidebar, SdsSortableHandle, SdsSortableItem, SdsSortableList, SdsStatusTile, SdsTab, SdsTabList, SdsTabPanel, SdsTabPanels, SdsTable, SdsTableCell, SdsTableEmpty, SdsTableHeader, SdsTableRowExpansion, SdsTabs, SdsTabsStore, SdsTextarea, SdsThemeService, SdsThemeToggle, SdsTimeInput, SdsToastHost, SdsToastService, SdsToggleSwitch, SdsTopbar, SdsTriStateChip, SdsUserMenu, SidebarStore, addDays, addMonths, addMonthsKeepDay, formatDdMmYyyy, formatHhMm, isOutOfRange, isSameDay, isoDay, pad2, sdsFileMatchesAccept, sdsFormatBytes, sdsFormatNational, sdsMatchDialCode, sdsNormalizeSignificant, startOfDay, startOfMonth };
+export { SDS_ALLERGENS, SDS_ALLERGEN_ICONS, SDS_ALLERGEN_LABELS_EN, SDS_ICONS, SDS_PHONE_COUNTRIES, SDS_THEME_STORAGE_KEY, SDS_UI_PREF_LANG_PARAM, SDS_UI_PREF_THEME_PARAM, SdsAccordion, SdsAccordionContent, SdsAccordionHeader, SdsAccordionPanel, SdsAccordionStore, SdsAddressAutocomplete, SdsAddressExtra, SdsAllergenIcon, SdsAvatar, SdsBadge, SdsBulkBar, SdsButton, SdsCalendar, SdsCard, SdsCheckbox, SdsChecklistRow, SdsChip, SdsChipGroup, SdsDatePicker, SdsFileDrop, SdsIcon, SdsImageCropper, SdsInput, SdsInputNumber, SdsLanguageSwitcher, SdsLocalizedInput, SdsMenu, SdsMenuItem, SdsMenuTrigger, SdsMultiSelect, SdsNavGroup, SdsNavItem, SdsOtpInput, SdsPaginator, SdsPhoneInput, SdsRadio, SdsScore, SdsSearchCommand, SdsSegmented, SdsSelect, SdsSelectEmpty, SdsSelectFooter, SdsSelectOption, SdsShell, SdsSidebar, SdsSortableHandle, SdsSortableItem, SdsSortableList, SdsStatusTile, SdsTab, SdsTabList, SdsTabPanel, SdsTabPanels, SdsTable, SdsTableCell, SdsTableEmpty, SdsTableHeader, SdsTableRowExpansion, SdsTabs, SdsTabsStore, SdsTextarea, SdsThemeService, SdsThemeToggle, SdsTimeInput, SdsToastHost, SdsToastService, SdsToggleSwitch, SdsTopbar, SdsTriStateChip, SdsUserMenu, SidebarStore, addDays, addMonths, addMonthsKeepDay, appendUiPrefs, formatDdMmYyyy, formatHhMm, isOutOfRange, isSameDay, isSdsThemeMode, isoDay, pad2, readUiPrefs, sdsFileMatchesAccept, sdsFormatBytes, sdsFormatNational, sdsMatchDialCode, sdsNormalizeSignificant, startOfDay, startOfMonth, stripUiPrefs };
 //# sourceMappingURL=besaitech-ng-design-system.mjs.map