paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 26 Packages Projects Releases Wiki Activity

Move @backstage/techdocs-addons to @backstage/plugin-techdocs-react

Browse Source 
Co-authored-by: Eric Peterson <iamEAP@users.noreply.github.com>
Co-authored-by: Anders Näsman <realandersn@users.noreply.github.com>
Signed-off-by: Otto Sichert <git@ottosichert.de>
This commit is contained in:
Otto Sichert
2022-04-11 16:13:07 +02:00
parent 4e489d10db
commit b05870bcb7
18 changed files with 28 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/techdocs-react/.eslintrc.js
+1
View File
@@ -0,0 +1 @@
module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
plugins/techdocs-react/README.md
+9
View File
@@ -0,0 +1,9 @@
# @backstage/plugin-techdocs-react
This package provides frontend utilities for TechDocs and Addons.
## Installation
```sh
yarn add @backstage/plugin-techdocs-react
```
plugins/techdocs-react/api-report.md
+54
View File
@@ -0,0 +1,54 @@
## API Report File for "@backstage/plugin-techdocs-react"
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
import { ComponentType } from 'react';
import { Extension } from '@backstage/core-plugin-api';
import { default as React_2 } from 'react';
// @alpha
export function createTechDocsAddon<TComponentProps>(
options: TechDocsAddonOptions<TComponentProps>,
): Extension<ComponentType<TComponentProps>>;
// @alpha
export const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1';
// @alpha
export enum TechDocsAddonLocations {
CONTENT = 'content',
HEADER = 'header',
PRIMARY_SIDEBAR = 'primary sidebar',
SECONDARY_SIDEBAR = 'secondary sidebar',
SUBHEADER = 'subheader',
}
// @alpha
export type TechDocsAddonOptions<TAddonProps = {}> = {
name: string;
location: TechDocsAddonLocations;
component: ComponentType<TAddonProps>;
};
// @alpha
export const TechDocsAddons: React_2.ComponentType;
// @alpha
export const useTechDocsAddons: () => {
renderComponentByName: (name: string) => React_2.ReactElement<
{
[name: string]: unknown;
},
string | React_2.JSXElementConstructor<any>
> | null;
renderComponentsByLocation: (location: TechDocsAddonLocations) =>
| (React_2.ReactElement<
{
[name: string]: unknown;
},
string | React_2.JSXElementConstructor<any>
> | null)[]
| null;
};
```
plugins/techdocs-react/package.json
+58
View File
@@ -0,0 +1,58 @@
{
"name": "@backstage/plugin-techdocs-react",
"description": "Shared frontend utilities for TechDocs and Addons",
"version": "0.0.0",
"private": false,
"publishConfig": {
"access": "public",
"main": "dist/index.esm.js",
"types": "dist/index.d.ts"
},
"backstage": {
"role": "web-library"
},
"homepage": "https://backstage.io",
"repository": {
"type": "git",
"url": "https://github.com/backstage/backstage",
"directory": "plugins/techdocs-react"
},
"keywords": [
"backstage",
"techdocs"
],
"license": "Apache-2.0",
"main": "src/index.ts",
"types": "src/index.ts",
"scripts": {
"build": "backstage-cli package build",
"lint": "backstage-cli package lint",
"test": "backstage-cli package test",
"prepack": "backstage-cli package prepack",
"postpack": "backstage-cli package postpack",
"clean": "backstage-cli package clean",
"start": "backstage-cli package start"
},
"dependencies": {
"@backstage/catalog-model": "^1.0.1-next.1",
"@backstage/core-components": "^0.9.3-next.1",
"@backstage/core-plugin-api": "^1.0.0",
"@material-ui/core": "^4.12.2",
"@material-ui/lab": "4.0.0-alpha.57",
"@material-ui/styles": "^4.11.0",
"jss": "~10.8.2",
"react-helmet": "6.1.0",
"react-router-dom": "6.0.0-beta.0"
},
"peerDependencies": {
"@types/react": "^16.13.1 || ^17.0.0",
"react": "^16.13.1 || ^17.0.0"
},
"devDependencies": {
"@testing-library/react-hooks": "^7.0.2",
"@backstage/test-utils": "^1.0.1-next.1"
},
"files": [
"dist"
]
}
plugins/techdocs-react/src/addons.tsx
+129
View File
@@ -0,0 +1,129 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import React, { ComponentType, useCallback } from 'react';
import { useOutlet } from 'react-router-dom';
import {
attachComponentData,
createReactExtension,
ElementCollection,
Extension,
useElementFilter,
} from '@backstage/core-plugin-api';
import { TechDocsAddonLocations, TechDocsAddonOptions } from './types';
export const TECHDOCS_ADDONS_KEY = 'techdocs.addons.addon.v1';
/**
* Marks the <TechDocsAddons> registry component.
* @alpha
*/
export const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1';
/**
* TechDocs Addon registry.
* @alpha
*/
export const TechDocsAddons: React.ComponentType = () => null;
attachComponentData(TechDocsAddons, TECHDOCS_ADDONS_WRAPPER_KEY, true);
const getDataKeyByName = (name: string) => {
return `${TECHDOCS_ADDONS_KEY}.${name.toLocaleLowerCase('en-US')}`;
};
/**
* Create a TechDocs addon.
* @alpha
*/
export function createTechDocsAddon<TComponentProps>(
options: TechDocsAddonOptions<TComponentProps>,
): Extension<ComponentType<TComponentProps>> {
const { name, component: TechDocsAddon } = options;
return createReactExtension({
name,
component: {
sync: (props: TComponentProps) => <TechDocsAddon {...props} />,
},
data: {
[TECHDOCS_ADDONS_KEY]: options,
[getDataKeyByName(name)]: true,
},
});
}
const getTechDocsAddonByName = (collection: ElementCollection, key: string) => {
return collection.selectByComponentData({ key }).getElements()[0];
};
const getAllTechDocsAddons = (collection: ElementCollection) => {
return collection
.selectByComponentData({
key: TECHDOCS_ADDONS_WRAPPER_KEY,
})
.selectByComponentData({
key: TECHDOCS_ADDONS_KEY,
});
};
const getAllTechDocsAddonsData = (collection: ElementCollection) => {
return collection
.selectByComponentData({
key: TECHDOCS_ADDONS_WRAPPER_KEY,
})
.findComponentData<TechDocsAddonOptions>({
key: TECHDOCS_ADDONS_KEY,
});
};
/**
* hook to use addons in components
* @alpha
*/
export const useTechDocsAddons = () => {
const node = useOutlet();
const collection = useElementFilter(node, getAllTechDocsAddons);
const options = useElementFilter(node, getAllTechDocsAddonsData);
const findAddonByData = useCallback(
(data: TechDocsAddonOptions | undefined) => {
if (!collection || !data) return null;
const nameKey = getDataKeyByName(data.name);
return getTechDocsAddonByName(collection, nameKey) ?? null;
},
[collection],
);
const renderComponentByName = useCallback(
(name: string) => {
const data = options.find(option => option.name === name);
return data ? findAddonByData(data) : null;
},
[options, findAddonByData],
);
const renderComponentsByLocation = useCallback(
(location: TechDocsAddonLocations) => {
const data = options.filter(option => option.location === location);
return data.length ? data.map(findAddonByData) : null;
},
[options, findAddonByData],
);
return { renderComponentByName, renderComponentsByLocation };
};
plugins/techdocs-react/src/index.ts
+30
View File
@@ -0,0 +1,30 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Package encapsulating the TechDocs Addon framework.
*
* @packageDocumentation
*/
export {
useTechDocsAddons,
createTechDocsAddon,
TechDocsAddons,
TECHDOCS_ADDONS_WRAPPER_KEY,
} from './addons';
export { TechDocsAddonLocations } from './types';
export type { TechDocsAddonOptions } from './types';
plugins/techdocs-react/src/types.ts
+87
View File
@@ -0,0 +1,87 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ComponentType } from 'react';
/**
* Locations for which TechDocs addons may be declared and rendered.
* @alpha
*/
export enum TechDocsAddonLocations {
/**
* These addons fill up the header from the right, on the same line as the
* title.
*/
HEADER = 'header',
/**
* These addons appear below the header and above all content; tooling addons
* can be inserted for convenience.
*/
SUBHEADER = 'subheader',
/**
* These addons appear left of the content and above the navigation.
*/
PRIMARY_SIDEBAR = 'primary sidebar',
/**
* These addons appear right of the content and above the table of contents.
*/
SECONDARY_SIDEBAR = 'secondary sidebar',
/**
* A virtual location which allows mutation of all content within the shadow
* root by transforming DOM nodes. These addons should return null on render.
*/
CONTENT = 'content',
/**
* todo(backstage/community): This is a proposed virtual location which would
* help implement a common addon pattern in which many instances of a given
* element in markdown would be dynamically replaced at render-time based on
* attributes provided on that element, for example:
*
* ```md
* ## Component Metadata
* [CatalogEntityCard](default:component/some-component-name)
*
* ## System Metadata
* [CatalogEntityCard](default:system/some-system-name)
* ```
*
* Could correspond to a TechDocs addon named `CatalogEntityCard` with
* location `TechDocsAddonLocations.COMPONENT`, whose `component` would be
* the react component that would be rendered in place of all instances of
* the markdown illustrated above.
*
* The `@backstage/plugin-techdocs-react` package would need to be updated to, in
* cases where such addons had been registered, find all instances of the
* rendered markdown (e.g. `<a href="{entityRef}">CatalogEntityCard</a>`) and
* replace them with react portals to the addon component.
*/
// COMPONENT = 'component',
}
/**
* Options for creating a TechDocs addon.
* @alpha
*/
export type TechDocsAddonOptions<TAddonProps = {}> = {
name: string;
location: TechDocsAddonLocations;
component: ComponentType<TAddonProps>;
};