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

package/src/components/Splitter/Splitter.tsx

@@ -2,31 +2,125 @@
 // Copyright 2026 DXOS.org
 //
 
-import { createContextScope } from '@radix-ui/react-context';
+import { useComposedRefs } from '@radix-ui/react-compose-refs';
+import { createContext } from '@radix-ui/react-context';
 import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
-import React from 'react';
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import React, {
+  type CSSProperties,
+  type KeyboardEvent,
+  type PointerEvent,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+
+import { type SlottableProps } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
 import { composableProps, slottable } from '../../util';
-import { ThemedClassName } from '../../util';
 
-type ScopedProps<P> = P & { __scopeSplitter?: any };
+type SplitterOrientation = 'horizontal' | 'vertical';
+
+// Animated panel visibility: collapse to the start panel, the end panel, or show both split at `size`.
+type SplitterMode = 'start' | 'end' | 'split';
+
+type Position = 'start' | 'end';
 
-// TODO(burdon): Generalize horizontal/vertical and change to start/end.
-type Mode = 'top' | 'bottom' | 'split';
+//
+// Context
+//
+
+const SPLITTER_NAME = 'Splitter';
 
 type SplitterContextValue = {
-  mode: Mode;
-  ratio?: number;
+  orientation: SplitterOrientation;
+  mode: SplitterMode;
+  /** Which panel `size` measures; the other panel fills the remainder. */
+  anchor: Position;
+  /** The anchored panel's extent in rem, or `undefined` for an even (50/50) split. */
+  size: number | undefined;
   transition: number;
+  resizable: boolean;
+  /** Lower bound (rem) applied to both panels. */
+  minSize: number;
+  dragging: boolean;
+  /** True only briefly after a `mode` change, so the collapse animates but layout reflows (resize) do not. */
+  animating: boolean;
+  rootRef: RefObject<HTMLDivElement | null>;
+  setSize: (size: number) => void;
+  setDragging: (dragging: boolean) => void;
 };
 
-const SPLITTER_NAME = 'Splitter';
+const [SplitterProvider, useSplitterContext] = createContext<SplitterContextValue>(SPLITTER_NAME);
+
+const getRem = (): number => parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
 
-const [createSplitterContext, createSplitterScope] = createContextScope(SPLITTER_NAME);
+// Lower-bound clamp applied to both panels: the start panel can't drop below `minSize` nor exceed the
+// container minus `minSize` (reserving room for the end panel, which also carries the min).
+const clampStyle = (minSize: number, orientation: SplitterOrientation): CSSProperties =>
+  orientation === 'horizontal'
+    ? { minInlineSize: `${minSize}rem`, maxInlineSize: `calc(100% - ${minSize}rem)` }
+    : { minBlockSize: `${minSize}rem`, maxBlockSize: `calc(100% - ${minSize}rem)` };
 
-const [SplitterProvider, useSplitterContext] = createSplitterContext<SplitterContextValue>(SPLITTER_NAME);
+const endMinStyle = (minSize: number, orientation: SplitterOrientation): CSSProperties =>
+  orientation === 'horizontal' ? { minInlineSize: `${minSize}rem` } : { minBlockSize: `${minSize}rem` };
+
+// In `split` mode the anchored panel is fixed at `size` rem (clamped) and the other fills the rest; when
+// `size` is undefined both panels grow equally (50/50). Otherwise one panel fills (flex-grow) and the
+// other collapses to zero (content stays mounted, clipped).
+const panelStyle = (
+  position: Position,
+  mode: SplitterMode,
+  anchor: Position,
+  size: number | undefined,
+  minSize: number,
+  orientation: SplitterOrientation,
+): CSSProperties => {
+  if (mode !== 'split') {
+    const fills = (mode === 'start' && position === 'start') || (mode === 'end' && position === 'end');
+    return { flexGrow: fills ? 1 : 0, flexShrink: 1, flexBasis: 0 };
+  }
+
+  // No explicit size: split evenly.
+  if (size === undefined) {
+    return { flexGrow: 1, flexShrink: 1, flexBasis: 0, ...endMinStyle(minSize, orientation) };
+  }
+
+  return position === anchor
+    ? { flexGrow: 0, flexShrink: 1, flexBasis: `${size}rem`, ...clampStyle(minSize, orientation) }
+    : { flexGrow: 1, flexShrink: 1, flexBasis: 0, ...endMinStyle(minSize, orientation) };
+};
+
+// Absolute position for the handle, centered on the split point (`size` rem from the anchored edge, or
+// the middle for an even split). The offset is clamped to the same bounds as the anchored panel
+// (`minSize` .. `100% - minSize`) so a sudden container shrink (e.g. opening devtools) that caps the
+// panel keeps the handle pinned to the panel edge instead of floating into the other panel.
+const handlePosition = (
+  orientation: SplitterOrientation,
+  anchor: Position,
+  size: number | undefined,
+  minSize: number,
+): CSSProperties => {
+  if (size === undefined) {
+    return orientation === 'horizontal'
+      ? { insetBlock: 0, insetInlineStart: '50%', transform: 'translateX(-50%)' }
+      : { insetInline: 0, insetBlockStart: '50%', transform: 'translateY(-50%)' };
+  }
+
+  const offset = `clamp(${minSize}rem, ${size}rem, calc(100% - ${minSize}rem))`;
+  if (orientation === 'horizontal') {
+    return anchor === 'end'
+      ? { insetBlock: 0, insetInlineEnd: offset, transform: 'translateX(50%)' }
+      : { insetBlock: 0, insetInlineStart: offset, transform: 'translateX(-50%)' };
+  }
+  return anchor === 'end'
+    ? { insetInline: 0, insetBlockEnd: offset, transform: 'translateY(50%)' }
+    : { insetInline: 0, insetBlockStart: offset, transform: 'translateY(-50%)' };
+};
 
 //
 // Root
@@ -34,18 +128,88 @@ const [SplitterProvider, useSplitterContext] = createSplitterContext<SplitterCon
 
 const ROOT_NAME = 'Splitter.Root';
 
-type SplitterRootProps = Partial<SplitterContextValue>;
+type SplitterRootElementProps = {
+  orientation?: SplitterOrientation;
+  mode?: SplitterMode;
+  /** Which panel `size` measures (defaults to `start`); the other panel fills the remainder. */
+  anchor?: Position;
+  /** The anchored panel's extent in rem (controlled). */
+  size?: number;
+  defaultSize?: number;
+  onSizeChange?: (size: number) => void;
+  transition?: number;
+  resizable?: boolean;
+  /** Lower bound (rem) applied to both panels. */
+  minSize?: number;
+};
+
+type SplitterRootProps = SlottableProps<SplitterRootElementProps>;
 
-const SplitterRoot = slottable<HTMLDivElement, SplitterRootProps>(
-  ({ asChild, mode = 'top', ratio = 0.5, transition = 250, children, ...props }, forwardedRef) => {
+const SplitterRoot = slottable<HTMLDivElement, SplitterRootElementProps>(
+  (
+    {
+      asChild,
+      children,
+      orientation = 'vertical',
+      mode = 'split',
+      anchor = 'start',
+      size: sizeProp,
+      defaultSize,
+      onSizeChange,
+      transition = 250,
+      resizable = false,
+      minSize = 0,
+      ...props
+    },
+    forwardedRef,
+  ) => {
     const { tx } = useThemeContext();
-    const { __scopeSplitter, ...rest } = props as ScopedProps<typeof props>;
-    const { className, ...restProps } = composableProps(rest);
+    const rootRef = useRef<HTMLDivElement>(null);
+    const composedRef = useComposedRefs(forwardedRef, rootRef);
+    const [size, setSize] = useControllableState({
+      prop: sizeProp,
+      defaultProp: defaultSize,
+      onChange: onSizeChange,
+    });
+    const [dragging, setDragging] = useState(false);
+
+    // Animate ONLY for a brief window right after a `mode` change (the collapse). The rest of the time the
+    // transition is off, so layout reflows from a container/window resize never animate (no jitter) — this
+    // avoids relying on observing/throttling resize events at all.
+    const [animating, setAnimating] = useState(false);
+    const previousMode = useRef(mode);
+    useEffect(() => {
+      if (previousMode.current === mode) {
+        return;
+      }
+      previousMode.current = mode;
+      if (transition <= 0) {
+        return;
+      }
+      setAnimating(true);
+      const timer = setTimeout(() => setAnimating(false), transition);
+      return () => clearTimeout(timer);
+    }, [mode, transition]);
+
+    const { className, ...rest } = composableProps(props);
     const Comp = asChild ? Slot : Primitive.div;
 
     return (
-      <SplitterProvider scope={__scopeSplitter} mode={mode} ratio={ratio} transition={transition}>
-        <Comp {...restProps} ref={forwardedRef} className={tx('splitter.root', {}, className)}>
+      <SplitterProvider
+        orientation={orientation}
+        mode={mode}
+        anchor={anchor}
+        size={size}
+        transition={transition}
+        resizable={resizable}
+        minSize={minSize}
+        animating={animating}
+        dragging={dragging}
+        rootRef={rootRef}
+        setSize={setSize}
+        setDragging={setDragging}
+      >
+        <Comp {...rest} ref={composedRef} className={tx('splitter.root', { orientation }, className)}>
           {children}
         </Comp>
       </SplitterProvider>
@@ -61,42 +225,28 @@ SplitterRoot.displayName = ROOT_NAME;
 
 const PANEL_NAME = 'Splitter.Panel';
 
-type SplitterPanelProps = ThemedClassName<{
-  position: 'top' | 'bottom';
-}>;
+type SplitterPanelProps = SlottableProps<{ position: Position }>;
 
-const SplitterPanel = slottable<HTMLDivElement, SplitterPanelProps>(
-  ({ classNames, asChild, children, position, style, ...props }, forwardedRef) => {
+const SplitterPanel = slottable<HTMLDivElement, { position: Position }>(
+  ({ asChild, children, position, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
-    const { __scopeSplitter, ...rest } = props as ScopedProps<typeof props>;
+    const { orientation, mode, anchor, size, minSize, transition, dragging, animating } =
+      useSplitterContext(PANEL_NAME);
+    const { className, style, ...rest } = composableProps(props);
     const Comp = asChild ? Slot : Primitive.div;
-    const { mode, ratio = 0.5, transition } = useSplitterContext(PANEL_NAME, __scopeSplitter);
-    const { className, ...restProps } = composableProps(rest);
-
-    // Calculate position and height based on mode and ratio.
-    const isTopPanel = position === 'top';
-    const topOffset = isTopPanel ? '0%' : mode === 'top' ? '100%' : mode === 'bottom' ? '0%' : `${ratio * 100}%`;
-    const height = isTopPanel
-      ? mode === 'top'
-        ? '100%'
-        : mode === 'bottom'
-          ? '0%'
-          : `${ratio * 100}%`
-      : mode === 'bottom'
-        ? '100%'
-        : mode === 'top'
-          ? '0%'
-          : `${(1 - ratio) * 100}%`;
+
+    // Only animate during the brief post-mode-change window (collapse), never while dragging or on a plain
+    // container/window resize — so the panels track layout reflows instantly without jitter.
+    const animate = transition > 0 && animating && !dragging;
 
     return (
       <Comp
-        {...restProps}
+        {...rest}
         ref={forwardedRef}
         className={tx('splitter.panel', {}, className)}
         style={{
-          top: topOffset,
-          height,
-          transition: `top ${transition}ms, height ${transition}ms ease-out`,
+          ...panelStyle(position, mode, anchor, size, minSize, orientation),
+          transition: animate ? `flex-grow ${transition}ms ease-out, flex-basis ${transition}ms ease-out` : undefined,
           ...style,
         }}
       >
@@ -108,6 +258,128 @@ const SplitterPanel = slottable<HTMLDivElement, SplitterPanelProps>(
 
 SplitterPanel.displayName = PANEL_NAME;
 
+//
+// Handle
+//
+
+const HANDLE_NAME = 'Splitter.Handle';
+
+type SplitterHandleProps = SlottableProps;
+
+const SplitterHandle = slottable<HTMLDivElement>(({ asChild, children, ...props }, forwardedRef) => {
+  const { tx } = useThemeContext();
+  const { orientation, anchor, size, resizable, minSize, rootRef, setSize, setDragging } =
+    useSplitterContext(HANDLE_NAME);
+  const { className, ...rest } = composableProps(props);
+  const Comp = asChild ? Slot : Primitive.div;
+
+  // Container extent (rem) along the split axis; the upper bound is `extent - minSize`.
+  const extentRem = useCallback((): number => {
+    const rect = rootRef.current?.getBoundingClientRect();
+    if (!rect) {
+      return (size ?? minSize) + minSize;
+    }
+    return (orientation === 'horizontal' ? rect.width : rect.height) / getRem();
+  }, [orientation, rootRef, size, minSize]);
+
+  const handlePointerDown = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      if (event.button !== 0) {
+        return;
+      }
+      event.preventDefault();
+      event.currentTarget.setPointerCapture(event.pointerId);
+      setDragging(true);
+    },
+    [setDragging],
+  );
+
+  // Map the pointer position within the Root to the anchored panel's extent (rem), clamped so neither
+  // panel drops below `minSize`. For an `end` anchor the extent is measured from the far edge.
+  const handlePointerMove = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      if (!event.currentTarget.hasPointerCapture(event.pointerId)) {
+        return;
+      }
+      const root = rootRef.current;
+      if (!root) {
+        return;
+      }
+      const rect = root.getBoundingClientRect();
+      const rem = getRem();
+      const offset = (orientation === 'horizontal' ? event.clientX - rect.left : event.clientY - rect.top) / rem;
+      const extent = (orientation === 'horizontal' ? rect.width : rect.height) / rem;
+      const next = anchor === 'end' ? extent - offset : offset;
+      setSize(Math.min(Math.max(next, minSize), Math.max(minSize, extent - minSize)));
+    },
+    [orientation, anchor, minSize, rootRef, setSize],
+  );
+
+  const handlePointerUp = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+        event.currentTarget.releasePointerCapture(event.pointerId);
+      }
+      setDragging(false);
+    },
+    [setDragging],
+  );
+
+  // Arrow keys nudge the start panel's size (rem); Home/End jump to the bounds.
+  // Keeps the resize affordance usable without a pointer.
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      const horizontal = orientation === 'horizontal';
+      const step = event.shiftKey ? 4 : 1;
+      // Start from the current size, or the midpoint when the split is even (unsized).
+      const base = size ?? extentRem() / 2;
+      let next: number | undefined;
+      if (event.key === (horizontal ? 'ArrowRight' : 'ArrowDown')) {
+        next = base + step;
+      } else if (event.key === (horizontal ? 'ArrowLeft' : 'ArrowUp')) {
+        next = base - step;
+      } else if (event.key === 'Home') {
+        next = minSize;
+      } else if (event.key === 'End') {
+        next = extentRem() - minSize;
+      }
+      if (next === undefined) {
+        return;
+      }
+      event.preventDefault();
+      setSize(Math.min(Math.max(next, minSize), Math.max(minSize, extentRem() - minSize)));
+    },
+    [orientation, size, minSize, extentRem, setSize],
+  );
+
+  if (!resizable) {
+    return null;
+  }
+
+  return (
+    <Comp
+      {...rest}
+      ref={forwardedRef}
+      role='separator'
+      tabIndex={0}
+      aria-orientation={orientation === 'horizontal' ? 'vertical' : 'horizontal'}
+      aria-valuemin={Math.round(minSize)}
+      aria-valuenow={size !== undefined ? Math.round(size) : undefined}
+      className={tx('splitter.handle', { orientation }, className)}
+      style={handlePosition(orientation, anchor, size, minSize)}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onPointerCancel={handlePointerUp}
+      onKeyDown={handleKeyDown}
+    >
+      {children}
+    </Comp>
+  );
+});
+
+SplitterHandle.displayName = HANDLE_NAME;
+
 //
 // Splitter
 //
@@ -115,8 +387,9 @@ SplitterPanel.displayName = PANEL_NAME;
 const Splitter = {
   Root: SplitterRoot,
   Panel: SplitterPanel,
+  Handle: SplitterHandle,
 };
 
-export { Splitter, createSplitterScope };
+export { Splitter };
 
-export type { Mode as SplitterMode, SplitterRootProps, SplitterPanelProps };
+export type { SplitterHandleProps, SplitterMode, SplitterOrientation, SplitterPanelProps, SplitterRootProps };

package/src/components/Tag/Tag.stories.tsx

@@ -19,7 +19,7 @@ const meta = {
   render: () => (
     <div>
       {palettes.map((palette) => (
-        <Tag key={palette} palette={palette}>
+        <Tag key={palette} hue={palette}>
           {palette}
         </Tag>
       ))}

package/src/components/Tag/Tag.theme.ts

@@ -12,7 +12,7 @@ import {
 } from '@dxos/ui-types';
 
 export type TagStyleProps = {
-  palette?: ChromaticPalette | NeutralPalette | MessageValence;
+  hue?: ChromaticPalette | NeutralPalette | MessageValence;
 };
 
 const root: ComponentFunction<TagStyleProps> = (_, ...etc) => mx('dx-tag', ...etc);

package/src/components/Tag/Tag.tsx

@@ -12,16 +12,14 @@ import { useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';
 
 export type TagProps = ThemedClassName<ComponentPropsWithRef<typeof Primitive.span>> & {
-  palette?: NeutralPalette | ChromaticPalette | MessageValence;
   asChild?: boolean;
+  hue?: NeutralPalette | ChromaticPalette | MessageValence;
 };
 
 export const Tag = forwardRef<HTMLSpanElement, TagProps>(
-  ({ asChild, palette = 'neutral', classNames, ...props }, forwardedRef) => {
+  ({ asChild, hue = 'neutral', classNames, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
     const Comp = asChild ? Slot : Primitive.span;
-    return (
-      <Comp {...props} className={tx('tag.root', { palette }, classNames)} data-hue={palette} ref={forwardedRef} />
-    );
+    return <Comp {...props} className={tx('tag.root', { hue }, classNames)} data-hue={hue} ref={forwardedRef} />;
   },
 );

package/src/components/Toast/Toast.theme.ts

@@ -9,8 +9,9 @@ export type ToastStyleProps = {};
 
 const viewport: ComponentFunction<ToastStyleProps> = (_props, ...etc) =>
   mx(
-    // TODO(burdon): block-end should take into account status bar.
-    'z-40 fixed bottom-[calc(env(safe-area-inset-bottom)+1rem)] inset-start-[calc(env(safe-area-inset-left)+1rem)] inset-end-[calc(env(safe-area-inset-right)+1rem)] w-auto md:end-[calc(env(safe-area-inset-right)+1rem)] md:left-auto md:w-full md:max-w-sm',
+    'z-40 fixed bottom-[calc(env(safe-area-inset-bottom)+1rem)]',
+    'inset-start-[calc(env(safe-area-inset-left)+1rem)] inset-end-[calc(env(safe-area-inset-right)+1rem)]',
+    'w-auto md:end-[calc(env(safe-area-inset-right)+4rem)] md:left-auto md:w-full md:max-w-sm',
     'rounded-md flex flex-col gap-2',
     ...etc,
   );

package/src/components/Toast/Toast.tsx

@@ -162,12 +162,12 @@ export const Toast = {
 };
 
 export type {
+  ToastActionProps,
+  ToastActionsProps,
+  ToastCloseProps,
+  ToastDescriptionProps,
   ToastProviderProps,
-  ToastViewportProps,
   ToastRootProps,
   ToastTitleProps,
-  ToastDescriptionProps,
-  ToastActionsProps,
-  ToastActionProps,
-  ToastCloseProps,
+  ToastViewportProps,
 };

package/src/components/Toolbar/Toolbar.tsx

@@ -366,19 +366,19 @@ export const Toolbar = {
 };
 
 export type {
-  ToolbarRootProps,
-  ToolbarTextProps,
+  ToolbarActionIconButtonAction,
+  ToolbarActionIconButtonProps,
   ToolbarButtonProps,
+  ToolbarDragHandleProps,
   ToolbarIconButtonProps,
   ToolbarLinkProps,
-  ToolbarToggleProps,
-  ToolbarToggleGroupProps,
-  ToolbarToggleGroupItemProps,
-  ToolbarToggleGroupIconItemProps,
-  ToolbarSeparatorProps,
-  ToolbarDragHandleProps,
-  ToolbarActionIconButtonAction,
-  ToolbarActionIconButtonProps,
   ToolbarMenuItem,
   ToolbarMenuProps,
+  ToolbarRootProps,
+  ToolbarSeparatorProps,
+  ToolbarTextProps,
+  ToolbarToggleGroupIconItemProps,
+  ToolbarToggleGroupItemProps,
+  ToolbarToggleGroupProps,
+  ToolbarToggleProps,
 };

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -11,12 +11,12 @@ import { withTheme } from '../../testing';
 import { Button } from '../Button';
 import { Tooltip } from './Tooltip';
 
-type DefaultStoryProps = {
+type StoryArgs = {
   tooltips: { label: string; content: string }[];
   defaultOpen?: boolean;
 };
 
-const DefaultStory = ({ tooltips, defaultOpen }: DefaultStoryProps) => {
+const DefaultStory = ({ tooltips, defaultOpen }: StoryArgs) => {
   return (
     <Tooltip.Provider defaultOpen={defaultOpen}>
       <div className='w-32'>

package/src/components/Tooltip/Tooltip.tsx

@@ -493,12 +493,12 @@ type TooltipContentImplProps = Omit<PopperContentProps, 'onPlaced'> & {
    * Event handler called when the escape key is down.
    * Can be prevented.
    */
-  onEscapeKeyDown?: DismissableLayerProps['onEscapeKeyDown'];
+  'onEscapeKeyDown'?: DismissableLayerProps['onEscapeKeyDown'];
   /**
    * Event handler called when the a `pointerdown` event happens outside of the `Tooltip`.
    * Can be prevented.
    */
-  onPointerDownOutside?: DismissableLayerProps['onPointerDownOutside'];
+  'onPointerDownOutside'?: DismissableLayerProps['onPointerDownOutside'];
 };
 
 const TooltipContentImpl = forwardRef<TooltipContentImplElement, TooltipContentImplProps>(
@@ -765,4 +765,4 @@ export const Tooltip = {
 
 export { createTooltipScope, useTooltipContext };
 
-export type { TooltipProviderProps, TooltipTriggerProps, TooltipScopedProps, TooltipSide };
+export type { TooltipProviderProps, TooltipScopedProps, TooltipSide, TooltipTriggerProps };

package/src/components/index.ts

@@ -18,7 +18,6 @@ export * from './Icon';
 export * from './Image';
 export * from './Input';
 export * from './Link';
-export * from './List';
 export * from './Main';
 export * from './MediaPlayer';
 export * from './Menu';

package/src/exemplars/tabster.stories.tsx

@@ -4,8 +4,8 @@
 
 import {
   useArrowNavigationGroup,
-  useFocusFinders,
   useFocusableGroup,
+  useFocusFinders,
   useMergedTabsterAttributes_unstable,
 } from '@fluentui/react-tabster';
 import { type Decorator, type Meta, type StoryObj } from '@storybook/react-vite';

package/src/index.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export { type Resource, type TFunction } from 'i18next';
+export { type Resource, type TFunction } from '@dxos/i18n';
 export { Trans } from 'react-i18next';
 
 export * from '@dxos/react-hooks';

package/src/primitives/ThemeProvider/TranslationsProvider.tsx

@@ -3,31 +3,14 @@
 //
 
 import { type Locale, enUS as dtLocaleEnUs } from 'date-fns/locale';
-import i18Next, { type Resource } from 'i18next';
 import React, { type ReactNode, Suspense, createContext, useContext, useEffect, useState } from 'react';
-import { initReactI18next, useTranslation as useI18NextTranslation } from 'react-i18next';
+import { I18nextProvider, useTranslation as useI18NextTranslation } from 'react-i18next';
+
+import { type Resource, addResources, i18n } from '@dxos/i18n';
 
-const initialLng = 'en-US';
 const initialNs = 'dxos-common';
 const initialDtLocale = dtLocaleEnUs;
 
-export const resources = {
-  [initialLng]: {
-    [initialNs]: {
-      'loading translations': 'Loading translations…',
-    },
-  },
-} as const satisfies Resource;
-
-void i18Next.use(initReactI18next).init({
-  resources,
-  lng: initialLng,
-  defaultNS: initialNs,
-  interpolation: {
-    escapeValue: false,
-  },
-});
-
 export interface TranslationsProviderProps {
   children?: ReactNode;
   // TODO(wittjosiah): Rename to `placeholder` to match ClientProvider?
@@ -59,14 +42,9 @@ export const TranslationsProvider = ({
   const [loaded, setLoaded] = useState(false);
   useEffect(() => {
     setLoaded(false);
+    // Convenience for standalone/storybook callers; the i18next instance lifecycle is owned by `@dxos/i18n`.
     if (resourceExtensions && resourceExtensions.length) {
-      resourceExtensions.forEach((resource) => {
-        Object.keys(resource).forEach((language) => {
-          Object.keys(resource[language]).forEach((ns) => {
-            i18Next.addResourceBundle(language, ns, resource[language][ns]);
-          });
-        });
-      });
+      addResources(resourceExtensions);
     }
 
     setLoaded(true);
@@ -75,8 +53,10 @@ export const TranslationsProvider = ({
   // TODO(thure): This is not ideal, but i18next was causing `Suspense` to not render the fallback even when the child was asking for namespaces yet to be added.
   // TODO(burdon): Fallbacks should only appear after a short delay, and if the displayed then be visible for 500mx to avoid startup flickering.
   return (
-    <TranslationsContext.Provider value={{ appNs: appNs ?? initialNs, dtLocale: dtLocale ?? initialDtLocale }}>
-      <Suspense fallback={fallback}>{loaded ? children : fallback}</Suspense>
-    </TranslationsContext.Provider>
+    <I18nextProvider i18n={i18n}>
+      <TranslationsContext.Provider value={{ appNs: appNs ?? initialNs, dtLocale: dtLocale ?? initialDtLocale }}>
+        <Suspense fallback={fallback}>{loaded ? children : fallback}</Suspense>
+      </TranslationsContext.Provider>
+    </I18nextProvider>
   );
 };