@rainbow-robotics/plugin-ui 0.1.2-dev.8 → 1.0.0

package/src/pluginData.tsx

@@ -0,0 +1,232 @@
+/// <reference types="vite/client" />
+/**
+ * Plugin data seam (host-side). Resolves where each plugin's UI/assets load
+ * from. `muscat-pk dev` sets `window.__RB_PREVIEW_PLUGIN_ID__`; that id routes
+ * to preview-host, everything else to the installed-plugin back end, so both
+ * coexist. The host passes its dialog/toast as `hostServices`, registered via
+ * setHostServices (see ./host-ui).
+ */
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type PropsWithChildren,
+} from "react";
+import type { PluginManifest } from "./manifest";
+// Package specifier, not a relative path — see host.tsx for why (source vs dist
+// host-ui would be two `services` singletons).
+import {
+  setHostServices,
+  type PluginUIServices,
+} from "@rainbow-robotics/plugin-ui/host-ui";
+
+/**
+ * Where/how to load a plugin's UI module — no iframe involved, the host
+ * mounts it directly.
+ *
+ * - "dev": the plugin's own Vite dev server (muscat-pk dev). `bootstrapUrl` is
+ *   a plain ESM module exposing `mount(container, rb, hostServices)`; react
+ *   and plugin-ui resolve from that dev server's own module graph, so this
+ *   mount is a fully self-consistent, independently-rooted React tree.
+ * - "esm": a built plugin (`muscat-pk build` / robot runtime), a plain ESM
+ *   module the host dynamically imports. react / rb-components / plugin-ui
+ *   context modules are left external as bare specifiers, resolved by the host
+ *   page's import map to the host's own already-loaded instances — so it mounts
+ *   as a genuine nested React tree with working Context (RbContext, host-ui)
+ *   and no duplicate React instance.
+ */
+export type PluginModuleSource =
+  | { kind: "dev"; bootstrapUrl: string }
+  | { kind: "esm"; entryUrl: string };
+
+export interface PluginDataSource {
+  /** Preview plugin manifest (only while a dev plugin is being previewed). */
+  usePluginManifest: () => { data: PluginManifest | null; isLoading: boolean };
+  /** Where/how to load a plugin's UI module for a given UI entry. */
+  getModuleSource: (pluginId: string, ui: string) => PluginModuleSource;
+  /** URL of a plugin asset (e.g. an icon) by its manifest-relative path. */
+  getAssetUrl: (pluginId: string, assetPath: string) => string;
+  /** Socket.IO server URL the plugin connects to. */
+  getSocketUrl: (pluginId: string) => string;
+}
+
+const PluginDataContext = createContext<PluginDataSource | null>(null);
+
+export function usePluginData(): PluginDataSource {
+  const ctx = useContext(PluginDataContext);
+  if (!ctx) {
+    throw new Error("usePluginData must be used within a PluginDataProvider");
+  }
+  return ctx;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Preview (preview-host: the developer's locally-built plugin)                */
+/* -------------------------------------------------------------------------- */
+
+type PreviewWindow = Window & {
+  /** Plugin id under `muscat-pk dev` — requests for it route to preview-host. */
+  __RB_PREVIEW_PLUGIN_ID__?: string;
+  /** Base URL preview-host serves the dev plugin's manifest/assets from. */
+  __RB_PLUGIN_PREVIEW_BASE__?: string;
+  /** Where the plugin's OWN Vite dev server lives (distinct from the above —
+   *  that's preview-host's own static route; this is the plugin's dev server,
+   *  which serves its bootstrap module for direct mounting). */
+  __RB_PLUGIN_DEV_SERVER_URL__?: string;
+  /** Override URL for the plugin manifest. */
+  __RB_PLUGIN_PREVIEW_MANIFEST__?: string;
+  /** Socket.IO URL — injected by muscat-pk CLI when starting preview. */
+  __RB_PLUGIN_PREVIEW_SOCKET_URL__?: string;
+};
+
+const win = (): PreviewWindow | undefined =>
+  typeof window !== "undefined" ? (window as PreviewWindow) : undefined;
+
+const isViteDev = import.meta.env.DEV;
+
+/** The plugin id being previewed via `muscat-pk dev`, if any. */
+function previewPluginId(): string | undefined {
+  return (
+    win()?.__RB_PREVIEW_PLUGIN_ID__ ||
+    (isViteDev ? "com.example.demo-plugin" : undefined)
+  );
+}
+
+/** Whether a given plugin id is the one being developed locally. */
+function isPreviewPlugin(pluginId: string): boolean {
+  const id = previewPluginId();
+  return !!id && id === pluginId;
+}
+
+/** Where preview-host serves the dev plugin's manifest/assets. */
+function previewBase(): string {
+  const base =
+    win()?.__RB_PLUGIN_PREVIEW_BASE__ ||
+    (isViteDev ? "http://localhost:4180/plugin-dev" : "/plugin-dev");
+  return base.replace(/\/$/, "");
+}
+
+/** Where the plugin's own Vite dev server lives (for the bootstrap module). */
+function devServerUrl(): string {
+  const base =
+    win()?.__RB_PLUGIN_DEV_SERVER_URL__ ||
+    (isViteDev ? "http://localhost:4181" : win()?.location.origin || "");
+  return base.replace(/\/$/, "");
+}
+
+function previewManifestUrl(): string {
+  return (
+    win()?.__RB_PLUGIN_PREVIEW_MANIFEST__ || `${previewBase()}/manifest.json`
+  );
+}
+
+function previewSocketUrl(): string {
+  return win()?.__RB_PLUGIN_PREVIEW_SOCKET_URL__ || "ws://127.0.0.1:10000";
+}
+
+// Shared, deduped fetch — several components read the manifest, so a single
+// module-level promise avoids duplicate requests (react-query is not needed).
+let manifestPromise: Promise<PluginManifest> | null = null;
+function loadPreviewManifest(): Promise<PluginManifest> {
+  if (!manifestPromise) {
+    manifestPromise = (async () => {
+      const url = previewManifestUrl();
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`GET ${url} failed: ${res.status}`);
+      return res.json() as Promise<PluginManifest>;
+    })();
+  }
+  return manifestPromise;
+}
+
+function usePreviewManifest(): {
+  data: PluginManifest | null;
+  isLoading: boolean;
+} {
+  const enabled = !!previewPluginId();
+  const [data, setData] = useState<PluginManifest | null>(null);
+  const [isLoading, setIsLoading] = useState(enabled);
+
+  useEffect(() => {
+    if (!enabled) {
+      setData(null);
+      setIsLoading(false);
+      return;
+    }
+    let alive = true;
+    setIsLoading(true);
+    loadPreviewManifest()
+      .then((m) => alive && setData(m))
+      .finally(() => alive && setIsLoading(false));
+    return () => {
+      alive = false;
+    };
+  }, [enabled]);
+
+  return { data, isLoading };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Provider                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export interface PluginDataProviderProps {
+  /**
+   * The host's real dialog/toast, registered for plugins to use via
+   * `@rainbow-robotics/plugin-ui/host-ui`. The host builds these ONCE inside
+   * its own React tree (calling its real useDialog) and passes the resulting
+   * plain functions here — safe to call from a plugin's separate React
+   * instance (dev). See ./host-ui.
+   */
+  hostServices: PluginUIServices;
+  /** Socket.IO URL for installed (non-preview) plugins. */
+  wsUrl?: string;
+  /** URL prefix the host serves installed plugins from. */
+  liveBase?: string;
+}
+
+export function PluginDataProvider({
+  children,
+  hostServices,
+  wsUrl = "ws://127.0.0.1:10000",
+  liveBase = "http://localhost:3000/common/plugin",
+}: PropsWithChildren<PluginDataProviderProps>) {
+  // Register in an effect (setHostServices is a side effect, not render-safe).
+  // Layout effect so it runs before children (a mounting PluginHost) read it.
+  useEffect(() => {
+    setHostServices(hostServices);
+  }, [hostServices]);
+
+  const source = useMemo<PluginDataSource>(() => {
+    const base = liveBase.replace(/\/$/, "");
+    return {
+      usePluginManifest: usePreviewManifest,
+      getModuleSource: (pluginId, ui) =>
+        isPreviewPlugin(pluginId)
+          ? {
+              kind: "dev",
+              bootstrapUrl: `${devServerUrl()}/@id/__x00__rb-bootstrap:${ui}`,
+            }
+          : {
+              kind: "esm",
+              // The plugin's built ESM entry for this ui — bare externals
+              // inside are resolved by the host page's import map.
+              entryUrl: `${base}/${pluginId}/${ui}.js`,
+            },
+      getAssetUrl: (pluginId, assetPath) =>
+        isPreviewPlugin(pluginId)
+          ? `${previewBase()}/${assetPath}`
+          : `${base}/${pluginId}/${assetPath}`,
+      getSocketUrl: (pluginId) =>
+        isPreviewPlugin(pluginId) ? previewSocketUrl() : wsUrl,
+    };
+  }, [wsUrl, liveBase]);
+
+  return (
+    <PluginDataContext.Provider value={source}>
+      {children}
+    </PluginDataContext.Provider>
+  );
+}

package/src/react.tsx

@@ -1,131 +1,13 @@
 /**
- * Author bindings — the React components a plugin author imports from
- * `@rainbow-robotics/plugin-ui/react`.
+ * Author component surface — re-exports the @repo/rb-components new_components
+ * barrel, plus the sdk hooks.
  *
- * These are *name tags*: they render rb-* custom elements into the sandbox's
- * remote DOM. The real rb-components are rendered by the host (see ./host).
- * Event names from each element's `remoteEvents` surface as `onX` props
- * (e.g. `change` → `onChange`) carrying a `RemoteEvent` whose `detail` holds
- * the payload.
+ *   import { RBSlider, RBLabelButton, useRb } from "@rainbow-robotics/plugin-ui/react";
+ *
+ * The runtime import-map shim (./viteHost.ts) reads this module's exports
+ * rather than a hardcoded list, so the two stay in sync.
  */
-import { createRemoteComponent } from "@remote-dom/react";
-import type { ComponentType, ReactNode, Ref } from "react";
-import {
-  RbSliderElement,
-  RbButtonElement,
-  RbIconButtonElement,
-  RbTextElement,
-  RbTextInputElement,
-  RbSwitchElement,
-  RbSelectElement,
-  type RbButtonProps,
-  type RbIconButtonProps,
-  type RbSelectProps,
-  type RbSliderProps,
-  type RbSwitchProps,
-  type RbTextInputProps,
-  type RbTextProps,
-} from "./elements";
-
-// NOTE: createRemoteComponent only treats a prop as an event listener when it is
-// declared in `eventProps`; it does NOT auto-derive from the element's
-// `remoteEvents`. These maps MUST mirror the host's eventProps (see ./host).
-//
-// `eventProps` is typed against the element's *typed* EventListeners generic.
-// Fully typing those generics would also force typing every `remoteProperties`
-// shape on the classes (remote-dom itself uses @ts-expect-error around this), so
-// we cast the event maps here. The values are verified by the demo e2e, and the
-// returned components keep their element-derived prop types for plugin authors.
-type EventMap = Record<string, { event: string }>;
-const events = (map: EventMap) => ({ eventProps: map }) as never;
-
-type NoEventProps = Record<never, never>;
-
-type RemoteElementComponentProps<
-  Element,
-  Props,
-  EventProps = NoEventProps,
-> = Props &
-  EventProps & {
-    children?: ReactNode;
-    ref?: Ref<Element>;
-    slot?: string;
-  };
-
-type RemoteElementComponent<
-  Element,
-  Props,
-  EventProps = NoEventProps,
-> = ComponentType<RemoteElementComponentProps<Element, Props, EventProps>>;
-
-export type RbSliderChangeEvent = { detail: number };
-export type RbTextInputEvent = { detail: string };
-export type RbSwitchChangeEvent = { detail: boolean };
-export type RbSelectChangeEvent = { detail: string };
-
-export interface RbSliderEventProps {
-  onChange?: (event: RbSliderChangeEvent) => void;
-}
-
-export interface RbPressEventProps {
-  onPress?: () => void;
-}
-
-export interface RbTextInputEventProps {
-  onInput?: (event: RbTextInputEvent) => void;
-}
-
-export interface RbSwitchEventProps {
-  onChange?: (event: RbSwitchChangeEvent) => void;
-}
-
-export interface RbSelectEventProps {
-  onChange?: (event: RbSelectChangeEvent) => void;
-}
-
-export const Slider = createRemoteComponent(
-  "rb-slider",
-  RbSliderElement,
-  events({ onChange: { event: "change" } }),
-) as RemoteElementComponent<RbSliderElement, RbSliderProps, RbSliderEventProps>;
-export const Button = createRemoteComponent(
-  "rb-button",
-  RbButtonElement,
-  events({ onPress: { event: "press" } }),
-) as RemoteElementComponent<RbButtonElement, RbButtonProps, RbPressEventProps>;
-export const IconButton = createRemoteComponent(
-  "rb-icon-button",
-  RbIconButtonElement,
-  events({ onPress: { event: "press" } }),
-) as RemoteElementComponent<
-  RbIconButtonElement,
-  RbIconButtonProps,
-  RbPressEventProps
->;
-export const Text = createRemoteComponent(
-  "rb-text",
-  RbTextElement,
-) as RemoteElementComponent<RbTextElement, RbTextProps>;
-export const TextInput = createRemoteComponent(
-  "rb-text-input",
-  RbTextInputElement,
-  events({ onInput: { event: "input" } }),
-) as RemoteElementComponent<
-  RbTextInputElement,
-  RbTextInputProps,
-  RbTextInputEventProps
->;
-export const Switch = createRemoteComponent(
-  "rb-switch",
-  RbSwitchElement,
-  events({ onChange: { event: "change" } }),
-) as RemoteElementComponent<RbSwitchElement, RbSwitchProps, RbSwitchEventProps>;
-export const Select = createRemoteComponent(
-  "rb-select",
-  RbSelectElement,
-  events({ onChange: { event: "change" } }),
-) as RemoteElementComponent<RbSelectElement, RbSelectProps, RbSelectEventProps>;
+export * from "@repo/rb-components/new_components";
 
-export { useRb } from "./sdk";
-export type { RbSdk, RbNotifyType } from "./sdk";
-export type { RbSelectOption } from "./elements";
+export { useRb, useRbFormData, useRbSave } from "./sdk.js";
+export type { RbSdk } from "./sdk";

package/src/sdk.ts

@@ -1,21 +1,26 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
- * Plugin runtime SDK — the surface a plugin author calls from inside the sandbox.
+ * Plugin runtime SDK (`useRb()`).
  *
- * Zenoh methods (pub/sub/action/serve) talk directly to the Zenoh router via
- * WebSocket. Topics are auto-namespaced to plugin/{pluginId}/... to prevent
- * cross-plugin collisions. A leading "/" bypasses namespacing (absolute path).
- *
- * notify() is still host-mediated (goes through the Muscat shell).
+ * pub/sub/action/serve talk to the Zenoh router over WebSocket. Topics are
+ * namespaced to {pluginId}/... ; a leading "/" makes the path absolute.
+ * alert/confirm/prompt/toast delegate to the host.
  */
-import { createContext, useContext } from "react";
-import type { WsSubscriber as Subscriber, WsQueryable as Queryable } from "./ws";
+import { createContext, useContext, useEffect, useRef } from "react";
+import type {
+  WsSubscriber as Subscriber,
+  WsQueryable as Queryable,
+} from "./ws";
+// Type-only import — no runtime coupling to host-ui.ts (which itself has no
+// dependency back on sdk.ts, so this stays one-directional).
+import type { PluginUIServices } from "./host-ui";
 
 export type RbNotifyType = "info" | "success" | "warning" | "error";
 
 export interface RbSdk {
   /**
    * Publish JSON payload to a topic.
-   * "sensor/data" → plugin/{pluginId}/sensor/data
+   * "sensor/data" → {pluginId}/sensor/data
    * "/broadcast/x" → broadcast/x  (absolute)
    */
   pub: <P = any>(topic: string, payload: P) => Promise<void>;
@@ -42,7 +47,29 @@ export interface RbSdk {
   ) => Promise<Queryable>;
 
   /** Show a transient notification through the host's toast system. */
-  toast: (message: string, type?: RbNotifyType) => void;
+  toast: PluginUIServices["toast"];
+
+  /** Show a host alert dialog. */
+  alert: PluginUIServices["alert"];
+  /** Show a host confirm dialog. Resolves true/false. */
+  confirm: PluginUIServices["confirm"];
+  /** Show a host prompt dialog. Resolves the entered value, or undefined if cancelled. */
+  prompt: PluginUIServices["prompt"];
+
+  /**
+   * Host-provided initial data for this mount — e.g. the previously-saved
+   * values when the host re-opens a form. `undefined` for a fresh mount.
+   * Prefer the `useRbFormData()` hook over reading this directly.
+   */
+  data?: unknown;
+
+  /**
+   * Register a getter the host calls (synchronously) to collect this plugin's
+   * save payload — e.g. when the host's Save button is clicked. The returned
+   * value must be JSON-serialisable (the host persists it). Returns an
+   * unregister fn. Prefer the `useRbSave()` hook.
+   */
+  onSave: (getPayload: () => unknown) => () => void;
 }
 
 const noopSdk: RbSdk = {
@@ -57,13 +84,29 @@ const noopSdk: RbSdk = {
     console.warn("[plugin-ui] rb.action called outside of a host context");
     return undefined as R;
   },
-  serve: async <P = any, R = any>(_topic?: string, _handler?: (payload?: P) => R) => {
+  serve: async <P = any, R = any>(
+    _topic?: string,
+    _handler?: (payload?: P) => R,
+  ) => {
     console.warn("[plugin-ui] rb.serve called outside of a host context");
     return { undeclare: async () => {} } as unknown as Queryable;
   },
-  toast: (message) => {
-    console.warn("[plugin-ui] rb.toast (no host):", message);
+  toast: (params) => {
+    console.warn("[plugin-ui] rb.toast (no host):", params);
+  },
+  alert: async (_) => {
+    console.warn("[plugin-ui] rb.alert called outside of a host context");
+  },
+  confirm: async (_) => {
+    console.warn("[plugin-ui] rb.confirm called outside of a host context");
+    return false;
+  },
+  prompt: async (_) => {
+    console.warn("[plugin-ui] rb.prompt called outside of a host context");
+    return undefined;
   },
+  data: undefined,
+  onSave: () => () => {},
 };
 
 export const RbContext = createContext<RbSdk>(noopSdk);
@@ -72,3 +115,28 @@ export const RbContext = createContext<RbSdk>(noopSdk);
 export function useRb(): RbSdk {
   return useContext(RbContext);
 }
+
+/**
+ * Read the host-provided initial data for this mount (e.g. previously-saved
+ * form values). `undefined` for a fresh mount.
+ *
+ *   const saved = useRbFormData<MyArgs>();
+ *   const methods = useForm({ defaultValues: saved ?? DEFAULTS });
+ */
+export function useRbFormData<T = unknown>(): T | undefined {
+  return useRb().data as T | undefined;
+}
+
+/**
+ * Register a getter the host calls to collect this plugin's save payload when
+ * the host's Save is clicked. The latest `getPayload` is always used, so it can
+ * close over current state. The returned value must be JSON-serialisable.
+ *
+ *   useRbSave(() => ({ args: getValues(), summary: buildSummary() }));
+ */
+export function useRbSave<T = unknown>(getPayload: () => T): void {
+  const rb = useRb();
+  const ref = useRef(getPayload);
+  ref.current = getPayload;
+  useEffect(() => rb.onSave(() => ref.current()), [rb]);
+}