@ramathibodi/nuxt-commons 0.1.73 → 0.1.75

package/dist/runtime/components/ExportCSV.vue

@@ -1,102 +1,110 @@
-<script lang="ts" setup>
-import { ref } from 'vue'
-import * as XLSX from 'xlsx'
-import { VBtn } from 'vuetify/components/VBtn'
-import { useAlert } from '../composables/alert'
-
-interface ExportButtonProps extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
-  fileName?: string
-  sheetName?: string
-  modelValue?: object[]
-  stringFields?: Array<string>
-  tooltip?: string | Record<string,any> | undefined
-}
-
-const props = withDefaults(defineProps<ExportButtonProps>(), {
-  fileName: 'download',
-  sheetName: 'Sheet1',
-  stringFields: ()=>[],
-  tooltip: ()=>({text: 'Export', location: 'bottom'}),
-})
-
-const alert = useAlert()
-const loading = ref(false)
-
-/**
- * Triggers file export
- */
-function exportFile() {
-  if (props.modelValue && Array.isArray(props.modelValue) && props.modelValue.length > 0) {
-    loading.value = true
-
-    try {
-      const workbook = XLSX.utils.book_new()
-      const worksheet = XLSX.utils.json_to_sheet(flattenNestedFields(props.modelValue))
-      const fileName = `${props.fileName}.xlsx`
-
-      XLSX.utils.book_append_sheet(workbook, worksheet, props.sheetName)
-      XLSX.writeFile(workbook, fileName)
-    } catch (error: any) {
-      alert?.addAlert({ message: `Export failed: ${error.message}`, alertType: 'error' })
-    } finally {
-      loading.value = false
-    }
-  } else {
-    alert?.addAlert({ message: 'Invalid or no data to export', alertType: 'error' })
-  }
-}
-
-/**
- * Recursively flattens nested fields for export
- * @param items - Array of objects to flatten
- */
-function flattenNestedFields(items: any[]) {
-  return items.map((item: any) => {
-    return flattenObject(item)
-  })
-}
-
-/**
- * Recursively flattens an object, converting nested keys into dot-separated keys
- * @param obj - Object to flatten
- * @param parentKey - Parent key (for recursion)
- * @param separator - Separator for nested keys
- */
-function flattenObject(obj: any, parentKey = '', separator = '.') {
-  return Object.keys(obj).reduce((acc: any, key: string) => {
-    const newKey = parentKey ? `${parentKey}${separator}${key}` : key
-    const value = obj[key]
-
-    if (value && typeof value === 'object' && !Array.isArray(value) && !props.stringFields.includes(newKey)) {
-      Object.assign(acc, flattenObject(value, newKey, separator))
-    } else {
-      acc[newKey] = typeof value === 'object' ? JSON.stringify(value) : value
-    }
-
-    return acc
-  }, {})
-}
-</script>
-
-<template>
-  <VBtn
-      v-bind="$attrs"
-      color="primary"
-      :loading="loading"
-      :disabled="loading"
-      text="Export CSV"
-      @click="exportFile"
-      v-tooltip="props.tooltip"
-  >
-    <template
-        v-for="(_, name, index) in ($slots as {})"
-        :key="index"
-        #[name]="slotData"
-    >
-      <slot
-          :name="name"
-          v-bind="((slotData || {}) as object)"
-      />
-    </template>
-  </VBtn>
-</template>
+<script lang="ts" setup>
+/**
+ * ExportCSV exports array data to spreadsheet files, flattening nested fields before file generation.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
+import { ref } from 'vue'
+import * as XLSX from 'xlsx'
+import { VBtn } from 'vuetify/components/VBtn'
+import { useAlert } from '../composables/alert'
+
+interface ExportButtonProps extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
+  fileName?: string // File name used when downloading or printing generated files.
+  sheetName?: string // Configuration option used by ExportCSV.
+  modelValue?: object[] // Bound value for v-model synchronization with the parent component.
+  stringFields?: Array<string> // Field paths that must stay as string values (no nested object conversion).
+  tooltip?: string | Record<string,any> | undefined // Tooltip text or config object shown for the action control.
+}
+
+/**
+ * Public props accepted by ExportCSV.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
+const props = withDefaults(defineProps<ExportButtonProps>(), {
+  fileName: 'download',
+  sheetName: 'Sheet1',
+  stringFields: ()=>[],
+  tooltip: ()=>({text: 'Export', location: 'bottom'}),
+})
+
+const alert = useAlert()
+const loading = ref(false)
+
+/**
+ * Triggers file export
+ */
+function exportFile() {
+  if (props.modelValue && Array.isArray(props.modelValue) && props.modelValue.length > 0) {
+    loading.value = true
+
+    try {
+      const workbook = XLSX.utils.book_new()
+      const worksheet = XLSX.utils.json_to_sheet(flattenNestedFields(props.modelValue))
+      const fileName = `${props.fileName}.xlsx`
+
+      XLSX.utils.book_append_sheet(workbook, worksheet, props.sheetName)
+      XLSX.writeFile(workbook, fileName)
+    } catch (error: any) {
+      alert?.addAlert({ message: `Export failed: ${error.message}`, alertType: 'error' })
+    } finally {
+      loading.value = false
+    }
+  } else {
+    alert?.addAlert({ message: 'Invalid or no data to export', alertType: 'error' })
+  }
+}
+
+/**
+ * Recursively flattens nested fields for export
+ * @param items - Array of objects to flatten
+ */
+function flattenNestedFields(items: any[]) {
+  return items.map((item: any) => {
+    return flattenObject(item)
+  })
+}
+
+/**
+ * Recursively flattens an object, converting nested keys into dot-separated keys
+ * @param obj - Object to flatten
+ * @param parentKey - Parent key (for recursion)
+ * @param separator - Separator for nested keys
+ */
+function flattenObject(obj: any, parentKey = '', separator = '.') {
+  return Object.keys(obj).reduce((acc: any, key: string) => {
+    const newKey = parentKey ? `${parentKey}${separator}${key}` : key
+    const value = obj[key]
+
+    if (value && typeof value === 'object' && !Array.isArray(value) && !props.stringFields.includes(newKey)) {
+      Object.assign(acc, flattenObject(value, newKey, separator))
+    } else {
+      acc[newKey] = typeof value === 'object' ? JSON.stringify(value) : value
+    }
+
+    return acc
+  }, {})
+}
+</script>
+
+<template>
+  <VBtn
+      v-bind="$attrs"
+      color="primary"
+      :loading="loading"
+      :disabled="loading"
+      text="Export CSV"
+      @click="exportFile"
+      v-tooltip="props.tooltip"
+  >
+    <template
+        v-for="(_, name, index) in ($slots as {})"
+        :key="index"
+        #[name]="slotData"
+    >
+      <slot
+          :name="name"
+          v-bind="((slotData || {}) as object)"
+      />
+    </template>
+  </VBtn>
+</template>

package/dist/runtime/components/FileBtn.vue

@@ -1,67 +1,79 @@
-<script lang="ts" setup>
-import {ref} from 'vue'
-import {VBtn} from 'vuetify/components/VBtn'
-
-interface Props extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
-  accept?: string
-  multiple?: boolean
-  iconOnly?: boolean
-  modelValue?: File | File[] | undefined
-  tooltip?: string | Record<string,any> | undefined
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  multiple: false,
-  accept: '*',
-  tooltip: 'Upload File',
-})
-
-const emit = defineEmits<{
-  (event: 'update:modelValue', value: File | File[] | undefined): void
-}>()
-
-const fileInput = ref<HTMLInputElement>()
-const files = ref<File | File[]>()
-
-const openFileInput = () => {
-  fileInput.value?.click()
-}
-
-const reset = () => {
-  files.value = undefined
-}
-
-const emitFiles = () => {
-  emit('update:modelValue', files.value)
-  files.value = []
-}
-
-defineExpose({ reset })
-</script>
-
-<template>
-  <v-btn
-    v-bind="$attrs"
-    @click="openFileInput"
-    v-tooltip="tooltip"
-  >
-    <template
-      v-for="(_, name, index) in ($slots as {})"
-      :key="index"
-      #[name]="slotData"
-    >
-      <slot
-        :name="name"
-        v-bind="((slotData || {}) as object)"
-      />
-    </template>
-  </v-btn>
-  <v-file-input
-    ref="fileInput"
-    v-model="files"
-    @update:modelValue="emitFiles"
-    :accept="props.accept"
-    :multiple="props.multiple"
-    style="display: none"
-  />
-</template>
+<script lang="ts" setup>
+/**
+ * FileBtn wraps file selection behavior into a reusable button interface that works with form and upload flows.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
+import {ref} from 'vue'
+import {VBtn} from 'vuetify/components/VBtn'
+
+interface Props extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
+  accept?: string // Accepted file MIME types or extensions for file selection.
+  multiple?: boolean // Allows selecting or uploading more than one file.
+  iconOnly?: boolean // icon name/class used in UI rendering
+  modelValue?: File | File[] | undefined // Bound value for v-model synchronization with the parent component.
+  tooltip?: string | Record<string,any> | undefined // Tooltip text or config object shown for the action control.
+}
+
+/**
+ * Public props accepted by FileBtn.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
+const props = withDefaults(defineProps<Props>(), {
+  multiple: false,
+  accept: '*',
+  tooltip: 'Upload File',
+})
+
+/**
+ * Custom events emitted by FileBtn.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
+const emit = defineEmits<{
+  (event: 'update:modelValue', value: File | File[] | undefined): void
+}>()
+
+const fileInput = ref<HTMLInputElement>()
+const files = ref<File | File[]>()
+
+const openFileInput = () => {
+  fileInput.value?.click()
+}
+
+const reset = () => {
+  files.value = undefined
+}
+
+const emitFiles = () => {
+  emit('update:modelValue', files.value)
+  files.value = []
+}
+
+defineExpose({ reset })
+</script>
+
+<template>
+  <v-btn
+    v-bind="$attrs"
+    @click="openFileInput"
+    v-tooltip="tooltip"
+  >
+    <template
+      v-for="(_, name, index) in ($slots as {})"
+      :key="index"
+      #[name]="slotData"
+    >
+      <slot
+        :name="name"
+        v-bind="((slotData || {}) as object)"
+      />
+    </template>
+  </v-btn>
+  <v-file-input
+    ref="fileInput"
+    v-model="files"
+    @update:modelValue="emitFiles"
+    :accept="props.accept"
+    :multiple="props.multiple"
+    style="display: none"
+  />
+</template>

package/dist/runtime/components/ImportCSV.vue

@@ -1,139 +1,151 @@
-<script lang="ts" setup>
-import * as XLSX from 'xlsx'
-import { ref } from 'vue'
-import { useAlert } from '../composables/alert'
-import { VBtn } from 'vuetify/components/VBtn'
-
-interface ImportButtonProps extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
-  stringFields?: Array<string>
-  tooltip?: string | Record<string,any> | undefined
-}
-
-const props = withDefaults(defineProps<ImportButtonProps>(), {
-  stringFields: ()=>[],
-  tooltip: ()=>({text: 'Import', location: 'bottom'}),
-})
-
-const alert = useAlert()
-const emit = defineEmits<{
-  (e: 'import', value: object[]): void
-}>()
-
-const loading = ref(false)
-const fileBtnRef = ref()
-
-function uploadedFile(files: File[] | File | undefined) {
-  if (!files) return
-
-  if (Array.isArray(files) && files.length != 1) {
-    alert?.addAlert({ message: 'Please select a single file for import', alertType: 'error' })
-    return
-  }
-
-  if (Array.isArray(files)) files = files[0]
-
-  const fileExtension = files.name.slice(files.name.lastIndexOf('.')).toLowerCase()
-  if (!['.xlsx', '.csv'].includes(fileExtension)) {
-    alert?.addAlert({ message: `Please upload a file with .csv or .xlsx extension only (${files.name})`, alertType: 'error' })
-    return
-  }
-
-  const reader = new FileReader()
-  reader.onload = (e: ProgressEvent<FileReader>) => {
-    const workbook = XLSX.read(e.target?.result)
-    const parsedData = parseAndAggregateColumns(
-        XLSX.utils.sheet_to_json(workbook.Sheets[workbook.SheetNames[0]])
-    )
-    emit('import', parsedData)
-    loading.value = false
-    fileBtnRef.value.reset()
-  }
-  loading.value = true
-  reader.readAsArrayBuffer(files)
-}
-
-/**
- * Recursively aggregates nested columns and properties.
- * @param items - Array of data from the Excel sheet
- */
-const parseAndAggregateColumns = (items: any[]) => {
-  return items.map((item: any) => {
-    const aggregatedItem: any = {}
-
-    for (const key in item) {
-      if (key.includes('.')) {
-        // Extract root key and subKey
-        const [rootKey, ...subKeys] = key.split('.')
-
-        // Recursively aggregate subKeys
-        aggregatedItem[rootKey] = aggregatedItem[rootKey] || {}
-        assignNestedValue(aggregatedItem[rootKey], subKeys, parseIfJson(item[key]))
-      } else {
-        // Directly assign root-level properties
-        if (props.stringFields.includes(key)) aggregatedItem[key] = item[key]
-        else aggregatedItem[key] = parseIfJson(item[key])
-      }
-    }
-
-    return aggregatedItem
-  })
-}
-
-/**
- * Recursively assigns a value to a nested key structure.
- * @param obj - The object to assign to
- * @param keys - Array of keys leading to the final property
- * @param value - The value to assign
- */
-const assignNestedValue = (obj: any, keys: string[], value: any) => {
-  const [currentKey, ...remainingKeys] = keys
-  if (remainingKeys.length === 0) {
-    obj[currentKey] = value
-  } else {
-    obj[currentKey] = obj[currentKey] || {}
-    assignNestedValue(obj[currentKey], remainingKeys, value)
-  }
-}
-
-/**
- * Attempt to parse a value as JSON or array.
- * @param value - The value to parse
- */
-const parseIfJson = (value: any) => {
-  if (typeof value === 'string') {
-    try {
-      let parsedValue = JSON.parse(value)
-      return (parsedValue==value) ? value : parsedValue
-    } catch {
-      // If parsing fails, return the original value
-      return value
-    }
-  }
-  return value
-}
-</script>
-
-<template>
-  <FileBtn
-      ref="fileBtnRef"
-      v-bind="$attrs"
-      color="primary"
-      :loading="loading"
-      text="Import CSV"
-      accept=".csv, .xlsx"
-      :multiple="false"
-      @update:model-value="uploadedFile"
-      :tooltip="props.tooltip"
-  >
-    <template
-        v-for="(_, name, index) in ($slots as {})"
-        :key="index"
-        #[name]="slotData"
-    >
-      <slot
-          :name="name"
-          v-bind="((slotData || {}) as object)"
-      />
-    </template>
-  </FileBtn>
-</template>
+<script lang="ts" setup>
+/**
+ * ImportCSV imports spreadsheet rows, maps nested object keys, and emits normalized records for downstream processing.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
+import * as XLSX from 'xlsx'
+import { ref } from 'vue'
+import { useAlert } from '../composables/alert'
+import { VBtn } from 'vuetify/components/VBtn'
+
+interface ImportButtonProps extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
+  stringFields?: Array<string> // Field paths that must stay as string values (no nested object conversion).
+  tooltip?: string | Record<string,any> | undefined // Tooltip text or config object shown for the action control.
+}
+
+/**
+ * Public props accepted by ImportCSV.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
+const props = withDefaults(defineProps<ImportButtonProps>(), {
+  stringFields: ()=>[],
+  tooltip: ()=>({text: 'Import', location: 'bottom'}),
+})
+
+const alert = useAlert()
+/**
+ * Custom events emitted by ImportCSV.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
+const emit = defineEmits<{
+  (e: 'import', value: object[]): void
+}>()
+
+const loading = ref(false)
+const fileBtnRef = ref()
+
+function uploadedFile(files: File[] | File | undefined) {
+  if (!files) return
+
+  if (Array.isArray(files) && files.length != 1) {
+    alert?.addAlert({ message: 'Please select a single file for import', alertType: 'error' })
+    return
+  }
+
+  if (Array.isArray(files)) files = files[0]
+
+  const fileExtension = files.name.slice(files.name.lastIndexOf('.')).toLowerCase()
+  if (!['.xlsx', '.csv'].includes(fileExtension)) {
+    alert?.addAlert({ message: `Please upload a file with .csv or .xlsx extension only (${files.name})`, alertType: 'error' })
+    return
+  }
+
+  const reader = new FileReader()
+  reader.onload = (e: ProgressEvent<FileReader>) => {
+    const workbook = XLSX.read(e.target?.result)
+    const parsedData = parseAndAggregateColumns(
+        XLSX.utils.sheet_to_json(workbook.Sheets[workbook.SheetNames[0]])
+    )
+    emit('import', parsedData)
+    loading.value = false
+    fileBtnRef.value.reset()
+  }
+  loading.value = true
+  reader.readAsArrayBuffer(files)
+}
+
+/**
+ * Recursively aggregates nested columns and properties.
+ * @param items - Array of data from the Excel sheet
+ */
+const parseAndAggregateColumns = (items: any[]) => {
+  return items.map((item: any) => {
+    const aggregatedItem: any = {}
+
+    for (const key in item) {
+      if (key.includes('.')) {
+        // Extract root key and subKey
+        const [rootKey, ...subKeys] = key.split('.')
+
+        // Recursively aggregate subKeys
+        aggregatedItem[rootKey] = aggregatedItem[rootKey] || {}
+        assignNestedValue(aggregatedItem[rootKey], subKeys, parseIfJson(item[key]))
+      } else {
+        // Directly assign root-level properties
+        if (props.stringFields.includes(key)) aggregatedItem[key] = item[key]
+        else aggregatedItem[key] = parseIfJson(item[key])
+      }
+    }
+
+    return aggregatedItem
+  })
+}
+
+/**
+ * Recursively assigns a value to a nested key structure.
+ * @param obj - The object to assign to
+ * @param keys - Array of keys leading to the final property
+ * @param value - The value to assign
+ */
+const assignNestedValue = (obj: any, keys: string[], value: any) => {
+  const [currentKey, ...remainingKeys] = keys
+  if (remainingKeys.length === 0) {
+    obj[currentKey] = value
+  } else {
+    obj[currentKey] = obj[currentKey] || {}
+    assignNestedValue(obj[currentKey], remainingKeys, value)
+  }
+}
+
+/**
+ * Attempt to parse a value as JSON or array.
+ * @param value - The value to parse
+ */
+const parseIfJson = (value: any) => {
+  if (typeof value === 'string') {
+    try {
+      let parsedValue = JSON.parse(value)
+      return (parsedValue==value) ? value : parsedValue
+    } catch {
+      // If parsing fails, return the original value
+      return value
+    }
+  }
+  return value
+}
+</script>
+
+<template>
+  <FileBtn
+      ref="fileBtnRef"
+      v-bind="$attrs"
+      color="primary"
+      :loading="loading"
+      text="Import CSV"
+      accept=".csv, .xlsx"
+      :multiple="false"
+      @update:model-value="uploadedFile"
+      :tooltip="props.tooltip"
+  >
+    <template
+        v-for="(_, name, index) in ($slots as {})"
+        :key="index"
+        #[name]="slotData"
+    >
+      <slot
+          :name="name"
+          v-bind="((slotData || {}) as object)"
+      />
+    </template>
+  </FileBtn>
+</template>