Option Picker 2.0.0

# Usage

Note: CSS variables have been removed since version 2.0.0. From now on, I will only provide a minimal style just to make viable interaction. Expect it to look ugly by default. The main goal of this application is to be able to integrate it seamlessly into your web design. By providing a minimal style, it is easy to add other styles to it to adapt it to your own web design. Have a look at the source code on this page to see how I adapted the style to resemble the default style of the previous version.

Browser

<!DOCTYPE html>
<html dir="ltr">
  <head>
    <meta charset="utf-8">
    <link href="./index.min.css" rel="stylesheet">
    <style>
      .option-picker {
        width: 100%;
      }
      .option-picker__options {
        background: #fff;
      }
    </style>
  </head>
  <body>
    <p>
      <select>
        <option>
          Option 1
        </option>
        <option>
          Option 2
        </option>
        <option value="3">
          Option 3
        </option>
      </select>
    </p>
    <script src="./index.min.js"></script>
    <script>
      const picker = new OptionPicker(document.querySelector('select'));
    </script>
  </body>
</html>

Node.js

Functions and methods in this application are mostly native JavaScript and are intended for use by the browser. Node.js doesn’t know about the DOM, so this kind of practice will probably be used more often to build new browser packages than to be used directly in the Node.js server.

CommonJS

const OptionPicker = require('@taufik-nurrohman/option-picker').default;

const picker = new OptionPicker(document.querySelector('select'));

ECMAScript

import OptionPicker from '@taufik-nurrohman/option-picker';

const picker = new OptionPicker(document.querySelector('select'));

# Tests

# Tweaks

Bootstrap v5.3 Style (Drop-Down Component)

Bootstrap v5.3 Style (Form Control Select)

Fade Animation

Header in Options

Slide Animation

# Constructor

const picker = new OptionPicker(self, strict = false);

const picker = new OptionPicker(self, state = {
    max: null,
    min: null,
    options: null,
    size: null,
    strict: false,
    with: []
});

# Parameters

`self`

The <input> or <select> element.

`strict`

Do not allow users to enter a value other than those available in the options list on the “loose” option picker presentation. Pressing the Tab key will automatically select the first active option.

`state`

The configuration data.

`state.max`

Determines the maximum number of options that can be selected on the option picker that are sourced from a <select multiple> element. It has a default value set to Infinity. If the source element is an <input> element, then its default value will be 1. This means that the multiple selection feature will apply only to <select> element.

`state.min`

Determines the minimum number of options that can be selected on the option picker. If the source element is a <select> element, the default value will be 1; if the source element is an <input> element, the default value will be 0.

`state.options`

A list of options data as an array, an object, a map, or a function that returns an array, an object, or a map.

Array is the easiest data structure to write, it guarantees that the order will remain the same when transformed into a series of options. With this kind of data structure, where each element is a scalar, the option label will also act as a value after it is transformed into an options list. This is equivalent to creating an <option> element without a value attribute.

const options = [
    'Option 1',
    'Option 2',
    'Option 3'
];

const picker = new OptionPicker(document.querySelector('select'), {options});

const options = [
    ['Option 1', {
        value: 1
    }],
    ['Option 2', {
        value: 2
    }],
    ['Option 3', {
        disabled: true,
        value: 3
    }]
];

const picker = new OptionPicker(document.querySelector('select'), {options});

Object is another data structure that is also easy to write. The object item keys act as option values, and the object item values act as option labels. The only problem with this data structure is that it cannot guarantee that the order will remain the same when transformed into a series of options, especially if each object key is written as a number.

const options = {
    '1': 'Option 1',
    '2': 'Option 2',
    '3': 'Option 3'
};

const picker = new OptionPicker(document.querySelector('select'), {options});

The solution would be to set the object item key as text and then set the object item value in the attributes object.

const options = {
    'option-1': ['Option 1', {
        value: 1
    }],
    'option-2': ['Option 2', {
        value: 2
    }],
    'option-3': ['Option 3', {
        disabled: true,
        value: 3
    }]
};

const picker = new OptionPicker(document.querySelector('select'), {options});

Map is another type of data structure, similar to an object, but it guarantees that the order will remain the same when transformed into a series of options.

const options = new Map;

options.set(1, 'Option 1');
options.set(2, 'Option 2');
options.set(3, 'Option 3');

const picker = new OptionPicker(document.querySelector('select'), {options});

const options = new Map;

options.set(1, ['Option 1', {
    value: 1
}]);

options.set(2, ['Option 2', {
    value: 2
}]);

options.set(3, ['Option 3', {
    disabled: true,
    value: 3
}]);

const picker = new OptionPicker(document.querySelector('select'), {options});

Function that returns one of the three data structures above can also be used. The first argument of this function holds the typed search query. Useful for creating dynamic options list capabilities using AJAX.

const options = function (query) {
    return [
        'Option 1',
        'Option 2',
        'Option 3'
    ];
};

const picker = new OptionPicker(document.querySelector('select'), {options});

const options = function (query) {
    return fetch('./options.php?query=' + encodeURIComponent(query)).then(response => response.json());
};

const picker = new OptionPicker(document.querySelector('select'), {options});

`state.size`

Set the value to an integer greater than 1 to display the options list as a scrollable area that is always visible. This layout takes up space and is provided to mimic the behavior of a <select> element when given the size attribute. It has a default value of null. If self is a <select> element, then the application will try to use the size attribute value of that element. This does not apply if self is an <input> element, because size attribute on an <input> element has different semantics. ¹ ²

`state.strict`

`state.with`

List of callable functions or objects containing an attach() method to be invoked each time the application is initialized. A very simple “plugin” system.

# Methods

Instance Methods

Instance methods are methods available through the results of an OptionPicker construct.

`picker.attach(self, state)`

Re-initializes the application and its extensions after it has been detached.

picker.attach();

`picker.blur()`

Blurs from the option picker’s input or self.

picker.blur();

`picker.detach()`

Disables the application methods (except for the attach() method) and executes the detach() method of the extensions, if they are present.

picker.detach();

`picker.enter(focus, mode = true)`

Shows the option picker’s options.

picker.enter(); // Show the option picker’s options
picker.enter(true); // Show the option picker’s options and focus to the option picker’s input or value

`picker.exit(focus, mode = true)`

Hides the option picker’s options.

picker.exit(); // Hide the option picker’s options
picker.exit(true); // Hide the option picker’s options and focus to the option picker’s input or value

`picker.fire(event, data, that)`

Fires an event.

picker.fire('change', []);

`picker.focus(mode = true)`

Focuses to the option picker’s input or self. The mode value has no effect on the “strict” option picker presentation.

picker.focus(); // Focus and select the text
picker.focus(-1); // Focus and put the caret to the start of the text
picker.focus(+1); // Focus and put the caret to the end of the text

`picker.off(event, task)`

Removes an event.

picker.off('change'); // Remove all events from the `change` event container
picker.off('change', onChange); // Remove `onChange` event from the `change` event container

`picker.on(event, task)`

Adds a new event.

picker.on('change', function () {
    console.log(this.value);
});

function onChange() {
    console.log(this.value);
}

picker.on('change', onChange);

`picker.reset(focus, mode = true)`

Resets the option picker’s value or values to its initial value or values.

picker.reset(); // Reset the option picker’s value or values
picker.reset(true); // Reset the option picker’s value or values and focus to the option picker’s input or value

Static Methods

Static methods are methods available directly on the OptionPicker object.

`OptionPicker.from(self, state)`

Creates a new OptionPicker instance.

const picker = OptionPicker.from(document.querySelector('select'));

`OptionPicker.of(self)`

Gets OptionPicker instance of an element.

document.querySelectorAll('input[list], select').forEach(self => {
    const picker = OptionPicker.of(self);
});

# Properties

Instance Properties

Instance properties are properties available through the results of an OptionPicker construct.

`picker.active`

Gets or sets the active state of the option picker. By setting the value to false or true, the disabled state of the source element will also be set automatically.

picker.active = false; // Disable option picker
picker.active = true; // Enable option picker

`picker.fix`

Gets or sets the read-only state of the option picker. By setting the value to false or true, the read-only state of the source element will also be set automatically. This only applies to the option picker that is sourced from an <input> element.

picker.fix = true; // Make the option picker “read-only”

`picker.hooks`

Returns the events data.

console.log(picker.hooks);

`picker.mask`

Returns the option picker’s mask.

picker.mask.classList.add(picker.state.n + '--dark');

`picker.max`

Proxy that passes to the picker.state.max property, with additional actions that are executed while the value is being set.

Note: This does not apply to an option picker that is sourced from an <input> element.

console.log(picker.max); // Returns the `picker.state.max` value

picker.max = 4; // Add `multiple` attribute to the `<select>` element and allow the user to select up to 4 options. If the option picker is sourced from a `<select multiple>` element and it has more than 4 options selected, the form submission will be disabled and the `max.options` hook will be fired.

`picker.min`

Proxy that passes to the picker.state.min property, with additional actions that are executed while the value is being set.

Note: If the value is set to 0 and the option picker is sourced from a <select> element, it will allow the user to remove the only selection by focusing on the option picker value and then pressing the Backspace or Delete key, or by focusing on the selected option and then clicking/tapping or pressing the Space key on it to remove the selection.

console.log(picker.min); // Returns the `picker.state.min` value

picker.min = 4; // If the option picker is sourced from a `<select multiple>` element and it has less than 4 options selected, the form submission will be disabled and the `min.options` hook will be fired.

`picker.options`

Gets the current options list data, or sets (overwrites) the current options list with new data.

console.log(picker.options);

picker.options = [
    'Option 1',
    'Option 2',
    'Option 3'
];

// Or…
picker.options.set('Option 1');
picker.options.set('Option 2');
picker.options.set('Option 3');

picker.options = [
    ['Option 1', {
        value: 1
    }],
    ['Option 2', {
        value: 2
    }],
    ['Option 3', {
        disabled: true,
        value: 3
    }]
];

// Or…
picker.options.set(1, 'Option 1');
picker.options.set(2, 'Option 2');
picker.options.set(3, ['Option 3', {
    disabled: true
}]);

picker.options = {
    '1': 'Option 1',
    '2': 'Option 2',
    '3': 'Option 3'
};

// Or…
picker.options.set(1, 'Option 1');
picker.options.set(2, 'Option 2');
picker.options.set(3, 'Option 3');

picker.options = {
    'option-1': ['Option 1', {
        value: 1
    }],
    'option-2': ['Option 2', {
        value: 2
    }],
    'option-3': ['Option 3', {
        disabled: true,
        value: 3
    }]
};

// Or…
picker.options.set('option-1', ['Option 1', {
    value: 1
}]);

picker.options.set('option-2', ['Option 2', {
    value: 2
}]);

picker.options.set('option-3', ['Option 3', {
    disabled: true,
    value: 3
}]);

const options = new Map;

options.set(1, 'Option 1');
options.set(2, 'Option 2');
options.set(3, 'Option 3');

picker.options = options;

const options = new Map;

options.set(1, ['Option 1', {
    value: 1
}]);

options.set(2, ['Option 2', {
    value: 2
}]);

options.set(3, ['Option 3', {
    disabled: true,
    value: 3
}]);

picker.options = options;

`picker.self`

Returns the <input> or <select> element.

console.log(picker.self.getAttribute('name'));

`picker.size`

Changes the layout of a drop-down select box to a scrollable area select box. This is valid only if the value is an integer greater than 1. Otherwise, it will be considered as an invalid value and will revert the layout to its default layout, which is a drop-down select box.

picker.size = 5;

`picker.state`

Returns the application states if any.

console.log(picker.state);

`picker.text`

Gets or sets the current text in the “loose” option picker’s input.

console.log(picker.text);

picker.text = 'Option 3';

`picker.value`

Proxy that passes to the picker.self.value property, with additional actions that are executed while the value is being set.

console.log(picker.value);

picker.on('change', function () {
    console.log(this.value);
});

picker.value = '3';

Static Properties

Static properties are properties available directly on the OptionPicker object.

`OptionPicker._`

Alias for OptionPicker.prototype.

OptionPicker._.clear = function () {
    if ('input' !== this.self.tagName.toLowerCase()) {
        return this;
    }
    return (this.value = ""), this;
};

const picker = new OptionPicker(document.querySelector('input'));

picker.clear(); // Clear value

`OptionPicker.state`

Returns the default values of picker.state.

const picker = new OptionPicker(document.querySelector('select'), {
    foo: ['bar', 'baz', 'qux']
});

console.log([OptionPicker.state, picker.state]);

`OptionPicker.version`

Returns the application version.

# Extensions

Anatomy of an Extension

Extension as a function:

function Extension(self, state = {}) {
    this.a = 1;
    this.b = function () {};
    return this;
}

Object.defineProperty(Extension, 'name', {
    value: 'Extension'
});

Extension as an object:

const Extension = {
    attach: function (self, state = {}) {},
    detach: function (self, state = {}) {},
    name: 'Extension'
};

Usage of an Extension

As a core extension:

OptionPicker.state.with.push(Extension);

As an optional extension:

const picker = new OptionPicker(document.querySelector('select'), {
    with: [Extension]
});

# License

Use it for free, pay if you get paid. So, you’ve just benefited financially after using this project? It’s a good idea to share a little financial support with this open source project too. Your support will motivate me to do any further development, as well as to provide voluntary support to overcome problems related to this project.

Thank you! ❤️