feat(api): expose table tile alternateRowBackground in the external Dashboards API

[alex-fedotyev]

Summary

Follow-up to #2519, which added the Alternate Row Background display setting (zebra striping) to table tiles in the app and the internal chart schema. That PR shipped the app and common-utils slice only; this brings the setting to the external REST Dashboards API.

The field lives on the shared chart-settings schema rather than the builder-only config, so it applies to both builder and raw SQL table tiles (we moved it up to the shared schema during the #2519 review so SQL tiles get striping too). The external API now matches:

• Adds alternateRowBackground (optional boolean) to both the builder table config and the raw SQL table config in the request/response schemas (zod.ts).
• Threads it through the internal/external converters in both directions, guarding the raw SQL side by display type exactly like the existing onClick field.
• Documents it in the OpenAPI spec for both TableBuilderChartConfig and TableRawSqlChartConfig, and regenerates openapi.json.

No new helpers; every edit sits beside the existing groupByColumnsOnLeft / onClick fields on the same schema, converter, and JSDoc block.

Test plan

• Extended the POST and PUT round-trip integration tests to send and assert alternateRowBackground: true on both a builder table tile and a raw SQL table tile. The raw SQL assertions are new coverage that guards the SQL path.
• dashboards.int.test.ts: 162/162 passing locally against a ClickHouse + MongoDB stack. This is the end-to-end round-trip proof (POST a dashboard with the field, read it back, field preserved on both config kinds).
• tsc --noEmit, eslint, and spectral (lint:openapi) all clean.

Tier

This lands review/tier-4 because it necessarily touches packages/api/src/routers/external-api/, which the triage classifier always treats as critical-path. The change itself is small (38 production lines) and mirrors the existing groupByColumnsOnLeft and onClick fields.

Not in this PR

• MCP dashboard authoring schema and prompt (HDX-4603), stacked on this branch.
• ClickStack customer docs (DOC-855).

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jul 23, 2026 3:51pm
hyperdx-storybook	Ready	Preview, Comment	Jul 23, 2026 3:51pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 11e1ef6

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

This PR includes changesets to release 3 packages

Name	Type
@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

[github-actions]

🔴 Tier 4 — Critical

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

Why this tier:

• Critical-path files (2):
  • packages/api/src/routers/external-api/v2/dashboards.ts
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts

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: 38 (+ 63 in test files, excluded from tier calculation)
• Branch: alex/HDX-4602-table-tile-alternate-row-external-api
• 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.

[greptile-apps]

Greptile Summary

This PR exposes table zebra striping in the external Dashboards API. The main changes are:

• Adds alternateRowBackground to builder and raw SQL table request schemas.
• Preserves the field through dashboard config conversion in both directions.
• Updates the OpenAPI schema and generated API document.
• Extends dashboard integration tests for table round trips.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
packages/api/src/utils/zod.ts	Adds the optional table striping flag to the external builder and raw SQL table schemas.
packages/api/src/routers/external-api/v2/utils/dashboards.ts	Threads the table striping flag through internal and external dashboard config conversion.
packages/api/src/routers/external-api/v2/dashboards.ts	Documents the new table striping field in the external API schema blocks.
packages/api/openapi.json	Regenerates the OpenAPI document with the new table striping field.
packages/api/src/routers/external-api/tests/dashboards.int.test.ts	Adds dashboard API test coverage for preserving the table striping flag.
.changeset/table-tile-alternate-row-external-api.md	Adds a patch changeset for the external API addition.

_{Reviews (2): Last reviewed commit: "test(api): pin alternateRowBackground om..." | Re-trigger Greptile}

[github-actions]

E2E Test Results

✅ All tests passed • 242 passed • 1 skipped • 1063s

Status	Count
✅ Passed	242
❌ Failed	0
⚠️ Flaky	1
⏭️ Skipped	1

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

Deep Review

Scope: feat(api): expose table tile alternateRowBackground in the external Dashboards API — adds an optional boolean to the builder-table and raw-SQL-table external schemas, threads it through both converter directions (mirroring onClick), and documents it in the OpenAPI JSDoc.

Environment note: The shell was non-functional in this run (bwrap: Can't create file at /home/.mcp.json on every command, sandbox toggle honored or not), so git diff-based scope detection was impossible. The review was reconstructed from the full on-disk content of every touched file via read-only tooling; converter round-trip behavior was traced by hand across all three field states.

✅ No critical issues found. The change is a clean, symmetric additive field that mirrors the existing onClick handling on every path; round-trip of absent / explicit-false / explicit-true was verified in both directions on both the builder and raw SQL converter branches, and the field is placed consistently across the Zod schema, OpenAPI JSDoc, and internal SharedChartSettingsSchema.

🟡 P2 -- recommended

• packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts:2629 -- The dedicated omit / explicit-false round-trip test defines only builder tiles (displayType: 'table' with no configType: 'sql'), so the raw SQL converter branch is exercised only with alternateRowBackground: true; its distinct displayType === 'table' ternary and reliance on _.omitBy(_.isNil) to preserve false while dropping omitted values are untested, so a future regression that treated the value as truthy (silently discarding false) would pass the whole suite.
  • Fix: Add raw SQL (configType: 'sql') table tiles to the omit / false test — one omitting the field (assert not.toHaveProperty('alternateRowBackground')) and one with alternateRowBackground: false (assert toBe(false)) — through POST and read-back.
  • _{testing, correctness}

🔵 P3 nitpicks (1)

• packages/api/src/routers/external-api/v2/dashboards.ts:740 (and :1154) -- The OpenAPI JSDoc declares default: false, but the Zod schema uses .optional() with no .default(false) (packages/api/src/utils/zod.ts:304, :311), so an omitted field round-trips as absent rather than materialized false on read; this is harmless (the renderer treats undefined as off) and is identical to the already-accepted sibling groupByColumnsOnLeft.
  • Fix: Leave as-is for consistency, or reconcile doc-vs-schema for both fields together (drop default: false from the JSDoc, or add .default(false) in Zod).

---

Reviewers (4): correctness, adversarial, testing, api-contract.

Testing gaps:

• Raw SQL table path lacks explicit-false and omission assertions; only true is covered there (POST and PUT).
• The PR description references regenerating openapi.json, but no static spec file exists under packages/api/src/routers/external-api/ — the spec is generated at runtime from the JSDoc, so there is no committed artifact to verify against the schema.