@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.2

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

@@ -10,7 +10,7 @@ import { ITextBoxAlignment as _IAlignment } from './TextBoxAlignment';
  * A TextFrame allows precise control over the positioning, size (width and height),
  * layout, and appearance of text content.
  */
-export interface ITextFrame {
+export interface ITextFrame extends ITextFrame.IText {
     readonly wrapped: boolean;
     readonly insets: Rectangle;
     readonly orientation: ITextFrame.Orientation;
@@ -57,6 +57,8 @@ export interface ITextFrame {
      * @param allowWrap If `true` then will try to wrap on natural breaks. Defaults the the current settings.
      */
     createTextFrame(text: string, allowWrap?: boolean): ITextFrame;
+    /** For runtime type checking. */
+    readonly isITextFrame: true;
 }
 /**
  * {@inheritDoc ITextFrame}
@@ -66,6 +68,28 @@ export interface ITextFrame {
  * {@link ITextFrame}
  */
 export declare namespace ITextFrame {
+    /**
+     * The text of a frame, without its layout.
+     *
+     * @remarks
+     * What a frame can always answer, including one whose layout is not modeled — text on an
+     * imported shape is read this way.
+     */
+    interface IText {
+        /**
+         * Returns the frame's text with its formatting stripped.
+         *
+         * @remarks
+         * - Paragraphs are separated by `
+    `, and a line break inside a paragraph is also `
+    `.
+         * - Runs and fields are concatenated in document order.
+         * - Blank paragraphs at the start and end are dropped; blank paragraphs between text are kept.
+         * - An equation reads as its linear text form.
+         * - A frame with nothing written in it answers `''`.
+         */
+        getText(): string;
+    }
     namespace IAlignment {
         type Properties = _IAlignment.Properties;
         type JSON = _IAlignment.JSON;

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

@@ -61,24 +61,33 @@ export interface ITextBoxAlignment {
      */
     setOverflow(overflow: ITextFrame.Overflow | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
     /**
-     * Rotation of the text.
+     * Rotation of the text, in degrees `0…360` (counter-clockwise, as OOXML stores it).
      * @defaultValue 0
      */
     getRotation(): number;
     /**
-     * Sets the rotation
+     * Sets the rotation.
      *
-     * @param rotation The rotation
+     * @param rotation The rotation in degrees; negative values are normalized (`-45` is `315`).
+     *
+     * @remarks
+     * Rotation and {@link setStacked stacked} are one orientation setting: setting a rotation turns
+     * stacking off.
      */
     setRotation(rotation: number | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
     /**
-     * If the text should stack vertically instead of horizontally.
+     * If the text is stacked — every glyph upright, one below the other (Excel's "Vertical Text").
+     * @defaultValue false
      */
     getStacked(): boolean;
     /**
-     * Sets the stacked
+     * Sets whether the text is stacked.
      *
-     * @param stacked The stacked
+     * @param stacked `true` to stack the glyphs vertically.
+     *
+     * @remarks
+     * Stacked and {@link setRotation rotation} are one orientation setting: stacking clears any
+     * rotation.
      */
     setStacked(stacked: boolean | null, options?: IStyle.UpdateOptions): ITextBoxAlignment;
     /**

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

@@ -20,6 +20,8 @@ export declare class TextFrame {
     layout(size?: Partial<Size> | null): ITextFrame;
     clone(visitor?: TextVisitor): ITextFrame;
     equals(other: ITextParagraph): boolean;
+    /** {@inheritDoc ITextFrame.IText.getText} */
+    getText(): string;
     /** {@inheritDoc ITextFrame.createTextFrame} */
     createTextFrame(text: string, allowWrap?: boolean): ITextFrame;
     get bounds(): Bounds;
@@ -39,5 +41,7 @@ export declare class TextFrame {
     get isSpaceFirstLastPara(): boolean;
     get presetTextWarp(): string | null;
     get paragraphs(): ITextParagraph[];
+    /** {@inheritDoc ITextFrame.isITextFrame} */
+    get isITextFrame(): true;
 }
 //# sourceMappingURL=TextFrame.d.ts.map

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

@@ -9,6 +9,8 @@ export interface ITextLine {
     readonly runs: ITextRun[];
     readonly bounds: Bounds;
     readonly baseline: number;
+    /** For runtime type checking. */
+    readonly isITextLine: true;
 }
 /**
  * A default text line.
@@ -20,5 +22,7 @@ export declare class DefaultTextLine implements ITextLine {
     get baseline(): any;
     get runs(): any;
     get bullet(): null;
+    /** {@inheritDoc ITextLine.isITextLine} */
+    get isITextLine(): true;
 }
 //# sourceMappingURL=TextLine.d.ts.map

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

@@ -24,6 +24,8 @@ export interface ITextParagraph {
     readonly rightMargin: number;
     readonly bullet: IBullet | null;
     readonly runs: ITextRun[];
+    /** For runtime type checking. */
+    readonly isITextParagraph: true;
 }
 export interface PlacedTextParagraph extends ITextParagraph {
     /**
@@ -57,5 +59,7 @@ export declare class DefaultTextParagraph implements ITextParagraph, PlacedTextP
     get rightMargin(): number;
     get bullet(): IBullet | null;
     get runs(): ITextRun[];
+    /** {@inheritDoc ITextParagraph.isITextParagraph} */
+    get isITextParagraph(): true;
 }
 //# sourceMappingURL=TextParagraph.d.ts.map

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

@@ -52,6 +52,13 @@ export interface ITextRun {
      * Specifies the strikethrough style applied to the text.
      */
     readonly strikeStyle: IText.StrikeStyle;
+    /**
+       * Specifies the baseline for both the superscript and subscript fonts.
+       * The size is specified using a percentage where 1000 is equal to 1 percent
+       * of the font size and 100000 is equal to 100 percent font of the font size.
+       */
+    /** For runtime type checking. */
+    readonly isITextRun: true;
 }
 export interface PlacedTextRun extends ITextRun {
     /**
@@ -81,5 +88,7 @@ export declare class DefaultTextRun implements ITextRun, PlacedTextRun, Cloneabl
     get smallCaps(): IText.SmallCaps;
     get offset(): number;
     get strikeStyle(): IText.StrikeStyle;
+    /** {@inheritDoc ITextRun.isITextRun} */
+    get isITextRun(): true;
 }
 //# sourceMappingURL=TextRun.d.ts.map

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

@@ -0,0 +1,83 @@
+import { Bounds } from '@sheetxl/utils';
+import { ITextFrame } from './ITextFrame';
+/**
+ * Stacked cell-text layout — Excel's "Vertical Text" (`textRotation="255"`).
+ *
+ * Stacked text is not rotated. Every glyph stays upright and occupies one SLOT of the font's line
+ * pitch, glyphs advancing downward in a column. Measured against Excel (hidden-COM probes, see
+ * `VERTICAL-TEXT-PLAN.md`):
+ *
+ * 1. Columns come from explicit line breaks — one column per line, left → right in reading order —
+ *    and, when the cell wraps, from breaking a column that would exceed the content height: greedy
+ *    at spaces (the space at a break is consumed), per glyph inside a word longer than the capacity.
+ *    It is the horizontal wrap rule transposed. An unwrapped cell keeps one column; a line break
+ *    there is a blank slot.
+ * 2. Leading and trailing spaces of a column are measured but never painted (see
+ *    {@link layoutColumns}); inner spaces are blank slots.
+ * 3. Each column is aligned on its own by the vertical alignment (Top / Center / Bottom; Justify
+ *    and Distributed behave as Top and Center — nothing is spread). The horizontal alignment places
+ *    the group of columns; the caller resolves General (Excel centers it). Columns are one pitch
+ *    wide and glyphs center in them.
+ * 4. Nothing overflows: the footprint clips to the cell on both axes.
+ *
+ * All output is pure geometry, renderer-agnostic: a DOM renderer maps each column to a box of
+ * `pitch` line-height with one glyph per line; a canvas renderer paints each glyph centered in
+ * its slot.
+ */
+/**
+ * One stacked column.
+ */
+export interface Column {
+    /** The slot texts, top to bottom — one glyph each; a blank slot is `' '`. */
+    glyphs: readonly string[];
+    /** The column box (content-box coordinate space): one pitch wide, `glyphs.length · pitch` tall. */
+    bounds: Bounds;
+}
+/**
+ * The placed geometry for all columns — see {@link layoutColumns}.
+ */
+export interface Layout {
+    /** The slot pitch: the font's line height. Also the column width. */
+    pitch: number;
+    /** One entry per column, in reading order (left → right). */
+    columns: readonly Column[];
+    /** The axis-aligned union of all columns. */
+    bounds: Bounds;
+}
+/**
+ * Splits text into the units that take a slot each. Code points, so a surrogate pair is one slot.
+ */
+export declare function splitGlyphs(text: string): string[];
+/**
+ * Splits text into columns of slots.
+ *
+ * @param text The text to stack (line breaks are `\n`).
+ * @param wrapped `true` when the cell wraps: line breaks start new columns and a column longer than
+ *  `capacity` breaks (see the module notes). `false` keeps one column with a line break as a blank
+ *  slot.
+ * @param capacity The slots per column before a wrapped column breaks. Pass
+ *  `Number.MAX_SAFE_INTEGER` to split on line breaks only (the measure Excel's autofit uses).
+ *
+ * @remarks
+ * Columns keep their leading/trailing spaces — those count for measurement. {@link layoutColumns}
+ * trims them for painting.
+ */
+export declare function toColumns(text: string, wrapped: boolean, capacity: number): string[][];
+/**
+ * The slot count a measure uses: the longest column, spaces included.
+ */
+export declare function slotCount(columns: readonly (readonly string[])[]): number;
+/**
+ * Lays out stacked columns within a content box.
+ *
+ * @param columns The columns' slot glyphs, in reading order (see {@link toColumns}). Leading and
+ *  trailing spaces are trimmed here — Excel measures them but does not paint them.
+ * @param pitch The slot pitch (the font's line height); also the column width.
+ * @param content The content box (cell box minus insets), in the caller's coordinate space.
+ * @param horizontal The resolved horizontal alignment (`General` already resolved). Places the
+ *  group of columns: Left/Justify at the left edge, Right at the right edge, otherwise centered.
+ * @param vertical The vertical alignment, applied to EACH column: Top/Justify hug the top edge,
+ *  Center/Distributed center, Bottom (the default) hugs the bottom.
+ */
+export declare function layoutColumns(columns: readonly (readonly string[])[], pitch: number, content: Bounds, horizontal: ITextFrame.HorizontalAlignment, vertical: ITextFrame.VerticalAlignment): Layout;
+//# sourceMappingURL=TextStacked.d.ts.map

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

@@ -4,4 +4,5 @@ export * from './richtext';
 export * from './TextBoxAlignment';
 export * as TextUtils from './TextUtils';
 export * as TextRotation from './TextRotation';
+export * as TextStacked from './TextStacked';
 //# sourceMappingURL=index.d.ts.map

package/types/src/theme/ITheme.d.ts

@@ -54,6 +54,8 @@ export interface ITheme {
      * @param includeInherited If true then the inherited properties will be included.
      */
     toJSON(includeInherited?: boolean): ITheme.JSON;
+    /** For runtime type checking. */
+    readonly isITheme: true;
 }
 /**
  * {@inheritDoc ITheme}

package/types/src/theme/IThemeCollection.d.ts

@@ -53,6 +53,8 @@ export interface IThemeCollection extends ICollection<ITheme> {
      * @returns The previous default theme.
      */
     setDefaultTheme: (theme: ITheme) => ITheme;
+    /** For runtime type checking. */
+    readonly isIThemeCollection: true;
 }
 /**
  * {@inheritDoc IThemeCollection}

package/types/src/theme/ThemeCollection.d.ts

@@ -1,3 +1,4 @@
+import { AbstractCollection } from '../type';
 import { IColor } from '../color';
 import { ITheme } from './ITheme';
 import { IThemeCollection } from './IThemeCollection';
@@ -33,11 +34,13 @@ export declare class Theme implements ITheme {
     parseColor(str: string): IColor;
     /** {@inheritDoc ITheme.toJSON} */
     toJSON(): ITheme.JSON;
+    /** {@inheritDoc ITheme.isITheme} */
+    get isITheme(): true;
 }
 /**
  * Collection of themes
  */
-export declare class ThemeCollection implements IThemeCollection {
+export declare class ThemeCollection extends AbstractCollection<ITheme, IThemeCollection.GetItemsOptions> implements IThemeCollection {
     private _customMap;
     private _defaultTheme;
     private _isReadOnly;
@@ -48,15 +51,13 @@ export declare class ThemeCollection implements IThemeCollection {
     setDefaultTheme(theme: ITheme): ITheme;
     /** {@inheritDoc IThemeCollection.getByName} */
     getByName(name: string): ITheme | null;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<ITheme>;
-    /** {@inheritDoc IThemeCollection.getByName} */
-    getItems(options?: IThemeCollection.GetItemsOptions): ITheme[];
-    /** {@inheritDoc IThemeCollection.getCount} */
-    getCount(): number;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IThemeCollection.GetItemsOptions): ITheme[];
     /** {@inheritDoc IThemeCollection.setCustomTheme} */
     setCustomTheme(theme: ITheme): ITheme | null;
     /** {@inheritDoc IThemeCollection.deleteCustomTheme} */
     deleteCustomTheme(theme: ITheme | string): ITheme | null;
+    /** {@inheritDoc IThemeCollection.isIThemeCollection} */
+    get isIThemeCollection(): true;
 }
 //# sourceMappingURL=ThemeCollection.d.ts.map