Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

feat(documents): the Approval block carries its own heading and caption

Sidwebworks25d33388efb7
diff --git a/.claude/rules/document-template-customizer.md b/.claude/rules/document-template-customizer.md
index 97680f91bf..da1e692e44 100644
--- a/.claude/rules/document-template-customizer.md
+++ b/.claude/rules/document-template-customizer.md
@@ -103,8 +103,14 @@ registries + a `BLOCK_META` entry + (if built-in) a `DEFAULT_TEMPLATES` entry.
## Approval block (purchase orders)
The built-in `approval` block (`pdf/blocks/purchaseOrder/ApprovalBlock.tsx`)
-prints the approver's signature (max 40 pt high), name and approval date, and
-nothing while the order is unapproved. It is last in the default PO layout and
+prints a heading, the approver's signature (max 40 pt high) over a line, and a
+caption, and nothing while the order is unapproved. Its options, set in the
+editor's `ApprovalConfig`: `heading` (absent = `DEFAULT_APPROVAL_HEADING`,
+"Approved By"; an empty string prints none), `showSignature` (default true)
+and `content`, a rich-text caption with merge fields (empty =
+`DEFAULT_APPROVAL_CAPTION`: `{order.approvedBy}`, a line break,
+`{order.approvedDate}`). "Approved by … on …" text belongs in this caption,
+not in a separate Rich Text block, or the PDF prints it twice. It is last in the default PO layout and
is appended visible to saved templates. Its data is `PurchaseOrderData.approval`
from `getPurchaseOrderApproval(…, { withSignature: true })`
(`purchasing.service.ts`), which reads the file recorded on the approval
diff --git a/apps/erp/app/components/DocumentTemplateEditor/BlockConfig.tsx b/apps/erp/app/components/DocumentTemplateEditor/BlockConfig.tsx
index 3a754c281e..9d97199ca4 100644
--- a/apps/erp/app/components/DocumentTemplateEditor/BlockConfig.tsx
+++ b/apps/erp/app/components/DocumentTemplateEditor/BlockConfig.tsx
@@ -3,6 +3,7 @@
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
import type {
+ ApprovalBlock,
CustomFieldBlock,
DocumentBlockType,
KeyValueBlock,
@@ -17,6 +18,8 @@ import type {
import {
BLOCK_META,
BUILT_IN_SECTION_IDS,
+ DEFAULT_APPROVAL_CAPTION,
+ DEFAULT_APPROVAL_HEADING,
DEFAULT_LINE_ITEMS_OPTIONS,
DEFAULT_SUMMARY_OPTIONS,
getMergeFields
@@ -141,6 +144,7 @@ export function BlockConfig() {
block.type === "lineItems" ||
block.type === "summary" ||
block.type === "terms" ||
+ block.type === "approval" ||
block.type === "labelRevision" ||
block.type === "labelQuantity" ||
block.type === "labelTracking" ||
@@ -173,6 +177,7 @@ export function BlockConfig() {
{block.type === "operations" && <OperationsConfig block={block} />}
{block.type === "summary" && <SummaryConfig block={block} />}
{block.type === "terms" && <TermsConfig block={block} />}
+ {block.type === "approval" && <ApprovalConfig block={block} />}
{(block.type === "labelRevision" ||
block.type === "labelQuantity" ||
block.type === "labelTracking") && (
@@ -575,6 +580,60 @@ function TermsConfig({ block }: { block: TermsBlock }) {
);
}
+/**
+ * The Approval block: its heading, whether the signature prints, and the
+ * caption under the line. The caption starts as the approver and the date, so
+ * "Approved by … on …" is written here rather than in a separate block.
+ */
+function ApprovalConfig({ block }: { block: ApprovalBlock }) {
+ const { updateBlock, documentType } = useDocumentTemplate();
+ const [nonce, setNonce] = useState(0);
+ const knownTokens = getMergeFields(documentType).map((f) => f.token);
+ const caption = hasDocContent(block.content)
+ ? (block.content as JSONContent)
+ : DEFAULT_APPROVAL_CAPTION;
+
+ const insertField = (snippet: string) => {
+ updateBlock(block.id, { content: appendText(caption, snippet) });
+ setNonce((n) => n + 1);
+ };
+
+ return (
+ <div className="flex flex-col gap-3">
+ <p className="text-xs text-muted-foreground">
+ Prints once the order is approved.
+ </p>
+ <div className="flex flex-col gap-1.5">
+ <Label htmlFor="approval-heading">Heading</Label>
+ <Input
+ id="approval-heading"
+ value={block.heading ?? DEFAULT_APPROVAL_HEADING}
+ onChange={(e) => updateBlock(block.id, { heading: e.target.value })}
+ />
+ </div>
+ <ToggleRow
+ label="Show signature"
+ checked={block.showSignature ?? true}
+ onChange={(v) => updateBlock(block.id, { showSignature: v })}
+ />
+ <div className="flex flex-col gap-1.5">
+ <div className="flex items-center justify-between">
+ <Label>Caption</Label>
+ <MergeFieldMenu onInsert={insertField} label="Insert field" />
+ </div>
+ <Editor
+ key={`${block.id}-${nonce}`}
+ className="min-h-[96px] w-full rounded-md border bg-background p-3"
+ initialValue={caption}
+ onChange={(content) => updateBlock(block.id, { content })}
+ highlightTokens={knownTokens}
+ disableFileUpload
+ />
+ </div>
+ </div>
+ );
+}
+
function KeyValueConfig({ block }: { block: KeyValueBlock }) {
const { updateBlock } = useDocumentTemplate();
const rows = block.rows ?? [];
diff --git a/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json b/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
index a9b1b7168f..3e175d88c1 100644
--- a/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
+++ b/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
@@ -1531,7 +1531,7 @@
{"name":"settings_getCustomFieldsTables","classification":"READ","schema":"cd40ae40fad5","response":"b1e2b7dc7754","permission":"settings:view","paginates":true},
{"name":"settings_getDocumentSections","classification":"READ","schema":"31b84d65b2ac","response":"d8b65982e0d9","permission":"settings:view","paginates":false},
{"name":"settings_getDocumentTemplate","classification":"READ","schema":"2a2940399e72","response":"99cae633d7cb","permission":"settings:view","paginates":false},
- {"name":"settings_getDocumentTemplateConfig","classification":"READ","schema":"2a2940399e72","response":"9d816ad27ae2","permission":"settings:view","paginates":false},
+ {"name":"settings_getDocumentTemplateConfig","classification":"READ","schema":"2a2940399e72","response":"586da3c785a5","permission":"settings:view","paginates":false},
{"name":"settings_getEmployeeCompanies","classification":"READ","schema":"31b84d65b2ac","response":"5783a32e0f4a","permission":"settings:view","paginates":false},
{"name":"settings_getIndustries","classification":"READ","schema":"31b84d65b2ac","response":"5dcce0f224dd","permission":"settings:view","paginates":false},
{"name":"settings_getIntegration","classification":"READ","schema":"7f8214d1083f","response":"099545249106","permission":"settings:view","paginates":false},
@@ -1553,7 +1553,7 @@
{"name":"settings_removePrinterRoute","classification":"DESTRUCTIVE","schema":"3797626bd17e","response":"3797626bd17e","permission":"settings:update","paginates":false},
{"name":"settings_resolveSections","classification":"WRITE","schema":"1ddda22ecba8","response":"32e51b029d79","permission":"settings:update","paginates":false},
{"name":"settings_saveDocumentSection","classification":"WRITE","schema":"8a0f21626132","response":"d77a04e8c53e","permission":"settings:update","paginates":false},
- {"name":"settings_saveDocumentTemplate","classification":"WRITE","schema":"ed92a276fb6b","response":"f1822dd9c8ab","permission":"settings:update","paginates":false},
+ {"name":"settings_saveDocumentTemplate","classification":"WRITE","schema":"d7e28d85cf1d","response":"f1822dd9c8ab","permission":"settings:update","paginates":false},
{"name":"settings_setIntegrationSyncEnabled","classification":"WRITE","schema":"fa07001f8501","response":"4111dc6445bb","permission":"settings:update","paginates":false},
{"name":"settings_transitionSyncOperations","classification":"WRITE","schema":"c5a1f2594d65","response":"401e1aae225f","permission":"settings:update","paginates":false},
{"name":"settings_updateAccountingSettings","classification":"WRITE","schema":"ecf0d5091645","response":"70bcf2b87ee3","permission":"settings:update","paginates":false},
diff --git a/packages/documents/src/pdf/blocks/purchaseOrder/ApprovalBlock.tsx b/packages/documents/src/pdf/blocks/purchaseOrder/ApprovalBlock.tsx
index 157bbfaf65..b69f670327 100644
--- a/packages/documents/src/pdf/blocks/purchaseOrder/ApprovalBlock.tsx
+++ b/packages/documents/src/pdf/blocks/purchaseOrder/ApprovalBlock.tsx
@@ -2,41 +2,61 @@
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
-import { formatDate } from "@carbon/utils";
import { Image, Text, View } from "@react-pdf/renderer";
+import type { ApprovalBlock as ApprovalBlockType } from "../../../template";
+import {
+ DEFAULT_APPROVAL_CAPTION,
+ DEFAULT_APPROVAL_HEADING,
+ interpolateContent
+} from "../../../template";
+import { Note } from "../../components";
+import { hasContent } from "../resolveTerms";
import { useTw } from "../tw";
import type { PurchaseOrderData } from "./types";
/**
- * The approver's signature, name and approval date. Prints nothing until the
- * order is approved, so it can sit on every saved template.
+ * The approver's signature over a line, under a heading, with a caption the
+ * template can edit (the approver and the date by default). Prints nothing
+ * until the order is approved, so it can sit on every saved template.
*/
-export function ApprovalBlock({ data }: { data: PurchaseOrderData }) {
+export function ApprovalBlock({
+ block,
+ data
+}: {
+ block: ApprovalBlockType;
+ data: PurchaseOrderData;
+}) {
const tw = useTw();
- const { approval, locale } = data;
+ const { approval, vars } = data;
if (!approval) return null;
+ const heading = block.heading ?? DEFAULT_APPROVAL_HEADING;
+ const showSignature = block.showSignature ?? true;
+ const caption = interpolateContent(
+ block.content && hasContent(block.content)
+ ? block.content
+ : DEFAULT_APPROVAL_CAPTION,
+ vars
+ );
+
return (
- <View wrap={false} style={tw("mt-4 mb-4 w-[220px]")}>
- <Text style={tw("text-[9px] font-bold uppercase text-gray-600 mb-1")}>
- Approved By
- </Text>
- <View style={tw("h-[40px] justify-end")}>
- {approval.signature ? (
- <Image
- src={approval.signature}
- style={{ maxHeight: 40, maxWidth: 200, objectFit: "contain" }}
- />
- ) : null}
- </View>
- <View style={tw("border-t border-gray-400 mt-1 pt-1")}>
- <Text style={tw("text-[10px] text-gray-800")}>
- {approval.approvedBy ?? ""}
- </Text>
- <Text style={tw("text-[9px] text-gray-600")}>
- {formatDate(approval.approvedDate, undefined, locale)}
+ <View wrap={false} style={tw("mt-4 mb-4 w-[240px]")}>
+ {heading.trim() ? (
+ <Text style={tw("text-[9px] font-bold uppercase text-gray-600 mb-1")}>
+ {heading}
</Text>
- </View>
+ ) : null}
+ {showSignature ? (
+ <View style={tw("h-[40px] justify-end border-b border-gray-400 mb-1")}>
+ {approval.signature ? (
+ <Image
+ src={approval.signature}
+ style={{ maxHeight: 40, maxWidth: 200, objectFit: "contain" }}
+ />
+ ) : null}
+ </View>
+ ) : null}
+ <Note content={caption} />
</View>
);
}
diff --git a/packages/documents/src/pdf/blocks/purchaseOrder/registry.tsx b/packages/documents/src/pdf/blocks/purchaseOrder/registry.tsx
index 428f00c4de..5a24e33f01 100644
--- a/packages/documents/src/pdf/blocks/purchaseOrder/registry.tsx
+++ b/packages/documents/src/pdf/blocks/purchaseOrder/registry.tsx
@@ -32,7 +32,10 @@ export const purchaseOrderBlockRegistry: Partial<
) : null,
terms: ({ block, data }) =>
block.type === "terms" ? <TermsBlock block={block} data={data} /> : null,
- approval: ({ data }) => <ApprovalBlock data={data} />,
+ approval: ({ block, data }) =>
+ block.type === "approval" ? (
+ <ApprovalBlock block={block} data={data} />
+ ) : null,
customField: ({ block, data }) =>
block.type === "customField" ? (
<CustomFieldBlock
diff --git a/packages/documents/src/pdf/components/Note.tsx b/packages/documents/src/pdf/components/Note.tsx
index 3411c81fd4..4e5f9c172c 100644
--- a/packages/documents/src/pdf/components/Note.tsx
+++ b/packages/documents/src/pdf/components/Note.tsx
@@ -116,6 +116,10 @@ function makeConvert(theme: DocumentTheme) {
case "text":
return node.text;
+ // Shift+Enter in the editor: a new line inside the same paragraph.
+ case "hardBreak":
+ return "\n";
+
default:
return null;
}
diff --git a/packages/documents/src/template/defaults.ts b/packages/documents/src/template/defaults.ts
index 0284dccc68..a3a10c8298 100644
--- a/packages/documents/src/template/defaults.ts
+++ b/packages/documents/src/template/defaults.ts
@@ -312,6 +312,27 @@ export const BLOCK_META: Record<DocumentBlockType, BlockMeta> = {
};
/** Block types a user may append, in menu order. */
+/** The Approval block's heading when the template sets none. */
+export const DEFAULT_APPROVAL_HEADING = "Approved By";
+
+/**
+ * The Approval block's caption under the signature line when the template
+ * sets none: the approver, then the approval date.
+ */
+export const DEFAULT_APPROVAL_CAPTION: JSONContent = {
+ type: "doc",
+ content: [
+ {
+ type: "paragraph",
+ content: [
+ { type: "text", text: "{order.approvedBy}" },
+ { type: "hardBreak" },
+ { type: "text", text: "{order.approvedDate}" }
+ ]
+ }
+ ]
+};
+
export const ADDABLE_BLOCK_TYPES = (
Object.keys(BLOCK_META) as DocumentBlockType[]
).filter((type) => BLOCK_META[type].addable);
diff --git a/packages/documents/src/template/schema.ts b/packages/documents/src/template/schema.ts
index 99141e67c7..d5c9bfaf92 100644
--- a/packages/documents/src/template/schema.ts
+++ b/packages/documents/src/template/schema.ts
@@ -129,8 +129,20 @@ const issueDetailsBlock = builtInBlock("issueDetails");
const associationsBlock = builtInBlock("associations");
const actionTasksBlock = builtInBlock("actionTasks");
const reviewersBlock = builtInBlock("reviewers");
-/** Who approved the document: signature, name and date. Empty until approved. */
-const approvalBlock = builtInBlock("approval");
+/**
+ * Who approved the document: a heading, the approver's signature over a line,
+ * and a rich-text caption with merge fields (the approver and the date by
+ * default). Prints nothing until the document is approved.
+ */
+const approvalBlock = z.object({
+ ...baseFields,
+ type: z.literal("approval"),
+ /** Absent: "Approved By". An empty string prints no heading. */
+ heading: z.string().optional(),
+ showSignature: z.boolean().optional(),
+ /** Empty: `DEFAULT_APPROVAL_CAPTION`. */
+ content: jsonContentSchema.optional()
+});
/** Tracking-label fields (data-bound; one per label element). */
const labelHeadingBlock = builtInBlock("labelHeading");
/** A label field whose printed name (the prefix before the value) is editable. */
@@ -516,6 +528,7 @@ export type AssociationsBlock = Extract<
>;
export type ActionTasksBlock = Extract<DocumentBlock, { type: "actionTasks" }>;
export type ReviewersBlock = Extract<DocumentBlock, { type: "reviewers" }>;
+export type ApprovalBlock = Extract<DocumentBlock, { type: "approval" }>;
export type LabelHeadingBlock = Extract<
DocumentBlock,
{ type: "labelHeading" }