pixi-glyphs 4.0.2 → 4.1.0

package/README.md

@@ -48,7 +48,17 @@ The style objects are modified versions (supersets) of `PIXI.TextStyle` (referre
 
 (By the way, there is an excellent [TextStyle visual editor](https://pixijs.io/pixi-text-style/) that you can use to preview how your style will appear. The style objects generated can be used in this component.)
 
-- Everything in [`PIXI.TextStyle`](https://pixijs.download/dev/docs/PIXI.TextStyle.html)
+- Everything in [`PIXI.TextStyle`](https://pixijs.download/dev/docs/PIXI.TextStyle.html) including:
+  - `fontFamily` - The font family. e.g. `"Arial"` or `"Arial, Helvetica, sans-serif"`
+  - `fontStyle` - Font style. Options are `"normal"`, `"italic"`, `"oblique"`. Default is `"normal"`.
+  - `fontWeight` - Font weight. Options include `"normal"`, `"bold"`, `"bolder"`, `"lighter"`, `"100"` through `"900"`. Default is `"normal"`.
+  - `stroke` - Stroke color for the text. Default is `0x000000` (black).
+  - `strokeThickness` - Thickness of the stroke. Default is `0` (no stroke).
+  - `dropShadow` - Enable drop shadow. Default is `false`.
+  - `dropShadowColor` - Drop shadow color. Default is `0x000000`.
+  - `dropShadowBlur`, `dropShadowAngle`, `dropShadowDistance` - Drop shadow properties.
+  - `padding` - Padding around the text. Default is `0`.
+  - `trim` - Trim transparent borders. Default is `false`.
 - `align` - Has all the options from `PIXI.TextStyle` plus additional options for justified alignment:
   - `"justify-left"`, `"justify-right"`, and `"justify-center"` are all types of jutified alignment and they only differ in how they treat the last line of text.
   - `"justify-all"` justifies all lines of text even the last line.
@@ -58,11 +68,18 @@ The style objects are modified versions (supersets) of `PIXI.TextStyle` (referre
 - `fontSize` - Has the added ability to use percentage-based sizes which are based on the `fontSize` in the parent tag. In the example: `<small fontSize="10">small<big fontSize="300%">big</big></small>`, "small" will be 10px and "big" will be 30px. The default `fontSize` is `26`px.
 - `fontScaleWidth` - Percentage to scale the font e.g. `0.5` = 50%
 - `fontScaleHeight` - Percentage to scale the font e.g. `1.25` = 125%
+- `letterSpacing` - Additional horizontal spacing between each character in pixels. Can be positive to spread letters apart or negative to bring them closer together. Default is `0`.
+- `lineSpacing` - Additional vertical spacing between lines of text in pixels. This spacing is added between all lines within a paragraph. Default is `0`.
 - `paragraphSpacing` - Additional spacing between paragraphs that is added when you use an explicit carriage return rather than letting the text wrap at the end of a line. Default is `0`. Can also be negative.
 - `breakLines` - When `breakLines` is `false`, the text in the tag will ignore the `wordWrapWidth` property and never wrap to the next line unless you explicitly include a newline character. It essentially treats the whole tag as a single word. If a nested tag overrides this, only the text inside the nested tag will wrap. Default is `true`.
 - `imgSrc` - ID of image to include in this tag (see `imgMap` under Options section)
-- `imgDisplay` - How should the image be displayed. `"block"` is no scaling, `"icon"` scales the image to match the text-size and appear inline.
+- `imgDisplay` - How should the image be displayed. `"block"` is no scaling, `"icon"` scales the image to match the text-size and appear inline, `"inline"` displays at original size inline. Default is `"inline"`.
 - `iconScale` - If you use `imgDisplay="icon"`, this value will scale the size of the icon relative to the text size. Default is `1.0` (or 100%)
+- `imgScale` - Scales both width and height of an image by a percentage. e.g. `"50%"` makes the image half size.
+- `imgScaleX` - Scales only the width of an image by a percentage. e.g. `"200%"` makes the image twice as wide.
+- `imgScaleY` - Scales only the height of an image by a percentage. e.g. `"75%"` makes the image 3/4 of its original height.
+- `imgWidth` - Sets the width of an image in pixels or as a percentage. e.g. `100` or `"50%"`.
+- `imgHeight` - Sets the height of an image in pixels or as a percentage. e.g. `50` or `"150%"`.
 - `textDecoration` - (i.e. underlines) Adds lines under, over, or through your text. Possible values are either `"normal"` or one or more of `"underline"`, `"overline"`, `"line-through"` (as a space separated string). Can also be set using the more fine-grained properties below. By default, decorations have `color` that matches the `fill` color of the text, `thickness` of `1` and `offset` `0`. **Note: You may need to enabled the `drawWhitespace` option in `options` to avoid seeing gaps in your text decorations between words.**
 - `decorationColor` - overrides the default color (`fill`) for all decorations.
 - `decorationThickness` - overrides the default thickness (`1`) for all decorations.
@@ -76,6 +93,7 @@ The style objects are modified versions (supersets) of `PIXI.TextStyle` (referre
 - `lineThroughThickness` - Sets the thickness of the line-through. Default is `1`.
 - `lineThroughOffset` - Positions the line-through above or below the default location. Default is `0`.
 - `adjustBaseline` - Adjusts the position of the text above or below the baseline. Default is `0`. Also see the `adjustFontBaseline` property in the options.
+- `highlightColor` - Adds a background highlight color behind the text. Can be a hex number like `0xFFEB3B` or a hex string like `"#FFEB3B"`. The highlight appears as a continuous solid color box behind the text with no borders, spanning across spaces between words for a seamless highlight effect. When the same highlight color is applied to consecutive text segments, they will be rendered as a single continuous highlight box. Perfect for emphasizing important text, creating visual hierarchy, inline code blocks, or implementing syntax highlighting. Example: `<highlight>This entire phrase is highlighted</highlight>` will create one continuous highlight box.
 - `color` - An alias for `fill`. It's recommended you just use either `fill` or `color`, but if both are set, `fill` will be used. If tags are nested, `color` on an inner tag can override `fill` in an outer tag.
 
 Additionally, the following changes have been made to the default style values:
@@ -86,7 +104,7 @@ Additionally, the following changes have been made to the default style values:
 
 ##### 'Default' `default` styles
 
-Some styles (`fontSize`, `color`, etc.) are set by default when you call `new Glyphs()` but they can all be overridden. The most important default styles are:
+Some styles (`fontSize`, `color`, etc.) are set by default when you call `new Glyphs()` but they can all be overridden. The complete default styles are:
 
 ```javascript
 {
@@ -95,6 +113,12 @@ Some styles (`fontSize`, `color`, etc.) are set by default when you call `new Gl
   wordWrap: true,
   wordWrapWidth: 500,
   fill: 0x000000,
+  fontSize: 26,
+  stroke: 0x000000,
+  dropShadowColor: 0x000000,
+  imgDisplay: "inline",
+  iconScale: 1.0,
+  breakLines: true
 }
 ```
 
@@ -117,6 +141,8 @@ The third parameter in the Glyphs constructor is a set of options.
 - `supressConsole` - When `true`, prevents warnings and other messages from being logged to the console, however, this does **not** affect `debugConsole`.
 - `errorHandler` - A handler function that will receive non-fatal warnings and errors generated by the component. **This will not catch any exceptions**, only internal messaging such as when you try use an unknown tag. The handler should be in the format `(e:ErrorMessage) => void` where `ErrorMessage` is an object with the shape `{ code: string, message: string, type: "warning" | "error" }`.
 - `overdrawDecorations` - When using text decorations (e.g. `underline`) an additional length in pixels equal to `overdrawDecorations` will be added to _both_ sides of the line. Default is `0`.
+- `lineSpacing` - Sets the default line spacing for all text. Can also be set per-tag in styles. Default is `0`.
+- `paragraphSpacing` - Sets the default paragraph spacing for all text. Can also be set per-tag in styles. Default is `0`.
 
 To see a list of the default options, you can view the static property `Glyphs.defaultOptions` or look in the source code for `DEFAULT_OPTIONS`
 

package/dist/Glyphs.d.ts

@@ -39,6 +39,8 @@ export default class Glyphs<TextType extends PixiTextTypes = PIXI.Text> extends
     private _debugGraphics;
     private _textContainer;
     get textContainer(): PIXI.Container;
+    private _highlightContainer;
+    get highlightContainer(): PIXI.Container;
     private _decorationContainer;
     get decorationContainer(): PIXI.Container;
     private _spriteContainer;
@@ -58,6 +60,7 @@ export default class Glyphs<TextType extends PixiTextTypes = PIXI.Text> extends
     draw(): void;
     protected createDrawingForTextDecoration(textDecoration: TextDecorationMetrics): PIXI.Graphics;
     protected createTextField(text: string, style: TextStyleExtended): TextType;
+    protected createHighlightBox(highlightColor: any, x: number, y: number, width: number, height: number): PIXI.Graphics | null;
     protected createTextFieldForToken(token: TextSegmentToken): TextType;
     toDebugString(): string;
     drawDebug(): void;

package/dist/pixi-glyphs.js

@@ -1492,6 +1492,9 @@ class Glyphs extends PIXI__namespace.Container {
   get textContainer() {
     return this._textContainer;
   }
+  get highlightContainer() {
+    return this._highlightContainer;
+  }
   get decorationContainer() {
     return this._decorationContainer;
   }
@@ -1515,12 +1518,14 @@ class Glyphs extends PIXI__namespace.Container {
     this._spriteTemplates = {};
     this._debugGraphics = void 0;
     this._textContainer = void 0;
+    this._highlightContainer = void 0;
     this._decorationContainer = void 0;
     this._spriteContainer = void 0;
     this._debugContainer = void 0;
     this.logWarning = (code, message) => logWarning(this.options.errorHandler, this.options.supressConsole, this)(code, message);
     this._textContainer = new PIXI__namespace.Container();
     this._spriteContainer = new PIXI__namespace.Container();
+    this._highlightContainer = new PIXI__namespace.Container();
     this._decorationContainer = new PIXI__namespace.Container();
     this._debugContainer = new PIXI__namespace.Container();
     this._debugGraphics = new PIXI__namespace.Graphics();
@@ -1541,9 +1546,18 @@ class Glyphs extends PIXI__namespace.Container {
         ...userStyles
       };
     }
+    const styleOverrides = {
+      ...tagStyles.default
+    };
+    if (options.lineSpacing !== undefined) {
+      styleOverrides.lineSpacing = options.lineSpacing;
+    }
+    if (options.paragraphSpacing !== undefined) {
+      styleOverrides.paragraphSpacing = options.paragraphSpacing;
+    }
     const mergedDefaultStyles = {
       ...DEFAULT_STYLE,
-      ...tagStyles.default
+      ...styleOverrides
     };
     tagStyles.default = mergedDefaultStyles;
     this.tagStyles = tagStyles;
@@ -1588,6 +1602,12 @@ class Glyphs extends PIXI__namespace.Container {
     this._options = {};
   }
   resetChildren() {
+    if (this._highlightContainer) {
+      this._highlightContainer.removeChildren();
+      this.removeChild(this._highlightContainer);
+    }
+    this._highlightContainer = new PIXI__namespace.Container();
+    this.addChild(this._highlightContainer);
     if (this._textContainer) {
       this._textContainer.removeChildren();
       this.removeChild(this._textContainer);
@@ -1703,16 +1723,47 @@ class Glyphs extends PIXI__namespace.Container {
   }
   draw() {
     this.resetChildren();
-    if (this.textContainer === null || this.spriteContainer === null) {
-      throw new Error("Somehow the textContainer or spriteContainer is null. This shouldn't be possible. Perhaps you've destroyed this object?");
+    if (this.textContainer === null || this.spriteContainer === null || this.highlightContainer === null) {
+      throw new Error("Somehow the textContainer, spriteContainer, or highlightContainer is null. This shouldn't be possible. Perhaps you've destroyed this object?");
     }
     const textContainer = this.textContainer;
     const spriteContainer = this.spriteContainer;
+    const highlightContainer = this.highlightContainer;
     const {
       drawWhitespace
     } = this.options;
     const tokensFlat = this.tokensFlat;
     const tokens = drawWhitespace ? tokensFlat : tokensFlat.filter(isNotWhitespaceToken);
+    let i = 0;
+    while (i < tokensFlat.length) {
+      const token = tokensFlat[i];
+      if (isTextToken(token) && token.style.highlightColor !== undefined) {
+        const highlightColor = token.style.highlightColor;
+        let startX = token.bounds.x;
+        let minY = token.bounds.y;
+        let maxY = token.bounds.y + token.bounds.height;
+        let endX = token.bounds.x + token.bounds.width;
+        let j = i + 1;
+        while (j < tokensFlat.length) {
+          const nextToken = tokensFlat[j];
+          if (isTextToken(nextToken) && nextToken.style.highlightColor === highlightColor && Math.abs(nextToken.bounds.y - token.bounds.y) < 5) {
+            endX = nextToken.bounds.x + nextToken.bounds.width;
+            minY = Math.min(minY, nextToken.bounds.y);
+            maxY = Math.max(maxY, nextToken.bounds.y + nextToken.bounds.height);
+            j++;
+          } else {
+            break;
+          }
+        }
+        const highlight = this.createHighlightBox(highlightColor, startX, minY, endX - startX, maxY - minY);
+        if (highlight) {
+          highlightContainer.addChild(highlight);
+        }
+        i = j;
+      } else {
+        i++;
+      }
+    }
     let drewDecorations = false;
     let displayObject;
     tokens.forEach((t, index) => {
@@ -1816,6 +1867,28 @@ class Glyphs extends PIXI__namespace.Container {
     });
     return textField;
   }
+  createHighlightBox(highlightColor, x, y, width, height) {
+    if (!highlightColor || width <= 0 || height <= 0) {
+      return null;
+    }
+    const highlight = new PIXI__namespace.Graphics();
+    let color = highlightColor;
+    if (typeof color === "string") {
+      if (color.indexOf("#") === 0) {
+        color = "0x" + color.substring(1);
+        color = parseInt(color, 16);
+      } else {
+        this.logWarning("invalid-highlight-color", "Sorry, at this point, only hex colors are supported for highlightColor. Please use either a hex number like 0x66FF33 or a string like '#66FF33'");
+        color = 0xFFFF00;
+      }
+    }
+    highlight.rect(0, 0, width, height).fill({
+      color: color
+    });
+    highlight.x = x;
+    highlight.y = y;
+    return highlight;
+  }
   createTextFieldForToken(token) {
     const {
       textTransform = ""