Charts: Document animation feature across all supported charts (#46326)

* Charts: Document animation feature across all supported charts

- Update documentation guidelines and template with animation section
- Add animation documentation to all chart types with animation support
- Include animation prop in API reference docs for all applicable charts
- Document radial wipe, rising, and stretching animation effects
- Note accessibility support for prefers-reduced-motion

* Charts: Add changelog

Author: halfo

projects/js-packages/charts/changelog/update-charts-137-document-animation-feature

@@ -0,0 +1,4 @@
+Significance: patch
+Type: fixed
+
+Charts: Add documentation and API references of animation feature.

projects/js-packages/charts/docs/ai-documentation-guide.md

@@ -183,6 +183,23 @@ For the Theming Integration section, use the standardized format from the `featu
 - A code example showing how to wrap the chart in `GlobalChartsProvider` with a custom theme
 
 See the template for the complete section structure.
+
+## Animation
+
+Only include this section if the chart component supports animation (check the implementation for an `animation` prop). If animation is not supported, remove this section entirely.
+
+When documenting animation:
+
+- Show the Animation story with a Canvas example
+- Include a basic code example with `animation={true}`
+- Document animation behavior in a bulleted list covering:
+  - Opt-in nature (disabled by default)
+  - Accessibility (respects `prefers-reduced-motion`)
+  - Effect description (e.g., "radial wipe reveal effect")
+  - Duration in milliseconds
+- Note that animation plays once on initial render and does not repeat
+
+See the `feature-documentation.mdx.template` for the complete section structure.
 ```
 
 ### 8. Advanced Usage
@@ -319,6 +336,7 @@ Before considering documentation complete, verify both main docs and API referen
 - [ ] Visual examples for all major variations in main docs
 - [ ] Code examples are complete and runnable in main docs
 - [ ] Accessibility considerations covered in main docs
+- [ ] Animation section included if chart supports animation (check for `animation` prop)
 - [ ] Browser compatibility notes included where relevant
 - [ ] Both documents created using appropriate templates
 

projects/js-packages/charts/docs/feature-documentation.mdx.template

@@ -151,6 +151,31 @@ Controls [what this affects]:
 	</GlobalChartsProvider>` }
 />
 
+## Animation
+
+[Only include this section if the chart component supports animation. Remove this section entirely if animation is not supported.]
+
+The [Component] component supports an optional entry animation that creates a smooth reveal effect when the chart first renders:
+
+<Canvas of={ [FeatureName]Stories.Animation } />
+
+<Source
+	language="tsx"
+	code={ `<[Component]
+		data={ data }
+		animation={ true }
+	/>` }
+/>
+
+### Animation Behavior
+
+- **Opt-in**: Animation is disabled by default and must be explicitly enabled with the `animation` prop
+- **Accessibility**: Automatically respects the user's `prefers-reduced-motion` system setting - animation will not play for users who prefer reduced motion
+- **Effect**: Creates a [describe the animation effect, e.g., "radial wipe reveal effect" for pie charts, or the specific animation type for the chart]
+- **Duration**: [Animation duration in milliseconds, e.g., "1000ms (1 second)"]
+
+**Note**: The animation plays once when the chart initially renders and does not repeat.
+
 ## Custom [Feature Name]
 
 ### Custom [Aspect] Rendering

projects/js-packages/charts/src/charts/bar-chart/stories/index.api.mdx

@@ -19,6 +19,7 @@ Main chart component with responsive behavior by default.
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Bar orientation |
 | `withTooltips` | `boolean` | `false` | Enable interactive tooltips |
 | `withPatterns` | `boolean` | `false` | Use pattern fills for accessibility |
+| `animation` | `boolean` | `false` | Enable entry animation on initial render. Vertical bars rise from the bottom; horizontal bars stretch from the left. Automatically respects user's `prefers-reduced-motion` system setting |
 | `showZeroValues` | `boolean` | `false` | Display zero values with minimum visual height |
 | `showLegend` | `boolean` | `false` | Display chart legend |
 | `legendOrientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Legend layout orientation |

projects/js-packages/charts/src/charts/bar-chart/stories/index.docs.mdx

@@ -554,3 +554,28 @@ Bar Charts integrate seamlessly with the chart theming system. The default theme
 		<BarChart data={data} />
 	</GlobalChartsProvider>` }
 />
+
+## Animation
+
+The Bar Chart component supports an optional entry animation that creates a smooth reveal effect when the chart first renders:
+
+<Canvas of={ BarChartStories.Animation } />
+
+<Source
+	language="tsx"
+	code={ `<BarChart
+		data={ data }
+		width={ 800 }
+		height={ 400 }
+		animation={ true }
+	/>` }
+/>
+
+### Animation Behavior
+
+- **Opt-in**: Animation is disabled by default and must be explicitly enabled with the `animation` prop
+- **Accessibility**: Automatically respects the user's `prefers-reduced-motion` system setting - animation will not play for users who prefer reduced motion
+- **Effect**: Creates a growing effect where bars scale from zero to their full size. Vertical bars rise from the bottom, while horizontal bars stretch from the left
+- **Duration**: 1000ms (1 second) with ease-out timing
+
+**Note**: The animation plays once when the chart initially renders and does not repeat.

projects/js-packages/charts/src/charts/bar-list-chart/stories/index.api.mdx

@@ -17,6 +17,7 @@ A horizontal bar chart component optimized for list-style data presentation.
 | `height` | `number` | `400` | Chart height in pixels |
 | `margin` | `ChartMargin` | `{ left: 0, right: 20, bottom: 0, top: 0 }` | Chart margins |
 | `withTooltips` | `boolean` | `false` | Enable interactive tooltips |
+| `animation` | `boolean` | `false` | Enable entry animation on initial render. Bars stretch from left to right. Automatically respects user's `prefers-reduced-motion` system setting |
 | `renderTooltip` | `Function` | - | Custom tooltip render function |
 | `options` | `BarListChartOptions` | `{}` | Chart configuration options |
 

projects/js-packages/charts/src/charts/bar-list-chart/stories/index.docs.mdx

@@ -270,6 +270,29 @@ Bar List Charts integrate seamlessly with the chart theming system. The default
 	</GlobalChartsProvider>` }
 />
 
+## Animation
+
+The Bar List Chart component supports an optional entry animation that creates a smooth reveal effect when the chart first renders:
+
+<Canvas of={ BarListChartStories.Animation } />
+
+<Source
+	language="tsx"
+	code={ `<BarListChart
+		data={ data }
+		animation={ true }
+	/>` }
+/>
+
+### Animation Behavior
+
+- **Opt-in**: Animation is disabled by default and must be explicitly enabled with the `animation` prop
+- **Accessibility**: Automatically respects the user's `prefers-reduced-motion` system setting - animation will not play for users who prefer reduced motion
+- **Effect**: Creates a stretching effect where bars grow from left to right, revealing the data progressively
+- **Duration**: 1000ms (1 second) with ease-out timing
+
+**Note**: The animation plays once when the chart initially renders and does not repeat.
+
 ## Advanced Features
 
 ### Scale Configuration

projects/js-packages/charts/src/charts/conversion-funnel-chart/stories/index.api.mdx

@@ -16,6 +16,7 @@ Main component for displaying conversion funnel visualizations.
 | `steps` | `FunnelStep[]` | - | **Required.** Array of funnel steps |
 | `changeIndicator` | `string` | - | Change indicator (e.g., "+2%", "-1.5%") |
 | `loading` | `boolean` | `false` | Whether the chart is in loading state |
+| `animation` | `boolean` | `false` | Enable entry animation on initial render. Funnel bars grow from bottom to full height. Automatically respects user's `prefers-reduced-motion` system setting |
 | `className` | `string` | - | Additional CSS class name |
 | `chartId` | `string` | - | Optional unique identifier for the chart |
 | `style` | `React.CSSProperties` | - | Custom styling for the chart container |

projects/js-packages/charts/src/charts/conversion-funnel-chart/stories/index.docs.mdx

@@ -262,6 +262,30 @@ Use the `style` prop or `className` prop for custom styling:
 	/>` }
 />
 
+## Animation
+
+The Conversion Funnel Chart component supports an optional entry animation that creates a smooth reveal effect when the chart first renders:
+
+<Canvas of={ ConversionFunnelChartStories.Animation } />
+
+<Source
+	language="tsx"
+	code={ `<ConversionFunnelChart
+		mainRate={ 10.3 }
+		steps={ funnelData }
+		animation={ true }
+	/>` }
+/>
+
+### Animation Behavior
+
+- **Opt-in**: Animation is disabled by default and must be explicitly enabled with the `animation` prop
+- **Accessibility**: Automatically respects the user's `prefers-reduced-motion` system setting - animation will not play for users who prefer reduced motion
+- **Effect**: Creates a rising effect where funnel bars grow from the bottom to their full height, revealing the conversion data progressively
+- **Duration**: 1000ms (1 second) with ease-out timing
+
+**Note**: The animation plays once when the chart initially renders and does not repeat.
+
 ## Use Cases and Examples
 
 ### E-commerce Conversion Funnel

projects/js-packages/charts/src/charts/leaderboard-chart/stories/index.api.mdx

@@ -20,6 +20,7 @@ Main chart component for displaying ranked data with optional comparison values.
 | `valueFormatter` | `(value: number) => string` | `defaultValueFormatter` | Custom formatter for values |
 | `deltaFormatter` | `(value: number) => string` | `defaultDeltaFormatter` | Custom formatter for delta values |
 | `loading` | `boolean` | `false` | Whether the chart is in loading state |
+| `animation` | `boolean` | `false` | Enable entry animation on initial render. Bars stretch from left to right. Automatically respects user's `prefers-reduced-motion` system setting |
 | `showLegend` | `boolean` | `false` | Whether to display the legend |
 | `legendPosition` | `'top' \| 'bottom'` | `'bottom'` | Position of the legend |
 | `legendAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment within position |