/**
 * Helper utilities for resolving background data in custom block components.
 *
 * These helpers allow custom block overrides to apply section backgrounds
 * (color, gradient, image, and decorative video) with full theme token support, matching the
 * behavior of the default declarative block system.
 */
import * as React from "react";
import type { ThemeTokens } from "../theme";
import type { Media } from "../../lib/media";
import { type BackgroundMedia } from "./backgroundMedia";
import { type ResolveImageUrlContext } from "../runtime/nodes/media";
/**
 * Raw background data from CMS content fields.
 * This is the shape of `_sectionStyles.background`, `_containerStyles.background`, etc.
 */
export type BackgroundInput = {
    /** Color token name (e.g., "primary") or raw hex value */
    color?: string | null;
    /** CSS gradient string */
    gradient?: string | null;
    /** Background image or decorative video media object */
    image?: Media | null;
    /** Whether decorative background video should play on mobile. Defaults to false. */
    showVideoOnMobile?: boolean | null;
    /** Media sizing mode: 'fill' (cover), 'fit' (contain), 'original', 'custom' */
    objectFit?: string | null;
    /** Media position: preset keyword or custom CSS value */
    position?: string | null;
    /** Media scale value (e.g., "150%", "200px") - only for 'custom'/'original' modes */
    scale?: string | null;
    /** Background opacity (0-1 decimal; legacy 1-100 percentages are still accepted) */
    opacity?: number | null;
    /** Image scroll behavior for image-backed sections. */
    motion?: "static" | "fixed-frame" | null;
    /** Whether background should overflow container bounds */
    overflow?: boolean | null;
    /** Overlay configuration for image/video media */
    overlay?: {
        /** Overlay type: 'color', 'gradient', or 'none' */
        type?: "color" | "gradient" | "none" | null;
        /** Overlay color token or hex value */
        color?: string | null;
        /** Overlay CSS gradient string */
        gradient?: string | null;
        /** Overlay opacity (0-1 decimal; legacy 1-100 percentages are still accepted) */
        opacity?: number | null;
    } | null;
};
/**
 * Resolved background ready for rendering.
 * Token names are converted to actual hex values.
 */
export type ResolvedBackground = {
    /** Resolved background color (hex value or null) */
    color: string | null;
    /** CSS gradient string */
    gradient: string | null;
    /** Opacity value (0-1) */
    opacity: number | null;
    /** Whether background should overflow */
    overflow: boolean;
    /** Resolved image/video media data. Retains the legacy `image` property name for saved background compatibility. */
    image: {
        /** Media kind */
        kind: BackgroundMedia["type"];
        /** Media URL */
        url: string;
        /** Alt text */
        alt: string;
        /** Original width */
        width?: number;
        /** Original height */
        height?: number;
        /** Poster URL for decorative video fallbacks */
        poster?: string;
        /** Poster URL to render as the mobile-only fallback layer */
        mobileFallbackPoster?: string;
    } | null;
    /** Inline styles for the image/video element */
    imageStyle: React.CSSProperties;
    /** CSS classes for the image/video element */
    imageClassName: string;
    /** Resolved overlay data for rendering on top of image/video media */
    overlay: {
        /** Overlay type */
        type: "color" | "gradient" | "none";
        /** Resolved background color (hex) */
        backgroundColor: string | null;
        /** CSS gradient string */
        backgroundImage: string | null;
        /** Opacity value (0-1) */
        opacity: number | null;
    } | null;
};
export type ResolveBackgroundOptions = {
    targetAspectRatio?: number | string;
    imageResolveContext?: ResolveImageUrlContext | null;
};
/**
 * Resolves background data from CMS content to render-ready values.
 *
 * This helper converts raw background field data (with token names like "primary")
 * into resolved values (with actual hex colors from the theme palette).
 *
 * @param background - Raw background data from content (e.g., content._sectionStyles?.background)
 * @param theme - Theme tokens containing the palette for token resolution
 * @returns Resolved background with all values ready for rendering
 *
 * @example
 * ```tsx
 * import { resolveBackground } from '../../index';
 * // or from SDK: import { resolveBackground } from '@riverbankcms/sdk/rendering';
 *
 * function CustomBlock({ content, theme, imageResolveContext }: CustomBlockProps) {
 *   const bg = resolveBackground(content._sectionStyles?.background, theme, {
 *     imageResolveContext,
 *   });
 *
 *   return (
 *     <section
      *       className="rb-relative"

 *       style={{ backgroundColor: bg.color ?? undefined }}
 *     >
 *       {bg.image && (
 *         <img
 *           src={bg.image.url}
 *           alt={bg.image.alt}
 *           className={bg.imageClassName}
 *           style={bg.imageStyle}
 *         />
 *       )}
 *       {content.heading}
 *     </section>
 *   );
 * }
 * ```
 */
export declare function resolveBackground(background: BackgroundInput | null | undefined, theme?: ThemeTokens, options?: ResolveBackgroundOptions): ResolvedBackground;
export type SectionBackgroundProps = {
    /** Raw background data from content (e.g., content._sectionStyles?.background) */
    background: BackgroundInput | null | undefined;
    /** Theme tokens for resolving color tokens to hex values */
    theme?: ThemeTokens;
    /** Target aspect ratio used to resolve aspect-specific crop metadata */
    targetAspectRatio?: number | string;
    /**
     * Render-scoped media context for resolving identifier-only images without
     * falling back to module-level state.
     *
     * In block overrides, pass `imageResolveContext` from `BlockOverrideProps`.
     */
    imageResolveContext?: ResolveImageUrlContext | null;
    /**
     * Additional className applied to background layers.
     *
     * **Note**: This className is applied to BOTH the color/gradient layer AND the
     * image layer when both exist. If you need different classes for each layer,
     * use the `resolveBackground()` helper directly for more control.
     */
    className?: string;
};
/**
 * Renders a complete background layer (color, gradient, image, and/or decorative video).
 *
 * This component handles all the complexity of rendering backgrounds from
 * CMS content, including theme token resolution, media positioning, opacity,
 * and the shared reduced-motion background-video marker.
 *
 * Use this component in custom block overrides to easily apply section backgrounds.
 *
 * @example
 * ```tsx
 * import { SectionBackground } from '../../index';
 * // or from SDK: import { SectionBackground } from '@riverbankcms/sdk/rendering';
 *
 * function CustomBlock({ content, theme, imageResolveContext }: CustomBlockProps) {
 *   return (
 *     <section className="rb-relative rb-py-16">
 *       <SectionBackground
 *         background={content._sectionStyles?.background}
 *         theme={theme}
 *         imageResolveContext={imageResolveContext}
 *       />
 *       <div className="rb-container rb-relative rb-z-10">
 *         {content.heading}
 *       </div>
 *     </section>
 *   );
 * }
 * ```
 */
export declare function SectionBackground({ background, theme, targetAspectRatio, imageResolveContext, className, }: SectionBackgroundProps): React.ReactElement | null;
