Utilities

/**
 * Retrieves the "composed parent" element of a node, ignoring DOM tree boundaries
 * When the parent of a node is a shadow-root, it will return the host element
 * @param element - The element for which to retrieve the composed parent
 * @returns The composed parent element or null
 */
function composedParent<T extends HTMLElement>(element: T): HTMLElement | null;

/**
 * Determines if the reference element contains the test element in a "composed" DOM tree
 * Returns true if the test element is a descendant of the reference, including through shadow DOM
 * @param reference - The element to test for containment against
 * @param test - The element being tested for containment
 * @returns True if test is contained within reference's composed tree
 */
function composedContains(reference: HTMLElement, test: HTMLElement): boolean;

import { composedParent, composedContains } from "@microsoft/fast-element/utilities.js";

// Navigate composed DOM tree
function findComposedAncestor(element: HTMLElement, selector: string): HTMLElement | null {
  let current = composedParent(element);
  
  while (current) {
    if (current.matches(selector)) {
      return current;
    }
    current = composedParent(current);
  }
  
  return null;
}

// Check composed containment
function isChildOfDialog(element: HTMLElement, dialog: HTMLElement): boolean {
  return composedContains(dialog, element);
}

// Handle events across shadow boundaries
function handleComposedClick(event: Event) {
  const target = event.target as HTMLElement;
  const container = document.querySelector('.app-container') as HTMLElement;
  
  if (composedContains(container, target)) {
    console.log('Click occurred within app container (including shadow DOM)');
  }
}

/**
 * An extension of MutationObserver that supports unobserving specific nodes
 */
class UnobservableMutationObserver extends MutationObserver {
  /**
   * Creates an instance of UnobservableMutationObserver
   * @param callback - The callback to invoke when observed nodes are changed
   */
  constructor(callback: MutationCallback);
  
  /**
   * Observe a target node for changes
   * @param target - The node to observe
   * @param options - Mutation observer options
   */
  observe(target: Node, options?: MutationObserverInit): void;
  
  /**
   * Stop observing a specific target node
   * @param target - The node to stop observing
   */
  unobserve(target: Node): void;
}

import { UnobservableMutationObserver } from "@microsoft/fast-element/utilities.js";

// Create selective mutation observer
const observer = new UnobservableMutationObserver((mutations) => {
  mutations.forEach(mutation => {
    console.log('Mutation observed:', mutation.type, mutation.target);
  });
});

// Observe multiple elements
const elements = document.querySelectorAll('.watched-element');
elements.forEach(element => {
  observer.observe(element, {
    childList: true,
    attributes: true,
    subtree: true
  });
});

// Later, selectively stop observing some elements
function stopWatchingElement(element: Element) {
  observer.unobserve(element);
  console.log('Stopped watching element');
}

// The observer automatically disconnects when no nodes are being observed

/**
 * Bridges between ViewBehaviors and HostBehaviors, enabling a host to control ViewBehaviors
 */
interface ViewBehaviorOrchestrator<TSource = any, TParent = any> 
  extends ViewController<TSource, TParent>, HostBehavior<TSource> {
  
  /**
   * Adds a target node with associated structural ID
   * @param nodeId - The structural id of the DOM node
   * @param target - The DOM node associated with the id
   */
  addTarget(nodeId: string, target: Node): void;
  
  /**
   * Adds a behavior to be managed
   * @param behavior - The behavior to add
   */
  addBehavior(behavior: ViewBehavior): void;
  
  /**
   * Adds a behavior factory that will create behaviors for a target
   * @param factory - The behavior factory to add
   * @param target - The target the factory will create behaviors for
   */
  addBehaviorFactory(factory: ViewBehaviorFactory, target: Node): void;
}

/**
 * Factory for creating ViewBehaviorOrchestrator instances
 */
const ViewBehaviorOrchestrator: {
  /**
   * Creates a ViewBehaviorOrchestrator
   * @param source - The source to associate behaviors with
   * @returns A ViewBehaviorOrchestrator instance
   */
  create<TSource = any, TParent = any>(source: TSource): ViewBehaviorOrchestrator<TSource, TParent>;
};

import { ViewBehaviorOrchestrator } from "@microsoft/fast-element/utilities.js";
import { FASTElement, customElement, html, ViewBehavior } from "@microsoft/fast-element";

// Custom behavior that needs orchestration
class CustomHighlightBehavior implements ViewBehavior {
  private element: HTMLElement;
  
  constructor(private color: string) {}
  
  bind(controller: ViewController): void {
    this.element = controller.targets['highlight-target'] as HTMLElement;
    this.element.style.backgroundColor = this.color;
  }
  
  unbind(): void {
    if (this.element) {
      this.element.style.backgroundColor = '';
    }
  }
}

@customElement("orchestrated-component")
export class OrchestratedComponent extends FASTElement {
  private orchestrator: ViewBehaviorOrchestrator<this>;
  
  connectedCallback() {
    super.connectedCallback();
    
    // Create orchestrator
    this.orchestrator = ViewBehaviorOrchestrator.create(this);
    
    // Add targets
    const highlightTarget = this.shadowRoot!.querySelector('.highlight-area')!;
    this.orchestrator.addTarget('highlight-target', highlightTarget);
    
    // Add behaviors
    this.orchestrator.addBehavior(new CustomHighlightBehavior('yellow'));
    
    // Connect orchestrator
    this.orchestrator.connectedCallback(this.$fastController);
  }
  
  disconnectedCallback() {
    super.disconnectedCallback();
    this.orchestrator?.disconnectedCallback(this.$fastController);
  }
}

interface ViewBehaviorOrchestrator<TSource = any, TParent = any> {
  readonly source: TSource;
  readonly context: ExecutionContext<TParent>;
  readonly targets: ViewBehaviorTargets;
  readonly isBound: boolean;
}