npm - @mlightcad/cad-simple-viewer - Versions diffs - 1.0.0 → 1.0.2 - Mend

@mlightcad/cad-simple-viewer 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (136) hide show

package/README.md +296 -2
package/dist/index.js +1348 -122
package/dist/index.umd.cjs +2 -2
package/lib/app/AcApContext.d.ts +45 -3
package/lib/app/AcApContext.d.ts.map +1 -1
package/lib/app/AcApContext.js +43 -3
package/lib/app/AcApContext.js.map +1 -1
package/lib/app/AcApDocCreator.d.ts +68 -2
package/lib/app/AcApDocCreator.d.ts.map +1 -1
package/lib/app/AcApDocCreator.js +67 -2
package/lib/app/AcApDocCreator.js.map +1 -1
package/lib/app/AcApDocManager.d.ts +227 -12
package/lib/app/AcApDocManager.d.ts.map +1 -1
package/lib/app/AcApDocManager.js +229 -17
package/lib/app/AcApDocManager.js.map +1 -1
package/lib/app/AcApDocument.d.ts +77 -3
package/lib/app/AcApDocument.d.ts.map +1 -1
package/lib/app/AcApDocument.js +75 -3
package/lib/app/AcApDocument.js.map +1 -1
package/lib/app/AcApFontLoader.d.ts +32 -0
package/lib/app/AcApFontLoader.d.ts.map +1 -1
package/lib/app/AcApFontLoader.js +30 -0
package/lib/app/AcApFontLoader.js.map +1 -1
package/lib/app/AcApSettingManager.d.ts +191 -3
package/lib/app/AcApSettingManager.d.ts.map +1 -1
package/lib/app/AcApSettingManager.js +161 -0
package/lib/app/AcApSettingManager.js.map +1 -1
package/lib/command/AcApConvertToSvgCmd.d.ts +26 -0
package/lib/command/AcApConvertToSvgCmd.d.ts.map +1 -1
package/lib/command/AcApConvertToSvgCmd.js +26 -0
package/lib/command/AcApConvertToSvgCmd.js.map +1 -1
package/lib/command/AcApOpenCmd.d.ts +31 -0
package/lib/command/AcApOpenCmd.d.ts.map +1 -1
package/lib/command/AcApOpenCmd.js +31 -0
package/lib/command/AcApOpenCmd.js.map +1 -1
package/lib/command/AcApPanCmd.d.ts +25 -0
package/lib/command/AcApPanCmd.d.ts.map +1 -1
package/lib/command/AcApPanCmd.js +25 -0
package/lib/command/AcApPanCmd.js.map +1 -1
package/lib/command/AcApQNewCmd.d.ts +26 -0
package/lib/command/AcApQNewCmd.d.ts.map +1 -1
package/lib/command/AcApQNewCmd.js +26 -0
package/lib/command/AcApQNewCmd.js.map +1 -1
package/lib/command/AcApSelectCmd.d.ts +26 -0
package/lib/command/AcApSelectCmd.d.ts.map +1 -1
package/lib/command/AcApSelectCmd.js +26 -0
package/lib/command/AcApSelectCmd.js.map +1 -1
package/lib/command/AcApSvgConvertor.d.ts +48 -0
package/lib/command/AcApSvgConvertor.d.ts.map +1 -1
package/lib/command/AcApSvgConvertor.js +48 -0
package/lib/command/AcApSvgConvertor.js.map +1 -1
package/lib/command/AcApZoomCmd.d.ts +29 -0
package/lib/command/AcApZoomCmd.d.ts.map +1 -1
package/lib/command/AcApZoomCmd.js +29 -0
package/lib/command/AcApZoomCmd.js.map +1 -1
package/lib/command/AcApZoomToBoxCmd.d.ts +57 -0
package/lib/command/AcApZoomToBoxCmd.d.ts.map +1 -1
package/lib/command/AcApZoomToBoxCmd.js +57 -0
package/lib/command/AcApZoomToBoxCmd.js.map +1 -1
package/lib/editor/command/AcEdCommand.d.ts +118 -9
package/lib/editor/command/AcEdCommand.d.ts.map +1 -1
package/lib/editor/command/AcEdCommand.js +113 -9
package/lib/editor/command/AcEdCommand.js.map +1 -1
package/lib/editor/command/AcEdCommandStack.d.ts +59 -5
package/lib/editor/command/AcEdCommandStack.d.ts.map +1 -1
package/lib/editor/command/AcEdCommandStack.js +48 -5
package/lib/editor/command/AcEdCommandStack.js.map +1 -1
package/lib/editor/global/eventBus.d.ts +76 -7
package/lib/editor/global/eventBus.d.ts.map +1 -1
package/lib/editor/global/eventBus.js +38 -0
package/lib/editor/global/eventBus.js.map +1 -1
package/lib/editor/input/AcEdBaseInput.d.ts +65 -1
package/lib/editor/input/AcEdBaseInput.d.ts.map +1 -1
package/lib/editor/input/AcEdBaseInput.js +62 -1
package/lib/editor/input/AcEdBaseInput.js.map +1 -1
package/lib/editor/input/AcEdBoxSelector.d.ts +81 -0
package/lib/editor/input/AcEdBoxSelector.d.ts.map +1 -1
package/lib/editor/input/AcEdBoxSelector.js +80 -0
package/lib/editor/input/AcEdBoxSelector.js.map +1 -1
package/lib/editor/input/AcEdCursorManager.d.ts +95 -8
package/lib/editor/input/AcEdCursorManager.d.ts.map +1 -1
package/lib/editor/input/AcEdCursorManager.js +95 -11
package/lib/editor/input/AcEdCursorManager.js.map +1 -1
package/lib/editor/input/AcEdInputPoint.d.ts +38 -1
package/lib/editor/input/AcEdInputPoint.d.ts.map +1 -1
package/lib/editor/input/AcEdInputPoint.js +38 -1
package/lib/editor/input/AcEdInputPoint.js.map +1 -1
package/lib/editor/input/AcEdJig.d.ts +166 -0
package/lib/editor/input/AcEdJig.d.ts.map +1 -1
package/lib/editor/input/AcEdJig.js +164 -0
package/lib/editor/input/AcEdJig.js.map +1 -1
package/lib/editor/input/AcEdJigLoop.d.ts +49 -0
package/lib/editor/input/AcEdJigLoop.d.ts.map +1 -1
package/lib/editor/input/AcEdJigLoop.js +48 -0
package/lib/editor/input/AcEdJigLoop.js.map +1 -1
package/lib/editor/input/AcEdSelectionSet.d.ts +122 -2
package/lib/editor/input/AcEdSelectionSet.d.ts.map +1 -1
package/lib/editor/input/AcEdSelectionSet.js +117 -1
package/lib/editor/input/AcEdSelectionSet.js.map +1 -1
package/lib/editor/input/AcEditor.d.ts +90 -6
package/lib/editor/input/AcEditor.d.ts.map +1 -1
package/lib/editor/input/AcEditor.js +86 -6
package/lib/editor/input/AcEditor.js.map +1 -1
package/lib/editor/view/AcEdBaseView.d.ts +163 -16
package/lib/editor/view/AcEdBaseView.d.ts.map +1 -1
package/lib/editor/view/AcEdBaseView.js +94 -5
package/lib/editor/view/AcEdBaseView.js.map +1 -1
package/lib/util/AcTrGeometryUtil.d.ts +65 -0
package/lib/util/AcTrGeometryUtil.d.ts.map +1 -1
package/lib/util/AcTrGeometryUtil.js +65 -0
package/lib/util/AcTrGeometryUtil.js.map +1 -1
package/lib/view/AcTrLayer.d.ts +40 -5
package/lib/view/AcTrLayer.d.ts.map +1 -1
package/lib/view/AcTrLayer.js +34 -5
package/lib/view/AcTrLayer.js.map +1 -1
package/lib/view/AcTrLayout.d.ts +122 -23
package/lib/view/AcTrLayout.d.ts.map +1 -1
package/lib/view/AcTrLayout.js +103 -23
package/lib/view/AcTrLayout.js.map +1 -1
package/lib/view/AcTrLayoutView.d.ts +74 -16
package/lib/view/AcTrLayoutView.d.ts.map +1 -1
package/lib/view/AcTrLayoutView.js +65 -16
package/lib/view/AcTrLayoutView.js.map +1 -1
package/lib/view/AcTrLayoutViewManager.d.ts +58 -12
package/lib/view/AcTrLayoutViewManager.d.ts.map +1 -1
package/lib/view/AcTrLayoutViewManager.js +56 -12
package/lib/view/AcTrLayoutViewManager.js.map +1 -1
package/lib/view/AcTrScene.d.ts +48 -4
package/lib/view/AcTrScene.d.ts.map +1 -1
package/lib/view/AcTrScene.js +44 -4
package/lib/view/AcTrScene.js.map +1 -1
package/lib/view/AcTrView2d.d.ts +71 -0
package/lib/view/AcTrView2d.d.ts.map +1 -1
package/lib/view/AcTrView2d.js +65 -0
package/lib/view/AcTrView2d.js.map +1 -1
package/package.json +8 -4

package/README.md CHANGED Viewed

@@ -11,6 +11,15 @@ This module doesn't depend on any UI framework and doesn't provide any UI except
 - Performance-focused settings and context management
 - Framework-agnostic design for maximum flexibility
+## When Should You Choose cad-simple-viewer?
+Use `cad-simple-viewer` if you need **core CAD logic only** (document management, command stack, rendering engine integration) without any UI framework dependencies. This package is ideal if:
+- You want to build your **own custom UI** or integrate CAD functionality into a non-Vue or non-web environment.
+- You require maximum flexibility and performance for handling large CAD files, and plan to connect the logic to your own rendering or UI layer.
+- You want a framework-agnostic solution that provides only the essential CAD operations and canvas rendering.
+**Recommended for:** Custom integrations, headless CAD processing, or advanced users building highly tailored CAD solutions.
 ## Directory Structure (partial)
 - `src/app/` – Document/context management, settings
@@ -19,8 +28,293 @@ This module doesn't depend on any UI framework and doesn't provide any UI except
 - `src/view/` – Layout and scene management
 - `src/util/` – Utilities
+## Installation
+```bash
+npm install @mlightcad/cad-simple-viewer
+```
 ## Usage
-Entry point: `src/app/index.ts`. Used by the main application to manage documents and commands.
+Please refer to sub-package `cad-simple-viewer-example` as one example.
+### Basic Usage
+Firstly, add the following dependencies into your package.json.
+- @mlightcad/cad-simple-viewer
+- @mlightcad/data-model
+- @mlightcad/libredwg-converter
+- @mlightcad/libredwg-web
+Secondly, add one canvas element in your html.
+```html
+<body>
+  <canvas id="canvas"></canvas>
+</body>
+```
+Thirdly, add the following code in the entry point of cad-simple-viewer integration page.
+```typescript
+import { AcApDocManager } from '@mlightcad/cad-simple-viewer'
+import { AcDbDatabaseConverterManager, AcDbFileType } from '@mlightcad/data-model'
+// Get canvas DOM element by its id
+const canvas = document.getElementById('canvas') as HTMLCanvasElement
+AcApDocManager.createInstance(canvas)
+// Although it is optional, it is better to call this method to load the default fonts.
+// The default fonts are used if fonts used in drawing are not found.
+await AcApDocManager.instance.loadDefaultFonts()
+// Read the file content
+const fileContent = await this.readFile(file)
+// Set database options
+const options: AcDbOpenDatabaseOptions = {
+  minimumChunkSize: 1000,
+  readOnly: true
+}
+// Open the document
+const success = await AcApDocManager.instance.openDocument(
+  file.name,
+  fileContent,
+  options
+)
+// Your application logic here...
+......
+```
+### Register DWG Converter to Display Drawings in DWG Format
+By default, cad-simple-viewer registers DXF converter only and can view DXF file only. If you want to view DWG file, you need to register DWG converter. The following example code shows how to register DWG converter.
+```typescript
+import {
+  AcDbDatabaseConverterManager,
+  AcDbFileType
+} from '@mlightcad/data-model'
+import { AcDbLibreDwgConverter } from '@mlightcad/libredwg-converter'
+const registerConverters = async () => {
+  try {
+    const isDev = import.meta.env.DEV
+    if (!isDev) {
+      // Production mode - use dynamic import with explicit chunk name
+      const instance = await import(
+        /* webpackChunkName: "libredwg-web" */ '@mlightcad/libredwg-web'
+      )
+      const converter = new AcDbLibreDwgConverter(await instance.createModule())
+      AcDbDatabaseConverterManager.instance.register(
+        AcDbFileType.DWG,
+        converter
+      )
+    }
+  } catch (error) {
+    console.error('Failed to load libredwg-web: ', error)
+  }
+}
+```
+However, the code above works in production mode only even if removing check on 'isDev'. So you still need to make additional changes in order to make it work in Vite dev mode.
+Firstly, update `vite.config.ts` to copy `libredwg-web.js` to folder `assets` using `vite-plugin-static-copy`. Do remember adding `vite-plugin-static-copy` as your package devDependencies.
+```typescript
+import { resolve } from 'path'
+import { defineConfig, type ConfigEnv } from 'vite'
+import { viteStaticCopy } from 'vite-plugin-static-copy'
+export default defineConfig(({ command }: ConfigEnv) => {
+  return {
+    server: {
+      port: 3000
+    },
+    build: {
+      target: 'es2020',
+      modulePreload: false,
+      rollupOptions: {
+        // Main entry point for the app
+        input: {
+          main: resolve(__dirname, 'index.html')
+        },
+        output: {
+          manualChunks: id => {
+            if (id.includes('@mlightcad/libredwg-web')) {
+              return 'libredwg-web'
+            }
+          }
+        }
+      }
+    },
+    plugins: [
+      command === 'serve' ? viteStaticCopy({
+        targets: [
+          {
+            src: './node_modules/@mlightcad/libredwg-web/dist/libredwg-web.js',
+            dest: 'assets'
+          }
+        ]
+      }) : undefined
+    ]
+  }
+})
+```
+Secondly, add the following code in your html page such as `index.html` to dynamically import `libredwg-web` and trigger one event `libredwg-ready` after loaded.
+```html
+<script type="module" defer>
+  if (import.meta.env.DEV) {
+    (async () => {
+      // Create a script element to load the module
+      const script = document.createElement("script");
+      script.type = "module";
+      script.src = "/assets/libredwg-web.js";
+      script.async = true;
+      script.onload = async () => {
+        // Import dynamically after script is loaded
+        const actualModule = await import(/* @vite-ignore */script.src);
+        const libredwg = await actualModule.createModule();
+        window.dispatchEvent(new CustomEvent("libredwg-ready", { detail: libredwg }));
+      };
+      document.body.appendChild(script);
+    })();
+  }
+</script>
+```
+Thirdly, listen event `libredwg-ready` to register DWG converter `AcDbLibreDwgConverter` after `libredwg-ready` loaded.
+```typescript
+// This is for development mode only. In production mode, the library is bundled
+window.addEventListener('libredwg-ready', event => {
+  // @ts-expect-error this is one custom event and you can get details in index.html
+  const instance = event.detail as LibreDwgEx
+  const converter = new AcDbLibreDwgConverter(instance)
+  AcDbDatabaseConverterManager.instance.register(AcDbFileType.DWG, converter)
+})
+```
+### Beyond a Viewer
+While `cad-simple-viewer` doesn't support saving drawings to DWG/DXF files, it provides comprehensive support for **modifying drawings in real-time**. You can add, edit, and delete entities within the drawing, and the viewer will automatically update to reflect these changes.
+When you modify entities, you're working directly with the underlying drawing database. The viewer automatically detects these changes and updates the display accordingly. This real-time synchronization ensures that:
+- All modifications are immediately visible
+- The command stack properly tracks changes for undo/redo operations. This will be implemented soon.
+This capability makes `cad-simple-viewer` suitable for applications that need to not only display CAD files but also allow users to interact with and modify the drawing content.
+**Important Note**: The usage patterns in `cad-simple-viewer` are **very similar to AutoCAD RealDWG**. If you're familiar with AutoCAD RealDWG development, you'll find the API structure and workflow nearly identical. The main difference is that we use the [**realdwg-web API**](https://mlight-lee.github.io/realdwg-web/) instead of the native RealDWG libraries.
+#### Example: Adding Entities
+The following code demonstrates how to add entities, following the same pattern you'd use in AutoCAD RealDWG:
+```typescript
+import { AcApDocManager } from '@mlightcad/cad-simple-viewer'
+import { AcDbLine, AcDbCircle, AcDbText, AcGePoint3d, AcGeVector3d } from '@mlightcad/data-model'
+// Get the current document (same as RealDWG)
+const doc = AcApDocManager.instance.activeDocument
+if (!doc) return
+// Get the model space (identical to RealDWG pattern)
+const modelSpace = doc.database.modelSpace
+// Add a line (same constructor and property setting as RealDWG)
+const startPoint = new AcGePoint3d(0, 0, 0)
+const endPoint = new AcGePoint3d(100, 100, 0)
+const line = new AcDbLine(startPoint, endPoint)
+line.layer = '0' // Set layer (same property name as RealDWG)
+line.color = 1 // Red color (same color index as RealDWG)
+modelSpace.appendEntity(line)
+// Add a circle (identical API to RealDWG)
+const centerPoint = new AcGePoint3d(50, 50, 0)
+const radius = 25
+const circle = new AcDbCircle(centerPoint, radius)
+circle.layer = '0'
+circle.color = 2 // Yellow color
+modelSpace.appendEntity(circle)
+// Add text (same constructor pattern as RealDWG)
+const textPoint = new AcGePoint3d(0, -50, 0)
+const text = new AcDbText(textPoint, 'Sample Text', 10) // position, text, height
+text.layer = '0'
+text.color = 3 // Green color
+modelSpace.appendEntity(text)
+```
+#### Example: Editing Entities
+TBD
+#### Example: Deleting Entities
+TBD
+#### Example: Working with Layers
+TBD
+## Available Exports
+### Core Classes
+- `AcApContext` - Main application context
+- `AcApDocManager` - Document management
+- `AcApDocument` - Individual document handling
+- `AcApSettingManager` - Settings management
+### Commands
+- `AcApOpenCmd` - Open file command
+- `AcApZoomCmd` - Zoom command
+- `AcApPanCmd` - Pan command
+- `AcApSelectCmd` - Selection command
+- `AcApConvertToSvgCmd` - SVG conversion command
+### Editor Components
+- `AcEditor` - Main editor class
+- `AcEdCommandStack` - Command stack management
+- `AcEdSelectionSet` - Selection handling
+- `AcEdInputPoint` - Input point management
+### View Components
+- `AcTrScene` - Scene management
+- `AcTrLayoutView` - Layout view handling
+- `AcTrView2d` - 2D view management
+## Development
+```bash
+# Install dependencies
+pnpm install
+# Start development server
+pnpm dev
+# Build the library
+pnpm build
+# Preview the build
+pnpm preview
+```
 ## Role in MLightCAD
-This package acts as the core logic layer, connecting the frontend UI with the rendering engines and managing all document-related operations.
+This package acts as the core logic layer, connecting the frontend UI with the rendering engines and managing all document-related operations.
+## License
+MIT