@design.estate/dees-domtools 5.0.1 → 5.2.0

package/readme.md

@@ -17,6 +17,7 @@ pnpm add @design.estate/dees-domtools
 ## What It Includes
 
 - `DomTools` for one-time app bootstrap and shared browser services
+- `ThemeManager` (the class behind `domtools.themeManager`) and its `TThemePreference` type, for a bright/dark theme that follows the system until the reader picks one
 - `breakpoints` helpers for viewport and container-query driven Lit CSS
 - `css.cssGridColumns()` for simple grid-template generation
 - `elementBasic` helpers for Lit base styles and one-time global CSS setup
@@ -144,6 +145,29 @@ await themeManager.enableAutomaticGlobalThemeChange();
 
 The theme manager starts from `prefers-color-scheme` and publishes updates through an RxJS `ReplaySubject<boolean>`.
 
+### Theme preference
+
+A theme toggle sets the reader's preference rather than the theme of the moment:
+
+```ts
+themeManager.preference; // 'system' | 'bright' | 'dark' (TThemePreference)
+themeManager.setPreference(themeManager.goBrightBoolean ? 'dark' : 'bright'); // true when kept
+themeManager.setPreference('system'); // follow prefers-color-scheme again
+```
+
+`'system'` follows `prefers-color-scheme`; `'bright'` and `'dark'` hold that theme while the system's scheme changes. A picked preference is kept in `localStorage` under `ThemeManager.preferenceStorageKey` (`dees-domtools:theme-preference`, per browser and origin; `'system'` removes the key) and is read before the theme manager's first emission, so a reload starts in it without showing the system theme first. Another tab's pick reaches every open page of the origin through the `storage` event. `setPreference()` returns `false` when the browser refuses the page its storage: the pick then holds for this page only, and it throws on a value that is no `TThemePreference`. An unknown stored value counts as no pick. `goBright()`, `goDark()` and `toggleDarkBright()` set the theme for now and leave the preference alone.
+
+A toggle that shows the preference, not only the theme, subscribes to `stateObservable`, a `ReplaySubject<IThemeState>` that replays the current state and emits on every change of the preference, the system's colour scheme or the theme, also when the theme stays (a pick of the theme the system already shows, the system changing while a pick holds, another tab's pick):
+
+```ts
+themeManager.stateObservable.subscribe(({ preference, systemBright, goBright }) => {
+  // e.g. offer "follow the system" while a pick holds the theme the system shows
+});
+themeManager.systemBright; // the system's colour scheme is light, as prefers-color-scheme last reported it
+```
+
+The page's `DomTools` is one instance on `globalThis` shared by every copy of this package, so it is the copy that creates it whose `ThemeManager` serves the page: every copy in a bundle must be a version with `setPreference()` for a toggle to rely on it.
+
 `enableAutomaticGlobalThemeChange()` waits for `domReady`, so it is safe to call before `document.body` exists.
 
 ## Keyboard Shortcuts
@@ -305,9 +329,10 @@ Repeated callers receive the first result, and repeated failures re-throw the st
 ## Extra Exports
 
 ```ts
-import { TypedRequest, plugins } from '@design.estate/dees-domtools';
+import { TypedRequest, ThemeManager, type IThemeState, type TThemePreference, plugins } from '@design.estate/dees-domtools';
 ```
 
+- `ThemeManager` is the class of `domtools.themeManager`, exported for `ThemeManager.preferenceStorageKey` and for typing; use the page's instance rather than constructing one, `TThemePreference` (`'system' | 'bright' | 'dark'`) for a preference, and `IThemeState` for what `stateObservable` emits (see Theme preference)
 - `TypedRequest` is re-exported from `@api.global/typedrequest` 9 for typed request flows
 - `plugins` exposes the underlying modules used by the package, including `smartrouter`, `smartstate`, `smartrx`, `smartpromise`, and `typedrequest`
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-domtools',
-  version: '5.0.1',
+  version: '5.2.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,93 @@
 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)
+);
+
+/** What a theme toggle shows: the reader's preference, the system's colour scheme and the theme they resolve to. */
+export interface IThemeState {
+  preference: TThemePreference;
+  /** The system's colour scheme is light. */
+  systemBright: boolean;
+  /** The page shows the bright theme. */
+  goBright: boolean;
+}
+
 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)');
+  /** The system's colour scheme is light, as `prefers-color-scheme` last reported it. */
+  public systemBright = this.preferredColorSchemeMediaMatch.matches;
 
   public themeObservable = new plugins.smartrx.rxjs.ReplaySubject<boolean>(1);
+  /**
+   * The preference, the system's colour scheme and the theme, on every change of any of them, also
+   * when the theme stays; replays the current state to a new subscriber.
+   */
+  public stateObservable = new plugins.smartrx.rxjs.ReplaySubject<IThemeState>(1);
   private automaticGlobalThemeChangeSubscription: plugins.smartrx.rxjs.Subscription | null = null;
   private readonly preferredColorSchemeChangeHandler = (eventArg: MediaQueryListEvent) => {
+    this.systemBright = eventArg.matches;
+    if (this.preference !== 'system') {
+      this.publishState();
+      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) {
@@ -39,10 +104,55 @@ export class ThemeManager {
       return;
     }
     this.themeObservable.next(this.goBrightBoolean);
+    this.publishState();
+  }
+
+  private publishState(): void {
+    if (this.domtoolsRef.disposed) {
+      return;
+    }
+    this.stateObservable.next({ preference: this.preference, systemBright: this.systemBright, goBright: this.goBrightBoolean });
+  }
+
+  private resolveBright(): boolean {
+    return this.preference === 'system' ? this.systemBright : this.preference === 'bright';
+  }
+
+  private applyPreference(preferenceArg: TThemePreference): void {
+    const preferenceChanged = preferenceArg !== this.preference;
+    this.preference = preferenceArg;
+    const goBright = this.resolveBright();
+    if (goBright !== this.goBrightBoolean) {
+      this.goBrightBoolean = goBright;
+      this.updateAllConnectedElements();
+    } else if (preferenceChanged) {
+      this.publishState();
+    }
+  }
+
+  /**
+   * 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 +160,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 +168,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,8 +177,10 @@ 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();
+    this.stateObservable.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 IThemeState, type TThemePreference } from './domtools.classes.thememanager.js';
 export { TypedRequest } from '@api.global/typedrequest';
 export { type IWebSetupConstructorOptions } from '@push.rocks/websetup';