bimberlab / discvr-components Goto Github PK

We should research packages to help us develop and test React components in a vacuum prior to integrating them with our LabKey modules. The workflow I'm aware of is the following:

• Storybook allows us to develop standalone React components and test their behavior prior to publishing them as a module
• Jest for unit/integration testing
• eslint with typescript-eslint for linting our typescript code

Evaluate that workflow and those packages, and see if there are newer or more fully-featured alternatives.

Research:

• Familiarize oneself with how to manage an npm monorepo, and packages for repo management
• Research best practices for maintaining/developing npm packages. Are we missing key things from this list?
• Research testing frameworks. We do not have very specialized or niche needs. Something that is widely used, documented, maintained, and robust is ideal. Jest is my default here. It should ideally offer unit-like testing.
• Research frameworks that would allow the developer to actually build and run specific components in the browser in a code-sandbox type of thing. The use-case here would be to provide a minimal, fast, environment for the developer to build something like an extension to a MUI grid, build some kind of form element, etc. Ideally, this framework would allow one to easily create test cases that sync with the development.
• Evaluate code tools like eslint, and determine if there is a newer compelling alternative to eslint.
• Research options to publish npm packages. The code will all be public/open source. The primary criteria is reliability, ease of use, and ability to integrate with github actions.
• Determine best practices for developing on multiple packages at the same time, and coordinating changes/version updates. Document this in a wki or similar in this project.

Implementation:

• Create structure to handle multiple npm packages within this repo
• Establish branch protection, and integration of code standards into PRs.
• Create a basic README that outlines each npm package, dev practices, and deployment practices
• Create test stubs using github actions
• Create structure to publish the packages using github packages or another mechanism
• Consider making a nightly 'latest' release, auto-generated each day.
• Implement eslint or similar across the project
• Implement basic scaffold for a discvr-utils package

We anticipate to begin with these packages:

• discvr-utils: this should hold very generic code, like helper functions, ideally with minimal dependencies.
• discvr-ui-components: Holds standalone UI components that are not too tightly linked to a specific project. This can depend on MUI. One example might be components that extend a MUI select or enhancements to the MUI grid.
• discvr-jbrowse: we should consider migrating some of the code from the existing discvrlabkeymodules/jbrowse LK module into here.

We may eventually also want project-specific repos, such as mgap or mcc.

We need a solution for publishing/hosting NPM packages, with a focus on reliability, ease of use, and integration with GitHub Actions. We should be able to use an Action to run our testing/linting setup on every commit to any branch, and on a commit to main publish a package to our package repository of choice. I'm aware of two options:

• NPM
• GitHub Package Registry

Per the GitHub docs, I think the expected workflow is an Action that publishes to NPM, but we need to do more research on if that's a good solution. In particular, determining how to do semantic versioning properly and documenting the process in the Wiki will be important.

We have a page that displays data in a table format. You can filter the table using a field + operator + value UI, and you can have multiple filters. An example of a filter for "Allele Frequency > 0.2":

The rendered JSX for the Value input changes depending on the type of Field you're filtering on. In the vast majority of cases, it's just a simple MUI TextField, like the "Allele Frequency" case. However, for fields with a defined set of possible values, like "Samples With Variant" it'll render a Select:

If there are a lot of possible values, we render a more complex component -- an AsyncSelect from react-select:

The exact specifics vary depending on the Field and Operator. Our goal is to extract these various cases into a component with a clean interface and put it in discvr-components, as an example use-case for our monorepo.

The file containing the filter form is here. The lines that control the Value portion of the form are highlighted. In short:

• We special case the operator "in set", which renders a select field with some special values in it
• If the number of selectable values > 10, we render the complex AsyncSelect
• Otherwise, if the number of selectable values > 0, we render a simple Select
• If there are no selectable values (i.e. we're just accepting any user input) we render a TextField

As you can see, there's a bit of logic behind how we determine which version of the Value input to render. This logic is based on a bunch of external data, i.e. the current filter, the fieldTypeInfo object, and others. In order to refactor this out into a separate component, we need to identify what values we'd need to pass into the component as props in order for all the logic to work. I think the prop list looks like:

• index, which refers to the position of this filter in the filter list
• filter, so that lines like filter.operator === "in set" can work
• fieldTypeInfo, for fieldTypeInfo.find(obj => obj.name === filter.field)?.allowableValues?.length > 10
• highlightedInputs, for the various highlightedInputs[index] calls
• handleFilterChange for all the onChange callbacks

So, we should produce something that looks like

const ValueComponent = ({ index, filter, fieldTypeInfo, highlightedInputs, handleFilterChange }) => {<a lot of JSX>}

such that we can delete the aforementioned lines of code and replace it with this new ValueComponent. We should identify how to test/build this as well.

We should research how to do NPM monorepo management. The library I'm aware of to automate this is Turborepo. Evaluate any other options in the space that can be easily deployed and incrementally adopted. A library of some kind is preferable to npm/yarn workspaces. If Turborepo is what we end up going with, you should familiarize yourself with it.

After determining which framework we want to use per #3, we should push the configuration/code for a monorepo management solution to a feature branch on this repo, with stubs for three packages named the following:

• discvr-utils
• discvr-ui-components
• discvr-jbrowse

These will be empty for now, but later on we'll determine what to pull out of our main repo and put in them.

In https://github.com/BimberLab/DiscvrLabKeyModules, we use React for page layout/behavior, and MUI v4 for styling. You should familiarize yourself with React, and briefly with some MUI concepts.

React's quickstart teaches you about components, JSX, and state management. We heavily use hooks for state management, so understanding them will be important. We mostly use functional components, which is React's default component format, but it's worth at least knowing about class components since you'll sometimes see those as well.

We use MUI components rather than default browser buttons, select boxes, etc. MUI also controls the layout of our webpages. In general MUI code should be reasonably readable without deep knowledge of the library, but it's worth skimming the getting started docs so you know how it works differently from normal CSS.

You should get familiarized with NPM basics, specifically creating an NPM package with a package.json. We've enumerated here and in other issues the basic workflow we're expecting to implement:

1. Open a feature branch in Git
2. Write code and push it to the monorepo
3. Automatically lint and test
4. Publish to a package repo when the developer merges to main

We should be able to answer the question: are we missing anything critical about maintaining or developing NPM packages?