@ds-mo/ui 12.9.0 → 13.0.0

package/dist/mcp-data/registry/chart-bar-stacked.json

@@ -1,230 +0,0 @@
-{
-  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
-  "name": "chart-bar-stacked",
-  "title": "ChartBarStacked",
-  "description": "Multi-series stacked bar chart for comparing raw totals or normalized 0–100% composition across ordered categories and time buckets.",
-  "type": "registry:ui",
-  "meta": {
-    "library": "@ds-mo/ui",
-    "distribution": "npm",
-    "storybook": "https://zainadeel.github.io/compomo/?path=/story/chart-bar-stacked",
-    "source": "src/wc/components/ChartBarStacked/ChartBarStacked.tsx",
-    "intentStatus": "complete",
-    "intent": {
-      "audience": "specialized",
-      "status": "experimental",
-      "summary": "Multi-series stacked bar chart for comparing raw totals or normalized 0–100% composition across ordered categories and time buckets.",
-      "useWhen": [
-        "Users need to compare both a category total and the contribution of several consistent series.",
-        "A time series needs to show how its composition changes across equal time buckets.",
-        "Every category should normalize to 100% so proportional composition can be compared independently of total magnitude."
-      ],
-      "avoidWhen": [
-        "Users need to compare individual series values precisely across categories; use grouped bars or separate charts.",
-        "The visualization has only one measure per category; use ChartBar.",
-        "The primary task is following continuous trends; use ChartLine.",
-        "Series contain negative values or do not align with the shared category list."
-      ],
-      "alternatives": [
-        {
-          "when": "Each category contains one independent value.",
-          "component": "component:ds-chart-bar",
-          "reason": "ChartBar provides the simpler single-series magnitude comparison."
-        },
-        {
-          "when": "Users need to follow one or more trends rather than compare stack composition.",
-          "component": "component:ds-chart-line",
-          "reason": "ChartLine preserves each series as a continuous path across the ordered axis."
-        },
-        {
-          "when": "One category's parts-to-whole composition is the focus.",
-          "component": "component:ds-chart-donut",
-          "reason": "ChartDonut provides the dedicated single-total composition treatment."
-        }
-      ],
-      "commonlyComposedWith": [
-        "component:ds-chart-legend",
-        "component:ds-card-shell-data-viz",
-        "component:ds-tooltip-data-viz"
-      ],
-      "accessibility": [
-        "Provide a visible legend or adjacent textual summary that names every series; do not rely on segment color alone.",
-        "The chart image name includes each category and series value, using normalized percentages in percentage mode.",
-        "Use an adjacent data table when exact cross-category comparisons are necessary to complete the task."
-      ],
-      "states": [
-        "Stacked mode preserves raw magnitudes and scales the y-axis to the largest category total.",
-        "Percentage mode normalizes each non-empty category independently and renders a fixed 0%, 25%, 50%, 75%, and 100% axis.",
-        "Series render bottom-to-top in authored order; keep that order and color mapping stable across categories.",
-        "Stacked mode gives only the top visible segment 2px top corners. Percentage mode keeps every corner square because the normalized stack touches both axis edges.",
-        "Adjacent segments are separated by a non-scaling 1px gap; the stack's outer edges do not receive that separator.",
-        "Negative values are unsupported and render as zero; the owning product supplies loading, empty, and error states."
-      ],
-      "responsiveBehavior": [
-        "Width and height provide the standalone intrinsic viewport; constrained card regions are measured and reflow both axes to their rendered pixel dimensions.",
-        "Responsive layout changes stack positions and plot extents without scaling SVG text, strokes, separators, corner radii, or margins.",
-        "The parent chooses how many time buckets remain legible at each width.",
-        "Pre-format category labels and reduce bucket count before rendering when horizontal space becomes constrained."
-      ],
-      "frameworkCaveats": {
-        "customElements": [
-          "Assign series and categories as JavaScript properties and keep every series aligned to the category count."
-        ],
-        "react": [
-          "Pass stable series and category arrays; choose percentage variant only when each category represents a meaningful whole."
-        ],
-        "angular": [
-          "Bind series and categories as properties; choose percentage variant only when each category represents a meaningful whole."
-        ]
-      },
-      "references": [
-        {
-          "label": "Storybook examples",
-          "path": "src/wc/components/ChartBarStacked/ChartBarStacked.stories.ts"
-        }
-      ]
-    },
-    "api": {
-      "props": {
-        "categories": {
-          "type": "string[]",
-          "resolvedType": "string[]",
-          "default": "[]",
-          "required": false,
-          "mutable": false,
-          "description": "X-axis labels — must match each series' `data` length. Set as a JS property."
-        },
-        "height": {
-          "type": "number",
-          "resolvedType": "number",
-          "attribute": "height",
-          "default": "240",
-          "required": false,
-          "mutable": false,
-          "description": "Standalone intrinsic height. Container constraints reflow the plot at rendered pixel size."
-        },
-        "series": {
-          "type": "ChartSeries[]",
-          "resolvedType": "ChartSeries[]",
-          "default": "[]",
-          "required": false,
-          "mutable": false,
-          "description": "Ordered stack series. Set as a JS property (not an HTML attribute)."
-        },
-        "variant": {
-          "type": "ChartBarStackedVariant",
-          "resolvedType": "\"percentage\" | \"stacked\"",
-          "attribute": "variant",
-          "default": "'stacked'",
-          "required": false,
-          "mutable": false
-        },
-        "width": {
-          "type": "number",
-          "resolvedType": "number",
-          "attribute": "width",
-          "default": "480",
-          "required": false,
-          "mutable": false,
-          "description": "Standalone intrinsic width. Container constraints reflow the plot at rendered pixel size."
-        }
-      },
-      "events": [],
-      "methods": [],
-      "slots": []
-    },
-    "props": {
-      "categories": {
-        "type": "string[]",
-        "resolvedType": "string[]",
-        "default": "[]",
-        "required": false,
-        "mutable": false,
-        "description": "X-axis labels — must match each series' `data` length. Set as a JS property."
-      },
-      "height": {
-        "type": "number",
-        "resolvedType": "number",
-        "attribute": "height",
-        "default": "240",
-        "required": false,
-        "mutable": false,
-        "description": "Standalone intrinsic height. Container constraints reflow the plot at rendered pixel size."
-      },
-      "series": {
-        "type": "ChartSeries[]",
-        "resolvedType": "ChartSeries[]",
-        "default": "[]",
-        "required": false,
-        "mutable": false,
-        "description": "Ordered stack series. Set as a JS property (not an HTML attribute)."
-      },
-      "variant": {
-        "type": "ChartBarStackedVariant",
-        "resolvedType": "\"percentage\" | \"stacked\"",
-        "attribute": "variant",
-        "default": "'stacked'",
-        "required": false,
-        "mutable": false
-      },
-      "width": {
-        "type": "number",
-        "resolvedType": "number",
-        "attribute": "width",
-        "default": "480",
-        "required": false,
-        "mutable": false,
-        "description": "Standalone intrinsic width. Container constraints reflow the plot at rendered pixel size."
-      }
-    },
-    "events": [],
-    "methods": [],
-    "slots": [],
-    "exports": {
-      "customElement": "ds-chart-bar-stacked",
-      "react": "DsChartBarStacked",
-      "angular": "DsChartBarStacked"
-    },
-    "consumption": {
-      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
-      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
-      "customElements": {
-        "import": "import '@ds-mo/ui/dist/components/ds-chart-bar-stacked.js';",
-        "example": "<ds-chart-bar-stacked></ds-chart-bar-stacked>"
-      },
-      "react": {
-        "import": "import { DsChartBarStacked } from '@ds-mo/ui/react';",
-        "example": "<DsChartBarStacked />"
-      },
-      "angular": {
-        "import": "import { DsChartBarStacked } from '@ds-mo/ui/angular/ds-chart-bar-stacked';",
-        "example": "<ds-chart-bar-stacked></ds-chart-bar-stacked>"
-      },
-      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: categories, series.",
-      "peerDependencies": {
-        "required": [
-          "@ds-mo/tokens ^5.0.0",
-          "@ds-mo/icons ^6.4.0"
-        ],
-        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
-      }
-    }
-  },
-  "dependencies": [
-    "@ds-mo/ui",
-    "@ds-mo/tokens"
-  ],
-  "registryDependencies": [],
-  "files": [
-    {
-      "path": "src/wc/components/ChartBarStacked/ChartBarStacked.css",
-      "content": ":host {\n  display: inline-flex;\n  max-width: 100%;\n  font-family: var(--typography-font-family);\n}\n\n.chart-bar-stacked__svg {\n  display: block;\n  width: 100%;\n  height: 100%;\n}\n\n.chart-bar-stacked__gridline {\n  stroke: var(--color-border-tertiary);\n  stroke-width: var(--dimension-stroke-width-012);\n  vector-effect: non-scaling-stroke;\n}\n\n/* Matches ds-text text-caption regular (SVG cannot host ds-text). */\n.chart-bar-stacked__axis-label {\n  fill: var(--color-foreground-secondary);\n  font-family: var(--typography-font-family);\n  font-size: var(--typography-fontsize-xs);\n  font-weight: var(--typography-weight-medium);\n  letter-spacing: var(--typography-letterspacing-positive);\n  text-transform: uppercase;\n}\n\n.chart-bar-stacked__segment-shape--rounded {\n  rx: var(--dimension-radius-025);\n}\n\n.chart-bar-stacked__segment-separator {\n  stroke: var(--color-background-primary);\n  stroke-width: var(--dimension-stroke-width-012);\n  stroke-linecap: butt;\n  vector-effect: non-scaling-stroke;\n}\n",
-      "type": "registry:ui"
-    },
-    {
-      "path": "src/wc/components/ChartBarStacked/ChartBarStacked.tsx",
-      "content": "import { Component, Prop, State, Watch, h, Host } from '@stencil/core';\nimport { scaleBand, scaleLinear } from 'd3-scale';\nimport { categoryColor } from '../../utils/chart-colors';\nimport { formatPercentage } from '../../utils';\nimport { resolveCartesianChartLayout } from '../../utils/cartesian-chart-layout';\nimport {\n  ChartViewportController,\n  type ChartViewportSize,\n} from '../../utils/chart-viewport-controller';\nimport type { ChartSeries } from '../../utils/chart-types';\n\nexport type ChartBarStackedVariant = 'stacked' | 'percentage';\n\nconst PERCENTAGE_TICKS = [0, 25, 50, 75, 100];\n\n@Component({\n  tag: 'ds-chart-bar-stacked',\n  styleUrl: 'ChartBarStacked.css',\n  scoped: true,\n})\nexport class ChartBarStacked {\n  /** Ordered stack series. Set as a JS property (not an HTML attribute). */\n  @Prop() series: ChartSeries[] = [];\n  /** X-axis labels — must match each series' `data` length. Set as a JS property. */\n  @Prop() categories: string[] = [];\n  @Prop() variant: ChartBarStackedVariant = 'stacked';\n  /** Standalone intrinsic width. Container constraints reflow the plot at rendered pixel size. */\n  @Prop() width: number = 480;\n  /** Standalone intrinsic height. Container constraints reflow the plot at rendered pixel size. */\n  @Prop() height: number = 240;\n\n  @State() private viewport: ChartViewportSize | undefined;\n\n  private viewportController: ChartViewportController | null = null;\n  private svgEl: SVGElement | null = null;\n\n  componentDidLoad() {\n    this.connectViewportController();\n  }\n\n  connectedCallback() {\n    if (this.svgEl && !this.viewportController) this.connectViewportController();\n  }\n\n  componentDidRender() {\n    if (!this.viewportController) this.connectViewportController();\n  }\n\n  private connectViewportController() {\n    if (!this.svgEl) return;\n    this.viewportController = new ChartViewportController(this.svgEl, viewport => {\n      if (\n        viewport.width !== this.viewport?.width ||\n        viewport.height !== this.viewport?.height\n      ) {\n        this.viewport = viewport;\n      }\n    });\n    this.viewportController.connect();\n  }\n\n  disconnectedCallback() {\n    this.viewportController?.disconnect();\n    this.viewportController = null;\n  }\n\n  @Watch('width')\n  @Watch('height')\n  handleIntrinsicSizeChange() {\n    this.viewport = undefined;\n    if (typeof requestAnimationFrame === 'function') {\n      requestAnimationFrame(() => this.viewportController?.measure());\n    }\n  }\n\n  private valuesForCategory(categoryIndex: number) {\n    return this.series.map(series => Math.max(0, series.data[categoryIndex] ?? 0));\n  }\n\n  private accessibleLabel() {\n    return this.categories\n      .map((category, categoryIndex) => {\n        const values = this.valuesForCategory(categoryIndex);\n        const total = values.reduce((sum, value) => sum + value, 0);\n        const details = this.series\n          .map((series, seriesIndex) => {\n            const value = values[seriesIndex];\n            const visibleValue = this.variant === 'percentage'\n              ? formatPercentage(total ? value / total : 0, 1)\n              : String(value);\n            return `${series.name}: ${visibleValue}`;\n          })\n          .join(', ');\n        return `${category}: ${details}`;\n      })\n      .join('; ');\n  }\n\n  render() {\n    const viewportWidth = this.viewport?.width ?? this.width;\n    const viewportHeight = this.viewport?.height ?? this.height;\n    const { margin, axisLabelGap, categoryLabelOffset } =\n      resolveCartesianChartLayout();\n    const innerWidth = Math.max(0, viewportWidth - margin.left - margin.right);\n    const innerHeight = Math.max(0, viewportHeight - margin.top - margin.bottom);\n    const categoryValues = this.categories.map((_, index) => this.valuesForCategory(index));\n    const totals = categoryValues.map(values =>\n      values.reduce((sum, value) => sum + value, 0)\n    );\n    const yMax = this.variant === 'percentage' ? 100 : Math.max(0, ...totals);\n\n    const xScale = scaleBand()\n      .domain(this.categories)\n      .range([0, innerWidth])\n      .padding(0.35);\n\n    const yScale = scaleLinear()\n      .domain([0, yMax || 1])\n      .range([innerHeight, 0])\n      .nice();\n\n    const yTicks = this.variant === 'percentage' ? PERCENTAGE_TICKS : yScale.ticks(4);\n\n    return (\n      <Host class=\"chart-bar-stacked\">\n        <svg\n          class=\"chart-bar-stacked__svg\"\n          ref={element => {\n            this.svgEl = element ?? null;\n          }}\n          width={viewportWidth}\n          height={viewportHeight}\n          role=\"img\"\n          aria-label={this.accessibleLabel()}\n        >\n          <g transform={`translate(${margin.left}, ${margin.top})`}>\n            {yTicks.map(tick => (\n              <g key={`grid-${tick}`} transform={`translate(0, ${yScale(tick)})`}>\n                <line class=\"chart-bar-stacked__gridline\" x1={0} x2={innerWidth} />\n                <text\n                  class=\"chart-bar-stacked__axis-label\"\n                  x={-axisLabelGap}\n                  text-anchor=\"end\"\n                  dominant-baseline=\"middle\"\n                >\n                  {this.variant === 'percentage' ? `${tick}%` : tick}\n                </text>\n              </g>\n            ))}\n\n            {this.categories.map((category, categoryIndex) => {\n              const barWidth = xScale.bandwidth();\n              const barX = xScale(category) ?? 0;\n              const values = categoryValues[categoryIndex];\n              const total = totals[categoryIndex];\n              const topSeriesIndex = values.reduce(\n                (topIndex, value, seriesIndex) => (value > 0 ? seriesIndex : topIndex),\n                -1\n              );\n              let cumulativeValue = 0;\n\n              return (\n                <g class=\"chart-bar-stacked__stack\" data-category={category} key={category}>\n                  {this.series.map((series, seriesIndex) => {\n                    const rawValue = values[seriesIndex];\n                    const value = this.variant === 'percentage'\n                      ? total\n                        ? (rawValue / total) * 100\n                        : 0\n                      : rawValue;\n                    const segmentStart = cumulativeValue;\n                    const segmentEnd = cumulativeValue + value;\n                    cumulativeValue = segmentEnd;\n\n                    const segmentY = yScale(segmentEnd);\n                    const segmentBottom = yScale(segmentStart);\n                    const segmentHeight = Math.max(0, segmentBottom - segmentY);\n                    if (!segmentHeight) return null;\n\n                    const fill = series.color ?? categoryColor(seriesIndex);\n                    const isTopSegment = seriesIndex === topSeriesIndex;\n                    const hasRoundedTop =\n                      this.variant === 'stacked' && isTopSegment;\n                    const squareBaseY = segmentY + segmentHeight / 2;\n                    const squareBaseHeight = segmentHeight / 2;\n\n                    return (\n                      <g\n                        class=\"chart-bar-stacked__segment\"\n                        data-series={series.name}\n                        key={series.name}\n                      >\n                        <rect\n                          class={{\n                            'chart-bar-stacked__segment-shape': true,\n                            'chart-bar-stacked__segment-shape--rounded': hasRoundedTop,\n                          }}\n                          x={barX}\n                          y={segmentY}\n                          width={barWidth}\n                          height={segmentHeight}\n                          fill={fill}\n                        />\n                        {hasRoundedTop ? (\n                          <rect\n                            class=\"chart-bar-stacked__segment-square-base\"\n                            x={barX}\n                            y={squareBaseY}\n                            width={barWidth}\n                            height={squareBaseHeight}\n                            fill={fill}\n                          />\n                        ) : null}\n                        {segmentStart > 0 ? (\n                          <line\n                            class=\"chart-bar-stacked__segment-separator\"\n                            x1={barX}\n                            x2={barX + barWidth}\n                            y1={segmentBottom}\n                            y2={segmentBottom}\n                            vector-effect=\"non-scaling-stroke\"\n                          />\n                        ) : null}\n                      </g>\n                    );\n                  })}\n                  <text\n                    class=\"chart-bar-stacked__axis-label\"\n                    x={barX + barWidth / 2}\n                    y={innerHeight + categoryLabelOffset}\n                    text-anchor=\"middle\"\n                  >\n                    {category}\n                  </text>\n                </g>\n              );\n            })}\n          </g>\n        </svg>\n      </Host>\n    );\n  }\n}\n",
-      "type": "registry:ui"
-    }
-  ]
-}