From 25a4778cf7ebbdcfbe6f7da7e0c86238e7cbf819 Mon Sep 17 00:00:00 2001
From: JC Franco <jfranco@esri.com>
Date: Tue, 16 Jul 2024 11:37:19 -0700
Subject: [PATCH] feat(combobox, combobox-item): add `description`,
 `shortHeading` props and `content-end` slot (#9771)

**Related Issue:** #3695

## Summary

This adds the following enhancements to `combobox`/`combobox-item`:

* `description` prop - displays description below label
* `shortHeading` prop - displays short version of the heading (label) in
selection
* `content-end` slot - enables slotting non-interactive elements after
the item's content

**Note**: the new props are filterable and also participate in visual
matching
---
 .../calcite-components/src/components.d.ts    |  16 +++
 .../combobox-item/combobox-item.scss          |  62 +++++++----
 .../combobox-item/combobox-item.tsx           |  60 ++++++++---
 .../src/components/combobox-item/resources.ts |  24 +++--
 .../components/combobox/combobox.stories.ts   | 100 +++++++++++++++++-
 .../src/components/combobox/combobox.tsx      |  27 +++--
 .../src/components/combobox/utils.ts          |   4 +
 7 files changed, 238 insertions(+), 55 deletions(-)

diff --git a/packages/calcite-components/src/components.d.ts b/packages/calcite-components/src/components.d.ts
index 276991b089b..7a7c23f9af6 100644
--- a/packages/calcite-components/src/components.d.ts
+++ b/packages/calcite-components/src/components.d.ts
@@ -1267,6 +1267,10 @@ export namespace Components {
           * Specifies the parent and grandparent items, which are set on `calcite-combobox`.
          */
         "ancestors": ComboboxChildElement[];
+        /**
+          * A description for the component, which displays below the label.
+         */
+        "description": string;
         /**
           * When `true`, interaction is prevented and the component is displayed with lower opacity.
          */
@@ -1306,6 +1310,10 @@ export namespace Components {
     "single" | "single-persist" | "ancestors" | "multiple",
     SelectionMode
   >;
+        /**
+          * The component's short heading.  When provided, the short heading will be displayed in the component's selection.  It is recommended to use 5 characters or fewer.
+         */
+        "shortHeading": string;
         /**
           * The component's text.
          */
@@ -9110,6 +9118,10 @@ declare namespace LocalJSX {
           * Specifies the parent and grandparent items, which are set on `calcite-combobox`.
          */
         "ancestors"?: ComboboxChildElement[];
+        /**
+          * A description for the component, which displays below the label.
+         */
+        "description"?: string;
         /**
           * When `true`, interaction is prevented and the component is displayed with lower opacity.
          */
@@ -9153,6 +9165,10 @@ declare namespace LocalJSX {
     "single" | "single-persist" | "ancestors" | "multiple",
     SelectionMode
   >;
+        /**
+          * The component's short heading.  When provided, the short heading will be displayed in the component's selection.  It is recommended to use 5 characters or fewer.
+         */
+        "shortHeading"?: string;
         /**
           * The component's text.
          */
diff --git a/packages/calcite-components/src/components/combobox-item/combobox-item.scss b/packages/calcite-components/src/components/combobox-item/combobox-item.scss
index 9c10946cbdd..c06009ed955 100644
--- a/packages/calcite-components/src/components/combobox-item/combobox-item.scss
+++ b/packages/calcite-components/src/components/combobox-item/combobox-item.scss
@@ -6,6 +6,7 @@
   --calcite-combobox-item-spacing-unit-s: theme("spacing.1");
   --calcite-combobox-item-spacing-indent: theme("spacing.2");
   --calcite-combobox-item-selector-icon-size: theme("spacing.4");
+  --calcite-combobox-item-description-font-size: var(--calcite-font-size-xs);
 }
 
 .scale--m {
@@ -14,6 +15,7 @@
   --calcite-combobox-item-spacing-unit-s: theme("spacing.2");
   --calcite-combobox-item-spacing-indent: theme("spacing.3");
   --calcite-combobox-item-selector-icon-size: theme("spacing.4");
+  --calcite-combobox-item-description-font-size: var(--calcite-font-size-sm);
 }
 
 .scale--l {
@@ -22,6 +24,7 @@
   --calcite-combobox-item-spacing-unit-s: theme("spacing[2.5]");
   --calcite-combobox-item-spacing-indent: theme("spacing.4");
   --calcite-combobox-item-selector-icon-size: theme("spacing.6");
+  --calcite-combobox-item-description-font-size: var(--calcite-font-size);
 }
 
 .container {
@@ -48,20 +51,22 @@ ul:focus {
 
 .label {
   @apply text-color-3
-    focus-base
-    relative
-    box-border
-    flex
-    w-full
-    min-w-full
-    cursor-pointer
-    items-center
-    no-underline
-    duration-150
-    ease-in-out;
+  focus-base
+  relative
+  box-border
+  flex
+  w-full
+  min-w-full
+  cursor-pointer
+  items-center
+  no-underline
+  duration-150
+  ease-in-out;
   @include word-break();
+  justify-content: space-around;
+  gap: var(--calcite-combobox-item-spacing-unit-l);
   padding-block: var(--calcite-combobox-item-spacing-unit-s);
-  padding-inline: var(--calcite-combobox-item-spacing-unit-l);
+  padding-inline: var(--calcite-combobox-item-indent-value);
 }
 
 :host([disabled]) .label {
@@ -85,11 +90,6 @@ ul:focus {
     shadow-none;
 }
 
-.title {
-  padding-block: 0;
-  padding-inline: var(--calcite-combobox-item-spacing-unit-l);
-}
-
 .icon {
   @apply inline-flex
     opacity-0
@@ -98,13 +98,8 @@ ul:focus {
   color: theme("borderColor.color.1");
 }
 
-.icon--indent {
-  padding-inline-start: var(--calcite-combobox-item-indent-value);
-}
-
 .icon--custom {
   margin-block-start: -1px;
-  padding-inline-start: var(--calcite-combobox-item-spacing-unit-l);
   @apply text-color-3;
 }
 
@@ -140,3 +135,26 @@ ul:focus {
   color: var(--calcite-color-text-1);
   background-color: var(--calcite-color-foreground-current);
 }
+
+.center-content {
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  padding-block: 0;
+}
+
+.description {
+  font-size: var(--calcite-combobox-item-description-font-size);
+  font-weight: var(--calcite-font-weight-normal);
+}
+
+:host([selected]),
+:host(:hover) {
+  .description {
+    color: var(--calcite-color-text-2);
+  }
+}
+
+.short-text {
+  color: var(--calcite-color-text-3);
+}
diff --git a/packages/calcite-components/src/components/combobox-item/combobox-item.tsx b/packages/calcite-components/src/components/combobox-item/combobox-item.tsx
index f65d4d4fb19..b908cbd4855 100644
--- a/packages/calcite-components/src/components/combobox-item/combobox-item.tsx
+++ b/packages/calcite-components/src/components/combobox-item/combobox-item.tsx
@@ -28,10 +28,11 @@ import { getAncestors, getDepth, isSingleLike } from "../combobox/utils";
 import { Scale, SelectionMode } from "../interfaces";
 import { getIconScale } from "../../utils/component";
 import { IconName } from "../icon/interfaces";
-import { CSS } from "./resources";
+import { CSS, SLOTS } from "./resources";
 
 /**
  * @slot - A slot for adding nested `calcite-combobox-item`s.
+ * @slot content-end - A slot for adding non-actionable elements after the component's content.
  */
 @Component({
   tag: "calcite-combobox-item",
@@ -59,6 +60,11 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
   /** Specifies the parent and grandparent items, which are set on `calcite-combobox`. */
   @Prop({ mutable: true }) ancestors: ComboboxChildElement[];
 
+  /**
+   * A description for the component, which displays below the label.
+   */
+  @Prop() description: string;
+
   /** The `id` attribute of the component. When omitted, a globally unique identifier is used. */
   @Prop({ reflect: true }) guid = guid();
 
@@ -83,14 +89,18 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
    */
   @Prop({ reflect: true }) filterTextMatchPattern: RegExp;
 
-  /** The component's value. */
-  @Prop() value!: any;
-
   /**
    * When `true`, omits the component from the `calcite-combobox` filtered search results.
    */
   @Prop({ reflect: true }) filterDisabled: boolean;
 
+  /**
+   * Specifies the size of the component inherited from the `calcite-combobox`, defaults to `m`.
+   *
+   * @internal
+   */
+  @Prop() scale: Scale = "m";
+
   /**
    * Specifies the selection mode of the component, where:
    *
@@ -110,11 +120,16 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
   > = "multiple";
 
   /**
-   * Specifies the size of the component inherited from the `calcite-combobox`, defaults to `m`.
+   * The component's short heading.
    *
-   * @internal
+   * When provided, the short heading will be displayed in the component's selection.
+   *
+   * It is recommended to use 5 characters or fewer.
    */
-  @Prop() scale: Scale = "m";
+  @Prop({ reflect: true }) shortHeading: string;
+
+  /** The component's value. */
+  @Prop() value!: any;
 
   // --------------------------------------------------------------------------
   //
@@ -189,7 +204,6 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
         class={{
           [CSS.custom]: !!this.icon,
           [CSS.iconActive]: this.icon && this.selected,
-          [CSS.iconIndent]: true,
         }}
         flipRtl={this.iconFlipRtl}
         icon={this.icon || iconPath}
@@ -207,7 +221,6 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
         class={{
           [CSS.icon]: true,
           [CSS.dot]: true,
-          [CSS.iconIndent]: true,
         }}
       />
     ) : (
@@ -215,7 +228,6 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
         class={{
           [CSS.icon]: true,
           [CSS.iconActive]: this.selected,
-          [CSS.iconIndent]: true,
         }}
         flipRtl={this.iconFlipRtl}
         icon={iconPath}
@@ -250,19 +262,31 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
       [CSS.active]: this.active,
       [CSS.single]: isSingleSelect,
     };
-    const depth = getDepth(this.el);
+    const depth = getDepth(this.el) + 1;
 
     return (
       <Host aria-hidden="true">
         <InteractiveContainer disabled={disabled}>
           <div
-            class={`container scale--${this.scale}`}
+            class={{
+              [CSS.container]: true,
+              [CSS.scale(this.scale)]: true,
+            }}
             style={{ "--calcite-combobox-item-spacing-indent-multiplier": `${depth}` }}
           >
             <li class={classes} id={this.guid} onClick={this.itemClickHandler}>
               {this.renderSelectIndicator(showDot, iconPath)}
               {this.renderIcon(iconPath)}
-              <span class="title">{this.renderTextContent()}</span>
+              <div class={CSS.centerContent}>
+                <div class={CSS.title}>{this.renderTextContent(this.textLabel)}</div>
+                {this.description ? (
+                  <div class={CSS.description}>{this.renderTextContent(this.description)}</div>
+                ) : null}
+              </div>
+              {this.shortHeading ? (
+                <div class={CSS.shortText}>{this.renderTextContent(this.shortHeading)}</div>
+              ) : null}
+              <slot name={SLOTS.contentEnd} />
             </li>
             {this.renderChildren()}
           </div>
@@ -271,12 +295,14 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
     );
   }
 
-  private renderTextContent(): string | (string | VNode)[] {
-    if (!this.filterTextMatchPattern) {
-      return this.textLabel;
+  private renderTextContent(text: string): string | (string | VNode)[] {
+    const pattern = this.filterTextMatchPattern;
+
+    if (!pattern || !text) {
+      return text;
     }
 
-    const parts: (string | VNode)[] = this.textLabel.split(this.filterTextMatchPattern);
+    const parts: (string | VNode)[] = text.split(pattern);
 
     if (parts.length > 1) {
       // we only highlight the first match
diff --git a/packages/calcite-components/src/components/combobox-item/resources.ts b/packages/calcite-components/src/components/combobox-item/resources.ts
index c7375d2bc96..19df6171926 100644
--- a/packages/calcite-components/src/components/combobox-item/resources.ts
+++ b/packages/calcite-components/src/components/combobox-item/resources.ts
@@ -1,14 +1,24 @@
+import { Scale } from "../interfaces";
+
 export const CSS = {
-  icon: "icon",
-  iconActive: "icon--active",
-  iconIndent: "icon--indent",
+  active: "label--active",
+  centerContent: "center-content",
+  container: "container",
   custom: "icon--custom",
+  description: "description",
   dot: "icon--dot",
-  single: "label--single",
+  filterMatch: "filter-match",
+  icon: "icon",
+  iconActive: "icon--active",
   label: "label",
-  active: "label--active",
+  scale: (scale: Scale) => `scale--${scale}` as const,
   selected: "label--selected",
-  title: "title",
+  shortText: "short-text",
+  single: "label--single",
   textContainer: "text-container",
-  filterMatch: "filter-match",
+  title: "title",
+};
+
+export const SLOTS = {
+  contentEnd: "content-end",
 };
diff --git a/packages/calcite-components/src/components/combobox/combobox.stories.ts b/packages/calcite-components/src/components/combobox/combobox.stories.ts
index 80c953325cc..3ab19ef2f39 100644
--- a/packages/calcite-components/src/components/combobox/combobox.stories.ts
+++ b/packages/calcite-components/src/components/combobox/combobox.stories.ts
@@ -1,5 +1,66 @@
 import { modesDarkDefault } from "../../../.storybook/utils";
 import { html } from "../../../support/formatting";
+import type { Scale } from "../interfaces";
+import type { Combobox } from "./combobox";
+
+/**
+ * This decorator takes HTML for items and will create a composite story for all scales for each specified selection mode.
+ *
+ * @param itemsStory - the HTML story template for items
+ * @param context - the context object
+ * @param context.args - the args object
+ * @param context.args.selectionMode - the selection mode(s) to use for the combobox
+ *
+ * @returns the composite story for all scales for each specified selection mode
+ */
+function allScaleComboboxBuilder(
+  itemsStory: () => string,
+  context: { args: { selectionMode: Combobox["selectionMode"] | Combobox["selectionMode"][] } },
+): string {
+  const items = itemsStory();
+  const { selectionMode } = context.args;
+  const selectionModes = Array.isArray(selectionMode) ? selectionMode : [selectionMode];
+  const scales: Scale[] = ["s", "m", "l"];
+
+  return html`
+    <style>
+      calcite-combobox {
+        margin-bottom: 250px;
+      }
+      .selection-mode-group {
+        display: flex;
+        justify-content: space-between;
+      }
+      .combobox-container {
+        flex: 1;
+        margin-right: 10px;
+      }
+    </style>
+
+    ${selectionModes.map(
+      (selectionMode) => html`
+        <div class="selection-mode-group">
+          ${scales.map(
+            (scale) => html`
+              <div class="combobox-container">
+                <h3>${selectionMode} selection mode + ${scale} scale</h3>
+                <calcite-combobox
+                  placeholder="select element"
+                  max-items="6"
+                  selection-mode="${selectionMode}"
+                  open
+                  scale="${scale}"
+                >
+                  ${items}
+                </calcite-combobox>
+              </div>
+            `,
+          )}
+        </div>
+      `,
+    )}
+  `;
+}
 
 export default {
   title: "Components/Controls/Combobox",
@@ -823,7 +884,12 @@ export const filterHighlighting = (): string => html`
     </calcite-combobox-item>
     <calcite-combobox-item value="Flowers" text-label="Flowers">
       <calcite-combobox-item value="Daffodil" text-label="Daffodil"></calcite-combobox-item>
-      <calcite-combobox-item value="Black Eyed Susan" text-label="Black Eyed Susan"></calcite-combobox-item>
+      <calcite-combobox-item
+        value="Black Eyed Susan"
+        description="The Black Eyed Susan is a yellow flower with a dark center."
+        text-label="Black Eyed Susan"
+        short-heading="Susan"
+      ></calcite-combobox-item>
       <calcite-combobox-item value="Nasturtium" text-label="Nasturtium"></calcite-combobox-item>
     </calcite-combobox-item>
     <calcite-combobox-item value="Animals" text-label="Animals">
@@ -836,3 +902,35 @@ export const filterHighlighting = (): string => html`
     <calcite-combobox-item value="Rivers" text-label="Rivers"></calcite-combobox-item>
   </calcite-combobox>
 `;
+
+export const withDescriptionShortLabelAndContentEndSlot = (): string => html`
+  <calcite-combobox-item
+    description="the first installment in this thrilling series"
+    selected
+    short-heading="#1"
+    text-label="1ne"
+    value="one"
+  >
+    <calcite-icon icon="number-circle-1" slot="content-end"></calcite-icon>
+  </calcite-combobox-item>
+  <calcite-combobox-item
+    description="the sequel to the smash hit 'one'"
+    short-heading="#2"
+    text-label="2woo"
+    value="two"
+  >
+    <calcite-icon icon="number-circle-2" slot="content-end"></calcite-icon>
+  </calcite-combobox-item>
+  <calcite-combobox-item
+    description="the thrilling conclusion to the number series"
+    short-heading="#3"
+    text-label="Thr333"
+    value="three"
+  >
+    <calcite-icon icon="number-circle-3" slot="content-end"></calcite-icon>
+  </calcite-combobox-item>
+`;
+withDescriptionShortLabelAndContentEndSlot.decorators = [allScaleComboboxBuilder];
+withDescriptionShortLabelAndContentEndSlot.args = {
+  selectionMode: ["single", "multiple"],
+};
diff --git a/packages/calcite-components/src/components/combobox/combobox.tsx b/packages/calcite-components/src/components/combobox/combobox.tsx
index a8768d9fa4d..8c7506bf9a2 100644
--- a/packages/calcite-components/src/components/combobox/combobox.tsx
+++ b/packages/calcite-components/src/components/combobox/combobox.tsx
@@ -71,10 +71,18 @@ import { IconName } from "../icon/interfaces";
 import { ComboboxMessages } from "./assets/combobox/t9n";
 import { ComboboxChildElement, SelectionDisplay } from "./interfaces";
 import { ComboboxChildSelector, ComboboxItem, ComboboxItemGroup, CSS } from "./resources";
-import { getItemAncestors, getItemChildren, hasActiveChildren, isSingleLike } from "./utils";
+import {
+  getItemAncestors,
+  getItemChildren,
+  getLabel,
+  hasActiveChildren,
+  isSingleLike,
+} from "./utils";
 
 interface ItemData {
   label: string;
+  shortHeading: string;
+  description: string;
   value: string;
 }
 
@@ -577,7 +585,7 @@ export class Combobox
 
   textInput: HTMLInputElement = null;
 
-  data: ItemData[];
+  private data: ItemData[];
 
   mutationObserver = createObserver("mutation", () => this.updateItems());
 
@@ -1153,7 +1161,7 @@ export class Combobox
       this.emitComboboxChange();
 
       if (this.textInput) {
-        this.textInput.value = item.textLabel;
+        this.textInput.value = getLabel(item);
       }
       this.open = false;
       this.updateActiveItemIndex(-1);
@@ -1242,9 +1250,11 @@ export class Combobox
 
   getData(): ItemData[] {
     return this.items.map((item) => ({
+      description: item.description,
       filterDisabled: item.filterDisabled,
-      value: item.value,
       label: item.textLabel,
+      shortHeading: item.shortHeading,
+      value: item.value,
     }));
   }
 
@@ -1404,8 +1414,9 @@ export class Combobox
         "chip--active": activeChipIndex === i,
       };
       const ancestors = [...getItemAncestors(item)].reverse();
-      const pathLabel = [...ancestors, item].map((el) => el.textLabel);
-      const label = selectionMode !== "ancestors" ? item.textLabel : pathLabel.join(" / ");
+      const itemLabel = getLabel(item);
+      const pathLabel = [...ancestors, item].map((el) => getLabel(el));
+      const label = selectionMode !== "ancestors" ? itemLabel : pathLabel.join(" / ");
 
       return (
         <calcite-chip
@@ -1416,7 +1427,7 @@ export class Combobox
           icon={item.icon}
           iconFlipRtl={item.iconFlipRtl}
           id={item.guid ? `${chipUidPrefix}${item.guid}` : null}
-          key={item.textLabel}
+          key={itemLabel}
           messageOverrides={{ dismissLabel: messages.removeTag }}
           onCalciteChipClose={() => this.calciteChipCloseHandler(item)}
           onFocusin={() => (this.activeChipIndex = i)}
@@ -1607,7 +1618,7 @@ export class Combobox
             }}
             key="label"
           >
-            {selectedItem.textLabel}
+            {getLabel(selectedItem)}
           </span>
         )}
         <input
diff --git a/packages/calcite-components/src/components/combobox/utils.ts b/packages/calcite-components/src/components/combobox/utils.ts
index 3afe2fb51dc..5c92b929dc2 100644
--- a/packages/calcite-components/src/components/combobox/utils.ts
+++ b/packages/calcite-components/src/components/combobox/utils.ts
@@ -44,3 +44,7 @@ export function getDepth(element: HTMLElement): number {
 export function isSingleLike(selectionMode: Combobox["selectionMode"]): boolean {
   return selectionMode.includes("single");
 }
+
+export function getLabel(item: HTMLCalciteComboboxItemElement): string {
+  return item.shortHeading || item.textLabel;
+}