Increase documentation discoverability (#751)

CartoDB · Jul 28, 2023 · d287f24 · d287f24
1 parent 23b9ce5
commit d287f24
Show file tree

Hide file tree

Showing 27 changed files with 841 additions and 127 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## Not released
 
+- Increase documentation discoverability [#751](https://github.com/CartoDB/carto-react/pull/751)
+
 ## 2.2
 
 ### 2.2.2 (2023-07-26)

diff --git a/UPGRADE.md b/UPGRADE.md
@@ -94,7 +94,7 @@ For external use: `Open Sans` and `Montserrat` families have been replaced by `I
 
 ### Deleted colors
 
-Some keys have been removed from [color palette](https://github.com/CartoDB/carto-react/tree/master/packages/react-ui/src/theme) due they are unused:
+Some keys have been removed from [color palette](https://github.com/CartoDB/carto-react/blob/master/packages/react-ui/src/theme/sections/palette.js) due they are unused:
 
 - activatedOpacity
 - hoverOpacity
@@ -139,6 +139,44 @@ We have a new component for building data structures within Tooltips, `TooltipDa
 
 # Components
 
+## Good practices
+
+### ListItem
+
+In order to be interactive, you need to use `MenuItem` component, or use `ListItemButton`instead.
+
+```
+<List>
+  <ListItemButton>
+    <ListItemIcon>
+      <Icon />
+    </ListItemIcon>
+    <ListItemText primary="List item text" />
+  </ListItemButton>
+<List>
+```
+
+```
+<MenuList>
+  <MenuItem>
+    <ListItemIcon>
+      <Icon />
+    </ListItemIcon>
+    <ListItemText primary="List item text" />
+  </MenuItem>
+<MenuList>
+```
+
+To render a link:
+
+```
+<ListItemButton component="a">
+  <ListItemText primary="List item text" />
+</ListItemButton>
+```
+
+Note that `<ListItem button />` is deprecated.
+
 ## Mui components replacement
 
 These components should be imported from carto-react library instead of Mui, as they replace the Mui components extending their functionality to meet with design criteria.

diff --git a/packages/react-ui/storybook/stories/atoms/Button.stories.js b/packages/react-ui/storybook/stories/atoms/Button.stories.js
@@ -4,6 +4,7 @@ import { Add, Close } from '@mui/icons-material';
 import LoadingButton from '@mui/lab/LoadingButton';
 import Typography from '../../../src/components/atoms/Typography';
 import Button from '../../../src/components/atoms/Button';
+import { DocContainer, DocHighlight, DocLink } from '../../utils/storyStyles';
 
 const options = {
   title: 'Atoms/Button',
@@ -203,9 +204,35 @@ const BehaviorTemplate = ({ label, icon, ...rest }) => {
   );
 };
 
+const DocTemplate = () => {
+  return (
+    <DocContainer severity='warning'>
+      We have our own
+      <DocLink href='https://github.com/CartoDB/carto-react/blob/master/packages/react-ui/src/components/atoms/Button.js'>
+        Button
+      </DocLink>
+      component that uses <i>Mui Button</i> and wraps its children in a <i>Typography</i>{' '}
+      component to meet with the designed behavior (text overflow case).
+      <Typography mt={2}>
+        So, instead of Mui Button, you should use this one:
+        <DocHighlight component='span'>react-ui/src/components/atoms/Button</DocHighlight>
+      </Typography>
+      <Typography mt={2}>
+        For external use:
+        <DocHighlight component='span'>
+          {'import { Button } from "@carto/react-ui";'}
+        </DocHighlight>
+        .
+      </Typography>
+    </DocContainer>
+  );
+};
+
 export const Playground = PlaygroundTemplate.bind({});
 Playground.args = { label: 'Button' };
 
+export const Guide = DocTemplate.bind({});
+
 export const Contained = VariantTemplate.bind({});
 Contained.args = { variant: 'contained' };
 

diff --git a/packages/react-ui/storybook/stories/atoms/LabelWithIndicator.stories.js b/packages/react-ui/storybook/stories/atoms/LabelWithIndicator.stories.js
@@ -8,7 +8,8 @@ import {
   FormLabel,
   FormGroup,
   FormControlLabel,
-  Checkbox
+  Checkbox,
+  MenuItem
 } from '@mui/material';
 import PasswordField from '../../../src/components/atoms/PasswordField';
 import SelectField from '../../../src/components/atoms/SelectField';
@@ -44,21 +45,6 @@ const options = {
 };
 export default options;
 
-const menuItems = [
-  {
-    label: 'Ten: super large text with overflow',
-    value: '10'
-  },
-  {
-    label: 'Twenty',
-    value: '20'
-  },
-  {
-    label: 'Thirty',
-    value: '30'
-  }
-];
-
 const top100Films = [
   { label: 'The Shawshank Redemption', year: 1994 },
   { label: 'The Godfather', year: 1972 },
@@ -150,32 +136,76 @@ const UseCasesTemplate = ({ label, ...rest }) => {
                 <SelectField
                   label={<LabelWithIndicator {...rest} label={label} />}
                   placeholder='Placeholder text'
-                  items={menuItems}
-                />
+                  onChange={() => void 0}
+                  value={[]}
+                >
+                  {[...Array(5)].map((item, index) => {
+                    const itemText = `Item ${index + 1}`;
+
+                    return (
+                      <MenuItem key={index} value={itemText}>
+                        {itemText}
+                      </MenuItem>
+                    );
+                  })}
+                </SelectField>
               </Grid>
               <Grid item xs={3}>
                 <SelectField
                   label={label}
                   required
                   placeholder='Placeholder text'
-                  items={menuItems}
-                />
+                  onChange={() => void 0}
+                  value={[]}
+                >
+                  {[...Array(5)].map((item, index) => {
+                    const itemText = `Item ${index + 1}`;
+
+                    return (
+                      <MenuItem key={index} value={itemText}>
+                        {itemText}
+                      </MenuItem>
+                    );
+                  })}
+                </SelectField>
               </Grid>
               <Grid item xs={3}>
                 <SelectField
                   label={<LabelWithIndicator {...rest} label={label} />}
                   placeholder='Placeholder text'
-                  items={menuItems}
+                  onChange={() => void 0}
+                  value={[]}
                   error
-                />
+                >
+                  {[...Array(5)].map((item, index) => {
+                    const itemText = `Item ${index + 1}`;
+
+                    return (
+                      <MenuItem key={index} value={itemText}>
+                        {itemText}
+                      </MenuItem>
+                    );
+                  })}
+                </SelectField>
               </Grid>
               <Grid item xs={3}>
                 <SelectField
                   label={<LabelWithIndicator {...rest} label={label} />}
                   placeholder='Placeholder text'
-                  items={menuItems}
+                  onChange={() => void 0}
+                  value={[]}
                   disabled
-                />
+                >
+                  {[...Array(5)].map((item, index) => {
+                    const itemText = `Item ${index + 1}`;
+
+                    return (
+                      <MenuItem key={index} value={itemText}>
+                        {itemText}
+                      </MenuItem>
+                    );
+                  })}
+                </SelectField>
               </Grid>
             </Grid>
           </Grid>

diff --git a/packages/react-ui/storybook/stories/atoms/SelectField.stories.js b/packages/react-ui/storybook/stories/atoms/SelectField.stories.js
@@ -1,8 +1,9 @@
 import React, { useState } from 'react';
-import { FormControl, Grid, InputLabel, Link, MenuItem, TextField } from '@mui/material';
+import { FormControl, Grid, InputLabel, MenuItem, TextField } from '@mui/material';
 import Typography from '../../../src/components/atoms/Typography';
 import SelectField from '../../../src/components/atoms/SelectField';
-import { Container, Label } from '../../utils/storyStyles';
+import { Container, DocContainer, DocLink, Label } from '../../utils/storyStyles';
+import Button from '../../../src/components/atoms/Button';
 
 const options = {
   title: 'Atoms/Select Field',
@@ -476,13 +477,25 @@ const MultipleTemplate = ({
   ...rest
 }) => {
   return (
-    <Typography variant='subtitle1'>
-      Check{' '}
-      <Link href='/?path=/docs/atoms-multiple-select-field--playground'>
+    <DocContainer
+      severity='warning'
+      action={
+        <Button
+          color='inherit'
+          variant='outlined'
+          size='small'
+          href='/?path=/docs/atoms-multiple-select-field--playground'
+        >
+          MultipleSelectField story
+        </Button>
+      }
+    >
+      We have a specific
+      <DocLink href='https://github.com/CartoDB/carto-react/blob/master/packages/react-ui/src/components/atoms/MultipleSelectField.js'>
         MultipleSelectField
-      </Link>{' '}
-      component documentation
-    </Typography>
+      </DocLink>
+      component to handle this functionality, check the associated story.
+    </DocContainer>
   );
 };
 

diff --git a/packages/react-ui/storybook/stories/atoms/Text-field.stories.js b/packages/react-ui/storybook/stories/atoms/Text-field.stories.js
@@ -3,7 +3,7 @@ import { Grid, InputAdornment, TextField } from '@mui/material';
 import React from 'react';
 import PasswordField from '../../../src/components/atoms/PasswordField';
 import Typography from '../../../src/components/atoms/Typography';
-import { Container, Label } from '../../utils/storyStyles';
+import { Container, DocContainer, DocHighlight, Label } from '../../utils/storyStyles';
 
 const options = {
   title: 'Atoms/Text Field',
@@ -536,9 +536,20 @@ const PasswordFieldTemplate = ({
 }) => {
   return (
     <Grid container direction='column' spacing={6}>
+      <Grid item>
+        <DocContainer severity='warning'>
+          Use <DocHighlight component='span'>{'<PasswordField />'}</DocHighlight> instead
+          of
+          <DocHighlight component='span'>{'<TextField type="password" />'}</DocHighlight>
+          This component build the show / hide content logic on top of <i>
+            TextField
+          </i>{' '}
+          Mui component.
+        </DocContainer>
+      </Grid>
       <Grid item>
         <Container>
-          <Label variant='body2'>{'Default'}</Label>
+          <Label variant='body2'>{'TextField'}</Label>
           <TextField
             {...rest}
             label='Password'
@@ -551,7 +562,7 @@ const PasswordFieldTemplate = ({
       </Grid>
       <Grid item>
         <Container>
-          <Label variant='body2'>{'Custom component'}</Label>
+          <Label variant='body2'>{'PasswordField'}</Label>
           <PasswordField
             {...rest}
             label='Password'

diff --git a/packages/react-ui/storybook/stories/foundations/Borders.stories.js b/packages/react-ui/storybook/stories/foundations/Borders.stories.js
@@ -2,7 +2,7 @@ import React from 'react';
 import { Box, Grid } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
 import Typography from '../../../src/components/atoms/Typography';
-import { FilledContainer } from '../../utils/storyStyles';
+import { DocContainer, DocHighlight, FilledContainer } from '../../utils/storyStyles';
 
 const options = {
   title: 'Foundations/Borders',
@@ -60,6 +60,17 @@ const Template = () => {
   );
 };
 
+const DocTemplate = () => {
+  return (
+    <DocContainer severity='warning'>
+      Use is restringed to a few specific values, defined in the design system, which are:
+      <DocHighlight component='span'>0.5, 1, 1.5, 2</DocHighlight>
+    </DocContainer>
+  );
+};
+
 export const Playground = BorderBox.bind({});
 
+export const Guide = DocTemplate.bind({});
+
 export const BorderRadius = Template.bind({});