/**
 * Represents the attributes of an HTML `<link>` element.
 *
 * @see [HTML link element](https://developer.mozilla.org/docs/Web/HTML/Element/link)
 * @see {@link Link}
 *
 * @publicApi
 */
export type LinkDefinition = {
  as?: string;
  blocking?: string;
  charset?: string;           // deprecated in HTML5, retained for legacy
  crossorigin?: string;
  disabled?: string;
  fetchpriority?: string;
  href?: string;
  hreflang?: string;
  imagesizes?: string;
  imagesrcset?: string;
  integrity?: string;
  media?: string;
  nonce?: string;
  referrerpolicy?: string;
  rel?: string;
  rev?: string;               // deprecated in HTML5, retained for legacy
  sizes?: string;
  target?: string;            // deprecated in HTML5, retained for legacy
  title?: string;
  type?: string;
} & {
  [prop: string]: string;
};

/**
 * A service for managing HTML `<link>` tags.
 *
 * Properties of the `LinkDefinition` object match the attributes of the
 * HTML `<link>` tag. These tags are used for canonical URLs, stylesheets,
 * preload/prefetch hints, Web App Manifest references, and more.
 *
 * To identify specific `<link>` tags in a document, use an attribute selection
 * string in the format `"tag_attribute='value string'"`.
 * For example, an `attrSelector` value of `"rel='canonical'"` matches a tag
 * whose `rel` attribute has the value `"canonical"`.
 * Selectors are used with the `querySelector()` Document method,
 * in the format `link[{attrSelector}]`.
 *
 * @see [HTML link element](https://developer.mozilla.org/docs/Web/HTML/Element/link)
 * @see [Document.querySelector()](https://developer.mozilla.org/docs/Web/API/Document/querySelector)
 *
 * @publicApi
 */
@Injectable({ providedIn: 'root' })
export class Link {
  /**
   * Retrieves or creates a specific `<link>` tag element in the current HTML document.
   * @param tag The definition of a `<link>` element to match or create.
   * @param forceCreation True to create a new element without checking whether one already exists.
   */
  addTag(tag: LinkDefinition, forceCreation?: boolean): HTMLLinkElement | null;

  /**
   * Retrieves or creates a set of `<link>` tag elements in the current HTML document.
   */
  addTags(tags: LinkDefinition[], forceCreation?: boolean): HTMLLinkElement[];

  /**
   * Retrieves a `<link>` tag element in the current HTML document.
   * @param attrSelector The tag attribute and value to match against, in the format
   * `"tag_attribute='value string'"`.
   */
  getTag(attrSelector: string): HTMLLinkElement | null;

  /**
   * Retrieves a set of `<link>` tag elements in the current HTML document.
   */
  getTags(attrSelector: string): HTMLLinkElement[];

  /**
   * Modifies an existing `<link>` tag element in the current HTML document,
   * or creates a new one if not found.
   */
  updateTag(tag: LinkDefinition, selector?: string): HTMLLinkElement | null;

  /**
   * Removes an existing `<link>` tag element from the current HTML document.
   */
  removeTag(attrSelector: string): void;

  /**
   * Removes a specific `<link>` element from the DOM.
   */
  removeTagElement(link: HTMLLinkElement): void;
}

readonly link = inject(Link);

// Canonical URL
this.link.addTag({ rel: 'canonical', href: 'https://example.com/page' });

// Preload a critical font
this.link.addTag({
  rel: 'preload',
  as: 'font',
  type: 'font/woff2',
  href: '/fonts/brand.woff2',
  crossorigin: 'anonymous',
});

// Update canonical — no duplicate is created
this.link.updateTag({ rel: 'canonical', href: 'https://example.com/new-page' });

// Remove a stylesheet
this.link.removeTag('rel="stylesheet"');