import type { ModalFieldDefinition } from '../manifest/schema';
import type { EyebrowTreatment } from '@riverbankcms/theme-core/site-styles';
import type { Media } from '../../lib/media';
/**
 * Options for customizing a section styles field.
 */
type SectionStylesOptions = {
    /** Field ID (default: '_sectionStyles') */
    id?: string;
    /** Field label (default: 'Section styles') */
    label?: string;
    /** Whether to include background field (default: true) */
    includeBackground?: boolean;
    /** Whether to render in block header (default: true) */
    renderInHeader?: boolean;
};
/**
 * Options for customizing a container styles field.
 */
type BoxStylesUiOptions = {
    /** Whether to render in block header */
    renderInHeader?: boolean;
    /** Field intent for editor grouping */
    intent?: 'content' | 'display' | 'behavior' | 'style';
};
type ContainerStylesOptions = {
    /** Field ID (default: '_containerStyles') */
    id?: string;
    /** Field label (default: 'Container styles') */
    label?: string;
    /** Whether to include background field (default: true) */
    includeBackground?: boolean;
} & BoxStylesUiOptions;
/**
 * Options for customizing a card styles field.
 */
type CardStylesOptions = {
    /** Field ID (default: '_cardStyles') */
    id?: string;
    /** Field label (default: 'Card styles') */
    label?: string;
    /** Whether to include background field (default: true) */
    includeBackground?: boolean;
} & BoxStylesUiOptions;
/**
 * Content type for section styles field (_sectionStyles).
 * Use this in block content types to get proper typing for section styling.
 *
 * @example
 * ```typescript
 * import type { SectionStylesContent } from '../fields/boxStyles'
 *
 * export type MyBlockContent = {
 *   heading?: string | null
 *   _sectionStyles?: SectionStylesContent
 * }
 * ```
 */
export type SectionStylesContent = {
    background?: {
        type?: 'color' | 'gradient' | 'image';
        color?: string | null;
        /** CSS gradient string (e.g., "linear-gradient(...)") */
        gradient?: string | null;
        image?: Media | null;
        objectFit?: 'fill' | 'fit' | 'original' | 'custom' | null;
        scale?: string | null;
        position?: string | null;
        opacity?: number | null;
        motion?: 'static' | 'fixed-frame' | null;
        overlay?: {
            type?: 'none' | 'color' | 'gradient' | null;
            color?: string | null;
            /** CSS gradient string (e.g., "linear-gradient(...)") */
            gradient?: string | null;
            opacity?: number | null;
        } | null;
        textColor?: string | null;
        /** Optional color token for headings. Falls back to textColor if not set. */
        headingColor?: string | null;
    } | null;
    spacing?: string | null;
    minHeight?: 'none' | 'banner' | 'hero' | 'immersive' | null;
    eyebrowTreatment?: EyebrowTreatment | null;
} | null;
export type CardStylesContent = {
    background?: Record<string, unknown> | null;
    border?: {
        enabled?: boolean | null;
        width?: 'none' | '1' | '2' | '3' | null;
        colorToken?: string | null;
    } | null;
    spacing?: string | null;
    raised?: boolean | null;
    rounded?: string | null;
    treatment?: 'accent-quote' | null;
} | null;
export type ContainerStylesContent = {
    background?: Record<string, unknown> | null;
    spacing?: string | null;
    raised?: boolean | null;
    rounded?: string | null;
    fullWidth?: boolean | null;
} | null;
type FieldIdWithDefault<Options, Default extends string> = Options extends {
    id: infer Id extends string;
} ? Id : Default;
type BoxStylesField<Id extends string, Kind extends 'section' | 'container' | 'card'> = ModalFieldDefinition & {
    id: Id;
    readonly __boxStyleType?: Kind;
};
/**
 * Creates a modal field group for styling full-width sections.
 *
 * Section styles include:
 * - Background (color/gradient/image with advanced options)
 * - Inner spacing (vertical padding)
 *
 * Sections are full-width wrappers that span the entire viewport, so they don't
 * support rounded corners or elevation shadows (unlike containers and cards).
 *
 * Use with the `backgroundLayer()` helper to render backgrounds in the block layout.
 *
 * @param options - Customization options for the field
 * @param options.id - Field ID (default: '_sectionStyles')
 * @param options.label - Field label (default: 'Section styles')
 * @param options.includeBackground - Whether to include background field (default: true)
 * @returns A modal FieldDefinition that can be added to a block's fields array
 *
 * @example
 * // Basic usage in a block
 * const fields = [
 *   // ... other fields
 *   sectionStylesField({
 *     id: '_sectionStyles',
 *     label: 'Section styles',
 *   }),
 * ]
 *
 * @example
 * // In the layout, use backgroundLayer() to render
 * const layout = section(
 *   { background: 'background' },
 *   [
 *     ...backgroundLayer('_sectionStyles.background'),
 *     sectionContainer([])
 *   ]
 * )
 *
 * @see {@link containerStylesField} for constrained-width containers with elevation
 * @see {@link cardStylesField} for repeater items with elevation
 * @see {@link backgroundLayer} for rendering backgrounds in layouts
 */
export declare function sectionStylesField(): BoxStylesField<'_sectionStyles', 'section'>;
export declare function sectionStylesField<const Options extends SectionStylesOptions>(options: Options): BoxStylesField<FieldIdWithDefault<Options, '_sectionStyles'>, 'section'>;
/**
 * Creates a modal field group for styling constrained-width containers.
 *
 * Container styles include:
 * - Background (color/gradient/image with advanced options)
 * - Inner spacing (padding)
 * - Raised (elevation shadow for visual depth)
 * - Rounded corners (border radius)
 *
 * Containers have constrained width (max-w-*) and are centered within their parent.
 * Use for content areas that need visual separation or elevation from the page background.
 *
 * @param options - Customization options for the field
 * @param options.id - Field ID (default: '_containerStyles')
 * @param options.label - Field label (default: 'Container styles')
 * @param options.includeBackground - Whether to include background field (default: true)
 * @returns A modal FieldDefinition that can be added to a block's fields array
 *
 * @example
 * // Basic usage in a block
 * const fields = [
 *   // ... other fields
 *   containerStylesField({
 *     id: '_containerStyles',
 *     label: 'Container styles',
 *   }),
 * ]
 *
 * @see {@link sectionStylesField} for full-width sections
 * @see {@link cardStylesField} for repeater items with the same styling options
 * @see {@link backgroundLayer} for rendering backgrounds in layouts
 */
export declare function containerStylesField(): BoxStylesField<'_containerStyles', 'container'>;
export declare function containerStylesField<const Options extends ContainerStylesOptions>(options: Options): BoxStylesField<FieldIdWithDefault<Options, '_containerStyles'>, 'container'>;
/**
 * Creates a modal field group for styling individual cards in repeaters.
 *
 * Card styles include:
 * - Background (color/gradient/image with advanced options)
 * - Inner spacing (padding)
 * - Raised (elevation shadow for visual depth)
 * - Rounded corners (border radius)
 *
 * Cards are used in repeaters (e.g., columns, grids, carousels) and have the same
 * styling options as containers. Each card instance can be styled independently.
 *
 * **Important:** When used in fragments (not blocks), the field ID must start with
 * a letter (e.g., 'styles', 'cardStyles') - do NOT use a leading underscore like '_cardStyles'.
 *
 * @param options - Customization options for the field
 * @param options.id - Field ID (default: '_cardStyles' for blocks, 'styles' recommended for fragments)
 * @param options.label - Field label (default: 'Card styles')
 * @param options.includeBackground - Whether to include background field (default: true)
 * @returns A modal FieldDefinition that can be added to a block or fragment's fields array
 *
 * @example
 * // In a fragment (e.g., card.ts)
 * const cardFragment = defineFragment({
 *   id: 'card',
 *   fields: [
 *     { id: 'title', type: 'text', label: 'Title' },
 *     { id: 'body', type: 'richText', label: 'Body' },
 *     cardStylesField({
 *       id: 'styles',  // No leading underscore for fragments!
 *       label: 'Card styles',
 *     }),
 *   ],
 *   layout: stack({ gap: 'md' }, [
 *     text({ as: 'h3' }, bind('title')),
 *     richText({}, bind('body')),
 *   ]),
 * })
 *
 * @example
 * // In a block
 * const fields = [
 *   // ... other fields
 *   cardStylesField({
 *     id: '_cardStyles',  // Can use underscore in blocks
 *     label: 'Card styles',
 *   }),
 * ]
 *
 * @see {@link sectionStylesField} for full-width sections
 * @see {@link containerStylesField} for constrained-width containers
 * @see {@link backgroundLayer} for rendering backgrounds in layouts
 */
export declare function cardStylesField(): BoxStylesField<'_cardStyles', 'card'>;
export declare function cardStylesField<const Options extends CardStylesOptions>(options: Options): BoxStylesField<FieldIdWithDefault<Options, '_cardStyles'>, 'card'>;
export {};
