@dxos/react-ui 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

package/src/components/Tooltip/Tooltip.tsx

@@ -3,6 +3,7 @@
 //
 
 // This is based upon `@radix-ui/react-tooltip` fetched 17 March 2025 at https://github.com/radix-ui/primitives at commit 6e75e11.
+// TODO(burdon): Replace with https://ui.shadcn.com/docs/components/radix/tooltip
 
 import { composeEventHandlers } from '@radix-ui/primitive';
 import { useComposedRefs } from '@radix-ui/react-compose-refs';
@@ -11,7 +12,7 @@ import type { Scope } from '@radix-ui/react-context';
 import { DismissableLayer } from '@radix-ui/react-dismissable-layer';
 import { useId } from '@radix-ui/react-id';
 import * as PopperPrimitive from '@radix-ui/react-popper';
-import { createPopperScope, type PopperAnchorProps } from '@radix-ui/react-popper';
+import { type PopperAnchorProps, createPopperScope } from '@radix-ui/react-popper';
 import { Portal as PortalPrimitive } from '@radix-ui/react-portal';
 import { Presence } from '@radix-ui/react-presence';
 import { Primitive } from '@radix-ui/react-primitive';
@@ -21,12 +22,12 @@ import { useControllableState } from '@radix-ui/react-use-controllable-state';
 import * as VisuallyHiddenPrimitive from '@radix-ui/react-visually-hidden';
 import React, {
   type ComponentPropsWithoutRef,
-  type ElementRef,
+  type ComponentRef,
   type FC,
+  type ReactNode,
+  type RefObject,
   type SyntheticEvent,
   forwardRef,
-  type MutableRefObject,
-  type ReactNode,
   useCallback,
   useEffect,
   useMemo,
@@ -40,9 +41,9 @@ type TooltipScopedProps<P = {}> = P & { __scopeTooltip?: Scope };
 const [createTooltipContext, createTooltipScope] = createContextScope('Tooltip', [createPopperScope]);
 const usePopperScope = createPopperScope();
 
-/* -------------------------------------------------------------------------------------------------
- * Tooltip
- * ----------------------------------------------------------------------------------------------- */
+//
+// Tooltip
+//
 
 const DEFAULT_DELAY_DURATION = 700;
 const TOOLTIP_OPEN = 'tooltip.open';
@@ -53,19 +54,19 @@ type TooltipContextValue = {
   open: boolean;
   stateAttribute: 'closed' | 'delayed-open' | 'instant-open';
   trigger: TooltipTriggerElement | null;
-  onTriggerChange(trigger: TooltipTriggerElement | null): void;
+  onTriggerChange(trigger: TooltipTriggerElement | null, content?: ReactNode, side?: TooltipSide): void;
   onTriggerEnter(): void;
   onTriggerLeave(): void;
   onOpen(): void;
   onClose(): void;
   onPointerInTransitChange(inTransit: boolean): void;
-  isPointerInTransitRef: MutableRefObject<boolean>;
+  isPointerInTransitRef: RefObject<boolean>;
   disableHoverableContent: boolean;
 };
 
 const [TooltipContextProvider, useTooltipContext] = createTooltipContext<TooltipContextValue>(TOOLTIP_NAME);
 
-interface TooltipProviderProps {
+type TooltipProviderProps = {
   children?: ReactNode;
   open?: boolean;
   defaultOpen?: boolean;
@@ -86,7 +87,7 @@ interface TooltipProviderProps {
    * @defaultValue 300
    */
   skipDelayDuration?: number;
-}
+};
 
 const TooltipProvider: FC<TooltipProviderProps> = (props: TooltipScopedProps<TooltipProviderProps>) => {
   const {
@@ -110,15 +111,18 @@ const TooltipProvider: FC<TooltipProviderProps> = (props: TooltipScopedProps<Too
 
   const popperScope = usePopperScope(__scopeTooltip);
   const [trigger, setTrigger] = useState<HTMLButtonElement | null>(null);
-  const [content, setContent] = useState<string>('');
+  const [content, setContent] = useState<ReactNode>(null);
   const [side, setSide] = useState<TooltipSide | undefined>(undefined);
   const triggerRef = useRef<HTMLButtonElement | null>(trigger);
-  const handleTriggerChange = useCallback((nextTrigger: HTMLButtonElement | null) => {
-    setTrigger(nextTrigger);
-    triggerRef.current = nextTrigger;
-    setContent(nextTrigger?.getAttribute('data-tooltip-content') ?? '');
-    setSide((nextTrigger?.getAttribute('data-tooltip-side') as TooltipSide | null) ?? undefined);
-  }, []);
+  const handleTriggerChange = useCallback(
+    (nextTrigger: HTMLButtonElement | null, nextContent?: ReactNode, nextSide?: TooltipSide) => {
+      setTrigger(nextTrigger);
+      triggerRef.current = nextTrigger;
+      setContent(nextContent ?? null);
+      setSide(nextSide);
+    },
+    [],
+  );
   const contentId = useId();
   const openTimerRef = useRef(0);
   const wasOpenDelayedRef = useRef(false);
@@ -214,11 +218,11 @@ const TooltipProvider: FC<TooltipProviderProps> = (props: TooltipScopedProps<Too
           isPointerInTransitRef.current = inTransit;
         }, [])}
       >
-        <TooltipContent side={side} className={tx('tooltip.content', 'tooltip', { elevation })}>
+        <TooltipContent side={side} className={tx('tooltip.content', { elevation })}>
           {content}
-          <TooltipArrow className={tx('tooltip.arrow', 'tooltip__arrow')} />
+          <TooltipArrow className={tx('tooltip.arrow')} />
         </TooltipContent>
-        <TooltipVirtualTrigger virtualRef={triggerRef} />
+        <TooltipVirtualTrigger virtualRef={triggerRef as RefObject<HTMLButtonElement>} />
         {children}
       </TooltipContextProvider>
     </PopperPrimitive.Root>
@@ -227,9 +231,9 @@ const TooltipProvider: FC<TooltipProviderProps> = (props: TooltipScopedProps<Too
 
 TooltipProvider.displayName = TOOLTIP_NAME;
 
-/* -------------------------------------------------------------------------------------------------
- * TooltipVirtualTrigger
- * ----------------------------------------------------------------------------------------------- */
+//
+// TooltipVirtualTrigger
+//
 
 const TooltipVirtualTrigger = ({
   virtualRef,
@@ -239,17 +243,17 @@ const TooltipVirtualTrigger = ({
   return <PopperPrimitive.Anchor asChild {...popperScope} virtualRef={virtualRef} />;
 };
 
-/* -------------------------------------------------------------------------------------------------
- * TooltipTrigger
- * ----------------------------------------------------------------------------------------------- */
+//
+// TooltipTrigger
+//
 
 const TRIGGER_NAME = 'TooltipTrigger';
 
-type TooltipTriggerElement = ElementRef<typeof Primitive.button>;
+type TooltipTriggerElement = ComponentRef<typeof Primitive.button>;
 type PrimitiveButtonProps = ComponentPropsWithoutRef<typeof Primitive.button>;
-type TooltipTriggerProps = PrimitiveButtonProps &
+type TooltipTriggerProps = Omit<PrimitiveButtonProps, 'content'> &
   Pick<TooltipProps, 'delayDuration'> & {
-    content?: string;
+    content?: ReactNode;
     side?: TooltipSide;
     onInteract?: (event: SyntheticEvent) => void;
   };
@@ -282,8 +286,6 @@ const TooltipTrigger = forwardRef<TooltipTriggerElement, TooltipTriggerProps>(
         // commonly anchors and the anchor `type` attribute signifies MIME type.
         aria-describedby={context.open ? context.contentId : undefined}
         data-state={context.stateAttribute}
-        data-tooltip-content={content}
-        data-tooltip-side={side}
         {...triggerProps}
         ref={composedRefs}
         onPointerMove={composeEventHandlers(props.onPointerMove, (event) => {
@@ -295,7 +297,7 @@ const TooltipTrigger = forwardRef<TooltipTriggerElement, TooltipTriggerProps>(
             if (event.defaultPrevented) {
               return;
             }
-            context.onTriggerChange(ref.current);
+            context.onTriggerChange(ref.current, content, side);
             context.onTriggerEnter();
             hasPointerMoveOpenedRef.current = true;
           }
@@ -321,9 +323,9 @@ const TooltipTrigger = forwardRef<TooltipTriggerElement, TooltipTriggerProps>(
 
 TooltipTrigger.displayName = TRIGGER_NAME;
 
-/* -------------------------------------------------------------------------------------------------
- * TooltipPortal
- * ----------------------------------------------------------------------------------------------- */
+//
+// TooltipPortal
+//
 
 const PORTAL_NAME = 'TooltipPortal';
 
@@ -333,7 +335,7 @@ const [PortalProvider, usePortalContext] = createTooltipContext<PortalContextVal
 });
 
 type PortalProps = ComponentPropsWithoutRef<typeof PortalPrimitive>;
-interface TooltipPortalProps {
+type TooltipPortalProps = {
   children?: ReactNode;
   /**
    * Specify a container element to portal the content into.
@@ -344,7 +346,7 @@ interface TooltipPortalProps {
    * controlling animation with React animation libraries.
    */
   forceMount?: true;
-}
+};
 
 const TooltipPortal: FC<TooltipPortalProps> = (props: TooltipScopedProps<TooltipPortalProps>) => {
   const { __scopeTooltip, forceMount, children, container } = props;
@@ -362,20 +364,20 @@ const TooltipPortal: FC<TooltipPortalProps> = (props: TooltipScopedProps<Tooltip
 
 TooltipPortal.displayName = PORTAL_NAME;
 
-/* -------------------------------------------------------------------------------------------------
- * TooltipContent
- * ----------------------------------------------------------------------------------------------- */
+//
+// TooltipContent
+//
 
 const CONTENT_NAME = 'TooltipContent';
 
 type TooltipContentElement = TooltipContentImplElement;
-interface TooltipContentProps extends TooltipContentImplProps {
+type TooltipContentProps = TooltipContentImplProps & {
   /**
    * Used to force mounting when more control is needed. Useful when
    * controlling animation with React animation libraries.
    */
   forceMount?: true;
-}
+};
 
 const TooltipContent = forwardRef<TooltipContentElement, TooltipContentProps>(
   (props: TooltipScopedProps<TooltipContentProps>, forwardedRef) => {
@@ -399,7 +401,7 @@ type Point = { x: number; y: number };
 type Polygon = Point[];
 
 type TooltipContentHoverableElement = TooltipContentImplElement;
-interface TooltipContentHoverableProps extends TooltipContentImplProps {}
+type TooltipContentHoverableProps = TooltipContentImplProps;
 
 const TooltipContentHoverable = forwardRef<TooltipContentHoverableElement, TooltipContentHoverableProps>(
   (props: TooltipScopedProps<TooltipContentHoverableProps>, forwardedRef) => {
@@ -478,10 +480,10 @@ const [VisuallyHiddenContentContextProvider, useVisuallyHiddenContentContext] =
   isInside: false,
 });
 
-type TooltipContentImplElement = ElementRef<typeof PopperPrimitive.Content>;
+type TooltipContentImplElement = ComponentRef<typeof PopperPrimitive.Content>;
 type DismissableLayerProps = ComponentPropsWithoutRef<typeof DismissableLayer>;
 type PopperContentProps = ComponentPropsWithoutRef<typeof PopperPrimitive.Content>;
-interface TooltipContentImplProps extends Omit<PopperContentProps, 'onPlaced'> {
+type TooltipContentImplProps = Omit<PopperContentProps, 'onPlaced'> & {
   /**
    * A more descriptive label for accessibility purpose
    */
@@ -497,7 +499,7 @@ interface TooltipContentImplProps extends Omit<PopperContentProps, 'onPlaced'> {
    * Can be prevented.
    */
   onPointerDownOutside?: DismissableLayerProps['onPointerDownOutside'];
-}
+};
 
 const TooltipContentImpl = forwardRef<TooltipContentImplElement, TooltipContentImplProps>(
   (props: TooltipScopedProps<TooltipContentImplProps>, forwardedRef) => {
@@ -573,15 +575,15 @@ const TooltipContentImpl = forwardRef<TooltipContentImplElement, TooltipContentI
 
 TooltipContent.displayName = CONTENT_NAME;
 
-/* -------------------------------------------------------------------------------------------------
- * TooltipArrow
- * ----------------------------------------------------------------------------------------------- */
+//
+// TooltipArrow
+//
 
 const ARROW_NAME = 'TooltipArrow';
 
-type TooltipArrowElement = ElementRef<typeof PopperPrimitive.Arrow>;
+type TooltipArrowElement = ComponentRef<typeof PopperPrimitive.Arrow>;
 type PopperArrowProps = ComponentPropsWithoutRef<typeof PopperPrimitive.Arrow>;
-interface TooltipArrowProps extends PopperArrowProps {}
+type TooltipArrowProps = PopperArrowProps;
 
 const TooltipArrow = forwardRef<TooltipArrowElement, TooltipArrowProps>(
   (props: TooltipScopedProps<TooltipArrowProps>, forwardedRef) => {
@@ -598,8 +600,6 @@ const TooltipArrow = forwardRef<TooltipArrowElement, TooltipArrowProps>(
 
 TooltipArrow.displayName = ARROW_NAME;
 
-/* ----------------------------------------------------------------------------------------------- */
-
 type TooltipSide = NonNullable<TooltipContentProps['side']>;
 
 const getExitSideFromRect = (point: Point, rect: DOMRect): TooltipSide => {
@@ -754,6 +754,10 @@ const getHullPresorted = <P extends Point>(points: Readonly<Array<P>>): Array<P>
   }
 };
 
+//
+// Tooltip
+//
+
 export const Tooltip = {
   Provider: TooltipProvider,
   Trigger: TooltipTrigger,

package/src/components/index.ts

@@ -2,29 +2,37 @@
 // Copyright 2022 DXOS.org
 //
 
-export * from './AnchoredOverflow';
+export * from './DensityProvider';
+export * from './ElevationProvider';
+export * from './ThemeProvider';
+
 export * from './Avatars';
 export * from './Breadcrumb';
-export * from './Buttons';
+export * from './Button';
+export * from './Card';
+export * from './Carousel';
 export * from './Clipboard';
-export * from './Dialogs';
+export * from './Dialog';
+export * from './ErrorFallback';
+export * from './Focus';
 export * from './Icon';
+export * from './Image';
 export * from './Input';
 export * from './Link';
-export * from './Lists';
+export * from './List';
 export * from './Main';
-export * from './Menus';
+export * from './MediaPlayer';
+export * from './Menu';
 export * from './Message';
 export * from './Popover';
 export * from './Status';
 export * from './ScrollArea';
+export * from './ScrollContainer';
 export * from './Select';
 export * from './Separator';
+export * from './Skeleton';
+export * from './Splitter';
 export * from './Tag';
 export * from './Toast';
 export * from './Toolbar';
 export * from './Tooltip';
-
-export * from './DensityProvider';
-export * from './ElevationProvider';
-export * from './ThemeProvider';

package/src/exemplars/generics.stories.tsx

@@ -0,0 +1,41 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { slottable } from '@dxos/ui-theme';
+
+import { withTheme } from '../testing';
+
+/**
+ * Generic component pattern using the slottable factory.
+ */
+const Component = slottable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
+  return (
+    <div {...props} ref={forwardedRef}>
+      {children}
+    </div>
+  );
+});
+
+const meta = {
+  title: 'ui/react-ui-core/exemplars/generics',
+  component: Component,
+  render: (props) => <Component {...props} />,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: 'Hello',
+  },
+};

package/src/exemplars/slot.stories.tsx

@@ -0,0 +1,115 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { PropsWithChildren } from 'react';
+
+import { composable, composableProps, mx, slottable } from '@dxos/ui-theme';
+
+import { withTheme } from '../testing';
+import { ThemedClassName } from '../util';
+
+/**
+ * Radix-style composition.
+ * All Radix primitive parts that render a DOM element accept an asChild prop.
+ * When asChild is set to true, Radix will not render a default DOM element,
+ * instead cloning the part's child and passing it the props and behavior required to make it functional.
+ * https://www.radix-ui.com/primitives/docs/guides/composition
+ */
+
+const Outer = slottable<HTMLDivElement, { priority?: number }>(
+  ({ children, asChild, priority, ...props }, forwardedRef) => {
+    const Comp = asChild ? Slot : Primitive.div;
+    return (
+      <Comp
+        {...composableProps<HTMLDivElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+        ref={forwardedRef}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+const Middle = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const Comp = asChild ? Slot : Primitive.div;
+  return (
+    <Comp
+      {...composableProps<HTMLDivElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+      ref={forwardedRef}
+    >
+      {children}
+    </Comp>
+  );
+});
+
+const Leaf = composable<HTMLButtonElement>(({ children, ...props }, forwardedRef) => {
+  return (
+    <button
+      {...composableProps<HTMLButtonElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+      ref={forwardedRef}
+    >
+      {children}
+    </button>
+  );
+});
+
+/** This isn't a valid child for a `slottable` component. */
+const Simple = ({ children, classNames }: ThemedClassName<PropsWithChildren>) => (
+  <div className={mx(classNames)}>{children}</div>
+);
+
+const meta = {
+  title: 'ui/react-ui-core/exemplars/slot',
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Single: Story = {
+  render: () => (
+    <Outer asChild role='article' classNames='border-green-500' priority={1}>
+      <Leaf>Single asChild (non-compliant — see console)</Leaf>
+    </Outer>
+  ),
+};
+
+export const Nested: Story = {
+  render: () => (
+    <Outer asChild role='article' classNames='border-blue-500'>
+      <Middle asChild>
+        <Leaf>Nested asChild</Leaf>
+      </Middle>
+    </Outer>
+  ),
+};
+
+export const Inner: Story = {
+  render: () => (
+    <Outer asChild role='article' classNames='border-orange-500'>
+      <Middle asChild>
+        <Leaf>
+          <div>Leaf</div>
+        </Leaf>
+      </Middle>
+    </Outer>
+  ),
+};
+
+export const Error: Story = {
+  render: () => (
+    <Outer asChild role='none' classNames='p-2 border border-green-500 rounded'>
+      <Middle asChild>
+        <Simple>Simple</Simple>
+      </Middle>
+    </Outer>
+  ),
+};

package/src/exemplars/tabster.stories.tsx

@@ -0,0 +1,127 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import {
+  useArrowNavigationGroup,
+  useFocusFinders,
+  useFocusableGroup,
+  useMergedTabsterAttributes_unstable,
+} from '@fluentui/react-tabster';
+import { type Decorator, type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { forwardRef, useEffect, useMemo, useRef } from 'react';
+import { createTabster, disposeTabster } from 'tabster';
+
+import { Input, ScrollArea } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { mx } from '@dxos/ui-theme';
+
+// TODO(burdon): Factor out styles (incl. tabster debugging).
+// TODO(burdon): Implement horizontal movement between columns when column is selected.
+// TODO(burdon): Prevent tab out of app.
+
+const border =
+  'rounded-xs outline-hidden border border-subdued-separator focus:border-primary-500 focus-within:border-rose-500';
+
+const Board = forwardRef<HTMLDivElement, { columns: string[][] }>(({ columns }, ref) => {
+  const arrowNavigationAttrs = useArrowNavigationGroup({ axis: 'horizontal', memorizeCurrent: true, tabbable: true });
+
+  return (
+    <div ref={ref} tabIndex={0} {...arrowNavigationAttrs} className='flex h-full w-full overflow-hidden'>
+      <div className={mx('flex h-full overflow-x-auto p-4 gap-4')}>
+        {columns.map((column) => (
+          <Column key={column[0]} items={column} />
+        ))}
+      </div>
+    </div>
+  );
+});
+
+const Column = forwardRef<HTMLDivElement, { items: string[] }>(({ items }, ref) => {
+  const focusableGroupAttrs = useFocusableGroup({ tabBehavior: 'limited' });
+  const arrowNavigationAttrs = useArrowNavigationGroup({ axis: 'vertical', memorizeCurrent: true });
+  const tabsterAttrs = useMergedTabsterAttributes_unstable(focusableGroupAttrs, arrowNavigationAttrs);
+
+  return (
+    <ScrollArea.Root orientation='vertical' classNames={mx('w-[25rem]', border)}>
+      <ScrollArea.Viewport {...tabsterAttrs} classNames='p-4 gap-4' ref={ref}>
+        {items.map((item) => (
+          <Item key={item} value={item} />
+        ))}
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+});
+
+const Item = forwardRef<HTMLDivElement, { value: string }>(({ value }, ref) => {
+  const focusableGroupAttrs = useFocusableGroup();
+
+  return (
+    <div
+      ref={ref}
+      tabIndex={0}
+      {...focusableGroupAttrs}
+      className={mx('flex shrink-0 w-full gap-4 p-4 items-center', border)}
+    >
+      <Input.Root>
+        <Input.Checkbox />
+      </Input.Root>
+      <Input.Root>
+        <Input.TextInput defaultValue={value} />
+      </Input.Root>
+    </div>
+  );
+});
+
+const DefaultStory = () => {
+  const columns = useMemo(() => {
+    return [['A1', 'A2', 'A3'], ['B1'], ['C1', 'C2', 'C3', 'C4', 'C5', 'C6'], ['D1', 'D2']];
+  }, []);
+
+  const ref = useRef<HTMLDivElement>(null);
+  const { findFirstFocusable } = useFocusFinders();
+  useEffect(() => {
+    if (ref.current) {
+      findFirstFocusable(ref.current)?.focus();
+    }
+  }, []);
+
+  return <Board columns={columns} ref={ref} />;
+};
+
+// TODO(burdon): This doesn't seem to be necessary or recongized; memoization doesn't work.
+const withTabster: Decorator = (Story) => {
+  useEffect(() => {
+    const tabster = createTabster(window, {
+      autoRoot: {},
+      // TODO(burdon): Not called.
+      // checkUncontrolledCompletely: (el) => {
+      //   console.log(el);
+      //   return true;
+      // },
+    });
+
+    return () => {
+      disposeTabster(tabster);
+    };
+  }, []);
+
+  return <Story />;
+};
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'ui/react-ui-core/exemplars/tabster',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withTabster],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {},
+};