declare namespace SpreadsheetAnalytics.Data {

    /** The core (root) structure for the exported JSON document. A single JSON file contain just one root object with this type. */
    export interface IData {
        /** Describes the data sources for the data. The data sources are then shown to the user in the details window.
            If no sources are given, the application will show that the JSON file itself is the original source. */
        source?: IDataSource;

        /** Contains the meta data information about each column. While it is not required to have this in every file, it is recommended
            to explicitly define the types of each column - this helps the application to display the data correctly without the need to
            infer the data types dynamically.

            The keys in the meta object must match the names of properties in each data row. */
        meta: Dictionary<IMetaData>;

        /** The main data array. It is mandatory in every file, even if the data array is empty. */
        data: Array<IDataRow>;

        /** The HTML code for the table header cells (the `<tr>` tags should not be included). If both this and `tableRowTemplate` is
            omitted, the table will be automatically generated to include all columns.

            Note that the application does not allow any inline scripts or styles to be included in the HTML code. */
        tableHeader?: string;

        /** The HTML code for each data row (the `<tr>` tags should not be included). If both this and `tableRowTemplate` is
            omitted, the table will be automatically generated to include all columns.

            The code should contain placeholders for columns in form `${FieldName}` (dollar sign, opening bracket, column name, closing bracket).
            The column name must match the keys in the meta object or data objects.

            Note that the application does not allow any inline scripts or styles to be included in the HTML code. */
        tableRowTemplate?: string;

        /** Optionally defines the initial view for the dashboard (for example, any active filters). */
        state?: IState;
    }

    /** Interface describing a single column in the source data. */
    export interface IMetaData {
        /** Specifies if the column contains dates. The date should either be specified using ISO 8601 format or using the 
            JavaScript timestamp (milliseconds since UNIX epoch) value. */
        date?: boolean;

        /** Specifies that the columns contain numeric values that should be used as values for the aggregations. */
        value?: boolean | IMetaDataValue;

        /** Specifies that the column should not be shown in the user interface. The only place where hidden columns are shown
        to the user is when the `Add data` dialog shows the columns by which the data can be merged. */
        hidden?: boolean;

        /** Specifies that the column contains coordinates. The coordinates can either be specified as strings using one of
            the formats given below or using numeric values with the `ITypedValue.coords` property.

            The coordinates must be given in the WGS 84 projection.

            Some supported coordinate string representations:

            - N 56 24.123 E 24 58.789
            - N 56.40205 E 12.979816
            - 56.40205 12.979816 */
        coordinates?: boolean;

        /** The name used to show the column in the user interface. If not specified, `column` should be used instead. */
        displayName?: string;

        /** The comment for the column. Currently not shown in the user interface. */
        comment?: string;

        /** Specifies that the column is somehow special and should never be used in any user interface directly. This is a
        more thourough version of `hidden`. It is only used internally by the application to give special meaning to columns
        based on the name of the column. */
        special?: boolean;

        /** Specifies that the column contains identifiers that are then used to display shapes on the map.

            The currently supported shapes and the identifier format:

            - "Countries" - identifier is the two letter ISO 3166-1 code
            - "LatviaAdm" - municipalities of Latvia; identifier is the name like 'Priekules novads' */
        shapes?: "Countries" | "LatviaAdm" | "USAstates";
    }

    export interface IMetaDataValue {
        /** The format for the values. The array must contain three elements - the number of decimal digits,
        the decimal separator character and the thousands separator character. */
        format?: [number, "." | ",", "" | " " | ","];
    }

    /** A dictionary (a dynamic object) where the key (property name) is a string. */
    export interface Dictionary<TValue> {
        [key: string]: TValue;
    }

    /** A structured format for specifying the data value. The main benefit from using this structure is the ability to specify
        both the parsed (numeric, date or coordinate) value and the raw string value that could contain some special formatting. */
    export interface ITypedValue {
        /** The numeric value. When using this, the `IMetaData.value` should be set to `true`. */
        number?: number;
        /** The JavaScript timestamp (milliseconds since UNIX epoch) of the date. */
        date?: number;
        /** The raw string representation. It could be used in the table view but will not be parsed automatically for dates or numbers. */
        raw: string;
        /** The parsed WGS 84 coordinates. The first value is latitude (N/S), the second is longitude (E/W). */
        coords?: [number, number];
    }

    /** Represents a single data object in the array. A data object is a dictionary (object containing named properties) where
        each value is either a raw string or number or an instance of `ITypedValue` that contains more specific value information. */
    export interface IDataRow extends Dictionary<string | number | ITypedValue> {
    }

    /** The state of a PieChart that can be specified in the data. */
    export interface ICategoryChartState {
        /** The offset (starting from which value the data is displayed). In the UI this is controlled by clicking `Others` and
            `Previous` slices. */
        offset?: number;

        /** The chart type used to display the category. The default is `"pieChart"`. */
        mode?: "pieChart" | "facetChart";

        /** Specifies if the chart is visible. This does not affect the visibility of the category field
        from the rest of the user interface. */
        hidden?: boolean;

        /** Specifies custom settings for the PieChart. */
        pieChartSettings?: ZoomCharts.Configuration.PieChartSettings;

        /** Specifies custom settings for the FacetChart. */
        facetChartSettings?: ZoomCharts.Configuration.FacetChartSettings;
    }

    /** The state of the TimeChart that can be specified in the data. */
    export interface ITimeChartState {
        /** The JavaScript timestamp specifying the left edge of the visible area. */
        from?: number;
        /** The JavaScript timestamp specifying the right edge of the visible area. */
        to?: number;
        /** The display unit of the chart. Example values: `m`, `s`, `h`, `2 h`, `10 m`, `auto`. To specify month, use uppercase `M`. */
        unit?: string;

        /** A list of columns that will be calculated for the chart. When this is used, the 
        default value field is ignored and the default count series is not added.

        To display the additional values, the series must be configured using the `settings` property.

        The maximum of value fields specified is 13. */
        values?: string[];

        /** Additional settings for the TimeChart. */
        settings?: ZoomCharts.Configuration.TimeChartSettings;

        /** The series type used when showing the stacked/grouped series. */
        groupedSeriesType?: "line" | "area" | "columns";
    }

    export interface IGeoRectangle {
        east: number;
        west: number;
        north: number;
        south: number;
    }

    export interface IGeoChartState {
        bounds: IGeoRectangle;
        zoom: number;

        /** The initial height of the GeoChart, in pixels. */
        height?: number;
    }

    export type IChartState = ICategoryChartState | ITimeChartState | IGeoChartState;

    export interface IFilterItem {
        inverted?: boolean;
        text?: string;
    }

    export interface IStateColors {
        /** The default colors that are used if the category does not match a more specific value. */
        main: string[];

        /** The default colors used in the TimeChart and FacetChart series when group-by is not used. */
        series: string[];

        /** The color used by the dashboard when a series or category like "Others" have to be visualized. */
        other: string;

        /** The font color used by the charts */
        text: string;

        /** The class name added to the `<body>` element that can overwrite how the elements are styled. The class name must be prefixed with `colors-`. */
        className?: string;

        /** The tile URL used as the basemap. */
        mapTileUrl?: string;

        /** Maps the category names to specific colors. The value is either the CSS color name (either constant
        name or the `rgb()` or `rgba()` notation) or an object that identifies the key as a regular expression and
        the color value. Note that if multiple regular expressions match a single category, it is not defined which
        one of the replacement values will be used.

        Note that default CSS color names are always automatically used as the category color but if the key is also
        specified in the mapping, this value will take precedence.

        The string keys are case insensitive. For regular expression the key is case sensitive but can be overridden
        by specifying `regExp: "i"`. */
        categories?: ZoomCharts.Dictionary<string | {
            /** Specifies that the key should be interpreted as a regular expression. The value can also be a string 
            containing the regular expression flags. */
            regExp: boolean | string;
            /** The replacement color. 

            For regular expressions the replacement color can use back references.*/
            color: string;
        }>
    }

    export interface IState {
        filters: Dictionary<IFilterItem>;

        /** Contains configuration specific to individual charts. */
        charts: Dictionary<IChartState>;

        /** Specifies the colors used by the dashboard. */
        colors?: IStateColors;

        /** Sets the default columns that will be used by the dashboard. If any of these are omitted (undefined), the application will 
            automatically pick the most appropriate. Use `null` to select the `None` option where applicable. */
        fields: {
            /** The initial value field. If `null`, count will be used instead. */
            value?: string;

            /** The initial data field. If `null`, the TimeChart will not be displayed. */
            date?: string;

            /** The initial group-by field. If `null`, the automatic grouping will be disabled. */
            group?: string;

            /** The initial coordinate or shape field. If `null`, the GeoChart will be disabled. */
            map?: string;
        };
    }

    export interface IDataSourceInfo {
        /** The type of the data source */
        type: DataSourceType;
        /** The name of the source, for example, the file name */
        name: string;
    }

    export interface IDataSourceMergeInfo {
        /** The columns in the left side that are used for the merge. */
        leftColumns: string[];
        /** The columns in the left side that are used for the merge. */
        rightColumns: string[];
        /** The prefix that is added to the columns of the right side. */
        rightPrefix: string;
        /** The suffix that is added to the columns of the right side. */
        rightSuffix: string;
        /** If a row in the left side must match for the row to be left in the output. */
        leftRequired: boolean;
        /** If a row in the right side must match for the row to be left in the output. */
        rightRequired: boolean;
    }

    export type DataSourceType = "excel" | "json" | "google-sheets" | "geocode" | "csv";

    export interface IDataSource extends IDataSourceInfo {
        merge: Array<IDataSourceInfo & IDataSourceMergeInfo>;
    }

}