Skip to content

Commit 49e64c1

Browse files
mydeamydea
committed
WIP WIP
1 parent 4d35022 commit 49e64c1

File tree

6 files changed

+205
-35
lines changed

6 files changed

+205
-35
lines changed

‎docs/platforms/javascript/common/apis.mdx‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: APIs
3+
description: "Learn more about APIs of the SDK."
4+
customCanonicalTag: "/platforms/javascript/apis/"
5+
sidebar_order: 3
6+
---
7+
8+
This page shows all available to-level APIs of the SDK. You can use them like this:
9+
10+
```javascript
11+
import * as Sentry from "@sentry/browser";
12+
13+
Sentry.setTag("tag", "value");
14+
```
15+
16+
## Available Options
17+
18+
<TableOfContents ignoreIds={["available-options"]} />
19+
20+
## Enriching Events
21+
22+
<SdkApi
23+
name="addBreadcrumb"
24+
signature="function addBreadcrumb(breadcrumb: Breadcrumb, hint?: Hint): void"
25+
parameters={[
26+
{
27+
name: "breadcrumb",
28+
required: true,
29+
type: [
30+
{
31+
name: "message",
32+
type: "string",
33+
description:
34+
"If a message is provided, it is rendered as text with all whitespace preserved.",
35+
},
36+
{
37+
name: "type",
38+
type: '"default" | "debug" | "error" | "info" | "navigation" | "http" | "query" | "ui" | "user"',
39+
defaultValue: '"default"',
40+
description:
41+
"The type influences how a breadcrumb is rendered in Sentry. When in doubt, leave it at `default`.",
42+
},
43+
{
44+
name: "level",
45+
type: '"fatal" | "error" | "warning" | "log" | "info" | "debug"',
46+
defaultValue: '"info"',
47+
description:
48+
"The level is used in the UI to emphasize or deemphasize the breadcrumb.",
49+
},
50+
{
51+
name: "category",
52+
type: "string",
53+
description:
54+
"Typically it is a module name or a descriptive string. For instance, `ui.click` could be used to indicate that a click happened",
55+
},
56+
{
57+
name: "data",
58+
type: "Record<string, unknown>",
59+
description:
60+
"Additional data that should be sent with the breadcrumb.",
61+
},
62+
],
63+
},
64+
{
65+
name: "hint",
66+
type: "Record<string, unknown>",
67+
description:
68+
"A hint object containing additional information about the breadcrumb.",
69+
},
70+
]}
71+
>
72+
You can manually add breadcrumbs whenever something interesting happens. For
73+
example, you might manually record a breadcrumb if the user authenticates or
74+
another state change occurs.
75+
</SdkApi>

‎src/components/sdkApi.tsx‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
import {Fragment} from 'react';
2+
import {jsx, jsxs} from 'react/jsx-runtime';
3+
import {toJsxRuntime} from 'hast-util-to-jsx-runtime';
4+
import {Nodes} from 'hastscript/lib/create-h';
5+
import bash from 'refractor/lang/bash.js';
6+
import json from 'refractor/lang/json.js';
7+
import {refractor} from 'refractor/lib/core.js';
8+
9+
import {getCurrentPlatformOrGuide} from 'sentry-docs/docTree';
10+
import {serverContext} from 'sentry-docs/serverContext';
11+
import {PlatformCategory} from 'sentry-docs/types';
12+
13+
import {CodeBlock} from './codeBlock';
14+
import {CodeTabs} from './codeTabs';
15+
import {PlatformCategorySection} from './platformCategorySection';
16+
import {PlatformSection} from './platformSection';
17+
import {SdkDefinition, SdkDefinitionTable, SdkDefinitionTableRow} from './sdkDefinition';
18+
19+
interface ParameterDef {
20+
name: string;
21+
type: string | ParameterDef[];
22+
defaultValue?: string;
23+
description?: string;
24+
required?: boolean;
25+
}
26+
27+
type Props = {
28+
name: string;
29+
parameters: ParameterDef[];
30+
signature: string;
31+
categorySupported?: PlatformCategory[];
32+
children?: React.ReactNode;
33+
};
34+
35+
refractor.register(bash);
36+
refractor.register(json);
37+
38+
const codeToJsx = (code: string, lang = 'json') => {
39+
return toJsxRuntime(refractor.highlight(code, lang) as Nodes, {Fragment, jsx, jsxs});
40+
};
41+
42+
export function SdkApi({
43+
name,
44+
children,
45+
signature,
46+
parameters = [],
47+
categorySupported = [],
48+
}: Props) {
49+
return (
50+
<SdkDefinition name={name} categorySupported={categorySupported}>
51+
<pre className="mt-2 mb-2">{codeToJsx(signature, 'typescript')}</pre>
52+
53+
{parameters.length ? (
54+
<Fragment>
55+
<SdkDefinitionTable>
56+
{parameters.map(param => (
57+
<ApiParameterDef key={param.name} {...param} />
58+
))}
59+
</SdkDefinitionTable>
60+
</Fragment>
61+
) : null}
62+
63+
{children}
64+
</SdkDefinition>
65+
);
66+
}
67+
68+
function ApiParameterDef({name, type, description, required}: ParameterDef) {
69+
return (
70+
<tr>
71+
<th>
72+
{name}
73+
{required ? <span className="text-red">*</span> : null}
74+
</th>
75+
<td>
76+
{typeof type === 'string' ? (
77+
<code>{type}</code>
78+
) : (
79+
<RenderNestedObject objProps={type} />
80+
)}
81+
82+
{description ? <p className="m-0">{description}</p> : null}
83+
</td>
84+
</tr>
85+
);
86+
}
87+
88+
function RenderNestedObject({objProps}: {objProps: ParameterDef[]}) {
89+
return (
90+
<Fragment>
91+
<div>
92+
<code>Object:</code>
93+
</div>
94+
<SdkDefinitionTable className="mt-1">
95+
{objProps.map(prop => (
96+
<ApiParameterDef key={prop.name} {...prop} />
97+
))}
98+
</SdkDefinitionTable>
99+
</Fragment>
100+
);
101+
}

‎src/components/sdkDefinition/index.tsx‎

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -38,27 +38,10 @@ export function SdkDefinition({name, children, categorySupported = []}: Props) {
3838
);
3939
}
4040

41-
export function SdkDefinitionTable({children}: {children?: React.ReactNode}) {
41+
export function SdkDefinitionTable({children, className}: {children?: React.ReactNode, className?: string}) {
4242
return (
43-
<table className={styles['sdk-option-table']}>
43+
<table className={styles['sdk-option-table'] + (className ? ` ${className}` : '')}>
4444
<tbody>{children}</tbody>
4545
</table>
4646
);
4747
}
48-
49-
export function SdkDefinitionTableRow({
50-
label,
51-
children,
52-
}: {
53-
label: string;
54-
children?: React.ReactNode;
55-
}) {
56-
return (
57-
<tr>
58-
<th>{label}</th>
59-
<td>
60-
<code>{children}</code>
61-
</td>
62-
</tr>
63-
);
64-
}

‎src/components/sdkDefinition/style.module.scss‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@
77
border-collapse: separate !important;
88
border-spacing: 0px;
99

10+
&:first-child {
11+
margin-top: 0;
12+
}
13+
14+
&:last-child {
15+
margin-bottom: 0;
16+
}
17+
1018
& tr th, & tr td {
1119
border-bottom-width: 0;
1220
border-right-width: 0;

‎src/components/sdkOption.tsx‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import {PlatformCategory} from 'sentry-docs/types';
44

55
import {PlatformCategorySection} from './platformCategorySection';
66
import {PlatformSection} from './platformSection';
7-
import {SdkDefinition, SdkDefinitionTable, SdkDefinitionTableRow} from './sdkDefinition';
7+
import {SdkDefinition, SdkDefinitionTable} from './sdkDefinition';
88

99
type Props = {
1010
name: string;
@@ -13,7 +13,6 @@ type Props = {
1313
children?: React.ReactNode;
1414
defaultValue?: string;
1515
envVar?: string;
16-
group?: string;
1716
};
1817

1918
export function SdkOption({
@@ -29,33 +28,35 @@ export function SdkOption({
2928
return (
3029
<SdkDefinition name={name} categorySupported={categorySupported}>
3130
<SdkDefinitionTable>
32-
{type && <SdkDefinitionTableRow label="Type">{type}</SdkDefinitionTableRow>}
33-
{defaultValue && (
34-
<SdkDefinitionTableRow label="Default">{defaultValue}</SdkDefinitionTableRow>
35-
)}
31+
{type && <OptionDefRow label="Type" value={type} />}
32+
{defaultValue && <OptionDefRow label="Default" value={defaultValue} />}
3633

3734
<PlatformCategorySection supported={['server', 'serverless']}>
3835
<PlatformSection notSupported={['javascript.nextjs']}>
39-
{envVar && (
40-
<SdkDefinitionTableRow label="ENV Variable">{envVar}</SdkDefinitionTableRow>
41-
)}
36+
{envVar && <OptionDefRow label="ENV Variable" value={envVar} />}
4237
</PlatformSection>
4338
</PlatformCategorySection>
4439

45-
{showBrowserOnly && (
46-
<SdkDefinitionTableRow label="Only available on">Client</SdkDefinitionTableRow>
47-
)}
48-
49-
{showServerLikeOnly && (
50-
<SdkDefinitionTableRow label="Only available on">Server</SdkDefinitionTableRow>
51-
)}
40+
{showBrowserOnly && <OptionDefRow label="Only available on" value="Client" />}
41+
{showServerLikeOnly && <OptionDefRow label="Only available on" value="Server" />}
5242
</SdkDefinitionTable>
5343

5444
{children}
5545
</SdkDefinition>
5646
);
5747
}
5848

49+
function OptionDefRow({label, value}: {label: string; value: string}) {
50+
return (
51+
<tr>
52+
<th>{label}</th>
53+
<td>
54+
<code>{value}</code>
55+
</td>
56+
</tr>
57+
);
58+
}
59+
5960
function getPlatformHints(categorySupported: PlatformCategory[]) {
6061
const {rootNode, path} = serverContext();
6162
const currentPlatformOrGuide = getCurrentPlatformOrGuide(rootNode, path);

‎src/mdxComponents.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ import {PlatformSdkPackageName} from './components/platformSdkPackageName';
3333
import {PlatformSection} from './components/platformSection';
3434
import {RelayMetrics} from './components/relayMetrics';
3535
import {SandboxLink} from './components/sandboxLink';
36+
import {SdkApi} from './components/sdkApi';
3637
import {SdkOption} from './components/sdkOption';
3738
import {SignInNote} from './components/signInNote';
3839
import {SmartLink} from './components/smartLink';
@@ -56,6 +57,7 @@ export function mdxComponents(
5657
CodeTabs,
5758
ConfigKey,
5859
SdkOption,
60+
SdkApi,
5961
TableOfContents,
6062
CreateGitHubAppForm,
6163
ConfigValue,

0 commit comments

Comments
 (0)