@ds-mo/ui 14.25.0 → 14.26.0

package/dist/mcp-data/registry/score.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "score",
+  "title": "Score",
+  "description": "Safety-score figure in a semantic fill at the three control densities.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/score",
+    "source": "src/wc/components/Score/Score.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "general",
+      "status": "experimental",
+      "summary": "Safety-score figure in a semantic fill at the three control densities.",
+      "useWhen": [
+        "A driver or fleet safety score needs its fair, good, or excellent fill and the numeric figure in one place.",
+        "The same score treatment appears in Card Overview, an in-card summary, or a compact row such as a table group header."
+      ],
+      "avoidWhen": [
+        "The figure is an ordinary metric without a safety-score color band; use Text.",
+        "The score is one cell in a comparable measures grid that also needs period chrome; use CardOverview, which composes Score.",
+        "The mark is a notification count or status label; use Badge or Tag.",
+        "A comparison trend should sit beside the fill; keep trend in the owner. Card Overview already renders score trend in its copy column."
+      ],
+      "alternatives": [
+        {
+          "when": "The figure is one of several comparable measures under a shared period bar.",
+          "component": "component:ds-card-overview",
+          "reason": "CardOverview owns the summary grid, period chrome, score-cell alignment, and score trend; it renders Score at lg for the fill."
+        },
+        {
+          "when": "The quantity is ordinary readable content without a safety-score fill.",
+          "component": "component:ds-text",
+          "reason": "Text preserves the figure as body content."
+        },
+        {
+          "when": "The compact mark is unread count or notification presence.",
+          "component": "component:ds-badge",
+          "reason": "Badge owns supplemental notification chrome, not a scored figure."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-card-overview",
+        "component:ds-table",
+        "component:ds-text",
+        "component:ds-skeleton"
+      ],
+      "accessibility": [
+        "Set label when the atomic score graphic needs a spoken prefix such as Safety score; the visible number remains in the fill.",
+        "Colour never carries score meaning alone; the numeric figure stays visible inside the fill.",
+        "Score is not interactive and is not a tab stop.",
+        "While loading, the host exposes a busy state and a skeleton whose type metrics match the resolved size."
+      ],
+      "states": [
+        "lg is the Card Overview fill: 56 by 40, display-small emphasis. md is the 32px control treatment: 40 by 32, title-large emphasis. sm is the 24px compact fill: 28 by 24, title-small emphasis. The fill box crops the type canvas so line-height does not change the declared size.",
+        "A numeric value from 0–100 infers fair from 0–50, good from 51–80, and excellent from 81–100. Empty or whitespace-only values stay on the faint neutral surface. Supply level explicitly when another displayed value needs a semantic fill.",
+        "The fill uses the safety-score background and keeps its foreground at AA text contrast in light and dark themes.",
+        "isLoading replaces the figure with a skeleton at the matching type metrics. The skeleton uses the faint context when no score level is known and the bold context when a known or explicitly supplied level keeps its semantic fill."
+      ],
+      "responsiveBehavior": [
+        "The owner selects sm, md, or lg to match the local layout. Score does not change size at breakpoints.",
+        "sm is the density for table group headers. md is the in-card summary fill. lg is the Card Overview fill."
+      ],
+      "references": [
+        {
+          "label": "Storybook examples",
+          "path": "src/wc/components/Score/Score.stories.ts"
+        },
+        {
+          "label": "Safety-score level unit coverage",
+          "path": "tests/score-model.test.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "isLoading": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "is-loading",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Replace the figure with a skeleton while data resolves."
+        },
+        "label": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "label",
+          "default": "''",
+          "required": false,
+          "mutable": false,
+          "description": "Accessible name prefix, for example “Safety score”."
+        },
+        "level": {
+          "type": "SafetyScoreLevel | undefined",
+          "resolvedType": "\"excellent\" | \"fair\" | \"good\" | undefined",
+          "attribute": "level",
+          "required": false,
+          "mutable": false,
+          "description": "Safety-score color level. Numeric values from 0–100 infer fair (0–50),\ngood (51–80), or excellent (81–100) when this is omitted."
+        },
+        "size": {
+          "type": "ScoreSize",
+          "resolvedType": "\"lg\" | \"md\" | \"sm\"",
+          "attribute": "size",
+          "default": "'md'",
+          "required": false,
+          "mutable": false,
+          "description": "Visual density matching control height: `sm` 24px, `md` 32px, `lg` 40px.\n`lg` is the Card Overview recipe."
+        },
+        "value": {
+          "type": "string | number",
+          "resolvedType": "number | string",
+          "attribute": "value",
+          "default": "''",
+          "required": false,
+          "mutable": false,
+          "description": "Display-ready headline figure."
+        }
+      },
+      "events": [],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "isLoading": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "is-loading",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Replace the figure with a skeleton while data resolves."
+      },
+      "label": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "label",
+        "default": "''",
+        "required": false,
+        "mutable": false,
+        "description": "Accessible name prefix, for example “Safety score”."
+      },
+      "level": {
+        "type": "SafetyScoreLevel | undefined",
+        "resolvedType": "\"excellent\" | \"fair\" | \"good\" | undefined",
+        "attribute": "level",
+        "required": false,
+        "mutable": false,
+        "description": "Safety-score color level. Numeric values from 0–100 infer fair (0–50),\ngood (51–80), or excellent (81–100) when this is omitted."
+      },
+      "size": {
+        "type": "ScoreSize",
+        "resolvedType": "\"lg\" | \"md\" | \"sm\"",
+        "attribute": "size",
+        "default": "'md'",
+        "required": false,
+        "mutable": false,
+        "description": "Visual density matching control height: `sm` 24px, `md` 32px, `lg` 40px.\n`lg` is the Card Overview recipe."
+      },
+      "value": {
+        "type": "string | number",
+        "resolvedType": "number | string",
+        "attribute": "value",
+        "default": "''",
+        "required": false,
+        "mutable": false,
+        "description": "Display-ready headline figure."
+      }
+    },
+    "events": [],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-score",
+      "react": "DsScore",
+      "vue": "DsScore",
+      "angular": "DsScore"
+    },
+    "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-score.js';",
+        "example": "<ds-score></ds-score>"
+      },
+      "react": {
+        "import": "import { DsScore } from '@ds-mo/ui/react';",
+        "example": "<DsScore />"
+      },
+      "vue": {
+        "import": "import { DsScore } from '@ds-mo/ui/vue';",
+        "example": "<DsScore />"
+      },
+      "angular": {
+        "import": "import { DsScore } from '@ds-mo/ui/angular/ds-score';",
+        "example": "<ds-score></ds-score>"
+      },
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^6.5.1",
+          "@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"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/Score/Score.css",
+      "content": "@import '../../utils/control-parts.css';\n@import '../../utils/forced-colors.css';\n\n:host {\n  display: inline-flex;\n  align-items: center;\n  box-sizing: border-box;\n  min-width: 0;\n  --_score-badge-inline-size: var(--dimension-size-500);\n  --_score-badge-block-size: var(--dimension-size-400);\n  /* Matches the text skeleton’s 75% bar so the fill inset is even on all sides. */\n  --_score-skeleton-inset: calc(var(--_score-badge-block-size) / 8);\n}\n\n:host(.score--sm) {\n  --_score-badge-inline-size: calc(var(--dimension-size-400) - var(--dimension-space-050));\n  --_score-badge-block-size: var(--dimension-size-300);\n}\n\n:host(.score--md) {\n  --_score-badge-inline-size: var(--dimension-size-500);\n  --_score-badge-block-size: var(--dimension-size-400);\n}\n\n:host(.score--lg) {\n  --_score-badge-inline-size: calc(var(--dimension-size-600) + var(--dimension-space-100));\n  --_score-badge-block-size: var(--dimension-size-500);\n}\n\n.score__badge {\n  display: flex;\n  flex: 0 0 auto;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  inline-size: var(--_score-badge-inline-size);\n  block-size: var(--_score-badge-block-size);\n  overflow: hidden;\n  border-radius: var(--dimension-radius-025);\n  background: var(--color-background-faint-neutral);\n  color: var(--color-foreground-bold-neutral);\n  -webkit-user-select: none;\n  user-select: none;\n}\n\n.score__badge--fair {\n  background: var(--color-safety-score-background-fair);\n  color: var(--color-safety-score-foreground-on-fair);\n}\n\n.score__badge--good {\n  background: var(--color-safety-score-background-good);\n  color: var(--color-foreground-primary);\n}\n\n.score__badge--excellent {\n  background: var(--color-safety-score-background-excellent);\n  color: var(--color-safety-score-foreground-on-excellent);\n}\n\n.score__value,\n.score__badge ds-skeleton {\n  flex: 0 0 auto;\n}\n\n.score__badge--loading {\n  padding-inline: var(--_score-skeleton-inset);\n}\n\n.score__badge--loading .score__value {\n  flex: 1 1 auto;\n  inline-size: 100%;\n  block-size: 100%;\n  max-inline-size: 100%;\n  max-block-size: 100%;\n  min-inline-size: 0;\n}\n\n@media (forced-colors: active) {\n  .score__badge {\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/Score/Score.tsx",
+      "content": "import { Component, Prop, h, Host } from '@stencil/core';\nimport { SCORE_VALUE_VARIANT, resolveScoreLevel } from './score-model';\nimport type { SafetyScoreLevel, ScoreSize } from './score-types';\n\n@Component({\n  tag: 'ds-score',\n  styleUrl: 'Score.css',\n  scoped: true,\n})\nexport class Score {\n  /** Display-ready headline figure. */\n  @Prop() value: string | number = '';\n  /**\n   * Visual density matching control height: `sm` 24px, `md` 32px, `lg` 40px.\n   * `lg` is the Card Overview recipe.\n   */\n  @Prop() size: ScoreSize = 'md';\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  @Prop() level: SafetyScoreLevel | undefined;\n  /** Replace the figure with a skeleton while data resolves. */\n  @Prop() isLoading: boolean = false;\n  /** Accessible name prefix, for example “Safety score”. */\n  @Prop() label: string = '';\n\n  render() {\n    const size = this.size;\n    const level = resolveScoreLevel(this.value, this.level);\n    const valueVariant = SCORE_VALUE_VARIANT[size];\n    const accessibleName = [this.label.trim(), this.isLoading ? '' : this.value]\n      .filter(Boolean)\n      .join(' ');\n\n    return (\n      <Host\n        class={{\n          score: true,\n          [`score--${size}`]: true,\n          'score--loading': this.isLoading,\n        }}\n        role={accessibleName ? 'img' : undefined}\n        aria-busy={this.isLoading ? 'true' : undefined}\n        aria-label={accessibleName || undefined}\n      >\n        <span\n          class={{\n            score__badge: true,\n            [`score__badge--${level}`]: Boolean(level),\n            'score__badge--loading': this.isLoading,\n          }}\n        >\n          {this.isLoading ? (\n            <ds-skeleton\n              class=\"score__value\"\n              variant=\"text\"\n              textVariant={valueVariant}\n              background={level ? 'bold' : 'faint'}\n            />\n          ) : (\n            <ds-text\n              as=\"span\"\n              class=\"score__value ds-control-label-box\"\n              variant={valueVariant}\n              emphasis={true}\n              color=\"inherit\"\n              fontFeature=\"tabular-nums\"\n            >\n              {this.value}\n            </ds-text>\n          )}\n        </span>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Score/score-model.ts",
+      "content": "import { SAFETY_SCORE_LEVELS, type SafetyScoreLevel, type ScoreSize } from './score-types';\n\nexport function isSafetyScoreLevel(value: unknown): value is SafetyScoreLevel {\n  return typeof value === 'string' && (SAFETY_SCORE_LEVELS as readonly string[]).includes(value);\n}\n\n/**\n * Infer a safety-score color level from a 0–100 figure. Non-numeric or out-of-range\n * values return undefined so the owner can supply `level` explicitly.\n */\nexport function resolveSafetyScoreLevel(value: string | number): SafetyScoreLevel | undefined {\n  if (typeof value === 'string' && value.trim() === '') return 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 resolveScoreLevel(\n  value: string | number,\n  level?: SafetyScoreLevel\n): SafetyScoreLevel | undefined {\n  return isSafetyScoreLevel(level) ? level : resolveSafetyScoreLevel(value);\n}\n\nexport const SCORE_VALUE_VARIANT = {\n  sm: 'text-title-small',\n  md: 'text-title-large',\n  lg: 'text-display-small',\n} as const satisfies Record<\n  ScoreSize,\n  'text-title-small' | 'text-title-large' | 'text-display-small'\n>;\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Score/score-types.ts",
+      "content": "export type SafetyScoreLevel = 'fair' | 'good' | 'excellent';\nexport type ScoreSize = 'sm' | 'md' | 'lg';\n\nexport const SCORE_SIZES = ['sm', 'md', 'lg'] as const;\nexport const SAFETY_SCORE_LEVELS = ['fair', 'good', 'excellent'] as const;\n",
+      "type": "registry:ui"
+    }
+  ]
+}