@kemu-io/hs-react 0.2.36 → 0.2.37

package/cjs/hooks/useOnParentEvent.d.ts

@@ -0,0 +1,545 @@
+export type Rect = {
+	width: number;
+	height: number;
+	top: number;
+	left: number;
+};
+export type Point = {
+	x: number;
+	y: number;
+};
+export type BinaryFile<D extends ArrayBuffer | Uint8Array | Uint8ClampedArray | Buffer = ArrayBuffer> = {
+	format: string;
+	data: D;
+};
+declare enum DataType {
+	Number = 0,
+	String = 1,
+	ArrayBuffer = 2,
+	Array = 3,
+	Boolean = 4,
+	/** a javascript object */
+	JsonObj = 5,
+	/**
+	 * Does not care; mostly used by actions to indicate they accept anything since they probably won't use the
+	 * value.
+	 **/
+	Anything = 6,
+	/** Raw image data, produced in browser environments */
+	ImageData = 7,
+	/** Raw audio data fraction */
+	AudioBuffer = 8,
+	Rect = 9,
+	Point = 10,
+	ImageBitmap = 11,
+	/**
+	 * Custom binary data. Use the `format` property to specify the type of data, i.e. 'image/png', 'audio/mp3', etc.
+	 **/
+	BinaryFile = 12
+}
+export type JsonType = {
+	[key: string]: SupportedTypes;
+};
+export type KemuType = number | string | ArrayBuffer | JsonType | boolean | ImageData | AudioBuffer | Rect | Point | ImageBitmap | BinaryFile;
+export type SupportedTypes = KemuType | KemuType[];
+/** Type passed around between gates and blocks */
+export type Data = {
+	/** the type of data represented  */
+	type: DataType;
+	value: SupportedTypes;
+	/** original time when the event was first picked up by an input gate. */
+	timestamp: number;
+};
+/**
+ * Describe the shape of objects. For example:
+ *
+ * Given the following object:
+ * ```
+ * const obj = {
+ *   property1: 12,
+ *   property2: 'Hello'
+ * };
+ * ```
+ *
+ * The shape definition would be:
+ * ```
+ * {
+ *   'property1': DataType.Number,
+ *   'property2': DataType.String,
+ * }
+ * ```
+ *
+ * Use a JsonPrimitiveFormat (`$$primitive_{x}`) to specify the type of an array of primitive objects,
+ * where 'x' is the index in the array the value of the property belongs to. For example:
+ *
+ * An event with `[1, 'hi', {other: 'yes}]` would produce the following jsonShape:
+ *
+ * ```
+ * {
+ *   '$$primitive_0': DataType.Number,
+ *   '$$primitive_1': DataType.String,
+ *   '$$primitive_2': DataType.JsonObj,
+ * }
+ * ```
+ *
+ * If no primitive index is specified, the system assumes all the items in the array
+ * will have the given primitive type. For example:
+ *
+ * An array of `[1, 2, 3, 4]` should be described as:
+ * ```
+ * {
+ *   '$$primitive': DataType.Number
+ * }
+ * ```
+ */
+export type JsonTypeShape = {
+	[key: string]: DataType;
+};
+/**
+ * Used by Widget (formerly known as Gates) modules when defining their
+ * input/output port list
+ */
+export type WidgetPort = {
+	/** a unique identifier (in the context of the widget) for this port. */
+	name: string;
+	/** alternative label used to replace the name for presentation purposes only */
+	label?: string;
+	/** Type of data the port accepts or produces, an array indicates the gate can receive multiple types */
+	type: DataType | DataType[];
+	/**
+	 * If true, processors won't be invoked until at least an event is received in this port.
+	 */
+	required?: boolean;
+	/**
+	 * Describes the shape of a JSON object when dataType == JsonObj. Or the shape of items
+	 * when dataType == Array
+	 */
+	jsonShape?: JsonTypeShape;
+	/** help description markdown */
+	description?: string;
+};
+export type WidgetState<T extends Record<string, any> = Record<string, unknown>> = T;
+export type TargetOutput = {
+	/**
+	 * the name of the port the `data` will be sent from.
+	 * This name MUST match one of the ports
+	 * returned by the `getOutputs` function or defined in the widget
+	 * manifest. If the name does not match, the data will not be sent.
+	 **/
+	name: string;
+	/**
+	 * The data to send to the output port.
+	 * If the value is `undefined` or `null`, no data will be sent.
+	 * Also, the data type MUST match the type defined in the widget manifest.
+	 */
+	value: SupportedTypes | undefined | null;
+	/**
+	 * the data type of the value being sent.
+	 * This value is automatically inferred from the widget manifest.
+	 **/
+	type: DataType;
+	/** id of the variant that defined the output */
+	variantId?: string;
+};
+export type WidgetPortStr = Omit<WidgetPort, "type"> & {
+	type: string;
+};
+declare enum ProcessorType {
+	Javascript = "js",
+	Python = "py",
+	Executable = "exe"
+}
+export type ServiceSecret = {
+	/** a markdown description of the secret */
+	description: string;
+	/** if true, the secret is optional and the service will still start if the secret is not provided */
+	optional?: boolean;
+};
+export type ServiceWidgetVariant<P extends WidgetPort | WidgetPortStr> = {
+	/** unique identifier for the variant */
+	id: string;
+	name: string;
+	description: string;
+	/**
+	 * custom color for the variant. If not provided, the main
+	 * color defined in the manifest will be used.
+	 **/
+	color?: string;
+	/** SVG icon data */
+	svgIcon?: string;
+	inputs?: P[];
+	outputs?: P[];
+};
+export type ServiceManifest<P extends WidgetPort | WidgetPortStr> = {
+	/** the unique name defined by the service */
+	name: string;
+	/** a unique identifier given during startup */
+	version: string;
+	/** a service title for UI purposes */
+	title?: string;
+	/** a shorten title to be used in the canvas */
+	shortTitle?: string;
+	description: string;
+	processor: ProcessorType;
+	/**
+	 * if true, it indicates other services can subscribe
+	 * to events emitted by this service. Only services
+	 * with `eventEmitter` set to true can use `broadcast`
+	 * to emit events.
+	 */
+	eventEmitter?: boolean;
+	/**
+	 * Specifies the default timeout in seconds when a parentEvent is received.
+	 * This is used to discard events that take too long to process.
+	 * Set to 0 to disable the timeout. Warning this may
+	 * cause some parent widgets to hang indefinitely if the child
+	 * widget does not respond to the event.
+	 **/
+	processingTimeoutSec?: number;
+	/**
+	 * if true, parent events sent to this widget will
+	 * be resolved immediately, meaning the parent widget
+	 * will not have to wait for this service to respond
+	 * before continuing execution.
+	 */
+	asyncParentEvents?: boolean;
+	/**
+	 * if true, it indicates the service is only meant to be used in a
+	 * web environment. The widget won't work when exported.
+	 */
+	webOnly?: boolean;
+	/**
+	 * if set the service will only receive env vars that start with this prefix.
+	 * Use it to isolate the information services have access to.
+	 * Eg:
+	 * - `KEMU_{CUSTOM_PREFIX}_DB_URL`: Your service will receive this env var as `DB_URL`
+	 *
+	 * Remember that only variables that start with `KEMU_` are forwarded to services.
+	 */
+	envVarPrefix?: string;
+	color?: string;
+	svgIcon?: string;
+	/**
+	 * Flags this service as internal. Internal services are not
+	 * meant to be used by the end-user. Attempts to use an internal service
+	 * will likely result in an error.
+	 */
+	internal?: boolean;
+	/**
+	 * if true, the service is expected to have a `widgetUI.js` file in the root directory
+	 * that will be used to mount a new UI onto the canvas.
+	 **/
+	widgetUI?: boolean;
+	/**
+	 * If true, the processor won't be forwarded any parent events.
+	 * Use it when you have a widget with custom UI that performs all processing
+	 * inside of its own component. Keep in mind that when exported, any processing
+	 * logic that does not exist in the processor will not be available in the exported
+	 * recipe.
+	 */
+	ignoreParentEvents?: boolean;
+	/**
+	 * A list of relative paths to `txt` files where custom widget clipboard data are stored. Eg:
+	 * ```json
+	 * {
+	 *  "customWidgets": [
+	 *    "customWidgets/widget1.txt",
+	 *    "customWidgets/widget2.txt",
+	 *  ]
+	 * }
+	 * ```
+	 * This will cause the service to be rendered as a folder with the custom widgets as sub-widgets.
+	 */
+	customWidgets?: string[];
+	/**
+	 * A list of widget variants that can be selected by the user.
+	 * All variants will invoke the same processor, but they can have different input/output ports
+	 * and be visually distinct.
+	 */
+	variants?: ServiceWidgetVariant<P>[];
+	/**
+	 * A list of relative paths to folders containing extra services that are part of this service. Eg:
+	 * ```json
+	 * {
+	 *  "subServices": [
+	 *    "subServices/subService1",
+	 *    "subServices/subService2",
+	 *  ]
+	 * }
+	 * ```
+	 *
+	 * Each folder should contain all the required files that represent a service (manifest, processor, etc).
+	 */
+	subServices?: string[];
+	/** the list of input ports. If not provided,
+	 * `dynamicInputs` MUST be set to true, or loading the
+	 * widget will fail.
+	 */
+	inputs: P[];
+	/**
+	 * the list of output ports. If not provided,
+	 * `dynamicOutputs` MUST be set to true, or loading the
+	 * widget will fail.
+	 */
+	outputs: P[];
+	/**
+	 * A map of secret names to their descriptions
+	 */
+	requiredSecrets?: {
+		[name: string]: ServiceSecret;
+	};
+};
+export type ServiceWidgetInfo = {
+	name: string;
+	icon?: string;
+	color?: string;
+	description: string;
+	contents: string;
+	/**
+	 * The id of the first root group in the widget.
+	 * Keep in mind this id will be re-generated when the widget is added to the canvas.
+	*/
+	rootGroupId: string;
+	protocolVersion: string;
+};
+/**
+ * This is the output of the service library after processing its own manifest file.
+ */
+export type PartiallyProcessedManifest<B extends Buffer | ArrayBuffer = Buffer, SM extends WidgetPort | WidgetPortStr = WidgetPortStr> = ServiceManifest<SM> & {
+	widgetUIContents?: B;
+	uiContentChecksum?: string;
+	/** path to the root directory where the service resides */
+	path: string;
+	/** added by the service automatically when the service is running in dev mode */
+	readonly devMode?: boolean;
+};
+/**
+ * This is the output of the Hub after combining a PartiallyProcessedManifest and processing variants, sub-services and custom widgets.
+ */
+export type ProcessedManifest<B extends Buffer | ArrayBuffer = Buffer> = Omit<PartiallyProcessedManifest<B, WidgetPort>, "customWidgets"> & {
+	customWidgets?: ServiceWidgetInfo[];
+	/** if present, it indicates this service is a sub-service of another service */
+	parentService?: {
+		name: string;
+		version: string;
+	};
+};
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
+	[K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+}[Keys];
+export type DefineDynamicPortsArgs = RequireAtLeastOne<{
+	/**
+	 * Set to null to remove any previously defined ports or
+	 * set to an empty array to remove ports from the widget.
+	 */
+	outputs?: WidgetPort[] | null;
+	/**
+	 * Set to null to remove any previously defined ports or
+	 * set to an empty array to remove ports from the widget.
+	 */
+	inputs?: WidgetPort[] | null;
+}, "outputs" | "inputs"> & {
+	/** the id of the variant this definition applies to */
+	variantId?: string;
+};
+export type UseWidgetStateResponse<T extends WidgetState = WidgetState> = {
+	/**
+	 * the current state of the widget at the time the hook was created.
+	 * This state is not reactive and will not trigger a re-render when the state changes.
+	 **/
+	state: Readonly<T>;
+	/**
+	 * @returns the current state of the widget. This function is memoized and will always return the latest state.
+	 */
+	getState: () => Readonly<T>;
+	/**
+	 * Updates the state of the widget.
+	 * @param newState the new state to set.
+	 * @param triggerEvents if true, the widget will notify listeners that its state has changed. Default is true.
+	 */
+	setState: (newState: T, triggerEvents?: boolean) => void;
+};
+/**
+ * @returns the current state and a memoized function to get the current state.
+ */
+export type UseWidgetStateHook<T extends WidgetState = WidgetState> = () => UseWidgetStateResponse<T>;
+export type DeepReadOnly<T> = T extends (infer R)[] ? ReadonlyArray<DeepReadOnly<R>> : T extends object ? {
+	readonly [K in keyof T]: DeepReadOnly<T[K]>;
+} : T;
+export type DeepReadOnlyArray<T> = ReadonlyArray<DeepReadOnly<T>>;
+export type ServiceParentEvent = {
+	/** information about the widget producing */
+	sourceWidget: {
+		id: string;
+		port: string;
+	};
+	targetPort: string;
+	data: Data;
+};
+export type BroadcastEvent = {
+	outputs: TargetOutput[];
+	source: {
+		serviceName: string;
+		serviceVersion: string;
+		sessionId: number;
+	};
+};
+export type ServiceParentEventHandler = (event: ServiceParentEvent) => void | Promise<void>;
+export type ServiceBroadcastEventHandler = (event: DeepReadOnly<BroadcastEvent>) => void | Promise<void>;
+export type ServiceSetOutputsEventHandler = (outputs: DeepReadOnlyArray<TargetOutput>) => void | Promise<void>;
+export type LimitedManifest = Omit<ProcessedManifest, "widgetUIContents" | "settingsUIContents" | "path">;
+export type ReactWidgetUtils = {
+	/**
+	 * Shows a native dialog to choose a file.
+	 * @returns a promise that resolves to the paths of the chosen files.
+	 **/
+	showChooseFileDialog: (args: {
+		title?: string;
+		fileTypes?: string[];
+		allowMultiple?: boolean;
+	}) => Promise<string[]>;
+	/**
+	 * Shows a native dialog to choose a directory.
+	 * @returns a promise that resolves to the path of the chosen directory.
+	 */
+	showChooseDirectoryDialog: (args: {
+		title?: string;
+	}) => Promise<string>;
+	browser: {
+		/**
+		 * @returns the Cache Storage path for the given file
+		 **/
+		getCacheFilePath: (fileName: string) => string;
+		/**
+		 * Adds the given data to the service cache
+		 * @param filePath the full path of the file, including the file name and extension
+		 * @param data the raw data to store
+		 * @param headers optional response headers
+		 * @returns
+		 */
+		cacheFile: (filePath: string, data: string | ArrayBuffer | Uint8Array | Uint8ClampedArray | Blob, headers?: Headers) => Promise<void>;
+		/**
+		 * Attempts to load the file from the cache storage
+		 * @param filePath full path of the file, including the file name and extension
+		 * @returns the cached file or undefined if the file is not found
+		 */
+		getCachedFile: (filePath: string) => Promise<Response | undefined>;
+		/**
+		 * Removes the file from the cache storage. If path does not exist, nothing happens.
+		 * @param filePath full path of the file, including the file name and extension
+		 */
+		removeCachedFile: (filePath: string) => Promise<void>;
+		/**
+		 * Removes all entries linked to this service
+		 */
+		clearServiceCache: () => Promise<void>;
+	};
+};
+export type CustomWidgetProps = {
+	/** the id of this widget in the recipe */
+	readonly widgetId: string;
+	/** the id of the recipe */
+	readonly recipeId: string;
+	/** the widget variant that was added to the workspace */
+	readonly variantId?: string;
+	/** the manifest file of the running service */
+	manifest: DeepReadOnly<LimitedManifest>;
+	serviceOnline: boolean;
+	disabled: boolean;
+	/**
+	 * Redraws the ports and their connections.
+	 * Useful when the size of your widget changes dynamically.
+	 **/
+	repaintPorts: () => void;
+	/**
+	 * Sets the value of the outputs of the widget.
+	 * IMPORTANT: Keep in mind that port changes triggered from UI components won't work
+	 * when the recipe is exported as a standalone service.
+	 **/
+	setOutputs: GlobalContext["setOutputs"];
+	/**
+	 * Invokes an `onUIEvent` in the processor file.
+	 * @param name the name of the handler to be called.
+	 * @returns a promise that resolves to the return value of the processor handler.
+	 **/
+	callProcessorHandler: <R = any>(name: string, data?: any) => Promise<R>;
+	/**
+	 * Allows the UI instance to change the default
+	 * ports definition of a widget service based on custom logic. The interface
+	 * will repaint the ports for the given widget accordingly.
+	 *
+	 * Keep in mind that calling this method while attached to other widgets will
+	 * automatically remove the links with any parent or child widget.
+	 **/
+	defineDynamicPorts: (config: DefineDynamicPortsArgs) => Promise<void>;
+	/**
+	 * Utility functions
+	 */
+	utils: ReactWidgetUtils;
+};
+export type WidgetCanvasDimensions = {
+	width: number;
+	height: number;
+};
+export type Output = Omit<TargetOutput, "value"> & {
+	value: SupportedTypes;
+};
+export type GlobalContext<T extends WidgetState = WidgetState> = {
+	useWidgetState: UseWidgetStateHook<T>;
+	setOutputs: (outputs: Output[]) => Promise<void>;
+	defineDynamicPorts: (config: DefineDynamicPortsArgs) => Promise<void>;
+	callProcessorHandler: <R = any>(name: string, data?: any) => Promise<R>;
+	setWidgetDimensions: (width: number, height: number) => void;
+	getWidgetDimensions: () => WidgetCanvasDimensions;
+	utils: ReactWidgetUtils;
+	widgetId: string;
+	recipeId: string;
+	variantId?: string;
+	manifest: LimitedManifest;
+};
+export type InstanceContext = {
+	/** defines an event listener to be invoked when a parent widgets sends data to this widget */
+	useOnParentEvent: (cb: ServiceParentEventHandler) => void;
+	/** Defines an event listener to be invoked when the processor produces a broadcast event */
+	useOnBroadcastEvent: (cb: ServiceBroadcastEventHandler) => void;
+	/** Defines an event listener to be invoked when the processor calls `setOutputs()` */
+	useOnSetOutputsEvent: (cb: ServiceSetOutputsEventHandler) => void;
+	/**
+	 * Sets the dimensions of the widget's canvas. It's used to automatically restore
+	 * the widget's size when the recipe is re-loaded.
+	 **/
+	setWidgetDimensions: (width: number, height: number) => void;
+	getWidgetDimensions: () => WidgetCanvasDimensions;
+	/** returns the original props passed to a widget instance */
+	getWidgetProps: () => CustomWidgetProps;
+};
+/**
+ * defines an event listener to be invoked when a parent widgets sends data to this widget.
+ * @param cb the event handler to be invoked.
+ * @example
+ *
+ * ```tsx
+ *  const MyWidget = () => {
+ *    const [parentValue, setParentValue] = useState(0);
+ *
+ *    // A parent widget sends data to this widget
+ *    useOnParentEvent((evt) => {
+ *      console.log(`Parent is sending data to port ${evt.targetPort}`)
+ *      setParentValue(evt.data.value);
+ *    });
+ *
+ *    return (
+ *     <div>
+ *       <p>Parent value: {parentValue}</p>
+ *     </div>
+ *    );
+ *  }
+ * ```
+ **/
+declare const useOnParentEvent: InstanceContext["useOnParentEvent"];
+
+export {
+	useOnParentEvent as default,
+};
+
+export {};