docs(Slider): Add kdoc for the public apis

Author: levinzonr

slider/src/main/java/io/monstarlab/mosaic/slider/Slider.kt

@@ -15,6 +15,18 @@ import androidx.compose.ui.platform.LocalLayoutDirection
 import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.LayoutDirection
 
+/**
+ * A composable function that creates a slider UI component.
+ *
+ * @param value the current value of the slider
+ * @param onValueChange a callback function invoked when the slider value changes
+ * @param colors the colors used to customize the appearance of the slider
+ * @param modifier the modifier to be applied to the slider
+ * @param valueDistribution the strategy for distributing slider values
+ * @param range the range of values the slider can represent
+ * @param interactionSource the interaction source used to handle user input interactions
+ * @param thumb the composable function used to render the slider thumb
+ */
 @Composable
 public fun Slider(
     value: Float,

slider/src/main/java/io/monstarlab/mosaic/slider/SliderState.kt

@@ -12,6 +12,10 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import kotlinx.coroutines.coroutineScope
 
+/**
+ * A compose state for the Slider component
+ * Responsible for managing internal properties such as offset value and drag / click behaviours
+ */
 public class SliderState(
     value: Float,
     private val valueDistribution: SliderValueDistribution,
@@ -32,10 +36,14 @@ public class SliderState(
         return calcFraction(0f, totalWidth, rawOffset)
     }
 
+    /**
+     * Current value of the slider
+     * If value of the slider is out of the [range] it will be coerced into it
+     */
     public var value: Float
-        get() = scaleToUserValue(rawOffset)
+        get() = scaleToUserValue(rawOffset).coerceIn(range)
         set(value) {
-            rawOffset = scaleToOffset(value)
+            rawOffset = scaleToOffset(value.coerceIn(range))
         }
 
     private val dragScope: DragScope = object : DragScope {

slider/src/main/java/io/monstarlab/mosaic/slider/SliderValueDistribution.kt

@@ -2,18 +2,47 @@ package io.monstarlab.mosaic.slider
 
 import kotlin.math.sqrt
 
+/**
+ * Determines how the values will be distributed across the slider
+ * Usually the values are distributed in a linear fashion, this interfaces allows
+ * to control the distribution using simple math expressions
+ * @see ParabolicValueDistribution to see how values can be distributed using parabolic curve
+ */
 public interface SliderValueDistribution {
 
+    /**
+     * Interpolates a value based on the distribution strategy.
+     * @param value the input value to interpolate
+     * @return the interpolated value based on the distribution strategy
+     */
     public fun interpolate(value: Float): Float
 
+    /**
+     * Inversely interpolates a value from the output range to the input range based on the distribution strategy.
+     *
+     * @param value the output value to inverse interpolate
+     * @return the inverse interpolated value based on the distribution strategy
+     */
     public fun inverse(value: Float): Float
 
     public companion object {
 
+        /**
+         * Creates a [SliderValueDistribution] with a parabolic distribution strategy.
+         *
+         * @param a coefficient of the x^2 term in the parabolic equation
+         * @param b coefficient of the x term in the parabolic equation
+         * @param c constant term in the parabolic equation
+         * @return a [SliderValueDistribution] instance with a parabolic distribution strategy
+         */
         public fun parabolic(a: Float, b: Float, c: Float): SliderValueDistribution {
             return ParabolicValueDistribution(a, b, c)
         }
 
+        /**
+         * A linear distribution strategy where the input value is directly mapped to the output value.
+         * Used in [Slider] by default
+         */
         public val Linear: SliderValueDistribution = object : SliderValueDistribution {
             override fun interpolate(value: Float): Float {
                 return value
@@ -26,6 +55,18 @@ public interface SliderValueDistribution {
     }
 }
 
+
+/**
+ * Represents a parabolic distribution strategy for slider values.
+ *
+ * This strategy calculates interpolated and inversely interpolated values based on a parabolic equation:
+ * f(x) = a * x^2 + b * x + c
+ *
+ * @property a coefficient of the x^2 term in the parabolic equation
+ * @property b coefficient of the x term in the parabolic equation
+ * @property c constant term in the parabolic equation
+ * @constructor Creates a ParabolicValueDistribution with the given coefficients.
+ */
 public class ParabolicValueDistribution(
     private val a: Float,
     private val b: Float,