@unlayer/react-elements 0.1.21 → 0.2.0

package/dist/index.d.cts

@@ -16,6 +16,8 @@ import { MenuValues } from '@unlayer/types/tools/menu';
 export { MenuValues } from '@unlayer/types/tools/menu';
 import { ParagraphValues } from '@unlayer/types/tools/paragraph';
 export { ParagraphValues } from '@unlayer/types/tools/paragraph';
+import { PageBreakValues } from '@unlayer/types/tools/page-break';
+export { PageBreakValues } from '@unlayer/types/tools/page-break';
 import { SocialValues } from '@unlayer/types/tools/social';
 export { SocialValues } from '@unlayer/types/tools/social';
 import { TableValues } from '@unlayer/types/tools/table';
@@ -140,6 +142,24 @@ interface DesignJSON {
     body: DesignBody;
     schemaVersion: number;
 }
+/** Phone settings use the same flat CSS inputs as desktop props. */
+interface MobileProps {
+    padding?: number | string;
+    containerPadding?: number | string;
+    fontSize?: number | string;
+    lineHeight?: number | string;
+    textAlign?: TextAlign;
+    width?: number | string;
+    maxWidth?: number | string;
+    autoWidth?: boolean;
+    /** Column border on this device (per side, as the desktop `border`). */
+    border?: Partial<Record<`border${"Top" | "Right" | "Bottom" | "Left"}${"Width" | "Style" | "Color"}`, number | string>>;
+}
+interface DeviceProps {
+    mobile?: MobileProps;
+    hideOnMobile?: boolean;
+    hideOnDesktop?: boolean;
+}
 
 interface HeadConfig {
     hasFeature?: (featureName: string) => boolean;
@@ -222,6 +242,7 @@ declare function htmlToTextJson(html: string): string;
  * - Users can pass: { color: "red", backgroundColor: "blue" } OR { buttonColors: { color: "red" } }
  * - TypeScript provides autocomplete for ALL properties (flat and nested)
  */
+
 /**
  * Type utility: Extracts all properties from nested objects
  * This provides TypeScript autocomplete for flat props!
@@ -235,7 +256,7 @@ type FlattenObjectProps<T> = T extends object ? {
  * Semantic props type for any component.
  * Generic TChildren parameter allows each framework to supply its own child type.
  */
-type SemanticProps$1<T, TChildren = any> = FlattenObjectProps<T> & {
+type SemanticProps$1<T, TChildren = any> = Omit<FlattenObjectProps<T>, keyof DeviceProps> & DeviceProps & {
     children?: TChildren;
     values?: T;
     /** HTML string with inline formatting for Paragraph (e.g. `'Hello <b>bold</b>'`) */
@@ -305,7 +326,7 @@ type ImageSrcInput = string | {
 /**
  * Base props that all item components support
  */
-interface BaseItemComponentProps {
+interface BaseItemComponentProps extends DeviceProps {
     children?: React__default.ReactNode;
     className?: string;
     style?: React__default.CSSProperties;
@@ -330,7 +351,7 @@ interface BaseItemComponentProps {
 /**
  * Props type that combines base props with semantic props
  */
-type ItemComponentProps<TSemanticProps> = BaseItemComponentProps & TSemanticProps;
+type ItemComponentProps<TSemanticProps> = BaseItemComponentProps & Omit<TSemanticProps, keyof DeviceProps>;
 
 /**
  * React Semantic Props
@@ -592,6 +613,15 @@ interface ParagraphProps extends ItemComponentProps<ParagraphSemanticProps> {
  */
 declare const Paragraph: React$1.FC<ItemComponentProps<ParagraphSemanticProps>>;
 
+type PageBreakProps = ItemComponentProps<SemanticProps<PageBreakValues>>;
+/**
+ * PageBreak - Forces subsequent document content onto a new PDF page.
+ *
+ * Page breaks render only in document mode. In email and web output they are
+ * intentionally inert.
+ */
+declare const PageBreak: React$1.FC<ItemComponentProps<SemanticProps<PageBreakValues>>>;
+
 type SocialSemanticProps = Omit<SemanticProps<SocialValues>, "iconSize" | "spacing"> & {
     /** Social icons shorthand (array of {name, url}) */
     icons?: SocialIcon[];
@@ -694,7 +724,7 @@ interface VideoProps extends ItemComponentProps<SemanticProps<VideoValues>> {
  */
 declare const Video: React$1.FC<ItemComponentProps<VideoSemanticProps>>;
 
-type RowProps = Omit<SemanticProps<RowValues>, "padding"> & {
+type RowProps = Omit<SemanticProps<RowValues>, "padding" | keyof DeviceProps> & DeviceProps & {
     children?: React__default.ReactNode;
     layout?: ColumnLayout;
     cells?: number[];
@@ -711,7 +741,7 @@ type RowProps = Omit<SemanticProps<RowValues>, "padding"> & {
 };
 declare const Row: React__default.FC<RowProps>;
 
-type ColumnProps = Omit<SemanticProps<ColumnValues>, "padding" | "border" | "borderRadius"> & {
+type ColumnProps = Omit<SemanticProps<ColumnValues>, "padding" | "border" | "borderRadius" | keyof DeviceProps> & Omit<DeviceProps, "hideOnMobile" | "hideOnDesktop"> & {
     children?: React__default.ReactNode;
     index?: number;
     cells?: number[];
@@ -742,6 +772,17 @@ type BodyProps = Omit<SemanticProps<BodyValues>, "padding" | "borderRadius"> & {
     config?: Partial<UnlayerConfig>;
     /** Preview text shown in email client inboxes (email mode only) */
     previewText?: string;
+    /** Document text direction, also kept in the design JSON. Renderer options can override it. */
+    textDirection?: string;
+    /** Language of the rendered document (for example, "ar"). */
+    lang?: string;
+    /**
+     * Web font stylesheets the content uses (e.g. a Google Fonts CSS URL).
+     * renderToHtml links them in the document head, with any `fonts` option.
+     */
+    fonts?: Array<{
+        url: string;
+    }>;
     /** Padding — a CSS string ("0 48px", "20px") or a number (px). */
     padding?: SizeInput;
     /** Corner radius — a number (→ px) or CSS string ("8px"). */
@@ -806,7 +847,12 @@ declare namespace Page {
     var displayName: string;
 }
 
-type DocumentProps = Omit<BodyProps, "mode">;
+type DocumentPageSize = "A3" | "A4" | "A5" | "Legal" | "Letter" | "Tabloid";
+type DocumentOrientation = "portrait" | "landscape";
+type DocumentProps = Omit<BodyProps, "mode" | "documentSize" | "documentOrientation" | "documentMargin"> & {
+    documentSize?: DocumentPageSize;
+    documentOrientation?: DocumentOrientation;
+};
 /**
  * Document - Print-optimized rendering for PDF generation.
  *
@@ -814,7 +860,12 @@ type DocumentProps = Omit<BodyProps, "mode">;
  *
  * @example
  * ```tsx
- * <Document backgroundColor="#ffffff" contentWidth="700px">
+ * <Document
+ *   backgroundColor="#ffffff"
+ *   contentWidth="700px"
+ *   documentSize="A4"
+ *   documentOrientation="portrait"
+ * >
  *   <Row><Column><Paragraph text="Hello" /></Column></Row>
  * </Document>
  * ```
@@ -835,6 +886,8 @@ declare function useUnlayerConfig(): UnlayerConfig;
  * Options for renderToHtml — config overrides plus document-level extras.
  */
 interface RenderToHtmlOptions extends Partial<UnlayerConfig> {
+    /** Document language; overrides the root's `lang` prop. */
+    lang?: string;
     /** Document `<title>` */
     title?: string;
     /**
@@ -859,7 +912,11 @@ interface RenderToHtmlOptions extends Partial<UnlayerConfig> {
  * Use {@link renderToHtmlParts} instead when your app owns the document
  * shell and only needs the head/body chunks.
  *
- * @param element - A React element tree (e.g. `<Email><Row>...</Row></Email>`)
+ * @param element - A React element tree (e.g. `<Email><Row>...</Row></Email>`), or a
+ *   template component that returns one (`<Welcome name="Ada" />`, also `memo`/`forwardRef`).
+ *   A template is called in a render of its own to reach its root (its hooks work); a class
+ *   component, or one that doesn't return an element, renders without its root's settings,
+ *   with a warning.
  * @param options - Config overrides (mode, cdnBaseUrl, etc.) plus `title` and `fonts`
  * @returns Complete HTML document string
  * @throws {Error} If rendering fails, with a helpful message
@@ -1095,8 +1152,11 @@ interface ElementsToolConfig {
     /** Editor-only fields (label, icon, options, validator, ...) — ignored */
     [editorOnly: string]: unknown;
 }
-/** Props: the tool's values as flat props, plus a `values` escape hatch. */
-type ElementsToolProps = BaseItemComponentProps & Record<string, any> & {
+/**
+ * Props: the tool's values as flat props, plus a `values` escape hatch. Every prop is the tool's own, as in 0.1.22:
+ * a `mobile` or `hideOnMobile` value isn't a device setting (`values._override` sets those).
+ */
+type ElementsToolProps = Omit<BaseItemComponentProps, keyof DeviceProps> & Record<string, any> & {
     values?: Record<string, any>;
 };
 /**
@@ -1126,4 +1186,4 @@ declare function registerTool(tool: ElementsToolConfig): React__default.FC<Eleme
 /** Alias of {@link registerTool}. */
 declare const registerElementsTool: typeof registerTool;
 
-export { Body, type BorderInput, Button, type ButtonProps, Column, type ColumnLayout, ColumnLayouts, DEFAULT_CONFIG, type DesignBody, type DesignColumn, type DesignContent, type DesignJSON, type DesignRow, Divider, type DividerProps, Document, type DocumentProps, type ElementsToolConfig, type ElementsToolProps, Email, type EmailProps, type FontFamilyInput, type FontWeightInput, Heading, type HeadingLevel, type HeadingProps, type Href, Html, type HtmlParts, type HtmlProps, type Icons, Image, type ImageProps, type ImageSrcInput, type LinkStyle, Menu, type MenuItem, type MenuProps, Page, type PageProps, Paragraph, type ParagraphProps, type RenderToHtmlOptions, Row, type RowProps, type SizeInput, Social, type SocialIcon, type SocialProps, Table, type TableProps, type TextAlign, type TextStyleProps, type ToolExporter, type UnlayerConfig, UnlayerProvider, type UnlayerProviderProps, type ValidColumnLayout, Video, type VideoProps, type VideoSource, htmlToTextJson, registerElementsTool, registerTool, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };
+export { Body, type BorderInput, Button, type ButtonProps, Column, type ColumnLayout, ColumnLayouts, DEFAULT_CONFIG, type DesignBody, type DesignColumn, type DesignContent, type DesignJSON, type DesignRow, type DeviceProps, Divider, type DividerProps, Document, type DocumentOrientation, type DocumentPageSize, type DocumentProps, type ElementsToolConfig, type ElementsToolProps, Email, type EmailProps, type FontFamilyInput, type FontWeightInput, Heading, type HeadingLevel, type HeadingProps, type Href, Html, type HtmlParts, type HtmlProps, type Icons, Image, type ImageProps, type ImageSrcInput, type LinkStyle, Menu, type MenuItem, type MenuProps, type MobileProps, Page, PageBreak, type PageBreakProps, type PageProps, Paragraph, type ParagraphProps, type RenderToHtmlOptions, Row, type RowProps, type SizeInput, Social, type SocialIcon, type SocialProps, Table, type TableProps, type TextAlign, type TextStyleProps, type ToolExporter, type UnlayerConfig, UnlayerProvider, type UnlayerProviderProps, type ValidColumnLayout, Video, type VideoProps, type VideoSource, htmlToTextJson, registerElementsTool, registerTool, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };

package/dist/index.d.ts

@@ -16,6 +16,8 @@ import { MenuValues } from '@unlayer/types/tools/menu';
 export { MenuValues } from '@unlayer/types/tools/menu';
 import { ParagraphValues } from '@unlayer/types/tools/paragraph';
 export { ParagraphValues } from '@unlayer/types/tools/paragraph';
+import { PageBreakValues } from '@unlayer/types/tools/page-break';
+export { PageBreakValues } from '@unlayer/types/tools/page-break';
 import { SocialValues } from '@unlayer/types/tools/social';
 export { SocialValues } from '@unlayer/types/tools/social';
 import { TableValues } from '@unlayer/types/tools/table';
@@ -140,6 +142,24 @@ interface DesignJSON {
     body: DesignBody;
     schemaVersion: number;
 }
+/** Phone settings use the same flat CSS inputs as desktop props. */
+interface MobileProps {
+    padding?: number | string;
+    containerPadding?: number | string;
+    fontSize?: number | string;
+    lineHeight?: number | string;
+    textAlign?: TextAlign;
+    width?: number | string;
+    maxWidth?: number | string;
+    autoWidth?: boolean;
+    /** Column border on this device (per side, as the desktop `border`). */
+    border?: Partial<Record<`border${"Top" | "Right" | "Bottom" | "Left"}${"Width" | "Style" | "Color"}`, number | string>>;
+}
+interface DeviceProps {
+    mobile?: MobileProps;
+    hideOnMobile?: boolean;
+    hideOnDesktop?: boolean;
+}
 
 interface HeadConfig {
     hasFeature?: (featureName: string) => boolean;
@@ -222,6 +242,7 @@ declare function htmlToTextJson(html: string): string;
  * - Users can pass: { color: "red", backgroundColor: "blue" } OR { buttonColors: { color: "red" } }
  * - TypeScript provides autocomplete for ALL properties (flat and nested)
  */
+
 /**
  * Type utility: Extracts all properties from nested objects
  * This provides TypeScript autocomplete for flat props!
@@ -235,7 +256,7 @@ type FlattenObjectProps<T> = T extends object ? {
  * Semantic props type for any component.
  * Generic TChildren parameter allows each framework to supply its own child type.
  */
-type SemanticProps$1<T, TChildren = any> = FlattenObjectProps<T> & {
+type SemanticProps$1<T, TChildren = any> = Omit<FlattenObjectProps<T>, keyof DeviceProps> & DeviceProps & {
     children?: TChildren;
     values?: T;
     /** HTML string with inline formatting for Paragraph (e.g. `'Hello <b>bold</b>'`) */
@@ -305,7 +326,7 @@ type ImageSrcInput = string | {
 /**
  * Base props that all item components support
  */
-interface BaseItemComponentProps {
+interface BaseItemComponentProps extends DeviceProps {
     children?: React__default.ReactNode;
     className?: string;
     style?: React__default.CSSProperties;
@@ -330,7 +351,7 @@ interface BaseItemComponentProps {
 /**
  * Props type that combines base props with semantic props
  */
-type ItemComponentProps<TSemanticProps> = BaseItemComponentProps & TSemanticProps;
+type ItemComponentProps<TSemanticProps> = BaseItemComponentProps & Omit<TSemanticProps, keyof DeviceProps>;
 
 /**
  * React Semantic Props
@@ -592,6 +613,15 @@ interface ParagraphProps extends ItemComponentProps<ParagraphSemanticProps> {
  */
 declare const Paragraph: React$1.FC<ItemComponentProps<ParagraphSemanticProps>>;
 
+type PageBreakProps = ItemComponentProps<SemanticProps<PageBreakValues>>;
+/**
+ * PageBreak - Forces subsequent document content onto a new PDF page.
+ *
+ * Page breaks render only in document mode. In email and web output they are
+ * intentionally inert.
+ */
+declare const PageBreak: React$1.FC<ItemComponentProps<SemanticProps<PageBreakValues>>>;
+
 type SocialSemanticProps = Omit<SemanticProps<SocialValues>, "iconSize" | "spacing"> & {
     /** Social icons shorthand (array of {name, url}) */
     icons?: SocialIcon[];
@@ -694,7 +724,7 @@ interface VideoProps extends ItemComponentProps<SemanticProps<VideoValues>> {
  */
 declare const Video: React$1.FC<ItemComponentProps<VideoSemanticProps>>;
 
-type RowProps = Omit<SemanticProps<RowValues>, "padding"> & {
+type RowProps = Omit<SemanticProps<RowValues>, "padding" | keyof DeviceProps> & DeviceProps & {
     children?: React__default.ReactNode;
     layout?: ColumnLayout;
     cells?: number[];
@@ -711,7 +741,7 @@ type RowProps = Omit<SemanticProps<RowValues>, "padding"> & {
 };
 declare const Row: React__default.FC<RowProps>;
 
-type ColumnProps = Omit<SemanticProps<ColumnValues>, "padding" | "border" | "borderRadius"> & {
+type ColumnProps = Omit<SemanticProps<ColumnValues>, "padding" | "border" | "borderRadius" | keyof DeviceProps> & Omit<DeviceProps, "hideOnMobile" | "hideOnDesktop"> & {
     children?: React__default.ReactNode;
     index?: number;
     cells?: number[];
@@ -742,6 +772,17 @@ type BodyProps = Omit<SemanticProps<BodyValues>, "padding" | "borderRadius"> & {
     config?: Partial<UnlayerConfig>;
     /** Preview text shown in email client inboxes (email mode only) */
     previewText?: string;
+    /** Document text direction, also kept in the design JSON. Renderer options can override it. */
+    textDirection?: string;
+    /** Language of the rendered document (for example, "ar"). */
+    lang?: string;
+    /**
+     * Web font stylesheets the content uses (e.g. a Google Fonts CSS URL).
+     * renderToHtml links them in the document head, with any `fonts` option.
+     */
+    fonts?: Array<{
+        url: string;
+    }>;
     /** Padding — a CSS string ("0 48px", "20px") or a number (px). */
     padding?: SizeInput;
     /** Corner radius — a number (→ px) or CSS string ("8px"). */
@@ -806,7 +847,12 @@ declare namespace Page {
     var displayName: string;
 }
 
-type DocumentProps = Omit<BodyProps, "mode">;
+type DocumentPageSize = "A3" | "A4" | "A5" | "Legal" | "Letter" | "Tabloid";
+type DocumentOrientation = "portrait" | "landscape";
+type DocumentProps = Omit<BodyProps, "mode" | "documentSize" | "documentOrientation" | "documentMargin"> & {
+    documentSize?: DocumentPageSize;
+    documentOrientation?: DocumentOrientation;
+};
 /**
  * Document - Print-optimized rendering for PDF generation.
  *
@@ -814,7 +860,12 @@ type DocumentProps = Omit<BodyProps, "mode">;
  *
  * @example
  * ```tsx
- * <Document backgroundColor="#ffffff" contentWidth="700px">
+ * <Document
+ *   backgroundColor="#ffffff"
+ *   contentWidth="700px"
+ *   documentSize="A4"
+ *   documentOrientation="portrait"
+ * >
  *   <Row><Column><Paragraph text="Hello" /></Column></Row>
  * </Document>
  * ```
@@ -835,6 +886,8 @@ declare function useUnlayerConfig(): UnlayerConfig;
  * Options for renderToHtml — config overrides plus document-level extras.
  */
 interface RenderToHtmlOptions extends Partial<UnlayerConfig> {
+    /** Document language; overrides the root's `lang` prop. */
+    lang?: string;
     /** Document `<title>` */
     title?: string;
     /**
@@ -859,7 +912,11 @@ interface RenderToHtmlOptions extends Partial<UnlayerConfig> {
  * Use {@link renderToHtmlParts} instead when your app owns the document
  * shell and only needs the head/body chunks.
  *
- * @param element - A React element tree (e.g. `<Email><Row>...</Row></Email>`)
+ * @param element - A React element tree (e.g. `<Email><Row>...</Row></Email>`), or a
+ *   template component that returns one (`<Welcome name="Ada" />`, also `memo`/`forwardRef`).
+ *   A template is called in a render of its own to reach its root (its hooks work); a class
+ *   component, or one that doesn't return an element, renders without its root's settings,
+ *   with a warning.
  * @param options - Config overrides (mode, cdnBaseUrl, etc.) plus `title` and `fonts`
  * @returns Complete HTML document string
  * @throws {Error} If rendering fails, with a helpful message
@@ -1095,8 +1152,11 @@ interface ElementsToolConfig {
     /** Editor-only fields (label, icon, options, validator, ...) — ignored */
     [editorOnly: string]: unknown;
 }
-/** Props: the tool's values as flat props, plus a `values` escape hatch. */
-type ElementsToolProps = BaseItemComponentProps & Record<string, any> & {
+/**
+ * Props: the tool's values as flat props, plus a `values` escape hatch. Every prop is the tool's own, as in 0.1.22:
+ * a `mobile` or `hideOnMobile` value isn't a device setting (`values._override` sets those).
+ */
+type ElementsToolProps = Omit<BaseItemComponentProps, keyof DeviceProps> & Record<string, any> & {
     values?: Record<string, any>;
 };
 /**
@@ -1126,4 +1186,4 @@ declare function registerTool(tool: ElementsToolConfig): React__default.FC<Eleme
 /** Alias of {@link registerTool}. */
 declare const registerElementsTool: typeof registerTool;
 
-export { Body, type BorderInput, Button, type ButtonProps, Column, type ColumnLayout, ColumnLayouts, DEFAULT_CONFIG, type DesignBody, type DesignColumn, type DesignContent, type DesignJSON, type DesignRow, Divider, type DividerProps, Document, type DocumentProps, type ElementsToolConfig, type ElementsToolProps, Email, type EmailProps, type FontFamilyInput, type FontWeightInput, Heading, type HeadingLevel, type HeadingProps, type Href, Html, type HtmlParts, type HtmlProps, type Icons, Image, type ImageProps, type ImageSrcInput, type LinkStyle, Menu, type MenuItem, type MenuProps, Page, type PageProps, Paragraph, type ParagraphProps, type RenderToHtmlOptions, Row, type RowProps, type SizeInput, Social, type SocialIcon, type SocialProps, Table, type TableProps, type TextAlign, type TextStyleProps, type ToolExporter, type UnlayerConfig, UnlayerProvider, type UnlayerProviderProps, type ValidColumnLayout, Video, type VideoProps, type VideoSource, htmlToTextJson, registerElementsTool, registerTool, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };
+export { Body, type BorderInput, Button, type ButtonProps, Column, type ColumnLayout, ColumnLayouts, DEFAULT_CONFIG, type DesignBody, type DesignColumn, type DesignContent, type DesignJSON, type DesignRow, type DeviceProps, Divider, type DividerProps, Document, type DocumentOrientation, type DocumentPageSize, type DocumentProps, type ElementsToolConfig, type ElementsToolProps, Email, type EmailProps, type FontFamilyInput, type FontWeightInput, Heading, type HeadingLevel, type HeadingProps, type Href, Html, type HtmlParts, type HtmlProps, type Icons, Image, type ImageProps, type ImageSrcInput, type LinkStyle, Menu, type MenuItem, type MenuProps, type MobileProps, Page, PageBreak, type PageBreakProps, type PageProps, Paragraph, type ParagraphProps, type RenderToHtmlOptions, Row, type RowProps, type SizeInput, Social, type SocialIcon, type SocialProps, Table, type TableProps, type TextAlign, type TextStyleProps, type ToolExporter, type UnlayerConfig, UnlayerProvider, type UnlayerProviderProps, type ValidColumnLayout, Video, type VideoProps, type VideoSource, htmlToTextJson, registerElementsTool, registerTool, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };