@dxos/react-ui-trace 0.11.1 → 0.14.0

package/src/components/Gantt/gantt-rows.test.ts

@@ -0,0 +1,123 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { orderRows } from './gantt-rows.ts';
+import { type GanttGroup, type GanttLane } from './Gantt.tsx';
+
+const lane = (id: string, rest: Partial<GanttLane> = {}): GanttLane => ({
+  id,
+  label: id,
+  status: 'done',
+  ...rest,
+});
+
+/** `<row index>: <indent><lane id> [band]`, which is the shape a reader checks against the drawing. */
+const format = ({ rows, bands }: ReturnType<typeof orderRows>): string =>
+  [
+    ...rows.map(({ lane, depth, index }) => `${index}: ${'  '.repeat(depth)}${lane.id}`),
+    ...bands.map(({ group, first, last }) => `band ${group.id}: ${first}..${last}`),
+  ].join('\n');
+
+describe('orderRows', () => {
+  test('a band holds its lanes in the order given', ({ expect }) => {
+    const groups: GanttGroup[] = [{ id: 'g' }];
+    const lanes = [lane('a', { groupId: 'g' }), lane('b', { groupId: 'g' }), lane('c', { groupId: 'g' })];
+    expect(`\n${format(orderRows(groups, lanes))}\n`).toMatchInlineSnapshot(`
+      "
+      0: a
+      1: b
+      2: c
+      band g: 0..2
+      "
+    `);
+  });
+
+  test('a lane nests under its parent, which indents it and the lanes under it', ({ expect }) => {
+    const groups: GanttGroup[] = [{ id: 'g' }];
+    const lanes = [
+      lane('root', { groupId: 'g' }),
+      lane('child', { groupId: 'g', parentId: 'root' }),
+      lane('grandchild', { groupId: 'g', parentId: 'child' }),
+      lane('sibling', { groupId: 'g' }),
+    ];
+    expect(`\n${format(orderRows(groups, lanes))}\n`).toMatchInlineSnapshot(`
+      "
+      0: root
+      1:   child
+      2:     grandchild
+      3: sibling
+      band g: 0..3
+      "
+    `);
+  });
+
+  test("a nested group's band follows its parent's, indented", ({ expect }) => {
+    const groups: GanttGroup[] = [{ id: 'one' }, { id: 'one:a', parentId: 'one' }, { id: 'two' }];
+    const lanes = [
+      lane('p1', { groupId: 'one' }),
+      lane('p1:task', { groupId: 'one' }),
+      lane('p2', { groupId: 'one:a' }),
+      lane('p4', { groupId: 'two' }),
+    ];
+    expect(`\n${format(orderRows(groups, lanes))}\n`).toMatchInlineSnapshot(`
+      "
+      0: p1
+      1: p1:task
+      2:   p2
+      3: p4
+      band one: 0..1
+      band one:a: 2..2
+      band two: 3..3
+      "
+    `);
+  });
+
+  test('every band is a contiguous run of rows that all belong to it', ({ expect }) => {
+    // The invariant the rectangles rest on: one rect can only enclose adjacent rows, so a band's
+    // range must hold its own lanes and nobody else's — however the caller interleaved the input.
+    const groups: GanttGroup[] = [{ id: 'one' }, { id: 'one:a', parentId: 'one' }, { id: 'two' }];
+    const lanes = [
+      lane('from-two', { groupId: 'two' }),
+      lane('from-one', { groupId: 'one' }),
+      lane('from-nested', { groupId: 'one:a' }),
+      lane('from-one-again', { groupId: 'one' }),
+    ];
+    const { rows, bands } = orderRows(groups, lanes);
+    for (const { group, first, last } of bands) {
+      expect(rows.slice(first, last + 1).map((row) => row.groupId)).toEqual(
+        rows.slice(first, last + 1).map(() => group.id),
+      );
+    }
+    expect(bands.map(({ group, first, last }) => `${group.id}:${first}..${last}`)).toEqual([
+      'one:0..1',
+      'one:a:2..2',
+      'two:3..3',
+    ]);
+  });
+
+  test('an ungrouped lane comes first and belongs to no band', ({ expect }) => {
+    const groups: GanttGroup[] = [{ id: 'g' }];
+    const lanes = [lane('grouped', { groupId: 'g' }), lane('loose')];
+    const { rows, bands } = orderRows(groups, lanes);
+    expect(rows.map((row) => row.lane.id)).toEqual(['loose', 'grouped']);
+    expect(bands).toEqual([{ group: { id: 'g' }, first: 1, last: 1 }]);
+  });
+
+  test('a group with no lanes gets no band, so nothing draws an empty rectangle', ({ expect }) => {
+    const { rows, bands } = orderRows([{ id: 'empty' }, { id: 'g' }], [lane('a', { groupId: 'g' })]);
+    expect(rows).toHaveLength(1);
+    expect(bands.map(({ group }) => group.id)).toEqual(['g']);
+  });
+
+  test('a lane whose parent sits in another group is dropped rather than misplaced', ({ expect }) => {
+    // Nesting is within a band by definition; drawing such a lane anyway would put it inside a
+    // rectangle that does not own it and break the contiguity the bands promise.
+    const groups: GanttGroup[] = [{ id: 'one' }, { id: 'two' }];
+    const lanes = [lane('a', { groupId: 'one' }), lane('b', { groupId: 'two', parentId: 'a' })];
+    const { rows } = orderRows(groups, lanes);
+    expect(rows.map((row) => row.lane.id)).toEqual(['a']);
+  });
+});

package/src/components/Gantt/gantt-rows.ts

@@ -0,0 +1,71 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Kept out of `Gantt.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a layout function exported beside them forces a full reload on every edit.
+
+import { type GanttGroup, type GanttLane } from './Gantt.tsx';
+
+export type Row = {
+  lane: GanttLane;
+  depth: number;
+  index: number;
+  groupId: string | undefined;
+};
+
+/** A group's rows, contiguous — which is what lets one rectangle enclose them. */
+export type Band = {
+  group: GanttGroup;
+  first: number;
+  last: number;
+};
+
+/**
+ * Rows in reading order: the ungrouped lanes, then each group's band, a nested group's band directly
+ * after its parent's. Within a band the lanes come in the order given, each nested under its
+ * `parentId`.
+ *
+ * A band is contiguous by construction, which is the whole reason the order is settled here rather
+ * than left to the caller: one rectangle can only enclose a run of adjacent rows.
+ */
+export const orderRows = (
+  groups: readonly GanttGroup[],
+  lanes: readonly GanttLane[],
+): { rows: Row[]; bands: Band[] } => {
+  const rows: Row[] = [];
+  const bands: Band[] = [];
+
+  /** A group's lanes, nested under one another by `parentId`; a parent in another group is ignored. */
+  const pushLanes = (members: readonly GanttLane[], parentId: string | undefined, depth: number): void => {
+    for (const lane of members.filter((member) => member.parentId === parentId)) {
+      rows.push({ lane, depth, index: rows.length, groupId: lane.groupId });
+      pushLanes(members, lane.id, depth + 1);
+    }
+  };
+
+  const visitGroup = (group: GanttGroup, depth: number): void => {
+    const first = rows.length;
+    pushLanes(
+      lanes.filter((lane) => lane.groupId === group.id),
+      undefined,
+      depth,
+    );
+    if (rows.length > first) {
+      bands.push({ group, first, last: rows.length - 1 });
+    }
+    for (const child of groups.filter((candidate) => candidate.parentId === group.id)) {
+      visitGroup(child, depth + 1);
+    }
+  };
+
+  pushLanes(
+    lanes.filter((lane) => lane.groupId === undefined),
+    undefined,
+    0,
+  );
+  for (const group of groups.filter((group) => group.parentId === undefined)) {
+    visitGroup(group, 0);
+  }
+  return { rows, bands };
+};

package/src/components/Gantt/gantt-scale.test.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { timeScale, unitScale } from './gantt-scale.ts';
+
+const PAD = 10;
+const STEP = 20;
+
+describe('timeScale', () => {
+  test('maps the range onto the padded width', ({ expect }) => {
+    const scale = timeScale({ range: { start: 100, end: 200 }, width: 220, pad: PAD });
+    expect(scale.at(100)).toBe(PAD);
+    expect(scale.at(200)).toBe(210);
+    expect(scale.at(150)).toBe(110);
+    expect(scale.width).toBe(220);
+  });
+
+  test('labels ticks with elapsed time at round intervals', ({ expect }) => {
+    const labels = (end: number) =>
+      timeScale({ range: { start: 1_000_000, end: 1_000_000 + end }, width: 600, pad: PAD }).ticks.map(
+        ({ label }) => label,
+      );
+    expect(labels(40_000)).toEqual(['0s', '5s', '10s', '15s', '20s', '25s', '30s', '35s', '40s']);
+    expect(labels(800)).toEqual(['0.0s', '0.1s', '0.2s', '0.3s', '0.4s', '0.5s', '0.6s', '0.7s', '0.8s']);
+    expect(labels(150_000)).toEqual(['0:00', '0:30', '1:00', '1:30', '2:00', '2:30']);
+  });
+
+  test('an instantaneous range does not divide by zero', ({ expect }) => {
+    const scale = timeScale({ range: { start: 100, end: 100 }, width: 220, pad: PAD });
+    expect(scale.at(100)).toBe(PAD);
+  });
+
+  test('ticks thin out with the width, never below two', ({ expect }) => {
+    const wide = timeScale({ range: { start: 0, end: 1_000 }, width: 800, pad: PAD });
+    const narrow = timeScale({ range: { start: 0, end: 1_000 }, width: 120, pad: PAD });
+    // Round 0.2s steps across the wide one; the narrow one keeps just its two ends.
+    expect(wide.ticks).toHaveLength(6);
+    expect(narrow.ticks).toHaveLength(2);
+    expect(wide.ticks[0].at).toBe(PAD);
+    expect(wide.ticks[5].at).toBe(790);
+  });
+});
+
+describe('unitScale', () => {
+  test('one step per event, whatever the gaps between them', ({ expect }) => {
+    // The third event is a hundred times further from the second than the second is from the first;
+    // on this axis that lull is one step like any other.
+    const scale = unitScale({ times: [0, 10, 1_010], step: STEP, pad: PAD });
+    expect(scale.at(0)).toBe(PAD);
+    expect(scale.at(10)).toBe(30);
+    expect(scale.at(1_010)).toBe(50);
+  });
+
+  test('out of order and duplicate instants land on the same units', ({ expect }) => {
+    const scale = unitScale({ times: [1_010, 10, 0, 10], step: STEP, pad: PAD });
+    expect([scale.at(0), scale.at(10), scale.at(1_010)]).toEqual([PAD, 30, 50]);
+  });
+
+  test('an instant between two events sits proportionally between their units', ({ expect }) => {
+    const scale = unitScale({ times: [0, 100], step: STEP, pad: PAD });
+    expect(scale.at(25)).toBe(15);
+    expect(scale.at(50)).toBe(20);
+  });
+
+  test('an instant outside the events clamps to the nearest end', ({ expect }) => {
+    const scale = unitScale({ times: [100, 200], step: STEP, pad: PAD });
+    expect(scale.at(0)).toBe(PAD);
+    expect(scale.at(10_000)).toBe(30);
+  });
+
+  test('the width ends at the newest event, with no empty unit after it', ({ expect }) => {
+    expect(unitScale({ times: [0, 10, 20], step: STEP, pad: PAD }).width).toBe(2 * PAD + 2 * STEP);
+  });
+
+  test('no events is a drawing with no axis rather than a division by zero', ({ expect }) => {
+    const scale = unitScale({ times: [], step: STEP, pad: PAD });
+    expect(scale.at(1_234)).toBe(PAD);
+    expect(scale.ticks).toEqual([]);
+    expect(scale.width).toBe(2 * PAD);
+  });
+
+  test('ticks are event ordinals, strided so their labels cannot collide', ({ expect }) => {
+    // A step as wide as a label leaves room for one tick per event.
+    expect(unitScale({ times: [0, 1, 2, 3, 4, 5], step: 40, pad: PAD }).ticks).toEqual([
+      { at: PAD, label: '#1' },
+      { at: PAD + 40, label: '#2' },
+      { at: PAD + 80, label: '#3' },
+      { at: PAD + 120, label: '#4' },
+      { at: PAD + 160, label: '#5' },
+      { at: PAD + 200, label: '#6' },
+    ]);
+    // Half that, and only every third event can carry one.
+    expect(unitScale({ times: [0, 1, 2, 3, 4, 5], step: STEP, pad: PAD }).ticks).toEqual([
+      { at: PAD, label: '#1' },
+      { at: PAD + 3 * STEP, label: '#4' },
+    ]);
+  });
+
+  test('a single event still labels itself', ({ expect }) => {
+    expect(unitScale({ times: [7], step: STEP, pad: PAD }).ticks).toEqual([{ at: PAD, label: '#1' }]);
+  });
+});

package/src/components/Gantt/gantt-scale.ts

@@ -0,0 +1,143 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * What the horizontal axis measures.
+ * - `time` — real duration, fitted to the width available: an idle gap is as wide as it was long.
+ * - `unit` — one fixed step per event: a burst and a lull read alike, and the drawing grows to the
+ *   right instead of compressing, so an event already placed never moves again. That is what makes a
+ *   live chart watchable — on a fitted axis every arrival shifts the whole history left.
+ */
+export type GanttAxis = 'time' | 'unit';
+
+/** A labelled gridline, positioned in the same pixels as `GanttScale.at`. */
+export type GanttTick = { at: number; label: string };
+
+/** The mapping every part of the drawing shares: an instant to a horizontal offset in pixels. */
+export type GanttScale = {
+  at: (time: number) => number;
+  /** The drawing's width: the time axis takes what it is given, the unit axis states its own. */
+  width: number;
+  /** The labelled gridlines, as many as fit — the label's own width decides, so the scale owns this. */
+  ticks: GanttTick[];
+};
+
+/** Room a tick label needs; elapsed labels are short, so this also caps how many fit. */
+const TIME_LABEL_WIDTH = 56;
+const MAX_TIME_TICKS = 10;
+
+/** Round tick intervals in milliseconds, so elapsed labels read `0s, 10s, 20s` rather than `13.4s`. */
+const TICK_STEPS = [
+  100, 200, 500, 1_000, 2_000, 5_000, 10_000, 15_000, 30_000, 60_000, 120_000, 300_000, 600_000, 900_000, 1_800_000,
+  3_600_000, 7_200_000, 21_600_000, 43_200_000, 86_400_000,
+];
+
+const pad2 = (value: number): string => String(value).padStart(2, '0');
+
+/**
+ * Elapsed time since the start of the axis. The span picks the form for every tick alike, so a
+ * run's labels read as one unit: `0.2s` below a second's step, `45s` below a minute, `1:05` below an
+ * hour, `1:02:05` beyond.
+ */
+export const formatElapsed = (elapsed: number, { span, step }: { span: number; step: number }): string => {
+  const seconds = Math.round(elapsed / 1_000);
+  if (span >= 3_600_000) {
+    return `${Math.floor(seconds / 3_600)}:${pad2(Math.floor(seconds / 60) % 60)}:${pad2(seconds % 60)}`;
+  }
+  if (span >= 60_000) {
+    return `${Math.floor(seconds / 60)}:${pad2(seconds % 60)}`;
+  }
+  if (step < 1_000) {
+    return `${(elapsed / 1_000).toFixed(1)}s`;
+  }
+  return `${seconds}s`;
+};
+
+/** An event's ordinal is two or three glyphs, so its labels pack tighter than a clock's. */
+const EVENT_LABEL_WIDTH = 40;
+
+export type TimeScaleOptions = {
+  range: { start: number; end: number };
+  /** The width the range is fitted into. */
+  width: number;
+  /** Clearance at each end, so a bar's cap and the first tick's label stay inside the drawing. */
+  pad: number;
+};
+
+/** Duration against width, labelled with the time elapsed since the start of the range. */
+export const timeScale = ({ range, width, pad }: TimeScaleOptions): GanttScale => {
+  const span = Math.max(range.end - range.start, 1);
+  const inner = Math.max(width - 2 * pad, 1);
+  const at = (time: number): number => pad + ((time - range.start) / span) * inner;
+  const maxTicks = Math.max(2, Math.min(MAX_TIME_TICKS, Math.floor(inner / TIME_LABEL_WIDTH)));
+  const step =
+    TICK_STEPS.find((candidate) => span / candidate <= maxTicks - 1) ??
+    Math.ceil(span / (maxTicks - 1) / TICK_STEPS[TICK_STEPS.length - 1]) * TICK_STEPS[TICK_STEPS.length - 1];
+  const ticks: GanttTick[] = [];
+  for (let elapsed = 0; elapsed <= span; elapsed += step) {
+    ticks.push({ at: at(range.start + elapsed), label: formatElapsed(elapsed, { span, step }) });
+  }
+  return { at, width, ticks };
+};
+
+export type UnitScaleOptions = {
+  /** Every event's instant; order and duplicates do not matter. */
+  times: readonly number[];
+  /** Pixels per event — the axis's one unit. */
+  step: number;
+  /** Clearance at each end, which also keeps the newest node off the edge. */
+  pad: number;
+};
+
+/**
+ * One step per event, in the order they happened. Ordinals are global rather than per lane: a
+ * delegation drops from a parent's node to its child's first node, and only a shared ordering keeps
+ * those two at the same offset.
+ */
+export const unitScale = ({ times, step, pad }: UnitScaleOptions): GanttScale => {
+  const events = [...new Set(times)].sort((left, right) => left - right);
+  const last = Math.max(events.length - 1, 0);
+
+  /** Index of the last event at or before `time`, or -1 when `time` precedes every event. */
+  const floorIndex = (time: number): number => {
+    let low = 0;
+    let high = events.length - 1;
+    let found = -1;
+    while (low <= high) {
+      const mid = (low + high) >> 1;
+      if (events[mid] <= time) {
+        found = mid;
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+    return found;
+  };
+
+  // An instant between two events sits proportionally between their units: a lane's start or end is
+  // rarely an event of its own, and snapping it to the nearest would pull a bar's edge off its node.
+  const unit = (time: number): number => {
+    if (events.length === 0) {
+      return 0;
+    }
+    const index = floorIndex(time);
+    if (index < 0) {
+      return 0;
+    }
+    if (index >= last) {
+      return last;
+    }
+    const from = events[index];
+    return index + (time - from) / (events[index + 1] - from);
+  };
+
+  const stride = Math.max(1, Math.ceil(last / Math.max(Math.floor((last * step) / EVENT_LABEL_WIDTH), 1)));
+  const ticks: GanttTick[] = [];
+  for (let index = 0; events.length > 0 && index <= last; index += stride) {
+    ticks.push({ at: pad + index * step, label: `#${index + 1}` });
+  }
+
+  return { at: (time) => pad + unit(time) * step, width: 2 * pad + last * step, ticks };
+};

package/src/components/Gantt/index.ts

@@ -3,3 +3,5 @@
 //
 
 export * from './Gantt.tsx';
+export * from './gantt-rows.ts';
+export * from './gantt-scale.ts';

package/src/components/Gantt/useEnter.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+/**
+ * Which of `ids` arrived since the last frame.
+ *
+ * A caller draws an entering element at the place it came from — the event before it, the node that
+ * spawned its lane — and the next frame draws it where it belongs, leaving a CSS transition to carry
+ * it the rest of the way. That is all the bookkeeping an enter animation needs: everything else in
+ * the drawing animates from its own previous value, which the browser already has.
+ *
+ * Nothing present on mount ever counts as entering — a chart that animates its whole history open on
+ * first paint is noise, since the reader was not there to see it arrive.
+ */
+export const useEnter = (ids: readonly string[]): ((id: string) => boolean) => {
+  const [settled, setSettled] = useState<ReadonlySet<string>>(() => new Set(ids));
+  const entering = ids.some((id) => !settled.has(id));
+
+  useEffect(() => {
+    if (!entering) {
+      return;
+    }
+    // The transition needs one painted frame at the origin to run from. This effect is already past
+    // that paint, so the frame after it is where the resting value belongs.
+    const frame = requestAnimationFrame(() => setSettled(new Set(ids)));
+    return () => cancelAnimationFrame(frame);
+  });
+
+  return (id) => !settled.has(id);
+};

package/src/components/Gantt/useRangeTween.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useEffect, useRef, useState } from 'react';
+
+export type TimeRange = { start: number; end: number };
+
+/** How long the axis takes to settle on new bounds. */
+const TWEEN_DURATION = 400;
+
+const easeOutCubic = (progress: number): number => 1 - (1 - progress) ** 3;
+
+/** Motion is skipped where nothing would see it, or where the reader asked for less of it. */
+const shouldSnap = (): boolean =>
+  typeof document === 'undefined' ||
+  document.hidden ||
+  (typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches);
+
+/**
+ * The range to draw with: `target`, reached over a short ease rather than in one step, so a
+ * time axis whose bounds move (a new event, `now` advancing) slides every span, node and tick to
+ * its new place together instead of jumping. A new target mid-flight eases on from wherever the
+ * drawing is, so a stream of updates reads as one continuous motion.
+ */
+export const useRangeTween = (target: TimeRange, enabled: boolean): TimeRange => {
+  const [shown, setShown] = useState(target);
+  const shownRef = useRef(target);
+
+  useEffect(() => {
+    const from = shownRef.current;
+    const settle = (range: TimeRange) => {
+      shownRef.current = range;
+      setShown(range);
+    };
+    if (!enabled || shouldSnap() || (from.start === target.start && from.end === target.end)) {
+      settle(target);
+      return;
+    }
+
+    let frame: number | undefined;
+    const startedAt = performance.now();
+    const step = (time: number) => {
+      const progress = Math.min((time - startedAt) / TWEEN_DURATION, 1);
+      const eased = easeOutCubic(progress);
+      settle({
+        start: from.start + (target.start - from.start) * eased,
+        end: from.end + (target.end - from.end) * eased,
+      });
+      frame = progress < 1 ? requestAnimationFrame(step) : undefined;
+    };
+    frame = requestAnimationFrame(step);
+    return () => {
+      if (frame !== undefined) {
+        cancelAnimationFrame(frame);
+      }
+    };
+  }, [enabled, target.start, target.end]);
+
+  return enabled ? shown : target;
+};

package/src/components/ProcessTree/ProcessTree.stories.tsx

@@ -11,10 +11,9 @@ import { log } from '@dxos/log';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
 import { makeProcess } from '../../testing/index.ts';
-
 import { ProcessTree, type ProcessTreeProps } from './ProcessTree.tsx';
 
-const processes: Process.Info[] = [
+const processes: Process.Process[] = [
   makeProcess({
     pid: Process.ID.make('97793611-815e-4a67-bc04-60fa67b2c987'),
     name: 'Trigger watcher',
@@ -68,7 +67,7 @@ const DefaultStory = (props: ProcessTreeProps) => {
 };
 
 const meta: Meta<typeof ProcessTree> = {
-  title: 'plugins/plugin-assistant/components/ProcessTree',
+  title: 'ui/react-ui-trace/ProcessTree',
   component: ProcessTree,
   render: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-(--dx-complementary-sidebar-size)' })],