@plasmicapp/loader-react 1.0.340 → 1.0.342

package/dist/index.d.ts

@@ -1,44 +1,134 @@
+/// <reference types="react" />
+
 import { AssetModule } from '@plasmicapp/loader-core';
-import { CodeComponentMeta as CodeComponentMeta_2 } from '@plasmicapp/host';
+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 { CustomFunctionMeta as CustomFunctionMeta_2 } from '@plasmicapp/host';
+import { ComponentMeta as ComponentMeta_2 } from '@plasmicapp/loader-fetcher';
+import type { CustomFunctionMeta as CustomFunctionMeta_2 } from '@plasmicapp/host';
 import { DataCtxReader } from '@plasmicapp/host';
 import { DataProvider } from '@plasmicapp/host';
-import { extractPlasmicQueryData } from '@plasmicapp/prepass';
 import { FontMeta } from '@plasmicapp/loader-core';
 import { getExternalIds } from '@plasmicapp/loader-splits';
 import { GlobalActionsContext } from '@plasmicapp/host';
 import { GlobalActionsProvider } from '@plasmicapp/host';
-import { GlobalContextMeta as GlobalContextMeta_2 } from '@plasmicapp/host';
+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 } from '@plasmicapp/loader-fetcher';
+import { LoaderBundleOutput as LoaderBundleOutput_2 } from '@plasmicapp/loader-core';
 import { PageMeta } from '@plasmicapp/loader-core';
-import { PageMeta as PageMeta_2 } from '@plasmicapp/loader-fetcher';
 import { PageMetadata } from '@plasmicapp/loader-core';
 import { PageParamsProvider } from '@plasmicapp/host';
+import { plasmicappDataSourcesContext } from '@plasmicapp/data-sources-context';
+import { plasmicappHost } from '@plasmicapp/host';
+import { plasmicappQuery } from '@plasmicapp/query';
 import { PlasmicCanvasContext } from '@plasmicapp/host';
 import { PlasmicCanvasHost } from '@plasmicapp/host';
 import { PlasmicDataSourceContextValue } from '@plasmicapp/data-sources-context';
-import { plasmicPrepass } from '@plasmicapp/prepass';
+import { PlasmicModulesFetcher } from '@plasmicapp/loader-core';
+import { PlasmicTracker } from '@plasmicapp/loader-core';
 import { PropType } from '@plasmicapp/host';
-import { default as React_2 } from 'react';
-import * as React_3 from 'react';
+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 { repeatedElement } from '@plasmicapp/host';
 import { Split } from '@plasmicapp/loader-fetcher';
-import { StateHelpers } from '@plasmicapp/host';
-import { StateSpec } from '@plasmicapp/host';
+import type { StateHelpers } from '@plasmicapp/host';
+import type { StateSpec } from '@plasmicapp/host';
 import { TokenRegistration } from '@plasmicapp/host';
 import { TrackRenderOptions } from '@plasmicapp/loader-core';
 import { TraitMeta } from '@plasmicapp/host';
 import { useDataEnv } from '@plasmicapp/host';
+import type { useMutablePlasmicQueryData } from '@plasmicapp/query';
 import { usePlasmicCanvasContext } from '@plasmicapp/host';
 import { usePlasmicQueryData } from '@plasmicapp/query';
 import { useSelector } from '@plasmicapp/host';
 import { useSelectors } from '@plasmicapp/host';
 
+/** 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(bundle: 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>;
+    };
+}
+
 export declare type CodeComponentMeta<P> = Omit<CodeComponentMeta_2<P>, "importPath" | "componentHelpers" | "states"> & {
     /**
      * The path to be used when importing the component in the generated code.
@@ -51,14 +141,19 @@ export declare type CodeComponentMeta<P> = Omit<CodeComponentMeta_2<P>, "importP
      * 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, registry: Registry);
+    constructor(bundle: LoaderBundleOutput_2, registry: Registry);
     getComponentMeta(spec: ComponentLookupSpec): ComponentMeta | undefined;
-    getComponent<P extends React_3.ComponentType = any>(spec: ComponentLookupSpec, opts?: {
+    getComponent<P extends React_2.ComponentType = any>(spec: ComponentLookupSpec, opts?: {
         forceOriginal?: boolean;
     }): any;
     hasComponent(spec: ComponentLookupSpec): boolean;
@@ -81,14 +176,14 @@ export 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"> & {
     /**
@@ -104,7 +199,43 @@ export { DataCtxReader }
 
 export { DataProvider }
 
-export { extractPlasmicQueryData }
+/**
+ * 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(
+ *     <PlasmicRootProvider loader={PLASMIC} 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={{
+ *         ...
+ *       }} />
+ *       ...
+ *     </PlasmicRootProvider>
+ *   );
+ *
+ * If your PlasmicComponent will be wrapping components that require special
+ * context set up, you should also wrap the element above with those context
+ * providers.
+ *
+ * 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 extractPlasmicQueryData(element: React.ReactElement): Promise<Record<string, any>>;
 
 export declare function extractPlasmicQueryDataFromElement(loader: PlasmicComponentLoader, lookup: ComponentLookupSpec, opts?: {
     prefetchedData?: ComponentRenderData;
@@ -214,49 +345,17 @@ export declare interface InitOptions {
 
 export declare function initPlasmicLoader(opts: InitOptions): PlasmicComponentLoader;
 
-export declare class InternalPlasmicComponentLoader {
-    opts: InitOptions;
-    private readonly reactServerLoader;
-    private readonly registry;
-    private subs;
-    private roots;
-    private globalVariants;
-    private tracker;
+export declare class InternalPlasmicComponentLoader extends BaseInternalPlasmicComponentLoader {
+    private readonly roots;
     constructor(opts: InitOptions);
-    getBundle(): LoaderBundleOutput;
-    setGlobalVariants(globalVariants: GlobalVariantSpec[]): void;
-    getGlobalVariants(): GlobalVariantSpec[];
-    registerModules(modules: Record<string, any>): void;
-    substituteComponent<P>(component: React_2.ComponentType<P>, name: ComponentLookupSpec): void;
-    private internalSubstituteComponent;
-    registerComponent<T extends React_2.ComponentType<any>>(component: T, meta: CodeComponentMeta<React_2.ComponentProps<T>>): void;
+    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_2.ComponentType<any>>(context: T, meta: GlobalContextMeta<React_2.ComponentProps<T>>): 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;
-    registerPrefetchedBundle(bundle: LoaderBundleOutput): void;
     subscribePlasmicRoot(watcher: PlasmicRootWatcher): void;
     unsubscribePlasmicRoot(watcher: PlasmicRootWatcher): void;
-    clearCache(): void;
-    getLookup(): ComponentLookup;
-    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_2[]>;
-    fetchComponents(): Promise<ComponentMeta[]>;
-    getActiveSplits(): Split[];
-    getChunksUrl(bundle: LoaderBundleOutput, modules: CodeModule[]): string;
-    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;
-    private refreshRegistry;
+    refreshRegistry(): void;
 }
 
 /**
@@ -302,7 +401,7 @@ export declare function PlasmicComponent(props: {
      */
     forceOriginal?: boolean;
     componentProps?: any;
-}): React_3.ReactElement | null;
+}): React_2.ReactElement | null;
 
 /**
  * Library for fetching component data, and registering
@@ -310,7 +409,7 @@ export declare function PlasmicComponent(props: {
  */
 export declare class PlasmicComponentLoader {
     private __internal;
-    constructor(internal: InternalPlasmicComponentLoader);
+    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
@@ -326,11 +425,11 @@ export declare class PlasmicComponentLoader {
      * components defined in your project.  You can use this to
      * swap in / substitute a Plasmic component with a "real" component.
      */
-    substituteComponent<P>(component: React_2.ComponentType<P>, name: ComponentLookupSpec): void;
+    substituteComponent<P>(component: React.ComponentType<P>, name: ComponentLookupSpec): void;
     /**
      * Register code components to be used on Plasmic Editor.
      */
-    registerComponent<T extends React_2.ComponentType<any>>(component: T, meta: CodeComponentMeta<React_2.ComponentProps<T>>): void;
+    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
@@ -338,10 +437,10 @@ export declare class PlasmicComponentLoader {
      *
      * @see `substituteComponent`
      */
-    registerComponent<T extends React_2.ComponentType<any>>(component: T, name: ComponentLookupSpec): void;
+    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_2.ComponentType<any>>(context: T, meta: GlobalContextMeta<React_2.ComponentProps<T>>): 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;
     /**
@@ -371,11 +470,11 @@ export declare class PlasmicComponentLoader {
     /**
      * Returns all the page component metadata for these projects.
      */
-    fetchPages(opts?: FetchPagesOpts): Promise<PageMeta_2[]>;
+    fetchPages(opts?: FetchPagesOpts): Promise<PageMeta[]>;
     /**
      * Returns all components metadata for these projects.
      */
-    fetchComponents(): Promise<ComponentMeta[]>;
+    fetchComponents(): Promise<ComponentMeta_2[]>;
     protected _getActiveVariation(opts: {
         traits: Record<string, string | number | boolean>;
         getKnownValue: (key: string) => string | undefined;
@@ -392,7 +491,10 @@ export declare class PlasmicComponentLoader {
     clearCache(): void;
 }
 
-export { plasmicPrepass }
+/**
+ * @deprecated Maintained for backwards compatibility
+ */
+export declare function plasmicPrepass(element: React.ReactElement): Promise<void>;
 
 /**
  * PlasmicRootProvider should be used at the root of your page
@@ -408,7 +510,7 @@ export declare function PlasmicRootProvider(props: {
      * Global variants to activate for Plasmic components
      */
     globalVariants?: GlobalVariantSpec[];
-    children?: React_3.ReactNode;
+    children?: React_2.ReactNode;
     /**
      * If true, will skip rendering css
      */
@@ -451,12 +553,12 @@ export declare function PlasmicRootProvider(props: {
      * Head component to use in PlasmicHead component (e.g. Head from next/head
      * or Helmet from react-helmet).
      */
-    Head?: React_3.ComponentType<any>;
+    Head?: React_2.ComponentType<any>;
     /**
      * Link component to use. Can be any component that takes in props passed
      * to an <a/> tag.
      */
-    Link?: React_3.ComponentType<any>;
+    Link?: React_2.ComponentType<any>;
     /**
      * Page route without params substitution (e.g. /products/[slug]).
      */
@@ -478,8 +580,8 @@ export declare function PlasmicRootProvider(props: {
     /**
      * Fallback value for the root-level React.Suspense
      */
-    suspenseFallback?: React_3.ReactNode;
-} & PlasmicDataSourceContextValue): React_3.JSX.Element;
+    suspenseFallback?: React_2.ReactNode;
+} & PlasmicDataSourceContextValue): React_2.JSX.Element;
 
 declare interface PlasmicRootWatcher {
     onDataFetched?: () => void;
@@ -487,12 +589,34 @@ declare interface PlasmicRootWatcher {
 
 export declare type PlasmicTranslator = (str: string, opts?: {
     components?: {
-        [key: string]: React_3.ReactElement | React_3.ReactFragment;
+        [key: string]: React_2.ReactElement | React_2.ReactFragment;
     };
-}) => React_3.ReactNode;
+}) => React_2.ReactNode;
 
 export { PropType }
 
+/**
+ * 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;
+}
+
 export declare function renderToElement(loader: PlasmicComponentLoader, target: HTMLElement, lookup: ComponentLookupSpec, opts?: {
     prefetchedData?: ComponentRenderData;
     componentProps?: any;
@@ -511,6 +635,54 @@ export declare function renderToString(loader: PlasmicComponentLoader, lookup: C
 
 export { repeatedElement }
 
+/**
+ *  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 { TokenRegistration }
 
 export { useDataEnv }
@@ -527,7 +699,7 @@ export { usePlasmicCanvasContext }
  *   You can set forceOriginal to true if you want to return the Plasmic-generated
  *   component instead.
  */
-export declare function usePlasmicComponent<P extends React_3.ComponentType = any>(spec: ComponentLookupSpec, opts?: {
+export declare function usePlasmicComponent<P extends React_2.ComponentType = any>(spec: ComponentLookupSpec, opts?: {
     forceOriginal?: boolean;
 }): P;