@ds-mo/ui 14.5.0 → 14.6.0

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

@@ -45,12 +45,13 @@
         "component:ds-button-filled",
         "component:ds-button-unfilled",
         "component:ds-panel-nav",
-        "component:ds-panel-tools"
+        "component:ds-panel-tools",
+        "component:ds-table"
       ],
       "accessibility": [
         "The slotted trigger must have its own accessible name, usually an aria-label that closely matches the visual tooltip label.",
         "Tooltip content is supplementary and non-essential; touch input intentionally does not open it.",
-        "While open, the trigger is linked to the role=tooltip popup with aria-describedby; the relationship is removed when the popup leaves the DOM without disturbing consumer description IDs.",
+        "While open, the trigger is linked to the role=tooltip popup with aria-describedby by default; the relationship is removed when the popup leaves the DOM without disturbing consumer description IDs. Hosts that already expose the full string, such as a truncated table cell, disable that relationship.",
         "Keyboard focus opens the tooltip and Escape dismisses it without moving focus."
       ],
       "states": [
@@ -58,18 +59,20 @@
         "An empty or whitespace-only label suppresses the popup while preserving the wrapper.",
         "Only one tooltip remains active globally; warm handoff removes the previous popup before showing the next.",
         "Disconnecting and reinserting the tooltip host rebinds the current slotted trigger.",
+        "A host may present the popup against an external anchor it already owns, without wrapping that trigger or binding hover on it.",
         "The preferred side flips when it cannot fit, then alignment is clamped to viewport padding.",
         "Reduced motion removes enter and exit fades while retaining the final visible or hidden state."
       ],
       "responsiveBehavior": [
         "The portaled popup follows trigger and popup resize, viewport resize, and nested scrolling while open.",
         "Touch users rely on the trigger's accessible and visible context rather than tooltip disclosure.",
-        "Keep labels concise and non-wrapping; use inline text or a larger disclosure component for essential explanation."
+        "Keep labels concise and non-wrapping by default; omitted table cell values may wrap at panel-xs."
       ],
       "frameworkCaveats": {
         "customElements": [
           "Place exactly one trigger element as the component's light-DOM child.",
           "Replacing the slotted trigger rebinds pointer and focus behavior automatically.",
+          "A table or similar host can present the popup against an overflowing text node instead of wrapping that node.",
           "sideOffset, alignOffset, and delay accept numbers or TokoMo CSS values."
         ],
         "react": [
@@ -122,6 +125,15 @@
           "mutable": false,
           "description": "Hover show delay before the tooltip appears.\nDefault: `--effect-animation-delay-medium-3` (1000ms). Accepts a number (ms)\nor a TokoMo time token / `var(--effect-animation-delay-*)`. Applies to the\ninitial hover/focus show only — after a recent dismiss, reopen is instant.\nPrefer the default; override only for denser chrome or rare/destructive actions."
         },
+        "describedBy": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "described-by",
+          "default": "true",
+          "required": false,
+          "mutable": false,
+          "description": "Link the trigger with aria-describedby while the popup is open. Disable when\nthe label is already in the DOM, such as a truncated table cell."
+        },
         "label": {
           "type": "string",
           "resolvedType": "string",
@@ -170,10 +182,30 @@
           "required": false,
           "mutable": false,
           "description": "Control density (height, padding, type)."
+        },
+        "wrapLabel": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "wrap-label",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Allow the label to wrap at a panel-xs max width instead of a single line."
         }
       },
       "events": [],
-      "methods": [],
+      "methods": [
+        {
+          "name": "dismiss",
+          "signature": "dismiss() => Promise<void>",
+          "description": "Dismiss a popup opened through presentFrom or the slotted trigger."
+        },
+        {
+          "name": "presentFrom",
+          "signature": "presentFrom(anchor: HTMLElement, label?: string) => Promise<void>",
+          "description": "Present against an external anchor the host already measured.\nDoes not bind hover or focus on that anchor — the owner drives show/hide."
+        }
+      ],
       "slots": []
     },
     "props": {
@@ -203,6 +235,15 @@
         "mutable": false,
         "description": "Hover show delay before the tooltip appears.\nDefault: `--effect-animation-delay-medium-3` (1000ms). Accepts a number (ms)\nor a TokoMo time token / `var(--effect-animation-delay-*)`. Applies to the\ninitial hover/focus show only — after a recent dismiss, reopen is instant.\nPrefer the default; override only for denser chrome or rare/destructive actions."
       },
+      "describedBy": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "described-by",
+        "default": "true",
+        "required": false,
+        "mutable": false,
+        "description": "Link the trigger with aria-describedby while the popup is open. Disable when\nthe label is already in the DOM, such as a truncated table cell."
+      },
       "label": {
         "type": "string",
         "resolvedType": "string",
@@ -251,10 +292,30 @@
         "required": false,
         "mutable": false,
         "description": "Control density (height, padding, type)."
+      },
+      "wrapLabel": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "wrap-label",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Allow the label to wrap at a panel-xs max width instead of a single line."
       }
     },
     "events": [],
-    "methods": [],
+    "methods": [
+      {
+        "name": "dismiss",
+        "signature": "dismiss() => Promise<void>",
+        "description": "Dismiss a popup opened through presentFrom or the slotted trigger."
+      },
+      {
+        "name": "presentFrom",
+        "signature": "presentFrom(anchor: HTMLElement, label?: string) => Promise<void>",
+        "description": "Present against an external anchor the host already measured.\nDoes not bind hover or focus on that anchor — the owner drives show/hide."
+      }
+    ],
     "slots": [],
     "exports": {
       "customElement": "ds-tooltip",
@@ -295,12 +356,12 @@
   "files": [
     {
       "path": "src/wc/components/Tooltip/Tooltip.css",
-      "content": "@import '../../utils/control-density.css';\n@import '../../utils/key-hint.css';\n@import '../../utils/forced-colors.css';\n\n.tooltip-popup {\n  box-sizing: border-box;\n  background-color: var(--color-background-primary);\n  border-radius: var(--ds-control-radius, var(--dimension-radius-025));\n  box-shadow: var(--effect-elevation-elevated-floating);\n  white-space: nowrap;\n  pointer-events: none;\n  animation: tooltipFadeIn var(--effect-motion-short-2) forwards;\n  will-change: transform;\n  backface-visibility: hidden;\n}\n\n/* Warm handoff between nearby triggers — no enter fade (avoids 20–100ms lag). */\n.tooltip-popup--instant {\n  animation: none;\n  opacity: 1;\n}\n\n.tooltip-popup--closing {\n  animation: tooltipFadeOut var(--effect-motion-short-3) forwards;\n}\n\n/* Density: md / sm / xs via `.ds-control--*` on `.tooltip-inner`. */\n.tooltip-inner {\n  box-sizing: border-box;\n  height: var(--ds-control-height, var(--dimension-size-400));\n  display: flex;\n  align-items: center;\n  gap: var(--ds-control-gap, var(--dimension-space-050));\n  padding: 0 var(--ds-control-padding-inline, var(--dimension-space-075));\n}\n\n/*\n * Label layout lives on ds-text (metric-box + control label-inset).\n * NOTE: Stencil scopes this to `ds-text.sc-ds-tooltip`, but portaled\n * createElement ds-text loses that class when Text's <Host class> renders.\n * `renderPopupContent` therefore also sets these as inline styles.\n */\n.tooltip-inner > ds-text {\n  flex-shrink: 0;\n  min-width: max-content;\n  max-width: none;\n  padding: 0 var(--ds-control-label-inset, var(--dimension-space-025));\n  color: var(--color-foreground-primary);\n}\n\n@keyframes tooltipFadeIn {\n  from { opacity: 0; }\n  to   { opacity: 1; }\n}\n\n@keyframes tooltipFadeOut {\n  from { opacity: 1; }\n  to   { opacity: 0; }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .tooltip-popup,\n  .tooltip-popup--instant {\n    animation: none;\n    opacity: 1;\n  }\n\n  .tooltip-popup--closing {\n    animation: none;\n    opacity: 0;\n  }\n}\n\n@media (forced-colors: active) {\n  .tooltip-popup {\n    box-shadow: none;\n    outline: var(--dimension-stroke-width-012) solid var(--ds-forced-color-content);\n    outline-offset: calc(-1 * var(--dimension-stroke-width-012));\n  }\n}\n",
+      "content": "@import '../../utils/control-density.css';\n@import '../../utils/key-hint.css';\n@import '../../utils/forced-colors.css';\n\n.tooltip-popup {\n  box-sizing: border-box;\n  background-color: var(--color-background-primary);\n  border-radius: var(--ds-control-radius, var(--dimension-radius-025));\n  box-shadow: var(--effect-elevation-elevated-floating);\n  white-space: nowrap;\n  pointer-events: none;\n  animation: tooltipFadeIn var(--effect-motion-short-2) forwards;\n  will-change: transform;\n  backface-visibility: hidden;\n}\n\n/* Warm handoff between nearby triggers — no enter fade (avoids 20–100ms lag). */\n.tooltip-popup--instant {\n  animation: none;\n  opacity: 1;\n}\n\n.tooltip-popup--closing {\n  animation: tooltipFadeOut var(--effect-motion-short-3) forwards;\n}\n\n/* Density: md / sm / xs via `.ds-control--*` on `.tooltip-inner`. */\n.tooltip-inner {\n  box-sizing: border-box;\n  height: var(--ds-control-height, var(--dimension-size-400));\n  display: flex;\n  align-items: center;\n  gap: var(--ds-control-gap, var(--dimension-space-050));\n  padding: 0 var(--ds-control-padding-inline, var(--dimension-space-075));\n}\n\n/*\n * Label layout lives on ds-text (metric-box + control label-inset).\n * NOTE: Stencil scopes this to `ds-text.sc-ds-tooltip`, but portaled\n * createElement ds-text loses that class when Text's <Host class> renders.\n * `renderPopupContent` therefore also sets these as inline styles.\n */\n.tooltip-inner > ds-text {\n  flex-shrink: 0;\n  min-width: max-content;\n  max-width: none;\n  padding: 0 var(--ds-control-label-inset, var(--dimension-space-025));\n  color: var(--color-foreground-primary);\n}\n\n.tooltip-popup--wrap {\n  white-space: normal;\n  max-inline-size: var(--dimension-panel-width-xs);\n}\n\n.tooltip-popup--wrap .tooltip-inner {\n  height: auto;\n  min-height: var(--ds-control-height, var(--dimension-size-400));\n  padding-block: var(--dimension-space-050);\n  align-items: flex-start;\n}\n\n.tooltip-popup--wrap .tooltip-inner > ds-text {\n  flex: 1 1 auto;\n  min-width: 0;\n  max-width: 100%;\n  white-space: normal;\n}\n\n@keyframes tooltipFadeIn {\n  from { opacity: 0; }\n  to   { opacity: 1; }\n}\n\n@keyframes tooltipFadeOut {\n  from { opacity: 1; }\n  to   { opacity: 0; }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .tooltip-popup,\n  .tooltip-popup--instant {\n    animation: none;\n    opacity: 1;\n  }\n\n  .tooltip-popup--closing {\n    animation: none;\n    opacity: 0;\n  }\n}\n\n@media (forced-colors: active) {\n  .tooltip-popup {\n    box-shadow: none;\n    outline: var(--dimension-stroke-width-012) solid var(--ds-forced-color-content);\n    outline-offset: calc(-1 * var(--dimension-stroke-width-012));\n  }\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/Tooltip/Tooltip.tsx",
-      "content": "import { Component, Prop, Element, Watch, h, Host } from '@stencil/core';\nimport {\n  CONTROL_TEXT_VARIANT,\n  resolveCssLengthPx,\n  resolveCssTimeMs,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n} from '../../utils';\nimport type { TextVariant } from '../Text/text-types';\nimport { shortcutKeyLabels } from '../../utils/shortcut-key';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\n// Side-effect: register `ds-text` — the portal builds it via createElement, not JSX.\nimport '../Text/Text';\n\nexport type TooltipSide = 'top' | 'right' | 'bottom' | 'left';\nexport type TooltipAlign = 'start' | 'center' | 'end';\nexport type TooltipSize = 'md' | 'sm' | 'xs';\n\nconst FALLBACK_HEIGHT: Record<TooltipSize, string> = {\n  md: TOKEN_DEFAULTS.size400,\n  sm: TOKEN_DEFAULTS.size300,\n  xs: TOKEN_DEFAULTS.size200,\n};\n\nlet lastDismissedAt = 0;\nlet tooltipIdCounter = 0;\n/** Currently open tooltip — force-cleared on warm handoff so tips don't cross-fade. */\nlet activeTooltip: Tooltip | null = null;\n\ntype DsTextEl = HTMLElement & {\n  as: string;\n  variant: TextVariant;\n  emphasis: boolean;\n  color: string;\n  wrap: string;\n};\n\nfunction createDsText(opts: {\n  variant: TextVariant;\n  emphasis?: boolean;\n  color?: string;\n  wrap?: 'wrap' | 'nowrap' | 'balance' | 'pretty';\n  text: string;\n}): DsTextEl {\n  const el = document.createElement('ds-text') as DsTextEl;\n  el.as = 'span';\n  el.variant = opts.variant;\n  el.emphasis = opts.emphasis ?? false;\n  el.color = opts.color ?? 'inherit';\n  if (opts.wrap) el.wrap = opts.wrap;\n  el.textContent = opts.text;\n  return el;\n}\n\n/**\n * Control-density label styles for portaled ds-text.\n * Scoped CSS requires `sc-ds-tooltip` on the host, but Text's `<Host class>`\n * overwrites imperative className — so these must be inline to stick.\n */\nfunction styleTooltipLabel(el: HTMLElement) {\n  el.style.flexShrink = '0';\n  el.style.minWidth = 'max-content';\n  el.style.maxWidth = 'none';\n  el.style.padding = '0 var(--ds-control-label-inset, var(--dimension-space-025))';\n  el.style.color = 'var(--color-foreground-primary)';\n}\n\n/**\n * Imperative body portal for the popup.\n * Stencil must not own the portaled node — moving a VDOM child to `document.body`\n * causes recreate → re-portal → @State loops that freeze the page.\n */\n@Component({\n  tag: 'ds-tooltip',\n  styleUrl: 'Tooltip.css',\n  scoped: true,\n})\nexport class Tooltip {\n  @Element() el!: HTMLElement;\n\n  /**\n   * Tooltip text. Empty/whitespace skips show — useful when the wrapper must stay\n   * mounted for layout/animation stability (e.g. PanelNav expand/collapse).\n   */\n  @Prop() label!: string;\n\n  /** Control density (height, padding, type). */\n  @Prop() size: TooltipSize = 'md';\n\n  @Prop() side: TooltipSide = 'top';\n  @Prop() align: TooltipAlign = 'center';\n  /** Gap between anchor and tooltip — number (px) or TokoMo length. */\n  @Prop() sideOffset: number | string = TOKEN_CSS_LENGTHS.space050;\n  /** Cross-axis offset — number (px) or TokoMo length. */\n  @Prop() alignOffset: number | string = 0;\n  /**\n   * Hover show delay before the tooltip appears.\n   * Default: `--effect-animation-delay-medium-3` (1000ms). Accepts a number (ms)\n   * or a TokoMo time token / `var(--effect-animation-delay-*)`. Applies to the\n   * initial hover/focus show only — after a recent dismiss, reopen is instant.\n   * Prefer the default; override only for denser chrome or rare/destructive actions.\n   */\n  @Prop() delay: number | string = TOKEN_DEFAULTS.animationDelayMedium3;\n  @Prop() shortcutKey: string | undefined;\n  @Prop() shortcutKeyPosition: 'start' | 'end' = 'end';\n\n  private tooltipId = `ds-tooltip-${++tooltipIdCounter}`;\n  private delayTimer: ReturnType<typeof setTimeout> | null = null;\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private anchor: HTMLElement | null = null;\n  private popupEl: HTMLElement | null = null;\n  private anchorObserver: MutationObserver | null = null;\n  private didLoad = false;\n  private readonly position = new AnchoredPositionController({\n    getAnchor: () => this.anchor,\n    getPopup: () => this.popupEl,\n    measure: (anchor, tip) => ({\n      anchorRect: anchor.getBoundingClientRect(),\n      // Fall back to token metrics until `ds-text` upgrades and reports a width.\n      popupWidth: tip.offsetWidth || this.tooltipFallbackWidthPx,\n      popupHeight: tip.offsetHeight || this.tooltipFallbackHeightPx,\n      side: this.side,\n      align: this.align,\n      sideOffsetPx: this.sideOffsetPx,\n      alignOffsetPx: this.alignOffsetPx,\n      viewportPadPx: this.viewportPadPx,\n      viewportWidth: window.innerWidth,\n      viewportHeight: window.innerHeight,\n    }),\n    apply: ({ x, y, resolvedSide }) => {\n      if (!this.popupEl) return;\n      this.popupEl.dataset.side = resolvedSide;\n      this.popupEl.style.transform = `translate(${Math.round(x)}px, ${Math.round(y)}px)`;\n    },\n    liveUpdate: 'frame',\n    observeResize: true,\n  });\n  private skipEnterAnimation = false;\n  private isOpen = false;\n  private lastInteractionWasKeyboard = false;\n  private pointerEnterHandler = (event: PointerEvent) => {\n    if (event.pointerType === 'touch') return;\n    this.show();\n  };\n  private pointerLeaveHandler = (event: PointerEvent) => {\n    if (event.pointerType === 'touch') return;\n    this.hide();\n  };\n  private pointerDownHandler = (event: PointerEvent) => {\n    this.lastInteractionWasKeyboard = false;\n    if (event.pointerType === 'touch' && (this.isOpen || this.popupEl)) this.hideInstant();\n  };\n  private keyDownHandler = () => {\n    this.lastInteractionWasKeyboard = true;\n  };\n  /** focusin/focusout so nested focus targets (e.g. ds-button-* inner button) still open the tip. */\n  private focusHandler = () => {\n    if (this.lastInteractionWasKeyboard || this.anchor?.matches(':focus-visible')) this.show();\n  };\n  private blurHandler: (e: FocusEvent) => void = (e) => {\n    const next = e.relatedTarget as Node | null;\n    if (next && this.anchor?.contains(next)) return;\n    this.hide();\n  };\n  private escapeHandler = (event: KeyboardEvent) => {\n    if (event.key !== 'Escape' || !this.isOpen) return;\n    event.preventDefault();\n    this.hide();\n  };\n\n  connectedCallback() {\n    if (!this.didLoad) return;\n    this.connectAnchor();\n  }\n\n  componentDidLoad() {\n    this.didLoad = true;\n    this.connectAnchor();\n  }\n\n  private connectAnchor() {\n    this.bindAnchor();\n    if (this.anchorObserver) return;\n    this.anchorObserver = new MutationObserver(() => this.handleSlotChange());\n    this.anchorObserver.observe(this.el, { childList: true });\n  }\n\n  disconnectedCallback() {\n    if (activeTooltip === this) activeTooltip = null;\n    this.anchorObserver?.disconnect();\n    this.anchorObserver = null;\n    this.unbindAnchor();\n    this.clearTimers();\n    this.destroyPopup();\n  }\n\n  @Watch('label')\n  @Watch('size')\n  @Watch('side')\n  @Watch('align')\n  @Watch('sideOffset')\n  @Watch('alignOffset')\n  @Watch('shortcutKey')\n  @Watch('shortcutKeyPosition')\n  onContentOrPositionChange() {\n    if (!this.label?.trim()) {\n      if (this.isOpen || this.popupEl) this.hideInstant();\n      return;\n    }\n    if (!this.popupEl || !this.isOpen) return;\n    this.renderPopupContent();\n    this.schedulePosition();\n  }\n\n  private get viewportPadPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n  }\n\n  private get sideOffsetPx(): number {\n    return resolveCssLengthPx(this.sideOffset, TOKEN_DEFAULTS.space050);\n  }\n\n  private get alignOffsetPx(): number {\n    return resolveCssLengthPx(this.alignOffset, 0);\n  }\n\n  private get hoverDelayMs(): number {\n    return resolveCssTimeMs(this.delay, TOKEN_DEFAULTS.animationDelayMedium3);\n  }\n\n  private get instantReopenMs(): number {\n    return resolveCssTimeMs(\n      TOKEN_DEFAULTS.animationDurationMedium1,\n      TOKEN_DEFAULTS.animationDurationMedium1,\n    );\n  }\n\n  private get fadeOutMs(): number {\n    return resolveMotionTimeMs(TOKEN_DEFAULTS.motionShort3, TOKEN_DEFAULTS.animationDurationShort3);\n  }\n\n  private get tooltipFallbackWidthPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.tooltipFallbackWidth, TOKEN_DEFAULTS.tooltipFallbackWidth);\n  }\n\n  private get tooltipFallbackHeightPx(): number {\n    const token = FALLBACK_HEIGHT[this.size];\n    return resolveCssLengthPx(token, token);\n  }\n\n  private bindAnchor() {\n    const slot = this.el.querySelector('slot') as HTMLSlotElement | null;\n    const slotted = slot?.assignedElements?.() ?? [];\n    const child = (slotted[0] ?? this.el.firstElementChild) as HTMLElement | null;\n    if (!child || child === this.anchor) return;\n    this.anchor = child;\n    child.addEventListener('pointerenter', this.pointerEnterHandler);\n    child.addEventListener('pointerleave', this.pointerLeaveHandler);\n    child.addEventListener('pointerdown', this.pointerDownHandler);\n    child.addEventListener('keydown', this.keyDownHandler);\n    child.addEventListener('focusin', this.focusHandler);\n    child.addEventListener('focusout', this.blurHandler);\n  }\n\n  private unbindAnchor() {\n    if (!this.anchor) return;\n    this.unlinkDescribedBy();\n    this.anchor.removeEventListener('pointerenter', this.pointerEnterHandler);\n    this.anchor.removeEventListener('pointerleave', this.pointerLeaveHandler);\n    this.anchor.removeEventListener('pointerdown', this.pointerDownHandler);\n    this.anchor.removeEventListener('keydown', this.keyDownHandler);\n    this.anchor.removeEventListener('focusin', this.focusHandler);\n    this.anchor.removeEventListener('focusout', this.blurHandler);\n    this.anchor = null;\n  }\n\n  private linkDescribedBy() {\n    if (!this.anchor || !this.popupEl) return;\n    const ids = new Set((this.anchor.getAttribute('aria-describedby') ?? '').split(/\\s+/).filter(Boolean));\n    ids.add(this.tooltipId);\n    this.anchor.setAttribute('aria-describedby', Array.from(ids).join(' '));\n  }\n\n  private unlinkDescribedBy() {\n    if (!this.anchor) return;\n    const ids = (this.anchor.getAttribute('aria-describedby') ?? '')\n      .split(/\\s+/)\n      .filter(id => id && id !== this.tooltipId);\n    if (ids.length) this.anchor.setAttribute('aria-describedby', ids.join(' '));\n    else this.anchor.removeAttribute('aria-describedby');\n  }\n\n  private handleSlotChange = () => {\n    const slot = this.el.querySelector('slot') as HTMLSlotElement | null;\n    const next = (slot?.assignedElements?.()[0] ?? this.el.firstElementChild) as HTMLElement | null;\n    if (next === this.anchor) return;\n    if (this.isOpen || this.popupEl) this.hideInstant();\n    this.unbindAnchor();\n    this.bindAnchor();\n  };\n\n  private clearTimers() {\n    if (this.delayTimer) { clearTimeout(this.delayTimer); this.delayTimer = null; }\n    if (this.closeTimer) { clearTimeout(this.closeTimer); this.closeTimer = null; }\n  }\n\n  private setupOpenListeners() {\n    // Binds scroll/resize + the resize observer; placement itself is scheduled\n    // by schedulePosition() so the label restyle stays interleaved.\n    this.position.observe();\n    document.addEventListener('keydown', this.escapeHandler);\n  }\n\n  private teardownOpenListeners() {\n    this.position.unobserve();\n    document.removeEventListener('keydown', this.escapeHandler);\n  }\n\n  private destroyPopup() {\n    this.teardownOpenListeners();\n    this.unlinkDescribedBy();\n    if (!this.popupEl) return;\n    this.popupEl.remove();\n    this.popupEl = null;\n  }\n\n  /**\n   * Position after `ds-text` upgrades and lays out. Measuring synchronously in\n   * `mountPopup` reads a collapsed/fallback width and places left/right tips wrong.\n   */\n  private schedulePosition() {\n    if (!this.popupEl) return;\n\n    const reapplyLabelStyles = () => {\n      const label = this.popupEl?.querySelector(':scope > .tooltip-inner > ds-text');\n      if (label instanceof HTMLElement) styleTooltipLabel(label);\n    };\n\n    requestAnimationFrame(() => {\n      reapplyLabelStyles();\n      this.position.update();\n      requestAnimationFrame(() => {\n        reapplyLabelStyles();\n        this.position.update();\n      });\n    });\n\n    // The popup remounts on every show, so re-target the observer bound in start().\n    this.position.observeResizeTargets();\n  }\n\n  /** Drop the open tip immediately (warm handoff to another tooltip). */\n  private hideInstant() {\n    this.clearTimers();\n    lastDismissedAt = Date.now();\n    if (activeTooltip === this) activeTooltip = null;\n    this.destroyPopup();\n    this.isOpen = false;\n    this.skipEnterAnimation = false;\n  }\n\n  private show() {\n    // Empty label = wrapper present for DOM stability (e.g. PanelNav expand/collapse)\n    // but no tip should appear.\n    if (!this.label?.trim()) return;\n    this.clearTimers();\n    let instant = Date.now() - lastDismissedAt < this.instantReopenMs;\n    if (activeTooltip && activeTooltip !== this) {\n      activeTooltip.hideInstant();\n      instant = true;\n    }\n    // eslint-disable-next-line @typescript-eslint/no-this-alias -- module singleton tracks the active instance\n    activeTooltip = this;\n    this.skipEnterAnimation = instant;\n    if (instant) {\n      this.mountPopup();\n      return;\n    }\n    this.delayTimer = setTimeout(() => {\n      this.delayTimer = null;\n      if (!this.label?.trim()) return;\n      this.mountPopup();\n    }, this.hoverDelayMs);\n  }\n\n  private hide() {\n    this.clearTimers();\n    if (!this.popupEl && !this.isOpen) return;\n    lastDismissedAt = Date.now();\n    if (!this.popupEl) {\n      this.isOpen = false;\n      return;\n    }\n    this.popupEl.classList.remove('tooltip-popup--instant');\n    this.popupEl.classList.add('tooltip-popup--closing');\n    if (this.fadeOutMs === 0) {\n      if (activeTooltip === this) activeTooltip = null;\n      this.destroyPopup();\n      this.isOpen = false;\n      this.skipEnterAnimation = false;\n      return;\n    }\n    this.closeTimer = setTimeout(() => {\n      this.closeTimer = null;\n      if (activeTooltip === this) activeTooltip = null;\n      this.destroyPopup();\n      this.isOpen = false;\n      this.skipEnterAnimation = false;\n    }, this.fadeOutMs);\n  }\n\n  private mountPopup() {\n    if (!this.popupEl) {\n      const tip = document.createElement('div');\n      tip.id = this.tooltipId;\n      tip.setAttribute('role', 'tooltip');\n      // `sc-ds-tooltip` is required for Stencil scoped CSS to match outside the host.\n      tip.className = 'tooltip-popup ds-forced-colors-scope sc-ds-tooltip';\n      Object.assign(tip.style, {\n        position: 'fixed',\n        left: '0',\n        top: '0',\n        zIndex: 'var(--dimension-z-index-tooltip)',\n        pointerEvents: 'none',\n      });\n      document.body.appendChild(tip);\n      this.popupEl = tip;\n    }\n\n    this.setupOpenListeners();\n    this.linkDescribedBy();\n    this.popupEl.classList.toggle('tooltip-popup--instant', this.skipEnterAnimation);\n    this.popupEl.classList.remove('tooltip-popup--closing');\n    this.renderPopupContent();\n    this.schedulePosition();\n    this.isOpen = true;\n  }\n\n  private renderPopupContent() {\n    if (!this.popupEl) return;\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const density =\n      this.size === 'md' ? 'ds-control--md' : this.size === 'sm' ? 'ds-control--sm' : 'ds-control--xs';\n    // Every layout node needs `sc-ds-tooltip` so scoped selectors (`.foo.sc-ds-tooltip`) match.\n    const sc = 'sc-ds-tooltip';\n\n    const inner = document.createElement('div');\n    inner.className = `tooltip-inner ${density} ${sc}`;\n\n    const appendShortcut = (position: 'start' | 'end') => {\n      if (!this.shortcutKey || this.shortcutKeyPosition !== position) return;\n      const group = document.createElement('span');\n      group.className = `key-hint-group ${sc}`;\n      group.setAttribute('aria-hidden', 'true');\n\n      for (const label of shortcutKeyLabels(this.shortcutKey)) {\n        const hint = document.createElement('span');\n        const wide = Array.from(label).length > 1 ? ' key-hint--wide' : '';\n        hint.className = `key-hint${wide} ${sc}`;\n        const text = document.createElement('span');\n        text.className = `key-hint__label ${sc}`;\n        text.textContent = label;\n        hint.appendChild(text);\n        group.appendChild(hint);\n      }\n      inner.appendChild(group);\n    };\n\n    appendShortcut('start');\n\n    // ds-text is the layout box (metric-box + 2px control label-inset).\n    // Inline styles required — see styleTooltipLabel.\n    const label = createDsText({ variant: textVariant, wrap: 'nowrap', text: this.label });\n    styleTooltipLabel(label);\n    inner.appendChild(label);\n\n    appendShortcut('end');\n\n    this.popupEl.replaceChildren(inner);\n  }\n\n  render() {\n    return (\n      <Host style={{ display: 'contents' }}>\n        <slot onSlotchange={this.handleSlotChange} />\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Prop, Element, Method, Watch, h, Host } from '@stencil/core';\nimport {\n  CONTROL_TEXT_VARIANT,\n  resolveCssLengthPx,\n  resolveCssTimeMs,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n} from '../../utils';\nimport type { TextVariant } from '../Text/text-types';\nimport { shortcutKeyLabels } from '../../utils/shortcut-key';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\n// Side-effect: register `ds-text` — the portal builds it via createElement, not JSX.\nimport '../Text/Text';\n\nexport type TooltipSide = 'top' | 'right' | 'bottom' | 'left';\nexport type TooltipAlign = 'start' | 'center' | 'end';\nexport type TooltipSize = 'md' | 'sm' | 'xs';\n\nconst FALLBACK_HEIGHT: Record<TooltipSize, string> = {\n  md: TOKEN_DEFAULTS.size400,\n  sm: TOKEN_DEFAULTS.size300,\n  xs: TOKEN_DEFAULTS.size200,\n};\n\nlet lastDismissedAt = 0;\nlet tooltipIdCounter = 0;\n/** Currently open tooltip — force-cleared on warm handoff so tips don't cross-fade. */\nlet activeTooltip: Tooltip | null = null;\n\ntype DsTextEl = HTMLElement & {\n  as: string;\n  variant: TextVariant;\n  emphasis: boolean;\n  color: string;\n  wrap: string;\n};\n\nfunction createDsText(opts: {\n  variant: TextVariant;\n  emphasis?: boolean;\n  color?: string;\n  wrap?: 'wrap' | 'nowrap' | 'balance' | 'pretty';\n  text: string;\n}): DsTextEl {\n  const el = document.createElement('ds-text') as DsTextEl;\n  el.as = 'span';\n  el.variant = opts.variant;\n  el.emphasis = opts.emphasis ?? false;\n  el.color = opts.color ?? 'inherit';\n  if (opts.wrap) el.wrap = opts.wrap;\n  el.textContent = opts.text;\n  return el;\n}\n\n/**\n * Control-density label styles for portaled ds-text.\n * Scoped CSS requires `sc-ds-tooltip` on the host, but Text's `<Host class>`\n * overwrites imperative className — so these must be inline to stick.\n */\nfunction styleTooltipLabel(el: HTMLElement, wrapLabel = false) {\n  el.style.flexShrink = wrapLabel ? '1' : '0';\n  el.style.minWidth = wrapLabel ? '0' : 'max-content';\n  el.style.maxWidth = wrapLabel ? '100%' : 'none';\n  el.style.whiteSpace = wrapLabel ? 'normal' : '';\n  el.style.padding = '0 var(--ds-control-label-inset, var(--dimension-space-025))';\n  el.style.color = 'var(--color-foreground-primary)';\n}\n\n/**\n * Imperative body portal for the popup.\n * Stencil must not own the portaled node — moving a VDOM child to `document.body`\n * causes recreate → re-portal → @State loops that freeze the page.\n */\n@Component({\n  tag: 'ds-tooltip',\n  styleUrl: 'Tooltip.css',\n  scoped: true,\n})\nexport class Tooltip {\n  @Element() el!: HTMLElement;\n\n  /**\n   * Tooltip text. Empty/whitespace skips show — useful when the wrapper must stay\n   * mounted for layout/animation stability (e.g. PanelNav expand/collapse).\n   */\n  @Prop() label!: string;\n\n  /** Control density (height, padding, type). */\n  @Prop() size: TooltipSize = 'md';\n\n  @Prop() side: TooltipSide = 'top';\n  @Prop() align: TooltipAlign = 'center';\n  /** Gap between anchor and tooltip — number (px) or TokoMo length. */\n  @Prop() sideOffset: number | string = TOKEN_CSS_LENGTHS.space050;\n  /** Cross-axis offset — number (px) or TokoMo length. */\n  @Prop() alignOffset: number | string = 0;\n  /**\n   * Hover show delay before the tooltip appears.\n   * Default: `--effect-animation-delay-medium-3` (1000ms). Accepts a number (ms)\n   * or a TokoMo time token / `var(--effect-animation-delay-*)`. Applies to the\n   * initial hover/focus show only — after a recent dismiss, reopen is instant.\n   * Prefer the default; override only for denser chrome or rare/destructive actions.\n   */\n  @Prop() delay: number | string = TOKEN_DEFAULTS.animationDelayMedium3;\n  @Prop() shortcutKey: string | undefined;\n  @Prop() shortcutKeyPosition: 'start' | 'end' = 'end';\n  /**\n   * Link the trigger with aria-describedby while the popup is open. Disable when\n   * the label is already in the DOM, such as a truncated table cell.\n   */\n  @Prop() describedBy = true;\n  /** Allow the label to wrap at a panel-xs max width instead of a single line. */\n  @Prop() wrapLabel = false;\n\n  private tooltipId = `ds-tooltip-${++tooltipIdCounter}`;\n  private delayTimer: ReturnType<typeof setTimeout> | null = null;\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private anchor: HTMLElement | null = null;\n  private popupEl: HTMLElement | null = null;\n  private anchorObserver: MutationObserver | null = null;\n  private didLoad = false;\n  private readonly position = new AnchoredPositionController({\n    getAnchor: () => this.anchor,\n    getPopup: () => this.popupEl,\n    measure: (anchor, tip) => ({\n      anchorRect: anchor.getBoundingClientRect(),\n      // Fall back to token metrics until `ds-text` upgrades and reports a width.\n      popupWidth: tip.offsetWidth || this.tooltipFallbackWidthPx,\n      popupHeight: tip.offsetHeight || this.tooltipFallbackHeightPx,\n      side: this.side,\n      align: this.align,\n      sideOffsetPx: this.sideOffsetPx,\n      alignOffsetPx: this.alignOffsetPx,\n      viewportPadPx: this.viewportPadPx,\n      viewportWidth: window.innerWidth,\n      viewportHeight: window.innerHeight,\n    }),\n    apply: ({ x, y, resolvedSide }) => {\n      if (!this.popupEl) return;\n      this.popupEl.dataset.side = resolvedSide;\n      this.popupEl.style.transform = `translate(${Math.round(x)}px, ${Math.round(y)}px)`;\n    },\n    liveUpdate: 'frame',\n    observeResize: true,\n  });\n  private skipEnterAnimation = false;\n  private isOpen = false;\n  private programmaticAnchor = false;\n  private lastInteractionWasKeyboard = false;\n  private pointerEnterHandler = (event: PointerEvent) => {\n    if (event.pointerType === 'touch') return;\n    this.show();\n  };\n  private pointerLeaveHandler = (event: PointerEvent) => {\n    if (event.pointerType === 'touch') return;\n    this.hide();\n  };\n  private pointerDownHandler = (event: PointerEvent) => {\n    this.lastInteractionWasKeyboard = false;\n    if (event.pointerType === 'touch' && (this.isOpen || this.popupEl)) this.hideInstant();\n  };\n  private keyDownHandler = () => {\n    this.lastInteractionWasKeyboard = true;\n  };\n  /** focusin/focusout so nested focus targets (e.g. ds-button-* inner button) still open the tip. */\n  private focusHandler = () => {\n    if (this.lastInteractionWasKeyboard || this.anchor?.matches(':focus-visible')) this.show();\n  };\n  private blurHandler: (e: FocusEvent) => void = (e) => {\n    const next = e.relatedTarget as Node | null;\n    if (next && this.anchor?.contains(next)) return;\n    this.hide();\n  };\n  private escapeHandler = (event: KeyboardEvent) => {\n    if (event.key !== 'Escape' || !this.isOpen) return;\n    event.preventDefault();\n    this.hide();\n  };\n\n  connectedCallback() {\n    if (!this.didLoad) return;\n    this.connectAnchor();\n  }\n\n  componentDidLoad() {\n    this.didLoad = true;\n    this.connectAnchor();\n  }\n\n  private connectAnchor() {\n    this.bindAnchor();\n    if (this.anchorObserver) return;\n    this.anchorObserver = new MutationObserver(() => this.handleSlotChange());\n    this.anchorObserver.observe(this.el, { childList: true });\n  }\n\n  disconnectedCallback() {\n    if (activeTooltip === this) activeTooltip = null;\n    this.anchorObserver?.disconnect();\n    this.anchorObserver = null;\n    this.unbindAnchor();\n    this.clearTimers();\n    this.destroyPopup();\n  }\n\n  @Watch('label')\n  @Watch('size')\n  @Watch('side')\n  @Watch('align')\n  @Watch('sideOffset')\n  @Watch('alignOffset')\n  @Watch('shortcutKey')\n  @Watch('shortcutKeyPosition')\n  @Watch('wrapLabel')\n  onContentOrPositionChange() {\n    if (!this.label?.trim()) {\n      if (this.isOpen || this.popupEl) this.hideInstant();\n      return;\n    }\n    if (!this.popupEl || !this.isOpen) return;\n    this.renderPopupContent();\n    this.schedulePosition();\n  }\n\n  private get viewportPadPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n  }\n\n  private get sideOffsetPx(): number {\n    return resolveCssLengthPx(this.sideOffset, TOKEN_DEFAULTS.space050);\n  }\n\n  private get alignOffsetPx(): number {\n    return resolveCssLengthPx(this.alignOffset, 0);\n  }\n\n  private get hoverDelayMs(): number {\n    return resolveCssTimeMs(this.delay, TOKEN_DEFAULTS.animationDelayMedium3);\n  }\n\n  private get instantReopenMs(): number {\n    return resolveCssTimeMs(\n      TOKEN_DEFAULTS.animationDurationMedium1,\n      TOKEN_DEFAULTS.animationDurationMedium1,\n    );\n  }\n\n  private get fadeOutMs(): number {\n    return resolveMotionTimeMs(TOKEN_DEFAULTS.motionShort3, TOKEN_DEFAULTS.animationDurationShort3);\n  }\n\n  private get tooltipFallbackWidthPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.tooltipFallbackWidth, TOKEN_DEFAULTS.tooltipFallbackWidth);\n  }\n\n  private get tooltipFallbackHeightPx(): number {\n    const token = FALLBACK_HEIGHT[this.size];\n    return resolveCssLengthPx(token, token);\n  }\n\n  /**\n   * Present against an external anchor the host already measured.\n   * Does not bind hover or focus on that anchor — the owner drives show/hide.\n   */\n  @Method()\n  async presentFrom(anchor: HTMLElement, label?: string) {\n    if (label != null) this.label = label;\n    if (!this.label?.trim()) {\n      this.hide();\n      return;\n    }\n    const sameAnchor = this.anchor === anchor;\n    if (!sameAnchor) {\n      this.unbindAnchor();\n      this.anchor = anchor;\n      this.programmaticAnchor = true;\n      if (this.popupEl && this.describedBy) this.linkDescribedBy();\n    }\n    if (this.popupEl) {\n      this.renderPopupContent();\n      this.schedulePosition();\n      return;\n    }\n    if (this.delayTimer && sameAnchor) return;\n    this.show();\n  }\n\n  /** Dismiss a popup opened through presentFrom or the slotted trigger. */\n  @Method()\n  async dismiss() {\n    this.hide();\n  }\n\n  private bindAnchor() {\n    if (this.programmaticAnchor) return;\n    const slot = this.el.querySelector('slot') as HTMLSlotElement | null;\n    const slotted = slot?.assignedElements?.() ?? [];\n    const child = (slotted[0] ?? this.el.firstElementChild) as HTMLElement | null;\n    if (!child || child.tagName === 'SLOT' || child === this.anchor) return;\n    this.anchor = child;\n    child.addEventListener('pointerenter', this.pointerEnterHandler);\n    child.addEventListener('pointerleave', this.pointerLeaveHandler);\n    child.addEventListener('pointerdown', this.pointerDownHandler);\n    child.addEventListener('keydown', this.keyDownHandler);\n    child.addEventListener('focusin', this.focusHandler);\n    child.addEventListener('focusout', this.blurHandler);\n  }\n\n  private unbindAnchor() {\n    if (!this.anchor) return;\n    this.unlinkDescribedBy();\n    if (!this.programmaticAnchor) {\n      this.anchor.removeEventListener('pointerenter', this.pointerEnterHandler);\n      this.anchor.removeEventListener('pointerleave', this.pointerLeaveHandler);\n      this.anchor.removeEventListener('pointerdown', this.pointerDownHandler);\n      this.anchor.removeEventListener('keydown', this.keyDownHandler);\n      this.anchor.removeEventListener('focusin', this.focusHandler);\n      this.anchor.removeEventListener('focusout', this.blurHandler);\n    }\n    this.anchor = null;\n    this.programmaticAnchor = false;\n  }\n\n  private linkDescribedBy() {\n    if (!this.describedBy || !this.anchor || !this.popupEl) return;\n    const ids = new Set((this.anchor.getAttribute('aria-describedby') ?? '').split(/\\s+/).filter(Boolean));\n    ids.add(this.tooltipId);\n    this.anchor.setAttribute('aria-describedby', Array.from(ids).join(' '));\n  }\n\n  private unlinkDescribedBy() {\n    if (!this.anchor) return;\n    const ids = (this.anchor.getAttribute('aria-describedby') ?? '')\n      .split(/\\s+/)\n      .filter(id => id && id !== this.tooltipId);\n    if (ids.length) this.anchor.setAttribute('aria-describedby', ids.join(' '));\n    else this.anchor.removeAttribute('aria-describedby');\n  }\n\n  private handleSlotChange = () => {\n    if (this.programmaticAnchor) return;\n    const slot = this.el.querySelector('slot') as HTMLSlotElement | null;\n    const next = (slot?.assignedElements?.()[0] ?? this.el.firstElementChild) as HTMLElement | null;\n    if (next === this.anchor || next?.tagName === 'SLOT') return;\n    if (this.isOpen || this.popupEl) this.hideInstant();\n    this.unbindAnchor();\n    this.bindAnchor();\n  };\n\n  private clearTimers() {\n    if (this.delayTimer) { clearTimeout(this.delayTimer); this.delayTimer = null; }\n    if (this.closeTimer) { clearTimeout(this.closeTimer); this.closeTimer = null; }\n  }\n\n  private setupOpenListeners() {\n    // Binds scroll/resize + the resize observer; placement itself is scheduled\n    // by schedulePosition() so the label restyle stays interleaved.\n    this.position.observe();\n    document.addEventListener('keydown', this.escapeHandler);\n  }\n\n  private teardownOpenListeners() {\n    this.position.unobserve();\n    document.removeEventListener('keydown', this.escapeHandler);\n  }\n\n  private destroyPopup() {\n    this.teardownOpenListeners();\n    this.unlinkDescribedBy();\n    if (!this.popupEl) return;\n    this.popupEl.remove();\n    this.popupEl = null;\n  }\n\n  /**\n   * Position after `ds-text` upgrades and lays out. Measuring synchronously in\n   * `mountPopup` reads a collapsed/fallback width and places left/right tips wrong.\n   */\n  private schedulePosition() {\n    if (!this.popupEl) return;\n\n    const reapplyLabelStyles = () => {\n      const label = this.popupEl?.querySelector(':scope > .tooltip-inner > ds-text');\n      if (label instanceof HTMLElement) styleTooltipLabel(label, this.wrapLabel);\n    };\n\n    requestAnimationFrame(() => {\n      reapplyLabelStyles();\n      this.position.update();\n      requestAnimationFrame(() => {\n        reapplyLabelStyles();\n        this.position.update();\n      });\n    });\n\n    // The popup remounts on every show, so re-target the observer bound in start().\n    this.position.observeResizeTargets();\n  }\n\n  /** Drop the open tip immediately (warm handoff to another tooltip). */\n  private hideInstant() {\n    this.clearTimers();\n    lastDismissedAt = Date.now();\n    if (activeTooltip === this) activeTooltip = null;\n    this.destroyPopup();\n    this.isOpen = false;\n    this.skipEnterAnimation = false;\n  }\n\n  private show() {\n    // Empty label = wrapper present for DOM stability (e.g. PanelNav expand/collapse)\n    // but no tip should appear.\n    if (!this.label?.trim()) return;\n    this.clearTimers();\n    let instant = Date.now() - lastDismissedAt < this.instantReopenMs;\n    if (activeTooltip && activeTooltip !== this) {\n      activeTooltip.hideInstant();\n      instant = true;\n    }\n    // eslint-disable-next-line @typescript-eslint/no-this-alias -- module singleton tracks the active instance\n    activeTooltip = this;\n    this.skipEnterAnimation = instant;\n    if (instant) {\n      this.mountPopup();\n      return;\n    }\n    this.delayTimer = setTimeout(() => {\n      this.delayTimer = null;\n      if (!this.label?.trim()) return;\n      this.mountPopup();\n    }, this.hoverDelayMs);\n  }\n\n  private hide() {\n    this.clearTimers();\n    if (!this.popupEl && !this.isOpen) return;\n    lastDismissedAt = Date.now();\n    if (!this.popupEl) {\n      this.isOpen = false;\n      return;\n    }\n    this.popupEl.classList.remove('tooltip-popup--instant');\n    this.popupEl.classList.add('tooltip-popup--closing');\n    if (this.fadeOutMs === 0) {\n      if (activeTooltip === this) activeTooltip = null;\n      this.destroyPopup();\n      this.isOpen = false;\n      this.skipEnterAnimation = false;\n      return;\n    }\n    this.closeTimer = setTimeout(() => {\n      this.closeTimer = null;\n      if (activeTooltip === this) activeTooltip = null;\n      this.destroyPopup();\n      this.isOpen = false;\n      this.skipEnterAnimation = false;\n    }, this.fadeOutMs);\n  }\n\n  private mountPopup() {\n    if (!this.popupEl) {\n      const tip = document.createElement('div');\n      tip.id = this.tooltipId;\n      tip.setAttribute('role', 'tooltip');\n      // `sc-ds-tooltip` is required for Stencil scoped CSS to match outside the host.\n      tip.className = 'tooltip-popup ds-forced-colors-scope sc-ds-tooltip';\n      Object.assign(tip.style, {\n        position: 'fixed',\n        left: '0',\n        top: '0',\n        zIndex: 'var(--dimension-z-index-tooltip)',\n        pointerEvents: 'none',\n      });\n      document.body.appendChild(tip);\n      this.popupEl = tip;\n    }\n\n    this.setupOpenListeners();\n    this.linkDescribedBy();\n      this.popupEl.classList.toggle('tooltip-popup--instant', this.skipEnterAnimation);\n    this.popupEl.classList.toggle('tooltip-popup--wrap', this.wrapLabel);\n    this.popupEl.classList.remove('tooltip-popup--closing');\n    this.renderPopupContent();\n    this.schedulePosition();\n    this.isOpen = true;\n  }\n\n  private renderPopupContent() {\n    if (!this.popupEl) return;\n    this.popupEl.classList.toggle('tooltip-popup--wrap', this.wrapLabel);\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const density =\n      this.size === 'md' ? 'ds-control--md' : this.size === 'sm' ? 'ds-control--sm' : 'ds-control--xs';\n    // Every layout node needs `sc-ds-tooltip` so scoped selectors (`.foo.sc-ds-tooltip`) match.\n    const sc = 'sc-ds-tooltip';\n\n    const inner = document.createElement('div');\n    inner.className = `tooltip-inner ${density} ${sc}`;\n\n    const appendShortcut = (position: 'start' | 'end') => {\n      if (!this.shortcutKey || this.shortcutKeyPosition !== position) return;\n      const group = document.createElement('span');\n      group.className = `key-hint-group ${sc}`;\n      group.setAttribute('aria-hidden', 'true');\n\n      for (const label of shortcutKeyLabels(this.shortcutKey)) {\n        const hint = document.createElement('span');\n        const wide = Array.from(label).length > 1 ? ' key-hint--wide' : '';\n        hint.className = `key-hint${wide} ${sc}`;\n        const text = document.createElement('span');\n        text.className = `key-hint__label ${sc}`;\n        text.textContent = label;\n        hint.appendChild(text);\n        group.appendChild(hint);\n      }\n      inner.appendChild(group);\n    };\n\n    appendShortcut('start');\n\n    // ds-text is the layout box (metric-box + 2px control label-inset).\n    // Inline styles required — see styleTooltipLabel.\n    const label = createDsText({\n      variant: textVariant,\n      wrap: this.wrapLabel ? 'wrap' : 'nowrap',\n      text: this.label,\n    });\n    styleTooltipLabel(label, this.wrapLabel);\n    inner.appendChild(label);\n\n    appendShortcut('end');\n\n    this.popupEl.replaceChildren(inner);\n  }\n\n  render() {\n    return (\n      <Host style={{ display: 'contents' }}>\n        <slot onSlotchange={this.handleSlotChange} />\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/styles/table.css

@@ -25,6 +25,31 @@
     + var(--dimension-space-025)
     + var(--dimension-size-250)
   );
+  /*
+   * Wrapping primary on a 1-track cell occupies later tracks instead of a
+   * private leading scale. Keep body-medium size; add the 2px stack gap to
+   * line-height and leave the leftover first-track inset as padding-block
+   * so 1 / 2 / 3 wrapped lines measure 40 / 62 / 84 like named tracks.
+   */
+  --_table-wrap-primary-line-height: calc(
+    var(--typography-lineheight-md) + var(--dimension-space-025)
+  );
+  --_table-wrap-primary-padding-block: calc(
+    (
+      var(--_table-cell-track-min-block-size)
+      - var(--typography-lineheight-md)
+      - var(--dimension-space-025)
+    ) / 2
+  );
+  /*
+   * Wrapping secondary on a 2-track cell occupies later tracks. Zero the copy
+   * gap and use later-track + gap as line-height so 1 / 2 / 3 secondary lines
+   * land on 62 / 84 / 106 with primary remaining the first 24px track.
+   */
+  --_table-wrap-secondary-line-height: calc(
+    var(--dimension-size-250) + var(--dimension-space-025)
+  );
+  --_table-wrap-secondary-padding-block: 0;
   --_table-surface: var(--ds-table-surface, var(--color-background-primary));
   --_table-header-surface: var(--ds-table-header-surface, var(--color-background-primary));
   --_table-group-surface: var(--ds-table-group-surface, var(--color-background-faint-neutral));
@@ -795,7 +820,11 @@
  * checkbox) sits in a 24px track (2px block inset). Text tracks keep that
  * 2px plus the 2px label inset, so padding-inline is 4px and copy lines up
  * with column-header labels. Later body-small tracks stay 20px, stacked with
- * a 2px gap. Header and group rows keep their own recipes.
+ * a 2px gap. Wrapping 1-track primary folds that gap into line-height so
+ * extra lines land on the same 62px and 84px rows as 2- and 3-track cells.
+ * Wrapping secondary keeps primary on track 1 and consumes later tracks the
+ * same way, including a 106px fourth track when secondary wraps to three lines.
+ * Header and group rows keep their own recipes.
  */
 :where(.ds-table__cell-primary),
 :where(.ds-table__cell--empty .ds-table__cell-track) {
@@ -970,6 +999,35 @@
   overflow-wrap: anywhere;
 }
 
+/*
+ * Wrapping tracks must be block boxes so ds-text line-clamp (a -webkit-box
+ * inner) can grow onto later tracks. Flex + line-clamp otherwise collapses
+ * to the 40px single-track row.
+ */
+:where(.ds-table__cell--text-wrap .ds-table__cell-track--text),
+:where(.ds-table__cell--icon-text-wrap .ds-table__cell-track--text) {
+  display: block;
+}
+
+:where(.ds-table__cell--text-wrap.ds-table__cell--text-single .ds-table__cell-primary),
+:where(.ds-table__cell--text-wrap.ds-table__cell--text-multi .ds-table__cell-primary),
+:where(.ds-table__cell--icon-text-wrap.ds-table__cell--icon-text-single .ds-table__cell-primary),
+:where(.ds-table__cell--icon-text-wrap.ds-table__cell--icon-text-multi .ds-table__cell-primary) {
+  line-height: var(--_table-wrap-primary-line-height);
+  padding-block: var(--_table-wrap-primary-padding-block);
+}
+
+:where(.ds-table__cell--text-wrap.ds-table__cell--text-multi .ds-table__cell-copy),
+:where(.ds-table__cell--icon-text-wrap.ds-table__cell--icon-text-multi .ds-table__cell-copy) {
+  gap: 0;
+}
+
+:where(.ds-table__cell--text-wrap.ds-table__cell--text-multi .ds-table__cell-secondary),
+:where(.ds-table__cell--icon-text-wrap.ds-table__cell--icon-text-multi .ds-table__cell-secondary) {
+  line-height: var(--_table-wrap-secondary-line-height);
+  padding-block: var(--_table-wrap-secondary-padding-block);
+}
+
 :where(.ds-table__cell--align-center),
 :where(.ds-table__cell--align-center .ds-table__cell-content),
 :where(.ds-table__cell--align-center .ds-table__cell-track),

package/dist/types/components/Menu/Menu.d.ts

@@ -46,6 +46,7 @@ export declare class Menu {
     dsSwatchSelect: EventEmitter<string>;
     private clickOutsideHandler;
     private closeTimer;
+    private positionReadyCallback;
     /**
      * Anchored placement. The choice-cell measurement stays here on purpose: the
      * inner-cell align offset and the `--dimension-menu-width-xs` floor are Menu

package/dist/types/components/Table/Table.d.ts

@@ -99,6 +99,13 @@ export declare class Table {
     private viewportFitSettled;
     private headerPresent;
     private fitPageSize;
+    private actionMenu;
+    private actionMenuInitialFocusVisible;
+    private truncateTooltipLabel;
+    private readonly actionMenuElementId;
+    private truncateTooltipEl?;
+    private truncateAnchor;
+    private truncateTooltipBound;
     private rootEl;
     private viewportEl;
     private frameEl;
@@ -166,6 +173,21 @@ export declare class Table {
     private emitGroupSelection;
     private rowEventOwnsActivation;
     private emitRowActivation;
+    private syncActionMenu;
+    private closeActionMenu;
+    private handleActionMenuSelect;
+    private toggleActionMenu;
+    private renderOverflowActionMenu;
+    private connectTruncateTooltip;
+    private disconnectTruncateTooltip;
+    private onTruncatePointerOver;
+    private onTruncatePointerOut;
+    private onTruncateFocusIn;
+    private onTruncateFocusOut;
+    private presentOrDismissTruncateTrack;
+    private dismissTruncateTooltip;
+    private renderTruncateTooltip;
+    private truncateAttr;
     private handleRowKeydown;
     private renderSelectionControl;
     private renderStickyEdge;

package/dist/types/components/Table/index.d.ts

@@ -1,2 +1,2 @@
-export type { TableCaptionVisibility, TableCellAlign, TableCellAction, TableCellActionDetail, TableCellBlank, TableCellEmpty, TableCellLinkTarget, TableCellIcon, TableCellIconText, TableCellImage, TableCellImageTracks, TableCellPrimaryText, TableCellSkeleton, TableCellText, TableCellTextRun, TableCellTextTrack, TableCellTag, TableCellTagVariant, TableCellValue, TableSkeletonWidth, TableColumn, TableColumnSticky, TableColumnWidth, TableDataMode, TableGroup, TableGroupCollapseChangeDetail, TableGroupLoadMoreDetail, TableGroupIntent, TableHeaderSegment, TableGroupingState, TableLoadMoreDetail, TableLoadMoreMode, TableLoadMoreReason, TablePaginationState, TableRow, TableRowActivateDetail, TableSelectionChangeDetail, TableSelectionMode, TableSortChangeDetail, TableSortDirection, TableSortState, } from './table-types';
+export type { TableCaptionVisibility, TableCellAlign, TableCellAction, TableCellActionDetail, TableCellActionDivider, TableCellActionMenuEntry, TableCellActionMenuItem, TableCellBlank, TableCellEmpty, TableCellLinkTarget, TableCellIcon, TableCellIconText, TableCellImage, TableCellImageTracks, TableCellPrimaryText, TableCellSkeleton, TableCellText, TableCellTextRun, TableCellTextTrack, TableCellTag, TableCellTagVariant, TableCellValue, TableSkeletonWidth, TableColumn, TableColumnSticky, TableColumnWidth, TableDataMode, TableGroup, TableGroupCollapseChangeDetail, TableGroupLoadMoreDetail, TableGroupIntent, TableHeaderSegment, TableGroupingState, TableLoadMoreDetail, TableLoadMoreMode, TableLoadMoreReason, TablePaginationState, TableRow, TableRowActivateDetail, TableSelectionChangeDetail, TableSelectionMode, TableSortChangeDetail, TableSortDirection, TableSortState, } from './table-types';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/components/Table/table-action-menu.d.ts

@@ -0,0 +1,15 @@
+import type { MenuItemsSection } from '../Menu/menu-types';
+import type { TableCellAction, TableCellActionMenuEntry } from './table-types';
+export declare function nextTableActionMenuElementId(): string;
+export declare function isTableCellActionMenu(value: TableCellAction): value is TableCellAction & {
+    items: TableCellActionMenuEntry[];
+    ariaLabel: string;
+};
+export declare function isRenderableTableActionMenu(value: TableCellAction): value is TableCellAction & {
+    items: TableCellActionMenuEntry[];
+    ariaLabel: string;
+};
+/** Split divider entries into Menu sections. Empty runs (leading/repeated dividers) are dropped. */
+export declare function tableActionMenuSections(items: TableCellActionMenuEntry[]): MenuItemsSection[];
+export declare function tableActionTriggerId(menuId: string, rowId: string, columnId: string): string;
+//# sourceMappingURL=table-action-menu.d.ts.map

package/dist/types/components/Table/table-cell-model.d.ts

@@ -1,4 +1,4 @@
-import type { TableCellAction, TableCellBlank, TableCellEmpty, TableCellIcon, TableCellImage, TableCellImageTracks, TableCellTag, TableCellTagVariant, TableCellTextRun, TableCellTextTrack, TableCellValue, TableCellLinkTarget, TableColumn } from './table-types';
+import type { TableCellAction, TableCellBlank, TableCellEmpty, TableCellIcon, TableCellImage, TableCellImageTracks, TableCellTag, TableCellTagVariant, TableCellTextRun, TableCellTextTrack, TableCellValue, TableCellLinkTarget, TableCellLineClamp, TableCellMaxLines, TableColumn } from './table-types';
 import type { IconColor } from '../Icon/Icon';
 import type { TextColor } from '../Text/text-types';
 /** Maximum independently colored runs on one secondary or tertiary track. */
@@ -35,6 +35,7 @@ export type TableCellPresentation = {
     value: ResolvedTableCellText;
     variant: 'single' | 'multi' | 'triple';
     wraps: boolean;
+    lineClamp: TableCellLineClamp;
 } | {
     kind: 'image';
     cellType: 'image';
@@ -57,6 +58,7 @@ export type TableCellPresentation = {
     singleLine: boolean;
     variant: 'single' | 'multi' | 'triple' | 'primary-pair';
     wraps: boolean;
+    lineClamp: TableCellLineClamp;
 };
 /** Resolve an image cell's track stack; unknown values fall back to one track. */
 export declare function resolveTableCellImageTracks(tracks: TableCellImage['tracks']): TableCellImageTracks;
@@ -64,6 +66,19 @@ export declare function resolveTableCellImageTracks(tracks: TableCellImage['trac
 export declare function tableCellImageVariant(tracks: TableCellImageTracks): 'single' | 'multi' | 'triple';
 /** Collapse a consumer track into at most three non-empty runs. */
 export declare function normalizeTableCellTextTrack(track: TableCellTextTrack | number | undefined): TableCellTextRun[] | undefined;
+/** Map wrap / maxLines onto wrap-to-track geometry and a line clamp. */
+export declare function resolveTableCellTextOverflow(source: {
+    wrap?: boolean;
+    maxLines?: TableCellMaxLines;
+}, column: TableColumn): {
+    wraps: boolean;
+    lineClamp: TableCellLineClamp;
+};
+/** ds-text overflow props for a resolved clamp. */
+export declare function tableCellTextOverflowProps(lineClamp: TableCellLineClamp): {
+    lineTruncation: TableCellLineClamp;
+    wrap: 'wrap' | 'nowrap';
+};
 /** Resolve a cell's semantic and visual recipe once for both markup and classes. */
 export declare function resolveTableCellPresentation(value: TableCellValue, column: TableColumn): TableCellPresentation;
 //# sourceMappingURL=table-cell-model.d.ts.map

package/dist/types/components/Table/table-truncate.d.ts

@@ -0,0 +1,6 @@
+/** Marks text tracks that may present the table-owned truncation tooltip. */
+export declare const TABLE_TRUNCATE_ATTR = "data-table-truncate";
+/** Resolve the overflowing text track under a pointer or focus target. */
+export declare function resolveTableTruncateTrack(target: EventTarget | null): HTMLElement | null;
+export declare function tableTruncateLabel(track: HTMLElement): string;
+//# sourceMappingURL=table-truncate.d.ts.map

package/dist/types/components/Table/table-types.d.ts

@@ -12,6 +12,10 @@ export type TableLoadMoreMode = 'auto' | 'manual';
 export type TableDataMode = 'infinite' | 'pagination';
 export type TableLoadMoreReason = 'auto' | 'manual' | 'retry';
 export type TableColumnWidth = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Visible line budget before a text track ellipsizes. */
+export type TableCellMaxLines = 1 | 2 | 3;
+/** Resolved clamp, including unlimited wrapping. */
+export type TableCellLineClamp = TableCellMaxLines | 'none';
 /** Semantic color for a group section header (faint surface + bold title). */
 export type TableGroupIntent = 'brand' | 'neutral' | 'negative' | 'warning' | 'caution' | 'positive';
 /** Independently sortable label within a compound column header. */
@@ -56,6 +60,8 @@ export interface TableCellText {
     target?: TableCellLinkTarget;
     /** Allow this cell to wrap even when its column truncates by default. */
     wrap?: boolean;
+    /** Clamp wrapping text after 1, 2, or 3 lines. Overrides column wrap. */
+    maxLines?: TableCellMaxLines;
     fontFeature?: 'normal' | 'tabular-nums';
 }
 /** Two-line text content where both tracks use primary body text. */
@@ -69,6 +75,8 @@ export interface TableCellPrimaryText {
     target?: TableCellLinkTarget;
     /** Allow this cell to wrap even when its column truncates by default. */
     wrap?: boolean;
+    /** Clamp wrapping text after 1, 2, or 3 lines. Overrides column wrap. */
+    maxLines?: TableCellMaxLines;
     fontFeature?: 'normal' | 'tabular-nums';
 }
 /** Applicable data point whose value is currently unavailable. */
@@ -109,6 +117,7 @@ export interface TableCellIconText {
     href?: string;
     target?: TableCellLinkTarget;
     wrap?: boolean;
+    maxLines?: TableCellMaxLines;
     fontFeature?: 'normal' | 'tabular-nums';
 }
 /** Body-row track stack an image preview occupies. */
@@ -128,29 +137,55 @@ export interface TableCellImage {
 }
 interface TableCellActionBase {
     kind: 'action';
-    /** Stable application-owned action identity emitted with dsCellAction. */
-    actionId: string;
     /** Add the ButtonUnfilled resting border. Action cells are unbordered by default. */
     hasBorder?: boolean;
     isInactive?: boolean;
     isLoading?: boolean;
 }
+/** One command inside an overflow action menu. */
+export interface TableCellActionMenuItem {
+    /** Stable application-owned action identity emitted with dsCellAction. */
+    actionId: string;
+    label: string;
+    isInactive?: boolean;
+    isDestructive?: boolean;
+}
+/** Visual separator between overflow action-menu commands. */
+export interface TableCellActionDivider {
+    kind: 'divider';
+}
+export type TableCellActionMenuEntry = TableCellActionMenuItem | TableCellActionDivider;
 /** Declarative ButtonUnfilled content rendered by the table's standard action cell. */
 export type TableCellAction = TableCellActionBase & ({
     variant?: 'label';
+    /** Stable application-owned action identity emitted with dsCellAction. */
+    actionId: string;
     label: string;
     icon?: never;
     ariaLabel?: string;
+    items?: never;
 } | {
     variant: 'icon-label';
+    actionId: string;
     label: string;
     icon: string;
     ariaLabel?: string;
+    items?: never;
 } | {
     variant: 'icon';
+    actionId: string;
     label?: never;
     icon: string;
     ariaLabel: string;
+    items?: never;
+} | {
+    variant?: 'icon';
+    /** Overflow commands. The Ellipses trigger opens ds-menu instead of emitting on click. */
+    items: TableCellActionMenuEntry[];
+    ariaLabel: string;
+    icon?: string;
+    actionId?: never;
+    label?: never;
 });
 /** Declarative Tag content rendered by the table's standard cell primitive. */
 export type TableCellTagVariant = 'tag-only' | 'tag-with-text' | 'text-with-tag';
@@ -222,6 +257,8 @@ export interface TableColumn {
     maxSize?: number;
     /** Wrap cell text instead of truncating it to one line. */
     wrap?: boolean;
+    /** Clamp wrapping text after 1, 2, or 3 lines. Omit with wrap for unlimited wrap. */
+    maxLines?: TableCellMaxLines;
     /** Pin one application column to either inline edge during horizontal scrolling. */
     sticky?: TableColumnSticky;
     /**

package/dist/types/components/Tooltip/Tooltip.d.ts

@@ -32,6 +32,13 @@ export declare class Tooltip {
     delay: number | string;
     shortcutKey: string | undefined;
     shortcutKeyPosition: 'start' | 'end';
+    /**
+     * Link the trigger with aria-describedby while the popup is open. Disable when
+     * the label is already in the DOM, such as a truncated table cell.
+     */
+    describedBy: boolean;
+    /** Allow the label to wrap at a panel-xs max width instead of a single line. */
+    wrapLabel: boolean;
     private tooltipId;
     private delayTimer;
     private closeTimer;
@@ -42,6 +49,7 @@ export declare class Tooltip {
     private readonly position;
     private skipEnterAnimation;
     private isOpen;
+    private programmaticAnchor;
     private lastInteractionWasKeyboard;
     private pointerEnterHandler;
     private pointerLeaveHandler;
@@ -64,6 +72,13 @@ export declare class Tooltip {
     private get fadeOutMs();
     private get tooltipFallbackWidthPx();
     private get tooltipFallbackHeightPx();
+    /**
+     * Present against an external anchor the host already measured.
+     * Does not bind hover or focus on that anchor — the owner drives show/hide.
+     */
+    presentFrom(anchor: HTMLElement, label?: string): Promise<void>;
+    /** Dismiss a popup opened through presentFrom or the slotted trigger. */
+    dismiss(): Promise<void>;
     private bindAnchor;
     private unbindAnchor;
     private linkDescribedBy;