textmode.js 0.7.1 → 0.8.0-beta.2

package/dist/types/textmode/managers/MouseManager.d.ts

@@ -1,17 +1,22 @@
 import type { TextmodeCanvas } from '../Canvas';
 import type { TextmodeGrid } from '../Grid';
 /**
- * Mouse coordinates in grid space.
+ * Mouse coordinates in grid space using center-based coordinates.
  *
- * Unlike the main drawing logic, where `(0,0,0)` is the center cell,
- * the mouse coordinates use the top-left cell as `(0,0)`. This means
- * you'll need to adjust accordingly when using these coordinates
- * for drawing or other grid operations.
+ * The coordinate system matches the main drawing/rendering space:
+ * - `(0, 0)` is the center cell of the grid
+ * - Negative X values are to the left of center
+ * - Positive X values are to the right of center
+ * - Negative Y values are above center
+ * - Positive Y values are below center
+ *
+ * When the mouse is outside the grid bounds, both `x` and `y` are set to
+ * `Number.NEGATIVE_INFINITY` to indicate an invalid/outside position.
  */
 export interface MousePosition {
-    /** Grid X coordinate (column), -1 if mouse is outside grid */
+    /** Grid X coordinate (column) in center-based coords. `Number.NEGATIVE_INFINITY` if outside grid. */
     x: number;
-    /** Grid Y coordinate (row), -1 if mouse is outside grid */
+    /** Grid Y coordinate (row) in center-based coords. `Number.NEGATIVE_INFINITY` if outside grid. */
     y: number;
 }
 /**
@@ -38,6 +43,10 @@ export interface MouseEventData {
  * Mouse event handler function type
  */
 export type MouseEventHandler = (data: MouseEventData) => void;
+/**
+ * Grid provider function type - returns the grid to use for coordinate calculations
+ */
+export type GridProvider = () => TextmodeGrid | undefined;
 /**
  * Manages all mouse interaction for a Textmodifier instance.
  * Handles event listeners, coordinate conversion, and event dispatching.
@@ -45,7 +54,7 @@ export type MouseEventHandler = (data: MouseEventData) => void;
  */
 export declare class MouseManager {
     private _canvas;
-    private _grid;
+    private _getGrid;
     private _mousePosition;
     private _previousMousePosition;
     private _lastClientCoordinates;
@@ -62,7 +71,12 @@ export declare class MouseManager {
     private _mouseReleasedCallback?;
     private _mouseMovedCallback?;
     private _mouseScrolledCallback?;
-    constructor(canvas: TextmodeCanvas);
+    /**
+     * Create a new MouseManager.
+     * @param canvas The canvas to track mouse events on.
+     * @param getGrid A function that returns the grid to use for coordinate calculations.
+     */
+    constructor(canvas: TextmodeCanvas, getGrid: GridProvider);
     /**
      * Temporarily suppress mouse event callbacks for a duration in milliseconds.
      * Used to prevent synthetic mouse events from touch interactions from firing twice.
@@ -77,10 +91,6 @@ export declare class MouseManager {
      * Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/cursor
      */
     $setCursor(cursor?: string): void;
-    /**
-     * Update the grid reference (useful when grid changes after font loading)
-     */
-    $initialize(grid: TextmodeGrid): void;
     /**
      * Setup mouse event listeners on the canvas.
      */
@@ -147,7 +157,7 @@ export declare class MouseManager {
     private _handleMouseScrolled;
     /**
      * Update mouse position based on mouse event.
-     * Converts pixel coordinates to grid coordinates.
+     * Converts pixel coordinates to center-based grid coordinates.
      */
     private _updateMousePosition;
 }

package/dist/types/textmode/managers/TouchManager.d.ts

@@ -1,15 +1,24 @@
 import type { TextmodeCanvas } from '../Canvas';
-import type { TextmodeGrid } from '../Grid';
-import type { MouseManager } from './MouseManager';
+import type { MouseManager, GridProvider } from './MouseManager';
 /**
- * Touch position expressed both in grid and client coordinates
+ * Touch position expressed both in grid and client coordinates.
+ *
+ * The grid coordinate system uses center-based coordinates matching the rendering space:
+ * - `(0, 0)` is the center cell of the grid
+ * - Negative X values are to the left of center
+ * - Positive X values are to the right of center
+ * - Negative Y values are above center
+ * - Positive Y values are below center
+ *
+ * When the touch is outside the grid bounds, `x` and `y` are set to
+ * `Number.NEGATIVE_INFINITY` to indicate an invalid/outside position.
  */
 export interface TouchPosition {
     /** Identifier provided by the browser for a touch point */
     id: number;
-    /** Grid X coordinate (column), -1 if touch is outside grid */
+    /** Grid X coordinate (column) in center-based coords. `Number.NEGATIVE_INFINITY` if outside grid. */
     x: number;
-    /** Grid Y coordinate (row), -1 if touch is outside grid */
+    /** Grid Y coordinate (row) in center-based coords. `Number.NEGATIVE_INFINITY` if outside grid. */
     y: number;
     /** Client X coordinate in CSS pixels */
     clientX: number;
@@ -27,10 +36,9 @@ export interface TouchPosition {
 /**
  * Touch event data.
  *
- * Unlike the main drawing logic, where `(0,0,0)` is the center cell,
- * the mouse coordinates use the top-left cell as `(0,0)`. This means
- * you'll need to adjust accordingly when using these coordinates
- * for drawing or other grid operations.
+ * The coordinate system uses center-based coordinates matching the main rendering space:
+ * - `(0, 0)` is the center cell of the grid
+ * - Coordinates can be used directly with `translate()` and other drawing functions
  */
 export interface TouchEventData {
     /** The touch point that triggered this event */
@@ -153,7 +161,7 @@ export type TouchRotateHandler = (data: TouchRotateEventData) => void;
 export declare class TouchManager {
     private readonly _canvas;
     private readonly _mouseManager?;
-    private _grid;
+    private readonly _getGrid;
     private _activeTouches;
     private _previousTouches;
     private _touchInfo;
@@ -187,9 +195,13 @@ export declare class TouchManager {
     private readonly _mouseSuppressionDuration;
     private _lastTapTime;
     private _lastTapPosition;
-    constructor(canvas: TextmodeCanvas, mouseManager?: MouseManager);
-    /** Initialise the manager with the active grid */
-    $initialize(grid: TextmodeGrid): void;
+    /**
+     * Create a new TouchManager.
+     * @param canvas The canvas to track touch events on.
+     * @param getGrid A function that returns the grid to use for coordinate calculations.
+     * @param mouseManager Optional mouse manager for suppressing mouse events during touch.
+     */
+    constructor(canvas: TextmodeCanvas, getGrid: GridProvider, mouseManager?: MouseManager);
     /** Install touch listeners onto the canvas */
     $setupListeners(): void;
     /** Remove all touch listeners */

package/dist/types/textmode/mixins/index.d.ts

@@ -1,10 +1,9 @@
 export { type Constructor, type Mixin, $applyMixins } from './TextmodifierMixin';
 export { RenderingMixin } from './RenderingMixin';
-export { FontMixin } from './FontMixin';
 export { AnimationMixin } from './AnimationMixin';
 export { MouseMixin } from './MouseMixin';
 export { TouchMixin } from './TouchMixin';
 export { KeyboardMixin } from './KeyboardMixin';
 export type { MousePosition, MouseEventData, MouseEventHandler } from '../managers/MouseManager';
 export type { KeyboardEventData, KeyboardEventHandler, KeyState } from '../managers/KeyboardManager';
-export type { TouchEventData, TouchLongPressEventData, TouchPinchEventData, TouchPosition, TouchRotateEventData, TouchSwipeEventData, TouchTapEventData } from '../managers/TouchManager';
+export type { TouchEventData, TouchLongPressEventData, TouchPinchEventData, TouchPosition, TouchRotateEventData, TouchSwipeEventData, TouchTapEventData, } from '../managers/TouchManager';

package/dist/types/textmode/mixins/interfaces/IAnimationMixin.d.ts

@@ -30,57 +30,57 @@ export interface IAnimationMixin {
      * it to be resumed later with {@link loop}. This is useful for temporarily pausing
      * animation while maintaining the ability to continue it.
      *
-    * @example
-    * ```javascript
-    * const t = textmode.create({ width: 800, height: 600 });
-    *
-    * // Toggle loop on SPACE
-    * t.keyPressed((data) => {
-    *   if (data.key === ' ') {
-    *     if (t.isLooping()) {
-    *       t.noLoop();
-    *     } else {
-    *       t.loop();
-    *     }
-    *   }
-    * });
-    *
-    * t.draw(() => {
-    *   t.background(0);
-    *   t.char('A');
-    *   t.charColor(255, 255, 255);
-    *   t.rotateZ(t.frameCount * 2);
-    *   t.rect(16, 16);
-    * });
-    * ```
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * // Toggle loop on SPACE
+     * t.keyPressed((data) => {
+     *   if (data.key === ' ') {
+     *     if (t.isLooping()) {
+     *       t.noLoop();
+     *     } else {
+     *       t.loop();
+     *     }
+     *   }
+     * });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.char('A');
+     *   t.charColor(255, 255, 255);
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(16, 16);
+     * });
+     * ```
      */
     noLoop(): void;
     /**
      * Resume the rendering loop if it was stopped by {@link noLoop}.
      *
-    * @example
-    * ```javascript
-    * const t = textmode.create({ width: 800, height: 600 });
-    *
-    * // Toggle loop on SPACE
-    * t.keyPressed((data) => {
-    *   if (data.key === ' ') {
-    *     if (t.isLooping()) {
-    *       t.noLoop();
-    *     } else {
-    *       t.loop();
-    *     }
-    *   }
-    * });
-    *
-    * t.draw(() => {
-    *   t.background(0);
-    *   t.char('A');
-    *   t.charColor(255, 255, 255);
-    *   t.rotateZ(t.frameCount * 2);
-    *   t.rect(16, 16);
-    * });
-    * ```
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * // Toggle loop on SPACE
+     * t.keyPressed((data) => {
+     *   if (data.key === ' ') {
+     *     if (t.isLooping()) {
+     *       t.noLoop();
+     *     } else {
+     *       t.loop();
+     *     }
+     *   }
+     * });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.char('A');
+     *   t.charColor(255, 255, 255);
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(16, 16);
+     * });
+     * ```
      */
     loop(): void;
     /**
@@ -93,47 +93,47 @@ export interface IAnimationMixin {
      *
      * @example
      * ```javascript
-    * // Press SPACE to manually trigger single frames while loop is paused.
-    *
-    * const t = textmode.create({ width: 800, height: 600 });
-    *
-    * let rotation = 0;
-    *
-    * t.keyPressed((data) => {
-    *   if (data.key === ' ') {
-    *     rotation += 15; // Increment rotation
-    *     t.redraw(); // Manually trigger one frame
-    *   }
-    * });
-    *
-    * t.draw(() => {
-    *   if(t.frameCount === 1) {
-    *     t.noLoop();
-    *   }
-    *
-    *   t.background(0);
-    *
-    *   t.push();
-    *   t.char('A');
-    *   t.charColor(100, 200, 255);
-    *   t.rotateZ(rotation);
-    *   t.rect(13, 13);
-    *   t.pop();
-    *
-    *   // Show instruction text
-    *   t.push();
-    *   t.translate(-5, -10);
-    *   t.charColor(150);
-    *   const msg = 'PRESS SPACE';
-    *   [...msg].forEach((char, i) => {
-    *     t.push();
-    *     t.translate(i, 0);
-    *     t.char(char);
-    *     t.point();
-    *     t.pop();
-    *   });
-    *   t.pop();
-    * });
+     * // Press SPACE to manually trigger single frames while loop is paused.
+     *
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * let rotation = 0;
+     *
+     * t.keyPressed((data) => {
+     *   if (data.key === ' ') {
+     *     rotation += 15; // Increment rotation
+     *     t.redraw(); // Manually trigger one frame
+     *   }
+     * });
+     *
+     * t.draw(() => {
+     *   if(t.frameCount === 1) {
+     *     t.noLoop();
+     *   }
+     *
+     *   t.background(0);
+     *
+     *   t.push();
+     *   t.char('A');
+     *   t.charColor(100, 200, 255);
+     *   t.rotateZ(rotation);
+     *   t.rect(13, 13);
+     *   t.pop();
+     *
+     *   // Show instruction text
+     *   t.push();
+     *   t.translate(-5, -10);
+     *   t.charColor(150);
+     *   const msg = 'PRESS SPACE';
+     *   [...msg].forEach((char, i) => {
+     *     t.push();
+     *     t.translate(i, 0);
+     *     t.char(char);
+     *     t.point();
+     *     t.pop();
+     *   });
+     *   t.pop();
+     * });
      * ```
      */
     redraw(n?: number): void;

package/dist/types/textmode/mixins/interfaces/IKeyboardMixin.d.ts

@@ -1,4 +1,4 @@
-import type { KeyboardEventHandler } from "../../managers/KeyboardManager";
+import type { KeyboardEventHandler } from '../../managers/KeyboardManager';
 /**
  * Capabilities provided by the KeyboardMixin
  */
@@ -10,36 +10,36 @@ export interface IKeyboardMixin {
      * @returns true if the key is currently pressed, false otherwise
      *
      * @example
-    * ```javascript
-    * const t = textmode.create({ width: 800, height: 600 });
-    *
-    * let playerX = 0;
-    * let playerY = 0;
-    *
-    * t.draw(() => {
-    *   t.background(0);
-    *
-    *   // Check for arrow keys to move a character
-    *   if (t.isKeyPressed('ArrowUp')) {
-    *     playerY -= 1;
-    *   }
-    *   if (t.isKeyPressed('ArrowDown')) {
-    *     playerY += 1;
-    *   }
-    *   if (t.isKeyPressed('ArrowLeft')) {
-    *     playerX -= 1;
-    *   }
-    *   if (t.isKeyPressed('ArrowRight')) {
-    *     playerX += 1;
-    *   }
-    *
-    *   // Draw player character
-    *   t.char('@');
-    *   t.charColor(255, 255, 0);
-    *   t.translate(playerX, playerY);
-    *   t.point();
-    * });
-    * ```
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * let playerX = 0;
+     * let playerY = 0;
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Check for arrow keys to move a character
+     *   if (t.isKeyPressed('ArrowUp')) {
+     *     playerY -= 1;
+     *   }
+     *   if (t.isKeyPressed('ArrowDown')) {
+     *     playerY += 1;
+     *   }
+     *   if (t.isKeyPressed('ArrowLeft')) {
+     *     playerX -= 1;
+     *   }
+     *   if (t.isKeyPressed('ArrowRight')) {
+     *     playerX += 1;
+     *   }
+     *
+     *   // Draw player character
+     *   t.char('@');
+     *   t.charColor(255, 255, 0);
+     *   t.translate(playerX, playerY);
+     *   t.point();
+     * });
+     * ```
      */
     isKeyPressed(key: string): boolean;
     /**
@@ -47,34 +47,34 @@ export interface IKeyboardMixin {
      *
      * @param callback The function to call when a key is pressed
      *
-    * @example
-    * ```javascript
-    * const t = textmode.create({ width: 800, height: 600 });
-    *
-    * let lastKey = '?';
-    * let pulse = 0;
-    *
-    * // Update some visual state when a key is pressed
-    * t.keyPressed((data) => {
-    *   lastKey = data.key;
-    *   pulse = 6; // make the next frames brighter
-    * });
-    *
-    * t.draw(() => {
-    *   t.background(0);
-    *
-    *   // Fade brightness back down each frame
-    *   const glow = Math.max(0, pulse--);
-    *   const brightness = 120 + glow * 20;
-    *   t.charColor(brightness, brightness, 0);
-    *
-    *   // Show the last pressed key at the center of the grid
-    *   t.push();
-    *   t.char(lastKey.length ? lastKey[0] : '?');
-    *   t.point();
-    *   t.pop();
-    * });
-    * ```
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * let lastKey = '?';
+     * let pulse = 0;
+     *
+     * // Update some visual state when a key is pressed
+     * t.keyPressed((data) => {
+     *   lastKey = data.key;
+     *   pulse = 6; // make the next frames brighter
+     * });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Fade brightness back down each frame
+     *   const glow = Math.max(0, pulse--);
+     *   const brightness = 120 + glow * 20;
+     *   t.charColor(brightness, brightness, 0);
+     *
+     *   // Show the last pressed key at the center of the grid
+     *   t.push();
+     *   t.char(lastKey.length ? lastKey[0] : '?');
+     *   t.point();
+     *   t.pop();
+     * });
+     * ```
      */
     keyPressed(callback: KeyboardEventHandler): void;
     /**
@@ -82,31 +82,31 @@ export interface IKeyboardMixin {
      *
      * @param callback The function to call when a key is released
      *
-    * @example
-    * ```javascript
-    * const t = textmode.create({ width: 800, height: 600 });
-    *
-    * let lastRelease = '?';
-    * let fade = 0;
-    *
-    * // Capture the most recent key release and trigger a pulse
-    * t.keyReleased((data) => {
-    *   lastRelease = data.key;
-    *   fade = 10;
-    * });
-    *
-    * t.draw(() => {
-    *   t.background(0);
-    *
-    *   // Dim the glow over time
-    *   const glow = Math.max(0, fade--);
-    *   const color = 80 + glow * 17;
-    *   t.charColor(color, color, 255);
-    *
-    *   t.char(lastRelease.length ? lastRelease[0] : '?');
-    *   t.point();
-    * });
-    * ```
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * let lastRelease = '?';
+     * let fade = 0;
+     *
+     * // Capture the most recent key release and trigger a pulse
+     * t.keyReleased((data) => {
+     *   lastRelease = data.key;
+     *   fade = 10;
+     * });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Dim the glow over time
+     *   const glow = Math.max(0, fade--);
+     *   const color = 80 + glow * 17;
+     *   t.charColor(color, color, 255);
+     *
+     *   t.char(lastRelease.length ? lastRelease[0] : '?');
+     *   t.point();
+     * });
+     * ```
      */
     keyReleased(callback: KeyboardEventHandler): void;
     /**
@@ -161,25 +161,25 @@ export interface IKeyboardMixin {
      * Returns an array of key strings that are currently being held down.
      *
      * @example
-    * ```javascript
-    * const t = textmode.create({ width: 800, height: 600 });
-    *
-    * t.draw(() => {
-    *     t.background(0);
-    *
-    *     const pressed = t.pressedKeys;
-    *
-    *     // Display all currently pressed keys
-    *     pressed.forEach((key, index) => {
-    *         t.push();
-    *         t.char(key[0] || '?'); // Show first character of key name
-    *         t.charColor(255, 200, 100);
-    *         t.translate(index, 0);
-    *         t.point();
-    *         t.pop();
-    *     });
-    * });
-    * ```
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.draw(() => {
+     *     t.background(0);
+     *
+     *     const pressed = t.pressedKeys;
+     *
+     *     // Display all currently pressed keys
+     *     pressed.forEach((key, index) => {
+     *         t.push();
+     *         t.char(key[0] || '?'); // Show first character of key name
+     *         t.charColor(255, 200, 100);
+     *         t.translate(index, 0);
+     *         t.point();
+     *         t.pop();
+     *     });
+     * });
+     * ```
      */
     get pressedKeys(): string[];
     /**
@@ -187,31 +187,31 @@ export interface IKeyboardMixin {
      *
      * Returns an object with boolean properties for each modifier key.
      *
-    * @example
-    * ```javascript
-    * const t = textmode.create({ width: 800, height: 600 });
-    *
-    * t.draw(() => {
-    *     t.background(0);
-    *     const mods = t.modifierState;
-    *
-    *     // Change behavior based on modifier keys
-    *     if (mods.shift) {
-    *         // Draw in caps or with different behavior
-    *         t.char('S');
-    *         t.charColor(255, 255, 0);
-    *         t.point();
-    *     }
-    *
-    *     if (mods.ctrl) {
-    *         // Control key is pressed
-    *         t.translate(2, 0);
-    *         t.char('C');
-    *         t.charColor(0, 255, 255);
-    *         t.point();
-    *     }
-    * });
-    * ```
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.draw(() => {
+     *     t.background(0);
+     *     const mods = t.modifierState;
+     *
+     *     // Change behavior based on modifier keys
+     *     if (mods.shift) {
+     *         // Draw in caps or with different behavior
+     *         t.char('S');
+     *         t.charColor(255, 255, 0);
+     *         t.point();
+     *     }
+     *
+     *     if (mods.ctrl) {
+     *         // Control key is pressed
+     *         t.translate(2, 0);
+     *         t.char('C');
+     *         t.charColor(0, 255, 255);
+     *         t.point();
+     *     }
+     * });
+     * ```
      */
     get modifierState(): {
         /**