@plasmicapp/loader-react 1.0.317 → 1.0.319

package/dist/index.d.ts

@@ -1,15 +1,523 @@
-import { CodeComponentMeta, InternalPlasmicComponentLoader, PlasmicComponentLoader } from "./loader";
-import type { InitOptions } from "./loader-react-server";
-export type { PropType, TokenRegistration } from "@plasmicapp/host";
-export { DataCtxReader, DataProvider, PageParamsProvider, PlasmicCanvasContext, PlasmicCanvasHost, repeatedElement, useDataEnv, usePlasmicCanvasContext, useSelector, useSelectors, } from "@plasmicapp/host";
-export { usePlasmicQueryData } from "@plasmicapp/query";
-export * from "./shared-exports";
-export { PlasmicComponent } from "./PlasmicComponent";
-export type { GlobalVariantSpec, PlasmicTranslator, } from "./PlasmicRootProvider";
-export { PlasmicRootProvider } from "./PlasmicRootProvider";
-export { extractPlasmicQueryData, plasmicPrepass } from "@plasmicapp/prepass";
-export { extractPlasmicQueryDataFromElement, hydrateFromElement, renderToElement, renderToString, } from "./render";
-export { usePlasmicComponent } from "./usePlasmicComponent";
-export type { CodeComponentMeta };
-export { InternalPlasmicComponentLoader, PlasmicComponentLoader };
+import { AssetModule } from '@plasmicapp/loader-core';
+import { CodeComponentMeta as CodeComponentMeta_2 } from '@plasmicapp/host';
+import { ComponentMeta } from '@plasmicapp/loader-core';
+import { 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 { 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 { 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 { PlasmicCanvasContext } from '@plasmicapp/host';
+import { PlasmicCanvasHost } from '@plasmicapp/host';
+import { PlasmicDataSourceContextValue } from '@plasmicapp/data-sources-context';
+import { plasmicPrepass } from '@plasmicapp/prepass';
+import { PropType } from '@plasmicapp/host';
+import { default as React_2 } from 'react';
+import * as React_3 from 'react';
+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 { TokenRegistration } from '@plasmicapp/host';
+import { TrackRenderOptions } from '@plasmicapp/loader-core';
+import { TraitMeta } from '@plasmicapp/host';
+import { useDataEnv } from '@plasmicapp/host';
+import { usePlasmicCanvasContext } from '@plasmicapp/host';
+import { usePlasmicQueryData } from '@plasmicapp/query';
+import { useSelector } from '@plasmicapp/host';
+import { useSelectors } from '@plasmicapp/host';
+
+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.
+     * 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>>;
+};
+
+declare class ComponentLookup {
+    private bundle;
+    private registry;
+    constructor(bundle: LoaderBundleOutput, registry: Registry);
+    getComponentMeta(spec: ComponentLookupSpec): ComponentMeta | undefined;
+    getComponent<P extends React_3.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;
+    projectId?: string;
+    isCode?: boolean;
+};
+
+export { ComponentMeta }
+
+export declare interface ComponentRenderData {
+    entryCompMetas: (ComponentMeta & {
+        params?: Record<string, string>;
+    })[];
+    bundle: LoaderBundleOutput;
+    remoteFontUrls: string[];
+}
+
+export declare const convertBundlesToComponentRenderData: (bundles: LoaderBundleOutput[], 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;
+};
+
+export { DataCtxReader }
+
+export { DataProvider }
+
+export { extractPlasmicQueryData }
+
+export declare function extractPlasmicQueryDataFromElement(loader: PlasmicComponentLoader, lookup: ComponentLookupSpec, opts?: {
+    prefetchedData?: ComponentRenderData;
+    componentProps?: any;
+    globalVariants?: GlobalVariantSpec[];
+    prefetchedQueryData?: Record<string, any>;
+}): Promise<Record<string, any>>;
+
+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;
+};
+
+export declare interface GlobalVariantSpec {
+    name: string;
+    projectId?: string;
+    value: any;
+}
+
+export declare function hydrateFromElement(loader: PlasmicComponentLoader, target: HTMLElement, lookup: ComponentLookupSpec, opts?: {
+    prefetchedData?: ComponentRenderData;
+    componentProps?: any;
+    globalVariants?: GlobalVariantSpec[];
+    prefetchedQueryData?: Record<string, any>;
+}): Promise<void>;
+
+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;
+}
+
 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;
+    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;
+    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;
+    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[];
+    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;
+}
+
+/**
+ * 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("/", "")` -> `{params: {}}`
+ */
+export declare function matchesPagePath(pagePath: string, lookup: string): {
+    params: Record<string, string | string[]>;
+} | false;
+
+export { PageMeta }
+
+export { PageMetadata }
+
+export { PageParamsProvider }
+
+export { PlasmicCanvasContext }
+
+export { PlasmicCanvasHost }
+
+export declare function PlasmicComponent(props: {
+    /**
+     * Name of the component to render, or the path of the page component
+     */
+    component: string;
+    /**
+     * Optionally specify a projectId if there are multiple components
+     * of the same name from different projects
+     */
+    projectId?: string;
+    /**
+     * If you used registerComponent(), then if the name matches a registered
+     * component, that component is used.  If you want the Plasmic-generated
+     * component instead, specify forceOriginal.
+     */
+    forceOriginal?: boolean;
+    componentProps?: any;
+}): React_3.ReactElement | null;
+
+/**
+ * Library for fetching component data, and registering
+ * custom components.
+ */
+export declare class PlasmicComponentLoader {
+    private __internal;
+    constructor(internal: InternalPlasmicComponentLoader);
+    /**
+     * 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_2.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;
+    /**
+     * [[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_2.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;
+    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>;
+    /**
+     * 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>;
+    /**
+     * Returns all the page component metadata for these projects.
+     */
+    fetchPages(opts?: FetchPagesOpts): Promise<PageMeta_2[]>;
+    /**
+     * Returns all components metadata for these projects.
+     */
+    fetchComponents(): Promise<ComponentMeta[]>;
+    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>>;
+    getExternalVariation(variation: Record<string, string>, filters?: Parameters<typeof getExternalIds>[2]): Record<string, string>;
+    getActiveSplits(): Split[];
+    trackConversion(value?: number): void;
+    clearCache(): void;
+}
+
+export { plasmicPrepass }
+
+/**
+ * PlasmicRootProvider should be used at the root of your page
+ * or application.
+ */
+export declare function PlasmicRootProvider(props: {
+    /**
+     * The global PlasmicComponentLoader instance you created via
+     * initPlasmicLoader().
+     */
+    loader: PlasmicComponentLoader;
+    /**
+     * Global variants to activate for Plasmic components
+     */
+    globalVariants?: GlobalVariantSpec[];
+    children?: React_3.ReactNode;
+    /**
+     * If true, will skip rendering css
+     */
+    skipCss?: boolean;
+    /**
+     * If true, will skip installing fonts
+     */
+    skipFonts?: boolean;
+    /**
+     * If you have pre-fetched component data via PlasmicComponentLoader,
+     * you can pass them in here; PlasmicComponent will avoid fetching
+     * component data that have already been pre-fetched.
+     */
+    prefetchedData?: ComponentRenderData;
+    /**
+     * If you have pre-fetched data that are needed by usePlasmicQueryData(),
+     * then pass in the pre-fetched cache here, mapping query key to fetched data.
+     */
+    prefetchedQueryData?: Record<string, any>;
+    /**
+     * Specifies whether usePlasmicQueryData() should be operating in suspense mode
+     * (throwing promises).
+     */
+    suspenseForQueryData?: boolean;
+    /**
+     * Override your Global Contexts Provider props. This is a map from
+     * globalContextComponentNameProps to object of props to use for that
+     * component.
+     */
+    globalContextsProps?: Record<string, any>;
+    /**
+     * Specifies a mapping of split id to slice id that should be activated
+     */
+    variation?: Record<string, string>;
+    /**
+     * Translator function to be used for text blocks
+     */
+    translator?: PlasmicTranslator;
+    /**
+     * Head component to use in PlasmicHead component (e.g. Head from next/head
+     * or Helmet from react-helmet).
+     */
+    Head?: React_3.ComponentType<any>;
+    /**
+     * Link component to use. Can be any component that takes in props passed
+     * to an <a/> tag.
+     */
+    Link?: React_3.ComponentType<any>;
+    /**
+     * Page route without params substitution (e.g. /products/[slug]).
+     */
+    pageRoute?: string;
+    /**
+     * Page path parameters (e.g. {slug: "foo"} if page path is
+     * /products/[slug] and URI is /products/foo).
+     */
+    pageParams?: Record<string, string | string[] | undefined>;
+    /**
+     * Page query parameters (e.g. {q: "foo"} if page path is
+     * /some/path?q=foo).
+     */
+    pageQuery?: Record<string, string | string[] | undefined>;
+    /**
+     * Whether the React.Suspense boundaries should be removed
+     */
+    disableLoadingBoundary?: boolean;
+    /**
+     * Fallback value for the root-level React.Suspense
+     */
+    suspenseFallback?: React_3.ReactNode;
+} & PlasmicDataSourceContextValue): React_3.JSX.Element;
+
+declare interface PlasmicRootWatcher {
+    onDataFetched?: () => void;
+}
+
+export declare type PlasmicTranslator = (str: string, opts?: {
+    components?: {
+        [key: string]: React_3.ReactElement | React_3.ReactFragment;
+    };
+}) => React_3.ReactNode;
+
+export { PropType }
+
+export declare function renderToElement(loader: PlasmicComponentLoader, target: HTMLElement, lookup: ComponentLookupSpec, opts?: {
+    prefetchedData?: ComponentRenderData;
+    componentProps?: any;
+    globalVariants?: GlobalVariantSpec[];
+    prefetchedQueryData?: Record<string, any>;
+    pageParams?: Record<string, any>;
+    pageQuery?: Record<string, any>;
+}): Promise<void>;
+
+export declare function renderToString(loader: PlasmicComponentLoader, lookup: ComponentLookupSpec, opts?: {
+    prefetchedData?: ComponentRenderData;
+    componentProps?: any;
+    globalVariants?: GlobalVariantSpec[];
+    prefetchedQueryData?: Record<string, any>;
+}): string;
+
+export { repeatedElement }
+
+export { TokenRegistration }
+
+export { useDataEnv }
+
+export { usePlasmicCanvasContext }
+
+/**
+ * Hook that fetches and returns a React component for rendering the argument
+ * Plasmic component.  Returns undefined if the component data is still
+ * being fetched.
+ *
+ * @param opts.forceOriginal if you used PlasmicComponentLoader.registerComponent,
+ *   then normally usePlasmicComponent will return the registered component.
+ *   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?: {
+    forceOriginal?: boolean;
+}): P;
+
+export { usePlasmicQueryData }
+
+export { useSelector }
+
+export { useSelectors }
+
+export { }

package/dist/index.esm.js

@@ -56,11 +56,11 @@ import * as PlasmicDataSourcesContext from "@plasmicapp/data-sources-context";
 import * as PlasmicHost from "@plasmicapp/host";
 import {
   registerComponent,
+  registerFunction,
   registerGlobalContext,
   registerToken,
   registerTrait,
-  stateHelpersKeys,
-  unstable_registerFunction
+  stateHelpersKeys
 } from "@plasmicapp/host";
 import {
   PlasmicModulesFetcher,
@@ -933,9 +933,9 @@ var InternalPlasmicComponentLoader = class {
       }
     } : {}));
   }
-  unstable_registerFunction(fn, meta) {
+  registerFunction(fn, meta) {
     var _a;
-    unstable_registerFunction(fn, __spreadProps(__spreadValues({}, meta), {
+    registerFunction(fn, __spreadProps(__spreadValues({}, meta), {
       importPath: (_a = meta.importPath) != null ? _a : ""
     }));
     REGISTERED_CUSTOM_FUNCTIONS[customFunctionImportAlias(meta)] = fn;
@@ -1079,8 +1079,8 @@ var PlasmicComponentLoader = class {
       this.substituteComponent(component, metaOrName);
     }
   }
-  unstable_registerFunction(fn, meta) {
-    this.__internal.unstable_registerFunction(fn, meta);
+  registerFunction(fn, meta) {
+    this.__internal.registerFunction(fn, meta);
   }
   registerGlobalContext(context, meta) {
     this.__internal.registerGlobalContext(context, meta);