@reliability-design/web 1.4.1 → 1.4.2

package/dist/components/rel-autocomplete/rel-autocomplete.ts

@@ -0,0 +1,612 @@
+import { LitElement, html, css, nothing, PropertyValues, TemplateResult } from "lit";
+import { customElement, property, state, query } from "lit/decorators.js";
+import { repeat } from "lit/directives/repeat.js";
+import "@reliability-design/icons/rel-icon";
+import "../rel-textfield/rel-textfield.js";
+import type { RelTextfield, TextFieldSize, TextFieldVariant } from "../rel-textfield/rel-textfield.js";
+
+/** An item is a plain string or any object read through displayField/valueField. */
+export type AutocompleteItem = string | Record<string, unknown>;
+export type AutocompleteFilter = "contains" | "starts-with" | "none";
+export type AutocompleteSearchFn = (query: string) => Promise<AutocompleteItem[]>;
+
+interface NormalizedItem {
+  value: string;
+  label: string;
+  icon: string;
+  item: AutocompleteItem;
+}
+
+/**
+ * `<rel-autocomplete>` — searchable single-select type-ahead field.
+ *
+ * Composes `<rel-textfield>` for all field chrome (label, sizes, variants,
+ * states, icons) and adds a suggestion panel on top. Two data modes:
+ *   - local:  set `items`; typing filters them (`filter` mode)
+ *   - remote: set `searchFn`; input is debounced (`debounceMs`), queries are
+ *     latest-wins (stale responses discarded), and `items` is ignored
+ *
+ * The committed `value` is always the selected item's value string (its
+ * `valueField`) — typing alone emits `rel-change` with the raw text but does
+ * not change `value` until an item is picked (or the text exactly matches an
+ * item's label/value on Enter/blur).
+ */
+@customElement("rel-autocomplete")
+export class RelAutocomplete extends LitElement {
+  /** Local (or fallback initial) suggestion list. Ignored while searchFn drives results. */
+  @property({ type: Array }) items: AutocompleteItem[] = [];
+
+  /** Committed value — the selected item's valueField string ("" = none). */
+  @property({ type: String }) value: string = "";
+
+  /** Object key read for the row label when items are objects. */
+  @property({ type: String, attribute: "display-field" }) displayField: string = "label";
+
+  /** Object key read for the committed value when items are objects. */
+  @property({ type: String, attribute: "value-field" }) valueField: string = "value";
+
+  /** Local filtering mode. Ignored when searchFn is set (results arrive pre-filtered). */
+  @property({ type: String }) filter: AutocompleteFilter = "contains";
+
+  /** Async data source. When set, local filtering is bypassed entirely. */
+  @property({ attribute: false }) searchFn?: AutocompleteSearchFn;
+
+  /** Debounce for searchFn calls, in ms. */
+  @property({ type: Number, attribute: "debounce-ms" }) debounceMs: number = 300;
+
+  /** Minimum typed characters before the panel opens / searchFn fires. 0 = open on focus. */
+  @property({ type: Number, attribute: "min-search-length" }) minSearchLength: number = 1;
+
+  /** Optional cap on rendered suggestions (panel scrolls regardless). */
+  @property({ type: Number, attribute: "max-suggestions" }) maxSuggestions: number = Infinity;
+
+  /** Shows a trailing ✕ that clears the text and the committed value. */
+  @property({ type: Boolean }) clearable: boolean = false;
+
+  /** Externally-controlled loading state (internal searchFn loading is automatic). */
+  @property({ type: Boolean }) loading: boolean = false;
+
+  /** Row shown when a query yields nothing. */
+  @property({ type: String, attribute: "no-results-text" }) noResultsText: string = "No results found";
+
+  @property({ type: String, attribute: "loading-text" }) loadingText: string = "Loading…";
+
+  // ── Field chrome passthroughs (forwarded to the inner rel-textfield) ──
+  @property({ type: String }) label?: string;
+  @property({ type: String }) placeholder: string = "";
+  @property({ type: String }) size: TextFieldSize = "medium";
+  @property({ type: String }) variant: TextFieldVariant = "default";
+  @property({ type: Boolean, attribute: "floating-label" }) floatingLabel = false;
+  @property({ type: String, attribute: "prefix-icon" }) prefixIcon?: string;
+  @property({ type: Boolean }) disabled = false;
+  @property({ type: Boolean }) readonly = false;
+  @property({ type: Boolean }) required = false;
+  @property({ type: Boolean }) error = false;
+  @property({ type: String, attribute: "error-message" }) errorMessage?: string;
+  @property({ type: String, attribute: "helper-text" }) helperText?: string;
+  @property({ type: String }) name?: string;
+  @property({ type: Boolean, attribute: "full-width" }) fullWidth = true;
+
+  @state() private open = false;
+  @state() private inputText = "";
+  @state() private highlightedIndex = -1;
+  @state() private panelStyle = "";
+  @state() private searching = false;
+  /** searchFn results; null = idle/local mode (use items). */
+  @state() private remoteItems: AutocompleteItem[] | null = null;
+
+  @query("rel-textfield") private fieldEl!: RelTextfield;
+  @query(".ac-panel") private panelEl!: HTMLDivElement;
+
+  private uniqueId = `autocomplete-${Math.random().toString(36).slice(2)}`;
+  private debounceTimer?: ReturnType<typeof setTimeout>;
+  private searchSeq = 0;
+  /** Set while a selection/clear updates `value` internally, so willUpdate
+   *  doesn't overwrite the input text the way it does for external writes. */
+  private internalValueWrite = false;
+
+  static styles = css`
+    :host {
+      color: var(--rel-text-default);
+      display: block;
+      font-family: var(--rel-fonts-font-family);
+      width: 100%;
+    }
+
+    :host(:not([full-width])) {
+      display: inline-block;
+      width: auto;
+    }
+
+    /* ── Suggestion panel — mirrors rel-select's listbox so the two read as
+       one family (same tokens, radius, shadow, row styling). ── */
+    .ac-panel {
+      position: fixed;
+      z-index: 1001;
+      display: none;
+      box-sizing: border-box;
+      background: var(--rel-autocomplete-bg, var(--rel-bg-neutral));
+      border: 1px solid var(--rel-autocomplete-menu-border, var(--rel-border-default));
+      border-radius: var(--rel-autocomplete-menu-radius, var(--rel-border-radius-sm));
+      box-shadow: var(--rel-autocomplete-menu-shadow, var(--rel-shadows-shadow-300));
+      max-height: 360px;
+      overflow-y: auto;
+    }
+
+    .ac-panel[data-open] {
+      display: block;
+    }
+
+    .ac-options {
+      padding: 4px 0;
+    }
+
+    .ac-option {
+      display: flex;
+      align-items: center;
+      gap: var(--rel-spacing-xs);
+      padding: var(--rel-spacing-xs) 12px;
+      color: var(--rel-autocomplete-value-color, var(--rel-text-default));
+      cursor: pointer;
+      font-family: var(--rel-body-md-regular-font-family);
+      font-weight: var(--rel-body-md-regular-font-weight);
+      font-size: var(--rel-body-md-regular-font-size);
+      line-height: var(--rel-body-md-regular-line-height);
+      letter-spacing: var(--rel-body-md-regular-letter-spacing);
+    }
+
+    .ac-option:hover,
+    .ac-option.highlighted {
+      background: var(--rel-autocomplete-option-hover, var(--rel-bg-neutral-elevated-1));
+    }
+
+    .ac-option-icon {
+      flex-shrink: 0;
+      color: var(--rel-autocomplete-icon-color, var(--rel-text-default));
+    }
+
+    .ac-option-label {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    .ac-option-label b {
+      font-weight: var(--rel-body-md-medium-font-weight);
+    }
+
+    /* Status rows (loading / no results) — informational, not selectable */
+    .ac-status {
+      display: flex;
+      align-items: center;
+      gap: var(--rel-spacing-xs);
+      padding: var(--rel-spacing-xs) 12px;
+      color: var(--rel-autocomplete-status-color, var(--rel-text-body));
+      font-family: var(--rel-body-sm-regular-font-family);
+      font-weight: var(--rel-body-sm-regular-font-weight);
+      font-size: var(--rel-body-sm-regular-font-size);
+      line-height: var(--rel-body-sm-regular-line-height);
+      letter-spacing: var(--rel-body-sm-regular-letter-spacing);
+    }
+
+    .ac-spinner {
+      animation: ac-spin 0.9s linear infinite;
+    }
+
+    @keyframes ac-spin {
+      to {
+        transform: rotate(360deg);
+      }
+    }
+  `;
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeGlobalListeners();
+    clearTimeout(this.debounceTimer);
+  }
+
+  protected willUpdate(changed: PropertyValues<this>) {
+    // External value writes (attribute, Angular writeValue) sync the visible
+    // text to the matching item's label — or the raw value when unknown
+    // (e.g. remote item not currently in the list).
+    if (changed.has("value") && !this.internalValueWrite) {
+      const match = this.allItems.find((i) => i.value === this.value);
+      this.inputText = match ? match.label : this.value ?? "";
+    }
+    this.internalValueWrite = false;
+  }
+
+  /** Full normalized source list (remote results while searchFn drives, else items). */
+  private get allItems(): NormalizedItem[] {
+    const source = this.searchFn && this.remoteItems !== null ? this.remoteItems : this.items;
+    return source.map((item) => this.normalizeItem(item));
+  }
+
+  private normalizeItem(item: AutocompleteItem): NormalizedItem {
+    if (typeof item === "string") return { value: item, label: item, icon: "", item };
+    const rec = item;
+    const rawLabel = rec[this.displayField] ?? rec[this.valueField];
+    const label = rawLabel == null ? "" : String(rawLabel);
+    const rawValue = rec[this.valueField];
+    const value = rawValue == null ? label : String(rawValue);
+    const icon = typeof rec["icon"] === "string" ? (rec["icon"] as string) : "";
+    return { value, label, icon, item };
+  }
+
+  /** Suggestions for the current query — local filter only applies without searchFn. */
+  private get filteredItems(): NormalizedItem[] {
+    let list = this.allItems;
+    if (!this.searchFn && this.filter !== "none" && this.inputText) {
+      const q = this.inputText.toLowerCase();
+      list = list.filter((i) =>
+        this.filter === "starts-with"
+          ? i.label.toLowerCase().startsWith(q)
+          : i.label.toLowerCase().includes(q)
+      );
+    }
+    return Number.isFinite(this.maxSuggestions) ? list.slice(0, this.maxSuggestions) : list;
+  }
+
+  private get isLoading(): boolean {
+    return this.loading || this.searching;
+  }
+
+  private get queryLongEnough(): boolean {
+    return this.inputText.length >= this.minSearchLength;
+  }
+
+  // ── Panel open/close + positioning (same proven mechanics as rel-select:
+  // fixed panel, flip above when short on space, close on outside
+  // pointerdown and on any outside scroll instead of re-anchoring) ──
+
+  private addGlobalListeners() {
+    document.addEventListener("pointerdown", this.onOutsidePointerDown);
+    window.addEventListener("resize", this.updatePosition);
+    window.addEventListener("scroll", this.onPageScroll, true);
+  }
+
+  private removeGlobalListeners() {
+    document.removeEventListener("pointerdown", this.onOutsidePointerDown);
+    window.removeEventListener("resize", this.updatePosition);
+    window.removeEventListener("scroll", this.onPageScroll, true);
+  }
+
+  private onOutsidePointerDown = (e: PointerEvent) => {
+    if (!this.open) return;
+    if (e.composedPath().includes(this)) return;
+    this.commitExactMatch();
+    this.closePanel();
+  };
+
+  private onPageScroll = (e: Event) => {
+    if (!this.open) return;
+    if (e.composedPath()[0] === this.panelEl) return;
+    this.closePanel();
+  };
+
+  private openPanel() {
+    if (this.disabled || this.readonly || this.open) return;
+    this.open = true;
+    this.highlightedIndex = -1;
+    this.addGlobalListeners();
+    requestAnimationFrame(() => this.updatePosition());
+  }
+
+  private closePanel() {
+    if (!this.open) return;
+    this.open = false;
+    this.highlightedIndex = -1;
+    this.removeGlobalListeners();
+  }
+
+  private updatePosition = () => {
+    if (!this.fieldEl || !this.panelEl) return;
+
+    this.panelEl.setAttribute("data-open", "");
+
+    const t = this.fieldEl.getBoundingClientRect();
+    const c = this.panelEl.getBoundingClientRect();
+
+    let top = t.bottom + 4;
+    if (top + c.height > window.innerHeight - 8) {
+      top = Math.max(8, t.top - c.height - 4);
+    }
+
+    let left = t.left;
+    if (left + t.width > window.innerWidth - 8) {
+      left = Math.max(8, window.innerWidth - t.width - 8);
+    }
+
+    this.panelStyle = `top:${top}px;left:${left}px;width:${t.width}px;`;
+  };
+
+  /** Re-evaluates whether the panel should be showing for the current state. */
+  private syncPanel() {
+    const shouldShow =
+      this.queryLongEnough && (this.isLoading || this.filteredItems.length > 0 || !!this.inputText || this.minSearchLength === 0);
+    if (shouldShow) {
+      if (!this.open) this.openPanel();
+      else requestAnimationFrame(() => this.updatePosition());
+    } else {
+      this.closePanel();
+    }
+  }
+
+  // ── Data flow ──
+
+  private onFieldInput(e: CustomEvent<string>) {
+    e.stopPropagation();
+    this.inputText = e.detail;
+    this.highlightedIndex = -1;
+
+    // Re-emit as our own rel-change so consumers listen on <rel-autocomplete>
+    // (the inner textfield's event is stopped above).
+    this.dispatchEvent(
+      new CustomEvent<string>("rel-change", { detail: this.inputText, bubbles: true, composed: true })
+    );
+
+    if (this.searchFn) {
+      clearTimeout(this.debounceTimer);
+      if (!this.queryLongEnough) {
+        this.searchSeq++; // invalidate any in-flight query
+        this.searching = false;
+        this.remoteItems = null;
+        this.closePanel();
+        return;
+      }
+      this.searching = true;
+      this.syncPanel();
+      this.debounceTimer = setTimeout(() => this.runSearch(this.inputText), this.debounceMs);
+    } else {
+      this.syncPanel();
+    }
+  }
+
+  private async runSearch(query: string) {
+    const seq = ++this.searchSeq;
+    try {
+      const results = await this.searchFn!(query);
+      if (seq !== this.searchSeq) return; // stale — a newer query superseded this one
+      this.remoteItems = results ?? [];
+    } catch (err) {
+      if (seq !== this.searchSeq) return;
+      this.remoteItems = [];
+      this.dispatchEvent(
+        new CustomEvent("rel-search-error", { detail: { query, error: err }, bubbles: true, composed: true })
+      );
+    } finally {
+      if (seq === this.searchSeq) {
+        this.searching = false;
+        this.syncPanel();
+      }
+    }
+  }
+
+  private selectItem(item: NormalizedItem) {
+    this.internalValueWrite = true;
+    this.value = item.value;
+    this.inputText = item.label;
+    this.closePanel();
+    this.emitChanged(item);
+  }
+
+  /** Silent commit when typed text exactly matches an item (label or value, case-insensitive). */
+  private commitExactMatch() {
+    if (!this.inputText) return;
+    const q = this.inputText.toLowerCase();
+    const match = this.allItems.find(
+      (i) => i.label.toLowerCase() === q || i.value.toLowerCase() === q
+    );
+    if (match && match.value !== this.value) {
+      this.internalValueWrite = true;
+      this.value = match.value;
+      this.inputText = match.label;
+      this.emitChanged(match);
+    }
+  }
+
+  private emitChanged(item: NormalizedItem | null) {
+    this.dispatchEvent(
+      new CustomEvent("changed", {
+        detail: { value: this.value, item: item ? item.item : null },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  private clear() {
+    if (this.disabled || this.readonly) return;
+    const hadValue = !!this.value || !!this.inputText;
+    this.internalValueWrite = true;
+    this.value = "";
+    this.inputText = "";
+    this.searchSeq++;
+    this.searching = false;
+    this.remoteItems = null;
+    this.closePanel();
+    if (hadValue) {
+      this.dispatchEvent(new CustomEvent("rel-clear", { bubbles: true, composed: true }));
+      this.emitChanged(null);
+      this.dispatchEvent(
+        new CustomEvent<string>("rel-change", { detail: "", bubbles: true, composed: true })
+      );
+    }
+    this.fieldEl?.focus();
+  }
+
+  // ── Keyboard / focus ──
+
+  private onKeyDown(e: KeyboardEvent) {
+    if (this.disabled || this.readonly) return;
+    const filtered = this.filteredItems;
+
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        if (!this.open) {
+          if (this.queryLongEnough) this.openPanel();
+          return;
+        }
+        this.highlightedIndex = Math.min(filtered.length - 1, this.highlightedIndex + 1);
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        if (!this.open) return;
+        this.highlightedIndex = Math.max(0, this.highlightedIndex - 1);
+        break;
+      case "Enter":
+        if (this.open && this.highlightedIndex >= 0 && filtered[this.highlightedIndex]) {
+          e.preventDefault();
+          this.selectItem(filtered[this.highlightedIndex]);
+        } else {
+          // Free text stays free text — but an exact match commits.
+          this.commitExactMatch();
+          this.closePanel();
+        }
+        break;
+      case "Escape":
+        if (this.open) {
+          e.preventDefault();
+          this.closePanel();
+        }
+        break;
+      case "Tab":
+        this.commitExactMatch();
+        this.closePanel();
+        break;
+    }
+  }
+
+  private onFocusIn() {
+    if (this.disabled || this.readonly) return;
+    if (this.queryLongEnough && (this.filteredItems.length > 0 || this.minSearchLength === 0)) {
+      this.openPanel();
+    }
+  }
+
+  private onFocusOut(e: FocusEvent) {
+    const next = e.relatedTarget as Node | null;
+    if (next && (this.contains(next) || this.renderRoot.contains(next))) return;
+    // Focus genuinely left the component (outside pointerdown handles the
+    // click-away case before blur; this covers programmatic focus moves).
+    this.commitExactMatch();
+    this.closePanel();
+  }
+
+  /** Delegates focus to the inner textfield. */
+  focus() {
+    this.fieldEl?.focus();
+  }
+
+  /** Bolds the first occurrence of the query inside a suggestion label. */
+  private renderLabel(label: string): TemplateResult | string {
+    const q = this.inputText;
+    if (!q) return label;
+    const idx = label.toLowerCase().indexOf(q.toLowerCase());
+    if (idx < 0) return label;
+    return html`${label.slice(0, idx)}<b>${label.slice(idx, idx + q.length)}</b>${label.slice(idx + q.length)}`;
+  }
+
+  render() {
+    const filtered = this.filteredItems;
+    const panelId = `${this.uniqueId}-panel`;
+    const activeOptionId =
+      this.open && this.highlightedIndex >= 0 ? `${this.uniqueId}-option-${this.highlightedIndex}` : "";
+    const showClear = this.clearable && !!this.inputText && !this.disabled && !this.readonly;
+    const showNoResults = !this.isLoading && filtered.length === 0 && this.queryLongEnough && !!this.inputText;
+
+    // ARIA note: the real <input> lives in rel-textfield's shadow root, which
+    // aria-activedescendant can't reach across. The combobox role therefore
+    // sits on this wrapper (containing the field) in the same tree as the
+    // panel — the pragmatic pattern for nested shadow roots.
+    return html`
+      <div
+        class="ac-field"
+        role="combobox"
+        aria-haspopup="listbox"
+        aria-expanded="${this.open}"
+        aria-controls="${panelId}"
+        aria-activedescendant="${activeOptionId}"
+        @keydown="${this.onKeyDown}"
+        @focusin="${this.onFocusIn}"
+        @focusout="${this.onFocusOut}"
+      >
+        <rel-textfield
+          exportparts="label, control, input, helper, right-icon"
+          .label="${this.label}"
+          .placeholder="${this.placeholder}"
+          .value="${this.inputText}"
+          .size="${this.size}"
+          .variant="${this.variant}"
+          .floatingLabel="${this.floatingLabel}"
+          .prefixIcon="${this.prefixIcon}"
+          .disabled="${this.disabled}"
+          .readonly="${this.readonly}"
+          .required="${this.required}"
+          .error="${this.error}"
+          .errorMessage="${this.errorMessage}"
+          .helperText="${this.helperText}"
+          .name="${this.name}"
+          .rightIcon="${showClear ? "close" : undefined}"
+          .clickableRightIcon="${showClear}"
+          right-icon-aria-label="Clear"
+          @rel-change="${this.onFieldInput}"
+          @rel-right-icon-click="${this.clear}"
+        ></rel-textfield>
+      </div>
+
+      <div
+        id="${panelId}"
+        part="panel list"
+        class="ac-panel"
+        role="listbox"
+        aria-label="${this.label || "Suggestions"}"
+        style="${this.panelStyle}"
+        ?data-open="${this.open}"
+      >
+        ${this.isLoading
+          ? html`<div class="ac-status" role="status">
+              <rel-icon name="status-loading" size="sm" class="ac-spinner"></rel-icon>
+              <span>${this.loadingText}</span>
+            </div>`
+          : nothing}
+        ${showNoResults
+          ? html`<div class="ac-status">${this.noResultsText}</div>`
+          : nothing}
+        ${filtered.length > 0
+          ? html`<div class="ac-options">
+              ${repeat(
+                filtered,
+                (item) => item.value,
+                (item, index) => html`
+                  <div
+                    id="${this.uniqueId}-option-${index}"
+                    part="option"
+                    class="ac-option ${index === this.highlightedIndex ? "highlighted" : ""}"
+                    role="option"
+                    aria-selected="${item.value === this.value}"
+                    @mousedown="${(e: Event) => e.preventDefault()}"
+                    @click="${() => this.selectItem(item)}"
+                    @pointerenter="${() => (this.highlightedIndex = index)}"
+                  >
+                    ${item.icon
+                      ? html`<rel-icon name="${item.icon}" size="sm" class="ac-option-icon"></rel-icon>`
+                      : nothing}
+                    <span class="ac-option-label">${this.renderLabel(item.label)}</span>
+                  </div>
+                `
+              )}
+            </div>`
+          : nothing}
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "rel-autocomplete": RelAutocomplete;
+  }
+}

package/dist/components/rel-button/rel-button.ts

@@ -191,13 +191,27 @@ export class RelButton extends LitElement {
          pointer-events:none on the HOST would make it transparent to the
          pointer and suppress the cursor entirely. */
       cursor: not-allowed;
+      /* The disabled tokens are full-contrast pairs (light: #0B0B0B on
+         #C2C2C2, dark: #FFF on #404040), so on their own they render a
+         crisp button that reads as enabled. Dulling happens here instead —
+         same opacity mechanism the rest of the library uses. */
+      opacity: 0.5;
+    }
+
+    /* Only styles that actually carry a fill flatten to the neutral disabled
+       fill. Ghost/link/outline/static stay transparent so a disabled one
+       keeps its own shape rather than becoming a solid pill — which is what
+       made them look like ordinary enabled buttons. */
+    :host([disabled]) button.btn-primary,
+    :host([disabled]) button.btn-default,
+    :host([disabled]) button.btn-icon {
+      background-color: var(--rel-action-brand-fill-disabled) !important;
+      color: var(--rel-action-brand-label-icons-primary-disabled) !important;
+      border: none !important;
     }
 
     :host([disabled]) button {
       cursor: not-allowed;
-      background-color: var(--rel-action-brand-fill-disabled) !important;
-      color: var(--rel-action-brand-label-icons-primary-disabled) !important;
-      border: none !important;
       pointer-events: none;
       filter: none !important;
     }

package/dist/components/rel-checkbox/README.md

@@ -23,6 +23,7 @@ A tri-state checkbox component supporting checked, unchecked, and indeterminate
 | Name | Type | Default | Description |
 |------|------|---------|-------------|
 | `label` | `string` | `"Label"` | Label text displayed next to the checkbox |
+| `icon` | `string` | `""` | `rel-icon` name rendered between the checkbox and the label (label prefix icon). Unset renders no icon and reserves no space |
 | `supportingtext` | `string` | `""` | Helper text displayed below the checkbox and label |
 | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual and interaction state of the checkbox |
 | `status` | `"unchecked" \| "checked" \| "indeterminate"` | `"unchecked"` | Current checked state of the checkbox |