From 2c6d345c65cc836a8d0ee467fd4e529cadd18689 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 6 Feb 2025 12:32:22 +0100 Subject: [PATCH 1/7] ref to be more extensible --- src/components/sdkDefinition/index.tsx | 64 +++++++++ .../style.module.scss | 0 src/components/sdkOption.tsx | 85 ++++++++++++ src/components/sdkOption/index.tsx | 130 ------------------ 4 files changed, 149 insertions(+), 130 deletions(-) create mode 100644 src/components/sdkDefinition/index.tsx rename src/components/{sdkOption => sdkDefinition}/style.module.scss (100%) create mode 100644 src/components/sdkOption.tsx delete mode 100644 src/components/sdkOption/index.tsx diff --git a/src/components/sdkDefinition/index.tsx b/src/components/sdkDefinition/index.tsx new file mode 100644 index 0000000000000..80cd5b4a36aa8 --- /dev/null +++ b/src/components/sdkDefinition/index.tsx @@ -0,0 +1,64 @@ +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}: {children?: React.ReactNode}) { + return ( + + {children} +
+ ); +} + +export function SdkDefinitionTableRow({ + label, + children, +}: { + label: string; + children?: React.ReactNode; +}) { + return ( + + {label} + + {children} + + + ); +} diff --git a/src/components/sdkOption/style.module.scss b/src/components/sdkDefinition/style.module.scss similarity index 100% rename from src/components/sdkOption/style.module.scss rename to src/components/sdkDefinition/style.module.scss diff --git a/src/components/sdkOption.tsx b/src/components/sdkOption.tsx new file mode 100644 index 0000000000000..66cafdcfe4e81 --- /dev/null +++ b/src/components/sdkOption.tsx @@ -0,0 +1,85 @@ +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, SdkDefinitionTableRow} from './sdkDefinition'; + +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 ( + + + {type && {type}} + {defaultValue && ( + {defaultValue} + )} + + + + {envVar && ( + {envVar} + )} + + + + {showBrowserOnly && ( + Client + )} + + {showServerLikeOnly && ( + Server + )} + + + {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/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}; -} From 073c46ad8900cf61de6714f9508e53e3e4df6639 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 6 Feb 2025 14:53:10 +0100 Subject: [PATCH 2/7] WIP WIP --- docs/platforms/javascript/common/apis.mdx | 75 +++++++++++++ src/components/sdkApi.tsx | 101 ++++++++++++++++++ src/components/sdkDefinition/index.tsx | 21 +--- .../sdkDefinition/style.module.scss | 8 ++ src/components/sdkOption.tsx | 33 +++--- src/mdxComponents.ts | 2 + 6 files changed, 205 insertions(+), 35 deletions(-) create mode 100644 docs/platforms/javascript/common/apis.mdx create mode 100644 src/components/sdkApi.tsx 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..327be8f6c9966 --- /dev/null +++ b/src/components/sdkApi.tsx @@ -0,0 +1,101 @@ +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 {getCurrentPlatformOrGuide} from 'sentry-docs/docTree'; +import {serverContext} from 'sentry-docs/serverContext'; +import {PlatformCategory} from 'sentry-docs/types'; + +import {CodeBlock} from './codeBlock'; +import {CodeTabs} from './codeTabs'; +import {PlatformCategorySection} from './platformCategorySection'; +import {PlatformSection} from './platformSection'; +import {SdkDefinition, SdkDefinitionTable, SdkDefinitionTableRow} 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; +}; + +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 = [], + categorySupported = [], +}: Props) { + return ( + + 
{codeToJsx(signature, 'typescript')}
+ + {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 index 80cd5b4a36aa8..dc3e46a6815e8 100644 --- a/src/components/sdkDefinition/index.tsx +++ b/src/components/sdkDefinition/index.tsx @@ -38,27 +38,10 @@ export function SdkDefinition({name, children, categorySupported = []}: Props) { ); } -export function SdkDefinitionTable({children}: {children?: React.ReactNode}) { +export function SdkDefinitionTable({children, className}: {children?: React.ReactNode, className?: string}) { return ( - +
{children}
); } - -export function SdkDefinitionTableRow({ - label, - children, -}: { - label: string; - children?: React.ReactNode; -}) { - return ( - - {label} - - {children} - - - ); -} diff --git a/src/components/sdkDefinition/style.module.scss b/src/components/sdkDefinition/style.module.scss index 263f6f8e40516..fb860e8ea9488 100644 --- a/src/components/sdkDefinition/style.module.scss +++ b/src/components/sdkDefinition/style.module.scss @@ -7,6 +7,14 @@ 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 index 66cafdcfe4e81..781095976cdac 100644 --- a/src/components/sdkOption.tsx +++ b/src/components/sdkOption.tsx @@ -4,7 +4,7 @@ import {PlatformCategory} from 'sentry-docs/types'; import {PlatformCategorySection} from './platformCategorySection'; import {PlatformSection} from './platformSection'; -import {SdkDefinition, SdkDefinitionTable, SdkDefinitionTableRow} from './sdkDefinition'; +import {SdkDefinition, SdkDefinitionTable} from './sdkDefinition'; type Props = { name: string; @@ -13,7 +13,6 @@ type Props = { children?: React.ReactNode; defaultValue?: string; envVar?: string; - group?: string; }; export function SdkOption({ @@ -29,26 +28,17 @@ export function SdkOption({ return ( - {type && {type}} - {defaultValue && ( - {defaultValue} - )} + {type && } + {defaultValue && } - {envVar && ( - {envVar} - )} + {envVar && } - {showBrowserOnly && ( - Client - )} - - {showServerLikeOnly && ( - Server - )} + {showBrowserOnly && } + {showServerLikeOnly && } {children} @@ -56,6 +46,17 @@ export function SdkOption({ ); } +function OptionDefRow({label, value}: {label: string; value: string}) { + return ( + + {label} + + {value} + + + ); +} + function getPlatformHints(categorySupported: PlatformCategory[]) { const {rootNode, path} = serverContext(); const currentPlatformOrGuide = getCurrentPlatformOrGuide(rootNode, path); 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, From b31b21159851af021effab94e6733a2233ab7513 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 6 Feb 2025 15:57:05 +0100 Subject: [PATCH 3/7] wip fixes --- src/components/sdkApi.tsx | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/src/components/sdkApi.tsx b/src/components/sdkApi.tsx index 327be8f6c9966..723485d7f2a22 100644 --- a/src/components/sdkApi.tsx +++ b/src/components/sdkApi.tsx @@ -6,15 +6,9 @@ import bash from 'refractor/lang/bash.js'; import json from 'refractor/lang/json.js'; import {refractor} from 'refractor/lib/core.js'; -import {getCurrentPlatformOrGuide} from 'sentry-docs/docTree'; -import {serverContext} from 'sentry-docs/serverContext'; import {PlatformCategory} from 'sentry-docs/types'; -import {CodeBlock} from './codeBlock'; -import {CodeTabs} from './codeTabs'; -import {PlatformCategorySection} from './platformCategorySection'; -import {PlatformSection} from './platformSection'; -import {SdkDefinition, SdkDefinitionTable, SdkDefinitionTableRow} from './sdkDefinition'; +import {SdkDefinition, SdkDefinitionTable} from './sdkDefinition'; interface ParameterDef { name: string; @@ -30,6 +24,7 @@ type Props = { signature: string; categorySupported?: PlatformCategory[]; children?: React.ReactNode; + language?: string; }; refractor.register(bash); @@ -44,11 +39,13 @@ export function SdkApi({ children, signature, parameters = [], + // TODO: How to handle this default better? + language = 'typescript', categorySupported = [], }: Props) { return ( - 
{codeToJsx(signature, 'typescript')}
+ 
{codeToJsx(signature, language)}
{parameters.length ? ( From a559d29ce7e545975416b91164044c43af209bde Mon Sep 17 00:00:00 2001 From: "getsantry[bot]" <66042841+getsantry[bot]@users.noreply.github.com> Date: Thu, 6 Feb 2025 14:58:07 +0000 Subject: [PATCH 4/7] [getsentry/action-github-commit] Auto commit --- src/components/sdkDefinition/index.tsx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/components/sdkDefinition/index.tsx b/src/components/sdkDefinition/index.tsx index dc3e46a6815e8..ef799aca63e7b 100644 --- a/src/components/sdkDefinition/index.tsx +++ b/src/components/sdkDefinition/index.tsx @@ -38,7 +38,13 @@ export function SdkDefinition({name, children, categorySupported = []}: Props) { ); } -export function SdkDefinitionTable({children, className}: {children?: React.ReactNode, className?: string}) { +export function SdkDefinitionTable({ + children, + className, +}: { + children?: React.ReactNode; + className?: string; +}) { return ( {children} From 1b0e8e143f429d5a61a4388de2960e969b4fc9e5 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 6 Feb 2025 15:59:01 +0100 Subject: [PATCH 5/7] expandable parameters? --- src/components/sdkApi.tsx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/components/sdkApi.tsx b/src/components/sdkApi.tsx index 723485d7f2a22..85ebcfdaff2a6 100644 --- a/src/components/sdkApi.tsx +++ b/src/components/sdkApi.tsx @@ -8,6 +8,7 @@ import {refractor} from 'refractor/lib/core.js'; import {PlatformCategory} from 'sentry-docs/types'; +import {Expandable} from './expandable'; import {SdkDefinition, SdkDefinitionTable} from './sdkDefinition'; interface ParameterDef { @@ -48,13 +49,13 @@ export function SdkApi({ 
{codeToJsx(signature, language)}
{parameters.length ? ( - - + + {parameters.map(param => ( ))} - + ) : null} {children} From 48dd846f239b9b4ffa31a0eb37c3d5ca1dd9fbab Mon Sep 17 00:00:00 2001 From: "getsantry[bot]" <66042841+getsantry[bot]@users.noreply.github.com> Date: Thu, 6 Feb 2025 15:00:10 +0000 Subject: [PATCH 6/7] [getsentry/action-github-commit] Auto commit --- src/components/sdkApi.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/components/sdkApi.tsx b/src/components/sdkApi.tsx index 85ebcfdaff2a6..f97a61c928da1 100644 --- a/src/components/sdkApi.tsx +++ b/src/components/sdkApi.tsx @@ -49,8 +49,8 @@ export function SdkApi({ 
{codeToJsx(signature, language)}
{parameters.length ? ( - - + + {parameters.map(param => ( ))} From 8276829fca10e3d1b5b3cf245a7b5d1b1ee28754 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 6 Feb 2025 17:02:26 +0100 Subject: [PATCH 7/7] font size? --- src/components/sdkDefinition/style.module.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/sdkDefinition/style.module.scss b/src/components/sdkDefinition/style.module.scss index fb860e8ea9488..74a84ee713203 100644 --- a/src/components/sdkDefinition/style.module.scss +++ b/src/components/sdkDefinition/style.module.scss @@ -1,6 +1,6 @@ .sdk-option-table { --border-radius: 6px; - + font-size: 1rem; width: auto !important; // This is necessary to make rounded borders work :(