@besaitech/ng-design-system 0.0.59 → 0.0.61

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);
+    }
+    /** Set the choice, `system` included. */
+    setMode(mode) {
+        this.mode.set(mode);
     }
-    initialTheme() {
+    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 'light';
+        return 'system';
     }
-    apply(theme) {
+    queryDark() {
+        try {
+            return this.document.defaultView?.matchMedia?.('(prefers-color-scheme: dark)') ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    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.
  *
@@ -18313,6 +18408,89 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.25", ngImpo
   `, styles: [".animate-sds-menu{animation:sds-menu-in .14s ease-out}@keyframes sds-menu-in{0%{opacity:0;transform:translateY(-6px)}to{opacity:1;transform:translateY(0)}}@media(prefers-reduced-motion:reduce){.animate-sds-menu{animation:none}}\n"] }]
         }], propDecorators: { trigger: [{ type: i0.ViewChild, args: ['trigger', { isSignal: true }] }], languages: [{ type: i0.Input, args: [{ isSignal: true, alias: "languages", required: false }] }], current: [{ type: i0.Input, args: [{ isSignal: true, alias: "current", required: false }] }, { type: i0.Output, args: ["currentChange"] }], appearance: [{ type: i0.Input, args: [{ isSignal: true, alias: "appearance", required: false }] }], align: [{ type: i0.Input, args: [{ isSignal: true, alias: "align", required: false }] }], direction: [{ type: i0.Input, args: [{ isSignal: true, alias: "direction", required: false }] }], menuLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "menuLabel", required: false }] }], heading: [{ type: i0.Input, args: [{ isSignal: true, alias: "heading", required: false }] }], openChange: [{ type: i0.Output, args: ["openChange"] }] } });
 
+/**
+ * Fixed, theme- AND brand-independent hues on purpose: a non-production marker must look identical in every
+ * app, brand and colour-scheme, so it uses literal sky / amber rather than themeable design-system tokens
+ * (which a brand preset could redefine). Sky for DEV, amber for TEST.
+ */
+const MARKERS = {
+    dev: { label: 'DEV', bar: 'bg-[#38bdf8]', tab: 'bg-[#38bdf8] text-[#0c1a24]', variant: 'dev' },
+    test: { label: 'TEST', bar: 'bg-[#f59e0b]', tab: 'bg-[#f59e0b] text-[#1c1916]', variant: 'test' },
+};
+/**
+ * Non-production environment marker: a 3px rule pinned across the very top of the viewport with a small tab
+ * hanging from its centre — sky **DEV** or amber **TEST**, nothing in production. Fixed and click-through,
+ * above all app chrome, so a dev or test environment is never mistaken for the live one.
+ *
+ * Presentation only, no i18n or environment dependency: the host app supplies the resolved `[env]` (from its
+ * `environment.env`, or — for an SSR app — from the request host) and, optionally, the translated
+ * screen-reader sentences. Render it once from the app's root component.
+ */
+class SdsEnvBanner {
+    /** The resolved build environment. Only `dev` and `test` show a marker; `prod`/anything else shows nothing. */
+    env = input(...(ngDevMode ? [undefined, { debugName: "env" }] : []));
+    /** Screen-reader sentence for the DEV marker (pass a translated string; English default). */
+    devSrLabel = input('Development environment — not production', ...(ngDevMode ? [{ debugName: "devSrLabel" }] : []));
+    /** Screen-reader sentence for the TEST marker (pass a translated string; English default). */
+    testSrLabel = input('Test environment — not production', ...(ngDevMode ? [{ debugName: "testSrLabel" }] : []));
+    marker = computed(() => {
+        const env = this.env();
+        return env === 'dev' ? MARKERS.dev : env === 'test' ? MARKERS.test : null;
+    }, ...(ngDevMode ? [{ debugName: "marker" }] : []));
+    srLabel = computed(() => {
+        const m = this.marker();
+        return m ? (m.variant === 'dev' ? this.devSrLabel() : this.testSrLabel()) : '';
+    }, ...(ngDevMode ? [{ debugName: "srLabel" }] : []));
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.25", ngImport: i0, type: SdsEnvBanner, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.25", type: SdsEnvBanner, isStandalone: true, selector: "sds-env-banner", inputs: { env: { classPropertyName: "env", publicName: "env", isSignal: true, isRequired: false, transformFunction: null }, devSrLabel: { classPropertyName: "devSrLabel", publicName: "devSrLabel", isSignal: true, isRequired: false, transformFunction: null }, testSrLabel: { classPropertyName: "testSrLabel", publicName: "testSrLabel", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `
+    @if (marker(); as m) {
+      <div
+        class="pointer-events-none fixed inset-x-0 top-0 z-[2147483000] h-[3px]"
+        [class]="m.bar"
+        role="note"
+        data-testid="env-banner"
+      >
+        <span
+          class="absolute left-1/2 top-0 -translate-x-1/2 rounded-b-lg px-3 pb-[3px] pt-px font-sans text-[11px] font-extrabold leading-4 tracking-[0.12em] shadow-[0_2px_6px_rgb(0_0_0/0.18)]"
+          [class]="m.tab"
+          aria-hidden="true"
+          >{{ m.label }}</span
+        >
+        @if (srLabel(); as sr) {
+          <span class="sr-only">{{ sr }}</span>
+        }
+      </div>
+    }
+  `, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.25", ngImport: i0, type: SdsEnvBanner, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'sds-env-banner',
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    template: `
+    @if (marker(); as m) {
+      <div
+        class="pointer-events-none fixed inset-x-0 top-0 z-[2147483000] h-[3px]"
+        [class]="m.bar"
+        role="note"
+        data-testid="env-banner"
+      >
+        <span
+          class="absolute left-1/2 top-0 -translate-x-1/2 rounded-b-lg px-3 pb-[3px] pt-px font-sans text-[11px] font-extrabold leading-4 tracking-[0.12em] shadow-[0_2px_6px_rgb(0_0_0/0.18)]"
+          [class]="m.tab"
+          aria-hidden="true"
+          >{{ m.label }}</span
+        >
+        @if (srLabel(); as sr) {
+          <span class="sr-only">{{ sr }}</span>
+        }
+      </div>
+    }
+  `,
+                }]
+        }], propDecorators: { env: [{ type: i0.Input, args: [{ isSignal: true, alias: "env", required: false }] }], devSrLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "devSrLabel", required: false }] }], testSrLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "testSrLabel", required: false }] }] } });
+
 /*
  * Public API Surface of saitech-design-system — the Saitech / App design system.
  */
@@ -18322,5 +18500,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, SdsEnvBanner, 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