Skip to content
Merged
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
8 changes: 8 additions & 0 deletions .changeset/add-click-ui.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
'@hyperdx/app': patch
---

feat: add `@clickhouse/click-ui` as a dependency and mount `ClickUIProvider`
next to `MantineProvider`. The provider follows the HyperDX color mode and does
not persist its own theme. The "open an issue on GitHub" link in error messages
is the first component to use click-ui (`Link`).
18 changes: 18 additions & 0 deletions agent_docs/code_style.md
Original file line number Diff line number Diff line change
Expand Up @@ -406,6 +406,24 @@ The UI is built with **Mantine components**, but **colors and surfaces** should

Mantine theme overrides in `packages/app/src/theme/**` may map Mantine’s scale to our palette; that does not replace using **`var(--color-...)`** in new styling where you need explicit color control.

## Click UI (incremental adoption)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — New Click UI section splits the semantic-tokens section, so the chart-colors rule now sits under the Click UI heading

Move the ## Click UI (incremental adoption) block below the "Chart and visualization colors are a separate, more specific contract" paragraph. That paragraph belongs to "Semantic design tokens", and right now it reads as part of the Click UI guidance.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond


`@clickhouse/click-ui` is a dependency of `packages/app`. `ThemeWrapper` mounts
`ClickUIProvider` inside `MantineProvider` with `persistTheme={false}`, so it
follows the HyperDX color mode and never writes its own theme to localStorage.
Storybook and `renderWithMantine` in tests get the provider for free.

- **Do**: Prefer a click-ui component over a new Mantine one when click-ui has

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — New 'prefer click-ui over Mantine' rule contradicts the existing 'Prefer Mantine components' rule in the same doc

The base convention under "Mantine UI Components" says "Prefer Mantine components over custom-styled elements". The new bullet tells contributors to pick click-ui Text/Title/Badge/Container over Mantine. Reword one of the two rules (e.g. scope the Mantine rule, or limit the click-ui rule to Link for now) so the doc doesn't give conflicting guidance.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

an equivalent for a simple primitive (`Link`, `Text`, `Title`, `Container`,
`Badge`, `Separator`, `Spacer`, `Icon`). Import from `@clickhouse/click-ui`.
- **Do not**: Mix both libraries inside one small component, and do not
replace working Mantine code outside the change you were asked to make.
- **Styling**: click-ui styles live in the `clickui` CSS cascade layer, so any
unlayered app or Mantine rule wins over them. Override `--click-*` variables
outside the layer if a token must change.
- **First use**: `packages/app/src/components/ContactSupportText.tsx` and the
`Click UI/Link` story in `packages/app/src/stories/ClickUI.stories.tsx`.

**Chart and visualization colors are a separate, more specific contract** — they have their own categorical, semantic, and heatmap palettes wired through `packages/app/src/utils.ts` helpers. Don't hard-code series colors or reuse `--color-text-*` for charts. See [`data_viz_colors.md`](./data_viz_colors.md) before touching anything that renders data.

## Refactoring
Expand Down
5 changes: 5 additions & 0 deletions packages/app/jest.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ module.exports = {
'^ky$': '<rootDir>/src/__mocks__/ky-universal.ts',
'^react-markdown$': '<rootDir>/src/__mocks__/react-markdown.tsx',
'^remark-gfm$': '<rootDir>/src/__mocks__/remark-gfm.ts',
'^react-syntax-highlighter$':
'<rootDir>/src/__mocks__/react-syntax-highlighter.tsx',
// @clickhouse/click-ui depends on ESM-only lodash-es; lodash has the same API.
'^lodash-es$': 'lodash',
'^lodash-es/(.*)$': 'lodash/$1',
},
setupFilesAfterEnv: ['<rootDir>/src/setupTests.tsx'],
// Coverage floors are scoped to hooks/ and utils/ only — the genuinely
Expand Down
3 changes: 3 additions & 0 deletions packages/app/next.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,9 @@ const nextConfig = {
// when running dev and E2E simultaneously (e.g. NEXT_DIST_DIR=.next-e2e)
...(process.env.NEXT_DIST_DIR ? { distDir: process.env.NEXT_DIST_DIR } : {}),
reactCompiler: true,
// click-ui ships per-component CSS imports from node_modules, which Next
// rejects as global CSS unless the package is transpiled.
transpilePackages: ['@clickhouse/click-ui'],
basePath: basePath,
env: {
// Ensures bundler-time replacements for client/server code that references this env var
Expand Down
1 change: 1 addition & 0 deletions packages/app/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
"storybook:build": "storybook build"
},
"dependencies": {
"@clickhouse/click-ui": "^0.12.0",
"@codemirror/autocomplete": "^6.0.0",
"@codemirror/lang-json": "^6.0.1",
"@codemirror/lang-sql": "^6.7.0",
Expand Down
8 changes: 6 additions & 2 deletions packages/app/src/ThemeWrapper.tsx
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import React from 'react';
import { ClickUIProvider } from '@clickhouse/click-ui';

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Importing the click-ui barrel in the app-wide provider likely adds the whole library to every page's bundle

ThemeWrapper is used by _app.tsx, so import { ClickUIProvider } from '@clickhouse/click-ui' puts the barrel in the shared bundle. The new jest mock (src/__mocks__/react-syntax-highlighter.tsx) says the barrel pulls in react-syntax-highlighter/prism and calls registerLanguage at import time, and each component also imports its own CSS. Both are side effects, so the bundler likely can't tree-shake CodeBlock, the Radix primitives, react-window and so on. Fix: import from per-component entry points if click-ui ships them, or check the size of the _app chunk with the bundle analyzer before and after this change.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a real issue. From claude:

  • The fix belongs in click-ui. The asset maps need lazy loading or a split so Icon does not include 950 KB of flags and logos. A ./ClickUIProvider subpath export would help a little but does not address the asset size.
  • In HyperDX, any click-ui adoption that mounts the provider pays this cost once, regardless of which components follow. The decision is whether a 315 KB gzip increase on every page is acceptable for the migration start, or whether it waits on the upstream fix.
  • Prefer components that do not touch Icon while that is open: Text, Title, Container, Separator, Spacer. Avoid Link with the icon prop, Badge with icons, and Button with icons.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Barrel import of click-ui in _app likely puts all of click-ui in the shared bundle

ThemeWrapper is rendered by pages/_app.tsx, so this import loads on every page. The new mock in src/__mocks__/react-syntax-highlighter.tsx says the barrel touches react-syntax-highlighter (registerLanguage) at import time. Module-level side effects like that stop tree-shaking, so CodeBlock's prism/highlight.js/refractor, the date picker, sortablejs and react-window probably all end up in the common chunk just to render one Link. Add experimental.optimizePackageImports: ['@clickhouse/click-ui'] (or import from per-component entry points if the package has them), then compare next build chunk sizes before and after.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed. The _app chunk grows by 315 KB gzip. Per-component imports do not help, since Link and the provider both pull in click-ui's Icon, which bundles every flag and logo SVG as React components, about 950 KB minified. Click-ui ships no provider subpath. The fix is upstream in click-ui's asset loading. We decide here whether to accept the cost for the first adoption step.

What to do

  • The fix belongs upstream in click-ui. The asset maps need lazy loading or a split so Icon does not carry 950 KB of flags and logos. A ./ClickUIProvider subpath export would help a little but does not address the asset weight.
  • In HyperDX, any click-ui adoption that mounts the provider pays this cost once, regardless of which components follow. The decision is whether a 315 KB gzip increase on every page is acceptable for the migration start, or whether it waits on the upstream fix.
  • Prefer components that do not touch Icon while that is open: Text, Title, Container, Separator, Spacer. Avoid Link with the icon prop, Badge with icons, and Button with icons.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — All of click-ui is loaded on every page just to render one Link

ThemeWrapper (mounted in pages/_app.tsx) and ContactSupportText import from the @clickhouse/click-ui barrel. The new __mocks__/react-syntax-highlighter.tsx comment confirms that barrel pulls in react-syntax-highlighter, prism, refractor and highlight.js when the module is imported, along with about 15 Radix packages. Run next build and compare the _app chunk size before and after. If it grew, import Link and ClickUIProvider from per-component entry points, or hold off on mounting the provider app-wide until more click-ui components are in use.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

import { MantineProvider, MantineThemeOverride } from '@mantine/core';
import { Notifications } from '@mantine/notifications';

Expand Down Expand Up @@ -36,8 +37,11 @@ export const ThemeWrapper = ({

return (
<MantineProvider forceColorScheme={colorScheme} theme={mantineTheme}>
<Notifications zIndex={999999} />
{children}
{/* HyperDX user preferences determine the color mode, so click-ui should not persist preferences to localstorage. */}
<ClickUIProvider theme={colorScheme} persistTheme={false}>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — ClickUIProvider adds a second, always-empty toast viewport to every page next to Mantine Notifications

The PR's own test change (SpanLinkedFromSubpanel.test.tsx) shows ClickUIProvider renders an empty Radix toast viewport (role="region") on every page. That puts a second "Notifications" landmark in front of screen readers and takes over the Radix F8 hotkey, but nothing uses it because toasts still go through Mantine <Notifications>. If click-ui allows it, turn off its toast/viewport. If not, write down the decision to keep two toast systems mounted.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — ClickUIProvider adds a second, always-empty toast viewport to every page

The updated SpanLinkedFromSubpanel test ("the providers add ... an empty toast viewport region") shows ClickUIProvider mounts a Radix Toast viewport. In _app.tsx and Storybook that means every page now has an empty role="region" "Notifications (F8)" landmark next to Mantine's <Notifications>, and it takes over the F8 hotkey, even though nothing in HyperDX uses click-ui toasts. If ClickUIProvider has an option to turn off its toast/tooltip sub-providers, use it. If not, mount only the theme provider click-ui exports so the app has one notification system.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — ClickUIProvider adds a second, always-empty toast viewport landmark next to Mantine Notifications

The SpanLinkedFromSubpanel.test.tsx change shows that the provider now renders an empty role="region" toast viewport on every page. Mantine Notifications already provides one. Screen-reader users get two notification landmarks, plus the Radix viewport's hotkey listener. Turn off click-ui's toast provider/viewport if it has an option for that, or note it as a known cost until click-ui toasts are actually used.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — ClickUIProvider adds a second, always-empty toast region to every page

The updated SpanLinkedFromSubpanel test confirms the provider renders an empty toast viewport (role="region"). In the app this sits next to Mantine's <Notifications>, so screen readers get an extra empty 'Notifications' landmark and the toast viewport's hotkey listener is registered globally. Nothing in the app uses click-ui toasts. Turn off click-ui's toast provider through ClickUIProvider's config, or only mount it once click-ui toasts are actually used.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

<Notifications zIndex={999999} />
{children}
</ClickUIProvider>
</MantineProvider>
);
};
17 changes: 17 additions & 0 deletions packages/app/src/__mocks__/react-syntax-highlighter.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
import React from 'react';

// @clickhouse/click-ui's barrel export pulls in react-syntax-highlighter for
// CodeBlock, whose prism build depends on ESM-only hastscript that Jest cannot
// parse. Unit tests never render a click-ui CodeBlock, so this stub only needs
// the surface the click-ui module touches at import time.
function Highlighter({ children }: { children?: React.ReactNode }) {
return <pre>{children}</pre>;
}

Highlighter.registerLanguage = () => undefined;

export const Light = Highlighter;
export const Prism = Highlighter;
export const PrismLight = Highlighter;
export const createElement = () => null;
export default Highlighter;
4 changes: 4 additions & 0 deletions packages/app/src/components/ContactSupportText.module.scss
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
// The link should look like normal font instead of click-ui's link font.
.inlineLink {
font: inherit;
}
13 changes: 11 additions & 2 deletions packages/app/src/components/ContactSupportText.tsx
Original file line number Diff line number Diff line change
@@ -1,15 +1,24 @@
import { Link } from '@clickhouse/click-ui';

import { IS_OSS } from '@/config';

import styles from './ContactSupportText.module.scss';

const GH_LINK = 'https://github.com/hyperdxio/hyperdx/issues';

export const ContactSupportText = () => {
if (IS_OSS) {
return (
<span>
Please open an issue on{' '}
<a href={GH_LINK} target="_blank">
<Link

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Global a { color: inherit; text-decoration: none } overrides click-ui Link's color and underline

packages/app/styles/globals.css:7 is unlayered and loaded in _app.tsx and Storybook. Per this PR's own note, click-ui styles sit in the clickui cascade layer, so that global rule beats the Link's color and underline. The 'GitHub' link then looks like the surrounding toast text, as it did before. Scope the global reset with :where(a:not([class])), or move it into a lower layer. Otherwise every click-ui Link the new guideline asks for will lose its styling the same way.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

className={styles.inlineLink}
href={GH_LINK}
target="_blank"
rel="noopener noreferrer"
>
GitHub
</a>
</Link>
.
</span>
);
Expand Down
12 changes: 4 additions & 8 deletions packages/app/src/components/__tests__/DBTimeChart.test.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
import React from 'react';
import { MantineProvider } from '@mantine/core';
import { Notifications } from '@mantine/notifications';
import { screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

Expand Down Expand Up @@ -307,8 +305,7 @@ describe('DBTimeChart', () => {
// survive — this also guards against dateRange being reintroduced into
// queryShapeIdentity, which would make live-range ticks re-cap the chart.
rerender(
<MantineProvider>
<Notifications />
<TestProviders>
<DBTimeChart
config={{
...groupByConfig,
Expand All @@ -318,7 +315,7 @@ describe('DBTimeChart', () => {
],
}}
/>
</MantineProvider>,
</TestProviders>,
);

// The opt-in survives: no series are re-hidden, so the affordance stays
Expand Down Expand Up @@ -349,10 +346,9 @@ describe('DBTimeChart', () => {
// Change the query shape (a positive seriesLimit below GROUP_COUNT keeps
// series hidden), which should reset the opt-in and re-show the affordance.
rerender(
<MantineProvider>
<Notifications />
<TestProviders>
<DBTimeChart config={{ ...groupByConfig, seriesLimit: 5 }} />
</MantineProvider>,
</TestProviders>,
);

expect(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,12 @@ describe('SpanLinkedFromSubpanel', () => {
const { container } = renderWithMantine(
<SpanLinkedFromSubpanel links={[]} />,
);
// The Mantine provider injects <style> nodes; the component itself must
// contribute no elements.
expect(container.querySelector('div')).toBeNull();
// The providers add <style> nodes and an empty toast viewport region;
// the component itself must contribute no elements.
const stray = Array.from(container.querySelectorAll('div')).filter(
el => !el.closest('[role="region"]'),
);
expect(stray).toHaveLength(0);
expect(screen.queryByTestId('linked-from-row')).not.toBeInTheDocument();
});

Expand Down
19 changes: 13 additions & 6 deletions packages/app/src/setupTests.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import React from 'react';
/* Polyfills for browser APIs in Node.js test environment */
import { TextDecoder, TextEncoder } from 'util';
import { ClickUIProvider } from '@clickhouse/click-ui';
import { MantineProvider } from '@mantine/core';
import { Notifications } from '@mantine/notifications';
import { render } from '@testing-library/react';
Expand Down Expand Up @@ -33,13 +34,17 @@ Object.defineProperty(window, 'matchMedia', {
}),
});

global.renderWithMantine = (ui: React.ReactElement) => {
return render(
<MantineProvider>
global.TestProviders = ({ children }: { children: React.ReactNode }) => (
<MantineProvider>
<ClickUIProvider theme="dark" persistTheme={false}>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Test providers hardcode a dark click-ui theme while Mantine renders in light

TestProviders renders <MantineProvider> (Mantine's default is light) but passes ClickUIProvider theme="dark". ThemeWrapper drives both providers from the same colorScheme. Use one shared constant here, e.g. const scheme = 'light', and pass it as both forceColorScheme={scheme} and theme={scheme}, so tests run with the same pairing as production.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

<Notifications />
{ui}
</MantineProvider>,
);
{children}
</ClickUIProvider>
</MantineProvider>
);

global.renderWithMantine = (ui: React.ReactElement) => {
return render(<TestProviders>{ui}</TestProviders>);
};

if (!globalThis.structuredClone) {
Expand All @@ -49,4 +54,6 @@ if (!globalThis.structuredClone) {

declare global {
function renderWithMantine(ui: React.ReactElement): ReturnType<typeof render>;
// `var`, not `const`, so the global assignment above passes type-check
var TestProviders: React.FC<{ children: React.ReactNode }>;
}
58 changes: 58 additions & 0 deletions packages/app/src/stories/ClickUI.stories.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
import { Link, Text } from '@clickhouse/click-ui';
import { Stack } from '@mantine/core';
import type { Meta, StoryObj } from '@storybook/nextjs';

import { ContactSupportText } from '@/components/ContactSupportText';

// Smoke test for the click-ui integration: the provider in ThemeWrapper must
// follow the Storybook theme toggle, and click-ui text must sit next to
// Mantine layout without either library's globals breaking the other.
const meta: Meta<typeof Link> = {
title: 'Click UI/Link',
component: Link,
parameters: {
layout: 'centered',
},
argTypes: {
size: {
control: 'select',
options: ['xs', 'sm', 'md', 'lg'],
},
weight: {
control: 'select',
options: ['normal', 'medium', 'semibold', 'bold', 'mono'],
},
},
};

export default meta;
type Story = StoryObj<typeof Link>;

export const Playground: Story = {
args: {
children: 'Open the ClickHouse docs',
href: 'https://clickhouse.com/docs',
target: '_blank',
size: 'md',
weight: 'normal',
},
};

export const WithIcon: Story = {
args: {
children: 'View in ClickHouse',
href: 'https://clickhouse.com',
target: '_blank',
icon: 'popout',
},
};

export const InErrorMessage: Story = {
render: () => (

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Stack gap="xs" in InErrorMessage wraps a single child, so the gap never applies

Remove the Stack and the @mantine/core import and render the click-ui <Text> directly. That also drops the Mantine/click-ui mix that the new code_style section tells people to avoid in small components.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

<Stack gap="xs">
<Text>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — InErrorMessage story uses click-ui Text inside a Mantine Stack, which doesn't match real usage and breaks the doc's own 'don't mix libraries' rule

In production, ContactSupportText renders inside a Mantine notifications.show message (DBSearchPage.tsx:1621, DBDashboardPage.tsx:2833). Render the story inside a Mantine Notification color="red" instead, so it actually catches the font/color regression the new .inlineLink stylesheet is meant to prevent.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

An error occurred. <ContactSupportText />
</Text>
Comment on lines +52 to +55

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Mixed UI libraries The new InErrorMessage story nests click-ui’s Text inside Mantine’s Stack. The repository’s Click UI guidance says not to mix the two libraries inside one small component. This requirement must be satisfied before merging.

Context Used: AGENTS.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

</Stack>
),
};
Loading
Loading