@collagejs/core 0.2.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Micro library for framework-agnostic micro-frontends
 
-**🚧🚧 YOU'RE EARLY.  WORK IN PROGRESS... ETA: Early February, 2026 🚧🚧**
+**🚧🚧 I'M LATE.  WORK IN PROGRESS... ETA: JULY, 2026 🚧🚧**
 
 **If you're interested, star ⭐ the repository to get updates on the progress in your GH homepage.**
 
@@ -10,7 +10,11 @@
 
 [Full Documentation](https://collagejs.dev)
 
-*CollageJS* is a very, very small library that enables the composition of a web user interface with micro-frontends created with any technology (Svelte, React, Vue, SolidJS, HTMX, etc.).  It is heavily inspired by the *parcel* concept in the excellent `single-spa` routing library.
+> 📰 **SAD NEWS**
+>
+> `single-spa` creator *Joel/Jolyn Denning* [has passed away in late 2025](https://github.com/single-spa/single-spa/issues/1361#issuecomment-3991093643).
+
+*CollageJS* is a very, very small library that enables the composition of a web user interface with micro-frontends created with any technology (Svelte, React, Vue, SolidJS, HTMX, Lit, Ripple-TS, etc.).  It is heavily inspired by the *parcel* concept in the excellent `single-spa` routing library.
 
 ## How It Works
 
@@ -20,7 +24,7 @@
 type UnmountFn = () => Promise<void>;
 
 interface CorePiece<TProps> {
-    mount: (target: HTMLElement, props?: TProps) => Promise<UnmountFn>;
+    mount: (target: HTMLElement | ShadowRoot, props?: TProps) => Promise<UnmountFn>;
     update?: (props: TProps) => Promise<void>;
 };
 ```
@@ -42,7 +46,7 @@ This is a simple example that shows a tiny, yet complete micro-frontend made wit
 ```typescript
 export function buildTestPiece<TProps extends Record<string, any> = Record<string, any>>(
     callbacks?: {
-        mount: (target: HTMLElement, props?: MountProps<TProps>) => void | (() => void);
+        mount: (target: AcceptableTarget, props?: MountProps<TProps>) => void | (() => void);
         unmount: () => void;
         update: (props: TProps) => void;
     }
@@ -50,7 +54,7 @@ export function buildTestPiece<TProps extends Record<string, any> = Record<strin
     let pre: HTMLElement;
     return {
         // Here's mount():
-        async mount(target: HTMLElement, props?: MountProps<TProps>) {
+        async mount(target: AcceptableTarget, props?: MountProps<TProps>) {
             const delayMountCb = callbacks?.mount?.(target, props);
             pre = document.createElement('pre');
             pre.setAttribute('data-testid', pieceTestId);
@@ -138,7 +142,7 @@ Then the micro-frontends:  The concept doesn't exist.  At this point (after crea
 
 While `single-spa` asks you to shape your module exports in a particular way (the lifecycle functions), *CollageJS* imposes no such restriction.  It is just not necessary.  Just make sure you can get an object of type `CorePiece` to the `<Piece>` component of your preferred framework.  Then use your framework's marvels to make the `<Piece>` component appear or disappear.
 
-Yes, you'll still be working with import maps.  They are super handy.  We provide an enhanced (and simplified at the same time) version of `import-map-overrides` named `@collagejs/imo`.  It only supports the `overridable-importmap` type (and therefore only native import maps for native ES modules), but carries support for our `@collagejs/aim` plug-in that let's you statically import from micro-frontends.  **That's right!  We are free from dynamic `import()` calls!**  We can statically import from micro-frontends.  Furthermore, it has a more modern user interface:
+Yes, you'll still be working with import maps.  They are super handy.  We provide an enhanced (and simplified at the same time) version of `import-map-overrides` named `@collagejs/imo`.  It only supports the `overridable-importmap` type (and therefore only native import maps for native ES modules), but carries support for our `@collagejs/vite-aim` plug-in that let's you statically import from micro-frontends.  **That's right!  We are free from dynamic `import()` calls!**  We can statically import from micro-frontends.  Furthermore, it has a more modern user interface:
 
 ![Main screen of @collagejs/imo](./_docs/collagejs-imo.png)
 
@@ -158,12 +162,12 @@ Gone.  There's no equivalent in *CollageJS*, as experience with `single-spa` has
 | - | - | - | - |
 | `@collagejs/core` | ✔️ | (This repo) | Core functionality.  Provides the general mounting and unmounting logic. |
 | `@collagejs/vite-css` | ✔️ | [Repo](https://github.com/collagejs/vite) | Vite plug-in that offers a CSS-mounting algorithm that is fully compatible with Vite's CSS bundling, including split CSS.  It also features FOUC prevention. |
-| `@collagejs/vite-im` | 🚧 | [Repo](https://github.com/collagejs/vite) | **Coming soon**.  Vite plug-in that injects an import map and optionally the `import-map-overrides` package to define bare module identifiers for easy micro-frontend loading and debugging. |
-| `@collagejs/vite-aim` | 🚧 | [Repo](https://github.com/collagejs/vite) | **Coming soon**.  Vite-plugin that gives the Vite development server the ability to accept import maps from the client, which are used to resolve modules in the Vite pipeline, enabling static imports from micro-frontend bare module identifiers. |
-| `@collagejs/imo` | 🚧 | [Repo](https://github.com/collagejs/imo) | **Coming soon**.  Our version of `import-map-overrides` that does the usual overriding of import map entries, plus it transmits the final import map to Vite development servers found in it. |
+| `@collagejs/vite-im` | ✔️ | [Repo](https://github.com/collagejs/vite) | Vite plug-in that injects an import map and optionally the `import-map-overrides` package to define bare module identifiers for easy micro-frontend loading and debugging. |
+| `@collagejs/vite-aim` | ✔️ | [Repo](https://github.com/collagejs/vite) | Vite-plugin that gives the Vite development server the ability to accept import maps from the client, which are used to resolve modules in the Vite pipeline, enabling static imports from micro-frontend bare module identifiers. |
+| `@collagejs/imo` | ✔️ | [Repo](https://github.com/collagejs/imo) | Our version of `import-map-overrides` that does the usual overriding of import map entries, plus it transmits the final import map to Vite development servers found in it. |
 | `@collagejs/svelte` | ✔️ | [Repo](https://github.com/collagejs/svelte) | Svelte component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
-| `@collagejs/react` | ❌ | [Repo](https://github.com/collagejs/react) | **Next priority**.  React component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
-| `@collagejs/solidjs` | ❌ | [Repo](https://github.com/collagejs/vite) | SolidJS component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
+| `@collagejs/react` | 🚧 | [Repo](https://github.com/collagejs/react) | **Coming soon**.  React component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
+| `@collagejs/solidjs` | ❌ | [Repo](https://github.com/collagejs/solidjs) | SolidJS component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
 | `@collagejs/vue` | ❌ | [Repo](https://github.com/collagejs/vue) | VueJS component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
 | `@collagejs/angular` | ❌ | | **External help needed.**  We don't have expertise in Angular, nor do we want to acquire it.  If you're an Angular developer, please consider contributing. |
 

package/dist/MountedPiece.d.ts

@@ -1,10 +1,10 @@
-import type { CorePiece, MountPiece } from "./types.js";
+import type { CorePiece, MountPiece, AcceptableTarget } from "./types.js";
 export declare const mountKey: unique symbol;
 export declare class MountedPiece<TProps extends Record<string, any> = Record<string, any>> {
     #private;
     get mountPiece(): MountPiece<TProps>;
     constructor(piece: CorePiece<TProps>, mountPiece: MountPiece<TProps>, parent?: MountedPiece);
-    [mountKey](target: HTMLElement, props?: TProps): Promise<void>;
+    [mountKey](target: AcceptableTarget, props?: TProps): Promise<void>;
     unmount(): Promise<void>;
     update(props: TProps): Promise<void>;
 }

package/dist/global.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Ensures that the global CollageJs object exists.
+ */
+export declare function ensureGlobalCollageJs(): void;

package/dist/global.js

@@ -0,0 +1,8 @@
+/**
+ * Ensures that the global CollageJs object exists.
+ */
+export function ensureGlobalCollageJs() {
+    if (!globalThis.CollageJs) {
+        globalThis.CollageJs = {};
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export type * from './types.js';
 export { mountPiece } from './mountPiece.js';
 export { mountPieceKey } from './common.js';
+export { ensureGlobalCollageJs } from './global.js';

package/dist/index.js

@@ -1,2 +1,3 @@
 export { mountPiece } from './mountPiece.js';
 export { mountPieceKey } from './common.js';
+export { ensureGlobalCollageJs } from './global.js';

package/dist/mountPiece.d.ts

@@ -1,5 +1,5 @@
 import { MountedPiece } from "./MountedPiece.js";
-import type { CorePiece, MountPiece } from "./types.js";
+import type { AcceptableTarget, CorePiece, MountPiece } from "./types.js";
 /**
  * Constructor type for MountedPiece classes.
  *
@@ -8,11 +8,11 @@ import type { CorePiece, MountPiece } from "./types.js";
 export interface MountedPieceConstructor {
     new <TProps extends Record<string, any> = Record<string, any>>(piece: CorePiece<TProps>, mountPiece: MountPiece<any>, parent?: MountedPiece<any>): MountedPiece<TProps>;
 }
-export declare function mountPieceCore<TProps extends Record<string, any> = Record<string, any>>(this: MountedPiece | undefined, piece: CorePiece<TProps> | Promise<CorePiece<TProps>>, target: HTMLElement, props?: TProps, MountedPieceClass?: MountedPieceConstructor): Promise<MountedPiece<TProps>>;
+export declare function mountPieceCore<TProps extends Record<string, any> = Record<string, any>>(this: MountedPiece | undefined, piece: CorePiece<TProps> | Promise<CorePiece<TProps>>, target: AcceptableTarget, props?: TProps, MountedPieceClass?: MountedPieceConstructor): Promise<MountedPiece<TProps>>;
 /**
  * Mounts the CollageJS piece as a child of the target element.
  * @param piece The CollageJS piece to mount.
- * @param target The target element to mount the piece to.
+ * @param target The target HTML element or shadow root where to mount the piece.
  * @param props The properties to pass to the piece.
  */
-export declare function mountPiece<TProps extends Record<string, any> = Record<string, any>>(piece: CorePiece<TProps>, target: HTMLElement, props?: TProps): Promise<MountedPiece<TProps>>;
+export declare function mountPiece<TProps extends Record<string, any> = Record<string, any>>(piece: CorePiece<TProps>, target: AcceptableTarget, props?: TProps): Promise<MountedPiece<TProps>>;

package/dist/mountPiece.js

@@ -10,7 +10,7 @@ export async function mountPieceCore(piece, target, props, MountedPieceClass = M
 /**
  * Mounts the CollageJS piece as a child of the target element.
  * @param piece The CollageJS piece to mount.
- * @param target The target element to mount the piece to.
+ * @param target The target HTML element or shadow root where to mount the piece.
  * @param props The properties to pass to the piece.
  */
 export function mountPiece(piece, target, props) {

package/dist/types.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Defines the type for acceptable targets for mounting *CollageJS* pieces.
+ */
+export type AcceptableTarget = HTMLElement | ShadowRoot;
 /**
  * Properties passed to `mount()` functions of `CorePiece` objects.  It extends the piece's supported objects with a
  * property of type `symbol` that carries the piece parent's `mountPiece()` function.
@@ -11,11 +15,11 @@ export type MountProps<TProps extends Record<string, any> = Record<string, any>>
 export type UnmountFn = () => Promise<void>;
 /**
  * Type that defines the signature of the functions accepted in `CorePiece.mount`.
- * @param target The HTML target where the piece will be mounted as a child.
+ * @param target The HTML or shadow root target where the piece will be mounted as a child.
  * @param props The piece's initial property values.
  * @returns A promise to the cleanup function that unmounts the piece.
  */
-export type MountFn<TProps extends Record<string, any> = Record<string, any>> = (target: HTMLElement, props?: MountProps<TProps>) => Promise<UnmountFn>;
+export type MountFn<TProps extends Record<string, any> = Record<string, any>> = (target: AcceptableTarget, props?: MountProps<TProps>) => Promise<UnmountFn>;
 /**
  * Type that defines the signature of the functions accepted in `CorePiece.update`.
  * @param props The new property values for the mounted piece.
@@ -73,7 +77,18 @@ export interface MountedPiece<TProps extends Record<string, any> = Record<string
  * generates a version of the global function that works identically, except that it tracks the `CollageJS` pieces
  * mounted with it so these are unmounted automatically as soon as the parent is unmounted.
  * @param piece `CorePiece` object to mount in the provided target, or a promise that resolves said object.
- * @param target HTML element where to mount
+ * @param target HTML element or shadow root where to mount.
  * @param props Optional properties for the `CorePiece` object.
  */
-export type MountPiece<TProps extends Record<string, any> = Record<string, any>> = (piece: CorePiece<TProps> | Promise<CorePiece<TProps>>, target: HTMLElement, props?: TProps) => Promise<MountedPiece<TProps>>;
+export type MountPiece<TProps extends Record<string, any> = Record<string, any>> = (piece: CorePiece<TProps> | Promise<CorePiece<TProps>>, target: AcceptableTarget, props?: TProps) => Promise<MountedPiece<TProps>>;
+declare global {
+    /**
+     * Defines the capabilities in the global `CollageJs` object.
+     */
+    interface CollageJs {
+    }
+    /**
+     * Global object that provides functionality outside bundling.
+     */
+    var CollageJs: CollageJs;
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@collagejs/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Core functionality for CollageJS.",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
-    "test": "npm run check && npm run test:unit && npm run test:types",
-    "test:unit": "ts-mocha -n loader=ts-node/esm -p ./tsconfig.json --require ./tests/setup.ts ./tests/ut/**/*.test.ts",
-    "test:watch": "ts-mocha -n loader=ts-node/esm -p ./tsconfig.json --require ./tests/setup.ts ./tests/ut/**/*.test.ts --watch",
+    "test": "npm run test:unit && npm run test:types",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
     "test:types": "tstyche ./tests/typetests",
     "build": "tsc && pwsh -File ./post-build.ps1 && publint",
     "check": "tsc --noEmit"
@@ -65,20 +65,16 @@
   "files": [
     "dist"
   ],
+  "sideEffects": false,
   "devDependencies": {
-    "@types/chai": "^5.2.2",
-    "@types/jsdom": "^27.0.0",
-    "@types/mocha": "^10.0.10",
-    "@types/node": "^25.0.1",
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^26.0.0",
     "@types/sinon": "^21.0.0",
-    "chai": "^6.0.1",
-    "jsdom": "^27.3.0",
-    "mocha": "^11.7.2",
+    "jsdom": "^29.1.1",
     "publint": "^0.3.11",
-    "sinon": "^21.0.0",
-    "ts-mocha": "^11.1.0",
-    "ts-node": "^10.9.2",
-    "tstyche": "^5.0.2",
-    "typescript": "^5.8.2"
+    "sinon": "^22.0.0",
+    "tstyche": "^7.2.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
   }
 }