piral-core/lib/types/api.d.ts

The core library for creating a Piral instance.

import type { ReactElement, ReactNode } from 'react';
import type { RouteComponentProps } from 'react-router';
import type { PiletApi, Pilet, PiletEntry, PiletEntries, PiletMetadata, EventEmitter, PiletLoader, PiletLoadingStrategy } from 'piral-base';
import type { PiletCustomApi } from './custom';
import type { AnyComponent, PiralPageMeta } from './components';
import type { ExtensionParams, ExtensionSlotProps, PiralExtensionSlotMap } from './extension';
import type { SharedData, DataStoreOptions } from './data';
import type { Disposable } from './utils';
export { PiletApi, Pilet, PiletMetadata, EventEmitter, PiletEntry, PiletEntries, PiletLoader, PiletLoadingStrategy };
/**
 * The props that every registered component obtains.
 */
export interface BaseComponentProps {
    /**
     * The currently used pilet API.
     */
    piral: PiletApi;
}
/**
 * The shape of an implicit unregister function.
 */
export interface RegistrationDisposer {
    /**
     * Cleans up the previous registration.
     */
    (): void;
}
/**
 * The props of an extension component.
 */
export interface ExtensionComponentProps<T> extends BaseComponentProps {
    /**
     * The provided parameters for showing the extension.
     */
    params: T extends keyof PiralExtensionSlotMap ? PiralExtensionSlotMap[T] : T extends string ? any : T;
    /**
     * The optional children to receive, if any.
     */
    children?: ReactNode;
}
/**
 * The props that every registered page component obtains.
 */
export interface RouteBaseProps<UrlParams extends {
    [K in keyof UrlParams]?: string;
} = {}, UrlState = any> extends RouteComponentProps<UrlParams, {}, UrlState>, BaseComponentProps {
}
/**
 * The props used by a page component.
 */
export interface PageComponentProps<T extends {
    [K in keyof T]?: string;
} = {}, S = any> extends RouteBaseProps<T, S> {
    /**
     * The meta data registered with the page.
     */
    meta: PiralPageMeta;
    /**
     * The children of the page.
     */
    children: ReactNode;
}
/**
 * Shorthand for the definition of an extension component.
 */
export type AnyExtensionComponent<TName> = TName extends keyof PiralExtensionSlotMap ? AnyComponent<ExtensionComponentProps<TName>> : TName extends string ? AnyComponent<ExtensionComponentProps<any>> : AnyComponent<ExtensionComponentProps<TName>>;
/**
 * Defines the Pilet API from piral-core.
 * This interface will be consumed by pilet developers so that their pilet can interact with the piral instance.
 */
export interface PiletCoreApi {
    /**
     * Gets a shared data value.
     * @param name The name of the data to retrieve.
     */
    getData<TKey extends string>(name: TKey): SharedData[TKey];
    /**
     * Sets the data using a given name. The name needs to be used exclusively by the current pilet.
     * Using the name occupied by another pilet will result in no change.
     * @param name The name of the data to store.
     * @param value The value of the data to store.
     * @param options The optional configuration for storing this piece of data.
     * @returns True if the data could be set, otherwise false.
     */
    setData<TKey extends string>(name: TKey, value: SharedData[TKey], options?: DataStoreOptions): boolean;
    /**
     * Registers a route for predefined page component.
     * The route needs to be unique and can contain params.
     * Params are following the path-to-regexp notation, e.g., :id for an id parameter.
     * @param route The route to register.
     * @param Component The component to render the page.
     * @param meta The optional metadata to use.
     */
    registerPage(route: string, Component: AnyComponent<PageComponentProps>, meta?: PiralPageMeta): RegistrationDisposer;
    /**
     * Unregisters the page identified by the given route.
     * @param route The route that was previously registered.
     */
    unregisterPage(route: string): void;
    /**
     * Registers an extension component with a predefined extension component.
     * The name must refer to the extension slot.
     * @param name The global name of the extension slot.
     * @param Component The component to be rendered.
     * @param defaults Optionally, sets the default values for the expected data.
     */
    registerExtension<TName>(name: TName extends string ? TName : string, Component: AnyExtensionComponent<TName>, defaults?: Partial<ExtensionParams<TName>>): RegistrationDisposer;
    /**
     * Unregisters a global extension component.
     * Only previously registered extension components can be unregistered.
     * @param name The name of the extension slot to unregister from.
     * @param Component The registered extension component to unregister.
     */
    unregisterExtension<TName>(name: TName extends string ? TName : string, Component: AnyExtensionComponent<TName>): void;
    /**
     * React component for displaying extensions for a given name.
     * @param props The extension's rendering props.
     * @return The created React element.
     */
    Extension<TName>(props: ExtensionSlotProps<TName>): ReactElement | null;
    /**
     * Renders an extension in a plain DOM component.
     * @param element The DOM element or shadow root as a container for rendering the extension.
     * @param props The extension's rendering props.
     * @return The disposer to clear the extension.
     */
    renderHtmlExtension<TName>(element: HTMLElement | ShadowRoot, props: ExtensionSlotProps<TName>): Disposable;
}
declare module 'piral-base/lib/types/runtime' {
    interface PiletApi extends PiletCustomApi, PiletCoreApi {
    }
}
/**
 * Represents the dictionary of the loaded pilets and their APIs.
 */
export interface PiletsBag {
    /**
     * Gets the API of the respective pilet name.
     */
    [name: string]: PiletApi;
}