# BarChart Vertical bars over an ordered sequence, the interactive chart member: an optional drag or keyboard scrubber plus a range toggle, with single-value or stacked bars. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/visualizations/BarChart/BarChart.tsx ## Guidance { "summary": "Vertical bars over an ordered sequence, the interactive chart member: an optional drag or keyboard scrubber plus a range toggle, with single-value or stacked bars.", "guidance": [ { "heading": "Overview", "body": "Vertical bars over an ordered sequence — almost always time buckets — and the one interactive\nmember of the chart family." }, { "heading": "When to use", "body": "Use BarChart for a series of discrete values across an ordered x-axis (days, weeks) where the\nreader may want to inspect individual buckets. It is the only chart here that supports\nscrubbing: pass `onScrub`/`onScrubStart`/`onScrubEnd` to make the plot a drag/keyboard slider,\nand `periods` + `activePeriod` + `onPeriodChange` for a range toggle (1M / 6M / 1Y / All). Use\n`stacks` for a per-bar categorical breakdown summed bottom-to-top.\n\nPrefer `LineChart` for a smooth continuous trend or many overlaid series, `CategoryBars` for a\nhandful of labeled categories with readable values, and `ActionOrbs` for a loose proportional\n2-4 category summary.\n\nUsed on Playlist Home in `ActionsDetail` (\"Actions taken over time\") as a scrubber with a\nperiod toggle." }, { "heading": "Stacked breakdown", "body": "Each bar can be a `stacks` breakdown; segment `color` drives each band." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/visualizations/BarChart/BarChart.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "values", "type": "number[]", "declared_type": "number[]", "required": true, "description": "Bar values rendered in order.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 186 } }, { "name": "stacks", "type": "readonly BarChartStack[] | undefined", "declared_type": "readonly BarChartStack[]", "required": false, "description": "Optional stacked segments rendered instead of a single value bar.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 188 } }, { "name": "periods", "type": "readonly DataVisualizationPeriod[] | undefined", "declared_type": "ReadonlyArray>", "required": false, "description": "Optional period controls shown with the chart.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 190 } }, { "name": "activePeriod", "type": "TPeriod | undefined", "declared_type": "TPeriod", "required": false, "description": "Id of the period button shown as selected; leave unset for none.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 192 } }, { "name": "onPeriodChange", "type": "((period: TPeriod) => void) | undefined", "declared_type": "(period: TPeriod) => void", "required": false, "description": "Fires with the tapped period id — the chart never changes `values` itself.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 194 } }, { "name": "onScrubStart", "type": "(() => void) | undefined", "declared_type": "() => void", "required": false, "description": "Fires once when a scrub session begins. Passing any of the three scrub handlers is what\nturns the plot into a focusable slider.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 199 } }, { "name": "onScrub", "type": "((index: number, value: number) => void) | undefined", "declared_type": "(index: number, value: number) => void", "required": false, "description": "Called with the active bar index and value while scrubbing.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 201 } }, { "name": "onScrubEnd", "type": "(() => void) | undefined", "declared_type": "() => void", "required": false, "description": "Fires once when the session ends — pointer up, cancel, or blur — not on every move.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 203 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label for meaningful charts.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 205 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector. The plot derives `${testId}-plot` and each period button\n`${testId}-period-`.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 210 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "BarChart", "public_path": "BarChart", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "BarChart", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/visualizations/BarChart/BarChart.tsx", "line": 22 }, "props_type": "BarChartProps", "props": [ { "name": "values", "type": "number[]", "declared_type": "number[]", "required": true, "description": "Bar values rendered in order.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 186 } }, { "name": "stacks", "type": "readonly BarChartStack[] | undefined", "declared_type": "readonly BarChartStack[]", "required": false, "description": "Optional stacked segments rendered instead of a single value bar.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 188 } }, { "name": "periods", "type": "readonly DataVisualizationPeriod[] | undefined", "declared_type": "ReadonlyArray>", "required": false, "description": "Optional period controls shown with the chart.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 190 } }, { "name": "activePeriod", "type": "TPeriod | undefined", "declared_type": "TPeriod", "required": false, "description": "Id of the period button shown as selected; leave unset for none.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 192 } }, { "name": "onPeriodChange", "type": "((period: TPeriod) => void) | undefined", "declared_type": "(period: TPeriod) => void", "required": false, "description": "Fires with the tapped period id — the chart never changes `values` itself.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 194 } }, { "name": "onScrubStart", "type": "(() => void) | undefined", "declared_type": "() => void", "required": false, "description": "Fires once when a scrub session begins. Passing any of the three scrub handlers is what\nturns the plot into a focusable slider.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 199 } }, { "name": "onScrub", "type": "((index: number, value: number) => void) | undefined", "declared_type": "(index: number, value: number) => void", "required": false, "description": "Called with the active bar index and value while scrubbing.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 201 } }, { "name": "onScrubEnd", "type": "(() => void) | undefined", "declared_type": "() => void", "required": false, "description": "Fires once when the session ends — pointer up, cancel, or blur — not on every move.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 203 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label for meaningful charts.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 205 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector. The plot derives `${testId}-plot` and each period button\n`${testId}-period-`.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 210 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 24, "name": "DataVisualizationPeriod", "code": "export interface DataVisualizationPeriod {\n id: TPeriod;\n label: React.ReactNode;\n}" }, { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 29, "name": "BarChartSegment", "code": "export interface BarChartSegment {\n /** Non-negative segment value. */\n value: number;\n color?: string;\n /** Optional segment label for accessible titles. */\n label?: React.ReactNode;\n}" }, { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 37, "name": "BarChartStack", "code": "export interface BarChartStack {\n /** Stable stack identifier. */\n id: string;\n /** Optional stack label for accessible titles. */\n label?: React.ReactNode;\n /** Ordered segments rendered bottom-to-top within this bar. */\n segments: readonly BarChartSegment[];\n}" }, { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 184, "name": "BarChartProps", "code": "export interface BarChartProps {\n /** Bar values rendered in order. */\n values: number[];\n /** Optional stacked segments rendered instead of a single value bar. */\n stacks?: readonly BarChartStack[];\n /** Optional period controls shown with the chart. */\n periods?: ReadonlyArray>;\n /** Id of the period button shown as selected; leave unset for none. */\n activePeriod?: TPeriod;\n /** Fires with the tapped period id — the chart never changes `values` itself. */\n onPeriodChange?: (period: TPeriod) => void;\n /**\n * Fires once when a scrub session begins. Passing any of the three scrub handlers is what\n * turns the plot into a focusable slider.\n */\n onScrubStart?: () => void;\n /** Called with the active bar index and value while scrubbing. */\n onScrub?: (index: number, value: number) => void;\n /** Fires once when the session ends — pointer up, cancel, or blur — not on every move. */\n onScrubEnd?: () => void;\n /** Accessible label for meaningful charts. */\n ariaLabel?: string;\n /**\n * Optional test selector. The plot derives `${testId}-plot` and each period button\n * `${testId}-period-`.\n */\n testId?: string;\n}" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "BarChart", "status": "preview", "version": "1.0.0", "summary": "Vertical bars over an ordered sequence, the interactive chart member: an optional drag or keyboard scrubber plus a range toggle, with single-value or stacked bars." }, "parts": [ { "id": "plot", "label": "Plot", "description": "The SVG bar field that fills the container width.", "required": true }, { "id": "track", "label": "Bar track", "description": "The full-height rail behind each bar." }, { "id": "bar", "label": "Bar value", "description": "The value bar or stacked segments rising from the baseline." }, { "id": "period-controls", "label": "Period controls", "description": "The optional range-toggle buttons shown below the plot." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "Values, stacks, and scrub callbacks change the reading without changing the plot treatment." } }, "sizes": {} }, "variants": [ { "id": "base", "label": "Base", "description": "A vertical bar field with optional period controls and scrub callbacks.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "chart-gap", "label": "Plot-to-controls gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "plot", "period-controls" ] }, { "id": "period-radius", "label": "Period button radius", "kind": "exact", "token": "--cds-radius-lg", "value": 20, "unit": "px", "appliesTo": [ "period-controls" ] }, { "id": "period-gap", "label": "Period button gap", "kind": "exact", "token": "--cds-space-8", "value": 8, "unit": "px", "appliesTo": [ "period-controls" ] } ], "layout": { "alignment": "Bars fill the plot width evenly; period controls center below the plot.", "flow": "The plot stacks above the optional period controls.", "notes": [ "Bar geometry is drawn in SVG view-box units so the plot scales to fill the container width." ] }, "typographyAndColor": { "typography": [ { "label": "Period control", "description": "Period toggle labels use the body ramp.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Track", "description": "The rail behind each bar.", "token": "--cds-graph-bg" }, { "label": "Bar value", "description": "The default value-bar fill.", "token": "--cds-text-primary" }, { "label": "Active bar", "description": "The scrubbed bar and active track highlight.", "token": "--cds-brand" }, { "label": "Active period text", "description": "The selected period button ink on its filled pill.", "token": "--cds-bg-page" } ] }, "states": [ { "id": "static", "label": "Static", "description": "With no scrub callbacks the plot is a presentational or labeled image." }, { "id": "interactive", "label": "Interactive", "description": "Any scrub callback turns the plot into a draggable, keyboardable slider." }, { "id": "stacked", "label": "Stacked", "description": "Each bar is a stack of segments summed bottom to top." }, { "id": "empty", "label": "Empty", "description": "No values renders empty tracks only." } ], "behavior": [ { "label": "Interactive when scrubbable", "description": "Passing any scrub callback switches the plot to a slider role with arrow-key support." }, { "label": "Range toggle", "description": "periods, activePeriod, and onPeriodChange add a range toggle beneath the plot." }, { "label": "Derived test ids", "description": "The scrubber and period buttons derive their test ids from the root testId." } ], "accessibility": [ { "label": "Static label", "description": "Pass an accessible label so a static plot is announced as a meaningful image." }, { "label": "Slider semantics", "description": "When interactive the plot exposes slider min, max, current index, and a value text, and keeps an accessible name from ariaLabel with a default scrubber label as fallback." }, { "label": "Keyboard scrubbing", "description": "The interactive plot is focusable and moves the active bar with arrow keys." } ], "contentAdaptation": [ { "label": "Time buckets", "description": "Use BarChart for an ordered sequence, almost always time buckets; use CategoryBars for named categories." }, { "label": "Stacked breakdown", "description": "Use stacks for a per-bar category breakdown summed bottom to top." } ], "motionHaptics": { "motion": [ { "label": "Active transition", "description": "Bars ease their active and inactive treatment while scrubbing; no mount animation." } ], "haptics": [ { "label": "No feedback", "description": "The chart requests no haptic feedback; a consumer may add it around scrub events." } ] }, "platformDifferences": [] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-space-12", "light": "12px", "dark": "12px" }, { "name": "--cds-radius-lg", "light": "20px", "dark": "20px" }, { "name": "--cds-space-8", "light": "8px", "dark": "8px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-graph-bg", "light": "#0b0b0a0d", "dark": "#ffffff0d" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-brand", "light": "#ff550c", "dark": "#ff550c" }, { "name": "--cds-bg-page", "light": "#f3f1ed", "dark": "#141410" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Interactive](/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--interactive&viewMode=story) | export: Interactive | source: packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx - [Edge Values](/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--edge-values&viewMode=story) | export: EdgeValues | source: packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx - [Single Bar](/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--single-bar&viewMode=story) | export: SingleBar | source: packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx - [Stacked](/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--stacked&viewMode=story) | export: Stacked | source: packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx - [Empty](/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--empty&viewMode=story) | export: Empty | source: packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.