Skip to contents

Contributing to muiMaterial

Source: CONTRIBUTING.md

Thanks for your interest in improving muiMaterial! This document covers the most common ways to contribute.

Reporting bugs and requesting features

Please open an issue on GitHub. For bugs, include a minimal reproducible example (a small shinyApp(...) block is ideal), the output of sessionInfo(), and the package versions of muiMaterial, shiny and shiny.react.

Development setup

# fork the repo, then:
git clone https://github.com/<your-user>/muiMaterial
cd muiMaterial

The R side has no compile step. Install dev dependencies in R and build the package:

install.packages(c("devtools", "roxygen2", "testthat", "checkmate"))
devtools::install_deps(dependencies = TRUE)
devtools::document()
devtools::test()
devtools::check()

Rebuilding the bundled JavaScript

The minified bundle shipped in inst/www/muiMaterial/ is produced from sources in js/. To rebuild it:

# Install the JavaScript dependencies
yarn --cwd js

# Bundle the JavaScript code into a single file
yarn --cwd js build

# Generate the NAMESPACE file and documentation
Rscript -e 'devtools::document()'

# Install the package
Rscript -e 'devtools::install()'

The build output is written directly into inst/www/muiMaterial/. The webpack pipeline pins exact MUI versions (js/package.json) and emits third-party license attributions to inst/www/muiMaterial/mui-material.js.LICENSE.txt via license-webpack-plugin. Please commit both files together so the licence file stays in sync with the bundle.

Adding a new component wrapper

muiMaterial mirrors the upstream MUI API by design. To add a new component:

  1. Add a <Name> <- component('<Name>') entry to R/components.R (use module = '@mui/lab' for lab components), and a matching roxygen doc block in R/documentation.R.
  2. If the component is meant to be Shiny-wired, add a <Component>.shinyInput() and update<Component>.shinyInput() pair to R/inputs.R.
  3. Add a tests/testthat/test-<Name>.R test, and confirm the name is actually exported by the bundled MUI version (a wrapper pointing at a non-existent export renders to an “Element type is invalid” error).
  4. Run devtools::document() and devtools::test().

Naming convention

  • Component() — plain MUI React element, PascalCase.
  • Component.shinyInput() / updateComponent.shinyInput() — Shiny-wired variants that expose input[[inputId]].
  • Component.triggerId() — overlay components bound to an existing DOM element by id, with no server logic required.

See ?muiMaterial for the full rationale.

Style

  • Follow the existing code style; the project uses base R conventions plus checkmate for argument validation.
  • New exported functions need roxygen documentation and at least one test, ideally with a runnable @examplesIf interactive() block.

Pull requests

  • One logical change per PR.
  • Update NEWS.md under the unreleased section at the top of the file.
  • Make sure devtools::check() is clean (0 errors, 0 warnings, at most the expected installed-size NOTE).

By contributing you agree that your contributions will be licensed under the MIT License of this project.