@design.estate/dees-document 1.0.103 → 1.3.0

package/npmextra.json

@@ -5,28 +5,26 @@
       "githost": "code.foss.global",
       "gitscope": "designestate/private",
       "gitrepo": "dedocument-catalog",
-      "description": "A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation.",
+      "description": "A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.",
       "npmPackagename": "@designestate_private/dedocument-catalog",
       "license": "MIT",
       "projectDomain": "design.estate",
       "shortDescription": "undefined variable",
       "keywords": [
         "document generation",
-        "invoices",
+        "invoice automation",
+        "business documentation",
+        "dynamic rendering",
         "PDF creation",
-        "typescript",
         "web components",
-        "custom elements",
-        "QR code",
-        "smart contracts",
+        "Node.js",
+        "TypeScript",
         "templating",
-        "dynamic rendering",
+        "modern web technologies",
         "responsive design",
-        "modular development",
-        "lightweight",
-        "efficient",
-        "finance",
-        "business"
+        "QR code",
+        "modular architecture",
+        "automated workflows"
       ]
     }
   },

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@design.estate/dees-document",
-  "version": "1.0.103",
+  "version": "1.3.0",
   "private": false,
-  "description": "A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation.",
+  "description": "A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.",
   "main": "dist_ts_web/index.js",
   "typings": "dist_ts_web/index.d.ts",
   "exports": {
@@ -19,9 +19,10 @@
     "@push.rocks/smartfile": "^11.0.21",
     "@push.rocks/smartjson": "^5.0.20",
     "@push.rocks/smartpath": "^5.0.18",
-    "@push.rocks/smartpdf": "^3.1.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,21 +60,19 @@
   "homepage": "https://gitlab.com/designestate/private/dedocument-catalog#readme",
   "keywords": [
     "document generation",
-    "invoices",
+    "invoice automation",
+    "business documentation",
+    "dynamic rendering",
     "PDF creation",
-    "typescript",
     "web components",
-    "custom elements",
-    "QR code",
-    "smart contracts",
+    "Node.js",
+    "TypeScript",
     "templating",
-    "dynamic rendering",
+    "modern web technologies",
     "responsive design",
-    "modular development",
-    "lightweight",
-    "efficient",
-    "finance",
-    "business"
+    "QR code",
+    "modular architecture",
+    "automated workflows"
   ],
   "scripts": {
     "test": "npm run build && tstest test/",

package/readme.md

@@ -1,26 +1,32 @@
+```markdown
 # @design.estate/dees-document
-a catalog for creating documents like invoices
+
+A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements.
 
 ## Install
-To install `@design.estate/dees-document`, run the following command in your project directory:
+
+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 add `@design.estate/dees-document` to your project's dependencies and ensure it's installed into your `node_modules` folder.
+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 is a comprehensive toolkit for creating various types of documents, such as invoices, with ease. It leverages modern ECMAScript (ES) modules and TypeScript for a type-safe, developer-friendly experience. Below, you'll find detailed examples covering how to utilize the package to its full potential.
 
-### Setting Up the Document Service
-Before diving into creating documents, you first need to set up the document service. This involves importing the necessary modules and initializing the service instance.
+The `@design.estate/dees-document` package serves as a robust framework to facilitate the generation of business documents, such as invoices and contracts. Leveraging modern web technologies, this package integrates seamlessly with TypeScript and ES modules, offering a type-safe environment conducive to efficient, dynamic document creation. Presented here is a comprehensive guide to utilizing this package, ranging from initializing your environment to generating complete PDF documents.
+
+### Getting Started
+
+To embark on a document creation journey, initiate the document service. This service constitutes the core of this package and is typically started at the application's outset.
 
 ```typescript
 import { PdfService, IPdfServiceConstructorOptions } from '@design.estate/dees-document';
 
 async function setupPdfService() {
   const options: IPdfServiceConstructorOptions = {
-    // Configuration options here
+    // configure your options here
   };
   
   const pdfService = await PdfService.createAndStart(options);
@@ -29,100 +35,138 @@ async function setupPdfService() {
 }
 ```
 
-In the example above, we import `PdfService` from the package and use its `createAndStart` method to initialize it with optional configuration settings. Replace `// Configuration options here` with any specific options your project may require.
+The above code initializes the `PdfService`. Tailor the configuration options to suit your specific requirements.
+
+### Creating Documents
+
+With the PDF service initialized, you can now proceed to generate your documents. In the following section, you will find a detailed walkthrough for creating an invoice. This method can be adapted to other document types with necessary modifications.
+
+#### Step-by-Step: Create an Invoice
+
+1. **Define the Data Structure**: Construct the details of the invoice, including the sender, recipient information, and the details of the items being invoiced.
+
+   ```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"
+     },
+   };
+   ```
 
-### Creating a Simple Invoice
-After setting up the document service, you can proceed to create documents such as invoices. Here, we'll demonstrate how to create a basic invoice.
+   The `ILetter` interface captures all the components of an invoice, including both the sender (`from`) and recipient (`to`) information, alongside the details of the invoiced items.
 
-#### Define the Invoice Data Structure
-First, define the basic structure of your invoice. This involves specifying details like the sender, recipient, items, and more.
+2. **Generate the PDF**: Convert the invoice details into a PDF file.
 
-```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"
-  },
-};
-```
+   ```typescript
+   async function generateInvoice(pdfService: PdfService, invoiceData: ILetter) {
+     const pdfBuffer = await pdfService.createPdfFromLetterObject(invoiceData);
+     console.log('Invoice PDF generated successfully.');
 
-In this structure, `invoiceData` outlines essential details for an invoice document, using the `ILetter` interface. It includes information about both the sender (`from`) and the recipient (`to`), as well as the invoiced items under `content.invoiceData.items`.
+     // Here you could save the PDF to your filesystem, send it via email, etc.
+   }
+   ```
 
-#### Generate the Invoice PDF
-With the invoice data ready, you can now generate the PDF using the `PdfService` instance.
+   The `createPdfFromLetterObject` function returns a `Buffer` that contains the generated PDF, enabling you to save it to a file, send it to clients, or store it for record-keeping.
 
-```typescript
-async function generateInvoice(pdfService: PdfService, invoiceData: ILetter) {
-  const pdfBuffer = await pdfService.createPdfFromLetterObject(invoiceData);
-  console.log('Invoice PDF generated successfully.');
+3. **Integrate It All**: The following script ties together the PDF service and generates the invoice with the described data.
 
-  // Here, you can save the PDF to a file, send it over a network, etc.
-}
-```
+   ```typescript
+   async function main() {
+     const pdfService = await setupPdfService();
+     await generateInvoice(pdfService, invoiceData);
+   }
 
-The method `createPdfFromLetterObject` receives the invoice data and returns a `Buffer` containing the PDF. You can then save this PDF to the filesystem, send it over email, or perform any other required actions.
+   main().then(() => console.log('Invoice generation process completed.'));
+   ```
 
-#### Complete Example Integration
-Combining everything, your complete script to set up the service, define invoice data, and generate a PDF invoice might look something like this:
+   This example initiates the PDF service and utilizes it to generate a PDF invoice with specified parameters.
 
-```typescript
-async function main() {
-  const pdfService = await setupPdfService();
-  await generateInvoice(pdfService, invoiceData);
-}
+### Advanced Document Features
 
-main().then(() => console.log('Invoice generation process completed.'));
-```
+The package is designed to create a broad range of documents, far beyond simple invoices. Utilize the modular architecture to customize documents to your specific business requirements.
+
+#### Advanced Scenarios
 
-### Beyond Invoices
-The `@design.estate/dees-document` package is not limited to invoices alone. It's designed to handle a wide range of document types. The modular architecture allows for the customizable construction of documents, enabling you to tailor the output to meet precise requirements.
+1. **Custom Styling**: Alter the visual styles of various elements within your documents, like headers, footers, and more through CSS or inline styles.
 
-For instance, you can create contracts, reports, and other document types using a similar approach—by defining the content structure and utilizing the PDF service to generate the document. The package's flexibility and extensibility make it an invaluable tool in any document generation workflow.
+   ```typescript
+   import { DeDocumentViewer } from '@design.estate/dees-element';
+
+   const customStyledViewer = new DeDocumentViewer();
+   customStyledViewer.style.setProperty('--main-bg-color', 'lightblue');
+   document.body.appendChild(customStyledViewer);
+   ```
+
+   Adjust styles either with standard CSS or via dynamic TypeScript changes.
+
+2. **Interactive Document Elements**: Integrate interactive UI components, like buttons or input fields, fitting seamlessly into your documents.
+
+3. **Multi-page Document Generation**: Handle content overflow elegantly through automatic page creation, keeping headers and footers intact.
+
+   ```typescript
+   pdfService.adjustDePageScaling();
+   ```
+
+   Adapt between print and digital formats, managing scaling effectively.
+
+4. **Embedding Images and Logos**: Enhance your document's appearance with company logos, graphics, and other auxiliary content.
+
+### Additional Capabilities
+
+Beyond basic functionality, this package offers a range of advanced features:
+
+- **Document Management**: Manage multiple document templates, maintain version control, and append annotations or notes.
+- **Dynamic Rendering**: Utilize templating engines to render dynamic content based on input variables.
+- **Responsive Design for Digital Documents**: Ensure your documents are consistently displayed across various devices.
+
+### Concluding Remarks
+
+The `@design.estate/dees-document` package presents a powerful solution within the modern document generation realm. From basic invoices to intricate templates, this package provides the essential tools for businesses to streamline their document workflows and enhance their presentation quality and accuracy. Explore further depth by consulting the package’s detailed documentation or by reviewing the examples included within the module.
+```
 
-### Advanced Usage
-For more advanced scenarios, such as custom styling, embedding images, and handling more complex document structures, refer to the package's documentation. It provides comprehensive details and examples to help you fully leverage the capabilities of `@design.estate/dees-document`.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-document',
-  version: '1.0.103',
-  description: 'A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation.'
+  version: '1.3.0',
+  description: 'A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.'
 }

package/ts/classes.pdfservice.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import * as paths from './paths.js';
 import * as helpers from './helpers.js';
+import * as interfaces from '../ts/interfaces/index.js';
 
 export interface IPdfServiceConstructorOptions {
 
@@ -44,12 +45,15 @@ export class PdfService {
   /**
    * creates an letter
    */
-  public async createPdfFromLetterObject(letterDataArg: plugins.tsclass.business.ILetter) {
+  public async createPdfFromLetterObject(optionsArg: {
+    letterData: plugins.tsclass.business.ILetter,
+    documentSettings: interfaces.IDocumentSettings
+  }) {
     const html = `
       <script type="module">
         ${await helpers.getBundleAsString()}
       </script>
-      <dedocument-dedocument printMode letterData="${plugins.smartjson.stringifyBase64(letterDataArg)}"></dedocument-dedocument>
+      <dedocument-dedocument printMode documentSettings="${plugins.smartjson.stringifyBase64(optionsArg.documentSettings)}" letterData="${plugins.smartjson.stringifyBase64(optionsArg.letterData)}"></dedocument-dedocument>
     `;
     // console.log(html);
     const pdfResult = await this.smartpdfInstance.getA4PdfResultForHtmlString(html);

package/ts/interfaces/document.ts

@@ -0,0 +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/index.ts

@@ -0,0 +1,2 @@
+export * from './document.js';
+export * from './translation.js';

package/ts/interfaces/translation.ts

@@ -0,0 +1,19 @@
+export interface IDeDocumentTranslations {
+  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

@@ -3,4 +3,7 @@ export const a4Width = 794;
 export const rightMargin = 70;
 export const leftMargin = 90;
 
-export * from './demoletter.js';
+import * as translation from './translation.js';
+export { translation };
+
+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.0.103',
-  description: 'A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation.'
+  version: '1.3.0',
+  description: 'A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.'
 }

package/ts_web/elements/contentinvoice.ts

@@ -12,12 +12,11 @@ import {
   cssManager,
   unsafeCSS,
   render,
+  domtools,
 } from '@design.estate/dees-element';
-import * as domtools from '@design.estate/dees-domtools';
-
 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 {
@@ -46,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();
@@ -276,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">Description</div>
-          <div class="lineItem">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;
@@ -330,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`