diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fe2a3247c..20b3671ade 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - Fix the behaviour of `AutoControlledComponent` when `undefined` is passed as a prop value @layershifter ([#499](https://github.com/stardust-ui/react/pull/499)) - Stop event propagation when press Escape on the popup @sophieH29 ([#515](https://github.com/stardust-ui/react/pull/515)) +### Documentation +- Add `Integrate Custom Components` guide page in the docs @mnajdova ([#517](https://github.com/stardust-ui/react/pull/517)) + ## [v0.12.0](https://github.com/stardust-ui/react/tree/v0.12.0) (2018-11-19) [Compare changes](https://github.com/stardust-ui/react/compare/v0.11.0...v0.12.0) diff --git a/docs/src/components/Sidebar/Sidebar.tsx b/docs/src/components/Sidebar/Sidebar.tsx index 50a331b84e..0c2c3e957f 100644 --- a/docs/src/components/Sidebar/Sidebar.tsx +++ b/docs/src/components/Sidebar/Sidebar.tsx @@ -245,6 +245,14 @@ class Sidebar extends React.Component { Theming Examples + + Integrate Custom Components + {process.env.NODE_ENV !== 'production' && ( diff --git a/docs/src/routes.tsx b/docs/src/routes.tsx index 9d0fa849e3..9a94a8ee65 100644 --- a/docs/src/routes.tsx +++ b/docs/src/routes.tsx @@ -12,6 +12,7 @@ import PageNotFound from './views/PageNotFound' import QuickStart from './views/QuickStart' import Theming from './views/Theming' import ThemingExamples from './views/ThemingExamples' +import IntegrateCustomComponents from './views/IntegrateCustomComponents' const Router = () => ( @@ -62,6 +63,11 @@ const Router = () => ( + diff --git a/docs/src/views/IntegrateCustomComponents.tsx b/docs/src/views/IntegrateCustomComponents.tsx new file mode 100644 index 0000000000..e65bdd7803 --- /dev/null +++ b/docs/src/views/IntegrateCustomComponents.tsx @@ -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 = createComponent({ + displayName: 'StyledButton', + render({ stardust, className, children }) { + const { classes } = stardust + return + }, +}) + +export default () => ( + +
+

+ 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{' '} + createComponent function, provided by the Stardust library. +

+
+

+ Let's take a look into one simple example of using the createComponent function + for adapting your custom component to the Stardust's styling and theming mechanisms. +

+ {`, + ` const { classes } = stardust`, + ` return `, + ` }`, + `})`, + ].join('\n')} + /> +

+ Let's go step by step throughout all bits of the createComponent method. +

+

+ The first argument to the createComponent config's param is the is the{' '} + displayName, 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. +

+ ({`, + ` backgroundColor: siteVariables.brand,`, + ` color: variables.color,`, + ` }),`, + ` },`, + ` },`, + ` }}`, + `>`, + ` Provider styled button `, + '', + ].join('\n')} + render={() => ( + ({ + backgroundColor: siteVariables.brand, + color: (variables as any).color, + }), + }, + }, + }} + > + Provider styled button + + )} + /> +

+ The second argument of the createComponent config param is the{' '} + render 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 render method + will be invoked with the following parameters: +

+
    +
  • + stardust - the object containing the evaluated theming props ( + classes + + and rtl). +
    • +
  • + ...props - all user props. +
    • +
+
+

+ We already saw how the Provider 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. +

+
+ Example 1. Using styles property + + } + /> + `, + ` Inline styled button`, + ``, + ].join('\n')} + render={() => ( + + Inline styled button + + )} + /> + The same can be achieved with adding styles in the componentStyles part of the{' '} + theme in the Provider. + ({`, + ` ':hover': {`, + ` backgroundColor: "yellow"`, + ` }`, + ` }),`, + ` },`, + ` },`, + ` }}`, + `>`, + ` Inline styled button`, + '', + ].join('\n')} + /> +

+ For more advanced theming scenarios, please take a look in the Styles section on the{' '} + Theming guide. +

+
+ Example 2. Using variables property + + } + /> + Let's consider that the following theme was passed to the Provider. + ({`, + ` color: variables.color,`, + ` }),`, + ` },`, + ` },`, + ` }}`, + `>`, + ` ...`, + '', + ].join('\n')} + /> + Then we can use the variables prop for changing the color inside the{' '} + StyledButton. + `, + ` Inline styled button`, + ``, + ].join('\n')} + render={() => ( + ({ + color: (variables as any).color, + }), + }, + }, + }} + > + Inline styled button + + )} + /> + The alternative approach with defining componentVariables inside the{' '} + theme would like like this: + ({`, + ` color: variables.color,`, + ` }),`, + ` },`, + ` },`, + ` }}`, + `>`, + ` ...`, + '', + ].join('\n')} + /> +

+ For more advanced theming scenarios, please take a look in the Variables section on the{' '} + Theming guide. +

+
+ +
+