@uniformdev/canvas-react 18.1.1-alpha.11 → 18.1.2-alpha.7

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ComponentInstance, SubscribeToCompositionOptions, UpdateCompositionMessage, RootComponentInstance } from '@uniformdev/canvas';
+import { ComponentInstance, RootComponentInstance, UpdateCompositionMessage, SubscribeToCompositionOptions } from '@uniformdev/canvas';
+export { createUniformApiEnhancer } from '@uniformdev/canvas';
 import React$1, { Key, ReactNode } from 'react';
 
 /**
@@ -29,80 +30,50 @@ type ComponentStore = {
     get: (name: string) => React.ComponentType<ComponentProps<any>> | undefined;
 };
 
-type CompositionProps<TRenderProps = unknown> = {
-    /** The root component in the composition */
-    data: ComponentInstance;
+/**
+ * A default implementation of a component-not-implemented component.
+ * Useful for model-first workflows where frontend dev comes later.
+ * To make this work, it needs to be the default returned from the
+ * resolveRenderer() function when the component is unknown.
+ **/
+declare function DefaultNotImplementedComponent(props: ComponentProps): JSX.Element | null;
+
+type UniformComponentProps<TRenderProps = unknown> = {
+    /** The data of the component instance */
+    data: ComponentInstance | RootComponentInstance;
     /** Resolves a React component to render a Canvas component, generally by inspecting type/variant */
     resolveRenderer?: RenderComponentResolver;
-    /** Either markup to render the composition directly, or render props to provide the ComponentProps for the root component */
+    /** Children to render. Can also be a function that takes ComponentProps as argument */
     children?: ReactNode | ((props: ComponentProps<TRenderProps>) => JSX.Element);
     /**
-     * When to track behavior from enrichment tags on this composition
+     * When to track behavior from enrichment tags on the current composition
      * onView: adds enrichment score when the visitor views the tagged component in the browser viewport.
-     * onLoad: adds enrichment score as soon as the composition mounts, regardless of viewport.
+     * onLoad: adds enrichment score as soon as the component mounts, regardless of viewport.
      *
-     * NOTE: onView renders a <div> tag around components that have enrichment tags, to support IntersectionObserver.
+     * NOTE: onView renders a `<div>` tag around components that have enrichment tags, to support IntersectionObserver.
      * onLoad does not need to do this, and renders no wrapping tag.
      *
      * Default: onView
      */
     behaviorTracking?: 'onLoad' | 'onView';
 };
-type CompositionContext = {
-    /** The parent composition */
-    composition: ComponentInstance;
-    /** The current function to translate component data into React components */
-    resolveRenderer?: RenderComponentResolver;
-    behaviorTracking: 'onLoad' | 'onView';
+type UniformComponentContextValue = {
+    data?: UniformComponentProps['data'];
+    resolveRenderer?: UniformComponentProps['resolveRenderer'];
+    behaviorTracking?: UniformComponentProps['behaviorTracking'];
 };
 /**
- * Gets the parent Canvas composition of the current component.
- * Note: this gets the direct parent, not necessarily the root of the composition.
+ * Gets the data of the closest `<UniformComponent />` ancestor.
  */
-declare function useComposition(): CompositionContext | undefined;
-/** Forms a Canvas composition root, providing services to render a tree of Canvas components */
-declare function Composition<TRenderProps = unknown>({ data, resolveRenderer, children, behaviorTracking, }: CompositionProps<TRenderProps>): JSX.Element | null;
-
+declare function useUniformCurrentComponent(): UniformComponentContextValue;
 /**
- * A default implementation of a component-not-implemented component.
- * Useful for model-first workflows where frontend dev comes later.
- * To make this work, it needs to be the default returned from the
- * resolveRenderer() function when the component is unknown.
- **/
-declare function DefaultNotImplementedComponent(props: ComponentProps): JSX.Element | null;
-
-type CustomSlotChildRenderFunc = (options: {
-    child: ReactNode;
-    component: ComponentInstance;
-    key: Key;
-}) => JSX.Element;
-type SlotProps<TSlotNames extends string> = {
-    /** Name of the slot to render */
-    name: TSlotNames;
-    /**
-     * Function to resolve the React component to render for a given Canvas component type.
-     * If not specified, the resolveRenderer function on the nearest Layout will be used, if any.
-     */
-    resolveRenderer?: RenderComponentResolver;
-    /** Optional render props enables wrapping all child components in the slot with some markup */
-    children?: CustomSlotChildRenderFunc;
-    /**
-     * Optional ReactNode to use as a placeholder in Canvas editor when the slot is empty.
-     * The node is used to render a placeholder with realistic dimensions and it's never shown to users.
-     * Pass `null` to disable the placeholder.
-     */
-    emptyPlaceholder?: React$1.ReactNode;
-};
-/** Renders a named Slot within a Composition. */
-declare function Slot<TSlotNames extends string = string>({ name, resolveRenderer, children, emptyPlaceholder, }: SlotProps<TSlotNames>): JSX.Element | null;
-
-type UseCompositionEventEffectOptions = Omit<Partial<SubscribeToCompositionOptions>, 'callback'> & {
-    enabled: boolean;
-    effect: () => void;
-};
-/** Hook to manage a subscription to a realtime event on a composition */
-declare function useCompositionEventEffect({ enabled, projectId, compositionId, effect, }: UseCompositionEventEffectOptions): void;
+ * Allows the rendering of a Canvas component instance (root or not), and its children if it has any.
+ * Note that the actual rendering happens inside `<Slot />`, this component only provides the services needed to achieve that.
+ * This component is used internally by `<UniformComposition />`, which you should use in most cases.
+ */
+declare function UniformComponent<TRenderProps = unknown>({ data, resolveRenderer, children, behaviorTracking, }: UniformComponentProps<TRenderProps>): JSX.Element | null;
 
+/** @deprecated use `createUniformApiEnhancer` instead */
 declare const createApiEnhancer: ({ apiUrl }: {
     apiUrl: string;
 }) => (message: UpdateCompositionMessage) => Promise<{
@@ -173,10 +144,19 @@ declare const createApiEnhancer: ({ apiUrl }: {
         };
     } | undefined;
 }>;
-declare const useContextualEditing: ({ initialCompositionValue, enhance, }: {
+type UseUniformContextualEditingProps = {
     initialCompositionValue: RootComponentInstance;
-    enhance?: ((composition: UpdateCompositionMessage) => RootComponentInstance | Promise<RootComponentInstance>) | undefined;
-}) => {
+    /**
+     * A function to enhance the composition after receiving it from Canvas editor.
+     * WARNING: This enhancer will run on the client side. Make sure you're not exposing any secrets. You can use `createApiEnhancer` to create an enhancer based on an API route.
+     */
+    enhance?: (composition: UpdateCompositionMessage) => RootComponentInstance | Promise<RootComponentInstance>;
+};
+/**
+ * Adds contextual editing capability to a Uniform app.
+ * This hook is already integrated in `<UniformComposition />`, you won't need to use it directly, unless you have a custom setup.
+ */
+declare const useUniformContextualEditing: ({ initialCompositionValue, enhance, }: UseUniformContextualEditingProps) => {
     composition: {
         type: string;
         parameters?: {
@@ -247,6 +227,69 @@ declare const useContextualEditing: ({ initialCompositionValue, enhance, }: {
     };
 };
 
+type UniformCompositionProps<TRenderProps = unknown> = UniformComponentProps<TRenderProps> & {
+    /** The composition data */
+    data: RootComponentInstance;
+    contextualEditingEnhancer?: UseUniformContextualEditingProps['enhance'];
+};
+type UniformCompositionContextValue = {
+    data?: UniformCompositionProps['data'];
+    resolveRenderer?: UniformCompositionProps['resolveRenderer'];
+    behaviorTracking?: UniformCompositionProps['behaviorTracking'];
+};
+/**
+ * Gets the data of the closest `<UniformComposition />` ancestor.
+ */
+declare function useUniformCurrentComposition(): UniformCompositionContextValue;
+/**
+ * The main component to render a Canvas composition.
+ * It renders the full tree of components, and provides some services to the children, such as `useUniformCurrentComposition`.
+ * It also takes care of enabling [Contextual Editing](https://docs.uniform.app/capabilities/composition/contextual-editing).
+ */
+declare function UniformComposition<TRenderProps = unknown>({ data, behaviorTracking, children, resolveRenderer, contextualEditingEnhancer, }: UniformCompositionProps<TRenderProps>): JSX.Element;
+/** @deprecated use `useUniformCurrentComposition` instead */
+declare const useComposition: typeof useUniformCurrentComposition;
+/** @deprecated use `UniformComposition` instead */
+declare const Composition: typeof UniformComposition;
+/** @deprecated use `UniformCompositionProps` instead */
+type CompositionProps<TRenderProps = unknown> = UniformCompositionProps<TRenderProps>;
+
+type CustomSlotChildRenderFunc = (options: {
+    child: ReactNode;
+    component: ComponentInstance;
+    key: Key;
+}) => JSX.Element;
+type UniformSlotProps<TSlotNames extends string> = {
+    /** Name of the slot to render */
+    name: TSlotNames;
+    /**
+     * Function to resolve the React component to render for a given Canvas component type.
+     * If not specified, the resolveRenderer function on the nearest Layout will be used, if any.
+     */
+    resolveRenderer?: RenderComponentResolver;
+    /** Optional render props enables wrapping all child components in the slot with some markup */
+    children?: CustomSlotChildRenderFunc;
+    /**
+     * Optional ReactNode to use as a placeholder in Canvas editor when the slot is empty.
+     * The node is used to render a placeholder with realistic dimensions and it's never shown to users.
+     * Pass `null` to disable the placeholder.
+     */
+    emptyPlaceholder?: React$1.ReactNode;
+};
+/** Renders a named Slot within a Composition. */
+declare function UniformSlot<TSlotNames extends string = string>({ name, resolveRenderer, children, emptyPlaceholder, }: UniformSlotProps<TSlotNames>): JSX.Element | null;
+/** @deprecated use `UniformSlotProps` instead */
+type SlotProps<TSlotNames extends string> = UniformSlotProps<TSlotNames>;
+/** @deprecated use `UniformSlot` instead */
+declare const Slot: typeof UniformSlot;
+
+type UseCompositionEventEffectOptions = Omit<Partial<SubscribeToCompositionOptions>, 'callback'> & {
+    enabled: boolean;
+    effect: () => void;
+};
+/** Hook to manage a subscription to a realtime event on a composition */
+declare function useCompositionEventEffect({ enabled, projectId, compositionId, effect, }: UseCompositionEventEffectOptions): void;
+
 declare const componentStore: ComponentStore;
 declare const registerUniformComponent: ({ type, component, }: {
     type: string | string[];
@@ -260,4 +303,4 @@ declare const createComponentStoreResolver: (options: {
     defaultComponent?: React.ComponentType<ComponentProps<any>>;
 }) => RenderComponentResolver;
 
-export { ComponentProps, ComponentStore, Composition, CompositionContext, CompositionProps, DefaultNotImplementedComponent, RenderComponentResolver, Slot, SlotProps, SystemRenderConfig, SystemRenderFunction, UseCompositionEventEffectOptions, componentStore, componentStoreResolver, createApiEnhancer, createComponentStore, createComponentStoreResolver, registerUniformComponent, useComposition, useCompositionEventEffect, useContextualEditing };
+export { ComponentProps, ComponentStore, Composition, CompositionProps, DefaultNotImplementedComponent, RenderComponentResolver, Slot, SlotProps, SystemRenderConfig, SystemRenderFunction, UniformComponent, UniformComponentContextValue, UniformComponentProps, UniformComposition, UniformCompositionProps, UniformSlot, UniformSlotProps, UseCompositionEventEffectOptions, UseUniformContextualEditingProps, componentStore, componentStoreResolver, createApiEnhancer, createComponentStore, createComponentStoreResolver, registerUniformComponent, useComposition, useCompositionEventEffect, useUniformContextualEditing, useUniformCurrentComponent, useUniformCurrentComposition };