import * as react from 'react';
import { HTMLAttributes, ReactNode } from 'react';

interface GridProps extends HTMLAttributes<HTMLDivElement> {
    children?: ReactNode;
    /**
     * The most columns this grid may use. Default `3`.
     *
     * A CEILING, not a fixed count: with `responsive` on (the default) the grid
     * uses fewer as it narrows and never more than this. Published as
     * `--fancy-grid-cols`, which the track template reads — so overriding that
     * property in CSS genuinely changes the layout.
     */
    cols?: number;
    /** Gutter. Default `md`. */
    gap?: "sm" | "md" | "lg";
    /**
     * Collapse toward one column on small screens. Default `true`.
     *
     * Off for grids that are genuinely fixed — a 2-up of icons, say — where
     * collapsing looks broken rather than responsive.
     */
    responsive?: boolean;
}

/**
 * The modular grid.
 *
 * Column count goes through a custom property rather than a `grid-cols-N` class
 * because N is a prop: Tailwind cannot generate a class it never sees in source,
 * and every hand-rolled copy in the gallery worked around that differently. The
 * property also gives a design a single place to override the breakpoint
 * behaviour in CSS without fighting a utility.
 *
 * ## `cols` is a CEILING, not a fixed count
 *
 * The responsive template reads `--fancy-grid-cols`, so `cols` means "this many
 * at most, fewer when narrow". Until 5.23.0 it meant nothing at all while
 * `responsive` was on: the template was a fixed `repeat(auto-fit, minmax(min(
 * 100%, 16rem), 1fr))`, so a grid asked for 2 and a grid asked for 5 rendered
 * the same track list, and the only way to get a real column count was
 * `responsive={false}` — which then had no breakpoints at all. The property this
 * doc comment has always advertised was set and never read.
 *
 * The gutter is in the arithmetic because it has to be: N tracks each `100%/N`
 * wide plus N-1 gaps overflow the row, and `auto-fit` responds by fitting N-1.
 * An off-by-one that looks like a design decision.
 *
 * Which is why the grid sets its own `gap` from `--fancy-grid-gap` instead of a
 * Tailwind `gap-*` class: the cap must divide by the gutter actually in effect,
 * and a class is a value this component does not control. Override the property
 * to change the gutter — that moves the spacing and the arithmetic together.
 */
declare const Grid: react.ForwardRefExoticComponent<GridProps & react.RefAttributes<HTMLDivElement>>;

export { Grid, type GridProps };