@design.estate/dees-document 1.1.0 → 1.3.1

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@design.estate/dees-document",
-  "version": "1.1.0",
+  "version": "1.3.1",
   "private": false,
-  "description": "A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements.",
+  "description": "A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.",
   "main": "dist_ts_web/index.js",
   "typings": "dist_ts_web/index.d.ts",
   "exports": {
@@ -22,6 +22,7 @@
     "@push.rocks/smartpdf": "^3.1.8",
     "@push.rocks/smarttime": "^4.0.8",
     "@tsclass/tsclass": "^4.1.2",
+    "@types/node": "^22.10.1",
     "@types/qrcode": "^1.5.5",
     "qrcode": "^1.5.4"
   },
@@ -59,26 +60,27 @@
   "homepage": "https://gitlab.com/designestate/private/dedocument-catalog#readme",
   "keywords": [
     "document generation",
-    "invoices",
+    "invoice automation",
+    "business documentation",
+    "dynamic rendering",
     "PDF creation",
-    "TypeScript",
     "web components",
+    "Node.js",
+    "TypeScript",
     "templating",
-    "dynamic rendering",
+    "modern web technologies",
     "responsive design",
-    "business documentation",
-    "automated workflows",
-    "modular architecture",
-    "smart contracts",
-    "javascript",
     "QR code",
-    "custom elements",
-    "nodejs",
-    "data-driven"
+    "modular architecture",
+    "automated workflows",
+    "localization",
+    "digital signatures",
+    "security",
+    "interactive documents"
   ],
   "scripts": {
     "test": "npm run build && tstest test/",
-    "build": "tsbuild --allowimplicitany && tsbuild element --allowimplicitany && tsbundle element --production",
+    "build": "tsbuild tsfolders --allowimplicitany && tsbuild element --allowimplicitany && tsbundle element --production",
     "watch": "tswatch element",
     "buildDocs": "tsdoc"
   }

package/readme.md

@@ -1,169 +1,177 @@
 # @design.estate/dees-document
 
-A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation.
+A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.
 
 ## Install
 
-To add `@design.estate/dees-document` to your project, run the following command in your terminal:
+To incorporate `@design.estate/dees-document` into your project, execute the following command in your terminal:
 
 ```shell
 npm install @design.estate/dees-document --save
 ```
 
-This will install the package and add it to your project's dependencies, ensuring all required modules are available in your `node_modules` directory.
+This command will install the package and add it to your project's dependencies, thus making all the necessary modules available within your `node_modules` directory.
 
 ## Usage
 
-The `@design.estate/dees-document` package provides a robust framework for creating documents including invoices, contracts, and various other business-related documents. It is built on modern web technologies including TypeScript and ES modules to ensure a type-safe and easy-to-integrate experience. Below, we will guide you through the comprehensive usage of this package, from setting up your environment to generating PDF documents. 
+The `@design.estate/dees-document` package serves as a robust framework to facilitate the generation of business documents, such as invoices, contracts, and reports. Leveraging modern web technologies, this package integrates seamlessly with TypeScript and ES modules, offering a type-safe environment conducive to efficient, dynamic document creation.
 
-### Getting Started
+Below, we provide a detailed guide for utilizing this package, from initializing your environment to generating complete PDF documents. 
 
-Before creating documents, initialize the document service which is central to this package. This is typically done at the beginning of your application.
+### Setting Up the Environment
+
+Before diving into document creation, ensure your environment is properly configured. Make sure to import necessary dependencies and setup configurations:
 
 ```typescript
 import { PdfService, IPdfServiceConstructorOptions } from '@design.estate/dees-document';
 
 async function setupPdfService() {
   const options: IPdfServiceConstructorOptions = {
-    // Add necessary configuration here
+    // Configure your options here
   };
-  
+
   const pdfService = await PdfService.createAndStart(options);
   console.log('PDF Service started successfully.');
   return pdfService;
 }
 ```
 
-This script initializes `PdfService`. Modify the options to tailor the service to your needs.
-
-### Creating Documents
-
-With the PDF service ready, you can proceed to generate documents. The following section provides a detailed example of creating an invoice. This example is applicable to various document types with necessary adjustments.
-
-#### Step-by-Step: Create an Invoice
-
-1. **Define the Data Structure**: Describe the invoice details. This includes sender and recipient information, the items being invoiced, and more.
-
-   ```typescript
-   import { ILetter } from '@design.estate/dees-document';
-
-   const invoiceData: ILetter = {
-     from: {
-       name: "Your Company Name",
-       address: {
-         streetName: "Your Street",
-         houseNumber: "123",
-         city: "Your City",
-         country: "Your Country",
-         postalCode: "12345",
-       },
-       email: "your-email@example.com",
-       phone: "123-456-7890",
-     },
-     to: {
-       name: "Recipient Company Name",
-       address: {
-         streetName: "Recipient Street",
-         houseNumber: "456",
-         city: "Recipient City",
-         country: "Recipient Country",
-         postalCode: "67890",
-       },
-       email: "recipient-email@example.com",
-       phone: "098-765-4321",
-     },
-     content: {
-       invoiceData: {
-         items: [
-           {
-             name: "Service or Product Name",
-             unitQuantity: 2,
-             unitNetPrice: 100.00,
-             unitType: 'service',
-             vatPercentage: 19,
-             currency: 'EUR',
-           }
-         ]
-       }
-     },
-     subject: "Invoice for Services Rendered",
-     date: new Date().getTime(),
-     versionInfo: {
-       type: "final",
-       version: "1.0.0"
-     },
-   };
-   ```
+In this setup snippet, you set up the `PdfService` which is the core component for PDF generation. The configuration options should be adjusted to fit your needs, especially considering options such as file paths, languages, and template directories.
+
+### Creating a Document Template
+
+To create documents, particularly invoices, you'll first need to define a template. This template describes the structure of your document:
+
+```typescript
+import { ILetter } from '@design.estate/dees-document';
+
+const invoiceTemplate: ILetter = {
+  from: {
+    name: "Your Company Name",
+    address: {
+      streetName: "Your Street",
+      houseNumber: "123",
+      city: "Your City",
+      country: "Your Country",
+      postalCode: "12345",
+    },
+    email: "your-email@example.com",
+    phone: "123-456-7890",
+  },
+  to: {
+    name: "Recipient Company Name",
+    address: {
+      streetName: "Recipient Street",
+      houseNumber: "456",
+      city: "Recipient City",
+      country: "Recipient Country",
+      postalCode: "67890",
+    },
+    email: "recipient-email@example.com",
+    phone: "098-765-4321",
+  },
+  content: {
+    invoiceData: {
+      items: [
+        {
+          name: "Service or Product Name",
+          unitQuantity: 2,
+          unitNetPrice: 100.00,
+          unitType: 'service',
+          vatPercentage: 19,
+          currency: 'EUR',
+        }
+      ]
+    }
+  },
+  subject: "Invoice for Services Rendered",
+  date: new Date().getTime(),
+  versionInfo: {
+    type: "final",
+    version: "1.0.0"
+  },
+};
+```
 
-   Here, `ILetter` interface details all components of an invoice including sender (`from`) and recipient (`to`) information, as well as the invoiced items.
+The `invoiceTemplate` object utilizes the `ILetter` interface which specifies the structure for invoice data, including sender and recipient details, itemization, and pricing.
 
-2. **Generate the PDF**: Transform the invoice details into a PDF.
+### Generating the Document
 
-   ```typescript
-   async function generateInvoice(pdfService: PdfService, invoiceData: ILetter) {
-     const pdfBuffer = await pdfService.createPdfFromLetterObject(invoiceData);
-     console.log('Invoice PDF generated successfully.');
+Once a template is established, the next step is generating a PDF:
 
-     // Save the PDF, send it via email, etc.
-   }
-   ```
+```typescript
+async function generateInvoice(pdfService: PdfService, invoiceData: ILetter) {
+  const pdfBuffer = await pdfService.createPdfFromLetterObject(invoiceData);
+  console.log('Invoice PDF generated successfully.');
 
-   The function `createPdfFromLetterObject` returns a `Buffer` containing the generated PDF. From here, you can save this PDF to a file, send it to clients, or archive it.
+  // Here you could save the PDF to your filesystem, send it via email, etc.
+}
+```
 
-3. **Integrate It All**: Here's how everything ties together into a complete script for generating an invoice:
+In this function, the `createPdfFromLetterObject` method converts your invoice data into a `Buffer` containing the PDF. This `Buffer` can subsequently be saved as a file or sent over HTTP.
 
-   ```typescript
-   async function main() {
-     const pdfService = await setupPdfService();
-     await generateInvoice(pdfService, invoiceData);
-   }
+### Comprehensive Example
 
-   main().then(() => console.log('Invoice generation process completed.'));
-   ```
+Below is an example integrating all previous steps into a single coherent script:
 
-   This script initiates the PDF service and generates the invoice PDF with the provided information.
+```typescript
+async function main() {
+  const pdfService = await setupPdfService();
+  const invoiceData: ILetter = {
+    // Populate your invoice object
+  };
+  await generateInvoice(pdfService, invoiceData);
+}
 
-### Advanced Document Features
+main().then(() => console.log('Invoice generation process completed.'));
+```
 
-The package is designed to create not only invoices but a wide range of document types. Leverage its modular architecture to build and customize documents to fit specific needs.
+This script encompasses initializing services and generating a PDF in a streamlined, efficient workflow.
 
-#### Advanced Scenarios
+### Advanced Features
 
-1. **Custom Styling**: Customize the appearance of elements within your documents, such as headers, footers, and more.
+`@design.estate/dees-document` provides several advanced functionalities, enabling rich document creation:
+
+1. **Custom Templates & Styling**
+   - Customize the styling through CSS or using inline styles in TypeScript.
+   - Templates can be adjusted to present different document types (e.g., contracts, reports).
+
+2. **Modular Components and Reuse**
+   - Utilize modular components to create reusable parts across different documents, enhancing maintainability and reducing redundancy.
+
+3. **Interactive Documents**
+   - Integrate interactivities like forms, buttons, and interactive charts within your documents.
+
+4. **Localization Support**
+   - Documents can be localized to support multiple languages, enhancing accessibility and usability.
+
+5. **Responsive and Adaptive Designs**
+   - Create documents that adjust layout dynamically depending on print or digital medium, maintaining consistency across platforms.
+
+6. **Security Features**
+   - Apply digital signatures and encrypt sensitive documents to ensure secure and authentic document distribution.
+
+7. **Complex Business Logic**
+   - Implement complex logic for feature-rich documents such as inventory systems, automatic tax calculations, or real-time pricing adjustments.
+
+### Utilize Translation for Localization
+
+The package offers a translation mechanism to adapt your documents for international clients:
+
+```typescript
+import { translate } from '@design.estate/dees-document/shared';
+
+const languageCode: 'DE' | 'EN' | 'ES' = 'EN'; // Set required language code
+console.log(translate(languageCode, 'invoice', 'Invoice')); // Translated output
+```
 
-   ```typescript
-   import { DeDocumentViewer } from '@design.estate/dees-element';
+Different language settings can be applied, enabling the seamless presentation of document contents tailored to regional and linguistic preferences.
 
-   const customStyledViewer = new DeDocumentViewer();
-   customStyledViewer.style.setProperty('--main-bg-color', 'lightblue');
-   document.body.appendChild(customStyledViewer);
-   ```
-
-   Customize via CSS or dynamically through TypeScript where necessary.
-
-2. **Interactive Document Elements**: Incorporate UI components like buttons, input fields, or visualizations tailored for your document needs.
-
-3. **Multi-page Document Generation**: Handle overflow of content and automatic page generation while maintaining headers and footers.
-
-   ```typescript
-   pdfService.adjustDePageScaling();
-   ```
-
-   Toggle between print and digital formats and handle scaling.
-
-4. **Embedding Images and Logos**: Add company logos, graphics, or auxiliary content to enhance document presentation.
-
-### Additional Capabilities
-
-Beyond these examples, delve deeper into advanced functionalities such as:
-
-- **Document Management**: Manage multiple document templates, manage versions, and add annotations or notes.
-- **Dynamic Rendering**: Use templating for dynamic content rendering based on variable inputs.
-- **Responsive Design for Digital Documents**: Ensure documents are displayed correctly across devices.
+### Conclusion
 
-### Concluding Remarks
+The `@design.estate/dees-document` package is a versatile and powerful solution for businesses seeking to automate and streamline their document generation processes using modern web technologies. By integrating seamlessly with TypeScript, it offers robust capabilities for creating complex, customizable, and interactive documents that can meet a variety of business needs.
 
-The `@design.estate/dees-document` package is an essential tool in the modern document generation ecosystem. Its expansive capabilities, from basic invoices to complex document templates, make it a versatile solution for businesses of all scales. Implementing this service broadly simplifies document management workflows and enhances document presentation precision and quality. For further depth, consult the package's documentation or explore the examples included in the module.
+From custom templates to localization and advanced security features, this module provides the flexibility and power to create polished and professional documents efficiently. Whether you're generating invoices, contracts, or detailed reports, `@design.estate/dees-document` has the tools to support your enterprise workflows with ease and precision.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-document',
-  version: '1.1.0',
-  description: 'A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements.'
+  version: '1.3.1',
+  description: 'A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.'
 }

package/ts/interfaces/document.ts

@@ -1,5 +1,8 @@
+import * as shared from '../shared/index.js';
+
 export interface IDocumentSettings {
   enableTopDraftText?: boolean;
   enableDefaultHeader?: boolean;
   enableDefaultFooter?: boolean;
+  languageCode?: shared.translation.TLanguageCode;
 }

package/ts/interfaces/translation.ts

@@ -1,4 +1,19 @@
 export interface IDeDocumentTranslations {
-  "invoice": string;
-  "quantity": string;
+  address: string;
+  bankConnection: string;
+  contactInfo: string;
+  description: string;
+  invoice: string;
+  itemPos: string;
+  quantity: string;
+  registrationInfo: string;
+  reverseVatNote: string;
+  totalNetPrice: string;
+  unitNetPrice: string;
+  unitType: string;
+  yourCustomerId: string;
+  yourVatId: string;
+  continuesOnPage: string;
+  finalPageStatement: string;
+  page: string;
 }

package/{ts_web/elements → ts}/shared/demoletter.ts

@@ -1,4 +1,6 @@
 import * as tsclass from '@tsclass/tsclass';
+import * as interfaces from '../interfaces/index.js';
+
 const fromContact: tsclass.business.IContact = {
   name: 'Awesome From Company',
   type: 'company',
@@ -207,4 +209,11 @@ export const demoLetter: tsclass.business.ILetter = {
   logoUrl: null,
   pdfAttachments: null,
   subject: 'Invoice: LL-INV-48765',
-}
+}
+
+export const demoDocumentSettings: interfaces.IDocumentSettings = {
+  enableTopDraftText: true,
+  enableDefaultHeader: true,
+  enableDefaultFooter: true,
+  languageCode: 'DE',
+};

package/{ts_web/elements → ts}/shared/index.ts

@@ -6,4 +6,4 @@ export const leftMargin = 90;
 import * as translation from './translation.js';
 export { translation };
 
-export * from './demoletter.js';
+export * from './demoletter.js';

package/ts/shared/translation.ts

@@ -0,0 +1,82 @@
+import * as interfaces from '../interfaces/index.js';
+
+type TTranslationImplementation = {
+  [key in keyof interfaces.IDeDocumentTranslations]: string;
+}
+
+export const EN_translations: TTranslationImplementation = {
+  address: 'Address',
+  bankConnection: 'Bank Connection',
+  contactInfo: 'Contact Info',
+  description: 'Description',
+  invoice: 'Invoice',
+  itemPos: 'Item Pos.',
+  quantity: 'Quantity',
+  registrationInfo: 'Registration Info',
+  reverseVatNote: 'VAT arises on a reverse charge basis and is payable by the customer.',
+  totalNetPrice: 'Total Net Price',
+  unitNetPrice: 'Unit Net Price',
+  unitType: 'Unit Type',
+  yourCustomerId: 'Your Customer ID:',
+  yourVatId: 'Your vat id on file:',
+  continuesOnPage: 'Continues on page',
+  finalPageStatement: 'This is the final page of this document.',
+  page: 'Page',
+};
+
+export const DE_translations: TTranslationImplementation = {
+  address: 'Adresse',
+  bankConnection: 'Bankverbindung',
+  contactInfo: 'Kontaktinformationen',
+  description: 'Beschreibung',
+  invoice: 'Rechnung',
+  itemPos: 'Pos.',
+  quantity: 'Anzahl',
+  registrationInfo: 'HRA/HRB Info',
+  reverseVatNote: 'Umkehr der Umsatzsteuerpflicht: Der Rechnungsempfänger ist für die korrekte Abrechnung der Umsatzsteuer zuständig.',
+  totalNetPrice: 'Nettopreis Summe',
+  unitNetPrice: 'Nettopreis',
+  unitType: 'Einheit',
+  yourCustomerId: 'Ihre Kundennummer:',
+  yourVatId: 'Ihre Umsatzsteuer-ID:',
+  continuesOnPage: 'Fortsetzung auf Seite',
+  finalPageStatement: 'Diese ist die letzte Seite einer Dokumente.',
+  page: 'Seite',
+};
+
+export const ES_translations: TTranslationImplementation = {
+  address: 'Dirección',
+  bankConnection: 'Conexión bancaria',
+  contactInfo: 'Información de contacto',
+  description: 'Descripción',
+  invoice: 'Factura',
+  itemPos: 'Pos.',
+  quantity: 'Cantidad',
+  registrationInfo: 'Información de registro',
+  reverseVatNote: 'La declaración de IVA se aplica en base a la factura de venta, y se paga por el cliente.',
+  totalNetPrice: 'Precio total neto',
+  unitNetPrice: 'Precio unitario neto',
+  unitType: 'Tipo de unidad',
+  yourCustomerId: 'Su número de cliente:',
+  yourVatId: 'Su ID de IVA:',
+  continuesOnPage: 'Continues on page',
+  finalPageStatement: 'This is the final page of this document.',
+  page: 'Page',
+};
+
+export const languageCodeMap = {
+  'DE': DE_translations,
+  'EN': EN_translations,
+  'ES': ES_translations,
+};
+
+export type TLanguageCode = keyof typeof languageCodeMap;
+
+export const translate = (languageCode: TLanguageCode, key: string, defaultValue: string) => {
+  const translations = languageCodeMap[languageCode] || EN_translations;
+  if (translations && translations[key]) {
+    return translations[key];
+  } else {
+    return defaultValue;
+  }
+};

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-document',
-  version: '1.1.0',
-  description: 'A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements.'
+  version: '1.3.1',
+  description: 'A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.'
 }

package/ts_web/elements/contentinvoice.ts

@@ -15,8 +15,8 @@ import {
   domtools,
 } from '@design.estate/dees-element';
 import * as plugins from '../plugins.js';
-import * as shared from './shared/index.js';
-
+import * as shared from '../../ts/shared/index.js';
+import * as interfaces from '../../ts/interfaces/index.js';
 
 
 declare global {
@@ -45,6 +45,12 @@ export class DeContentInvoice extends DeesElement {
   })
   public letterData: plugins.tsclass.business.ILetter;
 
+  @property({
+    type: Object,
+    reflect: true,
+  })
+  public documentSettings: interfaces.IDocumentSettings;
+
   constructor() {
     super();
     domtools.DomTools.setupDomTools();
@@ -275,12 +281,12 @@ export class DeContentInvoice extends DeesElement {
         </style>
         <div>We hereby invoice products and services provided to you by Lossless GmbH:</div>
         <div class="grid topLine dataHeader">
-          <div class="lineItem">Item Pos.</div>
-          <div class="lineItem">${shared.translation.translate('DE', 'description', 'Description')}</div>
-          <div class="lineItem">${shared.translation.translate('DE', 'quantity', 'Quantity')}</div>
-          <div class="lineItem">Unit Type</div>
-          <div class="lineItem">Unit Net Price</div>
-          <div class="lineItem">Total Net Price</div>
+          <div class="lineItem">${shared.translation.translate(this.documentSettings.languageCode, 'itemPos', 'Item Pos.')}</div>
+          <div class="lineItem">${shared.translation.translate(this.documentSettings.languageCode, 'description', 'Description')}</div>
+          <div class="lineItem">${shared.translation.translate(this.documentSettings.languageCode, 'quantity', 'Quantity')}</div>
+          <div class="lineItem">${shared.translation.translate(this.documentSettings.languageCode, 'unitType', 'Unit Type')}</div>
+          <div class="lineItem">${shared.translation.translate(this.documentSettings.languageCode, 'unitNetPrice', 'Unit Net Price')}</div>
+          <div class="lineItem">${shared.translation.translate(this.documentSettings.languageCode, 'totalNetPrice', 'Total Net Price')}</div>
         </div>
         ${(() => {
           let counter = 1;
@@ -329,7 +335,7 @@ export class DeContentInvoice extends DeesElement {
         ${this.letterData?.content.invoiceData.reverseCharge
           ? html`
               <div class="taxNote">
-                VAT arises on a reverse charge basis and is payable by the customer.
+                ${shared.translation.translate(this.documentSettings.languageCode, 'reverseVatNote', 'VAT arises on a reverse charge basis and is payable by the customer.')}
               </div>
             `
           : ``}

package/ts_web/elements/document.demo.ts

@@ -1,4 +1,4 @@
-import * as shared from './shared/index.js';
+import * as shared from '../../ts/shared/index.js';
 import { html } from '@design.estate/dees-element';
 
 export const demoFunc = () => html`

package/ts_web/elements/document.ts

@@ -24,7 +24,7 @@ export const defaultDocumentSettings: interfaces.IDocumentSettings = {
 import { DePage } from './page.js';
 import { DeContentInvoice } from './contentinvoice.js';
 
-import * as shared from './shared/index.js';
+import * as shared from '../../ts/shared/index.js';
 import { demoFunc } from './document.demo.js';
 
 declare global {
@@ -146,6 +146,7 @@ export class DeDocument extends DeesElement {
     // lets append the content
     const content: DeContentInvoice = new DeContentInvoice();
     content.letterData = this.letterData;
+    content.documentSettings = this.documentSettings;
     document.body.appendChild(content);
 
     await domtools.convenience.smartdelay.delayFor(0);
@@ -158,6 +159,7 @@ export class DeDocument extends DeesElement {
       const newPage = new DePage();
       newPage.printMode = this.printMode;
       newPage.letterData = this.letterData;
+      newPage.documentSettings = this.documentSettings;
       pages.push(newPage);
       newPage.pageNumber = pageCounter;
       newPage.append(currentContent);

package/ts_web/elements/index.ts

@@ -8,4 +8,4 @@ export * from './pagefooter.js';
 export * from './pageheader.js';
 export * from './viewer.js';
 
-export * from './shared/index.js';
+export * from '../../ts/shared/index.js';

package/ts_web/elements/letterheader.ts

@@ -10,7 +10,7 @@ import {
 } from '@design.estate/dees-element';
 import * as domtools from '@design.estate/dees-domtools';
 
-import * as shared from './shared/index.js';
+import * as shared from '../../ts/shared/index.js';
 import * as tsclass from '@tsclass/tsclass';
 
 declare global {