@apollion-dsi/core 3.0.0

package/lib/form/UploadCard/UploadCard.interface.d.ts

@@ -0,0 +1,203 @@
+import { DragEvents } from '../../hooks/useDrag';
+/**
+ * Configuração da requisição de upload feita pelo `UploadCard.submit()`.
+ *
+ * Não é necessária para uso puro como coletor de arquivos (sem submit).
+ *
+ * @example
+ * ```tsx
+ * <UploadCard
+ *   uploadConfig={{
+ *     endpoint: '/api/files',
+ *     headers: { 'X-CSRF-Token': csrf },
+ *     auth: { username: 'admin', password: 'secret' },
+ *   }}
+ * />
+ * ```
+ */
+export interface UploadFileRequestConfig {
+    endpoint: string;
+    timeout?: number;
+    responseType?: XMLHttpRequestResponseType;
+    withCredentials?: boolean;
+    headers?: {
+        [key: string]: any;
+    };
+    params?: {
+        [key: string]: any;
+    };
+    /** Nome do field do FormData (default `'file'`). */
+    formDataFileKey?: string;
+    /** Campos extras anexados ao FormData (ex.: token, metadata). */
+    formDataParams?: {
+        key: string;
+        value: string | Blob;
+        fileName?: string;
+    }[];
+    /** Autenticação básica — gera o header `Authorization` automaticamente. */
+    auth?: {
+        username: string;
+        password: string;
+    };
+}
+/**
+ * Argumentos da função utilitária `uploadFile` (uso direto, fora do
+ * `UploadCard`). Geralmente você não precisa interagir com isso.
+ */
+export interface UploadParameters {
+    file: File;
+    fieldName: string;
+    requestConfig: UploadFileRequestConfig;
+    onProgress?: (progress: number, success?: boolean, response?: any) => void;
+    onFail?: () => void;
+}
+/**
+ * Item de arquivo gerenciado pelo `UploadCard`.
+ *
+ * `id` é gerado via `nanoid` para rastreamento estável na UI. Os campos
+ * `upload*` ficam preenchidos durante e depois do upload.
+ */
+export type FileItem = {
+    file: File;
+    fileName: string;
+    fileSize: string;
+    id: string;
+    /** Bytes carregados (formatados, ex.: `'1.20 MB'`). */
+    uploadLoaded?: string;
+    /** Percentual carregado, ex.: `'45%'`. */
+    uploadPercentage?: string;
+    uploadCompleted?: boolean;
+    uploadError?: boolean;
+    uploadResponse?: any;
+};
+export type FileItemProps = {
+    removeFile(id: string): void;
+    disabled?: boolean;
+    readOnly?: boolean;
+} & FileItem;
+/**
+ * Ref imperativa exposta pelo `UploadCard`.
+ *
+ * Use para disparar o upload, manipular a lista de arquivos e ler o estado
+ * atual sem depender de re-renders do componente pai.
+ */
+export type UploadCardRef = {
+    /** Faz upload de todos os arquivos atuais. Devolve as respostas em paralelo. */
+    submit(config?: UploadFileRequestConfig): Promise<any>;
+    removeFile(id: string): void;
+    removeAll(): void;
+    addFiles(file: File | File[]): void;
+    files: FileItem[];
+};
+type CustomButtonProps = {
+    isDragging?: boolean;
+    openFileDialog: () => void;
+    files: FileItem[];
+    isSubmitting?: boolean;
+};
+/**
+ * Tipos de ação reportados pelo `onChange` do `UploadCard`. Útil para
+ * reagir a apenas certas operações (ex.: persistir só em `REMOVE`).
+ */
+export type FileActionType = 'ADD_INITIAL_FILES' | 'ADD' | 'REMOVE' | 'REPLACE' | 'UPDATE' | 'RESET';
+/**
+ * Payload entregue ao `onChange`. `payload` é o item afetado pela ação
+ * (ou array, no caso de `ADD_INITIAL_FILES`).
+ */
+export type UploadCardOnChangeValue = {
+    files: FileItem[];
+    type: FileActionType;
+    payload?: FileItem | FileItem[];
+};
+/**
+ * Props do componente `UploadCard`.
+ *
+ * @example
+ * ```tsx
+ * <UploadCard
+ *   accept={['image/*', 'application/pdf']}
+ *   acceptLabel="PNG, JPEG, PDF"
+ *   maxSize={10 * 1024 * 1024}
+ *   onChange={(value) => console.log(value)}
+ * />
+ *
+ * <UploadCard compact accept={['.png']} />
+ * ```
+ */
+export type UploadCardProps = {
+    /** Nome do `<input type="file">` (necessário em formulários nativos). */
+    name?: string;
+    /**
+     * Variante visual compacta — linha única em vez do card grande.
+     *
+     * @default false
+     */
+    compact?: boolean;
+    /**
+     * Tipos de arquivo aceitos. Aceita extensões (`'.png'`) ou MIME-types
+     * (`'image/*'`). Itens recusados disparam `onUnsupportedFile`.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept
+     */
+    accept: string[];
+    /**
+     * Tamanho máximo por arquivo, em bytes.
+     *
+     * @default 15728640 // 15 MB
+     */
+    maxSize?: number;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /**
+     * Restringe a um único arquivo (drag/drop e dialog).
+     *
+     * @default false
+     */
+    singleFile?: boolean;
+    /** Label do tipo aceito (ex.: `"PNG, JPEG, PDF"`) exibido no card. */
+    acceptLabel?: string;
+    /**
+     * Texto do botão de seleção.
+     *
+     * @default 'Enviar arquivos'
+     */
+    buttonText?: string;
+    /** Arquivos a popular no mount (útil em edição de formulários). */
+    initialFiles?: File | File[];
+    /** Configuração do upload — necessária para usar `ref.submit()`. */
+    uploadConfig?: UploadFileRequestConfig;
+    /** Callback disparado a cada mudança (ADD, REMOVE, UPDATE, ...). */
+    onChange?: (value: UploadCardOnChangeValue) => void;
+    /** Callback para arquivos rejeitados por `accept` (não pelo `maxSize`). */
+    onUnsupportedFile?: (f: File) => void;
+    /**
+     * Substitui o botão padrão por um customizado. Recebe utilitários para
+     * abrir o dialog, ler arquivos atuais e estado de submit.
+     */
+    customButton?: (p: CustomButtonProps) => React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+};
+/**
+ * Props internas passadas para os componentes de variante
+ * (`UploadCardRegular`/`UploadCardCompact`). Não exposto no barrel público.
+ */
+export type VariantProps = {
+    removeFile: (id: string) => void;
+    openFileDialogButton: React.ReactNode;
+    events?: DragEvents;
+    inputFile: React.ReactNode;
+} & UploadCardProps & CustomButtonProps;
+/** Props recebidas pelos styled-components (foco em estado visual). */
+export type VariantPropsStyle = {
+    active?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+};
+/** Opções aceitas pelo hook interno `useFileState`. */
+export interface useFileStateOptions {
+    single?: UploadCardProps['singleFile'];
+    maxSize?: UploadCardProps['maxSize'];
+    onChange?: UploadCardProps['onChange'];
+}
+export {};