Skip to content

Commit

Permalink
Merge pull request #1540 from gluestack/patch
Browse files Browse the repository at this point in the history 
Patch
  • Loading branch information
@makkarMeenu
makkarMeenu authored Dec 19, 2023
2 parents 07e648d + 20a7a17 commit 22b8b01
Show file tree
Hide file tree
Showing 4 changed files with 163 additions and 173 deletions.
2 changes: 1 addition & 1 deletion example/storybook/.storybook/preview.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ export const parameters = {
'Recipes',
['Card', 'LinearGradient'],
'Resources',
['Todo-List', 'Dashboard App'],
['Todo-List', 'Dashboard App', 'Third Party Library Integrations'],
'Migration',
['NativeBase to gluestack-ui'],
'More',
Expand Down
5 changes: 0 additions & 5 deletions example/storybook/src/styled/plugins/AnimationPlugin/index.stories.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,6 @@ import { Motion } from '@legendapp/motion';
import { Button, AppProvider, CodePreview } from '@gluestack/design-system';
import { config } from '../../components/nb.config';
import { StyledProvider, styled } from '@gluestack-style/react';
import {
AnimatedImage,
AnimatedView,
AnimatePresence,
} from '@gluestack-style/animation-resolver';

<Meta title="styled/plugins/Animation Plugin" />

Expand Down
201 changes: 34 additions & 167 deletions example/storybook/src/ui/guides/building-design-systems/index.stories.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,190 +9,57 @@ import { Canvas, Meta, Story } from '@storybook/addon-docs';

# Building Design Systems

Use `gluestack-ui` to build your own collection of components that match your vision, and deploy across projects.
## Introduction

## Step 1: Create Your Own Package
**gluestack-ui-design-system** is a comprehensive design system built on top of the universal `gluestack-ui` library. It provides a collection of UI components , a Storybook for interactive development and testing, and a flexible configuration setup for seamless customization. It is a starter kit template to create your own Design System.

To build your own design system, you can directly **fork** [`gluestack-ui`](https://github.com/gluestack/gluestack-ui) and begin shaping your design system upon this foundation.
## Getting Started

This includes :
- A component library package `@gluestack-ui/themed` in `packages/themed` directory.
- A theme package `@gluestack-ui/config` in `packages/config` directory.
- A storybook for both React and React Native in `example/storybook` directory.

Follow these steps after **forking** this repository:

### Change library name

- Navigate to the `packages/themed` and open `package.json`. (You can rename the folder if you need).
- Locate the `name` field in the `package.json` file and update it to `@myapp/components`.

```json
//package.json
{
"name": "@myapp/components"
// ...
}
- Go to the template [repository](https://github.com/gluestack/gluestack-ui-design-system) for `gluestack-ui-design-system`.
- Click on `Use this template` button on the top-right corner.
- Clicking on `Create a new repository` will create a new repository with this template on your desired organization.
- Clone that repository from your codebase.
- Navigate to project directory
```bash
cd gluestack-ui-design-system
```

Now your library `@myapp/components` has all primitive components from `@gluestack-ui/themed` by default.

- Similarly, Navigate to the `packages/config` and open `package.json`. (You can rename the folder if you need).
- Locate the `name` field in `package.json` file and update it to `@myapp/config`.

```json
//package.json
{
"name": "@myapp/config"
// ...
}
- Install dependencies
```bash
yarn
```

Now your library `@myapp/config` has all primitive components from `@gluestack-ui/config` by default.

### Update storybook configuration

Navigate to the `example/storybook` and make updates to the specified files below.
## Running Storybook

- **_tsconfig.json_**:
To interactively develop and test UI components, you can use Storybook. Follow these steps to run Storybook locally:

You'll need to update `paths` in `tsconfig.json` for TypeScript import resolution.
- Navigate to storybook directory

```jsx
// ... other configuration
"compilerOptions": {
// ...
"paths": {
"@myapp/components": ["../../packages/themed/src"],
"@myapp/config": ["../../packages/config/src/gluestack-ui.config"],
},
// ...
}
```bash
cd example/storybook
```

- **_babel.config.js_**:
You'll need to update `alias` in `babel.config.ts` file incase you've renamed the folder `packages/themed` or `packages/config`.
```jsx
// ... other configuration
plugins: [
[
'module-resolver',
{
alias: {
'@gluestack-ui/themed': path.join(
__dirname,
'../../packages/<component-folder-name>/src'
),
}
},
]
],
// ... other configuration
- Run to storybook on the web
```bash
yarn storybook
```
- Run to storybook on mobile
```bash
yarn ios
```

## Step 2: Customize Tokens and Components

### Theme Tokens

Theme tokens and other configuration is present in `packages/config/src`. You have the flexibility to modify these tokens as per your requirements.

Check [this](/ui/docs/theme-configuration/customizing-theme) for more details.

### Components

You can customize the styling of all primitive components by modifying styling in `packages/config/src/theme/<ComponentName>.ts/` for a particular component. You may add and modify property value and variants based on your need.

**Create a custom component**
To create your own custom component. You need to follow these steps:

1. Create a folder inside `packages/themed/src/components/Circle`
2. Create a folder `styled-components/` inside `packages/themed/src/components/Circle` to keep components.
3. Create a styled component using `@gluestack-style/react` in `Root.tsx`. This will be an unstyled component initially with just component name.

```jsx
export const Root = styled(View, {}, { componentName: 'Circle' });
```

5. For other functionalities like accessibility and events, create an `index.tsx` file `packages/themed/src/components/Circle/index.tsx` and export it.

```jsx
import { Root } from './styled-components';

const Circle = (props) => {
return <Root {...props}>{props.children}</Root>;
};
```

6. Export from `packages/themed/src/components/index.tsx`

```jsx
// other components
export * from './Circle';
```

7. Now we will define theme for `Circle` inside `packages/config/src/theme/Circle.ts`.

```jsx
import { createStyle } from '@gluestack-style/react';

export const Circle = createStyle({
alignItems: 'center',
justifyContent: 'center',
borderRadius: '$full',
overflow: 'hidden',
variants: {
size: {
large: {
width: 100,
height: 100,
},
},
},
});
```

8. Export from `packages/config/src/index.ts`

```jsx
// other components
export * from './Circle';
```

## Step 3: Test Your Package

Now you can import and test your component.

```jsx
import { Circle } from '@myapp/components';
export default () => <Circle size="large" />;
```

## Step 4: Publish Your Package

Publish your design system as a package from `packages/themed` and theme package from `packages/config`.

## Step 5: Integrate it in Your App

Once published, you can use `@myapp/components` in your app you need add it to your `package.json` and update your configuration.

#### Next.js
## Customization

Update **_next.config.js_**:
The gluestack-ui-design-system allows for easy customization to align with your project's requirements. To customize the design system, follow these steps:
```jsx
/** @type {import('next').NextConfig} */
const { withGluestackUI } = require('@gluestack/ui-next-adapter');
- Customize design tokens (colors, sizes, media queries) and component themes in `packages/config` by adding, removing, or modifying entries.
- Adjust component functionality by adding, removing, or modifying features in `packages/themed`.
const nextConfig = {
reactStrictMode: true,
transpilePackages: ['@myapp/components', '@myapp/config'],
};
- To customize the branding with your own design system, navigate to the preview.js file within the .storybook folder and modify the relevant fields according to your branding preferences.
module.exports = withGluestackUI(nextConfig);
```
## Documentation
#### Expo
You can find detailed documentation of `gluestack-ui` for each component, including a list of props, examples, and customization at https://gluestack.io/ui/docs website.
No need to update any config for Expo.
## Tech Stack
> Note: For production optimization you can have a look [here](/docs/production-optimizations/babel-plugin)
JavaScript, React, React Native, Styled System
128 changes: 128 additions & 0 deletions ...e/storybook/src/ui/resources/third-party-library-integrations/index.stories.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
title: Third party components | gluestack-ui
description: Ways to add third party components to gluestack-ui
toc: false
---

import {
GluestackUIProvider,
HStack,
Text,
Pressable,
Icon,
AddIcon,
Button,
Box,
} from '@gluestack-ui/themed';
import { config } from '@gluestack-ui/config';
import { transformedCode } from '../../utils';
import Wrapper from '../../components/Wrapper';
import {
AppProvider,
CodePreview,
Table,
TableContainer,
InlineCode,
} from '@gluestack/design-system';
import { Canvas, Meta, Story } from '@storybook/addon-docs';

<script async src="https://snack.expo.dev/embed.js"></script>

<Meta title="ui/Resources/Third Party Library Integrations" />

# Third-Party Component Integrations

This page provides guidance on incorporating third-party components into your gluestack-ui project. Enhance your application's functionality by seamlessly integrating external components.

## Integration Steps:

1. Install the third-party component's package.

2. Create a wrapper component that renders the third-party component.

3. Add the wrapper component to your gluestack-ui project.

## Example

### Install the third-party component's package

Install the third-party component's package using your package manager of choice. For example, to install the [react-native-color-picker](https://github.com/instea/react-native-color-picker) package, run the following command:

```bash
yarn add react-native-color-picker
```

### Create a wrapper component

Create a wrapper component that renders the third-party component. For example, to create a wrapper component for the [react-native-color-picker](ColorPicker)

- Create a new directory for the wrapper component. For example, `src/components/ColorPicker`.
- Create a new file for the wrapper component. For example, `src/components/ColorPicker/ColorPicker.tsx` for native and `src/components/ColorPicker/ColorPicker.web.tsx` for web.
- Add the following code to the wrapper component file for native:

```jsx
import { ColorPicker as ColorPickerComponent } from 'react-native-color-picker';

export default ColorPicker = (props) => {
return <ColorPickerComponent {...props} />;
};
```

- Add the following code to the wrapper component file for web:

```jsx
export default ColorPicker = (props) => {
return <input type="color" {...props} />;
};
```

- Add the following code to the `src/components/index.ts` file:

```jsx
export ColorPicker from './ColorPicker';
```

### Add the wrapper component to your gluestack-ui project

Add the wrapper component to your gluestack-ui project. For example, to add the [react-native-color-picker](ColorPicker) wrapper component to your gluestack-ui project:

```jsx
import { ColorPicker } from '../components';
import { Center } from '@gluestack-ui/themed';
export const HomeScreen = () => {
return (
<Center>
<ColorPicker style={{ height: 80, width: 80 }} />
</Center>
);
};
```

### Styling the third-party component using gluestack-style

You can style the third-party component using the [gluestack-style](/style/docs). For example, to style the [react-native-color-picker](ColorPicker) component:

```jsx
import { ColorPicker } from '../components';
import { styled } from '@gluestack-ui/themed';

const StyledColorPicker = styled(ColorPicker, {
bg: '$yellow100',
height: '$64',
width: '$48',
});
```

You can check the [styled](style/docs/getting-started/styled) function from `gluestack-style` to style it more precisely as per needs.

### Adding accessibility labels to the third-party component

You can add accessibility labels to the third-party component using the [gluestack-accessibility](/accessibility/docs). For example, to add accessibility labels to the [react-native-color-picker](ColorPicker) component:

```jsx
import { ColorPicker as ColorPickerComponent } from 'react-native-color-picker';

export default ColorPicker = (props) => {
return <ColorPickerComponent {...props} accessibilityLabel={'your-label'} />;
};
```

0 comments on commit 22b8b01

Please sign in to comment.