feat: add CAutoComplete component with basic functionality and remote search support
- Implemented CAutoComplete.vue with props for modelValue, options, debounceWait, loading, and more. - Added search functionality with debounce for remote city suggestions. - Created AutoComplete.vue page for documentation and examples. - Updated CSelect.vue to support remote searching and caching of selected values. - Enhanced CMultiSelect.vue to handle object comparisons for selected values.main
fandi.susanto.bts
1 month ago
parent
3a8489d818
commit
18eae8fa23
@ -0,0 +1,254 @@
|
||||
<script setup lang="ts">
|
||||
import { onBeforeUnmount, ref } from 'vue'
|
||||
|
||||
import { CAutoComplete, CFormField, CSeparator } from '@/index'
|
||||
import CCodeBlock from '@/documentation/CCodeBlock.vue'
|
||||
|
||||
const cities = [
|
||||
'Bandung',
|
||||
'Bekasi',
|
||||
'Bogor',
|
||||
'Denpasar',
|
||||
'Jakarta',
|
||||
'Makassar',
|
||||
'Medan',
|
||||
'Semarang',
|
||||
'Surabaya',
|
||||
'Yogyakarta',
|
||||
]
|
||||
|
||||
const destination = ref('Jakarta')
|
||||
const department = ref('')
|
||||
const smallValue = ref('Bandung')
|
||||
const largeValue = ref('Surabaya')
|
||||
const remoteCity = ref('')
|
||||
const remoteOptions = ref<string[]>([])
|
||||
const remoteLoading = ref(false)
|
||||
let remoteTimer: ReturnType<typeof setTimeout> | undefined
|
||||
|
||||
function searchCities(query: string) {
|
||||
if (remoteTimer !== undefined) clearTimeout(remoteTimer)
|
||||
if (!query) {
|
||||
remoteOptions.value = []
|
||||
remoteLoading.value = false
|
||||
return
|
||||
}
|
||||
|
||||
remoteLoading.value = true
|
||||
remoteTimer = setTimeout(() => {
|
||||
remoteOptions.value = cities.filter((city) =>
|
||||
city.toLocaleLowerCase().includes(query.toLocaleLowerCase()),
|
||||
)
|
||||
remoteLoading.value = false
|
||||
}, 600)
|
||||
}
|
||||
|
||||
onBeforeUnmount(() => {
|
||||
if (remoteTimer !== undefined) clearTimeout(remoteTimer)
|
||||
})
|
||||
|
||||
const basicJavaScript = `const cities = [
|
||||
'Bandung',
|
||||
'Bekasi',
|
||||
'Bogor',
|
||||
'Denpasar',
|
||||
'Jakarta',
|
||||
'Makassar',
|
||||
'Medan',
|
||||
'Semarang',
|
||||
'Surabaya',
|
||||
'Yogyakarta',
|
||||
]
|
||||
|
||||
const destination = ref('Jakarta')`
|
||||
|
||||
const basicUsage = `<CAutoComplete
|
||||
v-model="destination"
|
||||
:options="cities"
|
||||
placeholder="Enter a destination"
|
||||
clearable
|
||||
/>`
|
||||
|
||||
const arbitraryUsage = `<CAutoComplete
|
||||
v-model="department"
|
||||
:options="['Sales', 'Finance', 'Operations']"
|
||||
placeholder="Choose or enter a department"
|
||||
/>
|
||||
|
||||
<p>Current value: {{ department }}</p>`
|
||||
|
||||
const remoteJavaScript = `const suggestions = ref([])
|
||||
const loading = ref(false)
|
||||
let controller
|
||||
|
||||
async function searchCustomers(query) {
|
||||
controller?.abort()
|
||||
|
||||
if (!query) {
|
||||
suggestions.value = []
|
||||
loading.value = false
|
||||
return
|
||||
}
|
||||
|
||||
const request = new AbortController()
|
||||
controller = request
|
||||
loading.value = true
|
||||
|
||||
try {
|
||||
const response = await fetch(
|
||||
\`/api/customers?q=\${encodeURIComponent(query)}\`,
|
||||
{ signal: request.signal },
|
||||
)
|
||||
suggestions.value = await response.json()
|
||||
} catch (error) {
|
||||
if (error.name !== 'AbortError') throw error
|
||||
} finally {
|
||||
if (controller === request) loading.value = false
|
||||
}
|
||||
}`
|
||||
|
||||
const remoteUsage = `<CAutoComplete
|
||||
v-model="customer"
|
||||
:options="suggestions"
|
||||
:loading="loading"
|
||||
:debounce-wait="350"
|
||||
:min-search-length="2"
|
||||
@search="searchCustomers"
|
||||
/>`
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<article class="form-page">
|
||||
<header class="page-header">
|
||||
<div><p class="category">Forms</p><h1>Auto Complete</h1></div>
|
||||
<p>
|
||||
<code>CAutoComplete</code> is a text input with string suggestions. Users may select a
|
||||
suggestion or keep any arbitrary text they enter.
|
||||
</p>
|
||||
</header>
|
||||
<CSeparator />
|
||||
|
||||
<section class="section">
|
||||
<h2>String suggestions</h2>
|
||||
<p>
|
||||
Pass a simple array of strings through <code>options</code>. Matching is case-insensitive
|
||||
and checks the entire string. Because the options have no object mapping, the API does not
|
||||
need <code>option-label</code>, <code>option-value</code>, or <code>option-key</code>.
|
||||
</p>
|
||||
<div class="preview">
|
||||
<CFormField label="Destination">
|
||||
<CAutoComplete
|
||||
v-model="destination"
|
||||
:options="cities"
|
||||
placeholder="Enter a destination"
|
||||
clearable
|
||||
/>
|
||||
</CFormField>
|
||||
<span>Current value: {{ destination }}</span>
|
||||
</div>
|
||||
<CCodeBlock class="code-sample" :code="basicJavaScript" language="javascript" />
|
||||
<CCodeBlock class="code-sample" :code="basicUsage" />
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<h2>Arbitrary values</h2>
|
||||
<p>
|
||||
Typing updates <code>v-model</code> immediately, even when the text is absent from
|
||||
<code>options</code>. Suggestions assist entry but do not constrain it. The
|
||||
<code>select</code> event is emitted only when a listed suggestion is explicitly chosen.
|
||||
</p>
|
||||
<div class="preview">
|
||||
<CFormField label="Department" hint="You may enter a department not shown in the list.">
|
||||
<CAutoComplete
|
||||
v-model="department"
|
||||
:options="['Sales', 'Finance', 'Operations']"
|
||||
placeholder="Choose or enter a department"
|
||||
/>
|
||||
</CFormField>
|
||||
<span>Current value: {{ department }}</span>
|
||||
</div>
|
||||
<CCodeBlock class="code-sample" :code="arbitraryUsage" />
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<h2>Keyboard usage</h2>
|
||||
<p>
|
||||
Use Arrow Up or Arrow Down to move through suggestions, Enter to accept the highlighted
|
||||
suggestion, and Escape to close the list without changing the current text. Tab keeps the
|
||||
arbitrary value and moves focus normally.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<h2>Remote suggestions</h2>
|
||||
<p>
|
||||
The component does not make network requests itself. After the user pauses typing,
|
||||
<code>search</code> emits the trimmed query and the parent replaces <code>options</code>.
|
||||
<code>debounce-wait</code> controls that pause, while <code>min-search-length</code> prevents
|
||||
short queries from starting a search.
|
||||
</p>
|
||||
<p>
|
||||
When the query drops below the minimum, an empty search is emitted immediately so the
|
||||
parent can cancel work and clear stale results. Set <code>loading</code> while awaiting the
|
||||
response; users can continue typing while the spinner is visible.
|
||||
</p>
|
||||
<div class="preview">
|
||||
<CFormField label="Remote city search" hint="Type at least two characters.">
|
||||
<CAutoComplete
|
||||
v-model="remoteCity"
|
||||
:options="remoteOptions"
|
||||
:loading="remoteLoading"
|
||||
:debounce-wait="350"
|
||||
:min-search-length="2"
|
||||
placeholder="Search cities"
|
||||
clearable
|
||||
@search="searchCities"
|
||||
/>
|
||||
</CFormField>
|
||||
<span>Current value: {{ remoteCity }}</span>
|
||||
</div>
|
||||
<CCodeBlock class="code-sample" :code="remoteJavaScript" language="javascript" />
|
||||
<CCodeBlock class="code-sample" :code="remoteUsage" />
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<h2>Sizes and states</h2>
|
||||
<div class="preview">
|
||||
<CFormField label="Small (26px)">
|
||||
<CAutoComplete v-model="smallValue" :options="cities" size="small" />
|
||||
</CFormField>
|
||||
<CFormField label="Large (34px)">
|
||||
<CAutoComplete v-model="largeValue" :options="cities" size="large" />
|
||||
</CFormField>
|
||||
<CFormField label="Disabled">
|
||||
<CAutoComplete model-value="Jakarta" :options="cities" disabled />
|
||||
</CFormField>
|
||||
<CFormField label="Invalid">
|
||||
<CAutoComplete model-value="Unknown office" :options="cities" invalid />
|
||||
</CFormField>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<h2>Properties and events</h2>
|
||||
<dl class="property-list">
|
||||
<div><dt><code>model-value</code></dt><dd>Current string, including values absent from the suggestion list.</dd></div>
|
||||
<div><dt><code>options</code></dt><dd>Array of strings used as suggestions.</dd></div>
|
||||
<div><dt><code>debounce-wait</code></dt><dd>Milliseconds to wait before emitting a non-empty <code>search</code>. Defaults to <code>300</code>.</dd></div>
|
||||
<div><dt><code>loading</code></dt><dd>Shows remote loading feedback without disabling text entry.</dd></div>
|
||||
<div><dt><code>min-search-length</code></dt><dd>Minimum trimmed query length required before emitting a non-empty search.</dd></div>
|
||||
<div><dt><code>clearable</code></dt><dd>Adds a compact button that clears the value to an empty string.</dd></div>
|
||||
<div><dt><code>placeholder</code></dt><dd>Text displayed while the value is empty.</dd></div>
|
||||
<div><dt><code>size</code></dt><dd><code>small</code>, <code>medium</code>, or <code>large</code>.</dd></div>
|
||||
<div><dt><code>disabled</code></dt><dd>Disables input and focus.</dd></div>
|
||||
<div><dt><code>required</code></dt><dd>Applies native required validation.</dd></div>
|
||||
<div><dt><code>invalid</code></dt><dd>Applies invalid styling and <code>aria-invalid</code>.</dd></div>
|
||||
<div><dt><code>search</code></dt><dd>Emitted with the debounced query, or immediately with an empty string when below the minimum.</dd></div>
|
||||
<div><dt><code>select</code></dt><dd>Emitted with the string when a suggestion is explicitly selected.</dd></div>
|
||||
<div><dt><code>clear</code></dt><dd>Emitted after the clear button resets the value.</dd></div>
|
||||
</dl>
|
||||
</section>
|
||||
</article>
|
||||
</template>
|
||||
|
||||
<style scoped lang="scss" src="./form-demo.scss"></style>
|
||||
Loading…
Reference in New Issue