@ongov/ontario-design-system-component-library 4.3.0-alpha.2 → 4.3.0

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

@@ -0,0 +1,105 @@
+import { E2EElement, E2EPage, newE2EPage } from '@stencil/core/testing';
+
+describe('ontario-badge', () => {
+	it('renders', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-badge></ontario-badge>');
+		const component = await page.find('ontario-badge');
+		const element = await page.find('ontario-badge >>> span');
+
+		expect(component).toHaveClass('hydrated');
+		expect(element).toHaveClasses(['ontario-badge', 'ontario-badge--default-heavy']);
+	});
+
+	describe('render prop changes', () => {
+		let page: E2EPage;
+		let component: E2EElement;
+		let element: E2EElement;
+
+		beforeEach(async () => {
+			page = await newE2EPage();
+			await page.setContent('<ontario-badge></ontario-badge>');
+			component = await page.find('ontario-badge');
+			element = await page.find('ontario-badge >>> span');
+		});
+
+		it('renders changes to the class names when the colour prop is changed', async () => {
+			component.setProperty('colour', 'light-teal');
+			await page.waitForChanges();
+
+			expect(element).toHaveClasses(['ontario-badge', 'ontario-badge--default-light']);
+
+			component.setProperty('colour', 'black');
+			await page.waitForChanges();
+
+			expect(element).toHaveClasses(['ontario-badge', 'ontario-badge--neutral-heavy']);
+		});
+
+		/*
+		 * TODO: Haven't found an ideal way yet to test the aria-label-text property and how
+		 * it should create an aria-label attribute on the element.
+		 */
+		// it('renders changes to the aria-label-text property', async () => {
+		// component.setProperty('aria-label-text', 'This is aria label text.');
+		// await page.waitForChanges();
+
+		// expect(element.getAttribute("ariaLabel")).toBe("This is aria label text.");
+
+		// expect(element).toHaveAttribute('aria-label');
+
+		// let v = await page.$eval(element, (element: { hasAttribute: (arg0: string) => any; }) => element.hasAttribute("aria-label"))
+		// expect(v).toBe(true);
+		// let el: any;
+		// let value = await page.evaluate(element => element ? element.getAttribute("aria-label") : null, el);
+		// expect(value).toBe(true);
+
+		// element.hasAttribute("aria-label").toBe(true);
+		// expect(hasAriaLabelAttribute).toBe(true);
+		// await page.evaluate(`${element}.getAttribute("data-Color")`)
+
+		// expect(element.getAttribute('aria-label')).toBe('This is aria label text.');
+		// });
+	});
+
+	describe('render text content changes', () => {
+		let page: E2EPage;
+
+		beforeEach(async () => {
+			page = await newE2EPage();
+		});
+
+		it('renders changes to the component content when the host textContent is changed', async () => {
+			await page.setContent('<ontario-badge>Not started</ontario-badge>');
+			const element = await page.find('ontario-badge >>> span');
+
+			expect(element).toEqualText('Not started');
+		});
+
+		it('renders changes to the component content when the label prop is changed', async () => {
+			await page.setContent('<ontario-badge></ontario-badge>');
+			const component = await page.find('ontario-badge');
+			const element = await page.find('ontario-badge >>> span');
+
+			component.setProperty('label', 'Completed');
+			await page.waitForChanges();
+
+			expect(element).toEqualText('Completed');
+
+			component.setProperty('label', 'In progress');
+			await page.waitForChanges();
+
+			expect(element).toEqualText('In progress');
+		});
+
+		it('renders label content as priority even if host textContent is set', async () => {
+			await page.setContent('<ontario-badge>Not started</ontario-badge>');
+			const component = await page.find('ontario-badge');
+			const element = await page.find('ontario-badge >>> span');
+
+			component.setProperty('label', 'In progress');
+			await page.waitForChanges();
+
+			expect(element).toEqualText('In progress');
+		});
+	});
+});

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

@@ -0,0 +1,40 @@
+import { newSpecPage } from '@stencil/core/testing';
+import { OntarioBadge } from '../ontario-badge';
+
+describe('ontario-badge', () => {
+	it('should render the expected base html', async () => {
+		const page = await newSpecPage({
+			components: [OntarioBadge],
+			html: `<ontario-badge>In progress</ontario-badge>`,
+		});
+
+		expect(page.root).toMatchSnapshot();
+	});
+
+	it('should override the host textContent with label prop output on the span element', async () => {
+		const page = await newSpecPage({
+			components: [OntarioBadge],
+			html: `<ontario-badge label="completed">In progress</ontario-badge>`,
+		});
+
+		expect(page.root).toMatchSnapshot();
+	});
+
+	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>`,
+		});
+
+		expect(page.root).toMatchSnapshot();
+	});
+
+	it('should render the aria-label attribute on the span element', async () => {
+		const page = await newSpecPage({
+			components: [OntarioBadge],
+			html: `<ontario-badge aria-label-text="This course is currently in progress.">In progress</ontario-badge>`,
+		});
+
+		expect(page.root).toMatchSnapshot();
+	});
+});

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

@@ -72,6 +72,7 @@ export class OntarioButton implements Button {
 	/**
 	 * A reference to the internal button element.
 	 */
+
 	private buttonRef: HTMLButtonElement;
 
 	/*
@@ -94,11 +95,7 @@ export class OntarioButton implements Button {
 	@Watch('type')
 	validateType() {
 		const isValid = validateValueAgainstArray(this.type, ButtonTypes);
-		if (isValid) {
-			this.typeState = this.type;
-		} else {
-			this.typeState = this.warnDefaultType();
-		}
+		this.typeState = isValid ? this.type : this.warnDefaultType();
 	}
 
 	/**
@@ -110,11 +107,7 @@ export class OntarioButton implements Button {
 	@Watch('htmlType')
 	validateHtmlType() {
 		const isValid = validateValueAgainstArray(this.htmlType, HtmlTypes);
-		if (isValid) {
-			this.htmlTypeState = this.htmlType;
-		} else {
-			this.htmlTypeState = this.warnDefaultHtmlType();
-		}
+		this.htmlTypeState = isValid ? this.htmlType : this.warnDefaultHtmlType();
 	}
 
 	/**
@@ -209,9 +202,10 @@ export class OntarioButton implements Button {
 
 		// Add a click event listener to handle submitting a form
 		if (this.htmlTypeState === 'submit') {
-			const { form } = this.internals;
-			// Based off a comment within this bug about preventDefault(): https://bugzilla.mozilla.org/show_bug.cgi?id=1370630
-			this.buttonRef.addEventListener('click', () => form?.dispatchEvent(new Event('submit', { cancelable: true })));
+			this.buttonRef.addEventListener('click', () => {
+				const { form } = this.internals;
+				form?.requestSubmit();
+			});
 		}
 	}
 

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

@@ -147,6 +147,60 @@ The `ontario-checkboxes` supports integration with native HTML `<form>` elements
 
 Remember to set the `name` attribute as this is used to identify the field when submitting the form.
 
+## Event model
+
+Each event emitted by the component uses the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) type to emit a custom event to help communicate what the component is doing. To access the data emitted by the component within the `CustomEvent` type use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property.
+
+Eg. To access the value of any change made to this component from the `checkboxOnChange` event, use the following code to wire up to listen for the the `checkboxOnChange` event.
+
+```html
+<ontario-checkboxes
+	caption="Checkboxes"
+	id="checkboxes-1"
+	name="checkboxes-1"
+	required
+	options='[
+      {
+        "value": "checkbox-option-1",
+        "label": "Checkbox option 1 label",
+        "elementId": "checkbox-1"
+      },
+      {
+        "value": "checkbox-option-2",
+        "label": "Checkbox option 2 label",
+        "elementId": "checkbox-2"
+      }
+    ]'
+>
+</ontario-checkboxes>
+<script>
+	// Note: this waits for the page and components to load before
+	// locating the component.
+	window.onload = () => {
+		const checkboxes1 = document.getElementById('checkboxes-1');
+		checkboxes1.addEventListener('checkboxOnChange', (event) => {
+			console.log('OnChange detail:', event.detail);
+		});
+	};
+</script>
+```
+
+If the first checkbox is checked within `checkboxes-1`, the value of `event.detail` is the object emitted along with the `checkboxOnChange` event.
+
+```js
+{ checked: true, id: "checkbox-1", value: "checkbox-option-1" }
+```
+
+See the [Events](#events) table to learn more about the available custom events from the component and what the type of `CustomEvent.detail` will be.
+
+### Native `change` events
+
+The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.
+
+The native `change` event hits the ShadowDOM boundary and stops propagating. The implication of this is that it can't be listened for outside the component. To attempt to overcome this, a synthetic change event is generated and emitted. The original `change` event is available via the `detail` property on the emitted event.
+
+When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.
+
 ## Custom property types
 
 ### caption

package/src/components/ontario-date-input/readme.md

@@ -123,6 +123,61 @@ The `ontario-date-input` returns an [ISO 8601](https://en.wikipedia.org/wiki/ISO
 
 Remember to set the `name` attribute as this is used to identify the field when submitting the form.
 
+## Event model
+
+Each event emitted by the component uses the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) type to emit a custom event to help communicate what the component is doing. To access the data emitted by the component within the `CustomEvent` type use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property.
+
+Eg. To access the value of any change made to this component from the `inputOnInput` event, use the following code to wire up to listen for the the `inputOnInput` event.
+
+```html
+<ontario-date-input
+	element-id="date-input-example-id"
+	id="date-input-1"
+	placeholder='{
+		"day": "DD",
+		"month": "MM",
+		"year": "YYYY"
+	}'
+	min-year="999"
+	max-year="9999"
+	required="true"
+	date-options='["day", "month", "year"]'
+	hint-text="For example 2000 03 01"
+	caption='{
+		"captionText": "Exact Date",
+		"captionType": "default"
+	}'
+></ontario-date-input>
+<script>
+	// Note: this waits for the page and components to load before
+	// locating the component.
+	window.onload = () => {
+		const dateInput1 = document.getElementById('date-input-1');
+		dateInput1.addEventListener('inputOnInput', (event) => {
+			console.log('OnInput detail:', event.detail);
+		});
+	};
+</script>
+```
+
+If the number `2` is entered into the year input within `date-input-1`, the value of `event.detail` is the object emitted along with the `inputOnInput` event.
+
+```js
+{ value: "2", fieldType: "year" }
+```
+
+See the [Events](#events) table to learn more about the available custom events from the component and what the type of `CustomEvent.detail` will be.
+
+### Native `input` and `change` events
+
+The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.
+
+Events, such as the native `input` event, deliver data from inside of the component and flow up the event stack as expected.
+
+This isn't the case for the native `change` event, this event hits the ShadowDOM boundary and stops propagating. The implication of this is that it can't be listened for outside the component. To attempt to overcome this, a synthetic change event is generated and emitted. The original `change` event is available via the `detail` property on the emitted event.
+
+When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.
+
 ## Custom property types
 
 ### DateValidatorReturnType

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

@@ -229,7 +229,7 @@ The `ontario-dropdown-list` supports integration with native HTML `<form>` eleme
 		},
 		{
 			"value": "ontario",
-			"label": "Ontario"
+			"label": "Ontario",
 			"selected": true
 		},
 		{
@@ -250,6 +250,57 @@ The `ontario-dropdown-list` supports integration with native HTML `<form>` eleme
 
 Remember to set the `name` attribute as this is used to identify the field when submitting the form.
 
+## Event model
+
+Each event emitted by the component uses the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) type to emit a custom event to help communicate what the component is doing. To access the data emitted by the component within the `CustomEvent` type use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property.
+
+Eg. To access the value of any change made to this component from the `dropdownOnChange` event, use the following code to wire up to listen for the the `dropdownOnChange` event.
+
+```html
+<ontario-dropdown-list
+	name="dropdown-1"
+	id="dropdown-1"
+	is-empty-start-option="Select"
+	element-id="dropdown-1"
+	caption="Dropdown"
+	required
+	options='[{
+			"value": "ontario",
+			"label": "Ontario"
+		},
+		{
+			"value": "quebec",
+			"label": "Quebec"
+		}]'
+></ontario-dropdown-list>
+<script>
+	// Note: this waits for the page and components to load before
+	// locating the component.
+	window.onload = () => {
+		const dropdown1 = document.getElementById('dropdown-1');
+		dropdown1.addEventListener('dropdownOnChange', (event) => {
+			console.log('OnChange detail:', event.detail);
+		});
+	};
+</script>
+```
+
+If an option is selected from `dropdown-1`, the value of `event.detail` is the object emitted along with the `dropdownOnChange` event.
+
+```js
+{ id: "dropdown-1", value: "ontario" }
+```
+
+See the [Events](#events) table to learn more about the available custom events from the component and what the type of `CustomEvent.detail` will be.
+
+### Native `change` events
+
+The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.
+
+The native `change` event hits the ShadowDOM boundary and stops propagating. The implication of this is that it can't be listened for outside the component. To attempt to overcome this, a synthetic change event is generated and emitted. The original `change` event is available via the `detail` property on the emitted event.
+
+When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.
+
 ## Custom property types
 
 ### Caption

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

@@ -464,15 +464,15 @@ export class OntarioHeader {
 		}
 
 		if (viewportSize === 'mobile') {
-			return maxSubheaderMobileLinks && numOfMenuItems - maxSubheaderMobileLinks > 0;
+			return numOfMenuItems - (maxSubheaderMobileLinks ?? 0) > 0;
 		}
 
 		if (viewportSize === 'tablet') {
-			return maxSubheaderTabletLinks && numOfMenuItems - maxSubheaderTabletLinks > 0;
+			return numOfMenuItems - (maxSubheaderTabletLinks ?? 0) > 0;
 		}
 
 		if (viewportSize === 'desktop') {
-			return maxSubheaderDesktopLinks && numOfMenuItems - maxSubheaderDesktopLinks > 0;
+			return numOfMenuItems - (maxSubheaderDesktopLinks ?? 0) > 0;
 		}
 
 		return true;
@@ -680,7 +680,7 @@ export class OntarioHeader {
 							</div>
 						</header>
 
-						{/* Ontario application header subhearder */}
+						{/* Ontario application header subheader */}
 						<div class="ontario-application-subheader-menu__container">
 							<section
 								class={`ontario-application-subheader ${isServiceOntarioType ? 'ontario-service-subheader' : ''}`}
@@ -703,7 +703,7 @@ export class OntarioHeader {
 										)}
 										<div class="ontario-application-subheader__menu-container">
 											{/* Desktop subheader links */}
-											{this.applicationHeaderInfoState?.maxSubheaderDesktopLinks && (
+											{!!this.applicationHeaderInfoState?.maxSubheaderDesktopLinks && (
 												<ul
 													class={`${
 														isServiceOntarioType
@@ -727,7 +727,7 @@ export class OntarioHeader {
 											)}
 
 											{/* Tablet subheader links */}
-											{this.applicationHeaderInfoState?.maxSubheaderTabletLinks && (
+											{!!this.applicationHeaderInfoState?.maxSubheaderTabletLinks && (
 												<ul class="ontario-application-subheader__menu ontario-hide-for-small ontario-show-for-medium ontario-hide-for-large">
 													{this.menuItemState
 														?.slice(0, this.applicationHeaderInfoState?.maxSubheaderTabletLinks)
@@ -744,8 +744,8 @@ export class OntarioHeader {
 												</ul>
 											)}
 
-											{/* Desktop subheader links */}
-											{this.applicationHeaderInfoState?.maxSubheaderMobileLinks && (
+											{/* Mobile subheader links */}
+											{!!this.applicationHeaderInfoState?.maxSubheaderMobileLinks && (
 												<ul class="ontario-application-subheader__menu ontario-show-for-small-only">
 													{this.menuItemState
 														?.slice(0, this.applicationHeaderInfoState.maxSubheaderMobileLinks)

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

@@ -133,6 +133,12 @@ describe('ontario-header', () => {
 													<span class="ontario-header__icon-container"></span>
 													<span>Menu</span>
 												</button>
+												<button aria-controls="ontario-navigation" aria-label="Show navigation menu" class="ontario-header-button ontario-header-button--with-outline ontario-header__menu-toggler ontario-show-for-small-only" id="ontario-application-header-menu-toggler" type="button">
+                         <span class="ontario-header__icon-container"></span>
+                         <span>
+                           Menu
+                         </span>
+                       </button>
 											</div>
 										</div>
 									</div>
@@ -576,6 +582,12 @@ describe('ontario-header', () => {
 													<span class="ontario-header__icon-container"></span>
 													<span>Menu</span>
 												</button>
+												<button aria-controls="ontario-navigation" aria-label="Show navigation menu" class="ontario-header-button ontario-header-button--with-outline ontario-header__menu-toggler ontario-show-for-small-only" id="ontario-application-header-menu-toggler" type="button">
+                         <span class="ontario-header__icon-container"></span>
+                         <span>
+                           Menu
+                         </span>
+                       </button>
 											</div>
 										</div>
 									</div>

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

@@ -68,6 +68,44 @@ The `ontario-input` supports integration with native HTML `<form>` elements. Thi
 
 Remember to set the `name` attribute as this is used to identify the field when submitting the form.
 
+## Event model
+
+Each event emitted by the component uses the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) type to emit a custom event to help communicate what the component is doing. To access the data emitted by the component within the `CustomEvent` type use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property.
+
+Eg. To access the value of any input entered into this component from the `inputOnInput` event, use the following code to wire up to listen for the the `inputOnInput` event.
+
+```html
+<ontario-input id="input-1" name="input-1" caption="What is your name?" required></ontario-input>
+<script>
+	// Note: this waits for the page and components to load before
+	// locating the component.
+	window.onload = () => {
+		const input1 = document.getElementById('input-1');
+		input1.addEventListener('inputOnInput', (event) => {
+			console.log('OnInput detail:', event.detail);
+		});
+	};
+</script>
+```
+
+If the letter `i` is typed into `input-1`, the value of `event.detail` is the object emitted along with the `inputOnInput` event.
+
+```js
+{ id: "5d5d9012-3773-41c5-910b-851956b3fad7", value: "i", inputType: "insertText" }
+```
+
+See the [Events](#events) table to learn more about the available custom events from the component and what the type of `CustomEvent.detail` will be.
+
+### Native `input` and `change` events
+
+The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.
+
+Events, such as the native `input` event, deliver data from inside of the component and flow up the event stack as expected.
+
+This isn't the case for the native `change` event, this event hits the ShadowDOM boundary and stops propagating. The implication of this is that it can't be listened for outside the component. To attempt to overcome this, a synthetic change event is generated and emitted. The original `change` event is available via the `detail` property on the emitted event.
+
+When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.
+
 ## Error messaging
 
 ### Setting an error message
@@ -82,7 +120,7 @@ An error message can be displayed on an input by setting the `errorMessage` prop
 	window.onload = () => {
 		const input1 = document.getElementById('input-1');
 		input1.addEventListener('inputErrorOccurred', (event) => {
-			console.log('errorMessage:', event.details.errorMessage);
+			console.log('errorMessage:', event.detail.errorMessage);
 		});
 	};
 </script>

package/src/components/ontario-radio-buttons/readme.md

@@ -171,7 +171,6 @@ The `ontario-radio-buttons` supports integration with native HTML `<form>` eleme
 				"elementId": "radio-2",
 				"label": "Radio option 2 label"
 			},
-
 			{
 				"value": "radio-option-3",
 				"elementId": "radio-3",
@@ -188,6 +187,59 @@ The `ontario-radio-buttons` supports integration with native HTML `<form>` eleme
 
 Remember to set the `name` attribute as this is used to identify the field when submitting the form.
 
+## Event model
+
+Each event emitted by the component uses the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) type to emit a custom event to help communicate what the component is doing. To access the data emitted by the component within the `CustomEvent` type use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property.
+
+Eg. To access the value of any change made to this component from the `radioOnChange` event, use the following code to wire up to listen for the the `radioOnChange` event.
+
+```html
+<ontario-radio-buttons
+	id="radio-buttons-1"
+	name="radio-buttons-1"
+	caption="Radio buttons"
+	options='[
+		{
+			"value": "radio-option-1",
+			"elementId": "radio-1",
+			"label": "Radio option 1 label"
+		},
+		{
+			"value": "radio-option-2",
+			"elementId": "radio-2",
+			"label": "Radio option 2 label"
+		}
+	]'
+>
+</ontario-radio-buttons>
+<script>
+	// Note: this waits for the page and components to load before
+	// locating the component.
+	window.onload = () => {
+		const radioButtons1 = document.getElementById('radio-buttons-1');
+		radioButtons1.addEventListener('radioOnChange', (event) => {
+			console.log('OnChange detail:', event.detail);
+		});
+	};
+</script>
+```
+
+If the first radio button is selected within `radio-buttons-1`, the value of `event.detail` is the object emitted along with the `radioOnChange` event.
+
+```js
+{ checked: true, id: "radio-1", value: "radio-option-1" }
+```
+
+See the [Events](#events) table to learn more about the available custom events from the component and what the type of `CustomEvent.detail` will be.
+
+### Native `change` events
+
+The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.
+
+The native `change` event hits the ShadowDOM boundary and stops propagating. The implication of this is that it can't be listened for outside the component. To attempt to overcome this, a synthetic change event is generated and emitted. The original `change` event is available via the `detail` property on the emitted event.
+
+When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.
+
 ## Custom property types
 
 ### caption

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

@@ -52,6 +52,44 @@ The `ontario-textarea` supports integration with native HTML `<form>` elements.
 
 Remember to set the `name` attribute as this is used to identify the field when submitting the form.
 
+## Event model
+
+Each event emitted by the component uses the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) type to emit a custom event to help communicate what the component is doing. To access the data emitted by the component within the `CustomEvent` type use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property.
+
+Eg. To access the value of any input entered into this component from the `inputOnInput` event, use the following code to wire up to listen for the the `inputOnInput` event.
+
+```html
+<ontario-textarea id="textarea-1" name="textarea-1" caption="Text area"></ontario-textarea>
+<script>
+	// Note: this waits for the page and components to load before
+	// locating the component.
+	window.onload = () => {
+		const textarea1 = document.getElementById('textarea-1');
+		textarea1.addEventListener('inputOnInput', (event) => {
+			console.log('OnInput detail:', event.detail);
+		});
+	};
+</script>
+```
+
+If the letter `i` is typed into `textarea-1`, the value of `event.detail` is the object emitted along with the `inputOnInput` event.
+
+```js
+{ id: "910b4a52-c005-4fb6-9b6e-fd7370a00b25", value: "i", inputType: "insertText" }
+```
+
+See the [Events](#events) table to learn more about the available custom events from the component and what the type of `CustomEvent.detail` will be.
+
+### Native `input` and `change` events
+
+The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.
+
+Events, such as the native `input` event, deliver data from inside of the component and flow up the event stack as expected.
+
+This isn't the case for the native `change` event, this event hits the ShadowDOM boundary and stops propagating. The implication of this is that it can't be listened for outside the component. To attempt to overcome this, a synthetic change event is generated and emitted. The original `change` event is available via the `detail` property on the emitted event.
+
+When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.
+
 ## Custom property types
 
 ### caption