@edvizion/astro-components 0.1.0

package/src/components/SchoolSearch/school-search-element.ts

@@ -0,0 +1,993 @@
+import { baseComponentStyles } from '../../theme/component-styles';
+import { cssVar } from '../../theme/tokens';
+import {
+  DEFAULT_LIMIT,
+  DEFAULT_RECOMMEND_ENDPOINT,
+  DEFAULT_SEARCH_ENDPOINT,
+  MAX_LIMIT,
+  MAX_OFFSET,
+  RECOMMENDED_SCHOOL_ID,
+  recommendSchool,
+  SchoolSearchError,
+  searchSchools,
+  validateQuery,
+} from './api';
+import type {
+  SchoolRecommendation,
+  SchoolSearchErrorDetail,
+  SchoolSearchEventDetail,
+  SchoolSearchResult,
+  SelectedSchool,
+} from './types';
+import { normalizeStateCode, US_STATES } from './us-states';
+
+export const TAG_NAME = 'edv-school-search';
+
+const styles = /* css */ `
+  ${baseComponentStyles}
+
+  .root { display: grid; gap: calc(${cssVar('space')} * 2); }
+  .search-row { display: flex; gap: ${cssVar('space')}; }
+  .search-row .edv-control { flex: 1 1 auto; min-width: 0; }
+
+  .status { margin: 0; font-size: ${cssVar('fontSizeSmall')}; color: ${cssVar('colorTextMuted')}; }
+  .status[data-tone='error'] { color: ${cssVar('colorDanger')}; font-weight: ${cssVar('fontWeightStrong')}; }
+
+  .results {
+    list-style: none;
+    margin: 0;
+    padding: calc(${cssVar('space')} * 0.5);
+    max-height: 22rem;
+    overflow-y: auto;
+    background: ${cssVar('colorSurface')};
+    border: 1px solid ${cssVar('colorBorder')};
+    border-radius: ${cssVar('radius')};
+    box-shadow: ${cssVar('shadow')};
+  }
+  .option {
+    display: grid;
+    gap: 0.125rem;
+    padding: ${cssVar('space')} calc(${cssVar('space')} * 1.5);
+    border-radius: ${cssVar('radiusSmall')};
+    cursor: pointer;
+  }
+  .option:hover, .option[data-active] { background: ${cssVar('colorHighlight')}; }
+  .results:focus-visible .option[data-active] {
+    outline: ${cssVar('focusRingWidth')} solid ${cssVar('colorFocusRing')};
+    outline-offset: -${cssVar('focusRingWidth')};
+  }
+  .option-name { font-weight: ${cssVar('fontWeightStrong')}; }
+  .option-meta { font-size: ${cssVar('fontSizeSmall')}; color: ${cssVar('colorTextMuted')}; }
+
+  .selection {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: calc(${cssVar('space')} * 2);
+    padding: calc(${cssVar('space')} * 1.5);
+    background: ${cssVar('colorSurfaceMuted')};
+    border: 1px solid ${cssVar('colorBorder')};
+    border-radius: ${cssVar('radius')};
+  }
+  .selection-text { display: grid; gap: 0.125rem; min-width: 0; }
+  .selection-name { font-weight: ${cssVar('fontWeightStrong')}; }
+  .selection-meta { font-size: ${cssVar('fontSizeSmall')}; color: ${cssVar('colorTextMuted')}; }
+
+  .recommend-prompt { margin: 0; font-size: ${cssVar('fontSizeSmall')}; color: ${cssVar('colorTextMuted')}; }
+  .edv-link {
+    font: inherit;
+    color: ${cssVar('colorPrimary')};
+    font-weight: ${cssVar('fontWeightStrong')};
+    background: none;
+    border: 0;
+    padding: 0;
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+    cursor: pointer;
+  }
+  .edv-link:hover { color: ${cssVar('colorPrimaryHover')}; }
+
+  .recommend {
+    display: grid;
+    gap: calc(${cssVar('space')} * 1.5);
+    padding: calc(${cssVar('space')} * 2);
+    background: ${cssVar('colorSurface')};
+    border: 1px solid ${cssVar('colorBorder')};
+    border-radius: ${cssVar('radius')};
+  }
+  .recommend-title { margin: 0; font-weight: ${cssVar('fontWeightStrong')}; }
+  .recommend .edv-hint { margin: 0; }
+  .recommend textarea.edv-control { padding-block: ${cssVar('space')}; resize: vertical; min-height: 4.5rem; }
+  .actions { display: flex; flex-wrap: wrap; gap: ${cssVar('space')}; }
+
+  [hidden] { display: none !important; }
+`;
+
+const template = document.createElement('template');
+template.innerHTML = /* html */ `
+  <style>${styles}</style>
+  <div class="root" part="root">
+    <div class="field" part="state-field">
+      <label class="edv-label" for="state" part="label">
+        <span data-ref="stateLabel">State</span><span class="edv-required" aria-hidden="true">*</span>
+      </label>
+      <select id="state" class="edv-control" part="select" required aria-required="true" aria-describedby="state-error">
+        <option value="">Select a state</option>
+        ${US_STATES.map((s) => `<option value="${s.code}">${s.name}</option>`).join('')}
+      </select>
+      <p id="state-error" class="edv-error" part="error" hidden></p>
+    </div>
+
+    <div class="field" part="school-field" data-ref="searchField">
+      <label class="edv-label" for="query" part="label">
+        <span data-ref="schoolLabel">School</span><span class="edv-required" data-ref="schoolRequired" aria-hidden="true" hidden>*</span>
+      </label>
+      <div class="search-row" role="search" part="search-row">
+        <input
+          id="query"
+          class="edv-control"
+          part="input"
+          type="search"
+          autocomplete="off"
+          spellcheck="false"
+          enterkeyhint="search"
+          maxlength="200"
+          aria-describedby="hint school-error status"
+        />
+        <button id="search" class="edv-button" part="button search-button" type="button">Search</button>
+      </div>
+      <p id="hint" class="edv-hint" part="hint"></p>
+      <p id="school-error" class="edv-error" part="error" hidden></p>
+    </div>
+
+    <div class="selection" part="selection" data-ref="selection" hidden>
+      <div class="selection-text">
+        <span class="edv-visually-hidden">Selected school:</span>
+        <span class="selection-name" part="selection-name" data-ref="selectionName"></span>
+        <span class="selection-meta" part="selection-meta" data-ref="selectionMeta"></span>
+      </div>
+      <button class="edv-button edv-button--secondary" part="button change-button" type="button" data-ref="change">
+        Change<span class="edv-visually-hidden"> school</span>
+      </button>
+    </div>
+
+    <p id="status" class="status" part="status" role="status" aria-live="polite" aria-atomic="true"></p>
+
+    <ul id="results" class="results" part="results" role="listbox" tabindex="0" aria-label="School search results" hidden></ul>
+    <button class="edv-button edv-button--secondary" part="button more-button" type="button" data-ref="more" hidden>
+      Show more results
+    </button>
+
+    <p class="recommend-prompt" part="recommend-prompt" data-ref="recommendPrompt" hidden>
+      Can’t find your school?
+      <button class="edv-link" part="recommend-button" type="button" data-ref="recommendOpen">Recommend it</button>
+    </p>
+
+    <div class="recommend" part="recommend" role="group" aria-labelledby="recommend-title" data-ref="recommendPanel" hidden>
+      <p id="recommend-title" class="recommend-title">Recommend a school</p>
+      <p id="recommend-hint" class="edv-hint" part="hint" data-ref="recommendHint"></p>
+      <div class="field">
+        <label class="edv-label" for="recommend-name" part="label">
+          School name<span class="edv-required" aria-hidden="true">*</span>
+        </label>
+        <input
+          id="recommend-name"
+          class="edv-control"
+          part="input recommend-input"
+          type="text"
+          autocomplete="off"
+          maxlength="200"
+          aria-required="true"
+          aria-describedby="recommend-hint recommend-error"
+        />
+      </div>
+      <div class="field">
+        <label class="edv-label" for="recommend-notes" part="label">Notes (optional)</label>
+        <textarea
+          id="recommend-notes"
+          class="edv-control"
+          part="textarea recommend-notes"
+          rows="3"
+          placeholder="City, website, or anything that helps us find it"
+        ></textarea>
+      </div>
+      <p id="recommend-error" class="edv-error" part="error" role="alert" hidden></p>
+      <div class="actions">
+        <button class="edv-button" part="button recommend-submit" type="button" data-ref="recommendSubmit">
+          Submit recommendation
+        </button>
+        <button class="edv-button edv-button--secondary" part="button recommend-cancel" type="button" data-ref="recommendCancel">
+          Cancel
+        </button>
+      </div>
+    </div>
+  </div>
+`;
+
+interface FormState {
+  state: string | null;
+  school: SelectedSchool | null;
+}
+
+/**
+ * `<edv-school-search>` — a form-associated school picker backed by the
+ * Edvizion School Directory.
+ *
+ * Form value: the selected school's `edvizionId` (submitted under `name`).
+ * Validity: `valueMissing` when `required` and no state / no school is chosen.
+ * Search runs only on Enter or the Search button — never while typing.
+ *
+ * If the school is missing, the user can recommend it. A successful
+ * recommendation sets the value to `sch_00000000-0000-0000-0000-000000000000`; details are on
+ * `selectedSchool.recommendation`.
+ *
+ * Events: `input` + `change` when the selection changes; `edv-search` after
+ * results load; `edv-search-error` when a search fails; `edv-recommend` /
+ * `edv-recommend-error` for recommendations.
+ */
+export class EdvSchoolSearchElement extends HTMLElement {
+  static formAssociated = true;
+  static observedAttributes = [
+    'required',
+    'disabled',
+    'school-label',
+    'state-label',
+    'placeholder',
+    'hint',
+    'default-state',
+    'no-recommend',
+  ];
+
+  readonly #internals: ElementInternals;
+  readonly #shadow: ShadowRoot;
+
+  #stateSelect!: HTMLSelectElement;
+  #queryInput!: HTMLInputElement;
+  #searchButton!: HTMLButtonElement;
+  #results!: HTMLUListElement;
+  #more!: HTMLButtonElement;
+  #status!: HTMLParagraphElement;
+  #hint!: HTMLParagraphElement;
+  #stateError!: HTMLParagraphElement;
+  #schoolError!: HTMLParagraphElement;
+  #searchField!: HTMLElement;
+  #selection!: HTMLElement;
+  #selectionName!: HTMLElement;
+  #selectionMeta!: HTMLElement;
+  #change!: HTMLButtonElement;
+  #recommendPrompt!: HTMLElement;
+  #recommendOpenButton!: HTMLButtonElement;
+  #recommendPanel!: HTMLElement;
+  #recommendHint!: HTMLElement;
+  #recommendName!: HTMLInputElement;
+  #recommendNotes!: HTMLTextAreaElement;
+  #recommendError!: HTMLElement;
+  #recommendSubmit!: HTMLButtonElement;
+  #recommendCancel!: HTMLButtonElement;
+
+  #state: string | null = null;
+  #school: SelectedSchool | null = null;
+  #hits: SchoolSearchResult[] = [];
+  #activeIndex = -1;
+  #lastSearch: { query: string; state: string } | null = null;
+  #abort: AbortController | null = null;
+  #recommendOpen = false;
+  #recommendAbort: AbortController | null = null;
+  #formDisabled = false;
+  #customError = '';
+  #showErrors = false;
+  #initialized = false;
+
+  constructor() {
+    super();
+    this.#internals = this.attachInternals();
+    this.#shadow = this.attachShadow({ mode: 'open', delegatesFocus: true });
+    this.#shadow.appendChild(template.content.cloneNode(true));
+
+    const $ = <T extends Element>(selector: string) => this.#shadow.querySelector(selector) as T;
+    this.#stateSelect = $('#state');
+    this.#queryInput = $('#query');
+    this.#searchButton = $('#search');
+    this.#results = $('#results');
+    this.#status = $('#status');
+    this.#hint = $('#hint');
+    this.#stateError = $('#state-error');
+    this.#schoolError = $('#school-error');
+    this.#more = $('[data-ref="more"]');
+    this.#searchField = $('[data-ref="searchField"]');
+    this.#selection = $('[data-ref="selection"]');
+    this.#selectionName = $('[data-ref="selectionName"]');
+    this.#selectionMeta = $('[data-ref="selectionMeta"]');
+    this.#change = $('[data-ref="change"]');
+    this.#recommendPrompt = $('[data-ref="recommendPrompt"]');
+    this.#recommendOpenButton = $('[data-ref="recommendOpen"]');
+    this.#recommendPanel = $('[data-ref="recommendPanel"]');
+    this.#recommendHint = $('[data-ref="recommendHint"]');
+    this.#recommendName = $('#recommend-name');
+    this.#recommendNotes = $('#recommend-notes');
+    this.#recommendError = $('#recommend-error');
+    this.#recommendSubmit = $('[data-ref="recommendSubmit"]');
+    this.#recommendCancel = $('[data-ref="recommendCancel"]');
+
+    this.#stateSelect.addEventListener('change', () => this.#onStateChange());
+    this.#queryInput.addEventListener('keydown', (e) => this.#onQueryKeydown(e));
+    this.#searchButton.addEventListener('click', () => this.#runSearch());
+    this.#more.addEventListener('click', () => this.#runSearch({ append: true }));
+    this.#results.addEventListener('keydown', (e) => this.#onResultsKeydown(e));
+    this.#results.addEventListener('click', (e) => this.#onResultsClick(e));
+    this.#results.addEventListener('focus', () => {
+      if (this.#activeIndex < 0 && this.#hits.length) this.#setActive(0);
+    });
+    this.#change.addEventListener('click', () => this.#clearSelection({ focus: true }));
+    this.#recommendOpenButton.addEventListener('click', () => this.#openRecommend());
+    this.#recommendCancel.addEventListener('click', () => this.#closeRecommend({ focus: true }));
+    this.#recommendSubmit.addEventListener('click', () => this.#submitRecommendation());
+    this.#recommendName.addEventListener('keydown', (e) => {
+      if (e.key !== 'Enter') return;
+      e.preventDefault();
+      this.#submitRecommendation();
+    });
+    this.#recommendPanel.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape') this.#closeRecommend({ focus: true });
+    });
+    // Native `input` events are composed and would escape as if the host's
+    // value changed. The host fires its own input/change only on selection.
+    this.#shadow.addEventListener('input', (e) => e.stopPropagation());
+    // The host is what the form reports as invalid; mirror that inside.
+    this.addEventListener('invalid', () => {
+      this.#showErrors = true;
+      this.#renderErrors();
+    });
+  }
+
+  connectedCallback() {
+    if (!this.#initialized) {
+      this.#initialized = true;
+      this.#applyInitialValue();
+    }
+    this.#renderText();
+    this.#render();
+  }
+
+  disconnectedCallback() {
+    this.#abort?.abort();
+    this.#recommendAbort?.abort();
+  }
+
+  attributeChangedCallback(name: string) {
+    if (!this.#initialized) return;
+    if (name === 'default-state' && !this.#state) this.#setState(this.#defaultState, { clear: false });
+    this.#renderText();
+    this.#render();
+  }
+
+  // ---- Form-associated lifecycle -------------------------------------------
+
+  formResetCallback() {
+    this.#abort?.abort();
+    this.#recommendAbort?.abort();
+    this.#showErrors = false;
+    this.#queryInput.value = '';
+    this.#resetResults();
+    this.#applyInitialValue();
+    this.#render();
+  }
+
+  formDisabledCallback(disabled: boolean) {
+    this.#formDisabled = disabled;
+    this.#render();
+  }
+
+  formStateRestoreCallback(saved: unknown) {
+    if (typeof saved !== 'string') return;
+    try {
+      const { state, school } = JSON.parse(saved) as FormState;
+      this.#state = normalizeStateCode(state);
+      this.#school = school?.edvizionId ? school : null;
+      this.#render();
+    } catch {
+      /* ignore unreadable saved state */
+    }
+  }
+
+  // ---- Public form-control API ---------------------------------------------
+
+  /** The selected school's `edvizionId`, or `""`. */
+  get value(): string {
+    return this.#school?.edvizionId ?? '';
+  }
+  set value(id: string) {
+    // A bare id carries no display name; prefer `selectSchool()` when you have one.
+    this.#school = id ? { edvizionId: id, name: this.#school?.edvizionId === id ? this.#school.name : id } : null;
+    this.#render();
+  }
+
+  /** The selected school, including display fields when chosen from results. */
+  get selectedSchool(): SelectedSchool | null {
+    return this.#school ? { ...this.#school } : null;
+  }
+
+  /** The chosen USPS state code, or `""`. */
+  get state(): string {
+    return this.#state ?? '';
+  }
+  set state(code: string) {
+    this.#setState(normalizeStateCode(code), { clear: true, notify: false });
+  }
+
+  /** Select a school programmatically. Does not fire `change`. */
+  selectSchool(school: SelectedSchool | null) {
+    this.#school = school?.edvizionId ? { ...school } : null;
+    if (this.#school?.state && !this.#state) this.#state = normalizeStateCode(this.#school.state);
+    this.#resetResults();
+    this.#render();
+  }
+
+  get name() {
+    return this.getAttribute('name') ?? '';
+  }
+  set name(v: string) {
+    this.setAttribute('name', v);
+  }
+  get required() {
+    return this.hasAttribute('required');
+  }
+  set required(v: boolean) {
+    this.toggleAttribute('required', v);
+  }
+  get disabled() {
+    return this.hasAttribute('disabled');
+  }
+  set disabled(v: boolean) {
+    this.toggleAttribute('disabled', v);
+  }
+
+  get form() {
+    return this.#internals.form;
+  }
+  get labels() {
+    return this.#internals.labels;
+  }
+  get type() {
+    return TAG_NAME;
+  }
+  get validity() {
+    return this.#internals.validity;
+  }
+  get validationMessage() {
+    return this.#internals.validationMessage;
+  }
+  get willValidate() {
+    return this.#internals.willValidate;
+  }
+  checkValidity() {
+    return this.#internals.checkValidity();
+  }
+  reportValidity() {
+    return this.#internals.reportValidity();
+  }
+  setCustomValidity(message: string) {
+    this.#customError = message ?? '';
+    this.#syncForm();
+  }
+
+  // ---- Configuration -------------------------------------------------------
+
+  get #endpoint() {
+    return this.getAttribute('endpoint') || DEFAULT_SEARCH_ENDPOINT;
+  }
+  get #recommendEndpoint() {
+    return this.getAttribute('recommend-endpoint') || DEFAULT_RECOMMEND_ENDPOINT;
+  }
+  get #canRecommend() {
+    return !this.hasAttribute('no-recommend');
+  }
+  get #limit() {
+    const n = Number.parseInt(this.getAttribute('limit') ?? '', 10);
+    return Number.isFinite(n) && n > 0 ? Math.min(n, MAX_LIMIT) : DEFAULT_LIMIT;
+  }
+  get #defaultState() {
+    const raw = this.getAttribute('default-state');
+    const code = normalizeStateCode(raw);
+    if (raw && !code) console.warn(`<${TAG_NAME}>: ignoring unsupported default-state "${raw}".`);
+    return code;
+  }
+  get #isDisabled() {
+    return this.disabled || this.#formDisabled;
+  }
+
+  #applyInitialValue() {
+    const id = this.getAttribute('value');
+    const state = this.#defaultState;
+    this.#school = id ? { edvizionId: id, name: this.getAttribute('value-name') || id, state } : null;
+    this.#state = state;
+  }
+
+  // ---- Behaviour -----------------------------------------------------------
+
+  #onStateChange() {
+    this.#setState(normalizeStateCode(this.#stateSelect.value), { clear: true, notify: true });
+    if (this.#state) this.#queryInput.focus();
+  }
+
+  #setState(code: string | null, { clear, notify = false }: { clear: boolean; notify?: boolean }) {
+    if (code === this.#state) return;
+    this.#state = code;
+    if (clear) {
+      this.#abort?.abort();
+      this.#resetResults();
+      const hadSchool = this.#school !== null;
+      this.#school = null;
+      this.#setStatus('');
+      this.#render();
+      if (hadSchool && notify) this.#emitChange();
+    } else {
+      this.#render();
+    }
+  }
+
+  #onQueryKeydown(event: KeyboardEvent) {
+    if (event.key === 'Enter') {
+      // Never let Enter implicitly submit a surrounding form.
+      event.preventDefault();
+      this.#runSearch();
+    } else if (event.key === 'ArrowDown' && !this.#results.hidden && this.#hits.length) {
+      event.preventDefault();
+      this.#results.focus();
+      this.#setActive(Math.max(this.#activeIndex, 0));
+    }
+  }
+
+  async #runSearch({ append = false } = {}) {
+    if (this.#isDisabled) return;
+    if (!this.#state) {
+      this.#showErrors = true;
+      this.#renderErrors();
+      this.#stateSelect.focus();
+      return;
+    }
+
+    const query = append && this.#lastSearch ? this.#lastSearch.query : this.#queryInput.value;
+    const problem = validateQuery(query);
+    if (problem) {
+      this.#setStatus(problem, 'error');
+      this.#queryInput.setAttribute('aria-invalid', 'true');
+      return;
+    }
+    this.#queryInput.removeAttribute('aria-invalid');
+
+    const offset = append ? this.#hits.length : 0;
+    if (offset > MAX_OFFSET) return;
+
+    this.#abort?.abort();
+    const abort = new AbortController();
+    this.#abort = abort;
+    const state = this.#state;
+    this.#setBusy(true);
+    this.#setStatus(append ? 'Loading more schools…' : 'Searching…');
+
+    try {
+      const response = await searchSchools({
+        query,
+        state,
+        limit: this.#limit,
+        offset,
+        endpoint: this.#endpoint,
+        signal: abort.signal,
+      });
+      if (abort.signal.aborted) return;
+
+      this.#lastSearch = { query: query.trim(), state };
+      const previousCount = append ? this.#hits.length : 0;
+      this.#hits = append ? [...this.#hits, ...response.results] : response.results;
+      const hasMore = response.results.length === this.#limit && this.#hits.length <= MAX_OFFSET;
+      this.#renderResults(hasMore);
+
+      const total = this.#hits.length;
+      const stateName = US_STATES.find((s) => s.code === state)?.name ?? state;
+      if (total === 0) {
+        this.#setStatus(`No schools in ${stateName} match “${query.trim()}”. Try a different name or city.`);
+      } else if (append) {
+        this.#setStatus(`Loaded ${total - previousCount} more. ${total} schools shown.`);
+        this.#setActive(previousCount);
+        this.#results.focus();
+      } else {
+        this.#setStatus(
+          `${total}${hasMore ? '+' : ''} ${total === 1 ? 'school' : 'schools'} found in ${stateName}. ` +
+            'Press the down arrow to browse results, Enter to choose.',
+        );
+      }
+
+      this.dispatchEvent(
+        new CustomEvent<SchoolSearchEventDetail>('edv-search', {
+          bubbles: true,
+          composed: true,
+          detail: { query: query.trim(), state, offset, results: response.results },
+        }),
+      );
+    } catch (error) {
+      if (abort.signal.aborted || (error as Error)?.name === 'AbortError') return;
+      const e =
+        error instanceof SchoolSearchError
+          ? error
+          : new SchoolSearchError('School search failed. Please try again.', null, null, null);
+      if (!append) {
+        this.#hits = [];
+        this.#renderResults(false);
+      }
+      this.#setStatus(e.message, 'error');
+      this.dispatchEvent(
+        new CustomEvent<SchoolSearchErrorDetail>('edv-search-error', {
+          bubbles: true,
+          composed: true,
+          detail: { status: e.status, code: e.code, requestId: e.requestId, message: e.message },
+        }),
+      );
+    } finally {
+      if (this.#abort === abort) {
+        this.#abort = null;
+        this.#setBusy(false);
+      }
+    }
+  }
+
+  #onResultsKeydown(event: KeyboardEvent) {
+    const last = this.#hits.length - 1;
+    switch (event.key) {
+      case 'ArrowDown':
+        this.#setActive(Math.min(this.#activeIndex + 1, last));
+        break;
+      case 'ArrowUp':
+        if (this.#activeIndex <= 0) {
+          this.#queryInput.focus();
+          this.#setActive(-1);
+        } else {
+          this.#setActive(this.#activeIndex - 1);
+        }
+        break;
+      case 'Home':
+        this.#setActive(0);
+        break;
+      case 'End':
+        this.#setActive(last);
+        break;
+      case 'Enter':
+      case ' ':
+        if (this.#activeIndex >= 0) this.#choose(this.#hits[this.#activeIndex]);
+        break;
+      case 'Escape':
+        this.#queryInput.focus();
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+  }
+
+  #onResultsClick(event: MouseEvent) {
+    const option = (event.target as Element).closest<HTMLElement>('[role="option"]');
+    if (!option) return;
+    const hit = this.#hits[Number(option.dataset.index)];
+    if (hit) this.#choose(hit);
+  }
+
+  #choose(hit: SchoolSearchResult) {
+    this.#school = { edvizionId: hit.edvizionId, name: hit.name, city: hit.city, state: hit.state };
+    this.#showErrors = false;
+    this.#setStatus(`Selected ${hit.name}.`);
+    this.#render();
+    this.#change.focus();
+    this.#emitChange();
+  }
+
+  #clearSelection({ focus }: { focus: boolean }) {
+    if (!this.#school) return;
+    this.#school = null;
+    this.#setStatus(this.#hits.length ? `${this.#hits.length} results available.` : '');
+    this.#render();
+    if (focus) this.#queryInput.focus();
+    this.#emitChange();
+  }
+
+  #openRecommend() {
+    if (this.#isDisabled || !this.#state) return;
+    this.#recommendOpen = true;
+    if (!this.#recommendName.value) this.#recommendName.value = this.#lastSearch?.query ?? this.#queryInput.value.trim();
+    this.#setRecommendError('');
+    this.#render();
+    this.#recommendName.focus();
+  }
+
+  #closeRecommend({ focus }: { focus: boolean }) {
+    this.#recommendAbort?.abort();
+    this.#recommendOpen = false;
+    this.#setRecommendError('');
+    this.#render();
+    if (focus) this.#recommendOpenButton.focus();
+  }
+
+  async #submitRecommendation() {
+    if (this.#isDisabled || !this.#state || this.#recommendAbort) return;
+    const name = this.#recommendName.value.trim();
+    if (name.length < 2) {
+      this.#setRecommendError('Enter the school’s name.');
+      this.#recommendName.focus();
+      return;
+    }
+    const notes = this.#recommendNotes.value.trim();
+    const state = this.#state;
+
+    const abort = new AbortController();
+    this.#recommendAbort = abort;
+    this.#setRecommendError('');
+    this.#recommendSubmit.disabled = true;
+    this.#recommendSubmit.setAttribute('aria-busy', 'true');
+    this.#setStatus('Sending your recommendation…');
+
+    try {
+      const response = await recommendSchool({
+        name,
+        state,
+        notes,
+        endpoint: this.#recommendEndpoint,
+        signal: abort.signal,
+      });
+      if (abort.signal.aborted) return;
+
+      const recommendation: SchoolRecommendation = {
+        name: response.name || name,
+        state: response.state || state,
+        notes: notes || null,
+        requestId: response.requestId ?? null,
+        submittedAt: response.submittedAt ?? null,
+      };
+      this.#recommendOpen = false;
+      this.#recommendName.value = '';
+      this.#recommendNotes.value = '';
+      this.#school = {
+        edvizionId: RECOMMENDED_SCHOOL_ID,
+        name: recommendation.name,
+        state: recommendation.state,
+        recommendation,
+      };
+      this.#showErrors = false;
+      this.#setStatus(`Thanks — we received your recommendation for ${recommendation.name}. We’ll review it and add it to the directory.`);
+      this.#render();
+      this.#change.focus();
+      this.dispatchEvent(
+        new CustomEvent<SchoolRecommendation>('edv-recommend', { bubbles: true, composed: true, detail: recommendation }),
+      );
+      this.#emitChange();
+    } catch (error) {
+      if (abort.signal.aborted || (error as Error)?.name === 'AbortError') return;
+      const e =
+        error instanceof SchoolSearchError
+          ? error
+          : new SchoolSearchError('Your recommendation could not be sent. Please try again.', null, null, null);
+      this.#setStatus('');
+      this.#setRecommendError(e.message);
+      this.#recommendName.focus();
+      this.dispatchEvent(
+        new CustomEvent<SchoolSearchErrorDetail>('edv-recommend-error', {
+          bubbles: true,
+          composed: true,
+          detail: { status: e.status, code: e.code, requestId: e.requestId, message: e.message },
+        }),
+      );
+    } finally {
+      if (this.#recommendAbort === abort) {
+        this.#recommendAbort = null;
+        this.#recommendSubmit.disabled = this.#isDisabled;
+        this.#recommendSubmit.removeAttribute('aria-busy');
+      }
+    }
+  }
+
+  #setRecommendError(message: string) {
+    this.#recommendError.textContent = message;
+    this.#recommendError.hidden = !message;
+    this.#recommendName.toggleAttribute('aria-invalid', Boolean(message));
+  }
+
+  #emitChange() {
+    this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+    this.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+
+  // ---- Rendering -----------------------------------------------------------
+
+  #resetResults() {
+    this.#hits = [];
+    this.#activeIndex = -1;
+    this.#lastSearch = null;
+    this.#recommendAbort?.abort();
+    this.#recommendOpen = false;
+    this.#recommendName.value = '';
+    this.#recommendNotes.value = '';
+    this.#setRecommendError('');
+    this.#renderResults(false);
+  }
+
+  #setActive(index: number) {
+    this.#activeIndex = index;
+    const options = this.#results.querySelectorAll<HTMLElement>('[role="option"]');
+    options.forEach((el, i) => {
+      el.toggleAttribute('data-active', i === index);
+      el.setAttribute('aria-selected', String(i === index));
+    });
+    const active = options[index];
+    if (active) {
+      this.#results.setAttribute('aria-activedescendant', active.id);
+      active.scrollIntoView({ block: 'nearest' });
+    } else {
+      this.#results.removeAttribute('aria-activedescendant');
+    }
+  }
+
+  #renderResults(hasMore: boolean) {
+    this.#results.replaceChildren(
+      ...this.#hits.map((hit, index) => {
+        const li = document.createElement('li');
+        li.id = `option-${index}`;
+        li.className = 'option';
+        li.setAttribute('part', 'option');
+        li.setAttribute('role', 'option');
+        li.setAttribute('aria-selected', 'false');
+        li.dataset.index = String(index);
+        li.dataset.edvizionId = hit.edvizionId;
+
+        const name = document.createElement('span');
+        name.className = 'option-name';
+        name.setAttribute('part', 'option-name');
+        name.textContent = hit.name;
+
+        const meta = document.createElement('span');
+        meta.className = 'option-meta';
+        meta.setAttribute('part', 'option-meta');
+        meta.textContent = describe(hit);
+
+        li.append(name, meta);
+        return li;
+      }),
+    );
+    this.#activeIndex = -1;
+    this.#results.removeAttribute('aria-activedescendant');
+    this.#more.hidden = !hasMore;
+    this.#render();
+  }
+
+  #setStatus(message: string, tone: 'info' | 'error' = 'info') {
+    this.#status.textContent = message;
+    this.#status.dataset.tone = tone;
+  }
+
+  #setBusy(busy: boolean) {
+    this.toggleAttribute('busy', busy);
+    this.#searchButton.disabled = busy || this.#isDisabled || !this.#state;
+    this.#searchButton.setAttribute('aria-busy', String(busy));
+    this.#more.disabled = busy;
+    this.#internals.states?.[busy ? 'add' : 'delete']?.('busy');
+  }
+
+  #renderText() {
+    const text = (attr: string, fallback: string) => this.getAttribute(attr) || fallback;
+    this.#shadow.querySelector('[data-ref="stateLabel"]')!.textContent = text('state-label', 'State');
+    this.#shadow.querySelector('[data-ref="schoolLabel"]')!.textContent = text('school-label', 'School');
+    this.#queryInput.placeholder = text('placeholder', 'School name or city');
+  }
+
+  #render() {
+    const disabled = this.#isDisabled;
+    const hasState = Boolean(this.#state);
+    const selected = this.#school;
+
+    this.#stateSelect.value = this.#state ?? '';
+    this.#stateSelect.disabled = disabled;
+    this.#queryInput.disabled = disabled || !hasState;
+    this.#searchButton.disabled = disabled || !hasState || this.hasAttribute('busy');
+    this.#change.disabled = disabled;
+    this.#more.disabled = disabled || this.hasAttribute('busy');
+    (this.#shadow.querySelector('[data-ref="schoolRequired"]') as HTMLElement).hidden = !this.required;
+
+    this.#hint.textContent = hasState
+      ? this.getAttribute('hint') || 'Search by school name or city, then press Enter.'
+      : 'Select a state to search for a school.';
+
+    this.#searchField.hidden = Boolean(selected);
+    this.#selection.hidden = !selected;
+    if (selected) {
+      this.#selectionName.textContent = selected.name;
+      const place = [selected.city, selected.state].filter(Boolean).join(', ');
+      this.#selectionMeta.textContent =
+        selected.edvizionId === RECOMMENDED_SCHOOL_ID
+          ? ['Recommended — pending review', place].filter(Boolean).join(' · ')
+          : place;
+    }
+
+    const recommending = this.#recommendOpen && !selected && !disabled && this.#canRecommend && hasState;
+    this.#results.hidden = Boolean(selected) || this.#hits.length === 0 || disabled || recommending;
+    if (this.#results.hidden) this.#more.hidden = true;
+
+    this.#recommendPanel.hidden = !recommending;
+    this.#recommendPrompt.hidden =
+      recommending || Boolean(selected) || disabled || !this.#canRecommend || !this.#lastSearch;
+    this.#recommendSubmit.disabled = disabled || Boolean(this.#recommendAbort);
+    this.#recommendCancel.disabled = disabled;
+    this.#recommendName.disabled = disabled;
+    this.#recommendNotes.disabled = disabled;
+    if (recommending) {
+      const stateName = US_STATES.find((s) => s.code === this.#state)?.name ?? this.#state;
+      this.#recommendHint.textContent =
+        `Tell us about a school in ${stateName} that’s missing. We’ll review it before adding it to the directory.`;
+    }
+
+    this.#internals.states?.[selected ? 'add' : 'delete']?.('has-value');
+    this.#syncForm();
+  }
+
+  #syncForm() {
+    const formState: FormState = { state: this.#state, school: this.#school };
+    this.#internals.setFormValue(this.#school?.edvizionId || null, JSON.stringify(formState));
+
+    if (this.#isDisabled) {
+      this.#internals.setValidity({});
+    } else if (this.#customError) {
+      this.#internals.setValidity({ customError: true }, this.#customError, this.#queryInput);
+    } else if (this.required && !this.#state) {
+      this.#internals.setValidity({ valueMissing: true }, 'Select a state.', this.#stateSelect);
+    } else if (this.required && !this.#school) {
+      this.#internals.setValidity({ valueMissing: true }, 'Search for and select a school.', this.#queryInput);
+    } else {
+      this.#internals.setValidity({});
+    }
+    this.#renderErrors();
+  }
+
+  #renderErrors() {
+    const validity = this.#internals.validity;
+    const show = this.#showErrors && !validity.valid;
+    const stateMissing = !this.#state && (this.required || this.#showErrors);
+    const stateMessage = show && stateMissing ? 'Select a state.' : '';
+    const schoolMessage = show && !stateMissing ? this.#internals.validationMessage : '';
+
+    this.#stateError.textContent = stateMessage;
+    this.#stateError.hidden = !stateMessage;
+    this.#stateSelect.setAttribute('aria-invalid', String(Boolean(stateMessage)));
+
+    this.#schoolError.textContent = schoolMessage;
+    this.#schoolError.hidden = !schoolMessage;
+    if (schoolMessage) this.#queryInput.setAttribute('aria-invalid', 'true');
+    else if (!this.#status.textContent || this.#status.dataset.tone !== 'error')
+      this.#queryInput.removeAttribute('aria-invalid');
+
+    this.#internals.states?.[show ? 'add' : 'delete']?.('user-invalid');
+  }
+}
+
+function describe(hit: SchoolSearchResult): string {
+  const parts: string[] = [];
+  const place = [hit.city, hit.state].filter(Boolean).join(', ');
+  if (place) parts.push(place);
+  const grades = formatGradeSpan(hit.gradeSpan);
+  if (grades) parts.push(grades);
+  if (hit.type) parts.push(hit.type.charAt(0).toUpperCase() + hit.type.slice(1));
+  return parts.join(' · ');
+}
+
+function formatGradeSpan(span: SchoolSearchResult['gradeSpan']): string {
+  if (!span?.low || !span?.high) return '';
+  const grade = (g: string) => (/^\d+$/.test(g) ? String(Number(g)) : g.toUpperCase());
+  const low = grade(span.low);
+  const high = grade(span.high);
+  return low === high ? `Grade ${low}` : `Grades ${low}–${high}`;
+}
+
+if (!customElements.get(TAG_NAME)) {
+  customElements.define(TAG_NAME, EdvSchoolSearchElement);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'edv-school-search': EdvSchoolSearchElement;
+  }
+}