@guardian/stand 0.0.40 → 0.0.41

package/dist/components/Byline/Byline.js

@@ -1,273 +1,334 @@
-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, dropdownUlStyles, dropdownLiStyles, selectedDropdownLiStyles, dropdownContainerStyles } from './styles.js';
-
+import { bylineEditorSchema } from "./schema.js";
+import { addTaggedContributor, addUntaggedContributor, convertBylineModelToNode, convertNodeToBylineModel, getCurrentText, hasHitContributorLimit } from "./lib.js";
+import { createPlaceholderPlugin } from "./placeholder.js";
+import { bylinePlugin, clipboardPlugin, keybindings } from "./plugins.js";
+import { bylineContainerStyles, bylineEditorStyles, dropdownContainerStyles, dropdownLiStyles, dropdownUlStyles, selectedDropdownLiStyles } from "./styles.js";
+import { Preview } from "./Preview.js";
+import { useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "@emotion/react/jsx-runtime";
+import { createInvisiblesPlugin, nbSpace, space } from "@guardian/prosemirror-invisibles";
+import { dropCursor } from "prosemirror-dropcursor";
+import { history } from "prosemirror-history";
+import { EditorState } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+//#region src/components/Byline/Byline.tsx
+/**
+* ## Byline
+*
+* *Status: Production*
+*
+* A flexible byline editor component built in ProseMirror and React with usability and accessibility in mind.
+*
+* **Peer dependencies:**
+*
+* You'll need to install the following peer dependencies in your project to use the `Byline` component:
+* - `@guardian/prosemirror-invisibles`
+* - `prosemirror-dropcursor`
+* - `prosemirror-history`
+* - `prosemirror-keymap`
+* - `prosemirror-model`
+* - `prosemirror-state`
+* - `prosemirror-view`
+*
+* See the `peerDependencies` section of `package.json` for compatible versions to install.
+*
+* #### Usage
+*
+* ```tsx
+* import type { BylineModel } from '@guardian/stand';
+* import { Byline } from '@guardian/stand';
+*
+* const Component = () => {
+*     const bylineModel: BylineModel = {
+*         // ...set up your byline model here
+*     };
+*     ...
+* 	return (
+*         <>
+*         ...
+*             <Byline initialValue={bylineModel} />
+*         ...
+*         </>
+*     );
+* };
+* ```
+*
+* By itself the `Byline` component is just the editor UI.
+* You will need to set up the ProseMirror editor state, schema, and plugins to get a fully functioning byline editor.
+* See the props and example below for a more complete implementation.
+* The `BylineModel` type defines the structure of the byline data which is agnostic from any other data structure. You must convert to/from this model when integrating with your application's data structures.
+*
+* #### Props
+*
+* See {@link BylineProps} for the full list of props, usage example can be seen in Storybook.
+*
+* #### Example
+*
+* The `ContentByline` component in `flexible-frontend` has a detailed example of how to use the `Byline` component from Stand.
+* See [ContentByline.tsx](https://github.com/guardian/flexible-content/blob/1d537615a18ae24a4a5410a3f945b2b9db1dbb47/flexible-frontend/src/app/components/furniture/content-byline/ContentByline.tsx#L72-L205).
+*/
 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), 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?.dropdown),
-    i === currentOptionIndex && selectedDropdownLiStyles(theme?.dropdown)
-  ], 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?.dropdown),
-    currentOptionIndex === taggedContributors.length && selectedDropdownLiStyles(theme?.dropdown)
-  ], 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 })] });
+	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;
+		/**
+		* Determines whether to hide or show the contributor dropdown based on component props,
+		* and should be used in combination with the selected/current text when calling setShowDropdown
+		* The logic evaluates to true when either:
+		* - There are search contributors available OR
+		* - Untagged contributors are allowed
+		* - The document state is under any contributor limit
+		* - The selected text is not empty
+		*/
+		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((currentOptionIndex) => {
+								return currentOptionIndex + 1;
+							});
+							return true;
+						}
+						return false;
+					}
+					if (event.key === "ArrowUp") {
+						if (checkDropdownVisibility()) {
+							event.preventDefault();
+							setCurrentOptionIndex((currentOptionIndex) => {
+								return currentOptionIndex - 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) 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 /* @__PURE__ */ jsxs("div", {
+		css: bylineContainerStyles,
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				css: bylineEditorStyles(theme),
+				ref: editorRef,
+				onBlur
+			}),
+			/* @__PURE__ */ jsx("div", {
+				ref: dropdownRef,
+				tabIndex: 0,
+				css: dropdownContainerStyles(showDropdown && (taggedContributors.length > 0 || !!allowUntaggedContributors), theme?.dropdown),
+				children: /* @__PURE__ */ jsxs("ul", {
+					id: "byline-dropdown",
+					role: "listbox",
+					css: dropdownUlStyles,
+					children: [taggedContributors.map((contributor, i) => /* @__PURE__ */ jsx("li", {
+						id: `contributor-option-${i}`,
+						role: "option",
+						"aria-selected": i === currentOptionIndex,
+						css: [dropdownLiStyles(theme?.dropdown), i === currentOptionIndex && selectedDropdownLiStyles(theme?.dropdown)],
+						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 && /* @__PURE__ */ jsxs("li", {
+						role: "option",
+						id: `contributor-option-${taggedContributors.length}`,
+						"aria-selected": currentOptionIndex === taggedContributors.length,
+						css: [dropdownLiStyles(theme?.dropdown), currentOptionIndex === taggedContributors.length && selectedDropdownLiStyles(theme?.dropdown)],
+						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 && /* @__PURE__ */ jsx(Preview, { doc: currentDoc })
+		]
+	});
 };
-
+//#endregion
 export { Byline };