@ticatec/uniface-element 5.0.5 → 5.1.0

package/dist/form/attachment_files/README.md

@@ -1,492 +1,111 @@
-# AttachmentFilesField
+# AttachmentEditor
 
-A file upload component for attaching documents, spreadsheets, presentations, PDFs, and other file types. Users can drag-and-drop files or click to browse. Each file is displayed as a row with an icon, filename, and action buttons (download, delete). Supports multiple files, file type detection, and optional confirmation before deletion.
+A form field for uploading and managing attachments (documents, spreadsheets, PDFs, media, anything). The whole field is a drop zone; the upload entry is a placeholder that sits at the end of the content (a dashed row in `list` layout, a "+" tile in `icon` layout) and expands to fill the field while it is empty. Uploads run inline with a progress indicator and a cancel button; failed uploads can be retried or discarded.
 
-> Think of it as a file manager for your form. Upload, preview, and manage attachments with a consistent UI.
+> Rewritten in 5.1.0. Names follow the [API Naming Guide](../../../docs/NAMING.md); the old `onUpload` prop and the modal `FileUploadPanel` are gone (no compatibility aliases).
 
 ## Features
 
-- **File upload** — supports drag-and-drop and click-to-browse.
-- **File type detection** — automatically detects file types (image, PDF, DOC, XLS, PPT, audio, video, other).
-- **File list display** — shows uploaded files with icons, filenames, and action buttons.
-- **Delete with confirmation** — optional `removeFileConfirm` callback for deletion confirmation.
-- **Multiple files** — supports uploading multiple files at once.
-- **Download** — click the download icon to download a file.
-- **Upload progress** — shows upload progress with a progress bar.
-- **Disabled / readonly** modes.
-- **Compact mode** for dense UIs.
+- **Drag & drop** anywhere inside the field, or click the placeholder to open the file dialog.
+- **Two layouts** — `list` (one row per file, download + delete at the end of the row) and `icon` (tiles that wrap automatically).
+- **Fixed height** via `height`; the content scrolls inside.
+- **Inline upload progress** — list rows show a bar, percentage and a cancel button; tiles overlay a progress ring with the cancel button in the middle.
+- **Retry / discard** failed uploads.
+- **Limits** — `accept`, `maxSize`, `maxFiles`, `multiple`; rejected files are reported through `onFileRejected`.
+- **Veto hook** `beforeRemove` and notifications `onremove`, `onchange`, `onFileUploaded`, `onUploadError`.
+- **Readonly / disabled** — download stays available, delete and the upload entry disappear, drops are ignored.
+- Inherits the shared field props (`variant`, `compact`, `theme`, `tooltip`, `error`, `style`, `onfocus`, `onblur`).
 
-## Installation
-
-```bash
-npm install @ticatec/uniface-element
-```
-
-## 引入
+## Import
 
 ```typescript
-import AttachmentFilesField from "@ticatec/uniface-element/AttachmentFilesField";
-import type { AttachmentFile, RemoveConfirm, FileUpload } from "@ticatec/uniface-element/AttachmentFilesField";
+import AttachmentEditor from "@ticatec/uniface-element/AttachmentEditor";
+import type {AttachmentFile, AttachmentLayout, FileUpload, RejectReason} from "@ticatec/uniface-element/AttachmentEditor";
 ```
 
-## Basic Usage
+## Basic usage
 
 ```svelte
 <script lang="ts">
-  import AttachmentFilesField from "@ticatec/uniface-element/AttachmentFilesField";
-  import type { AttachmentFile, FileUpload } from "@ticatec/uniface-element/AttachmentFilesField";
+  import AttachmentEditor from "@ticatec/uniface-element/AttachmentEditor";
+  import type {AttachmentFile, FileUpload} from "@ticatec/uniface-element/AttachmentEditor";
 
   let files = $state<AttachmentFile[]>([]);
 
-  // Simulated upload function
-  const uploadFile: 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}`;
-        onUploaded(fakeUrl);
-      }
-    }, 100);
-
-    return {
-      cancel: async () => {
-        clearInterval(interval);
-        return true;
-      }
-    };
+  const uploadFile: FileUpload = (file, progressUpdate, onUploaded, onError) => {
+    const xhr = new XMLHttpRequest();
+    xhr.upload.onprogress = (e) => progressUpdate(e.loaded);
+    xhr.onload = () => xhr.status < 300 ? onUploaded(JSON.parse(xhr.responseText).url) : onError(new Error(xhr.statusText));
+    xhr.onerror = () => onError(new Error('Network error'));
+    const body = new FormData();
+    body.append('file', file);
+    xhr.open('POST', '/api/upload');
+    xhr.send(body);
+    return {cancel: async () => { xhr.abort(); return true; }};
   };
-
-  function handleFilesChange(updatedFiles: AttachmentFile[]) {
-    console.log("Files updated:", updatedFiles);
-    // ... save to backend
-  }
 </script>
 
-<AttachmentFilesField
-  bind:files={files}
-  uploadFile={uploadFile}
-  onchange={handleFilesChange}
-  maxFiles={5}
-/>
+<AttachmentEditor bind:files {uploadFile} layout="icon" height={160} maxFiles={5}
+                  onchange={(list) => console.log('files', list)}/>
 ```
 
 ## Props
 
-`AttachmentFilesField` extends `CommonFieldProps`, so it inherits `variant`, `compact`, `disabled`, `readonly`, `style`, `error`, `tooltip`, `theme`, `placeholder`.
+Props inherited from `CommonFieldProps` (`variant`, `compact`, `disabled`, `readonly`, `theme`, `tooltip`, `error`, `style`, `onfocus`, `onblur`) are not repeated.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `files` | `Array<AttachmentFile>` (bindable) | `[]` | Array of uploaded files. Each file has `name`, `uri`, and `type` properties. |
-| `uploadFile` | `FileUpload` | — | **Required.** Function that handles file upload. Receives `(file, progressUpdate, onUploaded, errorHandler)` and returns an `UploadProgress` object with a `cancel()` method. |
-| `maxFiles` | `number` | `10` | Maximum number of files allowed. |
-| `removeFileConfirm` | `RemoveConfirm` | — | Optional callback for deletion confirmation. Receives the file 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 files 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` | `(files: Array<AttachmentFile>) => void` | — | Fires when the files array changes (upload or delete). Receives the updated files array. |
-| `onfocus` | `(event: FocusEvent) => void` | — | Editor focus. |
-| `onblur` | `(event: FocusEvent) => void` | — | Editor blur. |
-
-## Events
-
-| Event | Signature | Description |
-|-------|-----------|-------------|
-| `onchange` | `(files: Array<AttachmentFile>) => void` | Fires when the files array changes (upload or delete). Receives the updated files array. |
-| `onfocus` | `(event: FocusEvent) => void` | Editor focus. |
-| `onblur` | `(event: FocusEvent) => void` | Editor blur. |
+| `files` | `AttachmentFile[]` (bindable) | `[]` | Uploaded files. Each has `name`, `type`, `uri` and optional `size` / `thumbnail`. |
+| `layout` | `'list' \| 'icon'` | `'list'` | `list`: one row per file; `icon`: tiles that wrap. |
+| `height` | `number \| string` | — | Height of the content area (number = px). Content scrolls inside; omit for auto height. |
+| `uploadFile` | `FileUpload` | — | Upload function (see below). Without it the field only displays files and shows no upload entry. |
+| `accept` | `string` | `"*/*"` | Allowed types, same syntax as `<input accept>`. |
+| `maxSize` | `number` | `10 MB` | Per-file size limit in bytes. |
+| `maxFiles` | `number` | `10` | Maximum number of files, uploads in progress included. The upload entry disappears when reached. |
+| `multiple` | `boolean` | `true` | Allow picking / dropping several files at once. |
+| `uploadText` | `string` | i18n `upload.dropHint` | Text of the upload entry; also the empty-state hint. |
+| `emptyText` | `string` | i18n `upload.emptyText` | Shown when there are no files and uploading is not possible. |
+| `showThumbnail` | `boolean` | `false` | Show image files as thumbnails (`thumbnail ?? uri`) and a local preview while an image is uploading. A file that carries `thumbnail` is always shown as one. |
+| `onPreview` | `(file: AttachmentFile) => void` | — | When set, every file gets a preview button. |
+| `beforeRemove` | `BeforeRemove<AttachmentFile>` | — | Veto hook; return `false` (or a promise of it) to keep the file. |
+| `onremove` | `(file: AttachmentFile) => void` | — | A file was removed. |
+| `ondownload` | `(file: AttachmentFile) => void` | — | Custom download. Without it the download icon is a plain link to `file.uri`. |
+| `onFileUploaded` | `(file: AttachmentFile, source: File) => void` | — | One upload finished and was appended to `files`. |
+| `onFileRejected` | `(file: File, reason: 'accept' \| 'size' \| 'count') => void` | — | A picked / dropped file was refused. |
+| `onUploadError` | `(file: File, error: Error) => void` | — | An upload failed; the task stays in the list with retry / remove. |
+| `onchange` | `(files: AttachmentFile[]) => void` | — | `files` changed (upload completed or file removed). |
 
 ## Methods
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `focus()` | `() => void` | Moves focus to the editor. |
-
-```svelte
-<script lang="ts">
-  import AttachmentFilesField from "@ticatec/uniface-element/AttachmentFilesField";
-
-  let editorRef;
-
-  function focusEditor() {
-    editorRef.focus();
-  }
-</script>
-
-<AttachmentFilesField bind:this={editorRef} bind:files={files} uploadFile={uploadFile} />
-<button onclick={focusEditor}>Focus</button>
-```
-
-## `FileUpload` — upload function
+| Method | Description |
+|--------|-------------|
+| `openFileDialog()` | Opens the system file dialog (same as clicking the upload entry). No-op when uploading is not possible. |
+| `focus()` | Moves focus to the first control inside the field. |
 
-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) => void` | Call this when upload is complete. Pass the file URL. |
-| `errorHandler` | `(error: Error) => void` | Call this if upload fails. Pass an Error object. |
-
-It must return an `UploadProgress` object:
+## `FileUpload`
 
 ```typescript
-interface UploadProgress {
-  cancel: () => Promise<boolean>;
-}
+type FileUpload = (
+  file: File,
+  progressUpdate: (uploadedBytes: number) => void,
+  onUploaded: (url: string, thumbnail?: string) => void,
+  onError: (error: Error) => void
+) => {cancel: () => Promise<boolean>};
 ```
 
-The `cancel()` method allows the user to cancel an in-progress upload.
-
-```svelte
-<script lang="ts">
-  import AttachmentFilesField from "@ticatec/uniface-element/AttachmentFilesField";
-  import type { FileUpload } from "@ticatec/uniface-element/AttachmentFilesField";
-
-  let files = $state([]);
-
-  const uploadFile: 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}`);
-      } else {
-        progressUpdate(bytesUploaded);
-      }
-    }, 100);
-
-    return {
-      cancel: async () => {
-        clearInterval(interval);
-        return true; // upload was cancelled
-      }
-    };
-  };
-</script>
-
-<AttachmentFilesField bind:files={files} uploadFile={uploadFile} />
-```
-
-## `AttachmentFile` — file object
-
-Each file in the `files` array is an `AttachmentFile` object:
-
-```typescript
-interface AttachmentFile {
-  name: string;    // File name
-  uri: string;     // File URL (after upload)
-  type: FileType;  // File type (IMAGE, PDF, DOC, XLS, PPT, AUDIO, VIDEO, OTHER)
-}
-```
-
-## `FileType` — file type enum
-
-```typescript
-enum FileType {
-  IMAGE = 'img',
-  PDF = 'pdf',
-  DOC = 'doc',
-  XLS = 'xml',
-  PPT = 'ppt',
-  AUDIO = 'wav',
-  VIDEO = 'mov',
-  OTHER = 'dat'
-}
-```
-
-## Examples
-
-### File upload with confirmation
-
-```svelte
-<script lang="ts">
-  import AttachmentFilesField from "@ticatec/uniface-element/AttachmentFilesField";
-  import type { AttachmentFile, FileUpload, RemoveConfirm } from "@ticatec/uniface-element/AttachmentFilesField";
-
-  let files = $state<AttachmentFile[]>([]);
-
-  const uploadFile: 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}`);
-      } else {
-        progressUpdate(bytesUploaded);
-      }
-    }, 100);
-
-    return {
-      cancel: async () => {
-        clearInterval(interval);
-        return true;
-      }
-    };
-  };
-
-  const removeFileConfirm: RemoveConfirm = async (file) => {
-    return confirm(`Are you sure you want to delete ${file.name}?`);
-  };
-
-  function handleFilesChange(updatedFiles: AttachmentFile[]) {
-    console.log("Files updated:", updatedFiles);
-    // ... save to backend
-  }
-</script>
-
-<AttachmentFilesField
-  bind:files={files}
-  uploadFile={uploadFile}
-  removeFileConfirm={removeFileConfirm}
-  onchange={handleFilesChange}
-  maxFiles={5}
-/>
-```
-
-### Multiple file types
-
-```svelte
-<script lang="ts">
-  import AttachmentFilesField from "@ticatec/uniface-element/AttachmentFilesField";
-  import type { AttachmentFile, FileUpload } from "@ticatec/uniface-element/AttachmentFilesField";
-
-  let files = $state<AttachmentFile[]>([]);
-
-  const uploadFile: FileUpload = (file, progressUpdate, onUploaded, errorHandler) => {
-    // Simulate upload
-    let progress = 0;
-    const interval = setInterval(() => {
-      progress += 10;
-      progressUpdate(Math.floor(file.size * (progress / 100)));
-
-      if (progress >= 100) {
-        clearInterval(interval);
-        onUploaded(`/uploads/${file.name}`);
-      }
-    }, 100);
-
-    return {
-      cancel: async () => {
-        clearInterval(interval);
-        return true;
-      }
-    };
-  };
-</script>
-
-<div class="file-upload-section">
-  <h3>Upload Files</h3>
-  <AttachmentFilesField
-    bind:files={files}
-    uploadFile={uploadFile}
-    maxFiles={10}
-  />
-  <div class="file-list">
-    {#each files as file}
-      <div class="file-item">
-        <span class="file-icon">📄</span>
-        <span class="file-name">{file.name}</span>
-        <span class="file-type">{file.type}</span>
-      </div>
-    {/each}
-  </div>
-</div>
-
-<style>
-  .file-upload-section {
-    max-width: 600px;
-    margin: 20px;
-    padding: 20px;
-    border: 1px solid #e5e7eb;
-    border-radius: 8px;
-  }
-  .file-list {
-    margin-top: 16px;
-  }
-  .file-item {
-    display: flex;
-    align-items: center;
-    gap: 8px;
-    padding: 8px;
-    border-bottom: 1px solid #f3f4f6;
-  }
-  .file-icon {
-    font-size: 20px;
-  }
-  .file-name {
-    flex: 1;
-  }
-  .file-type {
-    color: #6b7280;
-  }
-</style>
-```
-
-### Disabled and readonly modes
-
-```svelte
-<script lang="ts">
-  import AttachmentFilesField from "@ticatec/uniface-element/AttachmentFilesField";
-  import type { AttachmentFile, FileUpload } from "@ticatec/uniface-element/AttachmentFilesField";
-
-  let disabledFiles: AttachmentFile[] = [
-    { name: "disabled-file.pdf", uri: "/uploads/disabled-file.pdf", type: "pdf" }
-  ];
-  let readonlyFiles: AttachmentFile[] = [
-    { name: "readonly-file.docx", uri: "/uploads/readonly-file.docx", type: "doc" }
-  ];
-  let normalFiles: AttachmentFile[] = [];
-
-  const uploadFile: 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}`);
-      }
-    }, 100);
-
-    return {
-      cancel: async () => {
-        clearInterval(interval);
-        return true;
-      }
-    };
-  };
-</script>
-
-<div style="display: flex; flex-direction: column; gap: 16px;">
-  <AttachmentFilesField
-    bind:files={disabledFiles}
-    uploadFile={uploadFile}
-    disabled
-  />
-  <AttachmentFilesField
-    bind:files={readonlyFiles}
-    uploadFile={uploadFile}
-    readonly
-  />
-  <AttachmentFilesField
-    bind:files={normalFiles}
-    uploadFile={uploadFile}
-  />
-</div>
-```
-
-### Compact mode
-
-```svelte
-<script lang="ts">
-  import AttachmentFilesField from "@ticatec/uniface-element/AttachmentFilesField";
-  import type { AttachmentFile, FileUpload } from "@ticatec/uniface-element/AttachmentFilesField";
-
-  let files = $state<AttachmentFile[]>([]);
-
-  const uploadFile: 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}`);
-      }
-    }, 100);
-
-    return {
-      cancel: async () => {
-        clearInterval(interval);
-        return true;
-      }
-    };
-  };
-</script>
-
-<table>
-  <thead>
-    <tr>
-      <th>Name</th>
-      <th>Files</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Row 1</td>
-      <td>
-        <AttachmentFilesField
-          bind:files={files}
-          uploadFile={uploadFile}
-          compact
-        />
-      </td>
-    </tr>
-  </tbody>
-</table>
-```
-
-## Behavior Notes
-
-### Upload flow
-
-1. User clicks the upload icon or drags and drops files.
-2. The `FileUploadPanel` opens, showing a file picker.
-3. When a file 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)` with the file URL.
-6. The file is added to the `files` array and displayed in the file list.
-
-### Delete flow
-
-1. User clicks the delete icon on a file.
-2. If `removeFileConfirm` is provided, the callback is called with the file.
-3. If the callback returns `true`, the file is removed from the `files` array.
-4. The `onchange` event fires with the updated files array.
-
-### File type detection
-
-File types are detected based on file extensions:
-
-- **IMAGE**: jpg, jpeg, png, gif, bmp, tiff, webp, svg, ico, heif, heic
-- **PDF**: pdf
-- **DOC**: doc, docx, dot, dotx, docm, dotm
-- **XLS**: xls, xlsx, xlsm, xlsb, csv, ods, xlt, xltx, xltm
-- **PPT**: ppt, pptx, pptm, pps, ppsx, ppsm, pot, potx, potm
-- **AUDIO**: mp3, wav, aac, flac, ogg, wma, m4a, aiff, alac
-- **VIDEO**: mp4, avi, mkv, mov, wmv, flv, webm, mpeg, mpg, 3gp, m4v, vob
-- **OTHER**: anything else
+Call `progressUpdate` with the number of bytes sent so far (the component converts it to a percentage), `onUploaded` with the stored URL when done, or `onError` on failure. `cancel()` resolving `false` keeps the task in the list.
 
-### Read-only / disabled rendering
+## Behavior notes
 
-Both modes hide the upload icon and delete icons. Files are displayed but cannot be modified.
+- Files that fail `accept` / `maxSize` / the remaining `maxFiles` quota never start uploading; each is reported once through `onFileRejected`.
+- An upload that succeeds appends `{name, type, uri, size, thumbnail}` to `files` (type derived from the extension, `thumbnail` from the uploader's second `onUploaded` argument), then fires `onFileUploaded` and `onchange`.
+- `readonly` and `disabled` both hide delete and the upload entry and ignore drops; download links remain in `readonly`.
+- The drag highlight only reacts to drags that carry files.
 
-## Accessibility
+## Styling
 
-- The upload icon has `aria-hidden="true"` (decorative).
-- File names are displayed as plain text.
-- For full ARIA, wrap with `<label>` or use `aria-label`.
+Component-level CSS variables (all have fallbacks): `--uniface-attachment-item-height`, `--uniface-attachment-tile-size`, `--uniface-attachment-icon-color`, `--uniface-attachment-add-border-color`, `--uniface-attachment-add-color`, `--uniface-attachment-drag-bg`, `--uniface-attachment-error-color`, `--uniface-attachment-overlay-bg`. `compact` switches to 26 px rows / 64 px tiles.
 
-## Related Components
+## Related components
 
-- [ImageFilesField](../image-files/README.md) — specialized image upload component.
-- [TextEditor](../text_editor/README.md) — multi-line text area.
-- [NumberEditor](../number_editor/README.md) — numeric input.
+- [ImageEditor](../image_editor/README.md) — same implementation for images: thumbnail tiles and a built-in preview.