Adding in docs

PGMacDesign2 · PGMacDesign2 · commit dde9963a8488 · 2025-06-13T00:20:43.000-07:00
diff --git a/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/model/RichTextConfig.kt b/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/model/RichTextConfig.kt
@@ -1,5 +1,48 @@
 package com.mohamedrejeb.richeditor.model
 
+/**
+ * RichTextConfig - Configuration management class for customizing Rich Text Editor appearance and behavior.
+ * 
+ * This class provides centralized configuration for all visual and behavioral aspects of the rich text editor:
+ * 
+ * **Link Styling Configuration**:
+ * - `linkColor`: Sets the color for hyperlink text (default: Color.Blue)
+ * - `linkTextDecoration`: Controls link text decoration like underlines (default: TextDecoration.Underline)
+ * 
+ * **Code Span Styling Configuration**:
+ * - `codeSpanColor`: Text color for inline code spans (default: Color.Unspecified)
+ * - `codeSpanBackgroundColor`: Background color for code spans (default: Color.Transparent)
+ * - `codeSpanStrokeColor`: Border/stroke color for code spans (default: Color.LightGray)
+ * 
+ * **List Indentation Configuration**:
+ * - `listIndent`: Universal indentation for both ordered and unordered lists (default: 38)
+ * - `orderedListIndent`: Specific indentation for numbered lists (default: 38)
+ * - `unorderedListIndent`: Specific indentation for bullet lists (default: 38)
+ * 
+ * **List Style Type Configuration**:
+ * - `orderedListStyleType`: Numbering style for ordered lists (1,2,3 vs i,ii,iii vs A,B,C)
+ * - `unorderedListStyleType`: Bullet style for unordered lists (•, ◦, ▪)
+ * 
+ * **Editor Behavior Configuration**:
+ * - `preserveStyleOnEmptyLine`: Whether formatting persists on empty lines (default: true)
+ * - `exitListOnEmptyItem`: Whether pressing Enter on empty list item exits the list (default: true)
+ * 
+ * **Key Features**:
+ * - **Reactive Updates**: All configuration changes automatically trigger UI updates
+ * - **Nested List Support**: Different styles for different nesting levels
+ * - **Cross-Platform Consistency**: Same configuration works across all supported platforms
+ * - **Runtime Modification**: Configuration can be changed dynamically during editor usage
+ * 
+ * **Usage Patterns**:
+ * - Access via `richTextState.config` property
+ * - Modify properties directly to see immediate visual changes
+ * - Commonly used for theming and customizing editor appearance
+ * - Essential for implementing custom formatting toolbars and style controls
+ * 
+ * This configuration system enables developers to create rich text editors that match their
+ * application's design system and user experience requirements.
+ */
+
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.text.style.TextDecoration
 import com.mohamedrejeb.richeditor.paragraph.type.OrderedListStyleType
diff --git a/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/model/RichTextState.kt b/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/model/RichTextState.kt
@@ -1,5 +1,35 @@
 package com.mohamedrejeb.richeditor.model
 
+/**
+ * RichTextState - The core state management class for the Rich Text Editor library.
+ * 
+ * This class serves as the central hub for managing all aspects of rich text editing and provides:
+ * - **Text Content Management**: Stores and manages the rich text content with formatting
+ * - **Selection and Cursor Control**: Tracks text selection, cursor position, and composition state
+ * - **Styling Operations**: Applies and manages span styles (bold, italic, etc.) and paragraph styles
+ * - **List Management**: Handles ordered/unordered lists with nesting and indentation
+ * - **Link Management**: Creates, edits, and removes hyperlinks with custom styling
+ * - **Import/Export Functionality**: Converts between rich text and HTML/Markdown/Lexical formats
+ * - **Configuration Management**: Provides centralized configuration for colors, indentation, and behavior
+ * - **State Persistence**: Supports saving and restoring editor state across sessions
+ * 
+ * Key architectural features:
+ * - **Reactive State**: Uses Compose state management for automatic UI updates
+ * - **Immutable Operations**: All text modifications return new state instances
+ * - **Format Compatibility**: Supports multiple rich text formats (HTML, Markdown, Lexical JSON)
+ * - **Cross-Platform**: Works consistently across Android, Desktop, iOS, and Web platforms
+ * - **Performance Optimized**: Efficient text processing and minimal recompositions
+ * 
+ * Usage patterns:
+ * - **Editor Integration**: Used with RichTextEditor composables for interactive editing
+ * - **Display Integration**: Used with RichText composables for read-only display
+ * - **Programmatic Control**: Allows full programmatic control over text content and formatting
+ * - **Custom Toolbars**: Provides state information for building custom formatting toolbars
+ * 
+ * This class is the foundation that enables rich text editing capabilities across the entire library
+ * and serves as the primary interface for developers implementing rich text functionality.
+ */
+
 import androidx.compose.foundation.text.InlineTextContent
 import androidx.compose.runtime.*
 import androidx.compose.runtime.saveable.Saver
@@ -46,6 +76,49 @@ import kotlin.reflect.KClass
 import com.mohamedrejeb.richeditor.parser.utils.H1SpanStyle
 import com.mohamedrejeb.richeditor.parser.utils.H2SpanStyle
 
+/**
+ * rememberRichTextState - Creates and remembers a RichTextState instance with automatic state preservation.
+ * 
+ * This composable function provides the standard way to create and manage RichTextState in Compose:
+ * 
+ * **State Management Features**:
+ * - **Automatic Persistence**: Saves and restores rich text content across configuration changes
+ * - **Compose Integration**: Fully integrated with Compose's state management system
+ * - **Memory Efficiency**: Efficiently manages state lifecycle and memory usage
+ * - **Recomposition Optimization**: Minimizes unnecessary recompositions for better performance
+ * 
+ * **Persistence Behavior**:
+ * - **Content Preservation**: Rich text content and formatting are preserved across app lifecycle
+ * - **Selection State**: Text selection and cursor position are maintained during state restoration
+ * - **Configuration Changes**: Survives screen rotations, theme changes, and other configuration updates
+ * - **Process Death**: Handles Android process death and restoration gracefully
+ * 
+ * **Usage Patterns**:
+ * - **Standard Creation**: Primary method for creating RichTextState in Compose applications
+ * - **Screen-Level State**: Typically called at screen or major component level
+ * - **Shared State**: Can be passed down to child components for shared rich text editing
+ * - **Multiple Instances**: Multiple independent instances can be created for different text fields
+ * 
+ * **Integration Examples**:
+ * ```kotlin
+ * // Basic usage
+ * val richTextState = rememberRichTextState()
+ * RichTextEditor(state = richTextState)
+ * 
+ * // With initial content
+ * val richTextState = rememberRichTextState()
+ * LaunchedEffect(Unit) {
+ *     richTextState.setHtml("<p><b>Initial content</b></p>")
+ * }
+ * 
+ * // Multiple editors
+ * val titleState = rememberRichTextState()
+ * val contentState = rememberRichTextState()
+ * ```
+ * 
+ * This function is essential for proper rich text state management in Compose applications
+ * and ensures optimal user experience with automatic state preservation.
+ */
 @Composable
 public fun rememberRichTextState(): RichTextState {
     return rememberSaveable(saver = RichTextState.Saver) {
diff --git a/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/BasicRichText.kt b/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/BasicRichText.kt
@@ -1,5 +1,56 @@
 package com.mohamedrejeb.richeditor.ui
 
+/**
+ * BasicRichText - A foundational composable for displaying rich text content in read-only mode.
+ * 
+ * This composable serves as the core display component for rich text content and provides:
+ * 
+ * **Rich Text Display Capabilities**:
+ * - **Formatted Text Rendering**: Displays text with bold, italic, underline, color, and other formatting
+ * - **Interactive Links**: Clickable hyperlinks with hover states and custom styling
+ * - **List Visualization**: Properly formatted ordered and unordered lists with nesting
+ * - **Code Span Display**: Inline code formatting with background and border styling
+ * - **Custom Styling**: Support for custom rich span styles and visual effects
+ * - **Typography Integration**: Seamless integration with Compose typography systems
+ * 
+ * **Interaction Features**:
+ * - **Link Navigation**: Automatic link handling with platform-appropriate URL opening
+ * - **Text Selection**: Optional text selection for copying formatted content
+ * - **Hover Effects**: Mouse hover states for interactive elements (desktop platforms)
+ * - **Touch Feedback**: Appropriate touch feedback for interactive elements
+ * - **Accessibility**: Full screen reader and accessibility service integration
+ * 
+ * **Layout and Styling**:
+ * - **Text Flow**: Proper text wrapping, line breaking, and paragraph spacing
+ * - **Overflow Handling**: Configurable text overflow behavior (clip, ellipsis, visible)
+ * - **Line Limits**: Support for maximum and minimum line constraints
+ * - **Inline Content**: Support for embedding custom composables within text
+ * - **Text Measurement**: Provides text layout results for advanced positioning
+ * 
+ * **Performance Optimization**:
+ * - **Efficient Rendering**: Optimized for displaying large rich text documents
+ * - **Lazy Loading**: Supports lazy loading of images and embedded content
+ * - **Memory Management**: Efficient memory usage for complex formatted text
+ * - **Recomposition Optimization**: Minimal recompositions for better performance
+ * 
+ * **Platform Integration**:
+ * - **Cross-Platform**: Consistent rendering across Android, Desktop, iOS, and Web
+ * - **Image Loading**: Configurable image loading with custom ImageLoader support
+ * - **URL Handling**: Platform-appropriate URL handling and external link opening
+ * - **Font Support**: Support for custom fonts and platform-specific typography
+ * 
+ * **Usage Patterns**:
+ * - **Content Display**: Blog posts, articles, and formatted document display
+ * - **Message Rendering**: Chat messages and communication content with rich formatting
+ * - **Documentation**: Help text, tooltips, and instructional content
+ * - **Previews**: Read-only previews of rich text content being edited elsewhere
+ * - **Static Content**: Formatted static content like terms of service or about pages
+ * 
+ * This component is designed for scenarios where rich text content needs to be displayed
+ * without editing capabilities, providing optimal performance and user experience for
+ * read-only rich text presentation.
+ */
+
 import androidx.compose.foundation.gestures.awaitEachGesture
 import androidx.compose.foundation.text.BasicText
 import androidx.compose.foundation.text.InlineTextContent
diff --git a/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/BasicRichTextEditor.kt b/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/BasicRichTextEditor.kt
@@ -1,5 +1,46 @@
 package com.mohamedrejeb.richeditor.ui
 
+/**
+ * BasicRichTextEditor - The foundational composable for rich text editing functionality.
+ * 
+ * This composable serves as the core building block for all rich text editing interfaces and provides:
+ * 
+ * **Core Editing Capabilities**:
+ * - **Rich Text Input**: Handles text input with formatting preservation and application
+ * - **Selection Management**: Manages text selection, cursor positioning, and composition state
+ * - **Keyboard Integration**: Processes keyboard input, shortcuts, and IME actions
+ * - **Touch Interaction**: Handles tap gestures, text selection, and cursor placement
+ * - **Clipboard Operations**: Supports copy, cut, paste with rich formatting preservation
+ * 
+ * **Styling and Formatting**:
+ * - **Span Styles**: Applies bold, italic, underline, color, and other character-level formatting
+ * - **Paragraph Styles**: Manages paragraph-level formatting like alignment and indentation
+ * - **List Support**: Handles ordered and unordered lists with proper nesting
+ * - **Link Management**: Creates and manages hyperlinks with custom styling
+ * - **Custom Styles**: Supports custom rich span styles and visual transformations
+ * 
+ * **Platform Integration**:
+ * - **Cross-Platform**: Works consistently across Android, Desktop, iOS, and Web
+ * - **Accessibility**: Integrates with platform accessibility services
+ * - **Input Methods**: Supports various input methods and keyboard layouts
+ * - **Performance**: Optimized for smooth editing experience with large documents
+ * 
+ * **Architecture Features**:
+ * - **Decoration Box Pattern**: Uses decoration box for flexible UI customization
+ * - **State Management**: Integrates with RichTextState for reactive updates
+ * - **Modifier Support**: Fully supports Compose modifier chain for styling
+ * - **Interaction Source**: Provides interaction state for custom UI behaviors
+ * 
+ * **Usage Patterns**:
+ * - **Foundation Component**: Used as base for Material Design text fields (RichTextEditor, OutlinedRichTextEditor)
+ * - **Custom Implementations**: Enables building custom rich text editors with specific design requirements
+ * - **Minimal UI**: Provides rich text editing without built-in decorations like borders or labels
+ * - **Advanced Customization**: Allows full control over appearance through decoration box parameter
+ * 
+ * This composable is designed for developers who need maximum flexibility in creating rich text
+ * editing interfaces while maintaining full rich text functionality and cross-platform compatibility.
+ */
+
 import androidx.compose.foundation.interaction.Interaction
 import androidx.compose.foundation.interaction.MutableInteractionSource
 import androidx.compose.foundation.interaction.PressInteraction
diff --git a/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/material3/OutlinedRichTextEditor.kt b/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/material3/OutlinedRichTextEditor.kt
@@ -1,5 +1,53 @@
 package com.mohamedrejeb.richeditor.ui.material3
 
+/**
+ * OutlinedRichTextEditor (Material 3) - A Material Design 3 outlined text field with rich text editing capabilities.
+ * 
+ * This composable provides a Material Design 3 outlined text field experience with comprehensive rich text support:
+ * 
+ * **Material Design 3 Outlined Features**:
+ * - **Outlined Container**: Clean outlined design with customizable border colors and thickness
+ * - **Label Cutout**: Floating label with proper border cutout for seamless integration
+ * - **Focus Animation**: Smooth border color and thickness transitions on focus changes
+ * - **Supporting Text**: Helper text positioned below the field for guidance or validation
+ * - **Leading/Trailing Icons**: Icon slots with proper spacing and alignment
+ * - **Error Handling**: Comprehensive error state styling with color and border changes
+ * - **Transparent Background**: Clean appearance that works well on various backgrounds
+ * 
+ * **Rich Text Editing Features**:
+ * - **Character Formatting**: Bold, italic, underline, strikethrough, color, and font styling
+ * - **Paragraph Control**: Text alignment, indentation, line height, and spacing
+ * - **List Management**: Nested ordered and unordered lists with customizable styling
+ * - **Link Creation**: Interactive hyperlinks with hover states and custom appearance
+ * - **Code Formatting**: Inline code spans with syntax highlighting support
+ * - **Format Conversion**: Seamless import/export between HTML, Markdown, and Lexical formats
+ * 
+ * **Advanced Interaction**:
+ * - **Keyboard Shortcuts**: Full keyboard shortcut support for formatting operations
+ * - **Gesture Recognition**: Touch gestures for text selection and cursor positioning
+ * - **Clipboard Rich Text**: Preserves formatting in copy/paste operations
+ * - **Undo/Redo System**: Comprehensive undo/redo with formatting state preservation
+ * - **Selection Management**: Advanced text selection with formatting context awareness
+ * 
+ * **Design System Integration**:
+ * - **Theme Compatibility**: Automatically adapts to Material 3 color schemes and typography
+ * - **Density Support**: Responds to Material density settings for compact/comfortable layouts
+ * - **Motion Integration**: Uses Material motion specifications for animations
+ * - **Accessibility First**: Built-in accessibility features following Material guidelines
+ * - **Responsive Design**: Adapts to different screen sizes and orientations
+ * 
+ * **Use Cases & Applications**:
+ * - **Document Editing**: Professional document creation with rich formatting
+ * - **Content Management**: CMS interfaces requiring formatted text input
+ * - **Communication**: Email composition, messaging with rich text support
+ * - **Educational**: Note-taking applications with formatting capabilities
+ * - **Creative Writing**: Writing applications with advanced text formatting
+ * 
+ * The outlined variant is particularly suitable for forms and interfaces where a cleaner,
+ * less visually heavy appearance is desired while maintaining full rich text functionality
+ * and Material Design 3 compliance.
+ */
+
 import androidx.compose.foundation.interaction.Interaction
 import androidx.compose.foundation.interaction.MutableInteractionSource
 import androidx.compose.foundation.layout.*
diff --git a/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/material3/RichText.kt b/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/material3/RichText.kt
@@ -1,5 +1,56 @@
 package com.mohamedrejeb.richeditor.ui.material3
 
+/**
+ * RichText (Material 3) - A Material Design 3 text component for displaying rich text content.
+ * 
+ * This composable provides a Material Design 3 styled text display with comprehensive rich text support:
+ * 
+ * **Material Design 3 Integration**:
+ * - **Typography System**: Seamlessly integrates with Material 3 typography scale and font families
+ * - **Color System**: Automatically adapts to Material 3 color schemes and theme changes
+ * - **Content Color**: Respects Material 3 content color hierarchy and alpha values
+ * - **Density Support**: Responds to Material density settings for optimal spacing
+ * - **Theme Consistency**: Maintains visual consistency with other Material 3 components
+ * 
+ * **Rich Text Display Features**:
+ * - **Text Formatting**: Displays bold, italic, underline, strikethrough, and colored text
+ * - **Interactive Hyperlinks**: Clickable links with Material 3 color theming and hover states
+ * - **List Rendering**: Properly formatted ordered and unordered lists with Material spacing
+ * - **Code Spans**: Inline code display with Material 3 surface colors and typography
+ * - **Custom Styles**: Support for custom rich span styles following Material guidelines
+ * - **Paragraph Styling**: Text alignment, line height, and spacing following Material specs
+ * 
+ * **Typography and Layout**:
+ * - **Font Scaling**: Respects system font size preferences and accessibility settings
+ * - **Line Height**: Optimal line spacing for readability across different text sizes
+ * - **Text Overflow**: Configurable overflow handling with ellipsis or clipping
+ * - **Text Wrapping**: Intelligent word wrapping and line breaking
+ * - **Baseline Alignment**: Proper baseline alignment with other Material components
+ * 
+ * **Accessibility and Interaction**:
+ * - **Screen Reader Support**: Full accessibility support with proper content descriptions
+ * - **High Contrast**: Adapts to high contrast accessibility settings
+ * - **Touch Targets**: Appropriate touch target sizes for interactive elements
+ * - **Keyboard Navigation**: Support for keyboard navigation of interactive content
+ * - **Focus Management**: Proper focus handling for embedded interactive elements
+ * 
+ * **Performance and Platform**:
+ * - **Efficient Rendering**: Optimized text rendering for smooth scrolling and performance
+ * - **Cross-Platform**: Consistent appearance across Android, Desktop, iOS, and Web
+ * - **Memory Optimization**: Efficient memory usage for large text documents
+ * - **Image Integration**: Support for embedded images with Material loading states
+ * 
+ * **Common Use Cases**:
+ * - **Content Display**: Articles, blog posts, and formatted content in Material apps
+ * - **Message Display**: Chat messages and communication content with rich formatting
+ * - **Help Content**: Documentation, tooltips, and instructional text
+ * - **Card Content**: Rich text content within Material cards and surfaces
+ * - **List Items**: Formatted text within Material list items and components
+ * 
+ * This component is ideal for displaying rich text content in Material Design 3 applications
+ * where consistency with the design system and optimal user experience are priorities.
+ */
+
 import androidx.compose.foundation.text.InlineTextContent
 import androidx.compose.material3.LocalContentColor
 import androidx.compose.material3.LocalTextStyle
diff --git a/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/material3/RichTextEditor.kt b/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/material3/RichTextEditor.kt
diff --git a/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/material3/RichTextEditorDefaults.kt b/richeditor-compose/src/commonMain/kotlin/com/mohamedrejeb/richeditor/ui/material3/RichTextEditorDefaults.kt
diff --git a/sample/common/src/commonMain/kotlin/com/kjcommunities/KJDemoScreen.kt b/sample/common/src/commonMain/kotlin/com/kjcommunities/KJDemoScreen.kt
