docs: update dev docs about esm, building and testing

Author: HajagosNorbert

turbo.json

@@ -5,7 +5,7 @@
   "envMode": "loose",
   "tasks": {
     "build:bin": {
-      "outputs": ["dist/scripts/**"]
+      "outputs": ["dist/bin/**"]
     },
     "build:xmlui": {
       "outputs": ["dist/lib/**"]

xmlui/conventions/testing-conventions.md

@@ -70,7 +70,7 @@ There's also documentation in the `.md` files, next to the component's file.
 **ALWAYS read the component's `.tsx` file before creating tests.** The component files contain essential metadata that documents:
 
 - **Properties**: All available props with their types and descriptions
-- **Events**: Available event handlers and their parameters  
+- **Events**: Available event handlers and their parameters
 - **Theme Variables**: Default values and names for CSS custom properties used in theme testing
 
 Use the documented theme variable names when creating theme tests instead of guessing:
@@ -95,7 +95,8 @@ test("applies theme variables", async ({ initTestBed, page }) => {
 - **Provides context** for proper testing scenarios
 
 Example documentation locations:
-- `Button.tsx` - Contains metadata 
+
+- `Button.tsx` - Contains metadata
 - `Button.md` - Contains examples and detailed usage
 - `Button.spec.ts` - Your test file
 
@@ -400,10 +401,10 @@ test("enqueueItem returns valid ID", async ({ initTestBed, createButtonDriver })
       <Button onClick="testState = { id: testQueue.enqueueItem('test'), hasId: true }" />
     </Fragment>
   `);
-  
+
   const buttonDriver = await createButtonDriver("button");
   await buttonDriver.component.click();
-  
+
   const result = await testStateDriver.testState();
   expect(result.id).toBeTruthy();
   expect(result.hasId).toBe(true);
@@ -489,6 +490,14 @@ Use web-first assertions, like `await expect(checkboxLocator).not.toBeChecked()`
 
 ## Best Practices
 
+### Avoid Frontend Code in E2E Tests
+
+It is crucial to avoid importing frontend code into E2E tests, especially if it transitively imports stylesheets. This can lead to unexpected issues with the test runner and slow down test execution.
+
+For example, importing `defaultProps` from a component file like `ButtonNative.tsx` into a test file like `Button.spec.ts` is an anti-pattern. The component file likely imports SCSS or CSS files, which should not be part of the test environment.
+
+Instead, if you need to share data between your component and your tests, define it in a separate file that can be imported safely by both.
+
 ### Skipping tests
 
 #### Skipping For coverage
@@ -545,7 +554,7 @@ Components that support layout properties (like `labelPosition`, `direction`, po
 
 #### Best Practices for Layout Testing
 
-- **Import getBounds**: Import from `"../../testing/component-test-helpers"` 
+- **Import getBounds**: Import from `"../../testing/component-test-helpers"`
 - **Use descriptive coordinates**: Destructure specific properties like `{ left, right, top, bottom }`
 - **Test both directions**: Include RTL tests when direction affects layout
 - **Verify invalid values**: Test graceful handling of invalid layout properties
@@ -555,7 +564,10 @@ Components that support layout properties (like `labelPosition`, `direction`, po
 Use `getBounds()` to get element coordinates and verify relative positioning:
 
 ```typescript
-test("ComponentName appears at the correct side of ComponentName2", async ({ initTestBed, page }) => {
+test("ComponentName appears at the correct side of ComponentName2", async ({
+  initTestBed,
+  page,
+}) => {
   await initTestBed(`
     <Fragment>
       <ComponentName testId="comp1" />
@@ -614,9 +626,7 @@ test("all adornments appear in the right place", async ({ initTestBed, page }) =
   const { left: startIconLeft, right: startIconRight } = await getBounds(
     page.getByRole("img").first(),
   );
-  const { left: endIconLeft, right: endIconRight } = await getBounds(
-    page.getByRole("img").last(),
-  );
+  const { left: endIconLeft, right: endIconRight } = await getBounds(page.getByRole("img").last());
 
   // Check order of adornments relative to their container component bounds
   expect(startTextRight - compLeft).toBeLessThanOrEqual(compRight - startTextLeft);

xmlui/dev-docs/build-system.md

@@ -428,25 +428,24 @@ src/
 ```
 dist/
   ├── lib/                        # Library build
-  │   ├── xmlui.mjs
+  │   ├── xmlui.js
   │   ├── xmlui.d.ts
-  │   ├── xmlui-parser.mjs
-  │   ├── language-server.mjs
+  │   ├── xmlui-parser.js
+  │   ├── language-server.js
   │   └── scss/                   # SCSS source files
   ├── standalone/                 # Standalone build
   │   └── xmlui-standalone.umd.js
   ├── metadata/                   # Metadata build
   │   └── xmlui-metadata.js
-  └── scripts/
-      └── bin/
-          └── vite-xmlui-plugin.js
+  └── bin/
+      └── index.js
 ```
 
 ### Bin Scripts
 
 ```
 bin/
-  ├── bootstrap.js                # CLI entry (ts-node setup)
+  ├── bootstrap.js                # CLI entry for development (uses tsx)
   ├── index.ts                    # Command router
   ├── build.ts                    # Build implementation
   ├── build-lib.ts                # Library build
@@ -726,7 +725,7 @@ This table summarizes when to run builds across different contexts:
 | **xmlui/**     | Building standalone       | `npm run build:xmlui-standalone` | `vite build --mode standalone`                  | For CDN/buildless                              | Creates self-contained UMD bundle for `<script>` tag usage; framework builds itself with Vite directly                                                                                                                                                              |
 | **xmlui/**     | Generating metadata       | `npm run build:xmlui-metadata`   | `vite build --mode metadata`                    | After component changes, before doc generation | Extracts component metadata into `xmlui-metadata.js` for documentation generation and language server autocomplete. This is the source of truth for component APIs, props, and descriptions. Framework uses Vite directly.                                          |
 | **xmlui/**     | Full doc generation       | `npm run generate-all-docs`      | Node scripts (not CLI)                          | After metadata changes                         | Runs three scripts: (1) `build:xmlui-metadata` - extracts metadata, (2) `generate-docs` - creates component .md files from metadata, (3) `generate-docs-summaries` - creates overview/summary files. This is the complete pipeline from source code → documentation |
-| **xmlui/**     | Compile bin scripts       | `npm run build:bin`              | `tsc -p tsconfig.bin.json`                      | After changes to bin/\*.ts files               | Compiles TypeScript bin scripts (CLI tools) to JavaScript using TypeScript directly; needed when modifying build system or CLI commands                                                                                                                             |
+| **xmlui/**     | Compile bin scripts       | `npm run build:bin`              | `tsdown`                                        | After changes to bin/\*.ts files               | Compiles TypeScript bin scripts (CLI tools) to JavaScript using tsdown (see tsdown.config.ts); needed when modifying build system or CLI commands                                                                                                                   |
 | **extension/** | Development               | `npm start`                      | `xmlui start`                                   | Keep running during dev                        | Runs dev server with HMR for demo app; use with build-watch in separate terminal                                                                                                                                                                                    |
 | **extension/** | Watch mode build          | `npm run build-watch`            | `xmlui build-lib --watch`                       | Keep running during dev                        | Continuously rebuilds extension library on changes; pair with `npm start` for rapid iteration                                                                                                                                                                       |
 | **extension/** | Building for publish      | `npm run build:extension`        | `xmlui build-lib`                               | Before npm publish                             | Creates distributable library bundle (.mjs, .js, .d.ts, CSS) for npm package                                                                                                                                                                                        |

xmlui/dev-docs/build-xmlui.md

@@ -35,7 +35,7 @@ The XMLUI framework package is built using **Vite** with multiple build modes. T
 npm run build-xmlui              # Build entire XMLUI core package
 
 # From xmlui/ directory
-npm run build:bin                # Build CLI tools
+npm run build:bin                # Build CLI tools using tsdown
 npm run build:xmlui              # Build library mode
 npm run build:xmlui-standalone   # Build UMD bundle
 npm run build:xmlui-metadata     # Extract component metadata
@@ -47,7 +47,7 @@ npm run build:xmlui-metadata     # Extract component metadata
 
 | Mode           | Entry Point                   | Output Format        | Purpose                  |
 | -------------- | ----------------------------- | -------------------- | ------------------------ |
-| **lib**        | Multiple entries              | ES Modules (.mjs)    | npm package distribution |
+| **lib**        | Multiple entries              | ES Modules (.js)     | npm package distribution |
 | **standalone** | index-standalone.ts           | UMD bundle (.umd.js) | Buildless CDN deployment |
 | **metadata**   | collectedComponentMetadata.ts | ES Module            | Documentation/LSP        |
 
@@ -136,13 +136,13 @@ copy({
 
 ```
 dist/lib/
-  ├── xmlui.mjs                          # Main framework bundle
+  ├── xmlui.js                          # Main framework bundle
   ├── xmlui.d.ts                         # Bundled type definitions
-  ├── xmlui-parser.mjs                   # Parser bundle
-  ├── language-server.mjs                # LSP server bundle
-  ├── language-server-web-worker.mjs     # Browser LSP bundle
-  ├── syntax-monaco.mjs                  # Monaco syntax bundle
-  ├── syntax-textmate.mjs                # TextMate syntax bundle
+  ├── xmlui-parser.js                   # Parser bundle
+  ├── language-server.js                # LSP server bundle
+  ├── language-server-web-worker.js     # Browser LSP bundle
+  ├── syntax-monaco.js                  # Monaco syntax bundle
+  ├── syntax-textmate.js                # TextMate syntax bundle
   ├── *.css                              # Extracted component styles
   └── scss/                              # Source SCSS files
       └── (mirrors src/ structure)
@@ -154,35 +154,53 @@ After `clean-package` transforms package.json during publish:
 
 ```json
 {
-  "main": "./dist/lib/xmlui.js",
+  "main": "./dist/standalone/xmlui-standalone.umd.js",
+  "module": "./dist/lib/xmlui.js",
   "types": "./dist/lib/xmlui.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/lib/xmlui.js"
-    },
-    "./parser": {
-      "import": "./dist/lib/xmlui-parser.js"
+      "import": "./dist/lib/xmlui.js",
+      "require": "./dist/standalone/xmlui-standalone.umd.js"
     },
     "./language-server": {
-      "import": "./dist/lib/language-server.js"
+      "import": "./dist/lib/language-server.js",
+      "require": "./dist/lib/language-server.js"
     },
     "./language-server-web-worker": {
-      "import": "./dist/lib/language-server-web-worker.js"
+      "import": "./dist/lib/language-server-web-worker.js",
+      "require": "./dist/lib/language-server-web-worker.js"
     },
-    "./syntax/monaco": {
-      "import": "./dist/lib/syntax-monaco.js"
-    },
-    "./syntax/textmate": {
-      "import": "./dist/lib/syntax-textmate.js"
+    "./parser": {
+      "import": "./dist/lib/xmlui-parser.js",
+      "require": "./dist/lib/xmlui-parser.js"
     },
     "./*.css": {
-      "import": "./dist/lib/*.css"
+      "import": "./dist/lib/*.css",
+      "require": "./dist/lib/*.css"
     },
     "./index.scss": {
-      "import": "./dist/lib/scss/index.scss"
+      "import": "./dist/lib/scss/index.scss",
+      "require": "./dist/lib/scss/index.scss"
+    },
+    "./themes.scss": {
+      "import": "./dist/lib/scss/components-core/theming/_themes.scss",
+      "require": "./dist/lib/scss/components-core/theming/_themes.scss"
     },
     "./vite-xmlui-plugin": {
-      "import": "./dist/scripts/bin/vite-xmlui-plugin.js"
+      "import": "./dist/lib/vite-xmlui-plugin/index.js",
+      "require": "./dist/lib/vite-xmlui-plugin/index.js"
+    },
+    "./syntax/monaco": {
+      "import": "./dist/lib/syntax-monaco.js",
+      "require": "./dist/lib/syntax-monaco.js"
+    },
+    "./syntax/textmate": {
+      "import": "./dist/lib/syntax-textmate.js",
+      "require": "./dist/lib/syntax-textmate.js"
+    },
+    "./testing": {
+      "import": "./dist/lib/testing.js",
+      "require": "./dist/lib/testing.js"
     }
   }
 }
@@ -360,8 +378,8 @@ This internally runs in order:
 ```bash
 # 1. Build CLI tools
 npm run build:bin
-# Compiles TypeScript in bin/ folder using tsconfig.bin.json
-# Output: bin/*.js files
+# Compiles TypeScript in bin/ folder using tsdown (see tsdown.config.ts)
+# Output: dist/bin/
 
 # 2. Build library for npm
 npm run build:xmlui
@@ -405,11 +423,16 @@ The `clean-package` tool transforms package.json during publish:
 {
   "main": "./dist/lib/xmlui.js",
   "bin": {
-    "xmlui": "dist/scripts/bin/bootstrap.js"
+    "xmlui": "dist/bin/index.js"
   }
 }
 ```
 
+> **Note on CLI Development:**
+> In the development environment, the `xmlui` command points to `bin/bootstrap.js`. This file uses `tsx` to execute the CLI's TypeScript source (`bin/index.ts`) on-the-fly. This allows for rapid development of the CLI without requiring a separate build step for every change.
+>
+> For production, `clean-package` replaces the `bin` entry to point to the compiled `dist/bin/index.js`, ensuring the published package does not rely on `tsx`.
+
 ## Vite Configuration
 
 ### Target and Optimization

xmlui/dev-docs/xmlui-repo.md

@@ -187,7 +187,7 @@ The `turbo.json` file at the repository root defines all tasks and their orchest
 
 ```json
 {
-  "outputs": ["dist/scripts/**"]
+  "outputs": ["dist/bin/**"]
 }
 ```