@teamimpact/veda-ui-blocks 0.1.0-beta.13 → 0.1.0-beta.14

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode, ReactElement, ImgHTMLAttributes, SVGProps, VideoHTMLAttributes, CanvasHTMLAttributes, ComponentProps, ElementType, ComponentPropsWithRef } from 'react';
+import { ReactNode, ElementType, ComponentPropsWithRef, ReactElement, ImgHTMLAttributes, SVGProps, VideoHTMLAttributes, CanvasHTMLAttributes } from 'react';
 import { StyleSpecification } from 'maplibre-gl';
 import { ViewState } from 'react-map-gl/maplibre';
 
@@ -47,10 +47,43 @@ type BannerProps = {
  */
 declare function Banner({ ariaLabel, bannerHeaderText, bannerHeaderActionText, bannerIcon, bannerExpandedContent, className, }: BannerProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * @private
+ * should only be used by components within veda-ui-blocks
+ */
+type AsLinkProps<T extends ElementType = "a"> = {
+    /**
+     * The element or component to render as (e.g. "a", "button", RouterLink). Optional. Defaults to 'a'
+     * Note, TS is unable to check props against inferred generics when spread is used.
+     * For accurate prop checking, `as` prop needs to be explicitly defined.
+     * ex. ❌ <AsLink {...props} /> vs ✅ <AsLink {...props} as="a" />
+     */
+    as?: T;
+    isExternal?: boolean;
+} & Omit<ComponentPropsWithRef<T>, "as">;
+
+declare const LINK_VARIANTS: readonly ["text", "button", "button-outline", "arrow"];
+declare const LINK_SIZES: readonly ["md", "lg"];
+type LinkVariant = (typeof LINK_VARIANTS)[number];
+type LinkSize = (typeof LINK_SIZES)[number];
+
+type LinkProps<T extends ElementType = "a"> = AsLinkProps<T> & {
+    /**
+     * Optional visual treatment. Defaults to text.
+     */
+    variant?: LinkVariant;
+    /**
+     * Optional size. Defaults to md.
+     */
+    size?: LinkSize;
+    isExternal?: boolean;
+};
+declare function Link<T extends ElementType>({ variant, size, isExternal, className, as, children, ...rest }: LinkProps<T>): react_jsx_runtime.JSX.Element;
+
 type CardMediaElement = ReactElement<ImgHTMLAttributes<HTMLImageElement>, "img"> | ReactElement<SVGProps<SVGSVGElement>, "svg"> | ReactElement<VideoHTMLAttributes<HTMLVideoElement>, "video"> | ReactElement<CanvasHTMLAttributes<HTMLCanvasElement>, "canvas">;
 type LogoMediaElement = ReactElement<ImgHTMLAttributes<HTMLImageElement>, "img"> | ReactElement<SVGProps<SVGSVGElement>, "svg">;
 
-type CardProps = {
+type CardProps<CTA1 extends ElementType = "a", CTA2 extends ElementType = "a"> = {
     /** Optional: label/tag shown above title. */
     tag?: ReactNode;
     /** Optional: heading text for the card. */
@@ -59,17 +92,15 @@ type CardProps = {
     subtitle?: string;
     /** Optional: body text for the card. */
     description?: string;
-    /** Optional: Call to action for the card. */
-    callToAction?: {
+    /** Optional: Call to action for the card. Defaults to button variant */
+    callToAction?: LinkProps<CTA1> & {
         label: string;
-        href: string;
-        isExternal?: boolean;
+        children?: never;
     };
-    /** Optional: Secondary outlined call to action for the card. */
-    callToActionSecondary?: {
+    /** Optional: Secondary outlined call to action for the card. Defaults to button-outline variant*/
+    callToActionSecondary?: LinkProps<CTA2> & {
         label: string;
-        href: string;
-        isExternal?: boolean;
+        children?: never;
     };
     /** Required: media element rendered as either the card background or
      * an image within the card.
@@ -85,6 +116,7 @@ type CardProps = {
      * "light" is intended for use on light backgrounds,
      * "dark" is intended for use on dark backgrounds, and
      * "brand" applies color styles that are brand specific.
+     * * Defaults to "light".
      */
     colorMode?: "light" | "dark" | "brand";
     /** Optional: Whether the card is intended to fill the width of the site with a centered container for content. */
@@ -92,24 +124,27 @@ type CardProps = {
     className?: string;
     children?: ReactNode;
 };
-declare function Card({ tag, title, description, subtitle, callToAction, callToActionSecondary, image, imagePosition, colorMode, isMastHead, className, children, }: CardProps): react_jsx_runtime.JSX.Element;
+declare function Card<CTA1 extends ElementType, CTA2 extends ElementType>(props: CardProps<CTA1, CTA2>): react_jsx_runtime.JSX.Element;
 
-type CardCTAProps = ComponentProps<"a"> & {
+type CardCTAProps<T extends ElementType = "a"> = AsLinkProps<T> & {
     /** Required: heading text for the card. */
     title: string;
-    /** Required: link URL the card navigates to. */
-    url: string;
+    /** Semantic heading level for the title. */
+    titleAs?: "h2" | "h3" | "h4" | "h5" | "h6";
     /** Optional: body copy shown below the title row. */
     description?: string;
     /** Optional: accent color used for icon and title underline on hover/focus. */
     accentColor?: string;
-    /** Semantic heading level for the title. */
-    titleAs?: "h2" | "h3" | "h4" | "h5" | "h6";
-    className?: string;
+    /**
+     * Optional parameter to define the link as external to site.
+     * Adds visual indication and native link properties target and rel.
+     */
+    isExternal?: boolean;
+    children?: never;
 };
-declare function CardCTA({ title, url, description, accentColor, titleAs, className, style, ...rest }: CardCTAProps): react_jsx_runtime.JSX.Element;
+declare function CardCTA<T extends ElementType>({ title, titleAs, description, accentColor, className, style, isExternal, as, ...rest }: CardCTAProps<T>): react_jsx_runtime.JSX.Element;
 
-type CardDetailedProps = {
+type CardDetailedProps<CTA1 extends ElementType = "a", CTA2 extends ElementType = "a"> = {
     /** Optional: intro text above the title */
     intro?: string;
     /** Optional: heading text for the card */
@@ -120,17 +155,15 @@ type CardDetailedProps = {
     tagPrimary?: ReactNode;
     /** Optional: Array of tags below description */
     tags?: ReactNode[];
-    /** Optional: Call to action for the card. */
-    callToAction?: {
+    /** Optional: Call to action for the card. Defaults to button variant */
+    callToAction?: LinkProps<CTA1> & {
         label: string;
-        href: string;
-        isExternal?: boolean;
+        children?: never;
     };
-    /** Optional: Secondary outlined call to action for the card. */
-    callToActionSecondary?: {
+    /** Optional: Secondary outlined call to action for the card. Defaults to button-outline variant*/
+    callToActionSecondary?: LinkProps<CTA2> & {
         label: string;
-        href: string;
-        isExternal?: boolean;
+        children?: never;
     };
     /** Required: media element rendered as either the card background or
      * an image within the card.
@@ -147,35 +180,33 @@ type CardDetailedProps = {
 /**
  * CardDetailed: Vertical layout, image on top, overlay tag, intro, title, description, tags, action.
  */
-declare function CardDetailed({ intro, title, description, tags, callToAction, callToActionSecondary, tagPrimary, image, imagePosition, className, }: CardDetailedProps): react_jsx_runtime.JSX.Element;
+declare function CardDetailed<CTA1 extends ElementType, CTA2 extends ElementType>({ intro, title, description, tags, callToAction, callToActionSecondary, tagPrimary, image, imagePosition, className, }: CardDetailedProps<CTA1, CTA2>): react_jsx_runtime.JSX.Element;
 
-type CardMiniProps = {
+type CardMiniProps<T extends ElementType = "a"> = AsLinkProps<T> & {
     /** Required: media element rendered as the card image thumbnail. */
     image: CardMediaElement;
     /** Required: heading text for the card. */
     title: string;
-    /** Required: link URL the card navigates to. */
-    url: string;
-    /** Optional: label rendered below the title. Pass a Tag component. */
-    tag?: ReactNode;
     /** Semantic heading level for the title. */
     titleAs?: "h2" | "h3" | "h4" | "h5" | "h6";
-    className?: string;
-};
-declare function CardMini({ image, title, url, tag, titleAs, className }: CardMiniProps): react_jsx_runtime.JSX.Element;
-
-type CardSimpleProps = {
-    /** Required: heading text for the card. */
-    title: string;
-    /** Required: media element rendered as the card background. */
-    image: CardMediaElement;
-    /** Required: link URL the card navigates to. */
-    url: string;
+    /** Optional: label rendered below the title. Pass a Tag component. */
+    tag?: ReactNode;
     /**
      * Optional parameter to define the link as external to site.
      * Adds visual indication and native link properties target and rel.
      */
     isExternal?: boolean;
+    children?: never;
+};
+declare function CardMini<T extends ElementType>({ image, title, titleAs, tag, className, isExternal, as, ...rest }: CardMiniProps<T>): react_jsx_runtime.JSX.Element;
+
+type CardSimpleProps<T extends ElementType = "a"> = AsLinkProps<T> & {
+    /** Required: media element rendered as the card background. */
+    image: CardMediaElement;
+    /** Required: heading text for the card. */
+    title: string;
+    /** Semantic heading level for title. */
+    titleAs?: "h2" | "h3" | "h4" | "h5" | "h6";
     /** Optional: label rendered at the top of the card. Pass a Tag component. */
     tag?: ReactNode;
     /**
@@ -183,11 +214,75 @@ type CardSimpleProps = {
      * Defaults to `default`.
      */
     size?: "default" | "compact";
-    /** Semantic heading level for title. */
-    titleAs?: "h2" | "h3" | "h4" | "h5" | "h6";
+    /**
+     * Optional parameter to define the link as external to site.
+     * Adds visual indication and native link properties target and rel.
+     */
+    isExternal?: boolean;
+    children?: never;
+};
+declare function CardSimple<T extends ElementType>({ image, title, titleAs, tag, size, className, isExternal, as, ...rest }: CardSimpleProps<T>): react_jsx_runtime.JSX.Element;
+
+type TagProps = {
+    /**
+     * Visual treatment for the tag. Defaults to solid.
+     */
+    variant?: "solid" | "outline" | "text";
+    size?: "default" | "big";
+    /**
+     * Custom color used as the fill (solid variant), outline and text (outline variant), or text only (text variant) color depending on the chosen variant.
+     */
+    color?: string;
+    /**
+     * Optional override for the tag border color independent of variant.
+     */
+    borderColor?: string;
+    /**
+     * Optional override for the tag bg color independent of variant.
+     */
+    bgColor?: string;
+    /**
+     * Optional override for the tag text color independent of variant.
+     */
+    textColor?: string;
+    /**
+     * Icon to display on the left of the label. When provided, the `blocks-tag--icon` modifier is applied automatically.
+     */
+    icon?: ReactNode;
+    /**
+     * Callback for the close button. When provided, a close button is rendered automatically.
+     */
+    onClose?: () => void;
+    children: ReactNode;
+    className?: string;
+};
+/**
+ * Our custom Tag wrapper aligned to package-level SCSS styling.
+ * Public style contract: `.blocks-tag`, modifiers (`--solid`, `--outline`, `--text`, `--big`, `--icon`, `--x-close`),
+ * and elements (`__icon`, `__close-button`, `__close-icon`).
+ */
+declare function Tag({ variant, size, color, bgColor, borderColor, textColor, icon, onClose, children, className, }: TagProps): react_jsx_runtime.JSX.Element;
+
+type CarouselItem = Omit<CardProps, "tag" | "imagePosition" | "colorMode" | "isMastHead" | "subtitle" | "callToActionSecondary" | "className" | "children"> & {
+    /** Optional: label rendered as a Tag above the title.  */
+    tag?: Omit<TagProps, "onClose" | "children"> & {
+        label: string;
+    };
+};
+type CarouselProps = {
+    /** Required: array of slide data rendered as Card components. */
+    items: CarouselItem[];
+    /**
+     * Optional: max number of cards visible at once on desktop.
+     * - 1: full width (1 card per view)
+     * - 2: half width, 2 cards side by side (default)
+     * - 3: third width, 3 cards side by side
+     * All layouts collapse to 1 card per view on mobile.
+     */
+    maxVisibleItems?: 1 | 2 | 3;
     className?: string;
 };
-declare function CardSimple({ title, image, url, isExternal, tag, size, titleAs, className, }: CardSimpleProps): react_jsx_runtime.JSX.Element;
+declare function Carousel({ items, maxVisibleItems, className }: CarouselProps): react_jsx_runtime.JSX.Element;
 
 type NavItem$1 = {
     label: string;
@@ -241,87 +336,6 @@ interface HeaderProps {
 }
 declare function Header(props: HeaderProps): react_jsx_runtime.JSX.Element;
 
-declare const LINK_VARIANTS: readonly ["text", "button", "button-outline", "arrow"];
-declare const LINK_SIZES: readonly ["md", "lg"];
-type LinkVariant = (typeof LINK_VARIANTS)[number];
-type LinkSize = (typeof LINK_SIZES)[number];
-
-type LinkProps<T extends ElementType = "a"> = {
-    /**
-     * Optional visual treatment. Defaults to text.
-     */
-    variant?: LinkVariant;
-    /**
-     * Optional size. Defaults to md.
-     */
-    size?: LinkSize;
-    /**
-     * Optional parameter to define Link as external to site.
-     * Adds visual indication and native link properties target and rel.
-     */
-    isExternal?: boolean;
-    /** The element or component to render as (e.g. "a", "button", RouterLink) */
-    as?: T;
-    children: Exclude<ReactNode, null | undefined>;
-} & Omit<ComponentPropsWithRef<T>, "as">;
-/**
- * Polymorphic Link — renders as any element or component via the `as` prop.
- *
- * @example
- * // Native anchor (default)
- * <Link href="https://example.com">Visit</Link>
- *
- * // React Router / TanStack Router
- * <Link as={RouterLink} to="/about">About</Link>
- *
- * // Next.js
- * <Link as={NextLink} href="/dashboard">Dashboard</Link>
- *
- * // Button
- * <Link as="button" onClick={handleClick}>Click me</Link>
- */
-declare function Link<T extends ElementType = "a">({ variant, size, isExternal, className, as, children, ...rest }: LinkProps<T>): react_jsx_runtime.JSX.Element;
-
-type TagProps = {
-    /**
-     * Visual treatment for the tag.
-     */
-    variant?: "solid" | "outline" | "text";
-    size?: "default" | "big";
-    /**
-     * Custom color used as the fill (solid variant), outline and text (outline variant), or text only (text variant) color depending on the chosen variant.
-     */
-    color?: string;
-    /**
-     * Optional override for the tag border color independent of variant.
-     */
-    borderColor?: string;
-    /**
-     * Optional override for the tag bg color independent of variant.
-     */
-    bgColor?: string;
-    /**
-     * Optional override for the tag text color independent of variant.
-     */
-    textColor?: string;
-    /**
-     * Icon to display on the left of the label. When provided, the `blocks-tag--icon` modifier is applied automatically.
-     */
-    icon?: ReactNode;
-    /**
-     * Callback for the close button. When provided, a close button is rendered automatically.
-     */
-    onClose?: () => void;
-    children: ReactNode;
-    className?: string;
-};
-/**
- * Our custom Tag wrapper aligned to package-level SCSS styling.
- * Public style contract: `.blocks-tag`, modifiers (`--solid`, `--outline`, `--text`, `--big`, `--icon`, `--x-close`),
- * and elements (`__icon`, `__close-button`, `__close-icon`).
- */
-declare function Tag({ variant, size, color, bgColor, borderColor, textColor, icon, onClose, children, className, }: TagProps): react_jsx_runtime.JSX.Element;
-
 interface GeoConfigProviderProps {
     stacApiUrl?: string;
     titilerBaseUrl?: string;
@@ -395,6 +409,8 @@ type StacCompareMapProps = {
     rightLayerConfig: StacRasterLayerConfig;
     /** Additional CSS class applied to the root container element. */
     className?: string;
+    /** When true, renders a click-to-activate overlay that prevents scroll hijacking. The overlay reappears when the user clicks outside the map. */
+    showScrollGuard?: boolean;
 };
 /**
  * Smart swipe-slider map for comparing two STAC datasets side-by-side.
@@ -417,7 +433,7 @@ type StacCompareMapProps = {
  * </StacApiProvider>
  * ```
  */
-declare function StacCompareMap({ baseMapStyle, initialViewState, leftLayerConfig, rightLayerConfig, className, }: StacCompareMapProps): react_jsx_runtime.JSX.Element;
+declare function StacCompareMap({ baseMapStyle, initialViewState, leftLayerConfig, rightLayerConfig, className, showScrollGuard, }: StacCompareMapProps): react_jsx_runtime.JSX.Element;
 
 type StacSingleLayerMapProps = {
     /** MapLibre base map style URL or style object. Defaults to Carto Dark with labels. For known vector styles the label layer is derived automatically so STAC data renders beneath labels. */
@@ -426,6 +442,8 @@ type StacSingleLayerMapProps = {
     initialViewState?: Partial<ViewState>;
     /** STAC collection and date range to fetch and display as a raster tile layer. */
     layerConfig: StacRasterLayerConfig;
+    /** When true, renders a click-to-activate overlay that prevents scroll hijacking. The overlay reappears when the user clicks outside the map. */
+    showScrollGuard?: boolean;
 };
 /**
  * Smart map container that fetches STAC collection tiles and renders them with a legend overlay.
@@ -444,6 +462,6 @@ type StacSingleLayerMapProps = {
  * </StacApiProvider>
  * ```
  */
-declare function StacSingleLayerMap({ baseMapStyle, initialViewState, layerConfig, }: StacSingleLayerMapProps): react_jsx_runtime.JSX.Element;
+declare function StacSingleLayerMap({ baseMapStyle, initialViewState, layerConfig, showScrollGuard, }: StacSingleLayerMapProps): react_jsx_runtime.JSX.Element;
 
-export { Banner, type BannerProps, CARTO_DARK_BASEMAP_STYLE, CARTO_DARK_WITH_LABELS_BASEMAP_STYLE, CARTO_LABELS_LAYER_ID, Card, CardCTA, type CardCTAProps, CardDetailed, type CardDetailedProps, CardMini, type CardMiniProps, type CardProps, CardSimple, type CardSimpleProps, Footer, type FooterProps, GeoConfigProvider, type GeoConfigProviderProps, Header, type HeaderProps, Legend, type LegendProps, Link, type LinkProps, NASA_BLUE_MARBLE_BASEMAP_STYLE, OPEN_FREE_MAP_DARK_BASEMAP_STYLE, OPEN_FREE_MAP_LABELS_LAYER_ID, StacCompareMap, type StacCompareMapProps, StacSingleLayerMap, type StacSingleLayerMapProps, Tag, type TagProps };
+export { Banner, type BannerProps, CARTO_DARK_BASEMAP_STYLE, CARTO_DARK_WITH_LABELS_BASEMAP_STYLE, CARTO_LABELS_LAYER_ID, Card, CardCTA, type CardCTAProps, CardDetailed, type CardDetailedProps, CardMini, type CardMiniProps, type CardProps, CardSimple, type CardSimpleProps, Carousel, type CarouselProps, Footer, type FooterProps, GeoConfigProvider, type GeoConfigProviderProps, Header, type HeaderProps, Legend, type LegendProps, Link, type LinkProps, NASA_BLUE_MARBLE_BASEMAP_STYLE, OPEN_FREE_MAP_DARK_BASEMAP_STYLE, OPEN_FREE_MAP_LABELS_LAYER_ID, StacCompareMap, type StacCompareMapProps, StacSingleLayerMap, type StacSingleLayerMapProps, Tag, type TagProps };