Skip to content

[docs-utils] 4️⃣ Complete ReactElement signature fix#250814

Merged
clintandrewhall merged 2 commits intoelastic:mainfrom
clintandrewhall:feat/docs-utils/4-react-element
Feb 10, 2026
Merged

[docs-utils] 4️⃣ Complete ReactElement signature fix#250814
clintandrewhall merged 2 commits intoelastic:mainfrom
clintandrewhall:feat/docs-utils/4-react-element

Conversation

@clintandrewhall
Copy link
Copy Markdown
Contributor

@clintandrewhall clintandrewhall commented Jan 28, 2026

Summary

Fixes #120125 by normalizing ReactElement signatures in generated API documentation.

ReactElement types were expanding to include verbose second generic parameters like ReactElement<MyProps, string | React.JSXElementConstructor<any>>, making documentation difficult to read. This PR adds a normalizeReactElementSignature helper that strips the redundant second generic while preserving the meaningful first type parameter.

Note

This PR is a subset of #247688 for ease of review.

This PR was written with Cursor and claude-4.5-opus-high.

Important

This PR relies on #250810 and includes it as its base commit. This PR will remain draft until that PR is merged and this branch is rebased.

Before / After Example

Given this TypeScript type:

export interface MyProps {
  title: string;
}

export type AReactElementFn = () => ReactElement<MyProps>;

Before this PR:

The generated API docs expanded to verbose, hard-to-read signatures:

{
  "label": "AReactElementFn",
  "signature": [
    "() => React.ReactElement<",
    { "pluginId": "pluginA", "section": "def-public.MyProps", "text": "MyProps" },
    ", string | React.JSXElementConstructor<any>>"  // <-- Verbose noise!
  ]
}

This rendered in the docs as:

() => React.ReactElement<MyProps, string | React.JSXElementConstructor<any>>

After this PR:

The redundant second generic is stripped for cleaner output:

{
  "label": "AReactElementFn",
  "signature": [
    "() => React.ReactElement<",
    { "pluginId": "pluginA", "section": "def-public.MyProps", "text": "MyProps" },
    ">"  // ✅ Clean!
  ]
}

This now renders in the docs as:

() => React.ReactElement<MyProps>

Why This Matters

The second generic parameter of ReactElement (string | React.JSXElementConstructor<any>) is a TypeScript implementation detail that:

  • Provides no useful information to API consumers
  • Clutters the documentation with boilerplate
  • Makes signatures harder to scan and understand

Changes

  • Add normalizeReactElementSignature() in get_signature.ts to clean up ReactElement output before reference extraction
  • Re-enable the previously skipped Test ReactElement signature test
  • Update integration test snapshots to reflect the normalized signatures

@clintandrewhall clintandrewhall added review Team:Operations Kibana-Operations Team release_note:skip Skip the PR/issue when compiling release notes backport:skip This PR does not require backporting v9.4.0 labels Jan 28, 2026
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR normalizes ReactElement type signatures in generated API documentation by removing the verbose second generic parameter (string | React.JSXElementConstructor<any>) while preserving the meaningful first type parameter. This makes the documentation more readable without losing important type information.

Changes:

  • Added normalizeReactElementSignature() helper function in get_signature.ts to clean up ReactElement signatures
  • Introduced IssuesByPlugin interface to group issue-related parameters and refactored collectApiStatsForPlugin() to accept a single issues object instead of three separate parameters
  • Re-enabled the previously skipped Test ReactElement signature test and updated integration test snapshots to reflect the normalized output

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file
File Description
packages/kbn-docs-utils/src/types.ts Added IssuesByPlugin interface to bundle issue-related data structures
packages/kbn-docs-utils/src/stats.ts Refactored collectApiStatsForPlugin() to accept IssuesByPlugin parameter and added JSDoc comment
packages/kbn-docs-utils/src/stats.test.ts Updated all test calls to use the new IssuesByPlugin parameter format and added createEmptyIssues() helper
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_b.mdx Updated date metadata in snapshot
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a_foo.mdx Updated date metadata in snapshot
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.mdx Updated date metadata in snapshot
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.devdocs.json Updated ReactElement signature to normalized format in JSON snapshot
packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts Updated test expectations to match normalized ReactElement signature and refactored test setup calls
packages/kbn-docs-utils/src/cli/tasks/collect_stats.ts Updated function call to use new IssuesByPlugin parameter format
packages/kbn-docs-utils/src/build_api_declarations/get_signature.ts Added normalizeReactElementSignature() function that strips verbose second generic from ReactElement types
packages/kbn-docs-utils/src/build_api_declarations/build_api_declaration.test.ts Re-enabled previously skipped Test ReactElement signature test
packages/kbn-docs-utils/src/README.md Improved formatting and documentation structure with clearer section headers and validation rules

@clintandrewhall clintandrewhall changed the title [docs-utils] Complete ReactElement signature fix [docs-utils] 4️⃣ Complete ReactElement signature fix Jan 29, 2026
Copy link
Copy Markdown
Contributor

@mistic mistic left a comment

Choose a reason for hiding this comment

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

just a small comment. There are things from the pre-req PR that I haven't looked at because they will disappear once we merge it. LGTM

@clintandrewhall clintandrewhall marked this pull request as ready for review February 4, 2026 21:21
@clintandrewhall clintandrewhall requested a review from a team as a code owner February 4, 2026 21:21
@elasticmachine
Copy link
Copy Markdown
Contributor

Pinging @elastic/kibana-operations (Team:Operations)

- Implement handling for ReactElement signatures.
- Unskip and fix Test ReactElement signature test.
@clintandrewhall clintandrewhall force-pushed the feat/docs-utils/4-react-element branch from 1e531c2 to 9777309 Compare February 10, 2026 20:21
@clintandrewhall clintandrewhall enabled auto-merge (squash) February 10, 2026 20:22
@clintandrewhall clintandrewhall merged commit 0fa4322 into elastic:main Feb 10, 2026
16 checks passed
@clintandrewhall clintandrewhall deleted the feat/docs-utils/4-react-element branch February 10, 2026 21:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport:skip This PR does not require backporting release_note:skip Skip the PR/issue when compiling release notes review Team:Operations Kibana-Operations Team v9.4.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[docs-utils/api_docs] failing test with TS upgrade

4 participants