@ethisyscore/plugin-ui
The PlatformReact frontend foundation for EthisysCore plugins. It gives a plugin
everything it needs to lift a monolith React feature onto a plugin surface: page
and overlay factories, a static useView adapter, an MCP-over-hooks service
layer, react-query / react-router shims, scoped styles, the nexture icon set,
and the shared MUI component surface externalised to the host's instances.
MUI 7 or newer. The optional
@mui/materialpeer is>=7, matching the host and the sandbox theme kit (which uses MUI 7-only APIs).
PlatformReact is the high-trust render tier (RFC 0003), restricted to first-party
PlatformPluginbuilds. See the top-level render-mode overview and the PlatformReact author guide.
Export surface
| Subpath | Key exports | Purpose |
|---|---|---|
. | createPortBridgeClient, BridgeClientContext / useBridgeClient, useBridgeTheme / useBridgeLocale, ExtensionRuntimeProvider, useMcpResource / useMcpTool / useMcpQuery / unwrapItems, useHostIdentity / useCurrentUser, definePlatformReactPage / emitNavigation / PlatformReactPageProps | Bridge client + theme/locale context, brokered-MCP data hooks, host identity, and the base PlatformReact page contract |
./platform-react | definePlatformReactPluginPage / createPluginPageDefiner, definePlatformReactPluginOverlay / useOverlayHost, useView / createUseView / ViewComponent / isComponent, BaseMcpService / useToolInvoker / useToolInvokerMap, useAuthenticatedQuery / useAuthenticatedQueries, injectPluginStyles / PluginStyleScope, createReactRouterShim, usePluginRealtime, useBackgroundOperation / useOperationsByParent / useLatestTerminalOperationByParent / hasKind, useUploadToStorage / PluginStorageUploadError / isPluginStorageUploadError / validatePluginStoragePrefix, useMcpUpload (legacy CORE storage), useManagedLifecycle | The plugin authoring layer: page/overlay wrappers (react-query + manifest + style root), the static useView adapter pattern, the MCP service base + tool invokers, pre-authenticated react-query wrappers, scoped-style injection, router shim, realtime, following the plugin's own background operations, and file upload |
./icons | NextureIcons, IconMap, 470+ Ni* icon components, sizeHelper / strokeSizeHelper, IconName / IconSize / IconVariant | The gogo-ui "nexture" SVG icon set with props types and size/stroke helpers |
./components/ui | Button, Card, Dialog, Table, TextField, Select, Tabs, Typography, Grid, Stack, Menu, DebouncedSearchInput, cn, useDebounce, … | MUI component re-exports plus the Dialog scroll-lock wrapper, cn and useDebounce (all three from @ethisyscore/foundation-ui) and the debounced search field. These are host externals — never bundled; production builds bind them to the host's MUI instance |
./components/layout | PageHeader / usePageHeader / withPageHeader, FillGrid / FillGridItem / FillGap / FillSpan, sidebar-action context (SidebarActionProvider, useSidebarAction / useSidebarActions / useTriggerSidebarAction), RouteMeta / RouteMetaEntry; header actions take an optional attributes bag, restricted to data-* (e.g. onboardingTarget("x")) | Layout primitives (the flex-wrap grid, from @ethisyscore/foundation-ui), the page-header layer + breadcrumb builder, and the sidebar-action context/provider |
./components/shared | ConfirmActionDialog, ConfirmDeleteDialog, useConfirmDialog / useTargetDialog / useReasonDialog (from @ethisyscore/foundation-ui), useToast, showSuccessToast / showErrorToast / showWarningToast | Composite confirmation dialogs and toast notifications |
./components/data-grid | PersistentDataGrid (with a typed toolbar / toolbarProps), setGridUserId / getGridUserId, buildDataGridPaginationProps, buildDataGridSlots, DataGridPaginationFullPage, usePaginationSlot, grid-state persistence helpers | The shared list-page grid with per-user state persistence, the house slot set and pagination slots. Needs the optional peer @mui/x-data-grid |
./components/date | DateInput / DateInputProps, toIsoString / parseIsoValue, DATE_INPUT_MIN / DATE_INPUT_MAX, DateInputType | The shared date / datetime field over MUI X pickers, speaking ISO strings. Needs the optional peers @mui/x-date-pickers and dayjs |
./components/connectors | ConnectorMappingView, MappingCompletenessBanner, ConnectorMappingTranslationEditorView, selectRequiredIncompleteOperations / selectOptionalIncompleteOperations / selectIncompleteOperations / selectMappingReadiness, connectorMappingsQueryKey / connectorMappingCompletenessQueryKey, MappingCompletenessItem / MappingCompletenessResult, ConnectorCanonicalField / TestToolMappingRequest / TestToolMappingResult / ConnectorMappingSuggestionResult | The PRESENTATIONAL half of the shared Tool Mappings surface, for any module that reaches an external system through a connector — the mapping table, the completeness banner and the per-mapping field-translation editor. Needs the optional peer @mui/material. Carries four fixes a copy loses: the banner says FIELDS rather than tools, the completeness query key is nested under the mappings key so one invalidation covers both, the editor's "Test mapping" button is gated on onTestMapping (an ungated copy renders a dead control for a caller wiring only auto-configure) with ?? [] tolerance on both canonical field lists, and the view's unmapped-required warning is NOT gated on aiAvailable (a keyword-only auto-match always reports false, which made the one warning an operator must act on unreachable) |
./connector-mappings | ConnectorMappingService / CONNECTOR_MAPPING_TOOLS, useConnectorToolMappings, useConnectorMappings / useConnectorMappingCompleteness, useConnectorMappingMutations, useMappingTranslationEditor, useAutoMatchOnConnectorSwitch, useMappingBannerDismissal, useSuggestMappingTranslation / useTestMapping, mapConnectorsToOptions / mapConnectorToolsToOptions, ConnectorMappingItem / AutoMatchResponse / ConnectorMappingWriteArgs | The DATA half of the same surface: the connectors:mappings:* MCP service plus every react-query hook a Tool Mappings page needs, composed by useConnectorToolMappings into the three prop bundles the components take. Needs the optional peer @tanstack/react-query, and nothing else — identity, routing, connector enumeration and selection are all injected. Promoted from three plugins that had ~3,300 duplicated lines between them and had to fix the same two production defects once per repo; see docs/adopting-shared-tool-mappings.md |
./org-format | formatDate / formatDateTime / formatTime / formatDateOrPresent / formatRelativeTime, getOrgDateInputFormat / getOrgDateTimeInputFormat, formatMoney / formatCompactMoney / getCurrencySymbol, setOrgFormats / getOrgDateFormat / getOrgTimeFormat / resolveOrgDateFormat / resolveOrgTimeFormat, setOrgReportingCurrency / getOrgReportingCurrency / resolveOrgReportingCurrencyCode, ORG_DATE_FALLBACK_FORMAT / ORG_TIME_FALLBACK_FORMAT / MONEY_FALLBACK_CURRENCY | The organisation's date/time formats and reporting currency, stamped by useOrgFormatSync / useReportingCurrencySync, and argument-free formatters that read them (UK dd/MM/yyyy, HH:mm, GBP when nothing is stamped). Money renders with the en-GB symbol display, so USD, CAD and AUD read "US$", "CA$" and "A$" rather than a bare "$" (foundation-utils' own money formatters still use narrowSymbol). The pure date formatting lives in @ethisyscore/foundation-utils; plugin-ui imports this entry by its package specifier so the whole bundle shares one copy of the state |
./a11y | useA11yAnnounce | Accessible live-region announcement hook |
./l10n | usePluginLocale / PluginLocale | Locale + direction/RTL helper |
./token | useFrontendSessionToken, useAuth, decodeJwtPayload | Frontend session token + JWT auth utilities |
./tailwind-preset | ehxTailwindPreset | Tailwind preset carrying the gogo-ui theme scales (screens, fonts, sizes, colours, shadows) |
./plugin-base.css | (CSS asset) | Static base stylesheet for plugin surfaces |
Typical usage
// A PlatformReact page module the host dynamic-imports at surface mount.
import { definePlatformReactPluginPage } from "@ethisyscore/plugin-ui/platform-react";
import { useView } from "@ethisyscore/plugin-ui/platform-react";
function MyFeaturePage() {
const View = useView("my-feature/list");
return <View />;
}
export default definePlatformReactPluginPage(MyFeaturePage);
Handlers do not call MCP tools directly — wrap each callee domain in a typed
service extending BaseMcpService and consume it through useToolInvoker. See
the top-level README §"services over MCP" and the
FE migration playbook.
Uploading a browser file
Browser uploads go through useUploadToStorage into the app's own plugin storage. Never base64 a file through a tool call.
import { useUploadToStorage, isPluginStorageUploadError } from "@ethisyscore/plugin-ui/platform-react";
const { upload, loading, error } = useUploadToStorage();
async function onFile(file: File) {
try {
const { path } = await upload(file, { pathPrefix: "cvs" });
await recordCv({ path }); // the app's own command; the backend reads `path` via IPluginStorage
} catch (err) {
if (isPluginStorageUploadError(err) && err.reason === "quota_exceeded") { /* ... */ }
}
}
The prefix is one or more /-separated [A-Za-z0-9_-] segments, at most 84 characters, with no leading or trailing /. It is refused, never repaired. Files are capped at 30 MB, and only allow-listed passive types (PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES) are accepted. See CAPABILITIES.md for the full rules and the error reasons.
Build and test
npm ci && npm run build && npm test
Last Updated: 2026-07-10