vowel 0.6.3 → 0.7.0-beta.0

package/stylesheets/TypographyStyles.css

@@ -1,8 +1,25 @@
 @layer reset, typography;
 
 @layer typography {
-	html {
-		font-family:
+
+
+	/*
+		FONT FAMILIES
+	*/
+	:root {
+		/*
+			these variables declare a stack with system fallbacks
+			declare brand fonts with `--font-x-brand` to keep stack intact
+		*/
+		--font-stack-serif: var(--font-serif-brand), var(--font-serif-system);
+		--font-stack-sans: var(--font-sans-brand), var(--font-sans-system);
+		--font-stack-monospace: var(--font-monospace-brand), var(--font-monospace-system);
+
+		--font-serif-brand: "Declare a brand serif font with this variable";
+		--font-sans-brand: "Declare a brand sans-serif font with this variable";
+		--font-monospace-brand: "Declare a brand monospace font with this variable";
+
+		--font-sans-system:
 			-apple-system,
 			BlinkMacSystemFont,
 			avenir next,
@@ -16,199 +33,440 @@
 			noto,
 			arial,
 			sans-serif;
+
+		--font-monospace-system:
+			Menlo,
+			Consolas,
+			Monaco,
+			Liberation Mono,
+			Lucida Console,
+			monospace;
+
+		--font-serif-system:
+			Iowan Old Style,
+			Apple Garamond,
+			Baskerville,
+			Times New Roman,
+			Droid Serif,
+			Times,
+			Source Serif Pro,
+			serif,
+			Apple Color Emoji,
+			Segoe UI Emoji,
+			Segoe UI Symbol;
+
+
+		/*
+			the recommended root font size on small screens (16px) and
+			large screens (18px)
+		*/
+		--font-size-root: clamp(1rem, 0.875rem + 0.333vw, 1.125rem);
+
+		/*
+			the difference in size of h1 relative to the root
+			font size; increase or decrease this number for larger or
+			smaller headings
+		*/
+		--font-size-delta: calc(1.5 * var(--font-size-root));
+
+		/*
+			the rate of decay from h1 to h6 font size, where h6 is
+			almost as small as the root font size; a higher number
+			makes subheadings smaller
+		*/
+		--font-size-decay: 3;
+
+		/*
+			letter spacing of h1 and h6, with h2-h6 imputed
+			according to the decay variable
+		*/
+		--letter-spacing-h1: -0.01ch;
+		--letter-spacing-h6: 0ch;
+		--letter-spacing-decay: 2;
+
+		/*
+			weight of h1 and h6, with h2-h6 imputed according
+			to the decay variable
+		*/
+		--font-weight-h1: 800;
+		--font-weight-h6: 600;
+		--font-weight-decay: 2;
+
+		/*
+			*do not edit or overwrite*: calculations to impute
+			font sizes, weights, and spacing between h1 and h6
+		*/
+		--font-size-h1: calc(var(--font-size-root) + var(--font-size-delta));
+		--font-size-h2: calc(var(--font-size-root) + calc(var(--font-size-delta) * pow(5 / 6, var(--font-size-decay))));
+		--font-size-h3: calc(var(--font-size-root) + calc(var(--font-size-delta) * pow(4 / 6, var(--font-size-decay))));
+		--font-size-h4: calc(var(--font-size-root) + calc(var(--font-size-delta) * pow(3 / 6, var(--font-size-decay))));
+		--font-size-h5: calc(var(--font-size-root) + calc(var(--font-size-delta) * pow(2 / 6, var(--font-size-decay))));
+		--font-size-h6: calc(var(--font-size-root) + calc(var(--font-size-delta) * pow(1 / 6, var(--font-size-decay))));
+		--letter-spacing-delta: calc(var(--letter-spacing-h1) - var(--letter-spacing-h6));
+		--letter-spacing-h2: calc(var(--letter-spacing-h6) + calc(var(--letter-spacing-delta) * pow(5 / 6, var(--letter-spacing-decay))));
+		--letter-spacing-h3: calc(var(--letter-spacing-h6) + calc(var(--letter-spacing-delta) * pow(4 / 6, var(--letter-spacing-decay))));
+		--letter-spacing-h4: calc(var(--letter-spacing-h6) + calc(var(--letter-spacing-delta) * pow(3 / 6, var(--letter-spacing-decay))));
+		--letter-spacing-h5: calc(var(--letter-spacing-h6) + calc(var(--letter-spacing-delta) * pow(2 / 6, var(--letter-spacing-decay))));
+		--font-weight-delta: calc(var(--font-weight-h1) - var(--font-weight-h6));
+		--font-weight-h2: calc(var(--font-weight-h6) + calc(var(--font-weight-delta) * pow(5 / 6, var(--font-weight-decay))));
+		--font-weight-h3: calc(var(--font-weight-h6) + calc(var(--font-weight-delta) * pow(4 / 6, var(--font-weight-decay))));
+		--font-weight-h4: calc(var(--font-weight-h6) + calc(var(--font-weight-delta) * pow(3 / 6, var(--font-weight-decay))));
+		--font-weight-h5: calc(var(--font-weight-h6) + calc(var(--font-weight-delta) * pow(2 / 6, var(--font-weight-decay))));
 	}
 
+	html {
+		font-family: var(--font-stack-sans);
+	}
+
+	pre,
+	code,
+	kbd {
+		font-family: var(--font-stack-monospace);
+	}
+
+	/*
+		BOX SIZING
+	*/
+
+	p,
 	h1,
 	h2,
 	h3,
 	h4,
 	h5,
-	h6 {
-		margin-top: 0.5rem;
-		margin-bottom: 1rem;
-		text-rendering: optimizeLegibility;
-		font-weight: 600;
-		line-height: 1.1;
+	h6,
+	ul,
+	ol,
+	li,
+	dl,
+	dt,
+	dd,
+	table,
+	tbody,
+	th,
+	tr,
+	td,
+	blockquote,
+	a,
+	strong,
+	em,
+	i,
+	u,
+	q,
+	b,
+	s,
+	cite,
+	ins,
+	del,
+	dfn,
+	small,
+	address,
+	figcaption,
+	sub,
+	sup,
+	time,
+	kbd,
+	data,
+	samp,
+	var,
+	button {
+		text-box-trim: trim-both;
+		text-box-edge: cap alphabetic;
+		margin: 0;
 	}
 
-	h1 {
-		font-size: 3rem;
-		line-height: 1.2;
-		font-weight: 800;
-	}
+	/*
+		TEXT STYLES
+	*/
 
-	h2 {
-		font-size: 2.6rem;
-		margin-top: 3rem;
+	a {
+		text-decoration: none;
 	}
 
-	h3 {
-		font-size: 2rem;
-		margin-top: 3rem;
+	[rel=home] {
+		font-weight: bold;
 	}
 
-	h4 {
-		font-size: 1.44rem;
+	table {
+		border-collapse: collapse;
 	}
 
-	h5 {
-		font-size: 1.15rem;
+	time {
+		font-weight: bold;
 	}
 
-	h6 {
-		font-size: 0.96rem;
+	figcaption {
+		font-style: italic;
 	}
 
-	article h1 {
-		font-weight: 600;
-		font-size: 2rem;
+	nav a:where([aria-current='page'], [aria-current='true']),
+	nav a:where([aria-current='page'], [aria-current='true']):hover {
+		cursor: default;
 	}
 
-	@media only screen and (max-width: 720px) {
-		h1 {
-			font-size: 2.5rem;
-		}
-
-		h2 {
-			font-size: 2.1rem;
-		}
+	b,
+	strong {
+		font-weight: bolder;
+	}
 
-		h3 {
-			font-size: 1.75rem;
-		}
 
-		h4 {
-			font-size: 1.25rem;
-		}
+	small {
+		font-size: 80%;
 	}
 
-	p {
-		margin-top: 0;
+	sub,
+	sup {
+		font-size: 75%;
+		line-height: 0;
+		position: relative;
+		vertical-align: baseline;
 	}
 
-	ol,
-	ul {
-		/* padding-left: 0; */
-		margin-top: 0;
+	sub {
+		bottom: -0.25em;
 	}
 
-	ul ul,
-	ul ol,
-	ol ol,
-	ol ul {
-		font-size: 100%;
-		/* margin: 1rem 0 1rem 3rem; */
+	sup {
+		top: -0.5em;
 	}
 
-	/* Extra selector for specificity, see below */
-	li>p:not(:last-child) {
-		margin: 0;
-		padding: 0;
-	}
+	/*
+		CONTENT SPACING
+	*/
 
-	pre,
-	code {
-		font-family:
-			Menlo,
-			Consolas,
-			Monaco,
-			Liberation Mono,
-			Lucida Console,
-			monospace;
+	nav>a {
+		text-wrap: nowrap;
 	}
 
-	code {
-		font-size: 0.9em;
-		margin-inline: 0px;
-		padding: 3px 4px;
-		border-radius: 5px;
-	}
+	/* main */
+	main {
 
-	pre {
-		padding: 1rem 1.5rem;
-		border-radius: 5px;
-		overflow-x: auto;
+		time {
+			display: block;
+		}
 	}
 
-	blockquote {
-		margin: 1.5em 0;
-		padding: 0 1.6em 0 1.6em;
+	main,
+	section {
+
+		row-gap: 2lh;
+		align-items: stretch;
+
+		/* flex layout blocks */
+		&,
+		blockquote,
+		aside,
+		article,
+		figure,
+		nav[aria-label=Contents],
+		ul,
+		ol {
+			display: flex;
+			flex-direction: column;
+		}
+
+
+		/* nav spacing */
+		nav[aria-label=Contents] {
+
+			ol,
+			ol,
+			li {
+				display: flex;
+				flex-direction: column;
+				justify-content: flex-start;
+				line-height: 1.2;
+				gap: 0.8lh;
+			}
+		}
 	}
 
-	a {
-		text-decoration: none;
+	main {
+		row-gap: 1lh;
+
+		&>p {
+			margin-top: 1lh;
+		}
+
+		&>section {
+			margin-top: 1lh;
+		}
 	}
 
-	figcaption {
-		margin-top: 0.5rem;
-		font-style: italic;
+	/* content */
+	section {
+
+		/* image caption space */
+		figure {
+			gap: 1lh;
+		}
+
+		/* list spacing */
+		ul,
+		ol {
+			gap: 1lh;
+
+			/* nested list space */
+			ul,
+			ol {
+				padding-top: 1lh;
+			}
+		}
+
+		/* block spacing */
+		aside,
+		blockquote,
+		article {
+			gap: 1lh;
+			padding: clamp(1lh, 3vh, 1.5lh) clamp(2ch, 2vw, 3ch);
+		}
+
+		/* code spacing */
+		pre {
+			padding: 0.5lh 2ch;
+			overflow-x: auto;
+		}
+
+		/* table spacing */
+		td,
+		th {
+			padding: 0.5lh 2ch;
+			text-align: left;
+
+			&:first-child {
+				padding-left: 0;
+			}
+		}
 	}
 
-	article h2 {
-		margin-top: 2rem;
+	body {
+		display: flex;
+		flex-direction: row;
+
+		&>* {
+			width: 100%;
+		}
 	}
 
-	th,
-	td {
-		padding: 12px 15px;
-		text-align: left;
+	/* sidebar */
+	aside {
+		nav {
+
+			ul,
+			li {
+				display: flex;
+				flex-direction: column;
+				gap: 1.1em;
+			}
+		}
 	}
 
-	th:first-child,
-	td:first-child {
-		padding-left: 0;
+
+	/*
+		FONTS SIZING
+	*/
+
+	body {
+		font-size: var(--font-size-root);
 	}
 
-	th:last-child,
-	td:last-child {
-		padding-right: 0;
+	h1 {
+		font-size: var(--font-size-h1);
+		letter-spacing: var(--letter-spacing-h1);
+		font-weight: var(--font-weight-h1);
+
+		main article &,
+		main aside &,
+		main blockquote & {
+			font-size: var(--font-size-h3);
+		}
 	}
 
-	hr {
-		margin-top: 3rem;
-		margin-bottom: 3.5rem;
-		border-width: 0px;
+	h2 {
+		font-size: var(--font-size-h2);
+		letter-spacing: var(--letter-spacing-h2);
+		font-weight: var(--font-weight-h2);
+
+		main article &,
+		main aside &,
+		main blockquote & {
+			font-size: var(--font-size-h3);
+		}
 	}
 
-	time {
-		display: block;
+	h3 {
+		font-size: var(--font-size-h3);
+		letter-spacing: var(--letter-spacing-h3);
+		font-weight: var(--font-weight-h3);
+
+		main article &,
+		main aside &,
+		main blockquote & {
+			font-size: var(--font-size-h4);
+		}
 	}
 
-	[aria-label=Breadcrumbs] a {
-		font-size: 0.8em;
+	h4 {
+		font-size: var(--font-size-h4);
+		letter-spacing: var(--letter-spacing-h4);
+		font-weight: var(--font-weight-h4);
+
+		main article &,
+		main aside &,
+		main blockquote & {
+			font-size: var(--font-size-h5);
+		}
 	}
 
-	[aria-label=Breadcrumbs]>a:not(:last-child):after {
-		margin-inline: 0.2em;
-		content: '/';
+	h5 {
+		font-size: var(--font-size-h5);
+		letter-spacing: var(--letter-spacing-h5);
+		font-weight: var(--font-weight-h5);
+
+		main article &,
+		main aside &,
+		main blockquote & {
+			font-size: var(--font-size-h6);
+		}
 	}
 
-	nav>a {
-		text-wrap: nowrap;
+	h6 {
+		font-size: var(--font-size-h6);
+		letter-spacing: var(--letter-spacing-h6);
+		font-weight: var(--font-weight-h6);
 	}
 
-	header a[rel=home] {
-		font-weight: 900;
-		font-size: 2.8em;
-		text-box-trim: trim-both;
-		text-box-edge: cap alphabetic;
+	[rel=home] {
+		font-size: var(--font-size-h3);
+		font-weight: var(--font-weight-h1);
+		letter-spacing: var(--letter-spacing-h1);
 	}
 
-	header #tagline {
-		font-weight: 600;
-		font-size: 2.5em;
-		text-box-trim: trim-both;
-		text-box-edge: cap alphabetic;
+
+	ul ul,
+	ul ol,
+	ol ol,
+	ol ul {
+		font-size: inherit;
 	}
 
-	nav a:where([aria-current='page'], [aria-current='true']),
-	nav a:where([aria-current='page'], [aria-current='true']):hover {
-		text-decoration: none;
-		cursor: default;
+	/* main content */
+	main {
+		nav[aria-label=Breadcrumbs] {
+			font-size: 0.8em;
+		}
+
+		code,
+		kbd,
+		samp {
+			font-size: 0.9em;
+		}
 	}
 
-	aside h2 {
-		margin: 0 0 0.5em 0;
-		font-size: 1.1em;
+	/* header */
+	header {
+		a[rel=home] {
+			font-size: 2em;
+		}
 	}
 }

package/systemPaths.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto"
+import os from "node:os"
+import path from "node:path"
+
+/**
+ * The OS-appropriate root for per-application data (not votive-specific
+ * yet - see systemDirectoryFor). Follows the XDG Base Directory spec on
+ * Linux/other POSIX systems, and each platform's own convention
+ * elsewhere - the same rough convention tools like npm/eslint follow
+ * for their own caches.
+ * @returns {string}
+ */
+function systemDataRoot() {
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support")
+  }
+  if (process.platform === "win32") {
+    return process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local")
+  }
+  return process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share")
+}
+
+/**
+ * Computes a per-project system directory, so Vowel doesn't write
+ * `.votive.db`, a buffer cache, or its build output into a project
+ * folder a non-developer end user might be confused by. Keyed by a hash
+ * of the resolved `sourceFolder` path, so two projects never collide
+ * without a manually-assigned project name.
+ *
+ * Vowel's own concern, not votive's: votive takes whatever
+ * `databasePath`/`cacheDirectory`/`targetFolder` a config gives it and
+ * falls back to project-relative defaults otherwise. (It lived in votive
+ * and was exported from there once; nothing in votive ever called it.)
+ * The `sourceFolder` must already be resolved - `resolveProjectFolder`
+ * from votive, whose realpath step is what keeps the same folder reached
+ * through a symlink from hashing to a second directory; config.js does
+ * the two in that order. The `votive` path segment is kept as it was so
+ * existing system directories stay where they are.
+ * @param {string} sourceFolder
+ * @returns {string}
+ */
+function systemDirectoryFor(sourceFolder) {
+  const key = createHash("sha1").update(path.resolve(sourceFolder)).digest("hex").slice(0, 16)
+  const root = systemDataRoot()
+  return path.join(root, "votive", key)
+}
+
+export { systemDirectoryFor }