docs: updated docs based on copilot recommendations

packages/button-group/src/ButtonGroup.ts

@@ -33,9 +33,16 @@ export class ButtonGroup extends SizedMixin(SpectrumElement, {
         return [styles];
     }
 
+    /**
+     * When true, the button group is displayed vertically.
+     */
     @property({ type: Boolean, reflect: true })
     public vertical = false;
 
+    /**
+     * Handles the slotchange event for the button group.
+     * Updates the size of the assigned button elements.
+     */
     protected handleSlotchange({
         target: slot,
     }: Event & { target: HTMLSlotElement }): void {
@@ -45,6 +52,10 @@ export class ButtonGroup extends SizedMixin(SpectrumElement, {
         });
     }
 
+    /**
+     * Renders the button group.
+     * Includes the slot for the button elements.
+     */
     protected override render(): TemplateResult {
         return html`
             <slot @slotchange=${this.handleSlotchange}></slot>

packages/button/src/Button.ts

@@ -21,15 +21,30 @@ import { ButtonBase } from './ButtonBase.js';
 import buttonStyles from './button.css.js';
 import { PendingStateController } from '@spectrum-web-components/reactive-controllers/src/PendingState.js';
 
+/**
+ * Type definition for deprecated button variants.
+ */
 export type DeprecatedButtonVariants = 'cta' | 'overBackground';
+
+/**
+ * Type definition for button static colors.
+ */
 export type ButtonStaticColors = 'white' | 'black';
+
+/**
+ * Type definition for button variants.
+ */
 export type ButtonVariants =
     | 'accent'
     | 'primary'
     | 'secondary'
     | 'negative'
     | ButtonStaticColors
     | DeprecatedButtonVariants;
+
+/**
+ * List of valid button variants.
+ */
 export const VALID_VARIANTS = [
     'accent',
     'primary',
@@ -38,8 +53,15 @@ export const VALID_VARIANTS = [
     'white',
     'black',
 ];
+
+/**
+ * List of valid static colors for buttons.
+ */
 export const VALID_STATIC_COLORS = ['white', 'black'];
 
+/**
+ * Type definition for button treatments.
+ */
 export type ButtonTreatments = 'fill' | 'outline';
 
 /**
@@ -53,30 +75,17 @@ export class Button extends SizedMixin(ButtonBase, { noDefaultSize: true }) {
         return [...super.styles, buttonStyles];
     }
 
+    /**
+     * The label to display when the button is in a pending state.
+     */
     @property({ type: String, attribute: 'pending-label' })
     public pendingLabel = 'Pending';
 
-    // Use this property to set the button into a pending state
-    @property({ type: Boolean, reflect: true, attribute: true })
-    public pending = false;
-
-    public pendingStateController: PendingStateController<this>;
-
     /**
-     * Initializes the `PendingStateController` for the Button component.
-     * The `PendingStateController` manages the pending state of the Button.
+     * Use this property to set the button into a pending state.
      */
-    constructor() {
-        super();
-        this.pendingStateController = new PendingStateController(this);
-    }
-
-    public override click(): void {
-        if (this.pending) {
-            return;
-        }
-        super.click();
-    }
+    @property({ type: Boolean, reflect: true, attribute: true })
+    public pending = false;
 
     /**
      * The visual variant to apply to this button.
@@ -185,6 +194,24 @@ export class Button extends SizedMixin(ButtonBase, { noDefaultSize: true }) {
         return this.treatment === 'outline';
     }
 
+    public pendingStateController: PendingStateController<this>;
+
+    /**
+     * Initializes the `PendingStateController` for the Button component.
+     * The `PendingStateController` manages the pending state of the Button.
+     */
+    constructor() {
+        super();
+        this.pendingStateController = new PendingStateController(this);
+    }
+
+    public override click(): void {
+        if (this.pending) {
+            return;
+        }
+        super.click();
+    }
+
     protected override firstUpdated(changes: PropertyValues<this>): void {
         super.firstUpdated(changes);
         // There is no Spectrum design context for an `<sp-button>` without a variant
@@ -198,6 +225,10 @@ export class Button extends SizedMixin(ButtonBase, { noDefaultSize: true }) {
         }
     }
 
+    /**
+     * Renders the button content.
+     * Includes the button content and the pending state.
+     */
     protected override renderButton(): TemplateResult {
         return html`
             ${this.buttonContent}

packages/button/src/ButtonBase.ts

@@ -36,8 +36,10 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         return [buttonStyles];
     }
 
-    // TODO we need to document this property for consumers,
-    // as it's not a 1:1 equivalent to active
+    /**
+     * Indicates whether the button is active.
+     * This is not a 1:1 equivalent to the active state.
+     */
     @property({ type: Boolean, reflect: true })
     public active = false;
 
@@ -58,10 +60,17 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         return this;
     }
 
+    /**
+     * Checks if the button has a label.
+     */
     protected get hasLabel(): boolean {
         return this.slotHasContent;
     }
 
+    /**
+     * Retrieves the content to be rendered inside the button.
+     * Includes the icon slot and the label slot.
+     */
     protected get buttonContent(): TemplateResult[] {
         const content = [
             html`
@@ -85,6 +94,11 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         });
     }
 
+    /**
+     * Handles the click event capture phase.
+     * Prevents the default action and stops propagation if the button is disabled.
+     * Proxies the click event if necessary.
+     */
     private handleClickCapture(event: Event): void | boolean {
         if (this.disabled) {
             event.preventDefault();
@@ -98,10 +112,17 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         }
     }
 
+    /**
+     * Proxies the focus event to the button element.
+     */
     private proxyFocus(): void {
         this.focus();
     }
 
+    /**
+     * Determines if the click event should be proxied.
+     * Proxies the click event to the anchor element or creates a proxy button element if necessary.
+     */
     private shouldProxyClick(): boolean {
         let handled = false;
         if (this.anchorElement) {
@@ -121,6 +142,10 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         return handled;
     }
 
+    /**
+     * Renders the anchor element for the button.
+     * Includes the button content and the anchor element.
+     */
     public override renderAnchor(): TemplateResult {
         return html`
             ${this.buttonContent}
@@ -132,18 +157,29 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         `;
     }
 
+    /**
+     * Renders the button content.
+     * Includes the button content.
+     */
     protected renderButton(): TemplateResult {
         return html`
             ${this.buttonContent}
         `;
     }
 
+    /**
+     * Renders the button or anchor element based on the href property.
+     */
     protected override render(): TemplateResult {
         return this.href && this.href.length > 0
             ? this.renderAnchor()
             : this.renderButton();
     }
 
+    /**
+     * Handles the keydown event for the button.
+     * Activates the button when the Space key is pressed.
+     */
     protected handleKeydown(event: KeyboardEvent): void {
         const { code } = event;
         switch (code) {
@@ -160,6 +196,10 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         }
     }
 
+    /**
+     * Handles the keypress event for the button.
+     * Activates the button or link when the Enter or NumpadEnter key is pressed.
+     */
     private handleKeypress(event: KeyboardEvent): void {
         const { code } = event;
         switch (code) {
@@ -173,6 +213,10 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         }
     }
 
+    /**
+     * Handles the keyup event for the button.
+     * Deactivates the button when the Space key is released.
+     */
     protected handleKeyup(event: KeyboardEvent): void {
         const { code } = event;
         switch (code) {
@@ -186,6 +230,10 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
         }
     }
 
+    /**
+     * Manages the role attribute for the anchor element.
+     * Sets the role to 'link' if the href property is set, otherwise sets it to 'button'.
+     */
     private manageAnchor(): void {
         // for a link
         if (this.href && this.href.length > 0) {
@@ -238,6 +286,7 @@ export class ButtonBase extends ObserveSlotText(LikeAnchor(Focusable), '', [
             this.anchorElement.tabIndex = -1;
         }
     }
+
     protected override update(changes: PropertyValues): void {
         super.update(changes);
         if (changes.has('label')) {

packages/button/src/ClearButton.ts

@@ -26,6 +26,9 @@ import '@spectrum-web-components/icons-ui/icons/sp-icon-cross300.js';
 import crossMediumStyles from '@spectrum-web-components/icon/src/spectrum-icon-cross.css.js';
 import crossMediumOverrides from '@spectrum-web-components/icon/src/icon-cross-overrides.css.js';
 
+/**
+ * A record of cross icon templates for different sizes.
+ */
 const crossIcon: Record<string, () => TemplateResult> = {
     s: () => html`
         <sp-icon-cross75
@@ -77,10 +80,18 @@ export class ClearButton extends SizedMixin(StyledButton, {
     @property({ reflect: true })
     public variant: 'overBackground' | '' = '';
 
+    /**
+     * Retrieves the content to be rendered inside the button.
+     * Includes the cross icon based on the button size.
+     */
     protected override get buttonContent(): TemplateResult[] {
         return [crossIcon[this.size]()];
     }
 
+    /**
+     * Renders the clear button.
+     * Wraps the button content in a div with class "fill".
+     */
     protected override render(): TemplateResult {
         return html`
             <div class="fill">${super.render()}</div>

packages/button/src/CloseButton.ts

@@ -27,6 +27,9 @@ import crossMediumStyles from '@spectrum-web-components/icon/src/spectrum-icon-c
 import crossMediumOverrides from '@spectrum-web-components/icon/src/icon-cross-overrides.css.js';
 import type { ButtonStaticColors } from './Button.js';
 
+/**
+ * A record of cross icon templates for different sizes.
+ */
 const crossIcon: Record<string, () => TemplateResult> = {
     s: () => html`
         <sp-icon-cross200
@@ -78,9 +81,16 @@ export class CloseButton extends SizedMixin(StyledButton, {
     @property({ reflect: true })
     public variant: ButtonStaticColors | '' = '';
 
+    /**
+     * The static color variant to use for this button.
+     */
     @property({ reflect: true, attribute: 'static-color' })
     public staticColor?: 'black' | 'white';
 
+    /**
+     * Retrieves the content to be rendered inside the button.
+     * Includes the cross icon based on the button size.
+     */
     protected override get buttonContent(): TemplateResult[] {
         return [crossIcon[this.size]()];
     }