tungsten 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tungsten",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
-    "./react-zone": "./dist/react-zone.js",
+    "./react-zone": "./dist/zones/react.js",
+    "./testing": "./dist/testing/index.js",
     "./*": "./dist/*",
     "./types/*": "./types/*"
   },
@@ -123,6 +124,7 @@
     "eslint-import-resolver-typescript": "^2.7.1",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-no-type-assertion": "^1.3.0",
+    "happy-dom": "^20.10.6",
     "progress-webpack-plugin": "^1.0.16",
     "prop-types": "^15.8.1",
     "rimraf": "^5.0.10",

package/readme.md

@@ -2,6 +2,71 @@
 
 [Docs](https://robertsandiford.co.uk/tungsten)
 
+## Component testing
+
+Test-specific APIs are available from `tungsten/testing` and are not exported
+from Tungsten's main entry point. A test project supplies its own DOM
+implementation, such as happy-dom or jsdom:
+
+```tsx
+import { Window } from 'happy-dom'
+import { createTestApp } from 'tungsten/testing'
+
+describe('RootComponent', () => {
+    it('responds to a button click', async () => {
+        const window = new Window()
+        const testApp = await createTestApp(RootComponent, {
+            document: window.document as unknown as Document,
+            props: { initialName: 'Robert' },
+            location: '/',
+        })
+
+        try {
+            const button = testApp.container.querySelector('button')
+            expect(button).not.toBeNull()
+
+            button!.dispatchEvent(new window.Event('click') as unknown as Event)
+            await testApp.resolved()
+
+            expect(testApp.container.textContent).toContain('Robert')
+        } finally {
+            await testApp.unmount()
+        }
+    })
+})
+```
+
+The casts are only needed when a DOM package publishes types which are not
+structurally compatible with the TypeScript DOM library version used by the
+test project.
+
+`createTestApp()` completes the initial client render before returning.
+`resolved()` subsequently waits for Tungsten updates, DOM reconciliation,
+lifecycle-triggered updates, and promises returned by registered event
+handlers. It does not wait for unrelated timers, network requests, or promises
+which the application has not returned to Tungsten.
+
+An automatically created container is appended to the supplied document body
+and removed by `unmount()`. A caller-supplied container must be empty; it is
+emptied but retained during unmount.
+
+Registered stores are created independently for each test application. Use
+`testStore()` to initialize one before the root component starts:
+
+```ts
+import { createTestApp, testStore } from 'tungsten/testing'
+
+const testApp = await createTestApp(RootComponent, {
+    document,
+    stores: [testStore(userStore, store => {
+        store.user.set(mockUser)
+    })],
+})
+```
+
+Tests containing Tungsten JSX must be compiled through `tungsten compile` so
+they use Tungsten's JSX runtime and application transforms.
+
 ## Preparing code for tests
 
 Run a one-shot development compilation without starting a server:
@@ -16,6 +81,17 @@ transforms), stylesheets, client support files, assets, and public files into
 Each selected target's existing generated output is cleaned before the initial
 compilation, including when watch mode is used. Pass `--no-clean` to preserve
 existing output.
+
+Use `--output` to select an independent output root. The layout below that root
+is the same as `.tungsten/dev`, including `code`, `.client`, `.static`,
+`.assets`, `.public`, `.componentCss`, and `.packages`:
+
+```sh
+tungsten compile --output .tungsten/test
+tungsten compile --output .tungsten/test --watch
+```
+
+Cleaning and generated package-cache data are scoped to the selected output.
 Limit the work with one or more options:
 
 ```sh
@@ -27,7 +103,7 @@ tungsten compile --public
 tungsten compile --js --css
 ```
 
-`--all` explicitly selects all three targets.
+`--all` explicitly selects all five targets.
 
 Add `--watch` to keep the JavaScript, stylesheet, asset, and/or public-file
 compiler running after the initial pass. Client support files are still
@@ -37,3 +113,28 @@ generated once:
 tungsten compile --watch
 tungsten compile --js --watch
 ```
+
+For process orchestration, `--ready-file <file>` writes a small JSON file only
+after the initial compilation succeeds. A failed JavaScript watch cycle removes
+the file, and a later successful cycle recreates it. `--quiet` suppresses
+per-file transformation messages while retaining errors and cycle status:
+
+```sh
+tungsten compile --watch --output .tungsten/test \
+  --ready-file .tungsten/test.ready --quiet
+```
+
+## Preserving package imports in selected files
+
+Use `skipPackageCompilation` in `tungsten.config.js` for files that should be
+transformed and emitted without Tungsten traversing or copying their package
+dependencies. Bare package imports in matching files are left unchanged:
+
+```js
+export default {
+    skipPackageCompilation: '**/*.domTest.js'
+}
+```
+
+The option accepts one glob or an array of globs. Patterns match the actual
+JavaScript files received by Tungsten; extensions are not translated.

package/dist/react-zone.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"react-zone.d.ts","sourceRoot":"","sources":["../src/react-zone.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAC1E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,MAAM,IAC7C,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAC3B,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAA;AAEvC,KAAK,aAAa,GAAG;IACjB,MAAM,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;IAC/B,OAAO,IAAI,IAAI,CAAA;CAClB,CAAA;AAED,KAAK,kBAAkB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;AAE7F,MAAM,MAAM,gBAAgB,GAAG;IAC3B,KAAK,EAAE;QACH,SAAS,EAAE,GAAG,CAAA;QACd,aAAa,EAAE,kBAAkB,CAAA;KACpC,CAAA;IACD,MAAM,EAAE;QACJ,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,CAAA;QACxC,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,aAAa,CAAA;KAC/D,CAAA;IACD,MAAM,EAAE;QACJ,cAAc,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;KAC5C,CAAA;CACJ,CAAA;AAED,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,MAAM,IAAI;IAC/C,SAAS,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAA;IACpC,KAAK,EAAE,KAAK,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,QAAQ,CAAA;IACjB,OAAO,EAAE,gBAAgB,CAAA;CAC5B,CAAA;AAED,qBAAa,SAAS,CAAC,KAAK,SAAS,MAAM,CAAE,SAAQ,uBAAuB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/F,OAAO,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAqC;IAChF,SAAS,EAAE,aAAa,GAAG,SAAS,CAAA;IACpC,kBAAkB,EAAE,kBAAkB,GAAG,SAAS,CAAA;IAClD,aAAa,EAAE,OAAO,GAAG,SAAS,CAAA;IAClC,SAAS,UAAQ;IAEjB,OAAO,QAAa,OAAO,CAAC,WAAW,CAAC,CAsBvC;IAED,iBAAiB,QAAO,IAAI,CAG3B;IAED,kBAAkB,QAAO,IAAI,CAE5B;IAED,oBAAoB,QAAO,IAAI,CAM9B;IAED,OAAO,CAAC,UAAU;IAyBlB,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,WAAW;CAOtB"}