@ramathibodi/nuxt-commons 0.1.73 → 0.1.75

package/dist/runtime/components/form/File.vue

@@ -1,284 +1,296 @@
-<script lang="ts" setup>
-import { castArray } from 'lodash-es'
-import { ref, shallowRef, watch, computed } from 'vue'
-import { VTextField } from 'vuetify/components/VTextField'
-import { useAlert } from '../../composables/alert'
-import { type Base64File } from '../../composables/assetFile'
-import { useAssetFile } from '../../composables/assetFile'
-
-const alert = useAlert()
-const { hydrateAssetFile, base64ToFile, fileToBase64, downloadBase64File } = useAssetFile()
-
-const fileToBase64WithMaxSize = (file: File) => fileToBase64(file, props.maxSize)
-
-interface Props extends /* @vue-ignore */ InstanceType<typeof VTextField['$props']> {
-  accept?: string
-  multiple?: boolean
-  maxSize?: number
-  modelValue?: Base64File | Base64File[] | null
-  downloadable?: boolean
-  autoHydrate?: boolean
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  accept: '*',
-  multiple: false,
-  maxSize: 5,
-  downloadable: false,
-  autoHydrate: false,
-})
-
-const emit = defineEmits<{
-  (e: 'update:modelValue', value: Base64File | Base64File[] | null): void
-}>()
-
-/** UI ref */
-const fileInput = ref<HTMLInputElement | null>(null)
-
-/** Internal sources (always arrays) */
-const assets = ref<Base64File[]>([])       // items with server id (or ones we keep as “assets”)
-const files = shallowRef<File[]>([])       // native File objects picked by the user
-
-/** Cache to avoid re-reading the same File repeatedly */
-const fileCache = new WeakMap<File, Promise<Base64File>>()
-
-/** Re-entrancy guard to break the emit -> props watcher -> syncFromModel loop */
-let internalSync = false
-
-/** Build a stable dedupe key */
-function base64FileKey(x: Base64File): string {
-  if (x.id != null) return `id:${x.id}`
-  const name = x.fileName ?? ''
-  const len = x.base64String?.length ?? 0
-  return `n:${name}|l:${len}`
-}
-
-/** Dedupe by key (preserves order) */
-function uniqByKey(arr: Base64File[]): Base64File[] {
-  const seen = new Set<string>()
-  const out: Base64File[] = []
-  for (const it of arr) {
-    const k = base64FileKey(it)
-    if (!seen.has(k)) {
-      seen.add(k)
-      out.push(it)
-    }
-  }
-  return out
-}
-
-/** Shallow equal by key sequence */
-function arraysEqualByKey(a: Base64File[], b: Base64File[]): boolean {
-  if (a === b) return true
-  if (a.length !== b.length) return false
-  for (let i = 0; i < a.length; i++) {
-    if (base64FileKey(a[i]) !== base64FileKey(b[i])) return false
-  }
-  return true
-}
-
-/** Normalize incoming modelValue into arrays for internal use */
-async function syncFromModel() {
-  const mv = props.modelValue
-  if (!mv) {
-    assets.value = []
-    files.value = []
-    return
-  }
-
-  const asArray = castArray(mv) as Base64File[]
-
-  // Split into “asset with id” vs “inline base64” (no id)
-  const incomingAssets = asArray.filter(a => a.id != null)
-  const inlineBase64 = asArray.filter(a => a.id == null && a.base64String)
-
-  // Convert inline base64 to File for consistent UX
-  const inlineFiles: File[] = []
-  for (const item of inlineBase64) {
-    const f = base64ToFile(item.base64String as string, item.fileName)
-    if (f) inlineFiles.push(f)
-  }
-
-  assets.value = incomingAssets
-  files.value = inlineFiles
-
-  // Optionally hydrate assets that need it
-  if (props.autoHydrate) {
-    const needsHydration = assets.value.filter(a => a.id != null && !a.base64String)
-    if (needsHydration.length) {
-      await Promise.allSettled(needsHydration.map(hydrateAssetFile))
-    }
-  }
-}
-
-/** Open chooser */
-function openWindowUpload() {
-  if (props.multiple || (assets.value.length === 0 && files.value.length === 0)) {
-    fileInput.value?.click()
-  }
-}
-
-/** Add files from input (single or multiple) */
-function addFiles(payload: File | File[]) {
-  if (Array.isArray(payload)) files.value = [...files.value, ...payload]
-  else files.value = [...files.value, payload]
-}
-
-/** Remove chips */
-function removeFileByIndex(i: number | string) {
-  const idx = Number(i)
-  if (idx >= 0 && idx < files.value.length) {
-    const copy = files.value.slice()
-    copy.splice(idx, 1)
-    files.value = copy
-  }
-}
-function removeAssetByIndex(i: number | string) {
-  const idx = Number(i)
-  if (idx >= 0 && idx < assets.value.length) {
-    const copy = assets.value.slice()
-    copy.splice(idx, 1)
-    assets.value = copy
-  }
-}
-
-/** Convert current files → Base64File[] (cached) */
-async function filesToBase64Files(list: File[]): Promise<Base64File[]> {
-  const tasks = list.map(f => {
-    let p = fileCache.get(f)
-    if (!p) {
-      p = fileToBase64WithMaxSize(f)
-      fileCache.set(f, p)
-    }
-    return p
-  })
-  return Promise.all(tasks)
-}
-
-/** Combined result (array form) */
-const combinedArray = ref<Base64File[]>([])
-
-/** Dirty flag for <v-text-field> */
-const isDirty = computed(() =>
-    props.multiple ? combinedArray.value.length > 0 : combinedArray.value[0] != null
-)
-
-/** Sync from props.modelValue (guarded) */
-watch(
-    () => props.modelValue,
-    () => {
-      if (internalSync) return
-      void syncFromModel()
-    },
-    { deep: true, immediate: true }
-)
-
-/** Rebuild combined and emit (guarded, deduped, only-on-change) */
-watch([assets, files], async () => {
-  try {
-    const base64FromFiles = await filesToBase64Files(files.value)
-
-    const mergedArray = props.multiple
-        ? [...assets.value, ...base64FromFiles]
-        : (assets.value[0] ?? base64FromFiles[0] ?? null)
-            ? [assets.value[0] ?? base64FromFiles[0]]
-            : []
-
-    const nextCombined = props.multiple ? uniqByKey(mergedArray) : mergedArray
-
-    if (!arraysEqualByKey(combinedArray.value, nextCombined)) {
-      combinedArray.value = nextCombined
-
-      internalSync = true
-      try {
-        if (props.multiple) {
-          emit('update:modelValue', combinedArray.value)
-        } else {
-          emit('update:modelValue', combinedArray.value[0] ?? null)
-        }
-      } finally {
-        // let Vue flush the emit before re-enabling the external sync
-        queueMicrotask(() => { internalSync = false })
-      }
-    }
-  } catch (error: any) {
-    alert?.addAlert({ message: String(error), alertType: 'error' })
-    files.value = []
-    const fallback = props.multiple
-        ? [...assets.value]
-        : (assets.value[0] ? [assets.value[0]] : [])
-
-    if (!arraysEqualByKey(combinedArray.value, fallback)) {
-      combinedArray.value = fallback
-      internalSync = true
-      try {
-        if (props.multiple) emit('update:modelValue', combinedArray.value)
-        else emit('update:modelValue', combinedArray.value[0] ?? null)
-      } finally {
-        queueMicrotask(() => { internalSync = false })
-      }
-    }
-  }
-}, { deep: true, immediate: true })
-</script>
-
-<template>
-  <v-text-field
-      v-bind="$attrs"
-      label="Upload files"
-      readonly
-      :dirty="isDirty"
-      v-on="isDirty && !props.multiple ? {} : { click: openWindowUpload }"
-  >
-    <template #default>
-      <!-- Server/asset items -->
-      <v-chip
-          v-for="(asset, index) in assets"
-          :key="`${asset.id ?? asset.fileName}-${index}`"
-          color="green"
-          variant="flat"
-          closable
-          @click:close="removeAssetByIndex(index)"
-      >
-        {{ asset.originalFileName || asset.fileName }}
-        <template #append v-if="props.downloadable">
-          <slot name="download" :item="asset">
-            <v-icon
-                v-if="asset.base64String"
-                @click.stop="downloadBase64File(asset.base64String, asset.originalFileName || asset.fileName)"
-            >
-              mdi mdi-download
-            </v-icon>
-          </slot>
-        </template>
-      </v-chip>
-
-      <!-- Local uploaded files -->
-      <v-chip
-          v-for="(file, index) in files"
-          :key="`${file.name}-${file.size}-${index}`"
-          color="primary"
-          variant="flat"
-          closable
-          @click:close="removeFileByIndex(index)"
-      >
-        {{ file.name }}
-      </v-chip>
-    </template>
-
-    <!-- Add more button for multi mode -->
-    <template v-if="props.multiple && combinedArray.length > 0" #append-inner>
-      <VBtn variant="text" :icon="true" @click="openWindowUpload">
-        <v-icon>mdi mdi-plus</v-icon>
-      </VBtn>
-    </template>
-  </v-text-field>
-
-  <v-file-input
-      ref="fileInput"
-      :accept="props.accept"
-      :multiple="props.multiple"
-      style="display: none"
-      @update:model-value="addFiles"
-  />
+<script lang="ts" setup>
+/**
+ * FormFile is a schema-driven form field component that binds model data, renders field UI, and emits normalized updates.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
+import { castArray } from 'lodash-es'
+import { ref, shallowRef, watch, computed } from 'vue'
+import { VTextField } from 'vuetify/components/VTextField'
+import { useAlert } from '../../composables/alert'
+import { type Base64File } from '../../composables/assetFile'
+import { useAssetFile } from '../../composables/assetFile'
+
+const alert = useAlert()
+const { hydrateAssetFile, base64ToFile, fileToBase64, downloadBase64File } = useAssetFile()
+
+const fileToBase64WithMaxSize = (file: File) => fileToBase64(file, props.maxSize)
+
+interface Props extends /* @vue-ignore */ InstanceType<typeof VTextField['$props']> {
+  accept?: string // Accepted file MIME types or extensions for file selection.
+  multiple?: boolean // Allows selecting or uploading more than one file.
+  maxSize?: number // Maximum allowed output size (MB) before upload is blocked.
+  modelValue?: Base64File | Base64File[] | null // Bound value for v-model synchronization with the parent component.
+  downloadable?: boolean // Shows download actions for selected/loaded files.
+  autoHydrate?: boolean // Converts incoming serialized values into component runtime format on mount/watch.
+}
+
+/**
+ * Public props accepted by FormFile.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
+const props = withDefaults(defineProps<Props>(), {
+  accept: '*',
+  multiple: false,
+  maxSize: 5,
+  downloadable: false,
+  autoHydrate: false,
+})
+
+/**
+ * Custom events emitted by FormFile.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
+const emit = defineEmits<{
+  (e: 'update:modelValue', value: Base64File | Base64File[] | null): void
+}>()
+
+/** UI ref */
+const fileInput = ref<HTMLInputElement | null>(null)
+
+/** Internal sources (always arrays) */
+const assets = ref<Base64File[]>([])       // items with server id (or ones we keep as “assets”)
+const files = shallowRef<File[]>([])       // native File objects picked by the user
+
+/** Cache to avoid re-reading the same File repeatedly */
+const fileCache = new WeakMap<File, Promise<Base64File>>()
+
+/** Re-entrancy guard to break the emit -> props watcher -> syncFromModel loop */
+let internalSync = false
+
+/** Build a stable dedupe key */
+function base64FileKey(x: Base64File): string {
+  if (x.id != null) return `id:${x.id}`
+  const name = x.fileName ?? ''
+  const len = x.base64String?.length ?? 0
+  return `n:${name}|l:${len}`
+}
+
+/** Dedupe by key (preserves order) */
+function uniqByKey(arr: Base64File[]): Base64File[] {
+  const seen = new Set<string>()
+  const out: Base64File[] = []
+  for (const it of arr) {
+    const k = base64FileKey(it)
+    if (!seen.has(k)) {
+      seen.add(k)
+      out.push(it)
+    }
+  }
+  return out
+}
+
+/** Shallow equal by key sequence */
+function arraysEqualByKey(a: Base64File[], b: Base64File[]): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (base64FileKey(a[i]) !== base64FileKey(b[i])) return false
+  }
+  return true
+}
+
+/** Normalize incoming modelValue into arrays for internal use */
+async function syncFromModel() {
+  const mv = props.modelValue
+  if (!mv) {
+    assets.value = []
+    files.value = []
+    return
+  }
+
+  const asArray = castArray(mv) as Base64File[]
+
+  // Split into “asset with id” vs “inline base64” (no id)
+  const incomingAssets = asArray.filter(a => a.id != null)
+  const inlineBase64 = asArray.filter(a => a.id == null && a.base64String)
+
+  // Convert inline base64 to File for consistent UX
+  const inlineFiles: File[] = []
+  for (const item of inlineBase64) {
+    const f = base64ToFile(item.base64String as string, item.fileName)
+    if (f) inlineFiles.push(f)
+  }
+
+  assets.value = incomingAssets
+  files.value = inlineFiles
+
+  // Optionally hydrate assets that need it
+  if (props.autoHydrate) {
+    const needsHydration = assets.value.filter(a => a.id != null && !a.base64String)
+    if (needsHydration.length) {
+      await Promise.allSettled(needsHydration.map(hydrateAssetFile))
+    }
+  }
+}
+
+/** Open chooser */
+function openWindowUpload() {
+  if (props.multiple || (assets.value.length === 0 && files.value.length === 0)) {
+    fileInput.value?.click()
+  }
+}
+
+/** Add files from input (single or multiple) */
+function addFiles(payload: File | File[]) {
+  if (Array.isArray(payload)) files.value = [...files.value, ...payload]
+  else files.value = [...files.value, payload]
+}
+
+/** Remove chips */
+function removeFileByIndex(i: number | string) {
+  const idx = Number(i)
+  if (idx >= 0 && idx < files.value.length) {
+    const copy = files.value.slice()
+    copy.splice(idx, 1)
+    files.value = copy
+  }
+}
+function removeAssetByIndex(i: number | string) {
+  const idx = Number(i)
+  if (idx >= 0 && idx < assets.value.length) {
+    const copy = assets.value.slice()
+    copy.splice(idx, 1)
+    assets.value = copy
+  }
+}
+
+/** Convert current files → Base64File[] (cached) */
+async function filesToBase64Files(list: File[]): Promise<Base64File[]> {
+  const tasks = list.map(f => {
+    let p = fileCache.get(f)
+    if (!p) {
+      p = fileToBase64WithMaxSize(f)
+      fileCache.set(f, p)
+    }
+    return p
+  })
+  return Promise.all(tasks)
+}
+
+/** Combined result (array form) */
+const combinedArray = ref<Base64File[]>([])
+
+/** Dirty flag for <v-text-field> */
+const isDirty = computed(() =>
+    props.multiple ? combinedArray.value.length > 0 : combinedArray.value[0] != null
+)
+
+/** Sync from props.modelValue (guarded) */
+watch(
+    () => props.modelValue,
+    () => {
+      if (internalSync) return
+      void syncFromModel()
+    },
+    { deep: true, immediate: true }
+)
+
+/** Rebuild combined and emit (guarded, deduped, only-on-change) */
+watch([assets, files], async () => {
+  try {
+    const base64FromFiles = await filesToBase64Files(files.value)
+
+    const mergedArray = props.multiple
+        ? [...assets.value, ...base64FromFiles]
+        : (assets.value[0] ?? base64FromFiles[0] ?? null)
+            ? [assets.value[0] ?? base64FromFiles[0]]
+            : []
+
+    const nextCombined = props.multiple ? uniqByKey(mergedArray) : mergedArray
+
+    if (!arraysEqualByKey(combinedArray.value, nextCombined)) {
+      combinedArray.value = nextCombined
+
+      internalSync = true
+      try {
+        if (props.multiple) {
+          emit('update:modelValue', combinedArray.value)
+        } else {
+          emit('update:modelValue', combinedArray.value[0] ?? null)
+        }
+      } finally {
+        // let Vue flush the emit before re-enabling the external sync
+        queueMicrotask(() => { internalSync = false })
+      }
+    }
+  } catch (error: any) {
+    alert?.addAlert({ message: String(error), alertType: 'error' })
+    files.value = []
+    const fallback = props.multiple
+        ? [...assets.value]
+        : (assets.value[0] ? [assets.value[0]] : [])
+
+    if (!arraysEqualByKey(combinedArray.value, fallback)) {
+      combinedArray.value = fallback
+      internalSync = true
+      try {
+        if (props.multiple) emit('update:modelValue', combinedArray.value)
+        else emit('update:modelValue', combinedArray.value[0] ?? null)
+      } finally {
+        queueMicrotask(() => { internalSync = false })
+      }
+    }
+  }
+}, { deep: true, immediate: true })
+</script>
+
+<template>
+  <v-text-field
+      v-bind="$attrs"
+      label="Upload files"
+      readonly
+      :dirty="isDirty"
+      v-on="isDirty && !props.multiple ? {} : { click: openWindowUpload }"
+  >
+    <template #default>
+      <!-- Server/asset items -->
+      <v-chip
+          v-for="(asset, index) in assets"
+          :key="`${asset.id ?? asset.fileName}-${index}`"
+          color="green"
+          variant="flat"
+          closable
+          @click:close="removeAssetByIndex(index)"
+      >
+        {{ asset.originalFileName || asset.fileName }}
+        <template #append v-if="props.downloadable">
+          <slot name="download" :item="asset">
+            <v-icon
+                v-if="asset.base64String"
+                @click.stop="downloadBase64File(asset.base64String, asset.originalFileName || asset.fileName)"
+            >
+              mdi mdi-download
+            </v-icon>
+          </slot>
+        </template>
+      </v-chip>
+
+      <!-- Local uploaded files -->
+      <v-chip
+          v-for="(file, index) in files"
+          :key="`${file.name}-${file.size}-${index}`"
+          color="primary"
+          variant="flat"
+          closable
+          @click:close="removeFileByIndex(index)"
+      >
+        {{ file.name }}
+      </v-chip>
+    </template>
+
+    <!-- Add more button for multi mode -->
+    <template v-if="props.multiple && combinedArray.length > 0" #append-inner>
+      <VBtn variant="text" :icon="true" @click="openWindowUpload">
+        <v-icon>mdi mdi-plus</v-icon>
+      </VBtn>
+    </template>
+  </v-text-field>
+
+  <v-file-input
+      ref="fileInput"
+      :accept="props.accept"
+      :multiple="props.multiple"
+      style="display: none"
+      @update:model-value="addFiles"
+  />
 </template>