@ds-mo/ui 12.7.0 → 12.9.0

package/dist/.build-stamp

@@ -1 +1 @@
-1785106690096
+1785378569056

package/dist/agent-patterns.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "12.7.0",
+  "packageVersion": "12.9.0",
   "kind": "patterns",
   "entries": [
     {
@@ -354,10 +354,11 @@
     {
       "id": "pattern:menu-trigger",
       "status": "stable",
-      "summary": "Connect a ButtonUnfilled trigger to an anchored Menu for a compact command or view-selection popup without application-authored positioning.",
+      "summary": "Connect a button trigger to an anchored Menu for a compact command or view-selection popup without application-authored positioning.",
       "useWhen": [
         "A button should reveal a short contextual collection of commands.",
-        "A compact button should show the current view or mode and let the user choose another one from a menu."
+        "A compact button should show the current view or mode and let the user choose another one from a menu.",
+        "A row, card, or toolbar needs an overflow or more-options menu."
       ],
       "avoidWhen": [
         "The choice is a submitted form value with a field label or validation; use Select.",
@@ -368,24 +369,36 @@
       "components": [
         {
           "component": "component:ds-button-unfilled",
-          "role": "Provides the visible trigger, popup relationship attributes, and focus target.",
+          "role": "Provides the visible trigger, popup relationship attributes, and focus target. Carries both shapes, and is the only component that carries the icon-only overflow role.",
           "required": true
         },
         {
           "component": "component:ds-menu",
           "role": "Owns anchored placement, menu semantics, keyboard navigation, viewport clamping, selection, and close behavior.",
           "required": true
+        },
+        {
+          "component": "component:ds-button-filled",
+          "role": "Substitutes for the trigger when the menu belongs to the single primary action in a local decision area, using the label or icon-label shape only.",
+          "required": false
         }
       ],
       "stateOwnership": [
         "The application owns the selected command or view value and derives the trigger label and each item's isSelected state from it.",
-        "The application synchronizes one open boolean to ButtonUnfilled.expanded and Menu.open.",
+        "The application synchronizes one open boolean to the trigger's expanded prop and Menu.open.",
+        "An open popup is a transient pressed state, not a selected one. The trigger holds its pressed wash for the popup's rendered lifecycle from expanded alone, so never also set isActive to represent an open menu.",
         "Menu owns popup placement and keyboard navigation; the application never calculates popup coordinates or applies positional CSS.",
         "On dsSelect, update the selected value, close the Menu, and restore focus to the trigger.",
         "On dsClose, synchronize the application open state to false."
       ],
       "accessibility": [
-        "Set ButtonUnfilled.haspopup to menu, controls to the Menu id, and expanded from the same open state passed to Menu.",
+        "A button either has a menu or is a menu, and the trigger's variant selects between the two shapes.",
+        "Has a menu: a label or icon-label action that opens a menu. Set hasMenu, which implies aria-haspopup of menu and renders the trailing chevron that communicates the popup. Both button primitives support this shape.",
+        "Is a menu: an icon-only overflow or more-options control. Set hasMenu, which adds no chevron, so the glyph must convey the menu alone; use Ellipses. Only ButtonUnfilled carries this shape, because the role is chrome rather than a primary action.",
+        "Never pair hasMenu with an icon-only glyph that does not read as a menu on its own; there is no chevron to fall back on.",
+        "Set controls to the Menu id and expanded from the same open state passed to Menu.",
+        "Give an icon-only trigger an accessible name that states the role, such as More options, because no visible label or chevron carries it.",
+        "Use haspopup directly instead of hasMenu for a non-menu popup such as a listbox or dialog; those cases get no chevron.",
         "Give Menu a concise menuLabel describing the available commands or views.",
         "Set Menu.initialFocusVisible only when the trigger MouseEvent detail is zero, indicating keyboard activation.",
         "Keep visible selected styling synchronized with the application's selected value; Menu exposes the selected command through aria-current.",
@@ -408,7 +421,7 @@
                 {
                   "path": "view-menu.html",
                   "language": "html",
-                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  label=\"View · Overview\"\n  haspopup=\"menu\"\n  controls=\"view-menu\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchor-id=\"view-menu-trigger\"\n  menu-label=\"Choose view\"\n></ds-menu>"
+                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  label=\"View · Overview\"\n  has-menu\n  controls=\"view-menu\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchor-id=\"view-menu-trigger\"\n  menu-label=\"Choose view\"\n></ds-menu>\n\n<!-- Overflow shape: the Ellipses glyph conveys the menu, so no chevron is added. -->\n<ds-button-unfilled\n  id=\"row-menu-trigger\"\n  variant=\"icon\"\n  icon=\"Ellipses\"\n  aria-label=\"More options\"\n  has-menu\n  controls=\"row-menu\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"row-menu\"\n  anchor-id=\"row-menu-trigger\"\n  menu-label=\"More options\"\n  align=\"end\"\n></ds-menu>"
                 },
                 {
                   "path": "view-menu.ts",
@@ -438,7 +451,7 @@
                 {
                   "path": "ViewMenu.tsx",
                   "language": "tsx",
-                  "content": "import { useState } from 'react'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled, DsMenu } from '@ds-mo/ui/react'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nexport function ViewMenu() {\n  const [selectedValue, setSelectedValue] = useState('overview')\n  const [open, setOpen] = useState(false)\n  const [initialFocusVisible, setInitialFocusVisible] = useState(false)\n  const selected = choices.find(item => item.value === selectedValue) ?? choices[0]\n  const items = choices.map(item => ({ ...item, isSelected: item.value === selectedValue }))\n\n  function focusTrigger() {\n    requestAnimationFrame(() => {\n      const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n      trigger?.setFocus()\n    })\n  }\n\n  return (\n    <>\n      <DsButtonUnfilled\n        id=\"view-menu-trigger\"\n        label={`View · ${selected.label}`}\n        haspopup=\"menu\"\n        controls=\"view-menu\"\n        expanded={open}\n        onDsClick={event => {\n          setInitialFocusVisible(event.detail.detail === 0)\n          setOpen(current => !current)\n        }}\n      />\n      <DsMenu\n        id=\"view-menu\"\n        anchorId=\"view-menu-trigger\"\n        menuLabel=\"Choose view\"\n        items={items}\n        open={open}\n        initialFocusVisible={initialFocusVisible}\n        onDsClose={() => setOpen(false)}\n        onDsSelect={event => {\n          setSelectedValue(event.detail.value ?? selectedValue)\n          setOpen(false)\n          focusTrigger()\n        }}\n      />\n    </>\n  )\n}"
+                  "content": "import { useState } from 'react'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled, DsMenu } from '@ds-mo/ui/react'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nexport function ViewMenu() {\n  const [selectedValue, setSelectedValue] = useState('overview')\n  const [open, setOpen] = useState(false)\n  const [initialFocusVisible, setInitialFocusVisible] = useState(false)\n  const selected = choices.find(item => item.value === selectedValue) ?? choices[0]\n  const items = choices.map(item => ({ ...item, isSelected: item.value === selectedValue }))\n\n  function focusTrigger() {\n    requestAnimationFrame(() => {\n      const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n      trigger?.setFocus()\n    })\n  }\n\n  return (\n    <>\n      <DsButtonUnfilled\n        id=\"view-menu-trigger\"\n        label={`View · ${selected.label}`}\n        hasMenu\n        controls=\"view-menu\"\n        expanded={open}\n        onDsClick={event => {\n          setInitialFocusVisible(event.detail.detail === 0)\n          setOpen(current => !current)\n        }}\n      />\n      <DsMenu\n        id=\"view-menu\"\n        anchorId=\"view-menu-trigger\"\n        menuLabel=\"Choose view\"\n        items={items}\n        open={open}\n        initialFocusVisible={initialFocusVisible}\n        onDsClose={() => setOpen(false)}\n        onDsSelect={event => {\n          setSelectedValue(event.detail.value ?? selectedValue)\n          setOpen(false)\n          focusTrigger()\n        }}\n      />\n    </>\n  )\n}"
                 }
               ],
               "notes": [
@@ -463,7 +476,7 @@
                 {
                   "path": "view-menu.component.html",
                   "language": "html",
-                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  [label]=\"'View · ' + selectedLabel\"\n  haspopup=\"menu\"\n  controls=\"view-menu\"\n  [expanded]=\"open\"\n  (dsClick)=\"toggleMenu($event)\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchorId=\"view-menu-trigger\"\n  menuLabel=\"Choose view\"\n  [items]=\"menuItems\"\n  [open]=\"open\"\n  [initialFocusVisible]=\"initialFocusVisible\"\n  (dsClose)=\"open = false\"\n  (dsSelect)=\"selectView($event)\"\n></ds-menu>"
+                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  [label]=\"'View · ' + selectedLabel\"\n  has-menu\n  controls=\"view-menu\"\n  [expanded]=\"open\"\n  (dsClick)=\"toggleMenu($event)\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchorId=\"view-menu-trigger\"\n  menuLabel=\"Choose view\"\n  [items]=\"menuItems\"\n  [open]=\"open\"\n  [initialFocusVisible]=\"initialFocusVisible\"\n  (dsClose)=\"open = false\"\n  (dsSelect)=\"selectView($event)\"\n></ds-menu>"
                 },
                 {
                   "path": "view-menu.component.ts",

package/dist/agent.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "12.7.0",
+  "packageVersion": "12.9.0",
   "kind": "components",
   "entries": [
     {
@@ -1273,7 +1273,8 @@
           "The action is unfilled icon-only shell or navigation chrome.",
           "The element represents navigation rather than a command.",
           "The content is a persistent selected state rather than an action.",
-          "A semantic color would be decorative or merely match the surrounding product area."
+          "A semantic color would be decorative or merely match the surrounding product area.",
+          "The control is an overflow or more-options menu whose only content is an Ellipses glyph; that role is never filled."
         ],
         "alternatives": [
           {
@@ -1285,14 +1286,25 @@
             "when": "The user is choosing a destination in application navigation.",
             "component": "component:ds-panel-nav",
             "reason": "Navigation components own destination selection, active state, and navigation semantics."
+          },
+          {
+            "when": "The control is the overflow or more-options menu for a row, card, or toolbar.",
+            "component": "component:ds-button-unfilled",
+            "reason": "An icon-only Ellipses trigger is chrome, and its glyph conveys the menu without a chevron; a filled button never carries that role."
           }
         ],
         "commonlyComposedWith": [
           "component:ds-modal",
-          "component:ds-field"
+          "component:ds-field",
+          "component:ds-menu"
+        ],
+        "patterns": [
+          "pattern:menu-trigger"
         ],
         "accessibility": [
           "Provide an explicit accessible name for icon-only buttons.",
+          "Set hasMenu when the action opens a Menu; it implies aria-haspopup of menu and renders the trailing chevron. Pass controls with the Menu id and expanded from the same open state given to Menu.",
+          "Use haspopup directly for a non-menu popup such as a dialog; that case gets no chevron.",
           "Use inactive state only when the action must remain visible but unavailable.",
           "Do not encode the action meaning through color alone.",
           "Loading keeps the action focused and named, exposes busy and disabled state, and blocks activation; announce broader operation progress from the owning workflow when users need confirmation.",
@@ -1307,7 +1319,11 @@
           "Parent surface context changes only the optional inset border color. Contrast continues to own the button fill, foreground, hover, pressed, and focus treatments; never use surface context to change action hierarchy.",
           "Rounded changes only the control radius to the half-radius treatment; it does not change hierarchy, size, variant, intent, or interaction semantics.",
           "Loading prevents duplicate activation without applying inactive opacity or removing the current keyboard focus.",
-          "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width."
+          "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width.",
+          "Physical press scaling is on by default. Disable it only when an owning composite must keep child or background geometry fixed; hover and pressed interaction washes remain available.",
+          "ButtonFilled has no active or selected state; a filled action is a command, not a toggle or a persistent selection.",
+          "An open popup is a transient pressed state instead. While expanded is true the pressed wash is held for the popup's complete rendered lifecycle and survives hover, so the trigger reads as held open without introducing a selected treatment.",
+          "hasMenu supports only the label and icon-label variants. The chevron is what communicates that a menu will open, so an icon-only filled menu button would leave the affordance unstated."
         ],
         "responsiveBehavior": [
           "Use fill width only when the parent layout calls for a full-width action, commonly on narrow form layouts."
@@ -1344,10 +1360,26 @@
             "type": "ButtonFilledContrast",
             "required": false
           },
+          "controls": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "expanded": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "hasBorder": {
             "type": "boolean",
             "required": false
           },
+          "hasMenu": {
+            "type": "boolean",
+            "required": false
+          },
+          "haspopup": {
+            "type": "ButtonFilledPopup | undefined",
+            "required": false
+          },
           "icon": {
             "type": "string",
             "required": false
@@ -1368,6 +1400,14 @@
             "type": "string",
             "required": false
           },
+          "pressScale": {
+            "type": "boolean",
+            "required": false
+          },
+          "pressed": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "rounded": {
             "type": "boolean",
             "required": false
@@ -1427,7 +1467,8 @@
         "useWhen": [
           "A secondary command accompanies the single filled primary action in a local decision area.",
           "A toolbar, tool rail, overflow area, or shell region needs a compact icon action.",
-          "A command represents a persistent toggle or mode whose active state remains meaningful after activation."
+          "A command represents a persistent toggle or mode whose active state remains meaningful after activation.",
+          "A row, card, or toolbar needs an overflow or more-options menu; this is the only component that carries that role."
         ],
         "avoidWhen": [
           "The command is the single primary action in a local decision area; use ButtonFilled instead.",
@@ -1462,6 +1503,9 @@
         ],
         "accessibility": [
           "Provide an explicit accessible name for every icon-only action.",
+          "Set hasMenu when the button triggers a Menu; it implies aria-haspopup of menu. Pass controls with the Menu id and expanded from the same open state given to Menu.",
+          "Give an icon-only menu button an accessible name that states the role, such as More options, because no visible label or chevron carries it.",
+          "Use haspopup directly for a non-menu popup such as a listbox or dialog; those cases get no chevron.",
           "Use active state only for a persistent toggle or mode, and synchronize pressed semantics unless an owning composite exposes the selection state.",
           "Treat notification dots as supplemental unread or status information; never use a dot as the sole state, meaning, or accessible name.",
           "Loading keeps the action focused and named, exposes busy and disabled state, and blocks activation; announce broader operation progress from the owning workflow when needed.",
@@ -1476,7 +1520,11 @@
           "Surface context must match the actual parent surface; translucent, inverted, media, and always-dark treatments are reserved for those surfaces.",
           "Loading prevents duplicate activation without applying inactive opacity or removing the current keyboard focus.",
           "Rounded changes only the control radius to the half-radius treatment; it does not change hierarchy, size, variant, or interaction semantics.",
-          "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width."
+          "Physical press scaling is on by default. Disable it only when an owning composite must keep child or background geometry fixed; hover and pressed interaction washes remain available.",
+          "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width.",
+          "hasMenu covers two distinct menu-button shapes and the variant selects between them. With label or icon-label the action has a menu, and a trailing chevron carries the affordance. With icon the button is a menu, meaning the overflow or more-options control, and no chevron is added.",
+          "Because the icon-only shape has no chevron, its glyph must convey the menu on its own; use Ellipses. Never pair hasMenu with an icon-only glyph that does not read as a menu.",
+          "An open popup is a transient pressed state rather than a selected one. While expanded is true the pressed wash is held for the popup's complete rendered lifecycle and survives hover, including when chrome opts out of selected fills with activeFill set to false."
         ],
         "responsiveBehavior": [
           "The consuming layout decides when an icon-label action becomes icon-only and must provide an explicit accessible name after changing variants.",
@@ -1535,6 +1583,10 @@
             "type": "boolean",
             "required": false
           },
+          "hasMenu": {
+            "type": "boolean",
+            "required": false
+          },
           "haspopup": {
             "type": "ButtonUnfilledPopup | undefined",
             "required": false
@@ -1559,6 +1611,10 @@
             "type": "string",
             "required": false
           },
+          "pressScale": {
+            "type": "boolean",
+            "required": false
+          },
           "pressed": {
             "type": "boolean | undefined",
             "required": false
@@ -1669,7 +1725,7 @@
           "The owning product controls data, filtering, loading, empty, and error state; the card emits the filter action only."
         ],
         "responsiveBehavior": [
-          "The selected sm, md, or lg shell size controls the card dimensions while the bar chart shrinks within its chart region.",
+          "The selected sm, md, or lg shell size controls the card dimensions while the bar chart reflows to the chart region without visually scaling its primitives.",
           "The horizontal legend wraps complete entries when the available width is constrained.",
           "The parent dashboard owns card wrapping and breakpoint changes."
         ],
@@ -1782,6 +1838,7 @@
         ],
         "responsiveBehavior": [
           "Select the token-based card width appropriate to the parent grid; the matching minimum height preserves the chart region.",
+          "The donut measures the chart region and changes radius within its shared size band while token thickness and typography remain fixed.",
           "The parent dashboard owns wrapping and column changes while the internal chart-over-legend arrangement remains stable."
         ],
         "frameworkCaveats": {
@@ -1893,7 +1950,7 @@
           "The owning product controls data, filtering, loading, empty, and error state; the card emits the filter action only."
         ],
         "responsiveBehavior": [
-          "The selected sm, md, or lg shell size controls the card dimensions while the line chart shrinks within its chart region.",
+          "The selected sm, md, or lg shell size controls the card dimensions while the line chart reflows to the chart region without visually scaling its primitives.",
           "The horizontal legend wraps complete entries when the available width is constrained.",
           "The parent dashboard owns card wrapping and breakpoint changes."
         ],
@@ -1952,6 +2009,168 @@
         "card-shell-data-viz"
       ]
     },
+    {
+      "id": "component:ds-card-overview",
+      "tag": "ds-card-overview",
+      "name": "card-overview",
+      "title": "CardOverview",
+      "summary": "Page-level summary card pairing one headline score with a reporting period, an application-owned period control, and a responsive grid of comparable measures, with an optional compact 48px presentation.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "experimental",
+        "summary": "Page-level summary card pairing one headline score with a reporting period, an application-owned period control, and a responsive grid of comparable measures, with an optional compact 48px presentation.",
+        "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-shell-data-viz",
+            "reason": "CardShellDataViz owns the data-visualization shell 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.",
+          "Trend arrows are decorative and hidden from assistive technology, so the formatted change value must read correctly on its own.",
+          "Colour never carries the trend meaning alone; the arrow direction and the value are both present.",
+          "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 the bar without a headline figure. Set scoreErrorMessage to report that the figure could not be resolved while the measures remain readable.",
+          "Loading replaces the score and the measures with skeletons and does not alter the slotted period control.",
+          "At most six measures are shown. Keep larger collections outside the summary bar rather than turning it into a dense dashboard.",
+          "The period control is slotted rather than owned, because the choice of stepper, select, or date range varies by product surface.",
+          "compact is exactly 48px high and keeps only the score label, score value, trend, reporting copy, and slotted period control. It omits the score band, measures, and footer."
+        ],
+        "responsiveBehavior": [
+          "The measure grid reflows to fewer columns and finally stacks, driven by the minimum measure width alone. There is no measurement and no horizontal scrolling.",
+          "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 score block hugs its content and never shrinks, so the headline figure holds its size while the grid absorbs the remaining width.",
+          "Once the card reaches its narrow stacked state, one summary block holds the score label, score, trend, score band, reporting period, and the application-owned period control above the single-column measures.",
+          "In that stacked summary, the score and trend share one line at the start, while the score band is hidden to preserve space. The period control stays at the upper end, while the current period and comparison sit on separate right-aligned lines beside the score.",
+          "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 or choose its own presentation. The page owner may use compact as sticky summary chrome on supported breakpoints."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign score and metrics as JavaScript properties; both are objects and cannot be expressed as HTML attributes.",
+            "Place the period control in the filter slot; the component reserves space for it but never renders one."
+          ],
+          "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."
+          ],
+          "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."
+          ]
+        },
+        "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",
+            "required": false
+          },
+          "isLoading": {
+            "type": "boolean",
+            "required": false
+          },
+          "layout": {
+            "type": "CardOverviewLayout",
+            "required": false
+          },
+          "metricMinWidth": {
+            "type": "string",
+            "required": false
+          },
+          "metrics": {
+            "type": "OverviewMetric[]",
+            "required": false
+          },
+          "overviewLabel": {
+            "type": "string",
+            "required": false
+          },
+          "periodLabel": {
+            "type": "string",
+            "required": false
+          },
+          "score": {
+            "type": "OverviewScore | undefined",
+            "required": false
+          },
+          "scoreErrorMessage": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "variant": {
+            "type": "CardOverviewVariant",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsMetricSelect",
+            "detail": "OverviewMetric"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-card-overview",
+        "react": "DsCardOverview",
+        "angular": "DsCardOverview"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon",
+        "skeleton",
+        "text",
+        "tooltip"
+      ]
+    },
     {
       "id": "component:ds-card-setting",
       "tag": "ds-card-setting",
@@ -2260,7 +2479,8 @@
           "Authored datum colors override the shared categorical palette."
         ],
         "responsiveBehavior": [
-          "The owner supplies dimensions and updates them with its layout; the chart does not measure its container.",
+          "Width and height provide the standalone intrinsic viewport; container constraints are measured and reflow the plot across the available pixels.",
+          "Responsive layout changes bar positions and plot extents without scaling SVG text, strokes, corner radii, or margins.",
           "Limit or pre-format long category labels so they remain legible at the chosen width.",
           "Time labels remain ordered, pre-formatted buckets with equal spacing rather than raw continuous timestamps."
         ],
@@ -2269,10 +2489,10 @@
             "Assign data as a JavaScript property; arrays are not supported as HTML attributes."
           ],
           "react": [
-            "Pass a stable data array and dimensions derived from the containing layout."
+            "Pass a stable data array; width and height provide standalone intrinsic dimensions while constrained containers reflow automatically."
           ],
           "angular": [
-            "Bind data as a property and update dimensions from the containing layout."
+            "Bind data as a property; width and height provide standalone intrinsic dimensions while constrained containers reflow automatically."
           ]
         },
         "references": [
@@ -2369,8 +2589,9 @@
           "Negative values are unsupported and render as zero; the owning product supplies loading, empty, and error states."
         ],
         "responsiveBehavior": [
-          "The SVG preserves its authored aspect ratio while shrinking to fit a narrower parent.",
-          "The parent supplies dimensions and chooses how many time buckets remain legible at each width.",
+          "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": {
@@ -2482,6 +2703,7 @@
         "responsiveBehavior": [
           "Prefer container-fill sizing inside data-viz cards and explicit sizing only in layouts that own a stable diameter.",
           "Fill sizing remains centered and constrained to the shared donut size band.",
+          "Changing the measured diameter changes the ring radius without scaling its token-based thickness, typography, focus stroke, or corner treatment.",
           "The owner adapts category count and legend placement for available space."
         ],
         "frameworkCaveats": {
@@ -2764,7 +2986,8 @@
           "Authored series colors override the shared categorical palette."
         ],
         "responsiveBehavior": [
-          "The owner supplies intrinsic dimensions; the SVG preserves its aspect ratio while shrinking to fit a narrower parent.",
+          "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 point positions and plot extents without scaling SVG text, line strokes, point markers, or margins.",
           "Category positions are always equally spaced, even when labels represent time.",
           "Reduce or pre-format dense labels before passing them; the chart renders authored labels without a continuous time scale."
         ],
@@ -2773,10 +2996,10 @@
             "Assign series and categories as JavaScript properties and keep every series aligned to the category count."
           ],
           "react": [
-            "Pass stable series and category arrays with dimensions derived from the containing layout."
+            "Pass stable series and category arrays; width and height provide standalone intrinsic dimensions while constrained containers reflow automatically."
           ],
           "angular": [
-            "Bind series and categories as properties with dimensions derived from the containing layout."
+            "Bind series and categories as properties; width and height provide standalone intrinsic dimensions while constrained containers reflow automatically."
           ]
         },
         "references": [
@@ -6138,6 +6361,7 @@
           "Tools with search compose ds-panel-tool-search immediately below the shared header. Its 48px row always contains the md search control and must not be reduced to sm or xs.",
           "If an active optional tool becomes unavailable, PanelTools closes the drawer, clears activeTool, and emits its deselection.",
           "Use isInactive only for a temporarily unavailable visible tool; omit tools the user is not authorized to access.",
+          "Rail actions disable physical press scaling so notification-dot halos remain aligned to the shell gradient; hover and pressed washes continue to paint above the dot and halo.",
           "The application owns slotted tool products and data while PanelTools owns rail ordering, drawer selection, open state, motion, and shell events.",
           "Opening and closing clip an already-rendered fixed-width surface. Header and tool content remain fully opaque and retained during width motion; transition completion is accepted only at the measured terminal clip width, after which the closed surface becomes inert and paint-skipped.",
           "Entering and exiting fullscreen snaps without borrowing the drawer open or close animation.",
@@ -7444,7 +7668,8 @@
           "A ShellPage-managed BarTitle remains concealed until headerCapacity is available and its rendered variant matches the resolved presentation, preventing a default-variant flash during route activation.",
           "responsiveMode=mobile hides and inerts the desktop header, exposes mobile-header, and disables desktop scroll-compaction geometry.",
           "Update headerCapacity synchronously with shell layout state so opening tools or crossing application breakpoints cannot briefly render the wrong presentation.",
-          "On roomy pages, the expanded header scrolls upward until its title and action row reaches the compact row position, then snaps variants without moving that shared visual anchor.",
+          "The default content inset is 32px in desktop mode and 16px in tablet and mobile modes, while preserving the larger bottom scroll space.",
+          "On roomy pages, the expanded header scrolls upward until its title and action row reaches the compact row position, while its bottom divider progressively extends from the expanded inset to edge-to-edge; it then snaps variants without moving that shared visual anchor.",
           "Scroll compaction preserves the expanded page flow offset so content never jumps beneath the sticky header.",
           "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling.",
           "BarWorkflow remains compact and is not assigned BarTitle's capacity or scroll variants."
@@ -8652,7 +8877,7 @@
         "states": [
           "A variant is atomic: font size, line height, weight, and letter spacing stay together and are not overridden by consumers.",
           "Emphasis selects the supported stronger recipe for local hierarchy; it does not independently mean selected or active.",
-          "Omitted color inherits currentColor. Explicit semantic aliases or CSS-variable references are used only when Text has an independent color role.",
+          "Omitted color inherits currentColor without imposing a host color declaration, so an owning component may apply its semantic foreground directly without depending on stylesheet order. Explicit semantic aliases or CSS-variable references are used when Text has an independent color role.",
           "Prefer the owning control's isInactive or native disabled state over manually selecting tertiary or quaternary so visual treatment and inactive semantics remain synchronized.",
           "Line truncation and wrapping require an owner-supplied width constraint and content-aware composition decision.",
           "Solid underline is the default link affordance; brand-blue links may omit it at rest. Dotted underline communicates hidden or supplemental interaction such as a tooltip. Decoration does not make Text interactive by itself.",
@@ -9004,7 +9229,7 @@
           },
           {
             "label": "Positioning unit coverage",
-            "path": "tests/tooltip-position.test.ts"
+            "path": "tests/anchored-position.test.ts"
           }
         ]
       },
@@ -9111,6 +9336,8 @@
           "The owning chart mounts the callout when a local interaction starts and unmounts it when that interaction ends.",
           "Coordinate updates track within one mounted interaction session without restarting the show delay.",
           "Placement flips horizontally or vertically when the rendered callout approaches a viewport edge.",
+          "Placement is chosen as a quadrant rather than computed as coordinates: the component measures its own rendered rect and flips its side and align props, which CSS consumes. It therefore does not use the shared anchored-position utilities, which resolve an anchor element into x and y.",
+          "This separation is deliberate. The callout follows the pointer instead of an element, so it has no anchor rect to resolve; adopting the shared geometry would mean rewriting its CSS to consume coordinates for no behavioral gain.",
           "Reduced motion preserves the final visible state without an opacity transition."
         ],
         "responsiveBehavior": [

package/dist/angular/ds-button-filled.d.ts

@@ -8,7 +8,7 @@ export declare class DsButtonFilled {
     dsClick: EventEmitter<DsButtonFilledCustomEvent<MouseEvent>>;
     constructor(c: ChangeDetectorRef, r: ElementRef, z: NgZone);
     static ɵfac: i0.ɵɵFactoryDeclaration<DsButtonFilled, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DsButtonFilled, "ds-button-filled", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; }; "background": { "alias": "background"; "required": false; }; "contrast": { "alias": "contrast"; "required": false; }; "hasBorder": { "alias": "hasBorder"; "required": false; }; "icon": { "alias": "icon"; "required": false; }; "intent": { "alias": "intent"; "required": false; }; "isInactive": { "alias": "isInactive"; "required": false; }; "isLoading": { "alias": "isLoading"; "required": false; }; "label": { "alias": "label"; "required": false; }; "rounded": { "alias": "rounded"; "required": false; }; "size": { "alias": "size"; "required": false; }; "type": { "alias": "type"; "required": false; }; "variant": { "alias": "variant"; "required": false; }; "width": { "alias": "width"; "required": false; }; }, { "dsClick": "dsClick"; }, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DsButtonFilled, "ds-button-filled", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; }; "background": { "alias": "background"; "required": false; }; "contrast": { "alias": "contrast"; "required": false; }; "controls": { "alias": "controls"; "required": false; }; "expanded": { "alias": "expanded"; "required": false; }; "hasBorder": { "alias": "hasBorder"; "required": false; }; "hasMenu": { "alias": "hasMenu"; "required": false; }; "haspopup": { "alias": "haspopup"; "required": false; }; "icon": { "alias": "icon"; "required": false; }; "intent": { "alias": "intent"; "required": false; }; "isInactive": { "alias": "isInactive"; "required": false; }; "isLoading": { "alias": "isLoading"; "required": false; }; "label": { "alias": "label"; "required": false; }; "pressScale": { "alias": "pressScale"; "required": false; }; "pressed": { "alias": "pressed"; "required": false; }; "rounded": { "alias": "rounded"; "required": false; }; "size": { "alias": "size"; "required": false; }; "type": { "alias": "type"; "required": false; }; "variant": { "alias": "variant"; "required": false; }; "width": { "alias": "width"; "required": false; }; }, { "dsClick": "dsClick"; }, never, ["*"], true, never>;
 }
 export declare interface DsButtonFilled extends Components.DsButtonFilled {
     dsClick: EventEmitter<DsButtonFilledCustomEvent<MouseEvent>>;

package/dist/angular/ds-button-filled.js

@@ -18,12 +18,12 @@ let DsButtonFilled = class DsButtonFilled {
         this.el = r.nativeElement;
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: DsButtonFilled, deps: [{ token: i0.ChangeDetectorRef }, { token: i0.ElementRef }, { token: i0.NgZone }], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.0.7", type: DsButtonFilled, isStandalone: true, selector: "ds-button-filled", inputs: { ariaLabel: "ariaLabel", background: "background", contrast: "contrast", hasBorder: "hasBorder", icon: "icon", intent: "intent", isInactive: "isInactive", isLoading: "isLoading", label: "label", rounded: "rounded", size: "size", type: "type", variant: "variant", width: "width" }, outputs: { dsClick: "dsClick" }, ngImport: i0, template: '<ng-content></ng-content>', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.0.7", type: DsButtonFilled, isStandalone: true, selector: "ds-button-filled", inputs: { ariaLabel: "ariaLabel", background: "background", contrast: "contrast", controls: "controls", expanded: "expanded", hasBorder: "hasBorder", hasMenu: "hasMenu", haspopup: "haspopup", icon: "icon", intent: "intent", isInactive: "isInactive", isLoading: "isLoading", label: "label", pressScale: "pressScale", pressed: "pressed", rounded: "rounded", size: "size", type: "type", variant: "variant", width: "width" }, outputs: { dsClick: "dsClick" }, ngImport: i0, template: '<ng-content></ng-content>', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
 };
 DsButtonFilled = __decorate([
     ProxyCmp({
         defineCustomElementFn: defineDsButtonFilled,
-        inputs: ['ariaLabel', 'background', 'contrast', 'hasBorder', 'icon', 'intent', 'isInactive', 'isLoading', 'label', 'rounded', 'size', 'type', 'variant', 'width'],
+        inputs: ['ariaLabel', 'background', 'contrast', 'controls', 'expanded', 'hasBorder', 'hasMenu', 'haspopup', 'icon', 'intent', 'isInactive', 'isLoading', 'label', 'pressScale', 'pressed', 'rounded', 'size', 'type', 'variant', 'width'],
         methods: ['setFocus']
     })
 ], DsButtonFilled);
@@ -35,7 +35,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     template: '<ng-content></ng-content>',
                     // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-                    inputs: ['ariaLabel', 'background', 'contrast', 'hasBorder', 'icon', 'intent', 'isInactive', 'isLoading', 'label', 'rounded', 'size', 'type', 'variant', 'width'],
+                    inputs: ['ariaLabel', 'background', 'contrast', 'controls', 'expanded', 'hasBorder', 'hasMenu', 'haspopup', 'icon', 'intent', 'isInactive', 'isLoading', 'label', 'pressScale', 'pressed', 'rounded', 'size', 'type', 'variant', 'width'],
                     outputs: ['dsClick'],
                 }]
         }], ctorParameters: () => [{ type: i0.ChangeDetectorRef }, { type: i0.ElementRef }, { type: i0.NgZone }], propDecorators: { dsClick: [{