feat: improve query advise

Author: smeijer

src/components/App.js

@@ -1,40 +1,34 @@
-import React, { useState, useRef, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 import Editor from './Editor';
 import ElementInfo from './ElementInfo';
 import Header from './Header';
 import Footer from './Footer';
 import parser from '../parser';
 
 import { initialValues } from '../constants';
-import ensureArray from '../lib/ensureArray';
-import { AppContextProvider, useAppContext } from './Context';
+import { useAppContext } from './Context';
 import HtmlPreview from './HtmlPreview';
 
-let cycle = 0;
-
 function App() {
   const [html, setHtml] = useState(initialValues.html);
   const [js, setJs] = useState(initialValues.js);
 
-  const { htmlEditorRef, htmlPreviewRef, jsEditorRef } = useAppContext();
-
-  const [result, setResult] = useState({});
-  const [elements, setElements] = useState([]);
+  const {
+    htmlEditorRef,
+    htmlPreviewRef,
+    jsEditorRef,
+    parsed,
+    setParsed,
+  } = useAppContext();
 
   useEffect(() => {
     const parsed = parser.parse(htmlPreviewRef.current, js);
-    setResult(parsed);
-
-    const elements = ensureArray(parsed.code).filter(
-      (x) => x?.nodeType === Node.ELEMENT_NODE,
-    );
+    setParsed(parsed);
 
-    cycle++;
-    setElements(elements);
-    elements.forEach((el) => el.classList.add('highlight'));
+    parsed.targets?.forEach((el) => el.classList.add('highlight'));
 
     return () => {
-      elements.forEach((el) => el.classList.remove('highlight'));
+      parsed.targets?.forEach((el) => el.classList.remove('highlight'));
     };
   }, [html, js, htmlPreviewRef.current]);
 
@@ -65,17 +59,11 @@ function App() {
             />
             <div className="output">
               <span className="text-blue-600">&gt; </span>
-              {result.text || result.error || 'undefined'}
+              {parsed.text || parsed.error || 'undefined'}
             </div>
           </div>
 
-          <div>
-            <div>
-              {elements.map((x, idx) => (
-                <ElementInfo key={`${cycle}-${idx}`} element={x} />
-              ))}
-            </div>
-          </div>
+          <ElementInfo />
         </div>
       </div>
 

src/components/Context.js

@@ -1,15 +1,16 @@
-import React, { useContext, useRef } from 'react';
+import React, { useContext, useRef, useState } from 'react';
 
 export const AppContext = React.createContext();
 
 function AppContextProvider(props) {
   const jsEditorRef = useRef();
   const htmlEditorRef = useRef();
   const htmlPreviewRef = useRef();
+  const [parsed, setParsed] = useState({});
 
   return (
     <AppContext.Provider
-      value={{ jsEditorRef, htmlEditorRef, htmlPreviewRef }}
+      value={{ jsEditorRef, htmlEditorRef, htmlPreviewRef, parsed, setParsed }}
       {...props}
     />
   );

src/components/ElementInfo.js

@@ -1,47 +1,9 @@
 import React from 'react';
 import { getRole, computeAccessibleName } from 'dom-accessibility-api';
-import { links, messages } from '../constants';
-import SetLike from 'dom-accessibility-api/dist/polyfills/SetLike';
 import { useAppContext } from './Context';
+import QueryAdvise from './QueryAdvise';
 
-const colors = ['bg-blue-600', 'bg-yellow-600', 'bg-orange-600', 'bg-red-600'];
-
-const queries = [
-  { method: 'getByRole', level: 0 },
-  { method: 'getByLabelText', level: 0 },
-  { method: 'getByPlaceholderText', level: 0 },
-  { method: 'getByText', level: 0 },
-  { method: 'getByDisplayValue', level: 0 },
-
-  { method: 'getByAltText', level: 1 },
-  { method: 'getByTitle', level: 1 },
-
-  { method: 'getByTestId', level: 2 },
-
-  // 'container.querySelector'
-];
-
-function escape(val) {
-  return val.replace(/'/g, `\\'`);
-}
-
-function getExpression({ method, data }) {
-  const field = getFieldName(method);
-
-  if (method === 'getByRole' && data.role && data.name) {
-    return `screen.getByRole('${data.role}', { name: '${escape(data.name)}' })`;
-  }
-
-  if (data[field]) {
-    return `screen.${method}('${escape(data[field])}')`;
-  }
-
-  return '';
-}
-
-function getFieldName(method) {
-  return method[5].toLowerCase() + method.substr(6);
-}
+import { getExpression, getFieldName } from '../lib';
 
 function getData({ root, element }) {
   const type = element.getAttribute('type');
@@ -53,11 +15,10 @@ function getData({ root, element }) {
   const labelText = labelElem ? labelElem.innerText : null;
 
   return {
-    // input's require a type for the role
     role:
-      element.getAttribute('role') || (tagName === 'INPUT' && !type)
-        ? ''
-        : getRole(element),
+      element.getAttribute('role') ||
+      // input's require a type for the role
+      (tagName === 'INPUT' && type !== 'text' ? '' : getRole(element)),
     name: computeAccessibleName(element),
     tagName: tagName,
     type: type,
@@ -82,10 +43,12 @@ function Heading({ children }) {
 }
 
 function Field({ method, data }) {
-  const { jsEditorRef } = useAppContext();
+  const { jsEditorRef, parsed } = useAppContext();
 
+  const isActive = parsed.expression?.method === method;
   const field = getFieldName(method);
   const value = data[field];
+
   const handleClick = value
     ? () => {
         const expr = getExpression({ method, data });
@@ -95,7 +58,7 @@ function Field({ method, data }) {
 
   return (
     <div
-      className="text-xs field"
+      className={`text-xs field ${isActive ? 'active' : ''}`}
       data-clickable={!!handleClick}
       onClick={handleClick}
     >
@@ -107,53 +70,26 @@ function Field({ method, data }) {
   );
 }
 
-function getQueryAdvise(data) {
-  const query = queries.find(({ method }) => getExpression({ method, data }));
-  if (!query) {
-    return {
-      level: 3,
-      expression: 'container.querySelector(…)',
-      ...messages[3],
-    };
-  }
-  const expression = getExpression({ method: query.method, data });
-  return { expression, level: query.level, ...messages[query.level] };
-}
-
 // for inputs, the role will only work if there is also a type attribute
-function ElementInfo({ element }) {
-  const { htmlPreviewRef } = useAppContext();
-  const data = getData({ root: htmlPreviewRef.current, element });
-  const advise = getQueryAdvise(data);
+function ElementInfo() {
+  const { htmlPreviewRef, parsed } = useAppContext();
+  const element = parsed.target;
+
+  const data = element && getData({ root: htmlPreviewRef.current, element });
+
+  if (!data) {
+    return <div />;
+  }
 
   return (
     <div>
-      <div
-        className={[
-          'border text-white p-4 rounded mb-8',
-          colors[advise.level],
-        ].join(' ')}
-      >
-        <div className="font-bold text-xs mb-2">suggested query:</div>
-        {advise.expression && (
-          <div className="font-mono text-sm">&gt; {advise.expression}</div>
-        )}
-      </div>
+      <QueryAdvise data={data} />
 
-      {/*disabled for the time being*/}
-      {false && advise.description && (
-        <blockquote className="text-sm mb-4 italic">
-          <p className="font-bold text-xs mb-2">{advise.heading}:</p>
-          <p>{advise.description}</p>
-          <cite>
-            <a href={links.which_query.url}>Testing Library</a>
-          </cite>
-        </blockquote>
-      )}
+      <div className="my-6 border-b" />
 
       <div className="grid grid-cols-2 gap-4">
         <Section>
-          <Heading>Queries Accessible to Everyone</Heading>
+          <Heading>1. Queries Accessible to Everyone</Heading>
           <Field method="getByRole" data={data} />
           <Field method="getByLabelText" data={data} />
           <Field method="getByPlaceholderText" data={data} />
@@ -163,13 +99,13 @@ function ElementInfo({ element }) {
 
         <div className="space-y-8">
           <Section>
-            <Heading>Semantic Queries</Heading>
+            <Heading>2. Semantic Queries</Heading>
             <Field method="getByAltText" data={data} />
             <Field method="getByTitle" data={data} />
           </Section>
 
           <Section>
-            <Heading>TestId</Heading>
+            <Heading>3. TestId</Heading>
             <Field method="getByTestId" data={data} />
           </Section>
         </div>

src/components/Footer.js

@@ -54,4 +54,4 @@ function Footer() {
   );
 }
 
-export default Footer;
+export default React.memo(Footer);

src/components/QueryAdvise.js

@@ -0,0 +1,122 @@
+import React from 'react';
+import { messages, queries } from '../constants';
+import { useAppContext } from './Context';
+import { getExpression } from '../lib';
+
+const colors = ['bg-blue-600', 'bg-yellow-600', 'bg-orange-600', 'bg-red-600'];
+
+function getQueryAdvise(data) {
+  const query = queries.find(({ method }) => getExpression({ method, data }));
+  if (!query) {
+    return {
+      level: 3,
+      expression: 'container.querySelector(…)',
+      ...messages[3],
+    };
+  }
+  const expression = getExpression({ method: query.method, data });
+  return { expression, ...query, ...messages[query.level] };
+}
+
+function Code({ children }) {
+  return <span className="font-bold font-mono">{children}</span>;
+}
+
+function Quote({ heading, content, source, href }) {
+  return (
+    <blockquote className="text-sm mb-4 italic w-full">
+      <p className="font-bold text-xs mb-2">{heading}:</p>
+      <p>{content}</p>
+      <cite>
+        <a href={href}>{source}</a>
+      </cite>
+    </blockquote>
+  );
+}
+
+function QueryAdvise({ data }) {
+  const { parsed, jsEditorRef } = useAppContext();
+  const advise = getQueryAdvise(data);
+
+  const used = parsed?.expression || {};
+
+  const usingAdvisedMethod = advise.method === used.method;
+  const hasNameArg = data.name && used.args?.[1]?.includes('name');
+
+  const color = usingAdvisedMethod ? 'bg-green-600' : colors[advise.level];
+
+  const target = parsed.target || {};
+
+  let suggestion;
+
+  if (advise.level < used.level) {
+    suggestion = (
+      <p>
+        You're using <Code>{used.method}</Code>, which falls under{' '}
+        <Code>{messages[used.level].heading}</Code>. Upgrading to{' '}
+        <Code>{advise.method}</Code> is recommended.
+      </p>
+    );
+  } else if (advise.level === 0 && advise.method !== used.method) {
+    suggestion = (
+      <p>
+        Nice! <Code>{used.method}</Code> is a great selector! Using{' '}
+        <Code>{advise.method}</Code> would still be preferable though.
+      </p>
+    );
+  } else if (target.tagName === 'INPUT' && !target.getAttribute('type')) {
+    suggestion = (
+      <p>
+        You can unlock <Code>getByRole</Code> by adding the{' '}
+        <Code>type="text"</Code> attribute explicitly. Accessibility will
+        benefit from it.
+      </p>
+    );
+  } else if (
+    advise.level === 0 &&
+    advise.method === 'getByRole' &&
+    !data.name
+  ) {
+    suggestion = (
+      <p>
+        Awesome! This is great already! You could still make the query a bit
+        more specific by adding the name option. This would require to add some
+        markup though, as your element isn't named properly.
+      </p>
+    );
+  } else if (
+    advise.level === 0 &&
+    advise.method === 'getByRole' &&
+    data.name &&
+    !hasNameArg
+  ) {
+    suggestion = (
+      <p>
+        There is one thing though. You could make the query a bit more specific
+        by adding the name option.
+      </p>
+    );
+  } else {
+    suggestion = <p>This is great. Ship it!</p>;
+  }
+
+  const handleClick = () => {
+    jsEditorRef.current.setValue(advise.expression);
+  };
+
+  return (
+    <div className="space-y-4 text-sm">
+      <div className={['text-white p-4 rounded space-y-2', color].join(' ')}>
+        <div className="font-bold text-xs">suggested query</div>
+        {advise.expression && (
+          <div className="font-mono cursor-pointer" onClick={handleClick}>
+            &gt; {advise.expression}
+          </div>
+        )}
+      </div>
+      <div className="h-8">{suggestion}</div>
+    </div>
+  );
+}
+
+export default QueryAdvise;