xTabEvent

Shared cross-tab bus: trigger(type, data) for every mates app and library.

import { on, xTabEvent, MATES_XTAB_CHANNEL } from 'mates';

// Singleton bus — one BroadcastChannel ("mates:xtab") for the whole app
on((type, data) => {
  if (type === 'theme') {
    document.documentElement.dataset.theme = String(data);
  }
}, [xTabEvent]);

// Or __subscribe (auto-unsub on component unmount when a host exists)
xTabEvent.__subscribe((type, data) => {
  if (type === 'mates-db:sync') console.log('db table changed', data);
});

// Publish — other tabs + local handlers
xTabEvent.trigger('theme', 'dark');

MATES_XTAB_CHANNEL; // "mates:xtab"

Overview

xTabEvent is a singleton backed by one shared BroadcastChannel (mates:xtab / MATES_XTAB_CHANNEL). Use trigger(type, data?) to publish and __subscribe((type, data) => …) (or on(…, [xTabEvent])) to listen — including from other mates packages like mates-db.

Same-origin only. Payloads use the structured clone algorithm — plain objects / primitives, not functions or DOM nodes. Discriminate messages with a namespaced type string (e.g. mates-db:sync).

Unlike plain event().__subscribe, xTabEvent.__subscribe registers cleanup on the component host when one exists.

Compared to event()

API	Delivery	Notes
`event()`	In-process	Create typed channels per concern. Same JS context only.
`xTabEvent`	Cross-tab	One shared bus — filter by `type`. Falls back to local-only when BroadcastChannel is unavailable (SSR).

xTabEvent — cross-tab sync

Shared singleton bus — open the same page in two tabs and call xTabEvent.trigger(type, data) in one; every tab’s subscribers receive (type, data). The demo below runs in one preview tab.

import { html, atom, on, xTabEvent, renderApp } from 'mates';

const App = () => {

const log = atom(['Open this in another tab to see cross-tab sync']);

on((type, data) => {

if (type !== 'demo:ping') return;

const entry = `${type}: ${data} at ${new Date().toLocaleTimeString()}`;

log.set((prev) => [entry, ...prev.slice(0, 4)]);

}, [xTabEvent]);

return () => html`

<span class="tag tag-warning m-b-5">Cross-tab sync</span>

Shared <code>xTabEvent</code> bus — one BroadcastChannel for all mates apps.

</p>

</div>

<button class="btn-primary" @click=${() => xTabEvent.trigger('demo:ping', Date.now())}>

Ping all tabs

</button>

<span class="overline">Event log</span>

${log().map((e) => html`<div class="mono">${e}</div>`)}

</div>

};

renderApp(App, document.getElementById('app'));

Direct subscribe with auto-cleanup when a component host exists. Filter by type string.

import { html, atom, xTabEvent, renderApp } from 'mates';

const App = () => {

const last = atom('—');

// __subscribe auto-registers cleanup when a component host exists

xTabEvent.__subscribe((type, data) => {

if (type === 'demo:note') last.set(String(data));

});

return () => html`

<button class="btn-primary"

@click=${() => xTabEvent.trigger('demo:note', 'hello from this tab')}>

Broadcast note

</button>

</div>

};

renderApp(App, document.getElementById('app'));

API — xTabEvent

import { on, xTabEvent, MATES_XTAB_CHANNEL } from 'mates'

Prop / Option	Type	Default	Description
`xTabEvent`	`XTabEventType`	—	Singleton cross-tab bus. Channel name is fixed (`mates:xtab` / MATES_XTAB_CHANNEL). All mates apps and libraries share it.
`.trigger(type, data?)`	`void`	—	Broadcasts { type, data } to other tabs and notifies local subscribers with (type, data).
`.__subscribe(fn)`	`() => void`	—	fn(type, data). Auto-unsubscribes on component unmount when a host exists. Returns unsubscribe for manual cleanup.
`.close()`	`void`	—	Closes the BroadcastChannel and clears local handlers (tests / app teardown).
`MATES_XTAB_CHANNEL`	`"mates:xtab"`	—	Fixed BroadcastChannel name used by the singleton.

Compared to event()

Prop / Option	Type	Default	Description
`event()`	`EventType`	—	In-process only — create one channel per concern. No browser API overhead.
`xTabEvent`	`XTabEventType`	—	Cross-tab singleton — one bus for the origin; discriminate with type strings (e.g. mates-db:sync).