@pdanpdan/headless-combobox-vue 0.0.0-stage → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,124 @@
1
+ <script setup lang="ts" generic="O, V = O, Q = string">
2
+ import type { HeadlessComboboxProps, HeadlessComboboxSlotProps } from './useHeadlessCombobox';
3
+
4
+ import { useHeadlessCombobox } from './useHeadlessCombobox';
5
+
6
+ export type {
7
+ HeadlessComboboxComboboxInputProps,
8
+ HeadlessComboboxErrorCode,
9
+ HeadlessComboboxInputProps,
10
+ HeadlessComboboxListboxProps,
11
+ HeadlessComboboxOptionProps,
12
+ HeadlessComboboxPopupStyle,
13
+ HeadlessComboboxProps,
14
+ HeadlessComboboxPropsSource,
15
+ HeadlessComboboxScope,
16
+ HeadlessComboboxSlotProps,
17
+ HeadlessComboboxTriggerProps,
18
+ } from './useHeadlessCombobox';
19
+
20
+ const props = withDefaults(defineProps<Omit<HeadlessComboboxProps<O, V, Q>, 'modelValue'>>(), {
21
+ // defaults to auto based on `multiple`.
22
+ closeOnSelect: null,
23
+ // Vue casts absent boolean props to `false`; the default must be explicit.
24
+ closeOnClickOutside: true,
25
+ inputOnOpen: 'select',
26
+ });
27
+
28
+ defineSlots<{
29
+ default: (props: HeadlessComboboxSlotProps<O, V, Q>) => unknown;
30
+ }>();
31
+
32
+ // No parent `v-model`? The model falls back to local state (`defineModel`
33
+ // keeps the last set value internally) so the component still works.
34
+ const model = defineModel<V | V[] | null>('modelValue', { default: null });
35
+
36
+ const {
37
+ isOpen,
38
+ multiple,
39
+ disabled,
40
+ readonly,
41
+ searchQuery,
42
+ filteredOptions,
43
+ highlightedIndex,
44
+ alignmentOffset,
45
+ cssAnchorName,
46
+ popupStyle,
47
+ selectedCount,
48
+ selectedList,
49
+ canSelectMore,
50
+ isSelected,
51
+ valid,
52
+ errors,
53
+ validationMessage,
54
+ triggerProps,
55
+ inputProps,
56
+ comboboxInputProps,
57
+ listboxProps,
58
+ getOptionProps,
59
+ setSearchQuery,
60
+ setHighlightedIndex,
61
+ toggle,
62
+ open,
63
+ close,
64
+ select,
65
+ clear,
66
+ focusInput,
67
+ handleKeydown,
68
+ setContainerRef,
69
+ setTriggerRef,
70
+ setDropdownRef,
71
+ setInputRef,
72
+ setListRef,
73
+ setOptionRef,
74
+ } = useHeadlessCombobox<O, V, Q>(
75
+ // The getter keeps the props reactive: reading `props` inside it tracks
76
+ // every field, and the model ref is read on each access too.
77
+ () => ({ ...props, modelValue: model.value }) as unknown as HeadlessComboboxProps<O, V, Q>,
78
+ (value) => {
79
+ model.value = value;
80
+ },
81
+ );
82
+ </script>
83
+
84
+ <template>
85
+ <slot
86
+ :is-open="isOpen"
87
+ :multiple="multiple === true"
88
+ :disabled="disabled === true"
89
+ :readonly="readonly === true"
90
+ :search-query="(searchQuery as Q | undefined)"
91
+ :filtered-options="filteredOptions"
92
+ :highlighted-index="highlightedIndex"
93
+ :alignment-offset="alignmentOffset"
94
+ :css-anchor-name="cssAnchorName"
95
+ :popup-style="popupStyle"
96
+ :selected-count="selectedCount"
97
+ :selected-list="selectedList"
98
+ :can-select-more="canSelectMore"
99
+ :is-selected="isSelected"
100
+ :valid="valid"
101
+ :errors="errors"
102
+ :validation-message="validationMessage"
103
+ :trigger-props="triggerProps"
104
+ :input-props="inputProps"
105
+ :combobox-input-props="comboboxInputProps"
106
+ :listbox-props="listboxProps"
107
+ :get-option-props="getOptionProps"
108
+ :set-search-query="setSearchQuery"
109
+ :set-highlighted-index="setHighlightedIndex"
110
+ :toggle="toggle"
111
+ :open="open"
112
+ :close="close"
113
+ :select="select"
114
+ :clear="clear"
115
+ :focus-input="focusInput"
116
+ :handle-keydown="handleKeydown"
117
+ :set-container-ref="setContainerRef"
118
+ :set-trigger-ref="setTriggerRef"
119
+ :set-dropdown-ref="setDropdownRef"
120
+ :set-input-ref="setInputRef"
121
+ :set-list-ref="setListRef"
122
+ :set-option-ref="setOptionRef"
123
+ />
124
+ </template>
package/src/index.ts ADDED
@@ -0,0 +1,15 @@
1
+ export { default as HeadlessCombobox } from './HeadlessCombobox.vue';
2
+ export { useHeadlessCombobox } from './useHeadlessCombobox';
3
+ export type {
4
+ HeadlessComboboxComboboxInputProps,
5
+ HeadlessComboboxErrorCode,
6
+ HeadlessComboboxInputProps,
7
+ HeadlessComboboxListboxProps,
8
+ HeadlessComboboxOptionProps,
9
+ HeadlessComboboxPopupStyle,
10
+ HeadlessComboboxProps,
11
+ HeadlessComboboxPropsSource,
12
+ HeadlessComboboxScope,
13
+ HeadlessComboboxSlotProps,
14
+ HeadlessComboboxTriggerProps,
15
+ } from './useHeadlessCombobox';
@@ -0,0 +1,239 @@
1
+ import type {
2
+ HeadlessComboboxProps,
3
+ HeadlessComboboxSnapshot,
4
+ } from '@pdanpdan/headless-combobox-core';
5
+ import type { ComputedRef, Ref } from 'vue';
6
+
7
+ import { createCombobox } from '@pdanpdan/headless-combobox-core';
8
+ import {
9
+ computed,
10
+ getCurrentInstance,
11
+ isRef,
12
+ nextTick,
13
+ onMounted,
14
+ onUnmounted,
15
+ shallowRef,
16
+ toRaw,
17
+ useId,
18
+ watch,
19
+ } from 'vue';
20
+
21
+ export type {
22
+ HeadlessComboboxComboboxInputProps,
23
+ HeadlessComboboxErrorCode,
24
+ HeadlessComboboxInputProps,
25
+ HeadlessComboboxListboxProps,
26
+ HeadlessComboboxOptionProps,
27
+ HeadlessComboboxPopupStyle,
28
+ HeadlessComboboxProps,
29
+ HeadlessComboboxTriggerProps,
30
+ } from '@pdanpdan/headless-combobox-core';
31
+
32
+ /** Scope exposed by the default slot: plain values, no refs. */
33
+ export type HeadlessComboboxSlotProps<O, V, Q = string> = HeadlessComboboxSnapshot<O, V, Q>;
34
+
35
+ /**
36
+ * Accepted forms for `useHeadlessCombobox` props: a plain props object (fields
37
+ * may be refs, which are unwrapped and tracked), a ref to a props object, or a
38
+ * getter. Normalized internally, so no `reactive()` wrapper needed by callers.
39
+ */
40
+ export type HeadlessComboboxPropsSource<O, V = O, Q = string>
41
+ = | HeadlessComboboxProps<O, V, Q>
42
+ | Ref<HeadlessComboboxProps<O, V, Q>>
43
+ | (() => HeadlessComboboxProps<O, V, Q>)
44
+ | { [K in keyof HeadlessComboboxProps<O, V, Q>]: HeadlessComboboxProps<O, V, Q>[ K ] | Ref<HeadlessComboboxProps<O, V, Q>[ K ]> };
45
+
46
+ /** Return value of `useHeadlessCombobox`: Vue refs for state, stable actions. */
47
+ export interface HeadlessComboboxScope<O, V, Q = string> {
48
+ // State
49
+ isOpen: Ref<boolean>;
50
+ multiple: ComputedRef<boolean>;
51
+ disabled: ComputedRef<boolean>;
52
+ readonly: ComputedRef<boolean>;
53
+ searchQuery: Ref<Q | undefined>;
54
+ filteredOptions: ComputedRef<O[]>;
55
+ highlightedIndex: Ref<number>;
56
+ alignmentOffset: Ref<number>;
57
+ cssAnchorName: string;
58
+ popupStyle: ComputedRef<HeadlessComboboxSnapshot<O, V, Q>[ 'popupStyle' ]>;
59
+ selectedCount: ComputedRef<number>;
60
+ selectedList: ComputedRef<V[]>;
61
+ canSelectMore: ComputedRef<boolean>;
62
+ isSelected: (option: O) => boolean;
63
+ valid: ComputedRef<boolean>;
64
+ errors: ComputedRef<HeadlessComboboxSnapshot<O, V, Q>[ 'errors' ]>;
65
+ validationMessage: ComputedRef<string>;
66
+ // ARIA prop bags (spread with v-bind)
67
+ triggerProps: ComputedRef<HeadlessComboboxSnapshot<O, V, Q>[ 'triggerProps' ]>;
68
+ inputProps: ComputedRef<HeadlessComboboxSnapshot<O, V, Q>[ 'inputProps' ]>;
69
+ comboboxInputProps: ComputedRef<HeadlessComboboxSnapshot<O, V, Q>[ 'comboboxInputProps' ]>;
70
+ listboxProps: ComputedRef<HeadlessComboboxSnapshot<O, V, Q>[ 'listboxProps' ]>;
71
+ getOptionProps: (option: O, index: number) => HeadlessComboboxSnapshot<O, V, Q>[ 'getOptionProps' ] extends (option: O, index: number) => infer R
72
+ ? R
73
+ : never;
74
+ // Actions
75
+ setSearchQuery: (value: Q | undefined) => void;
76
+ setHighlightedIndex: (index: number) => void;
77
+ toggle: () => void;
78
+ open: () => Promise<void>;
79
+ close: (returnFocus?: boolean) => void;
80
+ select: (option: O) => void;
81
+ clear: () => void;
82
+ focusInput: () => void;
83
+ handleKeydown: (event: Event) => void;
84
+ // Element wiring
85
+ setContainerRef: (el: unknown) => void;
86
+ setTriggerRef: (el: unknown) => void;
87
+ setDropdownRef: (el: unknown) => void;
88
+ setInputRef: (el: unknown) => void;
89
+ setListRef: (el: unknown) => void;
90
+ setOptionRef: (option: O, el: unknown) => void;
91
+ }
92
+
93
+ /** The props fields read from a props source; a fixed list keeps tracking deterministic. */
94
+ const PROP_KEYS = [
95
+ 'modelValue',
96
+ 'options',
97
+ 'multiple',
98
+ 'minLength',
99
+ 'maxLength',
100
+ 'required',
101
+ 'disabled',
102
+ 'readonly',
103
+ 'closeOnSelect',
104
+ 'closeOnClickOutside',
105
+ 'clickOutsideFilter',
106
+ 'selectOnTab',
107
+ 'optionValue',
108
+ 'optionLabel',
109
+ 'optionFilter',
110
+ 'id',
111
+ 'alignSelected',
112
+ 'inputOnOpen',
113
+ 'errorMessages',
114
+ ] as const;
115
+
116
+ function resolveProps<O, V, Q>(source: HeadlessComboboxPropsSource<O, V, Q>): HeadlessComboboxProps<O, V, Q> {
117
+ const base = isRef(source)
118
+ ? source.value
119
+ : typeof source === 'function'
120
+ ? source()
121
+ : source;
122
+ const resolved: Record<string, unknown> = {};
123
+ for (const key of PROP_KEYS) {
124
+ const value = (base as Record<string, unknown>)[ key ];
125
+ resolved[ key ] = isRef(value)
126
+ ? value.value
127
+ : value;
128
+ }
129
+ return resolved as unknown as HeadlessComboboxProps<O, V, Q>;
130
+ }
131
+
132
+ /**
133
+ * Vue adapter for the framework-independent combobox core.
134
+ *
135
+ * Returns Vue refs backed by the core snapshot. Call it from `setup()`; it
136
+ * mounts the document listeners and uses Vue's `useId()` for default ids.
137
+ */
138
+ export function useHeadlessCombobox<O, V = O, Q = string>(
139
+ propsSource: HeadlessComboboxPropsSource<O, V, Q>,
140
+ emit: (value: V | V[] | null) => void,
141
+ ): HeadlessComboboxScope<O, V, Q> {
142
+ const resolvedProps = computed(() => resolveProps(propsSource));
143
+ const instance = getCurrentInstance();
144
+ const generatedId = instance
145
+ ? useId()
146
+ : undefined;
147
+
148
+ const store = createCombobox<O, V, Q>({
149
+ props: resolvedProps.value,
150
+ onChange: emit,
151
+ runtime: {
152
+ nextTick: () => nextTick(),
153
+ unwrap: (value) => toRaw(value),
154
+ getDocument: () => (typeof document === 'undefined'
155
+ ? null
156
+ : document),
157
+ ...(generatedId != null
158
+ ? {
159
+ createId: () => generatedId,
160
+ }
161
+ : {}),
162
+ },
163
+ });
164
+
165
+ const snapshot = shallowRef(store.getSnapshot());
166
+ const unsubscribe = store.subscribe(() => {
167
+ snapshot.value = store.getSnapshot();
168
+ });
169
+
170
+ // Props may be Vue-reactive (component props) or contain refs (composable
171
+ // callers). The computed tracks both; push each change into the core.
172
+ watch(resolvedProps, (next) => store.setProps(next), { immediate: true });
173
+
174
+ if (instance) {
175
+ onMounted(() => store.mount());
176
+ onUnmounted(() => {
177
+ unsubscribe();
178
+ store.destroy();
179
+ });
180
+ } else {
181
+ store.mount();
182
+ }
183
+
184
+ const isSelected = (option: O) => store.getSnapshot().isSelected(option);
185
+ const getOptionProps = (option: O, index: number) =>
186
+ store.getSnapshot().getOptionProps(option, index);
187
+
188
+ return {
189
+ isOpen: computed({
190
+ get: () => snapshot.value.isOpen,
191
+ set: (value) => store.setState({ isOpen: value }),
192
+ }),
193
+ multiple: computed(() => snapshot.value.multiple),
194
+ disabled: computed(() => snapshot.value.disabled),
195
+ readonly: computed(() => snapshot.value.readonly),
196
+ searchQuery: computed({
197
+ get: () => snapshot.value.searchQuery,
198
+ set: (value) => store.getSnapshot().setSearchQuery(value),
199
+ }),
200
+ filteredOptions: computed(() => snapshot.value.filteredOptions),
201
+ highlightedIndex: computed({
202
+ get: () => snapshot.value.highlightedIndex,
203
+ set: (value) => store.setState({ highlightedIndex: value }),
204
+ }),
205
+ alignmentOffset: computed({
206
+ get: () => snapshot.value.alignmentOffset,
207
+ set: (value) => store.setState({ alignmentOffset: value }),
208
+ }),
209
+ cssAnchorName: snapshot.value.cssAnchorName,
210
+ popupStyle: computed(() => snapshot.value.popupStyle),
211
+ selectedCount: computed(() => snapshot.value.selectedCount),
212
+ selectedList: computed(() => snapshot.value.selectedList),
213
+ canSelectMore: computed(() => snapshot.value.canSelectMore),
214
+ isSelected,
215
+ valid: computed(() => snapshot.value.valid),
216
+ errors: computed(() => snapshot.value.errors),
217
+ validationMessage: computed(() => snapshot.value.validationMessage),
218
+ triggerProps: computed(() => snapshot.value.triggerProps),
219
+ inputProps: computed(() => snapshot.value.inputProps),
220
+ comboboxInputProps: computed(() => snapshot.value.comboboxInputProps),
221
+ listboxProps: computed(() => snapshot.value.listboxProps),
222
+ getOptionProps,
223
+ setSearchQuery: (value) => store.getSnapshot().setSearchQuery(value),
224
+ setHighlightedIndex: (index) => store.getSnapshot().setHighlightedIndex(index),
225
+ toggle: () => store.getSnapshot().toggle(),
226
+ open: () => store.getSnapshot().open(),
227
+ close: (returnFocus) => store.getSnapshot().close(returnFocus),
228
+ select: (option) => store.getSnapshot().select(option),
229
+ clear: () => store.getSnapshot().clear(),
230
+ focusInput: () => store.getSnapshot().focusInput(),
231
+ handleKeydown: (event) => store.getSnapshot().handleKeydown(event),
232
+ setContainerRef: (el) => store.getSnapshot().setContainerRef(el),
233
+ setTriggerRef: (el) => store.getSnapshot().setTriggerRef(el),
234
+ setDropdownRef: (el) => store.getSnapshot().setDropdownRef(el),
235
+ setInputRef: (el) => store.getSnapshot().setInputRef(el),
236
+ setListRef: (el) => store.getSnapshot().setListRef(el),
237
+ setOptionRef: (option, el) => store.getSnapshot().setOptionRef(option, el),
238
+ };
239
+ }