Embedding the components

<script type="module" src="https://cartonization.internal.example/widget/1.0.0/cartonization-components.js"
        integrity="sha384-IY2t1rFsgll1gbkYp9AID/GajBy2fLKHFBMc8EjjMqft4DYUgwKM/OQWge93UbcZ" crossorigin="anonymous"></script>

curl -s https://cartonization.internal.example/widget/1.0.0/cartonization-components.js | openssl dgst -sha384 -binary | openssl base64 -A

<!-- Your own order form and button. The components only display the result your backend returns. -->
<form id="order-form" class="order">
    <label>Order <input id="order-id" name="orderId" value="SO-1001" required></label>
    <table>
        <thead>
        <tr><th>SKU</th><th>Quantity</th></tr>
        </thead>
        <tbody>
        <tr><td><input id="line-sku-0" value="BOOK" aria-label="SKU, line 1"></td><td><input id="line-qty-0" type="number" min="1" max="1000" value="6" required aria-label="Quantity, line 1"></td></tr>
        <tr><td><input id="line-sku-1" value="MUG" aria-label="SKU, line 2"></td><td><input id="line-qty-1" type="number" min="1" max="1000" value="4" required aria-label="Quantity, line 2"></td></tr>
        <tr><td><input id="line-sku-2" value="LAMP" aria-label="SKU, line 3"></td><td><input id="line-qty-2" type="number" min="1" max="1000" value="1" required aria-label="Quantity, line 3"></td></tr>
        <tr><td><input id="line-sku-3" value="CABLE" aria-label="SKU, line 4"></td><td><input id="line-qty-3" type="number" min="1" max="1000" value="8" required aria-label="Quantity, line 4"></td></tr>
        <tr><td><input id="line-sku-4" value="LIGHTER-FLUID" aria-label="SKU, line 5"></td><td><input id="line-qty-4" type="number" min="1" max="1000" value="4" required aria-label="Quantity, line 5"></td></tr>
        </tbody>
    </table>
    <button id="cartonize" type="submit">Cartonize</button>
    <p id="cartonize-status" class="status" role="status" data-state="idle"></p>
</form>

<!-- One group: the 3D view and the container list stay in sync, and so do the components in the info panel. -->
<cartonization-3d-view id="station-3d" group="station"></cartonization-3d-view>
<cartonization-containers id="station-containers" group="station"></cartonization-containers>

<section id="info-panel" hidden>
    <cartonization-summary id="info-summary" group="station"></cartonization-summary>
    <cartonization-ranking id="info-ranking" group="station"></cartonization-ranking>
</section>

<!-- The components, from your cartonization install. In production pin the versioned URL (/widget/<version>/...) and add
     integrity="sha384-..." crossorigin="anonymous" (see the docs at /docs/embedding.html on your install). -->
<script type="module" src="http://127.0.0.1:10081/widget/cartonization-components.js"></script>
<script type="module" src="app.js"></script>

// Same URL as the <script> in index.html, so the browser loads the module once and the page has one set of groups.
import { getGroup } from 'http://127.0.0.1:10081/widget/cartonization-components.js';

/** Your backend (examples/backend-node or backend-java). It builds the request, calls POST /api/pack and returns the response. */
const BACKEND_URL = 'http://127.0.0.1:3001';

const station = getGroup('station');
const form = document.getElementById('order-form');
const button = document.getElementById('cartonize');
const status = document.getElementById('cartonize-status');
const selected = document.getElementById('selected-container');
const toggle = document.getElementById('info-toggle');
const panel = document.getElementById('info-panel');

function showStatus(state, text) {
    status.dataset.state = state;
    status.textContent = text;
}

/** The order as your backend expects it: { orderId, lines: [{ sku, quantity }] }. Lines with no SKU are skipped. */
function readOrder() {
    const lines = [...form.querySelectorAll('tbody tr')]
        .map(row => row.querySelectorAll('input'))
        .map(([sku, quantity]) => ({ sku: sku.value.trim(), quantity: quantity.valueAsNumber }))
        .filter(line => line.sku !== '');
    return { orderId: document.getElementById('order-id').value.trim(), lines };
}

// The user clicks your button; your backend packs the order; the page hands the response to the components.
form.addEventListener('submit', async event => {
    event.preventDefault();
    button.disabled = true;
    showStatus('loading', 'Cartonizing...');
    try {
        const res = await fetch(`${BACKEND_URL}/api/cartonize`, {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify(readOrder()),
        });
        const body = await res.json().catch(() => ({}));
        if (!res.ok) {
            throw new Error(body.error ?? `HTTP ${res.status}`);
        }
        // Setting the result on the group updates every component in it and selects the best solution and container #1.
        station.setResult(body);
        const first = body.best.containers[0];
        selected.textContent = first ? `Pack container #1: ${first.containerId}` : 'Nothing to pack.';
        showStatus('done', `Packed ${body.best.metrics.packedUnits} units into ${body.best.metrics.containerCount} container(s).`);
    }
    catch (err) {
        // Clear the group, so the components don't keep showing the previous order's packing.
        station.setResult(null);
        selected.textContent = 'No packing.';
        showStatus('error', `Could not cartonize: ${err.message}`);
    }
    finally {
        button.disabled = false;
    }
});

// Import from the same URL as the <script> tag, so the page has one copy of the module (and of its groups).
import { getGroup } from 'https://cartonization.internal.example/widget/1.0.0/cartonization-components.js';

const group = getGroup('station');
group.setResult(packing);                          // like setting `result` on any element of the group; null clears it
group.select({ algorithm: 'extreme-points' });     // false if the result has no such solution
group.select({ container: 2 });
const unsubscribe = group.subscribe(state => console.log(state.selectedAlgorithm, state.selectedContainer));

// The components' events bubble out of their shadow roots, so one listener on the document sees them all.
document.addEventListener('cw-container-select', e => {
    selected.textContent = `Pack container #${e.detail.index}: ${e.detail.containerId}`;
});

cartonization-3d-view, cartonization-containers, cartonization-summary, cartonization-ranking {
    --cw-accent: #0f766e;
    --cw-3d-height: 520px;
}

cartonization-ranking::part(row winner) {
    background: #ccfbf1;
}

// Load the components from your cartonization install (another origin). In production, pin the versioned URL
// (/widget/<version>/cartonization-components.js), which is cacheable for a year.
const script = document.createElement('script');
script.type = 'module';
script.src = `${CARTONIZATION_URL}/widget/cartonization-components.js`;
document.head.append(script);

<!-- Set the result on one element of the group: every component with group="station" shows it. -->
<cartonization-3d-view id="station-3d" group="station" [result]="packing()"></cartonization-3d-view>
<cartonization-containers id="station-containers" group="station" (cw-container-select)="onContainerSelect($event)"></cartonization-containers>

<!-- Created when opened: components attached later show the group's current state. -->
@if (infoOpen()) {
    <section class="info">
        <cartonization-summary id="info-summary" group="station"></cartonization-summary>
        <cartonization-ranking id="info-ranking" group="station"></cartonization-ranking>
    </section>
}

<section class="solo">
    <h2>3D only (standalone, container 1)</h2>
    <cartonization-3d-view id="solo-3d" container="1" [result]="packing()"></cartonization-3d-view>
</section>

/** The user clicked Cartonize: your backend packs the order, and the response goes to the components unchanged. */
protected cartonize(event: Event) {
    event.preventDefault();
    const order = { orderId: this.orderId().trim(), lines: this.lines().map(l => ({ ...l, sku: l.sku.trim() })).filter(l => l.sku !== '') };
    this.status.set({ state: 'loading', text: 'Cartonizing...' });
    this.http.post<PackResponse>(`${BACKEND_URL}/api/cartonize`, order).subscribe({
        next: packing => {
            // A new result selects the best solution and container #1 in the whole group.
            this.packing.set(packing);
            const first = packing.best.containers[0];
            this.selected.set(first ? `Pack container #1: ${first.containerId}` : 'Nothing to pack.');
            this.status.set({ state: 'done', text: `Packed ${packing.best.metrics.packedUnits} units into ${packing.best.metrics.containerCount} container(s).` });
        },
        error: (err: HttpErrorResponse) => {
            // Clear the components, so they don't keep showing the previous order's packing.
            this.packing.set(null);
            this.selected.set('No packing.');
            this.status.set({ state: 'error', text: `Could not cartonize: ${err.error?.error ?? err.message}` });
        },
    });
}

/** Angular types custom-element events as Event; the .d.ts gives the detail's type. */
protected onContainerSelect(event: Event) {
    const { detail } = event as CartonizationEventMap['cw-container-select'];
    this.selected.set(`Pack container #${detail.index}: ${detail.containerId}`);
}

// Lets TSX use the <cartonization-*> elements with their attributes and typed refs.
import type { DetailedHTMLProps, HTMLAttributes } from 'react';

import type { Cartonization3DView, CartonizationContainers, CartonizationRanking, CartonizationSummary } from './cartonization-components';

type ElementProps<E extends HTMLElement> = DetailedHTMLProps<HTMLAttributes<E>, E> & { group?: string };

declare module 'react' {
    namespace JSX {
        interface IntrinsicElements {
            'cartonization-summary': ElementProps<CartonizationSummary>;
            'cartonization-ranking': ElementProps<CartonizationRanking>;
            'cartonization-containers': ElementProps<CartonizationContainers>;
            'cartonization-3d-view': ElementProps<Cartonization3DView> & { container?: string };
        }
    }
}

// `result` is an object, so set it as a property through a ref. React 19 assigns a prop as a property only when the element
// already has it at render time; the components load asynchronously from another origin, so on the first render they aren't
// defined yet and React would set a string attribute instead. A ref works either way. Setting it on one element of the
// group updates the whole group.
useEffect(() => {
    stationRef.current!.result = packing;
    soloRef.current!.result = packing;
}, [packing]);

// Custom events: add them with addEventListener. The .d.ts types the event's detail.
useEffect(() => {
    const containers = containersRef.current!;
    const onSelect = (e: CustomEvent<ContainerSelectDetail>) => setSelected(`Pack container #${e.detail.index}: ${e.detail.containerId}`);
    containers.addEventListener('cw-container-select', onSelect);
    return () => containers.removeEventListener('cw-container-select', onSelect);
}, []);

<cartonization-3d-view ref={stationRef} id="station-3d" group="station" />
<cartonization-containers ref={containersRef} id="station-containers" group="station" />

{/* Mounted when opened: components attached later show the group's current state. */}
{infoOpen && (
    <section className="info">
        <cartonization-summary id="info-summary" group="station" />
        <cartonization-ranking id="info-ranking" group="station" />
    </section>
)}

<section className="solo">
    <h2>3D only (standalone, container 1)</h2>
    <cartonization-3d-view ref={soloRef} id="solo-3d" container="1" />
</section>

/** Your backend packs the order; a non-2xx response carries { error } with a message for the user. */
async function cartonize(orderId: string, lines: OrderLine[]): Promise<PackResponse> {
    const res = await fetch(`${BACKEND_URL}/api/cartonize`, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ orderId, lines }),
    });
    const body = await res.json().catch(() => ({}));
    if (!res.ok) {
        throw new Error((body as { error?: string }).error ?? `HTTP ${res.status}`);
    }
    return body as PackResponse;
}

vue({
    template: {
        // Tell the Vue compiler that <cartonization-*> are custom elements, not Vue components.
        compilerOptions: { isCustomElement: tag => tag.startsWith('cartonization-') },
    },
}),

<!-- .prop sets the DOM property: an object can't be an attribute. Setting it on one element of the group updates the group. -->
<cartonization-3d-view id="station-3d" group="station" :result.prop="packing"/>
<cartonization-containers id="station-containers" group="station" @cw-container-select="onContainerSelect"/>

<!-- Created when opened: components attached later show the group's current state. -->
<section v-if="infoOpen" class="info">
    <cartonization-summary id="info-summary" group="station"/>
    <cartonization-ranking id="info-ranking" group="station"/>
</section>

<section class="solo">
    <h2>3D only (standalone, container 1)</h2>
    <cartonization-3d-view id="solo-3d" container="1" :result.prop="packing"/>
</section>

// The user clicked Cartonize: your backend packs the order, and the response goes to the components unchanged.
async function cartonize() {
    status.value = { state: 'loading', text: 'Cartonizing...' };
    try {
        const res = await fetch(`${BACKEND_URL}/api/cartonize`, {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify({
                orderId: orderId.value.trim(),
                lines: lines.value.map(l => ({ sku: l.sku.trim(), quantity: l.quantity })).filter(l => l.sku !== ''),
            }),
        });
        const body = await res.json().catch(() => ({}));
        if (!res.ok) {
            throw new Error((body as { error?: string }).error ?? `HTTP ${res.status}`);
        }
        // A new result selects the best solution and container #1 in the whole group.
        const result = body as PackResponse;
        packing.value = result;
        const first = result.best.containers[0];
        selected.value = first ? `Pack container #1: ${first.containerId}` : 'Nothing to pack.';
        status.value = { state: 'done', text: `Packed ${result.best.metrics.packedUnits} units into ${result.best.metrics.containerCount} container(s).` };
    }
    catch (err) {
        // Clear the components, so they don't keep showing the previous order's packing.
        packing.value = null;
        selected.value = 'No packing.';
        status.value = { state: 'error', text: `Could not cartonize: ${(err as Error).message}` };
    }
}

function onContainerSelect(event: Event) {
    const { detail } = event as CartonizationEventMap['cw-container-select'];
    selected.value = `Pack container #${detail.index}: ${detail.containerId}`;
}