@savvifi/meridian-web-react 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@savvifi/meridian-web-react",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "React adapter for the meridian WebRenderer seam: a kit-agnostic core (MeridianProvider, PanelRenderer, ComponentKit, reactWebRenderer) that renders meridian.ui.v1 PanelDescriptors through a swappable ComponentKit (MUI, shadcn, …). The premium web renderer tier of the meridian renderer family.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meridian-ux/meridian-web-react.git"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts"
+  ],
+  "dependencies": {
+    "@savvifi/meridian-proto-ts": "^0.1.0",
+    "@savvifi/meridian-schemas": "^0.1.0",
+    "@bufbuild/protobuf": "2.12.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "typescript": "5.6.2",
+    "vitest": "2.1.4"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  }
+}

package/src/component_kit.d.ts

@@ -0,0 +1,46 @@
+import type { ComponentType, CSSProperties, ReactNode } from "react";
+import type { GalleryPanel } from "@savvifi/meridian-proto-ts/proto/gallery_pb.js";
+import type { LlmPromptPanel } from "@savvifi/meridian-proto-ts/proto/llm_prompt_pb.js";
+import type { LroPanel } from "@savvifi/meridian-proto-ts/proto/lro_pb.js";
+import type { PanelDescriptor } from "@savvifi/meridian-proto-ts/proto/panel_pb.js";
+import type { PromptPanel } from "@savvifi/meridian-proto-ts/proto/prompt_pb.js";
+import type { TablePanel } from "@savvifi/meridian-proto-ts/proto/table_pb.js";
+import type { Theme } from "@savvifi/meridian-proto-ts/proto/theme_pb.js";
+import type { RpcInvoker } from "@savvifi/meridian-schemas/uiview";
+/** Props every shape component receives: its panel, the parent descriptor, transport. */
+export interface ShapeProps<P> {
+    panel: P;
+    descriptor: PanelDescriptor;
+    invoker: RpcInvoker;
+}
+export type TablePanelProps = ShapeProps<TablePanel>;
+export type PromptPanelProps = ShapeProps<PromptPanel>;
+export type LroPanelProps = ShapeProps<LroPanel>;
+export type GalleryPanelProps = ShapeProps<GalleryPanel>;
+export type LlmPromptPanelProps = ShapeProps<LlmPromptPanel>;
+/** A set of components + a theme binding that paints meridian panels. */
+export interface ComponentKit {
+    /** Stable id, e.g. "mui" / "shadcn" / "html". Used in the renderer id. */
+    readonly id: string;
+    /**
+     * Bind a meridian.theme.v1.Theme to this kit's style primitive (MUI theme,
+     * CSS custom properties, Tailwind config, …). Returned style is applied to the
+     * panel container. Optional — a kit may bind the theme its own way.
+     */
+    themeToStyle?(theme: Theme | undefined): CSSProperties;
+    /** Optional wrapper around every panel (title bar, surface, padding). */
+    Chrome?: ComponentType<{
+        descriptor: PanelDescriptor;
+        children: ReactNode;
+    }>;
+    Table: ComponentType<TablePanelProps>;
+    Prompt: ComponentType<PromptPanelProps>;
+    Lro: ComponentType<LroPanelProps>;
+    /** Optional richer shapes; PanelRenderer falls back when a kit omits them. */
+    Gallery?: ComponentType<GalleryPanelProps>;
+    LlmPrompt?: ComponentType<LlmPromptPanelProps>;
+    /** Rendered for unknown / unset / unsupported shapes. */
+    Fallback: ComponentType<{
+        descriptor: PanelDescriptor;
+    }>;
+}

package/src/component_kit.js

@@ -0,0 +1,9 @@
+// ComponentKit — the swap point *within* the React renderer.
+//
+// The React adapter core (provider + PanelRenderer + reactWebRenderer) is
+// kit-agnostic: it dispatches a meridian.ui.v1 PanelDescriptor to the kit's
+// per-shape components and binds the theme through the kit. Swapping the kit
+// (e.g. MUI -> shadcn) changes the look and the concrete components, not the
+// dispatch logic. The savvi `mui-kit` (wrapping @aion/ui) and a future
+// `shadcn-kit` are both implementations of this one interface.
+export {};

package/src/html_kit.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentKit } from "./component_kit.js";
+export declare const htmlKit: ComponentKit;

package/src/html_kit.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function themeToStyle(theme) {
+    if (!theme)
+        return {};
+    const pal = theme.dark ?? theme.light;
+    if (!pal)
+        return {};
+    // Expose the palette as the same --mer-* custom properties the web-components
+    // renderer uses, so one skin styles both web renderers identically.
+    return {
+        ["--mer-bg"]: pal.bg,
+        ["--mer-surface"]: pal.surface,
+        ["--mer-fg"]: pal.fg,
+        ["--mer-accent"]: pal.accent,
+        ["--mer-border"]: pal.border,
+        background: "var(--mer-bg)",
+        color: "var(--mer-fg)",
+    };
+}
+export const htmlKit = {
+    id: "html",
+    themeToStyle,
+    Chrome: ({ descriptor, children }) => (_jsxs("section", { className: "mer-panel", style: themeToStyle(undefined), children: [_jsx("h2", { className: "mer-panel-title", children: descriptor.title || descriptor.panelId }), children] })),
+    Table: ({ panel }) => (_jsxs("table", { className: "mer-table", children: [_jsx("thead", { children: _jsx("tr", { children: panel.columns.map((col, i) => (_jsx("th", { children: col.header }, i))) }) }), _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { className: "mer-empty", colSpan: panel.columns.length || 1, children: panel.placeholder || "(load to populate)" }) }) })] })),
+    Prompt: ({ panel }) => (_jsx("form", { className: "mer-prompt", children: panel.fields.map((field) => (_jsx("label", { className: "mer-field", children: _jsx("span", { children: field.label }) }, field.fieldId))) })),
+    Lro: ({ panel }) => (_jsx("div", { className: "mer-lro", children: _jsx("button", { type: "button", children: panel.runButtonLabel || "Run" }) })),
+    Fallback: ({ descriptor }) => (_jsx("pre", { className: "mer-fallback", children: descriptor.body.case
+            ? `unsupported panel shape: ${descriptor.body.case}`
+            : "(empty panel)" })),
+};

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export type { ComponentKit, ShapeProps, TablePanelProps, PromptPanelProps, LroPanelProps, GalleryPanelProps, LlmPromptPanelProps, } from "./component_kit.js";
+export { MeridianProvider, useMeridian, useMeridianTheme, useRpcInvoker, useComponentKit, useAdhocHandler, type MeridianContextValue, type MeridianProviderProps, type ReactAdhocFactory, } from "./provider.js";
+export { PanelRenderer } from "./panel_renderer.js";
+export { reactWebRenderer } from "./react_web_renderer.js";
+export { htmlKit } from "./html_kit.js";

package/src/index.js

@@ -0,0 +1,10 @@
+// @savvifi/meridian-web-react — the React renderer tier of the meridian renderer family.
+//
+// A kit-agnostic React adapter over the framework-neutral WebRenderer seam
+// (@savvifi/meridian-schemas/uiview): it renders meridian.ui.v1 PanelDescriptors through a
+// swappable ComponentKit. `reactWebRenderer(kit)` yields a WebRenderer a host
+// can mount, a peer of the web-components / TUI / native renderers.
+export { MeridianProvider, useMeridian, useMeridianTheme, useRpcInvoker, useComponentKit, useAdhocHandler, } from "./provider.js";
+export { PanelRenderer } from "./panel_renderer.js";
+export { reactWebRenderer } from "./react_web_renderer.js";
+export { htmlKit } from "./html_kit.js";

package/src/panel_renderer.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from "react";
+import type { PanelDescriptor } from "@savvifi/meridian-proto-ts/proto/panel_pb.js";
+export declare function PanelRenderer({ descriptor, }: {
+    descriptor: PanelDescriptor;
+}): ReactNode;

package/src/panel_renderer.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMeridian } from "./provider.js";
+export function PanelRenderer({ descriptor, }) {
+    const { kit, invoker, adhoc } = useMeridian();
+    const body = descriptor.body;
+    let inner;
+    switch (body.case) {
+        case "table":
+            inner = (_jsx(kit.Table, { panel: body.value, descriptor: descriptor, invoker: invoker }));
+            break;
+        case "prompt":
+            inner = (_jsx(kit.Prompt, { panel: body.value, descriptor: descriptor, invoker: invoker }));
+            break;
+        case "lro":
+            inner = (_jsx(kit.Lro, { panel: body.value, descriptor: descriptor, invoker: invoker }));
+            break;
+        case "gallery":
+            inner = kit.Gallery ? (_jsx(kit.Gallery, { panel: body.value, descriptor: descriptor, invoker: invoker })) : (_jsx(kit.Fallback, { descriptor: descriptor }));
+            break;
+        case "llmPrompt":
+            inner = kit.LlmPrompt ? (_jsx(kit.LlmPrompt, { panel: body.value, descriptor: descriptor, invoker: invoker })) : (_jsx(kit.Fallback, { descriptor: descriptor }));
+            break;
+        case "adhoc": {
+            const Adhoc = adhoc[body.value.handlerId];
+            inner = Adhoc ? (_jsx(Adhoc, { descriptor: descriptor })) : (_jsx(kit.Fallback, { descriptor: descriptor }));
+            break;
+        }
+        default:
+            inner = _jsx(kit.Fallback, { descriptor: descriptor });
+    }
+    const Chrome = kit.Chrome;
+    return Chrome ? _jsx(Chrome, { descriptor: descriptor, children: inner }) : inner;
+}

package/src/provider.d.ts

@@ -0,0 +1,24 @@
+import type { ComponentType, ReactNode } from "react";
+import type { PanelDescriptor } from "@savvifi/meridian-proto-ts/proto/panel_pb.js";
+import type { Theme } from "@savvifi/meridian-proto-ts/proto/theme_pb.js";
+import type { RpcInvoker } from "@savvifi/meridian-schemas/uiview";
+import type { ComponentKit } from "./component_kit.js";
+/** The React renderer's AdhocPanel factory: a component rendered for a handler_id. */
+export type ReactAdhocFactory = ComponentType<{
+    descriptor: PanelDescriptor;
+}>;
+export interface MeridianContextValue {
+    theme?: Theme;
+    invoker: RpcInvoker;
+    kit: ComponentKit;
+    adhoc: Record<string, ReactAdhocFactory>;
+}
+export declare function useMeridian(): MeridianContextValue;
+export declare const useMeridianTheme: () => Theme | undefined;
+export declare const useRpcInvoker: () => RpcInvoker;
+export declare const useComponentKit: () => ComponentKit;
+export declare const useAdhocHandler: (handlerId: string) => ReactAdhocFactory | undefined;
+export interface MeridianProviderProps extends MeridianContextValue {
+    children: ReactNode;
+}
+export declare function MeridianProvider({ children, ...value }: MeridianProviderProps): ReactNode;

package/src/provider.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// MeridianProvider — the React context that carries the cross-cutting inputs a
+// PanelRenderer needs: the active Theme (skin), the RpcInvoker (transport), the
+// chosen ComponentKit, and the adhoc-handler registry. It composes with a host's
+// other providers; it does not replace them.
+import { createContext, useContext } from "react";
+const MeridianContext = createContext(null);
+export function useMeridian() {
+    const value = useContext(MeridianContext);
+    if (!value) {
+        throw new Error("useMeridian must be used within a <MeridianProvider>");
+    }
+    return value;
+}
+export const useMeridianTheme = () => useMeridian().theme;
+export const useRpcInvoker = () => useMeridian().invoker;
+export const useComponentKit = () => useMeridian().kit;
+export const useAdhocHandler = (handlerId) => useMeridian().adhoc[handlerId];
+export function MeridianProvider({ children, ...value }) {
+    return (_jsx(MeridianContext.Provider, { value: value, children: children }));
+}

package/src/react_web_renderer.d.ts

@@ -0,0 +1,5 @@
+import type { Theme } from "@savvifi/meridian-proto-ts/proto/theme_pb.js";
+import type { WebRenderer } from "@savvifi/meridian-schemas/uiview";
+import type { ComponentKit } from "./component_kit.js";
+import { type ReactAdhocFactory } from "./provider.js";
+export declare function reactWebRenderer(kit: ComponentKit): WebRenderer<Theme, ReactAdhocFactory>;

package/src/react_web_renderer.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// reactWebRenderer — turns a ComponentKit into a meridian `WebRenderer` (the
+// framework-neutral seam from @savvifi/meridian-schemas/uiview). This is the React branch
+// of the web swap point: `reactWebRenderer(muiKit)` and
+// `reactWebRenderer(shadcnKit)` are both WebRenderers a host can mount, peers of
+// the web-components renderer — all consuming the same PanelDescriptor + Theme.
+import { createRoot } from "react-dom/client";
+import { PanelRenderer } from "./panel_renderer.js";
+import { MeridianProvider } from "./provider.js";
+export function reactWebRenderer(kit) {
+    return {
+        id: `react:${kit.id}`,
+        mount(opts) {
+            const root = createRoot(opts.container);
+            const draw = (descriptor) => root.render(_jsx(MeridianProvider, { theme: opts.theme, invoker: opts.invoker, kit: kit, adhoc: opts.adhoc ?? {}, children: _jsx(PanelRenderer, { descriptor: descriptor }) }));
+            draw(opts.descriptor);
+            return {
+                update: (descriptor) => draw(descriptor),
+                unmount: () => root.unmount(),
+            };
+        },
+    };
+}