@keboola/design 1.0.0

package/src/components/MarkdownEditor/MarkdownEditor.tsx

@@ -0,0 +1,155 @@
+import { useState } from 'react';
+import type { ReactNode } from 'react';
+import { CodeNode } from '@lexical/code';
+import { LinkNode } from '@lexical/link';
+import { ListItemNode, ListNode } from '@lexical/list';
+import { $convertFromMarkdownString } from '@lexical/markdown';
+import { AutoFocusPlugin } from '@lexical/react/LexicalAutoFocusPlugin';
+import { CheckListPlugin } from '@lexical/react/LexicalCheckListPlugin';
+import { ClickableLinkPlugin } from '@lexical/react/LexicalClickableLinkPlugin';
+import type { InitialConfigType } from '@lexical/react/LexicalComposer';
+import { LexicalComposer } from '@lexical/react/LexicalComposer';
+import { ContentEditable } from '@lexical/react/LexicalContentEditable';
+import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
+import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
+import { HorizontalRuleNode } from '@lexical/react/LexicalHorizontalRuleNode';
+import { HorizontalRulePlugin } from '@lexical/react/LexicalHorizontalRulePlugin';
+import { LinkPlugin } from '@lexical/react/LexicalLinkPlugin';
+import { ListPlugin } from '@lexical/react/LexicalListPlugin';
+import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin';
+import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
+import { TabIndentationPlugin } from '@lexical/react/LexicalTabIndentationPlugin';
+import { HeadingNode, QuoteNode } from '@lexical/rich-text';
+
+import { cn } from '../../utils';
+
+import { ImageNode } from './nodes/ImageNode';
+import { MermaidNode } from './nodes/MermaidNode';
+import { ImagePastePlugin } from './plugins/ImagePastePlugin';
+import { KeyboardPlugin } from './plugins/KeyboardPlugin';
+import { MarkdownSyncPlugin } from './plugins/MarkdownSyncPlugin';
+import { ToolbarPlugin } from './plugins/ToolbarPlugin';
+import { ImageRendererProvider } from './context';
+import { editorTheme } from './theme';
+import { CUSTOM_TRANSFORMERS, preprocessMarkdown } from './transformers';
+
+export type MarkdownEditorProps = {
+  /** Markdown string (controlled) */
+  value: string;
+  onChange?: (markdown: string) => void;
+  /**
+   * Renders content but never accepts input. Use for permanent view-only contexts
+   * (e.g. a current user lacks edit permission). Toolbar is hidden.
+   */
+  readOnly?: boolean;
+  /**
+   * Temporarily blocks input but signals intent to re-enable
+   * (e.g. while a save is in flight). Functionally identical to `readOnly` today.
+   */
+  disabled?: boolean;
+  placeholder?: string;
+  autoFocus?: boolean;
+  /** Invoked on Cmd/Ctrl+Enter — typically used to commit a form. */
+  onSave?: () => void;
+  /** Invoked on Escape — typically used to discard or close the editor. */
+  onCancel?: () => void;
+  /**
+   * Async image upload. Resolved URL is embedded as the image src
+   * (`![alt](url)` in the underlying markdown).
+   */
+  onImageUpload?: (file: File) => Promise<{ url: string }>;
+  className?: string;
+  imageRenderer?: (props: { src: string; alt: string }) => ReactNode;
+  showToolbar?: boolean;
+};
+
+const EDITOR_NODES = [
+  ImageNode,
+  MermaidNode,
+  HeadingNode,
+  QuoteNode,
+  ListNode,
+  ListItemNode,
+  CodeNode,
+  LinkNode,
+  HorizontalRuleNode,
+];
+
+export const MarkdownEditor = ({
+  value,
+  onChange,
+  readOnly = false,
+  placeholder,
+  autoFocus = false,
+  disabled = false,
+  onSave,
+  onCancel,
+  onImageUpload,
+  className,
+  imageRenderer,
+  showToolbar = false,
+}: MarkdownEditorProps) => {
+  const editable = !readOnly && !disabled;
+
+  // Lexical reads editorState only on first render; later prop changes are applied by MarkdownSyncPlugin.
+  const [initialConfig] = useState<InitialConfigType>(() => ({
+    namespace: 'MarkdownEditor',
+    theme: editorTheme,
+    nodes: EDITOR_NODES,
+    onError: (error: Error) => {
+      console.error('[MarkdownEditor] uncaught editor error', error);
+    },
+    editable,
+    editorState: () => {
+      $convertFromMarkdownString(preprocessMarkdown(value), CUSTOM_TRANSFORMERS);
+    },
+  }));
+
+  return (
+    <LexicalComposer initialConfig={initialConfig}>
+      <ImageRendererProvider value={imageRenderer ?? null}>
+        <div className={cn('tw-prose', className)}>
+          {showToolbar && editable && <ToolbarPlugin />}
+          <div
+            className={cn(
+              'tw-relative tw-rounded-md tw-p-2 tw-transition-colors',
+              editable &&
+                'tw-cursor-text hover:tw-bg-neutral-50 focus-within:tw-ring-2 focus-within:tw-ring-secondary-500/40',
+            )}
+          >
+            <RichTextPlugin
+              contentEditable={
+                <ContentEditable
+                  className="tw-min-h-[100px] tw-outline-none"
+                  aria-placeholder={placeholder ?? ''}
+                  placeholder={
+                    placeholder ? (
+                      <div className="tw-pointer-events-none tw-absolute tw-left-2 tw-top-[calc(0.5rem+0.35em)] tw-select-none tw-text-neutral-400">
+                        {placeholder}
+                      </div>
+                    ) : (
+                      <div />
+                    )
+                  }
+                />
+              }
+              ErrorBoundary={LexicalErrorBoundary}
+            />
+          </div>
+          <HistoryPlugin />
+          <LinkPlugin />
+          <ClickableLinkPlugin newTab />
+          <ListPlugin />
+          <CheckListPlugin />
+          <HorizontalRulePlugin />
+          <TabIndentationPlugin />
+          <MarkdownShortcutPlugin transformers={CUSTOM_TRANSFORMERS} />
+          <MarkdownSyncPlugin value={value} editable={editable} onChange={onChange} />
+          <ImagePastePlugin onImageUpload={onImageUpload} />
+          <KeyboardPlugin onSave={onSave} onCancel={onCancel} />
+          {autoFocus && <AutoFocusPlugin />}
+        </div>
+      </ImageRendererProvider>
+    </LexicalComposer>
+  );
+};

package/src/components/MarkdownEditor/context.ts

@@ -0,0 +1,10 @@
+import { createContext, use } from 'react';
+import type { ReactNode } from 'react';
+
+type ImageRenderer = (props: { src: string; alt: string }) => ReactNode;
+
+const ImageRendererContext = createContext<ImageRenderer | null>(null);
+
+export const ImageRendererProvider = ImageRendererContext;
+
+export const useImageRenderer = (): ImageRenderer | null => use(ImageRendererContext);

package/src/components/MarkdownEditor/index.ts

@@ -0,0 +1 @@
+export { MarkdownEditor, type MarkdownEditorProps } from './MarkdownEditor';

package/src/components/MarkdownEditor/nodes/ImageNode.tsx

@@ -0,0 +1,115 @@
+/* eslint-disable react/only-export-components -- Lexical convention: $create/$is helpers co-locate with node */
+import type { ReactNode } from 'react';
+import type {
+  DOMConversionMap,
+  DOMExportOutput,
+  EditorConfig,
+  LexicalNode,
+  NodeKey,
+  SerializedLexicalNode,
+  Spread,
+} from 'lexical';
+import { DecoratorNode } from 'lexical';
+
+import { ImageNodeComponent } from './ImageNodeComponent';
+
+type SerializedImageNode = Spread<{ src: string; altText: string }, SerializedLexicalNode>;
+
+export class ImageNode extends DecoratorNode<ReactNode> {
+  __src: string;
+  __altText: string;
+
+  static getType(): string {
+    return 'image';
+  }
+
+  static clone(node: ImageNode): ImageNode {
+    return new ImageNode(node.__src, node.__altText, node.__key);
+  }
+
+  constructor(src: string, altText: string, key?: NodeKey) {
+    super(key);
+    this.__src = src;
+    this.__altText = altText;
+  }
+
+  getSrc(): string {
+    return this.__src;
+  }
+
+  getAlt(): string {
+    return this.__altText;
+  }
+
+  setSrc(src: string): void {
+    const writable = this.getWritable();
+    writable.__src = src;
+  }
+
+  setAlt(altText: string): void {
+    const writable = this.getWritable();
+    writable.__altText = altText;
+  }
+
+  createDOM(config: EditorConfig): HTMLElement {
+    const span = document.createElement('span');
+    const className = config.theme.image;
+    if (typeof className === 'string') {
+      span.className = className;
+    }
+    return span;
+  }
+
+  updateDOM(): boolean {
+    return false;
+  }
+
+  decorate(): ReactNode {
+    return <ImageNodeComponent src={this.__src} alt={this.__altText} />;
+  }
+
+  isInline(): boolean {
+    return true;
+  }
+
+  static importJSON(serializedNode: SerializedImageNode): ImageNode {
+    return $createImageNode(serializedNode.src, serializedNode.altText);
+  }
+
+  exportJSON(): SerializedImageNode {
+    return {
+      type: 'image',
+      version: 1,
+      src: this.__src,
+      altText: this.__altText,
+    };
+  }
+
+  exportDOM(): DOMExportOutput {
+    const element = document.createElement('img');
+    element.setAttribute('src', this.__src);
+    element.setAttribute('alt', this.__altText);
+    return { element };
+  }
+
+  static importDOM(): DOMConversionMap | null {
+    return {
+      img: () => ({
+        conversion: (domNode: HTMLElement) => {
+          const src = domNode.getAttribute('src') || '';
+          const alt = domNode.getAttribute('alt') || '';
+          return { node: $createImageNode(src, alt) };
+        },
+        priority: 0,
+      }),
+    };
+  }
+}
+
+export const $createImageNode = (src: string, altText: string): ImageNode => {
+  return new ImageNode(src, altText);
+};
+
+export const $isImageNode = (node: LexicalNode | null | undefined): node is ImageNode => {
+  return node instanceof ImageNode;
+};

package/src/components/MarkdownEditor/nodes/ImageNodeComponent.tsx

@@ -0,0 +1,18 @@
+import { useImageRenderer } from '../context';
+
+const isPlaceholder = (src: string) => src.startsWith('upload-placeholder-');
+
+export const ImageNodeComponent = ({ src, alt }: { src: string; alt: string }) => {
+  const renderer = useImageRenderer();
+
+  if (isPlaceholder(src)) {
+    return (
+      <span className="tw-inline-flex tw-items-center tw-gap-1 tw-rounded tw-bg-neutral-100 tw-px-2 tw-py-1 tw-text-xs tw-text-neutral-400">
+        Uploading image…
+      </span>
+    );
+  }
+
+  if (renderer) return <>{renderer({ src, alt })}</>;
+  return <img src={src} alt={alt} />;
+};

package/src/components/MarkdownEditor/nodes/MermaidNode.tsx

@@ -0,0 +1,72 @@
+/* eslint-disable react/only-export-components -- Lexical convention: $create/$is helpers co-locate with node */
+import type { ReactNode } from 'react';
+import type { LexicalNode, NodeKey, SerializedLexicalNode, Spread } from 'lexical';
+import { DecoratorNode } from 'lexical';
+
+import { MermaidNodeComponent } from './MermaidNodeComponent';
+
+type SerializedMermaidNode = Spread<{ code: string }, SerializedLexicalNode>;
+
+export class MermaidNode extends DecoratorNode<ReactNode> {
+  __code: string;
+
+  static getType(): string {
+    return 'mermaid';
+  }
+
+  static clone(node: MermaidNode): MermaidNode {
+    return new MermaidNode(node.__code, node.__key);
+  }
+
+  constructor(code: string, key?: NodeKey) {
+    super(key);
+    this.__code = code;
+  }
+
+  getCode(): string {
+    return this.__code;
+  }
+
+  setCode(code: string): void {
+    const writable = this.getWritable();
+    writable.__code = code;
+  }
+
+  createDOM(): HTMLElement {
+    const div = document.createElement('div');
+    div.setAttribute('data-lexical-mermaid', 'true');
+    return div;
+  }
+
+  updateDOM(): boolean {
+    return false;
+  }
+
+  decorate(): ReactNode {
+    return <MermaidNodeComponent code={this.__code} />;
+  }
+
+  isInline(): boolean {
+    return false;
+  }
+
+  static importJSON(serializedNode: SerializedMermaidNode): MermaidNode {
+    return $createMermaidNode(serializedNode.code);
+  }
+
+  exportJSON(): SerializedMermaidNode {
+    return {
+      type: 'mermaid',
+      version: 1,
+      code: this.__code,
+    };
+  }
+}
+
+export const $createMermaidNode = (code: string): MermaidNode => {
+  return new MermaidNode(code);
+};
+
+export const $isMermaidNode = (node: LexicalNode | null | undefined): node is MermaidNode => {
+  return node instanceof MermaidNode;
+};

package/src/components/MarkdownEditor/nodes/MermaidNodeComponent.tsx

@@ -0,0 +1,35 @@
+import { lazy, Suspense } from 'react';
+
+import { Skeleton } from '../../../components/Skeleton/Skeleton';
+
+const MermaidDiagram = lazy(() =>
+  import('../../../blocks/MermaidDiagram/MermaidDiagram').then(
+    (m) => ({ default: m.MermaidDiagram }),
+    (error: unknown) => {
+      // Falling back to raw code on chunk-load failure (typically a stale tab after deploy).
+      // Logging so we don't silently swap implementations.
+      console.error('[MarkdownEditor] failed to load MermaidDiagram chunk', error);
+      return {
+        default: ({ code }: { code: string }) => (
+          <pre>
+            <code>{code}</code>
+          </pre>
+        ),
+      };
+    },
+  ),
+);
+
+export const MermaidNodeComponent = ({ code }: { code: string }) => {
+  return (
+    <Suspense
+      fallback={
+        <div className="tw-my-3 tw-overflow-hidden tw-rounded-card tw-border tw-border-neutral-150 tw-bg-neutral-50 tw-p-6">
+          <Skeleton className="tw-h-40" />
+        </div>
+      }
+    >
+      <MermaidDiagram code={code} />
+    </Suspense>
+  );
+};

package/src/components/MarkdownEditor/plugins/ImagePastePlugin.tsx

@@ -0,0 +1,149 @@
+import { useEffect, useRef } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import type { NodeKey } from 'lexical';
+import {
+  $getNodeByKey,
+  $insertNodes,
+  COMMAND_PRIORITY_CRITICAL,
+  DROP_COMMAND,
+  PASTE_COMMAND,
+} from 'lexical';
+
+import { toast } from '../../Toast/toast';
+import { $createImageNode, $isImageNode } from '../nodes/ImageNode';
+
+const ACCEPTED_IMAGE_TYPES = [
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+];
+
+const MAX_IMAGE_SIZE = 10 * 1024 * 1024; // 10 MB
+
+const PLACEHOLDER_PREFIX = 'upload-placeholder-';
+
+const generatePlaceholderId = (): string => {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+};
+
+const isAcceptedImageType = (type: string) => ACCEPTED_IMAGE_TYPES.includes(type);
+
+const getImageFilesFromDataTransfer = (dataTransfer: DataTransfer | null): File[] => {
+  if (!dataTransfer) return [];
+
+  if (dataTransfer.items.length > 0) {
+    const files: File[] = [];
+    for (const item of dataTransfer.items) {
+      if (item.kind === 'file' && isAcceptedImageType(item.type)) {
+        const file = item.getAsFile();
+        if (file) files.push(file);
+      }
+    }
+    if (files.length > 0) return files;
+  }
+
+  return Array.from(dataTransfer.files).filter((file) => isAcceptedImageType(file.type));
+};
+
+const escapeMarkdownAlt = (text: string) => text.replace(/[[\]()]/g, '');
+
+type ImagePastePluginProps = {
+  onImageUpload?: (file: File) => Promise<{ url: string }>;
+};
+
+export const ImagePastePlugin = ({ onImageUpload }: ImagePastePluginProps) => {
+  const [editor] = useLexicalComposerContext();
+  const onImageUploadRef = useRef(onImageUpload);
+  onImageUploadRef.current = onImageUpload;
+
+  useEffect(() => {
+    const uploadFile = (file: File) => {
+      const upload = onImageUploadRef.current;
+      if (!upload) return;
+
+      if (file.size > MAX_IMAGE_SIZE) {
+        toast.error(`Image "${file.name}" is too large. Maximum size is 10 MB.`);
+        return;
+      }
+
+      // Insert placeholder and start upload outside the command handler
+      // to avoid nested editor.update() batching issues
+      let nodeKey: NodeKey | null = null;
+
+      editor.update(() => {
+        const placeholderNode = $createImageNode(
+          `${PLACEHOLDER_PREFIX}${generatePlaceholderId()}`,
+          'Uploading image\u2026',
+        );
+        $insertNodes([placeholderNode]);
+        nodeKey = placeholderNode.getKey();
+      });
+
+      if (!nodeKey) return;
+      const capturedKey: NodeKey = nodeKey;
+
+      upload(file)
+        .then(({ url }) => {
+          editor.update(() => {
+            const node = $getNodeByKey(capturedKey);
+            if ($isImageNode(node)) {
+              const altText = escapeMarkdownAlt(file.name.replace(/\.[^.]+$/, '') || 'image');
+              node.setSrc(url);
+              node.setAlt(altText);
+            }
+          });
+        })
+        .catch((error: unknown) => {
+          console.error('[MarkdownEditor] image upload failed', error);
+          toast.error(`Failed to upload "${file.name}". Please try again.`);
+          editor.update(() => {
+            const node = $getNodeByKey(capturedKey);
+            if (node) node.remove();
+          });
+        });
+    };
+
+    const removePaste = editor.registerCommand(
+      PASTE_COMMAND,
+      (event) => {
+        if (!onImageUploadRef.current) return false;
+        if (!(event instanceof ClipboardEvent)) return false;
+        const files = getImageFilesFromDataTransfer(event.clipboardData);
+        if (files.length === 0) return false;
+
+        event.preventDefault();
+        // Defer upload to next microtask to escape the command handler's update context
+        Promise.resolve().then(() => files.forEach(uploadFile));
+        return true;
+      },
+      COMMAND_PRIORITY_CRITICAL,
+    );
+
+    const removeDrop = editor.registerCommand(
+      DROP_COMMAND,
+      (event: DragEvent) => {
+        if (!onImageUploadRef.current) return false;
+        const files = getImageFilesFromDataTransfer(event.dataTransfer);
+        if (files.length === 0) return false;
+
+        event.preventDefault();
+        // Defer upload to next microtask to escape the command handler's update context
+        Promise.resolve().then(() => files.forEach(uploadFile));
+        return true;
+      },
+      COMMAND_PRIORITY_CRITICAL,
+    );
+
+    return () => {
+      removePaste();
+      removeDrop();
+    };
+  }, [editor]);
+
+  return null;
+};

package/src/components/MarkdownEditor/plugins/KeyboardPlugin.tsx

@@ -0,0 +1,37 @@
+import { useEffect, useRef } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { COMMAND_PRIORITY_HIGH, KEY_DOWN_COMMAND } from 'lexical';
+
+type KeyboardPluginProps = {
+  onSave?: () => void;
+  onCancel?: () => void;
+};
+
+export const KeyboardPlugin = ({ onSave, onCancel }: KeyboardPluginProps) => {
+  const [editor] = useLexicalComposerContext();
+  const onSaveRef = useRef(onSave);
+  onSaveRef.current = onSave;
+  const onCancelRef = useRef(onCancel);
+  onCancelRef.current = onCancel;
+
+  useEffect(() => {
+    return editor.registerCommand(
+      KEY_DOWN_COMMAND,
+      (event: KeyboardEvent) => {
+        if (event.key === 'Enter' && (event.ctrlKey || event.metaKey)) {
+          event.preventDefault();
+          onSaveRef.current?.();
+          return true;
+        }
+        if (event.key === 'Escape') {
+          onCancelRef.current?.();
+          return true;
+        }
+        return false;
+      },
+      COMMAND_PRIORITY_HIGH,
+    );
+  }, [editor]);
+
+  return null;
+};

package/src/components/MarkdownEditor/plugins/MarkdownSyncPlugin.tsx

@@ -0,0 +1,56 @@
+import { useEffect, useRef } from 'react';
+import { $convertFromMarkdownString, $convertToMarkdownString } from '@lexical/markdown';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+
+import { CUSTOM_TRANSFORMERS, postprocessMarkdown, preprocessMarkdown } from '../transformers';
+
+const IMPORT_TAG = 'markdown-import';
+
+type MarkdownSyncPluginProps = {
+  value: string;
+  editable: boolean;
+  onChange?: (markdown: string) => void;
+};
+
+export const MarkdownSyncPlugin = ({ value, editable, onChange }: MarkdownSyncPluginProps) => {
+  const [editor] = useLexicalComposerContext();
+  const lastExportedRef = useRef(value);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  // Sync editable state — only when it actually changes
+  useEffect(() => {
+    editor.setEditable(editable);
+  }, [editor, editable]);
+
+  // Import: external value -> editor state
+  useEffect(() => {
+    if (value === lastExportedRef.current) return;
+    lastExportedRef.current = value;
+
+    editor.update(
+      () => {
+        $convertFromMarkdownString(preprocessMarkdown(value), CUSTOM_TRANSFORMERS);
+      },
+      { tag: IMPORT_TAG },
+    );
+  }, [editor, value]);
+
+  // Export: editor state -> onChange (subscription)
+  useEffect(() => {
+    return editor.registerUpdateListener(({ tags }) => {
+      if (tags.has(IMPORT_TAG)) return;
+
+      editor.getEditorState().read(() => {
+        const raw = $convertToMarkdownString(CUSTOM_TRANSFORMERS);
+        const markdown = postprocessMarkdown(raw);
+        if (markdown !== lastExportedRef.current) {
+          lastExportedRef.current = markdown;
+          onChangeRef.current?.(markdown);
+        }
+      });
+    });
+  }, [editor]);
+
+  return null;
+};