wip: 2024-08-14T08:34:08+0200 (1723617248)

modules/docs/contribute.php

@@ -1,11 +1,12 @@
-<section class="md">
+<style><?= VV::css("modules/docs/contribute/style.css") ?></style>
+<section class="contribute">
 	<container>
-		<h1>Contribute 💕</h1>
+		<h1>Contribute? 💕</h1>
-		<p>Have you found a problem om this page? Would you like to help make Vegvisir better?</p>
+		<p>Have you found a problem om this page? Would you like to help make this little project a bit better?</p>
 		<ul>
-			<li><a href="/"><button><p>Quick-report a problem on this page</p></button></a></li>
+			<li><a href="/"><button class="solid"><p>Quick-report a problem on this page</p></button></a></li>
-			<li><a href="/"><button><p>Report a bug</p></button></a></li>
+			<li><a href="/"><button class="shade"><p>Report a bug</p></button></a></li>
-			<li><a href="/"><button><p>Learn how to contribute</p></button></a></li>
+			<li><a href="/"><button class="shade"><p>Learn how to contribute</p></button></a></li>
 		</ul>
 	</container>
 </section>

modules/docs/contribute/style.css

@@ -0,0 +1,15 @@
+section.contribute {
+	background-color: rgba(var(--primer-color-deep), .1);
+}
+
+section.contribute container {
+	flex-direction: column;
+}
+
+section.contribute ul {
+	display: flex;
+	padding-left: 0;
+	padding: var(--padding);
+	list-style: none;
+	gap: var(--padding);
+}

modules/docs/legend-js.php

@@ -1,5 +1,5 @@
 <ul>
-	<li><a href="/docs/API/JS/Navigation"><button><p><code>Navigation</code></p></button></a></li>
+	<li><a href="/docs/API/JS/Navigation"><button><p><code>vegvisir.Navigation</code></p></button></a></li>
 	<ul>
 		<p>Instance variables</p>
 		<li><a href="/docs/API/JS/Navigation/abort"><button><p><code>Navigation.abort</code></p></button></a></li>
@@ -12,13 +12,13 @@
 	</ul>
 	<ul>
 		<p>Static variables</p>
-		<li><a href="/docs/API/JS/Navigation/MODE"><button><p><code>Navigation.MODE</code></p></button></a></li>
+		<li><a href="/docs/API/JS/Navigation/MODE"><button><p><code>vegvisir.Navigation.MODE</code></p></button></a></li>
-		<li><a href="/docs/API/JS/Navigation/TARGET"><button><p><code>Navigation.TARGET</code></p></button></a></li>
+		<li><a href="/docs/API/JS/Navigation/TARGET"><button><p><code>vegvisir.Navigation.TARGET</code></p></button></a></li>
-		<li><a href="/docs/API/JS/Navigation/EVENTS"><button><p><code>Navigation.EVENTS</code></p></button></a></li>
+		<li><a href="/docs/API/JS/Navigation/EVENTS"><button><p><code>vegvisir.Navigation.EVENTS</code></p></button></a></li>
-		<li><a href="/docs/API/JS/Navigation/POSITION"><button><p><code>Navigation.POSITION</code></p></button></a></li>
+		<li><a href="/docs/API/JS/Navigation/POSITION"><button><p><code>vegvisir.Navigation.POSITION</code></p></button></a></li>
 	</ul>
 	<ul>
 		<p>Static methods</p>
-		<li><a href="/docs/API/JS/Navigation/bindElements"><button><p><code>Navigation.bindElements()</code></p></button></a></li>
+		<li><a href="/docs/API/JS/Navigation/bindElements"><button><p><code>vegvisir.Navigation.bindElements()</code></p></button></a></li>
 	</ul>
 </ul>

modules/snippet/snippets/docs/API/JS/Navigation/EVENTS/description-additional.js

@@ -0,0 +1,3 @@
+{
+	target: HTMLElement
+}

modules/snippet/snippets/docs/API/JS/Navigation/EVENTS/description.js

@@ -0,0 +1,4 @@
+static Navigation.EVENTS = {
+	STARTED: "navstarted",
+	FINISHED: "navfinished"
+}

modules/snippet/snippets/docs/API/JS/Navigation/EVENTS/example-0-0.js

@@ -0,0 +1,3 @@
+document.addEventListener(vegvisir.Navigation.EVENTS.STARTED, (event) => {
+	console.log(event.detail.target);
+});

modules/snippet/snippets/docs/API/JS/Navigation/MODE/description.js

@@ -0,0 +1,4 @@
+static Navigation.MODE = {
+	REPLACE: "replace",
+	INSERT: "insert"
+}

modules/snippet/snippets/docs/API/JS/Navigation/POSITION/description.js

@@ -0,0 +1,6 @@
+static Navigation.POSITION = {
+	AFTEREND: "afterend",
+	BEFOREEND: "beforeend",
+	AFTERBEGIN: "afterbegin",
+	BEFOREBEGIN: "beforebegin"
+}

modules/snippet/snippets/docs/API/JS/Navigation/TARGET/description.js

@@ -0,0 +1,6 @@
+static Navigation.TARGET = {
+	TOP: "_top",
+	SELF: "_self",
+	BLANK: "_blank",
+	PARENT: "_parent"
+};

modules/snippet/snippets/docs/API/JS/Navigation/TARGET/example-0-0.php

@@ -0,0 +1 @@
+<a href="/some-page" target="_self">Click here to replace this button with the contents of /some-page</a>

modules/snippet/snippets/docs/API/JS/Navigation/TARGET/example-0-1.php

@@ -0,0 +1,4 @@
+<div vv-loading="false" vv-page="/">
+	<p>...</p>
+	<a href="/some-page" target="_parent">Click here to replace this button and its siblings with /some-page</a>	
+</a>

modules/snippet/snippets/docs/API/JS/Navigation/abort/description.js

@@ -0,0 +1 @@
+Navigation.abort: AbortController

modules/snippet/snippets/docs/API/JS/Navigation/bindElements/description.js

@@ -0,0 +1 @@
+static Navigation.bindElements(): void

modules/snippet/snippets/docs/API/JS/Navigation/bindElements/example-0-0.js

@@ -0,0 +1,5 @@
+// The programatically appended anchor tag will not have Vegvisir event listeners on it yet
+document.body.appendChild(document.createElement("a"));
+
+// It will have Vegvisir event listeners after this method is called
+vegvisir.Navigation.bindElements();

modules/snippet/snippets/docs/API/JS/Navigation/constructor/description.js

@@ -0,0 +1,4 @@
+new globalThis.vegvisir.Navigation(
+	URL|String url = window.location,
+	Object options = vegvisir.Navigation.options
+): Navigation

modules/snippet/snippets/docs/API/JS/Navigation/constructor/example-0-0.js

@@ -0,0 +1,2 @@
+// Pathname string with leading slash
+const nav = new vegvisir.Navigation("/some-page");

modules/snippet/snippets/docs/API/JS/Navigation/constructor/example-0-1.js

@@ -0,0 +1,2 @@
+// Pathname string without leading slash and a search parameter
+const nav = new vegvisir.Navigation("some-page?foo=bar");

modules/snippet/snippets/docs/API/JS/Navigation/constructor/example-0-2.js

@@ -0,0 +1,6 @@
+// URL object with a pathname and search parameter
+const url = new URL(window.location);
+url.pathname = "/some-page";
+url.searchParams.set("foo", "bar");
+
+const nav = new vegvisir.Navigation(url);

modules/snippet/snippets/docs/API/JS/Navigation/navigate/0.js

@@ -0,0 +1,4 @@
+const nav = new vegvisir.Navigation("/some-page");
+
+// Will navigate the top shell to /some-page
+nav.navigate();

modules/snippet/snippets/docs/API/JS/Navigation/navigate/1.js

@@ -0,0 +1,5 @@
+const target = document.querySelector("#target");
+const nav = new vegvisir.Navigation("/some-page");
+
+// Will replace the contents of an element with id #target with the contents of /some-page
+nav.navigate(target);

modules/snippet/snippets/docs/API/JS/Navigation/navigate/2.js

@@ -0,0 +1,8 @@
+const target = document.querySelector("#target");
+const nav = new vegvisir.Navigation("/some-page");
+
+// Will place the contents of /some-page after the target element as a sibling
+nav.navigate(target, vegvisir.Navigation.POSITION.AFTEREND);
+
+// Tip: You can also pass an insertAdjacentElement position string directly
+nav.navigate(target, "afterend");

modules/snippet/snippets/docs/API/JS/Navigation/navigate/description.js

@@ -0,0 +1,5 @@
+Navigation.navigate(
+	target: HTMLELement = Navigation.#rootShellElement
+	position: Navigation.POSITION = Navigation.POSITION.BEFOREEND,
+	mode: Navigation.MODE = Navigation.MODE.REPLACE
+): void 

modules/snippet/snippets/docs/API/JS/Navigation/navigate/example-0-0.js

@@ -0,0 +1,6 @@
+const target = document.querySelector("#update-this-element");
+const button = document.querySelector("#click-me-to-refresh");
+
+const nav = new vegvisir.Navigation("/page-with-new-content");
+
+button.addEventListener("click", () => nav.navigate(target));

modules/snippet/snippets/docs/API/JS/Navigation/options/description.js

@@ -0,0 +1,3 @@
+{
+	pushHistory: boolean
+}

modules/snippet/snippets/docs/API/PHP/VV/embed/example-1-0.css

@@ -1,6 +0,0 @@
-/* File: /var/www/my-website/public/assets/css/style.css */
-
-p {
-	color: blue;
-	background-color: red;
-}

modules/snippet/snippets/docs/API/PHP/VV/embed/example-1-0.php

@@ -0,0 +1,3 @@
+/* File: /var/www/my-website/public/assets/media/logo.svg */
+
+<svg viewBox="0 0 0 0" xmlns="http://www.w3.org/2000/svg">...</svg>

modules/snippet/snippets/docs/API/PHP/VV/embed/example-1-1.php

@@ -1,4 +1,5 @@
-// File: /var/www/my-website/public/index.php
+// File: /var/www/my-website/shells/document.php
 
-<style><?= VV::js("public/assets/css/style.css") ?></style>
+<header>
-<p>Some content...</p>
+	<?= VV::embed("public/assets/media/logo.svg") ?>
+</header>

modules/snippet/snippets/docs/API/PHP/VV/include/example-1-0.css

@@ -1,6 +0,0 @@
-/* File: /var/www/my-website/public/assets/css/style.css */
-
-p {
-	color: blue;
-	background-color: red;
-}

modules/snippet/snippets/docs/API/PHP/VV/include/example-1-0.php

@@ -0,0 +1,5 @@
+/* File: /var/www/my-website/modules/banner.php */
+
+<banner>
+	<p>Important text!</p>
+</banner>

modules/snippet/snippets/docs/API/PHP/VV/include/example-1-1.php

@@ -1,4 +1,6 @@
 // File: /var/www/my-website/public/index.php
 
-<style><?= VV::js("public/assets/css/style.css") ?></style>
+<header>
-<p>Some content...</p>
+	<p>Some header content</p>
+	<?= VV::include("modules/banner") ?>
+</header>

public/assets/css/document.css

@@ -66,8 +66,6 @@ h3 {
 	font-size: 18px;
 }
 
-/* ## Sections */
-
 /* ## Container */
 
 container {
@@ -113,6 +111,10 @@ button.solid {
 	background-color: var(--color-deep);
 }
 
+button.shade {
+	background-color: rgba(0, 0, 0, .05);
+}
+
 @media (hover: hover) {
 	button:hover {
 		background-color: rgba(0, 0, 0, .05);
@@ -126,6 +128,21 @@ button.solid {
 
 /* # Content */
 
+/* ## Runners */
+
+:is(header, footer) ul {
+	display: flex;
+	padding-left: 0;
+	list-style: none;
+	gap: var(--padding);
+}
+
+:is(header, footer) ul:last-child {
+	margin-left: auto;
+}
+
+/* ### Header */
+
 header {
 	--border-width: 2px;
 
@@ -144,21 +161,18 @@ header .logo {
 	background-color: var(--color-deep);
 }
 
-header ul {
-	display: flex;
-	padding-left: 0;
-	list-style: none;
-	gap: var(--padding);
-}
-
-header ul:last-child {
-	margin-left: auto;
-}
-
 [vv-top-page="/help"] header a[href="/help"] button,
 [vv-top-page^="/docs"] header a[href="/docs"] button,
 [vv-top-page="/demos"] header a[href="/demos"] button,
 [vv-top-page="/why"] header a[href="/why"] button {
 	font-weight: bold;
 	background-color: rgba(0, 0, 0, .05);
+}
+
+/* ### Footer */
+
+footer {
+	padding: var(--padding);
+	color: var(--color-light);
+	background-color: var(--color-deep);
 }

public/assets/css/shells/docs.css

@@ -1,3 +1,7 @@
+body {
+	background-color: rgba(var(--primer-color-deep), .01);
+}
+
 [vv-shell-id="/"] {
 	display: grid;
 	min-height: calc(100svh - var(--running-size) - var(--border-style-width));

public/docs/API/JS/Navigation/EVENTS.php

@@ -0,0 +1,76 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 3)</p>
+		<h1><code>vegvisir.Navigation.EVENTS</code></h1>
+		<p>Various navigation <a href="https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent" target="_blank"><code>CustomEvent</code></a>s that can be listened for.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/EVENTS/description", Snippet::JAVASCRIPT) ?>
+		<p>All events will also fire on <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document" target="_blank"><code>document</code></a> as a catch-all interface.</p>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Values</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>navstarted</code></h3>
+		<p>This <a href=""><code>CustomEvent</code></a> will be fired on the navigation <a href=""><code>target</code></a> and <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document" target="_blank"><code>document</code></a> when a navigation is started with <a href=""><code>.navigate()</code></a>.</p>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>navfinished</code></h3>
+		<p>This <a href=""><code>CustomEvent</code></a> will be fired on the navigation <a href=""><code>target</code></a> and <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document" target="_blank"><code>document</code></a> when a navigation with <a href=""><code>.navigate()</code></a> has finished completely.</p>
+		<p>A navigation is considered finished when the page has been fully loaded and all <a href="">element attributes</a> have been updated.</p>
+	</container>
+</section>
+
+<section class="md">
+	<container>
+		<h1><code>CustomEvent.detail</code> property</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/EVENTS/description-additional", Snippet::JAVASCRIPT) ?>
+		<p>Accessing the <a href="https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail" target="_blank"><code>.detail</code></a> property on a captured Vegvisir event will contain the following object.</p>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Values</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>target</code></h3>
+		<p>The <a href=""><code>target</code></a> element that is used/was used for the navigation.</p>
+	</container>
+</section>
+
+<?php // Examples ?>
+<section class="md">
+	<container>
+		<h1>Examples</h1>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h2>Basic usage</h2>
+		<p>This example logs the <a href=""><code>target</code></a> element of all navigations on this page.</p>
+		<?= Snippet::put("docs/API/JS/Navigation/EVENTS/example-0-0", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/MODE.php

@@ -0,0 +1,52 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 3)</p>
+		<h1><code>vegvisir.Navigation.MODE</code></h1>
+		<p>Change if content should be replaced or inserted when used in <a href=""><code>.navigate()</code></a>.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/MODE/description", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Values</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>REPLACE</code></h3>
+		<p>Content of the destination URL will replace the content at <a href=""><code>vegvisir.Navigation.POSITION</code></a>.</p>
+		<ul>
+			<li><p>Position: <code>beforebegin</code> = Replace the <a href=""><code>target</code></a> element itself.</p></li>
+			<li><p>Position: <code>afterbegin</code> = Replace the inner contents of the <a href=""><code>target</code></a> element.</li>
+			<li><p>Position: <code>beforeend</code> = Replace the inner contents of the <a href=""><code>target</code></a> element.</li>
+			<li><p>Position: <code>afterend</code> = Replace the <a href=""><code>target</code></a> element itself.</p></li>
+		</ul>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>INSERT</code></h3>
+		<p>Content of the destination URL will append/prepend to the existing content at <a href=""><code>vegvisir.Navigation.POSITION</code></a>.</p>
+		<p>Setting the mode to <code>INSERT</code> will make <a href=""><code>.navigate()</code></a> behave exactly like <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentElement"><code>HTMLElement.insertAdjacentElement()</code></a>.</p>
+		<ul>
+			<li><p>Position: <code>beforebegin</code> = Prepend before the <a href=""><code>target</code></a> element itself.</p></li>
+			<li><p>Position: <code>afterbegin</code> = Prepend just inside the <a href=""><code>target</code></a> element, before its first child.</p></li>
+			<li><p>Position: <code>beforeend</code> = Append just inside the <a href=""><code>target</code></a> element, after its last child.</p></li>
+			<li><p>Position: <code>afterend</code> = Append after the <a href=""><code>target</code></a> element itself.</p></li>
+		</ul>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/POSITION.php

@@ -0,0 +1,66 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 3)</p>
+		<h1><code>vegvisir.Navigation.POSITION</code></h1>
+		<p>Change where content should be placed when <a href=""><code>.navigate()</code></a> is used.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/POSITION/description", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Values</h2>
+		<p>The effect of <code>Navigation.POSITION</code> depend on the <a href=""><code>Navigation.MODE</code></a> used for the current navigation.</p>
+		<p>The default <code>Navigation.POSITION</code> for <a href=""><code>.navigate()</code></a> is <a href=""><code>beforeend</code></a> and the default mode is <a href=""><code>replace</code></a>.</p>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>afterend</code></h3>
+		<ul>
+			<li><p>Mode: <code>replace</code> = Replace the <a href=""><code>target</code></a> element itself.</li>
+			<li><p>Mode: <code>insert</code> = Append after the <a href=""><code>target</code></a> element itself.</p></li>
+		</ul>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>beforeend</code></h3>
+		<p>This is the default position for <a href=""><code>.navigate()</code></a>.</p>
+		<ul>
+			<li><p>Mode: <code>replace</code> = Replace the inner contents of the <a href=""><code>target</code></a> element.</li>
+			<li><p>Mode: <code>insert</code> = Append just inside the <a href=""><code>target</code></a> element, after its last child.</p></li>
+		</ul>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>afterbegin</code></h3>
+		<ul>
+			<li><p>Mode: <code>replace</code> = Replace the inner contents of the <a href=""><code>target</code></a> element.</li>
+			<li><p>Mode: <code>insert</code> = Prepend just inside the <a href=""><code>target</code></a> element, before its first child.</p></li>
+		</ul>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>beforebegin</code></h3>
+		<ul>
+			<li><p>Mode: <code>replace</code> = Replace the <a href=""><code>target</code></a> element itself.</p></li>
+			<li><p>Mode: <code>insert</code> = Prepend before the <a href=""><code>target</code></a> element itself.</p></li>
+		</ul>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/TARGET.php

@@ -0,0 +1,78 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 3)</p>
+		<h1><code>vegvisir.Navigation.TARGET</code></h1>
+		<p>Defines the <a href=""><code>target</code></a> element of a navigation triggered from a <a href="">bound element</a>.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/TARGET/description", Snippet::JAVASCRIPT) ?>
+		<p>This object follows the same syntax as the <code>target</code> attribute of <a href=""><code>HTMLAnchorElement</code></a>.</p>
+		<p>If a string is provided to a <code>target</code> attribute of the <a href="">bound element</a> that <strong>isn't</strong> in this enumerable, the string will be treated as a <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors" target="_blank">CSS selector</a>.</p>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Values</h2>
+		<p>These values correspond to the value of a <code>target</code> attribute on a <a href="">bound element</a>.</p>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>_top</code></h3>
+		<p>Target <a href=""><code>vegvisir.Navigation.rootShellElement</code></a>. This is the same as performing a normal soft-navigation.</p>
+		<p>This is the default behavior if a <code>target</code> attribute is omitted or equals an empty string.</p>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>_self</code></h3>
+		<p>Target the <a href="">bound element</a> itself with the defaults <a href=""><code>vegvisir.Navigation.POSITION.BEFOREEND</code></a> and <a href=""><code>vegvisir.Navigation.MODE.REPLACE</code></a>, which will replace the <a href="">bound element</a> itself with the contents of the destination URL.</p>
+		<p>The default position and mode behavior can be overridden with by setting a <a href=""><code>vv-position</code></a> and <a href=""><code>vv-mode</code></a> attribute on the <a href="">bound element</a> respectivly.</p>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>_blank</code></h3>
+		<p>Default browser behavior. The destination URL will open in a new tab or window.</p>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>_parent</code></h3>
+		<p>Target the closest parent <a href="">HTMLElement</a> that has a <a href=""><code>vv-page</code></a> attribute.</p>
+		<p><a href=""><code>vegvisir.Navigation.rootShellElement</code></a> will become the target if no parent is found.</p>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3>default</h3>
+		<p>The value of the <a href="">bound element</a>'s <code>target</code> attribute will be treated as a <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors" target="_blank">CSS selector</a> if the string value does not equal an entry in this enumerable.</p>
+	</container>
+</section>
+
+<?php // Examples ?>
+<section class="md">
+	<container>
+		<h1>Examples</h1>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h2>Basic usage</h2>
+		<p>Here's an example that uses a native anchor tag to do various navigations.</p>
+		<?= Snippet::put("docs/API/JS/Navigation/TARGET/example-0-0", Snippet::PHP) ?>
+		<?= Snippet::put("docs/API/JS/Navigation/TARGET/example-0-1", Snippet::PHP) ?>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/abort.php

@@ -0,0 +1,34 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 2, Vegvisir 3)</p>
+		<h1><code>Navigation.abort</code></h1>
+		<p>Interrupt a navigation started with <a href=""><code>.navigate()</code></a>.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/abort/description", Snippet::JAVASCRIPT) ?>
+		<p><code>Navigation.abort</code> is an instance of <a href="https://developer.mozilla.org/en-US/docs/Web/API/AbortController">AbortController</a> which gets contructed automatically with new <a href=""><code>vegvisir.Navigation</code></a> instances.</p>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Parameters</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>.abort()</code></h3>
+		<p>Call <code>Navigation.abort.abort()</code> to interrupt a Vegvisir navigation in progress.</p>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/bindElements.php

@@ -0,0 +1,36 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 2, Vegvisir 3)</p>
+		<h1><code>vegvisir.Navigation.bindElements()</code></h1>
+		<p>Trigger automatic binding of unbound tags.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/bindElements/description", Snippet::JAVASCRIPT) ?>
+		<p>Bind event listeners for <a href=""><code>HTMLAnchorElement</code></a> tags and other tags with a <a href=""><code>vv</code></a> attribute that haven't already been bound.</p>
+		<p>This method is runned automatically after a finished Vegvisir navigation.</p>
+	</container>
+</section>
+
+<?php // Examples ?>
+<section class="md">
+	<container>
+		<h1>Examples</h1>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h2>Basic usage</h2>
+		<p>In this example we will programatically create and append an anchor tag to the DOM and use this method to bind it.</p>
+		<?= Snippet::put("docs/API/JS/Navigation/bindElements/example-0-0", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/constructor.php

@@ -0,0 +1,70 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 2, Vegvisir 3)</p>
+		<h1><code>vegvisir.Navigation()</code> constructor</h1>
+		<p>The Vegvisir navigation constructor is used to create a new instance of <code>Navigation</code>. This is the first step to creating a custom navigation.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/constructor/description", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Parameters</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>url</code></h3>
+		<p>A <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/URL"><code>URL</code></a> object or string with to a location on the same origin as the initiator.</p>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>options</code></h3>
+		<p>An optional object containing <a href=""><code>vegvisir.Navigation.options</code></a> overrides.</p>
+	</container>
+</section>
+
+<?php // Method return values ?>
+<section class="md">
+	<container>
+		<h2>Return values</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>Navigation</code> instance</h3>
+		<p>A <code>Navigation</code> object instance. Use the instance method <a href=""><code>.navigate()</code></a> to navigate an, or many element(s) in the DOM.</p>
+	</container>
+</section>
+
+<?php // Examples ?>
+<section class="md">
+	<container>
+		<h1>Examples</h1>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h2>Basic usage</h2>
+		<p>Different ways to initialize <code>vegvisir.Navigation</code> with a location that will open <code>/public/some-page.php</code> relative from <a href="">project root</a>.</p>
+		<p>With strings:</p>
+		<?= Snippet::put("docs/API/JS/Navigation/constructor/example-0-0", Snippet::JAVASCRIPT) ?>
+		<?= Snippet::put("docs/API/JS/Navigation/constructor/example-0-1", Snippet::JAVASCRIPT) ?>
+		<p>With URL objects:</p>
+		<?= Snippet::put("docs/API/JS/Navigation/constructor/example-0-2", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/index.php

@@ -0,0 +1,13 @@
+<section class="md">
+	<container>
+		<h1><code>vegvisir.Navigation</code></h1>
+		<p>The Vegvisir <code>Navigation</code> class contains APIs for triggering navigations of any element programmatically.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h2>Quickstart</h2>
+		<p>A new navigation can be initialized by constructing the <code>vegvisir.Navigation</code> class.</p>
+	</container>
+</section>
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/navigate.php

@@ -0,0 +1,93 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 2, Vegvisir 3)</p>
+		<h1><code>Navigation.navigate()</code></h1>
+		<p>Perform a soft-navigation on an element.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/navigate/description", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Parameters</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>target</code></h3>
+		<p>An optional instance of an <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement" target="_blank"><code>HTMLElement</code></a> which will be the target of this navigation.</p>
+		<p><a href=""><code>Vegivisr.rootShellElement</code></a> will be used if no argument is passed to this parameter.</p>
+		<details>
+			<summary>Examples</summary>
+			<p>Passing nothing to this parameter will target the top shell. This would be equivalent to clicking a link.</p>
+			<?= Snippet::put("docs/API/JS/Navigation/navigate/0", Snippet::JAVASCRIPT) ?>
+			<p>Passing an <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement" target="_blank"><code>HTMLElement</code></a> to this parameter would in this example with no other arguments changed, replace the innerHTML of the target element with the response from <code>/some-page</code>.</p>
+			<?= Snippet::put("docs/API/JS/Navigation/navigate/1", Snippet::JAVASCRIPT) ?>
+		</details>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>position</code></h3>
+		<p>This parameter takes an optional <a href=""><code>Navigation.POSITION</code></a> string which can be used to change where content from the destination URL should be placed relative to the <a href=""><code>target</code></a> element.</p>
+		<details>
+			<summary>Examples</summary>
+			<p>Passing nothing to this parameter will replace the innerHTML of <a href=""><code>target</code></a>.</p>
+			<?= Snippet::put("docs/API/JS/Navigation/navigate/1", Snippet::JAVASCRIPT) ?>
+			<p>Passing an position string will in this example place the contents afterEnd from target.</p>
+			<?= Snippet::put("docs/API/JS/Navigation/navigate/2", Snippet::JAVASCRIPT) ?>
+		</details>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>mode</code></h3>
+		<p>This parameter takes an optional <a href=""><code>Navigation.MODE</code></a> string which can be used to change how the contents of the destination URL should be placed relative to existing content around the <a href=""><code>target</code></a> element.</p>
+	</container>
+</section>
+
+<?php // Method return values ?>
+<section class="md">
+	<container>
+		<h2>Return values</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<p>This method will not return anything, but a navigation in progress can be aborted with <a href=""><code>Navigation.abort</code></a>.</p>
+	</container>
+</section>
+
+<?php // Examples ?>
+<section class="md">
+	<container>
+		<h1>Examples</h1>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h2>Basic usage</h2>
+		<p>Programmatically invoke a top navigation - as if a user clicked a link.</p>
+		<?= Snippet::put("docs/API/JS/Navigation/navigate/0", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h2>Click to refresh</h2>
+		<p>An example how a simple "click to refresh" button can be implemented.</p>
+		<?= Snippet::put("docs/API/JS/Navigation/navigate/example-0-0", Snippet::JAVASCRIPT) ?>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/Navigation/options.php

@@ -0,0 +1,65 @@
+<?= VV::include("modules/snippet/Snippet.php") ?>
+<?php // General information ?>
+<section class="md">
+	<container>
+		<p>(Vegvisir 2, Vegvisir 3)</p>
+		<h1><code>Navigation.options</code></h1>
+		<p>Override default Vegvisir navigation behavior.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h1>Description</h1>
+		<?= Snippet::put("docs/API/JS/Navigation/options/description", Snippet::JAVASCRIPT) ?>
+		<p>This object should be passed as the second argument when constructing a <a href=""><code>vegvisir.Navigation</code></a> instance.</p>
+	</container>
+</section>
+
+<?php // Method parameters ?>
+<section class="md">
+	<container>
+		<h2>Parameters</h2>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h3><code>pushHistory</code></h3>
+		<p><strong>This option has no default value:</strong></p>
+		<p>The default behavior of any Vegvisir <strong>top</strong> navigation is to push the new URL to the history stack. Ie. History API entry and browser pathname changes.</p>
+		<p>Any navigation that is <strong>not</strong> a top navigation will not push to the history stack.</p>
+		<hr>
+		<p>By setting the <code>pushHistory</code> option to:</p>
+		<ul>
+			<li>
+				<p><code>true</code></p>
+				<p>Force all navigations with <a href=""><code>.navigate()</code></a> on this instance will push to the history stack. Including non-top navigations.</p>
+			</li>
+			<li>
+				<p><code>false</code></p>
+				<p>Force no navigations with <a href=""><code>.navigate()</code></a> on this instance will push to the history stack. Including top navigations.</p>
+			</li>
+		</ul>
+	</container>
+</section>
+
+<?php // Examples ?>
+<section class="md">
+	<container>
+		<h1>Examples</h1>
+	</container>
+</section>
+<section class="md inset">
+	<container>
+		<h2>Basic usage</h2>
+		<p>Here is an example the embeds an SVG file directly on a page.</p>
+		<p>This can come in handy for inlining small vector icons.</p>
+		<?= Snippet::put("docs/API/PHP/VV/embed/example-1-0", Snippet::PHP) ?>
+		<?= Snippet::put("docs/API/PHP/VV/embed/example-1-1", Snippet::PHP) ?>
+		<p>By using <code>VV::css()</code> inside a <code class="tag">style</code>, we've enabled this stylesheet for that specific page.</p>
+	</container>
+</section>
+
+<?php // Contribute ?>
+<?= VV::include("modules/docs/contribute") ?>
+
+<?= VV::shell("shells/docs") ?>

public/docs/API/JS/index.php

@@ -1 +1,14 @@
+<section class="md">
+	<container>
+		<h1>JavaScript Cheat Sheet</h1>
+		<p>Vegvisir will automatically bind <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement"><code>HTMLAnchorElement</code></a> tags and perform soft-navigation between pages on the same <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin" target="_blank">origin</a>.</p>
+		<p>The <a href=""><code>Navigation</code></a> lets you interact with, and expand Vegvisirs front-end behavior.</p>
+	</container>
+</section>
+<section class="md">
+	<container>
+		<h2>Manual pages</h2>
+		<?= VV::include("modules/docs/legend-js") ?>
+	</container>
+</section>
 <?= VV::shell("shells/docs") ?>

public/docs/API/PHP/VV/embed.php

@@ -59,9 +59,9 @@
 	<container>
 		<h2>Basic usage</h2>
 		<p>Here is an example the embeds an SVG file directly on a page.</p>
-		<p>This can come in handy for small icons stored in a separate directory as an example.</p>
+		<p>This can come in handy for inlining small vector icons.</p>
-		<?= Snippet::put("docs/API/PHP/VV/css/example-1-0", Snippet::CSS) ?>
+		<?= Snippet::put("docs/API/PHP/VV/embed/example-1-0", Snippet::PHP) ?>
-		<?= Snippet::put("docs/API/PHP/VV/css/example-1-1", Snippet::PHP) ?>
+		<?= Snippet::put("docs/API/PHP/VV/embed/example-1-1", Snippet::PHP) ?>
 		<p>By using <code>VV::css()</code> inside a <code class="tag">style</code>, we've enabled this stylesheet for that specific page.</p>
 	</container>
 </section>

public/docs/API/PHP/VV/include.php

@@ -64,10 +64,11 @@
 <section class="md inset">
 	<container>
 		<h2>Basic usage</h2>
-		<p>Let's take the following CSS stylesheet file and put it into a page.</p>
+		<p>Consider the following page snippet</p>
-		<?= Snippet::put("docs/API/PHP/VV/css/example-1-0", Snippet::CSS) ?>
+		<?= Snippet::put("docs/API/PHP/VV/include/example-1-0", Snippet::PHP) ?>
-		<?= Snippet::put("docs/API/PHP/VV/css/example-1-1", Snippet::PHP) ?>
+		<p>Let's put this snippet into another page</p>
-		<p>By using <code>VV::css()</code> inside a <code class="tag">style</code>, we've enabled this stylesheet for that specific page.</p>
+		<?= Snippet::put("docs/API/PHP/VV/include/example-1-1", Snippet::PHP) ?>
+		<p>By importing the snippet with <code>VV::include()</code> we have placed the <code class="tag">banner</code> tag and its contents into another page.</p>
 	</container>
 </section>
 

public/docs/index.php

@@ -12,4 +12,5 @@
 		<p>The older versions of Vegvisir can be found here. They lack proper documentation and function a bit differently than Vegvisir 3 which has been largely rewritten from scratch. The main addition to version 3 are what I call "shells".</p>
 	</container>
 </section>
+<?= VV::include("modules/docs/contribute") ?>
 <?= VV::shell("shells/docs") ?>

public/docs/installation.php

@@ -82,4 +82,5 @@
 		<p>Let's add the following <code>location</code> block to our NGINX virtual host that we set up in <a href="#asd">Step X</a>.</p>
 	</container>
 </section>
+<?= VV::include("modules/docs/contribute") ?>
 <?= VV::shell("shells/docs") ?>

shells/document.php

@@ -57,6 +57,17 @@
 		</container>
 	</header>
 	<vv-shell></vv-shell>
+	<footer>
+		<container>
+			<p>Copyleft 2024 - All rights reversed</p>
+			<ul>
+				<li><a href="https://vlw.se"><button><p>VLW</p></button></a></li>
+				<li><a href="https://codeberg.org/vegvisir/vegvisir/src/branch/master/LICENSE"><button><p>License</p></button></a></li>
+				<li><a href="https://codeberg.org/vegvisir/website"><button><p>Website</p></button></a></li>
+				<li><a href="/"><button class="shade"><p>Contribute ❤️</p></button></a></li>
+			</ul>
+		</container>
+	</footer>
 	<?= VV::init(); ?>
 </body>
 </html>