@nasser-sw/fabric 7.0.1-beta1 → 7.0.1-beta2

package/docs/text-engine-design.md

@@ -1,698 +0,0 @@
-# Fabric.js Text Engine Design & Implementation Plan
-
-## Overview
-
-This document outlines the design for re-implementing Konva-compatible text behavior in Fabric.js while preserving all existing functionality and maintaining backward compatibility.
-
-## Module Architecture
-
-### New Text Engine Modules
-
-#### `src/text/layout.ts` - Text Layout Engine
-**Purpose**: Core text layout algorithm handling tokenization, segmentation, measurement, wrapping, and alignment.
-
-**Key Functions**:
-```typescript
-export interface TextLayoutOptions {
-  text: string;
-  width?: number;
-  height?: number;
-  wrap: 'word' | 'char' | 'none';
-  align: 'left' | 'center' | 'right' | 'justify';
-  ellipsis?: boolean | string;
-  fontSize: number;
-  lineHeight: number;
-  letterSpacing?: number;
-  charSpacing?: number; // Fabric compatibility
-  direction: 'ltr' | 'rtl' | 'inherit';
-  fontFamily: string;
-  fontStyle: string;
-  fontWeight: string | number;
-}
-
-export interface LayoutResult {
-  lines: LayoutLine[];
-  totalWidth: number;
-  totalHeight: number;
-  isTruncated: boolean;
-  graphemeCount: number;
-}
-
-export interface LayoutLine {
-  text: string;
-  graphemes: string[];
-  width: number;
-  height: number;
-  bounds: GraphemeBounds[];
-  isWrapped: boolean;
-  isLastInParagraph: boolean;
-  justifyRatio?: number; // For justify alignment
-}
-
-export interface GraphemeBounds {
-  grapheme: string;
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  kernedWidth: number;
-  baseline: number;
-}
-
-// Core layout function
-export function layoutText(options: TextLayoutOptions): LayoutResult;
-```
-
-**Algorithm Flow**:
-1. **Tokenization**: Split text by hard line breaks (`\n`)
-2. **Segmentation**: Use `Intl.Segmenter` or fallback for grapheme splitting  
-3. **Measurement**: Measure each grapheme with caching
-4. **Wrapping**: Apply wrap mode with binary search optimization
-5. **Alignment**: Calculate positions for each alignment mode
-6. **Ellipsis**: Apply truncation if content exceeds bounds
-
-#### `src/text/measure.ts` - Text Measurement System
-**Purpose**: Wraps canvas text measurement with font/size/style caching and DPI awareness.
-
-**Key Functions**:
-```typescript
-export interface MeasurementOptions {
-  fontFamily: string;
-  fontSize: number;
-  fontStyle: string;
-  fontWeight: string | number;
-  letterSpacing?: number;
-  direction?: 'ltr' | 'rtl';
-}
-
-export interface GraphemeMeasurement {
-  width: number;
-  height: number;
-  ascent: number;
-  descent: number;
-  baseline: number;
-}
-
-export interface KerningMeasurement extends GraphemeMeasurement {
-  kernedWidth: number; // width accounting for kerning with previous char
-}
-
-// Core measurement functions
-export function measureGrapheme(
-  grapheme: string, 
-  options: MeasurementOptions,
-  ctx?: CanvasRenderingContext2D
-): GraphemeMeasurement;
-
-export function measureGraphemeWithKerning(
-  grapheme: string,
-  previousGrapheme: string | undefined,
-  options: MeasurementOptions,
-  ctx?: CanvasRenderingContext2D
-): KerningMeasurement;
-
-export function getFontMetrics(options: MeasurementOptions): {
-  ascent: number;
-  descent: number;
-  lineHeight: number;
-  baseline: string;
-};
-
-// Caching system
-export class MeasurementCache {
-  private cache = new Map<string, GraphemeMeasurement>();
-  
-  getCacheKey(grapheme: string, options: MeasurementOptions): string;
-  get(grapheme: string, options: MeasurementOptions): GraphemeMeasurement | undefined;
-  set(grapheme: string, options: MeasurementOptions, measurement: GraphemeMeasurement): void;
-  clear(): void;
-  getStats(): { size: number; hitRate: number };
-}
-```
-
-**Caching Strategy**:
-- Cache key: `${fontDeclaration}|${grapheme}|${letterSpacing}`
-- LRU eviction when cache exceeds size limit
-- Separate kerning cache for character pairs
-- DPI-aware caching for high-resolution displays
-
-#### `src/text/hitTest.ts` - Hit Testing and Cursor Mapping
-**Purpose**: Maps pointer coordinates to text positions and provides cursor rectangles.
-
-**Key Functions**:
-```typescript
-export interface HitTestResult {
-  lineIndex: number;
-  charIndex: number;
-  graphemeIndex: number;
-  isAtLineEnd: boolean;
-  isAtTextEnd: boolean;
-  insertionIndex: number; // For cursor positioning
-}
-
-export interface CursorRect {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  baseline: number;
-}
-
-// Hit testing
-export function hitTest(
-  x: number, 
-  y: number, 
-  layout: LayoutResult,
-  options: TextLayoutOptions
-): HitTestResult;
-
-// Cursor positioning  
-export function getCursorRect(
-  insertionIndex: number,
-  layout: LayoutResult,
-  options: TextLayoutOptions
-): CursorRect;
-
-export function getSelectionRects(
-  startIndex: number,
-  endIndex: number,
-  layout: LayoutResult,
-  options: TextLayoutOptions
-): CursorRect[];
-
-// Grapheme cluster boundaries for text editing
-export function getGraphemeBoundaries(text: string): number[];
-export function mapStringIndexToGraphemeIndex(text: string, stringIndex: number): number;
-export function mapGraphemeIndexToStringIndex(text: string, graphemeIndex: number): number;
-```
-
-#### `src/text/ellipsis.ts` - Ellipsis Handling
-**Purpose**: Implements text truncation with ellipsis when content exceeds bounds.
-
-**Key Functions**:
-```typescript
-export interface EllipsisOptions {
-  maxWidth?: number;
-  maxHeight?: number;
-  ellipsisChar: string; // Default: "…"
-  measureFn: (text: string) => { width: number; height: number };
-}
-
-export interface EllipsisResult {
-  truncatedText: string;
-  isTruncated: boolean;
-  truncationIndex: number; // Character index where truncation occurred
-  ellipsisWidth: number;
-}
-
-export function applyEllipsis(
-  text: string,
-  layout: LayoutResult,
-  options: EllipsisOptions
-): EllipsisResult;
-
-// Binary search for optimal truncation point
-export function findTruncationPoint(
-  text: string,
-  maxWidth: number,
-  ellipsisWidth: number,
-  measureFn: (text: string) => number
-): number;
-```
-
-#### `src/text/unicode.ts` - Unicode and Internationalization
-**Purpose**: Enhanced Unicode support for complex scripts, RTL, and grapheme handling.
-
-**Key Functions**:
-```typescript
-// Grapheme segmentation (enhanced version of existing)
-export function segmentGraphemes(text: string): string[];
-
-// Bidi algorithm for RTL/LTR mixed text
-export interface BiDiRun {
-  text: string;
-  direction: 'ltr' | 'rtl';
-  level: number;
-  start: number;
-  end: number;
-}
-
-export function analyzeBiDi(text: string, baseDirection: 'ltr' | 'rtl'): BiDiRun[];
-
-// Script detection for font fallback
-export function detectScript(text: string): string; // 'latin', 'arabic', 'cjk', etc.
-
-// Word breaking for different languages
-export function breakWords(text: string, locale?: string): string[];
-
-// Character classification
-export function isWhitespace(grapheme: string): boolean;
-export function isLineBreak(grapheme: string): boolean;
-export function isWordSeparator(grapheme: string): boolean;
-```
-
-### Integration Points
-
-#### Enhanced Text Base Class
-
-**File**: `src/shapes/Text/Text.ts`
-
-**New Properties**:
-```typescript
-// Add to TextProps interface
-export interface EnhancedTextProps extends TextProps {
-  // Konva compatibility
-  wrap?: 'word' | 'char' | 'none';
-  ellipsis?: boolean | string;
-  letterSpacing?: number; // px-based, in addition to charSpacing
-  
-  // Enhanced RTL
-  direction?: 'ltr' | 'rtl' | 'inherit';
-  
-  // Performance options
-  enableAdvancedLayout?: boolean; // Feature flag
-  cacheStrategy?: 'aggressive' | 'balanced' | 'minimal';
-}
-```
-
-**Modified Methods**:
-```typescript
-// Replace/enhance existing layout methods
-protected _layoutText(): LayoutResult {
-  if (this.enableAdvancedLayout) {
-    // Use new layout engine
-    return layoutText({
-      text: this.text,
-      width: this.width,
-      height: this.height,
-      wrap: this.wrap || 'word',
-      ellipsis: this.ellipsis || false,
-      // ... other options
-    });
-  } else {
-    // Use existing layout for backward compatibility
-    return this._legacyLayout();
-  }
-}
-
-protected _measureChar(/* existing signature */) {
-  if (this.enableAdvancedLayout) {
-    // Use new measurement system
-    return measureGraphemeWithKerning(/* ... */);
-  } else {
-    // Use existing measurement
-    return super._measureChar(/* ... */);
-  }
-}
-```
-
-#### Enhanced IText Integration
-
-**File**: `src/shapes/IText/IText.ts`
-
-**New Methods**:
-```typescript
-// Enhanced cursor positioning using new hit testing
-protected _getCursorBoundariesAdvanced(index: number): CursorBoundaries {
-  const layout = this._getLayout();
-  const cursorRect = getCursorRect(index, layout, this._getLayoutOptions());
-  
-  return {
-    left: this._getLeftOffset(),
-    top: this._getTopOffset(), 
-    leftOffset: cursorRect.x,
-    topOffset: cursorRect.y
-  };
-}
-
-// Enhanced hit testing
-getSelectionStartFromPointer(e: TPointerEvent): number {
-  if (this.enableAdvancedLayout) {
-    const pointer = this.getLocalPointer(e);
-    const layout = this._getLayout();
-    const result = hitTest(pointer.x, pointer.y, layout, this._getLayoutOptions());
-    return result.insertionIndex;
-  } else {
-    return super.getSelectionStartFromPointer(e);
-  }
-}
-```
-
-#### Enhanced Textbox Integration  
-
-**File**: `src/shapes/Textbox.ts`
-
-**Modified Wrapping**:
-```typescript
-// Use new layout engine for wrapping
-protected _splitTextIntoLines(text: string): TextLinesInfo {
-  if (this.enableAdvancedLayout) {
-    const layout = layoutText({
-      text,
-      width: this.width,
-      wrap: this.wrap || 'word',
-      // ... other options
-    });
-    
-    return this._convertLayoutToTextLines(layout);
-  } else {
-    return super._splitTextIntoLines(text);
-  }
-}
-```
-
-## Data Flow Architecture
-
-### Layout Pipeline
-
-```mermaid
-graph TD
-    A[Text Input] --> B[Tokenize by \\n]
-    B --> C[Grapheme Segmentation]
-    C --> D[Character Measurement]
-    D --> E{Wrapping Enabled?}
-    E -->|Yes| F[Apply Wrap Algorithm]
-    E -->|No| G[Single Line Layout]
-    F --> H{Ellipsis Enabled?}
-    G --> H
-    H -->|Yes| I[Apply Ellipsis]
-    H -->|No| J[Alignment Calculation]
-    I --> J
-    J --> K[Generate Line Boxes]
-    K --> L[Return LayoutResult]
-```
-
-### Measurement Caching Flow
-
-```mermaid
-graph TD
-    A[Measure Request] --> B{Cache Hit?}
-    B -->|Yes| C[Return Cached]
-    B -->|No| D[Canvas.measureText]
-    D --> E[Process Font Metrics]
-    E --> F[Apply Letter Spacing]
-    F --> G[Cache Result]
-    G --> H[Return Measurement]
-    C --> I[Update Hit Stats]
-    H --> I
-```
-
-## API Design
-
-### New Properties with Defaults
-
-```typescript
-// Add to textDefaultValues in constants.ts
-export const enhancedTextDefaults = {
-  // Konva compatibility
-  wrap: 'word' as const,
-  ellipsis: false,
-  letterSpacing: 0, // px-based
-  
-  // Enhanced features  
-  direction: 'inherit' as const,
-  enableAdvancedLayout: false, // Opt-in
-  cacheStrategy: 'balanced' as const,
-  
-  // Performance tuning
-  maxCacheSize: 1000,
-  measurementPrecision: 'auto' as const, // 'auto' | 'high' | 'fast'
-};
-```
-
-### Backward Compatibility Mapping
-
-```typescript
-// Property aliases for Konva compatibility
-export const propertyAliases: Record<string, string> = {
-  // Konva -> Fabric mapping
-  'align': 'textAlign',
-  'letterSpacing': 'letterSpacing', // New px-based property
-  'wrap': 'wrap', // New property
-  'ellipsis': 'ellipsis', // New property
-};
-
-// Value transformation functions
-export const valueTransformers: Record<string, (value: any) => any> = {
-  // Convert Konva's simple 'justify' to Fabric's 'justify-left'
-  align: (value: string) => value === 'justify' ? 'justify-left' : value,
-  
-  // Support both boolean and string ellipsis
-  ellipsis: (value: boolean | string) => 
-    typeof value === 'boolean' ? (value ? '…' : false) : value,
-};
-```
-
-### Migration Helper
-
-```typescript
-// Helper for gradual migration
-export function enableKonvaCompatibility(textInstance: FabricText) {
-  textInstance.set({
-    enableAdvancedLayout: true,
-    wrap: textInstance.get('wrap') || 'word',
-    ellipsis: false,
-    letterSpacing: 0,
-  });
-  
-  return textInstance;
-}
-
-// Feature detection
-export function supportsAdvancedLayout(): boolean {
-  return 'Intl' in window && 'Segmenter' in Intl;
-}
-```
-
-## Performance Strategy
-
-### Caching Layers
-
-#### 1. Measurement Cache
-- **Level**: Character + font style combinations
-- **Key**: `${fontDeclaration}|${grapheme}|${letterSpacing}`
-- **Strategy**: LRU with 1000 entry limit
-- **Eviction**: Based on usage frequency and memory pressure
-
-#### 2. Layout Cache  
-- **Level**: Complete layout results
-- **Key**: Hash of all layout-affecting properties  
-- **Strategy**: WeakMap keyed by text content + options
-- **Invalidation**: Automatic on property changes
-
-#### 3. Rendering Cache
-- **Level**: Canvas bitmap caching (existing Fabric system)
-- **Enhancement**: Cache awareness of new layout properties
-
-### Optimization Techniques
-
-#### 1. Lazy Layout Calculation
-```typescript
-class LazyLayoutResult {
-  private _layout?: LayoutResult;
-  
-  get layout(): LayoutResult {
-    if (!this._layout) {
-      this._layout = this.calculateLayout();
-    }
-    return this._layout;
-  }
-  
-  invalidate(): void {
-    this._layout = undefined;
-  }
-}
-```
-
-#### 2. Incremental Updates
-- Track which properties affect which parts of layout
-- Only recalculate affected portions
-- Preserve unaffected layout data
-
-#### 3. Web Worker Support (Future)
-```typescript
-// Offload complex layout calculations
-export interface LayoutWorkerMessage {
-  type: 'layout';
-  options: TextLayoutOptions;
-  id: string;
-}
-
-export interface LayoutWorkerResponse {
-  type: 'layout-result';
-  result: LayoutResult;
-  id: string;
-}
-```
-
-### Memory Management
-
-#### 1. Cache Size Limits
-```typescript
-export const cacheConfig = {
-  maxMeasurementCacheSize: 1000,
-  maxLayoutCacheSize: 100, 
-  maxKerningCacheSize: 5000,
-  cacheEvictionInterval: 30000, // 30 seconds
-};
-```
-
-#### 2. Cleanup Strategies
-- Periodic cache cleanup
-- Memory pressure detection
-- Weak references for disposable objects
-
-## Implementation Phases
-
-### Phase 1: Core Infrastructure (Week 1-2)
-1. ✅ Create new module files with interfaces
-2. ✅ Implement basic measurement system with caching
-3. ✅ Add grapheme segmentation with fallback
-4. ✅ Create layout algorithm skeleton
-
-### Phase 2: Layout Engine (Week 3-4)  
-1. ✅ Implement wrapping algorithms (word/char/none)
-2. ✅ Add alignment calculations
-3. ✅ Implement ellipsis truncation
-4. ✅ Add letter spacing support
-
-### Phase 3: Integration (Week 5-6)
-1. ✅ Integrate with FabricText base class
-2. ✅ Update IText for cursor/selection
-3. ✅ Update Textbox for wrapping
-4. ✅ Add property aliases and compatibility layer
-
-### Phase 4: Optimization & Testing (Week 7-8)
-1. ✅ Performance optimization
-2. ✅ Comprehensive testing
-3. ✅ Documentation and examples
-4. ✅ Migration guide
-
-## Testing Strategy
-
-### Unit Tests
-```typescript
-describe('Text Layout Engine', () => {
-  describe('ellipsis', () => {
-    it('should truncate text with ellipsis when width exceeded', () => {
-      const result = layoutText({
-        text: 'This is a very long text that should be truncated',
-        width: 100,
-        ellipsis: true,
-        fontSize: 16,
-        fontFamily: 'Arial'
-      });
-      
-      expect(result.isTruncated).toBe(true);
-      expect(result.lines[0].text).toMatch(/.*…$/);
-    });
-  });
-  
-  describe('wrapping', () => {
-    it('should not wrap when wrap is none', () => {
-      const result = layoutText({
-        text: 'This should not wrap at all',
-        width: 50,
-        wrap: 'none',
-        fontSize: 16,
-        fontFamily: 'Arial'
-      });
-      
-      expect(result.lines).toHaveLength(1);
-      expect(result.lines[0].isWrapped).toBe(false);
-    });
-  });
-});
-```
-
-### Integration Tests
-```typescript  
-describe('Fabric Text Integration', () => {
-  it('should maintain backward compatibility', () => {
-    const text = new FabricText('Hello World', {
-      fontSize: 20,
-      fontFamily: 'Arial'
-    });
-    
-    // Should work exactly as before
-    expect(text.calcTextWidth()).toBeGreaterThan(0);
-    expect(text.calcTextHeight()).toBeGreaterThan(0);
-  });
-  
-  it('should support new Konva-style properties', () => {
-    const text = new FabricText('Hello World', {
-      enableAdvancedLayout: true,
-      wrap: 'none',
-      ellipsis: true,
-      letterSpacing: 2
-    });
-    
-    expect(text.wrap).toBe('none');
-    expect(text.ellipsis).toBe(true);
-    expect(text.letterSpacing).toBe(2);
-  });
-});
-```
-
-### Performance Benchmarks
-```typescript
-describe('Performance', () => {
-  it('should layout 1000 characters in <50ms', () => {
-    const longText = 'A'.repeat(1000);
-    const start = performance.now();
-    
-    layoutText({
-      text: longText,
-      width: 400,
-      fontSize: 16,
-      fontFamily: 'Arial'
-    });
-    
-    const duration = performance.now() - start;
-    expect(duration).toBeLessThan(50);
-  });
-});
-```
-
-## Migration Guide
-
-### Enabling New Features
-
-#### Option 1: Explicit Opt-in (Recommended)
-```typescript
-const text = new FabricText('Hello World', {
-  enableAdvancedLayout: true,
-  wrap: 'word',
-  ellipsis: true,
-  letterSpacing: 1
-});
-```
-
-#### Option 2: Global Configuration
-```typescript
-// Enable for all new text instances
-FabricText.setGlobalDefaults({
-  enableAdvancedLayout: true
-});
-```
-
-#### Option 3: Progressive Enhancement
-```typescript
-// Detect and enable automatically
-const text = new FabricText('Hello World');
-if (supportsAdvancedLayout()) {
-  enableKonvaCompatibility(text);
-}
-```
-
-### Property Migration
-
-| Old (Fabric) | New (Konva-compatible) | Notes |
-|-------------|----------------------|-------|
-| `textAlign: 'justify'` | `align: 'justify'` | Maps to `justify-left` |
-| `charSpacing: 100` | `letterSpacing: 10` | Different units (em → px) |
-| N/A | `wrap: 'none'` | New single-line mode |
-| N/A | `ellipsis: true` | New truncation feature |
-| `direction: 'rtl'` | `direction: 'rtl'` | Enhanced with 'inherit' |
-
-This comprehensive design provides a roadmap for implementing Konva-compatible text behavior while preserving Fabric.js's advanced capabilities and maintaining full backward compatibility.