@lar-works/design-system 0.2.1 → 0.3.0

package/src/forms/MarkdownEditor.tsx

@@ -0,0 +1,283 @@
+// The Markdown editor: Lexical, formatting as you type and storing Markdown, under a light toolbar. "- " starts a
+// bullet list, "1. " a numbered list, "# " a heading and **bold** turns bold; pasted plain-text Markdown renders. It
+// opens HTML, as an older Azure DevOps description holds, as the nodes it stands for, and still reports Markdown.
+
+import { CodeNode } from '@lexical/code';
+import { $generateNodesFromDOM } from '@lexical/html';
+import { LinkNode } from '@lexical/link';
+import { $isListItemNode, ListItemNode, ListNode } from '@lexical/list';
+import {
+    $convertFromMarkdownString,
+    $convertToMarkdownString,
+    $generateNodesFromMarkdownString,
+    TRANSFORMERS,
+} from '@lexical/markdown';
+import { AutoFocusPlugin } from '@lexical/react/LexicalAutoFocusPlugin';
+import { LexicalComposer } from '@lexical/react/LexicalComposer';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { ContentEditable } from '@lexical/react/LexicalContentEditable';
+import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
+import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
+import { LinkPlugin } from '@lexical/react/LexicalLinkPlugin';
+import { ListPlugin } from '@lexical/react/LexicalListPlugin';
+import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin';
+import { OnChangePlugin } from '@lexical/react/LexicalOnChangePlugin';
+import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
+import { HeadingNode, QuoteNode } from '@lexical/rich-text';
+import {
+    $findMatchingParent,
+    $getRoot,
+    $getSelection,
+    $insertNodes,
+    $isParagraphNode,
+    $isRangeSelection,
+    COMMAND_PRIORITY_EDITOR,
+    COMMAND_PRIORITY_HIGH,
+    INDENT_CONTENT_COMMAND,
+    KEY_TAB_COMMAND,
+    OUTDENT_CONTENT_COMMAND,
+    PASTE_COMMAND,
+} from 'lexical';
+import type { EditorState, LexicalEditor, LexicalNode } from 'lexical';
+import { useCallback, useEffect } from 'react';
+
+import type { RichTextFormat } from '../display/RichText';
+import { MarkdownToolbar } from './MarkdownToolbar';
+
+const theme = {
+    heading: {
+        h1: 'text-xl font-semibold mt-4 mb-1.5 first:mt-0',
+        h2: 'text-lg font-semibold mt-4 mb-1 first:mt-0',
+        h3: 'font-semibold mt-3 mb-1 first:mt-0',
+    },
+    list: {
+        ul: 'list-disc ps-6 my-1.5',
+        ol: 'list-decimal ps-6 my-1.5',
+        listitem: 'my-0.5 marker:text-base-500',
+        nested: { listitem: 'list-none' },
+    },
+    paragraph: 'my-1.5 first:mt-0',
+    quote: 'border-s-2 border-base-300 ps-3 text-base-700 my-1.5',
+    code: 'block rounded-md bg-base-200 p-3 font-mono text-xs my-1.5 whitespace-pre-wrap',
+    link: 'text-(--lar-info-text) underline underline-offset-2',
+    text: {
+        bold: 'font-semibold',
+        italic: 'italic',
+        strikethrough: 'line-through',
+        code: 'rounded bg-base-200 px-1 font-mono text-[0.85em]',
+    },
+};
+
+const LOOKS_LIKE_MARKDOWN = /(^|\n)\s*([-*+] |\d+[.)] |#{1,6} |> |```)|\*\*[^*]+\*\*|\[[^\]]+\]\([^)]+\)/;
+
+/** Puts pasted `nodes` in place of the selected text. Ones starting with a heading, list, quote or code block go in after
+ *  the block the caret is in, unless it is empty, as inserted at the caret the first block's text would join that block's. */
+function $insertPasted(nodes: LexicalNode[]) {
+    const selection = $getSelection();
+
+    if ($isRangeSelection(selection)) selection.removeText();
+
+    const block = $isRangeSelection(selection) ? selection.anchor.getNode().getTopLevelElement() : null;
+    const first = nodes[0];
+
+    if (!block || !first || $isParagraphNode(first) || block.getTextContentSize() === 0) return $insertNodes(nodes);
+
+    let last: LexicalNode = block;
+
+    for (const node of nodes) last = last.insertAfter(node);
+    last.selectEnd();
+}
+
+/** Plain text that reads as Markdown, pasted without HTML, goes in as the nodes it stands for. */
+function MarkdownPastePlugin() {
+    const [editor] = useLexicalComposerContext();
+
+    useEffect(
+        () =>
+            editor.registerCommand(
+                PASTE_COMMAND,
+                (event) => {
+                    const data = 'clipboardData' in event ? event.clipboardData : null;
+
+                    if (!data || data.types.includes('text/html')) return false;
+
+                    const text = data.getData('text/plain');
+
+                    if (!LOOKS_LIKE_MARKDOWN.test(text)) return false;
+
+                    event.preventDefault();
+                    editor.update(() => $insertPasted($generateNodesFromMarkdownString(text, TRANSFORMERS)));
+
+                    return true;
+                },
+                COMMAND_PRIORITY_HIGH,
+            ),
+        [editor],
+    );
+
+    return null;
+}
+
+/** Tab nests the list item the selection is in, one deeper than the item before it at most, and Shift+Tab lifts it back
+ *  out. Where neither can change anything, as outside a list or on a top-level item, Tab is left to the browser, so it
+ *  moves focus on rather than trapping it in the editor. */
+function ListTabPlugin() {
+    const [editor] = useLexicalComposerContext();
+
+    useEffect(
+        () =>
+            editor.registerCommand(
+                KEY_TAB_COMMAND,
+                (event) => {
+                    const selection = $getSelection();
+
+                    if (!$isRangeSelection(selection)) return false;
+
+                    const items = selection
+                        .getNodes()
+                        .map((node) => ($isListItemNode(node) ? node : $findMatchingParent(node, $isListItemNode)));
+                    const moves = (item: ListItemNode | null) =>
+                        item !== null && (event.shiftKey ? item.getIndent() > 0 : item.getPreviousSibling() !== null);
+
+                    if (!items.some(moves)) return false;
+
+                    event.preventDefault();
+
+                    return editor.dispatchCommand(
+                        event.shiftKey ? OUTDENT_CONTENT_COMMAND : INDENT_CONTENT_COMMAND,
+                        undefined,
+                    );
+                },
+                COMMAND_PRIORITY_EDITOR,
+            ),
+        [editor],
+    );
+
+    return null;
+}
+
+/** Locks the text, as a disabled field does. */
+function EditablePlugin({ editable }: { editable: boolean }) {
+    const [editor] = useLexicalComposerContext();
+
+    useEffect(() => editor.setEditable(editable), [editor, editable]);
+
+    return null;
+}
+
+/** Reports the Markdown the editor makes of its starting text, which a check for changes compares against. */
+function BaselinePlugin({ onBaseline }: { onBaseline: (markdown: string) => void }) {
+    const [editor] = useLexicalComposerContext();
+
+    useEffect(
+        () => editor.getEditorState().read(() => onBaseline($convertToMarkdownString(TRANSFORMERS))),
+        [editor, onBaseline],
+    );
+
+    return null;
+}
+
+/** Fills a new editor from `value`, read as Markdown or as HTML. */
+const startFrom = (value: string, format: RichTextFormat) => (editor: LexicalEditor) => {
+    if (format === 'markdown') return $convertFromMarkdownString(value, TRANSFORMERS);
+
+    $getRoot().select();
+    $insertNodes($generateNodesFromDOM(editor, new DOMParser().parseFromString(value, 'text/html')));
+};
+
+interface MarkdownEditorProps {
+    /** The Markdown it starts from; later changes to it are ignored. */
+    value: string;
+    /** How `value` is written; the editor reports Markdown either way. */
+    format?: RichTextFormat;
+    onChange: (markdown: string) => void;
+    label: string;
+    placeholder: string;
+    /** Grows the editor into its parent's height, or, when 'wide', only while its container is 40rem wide or more and
+     *  otherwise with its text, uncapped, as its parent scrolls. Without it, it grows with its text up to a cap. */
+    fill?: boolean | 'wide';
+    disabled?: boolean;
+    autoFocus?: boolean;
+    /** Called with the Markdown the editor makes of `value`, before any edit. */
+    onBaseline?: (markdown: string) => void;
+}
+
+/** A rich text field that reads and reports Markdown, such as a ticket's description, with a formatting toolbar. */
+export function MarkdownEditor({
+    value,
+    format = 'markdown',
+    onChange,
+    label,
+    placeholder,
+    fill = false,
+    disabled = false,
+    autoFocus = false,
+    onBaseline,
+}: MarkdownEditorProps) {
+    // Below 40rem a 'wide' fill gives way to the editor's text height, with no scroll area of its own. The toolbar then
+    // sticks to the top of the parent's scroll area, which needs the box to stop clipping, so the toolbar rounds its own
+    // corners instead.
+    const narrow =
+        fill === 'wide'
+            ? {
+                  box: '@max-[40rem]:flex-none @max-[40rem]:overflow-visible',
+                  area: '@max-[40rem]:flex-none @max-[40rem]:overflow-visible',
+                  text: '@max-[40rem]:min-h-44',
+                  toolbar:
+                      '@max-[40rem]:sticky @max-[40rem]:top-0 @max-[40rem]:z-10 @max-[40rem]:rounded-t-lg @max-[40rem]:bg-base-100',
+              }
+            : { box: '', area: '', text: '', toolbar: '' };
+    const onEdit = useCallback(
+        (state: EditorState) => state.read(() => onChange($convertToMarkdownString(TRANSFORMERS))),
+        [onChange],
+    );
+
+    return (
+        <LexicalComposer
+            initialConfig={{
+                namespace: 'description',
+                theme,
+                onError: (error) => {
+                    throw error;
+                },
+                nodes: [HeadingNode, QuoteNode, ListNode, ListItemNode, CodeNode, LinkNode],
+                editorState: startFrom(value, format),
+            }}
+        >
+            <div
+                data-description-editor
+                className={`border-base-300 bg-base-100 focus-within:border-primary/60 focus-within:ring-primary/15 flex flex-col overflow-hidden rounded-lg border transition-[border-color,box-shadow] focus-within:ring-3 ${fill ? `min-h-0 flex-1 ${narrow.box}` : ''}`}
+            >
+                <MarkdownToolbar className={narrow.toolbar} />
+                <div
+                    className={`relative overflow-y-auto ${fill ? `min-h-0 flex-1 ${narrow.area}` : 'max-h-[min(24rem,45dvh)]'}`}
+                >
+                    <RichTextPlugin
+                        contentEditable={
+                            <ContentEditable
+                                aria-label={label}
+                                className={`px-4 py-3 text-[15px] leading-relaxed outline-none ${fill ? `min-h-full ${narrow.text}` : 'min-h-44'}`}
+                            />
+                        }
+                        placeholder={
+                            <div className="text-base-700 pointer-events-none absolute top-3 left-4 text-[15px] leading-relaxed">
+                                {placeholder}
+                            </div>
+                        }
+                        ErrorBoundary={LexicalErrorBoundary}
+                    />
+                </div>
+            </div>
+            {autoFocus && <AutoFocusPlugin defaultSelection="rootEnd" />}
+            <HistoryPlugin />
+            <ListPlugin />
+            <LinkPlugin />
+            <ListTabPlugin />
+            <MarkdownShortcutPlugin transformers={TRANSFORMERS} />
+            <MarkdownPastePlugin />
+            <EditablePlugin editable={!disabled} />
+            {onBaseline && <BaselinePlugin onBaseline={onBaseline} />}
+            <OnChangePlugin ignoreSelectionChange onChange={onEdit} />
+        </LexicalComposer>
+    );
+}

package/src/forms/MarkdownToolbar.tsx

@@ -0,0 +1,267 @@
+// The Markdown editor's toolbar: bold, italic, heading, bulleted list, numbered list and link, each pressed while
+// the selection has it. Link opens a URL field under the toolbar, as Electron has no window.prompt: Enter or Apply links
+// the selection, Escape, a click outside or an empty URL closes it with no link, and Escape leaves the dialog open. Its
+// tooltip stays shut while the field is open, so it covers none of it.
+
+import { $isLinkNode, $toggleLink, TOGGLE_LINK_COMMAND } from '@lexical/link';
+import {
+    $isListNode,
+    INSERT_ORDERED_LIST_COMMAND,
+    INSERT_UNORDERED_LIST_COMMAND,
+    REMOVE_LIST_COMMAND,
+} from '@lexical/list';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { $createHeadingNode, $isHeadingNode } from '@lexical/rich-text';
+import { $setBlocksType } from '@lexical/selection';
+import { $createParagraphNode, $getSelection, $isRangeSelection, $setSelection, FORMAT_TEXT_COMMAND } from 'lexical';
+import type { BaseSelection, EditorState } from 'lexical';
+import { BoldIcon, HeadingIcon, ItalicIcon, LinkIcon, ListIcon, ListOrderedIcon } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { Button } from '../actions/Button';
+import { useDesignSystemLabels } from '../foundations/DesignSystemProvider';
+import { applePlatform } from '../foundations/KeyboardShortcut';
+import { Popover } from '../overlays/Popover';
+import { Tooltip, TooltipPopup, TooltipTrigger } from '../overlays/Tooltip';
+
+const MOD = applePlatform ? '⌘' : 'Ctrl+';
+
+type Block = 'paragraph' | 'heading' | 'bullet' | 'number';
+interface Active {
+    bold: boolean;
+    italic: boolean;
+    link: boolean;
+    block: Block;
+}
+
+const NONE: Active = { bold: false, italic: false, link: false, block: 'paragraph' };
+
+/** What the selection has on. */
+function readActive(state: EditorState): Active {
+    return state.read(() => {
+        const selection = $getSelection();
+
+        if (!$isRangeSelection(selection)) return NONE;
+
+        const node = selection.anchor.getNode();
+        const top = node.getKey() === 'root' ? null : node.getTopLevelElement();
+        const block = $isHeadingNode(top)
+            ? 'heading'
+            : $isListNode(top)
+              ? top.getListType() === 'number'
+                  ? 'number'
+                  : 'bullet'
+              : 'paragraph';
+
+        return {
+            bold: selection.hasFormat('bold'),
+            italic: selection.hasFormat('italic'),
+            link: $isLinkNode(node.getParent()) || $isLinkNode(node),
+            block,
+        };
+    });
+}
+
+/** A toolbar button; `quiet` keeps its tooltip shut, as while the field it opens would sit under it. Any other props,
+ *  such as a popover trigger's, go on the button itself. */
+function ToolButton({
+    label,
+    keys,
+    on,
+    icon,
+    run,
+    quiet = false,
+    ...button
+}: {
+    label: string;
+    keys?: string;
+    on: boolean;
+    icon: ReactNode;
+    run: () => void;
+    quiet?: boolean;
+} & ComponentProps<'button'>) {
+    // Held here, so a hover while quiet doesn't leave the tooltip to show once it no longer is.
+    const [tip, setTip] = useState(false);
+
+    return (
+        <Tooltip open={tip && !quiet} onOpenChange={(open) => setTip(open && !quiet)}>
+            <TooltipTrigger asChild>
+                {/* Pressing keeps the editor's selection: focus stays in the editor. */}
+                <button
+                    type="button"
+                    {...button}
+                    aria-label={label}
+                    aria-pressed={on}
+                    onMouseDown={(event) => event.preventDefault()}
+                    onClick={(event) => {
+                        run();
+                        button.onClick?.(event);
+                    }}
+                    className={`focus-visible:ring-primary grid size-7 place-items-center rounded-md transition-colors outline-none focus-visible:ring-2 [&_svg]:size-4 ${on ? 'bg-primary/10 text-primary' : 'text-base-700 hover:bg-base-200 hover:text-base-content'}`}
+                >
+                    {icon}
+                </button>
+            </TooltipTrigger>
+            <TooltipPopup side="bottom">
+                {label}
+                {keys && <span className="text-base-500 ms-2">{keys}</span>}
+            </TooltipPopup>
+        </Tooltip>
+    );
+}
+
+/** The URL field Link opens, anchored under its button; `close` gets the URL to link, or null for none. A popover is a
+ *  layer above the dialog, so Escape closes the field alone. */
+function LinkField({
+    open,
+    close,
+    children,
+}: {
+    open: boolean;
+    close: (url: string | null) => void;
+    children: ReactNode;
+}) {
+    const labels = useDesignSystemLabels().editor;
+    const field = useRef<HTMLInputElement>(null);
+    const apply = () => close(field.current!.value.trim() || null);
+
+    return (
+        <Popover open={open} onOpenChange={(opened) => !opened && close(null)}>
+            {/* The button opens the field itself, so the trigger's own toggle is turned off. */}
+            <Popover.Trigger asChild onClick={(event) => event.preventDefault()}>
+                {children}
+            </Popover.Trigger>
+            {/* Portalled, its events still reach the form in the React tree, which would count them as edits. */}
+            <Popover.Content
+                side="bottom"
+                align="start"
+                onCloseAutoFocus={(event) => event.preventDefault()}
+                onInput={(event) => event.stopPropagation()}
+                onChange={(event) => event.stopPropagation()}
+            >
+                <div className="flex items-center gap-1.5">
+                    <input
+                        ref={field}
+                        type="url"
+                        aria-label={labels.linkUrl}
+                        placeholder={labels.linkPlaceholder}
+                        autoComplete="off"
+                        className="border-base-300 bg-base-100 focus:border-primary/60 focus:ring-primary/15 h-7 w-56 max-w-full rounded-md border px-2 text-sm outline-none focus:ring-3"
+                        onKeyDown={(event) => {
+                            if (event.key !== 'Enter') return;
+
+                            event.preventDefault();
+                            apply();
+                        }}
+                    />
+                    <Button compact onClick={apply}>
+                        {labels.apply}
+                    </Button>
+                </div>
+            </Popover.Content>
+        </Popover>
+    );
+}
+
+/** `className` adds to the bar's own classes. */
+export function MarkdownToolbar({ className = '' }: { className?: string }) {
+    const labels = useDesignSystemLabels().editor;
+    const [editor] = useLexicalComposerContext();
+    const [active, setActive] = useState(NONE);
+    // The selection Link opened its field on, which the field's focus would otherwise lose.
+    const [linking, setLinking] = useState<BaseSelection | null>(null);
+
+    useEffect(() => editor.registerUpdateListener(({ editorState }) => setActive(readActive(editorState))), [editor]);
+
+    const heading = () =>
+        editor.update(() => {
+            const selection = $getSelection();
+
+            if ($isRangeSelection(selection))
+                $setBlocksType(selection, () =>
+                    active.block === 'heading' ? $createParagraphNode() : $createHeadingNode('h2'),
+                );
+        });
+    const list = (type: 'bullet' | 'number') => {
+        if (active.block === type) editor.dispatchCommand(REMOVE_LIST_COMMAND, undefined);
+        else
+            editor.dispatchCommand(
+                type === 'bullet' ? INSERT_UNORDERED_LIST_COMMAND : INSERT_ORDERED_LIST_COMMAND,
+                undefined,
+            );
+    };
+    const link = () => {
+        if (active.link) return editor.dispatchCommand(TOGGLE_LINK_COMMAND, null);
+
+        setLinking(editor.getEditorState().read(() => $getSelection()?.clone() ?? null));
+    };
+    const closeLink = (url: string | null) => {
+        const selection = linking;
+
+        setLinking(null);
+
+        if (url && selection)
+            editor.update(() => {
+                $setSelection(selection.clone());
+                $toggleLink(url);
+            });
+
+        editor.focus();
+    };
+
+    return (
+        <div
+            role="toolbar"
+            aria-label={labels.formatting}
+            className={`border-base-300/70 flex shrink-0 items-center gap-0.5 border-b px-2 py-1 ${className}`}
+        >
+            <ToolButton
+                label={labels.bold}
+                keys={`${MOD}B`}
+                on={active.bold}
+                icon={<BoldIcon />}
+                run={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'bold')}
+            />
+            <ToolButton
+                label={labels.italic}
+                keys={`${MOD}I`}
+                on={active.italic}
+                icon={<ItalicIcon />}
+                run={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'italic')}
+            />
+            <span aria-hidden="true" className="bg-base-300 mx-1 h-4 w-px" />
+            <ToolButton
+                label={labels.heading}
+                keys="#"
+                on={active.block === 'heading'}
+                icon={<HeadingIcon />}
+                run={heading}
+            />
+            <ToolButton
+                label={labels.bulletedList}
+                keys="-"
+                on={active.block === 'bullet'}
+                icon={<ListIcon />}
+                run={() => list('bullet')}
+            />
+            <ToolButton
+                label={labels.numberedList}
+                keys="1."
+                on={active.block === 'number'}
+                icon={<ListOrderedIcon />}
+                run={() => list('number')}
+            />
+            <LinkField open={linking !== null} close={closeLink}>
+                <ToolButton
+                    label={labels.link}
+                    on={active.link}
+                    icon={<LinkIcon />}
+                    run={link}
+                    quiet={linking !== null}
+                />
+            </LinkField>
+            <span className="text-base-700 ms-auto pe-1 text-[11px]">{labels.markdown}</span>
+        </div>
+    );
+}