@makehq/forman-schema 1.2.1 → 1.2.3

package/dist/index.cjs

@@ -32,12 +32,20 @@ function noEmpty(text) {
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isOptionGroup(value) {
+  return "options" in value && Array.isArray(value.options);
+}
 
 // src/forman.ts
 var SchemaConversionError = class extends Error {
+  /** Field that caused the error */
+  field;
+  /**
+   * @param message The error message
+   * @param field The field that caused the error
+   */
   constructor(message, field) {
     super(message);
-    this.field = field;
     this.name = "SchemaConversionError";
   }
 };
@@ -236,41 +244,52 @@ function handleArrayType(field, result, context) {
   return result;
 }
 function handleSelectType(field, result, context) {
-  const options = isObject(field.options) ? field.options.store : field.options;
+  const optionsOrGroups = isObject(field.options) ? field.options.store : field.options;
   const nested = isObject(field.options) ? isObject(field.options.nested) ? field.options.nested.store : field.options.nested : void 0;
   const domain = isObject(field.options) ? isObject(field.options.nested) && field.options.nested.domain ? field.options.nested.domain : void 0 : void 0;
-  if (typeof options === "string") {
+  if (typeof optionsOrGroups === "string") {
     Object.defineProperty(result, "x-fetch", {
       configurable: true,
       enumerable: true,
       writable: true,
-      value: appendQueryString(options, context.domain, context.tail)
-    });
-  } else if (options?.some((option) => option.label || option.nested)) {
-    result.oneOf = (options || []).map((option) => {
-      const localNested = (isObject(option.nested) ? option.nested.store : option.nested) || nested;
-      const localDomain = (isObject(option.nested) && option.nested.domain ? option.nested.domain : domain) || context.domain;
-      if (localNested) {
-        context.addConditionalFields(
-          field.name,
-          option.value,
-          typeof localNested === "string" ? appendQueryString(localNested, localDomain, [...context.tail, field.name]) : toJSONSchemaInternal(
-            { type: "collection", spec: localNested },
-            {
-              ...context,
-              domain: localDomain,
-              tail: [...context.tail, field.name]
-            }
-          )
-        );
-      }
-      return {
-        title: noEmpty(option.label),
-        const: option.value
-      };
+      value: appendQueryString(optionsOrGroups, context.domain, context.tail)
     });
   } else {
-    result.enum = (options || []).map((option) => option.value);
+    const options = optionsOrGroups?.some(isOptionGroup) ? optionsOrGroups.flatMap(
+      (group) => group.options.map((option) => ({
+        ...option,
+        label: `${group.label}: ${option.label || option.value}`
+      }))
+    ) : optionsOrGroups || [];
+    if (options?.some((option) => {
+      if (isOptionGroup(option)) return option.options.some((option2) => option2.label || option2.nested);
+      return option.label || option.nested;
+    })) {
+      result.oneOf = (options || []).map((option) => {
+        const localNested = (isObject(option.nested) ? option.nested.store : option.nested) || nested;
+        const localDomain = (isObject(option.nested) && option.nested.domain ? option.nested.domain : domain) || context.domain;
+        if (localNested) {
+          context.addConditionalFields(
+            field.name,
+            option.value,
+            typeof localNested === "string" ? appendQueryString(localNested, localDomain, [...context.tail, field.name]) : toJSONSchemaInternal(
+              { type: "collection", spec: localNested },
+              {
+                ...context,
+                domain: localDomain,
+                tail: [...context.tail, field.name]
+              }
+            )
+          );
+        }
+        return {
+          title: noEmpty(option.label),
+          const: option.value
+        };
+      });
+    } else {
+      result.enum = (options || []).map((option) => option.value);
+    }
   }
   if (nested && domain && domain !== context.domain) {
     if (typeof nested === "string") {
@@ -292,7 +311,7 @@ function handleSelectType(field, result, context) {
       configurable: true,
       enumerable: true,
       writable: true,
-      value: typeof nested === "string" ? { $ref: nested } : toJSONSchemaInternal(
+      value: typeof nested === "string" ? { $ref: appendQueryString(nested, context.domain, [...context.tail, field.name]) } : toJSONSchemaInternal(
         { type: "collection", spec: nested },
         {
           ...context,

package/dist/index.d.cts

@@ -34,7 +34,7 @@ type FormanSchemaField = {
     /** Default value for the field */
     default?: FormanSchemaValue;
     /** Available options for select type fields */
-    options?: FormanSchemaOption[] | FormanSchemaExtendedOptions | string;
+    options?: FormanSchemaOption[] | FormanSchemaOptionGroup[] | FormanSchemaExtendedOptions | string;
     /** Help text or description for the field */
     help?: string;
     /** Sub-fields specification for collection or array types */
@@ -47,25 +47,92 @@ type FormanSchemaField = {
     nested?: FormanSchemaNested;
     /** Validation rules */
     validate?: FormanSchemaValidation;
+    /** Whether the field is disabled (`false` by default) */
+    disabled?: boolean;
+    /** Whether the field is mappable */
+    mappable?: boolean;
+    /** Whether the user will be able to insert new lines in GUI (a textarea will be displayed instead of the text field) */
+    multiline?: boolean;
+    /** Specifies how to treat HTML tags in the field (text only) */
+    tags?: 'strip' | 'stripall' | 'escape';
+    /** Allowed extension or array of allowed extensions. (filename only) */
+    extension?: string | string[];
+    /** Semantic type for the field */
+    semantic?: string;
+    /** Whether to allow time selection (date only, `true` by default) */
+    time?: boolean;
+    /** Whether the properties of the object will be in the same order as they are defined in the spec (collection only) */
+    sequence?: boolean;
+    /** Codepage for the field (buffer only) */
+    codepage?: string;
+    /** Whether the field is grouped (select only) */
+    grouped?: boolean;
+    /** Whether a mapped value in the select should be validated against the option values. If true, the value is treated as a dynamic and validation is disabled. The value is set to `true` automatically if select options are generated using RPC. */
+    dynamic?: boolean;
+    /** Mode for the field (select only) */
+    mode?: 'edit' | 'choose';
+    /** Sort order for the field (select only) */
+    sort?: string;
+    /** Adds an extra button to the field which opens an extra form. When the form is submitted, a specified RPC is called and the result is set as a new value of the parameter. */
+    rpc?: FormanSchemaRPCButton;
 } & Record<`x-${string}`, unknown>;
+/**
+ * RPC button allows for dynamic value retrieval from an external source
+ */
+type FormanSchemaRPCButton = {
+    /** RPC button label */
+    label: string;
+    /** RPC button URL */
+    url: string;
+    /** RPC button parameters */
+    parameters: FormanSchemaField[];
+};
+/**
+ * Valid Forman Schema values
+ */
 type FormanSchemaValue = string | number | boolean | null;
+/**
+ * Option for a select field
+ */
 type FormanSchemaOption = {
     /** Option value */
     value: FormanSchemaValue;
     /** Option label */
     label?: string;
+    /** Whether the option is the default */
+    default?: boolean;
     /** Nested fields for this option */
     nested?: FormanSchemaNested;
 };
+/**
+ * Option group for a select field
+ */
+type FormanSchemaOptionGroup = {
+    /** Group label */
+    label: string;
+    /** Group options */
+    options: FormanSchemaOption[];
+};
+/**
+ * Extended options for a select field
+ */
 type FormanSchemaExtendedOptions = {
     /** Store for the options */
-    store: FormanSchemaOption[] | string;
+    store: FormanSchemaOption[] | FormanSchemaOptionGroup[] | string;
     /** Nested fields for every option */
     nested?: FormanSchemaNested;
 };
+/**
+ * Nested fields
+ */
 type FormanSchemaNested = FormanSchemaField[] | string | FormanSchemaExtendedNested;
+/**
+ * Extended nested fields
+ */
 type FormanSchemaExtendedNested = {
+    /** Store for the nested fields */
     store: FormanSchemaField[] | string;
+    /** Domain for the nested fields */
     domain?: string;
 };
 

package/dist/index.d.ts

@@ -34,7 +34,7 @@ type FormanSchemaField = {
     /** Default value for the field */
     default?: FormanSchemaValue;
     /** Available options for select type fields */
-    options?: FormanSchemaOption[] | FormanSchemaExtendedOptions | string;
+    options?: FormanSchemaOption[] | FormanSchemaOptionGroup[] | FormanSchemaExtendedOptions | string;
     /** Help text or description for the field */
     help?: string;
     /** Sub-fields specification for collection or array types */
@@ -47,25 +47,92 @@ type FormanSchemaField = {
     nested?: FormanSchemaNested;
     /** Validation rules */
     validate?: FormanSchemaValidation;
+    /** Whether the field is disabled (`false` by default) */
+    disabled?: boolean;
+    /** Whether the field is mappable */
+    mappable?: boolean;
+    /** Whether the user will be able to insert new lines in GUI (a textarea will be displayed instead of the text field) */
+    multiline?: boolean;
+    /** Specifies how to treat HTML tags in the field (text only) */
+    tags?: 'strip' | 'stripall' | 'escape';
+    /** Allowed extension or array of allowed extensions. (filename only) */
+    extension?: string | string[];
+    /** Semantic type for the field */
+    semantic?: string;
+    /** Whether to allow time selection (date only, `true` by default) */
+    time?: boolean;
+    /** Whether the properties of the object will be in the same order as they are defined in the spec (collection only) */
+    sequence?: boolean;
+    /** Codepage for the field (buffer only) */
+    codepage?: string;
+    /** Whether the field is grouped (select only) */
+    grouped?: boolean;
+    /** Whether a mapped value in the select should be validated against the option values. If true, the value is treated as a dynamic and validation is disabled. The value is set to `true` automatically if select options are generated using RPC. */
+    dynamic?: boolean;
+    /** Mode for the field (select only) */
+    mode?: 'edit' | 'choose';
+    /** Sort order for the field (select only) */
+    sort?: string;
+    /** Adds an extra button to the field which opens an extra form. When the form is submitted, a specified RPC is called and the result is set as a new value of the parameter. */
+    rpc?: FormanSchemaRPCButton;
 } & Record<`x-${string}`, unknown>;
+/**
+ * RPC button allows for dynamic value retrieval from an external source
+ */
+type FormanSchemaRPCButton = {
+    /** RPC button label */
+    label: string;
+    /** RPC button URL */
+    url: string;
+    /** RPC button parameters */
+    parameters: FormanSchemaField[];
+};
+/**
+ * Valid Forman Schema values
+ */
 type FormanSchemaValue = string | number | boolean | null;
+/**
+ * Option for a select field
+ */
 type FormanSchemaOption = {
     /** Option value */
     value: FormanSchemaValue;
     /** Option label */
     label?: string;
+    /** Whether the option is the default */
+    default?: boolean;
     /** Nested fields for this option */
     nested?: FormanSchemaNested;
 };
+/**
+ * Option group for a select field
+ */
+type FormanSchemaOptionGroup = {
+    /** Group label */
+    label: string;
+    /** Group options */
+    options: FormanSchemaOption[];
+};
+/**
+ * Extended options for a select field
+ */
 type FormanSchemaExtendedOptions = {
     /** Store for the options */
-    store: FormanSchemaOption[] | string;
+    store: FormanSchemaOption[] | FormanSchemaOptionGroup[] | string;
     /** Nested fields for every option */
     nested?: FormanSchemaNested;
 };
+/**
+ * Nested fields
+ */
 type FormanSchemaNested = FormanSchemaField[] | string | FormanSchemaExtendedNested;
+/**
+ * Extended nested fields
+ */
 type FormanSchemaExtendedNested = {
+    /** Store for the nested fields */
     store: FormanSchemaField[] | string;
+    /** Domain for the nested fields */
     domain?: string;
 };
 

package/dist/index.js

@@ -5,12 +5,20 @@ function noEmpty(text) {
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isOptionGroup(value) {
+  return "options" in value && Array.isArray(value.options);
+}
 
 // src/forman.ts
 var SchemaConversionError = class extends Error {
+  /** Field that caused the error */
+  field;
+  /**
+   * @param message The error message
+   * @param field The field that caused the error
+   */
   constructor(message, field) {
     super(message);
-    this.field = field;
     this.name = "SchemaConversionError";
   }
 };
@@ -209,41 +217,52 @@ function handleArrayType(field, result, context) {
   return result;
 }
 function handleSelectType(field, result, context) {
-  const options = isObject(field.options) ? field.options.store : field.options;
+  const optionsOrGroups = isObject(field.options) ? field.options.store : field.options;
   const nested = isObject(field.options) ? isObject(field.options.nested) ? field.options.nested.store : field.options.nested : void 0;
   const domain = isObject(field.options) ? isObject(field.options.nested) && field.options.nested.domain ? field.options.nested.domain : void 0 : void 0;
-  if (typeof options === "string") {
+  if (typeof optionsOrGroups === "string") {
     Object.defineProperty(result, "x-fetch", {
       configurable: true,
       enumerable: true,
       writable: true,
-      value: appendQueryString(options, context.domain, context.tail)
-    });
-  } else if (options?.some((option) => option.label || option.nested)) {
-    result.oneOf = (options || []).map((option) => {
-      const localNested = (isObject(option.nested) ? option.nested.store : option.nested) || nested;
-      const localDomain = (isObject(option.nested) && option.nested.domain ? option.nested.domain : domain) || context.domain;
-      if (localNested) {
-        context.addConditionalFields(
-          field.name,
-          option.value,
-          typeof localNested === "string" ? appendQueryString(localNested, localDomain, [...context.tail, field.name]) : toJSONSchemaInternal(
-            { type: "collection", spec: localNested },
-            {
-              ...context,
-              domain: localDomain,
-              tail: [...context.tail, field.name]
-            }
-          )
-        );
-      }
-      return {
-        title: noEmpty(option.label),
-        const: option.value
-      };
+      value: appendQueryString(optionsOrGroups, context.domain, context.tail)
     });
   } else {
-    result.enum = (options || []).map((option) => option.value);
+    const options = optionsOrGroups?.some(isOptionGroup) ? optionsOrGroups.flatMap(
+      (group) => group.options.map((option) => ({
+        ...option,
+        label: `${group.label}: ${option.label || option.value}`
+      }))
+    ) : optionsOrGroups || [];
+    if (options?.some((option) => {
+      if (isOptionGroup(option)) return option.options.some((option2) => option2.label || option2.nested);
+      return option.label || option.nested;
+    })) {
+      result.oneOf = (options || []).map((option) => {
+        const localNested = (isObject(option.nested) ? option.nested.store : option.nested) || nested;
+        const localDomain = (isObject(option.nested) && option.nested.domain ? option.nested.domain : domain) || context.domain;
+        if (localNested) {
+          context.addConditionalFields(
+            field.name,
+            option.value,
+            typeof localNested === "string" ? appendQueryString(localNested, localDomain, [...context.tail, field.name]) : toJSONSchemaInternal(
+              { type: "collection", spec: localNested },
+              {
+                ...context,
+                domain: localDomain,
+                tail: [...context.tail, field.name]
+              }
+            )
+          );
+        }
+        return {
+          title: noEmpty(option.label),
+          const: option.value
+        };
+      });
+    } else {
+      result.enum = (options || []).map((option) => option.value);
+    }
   }
   if (nested && domain && domain !== context.domain) {
     if (typeof nested === "string") {
@@ -265,7 +284,7 @@ function handleSelectType(field, result, context) {
       configurable: true,
       enumerable: true,
       writable: true,
-      value: typeof nested === "string" ? { $ref: nested } : toJSONSchemaInternal(
+      value: typeof nested === "string" ? { $ref: appendQueryString(nested, context.domain, [...context.tail, field.name]) } : toJSONSchemaInternal(
         { type: "collection", spec: nested },
         {
           ...context,

package/package.json

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