@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.

PlatformReact is the high-trust render tier (RFC 0003), restricted to first-party PlatformPlugin builds. 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, … | MUI component re-exports plus the Dialog scroll-lock wrapper 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 / buildBreadcrumbs, 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 (flex-wrap grid), the page-header layer + breadcrumb builder, and the sidebar-action context/provider | | ./components/shared | ConfirmActionDialog, ConfirmDeleteDialog, useToast, showSuccessToast / showErrorToast / showWarningToast | Composite confirmation dialogs and toast notifications | | ./components/data-grid | PersistentDataGrid, setGridUserId / getGridUserId, buildDataGridPaginationProps, PAGE_SIZE_OPTIONS / DEFAULT_PAGE_SIZE, grid-state persistence helpers | The shared list-page grid with per-user state persistence. 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 | | ./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) | | ./types | Guid, Auditable, AuditableDetailed, HasRowVersion, PagedQuery, SearchQuery | Generic base DTO/query types (audit stamps, row version, branded GUID, paging) | | ./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