@staticcanvas/typeflow 0.34.0

package/dist/typeflow/src/typeflow-caret.js

@@ -0,0 +1,303 @@
+/** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+ * @description TypeFlow Caret - Interactive Cursor Positioning & Mid-String Editing.
+ * A persistent, editable cursor bound to an element's text: jump or move to any
+ * grapheme index, delete a character or whole word at that position, and type
+ * new text in with the usual character-by-character animation. Zero
+ * dependencies; opportunistically defers to a page-global TypeFlow so starting
+ * a `TypeFlow.type()`/`erase()` on the same element interrupts an in-flight
+ * caret edit, without requiring a hard import of the core engine.
+ *
+ * @module @staticcanvas/typeflow/caret
+ */
+
+const CURSOR_BLINK_INTERVAL = 530;
+const WHITESPACE_UNIT = /^\s+$/u;
+
+function segmentGraphemes(text) {
+  if (typeof Intl !== 'undefined' && Intl.Segmenter) {
+    return Array.from(
+      new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(text),
+      (s) => s.segment
+    );
+  }
+  return Array.from(text);
+}
+
+function prefersReducedMotion() {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+/** Stops any animation the page-global TypeFlow engine may have active on `el`, if present. */
+function stopPageTypeFlow(el) {
+  if (typeof window !== 'undefined') window.TypeFlow?.stop?.(el);
+}
+
+function clampCaretIndex(position, max) {
+  const value = position === undefined || position === null ? max : Number(position);
+  if (!Number.isFinite(value)) return max;
+  return Math.max(0, Math.min(Math.round(value), max));
+}
+
+function createCursorSpan(cursorChar) {
+  const span = document.createElement('span');
+  span.className = 'tf-cursor';
+  span.setAttribute('aria-hidden', 'true');
+  span.textContent = cursorChar;
+  return span;
+}
+
+/**
+ * Interactive, stateful cursor bound to an element's text content.
+ *
+ * Unlike `TypeFlow.type()`/`erase()`, which run once from start to finish, a
+ * Caret is persistent: `jump()`, `move()`, `deleteChar()`, and `deleteWord()`
+ * edit `text`/`position` and re-render immediately; `insert()` is animated
+ * and returns a `{ stop, promise }` controller.
+ */
+export class TypeFlowCaret {
+  /**
+   * @param {Element | string} target - Element or CSS selector.
+   * @param {object} [config={}]
+   * @param {string} [config.text] - Initial text. Defaults to the target's current text content.
+   * @param {number} [config.position] - Initial caret index in graphemes. Defaults to the end of the text.
+   * @param {string} [config.cursor='|'] - Cursor glyph. Empty string hides it.
+   * @param {boolean} [config.cursorBlink=true]
+   * @param {number} [config.speed=40] - Default ms per character for `insert()`.
+   * @param {boolean} [config.respectReducedMotion=true]
+   *
+   * @example
+   * const caret = new TypeFlowCaret('#terminal', { text: 'git commit -m "wip"' });
+   * caret.jump(3).deleteWord('forward').insert('push');
+   * // "git push -m "wip""
+   */
+  constructor(target, config = {}) {
+    this.el = typeof target === 'string' ? document.querySelector(target) : target;
+    if (!this.el) throw new Error('TypeFlowCaret: target element not found.');
+    stopPageTypeFlow(this.el);
+
+    this.cursor = config.cursor ?? '|';
+    this.cursorBlink = config.cursorBlink ?? true;
+    this.speed = config.speed ?? 40;
+    this.respectReducedMotion = config.respectReducedMotion ?? true;
+    this.units = segmentGraphemes(config.text ?? this.el.textContent ?? '');
+    this.index = clampCaretIndex(config.position ?? this.units.length, this.units.length);
+    this._blinkInterval = null;
+    this._activeInsert = null;
+    this._render();
+  }
+
+  /** Current plain-text content, cursor excluded. */
+  get text() {
+    return this.units.join('');
+  }
+
+  /** Current caret index, in graphemes, from the start of the text. */
+  get position() {
+    return this.index;
+  }
+
+  /** Total number of graphemes in the current text. */
+  get length() {
+    return this.units.length;
+  }
+
+  /** Moves the caret to an absolute grapheme index, clamped to bounds. */
+  jump(position) {
+    this._stopInsert();
+    this.index = clampCaretIndex(position, this.units.length);
+    this._render();
+    return this;
+  }
+
+  /** Moves the caret by a relative number of graphemes (positive = right, negative = left). */
+  move(delta) {
+    return this.jump(this.index + (Number(delta) || 0));
+  }
+
+  /**
+   * Deletes one grapheme at the caret.
+   * @param {'backward'|'forward'} [direction='backward'] - `'backward'` removes the character before the caret (Backspace); `'forward'` removes the character at/after it (Delete).
+   */
+  deleteChar(direction = 'backward') {
+    this._stopInsert();
+    if (direction === 'forward') {
+      if (this.index < this.units.length) this.units.splice(this.index, 1);
+    } else if (this.index > 0) {
+      this.units.splice(this.index - 1, 1);
+      this.index -= 1;
+    }
+    this._render();
+    return this;
+  }
+
+  /**
+   * Deletes the whitespace-delimited word adjacent to the caret.
+   * @param {'backward'|'forward'} [direction='backward'] - `'backward'` removes the word (and any whitespace immediately before it) that precedes the caret; `'forward'` removes the word (and any whitespace immediately after it) that follows.
+   */
+  deleteWord(direction = 'backward') {
+    this._stopInsert();
+    if (direction === 'forward') {
+      let end = this.index;
+      let ateLeadingSpace = false;
+      while (end < this.units.length && WHITESPACE_UNIT.test(this.units[end])) {
+        end += 1;
+        ateLeadingSpace = true;
+      }
+      while (end < this.units.length && !WHITESPACE_UNIT.test(this.units[end])) end += 1;
+      if (!ateLeadingSpace) {
+        while (end < this.units.length && WHITESPACE_UNIT.test(this.units[end])) end += 1;
+      }
+      if (end === this.index) return this;
+      this.units.splice(this.index, end - this.index);
+    } else {
+      let start = this.index;
+      while (start > 0 && WHITESPACE_UNIT.test(this.units[start - 1])) start -= 1;
+      while (start > 0 && !WHITESPACE_UNIT.test(this.units[start - 1])) start -= 1;
+      if (start === this.index) return this;
+      this.units.splice(start, this.index - start);
+      this.index = start;
+    }
+    this._render();
+    return this;
+  }
+
+  /**
+   * Types `text` at the current caret position, one grapheme at a time,
+   * shifting any following content to the right as it goes.
+   *
+   * @param {string} text
+   * @param {object} [config={}]
+   * @param {number} [config.speed] - Ms per character. Defaults to the speed passed to the constructor.
+   * @param {boolean} [config.respectReducedMotion]
+   * @param {() => void} [config.onStart]
+   * @param {(text: string) => void} [config.onComplete]
+   * @param {() => void} [config.onInterrupt]
+   * @returns {{ stop: () => void, promise: Promise<{completed: boolean, text: string}> }}
+   */
+  insert(text, config = {}) {
+    this._stopInsert();
+    const insertUnits = segmentGraphemes(text === null || text === undefined ? '' : String(text));
+    const speed = Math.max(0, Number(config.speed ?? this.speed) || 0);
+    const startIndex = this.index;
+
+    let settled = false;
+    let timeoutId = null;
+    let resolveFn = null;
+    const settle = (completed) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId !== null) clearTimeout(timeoutId);
+      this._activeInsert = null;
+      if (completed) config.onComplete?.(this.text);
+      else config.onInterrupt?.();
+      resolveFn?.({ completed, text: this.text });
+    };
+    const controller = {
+      stop: () => settle(false),
+      promise: new Promise((resolve) => {
+        resolveFn = resolve;
+      }),
+    };
+    this._activeInsert = controller;
+
+    if (insertUnits.length === 0) {
+      settle(true);
+      return controller;
+    }
+
+    const respectReducedMotion = config.respectReducedMotion ?? this.respectReducedMotion;
+    if (respectReducedMotion === true && prefersReducedMotion()) {
+      this.units.splice(startIndex, 0, ...insertUnits);
+      this.index = startIndex + insertUnits.length;
+      this._render();
+      settle(true);
+      return controller;
+    }
+
+    config.onStart?.();
+    let step = 0;
+    const tick = () => {
+      this.units.splice(startIndex + step, 0, insertUnits[step]);
+      this.index = startIndex + step + 1;
+      this._render();
+      step += 1;
+      if (step >= insertUnits.length) {
+        settle(true);
+        return;
+      }
+      timeoutId = setTimeout(tick, speed);
+    };
+    timeoutId = setTimeout(tick, speed);
+    return controller;
+  }
+
+  /** Stops an in-flight `insert()`, if any. */
+  stop() {
+    this._stopInsert();
+    return this;
+  }
+
+  /** Stops any in-flight `insert()` and clears the blink interval. Call when done with a caret. */
+  destroy() {
+    this._stopInsert();
+    if (this._blinkInterval !== null) {
+      clearInterval(this._blinkInterval);
+      this._blinkInterval = null;
+    }
+    return this;
+  }
+
+  _stopInsert() {
+    this._activeInsert?.stop();
+    stopPageTypeFlow(this.el);
+  }
+
+  _render() {
+    if (this._blinkInterval !== null) {
+      clearInterval(this._blinkInterval);
+      this._blinkInterval = null;
+    }
+    const before = this.units.slice(0, this.index).join('');
+    const after = this.units.slice(this.index).join('');
+    this.el.replaceChildren(document.createTextNode(before));
+
+    if (this.cursor) {
+      const cursorSpan = createCursorSpan(this.cursor);
+      this.el.appendChild(cursorSpan);
+      if (this.cursorBlink) {
+        let visible = true;
+        this._blinkInterval = setInterval(() => {
+          visible = !visible;
+          cursorSpan.style.visibility = visible ? 'visible' : 'hidden';
+        }, CURSOR_BLINK_INTERVAL);
+        this._blinkInterval.unref?.();
+      }
+    }
+
+    this.el.appendChild(document.createTextNode(after));
+  }
+}
+
+/**
+ * Factory form of `new TypeFlowCaret(target, config)`.
+ *
+ * @param {Element | string} target
+ * @param {object} [config]
+ * @returns {TypeFlowCaret}
+ *
+ * @example
+ * const caret = Caret('#terminal', { text: 'git commit' });
+ * caret.move(-6).insert('push --force ');
+ */
+export function Caret(target, config) {
+  return new TypeFlowCaret(target, config);
+}
+
+if (typeof window !== 'undefined') {
+  window.TypeFlowCaret = TypeFlowCaret;
+  window.Caret = Caret;
+}

package/dist/typeflow/src/typeflow-debug.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TypeFlow Debug - Diagnostic Tracing and LogCAD Integration.
+ */
+export interface TypeFlowDebugOptions {
+  logcad?: boolean;
+  console?: boolean;
+  maxHistory?: number;
+  traceFrames?: boolean;
+}
+
+export interface TypeFlowDebugEntry {
+  timestamp: string;
+  level: 'info' | 'warn' | 'error' | 'debug' | 'trace';
+  message: string;
+  data: Record<string, any>;
+}
+
+export class TypeFlowDebug {
+  static enabled: boolean;
+  static options: TypeFlowDebugOptions;
+  static history: TypeFlowDebugEntry[];
+
+  static enable(options?: TypeFlowDebugOptions): void;
+  static disable(): void;
+  static log(
+    level: 'info' | 'warn' | 'error' | 'debug' | 'trace',
+    message: string,
+    data?: Record<string, any>
+  ): void;
+  static trace<T>(controller: T, label?: string): T;
+  static getHistory(): TypeFlowDebugEntry[];
+  static clearHistory(): void;
+  static exportLog(): string;
+}

package/dist/typeflow/src/typeflow-debug.js

@@ -0,0 +1,223 @@
+/** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+ * @description TypeFlow Debug - Diagnostic Tracing and LogCAD Integration.
+ * Provides lifecycle telemetry, animation step timings, event hooks, and structured
+ * logger integration for TypeFlow applications.
+ *
+ * @module @staticcanvas/typeflow/debug
+ */
+
+export class TypeFlowDebug {
+  static enabled = false;
+  static options = {
+    logcad: true,
+    console: true,
+    maxHistory: 200,
+    traceFrames: false,
+  };
+  static history = [];
+  static originalType = null;
+  static originalErase = null;
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Enables diagnostic telemetry tracing across TypeFlow animation lifecycles.
+   * @param {Object} [opts={}] - Configuration options for the debug session.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {boolean} [opts.logcad=true] - Whether to route logs through @staticcanvas/logcad if available.
+   * @param {boolean} [opts.console=true] - Whether to output styled colored logs to the browser console.
+   * @param {number}  [opts.maxHistory=200] - Maximum number of recent log entries to retain in memory.
+   * @param {boolean} [opts.traceFrames=false] - Whether to log every individual frame render tick.
+   *
+   * -------------
+   *
+   * @example
+   *
+   * // Enable debugging with default settings
+   * TypeFlowDebug.enable();
+   *
+   * // Enable with custom history size and disabled console output
+   * TypeFlowDebug.enable({
+   *   logcad: true,
+   *   console: false,
+   *   maxHistory: 500,
+   * });
+   */
+  static enable(opts = {}) {
+    TypeFlowDebug.options = { ...TypeFlowDebug.options, ...opts };
+    TypeFlowDebug.enabled = true;
+    TypeFlowDebug.log('info', 'TypeFlowDebug enabled', { options: TypeFlowDebug.options });
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Disables diagnostic tracing and halts active logging.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @example
+   * TypeFlowDebug.disable();
+   */
+  static disable() {
+    TypeFlowDebug.enabled = false;
+    TypeFlowDebug.log('info', 'TypeFlowDebug disabled');
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Internal logging bridge supporting @staticcanvas/logcad and styled console messages.
+   * @param {'info' | 'warn' | 'error' | 'debug' | 'trace'} level - Severity level of the log entry.
+   * @param {string} message - Human-readable summary of the event.
+   * @param {Object} [data={}] - Contextual payload data to associate with the event.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {string} level - Severity level ('info', 'warn', 'error', 'debug', 'trace').
+   * @param {string} message - The message text to record.
+   * @param {Object} [data={}] - Arbitrary metadata object (timings, diffs, controllers).
+   *
+   * -------------
+   *
+   * @example
+   * TypeFlowDebug.log('info', 'Sequence step completed', { step: 1, duration: 45 });
+   * TypeFlowDebug.log('warn', 'Frame drop detected', { expectedMs: 16, actualMs: 34 });
+   */
+  static log(level, message, data = {}) {
+    if (!TypeFlowDebug.enabled && level !== 'error') return;
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      data,
+    };
+
+    TypeFlowDebug.history.push(entry);
+    if (TypeFlowDebug.history.length > TypeFlowDebug.options.maxHistory) {
+      TypeFlowDebug.history.shift();
+    }
+
+    // 1. Integration with @staticcanvas/logcad if available globally or via module
+    if (TypeFlowDebug.options.logcad && typeof globalThis !== 'undefined' && globalThis.logcad) {
+      try {
+        const logger = globalThis.logcad.getLogger?.('TypeFlow') || globalThis.logcad;
+        if (typeof logger[level] === 'function') {
+          logger[level](message, data);
+          return;
+        }
+      } catch {
+        // Fallback to console
+      }
+    }
+
+    // 2. Structured fallback console output with CSS colors
+    if (TypeFlowDebug.options.console && typeof console !== 'undefined') {
+      const colors = {
+        info: 'color: #38bdf8; font-weight: bold;',
+        warn: 'color: #f59e0b; font-weight: bold;',
+        error: 'color: #ef4444; font-weight: bold;',
+        debug: 'color: #ff6b2b; font-weight: bold;',
+        trace: 'color: #94a3b8; font-weight: normal;',
+      };
+
+      const tag = `%c[TypeFlow:${level.toUpperCase()}]`;
+      const style = colors[level] || colors.info;
+
+      if (Object.keys(data).length > 0) {
+        console[level === 'trace' ? 'debug' : level] || console.log(tag, style, message, data);
+      } else {
+        console[level === 'trace' ? 'debug' : level] || console.log(tag, style, message);
+      }
+    }
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Tracks a specific TypeFlow animation controller and logs lifecycle events upon resolution or rejection.
+   * @param {Object} controller - Active TypeFlow controller instance.
+   * @param {string} [label='Animation'] - Descriptive name for the tracked target.
+   * @returns {Object} The passed-in controller for chaining.
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {Object} controller - The TypeFlow controller returned by TypeFlow.type() / TypeFlow.erase().
+   * @param {Promise} controller.promise - The underlying completion promise.
+   * @param {Function} controller.stop - Method to abort the animation.
+   * @param {string} [label='Animation'] - Label displayed in log output.
+   *
+   * -------------
+   *
+   * @example
+   * const ctrl = TypeFlow.type('#headline', 'Hello World');
+   * TypeFlowDebug.trace(ctrl, 'Hero Headline');
+   */
+  static trace(controller, label = 'Animation') {
+    if (!TypeFlowDebug.enabled || !controller) return controller;
+
+    const start = performance.now();
+    TypeFlowDebug.log('debug', `[${label}] Started animation`, { controller });
+
+    if (controller.promise) {
+      controller.promise.then(
+        (res) => {
+          const duration = (performance.now() - start).toFixed(2);
+          TypeFlowDebug.log('info', `[${label}] Resolved (${duration}ms)`, res);
+        },
+        (err) => {
+          const duration = (performance.now() - start).toFixed(2);
+          TypeFlowDebug.log('error', `[${label}] Rejected (${duration}ms)`, err);
+        }
+      );
+    }
+
+    return controller;
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Returns a shallow copy of the recorded event history.
+   * @returns {Array<Object>} List of history entry objects.
+   *
+   * -------------
+   *
+   * @example
+   * const history = TypeFlowDebug.getHistory();
+   * console.log('Total recorded events:', history.length);
+   */
+  static getHistory() {
+    return [...TypeFlowDebug.history];
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Clears the current event history ring buffer.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @example
+   * TypeFlowDebug.clearHistory();
+   */
+  static clearHistory() {
+    TypeFlowDebug.history = [];
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Exports recorded telemetry event history as a formatted JSON string.
+   * @returns {string} Serialized JSON representation of debug history.
+   *
+   * -------------
+   *
+   * @example
+   * const jsonReport = TypeFlowDebug.exportLog();
+   * navigator.clipboard.writeText(jsonReport);
+   */
+  static exportLog() {
+    return JSON.stringify(TypeFlowDebug.history, null, 2);
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.TypeFlowDebug = TypeFlowDebug;
+}

package/dist/typeflow/src/typeflow-extchars.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TypeFlow ExtChars - Extended Unicode Glyph Presets & Scramble Pools.
+ */
+export const EXT_CHARSETS: {
+  hieroglyphs: string;
+  runic: string;
+  ogham: string;
+  coptic: string;
+  katakana: string;
+  cyberMatrix: string;
+  blocks: string;
+  boxDrawing: string;
+  mathSymbols: string;
+  braille: string;
+  astronomical: string;
+  geometric: string;
+  glitch: string;
+};
+
+export class TypeFlowExtChars {
+  static charsets: Record<string, string>;
+  static getCharset(name: string): string;
+  static registerCharset(name: string, glyphs: string): void;
+  static combineCharsets(...names: string[]): string;
+  static randomGlyph(charsetOrName: string): string;
+}
+
+export function getExtendedCharset(name: string): string;