@guardian/stand 0.0.0 → 0.0.3

package/README.md

@@ -0,0 +1,19 @@
+# Stand - a tools component library
+
+_Find what you need on the (news)stand!_
+
+Stand is component library for Guardian editorial tools. It is co-located within flexible-content as Composer is expected to be the main consumer of the UI components within Stand. But any editorial tool should be able to make use of the components as an npm package - `@guardian/stand` - and developers should feel comfortable contributing.
+
+## Setup
+
+- Run `./setup.sh` in the project root (flexible-content) directory to set up pnpm, install dependencies, and build the project.
+
+## Tasks
+
+- Run `pnpm install` to install dependencies.
+- Run `pnpm build` to build, this makes any changes available to flexible-frontend
+- Run `pnpm storybook` to run Storybook
+
+## Contributing
+
+See the [Contributing to Stand](./CONTRIBUTING.md) documentation

package/dist/byline/Byline.cjs

@@ -0,0 +1,375 @@
+'use strict';
+
+var jsxRuntime = require('@emotion/react/jsx-runtime');
+var prosemirrorInvisibles = require('@guardian/prosemirror-invisibles');
+var prosemirrorDropcursor = require('prosemirror-dropcursor');
+var prosemirrorHistory = require('prosemirror-history');
+var prosemirrorState = require('prosemirror-state');
+var prosemirrorView = require('prosemirror-view');
+var react = require('react');
+var lib = require('./lib.cjs');
+var placeholder = require('./placeholder.cjs');
+var plugins = require('./plugins.cjs');
+var Preview = require('./Preview.cjs');
+var schema = require('./schema.cjs');
+var styles = require('./styles.cjs');
+
+const Byline = ({
+  theme,
+  allowUntaggedContributors,
+  contributorLimit,
+  enablePreview,
+  placeholder: placeholder$1,
+  initialValue,
+  readOnly,
+  handleSave,
+  searchContributors,
+  onBlur
+}) => {
+  const editorRef = react.useRef(null);
+  const viewRef = react.useRef(null);
+  const dropdownRef = react.useRef(null);
+  const [currentText, setCurrentText] = react.useState("");
+  const [currentOptionIndex, setCurrentOptionIndex] = react.useState(0);
+  const [taggedContributors, setTaggedContributors] = react.useState([]);
+  const [currentDoc, setCurrentDoc] = react.useState(null);
+  const [showDropdown, setShowDropdown] = react.useState(false);
+  const isTypingFromStartRange = react.useRef(
+    void 0
+  );
+  const trackTypingFromStart = (tr) => {
+    const isCursorSelection = tr.selection.from === tr.selection.to;
+    const currentPosition = tr.selection.from;
+    const hasChanges = tr.steps.length > 0;
+    if (!isCursorSelection) {
+      isTypingFromStartRange.current = void 0;
+      return;
+    }
+    if (!isTypingFromStartRange.current && currentPosition === 1 && hasChanges) {
+      isTypingFromStartRange.current = {
+        start: 1,
+        maxReached: 1,
+        lastPosition: 1
+      };
+      return;
+    }
+    if (isTypingFromStartRange.current) {
+      const { start, maxReached, lastPosition } = isTypingFromStartRange.current;
+      const isWithinRange = currentPosition >= start && currentPosition <= maxReached;
+      const isExtendingRange = hasChanges && currentPosition === maxReached + 1;
+      if (isWithinRange || isExtendingRange) {
+        if (hasChanges) {
+          const positionDelta = currentPosition - lastPosition;
+          if (positionDelta < 0) {
+            isTypingFromStartRange.current.maxReached = maxReached - 1;
+          } else if (positionDelta > 0) {
+            isTypingFromStartRange.current.maxReached = maxReached + 1;
+          }
+          isTypingFromStartRange.current.lastPosition = currentPosition;
+        }
+        return;
+      }
+    }
+    isTypingFromStartRange.current = void 0;
+  };
+  const getShouldShowDropdown = (view, selectedText) => {
+    if (readOnly) {
+      return false;
+    }
+    const showDropdownBasedOnProps = !!searchContributors || !!allowUntaggedContributors;
+    if (lib.hasHitContributorLimit(view.state.doc, contributorLimit)) {
+      return false;
+    }
+    return selectedText.trim() !== "" && showDropdownBasedOnProps;
+  };
+  const [enterHit, setEnterHit] = react.useState(false);
+  const checkDropdownVisibility = () => {
+    if (dropdownRef.current?.checkVisibility) {
+      return dropdownRef.current.checkVisibility();
+    } else {
+      return dropdownRef.current?.offsetParent !== null;
+    }
+  };
+  react.useEffect(() => {
+    if (!editorRef.current) {
+      return;
+    }
+    const initialDoc = lib.convertBylineModelToNode(initialValue);
+    const state = prosemirrorState.EditorState.create({
+      schema: schema.bylineEditorSchema,
+      plugins: [
+        prosemirrorDropcursor.dropCursor(),
+        plugins.clipboardPlugin(allowUntaggedContributors, contributorLimit),
+        prosemirrorHistory.history(),
+        plugins.keybindings(),
+        prosemirrorInvisibles.createInvisiblesPlugin([prosemirrorInvisibles.space, prosemirrorInvisibles.nbSpace], {
+          displayLineEndSelection: true,
+          shouldShowInvisibles: true
+        }),
+        plugins.bylinePlugin(),
+        placeholder.createPlaceholderPlugin(placeholder$1 ?? "Enter a byline...")
+      ],
+      doc: initialDoc
+    });
+    setCurrentDoc(initialDoc);
+    viewRef.current = new prosemirrorView.EditorView(editorRef.current, {
+      state,
+      editable: () => !readOnly,
+      attributes: {
+        role: "combobox",
+        "aria-label": "byline",
+        "aria-controls": "byline-dropdown",
+        "aria-expanded": "false",
+        "data-testid": "byline-input",
+        ...readOnly && { "aria-readonly": "true" }
+      },
+      handleDOMEvents: {
+        keydown: (view, event) => {
+          if (readOnly) {
+            return false;
+          }
+          if (event.key === "Escape") {
+            setShowDropdown(false);
+            return true;
+          }
+          if (event.key === "ArrowDown") {
+            if (checkDropdownVisibility()) {
+              event.preventDefault();
+              setCurrentOptionIndex((currentOptionIndex2) => {
+                return currentOptionIndex2 + 1;
+              });
+              return true;
+            }
+            return false;
+          }
+          if (event.key === "ArrowUp") {
+            if (checkDropdownVisibility()) {
+              event.preventDefault();
+              setCurrentOptionIndex((currentOptionIndex2) => {
+                return currentOptionIndex2 - 1;
+              });
+              return true;
+            }
+            return false;
+          }
+          if (event.key === "Enter") {
+            if (checkDropdownVisibility()) {
+              event.preventDefault();
+              setEnterHit(true);
+            }
+            return false;
+          }
+          return false;
+        },
+        blur: (_view, event) => {
+          if (readOnly) {
+            return false;
+          }
+          if (!dropdownRef.current?.contains(
+            event.relatedTarget
+          )) {
+            setShowDropdown(false);
+          }
+          return false;
+        }
+      },
+      dispatchTransaction(tr) {
+        if (readOnly) {
+          if (tr.docChanged) {
+            return;
+          }
+          if (viewRef.current) {
+            const newState = viewRef.current.state.apply(tr);
+            viewRef.current.updateState(newState);
+          }
+          return;
+        }
+        if (viewRef.current?.hasFocus()) {
+          trackTypingFromStart(tr);
+          const newState = viewRef.current.state.apply(tr);
+          viewRef.current.updateState(newState);
+          const { selectedText } = lib.getCurrentText(
+            newState.doc,
+            newState.selection.from,
+            newState.selection.to,
+            isTypingFromStartRange.current
+          );
+          setCurrentText(selectedText);
+          const shouldShowDropdown = getShouldShowDropdown(
+            viewRef.current,
+            selectedText
+          );
+          if (shouldShowDropdown && searchContributors) {
+            void searchContributors(selectedText).then((contributors) => {
+              setTaggedContributors(contributors);
+            }).catch((error) => {
+              console.error(
+                "Error fetching tagged contributors:",
+                error
+              );
+              setTaggedContributors([]);
+            });
+          } else {
+            setTaggedContributors([]);
+          }
+          setShowDropdown(shouldShowDropdown);
+          if (tr.docChanged) {
+            setCurrentDoc(newState.doc);
+            handleSave(lib.convertNodeToBylineModel(newState.doc));
+          }
+        }
+      }
+    });
+    return () => {
+      viewRef.current?.destroy();
+    };
+  }, []);
+  react.useEffect(() => {
+    const numberOfOptions = taggedContributors.length + (allowUntaggedContributors ? 1 : 0);
+    if (numberOfOptions) {
+      if (currentOptionIndex < 0) {
+        setCurrentOptionIndex(numberOfOptions - 1);
+      } else {
+        setCurrentOptionIndex(currentOptionIndex % numberOfOptions);
+      }
+    }
+    if (showDropdown) {
+      const editor = document.querySelector("[role=combobox]");
+      editor?.setAttribute(
+        "aria-activedescendant",
+        `contributor-option-${currentOptionIndex}`
+      );
+      editor?.setAttribute("aria-expanded", "true");
+    }
+  }, [
+    currentOptionIndex,
+    showDropdown,
+    taggedContributors.length,
+    allowUntaggedContributors
+  ]);
+  react.useEffect(() => {
+    if (showDropdown && currentOptionIndex >= 0) {
+      const selectedOption = document.getElementById(
+        `contributor-option-${currentOptionIndex}`
+      );
+      if (selectedOption && dropdownRef.current) {
+        selectedOption.scrollIntoView({
+          behavior: "smooth",
+          block: "nearest"
+        });
+      }
+    }
+  }, [currentOptionIndex, showDropdown]);
+  react.useEffect(() => {
+    if (enterHit) {
+      if (allowUntaggedContributors && currentOptionIndex === taggedContributors.length) {
+        lib.addUntaggedContributor(
+          viewRef,
+          setShowDropdown,
+          contributorLimit,
+          isTypingFromStartRange.current
+        );
+      } else {
+        const contributorToAdd = taggedContributors[currentOptionIndex];
+        if (contributorToAdd) {
+          lib.addTaggedContributor(
+            contributorToAdd,
+            viewRef,
+            setShowDropdown,
+            contributorLimit,
+            isTypingFromStartRange.current
+          );
+        }
+      }
+      setEnterHit(false);
+    }
+  }, [
+    currentOptionIndex,
+    enterHit,
+    taggedContributors,
+    contributorLimit,
+    allowUntaggedContributors
+  ]);
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { css: styles.bylineContainerStyles, children: [
+    /* @__PURE__ */ jsxRuntime.jsx("div", { css: styles.bylineEditorStyles(theme?.editor), ref: editorRef, onBlur }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        ref: dropdownRef,
+        tabIndex: 0,
+        css: styles.dropdownContainerStyles(
+          showDropdown && // show the dropdown if there are tagged contributors to select or untagged contributors are allowed
+          (taggedContributors.length > 0 || !!allowUntaggedContributors),
+          theme?.dropdown
+        ),
+        children: /* @__PURE__ */ jsxRuntime.jsxs("ul", { id: "byline-dropdown", role: "listbox", css: styles.dropdownUlStyles, children: [
+          taggedContributors.map((contributor, i) => /* @__PURE__ */ jsxRuntime.jsx(
+            "li",
+            {
+              id: `contributor-option-${i}`,
+              role: "option",
+              "aria-selected": i === currentOptionIndex,
+              css: [
+                styles.dropdownLiStyles(theme),
+                i === currentOptionIndex && styles.selectedDropdownLiStyles(theme)
+              ],
+              onMouseMove: () => {
+                if (currentOptionIndex !== i) {
+                  setCurrentOptionIndex(i);
+                }
+              },
+              onMouseDown: (e) => {
+                e.preventDefault();
+                lib.addTaggedContributor(
+                  contributor,
+                  viewRef,
+                  setShowDropdown,
+                  contributorLimit,
+                  isTypingFromStartRange.current
+                );
+              },
+              children: contributor.internalLabel ?? contributor.label
+            },
+            contributor.tagId
+          )),
+          allowUntaggedContributors && /* @__PURE__ */ jsxRuntime.jsxs(
+            "li",
+            {
+              role: "option",
+              id: `contributor-option-${taggedContributors.length}`,
+              "aria-selected": currentOptionIndex === taggedContributors.length,
+              css: [
+                styles.dropdownLiStyles(theme),
+                currentOptionIndex === taggedContributors.length && styles.selectedDropdownLiStyles(theme)
+              ],
+              onMouseMove: () => {
+                if (currentOptionIndex !== taggedContributors.length) {
+                  setCurrentOptionIndex(
+                    taggedContributors.length
+                  );
+                }
+              },
+              onMouseDown: (e) => {
+                e.preventDefault();
+                lib.addUntaggedContributor(
+                  viewRef,
+                  setShowDropdown,
+                  contributorLimit,
+                  isTypingFromStartRange.current
+                );
+              },
+              children: [
+                'Add "',
+                currentText,
+                '" as untagged contributor'
+              ]
+            }
+          )
+        ] })
+      }
+    ),
+    enablePreview && /* @__PURE__ */ jsxRuntime.jsx(Preview.Preview, { doc: currentDoc })
+  ] });
+};
+
+exports.Byline = Byline;

package/dist/byline/Byline.js

@@ -0,0 +1,273 @@
+import { jsxs, jsx } from '@emotion/react/jsx-runtime';
+import { createInvisiblesPlugin, space, nbSpace } from '@guardian/prosemirror-invisibles';
+import { dropCursor } from 'prosemirror-dropcursor';
+import { history } from 'prosemirror-history';
+import { EditorState } from 'prosemirror-state';
+import { EditorView } from 'prosemirror-view';
+import { useRef, useState, useEffect } from 'react';
+import { convertBylineModelToNode, getCurrentText, convertNodeToBylineModel, addUntaggedContributor, addTaggedContributor, hasHitContributorLimit } from './lib.js';
+import { createPlaceholderPlugin } from './placeholder.js';
+import { clipboardPlugin, keybindings, bylinePlugin } from './plugins.js';
+import { Preview } from './Preview.js';
+import { bylineEditorSchema } from './schema.js';
+import { bylineContainerStyles, bylineEditorStyles, dropdownContainerStyles, dropdownUlStyles, dropdownLiStyles, selectedDropdownLiStyles } from './styles.js';
+
+const Byline = ({ theme, allowUntaggedContributors, contributorLimit, enablePreview, placeholder, initialValue, readOnly, handleSave, searchContributors, onBlur }) => {
+  const editorRef = useRef(null);
+  const viewRef = useRef(null);
+  const dropdownRef = useRef(null);
+  const [currentText, setCurrentText] = useState("");
+  const [currentOptionIndex, setCurrentOptionIndex] = useState(0);
+  const [taggedContributors, setTaggedContributors] = useState([]);
+  const [currentDoc, setCurrentDoc] = useState(null);
+  const [showDropdown, setShowDropdown] = useState(false);
+  const isTypingFromStartRange = useRef(void 0);
+  const trackTypingFromStart = (tr) => {
+    const isCursorSelection = tr.selection.from === tr.selection.to;
+    const currentPosition = tr.selection.from;
+    const hasChanges = tr.steps.length > 0;
+    if (!isCursorSelection) {
+      isTypingFromStartRange.current = void 0;
+      return;
+    }
+    if (!isTypingFromStartRange.current && currentPosition === 1 && hasChanges) {
+      isTypingFromStartRange.current = {
+        start: 1,
+        maxReached: 1,
+        lastPosition: 1
+      };
+      return;
+    }
+    if (isTypingFromStartRange.current) {
+      const { start, maxReached, lastPosition } = isTypingFromStartRange.current;
+      const isWithinRange = currentPosition >= start && currentPosition <= maxReached;
+      const isExtendingRange = hasChanges && currentPosition === maxReached + 1;
+      if (isWithinRange || isExtendingRange) {
+        if (hasChanges) {
+          const positionDelta = currentPosition - lastPosition;
+          if (positionDelta < 0) {
+            isTypingFromStartRange.current.maxReached = maxReached - 1;
+          } else if (positionDelta > 0) {
+            isTypingFromStartRange.current.maxReached = maxReached + 1;
+          }
+          isTypingFromStartRange.current.lastPosition = currentPosition;
+        }
+        return;
+      }
+    }
+    isTypingFromStartRange.current = void 0;
+  };
+  const getShouldShowDropdown = (view, selectedText) => {
+    if (readOnly) {
+      return false;
+    }
+    const showDropdownBasedOnProps = !!searchContributors || !!allowUntaggedContributors;
+    if (hasHitContributorLimit(view.state.doc, contributorLimit)) {
+      return false;
+    }
+    return selectedText.trim() !== "" && showDropdownBasedOnProps;
+  };
+  const [enterHit, setEnterHit] = useState(false);
+  const checkDropdownVisibility = () => {
+    if (dropdownRef.current?.checkVisibility) {
+      return dropdownRef.current.checkVisibility();
+    } else {
+      return dropdownRef.current?.offsetParent !== null;
+    }
+  };
+  useEffect(() => {
+    if (!editorRef.current) {
+      return;
+    }
+    const initialDoc = convertBylineModelToNode(initialValue);
+    const state = EditorState.create({
+      schema: bylineEditorSchema,
+      plugins: [
+        dropCursor(),
+        clipboardPlugin(allowUntaggedContributors, contributorLimit),
+        history(),
+        keybindings(),
+        createInvisiblesPlugin([space, nbSpace], {
+          displayLineEndSelection: true,
+          shouldShowInvisibles: true
+        }),
+        bylinePlugin(),
+        createPlaceholderPlugin(placeholder ?? "Enter a byline...")
+      ],
+      doc: initialDoc
+    });
+    setCurrentDoc(initialDoc);
+    viewRef.current = new EditorView(editorRef.current, {
+      state,
+      editable: () => !readOnly,
+      attributes: {
+        role: "combobox",
+        "aria-label": "byline",
+        "aria-controls": "byline-dropdown",
+        "aria-expanded": "false",
+        "data-testid": "byline-input",
+        ...readOnly && { "aria-readonly": "true" }
+      },
+      handleDOMEvents: {
+        keydown: (view, event) => {
+          if (readOnly) {
+            return false;
+          }
+          if (event.key === "Escape") {
+            setShowDropdown(false);
+            return true;
+          }
+          if (event.key === "ArrowDown") {
+            if (checkDropdownVisibility()) {
+              event.preventDefault();
+              setCurrentOptionIndex((currentOptionIndex2) => {
+                return currentOptionIndex2 + 1;
+              });
+              return true;
+            }
+            return false;
+          }
+          if (event.key === "ArrowUp") {
+            if (checkDropdownVisibility()) {
+              event.preventDefault();
+              setCurrentOptionIndex((currentOptionIndex2) => {
+                return currentOptionIndex2 - 1;
+              });
+              return true;
+            }
+            return false;
+          }
+          if (event.key === "Enter") {
+            if (checkDropdownVisibility()) {
+              event.preventDefault();
+              setEnterHit(true);
+            }
+            return false;
+          }
+          return false;
+        },
+        blur: (_view, event) => {
+          if (readOnly) {
+            return false;
+          }
+          if (!dropdownRef.current?.contains(event.relatedTarget)) {
+            setShowDropdown(false);
+          }
+          return false;
+        }
+      },
+      dispatchTransaction(tr) {
+        if (readOnly) {
+          if (tr.docChanged) {
+            return;
+          }
+          if (viewRef.current) {
+            const newState = viewRef.current.state.apply(tr);
+            viewRef.current.updateState(newState);
+          }
+          return;
+        }
+        if (viewRef.current?.hasFocus()) {
+          trackTypingFromStart(tr);
+          const newState = viewRef.current.state.apply(tr);
+          viewRef.current.updateState(newState);
+          const { selectedText } = getCurrentText(newState.doc, newState.selection.from, newState.selection.to, isTypingFromStartRange.current);
+          setCurrentText(selectedText);
+          const shouldShowDropdown = getShouldShowDropdown(viewRef.current, selectedText);
+          if (shouldShowDropdown && searchContributors) {
+            void searchContributors(selectedText).then((contributors) => {
+              setTaggedContributors(contributors);
+            }).catch((error) => {
+              console.error("Error fetching tagged contributors:", error);
+              setTaggedContributors([]);
+            });
+          } else {
+            setTaggedContributors([]);
+          }
+          setShowDropdown(shouldShowDropdown);
+          if (tr.docChanged) {
+            setCurrentDoc(newState.doc);
+            handleSave(convertNodeToBylineModel(newState.doc));
+          }
+        }
+      }
+    });
+    return () => {
+      viewRef.current?.destroy();
+    };
+  }, []);
+  useEffect(() => {
+    const numberOfOptions = taggedContributors.length + (allowUntaggedContributors ? 1 : 0);
+    if (numberOfOptions) {
+      if (currentOptionIndex < 0) {
+        setCurrentOptionIndex(numberOfOptions - 1);
+      } else {
+        setCurrentOptionIndex(currentOptionIndex % numberOfOptions);
+      }
+    }
+    if (showDropdown) {
+      const editor = document.querySelector("[role=combobox]");
+      editor?.setAttribute("aria-activedescendant", `contributor-option-${currentOptionIndex}`);
+      editor?.setAttribute("aria-expanded", "true");
+    }
+  }, [
+    currentOptionIndex,
+    showDropdown,
+    taggedContributors.length,
+    allowUntaggedContributors
+  ]);
+  useEffect(() => {
+    if (showDropdown && currentOptionIndex >= 0) {
+      const selectedOption = document.getElementById(`contributor-option-${currentOptionIndex}`);
+      if (selectedOption && dropdownRef.current) {
+        selectedOption.scrollIntoView({
+          behavior: "smooth",
+          block: "nearest"
+        });
+      }
+    }
+  }, [currentOptionIndex, showDropdown]);
+  useEffect(() => {
+    if (enterHit) {
+      if (allowUntaggedContributors && currentOptionIndex === taggedContributors.length) {
+        addUntaggedContributor(viewRef, setShowDropdown, contributorLimit, isTypingFromStartRange.current);
+      } else {
+        const contributorToAdd = taggedContributors[currentOptionIndex];
+        if (contributorToAdd) {
+          addTaggedContributor(contributorToAdd, viewRef, setShowDropdown, contributorLimit, isTypingFromStartRange.current);
+        }
+      }
+      setEnterHit(false);
+    }
+  }, [
+    currentOptionIndex,
+    enterHit,
+    taggedContributors,
+    contributorLimit,
+    allowUntaggedContributors
+  ]);
+  return jsxs("div", { css: bylineContainerStyles, children: [jsx("div", { css: bylineEditorStyles(theme?.editor), ref: editorRef, onBlur }), jsx("div", { ref: dropdownRef, tabIndex: 0, css: dropdownContainerStyles(showDropdown && // show the dropdown if there are tagged contributors to select or untagged contributors are allowed
+  (taggedContributors.length > 0 || !!allowUntaggedContributors), theme?.dropdown), children: jsxs("ul", { id: "byline-dropdown", role: "listbox", css: dropdownUlStyles, children: [taggedContributors.map((contributor, i) => jsx("li", { id: `contributor-option-${i}`, role: "option", "aria-selected": i === currentOptionIndex, css: [
+    dropdownLiStyles(theme),
+    i === currentOptionIndex && selectedDropdownLiStyles(theme)
+  ], onMouseMove: () => {
+    if (currentOptionIndex !== i) {
+      setCurrentOptionIndex(i);
+    }
+  }, onMouseDown: (e) => {
+    e.preventDefault();
+    addTaggedContributor(contributor, viewRef, setShowDropdown, contributorLimit, isTypingFromStartRange.current);
+  }, children: contributor.internalLabel ?? contributor.label }, contributor.tagId)), allowUntaggedContributors && jsxs("li", { role: "option", id: `contributor-option-${taggedContributors.length}`, "aria-selected": currentOptionIndex === taggedContributors.length, css: [
+    dropdownLiStyles(theme),
+    currentOptionIndex === taggedContributors.length && selectedDropdownLiStyles(theme)
+  ], onMouseMove: () => {
+    if (currentOptionIndex !== taggedContributors.length) {
+      setCurrentOptionIndex(taggedContributors.length);
+    }
+  }, onMouseDown: (e) => {
+    e.preventDefault();
+    addUntaggedContributor(viewRef, setShowDropdown, contributorLimit, isTypingFromStartRange.current);
+  }, children: ['Add "', currentText, '" as untagged contributor'] })] }) }), enablePreview && jsx(Preview, { doc: currentDoc })] });
+};
+
+export { Byline };