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

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

@@ -0,0 +1,89 @@
+import { OntarioTask } from '@ongov/ontario-design-system-component-library-react';
+
+# ontario-task
+
+Use a task to show the user activities they have completed and what they have left to do.
+
+## Usage guidance
+
+Please refer to the [Ontario Design System](https://designsystem.ontario.ca/components/detail/task-list.html) for current documentation guidance for tables.
+
+## Configuration
+
+Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the task component can be added directly into the project's code, and can be customized by updating the properties outlined [here](#properties). Additional information on custom types for header properties are outlined [here](#custom-property-types). Please see the [examples](#examples) below for how to configure the component.
+
+## Examples
+
+Example of a bare-bones task.
+
+```html
+<ontario-task label="Task" task-id="Task-id" task-status="notStarted" link="https://example.com"></ontario-task>
+```
+
+<div>
+	<OntarioTask 
+		label="Task" 
+		task-id="Task-id" 
+		task-status="notStarted" 
+		link="https://example.com">
+	</OntarioTask>
+</div>
+
+Example of a task with a hint.
+
+```html
+<ontario-task
+	label="Task"
+	task-id="Task-id"
+	hint-text="A hint for task"
+	hint-text-id="task-hint"
+	task-status="completed"
+	link="https://example.com"
+></ontario-task>
+```
+
+<div>
+	<OntarioTask
+		label="Task"
+		task-id="Task-id"
+		hint-text="A hint for task"
+		hint-text-id="task-hint"
+		task-status="completed"
+		link="https://example.com"
+	></OntarioTask>
+</div>
+
+<!-- Auto Generated Below -->
+
+## Properties
+
+| Property         | Attribute         | Description                                                                                                                                                                                                         | Type                                                                                                                                                         | Default                   |
+| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
+| `deactivateLink` | `deactivate-link` | Disables the task link when set to `true`. Default is `false`, meaning the link will be active if provided.                                                                                                         | `boolean`                                                                                                                                                    | `false`                   |
+| `headingLevel`   | `heading-level`   | Allows consumers to define the heading level for the task label. Accepts 'h2', 'h3' or 'h4'. Default is 'h3'.                                                                                                       | `"h2" \| "h3" \| "h4"`                                                                                                                                       | `'h3'`                    |
+| `hintText`       | `hint-text`       | Used to include the ontario-hint-text component for the task. This is optional.                                                                                                                                     | `Hint \| string \| undefined`                                                                                                                                | `undefined`               |
+| `label`          | `label`           | Specifies the label of the task. This is required to provide the name of the task.                                                                                                                                  | `string`                                                                                                                                                     | `undefined`               |
+| `language`       | `language`        | The language of the component. This is used for translations, and is by default set through event listeners checking for a language property from the header. If no language is passed, it will default to English. | `"en" \| "fr" \| undefined`                                                                                                                                  | `undefined`               |
+| `link`           | `link`            | Specifies an optional link associated with the task. If provided, clicking the task will navigate to this URL.                                                                                                      | `string \| undefined`                                                                                                                                        | `undefined`               |
+| `taskId`         | `task-id`         | A unique id for the task. This is required.                                                                                                                                                                         | `string`                                                                                                                                                     | `undefined`               |
+| `taskStatus`     | `task-status`     | Defines the status of the task, with default set to 'NotStarted'. Accepts values from `TaskStatuses` enum: `NotStarted`, `InProgress`, `Completed`, etc.                                                            | `TaskStatuses.CannotStartYet \| TaskStatuses.Completed \| TaskStatuses.Error \| TaskStatuses.InProgress \| TaskStatuses.NotStarted \| TaskStatuses.Optional` | `TaskStatuses.NotStarted` |
+
+## Dependencies
+
+### Depends on
+
+- [ontario-hint-text](../ontario-hint-text)
+- [ontario-badge](../ontario-badge)
+
+### Graph
+
+```mermaid
+graph TD;
+  ontario-task --> ontario-hint-text
+  ontario-task --> ontario-badge
+  style ontario-task fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+---
+
+_Built with [StencilJS](https://stenciljs.com/)_

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

@@ -0,0 +1,58 @@
+import { newE2EPage } from '@stencil/core/testing';
+
+describe('ontario-task', () => {
+	it('renders', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-task label="Task Label" task-id="task-1"></ontario-task>');
+
+		const element = await page.find('ontario-task');
+		expect(element).toHaveClass('hydrated');
+	});
+
+	it('renders with correct label', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-task label="My Task" task-id="task-2"></ontario-task>');
+
+		const label = await page.find('ontario-task >>> .ontario-task__label');
+		expect(label).toEqualText('My Task');
+	});
+
+	it('applies the correct task status class', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-task task-id="task-3" task-status="InProgress"></ontario-task>');
+
+		const element = await page.find('ontario-task');
+		const className = await element.getProperty('className');
+		expect(className).toContain('ontario-task-status--in-progress');
+	});
+
+	it('displays the badge with the correct status', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-task task-id="task-4" task-status="Completed"></ontario-task>');
+
+		const badge = await page.find('ontario-task >>> .ontario-task__badge');
+		expect(badge).toBeTruthy();
+		expect(badge).toEqualText('Completed');
+	});
+
+	it('does not render as a link when "deactivateLink" is true', async () => {
+		const page = await newE2EPage();
+		await page.setContent(
+			'<ontario-task label="No Link" task-id="task-6" link="https://example.com" deactivate-link="true"></ontario-task>',
+		);
+
+		const link = await page.find('ontario-task >>> .ontario-task__link');
+		expect(link).toBeNull();
+	});
+
+	it('renders hint text when "hintText" prop is provided', async () => {
+		const page = await newE2EPage();
+		await page.setContent(
+			'<ontario-task label="Task with Hint" task-id="task-7" hint-text="This is a hint"></ontario-task>',
+		);
+
+		const hintText = await page.find('ontario-task >>> ontario-hint-text');
+		expect(hintText).toBeTruthy();
+		expect(hintText).toEqualText('This is a hint');
+	});
+});

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

@@ -0,0 +1,97 @@
+import { newSpecPage } from '@stencil/core/testing';
+import { OntarioTask } from '../ontario-task';
+
+describe('ontario-task', () => {
+	it('renders with default props', async () => {
+		const page = await newSpecPage({
+			components: [OntarioTask],
+			html: `<ontario-task task-status="notStarted" task-id="task-1"></ontario-task>`,
+		});
+
+		if (!page.root) {
+			throw new Error('Component did not render properly.');
+		}
+
+		expect(page.root).toEqualHtml(`
+					<ontario-task data-task-status="notStarted" task-id="task-1" task-status="notStarted">
+							<mock:shadow-root>
+								<li aria-labelledby="task-label--task-1" class="ontario-task ontario-task-status--not-started" data-task-status="notStarted" role="group">
+											<div>
+													<div class="ontario-task__content">
+															<h3 class="ontario-task__label" id="task-label--task-1"></h3>
+															<ontario-badge aria-label="Task Status: Not Started (notStarted)" class="ontario-task__badge" colour="lightTeal" role="status">
+																	Not Started
+															</ontario-badge>
+													</div>
+											</div>
+									</li>
+							</mock:shadow-root>
+					</ontario-task>
+			`);
+	});
+
+	it('renders with a custom label', async () => {
+		const page = await newSpecPage({
+			components: [OntarioTask],
+			html: `<ontario-task task-status="inProgress" task-id="task-2" label="Task 2"></ontario-task>`,
+		});
+
+		if (!page.root) {
+			throw new Error('Component did not render properly.');
+		}
+
+		expect(page.root.shadowRoot?.querySelector('.ontario-task__label')?.textContent).toBe('Task 2');
+	});
+
+	it('renders with a different task status', async () => {
+		const page = await newSpecPage({
+			components: [OntarioTask],
+			html: `<ontario-task task-status="completed" task-id="task-3"></ontario-task>`,
+		});
+
+		if (!page.root) {
+			throw new Error('Component did not render properly.');
+		}
+
+		const badge = page.root.shadowRoot?.querySelector('ontario-badge');
+		expect(badge?.getAttribute('aria-label')).toBe('Task Status: Completed (completed)');
+		expect(badge?.getAttribute('colour')).toBe('white');
+		expect(badge?.textContent).toBe('Completed');
+	});
+
+	it('updates when task status changes', async () => {
+		const page = await newSpecPage({
+			components: [OntarioTask],
+			html: `<ontario-task task-status="notStarted" task-id="task-4"></ontario-task>`,
+		});
+
+		if (!page.root) {
+			throw new Error('Component did not render properly.');
+		}
+
+		const badge = page.root.shadowRoot?.querySelector('ontario-badge');
+		expect(badge?.textContent).toBe('Not Started');
+
+		// Update the task status
+		page.root.setAttribute('task-status', 'inProgress');
+		await page.waitForChanges();
+
+		expect(badge?.getAttribute('aria-label')).toBe('Task Status: In Progress (inProgress)');
+		expect(badge?.textContent).toBe('In Progress');
+	});
+
+	it('renders with accessibility attributes', async () => {
+		const page = await newSpecPage({
+			components: [OntarioTask],
+			html: `<ontario-task task-status="notStarted" task-id="task-5" label="Accessible Task"></ontario-task>`,
+		});
+
+		if (!page.root) {
+			throw new Error('Component did not render properly.');
+		}
+
+		const listItem = page.root.shadowRoot?.querySelector('li');
+		expect(listItem?.getAttribute('role')).toBe('group');
+		expect(listItem?.getAttribute('aria-labelledby')).toBe('task-label--task-5');
+	});
+});

package/src/components/ontario-task-list/ontario-task-list.scss

@@ -0,0 +1,14 @@
+@use '@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/colours.variables' as colours;
+@use '@ongov/ontario-design-system-global-styles/dist/styles/scss/2-tools/functions/global.functions' as globalFunctions;
+@use '@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/global.variables' as globalVariables;
+@use '@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/spacing.variables' as spacing;
+
+.ontario-task-list {
+	border-top: globalFunctions.px-to-rem(2) solid colours.$ontario-greyscale-20;
+	padding: spacing.$spacing-0;
+}
+
+.ontario-task-list__item {
+	max-width: globalVariables.$full-width;
+	list-style-type: none;
+}

package/src/components/ontario-task-list/ontario-task-list.tsx

@@ -0,0 +1,177 @@
+import { h, Component, Element, Prop, State, Watch } from '@stencil/core';
+import { Language } from '../../utils/common/language-types';
+import { ConsoleMessageClass } from '../../utils/console-message/console-message';
+import { validateLanguage } from '../../utils/validation/validation-functions';
+import translations from '../../translations/global.i18n.json';
+import { HeadingLevel } from '../../utils/common/common.interface';
+import { validateValueAgainstArray } from '../../utils/validation/validation-functions';
+import { TaskStatuses } from '../../utils/common/task-statuses.enum';
+export type TaskListHeadingLevel = 'h1' | Exclude<HeadingLevel, 'h6'>;
+
+@Component({
+	tag: 'ontario-task-list',
+	styleUrl: 'ontario-task-list.scss',
+	shadow: true,
+})
+export class OntarioTaskList {
+	@Element() el: HTMLElement;
+
+	/**
+	 * The label prop used for the task list heading.
+	 */
+	@Prop() label: string;
+
+	/**
+	 * Allows consumers to define the heading level for the task list component.
+	 *
+	 * Accepts 'h1', 'h2', 'h3' or 'h4'. Default is 'h2'.
+	 */
+	@Prop() headingLevel: TaskListHeadingLevel = 'h2';
+
+	/**
+	 * The language of the component.
+	 * This is used for translations, and is by default set through event listeners checking for a language property from the header. If none are passed, it will default to English.
+	 */
+	@Prop({ mutable: true }) language?: Language = 'en';
+
+	/**
+	 * State to track the number of completed tasks.
+	 */
+	@State() completedTasks: number = 0;
+
+	/**
+	 * State to track the total number of tasks.
+	 */
+	@State() totalTasks: number = 0;
+
+	/**
+	 * Class-level constant for task count delay in milliseconds.
+	 *
+	 * This delay ensures that the `ontario-task` custom elements are fully upgraded and rendered
+	 * in the DOM before the `countTasks` method is executed. Without this delay, the component
+	 * might attempt to query or count tasks before they are properly initialized, leading to
+	 * inaccurate task counts.
+	 */
+	private static readonly TASK_COUNT_DELAY_MS = 50;
+
+	/**
+	 * Watch for changes in `headingLevel` prop to validate its value.
+	 */
+	@Watch('headingLevel')
+	validateHeadingLevel(newValue: string) {
+		const allowedValues: TaskListHeadingLevel[] = ['h1', 'h2', 'h3', 'h4', 'h5'];
+
+		// Validate the new value against the allowed values
+		const isValid = validateValueAgainstArray(newValue, allowedValues);
+
+		if (!isValid) {
+			const message = new ConsoleMessageClass();
+			message
+				.addDesignSystemTag()
+				.addMonospaceText(' headingLevel ')
+				.addRegularText('on')
+				.addMonospaceText(' <ontario-task-list> ')
+				.addRegularText('was set to an invalid value; only ')
+				.addMonospaceText(allowedValues.join(', '))
+				.addRegularText(' are supported. The default value ')
+				.addMonospaceText('h2')
+				.addRegularText(' is assumed.')
+				.printMessage();
+
+			this.headingLevel = 'h2';
+		}
+	}
+
+	/**
+	 * Counts the total tasks and completed tasks by querying for `ontario-task` elements.
+	 */
+	countTasks() {
+		const slot = this.el.shadowRoot?.querySelector('slot');
+		const tasks = slot
+			? (slot.assignedElements().filter((el) => el.tagName.toLowerCase() === 'ontario-task') as HTMLElement[])
+			: [];
+
+		this.totalTasks = tasks.length;
+
+		this.completedTasks = tasks.filter((task) => {
+			// Get the status directly from the light DOM
+			const status = task.getAttribute('data-task-status');
+			return status === TaskStatuses.Completed;
+		}).length;
+	}
+
+	/**
+	 * Lifecycle method: before the component loads, validate heading level.
+	 */
+	async componentWillLoad() {
+		this.validateHeadingLevel(this.headingLevel);
+	}
+
+	/**
+	 * Ensure tasks are counted after custom elements are fully upgraded.
+	 */
+	connectedCallback() {
+		// Wait for the custom element to be fully defined before counting
+		customElements.whenDefined('ontario-task').then(() => {
+			setTimeout(() => {
+				this.countTasks();
+			}, OntarioTaskList.TASK_COUNT_DELAY_MS);
+		});
+	}
+
+	/**
+	 * Use slotchange and MutationObserver to track changes in slot content.
+	 */
+	componentDidLoad() {
+		const slot = this.el.shadowRoot?.querySelector('slot');
+		if (slot) {
+			slot.addEventListener('slotchange', () => {
+				this.countTasks();
+			});
+		}
+
+		// Observe changes to the light DOM for accurate counting
+		const observer = new MutationObserver((_mutations) => {
+			this.countTasks();
+		});
+		observer.observe(this.el, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: ['data-task-status'],
+		});
+	}
+
+	componentDidRender() {
+		setTimeout(() => {
+			this.countTasks();
+		}, OntarioTaskList.TASK_COUNT_DELAY_MS);
+	}
+
+	render() {
+		// Resolve the language to ensure valid translations are used.
+		const resolvedLanguage = validateLanguage(this.language);
+
+		const headingProps = {
+			class: { 'ontario-task-list__heading': true },
+		};
+
+		return (
+			<div class="ontario-task-list__container">
+				{h(this.headingLevel, headingProps, this.label)}
+
+				<p class="ontario-task-list__completion-text" aria-live="polite">
+					{translations.taskGroup.completed[resolvedLanguage]}&nbsp;
+					{this.completedTasks}&nbsp;
+					{translations.taskGroup.outOf[resolvedLanguage]}&nbsp;
+					{this.totalTasks}&nbsp;
+					{translations.taskGroup.tasks[resolvedLanguage]}
+				</p>
+
+				<ul class="ontario-task-list" role="list">
+					<slot></slot>
+				</ul>
+			</div>
+		);
+	}
+}

package/src/components/ontario-task-list/readme.md

@@ -0,0 +1,74 @@
+import { OntarioTaskList, OntarioTask } from '@ongov/ontario-design-system-component-library-react';
+
+# ontario-task-list
+
+Use a task list to show the user activities they have completed and what they have left to do.
+
+## Usage guidance
+
+Please refer to the [Ontario Design System](https://designsystem.ontario.ca/components/detail/task-list.html) for current documentation guidance for task list.
+
+## Prerequisites
+
+Before using the `ontario-task-list` component, ensure the following:
+
+1. The Ontario Design System Component Library is installed in your project. Refer to the [installation instructions](https://designsystem.ontario.ca/getting-started/installation.html) for guidance.
+2. The component library is properly configured in your project (e.g., included in your build process if using a framework like React or Angular).
+
+## Examples
+
+Example of a task-list component with tasks inside.
+
+```html
+<ontario-task-list language="en">
+	<ontario-task
+		label="Task 1"
+		task-id="Task-1-unique-id"
+		hint-text="A hint for task 1"
+		task-status="completed"
+		link="https://example.com"
+	></ontario-task>
+	<ontario-task
+		label="Task 2"
+		task-id="Task-2-unique-id"
+		hint-text="A hint for task 2"
+		task-status="inProgress"
+		link="https://example.com"
+		deactivate-link="true"
+	>
+</ontario-task-list>
+```
+
+<div>
+	<OntarioTaskList language="en">
+		<OntarioTask
+			label="Task 1"
+			task-id="Task-1-unique-id"
+			hint-text="A hint for task 1"
+			task-status="completed"
+			link="https://example.com"
+		></OntarioTask>
+		<OntarioTask
+			label="Task 2"
+			task-id="Task-2-unique-id"
+			hint-text="A hint for task 2"
+			task-status="inProgress"
+			link="https://example.com"
+			deactivate-link="true"
+		></OntarioTask>
+	</OntarioTaskList>
+</div>
+
+<!-- Auto Generated Below -->
+
+## Properties
+
+| Property       | Attribute       | Description                                                                                                                                                                                                   | Type                                   | Default     |
+| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------- |
+| `headingLevel` | `heading-level` | Allows consumers to define the heading level for the task list component. Accepts 'h1', 'h2', 'h3' or 'h4'. Default is 'h2'.                                                                                  | `"h1" \| "h2" \| "h3" \| "h4" \| "h5"` | `'h2'`      |
+| `label`        | `label`         | The label prop used for the task list heading.                                                                                                                                                                | `string`                               | `undefined` |
+| `language`     | `language`      | The language of the component. This is used for translations, and is by default set through event listeners checking for a language property from the header. If none are passed, it will default to English. | `"en" \| "fr" \| undefined`            | `'en'`      |
+
+---
+
+_Built with [StencilJS](https://stenciljs.com/)_

package/src/components/ontario-task-list/test/ontario-task-list.e2e.ts

@@ -0,0 +1,30 @@
+import { newE2EPage } from '@stencil/core/testing';
+
+describe('ontario-task-list component', () => {
+	it('renders with default props', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-task-list label="My Tasks"></ontario-task-list>');
+
+		const element = await page.find('ontario-task-list');
+		expect(element).toHaveClass('hydrated');
+
+		const label = await page.find('ontario-task-list >>> .ontario-task-list__heading');
+		expect(label.textContent).toBe('My Tasks');
+	});
+
+	it('updates label dynamically', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-task-list label="Initial Tasks"></ontario-task-list>');
+
+		let label = await page.find('ontario-task-list >>> .ontario-task-list__heading');
+		expect(label.textContent).toBe('Initial Tasks');
+
+		// Update the label prop
+		const element = await page.find('ontario-task-list');
+		element.setProperty('label', 'Updated Tasks');
+		await page.waitForChanges();
+
+		label = await page.find('ontario-task-list >>> .ontario-task-list__heading');
+		expect(label.textContent).toBe('Updated Tasks');
+	});
+});

package/src/components/ontario-task-list/test/ontario-task-list.spec.tsx

@@ -0,0 +1,67 @@
+import { newSpecPage } from '@stencil/core/testing';
+import { OntarioTaskList } from '../ontario-task-list';
+
+describe('ontario-task-list', () => {
+	beforeAll(() => {
+		global.MutationObserver = class {
+			constructor(callback: any) {
+				(this as any).callback = callback;
+			}
+			observe(_target: any, _options: any) {}
+			disconnect() {}
+			takeRecords() {
+				return [];
+			}
+		} as any;
+	});
+
+	it('renders with a label and updates when the label changes', async () => {
+		const page = await newSpecPage({
+			components: [OntarioTaskList],
+			html: `<ontario-task-list label="My Task List"></ontario-task-list>`,
+		});
+
+		if (!page.root) {
+			throw new Error('Component did not render properly.');
+		}
+
+		const heading = page.root.shadowRoot?.querySelector('.ontario-task-list__heading');
+		if (!heading) {
+			throw new Error('Heading element not found in shadowRoot.');
+		}
+
+		expect(heading.textContent).toBe('My Task List');
+
+		// Update the label prop
+		page.root.setAttribute('label', 'Updated Task List');
+		await page.waitForChanges();
+
+		expect(heading.textContent).toBe('Updated Task List');
+	});
+
+	it('handles language changes and updates translations', async () => {
+		const page = await newSpecPage({
+			components: [OntarioTaskList],
+			html: `<ontario-task-list language="en"></ontario-task-list>`,
+		});
+
+		if (!page.root) {
+			throw new Error('Component did not render properly.');
+		}
+
+		// Verify initial language
+		let completionText = page.root.shadowRoot?.querySelector('.ontario-task-list__completion-text')?.textContent;
+		if (!completionText) {
+			throw new Error('Completion text element not found in shadowRoot.');
+		}
+		expect(completionText).toBe('You have completed 0 out of 0 tasks.');
+
+		// Change language to French
+		page.root.setAttribute('language', 'fr');
+		await page.waitForChanges();
+
+		// Verify updated translation
+		completionText = page.root.shadowRoot?.querySelector('.ontario-task-list__completion-text')?.textContent;
+		expect(completionText).toBe('Vous avez complété 0 sur 0 tâches.');
+	});
+});

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

@@ -128,21 +128,21 @@ hintExpander='{ "hint": "This is the hint expander title", "content": "This is t
 
 ## Properties
 
-| Property         | Attribute       | Description                                                                                                                                                                                                                                    | Type                                    | Default     |
-| ---------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- |
-| `caption`        | `caption`       | The text to display as the textarea label.                                                                                                                                                                                                     | `Caption \| string`                     | `undefined` |
-| `customOnBlur`   | --              | Used to add a custom function to the textarea onBlur event.                                                                                                                                                                                    | `((event: Event) => void) \| undefined` | `undefined` |
-| `customOnChange` | --              | Used to add a custom function to the textarea onChange event.                                                                                                                                                                                  | `((event: Event) => void) \| undefined` | `undefined` |
-| `customOnFocus`  | --              | Used to add a custom function to the textarea onFocus event.                                                                                                                                                                                   | `((event: Event) => void) \| undefined` | `undefined` |
-| `customOnInput`  | --              | Used to add a custom function to the textarea onInput event.                                                                                                                                                                                   | `((event: Event) => void) \| undefined` | `undefined` |
-| `elementId`      | `element-id`    | The unique identifier of the textarea. This is optional - if no ID is passed, one will be generated.                                                                                                                                           | `string \| undefined`                   | `undefined` |
-| `errorMessage`   | `error-message` | Set this to display an error message                                                                                                                                                                                                           | `string \| undefined`                   | `undefined` |
-| `hintExpander`   | `hint-expander` | Used to include the ontario-hint-expander component for the textarea component. This is passed in as an object with key-value pairs. This is optional.                                                                                         | `HintExpander \| string \| undefined`   | `undefined` |
-| `hintText`       | `hint-text`     | Used to include the ontario-hint-text component for the textarea. This is optional.                                                                                                                                                            | `Hint \| string \| undefined`           | `undefined` |
-| `language`       | `language`      | The language of the component. This is used for translations, and is by default set through event listeners checking for a language property from the header. If no language is passed, it will default to English.                            | `"en" \| "fr" \| undefined`             | `undefined` |
-| `name`           | `name`          | The name assigned to the textarea. The name value is used to reference form data after a form is submitted.                                                                                                                                    | `string`                                | `undefined` |
-| `required`       | `required`      | This is used to determine whether the textarea is required or not. This prop also gets passed to the InputCaption utility to display either an optional or required flag in the label. If no prop is set, it will default to false (optional). | `boolean \| undefined`                  | `false`     |
-| `value`          | `value`         | The textarea content value.                                                                                                                                                                                                                    | `string \| undefined`                   | `undefined` |
+| Property         | Attribute          | Description                                                                                                                                                                                                                                    | Type                                    | Default     |
+| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- |
+| `caption`        | `caption`          | The text to display as the textarea label.                                                                                                                                                                                                     | `Caption \| string`                     | `undefined` |
+| `customOnBlur`   | `custom-on-blur`   | Used to add a custom function to the textarea onBlur event.                                                                                                                                                                                    | `((event: Event) => void) \| undefined` | `undefined` |
+| `customOnChange` | `custom-on-change` | Used to add a custom function to the textarea onChange event.                                                                                                                                                                                  | `((event: Event) => void) \| undefined` | `undefined` |
+| `customOnFocus`  | `custom-on-focus`  | Used to add a custom function to the textarea onFocus event.                                                                                                                                                                                   | `((event: Event) => void) \| undefined` | `undefined` |
+| `customOnInput`  | `custom-on-input`  | Used to add a custom function to the textarea onInput event.                                                                                                                                                                                   | `((event: Event) => void) \| undefined` | `undefined` |
+| `elementId`      | `element-id`       | The unique identifier of the textarea. This is optional - if no ID is passed, one will be generated.                                                                                                                                           | `string \| undefined`                   | `undefined` |
+| `errorMessage`   | `error-message`    | Set this to display an error message                                                                                                                                                                                                           | `string \| undefined`                   | `undefined` |
+| `hintExpander`   | `hint-expander`    | Used to include the ontario-hint-expander component for the textarea component. This is passed in as an object with key-value pairs. This is optional.                                                                                         | `HintExpander \| string \| undefined`   | `undefined` |
+| `hintText`       | `hint-text`        | Used to include the ontario-hint-text component for the textarea. This is optional.                                                                                                                                                            | `Hint \| string \| undefined`           | `undefined` |
+| `language`       | `language`         | The language of the component. This is used for translations, and is by default set through event listeners checking for a language property from the header. If no language is passed, it will default to English.                            | `"en" \| "fr" \| undefined`             | `undefined` |
+| `name`           | `name`             | The name assigned to the textarea. The name value is used to reference form data after a form is submitted.                                                                                                                                    | `string`                                | `undefined` |
+| `required`       | `required`         | This is used to determine whether the textarea is required or not. This prop also gets passed to the InputCaption utility to display either an optional or required flag in the label. If no prop is set, it will default to false (optional). | `boolean \| undefined`                  | `false`     |
+| `value`          | `value`            | The textarea content value.                                                                                                                                                                                                                    | `string \| undefined`                   | `undefined` |
 
 ## Events