@visulima/ansi 4.0.0-alpha.12 → 4.0.0-alpha.14

package/dist/iterm2.d.ts

@@ -1,58 +1,285 @@
-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 ; <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;
+import { LiteralUnion } from 'type-fest';
+/**
+* Represents the special string value `'auto'` used for iTerm2 image or file dimensions.
+* When `'auto'` is used for width or height, the terminal (iTerm2) determines the appropriate dimension
+* based on the image's inherent size or other context.
+* @example `width: IT2_AUTO`
+*/
+declare const IT2_AUTO: string;
+/**
+* Formats a number as a string representing a dimension in character cells for iTerm2.
+* iTerm2 interprets plain numbers for width/height as character cell counts.
+* @param n The number of character cells.
+* @returns A string representation of the number (e.g., `10` becomes `"10"`).
+* @example
+* ```typescript
+* const widthInCells = it2Cells(20); // "20"
+* const sequence = `File=width=${widthInCells}`;
+* ```
+*/
+declare const it2Cells: (n: number) => string;
+/**
+* Formats a number as a string representing a dimension in pixels for iTerm2.
+* Appends `px` to the number.
+* @param n The number of pixels.
+* @returns A string representing the dimension in pixels (e.g., `100` becomes `"100px"`).
+* @example
+* ```typescript
+* const heightInPixels = it2Pixels(150);
+* const sequence = `File=height=${heightInPixels}`;
+* ```
+*/
+declare const it2Pixels: (n: number) => string;
+/**
+* Formats a number as a string representing a dimension as a percentage for iTerm2.
+* Appends `%` to the number.
+* @param n The percentage value (e.g., `50` for 50%).
+* @returns A string representing the dimension as a percentage (e.g., `50` becomes `"50%"`).
+* @example
+* ```typescript
+* const widthAsPercentage = it2Percent(75);
+* const sequence = `File=width=${widthAsPercentage}`;
+* ```
+*/
+declare const it2Percent: (n: number) => string;
+/**
+* Defines the interface for any iTerm2 OSC 1337 payload object.
+*
+* An OSC 1337 sequence has the general form: `OSC 1337 ; <payload_string> BEL`.
+* Objects implementing this interface are responsible for generating that `<payload_string>`
+* via their `toString()` method. This allows for a structured way to build various iTerm2 commands.
+* @see `iTerm2` function in `iterm2.ts` which consumes objects of this type.
+*/
+interface IITerm2Payload {
+  /**
+  * Converts the payload object into its specific string representation required for an iTerm2 OSC 1337 command.
+  * For example, for a file transfer, this might return `"File=name=...;size=...:content..."`.
+  * @returns The string payload part of the OSC 1337 sequence.
+  */
+  toString: () => string;
+}
+/**
+* Defines the properties for an iTerm2 file transfer or inline image display command (`File=...`).
+* These correspond to the key-value pairs used within the `File=` argument of the OSC 1337 sequence.
+* @see {@link https://iterm2.com/documentation-escape-codes.html} iTerm2 Escape Codes (search for `File=`)
+* @see {@link https://iterm2.com/documentation-images.html} iTerm2 Inline Images Protocol
+*/
+interface ITerm2FileProperties {
+  /**
+  * The Base64 encoded content of the file or image.
+  * This is typically used when `inline=1` is set for images, or for transferring small files directly
+  * within the escape sequence. For larger files, multipart transfer is recommended.
+  * @remarks The `ITerm2File` class can handle the Base64 encoding of `Uint8Array` data automatically.
+  */
+  content?: string;
+  /**
+  * If `true`, instructs the terminal not to move the cursor after displaying an inline image.
+  * Corresponds to `doNotMoveCursor=1` in the sequence.
+  * This is a WezTerm extension, also supported by iTerm2 beta/nightly builds as of some versions.
+  * @default false (cursor behavior is default terminal behavior)
+  */
+  doNotMoveCursor?: boolean;
+  /**
+  * The display height of the image or file placeholder.
+  * Can be:
+  * - A number (interpreted as character cells, e.g., `10`).
+  * - A string with units: `"Npx"` (N pixels), `"N%"` (N percent of session height).
+  * - The string {@link IT2_AUTO} (`"auto"`) for automatic sizing.
+  * Use helper functions like {@link it2Cells}, {@link it2Pixels}, {@link it2Percent} for formatting if needed.
+  * @example `10`, `"100px"`, `"50%"`, `IT2_AUTO`
+  */
+  height?: LiteralUnion<typeof IT2_AUTO, number | string>;
+  /**
+  * Controls aspect ratio preservation for inline images.
+  * - If `true` (or omitted), the aspect ratio *is* preserved (`preserveAspectRatio=1`, which is the default iTerm2 behavior if the param is absent).
+  * - If `false`, the aspect ratio is *not* preserved, and the image may stretch (`preserveAspectRatio=0`).
+  * @remarks Note the slight inversion: this property `ignoreAspectRatio: true` means `preserveAspectRatio=0` in the sequence.
+  * The default iTerm2 behavior *is* to preserve aspect ratio if the `preserveAspectRatio` parameter is not given.
+  * So, to *not* preserve, you set this to true to *add* `preserveAspectRatio=0`.
+  * If you want to preserve (default), you can omit this or set it to `false`.
+  * @default false (meaning aspect ratio is preserved by iTerm2 default unless overridden)
+  */
+  ignoreAspectRatio?: boolean;
+  /**
+  * If `true`, the file (typically an image) should be displayed inline in the terminal.
+  * Corresponds to `inline=1` in the sequence.
+  * If `false` or omitted, iTerm2 might prompt for download or handle based on file type.
+  * @default false
+  */
+  inline?: boolean;
+  /**
+  * The name of the file. This is displayed in UI elements (like a download prompt or image info)
+  * and used as the default filename if downloaded.
+  * The name **must be Base64 encoded** if it contains special characters (like `;`, `=`, or non-ASCII characters)
+  * to ensure correct parsing of the escape sequence by iTerm2.
+  * The `ITerm2File` and `ITerm2MultipartFileStart` classes generally expect the name to be pre-encoded if necessary.
+  * @example `"bXlmaWxlLnR4dA=="` (Base64 for "myfile.txt")
+  */
+  name?: string;
+  /**
+  * The size of the file in bytes. This is used by iTerm2 for progress indication during downloads
+  * or to inform inline display mechanisms.
+  * JavaScript `number` type is generally sufficient for typical file sizes (up to `Number.MAX_SAFE_INTEGER`).
+  */
+  size?: number;
+  /**
+  * The display width of the image or file placeholder.
+  * Can be:
+  * - A number (interpreted as character cells, e.g., `20`).
+  * - A string with units: `"Npx"` (N pixels), `"N%"` (N percent of session width).
+  * - The string {@link IT2_AUTO} (`"auto"`) for automatic sizing.
+  * Use helper functions like {@link it2Cells}, {@link it2Pixels}, {@link it2Percent} for formatting if needed.
+  * @example `20`, `"200px"`, `"75%"`, `IT2_AUTO`
+  */
+  width?: LiteralUnion<typeof IT2_AUTO, number | string>;
+}
+/**
+* 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 ITerm2FileProperties} for property details.
+* @see `iTerm2` for the function that wraps this payload into a full escape sequence.
+*/
+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 ITerm2FileProperties}.
+  * 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.
+*/
+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.
+*/
+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 ITerm2FileProperties} for property details (omitting `content`).
+* @see {@link ITerm2FilePart} for sending file chunks.
+* @see {@link ITerm2FileEnd} for finalizing the transfer.
+*/
+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;
+}
+/**
+* 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
+* ```
+*/
+declare const iTerm2: (payload: IITerm2Payload) => string;
+export { type IITerm2Payload, IT2_AUTO, ITerm2File, ITerm2FileEnd, ITerm2FilePart, type ITerm2FileProperties, ITerm2MultipartFileStart, iTerm2, it2Cells, it2Percent, it2Pixels };

package/dist/iterm2.js

@@ -1,12 +1 @@
-import { O as OSC, B as BEL } from './packem_shared/constants-CE7WkXh_.js';
-export { IT2_AUTO, it2Cells, it2Percent, it2Pixels } from './packem_shared/IT2_AUTO-DyYWsxno.js';
-export { ITerm2File, ITerm2FileEnd, ITerm2FilePart, ITerm2MultipartFileStart } from './packem_shared/ITerm2File-CUZDBk99.js';
-
-const iTerm2 = (payload) => {
-  if (payload.toString === Object.prototype.toString) {
-    throw new Error("Invalid payload: must implement IITerm2Payload with a custom toString method");
-  }
-  return `${OSC}1337;${payload.toString()}${BEL}`;
-};
-
-export { iTerm2 };
+var i=Object.defineProperty;var r=(t,e)=>i(t,"name",{value:e,configurable:!0});import{O as o,B as m}from"./packem_shared/constants-D12jy2Zh.js";import{IT2_AUTO as u,it2Cells as c,it2Percent as d,it2Pixels as f}from"./packem_shared/IT2_AUTO-OiB8EaxU.js";import{ITerm2File as g,ITerm2FileEnd as O,ITerm2FilePart as P,ITerm2MultipartFileStart as v}from"./packem_shared/ITerm2File-XoC8RMzs.js";var a=Object.defineProperty,l=r((t,e)=>a(t,"name",{value:e,configurable:!0}),"e");const T=l(t=>{if(t.toString===Object.prototype.toString)throw new Error("Invalid payload: must implement IITerm2Payload with a custom toString method");return`${o}1337;${t.toString()}${m}`},"iTerm2");export{u as IT2_AUTO,g as ITerm2File,O as ITerm2FileEnd,P as ITerm2FilePart,v as ITerm2MultipartFileStart,T as iTerm2,c as it2Cells,d as it2Percent,f as it2Pixels};