@uniformdev/canvas-react 19.35.2 → 19.36.0

package/dist/index.d.mts

@@ -0,0 +1,394 @@
+import React$1, { Key, ReactNode, PropsWithChildren } from 'react';
+import * as _uniformdev_canvas from '@uniformdev/canvas';
+import { ComponentInstance, RootComponentInstance, UpdateCompositionMessage, getParameterAttributes as getParameterAttributes$1, SubscribeToCompositionOptions } from '@uniformdev/canvas';
+export { GetParameterAttributesProps, createUniformApiEnhancer } from '@uniformdev/canvas';
+import { RichTextNode } from '@uniformdev/richtext';
+
+/**
+ * Props passed to a Canvas component implementation.
+ * TProps is the Canvas component's parameters object after
+ * all enhancers have been applied.
+ */
+type ComponentProps<TProps = unknown> = TProps & {
+    component: ComponentInstance;
+};
+/**
+ * Function that maps a Canvas component instance to its React component to render it.
+ * The resolver would commonly inspect the `type` and possibly `variant` of the component to decide.
+ */
+type RenderComponentResolver = (component: ComponentInstance) => React.ComponentType<ComponentProps<any>> | null;
+/** Function that renders Canvas system internals */
+type SystemRenderFunction = (component: ComponentInstance, key: Key, renderChild: (component: ComponentInstance, key: Key) => JSX.Element | null) => JSX.Element | null;
+/** Configures rendering of system components (tests, pz) */
+type SystemRenderConfig = {
+    test: SystemRenderFunction;
+    personalization: SystemRenderFunction;
+};
+type ComponentStore = {
+    register: (options: {
+        type: string;
+        variantId?: string;
+        component: React.ComponentType<ComponentProps<any>>;
+    }) => void;
+    get: (type: string, variantId?: string) => React.ComponentType<ComponentProps<any>> | undefined;
+};
+
+/**
+ * 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): React$1.JSX.Element | null;
+
+type ParameterTextValue = string | undefined;
+type UniformTextProps = {
+    /**
+     * The name of the  HTML tag to render.
+     * @default "span"
+     */
+    as?: React$1.ElementType;
+    /** The ID of the parameter. */
+    parameterId: string;
+    /**
+     * When set to true, it adds `whiteSpace: 'pre-wrap'` to the styles of the root element to allow the rendering of line breaks.
+     * @default false
+     */
+    isMultiline?: boolean;
+    /**
+     * Sets the value to show in Canvas editor when the parameter value is empty.
+     * Can be a static string, or a function to generate the placeholder out of parameter info.
+     * @default undefined
+     */
+    placeholder?: string | ((parameter: {
+        id: string;
+    }) => string | undefined);
+    /**
+     * A function to customize the rendering of the parameter value. Useful to format the value before rendering it.
+     * @default "(value) => value"
+     */
+    render?: (value: ParameterTextValue) => React$1.ReactNode;
+} & Omit<React$1.HTMLAttributes<HTMLSpanElement>, 'children' | 'placeholder'>;
+/**
+ * Renders text parameters. Offers inline editing capability out of the box.
+ */
+declare const UniformText: ({ as: Tag, parameterId, isMultiline, placeholder, render, ...props }: UniformTextProps) => React$1.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;
+    /** 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 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 component mounts, regardless of viewport.
+     *
+     * 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';
+    /**
+     * The default placeholder to pass to the parameter component that support inline editing (such as UniformText).
+     */
+    contextualEditingDefaultPlaceholder?: UniformTextProps['placeholder'];
+};
+type UniformComponentContextValue = {
+    data?: UniformComponentProps['data'];
+    resolveRenderer?: UniformComponentProps['resolveRenderer'];
+    behaviorTracking?: UniformComponentProps['behaviorTracking'];
+    contextualEditingDefaultPlaceholder?: UniformComponentProps['contextualEditingDefaultPlaceholder'];
+};
+/**
+ * Gets the data of the closest `<UniformComponent />` ancestor.
+ */
+declare function useUniformCurrentComponent(): UniformComponentContextValue;
+/**
+ * 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 `<UniformSlot />`, 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, contextualEditingDefaultPlaceholder, }: UniformComponentProps<TRenderProps>): React$1.JSX.Element | null;
+
+type UseUniformContextualEditingProps = {
+    initialCompositionValue?: RootComponentInstance;
+    /**
+     * 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, hash, }: Pick<UpdateCompositionMessage, 'composition' | 'hash'>) => 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?: {
+            [key: string]: {
+                value: unknown;
+                type: string;
+                connectedData?: {
+                    pointer: string;
+                    syntax: "jptr";
+                } | undefined;
+            };
+        } | undefined;
+        variant?: string | undefined;
+        projectMapNodes?: {
+            id: string;
+            path: string;
+            projectMapId: string;
+        }[] | undefined;
+        slots?: {
+            [key: string]: {
+                type: string;
+                parameters?: {
+                    [key: string]: {
+                        value: unknown;
+                        type: string;
+                        connectedData?: {
+                            pointer: string;
+                            syntax: "jptr";
+                        } | undefined;
+                    };
+                } | undefined;
+                variant?: string | undefined;
+                slots?: {
+                    [key: string]: any[];
+                } | undefined;
+                _id?: string | undefined;
+                _pattern?: string | undefined;
+                _dataResources?: {
+                    [key: string]: {
+                        type: string;
+                        isPatternParameter?: boolean | undefined;
+                        ignorePatternParameterDefault?: boolean | undefined;
+                        variables?: {
+                            [key: string]: string;
+                        } | undefined;
+                    };
+                } | undefined;
+                _patternDataResources?: {
+                    [key: string]: {
+                        type: string;
+                        isPatternParameter?: boolean | undefined;
+                        ignorePatternParameterDefault?: boolean | undefined;
+                        variables?: {
+                            [key: string]: string;
+                        } | undefined;
+                    };
+                } | undefined;
+                _patternError?: "NOTFOUND" | "CYCLIC" | undefined;
+                _overrides?: {
+                    [key: string]: {
+                        parameters?: {
+                            [key: string]: {
+                                value: unknown;
+                                type: string;
+                                connectedData?: {
+                                    pointer: string;
+                                    syntax: "jptr";
+                                } | undefined;
+                            };
+                        } | undefined;
+                        variant?: string | undefined;
+                    };
+                } | undefined;
+                _overridability?: {
+                    parameters?: {
+                        [key: string]: "yes" | "no";
+                    } | undefined;
+                    variants?: boolean | undefined;
+                } | undefined;
+            }[];
+        } | undefined;
+        _id: string;
+        _slug?: string | null | undefined;
+        _name: string;
+        _dataResources?: {
+            [key: string]: {
+                type: string;
+                isPatternParameter?: boolean | undefined;
+                ignorePatternParameterDefault?: boolean | undefined;
+                variables?: {
+                    [key: string]: string;
+                } | undefined;
+            };
+        } | undefined;
+        _overrides?: {
+            [key: string]: {
+                parameters?: {
+                    [key: string]: {
+                        value: unknown;
+                        type: string;
+                        connectedData?: {
+                            pointer: string;
+                            syntax: "jptr";
+                        } | undefined;
+                    };
+                } | undefined;
+                variant?: string | undefined;
+            };
+        } | undefined;
+        _overridability?: {
+            parameters?: {
+                [key: string]: "yes" | "no";
+            } | undefined;
+            variants?: boolean | undefined;
+        } | undefined;
+    } | undefined;
+    isContextualEditing: boolean;
+};
+
+type UniformCompositionProps<TRenderProps = unknown> = UniformComponentProps<TRenderProps> & {
+    /** The composition data */
+    data?: RootComponentInstance;
+    contextualEditingEnhancer?: UseUniformContextualEditingProps['enhance'];
+};
+type UniformCompositionContextValue = {
+    data: UniformCompositionProps['data'] | undefined;
+    resolveRenderer?: UniformCompositionProps['resolveRenderer'];
+    behaviorTracking?: UniformCompositionProps['behaviorTracking'];
+    isContextualEditing: boolean;
+};
+/**
+ * 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, contextualEditingDefaultPlaceholder, }: UniformCompositionProps<TRenderProps>): React$1.JSX.Element;
+
+type RichTextComponentProps<TNode extends RichTextNode = RichTextNode> = {
+    node: TNode;
+};
+type RichTextRendererComponent<TNode extends RichTextNode = RichTextNode> = React$1.ComponentType<PropsWithChildren<RichTextComponentProps<TNode>>>;
+/**
+ * Function that maps a Rich Text node instance to its React component to render it.
+ * The resolver would commonly inspect the `type` of the component to decide.
+ */
+type RenderRichTextComponentResolver = (node: RichTextNode) => RichTextRendererComponent | null | undefined;
+
+type UniformRichTextProps = {
+    /**
+     * The name of the  HTML tag to render.
+     * @default "div"
+     */
+    as?: React$1.ElementType;
+    /** The ID of the parameter. */
+    parameterId: string;
+    /**
+     * A function which can provide a custom react component
+     * for rendering a rich text node
+     */
+    resolveRichTextRenderer?: RenderRichTextComponentResolver;
+} & Omit<React$1.HTMLAttributes<HTMLDivElement>, 'children'>;
+/**
+ * Adds rendering support for Uniform Rich Text parameters
+ */
+declare const UniformRichText: React$1.ForwardRefExoticComponent<{
+    /**
+     * The name of the  HTML tag to render.
+     * @default "div"
+     */
+    as?: React$1.ElementType<any> | undefined;
+    /** The ID of the parameter. */
+    parameterId: string;
+    /**
+     * A function which can provide a custom react component
+     * for rendering a rich text node
+     */
+    resolveRichTextRenderer?: RenderRichTextComponentResolver | undefined;
+} & Omit<React$1.HTMLAttributes<HTMLDivElement>, "children"> & React$1.RefAttributes<unknown>>;
+
+type UniformRichTextNodeProps = {
+    node: RichTextNode;
+    resolveRichTextRenderer?: RenderRichTextComponentResolver;
+};
+/**
+ * Render a single RichText node
+ */
+declare function UniformRichTextNode({ node, ...props }: UniformRichTextNodeProps): React$1.JSX.Element | null;
+
+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;
+
+/**
+ * Returns the attributes needed to annotate a Uniform parameter for inline editing.
+ * Supports only text parameters at the moment.
+ */
+declare const getParameterAttributes: typeof getParameterAttributes$1;
+
+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;
+
+type UseUniformContextualEditingStateProps = {
+    /**
+     * When set to true, the hook will return the global contextual state no matter where its used.
+     * When set to false, it will return only the state relevant to the current component (determined using `useUniformCurrentComponent`).
+     * @default false
+     **/
+    global?: boolean;
+};
+/**
+ * Returns the state of contextual editing, when the app is open inside Canvas Editor.
+ * This hook can be used to improve the editing experience of your team.
+ * For example: You can use `selectedComponentReference` to control which element to show inside a carousel or an accordion.
+ */
+declare const useUniformContextualEditingState: ({ global, }?: UseUniformContextualEditingStateProps) => {
+    isContextualEditing: boolean;
+    selectedComponentReference: Omit<_uniformdev_canvas.ContextualEditingComponentReference, "elements"> | undefined;
+};
+
+declare const componentStore: ComponentStore;
+declare const registerUniformComponent: ({ type, variantId, component, }: {
+    type: string;
+    variantId?: string | undefined;
+    component: React.ComponentType<ComponentProps<any>>;
+}) => void;
+declare const componentStoreResolver: RenderComponentResolver;
+
+/** Can be used to override default component Not Implemented fallback */
+declare const NOT_IMPLEMENTED_COMPONENT = "__not_implemented__";
+declare const createComponentStore: () => ComponentStore;
+declare const createComponentStoreResolver: (options: {
+    store: ComponentStore;
+    defaultComponent?: React$1.ComponentType<ComponentProps<any>>;
+}) => RenderComponentResolver;
+
+export { ComponentProps, ComponentStore, DefaultNotImplementedComponent, NOT_IMPLEMENTED_COMPONENT, RenderComponentResolver, RenderRichTextComponentResolver, RichTextComponentProps, RichTextRendererComponent, SystemRenderConfig, SystemRenderFunction, UniformComponent, UniformComponentContextValue, UniformComponentProps, UniformComposition, UniformCompositionProps, UniformRichText, UniformRichTextNode, UniformRichTextNodeProps, UniformRichTextProps, UniformSlot, UniformSlotProps, UniformText, UniformTextProps, UseCompositionEventEffectOptions, UseUniformContextualEditingProps, UseUniformContextualEditingStateProps, componentStore, componentStoreResolver, createComponentStore, createComponentStoreResolver, getParameterAttributes, registerUniformComponent, useCompositionEventEffect, useUniformContextualEditing, useUniformContextualEditingState, useUniformCurrentComponent, useUniformCurrentComposition };

package/dist/index.d.ts

@@ -70,9 +70,8 @@ type UniformTextProps = {
     render?: (value: ParameterTextValue) => React$1.ReactNode;
 } & Omit<React$1.HTMLAttributes<HTMLSpanElement>, 'children' | 'placeholder'>;
 /**
- * Adds inline editing capability to text parameters
- * @deprecated This component is unstable, and not ready for production usage.
- **/
+ * Renders text parameters. Offers inline editing capability out of the box.
+ */
 declare const UniformText: ({ as: Tag, parameterId, isMultiline, placeholder, render, ...props }: UniformTextProps) => React$1.JSX.Element | null;
 
 type UniformComponentProps<TRenderProps = unknown> = {
@@ -348,8 +347,7 @@ declare function UniformSlot<TSlotNames extends string = string>({ name, resolve
 /**
  * Returns the attributes needed to annotate a Uniform parameter for inline editing.
  * Supports only text parameters at the moment.
- * @deprecated Unstable, and not ready for production usage.
- **/
+ */
 declare const getParameterAttributes: typeof getParameterAttributes$1;
 
 type UseCompositionEventEffectOptions = Omit<Partial<SubscribeToCompositionOptions>, 'callback'> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniformdev/canvas-react",
-  "version": "19.35.2",
+  "version": "19.36.0",
   "description": "React SDK for Uniform Canvas",
   "license": "SEE LICENSE IN LICENSE.txt",
   "main": "./dist/index.js",
@@ -24,10 +24,10 @@
     "document": "api-extractor run --local"
   },
   "dependencies": {
-    "@uniformdev/canvas": "19.35.2",
-    "@uniformdev/context": "19.35.2",
-    "@uniformdev/context-react": "19.35.2",
-    "@uniformdev/richtext": "19.35.2"
+    "@uniformdev/canvas": "19.36.0",
+    "@uniformdev/context": "19.36.0",
+    "@uniformdev/context-react": "19.36.0",
+    "@uniformdev/richtext": "19.36.0"
   },
   "peerDependencies": {
     "react": ">= 16 || 17 || 18",
@@ -44,5 +44,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "64d3270175087c87cfaa29a283aa4a7b0a98fd2c"
+  "gitHead": "3ae246a7f0f39adeaf04ecba4c7e48c478c019ad"
 }