import { ContextMap } from './context-map';
/**
 * Describes a context entry, its id, a label, and an optional
 * description. Supplied at bootstrap when an entry is registered.
 *
 * The generic parameter ties `id` to a known key. So if you pass
 * `{ id: 'user' }`, the registration's fallback must return a `User`.
 * Passing a different type is a compile error.
 *
 * @example Register the built-in user entry
 * ```ts
 * import {
 *     ContextMetadata,
 *     PlatformServiceName,
 * } from '@limetech/lime-web-components';
 *
 * const userContext: ContextMetadata<'user'> = {
 *     id: 'user',
 *     label: 'Current user',
 *     description: 'The user currently authenticated in the session.',
 * };
 *
 * const registry = platform.get(PlatformServiceName.ContextRegistry);
 * const application = platform.get(PlatformServiceName.Application);
 *
 * // The `'user'` id pins the fallback's return type to User, so returning
 * // anything else would not compile.
 * registry.register(userContext, () => application.getCurrentUser());
 * ```
 *
 * @beta
 * @group Context
 */
export interface ContextMetadata<K extends keyof ContextMap = keyof ContextMap> {
    /**
     * The context id. Must be a key of {@link ContextMap}.
     *
     * Plugin-added entries should use namespaced ids (`mypkg.foo`,
     * `pluginx.bar`) so two plugins can't accidentally claim the same
     * name. The built-in keys are first-party and exempt from this
     * convention.
     */
    id: K;
    /**
     * Human-readable label. Useful for consumers that enumerate
     * registered entries.
     */
    label: string;
    /**
     * Longer description for tooltips or help text. Optional.
     */
    description?: string;
}