@collagejs/svelte 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# <img src="https://raw.githubusercontent.com/collagejs/core/HEAD/src/logos/collagejs-48.svg" alt="CollageJS Logo" width="48" height="48" align="left">&nbsp;@collagejs/svelte
+
+> Svelte v5 integration for the CollageJS micro-frontend library
+
+[Online Documentation](https://collagejs.dev)
+
+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
+
+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:
+
+```typescript
+// mfe.ts (or whatever name you wish for the file)
+import { buildPiece } from "@collagejs/svelte";
+// The component to wrap.  It usually is App.svelte.
+import App from "./App.svelte";
+
+export function myMfeFactory() {
+    return buildPiece(App /*, { options } */);
+}
+```
+
+> ✨ **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
+
+We can mount *CollageJS* pieces created in any technology in Svelte projects by using the `<Piece>` component.  This component requires that we pass the `CorePiece` object that we wish to mount.  Any other properties given to `<Piece>` are forwarded to the mounted `CorePiece` object:
+
+```svelte
+<script lang="ts">
+    import { Piece, piece } from "@collagejs/svelte";
+    import { myMfeFactory } from "@my/bare-module-specifier";
+</script>
+
+<Piece {...piece(myMfeFactory())} extra="yes" data={true} />
+```
+
+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.

package/dist/Piece/Piece.svelte

@@ -0,0 +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)
+-->

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

@@ -0,0 +1,108 @@
+declare const piecePropsSymbol: unique 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 declare function piece<TProps extends Record<string, any> = Record<string, any>>(piece: CorePiece<TProps>, containerProps?: HTMLAttributes<HTMLDivElement>): {
+    [piecePropsSymbol]: {
+        piece: CorePiece<TProps>;
+        containerProps: HTMLAttributes<HTMLDivElement> | undefined;
+    };
+};
+import { type CorePiece } from "@collagejs/core";
+import type { HTMLAttributes } from "svelte/elements";
+declare function $$render<TProps extends Record<string, any> = Record<string, any>>(): {
+    props: TProps & PieceProps<TProps>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TProps extends Record<string, any> = Record<string, any>> {
+    props(): ReturnType<typeof $$render<TProps>>['props'];
+    events(): ReturnType<typeof $$render<TProps>>['events'];
+    slots(): ReturnType<typeof $$render<TProps>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TProps extends Record<string, any> = Record<string, any>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TProps>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TProps>['props']>, ReturnType<__sveltets_Render<TProps>['events']>, ReturnType<__sveltets_Render<TProps>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TProps>['bindings']>;
+    } & ReturnType<__sveltets_Render<TProps>['exports']>;
+    <TProps extends Record<string, any> = Record<string, any>>(internal: unknown, props: ReturnType<__sveltets_Render<TProps>['props']> & {}): ReturnType<__sveltets_Render<TProps>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * ### 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)
+ */
+declare const Piece: $$IsomorphicComponent;
+type Piece<TProps extends Record<string, any> = Record<string, any>> = InstanceType<typeof Piece<TProps>>;
+export default Piece;

package/dist/collageContext.d.ts

@@ -0,0 +1,15 @@
+import type { CollageContext } from "./types.js";
+/**
+ * Defines the context key used to store the parent-aware `mountPiece()` function.
+ */
+export declare const contextKey: unique symbol;
+/**
+ * Obtains the *CollageJS* context, which is an object that contains the parent-aware `mountPiece()` function.
+ * @returns The stored *CollageJS* context.
+ */
+export declare function getCollageContext(): CollageContext;
+/**
+ * Sets the *CollageJS* context, which is an object that contains the parent-aware `mountPiece()` function.
+ * @param context The *CollageJS* context to store.
+ */
+export declare function setCollageContext(context: CollageContext): void;

package/dist/collageContext.js

@@ -0,0 +1,20 @@
+import { getContext, setContext } from "svelte";
+/**
+ * Defines the context key used to store the parent-aware `mountPiece()` function.
+ */
+export const contextKey = Symbol();
+/**
+ * Obtains the *CollageJS* context, which is an object that contains the parent-aware `mountPiece()` function.
+ * @returns The stored *CollageJS* context.
+ */
+export function getCollageContext() {
+    return getContext(contextKey);
+}
+;
+/**
+ * Sets the *CollageJS* context, which is an object that contains the parent-aware `mountPiece()` function.
+ * @param context The *CollageJS* context to store.
+ */
+export function setCollageContext(context) {
+    setContext(contextKey, context);
+}

package/dist/collagejs/collage.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentOperationOptions } from "../types.js";
+import { type MountProps } from "@collagejs/core";
+import { mount, unmount, type Component } from "svelte";
+/**
+ * Creates a `buildPiece` function for Svelte v5 components.
+ * @param mountFn Svelte's mount() function (or a substitute).
+ * @param unmountFn Svelte's unmount() function (or a substitute).
+ * @returns A `buildPiece` function that uses the given mounting and unmounting functions.
+ */
+export declare function buildPieceFactory(mountFn?: typeof mount, unmountFn?: typeof unmount): <TProps extends Record<string, any> = Record<string, any>>(component: Component<TProps>, options?: ComponentOperationOptions<TProps>) => {
+    mount: (target: HTMLElement, props?: MountProps<TProps> | undefined) => Promise<() => Promise<void>>;
+    update: (newProps: TProps) => Promise<void>;
+};

package/dist/collagejs/collage.svelte.js

@@ -0,0 +1,75 @@
+import { contextKey } from "../collageContext.js";
+import { mountPieceKey } from "@collagejs/core";
+import { mount, unmount } from "svelte";
+/**
+ * Class used to track instances.
+ */
+class SveltePiece {
+    props = $state({});
+    target;
+    instance;
+}
+/**
+ * Creates a `buildPiece` function for Svelte v5 components.
+ * @param mountFn Svelte's mount() function (or a substitute).
+ * @param unmountFn Svelte's unmount() function (or a substitute).
+ * @returns A `buildPiece` function that uses the given mounting and unmounting functions.
+ */
+export function buildPieceFactory(mountFn = mount, unmountFn = unmount) {
+    return function (component, options) {
+        if (!component) {
+            throw new Error('No component was given to the function.');
+        }
+        if (options?.mount?.target) {
+            console.warn("Specifying the 'target' mount option has no effect.");
+        }
+        const thisValue = new SveltePiece();
+        async function mountComponent(target, props) {
+            this.target = target;
+            await options?.preMount?.(this.target);
+            // Don't lose any potential incoming context.
+            let context = options?.mount?.context ?? new Map();
+            context.set(contextKey, {
+                mountPiece: props?.[mountPieceKey]
+            });
+            delete props?.[mountPieceKey];
+            const mergedProps = {
+                ...options?.mount?.props,
+                ...props
+            };
+            for (let key in mergedProps) {
+                this.props[key] = mergedProps[key];
+            }
+            this.instance = mountFn(component, {
+                ...options?.mount,
+                context,
+                target: this.target,
+                props: this.props
+            });
+            return async () => {
+                if (!this.instance) {
+                    throw new Error('Cannot unmount:  There is no component to unmount.');
+                }
+                await unmountFn(this.instance, options?.unmount);
+                await options?.postUnmount?.(this.target);
+                this.instance = undefined;
+                this.target = undefined;
+                this.props = {};
+            };
+        }
+        function updateComponent(newProps) {
+            if (!this.instance) {
+                return Promise.reject(new Error('Cannot update:  No component has been mounted.'));
+            }
+            for (let key in newProps) {
+                this.props[key] = newProps[key];
+            }
+            // TODO: Perhaps we need await tick() here?
+            return Promise.resolve();
+        }
+        return {
+            mount: mountComponent.bind(thisValue),
+            update: updateComponent.bind(thisValue)
+        };
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { default as Piece } from './Piece/Piece.svelte';
+export * from './Piece/Piece.svelte';
+/**
+ * Creates a `CorePiece`-compliant object from a Svelte component.
+ * @param component The Svelte component to wrap.
+ * @param options Optional options object for additional features and configuration of the mount/unmount process.
+ * @returns A `CorePiece`-compliant object that wraps the given Svelte component.
+ */
+export declare const buildPiece: <TProps extends Record<string, any> = Record<string, any>>(component: import("svelte").Component<TProps>, options?: import("./types.ts").ComponentOperationOptions<TProps>) => {
+    mount: (target: HTMLElement, props?: import("@collagejs/core").MountProps<TProps> | undefined) => Promise<() => Promise<void>>;
+    update: (newProps: TProps) => Promise<void>;
+};

package/dist/index.js

@@ -0,0 +1,10 @@
+import { buildPieceFactory } from "./collagejs/collage.svelte.js";
+export { default as Piece } from './Piece/Piece.svelte';
+export * from './Piece/Piece.svelte';
+/**
+ * Creates a `CorePiece`-compliant object from a Svelte component.
+ * @param component The Svelte component to wrap.
+ * @param options Optional options object for additional features and configuration of the mount/unmount process.
+ * @returns A `CorePiece`-compliant object that wraps the given Svelte component.
+ */
+export const buildPiece = buildPieceFactory();

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+import type { MountOptions, unmount } from "svelte";
+import type { MountPiece } from "@collagejs/core";
+/**
+ * Options for Svelte's `mount()` function.
+ */
+export type SvelteMountOptions<TProps extends Record<string, any> = Record<string, any>> = Omit<MountOptions<TProps>, 'target'>;
+/**
+ * Options given to the lifecycle-creation function.
+ */
+export type ComponentOperationOptions<TProps extends Record<string, any> = Record<string, any>> = {
+    /**
+     * Optional function to be run immediately before Svelte mounts the component.
+     *
+     * An error thrown from this function will make the mount promise to reject.
+     * @param target HTML element where the Svelte component will be mounted in.
+     */
+    preMount?: (target: HTMLElement) => Promise<void> | void;
+    /**
+     * Optional function to be run immediately after Svelte unmounts the component.
+     *
+     * An error thrown from this function will make the unmount promise to reject.
+     * @param target HTML element where the Svelte component was mounted in.
+     */
+    postUnmount?: (target: HTMLElement) => Promise<void> | void;
+    /**
+     * Optional options for Svelte's `mount()` function.  Refer to Svelte's `mount()` function documentation for
+     * information about each option.
+     */
+    mount?: SvelteMountOptions<TProps>;
+    /**
+     * Optional options for Svelte's `unmount()` function.  Refer to Svelte's `unmount()` function documentation for
+     * information about each option.
+     */
+    unmount?: Parameters<typeof unmount>[1];
+};
+export type CollageContext = {
+    mountPiece: MountPiece;
+};

package/dist/types.js

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

package/package.json

@@ -0,0 +1,77 @@
+{
+	"name": "@collagejs/svelte",
+	"version": "0.1.0",
+	"description": "Svelte v5 integration for the CollageJS micro-frontend library",
+	"author": {
+		"name": "José Pablo Ramírez Vargas",
+		"email": "webJose@gmail.com",
+		"url": "https://github.com/webJose"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/collagejs/svelte.git"
+	},
+	"bugs": {
+		"url": "https://github.com/collagejs/svelte/issues"
+	},
+	"homepage": "https://collagejs.dev",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && npm run prepack",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"prepack": "svelte-kit sync && svelte-package && publint",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"test:unit": "vitest",
+		"test": "npm run test:unit -- --run",
+		"test:e2e": "playwright test"
+	},
+	"files": [
+		"dist",
+		"!dist/testing",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"svelte": "^5.0.0",
+		"@collagejs/core": "^0.1.0"
+	},
+	"devDependencies": {
+		"@playwright/test": "^1.57.0",
+		"@sveltejs/adapter-auto": "^7.0.0",
+		"@sveltejs/kit": "^2.49.1",
+		"@sveltejs/package": "^2.5.7",
+		"@sveltejs/vite-plugin-svelte": "^6.2.1",
+		"@vitest/browser-playwright": "^4.0.15",
+		"playwright": "^1.57.0",
+		"publint": "^0.3.15",
+		"svelte": "^5.45.6",
+		"svelte-check": "^4.3.4",
+		"typescript": "^5.9.3",
+		"vite": "^7.2.6",
+		"vitest": "^4.0.15",
+		"vitest-browser-svelte": "^2.0.1"
+	},
+	"keywords": [
+		"svelte",
+		"collage",
+		"collage-js",
+		"collagejs",
+		"micro-frontend",
+		"mfe",
+		"single-spa"
+	]
+}