@apify/ui-library 1.92.0 → 1.92.1-featimprovetooltip-7e1224.32

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@apify/ui-library",
-    "version": "1.92.0",
+    "version": "1.92.1-featimprovetooltip-7e1224.32+2b6834918f7",
     "description": "React UI library used by apify.com",
     "license": "Apache-2.0",
     "type": "module",
@@ -66,5 +66,5 @@
         "src",
         "style"
     ],
-    "gitHead": "11dbfebf682791f049f490ff208aec3eb7475170"
+    "gitHead": "2b6834918f728c0d3d078ce95e5e3cbb007f9a7d"
 }

package/src/components/floating/floating_component_base.tsx

@@ -0,0 +1,263 @@
+import {
+    arrow,
+    autoPlacement,
+    autoUpdate,
+    flip,
+    FloatingPortal,
+    hide,
+    offset,
+    shift,
+    type Strategy,
+    useFloating,
+} from '@floating-ui/react';
+import clsx from 'clsx';
+import { type ComponentType, type CSSProperties, forwardRef, type MouseEvent, type ReactNode, type RefObject, useMemo, useRef } from 'react';
+import styled, { keyframes } from 'styled-components';
+
+import { theme } from '../../design_system/theme.js';
+
+export const classNames = {
+    ARROW: 'FloatingComponent-arrow',
+    CHILDREN: 'FloatingComponent-children',
+};
+
+export const FLOATING_PLACEMENT = {
+    TOP: 'top',
+    TOP_START: 'top-start',
+    TOP_END: 'top-end',
+    RIGHT: 'right',
+    RIGHT_START: 'right-start',
+    RIGHT_END: 'right-end',
+    BOTTOM: 'bottom',
+    BOTTOM_START: 'bottom-start',
+    BOTTOM_END: 'bottom-end',
+    LEFT: 'left',
+    LEFT_START: 'left-start',
+    LEFT_END: 'left-end',
+} as const;
+
+export type FloatingPlacement = typeof FLOATING_PLACEMENT[keyof typeof FLOATING_PLACEMENT];
+
+interface FadeInProps {
+    children: ReactNode;
+    duration?: number;
+    delay?: number;
+    $minHeight?: string;
+}
+
+interface FloatingComponentWrapStyledProps {
+    arrowRotationDegs: number;
+}
+
+interface FloatingComponentWrapProps extends FloatingComponentWrapStyledProps {
+    showInPortal?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    onClick?: (e: MouseEvent<HTMLElement>) => void;
+    children: ReactNode;
+}
+
+export interface FloatingComponentBaseProps {
+    placement?: FloatingPlacement;
+    autoPlacements?: FloatingPlacement[];
+    strategy?: Strategy;
+    content?: ReactNode | string;
+    children?: ReactNode;
+    isOpen?: boolean;
+    triggerRef?: RefObject<HTMLDivElement>;
+    className?: string;
+    offsetPx?: number;
+    contentWrapClassName?: string;
+    CloseButtonComponent?: ComponentType;
+    showInPortal?: boolean;
+}
+
+const fadeIn = keyframes`
+    from {
+        opacity: 0;
+    }
+    to {
+        opacity: 1;
+    }
+`;
+
+const FadeIn = styled.div<FadeInProps>`
+    @media (prefers-reduced-motion: no-preference) {
+        animation-name: ${fadeIn};
+        animation-fill-mode: backwards;
+        animation-duration: ${(props) => `${props.duration || 240}ms`};
+        animation-delay: ${(props) => `${props.delay || 0}ms`};
+    }
+
+    min-height: ${({ $minHeight }) => $minHeight || 'unset'};
+`;
+
+const FloatingComponentWrapStyled = styled.span<FloatingComponentWrapStyledProps>`
+    box-shadow: ${theme.shadow.shadow2};
+    padding: ${theme.space.space16};
+    ${theme.typography.shared.mobile.bodyM};
+    border-radius: 0.8rem;
+    z-index: 999;
+    white-space: normal;
+    word-break: break-word;
+    cursor: default;
+    text-align: left;
+
+    .${classNames.ARROW} {
+        position: absolute;
+        background-color: inherit;
+        border: inherit;
+        width: 10px;
+        height: 10px;
+        transform: ${({ arrowRotationDegs }) => `rotate(${arrowRotationDegs}deg)`} ;
+        z-index:-1;
+    }
+
+    @media ${theme.device.tablet} {
+        ${theme.typography.shared.tablet.bodyM};
+    }
+
+    @media ${theme.device.desktop} {
+        ${theme.typography.shared.desktop.bodyM};
+    }
+`;
+
+const ChildrenWrap = styled.div`
+    .${classNames.CHILDREN} {
+        width: fit-content;
+    }
+`;
+
+const StyledPopoverBox = styled.div`
+    display: flex;
+    align-items: center;
+    gap: ${theme.space.space4};
+    button {
+        color: inherit;
+    }
+`;
+
+const FloatingComponentWrap = forwardRef<HTMLSpanElement, FloatingComponentWrapProps>((props, ref) => {
+    const { showInPortal, ...rest } = props;
+    const component = <FloatingComponentWrapStyled {...rest} ref={ref} />;
+    if (showInPortal) {
+        return <FloatingPortal>{component}</FloatingPortal>;
+    }
+    return component;
+});
+
+FloatingComponentWrap.displayName = 'FloatingComponentWrap';
+
+/**
+ * This is just the base component for Tooltips and Popovers.
+ * Don't use this - use Tooltip/HelpPopover instead.
+ */
+export const FloatingComponentBase = ({
+    placement = FLOATING_PLACEMENT.TOP,
+    autoPlacements,
+    strategy = 'fixed',
+    content,
+    children,
+    isOpen = false,
+    triggerRef,
+    className,
+    offsetPx = 10,
+    contentWrapClassName,
+    CloseButtonComponent,
+    showInPortal = false,
+}: FloatingComponentBaseProps) => {
+    const arrowRef = useRef<HTMLDivElement>(null);
+
+    const {
+        x,
+        y,
+        refs: { setReference, setFloating },
+        placement: effectivePlacement,
+        strategy: effectiveStrategy,
+        middlewareData: {
+            arrow: { x: arrowX, y: arrowY } = {},
+            hide: refHidden,
+        },
+    } = useFloating({
+        placement,
+        strategy,
+        whileElementsMounted: autoUpdate,
+        middleware: [
+            offset(offsetPx),
+            autoPlacements?.length ? autoPlacement({ allowedPlacements: autoPlacements }) : flip(),
+            shift({ padding: 5 }),
+            arrow({ element: arrowRef, padding: 9 }),
+            hide({
+                strategy: 'referenceHidden',
+            }),
+        ],
+    });
+
+    const arrowStyle = useMemo(() => {
+        const staticSide = {
+            top: 'bottom',
+            right: 'left',
+            bottom: 'top',
+            left: 'right',
+        }[effectivePlacement.split('-')[0] as 'top' | 'right' | 'bottom' | 'left'];
+
+        let borderNone: CSSProperties = { borderLeft: 0, borderTop: 0 };
+        if (staticSide === 'bottom') borderNone = { borderRight: 0, borderBottom: 0 };
+        if (staticSide === 'right') borderNone = { borderLeft: 0, borderBottom: 0 };
+        if (staticSide === 'left') borderNone = { borderRight: 0, borderTop: 0 };
+
+        const style: CSSProperties = {
+            left: arrowX != null ? `${arrowX}px` : '',
+            top: arrowY != null ? `${arrowY}px` : '',
+            ...borderNone,
+        };
+
+        if (staticSide) {
+            (style as Record<string, string | number>)[staticSide] = '-6px';
+        }
+
+        return style;
+    }, [arrowX, arrowY, effectivePlacement]);
+
+    const arrowRotationDegs = effectivePlacement.includes(FLOATING_PLACEMENT.TOP) || effectivePlacement.includes(FLOATING_PLACEMENT.BOTTOM) ? 225 : 45;
+
+    if (!content) return <span>{children}</span>;
+
+    return (
+        <>
+            {/* Adding className to children for easier identifying in DevTools */}
+            <ChildrenWrap className={clsx(classNames.CHILDREN, contentWrapClassName)} ref={setReference}>
+                {children}
+            </ChildrenWrap>
+            {isOpen && (
+                <FloatingComponentWrap arrowRotationDegs={arrowRotationDegs}
+                    className={className}
+                    ref={setFloating}
+                    style={{
+                        position: effectiveStrategy,
+                        top: y ?? 0,
+                        left: x ?? 0,
+                        width: 'max-content',
+                        visibility: refHidden?.referenceHidden ? 'hidden' : 'visible',
+                    }}
+                    onClick={(e) => e.stopPropagation()}
+                    showInPortal={showInPortal}
+                >
+                    <FadeIn delay={60} ref={triggerRef}>
+                        {CloseButtonComponent
+                            ? <StyledPopoverBox>
+                                {content}
+                                <CloseButtonComponent />
+                            </StyledPopoverBox>
+                            : content}
+                    </FadeIn>
+                    <div
+                        ref={arrowRef}
+                        className={classNames.ARROW}
+                        style={arrowStyle}
+                    />
+                </FloatingComponentWrap>
+            )}
+        </>
+    );
+};

package/src/components/floating/index.ts

@@ -1,3 +1,5 @@
 export * from './menu.js';
 export * from './menu_components.js';
 export * from './menu_common.js';
+export * from './tooltip.js';
+export { FLOATING_PLACEMENT, type FloatingPlacement } from './floating_component_base.js';

package/src/components/floating/tooltip.stories.jsx

@@ -0,0 +1,128 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import { FLOATING_PLACEMENT } from './floating_component_base.tsx';
+import { Tooltip } from './tooltip.tsx';
+
+const Child = () => <div style={{ padding: '8px', border: '1px solid black', borderRadius: '4px' }}>Hover me</div>;
+
+const longText = 'This is a tooltip with a longer text. This is a tooltip with a longer text. This is a tooltip with a longer text.';
+
+export default {
+    title: 'UI-Library/Tooltip',
+    component: Tooltip,
+    parameters: {
+        design: {
+            type: 'figma',
+            url: 'https://www.figma.com/design/duSsGnk84UMYav8mg8QNgR/%F0%9F%93%96-Shared-library?node-id=5236-98464&p=f&m=dev',
+        },
+    },
+    decorators: [
+        (Story) => (
+            <div style={{ margin: '3em', width: 'fit-content' }}>
+                <Story />
+            </div>
+        ),
+    ],
+    args: {
+        children: <Child />,
+        content: 'This is a tooltip',
+    },
+};
+
+const DefaultStoryWrapper = styled.div`
+    display: grid;
+    grid-template-columns: 1fr 1fr 1fr;
+    gap: 10em;
+    row-gap: 20em;
+`;
+
+export const Default = (args) => {
+    return (<DefaultStoryWrapper>
+        <div>
+            Default:
+            <Tooltip {...args}/>
+        </div>
+        <div>
+            With shortcuts:
+            <Tooltip shortcuts={['Ctrl / ⌘', 'F']} {...args}/>
+        </div>
+        <div>
+            With shortcuts and long text:
+            <Tooltip
+                persistent={{ isOpenOverride: true }}
+                shortcuts={['Ctrl / ⌘', 'F']}
+                content={longText}
+            ><Child /></Tooltip>
+        </div>
+        <div>
+            With image:
+            <Tooltip imageUrl='https://picsum.photos/id/1/1024' {...args} />
+        </div>
+        <div>
+            With subtleText:
+            <Tooltip subtleText="This is some subtle text" {...args} />
+        </div>
+        <div>
+            With everything:
+            <Tooltip
+                persistent={{ isOpenOverride: true }}
+                shortcuts={['Ctrl / ⌘', 'F']}
+                imageUrl='https://picsum.photos/id/1/1024'
+                subtleText="This is some subtle text"
+                placement={FLOATING_PLACEMENT.BOTTOM}
+                content={longText}
+            ><Child /></Tooltip>
+        </div>
+    </DefaultStoryWrapper>
+    );
+};
+Default.args = {
+    persistent: { isOpenOverride: true },
+};
+
+export const Sizes = () => {
+    return (<DefaultStoryWrapper>
+        <div>
+            Xsmall:
+            <Tooltip size="xsmall" content={longText}><Child /></Tooltip>
+        </div>
+        <div>
+            Small (default):
+            <Tooltip size="small" content={longText}><Child /></Tooltip>
+        </div>
+        <div>
+            Medium:
+            <Tooltip size="medium" content={longText}><Child /></Tooltip>
+        </div>
+        <div>
+            Large:
+            <Tooltip size="large" content={longText}><Child /></Tooltip>
+        </div>
+        <div>
+            Xlarge:
+            <Tooltip size="xlarge" content={longText}><Child /></Tooltip>
+        </div>
+    </DefaultStoryWrapper>
+    );
+};
+
+export const Playground = (args) => {
+    return (
+        <Tooltip {...args}/>
+    );
+};
+Playground.argTypes = {
+    content: { control: 'text' },
+    shortcuts: { control: 'array' },
+    imageUrl: { control: 'text' },
+    subtleText: { control: 'text' },
+    size: {
+        control: 'select',
+        options: ['xsmall', 'small', 'medium', 'large', 'xlarge'],
+    },
+    placement: {
+        control: 'select',
+        options: Object.values(FLOATING_PLACEMENT),
+    },
+};

package/src/components/floating/tooltip.tsx

@@ -0,0 +1,120 @@
+import {
+    useFloating,
+    useHover,
+    useInteractions,
+} from '@floating-ui/react';
+import { type ComponentType, forwardRef, useState } from 'react';
+import styled from 'styled-components';
+
+import { theme } from '../../design_system/theme.js';
+import { FloatingComponentBase, type FloatingComponentBaseProps } from './floating_component_base.js';
+import { TooltipContent } from './tooltip_content.js';
+
+export const TOOLTIP_SIZES = {
+    XSMALL: 'xsmall',
+    SMALL: 'small',
+    MEDIUM: 'medium',
+    LARGE: 'large', /* Previously WIDE */
+    XLARGE: 'xlarge', /* Previously WIDER */
+} as const;
+
+export type TooltipSize = typeof TOOLTIP_SIZES[keyof typeof TOOLTIP_SIZES];
+
+interface PersistentTooltipProps {
+    isOpenOverride?: boolean;
+    CloseButtonComponent?: ComponentType;
+}
+
+export interface TooltipProps extends Omit<FloatingComponentBaseProps, 'isOpen' | 'size'> {
+    as?: keyof JSX.IntrinsicElements | ComponentType<unknown>;
+    className?: string;
+    persistent?: PersistentTooltipProps;
+    delayShow?: number;
+    delayHide?: number;
+    shortcuts?: string[];
+    imageUrl?: string;
+    subtleText?: string;
+    size?: TooltipSize;
+}
+
+interface WithTooltipProps {
+    tooltipProps?: TooltipProps;
+}
+
+// Using a styled component to get access to the `as` prop
+const TooltipFocusArea = styled.span``;
+
+const StyledFloatingComponentBase = styled(FloatingComponentBase)`
+    color: ${theme.colorPalette.dark.neutral0};
+    background-color: ${theme.colorPalette.dark.neutral900};
+    border: 1px solid ${theme.color.neutral.smallTooltipBorder};
+    padding: ${theme.space.space8};
+`;
+
+/**
+ * Tooltip appears on hover, for onclick use Popover
+ */
+export const Tooltip = ({
+    as,
+    className,
+    persistent,
+    delayShow = 500,
+    delayHide = 50,
+    shortcuts = [],
+    imageUrl,
+    subtleText,
+    size = TOOLTIP_SIZES.SMALL,
+    ...rest
+}: TooltipProps) => {
+    const { isOpenOverride, CloseButtonComponent } = persistent || {};
+    const [open, setOpen] = useState(false);
+
+    const { refs, context } = useFloating({
+        open,
+        onOpenChange: setOpen,
+    });
+
+    const hover = useHover(context, {
+        delay: {
+            open: delayShow,
+            close: delayHide,
+        },
+    });
+
+    const { getReferenceProps, getFloatingProps } = useInteractions([hover]);
+
+    const tooltipProps = {
+        ...rest,
+        isOpen: isOpenOverride !== undefined ? isOpenOverride : open,
+        content: <TooltipContent content={rest.content} shortcuts={shortcuts} imageUrl={imageUrl} subtleText={subtleText} size={size} />,
+    };
+
+    return (
+        <TooltipFocusArea
+            as={as as keyof JSX.IntrinsicElements}
+            className={className}
+            ref={refs.setReference}
+            {...getReferenceProps()}
+        >
+            <div
+                ref={refs.setFloating}
+                {...getFloatingProps()}
+            >
+                <StyledFloatingComponentBase {...tooltipProps} CloseButtonComponent={CloseButtonComponent} />
+            </div>
+        </TooltipFocusArea>
+    );
+};
+
+export function withTooltip<T extends Record<string, unknown> = Record<string, unknown>>(Component: ComponentType<T>) {
+    const Enhanced = forwardRef<HTMLElement, T & WithTooltipProps>(({ tooltipProps, ...rest }, ref) => {
+        if (!tooltipProps) return <Component {...(rest as unknown as T)} ref={ref} />;
+        return <Tooltip {...tooltipProps}>
+            <Component {...(rest as unknown as T)} ref={ref} />
+        </Tooltip>;
+    });
+
+    Enhanced.displayName = `WithTooltip:${Component.displayName || Component.name}`;
+
+    return Enhanced;
+}

package/src/components/floating/tooltip_content.tsx

@@ -0,0 +1,80 @@
+import styled, { css } from 'styled-components';
+
+import { theme } from '../../design_system/theme.js';
+import { Shortcut } from '../shortcut.js';
+import { TOOLTIP_SIZES, type TooltipProps, type TooltipSize } from './tooltip.js';
+
+type ContentProps = Pick<TooltipProps, 'content' | 'shortcuts' | 'imageUrl' | 'subtleText' | 'size'>;
+
+const TOOLTIP_SIZES_VALUES: Record<TooltipSize, string> = {
+    xsmall: '24rem',
+    small: '32rem',
+    medium: '40rem',
+    large: '48rem',
+    xlarge: '64rem',
+};
+
+const StyledContent = styled.div<{ $size: TooltipSize }>`
+    display: flex;
+    flex-direction: column;
+    gap: ${theme.space.space8};
+    /* Size - (tooltip padding + border) * 2 */
+    max-width: ${({ $size }) => css`calc(${TOOLTIP_SIZES_VALUES[$size]} - (${theme.space.space8} + 1px) * 2)`};
+
+    .Tooltip-image {
+        max-width: 100%;
+        max-height: 150px;
+        border-radius: 4px;
+        object-fit: contain;
+    }
+
+    .Tooltip-textContent {
+        display: flex;
+        flex-direction: column;
+        gap: ${theme.space.space8};
+
+        /* When there is no child with subtleText class */
+        &:not(:has(.Tooltip-subtleText)){
+            flex-direction: row;
+            flex-wrap: wrap;
+        }
+
+        .Tooltip-subtleText {
+            color: ${theme.colorPalette.dark.neutral500};
+        }
+
+        .Tooltip-shortcutContainer{
+            display: flex;
+            gap: ${theme.space.space4};
+        }
+    }
+`;
+
+export const TooltipContent = ({ content, shortcuts = [], imageUrl, subtleText, size = TOOLTIP_SIZES.SMALL }: ContentProps) => {
+    return (
+        <StyledContent $size={size}>
+            {imageUrl && (
+                <img
+                    src={imageUrl}
+                    alt=""
+                    className="Tooltip-image"
+                />
+            )}
+            <div className="Tooltip-textContent">
+                {content}
+                {subtleText && (
+                    <div className="Tooltip-subtleText">
+                        {subtleText}
+                    </div>
+                )}
+                {shortcuts.length > 0 && (
+                    <div className='Tooltip-shortcutContainer'>
+                        {shortcuts.map((shortcut, index) => (
+                            <Shortcut key={`${shortcut}-${index}`} dark>{shortcut}</Shortcut>
+                        ))}
+                    </div>
+                )}
+            </div>
+        </StyledContent>
+    );
+};

package/src/components/index.ts

@@ -20,3 +20,4 @@ export * from './rating.js';
 export * from './badge.js';
 export * from './tag.js';
 export * from './tabs/index.js';
+export * from './shortcut.js';

package/src/components/shortcut.stories.jsx

@@ -0,0 +1,57 @@
+import React from 'react';
+
+import { Shortcut } from './shortcut.tsx';
+
+export default {
+    title: 'UI-Library/Shortcut',
+    component: Shortcut,
+    parameters: {
+        design: {
+            type: 'figma',
+            url: 'https://www.figma.com/design/duSsGnk84UMYav8mg8QNgR/%F0%9F%93%96-Shared-library?node-id=5236-100844&m=dev',
+        },
+    },
+};
+
+export const ShortcutComponent = () => {
+    return (<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+    Default:
+        <div style={{ display: 'flex', gap: '4px' }}>
+            <Shortcut>F</Shortcut>
+            <Shortcut>Ctrl / ⌘</Shortcut>
+            <Shortcut>Shift</Shortcut>
+        </div>
+    Dark:
+        <div style={{ display: 'flex', gap: '4px' }}>
+            <Shortcut dark>F</Shortcut>
+            <Shortcut dark>Ctrl / ⌘</Shortcut>
+            <Shortcut dark>Shift</Shortcut>
+        </div>
+    </div>);
+};
+
+export const Playground = (args) => {
+    return (<Shortcut {...args}/>);
+};
+Playground.args = {
+    children: 'F',
+    dark: false,
+    as: 'div',
+};
+Playground.argTypes = {
+    dark: {
+        control: 'boolean',
+        defaultValue: false,
+    },
+    as: {
+        control: 'text',
+        defaultValue: 'div',
+    },
+    children: {
+        control: 'text',
+        defaultValue: 'F',
+    },
+    className: {
+        control: 'text',
+    },
+};