@ryanyahya/opendoc 0.4.0

package/starter/templates/magazine-feature/index.tsx

@@ -0,0 +1,41 @@
+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 interface MagazineFeatureProps {
+  title: string;
+  theme: DocTheme;
+  kicker?: string;
+  standfirst?: ReactNode;
+  author?: string;
+  hero?: ReactNode;
+  children: ReactNode;
+  references?: Parameters<typeof Document>[0]['references'];
+}
+
+/** Native flowing blocks: a broad opening followed by an offset reading column. */
+export function MagazineFeature({ title, theme, kicker, standfirst, author, hero, children, references }: MagazineFeatureProps) {
+  const layoutTheme: DocTheme = theme.design ? theme : { ...theme, fontSize: 11, lineHeight: 1.5, paragraphGap: 10 };
+  return <Document title={title} author={author} theme={layoutTheme} references={references}>
+    <Page {...themePage(theme, { top: 48, bottom: 58, left: 48, right: 48 })} 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: 'right', ...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}>
+        {kicker && <Paragraph id="feature-kicker" role="label" baseStyle={{ fontSize: 9, letterSpacing: 1.4, color: theme.accent, marginBottom: 14 }} style={theme.design?.title?.eyebrow}>{theme.design?.title?.uppercaseEyebrow ? kicker.toUpperCase() : <TextSlot slot="kicker" from="kicker">{kicker}</TextSlot>}</Paragraph>}
+        <Heading id="feature-title" level={1} baseStyle={{ fontSize: 52, lineHeight: 1.06, marginBottom: 18 }} style={theme.design?.title?.heading}><TextSlot slot="title" from="title">{title}</TextSlot></Heading>
+        {standfirst && <Paragraph id="feature-standfirst" role="lead" baseStyle={{ fontSize: 17, lineHeight: 1.35, marginBottom: 18 }} style={theme.design?.title?.subtitle}><TextSlot slot="standfirst" from="standfirst">{standfirst}</TextSlot></Paragraph>}
+        {author && <Paragraph id="feature-byline" role="small" baseStyle={{ fontSize: 9, color: theme.muted, marginBottom: 20 }} style={theme.design?.title?.byline}><TextSlot slot="author" from="author">{author}</TextSlot></Paragraph>}
+      </F.View>
+      {hero}
+      <F.View style={{ marginLeft: 96, marginTop: 18 }}>
+        {children}
+        <References headingBaseStyle={{ fontSize: 11, marginTop: 24, marginBottom: 10 }} />
+      </F.View>
+    </Page>
+  </Document>;
+}
+
+/** A flowing display quote. It stays in normal reading order and may span pages. */
+export function FeatureQuote({ id, children }: { id: string; children: ReactNode }) {
+  return <Paragraph id={id} role="lead" baseStyle={{ fontSize: 24, lineHeight: 1.25, marginTop: 16, marginBottom: 24, marginRight: 36 }}><TextSlot slot="children" from="children">{children}</TextSlot></Paragraph>;
+}

package/starter/templates/magazine-feature/preview.tsx

@@ -0,0 +1,34 @@
+import * as F from '@formepdf/react';
+import { Figure, Heading, Paragraph, Section } from 'opendoc';
+import { neutral } from '../../themes';
+import { type DocTheme } from 'opendoc/themes';
+import { FeatureQuote, MagazineFeature } from './index';
+
+export const meta = { title: 'Magazine feature', description: 'A neutral layout specimen. All text and visual areas are placeholders.', kind: 'article' as const, theme: 'neutral' };
+const paragraph = 'This is placeholder text for the reading column. The feature opens across a broader measure, then settles into a narrower passage offset from the left margin. These words show the rhythm of a printed page: the space between paragraphs, the length of a line, and the return to ordinary prose after a visual pause. They report no findings and describe no real person or event.';
+
+export function Specimen({ length = 'typical', theme = neutral }: { length?: 'sparse' | 'typical' | 'long'; theme?: DocTheme } = {}) {
+  const sparse = length === 'sparse';
+  const count = length === 'long' ? 16 : 3;
+  return <MagazineFeature title={meta.title} theme={theme}
+    kicker={sparse ? undefined : 'FEATURE / LAYOUT SPECIMEN'}
+    author={sparse ? undefined : 'Author name · Illustrative placeholders'}
+    standfirst={sparse ? undefined : 'An expansive opening gives the story a visual presence before the page settles into a quieter reading rhythm.'}
+    hero={sparse ? undefined : <Figure id="specimen-hero" caption="Opening image position. This frame is a layout placeholder, not evidence.">
+      <F.View style={{ height: 170, backgroundColor: theme.paper, borderWidth: 0.6, borderColor: theme.line, justifyContent: 'center', alignItems: 'center' }}>
+        <F.Text style={{ fontSize: 10, color: theme.muted }}>Opening image · Full content width</F.Text>
+      </F.View>
+    </Figure>}>
+    <Paragraph id="specimen-opening">{paragraph}</Paragraph>
+    {!sparse && <>
+      <FeatureQuote id="specimen-quote">A display quote creates a pause within the reading column.</FeatureQuote>
+      {Array.from({ length: count }, (_, index) => <Paragraph key={index} id={`specimen-body-${index + 1}`}>{paragraph}</Paragraph>)}
+      <Section id="specimen-section" title="A change of pace" lead="A short section opening stays with its heading. This text demonstrates placement, not a required outline.">
+        <Paragraph id="specimen-closing">{paragraph}</Paragraph>
+      </Section>
+      <Heading id="specimen-reference-heading" style={{ fontSize: 11, marginTop: 24 }}>References</Heading>
+      <Paragraph id="specimen-reference" style={{ fontSize: 9, color: theme.muted }}>Reference placement specimen. Real references appear here only when cited; no source is being claimed.</Paragraph>
+    </>}
+  </MagazineFeature>;
+}
+export default Specimen;

package/starter/templates/magazine-feature/starter.tsx

@@ -0,0 +1,15 @@
+import { MagazineFeature } from '../../templates/magazine-feature';
+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 magazine feature, ready for your material.', kind: 'article' as const, theme: themeId };
+export const provenance = { template: 'templates/magazine-feature/index.tsx' };
+
+export default function Feature() {
+  return <MagazineFeature title={title} theme={theme} kicker="FEATURE" author="Author name" standfirst="Standfirst — replace this placeholder with an introduction to your feature.">
+    <Paragraph id="feature-opening">Your feature begins here. Replace this placeholder with your own material; add photographs, quotations, and further passages where the story needs them.</Paragraph>
+  </MagazineFeature>;
+}

package/starter/templates/magazine-feature/template.json

@@ -0,0 +1,11 @@
+{
+  "name": "Magazine feature",
+  "description": "A broad visual opening followed by an offset reading column, with room for photographs and display quotes. For profiles, interviews, and illustrated features.",
+  "format": "A4 · Offset single column",
+  "structure": [
+    "A large headline, optional kicker, standfirst, and byline open the feature without a separate cover.",
+    "The opening visual spans the page's full content width; its caption stays with it.",
+    "Body text flows in a narrower column offset to the right, with flush paragraphs and open spacing.",
+    "Optional display quotes interrupt the reading rhythm in normal flow. References follow the body; page numbers sit quietly below."
+  ]
+}

package/starter/templates/monthly-report/AGENTS.md

@@ -0,0 +1,11 @@
+# Monthly report
+
+Use this as an adaptable foundation for a recurring operational report. A clear opening, concise summary, scorecard, risks, and actions are useful defaults. Let the actual material determine which sections appear and how much space they need. A short report can omit empty sections; a longer report should flow without a forced page count. Adjust emphasis, title size, and exhibit proportions to serve the reader.
+
+Each document owns its validated `data.json`; the shared template owns layout. Read [README.md](README.md) and `schema.ts` before changing the contract. Preserve explicit record IDs when editing or reordering data, and keep the existing `TextSlot` bindings for string fields. Numeric values, dates, units, targets, statuses, and source notes come from supplied records. Do not infer overdue work, improvement, or completion from dates or values alone.
+
+Keep illustrative examples visibly synthetic until replaced with real supplied material. Omit absent optional arrays instead of filling them with invented observations. Keep references and evidence limits accurate.
+
+Use the caller's adapted theme from the generated `theme.tsx`, retaining `assets.json` and data provenance. For one report's content correction, edit its local data; keep local design changes from altering every instance. Preserve block identities and comment history. Use native OpenDoc flow, repeated table headers, and bounded heading/lead groups.
+
+Review every adapted PDF. Shared changes need sparse, typical, and long data, a second theme, invalid-input checks, representative text extraction, and a created instance with independent data. Catalog specimens use Neutral and stay outside the document library.

package/starter/templates/monthly-report/README.md

@@ -0,0 +1,24 @@
+# Monthly operational report
+
+A pure, reusable English report with flowing sections, a scorecard, risks, and an action register. The supplied data is clearly marked synthetic in every exported PDF.
+
+Create a working instance with `pnpm run create -- monthly-report --project <project-id> --template monthly-report --title "Monthly report"`. It is also available from Templates in the app. Its source binds this template to a neighboring `data.json` through the generated `theme.tsx` adapter; retain that adapter and the exact selections in `assets.json`. Update the data for a new edition; the layout stays in one place. The project default theme applies at creation, with `--theme <id>` available to override it.
+
+## Data contract
+
+Use `examples/typical.json` as the complete starting point. `examples/sparse.json` demonstrates empty sections and missing targets. `examples/long.json` exercises long prose and a table that continues across pages.
+
+Required fields are `schemaVersion: 1`, `title`, `organization`, `period.start`, `period.end`, `issuedOn`, `synthetic`, `sourceNote`, and `summary`. Dates use `YYYY-MM-DD` and must be real calendar dates. `preparedBy` is optional. Set `synthetic: true` for illustrative data; set it to `false` only when the report contains real supplied material. Keep `sourceNote` accurate about the basis of the report.
+
+The five optional arrays are `metrics`, `highlights`, `risks`, `actions`, and `notes`. Omit a section, set it to `null`, or provide an empty array to leave it out of the PDF. Every record needs a stable `id`, unique within its array. Keep IDs when changing or moving the same record; do not generate IDs from row positions.
+
+- Metrics require a `label` and finite numeric `value`. `target`, `unit`, `note`, and `precision` are optional. A missing target displays a dash; zero remains zero. Precision is an integer from 0 to 3 and defaults to 0. Units appear after values, with `%` directly attached. Use a clear unit such as `USD` for money; no currency or direction is inferred.
+- Highlights and notes require `title` and `body`.
+- Risks require `title`, `level` (`low`, `medium`, or `high`), `owner`, and `mitigation`.
+- Actions require `title`, `owner`, `due`, and `status` (`planned`, `in-progress`, or `complete`). Dates and status are reported as supplied; the template does not invent overdue or completion claims.
+
+`parseMonthlyReport(unknown)` validates the entire input and reports concise field paths in one error. Unknown fields are rejected so a misspelling cannot silently disappear. It returns a fresh normalized `MonthlyReportData` object without mutating the input. `monthlyReportTemplate(theme)` returns `parse`, `meta`, and `render` for the shared template binding and batch export commands, using the instance's adapted theme.
+
+Narrative and risk comment targets use record IDs, so reordering preserves their identities. Tables keep their block identity through pagination; string cells use stable record bindings for quick text corrections. Calculated and numeric values remain protected. Long narratives split into flowing blocks and are edited by the agent in `data.json`; the reader explains this when selected. Prose and tables flow naturally; the template has no manually positioned pages or prescribed page count.
+
+The instance `data.json` is normalized report input. Leave supplied spreadsheets or prior reports in the project’s existing organization; chart-specific derived rows belong in the document’s `media/<id>/`. See [document media](../../docs/MEDIA.md).

package/starter/templates/monthly-report/data.json

@@ -0,0 +1,131 @@
+{
+  "schemaVersion": 1,
+  "title": "__OPENDOC_TITLE__",
+  "organization": "Northline Studio",
+  "preparedBy": "Operations team",
+  "period": {
+    "start": "2026-08-01",
+    "end": "2026-08-31"
+  },
+  "issuedOn": "2026-09-04",
+  "synthetic": true,
+  "sourceNote": "Synthetic demonstration data created for OpenDoc. The measures, narrative, names, risks, and commitments are illustrative and do not describe an actual organization. No external research or operational records were used.",
+  "summary": "August was a month of consolidation. The team completed more work with fewer late handoffs, while the oldest unresolved requests continued to absorb attention. The clearest improvement came from a simple change: every new assignment began with a named owner and a written definition of completion. That reduced the time spent deciding who should move a piece of work forward. The remaining constraint is capacity in final review. Adding more work at the front of the process would increase waiting time unless that constraint is addressed. September should therefore focus on closing the oldest requests, protecting review time, and testing a second reviewer on one service line before making a wider commitment.",
+  "metrics": [
+    {
+      "id": "completed-requests",
+      "label": "Requests completed",
+      "value": 86,
+      "target": 80,
+      "precision": 0,
+      "note": "Six above plan; the work mix was broadly unchanged."
+    },
+    {
+      "id": "on-time-delivery",
+      "label": "Delivered on time",
+      "value": 91.9,
+      "target": 95,
+      "unit": "%",
+      "precision": 1,
+      "note": "Final review caused five of the seven late handoffs."
+    },
+    {
+      "id": "median-cycle",
+      "label": "Median cycle time",
+      "value": 4.2,
+      "target": 4,
+      "unit": "days",
+      "precision": 1,
+      "note": "Calendar days from accepted brief to delivery."
+    },
+    {
+      "id": "open-backlog",
+      "label": "Open at month end",
+      "value": 23,
+      "precision": 0,
+      "note": "Eight requests are more than ten days old."
+    }
+  ],
+  "highlights": [
+    {
+      "id": "clearer-starts",
+      "title": "A clearer start reduced avoidable returns",
+      "body": "The intake checklist now asks for one decision owner, the expected output, and the date on which it becomes useful. Reviewers returned fewer briefs for clarification, and the weekly planning meeting spent less time reconstructing context. The change is deliberately small: the checklist remains on the assignment itself, where both the requester and the team can see it. It does not create a separate approval queue."
+    },
+    {
+      "id": "review-capacity",
+      "title": "The bottleneck moved into final review",
+      "body": "Most assignments passed through preparation without difficulty, but review demand was concentrated in the last week. Work arriving together competed for the same specialist. The result was a set of late handoffs that had little to do with the quality of the original brief. A protected review session twice a week is the next experiment. Its purpose is to make capacity visible early enough to adjust commitments."
+    },
+    {
+      "id": "oldest-work",
+      "title": "The oldest requests need individual decisions",
+      "body": "The eight requests older than ten days are not one problem. Three need a decision from the requester, two are waiting for missing material, and three require specialist review. The team will give each request an explicit next step and a named decision date. Closing the register administratively would improve the count while leaving the underlying work unresolved, so completion will continue to require a delivered or explicitly cancelled outcome."
+    }
+  ],
+  "risks": [
+    {
+      "id": "single-reviewer",
+      "title": "Review depends on one specialist",
+      "level": "high",
+      "owner": "Maya Chen",
+      "mitigation": "A planned absence could delay several active assignments at once. Pair a second reviewer with the specialist on one service line, record the review criteria, and compare decisions before expanding the arrangement. The immediate aim is dependable cover, with quality checked on a small sample."
+    },
+    {
+      "id": "uncertain-demand",
+      "title": "September demand is uneven",
+      "level": "medium",
+      "owner": "Jon Bell",
+      "mitigation": "Two possible assignments have not yet been confirmed. Keep them visible in the capacity review, but do not count them as accepted work or reserve a full delivery slot. Confirm scope and timing with the requesters before changing existing commitments."
+    }
+  ],
+  "actions": [
+    {
+      "id": "backlog-decisions",
+      "title": "Agree a next step and decision date for every request older than ten days.",
+      "owner": "Jon Bell",
+      "due": "2026-09-08",
+      "status": "in-progress"
+    },
+    {
+      "id": "protect-review",
+      "title": "Reserve two review sessions each week and publish available capacity.",
+      "owner": "Maya Chen",
+      "due": "2026-09-09",
+      "status": "planned"
+    },
+    {
+      "id": "pair-review",
+      "title": "Run a paired review on five assignments from one service line.",
+      "owner": "Maya Chen",
+      "due": "2026-09-18",
+      "status": "planned"
+    },
+    {
+      "id": "intake-audit",
+      "title": "Check a sample of ten new briefs for a named owner and a clear completion test.",
+      "owner": "Ari Patel",
+      "due": "2026-09-21",
+      "status": "planned"
+    },
+    {
+      "id": "next-review",
+      "title": "Review the experiments, late handoffs, and age of unresolved work together.",
+      "owner": "Operations team",
+      "due": "2026-09-30",
+      "status": "planned"
+    }
+  ],
+  "notes": [
+    {
+      "id": "measurement-window",
+      "title": "The measurement window",
+      "body": "Completed requests and on-time delivery include work delivered during August, even when it began earlier. Cycle time uses the same completed group. The open register is a separate snapshot taken at the end of the month. These measures should not be added together as if they were counts of the same population."
+    },
+    {
+      "id": "interpretation",
+      "title": "How to read the targets",
+      "body": "The targets are planning thresholds supplied with this example. A result above a target is not automatically better: lower cycle time is desirable, while a higher completion count may reflect a change in work mix. Interpret each value alongside its definition and the narrative before drawing a conclusion."
+    }
+  ]
+}