@pdfme/jsx 6.1.1-dev.8 → 6.1.2-dev.11

package/README.md

@@ -4,15 +4,23 @@ Small JSX authoring layer for creating pdfme templates from stacking layout prim
 
 ```tsx
 /** @jsxImportSource @pdfme/jsx */
-import { Page, Stack, Text, renderToTemplate } from '@pdfme/jsx';
+import { Document, MultiVariableText, Page, Stack, Text, renderToTemplate } from '@pdfme/jsx';
 
 const { template, inputs } = await renderToTemplate(
-  <Page margin={{ x: 12, y: 16 }}>
-    <Stack gap={4}>
-      <Text size={18}>Invoice</Text>
-      <Text name="customerName">Alice</Text>
-    </Stack>
-  </Page>,
+  <Document margin={{ x: 12, y: 16 }}>
+    <Page>
+      <Stack gap={4}>
+        <Text size={18}>Invoice</Text>
+        <Text name="customerName">Alice</Text>
+        <MultiVariableText
+          name="message"
+          text="Hello **{name}**, status: `{status}`"
+          values={{ name: 'Alice **literal**', status: 'draft' }}
+          textFormat="inline-markdown"
+        />
+      </Stack>
+    </Page>
+  </Document>,
 );
 ```
 
@@ -22,11 +30,95 @@ it provides its own `jsx-runtime` and `jsx-dev-runtime`.
 
 ## MVP constraints
 
-- `Text` height is measured with pdfme's text/rich text wrapping helpers when `height` is omitted.
-  Pass an explicit `height` when you need a fixed field box.
+- `Text` and `MultiVariableText` heights are measured with pdfme's text/rich text wrapping helpers
+  when `height` is omitted. Pass an explicit `height` when you need a fixed field box.
+- `Text textFormat="inline-markdown"` is read-only only. Editable `Text` values use plain content.
+- `MultiVariableText` uses `text` or children as the template string and stores `values` as the
+  JSON input. Variable names are inferred from `{name}` placeholders and can also be passed with
+  `variables`.
+- `Image` uses `src` as its initial content and is intended to be self-closing.
+- `Svg` uses `svg` or children as its initial content.
+- With `name`, `Image` and `Svg` become input-backed schemas; without `name`, they are read-only
+  content.
+- `Rectangle`, `Ellipse`, and `Line` are static visual schemas for backgrounds, dividers, and simple
+  shapes.
+- `Document` is the root component for document-level settings and repeated static content. It can
+  contain `Header`, `Footer`, `Static`, and `Page` children.
+- `Document` props are defaults, not deep-merged style objects. If a `Page` specifies `margin`,
+  `size`, `orientation`, or `font`, that `Page` value replaces the `Document` value for that prop.
+  The generated blank `basePdf.padding` comes from the resolved margin of the first rendered page.
+- `Header` and `Footer` render read-only content into blank `basePdf.staticSchema`. `Header` uses the
+  top margin area and `Footer` uses the bottom margin area, so body content stays inside the `Page`
+  margin frame.
+- `Static` is a lower-level repeated overlay that uses full-page coordinates. It is useful for
+  watermarks and other fixed page-coordinate content. Custom `basePdf` is not supported when
+  document static content is present.
+
+```tsx
+<Document size="A4" margin={{ x: 16, y: 18 }}>
+  <Header>
+    <Text height={8}>Header</Text>
+  </Header>
+  <Footer>
+    <Text height={8}>Footer</Text>
+  </Footer>
+  <Page>
+    <Text height={8}>Body</Text>
+  </Page>
+</Document>
+```
+
+- `Header`, `Footer`, and `Static` must be direct children of `Document`. They are intentionally not
+  allowed inside `Page`, because they render into document-level `staticSchema` and are repeated on
+  every page.
+- Multiple `Static` blocks with the same placement are concatenated in declaration order. Top blocks
+  start at the top of the page; bottom blocks are stacked together in declaration order and anchored
+  to the page bottom, so the last bottom block sits at the page edge. If static content overlaps the
+  header/footer/body areas, pdfme will draw the schemas in static schema order.
+- Static content currently accepts read-only `Stack`, `Row`, `Box`, `Spacer`, `Text`, `Image`, `Svg`,
+  `Rectangle`, `Ellipse`, and `Line` content. `MultiVariableText`, `List`, `Table`, input-backed
+  schemas, and `PageBreak` are rejected.
+- `Absolute` can be used inside `Page`, `Header`, `Footer`, top `Static`, or `Box` as a small manual
+  placement escape hatch. It uses the parent layout frame as its coordinate origin and does not
+  advance the surrounding stack/row flow. When `width` or `height` is omitted, it uses the remaining
+  parent frame size from `x` / `y`. Direct `Stack` / `Row` support is intentionally left for later;
+  wrap with an explicit-size `Box` when you need a local manual-placement frame inside flow content.
+
+```tsx
+<Page margin={12}>
+  <Text height={8}>Body starts here</Text>
+  <Absolute x={120} y={0} width={60}>
+    <Text height={6}>Top-right note</Text>
+  </Absolute>
+</Page>
+```
+
+- Layout children can use `margin`. `Stack` and `Row` support `alignItems` for simple cross-axis
+  alignment without trying to implement full CSS/Flexbox.
+- `Stack` and `Row` support `justifyContent="start" | "center" | "end" | "space-between"` for
+  main-axis spacing. `Stack` uses this most predictably with an explicit `height`; `Row` uses it most
+  predictably with an explicit `width`.
+- `Stack` defaults to `alignItems="stretch"` to preserve full-width stacking. Use an explicit child
+  `width` when you want `alignItems="center"` or `"end"` to visibly move that child.
+- `Row` defaults to `alignItems="start"` and intentionally does not support cross-axis stretch yet.
+- Row children can use `flexGrow` or `flex` as a grow weight. If `width` is also set, it is used as
+  the basis before remaining width is distributed.
+  `flex` is only a short alias for `flexGrow`, not the CSS `flex` shorthand.
+
+```tsx
+<Row width={120}>
+  <Text width={20} flex={1}>A</Text>
+  <Text width={20} flex={3}>B</Text>
+</Row>
+// A width: 40, B width: 80
+```
+
+- `flexGrow={0}` without `width` produces a zero-width Row child.
 - `PageBreak` is supported only along a `Page` / `Stack` / `Box` layout path. It is rejected inside
-  `Row`, `Text`, `List`, and `Table`.
+  `Row`, leaf schemas, `List`, and `Table`.
 - All `Page` nodes in one `renderToTemplate` call must use the same page size, orientation, and
   margin because a pdfme blank `basePdf` has one shared size and padding.
-- `Table widths` are percentages passed to pdfme `headWidthPercentages`, for example
-  `widths={[70, 30]}`.
+- `Table columnWeights` are relative column width weights, not millimeter widths. They are
+  normalized to pdfme `headWidthPercentages`, for example `columnWeights={[70, 30]}`.
+  Missing or invalid weights default to `1`, so pass one weight per column when you need exact
+  ratios. Earlier beta builds used `widths`; use `columnWeights` going forward.

package/dist/components.d.ts

@@ -1,10 +1,21 @@
-import type { BoxProps, ListProps, PageBreakProps, PageProps, RowProps, SpacerProps, StackProps, TableProps, TextProps } from './types.js';
+import type { AbsoluteProps, BoxProps, DocumentProps, EllipseProps, FooterProps, HeaderProps, ImageProps, LineProps, ListProps, MultiVariableTextProps, PageBreakProps, PageProps, RectangleProps, RowProps, SpacerProps, StackProps, StaticProps, SvgProps, TableProps, TextProps } from './types.js';
+export declare const Document: (props: DocumentProps) => import("./types.js").PdfJsxElement<"document">;
 export declare const Page: (props: PageProps) => import("./types.js").PdfJsxElement<"page">;
+export declare const Static: (props: StaticProps) => import("./types.js").PdfJsxElement<"static">;
+export declare const Header: (props: HeaderProps) => import("./types.js").PdfJsxElement<"header">;
+export declare const Footer: (props: FooterProps) => import("./types.js").PdfJsxElement<"footer">;
+export declare const Absolute: (props: AbsoluteProps) => import("./types.js").PdfJsxElement<"absolute">;
 export declare const Stack: (props: StackProps) => import("./types.js").PdfJsxElement<"stack">;
 export declare const Row: (props: RowProps) => import("./types.js").PdfJsxElement<"row">;
 export declare const Box: (props: BoxProps) => import("./types.js").PdfJsxElement<"box">;
 export declare const Spacer: (props: SpacerProps) => import("./types.js").PdfJsxElement<"spacer">;
 export declare const Text: (props: TextProps) => import("./types.js").PdfJsxElement<"text">;
+export declare const MultiVariableText: (props: MultiVariableTextProps) => import("./types.js").PdfJsxElement<"multiVariableText">;
+export declare const Image: (props: ImageProps) => import("./types.js").PdfJsxElement<"image">;
+export declare const Svg: (props: SvgProps) => import("./types.js").PdfJsxElement<"svg">;
+export declare const Rectangle: (props: RectangleProps) => import("./types.js").PdfJsxElement<"rectangle">;
+export declare const Ellipse: (props: EllipseProps) => import("./types.js").PdfJsxElement<"ellipse">;
+export declare const Line: (props: LineProps) => import("./types.js").PdfJsxElement<"line">;
 export declare const List: (props: ListProps) => import("./types.js").PdfJsxElement<"list">;
 export declare const Table: (props: TableProps) => import("./types.js").PdfJsxElement<"table">;
 export declare const PageBreak: (props?: PageBreakProps) => import("./types.js").PdfJsxElement<"pagebreak">;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { Box, List, Page, PageBreak, Row, Spacer, Stack, Table, Text } from './components.js';
+export { Absolute, Box, Document, Ellipse, Footer, Header, Image, Line, List, MultiVariableText, Page, PageBreak, Rectangle, Row, Spacer, Stack, Static, Svg, Table, Text, } from './components.js';
 export { renderToTemplate } from './render.js';
-export type { BoxProps, BoxSides, CellStyle, ListItem, ListProps, PageBreakProps, PageOrientation, PageProps, PageSize, PageSizePreset, PdfJsxChild, PdfJsxElement, RenderOptions, RenderResult, RowProps, SpacerProps, StackProps, TableProps, TextProps, } from './types.js';
+export type { AbsoluteProps, BoxProps, BoxSides, CellStyle, DocumentProps, EllipseProps, FooterProps, HeaderProps, ImageProps, LineProps, ListItem, ListProps, MultiVariableTextProps, MultiVariableTextValues, PageBreakProps, PageOrientation, PageProps, PageSize, PageSizePreset, PdfJsxChild, PdfJsxElement, RectangleProps, RenderOptions, RenderResult, RowProps, SpacerProps, StackProps, StaticPlacement, StaticProps, SvgProps, TableProps, TextProps, } from './types.js';