@ds-mo/ui 14.5.0 → 14.7.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/react/ds-menu.d.ts

@@ -3,7 +3,7 @@
  * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
  */
 import type { EventName, StencilReactComponent } from './react-runtime.js';
-import { type DsMenuCustomEvent, type MenuItemData } from "@ds-mo/ui";
+import { type DsMenuCustomEvent, type MenuItemData, type MenuReorderDetail } from "@ds-mo/ui";
 import type { Components } from "@ds-mo/ui/dist/components";
 import { DsMenu as DsMenuElement } from "@ds-mo/ui/dist/components/ds-menu.js";
 export type DsMenuEvents = {
@@ -11,5 +11,6 @@ export type DsMenuEvents = {
     onDsAfterClose: EventName<DsMenuCustomEvent<void>>;
     onDsSelect: EventName<DsMenuCustomEvent<MenuItemData>>;
     onDsSwatchSelect: EventName<DsMenuCustomEvent<string>>;
+    onDsReorder: EventName<DsMenuCustomEvent<MenuReorderDetail>>;
 };
 export declare const DsMenu: StencilReactComponent<DsMenuElement, DsMenuEvents, Components.DsMenu>;

package/dist/react/ds-menu.js

@@ -11,7 +11,8 @@ export const DsMenu = /*@__PURE__*/ createComponent({
         onDsClose: 'dsClose',
         onDsAfterClose: 'dsAfterClose',
         onDsSelect: 'dsSelect',
-        onDsSwatchSelect: 'dsSwatchSelect'
+        onDsSwatchSelect: 'dsSwatchSelect',
+        onDsReorder: 'dsReorder'
     },
     defineCustomElement: defineDsMenu
 });

package/dist/react/ds-table.d.ts

@@ -3,7 +3,7 @@
  * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
  */
 import type { EventName, StencilReactComponent } from './react-runtime.js';
-import { type DsTableCustomEvent, type PaginationChangeDetail, type TableCellActionDetail, type TableGroupCollapseChangeDetail, type TableGroupLoadMoreDetail, type TableLoadMoreDetail, type TableRowActivateDetail, type TableSelectionChangeDetail, type TableSortChangeDetail } from "@ds-mo/ui";
+import { type DsTableCustomEvent, type PaginationChangeDetail, type TableCellActionDetail, type TableColumnsConfigChangeDetail, type TableGroupCollapseChangeDetail, type TableGroupLoadMoreDetail, type TableLoadMoreDetail, type TableRowActivateDetail, type TableSelectionChangeDetail, type TableSortChangeDetail } from "@ds-mo/ui";
 import type { Components } from "@ds-mo/ui/dist/components";
 import { DsTable as DsTableElement } from "@ds-mo/ui/dist/components/ds-table.js";
 export type DsTableEvents = {
@@ -15,5 +15,6 @@ export type DsTableEvents = {
     onDsPaginationChange: EventName<DsTableCustomEvent<PaginationChangeDetail>>;
     onDsCellAction: EventName<DsTableCustomEvent<TableCellActionDetail>>;
     onDsRowActivate: EventName<DsTableCustomEvent<TableRowActivateDetail>>;
+    onDsColumnsConfigChange: EventName<DsTableCustomEvent<TableColumnsConfigChangeDetail>>;
 };
 export declare const DsTable: StencilReactComponent<DsTableElement, DsTableEvents, Components.DsTable, 'caption'>;

package/dist/react/ds-table.js

@@ -15,7 +15,8 @@ export const DsTable = /*@__PURE__*/ createComponent({
         onDsGroupLoadMore: 'dsGroupLoadMore',
         onDsPaginationChange: 'dsPaginationChange',
         onDsCellAction: 'dsCellAction',
-        onDsRowActivate: 'dsRowActivate'
+        onDsRowActivate: 'dsRowActivate',
+        onDsColumnsConfigChange: 'dsColumnsConfigChange'
     },
     defineCustomElement: defineDsTable
 });

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));
@@ -260,7 +285,28 @@
   max-inline-size: 100%;
 }
 
-:where(.ds-table__caption-content > slot) {
+:where(.ds-table__caption-content--trailing) {
+  grid-template-columns: minmax(0, 1fr) auto;
+  column-gap: var(--dimension-space-100);
+}
+
+:where(.ds-table__caption-trailing) {
+  display: flex;
+  align-items: center;
+  flex: 0 0 auto;
+  min-inline-size: 0;
+  gap: var(--dimension-space-100);
+}
+
+:where(.ds-table__caption-leading) {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  align-items: center;
+  min-inline-size: 0;
+  max-inline-size: 100%;
+}
+
+:where(.ds-table__caption-leading > slot) {
   display: contents;
 }
 
@@ -795,7 +841,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 +1020,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/ButtonUnfilled/ButtonUnfilled.d.ts

@@ -76,8 +76,10 @@ export declare class ButtonUnfilled {
      *
      * - `label` / `icon-label` — the action *has* a menu; a trailing chevron carries
      *   the affordance.
-     * - `icon` — the button *is* a menu, i.e. the overflow / more-options control.
-     *   No chevron is added, so the glyph must convey it on its own; use `Ellipses`.
+     * - `icon` — the button *is* a menu. No chevron is added, so the glyph must
+     *   convey the menu on its own. Use `Ellipses` for generic more-options;
+     *   use a specific icon when the menu has a named purpose, such as
+     *   `Preferences` for Customize table.
      *
      * Use `haspopup` directly for non-menu popups.
      */

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

@@ -1,7 +1,7 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { type ChoicePopupAnchorAlignment, type ControlSize } from '../../utils';
 import type { MenuAlign, MenuSide } from './menu-position';
-import { type MenuItemData, type MenuSection } from './menu-types';
+import { type MenuItemData, type MenuReorderDetail, type MenuSection } from './menu-types';
 export type MenuSelectionMode = 'none' | 'single';
 export type MenuSize = ControlSize;
 export declare class Menu {
@@ -38,14 +38,22 @@ export declare class Menu {
     private focusedIndex;
     private positionReady;
     private focusRingVisible;
+    private reorderFromFlat;
+    private reorderInsertBefore;
+    private reorderAnnouncement;
     dsClose: EventEmitter<void>;
     /** Emitted after the popup's exit motion is complete and its rendered content is removed. */
     dsAfterClose: EventEmitter<void>;
     dsSelect: EventEmitter<MenuItemData>;
     /** Emitted when a generic `swatch-picker` section option is chosen. */
     dsSwatchSelect: EventEmitter<string>;
+    /** Emitted after a pointer drop or keyboard move; Menu never mutates item order. */
+    dsReorder: EventEmitter<MenuReorderDetail>;
     private clickOutsideHandler;
     private closeTimer;
+    private positionReadyCallback;
+    private suppressItemClick;
+    private reorderPointer;
     /**
      * Anchored placement. The choice-cell measurement stays here on purpose: the
      * inner-cell align offset and the `--dimension-menu-width-xs` floor are Menu
@@ -94,6 +102,16 @@ export declare class Menu {
     private focusItem;
     private handleItemClick;
     private handleSwatchSelect;
+    private handleReorderKey;
+    private emitReorder;
+    private flatIndexFor;
+    private announceReorder;
+    private onReorderPointerDown;
+    private onReorderPointerMove;
+    private onReorderPointerUp;
+    private onReorderPointerCancel;
+    private resolveReorderInsertBefore;
+    private clearReorderPointer;
     render(): any;
 }
 //# sourceMappingURL=Menu.d.ts.map

package/dist/types/components/Menu/menu-reorder.d.ts

@@ -0,0 +1,21 @@
+import { type MenuItemData, type MenuReorderDetail, type MenuSection } from './menu-types';
+export interface MenuReorderRange {
+    start: number;
+    end: number;
+}
+/** Contiguous reorderable run containing `index`, or null when that row cannot move. */
+export declare function menuReorderableRange(items: readonly MenuItemData[], index: number): MenuReorderRange | null;
+/**
+ * Move a reorderable row so it would be inserted before `insertBefore`.
+ * `insertBefore` is clamped to the contiguous reorderable run.
+ */
+export declare function moveReorderableMenuItemBefore(items: readonly MenuItemData[], fromIndex: number, insertBefore: number): MenuItemData[] | null;
+/** Keyboard step: move one slot within the reorderable run. */
+export declare function moveReorderableMenuItemBy(items: readonly MenuItemData[], fromIndex: number, offset: number): MenuItemData[] | null;
+export declare function locateMenuItem(sections: readonly MenuSection[], flatIndex: number): {
+    sectionIndex: number;
+    itemIndex: number;
+    items: MenuItemData[];
+} | null;
+export declare function createMenuReorderDetail(items: MenuItemData[], fromIndex: number, nextItems: MenuItemData[], sectionIndex: number): MenuReorderDetail | null;
+//# sourceMappingURL=menu-reorder.d.ts.map

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

@@ -12,6 +12,8 @@ export interface MenuItemData {
     label: string;
     value?: string;
     subtext?: string;
+    /** Leading decorative icon. Ignored when `reorderable` is true. */
+    icon?: string;
     /** Show a supplemental brand notification dot. */
     dot?: boolean;
     /** Show a non-interactive tag at the trailing edge of the row. */
@@ -22,6 +24,16 @@ export interface MenuItemData {
     /** Render a compact switch indicator; the menu row owns interaction. */
     showSwitch?: boolean;
     switchValue?: boolean;
+    /** Prefix a drag handle and allow pointer and keyboard reorder within the contiguous reorderable run. */
+    reorderable?: boolean;
+}
+/** Next section item order after a pointer or keyboard reorder. */
+export interface MenuReorderDetail {
+    item: MenuItemData;
+    fromIndex: number;
+    toIndex: number;
+    sectionIndex: number;
+    items: MenuItemData[];
 }
 export interface MenuItemsSection {
     header?: string;

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

@@ -1,6 +1,6 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import type { PaginationChangeDetail } from '../Pagination/pagination-types';
-import type { TableCaptionVisibility, TableCellActionDetail, TableColumn, TableDataMode, TableGroup, TableGroupCollapseChangeDetail, TableGroupLoadMoreDetail, TableGroupingState, TableLoadMoreDetail, TableLoadMoreMode, TablePaginationState, TableRow, TableRowActivateDetail, TableSelectionChangeDetail, TableSelectionMode, TableSortChangeDetail, TableSortState } from './table-types';
+import type { TableCaptionVisibility, TableCellActionDetail, TableColumn, TableColumnsConfigChangeDetail, TableDataMode, TableGroup, TableGroupCollapseChangeDetail, TableGroupLoadMoreDetail, TableGroupingState, TableLoadMoreDetail, TableLoadMoreMode, TablePaginationState, TableRow, TableRowActivateDetail, TableSelectionChangeDetail, TableSelectionMode, TableSortChangeDetail, TableSortState } from './table-types';
 export declare class Table {
     el: HTMLElement;
     /** Stable column definitions. Assign through JavaScript. */
@@ -19,6 +19,16 @@ export declare class Table {
     caption: string;
     /** Shows a matching presentational title bar above the native table frame. */
     captionVisibility: TableCaptionVisibility;
+    /**
+     * Opt in to the table-owned column customizer. The `columns` prop remains the
+     * catalog; hidden and ordered columns are controlled separately. The trigger
+     * opens the shared Menu of live show/hide switch rows.
+     */
+    columnCustomizer: boolean;
+    /** Controlled hidden data-column identities. Action ids are ignored. */
+    hiddenColumnIds: string[];
+    /** Controlled data-column identities in display order. Omitted ids append in catalog order. */
+    columnOrder: string[];
     /**
      * Optional result summary footer. When both `displayedCount` and `totalCount`
      * are finite numbers, the table shows “Displaying {displayed} of {total}”.
@@ -91,6 +101,7 @@ export declare class Table {
     dsPaginationChange: EventEmitter<PaginationChangeDetail>;
     dsCellAction: EventEmitter<TableCellActionDetail>;
     dsRowActivate: EventEmitter<TableRowActivateDetail>;
+    dsColumnsConfigChange: EventEmitter<TableColumnsConfigChangeDetail>;
     private overflowStart;
     private overflowEnd;
     private scrollable;
@@ -99,6 +110,16 @@ export declare class Table {
     private viewportFitSettled;
     private headerPresent;
     private fitPageSize;
+    private actionMenu;
+    private actionMenuInitialFocusVisible;
+    private truncateTooltipLabel;
+    private columnCustomizerOpen;
+    private columnCustomizerInitialFocusVisible;
+    private readonly actionMenuElementId;
+    private readonly columnCustomizerElementId;
+    private truncateTooltipEl?;
+    private truncateAnchor;
+    private truncateTooltipBound;
     private rootEl;
     private viewportEl;
     private frameEl;
@@ -142,9 +163,13 @@ export declare class Table {
     handleLoadingMoreChange(loading: boolean): void;
     handleLoadMoreErrorChange(error: string | undefined): void;
     handleHasMoreChange(hasMore: boolean, hadMore: boolean): void;
+    handleColumnCustomizerAvailability(): void;
     private get grouped();
     private get hasIncrementalState();
     private get selectable();
+    private get visibleColumns();
+    private get showsColumnCustomizer();
+    private get showsCaptionTrailing();
     private get documentStickyHeader();
     private get fixedHeight();
     private get boundedComposition();
@@ -166,6 +191,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;
@@ -195,6 +235,15 @@ export declare class Table {
     private get hasResultFooter();
     private renderResultFooter;
     private renderCaptionBar;
+    private renderCaptionTrailing;
+    private renderColumnCustomizerTrigger;
+    private renderColumnCustomizerMenu;
+    private toggleColumnCustomizer;
+    private openColumnCustomizer;
+    private closeColumnCustomizer;
+    private emitColumnsConfigChange;
+    private handleColumnCustomizerReorder;
+    private handleColumnCustomizerSelect;
     render(): any;
 }
 //# sourceMappingURL=Table.d.ts.map

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, TableColumnsConfigChangeDetail, 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