@dxos/react-ui-attention 0.8.4-main.ead640a → 0.8.4-main.f466a3d56e

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

@@ -6,13 +6,20 @@ import { type Primitive } from '@radix-ui/react-primitive';
 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';
+const attentionGlyphStyles = mx(
+  'inline-block rounded-xs w-3 h-3 bg-transparent text-accent-text transition-colors',
+  '[[data-contains-attended=true]_&]:bg-attention-contains',
+  '[[data-attention=true]_&]:bg-accent-surface',
+  '[[data-attention=true]_&]:text-accent-foreground',
+  '[[aria-current][data-attention=true]_&]:bg-accent-surface',
+  '[[aria-current][data-attention=true]_&]:text-accent-foreground',
+  '[[aria-selected="true"][data-attention=true]_&]:bg-accent-surface',
+  '[[aria-selected="true"][data-attention=true]_&]:text-accent-foreground',
+);
 
-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';
+const presenceIconStyles = mx('w-3 h-3');
 
 const PresenceOne = () => {
   return (
@@ -87,7 +94,7 @@ export const AttentionGlyph = forwardRef<HTMLSpanElement, AttentionGlyphProps>(
     ) : null;
 
     return (
-      <div role='none' className='flex' data-attention={attended} data-contains-attended={containsAttended}>
+      <div className='flex group' data-attention={attended} data-contains-attended={containsAttended}>
         <span role='none' {...props} className={mx(attentionGlyphStyles, classNames)} ref={forwardedRef}>
           {icon}
         </span>

package/src/components/AttentionGlyph/index.ts

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

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

@@ -7,8 +7,7 @@ import React from 'react';
 
 import { withTheme } from '@dxos/react-ui/testing';
 
-import { withAttention } from '../testing';
-
+import { withAttention } from '../../testing';
 import { useAttentionAttributes } from './AttentionProvider';
 
 const Attendable = ({ id }: { id: string }) => {
@@ -16,7 +15,7 @@ const Attendable = ({ id }: { id: string }) => {
 
   return (
     <div {...attentionAttrs}>
-      <textarea className='attention-surface resize-none' placeholder={id} />
+      <textarea className='dx-attention-surface resize-none' placeholder={id} />
     </div>
   );
 };
@@ -35,7 +34,7 @@ const Story = () => {
 const meta = {
   title: 'ui/react-ui-attention/AttentionProvider',
   render: Story,
-  decorators: [withTheme, withAttention],
+  decorators: [withTheme(), withAttention()],
 } satisfies Meta;
 
 export default meta;

package/src/components/AttentionProvider/AttentionProvider.tsx

@@ -0,0 +1,176 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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, {
+  type ComponentPropsWithRef,
+  type FocusEvent,
+  type PropsWithChildren,
+  forwardRef,
+  useCallback,
+  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 { type Attention, AttentionManager, getAttendables } from '../../attention';
+
+const ATTENTION_NAME = 'Attention';
+const ATTENDABLE_ATTRIBUTE = 'data-attendable-id';
+const ATTENTION_SOURCE_ATTRIBUTE = 'data-w-attention-source';
+
+type AttentionContextValue = {
+  attention: AttentionManager;
+};
+
+const [AttentionContextProvider, useAttentionContext] = createContext<AttentionContextValue>(ATTENTION_NAME, {
+  attention: undefined as unknown as AttentionManager,
+});
+
+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 } = useAttentionContext(ATTENTION_NAME);
+  const [state, setState] = useState<Attention>(UNKNOWN_ATTENDABLE);
+  useEffect(() => {
+    if (!attendableId || !attention) {
+      setState(UNKNOWN_ATTENDABLE);
+      return;
+    }
+
+    const currentState = attention.get(attendableId);
+    setState(currentState);
+
+    return attention.subscribe(attendableId, (newState) => {
+      setState(newState);
+    });
+  }, [attention, attendableId]);
+
+  return state;
+};
+
+const useAttended = () => {
+  const { attention } = useAttentionContext(ATTENTION_NAME);
+  const [current, setCurrent] = useState<readonly string[]>([]);
+  useEffect(() => {
+    if (!attention) {
+      return;
+    }
+
+    setCurrent(attention.getCurrent());
+
+    return attention.subscribeCurrent((newCurrent) => {
+      setCurrent(newCurrent);
+    });
+  }, [attention]);
+
+  return current;
+};
+
+/**
+ * Computes HTML element attributes to apply so the attention system can detect changes.
+ */
+const useAttentionAttributes = (attendableId?: string) => {
+  const { hasAttention } = useAttention(attendableId);
+  return useMemo(() => {
+    const attributes: Record<string, string | undefined> = { [ATTENDABLE_ATTRIBUTE]: attendableId };
+    if (hasAttention) {
+      attributes[ATTENTION_SOURCE_ATTRIBUTE] = 'true';
+    }
+
+    return attributes;
+  }, [attendableId, hasAttention]);
+};
+
+type RootAttentionProviderProps = PropsWithChildren<{
+  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 = 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}>
+      <div className='contents' onFocusCapture={handleFocus}>
+        {children}
+      </div>
+    </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.
+ */
+const AttendableContainer = forwardRef<HTMLDivElement, AttendableContainerProps>(
+  ({ id, classNames, children, asChild, ...props }, forwardedRef) => {
+    const attentionAttrs = useAttentionAttributes(id);
+    const Comp = asChild ? Slot : Primitive.div;
+    return (
+      <Comp
+        role='none'
+        {...props}
+        {...attentionAttrs}
+        className={mx('dx-attention-surface', props.tabIndex === 0 && 'dx-focus-ring-inset-over-all', classNames)}
+        ref={forwardedRef}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+export {
+  RootAttentionProvider,
+  AttendableContainer,
+  useAttentionContext,
+  useAttention,
+  useAttended,
+  useAttentionAttributes,
+};

package/src/components/AttentionProvider/index.ts

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

package/src/components/SelectionProvider/SelectionProvider.tsx

@@ -0,0 +1,174 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import { createContext } from '@radix-ui/react-context';
+import * as Match from 'effect/Match';
+import React, { type PropsWithChildren, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+
+import { useDefaultValue } from '@dxos/react-hooks';
+
+import {
+  type Selection,
+  SelectionManager,
+  type SelectionMode,
+  type SelectionResult,
+  defaultSelection,
+} from '../../selection';
+
+const SELECTION_NAME = 'Selection';
+
+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,
+});
+
+/**
+ * Manages selection state across the app for multiple contexts.
+ */
+export const SelectionProvider = ({
+  children,
+  selection: selectionProp,
+}: PropsWithChildren<{ selection?: SelectionManager }>) => {
+  const registry = useContext(RegistryContext);
+  const selection = useDefaultValue(selectionProp, () => new SelectionManager(registry));
+
+  return <SelectionContextProvider selection={selection}>{children}</SelectionContextProvider>;
+};
+
+/**
+ * Get the selection contexts.
+ */
+export const useSelectionManager = (): SelectionManager => {
+  const { selection } = useSelectionContext(SELECTION_NAME);
+  return selection;
+};
+
+const getDefaultResult = <T extends SelectionMode>(mode: T): SelectionResult<T> => {
+  return Match.type<Selection>().pipe(
+    Match.when({ mode: 'single' }, (selection) => selection.id),
+    Match.when({ mode: 'multi' }, (selection) => selection.ids),
+    Match.when({ mode: 'range' }, (selection) =>
+      selection.from && selection.to ? { from: selection.from, to: selection.to } : undefined,
+    ),
+    Match.when({ mode: 'multi-range' }, (selection) => selection.ranges),
+    Match.exhaustive,
+  )(defaultSelection(mode)) as SelectionResult<T>;
+};
+
+/**
+ * Get the selected objects for a given context.
+ */
+export const useSelected = <T extends SelectionMode>(
+  contextId?: string,
+  mode: T = 'multi' as T,
+): SelectionResult<T> => {
+  const { selection } = useSelectionContext(SELECTION_NAME);
+  const [state, setState] = useState<SelectionResult<T>>(() =>
+    contextId && selection ? selection.getSelected(contextId, mode) : getDefaultResult(mode),
+  );
+
+  useEffect(() => {
+    if (!contextId || !selection) {
+      setState(getDefaultResult(mode));
+      return;
+    }
+
+    // Set initial state.
+    setState(selection.getSelected(contextId, mode));
+
+    // Subscribe to changes.
+    return selection.subscribe(() => {
+      setState(selection.getSelected(contextId, mode));
+    });
+  }, [selection, contextId, mode]);
+
+  return state;
+};
+
+export type UseSelectionActions = {
+  singleSelect: (id: string) => void;
+  multiSelect: (ids: string[]) => void;
+  rangeSelect: (from: string, to: string) => void;
+  toggle: (id: string) => void;
+  clear: () => void;
+};
+
+/**
+ * Provides functions to manage the selection state for multiple contexts.
+ */
+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) {
+        return;
+      }
+      for (const contextId of stableContextIds) {
+        selection.updateSingle(contextId, id);
+      }
+    },
+    [selection, stableContextIds],
+  );
+
+  const multiSelect = useCallback(
+    (ids: string[]) => {
+      if (!selection) {
+        return;
+      }
+      for (const contextId of stableContextIds) {
+        selection.updateMulti(contextId, ids);
+      }
+    },
+    [selection, stableContextIds],
+  );
+
+  const rangeSelect = useCallback(
+    (from: string, to: string) => {
+      if (!selection) {
+        return;
+      }
+      for (const contextId of stableContextIds) {
+        selection.updateRange(contextId, from, to);
+      }
+    },
+    [selection, stableContextIds],
+  );
+
+  const toggle = useCallback(
+    (id: string) => {
+      if (!selection) {
+        return;
+      }
+      for (const contextId of stableContextIds) {
+        selection.toggleSelection(contextId, id);
+      }
+    },
+    [selection, stableContextIds],
+  );
+
+  const clear = useCallback(() => {
+    if (!selection) {
+      return;
+    }
+    for (const contextId of stableContextIds) {
+      selection.clearSelection(contextId);
+    }
+  }, [selection, stableContextIds]);
+
+  return { singleSelect, multiSelect, rangeSelect, toggle, clear };
+};

package/src/components/SelectionProvider/index.ts

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