@apify/ui-library 0.51.6-featurepublishuilibrary-0a4729.38266

package/src/components/readme_renderer/table_of_contents.tsx

@@ -0,0 +1,257 @@
+import _ from 'lodash';
+import React, {
+    useMemo,
+    useCallback,
+} from 'react';
+import ReactMarkdown from 'react-markdown';
+import type { AllowElement } from 'react-markdown/lib/rehype-filter';
+import remarkToc from 'remark-toc';
+import styled from 'styled-components';
+
+import { theme } from '../../design_system/theme';
+import { inlineCodeStyles } from '../code';
+import { Link } from '../link';
+import { Text } from '../text';
+import { cleanMarkdown, slugifyHeadingChildren } from './utils';
+
+const TOC_HEADING_ID = 'Contents';
+
+const StyledTOCLink = styled(Text)`
+    display: inline-block;
+    color: ${theme.color.neutral.textMuted};
+    text-decoration: none;
+
+    /* Do no change the font style if the heading is defined as bold in the markdown and is wrapped in a <strong> tag */
+    strong {
+        font-size: inherit !important;
+        line-height: inherit !important;
+        font-weight: inherit !important;
+    }
+
+    &:hover, &.selected {
+        color: ${theme.color.primary.text} !important;
+    }
+
+    &:before {
+        content: " ";
+        display: inline-block;
+        height: 100%;
+        left: 0;
+        margin-top: -1px;
+        position: absolute;
+        width: 1px;
+        background-color: ${theme.color.neutral.border};
+    }
+
+    &.selected:before {
+        background-color: ${theme.color.primary.text};
+    }
+`;
+
+const StyledTableOfContents = styled.div`
+    position: relative;
+    overflow: hidden;
+
+    p {
+        margin: 0;
+    }
+
+    .level-3 a {
+        color: ${theme.color.neutral.textSubtle};
+    }
+
+    ul {
+        padding-left: ${theme.space.space8} !important;
+        list-style: none;
+        margin: 0;
+        overflow-y: auto;
+
+        &.level-3 {
+            padding-left: ${theme.space.space16} !important;
+            max-height: 0;
+            overflow: hidden;
+            transition: all .3s ease-in-out;
+
+            &.expanded {
+                max-height: 1000px;
+            }
+        }
+    }
+
+    .inline-code {
+        ${inlineCodeStyles}
+    }
+`;
+
+interface CustomHTMLAnchorElement extends Omit<HTMLAnchorElement, 'children' | 'parentNode'> {
+    hash: string;
+    tagName: string;
+    type: string;
+    parentNode: any;
+}
+
+const handleScroll = (anchors: CustomHTMLAnchorElement[] | null, headlines: HTMLElement[], anchorLists: HTMLUListElement[] | null, headingOffsetPx: number) => {
+    if (!anchors || !headlines) return;
+
+    // Items that are past scroll
+    const headlinesPastScrollPosition = headlines.filter((headline) => {
+        return headline.getBoundingClientRect().top - headingOffsetPx < 0;
+    });
+
+    // Last item that is past the scroll is current in view. If no headline is past the scroll, let's select the first one
+    const currentHeadlineId = headlinesPastScrollPosition[headlinesPastScrollPosition.length - 1]?.id || headlines[0]?.id;
+
+    // Highlighting anchor of current headline
+    if (currentHeadlineId) {
+        const currentHash = `#${currentHeadlineId}`;
+
+        anchorLists?.forEach((anchorList) => anchorList.classList.remove('expanded'));
+
+        // Remove selected class from all anchors and only add it to the current one
+        anchors.forEach((anchor) => {
+            anchor.classList.remove('selected');
+            if (anchor.hash === currentHash) {
+                anchor.classList.add('selected');
+
+                const grandparent = anchor.parentNode?.parentNode;
+
+                // Structure of the table of content is normalized so we can figure out if section should be expanded
+                // by tag and className of neighboring nodes. There are two cases:
+
+                // 1) If h2 is selected, we want to expand its section with h3 headings
+                if (grandparent?.tagName === 'LI' && grandparent.children[1]?.tagName === 'UL' && grandparent.children[1]?.classList.contains('level-3')) {
+                    grandparent.children[1].classList.add('expanded');
+                }
+
+                // 2) We also want to expand section of h3 headings that follow h1 right away
+                if (grandparent?.tagName === 'UL' && grandparent.classList.contains('level-3')) {
+                    grandparent.classList.add('expanded');
+                }
+            }
+        });
+    }
+};
+
+const assignHeadingLevelsRecursively = ({ children, tagName, properties }: any, level: number) => {
+    if (level > 3) return;
+    if (tagName === 'ul') {
+        properties.className = `level-${level}`; // assign level className
+        level += 1; // increase current heading level;
+    }
+
+    children?.forEach((child: { type: string }) => {
+        // We only care about ul and li elements - we don't need to traverse any other
+        if (child.type === 'element' && (tagName === 'ul' || tagName === 'li')) {
+            assignHeadingLevelsRecursively(child, level);
+        }
+    });
+};
+
+export interface TableOfContentsProps {
+    markdown: string;
+    headingOffsetPx?: number; // How far from the top should the toc detect the current heading
+    // Function where we can define which elements are allowed in the markdown. See https://github.com/remarkjs/react-markdown#props for more info
+    allowElement?: AllowElement;
+}
+
+const TableOfContents = ({
+    markdown,
+    headingOffsetPx = 10,
+    allowElement,
+    ...rest
+}: TableOfContentsProps) => {
+    const cleanedMarkdown = useMemo(() => {
+        const cleanedMarkdownString = cleanMarkdown(markdown);
+        return `### ${TOC_HEADING_ID}\n${cleanedMarkdownString}`;
+    }, [markdown]);
+
+    const hasTopLevelHeading = useMemo(() => !!cleanedMarkdown.match(/^#\s.+$/m), [cleanedMarkdown]);
+
+    const tocRef = useCallback((node: HTMLElement | null) => {
+        const anchors = node ? Array.from(node.querySelectorAll('a')) : null;
+        const anchorLists = node ? Array.from(node.querySelectorAll('ul')) : null;
+        const headlines = (anchors || [])
+            .map((anchor) => document.getElementById(anchor.hash.substr(1)))
+            .filter((headline) => headline !== undefined && headline !== null) as HTMLElement[];
+
+        const scrollHandler = () => handleScroll(anchors, headlines, anchorLists, headingOffsetPx);
+
+        // Callback refs cannot return cleanup functions - but they are called again with null on unmount
+        if (node) {
+            window.addEventListener('scroll', scrollHandler);
+        } else {
+            window.removeEventListener('scroll', scrollHandler);
+        }
+        scrollHandler(); // call for the first time so we select the first heading without scrolling
+    }, [headingOffsetPx]);
+
+    return (
+        <StyledTableOfContents ref={tocRef} {...rest}>
+            <ReactMarkdown
+                allowElement={allowElement}
+                remarkPlugins={[
+                    [remarkToc, { heading: TOC_HEADING_ID, maxDepth: 3 }],
+                    () => ({ children, ...nodeRest }) => {
+                        // TOC plug-ins only inject content table to existing markdown documents - only generating it is not a common use-case
+                        // To make is happen, we can just take the generated node where toc is located and throw away the rest.
+                        // children[0] is the heading where toc is placed (that's plug-in's requirement)
+                        // children[1] is the generated table of contents we can simply pick
+
+                        let tocContentNode = children[1];
+
+                        // If there is no H1 heading in the readme then assignHeadingLevelsRecursively does not work correctly.
+                        // We need to 'normalize' the final node to have all the levels we expect
+                        // - solution is to wrap the content in extra node that mimic this H1 group that remarkToc would normally create
+                        if (!hasTopLevelHeading) {
+                            tocContentNode = {
+                                type: 'list',
+                                ordered: false,
+                                spread: false,
+                                children: [
+                                    {
+                                        type: 'listItem',
+                                        spread: true,
+                                        children: [
+                                            tocContentNode,
+                                        ],
+                                    },
+                                ],
+                            };
+                        }
+
+                        return {
+                            ...nodeRest,
+                            children: [
+                                tocContentNode,
+                            ],
+                        };
+                    },
+                ]}
+                rehypePlugins={[() => (input) => {
+                    // this plug-in already works with html node representation so we can assign classNames that we need
+                    // in order to allow hiding blocks with h3 headings that are out of the viewport
+                    assignHeadingLevelsRecursively(input.children[0], 1);
+                    return input;
+                }]}
+                components={{
+                    a: ({ children }) => (
+                        <StyledTOCLink
+                            forwardedAs={Link}
+                            to={`#${slugifyHeadingChildren(children)}`}
+                            py={'space4'}
+                        >
+                            {children}
+                        </StyledTOCLink>
+                    ),
+                    code: ({ children }) => (
+                        <code className="inline-code">{children}</code>
+                    ),
+                }}
+            >
+                {cleanedMarkdown}
+            </ReactMarkdown>
+        </StyledTableOfContents>
+    );
+};
+
+export default React.memo(TableOfContents, (prevProps, nextProps) => _.isEqual(prevProps, nextProps));

package/src/components/readme_renderer/utils.tsx

@@ -0,0 +1,46 @@
+import React, { useCallback } from 'react';
+import type { AllowElement } from 'react-markdown/lib/rehype-filter';
+import slugify from 'slugify';
+
+export const slugifyHeadingChildren = (
+    headingChildren: React.ReactNode,
+): string | undefined => {
+    if (!headingChildren) return undefined;
+
+    const slugs: string[] = [];
+    React.Children.forEach(headingChildren, (child) => {
+        if (typeof child === 'string') {
+            slugs.push(slugify(child, { lower: true, strict: true }));
+        } else if (React.isValidElement(child) && child.props.children) {
+            const nestedSlugs = slugifyHeadingChildren(child.props.children);
+            if (nestedSlugs) slugs.push(nestedSlugs);
+        }
+    });
+
+    return slugs.join('-');
+};
+
+export const cleanMarkdown = (markdown: string, removeFirstH1?: boolean): string => {
+    // Remove the table of contents as we are generating our own
+    let clean = markdown
+        .replace(/<!-- toc start -->.*?<!-- toc end -->/s, '')
+        .replace(/##.*content.*?\n*<!-- toc -->(.|[\r\n])*<!-- tocstop -->\n*/, '');
+
+    // Remove first h1 if removeFirstH1 is true
+    if (removeFirstH1) clean = clean.replace(removeFirstH1 ? /^#\s.+$/m : '', '');
+
+    return clean.trim();
+};
+
+// This removes the first element if it's a `h1` containing exactly the Actor title
+export const useActorTitleHeadingFilter = (actorTitle: string): AllowElement => {
+    return useCallback((element, index, parent) => {
+        if (parent.type === 'root'
+            && index === 0
+            && element.tagName === 'h1'
+            && element.children.length === 1
+            && element.children[0].type === 'text'
+            && element.children[0].value?.toLowerCase() === actorTitle.toLowerCase()) return false;
+        return true;
+    }, [actorTitle]);
+};

package/src/components/simple_markdown/index.tsx

@@ -0,0 +1,2 @@
+export * from './simple_markdown';
+export * from './simple_markdown_components';

package/src/components/simple_markdown/simple_markdown.tsx

@@ -0,0 +1,181 @@
+import React, { useCallback, useMemo, useRef } from 'react';
+import type { Components } from 'react-markdown';
+import ReactMarkdown, { uriTransformer } from 'react-markdown';
+import type { ReactMarkdownOptions } from 'react-markdown/lib/react-markdown';
+import rehypeRaw from 'rehype-raw';
+import rehypeSanitize from 'rehype-sanitize';
+import remarkGfm from 'remark-gfm';
+import styled from 'styled-components';
+
+import { theme } from '../../design_system/theme';
+import { useSharedUiDependencies } from '../../ui_dependency_provider';
+import { Box } from '../box';
+import { isUrlExternal } from '../link';
+import { cleanMarkdown } from '../readme_renderer/utils';
+import { Heading, Text } from '../text';
+import { HeadingContent } from '../text/heading_content';
+import { TextContent } from '../text/text_content';
+import {
+    MarkdownBlockQuote,
+    MarkdownCode,
+    MarkdownLink,
+    MarkdownTable,
+} from './simple_markdown_components';
+
+export type SimpleMarkdownComponents = Components;
+
+const StyledMarkdown = styled(ReactMarkdown)`
+    scroll-margin-top: 10px;
+
+    @font-face {
+        font-family: "ellipsis-font";
+        src: local("Courier");
+        unicode-range: U+2026;
+        size-adjust: 0%;
+    }
+
+    img {
+        max-width: 100%;
+    }
+
+    hr {
+        color: ${theme.color.neutral.border};
+    }
+`;
+
+export const defaultRehypePlugins = [rehypeRaw];
+export const defaultRemarkPlugins = [remarkGfm];
+export const defaultAllowedElements = [
+    'a',
+    'b',
+    'blockquote',
+    'br',
+    'center',
+    'code',
+    'del',
+    'em',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'hr',
+    'i',
+    'img',
+    'li',
+    'ol',
+    'p',
+    'pre',
+    'span',
+    'strong',
+    'table',
+    'tbody',
+    'td',
+    'tfoot',
+    'th',
+    'thead',
+    'tr',
+    'u',
+    'ul',
+];
+
+// TODO: Add Image component
+const regularMarkdownSizeComponents: Components = {
+    h1: ({ children }) => <HeadingContent mt='space32' mb='space16' type='heading1'>{children}</HeadingContent>,
+    h2: ({ children }) => <HeadingContent mt='space32' mb='space16' type='heading2'>{children}</HeadingContent>,
+    h3: ({ children }) => <HeadingContent mt='space32' mb='space16' type='heading3'>{children}</HeadingContent>,
+    h4: ({ children }) => <HeadingContent mt='space32' mb='space16' type='heading4'>{children}</HeadingContent>,
+    h5: ({ children }) => <HeadingContent mt='space32' mb='space16' type='heading5'>{children}</HeadingContent>,
+    h6: ({ children }) => <HeadingContent mt='space32' mb='space16' type='heading6'>{children}</HeadingContent>,
+    p: ({ children }) => (<TextContent my='space16'>{children}</TextContent>),
+    strong: ({ children }) => <TextContent as='strong' weight='bold'>{children}</TextContent>,
+    b: ({ children }) => <TextContent as='b' weight='bold'>{children}</TextContent>,
+    th: ({ children }) => <TextContent as='th' weight='bold'>{children}</TextContent>,
+    blockquote: ({ children }) => <MarkdownBlockQuote>{children}</MarkdownBlockQuote>,
+    table: ({ children }) => <MarkdownTable>{children}</MarkdownTable>,
+    ul: ({ children }) => <Box as='ul' pl='space32'>{children}</Box>,
+    ol: ({ children, start }) => <Box as='ol' pl='space32' start={start}>{children}</Box>,
+    li: ({ children }) => <Box as='li' mt='space4'>{children}</Box>,
+    a: ({ children, href }) => <MarkdownLink to={href}>{children}</MarkdownLink>,
+    code: ({ children, inline }) => <MarkdownCode inline={inline} size='regular'>{children}</MarkdownCode>,
+};
+
+const smallMarkdownSizeComponents: Components = {
+    h1: ({ children }) => <Heading mt='space32' mb='space16' type='title2xl'>{children}</Heading>,
+    h2: ({ children }) => <Heading mt='space32' mb='space16' type='titleXl'>{children}</Heading>,
+    h3: ({ children }) => <Heading mt='space32' mb='space16' type='titleL'>{children}</Heading>,
+    h4: ({ children }) => <Heading mt='space32' mb='space16' type='titleM'>{children}</Heading>,
+    h5: ({ children }) => <Heading mt='space32' mb='space16' type='titleS'>{children}</Heading>,
+    h6: ({ children }) => <Heading mt='space32' mb='space16' type='titleXs'>{children}</Heading>,
+    p: ({ children }) => (<Text my='space16'>{children}</Text>),
+    strong: ({ children }) => <Text as='strong' weight='bold'>{children}</Text>,
+    b: ({ children }) => <Text as='b' weight='bold'>{children}</Text>,
+    th: ({ children }) => <Text as='th' weight='bold'>{children}</Text>,
+    blockquote: ({ children }) => <MarkdownBlockQuote>{children}</MarkdownBlockQuote>,
+    table: ({ children }) => <MarkdownTable>{children}</MarkdownTable>,
+    ul: ({ children }) => <Box as='ul' pl='space32'>{children}</Box>,
+    ol: ({ children, start }) => <Box as='ol' pl='space32' start={start}>{children}</Box>,
+    li: ({ children }) => <Box as='li' mt='space4'>{children}</Box>,
+    a: ({ children, href }) => <MarkdownLink to={href}>{children}</MarkdownLink>,
+    code: ({ children, inline }) => <MarkdownCode inline={inline} size='small'>{children}</MarkdownCode>,
+};
+
+type MarkdownSize = 'regular' | 'small';
+
+interface SimpleMarkdownProps extends ReactMarkdownOptions {
+    size?: MarkdownSize,
+}
+
+const useDefaultUrlTransform = () => {
+    const { windowLocationHost } = useSharedUiDependencies();
+
+    return useCallback((url: string) => {
+        if (!isUrlExternal(url, windowLocationHost)) {
+            // We want to make sure internal links will be relative links without https://host at the beginning because Link doesn't work with these
+            return url.replace(/^(https?:\/\/)?(www\.)?[^/]+/, '') || '/';
+        }
+
+        return url;
+    }, [windowLocationHost]);
+};
+
+export const SimpleMarkdown: React.FC<SimpleMarkdownProps> = ({
+    size = 'regular', // small is default for console
+    children: markdown,
+    components,
+    rehypePlugins,
+    remarkPlugins,
+    transformLinkUri,
+    allowedElements,
+    ...rest
+}) => {
+    const cleanedMarkdown = useMemo(() => cleanMarkdown(markdown), [markdown]);
+
+    const effectiveComponents = useRef({
+        ...(size === 'regular' ? regularMarkdownSizeComponents : smallMarkdownSizeComponents),
+        ...components,
+    });
+
+    const rehypePluginsRef = useRef([
+        ...(rehypePlugins || defaultRehypePlugins),
+        rehypeSanitize, // lets always sanitize the output
+    ]);
+
+    const defaultUrlTransform = useDefaultUrlTransform();
+
+    return (
+        <StyledMarkdown
+            components={effectiveComponents.current}
+            rehypePlugins={rehypePluginsRef.current}
+            remarkPlugins={remarkPlugins || defaultRemarkPlugins}
+            allowedElements={allowedElements || defaultAllowedElements}
+            transformLinkUri={(href, children, title) => {
+                const transformed = transformLinkUri ? transformLinkUri(href, children, title) : defaultUrlTransform(href);
+                return uriTransformer(transformed);
+            }}
+            {...rest}
+        >
+            {cleanedMarkdown}
+        </StyledMarkdown>
+    );
+};