<!-- Docs styles -->
import { Story, Canvas, Preview, ArgsTable   } from '@storybook/addon-docs';
import image1 from '../../stories/assets/dropdown/01_Desplegable_VariacionesSimple.png';
import image2 from '../../stories/assets/dropdown/02_Desplegable_VariacionesMultiple.png';
import image3 from '../../stories/assets/dropdown/03_Desplegable_VariacionesCombo.png';
import image4 from '../../stories/assets/dropdown/04_Desplegable_VariacionesFiltro.png';
import image5 from '../../stories/assets/dropdown/05_Desplegable_VariacionesNormal.png';
import image6 from '../../stories/assets/dropdown/06_Desplegable_VariacionesEnLinea.png';
import image7 from '../../stories/assets/dropdown/07_Desplegable_VariacionesEstrecho32.png';
import image8 from '../../stories/assets/dropdown/08_Desplegable_VariacionesNormal40.png';
import image9 from '../../stories/assets/dropdown/09_Desplegable_VariacionesAlto48.png';
import image10 from '../../stories/assets/dropdown/10_Desplegable_VariacionesNormalFondo.png';
import image11 from '../../stories/assets/dropdown/11_Desplegable_VariacionesLightFondo.png';
import image12 from '../../stories/assets/dropdown/12_Desplegable_Anatomia.png';
import image13 from '../../stories/assets/dropdown/13_Desplegable_AnatomiaOpcion.png';
import image14 from '../../stories/assets/dropdown/14_Desplegable_AnatomiaFiltro.png';
import image15 from '../../stories/assets/dropdown/15_Desplegable_AnatomiaEnLinea.png';
import image16 from '../../stories/assets/dropdown/16_Desplegable_AnatomiaCheck.png';
import image17 from '../../stories/assets/dropdown/17_Desplegable_AnatomiaCheckbox.png';
import image18 from '../../stories/assets/dropdown/18_Desplegable_AnatomiaAlturas.png';
import image19 from '../../stories/assets/dropdown/19_Desplegable_Comportamiento.png';
import image20 from '../../stories/assets/dropdown/20_Desplegable_ComportamientoAbierto.png';
import image21 from '../../stories/assets/dropdown/tag.png';


<style>
  {`
    .sbdocs-table tr * {
      text-align: center;
      font-weight: bold;
    }

    img {
      display: block;
      margin: 0 auto;
    }

    table {
      margin: 0 auto !important;
    }
  `}


</style>

<img src={image21} width="150"/>

# Desplegable / Dropdown

El desplegable presenta sobre una capa desplegada por encima del componente una lista de opciones al usuario, de las cuales este puede elegir una o varias. La opción seleccionada puede ser usada como un valor dentro de un formulario, o como una acción para filtrar u ordenar contenido existente.

Los desplegables se pueden usar en muchos lugares, dentro de formularios, en páginas, como elementos en las barras laterales, en ventanas modales, etc…

Como hemos visto anteriormente, este componente tiene similitudes con otros que permiten la elección.

En los casos en que solo haya dos opciones de selección se recomienda que se use componentes más sencillos como el botón de radio. Para soluciones basadas esencialmente en formularios y con muchos componentes de selección, se recomienda usar mejor el selector, puesto que al ser un componente más sencillo y que integra el desplegable del sistema del navegador funciona mejor.

### Variaciones

Según la posibilidad de elegir una o varias opciones, existen dos variaciones de este componente.

| **Desplegable simple**   | **Desplegable múltiple** (multiselect)   |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|        <img src={image1} width="250"/>       |        <img src={image2} width="250"/>            |

El **desplegable simple** permite una única opción seleccionada en cada caso de las ofrecidas en la lista del desplegable. Con el **desplegable múltiple** (multiselect) se incluye la posibilidad de seleccionar varias opciones a la vez de esa lista. Una vez realizada la selección, el desplegable simple muestra la opción seleccionada en la caja principal del componente, mientras que el múltiple muestra un contador de elementos seleccionados en dicha caja.

Por otro lado, el desplegable puede adicionalmente permitir la escritura en la caja de texto para permitir encontrar más fácilmente la o las opciones deseadas, generando así dos variaciones adicionales.

| **Desplegable simple con filtro** (filtrable select / combo box) | **Desplegable múltiple con filtro** (filtrable multiselect)   |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|         <img src={image3} width="250"/>                |               <img src={image4} width="250"/> |

El **desplegable simple con filtro** (filtrable selecct o combo-box) permite introducir un filtro, busca la opción deseada manteniendo todas mostradas, y permite elegir una única de las opciones presentadas. Es el caso más habitual.

El **desplegable múltiple con filtro** (filtrable multiselect), por su parte, permite escribir en la caja un texto de búsqueda, actuando este como filtro para presentar las opciones que se corresponden con ese el, y entre las cuales puede el usuario hacer múltiples elecciones.

El desplegable con filtrado facilita la selección al usuario en situaciones donde hay muchas opciones posibles, o donde las opciones son complejas, con textos largos o difíciles, y el usuario ya intuye su contenido.

Existen dos variaciones para este componente según su **distribución**, el desplegable normal y el desplegable en línea.

| **Desplegable normal**  | **Desplegable en línea** (inline dropdown) |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|      <img src={image5} width="250"/>    |      <img src={image6} width="250"/>                                             |

El **desplegable normal** se usa como parte de formularios, combinado con otros componentes y tiene la altura estándar de todos los componentes de formularios. Este es el tipo de desplegable por defecto.

El **desplegable en línea** (inline dropdown) se usa cuando se asocia con otros componentes, tanto en un interior (por ejemplo un desplegable en la cabecera de una tabla o en un bloque de contenido pequeño o una tarjeta) o por agrupación de desplegables y cajas creando componentes complejos.

Asimismo, el desplegable normal tiene tres variaciones de **tamaño**, teniendo el tamaño por defecto una altura de 40px, el alto de 48px en posiciones de mayor importancia, y el tamaño reducido una altura de 32px que se usa cuando hay problemas de espacio.

| **Desplegable estrecho**   | **Desplegable normal** (por defecto)  | **Desplegable alto**    |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
|             <img src={image7} width="250"/>                        |         <img src={image8} width="250"/>    |         <img src={image9} width="250"/> |

Por último existe también una variación según el color del fondo, proporcionándose, además de una **versión normal** con el fondo gris, otro **desplegable claro** que tiene el fondo blanco.

| **Desplegable normal**(por defecto)   | **Desplegable claro**(light dropdown)    |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|  <img src={image10} width="250"/>           |        <img src={image11} width="250"/>                 |

Contenido

### Contenido

Como muchos componentes de formularios, el desplegable tiene la posibilidad de tener una **etiqueta** y un **texto de ayuda** encima y debajo de la caja. Las mismas directrices de redacción de los textos aplican en esta situación, textos breves, de una línea máximo, y con explicaciones concisas y claras.

Asimismo se utiliza un **texto predefinido** que indique que se ha de desplegar el listado y seleccionar una opción, como “seleccione una opción”.

Las **opciones** del listado deben ser textos breves de una línea máximo, y preferiblemente pocas palabras. En el caso de que sea necesario incluir un texto largo, se prefiere la utilización de la elipsis «…» para el contenido sobrante y la utilización de un descriptor emergente para presentar el texto completo.

En cuanto al número de opciones presentadas, este puede ser muy grande pero se recomienda que la capa muestre solo cinco completas, necesitando el usuario deslizarse hacia abajo dentro de la capa para ver mas. No se recomienda la utilización de iconos o imágenes dentro del listado.

El orden de los elementos dentro del listado es preferiblemente alfabético, especialmente en aquellos casos en que se apliquen filtros.

### Anatomía

La anatomía de este elemento es compleja debido a sus múltiples variaciones pero en esencia, la caja principal se plantea de manera similar a la caja de texto o numérica, con los mismos espaciados entre la etiqueta, la caja principal y el texto de ayuda, y con paddings de 16px entre los distintos elementos de la caja principal. La anchura del componente varía en función de su contexto.

La versión combo box incluye un elemento de cierre dentro de la caja que reduce su distancia al otro control a 8px, relacionando así ambos elementos.

La versión del desplegable múltiple introduce una etiqueta de filtro con el contador de elementos seleccionados. Esta etiqueta se acerca a la caja de texto con 8px y respeta la anatomía del componente original.

<img src={image12} width="300"/>

<img src={image13} width="300"/>

<img src={image14} width="300"/>

La versión en línea reduce los paddings interiores y ajusta el ancho al texto mostrado dinámicamente, para no perder la relación entre los elementos.

<img src={image15} width="300"/>

Respecto a la caja desplegable con la lista de opciones, esta se coloca pegada a la caja principal con una elevación de 2px mediante una sombra y mantiene el tamaño de cada elemento del listado con el mismo tamaño de la caja principal, separaciones de 1px y paddings internos entre los elementos de opción de 16px igual que en la caja principal.

<img src={image16} width="300"/>

En los desplegables múltiples, también en la capa de opciones se incluye un elemento de casilla para indicar la selección. Esa castilla esta asociada al texto de la opción y por ello está separada por 8px.

<img src={image17} width="300"/>


La **altura** de la caja es diferente para las variaciones de alturas, 40px la altura del selector normal y 32px la del pequeño y 48px la del grande. Cuando el desplegable está abierto, cada una de las cajas de opción deben tener la misma altura que la caja principal del componente.

<img src={image18} width="600"/>

### Comportamiento

El usuario despliega la capa de opciones mediante clic en el icono de apertura. En el caso de desplegables de selección, el hacer clic en cualquier sitio del componente abre también la capa de listado. Sin embargo, en el caso de desplegables de filtrado, el click en la caja permite al usuario introducir el texto de filtro de opciones, a la vez que se abre la capa con el listado de las opciones ya filtrado.

Para seleccionar una opción basta con clicar en la caja del elemento del listado correspondiente. El usuario puede cerrar la capa de opciones clicando de nuevo en el icono de apertura, o clicando fuera del componente.

Según el tipo de componente, hay distintas opciones de borrar la selección, aunque siempre se realiza en el icono de la «x» de contenido, unas veces en la etiqueta de múltiple selección, o junto al icono de apertura en el combo box.

Toda esta interacción se puede realizar también mediante el teclado, abriéndose la capa y cerrándose al recibir el componente el foco, usando las flechas arriba y abajo para desplazarse entre las opciones y usando espacio para la selección de la opción en los desplegables múltiples, o mediante espacio o «enter» en los simples.

El comportamiento de despliegue de la capa de listado de opciones en el desplegable depende de su posición en la página, sobre todo en la parte inferior de la pantalla, aunque por defecto se abre siempre hacia abajo. Esta capa mantiene una cierta elevación frente a la caja principal que se percibe con una sombra tenue.

No se recomienda el uso de barras de desplazamiento en la capa desplegada, por lo que sí se recomienda que esta capa tenga un tamaño que corte el último elemento mostrado por la mitad, siendo así evidente para el usuario que hay más opciones disponibles.

Los estados del desplegable afectan tanto a la caja principal del componente como a las cajas del listado de opciones cuando este está abierto, teniendo así la caja principal los estados enabled, hover, focus, disabled y skeleton, y la caja abierta los estados open, open hover, open focus y open clic.

<img src={image19} width="600"/>

<img src={image20} width="600"/>


### Código

```
<dropdown></dropdown>
```


### Tokens

**Color**

| Element            | Property         | Color token                  |
| :----------------- | :--------------- | :--------------------------- |
| Label              | text color       | `$text-02`                   |
| Field text         | text color       | `$text-01`                   |
| Field text: prompt | text color       | `$text-05`                   |
| Helper text        | text color       | `$text-05`                   |
| Field              | background-color | `$field-01`                  |
|                    | border-bottom    | `$ui-04`                     |
| Field: light       | background-color | `$field-02`                  |
| Chevron            | svg              | `$icon-01`                   |
| Menu option        | text color       | `$text-02`                   |
|                    | background-color | `$field-01`                  |
|                    | border-top       | `$ui-03`                     |
| Menu option: light | background-color | `$field-02`                  |
| Menu               | box-shadow       | `0 2px 6px 0 rgba(0,0,0,.2)` |
| Checkbox           | background-color | `$icon-01`                   |
|                    | check            | `$inverse-01`                |
|                    | border           | `$icon-01`                   |

| State          | Element            | Property         | Color token          |
| :------------- | :----------------- | :--------------- | :------------------- |
| Focus          | Field              | border           | `$focus`             |
| Hover          | Field              | background-color | `$hover-ui`          |
|                | Menu option        | background-color | `$hover-ui`          |
|                | Menu option        | text color       | `$text-01`           |
|                | Field: light       | background-color | `$hover-light-ui`    |
|                | Menu option: light | background-color | `$hover-light-ui`    |
| Invalid        | Error icon         | svg              | `$support-01`        |
|                | Field              | border           | `$support-01`        |
|                | Error message      | text-color       | `$text-error`        |
| Warning        | Warning message    | text-color       | `$text-01`           |
|                | Warning icon       | svg              | `$support-03`        |
| Active         | Menu option        | background-color | `$selected-ui`       |
|                | Menu option: light | background-color | `$selected-light-ui` |
| Selected       | Menu option        | background-color | `$selected-ui`       |
|                | Menu option        | checkmark        | `$icon-01`           |
| Multi-selected | Tag                | background-color | `$inverse-02`        |
|                | Tag                | text color       | `$inverse-02`        |
| Disabled       | Field              | background-color | `$disabled-01`       |
|                | Field              | text color       | `$disabled-02`       |
|                | Label              | text color       | `$disabled-02`       |
|                | Chevron            | svg              | `$disabled-02`       |

**Tipografía**

| Class            | Type style        |
| :--------------- | :---------------- |
| Label            | `$label-01`       |
| Field text       | `$body-short-01`  |
| Menu option text | `$body-short-01`  |
| Error message    | `$label-01`       |
| Helper text      | `$helper-text-01` |

**Estructura**

| Element     | Property                    | Spacing tokens |
| :---------- | :-------------------------- | :------------- |
| Label       | margin-bottom               | `$spacing-03`  |
| Field       | padding-left                | `$spacing-05`  |
|             | padding-right               | `$spacing-09`  |
|             | border-bottom               | `-`            |
| Chevron     | padding-right, padding-left | `$spacing-05`  |
| Helper text | margin-top                  | `$spacing-02`  |
| State icon  | padding-right, padding-left | `$spacing-05`  |