@api-components/api-type-document 4.2.37 → 4.2.39

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-components/api-type-document",
   "description": "A documentation table for type (resource) properties. Works with AMF data model",
-  "version": "4.2.37",
+  "version": "4.2.39",
   "license": "Apache-2.0",
   "main": "index.js",
   "module": "index.js",

package/src/ApiTypeDocument.js

@@ -391,6 +391,7 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
       this._showExamples = !this.noMainExample && (
         this.renderMediaSelector ||
         this.isObject ||
+        this.isArray ||
         this._renderMainExample
       );
     }
@@ -448,9 +449,16 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
     } else if (
       this._hasType(type, shapesKey.UnionShape)
     ) {
-      isUnion = true;
-      key = this._getAmfKey(shapesKey.anyOf);
-      this.unionTypes = this._computeTypes(type, key);
+      // Check if this is a nullable union (type | null) which should be rendered as scalar
+      const nullableCheck = this._checkNullableUnion(type);
+      if (nullableCheck && nullableCheck.isNullable) {
+        // Treat nullable types as scalar for cleaner rendering
+        isScalar = true;
+      } else {
+        isUnion = true;
+        key = this._getAmfKey(shapesKey.anyOf);
+        this.unionTypes = this._computeTypes(type, key);
+      }
     } else if (this._hasProperty(type, this.ns.w3.shacl.xone)) {
       isOneOf = true;
       key = this._getAmfKey(this.ns.w3.shacl.xone);
@@ -523,15 +531,16 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
     }
     
     // Determine if we should show the examples section
-    // Priority: noMainExample (hide) > renderMediaSelector (show) > isObject (show) > _renderMainExample
+    // Priority: noMainExample (hide) > renderMediaSelector (show) > isObject (show) > isArray (show) > _renderMainExample
     this._showExamples = !this.noMainExample && (
       this.renderMediaSelector || // Need to show the section for the media type selector
       isObject ||                 // Objects can generate examples automatically
+      isArray ||                  // Arrays can generate examples automatically
       this._renderMainExample     // Has explicit examples
     );
     
-    // Effective media type - use 'application/json' as default for objects without mediaType
-    this._exampleMediaType = this.mediaType || (isObject ? 'application/json' : undefined);
+    // Effective media type - use 'application/json' as default for objects and arrays without mediaType
+    this._exampleMediaType = this.mediaType || (isObject || isArray ? 'application/json' : undefined);
   }
 
   /**
@@ -1134,7 +1143,7 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
       : this._renderMainExample;
     const exampleMediaType = this._exampleMediaType !== undefined
       ? this._exampleMediaType
-      : (this.mediaType || (this.isObject ? 'application/json' : undefined));
+      : (this.mediaType || (this.isObject || this.isArray ? 'application/json' : undefined));
     
     return html`<style>${this.styles}</style>
       ${shouldRenderExamples ? html`<section class="examples">

package/src/PropertyDocumentMixin.d.ts

@@ -49,6 +49,15 @@ interface PropertyDocumentMixin extends AmfHelperMixin {
    */
   graph: boolean;
 
+  /**
+   * Checks if a union shape represents a nullable type (union with null).
+   * A nullable type is a union of exactly 2 members where one is NilShape.
+   * 
+   * @param range AMF range object (should be UnionShape)
+   * @returns Returns {baseType, isNullable: true} if nullable, undefined otherwise
+   */
+  _checkNullableUnion(range: any): { baseType: any; isNullable: boolean } | undefined;
+
   /**
    * Computes type from a `http://raml.org/vocabularies/shapes#range` object
    *

package/src/PropertyDocumentMixin.js

@@ -107,6 +107,65 @@ const mxFunction = (base) => {
       this._hasMediaType = false;
     }
 
+    /**
+     * Checks if a union shape represents a nullable type (union with null).
+     * A nullable type is a union of exactly 2 members where one is NilShape
+     * and the other is any type (scalar, array, object, etc.).
+     * 
+     * This is specifically for OpenAPI 3.0 nullable: true which AMF converts
+     * to union of type + null. This simplifies the rendering to "Type or null"
+     * instead of showing a full union selector.
+     * 
+     * @param {any} range AMF range object (should be UnionShape)
+     * @return {Object|undefined} Returns {baseType, isNullable: true} if nullable, undefined otherwise
+     */
+    _checkNullableUnion(range) {
+      if (!range || !this._hasType(range, this.ns.aml.vocabularies.shapes.UnionShape)) {
+        return undefined;
+      }
+      
+      const key = this._getAmfKey(this.ns.aml.vocabularies.shapes.anyOf);
+      const unionMembers = this._ensureArray(range[key]);
+      
+      if (!unionMembers || unionMembers.length !== 2) {
+        return undefined;
+      }
+      
+      // Check if one member is NilShape
+      let nilIndex = -1;
+      let baseTypeIndex = -1;
+      
+      for (let i = 0; i < unionMembers.length; i++) {
+        let member = unionMembers[i];
+        if (Array.isArray(member)) {
+          [member] = member;
+        }
+        member = this._resolve(member);
+        
+        if (this._hasType(member, this.ns.aml.vocabularies.shapes.NilShape)) {
+          nilIndex = i;
+        } else {
+          baseTypeIndex = i;
+        }
+      }
+      
+      // If we found exactly one nil and one non-nil type, it's a nullable
+      if (nilIndex !== -1 && baseTypeIndex !== -1) {
+        let baseType = unionMembers[baseTypeIndex];
+        if (Array.isArray(baseType)) {
+          [baseType] = baseType;
+        }
+        baseType = this._resolve(baseType);
+        
+        return {
+          baseType,
+          isNullable: true
+        };
+      }
+      
+      return undefined;
+    }
+
     /**
      * Computes type from a `http://raml.org/vocabularies/shapes#range` object
      *
@@ -122,6 +181,12 @@ const mxFunction = (base) => {
         return this._computeScalarDataType(range);
       }
       if (this._hasType(range, rs.UnionShape)) {
+        // Check if this is a nullable union (type | null)
+        const nullableCheck = this._checkNullableUnion(range);
+        if (nullableCheck && nullableCheck.isNullable) {
+          const baseTypeName = this._computeRangeDataType(nullableCheck.baseType);
+          return `${baseTypeName} or null`;
+        }
         return 'Union';
       }
       if (this._hasType(range, rs.ArrayShape)) {
@@ -145,9 +210,6 @@ const mxFunction = (base) => {
       if (this._hasType(range, rs.TupleShape)) {
         return 'Tuple';
       }
-      if (this._hasType(range, rs.UnionShape)) {
-        return 'Union';
-      }
       if (this._hasType(range, rs.RecursiveShape)) {
         return 'Recursive';
       }
@@ -313,7 +375,12 @@ const mxFunction = (base) => {
      * @return {Boolean}
      */
     _computeIsUnion(range) {
-      return this._hasType(range, this.ns.aml.vocabularies.shapes.UnionShape);
+      if (!this._hasType(range, this.ns.aml.vocabularies.shapes.UnionShape)) {
+        return false;
+      }
+      // Check if it's a nullable union (which we don't treat as union for UI)
+      const nullableCheck = this._checkNullableUnion(range);
+      return !nullableCheck; // Only true if NOT nullable
     }
 
     /**
@@ -325,7 +392,15 @@ const mxFunction = (base) => {
      * @return {Boolean}
      */
     _computeIsObject(range) {
-      return this._hasType(range, this.ns.w3.shacl.NodeShape);
+      if (this._hasType(range, this.ns.w3.shacl.NodeShape)) {
+        return true;
+      }
+      // Check if it's a nullable object
+      const nullableCheck = this._checkNullableUnion(range);
+      if (nullableCheck) {
+        return this._hasType(nullableCheck.baseType, this.ns.w3.shacl.NodeShape);
+      }
+      return false;
     }
 
     /**
@@ -337,7 +412,15 @@ const mxFunction = (base) => {
      * @return {Boolean}
      */
     _computeIsArray(range) {
-      return this._hasType(range, this.ns.aml.vocabularies.shapes.ArrayShape);
+      if (this._hasType(range, this.ns.aml.vocabularies.shapes.ArrayShape)) {
+        return true;
+      }
+      // Check if it's a nullable array
+      const nullableCheck = this._checkNullableUnion(range);
+      if (nullableCheck) {
+        return this._hasType(nullableCheck.baseType, this.ns.aml.vocabularies.shapes.ArrayShape);
+      }
+      return false;
     }
 
     /**

package/src/PropertyShapeDocument.js

@@ -735,7 +735,14 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
     if (!this.isComplex || !this.opened || this.isScalarArray) {
       return '';
     }
-    const range = this._resolve(this.range);
+    let range = this._resolve(this.range);
+    
+    // If this is a nullable complex type, extract the base type
+    const nullableCheck = this._checkNullableUnion(range);
+    if (nullableCheck) {
+      range = nullableCheck.baseType;
+    }
+    
     const parentTypeName = this._getParentTypeName();
     return html`<api-type-document
       class="children complex"