/**
 * state-matrix — Storybook helper for documenting every visual state a
 * component supports in a consistent, side-by-side grid.
 *
 * Why this exists:
 *   Most of our components have a single `Default` story. That makes
 *   visual regression coverage thin (you see one state, miss the others)
 *   and forces the docs reader to discover edge cases on their own.
 *   `stateMatrix` lets a single story declaration render N labelled
 *   variants in a labelled grid — perfect for both visual review in
 *   Storybook AND automated browser-mode snapshots via addon-vitest.
 *
 * Usage:
 *   import { stateMatrix } from '../../stories/state-matrix';
 *   import { Button } from './Button';
 *
 *   export const States = stateMatrix({
 *     component: Button,
 *     groups: [
 *       {
 *         label: 'Default',
 *         items: [
 *           { label: 'idle',     args: { children: 'Save' } },
 *           { label: 'hover',    args: { children: 'Save' }, dataState: 'hover' },
 *           { label: 'disabled', args: { children: 'Save', disabled: true } },
 *           { label: 'loading',  args: { children: 'Save', loading: true } },
 *         ],
 *       },
 *       {
 *         label: 'Variants',
 *         items: [
 *           { label: 'primary',   args: { children: 'Save', variant: 'primary' } },
 *           { label: 'secondary', args: { children: 'Save', variant: 'secondary' } },
 *           { label: 'ghost',     args: { children: 'Save', variant: 'ghost' } },
 *           { label: 'danger',    args: { children: 'Save', variant: 'danger' } },
 *         ],
 *       },
 *     ],
 *   });
 *
 *   The exported `States` is a real Storybook story (Component + args),
 *   so it shows up in Docs AND becomes a single browser-mode test that
 *   asserts every cell renders.
 */
import type { StoryObj } from "@storybook/react";
import type { ComponentType, ReactNode } from "react";
export interface StateMatrixItem<P> {
    /** Label rendered above the cell. */
    label: string;
    /** Props passed to the component for this cell. */
    args: P;
    /** Optional caption rendered below the label (e.g. "hover" / "focus-visible"). */
    caption?: ReactNode;
    /** Optional wrapper around the cell (for context like a dark card). */
    wrap?: (node: ReactNode) => ReactNode;
}
export interface StateMatrixGroup<P> {
    label: string;
    description?: ReactNode;
    items: StateMatrixItem<P>[];
    /** Override per-group columns. Default: auto-fit minmax 180px 1fr. */
    columns?: number | string;
}
export interface StateMatrixConfig<P> {
    component: ComponentType<P>;
    groups: StateMatrixGroup<P>[];
    /** Optional decorator applied to the whole matrix. */
    wrap?: (node: ReactNode) => ReactNode;
}
/**
 * Build a Storybook StoryObj that renders the configured state matrix.
 */
export declare function stateMatrix<P>(config: StateMatrixConfig<P>): StoryObj<ComponentType<P>>;
//# sourceMappingURL=state-matrix.d.ts.map