nicklabs-ui 1.0.71 → 1.0.74

package/README.md

@@ -2,7 +2,7 @@
 
 A Vue 3 component library with glassmorphism design, built for modern web applications.
 
-**Version**: 1.0.51 | **Framework**: Vue 3.5+
+**Version**: 1.0.73 | **Framework**: Vue 3.5+
 
 ---
 
@@ -18,6 +18,9 @@ A Vue 3 component library with glassmorphism design, built for modern web applic
     - [NCheckbox](#ncheckbox)
     - [NSelect](#nselect)
     - [NFileSelect](#nfileselect)
+    - [NImageSelect](#nimageselect)
+    - [NVideoSelect](#nvideoselect)
+    - [NAudioSelect](#naudioselect)
     - [NSwitch](#nswitch)
     - [NDatePicker](#ndatepicker)
   - [Data Display](#data-display)
@@ -539,6 +542,183 @@ 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`.
+
+> Removal uses `useAlert` internally, so mount `<NAlert />` once at the app root (see [NAlert](#nalert)).
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `NImageSelectItem[]` | `[]` | Bound image list (v-model) |
+| `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 |
+| `title` | `string` | `""` | Label above the grid |
+| `showCount` | `boolean` | `false` | Show a count chip next to the title |
+| `emptyTitle` | `string` | `"將圖片拖放到這裡"` | Empty-state heading |
+| `emptyHint` | `string` | `"或點擊以選擇檔案 · 支援 JPG / PNG / WebP / GIF，可一次多張"` | Empty-state sub-text |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `NImageSelectItem[]` | The full list changed (v-model) |
+| `change` | `NImageSelectItem[]` | The full list changed |
+| `add` | `NImageSelectItem[]` | Items just added (this batch only) |
+| `remove` | `NImageSelectItem` | An item was removed (after confirm) |
+| `error` | `NImageSelectError` | A file was rejected (`type` / `size` / `count`) |
+
+**Usage**
+
+```vue
+<template>
+  <NImageSelect
+    v-model="images"
+    title="Product Photos"
+    multiple
+    :max-size="5"
+    show-count
+    @add="onAdd"
+    @error="onError"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { NImageSelect } from 'nicklabs-ui'
+import type { NImageSelectItem, NImageSelectError } from 'nicklabs-ui'
+
+const images = ref<NImageSelectItem[]>([])
+
+function onAdd(items: NImageSelectItem[]) {
+  console.log('Added', items.length, 'images')
+}
+
+function onError(err: NImageSelectError) {
+  console.warn('Rejected:', err.file.name, err.type)
+}
+
+// Each item carries the native File for upload:
+async function upload() {
+  const form = new FormData()
+  images.value.forEach((img) => img.file && form.append('files', img.file))
+  await api.upload(form)
+}
+</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 and unmount automatically.
+
+---
+
+#### 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`.
+
+> Removal uses `useAlert` internally, so mount `<NAlert />` once at the app root (see [NAlert](#nalert)).
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `NVideoSelectItem[]` | `[]` | Bound video list (v-model) |
+| `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 |
+| `title` | `string` | `""` | Label above the grid |
+| `showCount` | `boolean` | `false` | Show a count chip next to the title |
+| `emptyTitle` | `string` | `"將影片拖放到這裡"` | Empty-state heading |
+| `emptyHint` | `string` | `"或點擊以選擇檔案 · 支援 MP4 / MOV / WebM，可一次多支"` | Empty-state sub-text |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `NVideoSelectItem[]` | The full list changed (v-model) |
+| `change` | `NVideoSelectItem[]` | The full list changed |
+| `add` | `NVideoSelectItem[]` | Items just added (this batch only) |
+| `remove` | `NVideoSelectItem` | An item was removed (after confirm) |
+| `error` | `NVideoSelectError` | A file was rejected (`type` / `size` / `count`) |
+
+**Usage**
+
+```vue
+<template>
+  <NVideoSelect v-model="videos" title="Clips" multiple :max-size="200" @error="onError" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { NVideoSelect } from 'nicklabs-ui'
+import type { NVideoSelectItem, NVideoSelectError } from 'nicklabs-ui'
+
+const videos = ref<NVideoSelectItem[]>([])
+
+function onError(err: NVideoSelectError) {
+  console.warn('Rejected:', err.file.name, err.type)
+}
+</script>
+```
+
+---
+
+#### 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`.
+
+> Removal uses `useAlert` internally, so mount `<NAlert />` once at the app root (see [NAlert](#nalert)).
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `NAudioSelectItem[]` | `[]` | Bound audio list (v-model) |
+| `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 |
+| `title` | `string` | `""` | Label above the list |
+| `showCount` | `boolean` | `false` | Show a count chip next to the title |
+| `emptyTitle` | `string` | `"將音訊拖放到這裡"` | Empty-state heading |
+| `emptyHint` | `string` | `"或點擊以選擇檔案 · 支援 MP3 / WAV / OGG / M4A，可一次多首"` | Empty-state sub-text |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `NAudioSelectItem[]` | The full list changed (v-model) |
+| `change` | `NAudioSelectItem[]` | The full list changed |
+| `add` | `NAudioSelectItem[]` | Items just added (this batch only) |
+| `remove` | `NAudioSelectItem` | An item was removed (after confirm) |
+| `error` | `NAudioSelectError` | A file was rejected (`type` / `size` / `count`) |
+
+**Usage**
+
+```vue
+<template>
+  <NAudioSelect v-model="tracks" title="Soundtrack" multiple @error="onError" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { NAudioSelect } from 'nicklabs-ui'
+import type { NAudioSelectItem, NAudioSelectError } from 'nicklabs-ui'
+
+const tracks = ref<NAudioSelectItem[]>([])
+
+function onError(err: NAudioSelectError) {
+  console.warn('Rejected:', err.file.name, err.type)
+}
+</script>
+```
+
+---
+
 #### NSwitch
 
 Animated toggle switch.
@@ -1992,8 +2172,46 @@ type NTagIntent = 'none' | 'primary' | 'success' | 'warning' | 'error' | 'info'
 type NTagVariant = 'solid' | 'light' | 'outline'
 type PaddingSize = 'none' | 'sm' | 'md' | 'lg'
 type RadiusSize = 'none' | 'sm' | 'md' | 'lg' | 'xl'
+
+// Media selectors (NImageSelect / NVideoSelect / NAudioSelect)
+type MediaSelectErrorType = 'size' | 'type' | 'count'
+
+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
+}
+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
+  url: string
+}
+interface NVideoSelectError { type: MediaSelectErrorType; file: File }
+
+interface NAudioSelectItem {
+  id: string
+  file: File | null
+  name: string
+  size: number        // bytes
+  duration: number | null  // seconds
+  url: string
+}
+interface NAudioSelectError { type: MediaSelectErrorType; file: File }
 ```
 
+> `NImageSelectErrorType`, `NVideoSelectErrorType`, and `NAudioSelectErrorType` are each exported individually (all aliased to `'size' | 'type' | 'count'`).
+
 ---
 
 ## CSS Variables