### Example Release Flow for S2 Packages

Source: https://github.com/adobe/react-spectrum-charts/blob/main/PUBLISHING_S2.md

A step-by-step example demonstrating the release process for an S2 package, starting from version 0.1.0 to 0.2.0. It covers version update, commit, tagging, pushing, and waiting for GitHub Actions.

```bash
# Starting at version 0.1.0, releasing 0.2.0

# 1. Update version
yarn version:s2 0.2.0
# Output: ✅ S2 version update completed successfully.

# 2. Commit
git add .
git commit -m "[S2] Bump version to 0.2.0"
git push origin main

# 3. Tag and push
git tag s2-v0.2.0
git push origin s2-v0.2.0

# 4. Wait for GitHub Actions
# - Builds and publishes automatically
# - Creates PR with changes

# 5. Merge the PR
# Done! ✅
```

--------------------------------

### Start Storybook for Development

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CONTRIBUTING.md

Run the storybook command to start the development server. Access the storybook at http://localhost:6009.

```bash
yarn start
```

```bash
yarn storybook
```

--------------------------------

### Install React Spectrum Charts with yarn

Source: https://github.com/adobe/react-spectrum-charts/blob/main/README.md

Use this command to install the library and its peer dependencies using yarn.

```bash
yarn add @adobe/react-spectrum-charts @adobe/react-spectrum vega vega-lite
```

--------------------------------

### Install React Spectrum Charts with pnpm

Source: https://github.com/adobe/react-spectrum-charts/blob/main/README.md

Use this command to install the library and its peer dependencies using pnpm.

```bash
pnpm add @adobe/react-spectrum-charts @adobe/react-spectrum vega vega-lite
```

--------------------------------

### Install @spectrum-charts/react-spectrum-charts-s2

Source: https://github.com/adobe/react-spectrum-charts/blob/main/packages/react-spectrum-charts-s2/README.md

Install the package using npm or yarn. Ensure you also install @adobe/react-spectrum, vega, and vega-lite.

```bash
npm install @spectrum-charts/react-spectrum-charts-s2@alpha @adobe/react-spectrum vega vega-lite
# or
yarn add @spectrum-charts/react-spectrum-charts-s2@alpha @adobe/react-spectrum vega vega-lite
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CONTRIBUTING.md

Clone the repository locally, navigate to the project directory, and install project dependencies using yarn.

```bash
git clone https://github.com/YOUR-USERNAME/react-spectrum-charts
cd react-spectrum-charts
yarn install
```

--------------------------------

### Install React Spectrum Charts with npm

Source: https://github.com/adobe/react-spectrum-charts/blob/main/README.md

Use this command to install the library and its peer dependencies using npm.

```bash
npm install @adobe/react-spectrum-charts @adobe/react-spectrum vega vega-lite
```

--------------------------------

### Install Node Modules with Yarn

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Installs all project dependencies using Yarn. This is a prerequisite for running tests or other scripts.

```bash
yarn install
```

--------------------------------

### Start Storybook

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Launches Storybook on port 6009 for viewing and interacting with UI components.

```bash
yarn storybook
```

```bash
yarn start
```

--------------------------------

### Render Chart with Trendline Annotation

Source: https://github.com/adobe/react-spectrum-charts/wiki/Trendline

This example shows a basic chart setup with axes, scatter data, a trendline, and a trendline annotation. The annotation is configured to appear at the 'end' of the dimension axis.

```jsx
<Chart {...chartProps}>
    <Axis position="bottom" grid ticks baseline title="Speed (normal)" />
    <Axis position="left" grid ticks baseline title="Handling (normal)" />
    <Scatter color="weightClass" dimension="speedNormal" metric="handlingNormal">
        <Trendline method="median" dimensionExtent={['domain', 'domain']} lineWidth="S">
            <TrendlineAnnotation dimensionValue="end" prefix="Speed:" />
        </Trendline>
    </Scatter>
    <Legend title="Weight class" highlight position="right" />
    <Title text="Mario Kart 8 Character Data" />
</Chart>
```

--------------------------------

### Start Storybook

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CONTRIBUTING.md

Launch Storybook for local development and to demonstrate new features. This command typically opens Storybook in your browser.

```bash
yarn start
```

--------------------------------

### Install Spectrum 2 Alpha Version

Source: https://github.com/adobe/react-spectrum-charts/blob/main/README.md

Install the alpha version for Spectrum 2 support, which includes additional features like line gradients and direct labels. Ensure you also install the necessary React Spectrum and Vega packages.

```bash
yarn add @spectrum-charts/react-spectrum-charts-s2@alpha @adobe/react-spectrum vega vega-lite
```

--------------------------------

### Verify SonarScanner Installation

Source: https://github.com/adobe/react-spectrum-charts/wiki/SonarCloud

Run this command in your terminal to confirm that the SonarScanner application has been successfully installed and is accessible via your system's PATH.

```bash
sonar-scanner -h
```

--------------------------------

### Start Storybook S2 Variant

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Launches the S2 variant of Storybook on port 6010.

```bash
yarn storybook:s2
```

--------------------------------

### Basic Chart Composition Example

Source: https://github.com/adobe/react-spectrum-charts/blob/main/README.md

This example demonstrates how to compose a basic chart using Chart, Axis, Bar, and Legend components from React Spectrum Charts. Ensure you have the necessary data (`myChartData`) and props defined.

```typescript
import React from 'react';
import {Axis, Bar, Legend, Chart} from '@adobe/react-spectrum-charts';

const MyChart: FC<MyChartProps> = (props) => {
    ...

    return (
        <Chart data={myChartData}>
            <Axis position="bottom" />
            <Axis position="left" />
            <Bar type="stacked" color="series" />
            <Legend />
        </Chart>
    )
}
```

--------------------------------

### Install Latest Alpha S2 Package

Source: https://github.com/adobe/react-spectrum-charts/blob/main/PUBLISHING_S2.md

Install the latest available alpha version of an S2 package by using the '@alpha' tag. This is useful for testing the most recent experimental changes.

```bash
# Install latest alpha
npm install @spectrum-charts/react-spectrum-charts-s2@alpha

# Or with yarn
yarn add @spectrum-charts/react-spectrum-charts-s2@alpha
```

--------------------------------

### Basic Line Chart Setup

Source: https://github.com/adobe/react-spectrum-charts/wiki/Line

Sets up a basic line chart with axes, a line metric, and a legend. Ensure your data is structured correctly for the 'visitors' metric and 'browser' color key.

```jsx
<Chart data={data}>
	<Axis position='bottom' labelFormat='time' granularity='month' baseline />
	<Axis position='left' grid title="Visitors" />
	<Line metric="visitors" color="browser" />
	<Legend position='top' title='Browser' />
</Chart>
```

--------------------------------

### Vertical Bar Chart Example

Source: https://github.com/adobe/react-spectrum-charts/wiki/Bar

This example demonstrates a vertical bar chart. Configure axes to represent the metric and dimension appropriately.

```jsx
<Chart data={data}>
    <Axis position="bottom" baseline title="Browser" />
    <Axis position="left" grid ticks title="Visitors" />
    <Bar
        name="Vertical Bar"
        orientation="vertical"
        dimension="browser"
        metric="visitors"
    />
</Chart>
```

--------------------------------

### Basic Bar Chart

Source: https://github.com/adobe/react-spectrum-charts/wiki/BlogPost

Create a simple bar chart by specifying the data and the dimensions for the bars. This example plots 'users' by 'operatingSystem'.

```jsx
<Chart data={data}>
    <Bar dimension="users" metric="operatingSystem" />
</Chart>
```

--------------------------------

### Line Component Usage

Source: https://github.com/adobe/react-spectrum-charts/wiki/Line

Basic example of how to use the Line component within a Chart.

```APIDOC
## Line Component

### Description
The `Line` component is used to display line charts. It visualizes data trends over a specified scale.

### Props

#### Children
- **children** (ChartTooltip | ChartPopover | MetricRange | Trendline) - Optional - Elements that can be rendered within the chart, such as tooltips, popovers, metric ranges, or trendlines.

#### Data Mapping
- **color** (string) - Optional (default: 'series') - The key in the data that defines the color of the line. This maps to the colors scale.
- **dimension** (string) - Optional (default: 'datetime') - The key in the data that the metric is trended against (typically the x-axis).
- **metric** (string) - Optional (default: 'value') - The key in the data used for the value of the data point (typically the y-axis).
- **lineType** (string | {value: LineType | number[]}) - Optional - If a string, it's the key in the data to group lines by series. If an object, it sets the line type for all lines.
- **staticPoint** (string) - Optional - Key in the data that, if its value is true, displays a visible point on the line for that data item.

#### Configuration
- **scaleType** ('linear' | 'time' | 'point') - Optional (default: 'time') - The type of data the line is trended over. Use 'time' for epoch time, 'point' for ordinal data.
- **padding** (number) - Optional - Sets the chart area padding. A ratio (0-1) for categorical scales, a pixel value for continuous scales.

#### Interaction & Identification
- **name** (string) - Optional - Line name, useful for traversing the chart object.
- **onClick** ((item: Datum) => void) - Optional - Callback function when a point on the line is clicked. Enables hover effects and pointer cursor.

### Request Example
```jsx
<Chart data={data}>
	<Axis position='bottom' labelFormat='time' granularity='month' baseline />
	<Axis position='left' grid title="Visitors" />
	<Line metric="visitors" color="browser" />
	<Legend position='top' title='Browser' />
</Chart>
```

### Response
This component does not have direct request/response cycles as it's a UI component rendered within a chart. Its behavior is determined by the props provided and the data it receives.
```

--------------------------------

### Basic Chart Composition with Spectrum 2

Source: https://github.com/adobe/react-spectrum-charts/blob/main/packages/react-spectrum-charts-s2/README.md

Import necessary components and compose a chart using declarative syntax. This example shows a line chart with bottom and left axes, and a legend.

```jsx
import { Chart, Axis, Line, Legend } from '@spectrum-charts/react-spectrum-charts-s2';

<Chart data={data}>
  <Axis position="bottom" labelFormat="time" ticks baseline />
  <Axis position="left" grid />
  <Line color="series" />
  <Legend />
</Chart>
```

--------------------------------

### Install S2 Package with Specific Version

Source: https://github.com/adobe/react-spectrum-charts/blob/main/PUBLISHING_S2.md

Users can install a specific alpha version of an S2 package using npm or yarn, appending the version number to the package name.

```bash
npm install @spectrum-charts/react-spectrum-charts-s2@0.1.0
```

--------------------------------

### Run SonarCloud Analysis for Forked PRs

Source: https://github.com/adobe/react-spectrum-charts/wiki/SonarCloud

Execute this command in your terminal to install dependencies, run tests, and perform SonarCloud analysis for a forked branch PR. A report will be generated and uploaded to the PR.

```bash
yarn sonar-fork-pr <pr-number>
```

--------------------------------

### Horizontal Bar Chart Example

Source: https://github.com/adobe/react-spectrum-charts/wiki/Bar

Use this snippet to render a basic horizontal bar chart. Ensure 'data' is provided and axes are configured for dimension and metric.

```jsx
<Chart data={data}>
    <Axis position="bottom" grid ticks title="Page Views" />
    <Axis position="left" baseline title="Browser" />
    <Bar
        name="Bar Chart"
        orientation="horizontal"
        dimension="browser"
        metric="views"
    />
</Chart>
```

--------------------------------

### Link React Spectrum Charts Package

Source: https://github.com/adobe/react-spectrum-charts/wiki/Developer-Docs

Link the local react-spectrum-charts package into another project. Ensure you run `yarn install` in the target project after linking.

```bash
yarn link @adobe/react-spectrum-charts
```

--------------------------------

### CSS Colors Example

Source: https://github.com/adobe/react-spectrum-charts/wiki/Chart-API

Define a color scale using an array of CSS color values. This method is less preferred.

```javascript
['#FFF', 'DarkGoldenRod', '#00008B', 'rgb(150, 150, 150)']
```

--------------------------------

### Continuously Run Tests

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CONTRIBUTING.md

Run tests automatically whenever files are updated. This is useful during active development to get immediate feedback.

```bash
yarn watch
```

--------------------------------

### Custom Locale Definition Example

Source: https://github.com/adobe/react-spectrum-charts/wiki/Chart-API

Provide custom locale definitions for numbers and time. This allows for fine-grained control over formatting based on locale.

```typescript
import {NumberLocale, TimeLocale} from 'vega'

...
const numberLocale: NumberLocale = {
    "decimal": ",",
    "thousands": "\u00a0",
    "grouping": [3],
    "currency": ["", "\u00a0CHF"],
    "percent": "\u202f%"
};
const timeLocale: TimeLocale = {
    "dateTime": "%A %e %B %Y à %X",
    "date": "%d.%m.%Y",
    "time": "%H:%M:%S",
    "periods": ["AM", "PM"],
    "days": ["dimanche", "lundi", "mardi", "mercredi", "jeudi", "vendredi", "samedi"],
    "shortDays": ["dim.", "lun.", "mar.", "mer.", "jeu.", "ven.", "sam."],
    "months": ["janvier", "février", "mars", "avril", "mai", "juin", "juillet", "août", "septembre", "octobre", "novembre", "décembre"],
    "shortMonths": ["janv.", "févr.", "mars", "avr.", "mai", "juin", "juil.", "août", "sept.", "oct.", "nov.", "déc."]
}

...
<Chart {...chartProps} locale={{number: numberLocale, time: timeLocale}}>
...


```

--------------------------------

### Using ChartPopover with Bar Chart

Source: https://github.com/adobe/react-spectrum-charts/wiki/ChartPopover

This example demonstrates how to integrate ChartPopover with a Bar chart to display detailed information and provide interactive elements like a close button.

```jsx
<Chart data={data} >
    <Bar>
        <ChartPopover>
            {(datum, close) => (
                <Content>
                    <Text>Average: {datum.average}</Text>
                    <ActionButton onPress={close}>Close</ActionButton>
                </Content>
            )}
        </ChartPopover>
    </Bar>
</Chart>
```

--------------------------------

### Spectrum Color Names Example

Source: https://github.com/adobe/react-spectrum-charts/wiki/Chart-API

Define a color scale using an array of spectrum color names. These names are responsive and adjust for light and dark modes.

```javascript
['red-500', 'blue-600', 'celery-400']
```

--------------------------------

### BigNumber Currency Format Example

Source: https://github.com/adobe/react-spectrum-charts/wiki/Big-Number

Formats the BigNumber value as currency using the numberFormat prop and specifies the locale for correct formatting. The dataKey 'value' is used here.

```jsx
<Chart
  data={[{ value: 255.56 }]}
  height={600}
  locale="de-DE"
  width={600}
>
  <BigNumber
    dataKey="value"
    label="Ad Spend"
    numberFormat="$,.2f"
    orientation="horizontal"
  />
</Chart>
```

--------------------------------

### BigNumber Basic Horizontal Example

Source: https://github.com/adobe/react-spectrum-charts/wiki/Big-Number

Displays a BigNumber component with a label in a horizontal orientation. Requires a parent Chart component and dataKey prop.

```jsx
<Chart
  data={[{ x: 20, y: 90 }]}
  height={100}
  width={200}
>
  <BigNumber
    dataKey="x"
    label="Visitors"
    orientation="horizontal"
  />
</Chart>
```

--------------------------------

### Using ScatterPath in a Chart

Source: https://github.com/adobe/react-spectrum-charts/wiki/Scatter

This example demonstrates how to use the ScatterPath component within a Chart to draw connecting paths between data points. It requires the Chart and Scatter components to be set up first. The `groupBy` prop is essential for defining which points should be connected.

```jsx
<Chart {...chartProps}>
    {...chartComponents}
    <Scatter
        color="segment"
        dimension="dauPercent"
        lineType="period"
        lineWidth={{
            value: 1
        }}
        metric="countAvg"
        opacity="period"
    >
        {...scatterChildren}
        <ScatterPath
            groupBy={['event', 'segment']}
            opacity={0.2}
            pathWidth="trailSize"
        />
    </Scatter>
</Chart>
```

--------------------------------

### Chart with Multiple Scales and Line Types

Source: https://github.com/adobe/react-spectrum-charts/wiki/Chart-API

This example demonstrates subdividing data using both 'color' and 'lineType' scales. It configures specific line types ('dotted', 'solid') and assigns them based on the 'version' key, while 'browser' determines the color.

```jsx
<Chart data={data} lineTypes={['dotted', 'solid']}>
	<Axis position='bottom' labelFormat='time' granularity='day' baseline />
	<Axis position='left' grid title="Events" />
	<Line metric="events" color="browser" lineType="version" />
	<Legend position='bottom' />
</Chart>
```

--------------------------------

### Build React Spectrum Charts MCP Server from Source

Source: https://github.com/adobe/react-spectrum-charts/blob/main/packages/mcp/README.md

Navigate to the MCP package directory and run the build command to compile the server from source code.

```bash
cd packages/mcp
yarn build
```

--------------------------------

### Build All Packages

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Builds all packages in the monorepo, respecting dependency order.

```bash
yarn build
```

--------------------------------

### Test React Spectrum Charts MCP Server with Inspector

Source: https://github.com/adobe/react-spectrum-charts/blob/main/packages/mcp/README.md

Build the project and then run the MCP Inspector with the built server index file to test its functionality.

```bash
yarn build
npx @modelcontextprotocol/inspector node dist/index.js
```

--------------------------------

### Build a Single Package

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Builds a specific workspace package.

```bash
yarn workspace @spectrum-charts/vega-spec-builder build
```

--------------------------------

### Initialize local.json for SonarCloud

Source: https://github.com/adobe/react-spectrum-charts/wiki/SonarCloud

Create a local.json file in the react-spectrum-charts/ directory and paste this content. Fill in your SONAR_TOKEN and GITHUB_TOKEN to authenticate the analysis.

```json
{
    "SONAR_TOKEN": "",
    "GITHUB_TOKEN": ""
}
```

--------------------------------

### Define Area Chart with Start and End Metrics

Source: https://github.com/adobe/react-spectrum-charts/wiki/Area

Use `metricStart` and `metricEnd` props to define the shape of an area chart when start and end values are explicitly provided. These props cannot be used with `stacked = true` or with the `metric` prop.

```jsx
<Chart data={data}>
    <Area metricStart="minScore" metricEnd="maxScore" />
</Chart>
```

--------------------------------

### Build All Packages in Parallel

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Builds all packages concurrently for faster rebuilds.

```bash
yarn build:parallel
```

--------------------------------

### Recursive Effective Y Calculation

Source: https://github.com/adobe/react-spectrum-charts/blob/main/planning/research/direct-label-stacking.md

Calculates the effective y-position for labels recursively, starting with an initial nudge for the top label.

```plaintext
effectiveY[1] = scaledY[1] - 12          (nudge the top label up 12px)
effectiveY[k] = max(scaledY[k] - 12, effectiveY[k-1] + LABEL_LINE_HEIGHT)
```

--------------------------------

### Configure Local Development for React Spectrum Charts MCP Server

Source: https://github.com/adobe/react-spectrum-charts/blob/main/packages/mcp/README.md

Use this JSON configuration for local development to point to your built MCP server file. Replace '/path/to/react-spectrum-charts/packages/mcp/dist/index.js' with the actual path to your built file.

```json
{
  "mcpServers": {
    "react-spectrum-charts": {
      "command": "node",
      "args": ["/path/to/react-spectrum-charts/packages/mcp/dist/index.js"]
    }
  }
}
```

--------------------------------

### Run All Tests

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Executes all unit tests across the project.

```bash
yarn test
```

--------------------------------

### Get SVG String of Chart

Source: https://github.com/adobe/react-spectrum-charts/wiki/Chart-API

The 'getSvg()' method returns the current chart visualization as an SVG string, resolved by a promise.

```jsx
const ref = useRef<ChartHandle>(null);

const getSvg = () => {
    ref.current?.getSvg().then(console.log, console.warn)
}

return (
    <>
        <Chart data={data} ref={ref}>
            <Line />
        </Chart>

        <ActionButton onPress={getSvg}>Log SVG</ActionButton>
    </>
)
```

--------------------------------

### Position LineDirectLabel

Source: https://github.com/adobe/react-spectrum-charts/blob/main/packages/docs-s2/docs/line.md

Control the placement of the label. Use 'start' to place it at the left edge of the chart, or 'end' (default) for the right edge.

```jsx
 {/* Place the label at the start of the line */}
<LineDirectLabel position="start" />
```

--------------------------------

### Basic Bar Chart Configuration

Source: https://github.com/adobe/react-spectrum-charts/wiki/Developer-Docs

Demonstrates a simple way to configure a stacked bar chart with data and orientation.

```jsx
<Chart type="stacked-bar" data={data} orientation="horizontal" axis="bottom"/>
```

--------------------------------

### Run Sonar Analysis Locally

Source: https://github.com/adobe/react-spectrum-charts/wiki/SonarCloud

Execute this command to initiate all tests and subsequently run the Sonar analysis on your local machine. This is useful for PRs from forked branches.

```bash
yarn sonar
```

--------------------------------

### Run All Tests

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CONTRIBUTING.md

Execute all unit tests once. Ensure tests are included with pull requests for CI checks.

```bash
yarn test
```

--------------------------------

### Donut Component Usage

Source: https://github.com/adobe/react-spectrum-charts/wiki/Donut-(rc)

Demonstrates how to import and use the Donut component with a legend.

```APIDOC
## Donut Component with Legend

### Description
This example shows how to use the `Donut` component along with a `Legend` to display data.

### Method
N/A (Component Usage)

### Endpoint
N/A (Component Usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```jsx
<Chart data={data}>
    <Donut color="operatingSystem" metric="visitors">
        <DonutSummary label="Visitors" />
    </Donut>
    <Legend title="Operating system" />
</Chart>
```

### Response
#### Success Response (200)
N/A (Component Usage)

#### Response Example
N/A (Component Usage)
```

--------------------------------

### Download Chart Visualization as PNG

Source: https://github.com/adobe/react-spectrum-charts/wiki/Chart-API

Use the 'download()' handle to save the current chart visualization as a PNG file to the user's computer. This function returns a promise for handling success or failure.

```jsx
const ref = useRef<ChartHandle>(null);

const download = () => {
    ref.current?.download().then(console.log, console.warn)
}

return (
    <>
        <Chart data={data} ref={ref}>
            <Line />
        </Chart>

        <ActionButton onPress={download}>Download</ActionButton>
    </>
)
```

--------------------------------

### Get Base64 PNG String of Chart

Source: https://github.com/adobe/react-spectrum-charts/wiki/Chart-API

The 'getBase64Png()' method retrieves the current chart visualization as a Base64 encoded PNG string, returned as a resolved promise.

```jsx
const ref = useRef<ChartHandle>(null);

const getBase64Png = () => {
    ref.current?.getBase64Png().then(console.log, console.warn)
}

return (
    <>
        <Chart data={data} ref={ref}>
            <Line />
        </Chart>

        <ActionButton onPress={getBase64Png}>Log Base64 PNG</ActionButton>
    </>
)
```

--------------------------------

### Re-link Local Packages After Changes

Source: https://github.com/adobe/react-spectrum-charts/wiki/Developer-Docs

After making changes in the react-spectrum-charts project, re-run this command to update the links in dependent projects. Follow with `yarn install` in the dependent project.

```bash
yarn link-all
```

--------------------------------

### Manual Publish of S2 Packages

Source: https://github.com/adobe/react-spectrum-charts/blob/main/PUBLISHING_S2.md

In case of automated publishing failures, this section provides steps for manual publishing. It involves updating versions, building, and then publishing each S2 package individually with the 'alpha' tag.

```bash
# 1. Update versions
yarn version:s2 0.2.0

# 2. Build
yarn build:s2

# 3. Publish (requires npm login)
cd packages/vega-spec-builder-s2
npm publish --tag alpha

cd ../react-spectrum-charts-s2
npm publish --tag alpha
```

--------------------------------

### Getter Function Example

Source: https://github.com/adobe/react-spectrum-charts/wiki/Developer-Docs

A pure getter function that takes arguments and returns a value. Getters do not require an initial state and should not mutate objects, thus not needing Immer.

```typescript
function getTooltip(children: DialogElement[]): ProductionRule<StringValueRef> | undefined {
	if (children.length) {
		return { signal: 'datum' };
	}
}
```

--------------------------------

### Build S2 Packages

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Builds the S2 packages, which depend on the S1 packages being built first.

```bash
yarn build:s2
```

--------------------------------

### Bar Pseudo Component Definition

Source: https://github.com/adobe/react-spectrum-charts/wiki/Developer-Docs

Example of a 'pseudo component' for a Bar chart. These components do not render to the DOM but define props for the Vega spec. Includes default prop values.

```tsx
import { BarProps } from '../types';

export function Bar({ dimension = 'category', color = 'series', metric = 'value', opacity = 1 }: BarProps) {
	return null;
}
```

--------------------------------

### Manual S2 Package Publishing Workflow

Source: https://github.com/adobe/react-spectrum-charts/blob/main/PUBLISHING_S2.md

This sequence of commands can be used for manual publishing if the automated workflow fails. It includes updating versions, building packages, and publishing to npm with the 'alpha' tag.

```bash
# 1. Update versions
yarn version:s2 0.2.0

# 2. Build packages
yarn build:s2

# 3. Publish with alpha tag
yarn publish:s2 --tag alpha
```

--------------------------------

### Add AxisAnnotation to Chart

Source: https://github.com/adobe/react-spectrum-charts/wiki/Axis

Example of how to add an AxisAnnotation to an Axis component within a Chart. Ensure the Chart component has data and the Axis has appropriate props like position and title.

```jsx
const axisAnnotationProps = {
	dataKey: 'annotations',
	color: 'gray-600',
}

<Chart data={data}>
    <Axis position="bottom" granularity="hour" grid={false} title="My Axis Title">
        <AxisAnnotation {...axisAnnotationProps} />
    </Axis>
</Chart>
```

--------------------------------

### Bar Chart with Axes

Source: https://github.com/adobe/react-spectrum-charts/wiki/BlogPost

Enhance a bar chart by adding axes for better data readability. This example includes a left y-axis for 'Users' and a bottom x-axis for 'Operating System'.

```jsx
<Chart data={data}>
    <Axis position="left" title="Users" />
    <Axis position="bottom" title="Operating System" />
    <Bar dimension="users" metric="operatingSystem" />
</Chart>
```

--------------------------------

### MetricRange Component Usage

Source: https://github.com/adobe/react-spectrum-charts/wiki/MetricRange

Demonstrates how to use the MetricRange component within a Chart and Bar component. MetricRange is only supported for Line components, but the example shows its integration in a Bar chart context.

```APIDOC
## MetricRange Component

### Description
The `MetricRange` component is used to add a custom area mark onto visualizations. It is primarily supported for `Line` components but can be integrated within other chart types like `Bar` as shown in the example.

### Usage
When creating a `MetricRange`, you define `metricStart` and `metricEnd` to control the area of the chart it covers. An optional `metric` prop can be provided to display an additional line within the `MetricRange`.

### Examples

#### Average line on a bar chart
```jsx
<Chart data={data} >
    <Bar>
        <MetricRange metricStart="minDataKey" metricEnd="maxDataKey" color="gray-500"  />
    </Bar>
</Chart>
```

### Props

#### Request Body
- **children** (ChartTooltip) - Optional - Tooltip to be displayed when hovering over the metric range.
- **color** (SpectrumColor | CssColor) - Optional - The line color of the metric range. Defaults to the color of the series it represents if undefined.
- **displayOnHover** (boolean) - Optional - Determines if the metric range should only be visible when hovering over the parent line. Defaults to `false`.
- **lineType** ('solid' | 'dashed' | 'dotted' | 'dotDash' | 'shortDash' | 'longDash' | 'twoDash' | number[]) - Optional - If a metric is provided, defines the line type of the metric line. Defaults to `'dashed'`.
- **lineWidth** ('XS' | 'S' | 'M' | 'L' | 'XL' | number) - Optional - If a metric is provided, defines the width of the metric line. Defaults to `'S'`.
- **metric** (string) - Optional - The key for the metric value in the data. Defaults to `'value'`.
- **metricEnd** (string) - Required - The key for the upper range in the data.
- **metricStart** (string) - Required - The key for the lower range in the data.
- **rangeOpacity** (number) - Optional - The opacity of the metric range. Defaults to `0.8`.
- **scaleAxisToFit** (boolean) - Optional - Whether the y-axis should expand to include the entire metric range if necessary. Defaults to `false`.

### Notes
- `MetricRanges` are not added to the legend. Only the parent marks are included in the legend.
```

--------------------------------

### React Spectrum Charts Package Structure

Source: https://github.com/adobe/react-spectrum-charts/blob/main/CLAUDE.md

Overview of the directory structure for the react-spectrum-charts monorepo. Identifies the main packages and their purposes.

```bash
packages/
  react-spectrum-charts/       # Public React component library (@adobe/react-spectrum-charts)
  vega-spec-builder/           # Vega spec generation logic (@spectrum-charts/vega-spec-builder)
  vega-spec-builder-s2/        # Spectrum 2 variant of the spec builder
  react-spectrum-charts-s2/    # Spectrum 2 React component variant
  constants/                   # Shared string constants (signal names, data field names, defaults)
  themes/                      # Color schemes and runtime token resolution
  utils/                       # Shared utility functions
  locales/                     # i18n strings
  dev-tools/                   # Internal contributor CLI tools (not published)
  mcp/                         # MCP server
```

--------------------------------

### Trellised Stacked Vertical Bar Chart

Source: https://github.com/adobe/react-spectrum-charts/wiki/Bar

This example shows a trellised stacked vertical bar chart. It uses 'trellis' and 'trellisOrientation' props to create multiple sub-charts based on a dimension.

```jsx
<Chart data={data}>
    <Axis
        grid
        position="left"
        title="Users, Count"
    />
    <Axis
        baseline
        position="bottom"
        title="Platform"
    />
    <Bar
        color="bucket"
        dimension="platform"
        order="order"
        orientation="vertical"
        trellis="event"
        trellisOrientation="horizontal"
        type="stacked"
    >
    </Bar>
    <Legend />
</Chart>
```

--------------------------------

### Troubleshooting Version Update Failure

Source: https://github.com/adobe/react-spectrum-charts/blob/main/PUBLISHING_S2.md

If a version update fails, ensure you are using the correct 0.x.x alpha format for S2 packages and not the stable 1.x.x format or an incorrect 'v0.x.x' format.

```bash
# Make sure you're using 0.x.x format
yarn version:s2 0.2.0

# Not 1.x.x or v0.x.x
```