@echothink-ui/events

The backend-event contract for @echothink-ui components.

@echothink-ui components expose plain React callbacks (onClick, EthAction.onSelect, form onSubmit, table rowActions) with no path to a backend process. This package provides the serializable binding shape and the host-injected dispatch that carry those events to a backend (ultimately runProcess → gateway), while staying structurally compatible with the echothink-fugue registry EventBinding / action-graph contract.

Pieces

• EthEventBinding / EthAction — the serializable "when this event fires, run these actions" shape a builder authors. Action kinds: runProcess, navigate, setState, openModal, closeModal, showToast.
• EchoEventProvider — the host injects a dispatch(binding, payload, data) implementation here. A no-op default lets components render with no provider.
• useEchoEvents() — returns { dispatch }.
• useEthAction(binding) — returns an onSelect/onClick handler to wire EthAction.onSelect → dispatch (or undefined when unbound).
• useEthEventHandler(binding) — returns a payload-carrying handler for events that produce live data (form values, selected row, chosen rowAction).
• toRegistryEventBinding(binding) — the edge adapter that renames the authoring shape (kind/payload/target) to the registry action-graph shape (action/externalInput/route/modalId/key).

Usage

import {
  EchoEventProvider,
  useEthAction,
  toRegistryEventBinding,
  type EthEventBinding,
} from "@echothink-ui/events";

// Host wires dispatch to the registry/renderer action runtime:
const dispatch = (binding, payload) => {
  const reg = toRegistryEventBinding(binding);
  pageRuntime.dispatch([reg], binding.event, { row: payload });
};

<EchoEventProvider dispatch={dispatch}>
  <MyPage />
</EchoEventProvider>;

// Component wires a rich callback to a backend binding:
function ArchiveButton({ binding }: { binding?: EthEventBinding }) {
  const onSelect = useEthAction(binding);
  return <Button onClick={onSelect}>Archive</Button>;
}

See ../echothink-UI-components/docs/backend-events.md for the full design.