Embedding the components

Four custom elements bring slotting into your own pages:

They are standard custom elements in one ES module, with no framework runtime, so they work in plain HTML and in Angular, React, Vue, Svelte and every other framework. The station, the setup editor and the monitor call the install's API themselves (api-base); the wall draws what you give it, and calls the API only to show the lights.

Loading the script#

One ES module defines all four components. Your install serves it at two URLs, both with Access-Control-Allow-Origin: *:

For this install (version 1.0.0), with its Subresource Integrity hash:

<script type="module" src="https://slotting.internal.example/widget/1.0.0/slotting-components.js"
        integrity="sha384-1hTDsE/7ThzvFzX8J+xwUx0AjF16gdOWnKgPbt25wtRtY34ViTnLgJWgo3mfCZpU" crossorigin="anonymous"></script>

Replace the host with your install's. The hash belongs to this version: after an upgrade, take the new one from these pages on the upgraded install, or compute it from the versioned URL:

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

• Where the components send their requests. api-base defaults to the origin the script was loaded from, so components loaded from the install talk to the install. Set api-base to send them elsewhere, for example to your reverse proxy.
• Pages on another origin. When your page (for example https://wms.example.internal) is not served by the install, the browser only lets the components call the API if the install allows that origin, and the install refuses changes from origins it doesn't know (403 origin_not_allowed): set SLOTTING_CORS_ORIGINS=https://wms.example.internal (configuration). Alternatively, proxy /api and /v1/info through your own server and set api-base to it. A proxy that lets only some routes through must allow what the operator components call: GET /v1/info, GET /api/waves/{waveId}, .../pending and .../orders/{orderId}, GET /api/layouts/{layoutId}, .../bins and .../lights, and POST /api/waves/{waveId}/scan, .../undo and .../confirm (the wall's simulate-buttons also POST /api/lights/press).
• Content-Security-Policy. The components work under a strict CSP with no 'unsafe-inline' or 'unsafe-eval': they use constructed stylesheets in their shadow roots and set no inline styles. Allow the install in script-src and, for the API components, connect-src: script-src 'self' https://slotting.internal.example; connect-src https://slotting.internal.example; style-src 'self'.
• Types. The declarations are served next to the script at /widget/1.0.0/slotting-components.d.ts. Copy the file into your frontend's sources to type the elements, their properties and events.

The station#

<slotting-station wave-id="WAVE-0815" operator="station-1"></slotting-station>

• Scanners. The scan field keeps the focus and takes keyboard-wedge input: the scanner types the code and Enter (or Tab). Several codes separated by line breaks work too. A quantity field next to it sends several units with one scan.
• The answer. The target bin is shown very large, highlighted on the wall drawing, with the order's progress. When the scan completes the order, the station lists the order's bins.
• Errors are shown so the operator knows what to do: put the unit aside (not in the wave, fully slotted, no bin free, too large), retry (offline, no answer, busy), or a general error. Scans run one at a time, in order; each has its own scanId, so Retry after "offline" can never put a unit twice.
• Undo reverts the last successful scan.
• Methods: scan(sku, quantity?) scans as if the scanner sent the code; undo(); focus(). Read-only: wave (the wave as loaded, updated by every scan), lastResult and pendingConfirmation (below).

const station = document.querySelector('slotting-station');
station.addEventListener('put', e => console.log(`put ${e.detail.sku} into ${e.detail.bin.id}`));
station.addEventListener('order-complete', e => console.log(`order ${e.detail.orderId} complete:`, e.detail.bins.map(b => b.id)));
station.addEventListener('scan-error', e => {
    if (e.detail.kind === 'aside') {
        console.warn(`put ${e.detail.sku} aside: ${e.detail.message}`);
    }
});

Confirmed puts at the station#

In a wave with confirmPuts (Confirmed puts) the station asks for the bin scan by itself; nothing changes in your page:

1. The operator scans an item. The target bin is shown with Scan bin A-01-01 to confirm (parts target-pending and confirm-prompt, colour --sl-target-pending).
2. The operator puts the unit in and scans the bin's label. The station sends it to POST /api/waves/{waveId}/confirm, shows the put as confirmed (part target-confirmed) and fires confirm. A put split over several bins asks for each bin in turn.
3. A wrong bin shows "Wrong bin" with the bin to use, and the station keeps waiting (scan-error with code wrong_bin).
4. An item scanned meanwhile is not sent: the station asks to confirm the put first, or to press Undo (scan-error with code confirm_first).
5. The confirmation of the order's last put fires order-complete and lists the order's bins.

After a reload of the page, the station picks up where it was: it reads the wave's pending puts (GET /api/waves/{waveId}/pending) and asks again for the oldest one of its operator (of anyone, without operator). It reads them again each time a put is fully confirmed, so a put whose scan answer never reached the station (a timeout, then the operator scanned the next unit) is asked for next instead of staying pending. If the operator presses the bin's light button instead of scanning the label, the station notices it (it polls the light state every 1.5 seconds while a put is pending) and goes on. pendingConfirmation is the put waiting for its bin scan: { scanId, waveId, orderId, sku, quantity, bins, result }, with bins the bins still to confirm; null otherwise.

station.addEventListener('confirm', e => console.log(`confirmed ${e.detail.bin.id} for ${e.detail.orderId}`));

The wall#

<slotting-wall wall-id="A" order-id="ORD-1001"></slotting-wall>

Set layout (the layout JSON, from GET /api/layouts/{layoutId}) and bins (the occupancy, from GET /api/layouts/{layoutId}/bins) as properties, not attributes. The wall is drawn to the element's width, its height capped by --sl-wall-height.

Clicking a bin fires bin-select with { binId, wallId, bin, state }.

Lights on the wall#

<slotting-wall lights simulate-buttons wall-id="A"></slotting-wall>

With lights, the wall polls GET {api-base}/api/layouts/{layout-id}/lights (the light state) and shows the lit bins: put pulsing in --sl-light-put with the quantity, complete steady in --sl-light-complete (steady, with a thicker outline, for users who prefer reduced motion). It pauses while the page is hidden, stops when the element is removed, and backs off when the install can't be reached (the message is in part lights-status). Without lights the wall never calls the API.

With simulate-buttons, a click on a lit bin (or Enter or Space on it) presses its button, as a light module would: POST /api/lights/press, which confirms the bin's pending put or releases its complete order (Button presses). Then it fires light-press with { layoutId, binId, wallId, address, state, result, error }: result is the press route's answer, or error ({ status, code, message }) when it failed, for example not_pending. A press the server ignored (result.action ignored: it repeated a press of a moment ago) is not an error. While a bin's press is in flight, and for one second after its answer, further clicks and keys on that bin are ignored, so a double click doesn't confirm the next put or release the order. Use it as a simulator, or as a touch-screen alternative to the buttons. lightStates is the light state of the last poll.

The setup editor#

<slotting-setup layout-id="PUTWALL-A"></slotting-setup>

With layout-id, the editor loads that layout and Save replaces it (PUT); without it, Save creates a new layout (POST). Users import walls (a DXF or CSV file, a grid form, or a photo with their measurements), see them on the wall drawing, edit the bins in a table, validate and save. Files are read in the browser and sent to the install as JSON; imports return drafts and never save. The photo import is disabled, with an explanation, when the install has no AI provider configured (Bin setups).

• The bin table has a Light address column for put-to-light: empty means the bin id.
• Properties and methods: layout (the draft, a copy; setting it replaces the draft), validate() (returns the problems and shows them), save() (validates and saves; resolves with the saved layout).
• Events: layout-imported ({ source, layout, warnings }) and layout-saved ({ layout, created }).

The wave monitor#

<slotting-wave-monitor wave-id="WAVE-0815" interval="5000"></slotting-wave-monitor>

Shows the wave's stats, its walls with the held bins and the list of orders with a status filter. It polls GET /api/waves/{waveId} every interval milliseconds (default 3000, at least 1000) while the page is visible, until the wave is closed. refresh() polls at once; every poll fires wave-update with the wave. layout-id is needed only when two layouts have a wave with the same id.

Events#

All events are CustomEvents that bubble and are composed, so a listener on document sees them too.

License#

The components that call the API read GET {api-base}/v1/info (cached for 10 minutes) and:

• on an evaluation license, show a TRIAL mark;
• when the install is not licensed (expired, missing or invalid), show a neutral "not licensed, contact your administrator" notice instead of their content (part blocked). The API answers 402 anyway;
• when /v1/info can't be reached, work normally (they fail open; the API decides).

After installing a license key, clearInstallInfo() (exported by the module) makes the next component ask again.

Frameworks#

The pattern is the same everywhere: load the script once, let the framework pass the custom elements through, set object values (layout, bins, highlight) as DOM properties, set the rest as attributes, and listen to the events.

• Plain HTML: as above. Nothing else is needed.

• Angular: add CUSTOM_ELEMENTS_SCHEMA to the standalone component (or module) that uses them; bind properties with [layout]="layout" and events with (order-complete)="onComplete($event)".

• React 19: custom elements work as they are; React sets object props as properties. Type the tags with the helper in the declarations:

  ts

  import type { SlottingIntrinsicElements } from './slotting-components';
  declare module 'react' {
      namespace JSX {
          interface IntrinsicElements extends SlottingIntrinsicElements {}
      }
  }

  Events with dashes (order-complete) need a ref and addEventListener in a useEffect.

• Vue 3: tell the compiler the tags are custom elements (compilerOptions.isCustomElement: tag => tag.startsWith('slotting-') in the Vue plugin options), bind objects with .prop (:layout.prop="layout") and listen with @order-complete.

• Svelte: works as it is: <slotting-station wave-id={waveId} bind:this={station} /> sets attributes and properties; listen to the events with station.addEventListener('order-complete', ...) (or on:order-complete in Svelte 4).