@oscarpalmer/oui 0.33.0 → 0.34.0

package/src/js/combobox/i18n.combobox.ts

@@ -0,0 +1,179 @@
+import type {GenericCallback} from '@oscarpalmer/atoms/models';
+import {
+	updateComboboxAnchor,
+	updateComboboxMessage,
+	updateComboboxSelectionItems,
+} from './dom.combobox';
+import {getComboboxVisibleOptions} from './misc.combobox';
+import type {OuiComboboxLocalizations, OuiComboboxState} from './models.combobox';
+import {comboboxStates} from './state.combobox';
+
+// #region Functions
+
+export function getComboboxLanguage(state: OuiComboboxState): string {
+	return (
+		state.host.closest('[lang]')?.getAttribute('lang') ?? document.documentElement.lang
+	).toLowerCase();
+}
+
+export function getComboboxLocalization<Key extends keyof OuiComboboxLocalizations>(
+	key: Key,
+	state: OuiComboboxState,
+): OuiComboboxLocalizations[Key] {
+	const language = getComboboxLanguage(state);
+
+	const allLocalizations = [state.localizations, LOCALIZATIONS.globals];
+	const {length} = allLocalizations;
+
+	let localization: OuiComboboxLocalizations[Key] | undefined;
+	let shortLanguage: string | undefined;
+
+	for (let index = 0; index < length; index += 1) {
+		const localizations = allLocalizations[index];
+
+		localization = localizations?.[language]?.[key];
+
+		if (localization != null) {
+			break;
+		}
+
+		shortLanguage ??= language.split('-')[0];
+
+		if (shortLanguage === language) {
+			continue;
+		}
+
+		localization = localizations?.[shortLanguage]?.[key];
+
+		if (localization != null) {
+			break;
+		}
+	}
+
+	return localization ?? LOCALIZATIONS.defaults[key];
+}
+
+/**
+ * Set combobox localizations for a specific language
+ *
+ * @param language Language code
+ * @param localizations Localizations for language
+ */
+export function setComboboxLocalizations(
+	language: string,
+	localizations: Partial<OuiComboboxLocalizations>,
+): void;
+
+/**
+ * Set combobox localizations for one or more languages
+ *
+ * @param localizations Localizations for one or more languages
+ */
+export function setComboboxLocalizations(
+	localizations: Record<string, Partial<OuiComboboxLocalizations>>,
+): void;
+
+export function setComboboxLocalizations(
+	first: string | Record<string, Partial<OuiComboboxLocalizations>>,
+	second?: Partial<OuiComboboxLocalizations>,
+): void {
+	updateComboboxLocalizations(
+		typeof first === 'string'
+			? {
+					[first]: second!,
+				}
+			: first,
+	);
+}
+
+export function updateComboboxLocalizations(
+	values: Record<string, Partial<Record<string, string | GenericCallback>>>,
+	destination?: Record<string, Partial<OuiComboboxLocalizations>>,
+): void {
+	if (typeof values !== 'object' || values == null) {
+		return;
+	}
+
+	const localizations = destination ?? LOCALIZATIONS.globals;
+
+	const languages = Object.keys(values);
+	const languagesLength = languages.length;
+
+	let updated = false;
+
+	for (let languagesIndex = 0; languagesIndex < languagesLength; languagesIndex += 1) {
+		const language = languages[languagesIndex];
+		const languageValue = values[language];
+
+		if (typeof languageValue !== 'object' || languageValue == null) {
+			continue;
+		}
+
+		const normalizedLanguage = language.toLowerCase();
+
+		localizations[normalizedLanguage] ??= {};
+
+		const keys = Object.keys(languageValue);
+		const keysLength = keys.length;
+
+		for (let keysIndex = 0; keysIndex < keysLength; keysIndex += 1) {
+			const key = keys[keysIndex];
+			const keyValue = languageValue[key];
+
+			const normalizedKey = key.toLowerCase() as keyof OuiComboboxLocalizations;
+
+			if (
+				LOCALIZATIONS.keys.has(normalizedKey) &&
+				(typeof keyValue === 'string' || typeof keyValue === 'function')
+			) {
+				updated = true;
+
+				localizations[normalizedLanguage][normalizedKey] = keyValue as never;
+			}
+		}
+	}
+
+	if (!updated) {
+		return;
+	}
+
+	for (const state of comboboxStates.set) {
+		updateComboboxAnchor(state);
+		updateComboboxMessage(state, getComboboxVisibleOptions(state).length);
+		updateComboboxSelectionItems(state);
+	}
+}
+
+// #endregion
+
+// #region Variables
+
+const LOCALIZATIONS: {
+	defaults: OuiComboboxLocalizations;
+	globals: Record<string, Partial<OuiComboboxLocalizations>>;
+	keys: Set<keyof OuiComboboxLocalizations>;
+} = {
+	defaults: {
+		empty: 'No results found',
+		input: 'Please enter a value',
+		invalid: 'Please select an option from the list',
+		max: max => `Please select fewer options (maximum is ${max})`,
+		min: min => `Please select more options (minimum is ${min})`,
+		remove: label => `Remove ${label}`,
+		results: amount => `${amount} results available`,
+		selected: amount => `${amount} selected`,
+	},
+	globals: {},
+	keys: new Set<keyof OuiComboboxLocalizations>([
+		'empty',
+		'input',
+		'invalid',
+		'max',
+		'min',
+		'remove',
+		'results',
+		'selected',
+	]),
+};
+
+// #endregion

package/src/js/combobox/index.ts

@@ -0,0 +1,307 @@
+import {parse} from '@oscarpalmer/atoms/string';
+import {getAttribute} from '@oscarpalmer/toretto/attribute';
+import {COMBOBOX_TAGNAME} from './constants.combobox';
+import {setComboboxValue, setComboboxValues} from './data.combobox';
+import {setComboboxDisabled, setComboboxReadonly, setComboboxRequired} from './dom.combobox';
+import {updateComboboxLocalizations} from './i18n.combobox';
+import {setComboboxFilter, setComboboxLimit} from './misc.combobox';
+import type {OuiComboboxLocalizations, OuiComboboxState, OuiComboboxType} from './models.combobox';
+import {attachCombobox, createComboboxState, detachCombobox} from './state.combobox';
+
+// #region Types
+
+declare global {
+	interface HTMLElementTagNameMap {
+		[COMBOBOX_TAGNAME]: OuiComboboxElement;
+	}
+}
+
+export class OuiComboboxElement extends HTMLElement {
+	static formAssociated = true;
+
+	static observedAttributes = ['max', 'min', 'required', 'value'];
+
+	readonly #internals: ElementInternals;
+
+	#restored?: string[];
+
+	#state!: OuiComboboxState;
+
+	/**
+	 * Is the combobox disabled?
+	 */
+	get disabled(): boolean {
+		return this.#state?.disabled ?? false;
+	}
+
+	/**
+	 * Should the combobox be disabled?
+	 */
+	set disabled(value: boolean) {
+		if (typeof value === 'boolean' && value !== this.disabled) {
+			setComboboxDisabled(this.#state, value);
+		}
+	}
+
+	/**
+	 * Current filter value
+	 */
+	get filter(): string {
+		return this.#state.filter.element.value;
+	}
+
+	/**
+	 * Set the filter value
+	 */
+	set filter(value: string) {
+		setComboboxFilter(this.#state, value);
+	}
+
+	/**
+	 * Maximum number of selected options
+	 */
+	get max(): number | undefined {
+		return this.#state?.max;
+	}
+
+	/**
+	 * Set the maximum number of selected options
+	 */
+	set max(value: number) {
+		setComboboxLimit('max', this.#state, value);
+	}
+
+	/**
+	 * Minimum number of selected options
+	 */
+	get min(): number | undefined {
+		return this.#state?.min;
+	}
+
+	/**
+	 * Set the minimum number of selected options
+	 */
+	set min(value: number) {
+		setComboboxLimit('min', this.#state, value);
+	}
+
+	/**
+	 * Does the combobox allow multiple values?
+	 */
+	get multiple(): boolean {
+		return this.hasAttribute('multiple');
+	}
+
+	/**
+	 * Name of the combobox
+	 */
+	get name(): string {
+		return getAttribute(this, 'name') ?? '';
+	}
+
+	/**
+	 * Is the combobox readonly?
+	 */
+	get readonly(): boolean {
+		return this.#state?.readonly ?? false;
+	}
+
+	/**
+	 * Should the combobox be readonly?
+	 */
+	set readonly(value: boolean) {
+		if (typeof value === 'boolean' && value !== this.readonly) {
+			setComboboxReadonly(this.#state, value);
+		}
+	}
+
+	/**
+	 * Is the combobox required?
+	 */
+	get required(): boolean {
+		return this.#state?.required ?? false;
+	}
+
+	/**
+	 * Should the combobox be required?
+	 */
+	set required(value: boolean) {
+		if (typeof value === 'boolean' && value !== this.required) {
+			setComboboxRequired(this.#state, value);
+		}
+	}
+
+	/**
+	 * Selected options
+	 */
+	get selected(): HTMLElement[] {
+		return this.#state.options.selected.slice();
+	}
+
+	/**
+	 * Type of combobox
+	 */
+	get type(): OuiComboboxType {
+		return this.#state.type;
+	}
+
+	/**
+	 * Current value
+	 */
+	get value(): string {
+		return this.#state.values.current[0];
+	}
+
+	/**
+	 * Set the value
+	 */
+	set value(value: unknown) {
+		setComboboxValue(this.#state, value);
+	}
+
+	/**
+	 * Current values
+	 */
+	get values(): string[] {
+		return this.#state.values.current.slice();
+	}
+
+	/**
+	 * Set the values
+	 */
+	set values(value: unknown[]) {
+		setComboboxValues(this.#state, value);
+	}
+
+	constructor() {
+		super();
+
+		this.#internals = this.attachInternals();
+	}
+
+	attributeChangedCallback(name: string, _: string | null, value: string | null): void {
+		if (this.#state == null) {
+			return;
+		}
+
+		switch (name) {
+			case 'required':
+				this[name] = this.hasAttribute(name);
+				break;
+
+			case 'max':
+			case 'min':
+				setComboboxLimit(name, this.#state, value);
+				break;
+
+			case 'value':
+				this.value = value ?? '';
+				break;
+
+			default:
+				break;
+		}
+	}
+
+	/**
+	 * Clear all selected options
+	 */
+	clear(): void {
+		setComboboxValues(this.#state, []);
+	}
+
+	connectedCallback(): void {
+		if (this.#state == null) {
+			this.#initialize();
+		} else {
+			attachCombobox(this.#state);
+		}
+	}
+
+	disconnectedCallback(): void {
+		if (this.#state != null) {
+			detachCombobox(this.#state);
+		}
+	}
+
+	formDisabledCallback(disabled: boolean): void {
+		this.disabled = disabled;
+	}
+
+	formResetCallback(): void {
+		setComboboxValues(this.#state, this.#state.values.initial, false);
+	}
+
+	formStateRestoreCallback(state: string | File | FormData, reason: unknown): void {
+		if (reason !== 'restore') {
+			return;
+		}
+
+		const parsed = typeof state === 'string' ? parse(state) : undefined;
+
+		if (!Array.isArray(parsed)) {
+			return;
+		}
+
+		if (this.#state == null) {
+			this.#restored = parsed;
+		} else {
+			setComboboxValues(this.#state, parsed);
+		}
+	}
+
+	/**
+	 * Set combobox localizations for a specific language
+	 *
+	 * @param language Language code
+	 * @param localizations Localizations for language
+	 */
+	setLocalizations(language: string, localizations: Partial<OuiComboboxLocalizations>): void;
+
+	/**
+	 * Set combobox localizations for one or more languages
+	 *
+	 * @param localizations Localizations for one or more languages
+	 */
+	setLocalizations(localizations: Record<string, Partial<OuiComboboxLocalizations>>): void;
+
+	setLocalizations(
+		first: string | Record<string, Partial<OuiComboboxLocalizations>>,
+		second?: Partial<OuiComboboxLocalizations>,
+	): void {
+		updateComboboxLocalizations(
+			typeof first === 'string'
+				? {
+						[first]: second!,
+					}
+				: first,
+			this.#state.localizations,
+		);
+	}
+
+	#initialize(): void {
+		this.tabIndex = -1;
+
+		this.#state = createComboboxState(this, this.#internals);
+
+		if (this.#restored != null) {
+			setComboboxValues(this.#state, this.#restored, false);
+
+			this.#restored = undefined;
+		}
+	}
+}
+
+// #endregion
+
+// #region Initialization
+
+customElements.define(COMBOBOX_TAGNAME, OuiComboboxElement);
+
+// #endregion
+
+// #region Exports
+
+export {setComboboxLocalizations} from './i18n.combobox';
+
+// #endregion

package/src/js/combobox/misc.combobox.ts

@@ -0,0 +1,138 @@
+import {getAria} from '@oscarpalmer/toretto/aria';
+import {getAttribute, setAttribute} from '@oscarpalmer/toretto/attribute';
+import type {AnyAriaBooleanAttribute} from '@oscarpalmer/toretto/models';
+import type {OuiComboboxElement} from '.';
+import {COMBOBOX_AUTOCOMPLETES} from './constants.combobox';
+import {onComboboxFilter} from './event.combobox';
+import {updateComboboxValidity} from './form.combobox';
+import type {
+	OuiComboboxAutoComplete,
+	OuiComboboxAutoCompleteType,
+	OuiComboboxState,
+} from './models.combobox';
+
+// #region Functions
+
+export function generateComboboxIds(prefix: string, select: HTMLSelectElement): void {
+	const elements = [...select.children].flatMap(child =>
+		child instanceof HTMLOptGroupElement
+			? [
+					child,
+					...[...child.children].filter(groupChild => groupChild instanceof HTMLOptionElement),
+				]
+			: child instanceof HTMLOptionElement
+				? [child]
+				: [],
+	);
+
+	const {length} = elements;
+
+	for (let index = 0; index < length; index += 1) {
+		const element = elements[index];
+
+		if (element.id === '') {
+			element.id = `${prefix}${element instanceof HTMLOptGroupElement ? '_group_' : '_option_'}${index}`;
+		}
+	}
+}
+
+export function getComboboxAttributeValue<Value>(
+	element: HTMLElement,
+	attribute: string,
+	possible: Set<Value>,
+	defaultValue: Value,
+): Value {
+	const value = getAttribute(element, attribute);
+
+	return possible.has(value as Value) ? (value as Value) : defaultValue;
+}
+
+export function getComboboxAutoComplete(
+	element: OuiComboboxElement,
+	select: boolean,
+): OuiComboboxAutoComplete {
+	let value: OuiComboboxAutoCompleteType;
+
+	if (select) {
+		value = 'list';
+	} else {
+		value = getComboboxAttributeValue(element, 'autocomplete', COMBOBOX_AUTOCOMPLETES, 'none');
+	}
+
+	return {
+		value,
+		both: value === 'both',
+		inline: value === 'inline',
+		list: value === 'list',
+		none: value === 'none',
+	};
+}
+
+export function getComboboxBooleanAria(
+	element: HTMLElement,
+	attribute: AnyAriaBooleanAttribute,
+): boolean {
+	const value = getAria(element, attribute);
+
+	return value === true || value === 'true';
+}
+
+export function getComboboxId(): string {
+	index += 1;
+
+	return `oui_combobox_${index}`;
+}
+
+export function getComboboxVisibleOptions(state: OuiComboboxState): HTMLElement[] {
+	return state.options.all.filter(option => !option.hidden);
+}
+
+export function hasTextSelection(element: HTMLElement): element is HTMLInputElement {
+	return element instanceof HTMLInputElement && element.selectionStart !== element.selectionEnd;
+}
+
+export function setComboboxFilter(state: OuiComboboxState, value: unknown): void {
+	if (typeof value !== 'string') {
+		return;
+	}
+
+	const type: InputEvent['inputType'] =
+		value.length < state.filter.element.value.length ? 'deleteContentBackward' : 'insertText';
+
+	state.filter.element.value = value;
+
+	onComboboxFilter(type, state);
+}
+
+export function setComboboxLimit(
+	type: 'max' | 'min',
+	state: OuiComboboxState,
+	value?: unknown,
+): void {
+	let actual = value;
+
+	if (typeof actual === 'string') {
+		actual = Number.parseInt(actual, 10);
+	}
+
+	const updateLimit =
+		typeof actual === 'number' && !Number.isNaN(actual) && actual >= 0
+			? actual !== state[type]
+			: actual == null;
+
+	if (updateLimit) {
+		state[type] = actual as number | undefined;
+
+		setAttribute(state.host, type, actual);
+
+		updateComboboxValidity(state);
+	}
+}
+
+// #endregion
+
+// #region Variables
+
+let index = 0;
+
+// #endregion

package/src/js/combobox/models.combobox.ts

@@ -0,0 +1,94 @@
+import type {RemovableEventListener} from '@oscarpalmer/toretto/models';
+import type {OuiFloatable} from '../floatable/floatable.embedded';
+import type {OuiComboboxElement} from './index';
+
+export type OuiComboboxAnchor = {
+	container?: HTMLElement;
+	element: HTMLElement;
+};
+
+export type OuiComboboxAutoComplete = Record<OuiComboboxAutoCompleteType, boolean> & {
+	value: OuiComboboxAutoCompleteType;
+};
+
+export type OuiComboboxAutoCompleteType = 'both' | 'inline' | 'list' | 'none';
+
+export type OuiComboboxFilter = {
+	element: HTMLInputElement;
+	value: string;
+};
+
+export type OuiComboboxGroup = {
+	element: HTMLElement;
+	header: HTMLElement;
+	options: HTMLElement[];
+};
+
+export type OuiComboboxLabel = {
+	element: HTMLLabelElement;
+	id: string;
+};
+
+export type OuiComboboxLocalizations = {
+	empty: string | (() => string);
+	input: string | (() => string);
+	invalid: string | (() => string);
+	max: string | ((max: number) => string);
+	min: string | ((min: number) => string);
+	remove: string | ((label: string, value: string) => string);
+	results: string | ((amount: number) => string);
+	selected: string | ((amount: number) => string);
+};
+
+export type OuiComboboxOptions = {
+	all: HTMLElement[];
+	selected: HTMLElement[];
+};
+
+export type OuiComboboxPreview = 'none' | 'set' | 'typed';
+
+export type OuiComboboxSelection = {
+	container: HTMLElement;
+	items: OuiComboboxSelectionItem[];
+};
+
+export type OuiComboboxSelectionItem = {
+	button: HTMLButtonElement;
+	element: HTMLElement;
+};
+
+export type OuiComboboxState = {
+	active?: HTMLElement;
+	anchor: OuiComboboxAnchor;
+	autocomplete: OuiComboboxAutoComplete;
+	content: HTMLElement;
+	disabled: boolean;
+	filter: OuiComboboxFilter;
+	floatable: OuiFloatable;
+	groups?: OuiComboboxGroup[];
+	host: OuiComboboxElement;
+	id: string;
+	internals: ElementInternals;
+	label: OuiComboboxLabel;
+	listeners: RemovableEventListener[];
+	localizations: Record<string, Partial<OuiComboboxLocalizations>>;
+	max?: number;
+	min?: number;
+	message: HTMLElement;
+	name: string;
+	multiple: boolean;
+	options: OuiComboboxOptions;
+	readonly: boolean;
+	required: boolean;
+	select: HTMLSelectElement;
+	selection?: OuiComboboxSelection;
+	type: OuiComboboxType;
+	values: OuiComboboxValues;
+};
+
+export type OuiComboboxType = 'autocomplete' | 'select';
+
+export type OuiComboboxValues = {
+	current: string[];
+	initial: string[];
+};