Move @backstage/techdocs-addons to @backstage/plugin-techdocs-react
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
@@ -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 };
|
||||
};
|
||||
@@ -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';
|
||||
@@ -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>;
|
||||
};
|
||||
Reference in New Issue
Block a user