slim-select 2.13.1 → 3.0.0

package/README.md

@@ -1,11 +1,11 @@
-# Slim Select 2
+# Slim Select
 
 ## [slimselectjs.com](https://slimselectjs.com)
 
 Advanced select dropdown
 
 [![NPM Downloads](https://img.shields.io/npm/dt/slim-select.svg)](https://www.npmjs.com/package/slim-select)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/brianvoe/slim-select/jest.yml?logo=jest&label=unit%20tests) [![slim-select](https://snyk.io/advisor/npm-package/slim-select/badge.svg)](https://snyk.io/advisor/npm-package/slim-select)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/brianvoe/slim-select/vitest.yml?logo=vitest&label=unit%20tests) [![slim-select](https://snyk.io/advisor/npm-package/slim-select/badge.svg)](https://snyk.io/advisor/npm-package/slim-select)
 
 ## Support
 
@@ -39,10 +39,12 @@ See [website](https://slimselectjs.com) for the full list of [settings](https://
 - Clean Animations
 - Performant
 - Typescript
+- ARIA Accessibility (WCAG 2.1 Level AA compliant)
 
 ## Frameworks
 
-- Vue
+- [Vue](#vue)
+- [React](#react)
 
 ## Installation
 
@@ -65,7 +67,7 @@ import 'slim-select/styles' // optional css import method
 import 'slim-select/scss' // optional scss import method
 
 new SlimSelect({
-  select: '#selectElement',
+  select: '#selectElement'
 })
 ```
 
@@ -91,7 +93,7 @@ new SlimSelect({
   // or
 
   // Array of Optgroups and/or Options
-  data: [{ label: 'Optgroup Label', options: { text: 'Value 1', value: 'value1' } }],
+  data: [{ label: 'Optgroup Label', options: { text: 'Value 1', value: 'value1' } }]
 })
 ```
 
@@ -103,7 +105,7 @@ var optgroup = {
   label: 'label', // Required
   selectAll: false, // Optional - default false
   closable: 'off', // Optional - default 'off' - 'off', 'open', 'close'
-  options: [], // Required - value is an array of options
+  options: [] // Required - value is an array of options
 }
 
 // <option>
@@ -118,44 +120,46 @@ var option = {
   placeholder: false, // Optional - default is false
   class: '', // Optional - default is not set
   style: '', // Optional - default is not set
-  data: {}, // Optional - If you have data attributes
+  data: {} // Optional - If you have data attributes
 }
 ```
 
 ## Settings
 
-Settings are a list of fields that help customize how SlimSelect operates
+Settings are optional fields that customize how SlimSelect operates. All values shown are defaults.
+
+[Full Settings Documentation](https://slimselectjs.com/settings)
 
 ```javascript
 new SlimSelect({
   select: '#selectElement',
 
   settings: {
-    // Below are a list of optional fields
-    // their values are the defaults
-    disabled: false,
-    alwaysOpen: false,
-    showSearch: true,
-    focusSearch: true,
-    searchPlaceholder: 'Search',
-    searchText: 'No Results',
-    searchingText: 'Searching...',
-    searchHighlight: false,
-    closeOnSelect: true,
-    contentLocation: document.body,
-    contentPosition: 'absolute',
-    openPosition: 'auto', // options: auto, up, down
-    placeholderText: 'Select Value',
-    allowDeselect: false,
-    hideSelected: false,
-    showOptionTooltips: false,
-    minSelected: 0,
-    maxSelected: 1000,
-    timeoutDelay: 200,
-    maxValuesShown: 20,
-    maxValuesMessage: '{number} selected',
-    addableText: 'Press "Enter" to add {value}',
-  },
+    disabled: false, // Disable the select
+    alwaysOpen: false, // Keep dropdown always open
+    showSearch: true, // Show search input
+    focusSearch: true, // Auto focus search on open
+    ariaLabel: 'Combobox', // ARIA label for accessibility
+    searchPlaceholder: 'Search', // Search input placeholder
+    searchText: 'No Results', // Text when no results found
+    searchingText: 'Searching...', // Text while searching
+    searchHighlight: false, // Highlight search terms
+    closeOnSelect: true, // Close dropdown after selection
+    contentLocation: document.body, // Where to append dropdown
+    contentPosition: 'absolute', // CSS position: absolute, relative, fixed
+    openPosition: 'auto', // Open direction: auto, up, down
+    placeholderText: 'Select Value', // Placeholder text
+    allowDeselect: false, // Allow deselecting in single select
+    hideSelected: false, // Hide selected options in dropdown
+    keepOrder: false, // Keep user click order (not DOM order) for getSelected
+    showOptionTooltips: false, // Show tooltips on options
+    minSelected: 0, // Minimum selections (multi-select)
+    maxSelected: 1000, // Maximum selections (multi-select)
+    timeoutDelay: 200, // Delay for callbacks (ms)
+    maxValuesShown: 20, // Max values shown before message
+    maxValuesMessage: '{number} selected', // Message when max values exceeded
+    addableText: 'Press "Enter" to add {value}' // Text for addable option
+  }
 })
 ```
 
@@ -163,21 +167,158 @@ new SlimSelect({
 
 Events are function callbacks for when certain actions happen
 
+[Full Events Documentation](https://slimselectjs.com/events)
+
 ```javascript
 new SlimSelect({
   select: '#selectElement',
 
   events: {
-    search: (searchValue: string, currentData: DataArray) => Promise<DataArrayPartial> | DataArrayPartial
-    searchFilter: (option: Option, search: string) => boolean
-    addable: (value: string) => Promise<OptionOptional | string> | OptionOptional | string | Error
-    beforeChange: (newVal: Option[], oldVal: Option[]) => boolean | void
-    afterChange: (newVal: Option[]) => void
-    beforeOpen: () => void
-    afterOpen: () => void
-    beforeClose: () => void
-    afterClose: () => void
+    // Custom search function - return Promise or data array
+    search: (searchValue: string, currentData: (Option | Optgroup)[]) => Promise<(Partial<Option> | Partial<Optgroup>)[]> | (Partial<Option> | Partial<Optgroup>)[],
+
+    // Filter function for search - return true to show option
+    searchFilter: (option: Option, search: string) => boolean,
+
+    // Allow user to add options - return new option or error
+    addable: (value: string) => Promise<Partial<Option> | string> | Partial<Option> | string | Error,
+
+    // Before selection changes - return false to prevent change
+    beforeChange: (newVal: Option[], oldVal: Option[]) => boolean | void,
+
+    // After selection changes
+    afterChange: (newVal: Option[]) => void,
+
+    // Before dropdown opens
+    beforeOpen: () => void,
+
+    // After dropdown opens
+    afterOpen: () => void,
+
+    // Before dropdown closes
+    beforeClose: () => void,
+
+    // After dropdown closes
+    afterClose: () => void,
+
+    // Error handler
     error: (err: Error) => void
-  },
+  }
 })
 ```
+
+## Methods
+
+SlimSelect provides methods to programmatically control the select
+
+[Full Methods Documentation](https://slimselectjs.com/methods)
+
+```javascript
+const slim = new SlimSelect({ select: '#selectElement' })
+
+slim.enable() // Enable the select
+slim.disable() // Disable the select
+slim.getData() // Get current data array
+slim.setData(data) // Set new data array
+slim.getSelected() // Get selected values as string[]
+slim.setSelected(['value1', 'value2']) // Set selected by values
+slim.addOption(option) // Add a single option
+slim.open() // Open the dropdown
+slim.close() // Close the dropdown
+slim.search('searchValue') // Programmatically search
+slim.destroy() // Destroy the instance
+```
+
+## Vue
+
+SlimSelect has official Vue 3 component support with full reactivity.
+
+For more Vue examples and advanced usage, see the [Vue documentation](https://slimselectjs.com/vue).
+
+### Installation
+
+```bash
+npm install slim-select
+```
+
+### Usage
+
+```vue
+<script lang="ts">
+import SlimSelect from 'slim-select/vue'
+import 'slim-select/styles'
+
+export default {
+  components: { SlimSelect },
+  data() {
+    return {
+      selected: 'value2',
+      options: [
+        { text: 'Value 1', value: 'value1' },
+        { text: 'Value 2', value: 'value2' },
+        { text: 'Value 3', value: 'value3' }
+      ]
+    }
+  }
+}
+</script>
+
+<template>
+  <SlimSelect v-model="selected" :data="options" />
+</template>
+```
+
+## React
+
+SlimSelect has official React component support with hooks.
+
+For more React examples and advanced usage, see the [documentation](https://slimselectjs.com).
+
+### Installation
+
+```bash
+npm install slim-select
+```
+
+### Usage
+
+```tsx
+import { useState } from 'react'
+import SlimSelect from 'slim-select/react'
+import 'slim-select/styles'
+
+function MyComponent() {
+  const [selected, setSelected] = useState('value2')
+  const options = [
+    { text: 'Value 1', value: 'value1' },
+    { text: 'Value 2', value: 'value2' },
+    { text: 'Value 3', value: 'value3' }
+  ]
+
+  return <SlimSelect data={options} value={selected} onChange={setSelected} />
+}
+```
+
+### Advanced Usage with Ref
+
+```tsx
+import { useRef } from 'react'
+import SlimSelect, { SlimSelectRef } from 'slim-select/react'
+import 'slim-select/styles'
+
+function MyComponent() {
+  const slimRef = useRef<SlimSelectRef>(null)
+
+  const handleClick = () => {
+    // Access SlimSelect methods via ref
+    slimRef.current?.slimSelect?.open()
+  }
+
+  return (
+    <>
+      <SlimSelect ref={slimRef} data={options} />
+      <button onClick={handleClick}>Open Dropdown</button>
+    </>
+  )
+}
+```

package/dist/index.d.ts

@@ -1,52 +1,304 @@
-import CssClasses from './classes';
-import Render from './render';
-import Select from './select';
-import Settings from './settings';
-import type { SettingsPartial } from './settings';
-import Store from './store';
-import type { DataArray, DataArrayPartial, Option, OptionOptional } from './store';
-export { DataArray, DataArrayPartial, Option, OptionOptional, SettingsPartial };
-export interface Config {
-    select: string | Element;
-    data?: DataArrayPartial;
-    settings?: SettingsPartial;
-    cssClasses?: Partial<CssClasses>;
-    events?: Events;
-}
-export interface Events {
-    search?: (searchValue: string, currentData: DataArray) => Promise<DataArrayPartial> | DataArrayPartial;
-    searchFilter?: (option: Option, search: string) => boolean;
-    addable?: (value: string) => Promise<OptionOptional | string> | OptionOptional | string | false | null | undefined | Error;
-    beforeChange?: (newVal: Option[], oldVal: Option[]) => boolean | void;
-    afterChange?: (newVal: Option[]) => void;
-    beforeOpen?: () => void;
-    afterOpen?: () => void;
-    beforeClose?: () => void;
-    afterClose?: () => void;
-    error?: (err: Error) => void;
-}
-export default class SlimSelect {
-    selectEl: HTMLSelectElement;
-    settings: Settings;
-    cssClasses: CssClasses;
-    select: Select;
-    store: Store;
-    render: Render;
-    events: Events;
-    constructor(config: Config);
-    enable(): void;
-    disable(): void;
-    getData(): DataArray;
-    setData(data: DataArrayPartial): void;
-    getSelected(): string[];
-    setSelected(values: string | string[], runAfterChange?: boolean): void;
-    addOption(option: OptionOptional): void;
-    open(): void;
-    close(eventType?: string | null): void;
-    search(value: string): void;
-    destroy(): void;
-    private windowResize;
-    private windowScroll;
-    private documentClick;
-    private windowVisibilityChange;
-}
+declare interface Callbacks {
+    open: () => void;
+    close: () => void;
+    addable?: (value: string) => Promise<Partial<Option_2> | string> | Partial<Option_2> | string | false | undefined | null | Error;
+    setSelected: (value: string | string[], runAfterChange: boolean) => void;
+    addOption: (option: Option_2) => void;
+    search: (search: string) => void;
+    beforeChange?: (newVal: Option_2[], oldVal: Option_2[]) => boolean | void;
+    afterChange?: (newVal: Option_2[]) => void;
+}
+
+export declare interface Config {
+    select: string | Element;
+    data?: (Partial<Option_2> | Partial<Optgroup>)[];
+    settings?: Partial<Settings>;
+    cssClasses?: Partial<CssClasses>;
+    events?: Events;
+}
+
+declare interface Content {
+    main: HTMLDivElement;
+    search: Search;
+    list: HTMLDivElement;
+}
+
+declare class CssClasses {
+    main: string;
+    placeholder: string;
+    values: string;
+    single: string;
+    max: string;
+    value: string;
+    valueText: string;
+    valueDelete: string;
+    valueOut: string;
+    deselect: string;
+    deselectPath: string;
+    arrow: string;
+    arrowClose: string;
+    arrowOpen: string;
+    content: string;
+    contentOpen: string;
+    dirAbove: string;
+    dirBelow: string;
+    search: string;
+    searchHighlighter: string;
+    searching: string;
+    addable: string;
+    addablePath: string;
+    list: string;
+    optgroup: string;
+    optgroupLabel: string;
+    optgroupLabelText: string;
+    optgroupActions: string;
+    optgroupSelectAll: string;
+    optgroupSelectAllBox: string;
+    optgroupSelectAllCheck: string;
+    optgroupClosable: string;
+    option: string;
+    optionDelete: string;
+    highlighted: string;
+    mainOpen: string;
+    close: string;
+    selected: string;
+    error: string;
+    disabled: string;
+    hide: string;
+    constructor(classes?: Partial<CssClasses>);
+}
+
+export declare interface Events {
+    search?: (searchValue: string, currentData: (Option_2 | Optgroup)[]) => Promise<(Partial<Option_2> | Partial<Optgroup>)[]> | (Partial<Option_2> | Partial<Optgroup>)[];
+    searchFilter?: (option: Option_2, search: string) => boolean;
+    addable?: (value: string) => Promise<Partial<Option_2> | string> | Partial<Option_2> | string | false | null | undefined | Error;
+    beforeChange?: (newVal: Option_2[], oldVal: Option_2[]) => boolean | void;
+    afterChange?: (newVal: Option_2[]) => void;
+    beforeOpen?: () => void;
+    afterOpen?: () => void;
+    beforeClose?: () => void;
+    afterClose?: () => void;
+    error?: (err: Error) => void;
+}
+
+declare interface Main {
+    main: HTMLDivElement;
+    values: HTMLDivElement;
+    deselect: {
+        main: HTMLDivElement;
+        svg: SVGSVGElement;
+        path: SVGPathElement;
+    };
+    arrow: {
+        main: SVGSVGElement;
+        path: SVGPathElement;
+    };
+}
+
+export declare class Optgroup {
+    id: string;
+    label: string;
+    selectAll: boolean;
+    selectAllText: string;
+    closable: 'off' | 'open' | 'close';
+    options: Partial<Option_2>[];
+    constructor(optgroup: Partial<Optgroup>);
+}
+
+declare class Option_2 {
+    id: string;
+    value: string;
+    text: string;
+    html: string;
+    defaultSelected: boolean;
+    selected: boolean;
+    display: boolean;
+    disabled: boolean;
+    placeholder: boolean;
+    class: string;
+    style: string;
+    data: {
+        [key: string]: string;
+    };
+    mandatory: boolean;
+    constructor(option: Partial<Option_2>);
+}
+export { Option_2 as Option }
+
+export declare class Render {
+    settings: Settings;
+    store: Store;
+    callbacks: Callbacks;
+    private lastSelectedOption;
+    main: Main;
+    content: Content;
+    classes: CssClasses;
+    constructor(settings: Required<Settings>, classes: Required<CssClasses>, store: Store, callbacks: Callbacks);
+    enable(): void;
+    disable(): void;
+    open(): void;
+    close(): void;
+    updateClassStyles(): void;
+    updateAriaAttributes(): void;
+    mainDiv(): Main;
+    mainFocus(eventType: string | null): void;
+    placeholder(): HTMLDivElement;
+    renderValues(): void;
+    private renderSingleValue;
+    private renderMultipleValues;
+    multipleValue(option: Option_2): HTMLDivElement;
+    contentDiv(): Content;
+    moveContent(): void;
+    searchDiv(): Search;
+    searchFocus(): void;
+    clearSearch(): void;
+    getOptions(notPlaceholder?: boolean, notDisabled?: boolean, notHidden?: boolean): HTMLDivElement[];
+    highlight(dir: 'up' | 'down'): void;
+    listDiv(): HTMLDivElement;
+    renderError(error: string): void;
+    renderSearching(): void;
+    renderOptions(data: (Option_2 | Optgroup)[]): void;
+    option(option: Option_2): HTMLDivElement;
+    destroy(): void;
+    private highlightText;
+    moveContentAbove(): void;
+    moveContentBelow(): void;
+    ensureElementInView(container: HTMLElement, element: HTMLElement): void;
+    putContent(): 'up' | 'down';
+    updateDeselectAll(): void;
+}
+
+declare interface Search {
+    main: HTMLDivElement;
+    input: HTMLInputElement;
+    addable?: {
+        main: HTMLDivElement;
+        svg: SVGSVGElement;
+        path: SVGPathElement;
+    };
+}
+
+export declare class Select {
+    select: HTMLSelectElement;
+    onValueChange?: (value: Option_2[]) => void;
+    onClassChange?: (classes: string[]) => void;
+    onDisabledChange?: (disabled: boolean) => void;
+    onOptionsChange?: (data: (Option_2 | Optgroup)[]) => void;
+    listen: boolean;
+    private observer;
+    constructor(select: HTMLSelectElement);
+    enable(): void;
+    disable(): void;
+    hideUI(): void;
+    showUI(): void;
+    changeListen(listen: boolean): void;
+    valueChange(ev: Event): boolean;
+    private observeCall;
+    getData(): (Option_2 | Optgroup)[];
+    getDataFromOptgroup(optgroup: HTMLOptGroupElement): Optgroup;
+    getDataFromOption(option: HTMLOptionElement): Option_2;
+    getSelectedOptions(): Option_2[];
+    getSelectedValues(): string[];
+    setSelected(ids: string[]): void;
+    setSelectedByValue(values: string[]): void;
+    updateSelect(id?: string, style?: string, classes?: string[]): void;
+    updateOptions(data: (Option_2 | Optgroup)[]): void;
+    createOptgroup(optgroup: Optgroup): HTMLOptGroupElement;
+    createOption(info: Option_2): HTMLOptionElement;
+    destroy(): void;
+}
+
+declare type selectType = 'single' | 'multiple';
+
+export declare class Settings {
+    id: string;
+    style: string;
+    class: string[];
+    isMultiple: boolean;
+    isOpen: boolean;
+    isFullOpen: boolean;
+    intervalMove: ReturnType<typeof setInterval> | null;
+    disabled: boolean;
+    alwaysOpen: boolean;
+    showSearch: boolean;
+    focusSearch: boolean;
+    ariaLabel: string;
+    searchPlaceholder: string;
+    searchText: string;
+    searchingText: string;
+    searchHighlight: boolean;
+    closeOnSelect: boolean;
+    contentLocation: HTMLElement | null;
+    contentPosition: 'relative' | 'absolute' | 'fixed';
+    openPosition: 'auto' | 'up' | 'down';
+    placeholderText: string;
+    allowDeselect: boolean;
+    hideSelected: boolean;
+    keepOrder: boolean;
+    showOptionTooltips: boolean;
+    minSelected: number;
+    maxSelected: number;
+    timeoutDelay: number;
+    maxValuesShown: number;
+    maxValuesMessage: string;
+    addableText: string;
+    constructor(settings?: Partial<Settings>);
+}
+
+declare class SlimSelect {
+    selectEl: HTMLSelectElement;
+    settings: Settings;
+    cssClasses: CssClasses;
+    select: Select;
+    store: Store;
+    render: Render;
+    private openTimeout;
+    private closeTimeout;
+    events: Events;
+    constructor(config: Config);
+    enable(): void;
+    disable(): void;
+    getData(): Option_2[] | Optgroup[];
+    setData(data: (Partial<Option_2> | Partial<Optgroup>)[]): void;
+    getSelected(): string[];
+    setSelected(values: string | string[], runAfterChange?: boolean): void;
+    addOption(option: Partial<Option_2>): void;
+    open(): void;
+    close(eventType?: string | null): void;
+    search(value: string): void;
+    destroy(): void;
+    private windowResize;
+    private windowScroll;
+    private documentClick;
+    private windowVisibilityChange;
+}
+export default SlimSelect;
+
+export declare class Store {
+    private selectType;
+    private data;
+    private selectedOrder;
+    constructor(type: selectType, data: (Partial<Option_2> | Partial<Optgroup>)[]);
+    validateDataArray(data: (Partial<Option_2> | Partial<Optgroup>)[]): Error | null;
+    validateOption(option: Partial<Option_2>): Error | null;
+    partialToFullData(data: (Partial<Option_2> | Partial<Optgroup>)[]): (Option_2 | Optgroup)[];
+    setData(data: (Partial<Option_2> | Partial<Optgroup>)[], preserveSelected?: boolean): void;
+    getData(): Option_2[] | Optgroup[];
+    getDataOptions(): Option_2[];
+    addOption(option: Partial<Option_2>, addToStart?: boolean): void;
+    setSelectedBy(selectedType: 'id' | 'value', selectedValues: string[]): void;
+    getSelected(): string[];
+    getSelectedValues(): string[];
+    getSelectedOptions(): Option_2[];
+    getOptgroupByID(id: string): Optgroup | null;
+    getOptionByID(id: string): Option_2 | null;
+    getSelectType(): string;
+    getFirstOption(): Option_2 | null;
+    search(search: string, searchFilter: (opt: Option_2, search: string) => boolean): (Option_2 | Optgroup)[];
+    filter(filter: {
+        (opt: Option_2): boolean;
+    } | null, includeOptgroup: boolean): (Option_2 | Optgroup)[];
+    selectedOrderOptions(options: Option_2[]): Option_2[];
+}
+
+export { }