From 4c9b2671a91c515d059f248811c8f78588c14f3b Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Sun, 1 Dec 2024 23:04:28 +0100 Subject: [PATCH] feat(core): Enhance document generation capabilities with improved modular structure and extended translation support. --- changelog.md | 9 +++ npmextra.json | 27 ++++----- package.json | 30 +++++----- pnpm-lock.yaml | 3 + readme.md | 57 ++++++++++--------- ts/00_commitinfo_data.ts | 4 +- ts/interfaces/document.ts | 3 + {ts_web/elements => ts}/shared/demoletter.ts | 11 +++- {ts_web/elements => ts}/shared/index.ts | 2 +- {ts_web/elements => ts}/shared/translation.ts | 2 +- ts_web/00_commitinfo_data.ts | 4 +- ts_web/elements/contentinvoice.ts | 2 +- ts_web/elements/document.demo.ts | 2 +- ts_web/elements/document.ts | 2 +- ts_web/elements/index.ts | 2 +- ts_web/elements/letterheader.ts | 2 +- ts_web/elements/page.ts | 2 +- ts_web/elements/pagecontainer.ts | 2 +- ts_web/elements/pagecontent.ts | 2 +- ts_web/elements/pagefooter.ts | 2 +- ts_web/elements/pageheader.ts | 2 +- ts_web/elements/viewer.demo.ts | 4 +- ts_web/elements/viewer.ts | 6 +- 23 files changed, 104 insertions(+), 78 deletions(-) rename {ts_web/elements => ts}/shared/demoletter.ts (95%) rename {ts_web/elements => ts}/shared/index.ts (85%) rename {ts_web/elements => ts}/shared/translation.ts (92%) diff --git a/changelog.md b/changelog.md index 5f4b0d9..acf2323 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,14 @@ # Changelog +## 2024-12-01 - 1.2.0 - feat(core) +Enhance document generation capabilities with improved modular structure and extended translation support. + +- Enhanced document generation framework with a more modular structure. +- Integrated support for translations using JSON-based language maps. +- Optimized PDF generation process for dynamic document content. +- Added properties in 'IDocumentSettings' for language code management. +- Updated README documentation with more comprehensive examples and guidance. + ## 2024-11-30 - 1.1.0 - feat(core) Enhanced document generation features and added translation capabilities diff --git a/npmextra.json b/npmextra.json index de12191..edbb10b 100644 --- a/npmextra.json +++ b/npmextra.json @@ -5,29 +5,26 @@ "githost": "code.foss.global", "gitscope": "designestate/private", "gitrepo": "dedocument-catalog", - "description": "A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements.", + "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", - "PDF creation", - "TypeScript", - "web components", - "templating", - "dynamic rendering", - "responsive design", + "invoice automation", "business documentation", - "automated workflows", - "modular architecture", - "smart contracts", - "javascript", + "dynamic rendering", + "PDF creation", + "web components", + "Node.js", + "TypeScript", + "templating", + "modern web technologies", + "responsive design", "QR code", - "custom elements", - "nodejs", - "data-driven" + "modular architecture", + "automated workflows" ] } }, diff --git a/package.json b/package.json index fff5278..d0cc4b2 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@design.estate/dees-document", "version": "1.1.0", "private": false, - "description": "A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements.", + "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": { @@ -28,6 +28,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" }, @@ -65,21 +66,18 @@ "homepage": "https://gitlab.com/designestate/private/dedocument-catalog#readme", "keywords": [ "document generation", - "invoices", - "PDF creation", - "TypeScript", - "web components", - "templating", - "dynamic rendering", - "responsive design", + "invoice automation", "business documentation", - "automated workflows", - "modular architecture", - "smart contracts", - "javascript", + "dynamic rendering", + "PDF creation", + "web components", + "Node.js", + "TypeScript", + "templating", + "modern web technologies", + "responsive design", "QR code", - "custom elements", - "nodejs", - "data-driven" + "modular architecture", + "automated workflows" ] -} +} \ No newline at end of file diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c3e653d..b670fc8 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -38,6 +38,9 @@ importers: '@tsclass/tsclass': specifier: ^4.1.2 version: 4.1.2 + '@types/node': + specifier: ^22.10.1 + version: 22.10.1 '@types/qrcode': specifier: ^1.5.5 version: 1.5.5 diff --git a/readme.md b/readme.md index 3776773..8fb5598 100644 --- a/readme.md +++ b/readme.md @@ -1,31 +1,32 @@ +```markdown # @design.estate/dees-document -A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation. +A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements. ## 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 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 -Before creating documents, initialize the document service which is central to this package. This is typically done at the beginning of your application. +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 = { - // Add necessary configuration here + // configure your options here }; const pdfService = await PdfService.createAndStart(options); @@ -34,15 +35,15 @@ async function setupPdfService() { } ``` -This script initializes `PdfService`. Modify the options to tailor the service to your needs. +The above code initializes the `PdfService`. Tailor the configuration options to suit your specific requirements. ### 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. +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**: Describe the invoice details. This includes sender and recipient information, the items being invoiced, and more. +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'; @@ -95,22 +96,22 @@ With the PDF service ready, you can proceed to generate documents. The following }; ``` - Here, `ILetter` interface details all components of an invoice including sender (`from`) and recipient (`to`) information, as well as the invoiced items. + 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. -2. **Generate the PDF**: Transform the invoice details into a PDF. +2. **Generate the PDF**: Convert the invoice details into a PDF file. ```typescript async function generateInvoice(pdfService: PdfService, invoiceData: ILetter) { const pdfBuffer = await pdfService.createPdfFromLetterObject(invoiceData); console.log('Invoice PDF generated successfully.'); - // Save the PDF, send it via email, etc. + // Here you could save the PDF to your filesystem, send it via email, etc. } ``` - 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. + 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. -3. **Integrate It All**: Here's how everything ties together into a complete script for generating an invoice: +3. **Integrate It All**: The following script ties together the PDF service and generates the invoice with the described data. ```typescript async function main() { @@ -121,15 +122,15 @@ With the PDF service ready, you can proceed to generate documents. The following main().then(() => console.log('Invoice generation process completed.')); ``` - This script initiates the PDF service and generates the invoice PDF with the provided information. + This example initiates the PDF service and utilizes it to generate a PDF invoice with specified parameters. ### Advanced Document Features -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. +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 -1. **Custom Styling**: Customize the appearance of elements within your documents, such as headers, footers, and more. +1. **Custom Styling**: Alter the visual styles of various elements within your documents, like headers, footers, and more through CSS or inline styles. ```typescript import { DeDocumentViewer } from '@design.estate/dees-element'; @@ -139,31 +140,33 @@ The package is designed to create not only invoices but a wide range of document document.body.appendChild(customStyledViewer); ``` - Customize via CSS or dynamically through TypeScript where necessary. + Adjust styles either with standard CSS or via dynamic TypeScript changes. -2. **Interactive Document Elements**: Incorporate UI components like buttons, input fields, or visualizations tailored for your document needs. +2. **Interactive Document Elements**: Integrate interactive UI components, like buttons or input fields, fitting seamlessly into your documents. -3. **Multi-page Document Generation**: Handle overflow of content and automatic page generation while maintaining headers and footers. +3. **Multi-page Document Generation**: Handle content overflow elegantly through automatic page creation, keeping headers and footers intact. ```typescript pdfService.adjustDePageScaling(); ``` - Toggle between print and digital formats and handle scaling. + Adapt between print and digital formats, managing scaling effectively. -4. **Embedding Images and Logos**: Add company logos, graphics, or auxiliary content to enhance document presentation. +4. **Embedding Images and Logos**: Enhance your document's appearance with company logos, graphics, and other auxiliary content. ### Additional Capabilities -Beyond these examples, delve deeper into advanced functionalities such as: +Beyond basic functionality, this package offers a range of advanced features: -- **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. +- **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 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. +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. +``` + ## License and Legal Information diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 78d15ee..8ba00ed 100644 --- a/ts/00_commitinfo_data.ts +++ b/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.2.0', + description: 'A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.' } diff --git a/ts/interfaces/document.ts b/ts/interfaces/document.ts index 9165021..e84d180 100644 --- a/ts/interfaces/document.ts +++ b/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; } \ No newline at end of file diff --git a/ts_web/elements/shared/demoletter.ts b/ts/shared/demoletter.ts similarity index 95% rename from ts_web/elements/shared/demoletter.ts rename to ts/shared/demoletter.ts index 8023db0..2869224 100644 --- a/ts_web/elements/shared/demoletter.ts +++ b/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', -} \ No newline at end of file +} + +export const demoDocumentSettings: interfaces.IDocumentSettings = { + enableTopDraftText: true, + enableDefaultHeader: true, + enableDefaultFooter: true, + languageCode: 'DE', +}; \ No newline at end of file diff --git a/ts_web/elements/shared/index.ts b/ts/shared/index.ts similarity index 85% rename from ts_web/elements/shared/index.ts rename to ts/shared/index.ts index c8d0c38..edf58c2 100644 --- a/ts_web/elements/shared/index.ts +++ b/ts/shared/index.ts @@ -6,4 +6,4 @@ export const leftMargin = 90; import * as translation from './translation.js'; export { translation }; -export * from './demoletter.js'; \ No newline at end of file +export * from './demoletter.js'; diff --git a/ts_web/elements/shared/translation.ts b/ts/shared/translation.ts similarity index 92% rename from ts_web/elements/shared/translation.ts rename to ts/shared/translation.ts index 3f52485..b2a80e9 100644 --- a/ts_web/elements/shared/translation.ts +++ b/ts/shared/translation.ts @@ -1,4 +1,4 @@ -import * as interfaces from '../../../ts/interfaces/index.js'; +import * as interfaces from '../interfaces/index.js'; type TTranslationImplementation = { [key in keyof interfaces.IDeDocumentTranslations]: string; diff --git a/ts_web/00_commitinfo_data.ts b/ts_web/00_commitinfo_data.ts index 78d15ee..8ba00ed 100644 --- a/ts_web/00_commitinfo_data.ts +++ b/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.2.0', + description: 'A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.' } diff --git a/ts_web/elements/contentinvoice.ts b/ts_web/elements/contentinvoice.ts index 6ad7354..b3dcf47 100644 --- a/ts_web/elements/contentinvoice.ts +++ b/ts_web/elements/contentinvoice.ts @@ -15,7 +15,7 @@ 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'; diff --git a/ts_web/elements/document.demo.ts b/ts_web/elements/document.demo.ts index d9e33ea..ada07f6 100644 --- a/ts_web/elements/document.demo.ts +++ b/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` diff --git a/ts_web/elements/document.ts b/ts_web/elements/document.ts index 6df9bf8..3b032b6 100644 --- a/ts_web/elements/document.ts +++ b/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 { diff --git a/ts_web/elements/index.ts b/ts_web/elements/index.ts index d377dda..46cb17b 100644 --- a/ts_web/elements/index.ts +++ b/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'; \ No newline at end of file +export * from '../../ts/shared/index.js'; \ No newline at end of file diff --git a/ts_web/elements/letterheader.ts b/ts_web/elements/letterheader.ts index 1ef96f9..a99cbee 100644 --- a/ts_web/elements/letterheader.ts +++ b/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 { diff --git a/ts_web/elements/page.ts b/ts_web/elements/page.ts index dd385ba..d8ef4ef 100644 --- a/ts_web/elements/page.ts +++ b/ts_web/elements/page.ts @@ -15,7 +15,7 @@ import * as interfaces from '../../ts/interfaces/index.js'; import { defaultDocumentSettings } from './document.js'; -import * as shared from './shared/index.js'; +import * as shared from '../../ts/shared/index.js'; declare global { interface HTMLElementTagNameMap { diff --git a/ts_web/elements/pagecontainer.ts b/ts_web/elements/pagecontainer.ts index d134dfe..e7fcec3 100644 --- a/ts_web/elements/pagecontainer.ts +++ b/ts_web/elements/pagecontainer.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'; declare global { interface HTMLElementTagNameMap { diff --git a/ts_web/elements/pagecontent.ts b/ts_web/elements/pagecontent.ts index 4669cbd..c60ba42 100644 --- a/ts_web/elements/pagecontent.ts +++ b/ts_web/elements/pagecontent.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 { diff --git a/ts_web/elements/pagefooter.ts b/ts_web/elements/pagefooter.ts index b041948..bfc4f31 100644 --- a/ts_web/elements/pagefooter.ts +++ b/ts_web/elements/pagefooter.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 { diff --git a/ts_web/elements/pageheader.ts b/ts_web/elements/pageheader.ts index 280ecfd..0adebf0 100644 --- a/ts_web/elements/pageheader.ts +++ b/ts_web/elements/pageheader.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 { diff --git a/ts_web/elements/viewer.demo.ts b/ts_web/elements/viewer.demo.ts index 2d8c0bc..8424b17 100644 --- a/ts_web/elements/viewer.demo.ts +++ b/ts_web/elements/viewer.demo.ts @@ -1,6 +1,6 @@ import { html } from '@design.estate/dees-element'; -import * as shared from './shared/index.js'; +import * as shared from '../../ts/shared/index.js'; export const demoFunc = () => html` - + `; \ No newline at end of file diff --git a/ts_web/elements/viewer.ts b/ts_web/elements/viewer.ts index 8b2fa5a..10eb5c5 100644 --- a/ts_web/elements/viewer.ts +++ b/ts_web/elements/viewer.ts @@ -1,7 +1,9 @@ import * as plugins from '../plugins.js'; +import * as interfaces from '../../ts/interfaces/index.js'; import { DeesElement, css, cssManager, customElement, html } from '@design.estate/dees-element'; import { demoFunc } from './viewer.demo.js'; +import { defaultDocumentSettings } from './document.js'; declare global { interface HTMLElementTagNameMap { @@ -17,6 +19,8 @@ export class DeDocumentViewer extends DeesElement { // INSTANCE public letterData: plugins.tsclass.business.ILetter = null; + public documentSettings: interfaces.IDocumentSettings = defaultDocumentSettings; + public static styles = [ cssManager.defaultStyles, css` @@ -67,7 +71,7 @@ export class DeDocumentViewer extends DeesElement {
${this.letterData - ? html` ` + ? html` ` : html``}