Refactor react-uswds to export building blocks, too

[hannasage]

Hey! We use this library on the ReportStream project, and over time we've had to re-write our own versions of a lot of components, because of custom style needs, compositional needs, and most of all, the need for more complex or bespoke interfaces for components.

I compiled our learnings, identified ways to meet our needs with a library, and outlined a pattern specifically for designing unopinionated (yet, still compliant) libraries that adapt design systems like uswds. It's called Bricks and Components, and here's the excerpt from a README.md in a repo where I am toying around with my own version of a React uswds library:

---

Utility of Bricks and Components

It's bricks and components, not bricks or components!

Both components and bricks serve a purpose and have utility, but with each, there are limitations as well.

Components

Consider the following implementation of an Alert:

return (
  <div className={`usa-alert ${props.className}`}>
    <div className="usa-alert__body">
      {heading && <h4 className="usa-alert__heading">{heading}</h4>}
      {children && <div>{children}</div>}
    </div>
  </div>
)

In the above exported component, the main restriction is that custom classes can only exist at the parent div level. This means, because this code is from an installed package, you as the engineer using the package will have to sleuth through source code to discover these limitations and create workarounds. A workaround for something like this, aside from submitting an issue and hoping for the best, might look like:

.usa-alert {
  div {
    ...
  }
}

The above CSS serves a single use, which means any custom styling overrides needed result in larger css files than we'd like.

However, not every team is writing css, not every team needs custom styles, but all teams require brevity. A component's main utility is providing clean interfaces for quickly configuring pieces of your UI without the need to worry about dom structure or styling, and that has always been the most invaluable utility of componentized front-ends! A component library should always export a full component interface with the default implementation, as many design systems consider these implementations in a "suits most cases" kind of way.

Though some standards exist inside rigid bounds, others can and should always be flexed when a stress case is presented.

Bricks

Now consider this implementation of an Alert:

// Second level of the Alert ecosystem; wraps children with props-based styling.
// Required use when building with bricks
export const USAlertBody = ({ children, className }: StylesAndChildren) => {
  return <div className={`usa-alert__body ${className}`}>{children}</div>;
};

// Heading brick
// Use to add a heading to your alert
export const USAlertHeading = ({ className, text }: USAlertHeadingProps) => {
  return <h4 className={`usa-alert__heading ${className}`}>{text}</h4>;
};

// Content brick
// Use to add content to your alert
export const USAlertContent = ({ children, className }: USAlertTextProps) => {
  return <p className={`usa-alert__text ${className}`}>{children}</p>;
};
export const USAlert = ({
  heading,
  content,
  wrapperClasses,
  bodyClasses,
  headingClasses,
  textClasses,
}: USAlertProps) => {
  return (
    <USAlertWrapper className={wrapperClasses}>
      <USAlertBody className={bodyClasses}>
        {heading && <USAlertHeading className={headingClasses} text={heading} />}
        {content && <USAlertContent className={textClasses}>{content}</USAlertContent>}
      </USAlertBody>
    </USAlertWrapper>
  );
}

Aside from the obvious difference in naming and props piping styles to every level, it's pretty much the same thing, right? Yes! This is why it's important to remember that it's bricks and components, not bricks or components. Bricks are just the elemental pieces of a component. Now, that said, here's where this pattern's utility really is: this package not only includes standard components, but also exports each brick so that you aren't beholden to the above dom structure, and your css can be written as reusable classes rather than a single-use block.

In short, opening clients up, not only to the components, but to the bricks as well, makes your component packages much less opinionated and way more flexible.

---

In writing this, and the demo code to see if this pattern made any sense in practice, I got to digging through this repository to try and invalidate my thoughts and feelings - counter my hypothesis, so to speak - and came to a conclusion that there's really no need to spin my own open-source solution until I've verified that this package wouldn't see this as a potential enhancement. You have the foundations already in place, and from what I've learned while writing the sample code is that it's super easy to refactor something like this library to utilize the Bricks and Components pattern.

That said-

I bring this to discussion with two main goals:

1. Get thoughts and opinions on adoption of this pattern within react-uswds as it's already serving clients in GovTech. Let's see if this makes sense for more than just ReportStream.
2. Gather any and all experiential knowledge that you have from maintenance of this package that might inform a better, or refined, pattern.

[hannasage]

Revisiting this discussion, with a more real-world case for exporting something like the PaginationButton.