nicklabs-ui 1.0.81 → 1.0.83

package/README.md

@@ -2,7 +2,7 @@
 
 A Vue 3 component library with glassmorphism design, built for modern web applications.
 
-**Version**: 1.0.79 | **Framework**: Vue 3.5+
+**Version**: 1.0.81 | **Framework**: Vue 3.5+
 
 ---
 
@@ -544,7 +544,7 @@ function handleFiles(files: File[]) {
 
 #### NImageSelect
 
-A card-grid image uploader with drag-and-drop, multi-file support, automatic resolution probing, a built-in dark preview lightbox, and a confirm dialog before removal. Files are tracked as `NImageSelectItem[]` via `v-model`.
+A card-grid image uploader with drag-and-drop, multi-file support, automatic resolution probing, a built-in dark preview lightbox, and a confirm dialog before removal. Files are tracked as `NImageSelectItem[]` via `v-model`. Supports backfilling existing data by URL and a read-only view mode (see notes below).
 
 > Removal uses `useAlert` internally, so mount `<NAlert />` once at the app root (see [NAlert](#nalert)).
 
@@ -556,7 +556,8 @@ A card-grid image uploader with drag-and-drop, multi-file support, automatic res
 | `accept` | `string` | `"image/*"` | Accepted types — used for both the file dialog and drop validation. Supports `image/*`, exact MIME (`image/png`), extensions (`.png`), and comma-separated combinations |
 | `multiple` | `boolean` | `false` | Allow multiple images; when `false`, extra files are rejected with a `count` error |
 | `maxSize` | `number` | `0` | Per-file size limit in **MB** (`0` = unlimited) |
-| `disabled` | `boolean` | `false` | Disable adding and removing |
+| `disabled` | `boolean` | `false` | Disable adding and removing (also dims the component) |
+| `readonly` | `boolean` | `false` | View-only mode: browse and preview only. Hides the add/delete affordances and disables drag/drop, but keeps a normal (non-dimmed) appearance |
 | `title` | `string` | `""` | Label above the grid |
 | `showCount` | `boolean` | `false` | Show a count chip next to the title |
 | `emptyTitle` | `string` | `"將圖片拖放到這裡"` | Empty-state heading |
@@ -612,13 +613,24 @@ async function upload() {
 </script>
 ```
 
-> `width` / `height` are probed asynchronously after a file is added and written back into the item. The component creates object URLs for previews and revokes them on removal automatically, and on unmount too unless `autoRevoke` is `false` — in which case the parent owns the URLs and must revoke them.
+> `width` / `height` are probed asynchronously after a file is added and written back into the item. The component creates object URLs for previews and revokes them on removal automatically, and on unmount too unless `autoRevoke` is `false` — in which case the parent owns the URLs and must revoke them. Only `blob:` URLs the component created are revoked; remote URLs are never touched.
+
+**Backfilling existing data (edit mode)**
+
+After upload, the server usually returns only a URL. To show that data, push items with just `id` and `url` (leave `file` empty) — the component probes `width`/`height` and derives the display name from the URL:
+
+```ts
+const images = ref<NImageSelectItem[]>([
+  { id: 'remote-1', url: 'https://cdn.example.com/images/cover.jpg' },
+])
+// <NImageSelect v-model="images" readonly title="Image content" />
+```
 
 ---
 
 #### NVideoSelect
 
-A card-grid video uploader. Same interaction model as [NImageSelect](#nimageselect) — drag-and-drop, multi-file, confirm-before-remove, and a built-in preview modal — but items also carry `duration`, `width`, and `height`.
+A card-grid video uploader. Same interaction model as [NImageSelect](#nimageselect) — drag-and-drop, multi-file, confirm-before-remove, and a built-in preview modal — but items also carry `duration`, `width`, and `height`. Supports backfilling existing data by URL and a read-only view mode (same as [NImageSelect](#nimageselect)).
 
 > Removal uses `useAlert` internally, so mount `<NAlert />` once at the app root (see [NAlert](#nalert)).
 
@@ -630,7 +642,8 @@ A card-grid video uploader. Same interaction model as [NImageSelect](#nimagesele
 | `accept` | `string` | `"video/*"` | Accepted types — supports `video/*`, exact MIME (`video/mp4`), extensions (`.mp4`), and comma-separated combinations |
 | `multiple` | `boolean` | `false` | Allow multiple videos |
 | `maxSize` | `number` | `0` | Per-file size limit in **MB** (`0` = unlimited) |
-| `disabled` | `boolean` | `false` | Disable adding and removing |
+| `disabled` | `boolean` | `false` | Disable adding and removing (also dims the component) |
+| `readonly` | `boolean` | `false` | View-only mode: browse and preview only. Hides the add/delete affordances and disables drag/drop, but keeps a normal (non-dimmed) appearance |
 | `title` | `string` | `""` | Label above the grid |
 | `showCount` | `boolean` | `false` | Show a count chip next to the title |
 | `emptyTitle` | `string` | `"將影片拖放到這裡"` | Empty-state heading |
@@ -667,11 +680,13 @@ function onError(err: NVideoSelectError) {
 </script>
 ```
 
+> **Backfilling existing data:** push items with just `id` and `url` (leave `file` empty); `duration` / `width` / `height` are probed and the name is derived from the URL. Only component-created `blob:` URLs are revoked on remove/unmount — remote URLs are never touched.
+
 ---
 
 #### NAudioSelect
 
-An audio uploader that decodes each file with the Web Audio API to render a waveform, showing a skeleton row while decoding. Same drag-and-drop / multi-file / confirm-before-remove model as the other media selectors; items carry `duration`.
+An audio uploader that decodes each file with the Web Audio API to render a waveform, showing a skeleton row while decoding. Each row has an inline player (play/pause + click-and-drag seek on the waveform); only one track plays at a time. Same drag-and-drop / multi-file / confirm-before-remove model as the other media selectors; items carry `duration`. Supports backfilling existing data by URL and a read-only view mode.
 
 > Removal uses `useAlert` internally, so mount `<NAlert />` once at the app root (see [NAlert](#nalert)).
 
@@ -683,7 +698,8 @@ An audio uploader that decodes each file with the Web Audio API to render a wave
 | `accept` | `string` | `".mp3,.wav,.ogg,.m4a,.aac,.flac,audio/mpeg,audio/wav,audio/ogg,audio/aac,audio/flac"` | Accepted types. Defaults to an explicit extension + MIME list (rather than `audio/*`) so the dialog doesn't offer `.mp4`-style containers |
 | `multiple` | `boolean` | `false` | Allow multiple files |
 | `maxSize` | `number` | `0` | Per-file size limit in **MB** (`0` = unlimited) |
-| `disabled` | `boolean` | `false` | Disable adding and removing |
+| `disabled` | `boolean` | `false` | Disable adding and removing (also dims the component) |
+| `readonly` | `boolean` | `false` | View-only mode: browse and play only. Hides the add/delete affordances and disables drag/drop, but keeps a normal (non-dimmed) appearance. **Playback and seek stay enabled** |
 | `title` | `string` | `""` | Label above the list |
 | `showCount` | `boolean` | `false` | Show a count chip next to the title |
 | `emptyTitle` | `string` | `"將音訊拖放到這裡"` | Empty-state heading |
@@ -720,6 +736,21 @@ function onError(err: NAudioSelectError) {
 </script>
 ```
 
+**Backfilling existing data (edit mode)**
+
+Push items with just `id` and `url` (leave `file` empty); the display name is derived from the URL:
+
+```ts
+const tracks = ref<NAudioSelectItem[]>([
+  { id: 'remote-1', url: 'https://cdn.example.com/audios/track.mp3' },
+])
+// <NAudioSelect v-model="tracks" readonly title="Audio content" />
+```
+
+> **Waveform vs. duration for remote URLs.** The waveform needs the raw bytes (`fetch` + decode), which is subject to **CORS** — if the host doesn't allow it, the row falls back to a plain progress bar (track + played fill) instead of a waveform. Either way, **click/drag seek and the progress visual stay functional** — seeking only depends on the audio element's `duration`, not the waveform. Duration itself always resolves: it falls back to the `<audio>` element's metadata (no CORS needed), and playback works regardless.
+
+> **Waveform cache (survives `v-if` remount).** Decoded waveforms are kept in a module-level cache keyed by `url`, so toggling the component with `v-if` (unmount → remount) restores the waveform instantly with no re-decode and no flash. A `v-if` unmount does **not** clear the cache; only an explicit remove (the delete button) evicts the entry. Note this is independent of `autoRevoke`: the cache preserves the *waveform*, but `autoRevoke: true` still revokes the *blob* on unmount, which breaks **playback** of locally-added files after remount — set `autoRevoke: false` (and take over `URL.revokeObjectURL` in the parent) if you need playback to survive a remount.
+
 ---
 
 #### NSwitch
@@ -2179,35 +2210,38 @@ type RadiusSize = 'none' | 'sm' | 'md' | 'lg' | 'xl'
 // Media selectors (NImageSelect / NVideoSelect / NAudioSelect)
 type MediaSelectErrorType = 'size' | 'type' | 'count'
 
+// Only `id` and `url` are required. The rest are optional so you can backfill
+// existing data from the server with just a URL — the component probes the
+// missing metadata (and, for audio, the waveform) itself.
 interface NImageSelectItem {
   id: string
-  file: File | null   // native File for upload; null for seed/preset items
-  name: string
-  size: number        // bytes
-  width: number | null
-  height: number | null
-  url: string         // object URL for preview
+  file?: File | null    // native File for upload; null/absent for remote-URL items
+  name?: string         // derived from the URL when absent
+  size?: number | null  // bytes; null when unknown (remote)
+  width?: number | null
+  height?: number | null
+  url: string           // object URL or a remote URL — for thumbnail & preview
 }
 interface NImageSelectError { type: MediaSelectErrorType; file: File }
 
 interface NVideoSelectItem {
   id: string
-  file: File | null
-  name: string
-  size: number        // bytes
-  duration: number | null  // seconds
-  width: number | null
-  height: number | null
+  file?: File | null
+  name?: string
+  size?: number | null
+  duration?: number | null  // seconds
+  width?: number | null
+  height?: number | null
   url: string
 }
 interface NVideoSelectError { type: MediaSelectErrorType; file: File }
 
 interface NAudioSelectItem {
   id: string
-  file: File | null
-  name: string
-  size: number        // bytes
-  duration: number | null  // seconds
+  file?: File | null
+  name?: string
+  size?: number | null
+  duration?: number | null  // seconds
   url: string
 }
 interface NAudioSelectError { type: MediaSelectErrorType; file: File }