feat(schema): add Timeline display type and TimelineSeriesSchema

[alex-fedotyev]

Add DisplayType.Timeline to the shared enum and the accompanying TimelineSeriesSchema types. This is the first of three chained PRs landing the Timeline dashboard tile; the renderer and builder editor follow separately.

Summary

Registers DisplayType.Timeline = 'timeline' in the shared enum, adds TimelineSeriesSchema and TimelineSeries to SharedChartSettingsSchema, and updates all exhaustive Record<DisplayType, ...> maps so TypeScript compilation stays clean throughout the chain.

External API (packages/api/src/routers/external-api/v2/utils/dashboards.ts): two fall-through cases route Timeline to the existing "unsupported display type" error path, matching what Heatmap does. No Timeline tile is reachable from the external API until a later PR adds full support there.

What's in this PR

• DisplayType.Timeline enum value in packages/common-utils/src/types.ts
• TimelineSeriesSchema (Zod) + TimelineSeries (inferred type)
• timelineSeries: z.array(TimelineSeriesSchema).optional() on SharedChartSettingsSchema
• QUERY_PARAMS_BY_DISPLAY_TYPE[Timeline] and QUERY_PARAM_EXAMPLES[Timeline] in rawSqlParams.ts
• SQL_PLACEHOLDERS[Timeline] and DISPLAY_TYPE_INSTRUCTIONS[Timeline] in ChartEditor/constants.tsx
• External API stub (two switch fall-throughs) in dashboards.ts

What's NOT in this PR

• The chart renderer (DBTimelineChart, DashboardTimelineChart) - in PR B
• The builder editor (TimelineEditor, TimelineSeriesRow) - in PR C
• Dashboard wiring (DBDashboardPage tile render path) - in PR B
• packages/api/src/utils/zod.ts external API schema mirror - in PR B or C

Why the split

The renderer and editor touch ~1 200 lines across packages/app/. Keeping the schema as its own commit makes the exhaustive-record updates reviewable in isolation and gives PR B a clean base to target.

Test plan

• TypeScript compilation clean across all packages (yarn nx run-many -t typecheck)
• No new CI failures (lint, unit, knip)

[changeset-bot]

🦋 Changeset detected

Latest commit: 510a4c8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@hyperdx/common-utils	Minor
@hyperdx/api	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	May 5, 2026 11:04am

[github-actions]

🔴 Tier 4 — Critical

Touches auth, data models, config, tasks, OTel pipeline, ClickHouse, or CI/CD.

Why this tier:

• Critical-path files (1):
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts
• Cross-layer change: touches frontend (packages/app) + backend (packages/api) + shared utils (packages/common-utils)

Additional context: agent branch (claude/dashboard-timeline-tile-schema)

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

Stats

• Production files changed: 4
• Production lines changed: 131 (+ 58 in test files, excluded from tier calculation)
• Branch: claude/dashboard-timeline-tile-schema
• Author: alex-fedotyev

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

PR Review

✅ No critical issues found.

A few minor observations worth considering:

• ⚠️ timelineSeries added to SharedChartSettingsSchema means it's valid on all chart config types (Line, Bar, Pie, etc.), not just DisplayType.Timeline. This could allow orphaned timelineSeries data on non-Timeline tiles. If the renderer in the follow-up PR guards on displayType, this is fine — but consider documenting this assumption or using a discriminated union if strictness is needed later.

• ℹ️ TIMELINE_EXAMPLE_SQL uses < fromUnixTimestamp64Milli({endDateMilliseconds}) (exclusive upper bound) while DATE_RANGE_WHERE_EXAMPLE_SQL uses <= (inclusive). Minor inconsistency in the example SQL that could confuse users copying from the other example.

Both points are non-blocking for a schema-only PR. The Zod superRefine validation for mode-specific required fields is well-implemented, tests cover the key cases, and the external API routing (unsupported-type path matching Heatmap) is correctly handled.

[github-actions]

E2E Test Results

✅ All tests passed • 159 passed • 3 skipped • 1231s

Status	Count
✅ Passed	159
❌ Failed	0
⚠️ Flaky	4
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[alex-fedotyev]

Good catch on both items. Applied in 77b24fe:

• Extracted the Timeline SQL example to TIMELINE_EXAMPLE_SQL in rawSqlParams.ts; constants.tsx now imports it instead of duplicating the string
• Added .superRefine() to TimelineSeriesSchema enforcing events mode requires labelExpression and value_change mode requires trackColumn; 4 new unit tests cover the happy and rejection paths

[alex-fedotyev]

PR B (renderer) is open at #2192 and stacked on this branch. If you're reviewing both together, start here.