KompKit v0.4.0-alpha.0

🏷️ KompKit v0.4.0-alpha.0

🚀 Overview

Fourth alpha release of KompKit, adding two new cross-platform utilities — clamp and throttle — across all three platforms (Web/TypeScript, Android/Kotlin, Flutter/Dart), alongside a formatCurrency default currency fix, comprehensive documentation expansion with real-world examples, and full version alignment.

---

🧩 Highlights

• New utility: clamp

  • Constrains a number within an inclusive [min, max] range
  • Pure, synchronous, zero dependencies on all platforms
  • Throws RangeError on NaN, Infinity, or min > max
  • Identical API across TypeScript, Kotlin, and Dart

• New utility: throttle

  • Limits a function to execute at most once per wait period
  • First call executes immediately; subsequent calls within the cooldown are ignored
  • Returns a Throttled<T> object with cancel() — mirrors the Debounced<T> shape
  • TypeScript: throttle(fn, wait) returning T & { cancel(): void }
  • Kotlin: requires CoroutineScope (same pattern as debounce); wait in milliseconds
  • Dart: wait is a Duration (idiomatic); returns Throttled<T> with cancel()
  • Validates wait > 0 on all platforms — throws on invalid input

• formatCurrency default currency fix (breaking)

  • Default changed from EUR → USD to align with the existing en-US default locale
  • Affects all three platforms
  • Pass currency: "EUR" explicitly to restore previous behavior

• Documentation expansion

  • All platform docs (web.md, android.md, flutter.md) expanded with real-world examples for clamp and throttle
  • React useEffect + useRef throttle cleanup pattern added
  • Vue onUnmounted throttle cleanup pattern added
  • Jetpack Compose LaunchedEffect throttle scroll tracking example added
  • Flutter StatefulWidget with initState/dispose lifecycle for throttle and debounce
  • Complete Flutter app example updated to demonstrate all 5 utilities
  • recipes.md: new cross-platform "throttled scroll header with clamped opacity" recipe
  • packages/core/web/README.md: expanded clamp and throttle sections
  • README.md: Quick Start updated to show all 5 utilities across all platforms

---

🧠 Technical Notes

• Node version: 20.x
• Java version: 17 (Temurin)
• Kotlin: 2.3.0
• TypeScript: 5.7+
• Flutter: 3.27.4 (stable)
• Dart SDK: >=3.0.0 <4.0.0
• Gradle: 8.5 via setup-gradle action

---

🧪 Validation

• ✅ Web build/tests pass — 43/43 (Vitest, tsup)
• ✅ Android build/tests pass — BUILD SUCCESSFUL (Kotlin 2.3.0, JUnit4)
• ✅ Flutter build/tests pass — 50/50 (flutter_test, intl 0.20.2)
• ✅ CI workflows verified on develop
• ✅ Documentation consistent across all platforms
• ✅ develop and release branches in sync at v0.4.0-alpha.0

---

⚠️ Breaking Changes

Area	Change	Migration
formatCurrency default currency	EUR → USD	Pass currency: "EUR" explicitly if needed
throttle Kotlin	Requires CoroutineScope parameter	Pass active scope: throttle<T>(wait, scope) { ... }
throttle Dart	wait is Duration, not a number	Use const Duration(milliseconds: 200)

---

🧱 Known Limitations (Alpha)

• Android module not yet published to Maven Central
• Dokka V1 deprecation warning (V2 migration planned)
• TypeScript/V8 silently falls back on unrecognized locale strings (documented platform divergence)
• Kotlin/JVM silently falls back on unrecognized locale strings (documented platform divergence)

---

🧩 Changelog

[v0.4.0-alpha.0] — 2026-03-01

Added

• clamp(value, min, max) utility on all platforms (TypeScript, Kotlin, Dart)
• throttle(fn, wait) utility on all platforms with cancel() support
• Throttled<T> type/class on all platforms mirroring Debounced<T> shape
• Real-world usage examples for clamp and throttle in all platform docs
• React useRef + useEffect throttle cleanup pattern in web.md
• Vue onUnmounted throttle cleanup pattern in web.md
• Jetpack Compose throttled scroll tracker example in android.md
• Flutter StatefulWidget throttle + dispose example in flutter.md
• Cross-platform "throttled scroll header with clamped opacity" recipe in recipes.md
• throttle and clamp entries in ARCHITECTURE.md API parity contract
• throttle and clamp FAQ entries in faq.md
• throttle rows in Platform Differences table in README.md

Changed

• formatCurrency default currency: EUR → USD on all platforms
• README.md Quick Start expanded to show all 5 utilities
• docs/CHANGELOG.md and packages/core/flutter/CHANGELOG.md updated
• docs/roadmap.md updated — 0.4.0-alpha.0 is now current state
• SECURITY.md supported versions table updated
• Version bumped to 0.4.0-alpha.0 in lerna.json, package.json, pubspec.yaml, and all docs

Fixed

• develop branch synced with release (was 1 commit behind after merge commit)
• Remote URL corrected to lowercase (Kompkit/kompkit)
• Stale Flutter version reference (3.24.0 → 3.27.4) in README_CI.md
• Wrong formatCurrency output ("1.234,56 €") in README.md Quick Start examples