CONTRIBUTION.md

Contributing to Compose-Fluent-UI

Hello and welcome! 🎉

Our project components are designed using the Windows UI Kit Figma guidelines. Therefore, the layout and style of the components must strictly adhere to this design guide. Additionally, the components showcased in the Gallery should align as closely as possible with this design guide.

We are thrilled to have you considering contributing to Compose-Fluent-UI. Contributions are what make the open-source community such an incredible place to learn, inspire, and create. Here are some guidelines to help you get started:

Getting Started

• Fork this repository: Click on the "Fork" button at the top right of this page. This will create a copy of the repository in your account.
• Select the Dev branch: Choose the dev branch as your base branch.
• Create a new branch: Create a new branch from dev for your feature or bug fix using git checkout -b your-branch-name.
• Base all development work on your new branch: Ensure that all your development work is committed to the branch you just created from dev.

Developing Components

• Create the source code: In the fluent/components directory, create the source code for the component that corresponds to the Windows UI Kit.

// Button.kt
package io.github.composefluent.components

• Handle internal classes: If your component involves internal classes that may be used by other components (such as OverflowRow), create the relevant classes in the appropriate package (e.g., /layout).

// OverflowRow.kt
package io.github.composefluent.layout.overflow

@Composable
internal fun OverflowRow(
    modifier: Modifier = Modifier,
    overflow: OverflowPosition = OverflowPosition.End,
    state: OverflowRowState = rememberOverflowRowState(),
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    verticalAlignment: Alignment.Vertical = Alignment.CenterVertically,
    overflowAction: @Composable OverflowActionScope.() -> Unit = {},
    contentPadding: PaddingValues = PaddingValues(),
    alwaysShowOverflowAction: Boolean = false,
    content: OverflowRowScope.() -> Unit
)

• Adhere to guidelines: When developing, strictly follow the Windows UI Kit for layout, typography, and color.
• Include TODOs for animations: If your component involves animations and you're unsure of the specific parameters to use, add a TODO note.

Testing and Showcasing Components

The Gallery app uses KSP and KotlinPoet to automatically generate a navigation tree and Kotlin example source code. Below are the steps to add a component example page in the Gallery:

1. Create [YourComponent]Screen.kt: In the package corresponding to the component group, create a [YourComponent]Screen.kt file.

// ButtonScreen.kt
package io.github.composefluent.gallery.screen.basicinput

2. Create a method with @Component annotation: Create a method named [YourComponent]Screen and annotate it with @Component, providing the relevant description and index.

// ButtonScreen.kt
@Component(index = 0, description = "A control that responds to user input")
@Composable
fun ButtonScreen() {

}

3. Use GalleryPage method: In this method, use the GalleryPage method to create a uniform component example page layout. The GalleryPage method takes componentPath and galleryPath as parameters, which are provided by the FluentSourceFile and ComponentPagePath classes generated by KSP, indicating the source code path of the component and the corresponding Gallery example code path.

// ButtonScreen.kt
@Component(index = 0, description = "A control that responds to user input")
@Composable
fun ButtonScreen() {
    GalleryPage(
        componentPath = FluentSourceFile.Button,
        galleryPath = ComponentPagePath.ButtonScreen,
    ) {
        // Sample sections.
    }
}

4. Use Section method in GalleryPage: Within GalleryPage, use the Section method for each component example. The Section method provides output and options parameters for adjusting options and display output. The sourceCode parameter should be the global variable generated by the @Sample annotation (which contains the component source code).

// ButtonScreen.kt
@Component(index = 0, description = "A control that responds to user input")
@Composable
fun ButtonScreen() {
    GalleryPage(
        componentPath = FluentSourceFile.Button,
        galleryPath = ComponentPagePath.ButtonScreen,
    ) {
        val clickTextContent = remember { mutableStateOf("") }
        val buttonEnabled = remember { mutableStateOf(true) }
        Section(
            title = "A simple Button with text content.",
            content = {
                ButtonSample(enabled = buttonEnabled.value) { clickTextContent.value = "You clicked: Button 1" }
            },
            output = {
                if (clickTextContent.value.isNotBlank()) {
                    Text(clickTextContent.value)
                }
            },
            options = {
                CheckBox(
                    checked = !buttonEnabled.value,
                    onCheckStateChange = { buttonEnabled.value = !it },
                    label = "Disable button"
                )
            },
            sourceCode = sourceCodeOfButtonSample
        )
    }
}

5. Create an example: In the [YourComponent]Screen.kt file, add a new method named [YourComponentCase]Sample with a private visibility modifier, and annotate this method with @Sample. This will generate a global variable sourceCodeOf[YourComponentCase]Sample, which should be assigned to the sourceCode parameter in the corresponding Section.

//ButtonScreen.kt
@Sample
@Composable
private fun ButtonSample(enabled: Boolean = true, onClick: () -> Unit) {
    Button(disabled = !enabled, onClick = onClick) {
        Text("Standard Compose Button")
    }
}

6. Add new groups if needed: If you cannot find the appropriate group for the component, add a new group in the ComponentGroupInfo object, following the format of the existing groups. After adding the group, place the Screen file in the corresponding package.

// ComponentGrupInfo.kt
package io.github.composefluent.gallery.component

object ComponentGroupInfo {
    prival const val screenPackage: String = "io.github.composefluent.gallery.screen"

    // Basic Input is group name, ChckboxChecked is icon, packageMap is the component screens under this group were placed, like ButtonScreen
    @ComponentGroup("CheckboxChecked", index = 2, packageMap = "$screenPackage.basicinput")
    const val BasicInput = "Basic input"

    //other groups
    //....
}

7. At the end, you should see the component example page you've created in the Gallery, ready for demonstration and testing.

8. Debugging components with scale mode if needed: If you need to debug your component with scale mode, you can test it in TestComponentScreen. Navigate to this test page in the Gallery app through Settings > Test Component.

Need Help?

If you have any questions or need assistance, feel free to open an issue or reach out to the maintainers. We’re here to help!

Thank you for considering contributing to Compose-Fluent-UI. We can’t wait to see what you’ll create!