This repository was archived by the owner on Mar 4, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 51
docs(custom-components): adding initial guide for creating custom components #517
Merged
Merged
Changes from all commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
61828a4
-added custom components guide in the docs
6874613
-updated changelog
7e0d276
-replaced renderComponent with createComponent
c7647d4
-replaced renderComponent with createComponent
02702da
-simplified StyledButton example code
b06fc4f
-addressed comments from PR
08af6fd
-addressed PR comments
788baf8
-addressed final PR comments
603e424
-updated changelog
5f01ec8
-adding descriptive comments for the displayName in the Provider's ex…
738e616
Merge branch 'master' into docs/custom-components
688a80d
-small lexical change
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,274 @@ | ||
| import * as React from 'react' | ||
| import * as cx from 'classnames' | ||
| import { NavLink } from 'react-router-dom' | ||
| import { Header } from 'semantic-ui-react' | ||
| import { | ||
| Button, | ||
| Divider, | ||
| Provider, | ||
| createComponent, | ||
| ComponentSlotStyle, | ||
| ComponentVariablesInput, | ||
| } from '@stardust-ui/react' | ||
|
|
||
| import DocPage from '../components/DocPage/DocPage' | ||
| import ExampleSnippet from '../components/ExampleSnippet/ExampleSnippet' | ||
| import { ReactChildren } from '../../../types/utils' | ||
|
|
||
| interface StyledButtonProps { | ||
| className?: string | ||
| styles?: ComponentSlotStyle | ||
| variables?: ComponentVariablesInput | ||
| children?: ReactChildren | ||
| } | ||
|
|
||
| const StyledButton: React.SFC<StyledButtonProps> = createComponent<StyledButtonProps>({ | ||
| displayName: 'StyledButton', | ||
| render({ stardust, className, children }) { | ||
| const { classes } = stardust | ||
| return <button className={cx(className, classes.root)}>{children}</button> | ||
| }, | ||
| }) | ||
|
|
||
| export default () => ( | ||
| <DocPage title="Integrate Custom Components"> | ||
| <Header as="h2" content="Overview" /> | ||
| <p> | ||
| You can use your own components as part of the Stardust's styling and theming mechanisms. In | ||
| order for all theming aspects to be available to your custom components, you should use the{' '} | ||
| <code>createComponent</code> function, provided by the Stardust library. | ||
| </p> | ||
| <Header as="h2" content="Create custom component" /> | ||
| <p> | ||
| Let's take a look into one simple example of using the <code>createComponent</code> function | ||
| for adapting your custom component to the Stardust's styling and theming mechanisms. | ||
| </p> | ||
| <ExampleSnippet | ||
| value={[ | ||
| `import { createComponent } from '@stardust-ui/react'`, | ||
| ``, | ||
| `const StyledButton = createComponent({`, | ||
| ` displayName: 'StyledButton',`, | ||
| ` render: ({stardust, className, children}) => {`, | ||
| ` const { classes } = stardust`, | ||
| ` return <button className={cx(className, classes.root)}>{children}</button>`, | ||
| ` }`, | ||
| `})`, | ||
| ].join('\n')} | ||
| /> | ||
| <p> | ||
| Let's go step by step throughout all bits of the <code>createComponent</code> method. | ||
| </p> | ||
| <p> | ||
| The first argument to the <code>createComponent</code> config's param is the is the{' '} | ||
| <code>displayName</code>, which value might be used as key to define component's styles and | ||
| variables in theme, exactly the same way how it might be done for any first-class Stardust | ||
| component. | ||
| </p> | ||
| <ExampleSnippet | ||
| value={[ | ||
| `<Provider`, | ||
| ` theme={{`, | ||
| ` componentVariables: {`, | ||
| ` StyledButton: {`, | ||
| ` color: '#F2F2F2',`, | ||
| ` },`, | ||
| ` },`, | ||
| ` componentStyles: {`, | ||
| ` StyledButton: {`, | ||
| ` root: ({ props, variables, theme: {siteVariables} }) => ({`, | ||
| ` backgroundColor: siteVariables.brand,`, | ||
| ` color: variables.color,`, | ||
| ` }),`, | ||
| ` },`, | ||
| ` },`, | ||
| ` }}`, | ||
| `>`, | ||
| ` <StyledButton> Provider styled button </StyledButton>`, | ||
| '</Provider>', | ||
| ].join('\n')} | ||
| render={() => ( | ||
| <Provider | ||
| theme={{ | ||
| componentVariables: { | ||
| StyledButton: { | ||
| color: '#F2F2F2', | ||
| }, | ||
| }, | ||
| componentStyles: { | ||
| StyledButton: { | ||
| root: ({ props, variables, theme: { siteVariables } }) => ({ | ||
| backgroundColor: siteVariables.brand, | ||
| color: (variables as any).color, | ||
| }), | ||
| }, | ||
| }, | ||
| }} | ||
| > | ||
| <StyledButton>Provider styled button</StyledButton> | ||
| </Provider> | ||
| )} | ||
| /> | ||
| <p> | ||
| The second argument of the <code>createComponent</code> config param is the{' '} | ||
| <code>render</code> method. This is the place where where you might link Stardust bits with | ||
| your custom component - e.g. by simply passing them as props. This <code>render</code> method | ||
| will be invoked with the following parameters: | ||
| </p> | ||
| <ul> | ||
| <li> | ||
| <code>stardust</code> - the object containing the evaluated theming props (<code> | ||
| classes | ||
| </code> | ||
| and <code>rtl</code>). | ||
| </li> | ||
| <li> | ||
| <code>...props</code> - all <code>user props</code>. | ||
| </li> | ||
| </ul> | ||
| <Header as="h2" content="Using the custom components" /> | ||
| <p> | ||
| We already saw how the <code>Provider</code> can define some stylings and variables for the | ||
| custom components. Next, we will take a look into several examples of how the user can further | ||
| customize styles and variables of these components, the same way they would do with the | ||
| Stardust components. | ||
| </p> | ||
| <Header | ||
| as="h3" | ||
| content={ | ||
| <> | ||
| Example 1. Using <code>styles</code> property | ||
| </> | ||
| } | ||
| /> | ||
| <ExampleSnippet | ||
| value={[ | ||
| `<StyledButton styles={{':hover': {backgroundColor: "yellow"}}>`, | ||
| ` Inline styled button`, | ||
| `</StyledButton>`, | ||
| ].join('\n')} | ||
| render={() => ( | ||
| <StyledButton styles={{ ':hover': { backgroundColor: 'yellow' } }}> | ||
| Inline styled button | ||
| </StyledButton> | ||
| )} | ||
| /> | ||
| The same can be achieved with adding styles in the <code>componentStyles</code> part of the{' '} | ||
| <code>theme</code> in the <code>Provider</code>. | ||
| <ExampleSnippet | ||
| value={[ | ||
| `<Provider`, | ||
| ` theme={{`, | ||
| ` // component's displayName arg is used as a selector`, | ||
| ` componentStyles: {`, | ||
| ` StyledButton: {`, | ||
| ` root: () => ({`, | ||
| ` ':hover': {`, | ||
| ` backgroundColor: "yellow"`, | ||
| ` }`, | ||
| ` }),`, | ||
| ` },`, | ||
| ` },`, | ||
| ` }}`, | ||
| `>`, | ||
| ` <StyledButton>Inline styled button</StyledButton>`, | ||
| '</Provider>', | ||
| ].join('\n')} | ||
| /> | ||
| <p> | ||
| For more advanced theming scenarios, please take a look in the <b>Styles</b> section on the{' '} | ||
| <NavLink to="theming">Theming guide</NavLink>. | ||
| </p> | ||
| <Header | ||
| as="h3" | ||
| content={ | ||
| <> | ||
| Example 2. Using <code>variables</code> property | ||
| </> | ||
| } | ||
| /> | ||
| Let's consider that the following <code>theme</code> was passed to the <code>Provider</code>. | ||
| <ExampleSnippet | ||
| value={[ | ||
| `<Provider`, | ||
| ` theme={{`, | ||
| ` // other theme parts`, | ||
| ` componentStyles: {`, | ||
| ` StyledButton: {`, | ||
| ` root: ({ variables }) => ({`, | ||
| ` color: variables.color,`, | ||
| ` }),`, | ||
| ` },`, | ||
| ` },`, | ||
| ` }}`, | ||
| `>`, | ||
| ` ...`, | ||
| '</Provider>', | ||
| ].join('\n')} | ||
| /> | ||
| Then we can use the <code>variables</code> prop for changing the color inside the{' '} | ||
| <code>StyledButton</code>. | ||
| <ExampleSnippet | ||
| value={[ | ||
| `<StyledButton variables={{color: "red" }}>`, | ||
| ` Inline styled button`, | ||
| `</StyledButton>`, | ||
| ].join('\n')} | ||
| render={() => ( | ||
| <Provider | ||
| theme={{ | ||
| componentStyles: { | ||
| StyledButton: { | ||
| root: ({ variables }) => ({ | ||
| color: (variables as any).color, | ||
| }), | ||
| }, | ||
| }, | ||
| }} | ||
| > | ||
| <StyledButton variables={{ color: 'red' }}>Inline styled button</StyledButton> | ||
| </Provider> | ||
| )} | ||
| /> | ||
| The alternative approach with defining <code>componentVariables</code> inside the{' '} | ||
| <code>theme</code> would like like this: | ||
| <ExampleSnippet | ||
| value={[ | ||
| `<Provider`, | ||
| ` theme={{`, | ||
| ` // component's displayName arg is used as a selector`, | ||
| ` componentVariables: {`, | ||
| ` StyledButton: {`, | ||
| ` color: "red"`, | ||
| ` },`, | ||
| ` }`, | ||
| ` componentStyles: {`, | ||
| ` StyledButton: {`, | ||
| ` root: ({ variables }) => ({`, | ||
| ` color: variables.color,`, | ||
| ` }),`, | ||
| ` },`, | ||
| ` },`, | ||
| ` }}`, | ||
| `>`, | ||
| ` ...`, | ||
| '</Provider>', | ||
| ].join('\n')} | ||
| /> | ||
| <p> | ||
| For more advanced theming scenarios, please take a look in the <b>Variables</b> section on the{' '} | ||
| <NavLink to="theming">Theming guide</NavLink>. | ||
| </p> | ||
| <br /> | ||
| <Divider size={1} /> | ||
| <br /> | ||
| <Button | ||
| as={NavLink} | ||
| content="Theming Examples" | ||
| icon="arrow left" | ||
| iconPosition="before" | ||
| primary | ||
| to="/theming-examples" | ||
| /> | ||
| </DocPage> | ||
| ) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that we can use own
Headercomponent there 😃There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Switching the theme to dark will make the Header component white, and we don't have the other themes implemented for all page (like making the background dark in dark-mode). I would not like to introduce unnecessary providers just for handling things like that. In all docs pages, the Headers are from semantic-ui, so when the dark mode will be implemented for all page, we can safely replace them all in one iteration.