@aquera/nile-elements 2.0.2 → 2.0.3

package/src/nile-segmented-progress-bar/nile-segmented-progress-bar.ts

@@ -0,0 +1,437 @@
+/**
+ * Copyright Aquera Inc 2026
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { html, nothing } from 'lit';
+import { styles } from './nile-segmented-progress-bar.css';
+import { classMap } from 'lit/directives/class-map.js';
+import { styleMap } from 'lit/directives/style-map.js';
+import { customElement, property } from 'lit/decorators.js';
+import NileElement from '../internal/nile-element';
+import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
+import '../nile-lite-tooltip/index';
+
+/** A single slice of the distribution rendered by `nile-segmented-progress-bar`. */
+export interface NileProgressSegment {
+  /** Legend label, also used in the default tooltip text. */
+  label: string;
+  /** Raw magnitude of this segment. */
+  value: number;
+  /** Any CSS color; falls back to the palette rotation when omitted. */
+  color?: string;
+  /** Overrides the default tooltip content for this segment. */
+  tooltip?: string;
+}
+
+/** Placement values forwarded to `nile-lite-tooltip`. */
+export type NileSegmentTooltipPlacement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'auto'
+  | 'auto-start'
+  | 'auto-end';
+
+/** The number of palette classes declared in the stylesheet. */
+const PALETTE_LENGTH = 10;
+
+/**
+ * Nile segmented progress bar component.
+ *
+ * @tag nile-segmented-progress-bar
+ *
+ * @summary A config-driven, responsive multi-segment progress / distribution bar
+ * with an optional wrapping legend — a single rounded track split into colored
+ * proportional segments (for example Success / Failure / Errors / Running / Other).
+ * @status experimental
+ *
+ * @event nile-segment-click - Emitted when a segment or its legend entry is activated by click,
+ * `Enter` or `Space`. The `detail` contains `{ segment, index, percentage }`.
+ *
+ * @csspart container - The component's base wrapper.
+ * @csspart label - The optional heading above the bar.
+ * @csspart bar - The bar/track element (also exposed as `track`).
+ * @csspart track - The bar/track element (also exposed as `bar`).
+ * @csspart segment - An individual colored segment inside the track.
+ * @csspart legend - The wrapping legend row.
+ * @csspart legend-item - A single legend entry (swatch + label + value).
+ * @csspart legend-swatch - The small rounded square in the segment color.
+ * @csspart legend-label - The legend entry's label text.
+ * @csspart legend-value - The legend entry's bold value.
+ *
+ * @example
+ * <nile-segmented-progress-bar
+ *   label="Run outcomes"
+ *   .segments=${[
+ *     { label: 'Success', value: 45623 },
+ *     { label: 'Failure', value: 50342 },
+ *     { label: 'Errors', value: 682 },
+ *     { label: 'Running', value: 166 },
+ *     { label: 'Other', value: 1552 },
+ *   ]}
+ * ></nile-segmented-progress-bar>
+ */
+@customElement('nile-segmented-progress-bar')
+export class NileSegmentedProgressBar extends NileElement {
+  static styles: CSSResultGroup = styles;
+
+  /** The segments to distribute across the bar. This is the component's config. */
+  @property({ type: Array }) segments: NileProgressSegment[] = [];
+
+  /** Optional heading rendered above the bar. Nothing renders when empty. */
+  @property({ type: String, reflect: true }) label = '';
+
+  /** Renders the legend below the bar. */
+  @property({ type: Boolean, attribute: 'show-legend' }) showLegend = true;
+
+  /** Wraps every segment in a `nile-lite-tooltip`. */
+  @property({ type: Boolean, attribute: 'show-tooltip' }) showTooltip = true;
+
+  /** Renders the bold value alongside each legend label. */
+  @property({ type: Boolean, attribute: 'show-values' }) showValues = true;
+
+  /** The thickness of the bar. */
+  @property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
+
+  /**
+   * Optional denominator. When omitted the denominator is the sum of the segment
+   * values, so the segments always fill 100%. When larger than the sum, the
+   * remainder renders as an unfilled track.
+   */
+  @property({ type: Number }) total?: number;
+
+  /** Rounds the bar's outer ends. */
+  @property({ type: Boolean }) rounded = true;
+
+  /**
+   * Minimum rendered width, in pixels, of a non-zero segment. Guarantees sub-1%
+   * segments stay a discernible sliver. The largest segment absorbs whatever
+   * overflow this introduces, so the row still totals exactly 100%.
+   */
+  @property({ type: Number, attribute: 'min-segment-width' })
+  minSegmentWidth = 2;
+
+  /** Passed straight through to `nile-lite-tooltip`'s `placement`. */
+  @property({ attribute: 'tooltip-placement' })
+  tooltipPlacement: NileSegmentTooltipPlacement = 'top';
+
+  /* #region Math */
+
+  /** Coerces a configured value into a usable, non-negative, finite number. */
+  private sanitizeValue(value: unknown): number {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric < 0) return 0;
+    return numeric;
+  }
+
+  /** The sanitized magnitude of every configured segment, in config order. */
+  private get values(): number[] {
+    const list = Array.isArray(this.segments) ? this.segments : [];
+    return list.map(segment => this.sanitizeValue(segment?.value));
+  }
+
+  /** The sum of every sanitized segment value. */
+  private get sum(): number {
+    return this.values.reduce((runningTotal, value) => runningTotal + value, 0);
+  }
+
+  /** The denominator the percentages are computed against. */
+  private get denominator(): number {
+    const sum = this.sum;
+    const total = Number(this.total);
+    if (Number.isFinite(total) && total > sum) return total;
+    return sum;
+  }
+
+  /** Each segment's share of the denominator, in config order. */
+  private get percentages(): number[] {
+    const denominator = this.denominator;
+    if (denominator <= 0) return this.values.map(() => 0);
+    return this.values.map(value => (value / denominator) * 100);
+  }
+
+  /**
+   * The index of the widest rendered segment. That segment is the one allowed to
+   * shrink, so it absorbs the overflow introduced by `minSegmentWidth` on the
+   * tiny ones and the row still adds up to exactly 100% of the track.
+   */
+  private get largestIndex(): number {
+    const values = this.values;
+    let largest = -1;
+    let largestValue = 0;
+    values.forEach((value, index) => {
+      if (value > largestValue) {
+        largestValue = value;
+        largest = index;
+      }
+    });
+    return largest;
+  }
+
+  /** Formats a percentage to one decimal, trimming a trailing `.0`. */
+  private formatPercentage(percentage: number): string {
+    if (!Number.isFinite(percentage)) return '0';
+    const rounded = Math.round(percentage * 10) / 10;
+    return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+  }
+
+  /* #endregion */
+
+  /* #region Text */
+
+  /** The default tooltip / aria text for a segment. */
+  private describeSegment(index: number): string {
+    const segment = this.segments?.[index];
+    const value = this.values[index] ?? 0;
+    const percentage = this.formatPercentage(this.percentages[index] ?? 0);
+    return `${segment?.label ?? ''}: ${value} (${percentage}%)`;
+  }
+
+  /** The tooltip content for a segment, honouring a per-segment override. */
+  private tooltipFor(index: number): string {
+    const override = this.segments?.[index]?.tooltip;
+    return override && override.length > 0
+      ? override
+      : this.describeSegment(index);
+  }
+
+  /**
+   * A single sentence describing the whole distribution, used as the track's
+   * accessible name so screen readers get the breakdown without tabbing it.
+   */
+  private get accessibleSummary(): string {
+    const list = Array.isArray(this.segments) ? this.segments : [];
+    const parts = list.map((_, index) => this.describeSegment(index));
+    const body = parts.length > 0 ? parts.join(', ') : 'No data';
+    return this.label ? `${this.label}: ${body}` : body;
+  }
+
+  /* #endregion */
+
+  /* #region Validation */
+
+  override updated(changedProperties: PropertyValues): void {
+    super.updated(changedProperties);
+    if (changedProperties.has('segments') || changedProperties.has('total')) {
+      this.validateConfig();
+    }
+  }
+
+  /** Logs invalid config the way `nile-progress-bar` reports out-of-range values. */
+  private validateConfig(): void {
+    const list = Array.isArray(this.segments) ? this.segments : [];
+
+    list.forEach((segment, index) => {
+      const numeric = Number(segment?.value);
+      if (!Number.isFinite(numeric)) {
+        console.error(
+          `[NileSegmentedProgressBar]: Invalid value (${String(
+            segment?.value
+          )}) detected at segment index ${index}. Value must be a finite number. Falling back to 0.`
+        );
+        return;
+      }
+      if (numeric < 0) {
+        console.error(
+          `[NileSegmentedProgressBar]: Invalid value (${numeric}) detected at segment index ${index}. Value must be greater than or equal to 0. Falling back to 0.`
+        );
+      }
+    });
+
+    const total = Number(this.total);
+    if (this.total !== undefined && this.total !== null) {
+      if (!Number.isFinite(total) || total < 0) {
+        console.error(
+          `[NileSegmentedProgressBar]: Invalid total (${String(
+            this.total
+          )}) detected. Total must be a finite number greater than or equal to 0. Falling back to the sum of the segment values.`
+        );
+      } else if (total < this.sum) {
+        console.error(
+          `[NileSegmentedProgressBar]: Invalid total (${total}) detected. Total must be greater than or equal to the sum of the segment values (${this.sum}). Falling back to the sum.`
+        );
+      }
+    }
+  }
+
+  /* #endregion */
+
+  /* #region Interaction */
+
+  private activate(index: number): void {
+    const segment = this.segments?.[index];
+    if (!segment) return;
+    this.emit('nile-segment-click', {
+      segment,
+      index,
+      percentage: this.percentages[index] ?? 0,
+    });
+  }
+
+  /**
+   * `Enter` and `Space` activate a segment or legend entry. The affordances are
+   * `role="button"` elements rather than native buttons, so activation is wired
+   * up explicitly and a key press never double-fires alongside a synthetic click.
+   */
+  private handleKeyDown(event: KeyboardEvent, index: number): void {
+    if (
+      event.key !== 'Enter' &&
+      event.key !== ' ' &&
+      event.key !== 'Spacebar'
+    ) {
+      return;
+    }
+    event.preventDefault();
+    this.activate(index);
+  }
+
+  /* #endregion */
+
+  /* #region Render */
+
+  private renderSegment(index: number): TemplateResult | typeof nothing {
+    const segment = this.segments[index];
+    const percentage = this.percentages[index] ?? 0;
+    if (percentage <= 0) return nothing;
+
+    const isLargest = index === this.largestIndex;
+    const minWidth = Math.max(0, Number(this.minSegmentWidth) || 0);
+    const description = this.describeSegment(index);
+
+    const bar = html`
+      <div
+        part="segment"
+        role="button"
+        tabindex="0"
+        data-index=${index}
+        class=${classMap({
+          'segmented-progress-bar__segment': true,
+          [`segmented-progress-bar__palette-${index % PALETTE_LENGTH}`]:
+            !segment.color,
+        })}
+        style=${styleMap({
+          flexBasis: `${percentage}%`,
+          // Only the widest segment may shrink, so it soaks up every pixel the
+          // min-width floors add to the row and the total stays at 100%.
+          flexShrink: isLargest ? '1' : '0',
+          minWidth: isLargest ? '0px' : `${minWidth}px`,
+          backgroundColor: segment.color || undefined,
+        })}
+        aria-label=${description}
+        @click=${() => this.activate(index)}
+        @keydown=${(event: KeyboardEvent) => this.handleKeyDown(event, index)}
+      ></div>
+    `;
+
+    if (!this.showTooltip) return bar;
+
+    return html`
+      <nile-lite-tooltip
+        size="small"
+        content=${this.tooltipFor(index)}
+        placement=${this.tooltipPlacement}
+      >
+        ${bar}
+      </nile-lite-tooltip>
+    `;
+  }
+
+  private renderLegendItem(index: number): TemplateResult {
+    const segment = this.segments[index];
+    const value = this.values[index] ?? 0;
+
+    return html`
+      <div
+        part="legend-item"
+        role="button"
+        tabindex="0"
+        data-index=${index}
+        class="segmented-progress-bar__legend-item"
+        aria-label=${this.describeSegment(index)}
+        @click=${() => this.activate(index)}
+        @keydown=${(event: KeyboardEvent) => this.handleKeyDown(event, index)}
+      >
+        <span
+          part="legend-swatch"
+          aria-hidden="true"
+          class=${classMap({
+            'segmented-progress-bar__legend-swatch': true,
+            [`segmented-progress-bar__palette-${index % PALETTE_LENGTH}`]:
+              !segment.color,
+          })}
+          style=${styleMap({ backgroundColor: segment.color || undefined })}
+        ></span>
+        <span part="legend-label" class="segmented-progress-bar__legend-label"
+          >${segment.label}</span
+        >
+        ${this.showValues
+          ? html`<span
+              part="legend-value"
+              class="segmented-progress-bar__legend-value"
+              >${value}</span
+            >`
+          : nothing}
+      </div>
+    `;
+  }
+
+  render(): TemplateResult {
+    const segments = Array.isArray(this.segments) ? this.segments : [];
+
+    return html`
+      <div
+        part="container"
+        class=${classMap({
+          'segmented-progress-bar': true,
+          'segmented-progress-bar--small': this.size === 'small',
+          'segmented-progress-bar--medium': this.size === 'medium',
+          'segmented-progress-bar--large': this.size === 'large',
+          'segmented-progress-bar--rounded': this.rounded,
+        })}
+      >
+        ${this.label
+          ? html`<div part="label" class="segmented-progress-bar__label">
+              ${this.label}
+            </div>`
+          : nothing}
+
+        <div
+          part="bar track"
+          class="segmented-progress-bar__track"
+          role="group"
+          aria-label=${this.accessibleSummary}
+        >
+          ${segments.map((_, index) => this.renderSegment(index))}
+        </div>
+
+        ${this.showLegend
+          ? html`<div part="legend" class="segmented-progress-bar__legend">
+              ${segments.map((_, index) => this.renderLegendItem(index))}
+            </div>`
+          : nothing}
+      </div>
+    `;
+  }
+
+  /* #endregion */
+}
+
+export default NileSegmentedProgressBar;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-segmented-progress-bar': NileSegmentedProgressBar;
+  }
+}

package/vscode-html-custom-data.json

@@ -5916,6 +5916,119 @@
         }
       ]
     },
+    {
+      "name": "nile-segmented-progress-bar",
+      "description": "Nile segmented progress bar component.\n\nEvents:\n\n  * `nile-segment-click` {} - Emitted when a segment or its legend entry is activated by click,\n`Enter` or `Space`. The `detail` contains `{ segment, index, percentage }`.\n\nAttributes:\n\n  * `segments` {`NileProgressSegment[]`} - The segments to distribute across the bar. This is the component's config.\n\n  * `label` {`string`} - Optional heading rendered above the bar. Nothing renders when empty.\n\n  * `show-legend` {`boolean`} - Renders the legend below the bar.\n\n  * `show-tooltip` {`boolean`} - Wraps every segment in a `nile-lite-tooltip`.\n\n  * `show-values` {`boolean`} - Renders the bold value alongside each legend label.\n\n  * `size` {`\"small\" | \"medium\" | \"large\"`} - The thickness of the bar.\n\n  * `total` {`number | undefined`} - Optional denominator. When omitted the denominator is the sum of the segment\nvalues, so the segments always fill 100%. When larger than the sum, the\nremainder renders as an unfilled track.\n\n  * `rounded` {`boolean`} - Rounds the bar's outer ends.\n\n  * `min-segment-width` {`number`} - Minimum rendered width, in pixels, of a non-zero segment. Guarantees sub-1%\nsegments stay a discernible sliver. The largest segment absorbs whatever\noverflow this introduces, so the row still totals exactly 100%.\n\n  * `tooltip-placement` {`\"left\" | \"right\" | \"top\" | \"top-start\" | \"top-end\" | \"right-start\" | \"right-end\" | \"bottom\" | \"bottom-start\" | \"bottom-end\" | \"left-start\" | \"left-end\" | \"auto\" | \"auto-start\" | \"auto-end\"`} - Passed straight through to `nile-lite-tooltip`'s `placement`.\n\nProperties:\n\n  * `styles` - \n\n  * `segments` {`NileProgressSegment[]`} - The segments to distribute across the bar. This is the component's config.\n\n  * `label` {`string`} - Optional heading rendered above the bar. Nothing renders when empty.\n\n  * `showLegend` {`boolean`} - Renders the legend below the bar.\n\n  * `showTooltip` {`boolean`} - Wraps every segment in a `nile-lite-tooltip`.\n\n  * `showValues` {`boolean`} - Renders the bold value alongside each legend label.\n\n  * `size` {`\"small\" | \"medium\" | \"large\"`} - The thickness of the bar.\n\n  * `total` {`number | undefined`} - Optional denominator. When omitted the denominator is the sum of the segment\nvalues, so the segments always fill 100%. When larger than the sum, the\nremainder renders as an unfilled track.\n\n  * `rounded` {`boolean`} - Rounds the bar's outer ends.\n\n  * `minSegmentWidth` {`number`} - Minimum rendered width, in pixels, of a non-zero segment. Guarantees sub-1%\nsegments stay a discernible sliver. The largest segment absorbs whatever\noverflow this introduces, so the row still totals exactly 100%.\n\n  * `tooltipPlacement` {`\"left\" | \"right\" | \"top\" | \"top-start\" | \"top-end\" | \"right-start\" | \"right-end\" | \"bottom\" | \"bottom-start\" | \"bottom-end\" | \"left-start\" | \"left-end\" | \"auto\" | \"auto-start\" | \"auto-end\"`} - Passed straight through to `nile-lite-tooltip`'s `placement`.\n\n  * `values` {`number[]`} - The sanitized magnitude of every configured segment, in config order.\n\n  * `sum` {`number`} - The sum of every sanitized segment value.\n\n  * `denominator` {`number`} - The denominator the percentages are computed against.\n\n  * `percentages` {`number[]`} - Each segment's share of the denominator, in config order.\n\n  * `largestIndex` {`number`} - The index of the widest rendered segment. That segment is the one allowed to\nshrink, so it absorbs the overflow introduced by `minSegmentWidth` on the\ntiny ones and the row still adds up to exactly 100% of the track.\n\n  * `accessibleSummary` {`string`} - A single sentence describing the whole distribution, used as the track's\naccessible name so screen readers get the breakdown without tabbing it.\n\n  * `override` - \n\n  * `BUBBLES` {`boolean`} - \n\n  * `COMPOSED` {`boolean`} - \n\n  * `CANCELABLE` {`boolean`} - ",
+      "attributes": [
+        {
+          "name": "segments",
+          "description": "`segments` {`NileProgressSegment[]`} - The segments to distribute across the bar. This is the component's config.\n\nProperty: segments\n\nDefault: "
+        },
+        {
+          "name": "label",
+          "description": "`label` {`string`} - Optional heading rendered above the bar. Nothing renders when empty.\n\nProperty: label\n\nDefault: "
+        },
+        {
+          "name": "show-legend",
+          "description": "`show-legend` {`boolean`} - Renders the legend below the bar.\n\nProperty: showLegend\n\nDefault: true",
+          "valueSet": "v"
+        },
+        {
+          "name": "show-tooltip",
+          "description": "`show-tooltip` {`boolean`} - Wraps every segment in a `nile-lite-tooltip`.\n\nProperty: showTooltip\n\nDefault: true",
+          "valueSet": "v"
+        },
+        {
+          "name": "show-values",
+          "description": "`show-values` {`boolean`} - Renders the bold value alongside each legend label.\n\nProperty: showValues\n\nDefault: true",
+          "valueSet": "v"
+        },
+        {
+          "name": "size",
+          "description": "`size` {`\"small\" | \"medium\" | \"large\"`} - The thickness of the bar.\n\nProperty: size\n\nDefault: medium",
+          "values": [
+            {
+              "name": "small"
+            },
+            {
+              "name": "medium"
+            },
+            {
+              "name": "large"
+            }
+          ]
+        },
+        {
+          "name": "total",
+          "description": "`total` {`number | undefined`} - Optional denominator. When omitted the denominator is the sum of the segment\nvalues, so the segments always fill 100%. When larger than the sum, the\nremainder renders as an unfilled track.\n\nProperty: total",
+          "values": []
+        },
+        {
+          "name": "rounded",
+          "description": "`rounded` {`boolean`} - Rounds the bar's outer ends.\n\nProperty: rounded\n\nDefault: true",
+          "valueSet": "v"
+        },
+        {
+          "name": "min-segment-width",
+          "description": "`min-segment-width` {`number`} - Minimum rendered width, in pixels, of a non-zero segment. Guarantees sub-1%\nsegments stay a discernible sliver. The largest segment absorbs whatever\noverflow this introduces, so the row still totals exactly 100%.\n\nProperty: minSegmentWidth\n\nDefault: 2"
+        },
+        {
+          "name": "tooltip-placement",
+          "description": "`tooltip-placement` {`\"left\" | \"right\" | \"top\" | \"top-start\" | \"top-end\" | \"right-start\" | \"right-end\" | \"bottom\" | \"bottom-start\" | \"bottom-end\" | \"left-start\" | \"left-end\" | \"auto\" | \"auto-start\" | \"auto-end\"`} - Passed straight through to `nile-lite-tooltip`'s `placement`.\n\nProperty: tooltipPlacement\n\nDefault: top",
+          "values": [
+            {
+              "name": "left"
+            },
+            {
+              "name": "right"
+            },
+            {
+              "name": "top"
+            },
+            {
+              "name": "top-start"
+            },
+            {
+              "name": "top-end"
+            },
+            {
+              "name": "right-start"
+            },
+            {
+              "name": "right-end"
+            },
+            {
+              "name": "bottom"
+            },
+            {
+              "name": "bottom-start"
+            },
+            {
+              "name": "bottom-end"
+            },
+            {
+              "name": "left-start"
+            },
+            {
+              "name": "left-end"
+            },
+            {
+              "name": "auto"
+            },
+            {
+              "name": "auto-start"
+            },
+            {
+              "name": "auto-end"
+            }
+          ]
+        },
+        {
+          "name": "onnile-segment-click",
+          "description": "`nile-segment-click` {} - Emitted when a segment or its legend entry is activated by click,\n`Enter` or `Space`. The `detail` contains `{ segment, index, percentage }`."
+        }
+      ]
+    },
     {
       "name": "nile-select",
       "description": "Events:\n\n  * `nile-change` {} - Emitted when the control's value changes.\n\n  * `nile-clear` {} - Emitted when the control's value is cleared.\n\n  * `nile-input` {} - Emitted when the control receives input.\n\n  * `nile-focus` {} - Emitted when the control gains focus.\n\n  * `nile-blur` {} - Emitted when the control loses focus.\n\n  * `nile-show` {} - Emitted when the select's menu opens.\n\n  * `nile-after-show` {} - Emitted after the select's menu opens and all animations are complete.\n\n  * `nile-hide` {} - Emitted when the select's menu closes.\n\n  * `nile-after-hide` {} - Emitted after the select's menu closes and all animations are complete.\n\n  * `nile-invalid` {} - Emitted when the form control has been checked for validity and its constraints aren't satisfied.\n\n  * `nile-search` {} - Emitted when the user types in the search input. The event payload includes the search query for backend search functionality.\n\n  * `nile-scroll` {} - Emitted when the user scrolls within the listbox. The event payload includes scroll position information.\n\n  * `nile-scroll-start` {} - Emitted when the user starts scrolling within the listbox.\n\n  * `nile-scroll-end` {} - Emitted when the user stops scrolling and reaches the bottom of the listbox (debounced).\n\nSlots:\n\n  * ` ` {} - The listbox options. Must be `<nile-option>` elements. You can use `<nile-divider>` to group items visually.\n\n  * `label` {} - The input's label. Alternatively, you can use the `label` attribute.\n\n  * `prefix` {} - Used to prepend a presentational icon or similar element to the combobox.\n\n  * `clear-icon` {} - An icon to use in lieu of the default clear icon.\n\n  * `expand-icon` {} - The icon to show when the control is expanded and collapsed. Rotates on open and close.\n\n  * `help-text` {} - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.\n\n  * `pre-footer` {} - Content to display at the bottom of the dropdown listbox. Useful for action buttons like \"Create New\". In multi-select mode, appears above the \"Show Selected\" / \"Clear All\" bar.\n\nAttributes:\n\n  * `size` {`\"small\" | \"medium\" | \"large\"`} - The select's size.\n\n  * `placeholder` {`string`} - Placeholder text to show as a hint when the select is empty.\n\n  * `searchEnabled` {`boolean`} - \n\n  * `legacy` {`boolean`} - \n\n  * `tickOnSelect` {`boolean`} - Variant: show a tick on the right of the selected option (single-select). Propagated to options.\n\n  * `internal-search-placeholder` {`string`} - \n\n  * `enableVisibilityEffect` {`boolean`} - \n\n  * `blockValueChange` {`boolean`} - \n\n  * `disableLocalSearch` {`boolean`} - \n\n  * `optionsLoading` {`boolean`} - \n\n  * `noWidthSync` {`boolean`} - \n\n  * `portal` {`boolean`} - When true, the listbox will be appended to the document body instead of the parent container.\nThis is useful when the parent has overflow: hidden, clip-path, or transform applied.\n\n  * `multiple` {`string | boolean`} - Allows more than one option to be selected.\n\n  * `helpText` {`string`} - \n\n  * `help-text` {`string`} - \n\n  * `autoResize` {`boolean`} - \n\n  * `error-message` {`string`} - \n\n  * `warning` {`boolean`} - Sets the input to a warning state, changing its visual appearance.\n\n  * `error` {`boolean`} - Sets the input to an error state, changing its visual appearance.\n\n  * `success` {`boolean`} - Sets the input to a success state, changing its visual appearance.\n\n  * `max-options-visible` {`number`} - The maximum number of selected options to show when `multiple` is true. After the maximum, \"+n\" will be shown to\nindicate the number of additional items that are selected. Set to 0 to remove the limit.\n\n  * `clearable` {`boolean`} - Adds a clear button when the select is not empty.\n\n  * `open` {`boolean`} - Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can\nuse the `show()` and `hide()` methods and this attribute will reflect the select's open state.\n\n  * `hoist` {`boolean`} - Enable this option to prevent the listbox from being clipped when the component is placed inside a container with\n`overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.\n\n  * `filled` {`boolean`} - Draws a filled select.\n\n  * `pill` {`boolean`} - Draws a pill-style select with rounded edges.\n\n  * `label` {`string`} - The select's label. If you need to display HTML, use the `label` slot instead.\n\n  * `placement` {`ComboboxPlacement`} - The preferred placement of the select's menu. Note that the actual placement may vary as needed to keep the listbox\ninside of the viewport.\n\n  * `showSelected` {`boolean`} - \n\n  * `enableTabClose` {`boolean`} - \n\n  * `showNoResults` {`boolean`} - \n\n  * `noResultsMessage` {`string`} - \n\n  * `data` - \n\n  * `enableVirtualScroll` {`boolean`} - \n\n  * `enableGroupHeader` {`boolean`} - To enable the group header in the select\n\n  * `autoFocusSearch` {`boolean`} - To auto focus the search input when the select is opened\n\n  * `loading` {`boolean`} - loading indicator for virtual select\n\n  * `stickyHeader` {`boolean`} - \n\n  * `descriptionSearchEnabled` {`boolean`} - \n\n  * `enableDescription` {`boolean`} - \n\n  * `allowHtmlLabel` {`boolean`} - \n\n  * `name` {`string`} - The name of the select, submitted as a name/value pair with form data.\n\n  * `value` {`string | string[]`} - The current value of the select, submitted as a name/value pair with form data. When `multiple` is enabled, the\nvalue will be a space-delimited list of values based on the options selected.\n\n  * `disabled` {`boolean`} - Disables the select control.\n\n  * `form` {`string`} - By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you\nto place the form control outside of a form and associate it with the form that has this `id`. The form must be in\nthe same document or shadow root for this to work.\n\n  * `required` {`boolean`} - The select's required attribute.\n\nProperties:\n\n  * `styles` - \n\n  * `formControlController` - \n\n  * `virtualScrollHelper` - \n\n  * `portalManager` - \n\n  * `hasSlotController` - \n\n  * `typeToSelectString` {`string`} - \n\n  * `typeToSelectTimeout` {`number`} - \n\n  * `scrollTimeout` {`number | undefined`} - \n\n  * `scrolling` {`boolean`} - \n\n  * `options` {`NileOption[]`} - \n\n  * `resizeController` - \n\n  * `visibilityManager` - \n\n  * `popup` - \n\n  * `combobox` {`HTMLSlotElement`} - \n\n  * `displayInput` {`HTMLInputElement`} - \n\n  * `valueInput` {`HTMLInputElement`} - \n\n  * `listbox` {`HTMLSlotElement`} - \n\n  * `hasFocus` {`boolean`} - \n\n  * `displayLabel` {`string`} - \n\n  * `currentOption` - \n\n  * `selectedOptions` {`NileOption[]`} - \n\n  * `oldValue` {`string | string[]`} - \n\n  * `size` {`\"small\" | \"medium\" | \"large\"`} - The select's size.\n\n  * `placeholder` {`string`} - Placeholder text to show as a hint when the select is empty.\n\n  * `searchValue` {`string`} - Placeholder text to show as a hint when the select is empty.\n\n  * `searchEnabled` {`boolean`} - \n\n  * `legacy` {`boolean`} - \n\n  * `tickOnSelect` {`boolean`} - Variant: show a tick on the right of the selected option (single-select). Propagated to options.\n\n  * `internalSearchPlaceHolder` {`string`} - \n\n  * `enableVisibilityEffect` {`boolean`} - \n\n  * `blockValueChange` {`boolean`} - \n\n  * `disableLocalSearch` {`boolean`} - \n\n  * `optionsLoading` {`boolean`} - \n\n  * `noWidthSync` {`boolean`} - \n\n  * `portal` {`boolean`} - When true, the listbox will be appended to the document body instead of the parent container.\nThis is useful when the parent has overflow: hidden, clip-path, or transform applied.\n\n  * `multiple` {`string | boolean`} - Allows more than one option to be selected.\n\n  * `helpText` {`string`} - \n\n  * `help_text` {`string`} - \n\n  * `autoResize` {`boolean`} - \n\n  * `errorMessage` {`string`} - \n\n  * `warning` {`boolean`} - Sets the input to a warning state, changing its visual appearance.\n\n  * `error` {`boolean`} - Sets the input to an error state, changing its visual appearance.\n\n  * `success` {`boolean`} - Sets the input to a success state, changing its visual appearance.\n\n  * `maxOptionsVisible` {`number`} - The maximum number of selected options to show when `multiple` is true. After the maximum, \"+n\" will be shown to\nindicate the number of additional items that are selected. Set to 0 to remove the limit.\n\n  * `clearable` {`boolean`} - Adds a clear button when the select is not empty.\n\n  * `open` {`boolean`} - Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can\nuse the `show()` and `hide()` methods and this attribute will reflect the select's open state.\n\n  * `hoist` {`boolean`} - Enable this option to prevent the listbox from being clipped when the component is placed inside a container with\n`overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.\n\n  * `filled` {`boolean`} - Draws a filled select.\n\n  * `pill` {`boolean`} - Draws a pill-style select with rounded edges.\n\n  * `label` {`string`} - The select's label. If you need to display HTML, use the `label` slot instead.\n\n  * `placement` {`ComboboxPlacement`} - The preferred placement of the select's menu. Note that the actual placement may vary as needed to keep the listbox\ninside of the viewport.\n\n  * `showSelected` {`boolean`} - \n\n  * `oldMaxOptionsVisible` {`number`} - \n\n  * `enableTabClose` {`boolean`} - \n\n  * `showNoResults` {`boolean`} - \n\n  * `noResultsMessage` {`string`} - \n\n  * `renderItemConfig` {`RenderItemConfig | undefined`} - Enhanced configuration for rendering items with support for display text, value, and search text\n\n  * `data` - \n\n  * `enableVirtualScroll` {`boolean`} - \n\n  * `enableGroupHeader` {`boolean`} - To enable the group header in the select\n\n  * `autoFocusSearch` {`boolean`} - To auto focus the search input when the select is opened\n\n  * `loading` {`boolean`} - loading indicator for virtual select\n\n  * `stickyHeader` {`boolean`} - \n\n  * `descriptionSearchEnabled` {`boolean`} - \n\n  * `enableDescription` {`boolean`} - \n\n  * `allowHtmlLabel` {`boolean`} - \n\n  * `handleWindowResize` - \n\n  * `handleWindowScroll` - \n\n  * `name` {`string`} - The name of the select, submitted as a name/value pair with form data.\n\n  * `value` {`string | string[]`} - The current value of the select, submitted as a name/value pair with form data. When `multiple` is enabled, the\nvalue will be a space-delimited list of values based on the options selected.\n\n  * `disabled` {`boolean`} - Disables the select control.\n\n  * `defaultValue` {`string | string[]`} - The default value of the form control. Primarily used for resetting the form control.\n\n  * `defaultChecked` {`boolean | undefined`} - \n\n  * `form` {`string`} - By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you\nto place the form control outside of a form and associate it with the form that has this `id`. The form must be in\nthe same document or shadow root for this to work.\n\n  * `pattern` {`string | undefined`} - \n\n  * `min` {`string | number | Date | undefined`} - \n\n  * `max` {`string | number | Date | undefined`} - \n\n  * `step` {`number | \"any\" | undefined`} - \n\n  * `required` {`boolean`} - The select's required attribute.\n\n  * `minlength` {`number | undefined`} - \n\n  * `maxlength` {`number | undefined`} - \n\n  * `validity` {`ValidityState`} - Gets the validity state object\n\n  * `validationMessage` {`string`} - Gets the validation message\n\n  * `checkValidity` - \n\n  * `getForm` - \n\n  * `reportValidity` - \n\n  * `setCustomValidity` - \n\n  * `BUBBLES` {`boolean`} - \n\n  * `COMPOSED` {`boolean`} - \n\n  * `CANCELABLE` {`boolean`} - ",