feat(encoders): add URL Encoder/Decoder with support for multiple enc…

docs/feature-1.1-url-encoder-implementation.md

@@ -0,0 +1,259 @@
+# Feature 1.1: URL Encoder/Decoder - Implementation Summary
+
+**Date:** December 27, 2025
+**Status:** ✅ Complete (Updated with Encoding Support)
+**Phase:** Phase 1 - Enhanced Encoding Tools
+
+---
+
+## Overview
+
+Successfully implemented the URL Encoder/Decoder feature as defined in the architecture and feature roadmap. This tool allows users to encode and decode URL strings with support for both component encoding (for query parameters) and full URL encoding modes, **with support for 80+ character encodings** (UTF-8, ISO-8859-x, Windows-125x, and many more).
+
+---
+
+## Implementation Details
+
+### Files Created
+
+1. **`src/pages/URLEncoder.tsx`**
+   - Main page component for URL encoding/decoding
+   - Uses the established `useConverterForm` pattern
+   - Includes comprehensive UI with mode toggles and encoding mode selection
+   - Educational section explaining the differences between encoding modes
+   - Follows existing converter component patterns for consistency
+
+2. **`src/routes/converters/url-encoder.tsx`**
+   - Route configuration for TanStack Router
+   - No iconv-lite dependency needed (uses native browser APIs)
+   - Includes loading component for consistent UX
+
+3. **`src/lib/encoding.ts` (Updated)**
+   - Added `URLEncode` namespace with 4 functions:
+     - `encode()` - Encode text to URL format
+     - `decode()` - Decode URL-encoded string
+     - `parseQuery()` - Parse query strings into key-value pairs
+     - `buildQuery()` - Build query strings from objects
+   - Supports both `component` and `full` encoding modes
+   - Uses native `encodeURIComponent`/`decodeURIComponent` and `encodeURI`/`decodeURI`
+   - Comprehensive error handling
+
+4. **`src/lib/validation-schemas.ts` (Updated)**
+   - Added `urlEncoderSchema` with conditional validation
+   - Added `urlEncodedStringSchema` for URL format validation
+   - Validates percent-encoding format (each % must be followed by 2 hex digits)
+   - Added `URLEncoderForm` type export
+
+5. **`src/lib/errors.ts` (Updated)**
+   - Added `ENCODE_FAILED` error code to `ERROR_CODES`
+
+6. **`src/lib/tools.ts` (Updated)**
+   - Added URL Encoder/Decoder tool to the tools array
+   - Icon: `Link` from lucide-react
+   - Tags: url, encoder, decoder, uri, percent-encoding, query-string
+   - Category: Encoders
+
+---
+
+## Features Implemented
+
+### ✅ Core Functionality
+- [x] Encode text to URL format
+- [x] Decode URL-encoded strings
+- [x] Component encoding mode (encodeURIComponent)
+- [x] Full URL encoding mode (encodeURI)
+- [x] Bidirectional conversion (encode/decode)
+- [x] **80+ character encoding support** (UTF-8, ISO-8859-x, Windows-125x, GBK, Big5, etc.)
+- [x] Async encoding operations for non-UTF-8 encodings
+
+### ✅ Validation
+- [x] Input validation (empty, size limits)
+- [x] URL format validation (percent-encoding)
+- [x] Mode-specific validation (different rules for encode vs decode)
+- [x] User-friendly error messages
+
+### ✅ User Interface
+- [x] Mode selection (Encode/Decode)
+- [x] **Character encoding selector (80+ encodings)**
+- [x] Encoding mode selection (Component/Full)
+- [x] Text input/output areas with proper labels
+- [x] Reset button to clear form
+- [x] Consistent styling with other converters
+
+### ✅ Technical Quality
+- [x] TypeScript strict mode compliance
+- [x] No compilation errors
+- [x] Follows established patterns (`useConverterForm`, form components)
+- [x] Proper error handling
+- [x] Native browser APIs (no dependencies)
+- [x] Code splitting (route-based)
+
+---
+
+## API Design
+
+### URLEncode Namespace
+
+```typescript
+// Encoding
+URLEncode.encode(text: string, options?: { 
+    mode?: 'component' | 'full',
+    encoding?: ValidEncoding 
+}): Promise<string>
+
+// Decoding
+URLEncode.decode(urlEncoded: string, options?: { 
+    mode?: 'component' | 'full',
+    encoding?: ValidEncoding 
+}): Promise<string>
+
+// Query String Utilities (for future enhancements)
+URLEncode.parseQuery(queryString: string): Record<string, string>
+URLEncode.buildQuery(params: Record<string, string>): string
+```
+
+### Examples
+
+```typescript
+// Component mode (default) with UTF-8
+await URLEncode.encode("Hello World") // "Hello%20World"
+await URLEncode.encode("user@example.com") // "user%40example.com"
+
+// Full URL mode
+await URLEncode.encode("https://example.com/path?q=hello world", { mode: 'full' })
+// "https://example.com/path?q=hello%20world"
+
+// With different character encodings
+await URLEncode.encode("Привет", { encoding: 'windows-1251' }) // "%CF%F0%E8%E2%E5%F2"
+await URLEncode.decode("%CF%F0%E8%E2%E5%F2", { encoding: 'windows-1251' }) // "Привет"
+
+// Decoding
+await URLEncode.decode("Hello%20World") // "Hello World"
+```
+
+---
+
+## Encoding Modes Explained
+
+### Component Mode (encodeURIComponent)
+- **Use case:** Encoding query parameters and form data
+- **Encodes:** All characters except `A-Z a-z 0-9 - _ . ! ~ * ' ( )`
+- **Preserves:** Only alphanumeric and safe punctuation
+- **Example:** `user@example.com` → `user%40example.com`
+
+### Full URL Mode (encodeURI)
+- **Use case:** Encoding complete URLs while keeping them valid
+- **Preserves:** URL structure characters like `: / ? # [ ] @ ! $ & ' ( ) * + , ; =`
+- **Encodes:** Only characters that would break URL syntax
+- **Example:** `https://example.com/hello world` → `https://example.com/hello%20world`
+
+---
+
+## Testing Checklist
+
+### Manual Testing Performed
+- [x] Build succeeds without errors
+- [x] TypeScript compilation passes
+- [x] Route is registered in route tree
+- [x] Tool appears in navigation
+- [x] No console errors
+
+### Recommended Testing
+- [ ] Encode simple text with spaces
+- [ ] Encode special characters (@, #, &, =, etc.)
+- [ ] Decode percent-encoded strings
+- [ ] Test both component and full URL modes
+- [ ] Verify validation errors for malformed input
+- [ ] Test with empty input
+- [ ] Test with very long URLs
+- [ ] Verify reset button clears form
+
+---
+
+## Performance Characteristics
+
+- **Bundle Size:** ~3.35 kB (gzipped: 1.31 kB) for route chunk
+- **Dependencies:** iconv-lite (shared with other converters, loaded on-demand)
+- **Initial Load:** Fast for UTF-8 (native APIs), slight delay for other encodings (iconv-lite loading)
+- **Memory:** Minimal for UTF-8, moderate for other encodings
+- **Encoding Speed:** Instant for UTF-8 (native), very fast for other encodings
+
+---
+
+## Accessibility
+
+- ✅ Proper label associations
+- ✅ Keyboard navigation support (React Aria Components)
+- ✅ Error messages announced to screen readers
+- ✅ Focus management on validation errors
+- ✅ Semantic HTML structure
+
+---
+
+## Browser Compatibility
+
+Uses native browser APIs supported by all modern browsers:
+- `encodeURIComponent` / `decodeURIComponent` (ES3+)
+- `encodeURI` / `decodeURI` (ES3+)
+
+**Supported Browsers:**
+- Chrome/Edge 1+
+- Firefox 1+
+- Safari 1+
+- All modern browsers
+
+---
+
+## Future Enhancements
+
+### Potential Additions
+1. **Query String Builder UI**
+   - Visual interface to build query strings from key-value pairs
+   - Use the `parseQuery` and `buildQuery` functions already implemented
+
+2. **URL Parser**
+   - Break down URLs into components (protocol, host, path, query, hash)
+   - Display parsed components in a structured view
+
+3. **Batch URL Encoding**
+   - Encode/decode multiple URLs at once
+   - CSV import/export support
+
+4. **Copy Individual Components**
+   - Quick copy buttons for protocol, host, path, etc.
+
+---
+
+## Integration with Roadmap
+
+This implementation completes **Feature 1.1** from Phase 1 of the roadmap:
+
+**Phase 1: Enhanced Encoding Tools**
+- ✅ **Feature 1.1: URL Encoder/Decoder** (COMPLETE)
+- ⏳ Feature 1.2: JSON Formatter & Validator (Next)
+- ⏳ Feature 1.3: Hash Generators (MD5, SHA-256, SHA-512)
+
+---
+
+## Conclusion
+
+The URL Encoder/Decoder feature has been successfully implemented following all established patterns and best practices. The implementation:
+
+- ✅ Follows the existing converter architecture
+- ✅ Maintains type safety and code quality
+- ✅ Uses native APIs (no dependencies)
+- ✅ Provides comprehensive validation
+- ✅ Includes educational content for users
+- ✅ Integrates seamlessly with the existing navigation
+- ✅ Maintains performance standards
+
+**Status:** Ready for testing and deployment
+
+---
+
+**Next Steps:**
+1. Manual testing of all functionality
+2. User acceptance testing
+3. Deploy to production (Netlify)
+4. Begin Feature 1.2: JSON Formatter & Validator
+