@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/Card/components/createBadge.tsx

@@ -0,0 +1,34 @@
+import { ComponentProps } from 'react';
+
+import { Badge } from '../../Badge/Badge';
+import { CardComponent } from '../types';
+import { CardHook } from './types';
+
+/**
+ * Creates the card component that uses the provided hook `useGetBadgeState` to render a `Badge` for a Card. By default the props are `emphasis="bold"` and `round`.
+ *
+ * Returning `false` from the hook will render no badge.
+ */
+export const createBadge = <ExtraData,>({
+    useGetBadgeState,
+}: {
+    /** Returns the props to pass to the badge, or `false` to render no badge. */
+    useGetBadgeState: CardHook<ExtraData, ComponentProps<typeof Badge> | false>;
+}): CardComponent<ExtraData> => ({
+    Component: (props) => {
+        const badgeProps = useGetBadgeState(props);
+
+        if (badgeProps === false) {
+            return null;
+        }
+
+        return (
+            <Badge
+                className="absolute left-xs top-xs z-[1]"
+                emphasis="bold"
+                round
+                {...badgeProps}
+            />
+        );
+    },
+});

package/src/Card/components/createFavoriteButton.tsx

@@ -0,0 +1,40 @@
+import { useCallback } from 'react';
+
+import { FavoriteButton } from '../../FavoriteButton/FavoriteButton';
+import { CardComponent } from '../types';
+import { CardHook } from './types';
+
+/**
+ * Creates the card component that adds a favorite button.
+ *
+ * Callbacks that modify the favorite button:
+ * - `isFavoriteButtonFavorited` - show the favorite button as favorited
+ * - `onFavoriteButtonClick` - handle the favorite button click
+ */
+export const createFavoriteButton = <ExtraData,>({
+    useIsFavorited,
+    useSetFavorited,
+}: {
+    /** Returns whether the favorite button should be favorited. */
+    useIsFavorited: CardHook<ExtraData, boolean>;
+    /** Adds the onclick to the favorite button. */
+    useSetFavorited: CardHook<ExtraData, (favorited: boolean) => void>;
+}): CardComponent<ExtraData> => ({
+    Component: (props) => {
+        const isFavoriteButtonFavorited = useIsFavorited(props);
+        const onFavoriteButtonClick = useSetFavorited(props);
+
+        // Memoize the click handler
+        const handleClick = useCallback(() => {
+            onFavoriteButtonClick(!isFavoriteButtonFavorited);
+        }, [isFavoriteButtonFavorited, onFavoriteButtonClick]);
+
+        return (
+            <FavoriteButton
+                className="absolute right-xs top-xs z-[2]"
+                favorited={isFavoriteButtonFavorited}
+                onClick={handleClick}
+            />
+        );
+    },
+});

package/src/Card/components/createImage.tsx

@@ -0,0 +1,64 @@
+import { ComponentType, useCallback } from 'react';
+
+import { usePreventDefaultLinkOnClick } from '../../providers';
+import { CardComponent } from '../types';
+import { CardHook } from './types';
+
+/**
+ * Helps style an image for a card.
+ */
+export const createImage = <ExtraData,>({
+    aspectRatio = 1,
+    ImageComponent,
+    useHref,
+}: {
+    /** The your rendered image to use. Receives card data as props and `className`.
+     *
+     * **Do not forget to forward the className**
+     */
+    ImageComponent: ComponentType<ExtraData & { className: string }>;
+    /** Optional parameter to set aspect ratio on the image (1:1 by default) */
+    aspectRatio?: number;
+    /** A hook that returns the href to use for the image (makes it a link) */
+    useHref?: CardHook<ExtraData, string>;
+}): CardComponent<ExtraData> => ({
+    Component: (props) => {
+        const href = useHref?.(props);
+        const navigate = usePreventDefaultLinkOnClick();
+
+        const imageClasses = 'w-full object-cover';
+        const linkClasses = 'peer/card-image relative w-full cursor-pointer';
+
+        // Memoize click handler
+        const handleClick = useCallback((href: string) => navigate(href), [navigate]);
+
+        const image = (
+            <ImageComponent
+                className={imageClasses}
+                style={{ aspectRatio }}
+                {...props}
+            />
+        );
+
+        if (href) {
+            return (
+                <a
+                    className={linkClasses}
+                    href={href}
+                    onClick={handleClick(href)}
+                    style={{ aspectRatio }}
+                    tabIndex={-1}
+                >
+                    {image}
+                </a>
+            );
+        }
+
+        return image;
+    },
+    skeletonConfig: {
+        height: 282,
+        type: 'inline',
+        width: 282,
+    },
+});

package/src/Card/components/createInfo.tsx

@@ -0,0 +1,84 @@
+import { ReactNode, useCallback } from 'react';
+
+import { usePreventDefaultLinkOnClick } from '../../providers';
+import { SubtleWeakLink } from '../../Typography/Links/Links';
+import { BodySecondary } from '../../Typography/Text/Text';
+import { CardComponent } from '../types';
+import { CardHook } from './types';
+
+/**
+ * The sizes of the shadows used in the card.
+ *
+ * Pass this to the shadowSize prop of `createInfo`.
+ */
+export const shadowSizes = {
+    footer: 141,
+    location: 282,
+    sellerName: 143,
+    shipping: 79,
+} as const;
+
+/**
+ * Creates the card component that uses the given key of the `CardData` as a piece of info.
+ *
+ * This info might include
+ * - Seller Name
+ * - Location
+ * - Shipping
+ * - Footer
+ */
+export const createInfo = <ExtraData,>({
+    className = 'line-clamp-2',
+    skeletonWidth,
+    useHref,
+    useText,
+}: {
+    /**
+     * Pass styles down including line clamping
+     *
+     * @default 'line-clamp-2'
+     */
+    className?: string;
+    /** The width of the shadow to use. See `shadowSizes` export for options. */
+    skeletonWidth?: number;
+    /** A hook that returns the href to use for the name (makes it a link) */
+    useHref?: CardHook<ExtraData, string>;
+    /** A hook that returns the text to use for the component */
+    useText: CardHook<ExtraData, ReactNode>;
+}): CardComponent<ExtraData> => ({
+    Component: (props) => {
+        const info = useText(props);
+        const href = useHref?.(props);
+        const navigate = usePreventDefaultLinkOnClick();
+
+        // Memoize the click handler
+        const handleClick = useCallback((href: string) => navigate(href), [navigate]);
+
+        if (href) {
+            return (
+                <SubtleWeakLink
+                    className={className}
+                    href={href}
+                    onClick={handleClick(href)}
+                    size="sm"
+                >
+                    {info}
+                </SubtleWeakLink>
+            );
+        }
+
+        return (
+            <BodySecondary
+                className={className}
+                color="secondary"
+            >
+                {info}
+            </BodySecondary>
+        );
+    },
+    skeletonConfig: {
+        height: 22,
+        type: 'inline',
+        width: skeletonWidth,
+    },
+});

package/src/Card/components/createName.tsx

@@ -0,0 +1,63 @@
+import { cn } from '@evolve.ui/theme-system';
+import { ReactNode, useMemo } from 'react';
+
+import { usePreventDefaultLinkOnClick } from '../../providers';
+import { SubtleMonochromeLink } from '../../Typography/Links/Links';
+import { BodySecondary } from '../../Typography/Text/Text';
+import { CardComponent } from '../types';
+import { CardHook } from './types';
+
+/**
+ * Creates the card component with default "name" styles
+ */
+export const createName = <ExtraData,>({
+    className = 'line-clamp-2',
+    useHref,
+    useText,
+}: {
+    /**
+     * Pass styles down including line clamping
+     *
+     * @default 'line-clamp-2'
+     */
+    className?: string;
+    /** The number of lines to wrap */
+    lineClamp?: number;
+    /** A hook that returns the href to use for the name (makes it a link) */
+    useHref?: CardHook<ExtraData, string>;
+    /** A hook that returns the text to use for the component */
+    useText: CardHook<ExtraData, ReactNode>;
+}): CardComponent<ExtraData> => ({
+    Component: (props) => {
+        const navigate = usePreventDefaultLinkOnClick();
+        const name = useText(props);
+        const href = useHref?.(props);
+
+        // Memoize the full class names
+        const linkClasses = useMemo(
+            () =>
+                cn('hui-card-name peer-hover/card-image:text-link-primary peer-hover/card-image:underline', className),
+            []
+        );
+
+        if (href) {
+            return (
+                <SubtleMonochromeLink
+                    className={linkClasses}
+                    href={href}
+                    onClick={navigate(href)}
+                    size="md"
+                >
+                    {name}
+                </SubtleMonochromeLink>
+            );
+        }
+
+        return <BodySecondary className={linkClasses}>{name}</BodySecondary>;
+    },
+    skeletonConfig: {
+        height: 24,
+        type: 'inline',
+        width: 230,
+    },
+});

package/src/Card/components/createPriceStatus.tsx

@@ -0,0 +1,100 @@
+import { useMemo } from 'react';
+import { useIntl } from 'react-intl';
+
+import { InlineButton } from '../../Typography/InlineButton/InlineButton';
+import { BodyPrimary } from '../../Typography/Text/Text';
+import { CardComponent } from '../types';
+import { CardHook } from './types';
+
+export const priceStatusSeeSoldPriceIntlKey = 'hui.card.priceStatusSeeSoldPrice';
+export const priceStatusPreviewOnlyIntlKey = 'hui.card.priceStatusPreviewOnly';
+export const priceStatusSoldIntlKey = 'hui.card.priceStatusSold';
+
+/**
+ * Creates the card component that represents price.
+ */
+export const createPriceStatus = <ExtraData,>({
+    useBidCount,
+    useIsPriceStatusHidden,
+    useIsPriceStatusPreviewOnly,
+    useIsPriceStatusSold,
+    useOnSeeSoldPriceClick,
+    usePrice,
+    useShouldPriceStatusShowBidCount,
+}: {
+    /** A hook that returns the bid count to use for the component */
+    useBidCount?: CardHook<ExtraData, string>;
+    /** Returns whether the price status should be hidden. */
+    useIsPriceStatusHidden?: CardHook<ExtraData, boolean>;
+    /** Returns whether the price status should be "Preview Only". */
+    useIsPriceStatusPreviewOnly?: CardHook<ExtraData, boolean>;
+    /** Returns whether the price status should be "Sold for". */
+    useIsPriceStatusSold?: CardHook<ExtraData, boolean>;
+    /** Adds the onclick to the "See Sold Price" button. */
+    useOnSeeSoldPriceClick?: CardHook<ExtraData, () => void>;
+    /** A hook that returns the price to use for the component */
+    usePrice: CardHook<ExtraData, string>;
+    /** Returns whether the price status should show the bid count. */
+    useShouldPriceStatusShowBidCount?: CardHook<ExtraData, boolean>;
+}): CardComponent<ExtraData> => ({
+    Component: (props) => {
+        const price = usePrice(props);
+        const bidCount = useBidCount?.(props);
+        const { formatMessage } = useIntl();
+
+        const isPriceStatusHidden = useIsPriceStatusHidden?.(props);
+        const isPriceStatusPreviewOnly = useIsPriceStatusPreviewOnly?.(props);
+        const isPriceStatusSold = useIsPriceStatusSold?.(props);
+        const onSeeSoldPriceClick = useOnSeeSoldPriceClick?.(props);
+        const shouldPriceStatusShowBidCount = useShouldPriceStatusShowBidCount?.(props);
+
+        // Memoize classes
+        const containerClasses = 'flex gap-xs';
+        const textClasses = 'hui-text-h5';
+
+        // Memoize formatMessage calls
+        const seeSoldPriceText = useMemo(
+            () => formatMessage({ defaultMessage: 'See Sold Price', id: priceStatusSeeSoldPriceIntlKey }),
+            [formatMessage]
+        );
+        const previewOnlyText = useMemo(
+            () => formatMessage({ defaultMessage: 'Preview Only', id: priceStatusPreviewOnlyIntlKey }),
+            [formatMessage]
+        );
+        const soldForText = useMemo(
+            () =>
+                formatMessage(
+                    {
+                        defaultMessage: 'Sold for {price}',
+                        id: priceStatusSoldIntlKey,
+                    },
+                    { price }
+                ),
+            [formatMessage, price]
+        );
+
+        if (isPriceStatusHidden) {
+            return <InlineButton onClick={() => onSeeSoldPriceClick}>{seeSoldPriceText}</InlineButton>;
+        }
+
+        if (isPriceStatusPreviewOnly) {
+            return <span className={textClasses}>{previewOnlyText}</span>;
+        }
+
+        if (isPriceStatusSold) {
+            return <div className={containerClasses}>{soldForText}</div>;
+        }
+
+        return (
+            <div className={containerClasses}>
+                <span className={textClasses}>{price}</span>
+                {shouldPriceStatusShowBidCount && bidCount && <BodyPrimary color="secondary">{bidCount}</BodyPrimary>}
+            </div>
+        );
+    },
+    skeletonConfig: {
+        height: 22,
+        type: 'inline',
+        width: 56,
+    },
+});

package/src/Card/components/types.ts

@@ -0,0 +1,4 @@
+/**
+ * Helps define hooks used in the `create*` functions.
+ */
+export type CardHook<CardData, ExpectedReturnType> = (data: CardData) => ExpectedReturnType;

package/src/Card/hooks/useCardVisibilityTracking.ts

@@ -0,0 +1,82 @@
+import { useCallback, useRef } from 'react';
+
+import { useIntersectionObserver } from '../../JumpMenu/hooks/useIntersectionObserver';
+
+/**
+ * Options for the useCardVisibilityTracking hook
+ */
+type UseCardVisibilityTrackingOptions = {
+    /**
+     * Threshold at which to trigger the visibility callback.
+     * 0.5 means the callback fires when 50% of the card is visible.
+     * @default 0.5
+     */
+    threshold?: number;
+};
+
+/**
+ * Hook that tracks when a card becomes visible in the viewport
+ * and fires a callback only once per card.
+ *
+ * @param onVisible - Callback function to call when a card becomes visible
+ * @param options - Configuration options for visibility detection
+ * @returns A function that returns a ref callback for a specific card key
+ *
+ * @example
+ * ```tsx
+ * const getVisibilityRef = useCardVisibilityTracking(
+ *   (cardKey) => trackItemVisible(cardKey),
+ *   { threshold: 0.5 }
+ * );
+ *
+ * <Card visibilityRef={getVisibilityRef('card-123')} />
+ * ```
+ */
+export const useCardVisibilityTracking = <CardKey extends string | number>(
+    onVisible: (cardKey: CardKey) => void,
+    options: UseCardVisibilityTrackingOptions = {}
+) => {
+    const { threshold = 0.5 } = options;
+
+    // Track which cards have already triggered the callback
+    const seenCardsRef = useRef<Set<string>>(new Set());
+
+    // Handle intersection changes
+    const handleIntersection = useCallback(
+        (entries: IntersectionObserverEntry[]) => {
+            entries.forEach((entry) => {
+                // Only fire callback if card is intersecting and meets the threshold requirement
+                if (entry.isIntersecting && entry.intersectionRatio >= threshold) {
+                    // Extract card key from the element's data attribute
+                    const element = entry.target as HTMLElement;
+                    const cardKey = element.getAttribute('data-card-key');
+
+                    if (cardKey && !seenCardsRef.current.has(cardKey)) {
+                        seenCardsRef.current.add(cardKey);
+                        onVisible(cardKey as CardKey);
+                    }
+                }
+            });
+        },
+        [onVisible, threshold]
+    );
+
+    // Create intersection observer with specified threshold
+    const { observe } = useIntersectionObserver(handleIntersection, {
+        threshold,
+    });
+
+    // Return a function that creates a ref callback for a specific card key
+    const getRefCallback = useCallback(
+        (cardKey: CardKey) => (element: Element | null) => {
+            if (element) {
+                // Set the card key as a data attribute
+                (element as HTMLElement).setAttribute('data-card-key', String(cardKey));
+                observe(element);
+            }
+        },
+        [observe]
+    );
+
+    return getRefCallback;
+};

package/src/Card/sharedProps.ts

@@ -0,0 +1,12 @@
+import { CreatedCard } from './cardFactory';
+
+export type SharedProps<CardData> = {
+    /**
+     * The card to render. Must be created by `cardFactory`.
+     */
+    card: CreatedCard<CardData>;
+    /**
+     * Force render the skeleton card.
+     */
+    forceSkeleton?: boolean;
+};

package/src/Card/types.ts

@@ -0,0 +1,62 @@
+import { JSX, ReactNode } from 'react';
+
+export type CardComponent<ExtraData> = {
+    /**
+     * Component that gets rendered. Automatically gets passed all values from the card data.
+     */
+    Component: (props: { key?: number } & ExtraData) => JSX.Element | null;
+    /**
+     * The skeleton size of the component.
+     *
+     * We are assuming the item card is `282px` wide.
+     *
+     * `inline` means that it will be tracked and spacing will be added accordingly.
+     *
+     * `absolute` means that it will not be tracked, so you just put a `rect` wherever you like.
+     */
+    skeletonConfig?:
+        | {
+              height?: number;
+              rx?: number;
+              ry?: number;
+              type: 'inline';
+              width?: number;
+          }
+        | {
+              node: ReactNode;
+              type: 'absolute';
+          };
+};
+
+export type Spacer = {
+    spacerPx: number;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- hammer-parity: the ExtraData generic is irrelevant to this Spacer type guard (only `spacerPx` is checked); `unknown` breaks callers via contravariance on CardComponent's Component param
+export const isSpacer = (component: CardComponent<any> | Spacer): component is Spacer =>
+    (component as Spacer).spacerPx > 0;
+
+export type CardSpec<ExtraData> = {
+    /**
+     * The styles for the container of the card.
+     */
+    className?: string;
+    /**
+     * The components that make up the card.
+     *
+     * If you need space between components, do not style the components,
+     * instead, add a number to the array, which will be interpreted as
+     * margin-bottom to the above component.
+     */
+    components: (CardComponent<ExtraData> | Spacer)[];
+    /**
+     * The name of the card.
+     *
+     * Needed for React for better dev experience.
+     */
+    name: string;
+    /**
+     * The height of the skeleton card, if for some reason, the computed one is incorrect.
+     */
+    overrideSkeletonHeightPx?: number;
+};