@automattic/charts 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.0] - 2025-07-23
+### Added
+- Line Chart: Add documentation [#44410]
+
 ## [0.19.1] - 2025-07-22
 ### Changed
 - Removed dependency on jetpack-components [#44411]
@@ -304,6 +308,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed lints following ESLint rule changes for TS [#40584]
 - Fixing a bug in Chart storybook data. [#40640]
 
+[0.20.0]: https://github.com/Automattic/charts/compare/v0.19.1...v0.20.0
 [0.19.1]: https://github.com/Automattic/charts/compare/v0.19.0...v0.19.1
 [0.19.0]: https://github.com/Automattic/charts/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/Automattic/charts/compare/v0.17.0...v0.18.0

package/docs/ai-documentation-guide.md

@@ -0,0 +1,353 @@
+# AI Documentation Guide for Automattic Charts
+
+This guide provides instructions for AI agents to generate comprehensive documentation for chart components and features following the established patterns in `@automattic/charts`.
+
+## Documentation Structure Template
+
+All chart documentation should follow this standardized structure:
+
+### 1. File Header & Imports
+
+```mdx
+import { Meta, Canvas, Story, Source } from '@storybook/addon-docs/blocks';
+import * as [FeatureName]Stories from './[feature-name].stories';
+
+<Meta title="JS Packages/Charts/[Category]/[Component]/[Feature]" of={ [FeatureName]Stories } />
+```
+
+### 2. Title & Introduction
+
+```mdx
+# [Component] [Feature Name]
+
+Brief 1-2 sentence description of what this feature does and its primary use case.
+
+<Canvas of={ [FeatureName]Stories.Default } />
+```
+
+### 3. Overview Section
+
+Always include:
+
+- High-level explanation of the feature
+- Basic code example showing the compound component pattern
+- Key concepts or terminology
+
+```mdx
+## Overview
+
+The [Component] component supports [feature description], providing [benefits]:
+
+<Source
+	language="jsx"
+	code={ `import { [Component] } from '@automattic/charts';
+
+    <[Component] data={ data }>
+    	<[Component].[FeatureComponent]>
+    		<[Component].[SubComponent]
+    			[key-props]
+    		/>
+    	</[Component].[FeatureComponent]>
+    </[Component]>` }
+
+/>
+```
+
+### 4. Basic Usage Section
+
+```mdx
+## Basic Usage
+
+### Basic [Feature Name]
+
+Description of simplest implementation:
+
+<Canvas of={ [FeatureName]Stories.Default } />
+
+<Source language="jsx" code={ `[minimal-example]` } />
+
+### Required Props
+
+- **`propName`**: Description of what this prop does
+- **`anotherProp`**: Description
+
+### Optional Props
+
+- **`optionalProp`**: Description and default behavior
+- **`anotherOptional`**: Description
+```
+
+### 5. Feature Variations
+
+Document all major variations with:
+
+- Descriptive subsection title
+- Canvas example
+- Code snippet
+- Explanation of when to use
+
+```mdx
+## [Feature] Types
+
+### [Variation Name] (Default/Primary)
+
+Description of this variation:
+
+<Canvas of={ [FeatureName]Stories.[VariationName] } />
+
+### [Another Variation]
+
+Description and use case:
+
+<Canvas of={ [FeatureName]Stories.[AnotherVariation] } />
+
+<Source language="jsx" code={ `example-code` } />
+```
+
+### 6. Styling and Customization
+
+```mdx
+## Styling and Customization
+
+### Custom [Styling Aspect]
+
+How to customize appearance:
+
+<Canvas of={ [FeatureName]Stories.Styled } />
+
+<Source language="jsx" code={ `styling-example` } />
+
+### Styling Options
+
+The `styles` prop accepts the following nested objects:
+
+#### `[styleCategory]`
+
+Controls [what this category affects]:
+
+- `property`: Description and possible values
+- `anotherProperty`: Description
+
+### Theme Integration
+
+Explanation of how feature integrates with chart themes.
+```
+
+### 7. Advanced Features
+
+Document complex functionality:
+
+```mdx
+## Advanced Features
+
+### [Advanced Feature Name]
+
+Explanation of complex functionality with examples.
+
+### [Another Advanced Feature]
+
+More advanced usage patterns.
+```
+
+### 8. Accessibility Section
+
+Always include accessibility information:
+
+```mdx
+## Accessibility
+
+### Keyboard Navigation
+
+- Key interactions and behaviors
+
+### Screen Reader Support
+
+- ARIA attributes and labels
+- Any limitations or considerations
+
+### Focus Management
+
+- Focus behavior and visual indicators
+```
+
+### 9. Browser Compatibility
+
+Include any browser-specific considerations:
+
+```mdx
+## Browser Compatibility
+
+### [Browser Name] Considerations
+
+Any browser-specific behaviors or workarounds.
+
+### [API/Feature] Support
+
+Information about feature support and fallbacks.
+```
+
+### 10. API Reference
+
+Comprehensive prop documentation:
+
+````mdx
+## API Reference
+
+### [Component].[SubComponent]
+
+Description of the component.
+
+**Props:**
+
+- `children`: Description
+
+### [Component].[MainComponent]
+
+Description of main component.
+
+**Props:**
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `requiredProp` | `Type` | - | **Required.** Description |
+| `optionalProp` | `Type \| Other` | `default` | Description |
+
+### [TypeName] Type
+
+```typescript
+type TypeName = {
+	property: Type;
+	optional?: Type;
+};
+```
+````
+
+````
+
+### 11. Migration
+```mdx
+## Migration from [Legacy/Previous API]
+If applicable, provide migration examples:
+
+<Source language="jsx" code={`
+// Old API
+[old-example]
+
+// New API
+[new-example]
+`} />
+````
+
+## Content Guidelines
+
+### Writing Style
+
+- **Be concise but comprehensive**: Each section should be thorough but not verbose
+- **Use active voice**: "Annotations allow you to..." vs "You can use annotations to..."
+- **Include practical examples**: Always show real code that users can copy-paste
+- **Explain the "why"**: Don't just document what props do, explain when to use them
+
+### Code Examples
+
+- **Always use realistic data**: Show complete, runnable examples
+- **Follow TypeScript patterns**: Include proper typing in examples
+- **Use consistent naming**: `data`, `dataPoint`, `sampleData` for chart data
+- **Show progressive complexity**: Start simple, build up to advanced usage
+
+### Canvas Examples
+
+- **Every major feature needs a visual**: Use `<Canvas of={ Story } />`
+- **Order logically**: Default → Basic variations → Advanced → Custom
+- **Keep stories focused**: Each story should demonstrate one clear concept
+
+### Props Documentation
+
+- **Mark required props clearly**: Use bold "**Required.**" prefix
+- **Include defaults**: Show what happens if prop is omitted
+- **Type information**: Always include TypeScript types
+- **Practical descriptions**: Explain impact and use cases, not just data types
+
+### Cross-References
+
+- **Link to related documentation**: Reference other chart features when relevant
+- **Reference external docs**: Link to third-party libraries (visx, etc.) when applicable
+
+## File Organization
+
+### File Naming
+
+- Main docs: `[feature-name].docs.mdx`
+- Stories: `[feature-name].stories.tsx`
+
+### Directory Structure
+
+```
+src/components/[chart-type]/stories/
+├── [feature-name].docs.mdx
+├── [feature-name].stories.tsx
+```
+
+### Storybook Integration
+
+- Use consistent story naming: `Default`, `Styled`, `Custom`, `[VariationType]`
+- Group related stories logically in Storybook hierarchy
+- Include descriptive story descriptions for context
+
+## Quality Checklist
+
+Before considering documentation complete, verify:
+
+### Completeness
+
+- [ ] All props documented with types and descriptions
+- [ ] Visual examples for all major variations
+- [ ] Code examples are complete and runnable
+- [ ] Accessibility considerations covered
+- [ ] Browser compatibility notes included
+
+### Accuracy
+
+- [ ] Code examples match actual implementation
+- [ ] Type definitions are current
+- [ ] Examples use current API patterns
+
+### Usability
+
+- [ ] Progressive complexity (simple → advanced)
+- [ ] Clear section headings and navigation
+- [ ] Practical use case examples
+- [ ] Migration guidance where applicable
+
+### Standards Compliance
+
+- [ ] Follows compound component patterns
+- [ ] Uses established styling conventions
+- [ ] Integrates with chart theming system
+- [ ] Maintains accessibility standards
+
+## Using the Feature Documentation Template
+
+AI agents should use the provided `feature-documentation.mdx.template` as a starting point for any new chart feature documentation:
+
+1. **Copy the template**: Start with `feature-documentation.mdx.template`
+2. **Replace all bracketed placeholders**: Fill in `[Component]`, `[FeatureName]`, `[feature-name]`, etc. with actual values
+3. **Follow the structure**: Keep all sections but adapt content to your specific feature
+4. **Remove irrelevant sections**: If your feature doesn't have certain capabilities (e.g., no interactive features), remove those sections
+5. **Add feature-specific sections**: Include additional sections if your feature has unique aspects not covered in the template
+
+The template includes all the standard sections, proper MDX formatting, and placeholder text to guide content creation.
+
+## Example Analysis
+
+The `annotation.docs.mdx` file exemplifies these patterns:
+
+1. **Clear structure**: Logical flow from basic to advanced
+2. **Visual examples**: Every feature variation has a Canvas example
+3. **Complete API docs**: Comprehensive prop tables with types
+4. **Practical guidance**: Real-world usage scenarios and best practices
+5. **Accessibility focus**: Dedicated section covering keyboard, screen reader, and focus behavior
+6. **Browser considerations**: Honest discussion of Safari limitations
+7. **Migration support**: Clear guidance for upgrading from legacy API
+
+Follow this structure and level of detail for all chart component documentation to ensure consistency and usefulness across the entire charts library. Examples and stories are accessible through the Storybook UI, so they don't need to be listed in the documentation.
+
+**Important**: When documenting performance considerations, only include optimizations and limitations that are actually implemented, documented, or evidenced in the codebase. Avoid general web development best practices unless they are specifically relevant and tested for the chart components.

package/docs/feature-documentation.mdx.template

@@ -0,0 +1,244 @@
+import { Meta, Canvas, Story, Source } from '@storybook/addon-docs/blocks';
+import * as [FeatureName]Stories from './[feature-name].stories';
+
+<Meta title="JS Packages/Charts/[Category]/[Component]/[Feature]" of={ [FeatureName]Stories } />
+
+# [Component] [Feature Name]
+
+[Brief 1-2 sentence description of what this feature does and its primary use case.]
+
+<Canvas of={ [FeatureName]Stories.Default } />
+
+## Overview
+
+The [Component] component supports [feature description], providing [benefits and key capabilities]:
+
+<Source
+	language="jsx"
+	code={ `import { [Component] } from '@automattic/charts';
+
+	<[Component] data={ data }>
+		<[Component].[FeatureComponent]>
+			<[Component].[SubComponent]
+				[key-required-props]
+				[key-optional-props]
+			/>
+		</[Component].[FeatureComponent]>
+	</[Component]>` }
+/>
+
+## Basic Usage
+
+### Basic [Feature Name]
+
+[Description of the simplest implementation and when to use it]:
+
+<Canvas of={ [FeatureName]Stories.Default } />
+
+<Source
+	language="jsx"
+	code={ `<[Component] data={data}>
+		<[Component].[FeatureComponent]>
+			<[Component].[SubComponent]
+				[minimal-props-example]
+			/>
+		</[Component].[FeatureComponent]>
+	</[Component]>` }
+/>
+
+### Required Props
+
+- **`[propName]`**: [Description of what this prop does and its purpose]
+- **`[anotherRequiredProp]`**: [Description]
+
+### Optional Props
+
+- **`[optionalProp]`**: [Description and default behavior]
+- **`[anotherOptional]`**: [Description and use cases]
+
+## [Feature] Types
+
+### [Primary Type] (Default)
+
+[Description of the default/primary variation and when to use it]:
+
+<Canvas of={ [FeatureName]Stories.Default } />
+
+### [Variation Type]
+
+[Description and specific use case for this variation]:
+
+<Canvas of={ [FeatureName]Stories.[VariationName] } />
+
+<Source
+	language="jsx"
+	code={ `<[Component].[SubComponent]
+		[variation-specific-props]
+	/>` }
+/>
+
+### [Another Variation Type]
+
+[Description and use case]:
+
+<Canvas of={ [FeatureName]Stories.[AnotherVariation] } />
+
+### [Mixed/Combined Usage]
+
+[If applicable, show how different variations work together]:
+
+<Canvas of={ [FeatureName]Stories.Mixed } />
+
+## Styling and Customization
+
+### Custom [Styling Aspect]
+
+[Explanation of how to customize appearance with examples]:
+
+<Canvas of={ [FeatureName]Stories.Styled } />
+
+<Source
+	language="jsx"
+	code={ `<[Component].[SubComponent]
+		[props]
+		styles={{
+			[styleCategory]: {
+				[property]: '[value]',
+			},
+		}}
+	/>` }
+/>
+
+### Styling Options
+
+The `styles` prop accepts the following nested objects[, based on [external library reference if applicable]]:
+
+#### `[styleCategory]`
+
+Controls [what this category affects]:
+
+- `[property]`: [Description and possible values]
+- `[anotherProperty]`: [Description]
+
+#### `[anotherStyleCategory]`
+
+Controls [what this affects]:
+
+- `[property]`: [Description]
+
+### Theme Integration
+
+[Explanation of how feature integrates with chart themes and any theme-specific styling].
+
+## Custom [Feature Name]
+
+### Custom [Aspect] Rendering
+
+[Explanation of custom rendering capabilities]:
+
+<Canvas of={ [FeatureName]Stories.Custom } />
+
+<Source
+	language="jsx"
+	code={`[custom-implementation-example]`}
+/>
+
+### Interactive [Feature Name]
+
+[If applicable, show interactive capabilities]:
+
+<Source
+	language="jsx"
+	code={ `[interactive-example]` }
+/>
+
+## Advanced Features
+
+### [Advanced Feature Name]
+
+[Explanation of complex functionality with practical examples].
+
+### [Another Advanced Feature]
+
+[More advanced usage patterns and edge cases].
+
+## Accessibility
+
+### Keyboard Navigation
+
+- [Key interactions and expected behaviors]
+- [Navigation patterns]
+
+### Screen Reader Support
+
+- [ARIA attributes and labels used]
+- [Any limitations or considerations for screen readers]
+
+### Focus Management
+
+- [Focus behavior and visual indicators]
+- [Focus trapping or restoration if applicable]
+
+## Browser Compatibility
+
+### [Browser] Considerations
+
+[Any browser-specific behaviors, workarounds, or limitations].
+
+### [API/Feature] Support
+
+[Information about modern web API usage, polyfills, or fallback behavior].
+
+## API Reference
+
+### [Component].[FeatureComponent]
+
+[Description of the container/wrapper component].
+
+**Props:**
+
+- `children`: [Description of expected children]
+
+### [Component].[SubComponent]
+
+[Description of the main feature component].
+
+**Props:**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `[requiredProp]` | `[Type]` | - | **Required.** [Description] |
+| `[optionalProp]` | `[Type] \| [AlternativeType]` | `[default]` | [Description] |
+| `[anotherProp]` | `[ComplexType]` | - | [Description] |
+
+### [TypeName] Type
+
+```typescript
+type [TypeName] = {
+	[property]: [Type];
+	[optionalProperty]?: [Type];
+};
+```
+
+### [AnotherTypeName] Type
+
+```typescript
+type [AnotherTypeName] = {
+	[property]: [Type];
+};
+```
+
+## Migration from [Legacy API]
+
+[If applicable, provide migration examples]:
+
+<Source
+	language="jsx"
+	code={`// Old API (deprecated)
+[legacy-example]
+
+// New API
+[new-api-example]
+`} />
+
+[Brief explanation of benefits of the new approach and any breaking changes to be aware of].

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "0.19.1",
+	"version": "0.20.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {