2 subjects listed
``` The distinctive part of this markup is the `aria-activedescendant` attribute. Keyboard focus **never leaves the field**; what navigates the list is not focus, it is a declaration. When the user presses an arrow key, the cursor in the field stays put, and in the tree, a different option is announced as active. This distinction preserves the field's text-editing behavior; if focus actually moved to the list, continuing to type would be impossible. The distinction's consequence for design is that **two separate indicators** are required: a focus ring in the field, an active-option highlight in the list. If either is missing, the user cannot see either where they are or what will be selected. ## Keyboard Contract | Key | Behavior | |---|---| | `Tab` | The field is a single tab stop; focus stays in the field even while the list is open. The list closes and focus moves out. | | `Arrow Down` | Opens the list and activates the first option if closed; moves to the next one if open. | | `Arrow Up` | Opens the list and activates the last option if closed; moves to the previous one if open. | | `Enter` | Makes the active option the value and closes the list. | | `Escape` | Closes the list and keeps the value if open; clears the field if closed. | | Typing keys | Opens the list and filters the options. | | `Home` / `End` | Moves the cursor within the text; does not belong to the list. | The arrow keys **not wrapping** at the ends is the point where this diverges from the radio group's contract. Wrapping in a radio group does not lose the user, because the entire group is on screen. Wrapping in a long list throws the user to the other end of the list with a single keystroke and makes it impossible for them to understand where they are without reading. The test below builds the contract as a state machine, checks it with key sequences, and in the last test scans every reachable state to verify three invariants. ```js // dropdown.test.mjs — the combobox's keyboard contract and invariants // Run: node --test dropdown.test.mjs import { test } from "node:test"; import assert from "node:assert/strict"; const SUBJECTS = ["Microeconomics", "Microbiology", "Music History", "Mathematics"]; const lower = (s) => s.toLocaleLowerCase("en-US"); const initial = () => ({ focusInField: true, open: false, active: null, text: "", value: null }); const options = (d) => SUBJECTS.filter((k) => lower(k).startsWith(lower(d.text))); function key(d, t) { const s = options(d); if (t === "ArrowDown") { if (!d.open) return { ...d, open: true, active: s.length ? 0 : null }; if (d.active === null) return { ...d, active: s.length ? 0 : null }; return { ...d, active: Math.min(d.active + 1, s.length - 1) }; // no wraparound } if (t === "ArrowUp") { if (!d.open) return { ...d, open: true, active: s.length ? s.length - 1 : null }; if (d.active === null) return { ...d, active: s.length ? s.length - 1 : null }; return { ...d, active: Math.max(d.active - 1, 0) }; } if (t === "Enter") { if (d.open && d.active !== null) return { ...d, open: false, active: null, text: s[d.active], value: s[d.active] }; return d; } if (t === "Escape") { if (d.open) return { ...d, open: false, active: null }; // close the list return { ...d, text: "", value: null }; // clear the field } if (t === "Tab") return { ...d, open: false, active: null, focusInField: false }; if (t.startsWith("type:")) return { ...d, text: d.text + t.slice(5), open: true, active: null }; return d; } const apply = (d, keys) => keys.reduce(key, d); test("when closed, ArrowDown opens the list and makes the first option active", () => { const d = apply(initial(), ["ArrowDown"]); assert.equal(d.open, true); assert.equal(options(d)[d.active], "Microeconomics"); }); test("when closed, ArrowUp opens the list and makes the last option active", () => { const d = apply(initial(), ["ArrowUp"]); assert.equal(options(d)[d.active], "Mathematics"); }); test("ArrowDown does not wrap to the start at the last option", () => { const d = apply(initial(), ["ArrowDown", "ArrowDown", "ArrowDown", "ArrowDown", "ArrowDown"]); assert.equal(d.active, 3); assert.equal(options(d)[d.active], "Mathematics"); }); test("Enter makes the active option the value and closes the list", () => { const d = apply(initial(), ["ArrowDown", "ArrowDown", "Enter"]); assert.equal(d.value, "Microbiology"); assert.equal(d.open, false); assert.equal(d.active, null); }); test("typing opens the list and filters it, the active option resets", () => { const d = apply(initial(), ["type:M", "type:i"]); assert.deepEqual(options(d), ["Microeconomics", "Microbiology"]); assert.equal(d.active, null); }); test("Escape closes the list first, clears the field on the second press", () => { const first = apply(initial(), ["type:M", "type:i", "ArrowDown", "Escape"]); assert.equal(first.open, false); assert.equal(first.text, "Mi"); const second = apply(first, ["Escape"]); assert.equal(second.text, ""); assert.equal(second.value, null); }); test("Tab closes the list and takes focus out of the field", () => { const d = apply(initial(), ["ArrowDown", "Tab"]); assert.equal(d.open, false); assert.equal(d.focusInField, false); }); test("with no match, the list opens but there is no active option", () => { const d = apply(initial(), ["type:Z"]); assert.deepEqual(options(d), []); const e = apply(d, ["ArrowDown"]); assert.equal(e.active, null); }); test("invariants hold across every reachable state, and focus stays in the field", () => { const KEYS = ["ArrowDown", "ArrowUp", "Enter", "Escape", "type:M", "type:i", "type:a"]; const stateKey = (d) => [d.open, d.active, d.text, d.value].join("|"); const seen = new Map([[stateKey(initial()), initial()]]); const queue = [initial()]; while (queue.length) { const d = queue.shift(); for (const t of KEYS) { const y = key(d, t); if (y.text.length > 3) continue; // scan length is capped if (seen.has(stateKey(y))) continue; seen.set(stateKey(y), y); queue.push(y); } } for (const d of seen.values()) { assert.equal(d.focusInField, true, "focus left the field"); if (!d.open) assert.equal(d.active, null, "active option remained in a closed list"); if (d.active !== null) { assert.ok(d.open, "list is closed while an active option exists"); assert.ok(d.active < options(d).length, "active option is not in the list"); } } console.log(` states scanned: ${seen.size}`); }); ``` ``` states scanned: 90 ✔ when closed, ArrowDown opens the list and makes the first option active (0.369792ms) ✔ when closed, ArrowUp opens the list and makes the last option active (0.049834ms) ✔ ArrowDown does not wrap to the start at the last option (0.061833ms) ✔ Enter makes the active option the value and closes the list (0.041791ms) ✔ typing opens the list and filters it, the active option resets (0.286583ms) ✔ Escape closes the list first, clears the field on the second press (0.056916ms) ✔ Tab closes the list and takes focus out of the field (0.042209ms) ✔ with no match, the list opens but there is no active option (0.049791ms) ✔ invariants hold across every reachable state, and focus stays in the field (0.932875ms) ℹ tests 9 ℹ suites 0 ℹ pass 9 ℹ fail 0 ℹ cancelled 0 ℹ skipped 0 ℹ todo 0 ℹ duration_ms 35.087417 ``` The duration values vary from run to run. The number of states scanned, though, depends on the typing length being capped at three characters; when the cap is removed, the state space is infinite, because the user can type as many characters as they want. ## Reading the Invariants The last test checks three rules, and all three are places where the screen and the tree can diverge. **No active option can remain in a closed list.** If the list is closed without clearing the `aria-activedescendant` value, an option that no longer exists in the tree appears active. This leads the user to think they are still inside the list after closing it. **The active option has to be in the list.** When the list shortens after filtering, the old index becomes invalid. In the test, this is prevented by the `type:` keys resetting the active option; without the reset, the declaration would point to an id that no longer exists and would drop silently. **Focus does not leave the field.** All ninety states satisfy the condition. This follows from the pattern's definition: an implementation where focus moves to the list is not the `aria-activedescendant` pattern, it is a different pattern, and in that case the ability to filter by typing is lost. ## Measurable Constraints **4.1.2 Name, Role, Value.** The field's name, its combobox role, its open/closed state, and its selected value have to be programmatically readable. In a hand-built component, all four are written separately. **2.4.7 Focus Visible.** Real focus is in the field; its indicator has to be present in the field. The active-option highlight does not replace this indicator, it is added to it. **1.4.11 Non-text Contrast.** The active-option highlight has to separate from neighboring rows by at least 3:1. A highlight built only with a light gray surface does not satisfy this measure. **1.4.13 Content on Hover or Focus.** The opened list is content that appears on focus, and it has to satisfy three conditions: it has to be dismissible with `Escape`, the pointer has to be able to move over the list, and it must not disappear without the user taking an action. **Announcing the filter result.** How many options remain in a list filtered by typing is conveyed with a polite live region. The announcement is sent not on every keystroke but after typing stops; otherwise, the announcement queue prevents the user from hearing what they type. ## Common Mistake **Focus moving to the list.** Catching it means trying to type while the list is open: if the character typed does not go to the field, focus has shifted. In this pattern, the fix is not moving focus back, it is switching to the `aria-activedescendant` declaration. **The open/closed state not being updated.** The `aria-expanded` value staying `false` while the list is visible on screen is the tree contradicting the screen. Catching it is a uniqueness and consistency check: the list's visibility is compared against the declared state. **The native element being abandoned for the sake of appearance.** The hand-built component's cost is ten declarations, and each is a separate source of error. Catching it happens at the specification stage: if none of the requirements — extra information in the option row, filtering by typing, or fetching from the server — exists, the native element is the decision. ## Summary - A dropdown list is for option sets that are enumerable but do not fit on screen; a radio group is used for fewer than five options, and search is used for sets that are not known in advance. - The `select` element brings the role, name, state, value, and keyboard contract together; its cost is that the opened list's appearance cannot be controlled from the presentation layer. - The hand-built component reproduces ten separate declarations; it is chosen only when inline extra information, filtering by typing, or fetching from the server is required. - In the `aria-activedescendant` pattern, focus does not leave the field; what navigates the list is a declaration, and this is why two separate visual indicators are required. - Arrow keys do not wrap at the ends; wrapping behavior belongs only to radio groups whose entirety sits on screen. - No active-option declaration can remain in a closed list, and the active option always has to be in the filtered list; resetting the declaration after filtering guarantees this. ## Next Step The four components so far were each taken up on their own: a button, a field, a group, a list. The borrowing form, by contrast, carries all of them together and raises new questions. By what measure are fields grouped? When a form is split into three steps, how is the step change announced, and where does focus go? If submission fails, does the user lose what they typed? The next lesson specifies the form as a whole and shows where components that are correct individually can work incorrectly together.