feat: Add APIs page for JavaScript (#12605)

---------

Co-authored-by: Lukas Stracke <[email protected]>
Co-authored-by: Sarah Mischinger <[email protected]>

Author: 3 people

docs/platforms/javascript/common/apis.mdx

@@ -77,7 +77,7 @@ Sentry.withScope((scope) => {
 Sentry.captureException(new Error("my other error"));
 ```
 
-You can access the current scope via `Sentry.getCurrentScope()`, but usually you should use `Sentry.withScope()` to interact with local scopes instead.
+You can access the current scope via `Sentry.getCurrentScope()`, but in most cases you should not use this API, but instead use `withScope` to generate and access a local scope. There are no guarantees about the consistency of `getCurrentScope` across different parts of your application, as scope forking may happen under the hood at various points.
 
 ## How Scope Data is Applied to Events
 

docs/platforms/javascript/common/enriching-events/scopes/index.mdx

@@ -3,6 +3,7 @@ platformTitle: JavaScript
 caseStyle: camelCase
 supportLevel: production
 sdk: 'sentry.javascript.browser'
+language: typescript
 categories:
   - javascript
   - browser

docs/platforms/javascript/config.yml

@@ -1,13 +1,7 @@
 'use client';
 
 import {Fragment, useEffect, useState} from 'react';
-import {jsx, jsxs} from 'react/jsx-runtime';
 import {Clipboard} from 'react-feather';
-import {toJsxRuntime} from 'hast-util-to-jsx-runtime';
-import {Nodes} from 'hastscript/lib/create-h';
-import bash from 'refractor/lang/bash.js';
-import json from 'refractor/lang/json.js';
-import {refractor} from 'refractor/lib/core.js';
 
 import {type API} from 'sentry-docs/build/resolveOpenAPI';
 
@@ -16,9 +10,7 @@ import styles from './apiExamples.module.scss';
 
 import {CodeBlock} from '../codeBlock';
 import {CodeTabs} from '../codeTabs';
-
-refractor.register(bash);
-refractor.register(json);
+import {codeToJsx} from '../highlightCode';
 
 const strFormat = (str: string) => {
   const s = str.trim();
@@ -32,10 +24,6 @@ type Props = {
   api: API;
 };
 
-const codeToJsx = (code: string, lang = 'json') => {
-  return toJsxRuntime(refractor.highlight(code, lang) as Nodes, {Fragment, jsx, jsxs});
-};
-
 export function ApiExamples({api}: Props) {
   const apiExample = [
     `curl ${api.server}${api.apiPath}`,

src/components/apiExamples/apiExamples.tsx

@@ -55,6 +55,7 @@
 
 .callout-content {
   min-width: 0;
+  flex-grow: 1;
 }
 
 .callout-info {

src/components/callout/styles.scss

@@ -0,0 +1,23 @@
+import {Fragment} from 'react';
+import {jsx, jsxs} from 'react/jsx-runtime';
+import {toJsxRuntime} from 'hast-util-to-jsx-runtime';
+import {Nodes} from 'hastscript/lib/create-h';
+import bash from 'refractor/lang/bash.js';
+import json from 'refractor/lang/json.js';
+import typescript from 'refractor/lang/typescript.js';
+import {refractor} from 'refractor/lib/core.js';
+
+refractor.register(bash);
+refractor.register(json);
+refractor.register(typescript);
+
+// If a new language should be supported, add it here and register it in refractor above
+export const SUPPORTED_LANGUAGES = ['bash', 'json', 'typescript'];
+
+export function codeToJsx(code: string, lang = 'json') {
+  if (!SUPPORTED_LANGUAGES.includes(lang)) {
+    // eslint-disable-next-line no-console
+    console.error(`Unsupported language for syntax highlighting: ${lang}`);
+  }
+  return toJsxRuntime(refractor.highlight(code, lang) as Nodes, {Fragment, jsx, jsxs});
+}

src/components/highlightCode.tsx

@@ -0,0 +1,158 @@
+import {Fragment} from 'react';
+
+import {getCurrentPlatform} from 'sentry-docs/docTree';
+import {serverContext} from 'sentry-docs/serverContext';
+import {PlatformCategory} from 'sentry-docs/types';
+
+import {Expandable} from './expandable';
+import {codeToJsx} from './highlightCode';
+import {SdkDefinition} from './sdkDefinition';
+import {getPlatformHints} from './sdkOption';
+
+export interface ParameterDef {
+  name: string;
+  type: string | ObjectParameterDef;
+  defaultValue?: string;
+  description?: string;
+  required?: boolean;
+}
+
+type ObjectParameterDef = {
+  properties: ParameterDef[];
+  name?: string;
+};
+
+type Props = {
+  name: string;
+  parameters: ParameterDef[];
+  signature: string;
+  categorySupported?: PlatformCategory[];
+  children?: React.ReactNode;
+  language?: string;
+};
+
+export function SdkApi({
+  name,
+  children,
+  signature,
+  parameters = [],
+  language,
+  categorySupported = [],
+}: Props) {
+  const {rootNode, path} = serverContext();
+  const platform = getCurrentPlatform(rootNode, path);
+  const lang = language || platform?.language || 'typescript';
+
+  const {showBrowserOnly, showServerLikeOnly} = getPlatformHints(categorySupported);
+
+  return (
+    <SdkDefinition name={name} categorySupported={categorySupported}>
+      {showBrowserOnly && <div className="italic text-sm">Only available on Client</div>}
+      {showServerLikeOnly && (
+        <div className="italic text-sm">Only available on Server</div>
+      )}
+
+      <pre className="mt-2 mb-2 text-sm">{codeToJsx(signature, lang)}</pre>
+
+      {parameters.length ? (
+        <Expandable title="Parameters">
+          <div className="space-y-3">
+            {parameters.map(param => (
+              <ApiParameterDef key={param.name} language={lang} {...param} />
+            ))}
+          </div>
+        </Expandable>
+      ) : null}
+
+      {children}
+    </SdkDefinition>
+  );
+}
+
+function ApiParameterDef({
+  name,
+  type,
+  description,
+  required,
+  language,
+}: ParameterDef & {language: string}) {
+  return (
+    <div className="space-y-1">
+      <div className="font-bold m-0">
+        {name}
+        {required ? <span className="text-red">*</span> : null}
+      </div>
+      <div className="space-y-1">
+        <div className="flex">
+          {typeof type === 'string' ? (
+            <pre className="m-0 pt-1 pb-1 text-sm">
+              <code>{codeToJsx(type, language)}</code>
+            </pre>
+          ) : (
+            <pre className="m-0 pt-1 pb-1 text-sm">
+              <NestedObject
+                name={type.name}
+                objProps={type.properties}
+                language={language}
+              />
+            </pre>
+          )}
+        </div>
+
+        {description ? <p className="m-0">{description}</p> : null}
+      </div>
+    </div>
+  );
+}
+
+function NestedObject({
+  name,
+  objProps,
+  language,
+}: {
+  language: string;
+  objProps: ParameterDef[];
+  name?: string;
+}) {
+  // NOTE: For now, we always render the nested object in typescript
+
+  return (
+    <div>
+      <div>
+        <code>
+          {name ? name : 'Object'} {'{'}
+        </code>
+      </div>
+
+      <div className="flex flex-col gap-2 pl-4">
+        {objProps.map(prop => (
+          <div key={prop.name}>
+            {prop.description && (
+              <div>
+                <code>{codeToJsx(`// ${prop.description}`, 'typescript')}</code>
+              </div>
+            )}
+            <div>
+              {typeof prop.type === 'string' ? (
+                <Fragment>
+                  <code>
+                    {prop.name}
+                    {!prop.required ? '?' : ''}:{' '}
+                  </code>
+                  <code>{codeToJsx(prop.type, 'typescript')},</code>
+                </Fragment>
+              ) : (
+                <NestedObject
+                  name={`${prop.name}${!prop.required ? '?' : ''}: ${prop.type.name || 'Object'}`}
+                  objProps={prop.type.properties}
+                  language={language}
+                />
+              )}
+            </div>
+          </div>
+        ))}
+      </div>
+      <div>{'}'}</div>
+    </div>
+  );
+}

src/components/sdkApi.tsx

@@ -0,0 +1,53 @@
+import {PlatformCategory} from 'sentry-docs/types';
+
+import styles from './style.module.scss';
+
+import {PlatformCategorySection} from '../platformCategorySection';
+
+type Props = {
+  name: string;
+  categorySupported?: PlatformCategory[];
+  children?: React.ReactNode;
+};
+
+export function SdkDefinition({name, children, categorySupported = []}: Props) {
+  return (
+    <PlatformCategorySection supported={categorySupported}>
+      <div className={styles['sdk-config-option']}>
+        <h3 id={name} aria-label={name} data-sdk-option>
+          <a href={`#${name}`}>
+            <svg
+              className="anchorlink before"
+              viewBox="0 0 24 24"
+              xmlns="http://www.w3.org/2000/svg"
+              width="16"
+              height="16"
+            >
+              <path
+                d="M9.199 13.599a5.99 5.99 0 0 0 3.949 2.345 5.987 5.987 0 0 0 5.105-1.702l2.995-2.994a5.992 5.992 0 0 0 1.695-4.285 5.976 5.976 0 0 0-1.831-4.211 5.99 5.99 0 0 0-6.431-1.242 6.003 6.003 0 0 0-1.905 1.24l-1.731 1.721a.999.999 0 1 0 1.41 1.418l1.709-1.699a3.985 3.985 0 0 1 2.761-1.123 3.975 3.975 0 0 1 2.799 1.122 3.997 3.997 0 0 1 .111 5.644l-3.005 3.006a3.982 3.982 0 0 1-3.395 1.126 3.987 3.987 0 0 1-2.632-1.563A1 1 0 0 0 9.201 13.6zm5.602-3.198a5.99 5.99 0 0 0-3.949-2.345 5.987 5.987 0 0 0-5.105 1.702l-2.995 2.994a5.992 5.992 0 0 0-1.695 4.285 5.976 5.976 0 0 0 1.831 4.211 5.99 5.99 0 0 0 6.431 1.242 6.003 6.003 0 0 0 1.905-1.24l1.723-1.723a.999.999 0 1 0-1.414-1.414L9.836 19.81a3.985 3.985 0 0 1-2.761 1.123 3.975 3.975 0 0 1-2.799-1.122 3.997 3.997 0 0 1-.111-5.644l3.005-3.006a3.982 3.982 0 0 1 3.395-1.126 3.987 3.987 0 0 1 2.632 1.563 1 1 0 0 0 1.602-1.198z"
+                fill="currentColor"
+              />
+            </svg>
+            {name}
+          </a>
+        </h3>
+
+        <div className={styles['sdk-config-option-details']}>{children}</div>
+      </div>
+    </PlatformCategorySection>
+  );
+}
+
+export function SdkDefinitionTable({
+  children,
+  className,
+}: {
+  children?: React.ReactNode;
+  className?: string;
+}) {
+  return (
+    <table className={styles['sdk-option-table'] + (className ? ` ${className}` : '')}>
+      <tbody>{children}</tbody>
+    </table>
+  );
+}

src/components/sdkDefinition/index.tsx

@@ -1,25 +1,34 @@
-.sdk-config-option {
-  padding-top: 10px;
+.sdk-config-option:not(:last-child) {
+  margin-bottom: 2rem;
 }
 
 .sdk-config-option-details {
-  padding-left: 20px;
+  padding-left: 0;
 }
 
 .sdk-option-table {
   --border-radius: 6px;
+  font-size: 1rem;
   margin-top: 1rem;
-
-  width: auto !important;
+  width: auto;
 
   // This is necessary to make rounded borders work :(
   border-collapse: separate !important;
   border-spacing: 0;
 
-  & tr th, & tr td {
+  &:first-child {
+    margin-top: 0;
+  }
+
+  &:last-child {
+    margin-bottom: 0;
+  }
+
+  & tr th,
+  & tr td {
     border-bottom-width: 0;
     border-right-width: 0;
-    padding: .5rem .75rem
+    padding: 0.5rem 0.75rem;
   }
 
   & tr:last-child > * {
@@ -46,3 +55,8 @@
     border-bottom-right-radius: var(--border-radius);
   }
 }
+
+// This is to ensure specificity beats .prose table :(
+.sdk-config-option .sdk-option-table {
+  width: auto;
+}