feat: Backers + Contributors mdx components (#339)

* feat: Backer, Contributors mdx components

* fix: Handle empty backers and contributors lists in mdx components

* CONTRIBUTORS_PAT + authoring doc

* pmndrs/docs contrib

---------

Co-authored-by: Antoine BERNIER <antoine.bernier@gmail.com>

.github/workflows/build.yml

@@ -92,6 +92,7 @@ jobs:
             -e THEME_IMPORTANT \
             -e THEME_WARNING \
             -e THEME_CAUTION \
+            -e CONTRIBUTORS_PAT \
             ghcr.io/pmndrs/docs:2 npm run build
         env:
           BASE_PATH: ${{ steps.set-base-path.outputs.BASE_PATH }}
@@ -115,6 +116,7 @@ jobs:
           THEME_IMPORTANT: '${{ inputs.theme_important }}'
           THEME_WARNING: '${{ inputs.theme_warning }}'
           THEME_CAUTION: '${{ inputs.theme_caution }}'
+          CONTRIBUTORS_PAT: ${{ secrets.GITHUB_TOKEN }}
 
       - uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/release.yml

@@ -70,6 +70,7 @@ jobs:
             --build-env THEME_IMPORTANT="#8957e5" \
             --build-env THEME_WARNING="#d29922" \
             --build-env THEME_CAUTION="#da3633" \
+            --build-env CONTRIBUTORS_PAT="${{ secrets.GITHUB_TOKEN }}" \
             > deployment-url.txt
 
           echo "deployment_url=$(cat deployment-url.txt)" >> $GITHUB_OUTPUT

docs/getting-started/authoring.mdx

@@ -414,3 +414,32 @@ or better:
 <Hint>I'm a deprecated hint. Use `Gha` instead.</Hint>
 
 </details>
+
+### `Contributors`
+
+```md
+<Contributors owner="pmndrs" repo="docs" />
+```
+
+> [!WARNING]
+> [`CONTRIBUTORS_PAT`](introduction#configuration:~:text=CONTRIBUTORS_PAT) needs to be set. Otherwise, it will display John Doe.
+
+<details>
+  <summary>Result</summary>
+
+<Contributors owner="pmndrs" repo="docs" />
+
+</details>
+
+### Backers
+
+```md
+<Backers repo="react-three-fiber" />
+```
+
+<details>
+  <summary>Result</summary>
+
+<Backers repo="react-three-fiber" />
+
+</details>

docs/getting-started/introduction.mdx

@@ -47,6 +47,7 @@ $ npm ci
 | `THEME_IMPORTANT`           | "important" color                                                                                                                                                        | `#8957e5`                                                                                        |
 | `THEME_WARNING`             | "warning" color                                                                                                                                                          | `#d29922`                                                                                        |
 | `THEME_CAUTION`             | "caution" color                                                                                                                                                          | `#da3633`                                                                                        |
+| `CONTRIBUTORS_PAT`          | GitHub token for contributors API (see: https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators)                 | `ghp_1234567890`                                                                                 |
 
 \* Required
 
@@ -116,6 +117,7 @@ $ (
   export THEME_IMPORTANT="#8957e5"
   export THEME_WARNING="#d29922"
   export THEME_CAUTION="#da3633"
+  export CONTRIBUTORS_PAT=
 
   kill $(lsof -ti:"$_PORT")
   npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &
@@ -163,6 +165,7 @@ $ (
   export THEME_IMPORTANT="#8957e5"
   export THEME_WARNING="#d29922"
   export THEME_CAUTION="#da3633"
+  export CONTRIBUTORS_PAT=
 
   npm run build
 
@@ -211,6 +214,7 @@ $ (
   export THEME_IMPORTANT="#8957e5"
   export THEME_WARNING="#d29922"
   export THEME_CAUTION="#da3633"
+  export CONTRIBUTORS_PAT=
 
   rm -rf "$MDX/out"
 
@@ -238,6 +242,7 @@ $ (
     -e THEME_IMPORTANT \
     -e THEME_WARNING \
     -e THEME_CAUTION \
+    -e CONTRIBUTORS_PAT \
     pmndrs-docs npm run build
 
   kill $(lsof -ti:"$_PORT")

package.json

@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "@codesandbox/sandpack-react": "^2.19.8",
+    "@octokit/core": "^6.1.2",
     "@radix-ui/react-collapsible": "^1.1.0",
     "@radix-ui/react-dialog": "^1.1.1",
     "@radix-ui/react-visually-hidden": "^1.1.0",

src/components/mdx/People/People.tsx

@@ -0,0 +1,151 @@
+import cn from '@/lib/cn'
+import { initials } from '@/utils/text'
+import { Octokit } from '@octokit/core'
+import Image from 'next/image'
+import { cache, ComponentProps } from 'react'
+import backerBadge from './backer-badge.svg'
+
+//  ██████  ██████  ███    ██ ████████ ██████  ██ ██████  ██    ██ ████████  ██████  ██████  ███████
+// ██      ██    ██ ████   ██    ██    ██   ██ ██ ██   ██ ██    ██    ██    ██    ██ ██   ██ ██
+// ██      ██    ██ ██ ██  ██    ██    ██████  ██ ██████  ██    ██    ██    ██    ██ ██████  ███████
+// ██      ██    ██ ██  ██ ██    ██    ██   ██ ██ ██   ██ ██    ██    ██    ██    ██ ██   ██      ██
+//  ██████  ██████  ██   ████    ██    ██   ██ ██ ██████   ██████     ██     ██████  ██   ██ ███████
+
+const octokit = new Octokit({
+  auth: process.env.CONTRIBUTORS_PAT,
+})
+
+export async function Contributors({
+  owner,
+  repo,
+  limit = 50,
+  className,
+  ...props
+}: { owner: string; repo: string; limit: number } & ComponentProps<'ul'>) {
+  const contributors = (
+    await cachedFetchContributors(owner, repo).catch(
+      (err) =>
+        Array.from({ length: 100 }).map(() => ({
+          login: 'jdoe',
+          html_url: 'https://github.com/jdoe',
+        })) as Awaited<ReturnType<typeof cachedFetchContributors>>,
+    )
+  ).slice(0, limit)
+
+  return (
+    <div>
+      <ul className={cn('flex flex-wrap gap-1', className)} {...props}>
+        {contributors.map(({ html_url, avatar_url, login }) => (
+          <li key={login}>
+            <Avatar profileUrl={html_url} imageUrl={avatar_url} name={login} />
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+async function fetchContributors(owner: string, repo: string) {
+  const res = await octokit.request(`GET /repos/{owner}/{repo}/collaborators`, {
+    owner,
+    repo,
+    headers: {
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+  })
+  return res.data
+}
+const cachedFetchContributors = cache(fetchContributors)
+
+// ██████   █████   ██████ ██   ██ ███████ ██████  ███████
+// ██   ██ ██   ██ ██      ██  ██  ██      ██   ██ ██
+// ██████  ███████ ██      █████   █████   ██████  ███████
+// ██   ██ ██   ██ ██      ██  ██  ██      ██   ██      ██
+// ██████  ██   ██  ██████ ██   ██ ███████ ██   ██ ███████
+
+export async function Backers({
+  repo,
+  limit = 50,
+  className,
+  ...props
+}: ComponentProps<'ul'> & {
+  repo: string
+  limit: number
+}) {
+  const backers = (await fetchBackers(repo)).slice(0, limit)
+
+  return (
+    <div>
+      <ul className={cn('flex flex-wrap gap-1', className)} {...props}>
+        {backers.map((backer) => (
+          <li key={backer.name}>
+            <Avatar profileUrl={backer.profile} imageUrl={backer.image} name={backer.name} />
+          </li>
+        ))}
+      </ul>
+      <p>
+        <a
+          href={`https://opencollective.com/${repo}#backers`}
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <Image src={backerBadge} alt="Backer" />
+        </a>
+      </p>
+    </div>
+  )
+}
+
+async function fetchBackers(repo: string) {
+  const res = await fetch(`https://opencollective.com/${repo}/members/users.json`)
+  const backers: {
+    profile: string
+    name: string
+    image: string
+    totalAmountDonated: number
+  }[] = await res.json()
+
+  const backersMap = new Map(backers.map((backer) => [backer.name, backer]))
+  backersMap.forEach((backer) => {
+    const existingBacker = backersMap.get(backer.name)
+    if (existingBacker && backer.totalAmountDonated >= existingBacker.totalAmountDonated) {
+      backersMap.set(backer.name, backer) // replace with the backer with the highest donation
+    }
+  })
+  const uniqueBackers = Array.from(backersMap.values())
+
+  return uniqueBackers.sort((a, b) => b.totalAmountDonated - a.totalAmountDonated)
+}
+
+const cachedFetchBackers = cache(fetchBackers)
+
+//
+// common
+//
+
+function Avatar({
+  profileUrl,
+  imageUrl,
+  name,
+  className,
+  ...props
+}: { profileUrl: string; imageUrl: string; name: string } & ComponentProps<'a'>) {
+  return (
+    <a
+      href={profileUrl}
+      target="_blank"
+      rel="noopener noreferrer"
+      className={cn(
+        className,
+        'bg-surface-container-high inline-flex size-12 items-center justify-center overflow-clip rounded-full',
+      )}
+      {...props}
+    >
+      {imageUrl ? (
+        <Image width="48" height="48" src={imageUrl} alt={name} className="size-full" />
+      ) : (
+        initials(name)
+      )}
+    </a>
+  )
+}

src/components/mdx/People/index.ts

@@ -0,0 +1 @@
+export * from './People'

src/components/mdx/index.tsx

@@ -7,6 +7,7 @@ export * from './Hint'
 export * from './Img'
 export * from './Intro'
 export * from './Keypoints'
+export * from './People'
 export * from './Summary'
 export * from './Toc'
 

src/utils/text.ts

@@ -10,3 +10,17 @@ export const highlight = (text: string, target: string) =>
   target.length > 0
     ? text.replace(new RegExp(escape(target), 'gi'), (match: string) => `<mark>${match}</mark>`)
     : text
+
+export function initials(name: string) {
+  const parts = name.split(' ')
+
+  if (parts.length > 1) {
+    return parts
+      .slice(0, 2)
+      .map(([char]) => char)
+      .join('')
+      .toUpperCase()
+  }
+
+  return name.slice(0, 2).toUpperCase()
+}