fix(panel, flow-item): prevent footer slots from conflicting with each other (#9856)

**Related Issue:** #9855

## Summary

- prevent footer slots from conflicting
- modify stories
- add doc

Author: driskull

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

@@ -234,7 +234,8 @@ export const footerPaddingAndContentBottom = (): string =>
       <div slot="header-content">Header!</div>
       <p>Slotted content!</p>
       <div slot="content-bottom">Content bottom!</div>
-      <div slot="footer">Footer!</div>
+      <calcite-button slot="footer" width="half" appearance="outline">Footer 1</calcite-button>
+      <calcite-button slot="footer" width="half">Footer 2</calcite-button>
     </calcite-flow-item>
   </div>`;
 
@@ -248,13 +249,14 @@ export const footerStartEndAndContentBottom = (): string =>
     </calcite-flow-item>
   </div>`;
 
-export const footerSlotPrecedence = (): string =>
+export const footerSlotCoexistence = (): string =>
   html`<div style="width: 300px;">
     <calcite-flow-item height-scale="s" style="--calcite-flow-item-footer-padding: 20px;">
       <div slot="header-content">Header!</div>
       <p>Slotted content!</p>
       <div slot="content-bottom">Content bottom!</div>
-      <div slot="footer">Footer!</div>
+      <calcite-button slot="footer" width="half" appearance="outline">Footer 1</calcite-button>
+      <calcite-button slot="footer" width="half">Footer 2</calcite-button>
       ${footerHTML}
     </calcite-flow-item>
   </div>`;

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

@@ -52,10 +52,10 @@ import { CSS, ICONS, SLOTS } from "./resources";
  * @slot header-content - A slot for adding custom content to the component's header.
  * @slot header-menu-actions - A slot for adding an overflow menu with `calcite-action`s inside a `calcite-dropdown`.
  * @slot fab - A slot for adding a `calcite-fab` (floating action button) to perform an action.
- * @slot footer - A slot for adding custom content to the component's footer.
+ * @slot footer - A slot for adding custom content to the component's footer. Should not be used with the `"footer-start"` or `"footer-end"` slots.
  * @slot footer-actions - [Deprecated] Use the `"footer"` slot instead. A slot for adding `calcite-button`s to the component's footer.
- * @slot footer-end - A slot for adding a trailing footer custom content.
- * @slot footer-start - A slot for adding a leading footer custom content.
+ * @slot footer-end - A slot for adding a trailing footer custom content. Should not be used with the `"footer"` slot.
+ * @slot footer-start - A slot for adding a leading footer custom content. Should not be used with the `"footer"` slot.
  */
 @Component({
   tag: "calcite-flow-item",
@@ -405,10 +405,9 @@ export class FlowItem
             <slot name={SLOTS.fab} slot={PANEL_SLOTS.fab} />
             <slot name={SLOTS.contentTop} slot={PANEL_SLOTS.contentTop} />
             <slot name={SLOTS.contentBottom} slot={PANEL_SLOTS.contentBottom} />
-            <slot name={SLOTS.footer} slot={PANEL_SLOTS.footer}>
-              <slot name={SLOTS.footerStart} slot={PANEL_SLOTS.footerStart} />
-              <slot name={SLOTS.footerEnd} slot={PANEL_SLOTS.footerEnd} />
-            </slot>
+            <slot name={SLOTS.footerStart} slot={PANEL_SLOTS.footerStart} />
+            <slot name={SLOTS.footer} slot={PANEL_SLOTS.footer} />
+            <slot name={SLOTS.footerEnd} slot={PANEL_SLOTS.footerEnd} />
             <slot name={SLOTS.footerActions} slot={PANEL_SLOTS.footerActions} />
             <slot />
           </calcite-panel>

packages/calcite-components/src/components/panel/panel.tsx

@@ -58,10 +58,10 @@ import { CSS, ICONS, SLOTS } from "./resources";
  * @slot header-content - A slot for adding custom content to the header.
  * @slot header-menu-actions - A slot for adding an overflow menu with actions inside a `calcite-dropdown`.
  * @slot fab - A slot for adding a `calcite-fab` (floating action button) to perform an action.
- * @slot footer - A slot for adding custom content to the component's footer.
+ * @slot footer - A slot for adding custom content to the component's footer. Should not be used with the `"footer-start"` or `"footer-end"` slots.
  * @slot footer-actions - [Deprecated] Use the `footer-start` and `footer-end` slots instead. A slot for adding `calcite-button`s to the component's footer.
- * @slot footer-end - A slot for adding a trailing footer custom content.
- * @slot footer-start - A slot for adding a leading footer custom content.
+ * @slot footer-end - A slot for adding a trailing footer custom content. Should not be used with the `"footer"` slot.
+ * @slot footer-start - A slot for adding a leading footer custom content. Should not be used with the `"footer"` slot.
  */
 @Component({
   tag: "calcite-panel",
@@ -620,10 +620,9 @@ export class Panel
 
     return (
       <footer class={CSS.footer} hidden={!showFooter}>
-        <slot name={SLOTS.footer} onSlotchange={this.handleFooterSlotChange}>
-          <slot name={SLOTS.footerStart} onSlotchange={this.handleFooterStartSlotChange} />
-          <slot name={SLOTS.footerEnd} onSlotchange={this.handleFooterEndSlotChange} />
-        </slot>
+        <slot name={SLOTS.footerStart} onSlotchange={this.handleFooterStartSlotChange} />
+        <slot name={SLOTS.footer} onSlotchange={this.handleFooterSlotChange} />
+        <slot name={SLOTS.footerEnd} onSlotchange={this.handleFooterEndSlotChange} />
         <slot
           key="footer-actions-slot"
           name={SLOTS.footerActions}