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

package/src/selection.ts

@@ -2,21 +2,23 @@
 // Copyright 2025 DXOS.org
 //
 
-import { untracked } from '@preact/signals-core';
-import { Match, Schema } from 'effect';
+import { Atom, type Registry } from '@effect-atom/atom-react';
+import * as Match from 'effect/Match';
+import * as Schema from 'effect/Schema';
 
 import { invariant } from '@dxos/invariant';
-import { type Live, live } from '@dxos/live-object';
-
-// TODO(burdon): Reconcile with @dxos/graph.
 
 export type SelectionMode = 'single' | 'multi' | 'range' | 'multi-range';
 
 export const SelectionSchema = Schema.Union(
-  Schema.Struct({ mode: Schema.Literal('single'), id: Schema.optional(Schema.String) }).pipe(Schema.mutable),
-  Schema.Struct({ mode: Schema.Literal('multi'), ids: Schema.Array(Schema.String).pipe(Schema.mutable) }).pipe(
-    Schema.mutable,
-  ),
+  Schema.Struct({
+    mode: Schema.Literal('single'),
+    id: Schema.optional(Schema.String),
+  }).pipe(Schema.mutable),
+  Schema.Struct({
+    mode: Schema.Literal('multi'),
+    ids: Schema.Array(Schema.String).pipe(Schema.mutable),
+  }).pipe(Schema.mutable),
   Schema.Struct({
     mode: Schema.Literal('range'),
     from: Schema.optional(Schema.String),
@@ -49,7 +51,6 @@ export type SelectionResult<T extends SelectionMode> = T extends 'single'
         ? { from: string; to: string }[]
         : never;
 
-// TODO(burdon): Refactor.
 export const getSelectionSet = (selectionManager: SelectionManager, contextId?: string) => {
   const ids = new Set<string>(contextId ? [contextId] : []);
   for (const context of selectionManager.getSelectionContexts()) {
@@ -69,117 +70,159 @@ export const getSelectionSet = (selectionManager: SelectionManager, contextId?:
  * Each context maintains its own selection mode and state.
  */
 export class SelectionManager {
-  private readonly _state = live<{ selections: Record<string, Selection> }>({ selections: {} });
+  private readonly _state: Atom.Writable<{ selections: Record<string, Selection> }>;
+
+  constructor(
+    private readonly _registry: Registry.Registry,
+    initial: Record<string, Selection> = {},
+  ) {
+    this._state = Atom.make<{ selections: Record<string, Selection> }>({
+      selections: { ...initial },
+    });
+  }
 
-  constructor(initial: Record<string, Selection> = {}) {
-    if (Object.keys(initial).length > 0) {
-      untracked(() => {
-        this._state.selections = initial;
-      });
-    }
+  /**
+   * Get the state atom for reactive access in the graph system.
+   */
+  get state(): Atom.Atom<{ selections: Record<string, Selection> }> {
+    return this._state;
+  }
+
+  /**
+   * Gets the current state.
+   */
+  getState(): { selections: Record<string, Selection> } {
+    return this._registry.get(this._state);
+  }
+
+  /**
+   * Subscribe to changes in the selection state.
+   */
+  subscribe(cb: (state: { selections: Record<string, Selection> }) => void): () => void {
+    this._registry.get(this._state);
+    return this._registry.subscribe(this._state, () => {
+      cb(this._registry.get(this._state));
+    });
   }
 
   getSelectionContexts(): string[] {
-    return Object.keys(this._state.selections);
+    return Object.keys(this._registry.get(this._state).selections);
   }
 
+  getSelection(contextId: string): Selection | undefined;
+  getSelection<T extends SelectionMode>(contextId: string, mode: T): Selection;
   getSelection<T extends SelectionMode | undefined>(
     contextId: string,
     mode: T = undefined as T,
-  ): T extends undefined ? Live<Selection> | undefined : Live<Selection> {
-    const selection = untracked(() => this._state.selections[contextId]);
+  ): Selection | undefined {
+    const state = this._registry.get(this._state);
+    const selection = state.selections[contextId];
     if (!mode || selection) {
       return selection;
     }
 
-    return untracked(() => {
-      this._state.selections[contextId] = defaultSelection(mode);
-      return this._state.selections[contextId];
-    });
+    // Create new selection for the context.
+    const newSelection = defaultSelection(mode);
+    this._registry.update(this._state, (state) => ({
+      selections: { ...state.selections, [contextId]: newSelection },
+    }));
+
+    return newSelection;
   }
 
-  // TODO(burdon): Disambiguate with getSelection?
   getSelected<T extends SelectionMode>(contextId: string, mode: T = 'multi' as T): SelectionResult<T> {
     const selection = this.getSelection(contextId, mode);
     invariant(selection?.mode === mode, 'Selection mode mismatch');
+
+    // Cast required because TypeScript can't infer the relationship between T and the matched result.
     return Match.type<Selection>().pipe(
       Match.when({ mode: 'single' }, (s) => s.id),
       Match.when({ mode: 'multi' }, (s) => s.ids),
       Match.when({ mode: 'range' }, (s) => (s.from && s.to ? { from: s.from, to: s.to } : undefined)),
       Match.when({ mode: 'multi-range' }, (s) => s.ranges),
       Match.exhaustive,
-    )(selection) as any;
+    )(selection) as SelectionResult<T>;
   }
 
   updateSingle(contextId: string, id: string): void {
-    untracked(() => {
-      const selection = this.getSelection(contextId, 'single');
-      invariant(selection?.mode === 'single', 'Selection mode is not single');
-      selection.id = id;
-    });
+    const selection = this.getSelection(contextId, 'single');
+    invariant(selection?.mode === 'single', 'Selection mode is not single');
+    this._registry.update(this._state, (state) => ({
+      selections: {
+        ...state.selections,
+        [contextId]: { ...selection, id },
+      },
+    }));
   }
 
   updateMulti(contextId: string, ids: string[]) {
-    untracked(() => {
-      const selection = this.getSelection(contextId, 'multi');
-      invariant(selection?.mode === 'multi', 'Selection mode is not multi');
-      selection.ids.splice(0, selection.ids.length, ...ids);
-    });
+    const selection = this.getSelection(contextId, 'multi');
+    invariant(selection?.mode === 'multi', 'Selection mode is not multi');
+    this._registry.update(this._state, (state) => ({
+      selections: {
+        ...state.selections,
+        [contextId]: { ...selection, ids: [...ids] },
+      },
+    }));
   }
 
   updateRange(contextId: string, from: string, to: string) {
-    untracked(() => {
-      const selection = this.getSelection(contextId, 'range');
-      invariant(selection?.mode === 'range', 'Selection mode is not range');
-      selection.from = from;
-      selection.to = to;
-    });
+    const selection = this.getSelection(contextId, 'range');
+    invariant(selection?.mode === 'range', 'Selection mode is not range');
+    this._registry.update(this._state, (state) => ({
+      selections: {
+        ...state.selections,
+        [contextId]: { ...selection, from, to },
+      },
+    }));
   }
 
   updateMultiRange(contextId: string, ranges: { from: string; to: string }[]) {
-    untracked(() => {
-      const selection = this.getSelection(contextId, 'multi-range');
-      invariant(selection?.mode === 'multi-range', 'Selection mode is not multi-range');
-      selection.ranges.splice(0, selection.ranges.length, ...ranges);
-    });
+    const selection = this.getSelection(contextId, 'multi-range');
+    invariant(selection?.mode === 'multi-range', 'Selection mode is not multi-range');
+    this._registry.update(this._state, (state) => ({
+      selections: {
+        ...state.selections,
+        [contextId]: { ...selection, ranges: [...ranges] },
+      },
+    }));
   }
 
   clearSelection(contextId: string): void {
-    untracked(() => {
-      const selection = this.getSelection(contextId);
-      Match.type<Selection | undefined>().pipe(
-        Match.when(undefined, () => {
-          // No-op.
-        }),
-        Match.when({ mode: 'single' }, (s) => {
-          s.id = undefined;
-        }),
-        Match.when({ mode: 'multi' }, (s) => {
-          s.ids.splice(0, s.ids.length);
-        }),
-        Match.when({ mode: 'range' }, (s) => {
-          s.from = undefined;
-          s.to = undefined;
-        }),
-        Match.when({ mode: 'multi-range' }, (s) => {
-          s.ranges.splice(0, s.ranges.length);
-        }),
-        Match.exhaustive,
-      )(selection);
-    });
+    const selection = this.getSelection(contextId);
+    if (!selection) {
+      return;
+    }
+
+    const clearedSelection = Match.type<Selection>().pipe(
+      Match.when({ mode: 'single' }, (s) => ({ ...s, id: undefined })),
+      Match.when({ mode: 'multi' }, (s) => ({ ...s, ids: [] })),
+      Match.when({ mode: 'range' }, (s) => ({ ...s, from: undefined, to: undefined })),
+      Match.when({ mode: 'multi-range' }, (s) => ({ ...s, ranges: [] })),
+      Match.exhaustive,
+    )(selection);
+
+    this._registry.update(this._state, (state) => ({
+      selections: {
+        ...state.selections,
+        [contextId]: clearedSelection,
+      },
+    }));
   }
 
   toggleSelection(contextId: string, id: string): void {
-    untracked(() => {
-      const selection = this.getSelection(contextId, 'multi');
-      invariant(selection?.mode === 'multi', 'Selection mode is not multi');
-
-      if (selection.ids.includes(id)) {
-        const index = selection.ids.indexOf(id);
-        selection.ids.splice(index, 1);
-      } else {
-        selection.ids.push(id);
-      }
-    });
+    const selection = this.getSelection(contextId, 'multi');
+    invariant(selection?.mode === 'multi', 'Selection mode is not multi');
+
+    const newIds = selection.ids.includes(id)
+      ? selection.ids.filter((existingId) => existingId !== id)
+      : [...selection.ids, id];
+
+    this._registry.update(this._state, (state) => ({
+      selections: {
+        ...state.selections,
+        [contextId]: { ...selection, ids: newIds },
+      },
+    }));
   }
 }

package/src/testing/decorators/withAttention.ts

@@ -2,11 +2,29 @@
 // Copyright 2024 DXOS.org
 //
 
+import { Registry, RegistryContext } from '@effect-atom/atom-react';
 import { type Decorator } from '@storybook/react';
-import { createElement } from 'react';
+import { createElement, useMemo } from 'react';
 
-import { RootAttentionProvider } from '../../components';
+import { AttentionManager } from '../../attention';
+import { RootAttentionProvider, SelectionProvider } from '../../components';
 
-export const withAttention: Decorator = (Story) => {
-  return createElement(RootAttentionProvider, {}, createElement(Story));
+/**
+ * Storybook decorator that provides attention context.
+ * @param initialAttendedId Optional ID to set as initially attended.
+ */
+export const withAttention = (initialAttendedId?: string): Decorator => {
+  return (Story) => {
+    const registry = useMemo(() => Registry.make(), []);
+    const attention = useMemo(
+      () => (initialAttendedId ? new AttentionManager(registry, [initialAttendedId]) : undefined),
+      [registry],
+    );
+
+    return createElement(
+      RegistryContext.Provider,
+      { value: registry },
+      createElement(RootAttentionProvider, { attention }, createElement(SelectionProvider, {}, createElement(Story))),
+    );
+  };
 };

package/src/types/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// UI-free re-exports of @dxos/react-ui-attention. Importing from here does not
+// pull in React components, so it is safe to use from operations, schemas, and
+// other non-DOM code that only needs the data model and pure helpers.
+export * from '../attention';
+export * from '../selection';

package/src/useArticleKeyboardNavigation.test.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { advance } from './useArticleKeyboardNavigation';
+
+describe('advance', () => {
+  const ids = ['a', 'b', 'c', 'd'];
+
+  test('returns undefined for an empty list', ({ expect }) => {
+    expect(advance({ ids: [], currentId: undefined, delta: 1 })).to.equal(undefined);
+    expect(advance({ ids: [], currentId: 'x', delta: -1 })).to.equal(undefined);
+  });
+
+  test('with no current selection, delta=+1 enters at the first item', ({ expect }) => {
+    expect(advance({ ids, currentId: undefined, delta: 1 })).to.equal('a');
+  });
+
+  test('with no current selection, delta=-1 enters at the last item', ({ expect }) => {
+    expect(advance({ ids, currentId: undefined, delta: -1 })).to.equal('d');
+  });
+
+  test('advances forward from the middle of the list', ({ expect }) => {
+    expect(advance({ ids, currentId: 'b', delta: 1 })).to.equal('c');
+  });
+
+  test('advances backward from the middle of the list', ({ expect }) => {
+    expect(advance({ ids, currentId: 'c', delta: -1 })).to.equal('b');
+  });
+
+  test('clamps at the last item when pressing next', ({ expect }) => {
+    expect(advance({ ids, currentId: 'd', delta: 1 })).to.equal('d');
+  });
+
+  test('clamps at the first item when pressing previous', ({ expect }) => {
+    expect(advance({ ids, currentId: 'a', delta: -1 })).to.equal('a');
+  });
+
+  test('treats an unknown currentId like no selection', ({ expect }) => {
+    expect(advance({ ids, currentId: 'unknown', delta: 1 })).to.equal('a');
+    expect(advance({ ids, currentId: 'unknown', delta: -1 })).to.equal('d');
+  });
+
+  test('single-item list clamps both directions to that item', ({ expect }) => {
+    expect(advance({ ids: ['only'], currentId: 'only', delta: 1 })).to.equal('only');
+    expect(advance({ ids: ['only'], currentId: 'only', delta: -1 })).to.equal('only');
+  });
+});

package/src/useArticleKeyboardNavigation.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useEffect, useMemo } from 'react';
+
+import { Keyboard } from '@dxos/keyboard';
+
+import { useAttention } from './components';
+
+/**
+ * Compute the id to select after pressing 'j' (delta = 1) or 'k' (delta = -1).
+ * Clamps at the list ends — pressing 'j' on the last item keeps the last item
+ * selected (vim-style), and 'k' on the first item keeps the first.
+ *
+ * When no current selection exists, returns the first id (for delta = 1) or the
+ * last id (for delta = -1) so the user can enter the list with either key.
+ */
+export const advance = ({
+  ids,
+  currentId,
+  delta,
+}: {
+  ids: readonly string[];
+  currentId: string | undefined;
+  delta: 1 | -1;
+}): string | undefined => {
+  if (ids.length === 0) {
+    return undefined;
+  }
+
+  const idx = currentId ? ids.indexOf(currentId) : -1;
+  if (idx === -1) {
+    return delta === 1 ? ids[0] : ids[ids.length - 1];
+  }
+
+  const next = Math.max(0, Math.min(ids.length - 1, idx + delta));
+  return ids[next];
+};
+
+export type UseArticleKeyboardNavigationOptions<T> = {
+  /** Stable id for the article (used as the keyboard context path). */
+  articleId: string;
+  /** Ordered list of selectable items as they appear in the article. */
+  items: readonly T[];
+  /** Currently-selected id, if any. */
+  currentId: string | undefined;
+  /** Extracts the id from an item. Defaults to `item.id`. */
+  getId?: (item: T) => string;
+  /** Called with the id to select when the user presses 'j' or 'k'. */
+  onSelect: (id: string) => void;
+};
+
+/**
+ * Wire 'j' (next) and 'k' (previous) keyboard shortcuts for an article that
+ * navigates a list of items (e.g., messages, events). Bindings are scoped to
+ * the article's keyboard context so they only fire while the article has attention.
+ *
+ * Pass the items directly; ids are derived via `getId` (defaults to `item.id`).
+ * Clamps at list boundaries. Active only when the article is attended.
+ */
+export const useArticleKeyboardNavigation: {
+  <T extends { id: string }>(options: UseArticleKeyboardNavigationOptions<T>): void;
+  <T>(options: UseArticleKeyboardNavigationOptions<T> & { getId: (item: T) => string }): void;
+} = <T>({ articleId, items, currentId, getId, onSelect }: UseArticleKeyboardNavigationOptions<T>): void => {
+  const { hasAttention } = useAttention(articleId);
+
+  // `getId` is optional only when `T extends { id: string }` (enforced by the overloads above),
+  // so the fallback is sound; the cast bridges the generic erased by the implementation signature.
+  const ids = useMemo(() => items.map((item) => (getId ? getId(item) : (item as { id: string }).id)), [items, getId]);
+
+  useEffect(() => {
+    if (!hasAttention) {
+      return;
+    }
+
+    const context = Keyboard.singleton.getContext(articleId);
+    const prevContext = Keyboard.singleton.getCurrentContext();
+    Keyboard.singleton.setCurrentContext(articleId);
+
+    const nextBinding = {
+      shortcut: 'j',
+      handler: () => {
+        const target = advance({ ids, currentId, delta: 1 });
+        if (target !== undefined) {
+          onSelect(target);
+        }
+      },
+      data: 'Next item',
+      disableInput: true,
+    };
+    const prevBinding = {
+      shortcut: 'k',
+      handler: () => {
+        const target = advance({ ids, currentId, delta: -1 });
+        if (target !== undefined) {
+          onSelect(target);
+        }
+      },
+      data: 'Previous item',
+      disableInput: true,
+    };
+
+    context.bind(nextBinding);
+    context.bind(prevBinding);
+
+    return () => {
+      context.unbind('j');
+      context.unbind('k');
+      // Restore the prior context if we were the ones who set it.
+      if (Keyboard.singleton.getCurrentContext() === articleId) {
+        Keyboard.singleton.setCurrentContext(prevContext);
+      }
+    };
+  }, [articleId, ids, currentId, onSelect, hasAttention]);
+};