@vue-interface/searchable-select-field 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Justin Kimbrell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,54 @@
+# Searchable Select Field
+
+The `searchable-select-field` component provides flexible and customizable searchable input field with customizable sizes, states, and colors.
+
+## Installation
+
+```bash
+pnpm i @vue-interface/searchable-select-field
+```
+
+```bash
+yarn add @vue-interface/searchable-select-field
+```
+
+```bash
+npm i @vue-interface/searchable-select-field
+```
+
+```bash
+bun i @vue-interface/searchable-select-field
+```
+
+## Basic Usage
+
+```vue
+<SearchableSelectField v-model="selected" :options="languages"></SearchableSelectField>
+<SearchableSelectField :options="options" placeholder="Type to search..." label="Placeholder"></SearchableSelectField>
+<SearchableSelectField :options="options" label="Descriptive Text Field" help-text="Some helpful text goes here."></SearchableSelectField>
+<SearchableSelectField :options="options" label="Readonly" placeholder="Type something here..." readonly></SearchableSelectField>
+<SearchableSelectField :options="options" label="Disabled" disabled></SearchableSelectField>
+<SearchableSelectField :options="options" placeholder="Disabled" label="Disabled (Placeholder)" disabled></SearchableSelectField>
+```
+
+```ts
+import SearchableSelectField from '../src/SearchableSelectField.vue';
+
+const value = ref()
+const selected = ref()
+const options = [
+    'Option 1',
+    'Option 2',
+    'Option 3',
+    'Option 4',
+    'Option 5',
+    'Option 6',
+    'Option 7',
+    'Option 8',
+    'Option 9',
+    'Option 10'
+];
+```
+
+For more comprehensive documentation and examples, please visit the [online documentation](https://vue-interface.github.io/packages/searchable-select-field/).
+

package/index.css

@@ -0,0 +1,4 @@
+@import "tailwindcss";
+@import "@vue-interface/form-control/css";
+
+@import "./src/css/searchable-select-field.css";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@vue-interface/searchable-select-field",
+  "version": "1.0.0",
+  "description": "A Vue searchable select field component.",
+  "type": "module",
+  "main": "./dist/searchable-select-field.umd.cjs",
+  "module": "./dist/searchable-select-field.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "style": "./index.css",
+      "import": "./dist/searchable-select-field.js",
+      "require": "./dist/searchable-select-field.umd.cjs"
+    }
+  },
+  "browserslist": "last 2 versions, > 0.5%, ie >= 11",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vue-interface/vue-interface.github.io"
+  },
+  "keywords": [
+    "Searchable",
+    "Select",
+    "Input",
+    "Field",
+    "Vue",
+    "Component",
+    "Tailwind"
+  ],
+  "author": "Justin Kimbrell",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/vue-interface/vue-interface.github.io"
+  },
+  "homepage": "https://vue-interface.github.io/packages/searchable-select-field",
+  "readme": "README.md",
+  "files": [
+    "src",
+    "dist",
+    "index.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@heroicons/vue": "2.2.0",
+    "fuse.js": "^7.1.0",
+    "vue": "^3.3.4",
+    "@vue-interface/activity-indicator": "3.0.7",
+    "@vue-interface/form-control": "2.0.18",
+    "@vue-interface/input-field": "2.0.19",
+    "@vue-interface/sizeable": "2.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc && vite build",
+    "preview": "vite preview"
+  }
+}

package/src/SearchableSelectField.vue

@@ -0,0 +1,308 @@
+<script setup lang="ts" generic="T, Value">
+import { ChevronDownIcon, XMarkIcon } from '@heroicons/vue/24/outline';
+import { ActivityIndicator, Pulse } from '@vue-interface/activity-indicator';
+import type { FormControlEvents, FormControlProps, FormControlSlots } from '@vue-interface/form-control';
+import { useFormControl } from '@vue-interface/form-control';
+import { InputField } from '@vue-interface/input-field';
+import Fuse, { IFuseOptions } from 'fuse.js';
+import { InputHTMLAttributes, computed, nextTick, ref, useTemplateRef, watch, watchEffect } from 'vue';
+
+const props = withDefaults(defineProps<SearchableSelectFieldProps<T,Value>>(), {
+    formControlClass: 'form-control',
+    labelClass: 'form-label',
+    size: 'form-control-md',
+    clearable: true,
+    options: () => []
+});
+
+const model = defineModel<T>();
+const isInteractive = computed(() => !props.disabled && !props.readonly);
+
+defineSlots<FormControlSlots<SearchableSelectFieldSizePrefix,T> & {
+    default(props: { option: T; display?: (option: T) => string }): any;
+}>();
+
+const emit = defineEmits<FormControlEvents>();
+
+const {
+    controlAttributes,
+    formGroupClasses,
+    listeners
+} = useFormControl<InputHTMLAttributes, SearchableSelectFieldSizePrefix, T|undefined, T>({ model, props, emit });
+
+watchEffect(() => {
+    if(props.value !== undefined) {
+        model.value = props.value;
+    }
+});
+
+const input = ref<string>();
+const showOptions = ref(false);
+const active = ref<number>();
+const buttons = useTemplateRef<HTMLButtonElement[]>('buttons');
+const optionsEl = useTemplateRef<HTMLDivElement>('optionsEl');
+
+const keys = computed(() => {
+    return typeof props.options === 'object' && props.options?.[0]
+        ? Object.keys(props.options?.[0])
+        : ['$'];
+});
+
+let fuse: Fuse<T> = createFuse();
+
+function createFuse() {
+    return new Fuse(props.options ?? [], props.fuseOptions ?? {
+        includeScore: true,
+        threshold: .45,
+        keys: keys.value
+    });
+}
+
+const filtered = computed<T[]>(() => {
+    if(!input.value) {
+        return props.options ?? [];
+    }
+
+    const matches = fuse.search(input.value).map(({ item }) => item);
+
+    if(props.allowCustom && !matches.length) {
+        return props.options;
+    }
+
+    return matches;
+});
+
+watch(() => props.options, () => {
+    fuse = createFuse();
+});
+
+function scrollIntoView(child?: HTMLElement) {
+    const parent = optionsEl.value;
+
+    if(!parent || !child) {
+        return;
+    }
+
+    const parentRect = parent.getBoundingClientRect();
+    const childRect = child.getBoundingClientRect();
+
+    const childTop = childRect.top - parentRect.top + parent.scrollTop;
+
+    parent.scrollTop = childTop;
+};
+
+watch([input, active], ([input, active]) => {
+    if(input) {
+        buttons.value?.[0]?.scrollIntoView({
+            block: 'nearest',
+            inline: 'nearest'
+        });
+    }
+    else if(active !== undefined) {
+        buttons.value?.[active]?.scrollIntoView({
+            block: 'nearest',
+            inline: 'nearest'
+        });
+    }
+});
+
+watch(optionsEl, (value) => {
+    if(!value || active.value === undefined) {
+        return;
+    }
+
+    nextTick(() => {
+        scrollIntoView(buttons.value?.[active.value as number]);
+    });
+});
+
+function select(option?: T) {
+    model.value = option;
+    active.value = option && props.options.includes(option)
+        ? props.options.indexOf(option)
+        : undefined;
+    input.value = undefined;
+    showOptions.value = false;
+}
+
+function onInput(e: Event) {
+    if (!isInteractive.value) return;
+
+    showOptions.value = true;
+    active.value = undefined;
+    input.value = (e.target as HTMLInputElement)?.value;
+
+    if(!input.value && !props.allowCustom) {
+        model.value = undefined;
+    }
+
+    if(props.allowCustom) {
+        model.value = input.value as T;
+    }
+}
+
+function onKeypressEnter() {
+    if (!isInteractive.value) return;
+
+    if(!showOptions.value) {
+        showOptions.value = true;
+        return;
+    }
+
+    if(props.allowCustom && active.value === undefined) {
+        select(input.value as T ?? model.value);
+    }
+    else if(active.value === undefined) {
+        select(filtered.value[0]);
+    }
+    else if(filtered.value[active.value]) {
+        select(filtered.value[active.value]);
+    }
+    else {
+        select(undefined);
+    }
+}
+
+function onKeydownUp() {
+    if (!isInteractive.value) return;
+    
+    showOptions.value = true;
+
+    if(!active.value) {
+        active.value = filtered.value.length - 1;
+    }
+    else {
+        active.value--;
+    }
+}
+
+function onKeydownDown() {
+    if (!isInteractive.value) return;
+
+    showOptions.value = true;
+
+    if(active.value === undefined || active.value === filtered.value.length - 1) {
+        active.value = 0;
+    }
+    else {
+        active.value++;
+    }
+}
+
+function onBlur() {
+    showOptions.value = false;
+    input.value = undefined;
+}
+
+function onClickOption(option: T) {
+    if (!isInteractive.value) return;
+    select(option);
+}
+
+function clear() {
+    if (!isInteractive.value) return;
+    input.value = undefined;
+    model.value = undefined;
+}
+
+const canClear = computed(() => {
+    return props.clearable && (!!input.value || !!model.value) && isInteractive.value;
+});
+</script>
+<script lang="ts">
+export type SearchableSelectFieldSizePrefix = 'form-control';
+
+export type SearchableSelectFieldProps<ModelValue, Value> = FormControlProps<
+    InputHTMLAttributes, 
+    SearchableSelectFieldSizePrefix, 
+    ModelValue, 
+    Value
+> & {
+    options?: ModelValue[];
+    fuseOptions?: IFuseOptions<ModelValue>;
+    display?: (option: ModelValue) => string;
+    allowCustom?: boolean;
+    clearable?: boolean;
+};
+</script>
+
+
+<template>
+    <div class="relative [&_.form-control]:pr-8">
+        <InputField
+            ref="field"
+            class="searchable-select-field-input"
+            :class="{ 'has-clear-button': canClear, formGroupClasses }"
+            :size="size"
+            v-bind="{ ...$attrs, controlAttributes, listeners }"
+            :name="name"
+            :label="label"
+            :model-value="input ?? (model && props?.display ? props?.display?.(model) : model)"
+            :disabled="disabled"
+            :readonly="readonly"
+            :color="color"
+            :error="error"
+            :errors="errors"
+            :feedback="feedback"
+            :valid="valid"
+            :invalid="invalid"
+            @click="isInteractive && (showOptions = true)"
+            @focus="isInteractive && (showOptions = true)"
+            @blur="onBlur"
+            @keypress.enter.prevent="onKeypressEnter"
+            @keydown.up.prevent="onKeydownUp"
+            @keydown.down.prevent="onKeydownDown"
+            @keyup.escape="showOptions = false"
+            @input="onInput">
+            <template #icon v-if="$slots.icon">
+                <slot name="icon" />
+            </template>
+            <template #activity>
+                <slot
+                    name="activity"
+                    v-bind="{ disabled, options, invalid, valid }">
+                    <ActivityIndicator
+                        v-if="!disabled && !options"
+                        :type="Pulse"
+                        size="activity-indicator-sm" />
+                    <button
+                        v-else-if="canClear"
+                        type="button"
+                        class="searchable-select-field-clear-button"
+                        @click.stop="clear">
+                        <XMarkIcon class="size-[1.25em]" />
+                    </button>
+                    <ChevronDownIcon 
+                        v-else-if="!invalid && !valid"
+                        class="size-[1.25em]" />
+                </slot>
+            </template>
+        </InputField>
+        <div
+            v-if="showOptions && filtered.length"
+            ref="optionsEl"
+            tabindex="-1"
+            class="searchable-select-field-dropdown"
+            :class="size"
+            @mousedown.prevent.stop>
+            <button
+                v-for="(option, i) in filtered"
+                ref="buttons"
+                :key="i"
+                type="button"
+                tabindex="-1"
+                :title="display?.(option) ?? String(option)"
+                :class="{
+                    ['bg-neutral-200 dark:bg-neutral-700']: active === i
+                }"
+                @mousedown.prevent
+                @click="onClickOption(option)">
+                <slot v-bind="{ option, display }">
+                    <div class="truncate">
+                        {{ display?.(option) ?? option }}
+                    </div>
+                </slot>
+            </button>
+        </div>
+    </div>
+</template>

package/src/css/searchable-select-field.css

@@ -0,0 +1,129 @@
+@import "tailwindcss";
+
+@theme { 
+    /* Searchable Select Field Dropdown */
+    --searchable-select-field-dropdown-display: flex;
+    --searchable-select-field-dropdown-flex-direction: column;
+    --searchable-select-field-dropdown-position: absolute;
+    --searchable-select-field-dropdown-z-index: 10;
+    --searchable-select-field-dropdown-width: 100%;
+    --searchable-select-field-dropdown-max-height: 18rem;
+    --searchable-select-field-dropdown-margin-top: 0.25rem;
+    --searchable-select-field-dropdown-overflow: auto;
+    --searchable-select-field-dropdown-border-width: 1px;
+    --searchable-select-field-dropdown-border-radius: 0.25rem;
+    --searchable-select-field-dropdown-border-color: var(--color-neutral-300, oklch(87% 0 0));
+    --searchable-select-field-dropdown-background-color: var(--color-white, #fff);
+    --searchable-select-field-dropdown-color: var(--color-black, #000);
+    --searchable-select-field-dropdown-box-shadow-style: 0 10px 15px -3px, 0 4px 6px -4px;
+    --searchable-select-field-dropdown-box-shadow-color: rgb(0 0 0 / 0.1), rgb(0 0 0 / 0.1);
+
+    --searchable-select-field-dropdown-dark-border-color: var(--color-neutral-600, oklch(43.9% 0 0));
+    --searchable-select-field-dropdown-dark-background-color: var(--color-neutral-900, oklch(20.5% 0 0));
+    --searchable-select-field-dropdown-dark-color: var(--color-white, #fff);
+
+    --searchable-select-field-dropdown-text-align: left;
+    --searchable-select-field-dropdown-padding: 0.5em 1em;
+    --searchable-select-field-dropdown-border-bottom-width: 1px;
+    --searchable-select-field-dropdown-hover-background-color: var(--color-neutral-200, oklch(92.2% 0 0));
+    --searchable-select-field-dropdown-dark-hover-background-color: var(--color-neutral-700, oklch(37.1% 0 0));
+
+    /* Searchable Select Field Input */
+    --searchable-select-field-input-position: relative;
+    --searchable-select-field-input-activity-indicator-position: absolute;
+    --searchable-select-field-input-activity-indicator-top: 50%;
+    --searchable-select-field-input-activity-indicator-right: 0;
+    --searchable-select-field-input-activity-indicator-transform: translate(-1rem, -50%);
+
+    /* Searchable Select-field Clear Button */
+    --searchable-select-field-clear-button-display: flex;
+    --searchable-select-field-clear-button-cursor: pointer;
+    --searchable-select-field-clear-button-color: var(--color-black, #000);
+    --searchable-select-field-clear-button-hover-color: var(--color-neutral-600, oklch(43.9% 0 0));
+
+    --searchable-select-field-clear-button-dark-color: var(--color-white, #fff);
+    --searchable-select-field-clear-button-dark-hover-color: var(--color-neutral-400, oklch(70.8% 0 0));
+}
+
+@utility searchable-select-field-dropdown {
+    display: var(--searchable-select-field-dropdown-display);
+    flex-direction: var(--searchable-select-field-dropdown-flex-direction);
+    position: var(--searchable-select-field-dropdown-position);
+    z-index: var(--searchable-select-field-dropdown-z-index);
+    width: var(--searchable-select-field-dropdown-width);
+    max-height: var(--searchable-select-field-dropdown-max-height);
+    margin-top: var(--searchable-select-field-dropdown-margin-top);
+    overflow: var(--searchable-select-field-dropdown-overflow);
+    border-width: var(--searchable-select-field-dropdown-border-width);
+    border-radius: var(--searchable-select-field-dropdown-border-radius);
+    border-color: var(--searchable-select-field-dropdown-border-color);
+    background-color: var(--searchable-select-field-dropdown-background-color);
+    color: var(--searchable-select-field-dropdown-color);
+    box-shadow: var(--searchable-select-field-dropdown-box-shadow-style) var(--searchable-select-field-dropdown-box-shadow-color);
+
+    @variant dark {
+        border-color: var(--searchable-select-field-dropdown-dark-border-color);
+        background-color: var(--searchable-select-field-dropdown-dark-background-color);
+        color: var(--searchable-select-field-dropdown-dark-color);
+    }
+
+    & > button {
+        text-align: var(--searchable-select-field-dropdown-text-align);
+        padding: var(--searchable-select-field-dropdown-padding);
+        border-color: var(--searchable-select-field-dropdown-border-color);
+
+        &:not(:last-child) {
+            border-bottom-width: var(--searchable-select-field-dropdown-border-bottom-width);
+        }
+
+        &:hover {
+            background-color: var(--searchable-select-field-dropdown-hover-background-color);
+        }
+
+        @variant dark {
+            border-color: var(--searchable-select-field-dropdown-dark-border-color);
+
+            &:hover {
+                background-color: var(--searchable-select-field-dropdown-dark-hover-background-color);
+            }
+        }
+    }
+}
+
+@utility searchable-select-field-input {
+    position: var(--searchable-select-field-input-position);
+    
+    & .form-control-inner {
+        position: var(--searchable-select-field-input-position);
+    }
+
+    & .form-control-activity-indicator {
+        position: var(--searchable-select-field-input-activity-indicator-position);
+        top: var(--searchable-select-field-input-activity-indicator-top);
+        right: var(--searchable-select-field-input-activity-indicator-right);
+        transform: var(--searchable-select-field-input-activity-indicator-transform);
+    }
+
+    &.has-clear-button .form-control.is-valid,
+    &.has-clear-button .form-control.is-invalid {
+        background-image: none;
+    }
+}
+
+@utility searchable-select-field-clear-button {
+    display: var(--searchable-select-field-clear-button-display);
+    cursor: var(--searchable-select-field-clear-button-cursor);
+    color: var(--searchable-select-field-clear-button-color);
+
+    &:hover {
+        color: var(--searchable-select-field-clear-button-hover-color);
+    }
+
+    @variant dark {
+        color: var(--searchable-select-field-clear-button-dark-color);
+
+        &:hover {
+            color: var(--searchable-select-field-clear-button-dark-hover-color);
+        }
+    }
+}