@dxos/react-ui 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

package/src/components/Carousel/Carousel.tsx

@@ -0,0 +1,379 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useArrowNavigationGroup } from '@fluentui/react-tabster';
+import React, {
+  createContext,
+  type KeyboardEvent,
+  type PropsWithChildren,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+import { mx } from '@dxos/ui-theme';
+
+import { translationKey } from '../../translations';
+import { type ThemedClassName } from '../../util';
+import { IconButton } from '../Button';
+import { MediaPlayer, type MediaKind } from '../MediaPlayer';
+import { useTranslation } from '../ThemeProvider';
+
+// TODO(burdon): Move per-element class strings to `@dxos/ui-theme` (theme tokens)
+// so callers can re-theme via the same mechanism the rest of `react-ui` uses.
+
+//
+// Context
+//
+
+type CarouselContextValue = {
+  index: number;
+  count: number;
+  setIndex: (index: number) => void;
+  next: () => void;
+  prev: () => void;
+};
+
+const CarouselContext = createContext<CarouselContextValue | null>(null);
+
+/** Returns the current carousel state. Must be used within {@link Carousel.Root}. */
+export const useCarousel = (): CarouselContextValue => {
+  const context = useContext(CarouselContext);
+  if (!context) {
+    throw new Error('useCarousel must be used within Carousel.Root');
+  }
+  return context;
+};
+
+//
+// Root
+//
+
+export type CarouselRootProps = ThemedClassName<
+  PropsWithChildren<{
+    /** Total number of slides; drives auto-advance and indicator counts. */
+    count: number;
+    /** Whether to auto-advance slides on mount. Defaults to `false`. */
+    autorun?: boolean;
+    /** Auto-advance interval in milliseconds. Set 0 to disable. */
+    intervalMs?: number;
+    defaultIndex?: number;
+  }>
+>;
+
+const CarouselRoot = ({
+  classNames,
+  children,
+  count,
+  autorun = false,
+  intervalMs = 5_000,
+  defaultIndex = 0,
+}: CarouselRootProps) => {
+  const [index, setIndexState] = useState(defaultIndex);
+  const [autoAdvance, setAutoAdvance] = useState(autorun);
+
+  // Reset to first slide if the slide count shrinks below the current index.
+  useEffect(() => {
+    if (index >= count) {
+      setIndexState(0);
+    }
+  }, [count, index]);
+
+  // Auto-advance — stops permanently once the user interacts with any control.
+  useEffect(() => {
+    if (!autoAdvance || count <= 1 || intervalMs <= 0) {
+      return;
+    }
+    const handle = setInterval(() => setIndexState((i) => (i + 1) % count), intervalMs);
+    return () => clearInterval(handle);
+  }, [autoAdvance, count, intervalMs]);
+
+  const setIndex = useCallback((next: number) => {
+    setAutoAdvance(false);
+    setIndexState(next);
+  }, []);
+  const next = useCallback(() => {
+    setAutoAdvance(false);
+    setIndexState((i) => (i + 1) % count);
+  }, [count]);
+  const prev = useCallback(() => {
+    setAutoAdvance(false);
+    setIndexState((i) => (i - 1 + count) % count);
+  }, [count]);
+
+  const value = useMemo(() => ({ index, count, setIndex, next, prev }), [index, count, setIndex, next, prev]);
+
+  if (count === 0) {
+    return null;
+  }
+
+  return (
+    <CarouselContext.Provider value={value}>
+      {/*
+       * Rows are `[1fr, auto]`: row 1 (Previous|Viewport|Next) stretches when the parent
+       * gives the carousel a definite height, and row 2 (Indicators / Caption) sticks to
+       * its content height. With no parent height constraint, the `1fr` row simply tracks
+       * row-1 content — preserving the existing aspect-video behaviour for unbounded use.
+       */}
+      {/* TODO(burdon): Move to ui-theme. */}
+      <div
+        className={mx(
+          'w-full grid grid-cols-[min-content_1fr_min-content] grid-rows-[minmax(0,1fr)_auto] gap-4 items-center',
+          classNames,
+        )}
+      >
+        {children}
+      </div>
+    </CarouselContext.Provider>
+  );
+};
+
+CarouselRoot.displayName = 'Carousel.Root';
+
+//
+// Viewport
+//
+
+export type CarouselViewportProps = ThemedClassName<PropsWithChildren<{}>>;
+
+const CarouselViewport = ({ children, classNames }: CarouselViewportProps) => {
+  const { t } = useTranslation(translationKey);
+  const { count, next, prev } = useCarousel();
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      if (count <= 1) {
+        return;
+      }
+      if (event.key === 'ArrowLeft') {
+        event.preventDefault();
+        prev();
+      } else if (event.key === 'ArrowRight') {
+        event.preventDefault();
+        next();
+      }
+    },
+    [count, next, prev],
+  );
+
+  return (
+    <div
+      // TODO(burdon): Move to ui-theme.
+      className={mx(
+        'relative w-full aspect-video overflow-hidden',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+        classNames,
+      )}
+      tabIndex={0}
+      role='region'
+      aria-roledescription='carousel'
+      aria-label={t('carousel-viewport.label')}
+      onKeyDown={handleKeyDown}
+    >
+      {children}
+    </div>
+  );
+};
+
+CarouselViewport.displayName = 'Carousel.Viewport';
+
+//
+// Slide
+//
+
+export type CarouselSlideProps = ThemedClassName<{
+  index: number;
+  /** Media source URL — rendered via the embedded {@link MediaPlayer}. */
+  src: string;
+  /** Override media auto-detection (`'video' | 'audio'`). */
+  kind?: MediaKind;
+  /** Accessible label / `<img alt>` fallback. */
+  alt?: string;
+  /** Class names forwarded to the inner `<img>` when MediaPlayer resolves to an image. */
+  imgClassNames?: string;
+  /** Class names forwarded to the inner `<video>` / `<audio>` / `<iframe>`. */
+  mediaClassNames?: string;
+  controls?: boolean;
+  autoPlay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  crossOrigin?: 'anonymous' | 'use-credentials' | '';
+}>;
+
+const CarouselSlide = ({
+  index,
+  classNames,
+  src,
+  kind,
+  alt,
+  imgClassNames,
+  mediaClassNames,
+  controls,
+  autoPlay,
+  loop,
+  muted,
+  crossOrigin,
+}: CarouselSlideProps) => {
+  const { index: active } = useCarousel();
+  if (active !== index) {
+    return null;
+  }
+
+  return (
+    <div className={mx('absolute inset-0 w-full h-full bg-baseSurface', classNames)}>
+      <MediaPlayer
+        src={src}
+        kind={kind}
+        alt={alt}
+        classNames='w-full h-full'
+        imgClassNames={mx('object-cover', imgClassNames)}
+        mediaClassNames={mediaClassNames}
+        controls={controls}
+        autoPlay={autoPlay}
+        loop={loop}
+        muted={muted}
+        crossOrigin={crossOrigin}
+      />
+    </div>
+  );
+};
+
+CarouselSlide.displayName = 'Carousel.Slide';
+
+//
+// Previous / Next
+//
+
+export type CarouselButtonProps = ThemedClassName<{}>;
+
+const CarouselPrevious = ({ classNames }: CarouselButtonProps) => {
+  const { t } = useTranslation(translationKey);
+  const { count, prev } = useCarousel();
+  if (count <= 1) {
+    return <div />;
+  }
+
+  return (
+    <IconButton
+      classNames={mx('self-center', classNames)}
+      square
+      variant='ghost'
+      icon='ph--caret-left--regular'
+      iconOnly
+      label={t('carousel-prev.label')}
+      onClick={prev}
+    />
+  );
+};
+
+CarouselPrevious.displayName = 'Carousel.Previous';
+
+const CarouselNext = ({ classNames }: CarouselButtonProps) => {
+  const { t } = useTranslation(translationKey);
+  const { count, next } = useCarousel();
+  if (count <= 1) {
+    return <div />;
+  }
+
+  return (
+    <IconButton
+      classNames={mx('self-center', classNames)}
+      square
+      variant='ghost'
+      icon='ph--caret-right--regular'
+      iconOnly
+      label={t('carousel-next.label')}
+      onClick={next}
+    />
+  );
+};
+
+CarouselNext.displayName = 'Carousel.Next';
+
+//
+// Indicators
+//
+
+export type CarouselIndicatorsProps = ThemedClassName<{}>;
+
+/** Tab-strip of slide indicators. Sits in the centre column so it matches the viewport's width. */
+const CarouselIndicators = ({ classNames }: CarouselIndicatorsProps) => {
+  const { t } = useTranslation(translationKey);
+  const { count, index, setIndex } = useCarousel();
+  const arrowNavigationAttrs = useArrowNavigationGroup({ axis: 'horizontal', memorizeCurrent: true });
+  if (count <= 1) {
+    return null;
+  }
+
+  return (
+    <div className='col-start-2 overflow-hidden'>
+      <div
+        {...arrowNavigationAttrs}
+        className={mx('flex items-center justify-center', classNames)}
+        role='tablist'
+        aria-label={t('carousel-indicators.label')}
+      >
+        {Array.from({ length: count }).map((_, i) => (
+          <IconButton
+            key={i}
+            role='tab'
+            aria-selected={i === index}
+            classNames={i === index ? 'text-primary-500' : 'text-description'}
+            icon={i === index ? 'ph--circle--fill' : 'ph--circle--regular'}
+            iconOnly
+            label={t('carousel-go-to.label', { index: i + 1 })}
+            onClick={() => setIndex(i)}
+            onFocus={() => setIndex(i)}
+            size={3}
+            variant='ghost'
+          />
+        ))}
+      </div>
+    </div>
+  );
+};
+
+CarouselIndicators.displayName = 'Carousel.Indicators';
+
+//
+// Caption
+//
+
+export type CarouselCaptionProps = ThemedClassName<{
+  /** Render prop receiving the active slide index. */
+  children: (index: number) => ReactNode;
+}>;
+
+/** Caption sized to the viewport's column. */
+const CarouselCaption = ({ children, classNames }: CarouselCaptionProps) => {
+  const { index } = useCarousel();
+  const content = children(index);
+  if (content == null || content === false || content === '') {
+    return null;
+  }
+  return (
+    // TODO(burdon): Move to ui-theme.
+    <div className='col-start-2'>
+      <p className={mx('text-center text-description', classNames)}>{content}</p>
+    </div>
+  );
+};
+
+CarouselCaption.displayName = 'Carousel.Caption';
+
+//
+// Carousel
+//
+
+export const Carousel = {
+  Root: CarouselRoot,
+  Viewport: CarouselViewport,
+  Slide: CarouselSlide,
+  Previous: CarouselPrevious,
+  Next: CarouselNext,
+  Indicators: CarouselIndicators,
+  Caption: CarouselCaption,
+};

package/src/components/Carousel/index.ts

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

package/src/components/Clipboard/CopyButton.tsx

@@ -10,7 +10,6 @@ import { Button, type ButtonProps, IconButton } from '../Button';
 import { Icon, type IconProps } from '../Icon';
 import { useTranslation } from '../ThemeProvider';
 import { type TooltipScopedProps, useTooltipContext } from '../Tooltip';
-
 import { useClipboard } from './ClipboardProvider';
 
 export type CopyButtonProps = ButtonProps &
@@ -31,12 +30,12 @@ export const CopyButton = ({ classNames, value, size = 5, ...props }: CopyButton
       onClick={() => setTextValue(value)}
       data-testid='copy-invitation'
     >
-      <div role='none' className={mx('flex gap-1 items-center', isCopied && inactiveLabelStyles)}>
-        <span className='px-1'>{t('copy label')}</span>
+      <div className={mx('flex gap-1 items-center', isCopied && inactiveLabelStyles)}>
+        <span className='px-1'>{t('copy.label')}</span>
         <Icon icon='ph--copy--regular' size={size} />
       </div>
-      <div role='none' className={mx('flex gap-1 items-center', !isCopied && inactiveLabelStyles)}>
-        <span className='px-1'>{t('copy success label')}</span>
+      <div className={mx('flex gap-1 items-center', !isCopied && inactiveLabelStyles)}>
+        <span className='px-1'>{t('copy-success.label')}</span>
         <Icon icon='ph--check--regular' size={size} />
       </div>
     </Button>
@@ -58,7 +57,7 @@ export const CopyButtonIconOnly = ({
   const { t } = useTranslation(osTranslations);
   const { textValue, setTextValue } = useClipboard();
   const isCopied = textValue === value;
-  const label = isCopied ? t('copy success label') : (props.label ?? t('copy label'));
+  const label = isCopied ? t('copy-success.label') : (props.label ?? t('copy.label'));
   const { onOpen } = useTooltipContext('CopyButton', __scopeTooltip);
   return (
     <IconButton

package/src/components/Dialog/AlertDialog.stories.tsx

@@ -5,14 +5,13 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 
 import { withTheme } from '../../testing';
 import { Button } from '../Button';
-
 import { AlertDialog } from './AlertDialog';
 
-type StoryProps = Partial<{
+type DefaultStoryProps = Partial<{
   title: string;
   description: string;
   openTrigger: string;
@@ -20,7 +19,7 @@ type StoryProps = Partial<{
   actionTrigger: string;
 }>;
 
-const DefaultStory = ({ title, description, openTrigger, cancelTrigger, actionTrigger }: StoryProps) => {
+const DefaultStory = ({ title, description, openTrigger, cancelTrigger, actionTrigger }: DefaultStoryProps) => {
   return (
     <AlertDialog.Root defaultOpen>
       <AlertDialog.Trigger asChild>
@@ -60,8 +59,8 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {
-    title: faker.lorem.sentence(3),
-    description: faker.lorem.paragraph(1),
+    title: random.lorem.sentence(3),
+    description: random.lorem.paragraph(1),
     openTrigger: 'Open AlertDialog',
     cancelTrigger: 'Cancel',
     actionTrigger: 'Action',

package/src/components/Dialog/AlertDialog.tsx

@@ -4,12 +4,7 @@
 
 import * as AlertDialogPrimitive from '@radix-ui/react-alert-dialog';
 import { createContext } from '@radix-ui/react-context';
-import React, {
-  type ForwardRefExoticComponent,
-  type FunctionComponent,
-  type PropsWithChildren,
-  forwardRef,
-} from 'react';
+import React, { type ForwardRefExoticComponent, type FunctionComponent, forwardRef } from 'react';
 
 import { type DialogSize } from '@dxos/ui-theme';
 
@@ -17,6 +12,13 @@ import { useThemeContext } from '../../hooks';
 import { Column } from '../../primitives';
 import { type ThemedClassName } from '../../util';
 import { ElevationProvider } from '../ElevationProvider';
+import {
+  Dialog,
+  type DialogHeaderProps,
+  type DialogBodyProps,
+  type DialogActionBarProps,
+  type DialogCloseIconButtonProps,
+} from './Dialog';
 
 //
 // Root
@@ -63,68 +65,26 @@ type AlertDialogActionProps = AlertDialogPrimitive.AlertDialogActionProps;
 const AlertDialogAction: FunctionComponent<AlertDialogActionProps> = AlertDialogPrimitive.Action;
 
 //
-// Title
-//
-
-type AlertDialogTitleProps = ThemedClassName<AlertDialogPrimitive.AlertDialogTitleProps> & { srOnly?: boolean };
-
-const AlertDialogTitle: ForwardRefExoticComponent<AlertDialogTitleProps> = forwardRef<
-  HTMLHeadingElement,
-  AlertDialogTitleProps
->(({ classNames, srOnly, ...props }, forwardedRef) => {
-  const { tx } = useThemeContext();
-  return (
-    <AlertDialogPrimitive.Title {...props} className={tx('dialog.title', { srOnly }, classNames)} ref={forwardedRef} />
-  );
-});
-
-//
-// Description
+// Context
 //
 
-type AlertDialogDescriptionProps = ThemedClassName<AlertDialogPrimitive.AlertDialogDescriptionProps> & {
-  srOnly?: boolean;
-};
-
-const AlertDialogDescription: ForwardRefExoticComponent<AlertDialogTitleProps> = forwardRef<
-  HTMLParagraphElement,
-  AlertDialogDescriptionProps
->(({ classNames, srOnly, ...props }, forwardedRef) => {
-  const { tx } = useThemeContext();
-  return (
-    <AlertDialogPrimitive.Description
-      {...props}
-      className={tx('dialog.description', { srOnly }, classNames)}
-      ref={forwardedRef}
-    />
-  );
-});
-
 type OverlayLayoutContextValue = { inOverlayLayout?: boolean };
 
-//
-// Context
-//
-
 const ALERT_DIALOG_OVERLAY_NAME = 'AlertDialogOverlay';
 const ALERT_DIALOG_CONTENT_NAME = 'AlertDialogContent';
-const ALERT_DIALOG_BODY_NAME = 'AlertDialogBody';
-const ALERT_DIALOG_ACTIONBAR_NAME = 'AlertDialogActionBar';
 
 const [OverlayLayoutProvider, useOverlayLayoutContext] = createContext<OverlayLayoutContextValue>(
   ALERT_DIALOG_OVERLAY_NAME,
-  {
-    inOverlayLayout: false,
-  },
+  { inOverlayLayout: false },
 );
 
 //
 // Overlay
 //
 
-type AlertDialogOverlayProps = ThemedClassName<AlertDialogPrimitive.AlertDialogOverlayProps> & {
-  blockAlign?: 'center' | 'start' | 'end';
-};
+type AlertDialogOverlayProps = ThemedClassName<
+  AlertDialogPrimitive.AlertDialogOverlayProps & { blockAlign?: 'center' | 'start' | 'end' }
+>;
 
 const AlertDialogOverlay: ForwardRefExoticComponent<AlertDialogOverlayProps> = forwardRef<
   HTMLDivElement,
@@ -135,15 +95,7 @@ const AlertDialogOverlay: ForwardRefExoticComponent<AlertDialogOverlayProps> = f
     <AlertDialogPrimitive.Overlay
       {...props}
       data-block-align={blockAlign}
-      className={tx(
-        'dialog.overlay',
-        {},
-        classNames,
-        // TODO(burdon): Move to dialog.ts.
-        'data-[h-align=start]:justify-center',
-        'data-[h-align=start]:items-start',
-        'data-[h-align=center]:place-content-center',
-      )}
+      className={tx('dialog.overlay', {}, classNames)}
       ref={forwardedRef}
     >
       <OverlayLayoutProvider inOverlayLayout>{children}</OverlayLayoutProvider>
@@ -169,9 +121,14 @@ const AlertDialogContent: ForwardRefExoticComponent<AlertDialogContentProps> = f
     <AlertDialogPrimitive.Content
       {...props}
       className={tx('dialog.content', { inOverlayLayout, size }, classNames)}
+      // NOTE: Radix warning unless set to undefined.
+      // https://www.radix-ui.com/primitives/docs/components/dialog#description
+      aria-describedby={undefined}
       ref={forwardedRef}
     >
-      <Column.Root>{children}</Column.Root>
+      <Column.Root classNames='dx-expander' gutter='sm'>
+        {children}
+      </Column.Root>
     </AlertDialogPrimitive.Content>
   );
 });
@@ -179,49 +136,43 @@ const AlertDialogContent: ForwardRefExoticComponent<AlertDialogContentProps> = f
 AlertDialogContent.displayName = ALERT_DIALOG_CONTENT_NAME;
 
 //
-// Body
+// Title
 //
 
-type AlertDialogBodyProps = PropsWithChildren;
+type AlertDialogTitleProps = ThemedClassName<AlertDialogPrimitive.AlertDialogTitleProps> & { srOnly?: boolean };
 
-const AlertDialogBody: ForwardRefExoticComponent<AlertDialogBodyProps> = forwardRef<
-  HTMLDivElement,
-  AlertDialogBodyProps
->(({ children, ...props }, forwardedRef) => {
+const AlertDialogTitle: ForwardRefExoticComponent<AlertDialogTitleProps> = forwardRef<
+  HTMLHeadingElement,
+  AlertDialogTitleProps
+>(({ classNames, srOnly, ...props }, forwardedRef) => {
   const { tx } = useThemeContext();
   return (
-    <Column.Segment asChild>
-      <div role='none' {...props} className={tx('dialog.body')} ref={forwardedRef}>
-        {children}
-      </div>
-    </Column.Segment>
+    <AlertDialogPrimitive.Title {...props} className={tx('dialog.title', { srOnly }, classNames)} ref={forwardedRef} />
   );
 });
 
-AlertDialogBody.displayName = ALERT_DIALOG_BODY_NAME;
-
 //
-// ActionBar
+// Description
 //
 
-type AlertDialogActionBarProps = ThemedClassName<PropsWithChildren>;
+type AlertDialogDescriptionProps = ThemedClassName<AlertDialogPrimitive.AlertDialogDescriptionProps> & {
+  srOnly?: boolean;
+};
 
-const AlertDialogActionBar: ForwardRefExoticComponent<AlertDialogActionBarProps> = forwardRef<
-  HTMLDivElement,
-  AlertDialogActionBarProps
->(({ children, classNames, ...props }, forwardedRef) => {
+const AlertDialogDescription: ForwardRefExoticComponent<AlertDialogDescriptionProps> = forwardRef<
+  HTMLParagraphElement,
+  AlertDialogDescriptionProps
+>(({ classNames, srOnly, ...props }, forwardedRef) => {
   const { tx } = useThemeContext();
   return (
-    <Column.Segment asChild>
-      <div {...props} className={tx('dialog.actionbar', {}, classNames)} ref={forwardedRef}>
-        {children}
-      </div>
-    </Column.Segment>
+    <AlertDialogPrimitive.Description
+      {...props}
+      className={tx('dialog.description', { srOnly }, classNames)}
+      ref={forwardedRef}
+    />
   );
 });
 
-AlertDialogActionBar.displayName = ALERT_DIALOG_ACTIONBAR_NAME;
-
 //
 // AlertDialog
 //
@@ -232,10 +183,14 @@ export const AlertDialog = {
   Portal: AlertDialogPortal,
   Overlay: AlertDialogOverlay,
   Content: AlertDialogContent,
-  Body: AlertDialogBody,
+  // Shared with Dialog.
+  Header: Dialog.Header,
+  Body: Dialog.Body,
   Title: AlertDialogTitle,
   Description: AlertDialogDescription,
-  ActionBar: AlertDialogActionBar,
+  ActionBar: Dialog.ActionBar,
+  CloseIconButton: Dialog.CloseIconButton,
+  // AlertDialog-specific dismissal.
   Cancel: AlertDialogCancel,
   Action: AlertDialogAction,
 };
@@ -246,10 +201,13 @@ export type {
   AlertDialogPortalProps,
   AlertDialogOverlayProps,
   AlertDialogContentProps,
-  AlertDialogBodyProps,
   AlertDialogTitleProps,
   AlertDialogDescriptionProps,
-  AlertDialogActionBarProps,
   AlertDialogCancelProps,
   AlertDialogActionProps,
+  // Re-export shared types.
+  DialogHeaderProps as AlertDialogHeaderProps,
+  DialogBodyProps as AlertDialogBodyProps,
+  DialogActionBarProps as AlertDialogActionBarProps,
+  DialogCloseIconButtonProps as AlertDialogCloseIconButtonProps,
 };