denwa-react-shared/skills/media-management/SKILL.md

---
name: media-management
description: >
  Handle single/multiple image uploads and file attachments. 
  Covers drag-and-drop sorting, temporary upload patterns, 
  and media deletion.
type: framework
library: denwa-react-shared
framework: react
library_version: "1.0.88"
requires:
  - session-auth
sources:
  - "Denwa799/react-shared:src/shared/ui/image-upload/base-image-upload.tsx"
  - "Denwa799/react-shared:src/shared/ui/file-upload/file-upload.tsx"
---

# Media & File Management

The library provides `BaseImageUpload` for image galleries and `FileUpload` for general documents. Both rely on a two-step process: uploading to a temporary location first, then associating the path with the entity.

## Setup

### Image Upload with Sorting
```tsx
import { BaseImageUpload, TAdminImage } from 'denwa-react-shared';

const Gallery = () => {
  return (
    <BaseImageUpload
      isMultiple
      label="Галерея"
      images={images}
      onUpdateTempImage={handleTempUpload}
      onUpdateItems={handleReorder}
      onUpdateDeleteItems={handleDelete}
    />
  );
};
```

## Core Patterns

### Two-Step Upload Process
Components emit native File objects. You must upload these to a temporary storage API and return the resulting path to the component's state.

```tsx
const handleTempUpload = async (file: File) => {
  const formData = new FormData();
  formData.append('file', file);
  
  const response = await api.upload(formData); // Your API
  return response.path; // e.g. "/temp/random-id.png"
};
```

### File Attachments
For non-image files, use `FileUpload`. It supports single or multiple files with size/extension limits.

```tsx
import { FileUpload } from 'denwa-react-shared';

<FileUpload
  label="Документ"
  onUpload={handleFileUpload}
  onRemove={handleFileRemove}
  items={data.files}
  isMultiple={false}
/>
```

## Common Mistakes

### CRITICAL Forgetting to handle reordering
Wrong:
```tsx
// Only handling uploads
<BaseImageUpload onUpdateTempImage={upload} /> 
```
Correct:
```tsx
<BaseImageUpload 
  onUpdateTempImage={upload}
  onUpdateItems={(newItems) => setImages(newItems)}
/>
```
If `onUpdateItems` is missing, drag-and-drop reordering will visually work but won't persist to state.

Source: src/shared/ui/image-upload/base-image-upload.tsx

### HIGH Passing only URLs instead of Image objects
Wrong:
```tsx
<BaseImageUpload images={["/image1.png"]} />
```
Correct:
```tsx
<BaseImageUpload images={[{ id: 1, path: "/image1.png" }]} />
```
`BaseImageUpload` expects an array of objects containing `id` and `path`, not raw strings.

Source: src/shared/ui/image-upload/types.ts

### MEDIUM Missing upload button due to limits
If the `limit` prop is reached, the "Upload" button disappears. Ensure you communicate this UI behavior or provide a way to delete items.

Source: src/shared/ui/image-upload/base-image-upload.tsx:55