Upload

Composição de dropzone (`mk-upload`), lista (`mk-upload-list`) e item (`mk-upload-item`) para upload de arquivos com progresso e status por arquivo.

O upload de arquivos é composto por três elementos hierárquicos, seguindo o mesmo padrão de composição usado em mk-tabs/mk-tab/mk-tab-panel:

mk-upload — a dropzone e contêiner raiz. Cuida apenas de seleção de arquivos (clique ou drag-and-drop) e validação client-side (accept, maxSize, maxFiles).
mk-upload-list — wrapper estrutural que conta os mk-upload-item filhos e exibe "N arquivos". Deve ser filho direto de mk-upload.
mk-upload-item — representa um arquivo com seu status (uploading | success | error), progresso, preview e ações (cancelar, visualizar, remover). Deve ser filho direto de mk-upload-list.

O envio real do arquivo (a requisição HTTP) é responsabilidade da aplicação. O fluxo esperado: escutar mkAdd em mk-upload, iniciar o upload, e manter a lista de entradas (file, status, progress, errorMessage, previewUrl) no próprio estado da aplicação, renderizando um mk-upload-item por entrada dentro de mk-upload-list, dentro de mk-upload.

Padrão

import { MkUpload } from '@db1/makuco-ui-react';

<MkUpload onMkAdd={(e) => console.log(e.detail)} />

<mk-upload (mkAdd)="onAdd($event)"></mk-upload>

Múltiplos arquivos

Ative multiple para permitir seleção de vários arquivos. Use maxFiles para limitar a quantidade aceita por chamada de mkAdd.

<MkUpload multiple maxFiles={5} />

<mk-upload multiple max-files="5"></mk-upload>

Tipos aceitos

Use accept com a mesma sintaxe do atributo nativo <input accept>. Arquivos rejeitados disparam mkError com type: "accept".

<MkUpload accept="image/*, .pdf" />

<mk-upload accept="image/*, .pdf"></mk-upload>

Validação de tamanho

Use maxSize (em bytes) para rejeitar arquivos grandes. Arquivos rejeitados disparam mkError com type: "maxSize".

<MkUpload maxSize={5 * 1024 * 1024} />

<mk-upload max-size="5242880"></mk-upload>

Estado desabilitado

<MkUpload disabled />

<mk-upload disabled></mk-upload>

Estado inválido

Defina invalid para o estado visual de erro (borda e fundo error). A mensagem em si fica a critério do consumidor — por exemplo, um texto de ajuda próximo à dropzone.

<MkUpload invalid />

<mk-upload invalid></mk-upload>

Lista de arquivos

mk-upload-list conta os mk-upload-item filhos automaticamente e exibe "N arquivos". Cada item exibe ícone/corpo/ações diferentes conforme o status. Sempre como filho direto de mk-upload.

import { MkUpload, MkUploadList, MkUploadItem } from '@db1/makuco-ui-react';

<MkUpload multiple>
  <MkUploadList>
    <MkUploadItem file={file} status="uploading" progress={65} />
    <MkUploadItem file={file} status="success" />
    <MkUploadItem file={file} status="error" errorMessage="Arquivo excede o tamanho máximo permitido" />
  </MkUploadList>
</MkUpload>

<mk-upload multiple>
  <mk-upload-list>
    <mk-upload-item [file]="file" status="uploading" [progress]="65"></mk-upload-item>
    <mk-upload-item [file]="file" status="success"></mk-upload-item>
    <mk-upload-item [file]="file" status="error" error-message="Arquivo excede o tamanho máximo permitido"></mk-upload-item>
  </mk-upload-list>
</mk-upload>

Fluxo completo

Exemplo composto: a dropzone escuta mkAdd, cria uma entrada por arquivo e simula o progresso do envio até success. mkCancel/mkRemove removem a entrada da lista.

Props — mk-upload

Prop	Tipo	Padrão	Descrição
`accept`	`string`	—	Tipos aceitos, repassado ao input nativo e validado no drop (MIME types e/ou extensões).
`multiple`	`boolean`	`false`	Permite selecionar mais de um arquivo por vez.
`maxSize`	`number`	`0`	Tamanho máximo por arquivo em bytes. `0` = sem limite.
`maxFiles`	`number`	`0`	Quantidade máxima de arquivos aceitos por chamada de `mkAdd` (client-side). `0` = sem limite.
`disabled`	`boolean`	`false`	Desabilita clique e drag-and-drop.
`invalid`	`boolean`	`false`	Estado visual de erro da dropzone (borda/fundo `error`).
`locale`	`string`	—	Tag BCP 47 usada para resolver as mensagens i18n do texto fixo da dropzone. Locales suportados: `pt`, `es`, `en`. Recai para `<html lang>` quando ausente.

Props — mk-upload-list

mk-upload-list é puramente estrutural — não possui lista de arquivos própria. A contagem é derivada automaticamente dos mk-upload-item recebidos via slot, com singular ("1 arquivo") e plural ("2 arquivos") traduzidos via i18n.

Prop	Tipo	Padrão	Descrição
`locale`	`string`	—	Tag BCP 47 usada para resolver o `aria-label` e o contador via i18n. Locales suportados: `pt`, `es`, `en`.

Props — mk-upload-item

Prop	Tipo	Padrão	Descrição
`file`	`File`	—	Arquivo representado por este item. Usado para nome, tamanho e geração automática de preview.
`status`	`"uploading" \| "success" \| "error"`	`"uploading"`	Status atual do envio, controla ícone, corpo e ações renderizadas.
`progress`	`number`	`0`	Percentual de envio (`0`–`100`), relevante apenas quando `status="uploading"`.
`errorMessage`	`string`	—	Mensagem de erro específica deste arquivo, relevante apenas quando `status="error"`.
`previewUrl`	`string`	—	URL definitiva (ex: retornada pelo servidor). Quando ausente e o arquivo é uma imagem, uma preview local é gerada via `URL.createObjectURL(file)`.
`locale`	`string`	—	Tag BCP 47 usada para resolver as mensagens i18n do item (label do progresso, "Concluído", aria-labels das ações). Locales suportados: `pt`, `es`, `en`.

Quando o arquivo em status="success" não é uma imagem, o ícone exibido varia por categoria: planilhas (csv, xls, xlsx, ods) usam o ícone sheet em success, PDFs usam file em error, documentos de texto (doc, docx, txt, rtf, odt) usam file-text em info, e qualquer outro tipo usa file em gray.

Eventos

Evento	Componente	Payload	Descrição
`mkAdd`	`mk-upload`	`File[]`	Emitido quando arquivos são aceitos após validação de `accept`/`maxSize`/`maxFiles`.
`mkError`	`mk-upload`	`{"{ type: 'maxSize' \| 'maxFiles' \| 'accept', files: File[] }"}`	Emitido quando um ou mais arquivos são rejeitados pela validação client-side.
`mkCancel`	`mk-upload-item`	`File`	Emitido ao clicar em cancelar (`status="uploading"`). A aplicação deve abortar a requisição real.
`mkRemove`	`mk-upload-item`	`File`	Emitido ao clicar em remover (`status="success"` ou `"error"`).
`mkView`	`mk-upload-item`	`File`	Emitido ao clicar em visualizar (`status="success"`), após abrir o arquivo em nova aba.

Slots

Componente	Slot	Descrição
`mk-upload`	(default)	Um único `mk-upload-list`.
`mk-upload-list`	(default)	Instâncias de `mk-upload-item`.

Acessibilidade

A dropzone tem role="button", tabindex="0" e aria-label="Clique ou arraste arquivos aqui".
aria-dropeffect="copy" é aplicado enquanto a dropzone estiver habilitada; aria-disabled reflete o estado disabled.
Enter e Espaço ativam o seletor de arquivos nativo a partir da dropzone.
mk-upload-list usa role="list" com aria-label="Arquivos anexados"; cada mk-upload-item usa role="listitem".
Cada botão de ação (cancelar, visualizar, remover) tem aria-label específico — nunca um rótulo genérico.
A mensagem de erro do item usa role="alert" para anúncio imediato por leitores de tela.
O item em uploading usa mk-progress-bar internamente, que já expõe role="progressbar" com o percentual e o rótulo.

Upload

On this page