@dxos/react-ui 0.8.4-main.d05673bc65 → 0.8.4-main.dfabb4ec29

package/src/components/Focus/Focus.tsx

@@ -0,0 +1,201 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import {
+  useArrowNavigationGroup,
+  useFocusableGroup,
+  useMergedTabsterAttributes_unstable,
+} from '@fluentui/react-tabster';
+import { useComposedRefs } from '@radix-ui/react-compose-refs';
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, {
+  type FocusEvent,
+  type KeyboardEvent,
+  type MouseEvent,
+  createContext,
+  useCallback,
+  useContext,
+  useRef,
+  useState,
+} from 'react';
+
+import { composableProps, slottable } from '@dxos/ui-theme';
+import { type Axis } from '@dxos/ui-types';
+
+import { useThemeContext } from '../../hooks';
+
+//
+// Context
+//
+
+type FocusState = 'active' | 'error';
+
+const FOCUS_STATE_ATTR = 'focus-state';
+
+type ContextValue = {
+  setFocus?: (state: FocusState | undefined) => void;
+  /** True when any item within the group has DOM focus. */
+  groupHasFocus?: boolean;
+};
+
+const FocusContext = createContext<ContextValue>({});
+
+const useFocus = () => useContext(FocusContext);
+
+//
+// Group
+//
+
+type GroupProps = {
+  orientation?: Axis;
+  /** Show a subdued ring when unfocused (e.g., as a cell border). */
+  border?: boolean;
+  onKeyDown?: (event: KeyboardEvent<HTMLDivElement>) => void;
+};
+
+/**
+ * Provides arrow-key navigation across focusable children via tabster.
+ * Does not manage `aria-current` — use `Focus.Item` on each child for that.
+ */
+// TODO(wittjosiah): Consider how this could integrate with with react-ui-attention.
+//   Perhaps react-ui-attention comes under the mosaic umbrella as it supports selection?
+const Group = slottable<HTMLDivElement, GroupProps>(
+  ({ children, asChild, orientation = 'vertical', border = false, ...props }, forwardedRef) => {
+    const Comp = asChild ? Slot : Primitive.div;
+    const { tx } = useThemeContext();
+    const rootRef = useRef<HTMLDivElement>(null);
+    const focusableGroupAttrs = useFocusableGroup({ tabBehavior: 'limited-trap-focus' });
+    const arrowNavigationAttrs = useArrowNavigationGroup({ axis: orientation, memorizeCurrent: true });
+    const tabsterAttrs = useMergedTabsterAttributes_unstable(focusableGroupAttrs, arrowNavigationAttrs);
+    const [state, setState] = useState<FocusState | undefined>();
+    const [groupHasFocus, setGroupHasFocus] = useState(false);
+
+    const handleFocusIn = useCallback(() => setGroupHasFocus(true), []);
+    const handleFocusOut = useCallback((event: FocusEvent<HTMLDivElement>) => {
+      const related = event.relatedTarget as HTMLElement | null;
+      if (!related || !rootRef.current?.contains(related)) {
+        setGroupHasFocus(false);
+      }
+    }, []);
+
+    const { className, ...rest } = composableProps(props);
+    return (
+      <FocusContext.Provider value={{ setFocus: setState, groupHasFocus }}>
+        <Comp
+          {...rest}
+          tabIndex={0}
+          className={tx('focus.group', { border }, className)}
+          {...tabsterAttrs}
+          {...(state && {
+            [`data-${FOCUS_STATE_ATTR}`]: state,
+          })}
+          onBlur={handleFocusOut}
+          onFocus={handleFocusIn}
+          ref={useComposedRefs<HTMLDivElement>(rootRef, forwardedRef)}
+        >
+          {children}
+        </Comp>
+      </FocusContext.Provider>
+    );
+  },
+);
+
+//
+// Item
+//
+
+type ItemProps = {
+  current?: boolean;
+  /** Show a subdued ring when unfocused (e.g., as a cell border). */
+  border?: boolean;
+  onCurrentChange?: () => void;
+};
+
+/**
+ * Focusable item within a `Focus.Group`.
+ * Uses `useFocusableGroup` so the parent Group's arrow navigation treats this as a single unit
+ * (internal buttons are not arrow-navigation targets; Enter/Escape to go in/out).
+ * Supports controlled (`current` prop) and uncontrolled (focus-driven) `aria-current`.
+ */
+const Item = slottable<HTMLDivElement, ItemProps>(
+  (
+    { children, asChild, current, border = false, onCurrentChange, onClick, onFocus, onBlur, ...props },
+    forwardedRef,
+  ) => {
+    const Comp = asChild ? Slot : Primitive.div;
+    const { tx } = useThemeContext();
+    // Tell tabster's groupper to ignore Enter so it doesn't move focus into the group.
+    const focusableGroupAttrs = useFocusableGroup({ ignoreDefaultKeydown: { Enter: true } });
+    const [focused, setFocused] = useState(false);
+
+    const handleClick = useCallback(
+      (event: MouseEvent<HTMLDivElement>) => {
+        onCurrentChange?.();
+        onClick?.(event);
+      },
+      [onCurrentChange, onClick],
+    );
+
+    const handleKeyDown = useCallback(
+      (event: KeyboardEvent<HTMLDivElement>) => {
+        if (event.key === 'Enter') {
+          onCurrentChange?.();
+        }
+      },
+      [onCurrentChange],
+    );
+
+    const handleFocus = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(true);
+        onFocus?.(event);
+      },
+      [onFocus],
+    );
+
+    const handleBlur = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(false);
+        onBlur?.(event);
+      },
+      [onBlur],
+    );
+
+    // Controlled `current` prop takes precedence (e.g., virtualized items that scroll back into view).
+    // Otherwise fall back to DOM focus state.
+    const isCurrent = current ?? focused;
+
+    const { className, ...rest } = composableProps(props);
+    return (
+      <Comp
+        {...rest}
+        tabIndex={0}
+        className={tx('focus.item', { border }, className)}
+        {...focusableGroupAttrs}
+        aria-current={isCurrent || undefined}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        ref={forwardedRef}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+//
+// Focus
+//
+
+export const Focus = {
+  Group,
+  Item,
+};
+
+export type { GroupProps as FocusGroupProps, ItemProps as FocusItemProps };
+
+export { useFocus };

package/src/components/Focus/index.ts

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

package/src/components/Icon/Icon.stories.tsx

@@ -6,10 +6,9 @@ import { IconBase, type IconProps, type IconWeight } from '@phosphor-icons/react
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { type FC, type ReactElement, type SVGProps, forwardRef } from 'react';
 
-import { getSize, mx } from '@dxos/ui-theme';
+import { getSize, iconSize, mx } from '@dxos/ui-theme';
 
 import { withTheme } from '../../testing';
-
 import { Icon } from './Icon';
 
 /**
@@ -50,29 +49,60 @@ const createIcon = ({
   return CustomIcon;
 };
 
-const DefaultStory = ({ CustomIcon }: { CustomIcon: FC<IconProps> }) => {
-  return (
-    <div className='grid grid-cols-2 gap-8'>
-      <CustomIcon weight={'regular'} className={mx(getSize(16))} />
-      <Icon icon='ph--github-logo--regular' classNames={mx(getSize(16))} />
-    </div>
-  );
-};
-
 const meta = {
   title: 'ui/react-ui-core/components/Icon',
-  render: DefaultStory,
+  component: Icon,
   decorators: [withTheme()],
   parameters: {
     layout: 'centered',
   },
-} satisfies Meta<typeof DefaultStory>;
+} satisfies Meta<typeof Icon>;
 
 export default meta;
 
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+  },
+};
+
+export const Static: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+    classNames: getSize(8),
+  },
+};
+
+export const Dynamic: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+  },
+  render: (args) => {
+    return (
+      <div className='flex gap-4'>
+        <Icon {...args} />
+        <div className='flex gap-4' style={iconSize(8)}>
+          <Icon {...args} />
+          <div className='flex gap-4' style={iconSize(null)}>
+            <Icon {...args} />
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Custom = {
+  render: ({ CustomIcon }: { CustomIcon: FC<IconProps> }) => {
+    return (
+      <div className='grid grid-cols-2 gap-8'>
+        <CustomIcon weight={'regular'} className={mx(getSize(16))} />
+        <Icon icon='ph--github-logo--regular' classNames={mx(getSize(16))} />
+      </div>
+    );
+  },
   args: {
     CustomIcon: createIcon({
       name: 'GithubLogo',

package/src/components/Icon/Icon.tsx

@@ -3,7 +3,7 @@
 //
 
 import { type Primitive } from '@radix-ui/react-primitive';
-import React, { type ComponentPropsWithRef, forwardRef, memo } from 'react';
+import React, { type ComponentPropsWithRef, forwardRef, memo, useMemo } from 'react';
 
 import { type Size } from '@dxos/ui-types';
 
@@ -13,14 +13,25 @@ import { type ThemedClassName } from '../../util';
 export type IconProps = ThemedClassName<ComponentPropsWithRef<typeof Primitive.svg>> & {
   icon: string;
   size?: Size;
+  synchronized?: boolean;
 };
 
+/**
+ * The Icon's size can be set directly or inherited from the `--dx-icon-size` CSS variable.
+ */
 export const Icon = memo(
-  forwardRef<SVGSVGElement, IconProps>(({ icon, classNames, size = 4, ...props }, forwardedRef) => {
+  forwardRef<SVGSVGElement, IconProps>(({ classNames, icon, size, synchronized, style, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
+    const spinDelay = useMemo(() => (synchronized ? `${-(Date.now() % 1_000)}ms` : undefined), [synchronized]);
     const href = useIconHref(icon);
+
     return (
-      <svg {...props} className={tx('icon.root', { size }, classNames)} ref={forwardedRef}>
+      <svg
+        {...props}
+        style={{ ...style, animationDelay: spinDelay }}
+        className={tx('icon.root', { size }, classNames)}
+        ref={forwardedRef}
+      >
         <use href={href} />
       </svg>
     );

package/src/components/Image/Image.stories.tsx

@@ -5,14 +5,14 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useMemo } from 'react';
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { withTheme } from '@dxos/react-ui/testing';
 
 import { Image } from './Image';
 
 const seed = Math.random();
 
-faker.seed(seed);
+random.seed(seed);
 
 const meta = {
   title: 'ui/react-ui-mosaic/Image',
@@ -34,7 +34,7 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {
-    src: faker.image.url(),
+    src: random.image.url(),
   },
 };
 

package/src/components/Image/Image.tsx

@@ -13,15 +13,16 @@ export type ImageProps = ThemedClassName<
   {
     src: string;
     alt?: string;
+    fit?: 'contain' | 'cover';
     crossOrigin?: 'anonymous' | 'use-credentials' | '';
   } & ColorOptions
 >;
 
-// TODO(burdon): Option for neutral background color.
 export const Image = ({
   classNames,
   src,
   alt = '',
+  fit = 'contain',
   crossOrigin = 'anonymous',
   sampleSize = 64,
   contrast = 0.9,
@@ -68,7 +69,16 @@ export const Image = ({
 
   return (
     <div
-      className={mx(`relative flex w-full justify-center overflow-hidden transition-all duration-700`, classNames)}
+      // `isolate` (`isolation: isolate`) creates a new stacking context so
+      // the inner <img>'s `z-10` stays scoped to this wrapper. Without it
+      // the z-10 leaks into the parent's stacking context and elevates the
+      // image above any pseudo-element rings (e.g. Focus.Item's
+      // `dx-ring-pseudo` `::after`) painted on ancestors — most visibly,
+      // the focus ring on a Card containing a Card.Poster.
+      className={mx(
+        `relative flex w-full justify-center overflow-hidden transition-all duration-700 isolate`,
+        classNames,
+      )}
       style={{
         backgroundColor: dominantColor,
       }}
@@ -94,7 +104,10 @@ export const Image = ({
         crossOrigin={crossOriginState}
         onError={handleImageError}
         onLoad={handleImageLoad}
-        className='z-10 object-contain transition-opacity duration-500'
+        className={mx(
+          'z-10 transition-opacity duration-500',
+          fit === 'cover' ? 'w-full h-full object-cover' : 'object-contain',
+        )}
         style={{
           opacity: imageLoaded ? 1 : 0,
         }}
@@ -162,7 +175,9 @@ const extractDominantColor = (
       const alpha = pixels[i + 3];
 
       // Skip transparent pixels.
-      if (alpha === 0) continue;
+      if (alpha === 0) {
+        continue;
+      }
 
       // Calculate saturation to weight vibrant colors more.
       const max = Math.max(red, green, blue);
@@ -202,21 +217,29 @@ const isTransparent = (pixels: Uint8ClampedArray, sampleSize: number, threshold:
   for (let x = 0; x < sampleSize; x++) {
     // Top edge.
     const topIndex = x * 4;
-    if (pixels[topIndex + 3] === 0) edgeTransparentPixels++;
+    if (pixels[topIndex + 3] === 0) {
+      edgeTransparentPixels++;
+    }
 
     // Bottom edge.
     const bottomIndex = ((sampleSize - 1) * sampleSize + x) * 4;
-    if (pixels[bottomIndex + 3] === 0) edgeTransparentPixels++;
+    if (pixels[bottomIndex + 3] === 0) {
+      edgeTransparentPixels++;
+    }
   }
 
   for (let y = 1; y < sampleSize - 1; y++) {
     // Left edge.
     const leftIndex = y * sampleSize * 4;
-    if (pixels[leftIndex + 3] === 0) edgeTransparentPixels++;
+    if (pixels[leftIndex + 3] === 0) {
+      edgeTransparentPixels++;
+    }
 
     // Right edge.
     const rightIndex = (y * sampleSize + sampleSize - 1) * 4;
-    if (pixels[rightIndex + 3] === 0) edgeTransparentPixels++;
+    if (pixels[rightIndex + 3] === 0) {
+      edgeTransparentPixels++;
+    }
   }
 
   return edgeTransparentPixels / edgePixels > threshold;

package/src/components/Input/Input.stories.tsx

@@ -8,7 +8,6 @@ import React from 'react';
 import { type MessageValence } from '@dxos/ui-types';
 
 import { withLayoutVariants, withTheme } from '../../testing';
-
 import {
   type CheckboxProps,
   Input,
@@ -28,7 +27,7 @@ type VariantMap = {
 
 type Variant = { [K in keyof VariantMap]: { type: K } & VariantMap[K] }[keyof VariantMap];
 
-type StoryProps = Partial<{
+type DefaultStoryProps = Partial<{
   kind: keyof VariantMap;
   label: string;
   labelVisuallyHidden: boolean;
@@ -47,7 +46,7 @@ const DefaultStory = ({
   validationValence,
   validationMessage,
   ...props
-}: StoryProps) => {
+}: DefaultStoryProps) => {
   return (
     <Input.Root {...{ validationValence }}>
       <Input.Label srOnly={labelVisuallyHidden}>{label}</Input.Label>
@@ -75,7 +74,7 @@ const meta = {
 
 export default meta;
 
-type Story = StoryObj<StoryProps & Variant>;
+type Story = StoryObj<DefaultStoryProps & Variant>;
 
 export const DensityCoarse: Story = {
   args: {

package/src/components/Input/Input.tsx

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Root as CheckboxPrimitive, type CheckboxProps as CheckboxPrimitiveProps } from '@radix-ui/react-checkbox';
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
 import { useControllableState } from '@radix-ui/react-use-controllable-state';
 import React, { type ComponentPropsWithRef, type ForwardRefExoticComponent, forwardRef } from 'react';
 
@@ -130,13 +130,13 @@ type TextInputProps = InputSharedProps & ThemedClassName<TextInputPrimitiveProps
 
 const TextInput = forwardRef<HTMLInputElement, InputScopedProps<TextInputProps>>(
   (
-    { __inputScope, classNames, density: propsDensity, elevation: propsElevation, variant, noAutoFill, ...props },
+    { __inputScope, classNames, density: densityProp, elevation: elevationProp, variant, noAutoFill, ...props },
     forwardedRef,
   ) => {
     const { hasIosKeyboard } = useThemeContext();
     const { tx } = useThemeContext();
-    const density = useDensityContext(propsDensity);
-    const elevation = useElevationContext(propsElevation);
+    const density = useDensityContext(densityProp);
+    const elevation = useElevationContext(elevationProp);
     const { validationValence } = useInputContext(INPUT_NAME, __inputScope);
 
     return (
@@ -193,7 +193,7 @@ const TextArea = forwardRef<HTMLTextAreaElement, InputScopedProps<TextAreaProps>
   },
 );
 
-type CheckboxProps = ThemedClassName<Omit<CheckboxPrimitiveProps, 'children'>> & {
+type CheckboxProps = ThemedClassName<Omit<CheckboxPrimitive.CheckboxProps, 'children'>> & {
   size?: Size;
 };
 
@@ -222,7 +222,7 @@ const Checkbox: ForwardRefExoticComponent<CheckboxProps> = forwardRef<
     const { tx } = useThemeContext();
 
     return (
-      <CheckboxPrimitive
+      <CheckboxPrimitive.Root
         {...{
           ...props,
           checked,
@@ -241,7 +241,7 @@ const Checkbox: ForwardRefExoticComponent<CheckboxProps> = forwardRef<
           icon={checked === 'indeterminate' ? 'ph--minus--regular' : 'ph--check--regular'}
           classNames={tx('input.checkboxIndicator', { size, checked })}
         />
-      </CheckboxPrimitive>
+      </CheckboxPrimitive.Root>
     );
   },
 );

package/src/components/Link/Link.stories.tsx

@@ -5,7 +5,6 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 
 import { withTheme } from '../../testing';
-
 import { Link } from './Link';
 
 const meta = {

package/src/components/List/List.stories.tsx

@@ -13,7 +13,6 @@ import { getSize, ghostHover, mx, surfaceShadow } from '@dxos/ui-theme';
 
 import { withTheme } from '../../testing';
 import { Icon } from '../Icon';
-
 import { List, ListItem, type ListScopedProps } from './List';
 
 const meta = {
@@ -177,7 +176,7 @@ export const Collapsible: Story = {
       <List {...args}>
         {items.map(({ id, text, body }, index) => (
           <ListItem.Root key={id} id={id} collapsible={index !== 2} defaultOpen={index % 2 === 0}>
-            <div role='none' className='grow flex'>
+            <div className='grow flex'>
               {index !== 2 ? <ListItem.OpenTrigger /> : <ListItem.MockOpenTrigger />}
               <ListItem.Heading classNames='grow pt-2'>{text}</ListItem.Heading>
               <ListItem.Endcap>

package/src/components/List/List.tsx

@@ -24,24 +24,25 @@ import {
   useListContext,
   useListItemContext,
 } from '@dxos/react-list';
+import { composable, composableProps } from '@dxos/ui-theme';
 import { type Density } from '@dxos/ui-types';
 
 import { useDensityContext, useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';
 import { DensityProvider } from '../DensityProvider';
 import { Icon } from '../Icon';
-
 import { ListDropIndicator } from './ListDropIndicator';
 
-type ListProps = ThemedClassName<ListPrimitiveProps> & { density?: Density };
+type ListProps = ThemedClassName<ListPrimitiveProps & { density?: Density }>;
 
-const List = forwardRef<HTMLOListElement, ListProps>(({ classNames, children, ...props }, forwardedRef) => {
+const List = composable<HTMLOListElement, ListProps>(({ children, ...props }, forwardedRef) => {
   const { tx } = useThemeContext();
   const density = useDensityContext(props.density);
+  const { className, ...rest } = composableProps(props);
 
   return (
     <DensityProvider density={density}>
-      <ListPrimitive {...props} className={tx('list.root', {}, classNames)} ref={forwardedRef}>
+      <ListPrimitive {...rest} className={tx('list.root', {}, className)} ref={forwardedRef}>
         {children}
       </ListPrimitive>
     </DensityProvider>
@@ -74,7 +75,7 @@ const MockListItemOpenTrigger = ({
 }: ThemedClassName<Omit<ComponentPropsWithoutRef<'div'>, 'children'>>) => {
   const density = useDensityContext();
   const { tx } = useThemeContext();
-  return <div role='none' {...props} className={tx('list.item.openTrigger', { density }, classNames)} />;
+  return <div {...props} className={tx('list.item.openTrigger', { density }, classNames)} />;
 };
 
 type ListItemHeadingProps = ThemedClassName<ListPrimitiveItemHeadingProps>;
@@ -89,7 +90,7 @@ const ListItemHeading = forwardRef<HTMLParagraphElement, ListItemHeadingProps>(
         className={tx('list.item.heading', { density }, classNames)}
         ref={forwardedRef}
       >
-        {children}
+        <span>{children}</span>
       </ListPrimitiveItemHeading>
     );
   },

package/src/components/List/ListDropIndicator.tsx

@@ -52,7 +52,6 @@ export const ListDropIndicator = ({
 
   return (
     <div
-      role='none'
       style={
         {
           '--line-thickness': `${strokeSize}px`,

package/src/components/List/Tree.stories.tsx

@@ -6,7 +6,6 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { withTheme } from '../../testing';
-
 import { Tree, TreeItem } from './Tree';
 
 type StorybookTreeProps = {
@@ -25,7 +24,7 @@ const createKey = (key: string, prefix?: string) => (prefix === undefined ? key
 const StorybookTreeItem = ({ data, prefix }: StorybookTreeItemProps) => {
   const keys = Array.isArray(data) ? Array.from(data.keys()) : Object.keys(data);
   return (
-    <Tree.Root density='fine'>
+    <Tree.Root>
       {keys.map((key) => {
         const id = createKey(String(key), prefix);
         const value = data[key as keyof typeof data];
@@ -33,7 +32,7 @@ const StorybookTreeItem = ({ data, prefix }: StorybookTreeItemProps) => {
 
         return (
           <TreeItem.Root key={id} id={id} collapsible={!valueIsScalar} defaultOpen>
-            <div role='none' className='grow flex'>
+            <div className='grow flex'>
               {valueIsScalar ? <TreeItem.MockOpenTrigger /> : <TreeItem.OpenTrigger />}
               <TreeItem.Heading classNames='grow pt-1'>{valueIsScalar ? String(value) : key}</TreeItem.Heading>
             </div>

package/src/components/List/Tree.tsx

@@ -5,7 +5,6 @@
 import React, { type ComponentPropsWithoutRef, type FC, type ForwardRefExoticComponent, forwardRef } from 'react';
 
 import { type ThemedClassName } from '../../util';
-
 import {
   LIST_ITEM_NAME,
   List,