@iof/embedded-ux-kit

`@iof/embedded-ux-kit`

React component library backing the IOF Widgets platform. Use this package to embed IOF widgets directly in a React / Next.js application without the iframe boundary.

Installation

pnpm add @iof/embedded-ux-kit
# or
npm install @iof/embedded-ux-kit

Usage

import { MurabahaCalculator } from "@iof/embedded-ux-kit/widgets";

export function FinanceCalculatorPage() {
  return <MurabahaCalculator />;
}

All 13 widgets from the widgets catalog are available as React components, plus a generic WidgetShell wrapper and a useWidgetTheme hook.

Component	Purpose
`MurabahaCalculator`	Full Murabaha repayment schedule — AAOIFI SS-8 compliant
`IjarahCalculator`	Ijarah / Ijarah Muntahia Bittamleek rental schedule — AAOIFI SS-9
`SukukCalculator`	Sukuk distribution + yield-to-maturity — AAOIFI SS-17
`TakafulCalculator`	Family and General Takaful contribution — AAOIFI SS-26
`ROICalculator`	Islamic-finance ROI across Murabaha, Ijarah, Sukuk structures
`MurabahaApplicationForm`	End-to-end Murabaha finance application with KYC
`QrPaymentWidget`	ISO 20022 / EMVCo-compatible QR for merchant / invoice / zakat
`EvidencePackViewer`	Universal viewer for Shariah, BCBS 239, audit, trade, treasury packs
`ConsentCapture`	Open-finance and corporate consent with delegated authority
`TradeDocChecker`	UCP 600 / ISBP 821 / ISP98 discrepancy detection
`ReconciliationViewer`	Exception viewer for ledger / core / ISO 20022 breaks
`ComplianceBadge`	Trust badge linking to public evidence trail
`SandboxLauncher`	Self-serve sandbox tenant provisioning
`WidgetShell`	Generic wrapper — theme, error boundary, audit-event plumbing

Source of truth: packages/embedded-ux-kit/src/widgets/index.ts.

Theme

import { useWidgetTheme } from "@iof/embedded-ux-kit/widgets";

function Themed() {
  const theme = useWidgetTheme();
  return <div style={{ color: theme.accent }}>Hello</div>;
}

The theme system exposes brand tokens (accent colour, background, border, text tones) and honours the host application’s CSS variables when present. See packages/embedded-ux-kit/src/widgets/theme.ts.

`WidgetShell`

WidgetShell is the generic wrapper used internally by every concrete widget. You can use it directly when composing a custom widget that should still participate in the IOF audit-event stream and ABAC binding:

import { WidgetShell } from "@iof/embedded-ux-kit/widgets";

<WidgetShell widgetId="custom.my-widget" onEvent={(e) => send(e)}>
  {/* your UI */}
</WidgetShell>;

Event callbacks and audit trail

Every widget accepts an optional onEvent prop that receives structured WidgetEvent messages (same schema as the webhook-delivered events). These events are:

widget.session.started
widget.session.terminated
widget.submission.received
widget.error.thrown

Full payload schemas: packages/event-schema-registry/src/schemas/widget-events.ts (re-exported from @iof/contracts-core).

If you do not supply onEvent, events are still emitted server-side via the tenant’s configured webhook endpoint — the callback is purely for in-app reactivity.

ABAC and maker-checker

Every widget sits behind the embedded Cerbos PDP (EPDP) at the edge and the service PDP (SPDP) inside rail-api. Sensitive actions (contract creation, payment execution, consent grant) are declared approvalGated in the widget registry and are never auto-executed — the widget prepares, the supervisor approves.