@getdom/studio 0.1.0

package/src/pages/forms/combobox/DomCombobox.vue

@@ -0,0 +1,237 @@
+<script setup>
+import { computed, onMounted, ref, shallowRef, useId, watch } from 'vue';
+import { resolveFloatingTeleportTarget } from '../../lib/vue/floatingTeleportTarget.js';
+import DomFieldLoadingSpinner from '../_shared/DomFieldLoadingSpinner.vue';
+import { booleanProp, normalizeOption } from '../_shared/options.js';
+import DomField from '../field/DomField.vue';
+import { fieldProps } from '../field/fieldProps.js';
+import { useField } from '../field/useField.js';
+
+const listId = `dom-combobox-${useId()}`;
+
+defineOptions({
+	__doc: {
+		name: 'Combobox',
+		tag: '<DomCombobox>',
+		description: 'Select-like combobox with a styled input, floating list, keyboard navigation, and query events for async lookups.',
+		slots: [
+			{ name: 'item', payload: '{ item, index }', description: 'Replaces the rendering of each option.' },
+		],
+		events: [
+			{ name: 'query', payload: '(query: string)', description: 'Fired as the user types. Use it to fetch or replace options.' },
+			{ name: 'select', payload: '({ item, value, label })', description: 'Fired when an option is selected. item is the original option object.' },
+		],
+	},
+});
+
+const props = defineProps({
+	...fieldProps,
+	modelValue: {
+		type: [String, Number],
+		default: '',
+		_edit: { group: 'Control props', description: 'Committed selected value.' },
+	},
+	options: {
+		type: Array,
+		required: true,
+		_edit: {
+			component: 'DomJsonListInput',
+			description: 'Available options. May be replaced by async lookup results.',
+			props: {
+				compact: true,
+				addLabel: '+ Add option',
+				schema: [
+					{ key: 'label', label: 'Label', placeholder: 'Option label', default: (index) => `Option ${index + 1}` },
+					{ key: 'value', label: 'Value', placeholder: 'option-value', default: (index) => `option-${index + 1}` },
+				],
+			},
+		},
+	},
+	placeholder: {
+		type: String,
+		default: 'Search...',
+		_edit: { group: 'Control props', description: 'Placeholder shown when the input is empty.' },
+	},
+	placement: {
+		type: String,
+		default: 'bottom',
+		_edit: { group: 'Control props', options: ['bottom', 'top', 'right', 'left'], description: 'Preferred side before collision handling.' },
+	},
+	floatingMode: {
+		type: String,
+		default: 'viewport',
+		_edit: { group: 'Control props', options: ['viewport', 'anchor'], description: 'viewport keeps the list inside the browser; anchor keeps it attached while scrolling.' },
+	},
+	clearable: {
+		type: [Boolean, String],
+		default: true,
+		_edit: { group: 'Control props', description: 'Show a clear button when an option has been selected.' },
+	},
+	loading: {
+		type: [Boolean, String],
+		default: false,
+		_edit: { group: 'Control props', description: 'Show an inline spinner while async options are being fetched.' },
+	},
+});
+const emit = defineEmits(['update:modelValue', 'query', 'select', 'focus', 'blur']);
+
+const root = ref(null);
+const inputEl = ref(null);
+const isMounted = ref(false);
+const teleportTarget = shallowRef(null);
+const field = useField(props, emit, { idPrefix: 'dom-combobox' });
+const isClearable = computed(() => booleanProp(props.clearable, true));
+const isLoading = computed(() => booleanProp(props.loading, false));
+const hasSelection = computed(() => field.value.value !== null && field.value.value !== undefined && field.value.value !== '');
+const inputAttrs = computed(() => {
+	const { value: _value, ...attrs } = field.inputAttrs.value;
+	return attrs;
+});
+const inputPaddingClass = computed(() => {
+	if (isClearable.value && hasSelection.value && isLoading.value) return 'pr-28';
+	if (isClearable.value && hasSelection.value) return 'pr-20';
+	if (isLoading.value) return 'pr-20';
+	return 'pr-10';
+});
+const loadingPositionClass = computed(() => (isClearable.value && hasSelection.value ? 'right-[4.25rem]' : 'right-9'));
+
+const optionList = computed(() => props.options.map((option) => normalizeOption(option)).filter(Boolean));
+
+/**
+ * Resolve the user-facing text shown for a committed value.
+ *
+ * @param {string|number|null|undefined} value Current model value.
+ * @returns {string|number} Option label or raw value fallback.
+ */
+function displayForValue(value) {
+	const selected = optionList.value.find((option) => String(option.value ?? option.label) === String(value));
+	return selected ? (selected.label ?? selected.value ?? '') : (value ?? '');
+}
+
+/**
+ * Synchronize the headless host and visible input from the Vue model value.
+ *
+ * @returns {void}
+ */
+function syncInputFromModel() {
+	if (root.value && root.value.value !== String(field.value.value ?? '')) {
+		root.value.value = field.value.value ?? '';
+	}
+	if (inputEl.value) inputEl.value.value = displayForValue(field.value.value);
+}
+
+/**
+ * Refresh the input label after async option records change.
+ *
+ * @returns {void}
+ */
+function syncInputAfterOptionsChange() {
+	if (!hasSelection.value || field.focused.value) return;
+	syncInputFromModel();
+}
+
+onMounted(async () => {
+	teleportTarget.value = resolveFloatingTeleportTarget(root.value);
+	isMounted.value = true;
+	await import('../../lib/headless/combobox.js');
+	syncInputFromModel();
+	root.value?.addEventListener('dom:change', (event) => field.onInput(event.detail.value));
+	root.value?.addEventListener('dom:select', (event) => {
+		const index = Number(event.detail.option?.dataset.index);
+		emit('select', {
+			item: Number.isFinite(index) ? optionList.value[index] : null,
+			value: event.detail.value,
+			label: event.detail.label,
+			option: event.detail.option,
+		});
+	});
+	root.value?.addEventListener('dom:query', (event) => {
+		emit('query', event.detail.query);
+	});
+});
+
+watch(field.value, syncInputFromModel);
+watch(optionList, syncInputAfterOptionsChange);
+
+/**
+ * Clear the selected value and close any open suggestion list.
+ *
+ * @returns {void}
+ */
+function clearSelection() {
+	field.setValue('');
+	if (root.value) root.value.value = '';
+	if (inputEl.value) inputEl.value.value = '';
+	root.value?.removeAttribute('open');
+	emit('select', { item: null, value: '', label: '', option: null });
+}
+
+</script>
+
+<template>
+	<DomField v-bind="field.fieldAttrs.value" :chrome="chrome">
+		<dom-combobox
+			ref="root"
+			:data-menu-id="listId"
+			:placement="placement"
+			:floating-mode="floatingMode"
+			class="relative block"
+		>
+			<input
+				v-bind="inputAttrs"
+				ref="inputEl"
+				slot="input"
+				type="text"
+				class="skin-input h-10 rounded-full px-4 focus:ring-ring/60"
+				:class="inputPaddingClass"
+				@focus="field.onFocus"
+				@blur="field.onBlur"
+			/>
+			<DomFieldLoadingSpinner
+				v-if="isLoading"
+				class="absolute top-1"
+				:class="loadingPositionClass"
+			/>
+			<button
+				v-if="isClearable && hasSelection"
+				type="button"
+				class="absolute right-9 top-1 inline-flex size-8 items-center justify-center rounded-full text-muted-fg transition hover:bg-secondary hover:text-canvas-fg focus:outline-none focus-visible:ring-2 focus-visible:ring-ring/60"
+				aria-label="Clear selection"
+				@click.stop="clearSelection"
+				@mousedown.prevent
+			>
+				<svg viewBox="0 0 20 20" class="size-4" fill="none">
+					<circle cx="10" cy="10" r="7" stroke="currentColor" stroke-width="1.5" />
+					<path d="M7.5 7.5l5 5M12.5 7.5l-5 5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+				</svg>
+			</button>
+			<button
+				slot="toggle"
+				type="button"
+				class="absolute right-1 top-1 inline-flex size-8 items-center justify-center rounded-full text-muted-fg transition hover:bg-secondary hover:text-canvas-fg focus:outline-none focus-visible:ring-2 focus-visible:ring-ring/60"
+				aria-label="Show options"
+			>
+				<svg viewBox="0 0 20 20" class="size-4" fill="none">
+					<path d="M6 8l4 4 4-4" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" />
+				</svg>
+			</button>
+			<Teleport :to="teleportTarget || 'body'" :disabled="!isMounted || !teleportTarget">
+				<ul
+					:id="listId"
+					class="dom-floating-transition skin-popover z-50 max-h-[min(15rem,var(--dom-floating-available-height))] overflow-auto rounded-2xl p-1"
+				>
+					<li
+						v-for="(option, index) in optionList"
+						:key="option.value ?? index"
+						:data-value="option.value"
+						:data-label="option.label"
+						:data-index="index"
+						class="cursor-pointer rounded-xl px-3 py-2 text-sm transition data-[active]:bg-accent aria-selected:bg-accent"
+					>
+						<slot name="item" :item="option" :index="index">{{ option.label }}</slot>
+					</li>
+				</ul>
+			</Teleport>
+		</dom-combobox>
+	</DomField>
+</template>

package/src/pages/forms/confirmation-code-input/DomConfirmationCodeInput.vue

@@ -0,0 +1,345 @@
+<script setup>
+import { computed, nextTick, ref, watch } from 'vue';
+import DomField from '../field/DomField.vue';
+import { fieldProps } from '../field/fieldProps.js';
+import { useField } from '../field/useField.js';
+
+defineOptions({
+	__doc: {
+		name: 'Confirmation code input',
+		tag: '<DomConfirmationCodeInput>',
+		description: 'A segmented confirmation-code field with one character per box, automatic focus movement, and full-code paste support.',
+		icon: 'M4 8h3v3H4V8Zm6 0h3v3h-3V8Zm6 0h3v3h-3V8ZM4 14h3v3H4v-3Zm6 0h3v3h-3v-3Zm6 0h3v3h-3v-3Z',
+		events: [
+			{ name: 'update:modelValue', payload: 'string', description: 'Fired whenever the entered code changes.' },
+			{ name: 'complete', payload: 'string', description: 'Fired when every character box contains a value.' },
+			{ name: 'focus', payload: 'FocusEvent', description: 'Fired when focus enters the segmented control.' },
+			{ name: 'blur', payload: 'FocusEvent', description: 'Fired when focus leaves the segmented control.' },
+		],
+		keyboard: [
+			{ keys: 'Character', action: 'Enter one character and move focus to the next box.' },
+			{ keys: 'Backspace', action: 'Clear the current box, or move back and clear the previous box when empty.' },
+			{ keys: 'Delete', action: 'Clear the current box.' },
+			{ keys: 'Left / Right', action: 'Move between character boxes.' },
+			{ keys: 'Home / End', action: 'Move to the first or last character box.' },
+			{ keys: 'Paste', action: 'Distribute a complete or partial code across the boxes.' },
+		],
+	},
+});
+
+const props = defineProps({
+	...fieldProps,
+	modelValue: {
+		type: String,
+		default: '',
+		_edit: { group: 'Control props', description: 'Confirmation code without the visual separator.' },
+	},
+	length: {
+		type: Number,
+		default: 6,
+		_edit: { group: 'Control props', min: 1, max: 12, description: 'Number of character boxes.' },
+	},
+	separatorAfter: {
+		type: Number,
+		default: 3,
+		_edit: { group: 'Control props', min: 0, max: 11, description: 'Box position after which to show a visual separator. Use 0 to hide it.' },
+	},
+	characterSet: {
+		type: String,
+		default: 'alphanumeric',
+		_edit: { group: 'Control props', options: ['alphanumeric', 'numeric'], description: 'Characters accepted by the control.' },
+	},
+	uppercase: {
+		type: Boolean,
+		default: true,
+		_edit: { group: 'Control props', description: 'Convert entered letters to uppercase.' },
+	},
+	autocomplete: {
+		type: String,
+		default: 'one-time-code',
+		_edit: { group: 'Control props', description: 'Native autocomplete hint applied to the first box.' },
+	},
+});
+
+const emit = defineEmits(['update:modelValue', 'complete', 'focus', 'blur']);
+const field = useField(props, emit, { idPrefix: 'dom-confirmation-code-input' });
+const group = ref(null);
+const codeLength = computed(() => Math.min(12, Math.max(1, Math.round(props.length || 6))));
+const separatorPosition = computed(() => {
+	const requestedPosition = Math.round(props.separatorAfter || 0);
+	return requestedPosition > 0 && requestedPosition < codeLength.value ? requestedPosition : 0;
+});
+const inputMode = computed(() => (props.characterSet === 'numeric' ? 'numeric' : 'text'));
+const inputPattern = computed(() => (props.characterSet === 'numeric' ? '[0-9]' : '[A-Za-z0-9]'));
+const segments = ref(createSegments(field.value.value));
+const code = computed(() => segments.value.join(''));
+let lastEmittedValue = sanitizeCode(field.value.value);
+
+watch(field.value, (value) => {
+	const normalizedValue = sanitizeCode(value);
+	if (normalizedValue === lastEmittedValue) return;
+	segments.value = createSegments(normalizedValue);
+	lastEmittedValue = normalizedValue;
+});
+
+watch(
+	[codeLength, () => props.characterSet, () => props.uppercase],
+	() => {
+		segments.value = createSegments(field.value.value);
+		lastEmittedValue = sanitizeCode(field.value.value);
+	},
+);
+
+/**
+ * Removes unsupported characters and applies the configured letter casing.
+ *
+ * @param {unknown} value Raw code value.
+ * @returns {string} Normalized confirmation code.
+ */
+function sanitizeCode(value) {
+	const pattern = props.characterSet === 'numeric' ? /[^0-9]/g : /[^a-z0-9]/gi;
+	const normalizedValue = String(value ?? '').replace(pattern, '');
+	return (props.uppercase ? normalizedValue.toUpperCase() : normalizedValue).slice(0, codeLength.value);
+}
+
+/**
+ * Builds the fixed-length character array used by the segmented inputs.
+ *
+ * @param {unknown} value Raw or normalized code value.
+ * @returns {string[]} Character slots padded with empty strings.
+ */
+function createSegments(value) {
+	const nextSegments = Array.from({ length: codeLength.value }, () => '');
+	for (const [index, character] of Array.from(sanitizeCode(value)).entries()) {
+		nextSegments[index] = character;
+	}
+	return nextSegments;
+}
+
+/**
+ * Resolves a character input from its stable data attribute.
+ *
+ * @param {number} index Zero-based character position.
+ * @returns {HTMLInputElement|null} Matching character input.
+ */
+function inputAt(index) {
+	return group.value?.querySelector(`[data-code-index="${index}"]`) || null;
+}
+
+/**
+ * Moves focus to a character input and selects its existing value.
+ *
+ * @param {number} index Zero-based character position.
+ * @returns {Promise<void>} Promise resolved after Vue updates the inputs.
+ */
+async function focusInput(index) {
+	const boundedIndex = Math.min(codeLength.value - 1, Math.max(0, index));
+	await nextTick();
+	const input = inputAt(boundedIndex);
+	input?.focus();
+	input?.select();
+}
+
+/**
+ * Writes the local character slots through the shared field contract.
+ *
+ * @returns {void}
+ */
+function commitCode() {
+	const nextCode = code.value;
+	lastEmittedValue = nextCode;
+	field.onInput(nextCode);
+	if (segments.value.every(Boolean)) emit('complete', nextCode);
+}
+
+/**
+ * Distributes one or more characters from a starting box.
+ *
+ * @param {string} value Characters to insert.
+ * @param {number} startIndex Zero-based insertion position.
+ * @returns {void}
+ */
+function insertCharacters(value, startIndex) {
+	const characters = Array.from(sanitizeCode(value));
+	if (!characters.length) return;
+	const nextSegments = [...segments.value];
+	let nextIndex = startIndex;
+	for (const character of characters) {
+		if (nextIndex >= codeLength.value) break;
+		nextSegments[nextIndex] = character;
+		nextIndex += 1;
+	}
+	segments.value = nextSegments;
+	commitCode();
+	if (nextIndex < codeLength.value) void focusInput(nextIndex);
+}
+
+/**
+ * Handles native text input, including browser-provided one-time-code values.
+ *
+ * @param {InputEvent} event Native input event.
+ * @param {number} index Zero-based character position.
+ * @returns {void}
+ */
+function onInput(event, index) {
+	if (field.disabled.value || field.readOnly.value) return;
+	const value = sanitizeCode(event.target.value);
+	if (value) {
+		insertCharacters(value, index);
+		return;
+	}
+	const nextSegments = [...segments.value];
+	nextSegments[index] = '';
+	segments.value = nextSegments;
+	commitCode();
+}
+
+/**
+ * Distributes pasted confirmation-code text from the active box.
+ *
+ * @param {ClipboardEvent} event Native paste event.
+ * @param {number} index Zero-based character position.
+ * @returns {void}
+ */
+function onPaste(event, index) {
+	if (field.disabled.value || field.readOnly.value) return;
+	const value = sanitizeCode(event.clipboardData?.getData('text'));
+	if (!value) return;
+	event.preventDefault();
+	insertCharacters(value, index);
+}
+
+/**
+ * Applies segmented-input navigation and deletion keys.
+ *
+ * @param {KeyboardEvent} event Native keyboard event.
+ * @param {number} index Zero-based character position.
+ * @returns {void}
+ */
+function onKeydown(event, index) {
+	if (field.disabled.value || field.readOnly.value) return;
+	if (event.key === 'ArrowLeft') {
+		event.preventDefault();
+		void focusInput(index - 1);
+		return;
+	}
+	if (event.key === 'ArrowRight') {
+		event.preventDefault();
+		void focusInput(index + 1);
+		return;
+	}
+	if (event.key === 'Home') {
+		event.preventDefault();
+		void focusInput(0);
+		return;
+	}
+	if (event.key === 'End') {
+		event.preventDefault();
+		void focusInput(codeLength.value - 1);
+		return;
+	}
+	if (event.key !== 'Backspace' && event.key !== 'Delete') return;
+
+	event.preventDefault();
+	const nextSegments = [...segments.value];
+	if (event.key === 'Backspace' && !nextSegments[index] && index > 0) {
+		nextSegments[index - 1] = '';
+		segments.value = nextSegments;
+		commitCode();
+		void focusInput(index - 1);
+		return;
+	}
+	nextSegments[index] = '';
+	segments.value = nextSegments;
+	commitCode();
+}
+
+/**
+ * Selects a box's current character when it receives focus.
+ *
+ * @param {FocusEvent} event Native focus event.
+ * @returns {void}
+ */
+function onCellFocus(event) {
+	event.target.select();
+}
+
+/**
+ * Emits one field-level focus event when focus enters the segmented control.
+ *
+ * @param {FocusEvent} event Native focus-in event.
+ * @returns {void}
+ */
+function onGroupFocus(event) {
+	if (!field.focused.value) field.onFocus(event);
+}
+
+/**
+ * Emits one field-level blur event after focus leaves every character box.
+ *
+ * @param {FocusEvent} event Native focus-out event.
+ * @returns {void}
+ */
+function onGroupBlur(event) {
+	if (group.value?.contains(event.relatedTarget)) return;
+	void field.onBlur(event);
+}
+</script>
+
+<template>
+	<DomField v-bind="field.fieldAttrs.value" :chrome="chrome">
+		<input
+			v-if="field.htmlName.value"
+			type="hidden"
+			:name="field.htmlName.value"
+			:value="code"
+		/>
+		<div
+			ref="group"
+			role="group"
+			:aria-label="label || 'Confirmation code'"
+			:aria-describedby="field.describedBy.value || undefined"
+			:aria-errormessage="field.errorId.value || undefined"
+			:aria-invalid="field.invalid.value || undefined"
+			:data-invalid="field.invalid.value ? '' : undefined"
+			class="flex w-fit max-w-full items-center gap-1.5"
+			@focusin="onGroupFocus"
+			@focusout="onGroupBlur"
+		>
+			<template v-for="(_, index) in segments" :key="index">
+				<input
+					:id="index === 0 ? field.id.value : `${field.id.value}-${index + 1}`"
+					type="text"
+					:value="segments[index]"
+					:inputmode="inputMode"
+					:pattern="inputPattern"
+					:maxlength="index === 0 ? codeLength : 1"
+					:autocomplete="index === 0 ? autocomplete : 'off'"
+					:autocapitalize="uppercase ? 'characters' : 'off'"
+					:disabled="field.disabled.value || undefined"
+					:readonly="field.readOnly.value || undefined"
+					:required="required || undefined"
+					:aria-label="`Character ${index + 1} of ${codeLength}`"
+					:aria-invalid="field.invalid.value || undefined"
+					:aria-describedby="field.describedBy.value || undefined"
+					:aria-errormessage="field.errorId.value || undefined"
+					:data-code-index="index"
+					:data-invalid="field.invalid.value ? '' : undefined"
+					:spellcheck="false"
+					class="skin-input size-11 max-w-11 flex-none px-0 py-0 text-center font-mono text-lg font-semibold tracking-wide sm:size-12 sm:max-w-12"
+					@focus="onCellFocus"
+					@input="onInput($event, index)"
+					@keydown="onKeydown($event, index)"
+					@paste="onPaste($event, index)"
+				/>
+				<span
+					v-if="separatorPosition && index + 1 === separatorPosition"
+					class="mx-0.5 text-sm font-semibold text-muted-fg"
+					aria-hidden="true"
+				>
+					-
+				</span>
+			</template>
+		</div>
+	</DomField>
+</template>