@plasmicapp/loader-react 1.0.38 → 1.0.39-6.beta

package/dist/react-server.d.ts

@@ -0,0 +1,501 @@
+/// <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 { getActiveVariation } from '@plasmicapp/loader-splits';
+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-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: Omit<Parameters<typeof getActiveVariation>[0], "splits">): Promise<Record<string, string>>;
+    getTeamIds(): string[];
+    getProjectIds(): string[];
+    trackRender(opts?: TrackRenderOptions): void;
+    loadServerQueriesModule(fileName: string): any;
+}
+
+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;
+    }[];
+    /** Returns StyleTokensProvider if the project has style token overrides. */
+    maybeGetStyleTokensProvider(spec: ComponentLookupSpec): any;
+    getGlobalContextsProvider(spec: ComponentLookupSpec): any;
+    getRootProvider(): any;
+    getCss(): AssetModule[];
+    getRemoteFonts(): FontMeta[];
+}
+
+declare type ComponentLookupSpec = string | {
+    name: string;
+    projectId?: string;
+    isCode?: boolean;
+};
+
+export { ComponentMeta }
+
+export declare interface ComponentRenderData {
+    entryCompMetas: (ComponentMeta_2 & {
+        params?: Record<string, string>;
+    })[];
+    bundle: LoaderBundleOutput;
+    remoteFontUrls: string[];
+}
+
+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 {
+    /**
+     * Will fetch either code targeting SSR or browser hydration in the
+     * returned bundle.
+     *
+     * By default, the target is browser. That's okay, because even when
+     * doing SSR, as long as you are using the same instance of PlasmicLoader
+     * that was used to fetch component data, it will still know how to get at
+     * the server code.
+     *
+     * But, if you are building your own SSR solution, where fetching and rendering
+     * are using different instances of PlasmicLoader, then you'll want to make
+     * sure that when you fetch, you are fetching the right one to be used in the
+     * right environment for either SSR or browser hydration.
+     */
+    target?: "server" | "browser";
+}
+
+declare type FetchPagesOpts = {
+    /**
+     * Whether to include dynamic pages in fetchPages() output. A page is
+     * considered dynamic if its path contains some param between brackets,
+     * e.g. "[slug]".
+     */
+    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;
+        token: string;
+        version?: string;
+    }[];
+    cache?: LoaderBundleCache;
+    platform?: "react" | "nextjs" | "gatsby";
+    platformOptions?: {
+        nextjs?: {
+            appDir: boolean;
+        };
+    };
+    preview?: boolean;
+    host?: string;
+    onClientSideFetch?: "warn" | "error";
+    i18n?: {
+        keyScheme: "content" | "hash" | "path";
+        tagPrefix?: string;
+    };
+    /**
+     * @deprecated use i18n.keyScheme instead
+     */
+    i18nKeyScheme?: "content" | "hash";
+    /**
+     * By default, fetchComponentData() and fetchPages() calls cached in memory
+     * with the PlasmicComponentLoader instance.  If alwaysFresh is true, then
+     * data is always freshly fetched over the network.
+     */
+    alwaysFresh?: boolean;
+    /**
+     * If true, generated code from the server won't include page metadata tags
+     */
+    skipHead?: boolean;
+    /**
+     * If true, uses browser / node's native fetch
+     */
+    nativeFetch?: boolean;
+    /**
+     * If true, will not redirect to the codegen server automatically, and will
+     * try to reuse the existing bundle in the cache.
+     */
+    manualRedirect?: boolean;
+}
+
+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
+ * containing path params; otherwise, return false.
+ *
+ * For example,
+ * - `matchesPagePath("/hello/[name]", "/hello/world")` -> `{params: {name:
+ *   "world"}}`
+ * - `matchesPagePath("/hello/[name]", "/")` -> `false`
+ * - `matchesPagePath("/hello/[...catchall]", "/hello/a/b/c")` -> `{params: {catchall: ["a", "b", "c"]}}`
+ * - `matchesPagePath("/hello/[[...catchall]]", "/hello/")` -> `{params: {catchall: []}}`
+ * - `matchesPagePath("/", "")` -> `{params: {}}`
+ */
+export declare function matchesPagePath(pattern: string, path: string): false | {
+    params: Record<string, string | string[]>;
+};
+
+export { PageMeta }
+
+export { PageMetadata }
+
+/**
+ * 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: Parameters<typeof PlasmicComponentLoader.__internal.getActiveVariation>[0]): 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[];
+    trackConversion(value?: number): void;
+    clearCache(): void;
+    unstable__getServerQueriesData(renderData: ComponentRenderData, $ctx: Record<string, any>): Promise<any>;
+}
+
+/**
+ * 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 { }