Skip to content

API.md

Latest commit

 

History

History
1734 lines (1075 loc) · 35.3 KB

API.md

File metadata and controls

1734 lines (1075 loc) · 35.3 KB

@borgar/textbox

Classes

Interfaces

Type Aliases

Functions

References

default

Renames and re-exports Textbox

Rotator

A convenience utility class to assist rotating text.

Constructors

Constructor

new Rotator(opts: RotatorOptions): Rotator;

Parameters

Parameter Type
opts RotatorOptions

Returns

Rotator

Properties

Property Modifier Type Default value
createElement static (name: string, props?: | Record<string, string | number | boolean | null> | null, ...children: (string | SVGElement | null | undefined)[]) => SVGElement createElement

Accessors

origin

Get Signature

get origin(): [number, number];

Origin point of the rotation

Returns

[number, number]

Methods

align()

Call Signature

align(): HAlignment;

Controls the horizontal alignment of the text.

By default this will be set to "left".

Returns

HAlignment

Call Signature

align(align: HAlignment): this;

Controls the horizontal alignment of the text.

By default this will be set to "left".

Parameters
Parameter Type
align HAlignment
Returns

this

anchor()

Call Signature

anchor(): string;

A convenience method to set or get a rotation anchor.

A rotation anchor controls the origin point of the rotation relative to textbox. It is a string of one or more of alignment keywords separated by spaces.

Keywords: [ top, middle, bottom, left, center, right ].

By default it is set to "top left"

Returns

string

Call Signature

anchor(anchor: string): this;

A convenience method to set or get a rotation anchor.

A rotation anchor controls the origin point of the rotation relative to textbox. It is a string of one or more of alignment keywords separated by spaces.

Keywords: [ top, middle, bottom, left, center, right ].

By default it is set to "top left"

Parameters
Parameter Type
anchor string
Returns

this

createElement()

Call Signature

createElement(): CreateElementFunc;

The element factory function to use when constructing SVG elements within the SVG renderer.

The interface conforms to React's React.createElement so you may simply set that function as the factory if you want to use the rendered text in a React render tree.

Returns

CreateElementFunc

Call Signature

createElement(factory: CreateElementFunc): this;

The element factory function to use when constructing SVG elements within the SVG renderer.

The interface conforms to React's React.createElement so you may simply set that function as the factory if you want to use the rendered text in a React render tree.

Parameters
Parameter Type
factory CreateElementFunc
Returns

this

height()

Call Signature

height(): number;

Controls the height of the rotation box in pixels.

By default this will be set to Infinity.

Returns

number

Call Signature

height(height: number): this;

Controls the height of the rotation box in pixels.

By default this will be set to Infinity.

Parameters
Parameter Type
height number
Returns

this

render()

Call Signature

render(contentOrCallback: SVGElement): SVGElement;

Render onto a Canvas or as an SVG element based on whether a canvas based target was supplied or not.

Parameters
Parameter Type
contentOrCallback SVGElement
Returns

SVGElement

Deprecated

Call Signature

render(contentOrCallback: () => void, ctx: OffscreenCanvas | HTMLCanvasElement | CanvasRenderingContext2D): void;

Render onto a Canvas or as an SVG element based on whether a canvas based target was supplied or not.

Parameters
Parameter Type
contentOrCallback () => void
ctx OffscreenCanvas | HTMLCanvasElement | CanvasRenderingContext2D
Returns

void

Deprecated

renderCanvas()

renderCanvas(callback: (ctx: CanvasRenderingContext2D) => void, target: OffscreenCanvas | HTMLCanvasElement | CanvasRenderingContext2D): void;

Set up a rotated context for additional rendering.

The method will set up a rotated context, call the supplied callback argument with a CanvasRenderingContext2D as its argument, and then clean up.

Parameters

Parameter Type
callback (ctx: CanvasRenderingContext2D) => void
target OffscreenCanvas | HTMLCanvasElement | CanvasRenderingContext2D

Returns

void

renderSVG()

renderSVG(content: SVGElement): SVGElement;

Render an SVG element that is rotated around its origin point and place the given content inside it.

Parameters

Parameter Type
content SVGElement

Returns

SVGElement

rotate()

Call Signature

rotate(): number;

Controls the angle of rotation in degrees.

By default this will be set to 0.

Returns

number

Call Signature

rotate(degrees: number): this;

Controls the angle of rotation in degrees.

By default this will be set to 0.

Parameters
Parameter Type
degrees number
Returns

this

valign()

Call Signature

valign(): VAlignment;

Controls the vertical anchor point of the rotation.

By default this will be set to "top".

Returns

VAlignment

Call Signature

valign(align: VAlignment): this;

Controls the vertical anchor point of the rotation.

By default this will be set to "top".

Parameters
Parameter Type
align VAlignment
Returns

this

width()

Call Signature

width(): number;

Controls the width of the rotation box in pixels.

By default this will be set to Infinity.

Returns

number

Call Signature

width(width: number): this;

Controls the width of the rotation box in pixels.

By default this will be set to Infinity.

Parameters
Parameter Type
width number
Returns

this

Textbox

A Textbox formatter that allows flowing rich text into a preset area.

Constructors

Constructor

new Textbox(options?: Partial<LayoutOptions>): Textbox;

Parameters

Parameter Type
options? Partial<LayoutOptions>

Returns

Textbox

Properties

Property Modifier Type Default value Description
createElement static (name: string, props?: | Record<string, string | number | boolean | null> | null, ...children: (string | SVGElement | null | undefined)[]) => SVGElement createElement Default factory function to use when constructing SVG elements.
defaultparser static (text?: string | null) => Token[] textparser Default parser to use when consuming text.
measureText static (token: string | Token, font: string | FontProps, options: MeasureOptions) => number measureText Measure a string of text as printed with a specified font and return its width.
setMeasureCanvas static (canvas: MinimalCanvas | null) => void setMeasureCanvas Set the canvas to use when measuring text (in a non-browser environment).

Methods

align()

Call Signature

align(): Alignment;

Controls the horizontal alignment of the text.

By default this will be set to "left".

Returns

Alignment

Call Signature

align(align: Alignment): this;

Controls the horizontal alignment of the text.

By default this will be set to "left".

Parameters
Parameter Type
align Alignment
Returns

this

createElement()

Call Signature

createElement(): CreateElementFunc;

The element factory function to use when constructing SVG elements within the SVG renderer.

The interface conforms to React's React.createElement so you may simply set that function as the factory if you want to use the rendered text in a React render tree.

Returns

CreateElementFunc

Call Signature

createElement(factory: CreateElementFunc): this;

The element factory function to use when constructing SVG elements within the SVG renderer.

The interface conforms to React's React.createElement so you may simply set that function as the factory if you want to use the rendered text in a React render tree.

Parameters
Parameter Type
factory CreateElementFunc
Returns

this

font()

Call Signature

font(): string;

Set or get a default font for the text. Parts of the text may override the default font, but this defines the font used when nothing else is specified.

The method assumes a [CSS-style font declaration])(eb/CSS/Reference/Properties/font) string.

By default this will be set to "12px/14px sans-serif".

Returns

string

Call Signature

font(font: string): this;

Set or get a default font for the text. Parts of the text may override the default font, but this defines the font used when nothing else is specified.

The method assumes a [CSS-style font declaration])(eb/CSS/Reference/Properties/font) string.

By default this will be set to "12px/14px sans-serif".

Parameters
Parameter Type
font string
Returns

this

height()

Call Signature

height(): number | NumberFunc;

Controls the height of the textbox in which to fit the text.

By default this will be set to Infinity which mean text will not be subject to overflow.

Returns

number | NumberFunc

Call Signature

height(height: number | NumberFunc): this;

Controls the height of the textbox in which to fit the text.

By default this will be set to Infinity which mean text will not be subject to overflow.

Parameters
Parameter Type
height number | NumberFunc
Returns

this

linebreak()

linebreak(text: string): Lines;

Parses text, flows it into the set dimensions and returns a list of the lines. The returned object can then be passed on to the renderer.

As well as a list of lines of tokens, the lines object has a height property which is useful if you want to set the render destination to the fit the text.

The lines object also includes a .hasOverflow property which indicates if the text was able to fit a designated height. It will be true if the text did not fit the defined space.

Parameters

Parameter Type
text string

Returns

Lines

overflow()

Call Signature

overflow(): string;

The symbol to use when indicating text overflow (text that is cut off because it doesn't fit within the set boundaries).

May be set to any string or the keyword "ellipsis".

By default this will be set to "ellipsis" which prints ….

Returns

string

Call Signature

overflow(overflow: string): this;

The symbol to use when indicating text overflow (text that is cut off because it doesn't fit within the set boundaries).

May be set to any string or the keyword "ellipsis".

By default this will be set to "ellipsis" which prints ….

Parameters
Parameter Type
overflow string
Returns

this

overflowLine()

Call Signature

overflowLine(): string;

The symbol to use when indicating a single line text overflow.

May be set to any string or "" to turn off line overflow cutoff.

By default this will be set to "" which will allow words longer than the width of the textbox to print in full.

Returns

string

Call Signature

overflowLine(overflow: string): this;

The symbol to use when indicating a single line text overflow.

May be set to any string or "" to turn off line overflow cutoff.

By default this will be set to "" which will allow words longer than the width of the textbox to print in full.

Parameters
Parameter Type
overflow string
Returns

this

overflowWrap()

Call Signature

overflowWrap(): OverflowWrap;

Controls whether line breaks should be inserted within an otherwise unbreakable string to prevent text from overflowing the textbox.

  • Set this to "break-word" to allow extra breaks mid-word.
  • Set this to "normal" to only allow natural breaks at whitespace, punctuation, or hyphens.

By default this will be set to "normal".

Returns

OverflowWrap

Call Signature

overflowWrap(wrap: OverflowWrap): this;

Controls whether line breaks should be inserted within an otherwise unbreakable string to prevent text from overflowing the textbox.

  • Set this to "break-word" to allow extra breaks mid-word.
  • Set this to "normal" to only allow natural breaks at whitespace, punctuation, or hyphens.

By default this will be set to "normal".

Parameters
Parameter Type
wrap OverflowWrap
Returns

this

parser()

Call Signature

parser(): (text: string) => Token[];

The parser to use when parsing text input.

  • Set it to "text" for plaintext parsing.
  • Set it to "html" for basic HTML parsing (it understands such things as <b>, <sup>, <tt>, ...).
  • Set it to "latex" for a very basic LaTeX parser (it understands basic text commands and punctuation - no math mode).

An alternative parser may be provided as a callback, as long as it conforms to the parser interface.

By default the parser is set to "text".

Returns
(text: string): Token[];
Parameters
Parameter Type
text string
Returns

Token[]

Call Signature

parser(parser: 
  | "text"
  | (text: string) => Token[]
  | "html"
  | "latex"): this;

The parser to use when parsing text input.

  • Set it to "text" for plaintext parsing.
  • Set it to "html" for basic HTML parsing (it understands such things as <b>, <sup>, <tt>, ...).
  • Set it to "latex" for a very basic LaTeX parser (it understands basic text commands and punctuation - no math mode).

An alternative parser may be provided as a callback, as long as it conforms to the parser interface.

By default the parser is set to "text".

Parameters
Parameter Type
parser | "text" | (text: string) => Token[] | "html" | "latex"
Returns

this

render()

Call Signature

render(text: string | Lines): SVGElement;

Render text or linebreak-output onto a Canvas or as an SVG element.

This method determines which render output is desired based on whether a canvas based target was supplied or not.

Parameters
Parameter Type
text string | Lines
Returns

SVGElement

Deprecated

Call Signature

render(text: string | Lines, target: OffscreenCanvas | HTMLCanvasElement | CanvasRenderingContext2D): void;

Render text or linebreak-output onto a Canvas or as an SVG element.

This method determines which render output is desired based on whether a canvas based target was supplied or not.

Parameters
Parameter Type
text string | Lines
target OffscreenCanvas | HTMLCanvasElement | CanvasRenderingContext2D
Returns

void

Deprecated

renderCanvas()

renderCanvas(text: string | Lines, target: OffscreenCanvas | HTMLCanvasElement | CanvasRenderingContext2D): void;

Render text or linebreak-output onto a Canvas.

Parameters

Parameter Type
text string | Lines
target OffscreenCanvas | HTMLCanvasElement | CanvasRenderingContext2D

Returns

void

renderSVG()

renderSVG(text: string | Lines): SVGElement;

Render text or linebreak-output as an SVG element.

The output will be a single root text element with the lines and sections contained within.

Parameters

Parameter Type
text string | Lines

Returns

SVGElement

valign()

Call Signature

valign(): VAlignment;

Controls the vertical alignment of the text.

By default this will be set to "top".

Returns

VAlignment

Call Signature

valign(align: VAlignment): this;

Controls the vertical alignment of the text.

By default this will be set to "top".

Parameters
Parameter Type
align VAlignment
Returns

this

width()

Call Signature

width(): number | NumberLineFunc;

Controls the width of the textbox in which to fit the text.

This can be a callback function if you want runaround text layout, or to flow the text into irregular space.

By default this will be set to Infinity which prints a text without linebreaks into a single line.

Returns

number | NumberLineFunc

Call Signature

width(width: number | NumberLineFunc): this;

Controls the width of the textbox in which to fit the text.

This can be a callback function if you want runaround text layout, or to flow the text into irregular space.

By default this will be set to Infinity which prints a text without linebreaks into a single line.

Parameters
Parameter Type
width number | NumberLineFunc
Returns

this

x()

Call Signature

x(): number | NumberLineFunc;

Controls the indentation of text lines.

This is useful for fitting text into non-rectanglular shapes. A callback provided as an argument this will be called every line with the line number as a parameter.

By default this will be set to 0.

Returns

number | NumberLineFunc

Call Signature

x(x: number | NumberLineFunc): this;

Controls the indentation of text lines.

This is useful for fitting text into non-rectanglular shapes. A callback provided as an argument this will be called every line with the line number as a parameter.

By default this will be set to 0.

Parameters
Parameter Type
x number | NumberLineFunc
Returns

this

htmlparser()

function htmlparser(text?: string | null): Token[];

Parse a very small subset of HTML.

This parser can handle linebreaks, as well as inline text instruction tags such as <b>, <tt>, <em>, <sup>.

Parameters

Parameter Type
text? string | null

Returns

Token[]

latexparser()

function latexparser(text?: string | null): Token[];

Parse a very small subset of LaTeX.

This parser can handle linebreaks, verbatim, as well as inline text instructions for non-math text. Math mode is not supported at all.

Parameters

Parameter Type
text? string | null

Returns

Token[]

measureText()

function measureText(
   token: string | Token, 
   font: string | FontProps, 
   options: MeasureOptions): number;

Measure a string of text as printed with a specified font and return its width.

Be careful that in non-browser environments you may want to supply an alternative canvas using setMeasureCanvas or this method will default to a crude "best guess" method.

Parameters

Parameter Type Default value Description
token string | Token undefined A string or token of text to measure.
font string | FontProps undefined A CSS font shorthand string or a collection of font properties.
options MeasureOptions defaultOptions Text handling options.

Returns

number

setMeasureCanvas()

function setMeasureCanvas(canvas: MinimalCanvas | null): void;

Set the canvas to use when measuring text. This will be needed when using measureText in a non-browser environment.

Parameters

Parameter Type Description
canvas MinimalCanvas | null The canvas interface to use.

Returns

void

textparser()

function textparser(text?: string | null): Token[];

A basic text parser that sections texts into words but also deals with inserting appropriate breaks at correct points.

Parameters

Parameter Type
text? string | null

Returns

Token[]

Break

Represents a unit of text, typically a single word.

Extends

Properties

Property Type Inherited from
font FontProps Token.font
line? number Token.line
value string Token.value
whitespace boolean | undefined Token.whitespace
width number Token.width

Methods

toJSON()

toJSON(): any;

Returns

any

Overrides

Token.toJSON

LineBreak

Represents a unit of text, typically a single word.

Extends

Properties

Property Type Inherited from
font FontProps Token.font
line? number Token.line
value string Token.value
whitespace boolean | undefined Token.whitespace
width number Token.width

Methods

toJSON()

toJSON(): any;

Returns

any

Overrides

Token.toJSON

SoftHyphen

Represents a unit of text, typically a single word.

Extends

Properties

Property Type Inherited from
font FontProps Token.font
line? number Token.line
value string Token.value
whitespace boolean | undefined Token.whitespace
width number Token.width

Methods

toJSON()

toJSON(): any;

Returns

any

Overrides

Token.toJSON

Token

Represents a unit of text, typically a single word.

Extended by

Properties

Property Type
font FontProps
line? number
value string
whitespace boolean | undefined
width number

Methods

toJSON()

toJSON(): any;

Returns

any

Alignment

type Alignment = "left" | "center" | "right" | "justify";

Text alignment.

FontProps

type FontProps = {
  baseline?: number;
  class?: string;
  color?: string;
  family?: string;
  height?: number;
  href?: string;
  rel?: string;
  size?: number;
  sizeAdjust?: number;
  style?: FontStyle;
  target?: string;
  tracking?: number;
  variant?: FontVariant;
  weight?: number;
};

A collection of font properties or styles.

Properties

Property Type Description
baseline? number Baseline adjustment factor (such as for sub-/superscript).
class? string Class identifier to be applied to emitted elements.
color? string Color of the text.
family? string Name of the font's type family.
height? number Height of the leading (line-height).
href? string HREF URL property for the text.
rel? string Rel identifier to be applied to emitted link elements (use with href).
size? number Size of the font in pixels.
sizeAdjust? number Size adjustment multiplier (such as for sub-/superscript).
style? FontStyle Style of the font (italics or not).
target? string Link target identifier to be applied to emitted link elements (use with href).
tracking? number Tracking (multiplier) for the text.
variant? FontVariant Variant of the font (Small-Caps or not).
weight? number Weight of the font as a number (400 is regular).

FontStyle

type FontStyle = "normal" | "italic";

Font style.

FontVariant

type FontVariant = "normal" | "small-caps";

Font variant.

HAlignment

type HAlignment = "left" | "center" | "right";

Horizontal alignment.

LayoutOptions

type LayoutOptions = {
  align: Alignment;
  createElement: CreateElementFunc;
  font: string;
  height: number | NumberFunc;
  overflow: Overflow;
  overflowLine: Overflow;
  overflowWrap: OverflowWrap;
  parser: (text: string) => Token[];
  valign: VAlignment;
  width: number | NumberLineFunc;
  x: number | NumberLineFunc;
};

Options for a textbox and how text flows inside it.

Properties

Property Type Default value Description
align Alignment "top" Horizontal alignment of the text.
createElement CreateElementFunc Infinity Factory function to use when constructing SVG elements.
font string Infinity Default font to use (as CSS shorthand).
height number | NumberFunc Infinity Height of the textbox in pixels.
overflow Overflow "ellipsis" The symbol to use when indicating text overflow ("…").
overflowLine Overflow "" Symbol to use when indicating line overflow, or "" when line overflow is off.
overflowWrap OverflowWrap "normal" Whether breaks should be inserted within an otherwise unbreakable word to prevent overflowing the textbox.
parser (text: string) => Token[] Textbox.defaultparser Which parser to use when parsing text input.
valign VAlignment "left" Vertical alignment of the text.
width number | NumberLineFunc Infinity Width of the textbox in pixels.
x number | NumberLineFunc 0 Line horizontal offset factor or per-line callback to control horizontal offset.

Line

type Line = Token[] & {
  width: number;
};

A (linebroken) line of Tokens

Type Declaration

width

width: number;

Lines

type Lines = Line[] & LinesProps;

A collection of flowed text lines & their properties.

LinesProps

type LinesProps = {
  font: FontProps;
  hasLineOverflow: boolean;
  hasOverflow: boolean;
  height: number;
  width: number;
};

Additional properties for linebroken text.

Properties

Property Type Description
font FontProps Default font properties used.
hasLineOverflow boolean Does any line have line-overflow?
hasOverflow boolean Did the text overflow?
height number Height of the layed-out text.
width number Width of the layed-out text.

MeasureOptions

type MeasureOptions = {
  collapse?: boolean;
  trim?: boolean;
};

Options for text measuring.

Properties

Property Type Default value Description
collapse? boolean true Should whitespace in the text get collapsed (like in HTML)?
trim? boolean true Should the text be trimmed before measuring?

MinimalCanvas

type MinimalCanvas = {
  getContext: (contextId: "2d") => MinimalCanvasContext | null;
};

Minimal Canvas interface needed.

Properties

Property Type
getContext (contextId: "2d") => MinimalCanvasContext | null

MinimalCanvasContext

type MinimalCanvasContext = {
  font: string;
  measureText: (text: string) => {
     width: number;
  };
};

Minimal CanvasRenderingContext2D interface needed.

Properties

Property Type
font string
measureText (text: string) => { width: number; }

NumberFunc()

type NumberFunc = () => number;

A function that emits a width or height in pixels.

Returns

number

NumberLineFunc()

type NumberLineFunc = (line?: number) => number;

A function accepting a line number that emits a width or height in pixels.

Parameters

Parameter Type
line? number

Returns

number

Overflow

type Overflow = "ellipsis" | string;

Overflow indication symbol.

OverflowWrap

type OverflowWrap = "break-word" | "normal";

Overflow wrap behavior.

RotatorOptions

type RotatorOptions = {
  anchor: string;
  createElement: CreateElementFunc;
  height: number;
  rotate: number;
  width: number;
};

Options for the Rotator class

Properties

Property Type Default value Description
anchor string "top left" An anchor point for the rotation orientation (such as top center)
createElement CreateElementFunc Rotator.createElement SVG Element factory
height number Infinity Height of the rotated box (in pixels)
rotate number 0 Rotation of the content (in degrees)
width number Infinity Width of the rotated box (in pixels)

VAlignment

type VAlignment = "top" | "middle" | "bottom";

Vertical alignment.