Skip to content

Commit c2e5be0

Browse files
artyorsh32penkin
artyorsh
authored and
32penkin
committed
docs(theme): add theme components documentation (#387)
1 parent 664a823 commit c2e5be0

File tree

3 files changed

+205
-10
lines changed

3 files changed

+205
-10
lines changed

‎src/framework/theme/application/applicationProvider.component.tsx

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ import React from 'react';
88
import merge from 'lodash.merge';
99
import { SchemaProcessor } from '@eva/processor-kitten';
1010
import {
11-
ThemeStyleType,
12-
SchemaType,
1311
CustomSchemaType,
12+
SchemaType,
13+
ThemeStyleType,
1414
} from '@eva/core';
1515
import { StyleProvider } from '../style/styleProvider.component';
1616
import { ThemeProviderProps } from '../theme/themeProvider.component';
@@ -29,6 +29,52 @@ interface State {
2929
theme: ThemeType;
3030
}
3131

32+
/**
33+
* The `ApplicationProvider` component is designed to be a root of the application.
34+
*
35+
* This does basically two things:
36+
* - Provides styles for react-native-ui-kitten basic components (e.g `Button`);
37+
* - Renders modal window which is used to be common for all elements presented as modal;
38+
*
39+
* @extends React.Component
40+
*
41+
* @property {SchemaType} mapping - Determines the mapping for basic components.
42+
* This is designed to be provided by developers team and can be imported from npm package (e.g `@eva/eva`).
43+
*
44+
* @property {CustomSchemaType} customMapping - Determines the customization mapping.
45+
* This is merged with `mapping` property and designed to be used components customization.
46+
* Optional.
47+
*
48+
* @property {ThemeType} theme - Determines the theme for basic components.
49+
* This is designed to be provided by developers team and can be imported from npm package (e.v `@eva/theme-eva`).
50+
*
51+
* @property {React.ReactNode} children - Determines application root component.
52+
*
53+
* @property ThemeProviderProps
54+
*
55+
* @example ApplicationProvider API example
56+
*
57+
* ```
58+
* import { mapping } from '@eva/eva';
59+
* import { theme } from '@eva/theme-eva';
60+
* import { ApplicationProvider } from '@kitten/theme';
61+
* import { Application } from './path-to/root.component';
62+
*
63+
* export default class App extends React.Component {
64+
*
65+
* public render(): React.ReactNode {
66+
* return (
67+
* <ApplicationProvider
68+
* mapping={mapping}
69+
* theme={theme}>
70+
* <Application/>
71+
* </ApplicationProvider>
72+
* );
73+
* }
74+
* }
75+
* ```
76+
*/
77+
3278
export class ApplicationProvider extends React.Component<ApplicationProviderProps, State> {
3379

3480
private schemaProcessor: SchemaProcessor = new SchemaProcessor();

‎src/framework/theme/style/styleConsumer.component.tsx

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,97 @@ export interface ContextProps {
3838

3939
export type StyledComponentClass<P> = React.ComponentClass<StyledComponentProps & P>;
4040

41-
export const styled = <P, T = {}>(Component: React.ComponentClass<P>): StyledComponentClass<P> => {
41+
/**
42+
* The `styled` function is a High Order Function which is used to apply style `mapping`s on components.
43+
*
44+
* To be styled, source component class should have static `styledComponentName` property which defines
45+
* corresponding component name in `mapping`. (e.g 'Button' for `Button` class).
46+
*
47+
* Passes following props to `Component` when it is rendered:
48+
*
49+
* @property {string} appearance - Determines style appearance of component. Default is provided by mapping.
50+
* @property {ThemeType} theme - Determines theme used to style component.
51+
* @property {StyleType} themedStyle - Determines component style for it's current state.
52+
* @property {(interaction: Interaction[]) => void} - Determines function
53+
* for dispatching current state of component. This is designed to be used as style request function.
54+
* Calls component re-render if style for requested state differ from current.
55+
*
56+
* @param {React.ComponentClass} Component - Determines class of component to be styled.
57+
*
58+
* @example Declaring Styled Component
59+
*
60+
* ```
61+
* import {
62+
* styled,
63+
* StyledComponentProps,
64+
* Interaction,
65+
* } from '@kitten/theme';
66+
*
67+
* type StyledButtonProps = ButtonProps & StyledComponentProps;
68+
*
69+
* class Button extends React.Component<StyledButtonProps> {
70+
*
71+
* // Define component name used in `mapping`
72+
* static styledComponentName: string = 'Button';
73+
*
74+
* private onPressIn = (e: GestureResponderEvent) => {
75+
* // Request styles for `active` state and re-render
76+
*
77+
* this.props.dispatch([Interaction.ACTIVE]);
78+
*
79+
* if(this.props.onPressIn) {
80+
* this.props.onPressIn(e);
81+
* }
82+
* };
83+
*
84+
* private onPressOut = (e: GestureResponderEvent) => {
85+
* // Request styles for default state and re-render
86+
*
87+
* this.props.dispatch([]);
88+
*
89+
* if(this.props.onPressOut) {
90+
* this.props.onPressOut(e);
91+
* }
92+
* };
93+
*
94+
* public render(): React.ReactElement<ButtonProps> {
95+
* // Retrieve styles for current state from props (provided with themedStyle prop)
96+
* // And apply it with saving priority of `style` prop
97+
*
98+
* const { style, themedStyle, ...restProps } = this.props;
99+
*
100+
* return (
101+
* <TouchableOpacity
102+
* {...restProps}
103+
* style={[themedStyle, style]}
104+
* onPressIn={this.onPressIn}
105+
* onPressOut={this.onPressOut}
106+
* />
107+
* );
108+
* }
109+
* }
110+
*
111+
* export const StyledButton = styled<StyledButtonProps>(Button);
112+
* ```
113+
*
114+
* @example Styled Component Usage
115+
*
116+
* ```
117+
* import {
118+
* StyledButton,
119+
* StyledButtonProps,
120+
* } from './path-to/styledButton.component';
121+
*
122+
* public render(): React.ReactElement<StyledButtonProps> {
123+
* return (
124+
* <StyledButton/>
125+
* );
126+
* }
127+
* ```
128+
*
129+
* @returns {StyledComponentClass} - component class which can be used as styled component
130+
*/
131+
export const styled = <P extends object>(Component: React.ComponentClass<P>): StyledComponentClass<P> => {
42132

43133
// @ts-ignore
44134
if (!Component.styledComponentName) {

‎src/framework/theme/theme/themeConsumer.component.tsx

Lines changed: 66 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ import React from 'react';
88
import hoistNonReactStatics from 'hoist-non-react-statics';
99
import { ThemeContext } from './themeContext';
1010
import {
11-
ThemeType,
12-
ThemedStyleType,
1311
StyleSheetType,
12+
ThemedStyleType,
13+
ThemeType,
1414
} from './type';
1515

1616
interface PrivateProps<T> {
@@ -28,12 +28,71 @@ export interface Context {
2828
theme: ThemeType;
2929
}
3030

31-
// `P` is for component-specific props which could be passed into jsx element
32-
// `T` is for component-specific static props like `TabView.Tab`
33-
export type ThemedComponentClass<P, T = {}> = React.ComponentClass<ThemedComponentProps & P> & T;
31+
export type ThemedComponentClass<P> = React.ComponentClass<ThemedComponentProps & P>;
3432

35-
export const withStyles = <P, T = {}>(Component: React.ComponentClass<P>,
36-
createStyles?: CreateStylesFunction): ThemedComponentClass<P, T> => {
33+
/**
34+
* The `withStyles` function is a High Order Function which is used to create themed style for non-styled component.
35+
* Basically used when need to use `theme` variables somewhere.
36+
*
37+
* Passes following props to `Component` when it is rendered:
38+
*
39+
* @property {ThemeType} theme - Determines theme used to style component.
40+
* @property {StyleType} themedStyle - Determines component style for it's current state.
41+
*
42+
* @param {React.ComponentClass} Component - Determines class of component to be themed
43+
* @param {(theme: ThemeType) => any} createStyles - Determines arrow function used to create styles
44+
*
45+
* @example Declaring Themed Component
46+
*
47+
* ```
48+
* import {
49+
* withStyles,
50+
* ThemedComponentProps,
51+
* } from '@kitten/theme';
52+
*
53+
* type ThemedButtonProps = ButtonProps & ThemedComponentProps;
54+
*
55+
* class Button extends React.Component<ThemedButtonProps> {
56+
*
57+
* public render(): React.ReactElement<ButtonProps> {
58+
* // Retrieve styles from props (provided with themedStyle prop)
59+
* // And apply it with saving priority of `style` prop
60+
*
61+
* const { style, themedStyle, ...restProps } = this.props;
62+
*
63+
* return (
64+
* <TouchableOpacity
65+
* {...restProps}
66+
* style={[themedStyle, style]}
67+
* />
68+
* );
69+
* }
70+
* }
71+
*
72+
* export const ThemedButton = withStyles(Button, (theme: ThemeType) => ({
73+
* backgroundColor: theme['color-primary-500'],
74+
* }));
75+
* ```
76+
*
77+
* @example Themed Component Usage
78+
*
79+
* ```
80+
* import {
81+
* ThemedButton,
82+
* ThemedButtonProps,
83+
* } from './path-to/themedButton.component';
84+
*
85+
* public render(): React.ReactElement<ThemedButtonProps> {
86+
* return (
87+
* <ThemedButton/>
88+
* );
89+
* }
90+
* ```
91+
*
92+
* @returns {ThemedComponentClass} - component class which can be used as styled component
93+
*/
94+
export const withStyles = <P extends object>(Component: React.ComponentClass<P>,
95+
createStyles?: CreateStylesFunction): ThemedComponentClass<P> => {
3796

3897
type WrappingProps = PrivateProps<WrappedElementInstance> & WrappedProps;
3998
type WrappedProps = ThemedComponentProps & P;

0 commit comments

Comments
 (0)