@apify/ui-library 1.168.2 → 1.169.0

package/src/components/skeleton/skeleton.stories.tsx

@@ -0,0 +1,221 @@
+/* eslint-disable import/default -- Vite `?raw` imports have a default export the import plugin cannot see */
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { expect, userEvent, within } from 'storybook/test';
+
+import { theme } from '../../design_system/theme';
+import { Box } from '../box';
+import { Button } from '../button';
+import { Skeleton, SkeletonFadeIn, SkeletonGroup, skeletonTestIds } from './';
+import { ActorIdeaCardsSkeleton } from './examples/actor_idea_cards_skeleton.example';
+import actorIdeaCardsSource from './examples/actor_idea_cards_skeleton.example?raw';
+import { NewActorWizardCardsSkeleton } from './examples/new_actor_wizard_cards_skeleton.example';
+import newActorWizardCardsSource from './examples/new_actor_wizard_cards_skeleton.example?raw';
+import { PublicationCategoriesSkeleton } from './examples/publication_categories_skeleton.example';
+import publicationCategoriesSource from './examples/publication_categories_skeleton.example?raw';
+import { StoreActorCardsLoading } from './examples/store_actor_cards_loading.example';
+import storeActorCardsLoadingSource from './examples/store_actor_cards_loading.example?raw';
+import { StoreActorCardsSkeleton } from './examples/store_actor_cards_skeleton.example';
+import storeActorCardsSource from './examples/store_actor_cards_skeleton.example?raw';
+
+// Each story renders a `*.example.tsx` composition and shows that same file as its code, so what developers and
+// agents copy is exactly what is rendered.
+
+const meta: Meta<typeof Skeleton> = {
+    title: 'UI-Library/Skeleton',
+    tags: ['new'],
+    component: Skeleton,
+    subcomponents: { SkeletonGroup, SkeletonFadeIn },
+    parameters: {
+        docs: {
+            description: {
+                component:
+                    'Placeholder for content that is loading. Mirror its layout with `Skeleton` blocks inside a ' +
+                    '`SkeletonGroup`, and wrap the loaded content in `SkeletonFadeIn`. Spec: apify/apify-design#257.\n\n' +
+                    'The stories are examples to copy next to the card they mirror.',
+            },
+        },
+    },
+    argTypes: {
+        width: { control: false },
+        height: { control: false },
+    },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Skeleton>;
+
+const withSource = (code: string) => ({ docs: { source: { code, language: 'tsx' } } });
+
+// ---------------------------------------------------------------------------
+// Shared assertions
+// ---------------------------------------------------------------------------
+
+const prefersReducedMotion = () => window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+const getLoadingRegion = async (canvasElement: HTMLElement, label: string, blockCount: number) => {
+    const region = within(canvasElement).getByRole('status', { name: label });
+    await expect(region).toHaveAttribute('data-test', skeletonTestIds.GROUP);
+    await expect(region).toHaveAttribute('aria-busy', 'true');
+    const blocks = within(region).getAllByTestId(skeletonTestIds.ROOT);
+    await expect(blocks).toHaveLength(blockCount);
+    return { region, blocks };
+};
+
+/** The spec every block follows: 4px radius, decorative, and the wave on `::after` unless motion is reduced. */
+const expectSpec = async (blocks: HTMLElement[]) => {
+    for (const block of blocks) {
+        await expect(block).toHaveAttribute('aria-hidden', 'true');
+        await expect(getComputedStyle(block).borderRadius).toBe(theme.radius.radius4);
+    }
+    const wave = getComputedStyle(blocks[0], '::after');
+    if (prefersReducedMotion()) {
+        await expect(wave.content).toBe('none');
+        return;
+    }
+    await expect(wave.animationDuration).toBe('1.6s');
+    await expect(wave.animationTimingFunction).toBe('ease-in-out');
+    await expect(wave.animationIterationCount).toBe('infinite');
+};
+
+/** Background the block is painted over: the nearest ancestor with an opaque background. */
+const getSurfaceColor = (element: HTMLElement) => {
+    let node = element.parentElement;
+    while (node && getComputedStyle(node).backgroundColor === 'rgba(0, 0, 0, 0)') node = node.parentElement;
+    return node ? getComputedStyle(node).backgroundColor : '';
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/**
+ * The primitive on its own: one block that fills the width of its container. A block sets only its height
+ * (default `1em`), plus a width when a line is shorter than its column.
+ */
+export const Default: Story = {
+    args: {
+        height: theme.space.space16,
+    },
+    decorators: [
+        (Story) => (
+            <Box style={{ maxWidth: '32rem' }}>
+                <Story />
+            </Box>
+        ),
+    ],
+    play: async ({ canvasElement }) => {
+        const block = within(canvasElement).getByTestId(skeletonTestIds.ROOT);
+        await expectSpec([block]);
+        // Without a width, the block fills its container.
+        await expect(block.getBoundingClientRect().width).toBe(block.parentElement?.getBoundingClientRect().width);
+    },
+};
+
+/** apify.com Ideas search results: the richest layout - avatar, heading, paragraph and two footer chips. */
+export const ActorIdeaCards: Story = {
+    render: () => <ActorIdeaCardsSkeleton />,
+    parameters: withSource(actorIdeaCardsSource),
+    play: async ({ canvasElement }) => {
+        const { blocks } = await getLoadingRegion(canvasElement, 'Loading Actor ideas', 6 * 7);
+        await expectSpec(blocks);
+    },
+};
+
+/**
+ * Store home sections, Store search and Actor collections. The footer sits on the `backgroundSubtle` shell
+ * rather than the card body; the translucent skeleton stays visible on both surfaces.
+ */
+export const StoreActorCards: Story = {
+    render: () => <StoreActorCardsSkeleton />,
+    parameters: withSource(storeActorCardsSource),
+    play: async ({ canvasElement }) => {
+        const { blocks } = await getLoadingRegion(canvasElement, 'Loading Actors', 4 * 8);
+        await expectSpec(blocks);
+        const [bodyBlock, , , , footerBlock] = blocks;
+        for (const block of [bodyBlock, footerBlock]) {
+            await expect(getComputedStyle(block).backgroundColor).not.toBe(getSurfaceColor(block));
+        }
+        await expect(getSurfaceColor(footerBlock)).not.toBe(getSurfaceColor(bodyBlock));
+    },
+};
+
+/** Actor publication tab while the LLM assigns categories: real labels, loading values. */
+export const PublicationCategories: Story = {
+    render: () => <PublicationCategoriesSkeleton />,
+    parameters: withSource(publicationCategoriesSource),
+    play: async ({ canvasElement }) => {
+        const { region, blocks } = await getLoadingRegion(canvasElement, 'Assigning categories', 5);
+        await expectSpec(blocks);
+        await expect(within(region).getByText('Use case')).toBeVisible();
+    },
+};
+
+/** Console new Actor wizard: the use-case, language and recommendation cards of a step. */
+export const NewActorWizardCards: Story = {
+    render: () => <NewActorWizardCardsSkeleton />,
+    parameters: withSource(newActorWizardCardsSource),
+    play: async ({ canvasElement }) => {
+        const { blocks } = await getLoadingRegion(canvasElement, 'Loading recommendations', 4 * 6);
+        await expectSpec(blocks);
+    },
+};
+
+const STORE_ACTORS = [
+    {
+        id: '1',
+        title: 'Website Content Crawler',
+        name: 'apify/website-content-crawler',
+        description: 'Crawl websites and extract text content to feed AI models and LLM applications.',
+        author: 'Apify',
+        stats: '4.6 · 92K users',
+    },
+    {
+        id: '2',
+        title: 'Google Maps Scraper',
+        name: 'compass/crawler-google-places',
+        description: 'Extract data from Google Maps places: reviews, contact details, opening hours and more.',
+        author: 'Compass',
+        stats: '4.7 · 210K users',
+    },
+];
+
+const LoadingToggle = () => {
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    return (
+        <Box>
+            <Button size="small" variant="secondary" onClick={() => setIsLoaded((value) => !value)} mb="space16">
+                {isLoaded ? 'Load again' : 'Finish loading'}
+            </Button>
+            <StoreActorCardsLoading actors={isLoaded ? STORE_ACTORS : undefined} />
+        </Box>
+    );
+};
+
+/**
+ * The skeleton is swapped for the content the moment the data lands, and the content fades in over 80 ms.
+ * Because the skeleton mirrors the card, the swap does not move anything on the page.
+ */
+export const FadeIn: Story = {
+    render: () => <LoadingToggle />,
+    parameters: withSource(storeActorCardsLoadingSource),
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        const { region } = await getLoadingRegion(canvasElement, 'Loading Actors', 2 * 8);
+        const skeletonCardHeight = (region.firstElementChild as HTMLElement).getBoundingClientRect().height;
+
+        await userEvent.click(canvas.getByRole('button', { name: 'Finish loading' }));
+
+        await expect(canvas.queryByTestId(skeletonTestIds.ROOT)).not.toBeInTheDocument();
+        const content = canvas.getByTestId(skeletonTestIds.FADE_IN);
+        await expect(content).toHaveTextContent('Website Content Crawler');
+        if (!prefersReducedMotion()) {
+            await expect(getComputedStyle(content).animationDuration).toBe('0.08s');
+        }
+        // The skeleton mirrors the card, so the loaded card is about as tall and nothing below it jumps.
+        const loadedCard = content.firstElementChild?.firstElementChild as HTMLElement;
+        await expect(Math.abs(loadedCard.getBoundingClientRect().height - skeletonCardHeight)).toBeLessThan(16);
+    },
+};

package/src/components/skeleton/skeleton.styled.ts

@@ -0,0 +1,66 @@
+import styled, { keyframes } from 'styled-components';
+
+import { theme } from '../../design_system/theme';
+import { Box } from '../box';
+
+export const skeletonClassNames = {
+    ROOT: 'Skeleton',
+    GROUP: 'Skeleton-Group',
+    FADE_IN: 'Skeleton-FadeIn',
+};
+
+// TODO: move both durations to design tokens (`theme.transition`) once the motion tokens are agreed.
+const WAVE_DURATION = '1600ms';
+const FADE_IN_DURATION = '80ms';
+
+/* The highlight sweeps each block's own width, so short and long blocks start and end together. */
+const wave = keyframes`
+    from { transform: translateX(-100%); }
+    to { transform: translateX(100%); }
+`;
+
+const fadeIn = keyframes`
+    from { opacity: 0; }
+    to { opacity: 1; }
+`;
+
+type StyledSkeletonProps = {
+    $width: string;
+    $height: string;
+};
+
+export const StyledSkeleton = styled(Box)<StyledSkeletonProps>`
+    position: relative;
+    overflow: hidden;
+    flex: 0 1 auto;
+    min-width: 0;
+    width: ${({ $width }) => $width};
+    height: ${({ $height }) => $height};
+    border-radius: ${theme.radius.radius4};
+    /* Base and highlight are both on-surface: the highlight is a second translucent layer over the
+       base, so one token gives a visible sweep on every surface, in light and dark alike. */
+    background-color: ${theme.color.neutral.onSurface};
+
+    &::after {
+        content: '';
+        position: absolute;
+        inset: 0;
+        background: linear-gradient(90deg, transparent, ${theme.color.neutral.onSurface}, transparent);
+        transform: translateX(-100%);
+        animation: ${wave} ${WAVE_DURATION} ease-in-out infinite;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        &::after {
+            content: none;
+        }
+    }
+`;
+
+export const StyledSkeletonFadeIn = styled(Box)`
+    animation: ${fadeIn} ${FADE_IN_DURATION} ease-out both;
+
+    @media (prefers-reduced-motion: reduce) {
+        animation: none;
+    }
+`;

package/src/components/skeleton/skeleton.test_ids.ts

@@ -0,0 +1,5 @@
+export const skeletonTestIds = {
+    ROOT: 'skeleton',
+    GROUP: 'skeleton-group',
+    FADE_IN: 'skeleton-fade-in',
+};

package/src/components/skeleton/skeleton.tsx

@@ -0,0 +1,34 @@
+import clsx from 'clsx';
+import type { ComponentPropsWithoutRef } from 'react';
+
+import type { MarginSpacingProps } from '../box';
+import { StyledSkeleton, skeletonClassNames } from './skeleton.styled';
+import { skeletonTestIds } from './skeleton.test_ids';
+
+// Native onClick clashes with the legacy BoxProps handler type, so it is omitted.
+export interface SkeletonProps
+    extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'onClick'>, MarginSpacingProps {
+    /**
+     * Any CSS length. Defaults to the full width of the container.
+     */
+    width?: string;
+    /**
+     * Any CSS length. Defaults to `1em`, the font size of the surrounding text.
+     */
+    height?: string;
+}
+
+/**
+ * Placeholder block shown only while data is loading. Compose blocks to mirror the layout of the content,
+ * inside a `SkeletonGroup`.
+ */
+export const Skeleton = ({ width = '100%', height = '1em', className, ...rest }: SkeletonProps) => (
+    <StyledSkeleton
+        aria-hidden
+        data-test={skeletonTestIds.ROOT}
+        className={clsx(skeletonClassNames.ROOT, className)}
+        $width={width}
+        $height={height}
+        {...rest}
+    />
+);

package/src/components/skeleton/skeleton.type-test.ts

@@ -0,0 +1,32 @@
+import { expectTypeOf } from 'vitest';
+
+import type { SkeletonFadeInProps, SkeletonGroupProps, SkeletonProps } from './';
+
+// Extends the native <div> element.
+expectTypeOf<SkeletonProps>().toHaveProperty('title');
+expectTypeOf<SkeletonProps>().toHaveProperty('style');
+expectTypeOf<SkeletonFadeInProps>().toHaveProperty('aria-live');
+
+// Own props and margin spacing props.
+expectTypeOf<SkeletonProps>().toHaveProperty('width');
+expectTypeOf<SkeletonProps>().toHaveProperty('height');
+expectTypeOf<SkeletonProps>().toHaveProperty('mb');
+
+// Every block has the same 4px radius, so there is no radius prop.
+expectTypeOf<SkeletonProps>().not.toHaveProperty('radius');
+
+// A skeleton stands in for content, it never holds any.
+expectTypeOf<SkeletonProps>().not.toHaveProperty('children');
+expectTypeOf<SkeletonProps>().not.toHaveProperty('p');
+expectTypeOf<SkeletonFadeInProps>().toHaveProperty('children');
+
+// Neither component is interactive.
+expectTypeOf<SkeletonProps>().not.toHaveProperty('onClick');
+expectTypeOf<SkeletonFadeInProps>().not.toHaveProperty('onClick');
+
+// The group sets its own accessibility attributes and requires a label.
+expectTypeOf<SkeletonGroupProps>().toHaveProperty('label');
+expectTypeOf<SkeletonGroupProps['label']>().toEqualTypeOf<string>();
+expectTypeOf<SkeletonGroupProps>().not.toHaveProperty('role');
+expectTypeOf<SkeletonGroupProps>().not.toHaveProperty('aria-busy');
+expectTypeOf<SkeletonGroupProps>().not.toHaveProperty('aria-label');

package/src/components/skeleton/skeleton_fade_in.tsx

@@ -0,0 +1,21 @@
+import clsx from 'clsx';
+import type { ComponentPropsWithoutRef } from 'react';
+
+import type { MarginSpacingProps, PaddingSpacingProps } from '../box';
+import { StyledSkeletonFadeIn, skeletonClassNames } from './skeleton.styled';
+import { skeletonTestIds } from './skeleton.test_ids';
+
+// Native onClick clashes with the legacy BoxProps handler type, so it is omitted.
+export interface SkeletonFadeInProps
+    extends Omit<ComponentPropsWithoutRef<'div'>, 'onClick'>, MarginSpacingProps, PaddingSpacingProps {}
+
+/**
+ * Wraps the content that replaces a skeleton, so it fades in once instead of popping in.
+ */
+export const SkeletonFadeIn = ({ className, ...rest }: SkeletonFadeInProps) => (
+    <StyledSkeletonFadeIn
+        data-test={skeletonTestIds.FADE_IN}
+        className={clsx(skeletonClassNames.FADE_IN, className)}
+        {...rest}
+    />
+);

package/src/components/skeleton/skeleton_group.tsx

@@ -0,0 +1,32 @@
+import clsx from 'clsx';
+import type { ComponentPropsWithoutRef } from 'react';
+
+import { Box, type MarginSpacingProps, type PaddingSpacingProps } from '../box';
+import { skeletonClassNames } from './skeleton.styled';
+import { skeletonTestIds } from './skeleton.test_ids';
+
+// Native onClick clashes with the legacy BoxProps handler type, so it is omitted.
+export interface SkeletonGroupProps
+    extends
+        Omit<ComponentPropsWithoutRef<'div'>, 'onClick' | 'role' | 'aria-busy' | 'aria-label'>,
+        MarginSpacingProps,
+        PaddingSpacingProps {
+    /**
+     * What is loading, used as the accessible name of the region, e.g. "Loading Actors".
+     */
+    label: string;
+}
+
+/**
+ * Wraps the skeleton blocks of one loading region, names it and marks it busy for assistive technology.
+ */
+export const SkeletonGroup = ({ label, className, ...rest }: SkeletonGroupProps) => (
+    <Box
+        role="status"
+        aria-busy
+        aria-label={label}
+        data-test={skeletonTestIds.GROUP}
+        className={clsx(skeletonClassNames.GROUP, className)}
+        {...rest}
+    />
+);

package/src/design_system/colors/build_color_tokens.js

@@ -110,10 +110,12 @@ StyleDictionary.registerFilter({
     filter: (token) => ['Palette'].includes(token.path[0]),
 });
 
-// Select only tokens for theme colors (Decorative and Palette)
+// Select only tokens for theme colors (Decorative, Palette, Brand and Third Party)
 StyleDictionary.registerFilter({
     name: 'only-theme',
-    filter: (token) => ['Decorative', 'Palette', 'Brand'].includes(token.path[0]),
+    filter: (token) =>
+        ['Decorative', 'Palette', 'Brand'].includes(token.path[0]) ||
+        (token.path[0] === 'Semantic' && token.path[1] === 'Third_Party'),
 });
 
 // Select only the semantic neutral tokens (used for the brand dark neutral override)

package/src/design_system/colors/colors.stories.tsx

@@ -36,6 +36,13 @@ const decorativePaletteFamilies = [
     'slate',
 ];
 const brandPaletteFamilies = ['magenta', 'mondo', 'lime', 'meteorite', 'logo'];
+// Semantic tokens are labelled only by these families, so other theme values (e.g. third-party brand colors) can't take over the labels.
+const labelPaletteFamilies = [
+    ...basePaletteFamilies,
+    ...neutralPaletteFamilies,
+    ...decorativePaletteFamilies,
+    ...brandPaletteFamilies,
+];
 const semanticColorSections: SemanticColorSection[] = [
     {
         title: 'Neutral',
@@ -173,7 +180,8 @@ const getColorDisplayName = (name: string, prefix: string) => {
 
 const getPaletteNameByValue = (value: string, palette: Record<string, string>) => {
     const paletteColor = Object.entries(palette).find(
-        ([, paletteValue]) => paletteValue.toLowerCase() === value.toLowerCase(),
+        ([name, paletteValue]) =>
+            labelPaletteFamilies.includes(getPaletteFamily(name)) && paletteValue.toLowerCase() === value.toLowerCase(),
     );
 
     return paletteColor ? formatLabel(paletteColor[0]) : 'Color';

package/src/design_system/colors/generated/colors_theme.dark.ts

@@ -3,6 +3,19 @@
  */
 
 export const darkTheme = {
+    thirdPartyAnthropic: '#d97757',
+    thirdPartyChatGpt: '#ffffff',
+    thirdPartyClaude: '#d97757',
+    thirdPartyCursor: '#ffffff',
+    thirdPartyDiscord: '#5865f2',
+    thirdPartyGithub: '#ffffff',
+    thirdPartyLinkedin: '#0a66c2',
+    thirdPartyMake: '#6d00cc',
+    thirdPartyN8n: '#ea4b71',
+    thirdPartyPerplexity: '#20808d',
+    thirdPartyTwitter: '#ffffff',
+    thirdPartyYoutube: '#ff0000',
+    thirdPartyZapier: '#ff4a00',
     magentaDeep: '#694d6b',
     magentaMain: '#9d829f',
     magentaTint: '#fef3ff',

package/src/design_system/colors/generated/colors_theme.light.ts

@@ -3,6 +3,19 @@
  */
 
 export const lightTheme = {
+    thirdPartyAnthropic: '#d97757',
+    thirdPartyChatGpt: '#000000',
+    thirdPartyClaude: '#d97757',
+    thirdPartyCursor: '#000000',
+    thirdPartyDiscord: '#5865f2',
+    thirdPartyGithub: '#181717',
+    thirdPartyLinkedin: '#0a66c2',
+    thirdPartyMake: '#6d00cc',
+    thirdPartyN8n: '#ea4b71',
+    thirdPartyPerplexity: '#20808d',
+    thirdPartyTwitter: '#000000',
+    thirdPartyYoutube: '#ff0000',
+    thirdPartyZapier: '#ff4a00',
     magentaDeep: '#694d6b',
     magentaMain: '#9d829f',
     magentaTint: '#fef3ff',

package/src/test_ids.ts

@@ -16,6 +16,7 @@ export {
     selectControlTestId,
     selectMultiValueLabelTestId,
 } from './components/select/select.test_ids.js';
+export { skeletonTestIds } from './components/skeleton/skeleton.test_ids.js';
 export { spinnerTestIds } from './components/spinner/spinner.test_ids.js';
 export {
     splitButtonMainActionTestId,