@ds-mo/ui 12.8.0 → 13.0.0

package/dist/mcp-data/registry/card-data-viz.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "card-data-viz",
+  "title": "CardDataViz",
+  "description": "Standard data-visualization card chrome with variant-owned chart and legend composition.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/card-data-viz",
+    "source": "src/wc/components/CardDataViz/CardDataViz.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "specialized",
+      "status": "experimental",
+      "summary": "Standard data-visualization card chrome with variant-owned chart and legend composition.",
+      "useWhen": [
+        "A chart, legend, metric visualization, or custom data-viz composition needs standard card chrome.",
+        "Bar and line legends should remain static, or a donut and legend should cross-highlight without redundant donut tooltips.",
+        "A data-viz card needs a visible heading, optional filter action, and application-owned chart data."
+      ],
+      "avoidWhen": [
+        "The card contains editable settings; use CardSetting.",
+        "The surface contains ordinary non-visualization content.",
+        "The application needs to replace the card chrome rather than compose its chart and actions."
+      ],
+      "alternatives": [
+        {
+          "when": "The surface contains editable settings.",
+          "component": "component:ds-card-setting",
+          "reason": "CardSetting owns the controlled settings-section workflow."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-chart-bar",
+        "component:ds-chart-donut",
+        "component:ds-chart-line",
+        "component:ds-chart-legend",
+        "component:ds-button-unfilled"
+      ],
+      "accessibility": [
+        "Provide a concise visible heading; the component renders it as a section heading.",
+        "Slotted actions must provide accessible names and controlled-state semantics.",
+        "Charts retain their own image names and data summaries.",
+        "A visible donut legend owns persistent labels and values, so donut mode suppresses the redundant slice tooltip."
+      ],
+      "states": [
+        "Custom mode provides flexible body chrome and does not mutate chart or legend interaction.",
+        "Bar and line modes keep a slotted legend static by disabling hover emphasis.",
+        "Donut mode synchronizes active labels between chart and legend and shows chart tooltips only when no legend is present.",
+        "showFilter adds the standard filter action and emits dsFilterClick without owning filter state."
+      ],
+      "responsiveBehavior": [
+        "The sm, md, or lg width sets a matching token-based minimum height and remains constrained by its parent.",
+        "The body allocates remaining height to the chart while legends retain content height.",
+        "Parent layouts own wrapping, stacking, and breakpoint-dependent card width."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Set variant to bar, line, or donut when the component should manage legend interaction; slot chart, legend, actions, and supporting content by name."
+        ],
+        "react": [
+          "Keep chart data in React and pass chart, legend, and action elements through named slots."
+        ],
+        "angular": [
+          "Keep chart data in Angular and project chart, legend, and action elements through named slots."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook examples",
+          "path": "src/wc/components/CardDataViz/CardDataViz.stories.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "cardWidth": {
+          "type": "CardDataVizWidth",
+          "resolvedType": "\"lg\" | \"md\" | \"sm\"",
+          "attribute": "card-width",
+          "default": "'md'",
+          "required": false,
+          "mutable": false,
+          "description": "Width token with the matching data-visualization card min-height."
+        },
+        "filterLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "filter-label",
+          "default": "'Filter'",
+          "required": false,
+          "mutable": false
+        },
+        "heading": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "heading",
+          "required": true,
+          "mutable": false,
+          "description": "Data-visualization heading shown in the card header."
+        },
+        "showFilter": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "show-filter",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Renders the standard filter action before custom actions."
+        },
+        "variant": {
+          "type": "CardDataVizVariant",
+          "resolvedType": "\"bar\" | \"custom\" | \"donut\" | \"line\"",
+          "attribute": "variant",
+          "default": "'custom'",
+          "required": false,
+          "mutable": false,
+          "description": "Chart composition behavior."
+        }
+      },
+      "events": [
+        {
+          "name": "dsFilterClick",
+          "detail": "void",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "description": "Emits when the standard header filter control is activated."
+        }
+      ],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "cardWidth": {
+        "type": "CardDataVizWidth",
+        "resolvedType": "\"lg\" | \"md\" | \"sm\"",
+        "attribute": "card-width",
+        "default": "'md'",
+        "required": false,
+        "mutable": false,
+        "description": "Width token with the matching data-visualization card min-height."
+      },
+      "filterLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "filter-label",
+        "default": "'Filter'",
+        "required": false,
+        "mutable": false
+      },
+      "heading": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "heading",
+        "required": true,
+        "mutable": false,
+        "description": "Data-visualization heading shown in the card header."
+      },
+      "showFilter": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "show-filter",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Renders the standard filter action before custom actions."
+      },
+      "variant": {
+        "type": "CardDataVizVariant",
+        "resolvedType": "\"bar\" | \"custom\" | \"donut\" | \"line\"",
+        "attribute": "variant",
+        "default": "'custom'",
+        "required": false,
+        "mutable": false,
+        "description": "Chart composition behavior."
+      }
+    },
+    "events": [
+      {
+        "name": "dsFilterClick",
+        "detail": "void",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true,
+        "description": "Emits when the standard header filter control is activated."
+      }
+    ],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-card-data-viz",
+      "react": "DsCardDataViz",
+      "angular": "DsCardDataViz"
+    },
+    "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-card-data-viz.js';",
+        "example": "<ds-card-data-viz></ds-card-data-viz>"
+      },
+      "react": {
+        "import": "import { DsCardDataViz } from '@ds-mo/ui/react';",
+        "example": "<DsCardDataViz />"
+      },
+      "angular": {
+        "import": "import { DsCardDataViz } from '@ds-mo/ui/angular/ds-card-data-viz';",
+        "example": "<ds-card-data-viz></ds-card-data-viz>"
+      },
+      "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": [
+    "button-unfilled",
+    "text"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/CardDataViz/CardDataViz.css",
+      "content": "@import '../../utils/chrome-layout.css';\n\n:host {\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  width: var(--_card-data-viz-width);\n  min-height: var(--_card-data-viz-min-height);\n  max-width: 100%;\n  overflow: hidden;\n  border: none;\n  border-radius: var(--dimension-radius-025);\n  background-color: var(--color-background-primary);\n  box-shadow: 0 0 0 var(--dimension-stroke-width-012) var(--color-border-tertiary);\n}\n\n.card-data-viz__header {\n  flex-shrink: 0;\n  justify-content: space-between;\n  height: var(--dimension-size-600);\n  border-bottom: var(--dimension-stroke-width-012) solid var(--color-border-tertiary);\n  background-color: var(--color-background-secondary);\n}\n\nds-text.card-data-viz__title {\n  display: flex;\n  flex: 1 1 auto;\n  align-items: center;\n  box-sizing: border-box;\n  min-width: 0;\n  padding: calc(var(--dimension-space-075) + var(--dimension-space-025));\n  -webkit-user-select: none;\n  user-select: none;\n}\n\n.card-data-viz__actions {\n  display: flex;\n  flex-shrink: 0;\n  align-items: center;\n  gap: var(--dimension-space-100);\n}\n\n.card-data-viz__actions:empty {\n  display: none;\n}\n\n.card-data-viz__body,\n.card-data-viz__layout {\n  display: flex;\n  flex: 1 1 auto;\n  flex-direction: column;\n  box-sizing: border-box;\n  min-height: 0;\n}\n\n.card-data-viz__body {\n  border-radius: 0 0 var(--dimension-radius-025) var(--dimension-radius-025);\n  background-color: var(--color-background-primary);\n}\n\n.card-data-viz__layout {\n  height: 100%;\n  gap: var(--dimension-space-200);\n}\n\n.card-data-viz__chart {\n  display: grid;\n  flex: 1 1 auto;\n  align-items: center;\n  box-sizing: border-box;\n  min-height: 0;\n  padding: var(--dimension-space-400) var(--dimension-space-400) 0\n    var(--dimension-space-400);\n}\n\n.card-data-viz__chart > * {\n  width: 100%;\n  height: 100%;\n  min-width: 0;\n  min-height: 0;\n  max-width: 100%;\n  max-height: 100%;\n}\n\n.card-data-viz__chart--fill > * {\n  height: 100%;\n  min-height: 0;\n  max-height: 100%;\n}\n\n.card-data-viz__legend {\n  flex: 0 0 auto;\n  box-sizing: border-box;\n  padding: 0 var(--dimension-space-100) var(--dimension-space-100)\n    var(--dimension-space-100);\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/CardDataViz/CardDataViz.tsx",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Prop,\n  State,\n} from '@stencil/core';\n\nexport type CardDataVizWidth = 'sm' | 'md' | 'lg';\nexport type CardDataVizVariant = 'custom' | 'bar' | 'line' | 'donut';\n\ntype HoveredDatum = { label: string } | null;\n\ntype ChartSlot = HTMLElement & {\n  activeLabel?: string | null;\n  showTooltip?: boolean;\n};\n\ntype LegendSlot = HTMLElement & {\n  activeLabel?: string | null;\n  highlightOnHover?: boolean;\n};\n\nconst CARD_WIDTH_VARS: Record<CardDataVizWidth, string> = {\n  sm: 'var(--dimension-card-width-sm)',\n  md: 'var(--dimension-card-width-md)',\n  lg: 'var(--dimension-card-width-lg)',\n};\n\nconst CARD_HEIGHT_VARS: Record<CardDataVizWidth, string> = {\n  sm: 'var(--dimension-card-height-sm)',\n  md: 'var(--dimension-card-height-md)',\n  lg: 'var(--dimension-card-height-lg)',\n};\n\n/**\n * Standard data-visualization card chrome and composition. The variant owns\n * only the chart/legend relationship; applications continue to own data.\n */\n@Component({\n  tag: 'ds-card-data-viz',\n  styleUrl: 'CardDataViz.css',\n  scoped: true,\n})\nexport class CardDataViz {\n  @Element() el!: HTMLElement;\n\n  /** Data-visualization heading shown in the card header. */\n  @Prop() heading!: string;\n  /** Chart composition behavior. */\n  @Prop() variant: CardDataVizVariant = 'custom';\n  /** Width token with the matching data-visualization card min-height. */\n  @Prop() cardWidth: CardDataVizWidth = 'md';\n  /** Renders the standard filter action before custom actions. */\n  @Prop() showFilter: boolean = false;\n  @Prop() filterLabel: string = 'Filter';\n\n  /** Emits when the standard header filter control is activated. */\n  @Event() dsFilterClick!: EventEmitter<void>;\n\n  @State() private hasChartSlot = false;\n  @State() private hasLegendSlot = false;\n\n  componentWillRender() {\n    this.hasChartSlot = !!this.el.querySelector('[slot=\"chart\"]');\n    this.hasLegendSlot = !!this.el.querySelector('[slot=\"legend\"]');\n  }\n\n  componentDidLoad() {\n    this.el.addEventListener('dsSliceHover', this.handleChartHover);\n    this.el.addEventListener('dsItemHover', this.handleLegendHover);\n  }\n\n  componentDidRender() {\n    const chart = this.el.querySelector('[slot=\"chart\"]') as ChartSlot | null;\n    const legend = this.el.querySelector(\n      'ds-chart-legend[slot=\"legend\"]'\n    ) as LegendSlot | null;\n\n    if (this.variant === 'donut') {\n      if (chart && 'showTooltip' in chart) {\n        chart.showTooltip = !this.hasLegendSlot;\n      }\n      return;\n    }\n\n    if (\n      (this.variant === 'bar' || this.variant === 'line') &&\n      legend\n    ) {\n      legend.setAttribute('highlight-on-hover', 'false');\n      if ('highlightOnHover' in legend) legend.highlightOnHover = false;\n    }\n  }\n\n  disconnectedCallback() {\n    this.el.removeEventListener('dsSliceHover', this.handleChartHover);\n    this.el.removeEventListener('dsItemHover', this.handleLegendHover);\n  }\n\n  private handleChartHover = (event: Event) => {\n    if (this.variant !== 'donut') return;\n    const legend = this.el.querySelector('[slot=\"legend\"]') as LegendSlot | null;\n    if (!legend || !('activeLabel' in legend)) return;\n    legend.activeLabel =\n      (event as CustomEvent<HoveredDatum>).detail?.label ?? null;\n  };\n\n  private handleLegendHover = (event: Event) => {\n    if (this.variant !== 'donut') return;\n    const chart = this.el.querySelector('[slot=\"chart\"]') as ChartSlot | null;\n    if (!chart || !('activeLabel' in chart)) return;\n    chart.activeLabel =\n      (event as CustomEvent<HoveredDatum>).detail?.label ?? null;\n  };\n\n  private handleFilterClick = () => {\n    this.dsFilterClick.emit();\n  };\n\n  render() {\n    const usesChartLayout = this.variant !== 'custom' || this.hasChartSlot;\n    return (\n      <Host\n        class={{\n          'card-data-viz': true,\n          [`card-data-viz--${this.variant}`]: true,\n        }}\n        style={{\n          '--_card-data-viz-width': CARD_WIDTH_VARS[this.cardWidth],\n          '--_card-data-viz-min-height': CARD_HEIGHT_VARS[this.cardWidth],\n        }}\n      >\n        <header class=\"card-data-viz__header ds-chrome-row ds-chrome-space--md\">\n          <ds-text\n            class=\"card-data-viz__title\"\n            variant=\"text-title-small\"\n            emphasis\n            color=\"primary\"\n            as=\"h2\"\n          >\n            {this.heading}\n          </ds-text>\n          <div class=\"card-data-viz__actions\">\n            {this.showFilter ? (\n              <ds-button-unfilled\n                variant=\"icon\"\n                type=\"button\"\n                icon=\"Filters\"\n                aria-label={this.filterLabel}\n                onDsClick={this.handleFilterClick}\n              />\n            ) : null}\n            <slot name=\"actions\" />\n          </div>\n        </header>\n        <div class=\"card-data-viz__body\">\n          {usesChartLayout ? (\n            <div class=\"card-data-viz__layout\">\n              {this.hasChartSlot ? (\n                <div\n                  class={{\n                    'card-data-viz__chart': true,\n                    'card-data-viz__chart--fill': this.variant === 'donut',\n                  }}\n                >\n                  <slot name=\"chart\" />\n                </div>\n              ) : null}\n              {this.hasLegendSlot ? (\n                <div class=\"card-data-viz__legend\">\n                  <slot name=\"legend\" />\n                </div>\n              ) : null}\n              <slot />\n            </div>\n          ) : (\n            <slot />\n          )}\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}