[WIP] Document components using Docz

.gitignore

@@ -9,3 +9,4 @@ examples/**/static
 examples/**/dist
 cypress/videos
 cypress/screenshots
+.docz

docs/components/DocWrapper.js

@@ -0,0 +1,14 @@
+import React from 'react';
+import { Provider } from 'react-redux';
+import { createStore } from 'redux';
+import TranslationProvider from '../../packages/ra-core/src/i18n/TranslationProvider';
+
+const store = createStore(() => ({ i18n: { locale: 'en' } }));
+
+const DocWrapper = ({ children }) => (
+    <Provider store={store}>
+        <TranslationProvider>{children}</TranslationProvider>
+    </Provider>
+);
+
+export default DocWrapper;

docs/components/PropsTable.js

@@ -0,0 +1,89 @@
+import React, { Fragment } from 'react';
+import styled from 'react-emotion';
+
+const Table = styled('table')`
+    width: 100%;
+    padding: 0;
+    margin-bottom: 50px;
+    border-spacing: 0;
+    border-collapse: collapse;
+    border-style: hidden;
+    & thead {
+        color: ${p => p.theme.colors.grayDark};
+    }
+    & thead th {
+        text-align: left;
+        font-weight: 400;
+        padding: 1em;
+        &.description {
+            min-width: 40%;
+        }
+    }
+    & tbody td {
+        padding: 1em;
+        &.nowrap {
+            white-space: nowrap;
+        }
+        & code {
+            font-size: 0.8em;
+            font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+        }
+        &.description {
+            min-width: 40%;
+        }
+    }
+    & tbody > tr {
+        display: table-row;
+        border-top: 1px solid ${p => p.theme.colors.border};
+    }
+`;
+
+const PropsTable = ({ props }) => {
+    if (!props) {
+        return null;
+    }
+
+    return (
+        <Fragment>
+            <Table className="PropsTable">
+                <thead>
+                    <tr>
+                        <th>Property</th>
+                        <th>Type</th>
+                        <th>Default</th>
+                        <th className="description">Description</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    {props &&
+                        Object.keys(props).map((name: string) => {
+                            const prop = props[name];
+
+                            if (!prop.flowType && !prop.type) return null;
+                            return (
+                                <tr key={name}>
+                                    <td className="nowrap">
+                                        <code>
+                                            {name}
+                                            {prop.required && ' *'}
+                                        </code>
+                                    </td>
+                                    <td>
+                                        <code>{prop.type}</code>
+                                    </td>
+                                    <td>
+                                        <code>{prop.default}</code>
+                                    </td>
+                                    <td className="description">
+                                        {prop.description && prop.description}
+                                    </td>
+                                </tr>
+                            );
+                        })}
+                </tbody>
+            </Table>
+        </Fragment>
+    );
+};
+
+export default PropsTable;

docs/components/WithStyles.js

@@ -0,0 +1,9 @@
+import jss from 'jss';
+
+const WithStyles = ({ styles, children, ...rest }) =>
+    children({
+        classes: jss.createStyleSheet(styles).attach().classes,
+        ...rest,
+    });
+
+export default WithStyles;

doczrc.js

@@ -0,0 +1,20 @@
+import { babel } from 'docz-plugin-babel6';
+
+export default {
+    title: 'react-admin',
+    plugins: [babel()],
+    wrapper: 'docs/components/DocWrapper',
+    themeConfig: {
+        styles: {
+            sidebar: {
+                width: 250,
+            },
+            playground: {
+                padding: '1em',
+            },
+            pre: {
+                padding: '1em!important',
+            },
+        },
+    },
+};

package.json

@@ -2,7 +2,9 @@
     "private": true,
     "name": "react-admin-lerna",
     "scripts": {
-        "test": "make test"
+        "test": "make test",
+        "doc": "docz dev",
+        "doc-build": "docz build"
     },
     "jest": {
         "setupTestFrameworkScriptFile": "./test-setup.js"
@@ -20,6 +22,10 @@
         "babel-preset-stage-0": "~6.24.1",
         "babel-register": "~6.26.0",
         "cheerio": "~1.0.0-rc.2",
+        "docz": "~0.5.6",
+        "docz-plugin-babel6": "~0.5.6",
+        "docz-theme-default": "~0.5.6",
+        "emotion": "^9.2.4",
         "eslint": "~4.19.1",
         "eslint-config-prettier": "~2.9.0",
         "eslint-plugin-cypress": "~2.0.1",
@@ -34,7 +40,12 @@
         "prettier": "~1.13.7",
         "prettier-eslint-cli": "~4.7.1",
         "raf": "~3.4.0",
-        "wait-on": "^2.1.0"
+        "wait-on": "^2.1.0",
+        "react-emotion": "^9.2.4"
     },
-    "workspaces": ["packages/*", "examples/*", "cypress"]
+    "workspaces": [
+        "packages/*",
+        "examples/*",
+        "cypress"
+    ]
 }

packages/ra-ui-materialui/src/button/EditButton.mdx

@@ -0,0 +1,94 @@
+---
+name: EditButton
+menu: buttons
+---
+
+import { Playground } from 'docz';
+import PropTypes from 'prop-types';
+import PropsTable from '../../../../docs/components/PropsTable';
+import WithStyles from '../../../../docs/components/WithStyles';
+import EditButton from './EditButton';
+
+# EditButton
+
+A button leading to the Edit view of the current record. Generally used as child of `<Datagrid>`, and in the toolbar of the `<ShowView>`.
+
+<Playground>
+    <EditButton />
+</Playground>
+
+## Props
+
+<PropsTable props={{
+    alignIcon: { 
+        type: 'left|right',
+        description: 'The icon position',
+        default: 'left'
+    },
+    basePath: {
+        type: 'string',
+        description: 'The current page base path. Used for generating the link. Injected by react-admin.',
+        required: 'true',
+    },
+    className: {
+        type: 'string',
+        description: 'A custom class name to be applied to the main element'
+    },
+    classes: {
+        type: 'object',
+        description: 'The component styles, injected by withStyles().',
+        default: 'default styles (see below)'
+    },
+    label: {
+        type: 'string',
+        description: 'The Button text. Will be translated by the i18n provider.',
+        default: 'ra.action.edit'
+    },
+    record: { 
+        type: 'record',
+        description: 'The curent record. Injected by react-admin.',
+        required: 'true',
+    }
+}} />
+
+## Examples
+
+<Playground style={{ display:'flex', justifyContent: 'space-around' }}>
+    <EditButton label="Post details" />
+    <EditButton alignIcon="right" />
+    <EditButton className="Foo" />
+</Playground>
+
+## Customizing the material-ui Button
+
+Additional props are passed down to the material-ui [`<Button>`](https://material-ui.com/demos/buttons/) component.
+
+<Playground style={{ display:'flex', justifyContent: 'space-around' }}>
+    <EditButton variant="outlined" />
+    <EditButton size="large" />
+    <EditButton variant="contained" color="secondary" />
+</Playground>
+
+## Customizing Style
+
+Using the `classes` prop, you can override the following inner styles:
+
+- `button`: applied to the material-ui `<Button>` component
+- `label`: applied to the label
+- ` labelRightIcon`: applied to the label when the icon is in right position
+
+
+<Playground>
+    <WithStyles styles={{ label: { color: 'red' }}}>
+        {({ classes }) => <EditButton classes={{ label: classes.label }} />}
+    </WithStyles>
+</Playground>
+
+
+## Injected Props
+
+When used inside a `<Datagrid>` or `<CardActions>`, react-admin injects the current `basePath` and `record`, which are necessary to generate a correct link.
+
+<Playground>
+    <EditButton basePath="posts" record={{ id: 123, title: "hello, world" }} />
+</Playground>

packages/ra-ui-materialui/src/field/BooleanField.js

@@ -21,7 +21,6 @@ export const BooleanField = ({ className, source, record = {}, ...rest }) => {
 
 BooleanField.propTypes = {
     addLabel: PropTypes.bool,
-    basePath: PropTypes.string,
     className: PropTypes.string,
     cellClassName: PropTypes.string,
     headerClassName: PropTypes.string,

packages/ra-ui-materialui/src/field/BooleanField.mdx

@@ -0,0 +1,116 @@
+---
+name: BooleanField
+menu: fields
+---
+
+import { Playground } from 'docz';
+import PropTypes from 'prop-types';
+import PropsTable from '../../../../docs/components/PropsTable';
+import WithStyles from '../../../../docs/components/WithStyles';
+import BooleanField from './BooleanField';
+import SimpleShowLayout from '../detail/SimpleShowLayout';
+import Datagrid from '../list/Datagrid';
+
+# BooleanField
+
+Displays a true of false icon depending on the value of the record field. Generally used as child of `<Datagrid>`, `<SimpleShowLayout>`, or `<SimpleForm>`.
+
+<Playground>
+    <SimpleShowLayout resource="post" record={{ is_published: true, is_final: false, is_strange: 'neither true or false' }} style={{ display:'flex', justifyContent: 'space-around' }}>
+        <BooleanField source="is_published"  />
+        <BooleanField source="is_final"  />
+        <BooleanField source="is_strange" />
+    </SimpleShowLayout>
+</Playground>
+
+## Props
+
+<PropsTable props={{
+    addLabel: { 
+        type: 'boolean',
+        description: 'Add a label when used in a form',
+        default: true
+    },
+    className: {
+        type: 'string',
+        description: 'A custom class name to be applied to the main element'
+    },
+    cellClassName: {
+        type: 'string',
+        description: 'A custom class name to be applied to the cell containing the component when used in a Datagrid'
+    },
+    headerClassName: {
+        type: 'string',
+        description: 'A custom class name to be applied to the header of the column of the component when used in a Datagrid'
+    },
+    label: {
+        type: 'string',
+        description: 'The field label. Will be translated by the i18n provider.',
+        default: 'The humanized source (e.g. post_id => Post id)'
+    },
+    record: { 
+        type: 'object',
+        description: 'The curent record. Injected by react-admin.',
+    },
+    sortBy: { 
+        type: 'string',
+        description: 'The name of the field to use for sorting when the user clicks on the field header name.',
+        default: 'The source'
+    },
+    source: { 
+        type: 'string',
+        description: 'The path to the value in the record. Can use dot notation (e.g. "author.name") when the record has sub objects.',
+        required: 'true'
+    }
+}} />
+
+## Examples
+
+<Playground>
+    <WithStyles styles={{ dark: { background: '#ccffe3' }}}>
+    {({ classes }) => 
+        <SimpleShowLayout resource="post" record={{ is_published: true, is_final: false, has_class: true }} style={{ display:'flex', justifyContent: 'space-around' }}>
+            <BooleanField source="is_published" label="Published?" />
+            <BooleanField source="is_final" addLabel={false} />
+            <BooleanField source="has_class" className={classes.dark} />
+        </SimpleShowLayout>
+    }
+    </WithStyles>
+</Playground>
+
+Inside a `<Datagrid>`, you can benefit from the `headerClassName` and `cellClassName` props to style the filed header or cell.
+
+<Playground>
+<WithStyles styles={{ green: { background: '#ccffe3' }, yellow: { background: '#ffc' }}}>
+    {({ classes }) => 
+        <Datagrid resource="post" ids={[1, 2]} data={{
+            1: { is_published: true, is_final: false, has_class: true },
+            2: { is_published: false, is_final: false, has_class: false }
+        }}>
+            <BooleanField source="is_published" headerClassName={classes.green} />
+            <BooleanField source="is_final" cellClassName={classes.yellow} />
+            <BooleanField source="has_class" />
+        </Datagrid>
+    }
+    </WithStyles>
+</Playground>
+
+## Customizing the material-ui Icon
+
+Additional props are passed down to the material-ui [`<SvgIcon>`](https://material-ui.com/api/svg-icon/) component.
+
+<Playground>  
+    <SimpleShowLayout resource="post" record={{ is_published: true, is_final: false, has_class: true, }} style={{ display:'flex', justifyContent: 'space-around' }}>  
+        <BooleanField source="is_published" nativeColor="#afa" />
+        <BooleanField source="is_final" color="secondary" />
+        <BooleanField source="has_class" titleAccess="Has Class" />
+    </SimpleShowLayout>
+</Playground>
+
+## Injected Props
+
+When used inside a `<Datagrid>` or `<CardActions>`, react-admin injects the current `record`, which is necessary to get the data.
+
+<Playground>
+    <BooleanField source="is_published" record={{ id: 123, title: "hello, world", is_published: true }} />
+</Playground>