@dxos/react-ui-attention 0.8.4-staging.60fe92afc8 → 0.9.1-main.c7dcc2e112

package/src/view-state/backends.ts

@@ -0,0 +1,145 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, type Registry } from '@effect-atom/atom-react';
+import * as Schema from 'effect/Schema';
+
+import { type AspectDef, type BackendName, type ViewStateBackend } from './view-state';
+
+// Only the stable `key` string is needed to form the map key; avoids variance issues with AspectDef<T>.
+const cacheKey = (aspect: { key: string }, contextId: string) => `${aspect.key}:${contextId}`;
+
+/** In-memory backend: state is ephemeral and scoped to the session (never persisted). */
+export class MemoryBackend implements ViewStateBackend {
+  readonly #atoms = new Map<string, Atom.Writable<unknown>>();
+
+  atom<T>(aspect: AspectDef<T>, contextId: string): Atom.Writable<T> {
+    const key = cacheKey(aspect, contextId);
+    let atom = this.#atoms.get(key);
+    if (!atom) {
+      atom = Atom.make<unknown>(aspect.defaultValue());
+      this.#atoms.set(key, atom);
+    }
+    // Cast bridges the per-aspect value type erased by the shared atom map; safe by construction.
+    return atom as Atom.Writable<T>;
+  }
+
+  contexts<T>(aspect: AspectDef<T>): string[] {
+    const prefix = `${aspect.key}:`;
+    return [...this.#atoms.keys()].filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+  }
+}
+
+const STORAGE_PREFIX = 'dxos:view-state:';
+
+const storageKeyFor = (aspect: { key: string }, contextId: string) => `${STORAGE_PREFIX}${aspect.key}:${contextId}`;
+
+// Accessing `globalThis.localStorage` can throw a SecurityError in sandboxed iframes or when
+// storage is blocked; degrade to in-memory behaviour instead of crashing.
+const safeLocalStorage = (): Storage | undefined => {
+  try {
+    return globalThis.localStorage;
+  } catch {
+    return undefined;
+  }
+};
+
+export interface LocalBackendOptions {
+  readonly registry: Registry.Registry;
+  /** Injectable for tests; defaults to `window.localStorage`. */
+  readonly storage?: Storage;
+}
+
+/** localStorage-backed backend: seeds atoms from storage, persists on set, syncs across tabs. */
+export class LocalBackend implements ViewStateBackend {
+  readonly #registry: Registry.Registry;
+  // Absent in non-browser contexts (SSR/tests without injection); the backend then degrades to
+  // ephemeral, in-memory behaviour rather than crashing on a missing `localStorage`.
+  readonly #storage: Storage | undefined;
+  readonly #atoms = new Map<string, Atom.Writable<unknown>>();
+  // Reverse map: storage key -> (aspect, contextId) so `storage` events can target the right atom.
+  readonly #byStorageKey = new Map<string, { aspect: AspectDef<unknown>; contextId: string }>();
+  #storageListener?: (event: StorageEvent) => void;
+
+  constructor({ registry, storage }: LocalBackendOptions) {
+    this.#registry = registry;
+    this.#storage = storage ?? safeLocalStorage();
+    if (this.#storage && typeof globalThis.addEventListener === 'function') {
+      this.#storageListener = (event) => {
+        if (!event.key || !event.key.startsWith(STORAGE_PREFIX)) {
+          return;
+        }
+        const entry = this.#byStorageKey.get(event.key);
+        const atom = entry && this.#atoms.get(cacheKey(entry.aspect, entry.contextId));
+        if (entry && atom) {
+          this.#registry.set(atom, this.#read(entry.aspect, event.key));
+        }
+      };
+      globalThis.addEventListener('storage', this.#storageListener);
+    }
+  }
+
+  atom<T>(aspect: AspectDef<T>, contextId: string): Atom.Writable<T> {
+    const key = cacheKey(aspect, contextId);
+    let atom = this.#atoms.get(key);
+    if (!atom) {
+      const storageKey = storageKeyFor(aspect, contextId);
+      atom = Atom.make<unknown>(this.#read(aspect, storageKey));
+      this.#atoms.set(key, atom);
+      // Cast erases the per-aspect value type so the reverse map can hold aspects of any `T`; the
+      // stored aspect is only used to re-read/decode its own value, so the erasure is safe.
+      this.#byStorageKey.set(storageKey, { aspect: aspect as AspectDef<unknown>, contextId });
+    }
+    // Cast bridges the per-aspect value type erased by the shared atom map; safe by construction.
+    return atom as Atom.Writable<T>;
+  }
+
+  persist<T>(aspect: AspectDef<T>, contextId: string, value: T): void {
+    this.#storage?.setItem(storageKeyFor(aspect, contextId), JSON.stringify(Schema.encodeSync(aspect.schema)(value)));
+  }
+
+  contexts<T>(aspect: AspectDef<T>): string[] {
+    if (!this.#storage) {
+      // No persistent storage: fall back to the in-memory atoms (mirrors `atom()`'s ephemeral path).
+      const prefix = `${aspect.key}:`;
+      return [...this.#atoms.keys()].filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+    }
+    const prefix = storageKeyFor(aspect, '');
+    const ids: string[] = [];
+    for (let index = 0; index < this.#storage.length; index++) {
+      const key = this.#storage.key(index);
+      if (key?.startsWith(prefix)) {
+        ids.push(key.slice(prefix.length));
+      }
+    }
+    return ids;
+  }
+
+  dispose(): void {
+    if (this.#storageListener && typeof globalThis.removeEventListener === 'function') {
+      globalThis.removeEventListener('storage', this.#storageListener);
+    }
+    // Allow safe reuse after disposal: drop cached atoms and their reverse-key entries.
+    this.#atoms.clear();
+    this.#byStorageKey.clear();
+  }
+
+  #read<T>(aspect: AspectDef<T>, storageKey: string): T {
+    const raw = this.#storage?.getItem(storageKey);
+    if (raw == null) {
+      return aspect.defaultValue();
+    }
+    try {
+      return Schema.decodeUnknownSync(aspect.schema)(JSON.parse(raw));
+    } catch {
+      // Tolerate stale/corrupt entries (e.g. a prior schema shape) by falling back to the default.
+      return aspect.defaultValue();
+    }
+  }
+}
+
+export const createDefaultBackends = (registry: Registry.Registry): Record<BackendName, ViewStateBackend> => ({
+  memory: new MemoryBackend(),
+  local: new LocalBackend({ registry }),
+});

package/src/view-state/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './view-state';
+export * from './backends';

package/src/view-state/view-state.test.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom-react';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { createDefaultBackends } from './backends';
+import { ViewStateManager, defineViewState } from './view-state';
+
+const Counter = defineViewState({
+  key: 'counter',
+  backend: 'memory',
+  schema: Schema.Struct({ value: Schema.Number }).pipe(Schema.mutable),
+  defaultValue: () => ({ value: 0 }),
+});
+
+describe('ViewStateManager', () => {
+  const make = () => {
+    const registry = Registry.make();
+    return new ViewStateManager({ registry, backends: createDefaultBackends(registry) });
+  };
+
+  test('returns the aspect default for an unwritten context', ({ expect }) => {
+    const manager = make();
+    expect(manager.get(Counter, 'a')).toEqual({ value: 0 });
+  });
+
+  test('set then get round-trips per context', ({ expect }) => {
+    const manager = make();
+    manager.set(Counter, 'a', { value: 5 });
+    expect(manager.get(Counter, 'a')).toEqual({ value: 5 });
+    expect(manager.get(Counter, 'b')).toEqual({ value: 0 });
+  });
+
+  test('subscribe fires on change for that context', ({ expect }) => {
+    const manager = make();
+    let calls = 0;
+    const dispose = manager.subscribe(Counter, 'a', () => {
+      calls++;
+    });
+    manager.set(Counter, 'a', { value: 1 });
+    expect(calls).toBeGreaterThan(0);
+    dispose();
+  });
+
+  test('contexts enumerates touched contexts for an aspect', ({ expect }) => {
+    const manager = make();
+    manager.set(Counter, 'a', { value: 1 });
+    manager.set(Counter, 'b', { value: 2 });
+    expect(new Set(manager.contexts(Counter))).toEqual(new Set(['a', 'b']));
+  });
+});

package/src/view-state/view-state.ts

@@ -0,0 +1,91 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Atom, type Registry } from '@effect-atom/atom-react';
+import type * as Schema from 'effect/Schema';
+
+/**
+ * Persistence backend identifier. `personal` (ECHO/personal-space) is reserved for a future backend.
+ */
+export type BackendName = 'memory' | 'local';
+
+/**
+ * Declares a kind of per-context UI state. The value type `T` is inferred from the schema.
+ */
+export interface AspectDef<T> {
+  readonly key: string;
+  readonly backend: BackendName;
+  // Encoded type is intentionally unconstrained: persisted backends serialize `T` through the
+  // schema to an arbitrary wire form, and only the decoded `T` matters to consumers.
+  readonly schema: Schema.Schema<T, any>;
+  readonly defaultValue: () => T;
+}
+
+/**
+ * Identity helper that pins the value type from the schema while keeping the literal `key`/`backend`.
+ */
+export const defineViewState = <T>(def: AspectDef<T>): AspectDef<T> => def;
+
+/**
+ * A backend produces a reactive, writable atom for each `(aspect, contextId)` pair. Backends may
+ * hydrate asynchronously (an ECHO backend would), yielding `aspect.defaultValue()` until loaded;
+ * the memory and local backends resolve synchronously.
+ */
+export interface ViewStateBackend {
+  /** Stable atom for the pair; created (and seeded) on first access, cached thereafter. */
+  atom: <T>(aspect: AspectDef<T>, contextId: string) => Atom.Writable<T>;
+  /** Persist a value after the atom is updated. No-op for in-memory backends. */
+  persist?: <T>(aspect: AspectDef<T>, contextId: string, value: T) => void;
+  /** Context ids that currently hold a value for the aspect. */
+  contexts: <T>(aspect: AspectDef<T>) => string[];
+  /** Release listeners/timers (used by tests; app-lifetime managers do not call this). */
+  dispose?: () => void;
+}
+
+export interface ViewStateManagerOptions {
+  readonly registry: Registry.Registry;
+  readonly backends: Record<BackendName, ViewStateBackend>;
+}
+
+/**
+ * Routes per-context UI state to the backend declared by each aspect. Reads/writes go through the
+ * effect-atom registry so React hooks and graph atoms observe changes uniformly.
+ */
+export class ViewStateManager {
+  readonly #registry: Registry.Registry;
+  readonly #backends: Record<BackendName, ViewStateBackend>;
+
+  constructor({ registry, backends }: ViewStateManagerOptions) {
+    this.#registry = registry;
+    this.#backends = backends;
+  }
+
+  /** Reactive atom for `(aspect, contextId)`; pass to `registry.get` inside derived atoms/hooks. */
+  atom<T>(aspect: AspectDef<T>, contextId: string): Atom.Writable<T> {
+    return this.#backends[aspect.backend].atom(aspect, contextId);
+  }
+
+  get<T>(aspect: AspectDef<T>, contextId: string): T {
+    return this.#registry.get(this.atom(aspect, contextId));
+  }
+
+  set<T>(aspect: AspectDef<T>, contextId: string, value: T): void {
+    const backend = this.#backends[aspect.backend];
+    this.#registry.set(backend.atom(aspect, contextId), value);
+    backend.persist?.(aspect, contextId, value);
+  }
+
+  update<T>(aspect: AspectDef<T>, contextId: string, fn: (prev: T) => T): void {
+    this.set(aspect, contextId, fn(this.get(aspect, contextId)));
+  }
+
+  subscribe<T>(aspect: AspectDef<T>, contextId: string, cb: (value: T) => void): () => void {
+    const atom = this.atom(aspect, contextId);
+    return this.#registry.subscribe(atom, () => cb(this.#registry.get(atom)));
+  }
+
+  contexts<T>(aspect: AspectDef<T>): string[] {
+    return this.#backends[aspect.backend].contexts(aspect);
+  }
+}

package/src/vitest-setup.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// https://github.com/testing-library/jest-dom#with-vitest
+import '@testing-library/jest-dom/vitest';