@linkiez/dxf-renew 7.0.0 → 7.2.0

package/CONTRIBUTING.md

@@ -36,18 +36,20 @@ Antes de reportar um bug, verifique se já existe uma issue aberta sobre o probl
 ### Pull Requests
 
 1. Fork o repositório
-2. Crie uma branch a partir de `develop`:
+2. Crie uma branch a partir de `main`:
+
    ```bash
-   git checkout develop
+   git checkout main
    git checkout -b feature/sua-feature
    ```
+
 3. Faça suas mudanças seguindo o [Padrão de Commits](#padrão-de-commits)
 4. Execute os testes: `yarn test`
 5. Execute o linter: `yarn lint`
 6. Execute a build: `yarn build`
 7. Commit suas mudanças (o commitlint validará automaticamente)
 8. Push para sua branch
-9. Abra um Pull Request para `develop`
+9. Abra um Pull Request para `main`
 
 ## Padrão de Commits
 
@@ -55,7 +57,7 @@ Este projeto utiliza [Conventional Commits](https://www.conventionalcommits.org/
 
 ### Formato
 
-```
+```text
 <type>(<scope>): <subject>
 
 [optional body]
@@ -81,7 +83,7 @@ Este projeto utiliza [Conventional Commits](https://www.conventionalcommits.org/
 
 To indicate a breaking change (generates MAJOR release):
 
-```
+```text
 feat: allow provided config object to extend other configs
 
 BREAKING CHANGE: `extends` key in config file is now used
@@ -90,7 +92,7 @@ to extend other config files
 
 Or use `!` after the type:
 
-```
+```text
 feat!: remove support for Node 6
 ```
 
@@ -139,7 +141,7 @@ This will open an interactive prompt to create the commit in the correct format.
 O projeto usa [semantic-release](https://semantic-release.gitbook.io/) para releases automáticos:
 
 1. Faça commits seguindo o padrão Conventional Commits
-2. Faça merge do PR para `main`, `develop` ou `beta`
+2. Faça merge do PR para `main`
 3. O GitHub Actions automaticamente:
    * Analisa os commits desde o último release
    * Determina o novo número de versão (MAJOR.MINOR.PATCH)
@@ -151,8 +153,6 @@ O projeto usa [semantic-release](https://semantic-release.gitbook.io/) para rele
 ### Branches
 
 * **main**: Releases estáveis de produção
-* **develop**: Pre-releases (versões beta)
-* **beta**: Pre-releases específicas para testes
 
 ### Versionamento
 
@@ -220,7 +220,7 @@ yarn semantic-release   # Executar semantic-release
 
 ### Estrutura do Projeto
 
-```
+```text
 dxf/
 ├── src/                # Código-fonte TypeScript
 │   ├── handlers/       # Parsers de entidades e tabelas
@@ -238,15 +238,17 @@ dxf/
 ### Workflow de Desenvolvimento
 
 1. **Crie uma issue** descrevendo o que você vai fazer
-2. **Crie uma branch** a partir de `develop`:
+2. **Crie uma branch** a partir de `main`:
+
    ```bash
-   git checkout develop
-   git pull origin develop
+   git checkout main
+   git pull origin main
    git checkout -b feat/minha-feature
    ```
+
 3. **Faça suas mudanças** com commits seguindo o padrão
 4. **Execute os testes** localmente
-5. **Push e crie um PR** para `develop`
+5. **Push e crie um PR** para `main`
 6. **Aguarde a revisão** e responda aos comentários
 7. **Após merge**, o release será feito automaticamente
 

package/README.md

@@ -1,8 +1,8 @@
+# DXF-Renewed
+
 [![Build Status](https://travis-ci.org/bjnortier/dxf.svg?branch=master)](https://travis-ci.org/bjnortier/dxf)
 [![semantic-release: conventionalcommits](https://img.shields.io/badge/semantic--release-conventionalcommits-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
 
-# DXF-Renewed
-
 > **⚠️ WARNING: This repository is currently under development and has not been fully tested in production. Use at your own risk.**
 
 DXF parser for node/browser.
@@ -11,6 +11,39 @@ Written in **TypeScript** with full type definitions included. Uses modern ES201
 
 > **Note:** This is a renewed and modernized fork of the original [dxf](https://github.com/skymakerolof/dxf) library, with complete TypeScript migration, enhanced performance, and additional features.
 
+## TL;DR
+
+- Parse: `parseString(dxfText)` → typed `ParsedDXF`
+- Expand blocks: `denormalise(parsed)` → flat `Entity[]` with transforms
+- Render/export:
+  - `toSVG(parsed)` → SVG string
+  - `toPolylines(parsed)` → numeric polyline arrays
+  - `toJson(parsed)` → JSON string
+
+## Features
+
+- TypeScript-first public API (strict typing)
+- Deterministic parsing + regression coverage via real DXF fixtures
+- INSERT/BLOCK expansion (denormalisation) with transform stacking
+- SVG rendering for common 2D geometry + annotation entities
+- Polyline output for custom renderers (Canvas/WebGL/etc.)
+- Framework-agnostic (no React/Webpack required)
+
+## Documentation
+
+- Project roadmap and progress: [ROADMAP.md](./ROADMAP.md)
+- Architecture overview: [ARCHITECTURE.md](./ARCHITECTURE.md)
+
+## Table of Contents
+
+- [Version History](#version-history)
+- [Supported Entities](#supported-entities)
+- [Getting started](#getting-started)
+- [API](#api)
+- [Running the Examples](#running-the-examples)
+- [Tests](#tests)
+- [Build System](#build-system)
+
 ## Version History
 
 **Version 2.0** - Complete rewrite from SAX-style parsing to handle nested references properly (inserts, blocks, etc.)
@@ -24,15 +57,15 @@ Written in **TypeScript** with full type definitions included. Uses modern ES201
 - 🎯 Full TypeScript codebase with strict type checking
 - ⚡ Built with esbuild (96% faster than Babel - 18ms vs 447ms)
 - 📦 Modular type system with 22+ separate type files
-- ✅ 100% test coverage maintained (85 tests passing)
+- ✅ Extensive unit tests and browser integration tests
 - 🎨 Enhanced SVG rendering with TEXT, MTEXT, and DIMENSION support
 - 📚 Comprehensive type definitions for all DXF entities
 
 ## Supported Entities
 
-All major geometric entities are **parsed and rendered to SVG**:
+Many common DXF entities are **parsed and rendered to SVG**. Some entities are parsed but currently skipped during SVG rendering.
 
-### Fully Supported
+### Rendered to SVG
 
 - ✅ **LINE** - Straight line segments
 - ✅ **CIRCLE** - Native SVG `<circle />` element
@@ -44,16 +77,23 @@ All major geometric entities are **parsed and rendered to SVG**:
 - ✅ **TEXT** - Single-line text with rotation
 - ✅ **MTEXT** - Multi-line text with formatting
 - ✅ **DIMENSION** - Linear, aligned, radial, diameter, and ordinate dimensions
-- ✅ **INSERT** - Block references with transformations
-- ✅ **POINT** - Point entities
 - ✅ **SOLID** - Solid-filled triangles and quadrilaterals
-- ✅ **3DFACE** - 3D face entities
+- ✅ **TRACE** - Rendered as a filled path outline
+- ✅ **RAY/XLINE** - Rendered as polylines
+- ✅ **WIPEOUT** - Rendered as outline fallback
+- ✅ **LEADER** - Rendered as an SVG path (basic)
+- ✅ **TOLERANCE** - Rendered with SVG text fallback
+- ✅ **SHAPE** - Rendered with SVG text fallback
+
+> **INSERT note:** INSERT is supported via denormalisation. The library expands INSERT entities into their referenced BLOCK contents and then renders the resulting entities with transforms applied.
 
 ### Parsed (Not Rendered)
 
-- ⚠️ **HATCH** - Parsed but not rendered to SVG
-- ⚠️ **STYLE** - Text styles parsed (colors supported, fonts not applied)
+- ⚠️ **POINT** - Parsed but currently not rendered to SVG
+- ⚠️ **3DFACE** - Parsed but currently not rendered to SVG
+- ⚠️ **HATCH** - Parsed but currently not rendered to SVG
 - ⚠️ **ATTDEF/ATTRIB** - Block attributes parsed
+- ⚠️ **Text styles (STYLE table)** - Parsed (colors supported; fonts are not applied to SVG)
 
 ## Getting started
 
@@ -75,6 +115,9 @@ console.log('svg:', helper.toSVG())
 
 // Create polylines (e.g. to render in WebGL)
 console.log('polylines:', helper.toPolylines())
+
+// Create a JSON representation (1-to-1 with the parsed model)
+console.log('json:', helper.toJson({ pretty: true }))
 ```
 
 JavaScript example:
@@ -95,8 +138,28 @@ console.log('svg:', helper.toSVG())
 
 // Create polylines (e.g. to render in WebGL)
 console.log('polylines:', helper.toPolylines())
+
+// Create a JSON representation (1-to-1 with the parsed model)
+console.log('json:', helper.toJson({ pretty: true }))
 ```
 
+## API
+
+The public API is exported from `src/index.ts`.
+
+- `parseString(dxfText: string): ParsedDXF`
+  - Parse DXF text into a typed model.
+- `denormalise(parsed: ParsedDXF): Entity[]`
+  - Expand `INSERT` entities into their referenced `BLOCK` contents.
+- `toSVG(parsed: ParsedDXF, options?): string`
+  - Render the drawing to an SVG string.
+- `toPolylines(parsed: ParsedDXF, options?): any[]`
+  - Convert supported entities to polyline arrays.
+- `toJson(parsed: ParsedDXF, options?): string`
+  - Serialize the parsed model as JSON.
+- `Helper`
+  - Convenience wrapper that exposes `parsed`, `denormalised`, plus `toSVG()`, `toPolylines()`, and `toJson()`.
+
 ## Running the Examples
 
 There are examples in the `examples/` directory.
@@ -148,6 +211,34 @@ Here's an example you will find in the functional test output:
 
 ![svg example image](https://cloud.githubusercontent.com/assets/57994/17583566/e00f5d78-5fb1-11e6-9030-55686f980e6f.png)
 
+### DIMENSION auto-scaling
+
+DIMENSION rendering supports viewport-based auto-scaling so that arrows and text remain readable across different coordinate scales.
+
+```ts
+import { Helper } from '@linkiez/dxf-renew'
+
+const helper = new Helper(dxfString)
+
+const svg = helper.toSVG({
+  dimension: {
+    autoScale: true,
+    // Reference used when percentages are not provided.
+    autoScaleViewportReference: 40,
+    // Optional per-element overrides as a percentage (0..100)
+    // of min(viewBoxWidth, viewBoxHeight).
+    autoScaleViewportPercentages: {
+      arrowSize: 1.5,
+      textHeight: 1
+    }
+  }
+})
+```
+
+When `autoScaleViewportPercentages` is provided (and `autoScale` is enabled), the final size for each configured element is computed as:
+
+`size = min(viewBoxWidth, viewBoxHeight) * (percent / 100)`
+
 ## Interpolation
 
 The library supports outputting DXFs as interpolated polylines for custom rendering (e.g. WebGL) or other applications:
@@ -189,17 +280,25 @@ Running the unit tests:
 yarn test
 ```
 
+Running the browser integration tests (Playwright):
+
+```bash
+yarn test:integration:browser
+```
+
+These tests render fixtures in a real browser and write deterministic PNG screenshots under `test/rendered/` (overwritten on each run).
+
 Running the functional tests in a browser:
 
 ```bash
 yarn test:functional
 ```
 
-Please open `toSVG.html` when the file listing loads in the browser (or open `http://localhost:8030/toSVG.html#/`).
+This starts a Vite dev server and opens `http://localhost:8030/toSVG.html`.
 
 ## Development Guidelines
 
-- Code patterns and best practices: `docs/CODE_PATTERNS.md`
+Project documentation index: `ROADMAP.md` (see “Documentation (Consolidated)”).
 
 ## TypeScript Support
 
@@ -251,8 +350,6 @@ This project uses [semantic-release](https://semantic-release.gitbook.io/) for a
 **Releases are automatically created** when commits following [Conventional Commits](https://www.conventionalcommits.org/en/) are pushed to:
 
 - `main` - Stable production releases (`1.0.0`, `1.1.0`, `2.0.0`)
-- `develop` - Pre-releases for testing (`1.1.0-dev.1`, `1.1.0-dev.2`)
-- `beta` - Beta pre-releases (`1.1.0-beta.1`, `1.1.0-beta.2`)
 
 ### Commit Format
 
@@ -276,9 +373,9 @@ To contribute:
 1. Fork the repository
 2. Make commits using `yarn commit` (interactive) or following Conventional Commits
 3. Push to your fork
-4. Open a Pull Request to `develop`
+4. Open a Pull Request to `main`
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines and [docs/SEMANTIC_RELEASE.md](./docs/SEMANTIC_RELEASE.md) for release documentation.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
 
 ## Contributors