@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/form/image-files/README.md

@@ -0,0 +1,468 @@
+# ImageFilesField
+
+An image upload and management component. Users can drag-and-drop or click to browse for images. Uploaded images are displayed in a grid with thumbnails, full-size previews, and action buttons (delete, preview). Supports multiple images, aspect ratio preservation, and optional confirmation before deletion.
+
+> Think of it as a photo gallery manager for your form. Upload, preview, and manage images with a consistent UI.
+
+## Features
+
+- **Image upload** — supports drag-and-drop and click-to-browse.
+- **Image preview** — click an image to view it in full size.
+- **Thumbnail generation** — automatically generates thumbnails for uploaded images.
+- **Image grid display** — shows uploaded images in a responsive grid.
+- **Delete with confirmation** — optional `removeFileConfirm` callback for deletion confirmation.
+- **Multiple images** — supports uploading multiple images at once.
+- **Aspect ratio preservation** — images maintain their original aspect ratio.
+- **Disabled / readonly** modes.
+- **Compact mode** for dense UIs.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import ImageFilesField from "@ticatec/uniface-element/ImageFilesField";
+import type { ImageFile, RemoveConfirm, FileUpload } from "@ticatec/uniface-element/ImageFilesField";
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import ImageFilesField from "@ticatec/uniface-element/ImageFilesField";
+  import type { ImageFile, FileUpload } from "@ticatec/uniface-element/ImageFilesField";
+
+  let images = $state<ImageFile[]>([]);
+
+  // Simulated upload function
+  const uploadImage: FileUpload = (file, progressUpdate, onUploaded, errorHandler) => {
+    // Simulate upload progress
+    let progress = 0;
+    const interval = setInterval(() => {
+      progress += 10;
+      progressUpdate(Math.floor(file.size * (progress / 100)));
+
+      if (progress >= 100) {
+        clearInterval(interval);
+        // Simulate successful upload
+        const fakeUrl = `/uploads/${file.name}`;
+        const fakeThumbnail = `/thumbnails/${file.name}`;
+        onUploaded(fakeUrl, fakeThumbnail);
+      }
+    }, 100);
+
+    return {
+      cancel: async () => {
+        clearInterval(interval);
+        return true;
+      }
+    };
+  };
+</script>
+
+<ImageFilesField
+  bind:images={images}
+  uploadFile={uploadImage}
+  maxImages={5}
+/>
+```
+
+## Props
+
+`ImageFilesField` extends `CommonFieldProps`, so it inherits `variant`, `compact`, `disabled`, `readonly`, `style`, `error`, `tooltip`, `theme`, `placeholder`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `images` | `Array<ImageFile>` (bindable) | `[]` | Array of uploaded images. Each image has `name`, `uri`, and `thumbnail` properties. |
+| `uploadFile` | `FileUpload` | — | **Required.** Function that handles image upload. Receives `(file, progressUpdate, onUploaded, errorHandler)` and returns an `UploadProgress` object with a `cancel()` method. |
+| `maxImages` | `number` | `10` | Maximum number of images allowed. |
+| `removeFileConfirm` | `RemoveConfirm` | — | Optional callback for deletion confirmation. Receives the image to be deleted and returns a Promise<boolean>. |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Visual style variant. |
+| `compact` | `boolean` | `false` | Dense layout for table cells and inline forms. |
+| `disabled` | `boolean` | `false` | Fully disabled — no upload or delete actions. |
+| `readonly` | `boolean` | `false` | Read-only — no upload or delete actions, but images are visible. |
+| `style` | `string` | — | Inline CSS on the editor root. |
+| `error` | `string` | — | Validation error text — triggers the editor's error state. |
+| `tooltip` | `string` | — | Hover tooltip on the editor. |
+| `theme` | `string` | — | Rendered as `data-theme` on the editor for scoped styling. |
+| `onchange` | `(images: Array<ImageFile>) => void` | — | Fires when the images array changes (upload or delete). Receives the updated images array. |
+| `onfocus` | `(event: FocusEvent) => void` | — | Editor focus. |
+| `onblur` | `(event: FocusEvent) => void` | — | Editor blur. |
+
+## Events
+
+| Event | Signature | Description |
+|-------|-----------|-------------|
+| `onchange` | `(images: Array<ImageFile>) => void` | Fires when the images array changes (upload or delete). Receives the updated images array. |
+| `onfocus` | `(event: FocusEvent) => void` | Editor focus. |
+| `onblur` | `(event: FocusEvent) => void` | Editor blur. |
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `focus()` | `() => void` | Moves focus to the editor. |
+
+```svelte
+<script lang="ts">
+  import ImageFilesField from "@ticatec/uniface-element/ImageFilesField";
+
+  let editorRef;
+
+  function focusEditor() {
+    editorRef.focus();
+  }
+</script>
+
+<ImageFilesField bind:this={editorRef} bind:images={images} uploadFile={uploadImage} />
+<button onclick={focusEditor}>Focus</button>
+```
+
+## `FileUpload` — upload function
+
+The `uploadFile` callback is required. It receives:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `file` | `File` | The file to upload. |
+| `progressUpdate` | `(bytesUploaded: number) => void` | Call this to report upload progress. |
+| `onUploaded` | `(url: string, thumbnail: string) => void` | Call this when upload is complete. Pass the full-size URL and thumbnail URL. |
+| `errorHandler` | `(error: Error) => void` | Call this if upload fails. Pass an Error object. |
+
+It must return an `UploadProgress` object:
+
+```typescript
+interface UploadProgress {
+  cancel: () => Promise<boolean>;
+}
+```
+
+The `cancel()` method allows the user to cancel an in-progress upload.
+
+```svelte
+<script lang="ts">
+  import ImageFilesField from "@ticatec/uniface-element/ImageFilesField";
+  import type { FileUpload } from "@ticatec/uniface-element/ImageFilesField";
+
+  let images = $state([]);
+
+  const uploadImage: FileUpload = (file, progressUpdate, onUploaded, errorHandler) => {
+    // Simulate upload with progress
+    let bytesUploaded = 0;
+    const totalBytes = file.size;
+    const interval = setInterval(() => {
+      bytesUploaded += 1024; // 1KB per tick
+      if (bytesUploaded >= totalBytes) {
+        clearInterval(interval);
+        onUploaded(`/uploads/${file.name}`, `/thumbnails/${file.name}`);
+      } else {
+        progressUpdate(bytesUploaded);
+      }
+    }, 100);
+
+    return {
+      cancel: async () => {
+        clearInterval(interval);
+        return true; // upload was cancelled
+      }
+    };
+  };
+</script>
+
+<ImageFilesField bind:images={images} uploadFile={uploadImage} />
+```
+
+## `ImageFile` — image object
+
+Each image in the `images` array is an `ImageFile` object:
+
+```typescript
+interface ImageFile {
+  name: string;    // Image name
+  uri: string;     // Full-size image URL (after upload)
+  thumbnail: string; // Thumbnail URL (after upload)
+}
+```
+
+## Examples
+
+### Image upload with confirmation
+
+```svelte
+<script lang="ts">
+  import ImageFilesField from "@ticatec/uniface-element/ImageFilesField";
+  import type { ImageFile, FileUpload, RemoveConfirm } from "@ticatec/uniface-element/ImageFilesField";
+
+  let images = $state<ImageFile[]>([]);
+
+  const uploadImage: FileUpload = (file, progressUpdate, onUploaded, errorHandler) => {
+    let bytesUploaded = 0;
+    const totalBytes = file.size;
+    const interval = setInterval(() => {
+      bytesUploaded += 1024;
+      if (bytesUploaded >= totalBytes) {
+        clearInterval(interval);
+        onUploaded(`/uploads/${file.name}`, `/thumbnails/${file.name}`);
+      } else {
+        progressUpdate(bytesUploaded);
+      }
+    }, 100);
+
+    return {
+      cancel: async () => {
+        clearInterval(interval);
+        return true;
+      }
+    };
+  };
+
+  const removeImageConfirm: RemoveConfirm = async (image) => {
+    return confirm(`Are you sure you want to delete ${image.name}?`);
+  };
+</script>
+
+<ImageFilesField
+  bind:images={images}
+  uploadFile={uploadImage}
+  removeFileConfirm={removeImageConfirm}
+  maxImages={5}
+/>
+```
+
+### Multiple images gallery
+
+```svelte
+<script lang="ts">
+  import ImageFilesField from "@ticatec/uniface-element/ImageFilesField";
+  import type { ImageFile, FileUpload } from "@ticatec/uniface-element/ImageFilesField";
+
+  let images = $state<ImageFile[]>([]);
+
+  const uploadImage: FileUpload = (file, progressUpdate, onUploaded, errorHandler) => {
+    let progress = 0;
+    const interval = setInterval(() => {
+      progress += 10;
+      progressUpdate(Math.floor(file.size * (progress / 100)));
+
+      if (progress >= 100) {
+        clearInterval(interval);
+        onUploaded(`/uploads/${file.name}`, `/thumbnails/${file.name}`);
+      }
+    }, 100);
+
+    return {
+      cancel: async () => {
+        clearInterval(interval);
+        return true;
+      }
+    };
+  };
+</script>
+
+<div class="image-gallery">
+  <h3>Upload Images</h3>
+  <ImageFilesField
+    bind:images={images}
+    uploadFile={uploadImage}
+    maxImages={10}
+  />
+  <div class="image-grid">
+    {#each images as image}
+      <div class="image-item">
+        <img src={image.thumbnail} alt={image.name} />
+        <div class="image-info">
+          <p>{image.name}</p>
+          <a href={image.uri} download>Download</a>
+        </div>
+      </div>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .image-gallery {
+    max-width: 800px;
+    margin: 20px;
+  }
+  .image-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+    gap: 16px;
+    margin-top: 16px;
+  }
+  .image-item {
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    overflow: hidden;
+  }
+  .image-item img {
+    width: 100%;
+    height: 200px;
+    object-fit: cover;
+  }
+  .image-info {
+    padding: 12px;
+  }
+  .image-info p {
+    margin: 0 0 8px 0;
+    font-size: 14px;
+  }
+  .image-info a {
+    color: #3b82f6;
+    text-decoration: none;
+  }
+  .image-info a:hover {
+    text-decoration: underline;
+  }
+</style>
+```
+
+### Disabled and readonly modes
+
+```svelte
+<script lang="ts">
+  import ImageFilesField from "@ticatec/uniface-element/ImageFilesField";
+  import type { ImageFile, FileUpload } from "@ticatec/uniface-element/ImageFilesField";
+
+  let disabledImages: ImageFile[] = [
+    { name: "disabled-image.jpg", uri: "/uploads/disabled-image.jpg", thumbnail: "/thumbnails/disabled-image.jpg" }
+  ];
+  let readonlyImages: ImageFile[] = [
+    { name: "readonly-image.png", uri: "/uploads/readonly-image.png", thumbnail: "/thumbnails/readonly-image.png" }
+  ];
+  let normalImages: ImageFile[] = [];
+
+  const uploadImage: FileUpload = (file, progressUpdate, onUploaded, errorHandler) => {
+    let progress = 0;
+    const interval = setInterval(() => {
+      progress += 10;
+      progressUpdate(Math.floor(file.size * (progress / 100)));
+
+      if (progress >= 100) {
+        clearInterval(interval);
+        onUploaded(`/uploads/${file.name}`, `/thumbnails/${file.name}`);
+      }
+    }, 100);
+
+    return {
+      cancel: async () => {
+        clearInterval(interval);
+        return true;
+      }
+    };
+  };
+</script>
+
+<div style="display: flex; flex-direction: column; gap: 16px;">
+  <ImageFilesField
+    bind:images={disabledImages}
+    uploadFile={uploadImage}
+    disabled
+  />
+  <ImageFilesField
+    bind:images={readonlyImages}
+    uploadFile={uploadImage}
+    readonly
+  />
+  <ImageFilesField
+    bind:images={normalImages}
+    uploadFile={uploadImage}
+  />
+</div>
+```
+
+### Compact mode
+
+```svelte
+<script lang="ts">
+  import ImageFilesField from "@ticatec/uniface-element/ImageFilesField";
+  import type { ImageFile, FileUpload } from "@ticatec/uniface-element/ImageFilesField";
+
+  let images = $state<ImageFile[]>([]);
+
+  const uploadImage: FileUpload = (file, progressUpdate, onUploaded, errorHandler) => {
+    let progress = 0;
+    const interval = setInterval(() => {
+      progress += 10;
+      progressUpdate(Math.floor(file.size * (progress / 100)));
+
+      if (progress >= 100) {
+        clearInterval(interval);
+        onUploaded(`/uploads/${file.name}`, `/thumbnails/${file.name}`);
+      }
+    }, 100);
+
+    return {
+      cancel: async () => {
+        clearInterval(interval);
+        return true;
+      }
+    };
+  };
+</script>
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Images</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Row 1</td>
+      <td>
+        <ImageFilesField
+          bind:images={images}
+          uploadFile={uploadImage}
+          compact
+        />
+      </td>
+    </tr>
+  </tbody>
+</table>
+```
+
+## Behavior Notes
+
+### Upload flow
+
+1. User clicks the upload icon or drags and drops images.
+2. The `FileUploadPanel` opens, showing a file picker.
+3. When an image is selected, `uploadFile` is called with the file and progress callbacks.
+4. `uploadFile` calls `progressUpdate(bytesUploaded)` to report progress.
+5. When upload is complete, `uploadFile` calls `onUploaded(url, thumbnail)` with the full-size URL and thumbnail URL.
+6. The image is added to the `images` array and displayed in the grid.
+
+### Delete flow
+
+1. User clicks the delete icon on an image.
+2. If `removeFileConfirm` is provided, the callback is called with the image.
+3. If the callback returns `true`, the image is removed from the `images` array.
+4. The `onchange` event fires with the updated images array.
+
+### Preview flow
+
+1. User clicks on an image in the grid.
+2. The `ImagePreview` component opens, showing the full-size image.
+3. User can close the preview by clicking the close button or clicking outside.
+
+### Read-only / disabled rendering
+
+Both modes hide the upload icon and delete icons. Images are displayed but cannot be modified.
+
+## Accessibility
+
+- The upload icon has `aria-hidden="true"` (decorative).
+- Image names are displayed as alt text.
+- For full ARIA, wrap with `<label>` or use `aria-label`.
+
+## Related Components
+
+- [AttachmentFilesField](../attachment-files/README.md) — general file upload component.
+- [TextEditor](../text_editor/README.md) — multi-line text area.
+- [NumberEditor](../number_editor/README.md) — numeric input.