From 362cf45bc520a68a1c1be20e1189ca2307577dde Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 19 Apr 2022 12:12:15 +0200 Subject: chore: add a Code component --- src/utils/hooks/use-prism-plugins.tsx | 115 ++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 src/utils/hooks/use-prism-plugins.tsx (limited to 'src/utils/hooks') diff --git a/src/utils/hooks/use-prism-plugins.tsx b/src/utils/hooks/use-prism-plugins.tsx new file mode 100644 index 0000000..c4959ac --- /dev/null +++ b/src/utils/hooks/use-prism-plugins.tsx @@ -0,0 +1,115 @@ +import Prism from 'prismjs'; +import { useEffect, useMemo } from 'react'; +import { useIntl } from 'react-intl'; + +export type PrismPlugin = + | 'autoloader' + | 'color-scheme' + | 'command-line' + | 'copy-to-clipboard' + | 'diff-highlight' + | 'inline-color' + | 'line-highlight' + | 'line-numbers' + | 'match-braces' + | 'normalize-whitespace' + | 'show-language' + | 'toolbar'; + +/** + * Import and configure all given Prism plugins. + * + * @param {PrismPlugin[]} prismPlugins - The Prism plugins to activate. + */ +const loadPrismPlugins = async (prismPlugins: PrismPlugin[]) => { + for (const plugin of prismPlugins) { + try { + if (plugin === 'color-scheme') { + await import(`@utils/plugins/prism-${plugin}`); + } else { + await import(`prismjs/plugins/${plugin}/prism-${plugin}.min.js`); + } + + if (plugin === 'autoloader') { + Prism.plugins.autoloader.languages_path = '/prism/'; + } + } catch (error) { + console.error( + 'usePrismPlugins: an error occurred while loading Prism plugins.' + ); + console.error(error); + } + } +}; + +/** + * Load both the given Prism plugins and the default plugins. + * + * @param {PrismPlugin[]} plugins - The Prism plugins to activate. + */ +const usePrismPlugins = (plugins: PrismPlugin[]) => { + const intl = useIntl(); + + const copyText = intl.formatMessage({ + defaultMessage: 'Copy', + description: 'usePrismPlugins: copy button text (not clicked)', + id: 'FIE/eC', + }); + const copiedText = intl.formatMessage({ + defaultMessage: 'Copied!', + description: 'usePrismPlugins: copy button text (clicked)', + id: 'MzLdEl', + }); + const errorText = intl.formatMessage({ + defaultMessage: 'Use Ctrl+c to copy', + description: 'usePrismPlugins: copy button error text', + id: '0XePFn', + }); + const darkTheme = intl.formatMessage({ + defaultMessage: 'Dark Theme 🌙', + description: 'usePrismPlugins: toggle dark theme button text', + id: 'jo9vr5', + }); + const lightTheme = intl.formatMessage({ + defaultMessage: 'Light Theme 🌞', + description: 'usePrismPlugins: toggle light theme button text', + id: '6EUEtH', + }); + + const attributes = { + 'data-prismjs-copy': copyText, + 'data-prismjs-copy-success': copiedText, + 'data-prismjs-copy-error': errorText, + 'data-prismjs-color-scheme-dark': darkTheme, + 'data-prismjs-color-scheme-light': lightTheme, + }; + + const defaultPlugins: PrismPlugin[] = useMemo( + () => [ + 'toolbar', + 'autoloader', + 'show-language', + 'copy-to-clipboard', + 'color-scheme', + 'match-braces', + 'normalize-whitespace', + ], + [] + ); + + useEffect(() => { + loadPrismPlugins([...defaultPlugins, ...plugins]).then(() => { + Prism.highlightAll(); + }); + }, [defaultPlugins, plugins]); + + const defaultPluginsClasses = 'match-braces'; + const pluginsClasses = plugins.join(' '); + + return { + pluginsAttribute: attributes, + pluginsClassName: `${defaultPluginsClasses} ${pluginsClasses}`, + }; +}; + +export default usePrismPlugins; -- cgit v1.2.3 From 947a06bfdfdc5bca62c27fa2ee27f0ab9fefa0ea Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 22 Apr 2022 18:33:04 +0200 Subject: chore: add a TableOfContents component --- .../widgets/table-of-contents.stories.tsx | 41 ++++++ .../organisms/widgets/table-of-contents.test.tsx | 12 ++ .../organisms/widgets/table-of-contents.tsx | 53 +++++++ src/utils/hooks/use-headings-tree.tsx | 153 +++++++++++++++++++++ 4 files changed, 259 insertions(+) create mode 100644 src/components/organisms/widgets/table-of-contents.stories.tsx create mode 100644 src/components/organisms/widgets/table-of-contents.test.tsx create mode 100644 src/components/organisms/widgets/table-of-contents.tsx create mode 100644 src/utils/hooks/use-headings-tree.tsx (limited to 'src/utils/hooks') diff --git a/src/components/organisms/widgets/table-of-contents.stories.tsx b/src/components/organisms/widgets/table-of-contents.stories.tsx new file mode 100644 index 0000000..fba7c54 --- /dev/null +++ b/src/components/organisms/widgets/table-of-contents.stories.tsx @@ -0,0 +1,41 @@ +import { ComponentMeta, ComponentStory } from '@storybook/react'; +import { IntlProvider } from 'react-intl'; +import ToCWidget from './table-of-contents'; + +/** + * TableOfContents - Storybook Meta + */ +export default { + title: 'Organisms/Widgets', + component: ToCWidget, + argTypes: { + wrapper: { + control: { + type: null, + }, + description: + 'A reference to the HTML element that contains the headings.', + type: { + name: 'string', + required: true, + }, + }, + }, + decorators: [ + (Story) => ( + + + + ), + ], +} as ComponentMeta; + +const Template: ComponentStory = (args) => ( + +); + +/** + * Widgets Stories - Table of Contents + */ +export const TableOfContents = Template.bind({}); +TableOfContents.args = {}; diff --git a/src/components/organisms/widgets/table-of-contents.test.tsx b/src/components/organisms/widgets/table-of-contents.test.tsx new file mode 100644 index 0000000..2064f39 --- /dev/null +++ b/src/components/organisms/widgets/table-of-contents.test.tsx @@ -0,0 +1,12 @@ +import { render, screen } from '@test-utils'; +import TableOfContents from './table-of-contents'; + +describe('TableOfContents', () => { + it('renders the ToC title', () => { + const divEl = document.createElement('div'); + render(); + expect( + screen.getByRole('heading', { level: 2, name: /Table of Contents/i }) + ).toBeInTheDocument(); + }); +}); diff --git a/src/components/organisms/widgets/table-of-contents.tsx b/src/components/organisms/widgets/table-of-contents.tsx new file mode 100644 index 0000000..3778e02 --- /dev/null +++ b/src/components/organisms/widgets/table-of-contents.tsx @@ -0,0 +1,53 @@ +import useHeadingsTree, { type Heading } from '@utils/hooks/use-headings-tree'; +import { FC } from 'react'; +import { useIntl } from 'react-intl'; +import LinksListWidget, { type LinksListItems } from './links-list-widget'; + +type TableOfContentsProps = { + /** + * A reference to the HTML element that contains the headings. + */ + wrapper: HTMLElement; +}; + +/** + * Table of Contents widget component + * + * Render a table of contents. + */ +const TableOfContents: FC = ({ wrapper }) => { + const intl = useIntl(); + const headingsTree = useHeadingsTree(wrapper); + const title = intl.formatMessage({ + defaultMessage: 'Table of Contents', + description: 'TableOfContents: the widget title', + id: 'WKG9wj', + }); + + /** + * Convert an headings tree to list items. + * + * @param {Heading[]} tree - The headings tree. + * @returns {LinksListItems[]} The list items. + */ + const getItems = (tree: Heading[]): LinksListItems[] => { + return tree.map((heading) => { + return { + name: heading.title, + url: `#${heading.id}`, + child: getItems(heading.children), + }; + }); + }; + + return ( + + ); +}; + +export default TableOfContents; diff --git a/src/utils/hooks/use-headings-tree.tsx b/src/utils/hooks/use-headings-tree.tsx new file mode 100644 index 0000000..5506e8b --- /dev/null +++ b/src/utils/hooks/use-headings-tree.tsx @@ -0,0 +1,153 @@ +import { slugify } from '@utils/helpers/slugify'; +import { useCallback, useEffect, useMemo, useState } from 'react'; + +export type Heading = { + /** + * The heading depth. + */ + depth: number; + /** + * The heading id. + */ + id: string; + /** + * The heading children. + */ + children: Heading[]; + /** + * The heading title. + */ + title: string; +}; + +/** + * Get the headings tree of the given HTML element. + * + * @param {HTMLElement} wrapper - An HTML element that contains the headings. + * @returns {Heading[]} The headings tree. + */ +const useHeadingsTree = (wrapper: HTMLElement): Heading[] => { + const depths = useMemo(() => ['h2', 'h3', 'h4', 'h5', 'h6'], []); + const [allHeadings, setAllHeadings] = + useState>(); + const [headingsTree, setHeadingsTree] = useState([]); + + useEffect(() => { + const query = depths.join(', '); + const result: NodeListOf = + wrapper.querySelectorAll(query); + setAllHeadings(result); + }, [depths, wrapper]); + + const getDepth = useCallback( + /** + * Retrieve the heading element depth. + * + * @param {HTMLHeadingElement} el - An heading element. + * @returns {number} The heading depth. + */ + (el: HTMLHeadingElement): number => { + return depths.findIndex((depth) => depth === el.localName); + }, + [depths] + ); + + const formatHeadings = useCallback( + /** + * Convert a list of headings into an array of Heading objects. + * + * @param {NodeListOf} headings - A list of headings. + * @returns {Heading[]} An array of Heading objects. + */ + (headings: NodeListOf): Heading[] => { + const formattedHeadings: Heading[] = []; + + Array.from(headings).forEach((heading) => { + const title: string = heading.textContent!; + const id = slugify(title); + const depth = getDepth(heading); + const children: Heading[] = []; + + heading.id = id; + + formattedHeadings.push({ + depth, + id, + children, + title, + }); + }); + + return formattedHeadings; + }, + [getDepth] + ); + + const buildSubTree = useCallback( + /** + * Build the heading subtree. + * + * @param {Heading} parent - The heading parent. + * @param {Heading} currentHeading - The current heading element. + */ + (parent: Heading, currentHeading: Heading): void => { + if (parent.depth === currentHeading.depth - 1) { + parent.children.push(currentHeading); + } else { + const lastItem = parent.children[parent.children.length - 1]; + buildSubTree(lastItem, currentHeading); + } + }, + [] + ); + + const buildTree = useCallback( + /** + * Build a heading tree. + * + * @param {Heading[]} headings - An array of Heading objects. + * @returns {Heading[]} The headings tree. + */ + (headings: Heading[]): Heading[] => { + const tree: Heading[] = []; + + headings.forEach((heading) => { + if (heading.depth === 0) { + tree.push(heading); + } else { + const lastItem = tree[tree.length - 1]; + buildSubTree(lastItem, heading); + } + }); + + return tree; + }, + [buildSubTree] + ); + + const getHeadingsTree = useCallback( + /** + * Retrieve a headings tree from a list of headings element. + * + * @param {NodeListOf} headings - A headings list. + * @returns {Heading[]} The headings tree. + */ + (headings: NodeListOf): Heading[] => { + const formattedHeadings = formatHeadings(headings); + + return buildTree(formattedHeadings); + }, + [formatHeadings, buildTree] + ); + + useEffect(() => { + if (allHeadings) { + const headingsList = getHeadingsTree(allHeadings); + setHeadingsTree(headingsList); + } + }, [allHeadings, getHeadingsTree]); + + return headingsTree; +}; + +export default useHeadingsTree; -- cgit v1.2.3 From 8a6f09b564d5d2f02d0a2605f6b52070a910aaa3 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 25 Apr 2022 12:57:12 +0200 Subject: chore: add a PageLayout component --- src/components/atoms/layout/sidebar.module.scss | 5 + src/components/atoms/layout/sidebar.tsx | 6 +- src/components/molecules/layout/meta.module.scss | 17 + src/components/molecules/layout/meta.tsx | 14 +- .../molecules/nav/breadcrumb.stories.tsx | 13 + src/components/molecules/nav/breadcrumb.tsx | 22 +- .../organisms/layout/comment.stories.tsx | 10 - src/components/organisms/layout/header.module.scss | 2 +- .../organisms/layout/posts-list.module.scss | 11 +- .../organisms/layout/posts-list.stories.tsx | 7 + .../organisms/layout/summary.module.scss | 2 + src/components/templates/layout/layout.module.scss | 1 - .../templates/page/page-layout.module.scss | 85 ++++ .../templates/page/page-layout.stories.tsx | 520 +++++++++++++++++++++ src/components/templates/page/page-layout.test.tsx | 90 ++++ src/components/templates/page/page-layout.tsx | 166 +++++++ src/styles/abstracts/_placeholders.scss | 1 + src/styles/abstracts/placeholders/_layout.scss | 25 + src/utils/helpers/format.ts | 28 +- src/utils/hooks/use-is-mounted.tsx | 19 + 20 files changed, 1019 insertions(+), 25 deletions(-) create mode 100644 src/components/molecules/layout/meta.module.scss create mode 100644 src/components/templates/page/page-layout.module.scss create mode 100644 src/components/templates/page/page-layout.stories.tsx create mode 100644 src/components/templates/page/page-layout.test.tsx create mode 100644 src/components/templates/page/page-layout.tsx create mode 100644 src/styles/abstracts/placeholders/_layout.scss create mode 100644 src/utils/hooks/use-is-mounted.tsx (limited to 'src/utils/hooks') diff --git a/src/components/atoms/layout/sidebar.module.scss b/src/components/atoms/layout/sidebar.module.scss index da2acbe..5d36f18 100644 --- a/src/components/atoms/layout/sidebar.module.scss +++ b/src/components/atoms/layout/sidebar.module.scss @@ -5,3 +5,8 @@ margin-top: fun.convert-px(-2); } } + +.body { + position: sticky; + top: var(--spacing-xs); +} diff --git a/src/components/atoms/layout/sidebar.tsx b/src/components/atoms/layout/sidebar.tsx index 194ed9f..d13cc0d 100644 --- a/src/components/atoms/layout/sidebar.tsx +++ b/src/components/atoms/layout/sidebar.tsx @@ -18,7 +18,11 @@ export type SidebarProps = { * Render an aside element. */ const Sidebar: FC = ({ children, className = '' }) => { - return ; + return ( + + ); }; export default Sidebar; diff --git a/src/components/molecules/layout/meta.module.scss b/src/components/molecules/layout/meta.module.scss new file mode 100644 index 0000000..f7cc55b --- /dev/null +++ b/src/components/molecules/layout/meta.module.scss @@ -0,0 +1,17 @@ +@use "@styles/abstracts/mixins" as mix; + +.list { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + + @include mix.media("screen") { + @include mix.dimensions("sm") { + display: flex; + flex-flow: column nowrap; + } + } +} + +.value { + word-break: break-all; +} diff --git a/src/components/molecules/layout/meta.tsx b/src/components/molecules/layout/meta.tsx index fcce473..d05396e 100644 --- a/src/components/molecules/layout/meta.tsx +++ b/src/components/molecules/layout/meta.tsx @@ -3,6 +3,7 @@ import DescriptionList, { type DescriptionListItem, } from '@components/atoms/lists/description-list'; import { FC, ReactNode } from 'react'; +import styles from './meta.module.scss'; export type MetaItem = { /** @@ -23,7 +24,7 @@ export type MetaProps = { /** * Set additional classnames to the meta wrapper. */ - className?: string; + className?: DescriptionListProps['className']; /** * The meta data. */ @@ -43,7 +44,7 @@ export type MetaProps = { * * Renders the page metadata. */ -const Meta: FC = ({ data, ...props }) => { +const Meta: FC = ({ className, data, ...props }) => { /** * Transform the metadata to description list item format. * @@ -68,7 +69,14 @@ const Meta: FC = ({ data, ...props }) => { return listItems; }; - return ; + return ( + + ); }; export default Meta; diff --git a/src/components/molecules/nav/breadcrumb.stories.tsx b/src/components/molecules/nav/breadcrumb.stories.tsx index 500ae6c..e26b480 100644 --- a/src/components/molecules/nav/breadcrumb.stories.tsx +++ b/src/components/molecules/nav/breadcrumb.stories.tsx @@ -22,6 +22,19 @@ export default { required: false, }, }, + itemClassName: { + control: { + type: 'text', + }, + table: { + category: 'Styles', + }, + description: 'Set additional classnames to the breadcrumb items.', + type: { + name: 'string', + required: false, + }, + }, items: { description: 'The breadcrumb items.', type: { diff --git a/src/components/molecules/nav/breadcrumb.tsx b/src/components/molecules/nav/breadcrumb.tsx index 6dc86a0..d184d65 100644 --- a/src/components/molecules/nav/breadcrumb.tsx +++ b/src/components/molecules/nav/breadcrumb.tsx @@ -26,6 +26,10 @@ export type BreadcrumbProps = { * Set additional classnames to the nav element. */ className?: string; + /** + * Set additional classnames to the breadcrumb items. + */ + itemClassName?: string; /** * The breadcrumb items */ @@ -37,9 +41,19 @@ export type BreadcrumbProps = { * * Render a breadcrumb navigation. */ -const Breadcrumb: FC = ({ items, ...props }) => { +const Breadcrumb: FC = ({ + itemClassName = '', + items, + ...props +}) => { const intl = useIntl(); + const ariaLabel = intl.formatMessage({ + defaultMessage: 'Breadcrumb', + description: 'Breadcrumb: an accessible name for the breadcrumb nav.', + id: '28nnDY', + }); + /** * Retrieve the breadcrumb list items. * @@ -49,12 +63,12 @@ const Breadcrumb: FC = ({ items, ...props }) => { const getListItems = (list: BreadcrumbItem[]): JSX.Element[] => { return list.map((item, index) => { const isLastItem = index === list.length - 1; - const itemClassnames = isLastItem + const itemStyles = isLastItem ? `${styles.item} screen-reader-text` : styles.item; return ( -
  • +
  • {isLastItem ? item.name : {item.name}}
  • ); @@ -96,7 +110,7 @@ const Breadcrumb: FC = ({ items, ...props }) => { type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schemaJsonLd) }} /> -