Skip to content

Latest commit

 

History

History
278 lines (212 loc) · 9.4 KB

DEV_DOCS.md

File metadata and controls

278 lines (212 loc) · 9.4 KB
Raw

Things you must follow before contributing

New Feature Checklist

  • lint checks are passing
  • tests are added or updated and passing
  • showcase components in demo application added or updated
  • showcase components in documentation application added or updated
  • readable documentation added or updated
  • commit message is properly formatted
  • looks great on all default themes
  • requires approval from several core team contributors

Docs

Docs is a separate Angular application located right in this project in docs folder. The pages structure is taken from structure.ts file. The components documentation is taken from the component comment sections.

Framework Structure

  • docs - Documentation and framework website built on top on the framework
  • src
    • components - @ui-kitten/components package. UI components itself.
    • eva-icons - @ui-kitten/eva-icons package. Eva Icons for React Native
    • date-fns - @ui-kitten/moment package. Services that allows UI Kitten components to work with date-fns.
    • moment - @ui-kitten/moment package. Services that allows UI Kitten components to work with moment.js.
    • template-js - @ui-kitten/template-js package. Template app for creating UI Kitten project with React Native CLI.
    • template-ts - @ui-kitten/template-ts package. Template app for creating TypeScript UI Kitten project with React Native CLI.
    • Demo Application - independent application with runnable examples for each feature

UI Kit

Located in ./src/components. Divided into two dirs:

  • theme - Contains styling services and supporting components used to provide styles to basic components.
  • ui - Contains basic UI components.

Styling services

Located in ./src/components/theme

  • theme - ThemeProvider component. Used to provide one of Eva themes used to style basic components.
  • mapping - MappingProvider component. Used to provide one of Eva mappings to style basic components.
  • style - StyleProvider components. This mixes both Theme- and Mapping- providers to provide usable basic component style object.
  • application - Global ApplicationProvider component. This mixes StyleProvider implementation with Eva processing engine.

Basic UI components

Located in ./src/components/ui

Each component implementation can be found in a directory with the corresponding name.

UI component directory structure:

  • *.component.tsx - component implementation itself.
  • *.spec.tsx - component tests.
  • *.spec.tsx.snap - component test snapshots. This is a generated file. Could be presented or not depending on tests.

Some of the components can have a more complex implementation. In this case, the final component implementation could be divided into sub-components, but tests should be written in a single *.spec file. The good example is TabView.

Documentation

Documentation is generated by the custom generator built on top of UI Kit. You have to use typedoc everywhere for the documentation purpose.

How to add a page to the documentation

Docs application split into the sections which you can find in the app's sidebar. Each section contains some pages. If you wanna add new page in the documentation, please, open structure.ts file in the root of docs application and add a new page in the required section:

{
  type: 'page',
  name: 'Awesom page',
  children: [
    ... blocks
  ],
},

If it's a completely new feature, maybe it would be better to create a new section:

{
  type: 'section',
  name: 'New super section',
  children: [
    ... pages
  ],
},

Page can contain multiple blocks of the following types:

Markdown block

Renders plain markdown file from the articles dir. For example, if you wanna add getting started article you have to do the following:

  • put getting-started.md file in the articles folder.
  • add markdown block to the page children:
{
  type: 'block',
  block: 'markdown',
  source: 'getting-started.md',
},

Component block

If you have to render all the information about component parsed with typedoc you have to use component blocks:

{
  type: 'block',
  block: 'component',
  source: 'MyNewComponentName',
},

Tabbed component block

Tabbed component block will render component description splitted on the following tabs:

  • Overview - This is typedoc comment above component
  • Theme - Theme variables listed in the typedoc comment above component with @styles tag, for example:
/**
 * ...
 *
 * @styles
 *
 * var1
 * var2
 *
 * ...
 */
  • API - parsing result of the typedoc above public methods and props
  • Examples - live examples listed in the typedoc comment above component

Examples

When you're developing new functionality, please, always add some examples describing it. You have the following ways to add examples in your component documentation:

Add raw code

If you wan't to describe a small thing in two lines of code you can just add something similar in your typedoc comment:

```jsx
const AwesomeComponentShowcase = () => (
  <AwesomeComponent/>
);
```

And don't forget to specify the language above your example.

Development

Create a new component

  • create directory in ./src/components/ui/awesomeComponent with following files:
- awesomeComponent.component.tsx (component file)
- awesomeComponent.spec.tsx (component tests)
  • create directory in Demo Application ./src/scenes/components/awesomeComponent with following files:
- awesome-component.component.tsx (component showcase container)
- awesome-component-showcase.component.tsx (basic component showcase)
- type.tsx (component configuration file)

Look through already existing showcases and use similar implementation (e.g Button Showcase)

  • register your showcase in a Demo Application:

Open Components Navigator and expand navigation with your component container:

import { AwesomeComponentScreen } from '../scenes/components/awesome-component.component';
...
<Stack.Screen name='AwesomeComponent' component={AwesomeComponentScreen} />

Open Components Screen and expand it with route to new component:

{
    title: 'AwesomeComponent',
    route: 'AwesomeComponent',
    ...
  }

Release

  1. For major version, search for @breaking-change to make sure all breaking changes are covered.

To start a new release (publish the framework packages on NPM) you need:

  1. Create a new release branch with template release/vX.X.X
  2. Run tests: npm run lint && npm run test
  3. MANUALLY update a version in main ./package.json to a new one
  4. Generate changelog: npm run bump-version
  5. Fix/expand changelog manually
  6. Update documentation (e.g DEV_DOCS.md) files if needed
  7. Push the branch, create PR, approve - merge
  8. Pull the upstream (master or another version branch (e.g. 4.0.1, next))
  9. Publish documentation: npm run publish-docs
  10. Publish framework packages: npm run publish-packages
  11. Create and push git tag with template (vX.X.X)
  12. Create release on GitHub for the tag

Demo Application - Kitten Tricks

Kitten Tricks is an example app built on top of the Expo containing reusable screens and runnable component examples. This application is used as a framework demo.

Start a Demo Application

yarn && yarn demo start from the react-native-ui-kitten project or yarn && yarn start from the kittenTricks project

Demo Application environments:

Demo Application supports two environments:

  • Production (Provides Eva Design System and UI Kitten modules published to npm)
  • Development (Provides local Eva Design System and UI Kitten modules)

To run Demo Application in a development mode:

  • Clone Eva Design System to the directory containing UI Kitten repo:
git clone https://github.com/eva-design/eva
  • Clone Demo Application to the directory containing UI Kitten repo:
git clone https://github.com/akveo/kittenTricks
  • IMPORTANT Ensure you have the following structure of repos:
- /
  - eva
  - kittenTricks
  - react-native-ui-kitten
  • Install dependencies if needed and finally run yarn demo start:dev