@ongov/ontario-design-system-component-library 5.0.0-alpha.6 → 5.0.0

package/dist/types/stencil-public-runtime.d.ts

@@ -265,6 +265,25 @@ export declare function setPlatformHelpers(helpers: {
  * @returns the base path
  */
 export declare function getAssetPath(path: string): string;
+/**
+ * Method to render a virtual DOM tree to a container element.
+ *
+ * @example
+ * ```tsx
+ * import { render } from '@stencil/core';
+ *
+ * const vnode = (
+ *   <div>
+ *     <h1>Hello, world!</h1>
+ *   </div>
+ * );
+ * render(vnode, document.body);
+ * ```
+ *
+ * @param vnode - The virtual DOM tree to render
+ * @param container - The container element to render the virtual DOM tree to
+ */
+export declare function render(vnode: VNode, container: Element): void;
 /**
  * Used to manually set the base path where assets can be found. For lazy-loaded
  * builds the asset path is automatically set and assets copied to the correct
@@ -830,6 +849,7 @@ export declare namespace JSXBase {
 	}
 	interface DetailsHTMLAttributes<T> extends HTMLAttributes<T> {
 		open?: boolean;
+		name?: string;
 		onToggle?: (event: Event) => void;
 	}
 	interface DelHTMLAttributes<T> extends HTMLAttributes<T> {
@@ -1602,7 +1622,7 @@ export declare namespace JSXBase {
 		onKeyUp?: (event: KeyboardEvent) => void;
 		onKeyUpCapture?: (event: KeyboardEvent) => void;
 		onAuxClick?: (event: MouseEvent) => void;
-		onClick?: (event: MouseEvent) => void;
+		onClick?: (event: PointerEvent) => void;
 		onClickCapture?: (event: MouseEvent) => void;
 		onContextMenu?: (event: MouseEvent) => void;
 		onContextMenuCapture?: (event: MouseEvent) => void;
@@ -1682,6 +1702,8 @@ export declare namespace JSXBase {
 		onTransitionRunCapture?: (event: TransitionEvent) => void;
 		onTransitionStart?: (event: TransitionEvent) => void;
 		onTransitionStartCapture?: (event: TransitionEvent) => void;
+		[key: `aria-${string}`]: string | boolean | undefined;
+		[key: `aria${string}`]: string | boolean | undefined;
 	}
 }
 export interface JSXAttributes<T = Element> {

package/dist/types/utils/common/common.interface.d.ts

@@ -78,3 +78,10 @@ export interface Hint extends Base {
 	hint: string;
 }
 export type HintContentType = 'string' | 'html';
+export declare const headingLevelDefinitions: readonly ['h2', 'h3', 'h4', 'h5', 'h6'];
+/**
+ * Create a type from an array of values.
+ *
+ * https://steveholgado.com/typescript-types-from-arrays/
+ */
+export type HeadingLevel = (typeof headingLevelDefinitions)[number];

package/dist/types/utils/common/task-statuses.enum.d.ts

@@ -0,0 +1,18 @@
+export declare enum TaskStatuses {
+	NotStarted = 'notStarted',
+	InProgress = 'inProgress',
+	Completed = 'completed',
+	CannotStartYet = 'cannotStartYet',
+	Error = 'error',
+	Optional = 'optional',
+}
+export declare const TaskToBadgeColour: {
+	readonly notStarted: 'lightTeal';
+	readonly inProgress: 'teal';
+	readonly completed: 'white';
+	readonly cannotStartYet: 'darkGrey';
+	readonly error: 'red';
+	readonly optional: 'grey';
+};
+export type TaskStatus = keyof typeof TaskStatuses;
+export type TaskBadgeColour = (typeof TaskToBadgeColour)[TaskStatuses];

package/dist/types/utils/helper/assets.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generate the full path to an image asset based on the base asset path.
+ *
+ * - If `assetBasePath` is provided, it is used as the base path.
+ * - If not, attempts to use Stencil's `getAssetPath` (for Stencil/Angular builds).
+ * - If that fails (e.g., in React), falls back to `/assets/`, assuming assets are in the public folder.
+ *
+ * @param imageName - The name of the image file.
+ * @param assetBasePath - Optional base path for assets.
+ * @returns The full image path as a string.
+ */
+export declare function getImageAssetSrcPath(imageName: string, assetBasePath?: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ongov/ontario-design-system-component-library",
-	"version": "5.0.0-alpha.6",
+	"version": "5.0.0",
 	"private": false,
 	"description": "Ontario Design System Component Library",
 	"license": "Apache-2.0",
@@ -40,8 +40,8 @@
 		"test:unit": "stencil test --spec"
 	},
 	"dependencies": {
-		"@ongov/ontario-design-system-global-styles": "5.0.0-alpha.6",
-		"@stencil/core": "^4.23.0",
+		"@ongov/ontario-design-system-global-styles": "5.0.0",
+		"@stencil/core": "^4.33.1",
 		"dotenv": "^16.4.5",
 		"uuid": "^11.0.5"
 	},
@@ -103,5 +103,5 @@
 	"collection:main": "dist/collection/index.js",
 	"es2015": "dist/esm/index.mjs",
 	"es2017": "dist/esm/index.mjs",
-	"gitHead": "149604a02633d6ddbbebd9e481f4da6ca6c095c5"
+	"gitHead": "7c0af228ef7b2a6c44c1f8c3160e9f4a00727bb2"
 }

package/readme.md

@@ -30,14 +30,14 @@ Use this package if you are working with plain HTML or any framework/tooling tha
 
 ## Installation and usage
 
-There are two ways to install the Ontario Design System component library package into your project: through [NPM](#installing-the-npm-package) or through a [CDN](#cdn).
+There are two ways to install the Ontario Design System component library package into your project: through [npm](#installing-the-npm-package) or through a [CDN](#cdn).
 
-### Installing the NPM package
+### Installing the npm package
 
-1. Install the NPM package.
+1. Install the npm package.
 
    ```bash
-   pnpm install --save @ongov/ontario-design-system-component-library
+   npm install --save @ongov/ontario-design-system-component-library
    ```
 
 2. Add the following script tags to your HTML to import the component library, adjusting the paths to fit your setup.

package/src/components/ontario-aside/test/ontario-aside.e2e.ts

@@ -27,11 +27,11 @@ describe('ontario-aside', () => {
 			component.setProperty('headingType', 'h3');
 			await page.waitForChanges();
 
-			expect(element.firstChild.nodeName).toBe('H3');
+			expect(element.firstChild.nodeName).toBe('SLOT');
 
 			component.setProperty('headingType', 'h4');
 			await page.waitForChanges();
-			expect(element.firstChild.nodeName).toBe('H4');
+			expect(element.firstChild.nodeName).toBe('SLOT');
 		});
 
 		it('renders changes to the class names when the highlightColor is changed', async () => {

package/src/components/ontario-badge/ontario-badge.scss

@@ -69,3 +69,14 @@
 	background-color: colours.$ontario-colour-success;
 	color: colours.$ontario-colour-white;
 }
+
+.ontario-badge--white {
+	background-color: colours.$ontario-colour-white;
+	color: colours.$ontario-greyscale-70;
+	border: globalFunctions.px-to-rem(1) solid colours.$ontario-greyscale-70;
+}
+
+.ontario-badge--grey {
+	background-color: colours.$ontario-greyscale-20;
+	color: colours.$ontario-colour-black;
+}

package/src/components/ontario-badge/ontario-badge.types.ts

@@ -2,12 +2,14 @@ import { retrieveEnumKeys } from '../../utils/helper/utils';
 
 export enum BadgeColourToClass {
 	teal = 'ontario-badge--default-heavy',
-	'light-teal' = 'ontario-badge--default-light',
+	lightTeal = 'ontario-badge--default-light',
 	black = 'ontario-badge--neutral-heavy',
 	grey = 'ontario-badge--neutral-light',
 	red = 'ontario-badge--alert-heavy',
 	yellow = 'ontario-badge--warning-heavy',
 	green = 'ontario-badge--success-heavy',
+	white = 'ontario-badge--white',
+	darkGrey = 'ontario-badge--grey',
 }
 
 export const BadgeColours = retrieveEnumKeys(BadgeColourToClass);

package/src/components/ontario-badge/readme.md

@@ -31,12 +31,12 @@ Example of a badge component, where the user is explicitly passing in content th
 This is another example of a badge. This time, the content is passed as a child of the `ontario-badge` component. A `colour` option is also passed.
 
 ```html
-<ontario-badge colour="light-teal">Completed</ontario-badge>
+<ontario-badge colour="lightTeal">Completed</ontario-badge>
 ```
 
 <div>
 	<OntarioBadge
-		colour="light-teal"
+		colour="lightTeal"
 	>
 		Completed
 	</OntarioBadge>
@@ -46,11 +46,25 @@ This is another example of a badge. This time, the content is passed as a child
 
 ## Properties
 
-| Property        | Attribute         | Description                                                                                                               | Type                                                                          | Default     |
-| --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------- |
-| `ariaLabelText` | `aria-label-text` | An aria label for screen readers. Used to provide more context to screen readers if necessary. This property is optional. | `string \| undefined`                                                         | `undefined` |
-| `colour`        | `colour`          | The colour of the badge.                                                                                                  | `"black" \| "green" \| "grey" \| "light-teal" \| "red" \| "teal" \| "yellow"` | `'teal'`    |
-| `label`         | `label`           | The label for the badge. Offical guidance is to keep the label length within 15 characters.                               | `string`                                                                      | `undefined` |
+| Property        | Attribute         | Description                                                                                                               | Type                                                                                                  | Default     |
+| --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------- |
+| `ariaLabelText` | `aria-label-text` | An aria label for screen readers. Used to provide more context to screen readers if necessary. This property is optional. | `string \| undefined`                                                                                 | `undefined` |
+| `colour`        | `colour`          | The colour of the badge.                                                                                                  | `"black" \| "darkGrey" \| "green" \| "grey" \| "lightTeal" \| "red" \| "teal" \| "white" \| "yellow"` | `'teal'`    |
+| `label`         | `label`           | The label for the badge. Offical guidance is to keep the label length within 15 characters.                               | `string`                                                                                              | `undefined` |
+
+## Dependencies
+
+### Used by
+
+- [ontario-task](../ontario-task)
+
+### Graph
+
+```mermaid
+graph TD;
+  ontario-task --> ontario-badge
+  style ontario-badge fill:#f9f,stroke:#333,stroke-width:4px
+```
 
 ---
 

package/src/components/ontario-badge/test/__snapshots__/ontario-badge.spec.tsx.snap

@@ -34,7 +34,7 @@ exports[`ontario-badge should render the expected base html 1`] = `
 `;
 
 exports[`ontario-badge should render with the ontario-badge--default-light class on the span element 1`] = `
-<ontario-badge colour="light-teal">
+<ontario-badge colour="lightTeal">
   <template shadowrootmode="open">
     <span class="ontario-badge ontario-badge--default-light">
       In progress

package/src/components/ontario-badge/test/ontario-badge.spec.tsx

@@ -23,7 +23,7 @@ describe('ontario-badge', () => {
 	it('should render with the ontario-badge--default-light class on the span element', async () => {
 		const page = await newSpecPage({
 			components: [OntarioBadge],
-			html: `<ontario-badge colour="light-teal">In progress</ontario-badge>`,
+			html: `<ontario-badge colour="lightTeal">In progress</ontario-badge>`,
 		});
 
 		expect(page.root).toMatchSnapshot();

package/src/components/ontario-card/ontario-card-types.tsx

@@ -1,12 +1,14 @@
-export const Layouts = ['vertical', 'horizontal'] as const;
-export const HorizontalImagePositionTypes = ['left', 'right'] as const;
-export const HorizontalImageSizeTypes = ['one-fourth', 'one-third'] as const;
+import { HeadingLevel } from '../../utils/common/common.interface';
 
-export type Layout = (typeof Layouts)[number];
-export type HorizontalImagePositionType = (typeof HorizontalImagePositionTypes)[number];
-export type HorizontalImageSizeType = (typeof HorizontalImageSizeTypes)[number];
+export const layoutDirectionDefinitions = ['vertical', 'horizontal'] as const;
+export const horizontalImagePositionDefinitions = ['left', 'right'] as const;
+export const horizontalImageSizeDefinitions = ['one-fourth', 'one-third'] as const;
 
-export const HeaderColours = [
+export type LayoutDirection = (typeof layoutDirectionDefinitions)[number];
+export type HorizontalImagePositionType = (typeof horizontalImagePositionDefinitions)[number];
+export type HorizontalImageSizeType = (typeof horizontalImageSizeDefinitions)[number];
+
+export const headerColourDefinitions = [
 	'dark-accent',
 	'light-accent',
 	'light-gold',
@@ -33,6 +35,13 @@ export const HeaderColours = [
 	'orange',
 	'red',
 	'magenta',
-];
+] as const;
+
+export type HeaderColour = (typeof headerColourDefinitions)[number];
 
-export type HeaderColour = (typeof HeaderColours)[number];
+// Define properties that you would like to track as component state
+export type CardState = {
+	headerColour: HeaderColour | undefined;
+	headingLevel: HeadingLevel | undefined;
+	layoutDirection: LayoutDirection | undefined;
+};

package/src/components/ontario-card/ontario-card.tsx

@@ -1,15 +1,17 @@
 import { Component, Prop, Element, h, State, Watch } from '@stencil/core';
 import {
+	headerColourDefinitions,
 	HeaderColour,
-	HeaderColours,
 	HorizontalImagePositionType,
 	HorizontalImageSizeType,
-	Layout,
-	Layouts,
+	layoutDirectionDefinitions,
+	LayoutDirection,
+	CardState,
 } from './ontario-card-types';
-import { validateValueAgainstArray } from '../../utils/validation/validation-functions';
+import { headingLevelDefinitions, HeadingLevel } from '../../utils/common/common.interface';
 import { ConsoleMessageClass } from '../../utils/console-message/console-message';
 import { printArray } from '../../utils/helper/utils';
+import { validateValueAgainstArray } from '../../utils/validation/validation-functions';
 
 @Component({
 	tag: 'ontario-card',
@@ -32,6 +34,17 @@ export class OntarioCard {
 	 */
 	@Prop() label: string;
 
+	/**
+	 * The heading level that the label will be rendered as.
+	 *
+	 * @example
+	 *	<ontario-card
+	 *		heading-level="h4"
+	 *		label="Card Title 1"
+	 *	>
+	 */
+	@Prop() headingLevel: HeadingLevel = 'h2';
+
 	/**
 	 * Image to be displayed within the card image container.
 	 *
@@ -39,6 +52,22 @@ export class OntarioCard {
 	 */
 	@Prop() image?: string;
 
+	/**
+	 * Alt text for the card's image.
+	 *
+	 * This is optional prop, but may be required for an
+	 * image due to accessibility requirements.
+	 *
+	 * You can find guidance on when to add alt text to an image
+	 * on the Ontario.ca web content editing guide.
+	 *
+	 * https://www.ontario.ca/page/ontario-ca-web-content-editing-guide#alt-text-image-accessibility
+	 *
+	 * Note: This should default to an empty string ('') to ensure the alt attribute appears in the markup
+	 * for decorative images. If left as undefined, the alt attribute will not render in markup.
+	 */
+	@Prop() imageAltText?: string = '';
+
 	/**
 	 * Text to be displayed within the card description container.
 	 *
@@ -54,12 +83,12 @@ export class OntarioCard {
 	@Prop() cardLink?: string;
 
 	/**
-	 * The layout oritnetation of the card.
+	 * The layout direction/orientation of the card.
 	 *
 	 * If no type is passed, it will default to 'vertical'.
 	 *
 	 */
-	@Prop() layout?: Layout = 'vertical';
+	@Prop() layoutDirection?: LayoutDirection = 'vertical';
 
 	/**
 	 * Set the card's header colour.
@@ -112,82 +141,121 @@ export class OntarioCard {
 	 */
 	@Prop() ariaLabelText?: string;
 
+	@State() private cardState: CardState = {
+		headerColour: undefined,
+		headingLevel: undefined,
+		layoutDirection: undefined,
+	};
+
 	/**
-	 * Mutable variable, for internal use only.
-	 * Set the card's layout depending on validation result.
+	 * Watch for changes to the `layoutDirection` property for validation purposes.
+	 *
+	 * If the user input doesn't match one of the array values then `layoutDirection` will be set to its default (`vertical`).
+	 * If a match is found in one of the array values then `cardState.layoutDirection` will be set to the matching array key value.
 	 */
-	@State() private layoutState: string;
+	@Watch('layoutDirection')
+	validateLayoutDirection() {
+		const isValid = this.layoutDirection && validateValueAgainstArray(this.layoutDirection, layoutDirectionDefinitions);
+
+		if (!isValid) {
+			this.printPropWarning(
+				'layout-direction',
+				'<ontario-card>',
+				this.layoutDirection,
+				layoutDirectionDefinitions,
+				'vertical',
+			);
+			this.updateCardState('layoutDirection', 'vertical');
+			return;
+		}
+
+		this.updateCardState('layoutDirection', this.layoutDirection);
+	}
 
 	/**
-	 * Watch for changes to the `layout` property for validation purposes.
+	 * Watch for changes to the `headingLevel` property for validation purposes.
+	 *
+	 * If the user input doesn't match one of the array values then `headingLevel` will be set to its default (`h2`).
 	 *
-	 * If the user input doesn't match one of the array values then `layout` will be set to its default (`vertical`).
-	 * If a match is found in one of the array values then `layoutState` will be set to the matching array key value.
+	 * If a match is found in one of the array values then `headingLevel` will be set to the matching array key value.
 	 */
-	@Watch('layout')
-	validateLayout() {
-		if (this.layout) {
-			const isValid = validateValueAgainstArray(this.layout, Layouts);
-			if (isValid) {
-				this.layoutState = this.layout;
-			} else {
-				this.warnDefaultLayout();
-				this.layoutState = 'vertical';
-			}
+	@Watch('headingLevel')
+	validateHeadingLevel() {
+		const isValid = this.headingLevel && validateValueAgainstArray(this.headingLevel, headingLevelDefinitions);
+
+		if (!isValid) {
+			this.printPropWarning('heading-level', '<ontario-card>', this.headingLevel, headingLevelDefinitions, 'h2');
+			this.updateCardState('headingLevel', 'h2');
+			return;
 		}
+
+		this.updateCardState('headingLevel', this.headingLevel);
 	}
 
 	/**
 	 * Watch for changes to the `headerColour` property for validation purposes.
 	 *
-	 * If the user input doesn't match one of the array values then `headerColour` will be kept empty ('').
+	 * If the user input doesn't match one of the array values then `headerColour` will be kept empty (undefined).
 	 * If a match is found in one of the array values then `headerColour` will be set to the matching array key value.
 	 */
 	@Watch('headerColour')
 	validateHeaderColour() {
-		if (this.headerColour) {
-			const isValid = validateValueAgainstArray(this.headerColour, HeaderColours);
+		const isValid = this.headerColour && validateValueAgainstArray(this.headerColour, headerColourDefinitions);
 
-			if (!isValid) {
-				this.warnDefaultHeaderColour();
-				this.headerColour = '';
-			}
+		if (!isValid && this.headerColour !== undefined) {
+			this.printPropWarning('header-colour', '<ontario-card>', this.headerColour, headerColourDefinitions, 'undefined');
+			this.updateCardState('headerColour', undefined);
+			return;
 		}
+
+		this.updateCardState('headerColour', this.headerColour);
 	}
 
 	/**
-	 * Print the invalid `layout` prop warning message.
+	 * Print an invalid prop warning message.
+	 *
+	 * @param {string} propName - Name of the prop
+	 * @param {string} component - Component the error is on e.g. <ontario-card>
+	 * @param {any} propValue - Value of the prop
+	 * @param {readonly any[]} acceptableValues  - readonly array of acceptable prop values
+	 * @param {string} defaultValue - Stringified representation of the value that the corresponding State Object value will default to
 	 */
-	private warnDefaultLayout() {
+	private printPropWarning(
+		propName: string,
+		component: string,
+		propValue: any,
+		acceptableValues: readonly any[],
+		defaultValue: string,
+	) {
 		const message = new ConsoleMessageClass();
 		message
 			.addDesignSystemTag()
-			.addMonospaceText(' layout ')
+			.addMonospaceText(` ${propName} `)
 			.addRegularText('on')
-			.addMonospaceText(' <ontario-card> ')
-			.addRegularText('was set to an invalid layout; only ')
-			.addMonospaceText(printArray([...Layouts]))
-			.addRegularText(' are supported. The default layout')
-			.addMonospaceText(' vertical ')
+			.addMonospaceText(` ${component} `)
+			.addRegularText('was set to an invalid value of ')
+			.addMonospaceText(` ${propValue} `)
+			.addRegularText('. Only ')
+			.addMonospaceText(printArray([...acceptableValues]))
+			.addRegularText(' are supported values. The default value of')
+			.addMonospaceText(` ${defaultValue} `)
 			.addRegularText('is assumed.')
 			.printMessage();
 	}
 
 	/**
-	 * Print the invalid `headerColour` prop warning message.
+	 * Update a key within the State Object with a value.
+	 *
+	 * Note: When state is represented as an object, and values are changed, the entire object needs to be rebuilt.
+	 * If only the corresponding object key/value is updated, corresponding render changes may not happen.
+	 *
+	 * @param {keyof CardState} key - Should match a key found within `CardState`.
+	 * @param {any} value - Should match the value type associated to the key within `CardState`.
 	 */
-	private warnDefaultHeaderColour() {
-		const message = new ConsoleMessageClass();
-		message
-			.addDesignSystemTag()
-			.addMonospaceText(' header-colour ')
-			.addRegularText('on')
-			.addMonospaceText(' <ontario-card> ')
-			.addRegularText('was set to an invalid colour; only ')
-			.addMonospaceText(printArray([...HeaderColours]))
-			.addRegularText(' are supported. ')
-			.addRegularText('No colour is assumed as the default.')
-			.printMessage();
+	private updateCardState(key: keyof CardState, value: any) {
+		const cardStateCopy = { ...this.cardState };
+		cardStateCopy[key] = value;
+		this.cardState = cardStateCopy;
 	}
 
 	/**
@@ -197,9 +265,9 @@ export class OntarioCard {
 	 */
 	private getCardClasses(): string {
 		const baseClass =
-			this.layoutState === 'horizontal'
-				? `ontario-card ontario-card__card-type--${this.layoutState} ontario-card__image-${this.horizontalImagePositionType} ontario-card__image-size-${this.horizontalImageSizeType}`
-				: `ontario-card ontario-card__card-type--basic ontario-card--position-${this.layoutState}`;
+			this.cardState.layoutDirection === 'horizontal'
+				? `ontario-card ontario-card__card-type--${this.cardState.layoutDirection} ontario-card__image-${this.horizontalImagePositionType} ontario-card__image-size-${this.horizontalImageSizeType}`
+				: `ontario-card ontario-card__card-type--basic ontario-card--position-${this.cardState.layoutDirection}`;
 
 		const descriptionClass = this.description ? '' : ' ontario-card__description-false';
 
@@ -217,10 +285,7 @@ export class OntarioCard {
 	private getCardHeadingClasses(): string {
 		const baseClass = 'ontario-card__heading';
 
-		const backgroundClass =
-			this.headerColour && validateValueAgainstArray(this.headerColour, HeaderColours)
-				? `ontario-card__heading--${this.headerColour}`
-				: '';
+		const backgroundClass = this.cardState.headerColour ? `ontario-card__heading--${this.cardState.headerColour}` : '';
 
 		return `${baseClass} ${backgroundClass}`.trim();
 	}
@@ -240,7 +305,8 @@ export class OntarioCard {
 	 * https://stenciljs.com/docs/component-lifecycle#connectedcallback
 	 */
 	componentWillLoad() {
-		this.validateLayout();
+		this.validateLayoutDirection();
+		this.validateHeadingLevel();
 		this.validateHeaderColour();
 	}
 
@@ -250,16 +316,26 @@ export class OntarioCard {
 				{this.image && (
 					<div class="ontario-card__image-container">
 						<a href={this.getHref()} aria-label={this.ariaLabelText}>
-							<img class="ontario-card__image" src={this.image} />
+							<img class="ontario-card__image" alt={this.imageAltText} src={this.image} />
 						</a>
 					</div>
 				)}
 				<div class={`ontario-card__text-container ${this.image ? 'ontario-card--image-true' : ''}`}>
-					<h2 class={this.getCardHeadingClasses()}>
+					{/**
+					 * h() is a stencil wrapped shorthand method for a render function, and is very
+					 * similar to the h() method or createElement() method found within React
+					 * It accepts 3 parameters:
+					 *  - a string interpretation of an HTML tag (e.g. 'h2')
+					 *  - an object of properties / attributes (e.g. 'id', 'className')
+					 *  - The innerHTML such as a string, or additional HTML elements
+					 */}
+					{h(
+						this.cardState.headingLevel, //tag
+						{ className: this.getCardHeadingClasses() }, //attributes
 						<a href={this.getHref()} aria-label={this.ariaLabelText}>
 							{this.label}
-						</a>
-					</h2>
+						</a>,
+					)}
 					{this.description && (
 						<div class="ontario-card__description">
 							<p>{this.description}</p>