Merge pull request #110 from compose-fluent/doc

feat: Documents.

Author: Konyaco

fluent/src/commonMain/kotlin/io/github/composefluent/Colors.kt

@@ -1,5 +1,21 @@
 package io.github.jpy.wangposefluent
 
+/**
+ * Marks declarations that are part of an experimental fluent API.
+ *
+ * Experimental fluent APIs are subject to change or removal in future releases.
+ * The design and structure of these APIs are not considered stable, and breaking
+ * changes may occur without a major version increment.
+ *
+ * Using elements marked with this annotation requires explicit opt-in, either by
+ * applying the `@OptIn(ExperimentalFluentApi::class)` annotation to the calling site
+ * or by enabling the `-opt-in=io.github.jpy.wangposefluent.ExperimentalFluentApi` compiler
+ * argument.
+ *
+ * **Warning:** Use of experimental fluent APIs should be carefully considered, as
+ * they might introduce unforeseen compatibility issues or unexpected behavior changes
+ * when updating to newer versions of the library.
+ */
 @RequiresOptIn(message = "This is an experimental fluent API.")
 @Target(
     AnnotationTarget.CLASS,

fluent/src/commonMain/kotlin/io/github/composefluent/ExperimentalFluentApi.kt

@@ -19,6 +19,19 @@ import io.github.jpy.wangposefluent.component.ContentDialogHostState
 import io.github.jpy.wangposefluent.component.LocalContentDialog
 import io.github.jpy.wangposefluent.component.ProvideFontIcon
 
+/**
+ * FluentTheme is the root component of the Fluent Design System for Compose.
+ * It provides the default theming values and a [MaterialContainer] for acrylic effects.
+ * **Note:** This function is designed to be placed inside a Window or View. For global
+ * theme configuration, consider using [FluentThemeConfiguration].
+ *
+ * @param colors The colors to use for the theme. Defaults to [FluentTheme.colors].
+ * @param typography The typography to use for the theme. Defaults to [FluentTheme.typography].
+ * @param cornerRadius The corner radius to use for the theme. Defaults to [FluentTheme.cornerRadius].
+ * @param useAcrylicPopup Whether to use acrylic for popups. Defaults to [LocalAcrylicPopupEnabled.current].
+ * @param compactMode Whether to use compact mode. Defaults to true.
+ * @param content The content to display within the theme.
+ */
 @ExperimentalFluentApi
 @Composable
 fun FluentTheme(
@@ -56,7 +69,19 @@ fun FluentTheme(
 }
 
 /**
- * Uses for override theme configuration
+ * Overrides individual theme configuration options for a subset of the UI tree.
+ *
+ * This allows you to locally modify aspects of the theme, such as colors, typography,
+ * corner radius, compact mode, and whether acrylic popups are used,
+ * for the components within the provided `content`.
+ *
+ * @param colors The colors to use for this configuration scope. Defaults to the current [FluentTheme.colors].
+ * @param typography The typography to use for this configuration scope. Defaults to the current [FluentTheme.typography].
+ * @param cornerRadius The corner radius values to use for this configuration scope. Defaults to the current [FluentTheme.cornerRadius].
+ * @param useAcrylicPopup Whether to use acrylic for popups within this configuration scope. Defaults to the current value of [LocalAcrylicPopupEnabled].
+ * @param compactMode Whether compact mode is enabled within this configuration scope. Defaults to the current value of [LocalCompactMode].
+ * @param contentDialogHostState The state of the content dialog host to use for this configuration scope. Defaults to the current value of [LocalContentDialog].
+ * @param content The composable content that will inherit the specified theme configuration.
  */
 @ExperimentalFluentApi
 @Composable
@@ -85,6 +110,14 @@ fun FluentThemeConfiguration(
     )
 }
 
+/**
+ * FluentTheme provides a default theme for your application using the Fluent Design System.
+ * It applies default colors and typography, and enables compact mode.
+ *
+ * @param colors The colors to use for the theme. Defaults to the current FluentTheme colors.
+ * @param typography The typography to use for the theme. Defaults to the current FluentTheme typography.
+ * @param content The composable content to be themed.
+ */
 @OptIn(ExperimentalFluentApi::class)
 @Composable
 fun FluentTheme(
@@ -95,6 +128,16 @@ fun FluentTheme(
     FluentTheme(colors, typography, LocalCornerRadius.current, useAcrylicPopup = false, compactMode = true, content)
 }
 
+/**
+ * A composable that provides a compact mode configuration for its content.
+ *
+ * This function wraps the provided content within a [CompositionLocalProvider] that sets the
+ * [LocalCompactMode] to the specified [enabled] value. This allows components within the
+ * [content] to react to the compact mode setting and adjust their appearance or behavior accordingly.
+ *
+ * @param enabled Whether compact mode should be enabled for the wrapped content. Defaults to `true`.
+ * @param content The composable content that should be provided with the compact mode setting.
+ */
 @Composable
 fun CompactMode(enabled: Boolean = true, content: @Composable () -> Unit) {
     CompositionLocalProvider(
@@ -103,22 +146,38 @@ fun CompactMode(enabled: Boolean = true, content: @Composable () -> Unit) {
     )
 }
 
+/**
+ * Helper object to access the current Fluent Theme properties in a type-safe way.
+ */
 object FluentTheme {
+
+    /**
+     * The current [Colors] provided by the [FluentTheme].
+     */
     val colors: Colors
         @Composable
         @ReadOnlyComposable
         get() = LocalColors.current
 
+    /**
+     * The typography used by the theme.
+     */
     val typography: Typography
         @Composable
         @ReadOnlyComposable
         get() = LocalTypography.current
 
+    /**
+     * CompositionLocal for the current [Shapes]
+     */
     val shapes: Shapes
         @Composable
         @ReadOnlyComposable
         get() = LocalShapes.current
 
+    /**
+     * Represents the corner radius values for various components in the theme.
+     */
     val cornerRadius: CornerRadius
         @Composable
         @ReadOnlyComposable
@@ -154,5 +213,19 @@ private class EmptyMaterialContainerScope : MaterialContainerScope {
 
 internal val LocalAcrylicPopupEnabled = staticCompositionLocalOf { true }
 
+/**
+ * Creates a Fluent light theme color scheme.
+ *
+ * @param accent The accent color to be used for generating the color scheme. Defaults to a specific blue color (0xFF0078D4).
+ * @return A [Colors] object representing the light theme color scheme.
+ */
 fun lightColors(accent: Color = Color(0xFF0078D4)): Colors = Colors(generateShades(accent), false)
+
+
+/**
+ * Creates a Fluent dark theme color scheme.
+ *
+ * @param accent The accent color to be used for generating the color scheme. Defaults to a specific blue color (0xFF0078D4).
+ * @return A [Colors] object representing the dark theme color scheme.
+ */
 fun darkColors(accent: Color = Color(0xFF0078D4)): Colors = Colors(generateShades(accent), true)

fluent/src/commonMain/kotlin/io/github/composefluent/FluentTheme.kt

@@ -8,15 +8,40 @@ import androidx.compose.ui.graphics.Shape
 import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp
 
-/** https://learn.microsoft.com/en-us/windows/apps/design/signature-experiences/geometry */
-
-/** align Shape and CornerRadius style properties */
+/**
+ * Aligns style properties related to geometry, such as [Shape] and [CornerRadius].
+ *
+ * This interface serves as a common structure for defining geometric properties
+ * across different types of visual elements within a UI. It provides a consistent
+ * way to access geometry settings for different design use cases:
+ * - [overlay]: Geometry for elements that appear above other content, such as dialogs or flyouts.
+ * - [control]: Geometry for interactive controls, such as buttons, text fields, or checkboxes.
+ * - [intersectionEdge]: Geometry for elements at the intersection of other elements,
+ *   typically used for visual separation or emphasis at boundaries.
+ *
+ * The type parameter [Type] allows this interface to be used with different data types
+ * representing geometric properties, such as [Shape] or [Dp] for corner radius.
+ *
+ * Based on the Microsoft Fluent Design System principles for geometry:
+ * See [https://learn.microsoft.com/en-us/windows/apps/design/signature-experiences/geometry]
+ */
 interface Geometry<Type> {
     val overlay: Type
     val control: Type
     val intersectionEdge: Type
 }
 
+/**
+ * Defines the shapes used for different elements in the Fluent design system.
+ *
+ * This class aligns with the principles described in the Microsoft documentation on Geometry.
+ * See [https://learn.microsoft.com/en-us/windows/apps/design/signature-experiences/geometry]
+ * for more details.
+ *
+ * @property overlay The shape used for elements like overlays.
+ * @property control The shape used for control elements like buttons and text fields.
+ * @property intersectionEdge The shape used for elements at the intersection edge.
+ */
 @Immutable
 class Shapes(
     override val overlay: Shape,
@@ -40,6 +65,14 @@ internal fun createShape(cornerRadius: Dp): Shape {
     }
 }
 
+/**
+ * Converts a [CornerRadius] object to a [Shapes] object.
+ *
+ * This function maps the overlay, control, and intersection edge [Dp] values from the [CornerRadius]
+ * to corresponding [Shape] objects using the [createShape] function.
+ *
+ * @return A [Shapes] object representing the corner radius as shapes.
+ */
 fun CornerRadius.toShapes(): Shapes {
     return Shapes(
         overlay = createShape(overlay),
@@ -48,6 +81,16 @@ fun CornerRadius.toShapes(): Shapes {
     )
 }
 
+/**
+ * Corner radius values for different geometric elements in the UI.
+ *
+ * These values are based on the Microsoft Fluent design system's guidance on geometry.
+ * https://learn.microsoft.com/en-us/windows/apps/design/signature-experiences/geometry
+ *
+ * @property overlay The corner radius for overlay elements.
+ * @property control The corner radius for control elements.
+ * @property intersectionEdge The corner radius for elements at intersection edges.
+ */
 @Immutable
 class CornerRadius(
     override val overlay: Dp,

fluent/src/commonMain/kotlin/io/github/composefluent/Geometry.kt

@@ -2,4 +2,10 @@ package io.github.jpy.wangposefluent
 
 import androidx.compose.runtime.compositionLocalOf
 
+/**
+ * CompositionLocal used to pass the default content alpha down the tree.
+ *
+ * This is used to provide a default alpha for text, icons and other content that can
+ * be changed by a parent component.
+ */
 val LocalContentAlpha = compositionLocalOf { 1f }

fluent/src/commonMain/kotlin/io/github/composefluent/LocalContentAlpha.kt

@@ -3,4 +3,11 @@ package io.github.jpy.wangposefluent
 import androidx.compose.runtime.compositionLocalOf
 import androidx.compose.ui.graphics.Color
 
+/**
+ * CompositionLocal to pass the content color down the tree. For example, a `Button` may provide
+ * a default content color for the text and iconography inside it.
+ *
+ * This is typically used with the alpha applied to the color to provide a useful default for
+ * text and iconography.
+ */
 val LocalContentColor = compositionLocalOf { Color.Unspecified }

fluent/src/commonMain/kotlin/io/github/composefluent/LocalContentColor.kt

@@ -44,7 +44,19 @@ internal val LocalTypography = staticCompositionLocalOf {
 }
 
 /**
+ * The Fluent Design typography system, providing a set of predefined text styles.
+ *
+ * Based on the guidelines from Microsoft's Fluent Design documentation:
  * https://docs.microsoft.com/en-us/windows/apps/design/signature-experiences/typography
+ *
+ * @property caption Style for smaller text, often used for labels or annotations.
+ * @property body Standard body text style.
+ * @property bodyStrong Bold version of the standard body text style.
+ * @property bodyLarge Larger version of the standard body text style.
+ * @property subtitle Style for subtitles or secondary headings.
+ * @property title Style for main titles.
+ * @property titleLarge Style for large titles, suitable for prominent headings.
+ * @property display Style for very large text, often used for headlines or displays.
  */
 @Immutable
 class Typography(
@@ -58,8 +70,19 @@ class Typography(
     val display: TextStyle
 )
 
+/**
+ * CompositionLocal containing the current [TextStyle] for text components.
+ */
 val LocalTextStyle = compositionLocalOf(structuralEqualityPolicy()) { TextStyle.Default }
 
+/**
+ * This composable provides a [TextStyle] to the composition local tree.
+ * Any text composables within the `content` lambda will use this provided text style.
+ * The provided [value] is merged with the current [LocalTextStyle].
+ *
+ * @param value The [TextStyle] to provide. This will be merged with the current [LocalTextStyle].
+ * @param content The composable content that will inherit the provided [TextStyle].
+ */
 @Composable
 fun ProvideTextStyle(value: TextStyle, content: @Composable () -> Unit) {
     val mergedStyle = LocalTextStyle.current.merge(value)

fluent/src/commonMain/kotlin/io/github/composefluent/Typography.kt

@@ -20,6 +20,26 @@ import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp
 import io.github.jpy.wangposefluent.FluentTheme
 
+/**
+ * Applies an elevation effect to the composable.
+ *
+ * This function provides a way to add depth and visual hierarchy to UI elements.
+ * It uses different approaches based on the elevation value.
+ *
+ * When the elevation is less than 1dp, no elevation is applied.
+ * When the elevation is between 1dp and 3dp, a border with a color from the theme is applied.
+ * - If the elevation is between 1dp and 2dp, a `SolidColor` is used for the border.
+ * - If the elevation is between 2dp and 3dp, a provided [strokeShadow] brush is used for the border.
+ * For elevation of 3dp or more, a more complex shadow effect using [platformElevation] is applied.
+ *
+ * @param elevation The desired elevation (depth) of the composable.
+ * @param shape The shape of the composable, which affects how the shadow is drawn.
+ * @param strokeShadow The brush to use for the border when elevation is between 2dp and 3dp.
+ * It defaults to `FluentTheme.colors.borders.circle` if shape is [CircleShape] otherwise `FluentTheme.colors.borders.control`.
+ * @param isDarkTheme A boolean indicating if dark mode is active, which influences the shadow color.
+ * Defaults to `FluentTheme.colors.darkMode`.
+ * @return A [Modifier] that applies the elevation effect.
+ */
 @Composable
 fun Modifier.elevation(
     elevation: Dp,
@@ -132,6 +152,23 @@ internal fun Modifier.platformElevation(
     }
 }
 
+/**
+ * Default elevation values for different UI components.
+ *
+ * These values represent the recommended elevation levels for various elements
+ * in a Fluent Design system. Elevation is used to create a sense of depth and
+ * hierarchy in the UI.
+ *
+ * The higher the elevation, the more prominent the element appears to be,
+ * as if it's closer to the user's eye.
+ *
+ * - `layer`: Elevation for a basic background layer. Represents no elevation.
+ * - `control`: Elevation for interactive controls like buttons and toggles.
+ * - `cardRest`: Elevation for resting cards.
+ * - `tooltip`: Elevation for tooltips.
+ * - `flyout`: Elevation for flyout menus.
+ * - `dialog`: Elevation for modal dialogs, representing the highest level of prominence.
+ */
 object ElevationDefaults {
     val layer: Dp = 0.dp
     val control: Dp = 2.dp

fluent/src/commonMain/kotlin/io/github/composefluent/background/Elevation.kt

@@ -79,6 +79,18 @@ fun Layer(
     )
 }
 
+/**
+ * A composable that provides a layered background with customizable shape, color, border, and elevation.
+ *
+ * @param modifier The [Modifier] to be applied to the layer.
+ * @param shape The [Shape] of the layer's background. Defaults to [FluentTheme.shapes.control].
+ * @param color The background [Color] of the layer. Defaults to [FluentTheme.colors.background.layer.default].
+ * @param contentColor The preferred [Color] for content inside this layer. Defaults to [FluentTheme.colors.text.text.primary].
+ * @param border The [BorderStroke] to draw around the layer. If null, no border will be drawn. Defaults to a 1.dp border with [FluentTheme.colors.stroke.card.default].
+ * @param backgroundSizing Specifies how the background extends in relation to the border. See [BackgroundSizing] for options. Defaults to [BackgroundSizing.OuterBorderEdge].
+ * @param elevation The elevation of the layer, which affects the shadow. Defaults to 0.dp.
+ * @param content The composable content to be placed inside the layer.
+ */
 @Composable
 fun Layer(
     modifier: Modifier = Modifier,
@@ -103,6 +115,19 @@ fun Layer(
     )
 }
 
+/**
+ * A composable that provides a background layer with customizable shape, color, border, and elevation.
+ *
+ * @param modifier The [Modifier] to be applied to the layer.
+ * @param shape The [Shape] of the layer's background. Defaults to `FluentTheme.shapes.control`.
+ * @param color The background [Color] of the layer. Defaults to `FluentTheme.colors.background.layer.default`.
+ * @param contentColor The default color for the content inside the layer. Defaults to `FluentTheme.colors.text.text.primary`.
+ * @param border An optional [BorderStroke] to be drawn around the layer's background. Defaults to a 1.dp solid border using `FluentTheme.colors.stroke.card.default`.
+ * @param backgroundSizing Determines how the background extends in relation to the border. Defaults to [BackgroundSizing.OuterBorderEdge].
+ * @param clipContent If `true`, the content will be clipped to the layer's shape. Defaults to `false`.
+ * @param elevation The elevation of the layer, used for shadow effects. Defaults to `0.dp`.
+ * @param content The content to be displayed within the layer.
+ */
 @Composable
 fun Layer(
     modifier: Modifier = Modifier,