/**
 * @file AspectRatio.tsx
 * @input Uses React, stylex
 * @output Exports AspectRatio component, AspectRatioProps, AspectRatioShape, AspectRatioFit
 * @position AspectRatio component; maintains a specific aspect ratio for its children
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/AspectRatio/AspectRatio.doc.mjs
 * - /packages/core/src/AspectRatio/AspectRatio.test.tsx
 * - /packages/core/src/reset.css (AspectRatio fit baseline rules)
 * - /apps/storybook/stories/AspectRatio.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/AspectRatio/ (showcase blocks)
 */
import type { ReactNode } from 'react';
import type { BaseProps } from '../BaseProps';
/**
 * The shape of the aspect ratio container.
 * - `rectangle`: standard rectangular container (default).
 * - `ellipse`: clips the container to an ellipse. Combined with the `ratio`,
 *   this renders a circle at `ratio={1}` and an oval at non-square ratios.
 */
export type AspectRatioShape = 'rectangle' | 'ellipse';
/**
 * How the child is sized and positioned inside the ratio box.
 * - `cover`: the child fills the box; media is cropped to preserve its own
 *   aspect ratio (`object-fit: cover`).
 * - `contain`: the child fills the box; media is letterboxed to stay fully
 *   visible (`object-fit: contain`).
 * - `center`: the child keeps its natural size and sits centered in the box.
 */
export type AspectRatioFit = 'cover' | 'contain' | 'center';
export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
    /** Ref forwarded to the root element */
    ref?: React.Ref<HTMLDivElement>;
    /**
     * The aspect ratio as width/height (e.g., 16/9 = 1.777..., 4/3 = 1.333..., 1 for square).
     */
    ratio: number;
    /**
     * The shape of the container. Both shapes respect the provided `ratio`.
     * - `rectangle` (default): a standard rectangular container.
     * - `ellipse`: clips the container to an ellipse — a circle when `ratio={1}`,
     *   or an oval at other ratios. Pair with `fit="cover"` so the media fills
     *   the clipped container.
     *
     * @default 'rectangle'
     *
     * @example
     * ```
     * <AspectRatio ratio={1} shape="ellipse" fit="cover">
     *   <img src="avatar.jpg" alt="" />
     * </AspectRatio>
     * ```
     */
    shape?: AspectRatioShape;
    /**
     * How the child is laid out inside the ratio box, so the child does not
     * have to declare `width`/`height`/`objectFit` itself.
     * - `cover`: child fills the box; media is cropped (`object-fit: cover`).
     * - `contain`: child fills the box; media is letterboxed
     *   (`object-fit: contain`).
     * - `center`: child keeps its natural size, centered in the box.
     *
     * `cover`/`contain` child sizing ships as zero-specificity baseline rules
     * in `reset.css`, keyed on the `data-astryx-aspect-ratio-override`
     * attribute the component sets on the child's direct parent. Any styles
     * the child sets itself still win, so children that already size
     * themselves keep their behavior. When omitted, the child is left
     * unstyled (the pre-existing contract). `fit` is structural, not visual,
     * so it is not exposed on the theming surface.
     *
     * @example
     * ```
     * <AspectRatio ratio={16 / 9} fit="cover">
     *   <img src="image.jpg" alt="Widescreen image" />
     * </AspectRatio>
     * ```
     */
    fit?: AspectRatioFit;
    /**
     * Content to render inside the aspect ratio container.
     * The child element will be positioned absolutely to fill the container.
     *
     * Pass a single child. With `fit` set, every direct child is stretched to
     * fill the box, so a second child is laid out below the first and clipped
     * out of view; compose an overlay or caption inside one wrapper child.
     */
    children: ReactNode;
}
/**
 * AspectRatio component for maintaining a specific aspect ratio for its children.
 *
 * Uses the CSS aspect-ratio property to maintain the ratio. The child element
 * is positioned absolutely to fill the container, which is useful for images,
 * videos, embeds, and placeholders.
 *
 * Use `fit` to let the component size the child: `cover`/`contain` stretch
 * the child to fill the box (cropping or letterboxing media), `center` keeps
 * the child at its natural size. Without `fit`, the child styles itself.
 *
 * Use `shape="ellipse"` to clip the container into an ellipse — a circle at
 * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
 * `ratio`.
 *
 * Sizing: the box takes its width from its container and derives its height
 * from the ratio, so it needs an ancestor with a definite width. Two
 * consequences are worth knowing. Constraining only the height (`height` or
 * `maxHeight`) clamps the box without releasing the width, so the rendered
 * ratio no longer matches `ratio`; pass `width: 'auto'` alongside to size from
 * the height instead. And in a shrink-to-fit parent (`inline-flex`,
 * `width: fit-content`, a floated box) it contributes no intrinsic width and
 * collapses to zero.
 *
 * @example
 * ```
 * <AspectRatio ratio={16 / 9} fit="cover">
 *   <img src="image.jpg" alt="Widescreen image" />
 * </AspectRatio>
 * ```
 *
 * @example
 * ```
 * <AspectRatio ratio={1} shape="ellipse" fit="cover">
 *   <img src="avatar.jpg" alt="" />
 * </AspectRatio>
 * ```
 */
export declare function AspectRatio({ ratio, shape, fit, children, xstyle, className, style, ref, ...props }: AspectRatioProps): import("react").JSX.Element;
export declare namespace AspectRatio {
    var displayName: string;
}
//# sourceMappingURL=AspectRatio.d.ts.map