@ethisyscore/plugin-ui 1.88.3 → 1.91.0

package/dist/platform-react/index.d.cts

@@ -330,6 +330,49 @@ declare const ORGANISATION_SETTINGS_URI = "ethisys:organisation-settings";
  */
 declare function useOrgFormatSync(): void;
 
+/** Host tool that resolves the caller org's reporting currency (default, else GBP). */
+declare const REPORTING_CURRENCY_TOOL = "settings:get-organisation-reporting-currency";
+/** Host tool that lists the currency catalogue. */
+declare const LIST_CURRENCIES_TOOL = "settings:list-currencies";
+/** A currency as returned by the host currency tools. */
+interface CurrencyInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly code: string;
+    readonly symbol: string | null;
+    /** Host decimal-places override, or null to use the currency's ISO default. */
+    readonly decimalPlaces: number | null;
+}
+/** What a plugin surface may pass to {@link UseCurrencyResult.format} to name a currency. */
+type CurrencySelector = CurrencyInfo | string | null | undefined;
+interface UseCurrencyResult {
+    /** The org's reporting currency, or null while loading / when unresolved. */
+    reportingCurrency: CurrencyInfo | null;
+    /** The currency catalogue keyed by id (empty while loading / on a fail-open). */
+    currencies: ReadonlyMap<string, CurrencyInfo>;
+    /** True once the initial fetch has settled (whether it succeeded or failed open). */
+    ready: boolean;
+    /**
+     * Formats an amount in a currency. `currency` may be a {@link CurrencyInfo}, a
+     * currency id or ISO code (resolved via the catalogue), or null/undefined to use
+     * the org's reporting currency. When no currency can be resolved it falls back to a
+     * plain localized number so a render never throws or shows a wrong symbol.
+     */
+    format: (amount: number, currency?: CurrencySelector) => string;
+}
+/**
+ * Host-aware currency access for a plugin surface: the org's reporting currency, the
+ * currency catalogue, and a `format` helper that renders through the pure
+ * `@ethisyscore/core-utils/money` formatter honouring each currency's decimal-places
+ * override.
+ *
+ * Fails open, like {@link useOrgFormatSync}: it resolves the transport via the OPTIONAL
+ * accessor, so a surface rendered without a host transport (standalone/mock run, unit
+ * test) degrades to an empty catalogue and a plain-number fallback rather than crashing.
+ * Re-fetches when the active organisation changes.
+ */
+declare function useCurrency(): UseCurrencyResult;
+
 /**
  * Class on the portal container element rendered at the end of a plugin surface.
  * `plugin-base.css` positions it; the class is exported so a plugin can target it
@@ -1348,4 +1391,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, type ToolInvoker, TypedMcpService, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, BaseMcpService, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, type ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.d.ts

@@ -330,6 +330,49 @@ declare const ORGANISATION_SETTINGS_URI = "ethisys:organisation-settings";
  */
 declare function useOrgFormatSync(): void;
 
+/** Host tool that resolves the caller org's reporting currency (default, else GBP). */
+declare const REPORTING_CURRENCY_TOOL = "settings:get-organisation-reporting-currency";
+/** Host tool that lists the currency catalogue. */
+declare const LIST_CURRENCIES_TOOL = "settings:list-currencies";
+/** A currency as returned by the host currency tools. */
+interface CurrencyInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly code: string;
+    readonly symbol: string | null;
+    /** Host decimal-places override, or null to use the currency's ISO default. */
+    readonly decimalPlaces: number | null;
+}
+/** What a plugin surface may pass to {@link UseCurrencyResult.format} to name a currency. */
+type CurrencySelector = CurrencyInfo | string | null | undefined;
+interface UseCurrencyResult {
+    /** The org's reporting currency, or null while loading / when unresolved. */
+    reportingCurrency: CurrencyInfo | null;
+    /** The currency catalogue keyed by id (empty while loading / on a fail-open). */
+    currencies: ReadonlyMap<string, CurrencyInfo>;
+    /** True once the initial fetch has settled (whether it succeeded or failed open). */
+    ready: boolean;
+    /**
+     * Formats an amount in a currency. `currency` may be a {@link CurrencyInfo}, a
+     * currency id or ISO code (resolved via the catalogue), or null/undefined to use
+     * the org's reporting currency. When no currency can be resolved it falls back to a
+     * plain localized number so a render never throws or shows a wrong symbol.
+     */
+    format: (amount: number, currency?: CurrencySelector) => string;
+}
+/**
+ * Host-aware currency access for a plugin surface: the org's reporting currency, the
+ * currency catalogue, and a `format` helper that renders through the pure
+ * `@ethisyscore/core-utils/money` formatter honouring each currency's decimal-places
+ * override.
+ *
+ * Fails open, like {@link useOrgFormatSync}: it resolves the transport via the OPTIONAL
+ * accessor, so a surface rendered without a host transport (standalone/mock run, unit
+ * test) degrades to an empty catalogue and a plain-number fallback rather than crashing.
+ * Re-fetches when the active organisation changes.
+ */
+declare function useCurrency(): UseCurrencyResult;
+
 /**
  * Class on the portal container element rendered at the end of a plugin surface.
  * `plugin-base.css` positions it; the class is exported so a plugin can target it
@@ -1348,4 +1391,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, type ToolInvoker, TypedMcpService, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, BaseMcpService, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, type ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.js

@@ -1,11 +1,12 @@
-import { createContext, useEffect, useContext, useState, useMemo, createElement, useRef, useCallback, useSyncExternalStore } from 'react';
+import { createContext, useEffect, useContext, useState, useMemo, createElement, useCallback, useRef, useSyncExternalStore } from 'react';
 import { QueryClient, useQuery, useQueries, QueryClientProvider } from '@tanstack/react-query';
 import { definePlatformReactPage, emitNavigation } from '@ethisyscore/components-react';
 import * as extensionRuntime from '@ethisyscore/extension-runtime/plugin';
-import { useHostIdentity, useMcpTool, usePluginRealtimeSource, useExtensionRuntimeTransport } from '@ethisyscore/extension-runtime/plugin';
+import { useHostIdentity, useMcpTool, useOptionalExtensionRuntimeTransport, usePluginRealtimeSource, useExtensionRuntimeTransport } from '@ethisyscore/extension-runtime/plugin';
 import { useTheme, ThemeProvider } from '@mui/material';
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { setOrgFormats } from '@ethisyscore/core-utils/date/org-format';
+import { MONEY_FALLBACK_LOCALE, formatMoney } from '@ethisyscore/core-utils/money';
 
 // src/platform-react/definePlatformReactPluginPage.tsx
 var TemplateContext = createContext(null);
@@ -368,6 +369,89 @@ function useAuthenticatedQuery(options) {
 function useAuthenticatedQueries(queries) {
   return useQueries({ queries });
 }
+var REPORTING_CURRENCY_TOOL = "settings:get-organisation-reporting-currency";
+var LIST_CURRENCIES_TOOL = "settings:list-currencies";
+var emptyCatalogue = () => /* @__PURE__ */ new Map();
+var SETTLED_FULFILLED = "fulfilled";
+function useCurrency() {
+  const transport = useOptionalExtensionRuntimeTransport();
+  const organisationId = useHostIdentity()?.organisationId ?? null;
+  const [reportingCurrency, setReportingCurrency] = useState(null);
+  const [currencies, setCurrencies] = useState(emptyCatalogue);
+  const [ready, setReady] = useState(false);
+  useEffect(() => {
+    setReportingCurrency(null);
+    setCurrencies(emptyCatalogue());
+    setReady(false);
+    if (!transport) {
+      setReady(true);
+      return;
+    }
+    const controller = new AbortController();
+    Promise.allSettled([
+      transport.invokeTool(
+        REPORTING_CURRENCY_TOOL,
+        {},
+        controller.signal
+      ),
+      transport.invokeTool(
+        LIST_CURRENCIES_TOOL,
+        {},
+        controller.signal
+      )
+    ]).then(([reporting, list]) => {
+      if (controller.signal.aborted) return;
+      if (reporting.status === SETTLED_FULFILLED) {
+        setReportingCurrency(reporting.value?.currency ?? null);
+      }
+      if (list.status === SETTLED_FULFILLED && Array.isArray(list.value)) {
+        setCurrencies(new Map(list.value.map((currency) => [currency.id, currency])));
+      }
+      setReady(true);
+    });
+    return () => controller.abort();
+  }, [transport, organisationId]);
+  const format = useCallback(
+    (amount, selector) => {
+      const currency = resolveCurrency(selector, currencies, reportingCurrency);
+      if (currency === null) {
+        return new Intl.NumberFormat(MONEY_FALLBACK_LOCALE).format(amount);
+      }
+      if (typeof currency === "string") {
+        return formatMoney(amount, { currencyCode: currency });
+      }
+      return formatMoney(amount, {
+        currencyCode: currency.code,
+        decimalPlaces: currency.decimalPlaces,
+        symbol: currency.symbol
+      });
+    },
+    [currencies, reportingCurrency]
+  );
+  return useMemo(
+    () => ({ reportingCurrency, currencies, ready, format }),
+    [reportingCurrency, currencies, ready, format]
+  );
+}
+function resolveCurrency(selector, currencies, reportingCurrency) {
+  if (selector === null || selector === void 0) {
+    return reportingCurrency;
+  }
+  if (typeof selector !== "string") {
+    return selector;
+  }
+  const byId = currencies.get(selector);
+  if (byId) {
+    return byId;
+  }
+  const upper = selector.toUpperCase();
+  for (const currency of currencies.values()) {
+    if (currency.code.toUpperCase() === upper) {
+      return currency;
+    }
+  }
+  return selector;
+}
 function matchRouteParams(pathname, routes, basePath) {
   const prefix = basePath.length > 1 && basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
   const norm = pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
@@ -938,6 +1022,6 @@ function menuConfigToHostSidebarInput(config, opts) {
   return { mode: "actions", actions };
 }
 
-export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };
+export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, LIST_CURRENCIES_TOOL, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map