@cloudron/pankow 4.2.3 → 4.3.1

package/utils.js

@@ -2,7 +2,13 @@
 import { filesize } from 'filesize';
 import { customRef } from 'vue';
 
-// https://vuejs.org/api/reactivity-advanced.html#customref
+/**
+ * Creates a debounced reactive ref that delays value updates.
+ * @see https://vuejs.org/api/reactivity-advanced.html#customref
+ * @param {any} value
+ * @param {number} [delay=300] - Debounce delay in milliseconds
+ * @returns {import('vue').Ref}
+ */
 function useDebouncedRef(value, delay = 300) {
   let timeout;
   return customRef((track, trigger) => {
@@ -22,25 +28,46 @@ function useDebouncedRef(value, delay = 300) {
   })
 }
 
+/**
+ * Extracts the MIME type group from an item (e.g. "image" from "image/png").
+ * @param {{ mimeType: string }} item
+ * @returns {string}
+ * @throws {string} If item has no mimeType string property
+ */
 function getFileTypeGroup(item) {
     if (typeof item.mimeType !== 'string') throw 'item must have mimeType string property';
     return item.mimeType.split('/')[0];
 }
 
+/**
+ * Validates whether a string is a valid domain or URL (extracts hostname from URLs first).
+ * @param {string} domain
+ * @returns {boolean}
+ */
 function isValidDomainOrURL(domain) {
     try {
-        domain = new URL(input).hostname;
+        domain = new URL(domain).hostname;
     } catch (e) {}
 
     return isValidDomain(domain);
 }
 
+/**
+ * Validates whether a string is a valid domain name.
+ * @param {string} domain
+ * @returns {boolean}
+ */
 function isValidDomain(domain) {
     const domainRegex = /^([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}$/;
     return domainRegex.test(domain);
 }
 
-// this currently does not match: "john.doe"@example.com, user@[192.168.1.1], john.doe(comment)@example.com or 用户@例子.世界
+/**
+ * Validates whether a string is a valid email address.
+ * Does not match: quoted local-parts, IP-literal domains, comments, or internationalized addresses.
+ * @param {string} email
+ * @returns {boolean}
+ */
 function isValidEmail(email) {
     if (!email || typeof email !== 'string') return false;
 
@@ -49,8 +76,13 @@ function isValidEmail(email) {
 }
 
 
-// https://en.wikipedia.org/wiki/Binary_prefix
-// binary units (IEC) 1024 based
+/**
+ * Formats a byte count into human-readable IEC binary units (KiB, MiB, GiB, TiB).
+ * @see https://en.wikipedia.org/wiki/Binary_prefix
+ * @param {number} size - Byte count; -1 returns "Unlimited"
+ * @param {string|number} [fallback] - Value returned when size is falsy (0, null, undefined)
+ * @returns {string|number}
+ */
 function prettyBinarySize(size, fallback) {
     if (!size) return fallback || 0;
     if (size === -1) return 'Unlimited';
@@ -60,7 +92,12 @@ function prettyBinarySize(size, fallback) {
     return (size / Math.pow(1024, i)).toFixed(3) * 1 + ' ' + ['B', 'KiB', 'MiB', 'GiB', 'TiB'][i];
 }
 
-// decimal units (SI) 1000 based
+/**
+ * Formats a byte count into human-readable SI decimal units (kB, MB, GB, TB).
+ * @param {number} size - Byte count
+ * @param {string|number} [fallback] - Value returned when size is falsy
+ * @returns {string|number}
+ */
 function prettyDecimalSize(size, fallback) {
     if (!size) return fallback || 0;
 
@@ -68,6 +105,11 @@ function prettyDecimalSize(size, fallback) {
     return (size / Math.pow(1000, i)).toFixed(2) * 1 + ' ' + ['B', 'kB', 'MB', 'GB', 'TB'][i];
 }
 
+/**
+ * Formats a date as a relative time string using Intl.RelativeTimeFormat.
+ * @param {Date} date
+ * @returns {string}
+ */
 function fromNow(date) {
   const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
 
@@ -93,7 +135,11 @@ function fromNow(date) {
   return rtf.format(years, 'year');
 }
 
-// this will print a human friendly datetime offset from now
+/**
+ * Formats a value as a human-friendly relative time offset from now (e.g. "2 days ago").
+ * @param {string|number} value - Date string or timestamp; falsy returns "never"
+ * @returns {string}
+ */
 function prettyDate(value) {
     if (!value) return 'never';
 
@@ -103,6 +149,12 @@ function prettyDate(value) {
     return fromNow(date);
 }
 
+/**
+ * Formats a date using a named format preset.
+ * @param {'hh:mm A'|'hh:mm:ss A'|'DD MMM'|'DD MMM hh:mm A'} format - Preset format key
+ * @param {string|number} value - Date string or timestamp
+ * @returns {string}
+ */
 function formatDate(format, value) {
     const formatters = {
         'hh:mm A': new Intl.DateTimeFormat(undefined, {
@@ -126,16 +178,17 @@ function formatDate(format, value) {
             hour: '2-digit',
             minute: '2-digit',
             hour12: true
-        }),
-        'DD MMM': new Intl.DateTimeFormat(undefined, { // force this to get month first
-            day: '2-digit',
-            month: 'short'
         })
     };
 
     return formatters[format].format(new Date(value));
 }
 
+/**
+ * Formats a value as a short time string (medium time style via Intl.DateTimeFormat).
+ * @param {string|number} value - Date string or timestamp; falsy returns "unknown"
+ * @returns {string}
+ */
 function prettyShortDate(value) {
     if (!value) return 'unknown';
 
@@ -151,6 +204,11 @@ function prettyShortDate(value) {
     return formattedDate;
 }
 
+/**
+ * Formats a value as a long date string (day, month, year, time).
+ * @param {string|number} value - Date string or timestamp; falsy returns "unknown"
+ * @returns {string}
+ */
 function prettyLongDate(value) {
     if (!value) return 'unknown';
 
@@ -170,12 +228,22 @@ function prettyLongDate(value) {
     return formattedDate;
 }
 
+/**
+ * Formats a numeric value as a human-readable file size string (uses the `filesize` library).
+ * @param {number} value - Byte count
+ * @returns {string}
+ */
 function prettyFileSize(value) {
     if (typeof value !== 'number') return 'unknown';
 
     return filesize(value);
 }
 
+/**
+ * Strips angle brackets from email address strings or arrays.
+ * @param {string|string[]} addresses - Format: "<name@example.com>"; returns empty string if falsy
+ * @returns {string}
+ */
 function prettyEmailAddresses(addresses) {
     if (!addresses) return '';
     if (addresses === '<>') return '<>';
@@ -183,6 +251,11 @@ function prettyEmailAddresses(addresses) {
     return addresses.slice(1, -1);
 }
 
+/**
+ * Formats milliseconds as a human-readable duration string using Intl.DurationFormat.
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string}
+ */
 function prettyDuration(ms) {
   const totalSeconds = Math.floor(ms / 1000);
   const days = Math.floor(totalSeconds / 86400);
@@ -194,15 +267,32 @@ function prettyDuration(ms) {
   return df.format({ days, hours, minutes, seconds });
 }
 
+/**
+ * Normalizes a file path: ensures leading slash and collapses consecutive slashes.
+ * @param {string} path
+ * @returns {string}
+ */
 function sanitize(path) {
     path = '/' + path;
     return path.replace(/\/+/g, '/');
 }
 
+/**
+ * Joins path segments and normalizes the result (via sanitize).
+ * @param {...string} args - Path segments to join
+ * @returns {string}
+ */
 function pathJoin() {
     return sanitize(Array.from(arguments).join('/'));
 }
 
+/**
+ * Triggers a file download via the browser. Single entry: direct download.
+ * Multiple entries: zipped archive download via /api/v1/download.
+ * @param {Array<{ filePath: string, share?: { id: string } }>} entries - File entries to download
+ * @param {string} [name] - Archive name for multi-file downloads
+ * @returns {void}
+ */
 function download(entries, name) {
     if (!entries.length) return;
 
@@ -231,12 +321,22 @@ function download(entries, name) {
     window.location.href = '/api/v1/download?' + params.toString();
 }
 
-// simple extension detection, does not work with double extension like .tar.gz
+/**
+ * Extracts the file extension from a file entry. Does not detect double extensions (e.g. .tar.gz).
+ * @param {{ isFile: boolean, fileName: string }} entry
+ * @returns {string} Extension without leading dot (empty string for directories or files without extension)
+ */
 function getExtension(entry) {
     if (entry.isFile) return entry.fileName.slice(entry.fileName.lastIndexOf('.') + 1);
     return '';
 }
 
+/**
+ * Copies a string to the system clipboard using a temporary input element.
+ * @param {string} value
+ * @returns {void}
+ * @deprecated Prefer the native `navigator.clipboard.writeText()` API.
+ */
 function copyToClipboard(value) {
     var elem = document.createElement('input');
     elem.value = value;
@@ -246,11 +346,20 @@ function copyToClipboard(value) {
     elem.remove();
 }
 
+/**
+ * Parses the current page's URL query string into a key/value object.
+ * @returns {Object<string, string>}
+ */
 function urlSearchQuery() {
     return decodeURIComponent(window.location.search).slice(1).split('&').map(function (item) { return item.split('='); }).reduce(function (o, k) { o[k[0]] = k[1]; return o; }, {});
 }
 
-// those paths contain the internal type and path reference eg. shares/:shareId/folder/filename or files/folder/filename
+/**
+ * Parses a Cloudron resource path into its components (type, path, shareId, apiPath).
+ * Handles paths like "files/folder/filename" or "shares/:shareId/folder/filename".
+ * @param {string} resourcePath
+ * @returns {{ type: string, path: string, shareId: string, apiPath: string, resourcePath: string }}
+ */
 function parseResourcePath(resourcePath) {
     var result = {
         type: '',
@@ -279,10 +388,22 @@ function parseResourcePath(resourcePath) {
     return result;
 }
 
+/**
+ * Generates a unique identifier for a file entry, including its share ID if present.
+ * @param {{ share?: { id: string }, filePath: string }} entry
+ * @returns {string}
+ */
 function getEntryIdentifier(entry) {
     return (entry.share ? (entry.share.id + '/') : '') + entry.filePath;
 }
 
+/**
+ * Sorts an array of objects by a given property, case-insensitive for strings.
+ * @param {Array<Object>} list - Array of objects to sort
+ * @param {string} prop - Property name to sort by
+ * @param {boolean} desc - If falsey, reverses the sort (descending order)
+ * @returns {Array<Object>}
+ */
 function entryListSort(list, prop, desc) {
     var tmp = list.sort(function (a, b) {
         var av = a[prop];
@@ -296,11 +417,20 @@ function entryListSort(list, prop, desc) {
     return tmp.reverse();
 }
 
+/**
+ * Returns a promise that resolves after the specified number of milliseconds.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-// this is from the Cloudron dashboard translation project en.json
+/**
+ * Fallback English translations from the Cloudron dashboard translation project.
+ * Used when the app does not provide its own i18n strings.
+ * @type {Object<string, Object<string, string>>}
+ */
 const fallbackTranslations = {
     "main": {
         "dialog": {
@@ -410,6 +540,12 @@ const fallbackTranslations = {
     }
 };
 
+/**
+ * Looks up a translation string by dot-separated key (e.g. "filemanager.title").
+ * Falls back to the key itself if the translation is not found.
+ * @param {string} id - Dot-separated translation key
+ * @returns {string}
+ */
 function translation(id) {
     let value;
     try {
@@ -422,6 +558,10 @@ function translation(id) {
     return value;
 }
 
+/**
+ * Generates a random UUID v4 string using crypto.getRandomValues.
+ * @returns {string}
+ */
 function uuidv4() {
   return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, c =>
     (c ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> c / 4).toString(16)

package/viewers/GenericViewer.vue

@@ -22,45 +22,33 @@
   </MainLayout>
 </template>
 
-<script>
+<script setup>
 
+import { reactive } from 'vue';
 import Button from '../components/Button.vue';
 import MainLayout from '../components/MainLayout.vue';
 import TopBar from '../components/TopBar.vue';
 import utils from '../utils.js';
 
-export default {
-    name: 'GenericViewer',
-    components: {
-      Button,
-      TopBar,
-      MainLayout
-    },
-    props: {
-      tr: {
-        type: Function,
-        default(id) { console.warn('Missing tr for GenericViewer'); return utils.translation(id); }
-      }
-    },
-    emits: [ 'close' ],
-    data() {
-      return {
-        entry: {}
-      };
-    },
-    methods: {
-      async open(entry) {
-        if (!entry) return;
+const props = defineProps({
+  tr: {
+    type: Function,
+    default(id) { console.warn('Missing tr for GenericViewer'); return utils.translation(id); }
+  }
+});
 
-        this.entry = entry;
-      },
-      onClose() {
-        this.$emit('close');
-      }
-    },
-    mounted() {
-    }
-};
+const emit = defineEmits([ 'close' ]);
+
+const entry = reactive({});
+
+async function open(e) {
+  if (!e) return;
+  Object.assign(entry, e);
+}
+
+function onClose() {
+  emit('close');
+}
 
 </script>