@visulima/ansi 3.0.2 → 3.0.4

package/dist/iterm2/iterm2-sequences.d.ts

@@ -0,0 +1,96 @@
+import type { IITerm2Payload, ITerm2FileProperties } from "./iterm2-properties.d.ts";
+/**
+ * Represents the payload for a complete iTerm2 file transfer or an inline image display command.
+ * This class is used to construct the part of the OSC 1337 sequence that follows `File=`.
+ * The generated payload can be either:
+ * - `File=[PROPERTIES]:[BASE64_CONTENT]` (for inline content)
+ * - `File=[PROPERTIES]` (if content is not provided directly, e.g., for a download announcement)
+ *
+ * Implements {@link IITerm2Payload} for use with the generic `iTerm2` function.
+ * @see {@link ITerm2FileProps} for property details.
+ * @see {@link iTerm2} for the function that wraps this payload into a full escape sequence.
+ */
+export declare class ITerm2File implements IITerm2Payload {
+    private readonly fileProps;
+    /**
+     * Constructs an `ITerm2File` payload object.
+     * @param properties An object containing properties for the file/image, as defined by {@link ITerm2FileProps}.
+     * The `name` property within `props` should be pre-Base64 encoded by the caller if it might
+     * contain special characters (like `;`, `=`, or non-ASCII characters).
+     * If `fileData` is provided, `props.content` will be overridden, and `props.size` will be
+     * set from `fileData.byteLength` if not already present in `props`.
+     * @param fileData (Optional) A `Uint8Array` containing the raw file data. If provided, this data will be
+     * Base64 encoded and used as the `content` of the file transfer. The `size` property
+     * will also be automatically set from `fileData.byteLength` if not specified in `props`.
+     */
+    constructor(properties: ITerm2FileProperties, fileData?: Uint8Array);
+    /**
+     * Converts the file properties and its content (if any) into the string payload
+     * suitable for the iTerm2 `File=` command.
+     * @returns The string payload (e.g., `"File=name=...;size=...:BASE64_CONTENT"` or `"File=name=...;size=..."`).
+     */
+    toString(): string;
+}
+/**
+ * Represents the payload for ending an iTerm2 multipart file transfer.
+ * This class is used to construct the part of the OSC 1337 sequence that is simply `FileEnd`.
+ *
+ * Implements {@link IITerm2Payload} for use with the generic `iTerm2` function.
+ * @see {@link ITerm2MultipartFileStart} to initiate the transfer.
+ * @see {@link ITerm2FilePart} for sending file chunks.
+ */
+export declare class ITerm2FileEnd implements IITerm2Payload {
+    /**
+     * Generates the string payload for the iTerm2 `FileEnd` command.
+     * @returns The string `"FileEnd"`.
+     */
+    toString(): string;
+}
+/**
+ * Represents the payload for a part (chunk) of an iTerm2 multipart file transfer.
+ * This class is used to construct the part of the OSC 1337 sequence that follows `FilePart=`.
+ * The provided chunk must already be Base64 encoded.
+ *
+ * Implements {@link IITerm2Payload} for use with the generic `iTerm2` function.
+ * @see {@link ITerm2MultipartFileStart} to initiate the transfer.
+ * @see {@link ITerm2FileEnd} to finalize the transfer.
+ */
+export declare class ITerm2FilePart implements IITerm2Payload {
+    private readonly base64Chunk;
+    /**
+     * Constructs an `ITerm2FilePart` payload object.
+     * @param base64Chunk A string containing a Base64 encoded chunk of the file data.
+     * The caller is responsible for chunking the file and Base64 encoding each chunk.
+     */
+    constructor(base64Chunk: string);
+    /**
+     * Converts the Base64 encoded chunk into the string payload suitable for the iTerm2 `FilePart=` command.
+     * @returns The string payload (e.g., `"FilePart=U09NRURBVEE="`).
+     */
+    toString(): string;
+}
+/**
+ * Represents the payload for starting an iTerm2 multipart file transfer.
+ * This class is used to construct the part of the OSC 1337 sequence that follows `MultipartFile=`.
+ * This command initiates a transfer; the actual file data is sent in subsequent `FilePart` commands.
+ *
+ * Implements {@link IITerm2Payload} for use with the generic `iTerm2` function.
+ * @see {@link ITerm2FileProps} for property details (omitting `content`).
+ * @see {@link ITerm2FilePart} for sending file chunks.
+ * @see {@link ITerm2FileEnd} for finalizing the transfer.
+ */
+export declare class ITerm2MultipartFileStart implements IITerm2Payload {
+    private readonly properties;
+    /**
+     * Constructs an `ITerm2MultipartFileStart` payload object.
+     * @param properties Properties for the multipart file (e.g., `name`, `size`). Content is not part of this command.
+     * The `name` property within `props` should be pre-Base64 encoded by the caller if it might
+     * contain special characters.
+     */
+    constructor(properties: Omit<ITerm2FileProperties, "content">);
+    /**
+     * Converts the file properties into the string payload suitable for the iTerm2 `MultipartFile=` command.
+     * @returns The string payload (e.g., `"MultipartFile=name=...;size=..."`).
+     */
+    toString(): string;
+}

package/dist/iterm2.d.ts

@@ -1,43 +1,58 @@
-import { LiteralUnion } from 'type-fest';
-
-declare const IT2_AUTO: string;
-declare const it2Cells: (n: number) => string;
-declare const it2Pixels: (n: number) => string;
-declare const it2Percent: (n: number) => string;
-interface IITerm2Payload {
-    toString: () => string;
-}
-interface ITerm2FileProperties {
-    content?: string;
-    doNotMoveCursor?: boolean;
-    height?: LiteralUnion<typeof IT2_AUTO, number | string>;
-    ignoreAspectRatio?: boolean;
-    inline?: boolean;
-    name?: string;
-    size?: number;
-    width?: LiteralUnion<typeof IT2_AUTO, number | string>;
-}
-
-declare class ITerm2File implements IITerm2Payload {
-    private readonly fileProps;
-    constructor(properties: ITerm2FileProperties, fileData?: Uint8Array);
-    toString(): string;
-}
-declare class ITerm2FileEnd implements IITerm2Payload {
-    toString(): string;
-}
-declare class ITerm2FilePart implements IITerm2Payload {
-    private readonly base64Chunk;
-    constructor(base64Chunk: string);
-    toString(): string;
-}
-declare class ITerm2MultipartFileStart implements IITerm2Payload {
-    private readonly properties;
-    constructor(properties: Omit<ITerm2FileProperties, "content">);
-    toString(): string;
-}
-
-declare const iTerm2: (payload: IITerm2Payload) => string;
-
-export { IT2_AUTO, ITerm2File, ITerm2FileEnd, ITerm2FilePart, ITerm2MultipartFileStart, iTerm2, it2Cells, it2Percent, it2Pixels };
-export type { IITerm2Payload, ITerm2FileProperties };
+import type { IITerm2Payload } from './iterm2/iterm2-properties.d.ts';
+export type { IITerm2Payload, ITerm2FileProperties } from './iterm2/iterm2-properties.d.ts';
+export { IT2_AUTO, it2Cells, it2Percent, it2Pixels } from './iterm2/iterm2-properties.d.ts';
+export { ITerm2File, ITerm2FileEnd, ITerm2FilePart, ITerm2MultipartFileStart } from './iterm2/iterm2-sequences.d.ts';
+/**
+ * Generates a complete iTerm2 proprietary escape sequence (OSC 1337).
+ *
+ * This function serves as a general-purpose constructor for iTerm2 escape codes.
+ * It takes a payload object that conforms to the {@link IITerm2Payload} interface.
+ * The `toString()` method of this payload object is responsible for generating the
+ * specific command and arguments part of the sequence (e.g., `File=...`, `ShellIntegrationVersion=...`).
+ *
+ * The overall structure of the generated sequence is: `OSC 1337 ; &lt;PAYLOAD_STRING> BEL`
+ * (`OSC` is `\x1b]`, `BEL` is `\x07`).
+ * @param payload An object that implements the {@link IITerm2Payload} interface.
+ * This object must have a `toString()` method that returns the string representation
+ * of the iTerm2 command-specific payload.
+ * Examples include instances of `ITerm2File`, `ITerm2MultipartFileStart`, etc.
+ * @returns The fully formed ANSI escape sequence for the iTerm2 command.
+ * Returns an empty string if the provided `payload` is invalid (e.g., null, undefined,
+ * lacks a proper `toString` method, or its `toString` method is the generic `Object.prototype.toString`).
+ * @see {@link https://iterm2.com/documentation-escape-codes.html iTerm2 Escape Codes Documentation}
+ * for a comprehensive list of supported commands and their payloads.
+ * @see {@link IITerm2Payload} for the interface requirement.
+ * @see Classes like {@link ITerm2File}, {@link ITerm2MultipartFileStart}, {@link ITerm2FilePart}, {@link ITerm2FileEnd}
+ * for concrete examples of payload objects.
+ * @example
+ * ```typescript
+ * import { iTerm2, ITerm2File, ITerm2FileProps } from '@visulima/ansi/iterm2'; // ITerm2FileProps can be used for options
+ * import { Buffer } from 'node:buffer';
+ *
+ * // Example 1: Sending a file inline (like an image)
+ * const imageName = "my_image.png";
+ * const imageData = Buffer.from("dummyimagecontent"); // Replace with actual Uint8Array image data
+ * const imageFileProps: ITerm2FileProps = { // Use ITerm2FileProps for broader options
+ *   name: Buffer.from(imageName).toString("base64"), // Name should be base64 encoded
+ *   inline: true,
+ *   width: "50%",
+ *   height: "auto",
+ *   ignoreAspectRatio: false, // Equivalent to preserveAspectRatio: true
+ * };
+ * const filePayload = new ITerm2File(imageFileProps, imageData);
+ * const imageSequence = iTerm2(filePayload);
+ * console.log(imageSequence);
+ * // Expected output (simplified, actual base64 will be longer):
+ * // OSC1337;File=name=bXlfaW1hZ2UucG5n;inline=1;width=50%;height=auto:ZHVtbXlpbWFnZWNvbnRlbnQ=BEL
+ * // Note: if ignoreAspectRatio was true, preserveAspectRatio=0 would be in the sequence.
+ *
+ * // Example 2: A hypothetical simple command (e.g., shell integration handshake)
+ * const shellIntegrationPayload: IITerm2Payload = {
+ *   toString: () => "ShellIntegrationVersion=15;Shell=zsh"
+ * };
+ * const shellSequence = iTerm2(shellIntegrationPayload);
+ * console.log(shellSequence);
+ * // Output: OSC1337;ShellIntegrationVersion=15;Shell=zshBEL
+ * ```
+ */
+export declare const iTerm2: (payload: IITerm2Payload) => string;