@linkiez/dxf-renew 7.1.0 → 7.2.0

package/.eslintrc.json

@@ -5,9 +5,7 @@
     "node": true
   },
   "extends": [
-    "plugin:react/recommended",
     "standard",
-    "standard-react",
     "prettier"
   ],
   "globals": {
@@ -21,25 +19,12 @@
     "afterEach": "readonly"
   },
   "parserOptions": {
-    "babelOptions": {
-      "presets": ["@babel/preset-react"]
-    },
-    "ecmaFeatures": {
-      "jsx": true
-    },
-    "ecmaVersion": 2018,
+    "ecmaVersion": 2020,
     "sourceType": "module"
   },
-  "plugins": ["react"],
-  "parser": "@babel/eslint-parser",
   "rules": {
     "no-lone-blocks": "off"
   },
-  "settings": {
-    "react": {
-      "version": "detect"
-    }
-  },
   "overrides": [
     {
       "files": ["*.ts", "*.tsx"],

package/ARCHITECTURE.md

@@ -0,0 +1,163 @@
+# Architecture
+
+This document describes the high-level architecture of DXF-Renewed, including the parsing pipeline, denormalisation (INSERT expansion), and rendering outputs.
+
+## Goals
+
+- Parse DXF text into a typed model deterministically.
+- Expand INSERT/BLOCK references into a flattened entity list with transforms.
+- Provide multiple output formats:
+  - SVG string (`toSVG`)
+  - numeric polylines (`toPolylines`)
+  - JSON string (`toJson`)
+- Prefer "parse what we can, warn for what we can’t" over throwing, when feasible.
+
+## Project Layout
+
+- `src/` — TypeScript source
+  - `src/index.ts` — public API exports
+  - `src/Helper.ts` — convenience wrapper around parsing + denormalisation + outputs
+  - `src/parseString.ts` — main DXF text parser (routes sections)
+  - `src/handlers/` — section handlers and entity handlers
+  - `src/types/` — public type definitions
+  - `src/denormalise.ts` — INSERT expansion + transform stacking
+  - `src/toSVG.ts` — SVG renderer
+  - `src/toPolylines.ts` + `src/entityToPolyline.ts` — polyline renderer
+  - `src/toJson.ts` — JSON serializer for the parsed model
+  - `src/util/` — shared helpers (logger, XML escaping, etc.)
+- `test/` — tests and fixtures
+  - `test/unit/` — unit tests (Mocha + TSX)
+  - `test/integration-browser/` — Playwright browser rendering tests
+  - `test/resources/` — DXF fixtures
+- `docs/` — documentation and references
+- `lib/` and `dist/` — build outputs
+
+## Data Flow (End-to-End)
+
+Typical usage:
+
+1. `parseString(dxfText)` produces a `ParsedDXF` object.
+2. `denormalise(parsed)` expands block inserts and returns a flattened `Entity[]`.
+3. Render or export:
+   - `toSVG(parsed)` renders the denormalised entities into an SVG string.
+   - `toPolylines(parsed)` converts supported entities into numeric polyline arrays.
+   - `toJson(parsed)` serializes the `ParsedDXF` model into a JSON string.
+
+The `Helper` class wraps this pipeline:
+
+- Constructs from DXF text
+- Exposes `parsed` and `denormalised`
+- Exposes `toSVG()`, `toPolylines()`, and `toJson()`
+
+### Pipeline Diagram
+
+```mermaid
+flowchart LR
+  A[DXF text] --> B[parseString]
+  B --> C[ParsedDXF]
+
+  subgraph SectionHandlers[Section handlers]
+    H[HEADER]
+    T[TABLES]
+    BL[BLOCKS]
+    E[ENTITIES]
+    O[OBJECTS]
+  end
+
+  B -. routes sections .-> SectionHandlers
+  SectionHandlers -. populate .-> C
+
+  C --> D[denormalise]
+  D --> E2["Entity[] (flattened + transforms)"]
+
+  E2 --> S[toSVG]
+  E2 --> P[toPolylines]
+  C --> J[toJson]
+
+  S --> S2[SVG string]
+  P --> P2[Polyline arrays]
+  J --> J2[JSON string]
+
+  A --> HLP[Helper]
+  HLP --> C
+  HLP --> E2
+  HLP --> S2
+  HLP --> P2
+  HLP --> J2
+```
+
+## Parsing
+
+### Tuple Stream
+
+The parser converts the DXF text into a tuple stream of `[groupCode, value]` and routes it by section.
+
+### Section Routing
+
+`src/parseString.ts` is responsible for splitting tuples into sections and delegating to section handlers:
+
+- `src/handlers/header.ts`
+- `src/handlers/tables.ts`
+- `src/handlers/blocks.ts`
+- `src/handlers/entities.ts`
+- `src/handlers/objects.ts`
+
+### Entity Handlers
+
+Entity handlers live in `src/handlers/entity/*.ts` and follow a consistent pattern:
+
+- Export `TYPE` (DXF entity type string).
+- Export a `process(tuples)` function that reduces group codes into a typed entity.
+- Delegate common fields (layer, color, handle, etc.) to shared parsing helpers.
+
+Multi-entity sequences (e.g. `POLYLINE` → `VERTEX`… → `SEQEND`) are handled by sequencing logic in `src/handlers/entities.ts`.
+
+## Denormalisation (INSERT Expansion)
+
+`src/denormalise.ts` expands `INSERT` entities into the referenced BLOCK contents.
+
+Responsibilities:
+
+- Resolve INSERT → BLOCK.
+- Apply transform stacks to expanded entities.
+- Expand rectangular arrays when present.
+
+The output is a flat list of entities with an optional `transforms` stack used by renderers.
+
+## Rendering
+
+### SVG (`toSVG`)
+
+`src/toSVG.ts` renders the denormalised entities.
+
+- Uses native SVG primitives when feasible (`<circle>`, `<ellipse>`, path arcs).
+- Uses polyline approximations for entities that do not have a native SVG primitive or where approximation is acceptable.
+- Unsupported entity types are skipped with a warning.
+
+### Polylines (`toPolylines`)
+
+`src/entityToPolyline.ts` is the main conversion point for entities → polylines.
+
+- Designed to be pure: same input entity should result in the same polyline output.
+- Options (e.g., interpolation density) should be expressed via `ToPolylinesOptions`.
+
+### JSON (`toJson`)
+
+`src/toJson.ts` provides a stable way to serialize the parsed model.
+
+- Intended to represent the parsed model 1-to-1.
+- Supports pretty-printing via options.
+
+## Logging & Error Handling
+
+- Logging goes through `src/util/logger.ts`.
+- Prefer warnings over exceptions for unsupported features.
+- Parsing should remain resilient: bad/unknown codes should not crash the entire parse when possible.
+
+## Build & Test
+
+- Build: TypeScript + esbuild bundling.
+- Unit tests: Mocha executed with `tsx`.
+- Browser integration tests: Playwright (renders fixtures and captures screenshots under `test/rendered/`).
+- Functional manual viewer: Vite dev server under `test/functional/`.
+

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## 7.2.0 (2026-01-01)
+
+* Merge pull request #2 from linkiez/feature/2026.01.01 ([c01512f](https://github.com/linkiez/DXF-Renewed/commit/c01512f)), closes [#2](https://github.com/linkiez/DXF-Renewed/issues/2)
+* docs: add architecture diagram ([7f61ef2](https://github.com/linkiez/DXF-Renewed/commit/7f61ef2))
+* docs: clarify supported entities ([8cd47dc](https://github.com/linkiez/DXF-Renewed/commit/8cd47dc))
+* docs: consolidate documentation into PLAN.md ([204abf9](https://github.com/linkiez/DXF-Renewed/commit/204abf9))
+* docs: fix mermaid diagram parsing ([0cedf8d](https://github.com/linkiez/DXF-Renewed/commit/0cedf8d))
+* docs: improve README structure ([3c6659d](https://github.com/linkiez/DXF-Renewed/commit/3c6659d))
+* docs: rename plan to roadmap ([23b060e](https://github.com/linkiez/DXF-Renewed/commit/23b060e))
+* docs: update README progress ([64566b7](https://github.com/linkiez/DXF-Renewed/commit/64566b7))
+* feat: add toJson processor ([94e112c](https://github.com/linkiez/DXF-Renewed/commit/94e112c))
+* feat(entities): add handlers for additional 2D entities ([221ef8b](https://github.com/linkiez/DXF-Renewed/commit/221ef8b))
+* feat(parser): add FIELD/DIMASSOC objects and extra table types ([ef89ed7](https://github.com/linkiez/DXF-Renewed/commit/ef89ed7))
+* feat(render): support LEADER/RAY/XLINE/TRACE/SHAPE/WIPEOUT ([05a7c82](https://github.com/linkiez/DXF-Renewed/commit/05a7c82))
+* chore(tooling): remove babel/react/webpack and migrate functional tests to vite ([dd92031](https://github.com/linkiez/DXF-Renewed/commit/dd92031))
+
 ## 7.1.0 (2026-01-01)
 
 * Merge pull request #1 from linkiez/feat/seqend-sequencing ([068c6e1](https://github.com/linkiez/DXF-Renewed/commit/068c6e1)), closes [#1](https://github.com/linkiez/DXF-Renewed/issues/1)

package/README.md

@@ -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.)
@@ -30,9 +63,9 @@ Written in **TypeScript** with full type definitions included. Uses modern ES201
 
 ## 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.
@@ -231,11 +294,11 @@ Running the functional tests in a browser:
 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
 
-Project documentation index: `docs/README.md`
+Project documentation index: `ROADMAP.md` (see “Documentation (Consolidated)”).
 
 ## TypeScript Support
 
@@ -288,7 +351,6 @@ This project uses [semantic-release](https://semantic-release.gitbook.io/) for a
 
 - `main` - Stable production releases (`1.0.0`, `1.1.0`, `2.0.0`)
 
-
 ### Commit Format
 
 ```bash