diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx new file mode 100644 index 0000000000000..d6768e5a7aad1 --- /dev/null +++ b/docs/platforms/javascript/common/apis.mdx @@ -0,0 +1,75 @@ +--- +title: APIs +description: "Learn more about APIs of the SDK." +customCanonicalTag: "/platforms/javascript/apis/" +sidebar_order: 3 +--- + +This page shows all available to-level APIs of the SDK. You can use them like this: + +```javascript +import * as Sentry from "@sentry/browser"; + +Sentry.setTag("tag", "value"); +``` + +## Available Options + + + +## Enriching Events + +", + description: + "Additional data that should be sent with the breadcrumb.", + }, + ], + }, + { + name: "hint", + type: "Record", + description: + "A hint object containing additional information about the breadcrumb.", + }, + ]} +> + You can manually add breadcrumbs whenever something interesting happens. For + example, you might manually record a breadcrumb if the user authenticates or + another state change occurs. + diff --git a/src/components/sdkApi.tsx b/src/components/sdkApi.tsx new file mode 100644 index 0000000000000..f97a61c928da1 --- /dev/null +++ b/src/components/sdkApi.tsx @@ -0,0 +1,99 @@ +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 {refractor} from 'refractor/lib/core.js'; + +import {PlatformCategory} from 'sentry-docs/types'; + +import {Expandable} from './expandable'; +import {SdkDefinition, SdkDefinitionTable} from './sdkDefinition'; + +interface ParameterDef { + name: string; + type: string | ParameterDef[]; + defaultValue?: string; + description?: string; + required?: boolean; +} + +type Props = { + name: string; + parameters: ParameterDef[]; + signature: string; + categorySupported?: PlatformCategory[]; + children?: React.ReactNode; + language?: string; +}; + +refractor.register(bash); +refractor.register(json); + +const codeToJsx = (code: string, lang = 'json') => { + return toJsxRuntime(refractor.highlight(code, lang) as Nodes, {Fragment, jsx, jsxs}); +}; + +export function SdkApi({ + name, + children, + signature, + parameters = [], + // TODO: How to handle this default better? + language = 'typescript', + categorySupported = [], +}: Props) { + return ( + +
{codeToJsx(signature, language)}
+ + {parameters.length ? ( + + + {parameters.map(param => ( + + ))} + + + ) : null} + + {children} +
+ ); +} + +function ApiParameterDef({name, type, description, required}: ParameterDef) { + return ( + + + {name} + {required ? * : null} + + + {typeof type === 'string' ? ( + {type} + ) : ( + + )} + + {description ?

{description}

: null} + + + ); +} + +function RenderNestedObject({objProps}: {objProps: ParameterDef[]}) { + return ( + +
+ Object: +
+ + {objProps.map(prop => ( + + ))} + +
+ ); +} diff --git a/src/components/sdkDefinition/index.tsx b/src/components/sdkDefinition/index.tsx new file mode 100644 index 0000000000000..ef799aca63e7b --- /dev/null +++ b/src/components/sdkDefinition/index.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 ( + +
+

+ + + + + {name} + +

+ + {children} +
+
+ ); +} + +export function SdkDefinitionTable({ + children, + className, +}: { + children?: React.ReactNode; + className?: string; +}) { + return ( + + {children} +
+ ); +} diff --git a/src/components/sdkOption/style.module.scss b/src/components/sdkDefinition/style.module.scss similarity index 87% rename from src/components/sdkOption/style.module.scss rename to src/components/sdkDefinition/style.module.scss index 263f6f8e40516..74a84ee713203 100644 --- a/src/components/sdkOption/style.module.scss +++ b/src/components/sdkDefinition/style.module.scss @@ -1,12 +1,20 @@ .sdk-option-table { --border-radius: 6px; - + font-size: 1rem; width: auto !important; // This is necessary to make rounded borders work :( border-collapse: separate !important; border-spacing: 0px; + &:first-child { + margin-top: 0; + } + + &:last-child { + margin-bottom: 0; + } + & tr th, & tr td { border-bottom-width: 0; border-right-width: 0; diff --git a/src/components/sdkOption.tsx b/src/components/sdkOption.tsx new file mode 100644 index 0000000000000..781095976cdac --- /dev/null +++ b/src/components/sdkOption.tsx @@ -0,0 +1,86 @@ +import {getCurrentPlatformOrGuide} from 'sentry-docs/docTree'; +import {serverContext} from 'sentry-docs/serverContext'; +import {PlatformCategory} from 'sentry-docs/types'; + +import {PlatformCategorySection} from './platformCategorySection'; +import {PlatformSection} from './platformSection'; +import {SdkDefinition, SdkDefinitionTable} from './sdkDefinition'; + +type Props = { + name: string; + type: string; + categorySupported?: PlatformCategory[]; + children?: React.ReactNode; + defaultValue?: string; + envVar?: string; +}; + +export function SdkOption({ + name, + children, + type, + defaultValue, + envVar, + categorySupported = [], +}: Props) { + const {showBrowserOnly, showServerLikeOnly} = getPlatformHints(categorySupported); + + return ( + + + {type && } + {defaultValue && } + + + + {envVar && } + + + + {showBrowserOnly && } + {showServerLikeOnly && } + + + {children} + + ); +} + +function OptionDefRow({label, value}: {label: string; value: string}) { + return ( + + {label} + + {value} + + + ); +} + +function getPlatformHints(categorySupported: PlatformCategory[]) { + const {rootNode, path} = serverContext(); + const currentPlatformOrGuide = getCurrentPlatformOrGuide(rootNode, path); + const currentCategories = currentPlatformOrGuide?.categories || []; + + // We only handle browser, server & serverless here for now + const currentIsBrowser = currentCategories.includes('browser'); + const currentIsServer = currentCategories.includes('server'); + const currentIsServerless = currentCategories.includes('serverless'); + const currentIsServerLike = currentIsServer || currentIsServerless; + + const hasCategorySupported = categorySupported.length > 0; + const supportedBrowserOnly = + categorySupported.includes('browser') && + !categorySupported.includes('server') && + !categorySupported.includes('serverless'); + const supportedServerLikeOnly = + !categorySupported.includes('browser') && + (categorySupported.includes('server') || categorySupported.includes('serverless')); + + const showBrowserOnly = + hasCategorySupported && supportedBrowserOnly && currentIsServerLike; + const showServerLikeOnly = + hasCategorySupported && supportedServerLikeOnly && currentIsBrowser; + + return {showBrowserOnly, showServerLikeOnly}; +} diff --git a/src/components/sdkOption/index.tsx b/src/components/sdkOption/index.tsx deleted file mode 100644 index f0fc2adc96304..0000000000000 --- a/src/components/sdkOption/index.tsx +++ /dev/null @@ -1,130 +0,0 @@ -import {getCurrentPlatformOrGuide} from 'sentry-docs/docTree'; -import {serverContext} from 'sentry-docs/serverContext'; -import {PlatformCategory} from 'sentry-docs/types'; - -import styles from './style.module.scss'; - -import {PlatformCategorySection} from '../platformCategorySection'; -import {PlatformSection} from '../platformSection'; - -type Props = { - name: string; - type: string; - categorySupported?: PlatformCategory[]; - children?: React.ReactNode; - defaultValue?: string; - envVar?: string; - group?: string; -}; - -export function SdkOption({ - name, - children, - type, - defaultValue, - envVar, - categorySupported = [], -}: Props) { - const {showBrowserOnly, showServerLikeOnly} = getPlatformHints(categorySupported); - - return ( - -
-

- - - - - {name} - -

- - - - {type && ( - - - - - )} - {defaultValue && ( - - - - - )} - - - {envVar && ( - - - - - )} - - - - {showBrowserOnly && ( - - - - - )} - - {showServerLikeOnly && ( - - - - - )} - -
Type - {type} -
Default - {defaultValue} -
ENV Variable - {envVar} -
Only available onClient
Only available onServer
- - {children} -
-
- ); -} - -function getPlatformHints(categorySupported: PlatformCategory[]) { - const {rootNode, path} = serverContext(); - const currentPlatformOrGuide = getCurrentPlatformOrGuide(rootNode, path); - const currentCategories = currentPlatformOrGuide?.categories || []; - - // We only handle browser, server & serverless here for now - const currentIsBrowser = currentCategories.includes('browser'); - const currentIsServer = currentCategories.includes('server'); - const currentIsServerless = currentCategories.includes('serverless'); - const currentIsServerLike = currentIsServer || currentIsServerless; - - const hasCategorySupported = categorySupported.length > 0; - const supportedBrowserOnly = - categorySupported.includes('browser') && - !categorySupported.includes('server') && - !categorySupported.includes('serverless'); - const supportedServerLikeOnly = - !categorySupported.includes('browser') && - (categorySupported.includes('server') || categorySupported.includes('serverless')); - - const showBrowserOnly = - hasCategorySupported && supportedBrowserOnly && currentIsServerLike; - const showServerLikeOnly = - hasCategorySupported && supportedServerLikeOnly && currentIsBrowser; - - return {showBrowserOnly, showServerLikeOnly}; -} diff --git a/src/mdxComponents.ts b/src/mdxComponents.ts index f433c793de689..0f61fb91a3660 100644 --- a/src/mdxComponents.ts +++ b/src/mdxComponents.ts @@ -33,6 +33,7 @@ import {PlatformSdkPackageName} from './components/platformSdkPackageName'; import {PlatformSection} from './components/platformSection'; import {RelayMetrics} from './components/relayMetrics'; import {SandboxLink} from './components/sandboxLink'; +import {SdkApi} from './components/sdkApi'; import {SdkOption} from './components/sdkOption'; import {SignInNote} from './components/signInNote'; import {SmartLink} from './components/smartLink'; @@ -56,6 +57,7 @@ export function mdxComponents( CodeTabs, ConfigKey, SdkOption, + SdkApi, TableOfContents, CreateGitHubAppForm, ConfigValue,