@collagejs/core 0.5.0 → 0.6.0

package/dist/MountedPiece.d.ts

@@ -1,4 +1,4 @@
-import type { CorePiece, MountPiece, AcceptableTarget, CorePieceCapabilities } from "./types.js";
+import type { CorePiece, MountPiece, AcceptableTarget, CorePieceCapabilities, RelocationResult } from "./types.js";
 export declare const mountKey: unique symbol;
 export declare class MountedPiece<TProps extends Record<string, any> = Record<string, any>, TCap extends Record<string, any> = {}> {
     #private;
@@ -7,5 +7,6 @@ export declare class MountedPiece<TProps extends Record<string, any> = Record<st
     [mountKey](target: AcceptableTarget, props?: TProps): Promise<void>;
     unmount(): Promise<void>;
     update(props: TProps): Promise<void>;
+    relocate(target: AcceptableTarget, newTarget: AcceptableTarget): Promise<RelocationResult>;
     get capabilities(): (CorePieceCapabilities & TCap) | undefined;
 }

package/dist/MountedPiece.js

@@ -30,6 +30,27 @@ async function doUpdate(update, props) {
     }
     return await update(props);
 }
+async function doRelocate(relocate, target, newTarget) {
+    if (Array.isArray(relocate)) {
+        let first = true;
+        let ready = false;
+        for (const fn of relocate) {
+            const r = await doRelocate(fn, target, newTarget);
+            if (r === 'ready') {
+                ready = true;
+            }
+            else if (!r) {
+                if (first) {
+                    return false;
+                }
+                throw new Error("Relocation function returned 'false' after another relocation function returned 'ready' or 'true'.  The piece's state is now inconsistent.");
+            }
+            first = false;
+        }
+        return ready ? 'ready' : true;
+    }
+    return await relocate(target, newTarget);
+}
 export class MountedPiece {
     #piece;
     #id;
@@ -68,6 +89,12 @@ export class MountedPiece {
     update(props) {
         return doUpdate(this.#piece.update, props);
     }
+    relocate(target, newTarget) {
+        if (!this.#piece.relocate) {
+            return Promise.resolve(false);
+        }
+        return doRelocate(this.#piece.relocate, target, newTarget);
+    }
     get capabilities() {
         return this.#piece.capabilities;
     }

package/dist/types.d.ts

@@ -20,6 +20,19 @@ export type UnmountFn = () => Promise<void>;
  * @returns A promise to the cleanup function that unmounts the piece.
  */
 export type MountFn<TProps extends Record<string, any> = Record<string, any>> = (target: AcceptableTarget, props?: MountProps<TProps>) => Promise<UnmountFn>;
+/**
+ * Defines the possible return values of `CorePiece.relocate`.
+ */
+export type RelocationResult = boolean | 'ready';
+/**
+ * Type that defines the signature of the functions accepted in `CorePiece.relocate`.
+ * @param parent The current parent of the piece's root element(s).
+ * @param newParent The new parent where the piece's root element(s) will be relocated.
+ * @returns A promise that resolves to `true` if the relocation was successful, `false` if it failed or relocation
+ * is disallowed, or `'ready'` if the piece is ready to be relocated, but the relocation must be performed by the
+ * caller.
+ */
+export type RelocateFn = (parent: AcceptableTarget, newParent: AcceptableTarget) => Promise<RelocationResult>;
 /**
  * Type that defines the signature of the functions accepted in `CorePiece.update`.
  * @param props The new property values for the mounted piece.
@@ -33,7 +46,11 @@ 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[];
+export type Update<TProps extends Record<string, any> = Record<string, any>> = UpdateFn<TProps> | UpdateFn<TProps>[] | Update<TProps>[];
+/**
+ * Defines the accepted shapes for `CorePiece.relocate`.
+ */
+export type Relocate = RelocateFn | RelocateFn[] | Relocate[];
 /**
  * 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
@@ -50,18 +67,6 @@ export type CorePieceCapabilities = {
      * **💡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).
@@ -77,14 +82,47 @@ 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>;
+    /**
+     * Either relocates the root element(s) of the piece to a new parent, or prepares the piece for relocation.  This
+     * is optional.  If not provided, the piece won't support relocation of its root element(s) to a new parent, and
+     * the piece will be unmounted and remounted instead in the pertinent cases.
+     *
+     * ### Return Values
+     *
+     * + `true`:  The relocation was successful.
+     * + `false`:  The relocation failed or is disallowed.
+     * + `'ready'`:  The piece is ready to be relocated, but the relocation must be performed by the caller.
+     *
+     * ### When Using Multiple Relocation Functions
+     *
+     * If multiple relocation functions are provided, they will be called in order:
+     *
+     * + If the first of them returns `false`, the relocation process will stop.
+     * + If all of them return `true`, the relocation is considered successful.
+     * + If any of them returns `'ready'`, the remaining functions are still called, but the caller will
+     * run its relocation process after all functions have been called.
+     * + If any of them returns `false` after one or more of them returned `'ready'` or `true`, an error is thrown.
+     */
+    relocate?: Relocate;
     /**
      * 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.
+     * capabilities.
+     *
+     * ### Notable Exception
      *
-     * **💡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.
+     * The library defines the `remountable` capability, which is informative only.  The core library cannot enforce
+     * this capability, so `CorePiece` developers should use the `preventRemount()` function (or equivalent) to throw an
+     * error if the piece is mounted more than once for pieces that cannot withstand multiple mountings.
+     *
+     * Official framework adapters query the value of `capabilities.remountable` and act accordingly to their best
+     * ability, and at least emit a warning if a non-remountable piece is mounted more than once.
+     *
+     * Only the author of a `CorePiece` object can guarantee that the piece is remountable.  We encourage developers to
+     * be explicit about this capability when creating `CorePiece` objects.
+     *
+     * > ℹ️ **NOTE:**  Official framework adapters are free to choose which default value for `capabilities.remountable`
+     * > they will use while creating `CorePiece` objects when the property is not provided in order to maximize
+     * > framework feature usage (perhaps a framework can guarantee component state automatically, or perhaps it cannot).
      */
     readonly capabilities?: CorePieceCapabilities & TCap;
 }
@@ -100,6 +138,10 @@ export interface MountedPiece<TProps extends Record<string, any> = Record<string
      * Function used to unmount the `CorePiece` object.
      */
     unmount: UnmountFn;
+    /**
+     * Function used to relocate the `CorePiece` object to a new parent without unmounting.
+     */
+    relocate: RelocateFn;
     /**
      * The version of the global `mountPiece` function that tracks mounted children so their unmounting is
      * synchronized with this piece's unmount event.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collagejs/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Core functionality for CollageJS.",
   "type": "module",
   "main": "./dist/index.js",