# Feature: People Picker Runtime

## Intent

Problem: `@seventh-ui/css` defines the People Picker visual structure, but consuming apps need a small behavior layer for local people selection.
Users or stakeholders: maintainers, app teams, QA, and future runtime package authors.
Desired outcome: provide a dependency-free controller that renders DS People Picker markup, filters local people by keyword, supports keyboard selection, and cleans up listeners.
Non-goals: remote lookup orchestration, async loading states, directory permissions, or a full multi-select framework.

## Scope

In scope: local people arrays, generated search field, suggestions list, multiple or single selection, selected tags, keyboard navigation, ARIA state, public methods, events, and cleanup.
Out of scope: network data fetching, debouncing, avatars from images, grouped results, virtualization, free-form invite creation, and server validation.
Assumptions: visual styling comes from `@seventh-ui/css@1.0.2`; the CSS docs define People Picker as a visual composition, so runtime behavior is inferred pragmatically.
Dependencies: none beyond the local runtime core and `@seventh-ui/css` classes.

## Behavior

1. The controller must register on `[data-sui-people-picker]` and `[data-sui-component="people-picker"]`.
2. The controller accepts `people`, `selectedIds` or `selectedPeople`, `filter`, `open`, `multiple`, `maxResults`, placeholder, empty, search, selection, suggestions, and remove labels.
3. People entries normalize `id`, `label` or `name`, `support` or `email`, and initials.
4. Filtering is a case-insensitive keyword match across label and support text and excludes already selected people.
5. Arrow keys open/navigate suggestions, Enter selects the active option, Escape closes, and Backspace removes the last selected person when the search input is empty.
6. Rendered DOM must use Seventh UI People Picker classes such as `.sui-people-picker`, `.sui-people-picker__field`, `.sui-people-picker__control`, `.sui-people-picker__menu`, `.sui-people-picker__option`, `.sui-people-picker__selection`, and `.sui-people-picker__tag`.
7. Runtime hooks must remain behavior-only: `data-sui-people-picker`, `data-sui-people-picker-search`, `data-sui-people-picker-option`, and `data-sui-people-picker-remove`.
8. The runtime must emit `sui:people-picker:open`, `sui:people-picker:close`, `sui:people-picker:filter`, `sui:people-picker:select`, `sui:people-picker:remove`, `sui:people-picker:change`, and `sui:people-picker:render`.
9. Cleanup must remove listeners attached to generated controls and document-level dismissal handlers.

## Acceptance Examples

Scenario: filter suggestions
Given a People Picker has local people data
When the user types a keyword
Then matching unselected people render in the suggestion menu and `sui:people-picker:filter` is emitted.

Scenario: select and remove people
Given multiple selection is enabled
When the user selects a suggestion and removes its tag
Then the selected IDs update and select, remove, and change events are emitted.

Scenario: keyboard operation
Given suggestions are available
When the user presses ArrowDown and Enter
Then the active option is selected without requiring pointer interaction.

Scenario: keep remote behavior out
Given an application needs server search or invite creation
When it uses this controller
Then the application owns that orchestration and can update local people through `setPeople()`.

## Data and Contracts

Inputs: a People Picker root, local people data, runtime options, and optional per-instance options keyed by element id.
Outputs: rendered picker DOM, public controller methods, synchronized `data-sui-state`, selected people state, and `sui:people-picker:*` events.
API/schema/event changes: exports `createPeoplePickerController`, People Picker selectors, and `registerPeoplePicker`.
Persistence changes: none.

## Quality Attributes

Pragmatism: keep behavior useful without becoming a directory search product.
Accessibility: use combobox/listbox roles, `aria-expanded`, `aria-controls`, `aria-activedescendant`, labeled regions, and keyboard support.
Compatibility: avoid CSS source paths and preserve `.sui-*` visual classes.
Maintainability: prefer straightforward local array filtering and generated markup.