Merge pull request #14295 from overleaf/mj-table-gen-help-modal

[visual] Add help modal to table generator

GitOrigin-RevId: 48827734d2aa356f4547f1e6638381a1dd96b7e6

services/web/frontend/js/features/source-editor/components/table-generator/contexts/tabular-context.tsx

@@ -1,13 +1,30 @@
-import { FC, RefObject, createContext, useContext, useRef } from 'react'
+import {
+  FC,
+  RefObject,
+  createContext,
+  useCallback,
+  useContext,
+  useRef,
+  useState,
+} from 'react'
 
 const TabularContext = createContext<
-  { ref: RefObject<HTMLDivElement> } | undefined
+  | {
+      ref: RefObject<HTMLDivElement>
+      showHelp: () => void
+      hideHelp: () => void
+      helpShown: boolean
+    }
+  | undefined
 >(undefined)
 
 export const TabularProvider: FC = ({ children }) => {
   const ref = useRef<HTMLDivElement>(null)
+  const [helpShown, setHelpShown] = useState(false)
+  const showHelp = useCallback(() => setHelpShown(true), [])
+  const hideHelp = useCallback(() => setHelpShown(false), [])
   return (
-    <TabularContext.Provider value={{ ref }}>
+    <TabularContext.Provider value={{ ref, helpShown, showHelp, hideHelp }}>
       {children}
     </TabularContext.Provider>
   )

services/web/frontend/js/features/source-editor/components/table-generator/help-modal.tsx

@@ -0,0 +1,86 @@
+import { Button, Modal } from 'react-bootstrap'
+import AccessibleModal from '../../../../shared/components/accessible-modal'
+import { useTabularContext } from './contexts/tabular-context'
+
+export const TableGeneratorHelpModal = () => {
+  const { helpShown, hideHelp } = useTabularContext()
+  if (!helpShown) return null
+
+  return (
+    <AccessibleModal
+      show={helpShown}
+      onHide={hideHelp}
+      className="table-generator-help-modal"
+    >
+      <Modal.Header closeButton>
+        <Modal.Title>Help</Modal.Title>
+      </Modal.Header>
+      <Modal.Body>
+        <p>
+          This tool helps you insert simple tables into your project without
+          writing LaTeX code. This tool is new, so please{' '}
+          <a
+            href="https://forms.gle/ri3fzV1oQDAjmfmD7"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            give us feedback
+          </a>{' '}
+          and look out for additional functionality coming soon.
+        </p>
+        <b>How it works</b>
+        <p>
+          You’ll get the best results from using this tool in the{' '}
+          <b>Visual Editor</b>, although you can still use it to insert tables
+          in the <b>Code Editor</b>. Once you’ve selected the number of rows and
+          columns you need, the table will appear in your document and you can
+          double click in a cell to add contents to it.
+        </p>
+        <b>Customizing tables</b>
+        <p>
+          If you need to customize your table further, you can. Using LaTeX
+          code, you can change anything from table styles and border styles to
+          colors and column widths.{' '}
+          <a
+            href="https://www.overleaf.com/learn/latex/Tables"
+            target="_blank"
+            rel="noopener"
+          >
+            Read our guide
+          </a>{' '}
+          to using tables in LaTeX to help you get started.
+        </p>
+        <b>Changing the position of your table</b>
+        <p>
+          LaTeX places tables according to a special algorithm. You can use
+          “placement parameters” to influence the position of the table.{' '}
+          <a
+            href="https://www.overleaf.com/learn/latex/Positioning_images_and_tables"
+            target="_blank"
+            rel="noopener"
+          >
+            This article
+          </a>{' '}
+          explains how to do this.
+        </p>
+        <b>Understanding labels</b>
+        <p>
+          Labels help you to reference your tables throughout your document
+          easily. To reference a table within the text, reference the label
+          using the <code>\ref&#123;...&#125;</code> command. This makes it easy
+          to reference tables without manually remembering the table numbering.{' '}
+          <a
+            href="https://www.overleaf.com/learn/latex/Inserting_Images#Labels_and_cross-references"
+            target="_blank"
+            rel="noopener"
+          >
+            Read about labels and cross-references.
+          </a>
+        </p>
+      </Modal.Body>
+      <Modal.Footer>
+        <Button onClick={hideHelp}>Close</Button>
+      </Modal.Footer>
+    </AccessibleModal>
+  )
+}

services/web/frontend/js/features/source-editor/components/table-generator/tabular.tsx

@@ -20,6 +20,8 @@ import { TableProvider } from './contexts/table-context'
 import { TabularProvider, useTabularContext } from './contexts/tabular-context'
 import Icon from '../../../../shared/components/icon'
 import { BorderTheme } from './toolbar/commands'
+import { TableGeneratorHelpModal } from './help-modal'
+import { SplitTestProvider } from '../../../../shared/context/split-test-context'
 
 export type ColumnDefinition = {
   alignment: 'left' | 'center' | 'right' | 'paragraph'
@@ -190,22 +192,25 @@ export const Tabular: FC<{
         <TableRenderingError view={view} codePosition={tabularNode.from} />
       )}
     >
-      <CodeMirrorViewContextProvider value={view}>
-        <TabularProvider>
-          <TableProvider
-            tabularNode={tabularNode}
-            tableData={parsedTableData}
-            tableNode={tableNode}
-            view={view}
-          >
-            <SelectionContextProvider>
-              <EditingContextProvider>
-                <TabularWrapper />
-              </EditingContextProvider>
-            </SelectionContextProvider>
-          </TableProvider>
-        </TabularProvider>
-      </CodeMirrorViewContextProvider>
+      <SplitTestProvider>
+        <CodeMirrorViewContextProvider value={view}>
+          <TabularProvider>
+            <TableProvider
+              tabularNode={tabularNode}
+              tableData={parsedTableData}
+              tableNode={tableNode}
+              view={view}
+            >
+              <SelectionContextProvider>
+                <EditingContextProvider>
+                  <TabularWrapper />
+                </EditingContextProvider>
+              </SelectionContextProvider>
+            </TableProvider>
+            <TableGeneratorHelpModal />
+          </TabularProvider>
+        </CodeMirrorViewContextProvider>
+      </SplitTestProvider>
     </ErrorBoundary>
   )
 }
@@ -216,7 +221,10 @@ const TabularWrapper: FC = () => {
   const { ref } = useTabularContext()
   useEffect(() => {
     const listener: (event: MouseEvent) => void = event => {
-      if (!ref.current?.contains(event.target as Node)) {
+      if (
+        !ref.current?.contains(event.target as Node) &&
+        !(event.target as HTMLElement).closest('.table-generator-help-modal')
+      ) {
         if (selection) {
           setSelection(null)
         }

services/web/frontend/js/features/source-editor/components/table-generator/toolbar/toolbar.tsx

@@ -19,6 +19,8 @@ import {
 } from './commands'
 import { useCodeMirrorViewContext } from '../../codemirror-editor'
 import { useTableContext } from '../contexts/table-context'
+import { useTabularContext } from '../contexts/tabular-context'
+import SplitTestBadge from '../../../../../shared/components/split-test-badge'
 
 const borderThemeLabel = (theme: BorderTheme | null) => {
   switch (theme) {
@@ -36,6 +38,7 @@ export const Toolbar = memo(function Toolbar() {
   const view = useCodeMirrorViewContext()
   const { positions, rowSeparators, cellSeparators, tableEnvironment, table } =
     useTableContext()
+  const { showHelp } = useTabularContext()
 
   const borderDropdownLabel = useMemo(
     () => borderThemeLabel(table.getBorderTheme()),
@@ -319,6 +322,18 @@ export const Toolbar = memo(function Toolbar() {
             view.focus()
           }}
         />
+        <ToolbarButton
+          icon="help"
+          id="table-generator-show-help"
+          label="Help"
+          command={showHelp}
+        />
+        <div className="toolbar-beta-badge">
+          <SplitTestBadge
+            displayOnVariants={['enabled']}
+            splitTestName="table-generator"
+          />
+        </div>
       </div>
     </div>
   )

services/web/frontend/js/features/source-editor/extensions/visual/table-generator.ts

@@ -252,6 +252,10 @@ export const tableGeneratorTheme = EditorView.baseTheme({
     },
   },
 
+  '.toolbar-beta-badge': {
+    padding: '0 4px 2px 12px',
+  },
+
   '.table-generator-button-group': {
     display: 'inline-flex',
     'align-items': 'center',