@7shifts/sous-chef 4.2.0 → 4.3.0

package/llms-instructions/llms-composing-components.md

@@ -0,0 +1,502 @@
+# Sous Chef Design System - Composing Components
+
+In this document, you will find common examples and use cases for composing Sous Chef components to create user interfaces.
+
+## Pages
+
+In Sous Chef, there is currently no component to build the full app layout structure as a whole, such as the navbar, top bar, and center area. However, it offers the `PageLayout` component and the `Page` component, which can be used together.
+The `Page` component can be used without the `PageLayout` component.
+
+Use the `PageLayout` only when you have a group of pages, linked by a menu on the left side (it is not the app left side nav).
+
+Example:
+
+```tsx
+const MENU = [
+    {
+        to: '/employees',
+        label: 'Employees',
+        badge: '1'
+    },
+    {
+        to: '/inactive-employees',
+        label: 'Inactive Employees',
+        badge: '2'
+    }
+];
+
+return (
+    // I'm using the MemoryRouter but it could be any other react router
+    <MemoryRouter
+        initialEntries={['/active-employees', '/inactive-employees']}
+        initialIndex={0}
+    >
+        <PageLayout title="Employees" menu={MENU}>
+            <Routes>
+                <Route
+                    path="/active-employees"
+                    element={<ActiveEmployeesPage />}
+                />
+                <Route
+                    path="/inactive-employees"
+                    element={<InactiveEmployeesPage />}
+                />
+            </Routes>
+        </PageLayout>
+    </MemoryRouter>
+);
+
+// This is the example for the ActiveEmployeesPage
+
+const ActiveEmployeesPage = () => {
+    return <Page title="Active employees">// Content goes here</Page>;
+};
+
+// This is the example for the InactiveEmployeesPage
+
+const ActiveEmployeesPage = () => {
+    return <Page title="Inactive employees">// Content goes here</Page>;
+};
+```
+
+Notice that the `PageLayout` component is a container that holds a group of pages, and its children are where the `Page` component will be rendered and orchestrated by a router.
+
+## Forms
+
+When it comes to forms in Sous Chef, we need to be clear on three concepts:
+
+### Form UI
+
+By default, the `<Form>` component wraps all children in a `Stack` component. Because of that, all form fields will have the proper spacing of `20px`:
+
+```
+<Form>
+    <TextField name="firstName" label="First Name" />
+    <TextField name="lastName" label="Last Name" />
+    <FormFooter actions={{
+            primary: <Button>Save</Button>,
+            secondary: <Button>Cancel</Button>
+        }}
+    />
+</Form>
+```
+
+On the example above, it will add the proper spacing for the form fields, however, for the form footer by design it has a larger space from the form fields. The `FormFooter` adds that space automatically.
+Because of that, NEVER build your own form actions:
+
+NEVER DO THIS:
+
+```tsx
+<Form>
+    <TextField name="firstName" label="First Name" />
+    <TextField name="lastName" label="Last Name" />
+    // This won't add the proper spacing from the form fields
+    <Inline>
+        <Button theme="primary">Save</Button>
+        <Button>Cancel</Button>
+    </Inline>
+</Form>
+```
+
+Notice, the `FormFooter` also adds the proper theme to the buttons as well as controlling the position of the buttons.
+
+#### Form in a Modal
+
+The tricky part to understand when adding form in a modal is that the `Form` component needs to wrap the `ModalBody` and the `ModalFooter` so the form is accessible (user can hit the ENTER key to submit the form).
+
+Example:
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<>
+    <Button onClick={() => setIsOpen(true)}>Show modal</Button>
+    {isOpen && (
+        <Modal
+            header="Add Location"
+            onClose={() => setIsOpen(false)}
+            header="Add Location"
+        >
+            <Form
+                onSubmit={() => {
+                    console.log('Will submit form!');
+                    setIsOpen(false);
+                }}
+                stackContent={false}
+            >
+                <ModalBody>
+                    <Stack>
+                        <TextField name="firstName" label="First Name" />
+                        <TextField name="lastName" label="First Name" />
+                    </Stack>
+                </ModalBody>
+                <ModalFooter
+                    actions={{
+                        primary: <Button type="submit">Create location</Button>,
+                        secondary: (
+                            <Button onClick={() => setIsOpen(false)}>
+                                Cancel
+                            </Button>
+                        )
+                    }}
+                />
+            </Form>
+        </Modal>
+    )}
+</>;
+```
+
+Notice that `stackContent={false}` is passed to the `Form` component. That is necessary so it does not add a `Stack` around the form children, because we don't want to add extra space to `ModalBody` and `ModalFooter`. However, inside the `ModalBody`, we still need to add a `Stack` around the form fields to guarantee proper spacing.
+
+DON'T DO THIS:
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<>
+    <Button onClick={() => setIsOpen(true)}>Show modal</Button>
+    {isOpen && (
+        <Modal
+            header="Add Location"
+            onClose={() => setIsOpen(false)}
+            header="Add Location"
+        >
+            <ModalBody>
+                // The Form component is not wrapping the ModalFooter
+                <Form
+                    onSubmit={() => {
+                        console.log('Will submit form!');
+                        setIsOpen(false);
+                    }}
+                    stackContent={false}
+                >
+                    <TextField name="firstName" label="First Name" />
+                    <TextField name="lastName" label="First Name" />
+                </Form>
+            </ModalBody>
+            <ModalFooter
+                actions={{
+                    primary: <Button type="submit">Create location</Button>,
+                    secondary: (
+                        <Button onClick={() => setIsOpen(false)}>Cancel</Button>
+                    )
+                }}
+            />
+        </Modal>
+    )}
+</>;
+```
+
+The example above produces a good interface at first glance; however, it is NOT accessible. The user CAN'T press ENTER to submit the form.
+
+### Form state
+
+The Sous Chef form components are state-agnostic, which means you can keep form state wherever you want. However, we recommend two approaches:
+
+#### React useState
+
+Recommended for smaller forms when there is not much validation.
+
+Example:
+
+```tsx
+const [firstName, setFirstName] = useState('');
+
+return (
+    <Form onSubmit={() => console.log(firstName)}>
+        <TextField
+            name="firstName"
+            label="First Name"
+            value={firstName}
+            onChange={setFirstName}
+        />
+    </Form>
+);
+```
+
+Notice that in this case you need to pass the `value` and the `onChange` properties to make the form field controllable.
+If there is any validation you can use the `error` prop:
+
+Example:
+
+```tsx
+const [firstName, setFirstName] = useState('');
+
+return (
+    <Form onSubmit={() => console.log(firstName)}>
+        <TextField
+            name="firstName"
+            label="First Name"
+            value={firstName}
+            onChange={setFirstName}
+            error={!firstName && 'First name required!'}
+        />
+    </Form>
+);
+```
+
+Notice that in this case the validation is manual, and we would need to add other checks to make it a good user experience, for example, checking whether the field was touched before showing the error message. That is why, if you have validations, we recommend using Formik.
+
+### Formik
+
+Keeping the state in Formik is recommended in most cases because it is robust and has great support for validations.
+
+Example:
+
+```tsx
+const formik = useFormik({
+    initialValues: {
+        firstName: ''
+    },
+    onSubmit: (values) => console.log(values.firstName)
+});
+
+return (
+    <Form formik={formik}>
+        <TextField name="firstName" label="First Name" />
+    </Form>
+);
+```
+
+Notice it is way simpler to build the UI using Formik. We just need to pass the `formik` prop to the Sous Chef `Form` component, then it will match the Formik state with the form fields by the `name` prop.
+So, in this case, the `name="firstName"` will be matched to the `firstName` value in formik. The same applies to all other Sous Chef form fields.
+
+### Form validation
+
+For form validation, we recommend using `Formik` with `Yup`.
+
+Example:
+
+```tsx
+import { useFormik } from 'formik';
+import * as Yup from 'yup';
+
+const schema = Yup.object().shape({
+    firstName: Yup.string()
+        .min(2, 'Too Short!')
+        .max(50, 'Too Long!')
+        .required('Required'),
+    lastName: Yup.string()
+        .min(2, 'Too Short!')
+        .max(50, 'Too Long!')
+        .required('Required'),
+    email: Yup.string().email('Invalid email').required('Required'),
+    birthdate: Yup.date().required('Required')
+});
+
+const formik: any = useFormik({
+    initialValues: {
+        firstName: '',
+        lastName: '',
+        email: '',
+        birthdate: null
+    },
+    validationSchema: schema,
+    onSubmit: (submittedValues) => action('onSubmit')(submittedValues)
+});
+
+return (
+    <Form formik={formik}>
+        <FormRow>
+            <TextField name="firstName" label="First Name" />
+            <TextField name="lastName" label="Last Name" />
+        </FormRow>
+        <TextField name="email" label="Email" />
+        <DateField name="birthdate" label="birthdate" />
+        <FormFooter
+            actions={{
+                primary: <Button disabled={!formik.isValid}>Save</Button>
+            }}
+        />
+    </Form>
+);
+```
+
+Notice that in this example, we define the validation schema with `Yup`, then send it to `formik` through `validationSchema`. If there is any error, it will display automatically in the form field WITHOUT the need to pass the `error` prop.
+Also, you can make use of `formik.isValid` and `formik.touched`, in this case the `formik.isValid` was used in the submit button.
+
+## Data Tables
+
+Data tables can go from simple tables to more complex use-cases with pagination and editable cells.
+
+### Simple tables
+
+Example of simple table:
+
+```tsx
+const ITEMS = [
+    {
+        date: 'Jun 22, 2019',
+        employeeName: 'Steve Lawrence',
+        hours: 15
+    },
+    {
+        date: 'Jan 15, 2020',
+        employeeName: 'Alex Andrade',
+        hours: 8
+    }
+];
+
+<DataTable items={ITEMS} />;
+```
+
+However, in most cases, you will need columns:
+
+Example using columns:
+
+```tsx
+const COLUMNS = [
+    {
+        label: 'Employee Name',
+        name: 'employeeName'
+    },
+    {
+        label: 'Date',
+        name: 'date'
+    },
+    {
+        label: 'Hours',
+        name: 'hours',
+        isRightAligned: true
+    }
+];
+
+const ITEMS = [
+    {
+        date: 'Jun 22, 2019',
+        employeeName: 'Steve Lawrence',
+        hours: 15
+    },
+    {
+        date: 'Jan 15, 2020',
+        employeeName: 'Alex Andrade',
+        hours: <Text color="red">8</Text>
+    }
+];
+
+<DataTable columns={COLUMNS} items={ITEMS} />;
+```
+
+Notice in this example, when there is no use of the `itemComponent` prop, the cells will be matched using the column `name` and the object property in each `ITEMS` element.
+Also notice, the `Hours` column is right-aligned. That means all the SORTING, ALIGNMENT AND COLUMN SIZE is done by the columns.
+
+### Custom item elements
+
+It is recommended to use the `itemComponent` prop to fully customize how each row and cell will look:
+
+```tsx
+import { DataTable, DataTableRow, Inline, Avatar } from '@7shifts/sous-chef';
+import type { DataTableCustomComponent } from '@7shifts/sous-chef';
+
+const COLUMNS = [
+    {
+        name: 'employeeName',
+        label: 'Employee',
+        size: 2
+    },
+    {
+        name: 'date',
+        label: 'Date'
+    },
+    {
+        name: 'hours',
+        label: 'Hours'
+    }
+];
+
+type Item = {
+    employeeName: string;
+    date: string;
+    hours: number;
+    image: string;
+};
+
+const ITEMS: Item[] = [
+    {
+        employeeName: 'Steve Lawrence',
+        date: 'Jun 22, 2019',
+        hours: 15,
+        image: IMAGE_URL
+    },
+    {
+        employeeName: 'Alex Andrade',
+        date: 'Jan 15, 2020',
+        hours: 8,
+        image: 'https://cdn.sanity.io/images/6she4yvt/production/d013e0d710594033d7396bc39b6b58f974a718d3-376x376.png?w=70&h=70&q=75&fit=max&auto=format&dpr=2'
+    }
+];
+
+const CustomItemComponent = (props: DataTableCustomComponent<Item>) => {
+    const { employeeName, date, hours, image } = props.item;
+    return (
+        <DataTableRow>
+            <DataTableCell columnIndex={0}>
+                <Inline alignItems="center">
+                    <Avatar url={image} />
+                    {employeeName}
+                </Inline>
+            </DataTableCell>
+            <DataTableCell columnIndex={1}>{date}</DataTableCell>
+            <DataTableCell columnIndex={2}>{hours}</DataTableCell>
+        </DataTableRow>
+    );
+};
+
+export default function App() {
+    return (
+        <DataTable
+            columns={COLUMNS}
+            items={ITEMS}
+            itemComponent={CustomItemComponent}
+        />
+    );
+}
+```
+
+In the example above, the `itemComponent` prop is passed as a React component. The `CustomItemComponent` uses the `DataTableCustomComponent` type to create the component properly.
+With this approach, you need to construct the row and cells using `DataTableRow` and `DataTableCell`. `DataTableCell` requires the `columnIndex` prop, which maps it to the proper column.
+In this case, the item property name no longer needs to match the `COLUMNS` item name.
+
+### Pagination
+
+In order to use pagination, you need to specify the `onPreviousClick` and `onNextClick` handlers. Optionally, you can define whether there is a next or previous page with `hasNext` or `hasPrevious`.
+With this, it will render the Pagination Controls at the bottom of the table.
+
+```tsx
+const COLUMNS = [
+    {
+        label: 'Employee',
+        name: 'employeeName'
+    },
+    {
+        label: 'Date',
+        name: 'date'
+    },
+    {
+        label: 'Hours',
+        name: 'hours'
+    }
+];
+
+const ITEMS = [
+    {
+        date: 'Jun 22, 2019',
+        employeeName: 'Steve Lawrence',
+        hours: 15
+    },
+    {
+        date: 'Jan 15, 2020',
+        employeeName: 'Alex Andrade',
+        hours: 8
+    }
+];
+
+<DataTable
+    columns={COLUMNS}
+    items={ITEMS}
+    hasNext={true}
+    hasPrevious={false}
+    onNextClick={() => console.log('Fetch next page')}
+    onPreviousClick={() => console.log('Fetch previous page')}
+/>;
+```