selectic 3.0.21 → 3.1.0

package/types/Store.d.ts

@@ -36,92 +36,218 @@ export declare type FetchCallback = (_search: string, _offsetItem: number, _page
 }>;
 export declare type GetCallback = (_ids: OptionId[]) => Promise<OptionValue[]>;
 export declare type FormatCallback = (_option: OptionItem) => OptionItem;
-export declare type SelectionOverflow = 'collapsed' | 'multiline';
-export declare type ListPosition = 'bottom' | 'top' | 'auto';
-export declare type HideFilter = boolean | 'auto' | 'open';
-export declare type SelectAllOption = 'auto' | 'visible';
+export declare type SelectionOverflow = 
+/** Items are reduced in width and an ellipsis is displayed in their name. */
+'collapsed' | 'multiline';
+export declare type ListPosition = 
+/** Display the list at bottom */
+'bottom'
+/** Display the list at bottom */
+ | 'top'
+/** Display the list at bottom but if there is not enough space, display it at top */
+ | 'auto';
+export declare type HideFilter = 
+/** Display or hide the filter panel */
+boolean
+/** The handler to open the filter panel is hidden only if there is less
+ * than 10 options */
+ | 'auto'
+/** The panel filter is always open */
+ | 'open';
+export declare type SelectAllOption = 
+/** Display the "select all" only when data are all fetched or allowRevert */
+'auto'
+/** Always display the "select all" in mulitple mode. */
+ | 'visible';
 export interface SelecticStoreStateParams {
+    /** Equivalent of <select>'s "multiple" attribute */
     multiple?: boolean;
+    /** Equivalent of <input>'s "placeholder" attribute */
     placeholder?: string;
+    /** Hide filter component when enabled */
     hideFilter?: HideFilter;
+    /** Allow to reverse selection.
+     * If true, parent should support the selectionIsExcluded property.
+     * If false, the action is never available.
+     * If undefined, the action is available only when it is not needed to
+     * change selectionIsExcluded property.
+     */
     allowRevert?: boolean;
+    /** Force the availability of the "select all" even if all data is not fetched yet. */
     forceSelectAll?: SelectAllOption;
+    /** Allow user to clear current selection */
     allowClearSelection?: boolean;
+    /** Number of items to retrieve in fetch request  (it is possible
+     * to fetch more items at once if several pages are requested) */
     pageSize?: number;
+    /** Select the first available option */
     autoSelect?: boolean;
+    /** Disable the select if only one option is given and must be selected. */
     autoDisabled?: boolean;
+    /** Accept only values which are in options */
     strictValue?: boolean;
+    /** Define how the component should behave when selected items are too
+     * large for the container.
+     *     collapsed (default): Items are reduced in width and an ellipsis
+     *                          is displayed in their name.
+     *     multiline: The container extends in height in order to display all
+     *                items.
+     */
     selectionOverflow?: SelectionOverflow;
+    /** Called when item is displayed in the list. */
     formatOption?: FormatCallback;
+    /** Called when item is displayed in the selection area. */
     formatSelection?: FormatCallback;
+    /** Described behavior when options from several sources are set (static, dynamic, slots)
+     * It describe what to do (sort or force)
+     * and the order (O → static options, D → dynamic options, E → slot elements)
+     * Example: "sort-ODE"
+     */
     optionBehavior?: string;
+    /** Indicate where the list should be deployed */
     listPosition?: ListPosition;
+    /** If true, the component is open at start */
     isOpen?: boolean;
+    /** Avoid selecting all items when clicking on group's header */
+    disableGroupSelection?: boolean;
 }
 export interface Props {
+    /** Selected value */
     value?: SelectedValue | null;
+    /** If true, the value represents the ones we don't want to select */
     selectionIsExcluded?: boolean;
+    /** Equivalent of "disabled" Select's attribute */
     disabled?: boolean;
+    /** List of options to display */
     options?: OptionProp[] | null;
+    /** List of options to display from child elements */
     childOptions?: OptionValue[];
+    /** Define groups which will be used by items */
     groups?: GroupValue[];
+    /** Overwrite default texts */
     texts?: PartialMessages | null;
+    /** Overwrite default icons */
+    icons?: PartialIcons | null;
+    /** Overwrite default icon family */
+    iconFamily?: IconFamily | null;
+    /** Keep this component open if another Selectic component opens */
     keepOpenWithOtherSelectic?: boolean;
+    /** Selectic configuration */
     params?: SelecticStoreStateParams;
+    /** Method to call to fetch extra data */
     fetchCallback?: FetchCallback | null;
+    /** Method to call to get specific item */
     getItemsCallback?: GetCallback | null;
 }
 declare type InternalProps = MandateProps<Props>;
 export interface Data {
+    /** Number of items displayed in a page (before scrolling) */
     itemsPerPage: number;
     labels: Messages;
+    icons: PartialIcons;
+    iconFamily: IconFamily;
+    /** used to avoid checking and updating table while doing batch stuff */
     doNotUpdate: boolean;
     cacheItem: Map<OptionId, OptionValue>;
     activeOrder: OptionBehaviorOrder;
     dynOffset: number;
 }
 export interface SelecticStoreState {
+    /** The current selected values */
     internalValue: SelectedValue;
+    /** If true, user wants to choose the opposite selection */
     selectionIsExcluded: boolean;
+    /** If true, several value can be selected */
     multiple: boolean;
+    /** If true, no change can be done by user */
     disabled: boolean;
+    /** Define the default text to display when there is no selection */
     placeholder: string;
+    /** If true, filters and controls are hidden */
     hideFilter: boolean;
+    /** If true, the filter panel is always open */
     keepFilterOpen: boolean;
+    /** Allow to reverse selection.
+     * If true, parent should support the selectionIsExcluded property.
+     * If false, the action is never available.
+     * If undefined, the action is available only when it is not needed to
+     * change selectionIsExcluded property.
+     */
     allowRevert?: boolean;
+    /** If true, user can clear current selection
+     * (if false, it is still possible to clear it programmatically) */
     allowClearSelection: boolean;
+    /** If false, do not select the first available option even if value is mandatory */
     autoSelect: boolean;
+    /** If true, Selectic is disabled if there is only one mandatory option. */
     autoDisabled: boolean;
+    /** If true, only values which are in options are accepted. */
     strictValue: boolean;
+    /** Define how to behave when selected items are too large for container. */
     selectionOverflow: SelectionOverflow;
+    /** If true, the list is displayed */
     isOpen: boolean;
+    /** Text entered by user to look for options */
     searchText: string;
+    /** Contains all known options */
     allOptions: OptionValue[];
+    /** Contains all fetched dynamic options */
     dynOptions: OptionValue[];
+    /** Contains options which should be displayed */
     filteredOptions: OptionItem[];
+    /** Contains options which are selected */
     selectedOptions: OptionItem | OptionItem[] | null;
+    /** The total number of all options (static + dynamic + elements) without any filter */
     totalAllOptions: number;
+    /** The total number of options which can be fetched (without any filter) */
     totalDynOptions: number;
+    /** The total number of options which should be displayed (filter is applied) */
     totalFilteredOptions: number;
+    /** Description of groups (optGroup) */
     groups: Map<OptionId, string>;
+    /** Starting index of options which are displayed */
     offsetItem: number;
+    /** Index of active item */
     activeItemIdx: number;
+    /** Number of items to fetch per page */
     pageSize: number;
+    /** Called when item is displayed in the list. */
     formatOption?: FormatCallback;
+    /** Called when item is displayed in the selection area. */
     formatSelection?: FormatCallback;
+    /** Operation to apply when there are several sources */
     optionBehaviorOperation: OptionBehaviorOperation;
+    /** Order of sources options */
     optionBehaviorOrder: OptionBehaviorOrder[];
+    /** Indicate where the list should be deployed */
     listPosition: ListPosition;
+    /** If true, the "select All" is still available even if all data are not fetched yet. */
     forceSelectAll: SelectAllOption;
+    /** Avoid selecting all items when clicking on group's header */
+    disableGroupSelection: boolean;
+    /** Inner status which should be modified only by store */
     status: {
+        /** If true, a search is currently done */
         searching: boolean;
+        /** If not empty, an error happens */
         errorMessage: string;
+        /** If true it means that all options are selected */
         areAllSelected: boolean;
+        /** If true, a change has been done by user */
         hasChanged: boolean;
+        /** If true, it means the current change has been done automatically by Selectic */
         automaticChange: boolean;
+        /** If true, it means the current close has been done automatically by Selectic */
         automaticClose: boolean;
     };
 }
+export declare type IconFamily = '' | 'selectic' | 'font-awesome-4' | 'font-awesome-5' | 'font-awesome-6' | 'raw' | `prefix:${string}`;
+export declare type IconKey = 'caret-down' | 'caret-up' | 'check' | 'search' | 'spinner' | 'strikethrough' | 'times' | 'question' | 'spin';
+export declare type IconValue = `selectic:${IconKey}${'' | ':spin'}` | `raw:${string}` | `current:${IconKey}${'' | ':spin'}` | string;
+export declare type Icons = Record<IconKey, IconValue>;
+export declare type PartialIcons = {
+    [K in IconKey]?: Icons[K];
+};
 interface Messages {
     noFetchMethod: string;
     searchPlaceholder: string;
@@ -145,6 +271,7 @@ export declare type PartialMessages = {
     [K in keyof Messages]?: Messages[K];
 };
 export declare function changeTexts(texts: PartialMessages): void;
+export declare function changeIcons(newIcons: PartialIcons, newFamilyIcon?: IconFamily): void;
 export default class SelecticStore {
     props: InternalProps;
     state: SelecticStoreState;
@@ -152,7 +279,10 @@ export default class SelecticStore {
     private requestId;
     private cacheRequest;
     private closeSelectic;
+    /** Number of item to pre-display */
     marginSize: ComputedRef<number>;
+    /** If true, it is possible to click on group to select all items inside */
+    allowGroupSelection: ComputedRef<boolean>;
     isPartial: ComputedRef<boolean>;
     hasAllItems: ComputedRef<boolean>;
     hasFetchedAllItems: ComputedRef<boolean>;
@@ -165,13 +295,15 @@ export default class SelecticStore {
     setAutomaticClose(): void;
     getItem(id: OptionId): OptionValue;
     getItems(ids: OptionId[]): Promise<OptionItem[]>;
-    selectItem(id: OptionId, selected?: boolean, keepOpen?: boolean): void;
+    selectGroup(id: OptionId, itemsSelected: boolean): void;
+    selectItem(id: OptionId, selected?: boolean, keepOpen?: boolean): boolean;
     toggleSelectAll(): void;
     resetChange(): void;
     resetErrorMessage(): void;
     clearCache(forceReset?: boolean): void;
     changeGroups(groups: GroupValue[]): void;
     changeTexts(texts: PartialMessages): void;
+    changeIcons(icons: PartialIcons | null, family?: IconFamily | null): void;
     private hasValue;
     private getValue;
     private convertTypeValue;
@@ -179,6 +311,7 @@ export default class SelecticStore {
     private assertCorrectValue;
     private updateFilteredOptions;
     private addGroups;
+    /** This method is for the computed property listOptions */
     private getListOptions;
     private getElementOptions;
     private buildAllOptions;
@@ -196,5 +329,9 @@ export default class SelecticStore {
     private checkAutoSelect;
     private checkAutoDisabled;
     private checkHideFilter;
+    /** update group item, to mark them as selected if needed */
+    private updateGroupSelection;
+    /** assign new value to the filteredOptions and apply change depending on it */
+    private setFilteredOptions;
 }
 export {};

package/types/icons/caret-down.d.ts

@@ -0,0 +1,6 @@
+import { Vue, h } from 'vtyx';
+export interface Props {
+}
+export default class IconCaretDown extends Vue<Props> {
+    render(): h.JSX.Element;
+}

package/types/icons/caret-up.d.ts

@@ -0,0 +1,6 @@
+import { Vue, h } from 'vtyx';
+export interface Props {
+}
+export default class IconCaretUp extends Vue<Props> {
+    render(): h.JSX.Element;
+}

package/types/icons/check.d.ts

@@ -0,0 +1,6 @@
+import { Vue, h } from 'vtyx';
+export interface Props {
+}
+export default class IconCheck extends Vue<Props> {
+    render(): h.JSX.Element;
+}

package/types/icons/question.d.ts

@@ -0,0 +1,6 @@
+import { Vue, h } from 'vtyx';
+export interface Props {
+}
+export default class IconQuestion extends Vue<Props> {
+    render(): h.JSX.Element;
+}

package/types/icons/search.d.ts

@@ -0,0 +1,6 @@
+import { Vue, h } from 'vtyx';
+export interface Props {
+}
+export default class IconSearch extends Vue<Props> {
+    render(): h.JSX.Element;
+}

package/types/icons/spinner.d.ts

@@ -0,0 +1,6 @@
+import { Vue, h } from 'vtyx';
+export interface Props {
+}
+export default class IconSpinner extends Vue<Props> {
+    render(): h.JSX.Element;
+}

package/types/icons/strikeThrough.d.ts

@@ -0,0 +1,6 @@
+import { Vue, h } from 'vtyx';
+export interface Props {
+}
+export default class IconStrikeThrough extends Vue<Props> {
+    render(): h.JSX.Element;
+}

package/types/icons/times.d.ts

@@ -0,0 +1,6 @@
+import { Vue, h } from 'vtyx';
+export interface Props {
+}
+export default class IconTimes extends Vue<Props> {
+    render(): h.JSX.Element;
+}

package/types/index.d.ts

@@ -1,6 +1,6 @@
 import { Vue, h } from 'vtyx';
 import './css/selectic.css';
-import { OptionProp, OptionId, StrictOptionId, GroupValue, SelectedValue, FetchCallback, GetCallback, PartialMessages, OptionValue, OptionItem, FormatCallback, SelectionOverflow, ListPosition, HideFilter, SelectAllOption } from './Store';
+import { OptionProp, OptionId, StrictOptionId, GroupValue, SelectedValue, FetchCallback, GetCallback, PartialMessages, OptionValue, OptionItem, FormatCallback, SelectionOverflow, ListPosition, HideFilter, SelectAllOption, PartialIcons, IconFamily } from './Store';
 import MainInput from './MainInput';
 import ExtendedList from './ExtendedList';
 export { GroupValue, OptionValue, OptionItem, OptionProp, OptionId, StrictOptionId, SelectedValue, PartialMessages, GetCallback, FetchCallback, FormatCallback, SelectionOverflow, ListPosition, HideFilter, };
@@ -14,47 +14,109 @@ export interface EventChangeOptions extends EventOptions {
     isExcluded: boolean;
 }
 export interface ParamProps {
+    /** Method to call to fetch extra data */
     fetchCallback?: FetchCallback;
+    /** Method to call to get specific items */
     getItemsCallback?: GetCallback;
+    /** Number of elements to fetch.
+     * When scrolled too fast, a greater number of elements
+     * are going to be requested.
+     */
     pageSize?: number;
+    /** Hide the search control */
     hideFilter?: HideFilter;
+    /** Allow to reverse selection.
+     * If true, parent should support the selectionIsExcluded property.
+     * If false, the action is never available.
+     * If undefined, the action is available only when it is not needed to
+     * change selectionIsExcluded property.
+     */
     allowRevert?: boolean;
+    /** If true, the "select All" is still available even if all data are not fetched yet. */
     forceSelectAll?: SelectAllOption;
+    /** Allow user to clear the current selection */
     allowClearSelection?: boolean;
+    /** If false, avoid selecting the first available option. */
     autoSelect?: boolean;
+    /** Disable the select if no or only one option is given and must be selected. */
     autoDisabled?: boolean;
+    /** If true, value can be only in existing options. */
     strictValue?: boolean;
+    /** Define how to behave when selected items are too large for container.
+     *     collapsed (default): Items are reduced in width and an ellipsis
+     *                          is displayed in their name.
+     *     multiline: The container extends in height in order to display all
+     *                items.
+     */
     selectionOverflow?: SelectionOverflow;
+    /** In single mode, if no selection, this value is returned (default=null). */
     emptyValue?: SelectedValue;
+    /** Called when item is displayed in the list. */
     formatOption?: FormatCallback;
+    /** Called when item is displayed in the selection area. */
     formatSelection?: FormatCallback;
+    /** Define where the list should be displayed.
+     * With 'auto' it is displayed by default at bottom, but it can be at
+     * top if there is not enough space below. */
     listPosition?: ListPosition;
+    /** Described behavior when options from several sources are set (static, dynamic, slots)
+     * It describe what to do (sort or force)
+     * and the order (O → static options, D → dynamic options, E → slot elements)
+     * Example: "sort-ODE"
+     */
     optionBehavior?: string;
+    /** Keep this component open if another Selectic component opens */
     keepOpenWithOtherSelectic?: boolean;
+    /** Avoid click on group name to select all items in this group. */
+    disableGroupSelection?: boolean;
 }
 export declare type OnCallback = (event: string, ...args: any[]) => void;
 export declare type GetMethodsCallback = (methods: {
     clearCache: Selectic['clearCache'];
     changeTexts: Selectic['changeTexts'];
+    changeIcons: Selectic['changeIcons'];
     getValue: Selectic['getValue'];
     getSelectedItems: Selectic['getSelectedItems'];
     isEmpty: Selectic['isEmpty'];
     toggleOpen: Selectic['toggleOpen'];
 }) => void;
 export interface Props {
+    /** Selectic's initial value */
     value?: SelectedValue;
+    /** If true, the effective selection is the opposite */
     selectionIsExcluded?: boolean;
+    /** List of options to display */
     options?: OptionProp[];
+    /** Define groups of items (similar to optGroup) */
     groups?: GroupValue[];
+    /** Equivalent of <select>'s "multiple" attribute */
     multiple?: boolean;
+    /** Equivalent of <select>'s "disabled" attribute */
     disabled?: boolean;
+    /** Equivalent of <input>'s "placeholder" attribute */
     placeholder?: string;
+    /** id of the HTML element */
     id?: string;
+    /** CSS class of the HTML element */
     className?: string;
+    /** title on the HTML element */
     title?: string;
+    /** Replace the default texts used in Selectic */
     texts?: PartialMessages;
+    /** Replace the default icons used in Selectic */
+    icons?: PartialIcons;
+    /** Replace the default icon family used in Selectic */
+    iconFamily?: IconFamily;
+    /** If enabled, it resets the dynamic cache when selectic opens */
     noCache?: Boolean;
+    /** If true, the component opens (at start or if it is closed).
+     *  If false, the components closes (if it is opened). */
     open?: Boolean;
+    /** Props which is not expected to change during the life time of the
+     * component.
+     * These parameters modify the component behavior but are not official
+     * attributes of select.
+     */
     params?: ParamProps;
     /** _on is used mainly for tests.
      * Its purpose is to propagate $emit event mainly
@@ -67,6 +129,7 @@ export interface Props {
     _getMethods?: GetMethodsCallback;
 }
 export declare function changeTexts(texts: PartialMessages): void;
+export declare function changeIcons(icons: PartialIcons, iconFamily?: IconFamily): void;
 export default class Selectic extends Vue<Props> {
     $refs: {
         mainInput: MainInput;
@@ -83,6 +146,8 @@ export default class Selectic extends Vue<Props> {
     className: string;
     title?: string;
     texts?: PartialMessages;
+    icons?: PartialIcons;
+    iconFamily?: IconFamily;
     noCache: boolean;
     open?: boolean;
     params: ParamProps;
@@ -110,10 +175,17 @@ export default class Selectic extends Vue<Props> {
     })[];
     get hasGivenValue(): boolean;
     get defaultValue(): string | number | StrictOptionId[] | null;
+    /** Reset the inner cache (mainly for dynamic mode if context has changed) */
     clearCache(forceReset?: boolean): void;
+    /** Allow to change all text of the component */
     changeTexts(texts: PartialMessages): void;
+    /** Allow to change all icons of the component */
+    changeIcons(icons: PartialIcons, iconFamily?: IconFamily): void;
+    /** Return the current selection */
     getValue(): SelectedValue;
+    /** Return the current selection in Item format */
     getSelectedItems(): OptionValue | OptionValue[];
+    /** Check if there are Options available in the components */
     isEmpty(): boolean;
     toggleOpen(open?: boolean): boolean;
     private computeWidth;
@@ -125,6 +197,7 @@ export default class Selectic extends Vue<Props> {
     onExcludedChange(): void;
     onOptionsChange(): void;
     onTextsChange(): void;
+    onIconsChange(): void;
     onDisabledChange(): void;
     onGroupsChanged(): void;
     onPlaceholderChanged(): void;