Skip to content

refactor(ui5-*): use unified API to define a11y attributes via accessibilityAttributes#8810

Merged
ilhan007 merged 18 commits intomainfrom
common-accessibilityAttributes-type-and-approach
May 8, 2024
Merged

refactor(ui5-*): use unified API to define a11y attributes via accessibilityAttributes#8810
ilhan007 merged 18 commits intomainfrom
common-accessibilityAttributes-type-and-approach

Conversation

@ilhan007
Copy link
Copy Markdown
Contributor

@ilhan007 ilhan007 commented Apr 19, 2024 •
edited
Loading

Unifies the API to define additional a11y attributes cross components. The common approach in all relevant components to define additional a11y attributes is via property accessibilityAttributes:

type AccessibilityAttributes = {
	ariaSetsize?: number,
	ariaPosinset?: number,
	controls?: LowercaseString<string>
	expanded?: "true" | "false" | boolean,
	hasPopup?: ARIAHasPopup, // "dialog" | "grid" | "menu" | "listbox" | "tree",
	name?: string
	role?: ARIARoles, // "alertdialog" | "button" | "dialog" | "link"
}

accessibilityAttributes!: AccessibilityAttributes;

Fixes: #8353

BREAKING CHANGE:

ui5-flexible-column-layout

Changed item Old New
Property accessibilityTexts removed
Property accessibilityRoles removed
  • The accessibilityTexts and accessibilityRoles properties of the ui5-flexible-column-layout are removed.

If you have previously used the accessibilityTexts or accessibilityRoles properties:

fcl.accessibilityTexts = {
    startColumnAccessibleName: "Products list",
    midColumnAccessibleName: "Product information",
    endColumnAccessibleName: "Product detailed information",
    startArrowLeftText: "Collapse products list",
    startArrowRightText: "Expand products list",
    endArrowLeftText: "Expand product detailed information",
    endArrowRightText: "Collapse product detailed information",
    startArrowContainerAccessibleName: "Start Arrow Container",
    endArrowContainerAccessibleName: "End Arrow Container",
}

fcl.accessibilityRoles = {
    startColumnRole: "complementary",
    startArrowContainerRole: "navigation",
    midColumnRole: "main",
    endArrowContainerRole: "navigation",
    endColumnRole: "complementary".
}

Now use accessibilityAttributes instead:

fcl.accessibilityAttributes = {
    startColumn: {
      role: "complementary",
      name: "Products list",
    },
    midColumn: {
      role: "main",
      name: "Product information",
    },
    endColumn: {
      role: "complementary",
      name: "Product detailed information",
    },
    startArrowLeft:  {
      name: "Collapse products list",
    },
    startArrowRight: {
      name: "Expand products list",
    },
    endArrowLeft: {
      name: "Expand product detailed information",
    },
    endArrowRight:  {
      name: "Collapse product detailed information",
    },
    startArrowContainer: {
      role: "navigation",
      name: "Start Arrow Container",
    },
    endArrowContainer: {
      role: "navigation",
      name: "End Arrow Container",
    },
};

ui5-shellbar

Changed item Old New
Property accessibilityTexts removed
Property accessibilityRoles removed
  • The accessibilityTexts and accessibilityRoles properties of the ui5-shellbar are removed.
    If you have previously used the accessibilityTexts or accessibilityRoles properties:
shellbar.accessibilityTexts = {
    profileButtonTitle: "John Dow",
    logoTitle: "Custom logo title",
}

shellbar.accessibilityRoles = {
    logoRole: "link"
};

Now use accessibilityAttributes instead:

shellbar.accessibilityAttributes = {
  profile: {
    name:  "John Dow",
  },
  logo: {
    role: "link"
    name: "Custom logo title"
  },
};

Changes

1. Avatar and AvatarGroup

  • adds new public accessibilityAttributes property.
  • removes ariaHasPopup standalone private property and allow setting aria-haspopup via the public accessibilityAttributes

2. Unified API to define additional a11y attributes

The common approach in all relevant components to define additional a11y attributes is via property accessibilityAttributes
The accessibilityAttributes property is of newly created type AccessibilityAttributes, that is describing which attributes are supported and their exact values:

type AccessibilityAttributes = {
	ariaSetsize?: number,
	ariaPosinset?: number,
	controls?: LowercaseString<string>
	expanded?: "true" | "false" | boolean,
	hasPopup?: ARIAHasPopup, // "dialog" | "grid" | "menu" | "listbox" | "tree",
	name?: string
	role?: ARIARoles, // "alertdialog" | "button" | "dialog" | "link"
}

accessibilityAttributes!: AccessibilityAttributes;
  • Each component can restrict the type to a subset and introduce more specific type:
type LinkAccessibilityAttributes = Pick<AccessibilityAttributes, "expanded" | "hasPopup">;

@property({ type: Object })
accessibilityAttributes!: LinkAccessibilityAttributes;

export type {
    LinkAccessibilityAttributes,
}

3. Fixes

  • ListItem : removes obsolete private title property (public tooltip is available)
  • ListItems: removes ariaHasPopup standalone private property and allow setting aria-haspopup via the public accessibilityAttributes
  • Fix wrong usages of aria-label, aria-haspopup in multiple places, mostly set on ui5-button and ui5-link in the templates, while accessible-name and accessibilityAttributes: {hasPopup: "sth"} must be used:

Don't

<ui5-button aria-label="{{overflowBtnAccessibleName}}"
<ui5-button aria-haspopup="menu""

Do

<ui5-button accessible-name="{{overflowBtnAccessibleName}}"
<ui5-button .accessibilityAttributes="{{overflowBtnAccessibilityAttributes}}" // {hasPopup: "menu"}

@ilhan007 ilhan007 changed the title feat(ui5-avatar, ui5-avatar-gorup): introduce `accessibilityAttribute… chore(ui5-*): use unified API to define a11y attributes via accessibilityAttributes Apr 22, 2024
@ilhan007 ilhan007 changed the title chore(ui5-*): use unified API to define a11y attributes via accessibilityAttributes refactor(ui5-*): use unified API to define a11y attributes via accessibilityAttributes Apr 22, 2024
elenastoyanovaa
elenastoyanovaa requested changes Apr 23, 2024
View reviewed changes
@nnaydenow nnaydenow mentioned this pull request Apr 24, 2024
Merged
GerganaKremenska
GerganaKremenska reviewed Apr 25, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@GerganaKremenska GerganaKremenska left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good for team Rodopi components!

@yanaminkova
Copy link
Copy Markdown
Contributor

yanaminkova commented Apr 26, 2024

Looks good for team Pirin components.

elenastoyanovaa
elenastoyanovaa reviewed Apr 29, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@elenastoyanovaa elenastoyanovaa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 from my side.

elenastoyanovaa
elenastoyanovaa previously requested changes Apr 29, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@elenastoyanovaa elenastoyanovaa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't forget to update the PR description as I assume that some parts are outdated after the last changes. Please inform me once the PR is submitted as we need to update the Accessibility Documentation Chapter after that.

@ilhan007 ilhan007 mentioned this pull request Apr 29, 2024
Closed
unazko
unazko reviewed Apr 30, 2024
View reviewed changes
packages/main/src/Button.ts
@@ -26,7 +26,6 @@ import ButtonType from "./types/ButtonType.js";
import ButtonAccessibleRole from "./types/ButtonAccessibleRole.js";
Copy link
Copy Markdown
Contributor

@unazko unazko Apr 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the ButtonAccessibleRole enum is no longer needed. We could use the AriaRole enum now instead. Same applies for the ui5-link component and the corresponding accessibleRole property. There is the following related PR: https://github.com/SAP/ui5-webcomponents/pull/8807/files

unazko
unazko reviewed Apr 30, 2024
View reviewed changes
dobrinyonkov
dobrinyonkov reviewed May 7, 2024
View reviewed changes
@ilhan007 ilhan007 requested a review from dobrinyonkov May 8, 2024 06:41
@ilhan007 ilhan007 merged commit 49d587c into main May 8, 2024
@ilhan007 ilhan007 deleted the common-accessibilityAttributes-type-and-approach branch May 8, 2024 08:33
This was referenced Jul 10, 2024
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@unazko unazko unazko left review comments

@GerganaKremenska GerganaKremenska GerganaKremenska left review comments

@dobrinyonkov dobrinyonkov dobrinyonkov approved these changes

@yanaminkova yanaminkova Awaiting requested review from yanaminkova

@elenastoyanovaa elenastoyanovaa Awaiting requested review from elenastoyanovaa

Assignees

No one assigned

Labels

2.0 BREAKING CHANGE

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[UI5 Web Components 2.0] General guidance for API revision from accessibility perspective

6 participants

@ilhan007 @yanaminkova @elenastoyanovaa @unazko @dobrinyonkov @GerganaKremenska