@bnsights/bbsf-utilities-doc

Document generation utilities for BBSF applications. Generate Word (.docx) documents from HTML content.

📦 Installation

bash

npm install @bnsights/bbsf-utilities-doc





🚀 Quick Start

typescript

import { WordDocumentService, WordDocumentModel } from '@bnsights/bbsf-utilities-doc';



export class MyComponent {

  constructor(private wordService: WordDocumentService) {}



  async generateDocument() {

    const model = new WordDocumentModel();

    model.body = 'Hello World
Generated from HTML!';

    model.header = 'My Document Header';

    model.footer = 'Page Footer';

    

    model.options.pageWidth = 8.5;

    model.options.pageHeight = 11;

    model.options.isLandscape = false;

    model.options.showPaging = true;

    model.options.top = 0.5;

    model.options.bottom = 0.5;

    model.options.left = 0.75;

    model.options.right = 0.75;



    const buffer = await this.wordService.generateWordByteFile(model);

    

    // Save as file

    const blob = new Blob([buffer], { 

      type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' 

    });

    const url = window.URL.createObjectURL(blob);

    const a = document.createElement('a');

    a.href = url;

    a.download = 'document.docx';

    a.click();

  }

}





📚 Features



$3

- ✅ Headings (h1-h6)

- ✅ Paragraphs

- ✅ Tables (with styling)

- ✅ Lists (ordered & unordered)

- ✅ Images (base64 or URL)

- ✅ Text formatting (bold, italic, underline)

- ✅ Colors & fonts

- ✅ Hyperlinks



$3

- Page size (custom width/height)

- Orientation (portrait/landscape)

- Margins (top, bottom, left, right)

- Headers & footers

- Page numbering

- Table row break prevention



🎨 API Reference



$3



####

generateWordByteFile(model: WordDocumentModel): Promise





Generates a .docx file from the provided model.



Returns:

Promise

 - The document as a byte array



$3



| Property | Type | Description |

|----------|------|-------------|

|

body

 | string | HTML content for document body |

|

header

 | string | HTML content for header |

|

footer

 | string | HTML content for footer |

|

options

 | DocumentOptionsModel | Page and formatting options |



$3



| Property | Type | Default | Description |

|----------|------|---------|-------------|

|

pageWidth

 | number | 8.5 | Page width in inches |

|

pageHeight

 | number | 11 | Page height in inches |

|

top

 | number | 1 | Top margin in inches |

|

bottom

 | number | 1 | Bottom margin in inches |

|

left

 | number | 1 | Left margin in inches |

|

right

 | number | 1 | Right margin in inches |

|

isLandscape

 | boolean | false | Landscape orientation |

|

showPaging

 | boolean | true | Show page numbers |



📖 Examples



$3

typescript

const model = new WordDocumentModel();

model.body = 'Title
Content here';

const buffer = await this.wordService.generateWordByteFile(model);

$3

typescript

model.body =

Name	Value
Item 1	100
Item 2	200

$3

typescript

model.body =

Blue Heading

This is bold and this is italic.

Centered text

$3

typescript

model.body =

$3

typescript

model.options.pageWidth = 8.27;  // 210mm = 8.27 inches

model.options.pageHeight = 11.69; // 297mm = 11.69 inches

model.options.top = 0.79;         // 20mm = 0.79 inches

model.options.bottom = 0.79;

model.options.left = 0.79;

model.options.right = 0.79;

$3

typescript

model.options.isLandscape = true;

model.options.pageWidth = 11;

model.options.pageHeight = 8.5;





🔧 Dependencies



This package includes all necessary dependencies:

-

xmlbuilder2

 - XML generation

-

jszip

 - ZIP file creation

-

html-to-vdom

 - HTML parsing

-

virtual-dom

 - Virtual DOM handling

-

image-size

 - Image dimension detection

-

image-to-base64

 - Image encoding

-

color-name

 - Color conversion

-

escape-html

 - HTML escaping

-

mime-types

 - MIME type detection



📦 Bundle Size



- Package size: ~8 MB (uncompressed)

- Minified: ~2 MB

- Gzipped: ~500 KB



Note: This is why document generation is now a separate package - apps that don't need it won't bundle these dependencies.



🔄 Migration from bbsf-utilities



If you were using

WordDocumentService from @bnsights/bbsf-utilities

, see MIGRATION_GUIDE.md for easy migration steps.



TL;DR:

typescript

// Before

import { WordDocumentService } from '@bnsights/bbsf-utilities';



// After

import { WordDocumentService } from '@bnsights/bbsf-utilities-doc';





🐛 Troubleshooting



$3

bash

npm install @bnsights/bbsf-utilities-doc





$3

- Ensure images are base64 encoded or accessible URLs

- Check image size isn't too large (> 10MB)



$3

- Use inline styles for table cells

- Set explicit widths when needed

- Avoid complex nested tables



$3

bash

Clear cache

rm -rf node_modules/.cache

npm install

ng build





📝 Future Features



- [ ] PDF generation

- [ ] Excel export (.xlsx)

- [ ] Markdown conversion

- [ ] Document templates

- [ ] Mail merge support

- [ ] Digital signatures



🤝 Contributing



This package is part of the BBSF 3 framework. For contributions or issues, please refer to the main BBSF repository.



📄 License



Part of BBSF 3 - See main repository for license information.



🔗 Related Packages



-

@bnsights/bbsf-utilities

 - Core utilities

-

@bnsights/bbsf-admin-portal

 - Admin portal components

-

@bnsights/bbsf-controls` - UI controls

---

Version: 1.0.0
Last Updated: October 27, 2025
Maintainers: BBSF Team