{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "barchart", "name": "BarChart", "category": "Visualizations", "contract_status": "preview", "contract_kind": "source-derived", "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." }, "approval": "required", "visual_reference": { "stories": [ { "id": "cloaked-design-system-visualizations-barchart--interactive", "name": "Interactive", "title": "Cloaked Design System/Visualizations/BarChart", "exportName": "Interactive", "source_path": "packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx", "source_digest": "9d2e0744ba288540ca550f080272a1583b9f4b5411788f3af1f2ded6f8024e84", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--interactive&viewMode=story" }, { "id": "cloaked-design-system-visualizations-barchart--edge-values", "name": "Edge Values", "title": "Cloaked Design System/Visualizations/BarChart", "exportName": "EdgeValues", "source_path": "packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx", "source_digest": "9d2e0744ba288540ca550f080272a1583b9f4b5411788f3af1f2ded6f8024e84", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--edge-values&viewMode=story" }, { "id": "cloaked-design-system-visualizations-barchart--single-bar", "name": "Single Bar", "title": "Cloaked Design System/Visualizations/BarChart", "exportName": "SingleBar", "source_path": "packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx", "source_digest": "9d2e0744ba288540ca550f080272a1583b9f4b5411788f3af1f2ded6f8024e84", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--single-bar&viewMode=story" }, { "id": "cloaked-design-system-visualizations-barchart--stacked", "name": "Stacked", "title": "Cloaked Design System/Visualizations/BarChart", "exportName": "Stacked", "source_path": "packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx", "source_digest": "9d2e0744ba288540ca550f080272a1583b9f4b5411788f3af1f2ded6f8024e84", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--stacked&viewMode=story" }, { "id": "cloaked-design-system-visualizations-barchart--empty", "name": "Empty", "title": "Cloaked Design System/Visualizations/BarChart", "exportName": "Empty", "source_path": "packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx", "source_digest": "9d2e0744ba288540ca550f080272a1583b9f4b5411788f3af1f2ded6f8024e84", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--empty&viewMode=story" }, { "id": "cloaked-design-system-visualizations-barchart--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/BarChart", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx", "source_digest": "9d2e0744ba288540ca550f080272a1583b9f4b5411788f3af1f2ded6f8024e84", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-barchart--dark-theme&viewMode=story" } ], "name": "BarChart", "id": "barchart", "category": "Visualizations" }, "stories_source": { "path": "packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsx", "code": "import React, { useState } from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { BarChart } from './BarChart';\nimport { Card } from '../../cards/Card/Card';\nimport { Text } from '../../primitives/Text/Text';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport type { BarChartStack } from '../types';\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Visualizations/BarChart',\n component: BarChart,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Vertical bars over an ordered sequence — almost always time buckets (days, weeks). ' +\n 'It is the interactive member of the chart family: pass `onScrub`/`onScrubStart`/' +\n '`onScrubEnd` to make the plot a drag/keyboard scrubber (`role=\"slider\"`), and ' +\n '`periods` + `activePeriod` + `onPeriodChange` to add a range toggle (1M / 6M / 1Y / ' +\n 'All). Use `stacks` for a stacked breakdown per bar (categories summed bottom-to-top). ' +\n 'Prefer `LineChart` for a smooth continuous trend or overlaying many series, ' +\n '`CategoryBars` for a handful of labeled categories with readable values, and ' +\n '`ActionOrbs` for a proportional 2–4 category summary. Set `testId` on the chart and ' +\n 'the scrubber (`{testId}-plot`) and period buttons (`{testId}-period-{id}`) derive ' +\n 'from it automatically.',\n },\n },\n },\n argTypes: {\n values: {\n ...disabledControl,\n description: 'Bar heights rendered in order; non-negative numbers, one per bar.',\n },\n stacks: {\n ...disabledControl,\n description: 'Optional per-bar stacked segments (summed bottom-to-top) instead of a single value bar.',\n },\n periods: { ...disabledControl, description: 'Optional range-toggle options shown below the chart.' },\n activePeriod: { control: 'text', description: 'Id of the selected `periods` entry.' },\n onPeriodChange: { ...disabledControl, description: 'Fires with the chosen period id.' },\n onScrubStart: {\n ...disabledControl,\n description: 'Presence of any scrub callback switches the plot to an interactive `role=\"slider\"`.',\n },\n onScrub: { ...disabledControl, description: 'Fires with the active bar index and value while scrubbing.' },\n onScrubEnd: { ...disabledControl, description: 'Fires when a scrub gesture ends or the plot blurs.' },\n ariaLabel: {\n control: 'text',\n description: 'Accessible label; sets `role=\"img\"` (static) or labels the slider (interactive).',\n },\n testId: {\n control: 'text',\n description: 'Root selector; the scrubber and period buttons derive their test ids from it.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nconst edgeValues = [0, 12, 100, 48, 0, 72, 100, 16];\nconst dataRemovalColors = {\n name: '#00c776',\n email: '#ffd447',\n phone: '#e172eb',\n address: '#0067ff',\n family: '#003677',\n};\n\nconst stackedData = buildCumulativeStacks();\n\nexport const Interactive: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'Scrub callbacks turn the plot into a `role=\"slider\"` (drag or arrow-key it); `periods` ' +\n 'add the range toggle. Header value reflects the scrubbed bar or the total when idle.',\n },\n },\n },\n render: function InteractiveStory() {\n const [period, setPeriod] = useState('All');\n const [scrubbed, setScrubbed] = useState(null);\n const values = [2, 8, 4, 14, 18, 9, 20, 22, 12, 28, 34, 18, 40, 44, 38, 52, 48, 58, 62, 70];\n\n return (\n \n \n \n Volume\n \n \n {(scrubbed ?? values.reduce((sum, value) => sum + value, 0)).toLocaleString()}\n \n \n \n setScrubbed(value)}\n onScrubEnd={() => setScrubbed(null)}\n ariaLabel='Volume by period'\n testId='bar-chart-volume'\n />\n \n \n );\n },\n};\n\nexport const EdgeValues: Story = {\n parameters: {\n docs: { description: { story: 'Mixed zeros and max values — confirms empty bars and full-height bars.' } },\n },\n args: {\n values: edgeValues,\n ariaLabel: 'Bar chart with zero and max values',\n },\n};\n\nexport const SingleBar: Story = {\n parameters: {\n docs: { description: { story: 'Degenerate single-value case.' } },\n },\n args: {\n values: [64],\n ariaLabel: 'Single bar value',\n },\n};\n\nexport const Stacked: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Each bar is a `stacks` breakdown summed bottom-to-top; segment `color` drives each band.',\n },\n },\n },\n args: {\n values: stackedData.map(stack => stack.segments.reduce((sum, segment) => sum + segment.value, 0)),\n stacks: stackedData,\n ariaLabel: 'Data removal history by category',\n },\n};\n\nexport const Empty: Story = {\n parameters: {\n docs: { description: { story: 'No values — renders empty tracks only.' } },\n },\n args: {\n values: [],\n ariaLabel: 'Empty bar chart',\n },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n args: {\n values: stackedData.map(stack => stack.segments.reduce((sum, segment) => sum + segment.value, 0)),\n stacks: stackedData,\n ariaLabel: 'Data removal history by category',\n },\n};\n\nfunction buildCumulativeStacks(): BarChartStack[] {\n const totals = { family: 0, address: 0, phone: 0, email: 0, name: 0 };\n\n return Array.from({ length: 30 }, (_, index) => {\n const date = new Date();\n date.setDate(date.getDate() - (29 - index));\n\n const hasNewRemovals = index < 4 || index % 3 !== 1;\n if (hasNewRemovals) {\n const progress = index / 29;\n totals.family += Math.round(1 + progress * 3);\n totals.address += Math.round(1 + progress * 4);\n totals.phone += Math.round(1 + progress * 4);\n totals.email += Math.round(1 + progress * 3);\n totals.name += Math.round(1 + progress * 5);\n }\n\n return {\n id: `day-${index + 1}`,\n label: date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' }),\n segments: [\n { label: 'Family', value: totals.family, color: dataRemovalColors.family },\n { label: 'Address', value: totals.address, color: dataRemovalColors.address },\n { label: 'Phone', value: totals.phone, color: dataRemovalColors.phone },\n { label: 'Email', value: totals.email, color: dataRemovalColors.email },\n { label: 'Name', value: totals.name, color: dataRemovalColors.name },\n ],\n };\n });\n}\n" }, "specification": { "$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": [] }, "specification_source": "packages/design-system/src/components/visualizations/BarChart/BarChart.spec.json", "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." }, "links": { "human": "/component-barchart", "json": "/data/visual/components/barchart.json", "storybook": "/storybook/?path=/story/cloaked-design-system-visualizations-barchart--interactive" } }