@pixerate/editor 0.192.0 → 0.194.0

package/dist/text/layout.d.ts

@@ -2,11 +2,11 @@
  * Text layout shared by the image editor's type layers and the vector editor's text nodes: styled
  * runs, paragraphs, line breaking (at spaces and after break characters, and between wide CJK
  * characters), alignment and justification, tracking, leading, indents, spacing, baseline shift,
- * caret positions and hit testing. Everything that needs a font goes through a `TextShaper`, so
+ * horizontal and vertical writing, caret positions and hit testing. Everything that needs a font goes through a `TextShaper`, so
  * the same measurements give the same lines in every host.
  */
 import type { BezierPath } from '../canvas/pathops/bezier.js';
-import type { ParagraphRun, TextFont, TextRect, TextShaper, TextStyle } from './types.js';
+import type { ParagraphRun, TextFont, TextOrientation, TextRect, TextShaper, TextStyle } from './types.js';
 /** What layout needs: the text, its character and paragraph runs and its frame. */
 export interface TextBlock {
     text: string;
@@ -28,6 +28,12 @@ export interface TextBlock {
         width: number;
         height: number;
     };
+    /**
+     * Default `horizontal`. `vertical`: lines are columns running down, stacked right to left. Point
+     * text then starts at (0, 0) at the top of the first column's centre line (`origin: 'top'`: its
+     * right edge); a box's columns start at its right edge and wrap at its height.
+     */
+    orientation?: TextOrientation;
 }
 export declare const DEFAULT_TEXT_STYLE: TextStyle;
 export declare const DEFAULT_AUTO_LEADING = 1.2;
@@ -65,14 +71,39 @@ export declare function paragraphRanges(text: string): Array<{
 }>;
 /** Paragraph runs snapped to whole paragraphs: each paragraph takes the style at its start. */
 export declare function fitParagraphRuns(runs: readonly ParagraphRun[], text: string): ParagraphRun[];
+/** A point in text space (or line space, where said). */
+export interface TextPoint {
+    x: number;
+    y: number;
+}
+/** An affine matrix `[a, b, c, d, e, f]`: `x' = a·x + c·y + e`, `y' = b·x + d·y + f`. */
+export type TextMatrix = readonly [number, number, number, number, number, number];
 /** One laid-out character. */
 export interface LaidChar {
     /** Index in the text (UTF-16 code unit). */
     index: number;
-    /** Text-space x of its start and its advance (tracking and justification included). */
+    /** Line-space x of its start and its advance (tracking and justification included). */
     x: number;
     advance: number;
 }
+/**
+ * A character of vertical text as drawn, text space: its origin on its own baseline, its turn
+ * (`90`: turned sideways, clockwise; `0`: upright), its advance along its baseline and its box
+ * above and below the baseline.
+ */
+export interface LaidGlyph {
+    index: number;
+    /** Code units (2 for a surrogate pair). */
+    length: number;
+    x: number;
+    y: number;
+    angle: 0 | 90;
+    advance: number;
+    ascent: number;
+    descent: number;
+    /** Drawn with the font's vertical alternate (`vert`). */
+    vert: boolean;
+}
 /** A run of characters on one line in one style. */
 export interface LaidFragment {
     start: number;
@@ -81,18 +112,24 @@ export interface LaidFragment {
     font: TextFont;
     /** The family the shaper draws it with. */
     family: string;
+    /** Line space. */
     x: number;
-    /** Baseline in text space (baseline shift applied). */
+    /** Baseline in line space (baseline shift applied); for upright vertical text, the column's centre line. */
     y: number;
     /** Per-character x positions relative to `x` (`end − start + 1` entries). */
     carets: number[];
     /** Whether characters are placed one by one (tracking or justification). */
     spaced: boolean;
+    /** Vertical text only: whether the fragment's characters stand upright (else they are turned sideways). */
+    upright?: boolean;
+    /** Vertical text only: each character as drawn, text space (low surrogates join their pair). */
+    glyphs?: LaidGlyph[];
 }
 export interface LaidLine {
     start: number;
     /** End of the line's characters (line break and trailing spaces excluded from `width`). */
     end: number;
+    /** Line space; for vertical text the column's centre line. */
     baseline: number;
     ascent: number;
     descent: number;
@@ -100,34 +137,78 @@ export interface LaidLine {
     width: number;
     chars: LaidChar[];
     fragments: LaidFragment[];
+    /** Vertical text only: line space → text space (the layout's `matrix`). */
+    matrix?: TextMatrix;
 }
-/** A laid-out type layer in text space. */
+/** A laid-out type layer. */
 export interface TextLayout {
     lines: LaidLine[];
     /** Bounds of the lines (ascent to descent), text space; the box for paragraph text. */
     bounds: TextRect;
     /** Families replaced by a fallback. */
     missingFonts: string[];
+    orientation: TextOrientation;
+    /** Vertical text only: line space → text space. */
+    matrix?: TextMatrix;
 }
 export declare function fontOf(style: TextStyle): TextFont;
 /** Whether a character is a space or tab (spaces hang at line ends and stretch when justifying). */
 export declare const isTextSpace: (c: string) => c is "\t" | " ";
+/**
+ * How a code point is set in vertical text, after Unicode's Vertical_Orientation (UAX #50),
+ * simplified to CJK: `U` upright (ideographs, kana, Hangul, full-width forms, emoji), `R` turned
+ * sideways (Latin and other horizontal scripts, spaces), `Tu` upright in a vertical form when the
+ * font has one (、。 and small kana), `Tr` a vertical form when the font has one, else turned
+ * sideways (brackets, dashes, the long vowel mark, wave dash).
+ */
+export declare function verticalOrientationOf(cp: number): 'U' | 'R' | 'Tu' | 'Tr';
+/** A rectangle mapped through `m` (a quarter turn keeps it a rectangle); `r` itself without `m`. */
+export declare function transformTextRect(m: TextMatrix | undefined, r: TextRect): TextRect;
+/** A line-space point of `layout` in text space (the same point for horizontal text). */
+export declare function lineToTextSpace(layout: Pick<TextLayout, 'matrix'>, p: TextPoint): TextPoint;
+/** A text-space point of `layout` in line space (the same point for horizontal text). */
+export declare function textToLineSpace(layout: Pick<TextLayout, 'matrix'>, p: TextPoint): TextPoint;
+/** A line's box (its advance by ascent to descent) in text space. */
+export declare function textLineRect(l: LaidLine): TextRect;
 /** Lays out a type layer with `shaper` (memoised per layer object and shaper). */
 export declare function layoutText(layer: TextBlock, shaper: TextShaper): TextLayout;
 /** The text index nearest a text-space point (for clicks): the line under it, then the closest caret. */
-export declare function textIndexAt(layout: TextLayout, p: {
-    x: number;
-    y: number;
-}): number;
-/** The caret at text index `index`: its x and the line's top and bottom, text space. */
+export declare function textIndexAt(layout: TextLayout, point: TextPoint): number;
+/**
+ * The caret at text index `index`: in line space its x and the line's top and bottom, and in text
+ * space the segment it draws (`from` the line's top or, vertically, its right edge, `to` the other
+ * side).
+ */
 export declare function caretAt(layout: TextLayout, index: number): {
     x: number;
     top: number;
     bottom: number;
     line: number;
+    from: TextPoint;
+    to: TextPoint;
 };
-/** Underline and strike-through bars of a fragment, text space, as rectangles. */
+/** Quads (text space, four corners each) covering the characters of [start, end), one per line. */
+export declare function textSelectionQuads(layout: TextLayout, start: number, end: number): TextPoint[][];
+/** What an arrow key does to a text caret: along the line (`previous` / `next` character) or across lines. */
+export type TextCaretStep = 'previous' | 'next' | 'line-before' | 'line-after';
+/**
+ * The caret step of an arrow key. Horizontal text: ← → move along the line, ↑ ↓ between lines.
+ * Vertical text: ↑ ↓ move along the column, → to the column before (on the right), ← to the next.
+ */
+export declare function textArrowStep(orientation: TextOrientation | undefined, key: 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown'): TextCaretStep;
+/**
+ * The index on the line before (`dir` −1) or after (+1) the caret at `index`, at the same place
+ * along the line; the start or end of the text (`length`) past the first or last line.
+ */
+export declare function textLineMove(layout: TextLayout, index: number, dir: -1 | 1, length: number): number;
+/** Underline and strike-through bars of a fragment, text space, as rectangles. Vertical text underlines on the right. */
 export declare function textDecorations(f: LaidFragment, l: LaidLine): TextRect[];
 export declare const textRectPath: (r: TextRect) => BezierPath;
-/** The text of a fragment as outlines (one placement per character when spaced), text space. */
+/** The text of a fragment as outlines (one placement per character when spaced or vertical), text space. */
 export declare function textFragmentOutline(shaper: TextShaper, text: string, f: LaidFragment): BezierPath;
+/**
+ * Draws a fragment's text with a drawing shaper in the context's current transform (text space),
+ * fill style and alpha: each glyph of vertical text turned or upright, spaced text a character at
+ * a time. Decorations are not drawn (see `textDecorations`).
+ */
+export declare function drawTextFragment(ctx: CanvasRenderingContext2D, shaper: TextShaper, text: string, f: LaidFragment): void;

package/dist/text/opentype.d.cts

@@ -2,9 +2,10 @@
  * A small OpenType reader: enough of a font file to set Latin, Cyrillic, Greek and CJK text as
  * outlines without a third-party library. It reads TrueType (`glyf`) and CFF (`CFF `, CID-keyed
  * included) outlines, `cmap` (formats 4 and 12), horizontal metrics, `kern` (format 0) and `GPOS`
- * pair kerning (lookup type 2, formats 1 and 2, the `kern` feature), and the family, PostScript
- * name, weight and style. It does not apply `GSUB` (ligatures, contextual forms) or complex-script
- * shaping, so Arabic, Indic and similar scripts set as isolated glyphs.
+ * pair kerning (lookup type 2, formats 1 and 2, the `kern` feature), vertical metrics (`vhea`,
+ * `vmtx`, `VORG`) and vertical alternates (`GSUB` single substitutions of the `vert` feature), and
+ * the family, PostScript name, weight and style. It applies no other `GSUB` (ligatures, contextual
+ * forms) or complex-script shaping, so Arabic, Indic and similar scripts set as isolated glyphs.
  *
  * The result has the shape of opentype.js's `Font` that `createOutlineTextShaper` takes, so hosts
  * can pass either. Written from the OpenType specification (TrueType glyph outlines, the CFF
@@ -31,6 +32,15 @@ export interface OpenTypeFont extends OutlineFontFace {
     kerning(left: number, right: number): number;
     /** A glyph's outline in font units, y up, origin on the baseline. */
     glyphPath(glyph: number): OutlinePathCommand[];
+    /** Whether the font has vertical metrics (`vhea` and `vmtx`). */
+    readonly hasVerticalMetrics: boolean;
+    /** A glyph's vertical alternate (the `vert` feature), or the glyph itself when it has none. */
+    verticalGlyph(glyph: number): number;
+    getVerticalMetrics(char: string): {
+        advance: number;
+        originY: number;
+        alternate: boolean;
+    };
 }
 /**
  * Reads a TrueType or OpenType font (`.ttf`, `.otf`, or face `index` of a `.ttc` collection).

package/dist/text/opentype.d.ts

@@ -2,9 +2,10 @@
  * A small OpenType reader: enough of a font file to set Latin, Cyrillic, Greek and CJK text as
  * outlines without a third-party library. It reads TrueType (`glyf`) and CFF (`CFF `, CID-keyed
  * included) outlines, `cmap` (formats 4 and 12), horizontal metrics, `kern` (format 0) and `GPOS`
- * pair kerning (lookup type 2, formats 1 and 2, the `kern` feature), and the family, PostScript
- * name, weight and style. It does not apply `GSUB` (ligatures, contextual forms) or complex-script
- * shaping, so Arabic, Indic and similar scripts set as isolated glyphs.
+ * pair kerning (lookup type 2, formats 1 and 2, the `kern` feature), vertical metrics (`vhea`,
+ * `vmtx`, `VORG`) and vertical alternates (`GSUB` single substitutions of the `vert` feature), and
+ * the family, PostScript name, weight and style. It applies no other `GSUB` (ligatures, contextual
+ * forms) or complex-script shaping, so Arabic, Indic and similar scripts set as isolated glyphs.
  *
  * The result has the shape of opentype.js's `Font` that `createOutlineTextShaper` takes, so hosts
  * can pass either. Written from the OpenType specification (TrueType glyph outlines, the CFF
@@ -31,6 +32,15 @@ export interface OpenTypeFont extends OutlineFontFace {
     kerning(left: number, right: number): number;
     /** A glyph's outline in font units, y up, origin on the baseline. */
     glyphPath(glyph: number): OutlinePathCommand[];
+    /** Whether the font has vertical metrics (`vhea` and `vmtx`). */
+    readonly hasVerticalMetrics: boolean;
+    /** A glyph's vertical alternate (the `vert` feature), or the glyph itself when it has none. */
+    verticalGlyph(glyph: number): number;
+    getVerticalMetrics(char: string): {
+        advance: number;
+        originY: number;
+        alternate: boolean;
+    };
 }
 /**
  * Reads a TrueType or OpenType font (`.ttf`, `.otf`, or face `index` of a `.ttc` collection).

package/dist/text/shapers.d.cts

@@ -42,11 +42,23 @@ export interface OutlineFontFace {
     getAdvanceWidth(text: string, fontSize: number, options?: {
         kerning?: boolean;
     }): number;
+    /** `vertical`: the font's vertical alternates (`vert`), where it has them (faces without `getVerticalMetrics` ignore it). */
     getPath(text: string, x: number, y: number, fontSize: number, options?: {
         kerning?: boolean;
+        vertical?: boolean;
     }): {
         commands: OutlinePathCommand[];
     };
+    /**
+     * Vertical metrics of one character set upright, in font units: its advance down the column, the
+     * distance from the top of its cell to its baseline, and whether it has a vertical alternate.
+     * Optional (opentype.js lacks it): vertical text then uses the ascender and descender.
+     */
+    getVerticalMetrics?(char: string): {
+        advance: number;
+        originY: number;
+        alternate: boolean;
+    };
     names?: {
         fontFamily?: Record<string, string>;
         postScriptName?: Record<string, string>;

package/dist/text/shapers.d.ts

@@ -42,11 +42,23 @@ export interface OutlineFontFace {
     getAdvanceWidth(text: string, fontSize: number, options?: {
         kerning?: boolean;
     }): number;
+    /** `vertical`: the font's vertical alternates (`vert`), where it has them (faces without `getVerticalMetrics` ignore it). */
     getPath(text: string, x: number, y: number, fontSize: number, options?: {
         kerning?: boolean;
+        vertical?: boolean;
     }): {
         commands: OutlinePathCommand[];
     };
+    /**
+     * Vertical metrics of one character set upright, in font units: its advance down the column, the
+     * distance from the top of its cell to its baseline, and whether it has a vertical alternate.
+     * Optional (opentype.js lacks it): vertical text then uses the ascender and descender.
+     */
+    getVerticalMetrics?(char: string): {
+        advance: number;
+        originY: number;
+        alternate: boolean;
+    };
     names?: {
         fontFamily?: Record<string, string>;
         postScriptName?: Record<string, string>;

package/dist/text/types.d.cts

@@ -38,7 +38,20 @@ export interface TextStyle {
     strikethrough?: boolean;
     /** PostScript name from a PSD (`ArialMT`), kept so the exact face can be found and written back. */
     postScriptName?: string;
+    /**
+     * Vertical text only: set Latin and other horizontal-script characters upright, one under the
+     * other, instead of turned sideways (Photoshop's Standard Vertical Roman Alignment off). Default
+     * false. No effect on horizontal text.
+     */
+    upright?: boolean;
 }
+/**
+ * Which way text runs. `horizontal`: lines left to right, stacked downwards. `vertical`: columns
+ * top to bottom, stacked right to left; CJK characters stand upright and other scripts are turned
+ * 90° clockwise (unless their style is `upright`).
+ */
+export type TextOrientation = 'horizontal' | 'vertical';
+export declare const TEXT_ORIENTATIONS: readonly TextOrientation[];
 /** A character style over `length` UTF-16 code units of the text, in order. */
 export interface TextRun {
     length: number;
@@ -71,6 +84,20 @@ export interface TextFont {
     size: number;
     postScriptName?: string;
 }
+/** How a shaper sets a character upright in a vertical column (pixels). */
+export interface TextVerticalMetrics {
+    /** Advance down the column. */
+    advance: number;
+    /** Distance from the top of the character's cell to its horizontal baseline. */
+    originY: number;
+    /** Whether the font has a vertical alternate (OpenType `vert`) the shaper draws with `{ vertical: true }`. */
+    alternate: boolean;
+}
+/** Options for drawing or outlining text. */
+export interface TextGlyphOptions {
+    /** Use the font's vertical alternates (`vert`), for upright characters in vertical text. */
+    vertical?: boolean;
+}
 /**
  * What layout and rendering need from fonts. Implement `outline` (glyph outlines, pure) or `draw`
  * (onto a 2D canvas), or both.
@@ -94,9 +121,16 @@ export interface TextShaper {
      */
     measure(text: string, font: TextFont): ArrayLike<number>;
     /** Glyph outlines of `text` with its start on the baseline at (`x`, `y`), pixels, y down. */
-    outline?(text: string, font: TextFont, x: number, y: number): BezierPath;
+    outline?(text: string, font: TextFont, x: number, y: number, options?: TextGlyphOptions): BezierPath;
     /** Draws `text` with its start on the baseline at (`x`, `y`) in the context's current transform, fill style and alpha. */
-    draw?(ctx: CanvasRenderingContext2D, text: string, font: TextFont, x: number, y: number): void;
+    draw?(ctx: CanvasRenderingContext2D, text: string, font: TextFont, x: number, y: number, options?: TextGlyphOptions): void;
+    /**
+     * Vertical metrics of one character (a code point) set upright, from the font's `vhea` / `vmtx`.
+     * Optional: without it, vertical layout uses the font's ascent + descent as the advance and its
+     * ascent as the origin, and has no vertical alternates (brackets and dashes are then turned
+     * sideways, and 、。 moved to the upper right of their cell).
+     */
+    vertical?(char: string, font: TextFont): TextVerticalMetrics;
     /** Families this shaper can draw (for font pickers and agents), when it can tell. */
     families?(): string[];
 }

package/dist/text/types.d.ts

@@ -38,7 +38,20 @@ export interface TextStyle {
     strikethrough?: boolean;
     /** PostScript name from a PSD (`ArialMT`), kept so the exact face can be found and written back. */
     postScriptName?: string;
+    /**
+     * Vertical text only: set Latin and other horizontal-script characters upright, one under the
+     * other, instead of turned sideways (Photoshop's Standard Vertical Roman Alignment off). Default
+     * false. No effect on horizontal text.
+     */
+    upright?: boolean;
 }
+/**
+ * Which way text runs. `horizontal`: lines left to right, stacked downwards. `vertical`: columns
+ * top to bottom, stacked right to left; CJK characters stand upright and other scripts are turned
+ * 90° clockwise (unless their style is `upright`).
+ */
+export type TextOrientation = 'horizontal' | 'vertical';
+export declare const TEXT_ORIENTATIONS: readonly TextOrientation[];
 /** A character style over `length` UTF-16 code units of the text, in order. */
 export interface TextRun {
     length: number;
@@ -71,6 +84,20 @@ export interface TextFont {
     size: number;
     postScriptName?: string;
 }
+/** How a shaper sets a character upright in a vertical column (pixels). */
+export interface TextVerticalMetrics {
+    /** Advance down the column. */
+    advance: number;
+    /** Distance from the top of the character's cell to its horizontal baseline. */
+    originY: number;
+    /** Whether the font has a vertical alternate (OpenType `vert`) the shaper draws with `{ vertical: true }`. */
+    alternate: boolean;
+}
+/** Options for drawing or outlining text. */
+export interface TextGlyphOptions {
+    /** Use the font's vertical alternates (`vert`), for upright characters in vertical text. */
+    vertical?: boolean;
+}
 /**
  * What layout and rendering need from fonts. Implement `outline` (glyph outlines, pure) or `draw`
  * (onto a 2D canvas), or both.
@@ -94,9 +121,16 @@ export interface TextShaper {
      */
     measure(text: string, font: TextFont): ArrayLike<number>;
     /** Glyph outlines of `text` with its start on the baseline at (`x`, `y`), pixels, y down. */
-    outline?(text: string, font: TextFont, x: number, y: number): BezierPath;
+    outline?(text: string, font: TextFont, x: number, y: number, options?: TextGlyphOptions): BezierPath;
     /** Draws `text` with its start on the baseline at (`x`, `y`) in the context's current transform, fill style and alpha. */
-    draw?(ctx: CanvasRenderingContext2D, text: string, font: TextFont, x: number, y: number): void;
+    draw?(ctx: CanvasRenderingContext2D, text: string, font: TextFont, x: number, y: number, options?: TextGlyphOptions): void;
+    /**
+     * Vertical metrics of one character (a code point) set upright, from the font's `vhea` / `vmtx`.
+     * Optional: without it, vertical layout uses the font's ascent + descent as the advance and its
+     * ascent as the origin, and has no vertical alternates (brackets and dashes are then turned
+     * sideways, and 、。 moved to the upper right of their cell).
+     */
+    vertical?(char: string, font: TextFont): TextVerticalMetrics;
     /** Families this shaper can draw (for font pickers and agents), when it can tell. */
     families?(): string[];
 }

package/dist/vector/controller.d.cts

@@ -143,6 +143,8 @@ export interface VectorTextInput extends VectorStyle {
     }>, 'kind' | 'path'>;
     font?: Partial<VectorCharacterStyle>;
     paragraph?: VectorParagraphStyle;
+    /** Point and area text: `vertical` sets columns running down, right to left (default horizontal). */
+    orientation?: 'horizontal' | 'vertical';
     name?: string;
 }
 /** A constraint reference from loose input: an anchor by `subpath` / `index` (or its `id` as `anchor`), its handle, its segment, or a path as a circle. */
@@ -2249,6 +2251,7 @@ export declare class VectorEditorController {
     styleTexts(patch: {
         style?: Record<string, unknown>;
         paragraph?: Record<string, unknown>;
+        orientation?: 'horizontal' | 'vertical';
     }, options?: {
         ids?: readonly string[];
         merge?: string;
@@ -2264,6 +2267,11 @@ export declare class VectorEditorController {
      * the node's own space). One undo step.
      */
     setTextFrame(id: string, patch: Record<string, unknown>): VectorActionResult;
+    /**
+     * Horizontal ↔ vertical text (Type › Type Orientation) for point and area text: the text, styles
+     * and frame stay; lines become columns running down, right to left, or back. One undo step.
+     */
+    setTextOrientation(id: string, orientation: 'horizontal' | 'vertical'): VectorActionResult;
     /**
      * Turns path `pathId` into text set along it (Type on a Path): a text node in its place, its
      * anchors the text's path, its paint dropped for the text defaults (or `input`'s). Returns the

package/dist/vector/controller.d.ts

@@ -143,6 +143,8 @@ export interface VectorTextInput extends VectorStyle {
     }>, 'kind' | 'path'>;
     font?: Partial<VectorCharacterStyle>;
     paragraph?: VectorParagraphStyle;
+    /** Point and area text: `vertical` sets columns running down, right to left (default horizontal). */
+    orientation?: 'horizontal' | 'vertical';
     name?: string;
 }
 /** A constraint reference from loose input: an anchor by `subpath` / `index` (or its `id` as `anchor`), its handle, its segment, or a path as a circle. */
@@ -2249,6 +2251,7 @@ export declare class VectorEditorController {
     styleTexts(patch: {
         style?: Record<string, unknown>;
         paragraph?: Record<string, unknown>;
+        orientation?: 'horizontal' | 'vertical';
     }, options?: {
         ids?: readonly string[];
         merge?: string;
@@ -2264,6 +2267,11 @@ export declare class VectorEditorController {
      * the node's own space). One undo step.
      */
     setTextFrame(id: string, patch: Record<string, unknown>): VectorActionResult;
+    /**
+     * Horizontal ↔ vertical text (Type › Type Orientation) for point and area text: the text, styles
+     * and frame stay; lines become columns running down, right to left, or back. One undo step.
+     */
+    setTextOrientation(id: string, orientation: 'horizontal' | 'vertical'): VectorActionResult;
     /**
      * Turns path `pathId` into text set along it (Type on a Path): a text node in its place, its
      * anchors the text's path, its paint dropped for the text defaults (or `input`'s). Returns the