=============
Configuration
=============

Options can be passed in an object as the second argument to
``dropulous(target, options)``, or set via ``data-<option-name>``  attributes on the
``input`` or ``select`` element.

``source``
   URL of an API endpoint to load options from.

   Called with ``?q=<query>`` on each keystroke.

   Must return ``{"options": [{value, label}, ...]}`` - see :ref:`From an
   API <from-api>` for the full response format.

   * Data attribute: ``data-source``

``canAdd``
   Allow the user to create new options not in the list.

   * Data attribute: ``data-can-add``.
   * Default: ``false``.

``minQueryLength``
   Minimum number of characters the user must type before an API request is sent.
   Has no effect when options are loaded locally.

   * Data attribute: ``data-min-query-length``.
   * Default: ``0``.

``debounceTime``
   Milliseconds to wait after the last keystroke before sending an API request.

   * Data attribute: ``data-debounce-time``.
   * Default: ``300``.

``formatOption``
   Function called to render each option in the dropdown.

   Receives a ``Dropulous.Option`` and must return an HTML string.
   See :ref:`formatters`.

``formatSelected``
   Function called to render each selected item.

   Receives a ``Dropulous.Option`` and must return an HTML string.
   See :ref:`formatters`.

``templates``
   Object of HTML template strings to override the default markup.

   See :ref:`templates`.


Initial values
==============

For ``<select>`` elements, pre-selected options are read from the ``selected`` attribute
on ``<option>`` elements as normal.

For ``<input>`` elements, the initial value is read from the ``value`` attribute, or the
``data-value`` attribute (if set, takes priority over ``value``). For multiple-selection
inputs, supply a comma-separated string:

.. code-block:: html

   <input type="text" data-value="two,three" data-multiple ...>

When using an API source on a ``<select>``, ``data-value`` can select values
before the API loads:

.. code-block:: html

   <select data-source="/api/options/" data-value="two,three" multiple>
   </select>

.. _formatters:

Custom formatters
=================

``formatOption`` and ``formatSelected`` are methods that receive a
``Dropulous.Option`` object and return an HTML string.

``formatOption`` controls how options appear in the open dropdown;
``formatSelected`` controls how selected values appear in the control.

A ``Dropulous.Option`` has:

- ``value`` - the option's value string
- ``label`` - the plain-text label, used for search matching and aria labels
- ``html`` - optional pre-rendered markup to display instead of the escaped ``label``
- ``data`` - an object of extra data (from ``data-*`` attributes on ``<option>``
  elements, or the ``data`` field in a ``data-options`` or API response)

Since a formatter's return value is inserted directly as HTML, you can escape any values
which are potentially unsafe with the helper function ``Dropulous.escapeHtml(text)``:

.. code-block:: js

   dropulous(document.querySelector('#my-field'), {
     formatOption: (option) => `<img src="${Dropulous.escapeHtml(option.data.icon)}"> ${Dropulous.escapeHtml(option.label)}`,
     formatSelected: (option) => `<img src="${Dropulous.escapeHtml(option.data.icon)}"> ${Dropulous.escapeHtml(option.label)}`,
   });

When an API response includes ``html``, that HTML is used directly and formatters are
not called.


.. _templates:

HTML templates
==============

Every piece of Dropulous markup is defined as an HTML template string and can be overridden via the ``templates`` option. Templates use ``{key}`` placeholders.

``field``
   The outer wrapper structure.

   Contains the field area, display element,
   search input, clear button, dropdown panel, and options listbox.

   No placeholders.

``tag``
   A selected value in multiple mode.

   Placeholders:

   * ``{value}`` - the option's value
   * ``{label}`` - the rendered HTML label
   * ``{labelText}`` - the plain-text equivalent used in the remove button's
     ``aria-label``.

``option``
   A row in the open dropdown list.

   Placeholders:

   * ``{value}`` - the option's value
   * ``{label}`` - the rendered HTML label
   * ``{highlighted}`` - expands to the attribute ``data-highlighted`` (or empty
     string) when the row has keyboard focus
   * ``{active}`` - expands to ``data-active`` (or empty string) when the value is
     already selected

   ``{highlighted}`` and ``{active}`` are intended as HTML attribute insertions,
   not text content.

``loading``
   Shown in the dropdown while an API request is in progress.

   No placeholders.

``noResults``
   Shown when no options match the current query.

   No placeholders.

``addNew``
   The "Add …" entry shown at the bottom of the list when ``canAdd`` is set and the
   current query does not exactly match any existing option.

   Placeholders:

   * ``{query}`` - the current search query.


Example - replacing the loading indicator:

.. code-block:: js

   dropulous(document.querySelector('#my-field'), {
     source: '/api/options/',
     templates: {
       loading: '<div class="my-spinner">Loading...</div>',
     },
   });

Example - custom option markup:

.. code-block:: js

   dropulous(document.querySelector('#my-field'), {
     templates: {
       option: '<div role="option" data-value="{value}"{highlighted}{active} class="my-option">{label}</div>',
     },
   });


Customising the style
=====================

The default stylesheet uses CSS custom properties on ``:root`` for easy customisation.
Override them on ``.dropulous`` (or ``:root``) to restyle without touching the source:

.. code-block:: css

   .dropulous {
     --dropulous-border:      #d1d5db;   /* border colour */
     --dropulous-radius:      0.4rem;      /* border radius */
     --dropulous-focus:       #3b82f6;   /* focus and active border colour */
     --dropulous-z:           1000;        /* z-index for the dropdown panel */
     --dropulous-max-h:       16rem;       /* max-height of the options list */
     --dropulous-font:        sans-serif;
     --dropulous-size:        0.9rem;
     --dropulous-lh:          1.2rem;
     --dropulous-bg:          #ffffff;   /* control background */
     --dropulous-text:        #111827;   /* primary text */
     --dropulous-placeholder: #9ca3af;   /* placeholder and status-message text */
     --dropulous-hover:       #f3f4f6;   /* option row hover background */
     --dropulous-active:      #dbeafe;   /* already-selected option background */
     --dropulous-highlight:   #eff6ff;   /* keyboard-highlighted option background */

     /* Tags (multiple mode) */
     --dropulous-tag-bg:      #e5e7eb;   /* tag chip background */
     --dropulous-tag-text:    #1f2937;   /* tag chip text */
   }