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

feat(techdocs): create text size addon

Browse Source 
Signed-off-by: Camila Belo <camilaibs@gmail.com>
This commit is contained in:
Camila Belo
2022-05-05 07:57:32 +02:00
parent 10b8e973ef
commit 3711bc6031
7 changed files with 441 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/assets/techdocs/addon-locations.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 297 KiB

After

Width:  |  Height:  |  Size: 1.9 MiB

docs/features/techdocs/addons.md
+4 -3
View File
@@ -111,9 +111,10 @@ page header, TechDocs Addons whose location is `Header` will not be rendered.
Addons can, in principle, be provided by any plugin! To make it easier to
discover available Addons, we've compiled a list of them here:
| Addon | Package/Plugin | Description |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`<ReportIssue />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. |
| Addon | Package/Plugin | Description |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`<ReportIssue />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. |
| [`<TextSize />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. |
Got an Addon to contribute? Feel free to add a row above!
plugins/techdocs-module-addons-contrib/src/TextSize/TextSize.test.tsx
+124
View File
@@ -0,0 +1,124 @@
/*
* 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 { TechDocsAddonTester } from '@backstage/plugin-techdocs-addons-test-utils';
import React from 'react';
import { fireEvent, waitFor } from '@testing-library/react';
import { TextSize } from '..';
describe('TextSize', () => {
it('renders without exploding', async () => {
const { getByText } = await TechDocsAddonTester.buildAddonsInTechDocs([
<TextSize />,
])
.withDom(<body>TEST_CONTENT</body>)
.renderWithEffects();
expect(getByText('TEST_CONTENT')).toBeInTheDocument();
});
it('changes content text size using slider', async () => {
const { getByTitle, getByText, getByRole, getByDisplayValue } =
await TechDocsAddonTester.buildAddonsInTechDocs([<TextSize />])
.withDom(<body>TEST_CONTENT</body>)
.renderWithEffects();
fireEvent.click(getByTitle('Settings'));
await waitFor(() => {
expect(getByText('Text size')).toBeInTheDocument();
});
const slider = getByRole('slider');
slider.focus();
fireEvent.keyDown(slider, {
key: 'ArrowRight',
});
await waitFor(() => {
expect(getByDisplayValue('115')).toBeInTheDocument();
});
expect(slider).toHaveTextContent('115%');
let style = getComputedStyle(getByText('TEST_CONTENT'));
expect(style.getPropertyValue('--md-typeset-font-size')).toBe('18.4px');
fireEvent.keyDown(slider, {
key: 'ArrowLeft',
});
await waitFor(() => {
expect(getByDisplayValue('100')).toBeInTheDocument();
});
expect(slider).toHaveTextContent('100%');
style = getComputedStyle(getByText('TEST_CONTENT'));
expect(style.getPropertyValue('--md-typeset-font-size')).toBe('16px');
});
it('changes content text size using buttons', async () => {
const {
getByTitle,
getByText,
getByRole,
getByLabelText,
getByDisplayValue,
} = await TechDocsAddonTester.buildAddonsInTechDocs([<TextSize />])
.withDom(<body>TEST_CONTENT</body>)
.renderWithEffects();
fireEvent.click(getByTitle('Settings'));
await waitFor(() => {
expect(getByText('Text size')).toBeInTheDocument();
});
fireEvent.click(getByLabelText('Increase text size'));
await waitFor(() => {
expect(getByDisplayValue('115')).toBeInTheDocument();
});
const slider = getByRole('slider');
expect(slider).toHaveTextContent('115%');
let style = getComputedStyle(getByText('TEST_CONTENT'));
expect(style.getPropertyValue('--md-typeset-font-size')).toBe('18.4px');
fireEvent.click(getByLabelText('Decrease text size'));
await waitFor(() => {
expect(getByDisplayValue('100')).toBeInTheDocument();
});
expect(slider).toHaveTextContent('100%');
style = getComputedStyle(getByText('TEST_CONTENT'));
expect(style.getPropertyValue('--md-typeset-font-size')).toBe('16px');
});
});
plugins/techdocs-module-addons-contrib/src/TextSize/TextSize.tsx
+244
View File
@@ -0,0 +1,244 @@
/*
* 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, {
ChangeEvent,
MouseEvent,
useMemo,
useState,
useEffect,
useCallback,
} from 'react';
import {
withStyles,
makeStyles,
useTheme,
Theme,
Box,
MenuItem,
ListItemText,
Slider,
IconButton,
Typography,
} from '@material-ui/core';
import AddIcon from '@material-ui/icons/Add';
import RemoveIcon from '@material-ui/icons/Remove';
import { BackstageTheme } from '@backstage/theme';
import { useShadowRootElements } from '@backstage/plugin-techdocs-react';
const boxShadow =
'0 3px 1px rgba(0,0,0,0.1),0 4px 8px rgba(0,0,0,0.13),0 0 0 1px rgba(0,0,0,0.02)';
const StyledSlider = withStyles(theme => ({
root: {
height: 2,
padding: '15px 0',
},
thumb: {
height: 18,
width: 18,
backgroundColor: theme.palette.common.white,
boxShadow: boxShadow,
marginTop: -9,
marginLeft: -9,
'&:focus, &:hover, &$active': {
boxShadow:
'0 3px 1px rgba(0,0,0,0.1),0 4px 8px rgba(0,0,0,0.3),0 0 0 1px rgba(0,0,0,0.02)',
// Reset on touch devices, it doesn't add specificity
'@media (hover: none)': {
boxShadow: boxShadow,
},
},
},
active: {},
valueLabel: {
top: '100%',
left: '50%',
transform: 'scale(1) translate(-50%, -5px) !important',
'& *': {
color: theme.palette.common.black,
fontSize: theme.typography.caption.fontSize,
background: 'transparent',
},
},
track: {
height: 2,
},
rail: {
height: 2,
opacity: 0.5,
},
mark: {
height: 10,
width: 1,
marginTop: -4,
},
markActive: {
opacity: 1,
backgroundColor: 'currentColor',
},
}))(Slider);
const settings = {
key: 'techdocs.addons.settings',
defaultValue: 100,
};
const marks = [
{
value: 90,
},
{
value: 100,
},
{
value: 115,
},
{
value: 130,
},
{
value: 150,
},
];
const useStyles = makeStyles((theme: BackstageTheme) => ({
container: {
color: theme.palette.textSubtle,
display: 'flex',
alignItems: 'center',
margin: 0,
minWidth: 200,
},
menuItem: {
'&:hover': {
background: 'transparent',
},
},
decreaseButton: {
marginRight: theme.spacing(1),
},
increaseButton: {
marginLeft: theme.spacing(1),
},
}));
export const TextSizeAddon = () => {
const classes = useStyles();
const theme = useTheme<BackstageTheme>();
const [body] = useShadowRootElements(['body']);
const [value, setValue] = useState<number>(() => {
const initialValue = localStorage?.getItem(settings.key);
return initialValue ? parseInt(initialValue, 10) : settings.defaultValue;
});
const values = useMemo(() => marks.map(mark => mark.value), []);
const index = useMemo(() => values.indexOf(value), [values, value]);
const min = useMemo(() => values[0], [values]);
const max = useMemo(() => values[values.length - 1], [values]);
const getValueText = useCallback(() => `${value}%`, [value]);
const handleChangeCommitted = useCallback(
(_event: ChangeEvent<{}>, newValue: number | number[]) => {
if (!Array.isArray(newValue)) {
setValue(newValue);
localStorage?.setItem(settings.key, String(newValue));
}
},
[setValue],
);
const handleDecreaseClick = useCallback(
(event: MouseEvent) => {
handleChangeCommitted(event, values[index - 1]);
},
[index, values, handleChangeCommitted],
);
const handleIncreaseClick = useCallback(
(event: MouseEvent) => {
handleChangeCommitted(event, values[index + 1]);
},
[index, values, handleChangeCommitted],
);
useEffect(() => {
if (!body) return;
const htmlFontSize =
(
theme.typography as Theme['typography'] & {
htmlFontSize: number;
}
)?.htmlFontSize ?? 16;
body.style.setProperty(
'--md-typeset-font-size',
`${htmlFontSize * (value / 100)}px`,
);
}, [body, value, theme]);
return (
<MenuItem className={classes.menuItem} button disableRipple>
<ListItemText
primary={
<Typography variant="subtitle2" color="textPrimary">
Text size
</Typography>
}
secondary={
<Box className={classes.container}>
<IconButton
className={classes.decreaseButton}
size="small"
edge="start"
disabled={value === min}
onClick={handleDecreaseClick}
aria-label="Decrease text size"
>
<RemoveIcon />
</IconButton>
<StyledSlider
value={value}
aria-labelledby="text-size-slider"
getAriaValueText={getValueText}
valueLabelDisplay="on"
valueLabelFormat={getValueText}
marks={marks}
step={null}
min={min}
max={max}
onChangeCommitted={handleChangeCommitted}
/>
<IconButton
className={classes.increaseButton}
size="small"
edge="end"
disabled={value === max}
onClick={handleIncreaseClick}
aria-label="Increase text size"
>
<AddIcon />
</IconButton>
</Box>
}
disableTypography
/>
</MenuItem>
);
};
plugins/techdocs-module-addons-contrib/src/TextSize/index.ts
+16
View File
@@ -0,0 +1,16 @@
/*
* 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.
*/
export * from './TextSize';
plugins/techdocs-module-addons-contrib/src/index.ts
+5 -1
View File
@@ -20,7 +20,11 @@
* @packageDocumentation
*/
export { techdocsModuleAddonsContribPlugin, ReportIssue } from './plugin';
export {
techdocsModuleAddonsContribPlugin,
ReportIssue,
TextSize,
} from './plugin';
export type {
ReportIssueProps,
ReportIssueTemplate,
plugins/techdocs-module-addons-contrib/src/plugin.ts
+48
View File
@@ -20,6 +20,7 @@ import {
TechDocsAddonLocations,
} from '@backstage/plugin-techdocs-react';
import { ReportIssueAddon, ReportIssueProps } from './ReportIssue';
import { TextSizeAddon } from './TextSize';
/**
* The TechDocs addons contrib plugin
@@ -44,3 +45,50 @@ export const ReportIssue = techdocsModuleAddonsContribPlugin.provide(
component: ReportIssueAddon,
}),
);
/**
* This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons.
*
* @remarks
* The default value for font size is 100% of the HTML font size and, if the theme does not have an htmlFontSize value in its typography object,
* the Addon will assume 16px as 100% and this setting is kept in the browser's local storage.
*
* @example
* Here's a simple example:
* ```
* import {
* DefaultTechDocsHome,
* TechDocsIndexPage,
* TechDocsReaderPage,
* } from '@backstage/plugin-techdocs';
* import { TechDocsAddons } from '@backstage/plugin-techdocs-react/alpha';
* import { TextSize } from '@backstage/plugin-techdocs-module-addons-contrib';
*
*
* const AppRoutes = () => {
* <FlatRoutes>
* // other plugin routes
* <Route path="/docs" element={<TechDocsIndexPage />}>
* <DefaultTechDocsHome />
* </Route>
* <Route
* path="/docs/:namespace/:kind/:name/*"
* element={<TechDocsReaderPage />}
* >
* <TechDocsAddons>
* <TextSize />
* </TechDocsAddons>
* </Route>
* </FlatRoutes>;
* };
* ```
*
* @public
*/
export const TextSize = techdocsModuleAddonsContribPlugin.provide(
createTechDocsAddonExtension({
name: 'TextSize',
location: TechDocsAddonLocations.Settings,
component: TextSizeAddon,
}),
);