@dxos/react-ui-attention 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/package.json

@@ -1,20 +1,32 @@
 {
   "name": "@dxos/react-ui-attention",
-  "version": "0.8.4-main.84f28bd",
+  "version": "0.8.4-main.937b3ca",
   "description": "Signifier components and providers for attention system.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
     },
+    "./types": {
+      "source": "./src/types.ts",
+      "types": "./dist/types/src/types.d.ts",
+      "browser": "./dist/lib/browser/types.mjs",
+      "node": "./dist/lib/node-esm/types.mjs"
+    },
     "./testing": {
+      "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
       "browser": "./dist/lib/browser/testing/index.mjs",
       "node": "./dist/lib/node-esm/testing/index.mjs"
@@ -23,6 +35,9 @@
   "types": "dist/types/src/index.d.ts",
   "typesVersions": {
     "*": {
+      "types": [
+        "dist/types/src/types.d.ts"
+      ],
       "testing": [
         "dist/types/src/testing/index.d.ts"
       ]
@@ -33,8 +48,7 @@
     "src"
   ],
   "dependencies": {
-    "@preact-signals/safe-react": "^0.9.0",
-    "@preact/signals-core": "^1.9.0",
+    "@effect-atom/atom-react": "^0.4.6",
     "@radix-ui/primitive": "1.1.1",
     "@radix-ui/react-compose-refs": "1.1.1",
     "@radix-ui/react-context": "1.1.1",
@@ -42,30 +56,30 @@
     "@radix-ui/react-primitive": "2.0.2",
     "@radix-ui/react-slot": "1.1.2",
     "@radix-ui/react-use-controllable-state": "1.1.0",
-    "effect": "3.16.13",
-    "@dxos/echo-schema": "0.8.4-main.84f28bd",
-    "@dxos/invariant": "0.8.4-main.84f28bd",
-    "@dxos/live-object": "0.8.4-main.84f28bd",
-    "@dxos/log": "0.8.4-main.84f28bd",
-    "@dxos/util": "0.8.4-main.84f28bd"
+    "effect": "3.19.11",
+    "@dxos/invariant": "0.8.4-main.937b3ca",
+    "@dxos/echo": "0.8.4-main.937b3ca",
+    "@dxos/log": "0.8.4-main.937b3ca",
+    "@dxos/react-hooks": "0.8.4-main.937b3ca",
+    "@dxos/util": "0.8.4-main.937b3ca"
   },
   "devDependencies": {
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "vite": "5.4.7",
-    "@dxos/random": "0.8.4-main.84f28bd",
-    "@dxos/react-ui": "0.8.4-main.84f28bd",
-    "@dxos/react-ui-theme": "0.8.4-main.84f28bd",
-    "@dxos/storybook-utils": "0.8.4-main.84f28bd"
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "vite": "7.1.9",
+    "@dxos/random": "0.8.4-main.937b3ca",
+    "@dxos/react-ui": "0.8.4-main.937b3ca",
+    "@dxos/storybook-utils": "0.8.4-main.937b3ca",
+    "@dxos/ui-theme": "0.8.4-main.937b3ca"
   },
   "peerDependencies": {
-    "effect": "^3.13.3",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "@dxos/react-ui": "0.8.4-main.84f28bd",
-    "@dxos/react-ui-theme": "0.8.4-main.84f28bd"
+    "effect": "3.19.11",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/react-ui": "0.8.4-main.937b3ca",
+    "@dxos/ui-theme": "0.8.4-main.937b3ca"
   },
   "publishConfig": {
     "access": "public"

package/src/attention.test.ts

@@ -2,14 +2,16 @@
 // Copyright 2024 DXOS.org
 //
 
-import { describe, test, expect } from 'vitest';
+import { Registry } from '@effect-atom/atom-react';
+import { describe, expect, test } from 'vitest';
 
 import { AttentionManager } from './attention';
 
 describe('AttentionManager', () => {
   test('takes an initial attendable', () => {
-    const attention = new AttentionManager(['a', 'b', 'c']);
-    expect(attention.current).to.deep.equal(['a', 'b', 'c']);
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry, ['a', 'b', 'c']);
+    expect(attention.getCurrent()).to.deep.equal(['a', 'b', 'c']);
     expect(attention.keys()).to.deep.equal([['a'], ['b', 'c'], ['c'], ['a', 'b', 'c']]);
     expect(attention.get(['a'])).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: true });
     expect(attention.get(['b', 'c'])).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
@@ -19,15 +21,17 @@ describe('AttentionManager', () => {
   });
 
   test('current returns last updated key', () => {
-    const attention = new AttentionManager();
-    expect(attention.current).to.deep.equal([]);
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
+    expect(attention.getCurrent()).to.deep.equal([]);
 
     attention.update(['a', 'b', 'c']);
-    expect(attention.current).to.deep.equal(['a', 'b', 'c']);
+    expect(attention.getCurrent()).to.deep.equal(['a', 'b', 'c']);
   });
 
   test('keys returns all stored attendables', () => {
-    const attention = new AttentionManager();
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
     expect(attention.keys()).to.deep.equal([]);
 
     attention.update(['a']);
@@ -38,7 +42,8 @@ describe('AttentionManager', () => {
   });
 
   test('get returns attention object for a given key', () => {
-    const attention = new AttentionManager();
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
     expect(attention.get(['a'])).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
 
     attention.update(['a']);

package/src/attention.ts

@@ -2,24 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
-import { untracked } from '@preact/signals-core';
-import { Schema } from 'effect';
+import { Atom, type Registry } from '@effect-atom/atom-react';
 
-import { live, type Live } from '@dxos/live-object';
 import { ComplexMap } from '@dxos/util';
 
-// NOTE: Chosen from RFC 1738’s `safe` characters: http://www.faqs.org/rfcs/rfc1738.html
-export const ATTENDABLE_PATH_SEPARATOR = '~';
-
-export const AttentionSchema = Schema.mutable(
-  Schema.Struct({
-    hasAttention: Schema.Boolean,
-    isAncestor: Schema.Boolean,
-    isRelated: Schema.Boolean,
-  }),
-);
-
-export type Attention = Schema.Schema.Type<typeof AttentionSchema>;
+import { ATTENDABLE_PATH_SEPARATOR, type Attention } from './types';
 
 // TODO(wittjosiah): Use mosaic path utility?
 const stringKey = (key: string[]) => key.join(',');
@@ -27,26 +14,44 @@ const stringKey = (key: string[]) => key.join(',');
 /**
  * Manages attention state for an application.
  */
-// TODO(wittjosiah): Write unit tests.
 export class AttentionManager {
-  // Each attention path is associated with an attention object.
+  // Each attention path is associated with an attention atom.
   // The lookup is not a reactive object to ensure that attention for each path is subscribable independently.
-  private readonly _map = new ComplexMap<string[], Live<Attention>>(stringKey);
-  private readonly _state = live<{ current: string[] }>({ current: [] });
-
-  constructor(initial: string[] = []) {
+  private readonly _map = new ComplexMap<string[], Atom.Writable<Attention>>(stringKey);
+  private readonly _currentAtom: Atom.Writable<string[]>;
+
+  constructor(
+    private readonly _registry: Registry.Registry,
+    initial: string[] = [],
+  ) {
+    this._currentAtom = Atom.make<string[]>([]);
     if (initial.length > 0) {
       this.update(initial);
     }
   }
 
   /**
-   * Currently attended element.
-   *
-   * @reactive
+   * Atom for the currently attended element path.
+   */
+  get current(): Atom.Atom<string[]> {
+    return this._currentAtom;
+  }
+
+  /**
+   * Gets the currently attended element path.
+   */
+  getCurrent(): readonly string[] {
+    return this._registry.get(this._currentAtom);
+  }
+
+  /**
+   * Subscribe to changes in the current attention path.
    */
-  get current(): Live<readonly string[]> {
-    return this._state.current;
+  subscribeCurrent(cb: (current: readonly string[]) => void): () => void {
+    this._registry.get(this._currentAtom);
+    return this._registry.subscribe(this._currentAtom, () => {
+      cb(this._registry.get(this._currentAtom));
+    });
   }
 
   /**
@@ -59,15 +64,31 @@ export class AttentionManager {
   /**
    * Get the attention state for a given path.
    */
-  get(key: string[]): Live<Attention> {
-    const object = this._map.get(key);
-    if (object) {
-      return object;
+  get(key: string[]): Attention {
+    const atom = this._getAtom(key);
+    return this._registry.get(atom);
+  }
+
+  /**
+   * Subscribe to changes in the attention state for a given path.
+   */
+  subscribe(key: string[], cb: (attention: Attention) => void): () => void {
+    const atom = this._getAtom(key);
+    this._registry.get(atom);
+    return this._registry.subscribe(atom, () => {
+      cb(this._registry.get(atom));
+    });
+  }
+
+  private _getAtom(key: string[]): Atom.Writable<Attention> {
+    const existing = this._map.get(key);
+    if (existing) {
+      return existing;
     }
 
-    const newObject = live(AttentionSchema, { hasAttention: false, isAncestor: false, isRelated: false });
-    this._map.set(key, newObject);
-    return newObject;
+    const newAtom = Atom.make<Attention>({ hasAttention: false, isAncestor: false, isRelated: false });
+    this._map.set(key, newAtom);
+    return newAtom;
   }
 
   /**
@@ -76,12 +97,12 @@ export class AttentionManager {
    * @internal
    */
   update(nextKey: string[]): void {
-    const currentKey = untracked(() => this.current);
+    const currentKey = this.getCurrent();
     const currentRelatedTo = currentKey[0];
     const nextRelatedTo = nextKey[0];
 
     // Ensure related attention object is initialized.
-    this.get([nextRelatedTo]);
+    this._getAtom([nextRelatedTo]);
 
     const currentRelatedKeys = this.keys().filter((key) => key[0] === currentRelatedTo);
     const nextRelatedKeys = this.keys().filter(
@@ -97,7 +118,7 @@ export class AttentionManager {
       (curr) => !nextAncestorKeys.find((next) => stringKey(curr) === stringKey(next)),
     );
 
-    this._state.current = nextKey;
+    this._registry.set(this._currentAtom, nextKey);
     prevRelatedKeys.forEach((key) => this._set(key, {}));
     prevAncestorKeys.forEach((key) => this._set(key, {}));
     nextRelatedKeys.forEach((key) => this._set(key, { isRelated: true }));
@@ -106,15 +127,17 @@ export class AttentionManager {
   }
 
   private _set(key: string[], attention: Partial<Attention>): void {
-    const object = this.get(key);
-    object.hasAttention = attention.hasAttention ?? false;
-    object.isAncestor = attention.isAncestor ?? false;
-    object.isRelated = attention.isRelated ?? false;
+    const atom = this._getAtom(key);
+    this._registry.set(atom, {
+      hasAttention: attention.hasAttention ?? false,
+      isAncestor: attention.isAncestor ?? false,
+      isRelated: attention.isRelated ?? false,
+    });
   }
 }
 
 /**
- * Accumulates all attendable id’s between the element provided and the root, inclusive.
+ * Accumulates all attendable id's between the element provided and the root, inclusive.
  */
 export const getAttendables = (selector: string, cursor: Element, acc: string[] = []): string[] => {
   // Find the closest element with `data-attendable-id`, if any; start from cursor and move up the DOM tree.

package/src/components/AttentionGlyph.stories.tsx

@@ -2,17 +2,16 @@
 // Copyright 2024 DXOS.org
 //
 
-import '@dxos-theme';
-
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useCallback, useEffect, useState } from 'react';
 
 import { Button } from '@dxos/react-ui';
-import { withTheme } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
 import { range } from '@dxos/util';
 
 import { AttentionGlyph, type AttentionGlyphProps } from './AttentionGlyph';
 
-const Story = (props: AttentionGlyphProps) => {
+const DefaultStory = (props: AttentionGlyphProps) => {
   return (
     <ul className='flex gap-2 mbe-2'>
       <li>
@@ -28,26 +27,30 @@ const Story = (props: AttentionGlyphProps) => {
   );
 };
 
-export default {
+const meta = {
   title: 'ui/react-ui-attention/AttentionGlyph',
-  component: AttentionGlyph,
-  render: Story,
+  component: AttentionGlyph as any,
+  render: DefaultStory,
   decorators: [withTheme],
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
 
-export const Default = {
+export const Default: Story = {
   args: {},
 };
 
-export const Attention = {
+export const Attention: Story = {
   args: { attended: true },
 };
 
-export const Contains = {
+export const Contains: Story = {
   args: { containsAttended: true },
 };
 
-export const Syncing = {
+export const Syncing: Story = {
   render: () => {
     const [spaces, setSpaces] = useState(
       new Map<string, boolean>(range(8).map((i) => [`space-${i + 1}`, Math.random() > 0.5])),
@@ -73,7 +76,7 @@ export const Syncing = {
     });
 
     return (
-      <div className='flex flex-col p-2 w-[200px]'>
+      <div className='flex flex-col p-2 is-[200px]'>
         <Button onClick={handleChangeAttended}>Change attended</Button>
         {Array.from(spaces.entries()).map(([space, sync]) => (
           <div key={space} className='flex items-center'>

package/src/components/AttentionGlyph.tsx

@@ -3,10 +3,10 @@
 //
 
 import { type Primitive } from '@radix-ui/react-primitive';
-import React, { type ComponentPropsWithRef, type CSSProperties, forwardRef, useMemo } from 'react';
+import React, { type CSSProperties, type ComponentPropsWithRef, forwardRef, useMemo } from 'react';
 
 import { Icon, type ThemedClassName } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
 const attentionGlyphStyles =
   'inline-block rounded-sm is-3 bs-3 bg-transparent text-accentText transition-colors [[data-contains-attended=true]_&]:bg-attentionRelated [[data-attention=true]_&]:bg-accentSurface [[data-attention=true]_&]:text-accentSurfaceText [[aria-current][data-attention=true]_&]:bg-accentSurface [[aria-current][data-attention=true]_&]:text-accentSurfaceText';

package/src/components/AttentionProvider.stories.tsx

@@ -2,15 +2,15 @@
 // Copyright 2024 DXOS.org
 //
 
-import '@dxos-theme';
-
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { withTheme } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
 
-import { useAttentionAttributes } from './AttentionProvider';
 import { withAttention } from '../testing';
 
+import { useAttentionAttributes } from './AttentionProvider';
+
 const Attendable = ({ id }: { id: string }) => {
   const attentionAttrs = useAttentionAttributes(id);
 
@@ -32,10 +32,14 @@ const Story = () => {
   );
 };
 
-export default {
+const meta = {
   title: 'ui/react-ui-attention/AttentionProvider',
   render: Story,
   decorators: [withTheme, withAttention],
-};
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
 
-export const Default = {};
+export const Default: Story = {};

package/src/components/AttentionProvider.tsx

@@ -2,21 +2,31 @@
 // Copyright 2024 DXOS.org
 //
 
-// NOTE(thure): The following unused imports quell TS2742 (“likely not portable”).
-
-// eslint-disable-next-line unused-imports/no-unused-imports
-import { createContext, type Scope, type CreateScope } from '@radix-ui/react-context';
+import { RegistryContext } from '@effect-atom/atom-react';
+import { createContext } from '@radix-ui/react-context';
 import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
-import React, { useMemo, type FocusEvent, type PropsWithChildren, type ComponentPropsWithRef, forwardRef } from 'react';
-
-import { useDefaultValue, type ThemedClassName } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
-
-import { ATTENDABLE_PATH_SEPARATOR, type Attention, AttentionManager, getAttendables } from '../attention';
+import React, {
+  type ComponentPropsWithRef,
+  type FocusEvent,
+  type PropsWithChildren,
+  forwardRef,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+import { log } from '@dxos/log';
+import { useDefaultValue } from '@dxos/react-hooks';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { AttentionManager, getAttendables } from '../attention';
+import { ATTENDABLE_PATH_SEPARATOR, type Attention } from '../types';
 
 const ATTENTION_NAME = 'Attention';
-const ATTENABLE_ATTRIBUTE = 'data-attendable-id';
+const ATTENDABLE_ATTRIBUTE = 'data-attendable-id';
 const ATTENTION_SOURCE_ATTRIBUTE = 'data-is-attention-source';
 
 type AttentionContextValue = {
@@ -25,35 +35,70 @@ type AttentionContextValue = {
 };
 
 const [AttentionContextProvider, useAttentionContext] = createContext<AttentionContextValue>(ATTENTION_NAME, {
-  attention: new AttentionManager(),
+  attention: undefined as unknown as AttentionManager,
   path: [],
 });
 
-const UNKNOWN_ATTENDABLE = { hasAttention: false, isAncestor: false, isRelated: false };
+const UNKNOWN_ATTENDABLE = { hasAttention: false, isAncestor: false, isRelated: false } as Attention;
 
 const useAttention = (attendableId?: string): Attention => {
   const { attention, path } = useAttentionContext(ATTENTION_NAME);
-  if (!attendableId) {
-    return UNKNOWN_ATTENDABLE;
-  }
+  const [state, setState] = useState<Attention>(UNKNOWN_ATTENDABLE);
+
+  const key = useMemo(() => {
+    if (!attendableId) {
+      return undefined;
+    }
+    return [...attendableId.split(ATTENDABLE_PATH_SEPARATOR), ...path];
+  }, [attendableId, path]);
 
-  const current = [...attendableId.split(ATTENDABLE_PATH_SEPARATOR), ...path];
-  return attention.get(current);
+  useEffect(() => {
+    if (!key || !attention) {
+      setState(UNKNOWN_ATTENDABLE);
+      return;
+    }
+
+    // Set initial state.
+    setState(attention.get(key));
+
+    // Subscribe to changes.
+    return attention.subscribe(key, (newState) => {
+      setState(newState);
+    });
+  }, [attention, key]);
+
+  return state;
 };
 
 const useAttended = () => {
   const { attention } = useAttentionContext(ATTENTION_NAME);
-  return attention.current;
+  const [current, setCurrent] = useState<readonly string[]>([]);
+
+  useEffect(() => {
+    if (!attention) {
+      return;
+    }
+
+    // Set initial state.
+    setCurrent(attention.getCurrent());
+
+    // Subscribe to changes.
+    return attention.subscribeCurrent((newCurrent) => {
+      setCurrent(newCurrent);
+    });
+  }, [attention]);
+
+  return current;
 };
 
 /**
- * Computes HTML element attributes to apply so the attention system can detect changes
+ * Computes HTML element attributes to apply so the attention system can detect changes.
  * @param attendableId
  */
 const useAttentionAttributes = (attendableId?: string) => {
   const { hasAttention } = useAttention(attendableId);
   return useMemo(() => {
-    const attributes: Record<string, string | undefined> = { [ATTENABLE_ATTRIBUTE]: attendableId };
+    const attributes: Record<string, string | undefined> = { [ATTENDABLE_ATTRIBUTE]: attendableId };
     if (hasAttention) {
       attributes[ATTENTION_SOURCE_ATTRIBUTE] = 'true';
     }
@@ -77,15 +122,20 @@ const RootAttentionProvider = ({
     onChange: (nextAttended: string[]) => void;
   }>
 >) => {
-  const attention = useDefaultValue(propsAttention, () => new AttentionManager());
+  const registry = useContext(RegistryContext);
+  const attention = useDefaultValue(propsAttention, () => new AttentionManager(registry));
+
   const handleFocus = (event: FocusEvent) => {
+    // NOTE(thure): Use the following to debug focus movement across the app:
+    log('focus', { related: event.relatedTarget, target: event.target });
+
     const selector = [
       '[data-attendable-id]',
       ...Array.from(document.querySelectorAll('[aria-controls]')).map(
         (el) => `[id="${el.getAttribute('aria-controls')}"]`,
       ),
     ].join(',');
-    const prev = attention.current;
+    const prev = attention.getCurrent();
     const next = getAttendables(selector, event.target);
     // TODO(wittjosiah): Not allowing empty state means that the attended item is not strictly guaranteed to be in the DOM.
     //   Currently this depends on the deck in order to ensure that when the attended item is removed something else is attended.
@@ -96,49 +146,9 @@ const RootAttentionProvider = ({
     }
   };
 
-  // NOTE(thure): Use the following to debug the macOS package issue #8540
-
-  // const [startEl, setStartEl] = useState<HTMLElement | null>(null);
-  // const [endEl, setEndEl] = useState<HTMLElement | null>(null);
-  //
-  // const handleEventDebug = useCallback((event: any) => {
-  //   console.log(`[${event.type}]`, event.target, event.currentTarget, [event.clientX, event.clientY]);
-  // }, []);
-  //
-  // const handleStartDebug = useCallback(
-  //   (event: any) => {
-  //     setStartEl(event.target);
-  //     handleEventDebug(event);
-  //   },
-  //   [handleEventDebug],
-  // );
-  //
-  // const handleEndDebug = useCallback(
-  //   (event: any) => {
-  //     setEndEl(event.target);
-  //     handleEventDebug(event);
-  //   },
-  //   [handleEventDebug],
-  // );
-  //
-  // const handleClickDebug = useCallback(
-  //   (event: any) => {
-  //     console.log('[click compare]', startEl, endEl, startEl === endEl);
-  //     handleEventDebug(event);
-  //   },
-  //   [startEl, endEl, handleEventDebug],
-  // );
-
   return (
     <AttentionContextProvider attention={attention} path={[]}>
-      <div
-        role='none'
-        className='contents'
-        onFocusCapture={handleFocus}
-        // onClick={handleClickDebug}
-        // onMouseDown={handleStartDebug}
-        // onMouseUp={handleEndDebug}
-      >
+      <div role='none' className='contents' onFocusCapture={handleFocus}>
         {children}
       </div>
     </AttentionContextProvider>
@@ -193,6 +203,6 @@ export {
   useAttentionAttributes,
   useAttentionPath,
   ATTENTION_NAME,
-  ATTENABLE_ATTRIBUTE,
+  ATTENDABLE_ATTRIBUTE,
   ATTENTION_SOURCE_ATTRIBUTE,
 };