Merge pull request #79 from feedzai/develop

DiogoRDuarte · web-flow · commit def59de1ccd4 · 2026-02-10T09:45:35.000Z
Code for 3.1.0 release
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,25 +1,43 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+### Changed
+
+- Updated Shortcut Guides to better follow the [Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) by W3C
+- Updated cypress tests accordingly
+
+### Added
+
+- Added alt text to the Readme images
+
 ## 3.0.3 - 2025-12-03
+
 ### Added
+
 - Fixed vulnerable dependency
 
 ## 3.0.2 - 2025-12-03
+
 ### Added
+
 - Fixed multiple vulnerable dependencies
 
 ## 3.0.1 - 2025-10-06
+
 ### Added
+
 - Fixed vulnerable dependency
 
 ## 3.0.0 - 2025-09-15
+
 ### Added
+
 - Implemented i18n alternatives as the new "internationalization" property
 - Fixed tests / github pipeline errors
 - Adapted the ShortcutGuide to vary between "Alt" and "option" depending on the OS
@@ -28,29 +46,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added Arrow Navigation to the ShortcutGuide
 
 ### Changed
+
 - Replaced arrow symbols with text on the ShortcutGuide
 - Re-did ShortcutGuide `<dl>` structure
 - Moved the context prop to inside autoDescriptions
 
 ## 2.0.4 - 2025-01-06
+
 ### Added
+
 - Fixed an issue where series values having spaces would invalidate class names
 
 ## 2.0.3 - 2024-11-04
+
 ### Added
+
 - Adds missing types
 - Fixed the issue where components were not being properly exported
 
 ## 2.0.2 - 2024-10-24
+
 ### Added
+
 - Dynamic changes in the data or DOM elements now trigger updates in the tool
 
 ## 2.0.1 - 2024-10-08
+
 ### Added
+
 - Aligned native ShortcutGuide styling with the prototypes
 
 ## 2.0.0 - 2024-10-04
+
 ### Added
+
 - Changed bundler from babel to vite
 - Replaced jest with cypress
 - Converted Javascript to Typescript
@@ -60,22 +89,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Converted the ShortcutGuide into a prop, making it overridable and customizable
 
 ## 1.0.3 - 2024-01-09
+
 ### Added
+
 - Remove unused dependency
 
 ## 1.0.2 - 2023-12-06
+
 ### Added
+
 - Fixed the previously correction of the "series:" class attribution in the data elements that would break the navigation inside multi series charts
 
 ## 1.0.1 - 2023-12-06
+
 ### Added
+
 - Corrected the attribution of the "series:" class in the data elements that would break the navigation inside multi series charts
 
 ## 1.0.0 - 2023-11-14
+
 ### Added
+
 - Added support for charts with multiple encodings
 
 ## 0.2.0 - 2023-11-02
+
 ### Added
+
 - Extended React compatibility to support projects with React >=16.14.0
 - Set up automatic semantic versioning
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # AutoVizuA11y
 
-<img src="./src/assets/images/banner.png">
+<img src="./src/assets/images/banner.png" alt="Three illustrative bar charts, each corresponding to an AutoVizuA11y pillar. The first, 'Descriptions', depicts a focus highlight around the entire chart and a box with the text 'Calories per piece of fruit, bar chart. Automatic description: The data shows that bananas and grapes have the same...'. The second pillar, 'Navigation', depicts three focus highlights around the first three bars and two arrows going from the previous to the next. There is also a box that says 'Bananas: 105 calories' together with two icons of a right arrow. Lastly, the third pillar 'Shortcuts', depicts a single focus highlight around one of the bars. It also includes a box with the text 'The value is 42.18 above the average' and three icons, the first with 'Alt', the second with a top arrow and the third with the letter 'K'.">
 
 ## Description
 
@@ -73,7 +73,7 @@ cd autovizua11y
 
 | Keys                  | Required/Optional | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
 | --------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `apiKey`              | Required          | string  | The OpenAI or OpenAI-compatible API key, enabling an LLM to generate human-like descriptions of the data visualization. [You can get yours here](https://platform.openai.com/account/api-keys), It is recommended for the developer to take the necessary precautions in order to hide the API key.                                                                                                            |
+| `apiKey`              | Required          | string  | The OpenAI or OpenAI-compatible API key, enabling an LLM to generate human-like descriptions of the data visualization. [You can get yours here](https://platform.openai.com/account/api-keys). It is recommended for the developer to take the necessary precautions in order to hide the API key.                                                                                                            |
 | `context`             | Required          | string  | The context in which the data visualization is present. It is passed in the prompt, when generating automatic the descriptions, resulting in contextualized outputs.                                                                                                                                                                                                                                           |
 | `dynamicDescriptions` | Optional          | boolean | Setting this to `false` stops the component from generating the two descriptions for that chart after the first render (the descriptions get saved in localstorage). This should be useful for static visualizations.                                                                                                                                                                                          |
 | `model`               | Optional          | string  | The LLM responsible for generating both descriptions. [You can check the models available here](https://platform.openai.com/docs/models). If no model is provided, `gpt-3.5-turbo` will be chosen by `default`.                                                                                                                                                                                                |
@@ -261,7 +261,7 @@ The Shortcut Guide can be acessed by the user, using the <kbd>?</kbd> key, while
 
 The Shortcut Guide is the only aspect of AutoVizuA11y that is also visual. You may change the styling of the default guide. Below are the classNames of the elements that make up this component:
 
-<img src="./src/assets/images/shortcut_guide_class_anatomy.png">
+<img src="./src/assets/images/shortcut_guide_class_anatomy.png" alt="Diagram of the native Shortcut Guide styling. Each individual component of the guide has an annotation with its CSS class">
 
 | className                           | HTML   |
 | ----------------------------------- | ------ |
diff --git a/cypress/e2e/average.cy.js b/cypress/e2e/average.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Alt + K) Average Test", () => {
 	it("should alert the correct average value for the first chart", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/change-descriptions.cy.js b/cypress/e2e/change-descriptions.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Alt + S and Alt + B) Change Chart Description Test", () => {
 	it("should toggle between longer and shorter descriptions", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/chart-attributes.cy.js b/cypress/e2e/chart-attributes.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("Addition of Attributes to Chart Test", () => {
 	it("should add aria-labels and tabindexes to the charts", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/chart-element-attributes.cy.js b/cypress/e2e/chart-element-attributes.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("Addition of Attributes to Chart Elements Test", () => {
 	it("should add aria-labels, aria-roledescription, empty role but not tabindexes to the chart elements", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/chart-level.cy.js b/cypress/e2e/chart-level.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Up Arrow) Moving to Chart Level Test", () => {
 	it("should add back the tabindexes to the charts when moving from the data level", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/close-custom-guide.cy.js b/cypress/e2e/close-custom-guide.cy.js
@@ -1,10 +1,11 @@
+/* eslint-disable no-undef */
 describe("(Esc) Close Custom Shortcut Guide Test", () => {
 	it("should close the custom shortcut guide", () => {
 		cy.visit("/");
 		cy.injectAxe();
 		cy.findByTestId("manual-descriptions-option").click();
 		cy.wait(500); // AutoVizuA11y waits 500ms before handling descriptions
-		cy.findAllByTestId("a11y_desc").first().focus().tab().type("?");
+		cy.findAllByTestId("a11y_desc").first().focus().tab().type("?").tab().tab();
 		cy.get(":focus").click(); // Closing the guide by pressing the button
 		cy.findAllByTestId("a11y-custom-shortcut-guide").first().should("not.be.visible"); // Check if the custom shortcut guide is not visible (closed)
 		cy.findAllByTestId("a11y_desc").eq(1).should("be.focused"); // Checks if the chart is focused
diff --git a/cypress/e2e/close-native-guide.cy.js b/cypress/e2e/close-native-guide.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Esc) Close Native Shortcut Guide Test", () => {
 	it("should close the native shortcut guide", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/compare-to-chart.cy.js b/cypress/e2e/compare-to-chart.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Alt + Z) Compare to Rest of the Chart Test", () => {
 	it("should alert the correct comparison value between the first element and rest of the chart", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/compare-to-maximum.cy.js b/cypress/e2e/compare-to-maximum.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Alt + Shift + L) Compare to Maximum of the Chart Test", () => {
 	it("should alert the correct comparison value between the first element and maximum of the chart", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/data-level.cy.js b/cypress/e2e/data-level.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Down Arrow) Moving to Data Level Test", () => {
 	it("should add back the tabindexes to the chart elements when moving from the chart level", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/internationalization.cy.js b/cypress/e2e/internationalization.cy.js
@@ -26,6 +26,7 @@ describe("Internationalization Tests", () => {
 		cy.focused().type("?");
 		cy.get("dialog").should("be.visible");
 		cy.get("dialog h2").should("contain.text", "Guia de atalhos");
+		cy.focused().type("{esc}");
 		cy.checkA11y();
 	});
 
@@ -38,6 +39,7 @@ describe("Internationalization Tests", () => {
 		cy.focused().type("?");
 		cy.get("dialog").should("be.visible");
 		cy.get("dialog h2").should("contain.text", "Overwritten Shortcut guide title");
+		cy.focused().type("{esc}");
 		cy.checkA11y();
 	});
 });
diff --git a/cypress/e2e/jump-between-chart-elements.cy.js b/cypress/e2e/jump-between-chart-elements.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Alt + X) Prompt Test", () => {
 	it("should open a prompt when Alt + X is pressed and input '2'", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/jump-between-chart-extremes.cy.js b/cypress/e2e/jump-between-chart-extremes.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Alt + W and Alt + Q) Jump to the Extremes of the Chart Test", () => {
 	it("should set focus to the extreme elements of the chart", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/move-between-chart-elements.cy.js b/cypress/e2e/move-between-chart-elements.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Right and Left Arrow) Move Between Elements of the Chart Test", () => {
 	it("should move to the next and previous chart elements", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/move-between-chart-series.cy.js b/cypress/e2e/move-between-chart-series.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(Alt + M) Move Between Data Series Test", () => {
 	it("should move to the next series of data", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/open-custom-guide.cy.js b/cypress/e2e/open-custom-guide.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(?) Open Custom Shortcut Guide Test", () => {
 	it("should open the custom shortcut guide", () => {
 		cy.visit("/");
diff --git a/cypress/e2e/open-native-guide.cy.js b/cypress/e2e/open-native-guide.cy.js
@@ -1,3 +1,4 @@
+/* eslint-disable no-undef */
 describe("(?) Open Native Shortcut Guide Test", () => {
 	it("should open the native shortcut guide", () => {
 		cy.visit("/");
diff --git a/examples/src/components/custom_shortcut_guide/components/CustomGuideHeader.tsx b/examples/src/components/custom_shortcut_guide/components/CustomGuideHeader.tsx
@@ -8,23 +8,17 @@
 import * as constants from "../../../../../src/constants";
 import React from "react";
 
-export const CustomShortcutGuideHeader = ({ onClose }: { onClose: () => void }) => (
+export const CustomShortcutGuideHeader = () => (
 	<div className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideHeader}>
 		<h2
 			className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideTitle}
 			id={constants.SHORTCUTGUIDE_ID.shortcutGuideTitle}
+			tabIndex={-1}
 		>
 			Custom Shortcut Guide
 		</h2>
 		<p className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideActionLabel}>
 			Question Mark or Escape
 		</p>
-		<button
-			className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideButtonClose}
-			aria-label="Close shortcut guide"
-			onClick={onClose}
-		>
-			&times;
-		</button>
 	</div>
 );
diff --git a/examples/src/components/custom_shortcut_guide/components/CustomShortcutGuide.tsx b/examples/src/components/custom_shortcut_guide/components/CustomShortcutGuide.tsx
@@ -35,9 +35,17 @@ const CustomShortcutGuide = ({ dialogRef }: CustomShortcutGuideProps): JSX.Eleme
 		>
 			<CustomShortcutGuideDescription />
 			<div className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideContainer}>
-				<CustomShortcutGuideHeader onClose={handleCloseDialog} />
+				<CustomShortcutGuideHeader />
 				<hr className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideBreak} />
 				<CustomShortcutGuideBody />
+				<button
+					className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideButtonClose}
+					aria-label="Close shortcut guide"
+					onClick={handleCloseDialog}
+					type="button"
+				>
+					&times;
+				</button>
 			</div>
 		</div>
 	);
diff --git a/examples/src/components/custom_shortcut_guide/components/CustomShortcutGuideBody.tsx b/examples/src/components/custom_shortcut_guide/components/CustomShortcutGuideBody.tsx
@@ -12,7 +12,7 @@ import { CustomShortcutGuideSection } from "./CustomShortcutGuideSection";
 import { CUSTOM_GUIDE_DATA } from "./CustomGuideData";
 
 export const CustomShortcutGuideBody = () => (
-	<div className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideBody}>
+	<div className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideBody} tabIndex={0}>
 		{CUSTOM_GUIDE_DATA.map((section, sectionIndex) => (
 			<div key={sectionIndex}>
 				<CustomShortcutGuideSection section={section} sectionIndex={sectionIndex} />
diff --git a/examples/src/components/custom_shortcut_guide/components/CustomShortcutGuideSection.tsx b/examples/src/components/custom_shortcut_guide/components/CustomShortcutGuideSection.tsx
@@ -22,7 +22,6 @@ export const CustomShortcutGuideSection = ({
 		<h3
 			className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideListTitle}
 			id={`listHeader${sectionIndex}`}
-			aria-label={`Section: ${section.title}`}
 		>
 			{section.title}
 		</h3>
@@ -35,7 +34,6 @@ export const CustomShortcutGuideSection = ({
 					key={shortcutIndex}
 					className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideRow}
 					aria-label={`${shortcut.description}: ${shortcut.keys}`}
-					tabIndex={0}
 				>
 					<dt className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideCellShortcut}>
 						{shortcut.keys}
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -35,7 +35,7 @@
 	"scripts": {
 		"format": "npx prettier --write '**/*.{jsx,ts,tsx,js}'",
 		"reinstall": "rimraf node_modules && npm install",
-		"lint": "eslint \"src/**/*.{ts,tsx,js,jsx}\" --fix",
+		"lint": "eslint \"src/**/*.{ts,tsx,js,jsx}\" \"cypress/**/*.js\" --fix",
 		"build": "npm run lint && vite build",
 		"postbuild": "size-limit",
 		"docs:install": "cd ./examples && npm install",
diff --git a/src/assets/style/NativeShortcutGuide.css b/src/assets/style/NativeShortcutGuide.css
@@ -9,8 +9,8 @@
 .shortcut-guide {
 	--shortcut-guide-background-color: rgba(0, 15, 58, 0.35);
 	--shortcut-guide-color-primary: #000f3a;
-	--shortcut-guide-font-family: "Roboto", Roboto, -apple-system, BlinkMacSystemFont, Segoe UI,
-		Helvetica, Arial, sans-serif;
+	--shortcut-guide-font-family:
+		Roboto, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif;
 	--shortcut-guide-font-size-small: small;
 	--shortcut-guide-background-light: #ffffff;
 	--shortcut-guide-backdrop-blur: blur(6.5px);
@@ -51,13 +51,16 @@
 	height: 2rem;
 	cursor: pointer;
 	margin: 0;
+	position: absolute !important;
+	right: 1rem;
+	top: 0.5rem;
 }
 
-/* .shortcut-guide__button-close:hover,
+.shortcut-guide__button-close:hover,
 .shortcut-guide__button-close:focus {
 	color: var(--shortcut-guide-close-button-hover-color);
 	text-decoration: none;
-} */
+}
 
 .shortcut-guide__title {
 	margin-right: auto;
diff --git a/src/components/shortcut_guide/components/NativeGuideHeader.tsx b/src/components/shortcut_guide/components/NativeGuideHeader.tsx
@@ -8,25 +8,19 @@
 import * as constants from "../../../constants";
 import type { TFunction } from "i18next";
 
-export const ShortcutGuideHeader = ({ onClose, t }: { onClose: () => void; t: TFunction }) => {
+export const ShortcutGuideHeader = ({ t }: { t: TFunction }) => {
 	return (
 		<div className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideHeader}>
 			<h2
 				className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideTitle}
 				id={constants.SHORTCUTGUIDE_ID.shortcutGuideTitle}
+				tabIndex={-1}
 			>
 				{t("sg_title")}
 			</h2>
 			<p className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideActionLabel}>
 				Question Mark or Escape
 			</p>
-			<button
-				className={constants.SHORTCUTGUIDE_CLASSES.shortcutGuideButtonClose}
-				aria-label={t("close_shortcut_guide_label")}
-				onClick={onClose}
-			>
-				&times;
-			</button>
 		</div>
 	);
 };
diff --git a/src/components/shortcut_guide/components/NativeShortcutGuide.tsx b/src/components/shortcut_guide/components/NativeShortcutGuide.tsx
diff --git a/src/components/shortcut_guide/components/NativeShortcutGuideBody.tsx b/src/components/shortcut_guide/components/NativeShortcutGuideBody.tsx
diff --git a/src/components/shortcut_guide/components/NativeShortcutGuideSection.tsx b/src/components/shortcut_guide/components/NativeShortcutGuideSection.tsx

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* eslint-disable no-undef */`
`1`	`2`	`describe("(Alt + K) Average Test", () => {`
`2`	`3`	`it("should alert the correct average value for the first chart", () => {`
`3`	`4`	`cy.visit("/");`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* eslint-disable no-undef */`
`1`	`2`	`describe("(Alt + S and Alt + B) Change Chart Description Test", () => {`
`2`	`3`	`it("should toggle between longer and shorter descriptions", () => {`
`3`	`4`	`cy.visit("/");`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* eslint-disable no-undef */`
`1`	`2`	`describe("Addition of Attributes to Chart Test", () => {`
`2`	`3`	`it("should add aria-labels and tabindexes to the charts", () => {`
`3`	`4`	`cy.visit("/");`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* eslint-disable no-undef */`
`1`	`2`	`describe("(Up Arrow) Moving to Chart Level Test", () => {`
`2`	`3`	`it("should add back the tabindexes to the charts when moving from the data level", () => {`
`3`	`4`	`cy.visit("/");`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* eslint-disable no-undef */`
`1`	`2`	`describe("(Esc) Close Native Shortcut Guide Test", () => {`
`2`	`3`	`it("should close the native shortcut guide", () => {`
`3`	`4`	`cy.visit("/");`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* eslint-disable no-undef */`
`1`	`2`	`describe("(Alt + Z) Compare to Rest of the Chart Test", () => {`
`2`	`3`	`it("should alert the correct comparison value between the first element and rest of the chart", () => {`
`3`	`4`	`cy.visit("/");`