@dxos/react-ui-attention 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

package/src/components/{AttentionProvider.tsx → AttentionProvider/AttentionProvider.tsx}

@@ -11,6 +11,7 @@ import React, {
   type FocusEvent,
   type PropsWithChildren,
   forwardRef,
+  useCallback,
   useContext,
   useEffect,
   useMemo,
@@ -22,8 +23,7 @@ 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';
+import { type Attention, AttentionManager, getAttendables } from '../../attention';
 
 const ATTENTION_NAME = 'Attention';
 const ATTENDABLE_ATTRIBUTE = 'data-attendable-id';
@@ -31,41 +31,34 @@ const ATTENTION_SOURCE_ATTRIBUTE = 'data-w-attention-source';
 
 type AttentionContextValue = {
   attention: AttentionManager;
-  path: string[];
 };
 
 const [AttentionContextProvider, useAttentionContext] = createContext<AttentionContextValue>(ATTENTION_NAME, {
   attention: undefined as unknown as AttentionManager,
-  path: [],
 });
 
 const UNKNOWN_ATTENDABLE = { hasAttention: false, isAncestor: false, isRelated: false } as Attention;
 
+/**
+ * Subscribe to the attention state for a qualified graph ID.
+ */
+// TODO(burdon): Unify with seleciton and change to contextId?
 const useAttention = (attendableId?: string): Attention => {
-  const { attention, path } = useAttentionContext(ATTENTION_NAME);
+  const { attention } = useAttentionContext(ATTENTION_NAME);
   const [state, setState] = useState<Attention>(UNKNOWN_ATTENDABLE);
-
-  const key = useMemo(() => {
-    if (!attendableId) {
-      return undefined;
-    }
-    return [...attendableId.split(ATTENDABLE_PATH_SEPARATOR), ...path];
-  }, [attendableId, path]);
-
   useEffect(() => {
-    if (!key || !attention) {
+    if (!attendableId || !attention) {
       setState(UNKNOWN_ATTENDABLE);
       return;
     }
 
-    // Set initial state.
-    setState(attention.get(key));
+    const currentState = attention.get(attendableId);
+    setState(currentState);
 
-    // Subscribe to changes.
-    return attention.subscribe(key, (newState) => {
+    return attention.subscribe(attendableId, (newState) => {
       setState(newState);
     });
-  }, [attention, key]);
+  }, [attention, attendableId]);
 
   return state;
 };
@@ -73,16 +66,13 @@ const useAttention = (attendableId?: string): Attention => {
 const useAttended = () => {
   const { attention } = useAttentionContext(ATTENTION_NAME);
   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);
     });
@@ -93,7 +83,6 @@ const useAttended = () => {
 
 /**
  * Computes HTML element attributes to apply so the attention system can detect changes.
- * @param attendableId
  */
 const useAttentionAttributes = (attendableId?: string) => {
   const { hasAttention } = useAttention(attendableId);
@@ -107,73 +96,57 @@ const useAttentionAttributes = (attendableId?: string) => {
   }, [attendableId, hasAttention]);
 };
 
-const useAttentionPath = () => {
-  const { path } = useAttentionContext(ATTENTION_NAME);
-  return path;
-};
+type RootAttentionProviderProps = PropsWithChildren<{
+  attention?: AttentionManager;
+  onChange?: (nextAttended: string[]) => void;
+}>;
 
-const RootAttentionProvider = ({
-  children,
-  attention: propsAttention,
-  onChange,
-}: PropsWithChildren<
-  Partial<{
-    attention: AttentionManager;
-    onChange: (nextAttended: string[]) => void;
-  }>
->) => {
+const RootAttentionProvider = ({ children, attention: propsAttention, onChange }: RootAttentionProviderProps) => {
   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.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.
-    // 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);
-    }
-  };
+  const handleFocus = useCallback(
+    (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.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.
+      // 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);
+      }
+    },
+    [attention, onChange],
+  );
 
   return (
-    <AttentionContextProvider attention={attention} path={[]}>
-      <div role='none' className='contents' onFocusCapture={handleFocus}>
+    <AttentionContextProvider attention={attention}>
+      <div className='contents' onFocusCapture={handleFocus}>
         {children}
       </div>
     </AttentionContextProvider>
   );
 };
 
-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 AttendableContainerProps = ThemedClassName<
   ComponentPropsWithRef<'div'> & { id: string; asChild?: boolean }
 >;
 
 /**
- * Note that DeckPlugin and StackPlugin both handle attention on their own, and when rendering content in those cases it
- * is not necessary to also render an `AttendableContainer`. This component is primarily for Storybook stories and other
- * testing scenarios, or the rare cases where an attendable entity is rendered outside of either of those plugins.
+ * Note that DeckPlugin and StackPlugin both handle attention on their own,
+ * and when rendering content in those cases it is not necessary to also render an `AttendableContainer`.
+ * This component is primarily for Storybook stories and other testing scenarios,
+ * or the rare cases where an attendable entity is rendered outside of either of those plugins.
  */
 const AttendableContainer = forwardRef<HTMLDivElement, AttendableContainerProps>(
   ({ id, classNames, children, asChild, ...props }, forwardedRef) => {
@@ -182,8 +155,8 @@ const AttendableContainer = forwardRef<HTMLDivElement, AttendableContainerProps>
     return (
       <Comp
         role='none'
-        {...attentionAttrs}
         {...props}
+        {...attentionAttrs}
         className={mx('dx-attention-surface', props.tabIndex === 0 && 'dx-focus-ring-inset-over-all', classNames)}
         ref={forwardedRef}
       >
@@ -195,14 +168,9 @@ const AttendableContainer = forwardRef<HTMLDivElement, AttendableContainerProps>
 
 export {
   RootAttentionProvider,
-  AttentionProvider,
   AttendableContainer,
   useAttentionContext,
   useAttention,
   useAttended,
   useAttentionAttributes,
-  useAttentionPath,
-  ATTENTION_NAME,
-  ATTENDABLE_ATTRIBUTE,
-  ATTENTION_SOURCE_ATTRIBUTE,
 };

package/src/components/AttentionProvider/index.ts

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

package/src/components/{SelectionProvider.tsx → SelectionProvider/SelectionProvider.tsx}

@@ -15,7 +15,7 @@ import {
   type SelectionMode,
   type SelectionResult,
   defaultSelection,
-} from '../selection';
+} from '../../selection';
 
 const SELECTION_NAME = 'Selection';
 
@@ -23,6 +23,11 @@ type SelectionContextValue = {
   selection: SelectionManager;
 };
 
+// Default value lets consumers like `useSelected` render outside a
+// `SelectionProvider` (e.g. isolated stories) without throwing —
+// `selection` reads as `undefined` and the hook falls back to the
+// per-mode default result. Without this default, Radix `createContext`
+// throws "Selection must be used within Selection" on every consumer.
 const [SelectionContextProvider, useSelectionContext] = createContext<SelectionContextValue>(SELECTION_NAME, {
   selection: undefined as unknown as SelectionManager,
 });
@@ -30,20 +35,20 @@ const [SelectionContextProvider, useSelectionContext] = createContext<SelectionC
 /**
  * Manages selection state across the app for multiple contexts.
  */
-// TODO(burdon): When is the selection removed?
 export const SelectionProvider = ({
   children,
-  selection: propsSelection,
+  selection: selectionProp,
 }: PropsWithChildren<{ selection?: SelectionManager }>) => {
   const registry = useContext(RegistryContext);
-  const selection = useDefaultValue(propsSelection, () => new SelectionManager(registry));
+  const selection = useDefaultValue(selectionProp, () => new SelectionManager(registry));
+
   return <SelectionContextProvider selection={selection}>{children}</SelectionContextProvider>;
 };
 
 /**
  * Get the selection contexts.
  */
-export const useSelectionManager = () => {
+export const useSelectionManager = (): SelectionManager => {
   const { selection } = useSelectionContext(SELECTION_NAME);
   return selection;
 };
@@ -101,11 +106,13 @@ export type UseSelectionActions = {
 /**
  * Provides functions to manage the selection state for multiple contexts.
  */
-// TODO(burdon): Mode not used.
-export const useSelectionActions = (contextIds: string[], mode: SelectionMode = 'multi'): UseSelectionActions => {
-  const stableContextIds = useMemo(() => contextIds, [JSON.stringify(contextIds)]); // TODO(burdon): Avoid stringify.
+export const useSelectionActions = (contextIds: string[]): UseSelectionActions => {
+  const stableContextIds = useMemo(() => contextIds, [JSON.stringify(contextIds)]);
   const { selection } = useSelectionContext(SELECTION_NAME);
 
+  // No-op when rendered outside a `SelectionProvider` (e.g. an isolated
+  // story or a test harness) — `selection` is `undefined` from the
+  // context default value. Matches the pre-co-locate behaviour.
   const singleSelect = useCallback(
     (id: string) => {
       if (!selection) {

package/src/components/SelectionProvider/index.ts

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

package/src/index.ts

@@ -5,4 +5,3 @@
 export * from './attention';
 export * from './components';
 export * from './selection';
-export * from './types';

package/src/selection.ts

@@ -8,15 +8,17 @@ import * as Schema from 'effect/Schema';
 
 import { invariant } from '@dxos/invariant';
 
-// 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()) {
@@ -125,13 +126,14 @@ export class SelectionManager {
     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),

package/src/testing/decorators/withAttention.ts

@@ -20,6 +20,7 @@ export const withAttention = (initialAttendedId?: string): Decorator => {
       () => (initialAttendedId ? new AttentionManager(registry, [initialAttendedId]) : undefined),
       [registry],
     );
+
     return createElement(
       RegistryContext.Provider,
       { value: registry },

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/dist/lib/browser/chunk-PAZBZOO2.mjs

@@ -1,7 +0,0 @@
-// src/types.ts
-var ATTENDABLE_PATH_SEPARATOR = "~";
-
-export {
-  ATTENDABLE_PATH_SEPARATOR
-};
-//# sourceMappingURL=chunk-PAZBZOO2.mjs.map

package/dist/lib/browser/chunk-PAZBZOO2.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/types.ts"],
-  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\n// NOTE: Chosen from RFC 1738's `safe` characters: http://www.faqs.org/rfcs/rfc1738.html\nexport const ATTENDABLE_PATH_SEPARATOR = '~';\n\nexport type Attention = {\n  hasAttention: boolean;\n  isAncestor: boolean;\n  isRelated: boolean;\n};\n\nexport type CurrentState = {\n  current: string[];\n};\n"],
-  "mappings": ";AAKO,IAAMA,4BAA4B;",
-  "names": ["ATTENDABLE_PATH_SEPARATOR"]
-}