docs(no-navigation-without-resolve): update rule documentation (#1479)

Co-authored-by: Marek Dědič <developer@dedic.eu>

Author: sacrosanctic

README.md

@@ -370,7 +370,7 @@ These rules relate to SvelteKit and its best Practices.
 | Rule ID | Description |    |
 |:--------|:------------|:---|
 | [svelte/no-export-load-in-svelte-module-in-kit-pages](https://sveltejs.github.io/eslint-plugin-svelte/rules/no-export-load-in-svelte-module-in-kit-pages/) | disallow exporting load functions in `*.svelte` module in SvelteKit page components. | :star: |
-| [svelte/no-navigation-without-resolve](https://sveltejs.github.io/eslint-plugin-svelte/rules/no-navigation-without-resolve/) | disallow using navigation (links, goto, pushState, replaceState) without a resolve() | :star: |
+| [svelte/no-navigation-without-resolve](https://sveltejs.github.io/eslint-plugin-svelte/rules/no-navigation-without-resolve/) | disallow internal navigation (links, `goto()`, `pushState()`, `replaceState()`) without a `resolve()` | :star: |
 | [svelte/valid-prop-names-in-kit-pages](https://sveltejs.github.io/eslint-plugin-svelte/rules/valid-prop-names-in-kit-pages/) | disallow props other than data or errors in SvelteKit page components. | :star: |
 
 ## Experimental

docs/rules.md

@@ -118,11 +118,11 @@ These rules extend the rules provided by ESLint itself, or other plugins to work
 
 These rules relate to SvelteKit and its best Practices.
 
-| Rule ID                                                                                                        | Description                                                                          |        |
-| :------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :----- |
-| [svelte/no-export-load-in-svelte-module-in-kit-pages](./rules/no-export-load-in-svelte-module-in-kit-pages.md) | disallow exporting load functions in `*.svelte` module in SvelteKit page components. | :star: |
-| [svelte/no-navigation-without-resolve](./rules/no-navigation-without-resolve.md)                               | disallow using navigation (links, goto, pushState, replaceState) without a resolve() | :star: |
-| [svelte/valid-prop-names-in-kit-pages](./rules/valid-prop-names-in-kit-pages.md)                               | disallow props other than data or errors in SvelteKit page components.               | :star: |
+| Rule ID                                                                                                        | Description                                                                                           |        |
+| :------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :----- |
+| [svelte/no-export-load-in-svelte-module-in-kit-pages](./rules/no-export-load-in-svelte-module-in-kit-pages.md) | disallow exporting load functions in `*.svelte` module in SvelteKit page components.                  | :star: |
+| [svelte/no-navigation-without-resolve](./rules/no-navigation-without-resolve.md)                               | disallow internal navigation (links, `goto()`, `pushState()`, `replaceState()`) without a `resolve()` | :star: |
+| [svelte/valid-prop-names-in-kit-pages](./rules/valid-prop-names-in-kit-pages.md)                               | disallow props other than data or errors in SvelteKit page components.                                | :star: |
 
 ## Experimental
 

docs/rules/no-navigation-without-resolve.md

@@ -2,41 +2,53 @@
 pageClass: 'rule-details'
 sidebarDepth: 0
 title: 'svelte/no-navigation-without-resolve'
-description: 'disallow using navigation (links, goto, pushState, replaceState) without a resolve()'
+description: 'disallow internal navigation (links, `goto()`, `pushState()`, `replaceState()`) without a `resolve()`'
 since: 'v3.12.0'
 ---
 
 # svelte/no-navigation-without-resolve
 
-> disallow using navigation (links, goto, pushState, replaceState) without a resolve()
+> disallow internal navigation (links, `goto()`, `pushState()`, `replaceState()`) without a `resolve()`
 
 - :gear: This rule is included in `"plugin:svelte/recommended"`.
 
 ## :book: Rule Details
 
-This rule reports navigation using HTML `<a>` tags, SvelteKit's `goto()`, `pushState()` and `replaceState()` functions without resolving a relative URL. All four of these may be used for navigation, with `goto()`, `pushState()` and `replaceState()` being intended solely for internal navigation (i.e. not leaving the site), while `<a>` tags may be used for both internal and external navigation. When using any way of internal navigation, the URL must be resolved using SvelteKit's `resolve()`, otherwise the site may break. For programmatic navigation to external URLs, using `window.location` is advised.
-
-This rule checks all 4 navigation options for the presence of the `resolve()` function call, with an exception for `<a>` links to absolute URLs (and fragment URLs), which are assumed to be used for external navigation and so do not require the `resolve()` function, and for shallow routing functions with an empty string as the path, which keeps the current URL.
+This rule ensures internal navigation via HTML `<a>` tags, SvelteKit's `goto()`, `pushState()` and `replaceState()` uses `resolve()`. `<a>` tags will skip this check when it has an absolute URL or `rel="external"`. For programmatic external navigation, use `window.location`. Enforcing this rule ensures the base path is prefixed and internal links are type-checked.
 
 <!--eslint-skip-->
 
 ```svelte
+<!-- ✓ GOOD -->
 <script>
   /* eslint svelte/no-navigation-without-resolve: "error" */
 
   import { goto, pushState, replaceState } from '$app/navigation';
   import { resolve } from '$app/paths';
 
-  // ✓ GOOD
   goto(resolve('/foo/'));
-
   pushState(resolve('/foo/'), {});
-  pushState('', {});
-
   replaceState(resolve('/foo/'), {});
+
+  // shallow routing
+  pushState('', {});
   replaceState('', {});
+</script>
+
+<a href={resolve('/foo/')}>Click me!</a>
+<a href="https://svelte.dev">Click me!</a>
+<a href={someURL} rel="external">Click me!</a>
+<a href="#top">Click me!</a>
+```
+
+```svelte
+<!-- ✗ BAD -->
+<script>
+  /* eslint svelte/no-navigation-without-resolve: "error" */
+
+  import { goto, pushState, replaceState } from '$app/navigation';
+  import { resolve } from '$app/paths';
 
-  // ✗ BAD
   goto('/foo');
   goto('/foo' + resolve('/bar'));
   goto(resolve('/foo') + '/bar');
@@ -45,12 +57,6 @@ This rule checks all 4 navigation options for the presence of the `resolve()` fu
   replaceState('/foo', {});
 </script>
 
-<!-- ✓ GOOD -->
-<a href={resolve('/foo/')}>Click me!</a>
-<a href="https://svelte.dev">Click me!</a>
-<a href={someURL} rel="external">Click me!</a>
-
-<!-- ✗ BAD -->
 <a href="/foo">Click me!</a>
 <a href={'/foo'}>Click me!</a>
 ```

packages/eslint-plugin-svelte/src/rule-types.ts

@@ -199,7 +199,7 @@ export interface RuleOptions {
    */
   'svelte/no-navigation-without-base'?: Linter.RuleEntry<SvelteNoNavigationWithoutBase>
   /**
-   * disallow using navigation (links, goto, pushState, replaceState) without a resolve()
+   * disallow internal navigation (links, `goto()`, `pushState()`, `replaceState()`) without a `resolve()`
    * @see https://sveltejs.github.io/eslint-plugin-svelte/rules/no-navigation-without-resolve/
    */
   'svelte/no-navigation-without-resolve'?: Linter.RuleEntry<SvelteNoNavigationWithoutResolve>

packages/eslint-plugin-svelte/src/rules/no-navigation-without-resolve.ts

@@ -10,7 +10,7 @@ export default createRule('no-navigation-without-resolve', {
 	meta: {
 		docs: {
 			description:
-				'disallow using navigation (links, goto, pushState, replaceState) without a resolve()',
+				'disallow internal navigation (links, `goto()`, `pushState()`, `replaceState()`) without a `resolve()`',
 			category: 'SvelteKit',
 			recommended: true
 		},