List

Lista estruturada para exibir coleções de itens com slots de leading, badge, actions e trailing. Tags `mk-list`, `mk-list-item`, `mk-list-item-text` e `mk-list-subheader`.

mk-list renderiza um <ul> semântico e cada mk-list-item renderiza um <li>. Use mk-list-item-text para o texto primário e secundário de cada item. Dividers são exibidos automaticamente entre os itens.

Padrão

Aninhe os itens dentro da lista. Cada item recebe mk-list-item-text no slot default.

import { MkList, MkListItem, MkListItemText } from '@db1/makuco-ui-react';

<MkList>
  <MkListItem>
    <MkListItemText primary="Primeiro item" secondary="Supporting text" />
  </MkListItem>
  <MkListItem>
    <MkListItemText primary="Segundo item" secondary="Supporting text" />
  </MkListItem>
</MkList>

<mk-list>
  <mk-list-item>
    <mk-list-item-text primary="Primeiro item" secondary="Supporting text"></mk-list-item-text>
  </mk-list-item>
  <mk-list-item>
    <mk-list-item-text primary="Segundo item" secondary="Supporting text"></mk-list-item-text>
  </mk-list-item>
</mk-list>

Cabeçalho de seção

A prop subheader em mk-list exibe um título de seção acima dos itens. Para casos compostos (ícone + texto), use mk-list-subheader diretamente como filho.

// prop simples
<MkList subheader="Seção">...</MkList>

// composto com mk-list-subheader
<MkList>
  <MkListSubheader label="Seção" />
  <MkListItem>...</MkListItem>
</MkList>

<!-- prop simples -->
<mk-list subheader="Seção">...</mk-list>

<!-- composto com mk-list-subheader -->
<mk-list>
  <mk-list-subheader label="Seção"></mk-list-subheader>
  <mk-list-item>...</mk-list-item>
</mk-list>

Leading

Use o slot leading para posicionar um avatar, ícone ou checkbox à esquerda do conteúdo principal.

<MkListItem>
  <MkIcon slot="leading" name="inbox" />
  <MkListItemText primary="Caixa de entrada" />
</MkListItem>

<mk-list-item>
  <mk-icon slot="leading" name="inbox"></mk-icon>
  <mk-list-item-text primary="Caixa de entrada"></mk-list-item-text>
</mk-list-item>

Badges

Use o slot badge para chips que categorizam ou rotulam o item.

<MkListItem>
  <MkListItemText primary="Documentos" secondary="Última atualização hoje" />
  <MkChip slot="badge" color="info" label="Novo"></MkChip>
</MkListItem>

<mk-list-item>
  <mk-list-item-text primary="Documentos" secondary="Última atualização hoje"></mk-list-item-text>
  <mk-chip slot="badge" color="info" label="Novo"></mk-chip>
</mk-list-item>

Ações

Use o slot actions para icon buttons de ação secundária (editar, excluir, etc.).

<MkListItem>
  <MkListItemText primary="Maria Silva" secondary="maria@email.com" />
  <MkIcon slot="actions" name="pencil" />
  <MkIcon slot="actions" name="trash-2" />
</MkListItem>

<mk-list-item>
  <mk-list-item-text primary="Maria Silva" secondary="maria@email.com"></mk-list-item-text>
  <mk-icon slot="actions" name="pencil"></mk-icon>
  <mk-icon slot="actions" name="trash-2"></mk-icon>
</mk-list-item>

Trailing

Use o slot trailing para um controle de estado à direita — switch, chevron ou radio.

<MkListItem>
  <MkListItemText primary="Notificações push" />
  <MkSwitch slot="trailing" checked />
</MkListItem>

<mk-list-item>
  <mk-list-item-text primary="Notificações push"></mk-list-item-text>
  <mk-switch slot="trailing" checked></mk-switch>
</mk-list-item>

Desabilitado

A prop disabled em mk-list-item desativa visualmente o item e suprime os estados hover e active. O texto herda automaticamente a cor desabilitada via CSS custom property.

<MkListItem disabled>
  <MkListItemText primary="Item desabilitado" secondary="Indisponível" />
</MkListItem>

<mk-list-item disabled>
  <mk-list-item-text primary="Item desabilitado" secondary="Indisponível"></mk-list-item-text>
</mk-list-item>

Reordenar

reorderable mostra uma alça de arrasto antes do conteúdo de cada item. O usuário reordena arrastando a alça ou, com ela focada, com ↑, ↓, Home e End. A lista emite mkReorder com { from, to, value? } e não move os itens: reordene os dados e renderize os itens na nova ordem. to é a posição do item depois de removê-lo da origem e inseri-lo no destino.

import { useState } from 'react';
import { MkList, MkListItem, MkListItemText } from '@db1/makuco-ui-react';

const [tarefas, setTarefas] = useState([
  { id: 'pr', titulo: 'Revisar PR' },
  { id: 'docs', titulo: 'Atualizar docs' },
  { id: 'release', titulo: 'Publicar versão' },
]);

const mover = (from: number, to: number) =>
  setTarefas((atuais) => {
    const proximas = [...atuais];
    const [movida] = proximas.splice(from, 1);
    proximas.splice(to, 0, movida);
    return proximas;
  });

<MkList subheader="Prioridades" reorderable onMkReorder={({ detail }) => mover(detail.from, detail.to)}>
  {tarefas.map((tarefa) => (
    <MkListItem key={tarefa.id} value={tarefa.id}>
      <MkListItemText primary={tarefa.titulo} />
    </MkListItem>
  ))}
</MkList>

<mk-list subheader="Prioridades" [reorderable]="true" (mkReorder)="mover($event.detail.from, $event.detail.to)">
  @for (tarefa of tarefas(); track tarefa.id) {
    <mk-list-item [value]="tarefa.id">
      <mk-list-item-text [primary]="tarefa.titulo"></mk-list-item-text>
    </mk-list-item>
  }
</mk-list>

tarefas = signal([
  { id: 'pr', titulo: 'Revisar PR' },
  { id: 'docs', titulo: 'Atualizar docs' },
  { id: 'release', titulo: 'Publicar versão' },
]);

mover(from: number, to: number) {
  this.tarefas.update((atuais) => {
    const proximas = [...atuais];
    const [movida] = proximas.splice(from, 1);
    proximas.splice(to, 0, movida);
    return proximas;
  });
}

Use uma chave estável nos itens (key no React, track no Angular): com ela o foco volta à alça do item movido depois da reordenação.
O item disabled não tem alça ativa e não é movido; mk-list-subheader não tem alça.
Durante o arrasto, o item acompanha o ponteiro com borda tracejada na cor da marca e sombra, e os itens vizinhos deslizam para abrir o destino. Esc devolve o item à origem.

Props — mk-list

Prop	Tipo	Padrão	Descrição
`subheader`	`string`	—	Texto do cabeçalho de seção exibido no topo da lista. Para conteúdo composto, use `mk-list-subheader` diretamente como filho.
`reorderable`	`boolean`	`false`	Mostra a alça de arrasto em cada item e permite reordenar por ponteiro e teclado. Emite `mkReorder`; o consumidor reordena os itens.

Props — mk-list-item

Prop	Tipo	Padrão	Descrição
`disabled`	`boolean`	`false`	Desativa visualmente o item. Suprime hover e active. O texto herda `--text-disabled` automaticamente. Com `reorderable`, a alça fica desabilitada.
`value`	`string`	—	Identificador do item, devolvido em `detail.value` de `mkReorder`.

Props — mk-list-item-text

Prop	Tipo	Padrão	Descrição
`primary`	`string`	—	Texto principal do item. Tipografia body-md, cor high-emphasis.
`secondary`	`string`	—	Texto de suporte abaixo do primary. Tipografia caption, cor low-emphasis. Omitido quando ausente.

Props — mk-list-subheader

Prop	Tipo	Padrão	Descrição
`label`	`string`	—	Texto do cabeçalho. O slot default tem prioridade quando preenchido.

Eventos

Evento	Componente	Payload	Descrição
`mkReorder`	`mk-list`	`{ from: number; to: number; value?: string }`	Emitido ao mover um item. A lista não altera o DOM: aplique `splice(from, 1)` e `splice(to, 0, item)` nos dados.

Slots

Componente	Slot	Descrição
`mk-list`	(default)	Filhos da lista: `mk-list-item` e `mk-list-subheader`.
`mk-list-item`	`leading`	Conteúdo à esquerda: avatar, ícone, checkbox.
`mk-list-item`	(default)	Conteúdo principal. Use `mk-list-item-text` para texto estruturado.
`mk-list-item`	`badge`	Chips ou badges que categorizam o item.
`mk-list-item`	`actions`	Ações do item: icon buttons.
`mk-list-item`	`trailing`	Controle à direita: switch, chevron, radio.
`mk-list-subheader`	(default)	Conteúdo do cabeçalho. Tem prioridade sobre a prop `label`.

Acessibilidade

mk-list expõe role="list" no <ul> interno; mk-list-item expõe role="listitem", preservando a semântica de lista através da fronteira do shadow DOM. O cabeçalho da prop subheader e a região de anúncio ficam fora da lista.
mk-list-item[disabled] suprime hover e active. Elementos focáveis dentro dos slots (switches, botões) devem ter seu próprio estado disabled definido individualmente.
Com reorderable, a alça é um <button> na ordem de Tab, com o nome "Mover {rótulo do item}" (do mk-list-item-text[primary]). ↑ e ↓ movem o item uma posição, Home e End movem para as pontas, e cada movimento é anunciado com a posição final ("Revisar PR movido para a posição 3 de 4"). O arrasto por ponteiro não tem alternativa de ponteiro único sem arrastar.
O item em si não é focável — posicione elementos interativos nos slots para navegação por teclado.

List

On this page