Skip to content
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

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

Merged
merged 18 commits into from
May 8, 2024

Conversation

ilhan007
Copy link
Member

@ilhan007 ilhan007 commented Apr 19, 2024

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
packages/base/src/types.ts Outdated Show resolved Hide resolved
Copy link
Member

@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
Member

Looks good for team Pirin components.

Copy link
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.

Copy link
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.

@@ -26,7 +26,6 @@ import ButtonType from "./types/ButtonType.js";
import ButtonAccessibleRole from "./types/ButtonAccessibleRole.js";
Copy link
Contributor

@unazko unazko Apr 30, 2024

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

packages/fiori/src/FlexibleColumnLayout.ts Outdated Show resolved Hide resolved
packages/fiori/src/ShellBar.ts Outdated Show resolved Hide resolved
packages/fiori/src/ShellBar.ts Outdated Show resolved Hide resolved
@ilhan007 ilhan007 requested a review from dobrinyonkov May 8, 2024 06:41
@ilhan007 ilhan007 merged commit 49d587c into main May 8, 2024
10 checks passed
@ilhan007 ilhan007 deleted the common-accessibilityAttributes-type-and-approach branch May 8, 2024 08:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
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