@sepveneto/dao 0.0.4 → 0.1.0

package/dist/scene/text/TextStyle.d.ts

@@ -0,0 +1,632 @@
+import { DestroyOptions } from '../container/destroyTypes';
+/**
+ * The alignment of the text.
+ *
+ * - 'left': Aligns text to the left edge.
+ * - 'center': Centers text horizontally.
+ * - 'right': Aligns text to the right edge.
+ * - 'justify': Justifies text, aligning both left and right edges.
+ * @example
+ * ```ts
+ * import { TextStyle } from 'pixi.js';
+ * const style = new TextStyle({
+ *   align: 'center', // or 'left', 'right', 'justify'
+ * });
+ * ```
+ * @category text
+ * @standard
+ */
+export type TextStyleAlign = 'left' | 'center' | 'right' | 'justify';
+/**
+ * The font style input for text styles. Controls the slant or italicization of the text.
+ * @example
+ * ```ts
+ * // Create text with normal font style
+ * const normalText = new Text({
+ *     text: 'Normal Style Text',
+ *     style: {
+ *         fontStyle: 'normal',
+ *         fontSize: 24
+ *     }
+ * });
+ *
+ * // Create italic text
+ * const italicText = new Text({
+ *     text: 'Italic Style Text',
+ *     style: {
+ *         fontStyle: 'italic',
+ *         fontSize: 24,
+ *         fontFamily: 'Arial'
+ *     }
+ * });
+ *
+ * // Create oblique text
+ * const obliqueText = new Text({
+ *     text: 'Oblique Style Text',
+ *     style: {
+ *         fontStyle: 'oblique',
+ *         fontSize: 24,
+ *         fontFamily: 'Times New Roman'
+ *     }
+ * });
+ *
+ * // Dynamic style changes
+ * let isItalic = false;
+ * text.style = {
+ *     ...text.style,
+ *     fontStyle: isItalic ? 'italic' : 'normal'
+ * };
+ * ```
+ *
+ * Supported values:
+ * - 'normal': Regular upright text with no slant
+ * - 'italic': True italics using specifically designed italic glyphs
+ * - 'oblique': Slanted version of the regular glyphs
+ * @remarks
+ * - 'italic' uses specially designed glyphs with cursive characteristics
+ * - 'oblique' is a mechanical slant of the normal glyphs
+ * - Not all fonts include true italic designs; some may fall back to oblique
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font-style | MDN font-style}
+ * @category text
+ * @standard
+ */
+export type TextStyleFontStyle = 'normal' | 'italic' | 'oblique';
+/**
+ * The font variant input for text styles. Controls the capitalization and presentation of letters.
+ * Used to enable special rendering like small caps.
+ * @example
+ * ```ts
+ * // Create text with normal font variant
+ * const normalText = new Text({
+ *     text: 'Normal Text',
+ *     style: {
+ *         fontVariant: 'normal',
+ *         fontSize: 24
+ *     }
+ * });
+ *
+ * // Create text with small-caps variant
+ * const smallCapsText = new Text({
+ *     text: 'Small Caps Text',
+ *     style: {
+ *         fontVariant: 'small-caps',
+ *         fontSize: 24,
+ *         fontFamily: 'Arial'
+ *     }
+ * });
+ *
+ * // Use in a TextStyle instance
+ * const style = new TextStyle({
+ *     fontVariant: 'small-caps',
+ *     fontSize: 32,
+ *     fill: 0x4a4a4a
+ * });
+ *
+ * // Update variant dynamically
+ * text.style = {
+ *     ...text.style,
+ *     fontVariant: text.style.fontVariant === 'normal' ? 'small-caps' : 'normal'
+ * };
+ * ```
+ *
+ * Supported values:
+ * - 'normal': Regular text rendering with standard capitalization
+ * - 'small-caps': Renders lowercase letters as smaller versions of capital letters
+ * @remarks
+ * Small caps are only available if the font supports them.
+ * Not all fonts include true small caps glyphs.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant | MDN font-variant}
+ * @category text
+ * @standard
+ */
+export type TextStyleFontVariant = 'normal' | 'small-caps';
+/**
+ * The font weight input for text styles. Controls the thickness or boldness of the text.
+ * @example
+ * ```ts
+ * // Create text with different font weights
+ * const normalText = new Text({
+ *     text: 'Normal Weight',
+ *     style: { fontWeight: 'normal' }
+ * });
+ *
+ * const boldText = new Text({
+ *     text: 'Bold Weight',
+ *     style: { fontWeight: 'bold' }
+ * });
+ *
+ * // Using numeric weights
+ * const lightText = new Text({
+ *     text: 'Light Weight',
+ *     style: { fontWeight: '300' }
+ * });
+ *
+ * const mediumText = new Text({
+ *     text: 'Medium Weight',
+ *     style: { fontWeight: '500' }
+ * });
+ *
+ * const heavyText = new Text({
+ *     text: 'Heavy Weight',
+ *     style: { fontWeight: '900' }
+ * });
+ *
+ * // Responsive weight changes
+ * const adaptiveText = new Text({
+ *     text: 'Adaptive Weight',
+ *     style: { fontWeight: window.innerWidth > 600 ? 'bold' : 'normal' }
+ * });
+ * ```
+ *
+ * Supported values:
+ * - 'normal': Standard weight (equivalent to 400)
+ * - 'bold': Bold weight (equivalent to 700)
+ * - 'bolder': One weight darker than the parent element
+ * - 'lighter': One weight lighter than the parent element
+ * - '100': Thin (Hairline)
+ * - '200': Extra Light (Ultra Light)
+ * - '300': Light
+ * - '400': Normal
+ * - '500': Medium
+ * - '600': Semi Bold (Demi Bold)
+ * - '700': Bold
+ * - '800': Extra Bold (Ultra Bold)
+ * - '900': Heavy (Black)
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight | MDN font-weight}
+ * @category text
+ * @standard
+ */
+export type TextStyleFontWeight = 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+/**
+ * The line join style for text strokes. Determines how lines connect at corners.
+ * @example
+ * ```ts
+ * // Create text with miter joins (sharp corners)
+ * const sharpText = new Text({
+ *     text: 'Sharp Corners',
+ *     style: {
+ *         fontSize: 36,
+ *         stroke: {
+ *             color: '#4a1850',
+ *             width: 4,
+ *             lineJoin: 'miter'  // Sharp corners
+ *         }
+ *     }
+ * });
+ *
+ * // Create text with round joins
+ * const roundText = new Text({
+ *     text: 'Rounded Corners',
+ *     style: {
+ *         fontSize: 36,
+ *         stroke: {
+ *             color: '#4a1850',
+ *             width: 4,
+ *             lineJoin: 'round'  // Smooth rounded corners
+ *         }
+ *     }
+ * });
+ *
+ * // Create text with beveled joins
+ * const bevelText = new Text({
+ *     text: 'Beveled Corners',
+ *     style: {
+ *         fontSize: 36,
+ *         stroke: {
+ *             color: '#4a1850',
+ *             width: 4,
+ *             lineJoin: 'bevel'  // Flattened corners
+ *         }
+ *     }
+ * });
+ * ```
+ * Available values:
+ * - 'miter': Creates sharp corners by extending the outer edges until they meet
+ * - 'round': Creates smooth, rounded corners using a circular arc
+ * - 'bevel': Creates flattened corners by filling an additional triangle between the outer edges
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin | MDN lineJoin}
+ * @category text
+ * @standard
+ */
+export type TextStyleLineJoin = 'miter' | 'round' | 'bevel';
+/**
+ * The text baseline for text styles.
+ *
+ * This can be:
+ * - 'alphabetic': The alphabetic baseline
+ * - 'top': The top of the text
+ * - 'hanging': The hanging baseline
+ * - 'middle': The middle of the text
+ * - 'ideographic': The ideographic baseline
+ * - 'bottom': The bottom of the text
+ * @category text
+ * @standard
+ */
+export type TextStyleTextBaseline = 'alphabetic' | 'top' | 'hanging' | 'middle' | 'ideographic' | 'bottom';
+/**
+ * Controls how whitespace (spaces, tabs, and line breaks) is handled within the text.
+ * This affects text wrapping and spacing behavior.
+ * @example
+ * ```ts
+ * // Normal mode (collapse spaces and newlines)
+ * const normalText = new Text({
+ *     text: 'Hello    World\n\nNew Line',
+ *     style: {
+ *         whiteSpace: 'normal',
+ *         fontSize: 24
+ *     }
+ * }); // Renders as: "Hello World New Line"
+ *
+ * // Pre mode (preserve all whitespace)
+ * const preText = new Text({
+ *     text: 'Hello    World\n\nNew Line',
+ *     style: {
+ *         whiteSpace: 'pre',
+ *         fontSize: 24
+ *     }
+ * }); // Preserves spaces and line breaks exactly
+ *
+ * // Pre-line mode (preserve newlines, collapse spaces)
+ * const preLineText = new Text({
+ *     text: 'Hello    World\n\nNew Line',
+ *     style: {
+ *         whiteSpace: 'pre-line',
+ *         fontSize: 24
+ *     }
+ * }); // Preserves line breaks, collapses multiple spaces
+ *
+ * // With word wrap enabled
+ * const wrappedText = new Text({
+ *     text: 'A long text with    multiple spaces\nand line breaks',
+ *     style: {
+ *         whiteSpace: 'pre-line',
+ *         wordWrap: true,
+ *         wordWrapWidth: 200,
+ *         fontSize: 24
+ *     }
+ * });
+ * ```
+ *
+ * Supported values:
+ * - 'normal': Collapses all whitespace (spaces, tabs, line breaks) into a single space
+ * - 'pre': Preserves all whitespace characters exactly as written
+ * - 'pre-line': Preserves line breaks but collapses multiple spaces into a single space
+ * @remarks
+ * - 'normal' is best for single-line text or when you want to ignore formatting
+ * - 'pre' is useful for code blocks or when exact spacing is important
+ * - 'pre-line' is good for formatted text where you want to keep line breaks but clean up spaces
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/white-space | MDN white-space}
+ * @see {@link TextStyle#wordWrap} For controlling text wrapping
+ * @category text
+ * @standard
+ */
+export type TextStyleWhiteSpace = 'normal' | 'pre' | 'pre-line';
+/**
+ * Defines a drop shadow effect for text rendering.
+ * Drop shadows add depth and emphasis to text by creating a shadow offset from the text.
+ * @example
+ * ```ts
+ * // Create text with basic drop shadow
+ * const text = new Text({
+ *     text: 'Shadow Text',
+ *     style: {
+ *         fontSize: 48,
+ *         dropShadow: {
+ *             alpha: 0.5,         // 50% opacity shadow
+ *             angle: Math.PI / 6, // 30 degrees
+ *             blur: 4,            // Soft shadow edge
+ *             color: '#000000',   // Black shadow
+ *             distance: 6         // Shadow offset
+ *         }
+ *     }
+ * });
+ *
+ * // Dynamic shadow updates
+ * text.style.dropShadow = {
+ *     alpha: Math.sin(Date.now() / 1000) * 0.5 + 0.5, // Pulsing opacity
+ *     angle: Date.now() / 1000,                        // Rotating angle
+ *     blur: 4,
+ *     color: '#000000',
+ *     distance: 6
+ * };
+ * ```
+ * @category text
+ * @standard
+ */
+export type TextDropShadow = {
+    /**
+     * The opacity of the drop shadow.
+     * - Range: 0 to 1
+     * - 0 = fully transparent
+     * - 1 = fully opaque
+     * @example
+     * ```ts
+     * // Set drop shadow opacity to 50%
+     * dropShadow: {
+     *    alpha: 0.5
+     * }
+     * ```
+     * @default 1
+     */
+    alpha: number;
+    /**
+     * The angle of the drop shadow in radians.
+     * - 0 = right
+     * - Math.PI/2 = down
+     * - Math.PI = left
+     * - Math.PI*1.5 = up
+     * @example
+     * ```ts
+     * // Set drop shadow angle to 30 degrees
+     * dropShadow: {
+     *    angle: Math.PI / 6 // 30 degrees
+     * }
+     * ```
+     * @default Math.PI/6 (30 degrees)
+     */
+    angle: number;
+    /**
+     * The blur radius of the shadow.
+     * - 0 = sharp shadow
+     * - Higher values = softer shadow
+     * @example
+     * ```ts
+     * // Set drop shadow blur radius to 10 pixels
+     * dropShadow: {
+     *   blur: 10
+     * }
+     * ```
+     * @default 0
+     */
+    blur: number;
+    /**
+     * The color of the drop shadow.
+     * Accepts any valid CSS color string, hex number, or RGB/RGBA values.
+     * @example '#000000', 'rgba(0,0,0,0.5)', 0x000000
+     * @default 'black'
+     */
+    color: string;
+    /**
+     * The distance of the drop shadow from the text.
+     * Measured in pixels.
+     * @example
+     * ```ts
+     * // Set drop shadow distance to 5 pixels
+     * dropShadow: {
+     *   distance: 5
+     * }
+     * ```
+     * @default 5
+     */
+    distance: number;
+};
+/**
+ * Constructor options used for `TextStyle` instances. Defines the visual appearance and layout of text.
+ * @example
+ * ```ts
+ * // Basic text style
+ * const basicStyle = new TextStyle({
+ *     fontSize: 24,
+ *     fill: 'black',
+ *     fontFamily: 'Arial'
+ * });
+ *
+ * // Rich text style with multiple features
+ * const richStyle = new TextStyle({
+ *     fontFamily: ['Arial', 'Helvetica', 'sans-serif'],
+ *     fontSize: 36,
+ *     fontWeight: 'bold',
+ *     fill: 'red',
+ *     stroke: { color: '#4a1850', width: 5 },
+ *     align: 'center',
+ *     dropShadow: {
+ *         color: '#000000',
+ *         blur: 4,
+ *         distance: 6,
+ *         angle: Math.PI / 6
+ *     },
+ *     wordWrap: true,
+ *     wordWrapWidth: 440,
+ *     lineHeight: 40,
+ *     textBaseline: 'middle'
+ * });
+ * ```
+ * @see {@link TextStyle} For the main style class
+ * @category text
+ * @standard
+ */
+export interface TextStyleOptions {
+    /**
+     * Alignment for multiline text, does not affect single line text
+     * @default 'left'
+     */
+    align?: TextStyleAlign;
+    /**
+     * Whether to allow line breaks within words.
+     * Requires wordWrap to be true.
+     * @example
+     * ```ts
+     * // Enable word breaking
+     * const style = new TextStyle({
+     *    breakWords: true,
+     *    wordWrap: true,
+     *    wordWrapWidth: 200
+     * });
+     * ```
+     * @default false
+     */
+    breakWords?: boolean;
+    /**
+     * Drop shadow configuration for the text.
+     * Can be boolean or a TextDropShadow object.
+     * @default null
+     */
+    dropShadow?: boolean | Partial<TextDropShadow>;
+    /**
+     * Fill style for the text.
+     * Can be a color, gradient, or pattern.
+     * @default 'black'
+     */
+    fill?: string;
+    /**
+     * Font family or families to use.
+     * Can be single name or array of fallbacks.
+     * @example
+     * ```ts
+     * // Single font family
+     * fontFamily: 'Arial'
+     * // Multiple font families
+     * fontFamily: ['Helvetica', 'Arial', 'sans-serif']
+     * ```
+     * @default 'Arial'
+     */
+    fontFamily?: string | string[];
+    /**
+     * Font size in pixels or as string.
+     *
+     * Equivalents are '26px','20pt','160%' or '1.6em')
+     * @example
+     * ```ts
+     * // Numeric size
+     * fontSize: 26
+     * // String size
+     * fontSize: '26px'
+     * // Percentage size
+     * fontSize: '160%' // 1.6 times the parent element's font size
+     * // Em size
+     * fontSize: '1.6em' // 1.6 times the parent element's font size
+     * @default 26
+     */
+    fontSize?: number | string;
+    /**
+     * Font style (normal, italic, oblique).
+     * @default 'normal'
+     */
+    fontStyle?: TextStyleFontStyle;
+    /**
+     * Font variant (normal, small-caps).
+     * @default 'normal'
+     */
+    fontVariant?: TextStyleFontVariant;
+    /**
+     * Font weight (normal, bold, bolder, lighter, 100-900).
+     * @default 'normal'
+     */
+    fontWeight?: TextStyleFontWeight;
+    /** The height of the line, a number that represents the vertical space that a letter uses. */
+    leading?: number;
+    /** The amount of spacing between letters, default is 0 */
+    letterSpacing?: number;
+    /** The line height, a number that represents the vertical space that a letter uses */
+    lineHeight?: number;
+    /**
+     * Padding around the text.
+     *
+     * Occasionally some fonts are cropped. Adding some padding will prevent this from
+     * happening by adding padding to all sides of the text.
+     */
+    padding?: number;
+    /**
+     * Stroke style for text outline.
+     * @default null
+     */
+    stroke?: string;
+    /**
+     * Vertical alignment baseline.
+     * @default 'alphabetic'
+     */
+    textBaseline?: TextStyleTextBaseline;
+    /**
+     * Whether to trim transparent edges.
+     * > [!NOTE] This is an expensive operation and should only be used when necessary.
+     * @default false
+     */
+    trim?: boolean;
+    /**
+     * How to handle whitespace.
+     *
+     * It needs wordWrap to be set to true for this to have an effect.
+     * @default 'pre'
+     */
+    whiteSpace?: TextStyleWhiteSpace;
+    /** Indicates if word wrap should be used */
+    wordWrap?: boolean;
+    /** The width at which text will wrap, it needs wordWrap to be set to true */
+    wordWrapWidth?: number;
+    /**
+     * Custom styles to apply to specific tags within the text.
+     * Allows for rich text formatting using simple tag markup like `<red>text</red>`.
+     *
+     * Tags are only parsed when this property has entries. If `tagStyles` is empty or undefined,
+     * `<` characters in text are treated as literal.
+     *
+     * Nested tags are supported via a style stack - inner tags inherit from outer tags
+     * but can override specific properties.
+     * @example
+     * ```ts
+     * const text = new Text({
+     *     text: '<red>Red</red>, <blue>Blue</blue>, <big>Big</big>',
+     *     style: {
+     *         fontFamily: 'Arial',
+     *         fontSize: 24,
+     *         fill: 'white',
+     *         tagStyles: {
+     *             red: { fill: 'red' },
+     *             blue: { fill: 'blue' },
+     *             big: { fontSize: 48 }
+     *         }
+     *     }
+     * });
+     * ```
+     * @default undefined
+     */
+    tagStyles?: Record<string, TextStyleOptions>;
+}
+export declare class TextStyle {
+    uid: number;
+    static defaultStyle: TextStyleOptions;
+    private _cachedFontString;
+    private _fontSize;
+    private _fontFamily;
+    private _fontStyle;
+    private _lineHeight;
+    private _leading;
+    private _fontVariant;
+    private _fontWeight;
+    private _letterSpacing;
+    private _textBaseline;
+    private _align;
+    private _wordWrap;
+    private _fill;
+    _tick: 0;
+    constructor(style: Partial<TextStyleOptions>);
+    get styleKey(): string;
+    get fontSize(): number;
+    set fontSize(value: number);
+    get fill(): string;
+    set fill(value: string);
+    get align(): TextStyleAlign;
+    set align(value: TextStyleAlign);
+    get wordWarp(): boolean;
+    set wordWrap(value: boolean);
+    get fontFamily(): string | string[];
+    set fontFamily(value: string | string[]);
+    get leading(): number;
+    set leading(value: number);
+    get fontStyle(): TextStyleFontStyle;
+    set fontStyle(value: TextStyleFontStyle);
+    get textBaseline(): TextStyleTextBaseline;
+    set textBaseline(value: TextStyleTextBaseline);
+    get lineHeight(): number;
+    set lineHeight(value: number);
+    get letterSpacing(): number;
+    set letterSpacing(value: number);
+    get fontVariant(): TextStyleFontVariant;
+    set fontVariant(value: TextStyleFontVariant);
+    get fontWeight(): TextStyleFontWeight;
+    set fontWeight(value: TextStyleFontWeight);
+    get _fontString(): string;
+    update(): void;
+    destroy(_options?: DestroyOptions): void;
+}
+export declare function fontStringFromTextStyle(style: TextStyle): string;

package/dist/scene/text/TextSystem.d.ts

@@ -0,0 +1,19 @@
+import { CanvasRenderer } from '../../renderer';
+import { Text } from './Text';
+import { TextStyle } from './TextStyle';
+import { Texture } from '../../renderer/texture/Texture';
+import { TextureSource } from '../../renderer/texture/TextureSource';
+export declare class TextSystem {
+    static desc: {
+        readonly name: "text";
+    };
+    readonly renderer: CanvasRenderer;
+    private readonly _activeTexture;
+    constructor(renderer: CanvasRenderer);
+    getManagedTexture(text: Text): Texture<TextureSource<any>>;
+    getTexture(options: {
+        text: string;
+        style: TextStyle;
+        resolution: number;
+    }): Texture<TextureSource<HTMLCanvasElement | OffscreenCanvas>>;
+}

package/dist/scene/text/__tests__/Text.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scene/text/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Text';
+export * from './TextPipe';