CustomComponentAdapter interface presentation exported

export interface CustomComponentAdapter {
  /** Unique adapter name — stored in FormField.adapterName for fill-time lookup. */
  readonly name: AdapterName;

  /**
   * CSS selector that matches the component's root/wrapper element.
   * Used by the adapter registry to batch-query the DOM.
   */
  readonly selector: string;

  /**
   * Checks whether a DOM element actually belongs to this adapter.
   * Called after querySelectorAll(selector) to filter false positives.
   * Return `true` to claim the element for this adapter.
   */
  matches(element: HTMLElement): boolean;

  /**
   * Converts a matched wrapper element into a FormField stub.
   * Must set: element, selector, category, fieldType (as "unknown"),
   * and any relevant DOM metadata (label, options, placeholder, etc.).
   *
   * Classification is done downstream by the DetectionPipeline.
   */
  buildField(wrapper: HTMLElement): FormField;

  /**
   * Applies a value to the custom component.
   * Must trigger the component's own change events so frameworks (React, Vue, etc.)
   * pick up the change.
   *
   * Returns `true` if the value was successfully applied, `false` otherwise.
   * May be async for components that need to wait for dropdowns/panels to render.
   */
  fill(wrapper: HTMLElement, value: string): boolean | Promise<boolean>;

  /**
   * (Optional) Reads the current value from the custom component wrapper.
   * This is used when the user requests "Save form" so we can capture the
   * actual value instead of treating the wrapper as a generic <div>.
   * Returning `null` indicates the adapter cannot extract a value.
   */
  extractValue?(wrapper: HTMLElement): string | null;
}