/**
 * SharePoint Framework support for dynamic data bindings.
 *
 * @remarks
 * This package provides the necessary infrastructure classes and public APIs necessary
 * to run dynamic data, and implement components that use it.
 *
 * @packagedocumentation
 */

import { ISPEventObserver } from '@microsoft/sp-core-library';
import { ServiceKey } from '@microsoft/sp-core-library';
import { ServiceScope } from '@microsoft/sp-core-library';
import { SPEvent } from '@microsoft/sp-core-library';
import { SPEventArgs } from '@microsoft/sp-core-library';

/* Excluded from this release type: _DynamicDataManager */

/**
 * Class that contains the Dynamic Data reference.
 * This includes the source, property, and property path (if applicable) of Dynamic Data
 *
 * @remarks
 * The reference string is of the form `<sourceId>:<property>` or `<sourceId>:<property>:<propertyPath>`
 *
 * Examples of references are:
 * `WebPart.<componentId>.<instanceId>:myComplexProperty:myArray[0].lastName`
 *
 * @public
 */
export declare class DynamicDataReference {
    private _reference;
    private _sourceId;
    private _property;
    private _propertyPath;
    constructor(reference: string);
    /**
     * Returns the full reference of the Dynamic Data object as a string.
     */
    get reference(): string;
    /**
     * Returns the referred id of the Dynamic Data Source.
     */
    get sourceId(): string;
    /**
     * Returns the referred property of the Dynamic Data.
     */
    get property(): string;
    /**
     * Returns the referred property path of the Dynamic Data.
     * Returns undefined if there is no property path.
     */
    get propertyPath(): string | undefined;
}

/* Excluded from this release type: _DynamicDataUtilities */

/* Excluded from this release type: _IContextPropertyInfo */

/**
 * Describes the value and the structure of a property value.
 * It contains sample value of the property and the metadata
 * describing the structure of that value.
 * @public
 */
export declare interface IDynamicDataAnnotatedPropertyValue {
    /**
     * Sample value of a property
     */
    sampleValue: any;
    /**
     * Metadata describing the sample value of the property.
     */
    metadata?: IDynamicDataPropertyValueMetadataCollection;
}

/**
 * Interface for components to implement in order to be dynamic data sources.
 * This can be implemented as an object with state, or a set of loose functions that
 * returns the data.
 *
 * @privateRemarks
 * Please note that, if you add any api here, if you want that to be surfaced to the
 * consumers then you have to add an equivalent api in the 'IDynamicDataSource'.
 *
 * @public
 */
export declare interface IDynamicDataCallables {
    /**
     * Returns all the property definitions that the DataSource will provide.
     */
    getPropertyDefinitions(): ReadonlyArray<IDynamicDataPropertyDefinition>;
    /**
     * Given a property id, returns the value of the property.
     *
     * @remarks
     * It is assumed that when this function returns an array, it is homogeneous.
     */
    getPropertyValue(propertyId: string): any;
    /**
     * Given a property id, returns its annotated value. If the source doesn't supply
     * the annotated value, then it falls back to whatever 'getPropertyValue' returns as
     * the sample value and metadata would be undefined.
     *
     * @param propertyId - One of the property ids exposed from the dynamic data source.
     */
    getAnnotatedPropertyValue?(propertyId: string): IDynamicDataAnnotatedPropertyValue | undefined;
    /**
     * Returns list of allowed events on the dynamic data source.
     *
     * When this function returns a non-empty result, then source must define 'sendEvent' api.
     *
     * If this api is not defined or returns an empty array, then no consumer will be able
     * to talk to this source.
     *
     * @beta
     */
    allowedEvents?(): ReadonlyArray<IDynamicDataEventDefinition>;
    /**
     * If defined, enables the consumer to send data to the associated
     * dynamic data source. Then source can act accordingly.
     *
     * Invoking this api throws an error when the passed in 'eventName' is not
     * one of the allowed events on the source.
     *
     * @param eventName - A case-sensitive string representing the name of the event.
     * @param data - Data to be sent to the dynamic data source.
     *
     * @beta
     */
    sendEvent?(eventName: string, data: any): void;
}

/**
 * Definition of an event which a dynamic data source accepts.
 *
 * It includes the name of the event and description to be seen and used by end users.
 *
 * @beta
 */
export declare interface IDynamicDataEventDefinition {
    /**
     * Event name
     */
    name: string;
    /**
     * User-friendly, localized description of the event.
     */
    description?: string;
}

/* Excluded from this release type: _IDynamicDataManager */

/**
 * Definition of a property. It includes the id of the property to be used with the APIs, along with
 * a user-friendly, localized title and description to be seen and used by end users.
 *
 * @public
 */
export declare interface IDynamicDataPropertyDefinition extends IDynamicDataPropertyMetadata {
    /**
     * Id of the property. This can only contains letters, numbers, dashes and underscores.
     * Example: "myFiles" or "time_in_24-hour_clock"
     */
    id: string;
}

/**
 * Metadata of a property
 * @public
 */
export declare interface IDynamicDataPropertyMetadata {
    /**
     * User-friendly, localized title of the property.
     * Example: "My files" / "Mis archivos" (depending of current language)
     */
    title: string;
    /**
     * User-friendly, localized description of the property.
     * Example: "Contains a list of ids with the files of the current user"
     */
    description?: string;
}

/**
 * Metadata describing the sample value of the property.
 * @public
 */
export declare interface IDynamicDataPropertyValueMetadata extends IDynamicDataPropertyMetadata {
    /**
     * Metadata describing the sample value of the property.
     */
    metadata?: IDynamicDataPropertyValueMetadataCollection;
}

/**
 * A collection of key value pairs, where
 * 'key' is one of the keys from the property value object and
 * 'value' is the metadata describing the 'key' and its value.
 *
 * @remarks
 * Important note:
 *
 *  1. Key in the metadata should match the key in the sample value object.
 *
 *  2. For arrays, metadataCollection would be same as describing the element
 *     of the array, only once. See below example for more details.
 *
 * For example:
 *
 * ```
 * case 1: With simple values
 *  Sample Property Id value - {
 *    firstName: 'Bob',
 *    lastName: 'Smith',
 *    age: 30
 *  }
 *
 *  MetadataCollection for the above object would be -
 *  metadataCollection: {
 *    'firstName': { title: 'First Name' },
 *    'lastName': { title: 'Last Name' },
 *    'age': { title: 'Age' }
 *  }
 *
 * Case 2: With complex values
 *  Sample Property Id value - {
 *    person: {
 *      firstName: 'Bob',
 *      lastName: 'Smith',
 *      age: 30
 *    },
 *    visitedLocations: [
 *      {
 *        city: 'Redmond',
 *        state: 'WA'
 *      },
 *      {
 *        city: 'New York City',
 *        state: 'NY'
 *      }
 *    ]
 *  }
 *
 *  MetadataCollection for the above object would be -
 *  metadataCollection: {
 *    'person': {
 *      title: 'Person',
 *      metadataCollection: {
 *        'firstName': { title: 'First Name' },
 *        'lastName': { title: 'Last Name' },
 *        'age': { title: 'Age' }
 *      }
 *    },
 *    'vistedLocations': {
 *      title: 'Visted Locations',
 *      metadataCollection: {
 *        'city': { title: 'City' },
 *        'state': { title: 'State' }
 *      }
 *    }
 *  }
 * ```
 *
 * @public
 */
export declare interface IDynamicDataPropertyValueMetadataCollection {
    /**
     * Key-Value pair where
     * 'key' is one of the keys from the property value object and
     * 'value' is the metadata describing the 'key' and its value.
     */
    [key: string]: IDynamicDataPropertyValueMetadata;
}

/**
 * Dynamic Data Sources provide Dynamic Data to consumers.
 * They offer metadata to identify the data sources and API to get the data.
 *
 * @privateRemarks
 * We are not extending the IDynamicDataCallables interface here because
 * it would give us a flexibility of changing those api's signature to suit
 * the consumer needs.
 *
 * @public
 */
export declare interface IDynamicDataSource {
    /**
     * Id of the Dynamic Data Source.
     */
    id: string;
    /**
     * Metadata of the Dynamic Data Source.
     */
    metadata: IDynamicDataSourceMetadata;
    /**
     * Returns all the property definitions for dynamic data.
     * This needs to be overridden by the implementation of the component.
     */
    getPropertyDefinitionsAsync(): Promise<ReadonlyArray<IDynamicDataPropertyDefinition>>;
    /**
     * Given a property id, returns the value of the property.
     * This needs to be overridden by the implementation of the component.
     *
     * @param propertyId - Property id for which the value is requested.
     */
    getPropertyValueAsync(propertyId: string): Promise<any>;
    /**
     * Given a property id, returns its annotated value.
     * If the source doesn't supply the annotated value, then it falls back to whatever
     * 'getPropertyValue' as the sample value and metadata would be undefined.
     *
     * @param propertyId - Property id for which the value is requested.
     */
    getAnnotatedPropertyValueAsync(propertyId: string): Promise<IDynamicDataAnnotatedPropertyValue>;
    /**
     * Returns list of allowed events on the dynamic data source.
     * When this api returns a non-empty result, then source must define 'sendData' api.
     *
     * If this api is not defined or returns an empty map, then no consumer will be able
     * to talk to this source.
     *
     * @beta
     */
    allowedEventsAsync?(): Promise<ReadonlyArray<IDynamicDataEventDefinition>>;
    /**
     * If defined, enables the consumer to send data to the associated
     * dynamic data source. Then source can act accordingly.
     *
     * Invoking this api throws an error when the passed in 'eventName' is not
     * one of the allowed events on the source.
     *
     * @param eventName - A case-sensitive string representing the name of the event.
     * @param data - Data to be sent to the dynamic data source.
     *
     * @beta
     */
    sendEvent?(eventName: string, data: any): void;
    /**
     * Returns all the property definitions for dynamic data.
     * This needs to be overridden by the implementation of the component.
     * @deprecated - This API is deprecated. Please use the asynchronous version `getPropertyDefinitionsAsync`
     */
    getPropertyDefinitions(): ReadonlyArray<IDynamicDataPropertyDefinition>;
    /**
     * Given a property id, returns the value of the property.
     * This needs to be overridden by the implementation of the component.
     *
     * @param propertyId - Property id for which the value is requested.
     * @deprecated - This API is deprecated. Please use the asynchronous version `getAsyncPropertyValue`
     */
    getPropertyValue(propertyId: string): any;
    /**
     * Given a property id, returns its annotated value.
     * If the source doesn't supply the annotated value, then it falls back to whatever
     * 'getPropertyValue' as the sample value and metadata would be undefined.
     *
     * @param propertyId - One of the property ids exposed from the dynamic data source.
     * @deprecated - This API is deprecated. Please use the asynchronous version `getAsyncAnnotatedPropertyValue`
     */
    getAnnotatedPropertyValue(propertyId: string): IDynamicDataAnnotatedPropertyValue;
}

/**
 * Metadata of the Dynamic Data Source. It allows consumers to easily distinguish Dynamic Data Sources.
 *
 * @public
 */
export declare interface IDynamicDataSourceMetadata {
    /**
     * User-friendly, localized title of the Dynamic Data Source.
     * This can be customized by the component it refers to. By default it's the alias of the component.
     */
    title: string;
    /**
     * User-friendly, localized description of the Dynamic Data Source.
     */
    description?: string;
    /**
     * Alias of the component that the Dynamic Data Source refers to.
     * It can be undefined when the sources doesn't come from a component, for example framework level data sources.
     */
    alias?: string;
    /**
     * Id of the component that the Dynamic Data Source refers to.
     * It can be undefined when the sources doesn't come from a component, for example framework level data sources.
     */
    componentId?: string;
    /**
     * Id of the instance of the component that the Dynamic Data Source refers to.
     * This allows to distinguish, for example, between two web parts with the same type.
     * It can be undefined when the sources doesn't come from a component, for example framework level data sources.
     */
    instanceId?: string;
}

/* Excluded from this release type: _PageContextDataSource */

export { }