From 43b8ff68fb4b81fd6b16187b16adaaa43acf1ac5 Mon Sep 17 00:00:00 2001
From: Jakub Jankowski <jakubj@stoplight.io>
Date: Fri, 15 Dec 2023 23:11:28 +0800
Subject: [PATCH] feat: callbacks (#2480)

* feat: callbacks

* fix: import

* chore: release
---
 demo/package.json                             |   2 +-
 packages/elements-core/package.json           |   2 +-
 .../src/__fixtures__/operations/put-todos.ts  | 103 +++++++++++++++++-
 .../components/Docs/HttpOperation/Body.tsx    |   4 +-
 .../Docs/HttpOperation/Callbacks.tsx          |  86 +++++++++++++++
 .../Docs/HttpOperation/HttpOperation.spec.tsx |  37 ++++++-
 .../Docs/HttpOperation/HttpOperation.tsx      |   9 +-
 .../components/Docs/HttpOperation/Request.tsx |   2 +-
 .../Docs/HttpOperation/Responses.tsx          |  10 +-
 packages/elements-dev-portal/package.json     |   4 +-
 packages/elements/package.json                |   4 +-
 11 files changed, 244 insertions(+), 19 deletions(-)
 create mode 100644 packages/elements-core/src/components/Docs/HttpOperation/Callbacks.tsx

diff --git a/demo/package.json b/demo/package.json
index 19d2ac384..eb6542992 100644
--- a/demo/package.json
+++ b/demo/package.json
@@ -10,7 +10,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@stoplight/elements": "^7.15.3",
+    "@stoplight/elements": "^7.16.0",
     "@stoplight/mosaic": "^1.46.1",
     "history": "^5.0.0",
     "react": "16.14.0",
diff --git a/packages/elements-core/package.json b/packages/elements-core/package.json
index 0061a1b50..cbe4e3186 100644
--- a/packages/elements-core/package.json
+++ b/packages/elements-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stoplight/elements-core",
-  "version": "7.15.2",
+  "version": "7.16.0",
   "sideEffects": [
     "web-components.min.js",
     "src/web-components/**",
diff --git a/packages/elements-core/src/__fixtures__/operations/put-todos.ts b/packages/elements-core/src/__fixtures__/operations/put-todos.ts
index c98335f06..4ea0cd7bc 100644
--- a/packages/elements-core/src/__fixtures__/operations/put-todos.ts
+++ b/packages/elements-core/src/__fixtures__/operations/put-todos.ts
@@ -1,4 +1,4 @@
-import { HttpParamStyles, IHttpOperation } from '@stoplight/types';
+import { HttpOperationSecurityDeclarationTypes, HttpParamStyles, IHttpOperation } from '@stoplight/types';
 
 export const httpOperation: IHttpOperation = {
   id: '?http-operation-id?',
@@ -522,6 +522,107 @@ export const httpOperation: IHttpOperation = {
       },
     ],
   },
+  callbacks: [
+    {
+      key: 'newPet',
+      extensions: {},
+      id: '3245690b6a7fc',
+      method: 'post',
+      path: '{$request.body#/newPetAvailableUrl}',
+      request: {
+        body: {
+          description: 'Callback body description',
+          contents: [
+            {
+              encodings: [],
+              examples: [],
+              id: 'abc',
+              mediaType: 'application/json',
+              schema: {
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                properties: {
+                  message: {
+                    examples: ['A new pet has arrived'],
+                    type: 'string',
+                  },
+                },
+                required: ['message'],
+                type: 'object',
+              },
+            },
+          ],
+          id: 'abc',
+          required: true,
+        },
+        cookie: [],
+        headers: [],
+        path: [],
+        query: [],
+      },
+      responses: [
+        {
+          code: '200',
+          contents: [],
+          description: 'Your server returns this code if it accepts the callback',
+          headers: [],
+          id: 'abc',
+        },
+      ],
+      security: [],
+      securityDeclarationType: HttpOperationSecurityDeclarationTypes.InheritedFromService,
+      servers: [],
+      tags: [],
+    },
+    {
+      key: 'returnedPet',
+      extensions: {},
+      id: '07041d5723f4a',
+      method: 'post',
+      path: '{$request.body#/returnedPetAvailableUrl}',
+      request: {
+        body: {
+          contents: [
+            {
+              encodings: [],
+              examples: [],
+              id: 'abc',
+              mediaType: 'application/json',
+              schema: {
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                properties: {
+                  message: {
+                    examples: ['A pet has been returned'],
+                    type: 'string',
+                  },
+                },
+                required: ['message'],
+                type: 'object',
+              },
+            },
+          ],
+          id: 'abc',
+          required: true,
+        },
+        cookie: [],
+        headers: [],
+        path: [],
+        query: [],
+      },
+      responses: [
+        {
+          code: '200',
+          contents: [],
+          description: 'Your server returns this code if it accepts the callback',
+          headers: [],
+          id: 'abc',
+        },
+      ],
+      security: [],
+      securityDeclarationType: HttpOperationSecurityDeclarationTypes.InheritedFromService,
+      servers: [],
+      tags: [],
+    },
+  ],
   tags: [
     {
       id: '?http-tags-todos?',
diff --git a/packages/elements-core/src/components/Docs/HttpOperation/Body.tsx b/packages/elements-core/src/components/Docs/HttpOperation/Body.tsx
index 34ec4c41f..89f12cd46 100644
--- a/packages/elements-core/src/components/Docs/HttpOperation/Body.tsx
+++ b/packages/elements-core/src/components/Docs/HttpOperation/Body.tsx
@@ -12,7 +12,7 @@ import { SectionSubtitle } from '../Sections';
 
 export interface BodyProps {
   body: IHttpOperationRequestBody;
-  onChange: (requestBodyIndex: number) => void;
+  onChange?: (requestBodyIndex: number) => void;
 }
 
 export const isBodyEmpty = (body?: BodyProps['body']) => {
@@ -29,7 +29,7 @@ export const Body = ({ body, onChange }: BodyProps) => {
   const { nodeHasChanged } = useOptionsCtx();
 
   React.useEffect(() => {
-    onChange(chosenContent);
+    onChange?.(chosenContent);
     // disabling because we don't want to react on `onChange` change
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [chosenContent]);
diff --git a/packages/elements-core/src/components/Docs/HttpOperation/Callbacks.tsx b/packages/elements-core/src/components/Docs/HttpOperation/Callbacks.tsx
new file mode 100644
index 000000000..06fc20ef3
--- /dev/null
+++ b/packages/elements-core/src/components/Docs/HttpOperation/Callbacks.tsx
@@ -0,0 +1,86 @@
+import { Box, Flex, NodeAnnotation, Select, VStack } from '@stoplight/mosaic';
+import { IHttpCallbackOperation } from '@stoplight/types';
+import * as React from 'react';
+
+import { useOptionsCtx } from '../../../context/Options';
+import { MarkdownViewer } from '../../MarkdownViewer';
+import { SectionSubtitle, SectionTitle } from '../Sections';
+import { OperationHeader } from './HttpOperation';
+import { Request } from './Request';
+import { Responses } from './Responses';
+
+export interface CallbacksProps {
+  callbacks: IHttpCallbackOperation[];
+  isCompact?: boolean;
+}
+
+export interface CallbackProps {
+  data: IHttpCallbackOperation;
+  isCompact?: boolean;
+}
+
+export const Callbacks = ({ callbacks, isCompact }: CallbacksProps) => {
+  const [selectedCallbackIndex, setSelectedCallbackIndex] = React.useState(0);
+
+  const callback = React.useMemo(() => callbacks[selectedCallbackIndex], [callbacks, selectedCallbackIndex]);
+
+  return (
+    <VStack spacing={8}>
+      <SectionTitle title="Callbacks" isCompact={isCompact}>
+        {callbacks.length > 0 && (
+          <Flex flex={1} justify="end">
+            <Select
+              aria-label="Callback"
+              value={String(selectedCallbackIndex)}
+              onChange={value => setSelectedCallbackIndex(parseInt(String(value), 10))}
+              options={callbacks.map((c, index) => ({
+                label: `${c.key} - ${c.path} - ${c.method}`,
+                value: index,
+              }))}
+              size="sm"
+            />
+          </Flex>
+        )}
+      </SectionTitle>
+
+      {callback && <Callback data={callback} isCompact={isCompact} />}
+    </VStack>
+  );
+};
+
+Callbacks.displayName = 'HttpOperation.Callbacks';
+
+export const Callback = ({ data, isCompact }: CallbackProps) => {
+  const { nodeHasChanged } = useOptionsCtx();
+
+  const isDeprecated = !!data.deprecated;
+  const isInternal = !!data.internal;
+
+  const descriptionChanged = nodeHasChanged?.({ nodeId: data.id, attr: 'description' });
+
+  return (
+    <VStack spacing={10}>
+      <Box>
+        <SectionSubtitle title={data.key} id="callback-key"></SectionSubtitle>
+        <OperationHeader
+          id={data.id}
+          method={data.method}
+          path={`/${data.path}`}
+          isDeprecated={isDeprecated}
+          isInternal={isInternal}
+        />
+      </Box>
+      {data.description && (
+        <Box pos="relative">
+          <MarkdownViewer className="HttpOperation__Description" markdown={data.description} />
+          <NodeAnnotation change={descriptionChanged} />
+        </Box>
+      )}
+
+      <Request operation={data} />
+
+      {data.responses && <Responses responses={data.responses} isCompact={isCompact} />}
+    </VStack>
+  );
+};
+Callbacks.displayName = 'HttpOperation.Callback';
diff --git a/packages/elements-core/src/components/Docs/HttpOperation/HttpOperation.spec.tsx b/packages/elements-core/src/components/Docs/HttpOperation/HttpOperation.spec.tsx
index 4846f4ac4..dfbbfff1d 100644
--- a/packages/elements-core/src/components/Docs/HttpOperation/HttpOperation.spec.tsx
+++ b/packages/elements-core/src/components/Docs/HttpOperation/HttpOperation.spec.tsx
@@ -70,7 +70,7 @@ describe('HttpOperation', () => {
 
       expect(serversButton).toHaveTextContent('PR');
 
-      expect(screen.queryByText(/{proto}:\/\/x-{pr}.todos-pr.stoplight.io:{port}/)).toBeInTheDocument();
+      expect(screen.queryAllByText(/{proto}:\/\/x-{pr}.todos-pr.stoplight.io:{port}/)[0]).toBeInTheDocument();
       unmount();
     });
   });
@@ -617,6 +617,41 @@ describe('HttpOperation', () => {
     });
   });
 
+  describe('Callbacks', () => {
+    it('should display callback operation', async () => {
+      const { unmount } = render(<HttpOperation data={{ ...httpOperation, deprecated: false }} />);
+
+      //operation name
+      expect(screen.queryByText('newPet')).toBeInTheDocument();
+
+      // operation header
+      expect(screen.queryByText('/{$request.body#/newPetAvailableUrl}')).toBeInTheDocument();
+
+      // operation body
+      expect(screen.queryByText('Callback body description')).toBeInTheDocument();
+
+      // operation response
+      expect(screen.queryByText('Your server returns this code if it accepts the callback')).toBeInTheDocument();
+
+      unmount();
+    });
+    it('should display callback selector and switch between events', () => {
+      const { unmount } = render(<HttpOperation data={{ ...httpOperation, deprecated: false }} />);
+
+      const select = screen.getByLabelText('Callback');
+
+      expect(select).toHaveTextContent('newPet - {$request.body#/newPetAvailableUrl} - post');
+
+      chooseOption(select, 'returnedPet - {$request.body#/returnedPetAvailableUrl} - post');
+
+      expect(select).toHaveTextContent('returnedPet - {$request.body#/returnedPetAvailableUrl} - post');
+
+      expect(screen.queryByText('returnedPet')).toBeInTheDocument();
+
+      unmount();
+    });
+  });
+
   describe('Visibility', () => {
     it('should hide TryIt', async () => {
       const { unmount } = render(<HttpOperation data={httpOperation} layoutOptions={{ hideTryIt: true }} />);
diff --git a/packages/elements-core/src/components/Docs/HttpOperation/HttpOperation.tsx b/packages/elements-core/src/components/Docs/HttpOperation/HttpOperation.tsx
index 54ffe3b24..fec612937 100644
--- a/packages/elements-core/src/components/Docs/HttpOperation/HttpOperation.tsx
+++ b/packages/elements-core/src/components/Docs/HttpOperation/HttpOperation.tsx
@@ -15,6 +15,7 @@ import { chosenServerAtom, TryItWithRequestSamples } from '../../TryIt';
 import { DocsComponentProps } from '..';
 import { TwoColumnLayout } from '../TwoColumnLayout';
 import { DeprecatedBadge, InternalBadge } from './Badges';
+import { Callbacks } from './Callbacks';
 import { Request } from './Request';
 import { Responses } from './Responses';
 
@@ -84,6 +85,8 @@ const HttpOperationComponent = React.memo<HttpOperationProps>(
           />
         )}
 
+        {data.callbacks?.length && <Callbacks callbacks={data.callbacks} isCompact={isCompact} />}
+
         {isCompact && tryItPanel}
       </VStack>
     );
@@ -170,7 +173,7 @@ function MethodPathInner({ method, path, chosenServerUrl }: MethodPathProps & {
   );
 }
 
-function OperationHeader({
+export function OperationHeader({
   id,
   noHeading,
   hasBadges,
@@ -182,8 +185,8 @@ function OperationHeader({
 }: {
   id: string;
   noHeading?: boolean;
-  hasBadges: boolean;
-  name: string;
+  hasBadges?: boolean;
+  name?: string;
   isDeprecated?: boolean;
   isInternal?: boolean;
   method: string;
diff --git a/packages/elements-core/src/components/Docs/HttpOperation/Request.tsx b/packages/elements-core/src/components/Docs/HttpOperation/Request.tsx
index 1de974958..6e12c58d1 100644
--- a/packages/elements-core/src/components/Docs/HttpOperation/Request.tsx
+++ b/packages/elements-core/src/components/Docs/HttpOperation/Request.tsx
@@ -15,7 +15,7 @@ import { Parameters } from './Parameters';
 
 interface IRequestProps {
   operation: IHttpOperation;
-  onChange: (requestBodyIndex: number) => void;
+  onChange?: (requestBodyIndex: number) => void;
 }
 
 export const Request: React.FunctionComponent<IRequestProps> = ({
diff --git a/packages/elements-core/src/components/Docs/HttpOperation/Responses.tsx b/packages/elements-core/src/components/Docs/HttpOperation/Responses.tsx
index 87fe6b29a..0ab3906c2 100644
--- a/packages/elements-core/src/components/Docs/HttpOperation/Responses.tsx
+++ b/packages/elements-core/src/components/Docs/HttpOperation/Responses.tsx
@@ -33,13 +33,13 @@ import { Parameters } from './Parameters';
 
 interface ResponseProps {
   response: IHttpOperationResponse;
-  onMediaTypeChange(mediaType: string): void;
+  onMediaTypeChange?: (mediaType: string) => void;
 }
 
 interface ResponsesProps {
   responses: IHttpOperationResponse[];
-  onMediaTypeChange(mediaType: string): void;
-  onStatusCodeChange(statusCode: string): void;
+  onMediaTypeChange?: (mediaType: string) => void;
+  onStatusCodeChange?: (statusCode: string) => void;
   isCompact?: boolean;
 }
 
@@ -70,7 +70,7 @@ export const Responses = ({
   );
 
   React.useEffect(() => {
-    onStatusCodeChange(activeResponseId);
+    onStatusCodeChange?.(activeResponseId);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [activeResponseId]);
 
@@ -172,7 +172,7 @@ const Response = ({ response, onMediaTypeChange }: ResponseProps) => {
   const schema = responseContent?.schema;
 
   React.useEffect(() => {
-    responseContent && onMediaTypeChange(responseContent.mediaType);
+    responseContent && onMediaTypeChange?.(responseContent.mediaType);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [responseContent]);
 
diff --git a/packages/elements-dev-portal/package.json b/packages/elements-dev-portal/package.json
index c74cdd9bc..5e3350739 100644
--- a/packages/elements-dev-portal/package.json
+++ b/packages/elements-dev-portal/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stoplight/elements-dev-portal",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "UI components for composing beautiful developer documentation.",
   "keywords": [],
   "sideEffects": [
@@ -64,7 +64,7 @@
     ]
   },
   "dependencies": {
-    "@stoplight/elements-core": "~7.15.1",
+    "@stoplight/elements-core": "~7.16.0",
     "@stoplight/markdown-viewer": "^5.5.0",
     "@stoplight/mosaic": "^1.46.1",
     "@stoplight/path": "^1.3.2",
diff --git a/packages/elements/package.json b/packages/elements/package.json
index 58cb248f3..04fe7540c 100644
--- a/packages/elements/package.json
+++ b/packages/elements/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stoplight/elements",
-  "version": "7.15.4",
+  "version": "7.16.0",
   "description": "UI components for composing beautiful developer documentation.",
   "keywords": [],
   "sideEffects": [
@@ -62,7 +62,7 @@
     ]
   },
   "dependencies": {
-    "@stoplight/elements-core": "~7.15.2",
+    "@stoplight/elements-core": "~7.16.0",
     "@stoplight/http-spec": "^6.0.0",
     "@stoplight/json": "^3.18.1",
     "@stoplight/mosaic": "^1.46.1",