@componentonce/react 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @componentonce/react
+
+React adapter for trusted ComponentOnce modules.
+
+React is a peer dependency. Dynamically compiled modules must use the host application's actual React and JSX-runtime instances rather than bundling another React copy.
+
+## Define and render
+
+defineReactComponent<Props, HostContext, Payload> keeps persisted props, arbitrary host context, and per-render payload distinct.
+
+Typed rendering does not revalidate values by default. Raw JSON/editor/storage boundaries can use validateReactComponentBoundary or renderReactComponentBoundary to validate props and payload once.
+
+## React runtime compatibility
+
+createReactRequirement(version) creates the generic core requirement named react.
+
+When a definition declares requirements, renderReactComponent checks them against hostCapabilities before calling React createElement. Exact compatibility is the default. The host may supply capabilityCompatibility when it deliberately supports a version range.
+
+This matters because sharing the host React singleton prevents duplicate-React hook failures, but it does not make a React-19-authored module compatible with a React-18 host automatically.
+
+## Host-specific helpers
+
+createReactHostHelpers<HostContext, Payload>() fixes application context/payload types without importing application code into ComponentOnce. Each component still chooses its own Props type.

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import { type ComponentType, type ReactElement } from "react";
+import { type ComponentOnceCapability, type ComponentOnceCapabilityCompatibility, type ComponentOnceDefinition, type ComponentOnceManifest, type ComponentOnceRequirement, type ComponentOnceValidator } from "@componentonce/core";
+/** Stable core capability name used for the host React runtime. */
+export declare const REACT_CAPABILITY_NAME = "react";
+/** Create one generic core requirement for a React runtime version. */
+export declare function createReactRequirement(version: string): ComponentOnceRequirement;
+/** Props passed to one trusted React implementation by its host. */
+export interface ComponentOnceReactRenderInput<TProps, THostContext, TPayload> {
+    readonly props: TProps;
+    readonly context: THostContext;
+    readonly payload: TPayload;
+}
+/** React implementation shape registered with ComponentOnce. */
+export type ComponentOnceReactComponent<TProps, THostContext, TPayload> = ComponentType<ComponentOnceReactRenderInput<TProps, THostContext, TPayload>>;
+/** A core definition whose implementation is a typed React component. */
+export type ComponentOnceReactDefinition<TProps, THostContext, TPayload> = ComponentOnceDefinition<ComponentOnceReactComponent<TProps, THostContext, TPayload>, TProps, THostContext, TPayload>;
+/** Input used to define one typed React component. */
+export interface DefineReactComponentInput<TProps, THostContext, TPayload> {
+    readonly manifest: ComponentOnceManifest;
+    readonly component: ComponentOnceReactComponent<TProps, THostContext, TPayload>;
+    readonly validateProps?: ComponentOnceValidator<TProps>;
+    readonly validatePayload?: ComponentOnceValidator<TPayload>;
+}
+/** Selects typed values that the renderer should explicitly revalidate. */
+export interface ComponentOnceReactValidationRequest {
+    readonly props?: boolean;
+    readonly payload?: boolean;
+}
+/** Input used to render an already typed exact React definition. */
+export interface ComponentOnceReactRendererInput<TProps, THostContext, TPayload> extends ComponentOnceReactRenderInput<TProps, THostContext, TPayload> {
+    readonly definition: ComponentOnceReactDefinition<TProps, THostContext, TPayload>;
+    /** Validation is off by default; `true` requests both validators. */
+    readonly validation?: boolean | ComponentOnceReactValidationRequest;
+    /** Runtime/application capabilities exposed by the host. */
+    readonly hostCapabilities?: readonly ComponentOnceCapability[];
+    /** Optional host-defined compatibility policy; exact matching is the core default. */
+    readonly capabilityCompatibility?: ComponentOnceCapabilityCompatibility;
+}
+/** Unknown props and payload received at an untyped host boundary. */
+export interface ComponentOnceReactBoundaryInput<THostContext> {
+    readonly props: unknown;
+    readonly context: THostContext;
+    readonly payload: unknown;
+}
+/** The definition and raw values needed to validate an untyped render boundary. */
+export interface ComponentOnceReactBoundaryRenderInput<TProps, THostContext, TPayload> extends ComponentOnceReactBoundaryInput<THostContext> {
+    readonly definition: ComponentOnceReactDefinition<TProps, THostContext, TPayload>;
+    /** Runtime/application capabilities exposed by the host. */
+    readonly hostCapabilities?: readonly ComponentOnceCapability[];
+    /** Optional host-defined compatibility policy; exact matching is the core default. */
+    readonly capabilityCompatibility?: ComponentOnceCapabilityCompatibility;
+}
+/** A definition field that can carry an optional boundary validator. */
+export type ComponentOnceReactValidationField = "props" | "payload";
+/** Thrown when a caller requests boundary validation that a definition does not provide. */
+export declare class ComponentOnceReactValidatorMissingError extends Error {
+    readonly field: ComponentOnceReactValidationField;
+    readonly manifest: ComponentOnceManifest;
+    constructor(field: ComponentOnceReactValidationField, manifest: ComponentOnceManifest);
+}
+/** Helpers with host context and payload types fixed for one application integration. */
+export interface ComponentOnceReactHostHelpers<THostContext, TPayload> {
+    /** Define a component while inferring only its persisted props type. */
+    define<TProps>(input: DefineReactComponentInput<TProps, THostContext, TPayload>): ComponentOnceReactDefinition<TProps, THostContext, TPayload>;
+    /** Render typed values without validation unless the request explicitly enables it. */
+    render<TProps>(input: ComponentOnceReactRendererInput<TProps, THostContext, TPayload>): ReactElement;
+    /** Validate unknown props and payload once and preserve the host context unchanged. */
+    validateBoundary<TProps>(definition: ComponentOnceReactDefinition<TProps, THostContext, TPayload>, input: ComponentOnceReactBoundaryInput<THostContext>): ComponentOnceReactRenderInput<TProps, THostContext, TPayload>;
+    /** Validate and render values received from an untyped boundary. */
+    renderBoundary<TProps>(input: ComponentOnceReactBoundaryRenderInput<TProps, THostContext, TPayload>): ReactElement;
+}
+/** Define one typed React component without teaching core anything about React. */
+export declare function defineReactComponent<TProps, THostContext, TPayload>(input: DefineReactComponentInput<TProps, THostContext, TPayload>): ComponentOnceReactDefinition<TProps, THostContext, TPayload>;
+/** Render an exact React definition, with optional validation requested by the host. */
+export declare function renderReactComponent<TProps, THostContext, TPayload>(input: ComponentOnceReactRendererInput<TProps, THostContext, TPayload>): ReactElement;
+/** Validate unknown props and payload once at a host boundary. */
+export declare function validateReactComponentBoundary<TProps, THostContext, TPayload>(definition: ComponentOnceReactDefinition<TProps, THostContext, TPayload>, input: ComponentOnceReactBoundaryInput<THostContext>): ComponentOnceReactRenderInput<TProps, THostContext, TPayload>;
+/** Validate unknown boundary values and render the resulting typed React input. */
+export declare function renderReactComponentBoundary<TProps, THostContext, TPayload>(input: ComponentOnceReactBoundaryRenderInput<TProps, THostContext, TPayload>): ReactElement;
+/** Create concise definition and rendering helpers pinned to one host's own types. */
+export declare function createReactHostHelpers<THostContext, TPayload>(): ComponentOnceReactHostHelpers<THostContext, TPayload>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,94 @@
+import { createElement } from "react";
+import { assertComponentOnceCompatible, } from "@componentonce/core";
+/** Stable core capability name used for the host React runtime. */
+export const REACT_CAPABILITY_NAME = "react";
+/** Create one generic core requirement for a React runtime version. */
+export function createReactRequirement(version) {
+    return { name: REACT_CAPABILITY_NAME, version };
+}
+/** Thrown when a caller requests boundary validation that a definition does not provide. */
+export class ComponentOnceReactValidatorMissingError extends Error {
+    field;
+    manifest;
+    constructor(field, manifest) {
+        super(`Component "${manifest.id}" version "${manifest.version}" has no ${field} validator.`);
+        this.name = new.target.name;
+        this.field = field;
+        this.manifest = manifest;
+    }
+}
+/** Define one typed React component without teaching core anything about React. */
+export function defineReactComponent(input) {
+    return {
+        manifest: input.manifest,
+        implementation: input.component,
+        ...(input.validateProps === undefined ? {} : { validateProps: input.validateProps }),
+        ...(input.validatePayload === undefined ? {} : { validatePayload: input.validatePayload }),
+    };
+}
+/** Render an exact React definition, with optional validation requested by the host. */
+export function renderReactComponent(input) {
+    assertComponentOnceCompatible(input.definition.manifest, input.hostCapabilities ?? [], input.capabilityCompatibility);
+    const validation = normalizeValidation(input.validation);
+    const props = validation.props
+        ? validateField(input.definition, "props", input.props)
+        : input.props;
+    const payload = validation.payload
+        ? validateField(input.definition, "payload", input.payload)
+        : input.payload;
+    return createElement(input.definition.implementation, {
+        props,
+        context: input.context,
+        payload,
+    });
+}
+/** Validate unknown props and payload once at a host boundary. */
+export function validateReactComponentBoundary(definition, input) {
+    return {
+        props: validateField(definition, "props", input.props),
+        context: input.context,
+        payload: validateField(definition, "payload", input.payload),
+    };
+}
+/** Validate unknown boundary values and render the resulting typed React input. */
+export function renderReactComponentBoundary(input) {
+    const validated = validateReactComponentBoundary(input.definition, input);
+    return renderReactComponent({
+        definition: input.definition,
+        ...validated,
+        ...(input.hostCapabilities === undefined
+            ? {}
+            : { hostCapabilities: input.hostCapabilities }),
+        ...(input.capabilityCompatibility === undefined
+            ? {}
+            : { capabilityCompatibility: input.capabilityCompatibility }),
+    });
+}
+/** Create concise definition and rendering helpers pinned to one host's own types. */
+export function createReactHostHelpers() {
+    return {
+        define: (input) => defineReactComponent(input),
+        render: (input) => renderReactComponent(input),
+        validateBoundary: (definition, input) => validateReactComponentBoundary(definition, input),
+        renderBoundary: (input) => renderReactComponentBoundary(input),
+    };
+}
+function normalizeValidation(validation) {
+    if (validation === true)
+        return { props: true, payload: true };
+    if (validation === false || validation === undefined) {
+        return { props: false, payload: false };
+    }
+    return {
+        props: validation.props ?? false,
+        payload: validation.payload ?? false,
+    };
+}
+function validateField(definition, field, value) {
+    const validator = field === "props" ? definition.validateProps : definition.validatePayload;
+    if (validator === undefined) {
+        throw new ComponentOnceReactValidatorMissingError(field, definition.manifest);
+    }
+    return validator(value);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAyC,MAAM,OAAO,CAAC;AAC7E,OAAO,EACL,6BAA6B,GAO9B,MAAM,qBAAqB,CAAC;AAE7B,mEAAmE;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAE7C,uEAAuE;AACvE,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC;AAoED,4FAA4F;AAC5F,MAAM,OAAO,uCAAwC,SAAQ,KAAK;IAChD,KAAK,CAAoC;IACzC,QAAQ,CAAwB;IAEhD,YACE,KAAwC,EACxC,QAA+B;QAE/B,KAAK,CACH,cAAc,QAAQ,CAAC,EAAE,cAAc,QAAQ,CAAC,OAAO,YAAY,KAAK,aAAa,CACtF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAuBD,mFAAmF;AACnF,MAAM,UAAU,oBAAoB,CAClC,KAAgE;IAEhE,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,cAAc,EAAE,KAAK,CAAC,SAAS;QAC/B,GAAG,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC;QACpF,GAAG,CAAC,KAAK,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC;KAC3F,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,oBAAoB,CAClC,KAAsE;IAEtE,6BAA6B,CAC3B,KAAK,CAAC,UAAU,CAAC,QAAQ,EACzB,KAAK,CAAC,gBAAgB,IAAI,EAAE,EAC5B,KAAK,CAAC,uBAAuB,CAC9B,CAAC;IACF,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK;QAC5B,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC;QACvD,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;IAChB,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO;QAChC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;QAC3D,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IAElB,OAAO,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,cAAc,EAAE;QACpD,KAAK;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,OAAO;KACR,CAAC,CAAC;AACL,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,8BAA8B,CAC5C,UAAwE,EACxE,KAAoD;IAEpD,OAAO;QACL,KAAK,EAAE,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC;QACtD,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,OAAO,EAAE,aAAa,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,4BAA4B,CAC1C,KAA4E;IAE5E,MAAM,SAAS,GAAG,8BAA8B,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAC1E,OAAO,oBAAoB,CAAC;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,GAAG,SAAS;QACZ,GAAG,CAAC,KAAK,CAAC,gBAAgB,KAAK,SAAS;YACtC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,EAAE,CAAC;QACjD,GAAG,CAAC,KAAK,CAAC,uBAAuB,KAAK,SAAS;YAC7C,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,uBAAuB,EAAE,KAAK,CAAC,uBAAuB,EAAE,CAAC;KAChE,CAAC,CAAC;AACL,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,sBAAsB;IAIpC,OAAO;QACL,MAAM,EAAE,CAAU,KAAgE,EAAE,EAAE,CACpF,oBAAoB,CAAC,KAAK,CAAC;QAC7B,MAAM,EAAE,CAAU,KAAsE,EAAE,EAAE,CAC1F,oBAAoB,CAAC,KAAK,CAAC;QAC7B,gBAAgB,EAAE,CAChB,UAAwE,EACxE,KAAoD,EACpD,EAAE,CAAC,8BAA8B,CAAC,UAAU,EAAE,KAAK,CAAC;QACtD,cAAc,EAAE,CACd,KAA4E,EAC5E,EAAE,CAAC,4BAA4B,CAAC,KAAK,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAC1B,UAAqE;IAErE,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC/D,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QACrD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO;QACL,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,KAAK;QAChC,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,KAAK;KACrC,CAAC;AACJ,CAAC;AAYD,SAAS,aAAa,CACpB,UAAwE,EACxE,KAAwC,EACxC,KAAc;IAEd,MAAM,SAAS,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,eAAe,CAAC;IAC5F,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,uCAAuC,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC"}

package/examples/two-hosts.tsx

@@ -0,0 +1,66 @@
+import { renderReactComponent, defineReactComponent } from "@componentonce/react";
+
+interface BannerProps {
+  readonly prefix: string;
+}
+
+interface BrowserHostContext {
+  readonly kind: "browser";
+  readonly locale: string;
+  readonly navigate: (path: string) => void;
+}
+
+interface WorkerHostContext {
+  readonly kind: "worker";
+  readonly jobName: string;
+  readonly retry: (jobId: number) => Promise<void>;
+}
+
+interface PagePayload {
+  readonly kind: "page";
+  readonly pathname: string;
+}
+
+interface JobPayload {
+  readonly kind: "job";
+  readonly jobId: number;
+  readonly attempt: number;
+}
+
+type HostContext = BrowserHostContext | WorkerHostContext;
+type Payload = PagePayload | JobPayload;
+
+// One exact module accepts the two host-owned type pairs without ComponentOnce
+// knowing either shape.
+const statusBanner = defineReactComponent<BannerProps, HostContext, Payload>({
+  manifest: { id: "example/status-banner", version: "1.0.0" },
+  component: ({ props, context, payload }) => {
+    const host = context.kind === "browser" ? context.locale : context.jobName;
+    const value = payload.kind === "page" ? payload.pathname : `attempt ${payload.attempt}`;
+    return <strong>{props.prefix}: {host} / {value}</strong>;
+  },
+});
+
+/** The same exact definition rendered inside a browser application. */
+export const browserElement = renderReactComponent({
+  definition: statusBanner,
+  props: { prefix: "Status" },
+  context: {
+    kind: "browser",
+    locale: "en-GB",
+    navigate: () => undefined,
+  },
+  payload: { kind: "page", pathname: "/reports" },
+});
+
+/** The same exact definition rendered inside a background worker application. */
+export const workerElement = renderReactComponent({
+  definition: statusBanner,
+  props: { prefix: "Status" },
+  context: {
+    kind: "worker",
+    jobName: "monthly-report",
+    retry: async () => undefined,
+  },
+  payload: { kind: "job", jobId: 81, attempt: 2 },
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@componentonce/react",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "examples",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@componentonce/core": "0.1.0-beta.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react-dom": "^19.2.2",
+    "@types/react": "^19.2.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.5"
+  },
+  "description": "React adapter for trusted ComponentOnce components using the host React runtime.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "precheck": "pnpm --filter @componentonce/core build",
+    "check": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+    "pretest": "pnpm --filter @componentonce/core build",
+    "test": "vitest run",
+    "prebuild": "pnpm --filter @componentonce/core build",
+    "build": "tsc -p tsconfig.json"
+  }
+}