From dcf72a394e395858b9a8ceda44a70a90f6d37fde Mon Sep 17 00:00:00 2001 From: Josh Wooding <12938082+joshwooding@users.noreply.github.com> Date: Wed, 26 Jun 2024 00:11:50 +0100 Subject: [PATCH] Upgrade Salt and replace components --- docs/index.mdx | 6 + package.json | 1 + packages/components-labs/package.json | 3 +- .../components-labs/src/Sitemap/index.tsx | 62 +++++------ packages/components/package.json | 4 +- .../FilterToolbar/FilterDropdown/index.tsx | 44 ++++---- .../FilterDropdown/styles.css.ts | 16 --- .../Search/__tests__/index.test.tsx | 5 +- .../src/FilterToolbar/Search/index.tsx | 44 +++++--- .../src/FilterToolbar/SortDropdown/index.tsx | 38 +++---- .../FilterToolbar/SortDropdown/styles.css.ts | 15 --- .../src/FilterView/NoResults/index.tsx | 9 +- .../src/FilterView/ResultCount/styles.css.ts | 4 +- packages/components/src/Icon/index.tsx | 5 +- packages/components/src/Icon/styles.css.ts | 7 ++ .../src/TabsBase/TabsMenuButton.tsx | 35 +++--- .../src/TabsBase/tabsMenuButton.css.ts | 24 +++- packages/components/src/styles.ts | 2 - packages/content-editor-plugin/package.json | 8 +- .../src/components/ActionMenu/ActionMenu.tsx | 42 ++++--- .../components/LinkEditor/SaveAdornment.tsx | 9 +- .../components/PersistEditDialog/index.tsx | 23 ++-- .../Toolbar/InsertBlockDropdown.tsx | 25 +++-- .../src/components/Toolbar/InsertImage.tsx | 11 +- .../src/components/Toolbar/InsertLink.tsx | 11 +- .../src/plugins/TableActionMenuPlugin.tsx | 77 ++++++------- packages/layouts/package.json | 3 +- packages/site-components/package.json | 3 +- .../src/AppHeaderControls/index.tsx | 54 ++++----- .../src/NavigationItem/NavigationItem.tsx | 3 +- packages/site-preset-styles/package.json | 4 +- packages/site/package.json | 4 +- packages/site/public/search-data.json | 2 +- packages/site/public/sitemap.xml | 9 -- packages/sitemap-component/package.json | 3 +- .../sitemap-component/src/SitemapToolbar.tsx | 33 +++--- packages/theme/package.json | 2 +- packages/theme/types/saltIconNames.d.ts | 3 + yarn.lock | 103 ++++++++++-------- 39 files changed, 374 insertions(+), 382 deletions(-) delete mode 100644 packages/components/src/FilterToolbar/FilterDropdown/styles.css.ts delete mode 100644 packages/components/src/FilterToolbar/SortDropdown/styles.css.ts create mode 100644 packages/components/src/Icon/styles.css.ts diff --git a/docs/index.mdx b/docs/index.mdx index 3cfa3a1fb..7f9104c2e 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -16,6 +16,12 @@ sharedConfig: link: /mosaic/author/index - title: Publish link: /mosaic/publish/index + - title: Support + links: + - title: FAQs + link: /mosaic/faqs/index + - title: Contact Us + link: /mosaic/contact-us/index footer: description: Coming soon title: Mosaic BETA diff --git a/package.json b/package.json index 7655b8b01..b1e0e5bca 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,7 @@ }, "scripts": { "build:site": "turbo run build --filter=@jpmorganchase/mosaic-site", + "build:packages": "turbo run build --filter=!@jpmorganchase/mosaic-site", "build": "turbo run build", "clean": "turbo run clean", "copy:rig:images": "cp -r ./assets/[!.]* ./packages/rig/public/img", diff --git a/packages/components-labs/package.json b/packages/components-labs/package.json index 4c332f868..987960c7b 100644 --- a/packages/components-labs/package.json +++ b/packages/components-labs/package.json @@ -46,8 +46,7 @@ "dependencies": { "@jpmorganchase/mosaic-components": "^0.1.0-beta.78", "@jpmorganchase/mosaic-theme": "^0.1.0-beta.78", - "@salt-ds/core": "^1.26.0", - "@salt-ds/lab": "1.0.0-alpha.42", + "@salt-ds/core": "^1.30.0", "@vanilla-extract/css": "^1.6.0", "@vanilla-extract/recipes": "^0.2.1", "@vanilla-extract/sprinkles": "^1.3.0", diff --git a/packages/components-labs/src/Sitemap/index.tsx b/packages/components-labs/src/Sitemap/index.tsx index b40ebcd90..21f2c54a5 100644 --- a/packages/components-labs/src/Sitemap/index.tsx +++ b/packages/components-labs/src/Sitemap/index.tsx @@ -1,7 +1,6 @@ -import React, { RefObject, useEffect, useRef, useState } from 'react'; +import React, { RefObject, SyntheticEvent, useEffect, useRef, useState } from 'react'; import * as d3 from 'd3'; -import { Spinner } from '@salt-ds/core'; -import { Dropdown, DropdownButton, SelectionChangeHandler } from '@salt-ds/lab'; +import { Spinner, Dropdown, Option } from '@salt-ds/core'; import warning from 'warning'; import { Icon, Caption2 } from '@jpmorganchase/mosaic-components'; @@ -19,6 +18,8 @@ export interface SitemapProps { initialNamespaceFilters?: string[]; } +const dottedFileFilter = (pagePath: string) => /\/[^.]*$/.test(pagePath); + const filterPaths = (slugs: string[], namespaceFilters: string[]) => { const namespaceFilter = (pagePath: string) => { if (!namespaceFilters.length) { @@ -37,21 +38,6 @@ const filterPaths = (slugs: string[], namespaceFilters: string[]) => { return filteredPaths; }; -const drawSitemap = (filteredPaths: string[], containerRef: RefObject) => { - if (!containerRef?.current) { - throw new Error('no container ref defined for sitemap'); - } - - d3.select(containerRef.current).html(''); - d3.select(containerRef.current).append(() => - drawTree(parseFileSystem(filteredPaths), { - label: node => node.name.substring(node.name.lastIndexOf('/') + 1), - link: node => node.link, - width: 1152 - }).node() - ); -}; - type FileSystemBase = { name: string; parent: string | undefined; @@ -108,7 +94,20 @@ const parseFileSystem = (fileSystem: any) => { .parentId((data: FileSystemItem) => data.parent)(hierachyData); }; -const dottedFileFilter = (pagePath: string) => /\/[^.]*$/.test(pagePath); +const drawSitemap = (filteredPaths: string[], containerRef: RefObject) => { + if (!containerRef?.current) { + throw new Error('no container ref defined for sitemap'); + } + + d3.select(containerRef.current).html(''); + d3.select(containerRef.current).append(() => + drawTree(parseFileSystem(filteredPaths), { + label: node => node.name.substring(node.name.lastIndexOf('/') + 1), + link: node => node.link, + width: 1152 + }).node() + ); +}; const filterButtonLabel = (selectedItems: string[] | undefined) => { if (!selectedItems || selectedItems.length === 0) { @@ -130,7 +129,6 @@ export const Sitemap: React.FC> = ({ const containerRef = useRef(null); const dataRef = useRef(); const [loading, setLoading] = useState(true); - const [, setIsOpen] = useState(false); const [error, setError] = useState(); const [namespaceFilters, setNamespaceFilters] = useState(initialNamespaceFilters); const [namespaces, setNamespaces] = useState([]); @@ -182,7 +180,7 @@ export const Sitemap: React.FC> = ({ } }, [href, namespaceFilters]); - const handleSelect: SelectionChangeHandler = (_e, selectedItems) => { + const handleSelect = (_e: SyntheticEvent, selectedItems: string[]) => { setNamespaceFilters(selectedItems); }; @@ -193,18 +191,18 @@ export const Sitemap: React.FC> = ({ <> Number of pages: {pageCount} - } - width={200} - onOpenChange={setIsOpen} + startAdornment={} + value={filterButtonLabel(namespaceFilters)} + style={{ width: 200 }} onSelectionChange={handleSelect} - selectionStrategy="multiple" - source={namespaces} - /> + multiselect + > + {namespaces.map(namespace => ( + + ))} + ) : null} diff --git a/packages/components/package.json b/packages/components/package.json index cde2568f7..31cdfd1a7 100644 --- a/packages/components/package.json +++ b/packages/components/package.json @@ -46,8 +46,8 @@ "dependencies": { "@jpmorganchase/mosaic-store": "^0.1.0-beta.78", "@jpmorganchase/mosaic-theme": "^0.1.0-beta.78", - "@salt-ds/core": "^1.26.0", - "@salt-ds/lab": "1.0.0-alpha.42", + "@salt-ds/core": "^1.30.0", + "@salt-ds/lab": "1.0.0-alpha.48", "@vanilla-extract/css": "^1.6.0", "@vanilla-extract/sprinkles": "^1.3.0", "@vanilla-extract/recipes": "^0.2.1", diff --git a/packages/components/src/FilterToolbar/FilterDropdown/index.tsx b/packages/components/src/FilterToolbar/FilterDropdown/index.tsx index 7f80285c4..f1ff6b3f7 100644 --- a/packages/components/src/FilterToolbar/FilterDropdown/index.tsx +++ b/packages/components/src/FilterToolbar/FilterDropdown/index.tsx @@ -1,8 +1,6 @@ -import React, { useMemo, useState } from 'react'; -import classnames from 'clsx'; -import { Dropdown, DropdownButton, DropdownProps, SelectionChangeHandler } from '@salt-ds/lab'; +import React, { SyntheticEvent, useMemo } from 'react'; +import { Dropdown, DropdownProps, Option } from '@salt-ds/core'; import { Icon } from '../../Icon'; -import styles from './styles.css'; import { useToolbarDispatch, useToolbarState } from '../ToolbarProvider'; const defaultButtonLabel = (selectedItems: string[] | undefined) => { @@ -15,9 +13,12 @@ const defaultButtonLabel = (selectedItems: string[] | undefined) => { return `${selectedItems.length} Items Selected`; }; -export interface FilterDropdownProps extends DropdownProps { +export interface FilterDropdownProps extends DropdownProps { /** Callback to translate the selected list item to a Button label */ labelButton?: (selectedItems: string[] | undefined) => string; + /** Dropdown list source */ + source?: string[]; + itemToString?: DropdownProps['valueToString']; } const CLEAR_ALL = 'Clear all'; @@ -31,32 +32,27 @@ export function FilterDropdown({ }: FilterDropdownProps) { const dispatch = useToolbarDispatch(); const { filters = [] } = useToolbarState(); - const [isOpen, setIsOpen] = useState(false); const listItems = useMemo(() => (source.length > 1 ? [...source, CLEAR_ALL] : source), [source]); - const handleSelect: SelectionChangeHandler = (_e, selectedItems) => { + const handleSelect = (_e: SyntheticEvent, selectedItems: string[]) => { const nextSelectedItems: string[] = selectedItems.includes(CLEAR_ALL) ? [] : selectedItems; dispatch({ type: 'setFilters', value: nextSelectedItems }); }; return ( - - aria-label={isOpen ? 'close filters menu' : 'open filters menu'} - className={classnames(className, styles.root)} - itemToString={itemToString} - onOpenChange={setIsOpen} + } onSelectionChange={handleSelect} selected={filters} - selectionStrategy="multiple" - source={listItems} - triggerComponent={ - - - - - } - width={200} + multiselect + style={{ width: 200 }} {...rest} - /> + > + {listItems.map(item => ( + ); } diff --git a/packages/components/src/FilterToolbar/FilterDropdown/styles.css.ts b/packages/components/src/FilterToolbar/FilterDropdown/styles.css.ts deleted file mode 100644 index 7f305a18d..000000000 --- a/packages/components/src/FilterToolbar/FilterDropdown/styles.css.ts +++ /dev/null @@ -1,16 +0,0 @@ -import { style, globalStyle } from '@vanilla-extract/css'; - -const triggerRoot = style({ display: 'inline-flex', alignItems: 'center' }); - -export default { - root: style({ - display: 'flex !important', - alignSelf: 'stretch', - alignItems: 'center' - }), - triggerRoot -}; - -globalStyle(`${triggerRoot} svg.saltIcon`, { - vars: { '--saltIcon-size-multiplier': '1.2!important' } -}); diff --git a/packages/components/src/FilterToolbar/Search/__tests__/index.test.tsx b/packages/components/src/FilterToolbar/Search/__tests__/index.test.tsx index 2a479db41..6cf842744 100644 --- a/packages/components/src/FilterToolbar/Search/__tests__/index.test.tsx +++ b/packages/components/src/FilterToolbar/Search/__tests__/index.test.tsx @@ -11,10 +11,7 @@ test('updates the toolbar filters state when Filter 2 is selected', async () => // arrange const { getByTestId } = render( - + ); // action diff --git a/packages/components/src/FilterToolbar/Search/index.tsx b/packages/components/src/FilterToolbar/Search/index.tsx index f2f83c59d..b98f8f8d6 100644 --- a/packages/components/src/FilterToolbar/Search/index.tsx +++ b/packages/components/src/FilterToolbar/Search/index.tsx @@ -1,33 +1,49 @@ -import React from 'react'; +import React, { ChangeEvent, SyntheticEvent, useState } from 'react'; import classnames from 'clsx'; -import { escapeRegExp, ComboBox, ComboBoxProps, SelectionChangeHandler } from '@salt-ds/lab'; +import { ComboBox, Option, ComboBoxProps } from '@salt-ds/core'; import { Icon } from '../../Icon'; import { useToolbarDispatch } from '../ToolbarProvider'; -import styles from '../SortDropdown/styles.css'; +import styles from './styles.css'; -export interface FilterSearchProps extends ComboBoxProps {} +const regExp = /[.*+?^${}()|[\]\\]/g; + +function escapeRegExp(string: string): string { + return string.replace(regExp, '\\$&'); +} + +export interface FilterSearchProps extends ComboBoxProps { + source: string[]; +} export function FilterSearch({ className, source = [], ...rest }: FilterSearchProps) { const dispatch = useToolbarDispatch(); + const [value, setValue] = useState(''); // TODO convert to multiselect once Salt supports Multiselect from a ComboBox - const handleSelect: SelectionChangeHandler = (_e, item) => { - const value = item === null ? [] : [item]; - dispatch({ type: 'setFilters', value }); + const handleSelect = (_e: SyntheticEvent, newSelected: string[]) => { + dispatch({ type: 'setFilters', value: newSelected }); + }; + + const handleChange = (event: ChangeEvent) => { + setValue(event.target.value); }; - const getFilterRegex: (text: string) => RegExp = value => - new RegExp(`\\b(${escapeRegExp(value)})`, 'gi'); return ( }} + startAdornment={} className={classnames(className, styles.root)} - getFilterRegex={getFilterRegex} onSelectionChange={handleSelect} - source={source} - width={200} + value={value} + onChange={handleChange} + style={{ width: 200 }} {...rest} - /> + > + {source + .filter(item => item.match(new RegExp(`\\b(${escapeRegExp(value)})`, 'gi'))) + .map(item => ( + ); } diff --git a/packages/components/src/FilterToolbar/SortDropdown/index.tsx b/packages/components/src/FilterToolbar/SortDropdown/index.tsx index 66d07277c..8b0cddaf3 100644 --- a/packages/components/src/FilterToolbar/SortDropdown/index.tsx +++ b/packages/components/src/FilterToolbar/SortDropdown/index.tsx @@ -1,18 +1,17 @@ -import React, { useState } from 'react'; -import classnames from 'clsx'; -import { Dropdown, DropdownButton, DropdownProps, SelectionChangeHandler } from '@salt-ds/lab'; +import React, { SyntheticEvent, useState } from 'react'; +import { Dropdown, Option, DropdownProps } from '@salt-ds/core'; import { Icon } from '../../Icon'; -import styles from './styles.css'; import { useToolbarDispatch, useToolbarState } from '../ToolbarProvider'; import { itemToLabel as defaultItemToLabel, source as defaultSource } from './defaultSort'; -type PartialDropdownProps = Omit, 'source'>; +type PartialDropdownProps = DropdownProps; export interface FilterSortDropdownProps extends PartialDropdownProps { /** Callback to translate the selected list item to a Button label */ labelButton?: (selectedItem: string | undefined) => string; /** Dropdown list source */ source?: string[]; + itemToString?: DropdownProps['valueToString']; } export function FilterSortDropdown({ @@ -26,28 +25,27 @@ export function FilterSortDropdown({ const { sort = source[0] } = useToolbarState(); const [, setIsOpen] = useState(false); - const handleSelect: SelectionChangeHandler = (_e, selectedItem) => { - if (selectedItem) { - dispatch({ type: 'setSort', value: selectedItem }); + const handleSelect = (_e: SyntheticEvent, selectedItem: string[]) => { + if (selectedItem[0]) { + dispatch({ type: 'setSort', value: selectedItem[0] }); } }; return ( } + className={className} + valueToString={itemToString} + value={labelButton ? labelButton(sort) : sort} onOpenChange={setIsOpen} onSelectionChange={handleSelect} - selected={sort} - source={source} - triggerComponent={ - - - - - } - width={150} + selected={[sort]} + style={{ width: 150 }} {...rest} - /> + > + {source.map(item => ( + ); } diff --git a/packages/components/src/FilterToolbar/SortDropdown/styles.css.ts b/packages/components/src/FilterToolbar/SortDropdown/styles.css.ts deleted file mode 100644 index 7736414a5..000000000 --- a/packages/components/src/FilterToolbar/SortDropdown/styles.css.ts +++ /dev/null @@ -1,15 +0,0 @@ -import { style, globalStyle } from '@vanilla-extract/css'; -const triggerRoot = style({ display: 'inline-flex', alignItems: 'center' }); - -export default { - root: style({ - display: 'flex !important', - alignSelf: 'stretch', - alignItems: 'center' - }), - triggerRoot -}; - -globalStyle(`${triggerRoot} svg.saltIcon`, { - vars: { '--saltIcon-size-multiplier': '1.2!important' } -}); diff --git a/packages/components/src/FilterView/NoResults/index.tsx b/packages/components/src/FilterView/NoResults/index.tsx index 11565e868..fdabf5cec 100644 --- a/packages/components/src/FilterView/NoResults/index.tsx +++ b/packages/components/src/FilterView/NoResults/index.tsx @@ -1,6 +1,6 @@ import React from 'react'; import classnames from 'clsx'; -import { ContentStatus } from '@salt-ds/lab'; +import { Text, StatusIndicator, StackLayout } from '@salt-ds/core'; import styles from './styles.css'; @@ -10,7 +10,12 @@ export interface FilterNoResultsProps { } export function DefaultNoResults() { - return ; + return ( + + + No Results Found + + ); } export const FilterNoResults: React.FC> = ({ diff --git a/packages/components/src/FilterView/ResultCount/styles.css.ts b/packages/components/src/FilterView/ResultCount/styles.css.ts index d14bc69f2..754278401 100644 --- a/packages/components/src/FilterView/ResultCount/styles.css.ts +++ b/packages/components/src/FilterView/ResultCount/styles.css.ts @@ -1,11 +1,9 @@ import { style } from '@vanilla-extract/css'; -import { responsiveSprinkles } from '@jpmorganchase/mosaic-theme'; export default { root: style([ { flexGrow: 1 - }, - responsiveSprinkles({ paddingY: ['x4', 'x4', 'x4', 'x4'] }) + } ]) }; diff --git a/packages/components/src/Icon/index.tsx b/packages/components/src/Icon/index.tsx index 01cb2d2ce..ac310434a 100644 --- a/packages/components/src/Icon/index.tsx +++ b/packages/components/src/Icon/index.tsx @@ -1,5 +1,8 @@ import React from 'react'; import { icons, IconNames } from '@jpmorganchase/mosaic-theme'; +import classnames from 'clsx'; + +import styles from './styles.css'; export interface IconProps { /** Additional class name for root class override. */ @@ -43,7 +46,7 @@ export const Icon: React.FC> = ({ const IconComponent = icons[currentIconName]; const iconSize = typeof size === 'string' ? iconSizeMap[size] : size; return ( - + ); diff --git a/packages/components/src/Icon/styles.css.ts b/packages/components/src/Icon/styles.css.ts new file mode 100644 index 000000000..fd2d4f2e3 --- /dev/null +++ b/packages/components/src/Icon/styles.css.ts @@ -0,0 +1,7 @@ +import { style } from '@vanilla-extract/css'; + +export default { + root: style({ + display: 'contents' + }) +}; diff --git a/packages/components/src/TabsBase/TabsMenuButton.tsx b/packages/components/src/TabsBase/TabsMenuButton.tsx index 2e92fed8e..81630996e 100644 --- a/packages/components/src/TabsBase/TabsMenuButton.tsx +++ b/packages/components/src/TabsBase/TabsMenuButton.tsx @@ -1,10 +1,11 @@ import React, { FC, KeyboardEvent, MouseEvent } from 'react'; -import { MenuButton, MenuDescriptor } from '@salt-ds/lab'; +import { Menu, MenuItem, MenuPanel, MenuTrigger, Button } from '@salt-ds/core'; import classnames from 'clsx'; import styles from './tabsMenuButton.css'; -import { TabsLinkItem } from './TabsLink'; -import { TabMenuItemType } from './index'; +import type { TabsLinkItem } from './TabsLink'; +import type { TabMenuItemType } from './index'; +import { Icon } from '../Icon'; export interface TabsMenuButtonItem { /** @@ -14,7 +15,7 @@ export interface TabsMenuButtonItem { /** Collection of link options */ links: TabsLinkItem[]; /** Callback when Tab is selected */ - onSelect: (event: MouseEvent | KeyboardEvent, sourceItem: MenuDescriptor) => void; + onSelect: (event: MouseEvent | KeyboardEvent, sourceItem: TabsLinkItem) => void; /** Title of Tab */ title: string; /** Type of Tab */ @@ -28,14 +29,20 @@ export interface TabsMenuButtonProps { } export const TabsMenuButton: FC = ({ children, className, item }) => ( - item.onSelect(event, sourceItem) - }} - > - {item.title || item.label} - {children} - + + + + + + {item.links.map(link => ( + item.onSelect(event, link)}> + {link.title || link.label} + + ))} + + ); diff --git a/packages/components/src/TabsBase/tabsMenuButton.css.ts b/packages/components/src/TabsBase/tabsMenuButton.css.ts index 45fa0ea0f..3724b5fe7 100644 --- a/packages/components/src/TabsBase/tabsMenuButton.css.ts +++ b/packages/components/src/TabsBase/tabsMenuButton.css.ts @@ -1,5 +1,5 @@ import { style } from '@vanilla-extract/css'; -import { responsiveSprinkles, link } from '@jpmorganchase/mosaic-theme'; +import { link, darkMode, lightMode, vars } from '@jpmorganchase/mosaic-theme'; export default { root: style([ @@ -13,13 +13,27 @@ export default { letterSpacing: 'inherit', textTransform: 'inherit', textDecoration: 'none', - justifyContent: 'center' + justifyContent: 'center', + fontWeight: 'inherit' + }, + [`${darkMode} [aria-expanded="true"][aria-haspopup="menu"].&`]: { + background: 'inherit', + color: vars.color.dark.navigable.selectableLink.unselectedLabel + }, + [`${darkMode} [aria-expanded="true"][aria-haspopup="menu"].&:hover`]: { + background: vars.color.dark.neutral.background.emphasis, + color: vars.color.dark.navigable.selectableLink.unselectedLabel + }, + [`${lightMode} [aria-expanded="true"][aria-haspopup="menu"].&`]: { + background: 'inherit', + color: vars.color.light.navigable.selectableLink.unselectedLabel + }, + [`${lightMode} [aria-expanded="true"][aria-haspopup="menu"].&:hover`]: { + background: vars.color.light.neutral.background.emphasis, + color: vars.color.light.navigable.selectableLink.unselectedLabel } } }, - responsiveSprinkles({ - paddingX: ['x2', 'x2', 'x2', 'x2'] - }), link({ variant: 'selectable' }) ]) }; diff --git a/packages/components/src/styles.ts b/packages/components/src/styles.ts index 6b225edfa..4dadcd97d 100644 --- a/packages/components/src/styles.ts +++ b/packages/components/src/styles.ts @@ -11,10 +11,8 @@ import './Feature/FeatureTitle/styles.css'; import './Features/styles.css'; import './FilterToolbar/styles.css'; import './FilterToolbar/ContentArea/styles.css'; -import './FilterToolbar/FilterDropdown/styles.css'; import './FilterToolbar/PillGroup/styles.css'; import './FilterToolbar/Search/styles.css'; -import './FilterToolbar/SortDropdown/styles.css'; import './FilterView/ContentArea/styles.css'; import './FilterView/NoResults/styles.css'; import './FilterView/Pagination/styles.css'; diff --git a/packages/content-editor-plugin/package.json b/packages/content-editor-plugin/package.json index 7f222f210..351704258 100644 --- a/packages/content-editor-plugin/package.json +++ b/packages/content-editor-plugin/package.json @@ -43,10 +43,10 @@ "dependencies": { "@jpmorganchase/mosaic-components": "^0.1.0-beta.78", "@jpmorganchase/mosaic-theme": "^0.1.0-beta.78", - "@salt-ds/core": "^1.26.0", - "@salt-ds/icons": "^1.11.1", - "@salt-ds/lab": "1.0.0-alpha.42", - "@salt-ds/theme": "^1.14.0", + "@salt-ds/core": "^1.30.0", + "@salt-ds/icons": "^1.12.1", + "@salt-ds/lab": "1.0.0-alpha.48", + "@salt-ds/theme": "^1.19.0", "@floating-ui/react": "^0.26.6", "@lexical/code": "^0.11.1", "@lexical/link": "^0.11.1", diff --git a/packages/content-editor-plugin/src/components/ActionMenu/ActionMenu.tsx b/packages/content-editor-plugin/src/components/ActionMenu/ActionMenu.tsx index 1d440ec31..60a13b033 100644 --- a/packages/content-editor-plugin/src/components/ActionMenu/ActionMenu.tsx +++ b/packages/content-editor-plugin/src/components/ActionMenu/ActionMenu.tsx @@ -1,26 +1,36 @@ import React from 'react'; -import { MenuButton, MenuDescriptor } from '@salt-ds/lab'; -import { Icon } from '@jpmorganchase/mosaic-components'; +import { Menu, MenuTrigger, MenuPanel, MenuItem } from '@salt-ds/core'; +import { Icon, Button } from '@jpmorganchase/mosaic-components'; +import { IconNames } from '@jpmorganchase/mosaic-theme'; -import type { CascadingMenuProps } from '@salt-ds/lab'; +export type ActionMenuItem = { + title: string; + icon: IconNames; +}; -export type ActionMenuSource = MenuDescriptor; +export type ActionMenuSource = ActionMenuItem[]; interface ActionMenuProps { - initialSource: CascadingMenuProps['initialSource']; - onItemClick: CascadingMenuProps['onItemClick']; + items: ActionMenuSource; + onItemClick: (item: ActionMenuItem) => void; } -export function ActionMenu({ initialSource, onItemClick }: ActionMenuProps) { +export function ActionMenu({ items, onItemClick }: ActionMenuProps) { return ( - - - + + + + + + {items.map(item => ( + onItemClick(item)}> + + {item.title} + + ))} + + ); } diff --git a/packages/content-editor-plugin/src/components/LinkEditor/SaveAdornment.tsx b/packages/content-editor-plugin/src/components/LinkEditor/SaveAdornment.tsx index 14bfc6d71..66c658806 100644 --- a/packages/content-editor-plugin/src/components/LinkEditor/SaveAdornment.tsx +++ b/packages/content-editor-plugin/src/components/LinkEditor/SaveAdornment.tsx @@ -1,7 +1,6 @@ import React from 'react'; import { Icon } from '@jpmorganchase/mosaic-components'; import type { ButtonProps } from '@jpmorganchase/mosaic-components'; -import { StaticInputAdornment } from '@salt-ds/lab'; import { ToolbarButton } from '../Toolbar/ToolbarButton'; interface SaveAdornmentProps { @@ -9,9 +8,7 @@ interface SaveAdornmentProps { } export const SaveAdornment = ({ onSave }: SaveAdornmentProps) => ( - - - - - + + + ); diff --git a/packages/content-editor-plugin/src/components/PersistEditDialog/index.tsx b/packages/content-editor-plugin/src/components/PersistEditDialog/index.tsx index fbfaf03f9..3211b5a31 100644 --- a/packages/content-editor-plugin/src/components/PersistEditDialog/index.tsx +++ b/packages/content-editor-plugin/src/components/PersistEditDialog/index.tsx @@ -4,7 +4,6 @@ import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext import { $convertToMarkdownString } from '@lexical/markdown'; import { Link, P2, Button } from '@jpmorganchase/mosaic-components'; import { DialogHeader, DialogContent, DialogActions } from '@salt-ds/core'; -import { ButtonBar } from '@salt-ds/lab'; import { SourceWorkflowMessageEvent } from '@jpmorganchase/mosaic-types'; import { useEditorUser, usePageState } from '../../store'; @@ -134,18 +133,16 @@ export const PersistDialog = ({ meta, persistUrl }: PersistDialogProps) => { )} - - - - + + ); diff --git a/packages/content-editor-plugin/src/components/Toolbar/InsertBlockDropdown.tsx b/packages/content-editor-plugin/src/components/Toolbar/InsertBlockDropdown.tsx index 2da08ad71..6f3e8dbb9 100644 --- a/packages/content-editor-plugin/src/components/Toolbar/InsertBlockDropdown.tsx +++ b/packages/content-editor-plugin/src/components/Toolbar/InsertBlockDropdown.tsx @@ -1,5 +1,5 @@ -import React from 'react'; -import { Dropdown, SelectionChangeHandler } from '@salt-ds/lab'; +import React, { SyntheticEvent } from 'react'; +import { Dropdown, Option } from '@salt-ds/core'; import { $createCodeNode } from '@lexical/code'; import { INSERT_ORDERED_LIST_COMMAND, INSERT_UNORDERED_LIST_COMMAND } from '@lexical/list'; import { $createHeadingNode, $createQuoteNode, HeadingTagType } from '@lexical/rich-text'; @@ -106,7 +106,8 @@ export function InsertBlockDropdown({ } }; - const handleSelect: SelectionChangeHandler = (_event, item) => { + const handleSelect = (_event: SyntheticEvent, items: BlockSourceType[]) => { + const item = items[0]; if (!item) { return; } @@ -120,15 +121,15 @@ export function InsertBlockDropdown({ const selectedBlockSourceIndex = source.findIndex(item => item.type === blockSourceType); return ( - + defaultSelected={[source[selectedBlockSourceIndex]]} + valueToString={itemToString} onSelectionChange={handleSelect} - source={source} - width={132} - /> + style={{ width: 132 }} + > + {source.map(item => ( + ); } diff --git a/packages/content-editor-plugin/src/components/Toolbar/InsertImage.tsx b/packages/content-editor-plugin/src/components/Toolbar/InsertImage.tsx index 18b805c05..742e168ad 100644 --- a/packages/content-editor-plugin/src/components/Toolbar/InsertImage.tsx +++ b/packages/content-editor-plugin/src/components/Toolbar/InsertImage.tsx @@ -11,7 +11,6 @@ import { DialogContent, DialogActions } from '@salt-ds/core'; -import { ButtonBar } from '@salt-ds/lab'; import { ToolbarButton } from './ToolbarButton'; import { Dialog } from '../Dialog'; @@ -124,12 +123,10 @@ export const InsertImage = () => { - - - - + + diff --git a/packages/content-editor-plugin/src/components/Toolbar/InsertLink.tsx b/packages/content-editor-plugin/src/components/Toolbar/InsertLink.tsx index 35e10aa20..4680f0842 100644 --- a/packages/content-editor-plugin/src/components/Toolbar/InsertLink.tsx +++ b/packages/content-editor-plugin/src/components/Toolbar/InsertLink.tsx @@ -11,7 +11,6 @@ import { DialogActions, DialogHeader } from '@salt-ds/core'; -import { ButtonBar } from '@salt-ds/lab'; import { $getSelection, $isRangeSelection } from 'lexical'; import { ToolbarButton } from './ToolbarButton'; @@ -136,12 +135,10 @@ export const InsertLinkDialog = () => { - - - - + + ); diff --git a/packages/content-editor-plugin/src/plugins/TableActionMenuPlugin.tsx b/packages/content-editor-plugin/src/plugins/TableActionMenuPlugin.tsx index 6b7a1d85a..d6b978941 100644 --- a/packages/content-editor-plugin/src/plugins/TableActionMenuPlugin.tsx +++ b/packages/content-editor-plugin/src/plugins/TableActionMenuPlugin.tsx @@ -16,52 +16,41 @@ import { } from '@lexical/table'; import { useFloatingUI } from '@salt-ds/core'; import { useDismiss, useInteractions } from '@floating-ui/react'; -import { - ArrowDownIcon, - ArrowLeftIcon, - ArrowRightIcon, - ArrowUpIcon, - DeleteIcon, - DeleteSolidIcon -} from '@salt-ds/icons'; -import type { MenuDescriptor } from '@salt-ds/lab'; import { Popper } from '../components/Popper/Popper'; -import { ActionMenu, ActionMenuSource } from '../components/ActionMenu/ActionMenu'; +import { ActionMenu, ActionMenuItem, ActionMenuSource } from '../components/ActionMenu/ActionMenu'; import styles from './TableActionMenuPlugin.css'; -const initialSource: ActionMenuSource = { - menuItems: [ - { - title: 'Insert Row Above', - icon: ArrowUpIcon - }, - { - title: 'Insert Row Below', - icon: ArrowDownIcon - }, - { - title: 'Insert Column Left', - icon: ArrowLeftIcon - }, - { - title: 'Insert Column Right', - icon: ArrowRightIcon - }, - { - title: 'Delete Row', - icon: DeleteIcon - }, - { - title: 'Delete Column', - icon: DeleteIcon - }, - { - title: 'Delete Table', - icon: DeleteSolidIcon - } - ] -}; +const menuItems: ActionMenuSource = [ + { + title: 'Insert Row Above', + icon: 'arrowUp' + }, + { + title: 'Insert Row Below', + icon: 'arrowDown' + }, + { + title: 'Insert Column Left', + icon: 'arrowLeft' + }, + { + title: 'Insert Column Right', + icon: 'arrowRight' + }, + { + title: 'Delete Row', + icon: 'delete' + }, + { + title: 'Delete Column', + icon: 'delete' + }, + { + title: 'Delete Table', + icon: 'deleteSolid' + } +]; interface TableActionMenuProps { editor: LexicalEditor; @@ -70,7 +59,7 @@ interface TableActionMenuProps { } function TableActionMenu({ editor, tableCellNode, onComplete }: TableActionMenuProps) { - const handleMenuSelect = (item: MenuDescriptor | null) => { + const handleMenuSelect = (item: ActionMenuItem) => { if (!item) { return; } @@ -174,7 +163,7 @@ function TableActionMenu({ editor, tableCellNode, onComplete }: TableActionMenuP }); }, [editor, tableCellNode, onComplete]); - return ; + return ; } export function TableActionMenuPlugin() { diff --git a/packages/layouts/package.json b/packages/layouts/package.json index b89adb176..2ba1cbfc4 100644 --- a/packages/layouts/package.json +++ b/packages/layouts/package.json @@ -46,8 +46,7 @@ "@jpmorganchase/mosaic-site-components": "^0.1.0-beta.78", "@jpmorganchase/mosaic-store": "^0.1.0-beta.78", "@jpmorganchase/mosaic-theme": "^0.1.0-beta.78", - "@salt-ds/core": "^1.26.0", - "@salt-ds/lab": "1.0.0-alpha.42", + "@salt-ds/core": "^1.30.0", "@vanilla-extract/css": "^1.6.0", "@vanilla-extract/sprinkles": "^1.3.0", "clsx": "^2.0.0", diff --git a/packages/site-components/package.json b/packages/site-components/package.json index 0241530b4..97570e95e 100644 --- a/packages/site-components/package.json +++ b/packages/site-components/package.json @@ -51,7 +51,8 @@ "@jpmorganchase/mosaic-site-middleware": "^0.1.0-beta.78", "@jpmorganchase/mosaic-store": "^0.1.0-beta.78", "@jpmorganchase/mosaic-theme": "^0.1.0-beta.78", - "@salt-ds/lab": "1.0.0-alpha.42", + "@salt-ds/core": "^1.30.0", + "@salt-ds/lab": "1.0.0-alpha.48", "@types/mdast": "^3.0.0", "@vanilla-extract/css": "^1.6.0", "@vanilla-extract/recipes": "^0.2.1", diff --git a/packages/site-components/src/AppHeaderControls/index.tsx b/packages/site-components/src/AppHeaderControls/index.tsx index abaff7482..fe2f26821 100644 --- a/packages/site-components/src/AppHeaderControls/index.tsx +++ b/packages/site-components/src/AppHeaderControls/index.tsx @@ -1,7 +1,6 @@ import React from 'react'; -import { Icon, Link } from '@jpmorganchase/mosaic-components'; -import { MenuButton, MenuDescriptor } from '@salt-ds/lab'; -import { useRouter } from 'next/router'; +import { Icon, Link, Button } from '@jpmorganchase/mosaic-components'; +import { Menu, MenuTrigger, MenuPanel, MenuItem } from '@salt-ds/core'; import { useContentEditor, EditorControls } from '@jpmorganchase/mosaic-content-editor-plugin'; import { useColorMode, useSearchIndex, useStoreActions } from '@jpmorganchase/mosaic-store'; import { useSession } from 'next-auth/react'; @@ -21,7 +20,6 @@ function toUpperFirst(str) { } export const AppHeaderControls: React.FC = () => { - const router = useRouter(); const colorMode = useColorMode(); const { setColorMode } = useStoreActions(); @@ -52,24 +50,16 @@ export const AppHeaderControls: React.FC = () => { }); } if (isLoginEnabled && isLoggedIn) { - actionMenuOptions = [...actionMenuOptions, { title: 'Logout', link: '/api/auth/signout' }]; - } - function handleMenuSelect(selectedMenuItem) { - if (selectedMenuItem?.link) { - if (selectedMenuItem.title.toLowerCase() === 'logout') { - window.location.href = selectedMenuItem.link; - } else { - router.push(selectedMenuItem.link); + actionMenuOptions = [ + ...actionMenuOptions, + { + title: 'Logout', + onSelect: () => { + window.location.href = '/api/auth/signout'; + } } - } else if (selectedMenuItem?.onSelect) { - selectedMenuItem.onSelect(); - } + ]; } - - const initialSource: MenuDescriptor = { - menuItems: actionMenuOptions - }; - return (
{isLoginEnabled && } @@ -90,18 +80,18 @@ export const AppHeaderControls: React.FC = () => { )}
)} - - - + + + + + + {actionMenuOptions.map(option => ( + {option.title} + ))} + + ); }; diff --git a/packages/site-components/src/NavigationItem/NavigationItem.tsx b/packages/site-components/src/NavigationItem/NavigationItem.tsx index d79fda77f..9c39b2e3c 100644 --- a/packages/site-components/src/NavigationItem/NavigationItem.tsx +++ b/packages/site-components/src/NavigationItem/NavigationItem.tsx @@ -7,7 +7,8 @@ import { ExpansionIcon } from './ExpansionIcon'; import { useWindow } from '@salt-ds/window'; import { useComponentCssInjection } from '@salt-ds/styles'; -import navigationItemCss from '@salt-ds/core/dist-es/navigation-item/NavigationItem.css.js'; +const navigationItemCss = + '/* Vars applied to root NavigationItem component */\n.saltNavigationItem-wrapper {\n display: flex;\n gap: var(--salt-spacing-100);\n align-items: center;\n position: relative;\n background: none;\n border: none;\n font-size: var(--salt-text-fontSize);\n text-decoration: none;\n cursor: var(--salt-selectable-cursor-hover);\n /* Hover off animation */\n transition: all var(--salt-duration-instant) ease-in-out;\n box-sizing: border-box;\n}\n\n/* Vars applied to NavigationItem component when root */\n.saltNavigationItem-rootItem {\n font-weight: var(--salt-text-fontWeight-strong);\n}\n\n/* Styles applied to NavigationItem icon */\n.saltNavigationItem-label .saltIcon {\n top: var(--salt-spacing-25);\n}\n\n/* Styles applied when orientation = "horizontal" */\n.saltNavigationItem-horizontal {\n min-height: calc(var(--salt-size-base) + var(--salt-spacing-100) * 2);\n padding: 0 var(--salt-spacing-100);\n width: fit-content;\n}\n\n/* Styles applied when orientation = "vertical" */\n.saltNavigationItem-vertical {\n min-height: calc(var(--salt-size-base) + var(--salt-spacing-50) * 2);\n padding-top: 0;\n padding-bottom: 0;\n padding-right: var(--salt-spacing-100);\n padding-left: calc(var(--salt-spacing-300) * (min(var(--saltNavigationItem-level, 0) + 1, 2)));\n width: 100%;\n}\n\n/* Styles applied to NavigationItem label */\n.saltNavigationItem-label {\n color: var(--salt-content-primary-foreground);\n line-height: var(--salt-text-lineHeight);\n font-family: var(--salt-text-fontFamily);\n padding-left: calc(var(--saltNavigationItem-level, 0) * var(--salt-spacing-100));\n flex: 1;\n text-align: left;\n display: flex;\n align-items: baseline;\n gap: var(--salt-spacing-100);\n}\n\n/* Styles applied when orientation = "horizontal" */\n.saltNavigationItem-horizontal {\n min-height: calc(var(--salt-size-base) + var(--salt-spacing-100) * 2);\n padding: 0 var(--salt-spacing-100);\n width: fit-content;\n}\n\n/* Styles applied when orientation = "vertical" */\n.saltNavigationItem-vertical {\n --saltButton-margin: var(--salt-spacing-50) 0;\n\n min-height: calc(var(--salt-size-base) + var(--salt-spacing-50) * 2);\n padding-right: var(--salt-spacing-100);\n padding-left: calc(var(--salt-spacing-300) * (min(var(--saltNavigationItem-level, 0) + 1, 2)));\n width: 100%;\n}\n\n/* Styles applied to NavigationItem label */\n.saltNavigationItem-label {\n color: var(--salt-content-primary-foreground);\n line-height: var(--salt-text-lineHeight);\n font-family: var(--salt-text-fontFamily);\n padding-left: calc(var(--saltNavigationItem-level, 0) * var(--salt-spacing-100));\n flex: 1;\n text-align: left;\n display: flex;\n align-items: baseline;\n gap: var(--salt-spacing-100);\n}\n\n/* Styles applied to NavigationItem Badge */\n.saltNavigationItem-label .saltBadge {\n margin-left: auto;\n}\n\n/* Styles applied to NavigationItem when focus is visible */\n.saltNavigationItem-wrapper:focus-visible {\n outline: var(--salt-focused-outline);\n}\n\n/* Styles applied to NavigationItem for non-keyboard focus */\n.saltNavigationItem-wrapper:focus:not(:focus-visible) {\n outline: 0;\n}\n\n/* Styles applied to activation line */\n.saltNavigationItem-wrapper::after {\n content: "";\n position: absolute;\n top: var(--salt-spacing-25);\n left: 0;\n display: block;\n}\n\n/* Styles applied to activation line when orientation = "horizontal" */\n.saltNavigationItem-horizontal::after {\n width: 100%;\n height: var(--salt-size-indicator);\n}\n\n/* Styles applied to activation line when orientation = "vertical" */\n.saltNavigationItem-vertical::after {\n width: var(--salt-size-indicator);\n left: var(--salt-spacing-25);\n height: calc(100% - var(--salt-spacing-50));\n}\n\n/* Styles applied to activation line on hover */\n.saltNavigationItem-wrapper:hover::after,\n.saltNavigationItem-wrapper:focus-visible::after {\n background: var(--salt-navigable-indicator-hover);\n /* Hover on animation */\n transition: all var(--salt-duration-perceptible) ease-in-out;\n}\n\n/* Styles applied to activation line when item is active */\n.saltNavigationItem-active::after,\n.saltNavigationItem-active:hover::after,\n.saltNavigationItem-active:focus::after {\n background: var(--salt-navigable-indicator-active);\n /* Hover on animation */\n transition: all var(--salt-duration-perceptible) ease-in-out;\n}\n'; type OptionalPartial = Partial>; diff --git a/packages/site-preset-styles/package.json b/packages/site-preset-styles/package.json index 09e04abba..e135959c6 100644 --- a/packages/site-preset-styles/package.json +++ b/packages/site-preset-styles/package.json @@ -30,8 +30,8 @@ "esbuild-node-externals": "^1.0.2" }, "dependencies": { - "@salt-ds/theme": "^1.14.0", - "@salt-ds/icons": "^1.11.1", + "@salt-ds/theme": "^1.19.0", + "@salt-ds/icons": "^1.12.1", "@jpmorganchase/mosaic-components": "0.1.0-beta.78", "@jpmorganchase/mosaic-labs-components": "0.1.0-beta.78", "@jpmorganchase/mosaic-open-api-component": "0.1.0-beta.78", diff --git a/packages/site/package.json b/packages/site/package.json index f431ab261..27beb83c8 100644 --- a/packages/site/package.json +++ b/packages/site/package.json @@ -42,8 +42,8 @@ "@jpmorganchase/mosaic-store": "^0.1.0-beta.78", "@jpmorganchase/mosaic-theme": "^0.1.0-beta.78", "@philpl/buble": "^0.19.7", - "@salt-ds/core": "^1.26.0", - "@salt-ds/lab": "1.0.0-alpha.42", + "@salt-ds/core": "^1.30.0", + "@salt-ds/lab": "1.0.0-alpha.48", "@types/react": "^18.0.26", "next": "^13.4.1", "next-auth": "^4.24.5" diff --git a/packages/site/public/search-data.json b/packages/site/public/search-data.json index af108d95c..a3f05ec70 100644 --- a/packages/site/public/search-data.json +++ b/packages/site/public/search-data.json @@ -1 +1 @@ -[{"title":"Mosaic","route":"/mosaic/index","content":["True to its name, Mosaic brings together several concepts—including content, design and technical infrastructure—to deliver a unified website experience that is truly greater than the sum of its individual parts.","With Mosaic, you can:","Don't move your content where it does not belong. ","Compose content from remote data sources which\n","are pulled at runtime by our content aggregator.","Visualize your content with your own theme, layouts and components or use the Mosaic Design\n","language.","Extend the existing code and add your own content source types through our simple plugin\n","architecture.","Publish your content through Server Side Rendering (SSR) or generate a snapshot of your content\n","and serve it as a Statically Generated Site (SGS).","Creating a website has never been so easy!"]},{"title":"Sitemap","route":"/mosaic/sitemap","content":["Sitemap"]},{"title":"Aliases","route":"/mosaic/author/aliases","content":["Aliases are virtual 'symlinks' of pages, allowing one page to take on one or more other routes.\n","This is not the same as copying the page, it is a primitive filesystem link which is resolved by Mosaic.","Use Cases","Aliases are great for linking to an old route if you've moved a page to a new place.\n","They can also be used to create short hand links to pages or to 'clone' a copy of a page into\n","another section of the site where it may be relevant.","Example","This is the frontmatter for this page:","---\n","title: Aliases\n","layout: DetailTechnical\n","aliases:\n"," - /mosaic/example/aliases\n","---","Try accessing this page from ","/mosaic/example/aliases"]},{"title":"Fragments","route":"/mosaic/author/fragments","content":["Fragments, also known as content fragments, are powerful tools that allow you to incorporate content from other pages into your documentation. ","By creating an MDX file and using the ","generic directives"," syntax ",", you can easily render the fragment in another file, providing modularity and reusability to your content.","Use Cases","Fragments offer various use cases, such as:","Consistent Content",": Use fragments to maintain consistent content across multiple pages. ","For instance, if you have a table or a tile that appears on multiple pages, you can create a fragment for it and include it in all relevant files. ","This ensures that any updates made to the fragment automatically reflect across the entire documentation.","Reusable Components",": Fragments enable the creation of reusable components or sections. ","You can define a complex or commonly used section once and then include it in multiple pages as needed. ","This approach saves time and effort, as you only need to update the fragment file to propagate changes throughout your documentation.","Modular Documentation",": With fragments, you can break down your documentation into smaller, manageable pieces. ","Each fragment represents a specific topic or section, allowing you to organize and structure your content more efficiently. ","This modular approach simplifies maintenance and makes it easier to navigate and update your documentation.","Usage","Firstly, enable the Fragment Plugin by adding the following to your plugins in ",".","{\n"," modulePath: '@jpmorganchase/mosaic-plugins/FragmentPlugin',\n"," options: {}\n","}","To include a fragment in your content, follow these steps:","Create an MDX file for the fragment you want to reuse. ","Remember to set the sidebar property of your fragment's frontmatter to exclude: true if you don't want the fragment to appear in the vertical navigation menu.","---\n","title: Fragment Title\n","sidebar:\n"," exclude: true\n","---","In the target file where you want to include the fragment, use the remark directive syntax ",".","Markdown Content Example","This is the contents of a fragment located at ",":","---\n","title: Content Fragment\n","sidebar:\n"," exclude: true\n","---\n","\n","#### Fragment Title\n","\n","This is an example fragment of markdown content, being pulled from `../fragments/content-fragment.mdx`.\n","The below code snippet will render the content from the content-fragment.mdx file in your target file:",":fragment{src=\"../fragments/content-fragment.mdx\"}","Example output:",":fragment","Component Example","Here is another example, where the fragment files each contain a "," component.",":fragment{src=\"../fragments/tile-a.mdx\"} :fragment{src=\"../fragments/tile-b.mdx\"}","The above code will render the content from tile-a.mdx and tile-b.mdx files, demonstrated below:",":fragment"," :fragment"]},{"title":"Frontmatter","route":"/mosaic/author/frontmatter","content":["Frontmatter",", also known as page metadata, is a powerful feature that allows easy configuration of a page and Mosaic site components e.g. the sidebar.","Frontmatter is written in yaml syntax and is found at the top of a page between 2 sets of 3 dashes: ",".","Example page yaml","---\n","title: Page Title\n","layout: DetailTechnical\n","sidebar:\n"," priority: 4\n","---\n","\n","// frontmatter is closed and now comes page content\n","# Page Title\n","\n","This is some content.\n","Accessing Frontmatter in content","With the syntax below it is possible to directly reference frontmatter inside content using curly brackets and the "," object.","You can think of "," as a JSON object that holds all the frontmatter of a page and when the Mosaic "," encounters the curly brackets then the value in the frontmatter will be resolved.","{meta.title}\n","{meta.description}\n","{meta.someValueYouHaveAddedToTheFrontmatter}","This is very common to see Mosaic pages that reference the title as shown below:","---\n","title: Title\n","---\n","\n","# {meta.title}","Plugins & Frontmatter","Mosaic plugins can also embed their output into page frontmatter in 2 different ways:","a property is directly added to the page object","a JSON file is generated and referenced using a ","ref","Adding a property to the page","A plugin can add a property to a page simply by extending the page object it receives in the "," lifecycle event:","async function $afterSource(pages) {\n"," for (const page of pages) {\n"," page.newProperty = 'Hello'\n"," }\n"," return pages;\n","}","You could use this property in the page content using ","JSON File","Let's take a look at the ",".","The purpose of this plugin is to crawl the page hierarchy to find the closest "," found in any parent page's frontmatter.","Finds all index pages among the source docs","Deserialises those pages so it can read the frontmatter and content of the page","If a property called "," in the page frontmatter is found a new file named shared-config.json is created","Adds a ref named "," to the shared config file that points to the shared config of the index page","import type { Page, Plugin as PluginType } from '@jpmorganchase/mosaic-types';\n","import { flatten } from 'lodash-es';\n","import path from 'path';\n","\n","function createFileGlob(url, pageExtensions) {\n","if (pageExtensions.length === 1) {\n","return `${url}${pageExtensions[0]}`;\n","}\n","return `${url}{${pageExtensions.join(',')}}`;\n","}\n","\n","interface SharedConfigPluginPage extends Page {\n","sharedConfig?: string;\n","}\n","\n","interface SharedConfigPluginOptions {\n","filename: string;\n","}\n","\n","const SharedConfigPlugin: PluginType = {\n","async $beforeSend(\n"," mutableFilesystem,\n"," { config, serialiser, ignorePages, pageExtensions },\n"," options\n"," ) {\n"," const pagePaths = await mutableFilesystem.promises.glob(\n"," createFileGlob('**/index', pageExtensions),\n"," {\n"," ignore: [options.filename, ...flatten(ignorePages.map(ignore => [ignore, `**/${ignore}`]))],\n","cwd: '/'\n","}\n",");\n","\n"," for (const pagePath of pagePaths) {\n"," const sharedConfigFile = path.join(path.dirname(String(pagePath)), options.filename);\n","\n"," const page = await serialiser.deserialise(\n"," String(pagePath),\n"," await mutableFilesystem.promises.readFile(String(pagePath))\n"," );\n"," if (page.sharedConfig) {\n"," config.setRef(sharedConfigFile, ['config', '$ref'], `${String(pagePath)}#/sharedConfig`);\n"," await mutableFilesystem.promises.writeFile(sharedConfigFile, '{}');\n"," } else {\n"," const baseDir = path.posix.resolve(path.dirname(String(pagePath)), '..","/');\n"," config.setAliases(path.join(baseDir, options.filename), [sharedConfigFile]);\n"," }\n"," }\n","\n","}\n","};\n","\n","export default SharedConfigPlugin;\n"]},{"title":"Author","route":"/mosaic/author/index","content":["Here you will learn how to author documentation using markdown, Mosaic components and page templates"]},{"title":"Markdown Syntax","route":"/mosaic/author/markdown-syntax","content":["Out of the box, Mosaic supports documents written in ","MDX"," which allows React components to be embedded within the ","basic syntax"," outlined in the original Markdown design document.","In addition to the basic markdown syntax, the MDX processor used by Mosaic has been configured to support additional markdown syntax and features:","GitHub flavored markdown (gfm)","Frontmatter","Mosaic Standard Components","All components that comprise the "," export from "," package are available to use out of the box in your documents.","This includes components for all standard markdown syntax and additional components like "," and ",".","Referencing Frontmatter","Frontmatter values can be embedded into the page using the "," object. ","See ","frontmatter"," for more information.","Configuring Supported components","TODO"]},{"title":"Refs","route":"/mosaic/author/refs","content":["Refs are a very powerful feature of Mosaic documents that use ","JSON References"," to reference\n","a property from the page frontmatter or frontmatter of other pages.","The key concept is that of a JSON pointer which takes the form ","A","#","B"," where:","A"," is the relative path from the current schema to a target schema. ","If A is empty, the reference is to a type or property in the same schema, an in-schema reference. ","Otherwise, the reference is to a different schema, a cross-schema reference.","B"," is the complete path from the root of the schema to a type or property in the schema. ","If # in not included or B is empty, the reference is to an entire schema.","To translate this for our purposes:","A"," is the relative path to a file in the filesystem.","B"," is the path to a property in the frontmatter of the file.","It's probably better explained with examples...","Local refs (In-schema reference)","It is possible to reference a page's own frontmatter to avoid duplication:","---\n","title: Refs\n","layout: DetailTechnical\n","sidebar:\n"," priority: 3\n","data:\n"," sidebarPriority:\n"," $ref: '#/sidebar/priority'\n","---","This page you are reading right now has a sidebar priority of ",".","The value of "," comes from "," in the frontmatter.","Notice that because we don't specify a path before the "," in the ref we need to put the whole\n","value inside quotes.","Remote Refs (Cross-schema reference)","It is possible to reference frontmatter of other pages. ","Again this helps avoid duplication but the real power is using refs to build the data model. ","See ","advanced"," for more information.","The ","index"," page of the Author section has this frontmatter:","---\n","title: Author\n","layout: DetailTechnical\n","sidebar:\n"," priority: 3\n","data:\n"," exampleRefData: Hello from Author page\n","---","This page you are currently looking at is referencing the "," in it's frontmatter like this:","---\n","title: Refs\n","layout: DetailTechnical\n","sidebar:\n"," priority: 3\n","data:\n"," authorRef:\n"," $ref: ./#/data/exampleRefData\n","---","I can then use the data and embed it in this page like this:","{meta.data.authorRef}","And here it is: ","Notice that we did not need to put "," in the ref since index pages are resolved\n","automatically.","Advanced","You have had a taste of the power and want to know more? ","OK, lets reference and then list out all the mosaic modes:","The Modes ","index"," page has this frontmatter:","---\n","title: Modes of operation\n","layout: DetailTechnical\n","sidebar:\n"," priority: 4\n","data:\n"," modes:\n"," $ref: ./*#/title\n","---","The ref here is essentially using a wildcard (the *) to grab the "," property from the frontmatter of every page in the modes folder.","We can reference that data just like before:","---\n","title: Refs\n","layout: DetailTechnical\n","sidebar:\n"," priority: 3\n","data:\n"," modes:\n"," $ref: ../configure/modes#/data/modes\n","---","Output","With the code below, the referenced data can be embedded in a page.","
    \n"," {meta.data.modes.map(mode => (\n","
  • {mode}
    • \n"," ))}\n","
","Output with Mosaic Components","You can use Mosaic components with referenced data as well. ","Below we are using the "," and "," components.","\n"," {meta.data.modes.map(mode => (\n"," \n"," ))}\n","","Setting Refs using Plugins","Mosaic plugins can create new refs, create new ","global"," refs and see existing refs created by the page or other plugins. ","This is achieved using a special "," property available in the plugin helpers.","Create new refs","Use the "," function from the helpers provided to plugin lifecycle events. ","You need to provide","The file/fullpath to write the ref to","The path to the ptoperty where the ref will be applied","The value of the ref, which can use wildcards","For example, the following would add a property to pages named ",". ","The value is the title of all pages in the ","same"," directory as the current page"," async $afterSource(pages, { config }) {\n"," for (const page of pages) {\n"," config.setRef(page.fullPath, ['titles', '$ref'], `**#/title`);\n"," }\n"," return pages;\n"," }","When setting the property path the last string must be "," otherwise you're not creating a ref\n","that will be resolved by the RefPlugin.","Existing refs","To view refs that already exist you can use ",". ","For example to see all refs for a page:"," config.data.refs[fullPathToPage]","Create global refs","Global refs are similar to regular refs except they do not pre-resolve. ","This means they are resolved when the referenced file is read and the global mosaic filesystem, made up of multiple sources, is used rather than the filesystem of a single source."]},{"title":"Sidebar Configuration","route":"/mosaic/author/sidebars","content":["Sidebar data is generated by the the ","Sidebar Plugin"," which by default uses alphabetical ordering of page names to order the sidebar.","Sidebar frontmatter","A page can add a "," property to its ","frontmatter"," to change the ordering of a sidebar and what title is used for a page in the sidebar.","To rearrange pages in the sidebar or to apply a different label to a page you can specify the following in the page frontmatter:","Sidebar label","By default the ","title"," of a page is used in the sidebar as the label but this can be changed to another label using page frontmatter.","---\n","title: Sidebar Configuration\n","layout: DetailTechnical\n","sidebar:\n"," label: A New Label\n","---","Sidebar priority","Sidebar priority is a number used to sort the sidebar. ","Higher the priority pages appear first in the sidebar ordering.","---\n","title: Sidebar Configuration\n","layout: DetailTechnical\n","sidebar:\n"," priority: 10\n","---","Sidebar Sort Configuration","Sidebar sort configuration allows the sidebar to be sorted using a more sophisticated approach and only needs to be applied to the "," page of the directory you want to sort.","Priority takes precedence over sort configuration so it can be used to override the sort\n","configuration if required.","You must add the sidebar sort configuration to the "," property of an ","index"," page e.g.,","sharedConfig:\n"," sidebar:\n"," sort:\n"," field: data/title\n"," dataType: string\n"," arrange: desc","The properties of the sort configuration are described in the table below:","| Property | Description | Required |\n","| -------- | ------------------------------------------------------------------------------------------ | -------- |\n","| field | the path, separated by ",", used to find the value in page frontmatter you wish to sort by | Yes |\n","| dataType | is the type of the value. ","Can be a "," or "," or ",". ","| Yes |\n","| arrange | "," or "," order | yes |","Newsletters Example","Let's say you have a ","Newsletters"," directory and each page in the directory represents a newsletter. ","You wish to sort the newsletter sidebar by publication date in descending order (newest first).","One way to do this is to edit each page and add a "," which is manually incremented every time a news newsletter is added. ","Alternatively you can add the following sort configuration to the newsletters index page:","sharedConfig:\n"," sidebar:\n"," sort:\n"," field: data/publicationDate\n"," dataType: date\n"," arrange: desc","This will use the "," property in each newsletter to sort the newsletters in the sidebar. ","The publication date is converted to a "," by the Sidebar Plugin to ensure accurate ordering. ","There is now no need to increment a priority when a new newsletter is added.","Example newsletter page frontmatter:","---\n","title: Newsletter 01 Jan 2023\n","description: Newsletter 01 Jan 2023\n","data:\n"," title:\n"," $ref: '#/title'\n"," link: /newsletters/2023-01-01\n"," publicationDate: '2023-01-01'\n","---"]},{"title":"Tags","route":"/mosaic/author/tags","content":["Tags are very similar to ","Refs"," with one very important distinction: Tags work ","across multiple sources",".","In Mosaic, each source has it's own filesystem which are then merged together to form a union of all source filesystems. ","It is in this union filesystem that tags are applied and not to the individual source filesystem that the tag was defined on.","Tags are slower to apply than refs. ","Multiple sources need to run and update before tagged data\n","will be resolved. ","If possible, stick to refs and only use tags when dealing with multiple sources.","Tagging a page","To tag a page, add a "," property to the page frontmatter. ","For example, the Product A page is tagged with \"in-stock\":","---\n","title: Product A\n","description: Mosaic Product A\n","layout: ProductDiscover\n","tags:\n"," - in-stock\n","data:\n"," name:\n"," $ref: '#/title'\n","---"," is always an array","Subscribing to a tag","To subscribe to a tag, use the "," property. ","For example, the Products page has subscribed to the "," property of pages tagged with ",".","---\n","title: Products\n","data:\n"," in-stock:\n"," $tag: in-stock#/data\n","---","A "," can provide a path to a specific piece of metadata on tagged pages, just like a ref.","Example","This page has subscribed to "," and "," tags and is displaying them using 2 Mosaic "," components.","Both the Product A and Product B pages are part of a different source than this page.","In Stock","Out of Stock"]},{"title":"UI Components","route":"/mosaic/author/ui-components","content":["Todo..."]},{"title":"Configure","route":"/mosaic/configure/index","content":["Mosaic is a tool which retrieves, formats and combines documentation pages from any number of different external sources (such as GitHub repositories, local disks or REST endpoints), into a single filesystem for you to use in your websites."]},{"title":"Content Fragment","route":"/mosaic/fragments/content-fragment","content":["Fragment Title","This is an example fragment of markdown content, being pulled from ","."]},{"title":"Fragments","route":"/mosaic/fragments/index","content":["This folder contains example fragments that are referenced and rendered in the Fragments docs page."]},{"title":"Tile A","route":"/mosaic/fragments/tile-a","content":[]},{"title":"Tile B","route":"/mosaic/fragments/tile-b","content":[]},{"title":"Create a Site","route":"/mosaic/getting-started/create-a-site","content":["In this guide you will learn how to generate and serve a Mosaic site.","Prerequisites","To begin setting up a Mosaic site, you need to have the following software installed:","Yarn v1","Node.js v18 or higher","Step 1: Generate a Mosaic site","Run the following command in your project directory to generate a new Mosaic site:","npx @jpmorganchase/mosaic-create-site create -o my-sample-site","This command creates a new Mosaic site in the my-sample-site directory.","Next, navigate to the site directory:","cd my-sample-site","Step 2: Serve the site","The example site you have generated comes preconfigured with two ","sources",": a remote repository and a local docs folder. ","Sources are used by Mosaic to pull content from disparate locations and merge them into a single virtual filesystem that can be used by a Mosaic site.","Set up Git credentials","If you want the site to read from remote repositories, you need to set up an environment variable to store your Git credentials. ","Follow these steps:","Open a terminal or command prompt.","Replace "," and "," in the following commands with your actual Git username and personal access token.","On Unix:","export MOSAIC_DOCS_CLONE_CREDENTIALS=\":\"","On Windows:","set MOSAIC_DOCS_CLONE_CREDENTIALS=\":\"","This sets the MOSAIC_DOCS_CLONE_CREDENTIALS environment variable with your Git credentials.","Serve command","Now you can serve your Mosaic site by running the following command:","yarn serve","Access your Mosaic site from a browser using the following URLs:","To browse the content from your local source: http://localhost:3000/local","To browse the content from the Mosaic Git repo source: http://localhost:3000/mosaic","That's it! ","Your Mosaic site is now up and running.","Next Steps:","Deploy your Mosaic site to AWS or Vercel for production use.","Create more pages to expand your site's content.","Configure your own sources in the mosaic.config.mjs file to pull content from different locations.","Theme your site"]},{"title":"Getting Started","route":"/mosaic/getting-started/index","content":["Getting Started with Mosaic","Follow our step-by-step guides to quickly create and deploy your first Mosaic site."]},{"title":"Publish a site to AWS","route":"/mosaic/getting-started/publish-site-to-aws","content":["Publish a site to AWS using S3 snapshots.","Step 1: Generate a Mosaic site","If you have already created your Mosaic site, skip ahead to step 2.","> npx @jpmorganchase/mosaic-create-site -o my-sample-site\n","> cd my-sample-site","Step 2: Create a Github repository","> git init\n","> git remote add origin git@github.com:username/my-sample-site.git\n","> git add .\n","> git commit -m \"initial commit\"\n","> git push origin main","Step 3: Generate a snapshot of content","Consider a snapshot as a directory of static content previously pulled from your content sources, which does not update itself.","> yarn gen:snapshot","Step 4: Configure environment for S3","> export MOSAIC_MODE=\"snapshot-s3\"\n","> export MOSAIC_S3_BUCKET=\"\"\n","> export MOSAIC_S3_REGION=\"\"\n","> export MOSAIC_S3_ACCESS_KEY_ID=\"\"\"\n","> export MOSAIC_S3_SECRET_ACCESS_KEY=\"\"\n","> yarn mosaic upload -S ./snapshots/latest","Step 5: Setup AWS","Switch to the ","AWS Amplify"," console and deploy your app as a SSR application by following the ","AWS docs",".","Setup an S3 bucket as per the ","AWS S3 docs",".","Step 7: Configure your AWS app","Add the environment vars to the hosted app via your console","MOSAIC_MODE=\"snapshot-s3\"\n","MOSAIC_S3_BUCKET=\"\"\n","MOSAIC_S3_REGION=\"\"\n","MOSAIC_S3_ACCESS_KEY_ID=\"\"\"\n","MOSAIC_S3_SECRET_ACCESS_KEY=\"\"","Add the following build settings","version: 1\n","frontend:\n"," phases:\n"," preBuild:\n"," commands:\n"," - yarn install\n"," - env | grep -e MOSAIC >> .env.production\n"," build:\n"," commands:\n"," - yarn run build\n"," artifacts:\n"," baseDirectory: .next\n"," files:\n"," - '**/*'\n"," cache:\n"," paths:\n"," - node_modules/**/*","Ensure the Node is set to 16","Step 8: Upload your snapshot","Upload your snapshot to S3 storage.","> yarn mosaic upload -S ./snapshots/latest"]},{"title":"Publish","route":"/mosaic/publish/index","content":["To create your first Mosaic site, we have created a command line generator that scaffolds a ","standard"," site.","A ","standard"," site offers","an out the box, working site, which showcases local and remote content sources","a minimal set of files that can be configured with your own components, themes, layouts, sources and plugins","an update path that enables you to update Mosaic, independently of your own configuration","Create your first site","Install the Mosaic create site script.","> yarn global add @jpmorganchase/mosaic-create-site","Create a directory for your site and run the "," script.","> mkdir mosaic-sample-site\n","> cd mosaic-sample-site\n","> mosaic-create-site -f .","Define the environment variable, which enables us to access your remote repo.","> export MOSAIC_DOCS_CLONE_CREDENTIALS=\"\"","The "," environment variable is composed of your git username and your PAT token.\n","Follow these ","docs"," to see how to create your own PAT token.","Your site is ready to run.","> yarn serve","In your browser load ","Congratulations, you have created your first Mosaic site."]},{"title":"Publish a site to AWS","route":"/mosaic/publish/publish-site-to-aws","content":["A Mosaic site is a ","Next.Js"," app.","To publish a Next.Js App to AWS, deploy your app as a SSR application by following the ","AWS docs",".","Once the basic app has been configured, add the Mosaic specifics.","Add the environment vars to the hosted app via the Amplify console","MOSAIC_MODE=\"snapshot-s3\"\n","MOSAIC_S3_BUCKET=\"\"\n","MOSAIC_S3_REGION=\"\"\n","MOSAIC_S3_ACCESS_KEY_ID=\"\"\"\n","MOSAIC_S3_SECRET_ACCESS_KEY=\"\"","Add the following build settings","version: 1\n","frontend:\n"," phases:\n"," preBuild:\n"," commands:\n"," - yarn install\n"," - env | grep -e MOSAIC >> .env.production\n"," build:\n"," commands:\n"," - yarn run build\n"," artifacts:\n"," baseDirectory: .next\n"," files:\n"," - '**/*'\n"," cache:\n"," paths:\n"," - node_modules/**/*","Ensure the Node is set to 16"]},{"title":"Publish a site to Vercel","route":"/mosaic/publish/publish-site-to-vercel","content":["A Mosaic site is a ","Next.Js"," app.","To publish a Next.Js App to Vercel, refer to the ","Vercel docs",".","Deployment","As the ","vercel platform"," hosts static content you will need to deploy a mosaic snapshot. ","There is no option to run mosaic in ","active mode",".","1. ","Update Config File","Add the following to the mosaic config file used by your site:"," deployment: { mode: 'snapshot-file', platform: 'vercel' }","2. ","Set Environment Variables","Set 2 ","environment variables"," in the vercel dashboard.","| Variable Name | Value |\n","| ------------------- | ----------------- |\n","| MOSAIC_MODE | snapshot-file |\n","| MOSAIC_SNAPSHOT_DIR | snapshots/latest. ","|","3. ","Run Build and Deploy","The "," command used by vercel must run "," followed by ","The "," command is needed to workaround an ","output file tracing"," problem.","Example:","yarn build && yarn deploy","Output File Tracing","Output File Tracing"," is a feature of Next.js that uses static analysis\n","to determine what files are needed to deploy a production version of an application.","Due to the architecture of mosaic, snapshot files can be ignored by this process and therefore excluded from the build artifacts deployed by vercel.","If you are deploying your site to the ","vercel platform"," then the mosaic site has a "," command that will update the nextjs output trace to include the snapshot files."]},{"title":"Test","route":"/mosaic/test/index","content":["Pages for e2e testing."]},{"title":"Admin","route":"/mosaic/configure/admin/index","content":["There are several admin urls exposed by Mosaic that provide an insight into how the filesystem has been configured and a way to remotely manage sources.","Endpoints","| Endpoint | Method | Description | Params |\n","| -------------------------- | ------ | -------------------------------------------- | ---------------------- |\n","| "," | GET | Returns the JSON from the Mosaic config file | n/a |\n","| "," | GET | Returns the entire mosaic filesystem as JSON | n/a |\n","| "," | GET | Returns a collection of active sources | n/a |\n","| "," | POST | Adds the source | definition & isPreview |\n","| "," | PUT | Stops the source with the provided name | name |\n","| "," | PUT | Restarts the source with the provided name | name |"]},{"title":"Detail Highlight","route":"/mosaic/configure/layouts/detail-highlight","content":["Layout: Detail Highlight","Initialize with "," in your page's frontmatter.","This layout is used to promote, share insights, and statistics for a line of business.","This layout should be used for pages with only one level of nesting, therefore, pagination is not eligible for this\n","layout.","Page geometry"]},{"title":"Detail Overview","route":"/mosaic/configure/layouts/detail-overview","content":["Layout: Detail Overview","Initialize with "," in your page's frontmatter.","This layout is used to present an overview of expected documentation, statisitics, and ability to\n","navigate to more documents.","Avoid making this page too long. ","If it gets too long, we recommend the ","Detail Technical"," template.","Page geometry","Other Layouts","Detail Highlight","Detail Technical","Landing","Product Discover","Product Preview","Filler content","Eiusmod veniam adipisicing est magna id sunt occaecat minim adipisicing ad do pariatur id aliqua.\n","Officia officia deserunt consequat ullamco irure. ","Excepteur deserunt esse occaecat ex aute. ","Duis do\n","do in incididunt cupidatat dolore veniam magna aliquip voluptate laborum. ","Non irure magna amet\n","ullamco culpa esse dolore nostrud. ","Id ea id ipsum incididunt do velit aliquip fugiat do non\n","consequat.","A sub heading","Deserunt sunt pariatur mollit dolor eiusmod. ","Anim sunt officia cillum anim. ","Laborum ullamco\n","consectetur elit dolore quis laborum. ","Eiusmod cillum amet veniam sunt Lorem reprehenderit commodo.\n","Cupidatat cillum ea consequat anim. ","Duis voluptate nulla veniam labore quis tempor.","Commodo reprehenderit excepteur amet aliquip cillum veniam ad. ","Ullamco proident deserunt laboris\n","duis laborum consequat laboris est eu enim nulla. ","Mollit velit consectetur ea aliqua consectetur\n","mollit eu ex deserunt. ","Aute excepteur exercitation esse proident excepteur Lorem. ","Quis cillum\n","occaecat sint voluptate incididunt ea ipsum incididunt duis sint magna magna fugiat.","Third-level heading","Ea do magna aute proident nulla cupidatat esse consectetur anim eu esse. ","Consectetur est voluptate\n","excepteur non dolore consequat fugiat deserunt. ","Est nostrud est ea irure reprehenderit commodo\n","nostrud nulla tempor ipsum tempor sit id exercitation. ","Sunt reprehenderit officia anim id quis\n","pariatur velit cillum incididunt officia sunt. ","Ullamco ipsum cillum minim deserunt eiusmod nostrud\n","irure et nulla laborum ipsum ipsum incididunt. ","Voluptate reprehenderit in occaecat ipsum nulla\n","excepteur excepteur mollit laboris id ad laborum do. ","Qui in laborum nostrud quis occaecat proident\n","ipsum tempor laborum consequat id ut velit occaecat.Aliquip quis qui ullamco ipsum exercitation\n","exercitation excepteur ea ex. ","Proident elit incididunt incididunt ad adipisicing quis deserunt sint\n","laboris deserunt ipsum culpa est. ","Id do ex duis Lorem exercitation amet reprehenderit. ","Voluptate qui\n","tempor qui sit minim sit qui ea id dolor excepteur. ","Laborum elit excepteur enim sunt consequat\n","officia cillum. ","Do ea occaecat ut voluptate ea proident duis minim ad pariatur dolore magna enim\n","duis. ","Sit aliqua aliqua ea mollit enim cupidatat proident incididunt. ","Eu dolore sit non incididunt.\n","Mollit reprehenderit sunt sunt cillum labore velit exercitation officia aliqua ea adipisicing do ea.\n","Commodo et fugiat velit dolore consectetur.","Amet dolore deserunt in ut amet officia exercitation sint excepteur voluptate proident tempor enim\n","est. ","Culpa proident tempor in voluptate laboris sunt consectetur sit cillum excepteur culpa enim\n","velit laboris. ","Pariatur elit amet nostrud tempor nostrud ea. ","Exercitation do aliquip nisi amet id.\n","Lorem labore incididunt sit sit veniam tempor do consectetur do culpa qui.","Id sint deserunt laborum mollit id excepteur","mollit excepteur labore labore dolor. ","Sit cupidatat nostrud ad consequat amet excepteur id sunt\n","labore adipisicing non irure. ","Fugiat exercitation laborum officia minim duis dolor do officia Lorem\n","cillum excepteur. ","Sint elit mollit duis sit ad commodo.","Cillum amet irure ut tempor tempor culpa dolore sint.","Lorem qui ipsum reprehenderit est incididunt duis exercitation ea duis fugiat. ","Consectetur enim id\n","sunt exercitation et dolore ea proident sunt excepteur fugiat dolor. ","Veniam proident dolore irure\n","incididunt deserunt pariatur quis. ","Incididunt ea elit deserunt occaecat eiusmod velit fugiat eiusmod\n","dolor eiusmod ullamco. ","Fugiat fugiat eiusmod occaecat nulla consequat pariatur.","Aliquip non cupidatat irure magna et fugiat sunt amet ex est excepteur irure quis. ","Non culpa magna\n","nisi enim eu nulla esse laborum amet ipsum. ","Eu consectetur labore do id occaecat adipisicing."]},{"title":"Detail Technical","route":"/mosaic/configure/layouts/detail-technical","content":["Layout: Detail Technical","Initialize with "," in your page's frontmatter.","This layout is used for longer, technical, detailed content about the product.","This layout shows less marketing-type visuals and more visual of diagrams, screenshots, and code\n","snippets.","This page can be short or very lengthy.","Page geometry","Other Layouts","Detail Highlight","Detail Overview","Landing","Product Discover","Product Preview","Filler content","Eiusmod veniam adipisicing est magna id sunt occaecat minim adipisicing ad do pariatur id aliqua.\n","Officia officia deserunt consequat ullamco irure. ","Excepteur deserunt esse occaecat ex aute. ","Duis do\n","do in incididunt cupidatat dolore veniam magna aliquip voluptate laborum. ","Non irure magna amet\n","ullamco culpa esse dolore nostrud. ","Id ea id ipsum incididunt do velit aliquip fugiat do non\n","consequat.","A sub heading","Deserunt sunt pariatur mollit dolor eiusmod. ","Anim sunt officia cillum anim. ","Laborum ullamco\n","consectetur elit dolore quis laborum. ","Eiusmod cillum amet veniam sunt Lorem reprehenderit commodo.\n","Cupidatat cillum ea consequat anim. ","Duis voluptate nulla veniam labore quis tempor.","Commodo reprehenderit excepteur amet aliquip cillum veniam ad. ","Ullamco proident deserunt laboris\n","duis laborum consequat laboris est eu enim nulla. ","Mollit velit consectetur ea aliqua consectetur\n","mollit eu ex deserunt. ","Aute excepteur exercitation esse proident excepteur Lorem. ","Quis cillum\n","occaecat sint voluptate incididunt ea ipsum incididunt duis sint magna magna fugiat.","Third-level heading","Ea do magna aute proident nulla cupidatat esse consectetur anim eu esse. ","Consectetur est voluptate\n","excepteur non dolore consequat fugiat deserunt. ","Est nostrud est ea irure reprehenderit commodo\n","nostrud nulla tempor ipsum tempor sit id exercitation. ","Sunt reprehenderit officia anim id quis\n","pariatur velit cillum incididunt officia sunt. ","Ullamco ipsum cillum minim deserunt eiusmod nostrud\n","irure et nulla laborum ipsum ipsum incididunt. ","Voluptate reprehenderit in occaecat ipsum nulla\n","excepteur excepteur mollit laboris id ad laborum do. ","Qui in laborum nostrud quis occaecat proident\n","ipsum tempor laborum consequat id ut velit occaecat.Aliquip quis qui ullamco ipsum exercitation\n","exercitation excepteur ea ex. ","Proident elit incididunt incididunt ad adipisicing quis deserunt sint\n","laboris deserunt ipsum culpa est. ","Id do ex duis Lorem exercitation amet reprehenderit. ","Voluptate qui\n","tempor qui sit minim sit qui ea id dolor excepteur. ","Laborum elit excepteur enim sunt consequat\n","officia cillum. ","Do ea occaecat ut voluptate ea proident duis minim ad pariatur dolore magna enim\n","duis. ","Sit aliqua aliqua ea mollit enim cupidatat proident incididunt. ","Eu dolore sit non incididunt.\n","Mollit reprehenderit sunt sunt cillum labore velit exercitation officia aliqua ea adipisicing do ea.\n","Commodo et fugiat velit dolore consectetur.","Amet dolore deserunt in ut amet officia exercitation sint excepteur voluptate proident tempor enim\n","est. ","Culpa proident tempor in voluptate laboris sunt consectetur sit cillum excepteur culpa enim\n","velit laboris. ","Pariatur elit amet nostrud tempor nostrud ea. ","Exercitation do aliquip nisi amet id.\n","Lorem labore incididunt sit sit veniam tempor do consectetur do culpa qui.","Id sint deserunt laborum mollit id excepteur","mollit excepteur labore labore dolor. ","Sit cupidatat nostrud ad consequat amet excepteur id sunt\n","labore adipisicing non irure. ","Fugiat exercitation laborum officia minim duis dolor do officia Lorem\n","cillum excepteur. ","Sint elit mollit duis sit ad commodo.","Cillum amet irure ut tempor tempor culpa dolore sint.","Lorem qui ipsum reprehenderit est incididunt duis exercitation ea duis fugiat. ","Consectetur enim id\n","sunt exercitation et dolore ea proident sunt excepteur fugiat dolor. ","Veniam proident dolore irure\n","incididunt deserunt pariatur quis. ","Incididunt ea elit deserunt occaecat eiusmod velit fugiat eiusmod\n","dolor eiusmod ullamco. ","Fugiat fugiat eiusmod occaecat nulla consequat pariatur.","Aliquip non cupidatat irure magna et fugiat sunt amet ex est excepteur irure quis. ","Non culpa magna\n","nisi enim eu nulla esse laborum amet ipsum. ","Eu consectetur labore do id occaecat adipisicing."]},{"title":"Layouts","route":"/mosaic/configure/layouts/index","content":["Todo..."]},{"title":"Landing Layout","route":"/mosaic/configure/layouts/landing","content":["Layout: Landing","Initialize with "," in your page's frontmatter.","Use this layout as a landing page to show large branded visuals, and high-level content about the\n","line of business.","Set the tone and voice for your LOB’s experience.","Use components that support your content with places to insert visuals, share any stats or an\n","introduction of LOB’s story.","Use heading styles to show the grouping of content of a section.","Page geometry"]},{"title":"Product Discover Layout","route":"/mosaic/configure/layouts/product-discover","content":["Layout: Product Discover","Initialize with "," in your page's frontmatter.","Use this layout to introduce a product feature with a description and large visual.","This layout is use for marketing and discovery content.","Page geometry"]},{"title":"Product Preview Layout","route":"/mosaic/configure/layouts/product-preview","content":["Layout: Product Preview","Initialize with "," in your page's frontmatter.","This layout has been used to introduce a product and showcase their suite of product offerings.","Use heading styles to show the grouping of content of a section.","Page geometry"]},{"title":"Active mode","route":"/mosaic/configure/modes/active","content":["In "," mode content can be ","pulled"," from heterogeneous data sources and normalized via plugins, to the configured components/theme.\n","As your content changes, the site will ","re-pull"," the content and update your site in real-time.","The standard generated site comes with 2 sources to demonstrate, how 'active' mode work.","a local source, which loads content from ","a remote source, which loads content from a ","sample Github repository","Configuring your content sources","All content is composed together within a ","namespace",".","A ","namespace"," is the scope for aggregated content, represented by the root path.\n","e.g Our sample docs are aggregated into a ","namespace"," called "," and served by the user journey ","Mosaic doc sources are defined by a file called ","Here is how that might look for a standard site.","Pull your local content","To tryout local content creation, add a file called","The load ","Each directory should contain an "," which is the default page, when a page is loaded without a path","Now create other pages and subdirectories and explore how Mosaic, builds your user-journeys from your fileset.","Pull your remote content","To tryout remote content creation, your standard site comes pre-configured to load our Mosaic sample docs.","Edit the "," and change your "," and "," to pull content from other repos."]},{"title":"Modes of operation","route":"/mosaic/configure/modes/index","content":["Mosaic can operate in 3 different modes","Active updates","In ","active"," mode, content updates in real-time.","active"," mode content is pulled at configured intervals in real-time, as defined by ",".","Read the ","active"," configuration docs.","Static content","Consider a snapshot as a directory of static content previously pulled from your content sources, which does not update itself.","In a snapshot mode, the snapshot does update itself.","File based snapshots","In "," mode, immutable snapshots of content are loaded at startup from the local file-system.","Read the ","snapshot-file"," configuration docs.","S3 based snapshots","In "," mode, snapshots of content are loaded at startup from a remote S3 bucket.","Read the ","snapshot-s3"," configuration docs."]},{"title":"Snapshot file mode","route":"/mosaic/configure/modes/snapshot-file","content":["In "," mode a local immutable snapshot can be loaded by the site. ","Typically, the snapshot and the site are\n","deployed together and upon startup the site can load the snapshot from the local file-system.","To use "," mode","export MOSAIC_MODE=\"snapshot-file\"\n","export MOSAIC_SNAPSHOT_DIR=\"./snapshot/latest\"","Generating a snapshot","To generate a snapshot, run","yarn gen:snapshot","Commit the snapshot to your Git repo and push the site+snapshot to your Git repo, within the same branch."]},{"title":"Snapshot AWS/S3 mode","route":"/mosaic/configure/modes/snapshot-s3","content":["In "," mode a snapshot can be loaded from a pre-configured AWS S3 bucket.","To use "," mode","> export MOSAIC_MODE=\"snapshot-s3\"\n","> MOSAIC_S3_BUCKET=\"\"\n","> MOSAIC_S3_REGION=\"\"\n","> MOSAIC_S3_ACCESS_KEY_ID=\"\"\n","> MOSAIC_S3_SECRET_ACCESS_KEY=\"\"","Generating a snapshot","To generate a snapshot, run","yarn gen:snapshot","Uploading a snapshot to S3","To upload a snapshot to S3, define the required environment variables and run","yarn mosaic upload -S "]},{"title":"$AliasPlugin","route":"/mosaic/configure/plugins/alias-plugin","content":["The "," is what powers the ","aliases"," feature of Mosaic.","It does this by scrapes "," from page metadata and also applies all aliases stored in ","Other plugins can use "," to apply new aliases, as long as they call it before this plugin has reaches the "," lifecycle event.","This plugin is added to the plugins collection by Mosaic itself so users do ","not"," need to include it in their own mosaic config file.","Priority","This plugin runs with a priority of -1 so it runs ","after"," most other plugins."]},{"title":"BreadcrumbsPlugin","route":"/mosaic/configure/plugins/breadcrumbs-plugin","content":["The "," is responsible for generating the data needed to show breadcrumbs navigation on pages. ","It then appends this data to a "," property in the page metadata.","Should a page already have a "," property in it's metadata then it is respected and not overwritten.","If a page has a "," property in it's metadata then this is used as the label for the breadcrumb, otherwise the page "," is used.","When the "," is traversing up directories, it needs to know what page in the directory represents the ","breadcrumb"," for that directory. ","It is recommended to use the "," page for this but the page to use is a configurable option of the breadcrumbs plugin.","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| ------------- | ------------------------------------------------ |\n","| indexPageName | The page name to use for \"directory\" breadcrumbs |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the breadcrumbs plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/BreadcrumbsPlugin',\n"," options: {\n"," indexPageName: 'index.mdx'\n"," }\n"," }\n"," // other plugins\n","];"]},{"title":"BrokenLinksPlugin","route":"/mosaic/configure/plugins/broken-links-plugin","content":["The "," will identify any broken links in pages Mosaic has pulled into it's filesystem by making use of the ","check-links"," package.","It can identify broken links between the pages themselves and external links that pages link out to.","What this plugin is really checking is \"liveness\" of a link.","alive if the URL is reachable (2XX status code)","dead if the URL is not reachable","invalid if the URL was parsed as invalid or used an unsupported protocol","Links may be \"alive\", but the ","content"," of the linked page may not be what you want so continue\n","to check links show what you expect.","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n","| baseUrl | This is used to calculate the full url for links between pages. ","It should be the url Mosaic is running on |\n","| proxyEndpoint | If you are behind a corporate proxy, external link checking will not work unless you specify the proxy endpoint using this option |","Adding to Mosaic","This plugin is ","not"," included in the mosaic config shipped by the Mosaic standard generator so it must be added manually to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/BrokenLinksPlugin',\n"," priority: -1,\n"," // Exclude this plugin in builds\n"," runTimeOnly: true,\n"," options: {\n"," baseUrl: process.env.MOSAIC_ACTIVE_MODE_URL || 'http://localhost:8080',\n"," proxyEndpoint: 'http://some-proxy-url'\n"," }\n"," }\n"," // other plugins\n","];","This plugin needs to be a "," plugin because it needs Mosaic to be running in order to\n","make requests to all of the page links.","Example Output","When a link is found to be broken, you will see the following output in the console:","@jpmorganchase/mosaic-site:serve: 8080 [Mosaic] Broken links found in /local/docs/publish-site-to-vercel.mdx\n","@jpmorganchase/mosaic-site:serve: 8080 Link to https://nextjs.org/davie is dead {\n","@jpmorganchase/mosaic-site:serve: 8080 type: 'link',\n","@jpmorganchase/mosaic-site:serve: 8080 title: null,\n","@jpmorganchase/mosaic-site:serve: 8080 url: 'https://nextjs.org/davie',\n","@jpmorganchase/mosaic-site:serve: 8080 children: [ { type: 'text', value: 'Next.Js', position: [Object] } ],\n","@jpmorganchase/mosaic-site:serve: 8080 position: {\n","@jpmorganchase/mosaic-site:serve: 8080 start: { line: 4, column: 20, offset: 36 },\n","@jpmorganchase/mosaic-site:serve: 8080 end: { line: 4, column: 55, offset: 71 }\n","@jpmorganchase/mosaic-site:serve: 8080 }\n","@jpmorganchase/mosaic-site:serve: 8080 }"]},{"title":"$CodeModPlugin","route":"/mosaic/configure/plugins/codemod-plugin","content":["Todo"]},{"title":"Plugins","route":"/mosaic/configure/plugins/index","content":["Mosaic Plugins are ","lifecycle-based"," hooks that are called on ","every"," source at different stages. ","You will never need to invoke a lifecycle method directly as their execution is managed by a plugin runner.","Plugins enable Mosaic to have a lightweight and flexible, modular architecture by encapsulating features and functionality as plugins.","Installation","Configuration","Plugins are added to the "," collection of the mosaic config file. ","Like ","sources",", plugins have an options property that can be used to provide plugin specific configuration.","| Property | Description | Required |\n","| --------------- | -------------------------------------------------------------------------- | -------- |\n","| modulePath | The path to the installed plugin module | Yes |\n","| disabled | Exclude this plugin completely. ","Defaults to false | No |\n","| runtimeOnly | Exclude this plugin when generating a snapshot. ","Defaults to false | No |\n","| previewDisabled | Exclude this plugin for \"preview\" sources | No |\n","| allowMultiple | Allow multiple instances of this plugin to run. ","| No |\n","| priority | The importance of this plugin. ","Plugins with the highest priority run first | No |\n","| options | Collection of other configuration values | No |"," plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/PagesWithoutFileExtPlugin',\n"," options: {},\n"," priority: 1\n"," },\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',\n"," options: {}\n"," },\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/ReadingTimePlugin',\n"," options: {}\n"," }\n","],","There is no need to import the plugin module directly. ","As long as the plugin is installed, Mosaic\n","will be able to import it using the built-in plugin loader.","Default Plugins","The following plugins are always included by Mosaic, regardless of whether they are present in the plugins collection of the Mosaic config file:","$TagPlugin","$AliasPlugin","$CodeModPlugin","$RefPlugin","Plugin errors","Should a plugin fail, the failure will ","not"," cause a source to close or for any other plugin to not run.","Instead plugin errors are tracked by Mosaic and can be viewed in the "," property available on each source listed by the list sources ","admin API",".","Plugin errors will be split by lifecycle event and only the lifecycle events used by the loaded plugins used will be shown.","Multiple Instances","By default, Mosaic will only run one instance of a plugin.","It may be the case that you wish to run the same plugin twice with a slightly different config. ","To do this, you must have 2 instances listed in the plugins collection and they ","both"," must set the "," option to ",".","For example, the config below runs the ","SidebarPlugin"," twice:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',\n"," options: { rootDirGlob: 'products/product-a' },\n"," allowMultiple: true\n"," },\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',\n"," options: { rootDirGlob: '*/!(","product-a)/*' },\n"," allowMultiple: true\n"," }\n"," // other plugins\n","];"]},{"title":"LazyPagePlugin","route":"/mosaic/configure/plugins/lazy-page-plugin","content":["The "," attempts to reduce the size of the Mosaic filesystem in memory by moving page metadata and content to disk.","It then adds a hook, so that when a page is requested the data is loaded from disk and combined with what is already in the Mosaic filesystem.","It must be the very last to run so that it can strip off metadata and content after other plugins\n","have finished with them.","Priority","This plugin runs with a priority of -2. ","Needs to be the last to run for biggest impact.","Options","| Property | Description |\n","| -------- | ------------------------------------------------------------------------------ |\n","| cacheDir | The directory to store the cache. ","Defaults to "," |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/LazyPagePlugin',\n"," // This plugin must be the very last to run, so it can strip off metadata and content after the other\n"," // plugins are done with them\n"," priority: -2,\n"," // Exclude this plugin in builds\n"," runTimeOnly: true,\n"," options: {\n"," cacheDir: '.tmp/.pull-docs-last-page-plugin-cache'\n"," }\n"," }\n"," // other plugins\n","];","This plugin needs to be a "," plugin because the goal is to reduce the in-memory\n","filesystem size."]},{"title":"PagesWithoutFileExtPlugin","route":"/mosaic/configure/plugins/pages-wthout-extensions-plugin","content":["The "," plugin creates ","aliases"," without the file extension for every page in the Mosaic filesystem.\n","This allows pages to be retrieved from the filesystem without specifying the extension e.g., ",".","The plugin also modifies the "," metadata property of a page to point to the shorter alias.","Priority","This plugin runs with a priority of 1. ","It must run after the ","$AliasPlugin",".","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/PagesWithoutFileExtPlugin',\n"," options: {},\n"," priority: 1\n"," }\n"," // other plugins\n","];"]},{"title":"PublicAssetsPlugin","route":"/mosaic/configure/plugins/public-assets-plugin","content":["The "," is responsible for finding \"assets\" in the Mosaic filesystem and copying them to another directory.","Typical usecase is for copying "," and "," to the public directory of a Next.js site as these are considered ","static assets"," for Next.js.","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| --------- | ----------------------------------------------------------- |\n","| outputDir | The directory to copy the assets to. ","Defaults to "," |\n","| assets | A collection of filenames to copy to the outputDir |","Adding to Mosaic","This plugin is ","not"," included in the mosaic config shipped by the Mosaic standard generator so it must be added manually to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/PublicAssetsPlugin',\n"," priority: -1,\n"," options: {\n"," outputDir: './public',\n"," assets: ['sitemap.xml', 'search-data.json']\n"," }\n"," }\n"," // other plugins\n","];"]},{"title":"ReadingTimePlugin","route":"/mosaic/configure/plugins/reading-time-plugin","content":["The "," generates an estimation of how long a page written in MDX will take to read and adds the "," property to the metadata of a page.","Priority","This plugin runs with no special priority.","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/ReadingTimePlugin',\n"," options: {}\n"," }\n"," // other plugins\n","];"]},{"title":"$RefPlugin","route":"/mosaic/configure/plugins/ref-plugin","content":["The "," powers the ","refs"," feature of Mosaic.","The plugin scrapes "," properties from page metadata and also applies all refs stored in ",".","Other plugins can use "," to apply new refs, as long as they call it before this plugin has reaches ",".","Priority","This plugin runs with a priority of -1 so it runs ","after"," most other plugins."]},{"title":"SearchIndexPlugin","route":"/mosaic/configure/plugins/search-index-plugin","content":["The "," is responsible for generating the search index and configuration information for ","Fuse.js"," which is the matching engine powering the client-side search functionality of Mosaic sites.","It outputs 3 files:","Full Search Index - ","Condensed Search Index - ","Search Configuration - ","Full Search Index","On a Mosaic site, the full index is fetched after a page has loaded, thus removing the chance of a huge index slowing down first-load.","Practically, the full index should load in the background before a user searches for something, but should a search be initiated before that (e.g., slow-internet) then the condensed version of the search index is available.","Condensed Search Data","Search Index plugin creates a \"condensed\" version of the search index that only includes the "," and "," for each page. ","This is the \"Minimum Viable Index\" to provide somewhat useable search results client-side while the main search index is loaded in the background.","Search Configuration","Any ","options"," that need to be passed to Fuse.js.","Search relevancy configuration","| Property | Description |\n","| ---------------- | ----------------------------------------------------- |\n","| includeScore | https://www.fusejs.io/api/options.html#includescore |\n","| includeMatches | https://www.fusejs.io/api/options.html#includematches |\n","| maxPatternLength | TODO |\n","| ignoreLocation | https://www.fusejs.io/api/options.html#ignorelocation |\n","| threshold | https://www.fusejs.io/api/options.html#threshold |\n","| keys | https://www.fusejs.io/api/options.html#keys |","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| ------------- | --------------------------------------------------- |\n","| maxLineLength | TODO |\n","| maxLineCount | TODO |\n","| keys | https://www.fusejs.io/api/options.html#keys |\n","| relevancy | ","search relevancy"," |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SearchIndexPlugin',\n"," previewDisabled: true,\n"," options: { maxLineLength: 240, maxLineCount: 240 }\n"," }\n"," // other plugins\n","];","It's usually a good idea to mark this plugin as disabled for preview sources otherwise the pages\n","from the preview will appear in search results."]},{"title":"SharedConfigPlugin","route":"/mosaic/configure/plugins/shared-config-plugin","content":["The "," crawls the page hierarchy to find the closest "," metadata from any parent index's page metadata. ","It then exports a JSON file into each directory with the merged config for that level.","Shared config is typically the place where the following is configured for a Mosaic site:","App Header configuration including site name and main navigation","Footer information","Help links for the left sidebar area","Namespace Shared Configs","Consider 2 sources the share the same ","namespace"," \"product-docs\":","Source A - multiple product directories and main product index page. ","The index page specifies "," metadata.","Source B - pages relevant to a single product. ","Index page does ","not"," have any "," metadata.","Let's also assume that the pages from Source B would also naturally \"fit\" within the pages of Source B (e.g. inside a products directory).","In this scenario, the "," will attempt to copy the shared config file from Source A into the root directory of Source B allowing the Source B pages to use the Source A "," as though it were a product sourced directly from Source A.","Priority","This plugin runs with a priority of 3.","Options","| Property | Description |\n","| -------- | ---------------------------------------------- |\n","| filename | the name of the JSON file output by the plugin |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SharedConfigPlugin',\n"," options: {\n"," filename: 'shared-config.json'\n"," },\n"," priority: 3\n"," }\n"," // other plugins\n","];"]},{"title":"SidebarPlugin","route":"/mosaic/configure/plugins/sidebar-plugin","content":["The "," generates the necessary page metadata needed for the vertical navigation shown on some Mosaic pages.","The output from the plugin is added to a "," metadata property of the page.","Configuration","The "," is used to determine the \"root\" directories of the sidebar. ","So for example:"," - generate sidebar data for the pages that are 3 directories deep in the filesystem hierarchy"," - same as above but ignore the product-a directory"," - generate a sidebar just for product-b in the products directory","To rearrange pages in the sidebar or to apply a different label to a page you can ","configure the sidebar"," using page frontmatter.","Priority","This plugin runs with a priority of 3.","Options","| Property | Description |\n","| ----------- | ----------------------------------------------------------------------------- |\n","| filename | filename of the sidebar json, linked to each related page via ref |\n","| rootDirGlob | Glob pattern for matching directories which should be the root of the sidebar |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',\n"," options: { rootDirGlob: '*/*/*' }\n"," }\n"," // other plugins\n","];"]},{"title":"SiteMapPlugin","route":"/mosaic/configure/plugins/site-map-plugin","content":["The "," generates a ","sitemap"," using the pages in the Mosaic filesystem that adheres to the ","sitemaps XML schema",".","The output of the plugin is a file is named ",".","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| -------- | --------------------------------------------------------------------------------------------------- |\n","| siteUrl | The site URL. ","Used as the prefix for loc entries in the sitemap as these must start with a protocol |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SiteMapPlugin',\n"," previewDisabled: true,\n"," options: { siteUrl: process.env.SITE_URL || 'http://localhost:3000' }\n"," }\n"," // other plugins\n","];","Visualiser","To visualise your sitemap you can combine this plugin with the "," component provided by ",".","Rendering the "," component will render a tree view of your sitemap.","","Have a look at this site's pages, ","here","."]},{"title":"$TagPlugin","route":"/mosaic/configure/plugins/tag-plugin","content":["The "," powers the tags feature of Mosaic.","This plugin scrapes "," from page metadata and also applies all aliases stored in ",".","Tags ultimately resolve down into ","refs",", but are different from normal refs, in that they are applied to the\n","union filesystem (all merged filesystems), not to the individual source filesystem that they were defined on. ","This can be thought of as a ","global ref",".","Other plugins can use "," and modify the "," property, to apply new global refs, as long as\n","they do so before this plugin has reaches ",".","Priority","This plugin runs with no special priority but it must run before both the "," and the ",".","Example use case - Products Page","Let's assume there is a products page on your site and each product is shown as a tile. ","The information for each product tile is sourced from multiple Mosaic sources. ","How can tags be used to reference the product data needed for each tile on the products page?","The product page should add a "," metadata prop to its frontmatter:","---\n","title: Products\n","description: Product index\n","layout: ProductPreview\n","data:\n"," items:\n"," $tag: product#/data\n","---","The tag shown in the example above is saying populate "," of the Products index page with the "," metadata property of pages tagged with ",".","A tagged product page needs to have a "," property which is a collection of tags and one of these needs to be ",". ","This will allow the "," to correctly associate the product page to the product index page. ","It will also need a "," property because thats the property our product index page wants to use for the tiles.","---\n","title: Product A\n","description: My Product description\n","layout: ProductDiscover\n","tags:\n"," - product\n","data:\n"," name:\n"," $ref: '#/title'\n"," date: 2023/02/07\n"," action: Product Overview\n"," description:\n"," $ref: '#/description'\n"," link: /products/a/index\n","---","---\n","title: Product B\n","description: My Product description\n","layout: ProductDiscover\n","tags:\n"," - product\n","data:\n"," name:\n"," $ref: '#/title'\n"," date: 2023/02/07\n"," action: Product Overview\n"," description:\n"," $ref: '#/description'\n"," link: /products/b/index\n","---"]},{"title":"TableOfContentsPlugin","route":"/mosaic/configure/plugins/toc-plugin","content":["The "," generates a Table of Contents for each page in the Mosaic filesystem using the headings on the page.","Heading ranks are used to determine which page headings should be included in the Table of Contents:","| Heading Element (markdown syntax) | Rank |\n","| --------------------------------- | ---- |\n","| h1 (#) | 1 |\n","| h2 (##) | 2 |\n","| h3 (###) | 3 |\n","| h4 (####) | 4 |\n","| h5 (#####) | 5 |\n","| h6 (######) | 6 |","The plugin output is added to a "," metadata property of a page.","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| -------- | ----------------------------- |\n","| minRank | The minimum page heading rank |\n","| maxRank | The maximum page heading rank |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/TableOfContentsPlugin',\n"," options: {\n"," minRank: 2,\n"," maxRank: 3\n"," }\n"," }\n"," // other plugins\n","];"]},{"title":"Git Repo Source","route":"/mosaic/configure/sources/git-repo-source","content":["The Git Repo Source is used to pull content from a remote git repository e.g. github.","Installation","Credentials and Access tokens","To successfully clone the git repo, the source definition must include credentials that have sufficient permissions to clone the repository.","We recommend storing a ","personal access token"," in an environment variable and using the environment variable in the source definition.","This keeps credentials out of code where they may be accidentally exposed to third parties.","Example","export MOSAIC_DOCS_CLONE_CREDENTIALS=\":\",","Configuration","| Property | Description | Required |\n","| ------------------- | -------------------------------------------------------------------------------- | -------- |\n","| modulePath | The path to the installed module (@jpmorganchase/mosaic-source-git-repo) | Yes |\n","| namespace | The scope for this source. ","| Yes |\n","| disabled | When true, content from this source is not used | No |\n","| options.credentials | Collection of URLS to make requests | Yes |\n","| options.prefixDir | The root path used in the content URL | Yes |\n","| options.subfolder | The name of the folder within the cloned repo containing the docs | Yes |\n","| options.repo | The repo URL | Yes |\n","| options.branch | The branch or tag to clone | Yes |\n","| options.extensions | Collection of file extensions that the source will look for inside the subfolder | Yes |\n","| options.remote | The name of the git remote to use. ","Defaults to origin. ","| Yes |","Example Git Repo Source Definition","\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-git-repo',\n"," namespace: 'mosaic',\n"," options: {\n"," credentials: process.env.MOSAIC_DOCS_CLONE_CREDENTIALS,\n"," prefixDir: 'mosaic',\n"," subfolder: 'docs',\n"," repo: 'https://github.com/jpmorganchase/mosaic.git',\n"," branch: 'main',\n"," extensions: ['.mdx'],\n"," remote: 'origin'\n"," }\n"," }\n"]},{"title":"HTTP Source","route":"/mosaic/configure/sources/http-source","content":["The HTTP Source is used to pull content over HTTP.","Multiple endpoints can be specified and the source will combine and transform the response from each into a single collection of pages.","Installation","Configuration","| Property | Description | Required |\n","| ------------------------------------------ | ----------------------------------------------------------------------------- | -------- |\n","| modulePath | The path to the installed module (@jpmorganchase/mosaic-source-http) | Yes |\n","| namespace | The scope for this source | Yes |\n","| disabled | When true, content from this source is not used | No |\n","| options.endpoints | Collection of URLS to make requests | Yes |\n","| options.prefixDir | The root path used in the content URL | Yes |\n","| options.transformResponseToPagesModulePath | The path of the module used to transform endpoint responses into Mosaic pages | Yes |\n","| options.checkIntervalMins | Number of minutes to wait between requests. ","Defaults to 5 minutes | No |\n","| options.initialDelayMs | Number of milliseconds to wait for making initial request. ","Defaults to 1000 | No |","Example HTTP Source Definition"," {\n"," modulePath: '@jpmorganchase/mosaic-source-http',\n"," namespace: 'my-namespace',\n"," options: {\n"," prefixDir: 'docs',\n"," endpoints: [\n"," 'https://api.data.com/blah',\n"," 'https://api.data.com/hello'\n"," ],\n"," transformResponseToPagesModulePath: '@scope/transformer-package'\n"," }\n"," }"]},{"title":"Sources","route":"/mosaic/configure/sources/index","content":["Sources are what Mosaic uses to pull content from disparate locations and merge into a single virtual filesystem that can be used by a Mosaic Site.","Depending on the ","mode"," used, sources can update periodically ensuring that new content is made available automatically.","Source Definitions","Source Definitions are specified in the "," collection of a mosaic config file.","Each source uses a ","zod schema"," to validate the provided JSON to ensure that all required information for the source to pull content has been provided.","A source definition at a minimum needs to provide the module path of the source and the ","namespace"," that it will use. ","A namespace is not unique across sources though it is common that each source has a different namespace.","Lastly, the options field can be used as a bucket for configuration values needed to configure the source e.g. credentials.","Users are free to add any property as a source option but please read the ","gotchas","\n","first regarding the allowed ","values",".","Example Local Folder Source Definition"," /**\n"," * Demonstrates a local file-system source, in this case a relative path to where the\n"," * site was generated.\n"," * Access from your browser as http://localhost:3000/local\n"," */\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-local-folder',\n"," namespace: 'local', // each site has it's own namespace, think of this as your content's uid\n"," options: {\n"," rootDir: '..","/../docs', // relative path to content\n"," prefixDir: 'local', // root path used for namespace\n"," extensions: ['.mdx'] // extensions of content which should be pulled\n"," }\n"," }","Source Namespace","A Source Namespace is a scoping mechanism for Mosaic sources used to filter the content loaded by Mosaic. ","By default all sources specified in the mosaic config file are loaded.","sources: [\n"," {\n"," namespace: 'my-namespace',\n"," modulePath: '@jpmorganchase/mosaic-source-local-folder'\n"," }\n","];","The following command will ensure mosaic only loads sources with the "," scope.","yarn mosaic serve -c ''./mosaic.config.mjs' -p 8080 --scope \"local\"","Source Schedules","Source schedules define how often sources pull in content that exists remotely and if a failed source is retried. ","More information can be found ","here","Source Types","Out of the box, Mosaic provides 3 source \"types\":","Local Folder","Git Repo Source","HTTP Source","Sources must expose an observable interface so it is possible to compose sources together e.g. the Git Repo source uses the Local Folder source internally to watch the cloned folder for changes.","Watching for Updates","When running in ","active mode",", Mosaic will watch for any changes to the source content and if a change is detected, will initiate a pull of that new content.","How often to check for updates and how updates are triggered are a matter for the source to handle. ","Mosaic simply responds when a source emits new content.","Source Worker Thread","Sources are executed inside their own worker thread to ensure that the main thread is not overloaded. ","It is here that a local virtual filesystem for the source is created and where several of the ","Plugin Lifecycle"," events are triggered.","Gotchas","A service worker thread uses ","postMessage"," to communicate with the main thread and vice-versa.","This is important because it limits what values can be provided in the source definition to those that can be processed by the ","Structured Clone Algorithm","."]},{"title":"Local Folder Source","route":"/mosaic/configure/sources/local-folder-source","content":["The Local Folder Source is used to pull content from a folder located on the same machine as Mosaic is running.","It is common to use this source when running mosaic locally.","Installation","Configuration","| Property | Description | Required |\n","| ------------------ | ------------------------------------------------------------------------------ | -------- |\n","| modulePath | The path to the installed module (@jpmorganchase/mosaic-source-local-folder) | Yes |\n","| namespace | The scope for this source | Yes |\n","| disabled | When true, content from this source is not used | No |\n","| options.rootDir | The top level directory content will be pulled from | Yes |\n","| options.prefixDir | The root path used in the content URL | Yes |\n","| options.extensions | Collection of file extensions that the source will look for inside the rootDir | Yes |","Example Local Folder Source Definition","{\n"," modulePath: '@jpmorganchase/mosaic-source-local-folder',\n"," namespace: 'local', // each site has it's own namespace, think of this as your content's uid\n"," options: {\n"," rootDir: '..","/../docs', // relative path to content\n"," prefixDir: 'local', // root path used for namespace\n"," extensions: ['.mdx'] // extensions of content which should be pulled\n"," }\n","}","This source will look for content with the \".mdx\" extension in a \"docs\" directory 2 levels up from the Mosaic working directory. ","That content is included in the \"local\" namespace and available from a route that is prefixed with \"local\".","So if you had a file, "," then you would be able to view it at ","."]},{"title":"Source Schedules","route":"/mosaic/configure/sources/schedules","content":["A source schedule defines how often a source initiates a content pull and what to do when there is a failure.","A schedule can be specified for each source in the source definition, but should a source not provide a schedule it will inherit the \"global\" schedule.","Configuration","| Property | Description | Required | Default |\n","| ----------------- | -------------------------------------------------------------------------------------- | -------- | ------- |\n","| checkIntervalMins | The length of time in minutes before triggering a content refresh | Yes | 30 mins |\n","| initialDelayMs | Startup delay for the source. ","| Yes | 1000 ms |\n","| retryEnabled | When true, failures will trigger another content pull | No | true |\n","| retryDelayMins | The interval between retries. ","This will rise exponentially on every failure. ","| No | 5 |\n","| maxRetries | Maximum number of retry attempts | No | 100 |\n","| resetOnSuccess | If true, when a source recovers and emits pages it's retry counter is returned to zero | No | true |","Global Schedule","The global schedule applies to all sources that do ","not"," provide their own schedule. ","It can be configured as a top-level property of the Mosaic config file."," schedule: {\n"," checkIntervalMins: 60,\n"," initialDelayMs: 1000,\n"," retryDelayMins: 15,\n"," maxRetries: 20\n"," }","Example","Given the config file below:"," schedule: {\n"," checkIntervalMins: 30,\n"," initialDelayMs: 1000,\n"," retryDelayMins: 5,\n"," maxRetries: 10\n"," },\n"," sources: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-git-repo',\n"," namespace: 'sourceA',\n"," options: {\n"," credentials: 'credentials',\n"," prefixDir: 'sourceA',\n"," subfolder: 'docs',\n"," repo: 'source-a-repo-url',\n"," branch: 'develop',\n"," extensions: ['.mdx'],\n"," remote: 'origin'\n"," }\n"," },\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-git-repo',\n"," namespace: 'sourceB',\n"," schedule:{\n"," checkIntervalMins: 60,\n"," initialDelayMs: 5000,\n"," retryDelayMins: 30,\n"," maxRetries: 50\n"," }\n"," options: {\n"," credentials: 'credentials',\n"," prefixDir: 'sourceB',\n"," subfolder: 'docs',\n"," repo: 'source-b-repo-url',\n"," branch: 'develop',\n"," extensions: ['.mdx'],\n"," remote: 'origin'\n"," }\n"," }\n"," ]","Source A will inherit the global schedule so it will:","Start after a 1 second delay","Pull content every 30 minutes","Retry a failed content pull after an initial 5 minute delay","Retry 10 times and if still unsuccessful, closing","Source B has its own schedule so it will:","Start after a 5 second delay","Pull content every 60 minutes","Retry a failed content pull after an initial 30 minute delay","Retry 50 times and if still unsuccessful, closing","Retry Strategy","The retry strategy that Mosaic employs is ","Exponential Backoff",". ","This is a common strategy for networking applications that aims to prevent retries from causing more harm than good.","For example, given a source schedule that has a 1 minute retry delay and will retry a maximum of 3 times then the total time spent retrying is 7 minutes:","1 minute delay then 1st retry","2 minute delay then 2nd retry","4 minute delay then 3rd (and final) retry","Total delay: 1 + 2 + 4 = 7 minutes","As you can see, the delay between retries is growing exponentially giving the content source more time to recover after each retry."]},{"title":"Figma Source","route":"/mosaic/configure/sources/source-figma","content":["The Figma source is used to pull individual design patterns from Figma projects.\n","The source subscribes to Figma project groups, then extracts from project files, tagged patterns.","A Figma pattern tag is defined within a Figma project's ",".","For each retrieved/tagged pattern, a page is created in the Mosaic file-system.\n","Additional Mosaic metadata can be added, to each created page, using ","\n","For instance we could add metadata which defines which product owns a particular pattern and then\n","group patterns based on owner.","Installation","Configuration","The Figma source is an "," and shares the same base configuration.\n","The "," prop has a default transformer which creates a page for each matching Story.","| Property | Description | Required |\n","| ---------- | --------------------------------- | -------- |\n","| prefixDir | path to store figma patterns | Yes |\n","| figmaToken | figma access token | Yes |\n","| projects | array of projects to subscribe to | Yes |\n","| endpoints | figma endpoints | Yes |","Each project is configured from the "," array.","| Property | Description | Required |\n","| ------------- | --------------------------------------------- | -------- |\n","| id | numerical id of the subscribed project group | Yes |\n","| meta | metadata to add to each of the projects pages | Yes |\n","| patternPrefix | prefix to add to all pages created | Yes |"," defined the Figma REST API endpoints.","| Property | Description | Required |\n","| ----------------- | --------------------------------------------------------- | -------- |\n","| getProject | url to return a list of projects within the project group | Yes |\n","| getFile | url to return a project file | Yes |\n","| generateThumbnail | url to generate a thumbnail for the shared Figma node | Yes |","Example Figma Source Definition","sources: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-figma',\n"," namespace: 'some-namespace',\n"," options: {\n"," proxyEndpoint: 'http://path/to/optional/proxy',\n"," prefixDir: '/some/path/to/where/you/store/pattern/pages',\n"," figmaToken: process.env.FIGMA_TOKEN,\n"," projects: [{\n"," id: 99999,\n"," patternPrefix: 'yourPrefix',\n"," meta: {\n"," tags: [ 'some-tag'],\n"," data: {\n"," owner: 'some-owner'\n"," }\n"," }\n"," }],\n"," endpoints: {\n"," getFile: 'https://api.figma.com/v1/files/:file_id?","plugin_data=shared',\n"," getProject: 'https://api.figma.com/v1/projects/:project_id/files',\n"," generateThumbnail: 'https://api.figma.com/v1/images/:project_id?","ids=:node_id'\n"," }\n"," }\n"," }\n","]"]},{"title":"Readme Source","route":"/mosaic/configure/sources/source-readme","content":["The Readme source is used to pull individual "," text files from repositories.\n","This is a lighter weight version of a Git repository resource, which just pulls a single file,\n","rather the whole contents of the repo.","For each retrieved readme, a page is created in the Mosaic file-system.\n","Additional Mosaic metadata can be added, to each created page, using ","\n","For instance we could add metadata which defines which product owns a particular "," and then\n","group this page, with others, based on owner.","Installation","Configuration","The Readme source is an "," and shares the same base configuration.","| Property | Description | Required |\n","| ----------- | --------------------- | -------- |\n","| accessToken | request access token | Yes |\n","| prefixDir | path to store pages | Yes |\n","| readme | array of readme files | Yes |","Each readme is configured from the "," array.","| Property | Description | Required |\n","| --------------- | ---------------------------- | -------- |\n","| contentTemplate | template for content of page | No |\n","| name | page name used in route | Yes |\n","| readmeUrl | url of readme | Yes |\n","| meta | metadata for page | Yes |","Example Readme Source Definition"," sources: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-readme',\n"," namespace: 'your-namespace',\n"," schedule: { checkIntervalMins: 0.25, initialDelayMs: 0 },\n"," options: {\n"," prefixDir: '/salt/community-index/readme',\n"," accessToken: 'Bearer your-access-token',\n"," readme: [\n"," {\n"," name: 'your-mosaic-page-name',\n"," readmeUrl: 'https://some/repo/url/readme.md',\n"," contentTemplate: `a template which replaces ::content:: with the content`,\n"," meta: {\n"," layout: 'DetailTechnical',\n"," title: 'Your Page Title',\n"," tags: ['your-tag-if-required'],\n"," description: 'A description for your readme'\n"," }\n"," }]\n"," }\n"," }]"]},{"title":"Storybook Source","route":"/mosaic/configure/sources/source-storybook","content":["The Storybook source is used to pull individual stories from Storybook, based on tags.","The Mosaic source will filter your Storybook's stories, based on "," or ",".","For each matching story, a page is created in the Mosaic file-system.","additional Mosaic tags can be added to each page using ","additional Mosaic metadata can be added to each page using ","This information can be used to create a dynamic index of stories from Storybook.","Installation","Configuration","The Storybook source is an "," and shares the same base configuration.\n","The "," prop has a default transformer which creates a page for each matching Story.","The "," option is an array of Storybook urls that are used as Sources.\n","Each story is matched on "," using the "," Regexp (or by ",").","If specified, "," and "," can be added to any matching pages.","| Property | Description | Required |\n","| --------------- | ---------------------- | -------- |\n","| options.stories | array of story configs | Yes |"," is an array of Storybooks that you want to pull stories from","| Property | Description | Required |\n","| -------------- | ---------------------------------------- | -------- |\n","| storyUrlPrefix | prefix url of the storybook deployment | Yes |\n","| description | description of the storybook stories | Yes |\n","| storiesUrl | url of the storybook's "," | No |\n","| filter | RegExp filter to match on | No |\n","| filterTags | Array of Storybook tags to match on | No |\n","| meta | additional data to add to matching pages | No |","Example Local Folder Source Definition","sources: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-storybook',\n"," namespace: 'salt',\n"," options: {\n"," prefixDir: '/salt/internal/community-index/story-navigation',\n"," stories: [\n"," {\n"," storiesUrl: 'https://storybook.saltdesignsystem.com/stories.json',\n"," storyUrlPrefix: 'https://storybook.saltdesignsystem.com',\n"," description: 'Navigation patterns created in the Salt Labs',\n"," meta: { // can be any additional metadata you want added to the page's meta.data\n"," tags: ['some-tag'],\n"," data: {\n"," owner: 'Salt',\n"," source: 'STORYBOOK'\n"," }\n"," },\n"," filter: /Lab\\/Tabs/ // this is a Regexp that matches on Storybook kind\n"," }\n"," ]\n"," }\n"," }\n","]"]},{"title":"Custom Components","route":"/mosaic/configure/theme/custom-components","content":["Learn how to add your own custom components to your Mosaic site.","Create Components Folder","To start, create a "," folder under "," where you'll store your custom components.","src/\n","└── components/","In this tutorial, we will create a custom "," component.","Create Card Component","Inside the "," folder, create a "," folder, which will contain your React "," component. ","The "," folder should include "," and "," files as shown in the structure below:","├── src/\n","│ ├── components/\n","│ │ └── card/\n","│ │ ├── index.tsx\n","│ │ └── card.module.css","Card Component: index.tsx","Create your "," component within the "," file:","import React from 'react';\n","import styles from './card.module.css';\n","\n","type CardProps = {\n"," title: string;\n"," content: string;\n","};\n","\n","export const Card: React.FC = ({ title, content }) => {\n"," return (\n","
\n","

{title}

\n","

{content}

\n","
\n"," );\n","};","Card Component: card.module.css","Define your component styles in the "," file:",".card {\n"," background-color: #f5f5f5;\n"," border: 1px solid #ccc;\n"," border-radius: 4px;\n"," box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);\n"," padding: 16px;\n"," transition: box-shadow 0.2s ease-in-out;\n","}\n","\n",".card:hover {\n"," box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);\n","}\n","\n",".card h2 {\n"," color: #333;\n"," font-size: 24px;\n"," margin-bottom: 8px;\n","}\n","\n",".card p {\n"," color: #666;\n"," font-size: 16px;\n"," line-height: 1.5;\n","}","In this example, we use a CSS file, but you can use whichever styling approach you prefer, such as ","vanilla extract",".","To export your "," component, create an "," file in the "," folder:","export * from './card';","Your final folder structure should look like this:","├── src/\n","│ ├── components/\n","│ │ ├── card/\n","│ │ │ ├── index.tsx\n","│ │ │ └── card.module.css\n","│ │ ├── index.ts","Import Custom Card Component","To use your custom "," component, import it into your site's "," file. ","Add the following line to your imports:","import * as myComponents from '../components';","Replace this line:","const components = mosaicComponents;","with:","const components = {\n"," ...mosaicComponents,\n"," ...myComponents\n","};","This will add your custom components to the site, and any custom components in "," will override the corresponding ones in ",". ","The spread operator (",") merges both "," and "," objects, giving priority to "," when there is a naming conflict.","Use Your Custom Card Component","Now you're ready to use your custom "," component. ","Build and run your site, and add the "," component to an MDX file in your "," folder or another source:","","You can create and add more custom components to your Mosaic site by following the same process."]},{"title":"Custom CSS","route":"/mosaic/configure/theme/custom-css","content":["You can customize the look and feel of your Mosaic site by creating cusotm CSS files. ","Here is a step-by-step guide to help you create your own CSS theme.","Create a CSS folder","To get started, create a folder named \"css\" in the \"src\" folder of your Mosaic project.","src/\n","└── css/","Create your theme","Inside the \"css\" folder, create a folder named \"global\". ","This is where you will add your custom styles.","src/\n","└── css/\n"," ├── global/\n"," ├── index.css","Create an \"index.css\" file inside the \"css\" folder. ","This file will import your custom styles.","@import './global/';","Inside your global folder, create a separate CSS file for each part of your site that you want to customize. ","For instance, if you want to change the text styling, create a \"text.css\" file inside the \"global\" folder. ","Here is an example of how your \"text.css\" file could look like:","h1 {\n"," /* Set custom font size and weight */\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h2 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h3 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h4 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h5 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h6 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","p {\n"," font-size: /* insert value */ ;\n"," line-height: /* insert value */ ;\n","}","You can add as many CSS files as you need, depending on how much you want to customize your site.","Create an \"index.css\" file inside the \"global\" folder. ","This file will import your custom styles, in this example we are importing our \"text.css\" file.","@import './text.css';","Your \"css\" folder should now look like this:","src/\n","└── css/\n"," ├── global/\n"," │ ├── text.css\n"," │ ├── index.css\n"," ├── index.css","Import your custom CSS into your site","To apply your custom styles to your Mosaic site, open your \"_app.tsx\" file and add the following line to the bottom of your imports:","import '../css/index.css';","Congratulations! ","You have successfully applied your custom CSS styles to your site. ","This example demonstrated how to create text styles, but you can use the same approach to customize other aspects of your site as well."]},{"title":"Theming Your Site","route":"/mosaic/configure/theme/index","content":["Create a unique look and feel for your Mosaic site by customizing the CSS theme and integrating your own UI components.","Customize the CSS","Adapt various design elements of your Mosaic site to create a cohesive visual theme. ","Refer to our guide to learn more about crafting a custom CSS theme:","CSS Theme Guide","Import Custom Components","Incorporate your own UI components, to tailor the look and functionality of your content. ","This tutorial will walk you through the process of adding custom components to your site:","Adding Custom Components Tutorial"]},{"title":"Aliases Test","route":"/mosaic/test/aliases/index","content":["This page is the alias test page."]},{"title":"Detail Highlight Test Page","route":"/mosaic/test/layouts/detail-highlight","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Detail Overview Test Page","route":"/mosaic/test/layouts/detail-overview","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Detail Technical Test Page","route":"/mosaic/test/layouts/detail-technical","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Edit Layout","route":"/mosaic/test/layouts/edit","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Full Width Layout","route":"/mosaic/test/layouts/full-width","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Layouts","route":"/mosaic/test/layouts/index","content":["Pages for e2e testing of layouts."]},{"title":"Landing Layout Test Page","route":"/mosaic/test/layouts/landing","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Newsletter Test Page","route":"/mosaic/test/layouts/newsletter","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Product Discover Test Page","route":"/mosaic/test/layouts/product-discover","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Product Preview Test Page","route":"/mosaic/test/layouts/product-preview","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Refs Data","route":"/mosaic/test/refs/data","content":[]},{"title":"Refs Test","route":"/mosaic/test/refs/index","content":["The sidebar priority is ",".","The other page data is ","."]},{"title":"Tags Test","route":"/mosaic/test/tags/index","content":["In Stock","Out of Stock"]},{"title":"$afterSource","route":"/mosaic/configure/plugins/lifecycle/after-source","content":["The first lifecycle event to trigger after receiving pages from a source and runs in a child process.\n","The pages can safely be mutated and will be reflected in the final filesystem that gets generated.\n","It ","must"," return a collection of pages.","The "," lifecycle event is called with:","pages - the collection of pages emitted by the source","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | A mutable object for sharing data with other lifecycle phases of all plugins for this source (including in the main thread) in this plugin |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |","Example - Log out all page routes","async function $afterSource(pages, { config, ignorePages, pageExtensions }) {\n"," for (const page of pages) {\n"," console.log(page.route);\n"," }\n"," return pages;\n","}"]},{"title":"afterUpdate","route":"/mosaic/configure/plugins/lifecycle/after-update","content":["The third lifecycle event to trigger overall and the first to trigger inside the main Mosaic process.","Calls after the filesystem and symlinks have been reconstructed due to a change to the current source pages. ","Pages will ","not"," be cached when read at this stage, to allow for reading content and writing a new copy of it without the cached version taking effect.\n","This method is safe to use with lazy loading, as the filesystem should return the full page when read.","The "," lifecycle event is called with:","mutableFilesystem - Mutable filesystem instance with all of this source's pages inside (and symlinks re-applied)","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin. ","Shared only with this source. ","|\n","| globalConfig | An immutable object for reading data from other lifecycle phases of all plugins. ","Shared across all sources. ","|\n","| sharedFilesystem | Mutable filesystem instance independent of any sources. ","Useful for global pages, like sitemaps |\n","| globalFilesystem | Immutable union filesystem instance with all source's pages (and symlinks applied) |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |"]},{"title":"$beforeSend","route":"/mosaic/configure/plugins/lifecycle/before-send","content":["The second lifecycle event to trigger and does so after a filesystem has been built up from the source pages.","It is the last lifecycle event to run in a source child process before the filesystem is sent to the main Mosaic process and should ","not"," return a value.","The "," lifecycle event is called with:","mutableFilesystem - Mutable virtual filesystem instance with all of this source's pages inside (and symlinks applied)","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | A mutable object for sharing data with other lifecycle phases of all plugins for this source (including in the main thread) in this plugin |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |"]},{"title":"Lifecycle Events","route":"/mosaic/configure/plugins/lifecycle/index","content":["Plugin lifecycle","The plugin lifecycle is triggered when a source emits content.","Each Mosaic source has its own worker thread and plugin lifecycle events that start with a "," will execute inside the worker thread.\n","All other lifecycle events will execute in the main Mosaic process.","The 5 lifecycle events are:","$afterSource","$beforeSend","afterUpdate","shouldClearCache","shouldUpdateNamespaceSources","Plugin methods that trigger inside the main thread should be asynchronous and highly optimised to\n","avoid holding up the main thread."]},{"title":"shouldClearCache","route":"/mosaic/configure/plugins/lifecycle/should-clear-cache","content":["The fourth lifecycle event to trigger overall and the second to trigger inside the main Mosaic process.","It is called every time ","any"," source emits new pages and should return a boolean to indicate if ","other"," sources should clear their cache in response to the source updating.","Only sources that have already run "," will call this lifecycle hook since there is no\n","cache to clear if they haven't reached that stage in the lifecycle.","The "," lifecycle event is called with:","updatedSourceFilesystem - Immutable filesystem for the source that changed i.e, not the source filesystem","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin. ","Shared only with this source. ","|\n","| globalFilesystem | Immutable union filesystem instance with all source's pages (and symlinks applied) |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |"]},{"title":"shouldUpdateNamespaceSources","route":"/mosaic/configure/plugins/lifecycle/should-update-namespace-sources","content":["The fifth lifecycle event to trigger overall and the third to trigger inside the main Mosaic process.","It is called every time ","any"," source emits new pages and should return a boolean to indicate if ","other sources that share the same ","source namespace"," should re-run ",".","The "," lifecycle event is called with:","updatedSourceFilesystem - Immutable filesystem for the source that changed i.e, not the source filesystem","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin. ","Shared only with this source. ","|\n","| globalFilesystem | Immutable union filesystem instance with all source's pages (and symlinks applied) |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |"]},{"title":"Product A","route":"/mosaic/products/producta","content":[]},{"title":"Product B","route":"/mosaic/products/productb","content":[]}] \ No newline at end of file +[{"title":"Mosaic","route":"/mosaic/index","content":["True to its name, Mosaic brings together several concepts—including content, design and technical infrastructure—to deliver a unified website experience that is truly greater than the sum of its individual parts.","With Mosaic, you can:","Don't move your content where it does not belong. ","Compose content from remote data sources which\n","are pulled at runtime by our content aggregator.","Visualize your content with your own theme, layouts and components or use the Mosaic Design\n","language.","Extend the existing code and add your own content source types through our simple plugin\n","architecture.","Publish your content through Server Side Rendering (SSR) or generate a snapshot of your content\n","and serve it as a Statically Generated Site (SGS).","Creating a website has never been so easy!"]},{"title":"Sitemap","route":"/mosaic/sitemap","content":["Sitemap"]},{"title":"Aliases","route":"/mosaic/author/aliases","content":["Aliases are virtual 'symlinks' of pages, allowing one page to take on one or more other routes.\n","This is not the same as copying the page, it is a primitive filesystem link which is resolved by Mosaic.","Use Cases","Aliases are great for linking to an old route if you've moved a page to a new place.\n","They can also be used to create short hand links to pages or to 'clone' a copy of a page into\n","another section of the site where it may be relevant.","Example","This is the frontmatter for this page:","---\n","title: Aliases\n","layout: DetailTechnical\n","aliases:\n"," - /mosaic/example/aliases\n","---","Try accessing this page from ","/mosaic/example/aliases"]},{"title":"Fragments","route":"/mosaic/author/fragments","content":["Fragments, also known as content fragments, are powerful tools that allow you to incorporate content from other pages into your documentation. ","By creating an MDX file and using the ","generic directives"," syntax ",", you can easily render the fragment in another file, providing modularity and reusability to your content.","Use Cases","Fragments offer various use cases, such as:","Consistent Content",": Use fragments to maintain consistent content across multiple pages. ","For instance, if you have a table or a tile that appears on multiple pages, you can create a fragment for it and include it in all relevant files. ","This ensures that any updates made to the fragment automatically reflect across the entire documentation.","Reusable Components",": Fragments enable the creation of reusable components or sections. ","You can define a complex or commonly used section once and then include it in multiple pages as needed. ","This approach saves time and effort, as you only need to update the fragment file to propagate changes throughout your documentation.","Modular Documentation",": With fragments, you can break down your documentation into smaller, manageable pieces. ","Each fragment represents a specific topic or section, allowing you to organize and structure your content more efficiently. ","This modular approach simplifies maintenance and makes it easier to navigate and update your documentation.","Usage","Firstly, enable the Fragment Plugin by adding the following to your plugins in ",".","{\n"," modulePath: '@jpmorganchase/mosaic-plugins/FragmentPlugin',\n"," options: {}\n","}","To include a fragment in your content, follow these steps:","Create an MDX file for the fragment you want to reuse. ","Remember to set the sidebar property of your fragment's frontmatter to exclude: true if you don't want the fragment to appear in the vertical navigation menu.","---\n","title: Fragment Title\n","sidebar:\n"," exclude: true\n","---","In the target file where you want to include the fragment, use the remark directive syntax ",".","Markdown Content Example","This is the contents of a fragment located at ",":","---\n","title: Content Fragment\n","sidebar:\n"," exclude: true\n","---\n","\n","#### Fragment Title\n","\n","This is an example fragment of markdown content, being pulled from `../fragments/content-fragment.mdx`.\n","The below code snippet will render the content from the content-fragment.mdx file in your target file:",":fragment{src=\"../fragments/content-fragment.mdx\"}","Example output:","Fragment Title","This is an example fragment of markdown content, being pulled from ",".","Component Example","Here is another example, where the fragment files each contain a "," component.",":fragment{src=\"../fragments/tile-a.mdx\"} :fragment{src=\"../fragments/tile-b.mdx\"}","The above code will render the content from tile-a.mdx and tile-b.mdx files, demonstrated below:"," "]},{"title":"Frontmatter","route":"/mosaic/author/frontmatter","content":["Frontmatter",", also known as page metadata, is a powerful feature that allows easy configuration of a page and Mosaic site components e.g. the sidebar.","Frontmatter is written in yaml syntax and is found at the top of a page between 2 sets of 3 dashes: ",".","Example page yaml","---\n","title: Page Title\n","layout: DetailTechnical\n","sidebar:\n"," priority: 4\n","---\n","\n","// frontmatter is closed and now comes page content\n","# Page Title\n","\n","This is some content.\n","Accessing Frontmatter in content","With the syntax below it is possible to directly reference frontmatter inside content using curly brackets and the "," object.","You can think of "," as a JSON object that holds all the frontmatter of a page and when the Mosaic "," encounters the curly brackets then the value in the frontmatter will be resolved.","{meta.title}\n","{meta.description}\n","{meta.someValueYouHaveAddedToTheFrontmatter}","This is very common to see Mosaic pages that reference the title as shown below:","---\n","title: Title\n","---\n","\n","# {meta.title}","Plugins & Frontmatter","Mosaic plugins can also embed their output into page frontmatter in 2 different ways:","a property is directly added to the page object","a JSON file is generated and referenced using a ","ref","Adding a property to the page","A plugin can add a property to a page simply by extending the page object it receives in the "," lifecycle event:","async function $afterSource(pages) {\n"," for (const page of pages) {\n"," page.newProperty = 'Hello'\n"," }\n"," return pages;\n","}","You could use this property in the page content using ","JSON File","Let's take a look at the ",".","The purpose of this plugin is to crawl the page hierarchy to find the closest "," found in any parent page's frontmatter.","Finds all index pages among the source docs","Deserialises those pages so it can read the frontmatter and content of the page","If a property called "," in the page frontmatter is found a new file named shared-config.json is created","Adds a ref named "," to the shared config file that points to the shared config of the index page","import type { Page, Plugin as PluginType } from '@jpmorganchase/mosaic-types';\n","import { flatten } from 'lodash-es';\n","import path from 'path';\n","\n","function createFileGlob(url, pageExtensions) {\n","if (pageExtensions.length === 1) {\n","return `${url}${pageExtensions[0]}`;\n","}\n","return `${url}{${pageExtensions.join(',')}}`;\n","}\n","\n","interface SharedConfigPluginPage extends Page {\n","sharedConfig?: string;\n","}\n","\n","interface SharedConfigPluginOptions {\n","filename: string;\n","}\n","\n","const SharedConfigPlugin: PluginType = {\n","async $beforeSend(\n"," mutableFilesystem,\n"," { config, serialiser, ignorePages, pageExtensions },\n"," options\n"," ) {\n"," const pagePaths = await mutableFilesystem.promises.glob(\n"," createFileGlob('**/index', pageExtensions),\n"," {\n"," ignore: [options.filename, ...flatten(ignorePages.map(ignore => [ignore, `**/${ignore}`]))],\n","cwd: '/'\n","}\n",");\n","\n"," for (const pagePath of pagePaths) {\n"," const sharedConfigFile = path.join(path.dirname(String(pagePath)), options.filename);\n","\n"," const page = await serialiser.deserialise(\n"," String(pagePath),\n"," await mutableFilesystem.promises.readFile(String(pagePath))\n"," );\n"," if (page.sharedConfig) {\n"," config.setRef(sharedConfigFile, ['config', '$ref'], `${String(pagePath)}#/sharedConfig`);\n"," await mutableFilesystem.promises.writeFile(sharedConfigFile, '{}');\n"," } else {\n"," const baseDir = path.posix.resolve(path.dirname(String(pagePath)), '..","/');\n"," config.setAliases(path.join(baseDir, options.filename), [sharedConfigFile]);\n"," }\n"," }\n","\n","}\n","};\n","\n","export default SharedConfigPlugin;\n"]},{"title":"Author","route":"/mosaic/author/index","content":["Here you will learn how to author documentation using markdown, Mosaic components and page templates"]},{"title":"Markdown Syntax","route":"/mosaic/author/markdown-syntax","content":["Out of the box, Mosaic supports documents written in ","MDX"," which allows React components to be embedded within the ","basic syntax"," outlined in the original Markdown design document.","In addition to the basic markdown syntax, the MDX processor used by Mosaic has been configured to support additional markdown syntax and features:","GitHub flavored markdown (gfm)","Frontmatter","Mosaic Standard Components","All components that comprise the "," export from "," package are available to use out of the box in your documents.","This includes components for all standard markdown syntax and additional components like "," and ",".","Referencing Frontmatter","Frontmatter values can be embedded into the page using the "," object. ","See ","frontmatter"," for more information.","Configuring Supported components","TODO"]},{"title":"Refs","route":"/mosaic/author/refs","content":["Refs are a very powerful feature of Mosaic documents that use ","JSON References"," to reference\n","a property from the page frontmatter or frontmatter of other pages.","The key concept is that of a JSON pointer which takes the form ","A","#","B"," where:","A"," is the relative path from the current schema to a target schema. ","If A is empty, the reference is to a type or property in the same schema, an in-schema reference. ","Otherwise, the reference is to a different schema, a cross-schema reference.","B"," is the complete path from the root of the schema to a type or property in the schema. ","If # in not included or B is empty, the reference is to an entire schema.","To translate this for our purposes:","A"," is the relative path to a file in the filesystem.","B"," is the path to a property in the frontmatter of the file.","It's probably better explained with examples...","Local refs (In-schema reference)","It is possible to reference a page's own frontmatter to avoid duplication:","---\n","title: Refs\n","layout: DetailTechnical\n","sidebar:\n"," priority: 3\n","data:\n"," sidebarPriority:\n"," $ref: '#/sidebar/priority'\n","---","This page you are reading right now has a sidebar priority of ",".","The value of "," comes from "," in the frontmatter.","Notice that because we don't specify a path before the "," in the ref we need to put the whole\n","value inside quotes.","Remote Refs (Cross-schema reference)","It is possible to reference frontmatter of other pages. ","Again this helps avoid duplication but the real power is using refs to build the data model. ","See ","advanced"," for more information.","The ","index"," page of the Author section has this frontmatter:","---\n","title: Author\n","layout: DetailTechnical\n","sidebar:\n"," priority: 3\n","data:\n"," exampleRefData: Hello from Author page\n","---","This page you are currently looking at is referencing the "," in it's frontmatter like this:","---\n","title: Refs\n","layout: DetailTechnical\n","sidebar:\n"," priority: 3\n","data:\n"," authorRef:\n"," $ref: ./#/data/exampleRefData\n","---","I can then use the data and embed it in this page like this:","{meta.data.authorRef}","And here it is: ","Notice that we did not need to put "," in the ref since index pages are resolved\n","automatically.","Advanced","You have had a taste of the power and want to know more? ","OK, lets reference and then list out all the mosaic modes:","The Modes ","index"," page has this frontmatter:","---\n","title: Modes of operation\n","layout: DetailTechnical\n","sidebar:\n"," priority: 4\n","data:\n"," modes:\n"," $ref: ./*#/title\n","---","The ref here is essentially using a wildcard (the *) to grab the "," property from the frontmatter of every page in the modes folder.","We can reference that data just like before:","---\n","title: Refs\n","layout: DetailTechnical\n","sidebar:\n"," priority: 3\n","data:\n"," modes:\n"," $ref: ../configure/modes#/data/modes\n","---","Output","With the code below, the referenced data can be embedded in a page.","
    \n"," {meta.data.modes.map(mode => (\n","
  • {mode}
    • \n"," ))}\n","
","Output with Mosaic Components","You can use Mosaic components with referenced data as well. ","Below we are using the "," and "," components.","\n"," {meta.data.modes.map(mode => (\n"," \n"," ))}\n","","Setting Refs using Plugins","Mosaic plugins can create new refs, create new ","global"," refs and see existing refs created by the page or other plugins. ","This is achieved using a special "," property available in the plugin helpers.","Create new refs","Use the "," function from the helpers provided to plugin lifecycle events. ","You need to provide","The file/fullpath to write the ref to","The path to the ptoperty where the ref will be applied","The value of the ref, which can use wildcards","For example, the following would add a property to pages named ",". ","The value is the title of all pages in the ","same"," directory as the current page"," async $afterSource(pages, { config }) {\n"," for (const page of pages) {\n"," config.setRef(page.fullPath, ['titles', '$ref'], `**#/title`);\n"," }\n"," return pages;\n"," }","When setting the property path the last string must be "," otherwise you're not creating a ref\n","that will be resolved by the RefPlugin.","Existing refs","To view refs that already exist you can use ",". ","For example to see all refs for a page:"," config.data.refs[fullPathToPage]","Create global refs","Global refs are similar to regular refs except they do not pre-resolve. ","This means they are resolved when the referenced file is read and the global mosaic filesystem, made up of multiple sources, is used rather than the filesystem of a single source."]},{"title":"Sidebar Configuration","route":"/mosaic/author/sidebars","content":["Sidebar data is generated by the the ","Sidebar Plugin"," which by default uses alphabetical ordering of page names to order the sidebar.","Sidebar frontmatter","A page can add a "," property to its ","frontmatter"," to change the ordering of a sidebar and what title is used for a page in the sidebar.","To rearrange pages in the sidebar or to apply a different label to a page you can specify the following in the page frontmatter:","Sidebar group label","A sidebar group when expanded will reveal the pages contained within the group.\n","Each group has a default page, ",", which is the default for the group and any breadcrumb link.","The"," can define a "," which defines the name of the sidebar group.\n","If no ","groupLabel"," is defined, sidebar group labels will be defined by either ","label"," or ","title",".","To specify the label of the default page, refer to [Sidebar label](.","/Sidebar label)","---\n","title: Sidebar Configuration\n","layout: DetailTechnical\n","sidebar:\n"," groupLabel: Group label\n","---","Sidebar label","By default the ","title"," of a page is used in the sidebar as the label but this can be changed to another label using page frontmatter.","---\n","title: Sidebar Configuration\n","layout: DetailTechnical\n","sidebar:\n"," label: A New Label\n","---","Sidebar priority","Sidebar priority is a number used to sort the sidebar. ","Higher the priority pages appear first in the sidebar ordering.","---\n","title: Sidebar Configuration\n","layout: DetailTechnical\n","sidebar:\n"," priority: 10\n","---","Sidebar Sort Configuration","Sidebar sort configuration allows the sidebar to be sorted using a more sophisticated approach and only needs to be applied to the "," page of the directory you want to sort.","Priority takes precedence over sort configuration so it can be used to override the sort\n","configuration if required.","You must add the sidebar sort configuration to the "," property of an ","index"," page e.g.,","sharedConfig:\n"," sidebar:\n"," sort:\n"," field: data/title\n"," dataType: string\n"," arrange: desc","The properties of the sort configuration are described in the table below:","| Property | Description | Required |\n","| -------- | ------------------------------------------------------------------------------------------ | -------- |\n","| field | the path, separated by ",", used to find the value in page frontmatter you wish to sort by | Yes |\n","| dataType | is the type of the value. ","Can be a "," or "," or ",". ","| Yes |\n","| arrange | "," or "," order | yes |","Newsletters Example","Let's say you have a ","Newsletters"," directory and each page in the directory represents a newsletter. ","You wish to sort the newsletter sidebar by publication date in descending order (newest first).","One way to do this is to edit each page and add a "," which is manually incremented every time a news newsletter is added. ","Alternatively you can add the following sort configuration to the newsletters index page:","sharedConfig:\n"," sidebar:\n"," sort:\n"," field: data/publicationDate\n"," dataType: date\n"," arrange: desc","This will use the "," property in each newsletter to sort the newsletters in the sidebar. ","The publication date is converted to a "," by the Sidebar Plugin to ensure accurate ordering. ","There is now no need to increment a priority when a new newsletter is added.","Example newsletter page frontmatter:","---\n","title: Newsletter 01 Jan 2023\n","description: Newsletter 01 Jan 2023\n","data:\n"," title:\n"," $ref: '#/title'\n"," link: /newsletters/2023-01-01\n"," publicationDate: '2023-01-01'\n","---"]},{"title":"Tags","route":"/mosaic/author/tags","content":["Tags are very similar to ","Refs"," with one very important distinction: Tags work ","across multiple sources",".","In Mosaic, each source has it's own filesystem which are then merged together to form a union of all source filesystems. ","It is in this union filesystem that tags are applied and not to the individual source filesystem that the tag was defined on.","Tags are slower to apply than refs. ","Multiple sources need to run and update before tagged data\n","will be resolved. ","If possible, stick to refs and only use tags when dealing with multiple sources.","Tagging a page","To tag a page, add a "," property to the page frontmatter. ","For example, the Product A page is tagged with \"in-stock\":","---\n","title: Product A\n","description: Mosaic Product A\n","layout: ProductDiscover\n","tags:\n"," - in-stock\n","data:\n"," name:\n"," $ref: '#/title'\n","---"," is always an array","Subscribing to a tag","To subscribe to a tag, use the "," property. ","For example, the Products page has subscribed to the "," property of pages tagged with ",".","---\n","title: Products\n","data:\n"," in-stock:\n"," $tag: in-stock#/data\n","---","A "," can provide a path to a specific piece of metadata on tagged pages, just like a ref.","Example","This page has subscribed to "," and "," tags and is displaying them using 2 Mosaic "," components.","Both the Product A and Product B pages are part of a different source than this page.","In Stock","Out of Stock"]},{"title":"UI Components","route":"/mosaic/author/ui-components","content":["Todo..."]},{"title":"Configure","route":"/mosaic/configure/index","content":["Mosaic is a tool which retrieves, formats and combines documentation pages from any number of different external sources (such as GitHub repositories, local disks or REST endpoints), into a single filesystem for you to use in your websites."]},{"title":"Content Fragment","route":"/mosaic/fragments/content-fragment","content":["Fragment Title","This is an example fragment of markdown content, being pulled from ","."]},{"title":"Fragments","route":"/mosaic/fragments/index","content":["This folder contains example fragments that are referenced and rendered in the Fragments docs page."]},{"title":"Tile A","route":"/mosaic/fragments/tile-a","content":[]},{"title":"Tile B","route":"/mosaic/fragments/tile-b","content":[]},{"title":"Create a Site","route":"/mosaic/getting-started/create-a-site","content":["In this guide you will learn how to generate and serve a Mosaic site.","Prerequisites","To begin setting up a Mosaic site, you need to have the following software installed:","Yarn v1","Node.js v18 or higher","Step 1: Generate a Mosaic site","Run the following command in your project directory to generate a new Mosaic site:","npx @jpmorganchase/mosaic-create-site create -o my-sample-site","This command creates a new Mosaic site in the my-sample-site directory.","Next, navigate to the site directory:","cd my-sample-site","Step 2: Serve the site","The example site you have generated comes preconfigured with two ","sources",": a remote repository and a local docs folder. ","Sources are used by Mosaic to pull content from disparate locations and merge them into a single virtual filesystem that can be used by a Mosaic site.","Set up Git credentials","If you want the site to read from remote repositories, you need to set up an environment variable to store your Git credentials. ","Follow these steps:","Open a terminal or command prompt.","Replace "," and "," in the following commands with your actual Git username and personal access token.","On Unix:","export MOSAIC_DOCS_CLONE_CREDENTIALS=\":\"","On Windows:","set MOSAIC_DOCS_CLONE_CREDENTIALS=\":\"","This sets the MOSAIC_DOCS_CLONE_CREDENTIALS environment variable with your Git credentials.","Serve command","Now you can serve your Mosaic site by running the following command:","yarn serve","Access your Mosaic site from a browser using the following URLs:","To browse the content from your local source: http://localhost:3000/local","To browse the content from the Mosaic Git repo source: http://localhost:3000/mosaic","That's it! ","Your Mosaic site is now up and running.","Next Steps:","Deploy your Mosaic site to AWS or Vercel for production use.","Create more pages to expand your site's content.","Configure your own sources in the mosaic.config.mjs file to pull content from different locations.","Theme your site"]},{"title":"Getting Started","route":"/mosaic/getting-started/index","content":["Getting Started with Mosaic","Follow our step-by-step guides to quickly create and deploy your first Mosaic site."]},{"title":"Publish a site to AWS","route":"/mosaic/getting-started/publish-site-to-aws","content":["Publish a site to AWS using S3 snapshots.","Step 1: Generate a Mosaic site","If you have already created your Mosaic site, skip ahead to step 2.","> npx @jpmorganchase/mosaic-create-site -o my-sample-site\n","> cd my-sample-site","Step 2: Create a Github repository","> git init\n","> git remote add origin git@github.com:username/my-sample-site.git\n","> git add .\n","> git commit -m \"initial commit\"\n","> git push origin main","Step 3: Generate a snapshot of content","Consider a snapshot as a directory of static content previously pulled from your content sources, which does not update itself.","> yarn gen:snapshot","Step 4: Configure environment for S3","> export MOSAIC_MODE=\"snapshot-s3\"\n","> export MOSAIC_S3_BUCKET=\"\"\n","> export MOSAIC_S3_REGION=\"\"\n","> export MOSAIC_S3_ACCESS_KEY_ID=\"\"\"\n","> export MOSAIC_S3_SECRET_ACCESS_KEY=\"\"\n","> yarn mosaic upload -S ./snapshots/latest","Step 5: Setup AWS","Switch to the ","AWS Amplify"," console and deploy your app as a SSR application by following the ","AWS docs",".","Setup an S3 bucket as per the ","AWS S3 docs",".","Step 7: Configure your AWS app","Add the environment vars to the hosted app via your console","MOSAIC_MODE=\"snapshot-s3\"\n","MOSAIC_S3_BUCKET=\"\"\n","MOSAIC_S3_REGION=\"\"\n","MOSAIC_S3_ACCESS_KEY_ID=\"\"\"\n","MOSAIC_S3_SECRET_ACCESS_KEY=\"\"","Add the following build settings","version: 1\n","frontend:\n"," phases:\n"," preBuild:\n"," commands:\n"," - yarn install\n"," - env | grep -e MOSAIC >> .env.production\n"," build:\n"," commands:\n"," - yarn run build\n"," artifacts:\n"," baseDirectory: .next\n"," files:\n"," - '**/*'\n"," cache:\n"," paths:\n"," - node_modules/**/*","Ensure the Node is set to 16","Step 8: Upload your snapshot","Upload your snapshot to S3 storage.","> yarn mosaic upload -S ./snapshots/latest"]},{"title":"Publish","route":"/mosaic/publish/index","content":["To create your first Mosaic site, we have created a command line generator that scaffolds a ","standard"," site.","A ","standard"," site offers","an out the box, working site, which showcases local and remote content sources","a minimal set of files that can be configured with your own components, themes, layouts, sources and plugins","an update path that enables you to update Mosaic, independently of your own configuration","Create your first site","Install the Mosaic create site script.","> yarn global add @jpmorganchase/mosaic-create-site","Create a directory for your site and run the "," script.","> mkdir mosaic-sample-site\n","> cd mosaic-sample-site\n","> mosaic-create-site -f .","Define the environment variable, which enables us to access your remote repo.","> export MOSAIC_DOCS_CLONE_CREDENTIALS=\"\"","The "," environment variable is composed of your git username and your PAT token.\n","Follow these ","docs"," to see how to create your own PAT token.","Your site is ready to run.","> yarn serve","In your browser load ","Congratulations, you have created your first Mosaic site."]},{"title":"Publish a site to AWS","route":"/mosaic/publish/publish-site-to-aws","content":["A Mosaic site is a ","Next.Js"," app.","To publish a Next.Js App to AWS, deploy your app as a SSR application by following the ","AWS docs",".","Once the basic app has been configured, add the Mosaic specifics.","Add the environment vars to the hosted app via the Amplify console","MOSAIC_MODE=\"snapshot-s3\"\n","MOSAIC_S3_BUCKET=\"\"\n","MOSAIC_S3_REGION=\"\"\n","MOSAIC_S3_ACCESS_KEY_ID=\"\"\"\n","MOSAIC_S3_SECRET_ACCESS_KEY=\"\"","Add the following build settings","version: 1\n","frontend:\n"," phases:\n"," preBuild:\n"," commands:\n"," - yarn install\n"," - env | grep -e MOSAIC >> .env.production\n"," build:\n"," commands:\n"," - yarn run build\n"," artifacts:\n"," baseDirectory: .next\n"," files:\n"," - '**/*'\n"," cache:\n"," paths:\n"," - node_modules/**/*","Ensure the Node is set to 16"]},{"title":"Publish a site to Vercel","route":"/mosaic/publish/publish-site-to-vercel","content":["A Mosaic site is a ","Next.Js"," app.","To publish a Next.Js App to Vercel, refer to the ","Vercel docs",".","Deployment","As the ","vercel platform"," hosts static content you will need to deploy a mosaic snapshot. ","There is no option to run mosaic in ","active mode",".","1. ","Update Config File","Add the following to the mosaic config file used by your site:"," deployment: { mode: 'snapshot-file', platform: 'vercel' }","2. ","Set Environment Variables","Set 2 ","environment variables"," in the vercel dashboard.","| Variable Name | Value |\n","| ------------------- | ----------------- |\n","| MOSAIC_MODE | snapshot-file |\n","| MOSAIC_SNAPSHOT_DIR | snapshots/latest. ","|","3. ","Run Build and Deploy","The "," command used by vercel must run "," followed by ","The "," command is needed to workaround an ","output file tracing"," problem.","Example:","yarn build && yarn deploy","Output File Tracing","Output File Tracing"," is a feature of Next.js that uses static analysis\n","to determine what files are needed to deploy a production version of an application.","Due to the architecture of mosaic, snapshot files can be ignored by this process and therefore excluded from the build artifacts deployed by vercel.","If you are deploying your site to the ","vercel platform"," then the mosaic site has a "," command that will update the nextjs output trace to include the snapshot files."]},{"title":"Test","route":"/mosaic/test/index","content":["Pages for e2e testing."]},{"title":"Admin","route":"/mosaic/configure/admin/index","content":["There are several admin urls exposed by Mosaic that provide an insight into how the filesystem has been configured and a way to remotely manage sources.","Endpoints","| Endpoint | Method | Description | Params |\n","| -------------------------- | ------ | -------------------------------------------- | ---------------------- |\n","| "," | GET | Returns the JSON from the Mosaic config file | n/a |\n","| "," | GET | Returns the entire mosaic filesystem as JSON | n/a |\n","| "," | GET | Returns a collection of active sources | n/a |\n","| "," | POST | Adds the source | definition & isPreview |\n","| "," | PUT | Stops the source with the provided name | name |\n","| "," | PUT | Restarts the source with the provided name | name |"]},{"title":"Detail Highlight","route":"/mosaic/configure/layouts/detail-highlight","content":["Layout: Detail Highlight","Initialize with "," in your page's frontmatter.","This layout is used to promote, share insights, and statistics for a line of business.","This layout should be used for pages with only one level of nesting, therefore, pagination is not eligible for this\n","layout.","Page geometry"]},{"title":"Detail Overview","route":"/mosaic/configure/layouts/detail-overview","content":["Layout: Detail Overview","Initialize with "," in your page's frontmatter.","This layout is used to present an overview of expected documentation, statisitics, and ability to\n","navigate to more documents.","Avoid making this page too long. ","If it gets too long, we recommend the ","Detail Technical"," template.","Page geometry","Other Layouts","Detail Highlight","Detail Technical","Landing","Product Discover","Product Preview","Filler content","Eiusmod veniam adipisicing est magna id sunt occaecat minim adipisicing ad do pariatur id aliqua.\n","Officia officia deserunt consequat ullamco irure. ","Excepteur deserunt esse occaecat ex aute. ","Duis do\n","do in incididunt cupidatat dolore veniam magna aliquip voluptate laborum. ","Non irure magna amet\n","ullamco culpa esse dolore nostrud. ","Id ea id ipsum incididunt do velit aliquip fugiat do non\n","consequat.","A sub heading","Deserunt sunt pariatur mollit dolor eiusmod. ","Anim sunt officia cillum anim. ","Laborum ullamco\n","consectetur elit dolore quis laborum. ","Eiusmod cillum amet veniam sunt Lorem reprehenderit commodo.\n","Cupidatat cillum ea consequat anim. ","Duis voluptate nulla veniam labore quis tempor.","Commodo reprehenderit excepteur amet aliquip cillum veniam ad. ","Ullamco proident deserunt laboris\n","duis laborum consequat laboris est eu enim nulla. ","Mollit velit consectetur ea aliqua consectetur\n","mollit eu ex deserunt. ","Aute excepteur exercitation esse proident excepteur Lorem. ","Quis cillum\n","occaecat sint voluptate incididunt ea ipsum incididunt duis sint magna magna fugiat.","Third-level heading","Ea do magna aute proident nulla cupidatat esse consectetur anim eu esse. ","Consectetur est voluptate\n","excepteur non dolore consequat fugiat deserunt. ","Est nostrud est ea irure reprehenderit commodo\n","nostrud nulla tempor ipsum tempor sit id exercitation. ","Sunt reprehenderit officia anim id quis\n","pariatur velit cillum incididunt officia sunt. ","Ullamco ipsum cillum minim deserunt eiusmod nostrud\n","irure et nulla laborum ipsum ipsum incididunt. ","Voluptate reprehenderit in occaecat ipsum nulla\n","excepteur excepteur mollit laboris id ad laborum do. ","Qui in laborum nostrud quis occaecat proident\n","ipsum tempor laborum consequat id ut velit occaecat.Aliquip quis qui ullamco ipsum exercitation\n","exercitation excepteur ea ex. ","Proident elit incididunt incididunt ad adipisicing quis deserunt sint\n","laboris deserunt ipsum culpa est. ","Id do ex duis Lorem exercitation amet reprehenderit. ","Voluptate qui\n","tempor qui sit minim sit qui ea id dolor excepteur. ","Laborum elit excepteur enim sunt consequat\n","officia cillum. ","Do ea occaecat ut voluptate ea proident duis minim ad pariatur dolore magna enim\n","duis. ","Sit aliqua aliqua ea mollit enim cupidatat proident incididunt. ","Eu dolore sit non incididunt.\n","Mollit reprehenderit sunt sunt cillum labore velit exercitation officia aliqua ea adipisicing do ea.\n","Commodo et fugiat velit dolore consectetur.","Amet dolore deserunt in ut amet officia exercitation sint excepteur voluptate proident tempor enim\n","est. ","Culpa proident tempor in voluptate laboris sunt consectetur sit cillum excepteur culpa enim\n","velit laboris. ","Pariatur elit amet nostrud tempor nostrud ea. ","Exercitation do aliquip nisi amet id.\n","Lorem labore incididunt sit sit veniam tempor do consectetur do culpa qui.","Id sint deserunt laborum mollit id excepteur","mollit excepteur labore labore dolor. ","Sit cupidatat nostrud ad consequat amet excepteur id sunt\n","labore adipisicing non irure. ","Fugiat exercitation laborum officia minim duis dolor do officia Lorem\n","cillum excepteur. ","Sint elit mollit duis sit ad commodo.","Cillum amet irure ut tempor tempor culpa dolore sint.","Lorem qui ipsum reprehenderit est incididunt duis exercitation ea duis fugiat. ","Consectetur enim id\n","sunt exercitation et dolore ea proident sunt excepteur fugiat dolor. ","Veniam proident dolore irure\n","incididunt deserunt pariatur quis. ","Incididunt ea elit deserunt occaecat eiusmod velit fugiat eiusmod\n","dolor eiusmod ullamco. ","Fugiat fugiat eiusmod occaecat nulla consequat pariatur.","Aliquip non cupidatat irure magna et fugiat sunt amet ex est excepteur irure quis. ","Non culpa magna\n","nisi enim eu nulla esse laborum amet ipsum. ","Eu consectetur labore do id occaecat adipisicing."]},{"title":"Detail Technical","route":"/mosaic/configure/layouts/detail-technical","content":["Layout: Detail Technical","Initialize with "," in your page's frontmatter.","This layout is used for longer, technical, detailed content about the product.","This layout shows less marketing-type visuals and more visual of diagrams, screenshots, and code\n","snippets.","This page can be short or very lengthy.","Page geometry","Other Layouts","Detail Highlight","Detail Overview","Landing","Product Discover","Product Preview","Filler content","Eiusmod veniam adipisicing est magna id sunt occaecat minim adipisicing ad do pariatur id aliqua.\n","Officia officia deserunt consequat ullamco irure. ","Excepteur deserunt esse occaecat ex aute. ","Duis do\n","do in incididunt cupidatat dolore veniam magna aliquip voluptate laborum. ","Non irure magna amet\n","ullamco culpa esse dolore nostrud. ","Id ea id ipsum incididunt do velit aliquip fugiat do non\n","consequat.","A sub heading","Deserunt sunt pariatur mollit dolor eiusmod. ","Anim sunt officia cillum anim. ","Laborum ullamco\n","consectetur elit dolore quis laborum. ","Eiusmod cillum amet veniam sunt Lorem reprehenderit commodo.\n","Cupidatat cillum ea consequat anim. ","Duis voluptate nulla veniam labore quis tempor.","Commodo reprehenderit excepteur amet aliquip cillum veniam ad. ","Ullamco proident deserunt laboris\n","duis laborum consequat laboris est eu enim nulla. ","Mollit velit consectetur ea aliqua consectetur\n","mollit eu ex deserunt. ","Aute excepteur exercitation esse proident excepteur Lorem. ","Quis cillum\n","occaecat sint voluptate incididunt ea ipsum incididunt duis sint magna magna fugiat.","Third-level heading","Ea do magna aute proident nulla cupidatat esse consectetur anim eu esse. ","Consectetur est voluptate\n","excepteur non dolore consequat fugiat deserunt. ","Est nostrud est ea irure reprehenderit commodo\n","nostrud nulla tempor ipsum tempor sit id exercitation. ","Sunt reprehenderit officia anim id quis\n","pariatur velit cillum incididunt officia sunt. ","Ullamco ipsum cillum minim deserunt eiusmod nostrud\n","irure et nulla laborum ipsum ipsum incididunt. ","Voluptate reprehenderit in occaecat ipsum nulla\n","excepteur excepteur mollit laboris id ad laborum do. ","Qui in laborum nostrud quis occaecat proident\n","ipsum tempor laborum consequat id ut velit occaecat.Aliquip quis qui ullamco ipsum exercitation\n","exercitation excepteur ea ex. ","Proident elit incididunt incididunt ad adipisicing quis deserunt sint\n","laboris deserunt ipsum culpa est. ","Id do ex duis Lorem exercitation amet reprehenderit. ","Voluptate qui\n","tempor qui sit minim sit qui ea id dolor excepteur. ","Laborum elit excepteur enim sunt consequat\n","officia cillum. ","Do ea occaecat ut voluptate ea proident duis minim ad pariatur dolore magna enim\n","duis. ","Sit aliqua aliqua ea mollit enim cupidatat proident incididunt. ","Eu dolore sit non incididunt.\n","Mollit reprehenderit sunt sunt cillum labore velit exercitation officia aliqua ea adipisicing do ea.\n","Commodo et fugiat velit dolore consectetur.","Amet dolore deserunt in ut amet officia exercitation sint excepteur voluptate proident tempor enim\n","est. ","Culpa proident tempor in voluptate laboris sunt consectetur sit cillum excepteur culpa enim\n","velit laboris. ","Pariatur elit amet nostrud tempor nostrud ea. ","Exercitation do aliquip nisi amet id.\n","Lorem labore incididunt sit sit veniam tempor do consectetur do culpa qui.","Id sint deserunt laborum mollit id excepteur","mollit excepteur labore labore dolor. ","Sit cupidatat nostrud ad consequat amet excepteur id sunt\n","labore adipisicing non irure. ","Fugiat exercitation laborum officia minim duis dolor do officia Lorem\n","cillum excepteur. ","Sint elit mollit duis sit ad commodo.","Cillum amet irure ut tempor tempor culpa dolore sint.","Lorem qui ipsum reprehenderit est incididunt duis exercitation ea duis fugiat. ","Consectetur enim id\n","sunt exercitation et dolore ea proident sunt excepteur fugiat dolor. ","Veniam proident dolore irure\n","incididunt deserunt pariatur quis. ","Incididunt ea elit deserunt occaecat eiusmod velit fugiat eiusmod\n","dolor eiusmod ullamco. ","Fugiat fugiat eiusmod occaecat nulla consequat pariatur.","Aliquip non cupidatat irure magna et fugiat sunt amet ex est excepteur irure quis. ","Non culpa magna\n","nisi enim eu nulla esse laborum amet ipsum. ","Eu consectetur labore do id occaecat adipisicing."]},{"title":"Layouts","route":"/mosaic/configure/layouts/index","content":["Todo..."]},{"title":"Landing Layout","route":"/mosaic/configure/layouts/landing","content":["Layout: Landing","Initialize with "," in your page's frontmatter.","Use this layout as a landing page to show large branded visuals, and high-level content about the\n","line of business.","Set the tone and voice for your LOB’s experience.","Use components that support your content with places to insert visuals, share any stats or an\n","introduction of LOB’s story.","Use heading styles to show the grouping of content of a section.","Page geometry"]},{"title":"Product Discover Layout","route":"/mosaic/configure/layouts/product-discover","content":["Layout: Product Discover","Initialize with "," in your page's frontmatter.","Use this layout to introduce a product feature with a description and large visual.","This layout is use for marketing and discovery content.","Page geometry"]},{"title":"Product Preview Layout","route":"/mosaic/configure/layouts/product-preview","content":["Layout: Product Preview","Initialize with "," in your page's frontmatter.","This layout has been used to introduce a product and showcase their suite of product offerings.","Use heading styles to show the grouping of content of a section.","Page geometry"]},{"title":"Active mode","route":"/mosaic/configure/modes/active","content":["In "," mode content can be ","pulled"," from heterogeneous data sources and normalized via plugins, to the configured components/theme.\n","As your content changes, the site will ","re-pull"," the content and update your site in real-time.","The standard generated site comes with 2 sources to demonstrate, how 'active' mode work.","a local source, which loads content from ","a remote source, which loads content from a ","sample Github repository","Configuring your content sources","All content is composed together within a ","namespace",".","A ","namespace"," is the scope for aggregated content, represented by the root path.\n","e.g Our sample docs are aggregated into a ","namespace"," called "," and served by the user journey ","Mosaic doc sources are defined by a file called ","Here is how that might look for a standard site.","Pull your local content","To tryout local content creation, add a file called","The load ","Each directory should contain an "," which is the default page, when a page is loaded without a path","Now create other pages and subdirectories and explore how Mosaic, builds your user-journeys from your fileset.","Pull your remote content","To tryout remote content creation, your standard site comes pre-configured to load our Mosaic sample docs.","Edit the "," and change your "," and "," to pull content from other repos."]},{"title":"Modes of operation","route":"/mosaic/configure/modes/index","content":["Mosaic can operate in 3 different modes","Active updates","In ","active"," mode, content updates in real-time.","active"," mode content is pulled at configured intervals in real-time, as defined by ",".","Read the ","active"," configuration docs.","Static content","Consider a snapshot as a directory of static content previously pulled from your content sources, which does not update itself.","In a snapshot mode, the snapshot does update itself.","File based snapshots","In "," mode, immutable snapshots of content are loaded at startup from the local file-system.","Read the ","snapshot-file"," configuration docs.","S3 based snapshots","In "," mode, snapshots of content are loaded at startup from a remote S3 bucket.","Read the ","snapshot-s3"," configuration docs."]},{"title":"Snapshot file mode","route":"/mosaic/configure/modes/snapshot-file","content":["In "," mode a local immutable snapshot can be loaded by the site. ","Typically, the snapshot and the site are\n","deployed together and upon startup the site can load the snapshot from the local file-system.","To use "," mode","export MOSAIC_MODE=\"snapshot-file\"\n","export MOSAIC_SNAPSHOT_DIR=\"./snapshot/latest\"","Generating a snapshot","To generate a snapshot, run","yarn gen:snapshot","Commit the snapshot to your Git repo and push the site+snapshot to your Git repo, within the same branch."]},{"title":"Snapshot AWS/S3 mode","route":"/mosaic/configure/modes/snapshot-s3","content":["In "," mode a snapshot can be loaded from a pre-configured AWS S3 bucket.","To use "," mode","> export MOSAIC_MODE=\"snapshot-s3\"\n","> MOSAIC_S3_BUCKET=\"\"\n","> MOSAIC_S3_REGION=\"\"\n","> MOSAIC_S3_ACCESS_KEY_ID=\"\"\n","> MOSAIC_S3_SECRET_ACCESS_KEY=\"\"","Generating a snapshot","To generate a snapshot, run","yarn gen:snapshot","Uploading a snapshot to S3","To upload a snapshot to S3, define the required environment variables and run","yarn mosaic upload -S "]},{"title":"$AliasPlugin","route":"/mosaic/configure/plugins/alias-plugin","content":["The "," is what powers the ","aliases"," feature of Mosaic.","It does this by scrapes "," from page metadata and also applies all aliases stored in ","Other plugins can use "," to apply new aliases, as long as they call it before this plugin has reaches the "," lifecycle event.","This plugin is added to the plugins collection by Mosaic itself so users do ","not"," need to include it in their own mosaic config file.","Priority","This plugin runs with a priority of -1 so it runs ","after"," most other plugins."]},{"title":"BreadcrumbsPlugin","route":"/mosaic/configure/plugins/breadcrumbs-plugin","content":["The "," is responsible for generating the data needed to show breadcrumbs navigation on pages. ","It then appends this data to a "," property in the page metadata.","Should a page already have a "," property in it's metadata then it is respected and not overwritten.","If a page has a "," property in it's metadata then this is used as the label for the breadcrumb, otherwise the page "," is used.","When the "," is traversing up directories, it needs to know what page in the directory represents the ","breadcrumb"," for that directory. ","It is recommended to use the "," page for this but the page to use is a configurable option of the breadcrumbs plugin.","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| ------------- | ------------------------------------------------ |\n","| indexPageName | The page name to use for \"directory\" breadcrumbs |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the breadcrumbs plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/BreadcrumbsPlugin',\n"," options: {\n"," indexPageName: 'index.mdx'\n"," }\n"," }\n"," // other plugins\n","];"]},{"title":"BrokenLinksPlugin","route":"/mosaic/configure/plugins/broken-links-plugin","content":["The "," will identify any broken links in pages Mosaic has pulled into it's filesystem by making use of the ","check-links"," package.","It can identify broken links between the pages themselves and external links that pages link out to.","What this plugin is really checking is \"liveness\" of a link.","alive if the URL is reachable (2XX status code)","dead if the URL is not reachable","invalid if the URL was parsed as invalid or used an unsupported protocol","Links may be \"alive\", but the ","content"," of the linked page may not be what you want so continue\n","to check links show what you expect.","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n","| baseUrl | This is used to calculate the full url for links between pages. ","It should be the url Mosaic is running on |\n","| proxyEndpoint | If you are behind a corporate proxy, external link checking will not work unless you specify the proxy endpoint using this option |","Adding to Mosaic","This plugin is ","not"," included in the mosaic config shipped by the Mosaic standard generator so it must be added manually to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/BrokenLinksPlugin',\n"," priority: -1,\n"," // Exclude this plugin in builds\n"," runTimeOnly: true,\n"," options: {\n"," baseUrl: process.env.MOSAIC_ACTIVE_MODE_URL || 'http://localhost:8080',\n"," proxyEndpoint: 'http://some-proxy-url'\n"," }\n"," }\n"," // other plugins\n","];","This plugin needs to be a "," plugin because it needs Mosaic to be running in order to\n","make requests to all of the page links.","Example Output","When a link is found to be broken, you will see the following output in the console:","@jpmorganchase/mosaic-site:serve: 8080 [Mosaic] Broken links found in /local/docs/publish-site-to-vercel.mdx\n","@jpmorganchase/mosaic-site:serve: 8080 Link to https://nextjs.org/davie is dead {\n","@jpmorganchase/mosaic-site:serve: 8080 type: 'link',\n","@jpmorganchase/mosaic-site:serve: 8080 title: null,\n","@jpmorganchase/mosaic-site:serve: 8080 url: 'https://nextjs.org/davie',\n","@jpmorganchase/mosaic-site:serve: 8080 children: [ { type: 'text', value: 'Next.Js', position: [Object] } ],\n","@jpmorganchase/mosaic-site:serve: 8080 position: {\n","@jpmorganchase/mosaic-site:serve: 8080 start: { line: 4, column: 20, offset: 36 },\n","@jpmorganchase/mosaic-site:serve: 8080 end: { line: 4, column: 55, offset: 71 }\n","@jpmorganchase/mosaic-site:serve: 8080 }\n","@jpmorganchase/mosaic-site:serve: 8080 }"]},{"title":"$CodeModPlugin","route":"/mosaic/configure/plugins/codemod-plugin","content":["Todo"]},{"title":"Plugins","route":"/mosaic/configure/plugins/index","content":["Mosaic Plugins are ","lifecycle-based"," hooks that are called on ","every"," source at different stages. ","You will never need to invoke a lifecycle method directly as their execution is managed by a plugin runner.","Plugins enable Mosaic to have a lightweight and flexible, modular architecture by encapsulating features and functionality as plugins.","Installation","Configuration","Plugins are added to the "," collection of the mosaic config file. ","Like ","sources",", plugins have an options property that can be used to provide plugin specific configuration.","| Property | Description | Required |\n","| --------------- | -------------------------------------------------------------------------- | -------- |\n","| modulePath | The path to the installed plugin module | Yes |\n","| disabled | Exclude this plugin completely. ","Defaults to false | No |\n","| runtimeOnly | Exclude this plugin when generating a snapshot. ","Defaults to false | No |\n","| previewDisabled | Exclude this plugin for \"preview\" sources | No |\n","| allowMultiple | Allow multiple instances of this plugin to run. ","| No |\n","| priority | The importance of this plugin. ","Plugins with the highest priority run first | No |\n","| options | Collection of other configuration values | No |"," plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/PagesWithoutFileExtPlugin',\n"," options: {},\n"," priority: 1\n"," },\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',\n"," options: {}\n"," },\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/ReadingTimePlugin',\n"," options: {}\n"," }\n","],","There is no need to import the plugin module directly. ","As long as the plugin is installed, Mosaic\n","will be able to import it using the built-in plugin loader.","Default Plugins","The following plugins are always included by Mosaic, regardless of whether they are present in the plugins collection of the Mosaic config file:","$TagPlugin","$AliasPlugin","$CodeModPlugin","$RefPlugin","Plugin errors","Should a plugin fail, the failure will ","not"," cause a source to close or for any other plugin to not run.","Instead plugin errors are tracked by Mosaic and can be viewed in the "," property available on each source listed by the list sources ","admin API",".","Plugin errors will be split by lifecycle event and only the lifecycle events used by the loaded plugins used will be shown.","Multiple Instances","By default, Mosaic will only run one instance of a plugin.","It may be the case that you wish to run the same plugin twice with a slightly different config. ","To do this, you must have 2 instances listed in the plugins collection and they ","both"," must set the "," option to ",".","For example, the config below runs the ","SidebarPlugin"," twice:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',\n"," options: { rootDirGlob: 'products/product-a' },\n"," allowMultiple: true\n"," },\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',\n"," options: { rootDirGlob: '*/!(","product-a)/*' },\n"," allowMultiple: true\n"," }\n"," // other plugins\n","];"]},{"title":"LazyPagePlugin","route":"/mosaic/configure/plugins/lazy-page-plugin","content":["The "," attempts to reduce the size of the Mosaic filesystem in memory by moving page metadata and content to disk.","It then adds a hook, so that when a page is requested the data is loaded from disk and combined with what is already in the Mosaic filesystem.","It must be the very last to run so that it can strip off metadata and content after other plugins\n","have finished with them.","Priority","This plugin runs with a priority of -2. ","Needs to be the last to run for biggest impact.","Options","| Property | Description |\n","| -------- | ------------------------------------------------------------------------------ |\n","| cacheDir | The directory to store the cache. ","Defaults to "," |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/LazyPagePlugin',\n"," // This plugin must be the very last to run, so it can strip off metadata and content after the other\n"," // plugins are done with them\n"," priority: -2,\n"," // Exclude this plugin in builds\n"," runTimeOnly: true,\n"," options: {\n"," cacheDir: '.tmp/.pull-docs-last-page-plugin-cache'\n"," }\n"," }\n"," // other plugins\n","];","This plugin needs to be a "," plugin because the goal is to reduce the in-memory\n","filesystem size."]},{"title":"PagesWithoutFileExtPlugin","route":"/mosaic/configure/plugins/pages-wthout-extensions-plugin","content":["The "," plugin creates ","aliases"," without the file extension for every page in the Mosaic filesystem.\n","This allows pages to be retrieved from the filesystem without specifying the extension e.g., ",".","The plugin also modifies the "," metadata property of a page to point to the shorter alias.","Priority","This plugin runs with a priority of 1. ","It must run after the ","$AliasPlugin",".","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/PagesWithoutFileExtPlugin',\n"," options: {},\n"," priority: 1\n"," }\n"," // other plugins\n","];"]},{"title":"PublicAssetsPlugin","route":"/mosaic/configure/plugins/public-assets-plugin","content":["The "," is responsible for finding \"assets\" in the Mosaic filesystem and copying them to another directory.","Typical usecase is for copying "," and "," to the public directory of a Next.js site as these are considered ","static assets"," for Next.js.","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| --------- | ----------------------------------------------------------- |\n","| outputDir | The directory to copy the assets to. ","Defaults to "," |\n","| assets | A collection of filenames to copy to the outputDir |","Adding to Mosaic","This plugin is ","not"," included in the mosaic config shipped by the Mosaic standard generator so it must be added manually to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/PublicAssetsPlugin',\n"," priority: -1,\n"," options: {\n"," outputDir: './public',\n"," assets: ['sitemap.xml', 'search-data.json']\n"," }\n"," }\n"," // other plugins\n","];"]},{"title":"ReadingTimePlugin","route":"/mosaic/configure/plugins/reading-time-plugin","content":["The "," generates an estimation of how long a page written in MDX will take to read and adds the "," property to the metadata of a page.","Priority","This plugin runs with no special priority.","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/ReadingTimePlugin',\n"," options: {}\n"," }\n"," // other plugins\n","];"]},{"title":"$RefPlugin","route":"/mosaic/configure/plugins/ref-plugin","content":["The "," powers the ","refs"," feature of Mosaic.","The plugin scrapes "," properties from page metadata and also applies all refs stored in ",".","Other plugins can use "," to apply new refs, as long as they call it before this plugin has reaches ",".","Priority","This plugin runs with a priority of -1 so it runs ","after"," most other plugins."]},{"title":"SearchIndexPlugin","route":"/mosaic/configure/plugins/search-index-plugin","content":["The "," is responsible for generating the search index and configuration information for ","Fuse.js"," which is the matching engine powering the client-side search functionality of Mosaic sites.","It outputs 3 files:","Full Search Index - ","Condensed Search Index - ","Search Configuration - ","Full Search Index","On a Mosaic site, the full index is fetched after a page has loaded, thus removing the chance of a huge index slowing down first-load.","Practically, the full index should load in the background before a user searches for something, but should a search be initiated before that (e.g., slow-internet) then the condensed version of the search index is available.","Condensed Search Data","Search Index plugin creates a \"condensed\" version of the search index that only includes the "," and "," for each page. ","This is the \"Minimum Viable Index\" to provide somewhat useable search results client-side while the main search index is loaded in the background.","Search Configuration","Any ","options"," that need to be passed to Fuse.js.","Search relevancy configuration","| Property | Description |\n","| ---------------- | ----------------------------------------------------- |\n","| includeScore | https://www.fusejs.io/api/options.html#includescore |\n","| includeMatches | https://www.fusejs.io/api/options.html#includematches |\n","| maxPatternLength | TODO |\n","| ignoreLocation | https://www.fusejs.io/api/options.html#ignorelocation |\n","| threshold | https://www.fusejs.io/api/options.html#threshold |\n","| keys | https://www.fusejs.io/api/options.html#keys |","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| ------------- | --------------------------------------------------- |\n","| maxLineLength | TODO |\n","| maxLineCount | TODO |\n","| keys | https://www.fusejs.io/api/options.html#keys |\n","| relevancy | ","search relevancy"," |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SearchIndexPlugin',\n"," previewDisabled: true,\n"," options: { maxLineLength: 240, maxLineCount: 240 }\n"," }\n"," // other plugins\n","];","It's usually a good idea to mark this plugin as disabled for preview sources otherwise the pages\n","from the preview will appear in search results."]},{"title":"SharedConfigPlugin","route":"/mosaic/configure/plugins/shared-config-plugin","content":["The "," crawls the page hierarchy to find the closest "," metadata from any parent index's page metadata. ","It then exports a JSON file into each directory with the merged config for that level.","Shared config is typically the place where the following is configured for a Mosaic site:","App Header configuration including site name and main navigation","Footer information","Help links for the left sidebar area","Namespace Shared Configs","Consider 2 sources the share the same ","namespace"," \"product-docs\":","Source A - multiple product directories and main product index page. ","The index page specifies "," metadata.","Source B - pages relevant to a single product. ","Index page does ","not"," have any "," metadata.","Let's also assume that the pages from Source B would also naturally \"fit\" within the pages of Source B (e.g. inside a products directory).","In this scenario, the "," will attempt to copy the shared config file from Source A into the root directory of Source B allowing the Source B pages to use the Source A "," as though it were a product sourced directly from Source A.","Priority","This plugin runs with a priority of 3.","Options","| Property | Description |\n","| -------- | ---------------------------------------------- |\n","| filename | the name of the JSON file output by the plugin |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SharedConfigPlugin',\n"," options: {\n"," filename: 'shared-config.json'\n"," },\n"," priority: 3\n"," }\n"," // other plugins\n","];"]},{"title":"SidebarPlugin","route":"/mosaic/configure/plugins/sidebar-plugin","content":["The "," generates the necessary page metadata needed for the vertical navigation shown on some Mosaic pages.","The output from the plugin is added to a "," metadata property of the page.","Configuration","The "," is used to determine the \"root\" directories of the sidebar. ","So for example:"," - generate sidebar data for the pages that are 3 directories deep in the filesystem hierarchy"," - same as above but ignore the product-a directory"," - generate a sidebar just for product-b in the products directory","To rearrange pages in the sidebar or to apply a different label to a page you can ","configure the sidebar"," using page frontmatter.","Priority","This plugin runs with a priority of 3.","Options","| Property | Description |\n","| ----------- | ----------------------------------------------------------------------------- |\n","| filename | filename of the sidebar json, linked to each related page via ref |\n","| rootDirGlob | Glob pattern for matching directories which should be the root of the sidebar |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',\n"," options: { rootDirGlob: '*/*/*' }\n"," }\n"," // other plugins\n","];"]},{"title":"SiteMapPlugin","route":"/mosaic/configure/plugins/site-map-plugin","content":["The "," generates a ","sitemap"," using the pages in the Mosaic filesystem that adheres to the ","sitemaps XML schema",".","The output of the plugin is a file is named ",".","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| -------- | --------------------------------------------------------------------------------------------------- |\n","| siteUrl | The site URL. ","Used as the prefix for loc entries in the sitemap as these must start with a protocol |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/SiteMapPlugin',\n"," previewDisabled: true,\n"," options: { siteUrl: process.env.SITE_URL || 'http://localhost:3000' }\n"," }\n"," // other plugins\n","];","Visualiser","To visualise your sitemap you can combine this plugin with the "," component provided by ",".","Rendering the "," component will render a tree view of your sitemap.","","Have a look at this site's pages, ","here","."]},{"title":"$TagPlugin","route":"/mosaic/configure/plugins/tag-plugin","content":["The "," powers the tags feature of Mosaic.","This plugin scrapes "," from page metadata and also applies all aliases stored in ",".","Tags ultimately resolve down into ","refs",", but are different from normal refs, in that they are applied to the\n","union filesystem (all merged filesystems), not to the individual source filesystem that they were defined on. ","This can be thought of as a ","global ref",".","Other plugins can use "," and modify the "," property, to apply new global refs, as long as\n","they do so before this plugin has reaches ",".","Priority","This plugin runs with no special priority but it must run before both the "," and the ",".","Example use case - Products Page","Let's assume there is a products page on your site and each product is shown as a tile. ","The information for each product tile is sourced from multiple Mosaic sources. ","How can tags be used to reference the product data needed for each tile on the products page?","The product page should add a "," metadata prop to its frontmatter:","---\n","title: Products\n","description: Product index\n","layout: ProductPreview\n","data:\n"," items:\n"," $tag: product#/data\n","---","The tag shown in the example above is saying populate "," of the Products index page with the "," metadata property of pages tagged with ",".","A tagged product page needs to have a "," property which is a collection of tags and one of these needs to be ",". ","This will allow the "," to correctly associate the product page to the product index page. ","It will also need a "," property because thats the property our product index page wants to use for the tiles.","---\n","title: Product A\n","description: My Product description\n","layout: ProductDiscover\n","tags:\n"," - product\n","data:\n"," name:\n"," $ref: '#/title'\n"," date: 2023/02/07\n"," action: Product Overview\n"," description:\n"," $ref: '#/description'\n"," link: /products/a/index\n","---","---\n","title: Product B\n","description: My Product description\n","layout: ProductDiscover\n","tags:\n"," - product\n","data:\n"," name:\n"," $ref: '#/title'\n"," date: 2023/02/07\n"," action: Product Overview\n"," description:\n"," $ref: '#/description'\n"," link: /products/b/index\n","---"]},{"title":"TableOfContentsPlugin","route":"/mosaic/configure/plugins/toc-plugin","content":["The "," generates a Table of Contents for each page in the Mosaic filesystem using the headings on the page.","Heading ranks are used to determine which page headings should be included in the Table of Contents:","| Heading Element (markdown syntax) | Rank |\n","| --------------------------------- | ---- |\n","| h1 (#) | 1 |\n","| h2 (##) | 2 |\n","| h3 (###) | 3 |\n","| h4 (####) | 4 |\n","| h5 (#####) | 5 |\n","| h6 (######) | 6 |","The plugin output is added to a "," metadata property of a page.","Priority","This plugin runs with no special priority.","Options","| Property | Description |\n","| -------- | ----------------------------- |\n","| minRank | The minimum page heading rank |\n","| maxRank | The maximum page heading rank |","Adding to Mosaic","This plugin is included in the mosaic config shipped by the Mosaic standard generator. ","So if you use the below import in your "," file then the plugin is included already:","import mosaicConfig from '@jpmorganchase/mosaic-standard-generator/dist/fs.config.js';","To add it yourself, add the following to the "," collection:","plugins: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-plugins/TableOfContentsPlugin',\n"," options: {\n"," minRank: 2,\n"," maxRank: 3\n"," }\n"," }\n"," // other plugins\n","];"]},{"title":"Git Repo Source","route":"/mosaic/configure/sources/git-repo-source","content":["The Git Repo Source is used to pull content from a remote git repository e.g. github.","Installation","Credentials and Access tokens","To successfully clone the git repo, the source definition must include credentials that have sufficient permissions to clone the repository.","We recommend storing a ","personal access token"," in an environment variable and using the environment variable in the source definition.","This keeps credentials out of code where they may be accidentally exposed to third parties.","Example","export MOSAIC_DOCS_CLONE_CREDENTIALS=\":\",","Configuration","| Property | Description | Required |\n","| ------------------- | -------------------------------------------------------------------------------- | -------- |\n","| modulePath | The path to the installed module (@jpmorganchase/mosaic-source-git-repo) | Yes |\n","| namespace | The scope for this source. ","| Yes |\n","| disabled | When true, content from this source is not used | No |\n","| options.credentials | Collection of URLS to make requests | Yes |\n","| options.prefixDir | The root path used in the content URL | Yes |\n","| options.subfolder | The name of the folder within the cloned repo containing the docs | Yes |\n","| options.repo | The repo URL | Yes |\n","| options.branch | The branch or tag to clone | Yes |\n","| options.extensions | Collection of file extensions that the source will look for inside the subfolder | Yes |\n","| options.remote | The name of the git remote to use. ","Defaults to origin. ","| Yes |","Example Git Repo Source Definition","\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-git-repo',\n"," namespace: 'mosaic',\n"," options: {\n"," credentials: process.env.MOSAIC_DOCS_CLONE_CREDENTIALS,\n"," prefixDir: 'mosaic',\n"," subfolder: 'docs',\n"," repo: 'https://github.com/jpmorganchase/mosaic.git',\n"," branch: 'main',\n"," extensions: ['.mdx'],\n"," remote: 'origin'\n"," }\n"," }\n"]},{"title":"HTTP Source","route":"/mosaic/configure/sources/http-source","content":["The HTTP Source is used to pull content over HTTP.","Multiple endpoints can be specified and the source will combine and transform the response from each into a single collection of pages.","Installation","Configuration","| Property | Description | Required |\n","| ------------------------------------------ | ----------------------------------------------------------------------------- | -------- |\n","| modulePath | The path to the installed module (@jpmorganchase/mosaic-source-http) | Yes |\n","| namespace | The scope for this source | Yes |\n","| disabled | When true, content from this source is not used | No |\n","| options.endpoints | Collection of URLS to make requests | Yes |\n","| options.prefixDir | The root path used in the content URL | Yes |\n","| options.transformResponseToPagesModulePath | The path of the module used to transform endpoint responses into Mosaic pages | Yes |\n","| options.checkIntervalMins | Number of minutes to wait between requests. ","Defaults to 5 minutes | No |\n","| options.initialDelayMs | Number of milliseconds to wait for making initial request. ","Defaults to 1000 | No |","Example HTTP Source Definition"," {\n"," modulePath: '@jpmorganchase/mosaic-source-http',\n"," namespace: 'my-namespace',\n"," options: {\n"," prefixDir: 'docs',\n"," endpoints: [\n"," 'https://api.data.com/blah',\n"," 'https://api.data.com/hello'\n"," ],\n"," transformResponseToPagesModulePath: '@scope/transformer-package'\n"," }\n"," }"]},{"title":"Sources","route":"/mosaic/configure/sources/index","content":["Sources are what Mosaic uses to pull content from disparate locations and merge into a single virtual filesystem that can be used by a Mosaic Site.","Depending on the ","mode"," used, sources can update periodically ensuring that new content is made available automatically.","Source Definitions","Source Definitions are specified in the "," collection of a mosaic config file.","Each source uses a ","zod schema"," to validate the provided JSON to ensure that all required information for the source to pull content has been provided.","A source definition at a minimum needs to provide the module path of the source and the ","namespace"," that it will use. ","A namespace is not unique across sources though it is common that each source has a different namespace.","Lastly, the options field can be used as a bucket for configuration values needed to configure the source e.g. credentials.","Users are free to add any property as a source option but please read the ","gotchas","\n","first regarding the allowed ","values",".","Example Local Folder Source Definition"," /**\n"," * Demonstrates a local file-system source, in this case a relative path to where the\n"," * site was generated.\n"," * Access from your browser as http://localhost:3000/local\n"," */\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-local-folder',\n"," namespace: 'local', // each site has it's own namespace, think of this as your content's uid\n"," options: {\n"," rootDir: '..","/../docs', // relative path to content\n"," prefixDir: 'local', // root path used for namespace\n"," extensions: ['.mdx'] // extensions of content which should be pulled\n"," }\n"," }","Source Namespace","A Source Namespace is a scoping mechanism for Mosaic sources used to filter the content loaded by Mosaic. ","By default all sources specified in the mosaic config file are loaded.","sources: [\n"," {\n"," namespace: 'my-namespace',\n"," modulePath: '@jpmorganchase/mosaic-source-local-folder'\n"," }\n","];","The following command will ensure mosaic only loads sources with the "," scope.","yarn mosaic serve -c ''./mosaic.config.mjs' -p 8080 --scope \"local\"","Source Schedules","Source schedules define how often sources pull in content that exists remotely and if a failed source is retried. ","More information can be found ","here","Source Types","Out of the box, Mosaic provides 3 source \"types\":","Local Folder","Git Repo Source","HTTP Source","Sources must expose an observable interface so it is possible to compose sources together e.g. the Git Repo source uses the Local Folder source internally to watch the cloned folder for changes.","Watching for Updates","When running in ","active mode",", Mosaic will watch for any changes to the source content and if a change is detected, will initiate a pull of that new content.","How often to check for updates and how updates are triggered are a matter for the source to handle. ","Mosaic simply responds when a source emits new content.","Source Worker Thread","Sources are executed inside their own worker thread to ensure that the main thread is not overloaded. ","It is here that a local virtual filesystem for the source is created and where several of the ","Plugin Lifecycle"," events are triggered.","Gotchas","A service worker thread uses ","postMessage"," to communicate with the main thread and vice-versa.","This is important because it limits what values can be provided in the source definition to those that can be processed by the ","Structured Clone Algorithm","."]},{"title":"Local Folder Source","route":"/mosaic/configure/sources/local-folder-source","content":["The Local Folder Source is used to pull content from a folder located on the same machine as Mosaic is running.","It is common to use this source when running mosaic locally.","Installation","Configuration","| Property | Description | Required |\n","| ------------------ | ------------------------------------------------------------------------------ | -------- |\n","| modulePath | The path to the installed module (@jpmorganchase/mosaic-source-local-folder) | Yes |\n","| namespace | The scope for this source | Yes |\n","| disabled | When true, content from this source is not used | No |\n","| options.rootDir | The top level directory content will be pulled from | Yes |\n","| options.prefixDir | The root path used in the content URL | Yes |\n","| options.extensions | Collection of file extensions that the source will look for inside the rootDir | Yes |","Example Local Folder Source Definition","{\n"," modulePath: '@jpmorganchase/mosaic-source-local-folder',\n"," namespace: 'local', // each site has it's own namespace, think of this as your content's uid\n"," options: {\n"," rootDir: '..","/../docs', // relative path to content\n"," prefixDir: 'local', // root path used for namespace\n"," extensions: ['.mdx'] // extensions of content which should be pulled\n"," }\n","}","This source will look for content with the \".mdx\" extension in a \"docs\" directory 2 levels up from the Mosaic working directory. ","That content is included in the \"local\" namespace and available from a route that is prefixed with \"local\".","So if you had a file, "," then you would be able to view it at ","."]},{"title":"Source Schedules","route":"/mosaic/configure/sources/schedules","content":["A source schedule defines how often a source initiates a content pull and what to do when there is a failure.","A schedule can be specified for each source in the source definition, but should a source not provide a schedule it will inherit the \"global\" schedule.","Configuration","| Property | Description | Required | Default |\n","| ----------------- | -------------------------------------------------------------------------------------- | -------- | ------- |\n","| checkIntervalMins | The length of time in minutes before triggering a content refresh | Yes | 30 mins |\n","| initialDelayMs | Startup delay for the source. ","| Yes | 1000 ms |\n","| retryEnabled | When true, failures will trigger another content pull | No | true |\n","| retryDelayMins | The interval between retries. ","This will rise exponentially on every failure. ","| No | 5 |\n","| maxRetries | Maximum number of retry attempts | No | 100 |\n","| resetOnSuccess | If true, when a source recovers and emits pages it's retry counter is returned to zero | No | true |","Global Schedule","The global schedule applies to all sources that do ","not"," provide their own schedule. ","It can be configured as a top-level property of the Mosaic config file."," schedule: {\n"," checkIntervalMins: 60,\n"," initialDelayMs: 1000,\n"," retryDelayMins: 15,\n"," maxRetries: 20\n"," }","Example","Given the config file below:"," schedule: {\n"," checkIntervalMins: 30,\n"," initialDelayMs: 1000,\n"," retryDelayMins: 5,\n"," maxRetries: 10\n"," },\n"," sources: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-git-repo',\n"," namespace: 'sourceA',\n"," options: {\n"," credentials: 'credentials',\n"," prefixDir: 'sourceA',\n"," subfolder: 'docs',\n"," repo: 'source-a-repo-url',\n"," branch: 'develop',\n"," extensions: ['.mdx'],\n"," remote: 'origin'\n"," }\n"," },\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-git-repo',\n"," namespace: 'sourceB',\n"," schedule:{\n"," checkIntervalMins: 60,\n"," initialDelayMs: 5000,\n"," retryDelayMins: 30,\n"," maxRetries: 50\n"," }\n"," options: {\n"," credentials: 'credentials',\n"," prefixDir: 'sourceB',\n"," subfolder: 'docs',\n"," repo: 'source-b-repo-url',\n"," branch: 'develop',\n"," extensions: ['.mdx'],\n"," remote: 'origin'\n"," }\n"," }\n"," ]","Source A will inherit the global schedule so it will:","Start after a 1 second delay","Pull content every 30 minutes","Retry a failed content pull after an initial 5 minute delay","Retry 10 times and if still unsuccessful, closing","Source B has its own schedule so it will:","Start after a 5 second delay","Pull content every 60 minutes","Retry a failed content pull after an initial 30 minute delay","Retry 50 times and if still unsuccessful, closing","Retry Strategy","The retry strategy that Mosaic employs is ","Exponential Backoff",". ","This is a common strategy for networking applications that aims to prevent retries from causing more harm than good.","For example, given a source schedule that has a 1 minute retry delay and will retry a maximum of 3 times then the total time spent retrying is 7 minutes:","1 minute delay then 1st retry","2 minute delay then 2nd retry","4 minute delay then 3rd (and final) retry","Total delay: 1 + 2 + 4 = 7 minutes","As you can see, the delay between retries is growing exponentially giving the content source more time to recover after each retry."]},{"title":"Figma Source","route":"/mosaic/configure/sources/source-figma","content":["The Figma source is used to pull individual design patterns from Figma projects.\n","The source subscribes to Figma project groups, then extracts from project files, tagged patterns.","A Figma pattern tag is defined within a Figma project's ",".","For each retrieved/tagged pattern, a page is created in the Mosaic file-system.\n","Additional Mosaic metadata can be added, to each created page, using ","\n","For instance we could add metadata which defines which product owns a particular pattern and then\n","group patterns based on owner.","Installation","Configuration","The Figma source is an "," and shares the same base configuration.\n","The "," prop has a default transformer which creates a page for each matching Story.","| Property | Description | Required |\n","| ---------- | --------------------------------- | -------- |\n","| prefixDir | path to store figma patterns | Yes |\n","| figmaToken | figma access token | Yes |\n","| projects | array of projects to subscribe to | Yes |\n","| endpoints | figma endpoints | Yes |","Each project is configured from the "," array.","| Property | Description | Required |\n","| ------------- | --------------------------------------------- | -------- |\n","| id | numerical id of the subscribed project group | Yes |\n","| meta | metadata to add to each of the projects pages | Yes |\n","| patternPrefix | prefix to add to all pages created | Yes |"," defined the Figma REST API endpoints.","| Property | Description | Required |\n","| ----------------- | --------------------------------------------------------- | -------- |\n","| getProject | url to return a list of projects within the project group | Yes |\n","| getFile | url to return a project file | Yes |\n","| generateThumbnail | url to generate a thumbnail for the shared Figma node | Yes |","Example Figma Source Definition","sources: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-figma',\n"," namespace: 'some-namespace',\n"," options: {\n"," proxyEndpoint: 'http://path/to/optional/proxy',\n"," prefixDir: '/some/path/to/where/you/store/pattern/pages',\n"," figmaToken: process.env.FIGMA_TOKEN,\n"," projects: [{\n"," id: 99999,\n"," patternPrefix: 'yourPrefix',\n"," meta: {\n"," tags: [ 'some-tag'],\n"," data: {\n"," owner: 'some-owner'\n"," }\n"," }\n"," }],\n"," endpoints: {\n"," getFile: 'https://api.figma.com/v1/files/:file_id?","plugin_data=shared',\n"," getProject: 'https://api.figma.com/v1/projects/:project_id/files',\n"," generateThumbnail: 'https://api.figma.com/v1/images/:project_id?","ids=:node_id'\n"," }\n"," }\n"," }\n","]"]},{"title":"Readme Source","route":"/mosaic/configure/sources/source-readme","content":["The Readme source is used to pull individual "," text files from repositories.\n","This is a lighter weight version of a Git repository resource, which just pulls a single file,\n","rather the whole contents of the repo.","For each retrieved readme, a page is created in the Mosaic file-system.\n","Additional Mosaic metadata can be added, to each created page, using ","\n","For instance we could add metadata which defines which product owns a particular "," and then\n","group this page, with others, based on owner.","Installation","Configuration","The Readme source is an "," and shares the same base configuration.","| Property | Description | Required |\n","| ----------- | --------------------- | -------- |\n","| accessToken | request access token | Yes |\n","| prefixDir | path to store pages | Yes |\n","| readme | array of readme files | Yes |","Each readme is configured from the "," array.","| Property | Description | Required |\n","| --------------- | ---------------------------- | -------- |\n","| contentTemplate | template for content of page | No |\n","| name | page name used in route | Yes |\n","| readmeUrl | url of readme | Yes |\n","| meta | metadata for page | Yes |","Example Readme Source Definition"," sources: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-readme',\n"," namespace: 'your-namespace',\n"," schedule: { checkIntervalMins: 0.25, initialDelayMs: 0 },\n"," options: {\n"," prefixDir: '/salt/community-index/readme',\n"," accessToken: 'Bearer your-access-token',\n"," readme: [\n"," {\n"," name: 'your-mosaic-page-name',\n"," readmeUrl: 'https://some/repo/url/readme.md',\n"," contentTemplate: `a template which replaces ::content:: with the content`,\n"," meta: {\n"," layout: 'DetailTechnical',\n"," title: 'Your Page Title',\n"," tags: ['your-tag-if-required'],\n"," description: 'A description for your readme'\n"," }\n"," }]\n"," }\n"," }]"]},{"title":"Storybook Source","route":"/mosaic/configure/sources/source-storybook","content":["The Storybook source is used to pull individual stories from Storybook, based on tags.","The Mosaic source will filter your Storybook's stories, based on "," or ",".","For each matching story, a page is created in the Mosaic file-system.","additional Mosaic tags can be added to each page using ","additional Mosaic metadata can be added to each page using ","This information can be used to create a dynamic index of stories from Storybook.","Installation","Configuration","The Storybook source is an "," and shares the same base configuration.\n","The "," prop has a default transformer which creates a page for each matching Story.","The "," option is an array of Storybook urls that are used as Sources.\n","Each story is matched on "," using the "," Regexp (or by ",").","If specified, "," and "," can be added to any matching pages.","| Property | Description | Required |\n","| --------------- | ---------------------- | -------- |\n","| options.stories | array of story configs | Yes |"," is an array of Storybooks that you want to pull stories from","| Property | Description | Required |\n","| -------------- | ---------------------------------------- | -------- |\n","| storyUrlPrefix | prefix url of the storybook deployment | Yes |\n","| description | description of the storybook stories | Yes |\n","| storiesUrl | url of the storybook's "," | No |\n","| filter | RegExp filter to match on | No |\n","| filterTags | Array of Storybook tags to match on | No |\n","| meta | additional data to add to matching pages | No |","Example Local Folder Source Definition","sources: [\n"," {\n"," modulePath: '@jpmorganchase/mosaic-source-storybook',\n"," namespace: 'salt',\n"," options: {\n"," prefixDir: '/salt/internal/community-index/story-navigation',\n"," stories: [\n"," {\n"," storiesUrl: 'https://storybook.saltdesignsystem.com/stories.json',\n"," storyUrlPrefix: 'https://storybook.saltdesignsystem.com',\n"," description: 'Navigation patterns created in the Salt Labs',\n"," meta: { // can be any additional metadata you want added to the page's meta.data\n"," tags: ['some-tag'],\n"," data: {\n"," owner: 'Salt',\n"," source: 'STORYBOOK'\n"," }\n"," },\n"," filter: /Lab\\/Tabs/ // this is a Regexp that matches on Storybook kind\n"," }\n"," ]\n"," }\n"," }\n","]"]},{"title":"Custom Components","route":"/mosaic/configure/theme/custom-components","content":["Learn how to add your own custom components to your Mosaic site.","Create Components Folder","To start, create a "," folder under "," where you'll store your custom components.","src/\n","└── components/","In this tutorial, we will create a custom "," component.","Create Card Component","Inside the "," folder, create a "," folder, which will contain your React "," component. ","The "," folder should include "," and "," files as shown in the structure below:","├── src/\n","│ ├── components/\n","│ │ └── card/\n","│ │ ├── index.tsx\n","│ │ └── card.module.css","Card Component: index.tsx","Create your "," component within the "," file:","import React from 'react';\n","import styles from './card.module.css';\n","\n","type CardProps = {\n"," title: string;\n"," content: string;\n","};\n","\n","export const Card: React.FC = ({ title, content }) => {\n"," return (\n","
\n","

{title}

\n","

{content}

\n","
\n"," );\n","};","Card Component: card.module.css","Define your component styles in the "," file:",".card {\n"," background-color: #f5f5f5;\n"," border: 1px solid #ccc;\n"," border-radius: 4px;\n"," box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);\n"," padding: 16px;\n"," transition: box-shadow 0.2s ease-in-out;\n","}\n","\n",".card:hover {\n"," box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);\n","}\n","\n",".card h2 {\n"," color: #333;\n"," font-size: 24px;\n"," margin-bottom: 8px;\n","}\n","\n",".card p {\n"," color: #666;\n"," font-size: 16px;\n"," line-height: 1.5;\n","}","In this example, we use a CSS file, but you can use whichever styling approach you prefer, such as ","vanilla extract",".","To export your "," component, create an "," file in the "," folder:","export * from './card';","Your final folder structure should look like this:","├── src/\n","│ ├── components/\n","│ │ ├── card/\n","│ │ │ ├── index.tsx\n","│ │ │ └── card.module.css\n","│ │ ├── index.ts","Import Custom Card Component","To use your custom "," component, import it into your site's "," file. ","Add the following line to your imports:","import * as myComponents from '../components';","Replace this line:","const components = mosaicComponents;","with:","const components = {\n"," ...mosaicComponents,\n"," ...myComponents\n","};","This will add your custom components to the site, and any custom components in "," will override the corresponding ones in ",". ","The spread operator (",") merges both "," and "," objects, giving priority to "," when there is a naming conflict.","Use Your Custom Card Component","Now you're ready to use your custom "," component. ","Build and run your site, and add the "," component to an MDX file in your "," folder or another source:","","You can create and add more custom components to your Mosaic site by following the same process."]},{"title":"Custom CSS","route":"/mosaic/configure/theme/custom-css","content":["You can customize the look and feel of your Mosaic site by creating cusotm CSS files. ","Here is a step-by-step guide to help you create your own CSS theme.","Create a CSS folder","To get started, create a folder named \"css\" in the \"src\" folder of your Mosaic project.","src/\n","└── css/","Create your theme","Inside the \"css\" folder, create a folder named \"global\". ","This is where you will add your custom styles.","src/\n","└── css/\n"," ├── global/\n"," ├── index.css","Create an \"index.css\" file inside the \"css\" folder. ","This file will import your custom styles.","@import './global/';","Inside your global folder, create a separate CSS file for each part of your site that you want to customize. ","For instance, if you want to change the text styling, create a \"text.css\" file inside the \"global\" folder. ","Here is an example of how your \"text.css\" file could look like:","h1 {\n"," /* Set custom font size and weight */\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h2 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h3 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h4 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h5 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","h6 {\n"," font-size: /* insert value */ ;\n"," font-weight: /* insert value */ ;\n","}\n","\n","p {\n"," font-size: /* insert value */ ;\n"," line-height: /* insert value */ ;\n","}","You can add as many CSS files as you need, depending on how much you want to customize your site.","Create an \"index.css\" file inside the \"global\" folder. ","This file will import your custom styles, in this example we are importing our \"text.css\" file.","@import './text.css';","Your \"css\" folder should now look like this:","src/\n","└── css/\n"," ├── global/\n"," │ ├── text.css\n"," │ ├── index.css\n"," ├── index.css","Import your custom CSS into your site","To apply your custom styles to your Mosaic site, open your \"_app.tsx\" file and add the following line to the bottom of your imports:","import '../css/index.css';","Congratulations! ","You have successfully applied your custom CSS styles to your site. ","This example demonstrated how to create text styles, but you can use the same approach to customize other aspects of your site as well."]},{"title":"Theming Your Site","route":"/mosaic/configure/theme/index","content":["Create a unique look and feel for your Mosaic site by customizing the CSS theme and integrating your own UI components.","Customize the CSS","Adapt various design elements of your Mosaic site to create a cohesive visual theme. ","Refer to our guide to learn more about crafting a custom CSS theme:","CSS Theme Guide","Import Custom Components","Incorporate your own UI components, to tailor the look and functionality of your content. ","This tutorial will walk you through the process of adding custom components to your site:","Adding Custom Components Tutorial"]},{"title":"Aliases Test","route":"/mosaic/test/aliases/index","content":["This page is the alias test page."]},{"title":"Detail Highlight Test Page","route":"/mosaic/test/layouts/detail-highlight","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Detail Overview Test Page","route":"/mosaic/test/layouts/detail-overview","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Detail Technical Test Page","route":"/mosaic/test/layouts/detail-technical","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Edit Layout","route":"/mosaic/test/layouts/edit","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Full Width Layout","route":"/mosaic/test/layouts/full-width","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Layouts","route":"/mosaic/test/layouts/index","content":["Pages for e2e testing of layouts."]},{"title":"Landing Layout Test Page","route":"/mosaic/test/layouts/landing","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Newsletter Test Page","route":"/mosaic/test/layouts/newsletter","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Product Discover Test Page","route":"/mosaic/test/layouts/product-discover","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Product Preview Test Page","route":"/mosaic/test/layouts/product-preview","content":["Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 1","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 2","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 3","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum","Heading 4","Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n","Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n","Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n","Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"]},{"title":"Refs Data","route":"/mosaic/test/refs/data","content":[]},{"title":"Refs Test","route":"/mosaic/test/refs/index","content":["The sidebar priority is ",".","The other page data is ","."]},{"title":"Tags Test","route":"/mosaic/test/tags/index","content":["In Stock","Out of Stock"]},{"title":"$afterSource","route":"/mosaic/configure/plugins/lifecycle/after-source","content":["The first lifecycle event to trigger after receiving pages from a source and runs in a child process.\n","The pages can safely be mutated and will be reflected in the final filesystem that gets generated.\n","It ","must"," return a collection of pages.","The "," lifecycle event is called with:","pages - the collection of pages emitted by the source","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | A mutable object for sharing data with other lifecycle phases of all plugins for this source (including in the main thread) in this plugin |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |","Example - Log out all page routes","async function $afterSource(pages, { config, ignorePages, pageExtensions }) {\n"," for (const page of pages) {\n"," console.log(page.route);\n"," }\n"," return pages;\n","}"]},{"title":"afterUpdate","route":"/mosaic/configure/plugins/lifecycle/after-update","content":["The third lifecycle event to trigger overall and the first to trigger inside the main Mosaic process.","Calls after the filesystem and symlinks have been reconstructed due to a change to the current source pages. ","Pages will ","not"," be cached when read at this stage, to allow for reading content and writing a new copy of it without the cached version taking effect.\n","This method is safe to use with lazy loading, as the filesystem should return the full page when read.","The "," lifecycle event is called with:","mutableFilesystem - Mutable filesystem instance with all of this source's pages inside (and symlinks re-applied)","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin. ","Shared only with this source. ","|\n","| globalConfig | An immutable object for reading data from other lifecycle phases of all plugins. ","Shared across all sources. ","|\n","| sharedFilesystem | Mutable filesystem instance independent of any sources. ","Useful for global pages, like sitemaps |\n","| globalFilesystem | Immutable union filesystem instance with all source's pages (and symlinks applied) |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |"]},{"title":"$beforeSend","route":"/mosaic/configure/plugins/lifecycle/before-send","content":["The second lifecycle event to trigger and does so after a filesystem has been built up from the source pages.","It is the last lifecycle event to run in a source child process before the filesystem is sent to the main Mosaic process and should ","not"," return a value.","The "," lifecycle event is called with:","mutableFilesystem - Mutable virtual filesystem instance with all of this source's pages inside (and symlinks applied)","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | A mutable object for sharing data with other lifecycle phases of all plugins for this source (including in the main thread) in this plugin |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |"]},{"title":"Lifecycle Events","route":"/mosaic/configure/plugins/lifecycle/index","content":["Plugin lifecycle","The plugin lifecycle is triggered when a source emits content.","Each Mosaic source has its own worker thread and plugin lifecycle events that start with a "," will execute inside the worker thread.\n","All other lifecycle events will execute in the main Mosaic process.","The 5 lifecycle events are:","$afterSource","$beforeSend","afterUpdate","shouldClearCache","shouldUpdateNamespaceSources","Plugin methods that trigger inside the main thread should be asynchronous and highly optimised to\n","avoid holding up the main thread."]},{"title":"shouldClearCache","route":"/mosaic/configure/plugins/lifecycle/should-clear-cache","content":["The fourth lifecycle event to trigger overall and the second to trigger inside the main Mosaic process.","It is called every time ","any"," source emits new pages and should return a boolean to indicate if ","other"," sources should clear their cache in response to the source updating.","Only sources that have already run "," will call this lifecycle hook since there is no\n","cache to clear if they haven't reached that stage in the lifecycle.","The "," lifecycle event is called with:","updatedSourceFilesystem - Immutable filesystem for the source that changed i.e, not the source filesystem","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin. ","Shared only with this source. ","|\n","| globalFilesystem | Immutable union filesystem instance with all source's pages (and symlinks applied) |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |"]},{"title":"shouldUpdateNamespaceSources","route":"/mosaic/configure/plugins/lifecycle/should-update-namespace-sources","content":["The fifth lifecycle event to trigger overall and the third to trigger inside the main Mosaic process.","It is called every time ","any"," source emits new pages and should return a boolean to indicate if ","other sources that share the same ","source namespace"," should re-run ",".","The "," lifecycle event is called with:","updatedSourceFilesystem - Immutable filesystem for the source that changed i.e, not the source filesystem","helpers - an object with useful methods","options - the options specified for the plugin in the mosaic config file","Helpers","The helpers provided with this lifecycle event are listed in the table below.","| Property | Description |\n","| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n","| serialiser | A matching "," for serialising/deserialising pages when reading/writing to the filesystem |\n","| config | An immutable object for reading data from other lifecycle phases of all plugins for this source in the child process for this plugin. ","Shared only with this source. ","|\n","| globalFilesystem | Immutable union filesystem instance with all source's pages (and symlinks applied) |\n","| pageExtensions | A collection of pageExtensions the source is using |\n","| ignorePages | A collection of page globs that are to be ignored for this source |\n","| namespace | The namespace of the source running the plugin |"]}] \ No newline at end of file diff --git a/packages/site/public/sitemap.xml b/packages/site/public/sitemap.xml index a4068ccda..ce0967af2 100644 --- a/packages/site/public/sitemap.xml +++ b/packages/site/public/sitemap.xml @@ -408,15 +408,6 @@ https://mosaic-mosaic-dev-team.vercel.app/mosaic/configure/plugins/lifecycle/should-update-namespace-sources weekly 0.5 - , - https://mosaic-mosaic-dev-team.vercel.app/mosaic/products/producta - weekly - 0.5 - - - https://mosaic-mosaic-dev-team.vercel.app/mosaic/products/productb - weekly - 0.5 \ No newline at end of file diff --git a/packages/sitemap-component/package.json b/packages/sitemap-component/package.json index 42dc84550..7e0d73f1e 100644 --- a/packages/sitemap-component/package.json +++ b/packages/sitemap-component/package.json @@ -44,8 +44,7 @@ }, "dependencies": { "@jpmorganchase/mosaic-components": "^0.1.0-beta.78", - "@salt-ds/core": "^1.26.0", - "@salt-ds/lab": "1.0.0-alpha.42", + "@salt-ds/core": "^1.30.0", "d3": "^7.7.0" }, "peerDependencies": { diff --git a/packages/sitemap-component/src/SitemapToolbar.tsx b/packages/sitemap-component/src/SitemapToolbar.tsx index 6f0f36905..bc0a3eb3c 100644 --- a/packages/sitemap-component/src/SitemapToolbar.tsx +++ b/packages/sitemap-component/src/SitemapToolbar.tsx @@ -1,5 +1,5 @@ -import React, { useState } from 'react'; -import { Dropdown, DropdownButton, SelectionChangeHandler } from '@salt-ds/lab'; +import React, { SyntheticEvent } from 'react'; +import { Dropdown, Option } from '@salt-ds/core'; import { useToolbarDispatch, useToolbarState, @@ -39,8 +39,7 @@ export const SitemapToolbar: React.FC = ({ }: SitemapToolbarProps) => { const dispatch = useToolbarDispatch(); const { filters = [] } = useToolbarState(); - const [isOpen, setIsOpen] = useState(false); - const handleSelect: SelectionChangeHandler = (_e, selectedItems) => + const handleSelect = (_e: SyntheticEvent, selectedItems: string[]) => dispatch({ type: 'setFilters', value: selectedItems }); return ( @@ -49,23 +48,23 @@ export const SitemapToolbar: React.FC = ({ <> Number of pages: {pageCount} {namespaces?.length >= 1 ? ( - - aria-label={isOpen ? 'close filters menu' : 'open filters menu'} + } + value={defaultButtonLabel(filters)} + aria-label="Filters" className={styles.filterDropdown} - onOpenChange={setIsOpen} onSelectionChange={handleSelect} selected={filters} - selectionStrategy="multiple" - source={namespaces} - triggerComponent={ - - - - - } - width={200} + multiselect + style={{ width: 200 }} {...rest} - /> + > + {namespaces.map(namespace => ( + + ))} + ) : null} ) : null} diff --git a/packages/theme/package.json b/packages/theme/package.json index e4d75cb43..4609aa207 100644 --- a/packages/theme/package.json +++ b/packages/theme/package.json @@ -41,7 +41,7 @@ "fast-glob": "^3.2.7" }, "dependencies": { - "@salt-ds/icons": "^1.11.1", + "@salt-ds/icons": "^1.12.1", "@vanilla-extract/css": "^1.6.0", "@vanilla-extract/css-utils": "^0.1.1", "@vanilla-extract/sprinkles": "^1.3.0", diff --git a/packages/theme/types/saltIconNames.d.ts b/packages/theme/types/saltIconNames.d.ts index 66cee6d96..6dcee52a5 100644 --- a/packages/theme/types/saltIconNames.d.ts +++ b/packages/theme/types/saltIconNames.d.ts @@ -205,6 +205,7 @@ export type saltIconNames = | 'marker' | 'markerSolid' | 'maximize' + | 'maximizeSolid' | 'medicalKit' | 'medicalKitSolid' | 'menu' @@ -318,6 +319,8 @@ export type saltIconNames = | 'sortNumDescend' | 'sortableAlpha' | 'sortableNum' + | 'sparkle' + | 'sparkleSolid' | 'stackoverflow' | 'stepActive' | 'stepDefault' diff --git a/yarn.lock b/yarn.lock index 985f1f942..4d343cc28 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1877,29 +1877,38 @@ fastify-plugin "^4.0.0" ws "^8.0.0" -"@floating-ui/core@^1.5.3": - version "1.5.3" - resolved "https://registry.yarnpkg.com/@floating-ui/core/-/core-1.5.3.tgz#b6aa0827708d70971c8679a16cf680a515b8a52a" - integrity sha512-O0WKDOo0yhJuugCx6trZQj5jVJ9yR0ystG2JaNAemYUWce+pmM6WUEFIibnWyEJKdrDxhm75NoSRME35FNaM/Q== +"@floating-ui/core@^1.0.0": + version "1.6.3" + resolved "https://registry.yarnpkg.com/@floating-ui/core/-/core-1.6.3.tgz#5e7bb92843f47fd1d8dcb9b3cc3c243aaed54f95" + integrity sha512-1ZpCvYf788/ZXOhRQGFxnYQOVgeU+pi0i+d0Ow34La7qjIXETi6RNswGVKkA6KcDO8/+Ysu2E/CeUmmeEBDvTg== dependencies: - "@floating-ui/utils" "^0.2.0" + "@floating-ui/utils" "^0.2.3" -"@floating-ui/dom@^1.5.4": - version "1.5.4" - resolved "https://registry.yarnpkg.com/@floating-ui/dom/-/dom-1.5.4.tgz#28df1e1cb373884224a463235c218dcbd81a16bb" - integrity sha512-jByEsHIY+eEdCjnTVu+E3ephzTOzkQ8hgUfGwos+bg7NlH33Zc5uO+QHz1mrQUOgIKKDD1RtS201P9NvAfq3XQ== +"@floating-ui/dom@^1.0.0": + version "1.6.6" + resolved "https://registry.yarnpkg.com/@floating-ui/dom/-/dom-1.6.6.tgz#be54c1ab2d19112ad323e63dbeb08185fed0ffd3" + integrity sha512-qiTYajAnh3P+38kECeffMSQgbvXty2VB6rS+42iWR4FPIlZjLK84E9qtLnMTLIpPz2znD/TaFqaiavMUrS+Hcw== dependencies: - "@floating-ui/core" "^1.5.3" - "@floating-ui/utils" "^0.2.0" + "@floating-ui/core" "^1.0.0" + "@floating-ui/utils" "^0.2.3" -"@floating-ui/react-dom@^2.0.6": - version "2.0.6" - resolved "https://registry.yarnpkg.com/@floating-ui/react-dom/-/react-dom-2.0.6.tgz#5ffcf40b6550817a973b54cdd443374f51ca7a5c" - integrity sha512-IB8aCRFxr8nFkdYZgH+Otd9EVQPJoynxeFRGTB8voPoZMRWo8XjYuCRgpI1btvuKY69XMiLnW+ym7zoBHM90Rw== +"@floating-ui/react-dom@^2.0.6", "@floating-ui/react-dom@^2.1.0": + version "2.1.1" + resolved "https://registry.yarnpkg.com/@floating-ui/react-dom/-/react-dom-2.1.1.tgz#cca58b6b04fc92b4c39288252e285e0422291fb0" + integrity sha512-4h84MJt3CHrtG18mGsXuLCHMrug49d7DFkU0RMIyshRveBeyV2hmV/pDaF2Uxtu8kgq5r46llp5E5FQiR0K2Yg== dependencies: - "@floating-ui/dom" "^1.5.4" + "@floating-ui/dom" "^1.0.0" -"@floating-ui/react@^0.26.5", "@floating-ui/react@^0.26.6": +"@floating-ui/react@^0.26.5": + version "0.26.18" + resolved "https://registry.yarnpkg.com/@floating-ui/react/-/react-0.26.18.tgz#4231c9e76a88212524fce783007ca7fc3e7630fa" + integrity sha512-enDDX09Jpi3kmhcXXpvs+fvRXOfBj1jUV2KF6uDMf5HjS+SOZJzNTFUW71lKbFcxz0BkmQqwbvqdmHIxMq/fyQ== + dependencies: + "@floating-ui/react-dom" "^2.1.0" + "@floating-ui/utils" "^0.2.3" + tabbable "^6.0.0" + +"@floating-ui/react@^0.26.6": version "0.26.6" resolved "https://registry.yarnpkg.com/@floating-ui/react/-/react-0.26.6.tgz#34c58aacb5efe46633a7c9bf87c90c027d7bfafd" integrity sha512-FFDAuSlRwb8CY4/VvYio/wwk/0339B257yRpKwNOjcHWNYL/fgjl1KUvT3K6ZZ4WDbBWYc7Km4ITMuPZrS8omg== @@ -1908,10 +1917,10 @@ "@floating-ui/utils" "^0.2.1" tabbable "^6.0.1" -"@floating-ui/utils@^0.2.0", "@floating-ui/utils@^0.2.1": - version "0.2.1" - resolved "https://registry.yarnpkg.com/@floating-ui/utils/-/utils-0.2.1.tgz#16308cea045f0fc777b6ff20a9f25474dd8293d2" - integrity sha512-9TANp6GPoMtYzQdt54kfAyMmz1+osLlXdg2ENroU7zzrtflTLrrC/lgrIfaSe+Wu0b89GKccT7vxXA0MoAIO+Q== +"@floating-ui/utils@^0.2.1", "@floating-ui/utils@^0.2.3": + version "0.2.3" + resolved "https://registry.yarnpkg.com/@floating-ui/utils/-/utils-0.2.3.tgz#506fcc73f730affd093044cb2956c31ba6431545" + integrity sha512-XGndio0l5/Gvd6CLIABvsav9HHezgDFFhDfHk1bvLfr9ni8dojqLSvBbotJEjmIwNHL7vK4QzBJTdBRoB+c1ww== "@fluentui/keyboard-keys@^9.0.3": version "9.0.3" @@ -2717,36 +2726,36 @@ resolved "https://registry.yarnpkg.com/@rushstack/eslint-patch/-/eslint-patch-1.2.0.tgz#8be36a1f66f3265389e90b5f9c9962146758f728" integrity sha512-sXo/qW2/pAcmT43VoRKOJbDOfV3cYpq3szSVfIThQXNt+E4DfKj361vaAt3c88U5tPUxzEswam7GW48PJqtKAg== -"@salt-ds/core@^1.26.0": - version "1.26.0" - resolved "https://registry.yarnpkg.com/@salt-ds/core/-/core-1.26.0.tgz#fcffa2a5ae7bd618bab828a77ecb73c3a66af954" - integrity sha512-HSi5kZwZkB4xnsCYqQlf6zXilxWaxEFErJGT9DT6nUHVEawxxXdiNSgoY2qtr32EnkX9Sq4SN85l9xsv/Cmdwg== +"@salt-ds/core@^1.30.0": + version "1.30.0" + resolved "https://registry.yarnpkg.com/@salt-ds/core/-/core-1.30.0.tgz#50f28e21f0472e3432a6486dd3de6bfb10b50dfb" + integrity sha512-tPh4ho2/SjeVApNbmpAOCBj0gJoL9dgN1MvbbsbZitLxVauO+/fIv+XcjkDQjhH2tRp52IRH7uV9lR5lcup19g== dependencies: "@floating-ui/react" "^0.26.5" - "@salt-ds/icons" "^1.11.1" + "@salt-ds/icons" "^1.12.1" "@salt-ds/styles" "^0.2.1" "@salt-ds/window" "^0.1.1" clsx "^2.0.0" -"@salt-ds/icons@^1.11.1": - version "1.11.1" - resolved "https://registry.yarnpkg.com/@salt-ds/icons/-/icons-1.11.1.tgz#63117df11092f02c987114409e44162435fc9f26" - integrity sha512-7p32dONrzuObIkkiBlmFx4ptdDJxYbuQbkzVTqgo+vtSyU17BbwlQ1gMnu15ry7B3NpnMBFsFJ9ybSHZE/ljTA== +"@salt-ds/icons@^1.12.1": + version "1.12.1" + resolved "https://registry.yarnpkg.com/@salt-ds/icons/-/icons-1.12.1.tgz#817844b1102ae8b2c90bf1bae632de02a684ffd4" + integrity sha512-YSFBXEh+knGLWFVMoYqnQMUgWKyJk8CcsiW6OPCS4f4IEkT8p/CoSkgnK5gMe01m6DtL6Cby++IXCSZbMzQwmw== dependencies: "@salt-ds/styles" "^0.2.1" "@salt-ds/window" "^0.1.1" clsx "^2.0.0" -"@salt-ds/lab@1.0.0-alpha.42": - version "1.0.0-alpha.42" - resolved "https://registry.yarnpkg.com/@salt-ds/lab/-/lab-1.0.0-alpha.42.tgz#5af644076f5cab7e42b48269881f2b60a9f25173" - integrity sha512-4Yo6Mz2/oI5y2QmmDZ6+Hy3EcAqM9yOgeLjJ47lMbijoYujyTC6OfsbXzd13zT7IyLbQzLKT1XW87Yn/jY6kcw== +"@salt-ds/lab@1.0.0-alpha.48": + version "1.0.0-alpha.48" + resolved "https://registry.yarnpkg.com/@salt-ds/lab/-/lab-1.0.0-alpha.48.tgz#6ba1596c112d40531aa6c074d9a075e5c4c74671" + integrity sha512-yKXxWNNigeYwSEYTwFxcIIyR0F2ElBRt1QF0ZrXi6z+OP0EXBQhaYbgoggtiNYluVwRaaH72CrapuljrPRfgJg== dependencies: "@floating-ui/react" "^0.26.5" "@fluentui/react-overflow" "^9.0.19" "@internationalized/date" "^3.0.0" - "@salt-ds/core" "^1.26.0" - "@salt-ds/icons" "^1.11.1" + "@salt-ds/core" "^1.30.0" + "@salt-ds/icons" "^1.12.1" "@salt-ds/styles" "^0.2.1" "@salt-ds/window" "^0.1.1" "@types/react-window" "^1.8.2" @@ -2767,10 +2776,10 @@ resolved "https://registry.yarnpkg.com/@salt-ds/styles/-/styles-0.2.1.tgz#d6fc1bee5a8d3931cba4ec8baa14f1ad3d7582a4" integrity sha512-/GYQLY+ILzGyd2/KndCmoEfLw/t3pcYwihJn3ofe4yd6nhLYHPkvl4TXXzq6NnfD3NHmQWnWh3jQicLsYcvdXg== -"@salt-ds/theme@^1.14.0": - version "1.14.0" - resolved "https://registry.yarnpkg.com/@salt-ds/theme/-/theme-1.14.0.tgz#a1ff0fad19442b345254ac88f8a29499ce0dce10" - integrity sha512-q7f+9PeQLc3DrnniWNPY4bAXHBzuOuYNRG4IeDGxGuh3rDYwqj2gmASSqka7kZdVp/T39B/nFvsLXXums/pPjQ== +"@salt-ds/theme@^1.19.0": + version "1.19.0" + resolved "https://registry.yarnpkg.com/@salt-ds/theme/-/theme-1.19.0.tgz#aa619fe1e1248a3780b87d4341f4496bfb5fe84f" + integrity sha512-POe6ca1cHCQe3ehBrSdG79pKB+Zg0EAsNE4D292xxoSpoRSR0I6EtWQ8KM+nrscuZNu0FXHG9rLh8/y9zVBWcg== "@salt-ds/window@^0.1.1": version "0.1.1" @@ -4865,9 +4874,9 @@ clone@^1.0.2: integrity sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg== clsx@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/clsx/-/clsx-2.0.0.tgz#12658f3fd98fafe62075595a5c30e43d18f3d00b" - integrity sha512-rQ1+kcj+ttHG0MKVGBUXwayCCF1oh39BF5COIpRzuCEv8Mwjv0XucrI2ExNTOn9IlLifGClWQcU9BrZORvtw6Q== + version "2.1.1" + resolved "https://registry.yarnpkg.com/clsx/-/clsx-2.1.1.tgz#eed397c9fd8bd882bfb18deab7102049a2f32999" + integrity sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA== co@^4.6.0: version "4.6.0" @@ -12515,10 +12524,10 @@ symbol-tree@^3.2.4: resolved "https://registry.yarnpkg.com/symbol-tree/-/symbol-tree-3.2.4.tgz#430637d248ba77e078883951fb9aa0eed7c63fa2" integrity sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw== -tabbable@^6.0.1: - version "6.1.2" - resolved "https://registry.yarnpkg.com/tabbable/-/tabbable-6.1.2.tgz#b0d3ca81d582d48a80f71b267d1434b1469a3703" - integrity sha512-qCN98uP7i9z0fIS4amQ5zbGBOq+OSigYeGvPy7NDk8Y9yncqDZ9pRPgfsc2PJIVM9RrJj7GIfuRgmjoUU9zTHQ== +tabbable@^6.0.0, tabbable@^6.0.1: + version "6.2.0" + resolved "https://registry.yarnpkg.com/tabbable/-/tabbable-6.2.0.tgz#732fb62bc0175cfcec257330be187dcfba1f3b97" + integrity sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew== table@^6.0.9: version "6.8.0"