@design.estate/dees-domtools 5.0.0 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-domtools",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "private": false,
   "description": "A package providing tools to simplify complex CSS structures and web development tasks, featuring TypeScript support and integration with various web technologies.",
   "main": "dist_ts/index.js",
@@ -9,17 +9,18 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.1.2",
-    "@git.zone/tsbundle": "^3.1.3",
-    "@git.zone/tstest": "^7.0.0",
-    "@types/node": "^26.6.3"
+    "@git.zone/tsbuild": "^6.0.2",
+    "@git.zone/tsbundle": "^3.2.1",
+    "@git.zone/tstest": "^7.2.0",
+    "@types/node": "26.6.4",
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "@api.global/typedrequest": "^9.0.2",
     "@design.estate/dees-comms": "^2.0.0",
     "@push.rocks/lik": "^6.4.4",
     "@push.rocks/smartjson": "^6.0.2",
-    "@push.rocks/smartmarkdown": "^3.3.0",
+    "@push.rocks/smartmarkdown": "^3.5.0",
     "@push.rocks/smartpromise": "^4.3.0",
     "@push.rocks/smartrouter": "^1.3.3",
     "@push.rocks/smartrx": "^3.0.12",

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,20 @@ 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.
+
+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 +320,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 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, and `TThemePreference` (`'system' | 'bright' | 'dark'`) for a preference (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.0',
+  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.domtools.ts

@@ -5,9 +5,12 @@ import { WebSetup } from '@push.rocks/websetup';
 import { ThemeManager } from './domtools.classes.thememanager.js';
 import { Keyboard } from './domtools.classes.keyboard.js';
 
-declare global {
-  var deesDomTools: DomTools | undefined;
-}
+/**
+ * The page's one DomTools lives on `globalThis` as `deesDomTools`, so every copy of this package on a page shares
+ * it. It is typed here, for this module only: a global declaration names each copy's own `DomTools`, and two copies
+ * in one program — two versions, or one installed twice for different peers — would clash on it (TS2403).
+ */
+const globalScope = globalThis as typeof globalThis & { deesDomTools?: DomTools };
 
 export interface IDomToolsState {
   virtualViewport: TViewport;
@@ -34,19 +37,19 @@ export class DomTools {
       return domToolsInstance;
     }
 
-    if (globalThis.deesDomTools && !globalThis.deesDomTools.disposed) {
-      await globalThis.deesDomTools.initializationPromise;
-      return globalThis.deesDomTools;
+    if (globalScope.deesDomTools && !globalScope.deesDomTools.disposed) {
+      await globalScope.deesDomTools.initializationPromise;
+      return globalScope.deesDomTools;
     }
 
     if (!DomTools.initializationPromise) {
       const domToolsInstance = new DomTools(optionsArg);
-      globalThis.deesDomTools = domToolsInstance;
+      globalScope.deesDomTools = domToolsInstance;
       DomTools.initializationPromise = domToolsInstance.initializationPromise
         .then(() => domToolsInstance)
         .catch((error) => {
-          if (globalThis.deesDomTools === domToolsInstance) {
-            globalThis.deesDomTools = undefined;
+          if (globalScope.deesDomTools === domToolsInstance) {
+            globalScope.deesDomTools = undefined;
           }
           DomTools.initializationPromise = null;
           throw error;
@@ -60,7 +63,7 @@ export class DomTools {
    * if you can, use the static asysnc .setupDomTools() function instead since it is safer to use.
    */
   public static getGlobalDomToolsSync(): DomTools {
-    const globalDomTools = globalThis.deesDomTools;
+    const globalDomTools = globalScope.deesDomTools;
     if (!globalDomTools || globalDomTools.disposed) {
       throw new Error('You tried to access domtools synchronously too early');
     }
@@ -265,8 +268,8 @@ export class DomTools {
     }
     this.managedDomNodes.length = 0;
 
-    if (globalThis.deesDomTools === this) {
-      globalThis.deesDomTools = undefined;
+    if (globalScope.deesDomTools === this) {
+      globalScope.deesDomTools = undefined;
       DomTools.initializationPromise = null;
     }
   }

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';