feat: update link to use element internals custom states for presenta…

…tional styling (microsoft#31752)

change/@fluentui-web-components-45992585-e259-47e0-b8a2-2e3746e546f1.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat: update link to use Element Internals custom states for presentational attributes",
+  "packageName": "@fluentui/web-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/web-components/docs/api-report.md

@@ -2233,7 +2233,9 @@ export const lineHeightHero900 = "var(--lineHeightHero900)";
 // @public
 export class Link extends BaseAnchor {
     appearance?: LinkAppearance | undefined;
+    appearanceChanged(prev: LinkAppearance | undefined, next: LinkAppearance | undefined): void;
     inline: boolean;
+    inlineChanged(prev: boolean, next: boolean): void;
 }
 
 // @public

packages/web-components/src/anchor-button/anchor-button.ts

@@ -42,7 +42,7 @@ export class BaseAnchor extends FASTElement {
    *
    * @internal
    */
-  protected elementInternals: ElementInternals = this.attachInternals();
+  public elementInternals: ElementInternals = this.attachInternals();
 
   /**
    * The proxy anchor element

packages/web-components/src/link/link.spec.ts

@@ -1,6 +1,7 @@
 import { spinalCase } from '@microsoft/fast-web-utilities';
 import { expect, test } from '@playwright/test';
 import { fixtureURL } from '../helpers.tests.js';
+import { Link } from './link.js';
 
 const proxyAttributes = {
   href: 'href',
@@ -55,4 +56,36 @@ test.describe('Link', () => {
       await expect(proxy).toHaveAttribute(`${attribute}`, `${value}`);
     });
   }
+
+  test('should add a custom state matching the `appearance` attribute when provided', async ({ page }) => {
+    const element = page.locator('fluent-link');
+
+    await element.evaluate((node: Link) => {
+      node.appearance = 'subtle';
+    });
+
+    expect(await element.evaluate((node: Link) => node.elementInternals.states.has('subtle'))).toBe(true);
+
+    await element.evaluate((node: Link) => {
+      node.appearance = undefined;
+    });
+
+    expect(await element.evaluate((node: Link) => node.elementInternals.states.has('subtle'))).toBe(false);
+  });
+
+  test('should add a custom state of `inline` when true', async ({ page }) => {
+    const element = page.locator('fluent-link');
+
+    await element.evaluate((node: Link) => {
+      node.inline = true;
+    });
+
+    expect(await element.evaluate((node: Link) => node.elementInternals.states.has('inline'))).toBe(true);
+
+    await element.evaluate((node: Link) => {
+      node.inline = false;
+    });
+
+    expect(await element.evaluate((node: Link) => node.elementInternals.states.has('inline'))).toBe(false);
+  });
 });

packages/web-components/src/link/link.styles.ts

@@ -12,6 +12,7 @@ import {
   fontWeightRegular,
   strokeWidthThin,
 } from '../theme/design-tokens.js';
+import { subtleState } from '../styles/states/index.js';
 
 export const styles = css`
   ${display('inline')}
@@ -49,21 +50,21 @@ export const styles = css`
       color: ${colorBrandForegroundLinkPressed};
     }
 
-    :host([appearance='subtle']:hover) {
+    :host(${subtleState}:hover) {
       color: ${colorNeutralForeground2LinkHover};
     }
 
-    :host([appearance='subtle']:active) {
+    :host(${subtleState}:active) {
       color: ${colorNeutralForeground2LinkPressed};
     }
   }
 
-  :host([appearance='subtle']) {
+  :host(${subtleState}) {
     color: ${colorNeutralForeground2Link};
   }
 
   :host-context(:is(h1, h2, h3, h4, h5, h6, p, fluent-text)),
-  :host([inline]) {
+  :host(:is([state--inline], :state(inline))) {
     font: inherit;
     text-decoration: underline;
   }

packages/web-components/src/link/link.ts

@@ -1,5 +1,6 @@
 import { attr } from '@microsoft/fast-element';
 import { BaseAnchor } from '../anchor-button/anchor-button.js';
+import { toggleState } from '../utils/element-internals.js';
 import { type LinkAppearance } from './link.options.js';
 
 /**
@@ -23,6 +24,20 @@ export class Link extends BaseAnchor {
   @attr
   public appearance?: LinkAppearance | undefined;
 
+  /**
+   * Handles changes to appearance attribute custom states
+   * @param prev - the previous state
+   * @param next - the next state
+   */
+  public appearanceChanged(prev: LinkAppearance | undefined, next: LinkAppearance | undefined) {
+    if (prev) {
+      toggleState(this.elementInternals, `${prev}`, false);
+    }
+    if (next) {
+      toggleState(this.elementInternals, `${next}`, true);
+    }
+  }
+
   /**
    * The link is inline with text
    * In chromium browsers, if the link is contained within a semantic
@@ -35,4 +50,13 @@ export class Link extends BaseAnchor {
    */
   @attr({ mode: 'boolean' })
   public inline: boolean = false;
+
+  /**
+   * Handles changes to inline attribute custom states
+   * @param prev - the previous state
+   * @param next - the next state
+   */
+  public inlineChanged(prev: boolean, next: boolean) {
+    toggleState(this.elementInternals, 'inline', next);
+  }
 }