Skip to content

Commit

Permalink
Merge pull request morfeojs#9 from VLK-STUDIO/docs/docs-improvement-a…
Browse files Browse the repository at this point in the history 
…nd-missing-root-licence

docs: fixes to core and styled components documentations
  • Loading branch information
@mauroerta
mauroerta authored May 23, 2021
2 parents afbb2df + b5374e4 commit da916fc
Show file tree
Hide file tree
Showing 3 changed files with 124 additions and 64 deletions.
25 changes: 25 additions & 0 deletions LICENSE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@

The MIT License (MIT)

Copyright (c) 2021 Mauro Erta.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
17 changes: 8 additions & 9 deletions packages/core/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
<div align="center">
<h1>@morfeo/core</h1>
</div>
<a href="https://github.com/VLK-STUDIO/morfeo">morfeo</a> is a framework-agnostic set of tools that will help you to build your next <strong>design system</strong> based on a single source of truth: the <strong>theme</strong>.

[morfeo]("https://github.com/VLK-STUDIO/morfeo") is a framework-agnostic set of tools that will help you to build your next **design system** based on a single source of truth: the **theme**.

<div align="center">
<a href="https://github.com/VLK-STUDIO/morfeo">Documentation</a> |
Expand Down Expand Up @@ -60,11 +61,11 @@ export const defaultTheme: Theme = {
...,
space: {
...,
s: "32px",
m: "40px",
s: "32px",
m: "40px",
l: "48px",
...,
},
},
colors: {
...,
primary: '#00000',
Expand Down Expand Up @@ -138,7 +139,7 @@ style will be equals to:
{
color: "#00000",
backgroundColor: "#fffff",
paddingLeft: "40px",
paddingLeft: "40px",
paddingRight: "40px"
}
```
Expand Down Expand Up @@ -190,7 +191,7 @@ this will create the following style:
"padding": "40px"
},
"@media (min-width: 900px)": {
"padding": "48px"
"padding": "48px"
}
}
```
Expand Down Expand Up @@ -239,9 +240,7 @@ Here it is the result:

Imagine `parsers` as a set of smaller parsers, one for each property you can pass to the resolve method, for example there is parser that recognize the `bg` property and returns a valid css-in-js style by referreing the value to the `colors` slice of the theme:

```
bg: primary ---> { backgroundColor: theme.getValue('colors', 'primary') }
```
`bg: primary ---> { backgroundColor: theme.getValue('colors', 'primary') }`

`parsers` exposes other methods other than resolve, with the `add` method you can define a new parser.

Expand Down
146 changes: 91 additions & 55 deletions packages/styled-components-web/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,44 @@
<div align="center"><h1>@morfeo/styled-components-web</h1></div>
<div align="center">
<h1>@morfeo/styled-components-web</h1>
</div>

**@morfeo/styled-components-web** is a wrapper of the **styled-components** library that allow you to quickly create **styled components** based on **morfeo theme**.
**@morfeo/styled-components-web** is a wrapper of the **styled-components** library that allows you to quickly create **styled components** based on **the morfeo theme**.

**@morfeo/styled-components-web** is part of the **@morfeo** eco-system, a set of **framework agnostic** tools that help you to create beautiful design-systems for you web and mobile apps.
**@morfeo/styled-components-web** is part of the **@morfeo** eco-system, a set of **framework-agnostic** tools that help you to create beautiful design systems for your web and mobile apps.

:information_source: Look at <a href="https://github.com/VLK-STUDIO/morfeo" target="_blank"><b>VLK-STUDIO/morfeo</b></a> to know more about **morfeo**
:information_source: Look at <a href="https://github.com/VLK-STUDIO/morfeo" target="_blank"><b>morfeo</b></a> to know more about **morfeo**

---

<div align="center">
<a href="https://github.com/VLK-STUDIO/morfeo">Documentation</a> |
<a href="https://github.com/VLK-STUDIO/morfeo">API</a> |
<a href="https://github.com/VLK-STUDIO/morfeo">Contributing</a> |
<a href="https://morfeo.slack.com">Slack</a>
</div>

---

## Installation

```bash
npm i @morfeo/styled-components-web
npm i @morfeo/styled-components-web @morfeo/web
```

Remember that **@morfeo/styled-components-web** has **styled-components** as *peerDependencies* so you need to install it separately.
Remember that **@morfeo/styled-components-web** has **styled-components** as _peerDependencies_ so you need to install it separately.

---

## Usage

Starting from your configured theme, imagine to have defined a `Button` component.

## Usage

Starting from your configured theme, imagine to have defined a `Button` component.

:warning: :warning: If you need to know more about **@morfeo** theme definition and initialization, the read of <a href="https://github.com/VLK-STUDIO/morfeo/tree/main/packages/core" target="_blank"><b>@morfeo/core</b></a> docs is highly recommended.:warning: :warning:
:warning: :warning: If you need to know more about **@morfeo** theme definition and initialization, reading [@morfeo/spec](https://github.com/VLK-STUDIO/morfeo/tree/main/packages/spec) docs is highly recommended.:warning: :warning:

```ts
// Sample myTheme.ts


const theme = {
const myTheme = {
...appTheme,
components: {
Button: {
Expand All @@ -47,7 +53,7 @@ const theme = {
}
},
secondary: {
tag: 'h3',
tag: 'a',
style: {
...yourButtonSecondaryStyle
}
Expand All @@ -63,7 +69,6 @@ You can create a styled Component Based on your **theme Button component**:

```typescript
// Button.ts

import styled from '@morfeo/styled-components-web';

export const Button = styled.Button({});
Expand All @@ -73,26 +78,41 @@ And use it as a common React component:

```tsx
// MyComponent.ts
import { Typography, Box, Button } from './components'
import { Typography, Box, Button } from './components';

export const MyComponent = () => {
return (
<Box>
<Typography variant="h1">Would you like to continue?</Typography>
<Button variant="secondary">NO</Button>
{/* you can always add other properties */}
<Box display="flex" alignItems="center">
<Typography variant="h1">Would you like to continue?</Typography>
<Button variant="secondary" bg="danger">NO</Button>
<Button variant="primary">YES</Button>
</Box>
)
}
);
};
```

---
:information_source: Notice

Defining a component in this way:

```tsx
export const Button = styled.Button({});
```

It's the same as defining it in this way:

```tsx
export const Button = styled.button({ componentName: 'Button' });
```

In fact, under the hood morfeo will find the component "Button" inside your theme and its specification will use the right [tag](#custom-tag), style, and [properties](#custom-props)

---

## ThemeProvider

As **@morfeo/core** is based on a singleton, you don't really need to provide the theme by a ThemeProvider but it could be very usefull if you need to keep compatibility with an existing styled-component implementation.
As **@morfeo/core** is based on a singleton, you don't really need to provide the theme by a ThemeProvider but it could be very useful if you need to keep compatibility with an existing styled-component implementation.

ThemeProvider does not need to receive a theme prop because the library do the work for you.

Expand All @@ -101,32 +121,30 @@ To set your own Theme use the **@morfeo/web theme API** instead.
```tsx
// App.js

import { ThemeProvider } from '@morfeo/styled-components-web'
import { theme } from '@morfeo/web'
import { myTheme } from './myTheme'
import { ThemeProvider } from '@morfeo/styled-components-web';
import { theme } from '@morfeo/web';
import { myTheme } from './myTheme';

theme.set(myTheme);

export const App = () => {
return (
<ThemeProvider>
<YourApp />
<ThemeProvider>
<YourApp />
</ThemeProvider>
)
}
);
};
```

---



## Custom tag

**@morfeo/styled-components-web** allow you to define the **HTML tag** of your components in a very flexible way, directly from theme.
**@morfeo/styled-components-web** allows you to define the **HTML tag** of your components in a very flexible way, directly from the theme.

For Example you can set a different **HTML tag** for a variant.
For Example, you can set a different **HTML tag** for a variant.

Take a look on this sample theme:
Take a look at this sample theme:

```typescript
// myTheme.ts
Expand All @@ -146,7 +164,7 @@ const theme = {
}
},
link: {
tag: 'h3',
tag: 'a',
style: {
...yourButtonSecondaryStyle
}
Expand All @@ -158,8 +176,7 @@ const theme = {
}
```

As you can see the secondary variant use an `h3` tag.

As you can see the secondary variant uses an `a` tag.
So, you can define your component:

```tsx
Expand All @@ -181,33 +198,52 @@ const MyComponent = () => {
return (
<>
<Button variant="primary" /> // <button .../>
<Button variant="link" /> // <h3 .../>
<Button variant="link" /> // <a .../>
</>
)
}
```

## Custom Props

Inside the component specification you can also define **default properties** for your components, for example:

## useTheme

**useTheme** is just a re-export from **styled-components**. You can use it as usually.
```typescript
const myTheme = {
...restOfTheme,
components: {
Button: {
tag: 'button',
style: {},
props: {
type: 'submit',
},
variants: {
cancel: {
props: {
type: 'button',
'aria-label': 'cancel',
},
},
},
},
},
};
```

```tsx
import { useTheme } from '@morfeo/styled-components-web'
import { Box } from './components'
const Button = styled.Button({});
const CancelButton = styled.Button({
variant: 'cancel',
});

const MyComponent = () => {
const theme = useTheme();
const bgColor = theme.colors.primary

function App() {
return (
<Box bgColor={bgColor} />
)
<>
<Button>Submit</Button>; // <button type="submit" />
<Button variant="cancel">Cancel</Button>; // <button type="button"aria-label="cancel" />
<CancelButton>Cancel</CancelButton>; // <button type="button" aria-label="cancel" />
</>
);
}
```

---



0 comments on commit da916fc

Please sign in to comment.