@ongov/ontario-design-system-component-library 4.3.1-alpha.1 → 5.0.0-alpha.3

package/src/components/ontario-search-box/ontario-search-box.tsx

@@ -0,0 +1,341 @@
+import { Component, Prop, h, Element, EventEmitter, Event, AttachInternals, State, Watch } from '@stencil/core';
+import { Input } from '../../utils/common/input/input';
+import { Language } from '../../utils/common/language-types';
+import OntarioIconSearch from '../ontario-icon/assets/ontario-icon-search.svg';
+import { Hint } from '../../utils/common/common.interface';
+import { handleInputEvent } from '../../utils/events/event-handler';
+import {
+	InputFocusBlurEvent,
+	EventType,
+	InputInteractionEvent,
+	InputInputEvent,
+} from '../../utils/events/event-handler.interface';
+import { Caption } from '../../utils/common/input-caption/caption.interface';
+import { InputCaption } from '../../utils/common/input-caption/input-caption';
+import { default as translations } from '../../translations/global.i18n.json';
+import { constructHintTextObject } from '../../utils/components/hints/hints';
+
+@Component({
+	tag: 'ontario-search-box',
+	styleUrl: 'ontario-search-box.scss',
+	shadow: true,
+})
+export class OntarioSearchBox {
+	@Element() element: HTMLElement;
+	@AttachInternals() internals: ElementInternals;
+
+	/**
+	 * This Ref is used get a direct reference to the hint text element
+	 */
+	private hintTextRef?: HTMLOntarioHintTextElement;
+
+	/**
+	 * This Ref is used get a direct reference to the search input element
+	 */
+	private inputFieldRef?: HTMLInputElement;
+
+	/**
+	 * The language of the component.
+	 * This is used for translations. If none is passed, it will default to English.
+	 */
+	@Prop({ mutable: true }) language?: Language = 'en';
+
+	/**
+	 * The unique identifier of the search-box component. This is optional - if no ID is passed, one will be generated.
+	 */
+	@Prop({ mutable: true }) elementId?: string;
+
+	/**
+	 * The value of the search term.
+	 * This is optional.
+	 */
+	@Prop({ mutable: true }) value?: string;
+
+	/**
+	* The text to display as the input label
+	*
+	* @example
+	* <ontario-search-box
+	*      caption='{
+					"captionText": "Search directory",
+					"captionType": "default"
+					}'
+				required = "true"
+	>
+	</ontario-search-box>
+	*/
+	@Prop() caption: Caption | string;
+
+	/**
+	 * This is used to determine whether the dropdown list is required or not.
+	 * This prop 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).
+	 */
+	@Prop() required?: boolean = false;
+
+	/**
+	 * This Function to perform a search operation.
+	 * This function will be called when the search submit button is triggered.
+	 * The value argument is used for as search term to use for the search operation. This parameter is optional.
+	 * The performSearch prop can be set dynamically using JavaScript, allowing you to define custom search functionality when the search form is submitted.
+	 *
+	 * @example
+	 * <ontario-search-box
+	 *	  id="ontario-search-box"
+	 *	  caption='Search directory'
+	 * ></ontario-search-box>
+	 *
+	 * <script>
+	 *	window.addEventListener('load', () => {
+	 *		const searchBox = document.getElementById('ontario-search-box');
+	 *		searchBox.performSearch = async (value) => {
+	 * 			console.log('Performing search with value:', value);
+	 *		};
+	 *	});
+	 * </script>
+	 */
+	@Prop() performSearch?: (value?: string) => Promise<void>;
+
+	/**
+	 * Used to include the ontario-hint-text component for the search-box.
+	 * This is optional.
+	 */
+	@Prop() hintText?: string | Hint;
+
+	/**
+	 * Used to add a custom function to the input onInput event.
+	 */
+	@Prop() customOnInput?: (event: globalThis.Event) => void;
+
+	/**
+	 * Used to add a custom function to the input onChange event.
+	 */
+	@Prop() customOnChange?: (event: globalThis.Event) => void;
+
+	/**
+	 * Used to add a custom function to the input onBlur event.
+	 */
+	@Prop() customOnBlur?: (event: globalThis.Event) => void;
+
+	/**
+	 * Used to add a custom function to the input onFocus event.
+	 */
+	@Prop() customOnFocus?: (event: globalThis.Event) => void;
+
+	/**
+	 * Emitted when the search is submitted.
+	 * Below is an example on how to hook into the event to get the event details.
+	 *
+	 * @example
+	 *	<script>
+	 *		document.getElementById('ontario-search-box').addEventListener('searchOnSubmit', (event) => {
+	 *	 		const searchValue = event.detail;
+	 *			console.log('Search submitted with value:', searchValue);
+	 *	  };
+	 * 	</script>
+	 */
+	@Event() searchOnSubmit: EventEmitter<string>;
+
+	/**
+	 * Emitted when a input  occurs when an input has been changed.
+	 */
+	@Event() inputOnInput: EventEmitter<InputInputEvent>;
+
+	/**
+	 * Emitted when a keyboard input or mouse event occurs when an input has been changed.
+	 */
+	@Event() inputOnChange: EventEmitter<InputInteractionEvent>;
+
+	/**
+	 * Emitted when a keyboard input event occurs when an input has lost focus.
+	 */
+	@Event() inputOnBlur: EventEmitter<InputFocusBlurEvent>;
+
+	/**
+	 * Emitted when a keyboard input event occurs when an input has gained focus.
+	 */
+	@Event() inputOnFocus: EventEmitter<InputFocusBlurEvent>;
+
+	/**
+	 * The hint text options are re-assigned to the internalHintText array.
+	 */
+	@State() private internalHintText: Hint;
+
+	/**
+	 * Instantiate an InputCaption object for internal logic use
+	 */
+	@State() private captionState: InputCaption;
+
+	/**
+	 * Used for the `aria-describedby` value of the dropdown list. This will match with the id of the hint text.
+	 */
+	@State() hintTextId: string | null | undefined;
+
+	/**
+	 * Watch for changes to the `hintText` prop.
+	 *
+	 * If a `hintText` prop is passed, the `constructHintTextObject` function will convert it to the correct format, and set the result to the `internalHintText` state.
+	 */
+	@Watch('hintText')
+	private parseHintText() {
+		if (this.hintText) {
+			const hintTextObject = constructHintTextObject(this.hintText);
+			this.internalHintText = hintTextObject;
+		}
+	}
+
+	/**
+	 * Watch for changes to the `caption` prop.
+	 *
+	 * The caption will be run through the InputCaption constructor to convert it to the correct format, and set the result to the `captionState` state.
+	 * @param newValue: Caption | string
+	 */
+	@Watch('caption')
+	private updateCaptionState(newValue: Caption | string) {
+		this.captionState = new InputCaption(
+			this.element.tagName,
+			newValue,
+			translations,
+			this.language,
+			false,
+			this.required,
+		);
+	}
+
+	/**
+	 * Watch for changes to the `language` prop to render either the English or French translations
+	 */
+	@Watch('language')
+	updateLanguage() {
+		this.updateCaptionState(this.caption);
+	}
+
+	/**
+	 * If a `hintText` prop is passed, the id generated from it will be set to the internal `hintTextId` state to match with the select `aria-describedBy` attribute.
+	 */
+	async componentDidLoad() {
+		this.hintTextId = await this.hintTextRef?.getHintTextId();
+	}
+
+	componentWillLoad() {
+		this.elementId = this.elementId;
+		this.parseHintText();
+		this.updateCaptionState(this.caption);
+	}
+
+	/**
+	 * Function to handle input events and the information pertaining to the input to emit.
+	 */
+	private handleEvent(event: globalThis.Event, eventType: EventType) {
+		const input = event.target as HTMLInputElement | null;
+
+		// Update the component value to match the value of the input element.
+		this.value = input?.value;
+
+		this.internals?.setFormValue?.(this.value ?? '');
+
+		handleInputEvent(
+			event,
+			eventType,
+			input,
+			this.inputOnChange,
+			this.inputOnFocus,
+			this.inputOnBlur,
+			this.inputOnInput,
+			'input',
+			this.customOnChange,
+			this.customOnFocus,
+			this.customOnBlur,
+			this.customOnInput,
+			this.element,
+		);
+	}
+
+	/**
+	 * handleSearch function is called when the search submit button is clicked
+	 */
+	async handleSearch(event: MouseEvent) {
+		event.preventDefault();
+		this.searchOnSubmit.emit(this.value);
+		this.performSearch && (await this.performSearch(this.value));
+	}
+
+	public getId(): string {
+		return this.elementId ?? '';
+	}
+
+	private getValue(): string | number {
+		return this.value ?? '';
+	}
+
+	/**
+	 *This function ensures that the focus returns to the search input field when the reset button is clicked.
+	 */
+	private setFocus(inputRef?: HTMLInputElement) {
+		if (inputRef) {
+			inputRef.focus();
+		}
+	}
+
+	/**
+	 * when the reset button is clicked this function gets called
+	 */
+	handleFocus = () => {
+		this.setFocus(this.inputFieldRef);
+	};
+
+	render() {
+		const searchInputFieldId: string = 'ontario-search-input-field';
+		return (
+			<form
+				name="searchForm"
+				id="ontario-search-form-container"
+				class="ontario-search__container ontario-columns ontario-small-10 ontario-medium-offset-3 ontario-medium-6 ontario-large-offset-0 ontario-large-6"
+				novalidate
+			>
+				{this.captionState.getCaption(searchInputFieldId, false, true) /* Note the _required_ text is disabled */}
+				{this.internalHintText && (
+					<ontario-hint-text
+						hint={this.internalHintText.hint}
+						hintContentType={this.internalHintText.hintContentType}
+						ref={(el) => (this.hintTextRef = el)}
+					></ontario-hint-text>
+				)}
+
+				<div class="ontario-search__input-container">
+					<Input
+						aria-describedBy={this.hintTextId}
+						type="search"
+						name="search"
+						id={searchInputFieldId}
+						autoComplete="off"
+						aria-autocomplete="none"
+						className="ontario-search__input ontario-input"
+						required={true}
+						ref={(el) => (this.inputFieldRef = el)}
+						onInput={(e) => this.handleEvent(e, EventType.Input)}
+						onChange={(e) => this.handleEvent(e, EventType.Change)}
+						onBlur={(e) => this.handleEvent(e, EventType.Blur)}
+						onFocus={(e) => this.handleEvent(e, EventType.Focus)}
+						value={this.getValue()}
+					></Input>
+					<Input
+						className="ontario-search__reset"
+						id="ontario-search-reset"
+						type="reset"
+						value=""
+						onClick={() => this.handleFocus()}
+					></Input>
+					<button
+						class="ontario-search__submit"
+						type="submit"
+						id="ontario-search-box__submit"
+						onClick={(e) => this.handleSearch(e)}
+					>
+						<span innerHTML={OntarioIconSearch} />
+					</button>
+				</div>
+			</form>
+		);
+	}
+}

package/src/components/ontario-search-box/readme.md

@@ -0,0 +1,132 @@
+import { OntarioSearchBox } from '@ongov/ontario-design-system-component-library-react';
+
+# ontario-search-box
+
+Use a search box to let users complete keyword-based searches.
+
+## User guidance
+
+Please refer to the [Ontario Design System](https://designsystem.ontario.ca/components/detail/search-box.html) for current documentation guidance.
+
+## Configuration
+
+Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the search box 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.
+
+## Example
+
+### Search box with caption
+
+```html
+<ontario-search-box id="ontario-search-box" caption="Search the directory"></ontario-search-box>
+```
+
+<div>
+    <OntarioSearchBox id="ontario-search-box" caption="Search the directory"></OntarioSearchBox>
+</div>
+
+### Handling searching
+
+The `<ontario-search-box>` provides two ways to handle searching.
+
+#### The `performSearch()` function
+
+The `performSearch()` function allows for custom logic to be executed when the search box is submitted for searching. When the search box calls this function internally it will pass to it a string that is the value of the search field. This function is [asynchronous](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) and should return a [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+
+##### Example
+
+The following example registers a simple function on `window` `load` that assigns a custom function to the search box's `performSearch()` function to handle the application specific search logic.
+
+```html
+<script>
+	window.addEventListener('load', () => {
+		console.log('Loaded Search Box Event Listener');
+
+		const searchBox = document.getElementById('ontario-search-box');
+		searchBox.performSearch = async (value) => {
+			console.log('Performing search with value:', value);
+		};
+	});
+</script>
+```
+
+#### Using the `searchOnSubmit` function
+
+As an alternative to using a custom `performSearch()` function the search box also emits an event, `searchOnSubmit` that can be listened to to trigger any custom search logic that is needed. This allows for applications to listen for a search being performed and act accordingly. The value of the search box will be passed via the [`CustomEvent` `detail`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#detail) property.
+
+##### Example
+
+The following example registers a simple function on `window` `load` that adds an event listener to the search box listening for the `searchOnSubmit` event and outputs the value of the `detail` property.
+
+```html
+<script>
+	window.addEventListener('load', () => {
+		console.log('Loaded Search Box Event Listener');
+
+		const searchBox = document.getElementById('ontario-search-box');
+		searchBox.addEventListener('searchOnSubmit', (event) => {
+			console.log('Search Event Detail:', event.detail);
+		});
+	});
+</script>
+```
+
+## Custom property types
+
+### caption
+
+The `caption` property is used to render the label for the ontario-input. It can be passed either a string or an object. If no `captionType` needs to be specified, it can be passed as a string.
+
+```html
+caption='{ "captionText": "Input label", "captionType": "large" }'
+```
+
+| Property name | Type                               | Description                                                                                                                                      |
+| ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `captionText` | `string`                           | Text to display as the input question                                                                                                            |
+| `captionType` | `"default" \| "large"\| "heading"` | The type of label to display for the input question. This is optional, and if no information is provided, it will default to the `default` type. |
+
+<!-- Auto Generated Below -->
+
+## Properties
+
+| Property         | Attribute    | Description                                                                                                                                                                                                                                                                                                                                                                            | Type                                                            | Default     |
+| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------- |
+| `caption`        | `caption`    | The text to display as the input label                                                                                                                                                                                                                                                                                                                                                 | `Caption \| string`                                             | `undefined` |
+| `customOnBlur`   | --           | Used to add a custom function to the input onBlur event.                                                                                                                                                                                                                                                                                                                               | `((event: Event) => void) \| undefined`                         | `undefined` |
+| `customOnChange` | --           | Used to add a custom function to the input onChange event.                                                                                                                                                                                                                                                                                                                             | `((event: Event) => void) \| undefined`                         | `undefined` |
+| `customOnFocus`  | --           | Used to add a custom function to the input onFocus event.                                                                                                                                                                                                                                                                                                                              | `((event: Event) => void) \| undefined`                         | `undefined` |
+| `customOnInput`  | --           | Used to add a custom function to the input onInput event.                                                                                                                                                                                                                                                                                                                              | `((event: Event) => void) \| undefined`                         | `undefined` |
+| `elementId`      | `element-id` | The unique identifier of the search-box component. This is optional - if no ID is passed, one will be generated.                                                                                                                                                                                                                                                                       | `string \| undefined`                                           | `undefined` |
+| `hintText`       | `hint-text`  | Used to include the ontario-hint-text component for the search-box. This is optional.                                                                                                                                                                                                                                                                                                  | `Hint \| string \| undefined`                                   | `undefined` |
+| `language`       | `language`   | The language of the component. This is used for translations. If none is passed, it will default to English.                                                                                                                                                                                                                                                                           | `"en" \| "fr" \| undefined`                                     | `'en'`      |
+| `performSearch`  | --           | This Function to perform a search operation. This function will be called when the search submit button is triggered. The value argument is used for as search term to use for the search operation. This parameter is optional. The performSearch prop can be set dynamically using JavaScript, allowing you to define custom search functionality when the search form is submitted. | `((value?: string \| undefined) => Promise<void>) \| undefined` | `undefined` |
+| `required`       | `required`   | This is used to determine whether the dropdown list is required or not. This prop 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 value of the search term. This is optional.                                                                                                                                                                                                                                                                                                                                        | `string \| undefined`                                           | `undefined` |
+
+## Events
+
+| Event            | Description                                                                                                       | Type                                                                        |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `inputOnBlur`    | Emitted when a keyboard input event occurs when an input has lost focus.                                          | `CustomEvent<InputInteractionEvent & { focused: boolean; }>`                |
+| `inputOnChange`  | Emitted when a keyboard input or mouse event occurs when an input has been changed.                               | `CustomEvent<{ id?: string \| undefined; value?: string \| undefined; }>`   |
+| `inputOnFocus`   | Emitted when a keyboard input event occurs when an input has gained focus.                                        | `CustomEvent<InputInteractionEvent & { focused: boolean; }>`                |
+| `inputOnInput`   | Emitted when a input  occurs when an input has been changed.                                                      | `CustomEvent<InputInteractionEvent & { inputType?: string \| undefined; }>` |
+| `searchOnSubmit` | Emitted when the search is submitted. Below is an example on how to hook into the event to get the event details. | `CustomEvent<string>`                                                       |
+
+## Dependencies
+
+### Depends on
+
+- [ontario-hint-text](../ontario-hint-text)
+
+### Graph
+
+```mermaid
+graph TD;
+  ontario-search-box --> ontario-hint-text
+  style ontario-search-box fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+---
+
+_Built with [StencilJS](https://stenciljs.com/)_

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

@@ -0,0 +1,35 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`ontario-search-box should render a default search box element 1`] = `
+<ontario-search-box>
+  <mock:shadow-root>
+    <form class="ontario-columns ontario-large-6 ontario-large-offset-0 ontario-medium-6 ontario-medium-offset-3 ontario-search__container ontario-small-10" id="ontario-search-form-container" name="searchForm" novalidate="">
+      <label class="ontario-label" htmlfor="ontario-search-input-field"></label>
+      <div class="ontario-search__input-container">
+        <input aria-autocomplete="none" autocomplete="off" class="ontario-input ontario-search__input" id="ontario-search-input-field" name="search" required="" type="search" value="">
+        <input class="ontario-search__reset" id="ontario-search-reset" type="reset" value="">
+        <button class="ontario-search__submit" id="ontario-search-box__submit" type="submit">
+          <span></span>
+        </button>
+      </div>
+    </form>
+  </mock:shadow-root>
+</ontario-search-box>
+`;
+
+exports[`ontario-search-box should render the expected html 1`] = `
+<ontario-search-box class="hydrated" id="ontario-search-box">
+  <mock:shadow-root>
+    <form class="ontario-columns ontario-large-6 ontario-large-offset-0 ontario-medium-6 ontario-medium-offset-3 ontario-search__container ontario-small-10" id="ontario-search-form-container" name="searchForm" novalidate="">
+      <label class="ontario-label" htmlfor="ontario-search-input-field"></label>
+      <div class="ontario-search__input-container">
+        <input aria-autocomplete="none" autocomplete="off" class="ontario-input ontario-search__input" id="ontario-search-input-field" name="search" required="" type="search" value="">
+        <input class="ontario-search__reset" id="ontario-search-reset" type="reset" value="">
+        <button class="ontario-search__submit" id="ontario-search-box__submit" type="submit">
+          <span></span>
+        </button>
+      </div>
+    </form>
+  </mock:shadow-root>
+</ontario-search-box>
+`;

package/src/components/ontario-search-box/test/ontario-search-box.e2e.ts

@@ -0,0 +1,21 @@
+import { newE2EPage } from '@stencil/core/testing';
+
+describe('ontario-search-box', () => {
+	//checks if the component has hydrated class
+	it('renders', async () => {
+		const page = await newE2EPage();
+		await page.setContent(`<ontario-search-box></ontario-search-box>`);
+		const element = await page.find('ontario-search-box');
+		expect(element).toHaveClass('hydrated');
+	});
+
+	it('checks the onclick event', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-search-box></ontario-search-box>');
+		const changedEvent = await page.spyOnEvent('click');
+		const component = await page.find('ontario-search-box >>> #ontario-search-submit');
+		component.click();
+		await page.waitForChanges();
+		expect(changedEvent).toHaveReceivedEventTimes(1);
+	});
+});

package/src/components/ontario-search-box/test/ontario-search-box.spec.tsx

@@ -0,0 +1,22 @@
+import { newSpecPage } from '@stencil/core/testing';
+import { OntarioSearchBox } from '../ontario-search-box';
+
+describe('ontario-search-box', () => {
+	it('should render the expected html', async () => {
+		const page = await newSpecPage({
+			components: [OntarioSearchBox],
+			html: `<ontario-search-box id="ontario-search-box" class="hydrated"></ontario-search-box>`,
+		});
+
+		expect(page.root).toMatchSnapshot();
+	});
+
+	it('should render a default search box element', async () => {
+		const page = await newSpecPage({
+			components: [OntarioSearchBox],
+			html: `<ontario-search-box></ontario-search-box>`,
+		});
+
+		expect(page.root).toMatchSnapshot();
+	});
+});