{
  "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",
  "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.",
  "documentation": {
    "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."
  },
  "source": {
    "path": "packages/design-system/src/components/visualizations/BarChart/BarChart.tsx",
    "code": "import React, { useMemo } from 'react';\nimport { cn } from '../../../utilities';\nimport { BarChartPeriodControls } from './BarChartPeriodControls';\nimport type { BarChartProps, BarChartStack } from '../types';\nimport {\n    BAR_CHART_HEIGHT,\n    BAR_CHART_PADDING,\n    BAR_CHART_WIDTH,\n    getBarChartBars,\n    getBarChartStackSegments,\n    getChartValues,\n} from '../barChartGraphics';\nimport { normalizeChartValues } from '../numberUtils';\nimport { useBarChartScrubber } from './useBarChartScrubber';\nimport styles from './BarChart.module.scss';\n\n/**\n * Renders vertical bars over an ordered sequence — usually time buckets — with optional stacked\n * segments and a period toggle below the plot. Reach for it when the reader may want to inspect\n * individual buckets: it is the only chart in this family that scrubs.\n */\nexport function BarChart<TPeriod extends string = string>({\n    values,\n    stacks,\n    periods,\n    activePeriod,\n    onPeriodChange,\n    onScrubStart,\n    onScrub,\n    onScrubEnd,\n    ariaLabel,\n    testId,\n}: BarChartProps<TPeriod>) {\n    const safeValues = useMemo(() => normalizeChartValues(getChartValues(values, stacks)), [stacks, values]);\n    const maxValue = Math.max(...safeValues, 1);\n    const isInteractiveChart = Boolean(onScrub || onScrubStart || onScrubEnd);\n    const bars = useMemo(() => getBarChartBars(safeValues, maxValue), [maxValue, safeValues]);\n    const {\n        activeIndex,\n        isScrubbing,\n        selectedIndex,\n        chartValueText,\n        endScrub,\n        handleKeyDown,\n        handlePointerDown,\n        handlePointerMove,\n    } = useBarChartScrubber({\n        safeValues,\n        isInteractiveChart,\n        onScrubStart,\n        onScrub,\n        onScrubEnd,\n    });\n    let chartRole: 'slider' | 'img' | undefined;\n\n    if (isInteractiveChart) {\n        chartRole = 'slider';\n    } else if (ariaLabel) {\n        chartRole = 'img';\n    }\n\n    return (\n        <div\n            className={cn(styles.barChartRoot, isInteractiveChart && styles.barChartRootInteractive)}\n            data-testid={testId}\n        >\n            <svg\n                className={cn(styles.barChart, isInteractiveChart && styles.barChartInteractive)}\n                viewBox={`0 0 ${BAR_CHART_WIDTH} ${BAR_CHART_HEIGHT}`}\n                role={chartRole}\n                aria-label={isInteractiveChart ? ariaLabel ?? 'Chart scrubber' : ariaLabel}\n                aria-hidden={!isInteractiveChart && !ariaLabel ? true : undefined}\n                aria-valuemin={isInteractiveChart ? 1 : undefined}\n                aria-valuemax={isInteractiveChart ? safeValues.length : undefined}\n                aria-valuenow={isInteractiveChart ? selectedIndex + 1 : undefined}\n                aria-valuetext={chartValueText}\n                tabIndex={isInteractiveChart ? 0 : undefined}\n                data-testid={testId ? `${testId}-plot` : undefined}\n                onKeyDown={isInteractiveChart ? handleKeyDown : undefined}\n                onBlur={isInteractiveChart ? endScrub : undefined}\n                onPointerDown={isInteractiveChart ? handlePointerDown : undefined}\n                onPointerMove={isInteractiveChart ? handlePointerMove : undefined}\n                onPointerUp={isInteractiveChart ? endScrub : undefined}\n                onPointerCancel={isInteractiveChart ? endScrub : undefined}\n            >\n                {bars.map(bar => (\n                    <Bar\n                        key={bar.index}\n                        bar={bar}\n                        stack={stacks?.[bar.index]}\n                        maxValue={maxValue}\n                        activeIndex={activeIndex}\n                        isScrubbing={isScrubbing}\n                    />\n                ))}\n            </svg>\n            <BarChartPeriodControls\n                periods={periods}\n                activePeriod={activePeriod}\n                onPeriodChange={onPeriodChange}\n                testId={testId}\n            />\n        </div>\n    );\n}\n\ninterface BarProps {\n    bar: ReturnType<typeof getBarChartBars>[number];\n    stack?: BarChartStack;\n    maxValue: number;\n    activeIndex: number | null;\n    isScrubbing: boolean;\n}\n\nfunction Bar({ bar, stack, maxValue, activeIndex, isScrubbing }: BarProps) {\n    const isActive = activeIndex === bar.index;\n    const hasData = bar.height > 0;\n    const segments = getBarChartStackSegments(stack, maxValue);\n\n    return (\n        <>\n            <rect\n                className={cn(styles.barTrack, isActive && !hasData && styles.barTrackActive)}\n                x={bar.x}\n                y={BAR_CHART_PADDING / 2}\n                width={bar.width}\n                height={BAR_CHART_HEIGHT - BAR_CHART_PADDING}\n                rx={2}\n            />\n            {segments.length > 0 &&\n                segments.map((segment, index) => (\n                    <rect\n                        // eslint-disable-next-line react/no-array-index-key -- segment order is stable within a static stack\n                        key={index}\n                        className={cn(\n                            styles.barValue,\n                            styles.barSegment,\n                            isActive && styles.barValueActive,\n                            isScrubbing && !isActive && styles.barValueInactive\n                        )}\n                        x={bar.x}\n                        y={segment.y}\n                        width={bar.width}\n                        height={segment.height}\n                        rx={1}\n                        style={\n                            segment.color\n                                ? ({ '--bar-segment-color': segment.color } as React.CSSProperties)\n                                : undefined\n                        }\n                    >\n                        <title>\n                            {stack?.label}\n                            {stack?.label && segment.label ? ': ' : ''}\n                            {segment.label}\n                            {segment.label ? ' ' : ''}\n                            {segment.value.toLocaleString()}\n                        </title>\n                    </rect>\n                ))}\n            {segments.length === 0 && hasData && (\n                <rect\n                    className={cn(\n                        styles.barValue,\n                        isActive && styles.barValueActive,\n                        isScrubbing && !isActive && styles.barValueInactive\n                    )}\n                    x={bar.x}\n                    // Baseline must match where getBarChartStackSegments starts its cursor, or\n                    // plain and stacked bars sit on different lines.\n                    y={BAR_CHART_HEIGHT - BAR_CHART_PADDING / 2 - bar.height}\n                    width={bar.width}\n                    height={bar.height}\n                    rx={2}\n                />\n            )}\n        </>\n    );\n}\n"
  },
  "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": []
  },
  "spec_source": "packages/design-system/src/components/visualizations/BarChart/BarChart.spec.json",
  "guidance_source": {
    "path": "packages/design-system/src/components/visualizations/BarChart/BarChart.mdx",
    "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './BarChart.stories';\nimport barChartSpec from './BarChart.spec.json';\n\n<Meta of={Stories} />\n\n# BarChart\n\nVertical bars over an ordered sequence — almost always time buckets — and the one interactive\nmember of the chart family.\n\n<Canvas of={Stories.Interactive} />\n\n## When to use\n\nUse 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.\n\n## Stacked breakdown\n\nEach bar can be a `stacks` breakdown; segment `color` drives each band.\n\n<Canvas of={Stories.Stacked} />\n\n## Design Guidelines\n\n<ComponentSpec spec={barChartSpec} />\n\n## Props\n\n<Controls of={Stories.Interactive} />\n"
  },
  "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<TPeriod>[] | undefined",
      "declared_type": "ReadonlyArray<DataVisualizationPeriod<TPeriod>>",
      "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-<lowercased id>`.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 210
      }
    }
  ],
  "prop_shapes": {},
  "examples": [],
  "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"
    }
  ],
  "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": [
    {
      "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"
    }
  ],
  "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<typeof BarChart> = {\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<typeof BarChart>;\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<number | null>(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            <Card>\n                <Card.Header layout='row' justify='between' align='center'>\n                    <Text variant='body' color='primary'>\n                        Volume\n                    </Text>\n                    <Text variant='display-2' color='primary'>\n                        {(scrubbed ?? values.reduce((sum, value) => sum + value, 0)).toLocaleString()}\n                    </Text>\n                </Card.Header>\n                <Card.Body>\n                    <BarChart\n                        values={values}\n                        periods={[\n                            { id: '1M', label: '1M' },\n                            { id: '6M', label: '6M' },\n                            { id: '1Y', label: '1Y' },\n                            { id: 'All', label: 'All' },\n                        ]}\n                        activePeriod={period}\n                        onPeriodChange={setPeriod}\n                        onScrub={(_, value) => setScrubbed(value)}\n                        onScrubEnd={() => setScrubbed(null)}\n                        ariaLabel='Volume by period'\n                        testId='bar-chart-volume'\n                    />\n                </Card.Body>\n            </Card>\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"
  },
  "links": {
    "human": "/component-barchart",
    "json": "/data/components/barchart.json",
    "markdown": "/data/components/barchart.md",
    "storybook": "/storybook/?path=/story/cloaked-design-system-visualizations-barchart--interactive"
  },
  "contract_status": "preview",
  "contract_kind": "source-derived",
  "approval": "required",
  "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<TPeriod>",
        "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<TPeriod>[] | undefined",
            "declared_type": "ReadonlyArray<DataVisualizationPeriod<TPeriod>>",
            "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-<lowercased id>`.",
            "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<TPeriod extends string = string> {\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<TPeriod extends string = string> {\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<DataVisualizationPeriod<TPeriod>>;\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-<lowercased id>`.\n     */\n    testId?: string;\n}"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "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"
    }
  },
  "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."
    }
  ],
  "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."
  }
}