Skip to content

Commit fea0023

Browse files
phryneasphryneas
committed
Copy and use ApiDoc components from docs repo (#11416)
1 parent f5420b0 commit fea0023

13 files changed

+676
-19
lines changed

‎.prettierignore

+5
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,11 @@
2525
/docs/source/development-testing/**
2626
!/docs/source/development-testing/reducing-bundle-size.mdx
2727

28+
!docs/shared
29+
/docs/shared/**
30+
!/docs/shared/ApiDoc
31+
!/docs/shared/ApiDoc/**
32+
2833
node_modules/
2934
.yalc/
3035
.next/

‎docs/shared/ApiDoc/Context.js

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
import { useMDXComponents } from "@mdx-js/react";
2+
3+
export const useApiDocContext = function () {
4+
const MDX = useMDXComponents();
5+
return MDX.useApiDocContext(this, arguments);
6+
};

‎docs/shared/ApiDoc/DocBlock.js

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
import PropTypes from "prop-types";
2+
import React from "react";
3+
import { Stack } from "@chakra-ui/react";
4+
import { mdToReact } from "./mdToReact";
5+
import { useApiDocContext } from ".";
6+
7+
export function DocBlock({
8+
canonicalReference,
9+
summary = true,
10+
remarks = false,
11+
example = false,
12+
remarkCollapsible = true,
13+
since = true,
14+
deprecated = true,
15+
}) {
16+
return (
17+
<Stack spacing="4">
18+
{/** TODO: @since, @deprecated etc. */}
19+
{deprecated && <Deprecated canonicalReference={canonicalReference} />}
20+
{since && <Since canonicalReference={canonicalReference} />}
21+
{summary && <Summary canonicalReference={canonicalReference} />}
22+
{remarks && (
23+
<Remarks
24+
collapsible={remarkCollapsible}
25+
canonicalReference={canonicalReference}
26+
/>
27+
)}
28+
{example && <Example canonicalReference={canonicalReference} />}
29+
</Stack>
30+
);
31+
}
32+
33+
DocBlock.propTypes = {
34+
canonicalReference: PropTypes.string.isRequired,
35+
summary: PropTypes.bool,
36+
remarks: PropTypes.bool,
37+
example: PropTypes.bool,
38+
remarkCollapsible: PropTypes.bool,
39+
since: PropTypes.bool,
40+
deprecated: PropTypes.bool,
41+
};
42+
43+
function MaybeCollapsible({ collapsible, children }) {
44+
return (
45+
collapsible ?
46+
children ?
47+
<details>
48+
<summary>Read more...</summary>
49+
{children}
50+
</details>
51+
: null
52+
: children
53+
);
54+
}
55+
MaybeCollapsible.propTypes = {
56+
collapsible: PropTypes.bool,
57+
children: PropTypes.node,
58+
};
59+
60+
/**
61+
* Might still need more work on the Gatsby side to get this to work.
62+
*/
63+
export function Deprecated({ canonicalReference, collapsible = false }) {
64+
const getItem = useApiDocContext();
65+
const item = getItem(canonicalReference);
66+
const value = item.comment?.deprecated;
67+
if (!value) return null;
68+
return (
69+
<MaybeCollapsible collapsible={collapsible}>
70+
<b>{mdToReact(value)}</b>
71+
</MaybeCollapsible>
72+
);
73+
}
74+
Deprecated.propTypes = {
75+
canonicalReference: PropTypes.string.isRequired,
76+
collapsible: PropTypes.bool,
77+
};
78+
79+
/**
80+
* Might still need more work on the Gatsby side to get this to work.
81+
*/
82+
export function Since({ canonicalReference, collapsible = false }) {
83+
const getItem = useApiDocContext();
84+
const item = getItem(canonicalReference);
85+
const value = item.comment?.since;
86+
if (!value) return null;
87+
return (
88+
<MaybeCollapsible collapsible={collapsible}>
89+
<i>Added to Apollo Client in version {value}</i>
90+
</MaybeCollapsible>
91+
);
92+
}
93+
Since.propTypes = {
94+
canonicalReference: PropTypes.string.isRequired,
95+
collapsible: PropTypes.bool,
96+
};
97+
98+
export function Summary({ canonicalReference, collapsible = false }) {
99+
const getItem = useApiDocContext();
100+
const item = getItem(canonicalReference);
101+
const value = item.comment?.summary;
102+
if (!value) return null;
103+
return (
104+
<MaybeCollapsible collapsible={collapsible}>
105+
{mdToReact(value)}
106+
</MaybeCollapsible>
107+
);
108+
}
109+
Summary.propTypes = {
110+
canonicalReference: PropTypes.string.isRequired,
111+
collapsible: PropTypes.bool,
112+
};
113+
114+
export function Remarks({ canonicalReference, collapsible = false }) {
115+
const getItem = useApiDocContext();
116+
const item = getItem(canonicalReference);
117+
const value = item.comment?.remarks?.replace(/^@remarks/g, "");
118+
if (!value) return null;
119+
return (
120+
<MaybeCollapsible collapsible={collapsible}>
121+
{mdToReact(value)}
122+
</MaybeCollapsible>
123+
);
124+
}
125+
Remarks.propTypes = {
126+
canonicalReference: PropTypes.string.isRequired,
127+
collapsible: PropTypes.bool,
128+
};
129+
130+
export function Example({
131+
canonicalReference,
132+
collapsible = false,
133+
index = 0,
134+
}) {
135+
const getItem = useApiDocContext();
136+
const item = getItem(canonicalReference);
137+
const value = item.comment?.examples[index];
138+
if (!value) return null;
139+
return (
140+
<MaybeCollapsible collapsible={collapsible}>
141+
<b>{mdToReact(value)}</b>
142+
</MaybeCollapsible>
143+
);
144+
}
145+
Example.propTypes = {
146+
canonicalReference: PropTypes.string.isRequired,
147+
collapsible: PropTypes.bool,
148+
index: PropTypes.number,
149+
};

‎docs/shared/ApiDoc/Function.js

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
import PropTypes from "prop-types";
2+
import React from "react";
3+
import { ApiDocHeading, DocBlock, ParameterTable, useApiDocContext } from ".";
4+
5+
export function FunctionSignature({
6+
canonicalReference,
7+
parameterTypes = false,
8+
name = true,
9+
arrow = false,
10+
}) {
11+
const getItem = useApiDocContext();
12+
const { displayName, parameters, returnType } = getItem(canonicalReference);
13+
14+
return (
15+
<>
16+
{name ? displayName : ""}(
17+
{parameters
18+
.map((p) => {
19+
let pStr = p.name;
20+
if (p.optional) {
21+
pStr += "?";
22+
}
23+
if (parameterTypes) {
24+
pStr += ": " + p.type;
25+
}
26+
return pStr;
27+
})
28+
.join(", ")}
29+
){arrow ? " =>" : ":"} {returnType}
30+
</>
31+
);
32+
}
33+
34+
FunctionSignature.propTypes = {
35+
canonicalReference: PropTypes.string.isRequired,
36+
parameterTypes: PropTypes.bool,
37+
name: PropTypes.bool,
38+
arrow: PropTypes.bool,
39+
};
40+
41+
export function FunctionDetails({
42+
canonicalReference,
43+
customParameterOrder,
44+
headingLevel,
45+
}) {
46+
return (
47+
<>
48+
<ApiDocHeading
49+
canonicalReference={canonicalReference}
50+
headingLevel={headingLevel}
51+
/>
52+
<DocBlock
53+
canonicalReference={canonicalReference}
54+
remark
55+
remarkCollapsible
56+
example
57+
/>
58+
<ParameterTable
59+
canonicalReference={canonicalReference}
60+
customOrder={customParameterOrder}
61+
/>
62+
</>
63+
);
64+
}
65+
66+
FunctionDetails.propTypes = {
67+
canonicalReference: PropTypes.string.isRequired,
68+
headingLevel: PropTypes.number.isRequired,
69+
customParameterOrder: PropTypes.arrayOf(PropTypes.string),
70+
};

‎docs/shared/ApiDoc/Heading.js

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
import { useMDXComponents } from "@mdx-js/react";
2+
import PropTypes from "prop-types";
3+
import React from "react";
4+
import { Box, Heading } from "@chakra-ui/react";
5+
import { FunctionSignature } from ".";
6+
import { useApiDocContext } from "./Context";
7+
8+
const levels = {
9+
2: "xl",
10+
3: "lg",
11+
4: "md",
12+
5: "sm",
13+
6: "xs",
14+
};
15+
16+
export function ApiDocHeading({
17+
canonicalReference,
18+
headingLevel,
19+
link = true,
20+
}) {
21+
const MDX = useMDXComponents();
22+
const getItem = useApiDocContext();
23+
const item = getItem(canonicalReference);
24+
const heading =
25+
(
26+
item.kind === "MethodSignature" ||
27+
item.kind === "Function" ||
28+
item.kind === "Method"
29+
) ?
30+
<FunctionSignature
31+
canonicalReference={canonicalReference}
32+
parameterTypes={false}
33+
/>
34+
: item.displayName;
35+
return (
36+
<Box pt="4">
37+
<Heading
38+
as={`h${headingLevel}`}
39+
size={levels[String(headingLevel)]}
40+
fontFamily="mono"
41+
title={item.displayName}
42+
id={item.displayName}
43+
>
44+
{link ?
45+
<MDX.PrimaryLink href={`#${item.displayName}`}>
46+
{heading}
47+
</MDX.PrimaryLink>
48+
: heading}
49+
</Heading>
50+
{item.file && (
51+
<Heading as="h6" fontWeight="normal" size="sm" mt="2">
52+
<MDX.PrimaryLink
53+
href={`https://github.com/apollographql/apollo-client/blob/main/${item.file}`}
54+
isExternal
55+
>
56+
({item.file})
57+
</MDX.PrimaryLink>
58+
</Heading>
59+
)}
60+
</Box>
61+
);
62+
}
63+
ApiDocHeading.propTypes = {
64+
canonicalReference: PropTypes.string.isRequired,
65+
headingLevel: PropTypes.number.isRequired,
66+
link: PropTypes.bool,
67+
};

‎docs/shared/ApiDoc/InterfaceDetails.js

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import PropTypes from "prop-types";
2+
import React from "react";
3+
import { ApiDocHeading, DocBlock, PropertySignatureTable } from ".";
4+
export function InterfaceDetails({
5+
canonicalReference,
6+
headingLevel,
7+
link,
8+
customPropertyOrder,
9+
}) {
10+
return (
11+
<>
12+
<ApiDocHeading
13+
canonicalReference={canonicalReference}
14+
headingLevel={headingLevel}
15+
link={link}
16+
/>
17+
<DocBlock
18+
canonicalReference={canonicalReference}
19+
heading
20+
headingLevel={3}
21+
/>
22+
<PropertySignatureTable
23+
canonicalReference={canonicalReference}
24+
methods
25+
properties
26+
customOrder={customPropertyOrder}
27+
/>
28+
</>
29+
);
30+
}
31+
32+
InterfaceDetails.propTypes = {
33+
canonicalReference: PropTypes.string.isRequired,
34+
headingLevel: PropTypes.number.isRequired,
35+
link: PropTypes.bool,
36+
customPropertyOrder: PropTypes.arrayOf(PropTypes.string),
37+
};

0 commit comments

Comments
 (0)