-
Notifications
You must be signed in to change notification settings - Fork 6.8k
feat(cdk-experimental/ui-patterns): listbox ui pattern #30495
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
6b857e0
eef3526
89cb225
b01fb41
722b81b
85568f4
0de6c06
6bcf751
b6e4cf7
8f07db6
9f8ef21
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
load("//tools:defaults.bzl", "ng_module") | ||
|
||
package(default_visibility = ["//visibility:public"]) | ||
|
||
ng_module( | ||
name = "listbox", | ||
srcs = glob( | ||
["**/*.ts"], | ||
exclude = ["**/*.spec.ts"], | ||
), | ||
deps = [ | ||
"//src/cdk-experimental/ui-patterns", | ||
"//src/cdk/a11y", | ||
"//src/cdk/bidi", | ||
], | ||
) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
/** | ||
* @license | ||
* Copyright Google LLC All Rights Reserved. | ||
* | ||
* Use of this source code is governed by an MIT-style license that can be | ||
* found in the LICENSE file at https://angular.dev/license | ||
*/ | ||
|
||
export * from './public-api'; |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,158 @@ | ||
/** | ||
* @license | ||
* Copyright Google LLC All Rights Reserved. | ||
* | ||
* Use of this source code is governed by an MIT-style license that can be | ||
* found in the LICENSE file at https://angular.dev/license | ||
*/ | ||
|
||
import { | ||
booleanAttribute, | ||
computed, | ||
contentChildren, | ||
Directive, | ||
ElementRef, | ||
inject, | ||
input, | ||
model, | ||
} from '@angular/core'; | ||
import {ListboxPattern, OptionPattern} from '@angular/cdk-experimental/ui-patterns'; | ||
import {Directionality} from '@angular/cdk/bidi'; | ||
import {toSignal} from '@angular/core/rxjs-interop'; | ||
import {_IdGenerator} from '@angular/cdk/a11y'; | ||
|
||
/** | ||
* A listbox container. | ||
* | ||
* Listboxes are used to display a list of items for a user to select from. The CdkListbox is meant | ||
* to be used in conjunction with CdkOption as follows: | ||
* | ||
* ```html | ||
* <ul cdkListbox> | ||
* <li cdkOption>Item 1</li> | ||
* <li cdkOption>Item 2</li> | ||
* <li cdkOption>Item 3</li> | ||
* </ul> | ||
* ``` | ||
*/ | ||
@Directive({ | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
selector: '[cdkListbox]', | ||
exportAs: 'cdkListbox', | ||
host: { | ||
'role': 'listbox', | ||
'class': 'cdk-listbox', | ||
'[attr.tabindex]': 'pattern.tabindex()', | ||
'[attr.aria-disabled]': 'pattern.disabled()', | ||
'[attr.aria-orientation]': 'pattern.orientation()', | ||
'[attr.aria-multiselectable]': 'pattern.multiselectable()', | ||
'[attr.aria-activedescendant]': 'pattern.activedescendant()', | ||
'(keydown)': 'pattern.onKeydown($event)', | ||
'(pointerdown)': 'pattern.onPointerdown($event)', | ||
}, | ||
}) | ||
export class CdkListbox { | ||
/** The directionality (LTR / RTL) context for the application (or a subtree of it). */ | ||
private readonly _directionality = inject(Directionality); | ||
|
||
/** The CdkOptions nested inside of the CdkListbox. */ | ||
private readonly _cdkOptions = contentChildren(CdkOption, {descendants: true}); | ||
|
||
/** A signal wrapper for directionality. */ | ||
protected textDirection = toSignal(this._directionality.change, { | ||
initialValue: this._directionality.value, | ||
}); | ||
|
||
/** The Option UIPatterns of the child CdkOptions. */ | ||
protected items = computed(() => this._cdkOptions().map(option => option.pattern)); | ||
|
||
/** Whether the list is vertically or horizontally oriented. */ | ||
orientation = input<'vertical' | 'horizontal'>('vertical'); | ||
|
||
/** Whether multiple items in the list can be selected at once. */ | ||
multiselectable = input(false, {transform: booleanAttribute}); | ||
|
||
/** Whether focus should wrap when navigating. */ | ||
wrap = input(true, {transform: booleanAttribute}); | ||
|
||
/** Whether disabled items in the list should be skipped when navigating. */ | ||
skipDisabled = input(true, {transform: booleanAttribute}); | ||
|
||
/** The focus strategy used by the list. */ | ||
focusMode = input<'roving' | 'activedescendant'>('roving'); | ||
|
||
/** The selection strategy used by the list. */ | ||
selectionMode = input<'follow' | 'explicit'>('follow'); | ||
|
||
/** The amount of time before the typeahead search is reset. */ | ||
typeaheadDelay = input<number>(0.5); // Picked arbitrarily. | ||
|
||
/** Whether the listbox is disabled. */ | ||
disabled = input(false, {transform: booleanAttribute}); | ||
|
||
// TODO(wagnermaciel): Figure out how we want to expose control over the current listbox value. | ||
/** The ids of the current selected items. */ | ||
selectedIds = model<string[]>([]); | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
/** The current index that has been navigated to. */ | ||
activeIndex = model<number>(0); | ||
|
||
/** The Listbox UIPattern. */ | ||
pattern: ListboxPattern = new ListboxPattern({ | ||
...this, | ||
items: this.items, | ||
textDirection: this.textDirection, | ||
}); | ||
} | ||
|
||
/** A selectable option in a CdkListbox. */ | ||
@Directive({ | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
selector: '[cdkOption]', | ||
exportAs: 'cdkOption', | ||
host: { | ||
'role': 'option', | ||
'class': 'cdk-option', | ||
'[attr.tabindex]': 'pattern.tabindex()', | ||
'[attr.aria-selected]': 'pattern.selected()', | ||
'[attr.aria-disabled]': 'pattern.disabled()', | ||
}, | ||
}) | ||
export class CdkOption { | ||
/** A reference to the option element. */ | ||
private readonly _elementRef = inject(ElementRef); | ||
|
||
/** The parent CdkListbox. */ | ||
private readonly _cdkListbox = inject(CdkListbox); | ||
|
||
/** A unique identifier for the option. */ | ||
private readonly _generatedId = inject(_IdGenerator).getId('cdk-option-'); | ||
|
||
// TODO(wagnermaciel): https://github.com/angular/components/pull/30495#discussion_r1972601144. | ||
/** A unique identifier for the option. */ | ||
protected id = computed(() => this._generatedId); | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This can be a TODO / cleanup for a next PR, but these generally shouldn't be I think the reason that you're doing this is because the e.g. export type Reactive<T> = () => T; We probably want to do this before build too many more |
||
|
||
// TODO(wagnermaciel): See if we want to change how we handle this since textContent is not | ||
// reactive. See https://github.com/angular/components/pull/30495#discussion_r1961260216. | ||
/** The text used by the typeahead search. */ | ||
protected searchTerm = computed(() => this.label() ?? this.element().textContent); | ||
|
||
/** The parent Listbox UIPattern. */ | ||
protected listbox = computed(() => this._cdkListbox.pattern); | ||
|
||
/** A reference to the option element to be focused on navigation. */ | ||
protected element = computed(() => this._elementRef.nativeElement); | ||
|
||
/** Whether an item is disabled. */ | ||
disabled = input(false, {transform: booleanAttribute}); | ||
|
||
/** The text used by the typeahead search. */ | ||
label = input<string>(); | ||
|
||
/** The Option UIPattern. */ | ||
pattern = new OptionPattern({ | ||
...this, | ||
id: this.id, | ||
listbox: this.listbox, | ||
element: this.element, | ||
searchTerm: this.searchTerm, | ||
}); | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
/** | ||
* @license | ||
* Copyright Google LLC All Rights Reserved. | ||
* | ||
* Use of this source code is governed by an MIT-style license that can be | ||
* found in the LICENSE file at https://angular.dev/license | ||
*/ | ||
|
||
export {CdkListbox, CdkOption} from './listbox'; |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
load("//tools:defaults.bzl", "ts_library") | ||
|
||
package(default_visibility = ["//visibility:public"]) | ||
|
||
ts_library( | ||
name = "ui-patterns", | ||
srcs = glob( | ||
["**/*.ts"], | ||
exclude = ["**/*.spec.ts"], | ||
), | ||
deps = [ | ||
"//src/cdk-experimental/ui-patterns/listbox", | ||
"@npm//@angular/core", | ||
], | ||
) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
load("//tools:defaults.bzl", "ts_library") | ||
|
||
package(default_visibility = ["//visibility:public"]) | ||
|
||
ts_library( | ||
name = "event-manager", | ||
srcs = glob( | ||
["**/*.ts"], | ||
exclude = ["**/*.spec.ts"], | ||
), | ||
deps = ["@npm//@angular/core"], | ||
) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,103 @@ | ||
/** | ||
* @license | ||
* Copyright Google LLC All Rights Reserved. | ||
* | ||
* Use of this source code is governed by an MIT-style license that can be | ||
* found in the LICENSE file at https://angular.dev/license | ||
*/ | ||
|
||
/** | ||
* An event that supports modifier keys. | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* | ||
* Matches the native KeyboardEvent, MouseEvent, and TouchEvent. | ||
*/ | ||
export interface EventWithModifiers extends Event { | ||
ctrlKey: boolean; | ||
shiftKey: boolean; | ||
altKey: boolean; | ||
metaKey: boolean; | ||
} | ||
|
||
/** | ||
* Options that are applicable to all event handlers. | ||
* | ||
* This library has not yet had a need for stopPropagationImmediate. | ||
*/ | ||
export interface EventHandlerOptions { | ||
stopPropagation: boolean; | ||
preventDefault: boolean; | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
} | ||
|
||
/** A basic event handler. */ | ||
export type EventHandler<T extends Event> = (event: T) => void; | ||
|
||
/** A function that determines whether an event is to be handled. */ | ||
export type EventMatcher<T extends Event> = (event: T) => boolean; | ||
|
||
/** A config that specifies how to handle a particular event. */ | ||
export interface EventHandlerConfig<T extends Event> extends EventHandlerOptions { | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
matcher: EventMatcher<T>; | ||
handler: EventHandler<T>; | ||
} | ||
|
||
/** Bit flag representation of the possible modifier keys that can be present on an event. */ | ||
export enum ModifierKey { | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
None = 0, | ||
Ctrl = 0b1, | ||
Shift = 0b10, | ||
Alt = 0b100, | ||
Meta = 0b1000, | ||
} | ||
|
||
export type ModifierInputs = ModifierKey | ModifierKey[]; | ||
|
||
/** | ||
* Abstract base class for all event managers. | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* | ||
* Event managers are designed to normalize how event handlers are authored and create a safety net | ||
* for common event handling gotchas like remembering to call preventDefault or stopPropagation. | ||
*/ | ||
export abstract class EventManager<T extends Event> { | ||
protected configs: EventHandlerConfig<T>[] = []; | ||
abstract options: EventHandlerOptions; | ||
|
||
/** Runs the handlers that match with the given event. */ | ||
handle(event: T): void { | ||
for (const config of this.configs) { | ||
if (config.matcher(event)) { | ||
config.handler(event); | ||
|
||
if (config.preventDefault) { | ||
event.preventDefault(); | ||
} | ||
|
||
if (config.stopPropagation) { | ||
event.stopPropagation(); | ||
} | ||
} | ||
} | ||
} | ||
|
||
/** Configures the event manager to handle specific events. (See subclasses for more). */ | ||
abstract on(...args: [...unknown[]]): this; | ||
} | ||
|
||
/** Gets bit flag representation of the modifier keys present on the given event. */ | ||
export function getModifiers(event: EventWithModifiers): number { | ||
return ( | ||
(+event.ctrlKey && ModifierKey.Ctrl) | | ||
(+event.shiftKey && ModifierKey.Shift) | | ||
(+event.altKey && ModifierKey.Alt) | | ||
(+event.metaKey && ModifierKey.Meta) | ||
); | ||
} | ||
|
||
/** | ||
* Checks if the given event has modifiers that are an exact match for any of the given modifier | ||
* flag combinations. | ||
*/ | ||
export function hasModifiers(event: EventWithModifiers, modifiers: ModifierInputs): boolean { | ||
const eventModifiers = getModifiers(event); | ||
wagnermaciel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
const modifiersList = Array.isArray(modifiers) ? modifiers : [modifiers]; | ||
return modifiersList.some(modifiers => eventModifiers === modifiers); | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why don't we call this
patterns
? Theui-
seems a bit redundant.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jelbourn Do you recall the reason for keeping the
ui-
prefix?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like the
ui-
,patterns
by itself makes me think of like GoF design patterns or somethingThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, the thinking was that just "patterns" by itself was too generic
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Isn't everything we do related to building UI though? It seems a bit redundant to have it in the name. Then again, if we don't intend to make this public it might not matter 🤷♂️