seapig
v2.4.2TypeScript
Utility for generalized composition of React components.
0/weekUpdated 1 years agoMITUnpacked: 27.7 KB
Published by Nemanja Stojanovic
npm install seapig
seapig 🌊🐷
Utility for generalized composition of React components
Sea pig stands for (Children Props Internal Getter), except the C is spelled phonetically.
Table of Contents
- What does Seapig do?
- Install
- Example
- Walkthrough
- API
- License
What does Seapig do?
> seapig. seapig. Does whatever a seapig does!
seapig is here to help you compose your React Components in a consistent and flexible manner. It provides a mechanism to organize components that form into a single idea without limiting the types of components you can use.
> “A way to give rendering back to the user”
seapig eliminates configuration in favor of composition.
It abstracts component composition for you, allowing you to decouple how components are combined from which components they are. It enables you to generalize (and optionally enforce) the structure and behavior of a group of components but leaves out any restrictions on which exact components you must use.
``jsx`
🌊🐷
Seapig
Would render something like (play with the example):
seapig shines the most when used to create components whose state is too complex to be held in a single component yet not global enough to be represented at the application level.
Using this pattern in React allows us to have the rendering control with the minimal api surface area without the need for configuration props for all state and data variations that our component can have.
This is where compound components come to the rescue.
A compound component encloses the state and behavior for a group of components but still gives the rendering control for its variable parts back to the external user. When using it, you only need to worry about the actual parts that are different.
A concrete example of a compound component on the Web today is the
> If you're interested in more examples of compound components, Ryan Florence has a great talk on this topic.
Good ol' seapig twists the concept of compound components a bit by using designated props to determine distinct parts of our component group, rather than enforcing usage of specific components. Furthermore, it can restrict a consistent shape of our structure by enforcing Rendering Order and Child Presence using a schema object.
Imagine if
Wouldn't this be cool?
`html`
$3
Components that use seapig render their children into special placeholders determined by the schema. This means that the rendering shape can be enforced internally, allowing us to pass the children into a seapig component in any order.
`jsxMyCoolSidebar
/ and Content are always rendered in the same order no matter what order they are passed in /
/ This one would render the same /
Hello seapig
!
/ as this one /
Hello seapig
!
/ Corresponding seapig component example /
import seapig, { OPTIONAL, REQUIRED } from 'seapig'
const Main = props => {
const {
sidebarChildren, // array of children with the sidebar propcontent
contentChildren // array of children with the prop
} = seapig(props.children, { // schema object
sidebar: OPTIONAL, // sidebar is optional
content: REQUIRED // content is required
})
// rendering order is always the same
return (
{sidebarChildren.length && }
)
}
`
$3
A
component ensures that all children match the provided schema.To reuse
from above as an example, if we didn't pass any children with the 'content' prop, seapig would throw:`jsx
// The code below would throw a "Must have at least 1 content element" error
`The
also accumulates any unidentified children into the rest array.`jsx
import seapig, { OPTIONAL, REQUIRED } from 'seapig'const Main = props => {
const {
sidebarChildren,
contentChildren,
rest, // all children not matching
sidebar and content are in this array
} = seapig(props.children, {
sidebar: OPTIONAL,
content: REQUIRED
}) return (
{sidebarChildren.length && }
{content}
{rest} {/ passing rest of the children /}
)
}/
rest would contain the bottom section /
Hello
seapig!
I would be in the rest array
`
In fact,
and REQUIRED, along with their plural counterparts OPTIONALS and REQUIREDS, are just helpful schema constants:`jsx
const OPTIONAL = { // can have one
min: 0,
max: 1
}
const OPTIONALS = { // can have any
min: 0
}
const REQUIRED = { // must have one
min: 1,
max: 1
}
const REQUIREDS = { // must have at least one
min: 1
}
` allows us to pass custom min and max, both inclusive, values as well:`jsx
import seapig from 'seapig'const Main = props => {
const {
buttonChildren
} = seapig(props.children, {
button: { // custom button schema values
min: 2,
max: 5
}
})
return (
I can have between 2 to 5 buttons
{buttonChildren}
)
}/ Now we must have between 2 and 5 buttons /
Second
Third
`Install
bash
npm install seapig --saveor
yarn add seapig
`Example
$3
jsx
import React, { Component } from 'react'
import seapig, { OPTIONAL, REQUIRED } from 'seapig'/ Button with a required label and an optional icon /
class Button extends Component {
render() {
const {
iconChildren,
labelChildren
} = seapig(this.props.children, {
icon: OPTIONAL,
label: REQUIRED
})
return (
)
}
}
/ usage of the seapig Button /
import React, { Component } from 'react'
import Button from './Button'
class Form extends Component {
render() {
return (
)
}
}
`Walkthrough
To demonstrate the problem that
solves, let's see how we can design the API of a header component.Let's say we came up with an initial idea that the header will show a brand image to the left and a menu right after it.
`jsx
const Header = () => (
- Home
- About
)
`Ok simple enough. Now let's consider a few potential updates we might need to make this component.
Let's imagine a requirement comes in that each page has to render a custom menu item that is unique to it, maybe some icon designated for that portion of our site that may or may not be an anchor as well.
Sure, not a problem, instead of us worrying about element types and icons for each page, let's just allow them to pass that in. Of course we don't want to render blank items if nothing is provided:
jsx
const Header = ({ PageIcon }) => (
- Home
- About
{PageIcon && - {PageIcon}
}
)
`Now let's use it:
jsx
{/ or /}
`Alright, things are getting a bit messy but still manageable.
Headers usually show user info, assuming the user is authenticated.
jsx
const Header = ({ PageIcon, authenticated }) => (
- Home
- About
{PageIcon && - {PageIcon}
}
{authenticated &&
)
`Feels somewhat clunky but not terrible.
jsx
authenticated={user.isLoggedIn && user.hasPermission}
/>
`Phew, done. A few days go by and users now start complaining about having to navigate to
to explore your site and want a search bar directly in the header. Ok, we can add another flag. Additionally there isn't a point to storing this search state within the header when other parts of the app will need it so let's take that into account as well.`jsx
const Header = ({ PageIcon, authenticated, showSearch, searchTerm, onSearch }) => (
- Home
- About
{PageIcon && - {PageIcon}
}
{authenticated &&
{showSearch && (
)}
)
`Did that mess things up?
jsx
authenticated={user.isLoggedIn && user.hasPermission}
showSearch
searchTerm={this.state.searchTerm}
onSearch={this.handleSearch}
/>
`You can see where this is going.
- What if we want the menu to sometimes be an
rather than an ul? Theoretically, this header could be used in multiple sites. Surely we'll need to figure out how to generalize the hardcoded menu item texts for each site. Maybe a string array of items?
- What if those other sites behave the same but will never need special icons?
- What if the is sometimes only a numeric search? Pass a prop?
- What if in the future we want other pages to customize the order of the internal components of , maybe show the input before the ul menu?This is where
seapig comes in.Let's look at how a
seapig Header API would look like in each of these case, we'll deal with implementation later.`jsx
- Home
- About
`That's it. We mark our
and ul as the brand and menu and this satisfies all the requirements of our header for this particular page.What about the custom icon per page? We can just render it on each page directly:
`jsx
- Home
- About
`Ok, what about auth data? Well we could just mark those as well. We also want to pass the
flag to the header so it knows which items to show or not depending on the authentication state.`jsx
- Home
- About
{/ Mark restricted menu items /}
`What about search?
jsx
- Home
- About
`Wanna disable the search input? Just do it.
jsx
- Home
- About
`What if the
is sometimes only a numeric search? We can update the type property.`jsx
- Home
- About
`What if the menu is an
? We can change the tag.`jsx
- Home
- About
`Change what the items say?
jsx
- 🏠
- ℹ️
`Any specific rendering change we need to make to one of its children doesn't need to affect the
component itself. seapig allows you to use whatever component you want.Once you determine a consistent set of logic for your site or groups of pages, you can wrap that logic into a specific
seapig header component and be done with it. Any future requirements to any other system that uses the header won't affect you and you won't affect them.So how does the actual implementation of
Header look like?`jsx
const Header = ({ children, authenticated }) => {
const {
brandChildren,
menuChildren,
authChildren
searchChildren,
} = seapig(children, {
brand: REQUIRED,
menu: REQUIRED,
auth: OPTIONAL
search: OPTIONAL,
}); return (
{brandChildren}
{menuChildren}
{authenticated && authChildren}
{searchChildren}
)
}
`For a more advanced use case,
works great with React.cloneElement.Let's say we want to have all
auth children add a class 'authenticated-item' when present in the header.`jsx
const Header = ({ children, authenticated }) => {
const {
brandChildren,
menuChildren,
authChildren
searchChildren,
} = seapig(children, {
brand: REQUIRED,
menu: REQUIRED,
auth: OPTIONAL
search: OPTIONAL,
}); return (
{brandChildren}
{menuChildren}
{authenticated && authChildren.map(
child => React.cloneElement(child, {
className:
${child.props.className} authenticated-item
})
)}
{searchChildren}
)
}
`
API
jsx
const {
iconChildren,
iconsChildren,
labelChildren,
labelsChildren,
imageChildren,
rest, // array of children not matching any of the schema props
} = seapig(children, {
icon: OPTIONAL, // use OPTIONAL to specify only one optional child prop
icons: OPTIONALS, // use OPTIONALS to specify any amount of optional child props
label: REQUIRED, // use REQUIRED to specify only one required child prop,
labels: REQUIREDS, // use REQUIREDS to specify at least one required child prop,
image: { // pass an object with min and/or max
min: 1, // default is if only max is specified
max: 2 // default is Infinity if only min is specified
}
})
``License
MIT