@formspec/build 0.1.0-alpha.40 → 0.1.0-alpha.42

package/dist/browser.cjs

@@ -101,11 +101,35 @@ function normalizeDeclarationPolicy(input) {
     displayName: normalizeScalarPolicy(input?.displayName)
   };
 }
+function normalizeEnumMemberDisplayNamePolicy(input) {
+  if (input?.mode === "infer-if-missing") {
+    return {
+      mode: "infer-if-missing",
+      infer: input.infer
+    };
+  }
+  if (input?.mode === "require-explicit") {
+    return {
+      mode: "require-explicit",
+      infer: () => ""
+    };
+  }
+  return {
+    mode: "disabled",
+    infer: () => ""
+  };
+}
+function normalizeEnumMemberPolicy(input) {
+  return {
+    displayName: normalizeEnumMemberDisplayNamePolicy(input?.displayName)
+  };
+}
 function normalizeMetadataPolicy(input) {
   return {
     type: normalizeDeclarationPolicy(input?.type),
     field: normalizeDeclarationPolicy(input?.field),
-    method: normalizeDeclarationPolicy(input?.method)
+    method: normalizeDeclarationPolicy(input?.method),
+    enumMember: normalizeEnumMemberPolicy(input?.enumMember)
   };
 }
 function getDeclarationMetadataPolicy(policy, declarationKind) {
@@ -202,6 +226,134 @@ function resolveResolvedMetadata(current, policy, context) {
     ...displayNamePlural !== void 0 && { displayNamePlural }
   };
 }
+function resolveEnumMemberDisplayName(current, policy, context) {
+  if (current !== void 0) {
+    return current;
+  }
+  if (policy.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit displayName for enum member "${context.logicalName}" on the ${context.surface} surface.`
+    );
+  }
+  if (policy.mode !== "infer-if-missing") {
+    return void 0;
+  }
+  const inferredValue = policy.infer(context).trim();
+  return inferredValue !== "" ? inferredValue : void 0;
+}
+function resolveEnumTypeMetadata(type, options) {
+  const members = type.members.map((member) => {
+    const displayName = resolveEnumMemberDisplayName(
+      member.displayName,
+      options.policy.enumMember.displayName,
+      {
+        surface: options.surface,
+        logicalName: String(member.value),
+        memberValue: member.value,
+        ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+      }
+    );
+    if (displayName === member.displayName) {
+      return member;
+    }
+    return displayName === void 0 ? { value: member.value } : { value: member.value, displayName };
+  });
+  return members.some((member, index) => member !== type.members[index]) ? { ...type, members } : type;
+}
+function resolveTypeNodeMetadata(type, options) {
+  switch (type.kind) {
+    case "array":
+      return {
+        ...type,
+        items: resolveTypeNodeMetadata(type.items, options)
+      };
+    case "object":
+      return {
+        ...type,
+        properties: type.properties.map((property) => resolveObjectPropertyMetadata(property, options))
+      };
+    case "record":
+      return {
+        ...type,
+        valueType: resolveTypeNodeMetadata(type.valueType, options)
+      };
+    case "union":
+      return {
+        ...type,
+        members: type.members.map((member) => resolveTypeNodeMetadata(member, options))
+      };
+    case "enum":
+      return resolveEnumTypeMetadata(type, options);
+    case "reference":
+    case "primitive":
+    case "dynamic":
+    case "custom":
+      return type;
+    default: {
+      const _exhaustive = type;
+      return _exhaustive;
+    }
+  }
+}
+function resolveObjectPropertyMetadata(property, options) {
+  const metadata = resolveResolvedMetadata(property.metadata, options.policy.field, {
+    surface: options.surface,
+    declarationKind: "field",
+    logicalName: property.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...property,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(property.type, options)
+  };
+}
+function resolveFieldMetadataNode(field, options) {
+  const metadata = resolveResolvedMetadata(field.metadata, options.policy.field, {
+    surface: options.surface,
+    declarationKind: "field",
+    logicalName: field.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...field,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(field.type, options)
+  };
+}
+function resolveFormElementMetadata(element, options) {
+  switch (element.kind) {
+    case "field":
+      return resolveFieldMetadataNode(element, options);
+    case "group":
+      return {
+        ...element,
+        elements: element.elements.map((child) => resolveFormElementMetadata(child, options))
+      };
+    case "conditional":
+      return {
+        ...element,
+        elements: element.elements.map((child) => resolveFormElementMetadata(child, options))
+      };
+    default: {
+      const _exhaustive = element;
+      return _exhaustive;
+    }
+  }
+}
+function resolveTypeDefinitionMetadata(typeDefinition, options) {
+  const metadata = resolveResolvedMetadata(typeDefinition.metadata, options.policy.type, {
+    surface: options.surface,
+    declarationKind: "type",
+    logicalName: typeDefinition.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...typeDefinition,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(typeDefinition.type, options)
+  };
+}
 function resolveMetadata(explicit, policy, context) {
   return resolveResolvedMetadata(toExplicitResolvedMetadata(explicit), policy, context);
 }
@@ -211,6 +363,25 @@ function getSerializedName(logicalName, metadata) {
 function getDisplayName(metadata) {
   return metadata?.displayName?.value;
 }
+function resolveFormIRMetadata(ir, options) {
+  const metadata = options.resolveRootTypeMetadata === false ? ir.metadata : resolveResolvedMetadata(ir.metadata, options.policy.type, {
+    surface: options.surface,
+    declarationKind: "type",
+    logicalName: options.rootLogicalName ?? ir.name ?? "FormSpec",
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...ir,
+    ...metadata !== void 0 && { metadata },
+    elements: ir.elements.map((element) => resolveFormElementMetadata(element, options)),
+    typeRegistry: Object.fromEntries(
+      Object.entries(ir.typeRegistry).map(([name, definition]) => [
+        name,
+        resolveTypeDefinitionMetadata(definition, options)
+      ])
+    )
+  };
+}
 
 // src/canonicalize/chain-dsl-canonicalizer.ts
 var CHAIN_DSL_PROVENANCE = {
@@ -232,7 +403,7 @@ function canonicalizeChainDSL(form, options) {
   const metadataPolicy = normalizeMetadataPolicy(
     options?.metadata ?? (0, import_internals._getFormSpecMetadataPolicy)(form)
   );
-  return {
+  const ir = {
     kind: "form-ir",
     irVersion: import_internals.IR_VERSION,
     elements: canonicalizeElements(form.elements, metadataPolicy),
@@ -240,6 +411,13 @@ function canonicalizeChainDSL(form, options) {
     typeRegistry: {},
     provenance: CHAIN_DSL_PROVENANCE
   };
+  return resolveFormIRMetadata(ir, {
+    policy: metadataPolicy,
+    surface: "chain-dsl",
+    // Chain DSL has no root/type-metadata authoring surface, so only resolve
+    // field/type-registry metadata and enum-member labels here.
+    resolveRootTypeMetadata: false
+  });
 }
 function canonicalizeElements(elements, metadataPolicy) {
   return elements.map((element) => canonicalizeElement(element, metadataPolicy));
@@ -698,17 +876,25 @@ function assertNoSerializedNameCollisions(ir) {
 // src/json-schema/ir-generator.ts
 function makeContext(options) {
   const vendorPrefix = options?.vendorPrefix ?? "x-formspec";
+  const rawEnumSerialization = options?.enumSerialization;
   if (!vendorPrefix.startsWith("x-")) {
     throw new Error(
       `Invalid vendorPrefix "${vendorPrefix}". Extension JSON Schema keywords must start with "x-".`
     );
   }
+  if (rawEnumSerialization !== void 0 && rawEnumSerialization !== "enum" && rawEnumSerialization !== "oneOf") {
+    throw new Error(
+      `Invalid enumSerialization "${rawEnumSerialization}". Expected "enum" or "oneOf".`
+    );
+  }
+  const enumSerialization = rawEnumSerialization ?? "enum";
   return {
     defs: {},
     typeNameMap: {},
     typeRegistry: {},
     extensionRegistry: options?.extensionRegistry,
-    vendorPrefix
+    vendorPrefix,
+    enumSerialization
   };
 }
 function generateJsonSchemaFromIR(ir, options) {
@@ -882,7 +1068,7 @@ function generateTypeNode(type, ctx) {
     case "primitive":
       return generatePrimitiveType(type);
     case "enum":
-      return generateEnumType(type);
+      return generateEnumType(type, ctx);
     case "array":
       return generateArrayType(type, ctx);
     case "object":
@@ -908,20 +1094,37 @@ function generatePrimitiveType(type) {
     type: type.primitiveKind === "integer" || type.primitiveKind === "bigint" ? "integer" : type.primitiveKind
   };
 }
-function generateEnumType(type) {
-  const hasDisplayNames = type.members.some((m) => m.displayName !== void 0);
-  if (hasDisplayNames) {
+function generateEnumType(type, ctx) {
+  if (ctx.enumSerialization === "oneOf") {
     return {
-      oneOf: type.members.map((m) => {
-        const entry = { const: m.value };
-        if (m.displayName !== void 0) {
-          entry.title = m.displayName;
-        }
-        return entry;
-      })
+      oneOf: type.members.map((m) => ({
+        const: m.value,
+        title: m.displayName ?? String(m.value)
+      }))
     };
   }
-  return { enum: type.members.map((m) => m.value) };
+  const schema = { enum: type.members.map((m) => m.value) };
+  const displayNames = buildEnumDisplayNameExtension(type);
+  if (displayNames !== void 0) {
+    schema[`${ctx.vendorPrefix}-display-names`] = displayNames;
+  }
+  return schema;
+}
+function buildEnumDisplayNameExtension(type) {
+  if (!type.members.some((member) => member.displayName !== void 0)) {
+    return void 0;
+  }
+  const displayNames = /* @__PURE__ */ Object.create(null);
+  for (const member of type.members) {
+    const key = String(member.value);
+    if (Object.hasOwn(displayNames, key)) {
+      throw new Error(
+        `Enum display-name key "${key}" is ambiguous after stringification. Use oneOf serialization for mixed string/number enum values that collide.`
+      );
+    }
+    displayNames[key] = member.displayName ?? key;
+  }
+  return displayNames;
 }
 function generateArrayType(type, ctx) {
   return {
@@ -1270,6 +1473,66 @@ function generateCustomType(type, ctx) {
   }
   return registration.toJsonSchema(type.payload, ctx.vendorPrefix);
 }
+var JSON_SCHEMA_STRUCTURAL_KEYWORDS = /* @__PURE__ */ new Set([
+  "$schema",
+  "$ref",
+  "$defs",
+  "$id",
+  "$anchor",
+  "$dynamicRef",
+  "$dynamicAnchor",
+  "$vocabulary",
+  "$comment",
+  "type",
+  "enum",
+  "const",
+  "properties",
+  "patternProperties",
+  "additionalProperties",
+  "required",
+  "items",
+  "prefixItems",
+  "additionalItems",
+  "contains",
+  "allOf",
+  "oneOf",
+  "anyOf",
+  "not",
+  "if",
+  "then",
+  "else",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+  "minContains",
+  "maxContains",
+  "format",
+  "title",
+  "description",
+  "default",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "examples",
+  "dependentRequired",
+  "dependentSchemas",
+  "propertyNames",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+  "contentEncoding",
+  "contentMediaType",
+  "contentSchema"
+]);
 function applyCustomConstraint(schema, constraint, ctx) {
   const registration = ctx.extensionRegistry?.findConstraint(constraint.constraintId);
   if (registration === void 0) {
@@ -1277,12 +1540,25 @@ function applyCustomConstraint(schema, constraint, ctx) {
       `Cannot generate JSON Schema for custom constraint "${constraint.constraintId}" without a matching extension registration`
     );
   }
-  assignVendorPrefixedExtensionKeywords(
-    schema,
-    registration.toJsonSchema(constraint.payload, ctx.vendorPrefix),
-    ctx.vendorPrefix,
-    `custom constraint "${constraint.constraintId}"`
-  );
+  const extensionSchema = registration.toJsonSchema(constraint.payload, ctx.vendorPrefix);
+  if (registration.emitsVocabularyKeywords) {
+    const target = schema;
+    for (const [key, value] of Object.entries(extensionSchema)) {
+      if (JSON_SCHEMA_STRUCTURAL_KEYWORDS.has(key)) {
+        throw new Error(
+          `Custom constraint "${constraint.constraintId}" with emitsVocabularyKeywords must not overwrite standard JSON Schema keyword "${key}"`
+        );
+      }
+      target[key] = value;
+    }
+  } else {
+    assignVendorPrefixedExtensionKeywords(
+      schema,
+      extensionSchema,
+      ctx.vendorPrefix,
+      `custom constraint "${constraint.constraintId}"`
+    );
+  }
 }
 function applyCustomAnnotation(schema, annotation, ctx) {
   const registration = ctx.extensionRegistry?.findAnnotation(annotation.annotationId);
@@ -1314,11 +1590,17 @@ function assignVendorPrefixedExtensionKeywords(schema, extensionSchema, vendorPr
 
 // src/json-schema/generator.ts
 function generateJsonSchema(form, options) {
+  const metadata = options?.metadata;
+  const vendorPrefix = options?.vendorPrefix;
+  const enumSerialization = options?.enumSerialization;
   const ir = canonicalizeChainDSL(
     form,
-    options?.metadata !== void 0 ? { metadata: options.metadata } : void 0
+    metadata !== void 0 ? { metadata } : void 0
   );
-  const internalOptions = options?.vendorPrefix === void 0 ? void 0 : { vendorPrefix: options.vendorPrefix };
+  const internalOptions = vendorPrefix === void 0 && enumSerialization === void 0 ? void 0 : {
+    ...vendorPrefix !== void 0 && { vendorPrefix },
+    ...enumSerialization !== void 0 && { enumSerialization }
+  };
   return generateJsonSchemaFromIR(ir, internalOptions);
 }