Merge branch 'master' into experimentalHeaderNavigation

2026-01-06 05:42:40 +00:00 · 2025-01-03 11:20:16 +13:00
parent df5ed5190a b20eb28a37
commit 6b0c3b65b4
135 changed files with 7958 additions and 5067 deletions
--- a/client/homebrew/brewRenderer/brewRenderer.jsx
+++ b/client/homebrew/brewRenderer/brewRenderer.jsx
@@ -1,11 +1,11 @@
 /*eslint max-lines: ["warn", {"max": 300, "skipBlankLines": true, "skipComments": true}]*/
 require('./brewRenderer.less');
 const React = require('react');
-const { useState, useRef, useEffect } = React;
+const { useState, useRef, useMemo, useEffect } = React;
 const _ = require('lodash');

 const MarkdownLegacy = require('naturalcrit/markdownLegacy.js');
-const Markdown = require('naturalcrit/markdown.js');
+import Markdown from 'naturalcrit/markdown.js';
 const ErrorBar = require('./errorBar/errorBar.jsx');
 const ToolBar  = require('./toolBar/toolBar.jsx');

@@ -18,8 +18,8 @@ const { printCurrentBrew } = require('../../../shared/helpers.js');

 import HeaderNav from './headerNav/headerNav.jsx';

-const DOMPurify = require('dompurify');
-const purifyConfig = { FORCE_BODY: true, SANITIZE_DOM: false };
+import { safeHTML } from './safeHTML.js';
+

 const PAGE_HEIGHT = 1056;

@@ -31,6 +31,7 @@ const INITIAL_CONTENT = dedent`
 	<base target=_blank>
 	</head><body style='overflow: hidden'><div></div></body></html>`;

+
 //v=====----------------------< Brew Page Component >---------------------=====v//
 const BrewPage = (props)=>{
 	props = {
@@ -38,38 +39,84 @@ const BrewPage = (props)=>{
 		index    : 0,
 		...props
 	};
-	const cleanText = props.contents; //DOMPurify.sanitize(props.contents, purifyConfig);
-	return <div className={props.className} id={`p${props.index + 1}`} >
+	const pageRef = useRef(null);
+	const cleanText = safeHTML(props.contents);
+
+	useEffect(()=>{
+		if(!pageRef.current) return;
+
+		// Observer for tracking pages within the `.pages` div
+		const visibleObserver = new IntersectionObserver(
+			(entries)=>{
+				entries.forEach((entry)=>{
+					if(entry.isIntersecting)
+						props.onVisibilityChange(props.index + 1, true, false); // add page to array of visible pages.
+					else
+						props.onVisibilityChange(props.index + 1, false, false);
+				}
+			)},
+			{ threshold: .3, rootMargin: '0px 0px 0px 0px'  } // detect when >30% of page is within bounds.
+		);
+
+		// Observer for tracking the page at the center of the iframe.
+		const centerObserver = new IntersectionObserver(
+			(entries)=>{
+				entries.forEach((entry)=>{
+					if(entry.isIntersecting)
+						props.onVisibilityChange(props.index + 1, true, true); // Set this page as the center page
+				}
+			)},
+			{ threshold: 0, rootMargin: '-50% 0px -50% 0px' } // Detect when the page is at the center
+		);
+
+		// attach observers to each `.page`
+		visibleObserver.observe(pageRef.current);
+		centerObserver.observe(pageRef.current);
+		return ()=>{
+			visibleObserver.disconnect();
+			centerObserver.disconnect();
+		};
+	}, []);
+
+	return <div className={props.className} id={`p${props.index + 1}`} data-index={props.index} ref={pageRef} style={props.style}>
 	         <div className='columnWrapper' dangerouslySetInnerHTML={{ __html: cleanText }} />
 	       </div>;
 };


 //v=====--------------------< Brew Renderer Component >-------------------=====v//
-const renderedPages = [];
+let renderedPages = [];
 let rawPages      = [];

 const BrewRenderer = (props)=>{
 	props = {
-		text              : '',
-		style             : '',
-		renderer          : 'legacy',
-		theme             : '5ePHB',
-		lang              : '',
-		errors            : [],
-		currentEditorPage : 0,
-		showHeaderNav     : false,
-		themeBundle       : {},
+		text                       : '',
+		style                      : '',
+		renderer                   : 'legacy',
+		theme                      : '5ePHB',
+		lang                       : '',
+		errors                     : [],
+		currentEditorCursorPageNum : 1,
+		currentEditorViewPageNum   : 1,
+		currentBrewRendererPageNum : 1,
+		themeBundle                : {},
+		onPageChange               : ()=>{},
+    showHeavderNav             : false,
 		...props
 	};

 	const [state, setState] = useState({
-		viewablePageNumber : 0,
-		height             : PAGE_HEIGHT,
-		isMounted          : false,
-		visibility         : 'hidden',
-		zoom               : 100,
-		currentPageNumber  : 1,
+		isMounted    : false,
+		visibility   : 'hidden',
+		visiblePages : [],
+		centerPage   : 1
+	});
+
+	const [displayOptions, setDisplayOptions] = useState({
+		zoomLevel    : 100,
+		spread       : 'single',
+		startOnRight : true,
+		pageShadows  : true
 	});

 	const mainRef  = useRef(null);
@@ -81,36 +128,31 @@ const BrewRenderer = (props)=>{
 		rawPages = props.text.split(/^\\page$/gm);
 	}

-	useEffect(()=>{ // Unmounting steps
-		return ()=>{window.removeEventListener('resize', updateSize);};
-	}, []);
+	const handlePageVisibilityChange = (pageNum, isVisible, isCenter)=>{
+		setState((prevState)=>{
+			const updatedVisiblePages = new Set(prevState.visiblePages);
+			if(!isCenter)
+				isVisible ? updatedVisiblePages.add(pageNum) : updatedVisiblePages.delete(pageNum);

-	const updateSize = ()=>{
-		setState((prevState)=>({
-			...prevState,
-			height : mainRef.current.parentNode.clientHeight,
-		}));
-	};
+			return {
+				...prevState,
+				visiblePages : [...updatedVisiblePages].sort((a, b)=>a - b),
+				centerPage   : isCenter ? pageNum : prevState.centerPage
+			};
+		});

-	const getCurrentPage = (e)=>{
-		const { scrollTop, clientHeight, scrollHeight } = e.target;
-		const totalScrollableHeight = scrollHeight - clientHeight;
-		const currentPageNumber = Math.ceil((scrollTop / totalScrollableHeight) * rawPages.length);
-
-		setState((prevState)=>({
-			...prevState,
-			currentPageNumber : currentPageNumber || 1
-		}));
+		if(isCenter)
+			props.onPageChange(pageNum);
 	};

 	const isInView = (index)=>{
 		if(!state.isMounted)
 			return false;

-		if(index == props.currentEditorPage)	//Already rendered before this step
+		if(index == props.currentEditorCursorPageNum - 1)	//Already rendered before this step
 			return false;

-		if(Math.abs(index - state.currentPageNumber) <= 3)
+		if(Math.abs(index - props.currentBrewRendererPageNum - 1) <= 3)
 			return true;

 		return false;
@@ -123,19 +165,27 @@ const BrewRenderer = (props)=>{
 	};

 	const renderStyle = ()=>{
-		const cleanStyle = props.style; //DOMPurify.sanitize(props.style, purifyConfig);
 		const themeStyles = props.themeBundle?.joinedStyles ?? '<style>@import url("/themes/V3/Blank/style.css");</style>';
-		return <div style={{ display: 'none' }} dangerouslySetInnerHTML={{ __html: `${themeStyles} \n\n <style> ${cleanStyle} </style>` }} />;
+		const cleanStyle = safeHTML(`${themeStyles} \n\n <style> ${props.style} </style>`);
+		return <div style={{ display: 'none' }} dangerouslySetInnerHTML={{ __html: cleanStyle }} />;
 	};

 	const renderPage = (pageText, index)=>{
+
+		const styles = {
+			...(!displayOptions.pageShadows ? { boxShadow: 'none' } : {})
+			// Add more conditions as needed
+		};
+
 		if(props.renderer == 'legacy') {
 			const html = MarkdownLegacy.render(pageText);
-			return <BrewPage className='page phb' index={index} key={index} contents={html} />;
+
+			return <BrewPage className='page phb' index={index} key={index} contents={html} style={styles} onVisibilityChange={handlePageVisibilityChange} />;
 		} else {
 			pageText += `\n\n&nbsp;\n\\column\n&nbsp;`; //Artificial column break at page end to emulate column-fill:auto (until `wide` is used, when column-fill:balance will reappear)
 			const html = Markdown.render(pageText, index);
-			return <BrewPage className='page' index={index} key={index} contents={html} />;
+
+			return <BrewPage className='page' index={index} key={index} contents={html} style={styles} onVisibilityChange={handlePageVisibilityChange} />;
 		}
 	};

@@ -147,7 +197,8 @@ const BrewRenderer = (props)=>{
 			renderedPages.length = 0;

 		// Render currently-edited page first so cross-page effects (variables, links) can propagate out first
-		renderedPages[props.currentEditorPage] = renderPage(rawPages[props.currentEditorPage], props.currentEditorPage);
+		if(rawPages.length > props.currentEditorCursorPageNum -1)
+			renderedPages[props.currentEditorCursorPageNum - 1] = renderPage(rawPages[props.currentEditorCursorPageNum - 1], props.currentEditorCursorPageNum - 1);

 		_.forEach(rawPages, (page, index)=>{
 			if((isInView(index) || !renderedPages[index]) && typeof window !== 'undefined'){
@@ -167,10 +218,30 @@ const BrewRenderer = (props)=>{
 		}
 	};

+	const scrollToHash = (hash)=>{
+		if(!hash) return;
+
+		const iframeDoc = document.getElementById('BrewRenderer').contentDocument;
+		let anchor = iframeDoc.querySelector(hash);
+
+		if(anchor) {
+			anchor.scrollIntoView({ behavior: 'smooth' });
+		} else {
+			// Use MutationObserver to wait for the element if it's not immediately available
+			new MutationObserver((mutations, obs)=>{
+				anchor = iframeDoc.querySelector(hash);
+				if(anchor) {
+					anchor.scrollIntoView({ behavior: 'smooth' });
+					obs.disconnect();
+				}
+			}).observe(iframeDoc, { childList: true, subtree: true });
+		}
+	};
+
 	const frameDidMount = ()=>{	//This triggers when iFrame finishes internal "componentDidMount"
+		scrollToHash(window.location.hash);
+
 		setTimeout(()=>{	//We still see a flicker where the style isn't applied yet, so wait 100ms before showing iFrame
-			updateSize();
-			window.addEventListener('resize', updateSize);
 			renderPages(); //Make sure page is renderable before showing
 			setState((prevState)=>({
 				...prevState,
@@ -185,19 +256,30 @@ const BrewRenderer = (props)=>{
 		document.dispatchEvent(new MouseEvent('click'));
 	};

-	//Toolbar settings:
-	const handleZoom = (newZoom)=>{
-		setState((prevState)=>({
-			...prevState,
-			zoom : newZoom
-		}));
+	const handleDisplayOptionsChange = (newDisplayOptions)=>{
+		setDisplayOptions(newDisplayOptions);
 	};

+	const pagesStyle = {
+		zoom      : `${displayOptions.zoomLevel}%`,
+		columnGap : `${displayOptions.columnGap}px`,
+		rowGap    : `${displayOptions.rowGap}px`
+	};
+
+	const styleObject = {};
+
+	if(global.config.deployment) {
+		styleObject.backgroundImage = `url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' version='1.1' height='40px' width='200px'><text x='0' y='15' fill='%23fff7' font-size='20'>${global.config.deployment}</text></svg>")`;
+	}
+
+	const renderedStyle = useMemo(()=>renderStyle(), [props.style, props.themeBundle]);
+	renderedPages = useMemo(()=>renderPages(), [props.text, displayOptions]);
+
 	return (
 		<>
 			{/*render dummy page while iFrame is mounting.*/}
 			{!state.isMounted
-				? <div className='brewRenderer' onScroll={getCurrentPage}>
+				? <div className='brewRenderer'>
 					<div className='pages'>
 						{renderDummyPage(1)}
 					</div>
@@ -210,7 +292,7 @@ const BrewRenderer = (props)=>{
 				<NotificationPopup />
 			</div>

-			<ToolBar onZoomChange={handleZoom} currentPage={state.currentPageNumber}  totalPages={rawPages.length}/>
+			<ToolBar displayOptions={displayOptions} onDisplayOptionsChange={handleDisplayOptionsChange} visiblePages={state.visiblePages.length > 0 ? state.visiblePages : [state.centerPage]} totalPages={rawPages.length}/>

 			{/*render in iFrame so broken code doesn't crash the site.*/}
 			<Frame id='BrewRenderer' initialContent={INITIAL_CONTENT}
@@ -218,19 +300,19 @@ const BrewRenderer = (props)=>{
 				contentDidMount={frameDidMount}
 				onClick={()=>{emitClick();}}
 			>
-				<div className={'brewRenderer'}
-					onScroll={getCurrentPage}
+				<div className={`brewRenderer ${global.config.deployment && 'deployment'}`}
 					onKeyDown={handleControlKeys}
 					tabIndex={-1}
-					style={{ height: state.height }}>
+					style={ styleObject }
+				>

 					{/* Apply CSS from Style tab and render pages from Markdown tab */}
 					{state.isMounted
 						&&
 						<>
-							{renderStyle()}
-							<div className='pages' lang={`${props.lang || 'en'}`} ref={pagesRef} style={{ zoom: `${state.zoom}%` }}>
-								{renderPages()}
+							{renderedStyle}
+							<div className={`pages ${displayOptions.startOnRight ? 'recto' : 'verso'}	${displayOptions.spread}`} lang={`${props.lang || 'en'}`} style={pagesStyle}>
+								{renderedPages}
 							</div>
 						</>
 					}
--- a/client/homebrew/brewRenderer/brewRenderer.less
+++ b/client/homebrew/brewRenderer/brewRenderer.less
@@ -3,8 +3,45 @@
 .brewRenderer {
 	overflow-y    : scroll;
 	will-change   : transform;
+	padding-top   : 60px;
+	height        : 100vh;
+	&:has(.facing, .flow) {
+		padding : 60px 30px;
+	}
+	&.deployment {
+		background-color: darkred;
+	}
 	:where(.pages) {
-		margin : 30px 0px;
+		&.facing {
+			display: grid; 
+			grid-template-columns: repeat(2, auto); 
+			grid-template-rows: repeat(3, auto); 
+			gap: 10px 10px; 
+			justify-content: safe center;
+			&.recto .page:first-child {
+				// sets first page on 'right' ('recto') of the preview, as if for a Cover page.  
+				// todo: add a checkbox to toggle this setting
+				grid-column-start: 2; 
+			}
+			& :where(.page) {
+				margin-left: unset !important;
+				margin-right: unset !important;
+			}
+		}
+
+		&.flow {
+			display: flex;
+			flex-wrap: wrap;
+			gap: 10px;
+			justify-content: safe center;
+			& :where(.page) {
+				flex: 0 0 auto;
+				margin-left: unset !important;
+				margin-right: unset !important;
+			}
+
+		}
+
 		& > :where(.page) {
 			width         : 215.9mm;
 			height        : 279.4mm;
@@ -13,6 +50,9 @@
 			margin-left   : auto;
 			box-shadow    : 1px 4px 14px #000000;
 		}
+		*[id] {
+			scroll-margin-top:100px;
+		}
 	}
 	&::-webkit-scrollbar {
 		width : 20px;
@@ -39,6 +79,7 @@
 		overflow-y  : unset;
 		.pages {
 			margin : 0px;
+			zoom: 100% !important;
 			& > .page { box-shadow : unset; }
 		}
 	}
--- a/client/homebrew/brewRenderer/notificationPopup/notificationPopup.jsx
+++ b/client/homebrew/brewRenderer/notificationPopup/notificationPopup.jsx
@@ -1,43 +1,62 @@
 require('./notificationPopup.less');
-const React = require('react');
-const _     = require('lodash');
+import React, { useEffect, useState } from 'react';
+import request from '../../utils/request-middleware.js';

 import Dialog from '../../../components/dialog.jsx';

-const DISMISS_KEY = 'dismiss_notification12-04-23';
 const DISMISS_BUTTON = <i className='fas fa-times dismiss' />;

 const NotificationPopup = ()=>{
-	return <Dialog className='notificationPopup' dismissKey={DISMISS_KEY} closeText={DISMISS_BUTTON} >
+	const [notifications, setNotifications] = useState([]);
+	const [dissmissKeyList, setDismissKeyList] = useState([]);
+	const [error, setError] = useState(null);
+
+	useEffect(()=>{
+		getNotifications();
+	}, []);
+
+	const getNotifications = async ()=>{
+		setError(null);
+		try {
+			const res = await request.get('/admin/notification/all');
+			pickActiveNotifications(res.body || []);
+		} catch (err) {
+			console.log(err);
+			setError(`Error looking up notifications: ${err?.response?.body?.message || err.message}`);
+		}
+	};
+
+	const pickActiveNotifications = (notifs)=>{
+		const now = new Date();
+		const filteredNotifications = notifs.filter((notification)=>{
+			const startDate = new Date(notification.startAt);
+			const stopDate = new Date(notification.stopAt);
+			const dismissed = localStorage.getItem(notification.dismissKey) ? true : false;
+			return now >= startDate && now <= stopDate && !dismissed;
+		});
+		setNotifications(filteredNotifications);
+		setDismissKeyList(filteredNotifications.map((notif)=>notif.dismissKey));
+	};
+
+	const renderNotificationsList = ()=>{
+		if(error) return <div className='error'>{error}</div>;
+
+		return notifications.map((notification)=>(
+			<li key={notification.dismissKey} >
+				<em>{notification.title}</em><br />
+				<p dangerouslySetInnerHTML={{ __html: notification.text }}></p>
+			</li>
+		));
+	};
+
+	return <Dialog className='notificationPopup' dismisskeys={dissmissKeyList} closeText={DISMISS_BUTTON} >
 		<div className='header'>
 			<i className='fas fa-info-circle info'></i>
 			<h3>Notice</h3>
 			<small>This website is always improving and we are still adding new features and squashing bugs. Keep the following in mind:</small>
 		</div>
 		<ul>
-			<li key='psa'>
-				<em>Don't store IMAGES in Google Drive</em><br />
-				Google Drive is not an image service, and will block images from being used
-				in brews if they get more views than expected. Google has confirmed they won't fix
-				this, so we recommend you look for another image hosting service such as imgur, ImgBB or Google Photos.
-			</li>
-
-			<li key='googleDriveFolder'>
-				<em>Don't delete your Homebrewery folder on Google Drive!</em> <br />
-				We have had several reports of users losing their brews, not realizing
-				that they had deleted the files on their Google Drive. If you have a Homebrewery folder
-				on your Google Drive with *.txt files inside, <em>do not delete it</em>!
-				We cannot help you recover files that you have deleted from your own
-				Google Drive.
-			</li>
-
-			<li key='faq'>
-				<em>Protect your work! </em> <br />
-				If you opt not to use your Google Drive, keep in mind that we do not save a history of your projects. Please make frequent backups of your brews!&nbsp;
-				<a target='_blank' href='https://www.reddit.com/r/homebrewery/comments/adh6lh/faqs_psas_announcements/'>
-					See the FAQ
-				</a> to learn how to avoid losing your work!
-			</li>
+			{renderNotificationsList()}
 		</ul>
 	</Dialog>;
 };
--- a/client/homebrew/brewRenderer/notificationPopup/notificationPopup.less
+++ b/client/homebrew/brewRenderer/notificationPopup/notificationPopup.less
@@ -55,7 +55,10 @@
 			margin-top  : 1.4em;
 			font-size   : 0.8em;
 			line-height : 1.4em;
-			em { font-weight : 800; }
+			em { 
+				text-transform:capitalize;
+				font-weight : 800;
+			}
 		}
 	}
 }
--- a/client/homebrew/brewRenderer/safeHTML.js
+++ b/client/homebrew/brewRenderer/safeHTML.js
@@ -0,0 +1,46 @@
+// Derived from the vue-html-secure package, customized for Homebrewery
+
+let doc = null;
+let div = null;
+
+function safeHTML(htmlString) {
+	// If the Document interface doesn't exist, exit
+	if(typeof document == 'undefined') return null;
+	// If the test document and div don't exist, create them
+	if(!doc) doc = document.implementation.createHTMLDocument('');
+	if(!div) div = doc.createElement('div');
+
+	// Set the test div contents to the evaluation string
+	div.innerHTML = htmlString;
+	// Grab all nodes from the test div
+	const elements = div.querySelectorAll('*');
+
+	// Blacklisted tags
+	const blacklistTags = ['script', 'noscript', 'noembed'];
+	// Tests to remove attributes
+	const blacklistAttrs = [
+		(test)=>{return test.localName.indexOf('on') == 0;},
+		(test)=>{return test.localName.indexOf('type') == 0 && test.value.match(/submit/i);},
+		(test)=>{return test.value.replace(/[\u0000-\u0020\u00A0\u1680\u180E\u2000-\u2029\u205f\u3000]/g, '').toLowerCase().trim().indexOf('javascript:') == 0;}
+	];
+
+
+	elements.forEach((element)=>{
+		// Check each element for blacklisted type
+		if(blacklistTags.includes(element?.localName?.toLowerCase())) {
+			element.remove();
+			return;
+		}
+		// Check remaining elements for blacklisted attributes
+		for (const attribute of element.attributes){
+			if(blacklistAttrs.some((test)=>{return test(attribute);})) {
+				element.removeAttribute(attribute.localName);
+				break;
+			};
+		};
+	});
+
+	return div.innerHTML;
+};
+
+module.exports.safeHTML = safeHTML;
--- a/client/homebrew/brewRenderer/toolBar/toolBar.jsx
+++ b/client/homebrew/brewRenderer/toolBar/toolBar.jsx
@@ -1,26 +1,31 @@
+/* eslint-disable max-lines */
 require('./toolBar.less');
 const React = require('react');
 const { useState, useEffect } = React;
 const _ = require('lodash');

+import { Anchored, AnchoredBox, AnchoredTrigger } from '../../../components/Anchored.jsx';
+
 const MAX_ZOOM = 300;
 const MIN_ZOOM = 10;

-const ToolBar = ({ onZoomChange, currentPage, onPageChange, totalPages })=>{
+const ToolBar = ({ displayOptions, onDisplayOptionsChange, visiblePages, totalPages })=>{

-	const [zoomLevel, setZoomLevel] = useState(100);
-	const [pageNum, setPageNum]     = useState(currentPage);
+	const [pageNum, setPageNum]     = useState(1);
+	const [toolsVisible, setToolsVisible] = useState(true);

 	useEffect(()=>{
-		onZoomChange(zoomLevel);
-	}, [zoomLevel]);
+		// format multiple visible pages as a range (e.g. "150-153")
+		const pageRange = visiblePages.length === 1 ? `${visiblePages[0]}` : `${visiblePages[0]} - ${visiblePages.at(-1)}`;
+		setPageNum(pageRange);
+	}, [visiblePages]);

-	useEffect(()=>{
-		setPageNum(currentPage);
-	}, [currentPage]);
+	const handleZoomButton = (zoom)=>{
+		handleOptionChange('zoomLevel', _.round(_.clamp(zoom, MIN_ZOOM, MAX_ZOOM)));
+	};

-	const handleZoomButton = (delta)=>{
-		setZoomLevel(_.clamp(zoomLevel + delta, MIN_ZOOM, MAX_ZOOM));
+	const handleOptionChange = (optionKey, newValue)=>{
+		onDisplayOptionsChange({ ...displayOptions, [optionKey]: newValue });
 	};

 	const handlePageInput = (pageInput)=>{
@@ -28,38 +33,89 @@ const ToolBar = ({ onZoomChange, currentPage, onPageChange, totalPages })=>{
 			setPageNum(parseInt(pageInput)); // input type is 'text', so `page` comes in as a string, not number.
 	};

+	// scroll to a page, used in the Prev/Next Page buttons.
 	const scrollToPage = (pageNumber)=>{
+		if(typeof pageNumber !== 'number') return;
 		pageNumber = _.clamp(pageNumber, 1, totalPages);
 		const iframe = document.getElementById('BrewRenderer');
 		const brewRenderer = iframe?.contentWindow?.document.querySelector('.brewRenderer');
 		const page = brewRenderer?.querySelector(`#p${pageNumber}`);
 		page?.scrollIntoView({ block: 'start' });
-		setPageNum(pageNumber);
+	};
+
+	const calculateChange = (mode)=>{
+		const iframe = document.getElementById('BrewRenderer');
+		const iframeWidth = iframe.getBoundingClientRect().width;
+		const iframeHeight = iframe.getBoundingClientRect().height;
+		const pages = iframe.contentWindow.document.getElementsByClassName('page');
+
+		let desiredZoom = 0;
+
+		if(mode == 'fill'){
+			// find widest page, in case pages are different widths, so that the zoom is adapted to not cut the widest page off screen.
+			const widestPage = _.maxBy([...pages], 'offsetWidth').offsetWidth;
+
+			desiredZoom = (iframeWidth / widestPage) * 100;
+
+		} else if(mode == 'fit'){
+			let minDimRatio;
+			// find the page with the largest single dim (height or width) so that zoom can be adapted to fit it.
+			if(displayOptions.spread === 'facing')
+				minDimRatio = [...pages].reduce((minRatio, page)=>Math.min(minRatio, iframeWidth / page.offsetWidth / 2), Infinity);    // if 'facing' spread, fit two pages in view
+			else 
+				minDimRatio = [...pages].reduce((minRatio, page)=>Math.min(minRatio, iframeWidth / page.offsetWidth, iframeHeight / page.offsetHeight), Infinity);
+
+			desiredZoom = minDimRatio * 100;
+		}
+
+		const margin = 5;  // extra space so page isn't edge to edge (not truly "to fill")
+
+		const deltaZoom = (desiredZoom - displayOptions.zoomLevel) - margin;
+		return deltaZoom;
 	};

 	return (
-		<div className='toolBar'>
+		<div id='preview-toolbar' className={`toolBar ${toolsVisible ? 'visible' : 'hidden'}`} role='toolbar'>
+			<button className='toggleButton' title={`${toolsVisible ? 'Hide' : 'Show'} Preview Toolbar`} onClick={()=>{setToolsVisible(!toolsVisible);}}><i className='fas fa-glasses' /></button>
 			{/*v=====----------------------< Zoom Controls >---------------------=====v*/}
-			<div className='group'>
+			<div className='group' role='group' aria-label='Zoom' aria-hidden={!toolsVisible}>
+				<button
+					id='fill-width'
+					className='tool'
+					title='Set zoom to fill preview with one page'
+					onClick={()=>handleZoomButton(displayOptions.zoomLevel + calculateChange('fill'))}
+				>
+					<i className='fac fit-width' />
+				</button>
+				<button
+					id='zoom-to-fit'
+					className='tool'
+					title='Set zoom to fit entire page in preview'
+					onClick={()=>handleZoomButton(displayOptions.zoomLevel + calculateChange('fit'))}
+				>
+					<i className='fac zoom-to-fit' />
+				</button>
 				<button
 					id='zoom-out'
 					className='tool'
-					onClick={()=>handleZoomButton(-20)}
-					disabled={zoomLevel <= MIN_ZOOM}
+					onClick={()=>handleZoomButton(displayOptions.zoomLevel - 20)}
+					disabled={displayOptions.zoomLevel <= MIN_ZOOM}
+					title='Zoom Out'
 				>
 					<i className='fas fa-magnifying-glass-minus' />
 				</button>
 				<input
 					id='zoom-slider'
-					className='range-input tool'
+					className='range-input tool hover-tooltip'
 					type='range'
 					name='zoom'
+					title='Set Zoom'
 					list='zoomLevels'
 					min={MIN_ZOOM}
 					max={MAX_ZOOM}
 					step='1'
-					value={zoomLevel}
-					onChange={(e)=>setZoomLevel(parseInt(e.target.value))}
+					value={displayOptions.zoomLevel}
+					onChange={(e)=>handleZoomButton(parseInt(e.target.value))}
 				/>
 				<datalist id='zoomLevels'>
 					<option value='100' />
@@ -68,20 +124,74 @@ const ToolBar = ({ onZoomChange, currentPage, onPageChange, totalPages })=>{
 				<button
 					id='zoom-in'
 					className='tool'
-					onClick={()=>handleZoomButton(20)}
-					disabled={zoomLevel >= MAX_ZOOM}
+					onClick={()=>handleZoomButton(displayOptions.zoomLevel + 20)}
+					disabled={displayOptions.zoomLevel >= MAX_ZOOM}
+					title='Zoom In'
 				>
 					<i className='fas fa-magnifying-glass-plus' />
 				</button>
 			</div>

+			{/*v=====----------------------< Spread Controls >---------------------=====v*/}
+			<div className='group' role='group' aria-label='Spread' aria-hidden={!toolsVisible}>
+				<div className='radio-group' role='radiogroup'>
+					<button role='radio'
+						id='single-spread'
+						className='tool'
+						title='Single Page'
+						onClick={()=>{handleOptionChange('spread', 'active');}}
+						aria-checked={displayOptions.spread === 'single'}
+					><i className='fac single-spread' /></button>
+					<button role='radio'
+						id='facing-spread'
+						className='tool'
+						title='Facing Pages'
+						onClick={()=>{handleOptionChange('spread', 'facing');}}
+						aria-checked={displayOptions.spread === 'facing'}
+					><i className='fac facing-spread' /></button>
+					<button role='radio'
+						id='flow-spread'
+						className='tool'
+						title='Flow Pages'
+						onClick={()=>{handleOptionChange('spread', 'flow');}}
+						aria-checked={displayOptions.spread === 'flow'}
+					><i className='fac flow-spread' /></button>
+
+				</div>
+				<Anchored>
+					<AnchoredTrigger id='spread-settings' className='tool' title='Spread options'><i className='fas fa-gear' /></AnchoredTrigger>
+					<AnchoredBox title='Options'>
+						<h1>Options</h1>
+						<label title='Modify the horizontal space between pages.'>
+							Column gap
+							<input type='range' min={0} max={200} defaultValue={10} className='range-input' onChange={(evt)=>handleOptionChange('columnGap', evt.target.value)} />
+						</label>
+						<label title='Modify the vertical space between rows of pages.'>
+							Row gap
+							<input type='range' min={0} max={200} defaultValue={10} className='range-input' onChange={(evt)=>handleOptionChange('rowGap', evt.target.value)} />
+						</label>
+						<label title='Start 1st page on the right side, such as if you have cover page.'>
+							Start on right
+							<input type='checkbox' checked={displayOptions.startOnRight} onChange={()=>{handleOptionChange('startOnRight', !displayOptions.startOnRight);}}
+								title={displayOptions.spread !== 'facing' ? 'Switch to Facing to enable toggle.' : null} />
+						</label>
+						<label title='Toggle the page shadow on every page.'>
+							Page shadows
+							<input type='checkbox' checked={displayOptions.pageShadows} onChange={()=>{handleOptionChange('pageShadows', !displayOptions.pageShadows);}} />
+						</label>
+					</AnchoredBox>
+				</Anchored>
+			</div>
+
 			{/*v=====----------------------< Page Controls >---------------------=====v*/}
-			<div className='group'>
+			<div className='group' role='group'  aria-label='Pages' aria-hidden={!toolsVisible}>
 				<button
 					id='previous-page'
 					className='previousPage tool'
-					onClick={()=>scrollToPage(pageNum - 1)}
-					disabled={pageNum <= 1}
+					type='button'
+					title='Previous Page(s)'
+					onClick={()=>scrollToPage(_.min(visiblePages) - visiblePages.length)}
+					disabled={visiblePages.includes(1)}
 				>
 					<i className='fas fa-arrow-left'></i>
 				</button>
@@ -92,6 +202,7 @@ const ToolBar = ({ onZoomChange, currentPage, onPageChange, totalPages })=>{
 						className='text-input'
 						type='text'
 						name='page'
+						title='Current page(s) in view'
 						inputMode='numeric'
 						pattern='[0-9]'
 						value={pageNum}
@@ -99,15 +210,18 @@ const ToolBar = ({ onZoomChange, currentPage, onPageChange, totalPages })=>{
 						onChange={(e)=>handlePageInput(e.target.value)}
 						onBlur={()=>scrollToPage(pageNum)}
 						onKeyDown={(e)=>e.key == 'Enter' && scrollToPage(pageNum)}
+						style={{ width: `${pageNum.length}ch` }}
 					/>
-					<span id='page-count'>/ {totalPages}</span>
+					<span id='page-count' title='Total Page Count'>/ {totalPages}</span>
 				</div>

 				<button
 					id='next-page'
 					className='tool'
-					onClick={()=>scrollToPage(pageNum + 1)}
-					disabled={pageNum >= totalPages}
+					type='button'
+					title='Next Page(s)'
+					onClick={()=>scrollToPage(_.max(visiblePages) + 1)}
+					disabled={visiblePages.includes(totalPages)}
 				>
 					<i className='fas fa-arrow-right'></i>
 				</button>
--- a/client/homebrew/brewRenderer/toolBar/toolBar.less
+++ b/client/homebrew/brewRenderer/toolBar/toolBar.less
@@ -1,3 +1,5 @@
+@import (less) './client/icons/customIcons.less';
+
 .toolBar {
 	position         : absolute;
 	z-index          : 1;
@@ -11,8 +13,13 @@
 	height           : auto;
 	padding          : 2px 0;
 	font-family      : 'Open Sans', sans-serif;
+	font-size        : 13px;
 	color            : #CCCCCC;
 	background-color : #555555;
+	& > *:not(.toggleButton) {
+		opacity    : 1;
+		transition : all 0.2s ease;
+	}

 	.group {
 		box-sizing       : border-box;
@@ -28,14 +35,78 @@
 		align-items : center;
 	}

+	.active, [aria-checked='true'] { background-color : #444444; }
+
+	.anchored-trigger {
+		&.active { background-color : #444444; }
+	}
+
+	.anchored-box {
+		--box-color      : #555555;
+		top              : 30px;
+		display          : flex;
+		flex-direction   : column;
+		gap              : 5px;
+		padding          : 15px;
+		margin-top       : 10px;
+		font-size        : 0.8em;
+		color            : #CCCCCC;
+		background-color : var(--box-color);
+		border-radius    : 5px;
+	
+		h1 {
+			padding-bottom : 0.3em;
+			margin-bottom  : 0.5em;
+			border-bottom  : 1px solid currentColor;
+		}
+	
+		h2 {
+			padding-bottom : 0.3em;
+			margin         : 1em 0 0.5em 0;
+			color          : lightgray;
+			border-bottom  : 1px solid currentColor;
+		}
+	
+		label {
+			display         : flex;
+			gap             : 6px;
+			align-items     : center;
+			justify-content : space-between;
+	
+		}
+		input {
+			height : unset;
+			&[type='range'] { padding : 0; }
+		}
+		&::before {
+			position       : absolute;
+			top            : -20px;
+			left           : 50%;
+			width          : 0px;
+			height         : 0px;
+			pointer-events : none;
+			content        : '';
+			border         : 10px solid transparent;
+			border-bottom  : 10px solid var(--box-color);
+			transform      : translateX(-50%);
+		}
+
+	}
+
+	.radio-group:has(button[role='radio']) {
+		display : flex;
+		height  : 100%;
+		border  : 1px solid #333333;
+	}
+
 	input {
 		position       : relative;
 		height         : 1.5em;
 		padding        : 2px 5px;
 		font-family    : 'Open Sans', sans-serif;
-		color          : #000000;
-		background     : #EEEEEE;
-		border         : 1px solid gray;
+		color          : inherit;
+		background     : #3B3B3B;
+		border         : none;
 		&:focus { outline : 1px solid #D3D3D3; }

 		// `.range-input` if generic to all range inputs, or `#zoom-slider` if only for zoom slider
@@ -44,14 +115,14 @@
 			color        : #D3D3D3;
 			accent-color : #D3D3D3;
  
-			&::-webkit-slider-thumb, &::-moz-slider-thumb { 
+			&::-webkit-slider-thumb, &::-moz-range-thumb { 
 				width            : 5px;
 				height           : 5px;
-				cursor           : pointer;
+				cursor           : ew-resize;
 				outline          : none;
 			}

-			&:hover::after {
+			&.hover-tooltip[value]:hover::after {
 				position         : absolute;
 				bottom           : -30px;
 				left             : 50%;
@@ -70,29 +141,47 @@

 		// `.text-input` if generic to all range inputs, or `#page-input` if only for current page input
 		&#page-input {
-			width        : 4ch;
+			min-width    : 5ch;
 			margin-right : 1ch;
 			text-align   : center;
 		}
 	}

 	button {
-		box-sizing       : content-box;
+		box-sizing       : border-box;
 		display          : flex;
 		align-items      : center;
 		justify-content  : center;
 		width            : auto;
 		min-width        : 46px;
 		height           : 100%;
-		padding          : 0 0px;
-		font-weight      : unset;
-		color            : inherit;
-		background-color : unset;
 		&:hover { background-color : #444444; }
-		&:focus { outline : 1px solid #D3D3D3; }
+		&:focus { border  : 1px solid #D3D3D3;outline : none;}
 		&:disabled {
 			color            : #777777;
 			background-color : unset !important;
 		}
+		i { font-size : 1.2em; }
 	}
+
+	&.hidden {
+		flex-wrap        : nowrap;
+		width            : 32px;
+		overflow         : hidden;
+		background-color : unset;
+		opacity          : 0.5;
+		transition       : all 0.3s ease;
+		& > *:not(.toggleButton) {
+			opacity    : 0;
+			transition : all 0.2s ease;
+		}
+	}
+}
+
+button.toggleButton {
+	position  : absolute;
+	left      : 0;
+	z-index   : 5;
+	width     : 32px;
+	min-width : unset;
 }