@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/text/TextRun.d.ts

@@ -0,0 +1,85 @@
+import { Bounds } from '@sheetxl/utils';
+import { IText } from './IText';
+import { TextVisitor } from './TextVisitor';
+/**
+ * Represents a contiguous span of characters within a text frame that share the same formatting.
+ */
+export interface ITextRun {
+    /**
+     * The actual text content of the run.
+     */
+    readonly text: string;
+    /**
+     * The font name applied to the text run.
+     * If not specified, it inherits the font name from its parent paragraph.
+     */
+    readonly fontName: string;
+    /**
+     * The font size applied to the text run.
+     * If not specified, it inherits the font size from its parent paragraph.
+     */
+    readonly fontSize: number;
+    /**
+     * Indicates whether the text is bold.
+     */
+    readonly bold: boolean;
+    /**
+     * Indicates whether the text is italicized.
+     */
+    readonly italic: boolean;
+    readonly superSub: boolean;
+    /**
+     * Specifies the additional spacing between characters (in ems).
+     */
+    readonly letterSpacing: number;
+    /**
+     * Specifies the minimum font size (in points) at which character kerning will be applied.
+     * If omitted, kerning will be applied for all font sizes down to 0 points.
+     */
+    readonly kerningMin: number;
+    /**
+     * Specifies the capitalization style to be applied to the text during layout and rendering.
+     * This does not affect the actual stored text content.
+     */
+    readonly smallCaps: IText.SmallCaps;
+    /**
+     * Vertical offset of the text (as a percentage of font height),
+     * shifting it up (positive values) or down (negative values).
+     * This does not affect the line height.
+     */
+    readonly offset: number;
+    /**
+     * Specifies the strikethrough style applied to the text.
+     */
+    readonly strikeStyle: IText.StrikeStyle;
+}
+export interface PlacedTextRun extends ITextRun {
+    /**
+     * Bounds is not copied during clone.
+     */
+    readonly bounds?: Bounds;
+}
+export interface CloneableTextRun extends ITextRun {
+    clone(visitor?: TextVisitor): ITextRun;
+    equals(other: TextVisitor): boolean;
+}
+export declare class DefaultTextRun implements ITextRun, PlacedTextRun, CloneableTextRun {
+    private _private;
+    private _bounds?;
+    constructor(overrides: Partial<ITextRun>, bounds?: Bounds | null);
+    clone(visitor?: TextVisitor): ITextRun;
+    equals(other: TextVisitor): boolean;
+    get bounds(): Bounds | undefined;
+    get text(): string;
+    get fontName(): string;
+    get bold(): boolean;
+    get italic(): boolean;
+    get fontSize(): number;
+    get superSub(): boolean;
+    get letterSpacing(): number;
+    get kerningMin(): number;
+    get smallCaps(): IText.SmallCaps;
+    get offset(): number;
+    get strikeStyle(): IText.StrikeStyle;
+}
+//# sourceMappingURL=TextRun.d.ts.map

package/types/src/text/TextUtils.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Will try to find a valid text value from a template by incrementing a last number.
+ *
+ * @param template The string to use for a baseline for generating new text values.
+ * @param isValidName A callback for validating the current text.
+ * @returns A string for the first valid text.
+ */
+export declare function findValidTextValue(template: string, isValidName: (candidate: string) => boolean, maxIncrement?: number): string;
+/**
+ * Capitalizes the first character of a string and optionally lowercases the rest of the string.
+ *
+ * @param str The input string to be processed.
+ * @param lowerCaseRest A boolean flag indicating whether to convert the rest of the string to lowercase.
+ *                         If `true`, the remaining characters (after the first) will be converted to lowercase.
+ *                         If `false`, the remaining characters will remain unchanged.
+ *
+ * @returns A new string with the first character capitalized and the rest lowercased if the `lowerCaseRest` flag is `true`.
+ *          If the `lowerCaseRest` flag is `false`, only the first character is capitalized, and the rest of the string remains unchanged.
+ *
+ * @example
+ * ```
+ * capitalize("hello");           // Returns "Hello"
+ * capitalize("hello", true);     // Returns "Hello"
+ * capitalize("HELLO", true);     // Returns "Hello"
+ * capitalize("123abc", true);    // Returns "123abc"
+ * capitalize("", true);          // Returns ""
+ * ```
+ */
+export declare function capitalize(str: string, lowerCaseRest?: boolean): string;
+/**
+ * Extracts the file extension from a file path.
+ *
+ * @param path The file path from which to extract the file extension.
+ *
+ * @returns The file extension in lowercase. Returns an empty string if the path is invalid or has no extension.
+ *
+ * @example
+ * ```
+ * getFileNameExtension("example.txt");       // Returns "txt"
+ * getFileNameExtension("/path/to/file.jpg"); // Returns "jpg"
+ * getFileNameExtension("no_extension");      // Returns ""
+ * getFileNameExtension("");                  // Returns ""
+ * ```
+ */
+export declare function getFileNameExtension(path: string): string;
+/**
+ * Extracts the base name (file name without extension) from a file path.
+ *
+ * @param path The file path from which to extract the base name.
+ * @param shouldCapitalize A boolean flag indicating whether to capitalize the base name. Defaults to `false`.
+ *
+ * @returns The base name of the file. The base name will be capitalized if `shouldCapitalize` is `true`.
+ *
+ * @example
+ * ```
+ * getBaseName("example.txt");       // Returns "Example"
+ * getBaseName("/path/to/file.jpg"); // Returns "File"
+ * getBaseName("file_without_extension", false); // Returns "file_without_extension"
+ * getBaseName("", false);          // Returns ""
+ * ```
+ */
+export declare function getBaseName(path: string, shouldCapitalize?: boolean): string;
+/**
+ * Converts a snake_case or kebab-case string to camelCase.
+ *
+ * @param str The snake_case or kebab-case string to convert.
+ * @returns The string converted to camelCase.
+ *
+ * @example
+ * ```ts
+ * snakeToCamel('snake_case_string'); // Returns 'snakeCaseString'
+ * snakeToCamel('kebab-case-string'); // Returns 'kebabCaseString'
+ * ```
+ */
+export declare function snakeToCamel(str: string): string;
+/**
+ * Converts a camelCase string to snake_case.
+ *
+ * @param str The camelCase string to convert.
+ * @returns The string converted to snake_case.
+ *
+ * @example
+ * ```ts
+ * camelToSnake('camelCaseString'); // Returns 'camel_case_string'
+ * ```
+ */
+export declare function camelToSnake(str: string): string;
+/**
+ * Trims a string to a specified maximum length and adds an ellipsis (`…`) if the string exceeds the limit.
+ *
+ * @param str The string to trim.
+ * @param maxLength The maximum length of the string before truncation (default is 36).
+ * @returns The truncated string with an ellipsis if it exceeds the specified length.
+ *
+ * @example
+ * ```ts
+ * clampString('This is a long string', 10); // Returns 'This is a …'
+ * ```
+ */
+export declare function clampString(str: string, maxLength?: number): string;
+/**
+ * Counts the number of decimal places in a numeric string.
+ *
+ * @param input The string representation of a number.
+ * @returns The number of decimal places. Returns 0 if there are no decimal places.
+ *
+ * @example
+ * ```ts
+ * countDecimals('123.456'); // Returns 3
+ * countDecimals('123');     // Returns 0
+ * ```
+ */
+export declare function countDecimals(input: string): number;
+export declare const DefaultUnQuoteRegEx: RegExp;
+/**
+ * Checks if a string is enclosed in matching quotes.
+ *
+ * @param str The string to check.
+ * @returns `true` if the string is quoted with matching characters, `false` otherwise.
+ */
+export declare function isQuoted(str: string): boolean;
+/**
+ * Removes the enclosing quotes from a string.
+ *
+ * @param str The string to unquote.
+ * @returns The unquoted string.
+ */
+export declare function unquote(str: string): string;
+/**
+ * Encloses a string in the specified quote character.
+ *
+ * @param str The string to quote.
+ * @param char The quote character to use (default is a single quote `'`).
+ * @returns The quoted string.
+ */
+export declare function quote(str: string, char?: string): string;
+/**
+ * Splits a string by a delimiter, ignoring any quoted sections.
+ *
+ * @param str The string to split.
+ * @param delimiter The delimiter to split by (default is undefined).
+ * @param quote The quote character used to ignore splits inside quoted sections (default is undefined).
+ * @returns An array of strings split by the delimiter, ignoring quoted sections.
+ */
+export declare function splitUnquoted(str: string, delimiter?: string, quote?: string): string[];
+/**
+ * Validates if a string is a valid HTTP or HTTPS URL.
+ *
+ * @param value The string to check.
+ * @returns `true` if the string is a valid HTTP or HTTPS URL, `false` otherwise.
+ */
+export declare function isValidHttpUrl(value: string): boolean;
+/**
+ * Validates if a string is a valid email.
+ *
+ * @param text The string to check.
+ * @returns `true` if the string is a valid email, `false` otherwise.
+ */
+export declare function isValidEmail(text: string): boolean;
+/**
+ * Converts a number to alphabet.
+ * @param i The number to stringify
+ */
+export declare function numberToAlphabet(i: number): string;
+//# sourceMappingURL=TextUtils.d.ts.map

package/types/src/text/TextVisitor.d.ts

@@ -0,0 +1,11 @@
+import { ITextRun } from './TextRun';
+import { ITextParagraph } from './TextParagraph';
+import { ITextLine } from './TextLine';
+import { ITextFrame } from './ITextFrame';
+export interface TextVisitor {
+    visitTextRun?: (run: ITextRun, index: number, count: number) => Partial<ITextRun> | void;
+    visitTextParagraph?: (paragraph: ITextParagraph, index: number, count: number) => Partial<ITextParagraph> | void;
+    visitTextLine?: (line: ITextLine, index: number, count: number) => Partial<ITextLine> | void;
+    visitTextFrame?: (frame: ITextFrame) => Partial<ITextFrame> | void;
+}
+//# sourceMappingURL=TextVisitor.d.ts.map

package/types/src/text/TextWrapper.d.ts

@@ -0,0 +1,78 @@
+import { IFont } from '../font';
+/**
+ * Simple Text Line Wrapper. Is not useful for Rich Text (yet). see TextLayout.
+ */
+export interface TextWrapperOptions {
+    fontName: string;
+    fontSize: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    /**
+     * defaults to 0
+     */
+    letterSpacing?: number;
+    bold?: boolean;
+    italic?: boolean;
+    /**
+     * If the text is a superscript or a subscript.
+     * This affects the width but not the height of the line.
+     */
+    superSub?: boolean;
+    indent?: number;
+}
+export interface TextWrapperResults {
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        widthWhitespace: number;
+        height: number;
+    };
+    lines: Line[];
+}
+export interface Line {
+    text: string;
+    startPosition: number;
+    x: number;
+    y: number;
+    width: number;
+    widthWhitespace: number;
+    height: number;
+    baseline: number;
+}
+export interface onLine {
+    (line: Line): boolean | void;
+}
+export declare function linesToText(lines: Line[], trimTrailingSpace?: boolean): string;
+/**
+ * A simple text wrapper that uses a line breaker to break lines.
+ *
+ * *PERFORMANCE OPTIMIZATIONS*
+ * - Binary search for wordBreak
+ * - Reuse all of the objects. (this should support a reuse flag and it lines are not needed then they can also be internally reused)
+ * - Have text measure for collapsed text just calc the difference between the two (just trailing whitespace, is there kerning?)
+ */
+export declare class TextWrapper {
+    private _textMeasurer;
+    private _breaker;
+    private _lastBreak;
+    private _charactersRead;
+    private _linesRead;
+    private _maxXRead;
+    private _maxXWhitespaceRead;
+    private _maxYRead;
+    private _fontName;
+    private _fontSize;
+    private _metricOptions;
+    private _indent;
+    private _isSuperSub;
+    private _ellipsis;
+    private _maxWidth;
+    private _maxHeight;
+    constructor(textMeasurer: IFont.Measurer);
+    private _measureText;
+    private _breakWord;
+    private _breakWhiteSpace;
+    wrap(text: string, options?: TextWrapperOptions | null): TextWrapperResults;
+}
+//# sourceMappingURL=TextWrapper.d.ts.map

package/types/src/text/_TextUtils.d.ts

@@ -0,0 +1,90 @@
+import { Size } from '@sheetxl/utils';
+import { IFont } from '../font';
+import { ITextFrame } from './ITextFrame';
+import { ITextBoxAlignment } from './TextBoxAlignment';
+import { IStyledFont } from './richtext/IStyledFont';
+/**
+ * This 'places' text which means that using all of the formatting rules it assign's locations and bounds to
+ * all of the characters. It does not however actually render them. See @renderTextFrame for rendering.
+ *
+ * @param textFrame
+ * @param dimensions
+ * @param textMeasurer This defaults to a canvas context
+ */
+export declare function layoutTextFrame(textFrame: ITextFrame, defaultFont: IStyledFont, alignment: ITextBoxAlignment, dimensions?: Partial<Size> | null, textMeasurer?: IFont.Measurer): ITextFrame;
+/**
+ * Checks whether a string is entirely uppercase, lowercase, or mixed case.
+ *
+ * @param str The input string to be evaluated.
+ * @returns `1` if the string is all uppercase, `-1` if the string is all lowercase, and `0` if the string contains both uppercase and lowercase characters.
+ *
+ * @example
+ * ```
+ * checkCase("HELLO");  // Returns 1
+ * checkCase("hello");  // Returns -1
+ * checkCase("Hello");  // Returns 0
+ * ```
+ */
+export declare function detectCapitalize(str: string): number;
+/**
+ * Analyzes the casing of each character in the string and returns an array of numbers.
+ *
+ * @param str The input string to be evaluated.
+ * @returns An array of numbers where:
+ * - `1` indicates that the character is uppercase.
+ * - `-1` indicates that the character is lowercase.
+ * - `0` indicates that the character is non-alphabetic.
+ *
+ * @example
+ * ```
+ * analyzeCase("Hello123");  // Returns [1, -1, -1, -1, -1, 0, 0, 0]
+ * analyzeCase("ALL_CAPS");  // Returns [1, 1, 1, 0, 1, 1, 1, 1]
+ * analyzeCase("lowercase"); // Returns [-1, -1, -1, -1, -1, -1, -1, -1, -1]
+ * ```
+ */
+export declare function analyzeCase(str: string): readonly number[];
+/**
+ * Converts a given string to match the casing specified by an array of numbers.
+ *
+ * @param str The input string to be converted.
+ * @param caseArray An array of numbers representing the desired casing for each character.
+ * - `1` indicates that the character should be uppercase.
+ * - `-1` indicates that the character should be lowercase.
+ * - `0` indicates that the character should remain unchanged.
+ *
+ * @returns A new string with characters converted to match the specified casing.
+ *
+ * @example
+ * ```
+ * const original = "Hello123";
+ * const caseArray = analyzeCase(original); // [1, -1, -1, -1, -1, 0, 0, 0]
+ * convertCase("WORLD456", caseArray); // Returns "World456"
+ * ```
+ */
+/**
+ * Converts a given string to match the casing specified by an array of numbers.
+ *
+ * @param str The input string to be converted.
+ * @param caseArray An array of numbers representing the desired casing for each character.
+ * - `1` indicates that the character should be uppercase.
+ * - `-1` indicates that the character should be lowercase.
+ * - `0` indicates that the character should remain unchanged.
+ *
+ * @returns A new string with characters converted to match the specified casing.
+ *
+ * @example
+ * ```
+ * const original = "Hello123";
+ * const caseArray = analyzeCase(original); // [1, -1, -1, -1, -1, 0, 0, 0]
+ * convertCase("WORLD456", caseArray); // Returns "World456"
+ * ```
+ */
+export declare function convertCase(str: string, caseArray: readonly number[]): string;
+/**
+ * Create a simple text frame.
+ * TODO - Later we will make take frame take the style (and theme?) and have more operations on it.
+ * TODO - abstract CellStyle
+ * @internal
+ */
+export declare function createTextFrameFromText(text: string, defaultFont: IStyledFont, alignment: ITextBoxAlignment, allowWrap: boolean, disableCustomFormatting?: boolean): ITextFrame;
+//# sourceMappingURL=_TextUtils.d.ts.map

package/types/src/text/impl/Phrase.d.ts

@@ -0,0 +1,3 @@
+export declare class Phrase {
+}
+//# sourceMappingURL=Phrase.d.ts.map

package/types/src/text/impl/TabStrategy.d.ts

@@ -0,0 +1,9 @@
+import { ITextFrame } from '../ITextFrame';
+import { Phrase } from './Phrase';
+import { IFont } from '../../font';
+export interface TabStrategy {
+    width(x: number, xOffset: number, maxX: number, tabStop: ITextFrame.TabStop, phrase: Phrase, textMeasurer: IFont.Measurer): number;
+    yanks(): boolean;
+    shrinksToZero(): boolean;
+}
+//# sourceMappingURL=TabStrategy.d.ts.map

package/types/src/text/impl/WordWrapUtils.d.ts

@@ -0,0 +1,6 @@
+export declare class WordWrapUtils {
+    static NL: string;
+    static DefaultLineSpacing: number;
+    static DefaultTabWidth: number;
+}
+//# sourceMappingURL=WordWrapUtils.d.ts.map

package/types/src/text/index.d.ts

@@ -0,0 +1,7 @@
+export * from './IText';
+export * from './ITextFrame';
+export * from './richtext';
+export * from './TextBoxAlignment';
+export * as TextUtils from './TextUtils';
+export * as TextRotation from './TextRotation';
+//# sourceMappingURL=index.d.ts.map