@unlayer/react-elements 0.1.9 → 0.1.11

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 import * as React$1 from 'react';
 import React__default from 'react';
+import { ColumnValues } from '@unlayer/types/containers/column';
+export { ColumnValues } from '@unlayer/types/containers/column';
 import { ButtonValues } from '@unlayer/types/tools/button';
 export { ButtonValues } from '@unlayer/types/tools/button';
 import { DividerValues } from '@unlayer/types/tools/divider';
@@ -22,8 +24,6 @@ import { VideoValues } from '@unlayer/types/tools/video';
 export { VideoValues } from '@unlayer/types/tools/video';
 import { RowValues } from '@unlayer/types/containers/row';
 export { RowValues } from '@unlayer/types/containers/row';
-import { ColumnValues } from '@unlayer/types/containers/column';
-export { ColumnValues } from '@unlayer/types/containers/column';
 import { BodyValues } from '@unlayer/types/containers/body';
 export { BodyValues } from '@unlayer/types/containers/body';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -243,58 +243,53 @@ type SemanticProps$1<T, TChildren = any> = FlattenObjectProps<T> & {
 /**
  * Type Definitions
  *
- * Re-exports shared types from @unlayer-internal/shared-elements
- * and defines React-specific component prop types.
+ * Re-exports the canonical value types from @unlayer-internal/shared-elements
+ * and defines the agent-friendly input types components build their props from.
+ *
+ * Each component's prop type (ButtonProps, HeadingProps, …) lives next to its
+ * component — these are just the shared building blocks they share.
  */
 
+/** fontFamily accepts a ready stack object or a bare family-name string. */
+type FontFamilyInput = {
+    label: string;
+    value: string;
+} | string;
+/** fontWeight accepts a number, a numeric string, or a CSS keyword. */
+type FontWeightInput = number | `${number}` | "normal" | "bold" | "lighter" | "bolder";
+/** A CSS size: a number (treated as px) or a string ("24px", "50%", "1.5em"). */
+type SizeInput = number | (string & {});
 /**
- * Public props for item components.
- * Includes semantic flat props, children, values escape hatch,
- * className, style, and mode. Excludes internal threading props.
+ * The `border` object, agent-friendly. The canonical type pins each per-side
+ * `*Width` to `${number}px`, so a literal like "1px" type-checks inline but a
+ * factored-out object widens "1px" to `string` and stops compiling — exactly the
+ * reusable-divider pattern authors reach for. Relax the `*Width` fields to
+ * SizeInput (the runtime accepts any CSS string), derived from the canonical
+ * shape so it tracks the schema instead of duplicating it.
  */
-type ItemProps<TValues> = SemanticProps$1<TValues, React.ReactNode> & {
-    className?: string;
-    style?: React.CSSProperties;
-    mode?: "web" | "email" | "document";
-};
-/** Button component props */
-type ButtonProps = ItemProps<ButtonValues>;
-/** Heading component props */
-type HeadingProps = ItemProps<HeadingValues>;
-/** Divider component props */
-type DividerProps = ItemProps<DividerValues>;
-/** HTML component props */
-type HtmlProps = ItemProps<HtmlValues>;
-/** Paragraph component props */
-type ParagraphProps = ItemProps<ParagraphValues>;
-/** Image component props — supports `alt` shorthand for `altText`. */
-type ImageProps = ItemProps<ImageValues> & {
-    /** Alt text (alias for altText) */
-    alt?: string;
-};
-/** Social component props — supports `icons` shorthand array. */
-type SocialProps = ItemProps<SocialValues> & {
-    /** Social icons shorthand */
-    icons?: SocialIcon[];
-    /** Icon shape */
-    iconType?: "circle" | "rounded" | "squared";
-};
-/** Menu component props — supports `items` shorthand array. */
-type MenuProps = ItemProps<MenuValues> & {
-    /** Menu items shorthand */
-    items?: MenuItem[];
+type BorderInput = {
+    [K in keyof NonNullable<ColumnValues["border"]>]?: K extends `${string}Width` ? SizeInput : NonNullable<ColumnValues["border"]>[K];
 };
-/** Table component props — supports `headers` + `data` shorthands. */
-type TableProps = ItemProps<TableValues> & {
-    /** Column headers */
-    headers?: string[];
-    /** Row data as 2D array */
-    data?: string[][];
+/** Heading levels (h1–h6). */
+type HeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+/** Shared text/style inputs, agent-friendly. */
+type TextStyleProps = {
+    fontFamily?: FontFamilyInput;
+    fontWeight?: FontWeightInput;
+    fontSize?: SizeInput;
+    lineHeight?: SizeInput;
+    /** Letter spacing — a CSS string ("0.5px", "-0.01em") or a number (px). */
+    letterSpacing?: SizeInput;
+    color?: string;
 };
-/** Video component props — supports `videoUrl` shorthand. */
-type VideoProps = ItemProps<VideoValues> & {
-    /** YouTube/Vimeo URL (auto-parsed) */
-    videoUrl?: string;
+/** Image `src` accepts a plain URL string or the value object (loosened sizing). */
+type ImageSrcInput = string | {
+    url: string;
+    width?: SizeInput;
+    height?: number;
+    autoWidth?: boolean;
+    maxWidth?: SizeInput;
+    [key: string]: unknown;
 };
 
 /**
@@ -338,6 +333,26 @@ type ItemComponentProps<TSemanticProps> = BaseItemComponentProps & TSemanticProp
  */
 type SemanticProps<T> = SemanticProps$1<T, React.ReactNode>;
 
+/**
+ * Button semantic props — agent-friendly text/style types (replacing the loose
+ * `any` flat props) plus a CSS-style `width` (number/px pins; "100%" full-width).
+ */
+type ButtonSemanticProps = Omit<SemanticProps<ButtonValues>, keyof TextStyleProps | "width" | "padding" | "borderRadius" | "border"> & TextStyleProps & {
+    /** Display width — a number/px pins the button; "100%" makes it full-width. */
+    width?: SizeInput;
+    /** Inner padding — a number (→ px) or CSS string ("14px 28px"). */
+    padding?: SizeInput;
+    /** Corner radius — a number (→ px) or CSS string ("8px", "500px"). */
+    borderRadius?: SizeInput;
+    /** Per-side border object (width fields accept a number/px string). */
+    border?: BorderInput;
+};
+/**
+ * Button Component Props
+ * Automatically provides autocomplete for ALL properties (flat and nested)
+ */
+interface ButtonProps extends ItemComponentProps<ButtonSemanticProps> {
+}
 /**
  * Button - Universal SSR/Client Component with Automatic Semantic Props
  *
@@ -375,8 +390,14 @@ type SemanticProps<T> = SemanticProps$1<T, React.ReactNode>;
  * </Button>
  * ```
  */
-declare const Button: React$1.FC<ItemComponentProps<SemanticProps<ButtonValues>>>;
+declare const Button: React$1.FC<ItemComponentProps<ButtonSemanticProps>>;
 
+type DividerSemanticProps = Omit<SemanticProps<DividerValues>, "border"> & {
+    /** Per-side border object (width fields accept a number/px string). */
+    border?: BorderInput;
+};
+interface DividerProps extends ItemComponentProps<DividerSemanticProps> {
+}
 /**
  * Divider - Universal SSR/Client Component with Automatic Semantic Props
  *
@@ -393,8 +414,26 @@ declare const Button: React$1.FC<ItemComponentProps<SemanticProps<ButtonValues>>
  * }} />
  * ```
  */
-declare const Divider: React$1.FC<ItemComponentProps<SemanticProps<DividerValues>>>;
+declare const Divider: React$1.FC<ItemComponentProps<DividerSemanticProps>>;
 
+/**
+ * Heading semantic props — agent-friendly text/style types (replacing the loose
+ * `any` flat props) plus the `level` alias and h1–h6 levels.
+ */
+type HeadingSemanticProps = Omit<SemanticProps<HeadingValues>, keyof TextStyleProps | "headingType"> & TextStyleProps & {
+    /** Heading level h1–h6. */
+    headingType?: HeadingLevel;
+    /** Alias for `headingType`. */
+    level?: HeadingLevel;
+    /** Heading text (or use children). */
+    text?: string;
+};
+/**
+ * Heading Component Props
+ * Automatically provides autocomplete for ALL properties (flat and nested)
+ */
+interface HeadingProps extends ItemComponentProps<HeadingSemanticProps> {
+}
 /**
  * Heading - Universal SSR/Client Component with Semantic Props API
  *
@@ -415,8 +454,10 @@ declare const Divider: React$1.FC<ItemComponentProps<SemanticProps<DividerValues
  * <Heading values={{ headingType: "h1", color: "#222" }}>Welcome</Heading>
  * ```
  */
-declare const Heading: React$1.FC<ItemComponentProps<SemanticProps<HeadingValues>>>;
+declare const Heading: React$1.FC<ItemComponentProps<HeadingSemanticProps>>;
 
+interface HtmlProps extends ItemComponentProps<SemanticProps<HtmlValues>> {
+}
 /**
  * Html - Universal SSR/Client Component for custom HTML with Automatic Semantic Props
  *
@@ -432,10 +473,23 @@ declare const Heading: React$1.FC<ItemComponentProps<SemanticProps<HeadingValues
  */
 declare const Html: React$1.FC<ItemComponentProps<SemanticProps<HtmlValues>>>;
 
-type ImageSemanticProps = SemanticProps<ImageValues> & {
+/**
+ * Image semantic props — agent-friendly `src` (plain URL string or value object)
+ * and CSS-style sizing (number/px pins, "50%" sets a percentage), replacing the
+ * loose `any` flat props.
+ */
+type ImageSemanticProps = Omit<SemanticProps<ImageValues>, "src" | "width" | "maxWidth"> & {
     /** Alt text (alias for altText) */
     alt?: string;
+    /** Image URL string, or the value object `{ url, width?, maxWidth?, ... }`. */
+    src?: ImageSrcInput;
+    /** Display width — number/px pins the image; "50%" sets a percentage width. */
+    width?: SizeInput;
+    /** Display width as a CSS value ("50%", "300px"). */
+    maxWidth?: SizeInput;
 };
+interface ImageProps extends ItemComponentProps<ImageSemanticProps> {
+}
 /**
  * Image - Renders an image element.
  *
@@ -454,10 +508,14 @@ type ImageSemanticProps = SemanticProps<ImageValues> & {
  */
 declare const Image: React$1.FC<ItemComponentProps<ImageSemanticProps>>;
 
-type MenuSemanticProps = SemanticProps<MenuValues> & {
+type MenuSemanticProps = Omit<SemanticProps<MenuValues>, "padding"> & {
     /** Menu items shorthand */
     items?: MenuItem[];
+    /** Inner padding — a number (→ px) or CSS string. */
+    padding?: SizeInput;
 };
+interface MenuProps extends ItemComponentProps<MenuSemanticProps> {
+}
 /**
  * Menu - Renders a navigation menu.
  *
@@ -479,6 +537,20 @@ type MenuSemanticProps = SemanticProps<MenuValues> & {
  */
 declare const Menu: React$1.FC<ItemComponentProps<MenuSemanticProps>>;
 
+/**
+ * Paragraph semantic props — agent-friendly text/style types (replacing the
+ * loose `any` flat props) plus the `text` shorthand (converted to textJson).
+ */
+type ParagraphSemanticProps = Omit<SemanticProps<ParagraphValues>, keyof TextStyleProps> & TextStyleProps & {
+    /** Plain-text content (or use `html` for inline formatting, or children). */
+    text?: string;
+};
+/**
+ * Paragraph Component Props
+ * Automatically provides autocomplete for ALL properties (flat and nested)
+ */
+interface ParagraphProps extends ItemComponentProps<ParagraphSemanticProps> {
+}
 /**
  * Paragraph - Universal SSR/Client Component with Semantic Props API
  *
@@ -499,7 +571,7 @@ declare const Menu: React$1.FC<ItemComponentProps<MenuSemanticProps>>;
  * <Paragraph values={{ textJson: "...", color: "#555" }} />
  * ```
  */
-declare const Paragraph: React$1.FC<ItemComponentProps<SemanticProps<ParagraphValues>>>;
+declare const Paragraph: React$1.FC<ItemComponentProps<ParagraphSemanticProps>>;
 
 type SocialSemanticProps = SemanticProps<SocialValues> & {
     /** Social icons shorthand (array of {name, url}) */
@@ -507,6 +579,10 @@ type SocialSemanticProps = SemanticProps<SocialValues> & {
     /** Icon shape */
     iconType?: "circle" | "rounded" | "squared";
 };
+interface SocialProps extends Omit<ItemComponentProps<SemanticProps<SocialValues>>, "icons"> {
+    icons?: SocialIcon[] | SocialValues["icons"];
+    iconType?: "circle" | "rounded" | "squared";
+}
 /**
  * Social - Renders social-media icon links.
  *
@@ -527,12 +603,24 @@ type SocialSemanticProps = SemanticProps<SocialValues> & {
  */
 declare const Social: React$1.FC<ItemComponentProps<SocialSemanticProps>>;
 
-type TableSemanticProps = SemanticProps<TableValues> & {
+type TableSemanticProps = Omit<SemanticProps<TableValues>, "padding" | "border"> & {
     /** Column headers as string[] */
     headers?: string[];
     /** Row data as 2D string array */
     data?: string[][];
+    /** Inner padding — a number (→ px) or CSS string. */
+    padding?: SizeInput;
+    /** Per-side border object (width fields accept a number/px string). */
+    border?: BorderInput;
 };
+interface TableProps extends Omit<ItemComponentProps<Omit<SemanticProps<TableValues>, "padding" | "border">>, "headers" | "data"> {
+    headers?: string[];
+    data?: string[][];
+    /** Inner padding — a number (→ px) or CSS string. */
+    padding?: SizeInput;
+    /** Per-side border object (width fields accept a number/px string). */
+    border?: BorderInput;
+}
 /**
  * Table - Renders a data table.
  *
@@ -561,6 +649,9 @@ type VideoSemanticProps = SemanticProps<VideoValues> & {
     /** YouTube/Vimeo URL (auto-parsed) */
     videoUrl?: string;
 };
+interface VideoProps extends ItemComponentProps<SemanticProps<VideoValues>> {
+    videoUrl?: string;
+}
 /**
  * Video - Renders an embedded video player (YouTube/Vimeo).
  *
@@ -578,7 +669,7 @@ type VideoSemanticProps = SemanticProps<VideoValues> & {
  */
 declare const Video: React$1.FC<ItemComponentProps<VideoSemanticProps>>;
 
-interface RowProps extends SemanticProps<RowValues> {
+type RowProps = Omit<SemanticProps<RowValues>, "padding"> & {
     children?: React__default.ReactNode;
     layout?: ColumnLayout;
     cells?: number[];
@@ -588,12 +679,14 @@ interface RowProps extends SemanticProps<RowValues> {
     index?: number;
     bodyValues?: any;
     collection?: string;
+    /** Padding — a CSS string ("0 48px", "20px 40px") or a number (px). */
+    padding?: SizeInput;
     /** @internal - Unlayer config threaded from UnlayerProvider via Body */
     _config?: UnlayerConfig;
-}
+};
 declare const Row: React__default.FC<RowProps>;
 
-interface ColumnProps extends SemanticProps<ColumnValues> {
+type ColumnProps = Omit<SemanticProps<ColumnValues>, "padding" | "border" | "borderRadius"> & {
     children?: React__default.ReactNode;
     index?: number;
     cells?: number[];
@@ -602,12 +695,19 @@ interface ColumnProps extends SemanticProps<ColumnValues> {
     mode?: RenderMode;
     className?: string;
     style?: React__default.CSSProperties;
+    /** Padding — a CSS string ("0 24px", "10px") or a number (px). */
+    padding?: SizeInput;
+    /** Corner radius — a number (→ px) or CSS string ("8px"). */
+    borderRadius?: SizeInput;
+    /** Per-side border object (great for hairline dividers). Width fields accept
+     *  a number/px string; reuse it as a factored-out const without `as const`. */
+    border?: BorderInput;
     /** @internal - Unlayer config threaded from UnlayerProvider via Body/Row */
     _config?: UnlayerConfig;
-}
+};
 declare const Column: React__default.FC<ColumnProps>;
 
-interface BodyProps extends SemanticProps<BodyValues> {
+type BodyProps = Omit<SemanticProps<BodyValues>, "padding" | "borderRadius"> & {
     children?: React__default.ReactNode;
     mode?: RenderMode;
     className?: string;
@@ -617,7 +717,11 @@ interface BodyProps extends SemanticProps<BodyValues> {
     config?: Partial<UnlayerConfig>;
     /** Preview text shown in email client inboxes (email mode only) */
     previewText?: string;
-}
+    /** Padding — a CSS string ("0 48px", "20px") or a number (px). */
+    padding?: SizeInput;
+    /** Corner radius — a number (→ px) or CSS string ("8px"). */
+    borderRadius?: SizeInput;
+};
 /**
  * Body - Universal Server/Client Component
  *