@kemu-io/hs-react 0.2.36 → 0.2.38

package/cjs/types/widgetUI_t.d.ts

@@ -0,0 +1,536 @@
+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;
+	fileName?: 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;
+	/**
+	 * If true, the port will be highlighted in the UI
+	 * to indicate events on this port will start the
+	 * processor execution.
+	 */
+	triggerPort?: boolean;
+};
+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 ValidPlatformArch = "win-x64" | "win-x86" | "win-arm" | "win-arm64" | "osx-x64" | "osx-arm64";
+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;
+	/** Id of the user that published the service */
+	author: string;
+	/** id of the item in the marketplace */
+	publicationId?: string;
+	/**
+	 * 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;
+	};
+	/**
+	 * A list of platforms that this service supports.
+	 * If not provided, it will default to 'win-x86', 'win-x64', 'osx-x64' and 'osx-arm64'.
+	 */
+	supportedPlatforms?: ValidPlatformArch[];
+};
+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 WidgetRenderArgs = {
+	/** indicates if the Hub service is currently online */
+	serviceOnline: boolean;
+	/** indicates if this Widget is currently disabled */
+	disabled: boolean;
+};
+export type WidgetUIInstance = {
+	/** unmounts the component */
+	destroy: () => void;
+	/**
+	 * re-renders the component by triggering
+	 * an internal state change.
+	 **/
+	render: (a?: WidgetRenderArgs) => void;
+	handleParentEvent: ServiceParentEventHandler | null;
+	handleBroadcastEvent: ServiceBroadcastEventHandler | null;
+	handleSetOutputsEvent: ServiceSetOutputsEventHandler | null;
+};
+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 {};

package/mjs/WidgetWrapper.d.ts

@@ -1,5 +1,3 @@
-// Generated by dts-bundle-generator v9.5.1
-
 import React$1 from 'react';
 
 export type Rect = {
@@ -14,6 +12,7 @@ export type Point = {
 };
 export type BinaryFile<D extends ArrayBuffer | Uint8Array | Uint8ClampedArray | Buffer = ArrayBuffer> = {
 	format: string;
+	fileName?: string;
 	data: D;
 };
 declare enum DataType {
@@ -121,6 +120,12 @@ export type WidgetPort = {
 	jsonShape?: JsonTypeShape;
 	/** help description markdown */
 	description?: string;
+	/**
+	 * If true, the port will be highlighted in the UI
+	 * to indicate events on this port will start the
+	 * processor execution.
+	 */
+	triggerPort?: boolean;
 };
 export type WidgetState<T extends Record<string, any> = Record<string, unknown>> = T;
 export type TargetOutput = {
@@ -174,6 +179,7 @@ export type ServiceWidgetVariant<P extends WidgetPort | WidgetPortStr> = {
 	inputs?: P[];
 	outputs?: P[];
 };
+export type ValidPlatformArch = "win-x64" | "win-x86" | "win-arm" | "win-arm64" | "osx-x64" | "osx-arm64";
 export type ServiceManifest<P extends WidgetPort | WidgetPortStr> = {
 	/** the unique name defined by the service */
 	name: string;
@@ -185,6 +191,10 @@ export type ServiceManifest<P extends WidgetPort | WidgetPortStr> = {
 	shortTitle?: string;
 	description: string;
 	processor: ProcessorType;
+	/** Id of the user that published the service */
+	author: string;
+	/** id of the item in the marketplace */
+	publicationId?: string;
 	/**
 	 * if true, it indicates other services can subscribe
 	 * to events emitted by this service. Only services
@@ -292,6 +302,11 @@ export type ServiceManifest<P extends WidgetPort | WidgetPortStr> = {
 	requiredSecrets?: {
 		[name: string]: ServiceSecret;
 	};
+	/**
+	 * A list of platforms that this service supports.
+	 * If not provided, it will default to 'win-x86', 'win-x64', 'osx-x64' and 'osx-arm64'.
+	 */
+	supportedPlatforms?: ValidPlatformArch[];
 };
 export type ServiceWidgetInfo = {
 	name: string;

package/mjs/components/ResizableContainer.d.ts

@@ -0,0 +1,71 @@
+import { CSSObject } from '@emotion/styled';
+import React$1 from 'react';
+import { CSSProperties } from 'react';
+
+export type ResizableContainerProps = {
+	css?: CSSObject;
+	minWidth?: number;
+	minHeight?: number;
+	maxWidth?: number;
+	maxHeight?: number;
+	defaultWidth?: number;
+	defaultHeight?: number;
+	children: React$1.ReactNode;
+	/**
+	 * The lockAspectRatio property is used to lock aspect ratio. Set to true to lock
+	 * the aspect ratio based on the initial size. Set to a numeric value to lock a
+	 * specific aspect ratio (such as 16/9). If set to numeric, make sure to set initial
+	 * height/width to values with correct aspect ratio. If omitted, set false.
+	 */
+	lockAspectRatio?: boolean | number;
+	/**
+	 * Callback when the component is being resized.
+	 */
+	onResize?: (width: number, height: number, originalEvent: MouseEvent | TouchEvent) => void;
+	/**
+	 * Callback when the component has been resized.
+	 */
+	onStopResize?: (width: number, height: number, originalEvent: MouseEvent | TouchEvent) => void;
+};
+export type WrapperProps = {
+	cWidth?: number | string;
+	cHeight?: number | string;
+	noPadding?: boolean;
+	noBorderRadius?: boolean;
+	className?: string;
+	style?: React$1.CSSProperties;
+};
+/**
+ * A resizable container for the widget's canvas. It implements styles to handle
+ * the widget's appearance when selected or offline.
+ *
+ * @example
+ * ```tsx
+ * import packageJson from '../package.json';
+ * import { CustomWidgetProps, components, createWidgetUI } from '@kemu-io/hs-react';
+ *
+ * const { ResizableContainer } = components;
+ *
+ * const MyWidgetUI = (props: CustomWidgetProps) => {
+ *
+ *   const handleResize = useCallback((width: number, height: number) => {
+ *     console.log('Widget resized: ', width, height);
+ *   }, []);
+ *
+ *   return (
+ *     <ResizableContainer>
+ *       <button>Click Me</button>
+ *     </ResizableContainer>
+ *   );
+ * };
+ *
+ * export default createWidgetUI(MyWidgetUI, packageJson.name, packageJson.version);
+ * ```
+ */
+declare const ResizableContainer: (props: ResizableContainerProps & WrapperProps) => import("react/jsx-runtime.js").JSX.Element;
+
+export {
+	ResizableContainer as default,
+};
+
+export {};

package/mjs/components/WidgetContainer.d.ts

@@ -0,0 +1,20 @@
+export type WrapperProps = {
+	cWidth?: number | string;
+	cHeight?: number | string;
+	noPadding?: boolean;
+	noBorderRadius?: boolean;
+};
+export type WidthLessProps = Omit<WrapperProps, "cWidth" | "cHeight"> & {
+	width?: number | string;
+	height?: number | string;
+	children: React.ReactNode;
+	className?: string;
+	style?: React.CSSProperties;
+};
+declare const Wrap: (p: WidthLessProps) => import("react/jsx-runtime.js").JSX.Element;
+
+export {
+	Wrap as default,
+};
+
+export {};