@veams/status-quo 0.1.0 → 1.1.0

package/playground/src/styles.css

@@ -0,0 +1,411 @@
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap');
+
+:root {
+  color-scheme: light;
+  --bg: #f3f2ee;
+  --bg-strong: #e6e1d8;
+  --card: #ffffff;
+  --ink: #1b1b1f;
+  --muted: #5c5c66;
+  --accent: #2f6bff;
+  --accent-soft: #c9d8ff;
+  --accent-2: #ff9f1c;
+  --shadow: 0 18px 45px -30px rgba(0, 0, 0, 0.45);
+  --radius-lg: 28px;
+  --radius-md: 18px;
+  --radius-sm: 12px;
+  --panel-dark: #0e1116;
+  font-family: 'Space Grotesk', system-ui, -apple-system, sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  color: var(--ink);
+  background:
+    radial-gradient(circle at 20% 20%, rgba(47, 107, 255, 0.18), transparent 55%),
+    radial-gradient(circle at 80% 0%, rgba(255, 159, 28, 0.2), transparent 50%),
+    linear-gradient(160deg, var(--bg), var(--bg-strong));
+}
+
+#root {
+  min-height: 100vh;
+}
+
+.app {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 56px 28px 72px;
+  display: flex;
+  flex-direction: column;
+  gap: 40px;
+}
+
+.brand-bar {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  font-weight: 600;
+  justify-content: center;
+  width: 100%;
+}
+
+.brand-logo {
+  width: 260px;
+  height: auto;
+  display: block;
+}
+
+.nav {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 10px 6px;
+}
+
+.nav-links {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+  padding: 6px 12px;
+  background: rgba(255, 255, 255, 0.7);
+  border-radius: 999px;
+  border: 1px solid rgba(27, 27, 31, 0.1);
+  box-shadow: var(--shadow);
+}
+
+.nav-links a {
+  text-decoration: none;
+  color: var(--ink);
+  font-weight: 500;
+  padding: 6px 12px;
+  border-radius: 999px;
+  transition: background 0.2s ease, color 0.2s ease;
+}
+
+.nav-links a:hover {
+  background: rgba(47, 107, 255, 0.12);
+  color: var(--accent);
+}
+
+.hero {
+  display: grid;
+  gap: 16px;
+  padding: 32px 34px;
+  background: rgba(255, 255, 255, 0.75);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow);
+  border: 1px solid rgba(27, 27, 31, 0.08);
+  backdrop-filter: blur(14px);
+  animation: fade-up 0.6s ease both;
+}
+
+.hero.intro {
+  gap: 18px;
+}
+
+h1 {
+  font-size: clamp(2rem, 1.6vw + 1.4rem, 2.8rem);
+  line-height: 1.15;
+  margin: 0;
+}
+
+h2 {
+  margin: 0;
+  font-size: 1.4rem;
+}
+
+h3 {
+  margin: 0 0 8px;
+}
+
+p {
+  margin: 0;
+  color: var(--muted);
+  line-height: 1.6;
+
+  span {
+    font-family: monospace;
+    font-weight: 700;
+    font-size: .9rem;
+  }
+}
+
+.muted {
+  color: var(--muted);
+}
+
+.eyebrow {
+  font-family: 'IBM Plex Mono', ui-monospace, SFMono-Regular, monospace;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  font-size: 0.7rem;
+  color: var(--muted);
+  margin-bottom: 10px;
+}
+
+.subtext {
+  max-width: 600px;
+}
+
+.hero .subtext {
+  margin-top: 12px;
+}
+
+.hero .subtext + .subtext {
+  margin-top: 10px;
+}
+
+.grid {
+  display: grid;
+  gap: 24px;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+}
+
+.doc-section {
+  display: grid;
+  gap: 18px;
+  padding: 28px;
+  border-radius: var(--radius-md);
+  background: rgba(255, 255, 255, 0.85);
+  border: 1px solid rgba(27, 27, 31, 0.08);
+  box-shadow: var(--shadow);
+}
+
+.doc-copy {
+  display: grid;
+  gap: 10px;
+}
+
+.doc-snippets {
+  display: grid;
+  gap: 12px;
+}
+
+.singleton-grid {
+  display: grid;
+  gap: 20px;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+}
+
+.singleton-card {
+  background: #fff;
+  border-radius: var(--radius-md);
+  padding: 22px;
+  border: 1px solid rgba(27, 27, 31, 0.08);
+  box-shadow: var(--shadow);
+  display: grid;
+  gap: 14px;
+}
+
+.singleton-count {
+  font-size: 2.4rem;
+  font-weight: 700;
+  color: var(--ink);
+  background: var(--bg-strong);
+  border-radius: var(--radius-sm);
+  padding: 10px 16px;
+  width: fit-content;
+}
+
+.singleton-count.highlight {
+  background: rgba(47, 107, 255, 0.16);
+  color: var(--accent);
+}
+
+.singleton-hint {
+  font-size: 0.85rem;
+  color: var(--muted);
+}
+
+.guide {
+  display: grid;
+  gap: 20px;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+}
+
+.philosophy-grid {
+  display: grid;
+  gap: 20px;
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+}
+
+.philosophy-card {
+  background: #fff;
+  border-radius: var(--radius-md);
+  border: 1px solid rgba(27, 27, 31, 0.08);
+  box-shadow: var(--shadow);
+  overflow: hidden;
+  display: grid;
+  gap: 16px;
+}
+
+.philosophy-card img {
+  width: 100%;
+  height: 190px;
+  object-fit: cover;
+  background: var(--panel-dark);
+}
+
+.philosophy-card div {
+  padding: 0 20px 22px;
+  display: grid;
+  gap: 8px;
+}
+
+.guide-card {
+  background: rgba(255, 255, 255, 0.85);
+  border-radius: var(--radius-md);
+  padding: 22px;
+  border: 1px solid rgba(27, 27, 31, 0.08);
+  box-shadow: var(--shadow);
+  display: grid;
+  gap: 16px;
+}
+
+.code-block.compact {
+  font-size: 0.75rem;
+  padding: 12px 14px;
+}
+
+.card {
+  background: var(--card);
+  border-radius: var(--radius-md);
+  padding: 24px;
+  box-shadow: var(--shadow);
+  border: 1px solid rgba(27, 27, 31, 0.08);
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  animation: fade-up 0.6s ease both;
+}
+
+.card:nth-child(2) {
+  animation-delay: 0.1s;
+}
+
+.card-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.count-chip {
+  background: var(--accent-soft);
+  color: var(--accent);
+  border-radius: 999px;
+  padding: 6px 14px;
+  font-weight: 600;
+  font-size: 1rem;
+}
+
+.count-display {
+  display: grid;
+  gap: 8px;
+  padding: 16px;
+  border-radius: var(--radius-sm);
+  background: linear-gradient(120deg, rgba(47, 107, 255, 0.1), rgba(255, 159, 28, 0.08));
+}
+
+.code-block {
+  margin: 0;
+  padding: 16px 18px;
+  border-radius: var(--radius-sm);
+  background: #12131a;
+  color: #f0f2ff;
+  font-family: 'IBM Plex Mono', ui-monospace, SFMono-Regular, monospace;
+  font-size: 0.8rem;
+  line-height: 1.5;
+  overflow-x: auto;
+  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.08);
+}
+
+.code-block code {
+  font-family: inherit;
+}
+
+.count-label {
+  font-size: 0.85rem;
+  color: var(--muted);
+}
+
+.count-value {
+  font-size: 2.6rem;
+  font-weight: 700;
+}
+
+.actions {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(110px, 1fr));
+  gap: 10px;
+}
+
+.btn {
+  border: 1px solid rgba(27, 27, 31, 0.18);
+  border-radius: 999px;
+  padding: 10px 14px;
+  font: inherit;
+  background: #fff;
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease, border 0.2s ease;
+}
+
+.btn:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 10px 20px -14px rgba(27, 27, 31, 0.4);
+}
+
+.btn.primary {
+  background: var(--accent);
+  color: #fff;
+  border-color: transparent;
+}
+
+.btn.ghost {
+  background: transparent;
+  color: var(--ink);
+}
+
+@keyframes fade-up {
+  from {
+    opacity: 0;
+    transform: translateY(12px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (max-width: 720px) {
+  .app {
+    padding: 40px 20px 60px;
+  }
+
+  .nav {
+    padding: 0;
+  }
+
+  .nav-links {
+    border-radius: var(--radius-md);
+  }
+
+  .doc-section {
+    padding: 22px;
+  }
+
+  .hero {
+    padding: 26px;
+  }
+
+  .footer-card {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+}

package/playground/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@veams/status-quo": ["../src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/playground/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { fileURLToPath, URL } from 'node:url';
+
+export default defineConfig({
+  root: fileURLToPath(new URL('.', import.meta.url)),
+  base: './',
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@veams/status-quo': fileURLToPath(new URL('../src/index.ts', import.meta.url)),
+    },
+  },
+  build: {
+    outDir: fileURLToPath(new URL('../docs', import.meta.url)),
+    emptyOutDir: true,
+  },
+});

package/src/hooks/state-subscription.tsx

@@ -1,25 +1,32 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useSyncExternalStore } from 'react';
 
 import type { StateSubscriptionHandler } from '../types/types.js';
-import type { SetStateAction } from 'react';
+type Listener = () => void;
 
 export function useStateSubscription<V, A>(
   stateSubscriptionHandler: StateSubscriptionHandler<V, A>
 ) {
-  const [state, setSubscriptionState] = useState<SetStateAction<V>>(
-    stateSubscriptionHandler.getInitialState()
+  const subscribe = useCallback(
+    (listener: Listener) => {
+      const unsubscribe = stateSubscriptionHandler.subscribe(listener);
+
+      return () => {
+        unsubscribe();
+        stateSubscriptionHandler.destroy();
+      };
+    },
+    [stateSubscriptionHandler]
   );
 
-  useEffect(() => {
-    const state$ = stateSubscriptionHandler.getObservable().subscribe((data) => {
-      setSubscriptionState(data);
-    });
+  const getSnapshot = useCallback(
+    () => stateSubscriptionHandler.getSnapshot(),
+    [stateSubscriptionHandler]
+  );
 
-    return () => {
-      state$.unsubscribe();
-      return stateSubscriptionHandler.destroy();
-    };
-  }, [stateSubscriptionHandler]);
+  const getServerSnapshot = useCallback(
+    () => stateSubscriptionHandler.getInitialState(),
+    [stateSubscriptionHandler]
+  );
 
-  return state;
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }

package/src/index.ts

@@ -1,9 +1,21 @@
 import { useStateFactory, useStateSingleton } from './hooks/index.js';
-import { makeStateSingleton, StateHandler } from './store/index.js';
+import {
+  BaseStateHandler,
+  makeStateSingleton,
+  ObservableStateHandler,
+  SignalStateHandler,
+} from './store/index.js';
 
 import type { StateSingleton } from './store/index.js';
 import type { StateSubscriptionHandler } from './types/types.js';
 
-export { makeStateSingleton, StateHandler, useStateFactory, useStateSingleton };
+export {
+  BaseStateHandler,
+  makeStateSingleton,
+  ObservableStateHandler,
+  SignalStateHandler,
+  useStateFactory,
+  useStateSingleton,
+};
 
 export type { StateSingleton, StateSubscriptionHandler };

package/src/store/__tests__/{state-handler.spec.ts → observable-state-handler.spec.ts}

@@ -1,8 +1,8 @@
 import { lastValueFrom, Subject, take } from 'rxjs';
 
-import { StateHandler } from '../state-handler.js';
+import { ObservableStateHandler } from '../observable-state-handler.js';
 
-class TestStateHandler extends StateHandler<
+class TestObservableStateHandler extends ObservableStateHandler<
   { test: string; test2: string },
   { testAction: () => void }
 > {
@@ -13,18 +13,16 @@ class TestStateHandler extends StateHandler<
         test2: 'testValue2',
       },
       ...(withDevTools && {
-        devTools: {
-          enabled: true,
-          namespace: 'TestStateHandler',
+        options: {
+          devTools: {
+            enabled: true,
+            namespace: 'TestObservableStateHandler',
+          },
         },
       }),
     });
   }
 
-  getObservable() {
-    return this.getStateAsObservable();
-  }
-
   getActions(): { testAction: () => void } {
     return {
       testAction: () => {
@@ -34,11 +32,11 @@ class TestStateHandler extends StateHandler<
   }
 }
 
-describe('State Handler', () => {
-  let stateHandler: TestStateHandler;
+describe('Observable State Handler', () => {
+  let stateHandler: TestObservableStateHandler;
 
   beforeEach(() => {
-    stateHandler = new TestStateHandler();
+    stateHandler = new TestObservableStateHandler();
   });
 
   it('should provide initial state', () => {
@@ -63,7 +61,7 @@ describe('State Handler', () => {
 
     stateHandler.setState(expected);
 
-    const state = await lastValueFrom(stateHandler.getObservable().pipe(take(1)));
+    const state = await lastValueFrom(stateHandler.getStateAsObservable().pipe(take(1)));
 
     expect(state).toStrictEqual(expected);
     expect(stateHandler.getState()).toStrictEqual(expected);
@@ -89,7 +87,7 @@ describe('State Handler', () => {
   it('should only call subscriber when object state has changed', async () => {
     const spy = jest.fn();
 
-    stateHandler.getObservable().subscribe(spy);
+    const unsubscribe = stateHandler.subscribe(spy);
     stateHandler.setState({
       test: 'test',
     });
@@ -103,6 +101,8 @@ describe('State Handler', () => {
       test: 'test2',
     });
 
-    expect(spy).toHaveBeenCalledTimes(3); // 1. testValue (Initial value), 2. test (first setter), 3. test2 (second setter)
+    unsubscribe();
+
+    expect(spy).toHaveBeenCalledTimes(2); // 1. test (first setter), 2. test2 (second setter)
   });
 });

package/src/store/__tests__/signal-state-handler.spec.ts

@@ -0,0 +1,97 @@
+import { SignalStateHandler } from '../signal-state-handler.js';
+
+class TestSignalStateHandler extends SignalStateHandler<
+  { test: string; test2: string },
+  { testAction: () => void }
+> {
+  constructor(withDevTools?: boolean) {
+    super({
+      initialState: {
+        test: 'testValue',
+        test2: 'testValue2',
+      },
+      ...(withDevTools && {
+        options: {
+          devTools: {
+            enabled: true,
+            namespace: 'TestSignalStateHandler',
+          },
+        },
+      }),
+    });
+  }
+
+  getActions(): { testAction: () => void } {
+    return {
+      testAction: () => {
+        this.setState({ test: 'newValue' });
+      },
+    };
+  }
+}
+
+describe('Signal State Handler', () => {
+  let stateHandler: TestSignalStateHandler;
+
+  beforeEach(() => {
+    stateHandler = new TestSignalStateHandler();
+  });
+
+  it('should provide initial state', () => {
+    expect(stateHandler.getInitialState()).toStrictEqual({
+      test: 'testValue',
+      test2: 'testValue2',
+    });
+  });
+
+  it('should provide current state', () => {
+    expect(stateHandler.getState()).toStrictEqual({
+      test: 'testValue',
+      test2: 'testValue2',
+    });
+  });
+
+  it('should support state changing via setter and merge state object on first level', () => {
+    const expected = {
+      test: 'change',
+      test2: 'testValue2',
+    };
+
+    stateHandler.setState(expected);
+
+    expect(stateHandler.getState()).toStrictEqual(expected);
+  });
+
+  it('should support additional subscriptions handling', () => {
+    const spy = jest.fn();
+    const subscription = { unsubscribe: spy };
+
+    stateHandler.subscriptions = [subscription];
+
+    stateHandler.destroy();
+
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('should only call subscriber when object state has changed', () => {
+    const spy = jest.fn();
+    const unsubscribe = stateHandler.subscribe(spy);
+
+    stateHandler.setState({
+      test: 'test',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+
+    unsubscribe();
+
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+});