@getdom/studio 0.1.0

package/src/pages/forms/select/DomSelect.vue

@@ -0,0 +1,479 @@
+<script setup>
+import { computed, nextTick, onMounted, ref, shallowRef, useId, watch } from 'vue';
+import { resolveFloatingTeleportTarget } from '../../lib/vue/floatingTeleportTarget.js';
+import { booleanProp, normalizeOption, searchableText } from '../_shared/options.js';
+import DomField from '../field/DomField.vue';
+import { fieldProps } from '../field/fieldProps.js';
+import { useField } from '../field/useField.js';
+
+const id = useId();
+const panelId = `dom-select-panel-${id}`;
+const listId = `dom-select-list-${id}`;
+
+defineOptions({
+	__doc: {
+		name: 'Select',
+		tag: '<DomSelect>',
+		description: 'A styled select control with a closed trigger, floating listbox, keyboard navigation, and rich option slots.',
+		slots: [
+			{ name: 'value', payload: '{ option, value, label, placeholder }', description: 'Custom selected-value markup inside the trigger.' },
+			{ name: 'option', payload: '{ option, index, selected, optionId }', description: 'Custom option markup inside the floating list. optionId identifies the focusable option button for external floating UI.' },
+			{ name: 'group', payload: '{ group, options, index }', description: 'Custom heading markup for options that share a group.' },
+		],
+		events: [
+			{ name: 'update:modelValue', payload: '(value: string)', description: 'Emitted when the selected option changes.' },
+			{ name: 'select', payload: '({ option, value, label })', description: 'Emitted with the selected option record.' },
+		],
+		keyboard: [
+			{ keys: 'Enter / Space / ↓', action: 'Open the listbox.' },
+			{ keys: '↑ / ↓', action: 'Move active option.' },
+			{ keys: 'Type in search', action: 'Filter visible options when searchable is enabled.' },
+			{ keys: 'Enter / Space', action: 'Select active option.' },
+			{ keys: 'Esc / Tab', action: 'Close and return focus.' },
+		],
+	},
+});
+
+const props = defineProps({
+	...fieldProps,
+	modelValue: {
+		type: [String, Number],
+		default: '',
+		_edit: { group: 'Control props', description: 'Selected option value.' },
+	},
+	options: {
+		type: Array,
+		required: true,
+		_edit: {
+			component: 'DomJsonListInput',
+			description: 'Available options. Set group for non-selectable section headings and use the option slot for rich rows.',
+			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}` },
+					{ key: 'description', label: 'Description', placeholder: 'Optional helper text' },
+				],
+			},
+		},
+	},
+	placeholder: {
+		type: String,
+		default: 'Select an option',
+		_edit: { group: 'Control props', description: 'Text shown when no option is selected.' },
+	},
+	placement: {
+		type: String,
+		default: 'bottom',
+		_edit: { group: 'Control props', options: ['bottom', 'top', 'right', 'left'], description: 'Preferred side before collision handling.' },
+	},
+	align: {
+		type: String,
+		default: 'left',
+		_edit: { group: 'Control props', options: ['left', 'right'], description: 'Horizontal panel alignment.' },
+	},
+	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.' },
+	},
+	width: {
+		type: String,
+		default: 'min-w-[14rem]',
+		_edit: { group: 'Control props', description: 'Tailwind width utility for the floating listbox.' },
+	},
+	optionTone: {
+		type: String,
+		default: 'accent',
+		_edit: { group: 'Control props', description: 'Theme token basename for hovered, focused, and selected options. For example, primary uses var(--primary) and var(--primary-fg).' },
+	},
+	searchable: {
+		type: [Boolean, String],
+		default: false,
+		_edit: { group: 'Control props', description: 'Show a search input inside the option panel while keeping select-style committed values.' },
+	},
+	searchPlaceholder: {
+		type: String,
+		default: 'Search options...',
+		_edit: { group: 'Control props', description: 'Placeholder shown inside the panel search input.' },
+	},
+});
+const emit = defineEmits(['update:modelValue', 'select', 'focus', 'blur']);
+
+const root = ref(null);
+const listbox = ref(null);
+const searchInput = ref(null);
+const searchQuery = ref('');
+const isMounted = ref(false);
+const teleportTarget = shallowRef(null);
+const field = useField(props, emit, { idPrefix: 'dom-select' });
+const isSearchable = computed(() => booleanProp(props.searchable, false));
+
+const optionList = computed(() => props.options.map((option) => normalizeOption(option, {
+	stringifyValue: true,
+	allowEmptyValue: true,
+})).filter(Boolean));
+const filteredOptions = computed(() => {
+	if (!isSearchable.value) return optionList.value;
+	const needle = searchQuery.value.trim().toLowerCase();
+	if (!needle) return optionList.value;
+	return optionList.value.filter((option) => searchableText(option).includes(needle));
+});
+const optionSections = computed(buildOptionSections);
+const hasOptionGroups = computed(() => optionSections.value.some((section) => section.group));
+const selectedOption = computed(() => optionList.value.find((option) => String(option.value) === String(field.value.value)) || null);
+const selectedLabel = computed(() => selectedOption.value?.label ?? '');
+const selectedValue = computed(() => String(field.value.value ?? ''));
+const triggerClasses = computed(() => [
+	'skin-input flex h-auto min-h-10 cursor-pointer items-center justify-between gap-3 py-2 pr-3 text-left',
+	(field.disabled.value || field.readOnly.value) && 'cursor-not-allowed opacity-60',
+	field.invalid.value && 'border-destructive focus:border-destructive focus:ring-destructive/25',
+]);
+const optionToneStyle = computed(() => {
+	const tone = normalizeThemeVariableName(props.optionTone);
+	return {
+		'--dom-select-option-active-bg': `var(--${tone}, var(--accent))`,
+		'--dom-select-option-active-fg': `var(--${tone}-fg, var(--accent-fg))`,
+	};
+});
+
+/**
+ * Normalize a theme token basename before using it to assemble CSS variable references.
+ *
+ * @param {string|null|undefined} value Theme token basename such as accent, primary, or --brand.
+ * @returns {string} Safe CSS custom property basename without the leading double dash.
+ */
+function normalizeThemeVariableName(value) {
+	const name = String(value || '').trim().replace(/^--/, '');
+	return /^[A-Za-z][A-Za-z0-9_-]*$/.test(name) ? name : 'accent';
+}
+
+/**
+ * Build ordered option sections while preserving each option's filtered-list index.
+ *
+ * Options with the same non-empty group label share an accessible group. Ungrouped
+ * options remain in an unlabelled section and behave exactly like the flat list.
+ *
+ * @returns {Array<{ key: string, group: string|null, options: Array<Object>, entries: Array<{ option: Object, index: number }> }>} Ordered option sections.
+ */
+function buildOptionSections() {
+	const sections = [];
+	const sectionsByGroup = new Map();
+
+	filteredOptions.value.forEach((option, index) => {
+		const group = optionGroupLabel(option);
+		let section = sectionsByGroup.get(group);
+
+		if (!section) {
+			section = {
+				key: group === null ? 'ungrouped' : `group:${group}`,
+				group,
+				options: [],
+				entries: [],
+			};
+			sectionsByGroup.set(group, section);
+			sections.push(section);
+		}
+
+		section.options.push(option);
+		section.entries.push({ option, index });
+	});
+
+	return sections;
+}
+
+/**
+ * Normalize an option's group into a visible heading label.
+ *
+ * @param {Object|null|undefined} option Normalized select option.
+ * @returns {string|null} Trimmed group label, or null for an ungrouped option.
+ */
+function optionGroupLabel(option) {
+	if (option?.group === undefined || option?.group === null) return null;
+	const group = String(option.group).trim();
+	return group || null;
+}
+
+onMounted(async () => {
+	teleportTarget.value = resolveFloatingTeleportTarget(root.value);
+	isMounted.value = true;
+	await nextTick();
+	await Promise.all([
+		import('../../lib/headless/dropdown.js'),
+		import('../../lib/headless/listbox.js'),
+	]);
+	listbox.value?.addEventListener('dom:select', onSelect);
+	root.value?.addEventListener('dom:open', onOpen);
+	root.value?.addEventListener('dom:close', resetSearch);
+});
+
+watch(selectedValue, () => {
+	if (listbox.value && listbox.value.value !== selectedValue.value) listbox.value.value = selectedValue.value;
+});
+watch(isSearchable, () => {
+	if (!isSearchable.value) resetSearch();
+});
+
+/**
+ * Commit the selected option value and close the floating panel.
+ *
+ * @param {CustomEvent<{ value: string }>} event Selection event from the headless listbox.
+ * @returns {void}
+ */
+function onSelect(event) {
+	if (field.disabled.value || field.readOnly.value) return;
+	const value = event.detail.value;
+	const option = optionList.value.find((item) => String(item.value) === String(value)) || null;
+	field.onInput(value);
+	emit('select', {
+		option,
+		value,
+		label: option?.label ?? value,
+	});
+	close();
+}
+
+/**
+ * Reset transient search state when the select panel opens.
+ *
+ * @returns {void}
+ */
+function onOpen() {
+	resetSearch();
+	if (!isSearchable.value) return;
+	nextTick(() => searchInput.value?.focus());
+}
+
+/**
+ * Close the headless dropdown host.
+ *
+ * @returns {void}
+ */
+function close() {
+	if (root.value) root.value.open = false;
+}
+
+/**
+ * Clear the panel search input and matching query state.
+ *
+ * @returns {void}
+ */
+function resetSearch() {
+	searchQuery.value = '';
+	if (searchInput.value) searchInput.value.value = '';
+}
+
+/**
+ * Select an option from keyboard-driven searchable interactions.
+ *
+ * @param {{ value: string, disabled?: boolean }|null|undefined} option Normalized option record.
+ * @returns {void}
+ */
+function selectOption(option) {
+	if (!option || option.disabled) return;
+	onSelect({
+		detail: { value: option.value },
+	});
+}
+
+/**
+ * Move focus to the first or last visible option in the listbox.
+ *
+ * @param {'first'|'last'} [position='first'] Position to focus.
+ * @returns {void}
+ */
+function focusVisibleOption(position = 'first') {
+	const options = Array.from(listbox.value?.querySelectorAll('[role="option"]:not([disabled])') || [])
+		.filter((option) => option.getAttribute('aria-disabled') !== 'true');
+	if (!options.length) return;
+	const option = position === 'last' ? options[options.length - 1] : options[0];
+	option.focus();
+}
+
+/**
+ * Handle search-box keyboard shortcuts without leaking navigation to the listbox wrapper.
+ *
+ * @param {KeyboardEvent} event Search input keydown event.
+ * @returns {void}
+ */
+function onSearchKeydown(event) {
+	if (event.key === 'ArrowDown') {
+		event.preventDefault();
+		event.stopPropagation();
+		focusVisibleOption('first');
+		return;
+	}
+	if (event.key === 'ArrowUp') {
+		event.preventDefault();
+		event.stopPropagation();
+		focusVisibleOption('last');
+		return;
+	}
+	if (event.key === 'Enter') {
+		event.preventDefault();
+		event.stopPropagation();
+		selectOption(filteredOptions.value[0]);
+		return;
+	}
+	if (event.key === 'Home' || event.key === 'End') {
+		event.stopPropagation();
+	}
+}
+</script>
+
+<template>
+	<DomField v-bind="field.fieldAttrs.value" :chrome="chrome">
+		<input
+			v-if="field.htmlName.value"
+			type="hidden"
+			:name="field.htmlName.value"
+			:value="field.value.value ?? ''"
+		/>
+		<dom-dropdown
+			ref="root"
+			:data-menu-id="panelId"
+			:align="align"
+			:placement="placement"
+			:floating-mode="floatingMode"
+			:offset="4"
+			:data-disabled="field.disabled.value || field.readOnly.value ? '' : null"
+			class="relative block"
+		>
+			<button
+				:id="field.id.value"
+				slot="trigger"
+				type="button"
+				:class="triggerClasses"
+				:disabled="field.disabled.value || field.readOnly.value || undefined"
+				:aria-label="label || placeholder"
+				:aria-describedby="field.describedBy.value || undefined"
+				:aria-invalid="field.invalid.value || undefined"
+				:aria-errormessage="field.errorId.value || undefined"
+				:aria-controls="panelId"
+				@focus="field.onFocus"
+				@blur="field.onBlur"
+			>
+				<span class="min-w-0 flex-1 truncate">
+					<slot
+						name="value"
+						:option="selectedOption"
+						:value="selectedValue"
+						:label="selectedLabel"
+						:placeholder="placeholder"
+					>
+						<span :class="selectedOption ? 'text-canvas-fg' : 'text-muted-fg'">
+							{{ selectedOption ? selectedLabel : placeholder }}
+						</span>
+					</slot>
+				</span>
+				<svg viewBox="0 0 20 20" class="size-4 shrink-0 text-muted-fg" fill="none" aria-hidden="true">
+					<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">
+				<div
+					:id="panelId"
+					popover="manual"
+					data-composite-panel="true"
+					data-haspopup="listbox"
+					class="dom-dropdown-menu dom-floating-transition skin-popover z-50 flex max-h-[min(20rem,var(--dom-floating-available-height))] flex-col overflow-hidden rounded-2xl p-0"
+					:class="width"
+					:style="optionToneStyle"
+				>
+					<div v-if="isSearchable" class="border-b border-border p-2">
+						<input
+							ref="searchInput"
+							v-model="searchQuery"
+							type="search"
+							data-autofocus
+							:placeholder="searchPlaceholder"
+							:aria-label="label ? `Search ${label}` : 'Search options'"
+							:aria-controls="listId"
+							class="skin-input h-9 w-full rounded-full px-3 text-sm focus:ring-ring/60"
+							@focus="field.onFocus"
+							@blur="field.onBlur"
+							@keydown="onSearchKeydown"
+						/>
+					</div>
+					<dom-listbox
+						:id="listId"
+						ref="listbox"
+						:value="selectedValue"
+						class="min-h-0 overflow-auto"
+						:class="hasOptionGroups ? 'px-1 pb-1' : 'p-1'"
+					>
+						<div
+							v-for="(section, sectionIndex) in optionSections"
+							:key="section.key"
+							:role="section.group ? 'group' : null"
+							:aria-labelledby="section.group ? `${listId}-group-${sectionIndex}` : null"
+							:class="section.group ? 'pb-1 last:pb-0' : 'contents'"
+						>
+							<div
+								v-if="section.group"
+								class="sticky top-0 z-10 bg-[var(--skin-popover-bg,var(--canvas))]"
+							>
+								<div
+									:id="`${listId}-group-${sectionIndex}`"
+									class="px-3 pb-1 pt-2 text-xs font-semibold uppercase tracking-[0.12em] text-muted-fg"
+								>
+									<slot name="group" :group="section.group" :options="section.options" :index="sectionIndex">
+										{{ section.group }}
+									</slot>
+								</div>
+								<div class="mx-3 mb-1 border-t border-border" aria-hidden="true"></div>
+							</div>
+							<button
+								v-for="entry in section.entries"
+								:key="entry.option.value ?? entry.index"
+								:id="`${listId}-option-${entry.index}`"
+								role="option"
+								type="button"
+								:data-value="entry.option.value"
+								:disabled="entry.option.disabled || undefined"
+								class="dom-select-option flex w-full cursor-pointer items-center justify-between gap-3 rounded-xl px-3 py-2 text-left text-sm text-canvas-fg outline-none transition disabled:cursor-not-allowed disabled:opacity-50"
+							>
+								<span class="min-w-0 flex-1">
+									<slot
+										name="option"
+										:option="entry.option"
+										:index="entry.index"
+										:selected="String(entry.option.value) === selectedValue"
+										:option-id="`${listId}-option-${entry.index}`"
+									>
+										<span class="block font-medium">{{ entry.option.label }}</span>
+										<span v-if="entry.option.description" class="dom-select-option-description mt-0.5 block text-xs text-muted-fg">{{ entry.option.description }}</span>
+									</slot>
+								</span>
+								<svg
+									v-if="String(entry.option.value) === selectedValue"
+									viewBox="0 0 20 20"
+									class="size-4 shrink-0"
+									fill="none"
+									aria-hidden="true"
+								>
+									<path d="M4.5 10.5 8 14l7.5-8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+								</svg>
+							</button>
+						</div>
+						<div v-if="isSearchable && !filteredOptions.length" class="px-3 py-6 text-center text-sm text-muted-fg">
+							No options found
+						</div>
+					</dom-listbox>
+				</div>
+			</Teleport>
+		</dom-dropdown>
+	</DomField>
+</template>
+
+<style scoped>
+.dom-select-option:not(:disabled):is(:hover, :focus, [aria-selected="true"]) {
+	background-color: var(--dom-select-option-active-bg, var(--accent));
+	color: var(--dom-select-option-active-fg, var(--accent-fg));
+}
+
+.dom-select-option:not(:disabled):is(:hover, :focus, [aria-selected="true"]) .dom-select-option-description {
+	color: var(--dom-select-option-active-fg, var(--accent-fg));
+}
+</style>

package/src/pages/forms/select-input/DomSelectInput.vue

@@ -0,0 +1,155 @@
+<script setup>
+import { nextTick, onBeforeUnmount, onMounted, ref } from 'vue';
+import DomField from '../field/DomField.vue';
+import DomButton from '../../components/button/DomButton.vue';
+import { fieldProps } from '../field/fieldProps.js';
+import { useField } from '../field/useField.js';
+
+const props = defineProps({
+	...fieldProps,
+	modelValue: {
+		default: null,
+		_edit: { group: 'Control props', description: 'Selected value.' },
+	},
+	options: {
+		type: Array,
+		default: () => [],
+		_edit: {
+			group: 'Control props',
+			component: 'DomJsonListInput',
+			description: 'Options to render as buttons.',
+			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}` },
+				],
+			},
+		},
+	},
+});
+const emit = defineEmits(['update:modelValue', 'focus', 'blur']);
+const field = useField(props, emit, { idPrefix: 'dom-select-input' });
+const groupElement = ref(null);
+const wrapped = ref(false);
+let resizeObserver;
+
+/**
+ * Resolves the visible label for an option.
+ *
+ * @param {unknown} option Select option.
+ * @returns {unknown} Visible option label.
+ */
+function labelOf(option) {
+	return option && typeof option === 'object' ? (option.label ?? option.value) : option;
+}
+
+/**
+ * Resolves the emitted value for an option.
+ *
+ * @param {unknown} option Select option.
+ * @returns {unknown} Stable option value.
+ */
+function valueOf(option) {
+	return option && typeof option === 'object' ? (option.value ?? option.label) : option;
+}
+
+/**
+ * Selects an enabled, writable option.
+ *
+ * @param {unknown} value Option value.
+ * @returns {void}
+ */
+function select(value) {
+	if (field.disabled.value || field.readOnly.value) return;
+	field.onInput(value);
+}
+
+/**
+ * Detects whether the rendered option buttons occupy more than one row.
+ *
+ * @returns {void}
+ */
+function measureWrapping() {
+	const buttons = [...(groupElement.value?.children || [])];
+	const firstTop = buttons[0]?.offsetTop;
+	wrapped.value = firstTop != null && buttons.some((button) => button.offsetTop !== firstTop);
+}
+
+/**
+ * Starts observing the option group so its joined styling can adapt to wrapping.
+ *
+ * @returns {void}
+ */
+function startWrappingObserver() {
+	nextTick(measureWrapping);
+	if (typeof ResizeObserver === 'undefined' || !groupElement.value) return;
+	resizeObserver = new ResizeObserver(measureWrapping);
+	resizeObserver.observe(groupElement.value);
+}
+
+/**
+ * Stops the option-group resize observer during component teardown.
+ *
+ * @returns {void}
+ */
+function stopWrappingObserver() {
+	resizeObserver?.disconnect();
+}
+
+/**
+ * Builds option classes for joined and wrapped group layouts.
+ *
+ * @param {number} index Option index.
+ * @returns {Array<string>} Vue class list for the option button.
+ */
+function optionClasses(index) {
+	if (wrapped.value) return ['ml-0 rounded-full'];
+	return [
+		index > 0 ? '-ml-px' : '',
+		index === 0 ? 'rounded-l-full' : 'rounded-none',
+		index === props.options.length - 1 ? 'rounded-r-full' : 'rounded-none',
+	];
+}
+
+onMounted(startWrappingObserver);
+onBeforeUnmount(stopWrappingObserver);
+</script>
+
+<template>
+	<DomField v-bind="field.fieldAttrs.value" :chrome="chrome">
+		<input
+			v-if="field.htmlName.value"
+			type="hidden"
+			:name="field.htmlName.value"
+			:value="field.value.value ?? ''"
+		/>
+		<div
+			:id="field.id.value"
+			ref="groupElement"
+			role="group"
+			:aria-label="label || undefined"
+			:aria-describedby="field.describedBy.value || undefined"
+			:aria-invalid="field.invalid.value || undefined"
+			:aria-errormessage="field.errorId.value || undefined"
+			:data-wrapped="wrapped || undefined"
+			class="flex flex-wrap"
+			:class="wrapped ? 'gap-1' : 'gap-0'"
+		>
+			<DomButton
+				v-for="(opt, i) in options"
+				:key="valueOf(opt)"
+				type="button"
+				size="sm"
+				:variant="field.value.value === valueOf(opt) ? 'primary' : 'secondary'"
+				:disabled="field.disabled.value"
+				:aria-pressed="field.value.value === valueOf(opt)"
+				@click="select(valueOf(opt))"
+				@focus="field.onFocus"
+				@blur="field.onBlur"
+				:class="optionClasses(i)"
+			>{{ labelOf(opt) }}</DomButton>
+		</div>
+	</DomField>
+</template>