Dropdown

Level: molecule.

Purpose and use

Present actions, one selection or a set of checkbox selections beside a trigger. Use a filter wrapper for Apply/Clear drafts or searchable choices.

Anatomy, behavior, and accessibility

• The [wblDropdownTrigger] slot anchors a CDK overlay. The panel contains menu rows with optional icons/images, side text, badges and separators, or a loader.
• With the default controlled=false, trigger activation toggles local open state and emits openedChange; backdrop click and overlay detach close it. With controlled=true, opened is the sole overlay-state source: trigger, backdrop/detach, Escape, and selection close interactions only emit the next requested value through openedChange. The overlay changes state only after the parent writes that value to opened; duplicate requests for the current parent value are not emitted. The component applies aria-haspopup, aria-expanded, and, when present, aria-controls to the native trigger. Default/right placement use viewport fallback positions; nontext trigger width and minPanelWidth bound panel width.
• Default/radio choices emit itemSelect and close; radio also emits the ID. Checkbox choices emit the next ID array and keep the menu open. The parent writes selection back. Empty selectedIds/null selectedId fall back to per-item selected; avoid conflicting sources when clearing a selection.
• Default menu rows use menuitem/menuitemcheckbox/menuitemradio semantics; semanticRole='listbox' uses options. Opening focuses the selected enabled row or first enabled row. ArrowUp/ArrowDown, Home/End, Escape, Enter and Space work for both overlay semantics; Escape and keyboard selection return focus to the native trigger. Disabled rows cannot select. Loading replaces rows and sets busy. Supply a native named trigger and clear, unique labels/IDs.
• The panel itself owns vertical scrolling with overflow-y: auto and overscroll-behavior: contain. Maximum heights are 26.75rem for L, 19.875rem for M, and 15.625rem for S.

Local component contract

This is the active owned contract for component.dropdown. The API below is verified against the current local implementation, focused test and story. The Source commit 0112cba0779a2d2a4b6c7a17243201694344d70a remains migration provenance, not the runtime owner.

Classes and selectors

• WblDropdownComponent — wbl-dropdown (src/app/design-system/patterns/dropdown/dropdown.component.ts).

Inputs

• WblDropdownComponent.size = input<WblDropdownSize>('L')
• WblDropdownComponent.state = input<WblDropdownState>('default')
• WblDropdownComponent.itemsType = input<WblDropdownItemsType>('default')
• WblDropdownComponent.semanticRole = input<WblDropdownSemanticRole>('menu'), where WblDropdownSemanticRole = 'menu' | 'listbox'
• WblDropdownComponent.items = input<WblDropdownItem[]>([])
• WblDropdownComponent.opened = input(false)
• WblDropdownComponent.controlled = input(false) — opt-in parent-controlled overlay mode; when true, the parent must update opened in response to openedChange for the requested state to take effect.
• WblDropdownComponent.hasBackdrop = input(true)
• WblDropdownComponent.placement = input<WblDropdownPlacement>('default')
• WblDropdownComponent.panelId = input<string | null>(null) — optional stable overlay id; when provided, the component binds it to the native trigger's aria-controls.
• WblDropdownComponent.minPanelWidth = input<number | null>(null)
• WblDropdownComponent.selectedIds = input<readonly string[]>([])
• WblDropdownComponent.selectedId = input<string | null>(null)

Public types and allowed values

type WblDropdownSize = 'L' | 'M' | 'S';
type WblDropdownState = 'default' | 'loading';
type WblDropdownItemsType = 'default' | 'checkbox' | 'radio';
type WblDropdownSemanticRole = 'menu' | 'listbox';
type WblDropdownItem = {
  id: string;
  label: string;
  iconName?: WblIconName;
  imageSrc?: string;
  imageAlt?: string;
  badge?: string;
  rightText?: string;
  selected?: boolean;
  disabled?: boolean;
  separatorBefore?: boolean;
};
type WblDropdownPlacement = 'default' | 'right';

Icon-name inputs use WblIconName from the shared icon contract; choose a key present in the owned icon pack, not an arbitrary external icon name.

Models

• None.

Outputs

• WblDropdownComponent.openedChange = output<boolean>() — the local state change in default mode, or the requested next opened value in controlled mode.
• WblDropdownComponent.itemSelect = output<WblDropdownItem>()
• WblDropdownComponent.selectedIdsChange = output<string[]>()
• WblDropdownComponent.selectedIdChange = output<string | null>()

Slots and projection markers

• WblDropdownComponent: <ng-content select="[wblDropdownTrigger]">

Semantic role and keyboard behavior

• semanticRole='menu' is the default and preserves menu and menu-item semantics.
• semanticRole='listbox' is the narrow composition mode for selection fields. In checkbox mode the panel exposes role="listbox" with aria-multiselectable="true"; each enabled checkbox item is an role="option" with aria-selected. It does not expose a nested interactive checkbox to assistive technology.
• Opening focuses the selected enabled option or the first enabled row. In both modes ArrowUp/ArrowDown wrap through enabled rows; Home/End move to their bounds; Escape closes and restores focus; Enter/Space activate the row. This does not introduce draft selection, search, or a new selection data API.

Local evidence

• Code: src/app/design-system/patterns/dropdown/dropdown.component.ts.
• Focused test: src/app/design-system/patterns/dropdown/dropdown.component.spec.ts.
• Public export: export * from './patterns/dropdown/dropdown.component'; in src/app/design-system/index.ts.
• Storybook: storybook/stories/dropdown.stories.ts (Design System/Patterns/wbl-dropdown).

Figma status

This runtime contract does not infer a Figma owner. Assembly evidence, when verified, is maintained separately through the inventory-linked sidecar.

M-002 scrollbar treatment

The Dropdown panel uses a native 4px scrollbar: scrollbar-color pairs the tertiary thumb with a transparent track and scrollbar-width: thin provides the fallback. WebKit uses --space-100 width, a transparent track/corner, the tertiary thumb, and --radius-pill. The thumb is visible whenever content overflows; it is not hover-only. This styling adds no public API.

Provenance

The archived source-document copy is historical evidence only. The active resolver is local code/test/export and the exact Storybook story above.