@dxos/react-ui 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

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 { type Axis } from '@dxos/ui-types';
+
+import { useThemeContext } from '../../hooks';
+import { composableProps, slottable } from '../../util';
+
+//
+// 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/react-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/Icon',
-  render: DefaultStory,
-  decorators: [withTheme],
+  title: 'ui/react-ui-core/components/Icon',
+  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.theme.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { getSize, mx } from '@dxos/ui-theme';
+import { type ComponentFunction, type Size, type Theme } from '@dxos/ui-types';
+
+export type IconStyleProps = {
+  size?: Size;
+};
+
+export type IconBlockStyleProps = {
+  compact?: boolean;
+  /** Constrain to a square (1:1) slot rather than the default rail-item width. */
+  square?: boolean;
+};
+
+/**
+ * Size can be specified directly, or inherited from a container (e.g., toolbar).
+ */
+const root: ComponentFunction<IconStyleProps> = ({ size }, etc) => {
+  return mx(
+    'shrink-0 text-[var(--icons-color,currentColor)]',
+    size
+      ? getSize(size)
+      : '[width:var(--icon-size,var(--dx-default-icons-size))] [height:var(--icon-size,var(--dx-default-icons-size))]',
+    etc,
+  );
+};
+
+/**
+ * Static slot sized to `--dx-rail-item` so a wrapped `Icon` lines up with an `IconButton iconOnly`.
+ */
+const block: ComponentFunction<IconBlockStyleProps> = ({ compact, square }, ...etc) =>
+  mx(
+    'grid place-items-center [&>img]:max-w-[1.5rem]',
+    square ? 'aspect-square' : 'w-[var(--dx-rail-item)]',
+    compact ? '' : 'h-[var(--dx-rail-item)]',
+    ...etc,
+  );
+
+export const iconTheme: Theme<IconStyleProps & IconBlockStyleProps> = {
+  root,
+  block,
+};

package/src/components/Icon/Icon.tsx

@@ -3,9 +3,9 @@
 //
 
 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/react-ui-types';
+import { type Size } from '@dxos/ui-types';
 
 import { useIconHref, useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';
@@ -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', 'icon', { 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/Icon/IconBlock.tsx

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type ComponentPropsWithRef, type PropsWithChildren, forwardRef } from 'react';
+
+import { useThemeContext } from '../../hooks';
+import { type ThemedClassName } from '../../util';
+import { IconBlockStyleProps } from './Icon.theme';
+
+export type IconBlockProps = ThemedClassName<ComponentPropsWithRef<'div'> & PropsWithChildren<IconBlockStyleProps>>;
+
+/**
+ * Static layout slot sized to `--dx-rail-item` (the same square that an `IconButton iconOnly`
+ * occupies). Use whenever a decorative `<Icon>` needs to share a row, column, or grid track with
+ * interactive `IconButton`s without drifting by a pixel.
+ *
+ * Defaults `aria-hidden='true'` — the slot wraps decorative chrome by default. Pass
+ * `aria-hidden={false}` when the slot's contents convey meaning that isn't already labelled
+ * elsewhere in the row.
+ */
+export const IconBlock = forwardRef<HTMLDivElement, IconBlockProps>(
+  ({ classNames, children, compact, square, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    return (
+      <div
+        aria-hidden='true'
+        {...props}
+        className={tx('icon.block', { compact, square }, classNames)}
+        ref={forwardedRef}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+
+IconBlock.displayName = 'IconBlock';

package/src/components/Icon/index.ts

@@ -3,3 +3,4 @@
 //
 
 export * from './Icon';
+export * from './IconBlock';

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

@@ -0,0 +1,86 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+
+import { random } from '@dxos/random';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { Image } from './Image';
+
+const seed = Math.random();
+
+random.seed(seed);
+
+const meta = {
+  title: 'ui/react-ui-core/components/Image',
+  component: Image,
+  render: (args) => (
+    <div className='absolute inset-0 flex justify-center items-center'>
+      <Image {...args} />
+    </div>
+  ),
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof Image>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    src: random.image.url(),
+  },
+};
+
+const classNames = 'h-[12rem] w-[18rem]';
+
+/**
+ * Access to image at 'https://dxos.network/dxos-logotype-blue.png'
+ * from origin 'http://localhost:9009' has been blocked by CORS policy:
+ * No 'Access-Control-Allow-Origin' header is present on the requested resource.
+ */
+export const Cors: Story = {
+  args: {
+    src: 'https://dxos.network/dxos-logotype-blue.png',
+    classNames,
+  },
+};
+
+export const Corners: Story = {
+  args: {
+    src: 'https://picsum.photos/seed/picsum/200/200',
+    classNames,
+  },
+};
+
+export const SVG: Story = {
+  args: {
+    src: 'https://dxos.network/bg-kube.svg',
+    classNames,
+  },
+};
+
+export const Many: Story = {
+  args: {
+    src: 'https://dxos.network/bg-kube.svg',
+  },
+  render: () => {
+    const images = useMemo(
+      () => Array.from({ length: 9 }, (_, i) => `https://picsum.photos/seed/${seed + i}/500/500`),
+      [],
+    );
+    return (
+      <div className='w-[60rem] grid grid-cols-3 grid-rows-3 gap-8'>
+        {images.map((src, i) => (
+          <Image key={i} src={src} classNames={classNames} />
+        ))}
+      </div>
+    );
+  },
+};