Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/users/user_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,37 @@ _Note: Variables can refer only to PV traces on the same plot, not to other form

---

## Compare with a Time Offset

Overlay a trace's past data on the current time axis to see how a signal has changed. For example, compare today's beam current with the same signal one day or one week ago.

**Workflow:**

1. In the **Layers** panel, hover over a trace row to reveal the clock icon (①).
2. Click the clock icon to open the offset menu.
3. Choose a preset (**-1h**, **-1d**, **-7d**, **-30d**) or type a custom offset such as `-2h` or `-3d` and click **Go**.

Trace duplicates the trace, shifts its archive data by the offset, and draws it on the same axis. The offset trace uses a **dashed line** so you can tell it apart from the original, and its name in the legend and tooltip includes the offset, for example **Beam current (−1 d)**.

**How it works:**

- The offset trace fetches archive data from the shifted time window (for example, yesterday's data for a **-1d** offset) and moves the timestamps onto the current axis so the two traces line up.
- Offset traces are **archive-only** — live data is automatically disabled because live values have no meaningful shifted equivalent.
- If the original trace has a custom **Display Name**, the offset trace keeps it.

### Edit or Remove an Offset

Select the offset trace in **Layers** and open the **General** tab in **Properties**:

- **Time Offset** — change the offset by typing a new value (for example `-12h`). Invalid values show an error below the field.
- **Clear the offset** — delete the text in the **Time Offset** field. The trace goes back to normal and live data is re-enabled.

You can also delete the offset trace like any other trace.

_Note: Offset values use the same units as **Span**: `h` (hours), `d` (days), `w` (weeks), and so on. The offset must start with `-` to look into the past._

---

## Multiple Plots

Add more plots to view different groups of PVs side by side. Each plot has its own axes, traces, time range, and settings.
Expand Down
111 changes: 111 additions & 0 deletions src/App.css
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,97 @@
transition: background-color 0.15s;
}

/* Clock button (duplicate-with-offset trigger) */
.layer-row__offset-trigger {
display: flex;
align-items: center;
justify-content: center;
width: 20px;
height: 20px;
border: none;
background: transparent;
color: var(--cds-text-helper);
cursor: pointer;
padding: 0;
border-radius: 2px;
transition: background-color 0.15s;
}

.layer-row__offset-trigger:hover {
background-color: var(--cds-layer-hover);
}

/* Offset popover */
.offset-popover {
position: absolute;
top: 100%;
right: 0;
z-index: 100;
background: var(--cds-layer);
border: 1px solid var(--cds-border-subtle);
border-radius: 4px;
padding: 8px;
box-shadow: 0 2px 6px rgba(0, 0, 0, 0.2);
min-width: 140px;
}

.offset-popover__heading {
font-size: 11px;
color: var(--cds-text-helper);
margin-bottom: 4px;
}

.offset-popover__preset {
display: block;
width: 100%;
text-align: left;
padding: 4px 8px;
border: none;
background: transparent;
color: var(--cds-text-primary);
font-size: 12px;
cursor: pointer;
border-radius: 2px;
transition: background-color 0.15s;
}

.offset-popover__preset:hover {
background-color: var(--cds-layer-hover);
}

.offset-popover__custom-row {
display: flex;
gap: 4px;
margin-top: 4px;
}

.offset-popover__input {
flex: 1;
font-size: 11px;
padding: 2px 4px;
border: 1px solid var(--cds-border-strong);
border-radius: 2px;
background: var(--cds-field);
color: var(--cds-text-primary);
min-width: 0;
}

.offset-popover__submit {
font-size: 11px;
padding: 2px 6px;
border: 1px solid var(--cds-border-strong);
border-radius: 2px;
background: var(--cds-button-tertiary);
color: var(--cds-text-inverse);
cursor: pointer;
transition: opacity 0.15s;
}

.offset-popover__submit:disabled {
cursor: not-allowed;
opacity: 0.5;
}

.axis-drop-zone {
border-radius: 2px;
transition: background-color 0.15s;
Expand Down Expand Up @@ -397,6 +488,19 @@
color: var(--cds-text-primary);
}

.view-mode-btn:disabled {
opacity: 0.25;
pointer-events: none;
}

.plot-tab-bar__separator {
width: 1px;
height: 16px;
background-color: var(--cds-border-subtle);
margin: 0 4px;
flex-shrink: 0;
}

.plot-content {
flex: 1;
overflow: hidden;
Expand Down Expand Up @@ -446,6 +550,13 @@
z-index: 10;
}

.plot-grid__cell-btn--reset {
position: absolute;
top: 8px;
left: 80px;
z-index: 10;
}

.plot-grid__cell-btn--close {
position: absolute;
top: 8px;
Expand Down
31 changes: 30 additions & 1 deletion src/api/time.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
import { describe, it, expect } from 'vitest';
import { parseSpanMs, relativeRangeMs, resolveTimeWindow, toDatetimeLocal, msToNs } from './time';
import {
parseSpanMs,
relativeRangeMs,
resolveTimeWindow,
toDatetimeLocal,
msToNs,
parseOffsetMs,
formatOffsetLabel,
} from './time';

const SEC = 1000;
const MIN = 60 * SEC;
Expand Down Expand Up @@ -141,6 +149,27 @@ describe('resolveTimeWindow', () => {
});
});

describe('parseOffsetMs', () => {
it('parses signed and bare offsets, rejects invalid input', () => {
expect(parseOffsetMs('-1d')).toBe(-DAY);
expect(parseOffsetMs('-7d')).toBe(-7 * DAY);
expect(parseOffsetMs('+2h')).toBe(2 * HOUR);
expect(parseOffsetMs('30s')).toBe(30 * SEC);
expect(parseOffsetMs('')).toBeNull();
expect(parseOffsetMs('abc')).toBeNull();
expect(parseOffsetMs('-0h')).toBeNull();
});
});

describe('formatOffsetLabel', () => {
it('picks the largest whole unit with the correct sign', () => {
expect(formatOffsetLabel(-DAY)).toBe('−1 d');
expect(formatOffsetLabel(-14 * DAY)).toBe('−2 w');
expect(formatOffsetLabel(2 * HOUR)).toBe('+2 h');
expect(formatOffsetLabel(-500)).toBe('−500 ms');
});
});

describe('toDatetimeLocal', () => {
it('round-trips through Date in local time', () => {
const ms = new Date('2024-03-04T05:06').getTime();
Expand Down
27 changes: 27 additions & 0 deletions src/api/time.ts
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,33 @@ export function relativeRangeMs(range: string): number | null {
return parseSpanMs(range.slice(1));
}

// Parse a signed offset like "-1d", "+2h" into milliseconds. Returns null if invalid.
export function parseOffsetMs(offset: string): number | null {
const trimmed = offset.trim();
if (!trimmed) return null;
const neg = trimmed.startsWith('-');
const raw = neg || trimmed.startsWith('+') ? trimmed.slice(1) : trimmed;
const ms = parseSpanMs(raw);
return ms != null ? (neg ? -ms : ms) : null;
}

// Human-readable label for a millisecond offset, e.g. "−1 d", "+2 h".
export function formatOffsetLabel(offsetMs: number): string {
const sign = offsetMs < 0 ? '−' : '+';
const abs = Math.abs(offsetMs);
const units: [number, string][] = [
[SPAN_UNIT_MS.w, 'w'],
[SPAN_UNIT_MS.d, 'd'],
[SPAN_UNIT_MS.h, 'h'],
[SPAN_UNIT_MS.m, 'm'],
[SPAN_UNIT_MS.s, 's'],
];
for (const [ms, label] of units) {
if (abs >= ms && abs % ms === 0) return `${sign}${abs / ms} ${label}`;
}
return `${sign}${abs} ms`;
}

// Format an epoch-ms instant as a datetime-local value ("YYYY-MM-DDTHH:mm") in
// local time, suitable for seeding the From/To inputs from an absolute time.
export function toDatetimeLocal(ms: number): string {
Expand Down
1 change: 1 addition & 0 deletions src/components/LeftPanel.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ function panel(plots: Plot[]) {
onAddTrace={vi.fn()}
onAddFormula={vi.fn()}
onDeleteTrace={vi.fn()}
onDuplicateWithOffset={vi.fn()}
onAddAxis={vi.fn()}
onSearchPvs={vi.fn()}
onDeleteAxis={vi.fn()}
Expand Down
Loading
Loading