Add query syntax reference to search input - #2381

⚠️ No Changeset found

Latest commit: f0ef250

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

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

@vinzee is attempting to deploy a commit to the HyperDX Team on Vercel.

A member of the Team first needs to authorize it.

Deep Review

✅ No critical issues found. This is a self-contained, read-only display feature (a syntax reference modal) with no backend, auth, data-mutation, or network-write surface. No P0/P1 issues. The items below are recommendations and nits.

🟡 P2 -- recommended

• packages/app/src/components/SearchInput/SyntaxReferenceModal.tsx:180 -- New 350-line component ships with zero tests; the pure helpers filterSections and Highlight and the modal open/close, language-toggle, and filter-reset behavior are entirely unverified despite the repo's strong colocated-test convention.
  • Fix: Add SearchInput/__tests__/SyntaxReferenceModal.test.tsx covering filterSections (empty/whitespace query, expr-only match, desc-only match, no-match empty state, case-insensitivity), Highlight mark rendering, and the ActionIcon-opens-modal wiring in SearchWhereInput.
  • _{testing, maintainability, kieran-typescript, project-standards}
• packages/app/src/components/SearchInput/SyntaxReferenceModal.tsx:1 -- User-facing change to the published @hyperdx/app package has no changeset, which AGENTS.md PR Hygiene requires before merge.
  • Fix: Run yarn changeset and add an entry describing the new search syntax reference modal.
• packages/app/src/components/SearchInput/SyntaxReferenceModal.tsx:350 -- File is 350 lines, exceeding the documented 300-line max in agent_docs/code_style.md.
  • Fix: Extract SQL_SECTIONS/LUCENE_SECTIONS into a sibling constants module and/or move SyntaxTable/Highlight into their own file.

Reviewers (9): correctness, kieran-typescript, julik-frontend-races, maintainability, testing, project-standards, adversarial, agent-native, learnings-researcher.

Testing gaps:

• No tests added for the new SyntaxReferenceModal (helpers filterSections/Highlight, language-tab reset on reopen, query reset on close/toggle, empty-filter state).
• No test extends the existing SearchWhereInput.test.tsx to cover the new help-icon-opens-modal interaction.

Greptile Summary

This PR adds a query syntax reference modal accessible via a help icon next to the language selector in SearchWhereInput. Users can browse SQL and Lucene example queries, filter them with a text input, and follow an external link to the full ClickStack documentation.

• SyntaxReferenceModal.tsx is a new self-contained component with static SQL_SECTIONS / LUCENE_SECTIONS data, a filterSections helper, and a Highlight sub-component for match display.
• SearchWhereInput.tsx gains a useDisclosure hook, an ActionIcon help button in the language-switch row, and renders the modal as a Fragment sibling to the existing Box.

Confidence Score: 5/5

Safe to merge — the change is purely additive UI with no mutations to existing query or data-fetching logic.

Both files are self-contained UI additions. The modal manages its own local state cleanly, the static reference data is read-only, and the integration in SearchWhereInput is a minimal wrapper change that does not alter any existing behaviour.

No files require special attention.

Important Files Changed

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant U as User
    participant SWI as SearchWhereInput
    participant SRM as SyntaxReferenceModal

    U->>SWI: Click help icon (IconHelp)
    SWI->>SWI: "openSyntaxRef() → syntaxRefOpened = true"
    SWI->>SRM: "opened=true, language, onClose=closeSyntaxRef"
    SRM->>SRM: useEffect: setLanguage(initialLanguage)
    SRM->>U: Render modal with SegmentedControl + filter input (autoFocus)

    U->>SRM: Type in filter input
    SRM->>SRM: setQuery(value) → filterSections() → Highlight matches

    U->>SRM: Switch language tab (SegmentedControl)
    SRM->>SRM: setLanguage(newLang) + setQuery('')

    U->>SRM: Close modal (Escape / backdrop / X)
    SRM->>SRM: setQuery('') then onClose()
    SRM->>SWI: "closeSyntaxRef() → syntaxRefOpened = false"
    SWI->>U: Modal unmounted

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant U as User
    participant SWI as SearchWhereInput
    participant SRM as SyntaxReferenceModal

    U->>SWI: Click help icon (IconHelp)
    SWI->>SWI: "openSyntaxRef() → syntaxRefOpened = true"
    SWI->>SRM: "opened=true, language, onClose=closeSyntaxRef"
    SRM->>SRM: useEffect: setLanguage(initialLanguage)
    SRM->>U: Render modal with SegmentedControl + filter input (autoFocus)

    U->>SRM: Type in filter input
    SRM->>SRM: setQuery(value) → filterSections() → Highlight matches

    U->>SRM: Switch language tab (SegmentedControl)
    SRM->>SRM: setLanguage(newLang) + setQuery('')

    U->>SRM: Close modal (Escape / backdrop / X)
    SRM->>SRM: setQuery('') then onClose()
    SRM->>SWI: "closeSyntaxRef() → syntaxRefOpened = false"
    SWI->>U: Modal unmounted

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into va/syntax_guide" | Re-trigger Greptile}