tdn-stepper

Paquete: @tiendana/ngx-core/ui

Muestra en qué punto de un flujo que el usuario recorre se encuentra: un asistente, una importación, un onboarding, un diálogo de varios pasos. Los pasos anteriores llevan una marca de verificación, el actual va con un anillo y se anuncia como paso actual, y los siguientes son huecos numerados.

Disponible desde @tiendana/ngx-core 0.8.12. La entrada size llegó en 0.8.13 y expandable en 0.8.14.

Úsalo para un progreso que conduce el usuario. Para el registro de eventos que reporta el sistema usa tdn-timeline, con el que comparte marcador y riel; para un solo estado sin secuencia use tdn-status. El stepper solo muestra el progreso: sus pasos no son botones, y moverse entre pasos es trabajo de los controles del consumidor.

Características

✅ Estado derivado de current (base 1): hecho, actual o pendiente
✅ Horizontal o vertical, y modo compact de solo marcadores
✅ Tamaño large para un stepper que encabeza su pantalla
✅ expandable: un riel compacto vertical que abre sus etiquetas al pasar el cursor
✅ Paso fallido con marcador rojo y signo de exclamación
✅ Frases accesibles traducibles, «Paso 2 de 3: Fotos»

Selector

tdn-stepper

API

Inputs

Input	Tipo	Default	Descripción
steps	readonly (string | TdnStepperStep)[]	requerido	Un elemento por paso: su etiqueta ya traducida o un TdnStepperStep. Pueden mezclarse
current	number	requerido	Paso en curso, base 1. Pasado el último, todos quedan hechos; 0 deja todos pendientes
orientation	'horizontal' | 'vertical'	'horizontal'	Columnas iguales con etiquetas bajo el marcador, o pasos apilados con la etiqueta al lado
size	'default' | 'large'	'default'	Escala de los marcadores (desde 0.8.13)
compact	boolean	false	Solo marcadores: etiquetas y detalles no se dibujan. Acepta el atributo sin valor
expandable	boolean	false	Con compact y orientation="vertical", abre las etiquetas al pasar el cursor (desde 0.8.14). Acepta el atributo sin valor
translations	Partial<TdnStepperTranslations>	undefined	Reemplaza las cadenas accesibles; solo cambian las claves dadas

Sin outputs ni contenido proyectado.

Interfaces

Interfaz	Campo	Tipo	Descripción
TdnStepperStep	label	string	Nombre visible, ya traducido; también el {label} de la frase hablada
	detail?	string	Segunda línea más pequeña bajo la etiqueta, que también se agrega a la frase hablada
	failed?	boolean	Marca un paso ya alcanzado como fallido; se ignora en un paso pendiente
TdnStepperTranslations	label	string	Nombre accesible de la lista. Default 'Progreso'
	step	string	Frase de cada paso con {step}, {total} y {label}. Default 'Paso {step} de {total}: {label}'
	done	string	Se agrega tras una coma a un paso superado. Default 'completado'
	failed	string	Se agrega a un paso failed en lugar de done. Default 'con error'

Tipos exportados

export interface TdnStepperStep {
    label: string;
    detail?: string;
    failed?: boolean;
}

export type TdnStepperOrientation = 'horizontal' | 'vertical';
export type TdnStepperSize = 'default' | 'large';

export interface TdnStepperTranslations {
    label: string;
    step: string;
    done: string;
    failed: string;
}

// TDN_STEPPER_TRANSLATIONS: constante, no token de inyección
{ label: 'Progreso', step: 'Paso {step} de {total}: {label}', done: 'completado', failed: 'con error' }

Modelo visual

Cada paso deriva su estado de current (base 1): una posición anterior está hecha (marcador natura con verificación, y el conector hacia el siguiente se vuelve natura), la igual a current es la actual (anillo natura con halo suave y etiqueta en semibold) y una posterior es pendiente (hueco, anillo punteado y su número). Un paso alcanzado (hecho o actual) con failed: true dibuja un marcador rojo con exclamación.

Orientación y compact

• horizontal: columnas iguales a todo el ancho, etiqueta y detalle centrados bajo cada marcador, conector entre marcadores.
• vertical: pasos apilados con el texto a la derecha de la columna de marcadores, como tdn-timeline.
• compact: solo marcadores; en horizontal deja de estirarse y los marcadores quedan a --stepper-connector de distancia. La etiqueta se conserva como title (tooltip), salvo con expandable, cuyo panel ya la muestra.

Tamaño

size="large" dibuja marcadores de 32px con números de 13px y verificación de 20px, para un stepper que encabeza su pantalla o diálogo (un asistente de configuración). El tamaño por defecto, de 24px, sirve dentro de un formulario, una tarjeta o una columna lateral. Las etiquetas conservan su tamaño en ambos.

Expandable

expandable en un stepper compact y vertical recupera las etiquetas al pasar el cursor: mientras el puntero está sobre el riel, este se abre como un panel sobre el contenido de la derecha, con cada etiqueta (y detalle) junto a su marcador. Los marcadores no se mueven y el host mantiene su huella compacta, así que nada alrededor se reacomoda; para lograrlo, una etiqueta se limita a dos líneas (una cuando el paso tiene detalle, que también se limita a una) y se corta con puntos suspensivos, salvo la del último paso, para la que el panel crece.

• No hace nada en cualquier otra combinación.
• Solo en dispositivos con hover real ((hover: hover) and (pointer: fine)); en táctil el riel sigue compacto.
• El panel permanece abierto mientras el puntero esté sobre él o sobre sus marcadores; Escape lo cierra sin mover el puntero hasta que salga y vuelva a entrar (WCAG 1.4.13).
• La lista no tiene elementos enfocables, por lo que un usuario de teclado sin lector de pantalla no obtiene la revelación; un lector ya lee todas las etiquetas en la frase de cada paso.

Propiedades CSS

Se declaran en el host tdn-stepper; sobrescríbelas en ese elemento. Un valor puesto en un ancestro queda tapado. Ganan un style en línea o una regla más específica que la del host, como tdn-stepper.mi-clase en la hoja del componente consumidor; una única clase global pierde. Con size="large" la regla del host es :host(.tdn-stepper--large), que también supera a una sola clase encapsulada del consumidor para --stepper-marker, --stepper-number y --stepper-glyph.

Propiedad	Default	Descripción
--stepper-marker	24px (32px con large)	Diámetro del marcador
--stepper-number	var(--font-size-xs) (var(--font-size-sm) con large)	Tamaño de fuente del número
--stepper-glyph	16px (20px con large)	Tamaño de la verificación y la exclamación
--stepper-rail-gap	4px	Aire entre un marcador y su conector, y ancho del halo del paso actual
--stepper-step-gap	20px	Espacio entre pasos en vertical
--stepper-connector	32px	Largo del conector en compact horizontal
--stepper-expanded-width	280px	Ancho máximo del panel expandable, con su padding

Clases del host: tdn-stepper--horizontal o tdn-stepper--vertical, tdn-stepper--compact, tdn-stepper--large, tdn-stepper--expandable y tdn-stepper--expanded (mientras el panel está abierto). Cada li lleva tdn-stepper__step con --done, --current, --pending o --failed. Elementos internos: __list, __marker, __text, __label, __detail, __spoken.

La verificación se dibuja con --color-forrest, que no tiene valor oscuro y se lee sobre natura en ambos esquemas; los conectores y anillos se mezclan desde el color del texto, así que funciona bajo .scheme-dark sin configuración.

Accesibilidad

• Se renderiza como <ol> nombrada por translations.label (por defecto «Progreso»); el paso actual lleva aria-current="step".
• El texto visible está oculto a la tecnología asistiva y cada paso se lee desde una frase visualmente oculta: «Paso 2 de 3: Fotos», más «, completado» en un paso superado o «, con error» en uno fallido, más «. detalle» si lo tiene.
• Los glifos de los marcadores son aria-hidden.
• Con forced-colors, marcadores y conectores usan CanvasText, y el panel expandable usa Canvas con borde CanvasText. El movimiento del panel se desactiva con prefers-reduced-motion: reduce.

Trampas que fallan sin error

• current es de base 1. Pasar un índice de base 0 marca como actual el paso equivocado y nada se queja.
• Las etiquetas y detalles se dibujan tal cual: el componente nunca traduce. Pásalos por translate antes.
• failed es una marca sobre un paso ya alcanzado; no puede señalar un paso futuro.

Ejemplos y Demos

Horizontal y tamaño large

Cargando demo...

Ver código

Vertical con detalles

Cargando demo...

Ver código

Paso fallido y cadenas en inglés

<tdn-stepper orientation="vertical" [current]="step()"
  [steps]="[
    { label: 'Upload', detail: 'products.xlsx' },
    { label: 'Validation', detail: '3 rows with errors', failed: hasErrors() },
    { label: 'Import' }
  ]"
  [translations]="{ label: 'Progress', step: 'Step {step} of {total}: {label}', done: 'done', failed: 'with errors' }" />

Compacto y expandable

Cargando demo...

Ver código