@bonsae/nrg 0.22.0 → 0.22.2

package/types/shims/client/types.d.ts

@@ -0,0 +1,227 @@
+import type { Component, App } from "vue";
+import type { TSchema, Static } from "@sinclair/typebox";
+import type { SchemaObject } from "ajv";
+import type { NodeRefResolved, TypedInputResolved } from "../brands";
+import type { JsonSchemaObjectExtensions } from "../schema-options";
+export interface NodeStateCredentials {
+    [key: string]: any;
+}
+export interface NodeState {
+    credentials: NodeStateCredentials;
+    [key: string]: any;
+}
+export interface NodeButtonDefinition {
+    toggle: string;
+    onClick: () => void;
+    enabled?: () => boolean;
+    visible?: () => boolean;
+}
+export interface NodeRedNodeButtonDefinition {
+    toggle: string;
+    onclick: () => void;
+    enabled?: () => boolean;
+    visible?: () => boolean;
+}
+export interface NodeFormDefinition {
+    component?: Component;
+}
+export interface NodeRedNode {
+    id: string;
+    type: string;
+    name: string;
+    category: string;
+    x: string;
+    y: string;
+    g: string;
+    z: string;
+    credentials: Record<string, any>;
+    _def: {
+        defaults: Record<string, {
+            value: string;
+            type?: string;
+            label?: string;
+            required?: boolean;
+        }>;
+        credentials: Record<string, {
+            value: string;
+            type?: "password" | "text";
+            label?: string;
+            required?: boolean;
+        }>;
+        category: string;
+        color?: string;
+        icon?: string;
+        label?: ((this: NodeRedNode) => string) | string;
+        inputs?: number;
+        outputs?: number;
+        paletteLabel?: ((this: NodeRedNode) => string) | string;
+        labelStyle?: ((this: NodeRedNode) => string) | string;
+        inputLabels?: ((this: NodeRedNode, index: number) => string) | string;
+        outputLabels?: ((this: NodeRedNode, index: number) => string) | string;
+        align?: "left" | "right";
+        button?: NodeRedNodeButtonDefinition;
+    };
+    _newState?: NodeRedNode;
+    _app?: App | null;
+    _: (str: string) => string;
+    /** dynamic port count (base outputs + enabled built-in ports) */
+    outputs?: number;
+    /** injected when the node has an inputSchema */
+    validateInput?: boolean;
+    /** built-in port toggles, present when declared in the configSchema */
+    errorPort?: boolean;
+    completePort?: boolean;
+    statusPort?: boolean;
+    /**
+     * Per-port output settings, indexed by base-output port. `validateOutputs` is
+     * injected (empty) when the node has an outputsSchema; `outputReturnProperties`
+     * and `outputContextModes` are author-declared (SchemaType.*) — present only
+     * when the node opts into per-port return keys / context modes. Read at
+     * runtime by IONode.
+     */
+    validateOutputs?: Record<number, boolean>;
+    outputContextModes?: Record<number, "carry" | "trace" | "reset">;
+    outputReturnProperties?: Record<number, string>;
+    [key: string]: any;
+}
+export interface NodeDefinition {
+    type: string;
+    category?: string;
+    color?: string;
+    icon?: ((this: NodeRedNode) => string) | string;
+    label?: ((this: NodeRedNode) => string) | string;
+    inputs?: number;
+    outputs?: number;
+    paletteLabel?: ((this: NodeRedNode) => string) | string;
+    labelStyle?: ((this: NodeRedNode) => string) | string;
+    inputLabels?: ((this: NodeRedNode, index: number) => string) | string;
+    outputLabels?: ((this: NodeRedNode, index: number) => string) | string;
+    align?: "left" | "right";
+    button?: NodeButtonDefinition;
+    onEditResize?: (this: NodeRedNode, size: {
+        width: number;
+        height: number;
+    }) => void;
+    onPaletteAdd?: (this: NodeRedNode) => void;
+    onPaletteRemove?: (this: NodeRedNode) => void;
+    form?: NodeFormDefinition;
+}
+/** Form rendering hints carried by the `x-nrg-form` schema keyword. */
+export type NrgFormOptions = NonNullable<JsonSchemaObjectExtensions["x-nrg-form"]>;
+/**
+ * A serialized property schema inside {@link JsonSchemaObject} `properties`,
+ * including NRG's custom keywords (shared vocabulary in core/schema-options)
+ * that drive form rendering and NodeRef/TypedInput identification.
+ */
+export interface JsonPropertySchema extends JsonSchemaObjectExtensions {
+    type?: string | string[];
+    properties?: Record<string, JsonPropertySchema>;
+    required?: string[];
+    enum?: unknown[];
+    anyOf?: JsonPropertySchema[];
+    const?: unknown;
+    items?: JsonPropertySchema;
+    title?: string;
+    description?: string;
+    default?: unknown;
+}
+/**
+ * A serialized JSON Schema object as the build pipeline emits it (never a
+ * live TypeBox instance). Extends ajv's `SchemaObject` so it flows into
+ * validator APIs without casts, while keeping the `type: "object"`
+ * discriminant and structured `properties`/`required` that ajv's open
+ * `[x: string]: any` shape does not provide.
+ */
+export interface JsonSchemaObject extends SchemaObject {
+    type: "object";
+    properties?: Record<string, JsonPropertySchema>;
+    required?: string[];
+}
+/**
+ * A node definition as it exists at editor runtime, after the build pipeline
+ * merged in the schema-derived artifacts (defaults, credentials, serialized
+ * schemas). Authors write {@link NodeDefinition}; the inliner provides the
+ * rest.
+ */
+export interface RuntimeNodeDefinition extends NodeDefinition {
+    defaults?: NodeDefaults;
+    credentials?: NodeCredentials;
+    /**
+     * Names of the base output ports when `outputsSchema` is a record of named
+     * ports, in declaration order; absent for single/positional outputs. Resolved
+     * server-side by the inliner so the editor never guesses port names from the
+     * serialized schema.
+     */
+    outputPortNames?: string[];
+    configSchema?: JsonSchemaObject;
+    credentialsSchema?: JsonSchemaObject;
+    inputSchema?: JsonSchemaObject;
+    /**
+     * Single port, positional ports, or named ports (key = port name).
+     * Not constrained to object schemas: with returnProperty the raw sent
+     * value is validated, so results may be any schema shape.
+     */
+    outputsSchema?: JsonPropertySchema | JsonPropertySchema[] | Record<string, JsonPropertySchema>;
+}
+export interface NodeDefaults {
+    [key: string]: {
+        value: any;
+        type?: string;
+        label?: string;
+        required?: boolean;
+        validate?: (this: NodeRedNode, value: any, opt: any) => any;
+    };
+}
+export interface NodeCredentials {
+    [key: string]: {
+        value?: string;
+        type?: "password" | "text";
+        label?: string;
+        required?: boolean;
+    };
+}
+export interface NodeFeatures {
+    hasInputSchema: boolean;
+    hasOutputSchema: boolean;
+    /**
+     * Base output ports (excludes built-in error/complete/status), in port-index
+     * order. Drives the per-port context-mode rows in the Outputs subsection.
+     */
+    outputPorts: {
+        index: number;
+        label: string;
+    }[];
+}
+/** Client-side representation of a TypedInput field: the raw value string and its type selector. */
+export interface TypedInputValue {
+    value: string;
+    type: string;
+}
+/**
+ * Maps a schema's static type to the raw values the editor form holds.
+ * The server counterpart (`ResolvedStatic` in server/schemas/types) maps the
+ * same brands — shared via core/brands — to resolved runtime values instead.
+ * - `NodeRef<T>` → `string` (the referenced node's id)
+ * - `TypedInput<T>` → `TypedInputValue` (raw value + type pair)
+ * - Functions pass through, arrays and objects map recursively
+ */
+export type EditorStatic<T> = T extends NodeRefResolved<any> ? string : T extends TypedInputResolved ? TypedInputValue : T extends (...args: any[]) => any ? T : T extends Array<infer I> ? EditorStatic<I>[] : T extends object ? {
+    [K in keyof T]: EditorStatic<T[K]>;
+} : T;
+/**
+ * Infers the client-side TypeScript type from a TypeBox schema.
+ *
+ * Resolves schema types to their client form representations:
+ * - `NodeRef<T>` → `string` (node ID in the editor)
+ * - `TypedInput<T>` → `{ value: string; type: string }`
+ * - All other types resolve via TypeBox's `Static<T>`
+ *
+ * @example
+ * ```ts
+ * import type { Infer } from "@bonsae/nrg/client";
+ * import type { ConfigSchema } from "../schemas/my-node";
+ *
+ * type Config = Infer<typeof ConfigSchema>;
+ * ```
+ */
+export type Infer<T extends TSchema> = EditorStatic<Static<T>>;

package/types/shims/components.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Global component type declarations for Volar / Vue Language Server.
+ * Auto-generated during build — do not edit manually.
+ */
+
+export {};
+
+declare module "vue" {
+  export interface ComponentCustomProperties {
+    $i18n: (label: string) => string;
+  }
+
+  export interface GlobalComponents {
+    NodeRedConfigInput: (typeof import("./client/form/components/node-red-config-input.vue"))["default"];
+    NodeRedEditorInput: (typeof import("./client/form/components/node-red-editor-input.vue"))["default"];
+    NodeRedInputLabel: (typeof import("./client/form/components/node-red-input-label.vue"))["default"];
+    NodeRedInput: (typeof import("./client/form/components/node-red-input.vue"))["default"];
+    NodeRedJsonSchemaForm: (typeof import("./client/form/components/node-red-json-schema-form.vue"))["default"];
+    NodeRedSelectInput: (typeof import("./client/form/components/node-red-select-input.vue"))["default"];
+    NodeRedToggle: (typeof import("./client/form/components/node-red-toggle.vue"))["default"];
+    NodeRedTypedInput: (typeof import("./client/form/components/node-red-typed-input.vue"))["default"];
+  }
+}

package/types/shims/constants.d.ts

@@ -0,0 +1,4 @@
+declare const TYPED_INPUT_TYPES: readonly ["msg", "flow", "global", "str", "num", "bool", "json", "bin", "re", "jsonata", "date", "env", "node", "cred"];
+/** Reserved config property names for built-in ports (error, complete, status) */
+declare const BUILTIN_PORT_KEYS: readonly ["errorPort", "completePort", "statusPort"];
+export { BUILTIN_PORT_KEYS, TYPED_INPUT_TYPES };

package/types/shims/schema-options.d.ts

@@ -0,0 +1,24 @@
+/**
+ * NRG's JSON Schema vocabulary — the custom keywords the server emits onto
+ * serialized schemas and the client consumes for form rendering and
+ * validation. Shared at the core root (like brands.ts) so both planes derive
+ * from one definition instead of drifting copies.
+ */
+export interface JsonSchemaObjectExtensions {
+    format?: "node-id" | "flow-id" | "topic-path" | (string & {});
+    /** expose this settings property to the editor via RED.settings */
+    exportable?: boolean;
+    /** set by SchemaType.NodeRef — the referenced config node type */
+    "x-nrg-node-type"?: string;
+    /** set by SchemaType.TypedInput — marks a TypedInput value/type pair */
+    "x-nrg-typed-input"?: boolean;
+    /** set by markNonValidatable — ajv skips this property */
+    "x-nrg-skip-validation"?: boolean;
+    /** form rendering hints consumed by the auto-generated editor form */
+    "x-nrg-form"?: {
+        icon?: string;
+        typedInputTypes?: string[];
+        editorLanguage?: string;
+        toggle?: boolean;
+    };
+}

package/types/shims/shims-vue.d.ts

@@ -0,0 +1,5 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<any, any, any>;
+  export default component;
+}

package/types/shims/typebox.d.ts

@@ -0,0 +1,10 @@
+// This import makes the file a module, which is required for
+// TypeScript module augmentation (declare module) to work correctly.
+// Without it, the file is treated as a global script and the
+// augmentation silently fails.
+import type { JsonSchemaObjectExtensions } from "./schema-options";
+
+declare module "@sinclair/typebox" {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface SchemaOptions extends JsonSchemaObjectExtensions {}
+}