selectic 3.0.21 → 3.1.0

package/doc/changeIcons.md

@@ -0,0 +1,118 @@
+# Change icons
+
+[Back to documentation index](main.md)
+
+There are some icons in selectic. But sometimes it is useful to change them (because you want to use yours or the same of your favorite theme).
+
+There are 3 ways to changes these icons:
+* Call the static `changeIcons()` method. It changes icons for all selectic components.
+* Change the `icons` property. It changes icons only for the component.
+* Change the `iconFamily` property. It changes the icons origin only for the component.
+* Call the `changeIcons()` method on the component. It changes icons only for the component.
+
+_Changes made locally take precedence over changes made globally_.
+
+Changing `icons` or `iconFamily` on the component with property or with `changeIcons()` are equivalent.
+
+`icons` and the first argument of `changeIcons` accept the same kind of value: an object which contains icon keys and how to display them.
+
+It is possible to replace only some icons.
+
+`iconFamily` and the second argument of `changeIcons` accept a string describing how to display icons.
+
+## Icon family
+
+* **selectic** _(default)_: use the internal icons
+
+* **raw**: will create a span with the icon key as class (without any other prefix)
+
+* **font-awesome-4**: will create a span with font-awesome (v4) class.
+_Font-awesome is not include in Selectic, your project should have it_.
+
+* **font-awesome-5**: will create a span with font-awesome (v5) class.
+_Font-awesome is not include in Selectic, your project should have it_.
+
+* **font-awesome-6**: will create a span with font-awesome (v6) class.
+_Font-awesome is not include in Selectic, your project should have it_.
+
+* **prefix:_[string]_**: will create a span and will add the given string as class before the icon key.
+
+Example:
+```html
+<Selectic iconFamily="prefix:my-icon-" />
+```
+The icon `search` will be displayed like this:
+```html
+<span class="my-icon-search"></span>
+```
+
+## Icon Keys
+
+* **caret-down**: indicates that menu or panel could be extended down.
+* **caret-up**: indicates that panel could be collapsed upward.
+* **check**: indicates that the item is currently selected.
+* **search**: indicates the search bar.
+* **spinner**: indicates that we are fetching data.
+* **strikethrough**: indicates that we are in reverse selection mode.
+* **times**: used to clear the current selection.
+* **question**: used when the icon key is not found. _It should be never displayed._
+
+* **spin**: additional class added to rotate the current icon (used mainly with spinner).
+
+The value indicates what should be used instead of the icon key.
+
+It is possible to use `selectic:` prefix to display the original selectic icon, even if the icon family is configured differently.
+
+It is possible to use `raw:` prefix to display an icon with a span and only the given class (with no prefix).
+
+In some case, the prefix `current:` could be used to use the current icon family.
+
+
+With `selectic:`, `raw:`, or `current:` prefix, it is also possible to add a `:spin` suffix in order to add the _spin_ on the icon.
+
+Example:
+```javascript
+{
+    spinner: 'selectic:spinner:spin', // it will use the Selectic's spinner icon with the spin effect
+    search: 'current:cogs:spin', // it will use "cogs" as key in the current icon family, and will adds the spin effect
+}
+```
+
+## Example
+
+```javascript
+// change icons for all selectic components
+Selectic.changeIcons({
+    times: 'trash',
+    spinner: 'selectic:spinner',
+}, 'font-awesome-6');
+
+/* The icon 'times' will be displayed:
+ *     <span class="fa-solid fa-trash"></span>
+ *
+ * The icon 'spinner' will use the selectic's spinner icon.
+ */
+
+// change texts only for this instance
+this.$refs.selectic.changeIcons({
+    'caret-up': 'caret-down',
+});
+/* For this selectic instance,
+ * the caret-down icon will be displayed when it should be the caret-up.
+ * (caret-down will still be used for caret-down)
+ */
+
+```
+
+```html
+<Selectic
+    :icons="{
+        check: 'thumbs-o-up',
+    }"
+    iconFamily="font-awesome-4"
+/>
+
+/* For this selectic instance, the selected icon will be displayed:
+ * <span class="fa fa-thumbs-o-up"></span>
+ */
+```

package/doc/changeText.md

@@ -9,7 +9,7 @@ There are 3 ways to changes these texts:
 * Change the `texts` property. It changes texts only for the component.
 * Call the `changeTexts()` method on the component. It changes texts only for the component.
 
-_Changes done locally are prioritary on changes done globally_.
+_Changes made locally take precedence over changes made globally._.
 
 Changing texts on the component with property or with `changeTexts()` are equivalent.
 

package/doc/domProperties.md

@@ -2,50 +2,79 @@
 
 [Back to documentation index](main.md)
 
+[List of all properties](properties.md)
+
 `<select>` has several properties which can be used in the same way in `selectic`.
 
-## id
+* [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)
 
-It defines a unique identifier (ID) which must be unique in the whole document. It is applied on an `<input>` element which contains the current state.
+[Not supported attributes](domProperties.md#not-supported-attributes)
+
+## className
+
+Type: `string`
+
+Default: `''`
+
+The given string will be applied as class to the main element and also to the list element.
+It can be used instead of class for when it is not possible to use the reserved keyword.
+Note that it will be applied to the inner list element too.
 
 ```html
 <selectic
     :options="['item1', 'item2']"
     value="item2"
-    id="example"
+    className="my-custom-class another-class"
 />
 ```
-```javascript
-document.getElementById('example').value; // 'item2'
-```
 
+## disabled
 
-## value
+Type: `boolean`
 
-The selected value.  This is the initial value, and it can be altered to change the current selection.
+Default: `false`
 
-This is the id of the selected option or an array of id (if `multiple` is set).
+When disabled is set, `selectic` cannot be open nor changed.
 
 ```html
 <selectic
     :options="['item1', 'item2']"
-    value="item2"
+    disabled
 />
 ```
 
-## disabled
+## id
 
-When disabled is set, `selectic` cannot be open nor changed.
+Type: `string`
+
+Default: `''`
+
+It defines a unique identifier (ID) which must be unique in the whole document. It is applied on an `<input>` element which contains the current state.
 
 ```html
 <selectic
     :options="['item1', 'item2']"
-    disabled
+    value="item2"
+    id="example"
 />
 ```
+```javascript
+document.getElementById('example').value; // 'item2'
+```
 
 ## multiple
 
+Type: `boolean`
+
+Default: `false`
+
 If set then several options can be selected.
 
 The `value` will be an array.
@@ -59,6 +88,10 @@ The `value` will be an array.
 
 ## placeholder
 
+Type: `string`
+
+Default: `''`
+
 `placeholder` is not really a DOM attribute as it doesn't exist on `<select>` element. But it behaves like placeholder on `<input>`.
 
 It displays the given text if no option is selected.
@@ -72,6 +105,10 @@ It displays the given text if no option is selected.
 
 ## title
 
+Type: `string`
+
+Default: `''`
+
 It is added to the main element, and it behaves like `title` attribute of any HTML element when mouse is over the selected area.
 
 ```html
@@ -81,19 +118,20 @@ It is added to the main element, and it behaves like `title` attribute of any HT
 />
 ```
 
-## className
+## value
 
-Type: `string`
+Type: `optionId` or `optionId[]`
 
-The given string will be applied as class to the main element and also to the list element.
-It can be used instead of class for when it is not possible to use the reserved keyword.
-Note that it will be applied to the inner list element too.
+Default: `null` or `[]`
+
+The selected value.  This is the initial value, and it can be altered to change the current selection.
+
+This is the id of the selected option or an array of id (if `multiple` is set).
 
 ```html
 <selectic
     :options="['item1', 'item2']"
     value="item2"
-    className="my-custom-class another-class"
 />
 ```
 

package/doc/extendedProperties.md

@@ -2,56 +2,35 @@
 
 [Back to documentation index](main.md)
 
-Selectic supports common properties which are related to `<select>` element ([read dom properties document](domProperties.md)), but they are some more which are more related to the nature of selectic.
-
-## value
-
-Type: `optionId` or `optionId[]`
-
-Default: `null` or `[]`
-
-The selected value.  This is the initial value, and it can be altered to change the current selection.
-
-This is the id of the selected option or an array of id (if `multiple` is set).
-
-```html
-<selectic
-    :options="['item1', 'item2']"
-    value="item2"
-/>
-```
-
-## selectionIsExcluded
-
-Type: `boolean`
-
-Default: `false`
-
-It should be only used in _multiple_ mode.
-
-If it is set to `true`, it means that current `value` are options which are **not** selected.
-
-It is useful with _dynamic_ mode where it is not possible to fetch all options.
-
-This value can be changed automatically by selectic if all options are fetched.
+[List of all properties](properties.md)
 
-```html
-<selectic
-    :options="['item1', 'item2']"
-    value="item2"
-    selectionIsExcluded
-/>
-```
-
-## options
-
-Type: `Option[]`
-
-Default: `[]`
+Selectic supports common properties which are related to `<select>` element ([read dom properties document](domProperties.md)), but they are some more which are more related to the nature of selectic.
 
-This property is to list all options available ([read how to build a list](list.md)).
+* [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)
+    * [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)
 
-This property can be omitted in dynamic mode ([read how to build dynamic list](dynamic.md)).
 
 ## groups
 
@@ -75,31 +54,6 @@ It is required to fill this property only in _dynamic_ mode in order to know to
 />
 ```
 
-## texts
-
-Type: `Object`
-
-Default: `{}`
-
-The `texts` property is to change texts in the component.
-
-It is possible to change all texts or only some.
-
-It changes the texts only for this component. To change texts for all selectic components, you should use the static method `changeTexts()`.
-
-[Read the documentation about changing text](changeText.md).
-
-```html
-<selectic
-    :options="['Goldfish', 'Salmon', 'Trout', 'Tuna']"
-    value="Tuna"
-    :texts="{
-        searchPlaceholder: 'Search for fish',
-        noResult: 'No fish matched your search',
-    }"
-/>
-```
-
 ## noCache
 
 Type: `Boolean`
@@ -146,6 +100,63 @@ It is also possible to change the "open" state with the method [toggleOpen](meth
 />
 ```
 
+## options
+
+Type: `Option[]`
+
+Default: `[]`
+
+This property is to list all options available ([read how to build a list](list.md)).
+
+This property can be omitted in dynamic mode ([read how to build dynamic list](dynamic.md)).
+
+## selectionIsExcluded
+
+Type: `boolean`
+
+Default: `false`
+
+It should be only used in _multiple_ mode.
+
+If it is set to `true`, it means that current `value` are options which are **not** selected.
+
+It is useful with _dynamic_ mode where it is not possible to fetch all options.
+
+This value can be changed automatically by selectic if all options are fetched.
+
+```html
+<selectic
+    :options="['item1', 'item2']"
+    value="item2"
+    selectionIsExcluded
+/>
+```
+
+## texts
+
+Type: `Object`
+
+Default: `{}`
+
+The `texts` property is to change texts in the component.
+
+It is possible to change all texts or only some.
+
+It changes the texts only for this component. To change texts for all selectic components, you should use the static method `changeTexts()`.
+
+[Read the documentation about changing text](changeText.md).
+
+```html
+<selectic
+    :options="['Goldfish', 'Salmon', 'Trout', 'Tuna']"
+    value="Tuna"
+    :texts="{
+        searchPlaceholder: 'Search for fish',
+        noResult: 'No fish matched your search',
+    }"
+/>
+```
+
 ## params
 
 Type: `Object`

package/doc/main.md

@@ -3,6 +3,7 @@
 ## Configuration
 
 * Build a select from a list [(details)](./list.md)
+* List all supported properties [(details)](./properties.md)
 * Support DOM attributes [(details)](./domProperties.md)
   * value
   * disabled
@@ -14,6 +15,7 @@
   * optgroup
 * Advanced configuration [(details)](./params.md)
 * Change texts [(details)](./changeText.md)
+* Change icons [(details)](./changeIcons.md)
 * Change CSS style [(details)](./css.md)
 
 ## Events