@dxos/react-ui-chat 0.8.4-main.dedc0f3 → 0.8.4-main.dfabb4ec29

package/src/components/ChatStatus/ChatStatus.stories.tsx

@@ -0,0 +1,130 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useRef } from 'react';
+
+import { Button, Toolbar } from '@dxos/react-ui';
+import { Matrix } from '@dxos/react-ui-sfx';
+import { withTheme, withLayout } from '@dxos/react-ui/testing';
+
+import { ChatStatus, type ChatStatusController, useChatStatusContext } from './ChatStatus';
+
+const meta = {
+  title: 'ui/react-ui-chat/ChatStatus',
+  component: ChatStatus.Root,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'centered', classNames: 'py-1 px-2 border border-separator rounded-sm' }),
+  ],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof ChatStatus.Root>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <ChatStatus.Root>
+      <ChatStatus.Icon />
+      <ChatStatus.Stopwatch />
+    </ChatStatus.Root>
+  ),
+};
+
+export const WithMeta: Story = {
+  render: () => (
+    <ChatStatus.Root>
+      <ChatStatus.Icon />
+      <ChatStatus.Stopwatch />
+      <ChatStatus.Separator />
+      <ChatStatus.Text>↑ 234</ChatStatus.Text>
+      <ChatStatus.Separator />
+      <ChatStatus.Text>↓ 1.2k</ChatStatus.Text>
+    </ChatStatus.Root>
+  ),
+};
+
+/**
+ * Reads the running flag from Status context and forwards it to the Matrix as
+ * the `active` prop, so the Matrix runs its own internal interval loop only
+ * while the Status tick is running. Pausing the Status freezes the dots.
+ */
+const MatrixIcon = () => {
+  const { running } = useChatStatusContext('MatrixIcon');
+  return (
+    <Matrix
+      classNames='mr-2'
+      dim={4}
+      dotSize={3}
+      // TODO(burdon): Change with activity?
+      count={10}
+      interval={500}
+      active={running}
+    />
+  );
+};
+
+export const WithCustomIcon: Story = {
+  render: () => (
+    <ChatStatus.Root classNames='text-sm'>
+      <ChatStatus.Icon>
+        <MatrixIcon />
+      </ChatStatus.Icon>
+      <ChatStatus.Stopwatch />
+      <ChatStatus.Separator />
+      <ChatStatus.Text>↑ 234</ChatStatus.Text>
+      <ChatStatus.Separator />
+      <ChatStatus.Text>↓ 1.2k</ChatStatus.Text>
+    </ChatStatus.Root>
+  ),
+};
+
+export const LongRunning: Story = {
+  render: () => (
+    <ChatStatus.Root>
+      <ChatStatus.Icon />
+      <ChatStatus.Stopwatch offset={65 * 60} />
+      <ChatStatus.Separator />
+      <ChatStatus.Text>↑ 4.5k</ChatStatus.Text>
+      <ChatStatus.Separator />
+      <ChatStatus.Text>↓ 12.3k</ChatStatus.Text>
+    </ChatStatus.Root>
+  ),
+};
+
+export const TextOnly: Story = {
+  render: () => (
+    <ChatStatus.Root>
+      <ChatStatus.Icon />
+      <ChatStatus.Text>Connecting…</ChatStatus.Text>
+    </ChatStatus.Root>
+  ),
+};
+
+/**
+ * Demonstrates the imperative controller — start/stop the 1Hz tick from the outside.
+ */
+export const Controller: Story = {
+  render: () => {
+    const ref = useRef<ChatStatusController>(null);
+    return (
+      <div className='flex flex-col gap-4'>
+        <Toolbar.Root>
+          <Button onClick={() => ref.current?.start()}>Start</Button>
+          <Button onClick={() => ref.current?.stop()}>Stop</Button>
+        </Toolbar.Root>
+        <ChatStatus.Root ref={ref}>
+          <ChatStatus.Icon>
+            <MatrixIcon />
+          </ChatStatus.Icon>
+          <ChatStatus.Stopwatch />
+        </ChatStatus.Root>
+      </div>
+    );
+  },
+};

package/src/components/ChatStatus/ChatStatus.tsx

@@ -0,0 +1,183 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import React, { type PropsWithChildren, type Ref, forwardRef, useEffect, useImperativeHandle, useState } from 'react';
+
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { formatElapsed } from './format';
+
+const TICK_MS = 1_000;
+
+//
+// Context
+//
+
+type ChatStatusContextValue = {
+  /** Whole seconds elapsed since ChatStatus.Root mounted. Only advances while `running` is true. */
+  elapsed: number;
+  /** Whether the ChatStatus.Root tick is currently active. Toggled via the ChatStatusController. */
+  running: boolean;
+};
+
+const [ChatStatusProvider, useChatStatusContext] = createContext<ChatStatusContextValue>('ChatStatus');
+
+export { useChatStatusContext };
+
+//
+// Controller
+//
+
+export type ChatStatusController = {
+  /** Resume the tick. No-op if already running. */
+  start: () => void;
+  /** Pause the tick. The reported `elapsed` freezes at its last value. */
+  stop: () => void;
+};
+
+//
+// Root
+//
+
+export type RootProps = ThemedClassName<
+  PropsWithChildren<{
+    /** Whether the tick starts running on mount. Defaults to `true`. */
+    defaultRunning?: boolean;
+  }>
+>;
+
+const Root = forwardRef<ChatStatusController, RootProps>(
+  ({ classNames, children, defaultRunning = true }: RootProps, forwardedRef: Ref<ChatStatusController>) => {
+    const [elapsed, setElapsed] = useState(0);
+    const [running, setRunning] = useState(defaultRunning);
+
+    useEffect(() => {
+      if (!running) {
+        return;
+      }
+
+      // Anchor to a wall-clock timestamp so `elapsed` self-corrects after
+      // tab-throttling: browsers clamp setTimeout to >=1s in inactive tabs
+      // and >=1min when the page is hidden, so a count-the-ticks approach
+      // would under-report after a background period. Computing elapsed from
+      // (Date.now() - startedAt) restores the true wall-clock value on the
+      // next fired tick. The initial elapsed (preserved across stop/start)
+      // is folded into the anchor so paused intervals are excluded.
+      const startedAt = Date.now() - elapsed * TICK_MS;
+      let timeout: ReturnType<typeof setTimeout>;
+      const tick = () => {
+        setElapsed(Math.floor((Date.now() - startedAt) / TICK_MS));
+        timeout = setTimeout(tick, TICK_MS - (Date.now() % TICK_MS));
+      };
+      timeout = setTimeout(tick, TICK_MS - (Date.now() % TICK_MS));
+      return () => clearTimeout(timeout);
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- `elapsed` is
+      // captured once at resume; depending on it would restart the timer on
+      // every tick.
+    }, [running]);
+
+    useImperativeHandle(
+      forwardedRef,
+      () => ({
+        start: () => setRunning(true),
+        stop: () => setRunning(false),
+      }),
+      [],
+    );
+
+    return (
+      <ChatStatusProvider elapsed={elapsed} running={running}>
+        <span className={mx('inline-flex items-center gap-2 text-description font-mono tabular-nums', classNames)}>
+          {children}
+        </span>
+      </ChatStatusProvider>
+    );
+  },
+);
+
+Root.displayName = 'ChatChatStatus.Root';
+
+//
+// Icon
+//
+
+export type IconProps = ThemedClassName<PropsWithChildren>;
+
+/**
+ * Animated leading indicator. Defaults to a halo-pulse dot. Pass children to override.
+ */
+const Icon = ({ classNames, children }: IconProps) => {
+  if (children !== undefined) {
+    return <>{children}</>;
+  }
+  return (
+    <span
+      aria-hidden='true'
+      className={mx('inline-block size-2 rounded-full bg-current animate-halo-pulse', classNames)}
+    />
+  );
+};
+
+//
+// Stopwatch
+//
+
+export type StopwatchProps = ThemedClassName<{
+  /** Seconds to add to the context elapsed value before formatting. Defaults to 0. */
+  offset?: number;
+}>;
+
+/**
+ * Elapsed-time display, driven by the ChatStatus.Root context tick.
+ * Use `offset` to shift the displayed value; remount `ChatStatus.Root` to reset the underlying counter.
+ * Marked `aria-live='off'` so screen readers don't announce every tick.
+ */
+const Stopwatch = ({ classNames, offset = 0 }: StopwatchProps) => {
+  const { elapsed } = useChatStatusContext('ChatChatStatus.Stopwatch');
+  return (
+    <span aria-live='off' className={mx(classNames)}>
+      {formatElapsed((elapsed + offset) * 1_000)}
+    </span>
+  );
+};
+
+//
+// Separator
+//
+
+export type SeparatorProps = ThemedClassName<unknown>;
+
+/**
+ * Middle-dot separator. Decorative — `aria-hidden`.
+ */
+const Separator = ({ classNames }: SeparatorProps) => (
+  <span aria-hidden='true' className={mx('opacity-50', classNames)}>
+    ·
+  </span>
+);
+
+//
+// Text
+//
+
+export type TextProps = ThemedClassName<PropsWithChildren>;
+
+/**
+ * Generic text node — useful for token counts and other inline metadata.
+ */
+const Text = ({ classNames, children }: TextProps) => <span className={mx(classNames)}>{children}</span>;
+
+//
+// ChatStatus
+//
+
+export const ChatStatus = {
+  Root,
+  Icon,
+  Stopwatch,
+  Separator,
+  Text,
+};

package/src/components/ChatStatus/format.test.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { formatElapsed } from './format';
+
+describe('formatElapsed', () => {
+  test('zero returns 0s', ({ expect }) => {
+    expect(formatElapsed(0)).toBe('0s');
+  });
+
+  test('negative inputs clamp to 0s', ({ expect }) => {
+    expect(formatElapsed(-1_000)).toBe('0s');
+    expect(formatElapsed(-Infinity)).toBe('0s');
+  });
+
+  test('seconds tier under one minute', ({ expect }) => {
+    expect(formatElapsed(999)).toBe('0s');
+    expect(formatElapsed(1_000)).toBe('1s');
+    expect(formatElapsed(12_400)).toBe('12s');
+    expect(formatElapsed(59_999)).toBe('59s');
+  });
+
+  test('boundary at one minute', ({ expect }) => {
+    expect(formatElapsed(60_000)).toBe('1m 0s');
+    expect(formatElapsed(60_999)).toBe('1m 0s');
+    expect(formatElapsed(61_000)).toBe('1m 1s');
+  });
+
+  test('minutes tier under one hour', ({ expect }) => {
+    expect(formatElapsed(92_000)).toBe('1m 32s');
+    expect(formatElapsed(3_540_000)).toBe('59m 0s');
+    expect(formatElapsed(3_599_999)).toBe('59m 59s');
+  });
+
+  test('boundary at one hour', ({ expect }) => {
+    expect(formatElapsed(3_600_000)).toBe('1h 0m');
+    expect(formatElapsed(3_660_000)).toBe('1h 1m');
+  });
+
+  test('hours tier drops smaller units', ({ expect }) => {
+    expect(formatElapsed(3_720_000)).toBe('1h 2m');
+    expect(formatElapsed(7_323_000)).toBe('2h 2m');
+    expect(formatElapsed(36_000_000)).toBe('10h 0m');
+  });
+});

package/src/components/ChatStatus/format.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+const SECOND = 1_000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+
+/**
+ * Formats elapsed milliseconds as a human-readable duration.
+ * Tiers: `Ns` (< 60s), `Nm Xs` (< 60m), `Nh Xm` (≥ 60m).
+ * Negative inputs clamp to `0s`.
+ */
+export const formatElapsed = (ms: number): string => {
+  const safe = Math.max(0, ms);
+  if (safe < MINUTE) {
+    return `${Math.floor(safe / SECOND)}s`;
+  }
+  if (safe < HOUR) {
+    const m = Math.floor(safe / MINUTE);
+    const s = Math.floor((safe % MINUTE) / SECOND);
+    return `${m}m ${s}s`;
+  }
+  const h = Math.floor(safe / HOUR);
+  const m = Math.floor((safe % HOUR) / MINUTE);
+  return `${h}h ${m}m`;
+};

package/src/components/ChatStatus/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './ChatStatus';
+export * from './format';

package/src/components/index.ts

@@ -4,3 +4,4 @@
 
 export * from './ChatDialog';
 export * from './ChatEditor';
+export * from './ChatStatus';

package/src/index.ts

@@ -3,4 +3,3 @@
 //
 
 export * from './components';
-export * from './translations';

package/src/translations.ts

@@ -4,7 +4,7 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-export const translationKey = 'react-ui-chat';
+export const translationKey = '@dxos/react-ui-chat';
 
 export const translations = [
   {