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

package/dist/types/components/ontario-card/ontario-card-types.d.ts

@@ -1,8 +1,8 @@
-export declare const CardTypes: readonly ['basic', 'image', 'title', 'horizontal'];
-export declare const HeaderTypes: readonly ['default', 'light', 'dark'];
+export declare const Layouts: readonly ['vertical', 'horizontal'];
 export declare const HorizontalImagePositionTypes: readonly ['left', 'right'];
 export declare const HorizontalImageSizeTypes: readonly ['one-fourth', 'one-third'];
-export type CardType = (typeof CardTypes)[number];
-export type HeaderType = (typeof HeaderTypes)[number];
+export type Layout = (typeof Layouts)[number];
 export type HorizontalImagePositionType = (typeof HorizontalImagePositionTypes)[number];
 export type HorizontalImageSizeType = (typeof HorizontalImageSizeTypes)[number];
+export declare const HeaderColours: string[];
+export type HeaderColour = (typeof HeaderColours)[number];

package/dist/types/components/ontario-card/ontario-card.d.ts

@@ -1,4 +1,4 @@
-import { CardType, HeaderType, HorizontalImagePositionType, HorizontalImageSizeType } from './ontario-card-types';
+import { HeaderColour, HorizontalImagePositionType, HorizontalImageSizeType, Layout } from './ontario-card-types';
 export declare class OntarioCard {
 	host: HTMLElement;
 	/**
@@ -32,18 +32,18 @@ export declare class OntarioCard {
 	 */
 	cardLink?: string;
 	/**
-	 * The type of card to render.
+	 * The layout oritnetation of the card.
 	 *
-	 * If no type is passed, it will default to 'basic'.
+	 * If no type is passed, it will default to 'vertical'.
 	 *
 	 */
-	cardType: CardType;
+	layout?: Layout;
 	/**
-	 * The type of header to render.
+	 * Set the card's header colour.
 	 *
-	 * If no type is passed, it will default to 'default'.
+	 * This is optional.
 	 */
-	headerType: HeaderType;
+	headerColour?: HeaderColour;
 	/**
 	 * The position of the image when the card-type is set to 'horizontal'.
 	 *
@@ -87,43 +87,54 @@ export declare class OntarioCard {
 	ariaLabelText?: string;
 	/**
 	 * Mutable variable, for internal use only.
-	 * Set the card's type depending on validation result.
+	 * Set the card's layout depending on validation result.
 	 */
-	private cardTypeState;
+	private layoutState;
 	/**
-	 * Mutable variable, for internal use only.
-	 * Set the card's header type depending on validation result.
+	 * Watch for changes to the `layout` property for validation purposes.
+	 *
+	 * 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.
 	 */
-	private headerTypeState;
+	validateLayout(): void;
 	/**
-	 * Watch for changes to the `cardType` property for validation purposes.
+	 * Watch for changes to the `headerColour` property for validation purposes.
 	 *
-	 * If the user input doesn't match one of the array values then `cardType` will be set to its default (`basic`).
-	 * If a match is found in one of the array values then `cardType` will be set to the matching array key value.
+	 * If the user input doesn't match one of the array values then `headerColour` will be kept empty ('').
+	 * If a match is found in one of the array values then `headerColour` will be set to the matching array key value.
 	 */
-	validateCardType(): void;
+	validateHeaderColour(): void;
 	/**
-	 * Watch for changes to the `headerType` property for validation purposes.
-	 *
-	 * If the user input doesn't match one of the array values then `headerType` will be set to its default (`default`).
-	 * If a match is found in one of the array values then `headerType` will be set to the matching array key value.
+	 * Print the invalid `layout` prop warning message.
+	 */
+	private warnDefaultLayout;
+	/**
+	 * Print the invalid `headerColour` prop warning message.
 	 */
-	validateHeaderType(): void;
+	private warnDefaultHeaderColour;
 	/**
-	 * Print the invalid `cardType` prop warning message.
-	 * @returns default type (basic).
+	 * Returns the top level classes of the card.
+	 *
+	 * @returns {string}
 	 */
-	private warnDefaultCardType;
+	private getCardClasses;
 	/**
-	 * Print the invalid `headerType` prop warning message.
-	 * @returns default type (default).
+	 * Returns the heading classes of the card.
+	 *
+	 * @returns {string}
 	 */
-	private warnDefaultHeaderType;
+	private getCardHeadingClasses;
 	/**
-	 * @returns the classes of the ontario cards based off the `cardType` and `headerType`.
+	 * Returns the url that the card links to.
+	 *
+	 * @returns {string}
 	 */
-	private getClass;
 	private getHref;
+	/**
+	 * Component life cycle hook.
+	 *
+	 * https://stenciljs.com/docs/component-lifecycle#connectedcallback
+	 */
 	componentWillLoad(): void;
 	render(): any;
 }

package/dist/types/components/ontario-header/ontario-header.d.ts

@@ -153,9 +153,20 @@ export declare class OntarioHeader {
 	 */
 	handleClick(event: any): void;
 	/**
-	 * This listens for the `setAppLanguage` event sent from the test language toggler when it is is connected to the DOM. It is used for the initial language when the input component loads.
+	 * This listens for the `setAppLanguage` event sent from the language toggle when it is is connected to the DOM.
+	 * It is used for the initial language when the input component loads.
 	 */
-	handleSetAppLanguage(event: CustomEvent<Language>): void;
+	handleSetAppLanguage(event: CustomEvent<Language> | Language): void;
+	/**
+	 * This listens for the `headerLanguageToggled` event sent from the language toggle when it is is connected to the DOM.
+	 * It is used for changing the component language after the language toggle has been activated.
+	 */
+	handleLanguageToggle(
+		event: CustomEvent<{
+			oldLanguage: Language;
+			newLanguage: Language;
+		}>,
+	): void;
 	/**
 	 * Logic to handle the menu toggling
 	 */

package/dist/types/components/ontario-language-toggle/ontario-language-toggle.d.ts

@@ -2,7 +2,14 @@ import { EventEmitter } from '../../stencil-public-runtime';
 import { Language } from '../../utils/common/language-types';
 import { HeaderLanguageToggleEventDetails } from '../../utils/events/common-events.interface';
 export declare class OntarioLanguageToggle {
-	language: Language | string;
+	/**
+	 * The language of the component.
+	 *
+	 * In most cases, the language toggle should be the source of truth for determining the site language.
+	 *
+	 * Only pass a language value here if necessary.
+	 */
+	language?: Language;
 	/**
 	 * The size of the language toggle button.
 	 *
@@ -23,17 +30,77 @@ export declare class OntarioLanguageToggle {
 	customLanguageToggle?: (event: globalThis.Event) => void;
 	translations: any;
 	/**
-	 * An event to set the Document's HTML lang property, and emit the toggled language to other components.
+	 * Internal state used as the source of truth for component language.
 	 */
-	setAppLanguage: EventEmitter<string>;
-	setAppLanguageHandler(): void;
+	private languageState;
 	/**
-	 * An event that emits to other components that the language toggle button has been toggled.
+	 * Internal state used to render the text on the language toggle UI.
+	 */
+	private oppositeLanguageLabel;
+	/**
+	 * Updates the language and languageState props when changes to the language prop are detected.
 	 */
-	headerLanguageToggled: EventEmitter<HeaderLanguageToggleEventDetails>;
-	handleHeaderLanguageToggled(language: string, event?: globalThis.Event): void;
 	updateLanguage(): void;
-	updateHTMLLang: (lang: string) => void;
+	/**
+	 * Event that fires during the setAppLanguageHandler() method.
+	 *
+	 * The event contains the current language (after language logic has already occurred).
+	 */
+	setAppLanguage: EventEmitter<Language>;
+	/**
+	 * Event that fires when the language toggle is pressed/clicked.
+	 *
+	 * The event contains the oldLanguage along with the newLanguage.
+	 */
+	headerLanguageToggled: EventEmitter<HeaderLanguageToggleEventDetails>;
+	/**
+	 * This function sets the languageState (if not already set).
+	 *
+	 * It also emits the setAppLanguage() event, updates the component language label, and
+	 * updates the <html> tag lang attribute with the languageState value.
+	 *
+	 * It gets called by the connectedCallback() component lifecycle hook, and by the
+	 * updateLanguage() method, which is fired on the watch for the language prop.
+	 */
+	private setAppLanguageHandler;
+	/**
+	 * An event that emits to other components that the language toggle button has been toggled.
+	 *
+	 * @param {Language} oldLanguage - The language prior to the language toggle being pressed.
+	 * @param {globalThis.Event} event - event that triggered the function (e.g. onclick).
+	 */
+	private handleHeaderLanguageToggled;
+	/**
+	 * Prints a warning message to the console about using an incorrect language for the component.
+	 *
+	 * @param {string} lang - The incorrect language that was received.
+	 * @param {string} type - prop/document | Where the incorrect language is coming from.
+	 */
+	private showLanguageWarning;
+	/**
+	 * Returns abbreviated text for the opposite language.
+	 *
+	 * @returns {Language}
+	 */
+	private getOppositeLanguageAbbrievation;
+	/**
+	 * Returns full word text for the opposite language.
+	 *
+	 * @returns {string}
+	 */
+	private getOppositeLanguageFullWord;
+	private updateHTMLLang;
+	/**
+	 * Component life cycle hook.
+	 *
+	 * https://stenciljs.com/docs/component-lifecycle#connectedcallback
+	 */
 	connectedCallback(): void;
+	/**
+	 * Component life cycle hook.
+	 *
+	 * https://stenciljs.com/docs/component-lifecycle#componentdidload
+	 */
+	componentDidLoad(): void;
 	render(): any;
 }

package/dist/types/components/ontario-search-box/ontario-search-box.d.ts

@@ -0,0 +1,180 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import { Language } from '../../utils/common/language-types';
+import { Hint } from '../../utils/common/common.interface';
+import {
+	InputFocusBlurEvent,
+	InputInteractionEvent,
+	InputInputEvent,
+} from '../../utils/events/event-handler.interface';
+import { Caption } from '../../utils/common/input-caption/caption.interface';
+export declare class OntarioSearchBox {
+	element: HTMLElement;
+	internals: ElementInternals;
+	/**
+	 * This Ref is used get a direct reference to the hint text element
+	 */
+	private hintTextRef?;
+	/**
+	 * This Ref is used get a direct reference to the search input element
+	 */
+	private inputFieldRef?;
+	/**
+	 * The language of the component.
+	 * This is used for translations. If none is passed, it will default to English.
+	 */
+	language?: Language;
+	/**
+	 * The unique identifier of the search-box component. This is optional - if no ID is passed, one will be generated.
+	 */
+	elementId?: string;
+	/**
+	 * The value of the search term.
+	 * This is optional.
+	 */
+	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>
+    */
+	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).
+	 */
+	required?: boolean;
+	/**
+	 * 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>
+	 */
+	performSearch?: (value?: string) => Promise<void>;
+	/**
+	 * Used to include the ontario-hint-text component for the search-box.
+	 * This is optional.
+	 */
+	hintText?: string | Hint;
+	/**
+	 * Used to add a custom function to the input onInput event.
+	 */
+	customOnInput?: (event: globalThis.Event) => void;
+	/**
+	 * Used to add a custom function to the input onChange event.
+	 */
+	customOnChange?: (event: globalThis.Event) => void;
+	/**
+	 * Used to add a custom function to the input onBlur event.
+	 */
+	customOnBlur?: (event: globalThis.Event) => void;
+	/**
+	 * Used to add a custom function to the input onFocus event.
+	 */
+	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>
+	 */
+	searchOnSubmit: EventEmitter<string>;
+	/**
+	 * Emitted when a input  occurs when an input has been changed.
+	 */
+	inputOnInput: EventEmitter<InputInputEvent>;
+	/**
+	 * Emitted when a keyboard input or mouse event occurs when an input has been changed.
+	 */
+	inputOnChange: EventEmitter<InputInteractionEvent>;
+	/**
+	 * Emitted when a keyboard input event occurs when an input has lost focus.
+	 */
+	inputOnBlur: EventEmitter<InputFocusBlurEvent>;
+	/**
+	 * Emitted when a keyboard input event occurs when an input has gained focus.
+	 */
+	inputOnFocus: EventEmitter<InputFocusBlurEvent>;
+	/**
+	 * The hint text options are re-assigned to the internalHintText array.
+	 */
+	private internalHintText;
+	/**
+	 * Instantiate an InputCaption object for internal logic use
+	 */
+	private captionState;
+	/**
+	 * Used for the `aria-describedby` value of the dropdown list. This will match with the id of the hint text.
+	 */
+	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.
+	 */
+	private parseHintText;
+	/**
+	 * 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
+	 */
+	private updateCaptionState;
+	/**
+	 * Watch for changes to the `language` prop to render either the English or French translations
+	 */
+	updateLanguage(): void;
+	/**
+	 * 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.
+	 */
+	componentDidLoad(): Promise<void>;
+	componentWillLoad(): void;
+	/**
+	 * Function to handle input events and the information pertaining to the input to emit.
+	 */
+	private handleEvent;
+	/**
+	 * handleSearch function is called when the search submit button is clicked
+	 */
+	handleSearch(event: MouseEvent): Promise<void>;
+	getId(): string;
+	private getValue;
+	/**
+	 *This function ensures that the focus returns to the search input field when the reset button is clicked.
+	 */
+	private setFocus;
+	/**
+	 * when the reset button is clicked this function gets called
+	 */
+	handleFocus: () => void;
+	render(): any;
+}