@plasmicapp/loader-react 1.0.341 → 1.0.343

package/dist/react-server.d.ts

@@ -1,14 +1,199 @@
+/// <reference types="react" />
+
+import { AssetModule } from '@plasmicapp/loader-core';
+import type { CodeComponentMeta as CodeComponentMeta_2 } from '@plasmicapp/host';
 import { CodeModule } from '@plasmicapp/loader-fetcher';
+import type { ComponentHelpers } from '@plasmicapp/host';
 import { ComponentMeta } from '@plasmicapp/loader-core';
 import { ComponentMeta as ComponentMeta_2 } from '@plasmicapp/loader-fetcher';
+import type { CustomFunctionMeta as CustomFunctionMeta_2 } from '@plasmicapp/host';
+import { FontMeta } from '@plasmicapp/loader-core';
+import { getExternalIds } from '@plasmicapp/loader-splits';
+import type { GlobalContextMeta as GlobalContextMeta_2 } from '@plasmicapp/host';
+import { GlobalGroupMeta } from '@plasmicapp/loader-core';
 import { LoaderBundleCache } from '@plasmicapp/loader-core';
-import { LoaderBundleOutput } from '@plasmicapp/loader-core';
-import { LoaderBundleOutput as LoaderBundleOutput_2 } from '@plasmicapp/loader-fetcher';
+import { LoaderBundleOutput } from '@plasmicapp/loader-fetcher';
+import { LoaderBundleOutput as LoaderBundleOutput_2 } from '@plasmicapp/loader-core';
 import { PageMeta } from '@plasmicapp/loader-core';
 import { PageMetadata } from '@plasmicapp/loader-core';
+import { plasmicappDataSourcesContext } from '@plasmicapp/data-sources-context';
+import { plasmicappHost } from '@plasmicapp/host';
+import { plasmicappQuery } from '@plasmicapp/query';
 import { PlasmicModulesFetcher } from '@plasmicapp/loader-core';
 import { PlasmicTracker } from '@plasmicapp/loader-core';
+import { react } from 'react';
+import * as React_2 from 'react';
+import { default as React_3 } from 'react';
+import { reactDom } from 'react-dom';
+import { reactJsxDevRuntime } from 'react/jsx-dev-runtime';
+import { reactJsxRuntime } from 'react/jsx-runtime';
+import { Registry } from '@plasmicapp/loader-core';
 import { Split } from '@plasmicapp/loader-fetcher';
+import type { StateHelpers } from '@plasmicapp/host';
+import type { StateSpec } from '@plasmicapp/host';
+import type { TokenRegistration } from '@plasmicapp/host';
+import { TrackRenderOptions } from '@plasmicapp/loader-core';
+import type { TraitMeta } from '@plasmicapp/host';
+import type { useDataEnv } from '@plasmicapp/host';
+import type { useMutablePlasmicQueryData } from '@plasmicapp/query';
+import type { useSelector } from '@plasmicapp/host';
+import type { useSelectors } from '@plasmicapp/host';
+
+/**
+ * Performs a prepass over Plasmic content, kicking off the necessary
+ * data fetches, and populating the fetched data into a cache.  This
+ * cache can be passed as prefetchedQueryData into PlasmicRootProvider.
+ *
+ * To limit rendering errors that can occur when you do this, we recommend
+ * that you pass in _only_ the PlasmicComponents that you are planning to use
+ * as the argument.  For example:
+ *
+ *   const cache = await extractPlasmicQueryData(
+ *     <ClientPlasmicRootProvider prefetchedData={plasmicData}>
+ *       <PlasmicComponent component="Home" componentProps={{
+ *         // Specify the component prop overrides you are planning to use
+ *         // to render the page, as they may change what data is fetched.
+ *         ...
+ *       }} />
+ *       <PlasmicComponent component="NavBar" componentProps={{
+ *         ...
+ *       }} />
+ *       ...
+ *     </ClientPlasmicRootProvider>,
+ *     PLASMIC
+ *   );
+ *
+ * If your PlasmicComponent will be wrapping components that require special
+ * context set up, you should also wrap the element above with those context
+ * providers. Avoid, however, wrapping the root provider, because we inspect
+ * the props passed to the root element.
+ *
+ * You should avoid passing in elements that are not related to Plasmic, as any
+ * rendering errors from those elements during the prepass may result in data
+ * not being populated in the cache.
+ *
+ * @param element a React element containing instances of PlasmicComponent.
+ *   Will attempt to satisfy all data needs from usePlasmicDataQuery()
+ *   in this element tree.
+ * @returns an object mapping query key to fetched data
+ */
+export declare function __EXPERMIENTAL__extractPlasmicQueryData(element: React.ReactElement, loader: PlasmicComponentLoader): Promise<Record<string, any>>;
+
+/** Subset of loader functionality that works on Client and React Server Components. */
+declare abstract class BaseInternalPlasmicComponentLoader {
+    readonly opts: InitOptions;
+    private readonly registry;
+    private readonly tracker;
+    private readonly fetcher;
+    private readonly onBundleMerged?;
+    private readonly onBundleFetched?;
+    private globalVariants;
+    private subs;
+    private bundle;
+    constructor(args: {
+        opts: InitOptions;
+        fetcher: PlasmicModulesFetcher;
+        tracker: PlasmicTracker;
+        /** Called after `mergeBundle` (including `fetch` calls). */
+        onBundleMerged?: () => void;
+        /** Called after any `fetch` calls. */
+        onBundleFetched?: () => void;
+        builtinModules: BuiltinRegisteredModules;
+    });
+    private maybeGetCompMetas;
+    maybeFetchComponentData(specs: ComponentLookupSpec[], opts?: FetchComponentDataOpts): Promise<ComponentRenderData | null>;
+    maybeFetchComponentData(...specs: ComponentLookupSpec[]): Promise<ComponentRenderData | null>;
+    fetchComponentData(specs: ComponentLookupSpec[], opts?: FetchComponentDataOpts): Promise<ComponentRenderData>;
+    fetchComponentData(...specs: ComponentLookupSpec[]): Promise<ComponentRenderData>;
+    fetchPages(opts?: FetchPagesOpts): Promise<PageMeta[]>;
+    fetchComponents(): Promise<ComponentMeta_2[]>;
+    getActiveSplits(): Split[];
+    getChunksUrl(bundle: LoaderBundleOutput, modules: CodeModule[]): string;
+    private fetchMissingData;
+    private maybeReportClientSideFetch;
+    private fetchAllData;
+    mergeBundle(newBundle: LoaderBundleOutput): void;
+    getBundle(): LoaderBundleOutput;
+    clearCache(): void;
+    registerModules(modules: Record<string, any>): void;
+    substituteComponent<P>(component: React.ComponentType<P>, name: ComponentLookupSpec): void;
+    protected internalSubstituteComponent<P>(component: React.ComponentType<P>, name: ComponentLookupSpec, codeComponentHelpers: ComponentHelpers<React.ComponentProps<React.ComponentType<P>>> | undefined): void;
+    abstract registerComponent<T extends React.ComponentType<any>>(component: T, meta: CodeComponentMeta<React.ComponentProps<T>>): void;
+    abstract registerFunction<F extends (...args: any[]) => any>(fn: F, meta: CustomFunctionMeta<F>): void;
+    abstract registerGlobalContext<T extends React.ComponentType<any>>(context: T, meta: GlobalContextMeta<React.ComponentProps<T>>): void;
+    abstract registerTrait(trait: string, meta: TraitMeta): void;
+    abstract registerToken(token: TokenRegistration): void;
+    protected refreshRegistry(): void;
+    isRegistryEmpty(): boolean;
+    clearRegistry(): void;
+    setGlobalVariants(globalVariants: GlobalVariantSpec[]): void;
+    getGlobalVariants(): GlobalVariantSpec[];
+    registerPrefetchedBundle(bundle: LoaderBundleOutput): void;
+    getLookup(): ComponentLookup;
+    trackConversion(value?: number): void;
+    getActiveVariation(opts: {
+        traits: Record<string, string | number | boolean>;
+        getKnownValue: (key: string) => string | undefined;
+        updateKnownValue: (key: string, value: string) => void;
+    }): Promise<Record<string, string>>;
+    getTeamIds(): string[];
+    getProjectIds(): string[];
+    trackRender(opts?: TrackRenderOptions): void;
+}
+
+declare interface BuiltinRegisteredModules {
+    react: react;
+    "react-dom": reactDom;
+    "react/jsx-runtime": reactJsxRuntime;
+    "react/jsx-dev-runtime": reactJsxDevRuntime;
+    "@plasmicapp/query": plasmicappQuery;
+    "@plasmicapp/data-sources-context": plasmicappDataSourcesContext;
+    "@plasmicapp/host": plasmicappHost;
+    "@plasmicapp/loader-runtime-registry": {
+        components: Record<string, React.ComponentType<any>>;
+        globalVariantHooks: Record<string, () => any>;
+        codeComponentHelpers: Record<string, ComponentHelpers<any>>;
+        functions: Record<string, (...args: any[]) => any>;
+    };
+}
+
+declare type CodeComponentMeta<P> = Omit<CodeComponentMeta_2<P>, "importPath" | "componentHelpers" | "states"> & {
+    /**
+     * The path to be used when importing the component in the generated code.
+     * It can be the name of the package that contains the component, or the path
+     * to the file in the project (relative to the root directory).
+     * Optional: not used by Plasmic headless API, only by codegen.
+     */
+    importPath?: string;
+    /**
+     * The states helpers are registered together with the states for the Plasmic headless API
+     */
+    states?: Record<string, StateSpec<P> & StateHelpers<P, any>>;
+    /**
+     * Helper function to enable data extraction when running Plasmic from
+     * Next.js App Router.
+     */
+    getServerInfo?: (props: P, ops: ReactServerOps) => ServerInfo;
+};
+
+declare class ComponentLookup {
+    private bundle;
+    private registry;
+    constructor(bundle: LoaderBundleOutput_2, registry: Registry);
+    getComponentMeta(spec: ComponentLookupSpec): ComponentMeta | undefined;
+    getComponent<P extends React_2.ComponentType = any>(spec: ComponentLookupSpec, opts?: {
+        forceOriginal?: boolean;
+    }): any;
+    hasComponent(spec: ComponentLookupSpec): boolean;
+    getGlobalContexts(): {
+        meta: GlobalGroupMeta;
+        context: any;
+    }[];
+    getGlobalContextsProvider(spec: ComponentLookupSpec): any;
+    getRootProvider(): any;
+    getCss(): AssetModule[];
+    getRemoteFonts(): FontMeta[];
+}
 
 declare type ComponentLookupSpec = string | {
     name: string;
@@ -19,14 +204,24 @@ declare type ComponentLookupSpec = string | {
 export { ComponentMeta }
 
 export declare interface ComponentRenderData {
-    entryCompMetas: (ComponentMeta & {
+    entryCompMetas: (ComponentMeta_2 & {
         params?: Record<string, string>;
     })[];
     bundle: LoaderBundleOutput;
     remoteFontUrls: string[];
 }
 
-export declare const convertBundlesToComponentRenderData: (bundles: LoaderBundleOutput[], compMetas: ComponentMeta[]) => ComponentRenderData | null;
+export declare const convertBundlesToComponentRenderData: (bundles: LoaderBundleOutput_2[], compMetas: ComponentMeta[]) => ComponentRenderData | null;
+
+declare type CustomFunctionMeta<F extends (...args: any[]) => any> = Omit<CustomFunctionMeta_2<F>, "importPath"> & {
+    /**
+     * The path to be used when importing the function in the generated code.
+     * It can be the name of the package that contains the function, or the path
+     * to the file in the project (relative to the root directory).
+     * Optional: not used by Plasmic headless API, only by codegen.
+     */
+    importPath?: string;
+};
 
 declare interface FetchComponentDataOpts {
     /**
@@ -55,6 +250,22 @@ declare type FetchPagesOpts = {
     includeDynamicPages?: boolean;
 };
 
+declare type GlobalContextMeta<P> = Omit<GlobalContextMeta_2<P>, "importPath"> & {
+    /**
+     * The path to be used when importing the component in the generated code.
+     * It can be the name of the package that contains the component, or the path
+     * to the file in the project (relative to the root directory).
+     * Optional: not used by Plasmic headless API, only by codegen.
+     */
+    importPath?: string;
+};
+
+declare interface GlobalVariantSpec {
+    name: string;
+    projectId?: string;
+    value: any;
+}
+
 export declare interface InitOptions {
     projects: {
         id: string;
@@ -100,7 +311,17 @@ export declare interface InitOptions {
     manualRedirect?: boolean;
 }
 
-export declare function initPlasmicLoader(opts: InitOptions): ReactServerPlasmicComponentLoader;
+export declare function initPlasmicLoader(opts: InitOptions): PlasmicComponentLoader;
+
+export declare class InternalPlasmicComponentLoader extends BaseInternalPlasmicComponentLoader {
+    constructor(opts: InitOptions);
+    registerComponent<T extends React_3.ComponentType<any>>(component: T, meta: CodeComponentMeta<React_3.ComponentProps<T>>): void;
+    registerFunction<F extends (...args: any[]) => any>(fn: F, meta: CustomFunctionMeta<F>): void;
+    registerGlobalContext<T extends React_3.ComponentType<any>>(context: T, meta: GlobalContextMeta<React_3.ComponentProps<T>>): void;
+    registerTrait: (trait: string, meta: TraitMeta) => void;
+    registerToken: (token: TokenRegistration) => void;
+    refreshRegistry(): void;
+}
 
 /**
  * Check if `lookup` resolves to `pagePath`. If it's a match, return an object
@@ -122,38 +343,162 @@ export { PageMeta }
 
 export { PageMetadata }
 
-/** Subset of loader functionality that works on React Server Components. */
-export declare class ReactServerPlasmicComponentLoader {
-    private readonly opts;
-    private readonly fetcher;
-    private readonly tracker;
-    private readonly onBundleMerged?;
-    private readonly onBundleFetched?;
-    private bundle;
-    constructor(args: {
-        opts: InitOptions;
-        fetcher: PlasmicModulesFetcher;
-        tracker: PlasmicTracker;
-        /** Called after `mergeBundle` (including `fetch` calls). */
-        onBundleMerged?: () => void;
-        /** Called after any `fetch` calls. */
-        onBundleFetched?: () => void;
-    });
-    private maybeGetCompMetas;
-    maybeFetchComponentData(specs: ComponentLookupSpec[], opts?: FetchComponentDataOpts): Promise<ComponentRenderData | null>;
-    maybeFetchComponentData(...specs: ComponentLookupSpec[]): Promise<ComponentRenderData | null>;
-    fetchComponentData(specs: ComponentLookupSpec[], opts?: FetchComponentDataOpts): Promise<ComponentRenderData>;
+/**
+ * Library for fetching component data, and registering
+ * custom components.
+ */
+export declare class PlasmicComponentLoader {
+    private __internal;
+    constructor(internal: BaseInternalPlasmicComponentLoader);
+    /**
+     * Sets global variants to be used for all components.  Note that
+     * this is not reactive, and will not re-render all components
+     * already mounted; instead, it should be used to activate global
+     * variants that should always be activated for the lifetime of this
+     * app.  If you'd like to reactively change the global variants,
+     * you should specify them via <PlasmicRootProvider />
+     */
+    setGlobalVariants(globalVariants: GlobalVariantSpec[]): void;
+    registerModules(modules: Record<string, any>): void;
+    /**
+     * Register custom components that should be swapped in for
+     * components defined in your project.  You can use this to
+     * swap in / substitute a Plasmic component with a "real" component.
+     */
+    substituteComponent<P>(component: React.ComponentType<P>, name: ComponentLookupSpec): void;
+    /**
+     * Register code components to be used on Plasmic Editor.
+     */
+    registerComponent<T extends React.ComponentType<any>>(component: T, meta: CodeComponentMeta<React.ComponentProps<T>>): void;
+    /**
+     * [[deprecated]] Please use `substituteComponent` instead for component
+     * substitution, or the other `registerComponent` overload to register
+     * code components to be used on Plasmic Editor.
+     *
+     * @see `substituteComponent`
+     */
+    registerComponent<T extends React.ComponentType<any>>(component: T, name: ComponentLookupSpec): void;
+    private warnedRegisterComponent;
+    registerFunction<F extends (...args: any[]) => any>(fn: F, meta: CustomFunctionMeta<F>): void;
+    registerGlobalContext<T extends React.ComponentType<any>>(context: T, meta: GlobalContextMeta<React.ComponentProps<T>>): void;
+    registerTrait(trait: string, meta: TraitMeta): void;
+    registerToken(token: TokenRegistration): void;
+    /**
+     * Pre-fetches component data needed to for PlasmicLoader to render
+     * these components.  Should be passed into PlasmicRootProvider as
+     * the prefetchedData prop.
+     *
+     * You can look up a component either by:
+     * - the name of the component
+     * - the path for a page component
+     * - an array of strings that make up parts of the path
+     * - object { name: "name_or_path", projectId: ...}, to specify which project
+     *   to use, if multiple projects have the same component name
+     *
+     * Throws an Error if a specified component to fetch does not exist in
+     * the Plasmic project.
+     */
     fetchComponentData(...specs: ComponentLookupSpec[]): Promise<ComponentRenderData>;
+    fetchComponentData(specs: ComponentLookupSpec[], opts?: FetchComponentDataOpts): Promise<ComponentRenderData>;
+    /**
+     * Like fetchComponentData(), but returns null instead of throwing an Error
+     * when a component is not found.  Useful when you are implementing a catch-all
+     * page and want to check if a specific path had been defined for Plasmic.
+     */
+    maybeFetchComponentData(...specs: ComponentLookupSpec[]): Promise<ComponentRenderData | null>;
+    maybeFetchComponentData(specs: ComponentLookupSpec[], opts?: FetchComponentDataOpts): Promise<ComponentRenderData | null>;
+    /**
+     * Returns all the page component metadata for these projects.
+     */
     fetchPages(opts?: FetchPagesOpts): Promise<PageMeta[]>;
+    /**
+     * Returns all components metadata for these projects.
+     */
     fetchComponents(): Promise<ComponentMeta_2[]>;
+    protected _getActiveVariation(opts: {
+        traits: Record<string, string | number | boolean>;
+        getKnownValue: (key: string) => string | undefined;
+        updateKnownValue: (key: string, value: string) => void;
+    }): Promise<Record<string, string>>;
+    getActiveVariation(opts: {
+        known?: Record<string, string>;
+        traits: Record<string, string | number | boolean>;
+    }): Promise<Record<string, string>>;
+    getChunksUrl(bundle: LoaderBundleOutput, modules: CodeModule[]): string;
+    getExternalVariation(variation: Record<string, string>, filters?: Parameters<typeof getExternalIds>[2]): Record<string, string>;
     getActiveSplits(): Split[];
-    getChunksUrl(bundle: LoaderBundleOutput_2, modules: CodeModule[]): string;
-    private fetchMissingData;
-    private maybeReportClientSideFetch;
-    private fetchAllData;
-    mergeBundle(bundle: LoaderBundleOutput_2): void;
-    getBundle(): LoaderBundleOutput_2;
+    trackConversion(value?: number): void;
     clearCache(): void;
 }
 
+/**
+ * Helper functions to describe code component behaviors, in order to allow
+ * data extraction in RSC / Next.js App routing.
+ */
+declare interface ReactServerOps {
+    readDataEnv: typeof useDataEnv;
+    readDataSelector: typeof useSelector;
+    readDataSelectors: typeof useSelectors;
+    /**
+     * The contexts are passed using a key instead of the context provider
+     * Notice it cannot access the default context value if none has been provided,
+     * since React server components cannot create contexts.
+     */
+    readContext: (contextKey: string) => any;
+    /**
+     * Allows data fetching from the code component and caching the result,
+     * which will be stored in the `queryCache` returned by
+     * `extractPlasmicQueryData`.
+     */
+    fetchData: typeof useMutablePlasmicQueryData;
+}
+
+/**
+ *  Each child of a code component might receive separate `DataProvider` and
+ *  Context values.
+ */
+declare interface ServerChildData {
+    providedData?: ServerProvidedData | ServerProvidedData[];
+    providedContexts?: ServerProvidedContext | ServerProvidedContext[];
+    node: React.ReactNode;
+}
+
+declare interface ServerInfo {
+    /**
+     * Optional: Indicates the React Nodes created by the component and the
+     * respective contexts provided to them. If not specified, it will render the
+     * children passed to the component as props.
+     */
+    children?: ServerChildData | ServerChildData[];
+    providedData?: ServerProvidedData | ServerProvidedData[];
+    providedContexts?: ServerProvidedContext | ServerProvidedContext[];
+}
+
+/**
+ * Provides a new value for a given context key, similar to Context.Provider.
+ * The context itself is not available (RSC doesn't allow calling
+ * `createContext`) so each context will need to be represented as a unique
+ * "context key". Also it means the default context value is not available
+ * in case no value is passed (and reading that context will return `undefined`)
+ */
+declare interface ServerProvidedContext {
+    /**
+     * Identifier to the context, required to read it later via
+     * `ReactServerOps.readContext()`.
+     */
+    contextKey: string;
+    /**
+     * Context value being provided (similar to `Context.Provider`).
+     */
+    value: any;
+}
+
+/**
+ * Represents data provided by a code component via `DataProvider`
+ */
+declare interface ServerProvidedData {
+    name: string;
+    data: any;
+}
+
 export { }