@dxos/react-ui-attention 0.6.13 → 0.6.14-main.1366248

package/dist/types/src/components/AttentionProvider.d.ts

@@ -1,22 +1,27 @@
 import React, { type PropsWithChildren } from 'react';
+import { type Attention, AttentionManager } from '../attention';
 declare const ATTENTION_NAME = "Attention";
+declare const ATTENABLE_ATTRIBUTE = "data-attendable-id";
+declare const ATTENTION_SOURCE_ATTRIBUTE = "data-is-attention-source";
 type AttentionContextValue = {
-    attended: Set<string>;
+    attention: AttentionManager;
+    path: string[];
 };
 declare const useAttentionContext: (consumerName: string) => AttentionContextValue;
-declare const useHasAttention: (attendableId?: string) => boolean;
+declare const useAttention: (attendableId?: string) => Attention;
+declare const useAttended: () => string[];
 /**
  * Computes HTML element attributes to apply so the attention system can detect changes
  * @param attendableId
  */
-declare const createAttendableAttributes: (attendableId?: string) => {
-    'data-attendable-id': string | undefined;
-};
-declare const AttentionProvider: ({ children, attended: propsAttended, defaultAttended, onChangeAttend, }: PropsWithChildren<Partial<{
-    attended: Set<string>;
-    onChangeAttend: (nextAttended: Set<string>) => void;
-    defaultAttended: Set<string>;
+declare const useAttendableAttributes: (attendableId?: string) => Record<string, string | undefined>;
+declare const useAttentionPath: () => string[];
+declare const RootAttentionProvider: ({ children, attention: propsAttention, onChange, }: PropsWithChildren<Partial<{
+    attention: AttentionManager;
+    onChange: (nextAttended: string[]) => void;
 }>>) => React.JSX.Element;
-export { AttentionProvider, useAttentionContext, useHasAttention, createAttendableAttributes, ATTENTION_NAME };
-export type { AttentionContextValue };
+declare const AttentionProvider: ({ id, children }: PropsWithChildren<{
+    id: string;
+}>) => React.JSX.Element;
+export { RootAttentionProvider, AttentionProvider, useAttentionContext, useAttention, useAttended, useAttendableAttributes, useAttentionPath, ATTENTION_NAME, ATTENABLE_ATTRIBUTE, ATTENTION_SOURCE_ATTRIBUTE, };
 //# sourceMappingURL=AttentionProvider.d.ts.map

package/dist/types/src/components/AttentionProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AttentionProvider.d.ts","sourceRoot":"","sources":["../../../../src/components/AttentionProvider.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,EAAwD,KAAK,iBAAiB,EAAY,MAAM,OAAO,CAAC;AAEtH,QAAA,MAAM,cAAc,cAAc,CAAC;AAEnC,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB,CAAC;AAEF,QAAA,MAAiC,mBAAmB,iDAElD,CAAC;AAEH,QAAA,MAAM,eAAe,kBAAmB,MAAM,YAG7C,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,0BAA0B,kBAAmB,MAAM;;CAExD,CAAC;AA4BF,QAAA,MAAM,iBAAiB,4EAKpB,iBAAiB,CAClB,OAAO,CAAC;IACN,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,cAAc,EAAE,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IACpD,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B,CAAC,CACH,sBAyBA,CAAC;AAEF,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,eAAe,EAAE,0BAA0B,EAAE,cAAc,EAAE,CAAC;AAE/G,YAAY,EAAE,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"AttentionProvider.d.ts","sourceRoot":"","sources":["../../../../src/components/AttentionProvider.tsx"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,EAA4B,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAIhF,OAAO,EAAE,KAAK,SAAS,EAAE,gBAAgB,EAAkB,MAAM,cAAc,CAAC;AAEhF,QAAA,MAAM,cAAc,cAAc,CAAC;AACnC,QAAA,MAAM,mBAAmB,uBAAuB,CAAC;AACjD,QAAA,MAAM,0BAA0B,6BAA6B,CAAC;AAE9D,KAAK,qBAAqB,GAAG;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF,QAAA,MAAiC,mBAAmB,iDAGlD,CAAC;AAIH,QAAA,MAAM,YAAY,kBAAmB,MAAM,KAAG,SAQ7C,CAAC;AAEF,QAAA,MAAM,WAAW,gBAGhB,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,uBAAuB,kBAAmB,MAAM,uCAUrD,CAAC;AAEF,QAAA,MAAM,gBAAgB,gBAGrB,CAAC;AAEF,QAAA,MAAM,qBAAqB,uDAIxB,iBAAiB,CAClB,OAAO,CAAC;IACN,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAC5C,CAAC,CACH,sBA0BA,CAAC;AAEF,QAAA,MAAM,iBAAiB,qBAAsB,iBAAiB,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,sBAS7E,CAAC;AAEF,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,0BAA0B,GAC3B,CAAC"}

package/dist/types/src/components/AttentionProvider.stories.d.ts

@@ -0,0 +1,10 @@
+import '@dxos-theme';
+import React from 'react';
+declare const _default: {
+    title: string;
+    render: () => React.JSX.Element;
+    decorators: import("@storybook/react/*").Decorator[];
+};
+export default _default;
+export declare const Default: {};
+//# sourceMappingURL=AttentionProvider.stories.d.ts.map

package/dist/types/src/components/AttentionProvider.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttentionProvider.stories.d.ts","sourceRoot":"","sources":["../../../../src/components/AttentionProvider.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,aAAa,CAAC;AAErB,OAAO,KAAK,MAAM,OAAO,CAAC;;;;;;AA4B1B,wBAIE;AAEF,eAAO,MAAM,OAAO,IAAK,CAAC"}

package/dist/types/src/index.d.ts

@@ -1,2 +1,3 @@
+export * from './attention';
 export * from './components';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/types/src/testing/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './withAttention';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/testing/decorators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/testing/decorators/index.ts"],"names":[],"mappings":"AAIA,cAAc,iBAAiB,CAAC"}

package/dist/types/src/testing/decorators/withAttention.d.ts

@@ -0,0 +1,3 @@
+import { type Decorator } from '@storybook/react';
+export declare const withAttention: Decorator;
+//# sourceMappingURL=withAttention.d.ts.map

package/dist/types/src/testing/decorators/withAttention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withAttention.d.ts","sourceRoot":"","sources":["../../../../../src/testing/decorators/withAttention.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAKlD,eAAO,MAAM,aAAa,EAAE,SAE3B,CAAC"}

package/dist/types/src/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './decorators';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAIA,cAAc,cAAc,CAAC"}

package/package.json

@@ -1,26 +1,36 @@
 {
   "name": "@dxos/react-ui-attention",
-  "version": "0.6.13",
+  "version": "0.6.14-main.1366248",
   "description": "Signifier components and providers for attention system.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "license": "MIT",
   "author": "DXOS.org",
+  "sideEffects": true,
   "exports": {
     ".": {
-      "browser": "./dist/lib/browser/index.mjs",
-      "types": "./dist/types/src/index.d.ts"
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/types/src/testing/index.d.ts",
+      "browser": "./dist/lib/browser/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
   "typesVersions": {
-    "*": {}
+    "*": {
+      "testing": [
+        "dist/types/src/testing/index.d.ts"
+      ]
+    }
   },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
+    "@preact/signals-core": "^1.6.0",
     "@radix-ui/primitive": "^1.0.0",
     "@radix-ui/react-compose-refs": "^1.0.0",
     "@radix-ui/react-context": "^1.0.0",
@@ -28,9 +38,8 @@
     "@radix-ui/react-primitive": "^1.0.2",
     "@radix-ui/react-slot": "^1.0.1",
     "@radix-ui/react-use-controllable-state": "^1.0.0",
-    "@dxos/react-ui": "0.6.13",
-    "@dxos/util": "0.6.13",
-    "@dxos/react-ui-theme": "0.6.13"
+    "@dxos/echo-schema": "0.6.14-main.1366248",
+    "@dxos/util": "0.6.14-main.1366248"
   },
   "devDependencies": {
     "@phosphor-icons/react": "^2.1.5",
@@ -38,15 +47,19 @@
     "@types/react-dom": "~18.2.0",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "vite": "^5.3.4",
-    "@dxos/random": "0.6.13",
-    "@dxos/storybook-utils": "0.6.13",
-    "@dxos/app-graph": "0.6.13"
+    "vite": "5.4.7",
+    "@dxos/app-graph": "0.6.14-main.1366248",
+    "@dxos/random": "0.6.14-main.1366248",
+    "@dxos/react-ui": "0.6.14-main.1366248",
+    "@dxos/react-ui-theme": "0.6.14-main.1366248",
+    "@dxos/storybook-utils": "0.6.14-main.1366248"
   },
   "peerDependencies": {
     "@phosphor-icons/react": "^2.1.5",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "~18.2.0",
+    "react-dom": "~18.2.0",
+    "@dxos/react-ui": "0.6.14-main.1366248",
+    "@dxos/react-ui-theme": "0.6.14-main.1366248"
   },
   "publishConfig": {
     "access": "public"

package/src/attention.test.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { describe, test, expect } 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']);
+
+    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 });
+    expect(attention.get(['c'])).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
+    expect(attention.get(['a', 'b', 'c'])).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
+
+    expect(attention.get(['b'])).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
+  });
+
+  test('current returns last updated key', () => {
+    const attention = new AttentionManager();
+
+    expect(attention.current).to.deep.equal([]);
+
+    attention.update(['a', 'b', 'c']);
+
+    expect(attention.current).to.deep.equal(['a', 'b', 'c']);
+  });
+
+  test('keys returns all stored attendables', () => {
+    const attention = new AttentionManager();
+
+    expect(attention.keys()).to.deep.equal([]);
+
+    attention.update(['a']);
+
+    expect(attention.keys()).to.deep.equal([['a']]);
+
+    attention.update(['a', 'b']);
+
+    expect(attention.keys()).to.deep.equal([['a'], ['b'], ['a', 'b']]);
+  });
+
+  test('get returns attention object for a given key', () => {
+    const attention = new AttentionManager();
+
+    expect(attention.get(['a'])).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
+
+    attention.update(['a']);
+
+    expect(attention.get(['a'])).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
+  });
+});

package/src/attention.ts

@@ -0,0 +1,132 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { untracked } from '@preact/signals-core';
+
+import { create, type ReactiveObject, S } from '@dxos/echo-schema';
+import { ComplexMap } from '@dxos/util';
+
+export const AttentionSchema = S.mutable(
+  S.Struct({
+    hasAttention: S.Boolean,
+    isAncestor: S.Boolean,
+    isRelated: S.Boolean,
+  }),
+);
+
+export type Attention = S.Schema.Type<typeof AttentionSchema>;
+
+// TODO(wittjosiah): Use mosaic path utility?
+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.
+  // The lookup is not a reactive object to ensure that attention for each path is subscribable independently.
+  private readonly _map = new ComplexMap<string[], ReactiveObject<Attention>>(stringKey);
+  private readonly _state = create<{ current: string[] }>({ current: [] });
+
+  constructor(initial: string[] = []) {
+    if (initial.length > 0) {
+      this.update(initial);
+    }
+  }
+
+  /**
+   * Currently attended element.
+   */
+  get current() {
+    return this._state.current;
+  }
+
+  /**
+   * All attention paths.
+   */
+  keys() {
+    return Array.from(this._map.keys());
+  }
+
+  /**
+   * Get the attention state for a given path.
+   */
+  get(key: string[]): ReactiveObject<Attention> {
+    const object = this._map.get(key);
+    if (object) {
+      return object;
+    }
+
+    const newObject = create(AttentionSchema, { hasAttention: false, isAncestor: false, isRelated: false });
+    this._map.set(key, newObject);
+    return newObject;
+  }
+
+  /**
+   * Update the currently attended element.
+   */
+  update(nextKey: string[]) {
+    const currentKey = untracked(() => this.current);
+    const currentRelatedTo = currentKey[0];
+    const nextRelatedTo = nextKey[0];
+
+    // Ensure related attention object is initialized.
+    this.get([nextRelatedTo]);
+
+    const currentRelatedKeys = this.keys().filter((key) => key[0] === currentRelatedTo);
+    const nextRelatedKeys = this.keys().filter(
+      (key) => key[0] === nextRelatedTo && stringKey(key) !== stringKey(nextKey),
+    );
+    const prevRelatedKeys = currentRelatedKeys.filter(
+      (curr) => !nextRelatedKeys.find((next) => stringKey(curr) === stringKey(next)),
+    );
+
+    const currentAncestorKeys = currentKey.slice(1).map((_, i) => currentKey.slice(i + 1, currentKey.length));
+    const nextAncestorKeys = nextKey.slice(1).map((_, i) => nextKey.slice(i + 1, nextKey.length));
+    const prevAncestorKeys = currentAncestorKeys.filter(
+      (curr) => !nextAncestorKeys.find((next) => stringKey(curr) === stringKey(next)),
+    );
+
+    this._state.current = nextKey;
+    prevRelatedKeys.forEach((key) => this._set(key, {}));
+    prevAncestorKeys.forEach((key) => this._set(key, {}));
+    nextRelatedKeys.forEach((key) => this._set(key, { isRelated: true }));
+    nextAncestorKeys.forEach((key) => this._set(key, { isAncestor: true }));
+    this._set(nextKey, { hasAttention: true });
+  }
+
+  private _set(key: string[], attention: Partial<Attention>) {
+    const object = this.get(key);
+    object.hasAttention = attention.hasAttention ?? false;
+    object.isAncestor = attention.isAncestor ?? false;
+    object.isRelated = attention.isRelated ?? false;
+  }
+}
+
+/**
+ * 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.
+  const closestAttendable = cursor.closest(selector);
+  if (closestAttendable) {
+    const attendableId = closestAttendable.getAttribute('data-attendable-id');
+    if (!attendableId) {
+      // this has an id of an aria-controls elsewhere on the page, move cursor to that trigger
+      const trigger = document.querySelector(`[aria-controls="${closestAttendable.getAttribute('id')}"]`);
+      if (!trigger) {
+        return acc;
+      } else {
+        return getAttendables(selector, trigger, acc);
+      }
+    } else {
+      acc.push(attendableId);
+      // (attempt tail recursion)
+      return !closestAttendable.parentElement ? acc : getAttendables(selector, closestAttendable.parentElement, acc);
+    }
+  }
+
+  return [...new Set(acc)];
+};

package/src/components/AttentionGlyph.stories.tsx

@@ -10,12 +10,12 @@ import { withTheme } from '@dxos/storybook-utils';
 
 import { AttentionGlyph } from './AttentionGlyph';
 
-type StorybookAttentionGlyphProps = {
+type StoryProps = {
   current?: boolean;
   attention?: boolean;
 };
 
-const StorybookAttentionGlyph = ({ current, attention }: StorybookAttentionGlyphProps) => {
+const Story = ({ current, attention }: StoryProps) => {
   const itemAttrs = {
     ...(current && { 'aria-current': 'page' as const }),
     ...(attention && { 'data-attention': 'true' }),
@@ -36,17 +36,20 @@ const StorybookAttentionGlyph = ({ current, attention }: StorybookAttentionGlyph
 };
 
 export default {
-  title: 'react-ui-deck/AttentionGlyph',
-  component: StorybookAttentionGlyph,
+  title: 'ui/react-ui-attention/AttentionGlyph',
+  component: AttentionGlyph,
+  render: Story,
   decorators: [withTheme],
 };
 
 export const Default = {
   args: {},
 };
+
 export const Current = {
   args: { current: true },
 };
+
 export const Attention = {
   args: { current: true, attention: true },
 };

package/src/components/AttentionGlyph.tsx

@@ -9,7 +9,7 @@ import { type ThemedClassName } from '@dxos/react-ui';
 import { mx } from '@dxos/react-ui-theme';
 
 const attentionGlyphStyles =
-  'inline-block rounded-sm is-3 bs-3 bg-transparent text-accentText transition-colors [[data-attention=true]_&]:bg-accentSurface [[data-attention=true]_&]:fg-inverse [[aria-current][data-attention=true]_&]:bg-accentSurface [[aria-current][data-attention=true]_&]:fg-inverse';
+  'inline-block rounded-sm is-3 bs-3 bg-transparent text-accentText transition-colors [[data-attention=true]_&]:bg-accentSurface [[data-attention=true]_&]:text-inverse [[aria-current][data-attention=true]_&]:bg-accentSurface [[aria-current][data-attention=true]_&]:text-inverse';
 
 const presenceIconStyles =
   'is-3 bs-3 group-[[aria-current]_&:hover]/attentionGlyphButton:hidden group-[[aria-current]_&:focus]/attentionGlyphButton:hidden group-[[data-attention=true]_&:hover]/attentionGlyphButton:hidden group-[[data-attention=true]_&:focus]/attentionGlyphButton:hidden group-[[aria-current][data-attention=true]_&:hover]/attentionGlyphButton:hidden group-[[aria-current][data-attention=true]_&:focus]/attentionGlyphButton:hidden';

package/src/components/AttentionProvider.stories.tsx

@@ -0,0 +1,41 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import '@dxos-theme';
+
+import React from 'react';
+
+import { withTheme } from '@dxos/storybook-utils';
+
+import { useAttendableAttributes } from './AttentionProvider';
+import { withAttention } from '../testing';
+
+const Attendable = ({ id }: { id: string }) => {
+  const attendableAttrs = useAttendableAttributes(id);
+
+  return (
+    <div {...attendableAttrs}>
+      <textarea className='attention-surface resize-none' placeholder={id} />
+    </div>
+  );
+};
+
+const Story = () => {
+  return (
+    <div className='flex justify-between'>
+      <Attendable id='1' />
+      <Attendable id='2' />
+      <Attendable id='3' />
+      <Attendable id='4' />
+    </div>
+  );
+};
+
+export default {
+  title: 'ui/react-ui-attention/AttentionProvider',
+  render: Story,
+  decorators: [withTheme, withAttention],
+};
+
+export const Default = {};

package/src/components/AttentionProvider.tsx

@@ -6,76 +6,75 @@
 
 // eslint-disable-next-line unused-imports/no-unused-imports
 import { createContext, type Scope, type CreateScope } from '@radix-ui/react-context';
-import { useControllableState } from '@radix-ui/react-use-controllable-state';
-// eslint-disable-next-line unused-imports/no-unused-imports
-import React, { ComponentProps, type FocusEvent, type HTMLAttributes, type PropsWithChildren, useState } from 'react';
+import React, { useMemo, type FocusEvent, type PropsWithChildren } from 'react';
+
+import { useDefaultValue } from '@dxos/react-ui';
+
+import { type Attention, AttentionManager, getAttendables } from '../attention';
 
 const ATTENTION_NAME = 'Attention';
+const ATTENABLE_ATTRIBUTE = 'data-attendable-id';
+const ATTENTION_SOURCE_ATTRIBUTE = 'data-is-attention-source';
 
 type AttentionContextValue = {
-  attended: Set<string>;
+  attention: AttentionManager;
+  path: string[];
 };
 
 const [AttentionContextProvider, useAttentionContext] = createContext<AttentionContextValue>(ATTENTION_NAME, {
-  attended: new Set(),
+  attention: new AttentionManager(),
+  path: [],
 });
 
-const useHasAttention = (attendableId?: string) => {
-  const { attended } = useAttentionContext(ATTENTION_NAME);
-  return attendableId ? attended.has(attendableId) : false;
+const UNKNOWN_ATTENDABLE = { hasAttention: false, isAncestor: false, isRelated: false };
+
+const useAttention = (attendableId?: string): Attention => {
+  const { attention, path } = useAttentionContext(ATTENTION_NAME);
+  if (!attendableId) {
+    return UNKNOWN_ATTENDABLE;
+  }
+
+  const current = [attendableId, ...path];
+  return attention.get(current);
+};
+
+const useAttended = () => {
+  const { attention } = useAttentionContext(ATTENTION_NAME);
+  return attention.current;
 };
 
 /**
  * Computes HTML element attributes to apply so the attention system can detect changes
  * @param attendableId
  */
-const createAttendableAttributes = (attendableId?: string) => {
-  return { 'data-attendable-id': attendableId };
+const useAttendableAttributes = (attendableId?: string) => {
+  const { hasAttention } = useAttention(attendableId);
+  return useMemo(() => {
+    const attributes: Record<string, string | undefined> = { [ATTENABLE_ATTRIBUTE]: attendableId };
+    if (hasAttention) {
+      attributes[ATTENTION_SOURCE_ATTRIBUTE] = 'true';
+    }
+
+    return attributes;
+  }, [attendableId, hasAttention]);
 };
 
-/**
- * Accumulates all attendable id’s between the element provided and the root, inclusive.
- */
-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.
-  const closestAttendable = cursor.closest(selector);
-  if (!closestAttendable) {
-    return acc;
-  } else {
-    const attendableId = closestAttendable.getAttribute('data-attendable-id');
-    if (!attendableId) {
-      // this has an id of an aria-controls elsewhere on the page, move cursor to that trigger
-      const trigger = document.querySelector(`[aria-controls="${closestAttendable.getAttribute('id')}"]`);
-      if (!trigger) {
-        return acc;
-      } else {
-        return getAttendables(selector, trigger, acc);
-      }
-    } else {
-      acc.push(attendableId);
-      // (attempt tail recursion)
-      return !closestAttendable.parentElement ? acc : getAttendables(selector, closestAttendable.parentElement, acc);
-    }
-  }
+const useAttentionPath = () => {
+  const { path } = useAttentionContext(ATTENTION_NAME);
+  return path;
 };
 
-const AttentionProvider = ({
+const RootAttentionProvider = ({
   children,
-  attended: propsAttended,
-  defaultAttended,
-  onChangeAttend,
+  attention: propsAttention,
+  onChange,
 }: PropsWithChildren<
   Partial<{
-    attended: Set<string>;
-    onChangeAttend: (nextAttended: Set<string>) => void;
-    defaultAttended: Set<string>;
+    attention: AttentionManager;
+    onChange: (nextAttended: string[]) => void;
   }>
 >) => {
-  const [attended = new Set(), setAttended] = useControllableState<Set<string>>({
-    prop: propsAttended,
-    defaultProp: defaultAttended,
-    onChange: onChangeAttend,
-  });
+  const attention = useDefaultValue(propsAttention, () => new AttentionManager());
   const handleFocus = (event: FocusEvent) => {
     const selector = [
       '[data-attendable-id]',
@@ -83,13 +82,18 @@ const AttentionProvider = ({
         (el) => `[id="${el.getAttribute('aria-controls')}"]`,
       ),
     ].join(',');
-    const nextAttended = new Set(getAttendables(selector, event.target));
-    const [prev, next] = [Array.from(attended), Array.from(nextAttended)];
-    // Only update state if the result is different.
-    (prev.length !== next.length || !!prev.find((id, index) => next[index] !== id)) && setAttended(nextAttended);
+    const prev = attention.current;
+    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.
+    // Only update state if the result is different and not empty.
+    if (next.length > 0 && (prev.length !== next.length || !!prev.find((id, index) => next[index] !== id))) {
+      attention.update(next);
+      onChange?.(next);
+    }
   };
   return (
-    <AttentionContextProvider attended={attended}>
+    <AttentionContextProvider attention={attention} path={[]}>
       <div role='none' className='contents' onFocusCapture={handleFocus}>
         {children}
       </div>
@@ -97,6 +101,26 @@ const AttentionProvider = ({
   );
 };
 
-export { AttentionProvider, useAttentionContext, useHasAttention, createAttendableAttributes, ATTENTION_NAME };
+const AttentionProvider = ({ id, children }: PropsWithChildren<{ id: string }>) => {
+  const { attention, path } = useAttentionContext(ATTENTION_NAME);
+  const nextPath = useMemo(() => [id, ...path], [id, path]);
+
+  return (
+    <AttentionContextProvider attention={attention} path={nextPath}>
+      {children}
+    </AttentionContextProvider>
+  );
+};
 
-export type { AttentionContextValue };
+export {
+  RootAttentionProvider,
+  AttentionProvider,
+  useAttentionContext,
+  useAttention,
+  useAttended,
+  useAttendableAttributes,
+  useAttentionPath,
+  ATTENTION_NAME,
+  ATTENABLE_ATTRIBUTE,
+  ATTENTION_SOURCE_ATTRIBUTE,
+};

package/src/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './attention';
 export * from './components';

package/src/testing/decorators/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './withAttention';