@genesislcap/foundation-shell 14.131.0 → 14.132.0

package/dist/foundation-shell.d.ts

@@ -0,0 +1,1098 @@
+import { Behavior } from '@microsoft/fast-element';
+import { ComposableStyles } from '@microsoft/fast-element';
+import type { DesignSystemModule } from '@genesislcap/foundation-utils';
+import type { ElementStyles } from '@microsoft/fast-element';
+import { FASTElement } from '@microsoft/fast-element';
+import type { FoundationRoute } from '@genesislcap/foundation-ui';
+import type { FoundationRouteCollection } from '@genesislcap/foundation-ui';
+import type { HasElement } from '@microsoft/fast-router';
+import { InterfaceSymbol } from '@microsoft/fast-foundation';
+import { RepeatOptions } from '@microsoft/fast-element';
+import type { StoreRoot } from '@genesislcap/foundation-store';
+import { ViewTemplate } from '@microsoft/fast-element';
+
+/**
+ * `App` provides APIs to register integration targets for PBCs and other actors to register their assets in bulk via
+ * token exports. It also provides specific APIs to add single assets to the application itself, like routes, elements,
+ * styles, store fragments etc.
+ *
+ * @example
+ * App reference via DI.
+ * ```ts
+ * import { App } from '@genesislcap/foundation-shell/app';
+ * ...
+ * @App private app: App;
+ * ```
+ *
+ * @example
+ * App reference via getApp util.
+ * ```ts
+ * import { getApp } from '@genesislcap/foundation-shell/app';
+ * ...
+ * const app = getApp();
+ * ```
+ *
+ * @public
+ */
+export declare interface App extends AppAssets, AppRegister, AppValidity {
+    /**
+     * High-level app configuration.
+     */
+    readonly config: AppConfig;
+    /**
+     * Register assets from either a globed dynamic import or some predefined AppAssets instance. This is a one time
+     * operation. Assets had be subsequently registered and deregistered using their individual APIs.
+     *
+     * @example
+     * Manual `AppAssets` registration.
+     * ```ts
+     * app.registerAssets({
+     *   // with or without pbcAssets
+     *   elements: [...],
+     *   metadata: [...],
+     *   registrations: [...],
+     *   routes: [...],
+     *   styles: [...],
+     *   stores: [...],
+     * });
+     * ```
+     *
+     * @example
+     * PBC `AppAssets` registration.
+     * ```ts
+     * import { importPBCAssets } from '@genesislcap/foundation-shell/pbc';
+     * ...
+     * const pbcAssets = await importPBCAssets();
+     * ...
+     * app.registerAssets(pbcAssets);
+     * ```
+     *
+     * @param assets - {@link AppAssets}.
+     */
+    registerAssets(assets: Partial<AppAssets>): void;
+    /**
+     * Deregister assets.
+     */
+    deregisterAssets(): void;
+    /**
+     * Check if the App has registered assets.
+     */
+    hasAssets(): boolean;
+}
+
+/**
+ * App DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const App: InterfaceSymbol<App>;
+
+/**
+ * Dynamically registered assets.
+ *
+ * @public
+ */
+export declare interface AppAssets {
+    /**
+     * All {@link AppElement} tokens.
+     */
+    readonly elements: AppElement[];
+    /**
+     * All {@link AppMetadata} tokens.
+     */
+    readonly metadata: AppMetadata[];
+    /**
+     * All {@link AppRegistration} tokens.
+     */
+    readonly registrations: AppRegistration[];
+    /**
+     * All {@link AppRoute} tokens.
+     */
+    readonly routes: AppRoute[];
+    /**
+     * All {@link AppStyle} tokens.
+     */
+    readonly styles: AppStyle[];
+    /**
+     * All {@link AppStore} tokens.
+     */
+    readonly stores: AppStore[];
+}
+
+/**
+ * AppConfig DI interface.
+ *
+ * @public
+ */
+export declare interface AppConfig {
+    context?: AppContext;
+    defaultElementRepeatOptions?: RepeatOptions;
+}
+
+/**
+ * AppConfig DI key.
+ *
+ * @internal
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ */
+export declare const AppConfig: InterfaceSymbol<AppConfig>;
+
+/**
+ * Context passed to predicate functions and other utilities.
+ *
+ * @privateRemarks
+ * Properties are dynamically assigned.
+ *
+ * @public
+ */
+export declare type AppContext = {
+    env?: string;
+    domain?: string;
+    user?: {};
+    answers?: {};
+    featureFlags?: {};
+};
+
+/**
+ * A record of app dependencies.
+ * @public
+ */
+export declare type AppDependencies = {
+    [key: string]: string;
+};
+
+/**
+ * A record of app dependency prerequisites.
+ * @public
+ */
+export declare type AppDependencyPrerequisites = {
+    [key: string]: string;
+};
+
+/**
+ * @example
+ * AppElement definition example.
+ * ```ts
+ * const store = getNotifyStore();
+ * ...
+ * export const inboxFlyout: AppElement = {
+ *   targetId: 'layout',
+ *   elements: html`
+ *     <zero-flyout
+ *       position="right"
+ *       @closed=${(x, c) => c.parent.$emit('change-inbox-display', false)}
+ *       ?closed=${() => !store.inboxDisplayState}
+ *       displayHeader=${false}
+ *       data-pbc-asset-id="inbox-flyout"
+ *     >
+ *       <foundation-inbox
+ *         @close=${(x, c) => (<Flyout>(<HTMLElement>c.event.target).parentNode).closeFlyout()}
+ *       ></foundation-inbox>
+ *     </zero-flyout>
+ *   `,
+ * };
+ * ```
+ *
+ * Note that bindings may need to use `c.parent` to `$emit` or reference properties of the target integration point.
+ * The inclusion of a `data-pbc-asset-id` is not a hard requirement, but should be considered for future operations.
+ *
+ * @example
+ * Optional runtime {@link AssetPredicate} function to determine if the asset should be used.
+ * ```ts
+ * export const inboxFlyout: AppElement = {
+ *   targetId: 'layout',
+ *   predicate: (context: AppContext) => true, // < assess the user, permissions, env, domain, etc.
+ *   elements: html``,
+ * }
+ * ```
+ *
+ * @typeParam TSource - Optional ViewTemplate TSource interface.
+ * @typeParam TParent - Optional ViewTemplate TParent interface.
+ * @typeParam TTarget - Optional target id type.
+ *
+ * @public
+ */
+export declare type AppElement<TSource = any, TParent = any, TTarget = string> = HasTarget<TTarget> & HasPredicate & {
+    /**
+     * The elements to integrate.
+     */
+    elements: ViewTemplate<TSource, TParent>;
+    /**
+     * Optional placement index which influences ordering.
+     */
+    placementIndex?: number;
+    /**
+     * Optional slot id of the target, such as start, end or default/omitted.
+     * @privateRemarks
+     * Not currently used. We could mirror https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentElement#position here.
+     */
+    slotId?: string;
+};
+
+/**
+ * Determine if {@link AppElement} should be included during runtime integration.
+ *
+ * Provides app, micro frontend, and seed author fine-grained control over what assets they will accept in their
+ * target integration points. This is a similar concept to {@link @microsoft/fast-element#ElementsFilter} which may be
+ * applied to slotted content. For example the accordion accepts slotted accordionItems only.
+ *
+ * @public
+ */
+export declare type AppElementPredicate = (element: AppElement, context?: AppContext) => boolean;
+
+/**
+ * @example
+ * AppMetadata definition example.
+ * ```ts
+ * // src/pbc/reporting/metadata.ts
+ *
+ * export const metadata: AppMetadata = {
+ *   name: '@genesiscommunitysuccess/pbc-reporting',
+ *   description: 'Genesis Reporting PBC',
+ *   version: '1.0.0',
+ *   prerequisites: {
+ *     '@genesislcap/foundation-ui': '14.0.0',
+ *     gsf: '7.1.0-SNAPSHOT',
+ *   },
+ *   dependencies: {
+ *     '@genesislcap/pbc-reporting': '1.0.0',
+ *     serverDepId: '7.1.0-SNAPSHOT',
+ *   },
+ * };
+ * ```
+ *
+ * @remarks
+ * It is not a hard requirement to have a `metadata.ts` file or a `AppMetadata` export token.
+ *
+ * @public
+ */
+export declare type AppMetadata = {
+    name: string;
+    version: string;
+    description?: string;
+    dependencies?: AppDependencies;
+    prerequisites?: AppDependencyPrerequisites;
+};
+
+/**
+ * APIs to register asset targets and assets. These can be lazily registered and deregistered.
+ *
+ * @public
+ */
+export declare interface AppRegister {
+    /** {@inheritDoc RegisterComponents} */
+    registerComponents: RegisterComponents;
+    /** {@inheritDoc RegisterElementsTarget} */
+    registerElementsTarget: RegisterElementsTarget;
+    /**
+     * API for developers to register {@link AppElement | AppElements} lazily.
+     *
+     * @example
+     * ```ts
+     * getApp().registerElement(someAppElement);
+     * ```
+     *
+     * @param element - The {@link AppElement} to register.
+     *
+     * @public
+     */
+    registerElement(element: AppElement): void;
+    /**
+     * API for developers to deregister {@link AppElement | AppElements}.
+     *
+     * @example
+     * ```ts
+     * getApp().deregisterElement(someAppElement);
+     * ```
+     *
+     * @param element - The {@link AppElement} to deregister.
+     *
+     * @public
+     */
+    deregisterElement(element: AppElement): void;
+    /** {@inheritDoc RegisterRouteCollection} */
+    registerRouteCollection: RegisterRouteCollection;
+    /**
+     * API for developers to register {@link AppRoute | AppRoutes} lazily.
+     *
+     * @example
+     * ```ts
+     * getApp().registerRoute(someAppRoute);
+     * ```
+     *
+     * @param route - The {@link AppRoute} to register.
+     *
+     * @public
+     */
+    registerRoute(route: AppRoute): void;
+    /**
+     * API for developers to deregister {@link AppRoute | AppRoutes}.
+     *
+     * @example
+     * ```ts
+     * getApp().deregisterRoute(someAppRoute);
+     * ```
+     *
+     * @param route - The {@link AppRoute} to deregister.
+     *
+     * @public
+     */
+    deregisterRoute(route: AppRoute): void;
+    /** {@inheritDoc RegisterStylesTarget} */
+    registerStylesTarget: RegisterStylesTarget;
+    /**
+     * API for developers to register {@link AppStyle | AppStyles} lazily.
+     *
+     * @example
+     * ```ts
+     * getApp().registerStyle(someAppStyle);
+     * ```
+     *
+     * @param style - The {@link AppStyle} to register.
+     *
+     * @public
+     */
+    registerStyle(style: AppStyle): void;
+    /**
+     * API for developers to deregister {@link AppStyle | AppStyles}.
+     *
+     * @example
+     * ```ts
+     * getApp().deregisterStyle(someAppStyle);
+     * ```
+     *
+     * @param style - The {@link AppStyle} to deregister.
+     *
+     * @public
+     */
+    deregisterStyle(style: AppStyle): void;
+    /** {@inheritDoc RegisterStoreRoot} */
+    registerStoreRoot: RegisterStoreRoot;
+    /**
+     * API for developers to register {@link AppStore | AppStores} lazily.
+     *
+     * @example
+     * ```ts
+     * getApp().registerStore(someAppStore);
+     * ```
+     *
+     * @param store - The {@link AppStore} to register.
+     *
+     * @public
+     */
+    registerStore(store: AppStore): void;
+    /**
+     * API for developers to deregister {@link AppStore | AppStores}.
+     *
+     * @example
+     * ```ts
+     * getApp().deregisterStore(someAppStore);
+     * ```
+     *
+     * @param store - The {@link AppStore} to deregister.
+     *
+     * @public
+     */
+    deregisterStore(store: AppStore): void;
+}
+
+/**
+ * @example
+ * Simple registration function to include a component and avoid it being tree-shaken out of the build.
+ * ```ts
+ * // src/pbc/notify/registrations.ts
+ *
+ * export function registerAlerts() {
+ *   FoundationAlerts;
+ * }
+ * ```
+ *
+ * @example
+ * Combined registration function.
+ * ```ts
+ * // src/pbc/notify/registrations.ts
+ *
+ * export function register() {
+ *   FoundationAlerts;
+ *   FoundationInbox;
+ *   ...
+ * }
+ * ```
+ *
+ * @example
+ * Using the host application's registration context to register with the design system and import from it if needed.
+ * ```ts
+ * // src/pbc/notify/registrations.ts
+ *
+ * export async function registerAlerts(context: AppRegistrationContext) {
+ *   try {
+ *     const { provideDesignSystem, tokenX } = context.designSystem;
+ *     provideDesignSystem().register(foundationAlerts, tokenX);
+ *   } catch (e) {
+ *     console.error('Error registering alerts', e);
+ *   }
+ * }
+ * ```
+ *
+ * When defining `AppRegistration` functions in a PBC context, consider defining separate register functions if various
+ * subcomponents may be conditionally included based on user preferences or runtime predicates.
+ *
+ * @param context - {@link AppRegistrationContext}.
+ *
+ * @public
+ */
+export declare type AppRegistration = (context: AppRegistrationContext) => void;
+
+/**
+ * Context used during component registration.
+ *
+ * @public
+ */
+export declare type AppRegistrationContext = {
+    /**
+     * Explicitly set by app author via registerComponents.
+     */
+    designSystem: DesignSystemModule;
+};
+
+/**
+ * @example
+ * AppRoute definition example.
+ * ```ts
+ * export const reporting: AppRoute = {
+ *   title: 'Reporting',
+ *   path: 'reporting',
+ *   name: 'reporting',
+ *   element: async () => (await import('@genesislcap/pbc-reporting')).Reporting,
+ *   navItems: [
+ *     {
+ *       navId: 'header',
+ *       title: 'Reporting',
+ *       icon: {
+ *         name: 'file-csv',
+ *         variant: 'solid',
+ *       },
+ *       placementIndex: 15,
+ *     },
+ *   ],
+ * };
+ * ```
+ *
+ * @example
+ * Optional runtime {@link AssetPredicate} function to determine if the asset should be used.
+ * ```ts
+ * export const reportingAdmin: AppRoute = {
+ *   path: 'reporting-admin',
+ *   predicate: (context: AppContext) => context.user.isAdmin(),
+ *   ...
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type AppRoute = FoundationRoute & HasElement & HasPredicate;
+
+/**
+ * Determine if the {@link AppRoute} should be integrated.
+ *
+ * Provides app, micro frontend, and seed author fine-grained control over what assets they will accept in their
+ * target integration points.
+ *
+ * @public
+ */
+export declare type AppRoutePredicate = (route: AppRoute, context?: AppContext) => boolean;
+
+/**
+ * @example
+ * AppStore definition example.
+ * ```ts
+ * // src/pbc/notify/stores.ts
+ *
+ * // Setup the foundation stores your PBC needs to function, then include the following for each:
+ *
+ * export function getNotifyStore(): NotifyStore {
+ *   return DI.getOrCreateDOMContainer().get(NotifyStore);
+ * }
+ *
+ * // The actual `AppStore` definition
+ * export const notifyAppStore: AppStore<NotifyStore> = {
+ *   store: getNotifyStore(),
+ * };
+ * ```
+ *
+ * @example
+ * Optional runtime {@link AssetPredicate} function to determine if the asset should be used.
+ * ```ts
+ * export const notifyAppStore: AppStore<NotifyStore> = {
+ *   store: getNotifyStore(),
+ *   predicate: (context: AppContext) => true, // < assess the user, permissions, env, domain, etc.
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare type AppStore<S = any> = HasPredicate & {
+    /**
+     * A `foundation-store` reference.
+     */
+    store: S;
+};
+
+/**
+ * Determine if {@link AppStore} should be included during runtime integration.
+ *
+ * Provides app, micro frontend, and seed author fine-grained control over what assets they will accept in their
+ * target integration points.
+ *
+ * @public
+ */
+export declare type AppStorePredicate = (store: AppStore, context?: AppContext) => boolean;
+
+/**
+ * @example
+ * AppStyle definition example.
+ * ```ts
+ * export const alerts: AppStyle = {
+ *   targetId: 'layout',
+ *   styles: css`
+ *     foundation-alerts {
+ *       --design-unit: 2.5;
+ *       --stroke-width: 1;
+ *     }
+ *
+ *     foundation-alerts::part(filter-button) {
+ *       --design-unit: 4;
+ *     }
+ *   `,
+ * };
+ * ```
+ *
+ * @example
+ * Optional runtime {@link AssetPredicate} function to determine if the asset should be used.
+ * ```ts
+ * export const alerts: AppStyle = {
+ *   targetId: 'layout',
+ *   predicate: (context: AppContext) => context.user.isAdmin(),
+ *   styles: css``,
+ *   ...
+ * }
+ * ```
+ *
+ * @typeParam TTarget - Optional target id type.
+ *
+ * @public
+ */
+export declare type AppStyle<T = string> = HasTarget<T> & HasPredicate & {
+    /**
+     * The styles to integrate.
+     */
+    styles: ComposableStyles | ComposableStyles[];
+};
+
+/**
+ * Determine if {@link AppStyle} should be included during runtime integration.
+ *
+ * Provides app, micro frontend, and seed author fine-grained control over what assets they will accept in their
+ * target integration points.
+ *
+ * @public
+ */
+export declare type AppStylePredicate = (style: AppStyle, context?: AppContext) => boolean;
+
+/**
+ * @internal
+ */
+declare class AppStylesTargetBehavior implements Behavior {
+    protected app: App;
+    protected targetId: AppTargetId;
+    protected predicate?: AppStylePredicate;
+    protected targetElement: FASTElement;
+    protected prevTargetStyles: ElementStyles;
+    protected nextTargetStyles: ElementStyles;
+    constructor(app: App, targetId: AppTargetId, predicate?: AppStylePredicate);
+    bind(elementInstance: FASTElement): void;
+    unbind(): void;
+    handleChange(): void;
+    protected updateTargetStyles(): void;
+}
+
+/**
+ * A targetId string or an array of targetId strings.
+ *
+ * Apps and micro frontends will predefine integration targets that dynamic app assets can target using a `targetId`
+ * property. This creates a pull-like effect where the host can live reload itself should any matching asset be lazily
+ * added, removed, or customised.
+ *
+ * @example
+ * Foundation-header example.
+ * ```ts
+ * // src/main/targetId.ts
+ *
+ * export type NavTargetId = 'nav-start' | 'nav' | 'nav-end';
+ * export type SideNavTargetId = 'side-nav-start' | 'side-nav' | 'side-nav-end';
+ * export type ElementTargetId = HeaderTargetId | NavTargetId | SideNavTargetId;
+ * export type StyleTargetId = 'header';
+ *
+ * // src/main/main.template.ts
+ *
+ * export const NavTemplate = html<Navigation>`
+ *    ...
+ *    ${app.registerElementsTarget<NavTargetId>('nav-start')}
+ *    ...
+ * `
+ *
+ * // src/main/main.styles.ts
+ *
+ * export const MainStyles = css`
+ *    ...
+ * `.withBehaviors(getApp().registerStylesTarget<StyleTargetId>('header'));
+ * ```
+ *
+ * @typeParam TTarget - Optional target id type.
+ *
+ * @public
+ */
+export declare type AppTargetId<TTarget = string> = TTarget | TTarget[];
+
+/**
+ * Determine if export token should be included in the import all glob.
+ *
+ * @public
+ */
+export declare type AppTokenTypePredicate = (token: unknown) => boolean;
+
+/**
+ * APIs to check app validity.
+ *
+ * @public
+ */
+export declare interface AppValidity {
+    /**
+     * Monitors metadata and other data points as assets are registered and deregistered for app validity.
+     *
+     * @param context - {@link AppValidityContext}.
+     * @returns A boolean to indicate app validity.
+     */
+    isValid(context: AppValidityContext): boolean;
+}
+
+/**
+ * Context used to assess app validity.
+ *
+ * @public
+ */
+export declare type AppValidityContext = {
+    dependencies?: AppDependencies;
+    prerequisites?: AppDependencyPrerequisites;
+};
+
+/**
+ * Asset runtime predicate function.
+ *
+ * @param context - {@link AppContext}.
+ *
+ * @public
+ */
+export declare type AssetPredicate = (context?: AppContext) => boolean;
+
+/**
+ * @public
+ */
+export declare const assetPredicate: (asset: HasPredicate, context: AppContext) => boolean;
+
+/**
+ * Default App implementation.
+ * @public
+ */
+export declare class DefaultApp implements App {
+    /**
+     * {@inheritDoc App.config}
+     * @internal
+     */
+    config: AppConfig;
+    /** {@inheritDoc AppAssets.elements} */
+    elements: AppElement[];
+    /** {@inheritDoc AppAssets.metadata} */
+    metadata: AppMetadata[];
+    /** {@inheritDoc AppAssets.registrations} */
+    registrations: AppRegistration[];
+    /** {@inheritDoc AppAssets.routes} */
+    routes: AppRoute[];
+    /** {@inheritDoc AppAssets.styles} */
+    styles: AppStyle[];
+    /** {@inheritDoc AppAssets.stores} */
+    stores: AppStore[];
+    /** {@inheritDoc AppRegister.registerElementsTarget} */
+    registerElementsTarget(targetId: any, predicate: any, repeatOptions?: RepeatOptions): ViewTemplate<any, any>;
+    /** {@inheritDoc AppRegister.registerElement} */
+    registerElement(element: any): void;
+    /** {@inheritDoc AppRegister.deregisterElement} */
+    deregisterElement(element: any): void;
+    /** {@inheritDoc AppRegister.registerRouteCollection} */
+    registerRouteCollection(routeCollection: any, predicate: any): any;
+    /** {@inheritDoc AppRegister.registerRoute} */
+    registerRoute(route: any): void;
+    /** {@inheritDoc AppRegister.deregisterRoute} */
+    deregisterRoute(route: any): void;
+    /** {@inheritDoc AppRegister.registerStoreRoot} */
+    registerStoreRoot(storeRoot: any, predicate: any): () => void;
+    /** {@inheritDoc AppRegister.registerStore} */
+    registerStore(store: any): void;
+    /** {@inheritDoc AppRegister.deregisterStore} */
+    deregisterStore(store: any): void;
+    /** {@inheritDoc AppRegister.registerStylesTarget} */
+    registerStylesTarget(targetId: any, predicate: any): AppStylesTargetBehavior;
+    /** {@inheritDoc AppRegister.registerStyle} */
+    registerStyle(style: any): void;
+    /** {@inheritDoc AppRegister.deregisterStyle} */
+    deregisterStyle(style: any): void;
+    /** {@inheritDoc AppRegister.registerComponents} */
+    registerComponents(context: any): void;
+    /**
+     * {@inheritDoc AppValidity.isValid}
+     *
+     * @privateRemarks
+     * This is a placeholder to potentially monitor metadata etc. as assets are registered and deregistered.
+     */
+    isValid(context: any): boolean;
+    /** {@inheritDoc App.registerAssets} */
+    registerAssets(assets: any): void;
+    /** {@inheritDoc App.deregisterAssets} */
+    deregisterAssets(): void;
+    /** {@inheritDoc App.hasAssets} */
+    hasAssets(): boolean;
+}
+
+/**
+ * Default AppConfig DI implementation.
+ * @public
+ */
+export declare const defaultAppConfig: AppConfig;
+
+/**
+ * @public
+ */
+export declare const DynamicTemplate: ViewTemplate<MainApplication>;
+
+/**
+ * Gets App from the DI container.
+ *
+ * @remarks
+ * A utility method for host applications that are not using decorators or the DI container.
+ *
+ * @example
+ * ```ts
+ * import { getApp } from '@genesislcap/foundation-shell/app';
+ * ...
+ * private user = getApp();
+ * ```
+ *
+ * @public
+ */
+export declare function getApp(): App;
+
+/**
+ * @param module - An imported module.
+ * @param predicate - Token type predicate.
+ * @public
+ */
+export declare const getQualifiedModuleTokens: <T extends unknown>(module: any, predicate: AppTokenTypePredicate) => T[];
+
+/**
+ * Interface that includes `predicate` function.
+ *
+ * @public
+ */
+export declare type HasPredicate = {
+    /**
+     * Optional runtime predicate to include or exclude the pbc asset.
+     */
+    predicate?: AssetPredicate;
+};
+
+/**
+ * Interface that includes `targetId`.
+ *
+ * @typeParam TTarget - Optional target id type.
+ *
+ * @public
+ */
+export declare type HasTarget<TTarget = string> = {
+    /**
+     * The target the asset is intended for, such as main, header, header-start, header-end, layout etc.
+     */
+    targetId: TTarget;
+};
+
+/**
+ * A utility for importing PBC assets that have been added to the application's src/pbc directory via genx add.
+ *
+ * The `genx` builder (webpack or vite) will attempt to dynamically load all PBC assets from the application's `src/pbc`
+ * directory by default. The returned AppAssets can then be applied to the App. Please note that `app.registerAssets`
+ * is a one-time operation, intended for upfront bulk registration. After this point, you must use the single asset
+ * APIs of the `App` for lazy asset registration or deregistration.
+ *
+ * @example
+ * ```ts
+ * import { importPBCAssets } from '@genesislcap/foundation-shell/pbc';
+ * ...
+ * const assets = await importPBCAssets();
+ * ...
+ * app.registerAssets(assets);
+ * ```
+ *
+ * @example
+ * A typical app setup that makes use of PBC imports might look like this.
+ * ```ts
+ * // src/main/main.ts
+ *
+ * @App app: App;
+ *
+ * async connectedCallback() {
+ *   ...
+ *   await this.loadPBCs();
+ *   ...
+ * }
+ *
+ * async loadPBCs() {
+ *   // Import PBC assets that may have been added to the ./pbc directory by genx or by hand
+ *   const pbcAssets = await importPBCAssets();
+ *
+ *   // Register bulk assets
+ *   this.app.registerAssets(pbcAssets);
+ *
+ *   // Register the top-level route collection
+ *   this.app.registerRouteCollection(this.config.routes);
+ * }
+ * ```
+ *
+ * The rest of the PBC setup is handled by the system automatically, however, you will still need to register
+ * application asset integration points.
+ *
+ * @example
+ * A typical PBC directory structure may look like this.
+ * ```markdown
+ * ├── reporting
+ * │   ├── elements.ts
+ * │   ├── metadata.ts
+ * │   ├── registrations.ts
+ * │   ├── routes.ts
+ * │   ├── stores.ts
+ * │   └── styles.ts
+ * ```
+ *
+ * Each file is dynamically loaded and processed as part of the overall PBC set the application contains. PBCs do not
+ * need to include `index.ts` files, and export token naming does not matter within any of these files. For example,
+ * `foo` here `export const foo: AppElement = {...}` has no impact on PBC integration.
+ *
+ * The answers generated from the `genx add` cli flows can be used to tailor what PBC assets are included at build-time.
+ *
+ * @public
+ */
+export declare function importPBCAssets(): Promise<AppAssets>;
+
+/**
+ * @param token - A module export token.
+ * @public
+ */
+export declare function isAppElement(token: unknown): token is AppElement;
+
+/**
+ * @param token - A module export token.
+ * @public
+ */
+export declare function isAppMetadata(token: unknown): token is AppMetadata;
+
+/**
+ * @param token - A module export token.
+ * @public
+ */
+export declare function isAppRegistration(token: unknown): token is AppRegistration;
+
+/**
+ * @param token - A module export token.
+ * @public
+ */
+export declare function isAppRoute(token: unknown): token is AppRoute;
+
+/**
+ * @param token - A module export token.
+ * @public
+ */
+export declare function isAppStore(token: unknown): token is AppStore;
+
+/**
+ * @param token - A module export token.
+ * @public
+ */
+export declare function isAppStyle(token: unknown): token is AppStyle;
+
+/**
+ * @param token - A module export token / styles candidate.
+ * @public
+ */
+export declare function isComposableStyles(token: unknown): token is ComposableStyles;
+
+/**
+ * @param token - A module export token / element candidate.
+ * @public
+ */
+export declare function isViewTemplate(token: unknown): token is ViewTemplate;
+
+/**
+ * @public
+ */
+export declare const LoadingTemplate: ViewTemplate<MainApplication>;
+
+/**
+ * @public
+ */
+export declare class MainApplication extends FASTElement {
+    ready: boolean;
+    connectedCallback(): void;
+    selectTemplate(): ViewTemplate<MainApplication, any>;
+}
+
+/**
+ * @public
+ */
+export declare const MainTemplate: ViewTemplate<MainApplication>;
+
+/**
+ * API for Application and Seed authors to register dynamic components.
+ *
+ * @example
+ * Register components.
+ * ```ts
+ * export async function registerComponents() {
+ *   const designSystem = await designSystemImport();
+ *   const { provideDesignSystem, baseComponents } = designSystem;
+ *   ...
+ *   // Register any pbc components with the design system
+ *   getApp().registerComponents({
+ *     designSystem,
+ *   });
+ *   ...
+ *   provideDesignSystem().register(...);
+ * }
+ * ```
+ *
+ * PBCs or other application assets may need to register components with the design system of the application, or simply
+ * to ensure they are referenced, so they can be used in template literals without the risk of them being tree-shaken
+ * out by the application's build process.
+ *
+ * @public
+ */
+export declare type RegisterComponents = AppRegistration;
+
+/**
+ * API for Application and Seed authors to define dynamic {@link AppElement} integration points.
+ *
+ * @example
+ * Register elements targets within a {@link @microsoft/fast-element#html | html} template literal. An array can be used
+ * to integrate assets targeting N number of targets to the one integration location, ie. `['layout', 'layout-end']`.
+ * ```ts
+ * html`
+ *  ${app.registerElementsTarget('layout-start')}
+ *  ...
+ *  ${app.registerElementsTarget(['layout', 'layout-end'])}
+ * `
+ * ```
+ *
+ * @example
+ * Providing a predicate function to filter what elements you will allow.
+ * ```ts
+ * html`
+ *  ${app.registerElementsTarget('admin-tools', (element: AppElement, context: AppContext) => {
+ *    return context.user.isAdmin();
+ *  })}
+ * `
+ * ```
+ *
+ * @param targetId - {@link AppTargetId}.
+ * @param predicate - Optional {@link AppElementPredicate}.
+ * @returns A {@link @microsoft/fast-element#html | html} fragment that will stay in sync as elements are registered and deregistered.
+ *
+ * @public
+ */
+export declare type RegisterElementsTarget = <T = string>(targetId: AppTargetId<T>, predicate?: AppElementPredicate, repeatOptions?: RepeatOptions) => ViewTemplate;
+
+/**
+ * API for Application and Seed authors to register the main {@link @genesislcap/foundation-ui#FoundationRouteCollection | FoundationRouteCollection}.
+ *
+ * @example
+ * ```ts
+ * // src/main/main.ts
+ * ...
+ * getApp().registerRouteCollection(this.config.routes);
+ * ```
+ *
+ * @param routeCollection - The route collection to register {@link AppRoute | AppRoutes} to.
+ * @param predicate - Optional {@link AppRoutePredicate}.
+ *
+ * @public
+ */
+export declare type RegisterRouteCollection = (routeCollection: FoundationRouteCollection, predicate?: AppRoutePredicate) => (source: unknown) => void;
+
+/**
+ * API for Application and Seed authors to register the {@link @genesislcap/foundation-store#StoreRoot | StoreRoot}.
+ *
+ * @example
+ * ```ts
+ * // src/store/store.ts
+ *
+ * class DefaultStore extends AbstractStoreRoot<Store, StoreEventDetailMap> implements Store {
+ *   ...
+ *   constructor() {
+ *     super();
+ *
+ *     // Register the store root
+ *     getApp().registerStoreRoot(this);
+ *   }
+ *   ...
+ * }
+ * ```
+ *
+ * @param storeRoot - The store root to register {@link AppStore | AppStores} to.
+ * @param predicate - Optional {@link AppStorePredicate}.
+ *
+ * @public
+ */
+export declare type RegisterStoreRoot = (storeRoot: StoreRoot, predicate?: AppStorePredicate) => (source: unknown) => void;
+
+/**
+ * API for Application and Seed authors to define dynamic {@link AppStyle} integration points.
+ *
+ * @example
+ * Register styles targets as a {@link @microsoft/fast-element#Behavior | Behavior} on a {@link @microsoft/fast-element#css | css} definition.
+ * ```ts
+ * export const MainStyles = css`
+ *   :host {
+ *     contain: content;
+ *   }
+ * `.withBehaviors(getApp().registerStylesTarget('main'));
+ * ```
+ *
+ * @param targetId - {@link AppTargetId}.
+ * @param predicate - Optional {@link AppStylePredicate}.
+ * @returns A {@link @microsoft/fast-element#Behavior | Behavior} that will stay in sync as styles are registered and deregistered.
+ *
+ * @public
+ */
+export declare type RegisterStylesTarget = <T = string>(targetId: AppTargetId<T>, predicate?: AppStylePredicate) => Behavior;
+
+/**
+ * @public
+ */
+export declare const registrationPredicate: <A, P>(asset: A, predicate: P, context: AppContext) => boolean;
+
+/**
+ * @public
+ */
+export declare const targetIdPredicate: (asset: HasTarget, targetId: AppTargetId) => boolean;
+
+export { }