421 lines
25 KiB
Plaintext
421 lines
25 KiB
Plaintext
page ComboBoxcomponent {
|
|
seo {
|
|
title = "ComboBox component"
|
|
description = "Editable autocomplete combobox with local and remote suggestions."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<SkipLink label="Skip to content" href="#main" class="docs-skip-link" />
|
|
<header class="topbar">
|
|
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
|
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
|
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.5.0</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
|
</header>
|
|
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
|
|
<main class="portal-main docs-layout component-detail-page"><article id="main" class="documentation prose standalone"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/components">Components</a><span>/</span><span aria-current="page">ComboBox</span></nav><section class="doc-intro"><span class="eyebrow">advanced-forms component</span><h1>ComboBox</h1><p>Editable autocomplete combobox with local and remote suggestions.</p><div class="doc-meta"><span>@wrnexus/ui 0.5.0</span><span>41 props</span><span>0 slots</span><span>8 events</span></div></section><section id="usage"><h2>Usage</h2><p>Components are auto-discovered. Use the component directly in any <code>.wrn</code> view:</p><pre data-language="wrn"><code><ComboBox
|
|
size="default"
|
|
color="primary"
|
|
label="ComboBox"
|
|
name="name"
|
|
value="value"
|
|
/></code></pre><p>Legacy mount name: <code>data-component="ComboBox"</code>.</p></section><section id="props"><h2>Props and attributes</h2><div class="table-wrap"><table><thead><tr><th>Prop</th><th>Type</th><th>Requirement</th><th>Default</th></tr></thead><tbody><tr><td><code>size</code></td><td><code>string</code></td><td>Optional</td><td><code>"default"</code></td></tr><tr><td><code>color</code></td><td><code>string</code></td><td>Optional</td><td><code>"primary"</code></td></tr><tr><td><code>label</code></td><td><code>string</code></td><td>Optional</td><td><code>"ComboBox"</code></td></tr><tr><td><code>name</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>value</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>options</code></td><td><code>string</code></td><td>Optional</td><td><code>[]</code></td></tr><tr><td><code>groups</code></td><td><code>string</code></td><td>Optional</td><td><code>[]</code></td></tr><tr><td><code>placeholder</code></td><td><code>string</code></td><td>Optional</td><td><code>"Search or select an option"</code></td></tr><tr><td><code>searchPlaceholder</code></td><td><code>string</code></td><td>Optional</td><td><code>"Start typing…"</code></td></tr><tr><td><code>clearable</code></td><td><code>boolean</code></td><td>Optional</td><td><code>true</code></td></tr><tr><td><code>allowCustomValue</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>disabled</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>required</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>invalid</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>validationMessage</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>helpText</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>loading</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>loadingLabel</code></td><td><code>string</code></td><td>Optional</td><td><code>"Loading suggestions…"</code></td></tr><tr><td><code>emptyLabel</code></td><td><code>string</code></td><td>Optional</td><td><code>"No matching options"</code></td></tr><tr><td><code>clearLabel</code></td><td><code>string</code></td><td>Optional</td><td><code>"Clear value"</code></td></tr><tr><td><code>toggleLabel</code></td><td><code>string</code></td><td>Optional</td><td><code>"Toggle suggestions"</code></td></tr><tr><td><code>searchMode</code></td><td><code>string</code></td><td>Optional</td><td><code>"contains"</code></td></tr><tr><td><code>searchFields</code></td><td><code>string</code></td><td>Optional</td><td><code>"label,description"</code></td></tr><tr><td><code>minSearchLength</code></td><td><code>number</code></td><td>Optional</td><td><code>0</code></td></tr><tr><td><code>searchResultLimit</code></td><td><code>number</code></td><td>Optional</td><td><code>0</code></td></tr><tr><td><code>optionTemplate</code></td><td><code>string</code></td><td>Optional</td><td><code>"default"</code></td></tr><tr><td><code>defaultOpen</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>closeOnSelect</code></td><td><code>boolean</code></td><td>Optional</td><td><code>true</code></td></tr><tr><td><code>fixed</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>placement</code></td><td><code>string</code></td><td>Optional</td><td><code>"bottom"</code></td></tr><tr><td><code>autocomplete</code></td><td><code>string</code></td><td>Optional</td><td><code>"off"</code></td></tr><tr><td><code>remote</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>remoteUrl</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>remoteQueryParam</code></td><td><code>string</code></td><td>Optional</td><td><code>"q"</code></td></tr><tr><td><code>remoteDebounce</code></td><td><code>number</code></td><td>Optional</td><td><code>250</code></td></tr><tr><td><code>remoteAutoLoad</code></td><td><code>boolean</code></td><td>Optional</td><td><code>true</code></td></tr><tr><td><code>infinite</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>hasMore</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>page</code></td><td><code>number</code></td><td>Optional</td><td><code>1</code></td></tr><tr><td><code>loadMoreLabel</code></td><td><code>string</code></td><td>Optional</td><td><code>"Load more"</code></td></tr><tr><td><code>class</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr></tbody></table></div></section><section id="slots"><h2>Slots</h2><p>This component does not declare a slot.</p></section><section id="events"><h2>Events</h2><ul><li><code>search</code></li><li><code>select</code></li><li><code>change</code></li><li><code>clear</code></li><li><code>open</code></li><li><code>close</code></li><li><code>load</code></li><li><code>error</code></li></ul></section><section id="source"><h2>Source contract</h2><p>Installed source: <code>components/Combobox.wrn</code></p><pre data-language="wrn"><code>component ComboBox {
|
|
props {
|
|
size = "default"
|
|
color = "primary"
|
|
label = "ComboBox"
|
|
name = ""
|
|
value = ""
|
|
options = []
|
|
groups = []
|
|
placeholder = "Search or select an option"
|
|
searchPlaceholder = "Start typing…"
|
|
clearable = true
|
|
allowCustomValue = false
|
|
disabled = false
|
|
required = false
|
|
invalid = false
|
|
validationMessage = ""
|
|
helpText = ""
|
|
loading = false
|
|
loadingLabel = "Loading suggestions…"
|
|
emptyLabel = "No matching options"
|
|
clearLabel = "Clear value"
|
|
toggleLabel = "Toggle suggestions"
|
|
searchMode = "contains"
|
|
searchFields = "label,description"
|
|
minSearchLength = 0
|
|
searchResultLimit = 0
|
|
optionTemplate = "default"
|
|
defaultOpen = false
|
|
closeOnSelect = true
|
|
fixed = false
|
|
placement = "bottom"
|
|
autocomplete = "off"
|
|
remote = false
|
|
remoteUrl = ""
|
|
remoteQueryParam = "q"
|
|
remoteDebounce = 250
|
|
remoteAutoLoad = true
|
|
infinite = false
|
|
hasMore = false
|
|
page = 1
|
|
loadMoreLabel = "Load more"
|
|
class = ""
|
|
@event search = function
|
|
@event select = function
|
|
@event change = function
|
|
@event clear = function
|
|
@event open = function
|
|
@event close = function
|
|
@event load = function
|
|
@event error = function
|
|
}
|
|
|
|
state open = defaultOpen
|
|
state query = ""
|
|
state selectedValue = value
|
|
state activeIndex = -1
|
|
|
|
functions {
|
|
function allOptions() {
|
|
return [...groups.flatMap((group) => group.options || []), ...options]
|
|
}
|
|
|
|
function searchableText(option) {
|
|
return ((option.label || "") + " " + (option.description || "")).toLowerCase()
|
|
}
|
|
|
|
function matches(option) {
|
|
if (!query || query.length < minSearchLength) {
|
|
return true
|
|
}
|
|
if (searchMode === "startsWith") {
|
|
return searchableText(option).startsWith(query.toLowerCase())
|
|
}
|
|
if (searchMode === "exact") {
|
|
return searchableText(option) === query.toLowerCase()
|
|
}
|
|
return searchableText(option).includes(query.toLowerCase())
|
|
}
|
|
|
|
function matchingOptions(list) {
|
|
return list.filter((option) => matches(option))
|
|
}
|
|
|
|
function visibleOptions(list) {
|
|
if (searchResultLimit > 0) {
|
|
return matchingOptions(list).slice(0, searchResultLimit)
|
|
}
|
|
return matchingOptions(list)
|
|
}
|
|
|
|
function flatVisibleOptions() {
|
|
return visibleOptions(allOptions())
|
|
}
|
|
|
|
function isSelected(option) {
|
|
return selectedValue === option.value
|
|
}
|
|
|
|
function selectedOptions() {
|
|
return allOptions().filter((option) => isSelected(option))
|
|
}
|
|
|
|
function selectedText() {
|
|
return selectedOptions().length ? selectedOptions()[0].label : selectedValue
|
|
}
|
|
|
|
function inputText() {
|
|
return query || selectedText()
|
|
}
|
|
|
|
function shouldShowDropdown() {
|
|
if (!open) {
|
|
return false
|
|
}
|
|
if (loading) {
|
|
return true
|
|
}
|
|
if (remote && query.length !== 0 && query.length < minSearchLength) {
|
|
return true
|
|
}
|
|
if (flatVisibleOptions().length) {
|
|
return true
|
|
}
|
|
return infinite && hasMore
|
|
}
|
|
|
|
function canSelect(option) {
|
|
return !option.disabled
|
|
}
|
|
|
|
function chooseOption(option) {
|
|
if (!canSelect(option)) {
|
|
return
|
|
}
|
|
selectedValue = option.value
|
|
query = option.label
|
|
activeIndex = optionIndex(option)
|
|
if (closeOnSelect) {
|
|
open = false
|
|
}
|
|
}
|
|
|
|
function updateQuery(event) {
|
|
query = event.target.value
|
|
selectedValue = allowCustomValue ? event.target.value : ""
|
|
open = true
|
|
activeIndex = flatVisibleOptions().length ? 0 : -1
|
|
}
|
|
|
|
function clearValue(event) {
|
|
if (event) {
|
|
event.stopPropagation()
|
|
}
|
|
query = ""
|
|
selectedValue = ""
|
|
activeIndex = -1
|
|
open = false
|
|
}
|
|
|
|
function openDropdown() {
|
|
if (!disabled) {
|
|
open = true
|
|
activeIndex = flatVisibleOptions().length ? 0 : -1
|
|
}
|
|
}
|
|
|
|
function closeDropdown() {
|
|
open = false
|
|
}
|
|
|
|
function toggle() {
|
|
if (open) {
|
|
closeDropdown()
|
|
} else {
|
|
openDropdown()
|
|
}
|
|
}
|
|
|
|
function setValue(nextValue) {
|
|
selectedValue = nextValue
|
|
query = ""
|
|
}
|
|
|
|
function moveActive(direction) {
|
|
if (!flatVisibleOptions().length) {
|
|
return
|
|
}
|
|
activeIndex = (activeIndex + direction + flatVisibleOptions().length) % flatVisibleOptions().length
|
|
}
|
|
|
|
function handleKeydown(event) {
|
|
if (disabled) {
|
|
return
|
|
}
|
|
if (event.key === "ArrowDown") {
|
|
event.preventDefault()
|
|
openDropdown()
|
|
moveActive(1)
|
|
} else if (event.key === "ArrowUp") {
|
|
event.preventDefault()
|
|
openDropdown()
|
|
moveActive(-1)
|
|
} else if (event.key === "Enter" && open && activeIndex >= 0) {
|
|
event.preventDefault()
|
|
chooseOption(flatVisibleOptions()[activeIndex])
|
|
} else if (event.key === "Escape") {
|
|
closeDropdown()
|
|
} else if (event.key === "Home" && open) {
|
|
event.preventDefault()
|
|
activeIndex = 0
|
|
} else if (event.key === "End" && open) {
|
|
event.preventDefault()
|
|
activeIndex = flatVisibleOptions().length - 1
|
|
}
|
|
}
|
|
|
|
function optionIndex(option) {
|
|
return flatVisibleOptions().findIndex((item) => item.value === option.value)
|
|
}
|
|
}
|
|
|
|
view {
|
|
<div
|
|
class="wire-next wire-next--color-{color} wire-next--size-{size} wire-next--advanced-select wire-next--combobox {open ? 'wire-next--open' : ''} {fixed ? 'wire-next--advanced-select-fixed' : ''} {invalid ? 'wire-next--invalid' : ''} {disabled ? 'wire-next--disabled' : ''} {class}"
|
|
data-placement="{placement}"
|
|
data-search-mode="{searchMode}"
|
|
data-remote="{remote ? 'true' : 'false'}"
|
|
data-remote-url="{remoteUrl}"
|
|
data-remote-query-param="{remoteQueryParam}"
|
|
data-remote-debounce="{remoteDebounce}"
|
|
data-remote-auto-load="{remoteAutoLoad ? 'true' : 'false'}"
|
|
data-infinite="{infinite ? 'true' : 'false'}"
|
|
data-page="{page}"
|
|
data-wrn-select
|
|
data-wrn-combobox
|
|
@focusout="if (!event.currentTarget.contains(event.relatedTarget)) { closeDropdown() }"
|
|
>
|
|
<label id="{name}-label" for="{name}-input">{label}</label>
|
|
<div class="wire-next__select-control wire-next__combobox-control">
|
|
<span class="wire-next__search-icon icon-[lucide--search]" aria-hidden="true">
|
|
</span>
|
|
<input
|
|
{...attrs}
|
|
id="{name}-input"
|
|
class="wire-next__select-trigger wire-next__combobox-input"
|
|
type="text"
|
|
role="combobox"
|
|
name="{allowCustomValue ? name : ''}"
|
|
value="{inputText()}"
|
|
placeholder="{placeholder}"
|
|
autocomplete="{autocomplete}"
|
|
aria-autocomplete="list"
|
|
aria-haspopup="listbox"
|
|
aria-expanded="{open}"
|
|
aria-controls="{name}-listbox"
|
|
aria-labelledby="{name}-label"
|
|
aria-invalid="{invalid}"
|
|
disabled="{disabled}"
|
|
required="{required && allowCustomValue}"
|
|
@focus="openDropdown()"
|
|
@click="openDropdown()"
|
|
@input="updateQuery(event)"
|
|
@keydown="handleKeydown(event)"
|
|
/>
|
|
<button
|
|
type="button"
|
|
class="wire-next__clear-select"
|
|
data-show="clearable && inputText() && !disabled"
|
|
aria-label="{clearLabel}"
|
|
title="{clearLabel}"
|
|
@click="clearValue(event)"
|
|
>
|
|
<span class="icon-[lucide--x]" aria-hidden="true">
|
|
</span>
|
|
</button>
|
|
<button
|
|
type="button"
|
|
class="wire-next__combobox-toggle"
|
|
aria-label="{toggleLabel}"
|
|
tabindex="-1"
|
|
disabled="{disabled}"
|
|
@click="toggle()"
|
|
>
|
|
<span class="wire-next__select-chevron icon-[lucide--chevrons-up-down]" aria-hidden="true">
|
|
</span>
|
|
</button>
|
|
</div>
|
|
<div
|
|
class="wire-next__select-dropdown {fixed ? 'wire-next__select-dropdown--fixed' : ''}"
|
|
data-show="shouldShowDropdown()"
|
|
style="{shouldShowDropdown() ? '' : 'display: none'}"
|
|
>
|
|
<div
|
|
class="wire-next__select-message"
|
|
data-show="remote && query.length !== 0 && query.length < minSearchLength"
|
|
>Enter at least {minSearchLength} characters.</div>
|
|
<div class="wire-next__select-message" data-show="loading" role="status">
|
|
<i class="wire-spinner wire-spinner--inline" aria-hidden="true">
|
|
</i>
|
|
{loadingLabel}
|
|
</div>
|
|
<div
|
|
id="{name}-listbox"
|
|
class="wire-next__select-list"
|
|
data-show="(!remote || (query.length === 0 && remoteAutoLoad) || query.length >= minSearchLength) && !loading"
|
|
role="listbox"
|
|
>
|
|
{#each groups as group}
|
|
{#if visibleOptions(group.options || []).length}
|
|
<div class="wire-next__option-group" role="group" aria-label="{group.label}">
|
|
<div class="wire-next__group-label">{group.label}</div>
|
|
{#each group.options || [] as option}
|
|
<button
|
|
type="button"
|
|
class="wire-next__select-option {isSelected(option) ? 'wire-next__select-option--selected' : ''} {optionIndex(option) === activeIndex ? 'wire-next__select-option--active' : ''}"
|
|
data-option-value="{option.value}"
|
|
data-show="matches(option)"
|
|
role="option"
|
|
aria-selected="{isSelected(option)}"
|
|
disabled="{!canSelect(option)}"
|
|
@mouseenter="activeIndex = optionIndex(option)"
|
|
@mousedown="event.preventDefault()"
|
|
@click="chooseOption(option)"
|
|
>
|
|
{#if optionTemplate === "icon" && option.icon}<i class="{option.icon}" aria-hidden="true">
|
|
</i>{/if}
|
|
{#if optionTemplate === "avatar" && option.avatar}<img src="{option.avatar}" alt="" />{/if}
|
|
{#if optionTemplate === "color" && option.color}<i class="wire-next__color-dot" style="--option-color: {option.color}">
|
|
</i>{/if}
|
|
<span>
|
|
<strong>{option.label}</strong>{#if option.description}<small>{option.description}</small>{/if}</span>
|
|
<i class="wire-next__check icon-[lucide--check]" data-show="isSelected(option)" aria-hidden="true">
|
|
</i>
|
|
</button>
|
|
{/each}
|
|
</div>
|
|
{/if}
|
|
{/each}
|
|
|
|
{#each options as option}
|
|
<button
|
|
type="button"
|
|
class="wire-next__select-option {isSelected(option) ? 'wire-next__select-option--selected' : ''} {optionIndex(option) === activeIndex ? 'wire-next__select-option--active' : ''}"
|
|
data-option-value="{option.value}"
|
|
data-show="matches(option)"
|
|
role="option"
|
|
aria-selected="{isSelected(option)}"
|
|
disabled="{!canSelect(option)}"
|
|
@mouseenter="activeIndex = optionIndex(option)"
|
|
@mousedown="event.preventDefault()"
|
|
@click="chooseOption(option)"
|
|
>
|
|
{#if optionTemplate === "icon" && option.icon}<i class="{option.icon}" aria-hidden="true">
|
|
</i>{/if}
|
|
{#if optionTemplate === "avatar" && option.avatar}<img src="{option.avatar}" alt="" />{/if}
|
|
{#if optionTemplate === "color" && option.color}<i class="wire-next__color-dot" style="--option-color: {option.color}">
|
|
</i>{/if}
|
|
<span>
|
|
<strong>{option.label}</strong>{#if option.description}<small>{option.description}</small>{/if}</span>
|
|
<i class="wire-next__check icon-[lucide--check]" data-show="isSelected(option)" aria-hidden="true">
|
|
</i>
|
|
</button>
|
|
{/each}
|
|
</div>
|
|
<button
|
|
type="button"
|
|
class="wire-next__load-more"
|
|
data-wrn-select-load-more
|
|
data-show="infinite && hasMore"
|
|
>{loadMoreLabel}</button>
|
|
</div>
|
|
|
|
{#if !allowCustomValue}
|
|
<input
|
|
type="hidden"
|
|
name="{name}"
|
|
value="{selectedValue}"
|
|
required="{required}"
|
|
data-error="{name}"
|
|
aria-describedby="{validationMessage ? `${name}-validation` : helpText ? `${name}-help` : ''}"
|
|
/>
|
|
{/if}
|
|
|
|
{#if helpText && !validationMessage}<small id="{name}-help">{helpText}</small>{/if}
|
|
<small
|
|
id="{name}-validation"
|
|
class="wire-next__validation"
|
|
data-error="{name}"
|
|
>{validationMessage}</small>
|
|
</div>
|
|
}
|
|
}
|
|
</code></pre></section></article><aside class="on-this-page"><h2>On this page</h2><nav><a href="#usage">Usage</a><a href="#props">Props and attributes</a><a href="#slots">Slots</a><a href="#events">Events</a><a href="#source">Source contract</a></nav></aside></main>
|
|
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.5.0</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
|
|
<BackToTop />
|
|
</div>
|
|
}
|
|
}
|