From f8b3635f908289d9280d420f981d7474c3d811dd Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 11 Sep 2021 19:08:55 +0200 Subject: [PATCH 01/17] api-extractor: working docs mvp Signed-off-by: Patrik Oldsberg --- scripts/api-extractor.ts | 120 +++++++++++++++++++++++++++++++++++++++ tsdoc.json | 10 ++++ 2 files changed, 130 insertions(+) create mode 100644 tsdoc.json diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index ab5f063fb4..413d8e888e 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -31,8 +31,12 @@ import { CompilerState, ExtractorLogLevel, } from '@microsoft/api-extractor'; +import { DocNode, IDocNodeContainerParameters } from '@microsoft/tsdoc'; +import { TSDocConfigFile } from '@microsoft/tsdoc-config'; import { ApiPackage, ApiModel } from '@microsoft/api-extractor-model'; import { MarkdownDocumenter } from '@microsoft/api-documenter/lib/documenters/MarkdownDocumenter'; +import { CustomMarkdownEmitter } from '@microsoft/api-documenter/lib/markdown/CustomMarkdownEmitter'; +import { IMarkdownEmitterContext } from '@microsoft/api-documenter/lib/markdown/MarkdownEmitter'; const tmpDir = resolvePath(__dirname, '../node_modules/.cache/api-extractor'); @@ -150,6 +154,11 @@ async function runApiExtraction({ const projectFolder = resolvePath(__dirname, '..', packageDir); const packageFolder = resolvePath(__dirname, '../dist-types', packageDir); + const tsdocConf = TSDocConfigFile.loadFile( + resolvePath(__dirname, '../tsdoc.json'), + ); + tsdocConf.setSupportForTag('@component', true); + const extractorConfig = ExtractorConfig.prepare({ configObject: { mainEntryPointFilePath: resolvePath(packageFolder, 'src/index.d.ts'), @@ -211,6 +220,7 @@ async function runApiExtraction({ }, configObjectFullPath: projectFolder, packageJsonFullPath: resolvePath(projectFolder, 'package.json'), + tsdocConfigFile: tsdocConf, }); // The `packageFolder` needs to point to the location within `dist-types` in order for relative @@ -350,6 +360,116 @@ async function buildDocs({ outputFolder: outputDir, }); + class DocFrontMatter extends DocNode { + static kind = 'DocFrontMatter'; + + public readonly id: string; + public readonly title: string; + public readonly description: string; + + public constructor( + parameters: IDocNodeContainerParameters & { + id: string; + title: string; + description: string; + }, + ) { + super(parameters); + this.id = parameters.id; + this.title = parameters.title; + this.description = parameters.description; + } + + /** @override */ + public get kind(): string { + return DocFrontMatter.kind; + } + } + + const anyDocumenter = documenter as any; + + anyDocumenter._tsdocConfiguration.docNodeManager.registerDocNodes( + '@backstage/docs', + [{ docNodeKind: DocFrontMatter.kind, constructor: DocFrontMatter }], + ); + anyDocumenter._tsdocConfiguration.docNodeManager.registerAllowableChildren( + 'Paragraph', + [DocFrontMatter.kind], + ); + + class CustomCustomMarkdownEmitter extends CustomMarkdownEmitter { + /** @override */ + protected writeNode( + docNode: DocNode, + context: IMarkdownEmitterContext, + docNodeSiblings: boolean, + ): void { + switch (docNode.kind) { + case DocFrontMatter.kind: { + const node = docNode as DocFrontMatter; + context.writer.writeLine('---'); + context.writer.writeLine(`id: ${node.id}`); + context.writer.writeLine(`title: ${node.title}`); + context.writer.writeLine(`description: ${node.description}`); + context.writer.writeLine('---'); + context.writer.writeLine(); + break; + } + default: + super.writeNode(docNode, context, docNodeSiblings); + } + } + + /** @override */ + emit(stringBuilder, docNode, options) { + // Hack to get rid of the leading comment + stringBuilder._chunks.length = 0; + return super.emit(stringBuilder, docNode, options); + } + } + + const emitter = new CustomCustomMarkdownEmitter(newModel); + anyDocumenter._markdownEmitter = emitter; + + const oldWrite = anyDocumenter._writeBreadcrumb; + + anyDocumenter._writeBreadcrumb = function patchedWriteBreadcrumb( + output, + apiItem, + ) { + let title; + let description; + + const name = apiItem.getScopedNameWithinPackage(); + if (name) { + title = name; + description = `API reference for ${apiItem.getScopedNameWithinPackage()}`; + } else if (apiItem.kind === 'Model') { + title = 'Package Index'; + description = 'Index of all Backstage Packages'; + } else { + title = apiItem.name; + description = `API Reference for ${apiItem.name}`; + } + + output.appendNodeInParagraph( + new DocFrontMatter({ + configuration: this._tsdocConfiguration, + id: this._getFilenameForApiItem(apiItem).slice(0, -3), + title, + description, + }), + ); + + oldWrite.call(this, output, apiItem); + + // We wanna ignore the header that always gets written after the breadcrumb + const oldAppendNode = output.appendNode; + output.appendNode = () => { + output.appendNode = oldAppendNode; + }; + }; + documenter.generateFiles(); } diff --git a/tsdoc.json b/tsdoc.json new file mode 100644 index 0000000000..c19ba9f22b --- /dev/null +++ b/tsdoc.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"], + "tagDefinitions": [ + { + "tagName": "@component", + "syntaxKind": "modifier" + } + ] +} From e79b23d38bbf9a051873f137bca9d9e3e7b3c8fc Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 11 Sep 2021 19:10:16 +0200 Subject: [PATCH 02/17] api-extractor: drop special handling of @component Signed-off-by: Patrik Oldsberg --- scripts/api-extractor.ts | 16 +--------------- tsdoc.json | 10 ---------- 2 files changed, 1 insertion(+), 25 deletions(-) delete mode 100644 tsdoc.json diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index 413d8e888e..93e68a460a 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -32,7 +32,6 @@ import { ExtractorLogLevel, } from '@microsoft/api-extractor'; import { DocNode, IDocNodeContainerParameters } from '@microsoft/tsdoc'; -import { TSDocConfigFile } from '@microsoft/tsdoc-config'; import { ApiPackage, ApiModel } from '@microsoft/api-extractor-model'; import { MarkdownDocumenter } from '@microsoft/api-documenter/lib/documenters/MarkdownDocumenter'; import { CustomMarkdownEmitter } from '@microsoft/api-documenter/lib/markdown/CustomMarkdownEmitter'; @@ -154,11 +153,6 @@ async function runApiExtraction({ const projectFolder = resolvePath(__dirname, '..', packageDir); const packageFolder = resolvePath(__dirname, '../dist-types', packageDir); - const tsdocConf = TSDocConfigFile.loadFile( - resolvePath(__dirname, '../tsdoc.json'), - ); - tsdocConf.setSupportForTag('@component', true); - const extractorConfig = ExtractorConfig.prepare({ configObject: { mainEntryPointFilePath: resolvePath(packageFolder, 'src/index.d.ts'), @@ -220,7 +214,6 @@ async function runApiExtraction({ }, configObjectFullPath: projectFolder, packageJsonFullPath: resolvePath(projectFolder, 'package.json'), - tsdocConfigFile: tsdocConf, }); // The `packageFolder` needs to point to the location within `dist-types` in order for relative @@ -308,11 +301,6 @@ async function runApiExtraction({ } } -function isComponentMember(member: any) { - // React components are annotated with @component, and we want to skip those - return Boolean(member.docComment.match(/\n\s*\**\s*@component/m)); -} - async function buildDocs({ inputDir, outputDir, @@ -334,9 +322,7 @@ async function buildDocs({ const newModel = new ApiModel(); for (const serialized of serializedPackages) { - serialized.members[0].members = serialized.members[0].members.filter( - member => !isComponentMember(member), - ); + // Add any docs filtering logic here const pkg = ApiPackage.deserialize( serialized, diff --git a/tsdoc.json b/tsdoc.json deleted file mode 100644 index c19ba9f22b..0000000000 --- a/tsdoc.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", - "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"], - "tagDefinitions": [ - { - "tagName": "@component", - "syntaxKind": "modifier" - } - ] -} From 7da91310b0c0d454e4bec22cfd73dfab9625dc79 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 11 Sep 2021 19:21:50 +0200 Subject: [PATCH 03/17] api-extractor: document doc generation a bit Signed-off-by: Patrik Oldsberg --- scripts/api-extractor.ts | 44 ++++++++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index 93e68a460a..f53c46ddf2 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -301,6 +301,14 @@ async function runApiExtraction({ } } +/* +WARNING: Bring a blanket if you're gonna read the code below + +There's some weird shit going on here, and it's because we cba +forking rushstash to modify the api-documenter markdown generation, +which otherwise is the recommended way to do customizations. +*/ + async function buildDocs({ inputDir, outputDir, @@ -308,6 +316,8 @@ async function buildDocs({ inputDir: string; outputDir: string; }) { + // We start by constructing our own model from the files so that + // we get a change to modify them, as the model is otherwise read-only. const parseFile = async (filename: string): Promise => { console.log(`Reading ${filename}`); return fs.readJson(resolvePath(inputDir, filename)); @@ -331,9 +341,9 @@ async function buildDocs({ newModel.addMember(pkg); } - await fs.remove(outputDir); - await fs.ensureDir(outputDir); - + // This is root of the documentation generation, but it's not directly + // responsible for generating markdown, it just constructs an AST that + // is the consumed by an emitter to actually write the files. const documenter = new MarkdownDocumenter({ apiModel: newModel, documenterConfig: { @@ -346,6 +356,12 @@ async function buildDocs({ outputFolder: outputDir, }); + // We're accessing a lot of internal things... + const anyDocumenter = documenter as any; + + // The doc AST need to be extended with custom nodes if we want to + // add any extra content. + // This one is for the YAML front matter that we need for the microsite. class DocFrontMatter extends DocNode { static kind = 'DocFrontMatter'; @@ -372,8 +388,7 @@ async function buildDocs({ } } - const anyDocumenter = documenter as any; - + // It's a strict model, we gotta register the allowed usage of our new node anyDocumenter._tsdocConfiguration.docNodeManager.registerDocNodes( '@backstage/docs', [{ docNodeKind: DocFrontMatter.kind, constructor: DocFrontMatter }], @@ -383,6 +398,8 @@ async function buildDocs({ [DocFrontMatter.kind], ); + // This is where we actually write the markdown and where we can hook + // in the rendering of our own nodes. class CustomCustomMarkdownEmitter extends CustomMarkdownEmitter { /** @override */ protected writeNode( @@ -408,17 +425,22 @@ async function buildDocs({ /** @override */ emit(stringBuilder, docNode, options) { - // Hack to get rid of the leading comment + // Hack to get rid of the leading comment of each file, since + // we want the front matter to come first stringBuilder._chunks.length = 0; return super.emit(stringBuilder, docNode, options); } } - const emitter = new CustomCustomMarkdownEmitter(newModel); - anyDocumenter._markdownEmitter = emitter; + // The emitter is an internal thing, but it's fine to rewrite + anyDocumenter._markdownEmitter = new CustomCustomMarkdownEmitter(newModel); + // Gotta keep this around so we can call the real implementation const oldWrite = anyDocumenter._writeBreadcrumb; + // We don't really get many chances to modify the generated AST + // so we hook in wherever we can. In this case we add the front matter + // just before writing the breadcrumbs at the top. anyDocumenter._writeBreadcrumb = function patchedWriteBreadcrumb( output, apiItem, @@ -438,6 +460,7 @@ async function buildDocs({ description = `API Reference for ${apiItem.name}`; } + // Add our front matter output.appendNodeInParagraph( new DocFrontMatter({ configuration: this._tsdocConfiguration, @@ -447,15 +470,20 @@ async function buildDocs({ }), ); + // Now write the actual breadcrumbs oldWrite.call(this, output, apiItem); // We wanna ignore the header that always gets written after the breadcrumb + // This otherwise becomes more or less a duplicate of the title in the front matter const oldAppendNode = output.appendNode; output.appendNode = () => { output.appendNode = oldAppendNode; }; }; + // Clean up existing stuff and write ALL the docs! + await fs.remove(outputDir); + await fs.ensureDir(outputDir); documenter.generateFiles(); } From 6caa4df79b535b187edd2b312e1bc839ec2f0b63 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 11:42:17 +0200 Subject: [PATCH 04/17] api-extractor: switch to subclassing instead of monkey patching Signed-off-by: Patrik Oldsberg --- scripts/api-extractor.ts | 142 +++++++++++++++++++-------------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index f53c46ddf2..5e8393fc78 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -33,7 +33,10 @@ import { } from '@microsoft/api-extractor'; import { DocNode, IDocNodeContainerParameters } from '@microsoft/tsdoc'; import { ApiPackage, ApiModel } from '@microsoft/api-extractor-model'; -import { MarkdownDocumenter } from '@microsoft/api-documenter/lib/documenters/MarkdownDocumenter'; +import { + IMarkdownDocumenterOptions, + MarkdownDocumenter, +} from '@microsoft/api-documenter/lib/documenters/MarkdownDocumenter'; import { CustomMarkdownEmitter } from '@microsoft/api-documenter/lib/markdown/CustomMarkdownEmitter'; import { IMarkdownEmitterContext } from '@microsoft/api-documenter/lib/markdown/MarkdownEmitter'; @@ -341,24 +344,6 @@ async function buildDocs({ newModel.addMember(pkg); } - // This is root of the documentation generation, but it's not directly - // responsible for generating markdown, it just constructs an AST that - // is the consumed by an emitter to actually write the files. - const documenter = new MarkdownDocumenter({ - apiModel: newModel, - documenterConfig: { - outputTarget: 'markdown', - newlineKind: '\n', - // De ba dålig kod - configFilePath: '', - configFile: {}, - } as any, - outputFolder: outputDir, - }); - - // We're accessing a lot of internal things... - const anyDocumenter = documenter as any; - // The doc AST need to be extended with custom nodes if we want to // add any extra content. // This one is for the YAML front matter that we need for the microsite. @@ -388,16 +373,6 @@ async function buildDocs({ } } - // It's a strict model, we gotta register the allowed usage of our new node - anyDocumenter._tsdocConfiguration.docNodeManager.registerDocNodes( - '@backstage/docs', - [{ docNodeKind: DocFrontMatter.kind, constructor: DocFrontMatter }], - ); - anyDocumenter._tsdocConfiguration.docNodeManager.registerAllowableChildren( - 'Paragraph', - [DocFrontMatter.kind], - ); - // This is where we actually write the markdown and where we can hook // in the rendering of our own nodes. class CustomCustomMarkdownEmitter extends CustomMarkdownEmitter { @@ -432,54 +407,79 @@ async function buildDocs({ } } - // The emitter is an internal thing, but it's fine to rewrite - anyDocumenter._markdownEmitter = new CustomCustomMarkdownEmitter(newModel); + class CustomMarkdownDocumenter extends (MarkdownDocumenter as any) { + constructor(options: IMarkdownDocumenterOptions) { + super(options); - // Gotta keep this around so we can call the real implementation - const oldWrite = anyDocumenter._writeBreadcrumb; + // It's a strict model, we gotta register the allowed usage of our new node + this._tsdocConfiguration.docNodeManager.registerDocNodes( + '@backstage/docs', + [{ docNodeKind: DocFrontMatter.kind, constructor: DocFrontMatter }], + ); + this._tsdocConfiguration.docNodeManager.registerAllowableChildren( + 'Paragraph', + [DocFrontMatter.kind], + ); - // We don't really get many chances to modify the generated AST - // so we hook in wherever we can. In this case we add the front matter - // just before writing the breadcrumbs at the top. - anyDocumenter._writeBreadcrumb = function patchedWriteBreadcrumb( - output, - apiItem, - ) { - let title; - let description; - - const name = apiItem.getScopedNameWithinPackage(); - if (name) { - title = name; - description = `API reference for ${apiItem.getScopedNameWithinPackage()}`; - } else if (apiItem.kind === 'Model') { - title = 'Package Index'; - description = 'Index of all Backstage Packages'; - } else { - title = apiItem.name; - description = `API Reference for ${apiItem.name}`; + this._markdownEmitter = new CustomCustomMarkdownEmitter(newModel); } - // Add our front matter - output.appendNodeInParagraph( - new DocFrontMatter({ - configuration: this._tsdocConfiguration, - id: this._getFilenameForApiItem(apiItem).slice(0, -3), - title, - description, - }), - ); + // We don't really get many chances to modify the generated AST + // so we hook in wherever we can. In this case we add the front matter + // just before writing the breadcrumbs at the top. + /** @override */ + _writeBreadcrumb(output, apiItem) { + let title; + let description; - // Now write the actual breadcrumbs - oldWrite.call(this, output, apiItem); + const name = apiItem.getScopedNameWithinPackage(); + if (name) { + title = name; + description = `API reference for ${apiItem.getScopedNameWithinPackage()}`; + } else if (apiItem.kind === 'Model') { + title = 'Package Index'; + description = 'Index of all Backstage Packages'; + } else { + title = apiItem.name; + description = `API Reference for ${apiItem.name}`; + } - // We wanna ignore the header that always gets written after the breadcrumb - // This otherwise becomes more or less a duplicate of the title in the front matter - const oldAppendNode = output.appendNode; - output.appendNode = () => { - output.appendNode = oldAppendNode; - }; - }; + // Add our front matter + output.appendNodeInParagraph( + new DocFrontMatter({ + configuration: this._tsdocConfiguration, + id: this._getFilenameForApiItem(apiItem).slice(0, -3), + title, + description, + }), + ); + + // Now write the actual breadcrumbs + super._writeBreadcrumb(output, apiItem); + + // We wanna ignore the header that always gets written after the breadcrumb + // This otherwise becomes more or less a duplicate of the title in the front matter + const oldAppendNode = output.appendNode; + output.appendNode = () => { + output.appendNode = oldAppendNode; + }; + } + } + + // This is root of the documentation generation, but it's not directly + // responsible for generating markdown, it just constructs an AST that + // is the consumed by an emitter to actually write the files. + const documenter = new CustomMarkdownDocumenter({ + apiModel: newModel, + documenterConfig: { + outputTarget: 'markdown', + newlineKind: '\n', + // De ba dålig kod + configFilePath: '', + configFile: {}, + } as any, + outputFolder: outputDir, + }); // Clean up existing stuff and write ALL the docs! await fs.remove(outputDir); From 1a7340e1aef631b9ddd0c7af88f887c0e630947a Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 11:45:46 +0200 Subject: [PATCH 05/17] docs: clear out the reference folder Signed-off-by: Patrik Oldsberg --- docs/reference/.generated | 2 + docs/reference/createPlugin-feature-flags.md | 44 --- docs/reference/createPlugin.md | 41 --- docs/reference/utility-apis/AlertApi.md | 114 -------- docs/reference/utility-apis/AppThemeApi.md | 271 ------------------ .../utility-apis/BackstageIdentityApi.md | 100 ------- docs/reference/utility-apis/Config.md | 187 ------------ docs/reference/utility-apis/DiscoveryApi.md | 24 -- docs/reference/utility-apis/ErrorApi.md | 134 --------- .../reference/utility-apis/FeatureFlagsApi.md | 113 -------- docs/reference/utility-apis/IdentityApi.md | 81 ------ docs/reference/utility-apis/OAuthApi.md | 117 -------- .../reference/utility-apis/OAuthRequestApi.md | 233 --------------- .../utility-apis/OpenIdConnectApi.md | 75 ----- docs/reference/utility-apis/ProfileInfoApi.md | 104 ------- docs/reference/utility-apis/README.md | 202 ------------- docs/reference/utility-apis/SessionApi.md | 144 ---------- .../reference/utility-apis/SessionStateApi.md | 119 -------- docs/reference/utility-apis/StorageApi.md | 186 ------------ microsite/sidebars.json | 16 +- 20 files changed, 5 insertions(+), 2302 deletions(-) create mode 100644 docs/reference/.generated delete mode 100644 docs/reference/createPlugin-feature-flags.md delete mode 100644 docs/reference/createPlugin.md delete mode 100644 docs/reference/utility-apis/AlertApi.md delete mode 100644 docs/reference/utility-apis/AppThemeApi.md delete mode 100644 docs/reference/utility-apis/BackstageIdentityApi.md delete mode 100644 docs/reference/utility-apis/Config.md delete mode 100644 docs/reference/utility-apis/DiscoveryApi.md delete mode 100644 docs/reference/utility-apis/ErrorApi.md delete mode 100644 docs/reference/utility-apis/FeatureFlagsApi.md delete mode 100644 docs/reference/utility-apis/IdentityApi.md delete mode 100644 docs/reference/utility-apis/OAuthApi.md delete mode 100644 docs/reference/utility-apis/OAuthRequestApi.md delete mode 100644 docs/reference/utility-apis/OpenIdConnectApi.md delete mode 100644 docs/reference/utility-apis/ProfileInfoApi.md delete mode 100644 docs/reference/utility-apis/README.md delete mode 100644 docs/reference/utility-apis/SessionApi.md delete mode 100644 docs/reference/utility-apis/SessionStateApi.md delete mode 100644 docs/reference/utility-apis/StorageApi.md diff --git a/docs/reference/.generated b/docs/reference/.generated new file mode 100644 index 0000000000..e08947a827 --- /dev/null +++ b/docs/reference/.generated @@ -0,0 +1,2 @@ +The contents of this folder is generated by the root `yarn build:api-docs` command. +Don't put any additional content here as it will be overwritten during the microsite build. diff --git a/docs/reference/createPlugin-feature-flags.md b/docs/reference/createPlugin-feature-flags.md deleted file mode 100644 index d550ba10a9..0000000000 --- a/docs/reference/createPlugin-feature-flags.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: createPlugin-feature-flags -title: createPlugin - feature flags -description: Documentation on createPlugin - feature flags ---- - -The `featureFlags` object passed to the `register` function makes it possible -for plugins to register Feature Flags in Backstage for users to opt into. You -can use this to split out logic in your code for manual A/B testing, etc. - -Here's a code sample: - -```typescript -import { createPlugin } from '@backstage/core-plugin-api'; - -export default createPlugin({ - id: 'plugin-name', - register({ featureFlags }) { - featureFlags.register('enable-example-feature'); - }, -}); -``` - -## Using with useApi - -To inspect the state of a feature flag inside your plugin, you can use the -`FeatureFlagsApi`, accessed via the `featureFlagsApiRef`. For example: - -```tsx -import React from 'react'; -import { Button } from '@material-ui/core'; -import { featureFlagsApiRef, useApi } from '@backstage/core-plugin-api'; - -const ExamplePage = () => { - const featureFlags = useApi(featureFlagsApiRef); - - return ( -
- - { featureFlags.isActive('enable-example-feature') && } -
- ); -}; -``` diff --git a/docs/reference/createPlugin.md b/docs/reference/createPlugin.md deleted file mode 100644 index 6602b0b2cc..0000000000 --- a/docs/reference/createPlugin.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: createPlugin -title: createPlugin -description: Documentation on createPlugin ---- - -Takes a plugin config as an argument and returns a new plugin. - -## Plugin Config - -```typescript -function createPlugin(config: PluginConfig): BackstagePlugin; - -type PluginConfig = { - id: string; - register?(hooks: PluginHooks): void; -}; - -type PluginHooks = { - featureFlags: FeatureFlagsHooks; -}; -``` - -- [Read more about feature flags here](createPlugin-feature-flags.md) - -## Example Uses - -### Creating a basic plugin - -Showcasing adding a feature flag. - -```jsx -import { createPlugin } from '@backstage/core-plugin-api'; - -export default createPlugin({ - id: 'new-plugin', - register({ router, featureFlags }) { - featureFlags.register('enable-example-component'); - }, -}); -``` diff --git a/docs/reference/utility-apis/AlertApi.md b/docs/reference/utility-apis/AlertApi.md deleted file mode 100644 index 8d1851cc44..0000000000 --- a/docs/reference/utility-apis/AlertApi.md +++ /dev/null @@ -1,114 +0,0 @@ -# AlertApi - -The AlertApi type is defined at -[packages/core-api/src/apis/definitions/AlertApi.ts:29](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L29). - -The following Utility API implements this type: [alertApiRef](./README.md#alert) - -## Members - -### post() - -Post an alert for handling by the application. - -
-post(alert: AlertMessage): void
-
- -### alert\$() - -Observe alerts posted by other parts of the application. - -
-alert$(): Observable<AlertMessage>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### AlertMessage - -
-export type AlertMessage = {
-  message: string;
-  // Severity will default to success since that is what material ui defaults the value to.
-  severity?: 'success' | 'info' | 'warning' | 'error';
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/AlertApi.ts:19](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L19). - -Referenced by: [post](#post), [alert\$](#alert). - -### Observable - -Observable sequence of values and errors, see TC39. - -https://github.com/tc39/proposal-observable - -This is used as a common return type for observable values and can be created -using many different observable implementations, such as zen-observable or -RxJS 5. - -
-export type Observable<T> = {
-  /**
-   * Subscribes to this observable to start receiving new values.
-   */
-  subscribe(observer: Observer<T>): Subscription;
-  subscribe(
-    onNext: (value: T) => void,
-    onError?: (error: Error) => void,
-    onComplete?: () => void,
-  ): Subscription;
-}
-
- -Defined at -[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53). - -Referenced by: [alert\$](#alert). - -### Observer - -This file contains non-react related core types used throughout Backstage. - -Observer interface for consuming an Observer, see TC39. - -
-export type Observer<T> = {
-  next?(value: T): void;
-  error?(error: Error): void;
-  complete?(): void;
-}
-
- -Defined at -[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24). - -Referenced by: [Observable](#observable). - -### Subscription - -Subscription returned when subscribing to an Observable, see TC39. - -
-export type Subscription = {
-  /**
-   * Cancels the subscription
-   */
-  unsubscribe(): void;
-
-  /**
-   * Value indicating whether the subscription is closed.
-   */
-  readonly closed: Boolean;
-}
-
- -Defined at -[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33). - -Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/AppThemeApi.md b/docs/reference/utility-apis/AppThemeApi.md deleted file mode 100644 index a662b4cb70..0000000000 --- a/docs/reference/utility-apis/AppThemeApi.md +++ /dev/null @@ -1,271 +0,0 @@ -# AppThemeApi - -The AppThemeApi type is defined at -[packages/core-api/src/apis/definitions/AppThemeApi.ts:56](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L56). - -The following Utility API implements this type: -[appThemeApiRef](./README.md#apptheme) - -## Members - -### getInstalledThemes() - -Get a list of available themes. - -
-getInstalledThemes(): AppTheme[]
-
- -### activeThemeId\$() - -Observe the currently selected theme. A value of undefined means no specific -theme has been selected. - -
-activeThemeId$(): Observable<string | undefined>
-
- -### getActiveThemeId() - -Get the current theme ID. Returns undefined if no specific theme is selected. - -
-getActiveThemeId(): string | undefined
-
- -### setActiveThemeId() - -Set a specific theme to use in the app, overriding the default theme selection. - -Clear the selection by passing in undefined. - -
-setActiveThemeId(themeId?: string): void
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### AppTheme - -Describes a theme provided by the app. - -
-export type AppTheme = {
-  /**
-   * ID used to remember theme selections.
-   */
-  id: string;
-
-  /**
-   * Title of the theme
-   */
-  title: string;
-
-  /**
-   * Theme variant
-   */
-  variant: 'light' | 'dark';
-
-  /**
-   * The specialized MaterialUI theme instance.
-   */
-  theme: BackstageTheme;
-
-  /**
-   * An Icon for the theme mode setting.
-   */
-  icon?: React.ReactElement<SvgIconProps>;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/AppThemeApi.ts:25](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L25). - -Referenced by: [getInstalledThemes](#getinstalledthemes). - -### BackstagePalette - -
-export type BackstagePalette = Palette & PaletteAdditions
-
- -Defined at -[packages/theme/src/types.ts:74](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L74). - -Referenced by: [BackstageTheme](#backstagetheme). - -### BackstageTheme - -
-export interface BackstageTheme extends Theme {
-  palette: BackstagePalette;
-  page: PageTheme;
-  getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
-}
-
- -Defined at -[packages/theme/src/types.ts:81](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L81). - -Referenced by: [AppTheme](#apptheme). - -### Observable - -Observable sequence of values and errors, see TC39. - -https://github.com/tc39/proposal-observable - -This is used as a common return type for observable values and can be created -using many different observable implementations, such as zen-observable or -RxJS 5. - -
-export type Observable<T> = {
-  /**
-   * Subscribes to this observable to start receiving new values.
-   */
-  subscribe(observer: Observer<T>): Subscription;
-  subscribe(
-    onNext: (value: T) => void,
-    onError?: (error: Error) => void,
-    onComplete?: () => void,
-  ): Subscription;
-}
-
- -Defined at -[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53). - -Referenced by: [activeThemeId\$](#activethemeid). - -### Observer - -This file contains non-react related core types used throughout Backstage. - -Observer interface for consuming an Observer, see TC39. - -
-export type Observer<T> = {
-  next?(value: T): void;
-  error?(error: Error): void;
-  complete?(): void;
-}
-
- -Defined at -[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24). - -Referenced by: [Observable](#observable). - -### PageTheme - -
-export type PageTheme = {
-  colors: string[];
-  shape: string;
-  backgroundImage: string;
-}
-
- -Defined at -[packages/theme/src/types.ts:103](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L103). - -Referenced by: [BackstageTheme](#backstagetheme). - -### PageThemeSelector - -
-export type PageThemeSelector = {
-  themeId: string;
-}
-
- -Defined at -[packages/theme/src/types.ts:77](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L77). - -Referenced by: [BackstageTheme](#backstagetheme). - -### PaletteAdditions - -
-type PaletteAdditions = {
-  status: {
-    ok: string;
-    warning: string;
-    error: string;
-    pending: string;
-    running: string;
-    aborted: string;
-  };
-  border: string;
-  textContrast: string;
-  textVerySubtle: string;
-  textSubtle: string;
-  highlight: string;
-  errorBackground: string;
-  warningBackground: string;
-  infoBackground: string;
-  errorText: string;
-  infoText: string;
-  warningText: string;
-  linkHover: string;
-  link: string;
-  gold: string;
-  navigation: {
-    background: string;
-    indicator: string;
-    color: string;
-    selectedColor: string;
-  };
-  tabbar: {
-    indicator: string;
-  };
-  bursts: {
-    fontColor: string;
-    slackChannelText: string;
-    backgroundColor: {
-      default: string;
-    };
-  };
-  pinSidebarButton: {
-    icon: string;
-    background: string;
-  };
-  banner: {
-    info: string;
-    error: string;
-    text: string;
-    link: string;
-  };
-}
-
- -Defined at -[packages/theme/src/types.ts:23](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L23). - -Referenced by: [BackstagePalette](#backstagepalette). - -### Subscription - -Subscription returned when subscribing to an Observable, see TC39. - -
-export type Subscription = {
-  /**
-   * Cancels the subscription
-   */
-  unsubscribe(): void;
-
-  /**
-   * Value indicating whether the subscription is closed.
-   */
-  readonly closed: Boolean;
-}
-
- -Defined at -[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33). - -Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/BackstageIdentityApi.md b/docs/reference/utility-apis/BackstageIdentityApi.md deleted file mode 100644 index 80a40d427e..0000000000 --- a/docs/reference/utility-apis/BackstageIdentityApi.md +++ /dev/null @@ -1,100 +0,0 @@ -# BackstageIdentityApi - -The BackstageIdentityApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:134](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L134). - -The following Utility APIs implement this type: - -- [auth0AuthApiRef](./README.md#auth0auth) - -- [githubAuthApiRef](./README.md#githubauth) - -- [gitlabAuthApiRef](./README.md#gitlabauth) - -- [googleAuthApiRef](./README.md#googleauth) - -- [microsoftAuthApiRef](./README.md#microsoftauth) - -- [oauth2ApiRef](./README.md#oauth2) - -- [oidcAuthApiRef](./README.md#oidcauth) - -- [oktaAuthApiRef](./README.md#oktaauth) - -- [oneloginAuthApiRef](./README.md#oneloginauth) - -- [samlAuthApiRef](./README.md#samlauth) - -## Members - -### getBackstageIdentity() - -Get the user's identity within Backstage. This should normally not be called -directly, use the @IdentityApi instead. - -If the optional flag is not set, a session is guaranteed to be returned, while -if the optional flag is set, the session may be undefined. See -@AuthRequestOptions for more details. - -
-getBackstageIdentity(
-    options?: AuthRequestOptions,
-  ): Promise<BackstageIdentity | undefined>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### AuthRequestOptions - -
-export type AuthRequestOptions = {
-  /**
-   * If this is set to true, the user will not be prompted to log in,
-   * and an empty response will be returned if there is no existing session.
-   *
-   * This can be used to perform a check whether the user is logged in, or if you don't
-   * want to force a user to be logged in, but provide functionality if they already are.
-   *
-   * @default false
-   */
-  optional?: boolean;
-
-  /**
-   * If this is set to true, the request will bypass the regular oauth login modal
-   * and open the login popup directly.
-   *
-   * The method must be called synchronously from a user action for this to work in all browsers.
-   *
-   * @default false
-   */
-  instantPopup?: boolean;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40). - -Referenced by: [getBackstageIdentity](#getbackstageidentity). - -### BackstageIdentity - -
-export type BackstageIdentity = {
-  /**
-   * The backstage user ID.
-   */
-  id: string;
-
-  /**
-   * An ID token that can be used to authenticate the user within Backstage.
-   */
-  idToken: string;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:147](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L147). - -Referenced by: [getBackstageIdentity](#getbackstageidentity). diff --git a/docs/reference/utility-apis/Config.md b/docs/reference/utility-apis/Config.md deleted file mode 100644 index c5b20610e7..0000000000 --- a/docs/reference/utility-apis/Config.md +++ /dev/null @@ -1,187 +0,0 @@ -# Config - -The Config type is defined at -[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L32). - -The following Utility API implements this type: -[configApiRef](./README.md#config) - -## Members - -### has() - -
-has(key: string): boolean
-
- -### keys() - -
-keys(): string[]
-
- -### get() - -
-get(key?: string): JsonValue
-
- -### getOptional() - -
-getOptional(key?: string): JsonValue | undefined
-
- -### getConfig() - -
-getConfig(key: string): Config
-
- -### getOptionalConfig() - -
-getOptionalConfig(key: string): Config | undefined
-
- -### getConfigArray() - -
-getConfigArray(key: string): Config[]
-
- -### getOptionalConfigArray() - -
-getOptionalConfigArray(key: string): Config[] | undefined
-
- -### getNumber() - -
-getNumber(key: string): number
-
- -### getOptionalNumber() - -
-getOptionalNumber(key: string): number | undefined
-
- -### getBoolean() - -
-getBoolean(key: string): boolean
-
- -### getOptionalBoolean() - -
-getOptionalBoolean(key: string): boolean | undefined
-
- -### getString() - -
-getString(key: string): string
-
- -### getOptionalString() - -
-getOptionalString(key: string): string | undefined
-
- -### getStringArray() - -
-getStringArray(key: string): string[]
-
- -### getOptionalStringArray() - -
-getOptionalStringArray(key: string): string[] | undefined
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### Config - -
-export type Config = {
-  has(key: string): boolean;
-
-  keys(): string[];
-
-  get(key?: string): JsonValue;
-  getOptional(key?: string): JsonValue | undefined;
-
-  getConfig(key: string): Config;
-  getOptionalConfig(key: string): Config | undefined;
-
-  getConfigArray(key: string): Config[];
-  getOptionalConfigArray(key: string): Config[] | undefined;
-
-  getNumber(key: string): number;
-  getOptionalNumber(key: string): number | undefined;
-
-  getBoolean(key: string): boolean;
-  getOptionalBoolean(key: string): boolean | undefined;
-
-  getString(key: string): string;
-  getOptionalString(key: string): string | undefined;
-
-  getStringArray(key: string): string[];
-  getOptionalStringArray(key: string): string[] | undefined;
-}
-
- -Defined at -[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L32). - -Referenced by: [getConfig](#getconfig), [getOptionalConfig](#getoptionalconfig), -[getConfigArray](#getconfigarray), -[getOptionalConfigArray](#getoptionalconfigarray), [Config](#config). - -### JsonArray - -
-export type JsonArray = JsonValue[]
-
- -Defined at -[packages/config/src/types.ts:18](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L18). - -Referenced by: [JsonValue](#jsonvalue). - -### JsonObject - -
-export type JsonObject = { [key in string]?: JsonValue }
-
- -Defined at -[packages/config/src/types.ts:17](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L17). - -Referenced by: [JsonValue](#jsonvalue). - -### JsonValue - -
-export type JsonValue =
-  | JsonObject
-  | JsonArray
-  | number
-  | string
-  | boolean
-  | null
-
- -Defined at -[packages/config/src/types.ts:19](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L19). - -Referenced by: [get](#get), [getOptional](#getoptional), -[JsonObject](#jsonobject), [JsonArray](#jsonarray), [Config](#config). diff --git a/docs/reference/utility-apis/DiscoveryApi.md b/docs/reference/utility-apis/DiscoveryApi.md deleted file mode 100644 index 0d888c1daa..0000000000 --- a/docs/reference/utility-apis/DiscoveryApi.md +++ /dev/null @@ -1,24 +0,0 @@ -# DiscoveryApi - -The DiscoveryApi type is defined at -[packages/core-api/src/apis/definitions/DiscoveryApi.ts:30](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L30). - -The following Utility API implements this type: -[discoveryApiRef](./README.md#discovery) - -## Members - -### getBaseUrl() - -Returns the HTTP base backend URL for a given plugin, without a trailing slash. - -This method must always be called just before making a request, as opposed to -fetching the URL when constructing an API client. That is to ensure that more -flexible routing patterns can be supported. - -For example, asking for the URL for `auth` may return something like -`https://backstage.example.com/api/auth` - -
-getBaseUrl(pluginId: string): Promise<string>
-
diff --git a/docs/reference/utility-apis/ErrorApi.md b/docs/reference/utility-apis/ErrorApi.md deleted file mode 100644 index 1aaecdb47e..0000000000 --- a/docs/reference/utility-apis/ErrorApi.md +++ /dev/null @@ -1,134 +0,0 @@ -# ErrorApi - -The ErrorApi type is defined at -[packages/core-api/src/apis/definitions/ErrorApi.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L53). - -The following Utility API implements this type: [errorApiRef](./README.md#error) - -## Members - -### post() - -Post an error for handling by the application. - -
-post(error: Error, context?: ErrorContext): void
-
- -### error\$() - -Observe errors posted by other parts of the application. - -
-error$(): Observable<{ error: Error; context?: ErrorContext }>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### Error - -Mirrors the JavaScript Error class, for the purpose of providing documentation -and optional fields. - -
-type Error = {
-  name: string;
-  message: string;
-  stack?: string;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/ErrorApi.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L24). - -Referenced by: [post](#post), [error\$](#error). - -### ErrorContext - -Provides additional information about an error that was posted to the -application. - -
-export type ErrorContext = {
-  // If set to true, this error should not be displayed to the user. Defaults to false.
-  hidden?: boolean;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/ErrorApi.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L33). - -Referenced by: [post](#post), [error\$](#error). - -### Observable - -Observable sequence of values and errors, see TC39. - -https://github.com/tc39/proposal-observable - -This is used as a common return type for observable values and can be created -using many different observable implementations, such as zen-observable or -RxJS 5. - -
-export type Observable<T> = {
-  /**
-   * Subscribes to this observable to start receiving new values.
-   */
-  subscribe(observer: Observer<T>): Subscription;
-  subscribe(
-    onNext: (value: T) => void,
-    onError?: (error: Error) => void,
-    onComplete?: () => void,
-  ): Subscription;
-}
-
- -Defined at -[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53). - -Referenced by: [error\$](#error). - -### Observer - -This file contains non-react related core types used throughout Backstage. - -Observer interface for consuming an Observer, see TC39. - -
-export type Observer<T> = {
-  next?(value: T): void;
-  error?(error: Error): void;
-  complete?(): void;
-}
-
- -Defined at -[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24). - -Referenced by: [Observable](#observable). - -### Subscription - -Subscription returned when subscribing to an Observable, see TC39. - -
-export type Subscription = {
-  /**
-   * Cancels the subscription
-   */
-  unsubscribe(): void;
-
-  /**
-   * Value indicating whether the subscription is closed.
-   */
-  readonly closed: Boolean;
-}
-
- -Defined at -[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33). - -Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/FeatureFlagsApi.md b/docs/reference/utility-apis/FeatureFlagsApi.md deleted file mode 100644 index 1e8979c02e..0000000000 --- a/docs/reference/utility-apis/FeatureFlagsApi.md +++ /dev/null @@ -1,113 +0,0 @@ -# FeatureFlagsApi - -The FeatureFlagsApi type is defined at -[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:60](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L60). - -The following Utility API implements this type: -[featureFlagsApiRef](./README.md#featureflags) - -## Members - -### registerFlag() - -Registers a new feature flag. Once a feature flag has been registered it can be -toggled by users, and read back to enable or disable features. - -
-registerFlag(flag: FeatureFlag): void
-
- -### getRegisteredFlags() - -Get a list of all registered flags. - -
-getRegisteredFlags(): FeatureFlag[]
-
- -### isActive() - -Whether the feature flag with the given name is currently activated for the -user. - -
-isActive(name: string): boolean
-
- -### save() - -Save the user's choice of feature flag states. - -
-save(options: FeatureFlagsSaveOptions): void
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### FeatureFlag - -The feature flags API is used to toggle functionality to users across plugins -and Backstage. - -Plugins can use this API to register feature flags that they have available for -users to enable/disable, and this API will centralize the current user's state -of which feature flags they would like to enable. - -This is ideal for Backstage plugins, as well as your own App, to trial -incomplete or unstable upcoming features. Although there will be a common -interface for users to enable and disable feature flags, this API acts as -another way to enable/disable. - -
-export type FeatureFlag = {
-  name: string;
-  pluginId: string;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L31). - -Referenced by: [registerFlag](#registerflag), -[getRegisteredFlags](#getregisteredflags). - -### FeatureFlagState - -
-export enum FeatureFlagState {
-  None = 0,
-  Active = 1,
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:36](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L36). - -Referenced by: [FeatureFlagsSaveOptions](#featureflagssaveoptions). - -### FeatureFlagsSaveOptions - -Options to use when saving feature flags. - -
-export type FeatureFlagsSaveOptions = {
-  /**
-   * The new feature flag states to save.
-   */
-  states: Record<string, FeatureFlagState>;
-
-  /**
-   * Whether the saves states should be merged into the existing ones, or replace them.
-   *
-   * Defaults to false.
-   */
-  merge?: boolean;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:44](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L44). - -Referenced by: [save](#save). diff --git a/docs/reference/utility-apis/IdentityApi.md b/docs/reference/utility-apis/IdentityApi.md deleted file mode 100644 index aa2a4dd9a0..0000000000 --- a/docs/reference/utility-apis/IdentityApi.md +++ /dev/null @@ -1,81 +0,0 @@ -# IdentityApi - -The IdentityApi type is defined at -[packages/core-api/src/apis/definitions/IdentityApi.ts:22](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/IdentityApi.ts#L22). - -The following Utility API implements this type: -[identityApiRef](./README.md#identity) - -## Members - -### getUserId() - -The ID of the signed in user. This ID is not meant to be presented to the user, -but used as an opaque string to pass on to backends or use in frontend logic. - -TODO: The intention of the user ID is to be able to tie the user to an identity -that is known by the catalog and/or identity backend. It should for example be -possible to fetch all owned components using this ID. - -
-getUserId(): string
-
- -### getProfile() - -The profile of the signed in user. - -
-getProfile(): ProfileInfo
-
- -### getIdToken() - -An OpenID Connect ID Token which proves the identity of the signed in user. - -The ID token will be undefined if the signed in user does not have a verified -identity, such as a demo user or mocked user for e2e tests. - -
-getIdToken(): Promise<string | undefined>
-
- -### signOut() - -Sign out the current user - -
-signOut(): Promise<void>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### ProfileInfo - -Profile information of the user. - -
-export type ProfileInfo = {
-  /**
-   * Email ID.
-   */
-  email?: string;
-
-  /**
-   * Display name that can be presented to the user.
-   */
-  displayName?: string;
-
-  /**
-   * URL to an avatar image of the user.
-   */
-  picture?: string;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L162). - -Referenced by: [getProfile](#getprofile). diff --git a/docs/reference/utility-apis/OAuthApi.md b/docs/reference/utility-apis/OAuthApi.md deleted file mode 100644 index 9af6b3bb53..0000000000 --- a/docs/reference/utility-apis/OAuthApi.md +++ /dev/null @@ -1,117 +0,0 @@ -# OAuthApi - -The OAuthApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:67](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L67). - -The following Utility APIs implement this type: - -- [githubAuthApiRef](./README.md#githubauth) - -- [gitlabAuthApiRef](./README.md#gitlabauth) - -- [googleAuthApiRef](./README.md#googleauth) - -- [microsoftAuthApiRef](./README.md#microsoftauth) - -- [oauth2ApiRef](./README.md#oauth2) - -- [oidcAuthApiRef](./README.md#oidcauth) - -- [oktaAuthApiRef](./README.md#oktaauth) - -- [oneloginAuthApiRef](./README.md#oneloginauth) - -## Members - -### getAccessToken() - -Requests an OAuth 2 Access Token, optionally with a set of scopes. The access -token allows you to make requests on behalf of the user, and the copes may grant -you broader access, depending on the auth provider. - -Each auth provider has separate handling of scope, so you need to look at the -documentation for each one to know what scope you need to request. - -This method is cheap and should be called each time an access token is used. Do -not for example store the access token in React component state, as that could -cause the token to expire. Instead fetch a new access token for each request. - -Be sure to include all required scopes when requesting an access token. When -testing your implementation it is best to log out the Backstage session and then -visit your plugin page directly, as you might already have some required scopes -in your existing session. Not requesting the correct scopes can lead to 403 or -other authorization errors, which can be tricky to debug. - -If the user has not yet granted access to the provider and the set of requested -scopes, the user will be prompted to log in. The returned promise will not -resolve until the user has successfully logged in. The returned promise can be -rejected, but only if the user rejects the login request. - -
-getAccessToken(
-    scope?: OAuthScope,
-    options?: AuthRequestOptions,
-  ): Promise<string>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### AuthRequestOptions - -
-export type AuthRequestOptions = {
-  /**
-   * If this is set to true, the user will not be prompted to log in,
-   * and an empty response will be returned if there is no existing session.
-   *
-   * This can be used to perform a check whether the user is logged in, or if you don't
-   * want to force a user to be logged in, but provide functionality if they already are.
-   *
-   * @default false
-   */
-  optional?: boolean;
-
-  /**
-   * If this is set to true, the request will bypass the regular oauth login modal
-   * and open the login popup directly.
-   *
-   * The method must be called synchronously from a user action for this to work in all browsers.
-   *
-   * @default false
-   */
-  instantPopup?: boolean;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40). - -Referenced by: [getAccessToken](#getaccesstoken). - -### OAuthScope - -This file contains declarations for common interfaces of auth-related APIs. The -declarations should be used to signal which type of authentication and -authorization methods each separate auth provider supports. - -For example, a Google OAuth provider that supports OAuth 2 and OpenID Connect, -would be declared as follows: - -const googleAuthApiRef = createApiRef({ ... }) - -An array of scopes, or a scope string formatted according to the auth provider, -which is typically a space separated list. - -See the documentation for each auth provider for the list of scopes supported by -each provider. - -
-export type OAuthScope = string | string[]
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:38](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L38). - -Referenced by: [getAccessToken](#getaccesstoken). diff --git a/docs/reference/utility-apis/OAuthRequestApi.md b/docs/reference/utility-apis/OAuthRequestApi.md deleted file mode 100644 index 5f521cf288..0000000000 --- a/docs/reference/utility-apis/OAuthRequestApi.md +++ /dev/null @@ -1,233 +0,0 @@ -# OAuthRequestApi - -The OAuthRequestApi type is defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:99](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L99). - -The following Utility API implements this type: -[oauthRequestApiRef](./README.md#oauthrequest) - -## Members - -### createAuthRequester() - -A utility for showing login popups or similar things, and merging together -multiple requests for different scopes into one request that includes all -scopes. - -The passed in options provide information about the login provider, and how to -handle auth requests. - -The returned AuthRequester function is used to request login with new scopes. -These requests are merged together and forwarded to the auth handler, as soon as -a consumer of auth requests triggers an auth flow. - -See AuthRequesterOptions, AuthRequester, and handleAuthRequests for more info. - -
-createAuthRequester<AuthResponse>(
-    options: AuthRequesterOptions<AuthResponse>,
-  ): AuthRequester<AuthResponse>
-
- -### authRequest\$() - -Observers pending auth requests. The returned observable will emit all current -active auth request, at most one for each created auth requester. - -Each request has its own info about the login provider, forwarded from the auth -requester options. - -Depending on user interaction, the request should either be rejected, or used to -trigger the auth handler. If the request is rejected, all pending AuthRequester -calls will fail with a "RejectedError". If a auth is triggered, and the auth -handler resolves successfully, then all currently pending AuthRequester calls -will resolve to the value returned by the onAuthRequest call. - -
-authRequest$(): Observable<PendingAuthRequest[]>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### AuthProvider - -Information about the auth provider that we're requesting a login towards. - -This should be shown to the user so that they can be informed about what login -is being requested before a popup is shown. - -
-export type AuthProvider = {
-  /**
-   * Title for the auth provider, for example "GitHub"
-   */
-  title: string;
-
-  /**
-   * Icon for the auth provider.
-   */
-  icon: IconComponent;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:27](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L27). - -Referenced by: [AuthRequesterOptions](#authrequesteroptions), -[PendingAuthRequest](#pendingauthrequest). - -### AuthRequester - -Function used to trigger new auth requests for a set of scopes. - -The returned promise will resolve to the same value returned by the -onAuthRequest in the AuthRequesterOptions. Or rejected, if the request is -rejected. - -This function can be called multiple times before the promise resolves. All -calls will be merged into one request, and the scopes forwarded to the -onAuthRequest will be the union of all requested scopes. - -
-export type AuthRequester<AuthResponse> = (
-  scopes: Set<string>,
-) => Promise<AuthResponse>
-
- -Defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:66](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L66). - -Referenced by: [createAuthRequester](#createauthrequester). - -### AuthRequesterOptions - -Describes how to handle auth requests. Both how to show them to the user, and -what to do when the user accesses the auth request. - -
-export type AuthRequesterOptions<AuthResponse> = {
-  /**
-   * Information about the auth provider, which will be forwarded to auth requests.
-   */
-  provider: AuthProvider;
-
-  /**
-   * Implementation of the auth flow, which will be called synchronously when
-   * trigger() is called on an auth requests.
-   */
-  onAuthRequest(scopes: Set<string>): Promise<AuthResponse>;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:43](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L43). - -Referenced by: [createAuthRequester](#createauthrequester). - -### Observable - -Observable sequence of values and errors, see TC39. - -https://github.com/tc39/proposal-observable - -This is used as a common return type for observable values and can be created -using many different observable implementations, such as zen-observable or -RxJS 5. - -
-export type Observable<T> = {
-  /**
-   * Subscribes to this observable to start receiving new values.
-   */
-  subscribe(observer: Observer<T>): Subscription;
-  subscribe(
-    onNext: (value: T) => void,
-    onError?: (error: Error) => void,
-    onComplete?: () => void,
-  ): Subscription;
-}
-
- -Defined at -[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53). - -Referenced by: [authRequest\$](#authrequest). - -### Observer - -This file contains non-react related core types used throughout Backstage. - -Observer interface for consuming an Observer, see TC39. - -
-export type Observer<T> = {
-  next?(value: T): void;
-  error?(error: Error): void;
-  complete?(): void;
-}
-
- -Defined at -[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24). - -Referenced by: [Observable](#observable). - -### PendingAuthRequest - -An pending auth request for a single auth provider. The request will remain in -this pending state until either reject() or trigger() is called. - -Any new requests for the same provider are merged into the existing pending -request, meaning there will only ever be a single pending request for a given -provider. - -
-export type PendingAuthRequest = {
-  /**
-   * Information about the auth provider, as given in the AuthRequesterOptions
-   */
-  provider: AuthProvider;
-
-  /**
-   * Rejects the request, causing all pending AuthRequester calls to fail with "RejectedError".
-   */
-  reject: () => void;
-
-  /**
-   * Trigger the auth request to continue the auth flow, by for example showing a popup.
-   *
-   * Synchronously calls onAuthRequest with all scope currently in the request.
-   */
-  trigger(): Promise<void>;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:77](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L77). - -Referenced by: [authRequest\$](#authrequest). - -### Subscription - -Subscription returned when subscribing to an Observable, see TC39. - -
-export type Subscription = {
-  /**
-   * Cancels the subscription
-   */
-  unsubscribe(): void;
-
-  /**
-   * Value indicating whether the subscription is closed.
-   */
-  readonly closed: Boolean;
-}
-
- -Defined at -[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33). - -Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/OpenIdConnectApi.md b/docs/reference/utility-apis/OpenIdConnectApi.md deleted file mode 100644 index 6d05af6189..0000000000 --- a/docs/reference/utility-apis/OpenIdConnectApi.md +++ /dev/null @@ -1,75 +0,0 @@ -# OpenIdConnectApi - -The OpenIdConnectApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:99](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L99). - -The following Utility APIs implement this type: - -- [auth0AuthApiRef](./README.md#auth0auth) - -- [googleAuthApiRef](./README.md#googleauth) - -- [microsoftAuthApiRef](./README.md#microsoftauth) - -- [oauth2ApiRef](./README.md#oauth2) - -- [oidcAuthApiRef](./README.md#oidcauth) - -- [oktaAuthApiRef](./README.md#oktaauth) - -- [oneloginAuthApiRef](./README.md#oneloginauth) - -## Members - -### getIdToken() - -Requests an OpenID Connect ID Token. - -This method is cheap and should be called each time an ID token is used. Do not -for example store the id token in React component state, as that could cause the -token to expire. Instead fetch a new id token for each request. - -If the user has not yet logged in to Google inside Backstage, the user will be -prompted to log in. The returned promise will not resolve until the user has -successfully logged in. The returned promise can be rejected, but only if the -user rejects the login request. - -
-getIdToken(options?: AuthRequestOptions): Promise<string>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### AuthRequestOptions - -
-export type AuthRequestOptions = {
-  /**
-   * If this is set to true, the user will not be prompted to log in,
-   * and an empty response will be returned if there is no existing session.
-   *
-   * This can be used to perform a check whether the user is logged in, or if you don't
-   * want to force a user to be logged in, but provide functionality if they already are.
-   *
-   * @default false
-   */
-  optional?: boolean;
-
-  /**
-   * If this is set to true, the request will bypass the regular oauth login modal
-   * and open the login popup directly.
-   *
-   * The method must be called synchronously from a user action for this to work in all browsers.
-   *
-   * @default false
-   */
-  instantPopup?: boolean;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40). - -Referenced by: [getIdToken](#getidtoken). diff --git a/docs/reference/utility-apis/ProfileInfoApi.md b/docs/reference/utility-apis/ProfileInfoApi.md deleted file mode 100644 index 1a2f94d031..0000000000 --- a/docs/reference/utility-apis/ProfileInfoApi.md +++ /dev/null @@ -1,104 +0,0 @@ -# ProfileInfoApi - -The ProfileInfoApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:117](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L117). - -The following Utility APIs implement this type: - -- [auth0AuthApiRef](./README.md#auth0auth) - -- [githubAuthApiRef](./README.md#githubauth) - -- [gitlabAuthApiRef](./README.md#gitlabauth) - -- [googleAuthApiRef](./README.md#googleauth) - -- [microsoftAuthApiRef](./README.md#microsoftauth) - -- [oauth2ApiRef](./README.md#oauth2) - -- [oidcAuthApiRef](./README.md#oidcauth) - -- [oktaAuthApiRef](./README.md#oktaauth) - -- [oneloginAuthApiRef](./README.md#oneloginauth) - -- [samlAuthApiRef](./README.md#samlauth) - -## Members - -### getProfile() - -Get profile information for the user as supplied by this auth provider. - -If the optional flag is not set, a session is guaranteed to be returned, while -if the optional flag is set, the session may be undefined. See -@AuthRequestOptions for more details. - -
-getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### AuthRequestOptions - -
-export type AuthRequestOptions = {
-  /**
-   * If this is set to true, the user will not be prompted to log in,
-   * and an empty response will be returned if there is no existing session.
-   *
-   * This can be used to perform a check whether the user is logged in, or if you don't
-   * want to force a user to be logged in, but provide functionality if they already are.
-   *
-   * @default false
-   */
-  optional?: boolean;
-
-  /**
-   * If this is set to true, the request will bypass the regular oauth login modal
-   * and open the login popup directly.
-   *
-   * The method must be called synchronously from a user action for this to work in all browsers.
-   *
-   * @default false
-   */
-  instantPopup?: boolean;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40). - -Referenced by: [getProfile](#getprofile). - -### ProfileInfo - -Profile information of the user. - -
-export type ProfileInfo = {
-  /**
-   * Email ID.
-   */
-  email?: string;
-
-  /**
-   * Display name that can be presented to the user.
-   */
-  displayName?: string;
-
-  /**
-   * URL to an avatar image of the user.
-   */
-  picture?: string;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L162). - -Referenced by: [getProfile](#getprofile). diff --git a/docs/reference/utility-apis/README.md b/docs/reference/utility-apis/README.md deleted file mode 100644 index aefbb4b925..0000000000 --- a/docs/reference/utility-apis/README.md +++ /dev/null @@ -1,202 +0,0 @@ -# Backstage Core Utility APIs - -The following is a list of all Utility APIs defined by `@backstage/core`. They -are available to use by plugins and components, and can be accessed using the -`useApi` hook, also provided by `@backstage/core`. For more information, see -https://github.com/backstage/backstage/blob/master/docs/api/utility-apis.md. - -### alert - -Used to report alerts and forward them to the app - -Implemented type: [AlertApi](./AlertApi.md) - -ApiRef: -[alertApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L41) - -### appTheme - -API Used to configure the app theme, and enumerate options - -Implemented type: [AppThemeApi](./AppThemeApi.md) - -ApiRef: -[appThemeApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L80) - -### auth0Auth - -Provides authentication towards Auth0 APIs - -Implemented types: [OpenIdConnectApi](./OpenIdConnectApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[auth0AuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L275) - -### config - -Used to access runtime configuration - -Implemented type: [Config](./Config.md) - -ApiRef: -[configApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ConfigApi.ts#L25) - -### discovery - -Provides service discovery of backend plugins - -Implemented type: [DiscoveryApi](./DiscoveryApi.md) - -ApiRef: -[discoveryApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L44) - -### error - -Used to report errors and forward them to the app - -Implemented type: [ErrorApi](./ErrorApi.md) - -ApiRef: -[errorApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L65) - -### featureFlags - -Used to toggle functionality in features across Backstage - -Implemented type: [FeatureFlagsApi](./FeatureFlagsApi.md) - -ApiRef: -[featureFlagsApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L83) - -### githubAuth - -Provides authentication towards GitHub APIs - -Implemented types: [OAuthApi](./OAuthApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[githubAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L232) - -### gitlabAuth - -Provides authentication towards GitLab APIs - -Implemented types: [OAuthApi](./OAuthApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[gitlabAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L262) - -### googleAuth - -Provides authentication towards Google APIs and identities - -Implemented types: [OAuthApi](./OAuthApi.md), -[OpenIdConnectApi](./OpenIdConnectApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[googleAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L215) - -### identity - -Provides access to the identity of the signed in user - -Implemented type: [IdentityApi](./IdentityApi.md) - -ApiRef: -[identityApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/IdentityApi.ts#L53) - -### microsoftAuth - -Provides authentication towards Microsoft APIs and identities - -Implemented types: [OAuthApi](./OAuthApi.md), -[OpenIdConnectApi](./OpenIdConnectApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[microsoftAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L289) - -### oauth2 - -Example of how to use oauth2 custom provider - -Implemented types: [OAuthApi](./OAuthApi.md), -[OpenIdConnectApi](./OpenIdConnectApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[oauth2ApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L303) - -### oauthRequest - -An API for implementing unified OAuth flows in Backstage - -Implemented type: [OAuthRequestApi](./OAuthRequestApi.md) - -ApiRef: -[oauthRequestApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130) - -### oidcAuth - -Example of how to use oidc custom provider - -Implemented types: [OAuthApi](./OAuthApi.md), -[OpenIdConnectApi](./OpenIdConnectApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[oidcAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L317) - -### oktaAuth - -Provides authentication towards Okta APIs - -Implemented types: [OAuthApi](./OAuthApi.md), -[OpenIdConnectApi](./OpenIdConnectApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[oktaAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L245) - -### oneloginAuth - -Provides authentication towards OneLogin APIs and identities - -Implemented types: [OAuthApi](./OAuthApi.md), -[OpenIdConnectApi](./OpenIdConnectApi.md), -[ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[oneloginAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L338) - -### samlAuth - -Example of how to use SAML custom provider - -Implemented types: [ProfileInfoApi](./ProfileInfoApi.md), -[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) - -ApiRef: -[samlAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L331) - -### storage - -Provides the ability to store data which is unique to the user - -Implemented type: [StorageApi](./StorageApi.md) - -ApiRef: -[storageApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L68) diff --git a/docs/reference/utility-apis/SessionApi.md b/docs/reference/utility-apis/SessionApi.md deleted file mode 100644 index 4b584d92c8..0000000000 --- a/docs/reference/utility-apis/SessionApi.md +++ /dev/null @@ -1,144 +0,0 @@ -# SessionApi - -The SessionApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:190](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L190). - -The following Utility APIs implement this type: - -- [auth0AuthApiRef](./README.md#auth0auth) - -- [githubAuthApiRef](./README.md#githubauth) - -- [gitlabAuthApiRef](./README.md#gitlabauth) - -- [googleAuthApiRef](./README.md#googleauth) - -- [microsoftAuthApiRef](./README.md#microsoftauth) - -- [oauth2ApiRef](./README.md#oauth2) - -- [oidcAuthApiRef](./README.md#oidcauth) - -- [oktaAuthApiRef](./README.md#oktaauth) - -- [oneloginAuthApiRef](./README.md#oneloginauth) - -- [samlAuthApiRef](./README.md#samlauth) - -## Members - -### signIn() - -Sign in with a minimum set of permissions. - -
-signIn(): Promise<void>
-
- -### signOut() - -Sign out from the current session. This will reload the page. - -
-signOut(): Promise<void>
-
- -### sessionState\$() - -Observe the current state of the auth session. Emits the current state on -subscription. - -
-sessionState$(): Observable<SessionState>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### Observable - -Observable sequence of values and errors, see TC39. - -https://github.com/tc39/proposal-observable - -This is used as a common return type for observable values and can be created -using many different observable implementations, such as zen-observable or -RxJS 5. - -
-export type Observable<T> = {
-  /**
-   * Subscribes to this observable to start receiving new values.
-   */
-  subscribe(observer: Observer<T>): Subscription;
-  subscribe(
-    onNext: (value: T) => void,
-    onError?: (error: Error) => void,
-    onComplete?: () => void,
-  ): Subscription;
-}
-
- -Defined at -[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53). - -Referenced by: [sessionState\$](#sessionstate). - -### Observer - -This file contains non-react related core types used throughout Backstage. - -Observer interface for consuming an Observer, see TC39. - -
-export type Observer<T> = {
-  next?(value: T): void;
-  error?(error: Error): void;
-  complete?(): void;
-}
-
- -Defined at -[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24). - -Referenced by: [Observable](#observable). - -### SessionState - -Session state values passed to subscribers of the SessionApi. - -
-export enum SessionState {
-  SignedIn = 'SignedIn',
-  SignedOut = 'SignedOut',
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:182](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L182). - -Referenced by: [sessionState\$](#sessionstate). - -### Subscription - -Subscription returned when subscribing to an Observable, see TC39. - -
-export type Subscription = {
-  /**
-   * Cancels the subscription
-   */
-  unsubscribe(): void;
-
-  /**
-   * Value indicating whether the subscription is closed.
-   */
-  readonly closed: Boolean;
-}
-
- -Defined at -[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33). - -Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/SessionStateApi.md b/docs/reference/utility-apis/SessionStateApi.md deleted file mode 100644 index a8a4c3bc3d..0000000000 --- a/docs/reference/utility-apis/SessionStateApi.md +++ /dev/null @@ -1,119 +0,0 @@ -# SessionStateApi - -The SessionStateApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:201](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L201). - -The following Utility APIs implement this type: - -- [auth0AuthApiRef](./README.md#auth0auth) - -- [githubAuthApiRef](./README.md#githubauth) - -- [gitlabAuthApiRef](./README.md#gitlabauth) - -- [googleAuthApiRef](./README.md#googleauth) - -- [microsoftAuthApiRef](./README.md#microsoftauth) - -- [oauth2ApiRef](./README.md#oauth2) - -- [oktaAuthApiRef](./README.md#oktaauth) - -## Members - -### sessionState\$() - -
-sessionState$(): Observable<SessionState>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### Observable - -Observable sequence of values and errors, see TC39. - -https://github.com/tc39/proposal-observable - -This is used as a common return type for observable values and can be created -using many different observable implementations, such as zen-observable or -RxJS 5. - -
-export type Observable<T> = {
-  /**
-   * Subscribes to this observable to start receiving new values.
-   */
-  subscribe(observer: Observer<T>): Subscription;
-  subscribe(
-    onNext: (value: T) => void,
-    onError?: (error: Error) => void,
-    onComplete?: () => void,
-  ): Subscription;
-}
-
- -Defined at -[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L53). - -Referenced by: [sessionState\$](#sessionstate). - -### Observer - -This file contains non-react related core types used through Backstage. - -Observer interface for consuming an Observer, see TC39. - -
-export type Observer<T> = {
-  next?(value: T): void;
-  error?(error: Error): void;
-  complete?(): void;
-}
-
- -Defined at -[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L24). - -Referenced by: [Observable](#observable). - -### SessionState - -Session state values passed to subscribers of the SessionStateApi. - -
-export enum SessionState {
-  SignedIn = 'SignedIn',
-  SignedOut = 'SignedOut',
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/auth.ts:192](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L192). - -Referenced by: [sessionState\$](#sessionstate). - -### Subscription - -Subscription returned when subscribing to an Observable, see TC39. - -
-export type Subscription = {
-  /**
-   * Cancels the subscription
-   */
-  unsubscribe(): void;
-
-  /**
-   * Value indicating whether the subscription is closed.
-   */
-  readonly closed: Boolean;
-}
-
- -Defined at -[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L33). - -Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/StorageApi.md b/docs/reference/utility-apis/StorageApi.md deleted file mode 100644 index 3247d28f60..0000000000 --- a/docs/reference/utility-apis/StorageApi.md +++ /dev/null @@ -1,186 +0,0 @@ -# StorageApi - -The StorageApi type is defined at -[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L31). - -The following Utility API implements this type: -[storageApiRef](./README.md#storage) - -## Members - -### forBucket() - -Create a bucket to store data in. - -
-forBucket(name: string): StorageApi
-
- -### get() - -Get the current value for persistent data, use observe\$ to be notified of -updates. - -
-get<T>(key: string): T | undefined
-
- -### remove() - -Remove persistent data. - -
-remove(key: string): Promise<void>
-
- -### set() - -Save persistent data, and emit messages to anyone that is using observe\$ for -this key - -
-set(key: string, data: any): Promise<void>
-
- -### observe\$() - -Observe changes on a particular key in the bucket - -
-observe$<T>(key: string): Observable<StorageValueChange<T>>
-
- -## Supporting types - -These types are part of the API declaration, but may not be unique to this API. - -### Observable - -Observable sequence of values and errors, see TC39. - -https://github.com/tc39/proposal-observable - -This is used as a common return type for observable values and can be created -using many different observable implementations, such as zen-observable or -RxJS 5. - -
-export type Observable<T> = {
-  /**
-   * Subscribes to this observable to start receiving new values.
-   */
-  subscribe(observer: Observer<T>): Subscription;
-  subscribe(
-    onNext: (value: T) => void,
-    onError?: (error: Error) => void,
-    onComplete?: () => void,
-  ): Subscription;
-}
-
- -Defined at -[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53). - -Referenced by: [observe\$](#observe), [StorageApi](#storageapi). - -### Observer - -This file contains non-react related core types used throughout Backstage. - -Observer interface for consuming an Observer, see TC39. - -
-export type Observer<T> = {
-  next?(value: T): void;
-  error?(error: Error): void;
-  complete?(): void;
-}
-
- -Defined at -[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24). - -Referenced by: [Observable](#observable). - -### StorageApi - -
-export interface StorageApi {
-  /**
-   * Create a bucket to store data in.
-   * @param {String} name Namespace for the storage to be stored under,
-   *                      will inherit previous namespaces too
-   */
-  forBucket(name: string): StorageApi;
-
-  /**
-   * Get the current value for persistent data, use observe$ to be notified of updates.
-   *
-   * @param {String} key Unique key associated with the data.
-   * @return {Object} data The data that should is stored.
-   */
-  get<T>(key: string): T | undefined;
-
-  /**
-   * Remove persistent data.
-   *
-   * @param {String} key Unique key associated with the data.
-   */
-  remove(key: string): Promise<void>;
-
-  /**
-   * Save persistent data, and emit messages to anyone that is using observe$ for this key
-   *
-   * @param {String} key Unique key associated with the data.
-   */
-  set(key: string, data: any): Promise<void>;
-
-  /**
-   * Observe changes on a particular key in the bucket
-   * @param {String} key Unique key associated with the data
-   */
-  observe$<T>(key: string): Observable<StorageValueChange<T>>;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L31). - -Referenced by: [forBucket](#forbucket). - -### StorageValueChange - -
-export type StorageValueChange<T = any> = {
-  key: string;
-  newValue?: T;
-}
-
- -Defined at -[packages/core-api/src/apis/definitions/StorageApi.ts:21](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L21). - -Referenced by: [observe\$](#observe), [StorageApi](#storageapi). - -### Subscription - -Subscription returned when subscribing to an Observable, see TC39. - -
-export type Subscription = {
-  /**
-   * Cancels the subscription
-   */
-  unsubscribe(): void;
-
-  /**
-   * Value indicating whether the subscription is closed.
-   */
-  readonly closed: Boolean;
-}
-
- -Defined at -[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33). - -Referenced by: [Observable](#observable). diff --git a/microsite/sidebars.json b/microsite/sidebars.json index d200b615f1..dc8aa516cf 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -234,21 +234,11 @@ "dls/contributing-to-storybook", "dls/figma" ], - "API references": [ + "API Reference": [ { "type": "subcategory", - "label": "TypeScript API", - "ids": [ - "api/utility-apis", - "reference/utility-apis/README", - "reference/createPlugin", - "reference/createPlugin-feature-flags" - ] - }, - { - "type": "subcategory", - "label": "Backend APIs", - "ids": ["api/backend"] + "label": "Guides", + "ids": [ "api/utility-apis" ] } ], "Tutorials": [ From 5e0c8cdaaa0f3d55e6228daf12fad2d856e3a263 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 11:47:58 +0200 Subject: [PATCH 06/17] root: bump api-extractor deps and add missing explicit tsdoc dep Signed-off-by: Patrik Oldsberg --- package.json | 7 +++--- yarn.lock | 70 ++++++++++++++++++++++++++-------------------------- 2 files changed, 39 insertions(+), 38 deletions(-) diff --git a/package.json b/package.json index c9a33f78e6..ea930b060f 100644 --- a/package.json +++ b/package.json @@ -54,9 +54,10 @@ }, "version": "1.0.0", "dependencies": { - "@microsoft/api-documenter": "^7.13.30", - "@microsoft/api-extractor": "^7.18.1", - "@microsoft/api-extractor-model": "^7.13.3" + "@microsoft/api-documenter": "^7.13.47", + "@microsoft/api-extractor": "^7.18.7", + "@microsoft/api-extractor-model": "^7.13.5", + "@microsoft/tsdoc": "^0.13.2" }, "devDependencies": { "@types/webpack": "^5.28.0", diff --git a/yarn.lock b/yarn.lock index 1d408ff5ae..5c7c1b0235 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4540,45 +4540,45 @@ resolved "https://registry.npmjs.org/@mdx-js/util/-/util-1.6.22.tgz#219dfd89ae5b97a8801f015323ffa4b62f45718b" integrity sha512-H1rQc1ZOHANWBvPcW+JpGwr+juXSxM8Q8YCkm3GhZd8REu1fHR3z99CErO1p9pkcfcxZnMdIZdIsXkOHY0NilA== -"@microsoft/api-documenter@^7.13.30": - version "7.13.30" - resolved "https://registry.npmjs.org/@microsoft/api-documenter/-/api-documenter-7.13.30.tgz#f4832b8747ad9f61b3a0d87eb61b6b1aca2aeb60" - integrity sha512-n91XihJptwcHp1g5FUIcrjDXhg/g2q6+Rj+nuPBkvsCAKQP/OwCLNVO3tYNpz+qa+lWrHPWL3Urc8G3th5cn7w== +"@microsoft/api-documenter@^7.13.47": + version "7.13.47" + resolved "https://registry.npmjs.org/@microsoft/api-documenter/-/api-documenter-7.13.47.tgz#0b7726634232b37f76c0e5e8353cdbb5b52d4ece" + integrity sha512-jk78Pf8cKL2WZf6CkKUUtwegdsTA1Jf0MfIzD50qpG7T257HLrqCi1t70ZA85VpRLR8oSeNHMayqNTWkdku9iA== dependencies: - "@microsoft/api-extractor-model" "7.13.3" + "@microsoft/api-extractor-model" "7.13.5" "@microsoft/tsdoc" "0.13.2" - "@rushstack/node-core-library" "3.39.0" - "@rushstack/ts-command-line" "4.8.0" + "@rushstack/node-core-library" "3.40.0" + "@rushstack/ts-command-line" "4.9.0" colors "~1.2.1" js-yaml "~3.13.1" resolve "~1.17.0" -"@microsoft/api-extractor-model@7.13.3", "@microsoft/api-extractor-model@^7.13.3": - version "7.13.3" - resolved "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.13.3.tgz#ac01c064c5af520d3661c85d7e5ef95e1ca8ab92" - integrity sha512-uXilAhu2GcvyY/0NwVRk3AN7TFYjkPnjHLV2UywTTz9uglS+Af0YjNrCy+aaK8qXtfbFWdBzkH9N2XU8/YBeRQ== +"@microsoft/api-extractor-model@7.13.5", "@microsoft/api-extractor-model@^7.13.5": + version "7.13.5" + resolved "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.13.5.tgz#7836a81ba47b9a654062ed0361e4eee69afae51e" + integrity sha512-il6AebNltYo5hEtqXZw4DMvrwBPn6+F58TxwqmsLY+U+sSJNxaYn2jYksArrjErXVPR3gUgRMqD6zsdIkg+WEQ== dependencies: "@microsoft/tsdoc" "0.13.2" "@microsoft/tsdoc-config" "~0.15.2" - "@rushstack/node-core-library" "3.39.0" + "@rushstack/node-core-library" "3.40.0" -"@microsoft/api-extractor@^7.18.1": - version "7.18.1" - resolved "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.18.1.tgz#61b39f972b646261dd49f2de9f5d448aa6497e7a" - integrity sha512-qljUF2Q0zAx1vJrjKkJVGN7OVbsXki+Pji99jywyl6L/FK3YZ7PpstUJYE6uBcLPy6rhNPWPAsHNTMpG/kHIsg== +"@microsoft/api-extractor@^7.18.7": + version "7.18.7" + resolved "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.18.7.tgz#851d2413a3c5d696f7cc914eb59de7a7882b2e8b" + integrity sha512-JhtV8LoyLuIecbgCPyZQg08G1kngIRWpai2UzwNil9mGVGYiDZVeeKx8c2phmlPcogmMDm4oQROxyuiYt5sJiw== dependencies: - "@microsoft/api-extractor-model" "7.13.3" + "@microsoft/api-extractor-model" "7.13.5" "@microsoft/tsdoc" "0.13.2" "@microsoft/tsdoc-config" "~0.15.2" - "@rushstack/node-core-library" "3.39.0" - "@rushstack/rig-package" "0.2.12" - "@rushstack/ts-command-line" "4.8.0" + "@rushstack/node-core-library" "3.40.0" + "@rushstack/rig-package" "0.3.0" + "@rushstack/ts-command-line" "4.9.0" colors "~1.2.1" lodash "~4.17.15" resolve "~1.17.0" semver "~7.3.0" source-map "~0.6.1" - typescript "~4.3.2" + typescript "~4.3.5" "@microsoft/fetch-event-source@2.0.1": version "2.0.1" @@ -4600,7 +4600,7 @@ jju "~1.4.0" resolve "~1.19.0" -"@microsoft/tsdoc@0.13.2": +"@microsoft/tsdoc@0.13.2", "@microsoft/tsdoc@^0.13.2": version "0.13.2" resolved "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.13.2.tgz#3b0efb6d3903bd49edb073696f60e90df08efb26" integrity sha512-WrHvO8PDL8wd8T2+zBGKrMwVL5IyzR3ryWUsl0PXgEV0QHup4mTLi0QcATefGI6Gx9Anu7vthPyyyLpY0EpiQg== @@ -5217,10 +5217,10 @@ estree-walker "^2.0.1" picomatch "^2.2.2" -"@rushstack/node-core-library@3.39.0": - version "3.39.0" - resolved "https://registry.npmjs.org/@rushstack/node-core-library/-/node-core-library-3.39.0.tgz#38928946d15ae89b773386cf97433d0d1ec83b93" - integrity sha512-kgu3+7/zOBkZU0+NdJb1rcHcpk3/oTjn5c8cg5nUTn+JDjEw58yG83SoeJEcRNNdl11dGX0lKG2PxPsjCokZOQ== +"@rushstack/node-core-library@3.40.0": + version "3.40.0" + resolved "https://registry.npmjs.org/@rushstack/node-core-library/-/node-core-library-3.40.0.tgz#2551915ea34e34ec2abb7172b9d7f4546144d9d4" + integrity sha512-P6uMPI7cqTdawLSPAG5BQrBu1MHlGRPqecp7ruIRgyukIEzkmh0QAnje4jAL/l1r3hw0qe4e+Dz5ZSnukT/Egg== dependencies: "@types/node" "10.17.13" colors "~1.2.1" @@ -5232,18 +5232,18 @@ timsort "~0.3.0" z-schema "~3.18.3" -"@rushstack/rig-package@0.2.12": - version "0.2.12" - resolved "https://registry.npmjs.org/@rushstack/rig-package/-/rig-package-0.2.12.tgz#c434d62b28e0418a040938226f8913971d0424c7" - integrity sha512-nbePcvF8hQwv0ql9aeQxcaMPK/h1OLAC00W7fWCRWIvD2MchZOE8jumIIr66HGrfG2X1sw++m/ZYI4D+BM5ovQ== +"@rushstack/rig-package@0.3.0": + version "0.3.0" + resolved "https://registry.npmjs.org/@rushstack/rig-package/-/rig-package-0.3.0.tgz#334ad2846797861361b3445d4cc9ae9164b1885c" + integrity sha512-Lj6noF7Q4BBm1hKiBDw94e6uZvq1xlBwM/d2cBFaPqXeGdV+G6r3qaCWfRiSXK0pcHpGGpV5Tb2MdfhVcO6G/g== dependencies: resolve "~1.17.0" strip-json-comments "~3.1.1" -"@rushstack/ts-command-line@4.8.0": - version "4.8.0" - resolved "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.8.0.tgz#611accb931b9ac62ff4d078f68f95c47f6606724" - integrity sha512-nZ8cbzVF1VmFPfSJfy8vEohdiFAH/59Y/Y+B4nsJbn4SkifLJ8LqNZ5+LxCC2UR242EXFumxlsY1d6fPBxck5Q== +"@rushstack/ts-command-line@4.9.0": + version "4.9.0" + resolved "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.9.0.tgz#781ba42cff73cae097b6d5241b6441e7cc2fe6e0" + integrity sha512-kmT8t+JfnvphISF1C5WwY56RefjwgajhSjs9J4ckvAFXZDXR6F5cvF5/RTh7fGCzIomg8esy2PHO/b52zFoZvA== dependencies: "@types/argparse" "1.0.38" argparse "~1.0.9" @@ -26334,7 +26334,7 @@ typescript@^4.0.3, typescript@~4.2.3: resolved "https://registry.npmjs.org/typescript/-/typescript-4.2.4.tgz#8610b59747de028fda898a8aef0e103f156d0961" integrity sha512-V+evlYHZnQkaz8TRBuxTA92yZBPotr5H+WhQ7bD3hZUndx5tGOa1fuCgeSjxAzM1RiN5IzvadIXTVefuuwZCRg== -typescript@~4.3.2: +typescript@~4.3.5: version "4.3.5" resolved "https://registry.npmjs.org/typescript/-/typescript-4.3.5.tgz#4d1c37cc16e893973c45a06886b7113234f119f4" integrity sha512-DqQgihaQ9cUrskJo9kIyW/+g0Vxsk8cDtZ52a3NGh0YNTfpUSArXSohyUGnvbPazEPLu398C0UxmKSOrPumUzA== From 575d8bd9f25ed8ea5a8d3d8c9b002e18a6f57f13 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 12:00:12 +0200 Subject: [PATCH 07/17] build api reference as part of the microsite Signed-off-by: Patrik Oldsberg --- .github/workflows/microsite-with-storybook-deploy.yml | 9 +++------ docs/.gitignore | 1 + microsite/sidebars.json | 7 ++++++- 3 files changed, 10 insertions(+), 7 deletions(-) create mode 100644 docs/.gitignore diff --git a/.github/workflows/microsite-with-storybook-deploy.yml b/.github/workflows/microsite-with-storybook-deploy.yml index e8886b7d6b..47e18340eb 100644 --- a/.github/workflows/microsite-with-storybook-deploy.yml +++ b/.github/workflows/microsite-with-storybook-deploy.yml @@ -4,12 +4,6 @@ on: push: branches: - master - paths: - - '.github/workflows/microsite-with-storybook-deploy.yml' - - 'packages/storybook/**' - - 'packages/core-components/src/**' - - 'microsite/**' - - 'docs/**' jobs: deploy-microsite-and-storybook: @@ -41,6 +35,9 @@ jobs: run: yarn install --frozen-lockfile working-directory: microsite + - name: build API reference + run: yarn build:api-docs + - name: build microsite run: yarn build working-directory: microsite diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..c757205e4c --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +reference/*.md diff --git a/microsite/sidebars.json b/microsite/sidebars.json index dc8aa516cf..d0d77e9b59 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -238,7 +238,12 @@ { "type": "subcategory", "label": "Guides", - "ids": [ "api/utility-apis" ] + "ids": ["api/utility-apis"] + }, + { + "type": "subcategory", + "label": "API Reference", + "ids": ["reference/index"] } ], "Tutorials": [ From cf06e3881b94854384648fd41d6e1c25cc04ab2a Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 12:19:24 +0200 Subject: [PATCH 08/17] docs/api/utility-apis: links out to api reference Signed-off-by: Patrik Oldsberg --- docs/api/utility-apis.md | 177 +++++++++++++++++++++++---------------- 1 file changed, 106 insertions(+), 71 deletions(-) diff --git a/docs/api/utility-apis.md b/docs/api/utility-apis.md index f04202b79b..1a1e29c19c 100644 --- a/docs/api/utility-apis.md +++ b/docs/api/utility-apis.md @@ -12,25 +12,32 @@ however always be a need for plugins to communicate outside of its boundaries, both with other plugins and the app itself. Backstage provides two primary methods for plugins to communicate across their -boundaries in client-side code. The first one being the `createPlugin` API and -the registration hooks passed to the `register` method, and the second one being -Utility APIs. While the `createPlugin` API is focused on the initialization -plugins and the app, the Utility APIs provide ways for plugins to communicate -during their entire life cycle. +boundaries in client-side code. The first one being the +[createPlugin](../reference/core-plugin-api.createPlugin.md) API along with the +extensions that it can provide, and the second one being Utility APIs. While the +[createPlugin](../reference/core-plugin-api.createPlugin.md) API is focused on +the initialization plugins and the app, the Utility APIs provide ways for +plugins to communicate during their entire life cycle. ## Consuming APIs -Each Utility API is tied to an `ApiRef` instance, which is a global singleton -object without any additional state or functionality, its only purpose is to -reference Utility APIs. `ApiRef`s are created using `createApiRef`, which is -exported by `@backstage/core-plugin-api`. There are many -[predefined Utility APIs](../reference/utility-apis/README.md) defined in -`@backstage/core-plugin-api`, and they're all exported with a name of the -pattern `*ApiRef`, for example `errorApiRef`. +Each Utility API is tied to an [ApiRef](../reference/core-plugin-api.ApiRef.md) +instance, which is a global singleton object without any additional state or +functionality, its only purpose is to reference Utility APIs. +[ApiRef](../reference/core-plugin-api.ApiRef.md)s are created using +[createApiRef](../reference/core-plugin-api.createApiRef.md), which is exported +by [@backstage/core-plugin-api](../reference/core-plugin-api.md). There are also +many predefined Utility APIs in +[@backstage/core-plugin-api](../reference/core-plugin-api.md), and they're all +exported with a name of the pattern `*ApiRef`, for example +[errorApiRef](../reference/core-plugin-api.errorApiRef.md). -To access one of the Utility APIs inside a React component, use the `useApi` -hook exported by `@backstage/core-plugin-api`, or the `withApis` HOC if you -prefer class components. For example, the `ErrorApi` can be accessed like this: +To access one of the Utility APIs inside a React component, use the +[useApi](../reference/core-plugin-api.useApi.md) hook exported by +[@backstage/core-plugin-api](../reference/core-plugin-api.md), or the +[withApis](../reference/core-plugin-api.withApis.md) HOC if you prefer class +components. For example, the +[ErrorApi](../reference/core-plugin-api.ErrorApi.md) can be accessed like this: ```tsx import React from 'react'; @@ -48,24 +55,31 @@ export const MyComponent = () => { }; ``` -Note that there is no explicit type given for `ErrorApi`. This is because the -`errorApiRef` has the type embedded, and `useApi` is able to infer the type. +Note that there is no explicit type given for +[ErrorApi](../reference/core-plugin-api.ErrorApi.md). This is because the +[errorApiRef](../reference/core-plugin-api.errorApiRef.md) has the type +embedded, and [useApi](../reference/core-plugin-api.useApi.md) is able to infer +the type. Also note that consuming Utility APIs is not limited to plugins, it can be done from any component inside Backstage, including the ones in -`@backstage/core-plugin-api`. The only requirement is that they are beneath the -`AppProvider` in the react tree. +[@backstage/core-plugin-api](../reference/core-plugin-api.md). The only +requirement is that they are beneath the `AppProvider` in the react tree. ## Supplying APIs ### API Factories -APIs are registered in the form of `ApiFactories`, which encapsulate the process -of instantiating an API. It is a collection of three things: the `ApiRef` of the -API to instantiate, a list of all required dependencies, and a factory function -that returns a new API instance. +APIs are registered in the form of +[ApiFactories](../reference/core-plugin-api.ApiFactory.md), which encapsulate +the process of instantiating an API. It is a collection of three things: the +[ApiRef](../reference/core-plugin-api.ApiRef.md) of the API to instantiate, a +list of all required dependencies, and a factory function that returns a new API +instance. -For example, this is the default `ApiFactory` for the `ErrorApi`: +For example, this is the default +[ApiFactory](../reference/core-plugin-api.ApiFactory.md) for the +[ErrorApi](../reference/core-plugin-api.ErrorApi.md): ```ts createApiFactory({ @@ -79,18 +93,25 @@ createApiFactory({ }); ``` -In this example the `errorApiRef` is our API, which encapsulates the `ErrorApi` -type. The `alertApiRef` is our single dependency, which we give the name -`alertApi`, and is then passed on to the factory function, which returns an -implementation of the `ErrorApi`. +In this example the [errorApiRef](../reference/core-plugin-api.errorApiRef.md) +is our API, which encapsulates the +[ErrorApi](../reference/core-plugin-api.ErrorApi.md) type. The +[alertApiRef](../reference/core-plugin-api.alertApiRef.md) is our single +dependency, which we give the name `alertApi`, and is then passed on to the +factory function, which returns an implementation of the +[ErrorApi](../reference/core-plugin-api.ErrorApi.md). -The `createApiFactory` function is a thin wrapper that enables TypeScript type -inference. You may notice that there are no type annotations in the above -example, and that is because we're able to infer all types from the `ApiRef`s. -TypeScript will make sure that the return value of the `factory` function -matches the type embedded in `api`'s `ApiRef`, in this case the `ErrorApi`. It -will also match the types between the `deps` and the parameters of the `factory` -function, again using the type embedded within the `ApiRef`s. +The [createApiFactory](../reference/core-plugin-api.createApiFactory.md) +function is a thin wrapper that enables TypeScript type inference. You may +notice that there are no type annotations in the above example, and that is +because we're able to infer all types from the +[ApiRef](../reference/core-plugin-api.ApiRef.md)s. TypeScript will make sure +that the return value of the `factory` function matches the type embedded in +`api`'s [ApiRef](../reference/core-plugin-api.ApiRef.md), in this case the +[ErrorApi](../reference/core-plugin-api.ErrorApi.md). It will also match the +types between the `deps` and the parameters of the `factory` function, again +using the type embedded within the +[ApiRef](../reference/core-plugin-api.ApiRef.md)s. ## Registering API Factories @@ -102,24 +123,27 @@ app, and the app itself. Starting with the Backstage core library, it provides implementations for all of the core APIs. The core APIs are the ones exported by -`@backstage/core-plugin-api`, such as the `errorApiRef` and `configApiRef`. You -can find a full list of them [here](../reference/utility-apis/README.md). +[@backstage/core-plugin-api](../reference/core-plugin-api.md), such as the +[errorApiRef](../reference/core-plugin-api.errorApiRef.md) and +[configApiRef](../reference/core-plugin-api.configApiRef.md). -The core APIs are loaded for any app created with `createApp` from -`@backstage/core-plugin-api`, which means that there is no step that needs to be -taken to include these APIs in an app. +The core APIs are loaded for any app created with +[createApp](../reference/core-app-api.createApp.md) from +[@backstage/core-plugin-api](../reference/core-plugin-api.md), which means that +there is no step that needs to be taken to include these APIs in an app. ### Plugin APIs In addition to the core APIs, plugins can define and export their own APIs. While doing so they should usually also provide default implementations of their own APIs, for example, the `catalog` plugin exports `catalogApiRef`, and also -supplies a default `ApiFactory` of that API using the `CatalogClient`. There is -one restriction to plugin-provided API Factories: plugins may not supply -factories for core APIs, trying to do so will cause the app to refuse to start. +supplies a default [ApiFactory](../reference/core-plugin-api.ApiFactory.md) of +that API using the `CatalogClient`. There is one restriction to plugin-provided +API Factories: plugins may not supply factories for core APIs, trying to do so +will cause the app to refuse to start. -Plugins supply their APIs through the `apis` option of `createPlugin`, for -example: +Plugins supply their APIs through the `apis` option of +[createPlugin](../reference/core-plugin-api.createPlugin.md), for example: ```ts export const techdocsPlugin = createPlugin({ @@ -144,7 +168,8 @@ Lastly, the app itself is the final point where APIs can be added, and what has the final say in what APIs will be loaded at runtime. The app may override the factories for any of the core or plugin APIs, with the exception of the config, app theme, and identity APIs. These are static APIs that are tied into the -`createApp` implementation, and therefore not possible to override. +[createApp](../reference/core-app-api.createApp.md) implementation, and +therefore not possible to override. Overriding APIs is useful for apps that want to switch out behavior to tailor it to their environment. In some cases plugins may also export multiple @@ -206,16 +231,19 @@ const app = createApp({ ``` Note that the above line will cause an error if `IgnoreErrorApi` does not fully -implement the `ErrorApi`, as it is checked by the type embedded in the -`errorApiRef` at compile time. +implement the [ErrorApi](../reference/core-plugin-api.ErrorApi.md), as it is +checked by the type embedded in the +[errorApiRef](../reference/core-plugin-api.errorApiRef.md) at compile time. ## Defining custom Utility APIs Plugins are free to define their own Utility APIs. Simply define the TypeScript -interface for the API, and create an `ApiRef` using `createApiRef` exported from -`@backstage/core-plugin-api`. Also be sure to provide at least one -implementation of the API, and to declare a default factory for the API in -`createPlugin`. +interface for the API, and create an +[ApiRef](../reference/core-plugin-api.ApiRef.md) using +[createApiRef](../reference/core-plugin-api.createApiRef.md) exported from +[@backstage/core-plugin-api](../reference/core-plugin-api.md). Also be sure to +provide at least one implementation of the API, and to declare a default factory +for the API in [createPlugin](../reference/core-plugin-api.createPlugin.md). Custom Utility APIs can be either public or private, which is up to the plugin to choose. Private APIs do not expose an external API surface, and it's @@ -226,15 +254,18 @@ plugin to override the API in the app. It is however important to maintain backwards compatibility of public APIs, as you may otherwise break apps that are using your plugin. -To make an API public, simply export the `ApiRef` of the API, and any associated -types. To make an API private, just avoid exporting the `ApiRef`, but still be -sure to supply a default factory to `createPlugin`. +To make an API public, simply export the +[ApiRef](../reference/core-plugin-api.ApiRef.md) of the API, and any associated +types. To make an API private, just avoid exporting the +[ApiRef](../reference/core-plugin-api.ApiRef.md), but still be sure to supply a +default factory to [createPlugin](../reference/core-plugin-api.createPlugin.md). Private APIs are useful for plugins that want to depend on other APIs outside of React components, but not have to expose an entire API surface to maintain. When using private APIs, it is fine to use the `typeof` of an implementing class as -the type parameter passed to `createApiRef`, while public APIs should always -define a separate TypeScript interface type. +the type parameter passed to +[createApiRef](../reference/core-plugin-api.createApiRef.md), while public APIs +should always define a separate TypeScript interface type. Plugins may depend on APIs from other plugins, both in React components and as dependencies to API factories. Do however be sure to not cause circular @@ -242,13 +273,14 @@ dependencies between plugins. ## Architecture -The `ApiRef` instances mentioned above provide a point of indirection between -consumers and producers of Utility APIs. It allows for plugins and components to -depend on APIs in a type-safe way, without having a direct reference to a -concrete implementation of the APIs. The Apps are also given a lot of -flexibility in what implementations to provide. As long as they adhere to the -contract established by an `ApiRef`, they are free to choose any implementation -they want. +The [ApiRef](../reference/core-plugin-api.ApiRef.md) instances mentioned above +provide a point of indirection between consumers and producers of Utility APIs. +It allows for plugins and components to depend on APIs in a type-safe way, +without having a direct reference to a concrete implementation of the APIs. The +Apps are also given a lot of flexibility in what implementations to provide. As +long as they adhere to the contract established by an +[ApiRef](../reference/core-plugin-api.ApiRef.md), they are free to choose any +implementation they want. The figure below shows the relationship between different Apps, that provide @@ -271,14 +303,17 @@ directly tied to React. The indirection provided by Utility APIs also makes it straightforward to test components that depend on APIs, and to provide a standard common development environment for plugins. A proper test wrapper with mocked API implementations -is not yet ready, but it will be provided as a part of `@backstage/test-utils`. -It will provide mocked variants of APIs, with additional methods for asserting a -component's interaction with the API. +is not yet ready, but it will be provided as a part of +[@backstage/test-utils](../reference/test-utils.md). It will provide mocked +variants of APIs, with additional methods for asserting a component's +interaction with the API. The common development environment for plugins is included in -`@backstage/dev-utils`, where the exported `createDevApp` function creates an +[@backstage/dev-utils](../reference/dev-utils.md), where the exported +[createDevApp](../reference/dev-utils.createDevApp.md) function creates an application with implementations for all core APIs already present. Contrary to the method for wiring up Utility API implementations in an app created with -`createApp`, `createDevApp` uses automatic dependency injection. This is to make -it possible to replace any API implementation, and having that be reflected in -dependents of that API. +[createApp](../reference/core-app-api.createApp.md), +[createDevApp](../reference/dev-utils.createDevApp.md) uses automatic dependency +injection. This is to make it possible to replace any API implementation, and +having that be reflected in dependents of that API. From 8d30e0ec048180fe07d30dfcdb2c1d54dc48690b Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 12:24:05 +0200 Subject: [PATCH 09/17] docs: remove references to removed utility API docs Signed-off-by: Patrik Oldsberg --- docs/auth/index.md | 5 ++--- docs/auth/using-auth.md | 3 ++- docs/conf/reading.md | 4 ++-- mkdocs.yml | 9 ++------- 4 files changed, 8 insertions(+), 13 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index 76cd79b0fd..0c03e33900 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -60,9 +60,8 @@ small update to show this provider as a login option. The `SignInPage` component handles this, and takes either a `provider` or `providers` (array) prop of `SignInProviderConfig` definitions. -These reference the [ApiRef](../reference/utility-apis/README.md) exported by -the provider. Again, an example using GitHub that can be adapted to any of the -built-in providers: +These reference the `ApiRef` exported by the provider. Again, an example using +GitHub that can be adapted to any of the built-in providers: ```diff # packages/app/src/App.tsx diff --git a/docs/auth/using-auth.md b/docs/auth/using-auth.md index e4f87a12f9..067c43e8a0 100644 --- a/docs/auth/using-auth.md +++ b/docs/auth/using-auth.md @@ -28,7 +28,8 @@ OAuth helps in that regard. The method with which frontend plugins request access to third party services is through [Utility APIs](../api/utility-apis.md) for each service provider. For a full list of providers, see the -[Utility API References](../reference/utility-apis/README.md). +[@backstage/core-plugin-api](../reference/core-plugin-api.md#variables) +reference. ### Identity - WIP diff --git a/docs/conf/reading.md b/docs/conf/reading.md index d492723e3d..4568f4c378 100644 --- a/docs/conf/reading.md +++ b/docs/conf/reading.md @@ -7,7 +7,7 @@ description: Documentation on Reading Backstage Configuration ## Config API There's a common configuration API for by both frontend and backend plugins. An -API reference can be found [here](../reference/utility-apis/Config.md). +API reference can be found [here](../reference/config.Config.md). The configuration API is tailored towards failing fast in case of missing or bad config. That's because configuration errors can always be considered programming @@ -110,7 +110,7 @@ example `getString`. These will throw an error if there is no value available. ## Accessing ConfigApi in Frontend Plugins -The [ConfigApi](../reference/utility-apis/Config.md) in the frontend is a +The [ConfigApi](../reference/core-plugin-api.ConfigApi.md) in the frontend is a [UtilityApi](../api/utility-apis.md). It's accessible as usual via the `configApiRef` exported from `@backstage/core-plugin-api`: diff --git a/mkdocs.yml b/mkdocs.yml index bddce144d3..3ffd4aa97d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -156,14 +156,9 @@ nav: - Design: 'dls/design.md' - Contributing to Storybook: 'dls/contributing-to-storybook.md' - Figma: 'dls/figma.md' - - API references: - - TypeScript API: + - API Reference: + - Guides: - Utility APIs: 'api/utility-apis.md' - - reference/utility-apis/README: 'reference/utility-apis/README.md' - - createPlugin: 'reference/createPlugin.md' - - createPlugin -feature flags: 'reference/createPlugin-feature-flags.md' - - Backend APIs: - - Backend: 'api/backend.md' - Tutorials: - Future developer journey: 'tutorials/journey.md' - Migrating away from @backstage/core: 'tutorials/migrating-away-from-core.md' From 2485ea499db2c3cebc2ad078f2c917673140931f Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 12:25:09 +0200 Subject: [PATCH 10/17] workflows: generate API reference as part of CI to check links Signed-off-by: Patrik Oldsberg --- .github/workflows/ci.yml | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8361654038..d203fafa2c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -105,9 +105,6 @@ jobs: run: git diff --quiet origin/master HEAD -- yarn.lock continue-on-error: true - - name: verify doc links - run: node scripts/verify-links.js - - name: prettier run: yarn prettier:check '!ADOPTERS.md' @@ -123,8 +120,12 @@ jobs: - name: type checking and declarations run: yarn tsc:full - - name: check api reports - run: yarn build:api-reports:only --ci + # We need to generate the API references as well, so that we can verify the doc links + - name: check api reports and generate API reference + run: yarn build:api-reports:only --ci --docs + + - name: verify doc links + run: node scripts/verify-links.js - name: build changed packages if: ${{ steps.yarn-lock.outcome == 'success' }} From eb4fecca82a4b40ea9257970052ceb61e213d796 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 13:40:50 +0200 Subject: [PATCH 11/17] core-components: rewrite component components to use functions Signed-off-by: Patrik Oldsberg --- packages/core-components/api-report.md | 836 ++---------------- .../components/AlertDisplay/AlertDisplay.tsx | 4 +- .../src/components/Avatar/Avatar.tsx | 5 +- .../src/components/Button/Button.tsx | 13 +- .../components/CheckboxTree/CheckboxTree.tsx | 11 +- .../components/CodeSnippet/CodeSnippet.tsx | 17 +- .../CopyTextButton/CopyTextButton.tsx | 4 +- .../components/CreateButton/CreateButton.tsx | 5 +- .../DependencyGraph/DependencyGraph.tsx | 43 +- .../DismissableBanner/DismissableBanner.tsx | 8 +- .../src/components/EmptyState/EmptyState.tsx | 5 +- .../MissingAnnotationEmptyState.tsx | 5 +- .../src/components/ErrorPanel/ErrorPanel.tsx | 10 +- .../FeatureCalloutCircular.tsx | 10 +- .../HeaderIconLinkRow/HeaderIconLinkRow.tsx | 5 +- .../HorizontalScrollGrid.tsx | 4 +- .../src/components/Lifecycle/Lifecycle.tsx | 4 +- .../src/components/Link/Link.tsx | 11 +- .../MarkdownContent/MarkdownContent.tsx | 5 +- .../OAuthRequestDialog/OAuthRequestDialog.tsx | 4 +- .../OverflowTooltip/OverflowTooltip.tsx | 4 +- .../src/components/Progress/Progress.tsx | 4 +- .../src/components/ProgressBars/Gauge.tsx | 4 +- .../src/components/ProgressBars/GaugeCard.tsx | 4 +- .../components/ProgressBars/LinearGauge.tsx | 5 +- .../ResponseErrorPanel/ResponseErrorPanel.tsx | 9 +- .../src/components/Select/Select.tsx | 21 +- .../SimpleStepper/SimpleStepper.tsx | 10 +- .../SimpleStepper/SimpleStepperStep.tsx | 11 +- .../src/components/Status/Status.tsx | 24 +- .../StructuredMetadataTable.tsx | 9 +- .../SupportButton/SupportButton.tsx | 5 +- .../components/TabbedLayout/RoutedTabs.tsx | 5 +- .../components/TabbedLayout/TabbedLayout.tsx | 6 +- .../src/components/Table/SubvalueCell.tsx | 5 +- .../src/components/Table/Table.tsx | 28 +- .../src/components/Tabs/Tabs.tsx | 5 +- .../src/components/TrendLine/TrendLine.tsx | 6 +- .../components/WarningPanel/WarningPanel.tsx | 17 +- 39 files changed, 256 insertions(+), 935 deletions(-) diff --git a/packages/core-components/api-report.md b/packages/core-components/api-report.md index f73eee1f13..0f8ea308c6 100644 --- a/packages/core-components/api-report.md +++ b/packages/core-components/api-report.md @@ -9,10 +9,8 @@ import { ApiRef } from '@backstage/core-plugin-api'; import { BackstageIdentityApi } from '@backstage/core-plugin-api'; import { Breadcrumbs as Breadcrumbs_2 } from '@material-ui/core'; import { ButtonProps } from '@material-ui/core'; -import { ButtonTypeMap } from '@material-ui/core'; import { CardHeaderProps } from '@material-ui/core'; import { Column } from '@material-table/core'; -import { CommonProps } from '@material-ui/core/OverridableComponent'; import { ComponentClass } from 'react'; import { ComponentProps } from 'react'; import { Context } from 'react'; @@ -50,7 +48,7 @@ import { WithStyles } from '@material-ui/core'; // Warning: (ae-missing-release-tag) "AlertDisplay" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const AlertDisplay: () => JSX.Element | null; +export function AlertDisplay(_props: {}): JSX.Element | null; // Warning: (ae-missing-release-tag) "Alignment" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -70,11 +68,7 @@ enum Alignment { // Warning: (ae-missing-release-tag) "Avatar" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Avatar: ({ - displayName, - picture, - customStyles, -}: AvatarProps) => JSX.Element; +export function Avatar(props: AvatarProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "Breadcrumbs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -88,316 +82,10 @@ export const Breadcrumbs: ({ children, ...props }: Props_24) => JSX.Element; export const BrokenImageIcon: IconComponent; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "Button" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// Warning: (ae-missing-release-tag) "ButtonType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public -export const Button: React_2.ForwardRefExoticComponent< - Pick< - Props, - | 'replace' - | 'media' - | 'hidden' - | 'dir' - | 'form' - | 'slot' - | 'title' - | 'disabled' - | 'color' - | 'size' - | 'underline' - | 'display' - | 'translate' - | 'prefix' - | 'children' - | 'key' - | 'value' - | 'id' - | 'name' - | 'action' - | 'defaultChecked' - | 'defaultValue' - | 'suppressContentEditableWarning' - | 'suppressHydrationWarning' - | 'accessKey' - | 'contentEditable' - | 'contextMenu' - | 'draggable' - | 'lang' - | 'placeholder' - | 'spellCheck' - | 'tabIndex' - | 'radioGroup' - | 'role' - | 'about' - | 'datatype' - | 'inlist' - | 'property' - | 'resource' - | 'typeof' - | 'vocab' - | 'autoCapitalize' - | 'autoCorrect' - | 'autoSave' - | 'itemProp' - | 'itemScope' - | 'itemType' - | 'itemID' - | 'itemRef' - | 'results' - | 'security' - | 'unselectable' - | 'inputMode' - | 'is' - | 'aria-activedescendant' - | 'aria-atomic' - | 'aria-autocomplete' - | 'aria-busy' - | 'aria-checked' - | 'aria-colcount' - | 'aria-colindex' - | 'aria-colspan' - | 'aria-controls' - | 'aria-current' - | 'aria-describedby' - | 'aria-details' - | 'aria-disabled' - | 'aria-dropeffect' - | 'aria-errormessage' - | 'aria-expanded' - | 'aria-flowto' - | 'aria-grabbed' - | 'aria-haspopup' - | 'aria-hidden' - | 'aria-invalid' - | 'aria-keyshortcuts' - | 'aria-label' - | 'aria-labelledby' - | 'aria-level' - | 'aria-live' - | 'aria-modal' - | 'aria-multiline' - | 'aria-multiselectable' - | 'aria-orientation' - | 'aria-owns' - | 'aria-placeholder' - | 'aria-posinset' - | 'aria-pressed' - | 'aria-readonly' - | 'aria-relevant' - | 'aria-required' - | 'aria-roledescription' - | 'aria-rowcount' - | 'aria-rowindex' - | 'aria-rowspan' - | 'aria-selected' - | 'aria-setsize' - | 'aria-sort' - | 'aria-valuemax' - | 'aria-valuemin' - | 'aria-valuenow' - | 'aria-valuetext' - | 'dangerouslySetInnerHTML' - | 'onCopy' - | 'onCopyCapture' - | 'onCut' - | 'onCutCapture' - | 'onPaste' - | 'onPasteCapture' - | 'onCompositionEnd' - | 'onCompositionEndCapture' - | 'onCompositionStart' - | 'onCompositionStartCapture' - | 'onCompositionUpdate' - | 'onCompositionUpdateCapture' - | 'onFocus' - | 'onFocusCapture' - | 'onBlur' - | 'onBlurCapture' - | 'onChange' - | 'onChangeCapture' - | 'onBeforeInput' - | 'onBeforeInputCapture' - | 'onInput' - | 'onInputCapture' - | 'onReset' - | 'onResetCapture' - | 'onSubmit' - | 'onSubmitCapture' - | 'onInvalid' - | 'onInvalidCapture' - | 'onLoad' - | 'onLoadCapture' - | 'onError' - | 'onErrorCapture' - | 'onKeyDown' - | 'onKeyDownCapture' - | 'onKeyPress' - | 'onKeyPressCapture' - | 'onKeyUp' - | 'onKeyUpCapture' - | 'onAbort' - | 'onAbortCapture' - | 'onCanPlay' - | 'onCanPlayCapture' - | 'onCanPlayThrough' - | 'onCanPlayThroughCapture' - | 'onDurationChange' - | 'onDurationChangeCapture' - | 'onEmptied' - | 'onEmptiedCapture' - | 'onEncrypted' - | 'onEncryptedCapture' - | 'onEnded' - | 'onEndedCapture' - | 'onLoadedData' - | 'onLoadedDataCapture' - | 'onLoadedMetadata' - | 'onLoadedMetadataCapture' - | 'onLoadStart' - | 'onLoadStartCapture' - | 'onPause' - | 'onPauseCapture' - | 'onPlay' - | 'onPlayCapture' - | 'onPlaying' - | 'onPlayingCapture' - | 'onProgress' - | 'onProgressCapture' - | 'onRateChange' - | 'onRateChangeCapture' - | 'onSeeked' - | 'onSeekedCapture' - | 'onSeeking' - | 'onSeekingCapture' - | 'onStalled' - | 'onStalledCapture' - | 'onSuspend' - | 'onSuspendCapture' - | 'onTimeUpdate' - | 'onTimeUpdateCapture' - | 'onVolumeChange' - | 'onVolumeChangeCapture' - | 'onWaiting' - | 'onWaitingCapture' - | 'onAuxClick' - | 'onAuxClickCapture' - | 'onClick' - | 'onClickCapture' - | 'onContextMenu' - | 'onContextMenuCapture' - | 'onDoubleClick' - | 'onDoubleClickCapture' - | 'onDrag' - | 'onDragCapture' - | 'onDragEnd' - | 'onDragEndCapture' - | 'onDragEnter' - | 'onDragEnterCapture' - | 'onDragExit' - | 'onDragExitCapture' - | 'onDragLeave' - | 'onDragLeaveCapture' - | 'onDragOver' - | 'onDragOverCapture' - | 'onDragStart' - | 'onDragStartCapture' - | 'onDrop' - | 'onDropCapture' - | 'onMouseDown' - | 'onMouseDownCapture' - | 'onMouseEnter' - | 'onMouseLeave' - | 'onMouseMove' - | 'onMouseMoveCapture' - | 'onMouseOut' - | 'onMouseOutCapture' - | 'onMouseOver' - | 'onMouseOverCapture' - | 'onMouseUp' - | 'onMouseUpCapture' - | 'onSelect' - | 'onSelectCapture' - | 'onTouchCancel' - | 'onTouchCancelCapture' - | 'onTouchEnd' - | 'onTouchEndCapture' - | 'onTouchMove' - | 'onTouchMoveCapture' - | 'onTouchStart' - | 'onTouchStartCapture' - | 'onPointerDown' - | 'onPointerDownCapture' - | 'onPointerMove' - | 'onPointerMoveCapture' - | 'onPointerUp' - | 'onPointerUpCapture' - | 'onPointerCancel' - | 'onPointerCancelCapture' - | 'onPointerEnter' - | 'onPointerEnterCapture' - | 'onPointerLeave' - | 'onPointerLeaveCapture' - | 'onPointerOver' - | 'onPointerOverCapture' - | 'onPointerOut' - | 'onPointerOutCapture' - | 'onGotPointerCapture' - | 'onGotPointerCaptureCapture' - | 'onLostPointerCapture' - | 'onLostPointerCaptureCapture' - | 'onScroll' - | 'onScrollCapture' - | 'onWheel' - | 'onWheelCapture' - | 'onAnimationStart' - | 'onAnimationStartCapture' - | 'onAnimationEnd' - | 'onAnimationEndCapture' - | 'onAnimationIteration' - | 'onAnimationIterationCapture' - | 'onTransitionEnd' - | 'onTransitionEndCapture' - | 'component' - | 'variant' - | 'download' - | 'href' - | 'hrefLang' - | 'ping' - | 'rel' - | 'target' - | 'type' - | 'referrerPolicy' - | 'disableElevation' - | 'fullWidth' - | 'startIcon' - | 'endIcon' - | 'noWrap' - | 'gutterBottom' - | 'paragraph' - | 'autoFocus' - | 'formAction' - | 'formEncType' - | 'formMethod' - | 'formNoValidate' - | 'formTarget' - | 'disableFocusRipple' - | 'buttonRef' - | 'centerRipple' - | 'disableRipple' - | 'disableTouchRipple' - | 'focusRipple' - | 'focusVisibleClassName' - | 'onFocusVisible' - | 'TouchRippleProps' - | 'align' - | 'variantMapping' - | 'to' - | 'state' - | 'TypographyClasses' - | keyof CommonProps> - > & - React_2.RefAttributes ->; +// @public (undocumented) +export function Button(props: Props): JSX.Element; // Warning: (ae-forgotten-export) The symbol "CardTabProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "CardTab" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -422,14 +110,7 @@ export const ChatIcon: IconComponent; // Warning: (ae-missing-release-tag) "CodeSnippet" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const CodeSnippet: ({ - text, - language, - showLineNumbers, - showCopyCodeButton, - highlightedNumbers, - customStyle, -}: Props_2) => JSX.Element; +export const CodeSnippet: (props: Props_2) => JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "Content" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -455,26 +136,28 @@ export const ContentHeader: ({ textAlign, }: PropsWithChildren) => JSX.Element; +// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts +// Warning: (ae-missing-release-tag) "CopyTextButton" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // Warning: (ae-missing-release-tag) "CopyTextButton" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const CopyTextButton: { - (props: Props_3): JSX.Element; - propTypes: { - text: PropTypes.Validator; - tooltipDelay: PropTypes.Requireable; - tooltipText: PropTypes.Requireable; - }; -}; +export function CopyTextButton(props: Props_3): JSX.Element; + +// @public (undocumented) +export namespace CopyTextButton { + var // (undocumented) + propTypes: { + text: PropTypes.Validator; + tooltipDelay: PropTypes.Requireable; + tooltipText: PropTypes.Requireable; + }; +} // Warning: (ae-forgotten-export) The symbol "CreateButtonProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "CreateButton" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const CreateButton: ({ - title, - to, -}: CreateButtonProps) => JSX.Element | null; +export function CreateButton(props: CreateButtonProps): JSX.Element | null; // Warning: (ae-missing-release-tag) "DashboardIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -495,27 +178,7 @@ type DependencyEdge = T & { // Warning: (ae-missing-release-tag) "DependencyGraph" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export function DependencyGraph({ - edges, - nodes, - renderNode, - direction, - align, - nodeMargin, - edgeMargin, - rankMargin, - paddingX, - paddingY, - acyclicer, - ranker, - labelPosition, - labelOffset, - edgeRanks, - edgeWeight, - renderLabel, - defs, - ...svgProps -}: DependencyGraphProps): JSX.Element; +export function DependencyGraph(props: DependencyGraphProps): JSX.Element; declare namespace DependencyGraphTypes { export { @@ -561,12 +224,7 @@ enum Direction { // Warning: (ae-missing-release-tag) "DismissableBanner" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const DismissableBanner: ({ - variant, - message, - id, - fixed, -}: Props_4) => JSX.Element; +export const DismissableBanner: (props: Props_4) => JSX.Element; // Warning: (ae-missing-release-tag) "DocsIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -596,12 +254,7 @@ export const EmailIcon: IconComponent; // Warning: (ae-missing-release-tag) "EmptyState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const EmptyState: ({ - title, - description, - missing, - action, -}: Props_5) => JSX.Element; +export function EmptyState(props: Props_5): JSX.Element; // Warning: (ae-forgotten-export) The symbol "State" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "ErrorBoundary" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -630,12 +283,9 @@ export const ErrorPage: ({ // Warning: (ae-missing-release-tag) "ErrorPanel" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public -export const ErrorPanel: ({ - title, - error, - defaultExpanded, - children, -}: PropsWithChildren) => JSX.Element; +export function ErrorPanel( + props: PropsWithChildren, +): JSX.Element; // Warning: (ae-missing-release-tag) "ErrorPanelProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -650,24 +300,21 @@ export type ErrorPanelProps = { // Warning: (ae-missing-release-tag) "FeatureCalloutCircular" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const FeatureCalloutCircular: ({ - featureId, - title, - description, - children, -}: PropsWithChildren) => JSX.Element; +export function FeatureCalloutCircular( + props: PropsWithChildren, +): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "Gauge" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Gauge: (props: Props_14) => JSX.Element; +export function Gauge(props: Props_14): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "GaugeCard" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const GaugeCard: (props: Props_13) => JSX.Element; +export function GaugeCard(props: Props_13): JSX.Element; // Warning: (ae-missing-release-tag) "GitHubIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -710,7 +357,7 @@ export const Header: ({ // Warning: (ae-missing-release-tag) "HeaderIconLinkRow" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const HeaderIconLinkRow: ({ links }: Props_8) => JSX.Element; +export function HeaderIconLinkRow(props: Props_8): JSX.Element; // Warning: (ae-forgotten-export) The symbol "HeaderLabelProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "HeaderLabel" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -746,9 +393,9 @@ export const HomepageTimer: () => JSX.Element | null; // Warning: (ae-missing-release-tag) "HorizontalScrollGrid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const HorizontalScrollGrid: ( +export function HorizontalScrollGrid( props: PropsWithChildren, -) => JSX.Element; +): JSX.Element; // Warning: (ae-missing-release-tag) "IconLinkVerticalProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -872,302 +519,18 @@ enum LabelPosition { // Warning: (ae-missing-release-tag) "Lifecycle" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Lifecycle: (props: Props_10) => JSX.Element; +export function Lifecycle(props: Props_10): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "LinearGauge" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const LinearGauge: ({ value }: Props_15) => JSX.Element | null; +export function LinearGauge(props: Props_15): JSX.Element | null; -// Warning: (ae-missing-release-tag) "Link" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// Warning: (ae-missing-release-tag) "LinkType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public -export const Link: React_2.ForwardRefExoticComponent< - Pick< - LinkProps, - | 'replace' - | 'media' - | 'hidden' - | 'dir' - | 'slot' - | 'style' - | 'title' - | 'color' - | 'underline' - | 'display' - | 'translate' - | 'prefix' - | 'children' - | 'key' - | 'id' - | 'classes' - | 'defaultChecked' - | 'defaultValue' - | 'suppressContentEditableWarning' - | 'suppressHydrationWarning' - | 'accessKey' - | 'className' - | 'contentEditable' - | 'contextMenu' - | 'draggable' - | 'lang' - | 'placeholder' - | 'spellCheck' - | 'tabIndex' - | 'radioGroup' - | 'role' - | 'about' - | 'datatype' - | 'inlist' - | 'property' - | 'resource' - | 'typeof' - | 'vocab' - | 'autoCapitalize' - | 'autoCorrect' - | 'autoSave' - | 'itemProp' - | 'itemScope' - | 'itemType' - | 'itemID' - | 'itemRef' - | 'results' - | 'security' - | 'unselectable' - | 'inputMode' - | 'is' - | 'aria-activedescendant' - | 'aria-atomic' - | 'aria-autocomplete' - | 'aria-busy' - | 'aria-checked' - | 'aria-colcount' - | 'aria-colindex' - | 'aria-colspan' - | 'aria-controls' - | 'aria-current' - | 'aria-describedby' - | 'aria-details' - | 'aria-disabled' - | 'aria-dropeffect' - | 'aria-errormessage' - | 'aria-expanded' - | 'aria-flowto' - | 'aria-grabbed' - | 'aria-haspopup' - | 'aria-hidden' - | 'aria-invalid' - | 'aria-keyshortcuts' - | 'aria-label' - | 'aria-labelledby' - | 'aria-level' - | 'aria-live' - | 'aria-modal' - | 'aria-multiline' - | 'aria-multiselectable' - | 'aria-orientation' - | 'aria-owns' - | 'aria-placeholder' - | 'aria-posinset' - | 'aria-pressed' - | 'aria-readonly' - | 'aria-relevant' - | 'aria-required' - | 'aria-roledescription' - | 'aria-rowcount' - | 'aria-rowindex' - | 'aria-rowspan' - | 'aria-selected' - | 'aria-setsize' - | 'aria-sort' - | 'aria-valuemax' - | 'aria-valuemin' - | 'aria-valuenow' - | 'aria-valuetext' - | 'dangerouslySetInnerHTML' - | 'onCopy' - | 'onCopyCapture' - | 'onCut' - | 'onCutCapture' - | 'onPaste' - | 'onPasteCapture' - | 'onCompositionEnd' - | 'onCompositionEndCapture' - | 'onCompositionStart' - | 'onCompositionStartCapture' - | 'onCompositionUpdate' - | 'onCompositionUpdateCapture' - | 'onFocus' - | 'onFocusCapture' - | 'onBlur' - | 'onBlurCapture' - | 'onChange' - | 'onChangeCapture' - | 'onBeforeInput' - | 'onBeforeInputCapture' - | 'onInput' - | 'onInputCapture' - | 'onReset' - | 'onResetCapture' - | 'onSubmit' - | 'onSubmitCapture' - | 'onInvalid' - | 'onInvalidCapture' - | 'onLoad' - | 'onLoadCapture' - | 'onError' - | 'onErrorCapture' - | 'onKeyDown' - | 'onKeyDownCapture' - | 'onKeyPress' - | 'onKeyPressCapture' - | 'onKeyUp' - | 'onKeyUpCapture' - | 'onAbort' - | 'onAbortCapture' - | 'onCanPlay' - | 'onCanPlayCapture' - | 'onCanPlayThrough' - | 'onCanPlayThroughCapture' - | 'onDurationChange' - | 'onDurationChangeCapture' - | 'onEmptied' - | 'onEmptiedCapture' - | 'onEncrypted' - | 'onEncryptedCapture' - | 'onEnded' - | 'onEndedCapture' - | 'onLoadedData' - | 'onLoadedDataCapture' - | 'onLoadedMetadata' - | 'onLoadedMetadataCapture' - | 'onLoadStart' - | 'onLoadStartCapture' - | 'onPause' - | 'onPauseCapture' - | 'onPlay' - | 'onPlayCapture' - | 'onPlaying' - | 'onPlayingCapture' - | 'onProgress' - | 'onProgressCapture' - | 'onRateChange' - | 'onRateChangeCapture' - | 'onSeeked' - | 'onSeekedCapture' - | 'onSeeking' - | 'onSeekingCapture' - | 'onStalled' - | 'onStalledCapture' - | 'onSuspend' - | 'onSuspendCapture' - | 'onTimeUpdate' - | 'onTimeUpdateCapture' - | 'onVolumeChange' - | 'onVolumeChangeCapture' - | 'onWaiting' - | 'onWaitingCapture' - | 'onAuxClick' - | 'onAuxClickCapture' - | 'onClick' - | 'onClickCapture' - | 'onContextMenu' - | 'onContextMenuCapture' - | 'onDoubleClick' - | 'onDoubleClickCapture' - | 'onDrag' - | 'onDragCapture' - | 'onDragEnd' - | 'onDragEndCapture' - | 'onDragEnter' - | 'onDragEnterCapture' - | 'onDragExit' - | 'onDragExitCapture' - | 'onDragLeave' - | 'onDragLeaveCapture' - | 'onDragOver' - | 'onDragOverCapture' - | 'onDragStart' - | 'onDragStartCapture' - | 'onDrop' - | 'onDropCapture' - | 'onMouseDown' - | 'onMouseDownCapture' - | 'onMouseEnter' - | 'onMouseLeave' - | 'onMouseMove' - | 'onMouseMoveCapture' - | 'onMouseOut' - | 'onMouseOutCapture' - | 'onMouseOver' - | 'onMouseOverCapture' - | 'onMouseUp' - | 'onMouseUpCapture' - | 'onSelect' - | 'onSelectCapture' - | 'onTouchCancel' - | 'onTouchCancelCapture' - | 'onTouchEnd' - | 'onTouchEndCapture' - | 'onTouchMove' - | 'onTouchMoveCapture' - | 'onTouchStart' - | 'onTouchStartCapture' - | 'onPointerDown' - | 'onPointerDownCapture' - | 'onPointerMove' - | 'onPointerMoveCapture' - | 'onPointerUp' - | 'onPointerUpCapture' - | 'onPointerCancel' - | 'onPointerCancelCapture' - | 'onPointerEnter' - | 'onPointerEnterCapture' - | 'onPointerLeave' - | 'onPointerLeaveCapture' - | 'onPointerOver' - | 'onPointerOverCapture' - | 'onPointerOut' - | 'onPointerOutCapture' - | 'onGotPointerCapture' - | 'onGotPointerCaptureCapture' - | 'onLostPointerCapture' - | 'onLostPointerCaptureCapture' - | 'onScroll' - | 'onScrollCapture' - | 'onWheel' - | 'onWheelCapture' - | 'onAnimationStart' - | 'onAnimationStartCapture' - | 'onAnimationEnd' - | 'onAnimationEndCapture' - | 'onAnimationIteration' - | 'onAnimationIterationCapture' - | 'onTransitionEnd' - | 'onTransitionEndCapture' - | 'component' - | 'variant' - | 'innerRef' - | 'download' - | 'href' - | 'hrefLang' - | 'ping' - | 'rel' - | 'target' - | 'type' - | 'referrerPolicy' - | 'noWrap' - | 'gutterBottom' - | 'paragraph' - | 'align' - | 'variantMapping' - | 'to' - | 'state' - | 'TypographyClasses' - > & - React_2.RefAttributes ->; +// @public (undocumented) +export function Link(props: LinkProps): JSX.Element; // Warning: (ae-missing-release-tag) "LinkProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -1181,26 +544,24 @@ export type LinkProps = LinkProps_2 & // Warning: (ae-missing-release-tag) "MarkdownContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public -export const MarkdownContent: ({ content, dialect }: Props_11) => JSX.Element; +export function MarkdownContent(props: Props_11): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "MissingAnnotationEmptyState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const MissingAnnotationEmptyState: ({ - annotation, -}: Props_6) => JSX.Element; +export function MissingAnnotationEmptyState(props: Props_6): JSX.Element; // Warning: (ae-missing-release-tag) "OAuthRequestDialog" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const OAuthRequestDialog: () => JSX.Element; +export function OAuthRequestDialog(_props: {}): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "OverflowTooltip" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const OverflowTooltip: (props: Props_12) => JSX.Element; +export function OverflowTooltip(props: Props_12): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "Page" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -1224,9 +585,9 @@ export const PageWithHeader: ({ // Warning: (ae-missing-release-tag) "Progress" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Progress: ( +export function Progress( props: PropsWithChildren, -) => JSX.Element; +): JSX.Element; // Warning: (ae-missing-release-tag) "Ranker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -1267,30 +628,18 @@ type RenderNodeProps = { // Warning: (ae-missing-release-tag) "ResponseErrorPanel" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public -export const ResponseErrorPanel: ({ - title, - error, - defaultExpanded, -}: ErrorPanelProps) => JSX.Element; +export function ResponseErrorPanel(props: ErrorPanelProps): JSX.Element; // Warning: (ae-missing-release-tag) "RoutedTabs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const RoutedTabs: ({ routes }: { routes: SubRoute_2[] }) => JSX.Element; +export function RoutedTabs(props: { routes: SubRoute_2[] }): JSX.Element; // Warning: (ae-forgotten-export) The symbol "SelectProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "SelectComponent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Select: ({ - multiple, - items, - label, - placeholder, - selected, - onChange, - triggerReset, -}: SelectProps) => JSX.Element; +export function Select(props: SelectProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "Sidebar" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -2473,82 +1822,65 @@ export type SignInProviderConfig = { // Warning: (ae-missing-release-tag) "SimpleStepper" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const SimpleStepper: ({ - children, - elevated, - onStepChange, - activeStep, -}: PropsWithChildren) => JSX.Element; +export function SimpleStepper( + props: PropsWithChildren, +): JSX.Element; // Warning: (ae-forgotten-export) The symbol "StepProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "SimpleStepperStep" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const SimpleStepperStep: ({ - title, - children, - end, - actions, - ...muiProps -}: PropsWithChildren) => JSX.Element; +export function SimpleStepperStep( + props: PropsWithChildren, +): JSX.Element; // Warning: (ae-missing-release-tag) "StatusAborted" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const StatusAborted: (props: PropsWithChildren<{}>) => JSX.Element; +export function StatusAborted(props: PropsWithChildren<{}>): JSX.Element; // Warning: (ae-missing-release-tag) "StatusError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const StatusError: (props: PropsWithChildren<{}>) => JSX.Element; +export function StatusError(props: PropsWithChildren<{}>): JSX.Element; // Warning: (ae-missing-release-tag) "StatusOK" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const StatusOK: (props: PropsWithChildren<{}>) => JSX.Element; +export function StatusOK(props: PropsWithChildren<{}>): JSX.Element; // Warning: (ae-missing-release-tag) "StatusPending" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const StatusPending: (props: PropsWithChildren<{}>) => JSX.Element; +export function StatusPending(props: PropsWithChildren<{}>): JSX.Element; // Warning: (ae-missing-release-tag) "StatusRunning" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const StatusRunning: (props: PropsWithChildren<{}>) => JSX.Element; +export function StatusRunning(props: PropsWithChildren<{}>): JSX.Element; // Warning: (ae-missing-release-tag) "StatusWarning" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const StatusWarning: (props: PropsWithChildren<{}>) => JSX.Element; +export function StatusWarning(props: PropsWithChildren<{}>): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "StructuredMetadataTable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const StructuredMetadataTable: ({ - metadata, - dense, - options, -}: Props_16) => JSX.Element; +export function StructuredMetadataTable(props: Props_16): JSX.Element; // Warning: (ae-forgotten-export) The symbol "SubvalueCellProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "SubvalueCell" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const SubvalueCell: ({ - value, - subvalue, -}: SubvalueCellProps) => JSX.Element; +export function SubvalueCell(props: SubvalueCellProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "SupportButtonProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "SupportButton" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const SupportButton: ({ - title, - children, -}: SupportButtonProps) => JSX.Element; +export function SupportButton(props: SupportButtonProps): JSX.Element; // Warning: (ae-missing-release-tag) "SupportConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -2603,28 +1935,24 @@ export const TabbedCard: ({ onChange, }: PropsWithChildren) => JSX.Element; +// Warning: (ae-missing-release-tag) "TabbedLayout" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // Warning: (ae-missing-release-tag) "TabbedLayout" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public -export const TabbedLayout: { - ({ children }: PropsWithChildren<{}>): JSX.Element; - Route: (props: SubRoute) => null; -}; +export function TabbedLayout(props: PropsWithChildren<{}>): JSX.Element; + +// @public (undocumented) +export namespace TabbedLayout { + var // Warning: (ae-forgotten-export) The symbol "SubRoute" needs to be exported by the entry point index.d.ts + // + // (undocumented) + Route: (props: SubRoute) => null; +} // Warning: (ae-missing-release-tag) "Table" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export function Table({ - columns, - options, - title, - subtitle, - filters, - initialState, - emptyContent, - onStateChange, - ...props -}: TableProps): JSX.Element; +export function Table(props: TableProps): JSX.Element; // Warning: (ae-missing-release-tag) "TableColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -2676,17 +2004,17 @@ export type TableState = { // Warning: (ae-missing-release-tag) "Tabs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Tabs: ({ tabs }: TabsProps) => JSX.Element; +export function Tabs(props: TabsProps): JSX.Element; // Warning: (ae-missing-release-tag) "TrendLine" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const TrendLine: ( +export function TrendLine( props: SparklinesProps & Pick & { title?: string; }, -) => JSX.Element | null; +): JSX.Element | null; // Warning: (ae-forgotten-export) The symbol "SetQueryParams" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "useQueryParamState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -2728,19 +2056,11 @@ export const WarningIcon: IconComponent; // Warning: (ae-missing-release-tag) "WarningPanel" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public -export const WarningPanel: ({ - severity, - title, - message, - children, - defaultExpanded, -}: WarningProps) => JSX.Element; +export function WarningPanel(props: WarningProps): JSX.Element; // Warnings were encountered during analysis: // -// src/components/CopyTextButton/CopyTextButton.d.ts:24:5 - (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // src/components/TabbedLayout/RoutedTabs.d.ts:9:5 - (ae-forgotten-export) The symbol "SubRoute" needs to be exported by the entry point index.d.ts -// src/components/TabbedLayout/TabbedLayout.d.ts:29:5 - (ae-forgotten-export) The symbol "SubRoute" needs to be exported by the entry point index.d.ts // src/components/Table/Table.d.ts:15:5 - (ae-forgotten-export) The symbol "SelectedFilters" needs to be exported by the entry point index.d.ts // src/layout/ErrorBoundary/ErrorBoundary.d.ts:7:5 - (ae-forgotten-export) The symbol "SlackChannel" needs to be exported by the entry point index.d.ts diff --git a/packages/core-components/src/components/AlertDisplay/AlertDisplay.tsx b/packages/core-components/src/components/AlertDisplay/AlertDisplay.tsx index 495e2ea14c..f3e102d9a0 100644 --- a/packages/core-components/src/components/AlertDisplay/AlertDisplay.tsx +++ b/packages/core-components/src/components/AlertDisplay/AlertDisplay.tsx @@ -22,7 +22,7 @@ import { AlertMessage, useApi, alertApiRef } from '@backstage/core-plugin-api'; import pluralize from 'pluralize'; // TODO: improve on this and promote to a shared component for use by all apps. -export const AlertDisplay = () => { +export function AlertDisplay(_props: {}) { const [messages, setMessages] = useState>([]); const alertApi = useApi(alertApiRef); @@ -73,4 +73,4 @@ export const AlertDisplay = () => { ); -}; +} diff --git a/packages/core-components/src/components/Avatar/Avatar.tsx b/packages/core-components/src/components/Avatar/Avatar.tsx index df3c46fba7..f694365233 100644 --- a/packages/core-components/src/components/Avatar/Avatar.tsx +++ b/packages/core-components/src/components/Avatar/Avatar.tsx @@ -41,7 +41,8 @@ export type AvatarProps = { customStyles?: CSSProperties; }; -export const Avatar = ({ displayName, picture, customStyles }: AvatarProps) => { +export function Avatar(props: AvatarProps) { + const { displayName, picture, customStyles } = props; const classes = useStyles(); return ( { {displayName && extractInitials(displayName)} ); -}; +} diff --git a/packages/core-components/src/components/Button/Button.tsx b/packages/core-components/src/components/Button/Button.tsx index 6dd593d776..e52285312b 100644 --- a/packages/core-components/src/components/Button/Button.tsx +++ b/packages/core-components/src/components/Button/Button.tsx @@ -23,10 +23,19 @@ import { Link, LinkProps } from '../Link'; type Props = MaterialButtonProps & Omit; +declare function ButtonType(props: Props): JSX.Element; + /** * Thin wrapper on top of material-ui's Button component * Makes the Button to utilise react-router */ -export const Button = React.forwardRef((props, ref) => ( +const ActualButton = React.forwardRef((props, ref) => ( -)); +)) as { (props: Props): JSX.Element }; + +// TODO(Rugvip): We use this as a workaround to make the exported type be a +// function, which makes our API reference docs much nicer. +// The first type to be exported gets priority, but it will +// be thrown away when compiling to JS. +// @ts-ignore +export { ButtonType as Button, ActualButton as Button }; diff --git a/packages/core-components/src/components/CheckboxTree/CheckboxTree.tsx b/packages/core-components/src/components/CheckboxTree/CheckboxTree.tsx index 7e7155143b..695da88192 100644 --- a/packages/core-components/src/components/CheckboxTree/CheckboxTree.tsx +++ b/packages/core-components/src/components/CheckboxTree/CheckboxTree.tsx @@ -225,13 +225,8 @@ const indexer = ( }; }, {}); -export const CheckboxTree = ({ - subCategories, - label, - selected, - onChange, - triggerReset, -}: CheckboxTreeProps) => { +export function CheckboxTree(props: CheckboxTreeProps) { + const { subCategories, label, selected, onChange, triggerReset } = props; const classes = useStyles(); const [state, dispatch] = useReducer(reducer, indexer(subCategories)); @@ -355,4 +350,4 @@ export const CheckboxTree = ({ ); -}; +} diff --git a/packages/core-components/src/components/CodeSnippet/CodeSnippet.tsx b/packages/core-components/src/components/CodeSnippet/CodeSnippet.tsx index a3badaad07..6417151ff4 100644 --- a/packages/core-components/src/components/CodeSnippet/CodeSnippet.tsx +++ b/packages/core-components/src/components/CodeSnippet/CodeSnippet.tsx @@ -30,14 +30,15 @@ type Props = { customStyle?: any; }; -export const CodeSnippet = ({ - text, - language, - showLineNumbers = false, - showCopyCodeButton = false, - highlightedNumbers, - customStyle, -}: Props) => { +export const CodeSnippet = (props: Props) => { + const { + text, + language, + showLineNumbers = false, + showCopyCodeButton = false, + highlightedNumbers, + customStyle, + } = props; const theme = useTheme(); const mode = theme.palette.type === 'dark' ? dark : docco; const highlightColor = theme.palette.type === 'dark' ? '#256bf3' : '#e6ffed'; diff --git a/packages/core-components/src/components/CopyTextButton/CopyTextButton.tsx b/packages/core-components/src/components/CopyTextButton/CopyTextButton.tsx index cc0ecaf76f..2d3afff1dc 100644 --- a/packages/core-components/src/components/CopyTextButton/CopyTextButton.tsx +++ b/packages/core-components/src/components/CopyTextButton/CopyTextButton.tsx @@ -47,7 +47,7 @@ const defaultProps = { tooltipText: 'Text copied to clipboard', }; -export const CopyTextButton = (props: Props) => { +export function CopyTextButton(props: Props) { const { text, tooltipDelay, tooltipText } = { ...defaultProps, ...props, @@ -84,7 +84,7 @@ export const CopyTextButton = (props: Props) => { ); -}; +} // Type check for the JS files using this core component CopyTextButton.propTypes = { diff --git a/packages/core-components/src/components/CreateButton/CreateButton.tsx b/packages/core-components/src/components/CreateButton/CreateButton.tsx index 021e1b002d..1ca4fdaa97 100644 --- a/packages/core-components/src/components/CreateButton/CreateButton.tsx +++ b/packages/core-components/src/components/CreateButton/CreateButton.tsx @@ -24,7 +24,8 @@ type CreateButtonProps = { title: string; } & Partial>; -export const CreateButton = ({ title, to }: CreateButtonProps) => { +export function CreateButton(props: CreateButtonProps) { + const { title, to } = props; const isXSScreen = useMediaQuery(theme => theme.breakpoints.down('xs'), ); @@ -48,4 +49,4 @@ export const CreateButton = ({ title, to }: CreateButtonProps) => { {title} ); -}; +} diff --git a/packages/core-components/src/components/DependencyGraph/DependencyGraph.tsx b/packages/core-components/src/components/DependencyGraph/DependencyGraph.tsx index 436eda614c..0d74965e7e 100644 --- a/packages/core-components/src/components/DependencyGraph/DependencyGraph.tsx +++ b/packages/core-components/src/components/DependencyGraph/DependencyGraph.tsx @@ -60,27 +60,28 @@ export type DependencyGraphProps = React.SVGProps & { const WORKSPACE_ID = 'workspace'; -export function DependencyGraph({ - edges, - nodes, - renderNode, - direction = Direction.TOP_BOTTOM, - align, - nodeMargin = 50, - edgeMargin = 10, - rankMargin = 50, - paddingX = 0, - paddingY = 0, - acyclicer, - ranker = Ranker.NETWORK_SIMPLEX, - labelPosition = LabelPosition.RIGHT, - labelOffset = 10, - edgeRanks = 1, - edgeWeight = 1, - renderLabel, - defs, - ...svgProps -}: DependencyGraphProps) { +export function DependencyGraph(props: DependencyGraphProps) { + const { + edges, + nodes, + renderNode, + direction = Direction.TOP_BOTTOM, + align, + nodeMargin = 50, + edgeMargin = 10, + rankMargin = 50, + paddingX = 0, + paddingY = 0, + acyclicer, + ranker = Ranker.NETWORK_SIMPLEX, + labelPosition = LabelPosition.RIGHT, + labelOffset = 10, + edgeRanks = 1, + edgeWeight = 1, + renderLabel, + defs, + ...svgProps + } = props; const theme: BackstageTheme = useTheme(); const [containerWidth, setContainerWidth] = React.useState(100); const [containerHeight, setContainerHeight] = React.useState(100); diff --git a/packages/core-components/src/components/DismissableBanner/DismissableBanner.tsx b/packages/core-components/src/components/DismissableBanner/DismissableBanner.tsx index 6c4e43811d..cc20a49ad6 100644 --- a/packages/core-components/src/components/DismissableBanner/DismissableBanner.tsx +++ b/packages/core-components/src/components/DismissableBanner/DismissableBanner.tsx @@ -70,12 +70,8 @@ type Props = { fixed?: boolean; }; -export const DismissableBanner = ({ - variant, - message, - id, - fixed = false, -}: Props) => { +export const DismissableBanner = (props: Props) => { + const { variant, message, id, fixed = false } = props; const classes = useStyles(); const storageApi = useApi(storageApiRef); const notificationsStore = storageApi.forBucket('notifications'); diff --git a/packages/core-components/src/components/EmptyState/EmptyState.tsx b/packages/core-components/src/components/EmptyState/EmptyState.tsx index d916ad9a61..b2f5eca65e 100644 --- a/packages/core-components/src/components/EmptyState/EmptyState.tsx +++ b/packages/core-components/src/components/EmptyState/EmptyState.tsx @@ -38,7 +38,8 @@ type Props = { action?: JSX.Element; }; -export const EmptyState = ({ title, description, missing, action }: Props) => { +export function EmptyState(props: Props) { + const { title, description, missing, action } = props; const classes = useStyles(); return ( { ); -}; +} diff --git a/packages/core-components/src/components/EmptyState/MissingAnnotationEmptyState.tsx b/packages/core-components/src/components/EmptyState/MissingAnnotationEmptyState.tsx index d477494964..17061fa237 100644 --- a/packages/core-components/src/components/EmptyState/MissingAnnotationEmptyState.tsx +++ b/packages/core-components/src/components/EmptyState/MissingAnnotationEmptyState.tsx @@ -45,7 +45,8 @@ const useStyles = makeStyles(theme => ({ }, })); -export const MissingAnnotationEmptyState = ({ annotation }: Props) => { +export function MissingAnnotationEmptyState(props: Props) { + const { annotation } = props; const classes = useStyles(); const description = ( <> @@ -84,4 +85,4 @@ export const MissingAnnotationEmptyState = ({ annotation }: Props) => { } /> ); -}; +} diff --git a/packages/core-components/src/components/ErrorPanel/ErrorPanel.tsx b/packages/core-components/src/components/ErrorPanel/ErrorPanel.tsx index f9996b9b1f..309f2b447a 100644 --- a/packages/core-components/src/components/ErrorPanel/ErrorPanel.tsx +++ b/packages/core-components/src/components/ErrorPanel/ErrorPanel.tsx @@ -92,12 +92,8 @@ export type ErrorPanelProps = { /** * Renders a warning panel as the effect of an error. */ -export const ErrorPanel = ({ - title, - error, - defaultExpanded, - children, -}: PropsWithChildren) => { +export function ErrorPanel(props: PropsWithChildren) { + const { title, error, defaultExpanded, children } = props; return ( ); -}; +} diff --git a/packages/core-components/src/components/FeatureDiscovery/FeatureCalloutCircular.tsx b/packages/core-components/src/components/FeatureDiscovery/FeatureCalloutCircular.tsx index 9af6c30c3b..9459c3cbe0 100644 --- a/packages/core-components/src/components/FeatureDiscovery/FeatureCalloutCircular.tsx +++ b/packages/core-components/src/components/FeatureDiscovery/FeatureCalloutCircular.tsx @@ -93,12 +93,8 @@ type Placement = { textWidth: number; }; -export const FeatureCalloutCircular = ({ - featureId, - title, - description, - children, -}: PropsWithChildren) => { +export function FeatureCalloutCircular(props: PropsWithChildren) { + const { featureId, title, description, children } = props; const { show, hide } = useShowCallout(featureId); const portalElement = usePortal('core.callout'); const wrapperRef = useRef(null); @@ -196,4 +192,4 @@ export const FeatureCalloutCircular = ({ )} ); -}; +} diff --git a/packages/core-components/src/components/HeaderIconLinkRow/HeaderIconLinkRow.tsx b/packages/core-components/src/components/HeaderIconLinkRow/HeaderIconLinkRow.tsx index afceda165e..7e49537492 100644 --- a/packages/core-components/src/components/HeaderIconLinkRow/HeaderIconLinkRow.tsx +++ b/packages/core-components/src/components/HeaderIconLinkRow/HeaderIconLinkRow.tsx @@ -31,7 +31,8 @@ type Props = { links: IconLinkVerticalProps[]; }; -export const HeaderIconLinkRow = ({ links }: Props) => { +export function HeaderIconLinkRow(props: Props) { + const { links } = props; const classes = useStyles(); return ( ); -}; +} diff --git a/packages/core-components/src/components/HorizontalScrollGrid/HorizontalScrollGrid.tsx b/packages/core-components/src/components/HorizontalScrollGrid/HorizontalScrollGrid.tsx index f5c45d3eb0..a3d16bc4ec 100644 --- a/packages/core-components/src/components/HorizontalScrollGrid/HorizontalScrollGrid.tsx +++ b/packages/core-components/src/components/HorizontalScrollGrid/HorizontalScrollGrid.tsx @@ -181,7 +181,7 @@ function useSmoothScroll( return setScrollTarget; } -export const HorizontalScrollGrid = (props: PropsWithChildren) => { +export function HorizontalScrollGrid(props: PropsWithChildren) { const { scrollStep = 100, scrollSpeed = 50, @@ -244,4 +244,4 @@ export const HorizontalScrollGrid = (props: PropsWithChildren) => { )} ); -}; +} diff --git a/packages/core-components/src/components/Lifecycle/Lifecycle.tsx b/packages/core-components/src/components/Lifecycle/Lifecycle.tsx index c72ea46f1b..ef451ac1b0 100644 --- a/packages/core-components/src/components/Lifecycle/Lifecycle.tsx +++ b/packages/core-components/src/components/Lifecycle/Lifecycle.tsx @@ -38,7 +38,7 @@ const useStyles = makeStyles({ }, }); -export const Lifecycle = (props: Props) => { +export function Lifecycle(props: Props) { const classes = useStyles(props); const { shorthand, alpha } = props; return shorthand ? ( @@ -53,4 +53,4 @@ export const Lifecycle = (props: Props) => { {alpha ? 'Alpha' : 'Beta'} ); -}; +} diff --git a/packages/core-components/src/components/Link/Link.tsx b/packages/core-components/src/components/Link/Link.tsx index 7853c4f52f..0d301dccf9 100644 --- a/packages/core-components/src/components/Link/Link.tsx +++ b/packages/core-components/src/components/Link/Link.tsx @@ -31,11 +31,13 @@ export type LinkProps = MaterialLinkProps & component?: ElementType; }; +declare function LinkType(props: LinkProps): JSX.Element; + /** * Thin wrapper on top of material-ui's Link component * Makes the Link to utilise react-router */ -export const Link = React.forwardRef((props, ref) => { +const ActualLink = React.forwardRef((props, ref) => { const to = String(props.to); const external = isExternalUri(to); const newWindow = external && !!/^https?:/.exec(to); @@ -52,3 +54,10 @@ export const Link = React.forwardRef((props, ref) => { ); }); + +// TODO(Rugvip): We use this as a workaround to make the exported type be a +// function, which makes our API reference docs much nicer. +// The first type to be exported gets priority, but it will +// be thrown away when compiling to JS. +// @ts-ignore +export { LinkType as Link, ActualLink as Link }; diff --git a/packages/core-components/src/components/MarkdownContent/MarkdownContent.tsx b/packages/core-components/src/components/MarkdownContent/MarkdownContent.tsx index 296df22ecd..d2930cbf5d 100644 --- a/packages/core-components/src/components/MarkdownContent/MarkdownContent.tsx +++ b/packages/core-components/src/components/MarkdownContent/MarkdownContent.tsx @@ -76,7 +76,8 @@ const renderers = { * Renders markdown with the default dialect [gfm - GitHub flavored Markdown](https://github.github.com/gfm/) to backstage theme styled HTML. * If you just want to render to plain [CommonMark](https://commonmark.org/), set the dialect to `'common-mark'` */ -export const MarkdownContent = ({ content, dialect = 'gfm' }: Props) => { +export function MarkdownContent(props: Props) { + const { content, dialect = 'gfm' } = props; const classes = useStyles(); return ( { renderers={renderers} /> ); -}; +} diff --git a/packages/core-components/src/components/OAuthRequestDialog/OAuthRequestDialog.tsx b/packages/core-components/src/components/OAuthRequestDialog/OAuthRequestDialog.tsx index 687e4211bf..669b9a02f5 100644 --- a/packages/core-components/src/components/OAuthRequestDialog/OAuthRequestDialog.tsx +++ b/packages/core-components/src/components/OAuthRequestDialog/OAuthRequestDialog.tsx @@ -41,7 +41,7 @@ const useStyles = makeStyles(theme => ({ }, })); -export const OAuthRequestDialog = () => { +export function OAuthRequestDialog(_props: {}) { const classes = useStyles(); const [busy, setBusy] = useState(false); const oauthRequestApi = useApi(oauthRequestApiRef); @@ -83,4 +83,4 @@ export const OAuthRequestDialog = () => { ); -}; +} diff --git a/packages/core-components/src/components/OverflowTooltip/OverflowTooltip.tsx b/packages/core-components/src/components/OverflowTooltip/OverflowTooltip.tsx index 1be7ebc7ed..fbb1537847 100644 --- a/packages/core-components/src/components/OverflowTooltip/OverflowTooltip.tsx +++ b/packages/core-components/src/components/OverflowTooltip/OverflowTooltip.tsx @@ -32,7 +32,7 @@ const useStyles = makeStyles({ }, }); -export const OverflowTooltip = (props: Props) => { +export function OverflowTooltip(props: Props) { const [hover, setHover] = useState(false); const classes = useStyles(); @@ -54,4 +54,4 @@ export const OverflowTooltip = (props: Props) => { /> ); -}; +} diff --git a/packages/core-components/src/components/Progress/Progress.tsx b/packages/core-components/src/components/Progress/Progress.tsx index 68dcb91785..00ad532b5e 100644 --- a/packages/core-components/src/components/Progress/Progress.tsx +++ b/packages/core-components/src/components/Progress/Progress.tsx @@ -17,7 +17,7 @@ import React, { useState, useEffect, PropsWithChildren } from 'react'; import { LinearProgress, LinearProgressProps } from '@material-ui/core'; -export const Progress = (props: PropsWithChildren) => { +export function Progress(props: PropsWithChildren) { const [isVisible, setIsVisible] = useState(false); useEffect(() => { @@ -30,4 +30,4 @@ export const Progress = (props: PropsWithChildren) => { ) : (
); -}; +} diff --git a/packages/core-components/src/components/ProgressBars/Gauge.tsx b/packages/core-components/src/components/ProgressBars/Gauge.tsx index 46948d4af6..3b31f64fe7 100644 --- a/packages/core-components/src/components/ProgressBars/Gauge.tsx +++ b/packages/core-components/src/components/ProgressBars/Gauge.tsx @@ -77,7 +77,7 @@ export function getProgressColor( return palette.status.ok; } -export const Gauge = (props: Props) => { +export function Gauge(props: Props) { const classes = useStyles(props); const theme = useTheme(); const { value, fractional, inverse, unit, max } = { @@ -103,4 +103,4 @@ export const Gauge = (props: Props) => {
); -}; +} diff --git a/packages/core-components/src/components/ProgressBars/GaugeCard.tsx b/packages/core-components/src/components/ProgressBars/GaugeCard.tsx index 39248b1786..0a603ea991 100644 --- a/packages/core-components/src/components/ProgressBars/GaugeCard.tsx +++ b/packages/core-components/src/components/ProgressBars/GaugeCard.tsx @@ -37,7 +37,7 @@ const useStyles = makeStyles({ }, }); -export const GaugeCard = (props: Props) => { +export function GaugeCard(props: Props) { const classes = useStyles(props); const { title, subheader, progress, inverse, deepLink, variant } = props; @@ -53,4 +53,4 @@ export const GaugeCard = (props: Props) => { ); -}; +} diff --git a/packages/core-components/src/components/ProgressBars/LinearGauge.tsx b/packages/core-components/src/components/ProgressBars/LinearGauge.tsx index d733cb2eae..cf8c022852 100644 --- a/packages/core-components/src/components/ProgressBars/LinearGauge.tsx +++ b/packages/core-components/src/components/ProgressBars/LinearGauge.tsx @@ -28,7 +28,8 @@ type Props = { value: number; }; -export const LinearGauge = ({ value }: Props) => { +export function LinearGauge(props: Props) { + const { value } = props; const theme = useTheme(); if (isNaN(value)) { return null; @@ -50,4 +51,4 @@ export const LinearGauge = ({ value }: Props) => { ); -}; +} diff --git a/packages/core-components/src/components/ResponseErrorPanel/ResponseErrorPanel.tsx b/packages/core-components/src/components/ResponseErrorPanel/ResponseErrorPanel.tsx index ccfb706bf9..9f25e8290f 100644 --- a/packages/core-components/src/components/ResponseErrorPanel/ResponseErrorPanel.tsx +++ b/packages/core-components/src/components/ResponseErrorPanel/ResponseErrorPanel.tsx @@ -39,11 +39,8 @@ const useStyles = makeStyles(theme => ({ * Has special treatment for ResponseError errors, to display rich * server-provided information about what happened. */ -export const ResponseErrorPanel = ({ - title, - error, - defaultExpanded, -}: ErrorPanelProps) => { +export function ResponseErrorPanel(props: ErrorPanelProps) { + const { title, error, defaultExpanded } = props; const classes = useStyles(); if (error.name !== 'ResponseError') { @@ -93,4 +90,4 @@ export const ResponseErrorPanel = ({ ); -}; +} diff --git a/packages/core-components/src/components/Select/Select.tsx b/packages/core-components/src/components/Select/Select.tsx index b4512b3562..ae14545b29 100644 --- a/packages/core-components/src/components/Select/Select.tsx +++ b/packages/core-components/src/components/Select/Select.tsx @@ -106,15 +106,16 @@ export type SelectProps = { triggerReset?: boolean; }; -export const SelectComponent = ({ - multiple, - items, - label, - placeholder, - selected, - onChange, - triggerReset, -}: SelectProps) => { +export function SelectComponent(props: SelectProps) { + const { + multiple, + items, + label, + placeholder, + selected, + onChange, + triggerReset, + } = props; const classes = useStyles(); const [value, setValue] = useState( selected || (multiple ? [] : ''), @@ -228,4 +229,4 @@ export const SelectComponent = ({ ); -}; +} diff --git a/packages/core-components/src/components/SimpleStepper/SimpleStepper.tsx b/packages/core-components/src/components/SimpleStepper/SimpleStepper.tsx index 46b2ce551a..9ffb63c085 100644 --- a/packages/core-components/src/components/SimpleStepper/SimpleStepper.tsx +++ b/packages/core-components/src/components/SimpleStepper/SimpleStepper.tsx @@ -47,12 +47,8 @@ export interface StepperProps { activeStep?: number; } -export const SimpleStepper = ({ - children, - elevated, - onStepChange, - activeStep = 0, -}: PropsWithChildren) => { +export function SimpleStepper(props: PropsWithChildren) { + const { children, elevated, onStepChange, activeStep = 0 } = props; const [stepIndex, setStepIndex] = useState(activeStep); const [stepHistory, setStepHistory] = useState([0]); @@ -95,4 +91,4 @@ export const SimpleStepper = ({ {stepIndex >= Children.count(children) - 1 && endStep} ); -}; +} diff --git a/packages/core-components/src/components/SimpleStepper/SimpleStepperStep.tsx b/packages/core-components/src/components/SimpleStepper/SimpleStepperStep.tsx index 51fcee1f71..39383b934b 100644 --- a/packages/core-components/src/components/SimpleStepper/SimpleStepperStep.tsx +++ b/packages/core-components/src/components/SimpleStepper/SimpleStepperStep.tsx @@ -30,13 +30,8 @@ const useStyles = makeStyles(theme => ({ }, })); -export const SimpleStepperStep = ({ - title, - children, - end, - actions, - ...muiProps -}: PropsWithChildren) => { +export function SimpleStepperStep(props: PropsWithChildren) { + const { title, children, end, actions, ...muiProps } = props; const classes = useStyles(); // The end step is not a part of the stepper @@ -58,4 +53,4 @@ export const SimpleStepperStep = ({ ); -}; +} diff --git a/packages/core-components/src/components/Status/Status.tsx b/packages/core-components/src/components/Status/Status.tsx index 0b370a1397..2b2d40dee3 100644 --- a/packages/core-components/src/components/Status/Status.tsx +++ b/packages/core-components/src/components/Status/Status.tsx @@ -63,7 +63,7 @@ const useStyles = makeStyles(theme => ({ }, })); -export const StatusOK = (props: PropsWithChildren<{}>) => { +export function StatusOK(props: PropsWithChildren<{}>) { const classes = useStyles(props); return ( ) => { {...props} /> ); -}; +} -export const StatusWarning = (props: PropsWithChildren<{}>) => { +export function StatusWarning(props: PropsWithChildren<{}>) { const classes = useStyles(props); return ( ) => { {...props} /> ); -}; +} -export const StatusError = (props: PropsWithChildren<{}>) => { +export function StatusError(props: PropsWithChildren<{}>) { const classes = useStyles(props); return ( ) => { {...props} /> ); -}; +} -export const StatusPending = (props: PropsWithChildren<{}>) => { +export function StatusPending(props: PropsWithChildren<{}>) { const classes = useStyles(props); return ( ) => { {...props} /> ); -}; +} -export const StatusRunning = (props: PropsWithChildren<{}>) => { +export function StatusRunning(props: PropsWithChildren<{}>) { const classes = useStyles(props); return ( ) => { {...props} /> ); -}; +} -export const StatusAborted = (props: PropsWithChildren<{}>) => { +export function StatusAborted(props: PropsWithChildren<{}>) { const classes = useStyles(props); return ( ) => { {...props} /> ); -}; +} diff --git a/packages/core-components/src/components/StructuredMetadataTable/StructuredMetadataTable.tsx b/packages/core-components/src/components/StructuredMetadataTable/StructuredMetadataTable.tsx index 9b08123d1b..22a1a43b69 100644 --- a/packages/core-components/src/components/StructuredMetadataTable/StructuredMetadataTable.tsx +++ b/packages/core-components/src/components/StructuredMetadataTable/StructuredMetadataTable.tsx @@ -153,11 +153,8 @@ type Props = { options?: any; }; -export const StructuredMetadataTable = ({ - metadata, - dense = true, - options, -}: Props) => { +export function StructuredMetadataTable(props: Props) { + const { metadata, dense = true, options } = props; const metadataItems = mapToItems(metadata, options || {}); return {metadataItems}; -}; +} diff --git a/packages/core-components/src/components/SupportButton/SupportButton.tsx b/packages/core-components/src/components/SupportButton/SupportButton.tsx index 22ec5cf47e..8076636654 100644 --- a/packages/core-components/src/components/SupportButton/SupportButton.tsx +++ b/packages/core-components/src/components/SupportButton/SupportButton.tsx @@ -80,7 +80,8 @@ const SupportListItem = ({ item }: { item: SupportItem }) => { ); }; -export const SupportButton = ({ title, children }: SupportButtonProps) => { +export function SupportButton(props: SupportButtonProps) { + const { title, children } = props; const { items } = useSupportConfig(); const [popoverOpen, setPopoverOpen] = useState(false); @@ -160,4 +161,4 @@ export const SupportButton = ({ title, children }: SupportButtonProps) => { ); -}; +} diff --git a/packages/core-components/src/components/TabbedLayout/RoutedTabs.tsx b/packages/core-components/src/components/TabbedLayout/RoutedTabs.tsx index 52a2c29e2d..2a65c8ffc8 100644 --- a/packages/core-components/src/components/TabbedLayout/RoutedTabs.tsx +++ b/packages/core-components/src/components/TabbedLayout/RoutedTabs.tsx @@ -47,7 +47,8 @@ export function useSelectedSubRoute(subRoutes: SubRoute[]): { }; } -export const RoutedTabs = ({ routes }: { routes: SubRoute[] }) => { +export function RoutedTabs(props: { routes: SubRoute[] }) { + const { routes } = props; const navigate = useNavigate(); const { index, route, element } = useSelectedSubRoute(routes); const headerTabs = useMemo( @@ -80,4 +81,4 @@ export const RoutedTabs = ({ routes }: { routes: SubRoute[] }) => { ); -}; +} diff --git a/packages/core-components/src/components/TabbedLayout/TabbedLayout.tsx b/packages/core-components/src/components/TabbedLayout/TabbedLayout.tsx index f7671928f2..03f012b78f 100644 --- a/packages/core-components/src/components/TabbedLayout/TabbedLayout.tsx +++ b/packages/core-components/src/components/TabbedLayout/TabbedLayout.tsx @@ -82,10 +82,10 @@ export function createSubRoutesFromChildren( * * ``` */ -export const TabbedLayout = ({ children }: PropsWithChildren<{}>) => { - const routes = createSubRoutesFromChildren(children); +export function TabbedLayout(props: PropsWithChildren<{}>) { + const routes = createSubRoutesFromChildren(props.children); return ; -}; +} TabbedLayout.Route = Route; diff --git a/packages/core-components/src/components/Table/SubvalueCell.tsx b/packages/core-components/src/components/Table/SubvalueCell.tsx index 1dab2e1f49..fd7d3fd9fa 100644 --- a/packages/core-components/src/components/Table/SubvalueCell.tsx +++ b/packages/core-components/src/components/Table/SubvalueCell.tsx @@ -33,7 +33,8 @@ type SubvalueCellProps = { subvalue: React.ReactNode; }; -export const SubvalueCell = ({ value, subvalue }: SubvalueCellProps) => { +export function SubvalueCell(props: SubvalueCellProps) { + const { value, subvalue } = props; const classes = useSubvalueCellStyles(); return ( @@ -42,4 +43,4 @@ export const SubvalueCell = ({ value, subvalue }: SubvalueCellProps) => {
{subvalue}
); -}; +} diff --git a/packages/core-components/src/components/Table/Table.tsx b/packages/core-components/src/components/Table/Table.tsx index 22d8bff014..edc5fd33ce 100644 --- a/packages/core-components/src/components/Table/Table.tsx +++ b/packages/core-components/src/components/Table/Table.tsx @@ -263,21 +263,21 @@ export function TableToolbar(toolbarProps: { ); } -export function Table({ - columns, - options, - title, - subtitle, - filters, - initialState, - emptyContent, - onStateChange, - ...props -}: TableProps) { +export function Table(props: TableProps) { + const { + data, + columns, + options, + title, + subtitle, + filters, + initialState, + emptyContent, + onStateChange, + ...restProps + } = props; const tableClasses = useTableStyles(); - const { data, ...propsWithoutData } = props; - const theme = useTheme(); const calculatedInitialState = { ...defaultInitialState, ...initialState }; @@ -495,7 +495,7 @@ export function Table({ } data={typeof data === 'function' ? data : tableData} style={{ width: '100%' }} - {...propsWithoutData} + {...restProps} /> ); diff --git a/packages/core-components/src/components/Tabs/Tabs.tsx b/packages/core-components/src/components/Tabs/Tabs.tsx index ec9fecaca4..844f54a543 100644 --- a/packages/core-components/src/components/Tabs/Tabs.tsx +++ b/packages/core-components/src/components/Tabs/Tabs.tsx @@ -58,7 +58,8 @@ const useStyles = makeStyles(theme => ({ }, })); -export const Tabs = ({ tabs }: TabsProps) => { +export function Tabs(props: TabsProps) { + const { tabs } = props; const classes = useStyles(); const [value, setValue] = useState([0, 0]); // [selectedChunkedNavIndex, selectedIndex] const [navIndex, setNavIndex] = useState(0); @@ -160,4 +161,4 @@ export const Tabs = ({ tabs }: TabsProps) => { )} ); -}; +} diff --git a/packages/core-components/src/components/TrendLine/TrendLine.tsx b/packages/core-components/src/components/TrendLine/TrendLine.tsx index 0cbc2ca9d7..cb44d2b36b 100644 --- a/packages/core-components/src/components/TrendLine/TrendLine.tsx +++ b/packages/core-components/src/components/TrendLine/TrendLine.tsx @@ -32,10 +32,10 @@ function color(data: number[], theme: BackstageTheme): string | undefined { return theme.palette.status.error; } -export const TrendLine = ( +export function TrendLine( props: SparklinesProps & Pick & { title?: string }, -) => { +) { const theme = useTheme(); if (!props.data) return null; @@ -45,4 +45,4 @@ export const TrendLine = ( ); -}; +} diff --git a/packages/core-components/src/components/WarningPanel/WarningPanel.tsx b/packages/core-components/src/components/WarningPanel/WarningPanel.tsx index e6188172b7..536ab066b3 100644 --- a/packages/core-components/src/components/WarningPanel/WarningPanel.tsx +++ b/packages/core-components/src/components/WarningPanel/WarningPanel.tsx @@ -137,13 +137,14 @@ const capitalize = (s: string) => { * @param {Object} [children] Objects to provide context, such as a stack trace or detailed error reporting. * Will be available inside an unfolded accordion. */ -export const WarningPanel = ({ - severity = 'warning', - title, - message, - children, - defaultExpanded, -}: WarningProps) => { +export function WarningPanel(props: WarningProps) { + const { + severity = 'warning', + title, + message, + children, + defaultExpanded, + } = props; const classes = useStyles({ severity }); // If no severity or title provided, the heading will read simply "Warning" @@ -184,4 +185,4 @@ export const WarningPanel = ({ )} ); -}; +} From 653abaaada5ae5963fef805a2f338d29f98efe88 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 14:04:38 +0200 Subject: [PATCH 12/17] core-components: rewrite layout and icon components to use functions Signed-off-by: Patrik Oldsberg --- packages/core-components/api-report.md | 156 +++++------------- packages/core-components/src/icons/icons.tsx | 61 ++++--- .../src/layout/BottomLink/BottomLink.tsx | 5 +- .../src/layout/Breadcrumbs/Breadcrumbs.tsx | 7 +- .../src/layout/Content/Content.tsx | 13 +- .../layout/ContentHeader/ContentHeader.tsx | 17 +- .../src/layout/ErrorPage/ErrorPage.tsx | 9 +- .../src/layout/Header/Header.tsx | 23 +-- .../HeaderActionMenu/HeaderActionMenu.tsx | 5 +- .../src/layout/HeaderLabel/HeaderLabel.tsx | 5 +- .../src/layout/HeaderTabs/HeaderTabs.tsx | 9 +- .../layout/HomepageTimer/HomepageTimer.tsx | 4 +- .../src/layout/InfoCard/InfoCard.tsx | 43 ++--- .../src/layout/ItemCard/ItemCard.tsx | 15 +- .../src/layout/ItemCard/ItemCardGrid.tsx | 4 +- .../src/layout/ItemCard/ItemCardHeader.tsx | 4 +- .../core-components/src/layout/Page/Page.tsx | 5 +- .../src/layout/Page/PageWithHeader.tsx | 19 +-- .../src/layout/Sidebar/Bar.tsx | 13 +- .../src/layout/Sidebar/Intro.tsx | 8 +- .../src/layout/Sidebar/Items.tsx | 4 +- .../src/layout/Sidebar/Page.tsx | 4 +- .../src/layout/SignInPage/SignInPage.tsx | 4 +- .../src/layout/TabbedCard/TabbedCard.tsx | 30 ++-- 24 files changed, 199 insertions(+), 268 deletions(-) diff --git a/packages/core-components/api-report.md b/packages/core-components/api-report.md index 0f8ea308c6..f3652d98cf 100644 --- a/packages/core-components/api-report.md +++ b/packages/core-components/api-report.md @@ -74,12 +74,13 @@ export function Avatar(props: AvatarProps): JSX.Element; // Warning: (ae-missing-release-tag) "Breadcrumbs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Breadcrumbs: ({ children, ...props }: Props_24) => JSX.Element; +export function Breadcrumbs(props: Props_24): JSX.Element; +// Warning: (ae-forgotten-export) The symbol "IconComponentProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "BrokenImageIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const BrokenImageIcon: IconComponent; +export function BrokenImageIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "ButtonType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -91,20 +92,17 @@ export function Button(props: Props): JSX.Element; // Warning: (ae-missing-release-tag) "CardTab" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const CardTab: ({ - children, - ...props -}: PropsWithChildren) => JSX.Element; +export function CardTab(props: PropsWithChildren): JSX.Element; // Warning: (ae-missing-release-tag) "CatalogIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const CatalogIcon: IconComponent; +export function CatalogIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-missing-release-tag) "ChatIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const ChatIcon: IconComponent; +export function ChatIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "CodeSnippet" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -116,25 +114,15 @@ export const CodeSnippet: (props: Props_2) => JSX.Element; // Warning: (ae-missing-release-tag) "Content" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Content: ({ - className, - stretch, - noPadding, - children, - ...props -}: PropsWithChildren) => JSX.Element; +export function Content(props: PropsWithChildren): JSX.Element; // Warning: (ae-forgotten-export) The symbol "ContentHeaderProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "ContentHeader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const ContentHeader: ({ - description, - title, - titleComponent: TitleComponent, - children, - textAlign, -}: PropsWithChildren) => JSX.Element; +export function ContentHeader( + props: PropsWithChildren, +): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "CopyTextButton" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -162,7 +150,7 @@ export function CreateButton(props: CreateButtonProps): JSX.Element | null; // Warning: (ae-missing-release-tag) "DashboardIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const DashboardIcon: IconComponent; +export function DashboardIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "CustomType" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "DependencyEdge" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -229,7 +217,7 @@ export const DismissableBanner: (props: Props_4) => JSX.Element; // Warning: (ae-missing-release-tag) "DocsIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const DocsIcon: IconComponent; +export function DocsIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-missing-release-tag) "EdgeProperties" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -248,7 +236,7 @@ type EdgeProperties = { // Warning: (ae-missing-release-tag) "EmailIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const EmailIcon: IconComponent; +export function EmailIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "EmptyState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -274,11 +262,7 @@ export type ErrorBoundaryProps = { // Warning: (ae-missing-release-tag) "ErrorPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const ErrorPage: ({ - status, - statusMessage, - additionalInfo, -}: IErrorPageProps) => JSX.Element; +export function ErrorPage(props: IErrorPageProps): JSX.Element; // Warning: (ae-missing-release-tag) "ErrorPanel" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -319,7 +303,7 @@ export function GaugeCard(props: Props_13): JSX.Element; // Warning: (ae-missing-release-tag) "GitHubIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const GitHubIcon: IconComponent; +export function GitHubIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-missing-release-tag) "GraphEdge" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -336,22 +320,13 @@ type GraphNode = dagre_2.Node>; // Warning: (ae-missing-release-tag) "GroupIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const GroupIcon: IconComponent; +export function GroupIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "Header" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Header: ({ - children, - pageTitleOverride, - style, - subtitle, - title, - tooltip, - type, - typeLink, -}: PropsWithChildren) => JSX.Element; +export function Header(props: PropsWithChildren): JSX.Element; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "HeaderIconLinkRow" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -363,31 +338,23 @@ export function HeaderIconLinkRow(props: Props_8): JSX.Element; // Warning: (ae-missing-release-tag) "HeaderLabel" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const HeaderLabel: ({ - label, - value, - url, -}: HeaderLabelProps) => JSX.Element; +export function HeaderLabel(props: HeaderLabelProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "HeaderTabsProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "HeaderTabs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const HeaderTabs: ({ - tabs, - onChange, - selectedIndex, -}: HeaderTabsProps) => JSX.Element; +export function HeaderTabs(props: HeaderTabsProps): JSX.Element; // Warning: (ae-missing-release-tag) "HelpIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const HelpIcon: IconComponent; +export function HelpIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-missing-release-tag) "HomepageTimer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const HomepageTimer: () => JSX.Element | null; +export function HomepageTimer(_props: {}): JSX.Element | null; // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "HorizontalScrollGrid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -414,26 +381,7 @@ export type IconLinkVerticalProps = { // Warning: (ae-missing-release-tag) "InfoCard" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const InfoCard: ({ - title, - subheader, - divider, - deepLink, - slackChannel, - errorBoundaryProps, - variant, - children, - headerStyle, - headerProps, - action, - actionsClassName, - actions, - cardClassName, - actionsTopRight, - className, - noPadding, - titleTypographyProps, -}: Props_19) => JSX.Element; +export function InfoCard(props: Props_19): JSX.Element; // Warning: (ae-missing-release-tag) "InfoCardVariants" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -444,7 +392,7 @@ export type InfoCardVariants = 'flex' | 'fullHeight' | 'gridItem'; // Warning: (ae-missing-release-tag) "IntroCard" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const IntroCard: (props: IntroCardProps) => JSX.Element; +export function IntroCard(props: IntroCardProps): JSX.Element; // Warning: (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name // Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag @@ -452,16 +400,7 @@ export const IntroCard: (props: IntroCardProps) => JSX.Element; // Warning: (ae-missing-release-tag) "ItemCard" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @deprecated -export const ItemCard: ({ - description, - tags, - title, - type, - subtitle, - label, - onClick, - href, -}: ItemCardProps) => JSX.Element; +export function ItemCard(props: ItemCardProps): JSX.Element; // Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag @@ -472,7 +411,7 @@ export const ItemCard: ({ // Warning: (ae-missing-release-tag) "ItemCardGrid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public -export const ItemCardGrid: (props: ItemCardGridProps) => JSX.Element; +export function ItemCardGrid(props: ItemCardGridProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "styles" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "ItemCardGridProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -491,7 +430,7 @@ export type ItemCardGridProps = Partial> & { // Warning: (ae-missing-release-tag) "ItemCardHeader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public -export const ItemCardHeader: (props: ItemCardHeaderProps) => JSX.Element; +export function ItemCardHeader(props: ItemCardHeaderProps): JSX.Element; // Warning: (ae-forgotten-export) The symbol "styles" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "ItemCardHeaderProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -567,20 +506,15 @@ export function OverflowTooltip(props: Props_12): JSX.Element; // Warning: (ae-missing-release-tag) "Page" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Page: ({ - themeId, - children, -}: PropsWithChildren) => JSX.Element; +export function Page(props: PropsWithChildren): JSX.Element; // Warning: (ae-forgotten-export) The symbol "PageWithHeaderProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "PageWithHeader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const PageWithHeader: ({ - themeId, - children, - ...props -}: PropsWithChildren) => JSX.Element; +export function PageWithHeader( + props: PropsWithChildren, +): JSX.Element; // Warning: (ae-missing-release-tag) "Progress" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -645,11 +579,7 @@ export function Select(props: SelectProps): JSX.Element; // Warning: (ae-missing-release-tag) "Sidebar" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const Sidebar: ({ - openDelayMs, - closeDelayMs, - children, -}: PropsWithChildren) => JSX.Element; +export function Sidebar(props: PropsWithChildren): JSX.Element; // Warning: (ae-missing-release-tag) "SIDEBAR_INTRO_LOCAL_STORAGE" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -959,7 +889,7 @@ export const SidebarDivider: React_2.ComponentType< // Warning: (ae-missing-release-tag) "SidebarIntro" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const SidebarIntro: () => JSX.Element | null; +export function SidebarIntro(_props: {}): JSX.Element | null; // Warning: (ae-forgotten-export) The symbol "SidebarItemProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "SidebarItem" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -972,7 +902,7 @@ export const SidebarItem: React_2.ForwardRefExoticComponent< // Warning: (ae-missing-release-tag) "SidebarPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const SidebarPage: (props: PropsWithChildren<{}>) => JSX.Element; +export function SidebarPage(props: PropsWithChildren<{}>): JSX.Element; // Warning: (ae-missing-release-tag) "SidebarPinStateContext" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -1260,9 +1190,7 @@ export const SidebarScrollWrapper: React_2.ComponentType< // Warning: (ae-missing-release-tag) "SidebarSearchField" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const SidebarSearchField: ( - props: SidebarSearchFieldProps, -) => JSX.Element; +export function SidebarSearchField(props: SidebarSearchFieldProps): JSX.Element; // Warning: (ae-missing-release-tag) "SidebarSpace" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -1806,7 +1734,7 @@ export const SidebarSpacer: React_2.ComponentType< // Warning: (ae-missing-release-tag) "SignInPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const SignInPage: (props: Props_22) => JSX.Element; +export function SignInPage(props: Props_22): JSX.Element; // Warning: (ae-missing-release-tag) "SignInProviderConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -1925,15 +1853,7 @@ export type Tab = { // Warning: (ae-missing-release-tag) "TabbedCard" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const TabbedCard: ({ - slackChannel, - errorBoundaryProps, - children, - title, - deepLink, - value, - onChange, -}: PropsWithChildren) => JSX.Element; +export function TabbedCard(props: PropsWithChildren): JSX.Element; // Warning: (ae-missing-release-tag) "TabbedLayout" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // Warning: (ae-missing-release-tag) "TabbedLayout" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -2028,7 +1948,7 @@ export function useQueryParamState( // Warning: (ae-missing-release-tag) "UserIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const UserIcon: IconComponent; +export function UserIcon(props: IconComponentProps): JSX.Element; // Warning: (ae-missing-release-tag) "useSupportConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -2038,7 +1958,7 @@ export function useSupportConfig(): SupportConfig; // Warning: (ae-missing-release-tag) "WarningIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const WarningIcon: IconComponent; +export function WarningIcon(props: IconComponentProps): JSX.Element; // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets. diff --git a/packages/core-components/src/icons/icons.tsx b/packages/core-components/src/icons/icons.tsx index 258bc9f8e1..7a9f7f9832 100644 --- a/packages/core-components/src/icons/icons.tsx +++ b/packages/core-components/src/icons/icons.tsx @@ -15,27 +15,48 @@ */ import MuiBrokenImageIcon from '@material-ui/icons/BrokenImage'; -import React from 'react'; +import React, { ComponentProps } from 'react'; import { useApp, IconComponent } from '@backstage/core-plugin-api'; -const overridableSystemIcon = (key: string): IconComponent => { - const Component: IconComponent = props => { - const app = useApp(); - const Icon = app.getSystemIcon(key); - return Icon ? : ; - }; - return Component; -}; +type IconComponentProps = ComponentProps; + +function useSystemIcon(key: string, props: IconComponentProps) { + const app = useApp(); + const Icon = app.getSystemIcon(key); + return Icon ? : ; +} // Should match the list of overridable system icon keys in @backstage/core-app-api -export const BrokenImageIcon = overridableSystemIcon('brokenImage'); -export const CatalogIcon = overridableSystemIcon('catalog'); -export const ChatIcon = overridableSystemIcon('chat'); -export const DashboardIcon = overridableSystemIcon('dashboard'); -export const DocsIcon = overridableSystemIcon('docs'); -export const EmailIcon = overridableSystemIcon('email'); -export const GitHubIcon = overridableSystemIcon('github'); -export const GroupIcon = overridableSystemIcon('group'); -export const HelpIcon = overridableSystemIcon('help'); -export const UserIcon = overridableSystemIcon('user'); -export const WarningIcon = overridableSystemIcon('warning'); +export function BrokenImageIcon(props: IconComponentProps) { + return useSystemIcon('brokenImage', props); +} +export function CatalogIcon(props: IconComponentProps) { + return useSystemIcon('catalog', props); +} +export function ChatIcon(props: IconComponentProps) { + return useSystemIcon('chat', props); +} +export function DashboardIcon(props: IconComponentProps) { + return useSystemIcon('dashboard', props); +} +export function DocsIcon(props: IconComponentProps) { + return useSystemIcon('docs', props); +} +export function EmailIcon(props: IconComponentProps) { + return useSystemIcon('email', props); +} +export function GitHubIcon(props: IconComponentProps) { + return useSystemIcon('github', props); +} +export function GroupIcon(props: IconComponentProps) { + return useSystemIcon('group', props); +} +export function HelpIcon(props: IconComponentProps) { + return useSystemIcon('help', props); +} +export function UserIcon(props: IconComponentProps) { + return useSystemIcon('user', props); +} +export function WarningIcon(props: IconComponentProps) { + return useSystemIcon('warning', props); +} diff --git a/packages/core-components/src/layout/BottomLink/BottomLink.tsx b/packages/core-components/src/layout/BottomLink/BottomLink.tsx index 74912acf4c..6d6811cc09 100644 --- a/packages/core-components/src/layout/BottomLink/BottomLink.tsx +++ b/packages/core-components/src/layout/BottomLink/BottomLink.tsx @@ -41,7 +41,8 @@ export type BottomLinkProps = { onClick?: (event: React.MouseEvent) => void; }; -export const BottomLink = ({ link, title, onClick }: BottomLinkProps) => { +export function BottomLink(props: BottomLinkProps) { + const { link, title, onClick } = props; const classes = useStyles(); return ( @@ -59,4 +60,4 @@ export const BottomLink = ({ link, title, onClick }: BottomLinkProps) => { ); -}; +} diff --git a/packages/core-components/src/layout/Breadcrumbs/Breadcrumbs.tsx b/packages/core-components/src/layout/Breadcrumbs/Breadcrumbs.tsx index 418217f3b5..28c86d32f0 100644 --- a/packages/core-components/src/layout/Breadcrumbs/Breadcrumbs.tsx +++ b/packages/core-components/src/layout/Breadcrumbs/Breadcrumbs.tsx @@ -41,7 +41,8 @@ const StyledBox = withStyles({ }, })(Box); -export const Breadcrumbs = ({ children, ...props }: Props) => { +export function Breadcrumbs(props: Props) { + const { children, ...restProps } = props; const [anchorEl, setAnchorEl] = React.useState( null, ); @@ -65,7 +66,7 @@ export const Breadcrumbs = ({ children, ...props }: Props) => { const open = Boolean(anchorEl); return ( - + {childrenArray.length > 1 && {firstPage}} {childrenArray.length > 2 && {secondPage}} {hasHiddenBreadcrumbs && ( @@ -96,4 +97,4 @@ export const Breadcrumbs = ({ children, ...props }: Props) => { ); -}; +} diff --git a/packages/core-components/src/layout/Content/Content.tsx b/packages/core-components/src/layout/Content/Content.tsx index 323565159a..a3771dff3f 100644 --- a/packages/core-components/src/layout/Content/Content.tsx +++ b/packages/core-components/src/layout/Content/Content.tsx @@ -47,17 +47,12 @@ type Props = { className?: string; }; -export const Content = ({ - className, - stretch, - noPadding, - children, - ...props -}: PropsWithChildren) => { +export function Content(props: PropsWithChildren) { + const { className, stretch, noPadding, children, ...restProps } = props; const classes = useStyles(); return (
); -}; +} diff --git a/packages/core-components/src/layout/ContentHeader/ContentHeader.tsx b/packages/core-components/src/layout/ContentHeader/ContentHeader.tsx index 2259731148..76fec703a9 100644 --- a/packages/core-components/src/layout/ContentHeader/ContentHeader.tsx +++ b/packages/core-components/src/layout/ContentHeader/ContentHeader.tsx @@ -82,13 +82,14 @@ type ContentHeaderProps = { textAlign?: 'left' | 'right' | 'center'; }; -export const ContentHeader = ({ - description, - title, - titleComponent: TitleComponent = undefined, - children, - textAlign = 'left', -}: PropsWithChildren) => { +export function ContentHeader(props: PropsWithChildren) { + const { + description, + title, + titleComponent: TitleComponent = undefined, + children, + textAlign = 'left', + } = props; const classes = useStyles({ textAlign })(); const renderedTitle = TitleComponent ? ( @@ -112,4 +113,4 @@ export const ContentHeader = ({ ); -}; +} diff --git a/packages/core-components/src/layout/ErrorPage/ErrorPage.tsx b/packages/core-components/src/layout/ErrorPage/ErrorPage.tsx index cca88147c4..f4b2960f96 100644 --- a/packages/core-components/src/layout/ErrorPage/ErrorPage.tsx +++ b/packages/core-components/src/layout/ErrorPage/ErrorPage.tsx @@ -47,11 +47,8 @@ const useStyles = makeStyles(theme => ({ }, })); -export const ErrorPage = ({ - status, - statusMessage, - additionalInfo, -}: IErrorPageProps) => { +export function ErrorPage(props: IErrorPageProps) { + const { status, statusMessage, additionalInfo } = props; const classes = useStyles(); const navigate = useNavigate(); const support = useSupportConfig(); @@ -82,4 +79,4 @@ export const ErrorPage = ({ ); -}; +} diff --git a/packages/core-components/src/layout/Header/Header.tsx b/packages/core-components/src/layout/Header/Header.tsx index 3b2771e299..dd56505720 100644 --- a/packages/core-components/src/layout/Header/Header.tsx +++ b/packages/core-components/src/layout/Header/Header.tsx @@ -174,16 +174,17 @@ const SubtitleFragment = ({ classes, subtitle }: SubtitleFragmentProps) => { ); }; -export const Header = ({ - children, - pageTitleOverride, - style, - subtitle, - title, - tooltip, - type, - typeLink, -}: PropsWithChildren) => { +export function Header(props: PropsWithChildren) { + const { + children, + pageTitleOverride, + style, + subtitle, + title, + tooltip, + type, + typeLink, + } = props; const classes = useStyles(); const configApi = useApi(configApiRef); const appTitle = configApi.getOptionalString('app.title') || 'Backstage'; @@ -216,4 +217,4 @@ export const Header = ({ ); -}; +} diff --git a/packages/core-components/src/layout/HeaderActionMenu/HeaderActionMenu.tsx b/packages/core-components/src/layout/HeaderActionMenu/HeaderActionMenu.tsx index 06a9b2b701..5243a65498 100644 --- a/packages/core-components/src/layout/HeaderActionMenu/HeaderActionMenu.tsx +++ b/packages/core-components/src/layout/HeaderActionMenu/HeaderActionMenu.tsx @@ -66,7 +66,8 @@ export type HeaderActionMenuProps = { actionItems: ActionItemProps[]; }; -export const HeaderActionMenu = ({ actionItems }: HeaderActionMenuProps) => { +export function HeaderActionMenu(props: HeaderActionMenuProps) { + const { actionItems } = props; const [open, setOpen] = React.useState(false); const anchorElRef = React.useRef(null); @@ -103,4 +104,4 @@ export const HeaderActionMenu = ({ actionItems }: HeaderActionMenuProps) => { ); -}; +} diff --git a/packages/core-components/src/layout/HeaderLabel/HeaderLabel.tsx b/packages/core-components/src/layout/HeaderLabel/HeaderLabel.tsx index 8557ceddf7..88f6e26bf5 100644 --- a/packages/core-components/src/layout/HeaderLabel/HeaderLabel.tsx +++ b/packages/core-components/src/layout/HeaderLabel/HeaderLabel.tsx @@ -51,7 +51,8 @@ type HeaderLabelProps = { url?: string; }; -export const HeaderLabel = ({ label, value, url }: HeaderLabelProps) => { +export function HeaderLabel(props: HeaderLabelProps) { + const { label, value, url } = props; const classes = useStyles(); const content = ( { ); -}; +} diff --git a/packages/core-components/src/layout/HeaderTabs/HeaderTabs.tsx b/packages/core-components/src/layout/HeaderTabs/HeaderTabs.tsx index 20742114c9..0fe3cd967e 100644 --- a/packages/core-components/src/layout/HeaderTabs/HeaderTabs.tsx +++ b/packages/core-components/src/layout/HeaderTabs/HeaderTabs.tsx @@ -55,11 +55,8 @@ type HeaderTabsProps = { onChange?: (index: number) => void; selectedIndex?: number; }; -export const HeaderTabs = ({ - tabs, - onChange, - selectedIndex, -}: HeaderTabsProps) => { +export function HeaderTabs(props: HeaderTabsProps) { + const { tabs, onChange, selectedIndex } = props; const [selectedTab, setSelectedTab] = useState(selectedIndex ?? 0); const styles = useStyles(); @@ -101,4 +98,4 @@ export const HeaderTabs = ({ ); -}; +} diff --git a/packages/core-components/src/layout/HomepageTimer/HomepageTimer.tsx b/packages/core-components/src/layout/HomepageTimer/HomepageTimer.tsx index 04073cca48..a78f4af8ca 100644 --- a/packages/core-components/src/layout/HomepageTimer/HomepageTimer.tsx +++ b/packages/core-components/src/layout/HomepageTimer/HomepageTimer.tsx @@ -67,7 +67,7 @@ function getTimes(configApi: ConfigApi) { return clocks; } -export const HomepageTimer = () => { +export function HomepageTimer(_props: {}) { const configApi = useApi(configApiRef); const defaultTimes: TimeObj[] = []; @@ -99,4 +99,4 @@ export const HomepageTimer = () => { ); } return null; -}; +} diff --git a/packages/core-components/src/layout/InfoCard/InfoCard.tsx b/packages/core-components/src/layout/InfoCard/InfoCard.tsx index 650bf78bbd..36205b0dc0 100644 --- a/packages/core-components/src/layout/InfoCard/InfoCard.tsx +++ b/packages/core-components/src/layout/InfoCard/InfoCard.tsx @@ -128,26 +128,27 @@ type Props = { titleTypographyProps?: object; }; -export const InfoCard = ({ - title, - subheader, - divider = true, - deepLink, - slackChannel, - errorBoundaryProps, - variant, - children, - headerStyle, - headerProps, - action, - actionsClassName, - actions, - cardClassName, - actionsTopRight, - className, - noPadding, - titleTypographyProps, -}: Props): JSX.Element => { +export function InfoCard(props: Props): JSX.Element { + const { + title, + subheader, + divider = true, + deepLink, + slackChannel, + errorBoundaryProps, + variant, + children, + headerStyle, + headerProps, + action, + actionsClassName, + actions, + cardClassName, + actionsTopRight, + className, + noPadding, + titleTypographyProps, + } = props; const classes = useStyles(); /** * If variant is specified, we build up styles for that particular variant for both @@ -214,4 +215,4 @@ export const InfoCard = ({ ); -}; +} diff --git a/packages/core-components/src/layout/ItemCard/ItemCard.tsx b/packages/core-components/src/layout/ItemCard/ItemCard.tsx index b4273ee837..81a88d2c09 100644 --- a/packages/core-components/src/layout/ItemCard/ItemCard.tsx +++ b/packages/core-components/src/layout/ItemCard/ItemCard.tsx @@ -62,16 +62,9 @@ type ItemCardProps = { * @deprecated Use plain MUI and composable helpers instead. * @see https://material-ui.com/components/cards/ */ -export const ItemCard = ({ - description, - tags, - title, - type, - subtitle, - label, - onClick, - href, -}: ItemCardProps) => { +export function ItemCard(props: ItemCardProps) { + const { description, tags, title, type, subtitle, label, onClick, href } = + props; return ( @@ -101,4 +94,4 @@ export const ItemCard = ({ ); -}; +} diff --git a/packages/core-components/src/layout/ItemCard/ItemCardGrid.tsx b/packages/core-components/src/layout/ItemCard/ItemCardGrid.tsx index a5c57ba246..137c48d272 100644 --- a/packages/core-components/src/layout/ItemCard/ItemCardGrid.tsx +++ b/packages/core-components/src/layout/ItemCard/ItemCardGrid.tsx @@ -51,7 +51,7 @@ export type ItemCardGridProps = Partial> & { * This can be useful for e.g. overriding gridTemplateColumns to adapt the * minimum size of the cells to fit the content better. */ -export const ItemCardGrid = (props: ItemCardGridProps) => { +export function ItemCardGrid(props: ItemCardGridProps) { const { children, ...otherProps } = props; const classes = useStyles(otherProps); return ( @@ -59,4 +59,4 @@ export const ItemCardGrid = (props: ItemCardGridProps) => { {children} ); -}; +} diff --git a/packages/core-components/src/layout/ItemCard/ItemCardHeader.tsx b/packages/core-components/src/layout/ItemCard/ItemCardHeader.tsx index 58c7c1501d..15a1a7d78b 100644 --- a/packages/core-components/src/layout/ItemCard/ItemCardHeader.tsx +++ b/packages/core-components/src/layout/ItemCard/ItemCardHeader.tsx @@ -72,7 +72,7 @@ export type ItemCardHeaderProps = Partial> & { * * */ -export const ItemCardHeader = (props: ItemCardHeaderProps) => { +export function ItemCardHeader(props: ItemCardHeaderProps) { const { title, subtitle, children } = props; const classes = useStyles(props); return ( @@ -90,4 +90,4 @@ export const ItemCardHeader = (props: ItemCardHeaderProps) => { {children} ); -}; +} diff --git a/packages/core-components/src/layout/Page/Page.tsx b/packages/core-components/src/layout/Page/Page.tsx index f78dc038f2..b838693a3c 100644 --- a/packages/core-components/src/layout/Page/Page.tsx +++ b/packages/core-components/src/layout/Page/Page.tsx @@ -34,7 +34,8 @@ type Props = { themeId: string; }; -export const Page = ({ themeId, children }: PropsWithChildren) => { +export function Page(props: PropsWithChildren) { + const { themeId, children } = props; const classes = useStyles(); return ( ) => {
{children}
 ); -}; +} diff --git a/packages/core-components/src/layout/Page/PageWithHeader.tsx b/packages/core-components/src/layout/Page/PageWithHeader.tsx index 70a6c1f693..541b655dff 100644 --- a/packages/core-components/src/layout/Page/PageWithHeader.tsx +++ b/packages/core-components/src/layout/Page/PageWithHeader.tsx @@ -23,13 +23,12 @@ type PageWithHeaderProps = ComponentProps & { themeId: string; }; -export const PageWithHeader = ({ - themeId, - children, - ...props -}: PropsWithChildren) => ( - -
- {children} - -); +export function PageWithHeader(props: PropsWithChildren) { + const { themeId, children, ...restProps } = props; + return ( + +
+ {children} + + ); +} diff --git a/packages/core-components/src/layout/Sidebar/Bar.tsx b/packages/core-components/src/layout/Sidebar/Bar.tsx index f928c4b7c4..8855f01104 100644 --- a/packages/core-components/src/layout/Sidebar/Bar.tsx +++ b/packages/core-components/src/layout/Sidebar/Bar.tsx @@ -74,11 +74,12 @@ type Props = { closeDelayMs?: number; }; -export const Sidebar = ({ - openDelayMs = sidebarConfig.defaultOpenDelayMs, - closeDelayMs = sidebarConfig.defaultCloseDelayMs, - children, -}: PropsWithChildren) => { +export function Sidebar(props: PropsWithChildren) { + const { + openDelayMs = sidebarConfig.defaultOpenDelayMs, + closeDelayMs = sidebarConfig.defaultCloseDelayMs, + children, + } = props; const classes = useStyles(); const isSmallScreen = useMediaQuery(theme => theme.breakpoints.down('md'), @@ -149,4 +150,4 @@ export const Sidebar = ({ ); -}; +} diff --git a/packages/core-components/src/layout/Sidebar/Intro.tsx b/packages/core-components/src/layout/Sidebar/Intro.tsx index 14c5d9e25a..45098b49e1 100644 --- a/packages/core-components/src/layout/Sidebar/Intro.tsx +++ b/packages/core-components/src/layout/Sidebar/Intro.tsx @@ -74,7 +74,7 @@ type IntroCardProps = { onClose: () => void; }; -export const IntroCard = (props: IntroCardProps) => { +export function IntroCard(props: IntroCardProps) { const classes = useStyles(); const { text, onClose } = props; const handleClose = () => onClose(); @@ -97,7 +97,7 @@ export const IntroCard = (props: IntroCardProps) => { ); -}; +} type SidebarIntroLocalStorage = { starredItemsDismissed: boolean; @@ -127,7 +127,7 @@ Keep an eye out for the little star icon (⭐) next to the plugin name and give const recentlyViewedIntroText = 'And your recently viewed plugins will pop up here!'; -export const SidebarIntro = () => { +export function SidebarIntro(_props: {}) { const { isOpen } = useContext(SidebarContext); const defaultValue = { starredItemsDismissed: false, @@ -177,4 +177,4 @@ export const SidebarIntro = () => { )} ); -}; +} diff --git a/packages/core-components/src/layout/Sidebar/Items.tsx b/packages/core-components/src/layout/Sidebar/Items.tsx index 1068a877bd..b3acc36f98 100644 --- a/packages/core-components/src/layout/Sidebar/Items.tsx +++ b/packages/core-components/src/layout/Sidebar/Items.tsx @@ -282,7 +282,7 @@ type SidebarSearchFieldProps = { to?: string; }; -export const SidebarSearchField = (props: SidebarSearchFieldProps) => { +export function SidebarSearchField(props: SidebarSearchFieldProps) { const [input, setInput] = useState(''); const classes = useStyles(); @@ -334,7 +334,7 @@ export const SidebarSearchField = (props: SidebarSearchFieldProps) => { ); -}; +} export const SidebarSpace = styled('div')({ flex: 1, diff --git a/packages/core-components/src/layout/Sidebar/Page.tsx b/packages/core-components/src/layout/Sidebar/Page.tsx index 0ace7468ef..47c5878cde 100644 --- a/packages/core-components/src/layout/Sidebar/Page.tsx +++ b/packages/core-components/src/layout/Sidebar/Page.tsx @@ -49,7 +49,7 @@ export const SidebarPinStateContext = createContext( }, ); -export const SidebarPage = (props: PropsWithChildren<{}>) => { +export function SidebarPage(props: PropsWithChildren<{}>) { const [isPinned, setIsPinned] = useState(() => LocalStorage.getSidebarPinState(), ); @@ -71,4 +71,4 @@ export const SidebarPage = (props: PropsWithChildren<{}>) => {
{props.children}
); -}; +} diff --git a/packages/core-components/src/layout/SignInPage/SignInPage.tsx b/packages/core-components/src/layout/SignInPage/SignInPage.tsx index dcaad83c72..e0d4f6ed0d 100644 --- a/packages/core-components/src/layout/SignInPage/SignInPage.tsx +++ b/packages/core-components/src/layout/SignInPage/SignInPage.tsx @@ -192,10 +192,10 @@ export const SingleSignInPage = ({ ); }; -export const SignInPage = (props: Props) => { +export function SignInPage(props: Props) { if ('provider' in props) { return ; } return ; -}; +} diff --git a/packages/core-components/src/layout/TabbedCard/TabbedCard.tsx b/packages/core-components/src/layout/TabbedCard/TabbedCard.tsx index c9f2a477ef..f350b24f1d 100644 --- a/packages/core-components/src/layout/TabbedCard/TabbedCard.tsx +++ b/packages/core-components/src/layout/TabbedCard/TabbedCard.tsx @@ -62,15 +62,16 @@ type Props = { deepLink?: BottomLinkProps; }; -const TabbedCard = ({ - slackChannel, - errorBoundaryProps, - children, - title, - deepLink, - value, - onChange, -}: PropsWithChildren) => { +export function TabbedCard(props: PropsWithChildren) { + const { + slackChannel, + errorBoundaryProps, + children, + title, + deepLink, + value, + onChange, + } = props; const tabsClasses = useTabsStyles(); const [selectedIndex, selectIndex] = useState(0); @@ -111,7 +112,7 @@ const TabbedCard = ({ ); -}; +} const useCardTabStyles = makeStyles(theme => ({ root: { @@ -135,10 +136,9 @@ type CardTabProps = TabProps & { children: ReactNode; }; -const CardTab = ({ children, ...props }: PropsWithChildren) => { +export function CardTab(props: PropsWithChildren) { + const { children, ...restProps } = props; const classes = useCardTabStyles(); - return ; -}; - -export { TabbedCard, CardTab }; + return ; +} From 90ee6678159e474a69378975620f9eead67436ab Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 14:38:49 +0200 Subject: [PATCH 13/17] workflows: skip doc link verification in microsite CI Signed-off-by: Patrik Oldsberg --- .github/workflows/microsite-build-check.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/microsite-build-check.yml b/.github/workflows/microsite-build-check.yml index 68a6c08cd9..73f63ed63a 100644 --- a/.github/workflows/microsite-build-check.yml +++ b/.github/workflows/microsite-build-check.yml @@ -27,9 +27,6 @@ jobs: with: node-version: ${{ matrix.node-version }} - - name: verify doc links - run: node scripts/verify-links.js - # Skip caching of microsite dependencies, it keeps the global cache size # smaller, which make Windows builds a lot faster for the rest of the project. - name: yarn install From 6db4de79a17cbcf0f4c6f4d05e4e287fa6307343 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 14:39:22 +0200 Subject: [PATCH 14/17] explore: format API report Signed-off-by: Patrik Oldsberg --- plugins/explore/api-report.md | 67 +++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 27 deletions(-) diff --git a/plugins/explore/api-report.md b/plugins/explore/api-report.md index 6ed2be6cde..2d04574f88 100644 --- a/plugins/explore/api-report.md +++ b/plugins/explore/api-report.md @@ -3,11 +3,10 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts - /// import { BackstagePlugin } from '@backstage/core-plugin-api'; -import { default } from 'react'; +import { default as default_2 } from 'react'; import { ExternalRouteRef } from '@backstage/core-plugin-api'; import { RouteRef } from '@backstage/core-plugin-api'; import { TabProps } from '@material-ui/core'; @@ -15,25 +14,30 @@ import { TabProps } from '@material-ui/core'; // Warning: (ae-missing-release-tag) "catalogEntityRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const catalogEntityRouteRef: ExternalRouteRef< { -name: string; -kind: string; -namespace: string; -}, false>; +export const catalogEntityRouteRef: ExternalRouteRef< + { + name: string; + kind: string; + namespace: string; + }, + false +>; // Warning: (ae-missing-release-tag) "DomainExplorerContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const DomainExplorerContent: ({ title, }: { - title?: string | undefined; +export const DomainExplorerContent: ({ + title, +}: { + title?: string | undefined; }) => JSX.Element; // Warning: (ae-missing-release-tag) "ExploreLayout" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public export const ExploreLayout: { - ({ title, subtitle, children, }: ExploreLayoutProps): JSX.Element; - Route: (props: SubRoute) => null; + ({ title, subtitle, children }: ExploreLayoutProps): JSX.Element; + Route: (props: SubRoute) => null; }; // Warning: (ae-missing-release-tag) "ExplorePage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -44,17 +48,23 @@ export const ExplorePage: () => JSX.Element; // Warning: (ae-missing-release-tag) "explorePlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -const explorePlugin: BackstagePlugin< { -explore: RouteRef; -}, { -catalogEntity: ExternalRouteRef< { -name: string; -kind: string; -namespace: string; -}, false>; -}>; -export { explorePlugin } -export { explorePlugin as plugin } +const explorePlugin: BackstagePlugin< + { + explore: RouteRef; + }, + { + catalogEntity: ExternalRouteRef< + { + name: string; + kind: string; + namespace: string; + }, + false + >; + } +>; +export { explorePlugin }; +export { explorePlugin as plugin }; // Warning: (ae-missing-release-tag) "exploreRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -64,15 +74,19 @@ export const exploreRouteRef: RouteRef; // Warning: (ae-missing-release-tag) "GroupsExplorerContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const GroupsExplorerContent: ({ title, }: { - title?: string | undefined; +export const GroupsExplorerContent: ({ + title, +}: { + title?: string | undefined; }) => JSX.Element; // Warning: (ae-missing-release-tag) "ToolExplorerContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const ToolExplorerContent: ({ title }: { - title?: string | undefined; +export const ToolExplorerContent: ({ + title, +}: { + title?: string | undefined; }) => JSX.Element; // Warnings were encountered during analysis: @@ -81,5 +95,4 @@ export const ToolExplorerContent: ({ title }: { // src/components/ExploreLayout/ExploreLayout.d.ts:30:5 - (ae-forgotten-export) The symbol "SubRoute" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) - ``` From 7e32ac97cb9a87d683ca92fcb3f4e3e75a3396b4 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 15:31:00 +0200 Subject: [PATCH 15/17] microsite: add hardcoded reference/index to sidebar verification Signed-off-by: Patrik Oldsberg --- microsite/scripts/verify-sidebars.js | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/microsite/scripts/verify-sidebars.js b/microsite/scripts/verify-sidebars.js index 8d643b15a2..301a1cb4c0 100755 --- a/microsite/scripts/verify-sidebars.js +++ b/microsite/scripts/verify-sidebars.js @@ -28,15 +28,18 @@ try { } const errors = []; -const ids = Object.keys(metadata); -for (let id of ids) { + +// reference/index is generated, so make sure this goes through even if it's not there +const knownIds = new Set([...Object.keys(metadata), 'reference/index']); + +for (const id in metadata) { const { next, previous } = metadata[id]; - if (next && !ids.includes(next)) { + if (next && !knownIds.has(next)) { errors.push(`Next ${next} does not exist in ${id}.`); } - if (previous && !ids.includes(previous)) { + if (previous && !knownIds.has(previous)) { errors.push(`Previous ${previous} does not exist in ${id}.`); } } From e65c42aa77b128884def1711e1e701d949aa52e4 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 15:36:48 +0200 Subject: [PATCH 16/17] docs: fix reference links Signed-off-by: Patrik Oldsberg --- docs/api/utility-apis.md | 90 +++++++++++++-------------- docs/conf/reading.md | 4 +- docs/plugins/structure-of-a-plugin.md | 4 +- 3 files changed, 49 insertions(+), 49 deletions(-) diff --git a/docs/api/utility-apis.md b/docs/api/utility-apis.md index 1a1e29c19c..1b364bcdae 100644 --- a/docs/api/utility-apis.md +++ b/docs/api/utility-apis.md @@ -13,31 +13,31 @@ both with other plugins and the app itself. Backstage provides two primary methods for plugins to communicate across their boundaries in client-side code. The first one being the -[createPlugin](../reference/core-plugin-api.createPlugin.md) API along with the +[createPlugin](../reference/core-plugin-api.createplugin.md) API along with the extensions that it can provide, and the second one being Utility APIs. While the -[createPlugin](../reference/core-plugin-api.createPlugin.md) API is focused on +[createPlugin](../reference/core-plugin-api.createplugin.md) API is focused on the initialization plugins and the app, the Utility APIs provide ways for plugins to communicate during their entire life cycle. ## Consuming APIs -Each Utility API is tied to an [ApiRef](../reference/core-plugin-api.ApiRef.md) +Each Utility API is tied to an [ApiRef](../reference/core-plugin-api.apiref.md) instance, which is a global singleton object without any additional state or functionality, its only purpose is to reference Utility APIs. -[ApiRef](../reference/core-plugin-api.ApiRef.md)s are created using -[createApiRef](../reference/core-plugin-api.createApiRef.md), which is exported +[ApiRef](../reference/core-plugin-api.apiref.md)s are created using +[createApiRef](../reference/core-plugin-api.createapiref.md), which is exported by [@backstage/core-plugin-api](../reference/core-plugin-api.md). There are also many predefined Utility APIs in [@backstage/core-plugin-api](../reference/core-plugin-api.md), and they're all exported with a name of the pattern `*ApiRef`, for example -[errorApiRef](../reference/core-plugin-api.errorApiRef.md). +[errorApiRef](../reference/core-plugin-api.errorapiref.md). To access one of the Utility APIs inside a React component, use the -[useApi](../reference/core-plugin-api.useApi.md) hook exported by +[useApi](../reference/core-plugin-api.useapi.md) hook exported by [@backstage/core-plugin-api](../reference/core-plugin-api.md), or the -[withApis](../reference/core-plugin-api.withApis.md) HOC if you prefer class +[withApis](../reference/core-plugin-api.withapis.md) HOC if you prefer class components. For example, the -[ErrorApi](../reference/core-plugin-api.ErrorApi.md) can be accessed like this: +[ErrorApi](../reference/core-plugin-api.errorapi.md) can be accessed like this: ```tsx import React from 'react'; @@ -56,9 +56,9 @@ export const MyComponent = () => { ``` Note that there is no explicit type given for -[ErrorApi](../reference/core-plugin-api.ErrorApi.md). This is because the -[errorApiRef](../reference/core-plugin-api.errorApiRef.md) has the type -embedded, and [useApi](../reference/core-plugin-api.useApi.md) is able to infer +[ErrorApi](../reference/core-plugin-api.errorapi.md). This is because the +[errorApiRef](../reference/core-plugin-api.errorapiref.md) has the type +embedded, and [useApi](../reference/core-plugin-api.useapi.md) is able to infer the type. Also note that consuming Utility APIs is not limited to plugins, it can be done @@ -71,15 +71,15 @@ requirement is that they are beneath the `AppProvider` in the react tree. ### API Factories APIs are registered in the form of -[ApiFactories](../reference/core-plugin-api.ApiFactory.md), which encapsulate +[ApiFactories](../reference/core-plugin-api.apifactory.md), which encapsulate the process of instantiating an API. It is a collection of three things: the -[ApiRef](../reference/core-plugin-api.ApiRef.md) of the API to instantiate, a +[ApiRef](../reference/core-plugin-api.apiref.md) of the API to instantiate, a list of all required dependencies, and a factory function that returns a new API instance. For example, this is the default -[ApiFactory](../reference/core-plugin-api.ApiFactory.md) for the -[ErrorApi](../reference/core-plugin-api.ErrorApi.md): +[ApiFactory](../reference/core-plugin-api.apifactory.md) for the +[ErrorApi](../reference/core-plugin-api.errorapi.md): ```ts createApiFactory({ @@ -93,25 +93,25 @@ createApiFactory({ }); ``` -In this example the [errorApiRef](../reference/core-plugin-api.errorApiRef.md) +In this example the [errorApiRef](../reference/core-plugin-api.errorapiref.md) is our API, which encapsulates the -[ErrorApi](../reference/core-plugin-api.ErrorApi.md) type. The -[alertApiRef](../reference/core-plugin-api.alertApiRef.md) is our single +[ErrorApi](../reference/core-plugin-api.errorapi.md) type. The +[alertApiRef](../reference/core-plugin-api.alertapiref.md) is our single dependency, which we give the name `alertApi`, and is then passed on to the factory function, which returns an implementation of the -[ErrorApi](../reference/core-plugin-api.ErrorApi.md). +[ErrorApi](../reference/core-plugin-api.errorapi.md). -The [createApiFactory](../reference/core-plugin-api.createApiFactory.md) +The [createApiFactory](../reference/core-plugin-api.createapifactory.md) function is a thin wrapper that enables TypeScript type inference. You may notice that there are no type annotations in the above example, and that is because we're able to infer all types from the -[ApiRef](../reference/core-plugin-api.ApiRef.md)s. TypeScript will make sure +[ApiRef](../reference/core-plugin-api.apiref.md)s. TypeScript will make sure that the return value of the `factory` function matches the type embedded in -`api`'s [ApiRef](../reference/core-plugin-api.ApiRef.md), in this case the -[ErrorApi](../reference/core-plugin-api.ErrorApi.md). It will also match the +`api`'s [ApiRef](../reference/core-plugin-api.apiref.md), in this case the +[ErrorApi](../reference/core-plugin-api.errorapi.md). It will also match the types between the `deps` and the parameters of the `factory` function, again using the type embedded within the -[ApiRef](../reference/core-plugin-api.ApiRef.md)s. +[ApiRef](../reference/core-plugin-api.apiref.md)s. ## Registering API Factories @@ -124,11 +124,11 @@ app, and the app itself. Starting with the Backstage core library, it provides implementations for all of the core APIs. The core APIs are the ones exported by [@backstage/core-plugin-api](../reference/core-plugin-api.md), such as the -[errorApiRef](../reference/core-plugin-api.errorApiRef.md) and -[configApiRef](../reference/core-plugin-api.configApiRef.md). +[errorApiRef](../reference/core-plugin-api.errorapiref.md) and +[configApiRef](../reference/core-plugin-api.configapiref.md). The core APIs are loaded for any app created with -[createApp](../reference/core-app-api.createApp.md) from +[createApp](../reference/core-app-api.createapp.md) from [@backstage/core-plugin-api](../reference/core-plugin-api.md), which means that there is no step that needs to be taken to include these APIs in an app. @@ -137,13 +137,13 @@ there is no step that needs to be taken to include these APIs in an app. In addition to the core APIs, plugins can define and export their own APIs. While doing so they should usually also provide default implementations of their own APIs, for example, the `catalog` plugin exports `catalogApiRef`, and also -supplies a default [ApiFactory](../reference/core-plugin-api.ApiFactory.md) of +supplies a default [ApiFactory](../reference/core-plugin-api.apifactory.md) of that API using the `CatalogClient`. There is one restriction to plugin-provided API Factories: plugins may not supply factories for core APIs, trying to do so will cause the app to refuse to start. Plugins supply their APIs through the `apis` option of -[createPlugin](../reference/core-plugin-api.createPlugin.md), for example: +[createPlugin](../reference/core-plugin-api.createplugin.md), for example: ```ts export const techdocsPlugin = createPlugin({ @@ -168,7 +168,7 @@ Lastly, the app itself is the final point where APIs can be added, and what has the final say in what APIs will be loaded at runtime. The app may override the factories for any of the core or plugin APIs, with the exception of the config, app theme, and identity APIs. These are static APIs that are tied into the -[createApp](../reference/core-app-api.createApp.md) implementation, and +[createApp](../reference/core-app-api.createapp.md) implementation, and therefore not possible to override. Overriding APIs is useful for apps that want to switch out behavior to tailor it @@ -231,19 +231,19 @@ const app = createApp({ ``` Note that the above line will cause an error if `IgnoreErrorApi` does not fully -implement the [ErrorApi](../reference/core-plugin-api.ErrorApi.md), as it is +implement the [ErrorApi](../reference/core-plugin-api.errorapi.md), as it is checked by the type embedded in the -[errorApiRef](../reference/core-plugin-api.errorApiRef.md) at compile time. +[errorApiRef](../reference/core-plugin-api.errorapiref.md) at compile time. ## Defining custom Utility APIs Plugins are free to define their own Utility APIs. Simply define the TypeScript interface for the API, and create an -[ApiRef](../reference/core-plugin-api.ApiRef.md) using -[createApiRef](../reference/core-plugin-api.createApiRef.md) exported from +[ApiRef](../reference/core-plugin-api.apiref.md) using +[createApiRef](../reference/core-plugin-api.createapiref.md) exported from [@backstage/core-plugin-api](../reference/core-plugin-api.md). Also be sure to provide at least one implementation of the API, and to declare a default factory -for the API in [createPlugin](../reference/core-plugin-api.createPlugin.md). +for the API in [createPlugin](../reference/core-plugin-api.createplugin.md). Custom Utility APIs can be either public or private, which is up to the plugin to choose. Private APIs do not expose an external API surface, and it's @@ -255,16 +255,16 @@ backwards compatibility of public APIs, as you may otherwise break apps that are using your plugin. To make an API public, simply export the -[ApiRef](../reference/core-plugin-api.ApiRef.md) of the API, and any associated +[ApiRef](../reference/core-plugin-api.apiref.md) of the API, and any associated types. To make an API private, just avoid exporting the -[ApiRef](../reference/core-plugin-api.ApiRef.md), but still be sure to supply a -default factory to [createPlugin](../reference/core-plugin-api.createPlugin.md). +[ApiRef](../reference/core-plugin-api.apiref.md), but still be sure to supply a +default factory to [createPlugin](../reference/core-plugin-api.createplugin.md). Private APIs are useful for plugins that want to depend on other APIs outside of React components, but not have to expose an entire API surface to maintain. When using private APIs, it is fine to use the `typeof` of an implementing class as the type parameter passed to -[createApiRef](../reference/core-plugin-api.createApiRef.md), while public APIs +[createApiRef](../reference/core-plugin-api.createapiref.md), while public APIs should always define a separate TypeScript interface type. Plugins may depend on APIs from other plugins, both in React components and as @@ -273,13 +273,13 @@ dependencies between plugins. ## Architecture -The [ApiRef](../reference/core-plugin-api.ApiRef.md) instances mentioned above +The [ApiRef](../reference/core-plugin-api.apiref.md) instances mentioned above provide a point of indirection between consumers and producers of Utility APIs. It allows for plugins and components to depend on APIs in a type-safe way, without having a direct reference to a concrete implementation of the APIs. The Apps are also given a lot of flexibility in what implementations to provide. As long as they adhere to the contract established by an -[ApiRef](../reference/core-plugin-api.ApiRef.md), they are free to choose any +[ApiRef](../reference/core-plugin-api.apiref.md), they are free to choose any implementation they want. The figure below shows the relationship between @@ -310,10 +310,10 @@ interaction with the API. The common development environment for plugins is included in [@backstage/dev-utils](../reference/dev-utils.md), where the exported -[createDevApp](../reference/dev-utils.createDevApp.md) function creates an +[createDevApp](../reference/dev-utils.createdevapp.md) function creates an application with implementations for all core APIs already present. Contrary to the method for wiring up Utility API implementations in an app created with -[createApp](../reference/core-app-api.createApp.md), -[createDevApp](../reference/dev-utils.createDevApp.md) uses automatic dependency +[createApp](../reference/core-app-api.createapp.md), +[createDevApp](../reference/dev-utils.createdevapp.md) uses automatic dependency injection. This is to make it possible to replace any API implementation, and having that be reflected in dependents of that API. diff --git a/docs/conf/reading.md b/docs/conf/reading.md index 4568f4c378..fd1ce4c7a6 100644 --- a/docs/conf/reading.md +++ b/docs/conf/reading.md @@ -7,7 +7,7 @@ description: Documentation on Reading Backstage Configuration ## Config API There's a common configuration API for by both frontend and backend plugins. An -API reference can be found [here](../reference/config.Config.md). +API reference can be found [here](../reference/config.config.md). The configuration API is tailored towards failing fast in case of missing or bad config. That's because configuration errors can always be considered programming @@ -110,7 +110,7 @@ example `getString`. These will throw an error if there is no value available. ## Accessing ConfigApi in Frontend Plugins -The [ConfigApi](../reference/core-plugin-api.ConfigApi.md) in the frontend is a +The [ConfigApi](../reference/core-plugin-api.configapi.md) in the frontend is a [UtilityApi](../api/utility-apis.md). It's accessible as usual via the `configApiRef` exported from `@backstage/core-plugin-api`: diff --git a/docs/plugins/structure-of-a-plugin.md b/docs/plugins/structure-of-a-plugin.md index 99a55745c5..83fcfbddba 100644 --- a/docs/plugins/structure-of-a-plugin.md +++ b/docs/plugins/structure-of-a-plugin.md @@ -82,8 +82,8 @@ export const ExamplePage = examplePlugin.provide( This is where the plugin is created and where it creates and exports extensions that can be imported and used the app. See reference docs for -[createPlugin](../reference/createPlugin.md) or introduction to the new -[Composability System](./composability.md). +[createPlugin](../reference/core-plugin-api.createplugin.md) or introduction to +the new [Composability System](./composability.md). ## Components From 2aad5ab2269fd3569f16bbd5c49e07c3decf7138 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 12 Sep 2021 16:39:53 +0200 Subject: [PATCH 17/17] docs: get rid of the reference dir Signed-off-by: Patrik Oldsberg --- docs/.gitignore | 3 ++- docs/reference/.generated | 2 -- 2 files changed, 2 insertions(+), 3 deletions(-) delete mode 100644 docs/reference/.generated diff --git a/docs/.gitignore b/docs/.gitignore index c757205e4c..90b1e2c7ef 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ -reference/*.md +# This is generated by build:api-docs in the root +reference diff --git a/docs/reference/.generated b/docs/reference/.generated deleted file mode 100644 index e08947a827..0000000000 --- a/docs/reference/.generated +++ /dev/null @@ -1,2 +0,0 @@ -The contents of this folder is generated by the root `yarn build:api-docs` command. -Don't put any additional content here as it will be overwritten during the microsite build.