Merge pull request #1897 from jeddai/migration-guide

Legacy -> v3 Migration guide

client/homebrew/navbar/help.navitem.jsx

@@ -0,0 +1,25 @@
+const React = require('react');
+const createClass = require('create-react-class');
+const _ = require('lodash');
+
+const Nav = require('naturalcrit/nav/nav.jsx');
+
+module.exports = function(props){
+	return <Nav.dropdown>
+		<Nav.item color='grey' icon='fas fa-question-circle'>
+			need help?
+		</Nav.item>
+		<Nav.item color='red' icon='fas fa-fw fa-bug'
+			href={`https://www.reddit.com/r/homebrewery/submit?selftext=true&title=${encodeURIComponent('[Issue] Describe Your Issue Here')}`}
+			newTab={true}
+			rel='noopener noreferrer'>
+			report issue
+		</Nav.item>
+		<Nav.item color='blue' icon='fas fa-fw fa-file-import'
+			href='/migrate'
+			newTab={true}
+			rel='noopener noreferrer'>
+			migrate
+		</Nav.item>
+	</Nav.dropdown>;
+};

client/homebrew/navbar/issue.navitem.jsx

@@ -1,13 +0,0 @@
-const React = require('react');
-const createClass = require('create-react-class');
-const Nav = require('naturalcrit/nav/nav.jsx');
-
-module.exports = function(props){
-	return <Nav.item
-		newTab={true}
-		color='red'
-		icon='fas fa-bug'
-		href={`https://www.reddit.com/r/homebrewery/submit?selftext=true&title=${encodeURIComponent('[Issue] Describe Your Issue Here')}`} >
-		report issue
-	</Nav.item>;
-};

client/homebrew/navbar/navbar.less

@@ -1,5 +1,6 @@
+@import 'naturalcrit/styles/colors.less';
 @navbarHeight : 28px;
-@keyframes coloring {
+@keyframes pinkColoring {
 	//from {color: white;}
 	//to {color: red;}
 	0%   {color: pink;}
@@ -62,19 +63,21 @@
 		}
 		i{
 			.animate(color);
-			animation-name: coloring;
+			animation-name: pinkColoring;
 			animation-duration: 2s;
 			color: pink;
 		}
 	}
-	.recent.navItem{
+	.recent.navItem {
 		position : relative;
 		.dropdown{
-			position : absolute;
-			top      : 28px;
-			left     : 0px;
-			z-index  : 10000;
-			width    : 100%;
+			position   : absolute;
+			top        : 28px;
+			left       : 0px;
+			z-index    : 10000;
+			width      : 100%;
+			overflow   : hidden auto;
+			max-height : ~"calc(100vh - 28px)";
 			h4{
 				display          : block;
 				box-sizing       : border-box;
@@ -88,11 +91,12 @@
 				&:nth-of-type(2){ background-color: darken(@purple, 30%); }
 			}
 			.item{
+				#backgroundColors;
 				.animate(background-color);
 				position         : relative;
 				display          : block;
 				box-sizing       : border-box;
-				padding          : 13px 5px;
+				padding          : 8px 5px 13px;
 				background-color : #333;
 				color            : white;
 				text-decoration  : none;

client/homebrew/navbar/recent.navitem.jsx

@@ -123,8 +123,8 @@ const RecentItems = createClass({
 		if(!this.state.showDropdown) return null;
 
 		const makeItems = (brews)=>{
-			return _.map(brews, (brew)=>{
-				return <a href={brew.url} className='item' key={brew.id} target='_blank' rel='noopener noreferrer' title={brew.title || '[ no title ]'}>
+			return _.map(brews, (brew, i)=>{
+				return <a href={brew.url} className='item' key={`${brew.id}-${i}`} target='_blank' rel='noopener noreferrer' title={brew.title || '[ no title ]'}>
 					<span className='title'>{brew.title || '[ no title ]'}</span>
 					<span className='time'>{Moment(brew.ts).fromNow()}</span>
 				</a>;

client/homebrew/pages/editPage/editPage.jsx

@@ -10,7 +10,7 @@ const Nav = require('naturalcrit/nav/nav.jsx');
 const Navbar = require('../../navbar/navbar.jsx');
 
 const NewBrew = require('../../navbar/newbrew.navitem.jsx');
-const ReportIssue = require('../../navbar/issue.navitem.jsx');
+const HelpNavItem = require('../../navbar/help.navitem.jsx');
 const PrintLink = require('../../navbar/print.navitem.jsx');
 const Account = require('../../navbar/account.navitem.jsx');
 const RecentNavItem = require('../../navbar/recent.navitem.jsx').both;
@@ -434,7 +434,7 @@ const EditPage = createClass({
 				{this.renderGoogleDriveIcon()}
 				{this.renderSaveButton()}
 				<NewBrew />
-				<ReportIssue />
+				<HelpNavItem/>
 				<Nav.dropdown>
 					<Nav.item color='teal' icon='fas fa-share-alt'>
 						share

client/homebrew/pages/errorPage/errorPage.jsx

@@ -7,8 +7,8 @@ const cx = require('classnames');
 const Nav = require('naturalcrit/nav/nav.jsx');
 const Navbar = require('../../navbar/navbar.jsx');
 const PatreonNavItem = require('../../navbar/patreon.navitem.jsx');
-const IssueNavItem = require('../../navbar/issue.navitem.jsx');
 const RecentNavItem = require('../../navbar/recent.navitem.jsx').both;
+const HelpNavItem = require('../../navbar/help.navitem.jsx');
 
 const BrewRenderer = require('../../brewRenderer/brewRenderer.jsx');
 
@@ -33,7 +33,7 @@ const ErrorPage = createClass({
 
 				<Nav.section>
 					<PatreonNavItem />
-					<IssueNavItem />
+					<HelpNavItem />
 					<RecentNavItem />
 				</Nav.section>
 			</Navbar>

client/homebrew/pages/homePage/homePage.jsx

@@ -9,7 +9,7 @@ const { Meta } = require('vitreum/headtags');
 const Nav = require('naturalcrit/nav/nav.jsx');
 const Navbar = require('../../navbar/navbar.jsx');
 const NewBrewItem = require('../../navbar/newbrew.navitem.jsx');
-const IssueNavItem = require('../../navbar/issue.navitem.jsx');
+const HelpNavItem = require('../../navbar/help.navitem.jsx');
 const RecentNavItem = require('../../navbar/recent.navitem.jsx').both;
 const AccountNavItem = require('../../navbar/account.navitem.jsx');
 
@@ -59,7 +59,7 @@ const HomePage = createClass({
 		return <Navbar ver={this.props.ver}>
 			<Nav.section>
 				<NewBrewItem />
-				<IssueNavItem />
+				<HelpNavItem />
 				<RecentNavItem />
 				<AccountNavItem />
 			</Nav.section>

client/homebrew/pages/homePage/migrate.md

@@ -0,0 +1,202 @@
+# How to Convert a Legacy Document to v3
+Here you will find a number of steps to guide you through converting a Legacy document into a Homebrewery v3 document.
+
+**The first thing you'll want to do is switch the editor's rendering engine from `Legacy` to `v3`.** This will be the renderer we design features for moving forward.
+
+There are some examples of Legacy code in the code pane if you need more context behind some of the changes.
+
+**This document will evolve as users like yourself inform us of issues with it, or areas of conversion that it does not cover. _Please_ reach out if you have any suggestions for this document.**
+
+## Simple Replacements
+To make your life a little easier with this section, a text editor like [VSCode](https://code.visualstudio.com/) or Notepad will help a lot.
+
+The following table describes Legacy and other document elements and their Homebrewery counterparts. A simple find/replace should get these in working order.
+
+| Legacy / Other  | Homebrewery                  |
+|:----------------|:-----------------------------|
+| `\pagebreak`    | `\page`                      |
+| `======`        | `\page`                      |
+| `\pagebreaknum` | `{{pageNumber,auto}}\n\page` |
+| `@=====`        | `{{pageNumber,auto}}\n\page` |
+| `\columnbreak`  | `\column`                    |
+| `.phb`          | `.page`                      |
+
+## Classed or Styled Divs
+Anything that relies on the following syntax can be changed to the new Homebrewery v3 curly brace syntax:
+
+```
+<div class="classTable wide">
+...
+</div>
+```
+:
+The above example is equivalent to the following in v3 syntax.
+
+```
+{{classTable,wide
+...
+}}
+```
+:
+Some examples of this include class tables (as shown above), descriptive blocks, notes, and spell lists.
+
+\column
+
+## Margins and Padding
+Any manual margins and padding to push text down the page will likely need to be updated. Colons can be used on lines by themselves to push things down the page vertically if you'd rather not set pixel-perfect margins or padding.
+
+## Notes
+
+In Legacy, notes are denoted using markdown blockquote syntax. In Homebrewery v3, this is replaced by the curly brace syntax.
+
+<!--
+> ##### Catchy Title
+> Useful Information
+-->
+
+{{note
+##### Title
+Information
+}}
+
+## Split Tables
+Split tables also use the curly brace syntax, as the new renderer can handle style values separately from class names.
+
+<!--
+<div style='column-count:2'>
+
+| d8  | Loot |
+|:---:|:-----------:|
+|  1  | 100gp |
+|  2  | 200gp |
+|  3  | 300gp |
+|  4  | 400gp |
+
+| d8  | Loot |
+|:---:|:-----------:|
+|  5  | 500gp |
+|  6  | 600gp |
+|  7  | 700gp |
+|  8  | 1000gp |
+
+</div>
+-->
+
+##### Typical Difficulty Classes
+{{column-count:2
+| Task Difficulty | DC |
+|:----------------|:--:|
+| Very easy       | 5  |
+| Easy            | 10 |
+| Medium          | 15 |
+
+| Task Difficulty   | DC |
+|:------------------|:--:|
+| Hard              | 20 |
+| Very hard         | 25 |
+| Nearly impossible | 30 |
+}}
+
+## Blockquotes
+Blockquotes are denoted by the `>` character at the beginning of the line. In Homebrewery's v3 renderer, they hold virtually no meaning and have no CSS styling. You are free to use blockquotes when styling your document or creating themes without needing to worry about your CSS affecting other parts of the document.
+
+{{pageNumber,auto}}
+
+\page
+
+## Stat Blocks
+
+There are pretty significant differences between stat blocks on the Legacy renderer and Homebrewery v3. This section contains a list of changes that will need to be made to update the stat block.
+
+### Initial Changes
+You will want to **remove all leading** `___` that started the stat block in Legacy, and replace that with `{{monster` before the stat block, and `}}` after it.
+
+**If you want a frame** around the stat block, you can add `,frame` to the curly brace definition.
+
+**If the stat block was wide**, make sure to add `,wide` to the curly brace definition.
+
+### Blockquotes
+The key difference is the lack of blockquotes. Legacy documents use the `>` symbol at the start of the line for each line in the stat block, and the v3 renderer does not. **You will want to remove all `>` characters at the beginning of all lines, and delete any leading spaces.**
+
+### Lists
+The basic characteristics and advanced characteristics sections are not list elements in Homebrewery. You will want to **remove all `-` or `*` characters from the beginning of lines.**
+
+### Spacing
+In order to have the correct spacing after removing the list elements, you will want to **add two colons between the name of each basic/advanced characteristic and its value.** _(see example in the code pane)_
+
+Additionally, in the special traits and actions sections, you will want to add a colon at the beginning of each line that separates a trait/action from another, as seen below. **Any empty lines between special traits and actions should contain only a colon.** _(see example in the code pane)_
+
+\column
+
+{{margin-top:102px}}
+
+<!--
+### Legacy/Other Document Example:
+___
+> ## Centaur
+> *Large Monstrosity, neutral good*
+>___
+> - **Armor Class** 12
+> - **Hit Points** 45(6d10 + 12)
+> - **Speed** 50ft.
+>___
+>|STR|DEX|CON|INT|WIS|CHA|
+>|:---:|:---:|:---:|:---:|:---:|:---:|
+>|18 (+4)|14 (+2)|14 (+2)|9 (-1)|13 (+1)|11 (+0)|
+>___
+> - **Skills** Athletics +6, Perception +3, Survival +3
+> - **Senses** passive Perception 13
+> - **Languages** Elvish, Sylvan
+> - **Challenge** 2 (450 XP)
+> ___
+> ***Charge.*** If the centaur moves at least 30 feet straight toward a target and then hits it with a pike attack on the same turn, the target takes an extra 10 (3d6) piercing damage.
+>
+> ***Second Thing*** More details.
+>
+> ### Actions
+> ***Multiattack.*** The centaur makes two attacks: one with its pike and one with its hooves or two with its longbow.
+>
+> ***Pike.*** *Melee Weapon Attack:* +6 to hit, reach 10 ft., one target. *Hit:* 9 (1d10 + 4) piercing damage.
+>
+> ***Hooves.*** *Melee Weapon Attack:* +6 to hit, reach 5 ft., one target. *Hit:* 11 (2d6 + 4) bludgeoning damage.
+>
+> ***Longbow.*** *Ranged Weapon Attack:* +4 to hit, range 150/600 ft., one target. *Hit:* 6 (1d8 + 2) piercing damage.
+-->
+
+### Homebrewery v3 Example:
+
+{{monster
+## Centaur
+*Large monstrosity, neutral good*
+___
+**Armor Class** :: 12
+**Hit Points**  :: 45(6d10 + 12)
+**Speed**       :: 50ft.
+___
+|  STR  |  DEX  |  CON  |  INT  |  WIS  |  CHA  |
+|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|
+|18 (+4)|14 (+2)|14 (+2)|9 (-1) |13 (+1)|11 (+0)|
+___
+**Skills** :: Athletics +6, Perception +3, Survival +3
+**Senses** :: passive Perception 13
+**Languages** :: Elvish, Sylvan
+**Challenge** :: 2 (450 XP)
+___
+***Charge.*** If the centaur moves at least 30 feet straight toward a target and then hits it with a pike attack on the same turn, the target takes an extra 10 (3d6) piercing damage.
+:
+***Second Thing*** More details.
+
+### Actions
+***Multiattack.*** The centaur makes two attacks: one with its pike and one with its hooves or two with its longbow.
+:
+***Pike.*** *Melee Weapon Attack:* +6 to hit, reach 10 ft., one target. *Hit:* 9 (1d10 + 4) piercing damage.
+:
+***Hooves.*** *Melee Weapon Attack:* +6 to hit, reach 5 ft., one target. *Hit:* 11 (2d6 + 4) bludgeoning damage.
+:
+***Longbow.*** *Ranged Weapon Attack:* +4 to hit, range 150/600 ft., one target. *Hit:* 6 (1d8 + 2) piercing damage.
+}}
+
+{{pageNumber,auto}}
+
+
+

client/homebrew/pages/newPage/newPage.jsx

@@ -11,7 +11,7 @@ const Nav = require('naturalcrit/nav/nav.jsx');
 const Navbar = require('../../navbar/navbar.jsx');
 const AccountNavItem = require('../../navbar/account.navitem.jsx');
 const RecentNavItem = require('../../navbar/recent.navitem.jsx').both;
-const IssueNavItem = require('../../navbar/issue.navitem.jsx');
+const HelpNavItem = require('../../navbar/help.navitem.jsx');
 
 const SplitPane = require('naturalcrit/splitPane/splitPane.jsx');
 const Editor = require('../../editor/editor.jsx');
@@ -291,7 +291,7 @@ const NewPage = createClass({
 			<Nav.section>
 				{this.renderSaveButton()}
 				{this.renderLocalPrintButton()}
-				<IssueNavItem />
+				<HelpNavItem />
 				<RecentNavItem />
 				<AccountNavItem />
 			</Nav.section>

client/homebrew/pages/userPage/userPage.jsx

@@ -13,7 +13,7 @@ const RecentNavItem = require('../../navbar/recent.navitem.jsx').both;
 const Account = require('../../navbar/account.navitem.jsx');
 const NewBrew = require('../../navbar/newbrew.navitem.jsx');
 const BrewItem = require('./brewItem/brewItem.jsx');
-const ReportIssue = require('../../navbar/issue.navitem.jsx');
+const HelpNavItem = require('../../navbar/help.navitem.jsx');
 
 // const brew = {
 // 	title   : 'SUPER Long title woah now',
@@ -164,7 +164,7 @@ const UserPage = createClass({
 			<Navbar>
 				<Nav.section>
 					<NewBrew />
-					<ReportIssue />
+					<HelpNavItem />
 					<RecentNavItem />
 					<Account />
 				</Nav.section>

server/app.js

@@ -96,6 +96,7 @@ app.use(require('./admin.api.js'));
 const HomebrewModel  = require('./homebrew.model.js').model;
 const welcomeText    = require('fs').readFileSync('client/homebrew/pages/homePage/welcome_msg.md', 'utf8');
 const welcomeTextV3  = require('fs').readFileSync('client/homebrew/pages/homePage/welcome_msg_v3.md', 'utf8');
+const migrateText    = require('fs').readFileSync('client/homebrew/pages/homePage/migrate.md', 'utf8');
 const changelogText  = require('fs').readFileSync('changelog.md', 'utf8');
 const faqText        = require('fs').readFileSync('faq.md', 'utf8');
 
@@ -126,6 +127,17 @@ app.get('/v3_preview', async (req, res, next)=>{
 	return next();
 });
 
+//Legacy/Other Document -> v3 Migration Guide
+app.get('/migrate', async (req, res, next)=>{
+	const brew = {
+		text     : migrateText,
+		renderer : 'V3'
+	};
+	splitTextStyleAndMetadata(brew);
+	req.brew = brew;
+	return next();
+});
+
 //Changelog page
 app.get('/changelog', async (req, res, next)=>{
 	const brew = {

shared/naturalcrit/nav/nav.less

@@ -1,3 +1,4 @@
+@import '../styles/colors';
 @keyframes glideDropDown {
 	0%   {transform : translate(0px, -100%);
 				opacity   : 0;
@@ -49,6 +50,7 @@ nav{
 		}
 	}
 	.navItem{
+		#backgroundColors;
 		.animate(background-color);
 		padding          : 8px 12px;
 		cursor           : pointer;
@@ -58,30 +60,12 @@ nav{
 		color            : white;
 		text-decoration  : none;
 		text-transform   : uppercase;
+		line-height      : 13px;
 		i{
 			margin-left : 5px;
 			font-size   : 13px;
+			float       : right;
 		}
-		&.tealLight:hover{ background-color : @tealLight };
-		&.teal:hover{ background-color : @teal };
-		&.greenLight:hover{ background-color : @greenLight };
-		&.green:hover{ background-color : @green };
-		&.blueLight:hover{ background-color : @blueLight };
-		&.blue:hover{ background-color : @blue };
-		&.purpleLight:hover{ background-color : @purpleLight };
-		&.purple:hover{ background-color : @purple };
-		&.steelLight:hover{ background-color : @steelLight };
-		&.steel:hover{ background-color : @steel };
-		&.yellowLight:hover{ background-color : @yellowLight };
-		&.yellow:hover{ background-color : @yellow };
-		&.orangeLight:hover{ background-color : @orangeLight };
-		&.orange:hover{ background-color : @orange };
-		&.redLight:hover{ background-color : @redLight };
-		&.red:hover{ background-color : @red };
-		&.silverLight:hover{ background-color : @silverLight };
-		&.silver:hover{ background-color : @silver };
-		&.greyLight:hover{ background-color : @greyLight };
-		&.grey:hover{ background-color : @grey };
 	}
 	.navSection:last-child .navItem{
 		border-left : 1px solid #666;

shared/naturalcrit/styles/colors.less

@@ -20,4 +20,27 @@
 @silverLight : #ECF0F1;
 @silver      : #BDC3C7;
 @greyLight   : #95A5A6;
-@grey        : #7F8C8D;
+@grey        : #7F8C8D;
+
+#backgroundColors {
+  &.tealLight:hover{ background-color : @tealLight };
+  &.teal:hover{ background-color : @teal };
+  &.greenLight:hover{ background-color : @greenLight };
+  &.green:hover{ background-color : @green };
+  &.blueLight:hover{ background-color : @blueLight };
+  &.blue:hover{ background-color : @blue };
+  &.purpleLight:hover{ background-color : @purpleLight };
+  &.purple:hover{ background-color : @purple };
+  &.steelLight:hover{ background-color : @steelLight };
+  &.steel:hover{ background-color : @steel };
+  &.yellowLight:hover{ background-color : @yellowLight };
+  &.yellow:hover{ background-color : @yellow };
+  &.orangeLight:hover{ background-color : @orangeLight };
+  &.orange:hover{ background-color : @orange };
+  &.redLight:hover{ background-color : @redLight };
+  &.red:hover{ background-color : @red };
+  &.silverLight:hover{ background-color : @silverLight };
+  &.silver:hover{ background-color : @silver };
+  &.greyLight:hover{ background-color : @greyLight };
+  &.grey:hover{ background-color : @grey };
+}