treege 3.0.0-beta.5 → 3.0.0-beta.50

package/dist/editor/hooks/useFlowConnections.d.ts

@@ -1,4 +1,13 @@
 import { OnConnect, OnConnectEnd, OnEdgesDelete } from '@xyflow/react';
+/**
+ * Shape passed to the node-creating actions (`onAddFromHandle`, `onInsertAfter`,
+ * and the internal `createNodeAndConnect`). Lets callers seed the new node's
+ * `type` and `data` while React Flow handles position, id, etc.
+ */
+export type NodeInit = {
+    type: string;
+    data?: Record<string, unknown>;
+};
 /**
  * Custom hook to manage flow connections, including connecting nodes,
  * handling connection ends, and deleting edges with conditional logic.
@@ -8,8 +17,12 @@ declare const useFlowConnections: () => {
         source: string;
         target: string;
     }) => boolean;
+    moveStackNodeDown: (nodeId: string) => void;
+    moveStackNodeUp: (nodeId: string) => void;
+    onAddFromHandle: (sourceNodeId: string, nodeInit?: NodeInit) => void;
     onConnect: OnConnect;
     onConnectEnd: OnConnectEnd;
     onEdgesDelete: OnEdgesDelete;
+    onInsertAfter: (sourceNodeId: string, nodeInit?: NodeInit) => void;
 };
 export default useFlowConnections;

package/dist/editor/hooks/useHistoryStore.d.ts

@@ -0,0 +1,26 @@
+import { Edge, Node } from '@xyflow/react';
+type Snapshot = {
+    nodes: Node[];
+    edges: Edge[];
+};
+type HistoryStore = {
+    past: Snapshot[];
+    future: Snapshot[];
+    pushPast: (snapshot: Snapshot) => void;
+    popPast: () => Snapshot | undefined;
+    pushFuture: (snapshot: Snapshot) => void;
+    popFuture: () => Snapshot | undefined;
+    clearFuture: () => void;
+    reset: () => void;
+};
+/**
+ * Zustand store backing the editor's undo/redo history.
+ *
+ * Holds two stacks of `{ nodes, edges }` snapshots: `past` (states to undo into) and
+ * `future` (states to redo into). Both are capped at `MAX_HISTORY` to bound memory.
+ *
+ * Consumed exclusively by `useUndoRedo` — components should not read or mutate this
+ * store directly. Call `reset()` when loading a new flow to drop stale history.
+ */
+declare const useHistoryStore: import('zustand').UseBoundStore<import('zustand').StoreApi<HistoryStore>>;
+export default useHistoryStore;

package/dist/editor/hooks/useIsStackedEdge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * An edge is "stacked" when it connects two nodes that belong to the same
+ * visual chain — i.e. the source has a linear child (position "first" or
+ * "middle") and the target has a linear parent (position "middle" or "last").
+ * Stacked edges are not rendered: their endpoints touch border-to-border in
+ * the layout, making the line redundant.
+ */
+export declare const useIsStackedEdge: (source: string, target: string) => boolean;

package/dist/editor/hooks/useNodesSelection.d.ts

@@ -10,10 +10,10 @@ declare const useNodesSelection: <TNodeData extends TreegeNodeData = TreegeNodeD
     nodes: TreegeNode[];
     selectedNode: ({
         id: string;
-        position: import('@xyflow/react').XYPosition;
+        position: import('@xyflow/system').XYPosition;
         data: TreegeNodeData;
-        sourcePosition?: import('@xyflow/react').Position;
-        targetPosition?: import('@xyflow/react').Position;
+        sourcePosition?: import('@xyflow/system').Position;
+        targetPosition?: import('@xyflow/system').Position;
         hidden?: boolean;
         selected?: boolean;
         dragging?: boolean;
@@ -28,10 +28,10 @@ declare const useNodesSelection: <TNodeData extends TreegeNodeData = TreegeNodeD
         initialHeight?: number;
         parentId?: string;
         zIndex?: number;
-        extent?: "parent" | import('@xyflow/react').CoordinateExtent | null;
+        extent?: "parent" | import('@xyflow/system').CoordinateExtent | null;
         expandParent?: boolean;
         ariaLabel?: string;
-        origin?: import('@xyflow/react').NodeOrigin;
+        origin?: import('@xyflow/system').NodeOrigin;
         handles?: import('@xyflow/system').NodeHandle[];
         measured?: {
             width?: number;

package/dist/editor/hooks/useStackPosition.d.ts

@@ -0,0 +1,14 @@
+import { StackPosition } from '../utils/stackPositionIndex';
+export type StackPositionInfo = {
+    position: StackPosition;
+    isStackHead: boolean;
+    isStackTail: boolean;
+    isStackMiddle: boolean;
+    isStackSingle: boolean;
+};
+/**
+ * Returns the stack position of `nodeId` plus convenience booleans derived from
+ * it. Uses a shallow equality selector so consumers only re-render when one of
+ * the booleans actually flips, not on every edge mutation.
+ */
+export declare const useStackPosition: (nodeId: string) => StackPositionInfo;

package/dist/editor/hooks/useUndoRedo.d.ts

@@ -0,0 +1,31 @@
+import { OnBeforeDelete } from '@xyflow/react';
+type UseUndoRedoOptions = {
+    enableShortcuts?: boolean;
+};
+/**
+ * Snapshot-based undo/redo for the ReactFlow editor.
+ *
+ * Maintains `past` / `future` stacks of `{ nodes, edges }` snapshots in `useHistoryStore`.
+ * Callers must invoke `takeSnapshot()` before any mutation they want to be undoable
+ * (drag start, node/edge creation, deletion, type change, …); the hook itself does
+ * not observe ReactFlow state changes.
+ *
+ * @param enableShortcuts - When true, binds Cmd/Ctrl+Z (undo) and Cmd/Ctrl+Shift+Z /
+ *   Cmd/Ctrl+Y (redo) to the window. Should be enabled in a single root component
+ *   (e.g. the editor) to avoid duplicate listeners.
+ *
+ * @returns
+ * - `takeSnapshot`: pushes the current flow onto `past` and clears `future`.
+ * - `onBeforeDelete`: adapter typed for ReactFlow's `onBeforeDelete` prop.
+ * - `undo` / `redo`: restore the previous / next snapshot.
+ * - `canUndo` / `canRedo`: booleans driven by stack length, suitable for disabling UI buttons.
+ */
+declare const useUndoRedo: ({ enableShortcuts }?: UseUndoRedoOptions) => {
+    canRedo: boolean;
+    canUndo: boolean;
+    onBeforeDelete: OnBeforeDelete;
+    redo: () => void;
+    takeSnapshot: () => void;
+    undo: () => void;
+};
+export default useUndoRedo;

package/dist/editor/types/ai.d.ts

@@ -0,0 +1,65 @@
+import { Edge, Node } from '@xyflow/react';
+/**
+ * AI Provider types for tree generation
+ */
+export type AIProvider = "gemini" | "openai" | "deepseek" | "claude";
+/**
+ * AI Configuration for tree generation
+ */
+export interface AIConfig {
+    /**
+     * The AI provider to use
+     * @default "gemini"
+     */
+    provider?: AIProvider;
+    /**
+     * API key for the selected provider
+     */
+    apiKey: string;
+    /**
+     * Optional model name override
+     * - Gemini: "gemini-2.5-flash" (default), "gemini-2.5-pro-preview-03-25"
+     * - OpenAI: "gpt-4o-mini" (default), "gpt-4o", "gpt-3.5-turbo"
+     * - DeepSeek: "deepseek-chat" (default)
+     * - Claude: "claude-3-5-haiku-20241022" (default), "claude-3-5-sonnet-20241022"
+     */
+    model?: string;
+    /**
+     * Temperature for generation (0-1, default: 0.7)
+     */
+    temperature?: number;
+}
+/**
+ * AI Generation request
+ */
+export interface AIGenerationRequest {
+    /**
+     * User prompt describing the desired tree/form
+     */
+    prompt: string;
+    /**
+     * AI configuration
+     */
+    config: AIConfig;
+}
+/**
+ * AI Generation response
+ */
+export interface AIGenerationResponse {
+    /**
+     * Generated nodes
+     */
+    nodes: Node[];
+    /**
+     * Generated edges
+     */
+    edges: Edge[];
+    /**
+     * Optional explanation or metadata
+     */
+    metadata?: {
+        explanation?: string;
+        nodesCount?: number;
+        edgesCount?: number;
+    };
+}

package/dist/editor/types/editor.d.ts

@@ -1,19 +1,32 @@
 import { Edge, Node } from '@xyflow/react';
-import { Flow } from '../../shared/types/node';
-export interface TreegeEditorProps {
+import { ReactNode } from 'react';
+import { AIConfig } from './ai';
+import { OpenApiDocument } from './openapi';
+import { Flow, HttpHeader } from '../../shared/types/node';
+export interface ExtraMenuItem {
     /**
-     * Default flow structure containing combined nodes and edges.
-     * Note: Individual defaultNodes/defaultEdges props take precedence over this.
+     * Label displayed in the menu item.
      */
-    flow?: Flow | null;
+    label: ReactNode;
     /**
-     * Default nodes to initialize the nodes in the flow.
+     * Optional icon rendered before the label.
      */
-    nodes?: Node[];
+    icon?: ReactNode;
     /**
-     * Default edges to initialize the edges in the flow.
+     * Callback triggered when the menu item is clicked.
      */
-    edges?: Edge[];
+    onClick?: () => void;
+    /**
+     * When true, styles the item as destructive.
+     */
+    destructive?: boolean;
+}
+export interface TreegeEditorProps {
+    /**
+     * Default flow structure containing combined nodes and edges.
+     * Note: Individual defaultNodes/defaultEdges props take precedence over this.
+     */
+    flow?: Flow | null;
     /**
      * Callback function triggered when exporting JSON data.
      */
@@ -34,4 +47,53 @@ export interface TreegeEditorProps {
      * Language for the editor interface.
      */
     language?: string;
+    /**
+     * AI configuration for tree generation
+     */
+    aiConfig?: AIConfig;
+    /**
+     * Additional CSS class names for custom styling.
+     */
+    className?: string;
+    /**
+     * Extra menu items to append to the "more" dropdown of the actions panel.
+     */
+    extraMenuItems?: ExtraMenuItem[];
+    /**
+     * OpenAPI 3.x source used to power URL/route suggestions inside HTTP and
+     * Options-source forms, and to drive the Authorize flow. Accepts either:
+     * - a pre-parsed `OpenApiDocument` object
+     * - a URL string (the editor fetches it on mount and toasts on failure)
+     *
+     * Users can still load one at runtime via the editor's "OpenAPI" button.
+     */
+    openApi?: OpenApiDocument | string;
+    /**
+     * Base URL used for OpenAPI route resolution. When set, it takes precedence
+     * over the document's `servers[0].url` — useful when the spec points at a
+     * different environment than the one to call (e.g. staging vs prod).
+     */
+    openApiBaseUrl?: string;
+    /**
+     * Global HTTP headers applied to in-editor requests (e.g. the "Detect
+     * fields" button in `OptionsSourceForm`). Pass the same value you give to
+     * `TreegeRenderer` so editor-time previews use the same auth and headers
+     * that the runtime form will use.
+     */
+    headers?: HttpHeader[];
+    /**
+     * Called when the user submits the Authorize dialog. Receives the resulting
+     * HTTP headers (`Authorization`, API key headers…). The consumer is expected
+     * to forward those headers to `TreegeRenderer` (or `TreegeConfigProvider`)
+     * via its `headers` prop so every request issued by the form is authenticated.
+     */
+    onAuthorize?: (headers: HttpHeader[]) => void;
+    /**
+     * Called whenever the user edits the global headers via the editor's
+     * built-in "Global headers" dialog. The component is controlled — the
+     * parent is expected to update its `headers` state in response and pass
+     * the new list back via the `headers` prop, so every editor-time and
+     * runtime request reflects the change.
+     */
+    onHeadersChange?: (headers: HttpHeader[]) => void;
 }

package/dist/editor/types/openapi.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Minimal OpenAPI 3.x types — only what the editor needs to suggest API
+ * routes and authenticate against an API. Not a full OpenAPI definition.
+ *
+ * Swagger 2.0 (`swagger: "2.0"`) is intentionally not supported.
+ */
+export interface OpenApiDocument {
+    openapi: string;
+    info?: {
+        title?: string;
+        version?: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, OpenApiPathItem | undefined>;
+    components?: {
+        securitySchemes?: Record<string, OpenApiSecurityScheme | undefined>;
+    };
+}
+export interface OpenApiPathItem {
+    get?: OpenApiOperation;
+    put?: OpenApiOperation;
+    post?: OpenApiOperation;
+    delete?: OpenApiOperation;
+    patch?: OpenApiOperation;
+}
+export interface OpenApiOperation {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    operationId?: string;
+}
+/** HTTP Bearer auth scheme. */
+export interface OpenApiHttpBearerScheme {
+    type: "http";
+    scheme: "bearer";
+    bearerFormat?: string;
+    description?: string;
+}
+/** Header-based API key auth scheme. */
+export interface OpenApiApiKeyHeaderScheme {
+    type: "apiKey";
+    in: "header";
+    name: string;
+    description?: string;
+}
+/**
+ * OAuth2 with the `password` grant. The user provides username + password
+ * directly, the editor exchanges them at `tokenUrl` and uses the returned
+ * access token as a Bearer header.
+ *
+ * Other OAuth2 flows (`authorization_code`, `client_credentials`, `implicit`)
+ * are out of scope — they require browser redirects, server-side state, or
+ * PKCE.
+ */
+export interface OpenApiOAuth2PasswordScheme {
+    type: "oauth2";
+    /** Resolved against `servers[0].url` when the spec uses a relative path. */
+    tokenUrl: string;
+    description?: string;
+}
+/**
+ * Security schemes the editor supports today. Other schemes (OAuth2 flows
+ * other than password, cookie/query API keys, openIdConnect) are filtered
+ * out at extraction time.
+ */
+export type OpenApiSecurityScheme = OpenApiHttpBearerScheme | OpenApiApiKeyHeaderScheme | OpenApiOAuth2PasswordScheme;
+export type ApiRouteMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/**
+ * One operation extracted from an OpenAPI document, flattened to a single
+ * (method, path) record for easy listing.
+ */
+export interface ApiRoute {
+    method: ApiRouteMethod;
+    path: string;
+    summary?: string;
+    operationId?: string;
+}

package/dist/editor/utils/aiFlowGenerator.d.ts

@@ -0,0 +1,5 @@
+import { AIGenerationRequest, AIGenerationResponse } from '../types/ai';
+/**
+ * Main function to generate flow using AI
+ */
+export declare function generateFlowWithAI(request: AIGenerationRequest): Promise<AIGenerationResponse>;

package/dist/editor/utils/dagreLayout.d.ts

@@ -0,0 +1,8 @@
+import { Edge, Node } from '@xyflow/react';
+export type LayoutDirection = "TB" | "LR";
+export interface LayoutOptions {
+    direction?: LayoutDirection;
+    horizontalSpacing?: number;
+    verticalSpacing?: number;
+}
+export declare const getLayoutedElements: (nodes: Node[], edges: Edge[], options?: LayoutOptions) => Node[];

package/dist/editor/utils/edge.d.ts

@@ -0,0 +1,14 @@
+import { Edge } from '@xyflow/react';
+/**
+ * Re-normalize outgoing edges from a set of affected parent nodes: if a parent
+ * now has a single remaining child, convert its outgoing edge back to a
+ * "default" type and drop condition-specific data fields.
+ *
+ * Used after edge or node deletions to keep conditional edges in sync with the
+ * presence of siblings.
+ *
+ * @param edges - The edges remaining after deletion
+ * @param affectedParents - Source node IDs whose children changed
+ * @returns A new edges array with affected edges normalized
+ */
+export declare const normalizeConditionalEdges: (edges: Edge[], affectedParents: Set<string>) => Edge[];

package/dist/editor/utils/groupColor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deterministic color for a group, derived from its id.
+ *
+ * Why HSL + inline style (rather than a Tailwind class):
+ * Tailwind purges classes at build time and can't synthesize `bg-{color}`
+ * from a runtime hash. Picking from a fixed palette would cap the number of
+ * distinguishable groups; HSL with a hashed hue gives effectively unlimited
+ * distinct, stable colors with no Tailwind-side configuration.
+ *
+ * Saturation/lightness are fixed (65% / 45%) so every group lands in the
+ * same readable, mid-contrast band on both light and dark themes — only the
+ * hue varies between groups.
+ */
+export declare const getGroupColor: (groupId?: string) => string;

package/dist/editor/utils/image.d.ts

@@ -0,0 +1,7 @@
+export declare const MAX_IMAGE_INPUT_BYTES: number;
+/**
+ * Converts an image file to a resized JPEG base64 data URL.
+ * Rejects files that are not images or exceed MAX_IMAGE_INPUT_BYTES.
+ * Dimensions are capped at MAX_DIMENSION × MAX_DIMENSION to keep the JSON small.
+ */
+export declare const imageFileToOptimizedDataUrl: (file: File) => Promise<string>;

package/dist/editor/utils/inputTypeIcon.d.ts

@@ -0,0 +1,6 @@
+import { LucideIcon } from 'lucide-react';
+/**
+ * Returns the Lucide icon associated with an input or UI type.
+ * Falls back to DEFAULT_INPUT_TYPE_ICON when no match is found.
+ */
+export declare const getInputTypeIcon: (type?: string) => LucideIcon;

package/dist/editor/utils/openapi.d.ts

@@ -0,0 +1,35 @@
+import { ApiRoute, OpenApiDocument, OpenApiSecurityScheme } from '../types/openapi';
+/**
+ * Type guard validating that `value` is a usable OpenAPI 3.x document.
+ * Rejects 2.0 (Swagger) since we don't support it.
+ */
+export declare const isOpenApi3Document: (value: unknown) => value is OpenApiDocument;
+/**
+ * Load an OpenAPI document from either a remote URL or a raw JSON string.
+ * Throws when the input is empty, unreachable, malformed JSON, or not an
+ * OpenAPI 3.x document.
+ */
+export declare const loadOpenApiDocument: (input: string) => Promise<OpenApiDocument>;
+/**
+ * Flatten every (method, path) tuple defined in the document, preserving
+ * the path declaration order.
+ */
+export declare const extractApiRoutes: (doc: OpenApiDocument) => ApiRoute[];
+/** Returns the first declared server URL (with any trailing slash trimmed). */
+export declare const getBaseUrl: (doc: OpenApiDocument) => string;
+/** Resolve a path to a full URL using the document's first server. */
+export declare const resolveRouteUrl: (doc: OpenApiDocument, path: string) => string;
+/**
+ * Extract every supported security scheme from the document. Schemes other
+ * than `http+bearer` and `apiKey-in-header` are silently dropped — they're
+ * out of MVP scope.
+ */
+export declare const extractSecuritySchemes: (doc: OpenApiDocument) => Array<{
+    name: string;
+    scheme: OpenApiSecurityScheme;
+}>;
+/**
+ * Resolve a `tokenUrl` (which the OpenAPI spec sometimes leaves relative)
+ * against the document's first declared server URL.
+ */
+export declare const resolveTokenUrl: (tokenUrl: string, doc: OpenApiDocument) => string;

package/dist/editor/utils/stackPositionIndex.d.ts

@@ -0,0 +1,9 @@
+import { Edge } from '@xyflow/react';
+export type StackPosition = "single" | "first" | "middle" | "last";
+/**
+ * Memoizes the positions map keyed by the edges array reference. React Flow
+ * keeps that reference stable between unrelated updates (drag, selection, …),
+ * so selectors that read from this map effectively perform a Map lookup
+ * outside of edge mutations.
+ */
+export declare const getPositions: (edges: Edge[]) => Map<string, StackPosition>;