Skip to content

Commit

Permalink
feat(material/checkbox): add new aria properties to MatCheckbox (#29457)
Browse files Browse the repository at this point in the history
* feat(material/checkbox): add new aria properties to MatCheckbox

Added three new aria properties to MatCheckbox:
`aria-expanded`: Indicates whether the checkbox controls the visibility
of another element. This should be a boolean value (true or false).
`aria-controls`: Specifies the ID of the element that the checkbox controls.
`aria-owns`: Specifies the ID of the element that the checkbox visually owns.
These attributes will be added to the generated checkbox element if they
are specified and won't be present in the HTML if not provided.
Also added a small paragraph at the end of the checkbox.md file.

Fixes #28761

* feat(material/checkbox): add new aria properties to MatCheckbox

Added three new aria properties to MatCheckbox:
`aria-expanded`: Indicates whether the checkbox controls the visibility
of another element. This should be a boolean value (true or false).
`aria-controls`: Specifies the ID of the element that the checkbox controls.
`aria-owns`: Specifies the ID of the element that the checkbox visually owns.
These attributes will be added to the generated checkbox element if they
are specified and won't be present in the HTML if not provided.
Also added a small paragraph at the end of the checkbox.md file.

Fixes #28761

* feat(material/checkbox): add new aria properties to MatCheckbox

Added three new aria properties to MatCheckbox:
`aria-expanded`: Indicates whether the checkbox controls the visibility
of another element. This should be a boolean value (true or false).
`aria-controls`: Specifies the ID of the element that the checkbox controls.
`aria-owns`: Specifies the ID of the element that the checkbox visually owns.
These attributes will be added to the generated checkbox element if they
are specified and won't be present in the HTML if not provided.
Also added a small paragraph at the end of the checkbox.md file.

Fixes #28761
  • Loading branch information
jullierme authored Sep 10, 2024
1 parent 3a62ab1 commit 9122335
Show file tree
Hide file tree
Showing 5 changed files with 148 additions and 1 deletion.
3 changes: 3 additions & 0 deletions src/material/checkbox/checkbox.html
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,10 @@
[attr.aria-labelledby]="ariaLabelledby"
[attr.aria-describedby]="ariaDescribedby"
[attr.aria-checked]="indeterminate ? 'mixed' : null"
[attr.aria-controls]="ariaControls"
[attr.aria-disabled]="disabled && disabledInteractive ? true : null"
[attr.aria-expanded]="ariaExpanded"
[attr.aria-owns]="ariaOwns"
[attr.name]="name"
[attr.value]="value"
[checked]="checked"
Expand Down
6 changes: 6 additions & 0 deletions src/material/checkbox/checkbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,3 +74,9 @@ binding these properties, as demonstrated below.
<mat-checkbox [aria-label]="isSubscribedToEmailsMessage">
</mat-checkbox>
```

Additionally, `MatCheckbox` now supports the following accessibility properties:

- **`aria-expanded`**: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (`true` or `false`).
- **`aria-controls`**: Specifies the ID of the element that the checkbox controls.
- **`aria-owns`**: Specifies the ID of the element that the checkbox visually owns.
120 changes: 120 additions & 0 deletions src/material/checkbox/checkbox.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -807,6 +807,94 @@ describe('MatCheckbox', () => {
});
});

describe('with provided aria-expanded', () => {
let checkboxDebugElement: DebugElement;
let checkboxNativeElement: HTMLElement;
let inputElement: HTMLInputElement;

it('should use the provided postive aria-expanded', () => {
fixture = createComponent(CheckboxWithPositiveAriaExpanded);
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
checkboxNativeElement = checkboxDebugElement.nativeElement;
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');

fixture.detectChanges();
expect(inputElement.getAttribute('aria-expanded')).toBe('true');
});

it('should use the provided negative aria-expanded', () => {
fixture = createComponent(CheckboxWithNegativeAriaExpanded);
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
checkboxNativeElement = checkboxDebugElement.nativeElement;
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');

fixture.detectChanges();
expect(inputElement.getAttribute('aria-expanded')).toBe('false');
});

it('should not assign aria-expanded if none is provided', () => {
fixture = createComponent(SingleCheckbox);
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
checkboxNativeElement = checkboxDebugElement.nativeElement;
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');

fixture.detectChanges();
expect(inputElement.getAttribute('aria-expanded')).toBe(null);
});
});

describe('with provided aria-controls', () => {
let checkboxDebugElement: DebugElement;
let checkboxNativeElement: HTMLElement;
let inputElement: HTMLInputElement;

it('should use the provided aria-controls', () => {
fixture = createComponent(CheckboxWithAriaControls);
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
checkboxNativeElement = checkboxDebugElement.nativeElement;
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');

fixture.detectChanges();
expect(inputElement.getAttribute('aria-controls')).toBe('some-id');
});

it('should not assign aria-controls if none is provided', () => {
fixture = createComponent(SingleCheckbox);
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
checkboxNativeElement = checkboxDebugElement.nativeElement;
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');

fixture.detectChanges();
expect(inputElement.getAttribute('aria-controls')).toBe(null);
});
});

describe('with provided aria-owns', () => {
let checkboxDebugElement: DebugElement;
let checkboxNativeElement: HTMLElement;
let inputElement: HTMLInputElement;

it('should use the provided aria-owns', () => {
fixture = createComponent(CheckboxWithAriaOwns);
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
checkboxNativeElement = checkboxDebugElement.nativeElement;
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');

fixture.detectChanges();
expect(inputElement.getAttribute('aria-owns')).toBe('some-id');
});

it('should not assign aria-owns if none is provided', () => {
fixture = createComponent(SingleCheckbox);
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
checkboxNativeElement = checkboxDebugElement.nativeElement;
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');

fixture.detectChanges();
expect(inputElement.getAttribute('aria-owns')).toBe(null);
});
});

describe('with provided tabIndex', () => {
let checkboxDebugElement: DebugElement;
let checkboxNativeElement: HTMLElement;
Expand Down Expand Up @@ -1237,6 +1325,38 @@ class CheckboxWithAriaLabelledby {}
})
class CheckboxWithAriaDescribedby {}

/** Simple test component with an aria-expanded set with true. */
@Component({
template: `<mat-checkbox aria-expanded="true"></mat-checkbox>`,
standalone: true,
imports: [MatCheckbox],
})
class CheckboxWithPositiveAriaExpanded {}

/** Simple test component with an aria-expanded set with false. */
@Component({
template: `<mat-checkbox aria-expanded="false"></mat-checkbox>`,
standalone: true,
imports: [MatCheckbox],
})
class CheckboxWithNegativeAriaExpanded {}

/** Simple test component with an aria-controls set. */
@Component({
template: `<mat-checkbox aria-controls="some-id"></mat-checkbox>`,
standalone: true,
imports: [MatCheckbox],
})
class CheckboxWithAriaControls {}

/** Simple test component with an aria-owns set. */
@Component({
template: `<mat-checkbox aria-owns="some-id"></mat-checkbox>`,
standalone: true,
imports: [MatCheckbox],
})
class CheckboxWithAriaOwns {}

/** Simple test component with name attribute */
@Component({
template: `<mat-checkbox name="test-name"></mat-checkbox>`,
Expand Down
13 changes: 13 additions & 0 deletions src/material/checkbox/checkbox.ts
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,19 @@ export class MatCheckbox
/** The 'aria-describedby' attribute is read after the element's label and field type. */
@Input('aria-describedby') ariaDescribedby: string;

/**
* Users can specify the `aria-expanded` attribute which will be forwarded to the input element
*/
@Input({alias: 'aria-expanded', transform: booleanAttribute}) ariaExpanded: boolean;

/**
* Users can specify the `aria-controls` attribute which will be forwarded to the input element
*/
@Input('aria-controls') ariaControls: string;

/** Users can specify the `aria-owns` attribute which will be forwarded to the input element */
@Input('aria-owns') ariaOwns: string;

private _uniqueId: string;

/** A unique id for the checkbox input. If none is supplied, it will be auto-generated. */
Expand Down
7 changes: 6 additions & 1 deletion tools/public_api_guard/material/checkbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,12 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
};
// (undocumented)
_animationMode?: string | undefined;
ariaControls: string;
ariaDescribedby: string;
ariaExpanded: boolean;
ariaLabel: string;
ariaLabelledby: string | null;
ariaOwns: string;
readonly change: EventEmitter<MatCheckboxChange>;
get checked(): boolean;
set checked(value: boolean);
Expand Down Expand Up @@ -78,6 +81,8 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
labelPosition: 'before' | 'after';
name: string | null;
// (undocumented)
static ngAcceptInputType_ariaExpanded: unknown;
// (undocumented)
static ngAcceptInputType_checked: unknown;
// (undocumented)
static ngAcceptInputType_disabled: unknown;
Expand Down Expand Up @@ -123,7 +128,7 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
// (undocumented)
writeValue(value: any): void;
// (undocumented)
static ɵcmp: i0.ɵɵComponentDeclaration<MatCheckbox, "mat-checkbox", ["matCheckbox"], { "ariaLabel": { "alias": "aria-label"; "required": false; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; }; "ariaDescribedby": { "alias": "aria-describedby"; "required": false; }; "id": { "alias": "id"; "required": false; }; "required": { "alias": "required"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "name": { "alias": "name"; "required": false; }; "value": { "alias": "value"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "color": { "alias": "color"; "required": false; }; "disabledInteractive": { "alias": "disabledInteractive"; "required": false; }; "checked": { "alias": "checked"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "indeterminate": { "alias": "indeterminate"; "required": false; }; }, { "change": "change"; "indeterminateChange": "indeterminateChange"; }, never, ["*"], true, never>;
static ɵcmp: i0.ɵɵComponentDeclaration<MatCheckbox, "mat-checkbox", ["matCheckbox"], { "ariaLabel": { "alias": "aria-label"; "required": false; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; }; "ariaDescribedby": { "alias": "aria-describedby"; "required": false; }; "ariaExpanded": { "alias": "aria-expanded"; "required": false; }; "ariaControls": { "alias": "aria-controls"; "required": false; }; "ariaOwns": { "alias": "aria-owns"; "required": false; }; "id": { "alias": "id"; "required": false; }; "required": { "alias": "required"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "name": { "alias": "name"; "required": false; }; "value": { "alias": "value"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "color": { "alias": "color"; "required": false; }; "disabledInteractive": { "alias": "disabledInteractive"; "required": false; }; "checked": { "alias": "checked"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "indeterminate": { "alias": "indeterminate"; "required": false; }; }, { "change": "change"; "indeterminateChange": "indeterminateChange"; }, never, ["*"], true, never>;
// (undocumented)
static ɵfac: i0.ɵɵFactoryDeclaration<MatCheckbox, [null, null, null, { attribute: "tabindex"; }, { optional: true; }, { optional: true; }]>;
}
Expand Down

0 comments on commit 9122335

Please sign in to comment.