feat(icon-button): add new pressed property/attribute and deprecate on property

src/dev/pages/switch/switch.ejs

@@ -37,7 +37,7 @@
 
   <div>
     <h3 class="forge-typography--heading2">Disabled (checked)</h3>
-    <forge-switch disabled selected>off/on</forge-switch>
+    <forge-switch disabled checked>off/on</forge-switch>
   </div>
 
   <div>

src/lib/icon-button/icon-button-constants.ts

@@ -4,6 +4,8 @@ const elementName: keyof HTMLElementTagNameMap = `${COMPONENT_NAME_PREFIX}icon-b
 
 const observedAttributes = {
   TOGGLE: 'toggle',
+  PRESSED: 'pressed',
+  /** @deprecated use `PRESSED` instead. */
   ON: 'on',
   VARIANT: 'variant',
   THEME: 'theme',

src/lib/icon-button/icon-button-core.ts

@@ -4,7 +4,7 @@ import { IconButtonDensity, IconButtonShape, IconButtonTheme, IconButtonVariant,
 
 export interface IIconButtonCore extends IBaseButtonCore {
   toggle: boolean;
-  on: boolean;
+  pressed: boolean;
   variant: IconButtonVariant;
   theme: IconButtonTheme;
   shape: IconButtonShape;
@@ -13,7 +13,7 @@ export interface IIconButtonCore extends IBaseButtonCore {
 
 export class IconButtonCore extends BaseButtonCore<IIconButtonAdapter> implements IIconButtonCore {
   private _toggle = false;
-  private _on = false;
+  private _pressed = false;
   private _variant: IconButtonVariant = ICON_BUTTON_CONSTANTS.defaults.DEFAULT_VARIANT;
   private _theme: IconButtonTheme = ICON_BUTTON_CONSTANTS.defaults.DEFAULT_THEME;
   private _shape: IconButtonShape = ICON_BUTTON_CONSTANTS.defaults.DEFAULT_SHAPE;
@@ -37,17 +37,17 @@ export class IconButtonCore extends BaseButtonCore<IIconButtonAdapter> implement
 
   private _onToggle(): void {
     // Update internal state first so listeners can access the new state
-    const originalOn = this._on;
-    this._on = !this._on;
+    const originalPressed = this._pressed;
+    this._pressed = !this._pressed;
 
-    const cancelled = !this._adapter.emitHostEvent(ICON_BUTTON_CONSTANTS.events.TOGGLE, this.on, true, true);
-    this._on = originalOn;
+    const cancelled = !this._adapter.emitHostEvent(ICON_BUTTON_CONSTANTS.events.TOGGLE, this.pressed, true, true);
+    this._pressed = originalPressed;
 
     if (cancelled) {
       return;
     }
 
-    this.on = !originalOn;
+    this.pressed = !originalPressed;
   }
 
   public get toggle(): boolean {
@@ -57,26 +57,29 @@ export class IconButtonCore extends BaseButtonCore<IIconButtonAdapter> implement
     value = !!value;
     if (this._toggle !== value) {
       this._toggle = value;
-      this._adapter.toggleHostAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED, this._toggle, `${this._on}`);
+      this._adapter.toggleHostAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED, this._toggle, `${this._pressed}`);
       this._adapter.toggleHostAttribute(ICON_BUTTON_CONSTANTS.attributes.TOGGLE, this._toggle);
     }
   }
 
-  public get on(): boolean {
-    return this._on;
+  public get pressed(): boolean {
+    return this._pressed;
   }
-  public set on(value: boolean) {
+  public set pressed(value: boolean) {
     value = !!value;
-    if (this._on !== value) {
-      this._on = value;
+    if (this._pressed !== value) {
+      this._pressed = value;
 
       if (this._toggle) {
-        this._adapter.setHostAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED, `${this._on}`);
+        this._adapter.setHostAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED, `${this._pressed}`);
       } else {
         this._adapter.removeHostAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED);
       }
 
-      this._adapter.toggleHostAttribute(ICON_BUTTON_CONSTANTS.attributes.ON, this._on);
+      this._adapter.toggleHostAttribute(ICON_BUTTON_CONSTANTS.attributes.PRESSED, this._pressed);
+
+      // Deprecated but left for legacy support
+      this._adapter.toggleHostAttribute(ICON_BUTTON_CONSTANTS.attributes.ON, this._pressed);
     }
   }
 

src/lib/icon-button/icon-button.scss

@@ -126,49 +126,49 @@ forge-state-layer {
 // Toggle
 //
 
-:host(:is(:not([toggle]), [toggle]:not([on]))) {
+:host(:is(:not([toggle]), [toggle]:not([pressed]))) {
   slot[name='on'] {
     display: none;
   }
 }
 
-:host([toggle][on]) {
+:host([toggle][pressed]) {
   slot:not([name]) {
     display: none;
   }
 }
 
-:host([toggle][on]:is(:not([variant]), [variant='icon'])) {
+:host([toggle][pressed]:is(:not([variant]), [variant='icon'])) {
   .forge-icon-button {
     @include toggle-on-icon;
   }
 }
 
-:host([toggle][on][variant='outlined']) {
+:host([toggle][pressed][variant='outlined']) {
   .forge-icon-button {
     @include toggle-on-outlined;
   }
 }
 
-:host([toggle]:not([on])[variant='tonal']) {
+:host([toggle]:not([pressed])[variant='tonal']) {
   .forge-icon-button {
     @include toggle-tonal;
   }
 }
 
-:host([toggle][on][variant='tonal']) {
+:host([toggle][pressed][variant='tonal']) {
   .forge-icon-button {
     @include toggle-on-tonal;
   }
 }
 
-:host([toggle]:not([on]):is([variant='filled'], [variant='raised'])) {
+:host([toggle]:not([pressed]):is([variant='filled'], [variant='raised'])) {
   .forge-icon-button {
     @include toggle-filled;
   }
 }
 
-:host([toggle][on]:is([variant='filled'], [variant='raised'])) {
+:host([toggle][pressed]:is([variant='filled'], [variant='raised'])) {
   .forge-icon-button {
     @include toggle-on-filled;
   }
@@ -318,7 +318,7 @@ forge-state-layer {
     }
 
     // Toggle + tonal variant
-    :host([toggle]:not([on])[theme='#{$theme}'][variant='tonal']) {
+    :host([toggle]:not([pressed])[theme='#{$theme}'][variant='tonal']) {
       .forge-icon-button {
         @include override(background-color, theme.variable(#{$theme}-container), value);
       }
@@ -341,7 +341,7 @@ forge-state-layer {
     }
 
     // Toggle + filled & raised variants
-    :host([toggle]:not([on])[theme='#{$theme}']:is([variant='filled'], [variant='raised'])) {
+    :host([toggle]:not([pressed])[theme='#{$theme}']:is([variant='filled'], [variant='raised'])) {
       .forge-icon-button {
         @include override(icon-color, theme.variable($theme), value);
         @include override(background-color, theme.variable(#{$theme}-container), value);

src/lib/icon-button/icon-button.test.ts

@@ -25,6 +25,7 @@ describe('Icon Button', () => {
     const el = await fixture<IIconButtonComponent>(html`<forge-icon-button>${DEFAULT_ICON}</forge-icon-button>`);
 
     expect(el.toggle).to.be.false;
+    expect(el.pressed).to.be.false;
     expect(el.on).to.be.false;
   });
 
@@ -196,6 +197,7 @@ describe('Icon Button', () => {
   it('should not be on by default', async () => {
     const el = await fixture<IIconButtonComponent>(html`<forge-icon-button toggle>${DEFAULT_ICON}</forge-icon-button>`);
 
+    expect(el.pressed).to.be.false;
     expect(el.on).to.be.false;
     expect(el.getAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.equal('false');
   });
@@ -205,15 +207,17 @@ describe('Icon Button', () => {
 
     el.click();
 
+    expect(el.pressed).to.be.true;
     expect(el.on).to.be.true;
     expect(el.getAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.equal('true');
   });
 
-  it('should toggle on click when on is set', async () => {
-    const el = await fixture<IIconButtonComponent>(html`<forge-icon-button toggle on>${DEFAULT_ICON}</forge-icon-button>`);
+  it('should toggle on click when pressed is set', async () => {
+    const el = await fixture<IIconButtonComponent>(html`<forge-icon-button toggle pressed>${DEFAULT_ICON}</forge-icon-button>`);
 
     el.click();
 
+    expect(el.pressed).to.be.false;
     expect(el.on).to.be.false;
     expect(el.getAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.equal('false');
   });
@@ -223,14 +227,16 @@ describe('Icon Button', () => {
 
     el.click();
 
+    expect(el.pressed).to.be.false;
     expect(el.on).to.be.false;
     expect(el.getAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.equal('false');
   });
 
-  it('should not toggle to on when toggle event cancelled', async () => {
+  it('should not toggle to pressed when toggle event cancelled', async () => {
     const el = await fixture<IIconButtonComponent>(html`<forge-icon-button toggle>${DEFAULT_ICON}</forge-icon-button>`);
     const clickSpy = spy((evt: CustomEvent<boolean>) => evt.preventDefault());
 
+    expect(el.pressed).to.be.false;
     expect(el.on).to.be.false;
     expect(el.getAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.equal('false');
 
@@ -239,6 +245,7 @@ describe('Icon Button', () => {
     await elementUpdated(el);
 
     expect(clickSpy).to.be.calledOnce;
+    expect(el.pressed).to.be.false;
     expect(el.on).to.be.false;
     expect(el.getAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.equal('false');
   });
@@ -247,6 +254,7 @@ describe('Icon Button', () => {
     const el = await fixture<IIconButtonComponent>(html`<forge-icon-button toggle on>${DEFAULT_ICON}</forge-icon-button>`);
     const clickSpy = spy((evt: CustomEvent<boolean>) => evt.preventDefault());
 
+    expect(el.pressed).to.be.true;
     expect(el.on).to.be.true;
     expect(el.getAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.equal('true');
 
@@ -255,24 +263,27 @@ describe('Icon Button', () => {
     await elementUpdated(el);
 
     expect(clickSpy).to.be.calledOnce;
+    expect(el.pressed).to.be.true;
     expect(el.on).to.be.true;
     expect(el.getAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.equal('true');
   });
 
-  it('should not enable toggle if on is set while toggle is off', async () => {
-    const el = await fixture<IIconButtonComponent>(html`<forge-icon-button on>${DEFAULT_ICON}</forge-icon-button>`);
+  it('should not enable toggle if pressed is set while toggle is off', async () => {
+    const el = await fixture<IIconButtonComponent>(html`<forge-icon-button pressed>${DEFAULT_ICON}</forge-icon-button>`);
 
     expect(el.toggle).to.be.false;
+    expect(el.pressed).to.be.true;
     expect(el.on).to.be.true;
     expect(el.hasAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.be.false;
   });
 
-  it('should remove aria-pressed if on is set while toggle is off', async () => {
-    const el = await fixture<IIconButtonComponent>(html`<forge-icon-button on aria-pressed="true">${DEFAULT_ICON}</forge-icon-button>`);
+  it('should remove aria-pressed if pressed is set while toggle is off', async () => {
+    const el = await fixture<IIconButtonComponent>(html`<forge-icon-button pressed aria-pressed="true">${DEFAULT_ICON}</forge-icon-button>`);
 
-    el.on = false;
+    el.pressed = false;
 
     expect(el.toggle).to.be.false;
+    expect(el.pressed).to.be.false;
     expect(el.on).to.be.false;
     expect(el.hasAttribute(ICON_BUTTON_CONSTANTS.attributes.ARIA_PRESSED)).to.be.false;
   });

src/lib/icon-button/icon-button.ts

@@ -13,6 +13,8 @@ import styles from './icon-button.scss';
 
 export interface IIconButtonComponent extends IBaseButton {
   toggle: boolean;
+  pressed: boolean;
+  /** @deprecated use `pressed` instead. */
   on: boolean;
   variant: IconButtonVariant;
   theme: IconButtonTheme;
@@ -33,39 +35,10 @@ declare global {
 /**
  * @tag forge-icon-button
  *
- * @summary Icons buttons are used to trigger an action or event.
- *
- * @property {boolean} [toggle=false] - Whether or not the icon button can be toggled.
- * @property {boolean} [on=false] - Whether or not the button is on. Only applies when `toggle` is `true`.
- * @property {IconButtonVariant} [variant="icon"] - The variant of the button. Valid values are `text`, `outlined`, `filled`, and `raised`.
- * @property {IconButtonTheme} [theme="default"] - The theme of the button. Valid values are `default`, `primary`, `secondary`, `tertiary`, `success`, `error`, `warning`, `info`.
- * @property {string} [shape="circular"] - The shape of the button. Valid values are `circular` and `squared`.
- * @property {IconButtonDensity} [density="large"] - The density of the button. Valid values are `small`, `medium`, and `large`.
- * @property {string} [type="button"] - The type of button. Defaults to `button`. Valid values are `button`, `submit`, and `reset`.
- * @property {boolean} [disabled=false] - Whether or not the button is disabled.
- * @property {boolean} [popoverIcon=false] - Whether or not the button shows a built-in popover icon.
- * @property {boolean} [dense=false] - Whether or not the button is dense.
- * @property {string} name - The name of the button.
- * @property {string} value - The form value of the button.
- * @property {HTMLFormElement | null} form - The form reference of the button if within a `<form>` element.
- *
  * @globalconfig variant
  * @globalconfig shape
  * @globalconfig density
  *
- * @attribute {boolean} [toggle=false] - Whether or not the icon button can be toggled.
- * @attribute {boolean} [on=false] - Whether or not the button is on. Only applies when `toggle` is `true`.
- * @attribute {IconButtonVariant} [variant="icon"] - The variant of the button. Valid values are `text`, `outlined`, `filled`, and `raised`.
- * @attribute {IconButtonTheme} [theme="default"] - The theme of the button. Valid values are `default`, `primary`, `secondary`, `tertiary`, `success`, `error`, `warning`, `info`.
- * @attribute {string} [shape="circular"] - The shape of the button. Valid values are `circular` and `squared`.
- * @attribute {IconButtonDensity} [density="large"] - The density of the button. Valid values are `small`, `medium`, and `large`.
- * @attribute {string} [type="button"] - The type of button. Defaults to `button`. Valid values are `button`, `submit`, and `reset`.
- * @attribute {boolean} [disabled=false] - Whether or not the button is disabled.
- * @attribute {boolean} [popover-icon=false] - Whether or not the button shows a built-in popover icon.
- * @attribute {boolean} [dense=false] - Whether or not the button is dense.
- * @attribute {string} name - The name of the button.
- * @attribute {string} value - The form value of the button.
- *
  * @event {PointerEvent} click - Fires when the button is clicked.
  * @event {CustomEvent<boolean>} forge-icon-button-toggle - Fires when the icon button is toggled. Only applies in `toggle` mode.
  *
@@ -161,8 +134,9 @@ export class IconButtonComponent extends BaseButton<IconButtonCore> implements I
       case ICON_BUTTON_CONSTANTS.attributes.TOGGLE:
         this.toggle = coerceBoolean(newValue);
         break;
+      case ICON_BUTTON_CONSTANTS.attributes.PRESSED:
       case ICON_BUTTON_CONSTANTS.attributes.ON:
-        this.on = coerceBoolean(newValue);
+        this.pressed = coerceBoolean(newValue);
         break;
       case ICON_BUTTON_CONSTANTS.attributes.VARIANT:
         this.variant = newValue as IconButtonVariant;
@@ -180,21 +154,53 @@ export class IconButtonComponent extends BaseButton<IconButtonCore> implements I
     super.attributeChangedCallback(name, oldValue, newValue);
   }
 
+  /**
+   * Whether or not the icon button can be toggled.
+   * @default false
+   */
   @coreProperty()
   public declare toggle: boolean;
 
+  /**
+   * Whether or not the toggle button is pressed. Only applies when `toggle` is `true`.
+   * @default false
+   */
   @coreProperty()
+  public declare pressed: boolean;
+
+  /**
+   * Alias for `pressed` _(deprecated)_. Whether or not the toggle button is pressed. Only applies when `toggle` is `true`.
+   * @default false
+   * @deprecated Use `pressed` instead.
+   */
+  @coreProperty({ name: 'pressed' })
   public declare on: boolean;
 
+  /**
+   * The variant of the button. Valid values are `text`, `outlined`, `filled`, and `raised`.
+   * @default "default"
+   */
   @coreProperty()
   public declare theme: IconButtonTheme;
 
+  /**
+   * The variant of the button. Valid values are `text`, `outlined`, `filled`, and `raised`.
+   * @default "icon"
+   */
   @coreProperty()
   public declare variant: IconButtonVariant;
 
+  /**
+   * The shape of the button. Valid values are `circular` and `squared`.
+   * @default "circular"
+   */
   @coreProperty()
   public declare shape: IconButtonShape;
 
+  /**
+   * The density of the button. Valid values are `small`, `medium`, and `large`.
+   * @default "large"
+   */
   @coreProperty()
   public declare density: IconButtonDensity;
 }