@apify/ui-library 1.120.0 → 1.121.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@apify/ui-library",
-    "version": "1.120.0",
+    "version": "1.121.0",
     "description": "React UI library used by apify.com",
     "license": "Apache-2.0",
     "type": "module",
@@ -31,6 +31,7 @@
         "@react-hook/resize-observer": "^2.0.2",
         "clsx": "^2.0.0",
         "dayjs": "1.11.9",
+        "emoji-regex": "^9.2.2",
         "fast-average-color": "^9.4.0",
         "history": "^5.3.0",
         "lodash": "^4.17.21",
@@ -64,5 +65,5 @@
         "src",
         "style"
     ],
-    "gitHead": "ad7a5921f83c7575ecea7fca3b3843cdc7f04a8f"
+    "gitHead": "234eb45c25c1f6b5f0943da5fc4cd2c5fecd2afd"
 }

package/src/components/boring_avatar.stories.tsx

@@ -0,0 +1,188 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import styled from 'styled-components';
+
+import { BoringAvatarMarble, BoringAvatarSolid } from './boring_avatar.js';
+
+const meta = {
+    title: 'UI-Library/Store/BoringAvatar',
+    component: BoringAvatarMarble,
+    argTypes: {
+        name: {
+            control: 'text',
+            description: 'Name used to generate the avatar (determines colors and letters)',
+        },
+        size: {
+            control: { type: 'number', min: 16, max: 200 },
+            description: 'Size of the avatar in pixels',
+        },
+        square: {
+            control: 'boolean',
+            description: 'Whether the avatar should be square instead of circular',
+        },
+        colors: {
+            control: 'object',
+            description: 'Array of colors used for the avatar generation',
+        },
+        alt: {
+            control: 'text',
+            description: 'Alt text for accessibility',
+        },
+        className: {
+            control: 'text',
+            description: 'CSS class name for styling',
+        },
+    },
+} satisfies Meta<typeof BoringAvatarMarble>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const StoryWrapper = styled.div`
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1rem;
+    padding: 2rem;
+    align-items: center;
+`;
+
+const AvatarShowcase = styled.div`
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.5rem;
+
+    small {
+        color: #666;
+        font-size: 0.75rem;
+    }
+`;
+
+const GridWrapper = styled.div`
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(80px, 1fr));
+    gap: 1.5rem;
+    padding: 2rem;
+`;
+
+/**
+ * Default marble avatar with standard settings
+ */
+export const MarbleDefault: Story = {
+    args: {
+        name: 'John Doe',
+        size: 64,
+    },
+};
+
+/**
+ * Default solid color avatar
+ */
+export const SolidDefault: Story = {
+    render: (args) => <BoringAvatarSolid {...args} />,
+    args: {
+        name: 'John Doe',
+        size: 64,
+    },
+};
+
+/**
+ * Different sizes comparison
+ */
+export const Sizes: Story = {
+    render: () => (
+        <StoryWrapper>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Alice" size={24} />
+                <small>24px</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Alice" size={32} />
+                <small>32px</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Alice" size={48} />
+                <small>48px</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Alice" size={64} />
+                <small>64px</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Alice" size={96} />
+                <small>96px</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Alice" size={128} />
+                <small>128px</small>
+            </AvatarShowcase>
+        </StoryWrapper>
+    ),
+};
+
+/**
+ * Circular vs Square shapes
+ */
+export const Shapes: Story = {
+    render: () => (
+        <StoryWrapper>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Shape Test" size={80} square={false} />
+                <small>Circular</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Shape Test" size={80} square />
+                <small>Square (broken?)</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarSolid name="Shape Test" size={80} square={false} />
+                <small>Circular (Solid)</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarSolid name="Shape Test" size={80} square />
+                <small>Square (Solid) (broken?)</small>
+            </AvatarShowcase>
+        </StoryWrapper>
+    ),
+};
+
+/**
+ * Different names generate different avatars
+ */
+export const DifferentNames: Story = {
+    render: () => (
+        <GridWrapper>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="John Doe" size={64} />
+                <small>John Doe</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="Jane Smith" size={64} />
+                <small>Jane Smith</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="web-scraper" size={64} />
+                <small>web-scraper</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="my-actor" size={64} />
+                <small>my-actor</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="apify/store" size={64} />
+                <small>apify/store</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="data.processor" size={64} />
+                <small>data.processor</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="APIIntegration" size={64} />
+                <small>APIIntegration</small>
+            </AvatarShowcase>
+            <AvatarShowcase>
+                <BoringAvatarMarble name="test_user_123" size={64} />
+                <small>test_user_123</small>
+            </AvatarShowcase>
+        </GridWrapper>
+    ),
+};

package/src/components/boring_avatar.tsx

@@ -0,0 +1,262 @@
+import emojiRegex from 'emoji-regex';
+import React, { useMemo } from 'react';
+
+const emojiRegexPattern = emojiRegex();
+
+// This code is taken from https://github.com/boringdesigners/boring-avatars/blob/master/src/lib/components/avatar-marble.js
+
+const ELEMENTS = 3;
+const SIZE = 100;
+
+const IGNORED_WORDS = ['AND', 'A', 'THE', 'AN'];
+
+function hashCode(name?: string) {
+    // This is very defensive, but passing empty string as name to this component by mistake
+    // should never break the UI completely.
+    if (!name) return 0;
+
+    let hash = 0;
+    for (let i = 0; i < name.length; i++) {
+        const character = name.charCodeAt(i);
+        hash = (hash << 5) - hash + character; // eslint-disable-line
+        hash &= hash; // eslint-disable-line
+    }
+    return Math.abs(hash);
+}
+
+function getDigit(number: number, ntn: number) {
+    return Math.floor((number / 10 ** ntn) % 10);
+}
+
+function getUnit(number: number, range: number, index?: number) {
+    const value = number % range;
+
+    if (index && getDigit(number, index) % 2 === 0) {
+        return -value;
+    }
+    return value;
+}
+
+function generateProperties(name: string, colors: string[]) {
+    const numFromName = hashCode(name);
+
+    const elementsProperties = [];
+    for (let i = 0; i < ELEMENTS; i++) {
+        elementsProperties.push({
+            color: colors[(numFromName + (i + 1)) % colors.length],
+            translateX: getUnit(numFromName * (i + 1), SIZE / 10, 1),
+            translateY: getUnit(numFromName * (i + 1), SIZE / 10, 2),
+            scale: 1.2 + getUnit(numFromName * (i + 1), SIZE / 20) / 10,
+            rotate: getUnit(numFromName * (i + 1), 360, 1),
+        });
+    }
+
+    return elementsProperties;
+}
+
+function generateFill(
+    properties: ReturnType<typeof generateProperties>,
+    name: string,
+) {
+    const {
+        translateX: translateX1,
+        translateY: translateY1,
+        rotate: rotate1,
+    } = properties[1];
+    const {
+        translateX: translateX2,
+        translateY: translateY2,
+        rotate: rotate2,
+        scale,
+    } = properties[2];
+
+    let nameParts = name
+        .replace(emojiRegexPattern, ' ') // Remove emojis from the name
+        .trim().replace(/\s+/g, ' ') // Remove multiple spaces
+        .toUpperCase()
+        .split(' '); // Ideally if the Actor has a name with spaces, we take words separated by spaces
+
+    if (nameParts.length <= 1) nameParts = nameParts[0].split('-'); // If that did not work, we try to separate it by -
+    if (nameParts.length <= 1) nameParts = nameParts[0].split('_'); // If those are also not present we try to separate it by _
+    if (nameParts.length <= 1) nameParts = nameParts[0].split('.'); // If those are also not present we try to separate it by .
+    if (nameParts.length <= 1) nameParts = nameParts[0].split(''); // In the end we take the first word and separate it by letter
+
+    // Nice to have: remove ignored words from the name if the name has more than 2 words
+    if (nameParts.length > 2) { nameParts = nameParts.filter((part) => !IGNORED_WORDS.includes(part)); }
+
+    return {
+        fill0: properties[0].color,
+        fill1: properties[1].color,
+        fill2: properties[2].color,
+        transform1: `translate(${translateX1} ${translateY1}) rotate(${rotate1} ${SIZE / 2} ${SIZE / 2}) scale(${scale})`,
+        transform2: `translate(${translateX2} ${translateY2}) rotate(${rotate2} ${SIZE / 2} ${SIZE / 2}) scale(${scale})`,
+        letter1: nameParts?.[0]?.[0] ?? undefined,
+        letter2: nameParts?.[1]?.[0] ?? undefined,
+    };
+}
+
+interface BoringAvatarProps {
+    name?: string;
+    className?: string;
+    size: number;
+    colors?: string[];
+    square?: boolean;
+    alt?: string;
+}
+
+export const BoringAvatarMarble = React.memo(({
+    name = '',
+    colors = ['#12966F', '#5D85E1', '#E44467', '#F0B21B', '#FA8136', '#30C0BB'],
+    square = false,
+    className,
+    size = 24,
+    alt = 'Avatar image',
+}: BoringAvatarProps) => {
+    const fill = useMemo(() => {
+        const properties = generateProperties(name ?? '', colors);
+        return generateFill(properties, name ?? '');
+    }, [name, colors]);
+
+    return (
+        <svg
+            viewBox={`0 0 ${SIZE} ${SIZE}`}
+            fill="none"
+            role="img"
+            xmlns="http://www.w3.org/2000/svg"
+            width={size}
+            height={size}
+            className={className}
+            aria-label={alt}
+        >
+            <mask
+                id="mask__marble"
+                maskUnits="userSpaceOnUse"
+                x={0}
+                y={0}
+                width={SIZE}
+                height={SIZE}
+            >
+                <rect
+                    width={SIZE}
+                    height={SIZE}
+                    rx={square ? undefined : SIZE * 2}
+                    fill="#FFFFFF"
+                />
+            </mask>
+            <g mask="url(#mask__marble)">
+                <rect width={SIZE} height={SIZE} fill={fill.fill0} />
+                <path
+                    filter="url(#prefix__filter0_f)"
+                    d="M32.414 59.35L50.376 70.5H72.5v-71H33.728L26.5 13.381l19.057 27.08L32.414 59.35z"
+                    fill={fill.fill1}
+                    transform={fill.transform1}
+                />
+                <path
+                    filter="url(#prefix__filter0_f)"
+                    style={{
+                        mixBlendMode: 'overlay',
+                    }}
+                    d="M22.216 24L0 46.75l14.108 38.129L78 86l-3.081-59.276-22.378 4.005 12.972 20.186-23.35 27.395L22.215 24z"
+                    fill={fill.fill2}
+                    transform={fill.transform2}
+                />
+            </g>
+            <g>
+                {fill.letter1 && (
+                    <text
+                        style={{ fontSize: '50px' }}
+                        x="50"
+                        y="50"
+                        dy="7"
+                        textAnchor="middle"
+                        alignmentBaseline="middle"
+                        dominantBaseline="middle"
+                    >
+                        {fill.letter1}
+                        {fill.letter2}
+                    </text>
+                )}
+            </g>
+            <defs>
+                <filter
+                    id="prefix__filter0_f"
+                    filterUnits="userSpaceOnUse"
+                    colorInterpolationFilters="sRGB"
+                >
+                    <feFlood floodOpacity={0} result="BackgroundImageFix" />
+                    <feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape" />
+                    <feGaussianBlur stdDeviation={7} result="effect1_foregroundBlur" />
+                </filter>
+            </defs>
+        </svg>
+    );
+});
+
+export const BoringAvatarSolid = React.memo(({
+    name = '',
+    alt = 'Avatar image',
+    colors = ['#B8487B', '#E5B557', '#58BCC4', '#6D85CA', '#8690BF', '#F08848', '#8148C9', '#439274'],
+    square = false,
+    className,
+    size = 24,
+}: BoringAvatarProps) => {
+    /**
+         * Name must be lowercased to avoid irregularities caused by caps.
+         * This is an issue in the Actor detail header, where the username comes from the Actor object,
+         * while in the user selector it comes from the user object, where it can have capitals.
+         */
+    const nameLowercase = name.toLowerCase();
+
+    const fill = useMemo(() => {
+        const properties = generateProperties(nameLowercase, colors);
+        return generateFill(properties, nameLowercase);
+    }, [nameLowercase, colors]);
+
+    return (
+        <svg
+            viewBox={`0 0 ${SIZE} ${SIZE}`}
+            fill="none"
+            role="img"
+            xmlns="http://www.w3.org/2000/svg"
+            width={size}
+            height={size}
+            className={className}
+            aria-label={alt}
+        >
+            <mask
+                id="mask__solid"
+                maskUnits="userSpaceOnUse"
+                x={0}
+                y={0}
+                width={SIZE}
+                height={SIZE}
+            >
+                <rect
+                    width={SIZE}
+                    height={SIZE}
+                    rx={square ? undefined : SIZE * 2}
+                    fill="#FFFFFF"
+                />
+            </mask>
+            <g mask="url(#mask__solid)">
+                <rect width={SIZE} height={SIZE} fill={fill.fill0} />
+            </g>
+            <g>
+                {fill.letter1 && (
+                    <text
+                        style={{ fontSize: '50px' }}
+                        x="50"
+                        y="50"
+                        dy="7"
+                        textAnchor="middle"
+                        alignmentBaseline="middle"
+                        dominantBaseline="middle"
+                    >
+                        {fill.letter1}
+                        {fill.letter2}
+                    </text>
+                )}
+            </g>
+        </svg>
+    );
+});

package/src/components/index.ts

@@ -1,5 +1,6 @@
 export * from './text/index.js';
 export * from './box.js';
+export * from './boring_avatar.js';
 export * from './card_container.js';
 export * from './message.js';
 export * from './floating/index.js';
@@ -24,3 +25,4 @@ export * from './tabs/index.js';
 export * from './shortcut.js';
 export * from './icon_button.js';
 export * from './spinner.js';
+export * from './store/index.js';

package/src/components/readme_renderer/index.ts

@@ -1,3 +1,3 @@
-export { useActorTitleHeadingFilter } from './utils.js';
+export { useActorTitleHeadingFilter, cleanMarkdown, slugifyHeadingChildren } from './utils.js';
 export { pythonizeValue } from './pythonize_value.js';
-export { TableOfContents, useShowTableOfContents } from './table_of_contents.js';
+export { TableOfContents, type TableOfContentsProps, useShowTableOfContents } from './table_of_contents.js';

package/src/components/store/actor_avatar.stories.tsx

@@ -0,0 +1,65 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { ActorAvatar } from './actor_avatar.js';
+
+const meta = {
+    title: 'UI-Library/Store/ActorAvatar',
+    component: ActorAvatar,
+    parameters: {
+        layout: 'padded',
+    },
+    argTypes: {
+        name: {
+            control: 'text',
+            description: 'Name used to generate the avatar when no URL is provided',
+        },
+        url: {
+            control: 'text',
+            description: 'URL of the avatar image',
+        },
+        size: {
+            control: 'number',
+            description: 'Size of the avatar in pixels',
+        },
+        alt: {
+            control: 'text',
+            description: 'Alt text for the avatar image',
+        },
+    },
+} satisfies Meta<typeof ActorAvatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    args: {
+        name: 'Web Scraper',
+        size: 64,
+    },
+};
+
+export const Sizes: Story = {
+    render: () => (
+        <div style={{ display: 'flex', gap: '16px', alignItems: 'flex-end' }}>
+            {[24, 32, 40, 48, 64, 80, 128].map((size) => (
+                <div key={size} style={{ textAlign: 'center' }}>
+                    <ActorAvatar name="Web Scraper" size={size} />
+                    <p style={{ marginTop: '8px', fontSize: '12px' }}>{size}px</p>
+                </div>
+            ))}
+        </div>
+    ),
+};
+
+export const WithImageUrl: Story = {
+    render: () => (
+        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', marginTop: '16px' }}>
+            <ActorAvatar
+                name="Web Scraper"
+                url="https://apify.github.io/apify-web/img/apify-logo/logomark-32x32.svg"
+                size={64}
+            />
+        </div>
+    ),
+};

package/src/components/store/actor_avatar.tsx

@@ -0,0 +1,129 @@
+import clsx from 'clsx';
+import type { FC, RefCallback } from 'react';
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import styled from 'styled-components';
+
+import {
+    BoringAvatarMarble,
+    theme,
+    useImageColor,
+    useSharedUiDependencies,
+} from '../../index.js';
+
+export const actorAvatarClassnames = {
+    BASE: 'ActorAvatar',
+    IMG: 'ActorAvatar-image',
+    SVG: 'ActorAvatar-svg',
+};
+
+const StyledBoringAvatarMarble = styled(BoringAvatarMarble)`
+    border-radius: ${theme.radius.radius8};
+
+    text {
+        ${theme.typography.shared.mobile.bodyMStrong}
+
+        @media (min-width: ${theme.layout.tablet}) {
+            ${theme.typography.shared.tablet.bodyMStrong}
+        }
+        @media (min-width: ${theme.layout.desktop}) {
+            ${theme.typography.shared.desktop.bodyMStrong}
+        }
+
+        fill: ${theme.color.neutral.background};
+        color: ${theme.color.neutral.background};
+        text-transform: uppercase;
+        white-space: pre;
+    }
+`;
+
+const StyledImg = styled.img`
+    border-radius: ${theme.radius.radius8};
+`;
+
+interface ActorAvatarProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+    name?: string;
+    className?: string;
+    url?: string;
+    alt?: string;
+    size: number;
+}
+
+export const ActorAvatarInner: FC<ActorAvatarProps> = ({
+    name,
+    className,
+    url,
+    size,
+    alt,
+    ...rest
+}) => {
+    const [hasImageError, setHasImageError] = useState(false);
+    useEffect(() => {
+        setHasImageError(false);
+    }, [url]);
+
+    const { generateProxyImageUrl } = useSharedUiDependencies();
+
+    const maybeProxiedUrl = useMemo(
+        () => (
+            generateProxyImageUrl && url
+                ? generateProxyImageUrl(url, { resize: { height: size * 2, width: size * 2 } })
+                : url
+        ),
+        [generateProxyImageUrl, url, size],
+    );
+
+    const { color, refCallback } = useImageColor();
+
+    const imageRef = useRef<HTMLImageElement | null>(null);
+    const imageRefCallback = useCallback<RefCallback<HTMLImageElement>>(
+        (element) => {
+            imageRef.current = element;
+            refCallback(element);
+        },
+        [refCallback],
+    );
+
+    const onError = useCallback<React.ReactEventHandler<HTMLImageElement>>(() => setHasImageError(true), []);
+
+    useLayoutEffect(() => {
+        if (imageRef.current) {
+            imageRef.current.style.backgroundColor = color?.isLight
+                ? '#1a1b21' // TODO: introduce a static theme color variable (e.g.: theme.color.neutral.backgroundDark)
+                : theme.color.neutral.backgroundWhite;
+        }
+    }, [color?.isLight]);
+
+    const fullClassName = clsx(
+        actorAvatarClassnames.BASE,
+        maybeProxiedUrl ? actorAvatarClassnames.IMG : actorAvatarClassnames.SVG,
+        className,
+    );
+
+    const altText = alt || `${name} avatar`;
+    if (maybeProxiedUrl && !hasImageError) {
+        return (
+            <StyledImg
+                ref={imageRefCallback}
+                crossOrigin='anonymous'
+                src={maybeProxiedUrl}
+                className={fullClassName}
+                width={size}
+                height={size}
+                alt={altText}
+                onError={onError}
+                {...rest}
+            />
+        );
+    }
+    return (
+        <StyledBoringAvatarMarble
+            size={size}
+            className={fullClassName}
+            name={name}
+            square={true}
+            alt={altText}
+        />
+    );
+};
+
+export const ActorAvatar = React.memo(ActorAvatarInner);

package/src/components/store/index.ts

@@ -0,0 +1,2 @@
+export * from './store_actor_header.js';
+export * from './actor_avatar.js';