RFC: how should we structure our monorepo and packages

[levithomason]

We will move to a monorepo and publish packages for state, styling, and accessibility at the least. We also have utilities such as our factories, which may be part of a "core" package. What packages do we foresee and what modules should be included in them?

---

This list is updated per the discussion below:

• @stardust-ui/prop-types

  • use: /lib/customPropTypes.tsx
  • Move to /packages
  • Reconcile Stardust changes with SUIR
  • Write README.md
  • Publish

• @stardust-ui/auto-controlled-component

  • use: /lib/AutoControlledComponent.tsx
  • Move to /packages
  • Reconcile Stardust changes with SUIR
  • Write README.md
  • Publish

[layershifter]

custom-proptypes

I think that we should move them to a separate package, will allow us to drop this package for production builds at all.

auto-controlled-component

AutoControlledComponent is also used in SUI, this will allow us to start code-sharing. It also self-sufficient component.

event-stack

I have already rewritten EventStack to TS and it's a separate package, it also has a nice React component that makes life easier and less complex code (see changes in Semantic-Org/Semantic-UI-React#2990). We can simply adopt it there, however I should note that it has own build and test system (browser based testing with Mocha in IE 11, Chrome & Firefox). I'm not that it fits monorepo ideas. May be, we can move it just to the org.

https://github.com/layershifter/event-stack

props-utils

Not sure about this, but... getUnhandledProps(), partitionHTMLProps() and getElementType() can be used and are used outside SUIR and Stardust.

[bmdalex]

Slot and createSlotFactory

We are using these to create component slots (content, icon, label are just a few examples) and we might want to export them from the monorepo since they have the behavior of a factory of (sub)components;

we might want to move these to src/lib/ side of the object (currently the are in src/components/Slot.tsx)

[levithomason]

It seems that we might want to separate the React packages from the vanilla/core packages as well.

Slot / createSlotFactory, agree that we should publish something like this. I think we need to iterate that again before doing so though. Example issue, we call it "slot" but then we use it as the root wrapper element in the Input. Really, this is just a "generic stardust element factory".

[layershifter]

Example issue, we call it "slot" but then we use it as the root wrapper element in the Input. Really, this is just a "generic stardust element factory".

Guys from Segment (https://github.com/segmentio/evergreen) have a similar primitive, they call it Box: https://github.com/segmentio/ui-box

[brianespinosa]

It might also make sense to have UIComponent as a package (and an available export from Stardust). That way people can use it to extend and create their own components if there is something not available in Stardust. Unless @levithomason you have other thoughts about how people should be leveraging the Stardust provider for styling other components in concert with those coming from Stardust.

[layershifter]

keyboard-key

https://www.npmjs.com/package/keyboard-key

What about this package? May be we should rewrite it to TS and adopt it, too?

[levithomason]

I was just talking this through with @davezuko as well. We're thinking we need to be careful to not over burden ourselves with package granularity. At the same time, we should consider how to divide packages on the most intuitive axis, like React vs core (vanilla) packages.

Here's what we're proposing:

• Organize the src directory first, before packaging anything
• Publish first a React package and a Core package
• Separate our lib utils according to React and vanilla usage
• Add a README.md for each lib util

Repo Structure

Each top-level directory represents a domain of concern. Each domain has a /lib for domain specific utilities.

/specifications     Language agnostic UI specifications
    /lib            private code
    /components 

/state              Vanilla JS state managers
    /lib
    /components

/style              Vanilla JS styling APIs (no components)
    /lib

/accessibility      Vanilla JS accessibility abstractions
    /lib
    /components

/react              Exemplar React implementation of Stardust UI
    /lib
    /components

/themes             First-class supported themes (CSS-in-JS and stylesheets)
    /lib
    /theme-name 

Package API

We would target this sort of package API surface:

@stardust-ui/core     For framework and component developers
 - state
 - style
 - accessibility

@stardust-ui/react
  - components

@stardust-ui/themes
  - default
  - teams (for now)

Given the target packages, do we want to organize vanilla JS state/style/accessibility solutions under a /core directory instead?

[brianespinosa]

I think the process you have outlined is a good way to go.

Given the target packages, do we want to organize vanilla JS state/style/accessibility solutions under a /core directory instead?

Yes to this ⏫

Organize the src directory first, before packaging anything

Definitely do this first. I found in our application architecture at Espressive that the work getting everything moved to packages and updating dependencies there was a significant amount of work. And in the process we discovered some things made sense to bundle into packages together. We also discovered having TOO many packages can actually start to slow down install performance (especially in Jenkins), though yarn has improved that in recent releases.

Since it looks like we intend to publish core/react/themes to NPM, are we looking to utilize Lerna to help with that process? If there are only a few packages like this that will be published we might actually be able to get away with some more lightweight tooling for that.

[layershifter]

@levithomason I will suggest to add @stardust/docs for our reusable utils and components for docs.