@collagejs/core 0.4.0 → 0.5.0

package/README.md

@@ -23,9 +23,10 @@
 ```typescript
 type UnmountFn = () => Promise<void>;
 
-interface CorePiece<TProps> {
+interface CorePiece<TProps, TCap> {
     mount: (target: HTMLElement | ShadowRoot, props?: TProps) => Promise<UnmountFn>;
     update?: (props: TProps) => Promise<void>;
+    readonly capabilities?: CorePieceCapabilities & TCap;
 };
 ```
 > ℹ️ These types were simplified.  See the real ones after installing the library.
@@ -34,6 +35,7 @@ In short:  Micro-frontend creators must simply provide a way to generate an obje
 
 - `mount` mounts the micro-frontend user interface in the document
 - `update` updates the properties given to the micro-frontend
+- `capabilities` is a feature introduced in v0.5.0 that allows core piece objects to declare its capabilities (see more in its own section)
 
 The `update` function is optional.  The `mount` function must return a cleanup function that, ideally, reverts the mounting process.
 
@@ -67,7 +69,7 @@ export function buildTestPiece<TProps extends Record<string, any> = Record<strin
             // Here's the unmounting function:
             return () => {
                 callbacks?.unmount?.();
-                target.removeChild(pre);
+                pre.remove();
                 return Promise.resolve();
             };
         },
@@ -142,7 +144,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/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:
+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 lets 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)
 
@@ -156,19 +158,31 @@ In *CollageJS*, `CorePiece.mount()` returns the clean-up (unmounting) function.
 
 Gone.  There's no equivalent in *CollageJS*, as experience with `single-spa` has demonstrated that is rarely needed, and if needed, one can do this initialization easily without having to impose the function requirement.  At least for now, there's no foreseeable future where an initialization function similar to `single-spa`'s `bootstrap()` will be defined.  But we agree:  *Never say NEVER*.
 
+## I'm Curious about `capabilities`
+
+Ok, in a nutshell, what inspired this feature was implementing the ability to mount micro-frontends (and its CSS) inside shadow root objects, plus give the developers a good DX.  In short:  If you, the dev, said you wanted the MFE in an open shadow root, but then changed your mind and now you want a closed shadow root, we have to unmount and remount or some other hacky things, like a full page reload.  But for this case, and at least in Svelte, we could relocate the component's generated DOM tree without remounting.
+
+This sounds great, but what if that breaks the MFE?  So the safe path is not to take advantage of cool features.  This conclusion made me sad as a developer.  Therefore, enter `capabilties`.
+
+The `capabilities` object simply states what the core piece object is able to withstand.  The core library defines 2 capabilities, and devs can add user-defined ones to the object.
+
+One of the stock (or "official" if you will) capabilities is `relocatable: boolean`.  If a core piece object returns `true` for `relocatable`, it is making this statement:  "I can take DOM relocation operations without going through the mounting lifecycle".
+
+With this reassurance at hand, framework adapters like `@collagejs/svelte` and others that can pull the trick cleanly can go ahead and do it, enhancing DX.  This made me happy once more as a developer, and hope that it makes more devs happy.
+
 ## Packages
 
 | Package | Status | Links | Description |
 | - | - | - | - |
 | `@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) | 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/vite-im` | ✔️ | [Repo](https://github.com/collagejs/vite) | Vite plug-in that injects an import map and optionally the `@collagejs/imo` 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 auto-externalizes the module identifiers found in the application's import map.  It receives the import map live (and with overrides) from the client.  This enables static imports (no more dynamic `import()` calls). |
 | `@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) | **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/react` | ✔️ | [Repo](https://github.com/collagejs/react) | 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/vue` | 🚧 | [Repo](https://github.com/collagejs/vue) | **Next in line**  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. |
 
 ## Other Repositories

package/dist/MountedPiece.d.ts

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

package/dist/MountedPiece.js

@@ -63,8 +63,12 @@ export class MountedPiece {
         if (this.#parent) {
             this.#parent.#childPieces.delete((item) => item.#id === this.#id);
         }
+        this.#cleanup = undefined;
     }
     update(props) {
         return doUpdate(this.#piece.update, props);
     }
+    get capabilities() {
+        return this.#piece.capabilities;
+    }
 }

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/mountPiece.d.ts

@@ -6,13 +6,13 @@ import type { AcceptableTarget, CorePiece, MountPiece } from "./types.js";
  * This exists merely to allow unit testing.
  */
 export interface MountedPieceConstructor {
-    new <TProps extends Record<string, any> = Record<string, any>>(piece: CorePiece<TProps>, mountPiece: MountPiece<any>, parent?: MountedPiece<any>): MountedPiece<TProps>;
+    new (piece: CorePiece<any, any>, mountPiece: MountPiece<any, any>, parent?: MountedPiece<any, any>): MountedPiece<any, any>;
 }
-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>>;
+export declare function mountPieceCore<TProps extends Record<string, any> = Record<string, any>, TCap extends Record<string, any> = {}>(this: MountedPiece<any, any> | undefined, piece: CorePiece<TProps, TCap> | Promise<CorePiece<TProps, TCap>>, target: AcceptableTarget, props?: TProps, MountedPieceClass?: MountedPieceConstructor): Promise<MountedPiece<TProps, TCap>>;
 /**
  * Mounts the CollageJS piece as a child of the target element.
  * @param piece The CollageJS piece to mount.
  * @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: AcceptableTarget, props?: TProps): Promise<MountedPiece<TProps>>;
+export declare function mountPiece<TProps extends Record<string, any> = Record<string, any>, TCap extends Record<string, any> = {}>(piece: CorePiece<TProps, TCap>, target: AcceptableTarget, props?: TProps): Promise<MountedPiece<TProps, TCap>>;

package/dist/mountPiece.js

@@ -3,7 +3,7 @@ export async function mountPieceCore(piece, target, props, MountedPieceClass = M
     if (piece instanceof Promise) {
         piece = await piece;
     }
-    const mp = new MountedPieceClass(piece, (mountPieceCore), this);
+    const mp = new MountedPieceClass(piece, mountPieceCore, this);
     await mp[mountKey](target, props);
     return mp;
 }

package/dist/preventRemount.d.ts

@@ -0,0 +1,32 @@
+import type { MountFn } from "./types.js";
+/**
+ * Creates a mount function that can only be called once. If the mount function is called more than once, it will throw
+ * an error. This effectively prevents a piece from being mounted more than once.
+ *
+ * Use this on core piece objects that cannot guarantee the integrity of their state after they unmount.
+ *
+ * @example
+ * import { preventRemount } from "@collagejs/core";
+ *
+ * export function myCorePieceFactory() {
+ *   ...
+ *   return {
+ *     // The most logical place is at the very beginning of the mount array.
+ *     mount: [preventRemount(), myMount],
+ *     update: ...,
+ *     capabilities: {
+ *       // Informational only:  Allow the core piece object to answer the question.
+ *       remountable: false,
+ *     }
+ *   };
+ * }
+ *
+ * ### 💡 Tips
+ *
+ * - Try to always follow the "fail fast" principle, so call `preventRemount()` as early as possible in the mount array.
+ * - If for any reason the mount operation is expected to fail (for whatever needed reason), consider moving the call
+ * to `preventRemount()` after the mount operation that may fail, so that the piece object does not have to be
+ * discarded unnecessarily.
+ * @returns A mount function that throws an error if called more than once.
+ */
+export declare function preventRemount<TProps extends Record<string, any> = Record<string, any>>(): MountFn<TProps>;

package/dist/preventRemount.js

@@ -0,0 +1,40 @@
+/**
+ * Creates a mount function that can only be called once. If the mount function is called more than once, it will throw
+ * an error. This effectively prevents a piece from being mounted more than once.
+ *
+ * Use this on core piece objects that cannot guarantee the integrity of their state after they unmount.
+ *
+ * @example
+ * import { preventRemount } from "@collagejs/core";
+ *
+ * export function myCorePieceFactory() {
+ *   ...
+ *   return {
+ *     // The most logical place is at the very beginning of the mount array.
+ *     mount: [preventRemount(), myMount],
+ *     update: ...,
+ *     capabilities: {
+ *       // Informational only:  Allow the core piece object to answer the question.
+ *       remountable: false,
+ *     }
+ *   };
+ * }
+ *
+ * ### 💡 Tips
+ *
+ * - Try to always follow the "fail fast" principle, so call `preventRemount()` as early as possible in the mount array.
+ * - If for any reason the mount operation is expected to fail (for whatever needed reason), consider moving the call
+ * to `preventRemount()` after the mount operation that may fail, so that the piece object does not have to be
+ * discarded unnecessarily.
+ * @returns A mount function that throws an error if called more than once.
+ */
+export function preventRemount() {
+    let mountCount = 0;
+    return () => {
+        if (mountCount > 0) {
+            throw new Error("This piece cannot be mounted more than once.  If this is unexpected, you might be unknowingly sharing the same piece object in different places or Piece components.");
+        }
+        ++mountCount;
+        return Promise.resolve(() => Promise.resolve());
+    };
+}

package/dist/types.d.ts

@@ -34,10 +34,39 @@ export type Mount<TProps extends Record<string, any> = Record<string, any>> = Mo
  * Defines the accepted shapes for `CorePiece.update`.
  */
 export type Update<TProps extends Record<string, any> = Record<string, any>> = UpdateFn<TProps> | UpdateFn<TProps>[] | Update[];
+/**
+ * Defines the capabilities of a `CorePiece` object recognized by the core *CollageJS* library.  These capabilities are
+ * used to determine how the core library should handle the piece's lifecycle, or whether a particular action or
+ * feature can be enabled or allowed.
+ */
+export type CorePieceCapabilities = {
+    /**
+     * Informative only:  Indicates that the piece can be mounted more than once.
+     *
+     * Since `@collagejs/core` never injects code into `CorePiece` objects, it cannot enforce this capability.  The
+     * only place where this can be enforced is at `CorePiece.mount`.  The core library provides the `preventRemount()`
+     * function to help developers create mount functions that throw an error if called more than once.
+     *
+     * **💡TIP**:  Official framework adapters provide this functionality.
+     */
+    remountable?: boolean;
+    /**
+     * Indicates that the piece allows relocation of its HTML markup to a new parent without unmounting.  For the best
+     * development experience, piece objects should always strive to be relocatable.
+     *
+     * If `false`, `Piece` components created with official framework adapters will most likely have to ask HMR to
+     * perform a full page reload whenever the developer changes shadow DOM options, like moving from an open to a
+     * closed shadow root.
+     *
+     * If `true` **and if the framework is capable** (i. e. Svelte), the piece can be relocated without unmounting, and
+     * HMR will be able to update the shadow root options without a full page reload.
+     */
+    relocatable?: boolean;
+};
 /**
  * Defines the contract that objects must follow in order to be mountable as *CollageJS* pieces (micro-frontends).
  */
-export interface CorePiece<TProps extends Record<string, any> = Record<string, any>> {
+export interface CorePiece<TProps extends Record<string, any> = Record<string, any>, TCap extends Record<string, any> = {}> {
     /**
      * Mounts the piece (micro-frontend) in the document.  Every mount function should always return a cleanup function
      * that, when called, unmounts the piece.
@@ -48,11 +77,21 @@ export interface CorePiece<TProps extends Record<string, any> = Record<string, a
      * while mounted in the document, and all property values must have been passed during mounting.
      */
     update?: Update<TProps>;
+    /**
+     * Declares the capabilities of the piece.  This is optional.  If not provided, the piece will be assumed to have no
+     * capabilities, and the core library will treat it as a simple piece that can be mounted once and unmounted once, and
+     * that cannot be relocated or re-mounted.
+     *
+     * **💡TIP**: Always try to at least create pieces that are relocatable by not storing the original target element in
+     * the piece's state.  Instead, just use the piece's root element's `parentElement` property to determine the
+     * current parent element.
+     */
+    readonly capabilities?: CorePieceCapabilities & TCap;
 }
 /**
  * Defines the shape of the object returned by the process of mounting a `CorePiece` object.
  */
-export interface MountedPiece<TProps extends Record<string, any> = Record<string, any>> {
+export interface MountedPiece<TProps extends Record<string, any> = Record<string, any>, TCap extends Record<string, any> = {}> {
     /**
      * Function used to apply updated property values to the mounted `CorePiece` object.
      */
@@ -68,7 +107,11 @@ export interface MountedPiece<TProps extends Record<string, any> = Record<string
      * **IMPORTANT:**  Always use this function instead of the global `mountPiece` function when mounting other
      * `CorePiece` objects inside the mounted `CorePiece` object to prevent lifecycle issues.
      */
-    mountPiece: MountPiece<TProps>;
+    mountPiece<UProps extends Record<string, any> = Record<string, any>, UCap extends CorePieceCapabilities = CorePieceCapabilities>(piece: CorePiece<UProps, UCap> | Promise<CorePiece<UProps, UCap>>, target: AcceptableTarget, props?: UProps): Promise<MountedPiece<UProps, UCap>>;
+    /**
+     * The declared capabilities of the mounted `CorePiece` object.
+     */
+    readonly capabilities: (CorePieceCapabilities & TCap) | undefined;
 }
 /**
  * Type definition for the `mountPiece` functions that mount *CollageJS* pieces in the HTML document.
@@ -80,7 +123,7 @@ export interface MountedPiece<TProps extends Record<string, any> = Record<string
  * @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: AcceptableTarget, props?: TProps) => Promise<MountedPiece<TProps>>;
+export type MountPiece<TProps extends Record<string, any> = Record<string, any>, TCap extends Record<string, any> = {}> = (piece: CorePiece<TProps, TCap> | Promise<CorePiece<TProps, TCap>>, target: AcceptableTarget, props?: TProps) => Promise<MountedPiece<TProps, TCap>>;
 declare global {
     /**
      * Defines the capabilities in the global `CollageJs` object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collagejs/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Core functionality for CollageJS.",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,7 +9,8 @@
     "test:unit": "vitest run",
     "test:watch": "vitest",
     "test:types": "tstyche ./tests/typetests",
-    "build": "tsc && pwsh -File ./post-build.ps1 && publint",
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc && pwsh -File ./post-build.ps1 && publint",
     "check": "tsc --noEmit"
   },
   "keywords": [
@@ -72,6 +73,7 @@
     "@types/sinon": "^21.0.0",
     "jsdom": "^29.1.1",
     "publint": "^0.3.11",
+    "rimraf": "^6.1.3",
     "sinon": "^22.0.0",
     "tstyche": "^7.2.1",
     "typescript": "^6.0.3",

package/dist/internal-types.d.ts

@@ -1,8 +0,0 @@
-import type { UnmountFn, UpdateFn } from "./types.js";
-export declare namespace Internal {
-    type MountedPiece<TProps extends Record<string, any> = Record<string, any>> = {
-        update: UpdateFn<TProps>;
-        unmount: UnmountFn;
-        childPieces: Map<string, MountedPiece>;
-    };
-}

package/dist/internal-types.js

@@ -1 +0,0 @@
-export {};