@bnsights/bbsf-utilities-doc

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

📦 Installation

npm install @bnsights/bbsf-utilities-doc

🚀 Quick Start

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

export class MyComponent {
  constructor(private wordService: WordDocumentService) {}

  async generateDocument() {
    const model = new WordDocumentModel();
    model.body = '<h1>Hello World</h1><p>Generated from HTML!</p>';
    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

Supported HTML Elements

• ✅ Headings (h1-h6)
• ✅ Paragraphs
• ✅ Tables (with styling)
• ✅ Lists (ordered & unordered)
• ✅ Images (base64 or URL)
• ✅ Text formatting (bold, italic, underline)
• ✅ Colors & fonts
• ✅ Hyperlinks

Document Options

• Page size (custom width/height)
• Orientation (portrait/landscape)
• Margins (top, bottom, left, right)
• Headers & footers
• Page numbering
• Table row break prevention

🎨 API Reference

WordDocumentService

generateWordByteFile(model: WordDocumentModel): Promise<ArrayBuffer>

Generates a .docx file from the provided model.

Returns: Promise<ArrayBuffer> - The document as a byte array

WordDocumentModel

| 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 |

DocumentOptionsModel

| 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

Basic Document

const model = new WordDocumentModel();
model.body = '<h1>Title</h1><p>Content here</p>';
const buffer = await this.wordService.generateWordByteFile(model);

Table Example

model.body = `
  <table border="1">
    <thead>
      <tr>
        <th>Name</th>
        <th>Value</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Item 1</td>
        <td>100</td>
      </tr>
      <tr>
        <td>Item 2</td>
        <td>200</td>
      </tr>
    </tbody>
  </table>
`;

Styled Content

model.body = `
  <h1 style="color: blue;">Blue Heading</h1>
  <p style="font-size: 16px; font-family: Arial;">
    This is <strong>bold</strong> and this is <em>italic</em>.
  </p>
  <p style="text-align: center;">Centered text</p>
`;

Image Embedding

model.body = `
  <img src="data:image/png;base64,iVBORw0KG..." alt="Logo" />
  <img src="https://example.com/image.jpg" alt="Online Image" />
`;

Custom Page Size (A4)

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;

Landscape Document

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:

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

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

🐛 Troubleshooting

Issue: "Module not found"

npm install @bnsights/bbsf-utilities-doc

Issue: Images not showing

• Ensure images are base64 encoded or accessible URLs
• Check image size isn't too large (> 10MB)

Issue: Table formatting issues

• Use inline styles for table cells
• Set explicit widths when needed
• Avoid complex nested tables

Issue: Build errors

# 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