[ATOMS] Chip

[egdev6]

🧩 Tarea: Chip

Referencia:

https://www.heroui.com/docs/components/chip

✅ Fases del desarrollo

• 1. Research de funcionalidad
  Investigar soluciones similares, patrones existentes y necesidades reales. Añadir capturas, enlaces o benchmarks si aplican.

• 2. Definición de funcionalidades
  Especificar qué debe hacer el componente: props, estados, interacción, accesibilidad, variantes, etc.

• 3. Implementación del componente
  Desarrollo del componente en base a la definición anterior. Incluir historias de Storybook si procede.

• 4. Documentación del componente

  • Storybook documentado con controles y ejemplos de uso
  • MDX o comentarios en JSDoc si aplica
  • Sección de casos de uso o guidelines

• 5. Code review y modificaciones

  • Revisión funcional
  • Revisión visual (alineamiento con el design system)
  • Corrección de errores o ajustes sugeridos

• 6. Merge en main
  Una vez aprobado, mergear la rama a main siguiendo el flujo de PR establecido. (Esta parte me encargo yo)

---

📎 Notas adicionales

Anotar cualquier comentario, decisión tomada o consideraciones especiales. (Nómbra a egdev6 para cualquier consulta)

---

🔗 Recursos relacionados

_Nombrar cualquier recurso externo

[andresito87]

1.- Research de funcionalidad

Nuestro objetivo es crear un componente Chip que sea altamente personalizable y fácil de usar. En otras bibliotecas de componentes lo nombran como Tag.

1.1.- Componentes similares en otras bibliotecas

Nuestro trabajo se basa en el componente de HeroUI Chip.
https://www.heroui.com/docs/components/chip

He investigado otros componentes similares:

• Material-UI:
  https://mui.com/components/chips/
• PrimeVue:
  https://www.primevue.org/chip/
• Mantine:
  https://mantine.dev/core/chip/
• Otro componente que nos permite ver que es lo que buscamos es el componente Tag de React FluentUI:
  https://react.fluentui.dev/?path=/docs/components-tag-interactiontag--docs
  De este me gusta especialmente la variedad de iconografía que permite agregar al componente.
• En Carbon Design system podemos encontrar otro componente similar (también lo llaman Tag) y de este me gustaría destacar la variedad de funcionalidades que tiene y como la tienen documentada:
  https://carbondesignsystem.com/components/tag/usage/

1.2.- Patrones

- Chip de estado / informativo (read-only): Etiqueta compacta para mostrar estado o metadatos. No es interactivo (similar a badge).
- Chip descartable (dismissible): Token con botón de cierre para quitar elementos (p. ej., filtros activos, etiquetas aplicadas).
- Chip seleccionable (toggle): Actúa como un checkbox/radio en formato píldora; sirve para seleccionar uno o varios valores.
- Chip de filtro: Variación del seleccionable, enfocado a activar/desactivar filtros de contenido rápidamente.
- Chip de entrada (tokens): Se generan al introducir datos (tags, emails, keywords) normalmente vía autocomplete/multi-select.
- Conjuntos/agrupaciones (Chip group/Chip set): Contenedores que agrupan chips relacionados para facilitar lectura, navegación y manejo por teclado.

1.3.- Necesidades reales

• Permitir a los usuarios seleccionar y filtrar elementos de manera eficiente.
• Proporcionar una forma clara de etiquetar y organizar contenido.
• Facilitar la búsqueda y eliminación de elementos no deseados.
• Mostrar información adicional de manera concisa y accesible.
• Agrupar elementos relacionados para una mejor comprensión y navegación.

1.4.- Capturas, enlaces o benchmarks

• HeroUI Chip Component:

• Material-UI Chip Component:

• PrimeVue Chip Component:

• React FluentUI Tag Component:

• Ant Design Tag Component

• Chakra UI:

1.5.- Conclusiones

Se trata de un componente versátil que puede adaptarse a diversas necesidades de los usuarios, facilitando la interacción y organización de la información.

Nota: me llamó la atención un componente select que maneja la selección de multiples tags o chips para filtrar
https://react.fluentui.dev/?path=/docs/components-tagpicker--docs

@egdev6

[egdev6]

@andresito87 buen análisis, te comento cosas

• puedes utilizar el concepto de slots para hacer extensible la funcionalidad de elementos que se pueden añadir dentro del chip (tienes referencia de esto en el componente snippet por ej o puedes preguntar a Lautaro, que lo ha estado viendo hace poco)

• tenemos un componente icon que puedes reutilizar (Lucide)

• tenemos un componente IconButton que también puedes reutilizar

• El que comentas de select sería quizás una molécula u organismo (podríamos verlo más adelante)

Puedes iniciar la fase de definición!! buen trabajo!!

[andresito87]

2. Definición de funcionalidades — Chip (con justificación)

Objetivo: hacer el Chip extensible sin forks, permitiendo inyectar o reemplazar partes internas (iconos, avatar, acciones, botón de cierre, badges, etc.) mediante slots.

2.1 Alcance

• Chip (base): etiqueta compacta (estado/metadatos), opcional dismissible.

• ChipToggle (opcional): chip seleccionable (toggle/filtro).

• ChipGroup (opcional): agrupación (single/multiple) + foco navegable.

• ChipsInput (opcional): tokens (tags/emails) con autocompletado.

  Nota: cualquier Select o “Chip Selector avanzado” será molécula/organismo y se verá más adelante (fuera de este scope).

---

2.2 API (Chip base) — Props generales

type ChipSize    = "sm" | "md" | "lg";
type ChipVariant = "solid" | "soft" | "outline" | "ghost" | "faded" | "dot";
type ChipColor   = "neutral" | "brand" | "success" | "warning" | "danger" | "info" | "teal" | "indigo" | "purple" | "pink";
type Radius      = "none" | "sm" | "md" | "lg" | "full";

type ChipProps = {
  id?: string;

  /** Semántica/host: <span> por defecto; <button>/<a> si es interactivo */
  as?: React.ElementType;
  asChild?: boolean; // opcional: adopta el elemento hijo como root (sin wrapper)

  /** Contenido principal */
  label?: React.ReactNode;   // alias de children
  children?: React.ReactNode;

  /** Flags de comportamiento */
  closable?: boolean;        // fuerza render del closeButton
  onClose?: (e: React.MouseEvent | React.KeyboardEvent) => void;
  onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;
  disabled?: boolean;
  tabIndex?: number;

  /** Estilo y layout */
  size?: ChipSize;           // md (default)
  variant?: ChipVariant;     // soft (default)
  color?: ChipColor;         // neutral (default)
  radius?: Radius;           // md (default)
  density?: "comfortable" | "compact";  // definición rápida de paddings

  truncate?: boolean;        // añade truncado + title si procede
  maxWidth?: number | string;
  tooltip?: string;          // texto accesible al hover/focus

  /** Theming y overrides */
  className?: string;
  style?: React.CSSProperties;
  classNames?: Partial<Record<ChipSlotName, string>>;

  /** API de Slots (ver sección 2.3) */
  slots?: Partial<Record<ChipSlotName, React.ElementType>>;
  slotProps?: Partial<Record<ChipSlotName, any>>;

  /** A11y */
  "aria-label"?: string;
  "aria-describedby"?: string;
};

---

2.3 Slots (extensibilidad oficial)

2.3.1 Definición

type ChipSlotName =
  | "root"          // contenedor principal
  | "start"         // antes del texto: avatar/icon/dot
  | "content"       // wrapper del label
  | "label"         // texto
  | "end"           // después del texto: icon/acciones
  | "closeButton"   // botón de cierre (si onClose/closable)
  | "dot"           // indicador de estado (variant="dot")
  | "badge"         // mini-badge superpuesto (p.ej. NEW)
  | "counter"       // contador opcional (p.ej. 3)
  | "action";       // acción extra (IconButton/Menu/etc.)

• slots permite reemplazar el componente/elemento de cada parte.
• slotProps pasa props específicos a cada slot.
• classNames aplica clases por slot para estilado granular.

Reuso del Design System:

• Para iconografía usa Icon (Lucide) en start, end, dot, badge.
• Para acciones usa IconButton (p. ej., como closeButton o action).

2.3.2 Comportamiento por defecto

• start: no renderiza si no hay contenido (icon/avatar/dot).
• end: no renderiza si no hay contenido y no hay closeButton.
• closeButton: solo aparece si hay onClose o closable.
• badge, counter, action: opcionales, no renderizan si no se usan.

2.3.3 Ejemplos de uso (slots)

A) Reemplazar closeButton con IconButton + Icon (Lucide):

<Chip
  closable
  onClose={handleClose}
  slots={{
    closeButton: (props: any) => (
      <IconButton
        aria-label={props["aria-label"]}
        size="xs"
        variant="ghost"
        onClick={props.onClick}
        onKeyDown={props.onKeyDown}
      >
        <Icon name="x" />
      </IconButton>
    ),
  }}
  slotProps={{
    closeButton: { "aria-label": "Quitar UI/UX" },
  }}
>
  UI/UX
</Chip>

B) Icono al inicio y acción al final:

<Chip
  slots={{
    start: (p: any) => <Icon name="tag" aria-hidden />,
    action: (p: any) => (
      <IconButton aria-label="Más opciones" size="xs" variant="ghost" onClick={openMenu}>
        <Icon name="more-horizontal" />
      </IconButton>
    ),
  }}
>
  Marketing
</Chip>

C) dot + badge (estado + indicador):

<Chip
  variant="dot"
  slots={{
    dot: () => <span className="dot" />, // o <Icon name="circle" />
    badge: () => <span className="badge">NEW</span>,
  }}
  classNames={{ badge: "bg-pink-500 text-white" }}
>
  Pending review
</Chip>

---

2.4 Interacción y teclado

• Acción principal: usar <button> si ejecuta acción local; <a> con href si navega. Enter/Space activan.

• Cerrar: el closeButton (o slot equivalente) debe ser focusable y con aria-label (“Quitar {label}”). Enter/Space lo activan.

  • Si el chip es clickable y se pulsa cerrar, no propagar el click al root.
  • Opcional: Backspace/Delete al enfocar el chip invoca onClose (flag).

• Foco: :focus-visible claro tanto en root como en closeButton/action. Orden de tab: root → closeButton → action (si existen).

---

2.5 Accesibilidad

• Semántica:

  • No interactivo: <span>/<div>.
  • Acción: <button> o <a href>.
  • Dismissible: closeButton con aria-label significativo.

• Color ≠ único portador de significado: añadir texto o iconografía.

• Truncado accesible: title o tooltip.

• RTL: invertir start/end y paddings lógicos; espejar iconos direccionales.

---

2.6 Variantes, tamaños y diseño (resumen)

• Variants: solid, soft (default), outline, ghost, faded, dot.
• Colors : brand, neutral, success, warning, danger, info.
• Sizes (altura): sm ≈ 24px, md ≈ 28px (default), lg ≈ 32px.
• Radius: none | sm | md (default) | lg | full.
• Density: comfortable | compact.

Nota: el mapeo exacto a tokens de color/tema (light/dark) se define en el theme (referenciado en la paleta).

---

2.7 ChipToggle (seleccionable) — compatible con slots

• API: selected, defaultSelected, onSelectedChange, value, roleStrategy: "button-pressed" | "checkbox" | "radio".
• Render por defecto: <button aria-pressed={selected}>.
• Alternativa accesible: input oculto (checkbox/radio) + label (ideal en ChipGroup).
• Slots disponibles: mismos que Chip (puedes personalizar start/end/action/closeButton).

---

2.8 ChipGroup

• API: selectionMode: "single" | "multiple", value/defaultValue, onChange, rovingFocus, aria-label, wrap, gap.
• A11y: role="radiogroup" (single con radios) / role="group" (multiple con checkboxes); roving tabindex opcional.

---

2.9 ChipsInput (tokens)

• API: value/defaultValue, onChange, validate, suggestions/onSearch, renderChip, onChipClose, separators, max.
• Interacción: Enter/separadores añaden token; Backspace elimina último si input vacío; aria-live="polite" para alta/baja de tokens.
• Usa Chip con slots para renderizar cada token (ej.: closeButton con IconButton).

---

2.10 Edge cases

• Texto largo → truncate + title/tooltip.
• Solo icono → aria-label en root.
• disabled + closable → ocultar o desactivar closeButton.
• Listas largas → virtualización en el contenedor.
• Click root + close/action → detener propagación desde botones internos.

---

2.11 Ejemplos rápidos (con slots)

// Chip informativo con icono de inicio (Icon)
<Chip slots={{ start: () => <Icon name="info" aria-hidden /> }} color="info" variant="soft">
  Pending
</Chip>

// Chip dismissible con IconButton como closeButton
<Chip
  color="brand"
  closable
  onClose={() => removeTag("UI/UX")}
  slots={{
    closeButton: (p: any) => (
      <IconButton aria-label={p["aria-label"]} size="xs" variant="ghost" onClick={p.onClick}>
        <Icon name="x" />
      </IconButton>
    ),
  }}
  slotProps={{ closeButton: { "aria-label": "Quitar UI/UX" } }}
>
  UI/UX
</Chip>

// Chip con acción extra al final
<Chip
  slots={{
    action: () => (
      <IconButton aria-label="Más opciones" size="xs" variant="ghost" onClick={openMenu}>
        <Icon name="more-horizontal" />
      </IconButton>
    ),
  }}
>
  Marketing
</Chip>

---

2.12 Referencias (las que hemos tomado como base)

• Ant Design — Tag: https://ant.design/components/tag
• MUI — Chip: https://mui.com/material-ui/react-chip/
• Evergreen — TagInput: https://evergreen.segment.com/components/tag-input
• ZenUI — Chip: https://zenui.net/components/chip
• HeroUI — Chip: https://www.heroui.com/docs/components/chip

Notas:

• En la primera parte de Alcance me pareció interesante agregar esas features porque este componente la mayoría de veces se utiliza en grupo, entonces necesitamos una forma de agrupar, quitar, poner,...
• En la parte de props he combinado la información que he obtenido a través de otras bibliotecas con la que me ha dado la IA, pero me resultó interesante por ejemplo agregar density, si con una palabreja me ahorro tener que indicarle el tamaño concreto, calculando padings, el tamaño del hijo, creo que puedo simplificarlo con esta prop, permitiendo por supuesto la funcionalidad de size personalizado.
• Soy consciente de que propongo props o funcionalidad en exceso, así que espero feedback que me indique, "Esta sí, esta otra no", por proponer que no sea.

@egdev6

[egdev6]

Buena definición @andresito87!! a priori lo veo genial...dale candela al código!!!

[egdev6]

Rama con el componente -> feature/chip
PR -> #98