@fabric-msft/copilot-web 7.0.0

package/esm/components/reference-pill/reference-pill.js

@@ -0,0 +1,681 @@
+import { __decorate } from 'tslib';
+import { attr, observable, FASTElement } from '@microsoft/fast-element';
+import { keyEscape, keySpace, keyEnter } from '@microsoft/fast-web-utilities';
+import { ReferencePillEventNames } from './reference-pill.options.js';
+
+/**
+ * Counter for generating unique IDs for aria-labelledby.
+ * @internal
+ */
+let idCounter = 0;
+/**
+ * Reference Pill
+ * @summary A compact, composite widget for displaying reference information with associated metadata.
+ *
+ * @description
+ * The Reference Pill presents source references with an icon, clickable title link, optional sensitivity
+ * indicator (with popover), external labels, and metadata. It follows a composite widget pattern where
+ * the pill is a single tab stop, and Enter/Space "enters" the pill to access internal focusable elements.
+ *
+ * **Keyboard Navigation:**
+ * - Tab to the pill (single tab stop)
+ * - Enter/Space enters the pill and focuses the first internal element (title link)
+ * - Tab/Shift+Tab navigates between internal elements (title-link → sensitivity button → action → prompt-menu)
+ * - Escape returns focus to the pill container
+ * - When sensitivity popover is open, Escape closes it first
+ *
+ * **Internal Tab Order:**
+ * 1. Title link (fabric-link)
+ * 2. Sensitivity button (if present)
+ * 3. Action button (if present)
+ * 4. Prompt menu trigger (if present)
+ *
+ * @example Basic usage with title link
+ * ```html
+ * <fabric-reference-pill>
+ *   <fabric-svg-icon slot="icon" name="document-20-regular"></fabric-svg-icon>
+ *   <fabric-link slot="title-link" href="https://example.com">Document Title</fabric-link>
+ *   <span slot="metadata">Author | Modified: Jan 5, 2026</span>
+ * </fabric-reference-pill>
+ * ```
+ *
+ * @example With sensitivity popover
+ * ```html
+ * <fabric-reference-pill>
+ *   <fabric-svg-icon slot="icon" name="document-20-regular"></fabric-svg-icon>
+ *   <fabric-link slot="title-link" href="https://example.com">Confidential Report</fabric-link>
+ *   <fabric-popover slot="sensitivity" mode="auto" position="below" size="small">
+ *     <fabric-button slot="popover-trigger" icon-only size="small" appearance="subtle" aria-label="Sensitivity">
+ *       <svg><!-- sensitivity icon --></svg>
+ *     </fabric-button>
+ *     <div slot="popover-content">
+ *       <h4>Confidential</h4>
+ *       <p>This document contains sensitive information.</p>
+ *     </div>
+ *   </fabric-popover>
+ *   <span slot="metadata">Finance | Q4 2025</span>
+ * </fabric-reference-pill>
+ * ```
+ *
+ * @attr {boolean} disabled - Disables all interactive elements within the pill.
+ *
+ * @slot icon - The reference type icon (20×20px). Indicates the type of reference.
+ * @slot title-link - The clickable title link. Use `<fabric-link>` for navigation.
+ * @slot sensitivity - Sensitivity indicator popover. Use `<fabric-popover>` with trigger button and content.
+ * @slot external-label - External source badge. Expects a `<fabric-badge>` component.
+ * @slot metadata - Additional metadata text (e.g., author, date, file type).
+ * @slot action - Action button slot. Accepts one or more `<fabric-button icon-only>` elements.
+ * @slot prompt-menu - Prompt menu popover. Use `<fabric-popover>` with trigger button and content.
+ *
+ * @csspart container - The main pill container.
+ * @csspart icon - The icon wrapper.
+ * @csspart content-wrapper - The wrapper containing title row and metadata row.
+ * @csspart title-row - The row containing title, sensitivity, and badge.
+ * @csspart title - The title link wrapper.
+ * @csspart sensitivity - The sensitivity button wrapper.
+ * @csspart external-label - The external label wrapper.
+ * @csspart metadata-row - The row containing metadata.
+ * @csspart metadata - The metadata text wrapper.
+ * @csspart actions - The action buttons region.
+ *
+ * @fires sensitivity-toggle - Fires when the sensitivity popover opens or closes. Detail: `{ open: boolean }`.
+ * @fires prompt-menu-toggle - Fires when the prompt menu popover opens or closes. Detail: `{ open: boolean }`.
+ *
+ * @extends FASTElement
+ * @tagname fabric-reference-pill
+ * @public
+ */
+class ReferencePill extends FASTElement {
+  constructor() {
+    super(...arguments);
+    /**
+     * Tracks whether the pill is "entered" (internal content is keyboard-navigable).
+     * @internal
+     */
+    this.isEntered = false;
+    /**
+     * Stores original tabindex values for slotted elements.
+     * @internal
+     */
+    this.originalTabindexMap = new WeakMap();
+    /**
+     * Unique ID for this instance, used for aria-labelledby.
+     * @internal
+     */
+    this.uniqueId = `reference-pill-${++idCounter}`;
+    /**
+     * List of interactive slots that participate in focus management.
+     * @internal
+     */
+    this.interactiveSlots = ["title-link", "sensitivity", "action", "prompt-menu"];
+    /**
+     * Handles clicks on internal elements - enters the pill if not already entered.
+     * @internal
+     */
+    this.handleInternalClick = event => {
+      // Block all interactions when disabled
+      if (this.disabled) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        return;
+      }
+      const target = event.target;
+      // Only enter the pill when clicking on interactive slot content
+      // (not prompts-popover which is outside the main pill container)
+      if (target !== this && this.contains(target)) {
+        const isInteractiveSlot = this.interactiveSlots.some(slotName => {
+          const slotted = this.querySelectorAll(`[slot="${slotName}"]`);
+          return Array.from(slotted).some(el => el === target || el.contains(target));
+        });
+        if (isInteractiveSlot) {
+          this.isEntered = true;
+          this.restoreElementTabindexes();
+        }
+      }
+    };
+    /**
+     * Disables all interactive elements within the pill.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: `disabled`
+     */
+    this.disabled = false;
+    /**
+     * Tracks whether the prompts popover is open.
+     * @public
+     */
+    this.promptsOpen = false;
+    /**
+     * Tracks whether the sensitivity popover is open.
+     * @public
+     */
+    this.sensitivityOpen = false;
+    /**
+     * Handles keydown events on the pill.
+     * @internal
+     */
+    this.handleKeydown = event => {
+      if (this.disabled) return;
+      const {
+        key,
+        shiftKey,
+        target
+      } = event;
+      const isTargetHost = target === this;
+      switch (key) {
+        case keyEnter:
+        case keySpace:
+          // Only enter pill if focus is on the host itself
+          if (isTargetHost) {
+            event.preventDefault();
+            this.enterPill();
+          }
+          break;
+        case keyEscape:
+          // Close sensitivity popover first if open
+          if (this.sensitivityOpen) {
+            event.preventDefault();
+            this.sensitivityOpen = false;
+            this.emitSensitivityToggle(false);
+            const sensitivityPopover = this.getSensitivityPopover();
+            if (sensitivityPopover && "open" in sensitivityPopover) {
+              sensitivityPopover.open = false;
+            }
+            // Return focus to sensitivity trigger button
+            const triggerButton = sensitivityPopover === null || sensitivityPopover === void 0 ? void 0 : sensitivityPopover.querySelector('[slot="popover-trigger"]');
+            triggerButton === null || triggerButton === void 0 ? void 0 : triggerButton.focus();
+            return;
+          }
+          // Close prompts popover if open
+          if (this.promptsOpen) {
+            event.preventDefault();
+            this.promptsOpen = false;
+            this.emitPromptMenuToggle(false);
+            const promptMenuPopover = this.getPromptMenuPopover();
+            if (promptMenuPopover && "open" in promptMenuPopover) {
+              promptMenuPopover.open = false;
+            }
+            // Return focus to prompt menu trigger button
+            const triggerButton = promptMenuPopover === null || promptMenuPopover === void 0 ? void 0 : promptMenuPopover.querySelector('[slot="popover-trigger"]');
+            if (triggerButton) {
+              triggerButton.focus();
+            } else if (promptMenuPopover instanceof HTMLElement) {
+              // Fallback for direct button pattern
+              promptMenuPopover.focus();
+            }
+            return;
+          }
+          // Exit pill and return to host
+          if (this.isEntered) {
+            event.preventDefault();
+            event.stopPropagation(); // Prevent list from also handling Escape
+            this.exitPill(true);
+          }
+          break;
+        default:
+          // Handle focus trapping when entered - loop focus within the pill
+          if (key === "Tab" && this.isEntered) {
+            const tabbables = this.getTabbableElements();
+            if (tabbables.length === 0) return;
+            if (this.isLastElementFocused && !shiftKey) {
+              // Tab on last element - loop to first element
+              event.preventDefault();
+              tabbables[0].focus();
+            } else if (this.isFirstElementFocused && shiftKey) {
+              // Shift+Tab on first element - loop to last element
+              event.preventDefault();
+              tabbables[tabbables.length - 1].focus();
+            }
+          }
+          break;
+      }
+    };
+    /**
+     * Handles focus leaving the pill.
+     * @internal
+     */
+    this.handleFocusOut = event => {
+      const relatedTarget = event.relatedTarget;
+      // If focus is leaving the pill entirely, exit the pill and close popovers
+      if (!relatedTarget || !this.contains(relatedTarget)) {
+        this.closeAllPopovers();
+        this.exitPill(false);
+      }
+    };
+    /**
+     * Handles toggle events from slotted popovers via event delegation.
+     * Determines which popover emitted the event and updates state accordingly.
+     * @internal
+     */
+    this.handlePopoverToggle = event => {
+      const toggleEvent = event;
+      const isOpen = toggleEvent.newState === "open";
+      // Use composedPath to find the actual source element across shadow boundaries
+      const path = event.composedPath();
+      // Check if this toggle came from the sensitivity popover
+      const sensitivityPopover = this.getSensitivityPopover();
+      if (sensitivityPopover && path.includes(sensitivityPopover)) {
+        if (this.sensitivityOpen !== isOpen) {
+          this.sensitivityOpen = isOpen;
+          this.emitSensitivityToggle(isOpen);
+        }
+        return;
+      }
+      // Check if this toggle came from the prompt-menu popover
+      const promptMenuPopover = this.getPromptMenuPopover();
+      if (promptMenuPopover && path.includes(promptMenuPopover)) {
+        if (this.promptsOpen !== isOpen) {
+          this.promptsOpen = isOpen;
+          this.emitPromptMenuToggle(isOpen);
+        }
+      }
+    };
+  }
+  /**
+   * Called when the element is connected to the DOM.
+   * Sets up host-level focus handling and slot management.
+   * @public
+   */
+  connectedCallback() {
+    super.connectedCallback();
+    this.updateHostTabindex();
+    this.updateAriaDisabled();
+    this.addEventListener("keydown", this.handleKeydown);
+    this.addEventListener("focusout", this.handleFocusOut);
+    this.addEventListener("click", this.handleInternalClick);
+    // Listen for toggle events from slotted popovers (event delegation)
+    this.addEventListener("toggle", this.handlePopoverToggle);
+    // Set up slot change listeners for interactive slots
+    this.setupSlotListeners();
+    // Set up aria-labelledby pointing to title link
+    this.setupAriaLabelledBy();
+  }
+  /**
+   * Called when the element is disconnected from the DOM.
+   * @public
+   */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeEventListener("keydown", this.handleKeydown);
+    this.removeEventListener("focusout", this.handleFocusOut);
+    this.removeEventListener("click", this.handleInternalClick);
+    this.removeEventListener("toggle", this.handlePopoverToggle);
+  }
+  /**
+   * Sets up slot change listeners for interactive element slots.
+   * @internal
+   */
+  setupSlotListeners() {
+    var _a;
+    this.interactiveSlots.forEach(slotName => {
+      var _a;
+      const slot = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector(`slot[name="${slotName}"]`);
+      slot === null || slot === void 0 ? void 0 : slot.addEventListener("slotchange", () => this.handleInteractiveSlotChange(slot));
+    });
+    // Also listen for title-link slot changes to update aria-labelledby
+    const titleSlot = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('slot[name="title-link"]');
+    titleSlot === null || titleSlot === void 0 ? void 0 : titleSlot.addEventListener("slotchange", () => this.setupAriaLabelledBy());
+    // Initial setup for any already-slotted content
+    requestAnimationFrame(() => this.initializeSlottedElements());
+  }
+  /**
+   * Sets up aria-labelledby pointing to the title link element.
+   * @internal
+   */
+  setupAriaLabelledBy() {
+    const titleLink = this.querySelector('[slot="title-link"]');
+    if (titleLink) {
+      // Ensure the title link has an ID
+      if (!titleLink.id) {
+        titleLink.id = `${this.uniqueId}-title`;
+      }
+      this.setAttribute("aria-labelledby", titleLink.id);
+    }
+  }
+  /**
+   * Updates aria-disabled attribute on the host.
+   * @internal
+   */
+  updateAriaDisabled() {
+    if (this.disabled) {
+      this.setAttribute("aria-disabled", "true");
+    } else {
+      this.removeAttribute("aria-disabled");
+    }
+  }
+  /**
+   * Propagates disabled state to slotted interactive elements.
+   * @internal
+   */
+  propagateDisabledState() {
+    this.interactiveSlots.forEach(slotName => {
+      const slotted = this.querySelectorAll(`[slot="${slotName}"]`);
+      slotted.forEach(el => {
+        // Handle fabric-button, fabric-link, and fabric-popover
+        if (this.disabled) {
+          el.setAttribute("disabled", "");
+          // For links, also set aria-disabled since links don't support disabled
+          if (el.tagName.toLowerCase().includes("link")) {
+            el.setAttribute("aria-disabled", "true");
+          }
+        } else {
+          el.removeAttribute("disabled");
+          if (el.tagName.toLowerCase().includes("link")) {
+            el.removeAttribute("aria-disabled");
+          }
+        }
+      });
+    });
+  }
+  /**
+   * Handles slot changes for interactive element slots.
+   * @internal
+   */
+  handleInteractiveSlotChange(slot) {
+    const slotName = slot.name;
+    const elements = this.getFocusableFromSlot(slotName);
+    elements.forEach(el => {
+      this.setElementTabindex(el, -1);
+    });
+  }
+  /**
+   * Initialize tabindex for all slotted interactive elements.
+   * @internal
+   */
+  initializeSlottedElements() {
+    this.interactiveSlots.forEach(slotName => {
+      const elements = this.getFocusableFromSlot(slotName);
+      elements.forEach(el => {
+        this.setElementTabindex(el, -1);
+      });
+    });
+    // Propagate initial disabled state
+    this.propagateDisabledState();
+  }
+  /**
+   * Sets tabindex on an element, storing the original value.
+   * @internal
+   */
+  setElementTabindex(element, tabindex) {
+    // Store original tabindex if not already stored
+    if (!this.originalTabindexMap.has(element)) {
+      this.originalTabindexMap.set(element, element.getAttribute("tabindex"));
+    }
+    element.setAttribute("tabindex", String(tabindex));
+  }
+  /**
+   * Gets the focusable element from a slot - handles both direct elements and popover triggers.
+   * @internal
+   */
+  getFocusableFromSlot(slotName) {
+    const elements = [];
+    const slotted = this.querySelectorAll(`[slot="${slotName}"]`);
+    slotted.forEach(el => {
+      // Check if this is a popover with a trigger inside
+      const trigger = el.querySelector('[slot="popover-trigger"]');
+      if (trigger instanceof HTMLElement) {
+        elements.push(trigger);
+      } else if (el instanceof HTMLElement) {
+        // Direct element (e.g., fabric-link, fabric-button)
+        elements.push(el);
+      }
+    });
+    return elements;
+  }
+  /**
+   * Restores original tabindex on all managed elements.
+   * @internal
+   */
+  restoreElementTabindexes() {
+    this.interactiveSlots.forEach(slotName => {
+      const elements = this.getFocusableFromSlot(slotName);
+      elements.forEach(el => {
+        const original = this.originalTabindexMap.get(el);
+        if (original === null) {
+          el.removeAttribute("tabindex");
+        } else if (original !== undefined) {
+          el.setAttribute("tabindex", original);
+        } else {
+          // If we didn't store an original, set to 0 for natural tab order
+          el.setAttribute("tabindex", "0");
+        }
+      });
+    });
+  }
+  /**
+   * Removes elements from tab order by setting tabindex=-1.
+   * @internal
+   */
+  removeElementsFromTabOrder() {
+    this.interactiveSlots.forEach(slotName => {
+      const elements = this.getFocusableFromSlot(slotName);
+      elements.forEach(el => {
+        this.setElementTabindex(el, -1);
+      });
+    });
+  }
+  /**
+   * Updates the host tabindex based on disabled state.
+   * @internal
+   */
+  updateHostTabindex() {
+    this.tabIndex = this.disabled ? -1 : 0;
+  }
+  /**
+   * Handler for disabled attribute changes.
+   * @internal
+   */
+  disabledChanged() {
+    // Guard against running before element is connected to DOM
+    // (FAST may call change handlers during property initialization)
+    // Using native isConnected property which is always available
+    if (!this.isConnected) {
+      return;
+    }
+    this.updateHostTabindex();
+    this.updateAriaDisabled();
+    this.propagateDisabledState();
+    if (this.disabled) {
+      // Close any open popovers by setting their open property directly
+      const sensitivityPopover = this.getSensitivityPopover();
+      if (sensitivityPopover && "open" in sensitivityPopover) {
+        sensitivityPopover.open = false;
+      }
+      const promptMenuPopover = this.getPromptMenuPopover();
+      if (promptMenuPopover && "open" in promptMenuPopover) {
+        promptMenuPopover.open = false;
+      }
+      this.exitPill();
+    }
+  }
+  /**
+   * Gets all focusable elements inside the pill that participate in internal navigation.
+   * Order: title-link, sensitivity (popover trigger), action buttons, prompt-menu (popover trigger)
+   * @internal
+   */
+  getTabbableElements() {
+    const elements = [];
+    // Title link (first in tab order)
+    const titleLink = this.querySelector('[slot="title-link"]');
+    if (titleLink instanceof HTMLElement) {
+      elements.push(titleLink);
+    }
+    // Sensitivity popover - find the trigger button inside it
+    const sensitivityPopover = this.querySelector('[slot="sensitivity"]');
+    if (sensitivityPopover) {
+      // Look for the popover trigger button
+      const triggerButton = sensitivityPopover.querySelector('[slot="popover-trigger"]');
+      if (triggerButton instanceof HTMLElement) {
+        elements.push(triggerButton);
+      }
+    }
+    // Action buttons
+    const actions = this.querySelectorAll('[slot="action"]');
+    actions.forEach(el => {
+      if (el instanceof HTMLElement) {
+        elements.push(el);
+      }
+    });
+    // Prompt menu - check if it's a popover (has trigger inside) or direct button
+    const promptMenu = this.querySelector('[slot="prompt-menu"]');
+    if (promptMenu) {
+      // Check for popover trigger inside (fabric-popover pattern)
+      const triggerButton = promptMenu.querySelector('[slot="popover-trigger"]');
+      if (triggerButton instanceof HTMLElement) {
+        elements.push(triggerButton);
+      } else if (promptMenu instanceof HTMLElement) {
+        // Direct button pattern
+        elements.push(promptMenu);
+      }
+    }
+    return elements;
+  }
+  /**
+   * Gets the currently focused element.
+   * @internal
+   */
+  getActiveElement() {
+    return document.activeElement;
+  }
+  /**
+   * Checks if the first tabbable element is currently focused.
+   * @internal
+   */
+  get isFirstElementFocused() {
+    const tabbables = this.getTabbableElements();
+    const active = this.getActiveElement();
+    return tabbables.length > 0 && active === tabbables[0];
+  }
+  /**
+   * Checks if the last tabbable element is currently focused.
+   * @internal
+   */
+  get isLastElementFocused() {
+    const tabbables = this.getTabbableElements();
+    const active = this.getActiveElement();
+    return tabbables.length > 0 && active === tabbables[tabbables.length - 1];
+  }
+  /**
+   * Enters the pill, making internal content keyboard-navigable and focusing the first element.
+   * @internal
+   */
+  enterPill() {
+    if (this.disabled) return;
+    this.isEntered = true;
+    this.restoreElementTabindexes();
+    // Focus first tabbable element
+    const tabbables = this.getTabbableElements();
+    if (tabbables.length > 0) {
+      tabbables[0].focus();
+    }
+  }
+  /**
+   * Exits the pill, removing internal elements from tab order and optionally focusing the host.
+   * @internal
+   */
+  exitPill(focusHost = false) {
+    this.isEntered = false;
+    this.removeElementsFromTabOrder();
+    if (focusHost) {
+      this.focus();
+    }
+  }
+  /**
+   * Focuses the first tabbable element inside the pill.
+   * @public
+   */
+  focusFirstElement() {
+    const tabbables = this.getTabbableElements();
+    if (tabbables.length > 0) {
+      tabbables[0].focus();
+    }
+  }
+  /**
+   * Focuses the last tabbable element inside the pill.
+   * @public
+   */
+  focusLastElement() {
+    const tabbables = this.getTabbableElements();
+    if (tabbables.length > 0) {
+      tabbables[tabbables.length - 1].focus();
+    }
+  }
+  /**
+   * Closes all open popovers within the pill.
+   * @internal
+   */
+  closeAllPopovers() {
+    const sensitivityPopover = this.getSensitivityPopover();
+    if (sensitivityPopover && sensitivityPopover.hasAttribute("popover") && "hidePopover" in sensitivityPopover) {
+      sensitivityPopover.hidePopover();
+    }
+    const promptMenuPopover = this.getPromptMenuPopover();
+    if (promptMenuPopover && promptMenuPopover.hasAttribute("popover") && "hidePopover" in promptMenuPopover) {
+      promptMenuPopover.hidePopover();
+    }
+  }
+  /**
+   * Handles toggle events from the sensitivity fabric-popover.
+   * @internal
+   * @deprecated Use automatic event delegation via handlePopoverToggle instead.
+   */
+  handleSensitivityPopoverToggle(event) {
+    const toggleEvent = event;
+    const isOpen = toggleEvent.newState === "open";
+    if (this.sensitivityOpen !== isOpen) {
+      this.sensitivityOpen = isOpen;
+      this.emitSensitivityToggle(isOpen);
+    }
+  }
+  /**
+   * Gets the sensitivity popover element if present.
+   * @internal
+   */
+  getSensitivityPopover() {
+    return this.querySelector('[slot="sensitivity"]');
+  }
+  /**
+   * Gets the prompt menu popover element if present.
+   * @internal
+   */
+  getPromptMenuPopover() {
+    return this.querySelector('[slot="prompt-menu"]');
+  }
+  /**
+   * Emits the sensitivity-toggle event.
+   * @internal
+   */
+  emitSensitivityToggle(open) {
+    this.sensitivityOpen = open;
+    this.dispatchEvent(new CustomEvent(ReferencePillEventNames["sensitivity-toggle"], {
+      detail: {
+        open
+      },
+      bubbles: true,
+      composed: true
+    }));
+  }
+  /**
+   * Emits the prompt-menu-toggle event when popover state changes.
+   * @internal
+   * @param open - Whether the popover is now open.
+   */
+  emitPromptMenuToggle(open) {
+    this.promptsOpen = open;
+    this.dispatchEvent(new CustomEvent(ReferencePillEventNames["prompt-menu-toggle"], {
+      detail: {
+        open
+      },
+      bubbles: true,
+      composed: true
+    }));
+  }
+}
+__decorate([attr({
+  mode: "boolean"
+})], ReferencePill.prototype, "disabled", void 0);
+__decorate([observable], ReferencePill.prototype, "promptsOpen", void 0);
+__decorate([observable], ReferencePill.prototype, "sensitivityOpen", void 0);
+
+export { ReferencePill };