Consolidating Props

[seancdavis]

One question and one issue have popped up on recent projects that have led to this proposal:

Question: How do we define pass-through props? Do we define their shape(s), or do we leave them simply as objects/arrays, and pass them through?

Issue: Regardless of the answer to that question, it's unlikely that we're going to define the entire shape of a template. And yet, there's some value in being able to see that shape.

Better Defining Props

When it comes to answering the question, I believe we should follow a pattern like so: Components (React components, i.e. including templates) are responsible for defining the shape(s) of the prop(s) they render to the screen, while pass-through props can be defined generically.

Now, say we implement and tend to follow that rule. That still doesn't solve the issue. In fact, it almost makes the issue more severe, as the props defined at the template level would seem fairly obscure and perhaps without the necessary context.

The path of least resistance here would be to do something like this ... Say I have a <Card /> component that uses a <Button /> component. I could do this:

import Button from "@src/components/button"

// ...

Card.propTypes = {
  button: Button.propTypes
}

The downside to this is that the component's job is to concern itself only with the rendering process, while transforming data is delegated to the component's controller (index.js). In this example, when the card is used, it will should be sent transformed data, assuming it was accessed from the controller. The problem is that the button isn't going to be transformed until it is used within the card.

One way to get around this would be to transform further upstream. That seems like we could run into a hairy mess.

Rendering Defined Props

The last thing I'll add here is that ideally we'd be able to take the props definitions and render them somewhere, just as Storybook does. I know it can be done (because Storybook does it), but not exactly sure how.

Next Steps

So ... all that said, my proposal is:

1. Make no immediate code changes.
2. Let's discuss the feasibility and reliability of various approaches to better defining props.
3. Research how we can surface prop definitions at runtime.

[dholloran-ample]

Some thoughts not sure if this is more complicated or if any of this is really possible.

Shared Props

1. Separate the Component.propTypes into a prop-types.js file (name could be tweaked)
   • Some pros
     1. It can be imported into other files such as templates
   • Some Cons
     1. A separate file means you can not see the props in component.js to easily know what all the props are when you open a file but it could be better surfaced from automated tools
     2. I believe Docz had issues with some of the PropTypes definitions outside of being added directly to the component so other tools may have issues as well
   • The structure could be something as follows.

   // component/index.js
   import component from './component'
   import {propTypes, defaultProps} from './prop-types'
   export default component
   export { component, props }
   
   // component/component.js
   import props from '@components/component/props' // @components - Webpack alias to src/components
   const Component = ({prop1, prop2, prop3}) => {}
   Component.propTypes = propTypes
   // Alternative, may be more verbose/more work but could be helpful long term
   // Component.propTypes = {
   //   prop1: propTypes.prop1,
   //   prop2: propTypes.prop2,
   //   prop3: propTypes.prop3,
   // };
   Component.defaultProps = defaultProps // This could be replicated in any number of components as needed
   // Could use the more verbose formatting like propTypes as well
   export default Component
   
   // prop-types.js
   import PropTypes from "prop-types";
   export default {
     propTypes: {
       prop1: PropTypes.string,
       prop2: PropTypes.object,
       prop3: PropTypes.bool,
     },
     defaultProps: {
       prop1: 'Something',
     }
   };

2. Alternative to the prop-types.js solution we could create custom PropTypes that are basically the shape of the component (Docs)

Personally, if neither (I almost like 2 more) above are not possible then I would be in the camp of letting the component handle the prop definitions and error handling then everything above would be a primitive object. I don't want to get in a situation where the PropType definition is maintained in 5 different places all with varying levels of compliance.

Transforming Data

Having a global transformer that loads each component transformer. Possibly use the __typename or something else in GraphQL to match the transformer. Then at the highest possible point, the data is transformed so it's always in the format that is needed when coming out of the CMS. This is an ideal state for me so the transformations all happen in one place but not really sure if it's possible. Also may not be worth the effort since it would need to be recursive since a container could have a type of component and a container could have another component that has the same type of component.

[seancdavis]

After sitting with this a bit, I like where you're going. The consolidation of data and content structure makes sense to me.

Today we have a schema.yml file, which serves as the basis for explicitly defining GraphQL types so we can safely run queries. It also dynamically builds mappings for us.

Prop types feel related, even though they aren't exactly. Still, being able to see the shape of the entire application from one space does have some benefits — including being able to surface these in the playgrounds, and being able to reuse groups of validation rules.

I also agree that if we can transform at the top level, that would be ideal. I think the first iteration of that is going to have to be fairly opinionated. We'll have to consider how this would work with data coming in from both Contentful and Forestry, along with how other CMSes may behave.

There are a significant number of questions and hurdles involved here. I'm thinking the best path forward is for me to take a whack at it and discuss once I have an example of a working DSL for both prop types and transformers.

[seancdavis]

Considering this to be an exploration. Will reopen for comments after I've had some time to tinker.