@nasser-sw/fabric 7.0.0-beta1

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

@@ -0,0 +1,274 @@
+# 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.

package/docs/konva-text-behavior-spec.md

@@ -0,0 +1,265 @@
+# Konva Text Engine Behavior Specification
+
+## Overview
+
+This document specifies the behavior of Konva's text engine based on source analysis and documentation. This will serve as the target specification for re-implementing Fabric.js text behavior.
+
+## Text Properties and Configuration
+
+### Core Text Properties
+
+#### `text: string`
+- The text content to display
+- Can contain newlines (`\n`)
+- Default: `''`
+
+#### `fontSize: number`
+- Font size in pixels
+- Default: `12`
+- Used as base unit for various calculations
+
+#### `fontFamily: string`  
+- Font family name
+- Automatically quoted if contains spaces and not already quoted
+- Default: `'Arial'`
+- Example: `"Times New Roman"` or `Arial`
+
+#### `fontStyle: string`
+- Font style specification
+- Values: `'normal'`, `'italic'`, `'bold'`, `'500'`, or combinations like `'italic bold'`
+- Default: `'normal'`
+
+#### `fontVariant: string`
+- Font variant specification
+- Values: `'normal'`, `'small-caps'`
+- Default: `'normal'`
+
+#### `direction: string`
+- Text direction for RTL/LTR support
+- Values: `'inherit'`, `'ltr'`, `'rtl'`
+- Default: `'inherit'`
+- When `'inherit'`, uses context direction
+- Affects text alignment and rendering direction
+
+## Text Layout and Alignment
+
+### Horizontal Alignment (`align: string`)
+
+Values and behavior:
+- `'left'` (default): Text aligns to left edge
+- `'center'`: Text centers horizontally
+- `'right'`: Text aligns to right edge  
+- `'justify'`: Text spreads across full width by adjusting space between words
+
+**Justify Behavior:**
+- Distributes extra space evenly between words on each line
+- Last line of paragraph is NOT justified (stays left-aligned)
+- Spaces are expanded, word widths remain constant
+- Formula: `extraSpace = (lineWidth - textWidth) / numberOfSpaces`
+
+### Vertical Alignment (`verticalAlign: string`)
+
+Values and behavior:
+- `'top'` (default): Text aligns to top of container
+- `'middle'`: Text centers vertically in container  
+- `'bottom'`: Text aligns to bottom of container
+
+### Text Baseline (`textBaseline`)
+- Uses `'alphabetic'` baseline when not legacy mode
+- Uses `'middle'` baseline in legacy mode
+- Calculated using font metrics when available
+
+## Text Wrapping (`wrap: string`)
+
+### Wrap Modes
+
+#### `'word'` (default)
+- Wraps at word boundaries (spaces, hyphens)
+- Preserves whole words when possible
+- Long words that exceed line width are broken character-by-character
+- Algorithm:
+  1. Measure words until line width exceeded
+  2. Try to break at last space/hyphen
+  3. If no break point found, break mid-word
+
+#### `'char'`
+- Wraps at any character boundary
+- No consideration for word integrity
+- More aggressive wrapping
+
+#### `'none'`
+- No automatic wrapping
+- Text extends beyond container width
+- Used with `ellipsis` for single-line truncation
+
+### Wrapping Algorithm
+
+```typescript
+// Simplified wrapping logic
+function wrapText(line: string, maxWidth: number) {
+  const words = line.split(' ');
+  let currentLine = '';
+  let lines = [];
+  
+  for (const word of words) {
+    const testLine = currentLine ? `${currentLine} ${word}` : word;
+    const testWidth = measureText(testLine);
+    
+    if (testWidth > maxWidth && currentLine) {
+      lines.push(currentLine);
+      currentLine = word;
+    } else {
+      currentLine = testLine;
+    }
+  }
+  
+  if (currentLine) {
+    lines.push(currentLine);
+  }
+  
+  return lines;
+}
+```
+
+## Ellipsis Truncation (`ellipsis: boolean`)
+
+### Ellipsis Behavior
+- Default: `false`
+- When `true`, adds `"…"` character to indicate truncated text
+- Only applies when both width AND height constraints are set
+- Triggered when:
+  - `wrap: 'none'` and text exceeds width
+  - Wrapped text exceeds height limit
+
+### Ellipsis Algorithm
+1. Measure available space accounting for ellipsis width
+2. Find maximum characters that fit in available space
+3. Remove additional characters if needed to fit ellipsis
+4. Append `"…"` character
+
+```typescript
+if (shouldAddEllipsis && textWidth + ellipsisWidth > maxWidth) {
+  // Binary search for maximum characters that fit
+  let low = 0, high = text.length;
+  while (low < high) {
+    const mid = Math.floor((low + high) / 2);
+    const truncated = text.substring(0, mid);
+    if (measureText(truncated + "…") <= maxWidth) {
+      low = mid + 1;
+    } else {
+      high = mid;
+    }
+  }
+  return text.substring(0, low - 1) + "…";
+}
+```
+
+## Character Spacing and Metrics
+
+### Letter Spacing (`letterSpacing: number`)
+- Default: `0`
+- Added between every character (including last character)
+- Applied after text measurement
+- Formula: `totalWidth = textWidth + letterSpacing * textLength`
+- **Note:** Konva applies letterSpacing to ALL characters, including the last one
+
+### Character Measurement
+- Uses grapheme-aware splitting via `stringToArray()`
+- Handles emoji, combining characters, and complex scripts
+- Supports kerning between character pairs when available
+- Caches measurements for performance
+
+### Font Metrics
+- Uses `TextMetrics` API when available
+- Falls back to calculated values based on fontSize
+- Metrics used:
+  - `fontBoundingBoxAscent` / `fontBoundingBoxDescent`
+  - `actualBoundingBoxAscent` / `actualBoundingBoxDescent` 
+  - Baseline calculations for vertical positioning
+
+## Width and Height Behavior
+
+### Auto Sizing
+- `width: 'auto'` (default): Width adjusts to content
+- `height: 'auto'` (default): Height adjusts to content
+- Auto width = `textWidth + padding * 2`
+- Auto height = `fontSize * lineCount * lineHeight + padding * 2`
+
+### Fixed Sizing
+- When width/height are numbers, text is constrained
+- Fixed width triggers wrapping behavior
+- Fixed height with overflow triggers ellipsis
+
+### Line Height (`lineHeight: number`)
+- Default: `1`
+- Multiplier applied to fontSize
+- `actualLineHeight = fontSize * lineHeight`
+- Affects vertical spacing between lines
+
+## Advanced Features
+
+### Per-Character Rendering (`charRenderFunc`)
+- Optional callback for custom character rendering
+- Called for each grapheme with position and context
+- Allows character-level transformations
+- Signature: `(char: string, index: number, x: number, y: number, context) => void`
+
+### Text Decoration
+- `textDecoration: string`
+- Supports: `'underline'`, `'line-through'`, or combinations
+- Decorations scale with fontSize
+- Line thickness: `fontSize / 15`
+
+### RTL Text Support
+- `direction: 'rtl'` enables right-to-left text
+- Affects character order and alignment behavior
+- Context direction inheritance
+- Special handling for mixed RTL/LTR content
+
+## Unicode and Internationalization
+
+### Grapheme Splitting
+- Uses Unicode-aware character splitting
+- Handles:
+  - Emoji with skin tone modifiers
+  - Zero-width joiners (ZWJ)
+  - Regional indicator symbols (flags)
+  - Combining characters (diacritics)
+  - Complex scripts (Arabic, Thai, etc.)
+
+### Text Shaping
+- Native browser text shaping for complex scripts
+- Kerning and ligature support where available
+- Font feature support
+
+## Performance Considerations
+
+### Measurement Caching
+- Character widths cached by font style
+- Kerning pairs cached when measured
+- Font declarations cached
+- Cache key: font style string
+
+### Rendering Optimizations
+- Character-by-character rendering only when necessary:
+  - Letter spacing applied
+  - Per-character styling
+  - Justify alignment
+  - Custom render functions
+- Otherwise renders entire lines at once
+
+## Error Handling and Edge Cases
+
+### Empty Text
+- Empty string renders as zero-width, zero-height
+- Maintains minimum selectable area
+
+### Invalid Dimensions
+- Negative widths/heights treated as auto
+- Zero width with wrapping causes character-by-character breaks
+
+### Font Loading
+- Graceful fallback to system fonts
+- Re-measurement when fonts load
+
+This specification serves as the behavioral target for implementing Konva-compatible text rendering in Fabric.js while maintaining backward compatibility.