@ryanyahya/opendoc 0.4.0

package/starter/templates/invoice/examples/long.json

@@ -0,0 +1,241 @@
+{
+  "schemaVersion": 1,
+  "title": "Website content services",
+  "number": "SAMPLE-INV-001",
+  "issuedOn": "2026-09-08",
+  "dueOn": "2026-09-22",
+  "reference": "SAMPLE-Q-001",
+  "seller": {
+    "name": "Example Studio",
+    "details": "Studio address placeholder\nContact details placeholder"
+  },
+  "customer": {
+    "name": "Example Client",
+    "details": "Client address placeholder\nAttention: project contact"
+  },
+  "synthetic": true,
+  "pricing": {
+    "currency": {
+      "code": "USD",
+      "decimals": 2
+    },
+    "items": [
+      {
+        "id": "service-1",
+        "description": "Illustrative service 1: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-2",
+        "description": "Illustrative service 2: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-3",
+        "description": "Illustrative service 3: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-4",
+        "description": "Illustrative service 4: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-5",
+        "description": "Illustrative service 5: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-6",
+        "description": "Illustrative service 6: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-7",
+        "description": "Illustrative service 7: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-8",
+        "description": "Illustrative service 8: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-9",
+        "description": "Illustrative service 9: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-10",
+        "description": "Illustrative service 10: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-11",
+        "description": "Illustrative service 11: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-12",
+        "description": "Illustrative service 12: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-13",
+        "description": "Illustrative service 13: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-14",
+        "description": "Illustrative service 14: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-15",
+        "description": "Illustrative service 15: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-16",
+        "description": "Illustrative service 16: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-17",
+        "description": "Illustrative service 17: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-18",
+        "description": "Illustrative service 18: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-19",
+        "description": "Illustrative service 19: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-20",
+        "description": "Illustrative service 20: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-21",
+        "description": "Illustrative service 21: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-22",
+        "description": "Illustrative service 22: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-23",
+        "description": "Illustrative service 23: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-24",
+        "description": "Illustrative service 24: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-25",
+        "description": "Illustrative service 25: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-26",
+        "description": "Illustrative service 26: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-27",
+        "description": "Illustrative service 27: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "service-28",
+        "description": "Illustrative service 28: preparation, delivery, and review of a clearly described item for this example.",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      }
+    ],
+    "discount": "25.00",
+    "tax": {
+      "label": "Illustrative tax",
+      "ratePercent": "10"
+    }
+  },
+  "amountPaid": "320.00",
+  "paymentInstructions": "Payment details placeholder. Supply the agreed method and verified recipient details before issuing a real invoice.",
+  "paymentReference": "SAMPLE-INV-001",
+  "notes": [
+    {
+      "id": "scope",
+      "title": "Scope note",
+      "text": "Illustrative services only. Replace the sample with the actual goods or services and any necessary supporting details."
+    },
+    {
+      "id": "supporting-detail",
+      "title": "Supporting detail",
+      "text": "This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. This is an illustrative note about the services described in the invoice. No real delivery or payment is being claimed. "
+    }
+  ]
+}

package/starter/templates/invoice/examples/sparse.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "title": "Sample invoice",
+  "number": "SAMPLE-INV-001",
+  "issuedOn": "2026-09-08",
+  "dueOn": null,
+  "reference": null,
+  "seller": {
+    "name": "Example Studio"
+  },
+  "customer": {
+    "name": "Example Customer"
+  },
+  "synthetic": true,
+  "pricing": {
+    "currency": {
+      "code": "USD",
+      "decimals": 2
+    },
+    "items": [
+      {
+        "id": "service",
+        "description": "Illustrative service",
+        "quantity": "1",
+        "unitPrice": "100.00"
+      }
+    ]
+  },
+  "amountPaid": null,
+  "paymentInstructions": null,
+  "paymentReference": null,
+  "notes": []
+}

package/starter/templates/invoice/examples/typical.json

@@ -0,0 +1,61 @@
+{
+  "schemaVersion": 1,
+  "title": "Website content services",
+  "number": "SAMPLE-INV-001",
+  "issuedOn": "2026-09-08",
+  "dueOn": "2026-09-22",
+  "reference": "SAMPLE-Q-001",
+  "seller": {
+    "name": "Example Studio",
+    "details": "Studio address placeholder\nContact details placeholder"
+  },
+  "customer": {
+    "name": "Example Client",
+    "details": "Client address placeholder\nAttention: project contact"
+  },
+  "synthetic": true,
+  "pricing": {
+    "currency": {
+      "code": "USD",
+      "decimals": 2
+    },
+    "items": [
+      {
+        "id": "planning",
+        "description": "Content planning workshop",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "writing",
+        "description": "Website copy package: supplied scope and agreed deliverables",
+        "quantity": "1",
+        "unit": "package",
+        "unitPrice": "600.00"
+      },
+      {
+        "id": "review",
+        "description": "Review and revision sessions",
+        "quantity": "3",
+        "unit": "hours",
+        "unitPrice": "75.00"
+      }
+    ],
+    "discount": "25.00",
+    "tax": {
+      "label": "Illustrative tax",
+      "ratePercent": "10"
+    }
+  },
+  "amountPaid": "320.00",
+  "paymentInstructions": "Payment details placeholder. Supply the agreed method and verified recipient details before issuing a real invoice.",
+  "paymentReference": "SAMPLE-INV-001",
+  "notes": [
+    {
+      "id": "scope",
+      "title": "Scope note",
+      "text": "Illustrative services only. Replace the sample with the actual goods or services and any necessary supporting details."
+    }
+  ]
+}

package/starter/templates/invoice/index.tsx

@@ -0,0 +1,57 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { TextSlot, Block, Document, Heading, Paragraph, Strong, Page } from 'opendoc';
+import { defineTemplate } from 'opendoc/template';
+import { themePage, type DocTheme } from 'opendoc/themes';
+import { BusinessLogo } from '../_shared/BusinessLogo';
+import { Pricing } from '../_shared/Pricing';
+import { money } from '../_shared/commerce';
+import { calculateInvoice, parseInvoice, type InvoiceData } from './schema';
+export { calculateInvoice, parseInvoice } from './schema';
+export type { InvoiceData } from './schema';
+
+export function Invoice({ data, theme, titleStyle, logo }: { data: InvoiceData; theme: DocTheme; titleStyle?: F.Style; logo?: ReactNode }) {
+  const balance = calculateInvoice(data);
+  const layoutTheme = theme.design ? theme : { ...theme, fontSize: 10.5, lineHeight: 1.4, paragraphGap: 8 };
+  return <Document title={data.title} author={data.seller.name} theme={layoutTheme}>
+    <Page {...themePage(theme, { top: 48, bottom: 52, left: 48, right: 48 })} style={{ lineBreaking: 'greedy', ...theme.design?.page?.style }}>
+      {(!theme.design || theme.runningFooter) && <F.Fixed position="footer"><F.Text style={{ fontFamily: theme.design ? theme.body : undefined, fontSize: 8, color: theme.muted, textAlign: 'right', ...theme.design?.furniture?.text, ...theme.design?.furniture?.footer }}>{data.synthetic ? 'Illustrative invoice · ' : ''}{theme.design?.furniture?.pageNumber === 'total' ? '{{pageNumber}} / {{totalPages}}' : '{{pageNumber}}'}</F.Text></F.Fixed>}
+      <F.View style={theme.design?.title?.block}>
+        <F.View wrap={false} style={{ flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', marginBottom: 8 }}>
+          <Paragraph id="invoice-label" role="label" baseStyle={{ fontSize: 9, letterSpacing: 0.8, color: theme.muted, marginBottom: 0 }} style={theme.design?.title?.eyebrow}>INVOICE</Paragraph>
+          <BusinessLogo id="invoice-logo" theme={theme}>{logo}</BusinessLogo>
+        </F.View>
+        <Heading id="invoice-title" level={1} baseStyle={{ fontSize: 28, lineHeight: 1.15, marginBottom: 12 }} style={{ ...theme.design?.title?.heading, ...titleStyle }}><TextSlot slot="title" field={['title']}>{data.title}</TextSlot></Heading>
+        <Paragraph id="invoice-number" role="small" baseStyle={{ fontSize: 9, marginBottom: 8 }} style={theme.design?.title?.byline}>No. <TextSlot slot="number" field={['number']}>{data.number}</TextSlot>{data.reference ? <> · Reference: <TextSlot slot="reference" field={['reference']}>{data.reference}</TextSlot></> : ''}</Paragraph>
+        <Block id="invoice-balance-summary"><F.View wrap={false} style={{ flexDirection: 'row', gap: 24, marginBottom: 12 }}>
+          <F.View style={{ flex: 1 }}>
+            <F.Text style={{ fontSize: 9.5, marginBottom: 4, ...theme.design?.typography?.small }}>Issued <TextSlot slot="issuedOn" field={['issuedOn']}>{data.issuedOn}</TextSlot></F.Text>
+            {data.dueOn && <F.Text style={{ fontSize: 9.5, ...theme.design?.typography?.small }}>Due <TextSlot slot="dueOn" field={['dueOn']}>{data.dueOn}</TextSlot></F.Text>}
+          </F.View>
+          <F.View style={{ flex: 1 }}>
+            <F.Text style={{ fontSize: 8.5, color: theme.muted, textAlign: 'right', marginBottom: 5, ...theme.design?.typography?.small }}>Amount due</F.Text>
+            <F.Text style={{ fontSize: 21, fontWeight: 600, ...theme.design?.typography?.h2, textAlign: 'right' }}><TextSlot slot="amount-due" reason="Calculated value—ask your agent to change its inputs.">{money(balance.balanceMinor, data.pricing.currency)}</TextSlot></F.Text>
+          </F.View>
+        </F.View></Block>
+      </F.View>
+      <Block id="invoice-parties"><F.View wrap={false} style={{ flexDirection: 'row', gap: 28, marginBottom: 8 }}>
+        {([['From', data.seller, 'seller'], ['Bill to', data.customer, 'customer']] as const).map(([label, party, partyField]) => <F.View key={label} style={{ flex: 1 }}>
+          <F.Text style={{ fontSize: 8.5, color: theme.muted, marginBottom: 5, ...theme.design?.typography?.small }}>{label}</F.Text>
+          <F.Text style={{ fontWeight: 600, marginBottom: 5 }}><TextSlot slot={`${partyField}-name`} field={[partyField, 'name']}>{party.name}</TextSlot></F.Text>
+          {party.details && <F.Text style={{ fontSize: 9.5, color: theme.muted, ...theme.design?.typography?.small }}><TextSlot slot={`${partyField}-details`} field={[partyField, 'details']}>{party.details}</TextSlot></F.Text>}
+        </F.View>)}
+      </F.View></Block>
+      {data.synthetic && <Paragraph id="invoice-sample-notice" role="small" baseStyle={{ fontSize: 9, color: theme.muted }}>Illustrative invoice. All parties, amounts, dates, and payment details are synthetic. This is not a payment request.</Paragraph>}
+      {data.introduction && <Paragraph id="invoice-introduction"><TextSlot slot="introduction" field={['introduction']}>{data.introduction}</TextSlot></Paragraph>}
+      <Pricing data={data.pricing} theme={theme} totalLabel={data.amountPaid === undefined ? 'Amount due' : 'Invoice total'} paymentReceived={data.amountPaid === undefined ? undefined : balance.paidMinor} />
+      {data.paymentInstructions && <Paragraph id="invoice-payment-instructions" role="small" baseStyle={{ fontSize: 9.5 }}><Strong>Payment instructions. </Strong><TextSlot slot="paymentInstructions" field={['paymentInstructions']}>{data.paymentInstructions}</TextSlot></Paragraph>}
+      {data.paymentReference && <Paragraph id="invoice-payment-reference" role="small" baseStyle={{ fontSize: 9.5 }}><Strong>Payment reference. </Strong><TextSlot slot="paymentReference" field={['paymentReference']}>{data.paymentReference}</TextSlot></Paragraph>}
+      {data.notes.map(note => <Paragraph key={note.id} id={`invoice-note-${note.id.length}-${note.id}`} role="small" baseStyle={{ fontSize: 9.5, marginBottom: 10 }}><Strong><TextSlot slot="title" field={['notes', { id: note.id }, 'title']}>{note.title}</TextSlot>. </Strong><TextSlot slot="text" field={['notes', { id: note.id }, 'text']}>{note.text}</TextSlot></Paragraph>)}
+    </Page>
+  </Document>;
+}
+export const invoiceTemplate = (theme: DocTheme, { logo }: { logo?: ReactNode } = {}) => defineTemplate<InvoiceData>({
+  parse: parseInvoice,
+  meta: data => ({ title: data.title, description: `Invoice ${data.number} for ${data.customer.name}.`, kind: 'report', theme: theme.id, author: data.seller.name }),
+  render: data => <Invoice data={data} theme={theme} logo={logo} />,
+});

package/starter/templates/invoice/preview.tsx

@@ -0,0 +1,12 @@
+import { neutral } from '../../themes';
+import { type DocTheme } from 'opendoc/themes';
+import { invoiceTemplate, parseInvoice } from './index';
+import typical from './examples/typical.json';
+import sparse from './examples/sparse.json';
+import long from './examples/long.json';
+export const meta = invoiceTemplate(neutral).meta(parseInvoice(typical));
+export function Specimen({ length = 'typical', theme = neutral }: { length?: 'sparse' | 'typical' | 'long'; theme?: DocTheme } = {}) {
+  const template = invoiceTemplate(theme);
+  return template.render(template.parse({ sparse, typical, long }[length]));
+}
+export default Specimen;

package/starter/templates/invoice/schema.ts

@@ -0,0 +1,45 @@
+import { calculatePricing, date, object, optionalText, parsePricing, paymentMinor, text, type PricingData } from '../_shared/commerce';
+
+export interface InvoiceData {
+  schemaVersion: 1; title: string; number: string; issuedOn: string; dueOn?: string; reference?: string;
+  seller: { name: string; details?: string }; customer: { name: string; details?: string };
+  synthetic: boolean; introduction?: string; pricing: PricingData; amountPaid?: string;
+  paymentInstructions?: string; paymentReference?: string; notes: { id: string; title: string; text: string }[];
+}
+
+export function calculateInvoice(data: InvoiceData) {
+  const totals = calculatePricing(data.pricing);
+  const paidMinor = data.amountPaid === undefined ? 0n : paymentMinor(data.amountPaid, data.pricing.currency, 'invoice.amountPaid');
+  if (paidMinor > totals.totalMinor) throw new Error('invoice.amountPaid: cannot exceed the invoice total; a credit balance needs a separate explicit treatment.');
+  return { ...totals, paidMinor, balanceMinor: totals.totalMinor - paidMinor };
+}
+
+export function parseInvoice(input: unknown): InvoiceData {
+  const value = object(input, ['schemaVersion', 'title', 'number', 'issuedOn', 'dueOn', 'reference', 'seller', 'customer', 'synthetic', 'introduction', 'pricing', 'amountPaid', 'paymentInstructions', 'paymentReference', 'notes'], 'invoice');
+  if (value.schemaVersion !== 1) throw new Error('invoice.schemaVersion: expected 1.');
+  if (typeof value.synthetic !== 'boolean') throw new Error('invoice.synthetic: explicitly supply true or false.');
+  const party = (input: unknown, path: string) => {
+    const data = object(input, ['name', 'details'], path);
+    return { name: text(data.name, `${path}.name`, 180, 1), details: optionalText(data.details, `${path}.details`, 700, 8) };
+  };
+  const issuedOn = date(value.issuedOn, 'invoice.issuedOn');
+  const dueOn = value.dueOn === undefined || value.dueOn === null ? undefined : date(value.dueOn, 'invoice.dueOn');
+  if (dueOn && dueOn < issuedOn) throw new Error('invoice.dueOn: must be on or after issuedOn.');
+  if (value.notes !== undefined && !Array.isArray(value.notes)) throw new Error('invoice.notes: expected an array.');
+  const seen = new Set<string>();
+  const notes = ((value.notes ?? []) as unknown[]).map((raw, index) => {
+    const path = `invoice.notes[${index}]`, note = object(raw, ['id', 'title', 'text'], path), id = text(note.id, `${path}.id`, 100);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id) || seen.has(id)) throw new Error(`${path}.id: supply a unique stable ID.`);
+    seen.add(id);
+    return { id, title: text(note.title, `${path}.title`, 120), text: text(note.text, `${path}.text`) };
+  });
+  const data: InvoiceData = {
+    schemaVersion: 1, title: text(value.title, 'invoice.title', 300), number: text(value.number, 'invoice.number', 80, 1), issuedOn, dueOn,
+    reference: optionalText(value.reference, 'invoice.reference', 180, 1), seller: party(value.seller, 'invoice.seller'), customer: party(value.customer, 'invoice.customer'),
+    synthetic: value.synthetic, introduction: optionalText(value.introduction, 'invoice.introduction'), pricing: parsePricing(value.pricing),
+    amountPaid: value.amountPaid === undefined || value.amountPaid === null ? undefined : text(value.amountPaid, 'invoice.amountPaid', 20, 1),
+    paymentInstructions: optionalText(value.paymentInstructions, 'invoice.paymentInstructions'), paymentReference: optionalText(value.paymentReference, 'invoice.paymentReference', 180, 1), notes,
+  };
+  calculateInvoice(data);
+  return data;
+}

package/starter/templates/invoice/starter.tsx

@@ -0,0 +1,12 @@
+import { bindTemplate } from 'opendoc/template';
+import { invoiceTemplate } from '../../templates/invoice';
+// @ts-ignore The selected local theme module is inserted when this starter becomes a document.
+import { theme } from "__OPENDOC_THEME_MODULE__";
+import data from './data.json';
+const documentId = "__OPENDOC_DOCUMENT_ID__";
+const themeId = "__OPENDOC_THEME__";
+// Bind a shared logo, pass <Logo slot="primary" /> through the logo option, or pass null to omit it.
+const bound = bindTemplate(invoiceTemplate(theme), data);
+export const meta = { ...bound.meta, theme: themeId };
+export const provenance = { template: 'templates/invoice/index.tsx', dataFile: `documents/${documentId}/data.json` };
+export default bound.Document;

package/starter/templates/invoice/template.json

@@ -0,0 +1,11 @@
+{
+  "name": "Invoice",
+  "description": "Invoice references and dates, seller and customer details, itemized charges, and a clear amount due with optional payment instructions and recorded payments.",
+  "format": "A4 \u00b7 Business invoice",
+  "structure": [
+    "The opening pairs issue and optional due dates with a prominent calculated amount due, below the title and invoice reference. An optional logo slot sits at the upper right.",
+    "Seller and customer details sit side by side, followed by line items with repeating table headers.",
+    "Totals align on the right. Supplied payments reduce the calculated balance; the same amount due appears in the opening and the totals.",
+    "Optional payment instructions, payment reference, and supporting notes follow the charges. Each invoice owns its data and longer content flows naturally."
+  ]
+}

package/starter/templates/literary-text/AGENTS.md

@@ -0,0 +1,9 @@
+# Literary text
+
+Use this as a soft foundation for the writing, with room for variation and creativity. Its starting character is a restrained, slightly lowered title, an intimate reading measure, relaxed leading, and quiet page numbers. These are defaults, not a fixed rule system. A long title may need smaller type through `titleStyle`; another passage may benefit from different spacing, a different opening alignment, or a wider measure. Serve the voice and reading rhythm rather than reproducing the specimen.
+
+The author line, epigraph, and scene breaks are optional. Do not add them merely to fill space, and do not prescribe a plot, chapter structure, or writing method. An epigraph is supplied inline text; include attribution when needed and never invent a quotation. The native starting layout uses flush paragraphs with small gaps. It deliberately does not use the custom Prose indentation helper.
+
+Use ordinary Paragraph blocks and native Forme flow. SceneBreak takes a stable id and a short lead paragraph; its native unbreakable View keeps the marker with that opening. Put the remaining scene text in following paragraphs so it can paginate. Avoid custom fitting, manual line splitting, absolute-positioned body text, and renderer patches. Preserve IDs, quotations, and reference accuracy. Keep changes for one document local or use options that preserve shared defaults.
+
+The caller's theme supplies visual hierarchy, rhythm, and component treatments; catalog previews use Neutral. Review the adapted PDF. Shared changes also need short and long specimens, scene breaks near page boundaries, a second theme, and a working starter. Preserve unrelated documents and templates.

package/starter/templates/literary-text/README.md

@@ -0,0 +1,11 @@
+# Literary text
+
+A flexible prose layout for stories, chapters, and longer creative writing. Native Forme handles wrapping and pagination. Defaults are A4 portrait with 112-point side and 64-point top/bottom margins, a 371-point reading column, 11.5/17.825-point body type, and 7-point paragraph gaps. The centered 26-point title has additional opening space above it. Page numbers sit centrally below the text.
+
+`LiteraryText` accepts `title`, `theme`, and ordinary OpenDoc blocks as `children`. Optional `author` and inline `epigraph` supply opening material. `titleStyle` accepts native styles for smaller titles, alternate alignment, or different opening spacing. Fonts and colors come from the theme. Paragraphs begin flush; there is no indentation shim or custom typesetting. The layout is a starting point, not a prescribed literary style.
+
+Use `<SceneBreak id="return-to-the-house" lead="The first short paragraph of the new scene." />` for a quiet three-asterisk marker. It keeps the marker with its short lead using a native unbreakable View. The lead is limited to 700 characters to keep this small group page-sized; place the rest in normal Paragraph blocks. Its comment targets are `<id>-marker` and `<id>-lead`. Keep these IDs stable when moving scenes. Omit scene markers when the writing does not need them.
+
+Long titles and epigraphs remain breakable. If an opening becomes disproportionate, adapt it with ordinary styles after reviewing the PDF. Supply verified `references` and use existing Cite blocks if the work needs references; otherwise the reference section is omitted. No chapter order or content outline is imposed.
+
+`preview.tsx` uses explicitly identified placeholder prose, not a fictional quotation attributed to a real author. Its Specimen accepts sparse, typical, and long lengths plus an optional theme for review. The default catalog proof stays Neutral. `starter.tsx` creates a normal linked document. See [AGENTS.md](AGENTS.md) for the intended flexibility and native-layout boundaries.

package/starter/templates/literary-text/index.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { TextSlot, Document, Heading, Paragraph, References, Page } from 'opendoc';
+import { themePage, type DocTheme } from 'opendoc/themes';
+
+export function LiteraryText({ title, theme, author, epigraph, titleStyle, children, references }: {
+  title: string; theme: DocTheme; author?: string; epigraph?: ReactNode; titleStyle?: F.Style;
+  children: ReactNode; references?: Parameters<typeof Document>[0]['references'];
+}) {
+  const layoutTheme: DocTheme = theme.design ? theme : { ...theme, fontSize: 11.5, lineHeight: 1.55, paragraphGap: 7 };
+  return <Document title={title} author={author} theme={layoutTheme} references={references}>
+    <Page {...themePage(theme, { top: 64, bottom: 64, left: 112, right: 112 })} style={{ lineBreaking: 'greedy', ...theme.design?.page?.style }}>
+      {(!theme.design || theme.runningFooter) && <F.Fixed position="footer"><F.Text style={{ fontFamily: theme.body, fontSize: 8, color: theme.muted, textAlign: 'center', ...theme.design?.furniture?.text, ...theme.design?.furniture?.footer }}>{theme.design?.furniture?.pageNumber === 'total' ? '{{pageNumber}} / {{totalPages}}' : '{{pageNumber}}'}</F.Text></F.Fixed>}
+      <F.View style={theme.design?.title?.block}>
+        <Heading id="literary-title" level={1} baseStyle={{ fontSize: 26, lineHeight: 1.2, textAlign: 'center', marginTop: 56, marginBottom: 16 }} style={{ ...theme.design?.title?.heading, ...titleStyle }}><TextSlot slot="title" from="title">{title}</TextSlot></Heading>
+        {author && <Paragraph id="literary-author" role="small" baseStyle={{ fontSize: 10, color: theme.muted, textAlign: 'center', marginBottom: 20 }} style={theme.design?.title?.byline}><TextSlot slot="author" from="author">{author}</TextSlot></Paragraph>}
+        {epigraph && <Paragraph id="literary-epigraph" role="lead" baseStyle={{ fontSize: 11, fontStyle: 'italic', lineHeight: 1.45, marginLeft: 24, marginRight: 24, marginTop: 10, marginBottom: 14 }}><TextSlot slot="epigraph" from="epigraph">{epigraph}</TextSlot></Paragraph>}
+      </F.View>
+      <F.View style={{ marginTop: 28 }}>{children}<References headingBaseStyle={{ fontSize: 12, marginTop: 24, marginBottom: 8 }} /></F.View>
+    </Page>
+  </Document>;
+}
+
+/** Keep a scene marker with its short opening; subsequent paragraphs flow normally. */
+export function SceneBreak({ id, lead }: { id: string; lead: string }) {
+  if (!lead.trim() || lead.length > 700) throw new Error('SceneBreak needs a short opening paragraph of 1–700 characters. Put the rest in following Paragraph blocks.');
+  return <F.View wrap={false}>
+    <Paragraph id={`${id}-marker`} role="small" baseStyle={{ textAlign: 'center', fontSize: 10, marginTop: 18, marginBottom: 18 }}>* * *</Paragraph>
+    <Paragraph id={`${id}-lead`}><TextSlot slot="lead" from="lead">{lead}</TextSlot></Paragraph>
+  </F.View>;
+}

package/starter/templates/literary-text/preview.tsx

@@ -0,0 +1,20 @@
+import { Paragraph } from 'opendoc';
+import { neutral } from '../../themes';
+import { type DocTheme } from 'opendoc/themes';
+import { LiteraryText, SceneBreak } from './index';
+
+export const meta = { title: 'Literary text', description: 'A Neutral reading specimen with placeholder prose.', kind: 'article' as const, theme: 'neutral' };
+const paragraph = 'This is placeholder prose for the reading column. It makes the shape of a passage visible: the length of a line, the pause between paragraphs, and the quiet space around the text. In an authored work, the writer’s own sentences would set the pace. The page should support that voice and let a long passage continue naturally, without asking the writer to fit the story into a predetermined outline.';
+
+export function Specimen({ length = 'typical', theme = neutral }: { length?: 'sparse' | 'typical' | 'long'; theme?: DocTheme } = {}) {
+  const sparse = length === 'sparse';
+  return <LiteraryText title={meta.title} theme={theme} author={sparse ? undefined : 'Author name'} epigraph={sparse ? undefined : 'An optional epigraph can sit here. This is a layout placeholder, not a quotation.'}>
+    {Array.from({ length: sparse ? 1 : length === 'long' ? 15 : 3 }, (_, index) => <Paragraph key={index} id={`specimen-paragraph-${index + 1}`}>{paragraph}</Paragraph>)}
+    {!sparse && <>
+      <SceneBreak id="specimen-scene" lead="The next scene begins with this short placeholder paragraph. Its marker remains with it when a page turns." />
+      <Paragraph id="specimen-continuation">{paragraph}</Paragraph>
+      <Paragraph id="specimen-ending">This last passage shows the closing rhythm of the page. The writing can finish here or continue into another scene, in the author's own form.</Paragraph>
+    </>}
+  </LiteraryText>;
+}
+export default Specimen;

package/starter/templates/literary-text/starter.tsx

@@ -0,0 +1,11 @@
+import { LiteraryText } from '../../templates/literary-text';
+import { Paragraph } from 'opendoc';
+// @ts-ignore The selected local theme module is inserted when this starter becomes a document.
+import { theme } from "__OPENDOC_THEME_MODULE__";
+const title = "__OPENDOC_TITLE__";
+const themeId = "__OPENDOC_THEME__";
+export const meta = { title, description: 'A literary text, ready for your writing.', kind: 'article' as const, theme: themeId };
+export const provenance = { template: 'templates/literary-text/index.tsx' };
+export default function Text() {
+  return <LiteraryText title={title} theme={theme} author="Author name"><Paragraph id="literary-opening">Your writing begins here. Replace this placeholder with your own opening and let the work take its shape.</Paragraph></LiteraryText>;
+}

package/starter/templates/literary-text/template.json

@@ -0,0 +1,11 @@
+{
+  "name": "Literary text",
+  "description": "A restrained opening and a comfortable reading column for stories, chapters, and longer creative prose, with optional epigraphs and quiet scene breaks.",
+  "format": "A4 · Literary prose",
+  "structure": [
+    "A modest centered title sits lower on the opening page, with an optional author line and epigraph.",
+    "A narrow column, relaxed leading, and small paragraph gaps support continuous reading.",
+    "Optional scene markers stay with their short opening paragraphs; longer passages flow naturally across pages.",
+    "Centered page numbers keep navigation quiet. The writing determines its own structure, and the design remains adaptable."
+  ]
+}

package/starter/templates/magazine-feature/AGENTS.md

@@ -0,0 +1,11 @@
+# Magazine feature
+
+Use this template as an adaptable starting point for the feature, with room for variation and creativity. Its character comes from the contrast between a broad opening and an offset reading column. The specimen's measurements are defaults: a long headline may need a smaller size, different spacing, or a rebalanced opening. Adjust the column, image proportions, and placement when the material calls for it. Aim for a coherent feature, not an exact reproduction of the specimen.
+
+Give the headline presence and usually keep the kicker and byline quiet. An opening image can span the full content width, with its caption immediately below. Flush body paragraphs and open spacing are a useful baseline. Display quotes work as occasional moments of emphasis in the reading flow. Omit or adapt these elements to suit the story; none imposes a mandatory content outline.
+
+Accept ordinary OpenDoc blocks in the author's order. The theme supplies visual hierarchy, rhythm, and component treatments; the layout supplies adaptable dimensions and spacing. Use the shared Neutral theme for the catalog specimen. References normally follow the body. Preserve stable block IDs, and keep document-specific variations local so other documents retain their existing layout.
+
+Use Forme's native Page, Fixed, View, and text flow through the existing OpenDoc primitives. Do not introduce the Prose indentation helper, column-balancing logic, text measurement, custom line splitting, negative margins, absolute-positioned body text, or renderer patches. The reading column is one flowing column; it does not promise newspaper-style two-column pagination. Leave variable text breakable. An image and its caption may use the existing Figure block; size the complete figure to fit a page.
+
+Review the adapted document and its page continuations. Shared layout changes also need sparse, typical, and long specimens, a second theme, and a working starter. Do not change unrelated templates or documents.

package/starter/templates/magazine-feature/README.md

@@ -0,0 +1,13 @@
+# Magazine feature
+
+A native Forme layout for illustrated features, profiles, and interviews. A4 pages have 48-point top and side margins and a 58-point bottom margin. The opening uses the full 499-point content width; body text is inset 96 points from the left, leaving a 403-point reading column. The headline is 52 points. Body text is 11/16.5 points with 10-point paragraph gaps and no indents. Fonts and colors come from the caller's theme.
+
+`MagazineFeature` takes `title`, `theme`, and ordinary OpenDoc blocks as `children`. Optional `kicker`, `standfirst`, `author`, and `hero` supply opening material. Omit them when they are not needed; there are no empty reserved panels or mandatory content sections. Pass verified `references` and use `Cite` in the body for the usual reference list.
+
+For `hero`, supply an existing `Figure` containing local `Media` or a native Forme image. Its available width is approximately 499 points; body visuals have approximately 403 points. Preserve the image's aspect ratio and leave enough height for its caption. `Figure` keeps the image and caption together, so the complete group must fit on a page. See [the media guidance](../../docs/MEDIA.md).
+
+Use `<FeatureQuote id="a-stable-quote-id">…</FeatureQuote>` for an optional display quote. It inherits the body font and color, uses 24/30-point text, and remains breakable in normal reading order. The writer supplies the quotation and attribution; this component does not invent either. Use ordinary paragraphs for nearby attribution when needed.
+
+The implementation uses existing OpenDoc blocks backed by Forme's native `Page`, `Fixed`, `View`, and text primitives. There is no custom typesetting, indentation shim, page splitting, or simulated multi-column flow. Long titles, decks, body text, and quotes remain breakable. Keep headings with a short opening using OpenDoc `Section` where appropriate, rather than wrapping large passages in an unbreakable group.
+
+`preview.tsx` contains clearly marked layout placeholders. `Specimen` accepts `length="sparse"`, `"typical"`, or `"long"`, plus an optional theme for review. The default catalog proof stays Neutral. `starter.tsx` creates an ordinary document linked to this folder. Keep authored IDs stable across revisions; preview sequence IDs belong only to its fixed specimen.