Reviewing files that changed from the base of the PR and between a48d2b1 and 304ee44.

• .github/workflows/ci.yml (1 hunks)
• omnidoc/componentsAndDefaultPropsMap.ts (1 hunks)
• omnidoc/componentsWithInconsistentCommentsInApiDoc.ts (1 hunks)
• omnidoc/cross-component-prop-comments.spec.ts (3 hunks)
• omnidoc/generateApiDoc.ts (5 hunks)
• omnidoc/omnidoc.spec.ts (3 hunks)
• omnidoc/readProject.spec.ts (2 hunks)
• src/cartesian/Area.tsx (1 hunks)
• src/cartesian/Bar.tsx (1 hunks)
• src/cartesian/Line.tsx (1 hunks)
• src/cartesian/Scatter.tsx (3 hunks)
• src/chart/PieChart.tsx (1 hunks)
• src/chart/RechartsWrapper.tsx (1 hunks)
• src/chart/SunburstChart.tsx (2 hunks)
• src/chart/types.ts (1 hunks)
• src/component/Customized.tsx (1 hunks)
• src/component/DefaultLegendContent.tsx (3 hunks)
• src/component/Label.tsx (2 hunks)
• src/component/LabelList.tsx (2 hunks)
• src/component/Legend.tsx (4 hunks)
• src/component/Tooltip.tsx (1 hunks)
• src/polar/Pie.tsx (3 hunks)
• src/polar/PolarAngleAxis.tsx (1 hunks)
• src/polar/PolarGrid.tsx (1 hunks)
• src/polar/PolarRadiusAxis.tsx (1 hunks)
• src/polar/Radar.tsx (1 hunks)
• src/polar/RadialBar.tsx (1 hunks)
• src/util/types.ts (2 hunks)
• storybook/stories/API/props/LabelListProps.ts (0 hunks)
• test/component/Legend.itemSorter.spec.tsx (2 hunks)
• test/component/Legend.spec.tsx (2 hunks)
• www/src/docs/api/AreaAPI.tsx (1 hunks)
• www/src/docs/api/Customized.ts (0 hunks)
• www/src/docs/api/CustomizedAPI.tsx (1 hunks)
• www/src/docs/api/LabelAPI.tsx (2 hunks)
• www/src/docs/api/LabelList.ts (0 hunks)
• www/src/docs/api/LabelListAPI.tsx (1 hunks)
• www/src/docs/api/Legend.ts (0 hunks)
• www/src/docs/api/LegendAPI.tsx (1 hunks)
• www/src/docs/api/LineAPI.tsx (1 hunks)
• www/src/docs/api/Pie.ts (0 hunks)
• www/src/docs/api/PieAPI.tsx (1 hunks)
• www/src/docs/api/PieChart.ts (0 hunks)
• www/src/docs/api/PieChartAPI.tsx (1 hunks)
• www/src/docs/api/ScatterAPI.tsx (3 hunks)
• www/src/docs/api/TextAPI.tsx (1 hunks)
• www/src/docs/api/index.ts (4 hunks)
• www/src/docs/api/types.ts (2 hunks)
• www/src/views/APIViewNew.tsx (2 hunks)

• www/src/docs/api/PieChart.ts
• www/src/docs/api/Customized.ts
• www/src/docs/api/LabelList.ts
• storybook/stories/API/props/LabelListProps.ts
• www/src/docs/api/Pie.ts
• www/src/docs/api/Legend.ts

• GitHub Check: Build, Test, Pack
• GitHub Check: Analyze (javascript-typescript)

src/component/Tooltip.tsx (1)

182-185: LGTM! Documentation enhancement aligns with PR objectives.

The JSDoc annotation clearly documents the contexts consumed by this component, improving code maintainability and developer experience.

src/chart/SunburstChart.tsx (2)

86-89: LGTM! Consistent JSDoc formatting.

The added space before the closing */ improves consistency with standard JSDoc formatting conventions.

---

367-376: LGTM! Valid refactor removing unnecessary fragment.

The React fragment wrapper is unnecessary here since Surface already accepts multiple children (alongside Layer at line 366). Removing it simplifies the component structure without any functional impact.

.github/workflows/ci.yml (1)

201-206: Configuration is correct and fully compatible.

pnpm version 10.x requires Node.js at least v18.12, and the workflow uses Node.js 24.x, which exceeds this requirement. pnpm v10.24.0 is the latest stable release, and the combination has no known compatibility issues. The pnpm installation step is well-positioned, correctly configured with caching, and ready to proceed.

src/polar/PolarGrid.tsx (1)

165-168: LGTM!

The @consumes PolarViewBoxContext annotation accurately documents the component's dependency on the polar view box context, as evidenced by the useAppSelector(selectPolarViewBox) call at line 181. This aligns with the pattern being applied across other polar components in this PR.

src/polar/PolarRadiusAxis.tsx (1)

238-241: LGTM!

The @consumes PolarViewBoxContext annotation correctly documents that this component depends on the polar view box context. The actual consumption happens in PolarRadiusAxisWrapper via useAppSelector(selectPolarViewBox) at line 208, and documenting it on the public export is the appropriate approach.

src/cartesian/Scatter.tsx (3)

209-226: LGTM!

The documentation for the line prop is clear and comprehensive, with good examples and cross-references to the lineType prop and external documentation.

---

268-275: LGTM!

The enhanced description for activeShape now clearly explains the various activation triggers (mouse hover, touch, keyboard, programmatic), which improves API documentation clarity.

---

289-299: LGTM!

The new public hide prop is well-documented with clear explanation of its behavior regarding Legend visibility and axis domain calculations. The documentation is consistent with the same prop added to Area.tsx and aligns with the existing internal handling at line 152.

src/cartesian/Area.tsx (1)

196-206: LGTM!

The new public hide prop is properly documented with a clear explanation of the difference between hiding and removing an element. The documentation is consistent with the same prop added to Scatter.tsx, and the prop correctly defaults to false as defined in defaultAreaProps at line 855. The existing internal handling at line 794 already respects this prop.

src/polar/RadialBar.tsx (1)

658-661: LGTM!

The JSDoc annotations accurately document the context relationships. RadialBar provides LabelListContext via PolarLabelListContextProvider and consumes polar chart context through Redux selectors.

src/polar/Radar.tsx (1)

572-575: LGTM!

The JSDoc accurately documents the context relationships. Note that Radar provides CartesianLabelListContext (not PolarLabelListContext), but using the generic term "LabelListContext" appropriately abstracts this implementation detail.

src/cartesian/Bar.tsx (1)

180-188: LGTM!

The enhanced documentation clearly explains the difference between hiding and removing elements, and appropriately references the includeHidden prop for axis domain calculations. This is helpful for users understanding the behavior.

src/component/LabelList.tsx (2)

82-86: LGTM!

The documentation improvement clarifies that the content function is called once per item, which is helpful for understanding the rendering behavior.

---

111-121: Documentation is correct—no changes needed.

The documented default value of 2000 matches DefaultZIndexes.label, which is set to 2000 in src/zIndex/DefaultZIndexes.tsx line 80 and used as the default in LabelList.tsx line 179.

omnidoc/componentsAndDefaultPropsMap.ts (1)

52-52: The mapping of LabelList to defaultLabelProps is correct and intentional. LabelList accepts the same props as Label (angle, offset, position, textBreakAll, zIndex) and shares the same default values. The LabelList component internally manages how these defaults are applied—it wraps its content in a ZIndexLayer using the provided zIndex, then renders individual Label components with zIndex={0} to avoid portaling. No separate defaultLabelListProps is needed.

src/component/Label.tsx (1)

85-87: Formatter and zIndex docs look good; please verify default consistency

The new formatter description matches the existing getLabel behavior, and the expanded zIndex block correctly explains layering and portal behavior for Label. The only thing to double‑check is that DefaultZIndexes.label really is 2000, so the documented @defaultValue 2000 stays in sync with the actual default.

Also applies to: 138-147

www/src/docs/api/ScatterAPI.tsx (3)

13-16: Clarified activeShape activation description

The updated activeShape description correctly captures the various activation mechanisms (hover, touch, keyboard, programmatic) and matches how Scatter behaves in charts.

---

95-112: hide prop documentation matches component semantics

The new hide prop entry clearly explains that it hides the graphical element while keeping it in the Legend and (optionally) axis domain calculations via includeHidden on axes. This aligns well with the broader hide semantics used across components.

---

196-196: Minor copy fix for line prop description

Changing “Options"” to “Options:” improves readability and avoids the stray quote; no further changes needed.

src/polar/PolarAngleAxis.tsx (1)

325-327: Context-consumption annotation is accurate

The @consumes PolarViewBoxContext JSDoc accurately reflects that PolarAngleAxis depends on the polar view box from shared state/context, and brings this file in line with other annotated components.

src/chart/RechartsWrapper.tsx (1)

31-52: Simplified RechartsWrapperProps to extend ExternalMouseEvents directly

Using ExternalMouseEvents & { ... } now relies on the handlers being optional in ExternalMouseEvents, which matches the implementation and removes the extra Nullable<> indirection. This keeps the public prop type accurate without changing runtime behavior.

src/cartesian/Line.tsx (1)

196-203: hide JSDoc now accurately reflects legend and axis behavior

The expanded hide documentation matches how Line behaves: the graphical element is not rendered when hide is true, yet the legend entry remains (marked inactive) and axis-domain participation is controlled via includeHidden on X/Y axes. No code changes needed.

test/component/Legend.spec.tsx (1)

435-512: Tests correctly assert inactiveColor in Legend content props

Updating the expectations to include inactiveColor: '#ccc' in the arguments passed to function/Component content ensures the new Legend default is covered and that custom content can rely on this prop being present. The rest of the payload shape is unchanged.

Also applies to: 780-858

test/component/Legend.itemSorter.spec.tsx (1)

58-137: Legend.itemSorter tests now cover inactiveColor in content props

Including inactiveColor: '#ccc' in the expected Legend content props for both default sorting and itemSorter="dataKey" keeps these tests aligned with the new Legend default props and validates that custom content receives the inactive color as part of its inputs.

Also applies to: 152-232

www/src/docs/api/LineAPI.tsx (1)

146-151: Expanded Line.hide API docs align with component behavior

The updated hide description on the Line API page matches the JSDoc in Line.tsx and correctly explains Legend visibility and axis-domain implications via includeHidden on axes. This keeps the public docs consistent with runtime semantics.

www/src/docs/api/types.ts (1)

18-18: LGTM! Type extension supports richer deprecation metadata.

The change from boolean to boolean | string is backward compatible and enables deprecation messages with explanatory text. The implementation in www/src/views/APIViewNew.tsx correctly handles both types using typeof checks.

Also applies to: 27-27

src/chart/PieChart.tsx (1)

19-19: Good addition for API documentation clarity.

The @provides PolarChartContext annotation documents the context relationship, improving the generated API docs and helping developers understand component context consumption/provision patterns.

omnidoc/readProject.spec.ts (2)

19-19: LGTM! Correctly includes newly documented component.

Adding 'Customized' to the expected components list aligns with the PR's objective to document this component, even though it's deprecated.

---

1006-1030: Comprehensive test coverage for new deprecation features.

The new tests appropriately verify:

• Component-level JSDoc and deprecation metadata reading
• Prop-level deprecation tag handling
• Correct primitive default value processing (without string wrappers)

The tests are well-structured and align with the expanded API documentation surface.

www/src/views/APIViewNew.tsx (2)

60-64: Prop deprecation message rendering is correct.

The type guard correctly checks for string deprecation values. Note that when deprecated is true (boolean), only the @deprecated label is shown (line 58) without an explanatory message. This is a reasonable design choice since the boolean form typically indicates "check the docs" rather than providing inline explanation.

---

209-213: Component deprecation notice correctly handles both boolean and string types.

The implementation properly:

• Checks for any truthy deprecated value
• Provides a fallback message when deprecated === true
• Uses the custom deprecation message when it's a string

www/src/docs/api/AreaAPI.tsx (1)

139-156: Excellent documentation for the hide prop.

The description clearly explains:

• What hiding does (hides graphical element)
• Important nuances (still visible in Legend)
• Related functionality (includeHidden on axes)

This will help developers understand the distinction between hiding and removing elements.

omnidoc/cross-component-prop-comments.spec.ts (4)

51-51: Appropriate exception for Legend's height/width props.

Legend's height and width refer to the legend container dimensions, which have different semantics than chart dimensions. This exception prevents false positives in cross-component consistency checks.

Also applies to: 56-56

---

75-79: Correct exception for Legend's layout prop.

Legend's layout prop controls internal item arrangement (horizontal/vertical), which differs semantically from chart layout props. The exception is well-justified.

---

121-125: Valid exceptions for Pie component's unique props.

Both exceptions are justified:

• Pie's label implementation is unique due to arc positioning requirements
• Pie's shape receives activeIndex for active slice highlighting, unlike other components

Also applies to: 137-140

---

127-135: Well-justified exceptions for cx/cy and content props.

Both exceptions document genuine behavioral differences:

• Dot and SunburstChart's cx/cy don't support percentage values (unlike other components)
• Label's content function is called once per Label (not once per data point like other components)

Also applies to: 142-145

www/src/docs/api/LegendAPI.tsx (3)

3-31: Well-structured Legend API documentation.

The align prop documentation is particularly clear, explaining:

• Each alignment option's behavior
• How it affects chart dimensions
• Interaction with verticalAlign prop

This follows best practices for API documentation.

---

34-65: Good documentation with helpful examples.

The content and formatter props are clearly explained with practical examples. The CodeSandbox link in the formatter's format field provides valuable interactive documentation.

---

117-134: Excellent itemSorter documentation with important behavioral note.

The documentation clearly explains:

• Default sorting behavior (by value/label)
• Custom sorting options (dataKey, value, or function)
• Critical warning about using null and potential render order instability

The parentComponents list appropriately includes all chart types that support Legend.

Also applies to: 419-419

omnidoc/omnidoc.spec.ts (1)

20-25: LGTM! Smart test optimization.

Filtering auto-generated components from consistency tests makes sense since they're generated directly from the project source and are guaranteed to match. This reduces test noise while maintaining coverage for manually maintained API docs.

Also applies to: 68-73, 176-182

www/src/docs/api/CustomizedAPI.tsx (1)

3-32: LGTM! Clear deprecation documentation.

The API documentation for the deprecated Customized component is well-structured with:

• Clear migration guidance (Before/After examples)
• Consistent deprecation messages at both prop and component levels
• Explicit mention of removal timeline (version 4.0)

www/src/docs/api/LabelAPI.tsx (1)

144-161: LGTM! Comprehensive zIndex documentation.

The new zIndex prop is well-documented with:

• Clear description of behavior and rendering order
• Appropriate default value (2000)
• Link to the zIndex guide for further reference

src/component/Customized.tsx (1)

12-17: LGTM! Consistent deprecation documentation.

The JSDoc deprecation tags are well-written with:

• Clear explanation of why the component is no longer needed
• Before/After migration examples
• Explicit deprecation timeline (removal in 4.0)

This aligns perfectly with the API documentation in CustomizedAPI.tsx.

Also applies to: 22-29

www/src/docs/api/PieChartAPI.tsx (1)

3-277: LGTM! Comprehensive PieChart API documentation.

The API documentation is thorough and well-structured with:

• Complete prop coverage including data, dimensions, margins, and event handlers
• Detailed descriptions for key props (data, height, width, responsive, syncId, syncMethod)
• Appropriate default values specified
• Correct parent-child component relationships documented

www/src/docs/api/LabelListAPI.tsx (1)

3-165: LGTM! Well-documented LabelList API.

The API documentation is comprehensive with:

• Detailed descriptions for key props (dataKey, content, valueAccessor)
• Clear explanation of prop interactions (e.g., dataKey vs valueAccessor)
• Consistent zIndex documentation matching Label component
• Accurate parent component relationships

www/src/docs/api/PieAPI.tsx (3)

7-25: Good: activeShape deprecation is clearly documented.

The deprecation message provides clear migration guidance to use the shape prop with isActive instead.

---

150-167: Excellent hide prop documentation.

The description clearly explains the difference between hiding an element (still in Legend, can affect axis domain) versus removing it entirely. This nuance is important for users to understand.

---

3-673: LGTM! Comprehensive Pie API documentation.

The API documentation is thorough with:

• Complete prop coverage including shape, data, angles, radii, labels, and extensive event handlers
• Clear deprecation guidance for activeShape and inactiveShape
• Detailed descriptions for complex props (label, labelLine, hide)
• Accurate parent-child component relationships

omnidoc/generateApiDoc.ts (3)

24-39: LGTM! Expanded automated component list.

The addition of Customized, LabelList, Legend, Pie, and PieChart to the automated generation list aligns with the PR objectives.

---

243-266: Excellent deprecation extraction logic.

The implementation correctly:

• Prefers deprecation metadata from recharts-origin props over DOM/inherited props
• Falls back to checking all prop metadata sources if needed
• Returns the deprecation text if available, or true if only the tag exists

This ensures accurate deprecation information even for props that may be inherited or overridden.

---

356-359: LGTM! Complete deprecation support.

The implementation properly handles deprecation at both levels:

• Component-level: extracted from component JSDoc and included in ApiDoc
• Prop-level: extracted from prop JSDoc and included in ApiProps
• Both are correctly serialized to the generated output

The type safety is maintained with explicit string | boolean | undefined typing.

Also applies to: 431-433, 456-458

src/util/types.ts (1)

1143-1200: Good consolidation of shared chart props into BaseChartProps.

This refactoring eliminates duplication between CartesianChartProps and PolarChartProps by extracting common properties into a shared base interface. The JSDoc documentation is thorough and helpful.

Also applies to: 1202-1202, 1257-1257

src/component/Legend.tsx (2)

96-145: Well-documented Props type with clear JSDoc annotations.

The Props type correctly omits verticalAlign from DefaultLegendContentProps to re-declare it with a different default value (bottom vs middle). The JSDoc documentation clearly explains the behavior of each alignment option.

---

186-198: LGTM!

The inactiveColor default is consistent with DefaultLegendContent, and the @consumes annotations provide useful metadata for documentation generation.

www/src/docs/api/index.ts (1)

56-111: LGTM!

The export mappings correctly wire the new API documentation modules for PieChart, Legend, LabelList, Customized, and Pie.

src/component/DefaultLegendContent.tsx (2)

44-120: Comprehensive JSDoc documentation for DefaultLegendContentProps.

The documentation clearly explains each prop's purpose, includes practical examples, and links to external demos. The @defaultValue annotations properly match the actual defaults in defaultLegendContentDefaultProps.

---

137-154: LGTM!

The iconType parameter correctly uses LegendType | undefined, and the component properly handles the 'none' case at line 152-154 after the nullish coalescing fallback.

src/chart/types.ts (1)

8-53: LGTM - Making event handlers optional aligns with practical usage.

All event handlers in ExternalMouseEvents are now optional, which matches how users actually consume the API (providing only the handlers they need). This is a backward-compatible relaxation of the type constraint.

src/polar/Pie.tsx (3)

68-103: LGTM! Excellent documentation for PieDef properties.

The TSDoc comments clearly explain each property's purpose, including how percentage values are calculated and providing helpful examples with links.

---

287-310: Excellent comprehensive documentation for label and labelLine props.

The documentation thoroughly explains the different ways to use these props (boolean, object, ReactElement, function), provides clear examples, and links to live demonstrations. This will greatly improve the developer experience.

---

995-998: LGTM! Clear context consumption and provision annotations.

The @consumes and @provides annotations clearly document the component's context dependencies and what it provides to child components. This aligns with the implementation where PolarLabelListContextProvider is used (lines 816-819).