@apify/ui-library 1.119.0 → 1.120.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@apify/ui-library",
-    "version": "1.119.0",
+    "version": "1.120.0",
     "description": "React UI library used by apify.com",
     "license": "Apache-2.0",
     "type": "module",
@@ -64,5 +64,5 @@
         "src",
         "style"
     ],
-    "gitHead": "5c6e9bc263b489ab938a090589b1a291fcb7f381"
+    "gitHead": "ad7a5921f83c7575ecea7fca3b3843cdc7f04a8f"
 }

package/src/components/card_container.stories.tsx

@@ -7,7 +7,7 @@ import { CardContainer, type CardContainerProps } from './card_container.js';
 import { IconButton } from './icon_button.js';
 
 export default {
-    title: 'UI-Library/CardContainer',
+    title: 'UI-Library/Cards/CardContainer',
     component: CardContainer,
     argTypes: {
         headerPlacement: {
@@ -15,6 +15,7 @@ export default {
             options: ['TOP', 'BOTTOM'],
         },
     },
+    tags: ['new'],
 } as Meta<CardContainerProps>;
 
 type Story = StoryObj<CardContainerProps>;

package/src/components/code/code_block/code_block.stories.jsx

@@ -1,7 +1,7 @@
 import { CodeBlock } from './code_block.tsx';
 
 export default {
-    title: 'ui-library/CodeBlock',
+    title: 'ui-library/Code/CodeBlock',
     parameters: {
         layout: 'centered',
         design: {

package/src/components/code/inline_code/inline_code.stories.tsx

@@ -9,7 +9,7 @@ import { InlineCode } from './inline_code.js';
  * including different sizes and copy button functionality.
  */
 export default {
-    title: 'ui-library/InlineCode',
+    title: 'ui-library/Code/InlineCode',
     component: InlineCode,
     tags: [],
     argTypes: {

package/src/components/code/one_line_code/one_line_code.stories.tsx

@@ -8,7 +8,7 @@ import { OneLineCode, type OneLineCodeProps } from './one_line_code.js';
  * including different languages, HTTP methods, and interactive features.
  */
 export default {
-    title: 'ui-library/OneLineCode',
+    title: 'ui-library/Code/OneLineCode',
     component: OneLineCode,
     tags: [],
     argTypes: {

package/src/components/readme_renderer/table_of_contents.stories.tsx

@@ -0,0 +1,476 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import styled from 'styled-components';
+
+import { TableOfContents, type TableOfContentsProps } from './table_of_contents.js';
+
+export default {
+    title: 'UI-Library/TableOfContents',
+    component: TableOfContents,
+    argTypes: {
+        markdown: {
+            control: 'text',
+            description: 'The markdown content to generate table of contents from',
+        },
+        headingOffsetPx: {
+            control: { type: 'number', min: 0 },
+            description: 'Offset from the top for detecting current heading position',
+        },
+        allowElement: {
+            control: false,
+            description: 'Function to filter allowed markdown elements',
+        },
+    },
+} as Meta<TableOfContentsProps>;
+
+type Story = StoryObj<TableOfContentsProps>;
+
+const StoryWrapper = styled.div`
+    display: grid;
+    grid-template-columns: 250px 1fr;
+    gap: 2rem;
+    max-width: 1200px;
+`;
+
+const ContentArea = styled.div`
+    padding: 2rem;
+
+    h1, h2, h3 {
+        margin-top: 3rem;
+        margin-bottom: 1rem;
+    }
+
+    p {
+        margin-bottom: 1rem;
+        line-height: 1.6;
+    }
+`;
+
+const TOCContainer = styled.div`
+    position: sticky;
+    top: 2rem;
+    max-height: calc(100vh - 4rem);
+    overflow-y: auto;
+`;
+
+const basicMarkdown = `# Getting Started
+
+This is the introduction section with some content.
+
+## Installation
+
+Instructions for installing the package.
+
+## Configuration
+
+How to configure your project.
+
+### Basic Setup
+
+Initial configuration steps.
+
+### Advanced Options
+
+More complex configuration scenarios.
+
+## Usage
+
+Examples of how to use the component.
+
+### Basic Example
+
+A simple usage example.
+
+### Advanced Example
+
+A more complex usage scenario.
+
+## API Reference
+
+Details about the API.
+`;
+
+const markdownWithoutH1 = `## Overview
+
+This document starts with H2 headings.
+
+## Features
+
+List of available features.
+
+### Feature One
+
+Description of the first feature.
+
+### Feature Two
+
+Description of the second feature.
+
+## Installation
+
+How to install.
+
+### Prerequisites
+
+What you need before installing.
+
+### Steps
+
+Installation steps.
+`;
+
+const longMarkdown = `# Comprehensive Guide
+
+An extensive guide with many sections.
+
+## Section 1: Introduction
+
+Introduction content here.
+
+### Subsection 1.1
+
+Details about subsection 1.1.
+
+### Subsection 1.2
+
+Details about subsection 1.2.
+
+### Subsection 1.3
+
+Details about subsection 1.3.
+
+## Section 2: Getting Started
+
+Getting started content.
+
+### Subsection 2.1
+
+More details here.
+
+### Subsection 2.2
+
+Additional information.
+
+### Subsection 2.3
+
+Even more content.
+
+## Section 3: Core Concepts
+
+Core concepts explained.
+
+### Subsection 3.1
+
+First concept.
+
+### Subsection 3.2
+
+Second concept.
+
+### Subsection 3.3
+
+Third concept.
+
+## Section 4: Advanced Topics
+
+Advanced material.
+
+### Subsection 4.1
+
+Advanced topic 1.
+
+### Subsection 4.2
+
+Advanced topic 2.
+
+## Section 5: Examples
+
+Code examples and use cases.
+
+### Subsection 5.1
+
+Example 1.
+
+### Subsection 5.2
+
+Example 2.
+
+## Section 6: Troubleshooting
+
+Common issues and solutions.
+
+### Subsection 6.1
+
+Issue 1.
+
+### Subsection 6.2
+
+Issue 2.
+
+## Section 7: FAQ
+
+Frequently asked questions.
+
+### Question 1
+
+Answer to question 1.
+
+### Question 2
+
+Answer to question 2.
+
+## Conclusion
+
+Final thoughts and summary.
+`;
+
+const markdownWithCode = `# API Documentation
+
+Documentation with code examples in headings.
+
+## \`initialize()\` Method
+
+Details about the initialize method.
+
+### Parameters
+
+List of parameters.
+
+### Return Value
+
+What the method returns.
+
+## \`configure(options)\` Method
+
+Configuration method details.
+
+### \`options.setting1\`
+
+First setting.
+
+### \`options.setting2\`
+
+Second setting.
+
+## Usage Examples
+
+How to use the API.
+`;
+
+const simpleMarkdown = `# Quick Start
+
+A simple document.
+
+## Step 1
+
+First step.
+
+## Step 2
+
+Second step.
+
+## Step 3
+
+Third step.
+`;
+
+/**
+ * Basic table of contents with H1, H2, and H3 headings
+ */
+export const Default: Story = {
+    args: {
+        markdown: basicMarkdown,
+    },
+    render: (args) => (
+        <StoryWrapper>
+            <TOCContainer>
+                <TableOfContents {...args} />
+            </TOCContainer>
+            <ContentArea dangerouslySetInnerHTML={{ __html: `
+                <h1 id="getting-started">Getting Started</h1>
+                <p>This is the introduction section with some content.</p>
+
+                <h2 id="installation">Installation</h2>
+                <p>Instructions for installing the package.</p>
+
+                <h2 id="configuration">Configuration</h2>
+                <p>How to configure your project.</p>
+
+                <h3 id="basic-setup">Basic Setup</h3>
+                <p>Initial configuration steps.</p>
+
+                <h3 id="advanced-options">Advanced Options</h3>
+                <p>More complex configuration scenarios.</p>
+
+                <h2 id="usage">Usage</h2>
+                <p>Examples of how to use the component.</p>
+
+                <h3 id="basic-example">Basic Example</h3>
+                <p>A simple usage example.</p>
+
+                <h3 id="advanced-example">Advanced Example</h3>
+                <p>A more complex usage scenario.</p>
+
+                <h2 id="api-reference">API Reference</h2>
+                <p>Details about the API.</p>
+            ` }} />
+        </StoryWrapper>
+    ),
+};
+
+/**
+ * Table of contents for markdown without H1 heading
+ */
+export const WithoutH1Heading: Story = {
+    args: {
+        markdown: markdownWithoutH1,
+    },
+    render: (args) => (
+        <StoryWrapper>
+            <TOCContainer>
+                <TableOfContents {...args} />
+            </TOCContainer>
+            <ContentArea dangerouslySetInnerHTML={{ __html: `
+                <h2 id="overview">Overview</h2>
+                <p>This document starts with H2 headings.</p>
+
+                <h2 id="features">Features</h2>
+                <p>List of available features.</p>
+
+                <h3 id="feature-one">Feature One</h3>
+                <p>Description of the first feature.</p>
+
+                <h3 id="feature-two">Feature Two</h3>
+                <p>Description of the second feature.</p>
+
+                <h2 id="installation">Installation</h2>
+                <p>How to install.</p>
+
+                <h3 id="prerequisites">Prerequisites</h3>
+                <p>What you need before installing.</p>
+
+                <h3 id="steps">Steps</h3>
+                <p>Installation steps.</p>
+            ` }} />
+        </StoryWrapper>
+    ),
+};
+
+/**
+ * Table of contents with many sections (scrollable)
+ */
+export const ManySection: Story = {
+    args: {
+        markdown: longMarkdown,
+    },
+    render: (args) => (
+        <StoryWrapper>
+            <TOCContainer>
+                <TableOfContents {...args} />
+            </TOCContainer>
+            <ContentArea>
+                <p style={{ marginBottom: '2rem' }}>
+                    Scroll down to see the table of contents highlighting different sections.
+                    The TOC stays sticky while scrolling through content.
+                </p>
+                {Array.from({ length: 7 }, (_, i) => (
+                    <div key={i}>
+                        <h2 id={`section-${i + 1}`}>Section {i + 1}</h2>
+                        <p>Content for section {i + 1}.</p>
+                        {Array.from({ length: 3 }, (__, j) => (
+                            <div key={j}>
+                                <h3 id={`subsection-${i + 1}-${j + 1}`}>Subsection {i + 1}.{j + 1}</h3>
+                                <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+                                    Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
+                                <p>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
+                            </div>
+                        ))}
+                    </div>
+                ))}
+            </ContentArea>
+        </StoryWrapper>
+    ),
+};
+
+/**
+ * Table of contents with inline code in headings
+ */
+export const WithCodeInHeadings: Story = {
+    args: {
+        markdown: markdownWithCode,
+    },
+    render: (args) => (
+        <StoryWrapper>
+            <TOCContainer>
+                <TableOfContents {...args} />
+            </TOCContainer>
+            <ContentArea dangerouslySetInnerHTML={{ __html: `
+                <h1 id="api-documentation">API Documentation</h1>
+                <p>Documentation with code examples in headings.</p>
+
+                <h2 id="initialize-method"><code>initialize()</code> Method</h2>
+                <p>Details about the initialize method.</p>
+
+                <h3 id="parameters">Parameters</h3>
+                <p>List of parameters.</p>
+
+                <h3 id="return-value">Return Value</h3>
+                <p>What the method returns.</p>
+
+                <h2 id="configureoptions-method"><code>configure(options)</code> Method</h2>
+                <p>Configuration method details.</p>
+
+                <h3 id="optionssetting1"><code>options.setting1</code></h3>
+                <p>First setting.</p>
+
+                <h3 id="optionssetting2"><code>options.setting2</code></h3>
+                <p>Second setting.</p>
+
+                <h2 id="usage-examples">Usage Examples</h2>
+                <p>How to use the API.</p>
+            ` }} />
+        </StoryWrapper>
+    ),
+};
+
+/**
+ * Simple table of contents with flat structure
+ */
+export const SimpleFlat: Story = {
+    args: {
+        markdown: simpleMarkdown,
+    },
+    render: (args) => (
+        <StoryWrapper>
+            <TOCContainer>
+                <TableOfContents {...args} />
+            </TOCContainer>
+            <ContentArea dangerouslySetInnerHTML={{ __html: `
+                <h1 id="quick-start">Quick Start</h1>
+                <p>A simple document.</p>
+
+                <h2 id="step-1">Step 1</h2>
+                <p>First step.</p>
+
+                <h2 id="step-2">Step 2</h2>
+                <p>Second step.</p>
+
+                <h2 id="step-3">Step 3</h2>
+                <p>Third step.</p>
+            ` }} />
+        </StoryWrapper>
+    ),
+};
+
+/**
+ * Table of contents only (without content side-by-side)
+ */
+export const TOCOnly: Story = {
+    args: {
+        markdown: basicMarkdown,
+    },
+    render: (args) => (
+        <div style={{ maxWidth: '300px' }}>
+            <TableOfContents {...args} />
+        </div>
+    ),
+};

package/src/components/simple_markdown/simple_markdown.stories.tsx

@@ -62,7 +62,7 @@ const Template = (props: SimpleMarkdownProps) => {
 };
 
 export default {
-    title: 'UI-Library/Markdown',
+    title: 'UI-Library/Markdown/SimpleMarkdown',
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     component: SimpleMarkdown as any,
 };

package/src/components/simple_markdown/simple_markdown_components.tsx

@@ -1,3 +1,4 @@
+import type { ElementContent } from 'hast';
 import qs from 'query-string';
 import type React from 'react';
 import type { ExtraProps as MarkdownComponentExtraProps } from 'react-markdown';
@@ -14,7 +15,7 @@ import type { LinkProps } from '../link.js';
 import { Link } from '../link.js';
 import { slugifyHeadingChildren } from '../readme_renderer/utils.js';
 import type { HeadingSharedProps } from '../text/heading_shared.js';
-import { Heading } from '../text/index.js';
+import { Heading, Text } from '../text/index.js';
 import type { SharedTextProps, SharedTextSize } from '../text/text_shared.js';
 
 const simpleMarkdownClassNames = {
@@ -282,17 +283,38 @@ export const MarkdownTable = styled.table`
     }
 `;
 
+/**
+ * Helper function to extract video src from markdown node child.
+ * Handles both plain text URLs and link elements.
+ */
+const getMarkdownVideoSrc = (child?: ElementContent): string | undefined => {
+    // Check if it's a plain text YouTube/Vimeo URL
+    if (child?.type === 'text') {
+        return getVideoSrc(child.value);
+    }
+
+    // Check if it's a link element with YouTube/Vimeo URL
+    if (child?.type === 'element' && child?.tagName === 'a') {
+        const linkHref = child?.properties?.href;
+        if (linkHref && typeof linkHref === 'string') {
+            return getVideoSrc(linkHref);
+        }
+    }
+
+    return undefined;
+};
+
 // TODO: This should be used for readmes
 export const MarkdownParagraphContent: React.FC<SharedTextProps & MarkdownComponentExtraProps> = async ({
     children,
     node,
+    ...textProps
 }) => {
     const child = node?.children[0];
-    const isText = child?.type === 'text';
+    const videoSrc = getMarkdownVideoSrc(child);
 
-    const videoSrc = isText && getVideoSrc(child.value);
     if (videoSrc) return <MarkdownVideo src={videoSrc} />;
 
-    // the || null part is important because non-supported elements will fall back to this paragraph component;
-    return children || null;
+    // Render the children as a paragraph
+    return <Text as='p' my='space16' {...textProps}>{children}</Text>;
 };