@veams/status-quo 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -4,11 +4,55 @@ 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.1.0/).
 
+## [1.2.0] - 2026-02-25
+
+### Added
+- New composable hook APIs:
+  - `useStateHandler(factory, params?)`
+  - `useStateActions(handler)`
+  - `useStateSubscription(source, selector?, isEqual?)`
+- Selector + equality support across shortcut hooks:
+  - `useStateFactory(factory, selector?, isEqual?, params?)`
+  - `useStateSingleton(singleton, selector?, isEqual?)`
+- `StateSingletonOptions` with `destroyOnNoConsumers?: boolean` (default: `true`).
+- Ref-counted singleton lifecycle handling so shared singleton instances are only destroyed when the last consumer unmounts.
+- New hook test coverage for:
+  - composed API usage (`useStateHandler + useStateActions + useStateSubscription`)
+  - selector subscriptions with and without custom equality
+  - singleton subscription behavior and `destroyOnNoConsumers: false`
+  - full-snapshot subscription behavior.
+
+### Changed
+- `useStateFactory` now composes `useStateHandler` + `useStateSubscription` internally.
+- `useStateSubscription` now:
+  - accepts either `StateSubscriptionHandler` or `StateSingleton`
+  - returns `[selectedState, actions]`
+  - supports selector/equality without requiring separate selector-specific hook APIs.
+- `useStateSingleton` is now a shortcut over `useStateSubscription(singleton, selector?, isEqual?)`.
+- `makeStateSingleton` now accepts options and manages instance destruction through explicit lifecycle controls.
+- Public exports extended:
+  - Added `useStateHandler`, `useStateActions`, `useStateSubscription`
+  - Added exported `StateSingletonOptions` type.
+- Observable handler naming aligned with signal convention:
+  - Added `getObservable(key)` as the canonical API.
+
+### Deprecated
+- `ObservableStateHandler#getObservableItem(key)` is now deprecated in favor of `getObservable(key)`.
+
+### Documentation
+- README rewritten with a dedicated API guide that documents base composition, shortcut composition, singleton lifecycle options, and usage examples.
+- Playground documentation significantly expanded:
+  - dedicated API section grouped by base composition, shortcut composition, and helper functions
+  - clearer singleton lifecycle explanation and examples
+  - improved card hierarchy and spacing for readability
+  - responsive/toggleable navigation for better mobile usage.
+
 ## [1.0.0] - 2026-02-17
 
 ### Added
 - `SignalStateHandler` (signals-backed state handler).
 - `BaseStateHandler` to share devtools and lifecycle APIs.
+- `bindSubscribable` helper for managing external subscriptions.
 - Playground/demo with GitHub Pages deployment.
 
 ### Changed
@@ -26,4 +70,5 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   - From: `super({ initialState, devTools: { ... } })`
   - To: `super({ initialState, options: { devTools: { ... } } })`
 
+[1.2.0]: https://github.com/Veams/status-quo/compare/v1.0.0...v1.2.0
 [1.0.0]: https://github.com/Veams/status-quo/releases/tag/v1.0.0

package/README.md

@@ -1,193 +1,483 @@
-# Status Quo (`@veams/status-quo`)
+<center>
+<img src="assets/statusquo-logo.png" width="200" alt="StatusQuo Logo" style="margin: 0 auto;">
+</center>
 
-The `Manager` to rule your state.
+# @veams/status-quo 
+[![npm version](https://img.shields.io/npm/v/@veams/status-quo)](https://www.npmjs.com/package/@veams/status-quo)
 
----
+The manager to rule your state.
 
-## Table of Content
+This page mirrors the demo content and adds a full API reference.
 
-1. [Getting Started](#getting-started)
-2. [Example](#example)
+## Table of Contents
 
----
+1. [Overview](#overview)
+2. [Philosophy](#philosophy)
+3. [Demo](#demo)
+4. [Quickstart](#quickstart)
+5. [Handlers](#handlers)
+6. [Hooks](#hooks)
+7. [Singletons](#singletons)
+8. [Composition](#composition)
+9. [API Guide](#api-guide)
+10. [Devtools](#devtools)
+11. [Cleanup](#cleanup)
+12. [API Reference](#api-reference)
+13. [Migration](#migration)
 
-## Getting Started
+## Overview
 
-1. Create your own state handler which handles all the streams and a state you expose next to the actions
-1. Use actions and state in your component
-1. When using React, initialize the state handler with a custom hook called `useStateFactory()` (or `useStateSingleton()` for Singleton states)
+StatusQuo is a small, framework-agnostic state layer that focuses on explicit lifecycle, clear action APIs, and a minimal subscription surface. It ships two handler implementations with the same public interface: RxJS-backed observables and signals-backed stores.
 
+## Philosophy
 
-These three steps are necessary to create a completely decoupled state management solution without the need of creating custom hooks with `useEffect()`.
-
-__Note__: 
-_Please keep in mind that dependencies for the hook needs to be flattened and cannot be used as an object due to how React works._
+- Swap the engine, keep the API. Your UI code stays the same when you switch from RxJS to Signals.
+- Separate view and state. Handlers own transitions and expose actions; views subscribe to snapshots.
+- Framework-agnostic core. Business logic lives outside the UI library; hooks provide the glue.
 
 ## Demo
 
 Live docs and demo:
 
-```
-https://veams.github.io/status-quo/
-```
-
-## Handlers
+[https://veams.github.io/status-quo/](https://veams.github.io/status-quo/)
 
-Status Quo ships two handler implementations with the same public interface:
+## Quickstart
 
-- `ObservableStateHandler` (RxJS-backed)
-- `SignalStateHandler` (Signals-backed)
+Install:
 
-## Example
+```bash
+npm install @veams/status-quo rxjs @preact/signals-core
+```
 
-Let's start with a simple state example. 
-You should start with the abstract class `ObservableStateHandler`:
+Create a store and use it in a component:
 
 ```ts
-import { useStateFactory, ObservableStateHandler } from '@veams/status-quo';
+import { ObservableStateHandler, useStateFactory } from '@veams/status-quo';
+
+type CounterState = { count: number };
 
-type CounterState = {
-  count: number;
-};
 type CounterActions = {
   increase: () => void;
   decrease: () => void;
 };
 
-class CounterStateHandler extends ObservableStateHandler<CounterState, CounterActions> {
-  constructor([startCount = 0]) {
-    super({ initialState: { count: startCount } });
+class CounterStore extends ObservableStateHandler<CounterState, CounterActions> {
+  constructor() {
+    super({ initialState: { count: 0 } });
   }
-  
-  getActions() {
+
+  getActions(): CounterActions {
     return {
-      increase() {
-        this.setState({
-          count: this.getState() + 1
-        })
-      },
-      decrease() {
-        const currentState = this.getState();
-
-        if (currentState.count > 0) {
-          this.setState({
-            count: currentState - 1
-          })
-        }
-      }
-    }
+      increase: () => this.setState({ count: this.getState().count + 1 }),
+      decrease: () => this.setState({ count: this.getState().count - 1 }),
+    };
   }
 }
 
-export function CounterStateFactory(...args) {
-  return new CounterStateHandler(...args);
-}
+const [state, actions] = useStateFactory(() => new CounterStore(), []);
 ```
 
-This can be used in our factory hook function:
+## Handlers
 
-```tsx
-import { useStateFactory } from '@veams/status-quo';
-import { CounterStateFactory } from './counter.state.js';
+StatusQuo provides two handler implementations with the same public interface:
 
-const Counter = () => {
-  const [state, actions] = useStateFactory(CounterStateFactory, [0]);
-  
-  return (
-    <div>
-      <h2>Counter: {state}</h2>
-      <button onClick={actions.increase}>Increase</button>
-      <button onClick={actions.decrease}>Decrease</button>
-    </div>
-  )
-}
+- `ObservableStateHandler` (RxJS-backed)
+- `SignalStateHandler` (Signals-backed)
+
+Both are built on `BaseStateHandler`, which provides the shared lifecycle and devtools support.
+
+## Hooks
+
+Use `useStateHandler + useStateActions + useStateSubscription` as the base composition.
+`useStateFactory` and `useStateSingleton` are shortcut APIs over that composition.
+For full signatures and practical examples, see [API Guide](#api-guide).
+
+- `useStateHandler(factory, params)`
+  - Creates and memoizes one handler instance per component.
+- `useStateActions(handler)`
+  - Returns actions without subscribing to state.
+- `useStateSubscription(handlerOrSingleton, selector?, isEqual?)`
+  - Subscribes to full state or a selected slice and returns `[state, actions]`.
+- `useStateFactory(factory, selector?, isEqual?, params?)`
+  - Shortcut for `useStateHandler + useStateSubscription`.
+- `useStateSingleton(singleton, selector?, isEqual?)`
+  - Shortcut for `useStateSubscription(singleton, selector?, isEqual?)`.
+
+Recommended composition:
+
+```ts
+const handler = useStateHandler(createUserStore, []);
+const actions = useStateActions(handler);
+const [name] = useStateSubscription(handler, (state) => state.user.name);
+
+const [singletonName] = useStateSubscription(UserSingleton, (state) => state.user.name);
 ```
 
-**What about singletons?**
+## Singletons
 
-Therefore, you can use a simple singleton class or use `makeStateSingleton()` and pass it later on to the singleton hook function:
+Use singletons for shared state across multiple components.
 
 ```ts
-import { makeStateSingleton } from '@veams/status-quo';
+import { makeStateSingleton, useStateSingleton } from '@veams/status-quo';
+
+// Default behavior: singleton is destroyed when the last consumer unmounts.
+const CounterSingleton = makeStateSingleton(() => new CounterStore());
+
+const [state, actions] = useStateSingleton(CounterSingleton);
+```
 
-import { CounterStateHandler } from './counter.state.js';
+Keep a singleton instance alive across unmounts:
 
-export const CounterStateManager = makeStateSingleton(() => new CounterStateHandler([0]))
+```ts
+const PersistentCounterSingleton = makeStateSingleton(() => new CounterStore(), {
+  destroyOnNoConsumers: false,
+});
 ```
 
-```tsx
-import { useStateSingleton } from '@veams/status-quo';
-import { CounterStateManager } from './counter.singleton.js';
+Use this for app-level stores that should survive route/component unmounts. Keep the default for stores that should release resources when unused.
+
+## Composition
+
+Use only the slice you need. RxJS makes multi-source composition powerful and declarative with operators like `combineLatest`, `switchMap`, or `debounceTime`. Signals can derive values with `computed` and wire them into a parent store via `bindSubscribable`.
+
+```ts
+import { combineLatest } from 'rxjs';
+
+// RxJS: combine handler streams (RxJS shines here)
+class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
+  private counter$ = CounterObservableStore.getInstance().getStateAsObservable();
+  private card$ = new CardObservableHandler();
+
+  constructor() {
+    super({ initialState: { counter: 0, cardTitle: '' }});
+
+    this.subscriptions.push(
+      combineLatest([
+        this.counter$,
+        this.card$,
+      ]).subscribe(([counterState, cardState]) => {
+        this.setState({
+          counter: counterState,
+          cardTitle: cardState.title,
+        }, 'sync-combined');
+      })
+    )
+  }
 
-const GlobalCounterHandler = () => {
-  const [_, actions] = useStateSingleton(CounterStateManager);
-  
-  return (
-    <div>
-      <button onClick={actions.increase}>Increase</button>
-      <button onClick={actions.decrease}>Decrease</button>
-    </div>
-  )
 }
 
-const GlobalCounterDisplay = () => {
-  const [state] = useStateSingleton(CounterStateManager);
-  
-  return (
-    <div>
-      <h2>Counter: {state}</h2>
-    </div>
-  )
+// Signals: combine derived values via computed + bindSubscribable
+import { computed } from '@preact/signals-core';
+
+class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
+  private counter = CounterSignalHandler.getInstance();
+  private card = new CardSignalHandler();
+  private combined$ = computed(() => ({
+    counter: this.counter.getSignal().value,
+    cardTitle: this.card.getSignal().value.title,
+  }));
+
+  constructor() {
+    super({ initialState: { counter: 0, cardTitle: '' }});
+
+    this.bindSubscribable(
+      { subscribe: this.combined.subscribe.bind(this.combined), getSnapshot: () => this.combined.value },
+      (nextState) => this.setState(nextState, 'sync-combined')
+    );
+  }
 }
 ```
 
-### What about debugging? 
+## API Guide
+
+This section documents the primary public API with behavior notes and usage examples.
+
+### `useStateHandler(factory, params?)`
+
+Creates one handler instance per component mount and returns it.
+
+- `factory`: function returning a `StateSubscriptionHandler`
+- `params`: optional factory params tuple
+- lifecycle note: params are applied when the handler instance is created for that mount
+
+```ts
+const handler = useStateHandler(createUserStore, []);
+```
+
+### `useStateActions(handler)`
+
+Returns actions from a handler without subscribing to state changes.
+Use this in action-only components to avoid rerenders from state updates.
+
+```ts
+const handler = useStateHandler(createUserStore, []);
+const actions = useStateActions(handler);
+```
+
+### `useStateSubscription(source, selector?, isEqual?)`
+
+Subscribes to either a handler instance or a singleton and returns `[selectedState, actions]`.
+
+- `source`: `StateSubscriptionHandler` or `StateSingleton`
+- `selector`: optional projection function; defaults to identity
+- `isEqual`: optional equality function; defaults to `Object.is`
+
+Full snapshot subscription:
+
+```ts
+const handler = useStateHandler(createUserStore, []);
+const [state, actions] = useStateSubscription(handler);
+```
+
+Selector subscription:
+
+```ts
+const [name, actions] = useStateSubscription(
+  handler,
+  (state) => state.user.name
+);
+```
+
+Selector with custom equality:
+
+```ts
+const [profile] = useStateSubscription(
+  handler,
+  (state) => state.user.profile,
+  (current, next) => current.id === next.id && current.role === next.role
+);
+```
+
+Singleton source:
+
+```ts
+const [session, actions] = useStateSubscription(SessionSingleton);
+```
+
+Lifecycle note for singleton sources:
+- Consumers are ref-counted.
+- The singleton instance is only destroyed when the last consumer unmounts and `destroyOnNoConsumers !== false`.
+
+### `useStateFactory(factory, selector?, isEqual?, params?)`
+
+Shortcut API for `useStateHandler + useStateSubscription`.
+
+- `useStateFactory(factory, params)`
+- `useStateFactory(factory, selector, params)`
+- `useStateFactory(factory, selector, isEqual, params)`
+
+```ts
+const [state, actions] = useStateFactory(createUserStore, []);
+const [name] = useStateFactory(createUserStore, (state) => state.user.name, []);
+const [profile] = useStateFactory(
+  createUserStore,
+  (state) => state.user.profile,
+  (current, next) => current.id === next.id,
+  []
+);
+```
+
+### `makeStateSingleton(factory, options?)`
 
-You know redux-devtools? You like it? We covered you (at least a bit)!
-You can enable the devtools in an easy way: 
+Creates a shared singleton provider for a handler instance.
 
 ```ts
+const UserSingleton = makeStateSingleton(() => new UserStore());
+```
+
+Options:
+
+```ts
+type StateSingletonOptions = {
+  destroyOnNoConsumers?: boolean; // default: true
+};
+```
+
+- `true` (default): destroy instance after last consumer unmounts
+- `false`: keep instance alive across periods with zero consumers
+
+```ts
+const PersistentUserSingleton = makeStateSingleton(() => new UserStore(), {
+  destroyOnNoConsumers: false,
+});
+```
+
+### `useStateSingleton(singleton, selector?, isEqual?)`
 
-class CounterStateHandler extends ObservableStateHandler<CounterState, CounterActions> {
-  constructor([startCount = 0]) {
+Shortcut API for `useStateSubscription(singleton, selector?, isEqual?)`.
+
+```ts
+const [state, actions] = useStateSingleton(UserSingleton);
+const [name] = useStateSingleton(UserSingleton, (state) => state.user.name);
+```
+
+## Devtools
+
+Enable Redux Devtools integration with `options.devTools`:
+
+```ts
+class CounterStore extends ObservableStateHandler<CounterState, CounterActions> {
+  constructor() {
     super({
-      initialState: { count: startCount },
-      options: {
-        devTools: { enabled: true, namespace: 'Counter' },
-      },
+      initialState: { count: 0 },
+      options: { devTools: { enabled: true, namespace: 'Counter' } },
     });
   }
+}
+```
 
-  getActions() {
-    return {
-      increase() {
-        this.setState(
-          {
-            count: this.getState() + 1,
-          },
-          'increase'
-        );
-      },
-      decrease() {
-        const currentState = this.getState();
-
-        if (currentState.count > 0) {
-          this.setState(
-            {
-              count: currentState - 1,
-            },
-            'decrease'
-          );
-        }
-      },
-    };
-  }
+## Cleanup
+
+Handlers expose `subscribe`, `getSnapshot`, and `destroy` for custom integrations:
+
+```ts
+const unsubscribe = store.subscribe(() => {
+  console.log(store.getSnapshot());
+});
+
+unsubscribe();
+store.destroy();
+```
+
+## API Reference
+
+### `StateSubscriptionHandler<V, A>`
+
+Required interface implemented by all handlers.
+
+```ts
+interface StateSubscriptionHandler<V, A> {
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => V;
+  destroy: () => void;
+  getInitialState: () => V;
+  getActions: () => A;
 }
+```
+
+### `BaseStateHandler<S, A>`
+
+Shared base class for all handlers.
+
+Constructor:
+
+```ts
+protected constructor(initialState: S)
+```
+
+Public methods:
+
+- `getInitialState(): S`
+- `getState(): S`
+- `getSnapshot(): S`
+- `setState(next: Partial<S>, actionName = 'change'): void`
+- `subscribe(listener: () => void): () => void` (abstract)
+- `destroy(): void`
+- `getActions(): A` (abstract)
+
+Protected helpers:
+
+- `getStateValue(): S` (abstract)
+- `setStateValue(next: S): void` (abstract)
+- `initDevTools(options?: { enabled?: boolean; namespace: string }): void`
+- `bindSubscribable<T>(service: { subscribe: (listener: (value: T) => void) => () => void; getSnapshot?: () => T }, onChange: (value: T) => void): void`
+  - Registers the subscription on `this.subscriptions` and invokes `onChange` with the current snapshot when available.
+
+### `ObservableStateHandler<S, A>`
+
+RxJS-backed handler. Extends `BaseStateHandler`.
+
+Constructor:
+
+```ts
+protected constructor({
+  initialState,
+  options
+}: {
+  initialState: S;
+  options?: {
+    devTools?: { enabled?: boolean; namespace: string };
+  };
+})
+```
+
+Public methods:
+
+- `getStateAsObservable(options?: { useDistinctUntilChanged?: boolean }): Observable<S>`
+- `getStateItemAsObservable(key: keyof S): Observable<S[keyof S]>`
+- `getObservable(key: keyof S): Observable<S[keyof S]>`
+- `subscribe(listener: () => void): () => void`
+
+Notes:
+- The observable stream uses `distinctUntilChanged` by default (JSON compare).
+- `subscribe` does not fire for the initial value; it only fires on subsequent changes.
+
+### `SignalStateHandler<S, A>`
+
+Signals-backed handler. Extends `BaseStateHandler`.
+
+Constructor:
+
+```ts
+protected constructor({
+  initialState,
+  options
+}: {
+  initialState: S;
+  options?: {
+    devTools?: { enabled?: boolean; namespace: string };
+    useDistinctUntilChanged?: boolean;
+  };
+})
+```
+
+Public methods:
+
+- `getSignal(): Signal<S>`
+- `subscribe(listener: () => void): () => void`
+
+Notes:
+- `useDistinctUntilChanged` defaults to `true` (JSON compare).
+
+### `makeStateSingleton`
+
+```ts
+type StateSingletonOptions = {
+  destroyOnNoConsumers?: boolean; // default: true
+};
 
-export function CounterStateFactory(...args) {
-  return new CounterStateHandler(...args);
+function makeStateSingleton<S, A>(
+  factory: () => StateSubscriptionHandler<S, A>,
+  options?: StateSingletonOptions
+): {
+  getInstance: () => StateSubscriptionHandler<S, A>;
 }
 ```
 
-We just added the `options.devTools` option and also updated the `setState()` function by passing a second argument into it which is the actions name.
-Now you can open up the the browser extension and you are able to take a look at your actions and state(s).
+Lifecycle behavior:
+- `destroyOnNoConsumers: true` (default): destroy and recreate singleton instances with mount lifecycle.
+- `destroyOnNoConsumers: false`: keep the same singleton instance alive when no component is subscribed.
+
+### Hooks
+
+- `useStateHandler<V, A, P extends unknown[]>(factory: (...args: P) => StateSubscriptionHandler<V, A>, params?: P)`
+  - Returns `StateSubscriptionHandler<V, A>`.
+- `useStateActions<V, A>(handler: StateSubscriptionHandler<V, A>)`
+  - Returns `A`.
+- `useStateSubscription<V, A, Sel = V>(source: StateSubscriptionHandler<V, A> | StateSingleton<V, A>, selector?: (state: V) => Sel, isEqual?: (current: Sel, next: Sel) => boolean)`
+  - Returns `[state, actions]`.
+- `useStateFactory<V, A, P extends unknown[], Sel = V>(factory: (...args: P) => StateSubscriptionHandler<V, A>, selector?: (state: V) => Sel, isEqual?: (current: Sel, next: Sel) => boolean, params?: P)`
+  - Returns `[state, actions]`.
+- `useStateSingleton<V, A, Sel = V>(singleton: StateSingleton<V, A>, selector?: (state: V) => Sel, isEqual?: (current: Sel, next: Sel) => boolean)`
+  - Returns `[state, actions]`.
+
+## Migration
+
+From pre-1.0 releases:
+
+1. Rename `StateHandler` -> `ObservableStateHandler`.
+2. Implement `subscribe()` and `getSnapshot()` on custom handlers.
+3. Replace `getObservable()` usage with `subscribe()` in custom integrations.
+4. Update devtools config:
+   - From: `super({ initialState, devTools: { ... } })`
+   - To: `super({ initialState, options: { devTools: { ... } } })`

package/dist/hooks/__tests__/state-selector.spec.d.ts

@@ -0,0 +1,4 @@
+declare global {
+    var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+export {};