feat(validator): generate field states (#19)

Adds option to generate UI component states during forman validation.

Author: patriksimek

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@makehq/forman-schema",
-    "version": "1.4.1",
+    "version": "1.5.0",
     "description": "Forman Schema Tools",
     "license": "MIT",
     "author": "Make",

package.json

@@ -7,7 +7,7 @@ import type {
     FormanSchemaOption,
     FormanSchemaOptionGroup,
 } from './types';
-import { noEmpty, isObject, isOptionGroup, normalizeFormanFieldType, FORMAN_VISUAL_TYPES } from './utils';
+import { noEmpty, isObject, isOptionGroup, normalizeFormanFieldType, isVisualType } from './utils';
 
 /**
  * Context for schema conversion operations
@@ -217,7 +217,7 @@ function handleCollectionType(field: FormanSchemaField, result: JSONSchema7, con
     });
 
     function addField(subField: FormanSchemaField, tail?: string[]) {
-        if (FORMAN_VISUAL_TYPES.includes(subField.type)) {
+        if (isVisualType(subField.type)) {
             return;
         }
 

src/forman.ts

@@ -5,9 +5,11 @@ export type FormanSchemaFieldType =
     | 'aiagent'
     | 'account'
     | 'hook'
+    | 'device'
     | 'keychain'
     | 'datastore'
     | 'udt'
+    | 'scenario'
     | 'array'
     | 'collection'
     | 'text'
@@ -211,11 +213,23 @@ export type FormanValidationResult = {
         /** Error message */
         message: string;
     }[];
+    /** States of fields grouped by domain */
+    states?: Record<string, FormanSchemaFieldState>;
+};
+
+export type FormanSchemaFieldState = {
+    mode?: 'chose' | 'edit';
+    label?: string;
+    data?: Record<string, unknown>;
+    nested?: Record<string, FormanSchemaFieldState>;
+    items?: Record<string, FormanSchemaFieldState>[];
 };
 
 export type FormanValidationOptions = {
     /** Unknown fields are not allowed when strict is true */
     strict?: boolean;
+    /** Whether to generate states for fields */
+    states?: boolean;
     /** Remote resource resolver */
     resolveRemote?(path: string, data: Record<string, unknown>): Promise<unknown>;
 };

src/types.ts

@@ -1,6 +1,7 @@
 import {
     FormanSchemaExtendedOptions,
     FormanSchemaField,
+    FormanSchemaFieldState,
     FormanSchemaFieldType,
     FormanSchemaOption,
     FormanSchemaOptionGroup,
@@ -9,7 +10,39 @@ import {
 /**
  * Visual types are not a real input fields, they are used to display information in the UI.
  */
-export const FORMAN_VISUAL_TYPES = ['banner', 'markdown', 'html', 'separator'];
+export const FORMAN_VISUAL_TYPES = ['banner', 'markdown', 'html', 'separator'] as const;
+
+/**
+ * Type guard to check if a field type is a visual type.
+ * @param type The field type to check
+ * @returns true if the type is a visual type
+ */
+export function isVisualType(type: FormanSchemaFieldType): type is (typeof FORMAN_VISUAL_TYPES)[number] {
+    return (FORMAN_VISUAL_TYPES as readonly string[]).includes(type);
+}
+
+/**
+ * Reference types are types of type select that reference external resources.
+ */
+export const FORMAN_REFERENCE_TYPES = [
+    'account',
+    'hook',
+    'device',
+    'keychain',
+    'datastore',
+    'aiagent',
+    'udt',
+    'scenario',
+] as const;
+
+/**
+ * Type guard to check if a field type is a reference type.
+ * @param type The field type to check
+ * @returns true if the type is a reference type
+ */
+export function isReferenceType(type: FormanSchemaFieldType): type is (typeof FORMAN_REFERENCE_TYPES)[number] {
+    return (FORMAN_REFERENCE_TYPES as readonly string[]).includes(type);
+}
 
 /**
  * Utility function to handle empty strings by converting them to undefined.
@@ -64,8 +97,10 @@ export const API_ENDPOINTS = {
     aiagent: 'api://ai-agents/v1/agents',
     datastore: 'api://data-stores',
     hook: 'api://hooks/{{kind}}',
+    device: 'api://devices',
     keychain: 'api://keys/{{kind}}',
     udt: 'api://data-structures',
+    scenario: 'api://scenario-list',
 } as const;
 
 /**
@@ -94,3 +129,100 @@ export function normalizeFormanFieldType(field: FormanSchemaField): FormanSchema
         },
     };
 }
+
+/**
+ * Transforms a flat array of domain/path/state items into a nested object structure.
+ * Intermediate path levels are placed in a 'nested' property.
+ * @param items Array of items with domain, path, and state properties
+ * @returns Nested object structure organized by domain
+ */
+export function buildRestoreStructure(
+    items: Array<{
+        domain: string;
+        path: (string | number)[];
+        state: Omit<FormanSchemaFieldState, 'nested' | 'items'>;
+    }>,
+): Record<string, FormanSchemaFieldState> {
+    const result: Record<string, Record<string, FormanSchemaFieldState>> = {};
+
+    for (const item of items) {
+        const { domain, path, state } = item;
+
+        // Ensure domain exists
+        if (!result[domain]) {
+            result[domain] = {};
+        }
+
+        let current: Record<string, FormanSchemaFieldState> | Record<string, FormanSchemaFieldState>[] = result[domain];
+
+        // Navigate through the path
+        for (const [index, key] of path.entries()) {
+            const nextKey = path[index + 1];
+            const isLastElement = index === path.length - 1;
+            const nextIsNumber = typeof nextKey === 'number';
+
+            if (Array.isArray(current)) {
+                // We're in an array context
+                if (typeof key !== 'number') {
+                    throw new Error('Invalid path');
+                }
+                // Ensure the array item exists
+                if (!current[key]) {
+                    current[key] = {};
+                }
+
+                if (nextIsNumber) {
+                    // Next level is also an array - create nested array structure
+                    if (!current[key].value) {
+                        current[key].value = {
+                            mode: 'chose',
+                            items: [],
+                        };
+                    }
+                    if (!current[key].value.items) {
+                        current[key].value.items = [];
+                    }
+                    current = current[key].value.items;
+                } else if (isLastElement) {
+                    // Last element - merge the state
+                    Object.assign(current[key], state);
+                } else {
+                    // Move to the object at this array index
+                    current = current[key];
+                }
+            } else {
+                // We're in an object context
+                if (typeof key !== 'string') {
+                    throw new Error('Invalid path');
+                }
+                // Ensure the object item exists
+                if (!current[key]) {
+                    current[key] = {};
+                }
+
+                if (isLastElement) {
+                    // Last element - merge the state
+                    Object.assign(current[key], state);
+                } else {
+                    // Intermediate element - ensure it exists and navigate
+                    if (nextIsNumber) {
+                        // Next level is an array - create array structure
+                        if (!current[key].items) {
+                            current[key].items = [];
+                            current[key].mode = 'chose';
+                        }
+                        current = current[key].items;
+                    } else {
+                        // Next level is an object - navigate to nested
+                        if (!current[key].nested) {
+                            current[key].nested = {};
+                        }
+                        current = current[key].nested;
+                    }
+                }
+            }
+        }
+    }
+
+    return result;
+}