[docs] Improve feedback precision

docs/packages/markdown/parseMarkdown.js

@@ -249,6 +249,9 @@ function createRender(context) {
         `<a aria-labelledby="${hash}" class="anchor-link-style" href="#${hash}" tabindex="-1">`,
         '<svg><use xlink:href="#anchor-link-icon" /></svg>',
         '</a>',
+        `<button class="comment-link-style" data-feedback-hash="${hash}">`,
+        '<svg><use xlink:href="#comment-link-icon" /></svg>',
+        `</button>`,
         `</h${level}>`,
       ].join('');
     };
@@ -458,6 +461,11 @@ ${headers.components
   <symbol id="anchor-link-icon" viewBox="0 0 16 16">
     <path d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z" />
   </symbol>
+</svg>`);
+      rendered.unshift(`<svg style="display: none;" xmlns="http://www.w3.org/2000/svg">
+<symbol id="comment-link-icon" viewBox="0 0 24 24">
+  <path d="M20 2H4c-1.1 0-1.99.9-1.99 2L2 22l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zM6 14v-2.47l6.88-6.88c.2-.2.51-.2.71 0l1.77 1.77c.2.2.2.51 0 .71L8.47 14H6zm12 0h-7.5l2-2H18v2z" />
+</symbol>
 </svg>`);
 
       docs[userLanguage] = {

docs/src/modules/components/AppLayoutDocs.js

@@ -30,6 +30,13 @@ const Main = styled('main', {
   [theme.breakpoints.up('lg')]: {
     width: 'calc(100% - var(--MuiDocs-navDrawer-width))',
   },
+  '& .markdown-body': {
+    '& h1, & h2, & h3, & h4': {
+      '& .comment-link-style': {
+        display: 'inline-block',
+      },
+    },
+  },
 }));
 
 const StyledAppContainer = styled(AppContainer, {
@@ -130,7 +137,7 @@ function AppLayoutDocs(props) {
             <ActionsDiv>{location && <EditPage markdownLocation={location} />}</ActionsDiv>
             {children}
             <NoSsr>
-              <AppLayoutDocsFooter />
+              <AppLayoutDocsFooter tableOfContents={toc} />
             </NoSsr>
           </StyledAppContainer>
         </Main>

docs/src/modules/components/AppLayoutDocsFooter.js

@@ -1,5 +1,6 @@
 /* eslint-disable no-restricted-globals */
 import * as React from 'react';
+import PropTypes from 'prop-types';
 import { styled } from '@mui/material/styles';
 import DialogActions from '@mui/material/DialogActions';
 import TextField from '@mui/material/TextField';
@@ -10,6 +11,7 @@ import Grid from '@mui/material/Grid';
 import Typography from '@mui/material/Typography';
 import Tooltip from '@mui/material/Tooltip';
 import IconButton from '@mui/material/IconButton';
+import MenuItem from '@mui/material/MenuItem';
 import ThumbUpIcon from '@mui/icons-material/ThumbUpAlt';
 import ThumbDownIcon from '@mui/icons-material/ThumbDownAlt';
 import ChevronRightIcon from '@mui/icons-material/ChevronRight';
@@ -109,10 +111,10 @@ async function postFeedback(data) {
 }
 
 async function postFeedbackOnSlack(data) {
-  const { rating, comment } = data;
+  const { rating, comment, commentedSection } = data;
 
   if (!comment || comment.length < 10) {
-    return;
+    return 'ignored';
   }
 
   /**
@@ -158,9 +160,11 @@ async function postFeedbackOnSlack(data) {
   */
 
   const simpleSlackMessage = [
-    `New comment ${rating > 0 ? '👍' : '👎'}`,
+    `New comment ${rating === 1 ? '👍' : ''}${rating === 0 ? '👎' : ''}`,
     `>${comment.split('\n').join('\n>')}`,
-    `sent from ${window.location.href}`,
+    `sent from ${window.location.href}${commentedSection.hash ? `#${commentedSection.hash}` : ''}${
+      commentedSection.text ? ` (section ${commentedSection.text})` : ''
+    }`,
   ].join('\n\n');
 
   try {
@@ -169,8 +173,10 @@ async function postFeedbackOnSlack(data) {
       headers: { 'content-type': 'application/x-www-form-urlencoded' },
       body: JSON.stringify({ text: simpleSlackMessage }),
     });
+    return 'sent';
   } catch (error) {
     console.error(error);
+    return null;
   }
 }
 
@@ -191,7 +197,7 @@ async function getUserFeedback(id) {
   }
 }
 
-async function submitFeedback(page, rating, comment, language) {
+async function submitFeedback(page, rating, comment, language, commentedSection) {
   const data = {
     id: getCookie('feedbackId'),
     page,
@@ -201,18 +207,22 @@ async function submitFeedback(page, rating, comment, language) {
     language,
   };
 
-  await postFeedbackOnSlack(data);
-  const result = await postFeedback(data);
-  if (result) {
-    document.cookie = `feedbackId=${result.id};path=/;max-age=31536000`;
-    setTimeout(async () => {
-      const userFeedback = await getUserFeedback(result.id);
-      if (userFeedback) {
-        document.cookie = `feedback=${JSON.stringify(userFeedback)};path=/;max-age=31536000`;
-      }
-    });
+  const resultSlack = await postFeedbackOnSlack({ ...data, commentedSection });
+  if (rating !== undefined) {
+    const resultVote = await postFeedback(data);
+    if (resultVote) {
+      document.cookie = `feedbackId=${resultVote.id};path=/;max-age=31536000`;
+      setTimeout(async () => {
+        const userFeedback = await getUserFeedback(resultVote.id);
+        if (userFeedback) {
+          document.cookie = `feedback=${JSON.stringify(userFeedback)};path=/;max-age=31536000`;
+        }
+      });
+    }
+    return resultSlack && resultVote;
   }
-  return result;
+
+  return resultSlack;
 }
 
 function getCurrentRating(pathname) {
@@ -242,19 +252,36 @@ function usePageNeighbours() {
   return { prevPage, nextPage };
 }
 
-export default function AppLayoutDocsFooter() {
+const EMPTY_SECTION = { hash: '', text: '' };
+
+export default function AppLayoutDocsFooter(props) {
+  const { tableOfContents = [] } = props;
+
   const t = useTranslate();
   const userLanguage = useUserLanguage();
   const { activePage } = React.useContext(PageContext);
   const [rating, setRating] = React.useState();
   const [comment, setComment] = React.useState('');
-  const [commentOpen, setCommentOpen] = React.useState(false);
   const [snackbarOpen, setSnackbarOpen] = React.useState(false);
   const [snackbarMessage, setSnackbarMessage] = React.useState(false);
   const inputRef = React.useRef();
+  const [commentOpen, setCommentOpen] = React.useState(false);
+  const [commentedSection, setCommentedSection] = React.useState(EMPTY_SECTION);
 
   const { nextPage, prevPage } = usePageNeighbours();
 
+  const sectionOptions = React.useMemo(
+    () =>
+      tableOfContents.flatMap((section) => [
+        {
+          hash: section.hash,
+          text: section.text,
+        },
+        ...section.children.map(({ hash, text }) => ({ hash, text })),
+      ]),
+    [tableOfContents],
+  );
+
   const setCurrentRatingFromCookie = React.useCallback(() => {
     if (activePage !== null) {
       setRating(getCurrentRating(activePage.pathname));
@@ -270,7 +297,13 @@ export default function AppLayoutDocsFooter() {
       setSnackbarMessage(t('feedbackFailed'));
     }
 
-    const result = await submitFeedback(activePage.pathname, rating, comment, userLanguage);
+    const result = await submitFeedback(
+      activePage.pathname,
+      rating,
+      comment,
+      userLanguage,
+      commentedSection,
+    );
     if (result) {
       setSnackbarMessage(t('feedbackSubmitted'));
     } else {
@@ -291,6 +324,12 @@ export default function AppLayoutDocsFooter() {
     setComment(event.target.value);
   };
 
+  const handleChangeSection = (event) => {
+    const section =
+      sectionOptions.find((item) => item.hash === event.target.value) || EMPTY_SECTION;
+    setCommentedSection(section);
+  };
+
   const handleSubmitComment = (event) => {
     event.preventDefault();
     setCommentOpen(false);
@@ -310,6 +349,24 @@ export default function AppLayoutDocsFooter() {
     setSnackbarOpen(false);
   };
 
+  React.useEffect(() => {
+    const eventListener = (event) => {
+      const feedbackHash = event.target.getAttribute('data-feedback-hash');
+      if (feedbackHash) {
+        const section = sectionOptions.find((item) => item.hash === feedbackHash) || EMPTY_SECTION;
+        setCommentOpen(true);
+        setCommentedSection(section);
+        if (inputRef.current) {
+          inputRef.current.focus();
+        }
+      }
+    };
+    document.addEventListener('click', eventListener);
+    return () => {
+      document.removeEventListener('click', eventListener);
+    };
+  }, [sectionOptions]);
+
   const hidePagePagination = activePage === null || activePage.ordered === false;
 
   return (
@@ -389,6 +446,24 @@ export default function AppLayoutDocsFooter() {
               <Typography id="feedback-description" color="text.secondary" gutterBottom>
                 {rating === 1 ? t('feedbackMessageUp') : t('feedbackMessageDown')}
               </Typography>
+              <TextField
+                select
+                size="small"
+                margin="dense"
+                name="commentedSection"
+                fullWidth
+                value={commentedSection?.hash || ''}
+                onChange={handleChangeSection}
+                inputProps={{
+                  'aria-label': t('feedbackSectionLabel'),
+                }}
+                placeholder={t('feedbackSectionPlaceholder')}
+              >
+                <MenuItem value="">{t('feedbackNoSectionSelected')}</MenuItem>
+                {sectionOptions.map((section) => (
+                  <MenuItem value={section.hash}>{section.text}</MenuItem>
+                ))}
+              </TextField>
               <TextField
                 multiline
                 margin="dense"
@@ -420,3 +495,7 @@ export default function AppLayoutDocsFooter() {
     </React.Fragment>
   );
 }
+
+AppLayoutDocsFooter.propTypes = {
+  tableOfContents: PropTypes.array,
+};

docs/src/modules/components/MarkdownElement.js

@@ -140,6 +140,33 @@ const Root = styled('div')(({ theme }) => ({
         fill: 'currentColor',
       },
     },
+    '& .comment-link-style': {
+      display: 'none',
+      verticalAlign: 'middle',
+      textAlign: 'center',
+      lineHeight: '21.5px',
+      marginLeft: 10,
+      height: '26px',
+      width: '26px',
+      background: theme.palette.mode === 'dark' ? alpha(blue[800], 0.3) : theme.palette.primary[50],
+      border: '1px solid',
+      borderColor: theme.palette.mode === 'dark' ? blueDark[500] : theme.palette.grey[200],
+      borderRadius: 8,
+      color: theme.palette.text.secondary,
+      float: 'right',
+      marginRight: '16px',
+      cursor: 'pointer',
+      '&:hover': {
+        color: theme.palette.text.primary,
+      },
+      '& svg': {
+        verticalAlign: 'middle',
+        width: '0.875rem',
+        height: '0.875rem',
+        fill: 'currentColor',
+        pointerEvents: 'none',
+      },
+    },
   },
   '& h1 code': {
     fontWeight: theme.typography.fontWeightSemiBold,

docs/translations/translations.json

@@ -66,6 +66,9 @@
   "emoojiWarning": "Warning",
   "expandAll": "Expand all",
   "feedbackCommentLabel": "Comment",
+  "feedbackSectionLabel": "Section concerned by the comment",
+  "feedbackSectionPlaceholder": "Comment about the section ...",
+  "feedbackNoSectionSelected": "The all page",
   "feedbackFailed": "Couldn't submit feedback. Please try again later.",
   "feedbackMessage": "Was this page helpful?",
   "feedbackMessageDown": "Please let us know what we could do to improve this page.",