@su-labs/core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-04
+
+### Added
+- `createSuStore`: minimal reactive store compatible with the Svelte store contract and React `useSyncExternalStore`
+- `isBrowser`: environment check used to keep utilities safe in Node and during SSR
+- `@su-labs/core/theme`: framework-agnostic `SuThemeController` (moved from `@su-labs/theme`)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yevheniy Alekseyev <yev.alekseyev@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# @su-labs/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![npm](https://img.shields.io/npm/v/@su-labs/core?style=for-the-badge)
+![License](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)
+
+Framework-agnostic browser utilities with a tiny reactive store. Use them from vanilla JavaScript, React, Svelte, Angular or any other framework. No dependencies besides `tslib`.
+
+> Using Angular? [@su-labs/theme](https://www.npmjs.com/package/@su-labs/theme) wraps these utilities in Angular services with signals.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Entry Points](#entry-points)
+- [Reactive Stores](#reactive-stores)
+- [Theme](#theme)
+- [License](#license)
+
+## Installation
+
+```bash
+npm install @su-labs/core
+```
+
+## Getting Started
+
+Pick the guide for your environment. Each one covers installation, setup and usage:
+
+| Environment | Guide |
+|-------------|-------|
+| Vanilla JavaScript (bundler or CDN, no build step) | [Vanilla JS guide](https://github.com/Greezaaa/settings-utils-lib/blob/main/docs/guides/vanilla.md) |
+| React (Vite, Next.js, Remix, …) | [React guide](https://github.com/Greezaaa/settings-utils-lib/blob/main/docs/guides/react.md) |
+| Svelte and SvelteKit | [Svelte guide](https://github.com/Greezaaa/settings-utils-lib/blob/main/docs/guides/svelte.md) |
+| Angular | [Angular guide](https://github.com/Greezaaa/settings-utils-lib/blob/main/docs/guides/angular.md) (uses the Angular packages) |
+| Node.js and server-side rendering | [Node guide](https://github.com/Greezaaa/settings-utils-lib/blob/main/docs/guides/node.md) |
+
+## Entry Points
+
+Each utility has its own entry point, so your bundle only includes what you import.
+
+| Import | Contents |
+|--------|----------|
+| `@su-labs/core` | `createSuStore`, `isBrowser` |
+| `@su-labs/core/theme` | `SuThemeController` and theme types |
+
+## Reactive Stores
+
+Every utility exposes its state as a store with two methods:
+
+| Method | Description |
+|--------|-------------|
+| `get()` | Returns the current value |
+| `subscribe(listener)` | Calls `listener` immediately with the current value, then on every change. Returns an unsubscribe function. |
+
+This shape follows the Svelte store contract and plugs directly into React's `useSyncExternalStore`, so no adapter library is needed.
+
+You can create your own stores too:
+
+```ts
+import { createSuStore } from '@su-labs/core';
+
+const counter = createSuStore(0);
+const unsubscribe = counter.subscribe((value) => console.log(value)); // logs 0
+counter.set(1); // logs 1
+unsubscribe();
+```
+
+## Theme
+
+Manages light, dark, contrast and custom themes, follows the operating system's `prefers-color-scheme` when set to `'system'`, applies a `data-theme` attribute and CSS variables to `<html>`, and saves the user's choice in `localStorage`.
+
+```ts
+import { SuThemeController } from '@su-labs/core/theme';
+
+const theme = new SuThemeController();
+theme.init({ defaultTheme: 'system' });
+
+theme.theme.subscribe((name) => console.log('Active theme:', name));
+theme.setTheme('dark');
+```
+
+### API
+
+| Member | Description |
+|--------|-------------|
+| `init(config?)` | Applies configuration and the saved or default theme |
+| `setTheme(theme, persist = true)` | Sets `'light'`, `'dark'`, `'contrast'`, `'custom'` or `'system'` |
+| `getTheme()` | Returns the resolved theme (never `'system'`) |
+| `getUserPreference()` | Returns the user's choice (may be `'system'`) |
+| `theme` | Read-only store of the resolved theme |
+| `destroy()` | Stops listening to system theme changes |
+
+### Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `defaultTheme` | `'system'` | Theme used when nothing is saved |
+| `storageKey` | `'su:theme'` | `localStorage` key |
+| `cssVarPrefix` | `'--su-theme-'` | Prefix for the CSS variables |
+| `themes` | — | Per-theme CSS variable overrides, e.g. `{ dark: { background: '#000' } }` |
+
+### CSS Variables
+
+```css
+body {
+  color: var(--su-theme-color);
+  background: var(--su-theme-background);
+}
+
+a {
+  color: var(--su-theme-main-accent);
+}
+```
+
+## License
+
+MIT © 2025 [Yevheniy Alekseyev](https://github.com/Greezaaa)

package/fesm2022/su-labs-core-theme.mjs

@@ -0,0 +1,96 @@
+import { createSuStore, isBrowser } from "@su-labs/core";
+const DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+const DEFAULT_THEMES = {
+	light: {
+		color: "#333",
+		background: "#fff",
+		"main-accent": "#007bff",
+		"second-accent": "#6c757d",
+		"third-accent": "#28a745"
+	},
+	dark: {
+		color: "#f0f0f0",
+		background: "#1a1a1a",
+		"main-accent": "#38a8e1",
+		"second-accent": "#a8b0b5",
+		"third-accent": "#2ee057"
+	},
+	contrast: {
+		color: "#000",
+		background: "#fff",
+		"main-accent": "#ff0000"
+	},
+	custom: {},
+	system: {}
+};
+var SuThemeController = class {
+	config = {};
+	cssVarPrefix = "--su-theme-";
+	storageKey = "su:theme";
+	userPreference = "light";
+	themeStore = createSuStore("light");
+	theme = this.themeStore.asReadonly();
+	systemChangeHandler = null;
+	mediaQuery;
+	init(config) {
+		this.config = {
+			...this.config,
+			...config
+		};
+		this.cssVarPrefix = this.config.cssVarPrefix ?? this.cssVarPrefix;
+		this.storageKey = this.config.storageKey ?? this.storageKey;
+		const savedPreference = isBrowser() ? localStorage.getItem(this.storageKey) : null;
+		this.userPreference = savedPreference ?? this.config.defaultTheme ?? "system";
+		this.setTheme(this.userPreference, false);
+	}
+	getTheme() {
+		return this.themeStore.get();
+	}
+	getUserPreference() {
+		return this.userPreference;
+	}
+	setTheme(theme, persist = true) {
+		if (theme !== "system") this.stopListeningToSystemChanges();
+		this.userPreference = theme;
+		this.applyResolvedTheme(theme === "system" ? this.resolveSystemTheme() : theme);
+		if (persist && isBrowser()) localStorage.setItem(this.storageKey, theme);
+		if (theme === "system") this.listenToSystemChanges();
+	}
+	destroy() {
+		this.stopListeningToSystemChanges();
+	}
+	applyResolvedTheme(theme) {
+		this.themeStore.set(theme);
+		if (!isBrowser()) return;
+		document.documentElement.setAttribute("data-theme", theme);
+		this.applyThemeVariables(theme);
+	}
+	resolveSystemTheme() {
+		return isBrowser() && window.matchMedia(DARK_SCHEME_QUERY).matches ? "dark" : "light";
+	}
+	listenToSystemChanges() {
+		if (this.mediaQuery || !isBrowser()) return;
+		this.mediaQuery = window.matchMedia(DARK_SCHEME_QUERY);
+		this.systemChangeHandler = (event) => {
+			if (this.userPreference === "system") this.applyResolvedTheme(event.matches ? "dark" : "light");
+		};
+		this.mediaQuery.addEventListener("change", this.systemChangeHandler);
+	}
+	stopListeningToSystemChanges() {
+		if (this.mediaQuery && this.systemChangeHandler) {
+			this.mediaQuery.removeEventListener("change", this.systemChangeHandler);
+			this.systemChangeHandler = null;
+			this.mediaQuery = void 0;
+		}
+	}
+	applyThemeVariables(theme) {
+		const variablesToApply = {
+			...DEFAULT_THEMES[theme],
+			...this.config.themes?.[theme] ?? {}
+		};
+		for (const [key, value] of Object.entries(variablesToApply)) if (value) document.documentElement.style.setProperty(`${this.cssVarPrefix}${key}`, value);
+	}
+};
+export { SuThemeController };
+
+//# sourceMappingURL=su-labs-core-theme.mjs.map

package/fesm2022/su-labs-core-theme.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"su-labs-core-theme.mjs","names":[],"sources":["../../../../projects/su-labs/core/theme/src/lib/theme.controller.ts"],"sourcesContent":["import { createSuStore, isBrowser, SuReadableStore } from '@su-labs/core';\nimport { SuThemeConfig, SuThemeName, ThemeCssVariables } from './theme.types';\n\n/** Media query used to detect the operating system's dark mode */\nconst DARK_SCHEME_QUERY = '(prefers-color-scheme: dark)';\n\n/** Default CSS variables applied for each theme unless overridden in the config */\nconst DEFAULT_THEMES: Record<SuThemeName, ThemeCssVariables> = {\n  light: {\n    color: '#333',\n    background: '#fff',\n    'main-accent': '#007bff',\n    'second-accent': '#6c757d',\n    'third-accent': '#28a745',\n  },\n  dark: {\n    color: '#f0f0f0',\n    background: '#1a1a1a',\n    'main-accent': '#38a8e1',\n    'second-accent': '#a8b0b5',\n    'third-accent': '#2ee057',\n  },\n  contrast: {\n    color: '#000',\n    background: '#fff',\n    'main-accent': '#ff0000',\n  },\n  custom: {},\n  system: {},\n};\n\n/**\n * Framework-agnostic theme manager.\n *\n * Resolves the active theme (including 'system'), applies it to the document as a\n * `data-theme` attribute and CSS variables, persists the user's choice in localStorage,\n * and exposes the resolved theme as a reactive store.\n * Safe to import in Node: browser-only work is skipped when there is no DOM.\n */\nexport class SuThemeController {\n  /** Configuration for the theme, provided during initialization */\n  private config: SuThemeConfig = {};\n\n  /** CSS variable prefix, can be customized */\n  private cssVarPrefix = '--su-theme-';\n\n  /** localStorage key for storing user preference, can be customized */\n  private storageKey = 'su:theme';\n\n  /** User selected theme (can be 'system') */\n  private userPreference: SuThemeName = 'light';\n\n  /** Current resolved theme ('light' | 'dark' | 'contrast' | 'custom') */\n  private readonly themeStore = createSuStore<SuThemeName>('light');\n\n  /** Reactive, read-only access to the resolved theme */\n  readonly theme: SuReadableStore<SuThemeName> = this.themeStore.asReadonly();\n\n  /** System media query listener callback */\n  private systemChangeHandler: ((event: MediaQueryListEvent) => void) | null = null;\n\n  /** MediaQueryList instance for system theme changes */\n  private mediaQuery?: MediaQueryList;\n\n  /**\n   * Initialize with optional configuration and apply the saved or default theme.\n   * @param config Optional configuration object.\n   */\n  public init(config?: SuThemeConfig): void {\n    this.config = { ...this.config, ...config };\n    this.cssVarPrefix = this.config.cssVarPrefix ?? this.cssVarPrefix;\n    this.storageKey = this.config.storageKey ?? this.storageKey;\n\n    const savedPreference = isBrowser() ? (localStorage.getItem(this.storageKey) as SuThemeName | null) : null;\n    this.userPreference = savedPreference ?? this.config.defaultTheme ?? 'system';\n\n    this.setTheme(this.userPreference, false);\n  }\n\n  /**\n   * Get the currently active, resolved theme.\n   * @returns The resolved theme name ('light', 'dark', 'contrast', 'custom').\n   */\n  public getTheme(): SuThemeName {\n    return this.themeStore.get();\n  }\n\n  /**\n   * Get the user's theme preference (may be 'system').\n   * @returns The user preference ('light', 'dark', 'contrast', 'custom', 'system').\n   */\n  public getUserPreference(): SuThemeName {\n    return this.userPreference;\n  }\n\n  /**\n   * Set a new theme.\n   * @param theme The theme to set ('light', 'dark', 'contrast', 'custom', 'system').\n   * @param persist Whether to store the preference in localStorage (default: true).\n   */\n  public setTheme(theme: SuThemeName, persist: boolean = true): void {\n    if (theme !== 'system') {\n      this.stopListeningToSystemChanges();\n    }\n\n    this.userPreference = theme;\n    this.applyResolvedTheme(theme === 'system' ? this.resolveSystemTheme() : theme);\n\n    if (persist && isBrowser()) {\n      localStorage.setItem(this.storageKey, theme);\n    }\n\n    if (theme === 'system') {\n      this.listenToSystemChanges();\n    }\n  }\n\n  /** Stop listening to system theme changes and release browser resources */\n  public destroy(): void {\n    this.stopListeningToSystemChanges();\n  }\n\n  /**\n   * Update the store and apply the theme to the document.\n   * @param theme The resolved theme to apply.\n   */\n  private applyResolvedTheme(theme: SuThemeName): void {\n    this.themeStore.set(theme);\n\n    if (!isBrowser()) {\n      return;\n    }\n\n    document.documentElement.setAttribute('data-theme', theme);\n    this.applyThemeVariables(theme);\n  }\n\n  /**\n   * Resolve the current system theme using prefers-color-scheme.\n   * @returns 'dark' if system prefers dark mode, otherwise 'light'.\n   */\n  private resolveSystemTheme(): SuThemeName {\n    return isBrowser() && window.matchMedia(DARK_SCHEME_QUERY).matches ? 'dark' : 'light';\n  }\n\n  /**\n   * Listen to system theme changes and automatically update the theme.\n   * Only active when user preference is 'system'.\n   */\n  private listenToSystemChanges(): void {\n    if (this.mediaQuery || !isBrowser()) {\n      return;\n    }\n\n    this.mediaQuery = window.matchMedia(DARK_SCHEME_QUERY);\n    this.systemChangeHandler = (event: MediaQueryListEvent): void => {\n      if (this.userPreference === 'system') {\n        this.applyResolvedTheme(event.matches ? 'dark' : 'light');\n      }\n    };\n    this.mediaQuery.addEventListener('change', this.systemChangeHandler);\n  }\n\n  /** Stop listening to system theme changes */\n  private stopListeningToSystemChanges(): void {\n    if (this.mediaQuery && this.systemChangeHandler) {\n      this.mediaQuery.removeEventListener('change', this.systemChangeHandler);\n      this.systemChangeHandler = null;\n      this.mediaQuery = undefined;\n    }\n  }\n\n  /**\n   * Apply CSS variables for the given theme, merging defaults with config overrides.\n   * @param theme The theme whose variables should be applied.\n   */\n  private applyThemeVariables(theme: SuThemeName): void {\n    const variablesToApply = {\n      ...DEFAULT_THEMES[theme],\n      ...(this.config.themes?.[theme] ?? {}),\n    };\n\n    for (const [key, value] of Object.entries(variablesToApply)) {\n      if (value) {\n        document.documentElement.style.setProperty(`${this.cssVarPrefix}${key}`, value);\n      }\n    }\n  }\n}\n"],"mappings":";AAIA,MAAM,oBAAoB;AAG1B,MAAM,iBAAyD;CAC7D,OAAO;EACL,OAAO;EACP,YAAY;EACZ,eAAe;EACf,iBAAiB;EACjB,gBAAgB;CACjB;CACD,MAAM;EACJ,OAAO;EACP,YAAY;EACZ,eAAe;EACf,iBAAiB;EACjB,gBAAgB;CACjB;CACD,UAAU;EACR,OAAO;EACP,YAAY;EACZ,eAAe;CAChB;CACD,QAAQ,CAAA;CACR,QAAQ,CAAA;AACT;AAUD,IAAa,oBAAb,MAA8B;CAEpB,SAAwB,CAAA;CAGxB,eAAe;CAGf,aAAa;CAGb,iBAA8B;CAGrB,aAAa,cAA2B,OAAO;CAGvD,QAAsC,KAAK,WAAW,WAAU;CAGjE,sBAAqE;CAGrE;CAMD,KAAK,QAAsB;EAChC,KAAK,SAAS;GAAE,GAAG,KAAK;GAAQ,GAAG;EAAM;EACzC,KAAK,eAAe,KAAK,OAAO,gBAAgB,KAAK;EACrD,KAAK,aAAa,KAAK,OAAO,cAAc,KAAK;EAEjD,MAAM,kBAAkB,UAAS,IAAM,aAAa,QAAQ,KAAK,UAAU,IAA2B;EACtG,KAAK,iBAAiB,mBAAmB,KAAK,OAAO,gBAAgB;EAErE,KAAK,SAAS,KAAK,gBAAgB,KAAK;CAC1C;CAMO,WAAQ;EACb,OAAO,KAAK,WAAW,IAAG;CAC5B;CAMO,oBAAiB;EACtB,OAAO,KAAK;CACd;CAOO,SAAS,OAAoB,UAAmB,MAAI;EACzD,IAAI,UAAU,UACZ,KAAK,6BAA4B;EAGnC,KAAK,iBAAiB;EACtB,KAAK,mBAAmB,UAAU,WAAW,KAAK,mBAAkB,IAAK,KAAK;EAE9E,IAAI,WAAW,UAAS,GACtB,aAAa,QAAQ,KAAK,YAAY,KAAK;EAG7C,IAAI,UAAU,UACZ,KAAK,sBAAqB;CAE9B;CAGO,UAAO;EACZ,KAAK,6BAA4B;CACnC;CAMQ,mBAAmB,OAAkB;EAC3C,KAAK,WAAW,IAAI,KAAK;EAEzB,IAAI,CAAC,UAAS,GACZ;EAGF,SAAS,gBAAgB,aAAa,cAAc,KAAK;EACzD,KAAK,oBAAoB,KAAK;CAChC;CAMQ,qBAAkB;EACxB,OAAO,UAAS,KAAM,OAAO,WAAW,iBAAiB,CAAC,CAAC,UAAU,SAAS;CAChF;CAMQ,wBAAqB;EAC3B,IAAI,KAAK,cAAc,CAAC,UAAS,GAC/B;EAGF,KAAK,aAAa,OAAO,WAAW,iBAAiB;EACrD,KAAK,uBAAuB,UAAoC;GAC9D,IAAI,KAAK,mBAAmB,UAC1B,KAAK,mBAAmB,MAAM,UAAU,SAAS,OAAO;EAE5D;EACA,KAAK,WAAW,iBAAiB,UAAU,KAAK,mBAAmB;CACrE;CAGQ,+BAA4B;EAClC,IAAI,KAAK,cAAc,KAAK,qBAAqB;GAC/C,KAAK,WAAW,oBAAoB,UAAU,KAAK,mBAAmB;GACtE,KAAK,sBAAsB;GAC3B,KAAK,aAAa;EACpB;CACF;CAMQ,oBAAoB,OAAkB;EAC5C,MAAM,mBAAmB;GACvB,GAAG,eAAe;GAClB,GAAI,KAAK,OAAO,SAAS,UAAU,CAAA;EACpC;EAED,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,gBAAgB,GACxD,IAAI,OACF,SAAS,gBAAgB,MAAM,YAAY,GAAG,KAAK,eAAe,OAAO,KAAK;CAGpF;AACD"}

package/fesm2022/su-labs-core.mjs

@@ -0,0 +1,27 @@
+function isBrowser() {
+	return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function createSuStore(initialValue) {
+	let value = initialValue;
+	const listeners = /* @__PURE__ */ new Set();
+	const readonlyStore = {
+		get: () => value,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			listener(value);
+			return () => listeners.delete(listener);
+		}
+	};
+	return {
+		...readonlyStore,
+		set: (nextValue) => {
+			if (Object.is(nextValue, value)) return;
+			value = nextValue;
+			listeners.forEach((listener) => listener(value));
+		},
+		asReadonly: () => readonlyStore
+	};
+}
+export { createSuStore, isBrowser };
+
+//# sourceMappingURL=su-labs-core.mjs.map

package/fesm2022/su-labs-core.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"su-labs-core.mjs","names":[],"sources":["../../../../projects/su-labs/core/src/lib/environment.ts","../../../../projects/su-labs/core/src/lib/store.ts"],"sourcesContent":["/**\n * Whether the code runs in a browser with DOM access.\n * Used to keep utilities safe to import in Node and during server-side rendering.\n */\nexport function isBrowser(): boolean {\n  return typeof window !== 'undefined' && typeof document !== 'undefined';\n}\n","/** Callback invoked with the store's current value */\nexport type SuStoreListener<T> = (value: T) => void;\n\n/** Function returned by `subscribe` that stops the subscription */\nexport type SuUnsubscribe = () => void;\n\n/**\n * Read-only reactive value.\n *\n * `subscribe` calls the listener immediately with the current value and again on every change,\n * which matches the Svelte store contract and works with React's `useSyncExternalStore`.\n */\nexport interface SuReadableStore<T> {\n  /** Get the current value */\n  get(): T;\n\n  /**\n   * Listen to value changes.\n   * @param listener Called immediately with the current value, then on every change.\n   * @returns Function that removes the listener.\n   */\n  subscribe(listener: SuStoreListener<T>): SuUnsubscribe;\n}\n\n/** Reactive value that can be updated */\nexport interface SuWritableStore<T> extends SuReadableStore<T> {\n  /**\n   * Replace the current value and notify listeners if it changed.\n   * @param value The new value.\n   */\n  set(value: T): void;\n\n  /** Read-only view of this store, safe to expose publicly */\n  asReadonly(): SuReadableStore<T>;\n}\n\n/**\n * Create a minimal reactive store with no framework dependencies.\n * @param initialValue The starting value.\n * @returns A writable store.\n */\nexport function createSuStore<T>(initialValue: T): SuWritableStore<T> {\n  let value = initialValue;\n  const listeners = new Set<SuStoreListener<T>>();\n\n  const readonlyStore: SuReadableStore<T> = {\n    get: () => value,\n    subscribe: (listener) => {\n      listeners.add(listener);\n      listener(value);\n      return () => listeners.delete(listener);\n    },\n  };\n\n  return {\n    ...readonlyStore,\n    set: (nextValue) => {\n      if (Object.is(nextValue, value)) {\n        return;\n      }\n      value = nextValue;\n      listeners.forEach((listener) => listener(value));\n    },\n    asReadonly: () => readonlyStore,\n  };\n}\n"],"mappings":"AAIA,SAAgB,YAAS;CACvB,OAAO,OAAO,WAAW,eAAe,OAAO,aAAa;AAC9D;ACmCA,SAAgB,cAAiB,cAAe;CAC9C,IAAI,QAAQ;CACZ,MAAM,4BAAY,IAAI,IAAG;CAEzB,MAAM,gBAAoC;EACxC,WAAW;EACX,YAAY,aAAY;GACtB,UAAU,IAAI,QAAQ;GACtB,SAAS,KAAK;GACd,aAAa,UAAU,OAAO,QAAQ;EACxC;CACD;CAED,OAAO;EACL,GAAG;EACH,MAAM,cAAa;GACjB,IAAI,OAAO,GAAG,WAAW,KAAK,GAC5B;GAEF,QAAQ;GACR,UAAU,SAAS,aAAa,SAAS,KAAK,CAAC;EACjD;EACA,kBAAkB;CACnB;AACH"}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@su-labs/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Framework-agnostic browser utilities (theme, and more to come) with a tiny reactive store. Works with vanilla JS, React, Svelte, Angular or any other framework.",
+  "keywords": [
+    "framework-agnostic",
+    "vanilla-js",
+    "react",
+    "svelte",
+    "angular",
+    "theme",
+    "dark-mode",
+    "css-variables",
+    "store",
+    "reactive",
+    "prefers-color-scheme"
+  ],
+  "homepage": "https://github.com/Greezaaa/settings-utils-lib/tree/main/projects/su-labs/core#readme",
+  "author": {
+    "name": "Yevheniy Alekseyev",
+    "email": "yev.alekseyev@gmail.com",
+    "url": "https://github.com/Greezaaa"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Greezaaa/settings-utils-lib.git",
+    "directory": "projects/su-labs/core"
+  },
+  "bugs": {
+    "url": "https://github.com/Greezaaa/settings-utils-lib/issues"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "module": "fesm2022/su-labs-core.mjs",
+  "typings": "types/su-labs-core.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/su-labs-core.d.ts",
+      "default": "./fesm2022/su-labs-core.mjs"
+    },
+    "./theme": {
+      "types": "./types/su-labs-core-theme.d.ts",
+      "default": "./fesm2022/su-labs-core-theme.mjs"
+    }
+  },
+  "type": "module"
 }

package/types/su-labs-core-theme.d.ts

@@ -0,0 +1,94 @@
+import { SuReadableStore } from "@su-labs/core";
+/** Available theme names */
+export type SuThemeName = 'light' | 'dark' | 'contrast' | 'custom' | 'system';
+/** Theme configuration */
+export interface SuThemeConfig {
+  /** localStorage key for storing selected theme */
+  storageKey?: string;
+  /** CSS variable prefix, applied to all theme variables */
+  cssVarPrefix?: string;
+  /** Default theme if nothing saved in localStorage */
+  defaultTheme?: SuThemeName;
+  /** Optional CSS variable overrides for specific themes */
+  themes?: Partial<Record<SuThemeName, ThemeCssVariables>>;
+}
+/** Available CSS variables for theming */
+export interface ThemeCssVariables {
+  color?: string;
+  background?: string;
+  'main-accent'?: string;
+  'second-accent'?: string;
+  'third-accent'?: string;
+  [key: string]: string | undefined;
+}
+/**
+ * Framework-agnostic theme manager.
+ *
+ * Resolves the active theme (including 'system'), applies it to the document as a
+ * `data-theme` attribute and CSS variables, persists the user's choice in localStorage,
+ * and exposes the resolved theme as a reactive store.
+ * Safe to import in Node: browser-only work is skipped when there is no DOM.
+ */
+export declare class SuThemeController {
+  /** Configuration for the theme, provided during initialization */
+  private config;
+  /** CSS variable prefix, can be customized */
+  private cssVarPrefix;
+  /** localStorage key for storing user preference, can be customized */
+  private storageKey;
+  /** User selected theme (can be 'system') */
+  private userPreference;
+  /** Current resolved theme ('light' | 'dark' | 'contrast' | 'custom') */
+  private readonly themeStore;
+  /** Reactive, read-only access to the resolved theme */
+  readonly theme: SuReadableStore<SuThemeName>;
+  /** System media query listener callback */
+  private systemChangeHandler;
+  /** MediaQueryList instance for system theme changes */
+  private mediaQuery?;
+  /**
+   * Initialize with optional configuration and apply the saved or default theme.
+   * @param config Optional configuration object.
+   */
+  init(config?: SuThemeConfig): void;
+  /**
+   * Get the currently active, resolved theme.
+   * @returns The resolved theme name ('light', 'dark', 'contrast', 'custom').
+   */
+  getTheme(): SuThemeName;
+  /**
+   * Get the user's theme preference (may be 'system').
+   * @returns The user preference ('light', 'dark', 'contrast', 'custom', 'system').
+   */
+  getUserPreference(): SuThemeName;
+  /**
+   * Set a new theme.
+   * @param theme The theme to set ('light', 'dark', 'contrast', 'custom', 'system').
+   * @param persist Whether to store the preference in localStorage (default: true).
+   */
+  setTheme(theme: SuThemeName, persist?: boolean): void;
+  /** Stop listening to system theme changes and release browser resources */
+  destroy(): void;
+  /**
+   * Update the store and apply the theme to the document.
+   * @param theme The resolved theme to apply.
+   */
+  private applyResolvedTheme;
+  /**
+   * Resolve the current system theme using prefers-color-scheme.
+   * @returns 'dark' if system prefers dark mode, otherwise 'light'.
+   */
+  private resolveSystemTheme;
+  /**
+   * Listen to system theme changes and automatically update the theme.
+   * Only active when user preference is 'system'.
+   */
+  private listenToSystemChanges;
+  /** Stop listening to system theme changes */
+  private stopListeningToSystemChanges;
+  /**
+   * Apply CSS variables for the given theme, merging defaults with config overrides.
+   * @param theme The theme whose variables should be applied.
+   */
+  private applyThemeVariables;
+}

package/types/su-labs-core.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Whether the code runs in a browser with DOM access.
+ * Used to keep utilities safe to import in Node and during server-side rendering.
+ */
+export declare function isBrowser(): boolean;
+/** Callback invoked with the store's current value */
+export type SuStoreListener<T> = (value: T) => void;
+/** Function returned by `subscribe` that stops the subscription */
+export type SuUnsubscribe = () => void;
+/**
+ * Read-only reactive value.
+ *
+ * `subscribe` calls the listener immediately with the current value and again on every change,
+ * which matches the Svelte store contract and works with React's `useSyncExternalStore`.
+ */
+export interface SuReadableStore<T> {
+  /** Get the current value */
+  get(): T;
+  /**
+   * Listen to value changes.
+   * @param listener Called immediately with the current value, then on every change.
+   * @returns Function that removes the listener.
+   */
+  subscribe(listener: SuStoreListener<T>): SuUnsubscribe;
+}
+/** Reactive value that can be updated */
+export interface SuWritableStore<T> extends SuReadableStore<T> {
+  /**
+   * Replace the current value and notify listeners if it changed.
+   * @param value The new value.
+   */
+  set(value: T): void;
+  /** Read-only view of this store, safe to expose publicly */
+  asReadonly(): SuReadableStore<T>;
+}
+/**
+ * Create a minimal reactive store with no framework dependencies.
+ * @param initialValue The starting value.
+ * @returns A writable store.
+ */
+export declare function createSuStore<T>(initialValue: T): SuWritableStore<T>;