Product Data List

1.0.0

O padrão Product Data List permite visualizar e gerenciar listas resumidas de produtos. É projetado para facilitar a seleção, organização e priorização de produtos relacionados através de drag & drop e ações de edição rápidas.

import React from "react";
import { ProductDataList } from "@nimbus-ds/patterns";
import { Link, Icon, Box } from "@nimbus-ds/components";
import { BoxPackedIcon } from "@nimbus-ds/icons";

const Example: React.FC = () => (
  <ProductDataList
    title="Productos relacionados"
    backgroundColor="neutral-background"
  >
    <ProductDataList.Section
      title="Alternativos"
      description="Pueden ser opciones similares a este producto."
      link={
        <Link appearance="primary" textDecoration="none">
          <Icon source={<BoxPackedIcon />} color="primary-interactive" />
          Agregar productos
        </Link>
      }
    />
    <ProductDataList.ItemDivider />
    <ProductDataList.Section
      title="Complementarios"
      description="Productos que se complementan con este artículo."
      link={
        <Link appearance="primary" textDecoration="none">
          <Icon source={<BoxPackedIcon />} color="primary-interactive" />
          Agregar productos
        </Link>
      }
    />
  </ProductDataList>
);

export default Example;

Ver no Figma

Reportar um bug

Definição

O padrão Product Data List permite visualizar e gerenciar listas resumidas de produtos. É projetado para facilitar a seleção, organização e priorização de produtos relacionados, sejam eles alternativos ou complementares, através da funcionalidade de arrastar e soltar e ações de edição rápidas.

Este padrão é ideal para fluxos de trabalho de edição ou configuração de produtos onde é necessário manter a relação entre os diferentes artigos do catálogo.

Anatomia do componente

O product data list pode conter:

Title section
Title and description ou Radio buttons
Link
Thumbnail
Icon
Icon button
Text label
Tag

Dependências

Este padrão utiliza:

#card
#thumbnail
#icon
#tag
#link
#icon-button

Guidelines

Quando usar

Criar e gerenciar uma lista de produtos com informações resumidas.
Associar produtos alternativos ou complementares dentro do catálogo.
Apresentar uma lista flexível de produtos reorganizáveis por prioridade ou destaque.

Quando não usar

Não utilizar para listar produtos que requerem múltiplas ações ou que precisam visualizar atributos ou diversos conceitos e/ou informações do produto.
Evitar usar quando for necessário listar menos de três produtos ou, pelo contrário, para listas que excedam 15 artigos/produtos.

Drag and drop

O Product Data List proporciona a funcionalidade de reordenamento da lista de produtos através de drag and drop, permitindo configurar a ordem dos elementos segundo o critério do usuário.

Critérios de usabilidade e produtividade

Reordenamento com drag & drop visível: facilita a reorganização com feedback visual imediato e sem a necessidade de confirmar cada mudança.
Pré-seleção inteligente: sugerir produtos baseados em relações anteriores ou contexto do fluxo (por exemplo, produtos da mesma categoria)
Evita componentes de confirmação desnecessários: as ações como adicionar ou eliminar produtos devem se refletir imediatamente na UI sem a utilização de componentes de confirmação (por exemplo, o toast)
Uso de componentes de feedback. Utilizar componentes de feedback apenas quando se apresentar um problema na experiência, atraso no carregamento de produtos ou erro ao eliminar ou adicionar produtos.

Boas práticas de acessibilidade

Navegação completa com teclado: garantir que todos os elementos (cards e botões) possam ser navegados e ativados com teclado.
Mensagens e estados acessíveis: usar ARIA para descrever ações como "produto eliminado" ou "lista vazia".
Manejo correto do foco: após adicionar ou eliminar um produto, retornar o foco ao último elemento utilizado pelo usuário.

Variantes

O Product Data List pode ter 3 variantes de completude de conteúdo:

1- Content empty

Sem produtos adicionados. A lista ainda não se mostra, enfatiza-se o call to action principal.

2- Content partial

Com menos de 5 produtos adicionados. Os produtos vão sendo listados segundo a ordem em que foram carregados inicialmente. Utiliza-se a tag como elemento para indicar o estado de completude da lista. A funcionalidade drag and drop permite reordenar a listagem de produtos segundo o critério do usuário.

3- Content full

Com mais de 5 produtos adicionados (máx de 8 produtos admitidos). A lista mostra o scroll vertical interno a partir do 5º produto. Utiliza-se a tag como elemento para indicar o estado de completude da lista. Ao superar os 5 produtos, a tag muda do estado neutral para estado de warning para destacar o limite de completude.

Recomendações de uso

✅ Do

Mostrar informações claras e resumidas do produto: imagem, nome e ações principais.
Limitar a quantidade de itens para manter uma experiência clara e gerenciável (ex. máximo 8 produtos).
Usar ícones compreensíveis e acessíveis para as ações (por exemplo, o ícone de lixeira para eliminar).
Oferecer contexto com textos guia sobre o objetivo da lista. Objetivo e ações recomendadas.
Permitir o reordenamento unicamente quando fizer sentido para a experiência (como quando a ordem implica prioridade ou hierarquia).

❌ Don't

Incluir muitos produtos sem uma lógica clara.
Não permitir edição ou reordenamento em contextos onde se espera essa funcionalidade.
Não oferecer contexto visual ou textual sobre o objetivo da lista

Componentes relacionados

Card - Para conter as informações de cada produto.
Thumbnail - Para mostrar a imagem do produto.
Icon - Para indicadores visuais e ações.
Tag - Para mostrar o estado de completude.
Link - Para navegação aos detalhes do produto.
Icon Button - Para ações de eliminação e edição.

Props

Additional props are passed to the <ProductDataList> component. See div docs for a list of props accepted by the <ProductDataList> component.

ProductDataList

Name	Type	Default	Description
children			The content to be rendered inside the list
title			Optional title for the list section

ProductDataList.Item

Name	Type	Description
id*	string	The id of the product
title*	string	The title of the product
imageUrl	string	The image URL of the product
imageAlt	string	Alternative text for the product image
isDraggable	boolean	Whether the item is draggable
onRemove	object	Callback fired when remove button is clicked
withDivider	boolean	Whether the item has a divider
children		Additional content to be rendered

ProductDataList.Products

Name	Type	Description
items*	array	The array of items to be rendered and sorted in the list.
onReorder*	object	Callback fired when the order of items changes.
sortable	boolean	If true, enables drag-and-drop sorting for the list items.
renderItem*	object	Function to render each item in the list.
sortableProps	object	Additional properties to pass to the sortable container.

ProductDataList.ItemDivider

Name	Type	Description
id	string
width	string	The width property specifies the width of a box's content area. This is a responsive property and you can have the options below available for you to use. '{ "focus": "value", "focusWithin": "value", "active": "value", "hover": "value", "disabled": "value", "xs": "value", "md": "value", "lg": "value", "xl": "value" }'
borderBottomWidth	'1' '2' '3' '4' '5' 'none'	The borderBottomWidth property defines the width of the border at the bottom of a box. This is a responsive property and you can have the options below available for you to use. '{ "focus": "value", "focusWithin": "value", "active": "value", "hover": "value", "disabled": "value", "xs": "value", "md": "value", "lg": "value", "xl": "value" }'
borderColor	'danger-interactive' 'danger-surface' 'danger-surfaceHighlight' 'neutral-interactive' 'neutral-surface' 'neutral-surfaceDisabled' 'neutral-surfaceHighlight' 'primary-interactive' 'primary-surface' 'primary-surfaceHighlight' 'success-interactive' 'success-surface' 'success-surfaceHighlight' 'transparent' 'warning-interactive' 'warning-surface' 'warning-surfaceHighlight'	The borderColor property sets the color of the box's four borders. This is a responsive property and you can have the options below available for you to use. '{ "focus": "value", "focusWithin": "value", "active": "value", "hover": "value", "disabled": "value", "xs": "value", "md": "value", "lg": "value", "xl": "value" }'
borderStyle	'dashed' 'dotted' 'hidden' 'none' 'solid'	borderStyle property sets the line style for all four sides of an box's border. This is a responsive property and you can have the options below available for you to use. '{ "focus": "value", "focusWithin": "value", "active": "value", "hover": "value", "disabled": "value", "xs": "value", "md": "value", "lg": "value", "xl": "value" }'
borderTopWidth	'1' '2' '3' '4' '5' 'none'	The borderTopWidth property defines the width of the border at the top of a box. This is a responsive property and you can have the options below available for you to use. '{ "focus": "value", "focusWithin": "value", "active": "value", "hover": "value", "disabled": "value", "xs": "value", "md": "value", "lg": "value", "xl": "value" }'

ProductDataList.Section

Name	Type	Default	Description
title
description
content
link
children