@a11y-context/mcp-server 0.1.0

package/corpus/web/react/components/listbox.basic.md

@@ -0,0 +1,263 @@
+---
+id: listbox.basic
+title: Listbox
+stack: web/react
+status: beta
+latest_version: 0.1.0
+tags: [listbox, roving-tabindex, aria-activedescendant, multi-select, selection, form]
+aliases: [option list, select list, single-select list, multi-select list, transfer list source, inline listbox, choice list, selectable list]
+summary: An always-visible list of selectable options using role="listbox" and role="option", supporting single or multiple selection with roving tabindex or aria-activedescendant.
+---
+
+# Listbox
+
+Pattern ID: `listbox.basic`
+
+An always-visible list of selectable options using `role="listbox"` and `role="option"`, supporting single or multiple selection with roving tabindex or `aria-activedescendant`.
+
+This pattern is a permanently visible selection list. There is no trigger button, popup, or expand and collapse, and options carry plain content only.
+
+## Use When
+- Use when the choices are permanently visible with no popup or expansion (e.g., an inline "Playback quality" list, a settings choice shown in place).
+- Use when the user selects one option or multiple options from plain-text labels (e.g., "Select genres to follow", the source column of a transfer list).
+
+## Do Not Use When
+- Do not use when a collapsed popup value picker is expected (use `select.native`, or `select.basic` for a custom-styled one).
+- Do not use when the user types to filter the options (use `combobox.autocomplete`).
+- Do not use when the options must contain interactive elements such as links or buttons (use `grid.basic`).
+- Do not use when the user chooses among many independent on and off settings (use `checkbox.group`).
+- Do not use when the control performs actions rather than holding a selection (use `menu.basic`).
+
+## Must Haves
+
+### Roles & structure
+- The container is an element with `role="listbox"` and an accessible name via `aria-label` or `aria-labelledby`.
+- Each option is an element with `role="option"` and `aria-selected="true|false"`.
+- Options contain no interactive child elements (no links, buttons, inputs, or nested controls).
+
+### State & properties
+- For multiple selection, the listbox has `aria-multiselectable="true"`.
+
+### Keyboard
+- Arrow Down and Arrow Up move the active option to the next and previous option.
+- Home and End move the active option to the first and last option.
+- A printable character performs type-ahead, moving the active option to the next option whose label begins with the typed characters.
+- For single-select, selection is operable from the keyboard alone.
+- For multi-select, the selection is operable from the keyboard alone.
+  - Space toggles `aria-selected` on the active option.
+  - Shift+Arrow Up and Shift+Arrow Down extend the selection to the adjacent option.
+  - Ctrl+A (Cmd+A on macOS) selects all options.
+  - No modifier-only click is required to select an option.
+
+### Focus
+- Manage the active option with either roving tabindex or `aria-activedescendant`, and apply one approach consistently.
+  - Roving tabindex: the focused option has `tabindex="0"` and all other options have `tabindex="-1"`.
+  - `aria-activedescendant`: the `role="listbox"` element has `tabindex="0"` and its `aria-activedescendant` references the active option's ID.
+- Scripting keeps the active option scrolled into view.
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) around the active option.
+
+## Customizable
+- Roving tabindex and `aria-activedescendant` are equal alternatives. Choose one and apply it consistently.
+- For single-select, selection may follow focus (each Arrow move updates `aria-selected`) or require an explicit Enter or Space to commit. Selection-follows-focus suits short lists where each change is inexpensive; explicit selection suits lists where moving through options should not trigger side effects.
+- The multi-select keyboard model above (Space to toggle, Shift+Arrow to extend, Ctrl+A to select all) may be extended with Shift+Home, Shift+End, and Ctrl+Space, provided Space toggle and Arrow navigation remain intact.
+
+## Don'ts
+- Do not place interactive elements (links, buttons, checkboxes, inputs) inside `role="option"` elements.
+- Do not require Ctrl or Cmd plus click as the only way to select multiple options.
+- Do not use `role="menu"` or `role="menuitem"` for a selection list.
+- Do not leave `aria-selected` out of sync with the visible selection state.
+
+## Golden Pattern
+
+Structural reference for AI coding assistants — semantics, focus, and keyboard behavior. Styling, copy, and demo data are illustrative.
+
+```jsx
+"use client";
+
+function Listbox({ label, options, multiple = false }) {
+  const optionRefs = useRef([]);
+  const typeahead = useRef({ query: "", timer: null });
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [selected, setSelected] = useState(() => (multiple ? new Set() : null));
+  const [hasFocus, setHasFocus] = useState(false);
+
+  const labelId = useId();
+
+  function isSelected(value) {
+    return multiple ? selected.has(value) : selected === value;
+  }
+
+  function toggleAt(index) {
+    const { value } = options[index];
+    if (multiple) {
+      setSelected((prev) => {
+        const next = new Set(prev);
+        if (next.has(value)) next.delete(value);
+        else next.add(value);
+        return next;
+      });
+    } else {
+      setSelected(value);
+    }
+  }
+
+  function focusOption(index) {
+    setActiveIndex(index);
+    // Roving tabindex: move DOM focus to the newly active option.
+    optionRefs.current[index]?.focus();
+  }
+
+  // Type-ahead: accumulate typed characters briefly, then jump to the
+  // first option whose label matches, so a keyboard user can reach a
+  // distant option without arrowing through every one.
+  function typeAhead(char) {
+    const state = typeahead.current;
+    clearTimeout(state.timer);
+    state.query += char.toLowerCase();
+    state.timer = setTimeout(() => {
+      state.query = "";
+    }, 500);
+    const match = options.findIndex((opt) =>
+      opt.label.toLowerCase().startsWith(state.query)
+    );
+    if (match >= 0) focusOption(match);
+  }
+
+  function onKeyDown(e) {
+    const last = options.length - 1;
+    let next = activeIndex;
+
+    switch (e.key) {
+      case "ArrowDown":
+        next = Math.min(last, activeIndex + 1);
+        break;
+      case "ArrowUp":
+        next = Math.max(0, activeIndex - 1);
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = last;
+        break;
+      case " ":
+        // Space toggles in multi-select and commits in single-select;
+        // preventDefault stops the page from scrolling.
+        e.preventDefault();
+        toggleAt(activeIndex);
+        return;
+      case "Enter":
+        // Single-select: Enter commits the active option.
+        if (!multiple) toggleAt(activeIndex);
+        return;
+      default:
+        if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+          typeAhead(e.key);
+        }
+        return;
+    }
+
+    e.preventDefault();
+    focusOption(next);
+    // Single-select: selection follows focus.
+    if (!multiple) toggleAt(next);
+  }
+
+  return (
+    <div>
+      <span id={labelId}>{label}</span>
+      <ul
+        role="listbox"
+        aria-labelledby={labelId}
+        aria-multiselectable={multiple ? "true" : undefined}
+        onKeyDown={onKeyDown}
+        onFocus={() => setHasFocus(true)}
+        onBlur={() => setHasFocus(false)}
+        style={{
+          listStyle: "none",
+          margin: 0,
+          padding: 0,
+          border: "1px solid",
+          maxHeight: 200,
+          overflow: "auto",
+        }}
+      >
+        {options.map((opt, idx) => {
+          const isActive = idx === activeIndex;
+          return (
+            <li
+              key={opt.value}
+              ref={(el) => (optionRefs.current[idx] = el)}
+              role="option"
+              aria-selected={isSelected(opt.value) ? "true" : "false"}
+              // Roving tabindex: only the active option is in the tab order.
+              tabIndex={isActive ? 0 : -1}
+              onClick={() => {
+                focusOption(idx);
+                toggleAt(idx);
+              }}
+              style={{
+                display: "flex",
+                alignItems: "center",
+                gap: 8,
+                padding: "6px 8px",
+                cursor: "default",
+                // Focus ring keys to real DOM focus, not just active index,
+                // so it disappears when the listbox is not focused.
+                outline: isActive && hasFocus ? "2px solid" : "none",
+                outlineOffset: 1,
+              }}
+            >
+              {/* Selection is conveyed by aria-selected; the mark is decorative. */}
+              <span aria-hidden="true" style={{ width: "1em" }}>
+                {isSelected(opt.value) ? "✓" : ""}
+              </span>
+              {opt.label}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+
+export function ListboxDemo() {
+  return (
+    <div>
+      <Listbox label="Playback quality" options={QUALITY} />
+      <Listbox label="Genres to follow" options={GENRES} multiple />
+    </div>
+  );
+}
+
+const QUALITY = [
+  { value: "auto", label: "Auto" },
+  { value: "1080p", label: "1080p" },
+  { value: "720p", label: "720p" },
+  { value: "480p", label: "480p" },
+];
+
+const GENRES = [
+  { value: "drama", label: "Drama" },
+  { value: "comedy", label: "Comedy" },
+  { value: "thriller", label: "Thriller" },
+  { value: "documentary", label: "Documentary" },
+  { value: "sci-fi", label: "Sci-Fi" },
+];
+```
+
+## Acceptance Checks
+
+Keyboard
+- Arrow Down and Arrow Up move the active option, and the active option shows a visible focus indicator.
+- Home moves the active option to the first option; End moves it to the last option.
+- In a multi-select listbox, Space toggles the selected state of the active option without moving focus.
+- In a multi-select listbox, Shift+Arrow Up and Shift+Arrow Down extend the selection to the adjacent option.
+- In a multi-select listbox, Ctrl+A (Cmd+A on macOS) selects all options.
+- Typing a printable character moves the active option to the next option whose label begins with the typed characters.
+- No option requires Ctrl or Cmd plus click to be selected.
+
+Screen Reader
+- The container is announced as a listbox, and as multi-selectable when `aria-multiselectable="true"` is set.
+- Each option is announced as an option together with its selected state (from `aria-selected`).
+- Moving the active option announces the newly active option and its selected state.

package/corpus/web/react/components/menu.basic.md

@@ -0,0 +1,294 @@
+---
+id: menu.basic
+title: Menu
+stack: web/react
+status: beta
+latest_version: 0.1.0
+tags: [menu, actions-menu, roving-tabindex, overflow-menu, kebab-menu, commands]
+aliases: [kebab menu, overflow menu, actions menu, three-dot menu, more menu, menu button, context menu button, command menu]
+summary: A button that opens a menu of commands using role='menu' and role='menuitem', with roving tabindex focus management and the full menu keyboard contract.
+---
+
+# Menu
+
+Pattern ID: `menu.basic`
+
+A button that opens a menu of commands using `role="menu"` and `role="menuitem"`, with roving tabindex focus management and the full menu keyboard contract.
+
+`role="menu"` is a commitment to implement the entire menu keyboard contract below. A partially implemented menu is worse than a plain list of buttons, so use this pattern only when every requirement in Must Haves is met.
+
+## Use When
+- Use when a button reveals a set of in-place commands or actions (e.g., "Rename", "Duplicate", "Delete", "Export").
+- Use when a button exposes an overflow ("...") or kebab action menu on a toolbar, card, or table row.
+- Use when the items perform actions in place, not navigation to a URL.
+- Use when you will implement the full menu keyboard contract (roving tabindex, Arrow keys, Home/End, type-ahead, Esc).
+
+## Do Not Use When
+- Do not use when the items are links or navigate to a URL (use `navigation-menu.dropdown`, or for a primary navigation bar use `navigation-menu.basic`).
+- Do not use when the user picks a value to submit in a form (use `select.native`, or for type-to-filter selection use `combobox.autocomplete`).
+- Do not use when the trigger shows and hides arbitrary content rather than a list of commands (use `disclosure.basic`).
+- Do not use when building a persistent application command bar with horizontal top-level items (use `menu.menubar`).
+
+## Must Haves
+
+### Roles & structure
+- Use a native `<button>` (preferred), or `role="button"` only when a native button cannot be used.
+  - If `role="button"` is used instead of a native `<button>`, add `tabindex="0"` and keyboard support for Enter and Space, ensuring Space prevents page scrolling while activating the control.
+- The menu container has `role="menu"`.
+- Each command uses `role="menuitem"`.
+  - A stateful item that toggles in place uses `role="menuitemcheckbox"` or `role="menuitemradio"` with `aria-checked="true|false"`.
+- Dividers between groups of items use `role="separator"`.
+- The menu contains only menu parts (`menuitem`, `menuitemcheckbox`, `menuitemradio`, `separator`, and grouping wrappers with `role="none"`), with no links, headings, or form inputs.
+
+### Accessible name
+- The trigger has an accessible name that describes its purpose or action.
+  - For an icon-only trigger, provide an accessible name using `aria-label` or `aria-labelledby` (e.g., "More actions").
+  - Icons within the trigger must be decorative (`aria-hidden="true"`).
+- The menu container has an accessible name via `aria-labelledby` referencing the trigger, or via `aria-label`.
+
+### State & properties
+- The trigger has `aria-haspopup="menu"`.
+- The trigger has `aria-expanded="true|false"` reflecting the open or closed state of the menu.
+- The trigger has `aria-controls="IDREF"` pointing to the menu container.
+- The menu is shown/hidden in the DOM (e.g., via the `hidden` attribute), so that when closed, its items cannot be reached by keyboard or screen readers.
+
+### Keyboard
+- On the trigger, Enter, Space, and Arrow Down open the menu and move focus to the first item.
+- On the trigger, Arrow Up opens the menu and moves focus to the last item.
+- Within the menu, Arrow Up and Arrow Down move focus between items and wrap at the ends.
+- Within the menu, Home moves focus to the first item and End moves focus to the last item.
+- Within the menu, Enter or Space activates the focused item, then closes the menu and returns focus to the trigger.
+- Within the menu, a printable character moves focus to the next item whose label starts with that character (type-ahead).
+
+### Focus
+- Focus is managed with roving tabindex: the active item has `tabindex="0"` and all other items have `tabindex="-1"`.
+- The active item receives DOM focus via `element.focus()`.
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) around the trigger and the menu items.
+- Focus returns to the trigger when the menu closes via activation or Esc, deferred with `requestAnimationFrame` so the trigger is focusable when the call runs.
+
+### Dismissal
+- Esc closes the menu and returns focus to the trigger.
+- Tab moves focus out of the menu and closes it.
+- An outside click or focus loss closes the menu.
+
+## Customizable
+- Roving tabindex is the default focus model. `aria-activedescendant` on the menu container is an acceptable alternative when DOM focus must remain on a single owner element. It has weaker screen-reader support, and the active-item visual style must be painted manually because no element holds DOM focus.
+- Items that toggle a setting in place may use `role="menuitemcheckbox"` or `role="menuitemradio"` with `aria-checked` instead of `role="menuitem"`.
+- Submenus may be supported: Arrow Right on a parent item opens its submenu and Arrow Left closes the submenu and returns focus to the parent item.
+
+## Don'ts
+- Do not use `role="menu"` for navigation or for items that are links.
+- Do not place links, headings, form inputs, or arbitrary content inside a `role="menu"` container.
+- Do not declare `role="menu"` without implementing the full keyboard contract (roving tabindex, Arrow keys, Home/End, type-ahead, Esc).
+- Do not forget to return focus to the trigger when the menu closes via activation or Esc.
+- Do not leave the menu visible while `aria-expanded="false"` (and vice versa).
+- Do not reach for `aria-activedescendant` when roving tabindex is simpler for the case at hand.
+
+## Golden Pattern
+
+Structural reference for AI coding assistants — semantics, focus, and keyboard behavior. Styling, copy, and demo data are illustrative.
+
+```jsx
+"use client";
+
+export function MenuButton({ label = "Actions", items = DEFAULT_ITEMS }) {
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  const triggerRef = useRef(null);
+  const menuRef = useRef(null);
+  const itemRefs = useRef([]);
+
+  const baseId = useId();
+  const triggerId = `${baseId}-trigger`;
+  const menuId = `${baseId}-menu`;
+
+  // Roving tabindex: move DOM focus to the active item whenever the menu is open.
+  useEffect(() => {
+    if (open) itemRefs.current[activeIndex]?.focus();
+  }, [open, activeIndex]);
+
+  function openMenu(index) {
+    setActiveIndex(index);
+    setOpen(true);
+  }
+
+  function closeToTrigger() {
+    setOpen(false);
+    // Defer focus until the menu has left the tab order and the trigger is focusable again.
+    requestAnimationFrame(() => triggerRef.current?.focus());
+  }
+
+  function activate(index) {
+    items[index]?.onSelect?.();
+    closeToTrigger();
+  }
+
+  // Close on outside click without stealing focus back to the trigger.
+  useEffect(() => {
+    if (!open) return;
+
+    function onPointerDown(event) {
+      const trigger = triggerRef.current;
+      const menu = menuRef.current;
+      if (!trigger || !menu) return;
+      if (trigger.contains(event.target) || menu.contains(event.target)) return;
+      setOpen(false);
+    }
+
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [open]);
+
+  // Close on focus loss: if focus leaves both the trigger and the menu, close without
+  // pulling focus back, so Tab and programmatic focus moves out of the menu dismiss it.
+  function onMenuBlur(event) {
+    const next = event.relatedTarget;
+    if (next && (triggerRef.current?.contains(next) || menuRef.current?.contains(next))) return;
+    setOpen(false);
+  }
+
+  function onTriggerKeyDown(event) {
+    switch (event.key) {
+      case "Enter":
+      case " ":
+      case "ArrowDown":
+        event.preventDefault();
+        openMenu(0);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        openMenu(items.length - 1);
+        break;
+      default:
+        break;
+    }
+  }
+
+  function onMenuKeyDown(event) {
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        setActiveIndex((i) => (i + 1) % items.length); // wraps at the end
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        setActiveIndex((i) => (i - 1 + items.length) % items.length); // wraps at the start
+        break;
+      case "Home":
+        event.preventDefault();
+        setActiveIndex(0);
+        break;
+      case "End":
+        event.preventDefault();
+        setActiveIndex(items.length - 1);
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        activate(activeIndex);
+        break;
+      case "Escape":
+        event.preventDefault();
+        closeToTrigger();
+        break;
+      case "Tab":
+        // Tab moves focus out of the menu; let it proceed naturally and close.
+        setOpen(false);
+        break;
+      default:
+        // Type-ahead: jump to the next item whose label starts with the typed character.
+        if (event.key.length === 1 && !event.altKey && !event.ctrlKey && !event.metaKey) {
+          const query = event.key.toLowerCase();
+          for (let offset = 1; offset <= items.length; offset++) {
+            const idx = (activeIndex + offset) % items.length;
+            if (items[idx].label.toLowerCase().startsWith(query)) {
+              setActiveIndex(idx);
+              break;
+            }
+          }
+        }
+        break;
+    }
+  }
+
+  return (
+    <div style={{ position: "relative", display: "inline-block" }}>
+      <button
+        ref={triggerRef}
+        id={triggerId}
+        type="button"
+        aria-haspopup="menu"
+        aria-expanded={open ? "true" : "false"}
+        aria-controls={menuId}
+        onClick={() => (open ? setOpen(false) : openMenu(0))}
+        onKeyDown={onTriggerKeyDown}
+      >
+        {label}
+        <span aria-hidden="true"> ⋯</span>
+      </button>
+
+      <ul
+        ref={menuRef}
+        id={menuId}
+        role="menu"
+        aria-labelledby={triggerId}
+        hidden={!open}
+        onKeyDown={onMenuKeyDown}
+        onBlur={onMenuBlur}
+        style={{
+          position: "absolute",
+          top: "100%",
+          left: 0,
+          listStyle: "none",
+          margin: 0,
+          padding: 4,
+          border: "1px solid GrayText", // opaque, bounded overlay (system color, not decorative)
+          background: "Canvas",
+        }}
+      >
+        {items.map((item, idx) => (
+          <li
+            key={item.id}
+            role="menuitem"
+            tabIndex={idx === activeIndex ? 0 : -1}
+            ref={(el) => {
+              itemRefs.current[idx] = el;
+            }}
+            onClick={() => activate(idx)}
+            style={{ padding: "6px 8px", cursor: "default" }}
+          >
+            {item.label}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+const DEFAULT_ITEMS = [
+  { id: "rename", label: "Rename", onSelect: () => alert("Rename") },
+  { id: "duplicate", label: "Duplicate", onSelect: () => alert("Duplicate") },
+  { id: "export", label: "Export", onSelect: () => alert("Export") },
+  { id: "delete", label: "Delete", onSelect: () => alert("Delete") },
+];
+```
+
+## Acceptance Checks
+
+Keyboard
+- Enter, Space, or Arrow Down on the trigger opens the menu and focuses the first item.
+- Arrow Up on the trigger opens the menu and focuses the last item.
+- Arrow Up and Arrow Down move focus between items and wrap at the ends.
+- Home focuses the first item and End focuses the last item.
+- Typing a printable character moves focus to the next item whose label starts with that character.
+- Enter or Space activates the focused item, closes the menu, and returns focus to the trigger.
+- Esc closes the menu and returns focus to the trigger.
+- Tab closes the menu and moves focus out of it.
+- A click outside the trigger and menu closes the menu.
+
+Screen Reader
+- The trigger exposes a menu popup and its expanded or collapsed state (from `aria-haspopup="menu"` and `aria-expanded`).
+- The container is announced as a menu with its accessible name.
+- Items are announced as menu items, and stateful items convey their checked state via `aria-checked`.
+- Closed menus are not reachable.