@formepdf/react 0.3.0 → 0.4.0

package/dist/expr.d.ts

@@ -0,0 +1,20 @@
+/** Comparison and arithmetic expression helpers. */
+export declare const expr: {
+    eq: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    ne: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    gt: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    lt: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    gte: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    lte: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    add: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    sub: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    mul: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    div: (a: unknown, b: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    upper: (v: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    lower: (v: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    concat: (...args: unknown[]) => import("./template-proxy.js").ExprMarkerObject;
+    format: (v: unknown, fmt: string) => import("./template-proxy.js").ExprMarkerObject;
+    cond: (condition: unknown, ifTrue: unknown, ifFalse: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    if: (condition: unknown, then: unknown, elseVal?: unknown) => import("./template-proxy.js").ExprMarkerObject;
+    count: (v: unknown) => import("./template-proxy.js").ExprMarkerObject;
+};

package/dist/expr.js

@@ -0,0 +1,39 @@
+/// Expression helpers for template operations that Proxy can't capture.
+///
+/// These produce expression marker objects that `serializeTemplate()` detects
+/// and converts to the corresponding `$op` nodes in the template JSON.
+import { createExprMarker, toExprValue } from './template-proxy.js';
+/** Comparison and arithmetic expression helpers. */
+export const expr = {
+    // Comparison
+    eq: (a, b) => createExprMarker({ $eq: [toExprValue(a), toExprValue(b)] }),
+    ne: (a, b) => createExprMarker({ $ne: [toExprValue(a), toExprValue(b)] }),
+    gt: (a, b) => createExprMarker({ $gt: [toExprValue(a), toExprValue(b)] }),
+    lt: (a, b) => createExprMarker({ $lt: [toExprValue(a), toExprValue(b)] }),
+    gte: (a, b) => createExprMarker({ $gte: [toExprValue(a), toExprValue(b)] }),
+    lte: (a, b) => createExprMarker({ $lte: [toExprValue(a), toExprValue(b)] }),
+    // Arithmetic
+    add: (a, b) => createExprMarker({ $add: [toExprValue(a), toExprValue(b)] }),
+    sub: (a, b) => createExprMarker({ $sub: [toExprValue(a), toExprValue(b)] }),
+    mul: (a, b) => createExprMarker({ $mul: [toExprValue(a), toExprValue(b)] }),
+    div: (a, b) => createExprMarker({ $div: [toExprValue(a), toExprValue(b)] }),
+    // String transforms
+    upper: (v) => createExprMarker({ $upper: toExprValue(v) }),
+    lower: (v) => createExprMarker({ $lower: toExprValue(v) }),
+    concat: (...args) => createExprMarker({ $concat: args.map(toExprValue) }),
+    format: (v, fmt) => createExprMarker({ $format: [toExprValue(v), fmt] }),
+    // Conditional
+    cond: (condition, ifTrue, ifFalse) => createExprMarker({ $cond: [toExprValue(condition), toExprValue(ifTrue), toExprValue(ifFalse)] }),
+    if: (condition, then, elseVal) => {
+        const obj = {
+            $if: toExprValue(condition),
+            then: toExprValue(then),
+        };
+        if (elseVal !== undefined) {
+            obj.else = toExprValue(elseVal);
+        }
+        return createExprMarker(obj);
+    },
+    // Array
+    count: (v) => createExprMarker({ $count: toExprValue(v) }),
+};

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { Document, Page, View, Text, Image, Table, Row, Cell, Fixed, Svg, PageBreak } from './components.js';
-export { serialize, mapStyle, mapDimension, parseColor, expandEdges, expandCorners } from './serialize.js';
+export { serialize, serializeTemplate, mapStyle, mapDimension, parseColor, expandEdges, expandCorners } from './serialize.js';
 export { StyleSheet } from './stylesheet.js';
 export { Font } from './font.js';
 export type { FontRegistration } from './font.js';
+export { createDataProxy, isRefMarker, isEachMarker, isExprMarker } from './template-proxy.js';
+export { expr } from './expr.js';
 export { render, renderToObject } from './render.js';
 export type { Style, Edges, Corners, EdgeColors, DocumentProps, PageProps, ViewProps, TextProps, ImageProps, ColumnDef, TableProps, RowProps, CellProps, FixedProps, SvgProps, TextRun, FormeDocument, FormeFont, FormeNode, FormeNodeKind, FormeStyle, FormePageConfig, FormePageSize, FormeEdges, FormeMetadata, FormeColumnDef, FormeColumnWidth, FormeDimension, FormeColor, FormeEdgeValues, FormeCornerValues, } from './types.js';

package/dist/index.js

@@ -1,10 +1,13 @@
 // Components
 export { Document, Page, View, Text, Image, Table, Row, Cell, Fixed, Svg, PageBreak } from './components.js';
 // Serialization
-export { serialize, mapStyle, mapDimension, parseColor, expandEdges, expandCorners } from './serialize.js';
+export { serialize, serializeTemplate, mapStyle, mapDimension, parseColor, expandEdges, expandCorners } from './serialize.js';
 // StyleSheet
 export { StyleSheet } from './stylesheet.js';
 // Font registration
 export { Font } from './font.js';
+// Template compilation
+export { createDataProxy, isRefMarker, isEachMarker, isExprMarker } from './template-proxy.js';
+export { expr } from './expr.js';
 // Render functions
 export { render, renderToObject } from './render.js';

package/dist/serialize.d.ts

@@ -10,3 +10,8 @@ export declare function mapDimension(val: number | string): FormeDimension;
 export declare function parseColor(hex: string): FormeColor;
 export declare function expandEdges(val: number | Edges): FormeEdges;
 export declare function expandCorners(val: number | Corners): FormeCornerValues;
+/**
+ * Serialize a React element tree into a Forme template JSON document.
+ * Like `serialize()` but with expression marker detection for template compilation.
+ */
+export declare function serializeTemplate(element: ReactElement): Record<string, unknown>;

package/dist/serialize.js

@@ -1,6 +1,7 @@
 import { isValidElement, Children, Fragment } from 'react';
 import { Document, Page, View, Text, Image, Table, Row, Cell, Fixed, Svg, PageBreak } from './components.js';
 import { Font } from './font.js';
+import { isRefMarker, getRefPath, isEachMarker, getEachPath, getEachTemplate, isExprMarker, getExpr, REF_SENTINEL, REF_SENTINEL_END, } from './template-proxy.js';
 const VALID_PARENTS = {
     Page: {
         allowed: ['Document'],
@@ -759,3 +760,453 @@ function mergeFonts(globalFonts, docFonts) {
     }
     return Array.from(map.values());
 }
+// ─── Template serialization ─────────────────────────────────────────
+//
+// Parallel to `serialize()` but detects proxy markers and expr markers,
+// converting them to `$ref`, `$each`, `$if`, and operator nodes.
+/**
+ * Serialize a React element tree into a Forme template JSON document.
+ * Like `serialize()` but with expression marker detection for template compilation.
+ */
+export function serializeTemplate(element) {
+    if (element.type !== Document) {
+        throw new Error('Top-level element must be <Document>');
+    }
+    const props = element.props;
+    const childElements = flattenTemplateChildren(props.children);
+    const pageNodes = [];
+    const contentNodes = [];
+    for (const child of childElements) {
+        if (isValidElement(child) && child.type === Page) {
+            pageNodes.push(serializeTemplatePage(child));
+        }
+        else {
+            const node = serializeTemplateChild(child, 'Document');
+            if (node !== null)
+                contentNodes.push(node);
+        }
+    }
+    let children;
+    if (pageNodes.length > 0) {
+        if (contentNodes.length > 0) {
+            const lastPage = pageNodes[pageNodes.length - 1];
+            lastPage.children.push(...contentNodes);
+        }
+        children = pageNodes;
+    }
+    else if (contentNodes.length > 0) {
+        children = contentNodes;
+    }
+    else {
+        children = [];
+    }
+    const metadata = {};
+    if (props.title !== undefined)
+        metadata.title = processTemplateValue(props.title);
+    if (props.author !== undefined)
+        metadata.author = processTemplateValue(props.author);
+    if (props.subject !== undefined)
+        metadata.subject = processTemplateValue(props.subject);
+    if (props.creator !== undefined)
+        metadata.creator = processTemplateValue(props.creator);
+    const mergedFonts = mergeFonts(Font.getRegistered(), props.fonts);
+    const result = {
+        children,
+        metadata,
+        defaultPage: {
+            size: 'A4',
+            margin: { top: 54, right: 54, bottom: 54, left: 54 },
+            wrap: true,
+        },
+    };
+    if (mergedFonts.length > 0) {
+        result.fonts = mergedFonts;
+    }
+    return result;
+}
+function serializeTemplatePage(element) {
+    const props = element.props;
+    let size = 'A4';
+    if (props.size !== undefined) {
+        if (typeof props.size === 'string') {
+            size = props.size;
+        }
+        else {
+            size = { Custom: { width: props.size.width, height: props.size.height } };
+        }
+    }
+    let margin = { top: 54, right: 54, bottom: 54, left: 54 };
+    if (props.margin !== undefined) {
+        margin = expandEdges(props.margin);
+    }
+    const config = { size, margin, wrap: true };
+    const childElements = flattenTemplateChildren(props.children);
+    const children = serializeTemplateChildren(childElements, 'Page');
+    return {
+        kind: { type: 'Page', config },
+        style: {},
+        children,
+    };
+}
+function serializeTemplateChild(child, parent = null) {
+    if (child === null || child === undefined || typeof child === 'boolean') {
+        return null;
+    }
+    // Check for each marker (from .map() on proxy)
+    if (isEachMarker(child)) {
+        const path = getEachPath(child);
+        const template = getEachTemplate(child);
+        // The template is the JSX element returned from the .map() callback
+        const serializedTemplate = isValidElement(template)
+            ? serializeTemplateChild(template, parent)
+            : processTemplateValue(template);
+        return {
+            $each: { $ref: path },
+            as: '$item',
+            template: serializedTemplate,
+        };
+    }
+    // Check for expr marker
+    if (isExprMarker(child)) {
+        return getExpr(child);
+    }
+    // Check for ref sentinel strings
+    if (typeof child === 'string') {
+        const processed = processTemplateString(child);
+        if (processed !== null)
+            return processed;
+        return {
+            kind: { type: 'Text', content: child },
+            style: {},
+            children: [],
+        };
+    }
+    if (typeof child === 'number') {
+        return {
+            kind: { type: 'Text', content: String(child) },
+            style: {},
+            children: [],
+        };
+    }
+    if (!isValidElement(child))
+        return null;
+    const element = child;
+    if (element.type === View)
+        return serializeTemplateView(element, parent);
+    if (element.type === Text)
+        return serializeTemplateText(element);
+    if (element.type === Image)
+        return serializeTemplateImage(element);
+    if (element.type === Table)
+        return serializeTemplateTable(element, parent);
+    if (element.type === Row) {
+        validateNesting('Row', parent);
+        return serializeTemplateRow(element);
+    }
+    if (element.type === Cell) {
+        validateNesting('Cell', parent);
+        return serializeTemplateCell(element);
+    }
+    if (element.type === Fixed)
+        return serializeTemplateFixed(element);
+    if (element.type === Svg)
+        return serializeSvg(element);
+    if (element.type === PageBreak) {
+        return { kind: { type: 'PageBreak' }, style: {}, children: [] };
+    }
+    if (element.type === Page) {
+        validateNesting('Page', parent);
+        return serializeTemplatePage(element);
+    }
+    // Unknown function component — call it
+    if (typeof element.type === 'function') {
+        const result = element.type(element.props);
+        if (isValidElement(result)) {
+            return serializeTemplateChild(result, parent);
+        }
+        return null;
+    }
+    return null;
+}
+function serializeTemplateView(element, _parent = null) {
+    const props = element.props;
+    const style = mapTemplateStyle(props.style);
+    if (props.wrap !== undefined)
+        style.wrap = props.wrap;
+    const childElements = flattenTemplateChildren(props.children);
+    const children = serializeTemplateChildren(childElements, 'View');
+    const node = { kind: { type: 'View' }, style, children };
+    if (props.bookmark)
+        node.bookmark = props.bookmark;
+    if (props.href)
+        node.href = props.href;
+    return node;
+}
+function serializeTemplateText(element) {
+    const props = element.props;
+    const childElements = flattenTemplateChildren(props.children);
+    const hasTextChild = childElements.some(c => isValidElement(c) && c.type === Text);
+    const kind = { type: 'Text', content: '' };
+    if (hasTextChild) {
+        const runs = [];
+        for (const child of childElements) {
+            if (typeof child === 'string' || typeof child === 'number') {
+                const processed = typeof child === 'string' ? processTemplateString(child) : null;
+                if (processed !== null) {
+                    runs.push({ content: processed });
+                }
+                else {
+                    runs.push({ content: String(child) });
+                }
+            }
+            else if (isValidElement(child) && child.type === Text) {
+                const childProps = child.props;
+                const run = {
+                    content: flattenTemplateTextContent(childProps.children),
+                };
+                if (childProps.style)
+                    run.style = mapTemplateStyle(childProps.style);
+                if (childProps.href)
+                    run.href = childProps.href;
+                runs.push(run);
+            }
+        }
+        kind.runs = runs;
+    }
+    else {
+        kind.content = flattenTemplateTextContent(props.children);
+    }
+    if (props.href)
+        kind.href = props.href;
+    const node = {
+        kind,
+        style: mapTemplateStyle(props.style),
+        children: [],
+    };
+    if (props.bookmark)
+        node.bookmark = props.bookmark;
+    return node;
+}
+function serializeTemplateImage(element) {
+    const props = element.props;
+    const kind = { type: 'Image', src: processTemplateValue(props.src) };
+    if (props.width !== undefined)
+        kind.width = processTemplateValue(props.width);
+    if (props.height !== undefined)
+        kind.height = processTemplateValue(props.height);
+    return { kind, style: mapTemplateStyle(props.style), children: [] };
+}
+function serializeTemplateTable(element, _parent = null) {
+    const props = element.props;
+    const columns = (props.columns ?? []).map(col => ({
+        width: mapColumnWidth(col.width),
+    }));
+    const childElements = flattenTemplateChildren(props.children);
+    const children = serializeTemplateChildren(childElements, 'Table');
+    return { kind: { type: 'Table', columns }, style: mapTemplateStyle(props.style), children };
+}
+function serializeTemplateRow(element) {
+    const props = element.props;
+    const childElements = flattenTemplateChildren(props.children);
+    const children = serializeTemplateChildren(childElements, 'Row');
+    return { kind: { type: 'TableRow', is_header: props.header ?? false }, style: mapTemplateStyle(props.style), children };
+}
+function serializeTemplateCell(element) {
+    const props = element.props;
+    const childElements = flattenTemplateChildren(props.children);
+    const children = serializeTemplateChildren(childElements, 'Cell');
+    return { kind: { type: 'TableCell', col_span: props.colSpan ?? 1, row_span: props.rowSpan ?? 1 }, style: mapTemplateStyle(props.style), children };
+}
+function serializeTemplateFixed(element) {
+    const props = element.props;
+    const position = props.position === 'header' ? 'Header' : 'Footer';
+    const childElements = flattenTemplateChildren(props.children);
+    const children = serializeTemplateChildren(childElements, 'Fixed');
+    const node = { kind: { type: 'Fixed', position }, style: mapTemplateStyle(props.style), children };
+    if (props.bookmark)
+        node.bookmark = props.bookmark;
+    return node;
+}
+function serializeTemplateChildren(children, parent = null) {
+    const nodes = [];
+    for (const child of children) {
+        const node = serializeTemplateChild(child, parent);
+        if (node !== null)
+            nodes.push(node);
+    }
+    return nodes;
+}
+/**
+ * Flatten children without using React.Children.forEach, which rejects
+ * proxy objects and markers. Handles arrays, Fragments, and raw values.
+ */
+function flattenTemplateChildren(children) {
+    if (children === null || children === undefined)
+        return [];
+    const result = [];
+    if (Array.isArray(children)) {
+        for (const child of children) {
+            result.push(...flattenTemplateChildren(child));
+        }
+        return result;
+    }
+    // Fragment unwrapping
+    if (isValidElement(children) && children.type === Fragment) {
+        const fragProps = children.props;
+        return flattenTemplateChildren(fragProps.children);
+    }
+    result.push(children);
+    return result;
+}
+// ─── Template value processing ──────────────────────────────────────
+/**
+ * Process a value that may contain ref markers, expr markers, or proxy objects.
+ * Returns the expression form or the original value.
+ */
+function processTemplateValue(v) {
+    if (typeof v === 'string') {
+        if (isRefMarker(v)) {
+            return { $ref: getRefPath(v) };
+        }
+        // Check for embedded sentinels in longer strings
+        if (v.includes(REF_SENTINEL)) {
+            return processTemplateInterpolatedString(v);
+        }
+        return v;
+    }
+    if (isExprMarker(v)) {
+        return getExpr(v);
+    }
+    if (isEachMarker(v)) {
+        return {
+            $each: { $ref: getEachPath(v) },
+            as: '$item',
+            template: processTemplateValue(getEachTemplate(v)),
+        };
+    }
+    // Proxy objects with toPrimitive
+    if (typeof v === 'object' && v !== null && Symbol.toPrimitive in v) {
+        const str = String(v);
+        if (isRefMarker(str)) {
+            return { $ref: getRefPath(str) };
+        }
+    }
+    return v;
+}
+/**
+ * Process a string that contains interpolated ref sentinels.
+ * e.g. "Hello \0FORME_REF:name\0!" → {$concat: ["Hello ", {$ref: "name"}, "!"]}
+ */
+function processTemplateInterpolatedString(s) {
+    const parts = [];
+    let remaining = s;
+    while (remaining.length > 0) {
+        const startIdx = remaining.indexOf(REF_SENTINEL);
+        if (startIdx === -1) {
+            parts.push(remaining);
+            break;
+        }
+        if (startIdx > 0) {
+            parts.push(remaining.slice(0, startIdx));
+        }
+        const afterSentinel = remaining.slice(startIdx + REF_SENTINEL.length);
+        const endIdx = afterSentinel.indexOf(REF_SENTINEL_END);
+        if (endIdx === -1) {
+            parts.push(remaining);
+            break;
+        }
+        const path = afterSentinel.slice(0, endIdx);
+        parts.push({ $ref: path });
+        remaining = afterSentinel.slice(endIdx + REF_SENTINEL_END.length);
+    }
+    if (parts.length === 1)
+        return parts[0];
+    return { $concat: parts };
+}
+/**
+ * Process a string that might be a pure ref sentinel.
+ * Returns the $ref node if it's a pure ref, null otherwise.
+ */
+function processTemplateString(s) {
+    if (isRefMarker(s)) {
+        return { $ref: getRefPath(s) };
+    }
+    if (s.includes(REF_SENTINEL)) {
+        return processTemplateInterpolatedString(s);
+    }
+    return null;
+}
+/**
+ * Flatten text content within a <Text> element, detecting ref markers.
+ * Returns either a plain string or a $ref/$concat expression.
+ */
+function flattenTemplateTextContent(children) {
+    if (children === null || children === undefined)
+        return '';
+    if (typeof children === 'boolean')
+        return '';
+    if (typeof children === 'string') {
+        if (isRefMarker(children))
+            return { $ref: getRefPath(children) };
+        if (children.includes(REF_SENTINEL))
+            return processTemplateInterpolatedString(children);
+        return children;
+    }
+    if (typeof children === 'number')
+        return String(children);
+    if (isExprMarker(children))
+        return getExpr(children);
+    // Proxy with toPrimitive
+    if (typeof children === 'object' && children !== null && Symbol.toPrimitive in children) {
+        const str = String(children);
+        if (isRefMarker(str))
+            return { $ref: getRefPath(str) };
+        return str;
+    }
+    if (Array.isArray(children)) {
+        const parts = children.map(c => flattenTemplateTextContent(c));
+        // If all parts are strings, join them
+        if (parts.every(p => typeof p === 'string')) {
+            return parts.join('');
+        }
+        // Otherwise produce a $concat
+        return { $concat: parts };
+    }
+    if (isValidElement(children)) {
+        const element = children;
+        if (element.type === Text) {
+            const props = element.props;
+            return flattenTemplateTextContent(props.children);
+        }
+        const props = element.props;
+        return flattenTemplateTextContent(props.children);
+    }
+    const arr = [];
+    Children.forEach(children, c => arr.push(c));
+    if (arr.length > 0) {
+        return flattenTemplateTextContent(arr);
+    }
+    return String(children);
+}
+/**
+ * Map style, processing values that may contain template expressions.
+ */
+function mapTemplateStyle(style) {
+    if (!style)
+        return {};
+    // Use the regular mapStyle but then post-process values that contain markers
+    const result = mapStyle(style);
+    return processTemplateStyleValues(result);
+}
+function processTemplateStyleValues(obj) {
+    const result = {};
+    for (const [key, val] of Object.entries(obj)) {
+        if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+            result[key] = processTemplateStyleValues(val);
+        }
+        else {
+            result[key] = processTemplateValue(val);
+        }
+    }
+    return result;
+}

package/dist/template-proxy.d.ts

@@ -0,0 +1,38 @@
+/** Sentinel prefix/suffix for ref markers embedded in template strings. */
+declare const REF_SENTINEL = "\0FORME_REF:";
+declare const REF_SENTINEL_END = "\0";
+/** Symbol to identify each markers produced by .map() */
+declare const EACH_MARKER: unique symbol;
+/** Symbol to identify expression marker objects */
+declare const EXPR_MARKER: unique symbol;
+/** Create a recording proxy for template data. */
+export declare function createDataProxy(rootPath?: string[]): unknown;
+export declare function isRefMarker(value: unknown): boolean;
+export declare function getRefPath(value: string): string;
+export declare function isEachMarker(value: unknown): value is {
+    [EACH_MARKER]: true;
+    path: string;
+    template: unknown;
+};
+export declare function getEachPath(marker: {
+    path: string;
+}): string;
+export declare function getEachTemplate(marker: {
+    template: unknown;
+}): unknown;
+export declare function isExprMarker(value: unknown): value is {
+    [EXPR_MARKER]: true;
+    expr: Record<string, unknown>;
+};
+export declare function getExpr(marker: {
+    expr: Record<string, unknown>;
+}): Record<string, unknown>;
+/** Opaque marker type returned by expression helpers. */
+export interface ExprMarkerObject {
+    expr: Record<string, unknown>;
+}
+/** Create an expression marker wrapping a template expression object. */
+export declare function createExprMarker(expr: Record<string, unknown>): ExprMarkerObject;
+/** Convert a value that may be a proxy/marker to its expression form. */
+export declare function toExprValue(v: unknown): unknown;
+export { REF_SENTINEL, REF_SENTINEL_END, EACH_MARKER, EXPR_MARKER };

package/dist/template-proxy.js

@@ -0,0 +1,100 @@
+/// Recording proxy that traces property access for template compilation.
+///
+/// When JSX templates use `data.user.name`, the proxy records the access path
+/// and produces `$ref` markers in the serialized output. Array `.map()` calls
+/// produce `$each` markers.
+/** Sentinel prefix/suffix for ref markers embedded in template strings. */
+const REF_SENTINEL = '\0FORME_REF:';
+const REF_SENTINEL_END = '\0';
+/** Symbol to identify each markers produced by .map() */
+const EACH_MARKER = Symbol.for('forme:each');
+/** Symbol to identify expression marker objects */
+const EXPR_MARKER = Symbol.for('forme:expr');
+/** Create a recording proxy for template data. */
+export function createDataProxy(rootPath = []) {
+    const handler = {
+        get(_target, prop) {
+            // String coercion hooks — produce sentinel string for JSX interpolation
+            // Must be checked before the generic symbol guard below
+            if (prop === Symbol.toPrimitive || prop === 'toString' || prop === 'valueOf') {
+                return () => `${REF_SENTINEL}${rootPath.join('.')}${REF_SENTINEL_END}`;
+            }
+            // .map() on array proxies → produce $each marker
+            if (prop === 'map') {
+                return (fn) => {
+                    const itemProxy = createDataProxy(['$item']);
+                    const indexProxy = createDataProxy(['$index']);
+                    const template = fn(itemProxy, indexProxy);
+                    return createEachMarker(rootPath.join('.'), template);
+                };
+            }
+            // Other symbols — not supported
+            if (typeof prop === 'symbol') {
+                return undefined;
+            }
+            // Property access → extend path
+            return createDataProxy([...rootPath, prop]);
+        },
+        // Support `Symbol.toPrimitive in proxy` checks
+        has(_target, prop) {
+            if (prop === Symbol.toPrimitive)
+                return true;
+            return prop in _target;
+        },
+    };
+    return new Proxy(Object.create(null), handler);
+}
+// ─── Marker detection ────────────────────────────────────────────────
+export function isRefMarker(value) {
+    if (typeof value !== 'string')
+        return false;
+    return value.startsWith(REF_SENTINEL) && value.endsWith(REF_SENTINEL_END);
+}
+export function getRefPath(value) {
+    return value.slice(REF_SENTINEL.length, -REF_SENTINEL_END.length);
+}
+export function isEachMarker(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[EACH_MARKER] === true);
+}
+export function getEachPath(marker) {
+    return marker.path;
+}
+export function getEachTemplate(marker) {
+    return marker.template;
+}
+export function isExprMarker(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[EXPR_MARKER] === true);
+}
+export function getExpr(marker) {
+    return marker.expr;
+}
+// ─── Internal helpers ────────────────────────────────────────────────
+function createEachMarker(path, template) {
+    return Object.defineProperty({ path, template, [EACH_MARKER]: true }, EACH_MARKER, { enumerable: false, value: true });
+}
+/** Create an expression marker wrapping a template expression object. */
+export function createExprMarker(expr) {
+    return Object.defineProperty({ expr, [EXPR_MARKER]: true }, EXPR_MARKER, { enumerable: false, value: true });
+}
+/** Convert a value that may be a proxy/marker to its expression form. */
+export function toExprValue(v) {
+    if (typeof v === 'string' && isRefMarker(v)) {
+        return { $ref: getRefPath(v) };
+    }
+    if (isExprMarker(v)) {
+        return v.expr;
+    }
+    // Proxy objects will coerce to string via toPrimitive when used in expressions
+    if (typeof v === 'object' && v !== null && Symbol.toPrimitive in v) {
+        const str = String(v);
+        if (isRefMarker(str)) {
+            return { $ref: getRefPath(str) };
+        }
+    }
+    return v;
+}
+export { REF_SENTINEL, REF_SENTINEL_END, EACH_MARKER, EXPR_MARKER };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formepdf/react",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "JSX-to-JSON serializer for Forme PDF engine",
   "type": "module",
   "main": "./dist/index.js",