@ds-mo/ui 8.3.1 → 9.1.0

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

@@ -0,0 +1,311 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "tooltip",
+  "title": "Tooltip",
+  "description": "Supplementary, non-interactive visual label for an already named action, shown on mouse or hover-capable pen and keyboard focus.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/tooltip",
+    "source": "src/wc/components/Tooltip/Tooltip.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "general",
+      "status": "stable",
+      "summary": "Supplementary, non-interactive visual label for an already named action, shown on mouse or hover-capable pen and keyboard focus.",
+      "useWhen": [
+        "An icon-only or dense control benefits from a short visual label for sighted mouse, pen, and keyboard users.",
+        "A non-essential keyboard shortcut should appear beside a concise visual label.",
+        "Adjacent chrome actions need delayed first disclosure with instant warm handoff between tooltips."
+      ],
+      "avoidWhen": [
+        "The tooltip would be the trigger's only accessible name or contain information required to complete the task.",
+        "The popup needs links, buttons, rich content, a close action, click-to-open behavior, or touch access.",
+        "The callout follows a chart cursor or data point rather than a slotted control."
+      ],
+      "alternatives": [
+        {
+          "when": "The popup contains a contextual list of actions or options.",
+          "component": "component:ds-menu",
+          "reason": "Menu provides interactive content, keyboard navigation, selection, and close behavior."
+        },
+        {
+          "when": "The content requires focus management, substantial explanation, confirmation, or a form.",
+          "component": "component:ds-modal",
+          "reason": "Modal provides dialog semantics and focus containment."
+        },
+        {
+          "when": "A chart needs a cursor- or data-point-positioned value callout.",
+          "component": "component:ds-tooltip-data-viz",
+          "reason": "TooltipDataViz accepts chart coordinates and is designed for data visualization hover feedback."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-button-filled",
+        "component:ds-button-unfilled",
+        "component:ds-panel-nav",
+        "component:ds-panel-tools"
+      ],
+      "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.",
+        "Keyboard focus opens the tooltip and Escape dismisses it without moving focus."
+      ],
+      "states": [
+        "The first hover or keyboard focus waits for delay; moving to another tooltip shortly after dismissal opens it immediately.",
+        "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.",
+        "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."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Place exactly one trigger element as the component's light-DOM child.",
+          "Replacing the slotted trigger rebinds pointer and focus behavior automatically.",
+          "sideOffset, alignOffset, and delay accept numbers or TokoMo CSS values."
+        ],
+        "react": [
+          "Wrap one focusable trigger with DsTooltip; keep the trigger's aria-label independent from the tooltip label."
+        ],
+        "angular": [
+          "Wrap one focusable trigger with DsTooltip and use property binding when offset or delay values are not plain strings."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook behavior examples",
+          "path": "src/wc/components/Tooltip/Tooltip.stories.ts"
+        },
+        {
+          "label": "Cross-browser behavior and accessibility coverage",
+          "path": "tests/e2e/tooltip.spec.ts"
+        },
+        {
+          "label": "Positioning unit coverage",
+          "path": "tests/tooltip-position.test.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "align": {
+          "type": "TooltipAlign",
+          "resolvedType": "\"center\" | \"end\" | \"start\"",
+          "attribute": "align",
+          "default": "'center'",
+          "required": false,
+          "mutable": false
+        },
+        "alignOffset": {
+          "type": "number | string",
+          "resolvedType": "number | string",
+          "attribute": "align-offset",
+          "default": "0",
+          "required": false,
+          "mutable": false,
+          "description": "Cross-axis offset — number (px) or TokoMo length."
+        },
+        "delay": {
+          "type": "number | string",
+          "resolvedType": "number | string",
+          "attribute": "delay",
+          "default": "TOKEN_DEFAULTS.animationDelayMedium3",
+          "required": false,
+          "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."
+        },
+        "label": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "label",
+          "required": true,
+          "mutable": false,
+          "description": "Tooltip text. Empty/whitespace skips show — useful when the wrapper must stay\nmounted for layout/animation stability (e.g. PanelNav expand/collapse)."
+        },
+        "shortcutKey": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "shortcut-key",
+          "required": false,
+          "mutable": false
+        },
+        "shortcutKeyPosition": {
+          "type": "'start' | 'end'",
+          "resolvedType": "\"end\" | \"start\"",
+          "attribute": "shortcut-key-position",
+          "default": "'end'",
+          "required": false,
+          "mutable": false
+        },
+        "side": {
+          "type": "TooltipSide",
+          "resolvedType": "\"bottom\" | \"left\" | \"right\" | \"top\"",
+          "attribute": "side",
+          "default": "'top'",
+          "required": false,
+          "mutable": false
+        },
+        "sideOffset": {
+          "type": "number | string",
+          "resolvedType": "number | string",
+          "attribute": "side-offset",
+          "default": "TOKEN_CSS_LENGTHS.space050",
+          "required": false,
+          "mutable": false,
+          "description": "Gap between anchor and tooltip — number (px) or TokoMo length."
+        },
+        "size": {
+          "type": "TooltipSize",
+          "resolvedType": "\"md\" | \"sm\" | \"xs\"",
+          "attribute": "size",
+          "default": "'md'",
+          "required": false,
+          "mutable": false,
+          "description": "Control density (height, padding, type)."
+        }
+      },
+      "events": [],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "align": {
+        "type": "TooltipAlign",
+        "resolvedType": "\"center\" | \"end\" | \"start\"",
+        "attribute": "align",
+        "default": "'center'",
+        "required": false,
+        "mutable": false
+      },
+      "alignOffset": {
+        "type": "number | string",
+        "resolvedType": "number | string",
+        "attribute": "align-offset",
+        "default": "0",
+        "required": false,
+        "mutable": false,
+        "description": "Cross-axis offset — number (px) or TokoMo length."
+      },
+      "delay": {
+        "type": "number | string",
+        "resolvedType": "number | string",
+        "attribute": "delay",
+        "default": "TOKEN_DEFAULTS.animationDelayMedium3",
+        "required": false,
+        "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."
+      },
+      "label": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "label",
+        "required": true,
+        "mutable": false,
+        "description": "Tooltip text. Empty/whitespace skips show — useful when the wrapper must stay\nmounted for layout/animation stability (e.g. PanelNav expand/collapse)."
+      },
+      "shortcutKey": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "shortcut-key",
+        "required": false,
+        "mutable": false
+      },
+      "shortcutKeyPosition": {
+        "type": "'start' | 'end'",
+        "resolvedType": "\"end\" | \"start\"",
+        "attribute": "shortcut-key-position",
+        "default": "'end'",
+        "required": false,
+        "mutable": false
+      },
+      "side": {
+        "type": "TooltipSide",
+        "resolvedType": "\"bottom\" | \"left\" | \"right\" | \"top\"",
+        "attribute": "side",
+        "default": "'top'",
+        "required": false,
+        "mutable": false
+      },
+      "sideOffset": {
+        "type": "number | string",
+        "resolvedType": "number | string",
+        "attribute": "side-offset",
+        "default": "TOKEN_CSS_LENGTHS.space050",
+        "required": false,
+        "mutable": false,
+        "description": "Gap between anchor and tooltip — number (px) or TokoMo length."
+      },
+      "size": {
+        "type": "TooltipSize",
+        "resolvedType": "\"md\" | \"sm\" | \"xs\"",
+        "attribute": "size",
+        "default": "'md'",
+        "required": false,
+        "mutable": false,
+        "description": "Control density (height, padding, type)."
+      }
+    },
+    "events": [],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-tooltip",
+      "react": "DsTooltip",
+      "angular": "DsTooltip"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-tooltip.js';",
+        "example": "<ds-tooltip></ds-tooltip>"
+      },
+      "react": {
+        "import": "import { DsTooltip } from '@ds-mo/ui/react';",
+        "example": "<DsTooltip />"
+      },
+      "angular": {
+        "import": "import { DsTooltip } from '@ds-mo/ui/angular/ds-tooltip';",
+        "example": "<ds-tooltip></ds-tooltip>"
+      },
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/icons ^6.2.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [
+    "text"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/Tooltip/Tooltip.css",
+      "content": "@import '../../utils/control-density.css';\n@import '../../utils/key-hint.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",
+      "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 { computeTooltipPosition } from './tooltip-position';\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 positionObserver: ResizeObserver | null = null;\n  private anchorObserver: MutationObserver | null = null;\n  private positionFrame: number | null = null;\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 scrollResizeHandler = () => {\n    if (this.positionFrame !== null) return;\n    this.positionFrame = requestAnimationFrame(() => {\n      this.positionFrame = null;\n      this.calculatePosition();\n    });\n  };\n  private escapeHandler = (event: KeyboardEvent) => {\n    if (event.key !== 'Escape' || !this.isOpen) return;\n    event.preventDefault();\n    this.hide();\n  };\n\n  componentDidLoad() {\n    this.bindAnchor();\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    window.addEventListener('scroll', this.scrollResizeHandler, true);\n    window.addEventListener('resize', this.scrollResizeHandler);\n    document.addEventListener('keydown', this.escapeHandler);\n  }\n\n  private teardownOpenListeners() {\n    window.removeEventListener('scroll', this.scrollResizeHandler, true);\n    window.removeEventListener('resize', this.scrollResizeHandler);\n    document.removeEventListener('keydown', this.escapeHandler);\n    if (this.positionFrame !== null) {\n      cancelAnimationFrame(this.positionFrame);\n      this.positionFrame = null;\n    }\n  }\n\n  private destroyPopup() {\n    this.teardownOpenListeners();\n    this.positionObserver?.disconnect();\n    this.positionObserver = null;\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.calculatePosition();\n      requestAnimationFrame(() => {\n        reapplyLabelStyles();\n        this.calculatePosition();\n      });\n    });\n\n    this.positionObserver?.disconnect();\n    this.positionObserver = new ResizeObserver(() => this.calculatePosition());\n    this.positionObserver.observe(this.popupEl);\n    if (this.anchor) this.positionObserver.observe(this.anchor);\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 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  private calculatePosition() {\n    if (!this.anchor || !this.popupEl) return;\n    const tip = this.popupEl;\n    const a = this.anchor.getBoundingClientRect();\n    const tw = tip.offsetWidth || this.tooltipFallbackWidthPx;\n    const th = tip.offsetHeight || this.tooltipFallbackHeightPx;\n    const { x, y, resolvedSide } = computeTooltipPosition({\n      anchorRect: a,\n      popupWidth: tw,\n      popupHeight: th,\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    tip.dataset.side = resolvedSide;\n    tip.style.transform = `translate(${Math.round(x)}px, ${Math.round(y)}px)`;\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"
+    },
+    {
+      "path": "src/wc/components/Tooltip/tooltip-position.ts",
+      "content": "import type { TooltipAlign, TooltipSide } from './Tooltip';\n\nexport interface TooltipPositionInput {\n  anchorRect: Pick<DOMRectReadOnly, 'top' | 'left' | 'right' | 'bottom' | 'width' | 'height'>;\n  popupWidth: number;\n  popupHeight: number;\n  side: TooltipSide;\n  align: TooltipAlign;\n  sideOffsetPx: number;\n  alignOffsetPx: number;\n  viewportPadPx: number;\n  viewportWidth: number;\n  viewportHeight: number;\n}\n\nexport interface TooltipPosition {\n  x: number;\n  y: number;\n  resolvedSide: TooltipSide;\n}\n\nconst OPPOSITE_SIDE: Record<TooltipSide, TooltipSide> = {\n  top: 'bottom',\n  right: 'left',\n  bottom: 'top',\n  left: 'right',\n};\n\nfunction rawPosition(\n  input: TooltipPositionInput,\n  side: TooltipSide,\n): Pick<TooltipPosition, 'x' | 'y'> {\n  const {\n    anchorRect: anchor,\n    popupWidth,\n    popupHeight,\n    align,\n    sideOffsetPx,\n    alignOffsetPx,\n  } = input;\n\n  if (side === 'top' || side === 'bottom') {\n    return {\n      x:\n        align === 'start'\n          ? anchor.left + alignOffsetPx\n          : align === 'end'\n            ? anchor.right - popupWidth + alignOffsetPx\n            : anchor.left + anchor.width / 2 - popupWidth / 2 + alignOffsetPx,\n      y: side === 'top'\n        ? anchor.top - popupHeight - sideOffsetPx\n        : anchor.bottom + sideOffsetPx,\n    };\n  }\n\n  return {\n    x: side === 'left'\n      ? anchor.left - popupWidth - sideOffsetPx\n      : anchor.right + sideOffsetPx,\n    y:\n      align === 'start'\n        ? anchor.top + alignOffsetPx\n        : align === 'end'\n          ? anchor.bottom - popupHeight + alignOffsetPx\n          : anchor.top + anchor.height / 2 - popupHeight / 2 + alignOffsetPx,\n  };\n}\n\nfunction mainAxisOverflow(\n  input: TooltipPositionInput,\n  side: TooltipSide,\n  position: Pick<TooltipPosition, 'x' | 'y'>,\n): number {\n  const {\n    popupWidth,\n    popupHeight,\n    viewportPadPx,\n    viewportWidth,\n    viewportHeight,\n  } = input;\n\n  if (side === 'top' || side === 'bottom') {\n    return Math.max(viewportPadPx - position.y, 0) +\n      Math.max(position.y + popupHeight - (viewportHeight - viewportPadPx), 0);\n  }\n\n  return Math.max(viewportPadPx - position.x, 0) +\n    Math.max(position.x + popupWidth - (viewportWidth - viewportPadPx), 0);\n}\n\n/** Flip on the preferred axis when needed, then clamp within the viewport. */\nexport function computeTooltipPosition(input: TooltipPositionInput): TooltipPosition {\n  const preferred = rawPosition(input, input.side);\n  const oppositeSide = OPPOSITE_SIDE[input.side];\n  const opposite = rawPosition(input, oppositeSide);\n  const preferredOverflow = mainAxisOverflow(input, input.side, preferred);\n  const oppositeOverflow = mainAxisOverflow(input, oppositeSide, opposite);\n  const useOpposite = preferredOverflow > 0 && oppositeOverflow < preferredOverflow;\n  const resolvedSide = useOpposite ? oppositeSide : input.side;\n  const position = useOpposite ? opposite : preferred;\n  const maxX = Math.max(input.viewportPadPx, input.viewportWidth - input.popupWidth - input.viewportPadPx);\n  const maxY = Math.max(input.viewportPadPx, input.viewportHeight - input.popupHeight - input.viewportPadPx);\n\n  return {\n    x: Math.min(Math.max(position.x, input.viewportPadPx), maxX),\n    y: Math.min(Math.max(position.y, input.viewportPadPx), maxY),\n    resolvedSide,\n  };\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}

package/dist/react/components.d.ts

@@ -26,7 +26,6 @@ export { DsInput } from "./ds-input.js";
 export { DsLoader } from "./ds-loader.js";
 export { DsMenu } from "./ds-menu.js";
 export { DsModal } from "./ds-modal.js";
-export { DsPagination } from "./ds-pagination.js";
 export { DsPanelNav } from "./ds-panel-nav.js";
 export { DsPanelSubNav } from "./ds-panel-sub-nav.js";
 export { DsPanelTools } from "./ds-panel-tools.js";
@@ -37,9 +36,9 @@ export { DsShellGradientPicker } from "./ds-shell-gradient-picker.js";
 export { DsShellGradientSwatch } from "./ds-shell-gradient-swatch.js";
 export { DsSkeleton } from "./ds-skeleton.js";
 export { DsSlider } from "./ds-slider.js";
+export { DsSwatchPicker } from "./ds-swatch-picker.js";
 export { DsSwitch } from "./ds-switch.js";
 export { DsTabGroup } from "./ds-tab-group.js";
-export { DsTable } from "./ds-table.js";
 export { DsTag } from "./ds-tag.js";
 export { DsText } from "./ds-text.js";
 export { DsTooltipDataViz } from "./ds-tooltip-data-viz.js";

package/dist/react/components.js

@@ -27,7 +27,6 @@ export { DsInput } from "./ds-input.js";
 export { DsLoader } from "./ds-loader.js";
 export { DsMenu } from "./ds-menu.js";
 export { DsModal } from "./ds-modal.js";
-export { DsPagination } from "./ds-pagination.js";
 export { DsPanelNav } from "./ds-panel-nav.js";
 export { DsPanelSubNav } from "./ds-panel-sub-nav.js";
 export { DsPanelTools } from "./ds-panel-tools.js";
@@ -38,9 +37,9 @@ export { DsShellGradientPicker } from "./ds-shell-gradient-picker.js";
 export { DsShellGradientSwatch } from "./ds-shell-gradient-swatch.js";
 export { DsSkeleton } from "./ds-skeleton.js";
 export { DsSlider } from "./ds-slider.js";
+export { DsSwatchPicker } from "./ds-swatch-picker.js";
 export { DsSwitch } from "./ds-switch.js";
 export { DsTabGroup } from "./ds-tab-group.js";
-export { DsTable } from "./ds-table.js";
 export { DsTag } from "./ds-tag.js";
 export { DsText } from "./ds-text.js";
 export { DsTooltipDataViz } from "./ds-tooltip-data-viz.js";

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

@@ -10,5 +10,6 @@ export type DsMenuEvents = {
     onDsClose: EventName<DsMenuCustomEvent<void>>;
     onDsSelect: EventName<DsMenuCustomEvent<MenuItemData>>;
     onDsGradientSelect: EventName<DsMenuCustomEvent<ShellGradientPreset>>;
+    onDsSwatchSelect: EventName<DsMenuCustomEvent<string>>;
 };
 export declare const DsMenu: StencilReactComponent<DsMenuElement, DsMenuEvents, Components.DsMenu>;

package/dist/react/ds-menu.js

@@ -10,7 +10,8 @@ export const DsMenu = /*@__PURE__*/ createComponent({
     events: {
         onDsClose: 'dsClose',
         onDsSelect: 'dsSelect',
-        onDsGradientSelect: 'dsGradientSelect'
+        onDsGradientSelect: 'dsGradientSelect',
+        onDsSwatchSelect: 'dsSwatchSelect'
     },
     defineCustomElement: defineDsMenu
 });

package/dist/react/ds-swatch-picker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This file was automatically generated by the Stencil React Output Target.
+ * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
+import { type DsSwatchPickerCustomEvent } from "@ds-mo/ui";
+import type { Components } from "@ds-mo/ui/dist/components";
+import { DsSwatchPicker as DsSwatchPickerElement } from "@ds-mo/ui/dist/components/ds-swatch-picker.js";
+export type DsSwatchPickerEvents = {
+    onDsChange: EventName<DsSwatchPickerCustomEvent<string>>;
+};
+export declare const DsSwatchPicker: StencilReactComponent<DsSwatchPickerElement, DsSwatchPickerEvents, Components.DsSwatchPicker>;

package/dist/react/ds-swatch-picker.js

@@ -0,0 +1,12 @@
+'use client';
+import { createComponent } from '@stencil/react-output-target/runtime';
+import React from 'react';
+import { DsSwatchPicker as DsSwatchPickerElement, defineCustomElement as defineDsSwatchPicker } from "@ds-mo/ui/dist/components/ds-swatch-picker.js";
+export const DsSwatchPicker = /*@__PURE__*/ createComponent({
+    tagName: 'ds-swatch-picker',
+    elementClass: DsSwatchPickerElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: { onDsChange: 'dsChange' },
+    defineCustomElement: defineDsSwatchPicker
+});

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

@@ -1,7 +1,8 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+import { type ChoicePopupAnchorAlignment } from '../../utils';
 import { type MenuAlign, type MenuSide } from './menu-position';
 import type { MenuItemData, MenuSection } from './menu-types';
-import type { ShellGradientPreset } from '../../shell/shell-gradient-presets';
+import { type ShellGradientPreset } from '../../shell/shell-gradient-presets';
 export declare class Menu {
     el: HTMLElement;
     open: boolean;
@@ -9,6 +10,8 @@ export declare class Menu {
     sections: MenuSection[];
     side: MenuSide;
     align: MenuAlign;
+    /** Align choice-row edges to the anchor by default; use `popup-frame` only for custom frame geometry. */
+    anchorAlignment: ChoicePopupAnchorAlignment;
     /** Gap between anchor and menu — number (px) or TokoMo length (`var(--dimension-space-050)`, etc.). */
     sideOffset: number | string;
     /** Cross-axis offset — number (px) or TokoMo length. */
@@ -33,6 +36,8 @@ export declare class Menu {
     dsSelect: EventEmitter<MenuItemData>;
     /** Emitted when a `gradient-picker` section swatch is chosen. */
     dsGradientSelect: EventEmitter<ShellGradientPreset>;
+    /** Emitted when a generic `swatch-picker` section option is chosen. */
+    dsSwatchSelect: EventEmitter<string>;
     private clickOutsideHandler;
     private scrollResizeHandler;
     private closeTimer;
@@ -74,6 +79,7 @@ export declare class Menu {
     private focusItem;
     private handleItemClick;
     private handleGradientSelect;
+    private handleSwatchSelect;
     render(): any;
 }
 //# sourceMappingURL=Menu.d.ts.map

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

@@ -1,8 +1,10 @@
+import type { ChoicePopupAnchorAlignment } from '../../utils/choice-popup-alignment';
 import type { MenuAlign, MenuSide } from './menu-position';
 /** Placement props bindable on `ds-menu` (side, align, offsets). */
 export interface MenuPlacement {
     side: MenuSide;
     align: MenuAlign;
+    anchorAlignment: ChoicePopupAnchorAlignment;
     sideOffset: number | string;
     alignOffset: number | string;
 }
@@ -11,14 +13,15 @@ export interface MenuPlacement {
  * Anchor from `dsNavUserAction` detail `{ anchor }` (id `ds-panel-nav-user-menu-anchor`).
  *
  * Not for BarNav overflow menus — those use `side="bottom"` / `align="end"` internally.
- * `align: 'end'` bottom-aligns on the anchor; offsets nudge into the content area:
+ * `align: 'end'` bottom-aligns the last choice cell on the anchor; the side offset nudges into the content area:
  * - `sideOffset` space-100 + space-050 (12px): 4px past the panel-nav outer edge (anchor is ~8px inset).
- * - `alignOffset` space-050 (4px): 4px below the footer user row.
+ * - `anchorAlignment: 'choice-cell'`: the shared section inset puts the last row edge on the footer user row.
  */
 export declare const PANEL_NAV_USER_MENU_PLACEMENT: {
     readonly side: "right";
     readonly align: "end";
+    readonly anchorAlignment: "choice-cell";
     readonly sideOffset: "calc(var(--dimension-space-100) + var(--dimension-space-050))";
-    readonly alignOffset: "var(--dimension-space-050)";
+    readonly alignOffset: 0;
 };
 //# sourceMappingURL=menu-placement.d.ts.map

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

@@ -1,4 +1,5 @@
 import type { ShellGradientPreset } from '../../shell/shell-gradient-presets';
+import type { SwatchPickerOption, SwatchPickerSection } from '../SwatchPicker/swatch-picker-types';
 export type { MenuAlign, MenuSide } from './menu-position';
 export { PANEL_NAV_USER_MENU_PLACEMENT, type MenuPlacement, } from './menu-placement';
 export interface MenuItemData {
@@ -20,10 +21,22 @@ export interface MenuItemsSection {
 }
 export interface MenuGradientPickerSection {
     header?: string;
+    /** @deprecated Use the generic `swatch-picker` section. */
     variant: 'gradient-picker';
     value: ShellGradientPreset;
 }
-export type MenuSection = MenuItemsSection | MenuGradientPickerSection;
+export interface MenuSwatchPickerSection {
+    header?: string;
+    variant: 'swatch-picker';
+    value: string;
+    options?: SwatchPickerOption[];
+    sections?: SwatchPickerSection[];
+    groupLabel?: string;
+}
+export type MenuSection = MenuItemsSection | MenuGradientPickerSection | MenuSwatchPickerSection;
 export declare function isMenuGradientPickerSection(section: MenuSection): section is MenuGradientPickerSection;
+export declare function isMenuSwatchPickerSection(section: MenuSection): section is MenuSwatchPickerSection;
+export declare function isMenuPickerSection(section: MenuSection): section is MenuGradientPickerSection | MenuSwatchPickerSection;
 export type { ShellGradientPreset };
+export type { SwatchPickerOption, SwatchPickerSection };
 //# sourceMappingURL=menu-types.d.ts.map

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

@@ -1,15 +1,12 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { type ShellGradientPreset } from '../ShellGradientSwatch/shell-gradient-swatch-types';
+/** @deprecated Use `ds-swatch-picker` with shell preset options. */
 export declare class ShellGradientPicker {
     /** Active shell wash preset. */
     value: ShellGradientPreset;
     groupLabel: string;
     dsChange: EventEmitter<ShellGradientPreset>;
-    el: HTMLElement;
-    private handleSwatchSelect;
-    private focusSwatch;
-    private handleSwatchKeyDown;
-    private renderSwatch;
+    private handleChange;
     render(): any;
 }
 //# sourceMappingURL=ShellGradientPicker.d.ts.map

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

@@ -1,5 +1,6 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { type ShellGradientPreset } from './shell-gradient-swatch-types';
+/** @deprecated Use `ds-swatch-picker`; individual swatches are implementation detail. */
 export declare class ShellGradientSwatch {
     /** Wash preset this orb previews. */
     preset: ShellGradientPreset;

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

@@ -0,0 +1,21 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import { type SwatchPickerOption, type SwatchPickerSection } from './swatch-picker-types';
+export declare class SwatchPicker {
+    el: HTMLElement;
+    /** Selected option value. */
+    value: string;
+    /** Flat option list. Sections take precedence when supplied. Assign as a JavaScript property. */
+    options: SwatchPickerOption[];
+    /** Visually separated option groups that remain one radio group. Assign as a JavaScript property. */
+    sections: SwatchPickerSection[];
+    /** Accessible name for the complete one-of-many choice. */
+    groupLabel: string;
+    dsChange: EventEmitter<string>;
+    private get activeOptions();
+    private selectOption;
+    private focusOption;
+    private handleOptionKeyDown;
+    private renderOption;
+    render(): any;
+}
+//# sourceMappingURL=SwatchPicker.d.ts.map

package/dist/types/components/SwatchPicker/swatch-picker-types.d.ts

@@ -0,0 +1,26 @@
+export interface SwatchPickerPreview {
+    /** CSS color used as the swatch base or as a complete flat-color preview. */
+    backgroundColor?: string;
+    /** CSS gradient used as the swatch image. */
+    backgroundImage?: string;
+    /** Optional preview-layer opacity, clamped to the inclusive 0–1 range. */
+    opacity?: number;
+}
+export interface SwatchPickerOption {
+    /** Stable value emitted when this option is selected. */
+    value: string;
+    /** Accessible option name; the visual preview never replaces this label. */
+    label: string;
+    preview: SwatchPickerPreview;
+    isInactive?: boolean;
+}
+export interface SwatchPickerSection {
+    /** Sections remain one radio group and are separated visually. */
+    options: SwatchPickerOption[];
+}
+export type SwatchPickerNavigationKey = 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'Home' | 'End';
+export declare function flattenSwatchPickerOptions(options: readonly SwatchPickerOption[], sections: readonly SwatchPickerSection[]): SwatchPickerOption[];
+export declare function resolveSwatchPickerTabIndex(options: readonly SwatchPickerOption[], value: string): number;
+export declare function resolveSwatchPickerNavigationIndex(options: readonly SwatchPickerOption[], currentIndex: number, key: SwatchPickerNavigationKey): number | null;
+export declare function normalizeSwatchPickerOpacity(opacity: number | undefined): number;
+//# sourceMappingURL=swatch-picker-types.d.ts.map