{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "card-overview", "title": "CardOverview", "description": "Page-level summary with a persistent 48px reporting bar above an equal-track grid of an optional safety score and comparable measures, plus an elevated page-controlled collapse surface.", "type": "registry:ui", "meta": { "library": "@ds-mo/ui", "distribution": "npm", "storybook": "https://zainadeel.github.io/compomo/?path=/story/card-overview", "source": "src/wc/components/CardOverview/CardOverview.tsx", "intentStatus": "complete", "intent": { "audience": "general", "status": "stable", "summary": "Page-level summary with a persistent 48px reporting bar above an equal-track grid of an optional safety score and comparable measures, plus an elevated page-controlled collapse surface.", "useWhen": [ "A page opens with one headline figure that the surrounding measures explain.", "Every measure is compared against the same period, so one caption describes the comparison for all of them.", "The measures are read together at a glance rather than explored individually." ], "avoidWhen": [ "There is no headline figure and the measures are unrelated; use the matching card surface for each one.", "A measure needs a chart, sparkline, or other visualization; the grid presents values and change only.", "The measures each require their own comparison period or their own filter control.", "The content is a settings section or a general read-only card." ], "alternatives": [ { "when": "A measure needs a chart or other data visualization.", "component": "component:ds-card-chart", "reason": "CardChart owns the data-visualization card contract; the overview grid presents values and change only." }, { "when": "The surface is a settings section with an edit workflow.", "component": "component:ds-card-setting", "reason": "CardSetting owns the controlled view and edit chrome." } ], "commonlyComposedWith": [ "component:ds-select", "component:ds-button-unfilled", "component:ds-text", "component:ds-tooltip" ], "accessibility": [ "The bar is a labelled region; set overviewLabel to name what is being summarised, such as Safety summary.", "Colour never carries trend meaning alone; the arrow direction and formatted change value are both included in the accessible text.", "Measures become selectable only when they are not inactive. Selectable measures form one roving tab stop, so the grid is a single stop and arrow keys move between measures.", "Set labelTooltip when a measure's label needs qualifying rather than shortening the label into something ambiguous.", "While loading, the region exposes a busy state and renders skeletons whose type metrics match the resolved content." ], "states": [ "Score and measures are supplied as data; the component owns their type treatment so summary bars stay consistent across pages.", "Trend is supplied already resolved as a direction, a formatted value, and a tone. Whether a rise reads well is a product decision, so the component never infers tone from the numbers. Derive it with resolveMetricTrend.", "Omit a trend when there is nothing to report; resolveMetricTrend returns null in that case so no zero change is rendered.", "Omit score to render a centered Score unavailable cell with a tertiary border and no score fill. Set scoreErrorMessage to replace that copy while the measures remain readable.", "Loading replaces the score and measures with skeletons and does not alter the slotted period control. When measures are already supplied, their count preserves the resolved grid shape; otherwise five measure placeholders join the score in the standard six-cell grid.", "At most seven measures are shown. Keep larger collections outside the summary bar rather than turning it into a dense dashboard.", "The period and filter controls are slotted rather than owned. Use the period slot when the current range is selectable; otherwise periodLabel supplies fixed current copy in the same md control-frame and label-inset anatomy. Use the filter slot for the application-owned comparison-window control. Slotted Selects use hasBorder false so the 48px bar owns their surrounding boundary and allowClear false because both controls always require one selected reporting period.", "A numeric safety score infers fair from 0–50, good from 51–80, and excellent from 81–100. The level can be supplied explicitly when the displayed value is not numeric. The deprecated band field is ignored.", "The safety score is the first grid cell and uses the same track, 8px outer inset, 6px inner padding, dividers, and responsive behavior as metric cells. The display value removes 8px from both block edges of its line box so it does not increase the shared row height. Score remains nonselectable and excluded from metric roving focus.", "During page-controlled scroll collapse, the component preserves its expanded flow height and stationary reporting bar while the metric grid moves and clips beneath it. Elevation remains fitted to the visible surface.", "compact is exactly 48px high and renders only the reporting bar. It omits Score, measures, and footer." ], "responsiveBehavior": [ "The measure grid reflows to fewer columns and finally stacks without horizontal scrolling. Even cell totals prefer complete rows; odd totals retain the densest fitting layout and may leave an orphan in the final row.", "Every occupied grid track has the same width. When a final row is incomplete, its measures keep the same width as the row above and the unused tracks remain empty.", "Set metricMinWidth to change the width a measure may shrink to before the grid drops a column.", "The safety score participates in the same equal-width tracks as measures rather than occupying a separate rail.", "The reporting bar owns an exact 8px inset on every edge. Fixed current copy and slotted controls begin at that inset; their labels share md control-frame geometry and truncate before changing the 48px height.", "Every measure occupies a full-width row in the stacked state.", "Set layout to stacked when the owning page shell enters a responsive mode before the card's own container reaches its narrow threshold.", "CardOverview does not observe scroll, choose sticky offsets, or switch its own presentation. The page owner supplies collapse progress, keeps the card sticky at the appropriate shell inset, and swaps to compact at the 48px endpoint.", "Leave scroll collapse inactive on page modes that do not support sticky compact summary chrome." ], "frameworkCaveats": { "customElements": [ "Assign score and metrics as JavaScript properties; both are objects and cannot be expressed as HTML attributes.", "Place an optional current-range control in the period slot and the comparison-window control in the filter slot; the component reserves their layout but never computes or renders controls.", "When driving scroll collapse, update scrollCollapseProgress from page-owned geometry and swap to a separate compact presentation at the endpoint." ], "react": [ "Pass score and metrics as props and read the selected measure from the onDsMetricSelect event detail.", "Derive each trend with resolveMetricTrend so tone stays an explicit product decision.", "Keep sticky geometry and scrollCollapseProgress in the page owner; CardOverview only renders the visual collapse." ], "angular": [ "Bind [score] and [metrics] as properties and read the selected measure from $event.detail on (dsMetricSelect).", "Derive each trend with resolveMetricTrend so tone stays an explicit product decision.", "Keep date math, sticky geometry, and [scrollCollapseProgress] in the page owner; CardOverview only renders the supplied composition and visual collapse." ] }, "references": [ { "label": "Storybook structural examples", "path": "src/wc/components/CardOverview/CardOverview.stories.ts" }, { "label": "Trend resolution unit coverage", "path": "tests/metric-change.test.ts" } ] }, "api": { "props": { "comparisonLabel": { "type": "string", "resolvedType": "string", "attribute": "comparison-label", "default": "''", "required": false, "mutable": false, "description": "Copy between the current period and comparison control, usually `vs.`." }, "isLoading": { "type": "boolean", "resolvedType": "boolean", "attribute": "is-loading", "default": "false", "required": false, "mutable": false, "description": "Replace the score and metrics with skeletons while data resolves." }, "layout": { "type": "CardOverviewLayout", "resolvedType": "\"auto\" | \"stacked\"", "attribute": "layout", "default": "'auto'", "required": false, "mutable": false, "description": "Intrinsic responsive layout, or a page-owned single-column stack." }, "metricMinWidth": { "type": "string", "resolvedType": "string", "attribute": "metric-min-width", "default": "'200px'", "required": false, "mutable": false, "description": "Width a metric cell may shrink to before the grid drops a column. The grid\nuses this threshold while choosing an evenly distributed column count." }, "metrics": { "type": "OverviewMetric[]", "resolvedType": "OverviewMetric[]", "default": "[]", "required": false, "mutable": false, "description": "Measures rendered in the responsive grid. Only the first seven are shown." }, "overviewLabel": { "type": "string", "resolvedType": "string", "attribute": "overview-label", "default": "'Overview'", "required": false, "mutable": false, "description": "Accessible name for the region." }, "periodLabel": { "type": "string", "resolvedType": "string", "attribute": "period-label", "default": "''", "required": false, "mutable": false, "description": "Fixed current date or range. Replaced by content in the `period` slot." }, "score": { "type": "OverviewScore | undefined", "resolvedType": "OverviewScore | undefined", "required": false, "mutable": false, "description": "Optional nonselectable safety score rendered as the first grid cell." }, "scoreErrorMessage": { "type": "string | undefined", "resolvedType": "string | undefined", "attribute": "score-error-message", "required": false, "mutable": false, "description": "Message shown in place of the score when its figure cannot be resolved." }, "scrollCollapseProgress": { "type": "number", "resolvedType": "number", "attribute": "scroll-collapse-progress", "default": "0", "required": false, "mutable": false, "description": "Page-controlled visual collapse from the full card (`0`) toward its 48px\ncompact handoff height (`1`). The component preserves its expanded flow\nheight, keeps the period bar stationary, and moves/clips the grid beneath\nit. The page still owns sticky positioning and the final compact handoff." }, "variant": { "type": "CardOverviewVariant", "resolvedType": "\"compact\" | \"default\"", "attribute": "variant", "default": "'default'", "required": false, "mutable": false, "description": "Full summary card, or the condensed 48px summary bar." } }, "events": [ { "name": "dsMetricSelect", "detail": "OverviewMetric", "bubbles": true, "cancelable": true, "composed": true, "description": "Emitted when a metric that is not inactive is activated." } ], "methods": [], "slots": [] }, "props": { "comparisonLabel": { "type": "string", "resolvedType": "string", "attribute": "comparison-label", "default": "''", "required": false, "mutable": false, "description": "Copy between the current period and comparison control, usually `vs.`." }, "isLoading": { "type": "boolean", "resolvedType": "boolean", "attribute": "is-loading", "default": "false", "required": false, "mutable": false, "description": "Replace the score and metrics with skeletons while data resolves." }, "layout": { "type": "CardOverviewLayout", "resolvedType": "\"auto\" | \"stacked\"", "attribute": "layout", "default": "'auto'", "required": false, "mutable": false, "description": "Intrinsic responsive layout, or a page-owned single-column stack." }, "metricMinWidth": { "type": "string", "resolvedType": "string", "attribute": "metric-min-width", "default": "'200px'", "required": false, "mutable": false, "description": "Width a metric cell may shrink to before the grid drops a column. The grid\nuses this threshold while choosing an evenly distributed column count." }, "metrics": { "type": "OverviewMetric[]", "resolvedType": "OverviewMetric[]", "default": "[]", "required": false, "mutable": false, "description": "Measures rendered in the responsive grid. Only the first seven are shown." }, "overviewLabel": { "type": "string", "resolvedType": "string", "attribute": "overview-label", "default": "'Overview'", "required": false, "mutable": false, "description": "Accessible name for the region." }, "periodLabel": { "type": "string", "resolvedType": "string", "attribute": "period-label", "default": "''", "required": false, "mutable": false, "description": "Fixed current date or range. Replaced by content in the `period` slot." }, "score": { "type": "OverviewScore | undefined", "resolvedType": "OverviewScore | undefined", "required": false, "mutable": false, "description": "Optional nonselectable safety score rendered as the first grid cell." }, "scoreErrorMessage": { "type": "string | undefined", "resolvedType": "string | undefined", "attribute": "score-error-message", "required": false, "mutable": false, "description": "Message shown in place of the score when its figure cannot be resolved." }, "scrollCollapseProgress": { "type": "number", "resolvedType": "number", "attribute": "scroll-collapse-progress", "default": "0", "required": false, "mutable": false, "description": "Page-controlled visual collapse from the full card (`0`) toward its 48px\ncompact handoff height (`1`). The component preserves its expanded flow\nheight, keeps the period bar stationary, and moves/clips the grid beneath\nit. The page still owns sticky positioning and the final compact handoff." }, "variant": { "type": "CardOverviewVariant", "resolvedType": "\"compact\" | \"default\"", "attribute": "variant", "default": "'default'", "required": false, "mutable": false, "description": "Full summary card, or the condensed 48px summary bar." } }, "events": [ { "name": "dsMetricSelect", "detail": "OverviewMetric", "bubbles": true, "cancelable": true, "composed": true, "description": "Emitted when a metric that is not inactive is activated." } ], "methods": [], "slots": [], "exports": { "customElement": "ds-card-overview", "react": "DsCardOverview", "vue": "DsCardOverview", "angular": "DsCardOverview" }, "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-overview.js';", "example": "" }, "react": { "import": "import { DsCardOverview } from '@ds-mo/ui/react';", "example": "" }, "vue": { "import": "import { DsCardOverview } from '@ds-mo/ui/vue';", "example": "" }, "angular": { "import": "import { DsCardOverview } from '@ds-mo/ui/angular/ds-card-overview';", "example": "" }, "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: metrics, score.", "peerDependencies": { "required": [ "@ds-mo/tokens ^6.5.0", "@ds-mo/icons ^7.0.0" ], "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters." } } }, "dependencies": [ "@ds-mo/ui", "@ds-mo/tokens" ], "registryDependencies": [ "skeleton", "text", "tooltip" ], "files": [ { "path": "src/wc/components/CardOverview/CardOverview.css", "content": "@import '../../utils/interaction-fill.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/control-density.css';\n@import '../../utils/control-parts.css';\n@import '../../styles/control-elevation.css';\n\n:host {\n display: block;\n box-sizing: border-box;\n container-type: inline-size;\n -webkit-user-select: none;\n user-select: none;\n --ds-card-overview-metric-min: calc(var(--dimension-size-400) * 5);\n --ds-card-overview-divider-width: var(--dimension-stroke-width-012);\n --ds-card-overview-divider-color: var(--color-always-dark-border-tertiary);\n color: var(--color-always-dark-foreground-primary);\n}\n\n.card-overview__surface {\n width: 100%;\n min-width: 0;\n box-sizing: border-box;\n border-radius: var(--dimension-radius-125);\n background: var(--color-always-dark-background);\n color: var(--color-always-dark-foreground-primary);\n overflow-anchor: none;\n}\n\n.card-overview__clip {\n height: 100%;\n min-width: 0;\n border-radius: inherit;\n background: inherit;\n overflow: hidden;\n}\n\n:host(.card-overview--scroll-collapsing) {\n height: var(--ds-card-overview-expanded-height);\n pointer-events: none;\n}\n\n:host(.card-overview--scroll-collapsing) .card-overview__surface {\n height: var(--ds-card-overview-visible-height);\n pointer-events: auto;\n will-change: height;\n}\n\n:host(.card-overview--scroll-collapsing) .card-overview__body {\n transform: translateY(calc(-1 * var(--ds-card-overview-content-offset)));\n will-change: transform;\n}\n\n.card-overview__layout {\n display: flex;\n flex-direction: column;\n min-width: 0;\n}\n\n.card-overview__summary {\n position: relative;\n z-index: 1;\n flex: 0 0 auto;\n min-width: 0;\n background: var(--color-always-dark-background);\n}\n\n.card-overview__header {\n display: flex;\n position: relative;\n align-items: center;\n gap: 0;\n width: 100%;\n height: var(--dimension-size-600);\n min-width: 0;\n padding: var(--dimension-space-100);\n box-sizing: border-box;\n}\n\n.card-overview__header::after {\n content: '';\n position: absolute;\n inset-inline: 0;\n inset-block-end: 0;\n height: var(--ds-card-overview-divider-width);\n background: var(--ds-card-overview-divider-color);\n pointer-events: none;\n}\n\n.card-overview__period {\n display: flex;\n flex: 0 1 auto;\n align-items: center;\n gap: 0;\n min-width: 0;\n min-height: var(--ds-control-height);\n overflow: hidden;\n white-space: nowrap;\n}\n\n.card-overview__period-current,\n.card-overview__period-comparison {\n min-width: 0;\n overflow: hidden;\n text-overflow: ellipsis;\n}\n\n.card-overview__period-current {\n display: flex;\n flex: 0 1 auto;\n align-items: center;\n}\n\n.card-overview__period-fixed {\n flex: 0 1 auto;\n min-width: 0;\n}\n\n.card-overview__period-comparison {\n flex: 0 0 auto;\n}\n\n.card-overview__filter {\n display: flex;\n flex: 0 1 auto;\n align-items: center;\n min-width: 0;\n}\n\n.card-overview__body {\n display: flex;\n position: relative;\n z-index: 0;\n flex-direction: column;\n min-width: 0;\n transform: translateY(0);\n}\n\n.card-overview__metrics {\n display: grid;\n flex: 1 1 auto;\n grid-template-columns: repeat(\n var(--ds-card-overview-grid-columns, auto-fit),\n minmax(min(100%, var(--ds-card-overview-metric-min)), 1fr)\n );\n align-content: stretch;\n min-width: 0;\n overflow: clip;\n}\n\n.card-overview__score,\n.card-overview__metric {\n display: flex;\n min-width: 0;\n padding: var(--dimension-space-100);\n box-shadow:\n var(--ds-card-overview-divider-width) 0 0 0 var(--ds-card-overview-divider-color),\n 0 var(--ds-card-overview-divider-width) 0 0 var(--ds-card-overview-divider-color);\n box-sizing: border-box;\n}\n\n.card-overview__score-content,\n.card-overview__metric-action {\n display: flex;\n flex: 1 1 auto;\n min-width: 0;\n padding: var(--dimension-space-075);\n border-radius: var(--dimension-radius-025);\n box-sizing: border-box;\n}\n\n.card-overview__score-content {\n align-items: center;\n justify-content: flex-start;\n /*\n * Sits the fill 16px from the cell's left edge, on top of the 8px cell padding.\n * Metric cells keep the shared inner inset because their content is text; the\n * fill is a filled box and needs more room around it to read as inset.\n */\n padding-inline-start: var(--dimension-space-100);\n gap: var(--dimension-space-100);\n}\n\n/*\n * The level fill wraps the score figure alone. The trend sits outside it so it\n * keeps the same color and baseline as every other metric cell, and is never\n * held to the fill's contrast.\n */\n.card-overview__score-badge {\n display: flex;\n flex: 0 0 auto;\n align-items: center;\n justify-content: center;\n /*\n * The padding gives the fill its own breathing room around the figure, and the\n * matching negative margin keeps that padding out of layout so the cell still\n * measures the same as a metric cell.\n */\n margin-block: calc(-1 * var(--dimension-space-050));\n padding: var(--dimension-space-050);\n border-radius: var(--dimension-radius-025);\n background: var(--color-always-dark-interaction-active-brand);\n color: var(--color-always-dark-foreground-primary);\n}\n\n.card-overview__score-badge--fair {\n background: var(--color-safety-score-background-fair);\n color: var(--color-safety-score-foreground-on-fair);\n}\n\n.card-overview__score-badge--good {\n background: var(--color-safety-score-background-good);\n color: var(--color-safety-score-foreground-on-good);\n}\n\n.card-overview__score-badge--excellent {\n background: var(--color-safety-score-background-excellent);\n color: var(--color-safety-score-foreground-on-excellent);\n}\n\n/* Mirrors .card-overview__metric-content so labels and trends line up across cells. */\n.card-overview__score-copy {\n display: flex;\n flex: 1 1 auto;\n flex-direction: column;\n justify-content: center;\n align-items: flex-start;\n gap: var(--dimension-space-050);\n min-width: 0;\n}\n\n.card-overview__score-label-spacer {\n visibility: hidden;\n}\n\n/*\n * The display line box is taller than the figure needs, so it is cropped to keep\n * the fill from driving the cell taller than a metric cell's label-plus-figure\n * column.\n */\n.card-overview__score-value,\n.card-overview__score-badge ds-skeleton {\n flex: 0 0 auto;\n margin-block: calc(-1 * var(--dimension-space-100));\n}\n\n.card-overview__score-content--error {\n align-items: center;\n justify-content: center;\n /* No fill to align, so this box keeps the metric cells' inner inset. */\n padding-inline-start: var(--dimension-space-075);\n border: var(--ds-card-overview-divider-width) solid\n var(--color-always-dark-border-tertiary);\n background: transparent;\n color: var(--color-always-dark-foreground-negative);\n text-align: center;\n}\n\n.card-overview__metric-action {\n flex-direction: column;\n justify-content: center;\n gap: var(--dimension-space-050);\n}\n\n.card-overview__metric-action[role='button'] {\n cursor: default;\n}\n\n.card-overview__metric-content {\n display: flex;\n flex: 1 1 auto;\n flex-direction: column;\n justify-content: center;\n gap: var(--dimension-space-050);\n min-width: 0;\n}\n\n.card-overview__metric-label {\n min-width: 0;\n}\n\n.card-overview__metric-figure {\n display: flex;\n align-items: baseline;\n gap: var(--dimension-space-050);\n min-width: 0;\n}\n\n.card-overview__trend {\n flex: 0 0 auto;\n white-space: nowrap;\n}\n\n:host(.card-overview--stacked) .card-overview__metrics {\n grid-template-columns: minmax(0, 1fr);\n}\n\n:host(.card-overview--compact) {\n height: var(--dimension-size-600);\n min-height: var(--dimension-size-600);\n}\n\n:host(.card-overview--compact) .card-overview__surface,\n:host(.card-overview--compact) .card-overview__clip,\n:host(.card-overview--compact) .card-overview__layout,\n:host(.card-overview--compact) .card-overview__summary {\n width: 100%;\n height: 100%;\n}\n\n:host(.card-overview--compact) .card-overview__header::after {\n display: none;\n}\n\n@media (forced-colors: active) {\n .card-overview__header::after {\n background: var(--ds-forced-color-content);\n }\n\n .card-overview__score-badge,\n .card-overview__score-content--error {\n border: var(--dimension-stroke-width-012) solid var(--ds-forced-color-content);\n background: var(--ds-forced-color-surface);\n color: var(--ds-forced-color-content);\n }\n}\n", "type": "registry:ui" }, { "path": "src/wc/components/CardOverview/CardOverview.tsx", "content": "import {\n Component,\n Element,\n Event,\n EventEmitter,\n forceUpdate,\n h,\n Host,\n Prop,\n State,\n} from '@stencil/core';\nimport { resolveCssLengthPx, TOKEN_DEFAULTS } from '../../utils';\nimport type { TextColor, TextVariant } from '../Text/text-types';\nimport type { MetricTrend } from '../../utils/metric-change';\nimport type {\n CardOverviewLayout,\n CardOverviewVariant,\n OverviewMetric,\n OverviewScore,\n} from './card-overview-types';\nimport {\n findNextOverviewMetricIndex,\n resolveCardOverviewCollapseGeometry,\n resolveOverviewGridColumns,\n resolveOverviewRovingIndex,\n resolveSafetyScoreLevel,\n} from './card-overview-controller';\n\n/**\n * Metric cells below this width drop a grid column rather than compress further.\n *\n * A literal rather than a token: this is a layout threshold for a grid cell, and\n * the dimension scale has no token for that. The 200px tokens it could borrow\n * (`menu-width-xs`, `form-width-xs`, `panel-width-2xs`) all name other\n * components, so binding to one would couple this grid to an unrelated contract.\n * Consumers override with the `metricMinWidth` prop.\n */\nconst DEFAULT_METRIC_MIN_WIDTH = '200px';\n\n/** Skeleton cells rendered while loading with no metrics supplied yet. */\nconst DEFAULT_LOADING_METRIC_COUNT = 5;\n\n/** Maximum number of comparable measures the summary bar presents at once. */\nconst MAX_METRIC_COUNT = 7;\n\nconst TREND_COLORS: Record = {\n positive: 'var(--color-always-dark-foreground-positive)',\n negative: 'var(--color-always-dark-foreground-negative)',\n neutral: 'var(--color-always-dark-foreground-secondary)',\n};\n\nconst ALWAYS_DARK_PRIMARY: TextColor = 'var(--color-always-dark-foreground-primary)';\nconst ALWAYS_DARK_SECONDARY: TextColor = 'var(--color-always-dark-foreground-secondary)';\n\n@Component({\n tag: 'ds-card-overview',\n styleUrl: 'CardOverview.css',\n scoped: true,\n})\nexport class CardOverview {\n @Element() el!: HTMLElement;\n\n /** Full summary card, or the condensed 48px summary bar. */\n @Prop() variant: CardOverviewVariant = 'default';\n\n /** Intrinsic responsive layout, or a page-owned single-column stack. */\n @Prop() layout: CardOverviewLayout = 'auto';\n\n /** Optional nonselectable safety score rendered as the first grid cell. */\n @Prop() score: OverviewScore | undefined;\n\n /** Fixed current date or range. Replaced by content in the `period` slot. */\n @Prop() periodLabel: string = '';\n\n /** Copy between the current period and comparison control, usually `vs.`. */\n @Prop() comparisonLabel: string = '';\n\n /** Measures rendered in the responsive grid. Only the first seven are shown. */\n @Prop() metrics: OverviewMetric[] = [];\n\n /**\n * Width a metric cell may shrink to before the grid drops a column. The grid\n * uses this threshold while choosing an evenly distributed column count.\n */\n @Prop() metricMinWidth: string = DEFAULT_METRIC_MIN_WIDTH;\n\n /** Replace the score and metrics with skeletons while data resolves. */\n @Prop() isLoading: boolean = false;\n\n /** Message shown in place of the score when its figure cannot be resolved. */\n @Prop() scoreErrorMessage: string | undefined;\n\n /** Accessible name for the region. */\n @Prop() overviewLabel: string = 'Overview';\n\n /**\n * Page-controlled visual collapse from the full card (`0`) toward its 48px\n * compact handoff height (`1`). The component preserves its expanded flow\n * height, keeps the period bar stationary, and moves/clips the grid beneath\n * it. The page still owns sticky positioning and the final compact handoff.\n */\n @Prop() scrollCollapseProgress: number = 0;\n\n /** Emitted when a metric that is not inactive is activated. */\n @Event() dsMetricSelect!: EventEmitter;\n\n /** Roving tab stop across selectable metrics. */\n @State() private focusedMetricIndex: number = 0;\n @State() private expandedHeight: number = 0;\n @State() private gridColumns: number | undefined;\n\n private layoutEl?: HTMLElement;\n private layoutResizeObserver: ResizeObserver | null = null;\n /** The node the observer is bound to, which a later render can replace. */\n private observedLayoutEl?: HTMLElement;\n\n componentDidLoad() {\n this.observeLayout();\n }\n\n componentDidRender() {\n // Re-bind after HMR when DidLoad's observer was dropped, and whenever a\n // render swapped the layout node out from under the observer: the ref points\n // at the new node while the observer still watches the detached one, which\n // never resizes again. The grid would then keep its first measured column\n // count for the life of the component.\n if (!this.layoutResizeObserver || this.observedLayoutEl !== this.layoutEl) {\n this.observeLayout();\n } else {\n this.updateLayoutGeometry();\n }\n }\n\n disconnectedCallback() {\n this.layoutResizeObserver?.disconnect();\n this.layoutResizeObserver = null;\n this.observedLayoutEl = undefined;\n }\n\n private get visibleMetrics(): OverviewMetric[] {\n return this.metrics.slice(0, MAX_METRIC_COUNT);\n }\n\n private get visibleCellCount(): number {\n const metricCount = this.isLoading ? this.loadingMetricCount : this.visibleMetrics.length;\n return 1 + metricCount;\n }\n\n /** Preserve an authored data shape while loading, or use the standard six-cell grid. */\n private get loadingMetricCount(): number {\n return this.visibleMetrics.length || DEFAULT_LOADING_METRIC_COUNT;\n }\n\n private get resolvedScrollCollapseProgress(): number {\n if (this.variant === 'compact' || !Number.isFinite(this.scrollCollapseProgress)) return 0;\n return Math.min(1, Math.max(0, this.scrollCollapseProgress));\n }\n\n private get scrollCollapseGeometry() {\n const compactHeight = resolveCssLengthPx(TOKEN_DEFAULTS.size600, 48);\n return resolveCardOverviewCollapseGeometry({\n variant: this.variant,\n progress: this.resolvedScrollCollapseProgress,\n expandedHeight: this.expandedHeight,\n compactHeight,\n });\n }\n\n private observeLayout() {\n const layout = this.layoutEl;\n if (!layout) return;\n\n const bounds = layout.getBoundingClientRect();\n this.updateLayoutGeometry(bounds.width, bounds.height);\n if (typeof ResizeObserver === 'undefined') return;\n\n this.layoutResizeObserver?.disconnect();\n this.layoutResizeObserver = new ResizeObserver(entries => {\n const rect = entries[0]?.contentRect;\n if (rect) this.updateLayoutGeometry(rect.width, rect.height);\n });\n this.layoutResizeObserver.observe(layout);\n this.observedLayoutEl = layout;\n }\n\n private updateLayoutGeometry(width?: number, height?: number) {\n const layout = this.layoutEl;\n if (!layout) return;\n\n const bounds = width === undefined || height === undefined ? layout.getBoundingClientRect() : null;\n const resolvedWidth = width ?? bounds?.width ?? 0;\n const resolvedHeight = height ?? bounds?.height ?? 0;\n\n let changed = false;\n\n if (resolvedHeight > 0 && Math.abs(resolvedHeight - this.expandedHeight) >= 0.5) {\n this.expandedHeight = resolvedHeight;\n changed = true;\n }\n\n const columns = resolveOverviewGridColumns({\n cellCount: this.visibleCellCount,\n availableWidth: resolvedWidth,\n minCellWidth: resolveCssLengthPx(this.metricMinWidth, DEFAULT_METRIC_MIN_WIDTH),\n });\n if (columns !== this.gridColumns) {\n this.gridColumns = columns;\n changed = true;\n }\n\n // The column count is written straight to the host rather than through the\n // rendered style object. Measurement happens in `componentDidLoad` and in the\n // ResizeObserver callback, both outside a render cycle, and the host's style\n // is not patched again after the first render — so a rendered value would stay\n // pinned to whatever the first paint produced, before any width was known.\n if (this.gridColumns) {\n this.el.style.setProperty('--ds-card-overview-grid-columns', String(this.gridColumns));\n } else {\n this.el.style.removeProperty('--ds-card-overview-grid-columns');\n }\n\n if (changed) forceUpdate(this);\n }\n\n /** Index of the roving tab stop, skipping inactive metrics. */\n private get rovingIndex(): number {\n return resolveOverviewRovingIndex(this.visibleMetrics, this.focusedMetricIndex);\n }\n\n private selectMetric(metric: OverviewMetric, index: number) {\n if (metric.isInactive) return;\n this.focusedMetricIndex = index;\n this.dsMetricSelect.emit(metric);\n }\n\n /** Move the roving tab stop, wrapping and skipping inactive metrics. */\n private moveFocus(from: number, step: number) {\n const metrics = this.visibleMetrics;\n const next = findNextOverviewMetricIndex(metrics, from, step < 0 ? -1 : 1);\n if (next < 0) return;\n\n this.focusedMetricIndex = next;\n const cells = this.el.querySelectorAll('.card-overview__metric-action');\n cells[next]?.focus();\n }\n\n private handleMetricKeyDown = (event: KeyboardEvent, index: number) => {\n switch (event.key) {\n case 'ArrowRight':\n case 'ArrowDown':\n event.preventDefault();\n this.moveFocus(index, 1);\n break;\n case 'ArrowLeft':\n case 'ArrowUp':\n event.preventDefault();\n this.moveFocus(index, -1);\n break;\n default:\n break;\n }\n };\n\n /**\n * A skeleton bar matching the type metrics of the text it stands in for, so the\n * loading state holds the same shape and rhythm as the resolved content.\n *\n * `background` is always passed so the base and shimmer follow the card's\n * permanently dark surface in both themes.\n */\n private bar(textVariant: TextVariant, width: string, className?: string) {\n return (\n \n );\n }\n\n /**\n * Arrow and change in one text node.\n *\n * The arrow is a typeface glyph rather than an icon so it inherits the exact\n * size, weight, and baseline of the value beside it; an icon would need its\n * own size scale and would drift whenever the type scale changed.\n *\n * Tone is supplied by the caller and never inferred here.\n */\n private renderTrend(trend: MetricTrend | undefined, variant: TextVariant) {\n if (!trend) return null;\n return (\n \n {trend.direction === 'up' ? '↑' : '↓'} {trend.value}\n \n );\n }\n\n private renderScore() {\n if (this.isLoading) {\n return (\n
\n
\n
\n {this.bar('text-display-small', '40px')}\n
\n
\n {this.bar('text-body-small', '64px', 'card-overview__score-label-spacer')}\n {this.bar('text-body-medium', '28px')}\n
\n
\n
\n );\n }\n\n const unavailableMessage =\n this.scoreErrorMessage || (!this.score ? 'Score unavailable' : undefined);\n if (unavailableMessage) {\n return (\n /* eslint-disable-next-line local/prefer-direct-ds-text -- The score track owns the grid divider and 8px outer inset. */\n
\n \n {unavailableMessage}\n \n
\n );\n }\n\n const score = this.score;\n if (!score) return null;\n const level = score.level ?? resolveSafetyScoreLevel(score.value);\n\n return (\n
\n
\n {/* eslint-disable-next-line local/prefer-direct-ds-text -- The fill owns its own box: it pads out to 52px and crops the display line box, which the text element cannot do to itself. */}\n \n \n {score.value}\n \n
\n
\n \n  \n \n {this.renderTrend(score.trend, 'text-body-medium')}\n
\n
\n \n );\n }\n\n private renderMetric(metric: OverviewMetric, index: number) {\n const selectable = !metric.isInactive;\n const label = (\n \n {metric.label}\n \n );\n\n return (\n
\n this.selectMetric(metric, index)}\n onKeyDown={event => this.handleMetricKeyDown(event, index)}\n onFocusin={() => {\n if (selectable) this.focusedMetricIndex = index;\n }}\n >\n
\n {metric.labelTooltip ? (\n \n {label}\n \n ) : (\n label\n )}\n
\n \n {metric.value}\n \n {this.renderTrend(metric.trend, 'text-body-medium')}\n
\n
\n
\n \n );\n }\n\n private renderMetrics() {\n if (this.isLoading) {\n return [\n this.renderScore(),\n ...Array.from({ length: this.loadingMetricCount }, (_, index) => (\n
\n
\n
\n {this.bar('text-body-small', '35%', 'card-overview__metric-label')}\n
\n {this.bar('text-body-medium', '40px')}\n {/* Match renderTrend's type canvas and the score trend's 28px width. */}\n {this.bar('text-body-medium', '28px')}\n
\n
\n
\n
\n )),\n ];\n }\n\n return [\n this.renderScore(),\n ...this.visibleMetrics.map((metric, index) => this.renderMetric(metric, index)),\n ];\n }\n\n render() {\n const compact = this.variant === 'compact';\n const collapse = this.scrollCollapseGeometry;\n\n // Omit absent custom properties rather than handing them an undefined value.\n // Stencil serialises undefined to the string \"undefined\", which is invalid in\n // `repeat()` and voids the whole grid-template-columns declaration — the grid\n // then collapses to one implicit column instead of using the `auto-fit`\n // fallback baked into the stylesheet.\n const customProperties: Record = {\n '--ds-card-overview-metric-min': this.metricMinWidth,\n };\n if (this.gridColumns) {\n customProperties['--ds-card-overview-grid-columns'] = String(this.gridColumns);\n }\n if (collapse.active) {\n customProperties['--ds-card-overview-expanded-height'] = `${collapse.expandedHeight}px`;\n customProperties['--ds-card-overview-visible-height'] = `${collapse.visibleHeight}px`;\n customProperties['--ds-card-overview-content-offset'] = `${collapse.offset}px`;\n }\n\n return (\n \n \n
\n {\n this.layoutEl = (element as HTMLElement) ?? undefined;\n }}\n class={{\n 'card-overview__layout': true,\n }}\n >\n
\n
\n
\n
\n \n {this.periodLabel && (\n /* eslint-disable-next-line local/prefer-direct-ds-text -- Fixed copy uses the same structural frame and label inset as a slotted Select. */\n
\n \n {this.periodLabel}\n \n
\n )}\n \n
\n {this.comparisonLabel && (\n \n {this.comparisonLabel}\n \n )}\n
\n
\n \n
\n
\n
\n\n {!compact && (\n
\n
\n {this.renderMetrics()}\n
\n\n \n
\n )}\n
\n \n \n \n );\n }\n}\n", "type": "registry:ui" }, { "path": "src/wc/components/CardOverview/card-overview-controller.ts", "content": "import type {\n CardOverviewVariant,\n OverviewMetric,\n SafetyScoreLevel,\n} from './card-overview-types';\n\nexport interface CardOverviewCollapseGeometry {\n active: boolean;\n expandedHeight: number;\n offset: number;\n visibleHeight: number;\n}\n\n/**\n * Choose the column count for the metric grid.\n *\n * Cells that all fit across one row stay on one row: a full row is already\n * balanced, so there is nothing to distribute.\n *\n * Once the width forces a wrap, prefer equal rows — the widest column count\n * that divides the total exactly. Eight cells therefore step 8 → 4+4 → 2+2+2+2\n * as the width narrows, never trading an equal split for a shorter grid.\n *\n * Totals with no equal split available fall back to the fewest rows that fit,\n * spread as evenly as possible, which leaves one short final row: five cells at\n * a four-cell width are 3+2, seven are 4+3.\n *\n * Width is the only ceiling. There is deliberately no column cap: a wide card\n * showing six cells that each clear `minCellWidth` renders all six across.\n */\nexport function resolveOverviewGridColumns(options: {\n cellCount: number;\n availableWidth: number;\n minCellWidth: number;\n}): number {\n const cellCount = Math.max(1, Math.floor(options.cellCount));\n const minCellWidth = Math.max(1, options.minCellWidth);\n const fittingColumns = Math.max(\n 1,\n Math.floor(Math.max(0, options.availableWidth) / minCellWidth)\n );\n\n if (fittingColumns >= cellCount) return cellCount;\n\n for (let columns = fittingColumns; columns >= 2; columns -= 1) {\n if (cellCount % columns === 0) return columns;\n }\n\n const rows = Math.ceil(cellCount / fittingColumns);\n return Math.ceil(cellCount / rows);\n}\n\nexport function resolveCardOverviewCollapseGeometry(options: {\n variant: CardOverviewVariant;\n progress: number;\n expandedHeight: number;\n compactHeight: number;\n}): CardOverviewCollapseGeometry {\n const compactHeight = Math.max(0, options.compactHeight);\n const expandedHeight = Math.max(options.expandedHeight, compactHeight);\n const progress =\n options.variant === 'compact' || !Number.isFinite(options.progress)\n ? 0\n : Math.min(1, Math.max(0, options.progress));\n const distance = Math.max(0, expandedHeight - compactHeight);\n const offset = distance * progress;\n\n return {\n active: progress > 0 && distance > 0,\n expandedHeight,\n offset,\n visibleHeight: expandedHeight - offset,\n };\n}\n\nexport function resolveSafetyScoreLevel(value: string | number): SafetyScoreLevel | undefined {\n const numericValue = typeof value === 'number' ? value : Number(value);\n if (!Number.isFinite(numericValue) || numericValue < 0 || numericValue > 100) return undefined;\n if (numericValue <= 50) return 'fair';\n if (numericValue <= 80) return 'good';\n return 'excellent';\n}\n\nexport function resolveOverviewRovingIndex(\n metrics: readonly OverviewMetric[],\n focusedIndex: number\n): number {\n const first = metrics.findIndex(metric => !metric.isInactive);\n if (first < 0) return -1;\n return metrics[focusedIndex] && !metrics[focusedIndex].isInactive\n ? focusedIndex\n : first;\n}\n\nexport function findNextOverviewMetricIndex(\n metrics: readonly OverviewMetric[],\n from: number,\n step: -1 | 1\n): number {\n for (let offset = 1; offset <= metrics.length; offset += 1) {\n const next = (((from + step * offset) % metrics.length) + metrics.length) % metrics.length;\n if (!metrics[next]?.isInactive) return next;\n }\n return -1;\n}\n", "type": "registry:ui" }, { "path": "src/wc/components/CardOverview/card-overview-types.ts", "content": "import type { MetricTrend } from '../../utils/metric-change';\n\nexport type CardOverviewVariant = 'default' | 'compact';\nexport type CardOverviewLayout = 'auto' | 'stacked';\nexport type SafetyScoreLevel = 'fair' | 'good' | 'excellent';\n\n/**\n * Leading summary block — the headline figure the rest of the bar contextualises.\n *\n * Derive `trend` with `resolveMetricTrend` so whether a rise reads well stays a\n * product decision rather than a design-system one.\n */\nexport interface OverviewScore {\n /** Display-ready headline figure. */\n value: string | number;\n /** Change against the comparison period. Omit when there is nothing to report. */\n trend?: MetricTrend;\n /**\n * Safety score color level. Numeric values from 0–100 infer fair (0–50),\n * good (51–80), or excellent (81–100) when this is omitted.\n */\n level?: SafetyScoreLevel;\n /** @deprecated Ignored. The redesigned score cell no longer renders a band. */\n band?: string;\n}\n\n/** One measure in the overview grid. */\nexport interface OverviewMetric {\n /** Stable identity for keyed rendering and selection events. */\n id: string;\n label: string;\n /** Display-ready value; format compactly before passing it in. */\n value: string | number;\n /** Change against the comparison period. Omit when there is nothing to report. */\n trend?: MetricTrend;\n /** Present the measure without making it selectable. */\n isInactive?: boolean;\n /** Supplementary explanation for the label. */\n labelTooltip?: string;\n}\n", "type": "registry:ui" } ] }