selectic 3.0.21 → 3.1.0

package/doc/params.md

@@ -2,46 +2,93 @@
 
 [Back to documentation index](main.md)
 
+[List of all properties](properties.md)
+
 In property `params` you can configure selectic to behave the way you want.
 All configurations set in this property should not change during the component life.
 
 This property is an object with several attributes which are listed below.
 
+* [allowClearSelection](params.md#allowclearselection)
+* [allowRevert](params.md#allowrevert)
+* [autoDisabled](params.md#autodisabled)
+* [autoSelect](params.md#autoselect)
+* [disableGroupSelection](params.md#disableGroupSelection)
+* [emptyValue](params.md#emptyvalue)
+* [fetchCallback](params.md#fetchcallback)
+* [forceSelectAll](params.md#forceselectall)
+* [formatOption](params.md#formatoption)
+* [formatSelection](params.md#formatselection)
+* [getItemsCallback](params.md#getitemscallback)
+* [hideFilter](params.md#hidefilter)
+* [keepOpenWithOtherSelectic](params.md#keepopenwithotherselectic)
+* [listPosition](params.md#listposition)
+* [optionBehavior](params.md#optionbehavior)
+* [pageSize](params.md#pagesize)
+* [selectionOverflow](params.md#selectionoverflow)
+* [strictValue](params.md#strictvalue)
 
-## hideFilter
+## allowClearSelection
 
-Type: `boolean` | `'auto'` | `'open'`
+Type: `boolean`
 
-If `hideFilter` is set to `true`, the handler to open the filter panel is hidden and it will not be possible to search for options.
+If `allowClearSelection` is set to `true`, it will be possible to remove the selection to have nothing selected.
 
-If `hideFilter` is set to `'auto`, the handler to open the filter panel is hidden only if there is less than 10 options (when there is no scroll), and is displayed otherwise. _This is the default value_.
+If `allowClearSelection` is set to `false`, it won't be possible to have nothing selected since an item has been selected. _This is the default value_.
 
-If `hideFilter` is set to `false`, the handler to open the filter panel is always displayed.
+```html
+<selectic
+    :params="{
+        allowClearSelection: true,
+    }"
+    :options="optionList"
+/>
+```
 
-If `hideFilter` is set to `'open'`, the handler to open or close the filter panel
-will not be displayed and the filter panel is always open.
+## allowRevert
+
+Type: `boolean` | `undefined`
+
+In _multiple_ mode, it is possible to invert the selection.
+However in _dynamic_ mode selectic does not know all options so it cannot select the opposite selections.
+
+To allow this feature in _dynamic_ mode, there is a property `selectionIsExcluded` which means that values returned by `getValue()`, `getSelection()` or emitted events are the ones which are not selected.
+
+As this behavior is more complex, it is needed to set `allowRevert` to `true` to enable it.
+
+Read [the dynamic documentation](dynamic.md) for more information.
+
+If `allowRevert` is set to `false`, the action to invert the selection will always be disabled.
+
+If `allowRevert` is set to `true`, the action to invert the selection will always be enabled. The parent of selectic component should support `selectionIsExcluded` property (which can be applied in _dynamic_ mode).
+
+If `allowRevert` is set to `undefined` (is not set), the action to invert the selection will be enabled only if the `selectionIsExcluded` property is not needed (always in _static_ mode, and in _dynamic_ mode when all options are already fetched).
+
+Read [the extended properties documentation](extendedProperties.md) for more information about `selectionIsExcluded`.
 
 ```html
 <selectic
     :params="{
-        hideFilter: false,
+        allowRevert: true,
     }"
     :options="optionList"
 />
 ```
 
-## allowClearSelection
+## autoDisabled
 
 Type: `boolean`
 
-If `allowClearSelection` is set to `true`, it will be possible to remove the selection to have nothing selected.
+If `autoDisabled` is set to `true`, it will disable automatically the component if the list of options is empty or if there is only one which must be selected (`allowClearSelection` is not set).
 
-If `allowClearSelection` is set to `false`, it won't be possible to have nothing selected since an item has been selected. _This is the default value_.
+It doesn't apply for dynamic list ([see dynamic configuration](dynamic.md)).
+
+By default, it is set to `true`.
 
 ```html
 <selectic
     :params="{
-        allowClearSelection: true,
+        autoDisabled: true,
     }"
     :options="optionList"
 />
@@ -66,73 +113,108 @@ By default, it is set to `true` if `multiple` is not set, to `false` otherwise.
 />
 ```
 
-## autoDisabled
+## disableGroupSelection
 
 Type: `boolean`
 
-If `autoDisabled` is set to `true`, it will disable automatically the component if the list of options is empty or if there is only one which must be selected (`allowClearSelection` is not set).
+In multiple mode, if there are groups. It is possible to select all items
+under this group by clicking only on the group name.
 
-It doesn't apply for dynamic list ([see dynamic configuration](dynamic.md)).
+If `disableGroupSelection` is set to `true`, it will not be possible to click on the group (and so it will not select the items inside it).
 
-By default, it is set to `true`.
+By default, it is set to `false`.
+
+Note: Enabling this option may improve performance with long list of options.
 
 ```html
 <selectic
     :params="{
-        autoDisabled: true,
+        autoSelect: false,
     }"
     :options="optionList"
 />
 ```
 
-## strictValue
+### group selection
 
-Type: `boolean`
+Clicking on a group name, will select all items inside it.
 
-If `strictValue` is set to `true`, it will consider value as `undefined` if its value is not an id of `options`.
+If all items are already selected, then they all become unselected.
 
-By default, it is set to `false`.
+This behavior works only with the following condition:
+
+* multiple mode should be enabled: we should be able to select several items.
+
+* the component should be in static mode: otherwise it will not be possible to know which items are not loaded yet.
+
+* the group should not be disabled: this is a way to forbid this action on some groups.
+
+* the parameter `disableGroupSelection` should not be `true`: this is to disabled this behavior.
+
+Moreover in the group some items may be not (un)selected:
+
+* The item should not be disabled: it should not be possible to select a disabled item
+
+* The item should not use exclusive mode: because otherwise only this one should be selected.
+
+* Only items that matches the search will be selected: only visible items are (un)selected.
+
+## emptyValue
+
+Type: `OptionId`
+
+By default, if there is no selected options, the result given by `getValue()` returns `null`  (or `[]` in _multiple_ mode).
+
+`emptyValue` allows to change this default value.
 
 ```html
 <selectic
     :params="{
-        strictValue: true,
+        emptyValue: '',
     }"
     :options="optionList"
 />
 ```
 
-## selectionOverflow
+## fetchCallback
 
-Type: `'collapsed'` | `'multiline'`
+Type: `function (search, offset, limit) => Promise<{total, result}>`
 
-`selectOverflow` is to describe how selected options should be displayed when they are not enough space to display them all (in _multiple_ mode).
+The purpose of this function is to return a list of option dynamically. With it, it is possible to fetch data build the list asynchronously (useful for very large list).
 
-Currently there are two supported behavior:
-* `'collapsed'`: the size of selectic input is not changed. If there is not enough space to display all selected options then it displays the possible ones then displays a _"+x others"_ in a badge (_x_ is the number of not displayed options). It is possible to watch these options with `title` or by opening selectic and see which options are selected. _This is the default value_.
-* `'multiline'`: If there is not enough space to display all selected options then it displays the others on another line. The size of the component can be higher than the allowed space.
+Read [the dynamic documentation](dynamic.md) for more information.
+
+It should return a promise which resolves with an object which contains the total number of items and the list of options asked by the request.
 
 ```html
 <selectic
     :params="{
-        selectionOverflow: 'multiple',
+        fetchCallback: (search, offset, limit) => fetch(`list?search=${search}&offset=${offset}&limit=${limit}`),
     }"
     :options="optionList"
 />
 ```
 
-## emptyValue
+## forceSelectAll
 
-Type: `OptionId`
+Type: `'auto' | 'visible'`
 
-By default, if there is no selected options, the result given by `getValue()` returns `null`  (or `[]` in _multiple_ mode).
+Default value: `'auto'`
 
-`emptyValue` allows to change this default value.
+In _multiple_ mode, there is a "select all" action.
+If the selection inversion is not available and all data are not fetched (in
+_dynamic_ mode) it will not be possible to select all items. So this action
+will be disabled.
+
+This option allows you to change the behavior.
+
+* `'auto'`: The action is disabled when not possible.
+* `'visible'`: The action is displayed even when all data are not fetched.
 
 ```html
 <selectic
     :params="{
-        emptyValue: '',
+        forceSelectAll: 'auto',
     }"
     :options="optionList"
 />
@@ -184,25 +266,6 @@ As argument, it receives an option item and should also return an option item.
 />
 ```
 
-## fetchCallback
-
-Type: `function (search, offset, limit) => Promise<{total, result}>`
-
-The purpose of this function is to return a list of option dynamically. With it, it is possible to fetch data build the list asynchronously (useful for very large list).
-
-Read [the dynamic documentation](dynamic.md) for more information.
-
-It should return a promise which resolves with an object which contains the total number of items and the list of options asked by the request.
-
-```html
-<selectic
-    :params="{
-        fetchCallback: (search, offset, limit) => fetch(`list?search=${search}&offset=${offset}&limit=${limit}`),
-    }"
-    :options="optionList"
-/>
-```
-
 ## getItemsCallback
 
 Type: `function (optionId[]) => Promise<option[]>`
@@ -225,85 +288,48 @@ It should return a promise which resolves with an array of options corresponding
 />
 ```
 
-## pageSize
-
-Type: `number`
-
-`pageSize` is the number of options requested in dynamic mode when selectic needs to display more options than it has in cache.
-
-By changing this value you can optimize performance result (more or less requests vs memory cache consumption).
-
-Read [the dynamic documentation](dynamic.md) for more information.
-
-Selectic displays 10 options at a time, but it will call for a new request as soon as the last option index reach the half of page size.
-
-_`pageSize` default value is `100`._
-
-```html
-<selectic
-    :params="{
-        pageSize: 500,
-    }"
-    :options="optionList"
-/>
-```
-
-## allowRevert
-
-Type: `boolean` | `undefined`
-
-In _multiple_ mode, it is possible to invert the selection.
-However in _dynamic_ mode selectic does not know all options so it cannot select the opposite selections.
-
-To allow this feature in _dynamic_ mode, there is a property `selectionIsExcluded` which means that values returned by `getValue()`, `getSelection()` or emitted events are the ones which are not selected.
-
-As this behavior is more complex, it is needed to set `allowRevert` to `true` to enable it.
+## hideFilter
 
-Read [the dynamic documentation](dynamic.md) for more information.
+Type: `boolean` | `'auto'` | `'open'`
 
-If `allowRevert` is set to `false`, the action to invert the selection will always be disabled.
+If `hideFilter` is set to `true`, the handler to open the filter panel is hidden and it will not be possible to search for options.
 
-If `allowRevert` is set to `true`, the action to invert the selection will always be enabled. The parent of selectic component should support `selectionIsExcluded` property (which can be applied in _dynamic_ mode).
+If `hideFilter` is set to `'auto`, the handler to open the filter panel is hidden only if there is less than 10 options (when there is no scroll), and is displayed otherwise. _This is the default value_.
 
-If `allowRevert` is set to `undefined` (is not set), the action to invert the selection will be enabled only if the `selectionIsExcluded` property is not needed (always in _static_ mode, and in _dynamic_ mode when all options are already fetched).
+If `hideFilter` is set to `false`, the handler to open the filter panel is always displayed.
 
-Read [the extended properties documentation](extendedProperties.md) for more information about `selectionIsExcluded`.
+If `hideFilter` is set to `'open'`, the handler to open or close the filter panel
+will not be displayed and the filter panel is always open.
 
 ```html
 <selectic
     :params="{
-        allowRevert: true,
+        hideFilter: false,
     }"
     :options="optionList"
 />
 ```
 
-## forceSelectAll
-
-Type: `'auto' | 'visible'`
+## keepOpenWithOtherSelectic
 
-Default value: `'auto'`
+Type: `boolean`
 
-In _multiple_ mode, there is a "select all" action.
-If the selection inversion is not available and all data are not fetched (in
-_dynamic_ mode) it will not be possible to select all items. So this action
-will be disabled.
+Default value: `false`
 
-This option allows you to change the behavior.
+By default, only one selectic component can be open at the same time. So if another Selectic component is open (mainly programmatically) then any previously open component is closed.
+If `keepOpenWithOtherSelectic` is set to `true`, this component stays open when another Selectic component opens.
 
-* `'auto'`: The action is disabled when not possible.
-* `'visible'`: The action is displayed even when all data are not fetched.
+Note: This attribute does not prevent closing when user clicks outside the component.
 
 ```html
 <selectic
     :params="{
-        forceSelectAll: 'auto',
+        keepOpenWithOtherSelectic: true,
     }"
     :options="optionList"
 />
 ```
 
-
 ## listPosition
 
 Type: `'auto' | 'bottom' | 'top'`
@@ -363,21 +389,60 @@ Display only one source (the first which is not empty).
 />
 ```
 
-## keepOpenWithOtherSelectic
+## pageSize
 
-Type: `boolean`
+Type: `number`
 
-Default value: `false`
+`pageSize` is the number of options requested in dynamic mode when selectic needs to display more options than it has in cache.
 
-By default, only one selectic component can be open at the same time. So if another Selectic component is open (mainly programmatically) then any previously open component is closed.
-If `keepOpenWithOtherSelectic` is set to `true`, this component stays open when another Selectic component opens.
+By changing this value you can optimize performance result (more or less requests vs memory cache consumption).
 
-Note: This attribute does not prevent closing when user clicks outside the component.
+Read [the dynamic documentation](dynamic.md) for more information.
+
+Selectic displays 10 options at a time, but it will call for a new request as soon as the last option index reach the half of page size.
+
+_`pageSize` default value is `100`._
 
 ```html
 <selectic
     :params="{
-        keepOpenWithOtherSelectic: true,
+        pageSize: 500,
+    }"
+    :options="optionList"
+/>
+```
+
+## selectionOverflow
+
+Type: `'collapsed'` | `'multiline'`
+
+`selectOverflow` is to describe how selected options should be displayed when they are not enough space to display them all (in _multiple_ mode).
+
+Currently there are two supported behavior:
+* `'collapsed'`: the size of selectic input is not changed. If there is not enough space to display all selected options then it displays the possible ones then displays a _"+x others"_ in a badge (_x_ is the number of not displayed options). It is possible to watch these options with `title` or by opening selectic and see which options are selected. _This is the default value_.
+* `'multiline'`: If there is not enough space to display all selected options then it displays the others on another line. The size of the component can be higher than the allowed space.
+
+```html
+<selectic
+    :params="{
+        selectionOverflow: 'multiple',
+    }"
+    :options="optionList"
+/>
+```
+
+## strictValue
+
+Type: `boolean`
+
+If `strictValue` is set to `true`, it will consider value as `undefined` if its value is not an id of `options`.
+
+By default, it is set to `false`.
+
+```html
+<selectic
+    :params="{
+        strictValue: true,
     }"
     :options="optionList"
 />

package/doc/properties.md

@@ -0,0 +1,42 @@
+# Properties
+
+[Back to documentation index](main.md)
+
+## DOM properties
+
+* [className](domProperties.md#classname) (instead of `class` in order to be
+applied on main element and on the list element)
+* [disabled](domProperties.md#disabled)
+* [id](domProperties.md#id)
+* [multiple](domProperties.md#multiple)
+* [placeholder](domProperties.md#placeholder)
+* [title](domProperties.md#title)
+* [value](domProperties.md#value)
+
+## Extended properties
+
+* [groups](extendedProperties.md#groups)
+* [noCache](extendedProperties.md#nocache)
+* [open](extendedProperties.md#open)
+* [options](extendedProperties.md#options)
+* [selectionIsExcluded](extendedProperties.md#selectionisexcluded)
+* [texts](extendedProperties.md#texts)
+* [params](extendedProperties.md#params)
+    * [allowClearSelection](params.md#allowclearselection)
+    * [allowRevert](params.md#allowrevert)
+    * [autoDisabled](params.md#autodisabled)
+    * [autoSelect](params.md#autoselect)
+    * [disableGroupSelection](params.md#disableGroupSelection)
+    * [emptyValue](params.md#emptyvalue)
+    * [fetchCallback](params.md#fetchcallback)
+    * [forceSelectAll](params.md#forceselectall)
+    * [formatOption](params.md#formatoption)
+    * [formatSelection](params.md#formatselection)
+    * [getItemsCallback](params.md#getitemscallback)
+    * [hideFilter](params.md#hidefilter)
+    * [keepOpenWithOtherSelectic](params.md#keepopenwithotherselectic)
+    * [listPosition](params.md#listposition)
+    * [optionBehavior](params.md#optionbehavior)
+    * [pageSize](params.md#pagesize)
+    * [selectionOverflow](params.md#selectionoverflow)
+    * [strictValue](params.md#strictvalue)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "selectic",
-    "version": "3.0.21",
+    "version": "3.1.0",
     "description": "Smart Select for VueJS 3.x",
     "main": "dist/selectic.common.js",
     "module": "dist/selectic.esm.js",
@@ -38,13 +38,13 @@
         "test": "npm run build && tape test/**/*.spec.js"
     },
     "dependencies": {
-        "vtyx": "4.0.5"
+        "vtyx": "4.2.1"
     },
     "devDependencies": {
-        "@babel/types": "^7.21.2",
+        "@babel/types": "^7.23.6",
         "rollup": "^2.79.1",
         "rollup-plugin-postcss": "^4.0.2",
-        "tape": "^4.16.2",
+        "tape": "^4.17.0",
         "typescript": "~4.8"
     }
 }

package/src/ExtendedList.tsx

@@ -4,10 +4,12 @@
  */
 
 import {Vue, Component, Prop, Watch, h} from 'vtyx';
+import { unref } from 'vue';
 
-import Store, { OptionId } from './Store';
+import Store, { OptionId, OptionItem } from './Store';
 import Filter from './Filter';
 import List from './List';
+import Icon from './Icon';
 
 export interface Props {
     store: Store;
@@ -50,7 +52,8 @@ export default class ExtendedList extends Vue<Props> {
     /* }}} */
     /* {{{ data */
 
-    private topGroup = ' ';
+    private topGroupName = ' ';
+    private topGroupId: OptionId = null;
     private listHeight = 0;
     private listWidth = 200;
     private availableSpace = 0;
@@ -224,6 +227,32 @@ export default class ExtendedList extends Vue<Props> {
         `;
     }
 
+    get topGroup(): OptionItem | undefined {
+        const topGroupId = this.topGroupId;
+
+        if (!topGroupId) {
+            return undefined;
+        }
+
+        const group = this.store.state.filteredOptions.find((option) => {
+            return option.id === topGroupId;
+        });
+
+        return group;
+    }
+
+    get topGroupSelected(): boolean {
+        const group = this.topGroup;
+
+        return !!group?.selected;
+    }
+
+    get topGroupDisabled(): boolean {
+        const group = this.topGroup;
+
+        return !!group?.disabled;
+    }
+
     /* }}} */
     /* {{{ watch */
 
@@ -244,7 +273,8 @@ export default class ExtendedList extends Vue<Props> {
         const group = this.store.state.groups.get(id);
         const groupName = group || ' ';
 
-        this.topGroup = groupName;
+        this.topGroupName = groupName;
+        this.topGroupId = id;
     }
 
     private computeListSize() {
@@ -254,6 +284,10 @@ export default class ExtendedList extends Vue<Props> {
         this.listWidth = box.width;
     }
 
+    private clickHeaderGroup() {
+        this.store.selectGroup(this.topGroupId, !this.topGroupSelected);
+    }
+
     /* }}} */
     /* {{{ Life cycles */
 
@@ -296,9 +330,22 @@ export default class ExtendedList extends Vue<Props> {
 
               {isGroup && (
                 <span
-                    class="selectic-item selectic-item--header selectic-item__is-group"
+                    class={[
+                        'selectic-item selectic-item--header selectic-item__is-group',
+                        {
+                            selected: this.topGroupSelected,
+                            selectable: unref(this.store.allowGroupSelection) && !this.topGroupDisabled,
+                            disabled: this.topGroupDisabled,
+                        },
+                    ]}
+                    on={{
+                        click: () => this.clickHeaderGroup(),
+                    }}
                 >
-                    {this.topGroup}
+                  {this.topGroupSelected && (
+                    <Icon icon="check" store={this.store} class="selectic-item_icon" />
+                  )}
+                    {this.topGroupName}
                 </span>
               )}
                 <List
@@ -314,7 +361,7 @@ export default class ExtendedList extends Vue<Props> {
               )}
               {this.searching && (
                 <div class="selectic__message">
-                    <span class="fa fa-spinner fa-spin"></span>
+                    <Icon icon="spinner" store={this.store} spin />
                     {this.searchingLabel}
                 </div>
               )}

package/src/Filter.tsx

@@ -6,6 +6,7 @@ import {Vue, Component, Prop, Watch, h} from 'vtyx';
 import { unref } from 'vue';
 
 import Store from './Store';
+import Icon from './Icon';
 
 export interface Props {
     store: Store;
@@ -185,9 +186,11 @@ export default class FilterPanel extends Vue<Props> {
                             }}
                             ref="filterInput"
                         />
-                        <span class="fa fa-search selectic-search-scope
-                                     form-control-feedback"
-                        ></span>
+                        <Icon
+                            icon="search"
+                            store={this.store}
+                            class="selectic-search-scope form-control-feedback"
+                        />
                     </div>
                     {state.multiple && (
                         <div class="toggle-selectic">
@@ -236,12 +239,11 @@ export default class FilterPanel extends Vue<Props> {
                          'click.prevent.stop': this.togglePanel,
                      }}
                 >
-                    <span class="fa fa-search"></span>
-                    <span class={{
-                        'fa': true,
-                        'fa-caret-down': this.closed,
-                        'fa-caret-up': !this.closed,
-                    }}></span>
+                    <Icon icon="search" store={this.store} />
+                    <Icon
+                        icon={this.closed ? 'caret-down' : 'caret-up'}
+                        store={this.store}
+                    />
                 </div>
                 )}
            </div>