11import { Meta , Source } from ' @storybook/addon-docs/blocks' ;
22
3- <Meta title = " JS Packages/Charts/Types/Category Bar/API Reference" />
3+ <Meta title = " JS Packages/Charts/Types/Segmented Bar/API Reference" />
44
5- # Category Bar API Reference
5+ # Segmented Bar API Reference
66
7- Complete API documentation for the Category Bar component.
7+ Complete API documentation for the Segmented Bar component.
88
99## Props
1010
1111| Prop | Type | Default | Description |
1212| ------| ------| ---------| -------------|
13- | ` values ` | ` number[] \| CategoryBarSegment [] ` | Required | Array of segment values or segment objects |
13+ | ` values ` | ` number[] \| SegmentedBarSegment [] ` | Required | Array of segment values or segment objects |
1414| ` mode ` | ` 'proportional' \| 'equal' ` | ` 'proportional' ` | How segment widths are calculated |
1515| ` colors ` | ` string[] ` | Theme colors | Custom colors for segments |
16- | ` marker ` | ` CategoryBarMarker ` | - | Optional position indicator |
16+ | ` marker ` | ` SegmentedBarMarker ` | - | Optional position indicator |
1717| ` showLabels ` | ` boolean ` | ` true ` | Whether to show cumulative value labels |
1818| ` width ` | ` number ` | ` 300 ` | Width of the bar in pixels |
1919| ` height ` | ` number ` | ` 8 ` | Height of the bar in pixels |
@@ -27,11 +27,11 @@ Complete API documentation for the Category Bar component.
2727
2828## Type Definitions
2929
30- ### CategoryBarSegment
30+ ### SegmentedBarSegment
3131
3232<Source
3333 language = " typescript"
34- code = { ` interface CategoryBarSegment {
34+ code = { ` interface SegmentedBarSegment {
3535 /**
3636 * Numeric value for this segment.
3737 * In 'proportional' mode, determines segment width relative to total.
@@ -52,11 +52,11 @@ Complete API documentation for the Category Bar component.
5252} ` }
5353/>
5454
55- ### CategoryBarMarker
55+ ### SegmentedBarMarker
5656
5757<Source
5858 language = " typescript"
59- code = { ` interface CategoryBarMarker {
59+ code = { ` interface SegmentedBarMarker {
6060 /**
6161 * Position value where the marker should appear.
6262 * Interpreted as cumulative value from left (0 to total).
@@ -75,28 +75,28 @@ Complete API documentation for the Category Bar component.
7575 showAnimation?: boolean;
7676
7777 /**
78- * Marker color (defaults to theme text color)
78+ * Marker color (defaults to theme grid color)
7979 */
8080 color?: string;
8181} ` }
8282/>
8383
84- ### CategoryBarMode
84+ ### SegmentedBarMode
8585
8686<Source
8787 language = " typescript"
88- code = { ` type CategoryBarMode = 'proportional' | 'equal'; ` }
88+ code = { ` type SegmentedBarMode = 'proportional' | 'equal'; ` }
8989/>
9090
91- ### CategoryBarProps
91+ ### SegmentedBarProps
9292
9393<Source
9494 language = " typescript"
95- code = { ` interface CategoryBarProps {
96- values: number[] | CategoryBarSegment [];
97- mode?: CategoryBarMode ;
95+ code = { ` interface SegmentedBarProps {
96+ values: number[] | SegmentedBarSegment [];
97+ mode?: SegmentedBarMode ;
9898 colors?: string[];
99- marker?: CategoryBarMarker ;
99+ marker?: SegmentedBarMarker ;
100100 showLabels?: boolean;
101101 width?: number;
102102 height?: number;
@@ -115,42 +115,42 @@ Complete API documentation for the Category Bar component.
115115<Source
116116 language = " typescript"
117117 code = { ` // Main exports
118- import { CategoryBar, CategoryBarUnresponsive } from '@automattic/charts';
118+ import { SegmentedBar, SegmentedBarUnresponsive } from '@automattic/charts';
119119
120120// Type exports
121121import type {
122- CategoryBarProps ,
123- CategoryBarSegment ,
124- CategoryBarMarker ,
125- CategoryBarMode ,
122+ SegmentedBarProps ,
123+ SegmentedBarSegment ,
124+ SegmentedBarMarker ,
125+ SegmentedBarMode ,
126126} from '@automattic/charts';
127127
128128// Direct import (tree-shakeable)
129- import { CategoryBar } from '@automattic/charts/category -bar'; ` }
129+ import { SegmentedBar } from '@automattic/charts/segmented -bar'; ` }
130130/>
131131
132132## Component Variants
133133
134- ### CategoryBar (Responsive)
134+ ### SegmentedBar (Responsive)
135135
136136The default export that automatically adapts to container width:
137137
138138<Source
139139 language = " jsx"
140- code = { ` import { CategoryBar } from '@automattic/charts';
140+ code = { ` import { SegmentedBar } from '@automattic/charts';
141141
142- <CategoryBar values={[30, 40, 30]} height={8} /> ` }
142+ <SegmentedBar values={[30, 40, 30]} height={8} /> ` }
143143/>
144144
145- ### CategoryBarUnresponsive
145+ ### SegmentedBarUnresponsive
146146
147147Fixed-size variant that requires explicit width:
148148
149149<Source
150150 language = " jsx"
151- code = { ` import { CategoryBarUnresponsive } from '@automattic/charts';
151+ code = { ` import { SegmentedBarUnresponsive } from '@automattic/charts';
152152
153- <CategoryBarUnresponsive values={[30, 40, 30]} width={400} height={8} /> ` }
153+ <SegmentedBarUnresponsive values={[30, 40, 30]} width={400} height={8} /> ` }
154154/>
155155
156156## CSS Classes
@@ -159,19 +159,19 @@ The component uses CSS Modules with the following class structure:
159159
160160| Class | Description |
161161| -------| -------------|
162- | ` .categoryBar ` | Root container element |
163- | ` .categoryBar --empty ` | Applied when values array is empty |
164- | ` .categoryBar__bar ` | The horizontal bar container |
165- | ` .categoryBar__segment ` | Individual segment elements |
166- | ` .categoryBar__segment --first ` | First segment (has left border radius) |
167- | ` .categoryBar__segment --last ` | Last segment (has right border radius) |
168- | ` .categoryBar__marker ` | Position marker element |
169- | ` .categoryBar__marker --animated ` | Marker with animation enabled |
170- | ` .categoryBar__labels ` | Labels container |
171- | ` .categoryBar__label ` | Individual label elements |
172- | ` .categoryBar__tooltip ` | Tooltip container |
173- | ` .categoryBar__tooltipLabel ` | Tooltip label text |
174- | ` .categoryBar__tooltipValue ` | Tooltip value text |
162+ | ` .segmentedBar ` | Root container element |
163+ | ` .segmentedBar --empty ` | Applied when values array is empty |
164+ | ` .segmentedBar__bar ` | The horizontal bar container |
165+ | ` .segmentedBar__segment ` | Individual segment elements |
166+ | ` .segmentedBar__segment --first ` | First segment (has left border radius) |
167+ | ` .segmentedBar__segment --last ` | Last segment (has right border radius) |
168+ | ` .segmentedBar__marker ` | Position marker element |
169+ | ` .segmentedBar__marker --animated ` | Marker with animation enabled |
170+ | ` .segmentedBar__labels ` | Labels container |
171+ | ` .segmentedBar__label ` | Individual label elements |
172+ | ` .segmentedBar__tooltip ` | Tooltip container |
173+ | ` .segmentedBar__tooltipLabel ` | Tooltip label text |
174+ | ` .segmentedBar__tooltipValue ` | Tooltip value text |
175175
176176## Display Modes
177177
@@ -216,11 +216,11 @@ The component uses `GlobalChartsProvider` for theming:
216216
217217<Source
218218 language = " jsx"
219- code = { ` import { GlobalChartsProvider, CategoryBar } from '@automattic/charts';
219+ code = { ` import { GlobalChartsProvider, SegmentedBar } from '@automattic/charts';
220220import { jetpackTheme } from '@automattic/charts/providers';
221221
222222<GlobalChartsProvider theme={jetpackTheme}>
223- <CategoryBar values={[30, 40, 30]} width={400} />
223+ <SegmentedBar values={[30, 40, 30]} width={400} />
224224</GlobalChartsProvider> ` }
225225/>
226226
@@ -236,7 +236,7 @@ Colors are applied in this priority order:
236236
237237| Scenario | Behavior |
238238| ----------| ----------|
239- | Empty ` values ` array | Renders empty placeholder with ` data-testid="category -bar-empty" ` |
239+ | Empty ` values ` array | Renders empty placeholder with ` data-testid="segmented -bar-empty" ` |
240240| Single segment | Renders full-width bar |
241241| All zero values | Equal mode: equal segments; Proportional: equal segments |
242242| Marker value > total | Marker clamped to 100% |
@@ -248,11 +248,11 @@ For testing, the component provides these test IDs:
248248
249249| Test ID | Description |
250250| ---------| -------------|
251- | ` category -bar` | Main component container |
252- | ` category -bar-empty` | Empty state container |
253- | ` category -bar-segment-{index}` | Individual segments (0-indexed) |
254- | ` category -bar-marker` | Position marker |
255- | ` category -bar-label-{index}` | Cumulative labels (0-indexed) |
251+ | ` segmented -bar` | Main component container |
252+ | ` segmented -bar-empty` | Empty state container |
253+ | ` segmented -bar-segment-{index}` | Individual segments (0-indexed) |
254+ | ` segmented -bar-marker` | Position marker |
255+ | ` segmented -bar-label-{index}` | Cumulative labels (0-indexed) |
256256
257257## Performance Notes
258258
0 commit comments