import { ComponentDescriptor } from './component-descriptor';
import { ConfigDescription } from './config-description';
import { Icon } from './icon';
import { LimeWebComponentPlatform } from './platform';
/**
 * Extensible metadata for registered resources in the Lime CRM platform.
 *
 * This metadata structure is used to describe various resources like web components,
 * commands, actions, and other extensible elements. It provides a consistent way to
 * attach human-readable information, icons, tags, and configuration components to
 * any registered resource.
 *
 * Resources that use this metadata include:
 * - Web components (via WebComponentRegistry)
 * - Commands (via CommandBus and `@Command` decorator)
 *
 * @example Register a web component with metadata
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const registry = platform.get(PlatformServiceName.WebComponentRegistry);
 *
 * registry.register('customer-insights', {
 *     title: 'Customer Insights',
 *     description: 'Advanced analytics dashboard for customer behavior',
 *     icon: 'chart-line',
 *     tags: ['card-widget', 'start-page'],
 *     configComponent: {
 *         name: 'customer-insights-config',
 *         props: { defaultView: 'monthly' },
 *     },
 * });
 * ```
 *
 * @example Register a command with metadata
 * ```ts
 * import {
 *     Command,
 *     CommandHandler,
 *     PlatformServiceName,
 * } from '@limetech/lime-web-components';
 *
 * @Command({ id: 'export-to-excel' })
 * class ExportToExcelCommand {
 *     ids: number[];
 * }
 *
 * const handler: CommandHandler = {
 *     handle: (command: ExportToExcelCommand) => {
 *         const http = platform.get(PlatformServiceName.Http);
 *
 *         return http.post('exports/excel', { ids: command.ids });
 *     },
 * };
 *
 * const commandBus = platform.get(PlatformServiceName.CommandBus);
 *
 * commandBus.register(ExportToExcelCommand, handler, {
 *     title: 'Export to Excel',
 *     description: 'Export selected records to Microsoft Excel',
 *     icon: { name: 'file-excel', color: 'green' },
 *     tags: ['bulk-object'],
 * });
 * ```
 *
 * @see {@link WebComponentRegistry.register | WebComponentRegistry.register}
 * @see {@link CommandBus | CommandBus}
 *
 * @group Core
 * @public
 */
export type ConfigMetadata = {
    /**
     * Human-readable display name for the resource.
     *
     * This should be a concise, user-friendly name that appears in UI elements
     * like menus, toolbars, and configuration screens.
     */
    title?: string;
    /**
     * Detailed description of what the resource does.
     *
     * Provide helpful context about the resource's purpose, functionality,
     * and any important usage notes. This typically appears in tooltips or
     * help documentation.
     */
    description?: string;
    /**
     * Icon to visually represent the resource.
     *
     * Can be either a string referencing an icon name from the icon library,
     * or an Icon object with additional properties like color and style.
     */
    icon?: string | Icon;
    /**
     * Semantic tags for categorization and context-aware filtering.
     *
     * Tags help the platform determine where a component can be placed and when
     * it is relevant for a given context. These tags typically describe the slot
     * types or contexts that the component is suited for.
     *
     * The available tags are platform-specific and depend on the extensibility
     * points provided by the host application.
     */
    tags?: string[];
    /**
     * Optional configuration UI component for this resource.
     *
     * Specifies a web component that provides a configuration interface for
     * customizing the resource's behavior. This is typically used in admin
     * interfaces or setup wizards.
     *
     * @see {@link ComponentDescriptor}
     */
    configComponent?: ComponentDescriptor;
    /**
     * Describe one configured instance of this resource.
     *
     * It tells instances of the same resource apart, for example by the
     * limetype and the filter they show.
     *
     * The platform registers it as a {@link ConfigDescriber}. A web
     * component is described under its tag and gets its props. A command is
     * described under its id and gets the `params` of its config. A rule
     * primitive is described under its id and gets its args, or `null` when
     * the leaf has no args.
     *
     * @param config - The config of one instance, for example the props of a
     * web component.
     * @returns A description of the instance, or `undefined` if there is
     * nothing to add.
     *
     * @example Describe an info tile by its limetype and filter
     * ```ts
     * import {
     *     ConfigDescription,
     *     PlatformServiceName,
     * } from '@limetech/lime-web-components';
     *
     * interface InfoTileConfig {
     *     limetype: string;
     *     filterId: string;
     * }
     *
     * const limetypes = platform.get(PlatformServiceName.LimeTypeRepository);
     * const filters = platform.get(PlatformServiceName.FilterRepository);
     * const application = platform.get(PlatformServiceName.Application);
     * const translator = platform.get(PlatformServiceName.Translate);
     *
     * function describeInfoTile(config: InfoTileConfig): ConfigDescription {
     *     const limetype = limetypes.getLimeType(config.limetype);
     *     const filter = filters.getFilter?.(config.filterId);
     *     const filterName = filter?.name[application.getLanguage()];
     *
     *     return {
     *         facts: [
     *             {
     *                 label: translator.get('my-addon.info-tile.limetype'),
     *                 text: limetype?.localname.plural ?? config.limetype,
     *             },
     *             {
     *                 label: translator.get('my-addon.info-tile.filter'),
     *                 text: filterName ?? config.filterId,
     *             },
     *         ],
     *     };
     * }
     *
     * const registry = platform.get(PlatformServiceName.WebComponentRegistry);
     *
     * registry.register('my-addon-info-tile', {
     *     title: 'Info tile',
     *     icon: 'info',
     *     describeConfig: describeInfoTile,
     * });
     * ```
     *
     * @see {@link ConfigDescription}
     * @beta
     */
    describeConfig?(config: unknown): ConfigDescription | undefined;
};
/**
 * Metadata describing a package or addon using Lime Web Components.
 *
 * This metadata is defined in the package's `package.json` file under the
 * `lime` field. The system reads this metadata before installing
 * a package to ensure compatibility between the package and the target
 * Lime CRM client environment.
 *
 * Packages should declare which platforms they support to prevent installation
 * in incompatible environments.
 *
 * @example In package.json
 * ```json
 * {
 *   "name": "my-addon",
 *   "version": "1.0.0",
 *   "lime": {
 *     "platforms": ["LimeCRMWebClient", "LimeCRMDesktopClient"]
 *   }
 * }
 * ```
 *
 * @group Core
 * @public
 */
export interface LimePackageMetadata {
    /**
     * List of platform types this package is compatible with.
     *
     * If specified, the package will only be loaded on the listed platforms.
     * Omitting this field means the package is compatible with all platforms.
     *
     * Platform types:
     * - `LimeCRMWebClient` - Standard web browser client
     * - `LimeCRMDesktopClient` - Desktop application client
     * - `LimeCRMWebAdminClient` - Administrative web interface
     *
     * @example A web-only package
     * ```json
     * {
     *   "lime": {
     *     "platforms": ["LimeCRMWebClient", "LimeCRMWebAdminClient"]
     *   }
     * }
     * ```
     */
    platforms?: Array<LimeWebComponentPlatform['type']>;
}