@solostylist/ui-kit 2.0.1 → 2.0.3

package/dist/s-product-card/s-product-card.d.ts

@@ -0,0 +1,216 @@
+import { BoxProps, CardProps, TypographyProps } from '@mui/material';
+import { SIconButtonProps } from '../s-icon-button/s-icon-button';
+import { SLazyImageProps } from '../s-lazy-image/s-lazy-image';
+import { SSwatchVisualProps } from '../s-swatch/s-swatch';
+import { OwnerStateSlotProps as MuiOwnerStateSlotProps } from '../utils/slots';
+import * as React from 'react';
+/** Density preset. All four share one anatomy and differ only in layout and spacing. */
+export type SProductCardVariant = 'grid' | 'list' | 'mini' | 'overlay';
+/** Logical corner of the media the badge is pinned to. Safe in LTR and RTL layouts. */
+export type SProductCardBadgePlacement = 'bottom-end' | 'bottom-start' | 'top-end' | 'top-start';
+/** One valid color or image option summarised in the swatch row. */
+export type SProductCardSwatch = SSwatchVisualProps & {
+    /** Optional display and accessible label. */
+    label?: string;
+    /** Stable key and human-readable option value. */
+    value: string;
+};
+/** Stretched primary-action props. Navigation and activation stay owned by the top-level API. */
+export type SProductCardLinkProps = Omit<BoxProps, 'children' | 'component' | 'onClick'> & Pick<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'download' | 'rel' | 'target'> & {
+    /** Disable the MUI touch ripple for the primary action. */
+    disableRipple?: boolean;
+    /** Enable the keyboard focus ripple. */
+    focusRipple?: boolean;
+    /** Class applied while the primary action is keyboard-focus-visible. */
+    focusVisibleClassName?: string;
+};
+/** Root surface props that do not duplicate SProductCard's interaction API. */
+export type SProductCardRootProps = Omit<CardProps, 'children' | 'component' | 'onClick'>;
+export interface SProductCardSlots {
+    /** Trailing cluster of the footer row, holding the favorite toggle and `actions`. */
+    actions?: React.ElementType;
+    /** Promotional label pinned over the media. */
+    badge?: React.ElementType;
+    /** Text column below the media. */
+    content?: React.ElementType;
+    /** Built-in favorite toggle. */
+    favoriteButton?: React.ElementType;
+    /** Bottom row of the content column. */
+    footer?: React.ElementType;
+    /** Layer revealed over the media on hover, focus, and on touch devices. */
+    hoverActions?: React.ElementType;
+    /** Second image cross-faded in on hover. */
+    hoverImage?: React.ElementType;
+    /** Primary media image. */
+    image?: React.ElementType;
+    /** Stretched link covering the whole card. */
+    link?: React.ElementType;
+    /** Media frame that clips the image and positions the badge and hover actions. */
+    media?: React.ElementType;
+    /** Secondary information row under the title. */
+    meta?: React.ElementType;
+    /** Price group of the footer row. */
+    price?: React.ElementType;
+    /** Struck-through original price. */
+    originalPrice?: React.ElementType;
+    /** Rating row under the title. */
+    rating?: React.ElementType;
+    /** Card surface. */
+    root?: React.ElementType;
+    /** Swatch summary row. */
+    swatches?: React.ElementType;
+    /** Product name. */
+    title?: React.ElementType;
+}
+type OwnerStateSlotProps<Props> = MuiOwnerStateSlotProps<Props, SProductCardOwnerState>;
+export interface SProductCardSlotProps {
+    /** Props or owner-state callback for the actions slot. */
+    actions?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the badge slot. */
+    badge?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the content slot. */
+    content?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the favorite button slot. */
+    favoriteButton?: OwnerStateSlotProps<Omit<SIconButtonProps, 'children'>>;
+    /** Props or owner-state callback for the footer slot. */
+    footer?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the hover actions slot. */
+    hoverActions?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the hover image slot. */
+    hoverImage?: OwnerStateSlotProps<Omit<SLazyImageProps, 'alt' | 'src'>>;
+    /** Props or owner-state callback for the image slot. */
+    image?: OwnerStateSlotProps<Omit<SLazyImageProps, 'alt' | 'src'>>;
+    /** Props or owner-state callback for the stretched link slot. */
+    link?: OwnerStateSlotProps<SProductCardLinkProps>;
+    /** Props or owner-state callback for the media slot. */
+    media?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the meta slot. */
+    meta?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the price slot. */
+    price?: OwnerStateSlotProps<Omit<TypographyProps, 'children'>>;
+    /** Props or owner-state callback for the original-price slot. */
+    originalPrice?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the rating slot. */
+    rating?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the root slot. */
+    root?: OwnerStateSlotProps<SProductCardRootProps>;
+    /** Props or owner-state callback for the swatches slot. */
+    swatches?: OwnerStateSlotProps<Omit<BoxProps, 'children'>>;
+    /** Props or owner-state callback for the title slot. */
+    title?: OwnerStateSlotProps<Omit<TypographyProps, 'children'>>;
+}
+/**
+ * Props for a presentation-only product card. Every region is a `ReactNode` prop
+ * with a matching slot, so no commerce model, formatter, or router is involved.
+ */
+export interface SProductCardProps extends Omit<CardProps, 'children' | 'component' | 'onClick' | 'title' | 'variant'> {
+    /** Action cluster rendered at the trailing end of the footer row. */
+    actions?: React.ReactNode;
+    /**
+     * Alternative text for the built-in image. Empty by default because the
+     * primary card action is already labelled by the visible product title.
+     */
+    alt?: string;
+    /** Media aspect ratio, used when `mediaHeight` is not set. */
+    aspectRatio?: number | string;
+    /** Promotional label rendered over the media — a discount chip, "new", and so on. */
+    badge?: React.ReactNode;
+    /** Corner of the media the badge is pinned to. */
+    badgePlacement?: SProductCardBadgePlacement;
+    /** Initial favorite state for uncontrolled usage. */
+    defaultFavorite?: boolean;
+    /** Disables the primary action and removes all built-in action regions from the tab order. */
+    disabled?: boolean;
+    /** Keeps the hover border feedback but removes the card translate and scale. */
+    disableLift?: boolean;
+    /** Favorite state for controlled usage. */
+    favorite?: boolean;
+    /** Icon of the favorite toggle while favorited. */
+    favoriteActiveIcon?: React.ReactNode;
+    /** Accessible name of the favorite toggle while favorited. */
+    favoriteActiveLabel?: string;
+    /** Icon of the favorite toggle while not favorited. */
+    favoriteIcon?: React.ReactNode;
+    /** Accessible name of the favorite toggle while not favorited. */
+    favoriteLabel?: string;
+    /** Supplemental content rendered between the price and the trailing actions. */
+    footerContent?: React.ReactNode;
+    /** Actions revealed over the media on hover and focus. Always visible on touch devices. */
+    hoverActions?: React.ReactNode;
+    /** Second image URL cross-faded in over the primary image on hover and focus. */
+    hoverImage?: string;
+    /** Link destination. Renders a stretched anchor that covers the whole card. */
+    href?: string;
+    /** Primary media image URL, rendered with `SLazyImage`. Ignored when `media` is set. */
+    image?: string;
+    /** Enables card and media hover/focus effects without changing primary-action semantics. */
+    interactive?: boolean;
+    /** Accessible name of the stretched link. Defaults to the rendered `title`. */
+    linkLabel?: string;
+    /** Maximum swatches rendered before the overflow counter. */
+    maxSwatches?: number;
+    /** Custom media content. Replaces the built-in image and hover image. */
+    media?: React.ReactNode;
+    /** Fixed media height. Takes precedence over `aspectRatio`. */
+    mediaHeight?: number | string;
+    /** Media width. Only meaningful for the `list` variant. */
+    mediaWidth?: number | string;
+    /** Zooms the media image while the card is hovered or focused. */
+    mediaZoom?: boolean;
+    /** Scale factor of the media zoom. */
+    mediaZoomScale?: number;
+    /** Secondary information under the title — tags, category, or an option summary. */
+    meta?: React.ReactNode;
+    /** Called when the card is activated. Used instead of `href` for non-navigating cards. */
+    onClick?: React.MouseEventHandler<HTMLElement>;
+    /** Called with the next favorite state when the favorite toggle is pressed. */
+    onFavoriteChange?: (event: React.MouseEvent<HTMLButtonElement>, favorite: boolean) => void;
+    /** Pre-formatted current price. Formatting and currency stay with the consumer. */
+    price?: React.ReactNode;
+    /** Pre-formatted original price, rendered struck through next to `price`. */
+    originalPrice?: React.ReactNode;
+    /**
+     * Read-only rating. A number renders a read-only `SRating`; any other node is
+     * rendered as-is, so a custom rating summary can be injected.
+     */
+    rating?: React.ReactNode;
+    /** Sweeps a light sheen across the card on hover and focus. */
+    sheen?: boolean;
+    /** Renders the built-in favorite toggle at the start of the footer actions. */
+    showFavorite?: boolean;
+    /** Props or owner-state callbacks for internal structural slots. */
+    slotProps?: SProductCardSlotProps;
+    /** Components used for internal structural slots. */
+    slots?: SProductCardSlots;
+    /** Color or image options summarised under the title. Presentational, never focusable. */
+    swatches?: SProductCardSwatch[];
+    /** Accessible name of the swatch summary row. */
+    swatchesLabel?: string;
+    /** Product name. Also labels the primary card action when `linkLabel` is omitted. */
+    title: React.ReactNode;
+    /** Density preset. Replaces the MUI `Card` variant, which is available via `slotProps.root`. */
+    variant?: SProductCardVariant;
+}
+export interface SProductCardOwnerState extends Omit<SProductCardProps, 'slotProps' | 'slots'> {
+    alt: string;
+    aspectRatio: number | string;
+    badgePlacement: SProductCardBadgePlacement;
+    clickable: boolean;
+    disableLift: boolean;
+    disabled: boolean;
+    favorite: boolean;
+    interactive: boolean;
+    maxSwatches: number;
+    mediaZoom: boolean;
+    mediaZoomScale: number;
+    sheen: boolean;
+    showFavorite: boolean;
+    variant: SProductCardVariant;
+}
+/**
+ * Presentation shell for a product card. Media, badge, title, rating, meta,
+ * swatches, price, footer and actions are all `ReactNode` props backed by slots,
+ * and every hover effect is CSS driven so no animation library is pulled in.
+ */
+export declare const SProductCard: React.ForwardRefExoticComponent<Omit<SProductCardProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export default SProductCard;