You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+27-11Lines changed: 27 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,9 +10,12 @@ To get started with mdx-embed we suggest you clone the repo then do the followin
10
10
11
11
## Change an existing component
12
12
13
-
Feel free to make changes wherever you see bit but please be mindful that removing or changing prop names will count as a breaking change and we'll only do this if it's absolutely necessary.
13
+
Feel free to make changes wherever you see bit but please be mindful that removing or changing prop names will count as
14
+
a breaking change and we'll only do this if it's absolutely necessary.
14
15
15
-
Check the existing props still work by checking against the story in the components `.stories.mdx` file. Each prop usually means the component will behave in a different way so please check the component still does what it's supposed to do when you're altering prop _values_ or code.
16
+
Check the existing props still work by checking against the story in the components `.stories.mdx` file. Each prop
17
+
usually means the component will behave in a different way so please check the component still does what it's supposed
18
+
to do when you're altering prop _values_ or code.
16
19
17
20
## To add a new component
18
21
@@ -22,31 +25,43 @@ To add a new component there are several locations the new component needs to go
22
25
- All components are `FunctionComponents` and named using the [PascalCase](https://wiki.c2.com/?PascalCase) convention
23
26
- Add an `index.ts` file to the same dir and export the component: `export { ComponentName } from './component-name';`
24
27
- Add export to `mdx-embed/src/index.ts`: `export { ComponentName } from './components/component-name`
25
-
- Include component in the `components` object that gets passed onto the MDXProvider in `src/components/mdx-embed-provider/mdx-embed-provider.tsx`
28
+
- Include component in the `components` object that gets passed onto the MDXProvider in
- Add component to stories `docs/src/components/component-name.stories.mdx`
27
31
28
32
## Final checks
29
33
30
-
It's important for our users to understand how the component works so we always try to give any props the component has a brief description of what it does _and_ create a `<Story />` for each prop visually showing the usage.
34
+
It's important for our users to understand how the component works so we always try to give any props the component has
35
+
a brief description of what it does _and_ create a `<Story />` for each prop visually showing the usage.
31
36
32
37
## Create PR
33
38
34
-
Once you're happy with your new component create a PR that merges in to the `main` branch and one of the team will happily review your code.
39
+
Once you're happy with your new component create a PR that merges in to the `main` branch and one of the team will
40
+
happily review your code.
35
41
36
-
The team are on hand should you require any assistance of have any questions at all so please feel free to reach out on Twitter
42
+
The team are on hand should you require any assistance of have any questions at all so please feel free to reach out on
43
+
Twitter
37
44
38
45
- Paul Scanlon | [@pauliescanlon](https://twitter.com/PaulieScanlon)
39
46
- Scott Spence | [@spences10](https://twitter.com/spences10)
Each component will at some point require at least one test to check it renders correctly.
45
-
Each component in `mdx-embed/src/components/` is wrapped in what we call the **GeneralObserver** This component is responsible for ensuring the 3rd part embed script isn't invoked until the component has entered the viewport. This is particularly important for Lighthouse scores and page load speeds. If a blog post page for example has 10 or 15 embed codes, Twitter, CodePend, YouTube etc on the page we don't want to load all that 3rd party JavaScript until the reader has scrolled down to where the component is used. When it scrolls in to view **GeneralObserver** which is an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) triggers a React state change which causes the children to be rendered in the DOM
51
+
Each component will at some point require at least one test to check it renders correctly. Each component in
52
+
`mdx-embed/src/components/` is wrapped in what we call the **GeneralObserver** This component is responsible for
53
+
ensuring the 3rd part embed script isn't invoked until the component has entered the viewport. This is particularly
54
+
important for Lighthouse scores and page load speeds. If a blog post page for example has 10 or 15 embed codes, Twitter,
55
+
CodePend, YouTube etc on the page we don't want to load all that 3rd party JavaScript until the reader has scrolled down
56
+
to where the component is used. When it scrolls in to view **GeneralObserver** which is an
57
+
[Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) triggers a React
58
+
state change which causes the children to be rendered in the DOM
46
59
47
-
This presents an issue when we come to test the components because we need to fake the "scrolled in to view" action which allows the children of **GeneralObserver** to render.
60
+
This presents an issue when we come to test the components because we need to fake the "scrolled in to view" action
61
+
which allows the children of **GeneralObserver** to render.
48
62
49
-
To _mock_ this is a test we've globally exposed a method called `triggerGeneralObserver()` and since we're using Testing Library this state change must be wrapped in an `act`.
63
+
To _mock_ this is a test we've globally exposed a method called `triggerGeneralObserver()` and since we're using Testing
64
+
Library this state change must be wrapped in an `act`.
50
65
51
66
With that said we require each `test(() => {})` to contain an `act()` and a call to `triggerGeneralObserver()`
52
67
@@ -67,7 +82,8 @@ describe('<CodePen />', () => {
67
82
});
68
83
```
69
84
70
-
The other important part of the test is the use of `getByTestId` this is a special data attribute we use from Testing Library called `data-testid` and will need to be added to components with _new_ tests.
85
+
The other important part of the test is the use of `getByTestId` this is a special data attribute we use from Testing
86
+
Library called `data-testid` and will need to be added to components with _new_ tests.
71
87
72
88
In the `CodePen` example that looks a bit like this:
0 commit comments