# رافع الملفات واجهة البرمجة

> الخصائص والفتحات والنصوص والتنسيق في رافع الملفات من slotsmith.

## الفتحات

في `FileUploader` عدد 13 من الفتحات. مرّر بديلًا لأي منها في `components`، وكل فتحة لا تمرّرها تبقى على بديلها الافتراضي. فتحات العناصر تستقبل خصائص DOM فيناسبها عنصر المكتبة كما هو، وفتحات الأدوات تستقبل خصائص مسمّاة وتحتاج عادة إلى بضعة أسطر من المحوّل.

| Slot | Kind | Props type | Description |
| --- | --- | --- | --- |
| `Root` | element | `UploaderRootSlotProps` | Element slot: plain `<div>` props for the outer element. Carries `data-variant`, `data-dragging`, `data-disabled` and `data-empty`. |
| `Dropzone` | element | `DropzoneSlotProps` | Element slot: the drop target. Already carries the drag handlers, the keyboard handler, `role="button"`, `tabIndex` and `data-dragging`, so a replacement only has to render them. |
| `Input` | element | `UploaderInputSlotProps` | Element slot: the real `<input type="file">`. It stays in the accessibility tree — visually hidden, not `display: none` — so assistive tech can reach it. |
| `Icon` | widget | `UploaderIconSlotProps` | Widget slot: the picture at rest in the drop zone. |
| `Empty` | widget | `UploaderEmptySlotProps` | Widget slot: the drop zone's resting content. |
| `Trigger` | widget | `UploaderTriggerSlotProps` | Widget slot: the "browse" button inside the drop zone. |
| `List` | element | `UploaderListSlotProps` | Element slot: the `<ul>` holding the items. It takes a `ref` because a windowed list makes this element its scroll container. |
| `Item` | element | `UploaderItemSlotProps` | Element slot: one `<li>`. Carries `data-status` and `data-image`. |
| `Thumbnail` | widget | `ThumbnailSlotProps` | Widget slot: an item's preview. Images get a local object URL as soon as they're picked, so nothing waits for the server. |
| `ItemMeta` | widget | `ItemMetaSlotProps` | Widget slot: the line under an item's name — size, status, or the error. |
| `Progress` | widget | `UploaderProgressSlotProps` | Widget slot: one item's progress. The fallback is a real `progressbar`. |
| `Action` | widget | `UploaderActionSlotProps` | Widget slot shared by remove, retry and cancel, so one button component covers all three. |
| `Rejections` | widget | `RejectionsSlotProps` | Widget slot: the files the constraints turned away. Announced politely. |

## الخصائص

كل خصائص `FileUploader` مجمّعة كما في توثيق المكتبة. الحالة المتحكَّم بها تأتي أزواجًا: مرّر القيمة مع معالج تغييرها، أو القيمة الابتدائية وحدها لتبقى الحالة داخل المكوّن.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `accept` | `string \| string[]` |  |  |
| `multiple` | `boolean` | ``false`, like the native input` | Allow more than one file. Defaults to `false`, like the native input. |
| `maxFiles` | `number` |  | How many items the list may hold in total. |
| `maxSize` | `number` |  |  |
| `minSize` | `number` |  |  |
| `validate` | `(file: File) => string \| null \| undefined` |  | Your own rule. Return a message to refuse the file, or nothing to allow it. |
| `disabled` | `boolean` |  | Nothing can be picked, dropped or removed. |
| `value` | `UploadItem<TData>[]` |  | Controlled items. |
| `onValueChange` | `(items: UploadItem<TData>[]) => void` |  | Called with the new items after every change. |
| `defaultValue` | `InitialValue<TData>` |  | Where an uncontrolled uploader starts: items, files or URLs. |
| `onFilesChange` | `(files: File[]) => void` |  | Convenience for picker mode: the picked files, whenever they change. |
| `onUrlsChange` | `(urls: string[]) => void` |  | Convenience for upload mode: the stored URLs, whenever they change. |
| `name` | `string` |  | The form field name. A plain HTML form then submits every item under it: a file picked in the browser as the file, as `<input type="file" name>` would, and a file already on a server (restored from a URL, or uploaded) as its URL, so the server can tell what to keep. |
| `upload` | `UploadFn<TData>` |  | Sends one file. Omit it and nothing is ever uploaded — the component becomes a picker and items stay `ready`. |
| `autoUpload` | `boolean` | `true` | Start uploading as soon as files are picked. Defaults to `true`. |
| `concurrency` | `number` | `3` | How many uploads may run at once. Defaults to `3`. |
| `onUploaded` | `(item: UploadItem<TData>) => void` |  | Called for each file that finished uploading. |
| `onUploadError` | `(error: unknown, item: UploadItem<TData>) => void` |  | Called when an upload fails. |
| `onReject` | `(rejections: Rejection[]) => void` |  | Called with the files the constraints turned away. |
| `variant` | `FileUploaderVariant` | `dropzone` | How the component is laid out. Defaults to `dropzone`. |
| `components` | `Partial<FileUploaderComponents>` |  | Replace any part; the rest fall back to `SlotsmithProvider`'s `components.fileUploader`, then to the built-in ones. |
| `labels` | `Partial<FileUploaderLabels>` |  | Override any text. Wins over `locale`. |
| `locale` | `LocaleInput` | `the provider's` | The language: a locale object, or the tag of one given to `SlotsmithProvider`. Defaults to the provider's. |
| `validationLabels` | `Partial<ValidationLabels>` |  | Wording for rejection messages. |
| `slotProps` | `FileUploaderSlotProps` |  | Extra DOM props for the element parts. |
| `preview` | `boolean \| "auto"` |  | Object-URL previews for images. `"auto"` (the default) means images only. |
| `hideList` | `boolean` |  | Hide the item list, e.g. when you render the files yourself. |
| `children` | `ReactNode` |  | Rendered inside the drop zone, under the title. |
| `captureWindowDrops` | `boolean` |  | Swallow drops that miss the drop zone, so the browser doesn't open the file. |
| `virtual` | `FileUploaderVirtualOptions` |  | Renders only the items in view, for batches of hundreds: pass the virtualizer hook (`useVirtualizer` from `@tanstack/react-virtual`) as `use`, and the sizes. |

## النصوص واللغات

كل نص يعرضه `FileUploader` أو يعلنه، مع قيمته الافتراضية بالإنجليزية. مرّر `labels` لتغيير بعضها في مكوّن واحد، أو `locale` لتحويل كل النصوص إلى لغة أخرى. العرض أدناه يفعل الأمرين.

| Label | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | `"Drag and drop, or browse"` | The drop zone's headline. |
| `hint` | `(limits: { accept?: string; maxSize?: string; maxFiles?: number }) => ReactNode` | `({ accept, maxSize, maxFiles }) => { const parts = [ accept ? accept.replace(/,/g, ", ") : undefined, maxSize ? `up to ${maxSize}` : undefined, maxFiles && maxFiles > 1 ? `max ${maxFiles} files` : undefined, ].filter(Boolean); return parts.join(" · "); }` | The line under it; the default names the limits. |
| `dropHere` | `ReactNode` | `"Drop to add"` | While a file is over the zone. |
| `browse` | `ReactNode` | `"Browse"` | The browse button. |
| `dropzone` | `string` | `"Add files"` | Accessible name of the drop zone. |
| `remove` | `string` | `"Remove file"` |  |
| `retry` | `string` | `"Retry upload"` |  |
| `cancel` | `string` | `"Cancel upload"` |  |
| `progress` | `(name: string) => string` | `(name) => `Uploading ${name}`` | Accessible name of an item's progress bar. |
| `ready` | `ReactNode` | `"Ready"` | Status wording per item state. |
| `uploading` | `ReactNode` | `"Uploading…"` |  |
| `done` | `ReactNode` | `"Uploaded"` |  |
| `failed` | `ReactNode` | `"Failed"` |  |
| `preview` | `(name: string) => string` | `(name) => `Preview of ${name}`` | Accessible name for a preview. |
| `dismiss` | `string` | `"Dismiss"` | Dismisses the rejection list. |
| `rejectedTitle` | `(count: number) => ReactNode` | `(count) => `${count} ${count === 1 ? "file" : "files"} not added`` | Announced when files are refused. |

### رسائل التحقق

رسائل الملفات التي ترفضها القيود، وهي قسم ثانٍ من النصوص. مرّر `validationLabels` لتغيير بعضها في مكوّن واحد، وحزمة `locale` تترجمها مع بقية النصوص.

| Label | Type | Default | Description |
| --- | --- | --- | --- |
| `wrongType` | `(name: string) => string` | `(name) => `${name} is not an allowed file type`` | A file that matches none of the `accept` tokens. Receives the file name. |
| `tooLarge` | `(name: string, max: string) => string` | `(name, max) => `${name} is too large (max ${max})`` | A file over `maxSize`. Receives the file name and the limit, formatted (`5 MB`). |
| `tooSmall` | `(name: string, min: string) => string` | `(name, min) => `${name} is too small (min ${min})`` | A file under `minSize`. Receives the file name and the limit, formatted (`1 KB`). |
| `tooMany` | `(max: number) => string` | `(max) => `Only ${max} ${max === 1 ? "file" : "files"} allowed`` | A file past `maxFiles`, counting the items already listed. Receives the limit. |

## التنسيق

أسماء الأصناف التي تضعها البدائل الافتراضية في `FileUploader` على عناصرها، والمتغيرات التي يقرؤها ملف تنسيقه. اضبط متغيرًا على المكوّن أو على أي عنصر يحيط به لتغيير مظهره، واستهدف الصنف فقط لما لا يغطيه متغير.

Classes: `sfu`, `sfu__actions`, `sfu__error`, `sfu__compact`, `sfu__hint`, `sfu__input`, `sfu__icon`, `sfu__copy`, `sfu__title`, `sfu__browse`, `sfu__thumb`, `sfu__thumb-img`, `sfu__meta`, `sfu__name`, `sfu__sub`, `sfu__progress`, `sfu__progress-bar`, `sfu__action`, `sfu__rejections`, `sfu__zone`, `sfu__list`, `sfu__item`

Tokens: `--sfu-accent`, `--sfu-bg`, `--sfu-border`, `--sfu-danger`, `--sfu-font-size`, `--sfu-gap`, `--sfu-hover`, `--sfu-muted`, `--sfu-radius`, `--sfu-surface`, `--sfu-text`, `--sfu-tile-size`, `--ss-accent`, `--ss-border`, `--ss-danger`, `--ss-font-size`, `--ss-hover`, `--ss-muted`, `--ss-radius`, `--ss-surface`, `--ss-text`