@ethisyscore/components-react 1.7.1

package/README.md

@@ -0,0 +1,53 @@
+# `@ethisyscore/components-react`
+
+Host-bound React contract for EthisysCore PlatformReact pages (RFC 0003).
+
+Provides the typed page-props contract every PlatformReact page receives from
+the host at surface mount time, plus a `definePlatformReactPage` helper so
+plugin authors get type-safe access to the host realm without depending on
+the host app's internal modules.
+
+```tsx
+import { definePlatformReactPage, type PlatformReactPageProps } from "@ethisyscore/components-react";
+
+const Dashboard = ({ extensionId, organisationId, pageId }: PlatformReactPageProps) => (
+  <section>
+    <h1>Dashboard</h1>
+    <p>Extension {extensionId} for org {organisationId} (page: {pageId})</p>
+  </section>
+);
+
+export default definePlatformReactPage(Dashboard);
+```
+
+The plugin's `feature.manifest.json` references this module via
+`ui.platformReactPages[].moduleSpecifier`; the host loads the module at surface
+mount time, reads the declared `exportName`, and renders the component with the
+typed props.
+
+## Why this package exists
+
+PlatformReact is the high-trust platform-extension tier — the plugin's bundle
+runs in the host realm, so the plugin can use any npm package the author
+bundles. This package is the **one** dependency that has to come from the host
+side: the contract for what the host passes to the mounted page. Keeping it as
+a focused npm package means:
+
+- The host's internal modules (`coreconnect-web`'s `PlatformReactSurfaceMount`)
+  do not leak as plugin dependencies.
+- The contract grows with explicit versioning — additive changes are
+  backward-compatible, breaking changes bump the major.
+- Plugin authors get strict TypeScript at the host-↔-plugin seam — no `any`,
+  no shape drift.
+
+## What's in the package
+
+- `PlatformReactPageProps` — the props every page receives from the host
+  (`extensionId`, `organisationId`, optional `tenantId`, `pageId`).
+- `definePlatformReactPage(Component)` — pass-through helper today; the
+  indirection point for future host integrations (boundary injection,
+  suspense fallbacks, error contracts) to land without every plugin author
+  updating their export.
+
+See `docs/authoring/platform-react.md` for the full PlatformReact authoring
+guide.

package/dist/index.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+// src/navigation.ts
+function emitNavigation(to) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const event = new CustomEvent("ethisys:navigate", {
+    detail: { to },
+    cancelable: true
+  });
+  window.dispatchEvent(event);
+  if (!event.defaultPrevented) {
+    window.location.assign(to);
+  }
+}
+
+// src/index.ts
+function definePlatformReactPage(component) {
+  return component;
+}
+
+exports.definePlatformReactPage = definePlatformReactPage;
+exports.emitNavigation = emitNavigation;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/navigation.ts","../src/index.ts"],"names":[],"mappings":";;;AAmBO,SAAS,eAAe,EAAA,EAAkB;AAC/C,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACjC,IAAA;AAAA,EACF;AACA,EAAA,MAAM,KAAA,GAAQ,IAAI,WAAA,CAAY,kBAAA,EAAoB;AAAA,IAChD,MAAA,EAAQ,EAAE,EAAA,EAAG;AAAA,IACb,UAAA,EAAY;AAAA,GACb,CAAA;AACD,EAAA,MAAA,CAAO,cAAc,KAAK,CAAA;AAG1B,EAAA,IAAI,CAAC,MAAM,gBAAA,EAAkB;AAC3B,IAAA,MAAA,CAAO,QAAA,CAAS,OAAO,EAAE,CAAA;AAAA,EAC3B;AACF;;;ACmCO,SAAS,wBACd,SAAA,EACkB;AAClB,EAAA,OAAO,SAAA;AACT","file":"index.cjs","sourcesContent":["/**\n * Host navigation bridge for PlatformReact pages (RFC 0003).\n *\n * PlatformReact pages run inside the host's React tree but cannot import the\n * host's `useNavigate` directly — that would couple the plugin's bundle to\n * the host's router internals and break the realm boundary the contract\n * preserves. Instead, plugins dispatch a `CustomEvent(\"ethisys:navigate\")`\n * on `window`; the host's `useExtensionNavigation` listener intercepts the\n * event and translates it into a React Router push.\n *\n * `cancelable: true` is load-bearing — without it the host's\n * `event.preventDefault()` is a no-op (CustomEvent defaults to\n * non-cancelable), so `defaultPrevented` stays `false`, the\n * `window.location.assign` fallback fires AFTER the SPA navigation has\n * already run, and the user sees an unwanted full-page reload. The flag is\n * the entire contract between plugin and host on this seam, which is why\n * the helper exists — getting it right per-plugin is exactly the kind of\n * detail that should be baked into the SDK rather than the README.\n */\nexport function emitNavigation(to: string): void {\n  if (typeof window === \"undefined\") {\n    return;\n  }\n  const event = new CustomEvent(\"ethisys:navigate\", {\n    detail: { to },\n    cancelable: true,\n  });\n  window.dispatchEvent(event);\n  // Fallback for hosts that haven't wired the listener yet — full-document\n  // navigation isn't ideal but keeps the page functional.\n  if (!event.defaultPrevented) {\n    window.location.assign(to);\n  }\n}\n","import type { ComponentType } from \"react\";\n\n// ── Public contract ────────────────────────────────────────────────\n\n/**\n * The injected props every PlatformReact page component receives from the\n * host at surface mount time (RFC 0003).\n *\n * The host's surface mount (`PlatformReactSurfaceMount.tsx` in\n * `coreconnect-web`) reads each declared page's `exportName` from the loaded\n * module and renders it with these props. Plugin authors typing their page\n * components against this interface get strict type-checking for everything\n * the host actually supplies — no `any` at the seam.\n *\n * The shape is intentionally minimal. Additional context the host wires up\n * (theme, navigation, telemetry) reaches plugins via cross-cutting providers\n * the host wraps around the mounted component, not through this props\n * object — so growing the host's contextual surface does not change this\n * interface.\n */\nexport interface PlatformReactPageProps {\n  /**\n   * The extension's GUID as declared on the manifest's `id` field. Stable\n   * across enable/disable lifecycle transitions within a tenant.\n   */\n  extensionId: string;\n  /**\n   * The active organisation. Plugins MUST scope every data read and write to\n   * this id — the host enforces tenant isolation downstream, but propagating\n   * the id keeps the dependency direction explicit and testable.\n   */\n  organisationId: string;\n  /**\n   * Optional tenant id. Present for tenant-bound deployments; absent for\n   * platform-wide pages. Pages that branch on this MUST handle `undefined`.\n   */\n  tenantId?: string;\n  /**\n   * The host-side surface key for this page. Matches the `id` declared on\n   * the manifest's `ui.platformReactPages[]` entry. Useful for telemetry tags\n   * and for pages that share a component implementation across multiple\n   * surfaces.\n   */\n  pageId: string;\n}\n\n/**\n * Type-safe declaration helper for a PlatformReact page component.\n *\n * The plugin author exports the result of this call from the module path\n * referenced by the manifest's `moduleSpecifier`:\n *\n * @example\n * ```tsx\n * import { definePlatformReactPage, type PlatformReactPageProps } from \"@ethisyscore/components-react\";\n *\n * const Dashboard = ({ extensionId, organisationId }: PlatformReactPageProps) => (\n *   <div>Dashboard for {extensionId} / {organisationId}</div>\n * );\n *\n * export default definePlatformReactPage(Dashboard);\n * ```\n *\n * The helper currently returns the input component unchanged — it exists as\n * a stable indirection point so future host integrations (boundary-injection,\n * suspense fallbacks, error contracts) can land transparently without every\n * plugin author updating their export.\n */\nexport function definePlatformReactPage<P extends PlatformReactPageProps>(\n  component: ComponentType<P>,\n): ComponentType<P> {\n  return component;\n}\n\nexport { emitNavigation } from \"./navigation\";\n"]}

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+import { ComponentType } from 'react';
+
+/**
+ * Host navigation bridge for PlatformReact pages (RFC 0003).
+ *
+ * PlatformReact pages run inside the host's React tree but cannot import the
+ * host's `useNavigate` directly — that would couple the plugin's bundle to
+ * the host's router internals and break the realm boundary the contract
+ * preserves. Instead, plugins dispatch a `CustomEvent("ethisys:navigate")`
+ * on `window`; the host's `useExtensionNavigation` listener intercepts the
+ * event and translates it into a React Router push.
+ *
+ * `cancelable: true` is load-bearing — without it the host's
+ * `event.preventDefault()` is a no-op (CustomEvent defaults to
+ * non-cancelable), so `defaultPrevented` stays `false`, the
+ * `window.location.assign` fallback fires AFTER the SPA navigation has
+ * already run, and the user sees an unwanted full-page reload. The flag is
+ * the entire contract between plugin and host on this seam, which is why
+ * the helper exists — getting it right per-plugin is exactly the kind of
+ * detail that should be baked into the SDK rather than the README.
+ */
+declare function emitNavigation(to: string): void;
+
+/**
+ * The injected props every PlatformReact page component receives from the
+ * host at surface mount time (RFC 0003).
+ *
+ * The host's surface mount (`PlatformReactSurfaceMount.tsx` in
+ * `coreconnect-web`) reads each declared page's `exportName` from the loaded
+ * module and renders it with these props. Plugin authors typing their page
+ * components against this interface get strict type-checking for everything
+ * the host actually supplies — no `any` at the seam.
+ *
+ * The shape is intentionally minimal. Additional context the host wires up
+ * (theme, navigation, telemetry) reaches plugins via cross-cutting providers
+ * the host wraps around the mounted component, not through this props
+ * object — so growing the host's contextual surface does not change this
+ * interface.
+ */
+interface PlatformReactPageProps {
+    /**
+     * The extension's GUID as declared on the manifest's `id` field. Stable
+     * across enable/disable lifecycle transitions within a tenant.
+     */
+    extensionId: string;
+    /**
+     * The active organisation. Plugins MUST scope every data read and write to
+     * this id — the host enforces tenant isolation downstream, but propagating
+     * the id keeps the dependency direction explicit and testable.
+     */
+    organisationId: string;
+    /**
+     * Optional tenant id. Present for tenant-bound deployments; absent for
+     * platform-wide pages. Pages that branch on this MUST handle `undefined`.
+     */
+    tenantId?: string;
+    /**
+     * The host-side surface key for this page. Matches the `id` declared on
+     * the manifest's `ui.platformReactPages[]` entry. Useful for telemetry tags
+     * and for pages that share a component implementation across multiple
+     * surfaces.
+     */
+    pageId: string;
+}
+/**
+ * Type-safe declaration helper for a PlatformReact page component.
+ *
+ * The plugin author exports the result of this call from the module path
+ * referenced by the manifest's `moduleSpecifier`:
+ *
+ * @example
+ * ```tsx
+ * import { definePlatformReactPage, type PlatformReactPageProps } from "@ethisyscore/components-react";
+ *
+ * const Dashboard = ({ extensionId, organisationId }: PlatformReactPageProps) => (
+ *   <div>Dashboard for {extensionId} / {organisationId}</div>
+ * );
+ *
+ * export default definePlatformReactPage(Dashboard);
+ * ```
+ *
+ * The helper currently returns the input component unchanged — it exists as
+ * a stable indirection point so future host integrations (boundary-injection,
+ * suspense fallbacks, error contracts) can land transparently without every
+ * plugin author updating their export.
+ */
+declare function definePlatformReactPage<P extends PlatformReactPageProps>(component: ComponentType<P>): ComponentType<P>;
+
+export { type PlatformReactPageProps, definePlatformReactPage, emitNavigation };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { ComponentType } from 'react';
+
+/**
+ * Host navigation bridge for PlatformReact pages (RFC 0003).
+ *
+ * PlatformReact pages run inside the host's React tree but cannot import the
+ * host's `useNavigate` directly — that would couple the plugin's bundle to
+ * the host's router internals and break the realm boundary the contract
+ * preserves. Instead, plugins dispatch a `CustomEvent("ethisys:navigate")`
+ * on `window`; the host's `useExtensionNavigation` listener intercepts the
+ * event and translates it into a React Router push.
+ *
+ * `cancelable: true` is load-bearing — without it the host's
+ * `event.preventDefault()` is a no-op (CustomEvent defaults to
+ * non-cancelable), so `defaultPrevented` stays `false`, the
+ * `window.location.assign` fallback fires AFTER the SPA navigation has
+ * already run, and the user sees an unwanted full-page reload. The flag is
+ * the entire contract between plugin and host on this seam, which is why
+ * the helper exists — getting it right per-plugin is exactly the kind of
+ * detail that should be baked into the SDK rather than the README.
+ */
+declare function emitNavigation(to: string): void;
+
+/**
+ * The injected props every PlatformReact page component receives from the
+ * host at surface mount time (RFC 0003).
+ *
+ * The host's surface mount (`PlatformReactSurfaceMount.tsx` in
+ * `coreconnect-web`) reads each declared page's `exportName` from the loaded
+ * module and renders it with these props. Plugin authors typing their page
+ * components against this interface get strict type-checking for everything
+ * the host actually supplies — no `any` at the seam.
+ *
+ * The shape is intentionally minimal. Additional context the host wires up
+ * (theme, navigation, telemetry) reaches plugins via cross-cutting providers
+ * the host wraps around the mounted component, not through this props
+ * object — so growing the host's contextual surface does not change this
+ * interface.
+ */
+interface PlatformReactPageProps {
+    /**
+     * The extension's GUID as declared on the manifest's `id` field. Stable
+     * across enable/disable lifecycle transitions within a tenant.
+     */
+    extensionId: string;
+    /**
+     * The active organisation. Plugins MUST scope every data read and write to
+     * this id — the host enforces tenant isolation downstream, but propagating
+     * the id keeps the dependency direction explicit and testable.
+     */
+    organisationId: string;
+    /**
+     * Optional tenant id. Present for tenant-bound deployments; absent for
+     * platform-wide pages. Pages that branch on this MUST handle `undefined`.
+     */
+    tenantId?: string;
+    /**
+     * The host-side surface key for this page. Matches the `id` declared on
+     * the manifest's `ui.platformReactPages[]` entry. Useful for telemetry tags
+     * and for pages that share a component implementation across multiple
+     * surfaces.
+     */
+    pageId: string;
+}
+/**
+ * Type-safe declaration helper for a PlatformReact page component.
+ *
+ * The plugin author exports the result of this call from the module path
+ * referenced by the manifest's `moduleSpecifier`:
+ *
+ * @example
+ * ```tsx
+ * import { definePlatformReactPage, type PlatformReactPageProps } from "@ethisyscore/components-react";
+ *
+ * const Dashboard = ({ extensionId, organisationId }: PlatformReactPageProps) => (
+ *   <div>Dashboard for {extensionId} / {organisationId}</div>
+ * );
+ *
+ * export default definePlatformReactPage(Dashboard);
+ * ```
+ *
+ * The helper currently returns the input component unchanged — it exists as
+ * a stable indirection point so future host integrations (boundary-injection,
+ * suspense fallbacks, error contracts) can land transparently without every
+ * plugin author updating their export.
+ */
+declare function definePlatformReactPage<P extends PlatformReactPageProps>(component: ComponentType<P>): ComponentType<P>;
+
+export { type PlatformReactPageProps, definePlatformReactPage, emitNavigation };

package/dist/index.js

@@ -0,0 +1,23 @@
+// src/navigation.ts
+function emitNavigation(to) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const event = new CustomEvent("ethisys:navigate", {
+    detail: { to },
+    cancelable: true
+  });
+  window.dispatchEvent(event);
+  if (!event.defaultPrevented) {
+    window.location.assign(to);
+  }
+}
+
+// src/index.ts
+function definePlatformReactPage(component) {
+  return component;
+}
+
+export { definePlatformReactPage, emitNavigation };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/navigation.ts","../src/index.ts"],"names":[],"mappings":";AAmBO,SAAS,eAAe,EAAA,EAAkB;AAC/C,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACjC,IAAA;AAAA,EACF;AACA,EAAA,MAAM,KAAA,GAAQ,IAAI,WAAA,CAAY,kBAAA,EAAoB;AAAA,IAChD,MAAA,EAAQ,EAAE,EAAA,EAAG;AAAA,IACb,UAAA,EAAY;AAAA,GACb,CAAA;AACD,EAAA,MAAA,CAAO,cAAc,KAAK,CAAA;AAG1B,EAAA,IAAI,CAAC,MAAM,gBAAA,EAAkB;AAC3B,IAAA,MAAA,CAAO,QAAA,CAAS,OAAO,EAAE,CAAA;AAAA,EAC3B;AACF;;;ACmCO,SAAS,wBACd,SAAA,EACkB;AAClB,EAAA,OAAO,SAAA;AACT","file":"index.js","sourcesContent":["/**\n * Host navigation bridge for PlatformReact pages (RFC 0003).\n *\n * PlatformReact pages run inside the host's React tree but cannot import the\n * host's `useNavigate` directly — that would couple the plugin's bundle to\n * the host's router internals and break the realm boundary the contract\n * preserves. Instead, plugins dispatch a `CustomEvent(\"ethisys:navigate\")`\n * on `window`; the host's `useExtensionNavigation` listener intercepts the\n * event and translates it into a React Router push.\n *\n * `cancelable: true` is load-bearing — without it the host's\n * `event.preventDefault()` is a no-op (CustomEvent defaults to\n * non-cancelable), so `defaultPrevented` stays `false`, the\n * `window.location.assign` fallback fires AFTER the SPA navigation has\n * already run, and the user sees an unwanted full-page reload. The flag is\n * the entire contract between plugin and host on this seam, which is why\n * the helper exists — getting it right per-plugin is exactly the kind of\n * detail that should be baked into the SDK rather than the README.\n */\nexport function emitNavigation(to: string): void {\n  if (typeof window === \"undefined\") {\n    return;\n  }\n  const event = new CustomEvent(\"ethisys:navigate\", {\n    detail: { to },\n    cancelable: true,\n  });\n  window.dispatchEvent(event);\n  // Fallback for hosts that haven't wired the listener yet — full-document\n  // navigation isn't ideal but keeps the page functional.\n  if (!event.defaultPrevented) {\n    window.location.assign(to);\n  }\n}\n","import type { ComponentType } from \"react\";\n\n// ── Public contract ────────────────────────────────────────────────\n\n/**\n * The injected props every PlatformReact page component receives from the\n * host at surface mount time (RFC 0003).\n *\n * The host's surface mount (`PlatformReactSurfaceMount.tsx` in\n * `coreconnect-web`) reads each declared page's `exportName` from the loaded\n * module and renders it with these props. Plugin authors typing their page\n * components against this interface get strict type-checking for everything\n * the host actually supplies — no `any` at the seam.\n *\n * The shape is intentionally minimal. Additional context the host wires up\n * (theme, navigation, telemetry) reaches plugins via cross-cutting providers\n * the host wraps around the mounted component, not through this props\n * object — so growing the host's contextual surface does not change this\n * interface.\n */\nexport interface PlatformReactPageProps {\n  /**\n   * The extension's GUID as declared on the manifest's `id` field. Stable\n   * across enable/disable lifecycle transitions within a tenant.\n   */\n  extensionId: string;\n  /**\n   * The active organisation. Plugins MUST scope every data read and write to\n   * this id — the host enforces tenant isolation downstream, but propagating\n   * the id keeps the dependency direction explicit and testable.\n   */\n  organisationId: string;\n  /**\n   * Optional tenant id. Present for tenant-bound deployments; absent for\n   * platform-wide pages. Pages that branch on this MUST handle `undefined`.\n   */\n  tenantId?: string;\n  /**\n   * The host-side surface key for this page. Matches the `id` declared on\n   * the manifest's `ui.platformReactPages[]` entry. Useful for telemetry tags\n   * and for pages that share a component implementation across multiple\n   * surfaces.\n   */\n  pageId: string;\n}\n\n/**\n * Type-safe declaration helper for a PlatformReact page component.\n *\n * The plugin author exports the result of this call from the module path\n * referenced by the manifest's `moduleSpecifier`:\n *\n * @example\n * ```tsx\n * import { definePlatformReactPage, type PlatformReactPageProps } from \"@ethisyscore/components-react\";\n *\n * const Dashboard = ({ extensionId, organisationId }: PlatformReactPageProps) => (\n *   <div>Dashboard for {extensionId} / {organisationId}</div>\n * );\n *\n * export default definePlatformReactPage(Dashboard);\n * ```\n *\n * The helper currently returns the input component unchanged — it exists as\n * a stable indirection point so future host integrations (boundary-injection,\n * suspense fallbacks, error contracts) can land transparently without every\n * plugin author updating their export.\n */\nexport function definePlatformReactPage<P extends PlatformReactPageProps>(\n  component: ComponentType<P>,\n): ComponentType<P> {\n  return component;\n}\n\nexport { emitNavigation } from \"./navigation\";\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ethisyscore/components-react",
+  "version": "1.7.1",
+  "description": "Host-bound React contract for EthisysCore PlatformReact pages (RFC 0003). Provides the typed page-props contract and `definePlatformReactPage` helper so plugin authors get type-safe access to the host realm — extensionId, organisationId, mcp transport — without depending on the host app's internal modules.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "keywords": [
+    "ethisyscore",
+    "platform-react",
+    "rfc-0003",
+    "plugin"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ethisysltd/ethisyscore-plugin-sdk"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}