import type { NodeDefinition } from "../schema";
/**
 * Options for customizing the appearance of background layers.
 */
export type BackgroundLayerOptions = {
    /**
     * CSS class applied to the color/gradient layer container.
     * This layer renders solid colors and gradients.
     *
     * @default 'background-style rb-absolute rb-inset-0 rb-z-neg-10 rb-h-full rb-w-full rb-pointer-events-none'
     */
    styleClassName?: string;
    /**
     * Base CSS classes applied to the background image element.
     * This layer renders background images with dynamic positioning based on scale.
     *
     * Note: Do NOT include positioning (inset-0), sizing (h-full w-full), object-fit, or opacity.
     * Those properties are applied dynamically via transforms:
     * - Positioning/sizing: background.resolveImageClassName (based on scale)
     * - Visual properties: background.resolveImageStyle (object-fit, opacity, width/height)
     *
     * @default 'rb-absolute rb-z-neg-10'
     */
    imageClassName?: string;
    /**
     * CSS class applied to the overlay layer container.
     * This layer renders color/gradient overlays on top of background images.
     *
     * @default 'background-overlay rb-absolute rb-inset-0 rb-z-neg-10 rb-h-full rb-w-full rb-pointer-events-none'
     */
    overlayClassName?: string;
    /**
     * Fallback background token applied to the style layer when no background is configured.
     *
     * This should be a palette token (e.g. 'background', 'surface') or a raw CSS
     * value via `raw:*`.
     */
    fallbackToken?: string;
    /**
     * Omit the conditional image layer while keeping style and overlay layers.
     * Useful when a layout renders the same configured image as foreground media.
     *
     * @default false
     */
    omitImageLayer?: boolean;
};
/**
 * Creates background layer nodes for rendering backgrounds from field data.
 *
 * This helper generates three nodes:
 * 1. A style layer (div) that renders solid colors and gradients
 * 2. A media layer that conditionally renders background images/videos
 * 3. An overlay layer (div) that renders color/gradient overlays on images
 *
 * The layers are designed to be placed behind content (z-index -10) and work
 * with data from `sectionStylesField`, `containerStylesField`, or `cardStylesField`.
 *
 * Layer stacking order (all use -z-10, stacking determined by DOM order):
 * - Content (default z-index, rendered last)
 * - Overlay layer (rendered third, above image due to DOM order)
 * - Image layer (rendered second)
 * - Style layer (rendered first, at bottom)
 *
 * @param path - The data path to the background field (e.g., '_sectionStyles.background')
 * @param options - Optional customization for layer appearance
 * @returns Array of NodeDefinition objects in paint order: style, optional image, overlay
 *
 * @example
 * // Basic usage in a block
 * const heroBackgroundNodes = backgroundLayer('_sectionStyles.background')
 *
 * @example
 * // Custom styling
 * const customBackgroundNodes = backgroundLayer('_sectionStyles.background', {
 *   imageClassName: 'rb-absolute rb-inset-0 rb-z-neg-10 rb-h-full rb-w-full rb-object-cover rb-opacity-30'
 * })
 *
 * @example
 * // In a block layout
 * const layout = section(
 *   { background: 'background' },
 *   [
 *     ...backgroundLayer('_sectionStyles.background'),
 *     sectionContainer([])
 *   ]
 * )
 */
export declare function backgroundLayer(path: string, options?: BackgroundLayerOptions): NodeDefinition[];
/**
 * Creates a media node for rendering background image/video media with conditional rendering.
 *
 * This helper creates a media element that:
 * - Only renders when the media path has a value (via `when` modifier)
 * - Binds to the media data at the specified path (via `bind` modifier)
 * - Applies the provided CSS class for positioning and styling
 * - Applies advanced image options (object-fit, object-position, opacity) via transform
 *
 * Used internally by `backgroundLayer()` but can be used independently for custom layouts.
 *
 * @param path - The data path to the background field (e.g., '_sectionStyles.background')
 * @param className - CSS class for the image element
 * @returns A media NodeDefinition with conditional rendering and data binding
 *
 * @example
 * // Standalone usage
 * const imageNode = createBackgroundImageNode('_sectionStyles.background')
 *
 * @example
 * // Custom styling
 * const imageNode = createBackgroundImageNode(
 *   '_sectionStyles.background',
 *   'rb-absolute rb-inset-0 rb-h-full rb-w-full'
 * )
 */
export declare function createBackgroundImageNode(path: string, baseClassName?: string): NodeDefinition;
/**
 * Creates a div node for rendering color/gradient overlays on background images.
 *
 * This helper creates a div element that:
 * - Is always present in the DOM but invisible when no overlay is configured
 * - Binds to the overlay data at `${path}.overlay`
 * - Applies color/gradient via `background.resolveOverlayStyle` transform
 *
 * The overlay appears above the image due to DOM order (both use -z-10).
 * When no overlay is configured, the transform returns {} making the div invisible.
 *
 * Used internally by `backgroundLayer()` but can be used independently for custom layouts.
 *
 * @param path - The data path to the background field (e.g., '_sectionStyles.background')
 * @param className - CSS class for the overlay element
 * @returns A div NodeDefinition with style binding
 *
 * @example
 * // Standalone usage
 * const overlayNode = createBackgroundOverlayNode('_sectionStyles.background')
 */
export declare function createBackgroundOverlayNode(path: string, className?: string): NodeDefinition;
