import type { BasicToggleGroupListProps, CommonProps, Icon, Size } from "@trackunit/react-components";
import type { ComponentProps, ReactNode } from "react";
/** Extract IconName from Icon component props */
export type IconName = ComponentProps<typeof Icon>["name"];
/** Where the control appears in the UI hierarchy */
export type Placement = "standalone" | "menu";
/** Raw environment signal -- how much space the container has */
export type AvailableSpace = "constrained" | "comfortable";
/** Computed sizing decision -- set by the sizing middleware from placement + availableSpace */
export type Compactness = "compact" | "spacious";
/** The full rendering context that drives all layout decisions */
export type RenderContext = Readonly<{
    placement: Placement;
    availableSpace: AvailableSpace;
}>;
/** Shared resolved fields set by cross-cutting middleware (before type-specific resolution) */
export type ResolvedControlPropsBase = Readonly<{
    /** Physical size of the control -- aligns with component library Size type */
    size: Size;
    /** Whether the control should be rendered at all */
    visible: boolean;
    /** Spacing between sub-elements (e.g. stepper buttons) */
    gap: string;
    /** Sizing decision: "compact" when in a menu or constrained container, "spacious" otherwise */
    compactness: Compactness;
    /** Resolved icon (state-dependent for toggles, static for buttons) */
    icon?: IconName;
}>;
/** All control type discriminants (derived from config unions + separator) */
type ControlType = ControlConfig["type"] | SeparatorItemConfig["type"];
/**
 * Discriminated union of resolved control props.
 *
 * Discriminant: `controlType` -- mirrors the config's `type` field.
 * Flat mapped type: every control type resolves to `ResolvedControlPropsBase`
 * plus a `controlType` discriminant.
 */
export type ResolvedControlProps = {
    [K in ControlType]: ResolvedControlPropsBase & Readonly<{
        controlType: K;
    }>;
}[ControlType];
/**
 * What happens to a control when responsive collapsing moves it into a menu.
 *
 * - `"menu"` (default) -- the control is placed inside the overflow menu
 * - `"hide"` -- the control is fully removed instead of being menued
 *
 * Use `"hide"` for controls that only make sense as standalone map overlays
 * and would be confusing or useless inside a menu (e.g. a visual indicator
 * that has no interactive menu representation).
 */
export type OverflowBehavior = "menu" | "hide";
/** Base fields shared by all controls */
type BaseControlConfig<TType extends string> = Readonly<CommonProps & {
    type: TType;
    id: string;
    /**
     * What happens when responsive collapsing would move this control into a menu.
     *
     * - `"menu"` (default) -- placed inside the overflow menu alongside other controls
     * - `"hide"` -- fully hidden instead of being menued
     *
     * @default "menu"
     */
    overflowBehavior?: OverflowBehavior;
}>;
/** Simple icon button - click action */
export type ButtonControlConfig = BaseControlConfig<"button"> & Readonly<{
    icon: IconName;
    label: string;
    onClick: () => void;
    /** Section name for grouping in menus (consecutive items with same section get a header) */
    section?: string;
}>;
/** Two connected buttons for increment/decrement (zoom) */
export type StepperControlConfig = BaseControlConfig<"stepper"> & Readonly<{
    /** Display label for the whole stepper control (e.g. "Zoom") */
    label: string;
    increment: () => void;
    decrement: () => void;
    /** Section name for grouping in menus (consecutive items with same section get a header) */
    section?: string;
}>;
/** Shared fields for boolean (on/off) controls: toggle and checkbox */
type BooleanControlFields = Readonly<{
    label: string;
    value: boolean;
    onChange: (value: boolean) => void;
    /**
     * State-dependent icons shown when the control is on or off (standalone only).
     * Both must be provided together — this prevents partial-icon bugs where
     * only one state has a visible icon.
     *
     * - **Standalone**: the state-appropriate icon is shown on the button; omitted falls back to Check/XMark
     * - **Menu**: icon is never shown (not exposed; would look cluttered)
     */
    icon?: Readonly<{
        on: IconName;
        off: IconName;
    }>;
    /** Section name for grouping in menus (consecutive items with same section get a header) */
    section?: string;
}>;
/** Toggle switch - boolean value (renders ToggleSwitch in menus) */
export type ToggleControlConfig = BaseControlConfig<"toggle"> & BooleanControlFields;
/** Checkbox - boolean value (renders Checkbox in menus) */
export type CheckboxControlConfig = BaseControlConfig<"checkbox"> & BooleanControlFields;
/** Union of all boolean (on/off) control configs */
export type BooleanControlConfig = ToggleControlConfig | CheckboxControlConfig;
/** Select dropdown - string options */
export type SelectControlConfig<TValue extends string = string> = BaseControlConfig<"select"> & Readonly<{
    label: string;
    value: TValue;
    options: ReadonlyArray<Readonly<{
        value: TValue;
        label: string;
    }>>;
    onChange: (value: TValue) => void;
    /** Section name for grouping in menus (consecutive items with same section get a header) */
    section?: string;
}>;
/** Radio group - mutually exclusive string options (RadioGroup + RadioItem in the design system) */
export type RadioGroupControlConfig<TValue extends string = string> = BaseControlConfig<"radioGroup"> & Readonly<{
    label: string;
    value: TValue;
    options: ReadonlyArray<Readonly<{
        value: TValue;
        label: string;
    }>>;
    onChange: (value: TValue) => void;
    /** Icon on the standalone trigger button (menu uses labeled RadioGroup only) */
    icon: IconName;
    /** Section name for grouping in menus (consecutive items with same section get a header) */
    section?: string;
}>;
/**
 * One segment in a toggle group — matches {@link BasicToggleGroupListProps} for the design-system `ToggleGroup` `list` prop.
 */
export type ToggleGroupOption<TValue extends string = string> = Readonly<BasicToggleGroupListProps<TValue>>;
/**
 * Segmented toggle group — mutually exclusive options (design-system `ToggleGroup`).
 * Standalone uses icon-only styling per map controls patterns (every option must define `iconName`);
 * menu supports text-only segments and icons.
 */
export type ToggleGroupControlConfig<TValue extends string = string> = BaseControlConfig<"toggleGroup"> & Readonly<{
    /** Accessible name for the control (group label). */
    label: string;
    value: TValue;
    options: ReadonlyArray<ToggleGroupOption<TValue>>;
    onChange: (value: TValue) => void;
    disabled?: boolean;
    /** Section name for grouping in menus (consecutive items with same section get a header) */
    section?: string;
}>;
/** Search control - string value with search/filter UI */
export type SearchControlConfig = BaseControlConfig<"search"> & Readonly<{
    label: string;
    value: string;
    placeholder?: string;
    onChange: (value: string) => void;
    onClear?: () => void;
    /** Section name for grouping in menus (consecutive items with same section get a header) */
    section?: string;
}>;
/** Separator between items in a menu */
export type SeparatorItemConfig = Readonly<{
    type: "separator";
}>;
/** Items that can appear inside a menu (excludes menu itself -- menus cannot nest) */
export type MenuItemConfig = Readonly<ToggleControlConfig | CheckboxControlConfig | ButtonControlConfig | SelectControlConfig | RadioGroupControlConfig | ToggleGroupControlConfig | SearchControlConfig | StepperControlConfig | SeparatorItemConfig | CustomControlConfig>;
/** Menu control - groups other controls in a popover */
export type MenuControlConfig = BaseControlConfig<"menu"> & Readonly<{
    /** Icon shown on the menu trigger button */
    icon: IconName;
    /** Tooltip/label for the menu trigger button */
    label: string;
    /** Items in the menu */
    items: ReadonlyArray<MenuItemConfig>;
}>;
/**
 * Context passed to custom control render functions.
 *
 * Contains all environment information needed to adapt rendering.
 * Built-in control types handle these concerns automatically through
 * the middleware pipeline. With custom controls, **you** are responsible
 * for adapting to placement and compactness.
 *
 * @see {@link CustomControlConfig} for full usage guidance.
 */
export type CustomControlRenderContext = Readonly<{
    /**
     * Resolved rendering props from the middleware pipeline.
     * Contains pre-computed decisions (size, gap, compactness, visible)
     * that you should respect for visual consistency with built-in controls.
     */
    resolved: ResolvedControlProps;
    /** Current placement -- "standalone" (floating on the map) or "menu" (inside a popover) */
    placement: Placement;
}>;
/**
 * Custom React component control -- **escape hatch** for cases not covered
 * by the built-in control types (button, toggle, stepper, select, radioGroup, toggleGroup, search, menu).
 *
 * Custom controls can appear both **standalone** (floating on the map) and
 * **inside menus** (as a menu item). At narrow screen widths the system may
 * collapse any control into a menu, so your render function **must** handle
 * both placements.
 *
 * ---
 *
 * **PREFER BUILT-IN TYPES.** Custom controls bypass the type-safe rendering
 * pipeline and require you to manually handle:
 *
 * - **Compactness** -- use `resolved.compactness` to adapt sizing/spacing
 * - **Placement** -- standalone (icon button + tooltip) vs menu (labeled item).
 *   When `placement === "menu"`, render a menu-compatible layout: use `px-3 py-2`
 *   padding, `role="menuitem"`, and ensure the control is keyboard-navigable.
 * - **Tooltips** -- show tooltip when `placement === "standalone"`
 * - **Sizing** -- use `resolved.size` for consistency with other controls
 * - **Accessibility** -- keyboard navigation, ARIA attributes, focus management
 * - **Pointer events** -- in standalone mode your content is inside a
 *   `pointer-events-none` overlay (the container re-enables `pointer-events-auto`)
 *
 * If a built-in type can achieve what you need, use it instead. This escape
 * hatch exists for genuinely novel UI that no config-driven type can express.
 *
 * @example
 * ```ts
 * const customControl: CustomControlConfig = {
 *   type: "custom",
 *   id: "battery-indicator",
 *   label: "Battery Level",
 *   render: ({ placement, resolved }) => {
 *     // Menu placement -- render as a labeled row matching other menu items
 *     if (placement === "menu") {
 *       return (
 *         <div className="px-3 py-2" role="menuitem">
 *           <BatteryGauge level={72} size="small" showLabel />
 *         </div>
 *       );
 *     }
 *     // Standalone placement -- compact icon-style widget
 *     return (
 *       <BatteryGauge
 *         size={resolved.size}
 *         compact={resolved.compactness === "compact"}
 *       />
 *     );
 *   },
 * };
 * ```
 */
export type CustomControlConfig = BaseControlConfig<"custom"> & Readonly<{
    /**
     * Required label for accessibility -- used as tooltip text in standalone
     * placement (when {@link autoTooltip} is `"standalone"`). Even custom
     * controls need an accessible name.
     */
    label: string;
    /**
     * Controls automatic tooltip wrapping in standalone placement.
     * - `"standalone"` (default): wraps output in `Tooltip` using `label`.
     * - `"none"`: suppresses auto-tooltip — use when the rendered content manages its own label.
     */
    autoTooltip?: "standalone" | "none";
    /** Section name for grouping in menus (consecutive items with same section get a header) */
    section?: string;
    /**
     * Render function that produces the custom control's UI.
     *
     * Receives the full rendering context so the control can adapt to the
     * environment. You **must** handle compactness and placement changes --
     * the pipeline provides the information but cannot enforce its use.
     *
     * The returned ReactNode is rendered inside the controls overlay.
     * It will already have `pointer-events-auto` applied on its container.
     */
    render: (context: CustomControlRenderContext) => ReactNode;
    /**
     * Optional custom resolver that runs after the standard middleware pipeline
     * but before your render function receives the resolved props.
     *
     * Use this to transform or extend the resolved props based on the environment.
     * For example, override size decisions or add custom visibility logic.
     *
     * **Caveat —** returning `visible: false` hides the control at render time only.
     * Responsive flattening, its separators and its section headers are computed
     * beforehand and do not account for it, so a control hidden this way inside an
     * overflow menu can leave an orphaned divider or section header behind.
     *
     * @example
     * ```ts
     * resolve: (resolved, renderContext) => ({
     *   ...resolved,
     *   // Hide in constrained containers -- too detailed for small spaces
     *   visible: renderContext.availableSpace !== "constrained",
     * })
     * ```
     */
    resolve?: (resolved: ResolvedControlPropsBase, renderContext: RenderContext) => ResolvedControlPropsBase;
}>;
/**
 * Discriminated union of all control types (top-level).
 *
 * Prefer the built-in types (button, stepper, toggle, checkbox, select, radioGroup, toggleGroup, search, menu)
 * which participate fully in the rendering pipeline. Use "custom" only as an
 * escape hatch for genuinely novel UI.
 */
export type ControlConfig = Readonly<ButtonControlConfig | StepperControlConfig | ToggleControlConfig | CheckboxControlConfig | SelectControlConfig | RadioGroupControlConfig | ToggleGroupControlConfig | SearchControlConfig | MenuControlConfig | CustomControlConfig>;
/** Navigation area - array of controls */
export type NavigationConfig = Readonly<{
    controls: ReadonlyArray<ControlConfig>;
}>;
/** Settings area - array of controls */
export type SettingsConfig = Readonly<{
    controls: ReadonlyArray<ControlConfig>;
}>;
/** Statistics area - array of controls */
export type StatisticsConfig = Readonly<{
    controls: ReadonlyArray<ControlConfig>;
}>;
/** Tools area - array of controls (top-right on the map) */
export type ToolsConfig = Readonly<{
    controls: ReadonlyArray<ControlConfig>;
}>;
/** Complete controls configuration */
export type ControlsConfig = Readonly<{
    /** Navigation controls: zoom, fullscreen, compass (future), reset view (future) */
    navigation: NavigationConfig;
    /** Settings: layer toggles, layer settings (future), map style (future) */
    settings: SettingsConfig;
    /** Tools: top-right controls (e.g. find address, drawing, measurement) */
    tools: ToolsConfig;
    /** Statistics: data summaries, counts */
    statistics: StatisticsConfig;
}>;
/**
 * Built-in navigation controls returned by `useDefaultControls`.
 *
 * Consumers composing custom control stacks can use these named handles instead
 * of re-identifying built-ins by their string ids after the controls are built.
 */
export interface BuiltInNavigationConfig extends NavigationConfig {
    readonly zoom: StepperControlConfig | undefined;
    readonly fullscreen: ToggleControlConfig | undefined;
    readonly myLocation: ButtonControlConfig | undefined;
}
/** Built-in settings controls returned by `useDefaultControls`. */
export interface BuiltInSettingsConfig extends SettingsConfig {
    readonly mapStyle: MenuControlConfig | undefined;
}
/** Controls config with named handles for the controls built by `useDefaultControls`. */
export interface BuiltInControlsConfig extends ControlsConfig {
    readonly navigation: BuiltInNavigationConfig;
    readonly settings: BuiltInSettingsConfig;
}
/**
 * How aggressively controls are collapsed based on available space.
 *
 * - `"full"` -- all standalone controls shown as-is (wide containers)
 * - `"categorized"` -- controls within each category grouped into a per-category
 *   menu when >1 control exists in that category (medium containers)
 * - `"collapsed"` -- all controls collapsed into a single menu button, with each
 *   category's block separated from the next (narrow containers). Items keep whatever
 *   `section` they declare; the category name is only used as a fallback header for a
 *   block whose leading items declare none.
 */
export type ResponsiveMode = "full" | "categorized" | "collapsed";
/** The four semantic control areas used for categorization and section headers */
export type CategoryKey = "navigation" | "settings" | "tools" | "statistics";
/**
 * Per-area prepend/append modifiers for `useControls`.
 *
 * Each area key accepts an optional `prepend` and/or `append` array of
 * `ControlConfig | undefined` items (undefined entries are filtered out by
 * `defineControlStack`). Omitted areas are left untouched.
 */
export type UseControlsAreas = Partial<Record<CategoryKey, Readonly<{
    prepend?: ReadonlyArray<ControlConfig | undefined>;
    append?: ReadonlyArray<ControlConfig | undefined>;
}>>>;
export {};