@cloudron/pankow 4.2.3 → 4.3.0

package/tooltip.js

@@ -1,19 +1,16 @@
-/*
+/**
+ * Tooltip Directive
+ *
+ * Usage:
+ * ```
+ * import tooltip from 'pankow/tooltip';
+ * app.directive('tooltip', tooltip);
+ * // <div v-tooltip.top="'hello'"></div>
+ * ```
+ *
+ * Position modifiers: `.top`, `.left`, `.right` (default: bottom).
+ */
 
-Tooltip Directive
-
-```
-import tooltip from 'pankow/tooltip';
-
-app.directive('tooltip', tooltip);
-
-...
-
-<div v-tooltip.top="'hello'"></div>
-
-```
-
-*/
 
 const TOP = 1;
 const BOTTOM = 2;
@@ -73,6 +70,12 @@ function update(target, modifiers, key) {
     else tooltips[key].element.style.top = (targetRect.bottom + padding) + 'px';
 }
 
+/**
+ * Vue directive `mounted` hook. Creates tooltip element on mouseenter.
+ * @param {HTMLElement} el
+ * @param {import('vue').DirectiveBinding} binding
+ * @param {import('vue').VNode} vnode
+ */
 function mounted(el, binding, vnode) {
     // generate running unique id
     el.__pankow_id = id++;
@@ -112,6 +115,12 @@ function mounted(el, binding, vnode) {
 
 }
 
+/**
+ * Vue directive `updated` hook. Updates tooltip text and position.
+ * @param {HTMLElement} el
+ * @param {import('vue').DirectiveBinding} binding
+ * @param {import('vue').VNode} vnode
+ */
 function updated(el, binding, vnode) {
     if (!tooltips[el.__pankow_id]) return;
 
@@ -123,6 +132,12 @@ function updated(el, binding, vnode) {
     update(el, binding.modifiers, el.__pankow_id);
 }
 
+/**
+ * Vue directive `beforeUnmount` hook. Removes tooltip element and cleans up.
+ * @param {HTMLElement} el
+ * @param {import('vue').DirectiveBinding} binding
+ * @param {import('vue').VNode} vnode
+ */
 function beforeUnmount(el, binding, vnode) {
     if (!tooltips[el.__pankow_id]) return;
 
@@ -130,6 +145,10 @@ function beforeUnmount(el, binding, vnode) {
     delete tooltips[el.__pankow_id];
 }
 
+/**
+ * Vue directive for tooltips. Register via `app.directive('tooltip', tooltip)`.
+ * @type {import('vue').Directive}
+ */
 const tooltip = {
     mounted,
     updated,

package/types/fallbackImage.d.ts

@@ -1,5 +1,6 @@
 export default fallbackImage;
-declare namespace fallbackImage {
-    export { mounted };
-}
-declare function mounted(el: any, binding: any, vnode: any): void;
+/**
+ * Vue directive for image fallback. Register via `app.directive('fallback-image', fallbackImage)`.
+ * @type {import('vue').Directive}
+ */
+declare const fallbackImage: import("vue").Directive;

package/types/fetcher.d.ts

@@ -8,33 +8,83 @@ declare namespace _default {
     export { del as delete };
 }
 export default _default;
+/**
+ * Shared configuration for all HTTP requests.
+ */
+export type FetcherGlobalOptions = {
+    /**
+     * - Fetch credentials mode
+     */
+    credentials: string;
+    /**
+     * - Fetch redirect mode
+     */
+    redirect: string;
+    /**
+     * - Called on non-2xx responses or network errors
+     */
+    errorHook: ((arg0: Response | Error) => void) | null;
+};
 declare namespace globalOptions {
     let credentials: string;
     let redirect: string;
     let errorHook: null;
 }
-/** @param {RequestInit} [options] Merged into `fetch()`; use `{ signal }` to abort. */
-declare function head(uri: any, query?: {}, options?: RequestInit): Promise<{
+/**
+ * Sends a HEAD request.
+ * @param {string} uri
+ * @param {Object} [query={}] - Query parameters serialized as URL query string
+ * @param {RequestInit} [options={}] - Merged into `fetch()`; use `{ signal }` to abort
+ * @returns {Promise<{ status: number, body: * }>}
+ */
+declare function head(uri: string, query?: Object, options?: RequestInit): Promise<{
     status: number;
     body: any;
 }>;
-/** @param {RequestInit} [options] Merged into `fetch()`; use `{ signal }` to abort. */
-declare function get(uri: any, query?: {}, options?: RequestInit): Promise<{
+/**
+ * Sends a GET request.
+ * @param {string} uri
+ * @param {Object} [query={}] - Query parameters serialized as URL query string
+ * @param {RequestInit} [options={}] - Merged into `fetch()`; use `{ signal }` to abort
+ * @returns {Promise<{ status: number, body: * }>}
+ */
+declare function get(uri: string, query?: Object, options?: RequestInit): Promise<{
     status: number;
     body: any;
 }>;
-/** @param {RequestInit} [options] Merged into `fetch()`; use `{ signal }` to abort. */
-declare function post(uri: any, body: any, query?: {}, options?: RequestInit): Promise<{
+/**
+ * Sends a POST request with a JSON or FormData body.
+ * @param {string} uri
+ * @param {Object|FormData} body - Request body; objects are JSON-stringified
+ * @param {Object} [query={}] - Query parameters serialized as URL query string
+ * @param {RequestInit} [options={}] - Merged into `fetch()`; use `{ signal }` to abort
+ * @returns {Promise<{ status: number, body: * }>}
+ */
+declare function post(uri: string, body: Object | FormData, query?: Object, options?: RequestInit): Promise<{
     status: number;
     body: any;
 }>;
-/** @param {RequestInit} [options] Merged into `fetch()`; use `{ signal }` to abort. */
-declare function put(uri: any, body: any, query?: {}, options?: RequestInit): Promise<{
+/**
+ * Sends a PUT request with a JSON or FormData body.
+ * @param {string} uri
+ * @param {Object|FormData} body - Request body; objects are JSON-stringified
+ * @param {Object} [query={}] - Query parameters serialized as URL query string
+ * @param {RequestInit} [options={}] - Merged into `fetch()`; use `{ signal }` to abort
+ * @returns {Promise<{ status: number, body: * }>}
+ */
+declare function put(uri: string, body: Object | FormData, query?: Object, options?: RequestInit): Promise<{
     status: number;
     body: any;
 }>;
-/** @param {RequestInit} [options] Merged into `fetch()`; use `{ signal }` to abort. */
-declare function del(uri: any, body: any, query?: {}, options?: RequestInit): Promise<{
+/**
+ * Sends a DELETE request with an optional body.
+ * @param {string} uri
+ * @param {Object|FormData} body - Request body; objects are JSON-stringified
+ * @param {Object} [query={}] - Query parameters serialized as URL query string
+ * @param {RequestInit} [options={}] - Merged into `fetch()`; use `{ signal }` to abort
+ * @returns {Promise<{ status: number, body: * }>}
+ */
+declare function del(uri: string, body: Object | FormData, query?: Object, options?: RequestInit): Promise<{
     status: number;
     body: any;
 }>;

package/types/gestures.d.ts

@@ -2,4 +2,19 @@ declare namespace _default {
     export { onSwipe };
 }
 export default _default;
-export function onSwipe(elem: any, callback: any, threshold?: number): void;
+/**
+ * Swipe handler
+ *
+ * Usage:
+ * ```
+ * import { onSwipe } from 'pankow/gestures';
+ * onSwipe(element, (direction) => {});
+ * ```
+ */
+/**
+ * Registers touch event listeners on an element and calls the callback on swipe.
+ * @param {HTMLElement} elem
+ * @param {function('left'|'right'|'up'|'down'): void} callback
+ * @param {number} [threshold=50] - Minimum pixel distance to trigger a swipe
+ */
+export function onSwipe(elem: HTMLElement, callback: (arg0: "left" | "right" | "up" | "down") => void, threshold?: number): void;

package/types/index.d.ts

@@ -1,6 +1,9 @@
+export { useNotify } from "./notifyState.js";
+export default pankowPlugin;
 import fetcher from './fetcher.js';
 import gestures from './gestures.js';
 import tooltip from './tooltip.js';
 import fallbackImage from './fallbackImage.js';
 import utils from './utils.js';
-export { BottomBar, BreadCrumb, Button, ButtonGroup, ClipboardAction, ClipboardButton, CheckBox, DateTimeInput, Dialog, DirectoryView, EmailInput, FileUploader, FormGroup, InputGroup, Icon, InputDialog, LoginView, MainLayout, MaskedInput, Menu, MenuItem, SingleSelect, MultiSelect, Notification, NumberInput, OfflineBanner, PasswordInput, Popover, ProgressBar, RadioButton, SectionItem, SideBar, SplitLayout, Spinner, Switch, TableView, TableViewActionBar, TabView, TagInput, TextInput, TextInputRaw, TopBar, TreeView, fetcher, gestures, tooltip, fallbackImage, utils, CheckBox as Checkbox, RadioButton as Radiobutton, BreadCrumb as Breadcrumb };
+import pankowPlugin from './plugin.js';
+export { BottomBar, BreadCrumb, Button, ButtonGroup, ClipboardAction, ClipboardButton, CheckBox, DateTimeInput, Dialog, DirectoryView, EmailInput, FileUploader, FormGroup, InputGroup, Icon, ListItem, InputDialog, LoginView, MainLayout, MaskedInput, Menu, MenuItem, SingleSelect, MultiSelect, Notification, NumberInput, OfflineBanner, PasswordInput, Popover, ProgressBar, RadioButton, SectionItem, SideBar, SplitLayout, Spinner, Switch, TableView, TableViewActionBar, TabView, TagInput, TextInput, TextInputRaw, TopBar, TreeView, fetcher, gestures, tooltip, fallbackImage, utils, CheckBox as Checkbox, RadioButton as Radiobutton, BreadCrumb as Breadcrumb };

package/types/notifyState.d.ts

@@ -0,0 +1,8 @@
+export const messages: import("vue").Reactive<never[]>;
+export const position: import("vue").Ref<string, string>;
+export function pushNotify(options: any): void;
+export function removeNotify(id: any): void;
+export function setNotifyPosition(pos: any): void;
+export function useNotify(): {
+    notify: typeof pushNotify;
+};

package/types/plugin.d.ts

@@ -0,0 +1,4 @@
+declare namespace _default {
+    function install(app: any, options?: {}): void;
+}
+export default _default;

package/types/tooltip.d.ts

@@ -1,9 +1,6 @@
 export default tooltip;
-declare namespace tooltip {
-    export { mounted };
-    export { updated };
-    export { beforeUnmount };
-}
-declare function mounted(el: any, binding: any, vnode: any): void;
-declare function updated(el: any, binding: any, vnode: any): void;
-declare function beforeUnmount(el: any, binding: any, vnode: any): void;
+/**
+ * Vue directive for tooltips. Register via `app.directive('tooltip', tooltip)`.
+ * @type {import('vue').Directive}
+ */
+declare const tooltip: import("vue").Directive;

package/types/utils.d.ts

@@ -26,35 +26,195 @@ declare namespace _default {
     export { uuidv4 };
 }
 export default _default;
-export function getFileTypeGroup(item: any): any;
-export function translation(id: any): any;
-export function useDebouncedRef(value: any, delay?: number): import("vue").Ref<any, any>;
-export function isValidDomain(domain: any): boolean;
-export function isValidDomainOrURL(domain: any): boolean;
-export function isValidEmail(email: any): boolean;
-export function prettyBinarySize(size: any, fallback: any): any;
-export function prettyDecimalSize(size: any, fallback: any): any;
-export function prettyDate(value: any): string;
-export function prettyShortDate(value: any): string;
-export function formatDate(format: any, value: any): any;
-export function prettyLongDate(value: any): string;
-export function prettyFileSize(value: any): string;
-export function prettyEmailAddresses(addresses: any): any;
-export function prettyDuration(ms: any): string;
-export function sanitize(path: any): any;
-export function pathJoin(...args: any[]): any;
-export function download(entries: any, name: any): void;
-export function getExtension(entry: any): any;
-export function copyToClipboard(value: any): void;
-export function urlSearchQuery(): {};
-export function parseResourcePath(resourcePath: any): {
+/**
+ * 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
+ */
+export function getFileTypeGroup(item: {
+    mimeType: string;
+}): string;
+/**
+ * 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}
+ */
+export function translation(id: string): string;
+/**
+ * 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}
+ */
+export function useDebouncedRef(value: any, delay?: number): import("vue").Ref;
+/**
+ * Validates whether a string is a valid domain name.
+ * @param {string} domain
+ * @returns {boolean}
+ */
+export function isValidDomain(domain: string): boolean;
+/**
+ * Validates whether a string is a valid domain or URL (extracts hostname from URLs first).
+ * @param {string} domain
+ * @returns {boolean}
+ */
+export function isValidDomainOrURL(domain: string): boolean;
+/**
+ * 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}
+ */
+export function isValidEmail(email: string): boolean;
+/**
+ * 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}
+ */
+export function prettyBinarySize(size: number, fallback?: string | number): string | number;
+/**
+ * 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}
+ */
+export function prettyDecimalSize(size: number, fallback?: string | number): string | number;
+/**
+ * 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}
+ */
+export function prettyDate(value: string | number): string;
+/**
+ * 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}
+ */
+export function prettyShortDate(value: string | number): string;
+/**
+ * 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}
+ */
+export function formatDate(format: "hh:mm A" | "hh:mm:ss A" | "DD MMM" | "DD MMM hh:mm A", value: string | number): string;
+/**
+ * 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}
+ */
+export function prettyLongDate(value: string | number): string;
+/**
+ * Formats a numeric value as a human-readable file size string (uses the `filesize` library).
+ * @param {number} value - Byte count
+ * @returns {string}
+ */
+export function prettyFileSize(value: number): string;
+/**
+ * Strips angle brackets from email address strings or arrays.
+ * @param {string|string[]} addresses - Format: "<name@example.com>"; returns empty string if falsy
+ * @returns {string}
+ */
+export function prettyEmailAddresses(addresses: string | string[]): string;
+/**
+ * Formats milliseconds as a human-readable duration string using Intl.DurationFormat.
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string}
+ */
+export function prettyDuration(ms: number): string;
+/**
+ * Normalizes a file path: ensures leading slash and collapses consecutive slashes.
+ * @param {string} path
+ * @returns {string}
+ */
+export function sanitize(path: string): string;
+/**
+ * Joins path segments and normalizes the result (via sanitize).
+ * @param {...string} args - Path segments to join
+ * @returns {string}
+ */
+export function pathJoin(...args: string[]): string;
+/**
+ * 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}
+ */
+export function download(entries: Array<{
+    filePath: string;
+    share?: {
+        id: string;
+    };
+}>, name?: string): void;
+/**
+ * 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)
+ */
+export function getExtension(entry: {
+    isFile: boolean;
+    fileName: string;
+}): string;
+/**
+ * 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.
+ */
+export function copyToClipboard(value: string): void;
+/**
+ * Parses the current page's URL query string into a key/value object.
+ * @returns {Object<string, string>}
+ */
+export function urlSearchQuery(): {
+    [x: string]: string;
+};
+/**
+ * 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 }}
+ */
+export function parseResourcePath(resourcePath: string): {
     type: string;
     path: string;
     shareId: string;
     apiPath: string;
     resourcePath: string;
 };
-export function getEntryIdentifier(entry: any): string;
-export function entryListSort(list: any, prop: any, desc: any): any;
-export function sleep(ms: any): Promise<any>;
+/**
+ * Generates a unique identifier for a file entry, including its share ID if present.
+ * @param {{ share?: { id: string }, filePath: string }} entry
+ * @returns {string}
+ */
+export function getEntryIdentifier(entry: {
+    share?: {
+        id: string;
+    };
+    filePath: string;
+}): string;
+/**
+ * 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>}
+ */
+export function entryListSort(list: Array<Object>, prop: string, desc: boolean): Array<Object>;
+/**
+ * Returns a promise that resolves after the specified number of milliseconds.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms: number): Promise<void>;
+/**
+ * Generates a random UUID v4 string using crypto.getRandomValues.
+ * @returns {string}
+ */
 export function uuidv4(): string;