# Catálogo de componentes

Todos los nombres comienzan con `Ds`. A menos que se indique lo contrario, los atributos HTML adicionales llegan al control raíz correspondiente.

## Layout

| Componente        | Props principales                               | Slots                                  |
| ----------------- | ----------------------------------------------- | -------------------------------------- |
| `DsAppShell`      | `maxWidth`                                      | default                                |
| `DsPageHeader`    | `title`, `description`, `eyebrow`, `standalone` | default implícito en textos, `actions` |
| `DsPanel`         | `as`, `padding: sm\|md\|lg`, `tone`, `flat`     | default                                |
| `DsSectionHeader` | `title`, `description`, `eyebrow`               | `actions`                              |
| `DsStack`         | `as`, `gap`, `align`                            | default                                |
| `DsInline`        | `as`, `gap`, `align`, `justify`, `wrap`         | default                                |
| `DsDivider`       | —                                               | —                                      |

## Acciones

| Componente      | Props y eventos                                                                  | Slots         |
| --------------- | -------------------------------------------------------------------------------- | ------------- |
| `DsButton`      | `variant`, `size`, `type`, `disabled`, `loading`, `block`, evento nativo `click` | default       |
| `DsIconButton`  | `label` obligatorio, más variantes y estados de `DsButton`                       | icono default |
| `DsButtonGroup` | `label`                                                                          | default       |
| `DsFormActions` | —                                                                                | default       |

`loading` conserva el texto como nombre accesible, añade `aria-busy` y deshabilita el botón.

## Formularios

| Componente          | Modelo    | Props principales                                                                                                          |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| `DsFormField`       | —         | `id`, `label`, `description`, `error`, `required`; slot scoped con `controlId`, `describedBy`, `invalid`                   |
| `DsTextInput`       | `string`  | `id`, `name`, `label`, `description`, `error`, `type`, `autocomplete`, `disabled`, `required`; slots `leading`, `trailing` |
| `DsTextarea`        | `string`  | contrato común más `rows`                                                                                                  |
| `DsPasswordInput`   | `string`  | contrato común y botón mostrar/ocultar                                                                                     |
| `DsSearchInput`     | `string`  | contrato de texto con icono decorativo de búsqueda                                                                         |
| `DsSelect`          | `string`  | contrato común y `options: DsSelectOption[]`                                                                               |
| `DsCheckbox`        | `boolean` | `label`, `description`, `error`, estados HTML                                                                              |
| `DsRadioGroup`      | `string`  | `legend`, `name`, `options: DsRadioOption[]`, descripción y error                                                          |
| `DsSwitch`          | `boolean` | `label`, `description`, `disabled`, `name`                                                                                 |
| `DsSettingsSection` | —         | `title`, `description`; slots default y `actions`                                                                          |

Ejemplo:

```vue
<DsTextInput
  v-model="email"
  name="email"
  type="email"
  label="Correo electrónico"
  description="Usaremos tu correo de trabajo."
  :error="emailError"
  required
/>
```

## Retroalimentación

| Componente        | Props principales                    | Comportamiento                   |
| ----------------- | ------------------------------------ | -------------------------------- |
| `DsSpinner`       | `size`, `label`                      | `role=status`, nombre oculto     |
| `DsSkeleton`      | `width`, `height`, `rounded`         | decorativo y sin gradiente       |
| `DsProgressBar`   | `value`, `max`, `label`, `showValue` | semántica `progressbar`          |
| `DsAlert`         | `variant`, `title`, `live`           | `live` activa `status` o `alert` |
| `DsInlineMessage` | `variant`, `live`                    | ayuda o error breve              |
| `DsEmptyState`    | `title`, `description`               | slots `icon`, `actions`          |
| `DsLoadingState`  | `title`, `description`               | región de estado anunciable      |
| `DsErrorState`    | `title`, `description`               | alerta y slot `actions`          |

## Navegación y overlays

`DsTabs` recibe `items: DsTabItem[]`, `label` y `v-model<string>`. Cada `id` define un slot del mismo nombre. Admite flechas, Home y End.

```vue
<DsTabs v-model="tab" :items="tabs" label="Preferencias">
  <template #profile>…</template>
  <template #security>…</template>
</DsTabs>
```

`DsDialog` recibe `v-model<boolean>`, `title`, `description`, `closeLabel` y `closeOnBackdrop`. Emite `close` y `cancel`; ofrece slots default y `footer`.

`DsConfirmDialog` añade `confirmLabel`, `cancelLabel`, `danger` y `loading`; emite `confirm` y `cancel`.

## Datos y reglas

`DsSortableList` ordena un `v-model<DsSortableItem[]>` mediante drag-and-drop. Cada elemento requiere `id` y `label`; puede incluir `description` y `disabled`. El evento `reorder` entrega el elemento y sus posiciones `from` y `to`. Los botones subir/bajar ofrecen la misma operación sin depender del puntero.

```vue
<DsSortableList v-model="steps" label="Etapas del proyecto" />
```

`DsLogicTree` edita un `v-model<DsLogicGroup>` serializable. Un grupo combina nodos con `operator: "and" | "or"`; cada condición guarda `field`, `comparison` y `value`. `fields` y `comparisons` reciben opciones configurables, y `readonly` permite mostrar el árbol sin editarlo.

```vue
<DsLogicTree
  v-model="rules"
  :fields="[
    { label: 'Estado', value: 'status' },
    { label: 'Plan', value: 'plan' },
  ]"
  label="Reglas de audiencia"
/>
```

Los textos del constructor pueden adaptarse mediante la prop `labels`. El componente emite `change` con el árbol completo después de cada edición.

Las decisiones internas, limitaciones conocidas y propuestas de evolución están registradas en [Herramientas interactivas](interactive-tools.md).