@design.estate/dees-domtools 5.0.1 → 5.1.0

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-domtools',
-  version: '5.0.1',
+  version: '5.1.0',
   description: 'A package providing tools to simplify complex CSS structures and web development tasks, featuring TypeScript support and integration with various web technologies.'
 }

package/ts/domtools.classes.thememanager.ts

@@ -1,28 +1,73 @@
 import { DomTools } from './domtools.classes.domtools.js';
 import * as plugins from './domtools.plugins.js';
 
+/**
+ * Which theme the reader asked for: `'system'` follows `prefers-color-scheme`, `'bright'` and
+ * `'dark'` hold that theme whatever the system does.
+ */
+export type TThemePreference = 'system' | 'bright' | 'dark';
+
+const themePreferences: readonly TThemePreference[] = ['system', 'bright', 'dark'];
+
+const isThemePreference = (valueArg: unknown): valueArg is TThemePreference => (
+  themePreferences.includes(valueArg as TThemePreference)
+);
+
 export class ThemeManager {
+  /**
+   * The `localStorage` key a picked preference is kept under, per browser and origin. `'system'` is
+   * the absence of the key.
+   */
+  public static readonly preferenceStorageKey = 'dees-domtools:theme-preference';
+
   public domtoolsRef: DomTools;
 
   public goBrightBoolean = false;
+  /** The reader's preference; the theme follows the system only while it is `'system'`. */
+  public preference: TThemePreference = 'system';
   public preferredColorSchemeMediaMatch = window.matchMedia('(prefers-color-scheme: light)');
 
   public themeObservable = new plugins.smartrx.rxjs.ReplaySubject<boolean>(1);
   private automaticGlobalThemeChangeSubscription: plugins.smartrx.rxjs.Subscription | null = null;
   private readonly preferredColorSchemeChangeHandler = (eventArg: MediaQueryListEvent) => {
+    if (this.preference !== 'system') return;
     this.goBrightBoolean = eventArg.matches;
     this.updateAllConnectedElements();
   };
+  /** Another tab of this origin picked a preference; this page follows it. */
+  private readonly storageHandler = (eventArg: StorageEvent) => {
+    if (eventArg.storageArea !== window.localStorage) return;
+    if (eventArg.key !== ThemeManager.preferenceStorageKey && eventArg.key !== null) return;
+    // A cleared storage (`key` null) forgets the pick as well.
+    const value = eventArg.key === null ? null : eventArg.newValue;
+    this.applyPreference(isThemePreference(value) ? value : 'system');
+  };
 
   constructor(domtoolsRefArg: DomTools) {
     this.domtoolsRef = domtoolsRefArg;
 
-    // lets care
-    this.goBrightBoolean = this.preferredColorSchemeMediaMatch.matches;
+    // The stored preference is read before the first emission, so a page never flashes the system theme.
+    this.preference = ThemeManager.storedPreference();
+    this.goBrightBoolean = this.resolveBright();
     this.preferredColorSchemeMediaMatch.addEventListener('change', this.preferredColorSchemeChangeHandler);
+    window.addEventListener('storage', this.storageHandler);
     this.updateAllConnectedElements();
   }
 
+  /**
+   * The preference kept in this browser. A browser that does not let the page read its storage, or a
+   * value this version does not know, keeps no preference: the theme follows the system.
+   */
+  private static storedPreference(): TThemePreference {
+    let stored: string | null;
+    try {
+      stored = window.localStorage.getItem(ThemeManager.preferenceStorageKey);
+    } catch {
+      return 'system';
+    }
+    return isThemePreference(stored) ? stored : 'system';
+  }
+
   public async enableAutomaticGlobalThemeChange() {
     await this.domtoolsRef.domReady.promise;
     if (!this.automaticGlobalThemeChangeSubscription) {
@@ -41,8 +86,43 @@ export class ThemeManager {
     this.themeObservable.next(this.goBrightBoolean);
   }
 
+  private resolveBright(): boolean {
+    return this.preference === 'system'
+      ? this.preferredColorSchemeMediaMatch.matches
+      : this.preference === 'bright';
+  }
+
+  private applyPreference(preferenceArg: TThemePreference): void {
+    this.preference = preferenceArg;
+    const goBright = this.resolveBright();
+    if (goBright === this.goBrightBoolean) return;
+    this.goBrightBoolean = goBright;
+    this.updateAllConnectedElements();
+  }
+
+  /**
+   * Picks the theme and keeps the pick in this browser (`'system'` forgets it), so the next page
+   * load starts in it. While the preference is `'bright'` or `'dark'` the system's colour scheme no
+   * longer moves the theme. Returns whether the pick was kept: false when the browser refuses the
+   * page its storage, in which case it holds for this page only. Throws on a value that is no
+   * `TThemePreference`.
+   */
+  public setPreference(preferenceArg: TThemePreference): boolean {
+    if (!isThemePreference(preferenceArg)) {
+      throw new Error(`Unknown theme preference "${String(preferenceArg)}".`);
+    }
+    this.applyPreference(preferenceArg);
+    try {
+      if (preferenceArg === 'system') window.localStorage.removeItem(ThemeManager.preferenceStorageKey);
+      else window.localStorage.setItem(ThemeManager.preferenceStorageKey, preferenceArg);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   /**
-   * set the theme of the website to bright
+   * set the theme of the website to bright, for now: the preference is unchanged
    */
   public goBright() {
     this.goBrightBoolean = true;
@@ -50,7 +130,7 @@ export class ThemeManager {
   }
 
   /**
-   * set the theme of the website to dark
+   * set the theme of the website to dark, for now: the preference is unchanged
    */
   public goDark() {
     this.goBrightBoolean = false;
@@ -58,7 +138,7 @@ export class ThemeManager {
   }
 
   /**
-   * simply toggle between bright and dark
+   * simply toggle between bright and dark, for now: the preference is unchanged
    */
   public toggleDarkBright() {
     this.goBrightBoolean = !this.goBrightBoolean;
@@ -67,6 +147,7 @@ export class ThemeManager {
 
   public dispose() {
     this.preferredColorSchemeMediaMatch.removeEventListener('change', this.preferredColorSchemeChangeHandler);
+    window.removeEventListener('storage', this.storageHandler);
     this.automaticGlobalThemeChangeSubscription?.unsubscribe();
     this.automaticGlobalThemeChangeSubscription = null;
     this.themeObservable.complete();

package/ts/index.ts

@@ -6,6 +6,7 @@ import * as css from './domtools.css.js';
 
 export { css, breakpoints, elementBasic };
 export { DomTools, type IDomToolsConstructorOptions } from './domtools.classes.domtools.js';
+export { ThemeManager, type TThemePreference } from './domtools.classes.thememanager.js';
 export { TypedRequest } from '@api.global/typedrequest';
 export { type IWebSetupConstructorOptions } from '@push.rocks/websetup';