chore: move system-theme-extractor to i-static-page/modules/theme

CHANGELOG.md

@@ -17,6 +17,10 @@ _Note: Gaps between patch versions are faulty, broken or test releases._
 
 * Added support for different cookie stores: `core/cookies`, `core/kv-storage/engines/cookie`
 
+#### :house: Internal
+
+* Moved `system-theme-extractor` from `core` to `components/super/i-static-page/modules/theme`
+
 ## v4.0.0-beta.57 (2024-02-13)
 
 #### :bug: Bug Fix
@@ -70,6 +74,7 @@ _Note: Gaps between patch versions are faulty, broken or test releases._
 #### :house: Internal
 
 * Create a `mono` template in `i-block` for dynamic mono components. It disables vnode attribute hoisting.
+>>>>>>> v4
 
 ## v4.0.0-beta.54 (2024-02-06)
 

src/components/super/i-static-page/i-static-page.ts

@@ -22,7 +22,7 @@ import { setLocale, locale } from 'core/i18n';
 
 import type { AppliedRoute, InitialRoute } from 'core/router';
 import * as cookie from 'core/kv-storage/engines/cookie';
-import { webEngineFactory } from 'core/system-theme-extractor/engines/web';
+import { SystemThemeExtractorWeb } from 'components/super/i-static-page/modules/theme';
 
 import {
 
@@ -103,8 +103,10 @@ export default abstract class iStaticPage extends iPage {
 	 */
 	@system<iStaticPage>((o) => themeManagerFactory(
 		o,
-		cookie.syncLocalStorage,
-		webEngineFactory(o)
+		{
+			themeStorageEngine: cookie.syncLocalStorage,
+			systemThemeExtractor: new SystemThemeExtractorWeb(o)
+		}
 	))
 
 	readonly theme: CanUndef<ThemeManager>;

src/components/super/i-static-page/modules/theme/README.md

@@ -93,7 +93,24 @@ module.exports = config.createConfig({dirs: [__dirname, 'client']}, {
 
 ## Accessors
 
-## current
+### availableThemes
+
+A set of available app themes.
+
+```typescript
+import iBlock, { component, prop, field } from 'components/super/i-block/i-block';
+
+@component()
+export default class bExample extends iBlock {
+  created() {
+    console.log(this.r.theme.availableThemes);
+  }
+}
+```
+
+## Methods
+
+### get
 
 Current theme value.
 
@@ -103,22 +120,37 @@ import iBlock, { component, prop, field } from 'components/super/i-block/i-block
 @component()
 export default class bExample extends iBlock {
   created() {
-    console.log(this.r.theme.current);
+    console.log(this.r.theme.get());
   }
 }
 ```
 
-## availableThemes
+### set
 
-A set of available app themes.
+Sets a new value for the current theme.
+
+```typescript
+import iBlock, { component, prop, field } from 'components/super/i-block/i-block';
+
+@component()
+export default class bExample extends iBlock {
+  changeTheme(value: 'dark' | 'light') {
+    this.r.theme.set(value);
+  }
+}
+```
+
+### useSystem
+
+Sets the actual system theme and activates the system theme change listener.
 
 ```typescript
 import iBlock, { component, prop, field } from 'components/super/i-block/i-block';
 
 @component()
 export default class bExample extends iBlock {
   created() {
-    console.log(this.r.theme.availableThemes);
+    this.r.theme.useSystem();
   }
 }
 ```

src/components/super/i-static-page/modules/theme/factory.ts

@@ -6,22 +6,22 @@
  * https://github.com/V4Fire/Client/blob/master/LICENSE
  */
 
+import type { StorageEngine } from 'core/kv-storage';
+
 import type iBlock from 'components/super/i-block/i-block';
 import ThemeManager from 'components/super/i-static-page/modules/theme/theme-manager';
-import type { StorageEngine } from 'core/kv-storage';
-import type { SystemThemeExtractor } from 'core/system-theme-extractor';
+
+import type { SystemThemeExtractor } from 'components/super/i-static-page/modules/theme/system-theme-extractor';
 
 /**
- * Returns an instance of the class for managing interface themes, if that functionality is available
+ * Returns an instance of the class for managing interface themes if that functionality is available
  *
  * @param component
- * @param store
- * @param systemTheme
+ * @param engines
  */
 export default function themeManagerFactory(
 	component: iBlock,
-	store: StorageEngine,
-	systemTheme: SystemThemeExtractor
+	engines: {themeStorageEngine: StorageEngine; systemThemeExtractor: SystemThemeExtractor}
 ): CanNull<ThemeManager> {
-	return Object.isString(THEME) ? new ThemeManager(component, store, systemTheme) : null;
+	return Object.isString(THEME) ? new ThemeManager(component, engines) : null;
 }

src/components/super/i-static-page/modules/theme/index.ts

@@ -11,6 +11,8 @@
  * @packageDocumentation
  */
 
+export * from 'components/super/i-static-page/modules/theme/const';
 export { default } from 'components/super/i-static-page/modules/theme/factory';
+
 export { default as ThemeManager } from 'components/super/i-static-page/modules/theme/theme-manager';
-export * from 'components/super/i-static-page/modules/theme/const';
+export { default as SystemThemeExtractorWeb } from 'components/super/i-static-page/modules/theme/system-theme-extractor/engines/web/engine';

src/core/system-theme-extractor/CHANGELOG.md → src/components/super/i-static-page/modules/theme/system-theme-extractor/CHANGELOG.md

@@ -9,6 +9,12 @@ Changelog
 > - :house:      [Internal]
 > - :nail_care:  [Polish]
 
+## v4.0.0-beta.?? (2024-??-??)
+
+#### :house: Internal
+
+* Moved from `core` to `components/super/i-static-page/modules/theme`
+
 ## v4.0.0-beta.52 (2023-01-31)
 
 #### :rocket: New Feature

src/core/system-theme-extractor/README.md → src/components/super/i-static-page/modules/theme/system-theme-extractor/README.md

@@ -1,4 +1,4 @@
-# core/system-theme-extractor
+# components/super/i-static-page/modules/theme/system-theme-extractor
 
 This module provides an API for obtaining and observing the preferred color scheme of an application.
 
@@ -9,12 +9,12 @@ By default, the engine for the web is supported.
 The engine needs to be passed to the `themeManager` constructor.
 
 ```ts
-import { webEngineFactory } from 'core/system-theme-extractor/engines/web';
+import { SystemThemeExtractorWeb } from 'components/super/i-static-page/modules/theme';
 
 class iRoot extends iStaticPage {
   @system<iStaticPage>((o) => themeManagerFactory(
     // ...other required parameters for themeManager
-    webEngineFactory(o)
+    new SystemThemeExtractorWeb(o)
   ))
 
   readonly theme: CanUndef<ThemeManager>;
@@ -24,16 +24,16 @@ class iRoot extends iStaticPage {
 Also, you can implement your own engine.
 
 ```ts
-// src/core/system-theme-extractor/engines/custom/index.ts
-import type { SystemThemeExtractor } from 'core/system-theme-extractor';
+// src/components/super/i-static-page/modules/theme/system-theme-extractor/engines/custom/index.ts
+import type { SystemThemeExtractor } from 'components/super/i-static-page/modules/theme/system-theme-extractor';
 
 export default class CustomEngine implements SystemThemeExtractor {
   // Implement all necessary methods of the interface here.
 }
 ```
 
-The `SystemThemeExtractor` interface specifies that the `getSystemTheme` method
-should return a promise-like object so that you can compute the system theme asynchronously.
-If synchronous computation is relevant in your case, you can use `SyncPromise`.
+The `SystemThemeExtractor` interface specifies that the `getSystemTheme` method should return a Promise object,
+allowing for asynchronous computation of the system theme.
+If synchronous computation is necessary for your case, you can use `SyncPromise`.
 
-See `components/super/i-static-page/modules/theme` for details
+See `components/super/i-static-page/modules/theme` for details.

src/components/super/i-static-page/modules/theme/system-theme-extractor/engines/web/engine.ts

@@ -0,0 +1,55 @@
+/*!
+ * V4Fire Client Core
+ * https://github.com/V4Fire/Client
+ *
+ * Released under the MIT license
+ * https://github.com/V4Fire/Client/blob/master/LICENSE
+ */
+
+import type { EventEmitterLikeP, AsyncOptions } from 'core/async';
+import SyncPromise from 'core/promise/sync';
+
+import Friend from 'components/friends/friend';
+import type iBlock from 'components/super/i-block/i-block';
+
+import type { SystemThemeExtractor } from 'components/super/i-static-page/modules/theme/system-theme-extractor';
+
+/**
+ * Represents a `SystemThemeExtractor` implementation tailored for web environments.
+ * This implementation uses a media query to monitor changes in the preferred color scheme.
+ */
+export default class WebEngine extends Friend implements SystemThemeExtractor {
+	/**
+	 * Media query to watch theme changes
+	 */
+	protected darkThemeMq: MediaQueryList;
+
+	/**
+	 * Event emitter
+	 */
+	protected emitter: EventEmitterLikeP;
+
+	constructor(component: iBlock) {
+		super(component);
+
+		this.darkThemeMq = globalThis.matchMedia('(prefers-color-scheme: dark)');
+
+		type EmitterArgs = [string, (e: Event) => void];
+
+		this.emitter = Object.cast((...args: EmitterArgs) => {
+			this.darkThemeMq.addEventListener(...args);
+			return (...args: EmitterArgs) => this.darkThemeMq.removeEventListener(...args);
+		});
+	}
+
+	/** @inheritDoc */
+	getSystemTheme(): SyncPromise<string> {
+		return SyncPromise.resolve(this.darkThemeMq.matches ? 'dark' : 'light');
+	}
+
+	/** @inheritDoc */
+	onThemeChange(cb: (value: string) => void, asyncOptions?: AsyncOptions): void {
+		const changeHandler = (e: MediaQueryListEvent) => cb(e.matches ? 'dark' : 'light');
+		this.ctx.async.on(this.emitter, 'change', changeHandler, asyncOptions);
+	}
+}

src/core/system-theme-extractor/index.ts → src/components/super/i-static-page/modules/theme/system-theme-extractor/index.ts

@@ -6,4 +6,4 @@
  * https://github.com/V4Fire/Client/blob/master/LICENSE
  */
 
-export * from 'core/system-theme-extractor/interface';
+export * from 'components/super/i-static-page/modules/theme/system-theme-extractor/interface';

src/components/super/i-static-page/modules/theme/system-theme-extractor/interface.ts

@@ -0,0 +1,30 @@
+/*!
+ * V4Fire Client Core
+ * https://github.com/V4Fire/Client
+ *
+ * Released under the MIT license
+ * https://github.com/V4Fire/Client/blob/master/LICENSE
+ */
+
+import type { AsyncOptions } from 'core/async/modules/base/interface';
+
+/**
+ * An API for retrieving and monitoring the system's visual appearance
+ */
+export interface SystemThemeExtractor {
+	/**
+	 * Retrieves the current system visual appearance theme
+	 */
+	getSystemTheme(): Promise<string>;
+
+	/**
+	 * Initializes an event listener for changes in the system's visual appearance theme
+	 *
+	 * @param cb - a callback function to be invoked when the theme changes.
+	 *             It receives the color scheme identifier as a string parameter,
+	 *             by which the project's theme can be selected.
+	 *
+	 * @param [asyncOptions]
+	 */
+	onThemeChange(cb: (value: string) => void, asyncOptions?: AsyncOptions): void;
+}