@dxos/react-ui 0.8.4-main.406dc2a → 0.8.4-main.422d1c7879

package/src/components/Dialog/Dialog.tsx

@@ -0,0 +1,285 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, {
+  type ComponentPropsWithRef,
+  type ForwardRefExoticComponent,
+  type FunctionComponent,
+  forwardRef,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { composableProps, type DialogSize, osTranslations, slottable } from '@dxos/ui-theme';
+import { type SlottableProps } from '@dxos/ui-types';
+
+import { useThemeContext } from '../../hooks';
+import { Column } from '../../primitives';
+import { type ThemedClassName } from '../../util';
+import { IconButton } from '../Button';
+import { ElevationProvider } from '../ElevationProvider';
+
+//
+// Root
+//
+
+type DialogRootProps = DialogPrimitive.DialogProps;
+
+const DialogRoot: FunctionComponent<DialogRootProps> = (props) => (
+  <ElevationProvider elevation='dialog'>
+    <DialogPrimitive.Root
+      // NOTE: Radix warning unless set to undefined.
+      // https://www.radix-ui.com/primitives/docs/components/dialog#description
+      aria-describedby={undefined}
+      {...props}
+    />
+  </ElevationProvider>
+);
+
+//
+// Trigger
+//
+
+type DialogTriggerProps = DialogPrimitive.DialogTriggerProps;
+
+const DialogTrigger: FunctionComponent<DialogTriggerProps> = DialogPrimitive.Trigger;
+
+//
+// Portal
+//
+
+type DialogPortalProps = DialogPrimitive.DialogPortalProps;
+
+const DialogPortal: FunctionComponent<DialogPortalProps> = DialogPrimitive.Portal;
+
+//
+// Overlay
+//
+
+const DIALOG_OVERLAY_NAME = 'DialogOverlay';
+
+type OverlayLayoutContextValue = { inOverlayLayout?: boolean };
+
+const [OverlayLayoutProvider, useOverlayLayoutContext] = createContext<OverlayLayoutContextValue>(
+  DIALOG_OVERLAY_NAME,
+  {},
+);
+
+type DialogOverlayProps = ThemedClassName<
+  DialogPrimitive.DialogOverlayProps & { blockAlign?: 'center' | 'start' | 'end' }
+>;
+
+const DialogOverlay: ForwardRefExoticComponent<DialogOverlayProps> = forwardRef<HTMLDivElement, DialogOverlayProps>(
+  ({ classNames, children, blockAlign, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+
+    return (
+      <DialogPrimitive.Overlay
+        {...props}
+        data-block-align={blockAlign}
+        className={tx('dialog.overlay', {}, classNames)}
+        ref={forwardedRef}
+      >
+        <OverlayLayoutProvider inOverlayLayout>{children}</OverlayLayoutProvider>
+      </DialogPrimitive.Overlay>
+    );
+  },
+);
+
+DialogOverlay.displayName = DIALOG_OVERLAY_NAME;
+
+//
+// Content
+//
+
+const DIALOG_CONTENT_NAME = 'DialogContent';
+
+type DialogContentProps = ThemedClassName<ComponentPropsWithRef<typeof DialogPrimitive.Content>> & {
+  size?: DialogSize;
+  inOverlayLayout?: boolean;
+};
+
+const DialogContent: ForwardRefExoticComponent<DialogContentProps> = forwardRef<HTMLDivElement, DialogContentProps>(
+  ({ classNames, children, size = 'md', inOverlayLayout: propsInOverlayLayout, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    const { inOverlayLayout } = useOverlayLayoutContext(DIALOG_CONTENT_NAME);
+
+    return (
+      <DialogPrimitive.Content
+        {...props}
+        // NOTE: Radix warning unless set to undefined.
+        // https://www.radix-ui.com/primitives/docs/components/dialog#description
+        aria-describedby={undefined}
+        className={tx(
+          'dialog.content',
+          {
+            size,
+            inOverlayLayout: propsInOverlayLayout || inOverlayLayout,
+          },
+          classNames,
+        )}
+        ref={forwardedRef}
+      >
+        <Column.Root classNames='dx-expander' gutter='sm'>
+          {children}
+        </Column.Root>
+      </DialogPrimitive.Content>
+    );
+  },
+);
+
+DialogContent.displayName = DIALOG_CONTENT_NAME;
+
+//
+// Header
+//
+
+type DialogHeaderProps = SlottableProps;
+
+const DialogHeader = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const { className, ...rest } = composableProps(props);
+  const Comp = asChild ? Slot : Primitive.div;
+  const { tx } = useThemeContext();
+  return (
+    <Comp {...rest} className={tx('dialog.header', {}, className)} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
+
+//
+// CloseIconButton
+//
+
+type DialogCloseIconButtonProps = { label?: string };
+
+const DialogCloseIconButton = forwardRef<HTMLButtonElement, DialogCloseIconButtonProps>(
+  ({ label, ...props }, forwardedRef) => {
+    const { t } = useTranslation(osTranslations);
+    return (
+      <IconButton
+        {...props}
+        label={label ?? t('close-dialog.label')}
+        icon='ph--x--regular'
+        iconOnly
+        size={4}
+        variant='ghost'
+        ref={forwardedRef}
+      />
+    );
+  },
+);
+
+//
+// Body
+//
+
+type DialogBodyProps = SlottableProps;
+
+const DialogBody = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const { className, ...rest } = composableProps(props);
+  const Comp = asChild ? Slot : Primitive.div;
+  const { tx } = useThemeContext();
+  return (
+    <Comp {...rest} className={tx('dialog.body', {}, className)} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
+
+//
+// Title
+//
+
+type DialogTitleProps = ThemedClassName<DialogPrimitive.DialogTitleProps> & { srOnly?: boolean };
+
+const DialogTitle = forwardRef<HTMLHeadingElement, DialogTitleProps>(
+  ({ classNames, srOnly, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    return (
+      <DialogPrimitive.Title {...props} className={tx('dialog.title', { srOnly }, classNames)} ref={forwardedRef} />
+    );
+  },
+);
+
+//
+// Description
+//
+
+type DialogDescriptionProps = ThemedClassName<DialogPrimitive.DialogDescriptionProps> & { srOnly?: boolean };
+
+const DialogDescription = forwardRef<HTMLParagraphElement, DialogDescriptionProps>(
+  ({ classNames, srOnly, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    return (
+      <DialogPrimitive.Description
+        {...props}
+        className={tx('dialog.description', { srOnly }, classNames)}
+        ref={forwardedRef}
+      />
+    );
+  },
+);
+
+//
+// ActionBar
+//
+
+type DialogActionBarProps = SlottableProps;
+
+const DialogActionBar = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const { className: classNames, ...rest } = composableProps(props);
+  const Comp = asChild ? Slot : Primitive.div;
+  const { tx } = useThemeContext();
+  return (
+    <Comp {...rest} className={tx('dialog.actionbar', {}, classNames)} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
+
+//
+// Close
+//
+
+type DialogCloseProps = DialogPrimitive.DialogCloseProps;
+
+const DialogClose: FunctionComponent<DialogCloseProps> = DialogPrimitive.Close;
+
+//
+// Dialog
+//
+
+export const Dialog = {
+  Root: DialogRoot,
+  Trigger: DialogTrigger,
+  Portal: DialogPortal,
+  Overlay: DialogOverlay,
+  Content: DialogContent,
+  Header: DialogHeader,
+  Body: DialogBody,
+  Title: DialogTitle,
+  Description: DialogDescription,
+  ActionBar: DialogActionBar,
+  Close: DialogClose,
+  CloseIconButton: DialogCloseIconButton,
+};
+
+export type {
+  DialogRootProps,
+  DialogTriggerProps,
+  DialogPortalProps,
+  DialogOverlayProps,
+  DialogContentProps,
+  DialogHeaderProps,
+  DialogBodyProps,
+  DialogTitleProps,
+  DialogDescriptionProps,
+  DialogActionBarProps,
+  DialogCloseProps,
+  DialogCloseIconButtonProps,
+};

package/src/components/ElevationProvider/ElevationProvider.tsx

@@ -4,7 +4,7 @@
 
 import React, { type PropsWithChildren, createContext } from 'react';
 
-import { type Elevation } from '@dxos/react-ui-types';
+import { type Elevation } from '@dxos/ui-types';
 
 export interface ElevationContextValue {
   elevation?: Elevation;

package/src/components/ErrorFallback/ErrorFallback.stories.tsx

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { ErrorBoundary } from '@dxos/react-error-boundary';
+
+import { withLayout, withTheme } from '../../testing';
+import { ErrorFallback } from './ErrorFallback';
+import { ThrowError } from './ThrowError';
+
+const DefaultStory = () => {
+  return (
+    <ErrorBoundary name='story' FallbackComponent={ErrorFallback}>
+      <ThrowError />
+    </ErrorBoundary>
+  );
+};
+
+const meta: Meta = {
+  title: 'ui/react-ui-core/components/ErrorFallback',
+  component: ErrorFallback,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: DefaultStory,
+  play: async () => {
+    // This story intentionally renders an ErrorBoundary fallback; clear the smoke-test error flag.
+    (window as any).__ERROR_BOUNDARY_ERRORS__ = [];
+  },
+};
+
+export const StringError: Story = {
+  render: () => <ErrorFallback error='This is a string error message' data={{ context: 'story' }} />,
+};

package/src/components/ErrorFallback/ErrorFallback.tsx

@@ -0,0 +1,70 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+import { type FallbackProps } from 'react-error-boundary';
+
+import { safeStringify } from '@dxos/util';
+
+import { ErrorStack } from './ErrorStack';
+
+export type ErrorFallbackProps = PropsWithChildren<Pick<FallbackProps, 'error'> & { title?: string; data?: any }>;
+
+/**
+ * Themed fallback component for `ErrorBoundary`.
+ */
+export const ErrorFallback = ({ children, error, title, data }: ErrorFallbackProps) => {
+  const isDev = process.env.NODE_ENV === 'development';
+  const message = error instanceof Error ? error.message : String(error);
+
+  return (
+    <div role='alert' data-testid='error-boundary-fallback' className='flex flex-col p-4 gap-4 overflow-auto'>
+      <h1 className='text-lg text-info-text'>{title ?? 'Runtime Error'}</h1>
+      <p>{message}</p>
+
+      {isDev && error instanceof Error && (
+        <Section
+          title='Stack'
+          onClick={() => {
+            const text = error instanceof Error ? (error.stack ?? error.message) : String(error);
+            void navigator.clipboard.writeText(text);
+          }}
+        >
+          <ErrorStack error={error} />
+        </Section>
+      )}
+
+      {data && (
+        <Section
+          title='Data'
+          onClick={() => {
+            void navigator.clipboard.writeText(JSON.stringify(data, undefined, 2));
+          }}
+        >
+          <pre className='overflow-x-auto text-xs'>{safeStringify(data, undefined, 2)}</pre>
+        </Section>
+      )}
+
+      {children}
+    </div>
+  );
+};
+
+const Section = ({ children, title, onClick }: PropsWithChildren<{ title?: string; onClick?: () => void }>) => {
+  return (
+    <div className='flex flex-col gap-1'>
+      {onClick && (
+        <button
+          type='button'
+          onClick={onClick}
+          className='flex items-center gap-1 text-xs text-subdued hover:text-primary-500 transition-colors'
+          title={`Copy ${title}`}
+        >
+          <h2 className='text-xs uppercase text-subdued'>{title}</h2>
+        </button>
+      )}
+      {children}
+    </div>
+  );
+};

package/src/components/ErrorFallback/ErrorStack.tsx

@@ -0,0 +1,114 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import ErrorStackParser from 'error-stack-parser';
+import React from 'react';
+
+import { mx } from '@dxos/ui-theme';
+
+type LocalFrame = { href: string; fileName: string };
+
+export type ParsedStackFrame = ReturnType<typeof ErrorStackParser.parse>[number];
+
+export type ErrorStackProps = {
+  /** When set, these frames are shown instead of parsing `error`. */
+  frames?: ParsedStackFrame[];
+  /** Used when `frames` is omitted. */
+  error?: Error;
+};
+
+/**
+ * Parses `captureOwnerStack()` output (React dev) into frames for {@link ErrorStack}.
+ * Prefixes a synthetic Error line when needed so `error-stack-parser` can read V8-style stacks.
+ */
+export const parseCaptureOwnerStack = (stack: string | null): ParsedStackFrame[] | null => {
+  if (stack == null || stack.length === 0) {
+    return null;
+  }
+  const err = new Error();
+  err.stack = stack;
+  try {
+    return ErrorStackParser.parse(err);
+  } catch {
+    err.stack = `Error\n${stack}`;
+    try {
+      return ErrorStackParser.parse(err);
+    } catch {
+      return null;
+    }
+  }
+};
+
+/**
+ * Renders a parsed error stack trace with tree connector symbols and clickable vscode:// links for local frames.
+ */
+export const ErrorStack = ({ error, frames: framesProp }: ErrorStackProps) => {
+  const frames = framesProp ?? (error ? ErrorStackParser.parse(error) : []);
+  if (frames.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className='font-mono text-sm'>
+      {frames.map((frame, i) => {
+        const isLast = i === frames.length - 1;
+        const local = frame.fileName
+          ? parseLocalFrame(frame.fileName, frame.lineNumber, frame.columnNumber)
+          : undefined;
+        const name = frame.functionName ?? '<anonymous>';
+        return (
+          <div
+            key={i}
+            className={mx(
+              'grid grid-cols-[16px_1fr_auto_auto] items-stretch gap-x-2',
+              local && 'cursor-pointer hover:bg-hover-surface',
+            )}
+          >
+            {/* Tree connector: vertical line full-height + horizontal branch at midpoint */}
+            <div className='relative'>
+              <div
+                className={mx(
+                  'absolute left-1/2 -translate-x-1/2 w-px bg-neutral-500',
+                  isLast ? 'top-0 h-1/2' : 'inset-y-0',
+                )}
+              />
+              <div className='absolute top-1/2 -translate-y-1/2 left-1/2 right-0 h-px bg-neutral-500' />
+            </div>
+            {local ? (
+              <a href={local.href} className='truncate self-center'>
+                {name}
+              </a>
+            ) : (
+              <span className='text-subdued truncate self-center'>{name}</span>
+            )}
+            <span className='text-xs text-subdued truncate self-center'>{local?.fileName ?? ''}</span>
+            <span className='text-xs text-subdued text-right self-center'>
+              {local ? `${frame.lineNumber}:${frame.columnNumber}` : ''}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+/**
+ * Parses a Vite `/@fs/` URL into a `vscode://` deep link and short filename.
+ * Returns undefined if the URL cannot be resolved to a local file.
+ */
+const parseLocalFrame = (fileUrl: string, line?: number, col?: number): LocalFrame | undefined => {
+  try {
+    const { pathname } = new URL(fileUrl);
+    if (!pathname.startsWith('/@fs/')) {
+      return undefined;
+    }
+    const localPath = pathname.slice(4); // /@fs/Users/... → /Users/...
+    return {
+      href: `vscode://file/${localPath}:${line ?? 1}:${col ?? 1}`,
+      fileName: pathname.split('/').pop() ?? localPath,
+    };
+  } catch {
+    return undefined;
+  }
+};

package/src/components/ErrorFallback/ThrowError.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+export type ThrowErrorProps = {
+  error?: () => Error;
+  delay?: number;
+};
+
+/**
+ * Use this to debug the error boundary.
+ */
+export const ThrowError = ({ delay = 1_000, ...props }: ThrowErrorProps) => {
+  const [error, setError] = useState<Error>();
+  useEffect(() => {
+    if (delay < 0) {
+      return;
+    }
+
+    const t = setTimeout(() => {
+      setError(generator({ delay, ...props }));
+    }, delay);
+    return () => clearTimeout(t);
+  }, [delay, generator]);
+
+  if (error) {
+    throw error;
+  }
+
+  return null;
+};
+
+const generator = ({ error, delay }: ThrowErrorProps) => {
+  return error?.() ?? new Error(`Error generated after ${delay}ms`);
+};

package/src/components/ErrorFallback/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { ErrorBoundary, type ErrorBoundaryProps, type FallbackProps } from '@dxos/react-error-boundary';
+
+export * from './ErrorFallback';
+export * from './ErrorStack';
+export * from './ThrowError';

package/src/components/Focus/AUDIT.md

@@ -0,0 +1,43 @@
+# Focus
+
+## Problem
+
+Grid cells use `overflow-hidden` which clips outward CSS `ring` (box-shadow) and `outline` styles.
+Using `border` for focus indicators creates doubled lines at grid cell boundaries.
+Inset `box-shadow` alone is obscured by child elements with backgrounds (e.g., toolbar headers).
+
+## Solution
+
+Uses a `::after` pseudo-element overlay with `ring-inset` to paint the focus ring above all child content.
+The pseudo-element is absolutely positioned, `pointer-events-none`, and inherits `border-radius`.
+
+- **Default**: ring is transparent (invisible until focused).
+- **`border` prop**: shows a CSS `border-separator` when unfocused (e.g., for grid cell edges).
+- **Focus/active/error states**: ring color changes to the appropriate indicator color.
+
+Both `Focus.Group` and `Focus.Item` support the `border` prop.
+
+## Why `::after` overlay
+
+| Approach                 | Clipped? | Obscured by children? | Notes                                                                 |
+| ------------------------ | -------- | --------------------- | --------------------------------------------------------------------- |
+| `ring` (outward)         | Yes      | N/A                   | Extends outside bounds, clipped by parent `overflow-hidden`.          |
+| `ring-inset`             | No       | Yes                   | Inset box-shadow is part of background layer; children paint over it. |
+| `::after` + `ring-inset` | No       | No                    | Pseudo-element paints above children. Requires `position: relative`.  |
+
+## Relationship to `dx-focus-ring-inset-over-all`
+
+The CSS class `dx-focus-ring-inset-over-all` (in `focus-ring.css`) uses the same `::after` technique
+but only reacts to `:focus-visible`. `Focus.Group/Item` additionally support programmatic states
+via `data-focus-state` (`active`, `error`).
+
+## Clean-up
+
+- [ ] Unify: extend `dx-focus-ring-inset-over-all` to support `data-focus-state` attributes,
+      then have `Focus.Group/Item` use the CSS class instead of inline Tailwind utilities.
+      Consumers: Plank, StackItem, Tabs, AttentionProvider, main sidebar.
+
+## Audit
+
+- [ ] Create a list of all container components (outside of `react-ui`) that directly use `overflow-hidden`;
+      Consider containers to be components that have `children` and expand (e.g., `grid`, `grow`, `h-full`, `w-full`).