diff --git a/.changeset/dull-waves-marry.md b/.changeset/dull-waves-marry.md new file mode 100644 index 0000000000..22d33238b4 --- /dev/null +++ b/.changeset/dull-waves-marry.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-techdocs': patch +--- + +Create a menu in the sub header of documentation pages, it is responsible for rendering TechDocs addons that allow users to customize their reading experience. diff --git a/.changeset/nice-parrots-lie.md b/.changeset/nice-parrots-lie.md new file mode 100644 index 0000000000..2a917b89f3 --- /dev/null +++ b/.changeset/nice-parrots-lie.md @@ -0,0 +1,17 @@ +--- +'@backstage/plugin-techdocs-react': patch +--- + +Create a new addon location called "Settings", it is designed for addons that allow users to customize the reading experience in documentation pages. + +Usage example: + +```tsx +const TextSize = techdocsModuleAddonsContribPlugin.provide( + createTechDocsAddonExtension({ + name: 'TextSize', + location: TechDocsAddonLocations.Settings, + component: TextSizeAddon, + }), +); +``` diff --git a/.changeset/small-eggs-guess.md b/.changeset/small-eggs-guess.md new file mode 100644 index 0000000000..4738a8775a --- /dev/null +++ b/.changeset/small-eggs-guess.md @@ -0,0 +1,34 @@ +--- +'@backstage/plugin-techdocs-module-addons-contrib': patch +--- + +Create a TechDocs `` addon that allows users to set a font size in the browser's local storage for the text of documentation pages. + +Here's an example on how to use it in a Backstage app: + +```diff +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 = () => { + + // other plugin routes + }> + + + } + > + ++ + + + ; +}; +``` diff --git a/docs/assets/techdocs/addon-locations.png b/docs/assets/techdocs/addon-locations.png index e535fe61aa..0541f35af5 100644 Binary files a/docs/assets/techdocs/addon-locations.png and b/docs/assets/techdocs/addon-locations.png differ diff --git a/docs/features/techdocs/addons.md b/docs/features/techdocs/addons.md index 0fba3b92e3..e8af56d3fc 100644 --- a/docs/features/techdocs/addons.md +++ b/docs/features/techdocs/addons.md @@ -35,6 +35,8 @@ representative of physical spaces in the TechDocs UI: line as the title. - `Subheader`: For Addons that sit below the header but above all content. This is a great location for tooling/configuration of TechDocs display. +- `Settings`: These addons are items added to the settings menu list and are designed to make + the reader experience customizable, for example accessibility options. - `PrimarySidebar`: Left of the content, above of the navigation. - `SecondarySidebar`: Right of the content, above the table of contents. - `Content`: A special location intended for Addons which augment the @@ -109,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 | -| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [``](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 | +| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [``](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. | +| [``](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! diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx index 4cf2c02e55..089900fb77 100644 --- a/packages/app/src/App.tsx +++ b/packages/app/src/App.tsx @@ -70,7 +70,10 @@ import { techdocsPlugin, } from '@backstage/plugin-techdocs'; import { TechDocsAddons } from '@backstage/plugin-techdocs-react'; -import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib'; +import { + ReportIssue, + TextSize, +} from '@backstage/plugin-techdocs-module-addons-contrib'; import { UserSettingsPage, UserSettingsTab, @@ -183,6 +186,7 @@ const routes = ( {techDocsPage} + ; + +// @public +export const TextSize: (props: unknown) => JSX.Element | null; ``` diff --git a/plugins/techdocs-module-addons-contrib/src/TextSize/TextSize.test.tsx b/plugins/techdocs-module-addons-contrib/src/TextSize/TextSize.test.tsx new file mode 100644 index 0000000000..282d54a0b6 --- /dev/null +++ b/plugins/techdocs-module-addons-contrib/src/TextSize/TextSize.test.tsx @@ -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([ + , + ]) + .withDom(TEST_CONTENT) + .renderWithEffects(); + + expect(getByText('TEST_CONTENT')).toBeInTheDocument(); + }); + + it('changes content text size using slider', async () => { + const { getByTitle, getByText, getByRole, getByDisplayValue } = + await TechDocsAddonTester.buildAddonsInTechDocs([]) + .withDom(TEST_CONTENT) + .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([]) + .withDom(TEST_CONTENT) + .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'); + }); +}); diff --git a/plugins/techdocs-module-addons-contrib/src/TextSize/TextSize.tsx b/plugins/techdocs-module-addons-contrib/src/TextSize/TextSize.tsx new file mode 100644 index 0000000000..fc865c7826 --- /dev/null +++ b/plugins/techdocs-module-addons-contrib/src/TextSize/TextSize.tsx @@ -0,0 +1,243 @@ +/* + * 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, + 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.textsize', + 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(); + const [body] = useShadowRootElements(['body']); + + const [value, setValue] = useState(() => { + 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 BackstageTheme['typography'] & { + htmlFontSize?: number; + } + )?.htmlFontSize ?? 16; + body.style.setProperty( + '--md-typeset-font-size', + `${htmlFontSize * (value / 100)}px`, + ); + }, [body, value, theme]); + + return ( + + + Text size + + } + secondary={ + + + + + + + + + + } + disableTypography + /> + + ); +}; diff --git a/plugins/techdocs-module-addons-contrib/src/TextSize/index.ts b/plugins/techdocs-module-addons-contrib/src/TextSize/index.ts new file mode 100644 index 0000000000..ffcf655f63 --- /dev/null +++ b/plugins/techdocs-module-addons-contrib/src/TextSize/index.ts @@ -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'; diff --git a/plugins/techdocs-module-addons-contrib/src/index.ts b/plugins/techdocs-module-addons-contrib/src/index.ts index 09fe1f8671..e2e57b15d1 100644 --- a/plugins/techdocs-module-addons-contrib/src/index.ts +++ b/plugins/techdocs-module-addons-contrib/src/index.ts @@ -20,7 +20,11 @@ * @packageDocumentation */ -export { techdocsModuleAddonsContribPlugin, ReportIssue } from './plugin'; +export { + techdocsModuleAddonsContribPlugin, + ReportIssue, + TextSize, +} from './plugin'; export type { ReportIssueProps, ReportIssueTemplate, diff --git a/plugins/techdocs-module-addons-contrib/src/plugin.ts b/plugins/techdocs-module-addons-contrib/src/plugin.ts index e71ec2a5c7..0d7743da9e 100644 --- a/plugins/techdocs-module-addons-contrib/src/plugin.ts +++ b/plugins/techdocs-module-addons-contrib/src/plugin.ts @@ -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,49 @@ 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 the font size is 100% of the HTML font size, if the theme does not have a `htmlFontSize` in its typography object, the addon will assume 16px as 100%, and remember, this setting is kept in the browser 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 = () => { + * + * // other plugin routes + * }> + * + * + * } + * > + * + * + * + * + * ; + * }; + * ``` + * + * @public + */ +export const TextSize = techdocsModuleAddonsContribPlugin.provide( + createTechDocsAddonExtension({ + name: 'TextSize', + location: TechDocsAddonLocations.Settings, + component: TextSizeAddon, + }), +); diff --git a/plugins/techdocs-react/api-report.md b/plugins/techdocs-react/api-report.md index fa38feef14..d3803d6794 100644 --- a/plugins/techdocs-react/api-report.md +++ b/plugins/techdocs-react/api-report.md @@ -32,6 +32,7 @@ export const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1'; export const TechDocsAddonLocations: Readonly<{ readonly Header: 'Header'; readonly Subheader: 'Subheader'; + readonly Settings: 'Settings'; readonly PrimarySidebar: 'PrimarySidebar'; readonly SecondarySidebar: 'SecondarySidebar'; readonly Content: 'Content'; diff --git a/plugins/techdocs-react/src/types.ts b/plugins/techdocs-react/src/types.ts index de74d4f284..e147cd1dd1 100644 --- a/plugins/techdocs-react/src/types.ts +++ b/plugins/techdocs-react/src/types.ts @@ -53,6 +53,12 @@ export const TechDocsAddonLocations = Object.freeze({ */ Subheader: 'Subheader', + /** + * These addons are items added to the settings menu list and are designed to make + * the reader experience customizable, for example accessibility options + */ + Settings: 'Settings', + /** * These addons appear left of the content and above the navigation. */ diff --git a/plugins/techdocs/src/reader/components/TechDocsReaderPageSubheader/TechDocsReaderPageSubheader.tsx b/plugins/techdocs/src/reader/components/TechDocsReaderPageSubheader/TechDocsReaderPageSubheader.tsx index e0eb0ad2b0..a0013e81ab 100644 --- a/plugins/techdocs/src/reader/components/TechDocsReaderPageSubheader/TechDocsReaderPageSubheader.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsReaderPageSubheader/TechDocsReaderPageSubheader.tsx @@ -14,9 +14,18 @@ * limitations under the License. */ -import React from 'react'; +import React, { MouseEvent, useState, useCallback } from 'react'; -import { Box, makeStyles, Toolbar, ToolbarProps } from '@material-ui/core'; +import { + Box, + makeStyles, + Toolbar, + ToolbarProps, + Menu, + Tooltip, + IconButton, +} from '@material-ui/core'; +import SettingsIcon from '@material-ui/icons/Settings'; import { TechDocsAddonLocations as locations, @@ -44,31 +53,67 @@ export const TechDocsReaderPageSubheader = ({ toolbarProps?: ToolbarProps; }) => { const classes = useStyles(); + const [anchorEl, setAnchorEl] = useState(null); + + const handleClick = useCallback((event: MouseEvent) => { + setAnchorEl(event.currentTarget); + }, []); + + const handleClose = useCallback(() => { + setAnchorEl(null); + }, []); + const { entityMetadata: { value: entityMetadata, loading: entityMetadataLoading }, } = useTechDocsReaderPage(); + const addons = useTechDocsAddons(); + const subheaderAddons = addons.renderComponentsByLocation( locations.Subheader, ); - if (!subheaderAddons) return null; + const settingsAddons = addons.renderComponentsByLocation(locations.Settings); + + if (!subheaderAddons && !settingsAddons) return null; // No entity metadata = 404. Don't render subheader on 404. if (entityMetadataLoading === false && !entityMetadata) return null; return ( - {subheaderAddons && ( - - {subheaderAddons} - - )} + + {subheaderAddons} + {settingsAddons ? ( + <> + + + + + + + {settingsAddons} + + + ) : null} + ); };