@rainbow-robotics/plugin-ui 1.3.8-dev.4 → 1.10.1-dev.1

package/src/sdk.ts

@@ -1,175 +1,175 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Plugin runtime SDK (`useRb()`).
- *
- * 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, 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" → {pluginId}/sensor/data
-   * "/broadcast/x" → broadcast/x  (absolute)
-   */
-  pub: <P = any>(topic: string, payload: P) => Promise<void>;
-
-  /** Subscribe to a topic. Returns a handle with undeclare(). */
-  sub: <P = any>(
-    topic: string,
-    handler: (payload: P) => void,
-  ) => Promise<Subscriber>;
-
-  /**
-   * Send a request and await the first reply (Zenoh query).
-   * Use this to call a backend handler registered with rb.serve() / ZenohRouter.
-   */
-  action: <R = any, P = any>(topic: string, payload?: P) => Promise<R>;
-
-  /**
-   * Register a queryable — the frontend responds to backend queries.
-   * Mirror of rb.action() on the other side.
-   */
-  serve: <P = any, R = any>(
-    topic: string,
-    handler: (payload?: P) => R | Promise<R>,
-  ) => Promise<Queryable>;
-
-  /** Show a transient notification through the host's toast system. */
-  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"];
-
-  /** Push a step tree into the host Program page as an unsaved edit. */
-  program: PluginUIServices["program"];
-
-  /**
-   * 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;
-
-  /**
-   * PCs allowed to talk to this plugin's ROS 2 nodes. ROS discovery is robot-local
-   * (ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST); Muscat keeps this list per plugin, starts
-   * the plugin with ROS_STATIC_PEERS set to it, and restarts the plugin when it changes.
-   */
-  rosPeers: {
-    get: () => Promise<string[]>;
-    /** Saves the list and restarts the plugin backend. Rejects on an invalid IP. */
-    set: (peers: string[]) => Promise<string[]>;
-  };
-}
-
-const noopSdk: RbSdk = {
-  pub: async <P = any>(_topic?: string, _payload?: P) => {
-    console.warn("[plugin-ui] rb.pub called outside of a host context");
-  },
-  sub: async <P = any>(_topic?: string, _handler?: (payload: P) => void) => {
-    console.warn("[plugin-ui] rb.sub called outside of a host context");
-    return { undeclare: async () => {} } as unknown as Subscriber;
-  },
-  action: async <R = any, P = any>(_topic?: string, _payload?: P) => {
-    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,
-  ) => {
-    console.warn("[plugin-ui] rb.serve called outside of a host context");
-    return { undeclare: async () => {} } as unknown as Queryable;
-  },
-  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;
-  },
-  program: {
-    setSteps: async () => {
-      console.warn("[plugin-ui] rb.program called outside of a host context");
-    },
-    getCatalog: async () => {
-      console.warn("[plugin-ui] rb.program called outside of a host context");
-      return [];
-    },
-  },
-  data: undefined,
-  onSave: () => () => {},
-  rosPeers: {
-    get: async () => {
-      console.warn("[plugin-ui] rb.rosPeers called outside of a host context");
-      return [];
-    },
-    set: async () => {
-      console.warn("[plugin-ui] rb.rosPeers called outside of a host context");
-      return [];
-    },
-  },
-};
-
-export const RbContext = createContext<RbSdk>(noopSdk);
-
-/** Access the host SDK from within a plugin component. */
-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]);
-}
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Plugin runtime SDK (`useRb()`).
+ *
+ * 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, 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" → {pluginId}/sensor/data
+   * "/broadcast/x" → broadcast/x  (absolute)
+   */
+  pub: <P = any>(topic: string, payload: P) => Promise<void>;
+
+  /** Subscribe to a topic. Returns a handle with undeclare(). */
+  sub: <P = any>(
+    topic: string,
+    handler: (payload: P) => void,
+  ) => Promise<Subscriber>;
+
+  /**
+   * Send a request and await the first reply (Zenoh query).
+   * Use this to call a backend handler registered with rb.serve() / ZenohRouter.
+   */
+  action: <R = any, P = any>(topic: string, payload?: P) => Promise<R>;
+
+  /**
+   * Register a queryable — the frontend responds to backend queries.
+   * Mirror of rb.action() on the other side.
+   */
+  serve: <P = any, R = any>(
+    topic: string,
+    handler: (payload?: P) => R | Promise<R>,
+  ) => Promise<Queryable>;
+
+  /** Show a transient notification through the host's toast system. */
+  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"];
+
+  /** Push a step tree into the host Program page as an unsaved edit. */
+  program: PluginUIServices["program"];
+
+  /**
+   * 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;
+
+  /**
+   * PCs allowed to talk to this plugin's ROS 2 nodes. ROS discovery is robot-local
+   * (ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST); Muscat keeps this list per plugin, starts
+   * the plugin with ROS_STATIC_PEERS set to it, and restarts the plugin when it changes.
+   */
+  rosPeers: {
+    get: () => Promise<string[]>;
+    /** Saves the list and restarts the plugin backend. Rejects on an invalid IP. */
+    set: (peers: string[]) => Promise<string[]>;
+  };
+}
+
+const noopSdk: RbSdk = {
+  pub: async <P = any>(_topic?: string, _payload?: P) => {
+    console.warn("[plugin-ui] rb.pub called outside of a host context");
+  },
+  sub: async <P = any>(_topic?: string, _handler?: (payload: P) => void) => {
+    console.warn("[plugin-ui] rb.sub called outside of a host context");
+    return { undeclare: async () => {} } as unknown as Subscriber;
+  },
+  action: async <R = any, P = any>(_topic?: string, _payload?: P) => {
+    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,
+  ) => {
+    console.warn("[plugin-ui] rb.serve called outside of a host context");
+    return { undeclare: async () => {} } as unknown as Queryable;
+  },
+  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;
+  },
+  program: {
+    setSteps: async () => {
+      console.warn("[plugin-ui] rb.program called outside of a host context");
+    },
+    getCatalog: async () => {
+      console.warn("[plugin-ui] rb.program called outside of a host context");
+      return [];
+    },
+  },
+  data: undefined,
+  onSave: () => () => {},
+  rosPeers: {
+    get: async () => {
+      console.warn("[plugin-ui] rb.rosPeers called outside of a host context");
+      return [];
+    },
+    set: async () => {
+      console.warn("[plugin-ui] rb.rosPeers called outside of a host context");
+      return [];
+    },
+  },
+};
+
+export const RbContext = createContext<RbSdk>(noopSdk);
+
+/** Access the host SDK from within a plugin component. */
+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]);
+}