From effccd59011ce122fc74531470ce037c95bcaa48 Mon Sep 17 00:00:00 2001 From: absurdprofit Date: Thu, 23 Jan 2025 08:49:36 -0500 Subject: [PATCH 1/3] Initial content for anchor extension section --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 28e5545..80eb97f 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,7 @@ backButtonEl.addEventListener("click", () => { - [Notifications on entry disposal](#notifications-on-entry-disposal) - [Current entry change monitoring](#current-entry-change-monitoring) - [Complete event sequence](#complete-event-sequence) + - [Extensions to the Anchor Element](#extensions-to-the-anchor-element) - [Guide for migrating from the existing history API](#guide-for-migrating-from-the-existing-history-api) - [Performing navigations](#performing-navigations) - [Warning: back/forward are not always opposites](#warning-backforward-are-not-always-opposites) @@ -1033,6 +1034,19 @@ The commit steps are: 1. Any now-unreachable `NavigationHistoryEntry` instances fire `dispose`. 1. The URL bar updates. +### Extensions to the Anchor element +Currently an `` only supports push navigations, which leaves a lot to be desired. This proposal aims to extend its existing behaviour with a few new and existing attributes. +Namely: +- `replace="", reload=""` and `traverse=""` as boolean attributes. +- `navigateinfo=""` and `navigatestate=""` as string attributes. +- `href="..."` and `rel="next/prev"` with the addition of the string attribute `key="..."` as traversal hints. + +The default navigation type of a `` is always a push navigation. The new boolean attributes `replace="", reload=""` and `traverse=""` serve as the default navigation type modifier. +When using the `traverse=""` navigation type modifier the `rel="next/prev"`, `key="..."` and `href="..."` attributes, become optional hints. + +#### Default navigation type +The `replace=""` attribute in addition to the `href="..."` attribute will replace the current entry with a new history entry with the resolved href as the URL. + ## Guide for migrating from the existing history API For web developers using the API, here's a guide to explain how you would replace usage of `window.history` with `window.navigation`. From 7db74d32befc269600ff85790b98a1428cb8538d Mon Sep 17 00:00:00 2001 From: absurdprofit Date: Thu, 23 Jan 2025 19:22:12 -0500 Subject: [PATCH 2/3] Updated extended anchor section --- README.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 83 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 80eb97f..f6d2ff0 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,10 @@ backButtonEl.addEventListener("click", () => { - [Notifications on entry disposal](#notifications-on-entry-disposal) - [Current entry change monitoring](#current-entry-change-monitoring) - [Complete event sequence](#complete-event-sequence) - - [Extensions to the Anchor Element](#extensions-to-the-anchor-element) + - [Extensions to the Anchor element](#extensions-to-the-anchor-element) + - [Default navigation type](#default-navigation-type) + - [The navigateinfo="..." and navigatestate="..." attributes](#the-navigateinfo-and-navigatestate-attributes) + - [Additional example](#additional-example) - [Guide for migrating from the existing history API](#guide-for-migrating-from-the-existing-history-api) - [Performing navigations](#performing-navigations) - [Warning: back/forward are not always opposites](#warning-backforward-are-not-always-opposites) @@ -1035,17 +1038,90 @@ The commit steps are: 1. The URL bar updates. ### Extensions to the Anchor element -Currently an `` only supports push navigations, which leaves a lot to be desired. This proposal aims to extend its existing behaviour with a few new and existing attributes. +Currently an `` only supports push navigations. This proposal aims to extend its existing behaviour with a few new and existing attributes. Namely: -- `replace="", reload=""` and `traverse=""` as boolean attributes. +- `reload=""`, `replace=""` and `traverse=""` as boolean attributes. - `navigateinfo=""` and `navigatestate=""` as string attributes. - `href="..."` and `rel="next/prev"` with the addition of the string attribute `key="..."` as traversal hints. -The default navigation type of a `` is always a push navigation. The new boolean attributes `replace="", reload=""` and `traverse=""` serve as the default navigation type modifier. -When using the `traverse=""` navigation type modifier the `rel="next/prev"`, `key="..."` and `href="..."` attributes, become optional hints. - #### Default navigation type -The `replace=""` attribute in addition to the `href="..."` attribute will replace the current entry with a new history entry with the resolved href as the URL. +The default navigation type of a `` is always a push navigation. The new boolean attributes `replace=""`, `reload=""` and `traverse=""` serve as the default navigation type modifier. + +The default navigation type will still be a push navigation. +```html +Posts +``` + +The `reload=""` attribute will reload the current entry. Note: the `href=""` attribute is ignored. +```html +Refresh results +``` + +The `replace=""` attribute in addition to the `href="..."` attribute will replace the current entry with a new history entry. +```html +Logout +``` +The `traverse=""` attibute allows ``s to link to existing entries. When using the `traverse=""` navigation type modifier the `rel="next/prev"`, `key="..."` and `href="..."` attributes, become optional hints. +The `rel="..."` is an existing attribute that hints at the relationship of the linked URL to the current document. When used with `traverse=""` it serves as a directional hint. +```html + + +``` +The `href="..."` is an existing attribute that specifies the URL the `` points to. When used with the `traverse=""` attribute the anchor will point to the closest entry with a matching URL. The `rel="next/prev"` attribute can be used to specify the search direction. +```html +Tab 1 + + +``` +The `key="..."` is a new attribute that allows you to specify a history entry key the `` points to. This attribute only works with the `traverse=""` attribute and is ignored otherwise. If no matching entry is found the behaviour is the same as `Dead link`. +```html +Go to 7c6a6481-c4bc-40f5-9617-0287441a3418 +``` +The `key="..."` attribute takes precedence over `href=""` meaning if an entry with a matching key isn't found, the anchor will fallback to traversal with the `href="..."` hint. +```html +Go home +``` + +The `traverse=""` boolean attribute will always take precedence over push, replace and reload navigation types. Meaning if no matching entry is found the `` will fallback to the next navigation type. +```html + +``` + +#### The `navigateinfo="..."` and `navigatestate="..."` attributes +Finally two string attributes have been added for passing state and info via an ``. +```html +Home +``` +The new attributes will have corresponding DOM properties for passing non-string data types to entries. +```js +const a = document.getElementById("home"); +a.navigatestate = { + user: { + name: "John Doe", + }, +}; +a.navigateinfo = { + type: "push", +}; +``` + +Note: `navigatestate=""` is ignored for traverse navigations. +```html +Home +Refresh +Logout + +``` + +#### Additional Example +Tabbed navigation could be implemented without JavaScript. By using `traverse=""` anchors will point to existing entries if they exist but fallback to a push navigation if a matching entry doesn't already exist. +```html + +``` ## Guide for migrating from the existing history API From 5fb8b526f0e56fcb7fc0613f703146f0ca4e0f1c Mon Sep 17 00:00:00 2001 From: absurdprofit Date: Thu, 23 Jan 2025 20:56:19 -0500 Subject: [PATCH 3/3] Fixed tab example in extended anchor section --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f6d2ff0..f8bd877 100644 --- a/README.md +++ b/README.md @@ -1118,8 +1118,8 @@ Tabbed navigation could be implemented without JavaScript. By using `traverse="" ```html ```