create-dfactory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chiploopman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# create-dfactory
+
+## Purpose
+
+Project bootstrap generator for adding dFactory into existing React/Vue projects.
+
+It detects framework dependencies, updates package scripts/dependencies, and copies starter templates.
+
+## Usage
+
+```bash
+npm create dfactory@latest
+# or
+pnpm create dfactory@latest
+# or
+yarn create dfactory
+```
+
+## Development
+
+```bash
+pnpm --filter create-dfactory typecheck
+pnpm --filter create-dfactory test
+pnpm --filter create-dfactory build
+```
+
+When changing generation behavior, add unit coverage under `tests/unit/create-dfactory*.test.ts`.
+
+## Troubleshooting
+
+- Wrong framework selected: verify target project dependencies before running initializer.
+- Missing scripts/deps: rerun generator and inspect resulting `package.json` merge behavior.
+
+## Related Documentation
+
+- [Installation](/docs/installation)
+- [Contributing](/docs/contributing)

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "create-dfactory",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chiploopman/dfactory.git"
+  },
+  "homepage": "https://github.com/chiploopman/dfactory#readme",
+  "bugs": {
+    "url": "https://github.com/chiploopman/dfactory/issues"
+  },
+  "keywords": [
+    "dfactory",
+    "pdf",
+    "templates",
+    "scaffold"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "create-dfactory": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "tsx": "^4.20.5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}

package/templates/base/dfactory.config.ts

@@ -0,0 +1,34 @@
+import type { DFactoryConfig } from "@dfactory/core";
+
+const config: DFactoryConfig = {
+  templates: {
+    globs: ["src/templates/*/template.{ts,tsx,js,jsx,mts,mtsx}"],
+    compatibilityGlobEnabled: false
+  },
+  plugins: ["{{frameworkPluginPackage}}"],
+  moduleLoader: "{{moduleLoaderPackage}}",
+  auth: {
+    mode: "apiKey",
+    apiKeys: []
+  },
+  ui: {
+    exposeInProd: true,
+    sourceInProd: false,
+    playgroundInProd: false
+  },
+  renderer: {
+    engine: "playwright",
+    poolSize: 4,
+    timeoutMs: 30000,
+    pdfPlugins: ["@dfactory/pdf-feature-standard"],
+    defaults: {
+      format: "A4",
+      printBackground: true,
+      preferCSSPageSize: true,
+      tagged: true,
+      outline: true
+    }
+  }
+};
+
+export default config;

package/templates/react/src/templates/invoice/template.tsx

@@ -0,0 +1,154 @@
+import { z } from "zod";
+
+import {
+  AvoidBreakInside,
+  Document,
+  Heading,
+  KeepWithNext,
+  NumericCell,
+  Page,
+  PageBreakBefore,
+  Paragraph,
+  Section,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeaderCell,
+  TableRow
+} from "@dfactory/pdf-primitives-react";
+import { defineTemplate } from "@dfactory/template-kit";
+
+const template = defineTemplate({
+  meta: {
+    id: "invoice",
+    title: "Invoice",
+    description: "Default starter invoice template",
+    framework: "react",
+    version: "1.0.0",
+    tags: ["billing", "starter"]
+  },
+  schema: z.object({
+    invoiceNumber: z.string(),
+    customerName: z.string(),
+    issuedAt: z.string(),
+    items: z.array(
+      z.object({
+        name: z.string(),
+        qty: z.number(),
+        price: z.number()
+      })
+    )
+  }),
+  pdf: {
+    page: {
+      size: "A4",
+      marginsMm: { top: 12, right: 12, bottom: 14, left: 12 }
+    },
+    toc: {
+      enabled: true,
+      maxDepth: 2,
+      title: "Invoice Overview"
+    },
+    pagination: {
+      mode: "css"
+    },
+    headerFooter: {
+      enabled: true,
+      footerTemplate:
+        "<div style=\"width:100%;font-size:9px;padding:0 12px;color:#64748b;display:flex;justify-content:space-between;\"><span>{{title}}</span><span>{{pageXofY}}</span></div>"
+    },
+    metadata: {
+      title: "Invoice Document",
+      keywords: ["invoice", "billing", "starter"]
+    },
+    theme: {
+      font: {
+        family: "Inter, 'Segoe UI', sans-serif"
+      },
+      color: {
+        accent: "#1d4ed8"
+      }
+    }
+  },
+  examples: [
+    {
+      name: "default",
+      payload: {
+        invoiceNumber: "INV-1001",
+        customerName: "Northwind Trading",
+        issuedAt: "2026-03-27",
+        items: [
+          { name: "Consulting", qty: 2, price: 420 },
+          { name: "Support", qty: 1, price: 180 }
+        ]
+      }
+    }
+  ],
+  render(payload) {
+    const total = payload.items.reduce((sum, item) => sum + item.qty * item.price, 0);
+
+    return (
+      <Document>
+        <Page>
+          <Section style={{ padding: "24px" }}>
+            <KeepWithNext>
+              <Heading as="h1" style={{ marginBottom: "8px", color: "var(--df-pdf-color-accent)" }}>
+                Invoice {payload.invoiceNumber}
+              </Heading>
+              <Paragraph style={{ color: "var(--df-pdf-color-muted)", marginTop: 0 }}>
+                Customer: {payload.customerName}
+              </Paragraph>
+              <Paragraph style={{ color: "var(--df-pdf-color-muted)", marginTop: "4px" }}>
+                Issued: {payload.issuedAt}
+              </Paragraph>
+            </KeepWithNext>
+
+            <AvoidBreakInside>
+              <Heading as="h2" style={{ marginTop: "20px", marginBottom: "8px", fontSize: "16px" }}>
+                Line Items
+              </Heading>
+              <Table style={{ marginTop: "10px" }}>
+                <TableHead>
+                  <TableRow>
+                    <TableHeaderCell style={{ textAlign: "left" }}>Item</TableHeaderCell>
+                    <TableHeaderCell style={{ textAlign: "right" }}>Qty</TableHeaderCell>
+                    <TableHeaderCell style={{ textAlign: "right" }}>Price</TableHeaderCell>
+                  </TableRow>
+                </TableHead>
+                <TableBody>
+                  {payload.items.map((item) => (
+                    <TableRow key={item.name}>
+                      <TableCell>{item.name}</TableCell>
+                      <NumericCell>{item.qty}</NumericCell>
+                      <NumericCell>${(item.price * item.qty).toFixed(2)}</NumericCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+              <Paragraph style={{ textAlign: "right", marginTop: "16px", fontWeight: 700 }}>
+                Total: ${total.toFixed(2)}
+              </Paragraph>
+            </AvoidBreakInside>
+
+            <PageBreakBefore>
+              <Heading as="h2" style={{ marginTop: "24px", fontSize: "16px" }}>
+                Payment Terms
+              </Heading>
+              <Paragraph style={{ color: "var(--df-pdf-color-text)", lineHeight: 1.6 }}>
+                Payment due within 14 calendar days from invoice date. Late payments may incur
+                additional charges.
+              </Paragraph>
+            </PageBreakBefore>
+          </Section>
+        </Page>
+      </Document>
+    );
+  }
+});
+
+export const meta = template.meta;
+export const schema = template.schema;
+export const pdf = template.pdf;
+export const examples = template.examples;
+export const render = template.render;

package/templates/react/src/templates/invoice-reference/components/InvoiceReferenceDocument.tsx

@@ -0,0 +1,309 @@
+import {
+  AvoidBreakInside,
+  Divider,
+  Document,
+  KeepWithNext,
+  Page,
+  PageBreakBefore
+} from "@dfactory/pdf-primitives-react";
+
+import type { InvoiceReferencePayload } from "./types";
+
+function formatMoney(value: number, currency: string): string {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency
+  }).format(value);
+}
+
+function calculateLineTotal(options: {
+  qty: number;
+  unitPrice: number;
+  discount?: number;
+  taxRate?: number;
+}): number {
+  const gross = options.qty * options.unitPrice;
+  const discount = options.discount ?? 0;
+  const discounted = gross - gross * (discount / 100);
+  const taxRate = options.taxRate ?? 0;
+  return discounted + discounted * (taxRate / 100);
+}
+
+export function InvoiceReferenceDocument(props: {
+  payload: InvoiceReferencePayload;
+}) {
+  const accent = props.payload.brand?.accentColor ?? "#4f46e5";
+  const subtotal = props.payload.items.reduce(
+    (sum, item) => sum + item.qty * item.unitPrice,
+    0
+  );
+  const total = props.payload.items.reduce(
+    (sum, item) =>
+      sum +
+      calculateLineTotal({
+        qty: item.qty,
+        unitPrice: item.unitPrice,
+        discount: item.discount,
+        taxRate: item.taxRate
+      }),
+    0
+  );
+
+  return (
+    <Document>
+      <Page>
+        <KeepWithNext
+          as="header"
+          style={{
+            borderBottom: "2px solid #e2e8f0",
+            paddingBottom: "16px",
+            marginBottom: "18px"
+          }}
+        >
+          <h1 style={{ margin: 0, color: accent }}>Invoice {props.payload.invoiceNumber}</h1>
+          <p style={{ margin: "6px 0 0", color: "#475569" }}>
+            Issued {props.payload.issuedAt} • Due {props.payload.dueAt}
+          </p>
+          {props.payload.purchaseOrder ? (
+            <p style={{ margin: "4px 0 0", color: "#64748b" }}>
+              Purchase Order: {props.payload.purchaseOrder}
+            </p>
+          ) : null}
+        </KeepWithNext>
+
+        <section
+          style={{
+            display: "grid",
+            gridTemplateColumns: "1fr 1fr",
+            gap: "18px",
+            marginBottom: "16px"
+          }}
+        >
+          <AvoidBreakInside as="article">
+            <h2 style={{ fontSize: "16px", marginBottom: "8px" }}>Bill From</h2>
+            <p style={{ margin: 0, fontWeight: 600 }}>{props.payload.company.name}</p>
+            <p style={{ margin: "4px 0 0", color: "#475569", whiteSpace: "pre-line" }}>
+              {props.payload.company.address}
+            </p>
+            <p style={{ margin: "8px 0 0", color: "#334155" }}>
+              {props.payload.company.email} • {props.payload.company.phone}
+            </p>
+            <p style={{ margin: "4px 0 0", color: "#64748b" }}>
+              {props.payload.company.website} • Tax ID {props.payload.company.taxId}
+            </p>
+          </AvoidBreakInside>
+
+          <AvoidBreakInside as="article">
+            <h2 style={{ fontSize: "16px", marginBottom: "8px" }}>Bill To</h2>
+            <p style={{ margin: 0, fontWeight: 600 }}>{props.payload.customer.name}</p>
+            <p style={{ margin: "4px 0 0", color: "#475569" }}>
+              Contact: {props.payload.customer.contact}
+            </p>
+            <p style={{ margin: "4px 0 0", color: "#334155" }}>{props.payload.customer.email}</p>
+            <p style={{ margin: "4px 0 0", color: "#64748b", whiteSpace: "pre-line" }}>
+              {props.payload.customer.address}
+            </p>
+          </AvoidBreakInside>
+        </section>
+
+        <AvoidBreakInside as="section">
+          <h2 style={{ fontSize: "16px", margin: "20px 0 8px" }}>Services & Deliverables</h2>
+          <table
+            style={{
+              width: "100%",
+              borderCollapse: "collapse",
+              border: "1px solid #e2e8f0",
+              borderRadius: "8px",
+              overflow: "hidden"
+            }}
+          >
+            <thead style={{ backgroundColor: "#eef2ff" }}>
+              <tr>
+                <th style={{ textAlign: "left", padding: "10px 12px" }}>Description</th>
+                <th style={{ textAlign: "right", padding: "10px 12px" }}>Qty</th>
+                <th style={{ textAlign: "right", padding: "10px 12px" }}>Unit</th>
+                <th style={{ textAlign: "right", padding: "10px 12px" }}>Discount</th>
+                <th style={{ textAlign: "right", padding: "10px 12px" }}>Tax</th>
+                <th style={{ textAlign: "right", padding: "10px 12px" }}>Line Total</th>
+              </tr>
+            </thead>
+            <tbody>
+              {props.payload.items.map((item) => (
+                <tr key={item.id}>
+                  <td style={{ padding: "10px 12px", borderTop: "1px solid #e2e8f0" }}>
+                    <p style={{ margin: 0, fontWeight: 600 }}>{item.name}</p>
+                    {item.description ? (
+                      <p style={{ margin: "4px 0 0", color: "#64748b" }}>{item.description}</p>
+                    ) : null}
+                  </td>
+                  <td
+                    style={{
+                      textAlign: "right",
+                      padding: "10px 12px",
+                      borderTop: "1px solid #e2e8f0"
+                    }}
+                  >
+                    {item.qty}
+                  </td>
+                  <td
+                    style={{
+                      textAlign: "right",
+                      padding: "10px 12px",
+                      borderTop: "1px solid #e2e8f0"
+                    }}
+                  >
+                    {formatMoney(item.unitPrice, props.payload.currency)}
+                  </td>
+                  <td
+                    style={{
+                      textAlign: "right",
+                      padding: "10px 12px",
+                      borderTop: "1px solid #e2e8f0"
+                    }}
+                  >
+                    {(item.discount ?? 0).toFixed(1)}%
+                  </td>
+                  <td
+                    style={{
+                      textAlign: "right",
+                      padding: "10px 12px",
+                      borderTop: "1px solid #e2e8f0"
+                    }}
+                  >
+                    {(item.taxRate ?? 0).toFixed(1)}%
+                  </td>
+                  <td
+                    style={{
+                      textAlign: "right",
+                      padding: "10px 12px",
+                      borderTop: "1px solid #e2e8f0",
+                      fontWeight: 600
+                    }}
+                  >
+                    {formatMoney(
+                      calculateLineTotal({
+                        qty: item.qty,
+                        unitPrice: item.unitPrice,
+                        discount: item.discount,
+                        taxRate: item.taxRate
+                      }),
+                      props.payload.currency
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </AvoidBreakInside>
+
+        <section
+          style={{
+            marginTop: "16px",
+            display: "grid",
+            gridTemplateColumns: "1fr 280px",
+            gap: "24px"
+          }}
+        >
+          <article>
+            <h2 style={{ fontSize: "16px", marginBottom: "8px" }}>Summary Notes</h2>
+            <p style={{ color: "#475569", marginTop: 0 }}>
+              The sections below intentionally include long-form text to provide a strong
+              multi-page reference for TOC, pagination, and marker helpers.
+            </p>
+            {props.payload.sections.map((section, index) => {
+              const sectionStyle = {
+                marginTop: "14px",
+                padding: "12px",
+                border: "1px solid #e2e8f0",
+                borderRadius: "8px",
+                background: "#f8fafc"
+              } as const;
+
+              if (index === 2) {
+                return (
+                  <PageBreakBefore key={`${section.title}-${index}`} as="section" style={sectionStyle}>
+                    <h3 style={{ marginTop: 0, marginBottom: "8px", color: "#1e293b" }}>
+                      {section.title}
+                    </h3>
+                    <p style={{ margin: 0, color: "#334155" }}>{section.description}</p>
+                    {section.notes ? (
+                      <p style={{ margin: "8px 0 0", color: "#64748b" }}>{section.notes}</p>
+                    ) : null}
+                  </PageBreakBefore>
+                );
+              }
+
+              return (
+                <section key={`${section.title}-${index}`} style={sectionStyle}>
+                  <h3 style={{ marginTop: 0, marginBottom: "8px", color: "#1e293b" }}>
+                    {section.title}
+                  </h3>
+                  <p style={{ margin: 0, color: "#334155" }}>{section.description}</p>
+                  {section.notes ? (
+                    <p style={{ margin: "8px 0 0", color: "#64748b" }}>{section.notes}</p>
+                  ) : null}
+                </section>
+              );
+            })}
+          </article>
+
+          <KeepWithNext
+            as="aside"
+            style={{
+              border: "1px solid #dbeafe",
+              background: "#eff6ff",
+              borderRadius: "10px",
+              padding: "14px"
+            }}
+          >
+            <h2 style={{ margin: 0, fontSize: "15px" }}>Totals</h2>
+            <p style={{ margin: "10px 0 0", color: "#475569" }}>
+              Subtotal: <strong>{formatMoney(subtotal, props.payload.currency)}</strong>
+            </p>
+            <p style={{ margin: "6px 0 0", color: "#475569" }}>
+              Grand Total: <strong>{formatMoney(total, props.payload.currency)}</strong>
+            </p>
+            <Divider
+              style={{
+                borderTopColor: "rgba(71, 85, 105, 0.2)",
+                marginTop: "10px",
+                marginBottom: "8px"
+              }}
+            />
+            <p style={{ margin: "10px 0 0", color: "#1e293b", fontWeight: 600 }}>
+              Payment via {props.payload.payment.bankName}
+            </p>
+            <p style={{ margin: "4px 0 0", color: "#475569" }}>
+              IBAN: {props.payload.payment.iban}
+            </p>
+            <p style={{ margin: "4px 0 0", color: "#475569" }}>
+              SWIFT: {props.payload.payment.swift}
+            </p>
+            {props.payload.payment.instructions ? (
+              <p style={{ margin: "8px 0 0", color: "#64748b" }}>
+                {props.payload.payment.instructions}
+              </p>
+            ) : null}
+          </KeepWithNext>
+        </section>
+
+        {props.payload.notes ? (
+          <PageBreakBefore
+            as="section"
+            style={{
+              marginTop: "20px",
+              padding: "16px",
+              border: "1px dashed #cbd5e1",
+              borderRadius: "10px"
+            }}
+          >
+            <h2 style={{ marginTop: 0, fontSize: "16px" }}>Additional Terms</h2>
+            <p style={{ marginBottom: 0, color: "#334155", whiteSpace: "pre-line" }}>
+              {props.payload.notes}
+            </p>
+          </PageBreakBefore>
+        ) : null}
+      </Page>
+    </Document>
+  );
+}

package/templates/react/src/templates/invoice-reference/components/InvoiceReferenceFooter.tsx

@@ -0,0 +1,26 @@
+export function InvoiceReferenceFooter(props: {
+  templateId: string;
+  pageNumberToken: string;
+  totalPagesToken: string;
+  supportEmail?: string;
+}) {
+  return (
+    <div
+      style={{
+        width: "100%",
+        padding: "0 14px",
+        fontSize: "9px",
+        color: "#475569",
+        display: "flex",
+        justifyContent: "space-between",
+        alignItems: "center"
+      }}
+    >
+      <span>{props.supportEmail ?? "billing@dfactory.dev"}</span>
+      <span>{props.templateId}</span>
+      <span>
+        {props.pageNumberToken} / {props.totalPagesToken}
+      </span>
+    </div>
+  );
+}

package/templates/react/src/templates/invoice-reference/components/InvoiceReferenceHeader.tsx

@@ -0,0 +1,23 @@
+export function InvoiceReferenceHeader(props: {
+  title: string;
+  invoiceNumber: string;
+  generatedAtToken: string;
+}) {
+  return (
+    <div
+      style={{
+        width: "100%",
+        padding: "0 14px",
+        fontSize: "9px",
+        color: "#475569",
+        display: "flex",
+        justifyContent: "space-between",
+        alignItems: "center"
+      }}
+    >
+      <span>{props.title}</span>
+      <span>{props.invoiceNumber}</span>
+      <span>{props.generatedAtToken}</span>
+    </div>
+  );
+}

package/templates/react/src/templates/invoice-reference/components/InvoiceReferencePagination.tsx

@@ -0,0 +1,24 @@
+import { AvoidBreakInside } from "@dfactory/pdf-primitives-react";
+
+export function InvoiceReferencePagination(props: {
+  pageNumberToken: string;
+  totalPagesToken: string;
+}) {
+  return (
+    <AvoidBreakInside
+      style={{
+        width: "100%",
+        padding: "4px 16px 8px",
+        fontSize: "9px",
+        color: "#64748b",
+        display: "flex",
+        justifyContent: "space-between"
+      }}
+    >
+      <span>DFactory Reference Pagination Layer</span>
+      <span>
+        Page {props.pageNumberToken} of {props.totalPagesToken}
+      </span>
+    </AvoidBreakInside>
+  );
+}