build(docs-infra): improve directive API doc templates (#25768)

Closes #22790
Closes #25530

PR Close #25768

aio/tools/transforms/angular-base-package/rendering/hasValues.js

@@ -3,7 +3,21 @@ module.exports = function hasValues() {
     name: 'hasValues',
     process: function(list, property) {
       if (!list || !Array.isArray(list)) return false;
-      return list.some(item => item[property]);
+      return list.some(item => readProperty(item, property.split('.'), 0));
     }
   };
-};
+};
+
+/**
+ * Search deeply into an object via a collection of property segments, starting at the
+ * indexed segment.
+ *
+ * E.g. if `obj = { a: { b: { c: 10 }}}` then
+ *  `readProperty(obj, ['a', 'b', 'c'], 0)` will return true;
+ * but
+ *  `readProperty(obj, ['a', 'd'], 0)` will return false;
+ */
+function readProperty(obj, propertySegments, index) {
+  const value = obj[propertySegments[index]];
+  return !!value && (index === propertySegments.length - 1 || readProperty(value, propertySegments, index + 1));
+}

aio/tools/transforms/angular-base-package/rendering/hasValues.spec.js

@@ -7,13 +7,37 @@ describe('hasValues filter', () => {
 
   it('should be called "hasValues"', function() { expect(filter.name).toEqual('hasValues'); });
 
-  it('should return true if the specified property is truthy on any item in the list', function() {
-    expect(filter.process([], 'a')).toEqual(false);
-    expect(filter.process(0, 'a')).toEqual(false);
-    expect(filter.process({}, 'a')).toEqual(false);
+  it('should return true if the specified property path is truthy on any item in the list', function() {
     expect(filter.process([{a: 1}], 'a')).toEqual(true);
-    expect(filter.process([{b: 2}], 'a')).toEqual(false);
     expect(filter.process([{a: 1, b: 2}], 'a')).toEqual(true);
     expect(filter.process([{b: 2}, {a: 1}], 'a')).toEqual(true);
+
+    expect(filter.process([{a:{b:1}}], 'a.b')).toEqual(true);
+    expect(filter.process([{a:{b:1}, b: 2}], 'a.b')).toEqual(true);
+    expect(filter.process([{b: 2}, {a:{b:1}}], 'a.b')).toEqual(true);
+  });
+
+  it('should return false if the value is not an object', () => {
+    expect(filter.process([], 'a')).toEqual(false);
+    expect(filter.process(0, 'a')).toEqual(false);
+    expect(filter.process([], 'a.b')).toEqual(false);
+    expect(filter.process(0, 'a.b')).toEqual(false);
+  });
+
+  it('should return false if the property exists but is falsy', () => {
+    expect(filter.process([{a: false}], 'a')).toEqual(false);
+    expect(filter.process([{a: ''}], 'a')).toEqual(false);
+    expect(filter.process([{a: 0}], 'a')).toEqual(false);
+    expect(filter.process([{a: null}], 'a')).toEqual(false);
+    expect(filter.process([{a: undefined}], 'a')).toEqual(false);
+  });
+
+  it('should return false if any of the properties in the path do not exist', () => {
+    expect(filter.process({}, 'a')).toEqual(false);
+    expect(filter.process({}, 'a.b')).toEqual(false);
+
+    expect(filter.process([{b: 2}], 'a')).toEqual(false);
+    expect(filter.process([{a: 2}], 'a.b')).toEqual(false);
+    expect(filter.process([{a: {}}], 'a.b.c')).toEqual(false);
   });
 });