@dxos/react-ui 0.8.4-staging.ac66bdf99f → 0.9.1-main.c7dcc2e112

package/src/components/Carousel/Carousel.stories.tsx

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { withTheme } from '../../testing';
+import { Carousel } from './Carousel';
+
+// Stable placeholder images so the story renders without network fixtures.
+const IMAGES = Array.from({ length: 5 }).map((_, index) => `https://placehold.co/640x360?text=Slide+${index + 1}`);
+
+type DefaultStoryProps = { count?: number };
+
+const DefaultStory = ({ count = IMAGES.length }: DefaultStoryProps) => {
+  const images = IMAGES.slice(0, count);
+  return (
+    <Carousel.Root count={images.length}>
+      <Carousel.Content classNames='max-w-[40rem]'>
+        <Carousel.Previous />
+        <Carousel.Viewport>
+          {images.map((src, index) => (
+            <Carousel.Slide key={src} index={index} src={src} alt={`Slide ${index + 1}`} />
+          ))}
+        </Carousel.Viewport>
+        <Carousel.Next />
+        <Carousel.Indicators />
+        <Carousel.Caption>{(index) => `Slide ${index + 1} of ${images.length}`}</Carousel.Caption>
+      </Carousel.Content>
+    </Carousel.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-core/components/Carousel',
+  render: DefaultStory,
+  decorators: [withTheme()],
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { count: 5 },
+};

package/src/components/Carousel/Carousel.tsx

@@ -0,0 +1,373 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useArrowNavigationGroup } from '@fluentui/react-tabster';
+import { createContext } from '@radix-ui/react-context';
+import React, {
+  type KeyboardEvent,
+  type PropsWithChildren,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useState,
+} from 'react';
+
+import { mx } from '@dxos/ui-theme';
+
+import { useTranslation } from '../../primitives';
+import { translationKey } from '../../translations';
+import { type ThemedClassName, composable, composableProps } from '../../util';
+import { IconButton } from '../Button';
+import { MediaPlayer, type MediaKind } from '../MediaPlayer';
+
+// 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 CAROUSEL_NAME = 'Carousel';
+
+const [CarouselProvider, useCarouselContext] = createContext<CarouselContextValue>(CAROUSEL_NAME);
+
+/** Returns the current carousel state. Must be used within {@link Carousel.Root}. */
+export const useCarousel = (): CarouselContextValue => useCarouselContext('useCarousel');
+
+//
+// Root
+//
+
+export type CarouselRootProps = 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 = ({
+  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]);
+
+  if (count === 0) {
+    return null;
+  }
+
+  return (
+    <CarouselProvider index={index} count={count} setIndex={setIndex} next={next} prev={prev}>
+      {children}
+    </CarouselProvider>
+  );
+};
+
+CarouselRoot.displayName = 'Carousel.Root';
+
+//
+// Content
+//
+
+export type CarouselContentProps = ThemedClassName<PropsWithChildren<{}>>;
+
+// `composable` so a parent `<… asChild>` (Slot) is respected — the injected className/ref land on the grid.
+const CarouselContent = composable<HTMLDivElement>(({ children, ...props }, forwardedRef) => (
+  // 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 Carousel.theme.ts
+  <div
+    {...composableProps(props, {
+      classNames:
+        'w-full grid grid-cols-[min-content_1fr_min-content] grid-rows-[minmax(0,1fr)_auto] gap-4 items-center',
+    })}
+    ref={forwardedRef}
+  >
+    {children}
+  </div>
+));
+
+CarouselContent.displayName = 'Carousel.Content';
+
+//
+// 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;
+  controls?: boolean;
+  autoPlay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  crossOrigin?: 'anonymous' | 'use-credentials' | '';
+}>;
+
+const CarouselSlide = ({
+  index,
+  classNames,
+  src,
+  kind,
+  alt,
+  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'
+        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,
+  Content: CarouselContent,
+  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

@@ -6,9 +6,9 @@ import React from 'react';
 
 import { mx, osTranslations } from '@dxos/ui-theme';
 
+import { useTranslation } from '../../primitives';
 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';
 
@@ -30,11 +30,11 @@ 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)}>
+      <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)}>
+      <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>

package/src/{primitives → components}/Column/Column.stories.tsx

@@ -71,7 +71,7 @@ const DefaultStory = () => {
 };
 
 const meta: Meta = {
-  title: 'ui/react-ui-core/primitives/Column',
+  title: 'ui/react-ui-core/components/Column',
   render: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-[25rem]' })],
   parameters: {

package/src/components/Column/Column.theme.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { mx } from '@dxos/ui-theme';
+import { type ComponentFunction } from '@dxos/ui-types';
+
+import { withColumn } from './withColumn';
+
+export type ColumnStyleProps = {};
+
+export type ColumnBlockStyleProps = {
+  /** Trailing gutter (column 3) instead of the default leading gutter (column 1). */
+  end?: boolean;
+  compact?: boolean;
+  /** Constrain to a square (1:1) slot rather than the default rail-item width. */
+  square?: boolean;
+};
+
+const root: ComponentFunction<ColumnStyleProps> = (_, ...etc) => {
+  return mx('dx-column-root grid', ...etc);
+};
+
+/**
+ * Three-column subgrid row spanning all 3 columns of the parent Column.Root grid.
+ * Placement is explicit, not source-order based:
+ * - `Column.Block` self-places into column 1 (leading) or column 3 (trailing, `end`) and
+ *   carries the `dx-gutter` marker class.
+ * - Every other (content) child is placed in column 2 via `[&>*:not(.dx-gutter)]`.
+ * Class-based placement (rather than `[data-slot=…]`) is used because Tailwind does not
+ * generate arbitrary variants that nest a square-bracket attribute selector.
+ * Robust to conditional children: a falsy leading slot never shifts content into a gutter.
+ * NOTE: Must not use overflow-hidden here since it will clip input focus rings.
+ */
+const row: ComponentFunction<ColumnStyleProps> = (_, ...etc) => {
+  return mx('col-span-3 grid grid-cols-subgrid', '[&>*:not(.dx-gutter)]:col-start-2', ...etc);
+};
+
+/**
+ * Gutter slot geometry: a `--dx-rail-item` square that centers its child, so a passive
+ * `<Icon>` and an interactive `IconButton` line up to the pixel. Self-places into column 1
+ * (default) or column 3 (`end`); the `dx-gutter` marker keeps it out of the content track.
+ */
+const block: ComponentFunction<ColumnBlockStyleProps> = ({ end, compact, square }, ...etc) =>
+  mx(
+    'dx-gutter grid place-items-center [&>img]:max-w-[1.5rem]',
+    end ? 'col-start-3' : 'col-start-1',
+    square ? 'aspect-square' : 'w-[var(--dx-rail-item)]',
+    compact ? '' : 'h-[var(--dx-rail-item)]',
+    ...etc,
+  );
+
+/**
+ * Bleed placement: spans all 3 columns of the parent Column.Root grid (gutter-to-gutter).
+ * Use for `ScrollArea`, full-width dividers, tables, or any content that should ignore gutters.
+ */
+const bleed: ComponentFunction<ColumnStyleProps> = (_, ...etc) => {
+  return mx('col-span-full grid grid-cols-subgrid min-h-0', ...etc);
+};
+
+/**
+ * Center placement: places the element in column 2 (the central track between gutters) of the
+ * parent Column.Root grid. Does NOT use subgrid — placement is explicit on this element only.
+ * Safe to nest arbitrary compound components (including those that render `display: contents`).
+ */
+const center: ComponentFunction<ColumnStyleProps> = (_, ...etc) => {
+  return mx(withColumn.center(), 'min-h-0', ...etc);
+};
+
+export const columnTheme = {
+  root,
+  row,
+  block,
+  bleed,
+  center,
+};

package/src/{primitives → components}/Column/Column.tsx

@@ -6,10 +6,10 @@ import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
 import React, { type CSSProperties } from 'react';
 
-import { composableProps, slottable } from '@dxos/ui-theme';
 import { type SlottableProps } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
+import { composableProps, slottable } from '../../util';
 
 //
 // Root
@@ -57,6 +57,7 @@ const ColumnRoot = slottable<HTMLDivElement, ColumnRootProps>(
         role={role ?? 'none'}
         style={
           {
+            ...rest.style,
             '--gutter': gutterSize,
             '--dx-col': '2 / span 1',
             gridTemplateColumns: [gutterSize, 'minmax(0,1fr)', gutterSize].join(' '),
@@ -151,6 +152,40 @@ const ColumnCenter = slottable<HTMLDivElement>(({ children, asChild, ...props },
 
 ColumnCenter.displayName = COLUMN_CENTER_NAME;
 
+//
+// Block
+//
+
+const COLUMN_BLOCK_NAME = 'Column.Block';
+
+type ColumnBlockProps = SlottableProps<{ end?: boolean; compact?: boolean; square?: boolean }>;
+
+/**
+ * A gutter slot inside a Column.Row. Sized to `--dx-rail-item` and centers its child so a passive
+ * `<Icon>` and an interactive `IconButton` align to the pixel. `end` opts into the trailing gutter
+ * (column 3); default is the leading gutter (column 1). Placement is via `data-slot`, so it is
+ * robust to conditional rendering and source order.
+ */
+const ColumnBlock = slottable<HTMLDivElement, ColumnBlockProps>(
+  ({ children, asChild, end, compact, square, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    const { className, ...rest } = composableProps(props);
+    const Comp = asChild ? Slot : Primitive.div;
+    return (
+      <Comp
+        {...rest}
+        data-slot={end ? 'end' : 'start'}
+        className={tx('column.block', { end, compact, square }, className)}
+        ref={forwardedRef}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+ColumnBlock.displayName = COLUMN_BLOCK_NAME;
+
 //
 // Column
 //
@@ -158,8 +193,9 @@ ColumnCenter.displayName = COLUMN_CENTER_NAME;
 export const Column = {
   Root: ColumnRoot,
   Row: ColumnRow,
+  Block: ColumnBlock,
   Bleed: ColumnBleed,
   Center: ColumnCenter,
 };
 
-export type { ColumnRootProps, ColumnRowProps, ColumnBleedProps, ColumnCenterProps };
+export type { ColumnRootProps, ColumnRowProps, ColumnBlockProps, ColumnBleedProps, ColumnCenterProps };

package/src/{primitives → components}/Column/index.ts

@@ -3,3 +3,4 @@
 //
 
 export * from './Column';
+export * from './withColumn';

package/src/components/Column/withColumn.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Column-aware theme utilities.
+ * Components apply these in their theme functions to participate in the Column grid
+ * without importing Column React components.
+ *
+ * CSS custom property cascade:
+ * - Column.Root sets `--dx-col: 2 / span 1` (center column placement).
+ * - ScrollArea.Viewport resets `--dx-col: auto` after consuming `--gutter`.
+ * - Components apply `grid-column: var(--dx-col, auto)` to auto-center in Column
+ *   or do nothing outside Column / inside ScrollArea.
+ */
+export const withColumn = {
+  /** Centers element in the Column grid via --dx-col. No-op outside Column or inside ScrollArea. */
+  center: () => '[grid-column:var(--dx-col,auto)]',
+
+  /** Propagates the Column grid to children via subgrid. No-op outside Column.
+   *  Direct children default to center column unless they are a dx-container (ScrollArea). */
+  propagate: () =>
+    '[.dx-column-root_&]:col-span-full [.dx-column-root_&]:grid [.dx-column-root_&]:grid-cols-subgrid [.dx-column-root_&]:[&>*:not(.dx-container)]:[grid-column:var(--dx-col,auto)]',
+
+  /** Resets --dx-col after consuming --gutter. Applied by ScrollArea.Viewport. */
+  consumed: () => '[--dx-col:auto]',
+};