feat: custom extension rendering (#994)

* Custom extension value render

* Add parent to ExtensionComponentProps and move changes to Extensions component

* Address Sonar issue

* Apply suggestions from code review

Co-authored-by: Maciej Urbańczyk <[email protected]>

* Clean up Extension class

* Address eslint errors

* Fix handling of concatenatedConfig for extensions

* Add config modification docs

* Add test

* Add example for x-x extension

* Add viewBox to x logo

* Update package-lock.json

* Fix lint error

* Add x-x extensions example.

* Add x-x extensions example in info component

* Address review comments

* Address comments, use anchor tag and noopener, norefferer

* Remove unused code

---------

Co-authored-by: Duc Tai Ly <[email protected]>
Co-authored-by: asyncapi-bot <[email protected]>
Co-authored-by: Maciej Urbańczyk <[email protected]>
Co-authored-by: Lukasz Gornicki <[email protected]>
Co-authored-by: Pavel Kornev <[email protected]>
Co-authored-by: Cody's Dad <[email protected]>

Author: 7 people

docs/configuration/config-modification.md

@@ -36,6 +36,7 @@ interface ConfigInterface {
   receiveLabel?: string;
   requestLabel?: string;
   replyLabel?: string;
+  extensions?: Record<string, React.ComponentType<ExtensionComponentProps>>;
 }
 ```
 
@@ -100,6 +101,11 @@ interface ConfigInterface {
   This field contains configuration responsible for customizing the label for response operation. This takes effect when rendering AsyncAPI v3 documents.
   This field is set to `REPLY` by default.
 
+- **extensions?: Record<string, React.ComponentType<ExtensionComponentProps>>**
+
+  This field contains configuration responsible for adding custom extension components.
+  This field will contain default components.
+
 ## Examples
 
 See exemplary component configuration in TypeScript and JavaScript.
@@ -110,6 +116,7 @@ See exemplary component configuration in TypeScript and JavaScript.
 import * as React from "react";
 import { render } from "react-dom";
 import AsyncAPIComponent, { ConfigInterface } from "@asyncapi/react-component";
+import CustomExtension from "./CustomExtension";
 
 import { schema } from "./mock";
 
@@ -126,13 +133,28 @@ const config: ConfigInterface = {
   expand: {
     messageExamples: false,
   },
+  extensions: {
+    'x-custom-extension': CustomExtension
+  }
 };
 
 const App = () => <AsyncAPIComponent schema={schema} config={config} />;
 
 render(<App />, document.getElementById("root"));
 ```
 
+```tsx
+// CustomExtension.tsx
+import { ExtensionComponentProps } from '@asyncapi/react-component/lib/types/components/Extensions';
+
+export default function CustomExtension(props: ExtensionComponentProps<string>) {
+  return <div>
+    <h1>{props.propertyName}</h1>
+    <p>{props.propertyValue}</p>
+  </div>
+}
+```
+
 ### JavaScript
 
 ```jsx
@@ -162,6 +184,16 @@ const App = () => <AsyncAPIComponent schema={schema} config={config} />;
 render(<App />, document.getElementById("root"));
 ```
 
+```jsx
+// CustomExtension.jsx
+export default function CustomExtension(props) {
+  return <div>
+    <h1>{props.propertyName}</h1>
+    <p>{props.propertyValue}</p>
+  </div>
+}
+```
+
 In the above examples, after concatenation with the default configuration, the resulting configuration looks as follows:
 
 ```js
@@ -188,6 +220,10 @@ In the above examples, after concatenation with the default configuration, the r
   sendLabel: 'SEND',
   receiveLabel: 'RECEIVE',
   requestLabel: 'REQUEST',
-  replyLabel: 'REPLY'
+  replyLabel: 'REPLY', 
+  extensions: {
+    // default extensions...
+    'x-custom-extension': CustomExtension
+  }
 }
 ```

library/src/__tests__/index.test.tsx

@@ -6,7 +6,7 @@
 
 import React from 'react';
 import { render, waitFor } from '@testing-library/react';
-import AsyncApiComponent from '..';
+import AsyncApiComponent, { ExtensionComponentProps } from '..';
 import adoaKafka from './docs/v3/adeo-kafka-request-reply.json';
 import krakenMessageFilter from './docs/v3/kraken-websocket-request-reply-message-filter-in-reply.json';
 import krakenMultipleChannels from './docs/v3/kraken-websocket-request-reply-multiple-channels.json';
@@ -216,4 +216,54 @@ describe('AsyncAPI component', () => {
       expect(result.container.querySelector('#introduction')).toBeDefined(),
     );
   });
+
+  test('should work with custom extensions', async () => {
+    const schema = {
+      asyncapi: '2.0.0',
+      info: {
+        title: 'Example AsyncAPI',
+        version: '0.1.0',
+      },
+      channels: {
+        'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured':
+          {
+            subscribe: {
+              message: {
+                $ref: '#/components/messages/lightMeasured',
+              },
+            },
+          },
+      },
+      components: {
+        messages: {
+          lightMeasured: {
+            name: 'lightMeasured',
+            title: 'Light measured',
+            contentType: 'application/json',
+            'x-custom-extension': 'Custom extension value',
+          },
+        },
+      },
+    };
+
+    const CustomExtension = (props: ExtensionComponentProps) => (
+      <div id="custom-extension">{props.propertyValue}</div>
+    );
+
+    const result = render(
+      <AsyncApiComponent
+        schema={schema}
+        config={{
+          extensions: {
+            'x-custom-extension': CustomExtension,
+          },
+        }}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(result.container.querySelector('#introduction')).toBeDefined();
+      expect(result.container.querySelector('#custom-extension')).toBeDefined();
+    });
+  });
 });

library/src/components/Extensions.tsx

@@ -1,11 +1,13 @@
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 
-import React from 'react';
+import React, { useState } from 'react';
 
 import { Schema } from './Schema';
 
 import { SchemaHelpers } from '../helpers';
+import { useConfig, useSpec } from '../contexts';
+import { CollapseButton } from './CollapseButton';
 
 interface Props {
   name?: string;
@@ -17,18 +19,72 @@ export const Extensions: React.FunctionComponent<Props> = ({
   name = 'Extensions',
   item,
 }) => {
+  const [expanded, setExpanded] = useState(false);
+
+  const config = useConfig();
+  const document = useSpec();
+
   const extensions = SchemaHelpers.getCustomExtensions(item);
   if (!extensions || !Object.keys(extensions).length) {
     return null;
   }
 
-  const schema = SchemaHelpers.jsonToSchema(extensions);
+  if (!config.extensions || !Object.keys(config.extensions).length) {
+    const schema = SchemaHelpers.jsonToSchema(extensions);
+    return (
+      schema && (
+        <div className="mt-2">
+          <Schema schemaName={name} schema={schema} onlyTitle={true} />
+        </div>
+      )
+    );
+  }
 
   return (
-    schema && (
-      <div className="mt-2">
-        <Schema schemaName={name} schema={schema} onlyTitle />
+    <div>
+      <div className="flex py-2">
+        <div className="min-w-1/4">
+          <>
+            <CollapseButton
+              onClick={() => setExpanded((prev) => !prev)}
+              expanded={expanded}
+            >
+              <span className={`break-anywhere text-sm ${name}`}>{name}</span>
+            </CollapseButton>
+          </>
+        </div>
+      </div>
+      <div
+        className={`rounded p-4 py-2 border bg-gray-100 ${expanded ? 'block' : 'hidden'}`}
+      >
+        {Object.keys(extensions)
+          .sort((extension1, extension2) =>
+            extension1.localeCompare(extension2),
+          )
+          .map((extensionKey) => {
+            if (config.extensions?.[extensionKey]) {
+              const CustomExtensionComponent = config.extensions[extensionKey];
+              return (
+                <CustomExtensionComponent
+                  key={extensionKey}
+                  propertyName={extensionKey}
+                  propertyValue={extensions[extensionKey]}
+                  document={document}
+                  parent={item}
+                />
+              );
+            } else {
+              const extensionSchema = SchemaHelpers.jsonToSchema(
+                extensions[extensionKey],
+              );
+              return (
+                <div key={extensionKey} className="mt-2">
+                  <Schema schemaName={extensionKey} schema={extensionSchema} />
+                </div>
+              );
+            }
+          })}
       </div>
-    )
+    </div>
   );
 };

library/src/components/supportedExtensions/XExtension.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+
+import { ExtensionComponentProps } from '../../types';
+
+/**
+ * See <https://github.com/asyncapi/extensions-catalog/blob/master/extensions/x.md>.
+ */
+export default function XExtension({
+  propertyValue,
+}: ExtensionComponentProps<string>) {
+  return (
+    <a
+      title={`https://x.com/${propertyValue}`}
+      style={{ display: 'inline-block' }}
+      href={`https://x.com/${propertyValue}`}
+      rel="noopener noreferrer"
+      target="_blank"
+    >
+      <svg
+        // onClick={onClickHandler}
+        style={{ cursor: 'pointer' }}
+        width="15px"
+        height="15px"
+        viewBox="0 0 1200 1227"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M714.163 519.284L1160.89 0H1055.03L667.137 450.887L357.328 0H0L468.492 681.821L0 1226.37H105.866L515.491 750.218L842.672 1226.37H1200L714.137 519.284H714.163ZM569.165 687.828L521.697 619.934L144.011 79.6944H306.615L611.412 515.685L658.88 583.579L1055.08 1150.3H892.476L569.165 687.854V687.828Z"
+          fill="black"
+        />
+      </svg>
+    </a>
+  );
+}

library/src/config/config.ts

@@ -1,3 +1,5 @@
+import { ExtensionComponentProps } from '../types';
+
 export interface ConfigInterface {
   schemaID?: string;
   show?: ShowConfig;
@@ -11,6 +13,7 @@ export interface ConfigInterface {
   receiveLabel?: string;
   requestLabel?: string;
   replyLabel?: string;
+  extensions?: Record<string, React.ComponentType<ExtensionComponentProps>>;
 }
 
 export interface ShowConfig {

library/src/config/default.ts

@@ -7,6 +7,7 @@ import {
   SEND_LABEL_DEFAULT_TEXT,
   SUBSCRIBE_LABEL_DEFAULT_TEXT,
 } from '../constants';
+import XExtension from '../components/supportedExtensions/XExtension';
 
 export const defaultConfig: ConfigInterface = {
   schemaID: '',
@@ -33,4 +34,7 @@ export const defaultConfig: ConfigInterface = {
   receiveLabel: RECEIVE_TEXT_LABEL_DEFAULT_TEXT,
   requestLabel: REQUEST_LABEL_DEFAULT_TEXT,
   replyLabel: REPLIER_LABEL_DEFAULT_TEXT,
+  extensions: {
+    'x-x': XExtension,
+  },
 };

library/src/containers/AsyncApi/Standalone.tsx

@@ -69,6 +69,10 @@ class AsyncApiComponent extends Component<AsyncApiProps, AsyncAPIState> {
         ...defaultConfig.sidebar,
         ...(!!config && config.sidebar),
       },
+      extensions: {
+        ...defaultConfig.extensions,
+        ...(!!config && config.extensions),
+      },
     };
 
     if (!asyncapi) {

library/src/containers/Info/Info.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 
-import { Href, Markdown, Tags } from '../../components';
+import { Extensions, Href, Markdown, Tags } from '../../components';
 import { useSpec } from '../../contexts';
 import {
   TERMS_OF_SERVICE_TEXT,
@@ -23,6 +23,7 @@ export const Info: React.FunctionComponent = () => {
   const termsOfService = info.termsOfService();
   const defaultContentType = asyncapi.defaultContentType();
   const contact = info.contact();
+  const extensions = info.extensions();
 
   const showInfoList =
     license ?? termsOfService ?? defaultContentType ?? contact ?? externalDocs;
@@ -128,6 +129,12 @@ export const Info: React.FunctionComponent = () => {
             <Tags tags={asyncapi.info().tags()} />
           </div>
         )}
+
+        {extensions.length > 0 && (
+          <div className="mt-4">
+            <Extensions name="Info Extensions" item={info} />
+          </div>
+        )}
       </div>
 
       <div className="panel-item--right" />

library/src/index.ts

@@ -3,7 +3,7 @@ import AsyncApiComponentWP from './containers/AsyncApi/Standalone';
 
 export { AsyncApiProps } from './containers/AsyncApi/AsyncApi';
 export { ConfigInterface } from './config/config';
-export { FetchingSchemaInterface } from './types';
+export { FetchingSchemaInterface, ExtensionComponentProps } from './types';
 
 import { hljs } from './helpers';
 

library/src/types.ts

@@ -1,4 +1,4 @@
-import { AsyncAPIDocumentInterface } from '@asyncapi/parser';
+import { AsyncAPIDocumentInterface, BaseModel } from '@asyncapi/parser';
 
 export type PropsSchema =
   | string
@@ -77,3 +77,11 @@ export interface ErrorObject {
     endOffset: number;
   }[];
 }
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ExtensionComponentProps<V = any> {
+  propertyName: string;
+  propertyValue: V;
+  document: AsyncAPIDocumentInterface;
+  parent: BaseModel;
+}