feat(block, block-section): add expanded property and deprecate open property

packages/calcite-components/src/components/block-section/block-section.e2e.ts

@@ -20,6 +20,10 @@ describe("calcite-block-section", () => {
         propertyName: "open",
         value: true,
       },
+      {
+        propertyName: "expanded",
+        value: true,
+      },
     ]);
   });
 
@@ -29,6 +33,10 @@ describe("calcite-block-section", () => {
         propertyName: "open",
         defaultValue: false,
       },
+      {
+        propertyName: "expanded",
+        defaultValue: false,
+      },
       {
         propertyName: "toggleDisplay",
         defaultValue: "button",
@@ -43,7 +51,7 @@ describe("calcite-block-section", () => {
   describe("setFocus", () => {
     describe("focuses toggle switch", () => {
       focusable(
-        html`<calcite-block-section text="text" toggle-display="switch" open>
+        html`<calcite-block-section text="text" toggle-display="switch" expanded>
           <div>some content</div>
         </calcite-block-section>`,
         {
@@ -54,7 +62,7 @@ describe("calcite-block-section", () => {
 
     describe("focuses toggle button", () => {
       focusable(
-        html`<calcite-block-section text="text" toggle-display="button" open>
+        html`<calcite-block-section text="text" toggle-display="button" expanded>
           <div>some content</div>
         </calcite-block-section>`,
         {
@@ -67,13 +75,13 @@ describe("calcite-block-section", () => {
   describe("toggle-display = 'switch'", () => {
     describe("accessible", () => {
       accessible(html`
-        <calcite-block-section text="text" toggle-display="switch" open>
+        <calcite-block-section text="text" toggle-display="switch" expanded>
           <div>some content</div>
         </calcite-block-section>
       `);
     });
 
-    describe("accessible: when closed", () => {
+    describe("accessible: when collapsed", () => {
       accessible(html`
         <calcite-block-section text="text" toggle-display="switch">
           <div>some content</div>
@@ -96,7 +104,7 @@ describe("calcite-block-section", () => {
 
     it("renders section text", async () => {
       const page = await newE2EPage({
-        html: `<calcite-block-section text="test text" open toggle-display="switch"></calcite-block-section>`,
+        html: `<calcite-block-section text="test text" expanded toggle-display="switch"></calcite-block-section>`,
       });
       const element = await page.find(`calcite-block-section >>> .${CSS.toggle}`);
       expect(element.textContent).toBe("test text");
@@ -105,11 +113,11 @@ describe("calcite-block-section", () => {
 
   describe("toggle-display = 'button' (default)", () => {
     describe("accessible", () => {
-      describe("accessible: when open", () => {
-        accessible(html`<calcite-block-section text="text" open><div>some content</div></calcite-block-section>`);
+      describe("accessible: when expanded", () => {
+        accessible(html`<calcite-block-section text="text" expanded><div>some content</div></calcite-block-section>`);
       });
 
-      describe("accessible: when closed", () => {
+      describe("accessible: when collapsed", () => {
         accessible(html`<calcite-block-section text="text"><div>some content</div></calcite-block-section>`);
       });
     });
@@ -126,6 +134,24 @@ describe("calcite-block-section", () => {
     });
   });
 
+  // Broader functionality related to the 'expanded' prop is covered in the `expanded` tests.
+  it("should map deprecated 'open' prop to 'expanded' prop", async () => {
+    const page = await newE2EPage({
+      html: html`<calcite-block-section></calcite-block-section>`,
+    });
+    const blockSection = await page.find("calcite-block-section");
+
+    expect(await blockSection.getProperty("expanded")).toBe(false);
+
+    blockSection.setProperty("open", true);
+    await page.waitForChanges();
+    expect(await blockSection.getProperty("expanded")).toBe(true);
+
+    blockSection.setProperty("open", false);
+    await page.waitForChanges();
+    expect(await blockSection.getProperty("expanded")).toBe(false);
+  });
+
   describe("status = 'invalid'", () => {
     it("displays a status indicator when `status` is an accepted value", async () => {
       const page = await newE2EPage({
@@ -153,17 +179,17 @@ describe("calcite-block-section", () => {
 
     expect(await content.isVisible()).toBe(false);
 
-    element.setProperty("open", true);
+    element.setProperty("expanded", true);
     await page.waitForChanges();
-    element = await page.find("calcite-block-section[open]");
+    element = await page.find("calcite-block-section[expanded]");
     content = await page.find(`calcite-block-section >>> .${CSS.content}`);
 
     expect(element).toBeTruthy();
     expect(await content.isVisible()).toBe(true);
 
-    element.setProperty("open", false);
+    element.setProperty("expanded", false);
     await page.waitForChanges();
-    element = await page.find("calcite-block-section[open]");
+    element = await page.find("calcite-block-section[expanded]");
     content = await page.find(`calcite-block-section >>> .${CSS.content}`);
 
     expect(element).toBeNull();
@@ -181,13 +207,13 @@ describe("calcite-block-section", () => {
     await toggle.click();
 
     expect(toggleSpy).toHaveReceivedEventTimes(expectedClickEvents++);
-    expect(await element.getProperty("open")).toBe(true);
+    expect(await element.getProperty("expanded")).toBe(true);
     expect(toggle.getAttribute("aria-expanded")).toBe("true");
 
     await toggle.click();
 
     expect(toggleSpy).toHaveReceivedEventTimes(expectedClickEvents++);
-    expect(await element.getProperty("open")).toBe(false);
+    expect(await element.getProperty("expanded")).toBe(false);
     expect(toggle.getAttribute("aria-expanded")).toBe("false");
 
     if ((await element.getProperty("toggleDisplay")) === "switch") {
@@ -196,13 +222,13 @@ describe("calcite-block-section", () => {
       await switchToggle.click();
 
       expect(toggleSpy).toHaveReceivedEventTimes(expectedClickEvents++);
-      expect(await element.getProperty("open")).toBe(true);
+      expect(await element.getProperty("expanded")).toBe(true);
       expect(toggle.getAttribute("aria-expanded")).toBe("true");
 
       await switchToggle.click();
 
       expect(toggleSpy).toHaveReceivedEventTimes(expectedClickEvents++);
-      expect(await element.getProperty("open")).toBe(false);
+      expect(await element.getProperty("expanded")).toBe(false);
       expect(toggle.getAttribute("aria-expanded")).toBe("false");
     }
 
@@ -224,22 +250,22 @@ describe("calcite-block-section", () => {
     await page.waitForChanges();
 
     expect(toggleSpy).toHaveReceivedEventTimes(expectedClickEvents++);
-    expect(await element.getProperty("open")).toBe(true);
+    expect(await element.getProperty("expanded")).toBe(true);
     expect(toggle.getAttribute("aria-expanded")).toBe("true");
 
     await keyboardToggleEmitter.press("Enter");
     await page.waitForChanges();
 
     expect(toggleSpy).toHaveReceivedEventTimes(expectedClickEvents++);
-    expect(await element.getProperty("open")).toBe(false);
+    expect(await element.getProperty("expanded")).toBe(false);
     expect(toggle.getAttribute("aria-expanded")).toBe("false");
   }
 
   describe("theme", () => {
     describe("default", () => {
       themed(
         html`
-          <calcite-block-section text="Planes" open icon-end="pen" icon-start="pen" text="a block-section">
+          <calcite-block-section text="Planes" expanded icon-end="pen" icon-start="pen" text="a block-section">
             <p>Block section content</p>
           </calcite-block-section>
         `,

packages/calcite-components/src/components/block-section/block-section.scss

@@ -4,7 +4,7 @@
  * These properties can be overridden using the component's tag as selector.
  *
  * @prop --calcite-block-section-background-color: Specifies the component's background color.
- * @prop --calcite-block-section-border-color: Specifies the component's border color. When `open`, applies to the component's bottom border.
+ * @prop --calcite-block-section-border-color: Specifies the component's border color. When `expanded`, applies to the component's bottom border.
  * @prop --calcite-block-section-header-text-color: Specifies the component's header text color.
  * @prop --calcite-block-section-text-color: Specifies the component's text color.
  * @prop --calcite-block-section-text-color-hover: Specifies the component's text color on hover.
@@ -26,7 +26,7 @@ calcite-switch {
   // --calcite-switch-handle-shadow: var(--calcite-block-section-switch-handle-shadow);
 }
 
-:host([open]) {
+:host([expanded]) {
   @apply border-0
     border-b
     border-solid;

packages/calcite-components/src/components/block-section/block-section.tsx

@@ -6,6 +6,7 @@ import { FlipContext, Status } from "../interfaces";
 import { componentFocusable } from "../../utils/component";
 import { IconNameOrString } from "../icon/interfaces";
 import { useT9n } from "../../controllers/useT9n";
+import { logger } from "../../utils/logger";
 import T9nStrings from "./assets/t9n/messages.en.json";
 import { BlockSectionToggleDisplay } from "./interfaces";
 import { CSS, ICONS, IDS } from "./resources";
@@ -27,6 +28,9 @@ export class BlockSection extends LitElement {
 
   // #region Public Properties
 
+  /** When `true`, the component is expanded to show child components. */
+  @property({ reflect: true }) expanded = false;
+
   /** Specifies an icon to display at the end of the component. */
   @property({ reflect: true }) iconEnd: IconNameOrString;
 
@@ -46,8 +50,24 @@ export class BlockSection extends LitElement {
    */
   messages = useT9n<typeof T9nStrings>();
 
-  /** When `true`, expands the component and its contents. */
-  @property({ reflect: true }) open = false;
+  /**
+   * When `true`, expands the component and its contents.
+   *
+   * @deprecated Use `expanded` prop instead.
+   */
+  @property({ reflect: true })
+  get open(): boolean {
+    return this.expanded;
+  }
+
+  set open(value: boolean) {
+    logger.deprecated("property", {
+      name: "open",
+      removalVersion: 4,
+      suggested: "expanded",
+    });
+    this.expanded = value;
+  }
 
   /**
    * Displays a status-related indicator icon.
@@ -99,7 +119,7 @@ export class BlockSection extends LitElement {
   }
 
   private toggleSection(): void {
-    this.open = !this.open;
+    this.expanded = !this.expanded;
     this.calciteBlockSectionToggle.emit();
   }
 
@@ -146,10 +166,10 @@ export class BlockSection extends LitElement {
   }
 
   override render(): JsxNode {
-    const { messages, open, text, toggleDisplay } = this;
-    const arrowIcon = open ? ICONS.menuOpen : ICONS.menuClosed;
+    const { messages, expanded, text, toggleDisplay } = this;
+    const arrowIcon = expanded ? ICONS.menuExpanded : ICONS.menuCollapsed;
 
-    const toggleLabel = open ? messages.collapse : messages.expand;
+    const toggleLabel = expanded ? messages.collapse : messages.expand;
 
     const headerNode =
       toggleDisplay === "switch" ? (
@@ -160,7 +180,7 @@ export class BlockSection extends LitElement {
         >
           <div
             aria-controls={IDS.content}
-            ariaExpanded={open}
+            ariaExpanded={expanded}
             class={{
               [CSS.toggle]: true,
               [CSS.toggleSwitch]: true,
@@ -179,7 +199,13 @@ export class BlockSection extends LitElement {
 
             {this.renderIcon(this.iconEnd)}
             {this.renderStatusIcon()}
-            <calcite-switch checked={open} class={CSS.switch} inert label={toggleLabel} scale="s" />
+            <calcite-switch
+              checked={expanded}
+              class={CSS.switch}
+              inert
+              label={toggleLabel}
+              scale="s"
+            />
           </div>
         </div>
       ) : (
@@ -190,7 +216,7 @@ export class BlockSection extends LitElement {
         >
           <button
             aria-controls={IDS.content}
-            ariaExpanded={open}
+            ariaExpanded={expanded}
             class={{
               [CSS.sectionHeader]: true,
               [CSS.toggle]: true,
@@ -210,7 +236,12 @@ export class BlockSection extends LitElement {
     return (
       <>
         {headerNode}
-        <section aria-labelledby={IDS.toggle} class={CSS.content} hidden={!open} id={IDS.content}>
+        <section
+          aria-labelledby={IDS.toggle}
+          class={CSS.content}
+          hidden={!expanded}
+          id={IDS.content}
+        >
           <slot />
         </section>
       </>

packages/calcite-components/src/components/block-section/resources.ts

@@ -22,8 +22,8 @@ export const CSS = {
 };
 
 export const ICONS = {
-  menuOpen: "chevron-up",
-  menuClosed: "chevron-down",
+  menuExpanded: "chevron-up",
+  menuCollapsed: "chevron-down",
   valid: "check-circle",
   invalid: "exclamation-mark-triangle",
 } as const;