@besaitech/ng-design-system 0.0.59 → 0.0.60

package/index.d.ts

@@ -181,7 +181,7 @@ declare class SdsButton {
      * most important control.
      */
     readonly shape: _angular_core.InputSignal<SdsButtonShape>;
-    readonly type: _angular_core.InputSignal<"button" | "reset" | "submit">;
+    readonly type: _angular_core.InputSignal<"button" | "submit" | "reset">;
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly loading: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Full-width button. */
@@ -4069,7 +4069,14 @@ declare class SdsToastHost {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdsToastHost, "sds-toast-host", never, { "closeLabel": { "alias": "closeLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/** The theme actually painted. */
 type SdsTheme = 'light' | 'dark';
+/** The person's choice: an explicit theme, or `system` = follow the OS `prefers-color-scheme`, live. */
+type SdsThemeMode = 'system' | SdsTheme;
+/** The localStorage key the mode is persisted under. Also read by the pre-paint boot script (see README). */
+declare const SDS_THEME_STORAGE_KEY = "sds-theme";
+/** `true` for the three values {@link SdsThemeMode} accepts — for validating stored or URL-supplied input. */
+declare function isSdsThemeMode(value: unknown): value is SdsThemeMode;
 /**
  * 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
@@ -4080,25 +4087,35 @@ type SdsTheme = 'light' | 'dark';
  *
  * ```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).
  */
 declare class SdsThemeService {
     private readonly document;
-    readonly theme: _angular_core.WritableSignal<SdsTheme>;
+    /** The person's choice. */
+    readonly mode: _angular_core.WritableSignal<SdsThemeMode>;
+    /** The OS preference, kept live by a `matchMedia` listener. */
+    private readonly systemDark;
+    /** The theme painted: the explicit choice, or the OS one under `system`. */
+    readonly theme: _angular_core.Signal<SdsTheme>;
     readonly isDark: _angular_core.Signal<boolean>;
     constructor();
-    /** Flip between light and dark. */
+    /** Flip between light and dark (an explicit choice, leaving `system`). */
     toggle(): void;
     /** Set an explicit theme. */
     setTheme(theme: SdsTheme): void;
-    private initialTheme;
+    /** Set the choice, `system` included. */
+    setMode(mode: SdsThemeMode): void;
+    private initialMode;
+    private queryDark;
     private apply;
     private readStorage;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdsThemeService, never>;
@@ -4139,6 +4156,47 @@ declare class SdsThemeToggle {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdsThemeToggle, "sds-theme-toggle", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "darkLabel": { "alias": "darkLabel"; "required": false; "isSignal": true; }; "lightLabel": { "alias": "lightLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * UI preferences that travel in the URL between apps of one product (sign-in hinge ↔ storefront ↔ back-office,
+ * mobile app → web account page), so the page that opens is in the language and theme the person is in.
+ *
+ * The contract is two optional query params — `lang` (a language code) and `theme` (`system` | `light` |
+ * `dark`). The SENDING side appends them with {@link appendUiPrefs}; the RECEIVING side applies + persists +
+ * strips them before first paint with the inline boot script documented in the README (and mirrored by
+ * {@link readUiPrefs} / {@link stripUiPrefs} for code and tests).
+ *
+ * Never put them inside a nested redirect URL that a server matches exactly (an OAuth `return_to` /
+ * `redirect_uri`): append them to the OUTER URL, and let the receiving app append them to the final redirect.
+ */
+interface SdsUiPrefs {
+    /** A language code, e.g. `en`. Omitted / null / empty = not sent. */
+    lang?: string | null;
+    /** The theme CHOICE (`system` stays `system`). Omitted / null = not sent. */
+    theme?: SdsThemeMode | null;
+}
+declare const SDS_UI_PREF_LANG_PARAM = "lang";
+declare const SDS_UI_PREF_THEME_PARAM = "theme";
+/**
+ * `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'
+ * ```
+ */
+declare function appendUiPrefs(url: string, prefs: SdsUiPrefs): string;
+/**
+ * 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.
+ */
+declare function readUiPrefs(search: string, supportedLangs: readonly string[]): {
+    lang: string | null;
+    theme: SdsThemeMode | null;
+};
+/** `url` without the `lang` / `theme` params (everything else, fragment included, untouched). */
+declare function stripUiPrefs(url: string): string;
+
 /** How the rail is painted. `brand` is the dark brand rail; `surface` is a light rail with brand accents. */
 type SdsSidebarAppearance = 'brand' | 'surface';
 /**
@@ -4759,5 +4817,5 @@ declare class SdsLanguageSwitcher implements OnDestroy {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdsLanguageSwitcher, "sds-language-switcher", never, { "languages": { "alias": "languages"; "required": false; "isSignal": true; }; "current": { "alias": "current"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; "direction": { "alias": "direction"; "required": false; "isSignal": true; }; "menuLabel": { "alias": "menuLabel"; "required": false; "isSignal": true; }; "heading": { "alias": "heading"; "required": false; "isSignal": true; }; }, { "current": "currentChange"; "openChange": "openChange"; }, never, never, true, never>;
 }
 
-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 type { SdsAccordionActive, SdsAccordionValue, SdsAddressAutocompleteAppearance, SdsAddressAutocompleteShape, SdsAddressAutocompleteSize, SdsAddressExtraContext, SdsAddressExtraPosition, SdsAddressLocateFn, SdsAddressSearchFn, SdsAddressSuggestion, SdsAllergen, SdsAvatarShape, SdsAvatarStatus, SdsBadgeSize, SdsBadgeVariant, SdsBulkBarPosition, SdsButtonShape, SdsButtonSize, SdsButtonVariant, SdsCardVariant, SdsCheckboxSize, SdsChecklistStatus, SdsChipOption, SdsChipSize, SdsCropRect, SdsDatePickerSize, SdsFileDropAppearance, SdsFileRejection, SdsFileRejectionReason, SdsIconName, SdsIconSize, SdsImageCropperBlobOptions, SdsImageCropperShape, SdsInputAppearance, SdsInputNumberAppearance, SdsInputNumberButtonLayout, SdsInputNumberCurrencyDisplay, SdsInputNumberMode, SdsInputNumberSize, SdsInputShape, SdsInputSize, SdsInputType, SdsLanguageOption, SdsLanguageSwitcherAlign, SdsLanguageSwitcherAppearance, SdsLanguageSwitcherDirection, SdsLocalizedInputSize, SdsLocalizedValue, SdsMenuAction, SdsMenuAlign, SdsMenuEntry, SdsMenuItemTone, SdsMenuSeparator, SdsMultiSelectDisplay, SdsMultiSelectSize, SdsNavItemBadgeTone, SdsOtpInputSize, SdsPaginatorSize, SdsPaginatorState, SdsPhoneCountry, SdsPhoneInputSize, SdsPhoneValue, SdsRadioSize, SdsScoreSize, SdsScoreTier, SdsScoreVariant, SdsSearchAppearance, SdsSearchItem, SdsSegmentedOption, SdsSegmentedSize, SdsSelectAppearance, SdsSelectEmptyContext, SdsSelectFooterContext, SdsSelectOptionContext, SdsSelectSize, SdsShellBackground, SdsSidebarAppearance, SdsSortOrder, SdsSortableAppearance, SdsSortableItemContext, SdsSortableReorderEvent, SdsStatusTileState, SdsTabValue, SdsTableCellCommitEvent, SdsTableCellContext, SdsTableCellErrors, SdsTableColumn, SdsTableEditTrigger, SdsTableEditor, SdsTableEmptyContext, SdsTableHeaderContext, SdsTableLazyEvent, SdsTableRowExpansionContext, SdsTableSelectOption, SdsTableSize, SdsTableSortEvent, SdsTextareaAppearance, SdsTextareaResize, SdsTextareaSize, SdsTheme, SdsThemeToggleAppearance, SdsTimeInputAppearance, SdsTimeInputSize, SdsToast, SdsToastKind, SdsToggleSwitchSize, SdsTopbarAppearance, SdsTriState, SdsTriStateChipSize, SdsUserMenuAlign, SdsUserMenuAppearance };
+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 };
+export type { SdsAccordionActive, SdsAccordionValue, SdsAddressAutocompleteAppearance, SdsAddressAutocompleteShape, SdsAddressAutocompleteSize, SdsAddressExtraContext, SdsAddressExtraPosition, SdsAddressLocateFn, SdsAddressSearchFn, SdsAddressSuggestion, SdsAllergen, SdsAvatarShape, SdsAvatarStatus, SdsBadgeSize, SdsBadgeVariant, SdsBulkBarPosition, SdsButtonShape, SdsButtonSize, SdsButtonVariant, SdsCardVariant, SdsCheckboxSize, SdsChecklistStatus, SdsChipOption, SdsChipSize, SdsCropRect, SdsDatePickerSize, SdsFileDropAppearance, SdsFileRejection, SdsFileRejectionReason, SdsIconName, SdsIconSize, SdsImageCropperBlobOptions, SdsImageCropperShape, SdsInputAppearance, SdsInputNumberAppearance, SdsInputNumberButtonLayout, SdsInputNumberCurrencyDisplay, SdsInputNumberMode, SdsInputNumberSize, SdsInputShape, SdsInputSize, SdsInputType, SdsLanguageOption, SdsLanguageSwitcherAlign, SdsLanguageSwitcherAppearance, SdsLanguageSwitcherDirection, SdsLocalizedInputSize, SdsLocalizedValue, SdsMenuAction, SdsMenuAlign, SdsMenuEntry, SdsMenuItemTone, SdsMenuSeparator, SdsMultiSelectDisplay, SdsMultiSelectSize, SdsNavItemBadgeTone, SdsOtpInputSize, SdsPaginatorSize, SdsPaginatorState, SdsPhoneCountry, SdsPhoneInputSize, SdsPhoneValue, SdsRadioSize, SdsScoreSize, SdsScoreTier, SdsScoreVariant, SdsSearchAppearance, SdsSearchItem, SdsSegmentedOption, SdsSegmentedSize, SdsSelectAppearance, SdsSelectEmptyContext, SdsSelectFooterContext, SdsSelectOptionContext, SdsSelectSize, SdsShellBackground, SdsSidebarAppearance, SdsSortOrder, SdsSortableAppearance, SdsSortableItemContext, SdsSortableReorderEvent, SdsStatusTileState, SdsTabValue, SdsTableCellCommitEvent, SdsTableCellContext, SdsTableCellErrors, SdsTableColumn, SdsTableEditTrigger, SdsTableEditor, SdsTableEmptyContext, SdsTableHeaderContext, SdsTableLazyEvent, SdsTableRowExpansionContext, SdsTableSelectOption, SdsTableSize, SdsTableSortEvent, SdsTextareaAppearance, SdsTextareaResize, SdsTextareaSize, SdsTheme, SdsThemeMode, SdsThemeToggleAppearance, SdsTimeInputAppearance, SdsTimeInputSize, SdsToast, SdsToastKind, SdsToggleSwitchSize, SdsTopbarAppearance, SdsTriState, SdsTriStateChipSize, SdsUiPrefs, SdsUserMenuAlign, SdsUserMenuAppearance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besaitech/ng-design-system",
-  "version": "0.0.59",
+  "version": "0.0.60",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"