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

package/docs/fabric-konva-gap-analysis.md

@@ -1,274 +0,0 @@
-# Fabric.js vs Konva Text Engine Gap Analysis
-
-## Overview
-
-This document analyzes the differences between Fabric.js current text implementation and Konva's text behavior, identifying gaps that need to be addressed for feature parity.
-
-## Current Fabric.js Text Architecture
-
-### File Structure
-- `src/shapes/Text/Text.ts` - Base text class (1950+ lines)
-- `src/shapes/IText/IText.ts` - Interactive text (787+ lines) 
-- `src/shapes/IText/ITextKeyBehavior.ts` - Keyboard handling (692+ lines)
-- `src/shapes/Textbox.ts` - Wrapping text box (580+ lines)
-
-### Key Classes
-- `FabricText` - Base text rendering
-- `IText` - Adds editing capabilities 
-- `Textbox` - Adds automatic wrapping
-
-## Feature Comparison Matrix
-
-| Feature | Fabric.js Current | Konva Target | Gap Status |
-|---------|------------------|--------------|------------|
-| **Text Wrapping** | ✅ word/char modes | ✅ word/char/none | ⚠️ Missing 'none' mode |
-| **Ellipsis** | ❌ No ellipsis support | ✅ boolean/string ellipsis | ❌ **MISSING** |
-| **Letter Spacing** | ✅ charSpacing in em | ✅ letterSpacing in px | ⚠️ Different units |
-| **Justify Alignment** | ✅ justify variants | ✅ justify only | ⚠️ Different API |
-| **RTL Support** | ⚠️ Basic direction prop | ✅ Full RTL/bidi | ⚠️ Limited support |
-| **Grapheme Splitting** | ✅ Via graphemeSplit() | ✅ Via stringToArray() | ✅ **EQUIVALENT** |
-| **Per-char Styling** | ✅ Rich styling system | ⚠️ Limited styling | ✅ **FABRIC SUPERIOR** |
-| **Character Measurement** | ✅ Advanced caching | ✅ Font cache system | ✅ **EQUIVALENT** |
-| **Baseline Handling** | ✅ Multiple baselines | ✅ Auto/alphabetic | ✅ **EQUIVALENT** |
-
-## Detailed Gap Analysis
-
-### 1. Text Wrapping Modes
-
-**Current Fabric Behavior:**
-```typescript
-// Textbox wrapping in _wrapText()
-// - Word wrapping via wordSplit()
-// - Grapheme wrapping via splitByGrapheme
-// - No explicit 'none' mode
-```
-
-**Konva Target:**
-```typescript
-wrap: 'word' | 'char' | 'none'
-// 'none' = no wrapping, text extends beyond bounds
-```
-
-**Gap:** Fabric needs explicit `wrap: 'none'` mode for single-line text that doesn't wrap.
-
-### 2. Ellipsis Support ❌ CRITICAL GAP
-
-**Current Fabric:** No ellipsis functionality exists.
-
-**Konva Target:**
-```typescript
-ellipsis: boolean | string  // true = "…", string = custom
-// Only works with fixed width/height
-// Applied when:
-// - wrap: 'none' and text exceeds width  
-// - wrap: 'word'/'char' and text exceeds height
-```
-
-**Implementation Needed:**
-- Add `ellipsis` property to text options
-- Implement truncation algorithm with binary search
-- Handle ellipsis width in layout calculations
-- Support both boolean and custom string ellipsis
-
-### 3. Letter Spacing Units ⚠️ API DIFFERENCE
-
-**Current Fabric:**
-```typescript
-charSpacing: number // in thousandths of em (1000 = 1em)
-// Applied as: (fontSize * charSpacing) / 1000
-```
-
-**Konva Target:**
-```typescript
-letterSpacing: number // in pixels
-// Applied directly as pixel offset
-```
-
-**Gap:** Need to support both APIs or provide migration path.
-
-### 4. Justify Alignment Variants ⚠️ API DIFFERENCE
-
-**Current Fabric:**
-```typescript
-textAlign: 'justify' | 'justify-left' | 'justify-center' | 'justify-right'
-// justify-* variants control alignment of non-justified lines
-```
-
-**Konva Target:**
-```typescript
-align: 'justify' // Only single justify mode
-// Last line always left-aligned (no variants)
-```
-
-**Gap:** Fabric has more sophisticated justify variants. Need to map Konva's simple `justify` to Fabric's `justify-left`.
-
-### 5. RTL/Bidi Support ⚠️ LIMITED
-
-**Current Fabric:**
-```typescript
-direction: 'ltr' | 'rtl' // Basic support
-// Limited bidi algorithm implementation
-```
-
-**Konva Target:**
-```typescript
-direction: 'inherit' | 'ltr' | 'rtl'
-// Full Unicode bidi support
-// Context direction inheritance
-```
-
-**Gap:** 
-- Add `'inherit'` option
-- Improve bidi algorithm for mixed content
-- Better RTL text shaping support
-
-### 6. Character Bounds and Hit Testing
-
-**Current Fabric:**
-```typescript
-__charBounds: GraphemeBBox[][] // Per-line character bounds
-// Used for cursor positioning and selection
-```
-
-**Konva Equivalent:**
-```typescript
-// No direct equivalent - Konva focuses on rendering
-// Hit testing via pixel-based detection
-```
-
-**Gap:** Fabric's character bounds system is more sophisticated for editing. Need to preserve while adding Konva compatibility.
-
-## Text Layout Algorithm Differences
-
-### Fabric.js Current Flow
-```
-1. _splitText() -> Split by newlines
-2. _splitTextIntoLines() -> Apply wrapping  
-3. measureLine() -> Measure each line
-4. _renderTextCommon() -> Render with styling
-```
-
-### Konva Target Flow  
-```
-1. _setTextData() -> Parse and measure text
-2. Binary search for line breaks
-3. stringToArray() -> Grapheme splitting
-4. _renderTextLine() -> Character-by-character rendering
-```
-
-**Key Differences:**
-- Konva uses binary search for optimal line breaking
-- Fabric uses word-based then grapheme-based approach
-- Konva applies letterSpacing to all characters including last
-- Fabric has more complex per-character styling
-
-## Missing Konva Features in Fabric
-
-### 1. Ellipsis System ❌
-- No truncation with "…" character
-- No overflow handling for fixed-size containers
-- Need complete implementation
-
-### 2. Wrap Mode 'none' ⚠️
-- No explicit non-wrapping mode
-- Text always attempts to fit in container
-- Need single-line mode
-
-### 3. Letter Spacing API ⚠️  
-- Different unit system (em vs px)
-- Different application logic
-- Need compatibility layer
-
-### 4. Simplified Justify ⚠️
-- Konva's simpler justify model
-- No justify variants for last line alignment
-
-## Fabric.js Superior Features
-
-### 1. Rich Text Styling ✅
-- Per-character font, color, decoration
-- Complex style inheritance
-- Superior to Konva's basic styling
-
-### 2. Interactive Editing ✅
-- Cursor positioning and selection
-- Keyboard navigation
-- Text editing capabilities
-- No Konva equivalent
-
-### 3. Advanced Layout ✅
-- Sophisticated text box wrapping
-- Dynamic width/height calculations
-- Auto-sizing capabilities
-
-### 4. Performance Optimizations ✅
-- Extensive font caching
-- Optimized re-rendering
-- Character measurement caching
-
-## Implementation Strategy
-
-### Phase 1: Core Features
-1. Add `ellipsis: boolean | string` property
-2. Implement ellipsis truncation algorithm
-3. Add `wrap: 'none'` mode
-4. Add `letterSpacing` pixel-based option
-
-### Phase 2: API Compatibility  
-1. Create Konva-compatible property aliases
-2. Map `align` to `textAlign` variants
-3. Support both charSpacing and letterSpacing
-4. Add direction inheritance
-
-### Phase 3: Algorithm Updates
-1. Implement binary search line breaking
-2. Update grapheme handling to match Konva
-3. Improve RTL/bidi support
-4. Optimize character measurement
-
-### Phase 4: Advanced Features
-1. Per-character render hooks
-2. Enhanced font metrics
-3. Better Unicode support
-4. Performance optimizations
-
-## Backward Compatibility Requirements
-
-### Must Preserve:
-- All existing Fabric.js text APIs
-- Rich per-character styling
-- Interactive editing capabilities  
-- Current performance characteristics
-
-### Safe to Change:
-- Internal layout algorithms
-- Measurement caching strategies
-- Rendering optimizations
-- Add new optional properties
-
-### Migration Strategy:
-- All new features opt-in with safe defaults
-- Gradual migration path for existing apps
-- Feature flags for Konva compatibility mode
-
-## Testing Strategy
-
-### Unit Tests Needed:
-- Ellipsis truncation edge cases
-- Letter spacing calculations
-- Wrap mode behaviors
-- RTL text handling
-- Unicode grapheme splitting
-
-### Integration Tests:
-- Layout algorithm compatibility
-- Performance benchmarks
-- Visual rendering tests
-- Cross-browser compatibility
-
-### Migration Tests:
-- Backward compatibility validation
-- Feature parity verification
-- Performance regression detection
-
-This gap analysis provides the roadmap for implementing Konva text compatibility while preserving Fabric.js's advanced features.