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

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.37",
   "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
@@ -455,6 +506,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 +603,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 +616,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 +716,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 +892,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 +1128,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 +1162,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() : ''}