@vandenberghinc/volt 1.1.26 → 1.1.28

package/frontend/dist/frontend/src/elements/module.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+export * from "./base.js";
+export * from "./types.js";
+import { VElement, extend as extend_velement, wrapper as _wrapper, create_null as _create_null } from "./base.js";
+import { register_element as _register_element } from "./register_element.js";
+export declare namespace Elements {
+    /**
+     * Re-exports the `register_element` helper for registering custom elements.
+     */
+    export const register_element: typeof _register_element;
+    /**
+     * Get an element by its ID.
+     * @nav Frontend
+     * @chapter Elements
+     * @param id The ID of the element.
+     * @docs
+     */
+    export function get(id: string): VElement;
+    /**
+     * Alias for `get` to retrieve an element by its ID.
+     * @nav Frontend
+     * @chapter Elements
+     * @param id The ID of the element.
+     * @docs
+     */
+    export function get_by_id(id: string): VElement;
+    /**
+     * Programmatically clicks an element by its ID.
+     * @nav Frontend
+     * @chapter Elements
+     * @param id The ID of the element.
+     * @docs
+     */
+    export function click(id: string): void;
+    /**
+     * Generic constructor signature used for class decorators and factories.
+     */
+    type Constructor<T = any> = new (...args: any[]) => T;
+    /**
+     * Options for the `Elements.create` class decorator.
+     * @property name The name to use for this element (becomes the “v-…” tag)
+     * @property tag Optional host tag to extend (defaults to constructor.tag if set)
+     * @property default_style Default inline styles for the element.
+     * @property default_attributes Default attributes for the element.
+     * @property default_events Default event handlers for the element.
+     */
+    interface CreateOpts {
+        name: string;
+        tag?: string;
+        default_style?: Record<string, any>;
+        default_attributes?: Record<string, any>;
+        default_events?: Record<string, any>;
+    }
+    /**
+     * Class decorator factory.
+     * @example
+     *   @create({ name: "Foo", tag?: "section", base: HTMLElement })
+     *   class Foo extends HTMLElement { … }
+     */
+    export function create(opts: CreateOpts): <T extends Constructor>(constructor: T) => T;
+    /**
+     * Re-exported constructor wrapper from the base module.
+     */
+    export const wrapper: typeof _wrapper;
+    /**
+     * Shared null element mainly for TypeScript typing convenience.
+     */
+    export const create_null: typeof _create_null;
+    /**
+     * Submits multiple elements by ID or reference.
+     * @nav Frontend
+     * @chapter Elements
+     * @deprecated
+     * @param elements A list of element IDs or element references to submit.
+     * @docs
+     */
+    export function submit(...elements: (string | VElement | HTMLElement)[]): Record<string, any>;
+    /**
+     * Forwards a function to a child element.
+     * @nav Frontend
+     * @chapter Elements
+     * @param func_name The name of the function to forward.
+     * @param child The child element or a function that returns the child element.
+     * @docs
+     */
+    export function forward_func_to_child(func_name: string, child: any): (val?: any) => any;
+    /**
+     * Typed re-export of `extend` to augment a `VElement` with additional helpers.
+     */
+    export const extend: typeof extend_velement;
+    export {};
+}

package/frontend/dist/{elements → frontend/src/elements}/module.js

@@ -1,26 +1,28 @@
-/*
- * Author: Daan van den Bergh
- * Copyright: © 2022 - 2024 Daan van den Bergh.
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
  */
 // Import elements create func.
 export * from "./base.js";
+export * from "./types.js";
 import { extend as extend_velement, wrapper as _wrapper, create_null as _create_null, } from "./base.js";
 import { register_element as _register_element } from "./register_element.js";
 // Elements module.
 export var Elements;
 (function (Elements) {
+    /**
+     * Re-exports the `register_element` helper for registering custom elements.
+     */
     Elements.register_element = _register_element;
     // Get by id.
     // @note: always use VElement as return type since this is most likely the case and avoids type casting for users.
-    /*  @docs:
-        @nav: Frontend
-        @chapter: Elements
-        @title: Get Element by ID
-        @desc: Get an element by its ID.
-        @param:
-            @name: id
-            @description The ID of the element.
-    */
+    /**
+     * Get an element by its ID.
+     * @nav Frontend
+     * @chapter Elements
+     * @param id The ID of the element.
+     * @docs
+     */
     function get(id) {
         const e = document.getElementById(id);
         if (e == null) {
@@ -31,29 +33,25 @@ export var Elements;
     Elements.get = get;
     // Get by id (alias).
     // @note: always use VElement as return type since this is most likely the case and avoids type casting for users.
-    /*  @docs:
-        @nav: Frontend
-        @chapter: Elements
-        @title: Get Element by ID (Alias)
-        @desc: Alias for `get` to get an element by its ID.
-        @param:
-            @name: id
-            @description The ID of the element.
-    */
+    /**
+     * Alias for `get` to retrieve an element by its ID.
+     * @nav Frontend
+     * @chapter Elements
+     * @param id The ID of the element.
+     * @docs
+     */
     function get_by_id(id) {
         return Elements.get(id);
     }
     Elements.get_by_id = get_by_id;
     // Click an element by id.
-    /*  @docs:
-        @nav: Frontend
-        @chapter: Elements
-        @title: Click Element by ID
-        @desc: Programmatically clicks an element by its ID.
-        @param:
-            @name: id
-            @description The ID of the element.
-    */
+    /**
+     * Programmatically clicks an element by its ID.
+     * @nav Frontend
+     * @chapter Elements
+     * @param id The ID of the element.
+     * @docs
+     */
     function click(id) {
         const element = document.getElementById(id);
         if (element) {
@@ -131,8 +129,14 @@ export var Elements;
     //         customElements.define(new_xml_name, any_con, { extends: ext });
     //     }
     // }
+    /**
+     * Re-exported constructor wrapper from the base module.
+     */
     // Create a constructor wrapper.
     Elements.wrapper = _wrapper;
+    /**
+     * Shared null element mainly for TypeScript typing convenience.
+     */
     // Create a shared null element mainly for typescript types.
     Elements.create_null = _create_null;
     // Submit multiple elements by id or element.
@@ -140,16 +144,14 @@ export var Elements;
     // When an input is not required, no errors will be thrown.
     // An object will be returned with each input's id as the key and the input's value as value.
     // Only supported extended input elements like `ExtendedInput`.
-    /*  @docs:
-        @nav: Frontend
-        @chapter: Elements
-        @title: Submit Elements
-        @desc: Submits multiple elements by ID or reference.
-        @deprecated: true
-        @param:
-            @name: elements
-            @description A list of element IDs or element references to submit.
-    */
+    /**
+     * Submits multiple elements by ID or reference.
+     * @nav Frontend
+     * @chapter Elements
+     * @deprecated
+     * @param elements A list of element IDs or element references to submit.
+     * @docs
+     */
     function submit(...elements) {
         const params = {};
         let error;
@@ -182,18 +184,14 @@ export var Elements;
     Elements.submit = submit;
     // Forward a function to a child so a user can easily create functions on the parent like border_radius() which actually set the border radius of a child.
     // The new function still returns `this`.
-    /*  @docs:
-        @nav: Frontend
-        @chapter: Elements
-        @title: Forward Function to Child
-        @desc: Forwards a function to a child element.
-        @param:
-            @name: func_name
-            @description The name of the function to forward.
-        @param:
-            @name: child
-            @description The child element or a function that returns the child element.
-    */
+    /**
+     * Forwards a function to a child element.
+     * @nav Frontend
+     * @chapter Elements
+     * @param func_name The name of the function to forward.
+     * @param child The child element or a function that returns the child element.
+     * @docs
+     */
     function forward_func_to_child(func_name, child) {
         return function (val) {
             if (typeof child === "function") {
@@ -208,6 +206,9 @@ export var Elements;
     }
     Elements.forward_func_to_child = forward_func_to_child;
     // Update the extend_velement function to use proper types
+    /**
+     * Typed re-export of `extend` to augment a `VElement` with additional helpers.
+     */
     Elements.extend = extend_velement;
     // Create.
     // export const create = create_velement;

package/frontend/dist/frontend/src/elements/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved.
+ */
+/** Null / undefined alias. */
+export type None = undefined | null;
+/**
+ * Return type helper for common VElement methods.
+ * Resolving the return type to `This` if `V` is `undefined,
+ * or to `R` if no value is passed and `V` is undefined.
+ */
+export type ValueOrThis<V, R, This> = V extends undefined ? R : This;
+/** Options for configuring a border through {@link VElement.border}. */
+export interface BorderOpts {
+    /** Default color. */
+    color?: string;
+    /**
+     *  Border width.
+     * @default 1px
+     */
+    width?: string | number;
+    /**
+     * Border style.
+     * @default "solid"
+     */
+    style?: string;
+    /**
+     * Border radius.
+     * @default 0
+     */
+    radius?: string | number;
+    /**
+     * Top border enabled or a specific color for this border.
+     * @default true
+     */
+    top?: boolean | string;
+    /**
+     * Bottom border enabled or a specific color for this border.
+     * @default true
+     */
+    bottom?: boolean | string;
+    /**
+     * Left border enabled or a specific color for this border.
+     * @default true
+     */
+    left?: boolean | string;
+    /**
+     * Right border enabled or a specific color for this border.
+     * @default true
+     */
+    right?: boolean | string;
+}

package/frontend/dist/frontend/src/elements/types.js

@@ -0,0 +1,5 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved.
+ */
+export {};

package/frontend/dist/frontend/src/modules/attachment.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @author ...
+ * @copyright ...
+ */
+import { AnyElement } from "src/volt.js";
+import { Compression } from "./compression.js";
+import type { Mail } from "../../../backend/src/plugins/mail/mail.js";
+/** A file attachment with an internal byte buffer and compression/encoding helpers. */
+export declare class Attachment {
+    /** File or directory name. */
+    name: string;
+    /** Path relative to the dropped root. */
+    path: string;
+    /** MIME type of the data. */
+    mime_type: string;
+    /** Charset used for text decoding (if applicable). */
+    charset?: string;
+    /** Whether the internal buffer is gzip-compressed. */
+    compressed: boolean;
+    /** Optional original File/Blob source. */
+    file?: File | Blob;
+    /** Internal raw buffer (compressed or not depending on state). */
+    private _bytes;
+    /** Create an Attachment from initial metadata and/or bytes. */
+    constructor(init: Attachment.Opts);
+    /** Current size of the internal buffer in bytes (compressed if flagged). */
+    get size(): number;
+    /** Get a copy of the internal buffer (leave compression state unchanged). */
+    bytes(): Uint8Array;
+    /** Replace the internal buffer (optionally update compression flag). */
+    set_bytes(bytes: Compression.BytesLike, compressed?: boolean): this;
+    /** Ensure the buffer is gzip-compressed (noop if already compressed). */
+    compress(options?: Compression.GzipOptions): this;
+    /** Ensure the buffer is uncompressed (noop if already uncompressed). */
+    decompress(): this;
+    /** Return Base64 of the current buffer (compressed or not). */
+    to_base64({ url_safe }?: {
+        url_safe?: boolean;
+    }): string;
+    /**
+     * Return a string view of the data using a charset.
+     * @param decompress Whether to decompress first if compressed. Default true.
+     * @param encoding Charset label; defaults to this.charset or "utf-8".
+     */
+    to_string(decompress?: boolean, encoding?: string): string;
+    /**
+     * Parse JSON from the data.
+     * @param decompress Whether to decompress first if compressed. Default true.
+     */
+    to_json<T = unknown>(decompress?: boolean): T;
+    /**
+     * Convert this attachment to a backend REST API attachment payload.
+     *
+     * This returns an object compatible with the server's `Mail.Attachment.RestAPI`
+     * shape using either:
+     *  - `{ content, encoding }` (default; embeds the payload), or
+     *  - `{ url }` (streams from an http(s)/data URL).
+     *
+     * @param opts Conversion options.
+     * @param opts.encoding Output string encoding for `content`. Defaults to `"base64"`.
+     *                      Supported: `"base64" | "hex" | "utf8"`.
+     *                      Use `"utf8"` only for textual data.
+     * @param opts.decompress Whether to decompress before encoding. Defaults to `true`.
+     * @param opts.url Optional http(s) or data: URL. When provided, `content`/`encoding`
+     *                 are omitted and the server will stream from this URL.
+     *
+     * @returns A REST API attachment payload with metadata plus either `{ content, encoding }` or `{ url }`.
+     */
+    to_rest_api(opts?: {
+        encoding?: "base64" | "hex" | "utf8";
+        decompress?: boolean;
+        url?: string;
+    }): Mail.Attachment.RestAPI;
+    /** Clone the attachment, including bytes and metadata. */
+    clone(): Attachment;
+}
+export declare namespace Attachment {
+    /** Options for constructing an Attachment. */
+    interface Opts {
+        /** File or directory name. */
+        name: string;
+        /** Path relative to the dropped root (if available). */
+        path?: string;
+        /** MIME type of the data. */
+        mime_type?: string;
+        /** Charset used for text decoding (if applicable). */
+        charset?: string;
+        /** Initial bytes to load into the attachment. */
+        bytes?: Compression.BytesLike;
+        /** Original File/Blob (if created from user drop). */
+        file?: File | Blob;
+        /** Whether bytes are already gzip-compressed. */
+        compressed?: boolean;
+    }
+    /** Create an Attachment from a Blob/File; optionally read and compress. */
+    function from_blob(blob: Blob | File, opts?: {
+        name?: string;
+        read?: boolean;
+        compress?: boolean;
+        charset?: string | "auto";
+    }): Promise<Attachment>;
+    /** Parameters for the {@link on_drop} handler. */
+    interface OnDropOpts {
+        /** Callback invoked per created attachment (files only). */
+        callback: (attachment: Attachment) => any;
+        /** Whether to read bytes immediately. Default true. */
+        read?: boolean;
+        /** Whether to gzip after reading. Default false. */
+        compress?: boolean;
+        /** Max uncompressed size per file (-1 disables). Default 50MB. */
+        max_size?: number;
+        /** Max cumulative uncompressed size (-1 disables). Default 50MB. */
+        total_max_size?: number;
+        /** Called at drag start. */
+        on_start?: (event: DragEvent) => any;
+        /** Called at drag end. */
+        on_stop?: (event: DragEvent) => any;
+        /** Error callback. */
+        on_error?: (error: Error) => any;
+    }
+    /**
+     * Handle drag/drop; recursively traverses directories and adds only files.
+     * Uses FS Access API when available, falls back to WebKit entries, otherwise flat files only.
+     */
+    function on_drop(node: AnyElement, sink: Attachment[], opts: OnDropOpts): void;
+}