@dxos/react-ui-trace 0.11.1

package/src/components/ProcessTree/ProcessTree.tsx

@@ -0,0 +1,265 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RegistryContext } from '@effect/atom-react/RegistryContext';
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import React, { useCallback, useContext, useMemo, useRef } from 'react';
+
+import * as Process from '@dxos/compute/Process';
+import { Icon, IconButton, ScrollArea, Tooltip, composable, composableProps } from '@dxos/react-ui';
+import { type ColumnRenderer, type IconRenderer, Tree, createStaticTreeModel } from '@dxos/react-ui-list';
+import { mx } from '@dxos/ui-theme';
+import { Unit } from '@dxos/util';
+
+const DEFAULT_DEPTH = 1;
+/** Nested subprocess rows (level > 1) only surface still-active processes. */
+const NESTED_ACTIVE_STATES = new Set<Process.State>([
+  Process.State.RUNNING,
+  Process.State.HYBERNATING,
+  Process.State.TERMINATING,
+]);
+
+export type ProcessTreeProps = {
+  // TODO(burdon): Atom.
+  processes: readonly Process.Info[];
+  /**
+   * Maximum nesting depth from the root (1 = top-level processes only).
+   *
+   * @default 1
+   */
+  depth?: number;
+  /**
+   * Overrides the row label for a process (e.g. the name of the chat it is serving), falling back to
+   * the process name when it returns `undefined`.
+   *
+   * Must be referentially stable — `ProcessTree` is memoized on its props.
+   */
+  resolveLabel?: (process: Process.Info) => string | undefined;
+  /** Pids drawn as selected; the tree is controlled, so a click reports through `onSelectedChange`. */
+  selected?: readonly string[];
+  /** The selection after a click: the clicked pid alone, or toggled among the others on a meta-click. */
+  onSelectedChange?: (selected: string[]) => void;
+  onProcessTerminate?: (process: Process.Info) => void;
+};
+
+/** Node of the pruned process forest handed to the tree model. */
+type ProcessNode = {
+  id: string;
+  /** Absent on the synthetic root, which anchors the top-level processes and is never rendered. */
+  process?: Process.Info;
+  children: ProcessNode[];
+};
+
+/** Synthetic root; the tree renders its children, never the root itself. */
+const ROOT_ID = 'processes';
+
+const NO_SELECTION: readonly string[] = [];
+
+/**
+ * The agent's running processes as a tree, one row per process with its status glyph and metrics
+ * in trailing columns. The forest is rebuilt on every metrics tick, so open state lives outside the
+ * model and is re-seeded — a collapse must survive the next tick. Renders through `Tree`.
+ */
+export const ProcessTree = React.memo(
+  composable<HTMLDivElement, ProcessTreeProps>(
+    (
+      {
+        processes,
+        depth = DEFAULT_DEPTH,
+        resolveLabel,
+        selected = NO_SELECTION,
+        onSelectedChange,
+        onProcessTerminate,
+        ...props
+      },
+      forwardedRef,
+    ) => {
+      // Open state lives outside the model: `processes` carries live metrics, so the forest (and with
+      // it the model) is rebuilt on every tick, and a collapse held only inside the model would be
+      // undone by the next one.
+      const openRef = useRef(new Map<string, boolean>());
+      const registry = useContext(RegistryContext);
+      const root = useMemo(() => buildProcessForest(processes, depth), [processes, depth]);
+
+      const model = useMemo(
+        () =>
+          createStaticTreeModel<ProcessNode>(root, {
+            getChildren: (node) => node.children,
+            getProps: (node) => ({
+              label: (node.process && resolveLabel?.(node.process)) ?? node.process?.params.name ?? node.id,
+            }),
+            // Expanded by default, matching the flattened view this replaced.
+            isOpen: (_node, path) => openRef.current.get(path.join('/')) ?? true,
+            isCurrent: (node) => node.process !== undefined && selected.includes(node.process.pid),
+          }),
+        [root, resolveLabel, selected],
+      );
+
+      // The ref survives model rebuilds; the atom is what the controlled tree actually reads, so a
+      // toggle has to land in both.
+      const handleOpenChange = useCallback(
+        ({ path, open }: { path: string[]; open: boolean }) => {
+          openRef.current.set(path.join('/'), open);
+          const atom = model.stateAtom(path);
+          registry.set(atom, { ...registry.get(atom), open });
+        },
+        [model, registry],
+      );
+
+      const handleSelect = useCallback(
+        ({ item, current, meta }: { item: ProcessNode; current: boolean; meta: boolean }) => {
+          if (!item.process) {
+            return;
+          }
+          const pid = item.process.pid.toString();
+          onSelectedChange?.(
+            !meta ? [pid] : current ? [...selected, pid] : selected.filter((candidate) => candidate !== pid),
+          );
+        },
+        [selected, onSelectedChange],
+      );
+
+      const renderIcon = useMemo(() => makeIconRenderer(), []);
+      const renderColumns = useMemo(() => makeColumnRenderer(onProcessTerminate), [onProcessTerminate]);
+
+      return (
+        <ScrollArea.Root {...composableProps(props)} thin ref={forwardedRef}>
+          <ScrollArea.Viewport>
+            <Tree<ProcessNode>
+              id={ROOT_ID}
+              model={model}
+              density='sm'
+              selectionMode='multiple'
+              classNames='text-sm tabular-nums font-thin'
+              gridTemplateColumns='[tree-row-start] var(--dx-control) minmax(0, 1fr) min-content min-content [tree-row-end]'
+              renderIcon={renderIcon}
+              renderColumns={renderColumns}
+              onOpenChange={handleOpenChange}
+              onSelect={handleSelect}
+            />
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      );
+    },
+  ),
+);
+
+/** Status glyph — animated, coloured and tooltipped per state, which `TreeItemDataProps.icon` cannot express. */
+const makeIconRenderer =
+  (): IconRenderer<ProcessNode> =>
+  ({ item: { process } }) =>
+    process === undefined ? null : (
+      <Tooltip.Trigger content={process.state.toString()}>
+        <Icon
+          size={4}
+          synchronized
+          classNames={mx(
+            'shrink-0',
+            process.state === Process.State.RUNNING && 'animate-spin',
+            process.state === Process.State.FAILED && 'text-error-text',
+            process.state === Process.State.SUCCEEDED && 'text-success-text',
+          )}
+          icon={Match.value(process.state).pipe(
+            Match.when(Process.State.RUNNING, () => 'ph--spinner-gap--regular'),
+            Match.when(Process.State.SUCCEEDED, () => 'ph--check-circle--regular'),
+            Match.when(Process.State.FAILED, () => 'ph--warning--regular'),
+            Match.when(Process.State.HYBERNATING, () => 'ph--spinner--regular'),
+            Match.when(Process.State.IDLE, () => 'ph--moon-stars--regular'),
+            Match.when(Process.State.TERMINATING, () => 'ph--x-circle--regular'),
+            Match.when(Process.State.TERMINATED, () => 'ph--x-circle--regular'),
+            Match.orElse(() => 'ph--spinner-gap--regular'),
+          )}
+        />
+      </Tooltip.Trigger>
+    );
+
+/** Trailing columns: elapsed time for finished processes, and the terminate control. */
+const makeColumnRenderer =
+  (onProcessTerminate?: (process: Process.Info) => void): ColumnRenderer<ProcessNode> =>
+  ({ item: { process } }) =>
+    process === undefined ? null : (
+      <>
+        <div className='flex items-center justify-end text-xs text-description tabular-nums'>
+          {[Process.State.FAILED, Process.State.SUCCEEDED].includes(process.state) && (
+            <span className='whitespace-nowrap'>{Unit.Duration(process.metrics.wallTime).toString()}</span>
+          )}
+        </div>
+        <div className='flex items-center'>
+          {onProcessTerminate && (
+            <IconButton
+              classNames='min-h-0 p-1'
+              icon='ph--x--regular'
+              iconOnly
+              density='sm'
+              variant='ghost'
+              label='Actions'
+              onClick={(event) => {
+                event.stopPropagation();
+                onProcessTerminate(process);
+              }}
+            />
+          )}
+        </div>
+      </>
+    );
+
+const sortProcesses = (processes: readonly Process.Info[]): Process.Info[] => {
+  return [
+    ...processes.filter((process) => [Process.State.RUNNING, Process.State.HYBERNATING].includes(process.state)),
+    ...processes.filter((process) => [Process.State.IDLE].includes(process.state)).slice(0, 3),
+    ...processes.filter((process) =>
+      [Process.State.SUCCEEDED, Process.State.FAILED, Process.State.TERMINATED].includes(process.state),
+    ),
+  ].sort((left, right) => {
+    const leftCompletedAt = Option.getOrElse(left.completedAt, () => Infinity);
+    const rightCompletedAt = Option.getOrElse(right.completedAt, () => Infinity);
+    return rightCompletedAt - leftCompletedAt;
+  });
+};
+
+const sortNestedActive = (processes: readonly Process.Info[]): Process.Info[] =>
+  processes
+    .filter((process) => NESTED_ACTIVE_STATES.has(process.state))
+    .sort((left, right) => {
+      const priority = (state: Process.State) =>
+        state === Process.State.RUNNING ? 0 : state === Process.State.HYBERNATING ? 1 : 2;
+      return priority(left.state) - priority(right.state);
+    });
+
+/**
+ * Builds the process forest, pruned to `maxDepth` from each root. Nested levels surface only still-
+ * active processes, so a deep tree stays readable while completed work collapses out of view.
+ */
+const buildProcessForest = (processes: readonly Process.Info[], maxDepth: number): ProcessNode => {
+  const pidSet = new Set(processes.map((process) => String(process.pid)));
+  const childrenByParent = new Map<string, Process.Info[]>();
+  const roots: Process.Info[] = [];
+
+  for (const process of processes) {
+    const parent = process.parentPid;
+    if (parent === null || !pidSet.has(String(parent))) {
+      roots.push(process);
+      continue;
+    }
+    const key = String(parent);
+    const siblings = childrenByParent.get(key) ?? [];
+    siblings.push(process);
+    childrenByParent.set(key, siblings);
+  }
+
+  const visit = (process: Process.Info, level: number): ProcessNode => {
+    const children = level >= maxDepth ? [] : sortNestedActive(childrenByParent.get(String(process.pid)) ?? []);
+    return {
+      id: String(process.pid),
+      process,
+      children: children.map((child) => visit(child, level + 1)),
+    };
+  };
+
+  return {
+    id: ROOT_ID,
+    children: sortProcesses(roots).map((process) => visit(process, 1)),
+  };
+};

package/src/components/ProcessTree/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { ProcessTree, type ProcessTreeProps } from './ProcessTree.tsx';

package/src/components/Timeline/Timeline.stories.tsx

@@ -0,0 +1,326 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useRef, useState } from 'react';
+
+import { LogLevel } from '@dxos/log';
+import { random } from '@dxos/random';
+import { Button, Panel, ScrollArea, ScrollContainer, Toolbar, useInterval } from '@dxos/react-ui';
+import { type ScrollController } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { type Commit, Timeline, TimelineProps } from './Timeline.tsx';
+
+random.seed(1);
+
+enum IconType {
+  // General status.
+  WARN = 'ph--warning-circle--regular',
+  CHECK = 'ph--check-circle--regular',
+  ROCKET = 'ph--rocket--regular',
+  X = 'ph--x-circle--regular',
+  FLAG = 'ph--flag--regular',
+  TIMER = 'ph--timer--regular',
+
+  // Interactions.
+  USER = 'ph--user--regular',
+  USER_INTERACTION = 'ph--user-sound--regular',
+  AGENT = 'ph--drone--regular',
+  THINK = 'ph--brain--regular',
+  LINK = 'ph--link--regular',
+  TOOL = 'ph--wrench--regular',
+}
+
+const generateCommit = (
+  commits: Commit[],
+  branches: string[],
+  lastBranch: string,
+  lastCommit: string | undefined,
+  closedBranches: Set<string>,
+): {
+  commit: Commit | undefined;
+  branch: string | undefined;
+} => {
+  let commit: Commit | undefined = undefined;
+  let branch: string | undefined = undefined;
+
+  const p = Math.random();
+  if (commits.length > 3) {
+    if (p < 0.2 && branches.length < 6) {
+      // New branch.
+      branch = random.lorem.word();
+      lastBranch = branch;
+    } else if (p < 0.4) {
+      // Switch branch.
+      const branch = branches[Math.floor(Math.random() * branches.length)];
+      if (!closedBranches.has(branch)) {
+        lastBranch = branch;
+      }
+    } else if (p < 0.5 && branches.length > 3 && lastCommit && lastBranch !== branches[0]) {
+      // Merge branch.
+      closedBranches.add(lastBranch);
+      const lastBranchCommit = commits.findLast((c) => c.branch === lastBranch);
+      lastBranch = branches[0];
+      if (lastBranchCommit) {
+        commit = {
+          id: random.string.uuid(),
+          branch: lastBranch,
+          icon: IconType.TIMER,
+          level: LogLevel.INFO,
+          message: 'Merge',
+          parents: [lastBranchCommit.id, lastCommit],
+        };
+      }
+    }
+  }
+
+  if (!commit) {
+    commit = {
+      id: random.string.uuid(),
+      timestamp: new Date(),
+      branch: lastBranch,
+      icon: random.helpers.arrayElement([
+        IconType.WARN,
+        IconType.CHECK,
+        IconType.ROCKET,
+        IconType.X,
+        IconType.FLAG,
+        IconType.TIMER,
+        IconType.USER,
+        IconType.USER_INTERACTION,
+        IconType.AGENT,
+      ]),
+      level: random.helpers.arrayElement([
+        LogLevel.TRACE,
+        LogLevel.DEBUG,
+        LogLevel.VERBOSE,
+        LogLevel.INFO,
+        LogLevel.WARN,
+        LogLevel.ERROR,
+      ]),
+      message: random.lorem.paragraph(),
+      parents: lastCommit ? [lastCommit] : [],
+    };
+  }
+
+  return { commit, branch };
+};
+
+const generateCommits = (n: number): Pick<TimelineProps, 'commits' | 'branches'> => {
+  const commits = [];
+  const branches = ['main'];
+  let lastBranch = branches[0];
+  let lastCommit: string | undefined;
+  const closedBranches = new Set<string>();
+
+  for (let i = 0; i < n; i++) {
+    const { commit, branch } = generateCommit(commits, branches, lastBranch, lastCommit, closedBranches);
+    if (commit) {
+      commits.push(commit);
+      lastCommit = commit.id;
+    }
+    if (branch) {
+      branches.push(branch);
+      lastBranch = branch;
+    }
+  }
+
+  return { commits, branches };
+};
+
+const DefaultStory = (props: TimelineProps) => {
+  return (
+    <ScrollArea.Root>
+      <ScrollArea.Viewport>
+        <Timeline {...props} />
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-components/Timeline',
+  component: Timeline,
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+} satisfies Meta<typeof Timeline>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    debug: true,
+    showIcon: false,
+    commits: [
+      { id: 'c1', message: random.lorem.paragraph(), branch: 'main' },
+      { id: 'c2', message: random.lorem.paragraph(), branch: 'main', parents: ['c1'] },
+      { id: 'c3', message: random.lorem.paragraph(), branch: 'feature-a', parents: ['c2'] },
+      { id: 'c4', message: random.lorem.paragraph(), branch: 'main', parents: ['c2'] },
+      { id: 'c5', message: random.lorem.paragraph(), branch: 'feature-b', parents: ['c2'] },
+      { id: 'c6', message: random.lorem.paragraph(), branch: 'feature-a', parents: ['c3'] },
+      { id: 'c7', message: random.lorem.paragraph(), branch: 'feature-a', parents: ['c6'] },
+      { id: 'c8', message: random.lorem.paragraph(), branch: 'feature-c', parents: ['c6'] },
+      { id: 'c9', message: random.lorem.paragraph(), branch: 'main', parents: ['c4'] },
+    ],
+  },
+};
+
+export const Branch: Story = {
+  args: {
+    debug: true,
+    showIcon: false,
+    commits: [
+      { id: 'c1', message: random.lorem.paragraph(), branch: 'main' },
+      { id: 'c2', message: random.lorem.paragraph(), branch: 'main', parents: ['c1'] },
+      { id: 'c3', message: random.lorem.paragraph(), branch: 'feature-a', parents: ['c2'] },
+    ],
+  },
+};
+
+export const Timestamp: Story = {
+  args: {
+    debug: true,
+    showIcon: false,
+    showTimestamp: true,
+    commits: [
+      {
+        id: 'c1',
+        timestamp: new Date(Date.now()),
+        message: random.lorem.paragraph(),
+        branch: 'main',
+      },
+      {
+        id: 'c2',
+        timestamp: new Date(Date.now() + 100),
+        message: random.lorem.paragraph(),
+        branch: 'main',
+        parents: ['c1'],
+      },
+      {
+        id: 'c3',
+        timestamp: new Date(Date.now() + 120),
+        message: random.lorem.paragraph(),
+        branch: 'feature-a',
+        parents: ['c2'],
+      },
+    ],
+  },
+};
+
+export const Merge: Story = {
+  args: {
+    debug: true,
+    showIcon: false,
+    branches: ['main', 'feature-a', 'feature-b'],
+    commits: [
+      { id: 'c1', message: random.lorem.paragraph(), branch: 'main' },
+      { id: 'c2', message: random.lorem.paragraph(), branch: 'main', parents: ['c1'] },
+      { id: 'c3', message: random.lorem.paragraph(), branch: 'feature-a', parents: ['c2'] },
+      { id: 'c4', message: random.lorem.paragraph(), branch: 'feature-a', parents: ['c3'] },
+      { id: 'c5', message: random.lorem.paragraph(), branch: 'feature-b', parents: ['c3'] },
+      { id: 'c6', message: random.lorem.paragraph(), branch: 'main', parents: ['c2'] },
+      { id: 'c7', message: random.lorem.paragraph(), branch: 'main', parents: ['c6', 'c4', 'c5'] },
+    ],
+  },
+};
+
+export const Linear: Story = {
+  args: {
+    branches: ['main'],
+    commits: [
+      { id: 'c1', message: random.lorem.paragraph(), branch: 'main' },
+      { id: 'c2', message: random.lorem.paragraph(), branch: 'main', parents: ['c1'] },
+      { id: 'c3', message: random.lorem.paragraph(), branch: 'main', parents: ['c2'] },
+      { id: 'c4', message: random.lorem.paragraph(), branch: 'main', parents: ['c3'] },
+    ],
+  },
+};
+
+export const Empty: Story = {};
+
+export const Random: Story = {
+  args: generateCommits(100),
+};
+
+export const Compact: Story = {
+  args: { ...generateCommits(100), compact: true },
+};
+
+export const Streaming: Story = {
+  render: () => {
+    const [branches, setBranches] = useState<string[]>(['main']);
+    const [commits, setCommits] = useState<Commit[]>([
+      {
+        id: random.string.uuid(),
+        branch: branches[0],
+        message: random.lorem.paragraph(),
+      },
+    ]);
+    const lastCommit = useRef<string | undefined>(commits[0].id);
+    const lastBranch = useRef<string>(branches[0]);
+    const closedBranches = useRef<Set<string>>(new Set());
+
+    const [running, setRunning] = useState(true);
+    useInterval(
+      () => {
+        if (!running) {
+          return;
+        }
+
+        const { commit, branch } = generateCommit(
+          commits,
+          branches,
+          lastBranch.current,
+          lastCommit.current,
+          closedBranches.current,
+        );
+        if (!commit) {
+          return;
+        }
+
+        lastBranch.current = commit.branch;
+        if (branch) {
+          setBranches((branches) => [...branches, branch]);
+        }
+
+        lastCommit.current = commit.id;
+        setCommits((commits) => [...commits, commit]);
+      },
+      1_000,
+      [running],
+    );
+
+    const scrollerRef = useRef<ScrollController>(null);
+
+    return (
+      <Panel.Root>
+        <Panel.Toolbar asChild>
+          <Toolbar.Root>
+            <Button onClick={() => setRunning(true)}>Start</Button>
+            <Button onClick={() => setRunning(false)}>Stop</Button>
+            <Button onClick={() => scrollerRef.current?.scrollToTop()}>Top</Button>
+            <Button onClick={() => scrollerRef.current?.scrollToBottom()}>Bottom</Button>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+        <Panel.Content asChild>
+          <ScrollContainer.Root pin ref={scrollerRef}>
+            <ScrollContainer.Content thin>
+              <ScrollContainer.Viewport>
+                <Timeline branches={branches} commits={commits} showTimestamp />
+              </ScrollContainer.Viewport>
+              <ScrollContainer.ScrollDownButton />
+            </ScrollContainer.Content>
+          </ScrollContainer.Root>
+        </Panel.Content>
+      </Panel.Root>
+    );
+  },
+};
+
+//
+// Test data
+//