feat: introduce meta element APIs v2

Author: davidlj95

projects/ngx-meta/api-extractor/ngx-meta.api.md

@@ -164,6 +164,12 @@ export type MetadataSetterFactory<T> = (...deps: Exclude<FactoryProvider['deps']
 // @public
 export type MetadataValues = object;
 
+// @alpha (undocumented)
+export const NGX_META_ELEMENT_SETTER: InjectionToken<NgxMetaElementSetter>;
+
+// @alpha (undocumented)
+export const NGX_META_ELEMENTS_SETTER: InjectionToken<NgxMetaElementsSetter>;
+
 // @public
 export class NgxMetaCoreModule {
     // Warning: (ae-forgotten-export) The symbol "CoreFeatures" needs to be exported by the entry point all-entry-points.d.ts
@@ -177,6 +183,27 @@ export interface NgxMetaCoreModuleForRootOptions {
     defaults?: MetadataValues;
 }
 
+// @alpha
+export type NgxMetaElementAttributes = Partial<{
+    charset: string;
+    content: string;
+    'http-equiv': string;
+    id: string;
+    itemprop: string;
+    name: string;
+    property: string;
+    scheme: string;
+    url: string;
+}> & {
+    [key: string]: string;
+};
+
+// @alpha (undocumented)
+export type NgxMetaElementSetter = (nameAttribute: readonly [name: string, value: string], content: NgxMetaElementAttributes | undefined) => void;
+
+// @alpha (undocumented)
+export type NgxMetaElementsSetter = (nameAttribute: readonly [name: string, value: string], contents: ReadonlyArray<NgxMetaElementAttributes | undefined>) => void;
+
 // @public
 export class NgxMetaJsonLdModule {
 }
@@ -529,12 +556,21 @@ export const _URL_RESOLVER: InjectionToken<_UrlResolver>;
 // @internal (undocumented)
 export type _UrlResolver = (url: URL | string | undefined | null | AngularRouterUrl) => string | undefined | null;
 
+// @alpha
+export const withContentAttribute: (content: string | null | undefined) => NgxMetaElementAttributes | undefined;
+
+// @alpha
+export const withNameAttribute: (value: string) => readonly ["name", string];
+
 // @public
 export const withNgxMetaBaseUrl: (baseUrl: BaseUrl) => CoreFeature<CoreFeatureKind.BaseUrl>;
 
 // @public
 export const withNgxMetaDefaults: (defaults: MetadataValues) => CoreFeature<CoreFeatureKind.Defaults>;
 
+// @alpha
+export const withPropertyAttribute: (value: string) => string[];
+
 // (No @packageDocumentation comment for this package)
 
 ```

projects/ngx-meta/src/core/src/meta-elements/index.ts

@@ -9,3 +9,4 @@ export {
 export { NgxMetaMetaService } from './ngx-meta-meta.service'
 export { NgxMetaMetaContent } from './ngx-meta-meta-content'
 export { NgxMetaMetaDefinition } from './ngx-meta-meta-definition'
+export * from './v2'

projects/ngx-meta/src/core/src/meta-elements/v2/__tests__/add-meta-elements.ts

@@ -0,0 +1,5 @@
+import { TestBed } from '@angular/core/testing'
+import { Meta, MetaDefinition } from '@angular/platform-browser'
+
+export const addMetaElements = (tags: ReadonlyArray<MetaDefinition>) =>
+  TestBed.inject(Meta).addTags(tags as MetaDefinition[])

projects/ngx-meta/src/core/src/meta-elements/v2/__tests__/clear-metas-after-each.ts

@@ -0,0 +1,10 @@
+import { TestBed } from '@angular/core/testing'
+import { Meta } from '@angular/platform-browser'
+
+export const clearMetasAfterEach = (attributeSelector: string) => {
+  afterEach(() => {
+    TestBed.inject(Meta)
+      .getTags(attributeSelector)
+      .forEach((tag) => tag.remove())
+  })
+}

projects/ngx-meta/src/core/src/meta-elements/v2/__tests__/get-meta-elements-by-selector.ts

@@ -0,0 +1,5 @@
+import { TestBed } from '@angular/core/testing'
+import { Meta } from '@angular/platform-browser'
+
+export const getMetaElementsBySelector = (attrSelector: string) =>
+  TestBed.inject(Meta).getTags(attrSelector)

projects/ngx-meta/src/core/src/meta-elements/v2/__tests__/html-attributes-to-json.ts

@@ -0,0 +1,5 @@
+export const htmlAttributesToJson = (attributes: NamedNodeMap): object =>
+  [...Array(attributes.length).keys()]
+    .map((index) => attributes.item(index))
+    .map((item) => (item ? { [item.name]: item.value } : {}))
+    .reduce((acc, curr) => ({ ...acc, ...curr }), {})

projects/ngx-meta/src/core/src/meta-elements/v2/index.ts

@@ -0,0 +1,14 @@
+export {
+  NGX_META_ELEMENT_SETTER,
+  NgxMetaElementSetter,
+} from './ngx-meta-element-setter'
+export {
+  NGX_META_ELEMENTS_SETTER,
+  NgxMetaElementsSetter,
+} from './ngx-meta-elements-setter'
+export { NgxMetaElementAttributes } from './ngx-meta-element-attributes'
+export {
+  withNameAttribute,
+  withPropertyAttribute,
+  withContentAttribute,
+} from './meta-elements-helpers'

projects/ngx-meta/src/core/src/meta-elements/v2/meta-elements-helpers.ts

@@ -0,0 +1,36 @@
+import { NgxMetaElementAttributes } from './ngx-meta-element-attributes'
+
+/**
+ * Utility function to specify a `<meta name="{name}">` element.
+ *
+ * See {@link NgxMetaElementSetter} for examples.
+ *
+ * @param value - Value for the `name` attribute of the `<meta>` element
+ *
+ * @alpha
+ */
+export const withNameAttribute = (value: string) => ['name', value] as const
+/**
+ * Utility function to specify a `<meta property="{property}">` element.
+ *
+ * See {@link NgxMetaElementSetter} for examples.
+ *
+ * @param value - Value for the `property` attribute of the `<meta>` element
+ *
+ * @alpha
+ */
+export const withPropertyAttribute = (value: string) => ['property', value]
+
+/**
+ * Utility function to create an {@link NgxMetaElementAttributes} specifying the `content` attribute to the
+ * given `value`. Unless given `value` is `null` or `undefined`. In that case, `undefined` is returned.
+ *
+ * See {@link NgxMetaElementSetter} for examples.
+ *
+ * @param content - Value for the `property` attribute of the `<meta>` element
+ *
+ * @alpha
+ */
+export const withContentAttribute = (
+  content: string | null | undefined,
+): NgxMetaElementAttributes | undefined => (content ? { content } : undefined)

projects/ngx-meta/src/core/src/meta-elements/v2/ngx-meta-element-attributes.ts

@@ -0,0 +1,29 @@
+// noinspection JSValidateJSDoc
+/**
+ * Models a `<meta>` element HTML's attributes as a key / value map.
+ *
+ * Inspired on Angular's {@link https://angular.dev/api/platform-browser/MetaDefinition/ | MetaDefinition}
+ *
+ * Only difference is `http-equiv` property.
+ *
+ * @alpha
+ */
+export type NgxMetaElementAttributes = Partial<{
+  charset: string
+  content: string
+  /**
+   * In an Angular's {@link https://angular.dev/api/platform-browser/MetaDefinition/ | MetaDefinition},
+   * `httpEquiv` would also be accepted. This way no need to quote the key property.
+   *
+   * This way there's no need to map attribute names.
+   */
+  'http-equiv': string
+  id: string
+  itemprop: string
+  name: string
+  property: string
+  scheme: string
+  url: string
+}> & {
+  [key: string]: string
+}

projects/ngx-meta/src/core/src/meta-elements/v2/ngx-meta-element-setter.spec.ts

@@ -0,0 +1,117 @@
+import { TestBed } from '@angular/core/testing'
+import {
+  NGX_META_ELEMENT_SETTER,
+  NgxMetaElementSetter,
+} from './ngx-meta-element-setter'
+import {
+  withContentAttribute,
+  withNameAttribute,
+} from './meta-elements-helpers'
+import { htmlAttributesToJson } from './__tests__/html-attributes-to-json'
+import { getMetaElementsBySelector } from './__tests__/get-meta-elements-by-selector'
+import { clearMetasAfterEach } from './__tests__/clear-metas-after-each'
+import { addMetaElements } from './__tests__/add-meta-elements'
+
+describe('Meta element setter', () => {
+  const dummyMetaNameAttribute = withNameAttribute('dummy')
+  const dummyMetaAttributeSelector = 'name="dummy"'
+  const dummyMetaContentAttribute = withContentAttribute('dummy')
+  const dummyMetaAttributes = { name: 'dummy', content: 'dummy' }
+
+  clearMetasAfterEach(dummyMetaAttributeSelector)
+
+  describe('when no element exists yet', () => {
+    describe('when no content is provided', () => {
+      it('should not create the meta element', () => {
+        const sut = makeSut()
+
+        sut(dummyMetaNameAttribute, undefined)
+
+        const elements = getMetaElementsBySelector(dummyMetaAttributeSelector)
+        expect(elements).toHaveSize(0)
+      })
+    })
+
+    describe('when content is provided', () => {
+      it('should create the meta element', () => {
+        const sut = makeSut()
+
+        sut(dummyMetaNameAttribute, dummyMetaContentAttribute)
+
+        const elements = getMetaElementsBySelector(dummyMetaAttributeSelector)
+        expect(elements).toHaveSize(1)
+        const element = elements[0]
+        expect(htmlAttributesToJson(element.attributes)).toEqual(
+          dummyMetaAttributes,
+        )
+      })
+    })
+  })
+
+  describe('when an element already exists', () => {
+    let sut: NgxMetaElementSetter
+
+    beforeEach(() => {
+      sut = makeSut()
+      addMetaElements([dummyMetaAttributes])
+      expect(getMetaElementsBySelector(dummyMetaAttributeSelector))
+        .withContext('test setup: element should exist')
+        .toHaveSize(1)
+    })
+
+    describe('when no content is provided', () => {
+      it('should remove the element', () => {
+        sut(dummyMetaNameAttribute, undefined)
+
+        expect(
+          getMetaElementsBySelector(dummyMetaAttributeSelector),
+        ).toHaveSize(0)
+      })
+    })
+
+    describe('when content is provided', () => {
+      const anotherContent = 'another-dummy-content'
+
+      it('should update the element', () => {
+        sut(dummyMetaNameAttribute, withContentAttribute(anotherContent))
+
+        const elements = getMetaElementsBySelector(dummyMetaAttributeSelector)
+        expect(elements).toHaveSize(1)
+        const element = elements[0]
+        expect(htmlAttributesToJson(element.attributes)).toEqual({
+          ...dummyMetaAttributes,
+          content: anotherContent,
+        })
+      })
+    })
+  })
+
+  describe('with content attribute utility function', () => {
+    const sut = withContentAttribute
+
+    describe('when no content is provided', () => {
+      const TEST_CASES = [null, undefined]
+
+      TEST_CASES.forEach((testCase) => {
+        describe(`like when ${testCase}`, () => {
+          it('should return nothing', () => {
+            expect(sut(testCase)).toBeUndefined()
+          })
+        })
+      })
+    })
+
+    describe('when content is provided', () => {
+      const dummyContent = 'dummy'
+
+      it('should return the content value inside the content key', () => {
+        expect(sut(dummyContent)).toEqual({ content: dummyContent })
+      })
+    })
+  })
+})
+
+const makeSut = (): NgxMetaElementSetter => {
+  TestBed.configureTestingModule({})
+  return TestBed.inject(NGX_META_ELEMENT_SETTER)
+}

projects/ngx-meta/src/core/src/meta-elements/v2/ngx-meta-element-setter.ts

@@ -0,0 +1,35 @@
+import { inject, InjectionToken } from '@angular/core'
+import { Meta } from '@angular/platform-browser'
+import { NgxMetaElementAttributes } from './ngx-meta-element-attributes'
+
+/**
+ * @alpha
+ */
+export const NGX_META_ELEMENT_SETTER = new InjectionToken<NgxMetaElementSetter>(
+  ngDevMode ? 'NgxMeta Meta elements setter' : 'NgxMetaMES',
+  {
+    factory: () => {
+      const meta = inject(Meta)
+      return (nameAttribute, content) => {
+        const [nameAttributeName, nameAttributeValue] = nameAttribute
+        const attrSelector = `${nameAttributeName}="${nameAttributeValue}"`
+        if (!content) {
+          meta.removeTag(attrSelector)
+          return
+        }
+        meta.updateTag(
+          { [nameAttributeName]: nameAttributeValue, ...content },
+          attrSelector,
+        )
+      }
+    },
+  },
+)
+
+/**
+ * @alpha
+ */
+export type NgxMetaElementSetter = (
+  nameAttribute: readonly [name: string, value: string],
+  content: NgxMetaElementAttributes | undefined,
+) => void