/** Action property descriptions (from schema $defs/action). */
export declare const ACTION_PROP_DOCS: Readonly<Record<string, string>>;

/**
 * Generate a complete spec suggestion from data.
 *
 * Convenience wrapper: picks the top suggestion and returns a ready-to-use spec.
 *
 * @param data - The data to analyze.
 * @returns A complete spec, or `undefined` if no suggestion could be made.
 */
export declare function autoSpec(data: Record<string, unknown> | Record<string, unknown>[]): UWidgetSpec | undefined;

/**
 * Well-known data field descriptions.
 * Unlike schema-bound registries, these cover common keys used across widgets.
 * Not enforced by schema tests — new keys appear with type only until added here.
 */
export declare const DATA_FIELD_DOCS: Readonly<Record<string, string>>;

/** Data field descriptor for well-known widget data properties. */
export declare interface DataFieldInfo {
    readonly key: string;
    readonly type: string;
    readonly desc: string;
    readonly required?: boolean;
}

/** Field definition property descriptions (from schema $defs/fieldDefinition). */
export declare const FIELD_PROP_DOCS: Readonly<Record<string, string>>;

/** Supported input field types for form widgets. */
declare type FieldType = 'text' | 'email' | 'password' | 'tel' | 'url' | 'textarea' | 'number' | 'select' | 'multiselect' | 'date' | 'datetime' | 'time' | 'toggle' | 'range' | 'radio' | 'checkbox';

/** Get the event types emitted by a widget. Resolves `chart.*` → `chart`. */
export declare function getWidgetEvents(widget: string): readonly string[];

/**
 * Get the widget catalog.
 *
 * - No argument → list all widgets (`WidgetInfo[]`).
 * - Exact widget name → full detail (`WidgetDetail`).
 * - Category or prefix → filtered list (`WidgetInfo[]`).
 *
 * @example
 * ```ts
 * help()              // → all widget descriptions
 * help('chart')       // → all chart types (WidgetInfo[])
 * help('chart.bar')   // → full detail (WidgetDetail)
 * ```
 */
export declare function help(): WidgetInfo[];

export declare function help(widget: string): WidgetInfo[] | WidgetDetail;

/** Mapping key descriptions (from schema $defs/mapping.properties). */
export declare const MAPPING_DOCS: Readonly<Record<string, string>>;

/** A widget + mapping recommendation. */
export declare interface MappingSuggestion {
    /** Recommended widget type. */
    widget: string;
    /** Suggested mapping for the widget. */
    mapping?: UWidgetMapping;
    /** Confidence score (0–1). Higher means better fit. */
    confidence: number;
    /** Human-readable reason for this suggestion. */
    reason: string;
}

/**
 * Well-known options descriptions.
 * Covers widget-specific rendering options used across the catalog.
 */
export declare const OPTION_DOCS: Readonly<Record<string, string>>;

/**
 * Runtime spec scanner that extracts the full property surface from widget specs.
 *
 * `specSurface()` is the single function shared by both the MCP server and
 * the demo props panel — it scans an array of spec objects and returns every
 * key actually used, merged with descriptions from `widget-meta.ts`.
 *
 * Structural guarantee: if a spec uses a property, `specSurface()` reports it.
 */
/** A single discovered property with its inferred type and optional description. */
export declare interface PropInfo {
    key: string;
    /** Inferred runtime type: `"number"`, `"string"`, `"boolean"`, `"object[]"`, etc. */
    type: string;
    /** Description from the registry when available. */
    desc?: string;
}

/** The full property surface extracted from a set of specs. */
export declare interface SpecSurface {
    /** Top-level spec keys used (data, mapping, options, …). */
    specKeys: string[];
    /** `data.*` keys with inferred types. */
    dataFields: PropInfo[];
    /** `mapping.*` keys with schema descriptions. */
    mappingKeys: PropInfo[];
    /** `options.*` keys with inferred types. */
    optionKeys: PropInfo[];
    /** `fields[].*` keys with schema descriptions. */
    fieldProps: PropInfo[];
    /** Distinct `fields[].type` values used. */
    fieldTypes: string[];
    /** Distinct `actions[].style` values used. */
    actionStyles: string[];
    /** Events emitted by this widget category. */
    events: readonly string[];
}

/**
 * Scan an array of spec objects and collect their full property surface.
 *
 * @param specs  - Array of widget spec objects (e.g. variant values).
 * @param widget - Optional widget type string for event lookup.
 * @returns The collected {@link SpecSurface}.
 */
export declare function specSurface(specs: object[], widget?: string): SpecSurface;

/**
 * Suggest widget type and mapping from data alone.
 *
 * Analyzes data structure (keys, types, shape) and returns
 * ranked suggestions. If a widget type is provided, only suggests
 * a mapping for that specific widget.
 *
 * @param data - The data to analyze (object or array of records).
 * @param widget - Optional widget type to constrain the suggestion.
 * @returns Array of suggestions sorted by confidence (highest first).
 *
 * @example
 * ```ts
 * suggestMapping([{ name: 'A', value: 30 }, { name: 'B', value: 70 }])
 * // → [{ widget: 'chart.bar', mapping: { x: 'name', y: 'value' }, confidence: 0.9, ... }, ...]
 * ```
 */
export declare function suggestMapping(data: Record<string, unknown> | Record<string, unknown>[], widget?: string): MappingSuggestion[];

/**
 * Generate a minimal template spec for a widget type.
 *
 * Returns a complete, valid spec with sample data that can be
 * used as a starting point. Returns `undefined` for unknown types.
 *
 * @param widget - Widget type identifier (e.g., `"chart.bar"`, `"metric"`).
 * @returns A deep-copied template spec, or `undefined`.
 *
 * @example
 * ```ts
 * template('metric')
 * // → { widget: 'metric', data: { value: 1284, unit: 'users', ... } }
 * ```
 */
export declare function template(widget: string): UWidgetSpec | undefined;

/**
 * Action button definition.
 *
 * Reserved actions: `"submit"`, `"cancel"`, `"navigate"`.
 * Custom action strings are forwarded to the host via the `u-widget-event`.
 *
 * @example
 * ```json
 * { "label": "Submit", "action": "submit", "style": "primary" }
 * ```
 */
declare interface UWidgetAction {
    /** Button display text. */
    label: string;
    /** Action identifier emitted in the widget event. */
    action: string;
    /** Visual style hint. */
    style?: 'primary' | 'danger' | 'default';
    /** Whether the button is disabled. */
    disabled?: boolean;
    /** URL for `"navigate"` actions. */
    url?: string;
}

/**
 * Child widget spec inside a compose widget.
 * Inherits `type` and `version` from the parent — no need to repeat them.
 */
declare interface UWidgetChildSpec extends Omit<UWidgetSpec, 'type' | 'version'> {
    /** Grid column span within the parent compose layout. */
    span?: number;
    /** When true, the child is initially collapsed (uses native `<details>`). */
    collapsed?: boolean;
}

/**
 * Column definition for table widgets.
 *
 * @example
 * ```json
 * { "field": "price", "label": "Price", "format": "currency", "align": "right" }
 * ```
 */
declare interface UWidgetColumnDefinition {
    /** Data field name to display in this column. */
    field: string;
    /** Display header label. Defaults to the field name. */
    label?: string;
    /** Value formatting hint (e.g., `"currency"`, `"currency:EUR"`, `"percent"`). */
    format?: 'number' | 'currency' | 'percent' | 'date' | 'datetime' | 'bytes';
    /** Text alignment within the column. */
    align?: 'left' | 'center' | 'right';
}

/**
 * Field definition for form/confirm input widgets.
 *
 * @example
 * ```json
 * { "field": "email", "label": "Email", "type": "email", "required": true }
 * ```
 */
declare interface UWidgetFieldDefinition {
    /** Data field name (maps to `data[field]` for defaults and output). */
    field: string;
    /** Display label. Defaults to the field name. */
    label?: string;
    /** Input type. Defaults to `"text"`. */
    type?: FieldType;
    /** Whether the field must be filled before submit. */
    required?: boolean;
    /** Placeholder text shown when the field is empty. */
    placeholder?: string;
    /** Options for select, multiselect, radio, and checkbox types. */
    options?: string[];
    /** Minimum character length for text inputs. */
    minLength?: number;
    /** Maximum character length for text inputs. */
    maxLength?: number;
    /** Custom regex pattern for validation (e.g. `"^[A-Z]{3}$"`). */
    pattern?: string;
    /** Number of visible rows for textarea type. */
    rows?: number;
    /** Minimum value (number) or date string. */
    min?: number | string;
    /** Maximum value (number) or date string. */
    max?: number | string;
    /** Step increment for number and range inputs. */
    step?: number;
    /** Custom validation error message (overrides locale default). */
    message?: string;
}

/**
 * Mapping connects data fields to visual channels.
 *
 * Which keys are relevant depends on the widget type:
 * - **chart.bar/line/area:** `x`, `y`
 * - **chart.pie/funnel:** `label`, `value`
 * - **chart.scatter:** `x`, `y`, `color`, `size`
 * - **chart.radar:** `axis`, `value`
 * - **table:** `columns`
 * - **list:** `primary`, `secondary`, `avatar`, `icon`, `trailing`
 *
 * When omitted, mapping is auto-inferred from the data shape.
 */
declare interface UWidgetMapping {
    /** Category axis field (chart x-axis). */
    x?: string;
    /** Value axis field(s). A string for single series, string[] for multi-series. */
    y?: string | string[];
    /** Label field (pie/funnel charts). */
    label?: string;
    /** Value field (pie/funnel/heatmap). */
    value?: string;
    /** Color grouping field (scatter). */
    color?: string;
    /** Size encoding field (scatter bubble). */
    size?: string;
    /** Opacity encoding field (scatter). Maps data values to point opacity (0.1–1.0). */
    opacity?: string;
    /** Axis field (radar chart indicators). */
    axis?: string;
    /** Explicit column definitions for table widgets. */
    columns?: UWidgetColumnDefinition[];
    /** Primary text field (list widget). */
    primary?: string;
    /** Secondary/subtitle text field (list widget). */
    secondary?: string;
    /** Icon letter field (list widget fallback when no avatar). */
    icon?: string;
    /** Avatar image URL field (list widget). */
    avatar?: string;
    /** Trailing value field displayed on the right (list widget). */
    trailing?: string;
    /** Badge/tag field (list widget). */
    badge?: string;
}

/**
 * The u-widget spec envelope — a single, consistent structure for all widgets.
 *
 * Only `widget` is required. All other fields are optional or auto-inferred.
 *
 * @example
 * ```ts
 * const spec: UWidgetSpec = {
 *   widget: 'chart.bar',
 *   data: [{ name: 'A', value: 30 }, { name: 'B', value: 70 }],
 *   mapping: { x: 'name', y: 'value' },
 * };
 * ```
 */
declare interface UWidgetSpec {
    /** Widget type identifier (e.g., `"chart.bar"`, `"metric"`, `"form"`). */
    widget: string;
    /** Unique identifier for event correlation and compose children. */
    id?: string;
    /** Optional display title rendered above the widget. */
    title?: string;
    /** Optional description text rendered below the title. */
    description?: string;
    /** Inline data — an object (metric/gauge) or array of records (chart/table). */
    data?: Record<string, unknown> | Record<string, unknown>[];
    /** Maps data fields to visual channels. Auto-inferred when omitted. */
    mapping?: UWidgetMapping;
    /** Field definitions for form/confirm widgets. */
    fields?: UWidgetFieldDefinition[];
    /** Formdown shorthand syntax for form fields (mutually exclusive with `fields`). */
    formdown?: string;
    /**
     * Widget-specific rendering options.
     *
     * Chart widgets support an `echarts` sub-key for native ECharts option passthrough:
     * ```json
     * { "options": { "echarts": { "tooltip": { "trigger": "axis" } } } }
     * ```
     * All keys in `options.echarts` are deep-merged into the generated ECharts option.
     * @see https://echarts.apache.org/en/option.html
     */
    options?: Record<string, unknown>;
    /** Action buttons displayed below the widget. */
    actions?: UWidgetAction[];
    /** Interchange format type marker. Always `"u-widget"` if present. */
    type?: 'u-widget';
    /** Interchange format version string. */
    version?: string;
    /** Layout mode for compose widget: `"stack"` (default), `"row"`, or `"grid"`. */
    layout?: 'stack' | 'row' | 'grid';
    /** Number of grid columns for compose `"grid"` layout. Default: 2. */
    columns?: number;
    /** Child widget specs for compose widget. */
    children?: UWidgetChildSpec[];
    /** Grid column span for children inside a compose `"grid"` layout. */
    span?: number;
}

/**
 * Well-known data fields per widget type.
 * Charts/table/list use user-defined fields so they are omitted.
 */
export declare const WIDGET_DATA_FIELDS: Readonly<Record<string, readonly DataFieldInfo[]>>;

/** Events emitted per widget category. */
export declare const WIDGET_EVENTS: Readonly<Record<string, readonly string[]>>;

/** Auto-inference hints — tells LLM what can be omitted. */
export declare const WIDGET_INFERENCE: Readonly<Record<string, string>>;

/** Relevant option keys per widget type. Only lists keys from OPTION_DOCS. */
export declare const WIDGET_OPTIONS: Readonly<Record<string, readonly string[]>>;

/** Extended detail returned when `help()` is called with an exact widget name. */
export declare interface WidgetDetail extends WidgetInfo {
    /** One-line hint telling LLM what can be omitted via auto-inference. */
    autoInference: string;
    /** Well-known data fields (display/content widgets). Empty for user-defined data. */
    dataFields: DataFieldInfo[];
    /** Mapping key descriptions relevant to this widget. */
    mappingDocs: Record<string, string>;
    /** Option key descriptions relevant to this widget. */
    optionDocs: Record<string, string>;
    /** Field definition property docs (form/confirm only). */
    fieldDocs?: Record<string, string>;
    /** Action property docs (form/confirm only). */
    actionDocs?: Record<string, string>;
    /** Event types emitted by this widget. */
    events: readonly string[];
    /** Example specs (minimal template + feature-rich). */
    examples: {
        label: string;
        spec: UWidgetSpec;
    }[];
}

/** Describes a single widget type in the catalog. */
export declare interface WidgetInfo {
    /** Widget type identifier (e.g., `"chart.bar"`). */
    widget: string;
    /** Human-readable category. */
    category: 'chart' | 'display' | 'input' | 'content' | 'composition';
    /** Short description of the widget's purpose. */
    description: string;
    /** Which mapping keys are relevant for this widget. */
    mappingKeys: string[];
    /** Expected data shape. */
    dataShape: 'object' | 'array' | 'none';
}

export { }