Skip to content

Commit

Permalink
[core] Cover MDX with prettier (mui#54)
Browse files Browse the repository at this point in the history
  • Loading branch information
oliviertassinari committed Jul 9, 2020
1 parent c01c25b commit 8e63d73
Show file tree
Hide file tree
Showing 14 changed files with 125 additions and 98 deletions.
2 changes: 1 addition & 1 deletion packages/grid/data-grid/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Check out our [Demo here!](https://muix-preview.netlify.app/#/grid)

Using your favourite package manager, install `@material-ui-x/grid`

```shell script
```sh
//with npm
npm install @material-ui-x/grid

Expand Down
2 changes: 1 addition & 1 deletion packages/grid/x-grid/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Check out our [Demo here!](https://muix-preview.netlify.app/#/grid)

Using your favourite package manager, install `@material-ui-x/grid`

```shell script
```sh
//with npm
npm install @material-ui-x/grid

Expand Down
7 changes: 6 additions & 1 deletion packages/storybook/src/docs/api.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,17 @@ Generated?
## GridApi

### Core Api

### Columns Api

### Row Api

### Pagination Api

### Virtualization Api

### Sort Api

### Selection Api

### Style Api => Coming soon
Expand All @@ -25,4 +31,3 @@ Generated?
## ColDef

## Rows

133 changes: 82 additions & 51 deletions packages/storybook/src/docs/columns.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,29 @@ import StyleCellDemo from './demos/columns/styleCell.demo';

After importing XGrid or DataGrid, you're now ready to use the component in your JSX, and configure your grid columns.
To do this, you need to define the columns property of the component as below.
If you use Typescript, you can enforce the typing and define the prop with 'Columns' or 'ColDef[]' type.
If you use TypeScript, you can enforce the typing and define the prop with 'Columns' or 'ColDef[]' type.

```tsx
const columns: Columns = [
{
field: 'columnId', headerName: 'My Column Id', description: 'Something about this grid is amazing!', width: 100, sortable: true, type: 'number'
}
]
{
field: 'columnId',
headerName: 'My Column Id',
description: 'Something about this grid is amazing!',
width: 100,
sortable: true,
type: 'number',
},
];
```

In the code above we define a column with some of the basic attributes.

- `field` is a mandatory field and is used to associate the column header with the corresponding value in the rows that follow. It's similar to an id, but has to be a string.
- `headerName` is the title visible in the grid column header. If not set, `field` will be used in the header.
- `description` is the description of the column that will be displayed in a tooltip if the column header is too small to render the full column title.
- `width` is the width the column will be when the component has mounted.
- `sortable` is an optional boolean that allows making the column sortable.
- `type` is the type of the column, *more on this below*.
- `type` is the type of the column, _more on this below_.

The full list of column option is defined in the `ColDef` interface and can be found here (TODO: add link to ColDef generated doc)

Expand All @@ -38,20 +45,23 @@ By default, columns are assumed to hold strings and thus the default column stri
As a result, column sorting will use the string comparator, and the column content will be aligned to the left side of the cell.

The following types are built in:
- string
- number
- date
- dateTime

- string
- number
- date
- dateTime

To apply a column type, you just need to define the `type` property in your column definition.

```tsx
const columns: Columns = [
{ field: 'name' }, // `type: 'string'` by default
{ field: 'age', type: 'number' },
{ field: 'dateCreated', type: 'date' },
{ field: 'lastLogin', type: 'dateTime' },
]
];
```

In the code above, we are defining 4 columns, and just by applying a type, each column will be sortable with the correct comparator for its type.
We also added locale formatting for date, dateTime, and number Columns.

Expand All @@ -61,12 +71,13 @@ We also added locale formatting for date, dateTime, and number Columns.
### Extending col type? Adding new col type?

## Hiding

Hiding a column is pretty straightforward, you just need to toggle the `hide` attribute of the column definition.

```tsx
const columns: Columns = [
{ field: 'hiddenCol', hide: true },
]
const columns: Columns = [{ field: 'hiddenCol', hide: true }];
```

<HideColumnDemo />

## Sizing
Expand All @@ -76,74 +87,94 @@ To define the width of a column, you can use the `width` attribute available in
```tsx
const columns: Columns = [
{ field: 'largeCol', width: 200 },
{ field: 'unresizableCol', width: 200, resizable: false }
]
{ field: 'unresizableCol', width: 200, resizable: false },
];
```

## Getting values

Sometimes a column might not have a corresponding value and you just want to render a combination of different fields.
To do that, you can set the `valueGetter` attribute of `ColDef` as in the example below.

```tsx
const columns: Columns = [
{ field: 'firstName'},
{ field: 'lastName' },
{ field: 'fullName', valueGetter: ({data}) => `${data.firstName} ${data.lastName}` }
]
```
```tsx
const columns: Columns = [
{ field: 'firstName' },
{ field: 'lastName' },
{
field: 'fullName',
valueGetter: ({ data }) => `${data.firstName} ${data.lastName}`,
},
];
```

- `valueGetter` is a function of type `(params: ValueGetterParams) => CellValue;`, therefore you can destructure `params` to get all the row data, as in the example above.
TODO Api ref the valueGetter interface here!
TODO Api ref the valueGetter interface here!

<ValueGetterDemo />

## Formatting

Formatting data before rendering is a common task. It is used in the built in `date` or `dateTime` column types to apply local formatting to dates.

```tsx
const columns: Columns = [
{ field: 'date', headerName: 'Year' valueFormatter: ({value})=> value.getFullYear() }
]
```
- `valueFormatter` is a function of type `(params: ValueFormatterParams) => CellValue;`, therefore you can destructure `params` to get the column value as in the example above.
TODO: Api ref the valueFormatter interface here!
```tsx
const columns: Columns = [
{ field: 'date', headerName: 'Year' valueFormatter: ({value})=> value.getFullYear() }
]
```

- `valueFormatter` is a function of type `(params: ValueFormatterParams) => CellValue;`, therefore you can destructure `params` to get the column value as in the example above.
TODO: Api ref the valueFormatter interface here!

<FormattingDemo />

## Styling

There are different ways of styling `X-Grid` or `DataGrid`. In this part, we are going to focus only on the options available in our `ColDef` type.

### Header

`ColDef` has an attribute called `headerClass` that lets you inject some css classes into your column header.
You can also specify how to align the header text using `headerAlign`. The default value is `left`.

```tsx
const columns: Columns = [
{ field: 'styledCol', headerClass: 'super-app-theme--header', headerAlign: 'center'}
]
```
```tsx
const columns: Columns = [
{
field: 'styledCol',
headerClass: 'super-app-theme--header',
headerAlign: 'center',
},
];
```

- `HeaderClass` can be a `string` or a `string[]`
<StyleHeaderDemo />
<StyleHeaderDemo />

### Cell

`ColDef` lets you style cells with different attributes.

- `align` to align cell content, `'left' | 'right' | 'center'`
- `cellClass` of type `string | string[]`, allows you to apply css classes on every cell. It can also be of type `CellClassFn` which is a function that let you apply css classes dynamically.
- `cellClassRules` works like `classnames` [github here](https://github.com/JedWatson/classnames). It's an object, with css classes as keys and a boolean or a function as values.

```tsx
const columns: Columns = [
{ field: 'styledCell', cellClass: 'super-app-theme--cell', align: 'center'},
{
field: 'withRules',
cellClassRules: {
negative: {value} => value < 0,
positive: {value} => value > 0
},
align: 'right'
},
]
```
```tsx
const columns: Columns = [
{ field: 'styledCell', cellClass: 'super-app-theme--cell', align: 'center'},
{
field: 'withRules',
cellClassRules: {
negative: {value} => value < 0,
positive: {value} => value > 0
},
align: 'right'
},
]
```

<StyleCellDemo />

## Options

There are more options in `ColDef` which you can find the full definition in the API page (TODO: add link here)

- `disableClickEventBubbling`: allows you to disable the default click behaviour of the grid. If you render a clickable component in a column, such as a link or a button, you can use this option to disable the row selection on click.
- `disableClickEventBubbling`: allows you to disable the default click behaviour of the grid. If you render a clickable component in a column, such as a link or a button, you can use this option to disable the row selection on click.
1 change: 0 additions & 1 deletion packages/storybook/src/docs/components.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,3 @@ import { XGrid } from '@material-ui/x-grid';
# Components

How to override component

54 changes: 29 additions & 25 deletions packages/storybook/src/docs/quick-start.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,37 +2,42 @@ import { XGrid } from '@material-ui/x-grid';
import QuickStartDemo from './demos/quick-start.demo';

# Quick Start

<Meta title="1. Docs/1. Quick Start" component={XGrid} />

The official Material-UI Data Grid Component built in Typescript.
The official Material-UI Data Grid Component built in TypeScript.

Have a look at our demo app ** [here](https://muix-preview.netlify.app/#/grid)**.

## Install

Using your favourite package manager, install `@material-ui/x-grid` for the full featured enterprise grid, or `@material-ui/data-grid` for the free community version
Using your favourite package manager, install `@material-ui/x-grid` for the full featured enterprise grid, or `@material-ui/data-grid` for the free community version.

```shell script
//with npm
```sh
// with npm
npm install @material-ui/x-grid

//with yarn
// with yarn
yarn add @material-ui/x-grid
```

## Dependencies

To avoid package duplication, and its related issues, we let you control our dependencies.
Hence, X-Grid has the following peerDependencies.
```

```json
"peerDependencies": {
"@material-ui/core": "^4.11.0",
"react": "^16.13.1",
"styled-components": "^5.1.0"
},
"@material-ui/core": "^4.11.0",
"react": "^16.13.1",
"styled-components": "^5.1.0"
}
```

If you have not installed them yet, please do by running one of the following.
```shell script
//with npm

```sh
// with npm
npm install @material-ui/core react styled-components

//with yarn
Expand All @@ -46,29 +51,31 @@ First you have to import the component as below.
To avoid component clashing, we named our components **XGrid** and **DataGrid**.
If you don't use Material-UI core grid layout <a href='https://material-ui.com/components/grid/'>here</a>, and don't have any other components named grid, you can also import **Grid**.

`import { XGrid } from '@material-ui/x-grid';`
```js
import { XGrid } from '@material-ui/x-grid';
```

Then you need to create some columns which are simple objects containing at least a field property.
You can import `ColDef` to see all column properties.
A simple set of columns could be:

```tsx
const columns: ColDef[] = [
{ field: "id", width: 80},
{ field: "brand", headerName: 'Brand Name', width: 150}
...
];
{ field: 'id', width: 80 },
{ field: 'brand', headerName: 'Brand Name', width: 150 },
...
];
```

Rows are key value pair objects.

```tsx
const rows: RowsProp = [
{ id: 1, brand:'Nike'},
{ id: 2, brand:'Addidas'},
{ id: 3, brand:'Puma'},
...
]
{ id: 1, brand:'Nike'},
{ id: 2, brand:'Addidas'},
{ id: 3, brand:'Puma'},
...
];
```

The `options` properties let you apply different settings to the grid.
Expand All @@ -77,7 +84,4 @@ A complete example is below.

<QuickStartDemo />




**[Edit in Stackblitz](https://stackblitz.com/edit/x-grid-overview-demo)**
1 change: 0 additions & 1 deletion packages/storybook/src/docs/rows.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,3 @@ import { XGrid } from '@material-ui/x-grid';
## Height

## Options

1 change: 0 additions & 1 deletion packages/storybook/src/docs/selection.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,3 @@ import { XGrid } from '@material-ui/x-grid';
## Single Selection

## Multiple Selection

7 changes: 1 addition & 6 deletions packages/storybook/src/docs/sorting.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,7 @@ Row sorting
Enable sorting
You can enable sorting by setting the sortable option. A column can then be sorted by clicking on the column header.

<DataGrid
columns={[
{ field: 'name', sortable: true },
{ field: 'phone' },
]}
/>
<DataGrid columns={[{ field: 'name', sortable: true }, { field: 'phone' }]} />

## Single Column

Expand Down
3 changes: 0 additions & 3 deletions packages/storybook/src/docs/styling.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,3 @@ import { XGrid } from '@material-ui/x-grid';
### Header

### Overrides



Loading

0 comments on commit 8e63d73

Please sign in to comment.