@collagejs/svelte 0.1.0 → 0.2.0

package/README.md

@@ -9,7 +9,7 @@ This is the official Svelte component library for *CollageJS* used to:
 1. Create *CollageJS* `CorePiece` objects out of Svelte components
 2. Consume `CorePiece` objects (made with any framework or library) in Svelte v5 projects
 
-## Creating Svelte-Based `CorePiece` Objects
+## Creating Svelte-Powered `CorePiece` Objects
 
 Whenever we are creating a micro-frontend in Svelte v5 and wish for it to be used with *CollageJS*, we must create a `CorePiece` wrapper object for the Svelte component that is the root of our micro-frontend.  Unless we wanted to take on this task ourselves, we use this package's `buildPiece()` function:
 
@@ -18,12 +18,23 @@ Whenever we are creating a micro-frontend in Svelte v5 and wish for it to be use
 import { buildPiece } from "@collagejs/svelte";
 // The component to wrap.  It usually is App.svelte.
 import App from "./App.svelte";
+// Automatic CSS mounting and unmounting algorithm:
+import { cssMountFactory } from "@collagejs/vite-css/ex";
+
+// Only one cssMount per file is needed, regardless of the number of factory functions.
+const cssMount = cssMountFactory('mfe' /*, { options } */);
 
 export function myMfeFactory() {
-    return buildPiece(App /*, { options } */);
+    const piece = buildPiece(App /*, { options } */);
+    export {
+        mount: [cssMount, piece.mount],
+        update: piece.update
+    }
 }
 ```
 
+It is also customary to install [@collagejs/vite-css](https://github.com/collagejs/vite-css) in our piece-exporting projects to be able to mount the bundled CSS files that Vite produces.  The CSS-mounting function features FOUC prevention, but it only works if `cssMount` is listed in the array before `piece.mount`.  Remember this!
+
 > ✨ **Tip**:  Repeat this process in the same or different file for any number of Svelte components that you wish to make available as independent micro-frontends.  The sky is the limit.
 
 ## Consuming `CorePiece` Objects
@@ -42,3 +53,20 @@ We can mount *CollageJS* pieces created in any technology in Svelte projects by
 1. We must use the `piece()` function to pass the `CorePiece` object.
 2. The example uses the name of the factory function in the previous example, so we're mounting a Svelte MFE inside a Svelte project.
 3. The `"@my/bare-module-specifier"` module name is the bare module specifier we assign to the micro-frontend in our root project's import map.
+
+### Intellisense On The `CorePiece` Props
+
+Your IDE can provide Intellisense on the properties the `CorePiece` given to `<Piece>` supports if the return value of the factory function is properly typed.
+
+You can go several routes to type the factory functions.  One of these is to create a `.d.ts` file and declare the ambient module:
+
+```typescript
+import "@collagejs/core";
+
+declare module "@my/bare-module-identifier" {
+    function myMfeFactory(): CorePiece<{ extra: string; data: boolean; }>;
+    // --------------------------------^  <-- Properties type
+    // Etc. Other factory functions for this module.
+    ...
+}
+```

package/dist/Piece/Piece.svelte

@@ -1,154 +1,154 @@
-<script module lang="ts">
-    const piecePropsSymbol = Symbol();
-
-    /**
-     * Defines the special properties accepted by the `Piece` component.  This type is to be used in conjunction with 
-     * the `piece()` helper function to create the special property required by the `Piece` component.
-     */
-    export type PieceProps<
-        TProps extends Record<string, any> = Record<string, any>,
-    > = {
-        /**
-         * The special property that contains the `CorePiece` instance to render, along with optional container 
-         * properties.
-         */
-        [piecePropsSymbol]: {
-            /**
-             * The `CorePiece` instance to render.
-             */
-            piece: CorePiece<TProps>;
-            /**
-             * Optional HTML attributes to set on the container element that wraps the piece.
-             */
-            containerProps?: HTMLAttributes<HTMLDivElement>;
-        };
-    };
-
-    /**
-     * Helper function to create the special property required by the `Piece` component.  The result of this function 
-     * is to be spread into the props of the `Piece` component.
-     * 
-     * @example
-     * ```svelte
-     * <Piece {...piece(myPiece, { onfocusin: focusInHandler })} foo="bar" count={42} />
-     * ```
-     * 
-     * @param piece The `CorePiece` instance to render.
-     * @param containerProps Optional HTML attributes to set on the container element that wraps the piece.
-     * @returns An object containing the special property to pass to the `Piece` component.
-     */
-    export function piece<
-        TProps extends Record<string, any> = Record<string, any>,
-    >(
-        piece: CorePiece<TProps>,
-        containerProps?: HTMLAttributes<HTMLDivElement>,
-    ) {
-        return {
-            [piecePropsSymbol]: {
-                piece,
-                containerProps,
-            },
-        };
-    }
-</script>
-
-<script
-    lang="ts"
-    generics="TProps extends Record<string, any> = Record<string, any>"
->
-    import { getCollageContext } from "../collageContext.js";
-    import {
-        mountPiece,
-        type CorePiece,
-        type MountedPiece,
-        type MountPiece,
-    } from "@collagejs/core";
-    import { onMount } from "svelte";
-    import type { HTMLAttributes } from "svelte/elements";
-
-    type Props = TProps & PieceProps<TProps>;
-
-    let { ...restProps }: Props = $props();
-
-    const { piece: corePiece, containerProps } = $derived(restProps[piecePropsSymbol]);
-    let containerEl: HTMLDivElement;
-    let firstRun = true;
-    const ctx = getCollageContext();
-    let mountedPiece: MountedPiece<TProps> | undefined;
-
-    onMount(() => {
-        const mountPieceFn =
-            (ctx?.mountPiece as MountPiece<TProps>) ?? mountPiece<TProps>;
-        const mountPromise = mountPieceFn(corePiece, containerEl, restProps).then((mp) => {
-            mountedPiece = mp;
-        });
-        return async () => {
-            await mountPromise;
-            await mountedPiece?.unmount();
-            mountedPiece = undefined;
-        };
-    });
-
-    $effect(() => {
-        // Must be the first line so the dependency on restProps is tracked.
-        const newProps = { ...restProps };
-        delete (newProps as any)[piecePropsSymbol];
-        if (firstRun) {
-            firstRun = false;
-            return;
-        }
-        mountedPiece?.update(newProps);
-    });
-</script>
-
-<div bind:this={containerEl} {...containerProps}></div>
-
-<style>
-    div {
-        display: contents;
-    }
-</style>
-<!--
-@component
-
-### Piece Component
-
-Renders a CollageJS "piece" (micro-frontend) inside a Svelte application.  The piece itself may be built using any 
-valid framework or library, as long as it adheres to the *CollageJS* `CorePiece` interface.
-
-#### Props
-
-Properties passed to the `Piece` component must include a special property created using the `piece()` helper
-function. This property contains the `CorePiece` instance to render, along with optional container properties.  One can 
-also pass additional properties that will be forwarded to the mounted piece.
-
-If the mounted piece supports property updates, any changes to the additional properties will be propagated to the 
-piece reactively as per the rules of Svelte's reactivity system.
-
-#### Example Usage
-
-1. Import the `Piece` component and the `piece()` helper function from the library.
-2. Import whatever you need to get a hold of your `CorePiece` instance.  Normally, one imports a factory function that 
-creates the piece from a *bare module specifier* (an alias defined by your application's import map):
-    ```typescript
-    import Piece, { piece } from '@collagejs/svelte';
-    import { myPieceFactory } from '@my/bare-module-specifier';
-    ```
-3. Create a `CorePiece` instance using your factory function.  Pass whatever arguments the factory function requires.
-4. Render the `Piece` component in your Svelte template, passing the `CorePiece` instance using the `piece()` helper 
-function.  Also pass any additional properties that the piece supports:
-
-```svelte
-<Piece {...piece(myPieceFactory(), { class: 'my-piece-container' })} foo="bar" count={42} />
-```
-
-The above sets the `my-piece-container` CSS class on the container element that wraps the piece, and also passes the 
-`foo` and `count` properties to the mounted piece.  This example uses constant values in the properties, but you can 
-also pass stateful values that can update reactively, as if it were a regular Svelte component.
-
-> ⚠️ **IMPORTANT**:  Once a piece has unmounted, it cannot be remounted.  You must create a new `CorePiece` instance 
-> and `<Piece>` instance.  This is by design.  The easiest is to have the call to the factory function inside the 
-> Svelte template, so that a new `CorePiece` instance is created each time a new `<Piece>` instance is created.
-
-Online Documentation: Pending (https://collagejs.dev)
--->
+<script module lang="ts">
+    const piecePropsSymbol = Symbol();
+
+    /**
+     * Defines the special properties accepted by the `Piece` component.  This type is to be used in conjunction with 
+     * the `piece()` helper function to create the special property required by the `Piece` component.
+     */
+    export type PieceProps<
+        TProps extends Record<string, any> = Record<string, any>,
+    > = {
+        /**
+         * The special property that contains the `CorePiece` instance to render, along with optional container 
+         * properties.
+         */
+        [piecePropsSymbol]: {
+            /**
+             * The `CorePiece` instance to render.
+             */
+            piece: CorePiece<TProps> | Promise<CorePiece<TProps>>;
+            /**
+             * Optional HTML attributes to set on the container element that wraps the piece.
+             */
+            containerProps?: HTMLAttributes<HTMLDivElement>;
+        };
+    };
+
+    /**
+     * Helper function to create the special property required by the `Piece` component.  The result of this function 
+     * is to be spread into the props of the `Piece` component.
+     * 
+     * @example
+     * ```svelte
+     * <Piece {...piece(myPiece, { onfocusin: focusInHandler })} foo="bar" count={42} />
+     * ```
+     * 
+     * @param piece The `CorePiece` instance to render.
+     * @param containerProps Optional HTML attributes to set on the container element that wraps the piece.
+     * @returns An object containing the special property to pass to the `Piece` component.
+     */
+    export function piece<
+        TProps extends Record<string, any> = Record<string, any>,
+    >(
+        piece: CorePiece<TProps> | Promise<CorePiece<TProps>>,
+        containerProps?: HTMLAttributes<HTMLDivElement>,
+    ) {
+        return {
+            [piecePropsSymbol]: {
+                piece,
+                containerProps,
+            },
+        };
+    }
+</script>
+
+<script
+    lang="ts"
+    generics="TProps extends Record<string, any> = Record<string, any>"
+>
+    import { getCollageContext } from "../collageContext.js";
+    import {
+        mountPiece,
+        type CorePiece,
+        type MountedPiece,
+        type MountPiece,
+    } from "@collagejs/core";
+    import { onMount } from "svelte";
+    import type { HTMLAttributes } from "svelte/elements";
+
+    type Props = TProps & PieceProps<TProps>;
+
+    let { ...restProps }: Props = $props();
+
+    const { piece: corePiece, containerProps } = $derived(restProps[piecePropsSymbol]);
+    let containerEl: HTMLDivElement;
+    let firstRun = true;
+    const ctx = getCollageContext();
+    let mountedPiece: MountedPiece<TProps> | undefined;
+
+    onMount(() => {
+        const mountPieceFn =
+            (ctx?.mountPiece as MountPiece<TProps>) ?? mountPiece<TProps>;
+        const mountPromise = mountPieceFn(corePiece, containerEl, restProps).then((mp) => {
+            mountedPiece = mp;
+        });
+        return async () => {
+            await mountPromise;
+            await mountedPiece?.unmount();
+            mountedPiece = undefined;
+        };
+    });
+
+    $effect(() => {
+        // Must be the first line so the dependency on restProps is tracked.
+        const newProps = { ...restProps };
+        delete (newProps as any)[piecePropsSymbol];
+        if (firstRun) {
+            firstRun = false;
+            return;
+        }
+        mountedPiece?.update(newProps);
+    });
+</script>
+
+<div bind:this={containerEl} {...containerProps}></div>
+
+<style>
+    div {
+        display: contents;
+    }
+</style>
+<!--
+@component
+
+### Piece Component
+
+Renders a CollageJS "piece" (micro-frontend) inside a Svelte application.  The piece itself may be built using any 
+valid framework or library, as long as it adheres to the *CollageJS* `CorePiece` interface.
+
+#### Props
+
+Properties passed to the `Piece` component must include a special property created using the `piece()` helper
+function. This property contains the `CorePiece` instance to render, along with optional container properties.  One can 
+also pass additional properties that will be forwarded to the mounted piece.
+
+If the mounted piece supports property updates, any changes to the additional properties will be propagated to the 
+piece reactively as per the rules of Svelte's reactivity system.
+
+#### Example Usage
+
+1. Import the `Piece` component and the `piece()` helper function from the library.
+2. Import whatever you need to get a hold of your `CorePiece` instance.  Normally, one imports a factory function that 
+creates the piece from a *bare module specifier* (an alias defined by your application's import map):
+    ```typescript
+    import Piece, { piece } from '@collagejs/svelte';
+    import { myPieceFactory } from '@my/bare-module-specifier';
+    ```
+3. Create a `CorePiece` instance using your factory function.  Pass whatever arguments the factory function requires.
+4. Render the `Piece` component in your Svelte template, passing the `CorePiece` instance using the `piece()` helper 
+function.  Also pass any additional properties that the piece supports:
+
+```svelte
+<Piece {...piece(myPieceFactory(), { class: 'my-piece-container' })} foo="bar" count={42} />
+```
+
+The above sets the `my-piece-container` CSS class on the container element that wraps the piece, and also passes the 
+`foo` and `count` properties to the mounted piece.  This example uses constant values in the properties, but you can 
+also pass stateful values that can update reactively, as if it were a regular Svelte component.
+
+> ⚠️ **IMPORTANT**:  Once a piece has unmounted, it cannot be remounted.  You must create a new `CorePiece` instance 
+> and `<Piece>` instance.  This is by design.  The easiest is to have the call to the factory function inside the 
+> Svelte template, so that a new `CorePiece` instance is created each time a new `<Piece>` instance is created.
+
+Online Documentation: Pending (https://collagejs.dev)
+-->

package/dist/Piece/Piece.svelte.d.ts

@@ -12,7 +12,7 @@ export type PieceProps<TProps extends Record<string, any> = Record<string, any>>
         /**
          * The `CorePiece` instance to render.
          */
-        piece: CorePiece<TProps>;
+        piece: CorePiece<TProps> | Promise<CorePiece<TProps>>;
         /**
          * Optional HTML attributes to set on the container element that wraps the piece.
          */
@@ -32,9 +32,9 @@ export type PieceProps<TProps extends Record<string, any> = Record<string, any>>
  * @param containerProps Optional HTML attributes to set on the container element that wraps the piece.
  * @returns An object containing the special property to pass to the `Piece` component.
  */
-export declare function piece<TProps extends Record<string, any> = Record<string, any>>(piece: CorePiece<TProps>, containerProps?: HTMLAttributes<HTMLDivElement>): {
+export declare function piece<TProps extends Record<string, any> = Record<string, any>>(piece: CorePiece<TProps> | Promise<CorePiece<TProps>>, containerProps?: HTMLAttributes<HTMLDivElement>): {
     [piecePropsSymbol]: {
-        piece: CorePiece<TProps>;
+        piece: CorePiece<TProps> | Promise<CorePiece<TProps>>;
         containerProps: HTMLAttributes<HTMLDivElement> | undefined;
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@collagejs/svelte",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Svelte v5 integration for the CollageJS micro-frontend library",
 	"author": {
 		"name": "José Pablo Ramírez Vargas",
@@ -25,6 +25,7 @@
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"test:unit": "vitest",
 		"test": "npm run test:unit -- --run",
+		"test:cicd": "npx playwright install && npm run test",
 		"test:e2e": "playwright test"
 	},
 	"files": [
@@ -46,8 +47,8 @@
 		}
 	},
 	"peerDependencies": {
-		"svelte": "^5.0.0",
-		"@collagejs/core": "^0.1.0"
+		"@collagejs/core": "0.x || 1.x",
+		"svelte": "^5.0.0"
 	},
 	"devDependencies": {
 		"@playwright/test": "^1.57.0",