feat(panel, flow-item): add support for collapsing content (#7857)

**Related Issue:** #7498

## Summary

- Add support for collapsing panel content via an action in the header
- Adds props `collapsible`, `collapsed` and `collapseDirection` to both
`flow-item` and `panel`
  - `collapseDirection` is internal for discussion
- Depending on which way the panel expands, the icons may need to be
reversed.
  - This property allows that. cc @asangma for more information.
  - We can remove this prop if we don't think its necessary
- Adds event `calcitePanelToggle`.
  - Block calls this event `calciteBlockToggle`.
  - ActionPad calls this event `calciteActionPadToggle`
- Copies t9n messages from block component (expand/collapse) messages.
- Adds CSS custom properties for the panel/flow-item to disable the
header's bottom border
  - `--calcite-panel-header-border-block-end`
  - `--calcite-flow-item-header-border-block-end`
- Removes unused private properties on panel 🧹 
- Adds screenshot tests & stories
- Adds usage file
- Updates HTML file for panel
- Adds e2e tests

packages/calcite-components/src/components/flow-item/flow-item.e2e.ts

@@ -22,6 +22,18 @@ describe("calcite-flow-item", () => {
         propertyName: "closed",
         defaultValue: false,
       },
+      {
+        propertyName: "collapsible",
+        defaultValue: false,
+      },
+      {
+        propertyName: "collapseDirection",
+        defaultValue: "down",
+      },
+      {
+        propertyName: "collapsed",
+        defaultValue: false,
+      },
       {
         propertyName: "disabled",
         defaultValue: false,
@@ -60,6 +72,17 @@ describe("calcite-flow-item", () => {
       <calcite-button slot="${SLOTS.footerActions}">test button 2</calcite-button>
     </calcite-flow-item>
     `);
+
+    accessible(`
+    <calcite-flow-item collapsible>
+      <div slot="${SLOTS.headerActionsStart}">test start</div>
+      <div slot="${SLOTS.headerContent}">test content</div>
+      <div slot="${SLOTS.headerActionsEnd}">test end</div>
+      <p>Content</p>
+      <calcite-button slot="${SLOTS.footerActions}">test button 1</calcite-button>
+      <calcite-button slot="${SLOTS.footerActions}">test button 2</calcite-button>
+    </calcite-flow-item>
+    `);
   });
 
   describe("should focus on back button", () => {
@@ -111,6 +134,17 @@ describe("calcite-flow-item", () => {
     expect(calciteFlowItemBack).toHaveReceivedEvent();
   });
 
+  it("sets collapsible and collapsed on internal panel", async () => {
+    const page = await newE2EPage();
+
+    await page.setContent("<calcite-flow-item collapsible collapsed></calcite-flow-item>");
+
+    const panel = await page.find(`calcite-flow-item >>> calcite-panel`);
+
+    expect(await panel.getProperty("collapsed")).toBe(true);
+    expect(await panel.getProperty("collapsible")).toBe(true);
+  });
+
   it("allows scrolling content", async () => {
     const page = await newE2EPage();
     await page.setContent(html`
@@ -161,15 +195,23 @@ describe("calcite-flow-item", () => {
     });
 
     const scrollSpy = await page.spyOnEvent("calciteFlowItemScroll");
+    const panel = await page.find("calcite-flow-item >>> calcite-panel");
+    panel.triggerEvent("calcitePanelScroll");
+    await page.waitForChanges();
 
-    await page.evaluate(() => {
-      const panel = document.querySelector("calcite-flow-item").shadowRoot.querySelector("calcite-panel");
+    expect(scrollSpy).toHaveReceivedEventTimes(1);
+  });
 
-      panel.dispatchEvent(new CustomEvent("calcitePanelScroll"));
+  it("honors calciteFlowItemToggle event", async () => {
+    const page = await newE2EPage({
+      html: "<calcite-flow-item collapsible>test</calcite-flow-item>",
     });
 
+    const toggleSpy = await page.spyOnEvent("calciteFlowItemToggle");
+    const panel = await page.find("calcite-flow-item >>> calcite-panel");
+    panel.triggerEvent("calcitePanelToggle");
     await page.waitForChanges();
 
-    expect(scrollSpy).toHaveReceivedEventTimes(1);
+    expect(toggleSpy).toHaveReceivedEventTimes(1);
   });
 });

packages/calcite-components/src/components/flow-item/flow-item.scss

@@ -4,12 +4,12 @@
  * These properties can be overridden using the component's tag as selector.
  *
  * @prop --calcite-flow-item-footer-padding: Specifies the padding of the component's footer.
+ * @prop --calcite-flow-item-header-border-block-end: Specifies the component header's block end border.
  */
 
 :host {
   @extend %component-host;
   @apply relative flex w-full flex-auto overflow-hidden;
-  --calcite-flow-item-footer-padding: theme("spacing.2");
 }
 
 @include disabled();
@@ -23,6 +23,7 @@
 
 calcite-panel {
   --calcite-panel-footer-padding: var(--calcite-flow-item-footer-padding);
+  --calcite-panel-header-border-block-end: var(--calcite-flow-item-header-border-block-end);
 }
 
 @include base-component();

packages/calcite-components/src/components/flow-item/flow-item.stories.ts

@@ -49,6 +49,22 @@ const createAttributes: (options?: { exceptions: string[] }) => Attributes = ({
           return this;
         },
       },
+      {
+        name: "collapsible",
+        commit(): Attribute {
+          this.value = boolean("collapsible", false);
+          delete this.build;
+          return this;
+        },
+      },
+      {
+        name: "collapsed",
+        commit(): Attribute {
+          this.value = boolean("collapsed", false);
+          delete this.build;
+          return this;
+        },
+      },
       {
         name: "height-scale",
         commit(): Attribute {
@@ -139,6 +155,10 @@ export const onlyProps = (): string => html`
   </div>
 `;
 
+export const collapsed_TestOnly = (): string => html`
+  <calcite-flow-item collapsed collapsible closable> Hello World! </calcite-flow-item>
+`;
+
 export const disabledWithStyledSlot_TestOnly = (): string => html`
   <calcite-flow-item style="height: 100%;" heading="Heading" disabled>
     <div id="content" style="height: 100%;">${contentHTML}</div>
@@ -231,3 +251,8 @@ export const footerPadding_TestOnly = (): string => html`<div style="width: 300p
     <div slot="footer">Footer!</div>
   </calcite-flow-item>
 </div>`;
+
+export const withNoHeaderBorderBlockEnd_TestOnly = (): string =>
+  html`<calcite-flow-item style="--calcite-flow-item-header-border-block-end:none;" height-scale="s" heading="My Panel"
+    >Slotted content!</calcite-flow-item
+  >`;

packages/calcite-components/src/components/flow-item/flow-item.tsx

@@ -69,6 +69,23 @@ export class FlowItem
   /** When `true`, the component will be hidden. */
   @Prop({ reflect: true }) closed = false;
 
+  /**
+   * When `true`, hides the component's content area.
+   */
+  @Prop({ reflect: true }) collapsed = false;
+
+  /**
+   * Specifies the direction of the collapse.
+   *
+   * @internal
+   */
+  @Prop() collapseDirection: "down" | "up" = "down";
+
+  /**
+   * When `true`, the component is collapsible.
+   */
+  @Prop({ reflect: true }) collapsible = false;
+
   /**
    * When provided, the method will be called before it is removed from its parent `calcite-flow`.
    */
@@ -180,6 +197,11 @@ export class FlowItem
    */
   @Event({ cancelable: false }) calciteFlowItemClose: EventEmitter<void>;
 
+  /**
+   * Fires when the collapse button is clicked.
+   */
+  @Event({ cancelable: false }) calciteFlowItemToggle: EventEmitter<void>;
+
   // --------------------------------------------------------------------------
   //
   //  Private Properties
@@ -209,6 +231,8 @@ export class FlowItem
 
   /**
    * Sets focus on the component.
+   *
+   * @returns promise.
    */
   @Method()
   async setFocus(): Promise<void> {
@@ -232,7 +256,8 @@ export class FlowItem
    *   top: 0, // Specifies the number of pixels along the Y axis to scroll the window or element
    *   behavior: "auto" // Specifies whether the scrolling should animate smoothly (smooth), or happen instantly in a single jump (auto, the default value).
    * });
-   * @param options
+   * @param options - allows specific coordinates to be defined.
+   * @returns - promise that resolves once the content is scrolled to.
    */
   @Method()
   async scrollContentTo(options?: ScrollToOptions): Promise<void> {
@@ -255,6 +280,11 @@ export class FlowItem
     this.calciteFlowItemClose.emit();
   };
 
+  handlePanelToggle = (event: CustomEvent<void>): void => {
+    event.stopPropagation();
+    this.calciteFlowItemToggle.emit();
+  };
+
   backButtonClick = (): void => {
     this.calciteFlowItemBack.emit();
   };
@@ -300,6 +330,9 @@ export class FlowItem
 
   render(): VNode {
     const {
+      collapsed,
+      collapseDirection,
+      collapsible,
       closable,
       closed,
       description,
@@ -315,6 +348,9 @@ export class FlowItem
         <calcite-panel
           closable={closable}
           closed={closed}
+          collapseDirection={collapseDirection}
+          collapsed={collapsed}
+          collapsible={collapsible}
           description={description}
           disabled={disabled}
           heading={heading}
@@ -324,6 +360,7 @@ export class FlowItem
           messageOverrides={messages}
           onCalcitePanelClose={this.handlePanelClose}
           onCalcitePanelScroll={this.handlePanelScroll}
+          onCalcitePanelToggle={this.handlePanelToggle}
           // eslint-disable-next-line react/jsx-sort-props -- ref should be last so node attrs/props are in sync (see https://github.com/Esri/calcite-design-system/pull/6530)
           ref={this.setContainerRef}
         >

packages/calcite-components/src/components/panel/assets/panel/t9n/messages.json

@@ -1,4 +1,6 @@
 {
   "close": "Close",
-  "options": "Options"
+  "options": "Options",
+  "collapse": "Collapse",
+  "expand": "Expand"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_ar.json

@@ -1,4 +1,6 @@
 {
   "close": "إغلاق",
-  "options": "خيارات"
+  "options": "خيارات",
+  "collapse": "طي",
+  "expand": "توسيع"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_bg.json

@@ -1,4 +1,6 @@
 {
   "close": "Затваряне",
-  "options": "Опции"
+  "options": "Опции",
+  "collapse": "Сгъване",
+  "expand": "Разгъване"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_bs.json

@@ -1,4 +1,6 @@
 {
   "close": "Zatvori",
-  "options": "Opcije"
+  "options": "Opcije",
+  "collapse": "Sažmi",
+  "expand": "Proširi"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_ca.json

@@ -1,4 +1,6 @@
 {
   "close": "Tanca",
-  "options": "Opcions"
+  "options": "Opcions",
+  "collapse": "Redueix",
+  "expand": "Amplia"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_cs.json

@@ -1,4 +1,6 @@
 {
   "close": "Zavřít",
-  "options": "Možnosti"
+  "options": "Možnosti",
+  "collapse": "Sbalit",
+  "expand": "Rozbalit"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_da.json

@@ -1,4 +1,6 @@
 {
   "close": "Luk",
-  "options": "Indstillinger"
+  "options": "Indstillinger",
+  "collapse": "Skjul",
+  "expand": "Udvid"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_de.json

@@ -1,4 +1,6 @@
 {
   "close": "Schließen",
-  "options": "Optionen"
+  "options": "Optionen",
+  "collapse": "Ausblenden",
+  "expand": "Einblenden"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_el.json

@@ -1,4 +1,6 @@
 {
   "close": "Κλείσιμο",
-  "options": "Επιλογές"
+  "options": "Επιλογές",
+  "collapse": "Σύμπτυξη",
+  "expand": "Ανάπτυξη"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_en.json

@@ -1,4 +1,6 @@
 {
   "close": "Close",
-  "options": "Options"
+  "options": "Options",
+  "collapse": "Collapse",
+  "expand": "Expand"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_es.json

@@ -1,4 +1,6 @@
 {
   "close": "Cerrar",
-  "options": "Opciones"
+  "options": "Opciones",
+  "collapse": "Contraer",
+  "expand": "Expandir"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_et.json

@@ -1,4 +1,6 @@
 {
   "close": "Sule",
-  "options": "Valikud"
+  "options": "Valikud",
+  "collapse": "Ahenda",
+  "expand": "Laienda"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_fi.json

@@ -1,4 +1,6 @@
 {
   "close": "Sulje",
-  "options": "Asetukset"
+  "options": "Asetukset",
+  "collapse": "Kutista",
+  "expand": "Laajenna"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_fr.json

@@ -1,4 +1,6 @@
 {
   "close": "Fermer",
-  "options": "Options"
+  "options": "Options",
+  "collapse": "Réduire",
+  "expand": "Développer"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_he.json

@@ -1,4 +1,6 @@
 {
   "close": "סגירה",
-  "options": "אפשרויות"
+  "options": "אפשרויות",
+  "collapse": "צמצם",
+  "expand": "הרחב"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_hr.json

@@ -1,4 +1,6 @@
 {
   "close": "Zatvori",
-  "options": "Opcije"
+  "options": "Opcije",
+  "collapse": "Sažmi",
+  "expand": "Proširi"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_hu.json

@@ -1,4 +1,6 @@
 {
   "close": "Bezárás",
-  "options": "Beállítási lehetőségek"
+  "options": "Beállítási lehetőségek",
+  "collapse": "Összecsukás",
+  "expand": "Kibontás"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_id.json

@@ -1,4 +1,6 @@
 {
   "close": "Tutup",
-  "options": "Opsi"
+  "options": "Opsi",
+  "collapse": "Tutup",
+  "expand": "Bentang"
 }

packages/calcite-components/src/components/panel/assets/panel/t9n/messages_it.json

@@ -1,4 +1,6 @@
 {
   "close": "Chiudi",
-  "options": "Opzioni"
+  "options": "Opzioni",
+  "collapse": "Comprimi",
+  "expand": "Espandi"
 }