@api-components/api-type-document 4.2.34 → 4.2.38

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.34",
+  "version": "4.2.38",
   "license": "Apache-2.0",
   "main": "index.js",
   "module": "index.js",
@@ -28,7 +28,7 @@
     "@advanced-rest-client/arc-marked": "^1.1.0",
     "@advanced-rest-client/markdown-styles": "^3.1.4",
     "@anypoint-web-components/anypoint-button": "^1.2.3",
-    "@api-components/amf-helper-mixin": "^4.5.29",
+    "@api-components/amf-helper-mixin": "^4.5.34",
     "@api-components/api-annotation-document": "^4.1.0",
     "@api-components/api-resource-example-document": "^4.3.3",
     "@open-wc/dedupe-mixin": "^1.3.0",
@@ -39,15 +39,15 @@
     "@anypoint-web-components/anypoint-checkbox": "^1.2.2",
     "@anypoint-web-components/anypoint-styles": "^1.0.2",
     "@api-components/api-model-generator": "^0.2.14",
-    "@commitlint/cli": "^13.2.0",
+    "@commitlint/cli": "^13.2.1",
     "@commitlint/config-conventional": "^13.2.0",
     "@open-wc/eslint-config": "^4.2.0",
-    "@open-wc/testing": "^2.5.15",
+    "@open-wc/testing": "^2.5.32",
     "@web/dev-server": "^0.1.24",
     "@web/test-runner": "^0.13.18",
-    "@web/test-runner-playwright": "0.8.10",
-    "eslint": "^7.32.0",
-    "eslint-config-prettier": "^8.1.0",
+    "@web/test-runner-playwright": "^0.11.0",
+    "eslint": "^8.0.0",
+    "eslint-config-prettier": "^8.3.0",
     "husky": "^7.0.2",
     "lint-staged": "^11.1.2",
     "sinon": "^11.1.2",

package/src/ApiTypeDocument.d.ts

@@ -54,6 +54,23 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
   selectedMediaType: number;
   // The type after it has been resolved.
   _resolvedType: Object;
+  /**
+   * Computed properties for object types.
+   * This is a reactive property that is recalculated when type, amf, or renderReadOnly changes.
+   */
+  _computedProperties: any[] | undefined;
+  /**
+   * Resolved type for examples with all link-target references resolved
+   */
+  _resolvedExampleType: Object | undefined;
+  /**
+   * Whether to show the examples section
+   */
+  _showExamples: boolean | undefined;
+  /**
+   * Effective media type for examples
+   */
+  _exampleMediaType: string | undefined;
   /**
    * Should be set if described properties has a parent type.
    * This is used when recursively iterating over properties.
@@ -242,6 +259,15 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
    */
   _computeProperties(item: any): any[]|undefined;
 
+  /**
+   * Deeply resolves link-target references in a type and its nested properties.
+   * This is essential for rendering complete examples with nested objects.
+   *
+   * @param type The type to resolve
+   * @returns The type with all link-target references resolved
+   */
+  _deepResolveType(type: any): any|undefined;
+
   /**
    * Computes list values for `andTypes` property.
    * @param items List of OAS' "and" properties

package/src/ApiTypeDocument.js

@@ -68,6 +68,22 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
       selectedMediaType: { type: Number },
       // The type after it has been resolved.
       _resolvedType: { type: Object },
+      /**
+       * Computed properties from the resolved type
+       */
+      _computedProperties: { type: Array },
+      /**
+       * Resolved type for examples with all link-target references resolved
+       */
+      _resolvedExampleType: { type: Object },
+      /**
+       * Whether to show the examples section
+       */
+      _showExamples: { type: Boolean },
+      /**
+       * Effective media type for examples
+       */
+      _exampleMediaType: { type: String },
       /**
        * Should be set if described properties has a parent type.
        * This is used when recursively iterating over properties.
@@ -325,6 +341,10 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
      */
     this.selectedAnyOf = undefined;
     this.renderReadOnly = false;
+    this.noMainExample = false;
+    this._hasExamples = false;
+    this._renderMainExample = false;
+    this._cachedDeepResolvedType = undefined;
 
     this._isPropertyReadOnly = this._isPropertyReadOnly.bind(this);
     this.noMediaSelector = false;
@@ -345,6 +365,37 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
     return isScalar ? false : !!(!noMainExample && hasExamples);
   }
 
+  /**
+   * Called when properties change
+   * @param {Map} changedProperties Changed properties
+   */
+  updated(changedProperties) {
+    super.updated(changedProperties);
+    
+    // If amf changed and we have a type, recalculate properties synchronously
+    if (changedProperties.has('amf') && this._resolvedType && this.amf) {
+      // Cancel any pending debounced calls and recalculate
+      this.__typeChangeDebouncer = false;
+      this._typeChanged(this._resolvedType);
+      // _typeChanged will update _computedProperties, _isGrpcApi, and _deepResolvedType
+    }
+    
+    // If renderReadOnly changed and we have an object, recalculate properties
+    // This is needed because _filterReadOnlyProperties depends on this.renderReadOnly
+    if (changedProperties.has('renderReadOnly') && this._resolvedType && this.isObject) {
+      this._computedProperties = this._computeProperties(this._resolvedType);
+    }
+    
+    // If noMainExample changed, recalculate whether to render examples
+    if (changedProperties.has('noMainExample') && this._resolvedType) {
+      this._showExamples = !this.noMainExample && (
+        this.renderMediaSelector ||
+        this.isObject ||
+        this._renderMainExample
+      );
+    }
+  }
+
   /**
    * Called when resolved type or amf changed.
    * Creates a debouncer to compute UI values so it's independent of
@@ -397,9 +448,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);
@@ -455,6 +513,32 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
     this.isAnd = isAnd;
     this.isOneOf = isOneOf;
     this.isAnyOf = isAnyOf;
+    
+    // Compute properties for objects - this needs to be reactive
+    if (isObject) {
+      this._computedProperties = this._computeProperties(type);
+    } else {
+      this._computedProperties = undefined;
+    }
+    
+    // Always deep resolve for examples (resolves link-target references for gRPC and similar)
+    // This is cheap if there are no link-targets
+    if (type) {
+      this._resolvedExampleType = this._deepResolveType(type);
+    } else {
+      this._resolvedExampleType = type;
+    }
+    
+    // Determine if we should show the examples section
+    // Priority: noMainExample (hide) > renderMediaSelector (show) > isObject (show) > _renderMainExample
+    this._showExamples = !this.noMainExample && (
+      this.renderMediaSelector || // Need to show the section for the media type selector
+      isObject ||                 // Objects 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);
   }
 
   /**
@@ -526,18 +610,11 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
     if (Array.isArray(item)) {
       [item] = item;
     }
+    // For array types in unions, return the array itself instead of unwrapping to items
+    // This preserves the "array of" indicator in the UI
     if (this._hasType(item, this.ns.aml.vocabularies.shapes.ArrayShape)) {
       item = this._resolve(item);
-      const itemsKey = this._getAmfKey(this.ns.aml.vocabularies.shapes.items);
-      const items = this._ensureArray(item[itemsKey]);
-      if (items && items.length === 1) {
-        let result = items[0];
-        if (Array.isArray(result)) {
-          [result] = result;
-        }
-        result = this._resolve(result);
-        return result;
-      }
+      return item;
     }
     if (Array.isArray(item)) {
       [item] = item;
@@ -546,6 +623,91 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
     return this._resolve(item);
   }
 
+
+  /**
+   * Deeply resolves link-target references in a type for example generation.
+   * This ensures that nested objects show their full structure in examples.
+   * This is needed for APIs like gRPC where nested types use link-target references.
+   * 
+   * @param {Object} type The type to resolve
+   * @return {Object} The deeply resolved type
+   */
+  _deepResolveType(type) {
+    if (!type || !this.amf) {
+      return type;
+    }
+
+    const resolved = this._resolve(type);
+    if (!resolved) {
+      return type;
+    }
+
+    // Get properties
+    const propertyKey = this._getAmfKey(this.ns.w3.shacl.property);
+    const properties = this._ensureArray(resolved[propertyKey]);
+    
+    if (!properties || !properties.length) {
+      return resolved;
+    }
+
+    // Create a new type object with deeply resolved properties
+    const deepResolved = { ...resolved };
+    const linkTargetKey = this._getAmfKey(this.ns.aml.vocabularies.document.linkTarget);
+    const rangeKey = this._getAmfKey(this.ns.raml.vocabularies.shapes.range);
+    
+    // Resolve each property's range
+    const resolvedProperties = properties.map(prop => {
+      const resolvedProp = this._resolve(prop);
+      if (!resolvedProp) {
+        return prop;
+      }
+
+      const range = this._ensureArray(resolvedProp[rangeKey])[0];
+      if (!range) {
+        return resolvedProp;
+      }
+
+      // If the range has a link-target, resolve it
+      if (range[linkTargetKey]) {
+        const linkTargetId = this._ensureArray(range[linkTargetKey])[0];
+        if (linkTargetId && linkTargetId['@id']) {
+          const targetId = linkTargetId['@id'];
+          
+          // Find the target
+          const declares = this._computeDeclares(this.amf);
+          let target = declares ? this._findById(declares, targetId) : undefined;
+          
+          if (!target) {
+            const references = this._computeReferences(this.amf);
+            if (references && references.length) {
+              for (let i = 0; i < references.length && !target; i++) {
+                const refDeclares = this._computeDeclares(references[i]);
+                if (refDeclares) {
+                  target = this._findById(refDeclares, targetId);
+                }
+              }
+            }
+          }
+
+          // If target found, replace the range with the resolved target
+          if (target) {
+            const resolvedTarget = this._resolve(target);
+            if (resolvedTarget) {
+              const newProp = { ...resolvedProp };
+              newProp[rangeKey] = [resolvedTarget];
+              return newProp;
+            }
+          }
+        }
+      }
+
+      return resolvedProp;
+    });
+
+    deepResolved[propertyKey] = resolvedProperties;
+    return deepResolved;
+  }
+
   /**
    * Helper function for the view. Extracts `http://www.w3.org/ns/shacl#property`
    * from the shape model
@@ -561,16 +723,65 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
       return item;
     }
     
+    // For objects with link-target, we need to find the actual target with properties
+    const linkTargetKey = this._getAmfKey(this.ns.aml.vocabularies.document.linkTarget);
+    let resolvedItem = item;
+    
+    if (item[linkTargetKey] && this.amf) {
+      const linkTargetId = this._ensureArray(item[linkTargetKey])[0];
+      if (linkTargetId && linkTargetId['@id']) {
+        const targetId = linkTargetId['@id'];
+        // Try to find the target in declares
+        const declares = this._computeDeclares(this.amf);
+        let target = declares ? this._findById(declares, targetId) : undefined;
+        
+        // If not found in declares, search in references
+        if (!target) {
+          const references = this._computeReferences(this.amf);
+          if (references && references.length) {
+            for (let i = 0; i < references.length && !target; i++) {
+              const refDeclares = this._computeDeclares(references[i]);
+              if (refDeclares) {
+                target = this._findById(refDeclares, targetId);
+              }
+            }
+          }
+        }
+        
+        // If we found the target and it has properties, use it
+        // Don't use the target directly to avoid caching issues
+        const propertyKey = this._getAmfKey(this.ns.w3.shacl.property);
+        if (target && target[propertyKey]) {
+          // Use the target's properties but keep the original item structure
+          // This prevents issues with cached __apicResolved flags
+          resolvedItem = this._resolve(target);
+          // If resolve returned the same object or failed, fallback to standard resolve
+          if (!resolvedItem || !resolvedItem[propertyKey]) {
+            resolvedItem = this._resolve(item);
+          }
+        }
+      }
+    }
+    
+    // Fallback to standard resolve if no link-target or target not found
+    if (resolvedItem === item) {
+      resolvedItem = this._resolve(item);
+    }
+    
+    if (!resolvedItem) {
+      return undefined;
+    }
+    
     const propertyKey = this._getAmfKey(this.ns.w3.shacl.property);
-    const itemProperties = this._ensureArray(item[propertyKey]||[])
+    const itemProperties = this._ensureArray(resolvedItem[propertyKey]||[])
     const additionalPropertiesKey = this._getAmfKey(this.ns.w3.shacl.additionalPropertiesSchema);
 
     // If the item doesn't have additional properties, filter the read-only properties and return
-    if (!item[additionalPropertiesKey]) {
+    if (!resolvedItem[additionalPropertiesKey]) {
       return this._filterReadOnlyProperties(itemProperties)
     }
 
-    const additionalPropertiesSchema = this._ensureArray(item[additionalPropertiesKey])
+    const additionalPropertiesSchema = this._ensureArray(resolvedItem[additionalPropertiesKey])
     
     // If the item does have additional properties, ensure they are in an array
     const additionalProperties = this._ensureArray(additionalPropertiesSchema[0][propertyKey] || additionalPropertiesSchema[0])
@@ -688,7 +899,7 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
    * @return {TemplateResult[]|string} Templates for object properties
    */
   _objectTemplate() {
-    const items = this._computeProperties(this._resolvedType);
+    const items = this._computedProperties;
     if (!items || !items.length) {
       return '';
     }
@@ -924,8 +1135,16 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
     parts +=
       'code-content-action-button-active, code-wrapper, example-code-wrapper, markdown-html';
     const mediaTypes = (this.mediaTypes || []);
+    // Use cached values if available, otherwise fallback to computed values
+    const shouldRenderExamples = this._showExamples !== undefined 
+      ? this._showExamples 
+      : this._renderMainExample;
+    const exampleMediaType = this._exampleMediaType !== undefined
+      ? this._exampleMediaType
+      : (this.mediaType || (this.isObject ? 'application/json' : undefined));
+    
     return html`<style>${this.styles}</style>
-      <section class="examples" ?hidden="${!this._renderMainExample}">
+      ${shouldRenderExamples ? html`<section class="examples">
         ${this.shouldRenderMediaSelector
         ? html`<div class="media-type-selector">
               <span>Media type:</span>
@@ -950,18 +1169,18 @@ export class ApiTypeDocument extends PropertyDocumentMixin(LitElement) {
         <api-resource-example-document
           .amf="${this.amf}"
           .payloadId="${this.selectedBodyId}"
-          .examples="${this._resolvedType}"
-          .mediaType="${this.mediaType}"
+          .examples="${this._resolvedExampleType || this._resolvedType}"
+          .mediaType="${exampleMediaType}"
           .typeName="${this.parentTypeName}"
           @has-examples-changed="${this._hasExamplesHandler}"
           ?noauto="${!!this.isScalar}"
           ?noactions="${this.noExamplesActions}"
-          ?rawOnly="${!this.mediaType}"
+          ?rawOnly="${!exampleMediaType}"
           ?compatibility="${this.compatibility}"
           exportParts="${parts}"
           ?renderReadOnly="${this.renderReadOnly}"
         ></api-resource-example-document>
-      </section>
+      </section>` : ''}
 
       ${this.isObject ? this._objectTemplate() : ''}
       ${this.isArray ? this._arrayTemplate() : ''}

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"