fix(experimental): align hash parameter parsing with queries

Author: posva

packages/docs/experimental/param-parsers.md

@@ -65,7 +65,7 @@ route.params.id // number
 
 You define param parsers as modules exporting a `parser` in the configured param parser directory. The file name is the parser name you use in routes. For example, `src/params/uuid.ts` exports a `parser` that validates UUIDs and can be used as `[id=uuid]` in route files.
 
-A parser is just an object with a _getter_ and a _setter_ but to make things simpler to use, Vue Router provides two helpers: [`defineParamParser()`](#defineParamParser) and [`defineParamParserRaw()`](#defineParamParserRaw).
+A parser is just an object with a _getter_ and a _setter_. Vue Router provides three helpers: [`defineParamParser()`](#defineParamParser), [`defineParamParserRaw()`](#defineParamParserRaw), and [`defineHashParamParser()`](#defineHashParamParser).
 
 Reach for `defineParamParser` first, it's the most common use case for simple one-to-one transforms. Use `defineParamParserRaw` when you need to collapse multiple input shapes into one output type or you want to reject _nullish_ or array values outright.
 
@@ -155,6 +155,26 @@ Here is a table of the different meaningful combinations of return values from `
 
 :::
 
+### `defineHashParamParser`
+
+`defineHashParamParser` defines a transform for the hash. Both `get` and `set` are required: `get` receives a `string`, and `set` returns a `string`. The helper returns your parser unchanged, without array or nullish wrapping. You can specify the parsed type with `defineHashParamParser<TParam>` and a wider setter input with `defineHashParamParser<TParam, TParamRaw>`.
+
+The getter receives the hash contents without the leading `#`: `#setup` calls `get('setup')`, and a bare `#` calls `get('')`. An absent hash (`''`) skips the getter and produces `undefined`, or the configured default.
+
+For example, use the hash contents as a heading name:
+
+```ts
+// src/params/heading.ts
+import { defineHashParamParser } from 'vue-router/experimental'
+
+export const parser = defineHashParamParser<string>({
+  get: hash => hash,
+  set: heading => heading,
+})
+```
+
+Use `params: { hash: { heading: 'heading' } }` in `definePage()`. A hash of `#setup` gives `route.params.heading === 'setup'`. The setter returns contents without `#`. The matcher adds `#` to a present result, including `''`, which produces a bare `#`. Pass `undefined` to clear an optional hash param. You can also pass `null` when the parser or default type includes it.
+
 ## Errors
 
 Throw any error from `get` to mark the value as not matching. The router skips the route (treat it like a 404 candidate). `miss(reason?)` is just sugar for throwing a typed error.
@@ -232,7 +252,7 @@ definePage({
 </script>
 ```
 
-Hash params are optional by default. A parser error or a nullish result becomes `null`. Set `required: true` to reject the match instead, or provide a default:
+Hash params are optional by default. An absent hash skips the getter and produces `undefined`. Parsed values such as `null`, `false`, `0`, and `''` are preserved. For optional hash params, parser errors produce `undefined` or the configured default. Set `required: true` to reject missing hashes, parser errors, or `undefined` results. A default replaces only `undefined` results and parser errors:
 
 ```vue
 <script setup lang="ts">
@@ -249,30 +269,33 @@ definePage({
 </script>
 ```
 
-- `parser`: parser name. Omit to keep the hash string.
-- `required`: reject the match when parsing fails or returns a nullish result. Defaults to `false`.
-- `default`: a parsed value or factory used when the hash is absent or parsing fails. A declared default takes precedence over the getter for an absent hash.
+- `parser`: parser name. Omit to use `string`, which returns the hash contents without `#`. An absent hash produces `undefined` unless you provide a default.
+- `required`: reject the match when the hash is absent, parsing fails, or the parsed value is `undefined`. Defaults to `false`.
+- `default`: a parsed value or factory used when the hash is absent, parsing fails, or the parsed value is `undefined`. An absent hash skips the getter.
 
 `required: true` and `default` cannot be used together.
 
-Without a custom getter or a default, an absent hash becomes `null`.
+Without a parser, a default must be a `string`, `null`, or a factory that returns `string | null`. Other default types require an explicit parser: `{ default: 0 }` is invalid; `{ parser: 'int', default: 0 }` is valid.
+
+With `hash: { section: {} }`, an absent hash becomes `undefined`, `#` becomes `''`, and `#setup` becomes `'setup'`. The parsed type is `string | undefined`.
 
-The parser receives the entire hash string: an empty string when absent, or a string that starts with `#`. To extract several values, return an object from this one parser. Only the deepest matched route's hash parser runs.
+A default can itself be `null`, including when the parser is omitted. For example, `{ default: null }` and `{ parser: 'heading', default: null }` have the parsed type `string | null`, using the `heading` parser above. An absent hash uses the `null` default, while a bare `#` preserves `''`. The parsed type includes the default type, including `null` for `default: null`. Without a default, an optional hash param also includes `undefined` for an absent hash.
+
+The API limits defaults without an explicit parser to `string | null`. However, code generation currently uses `unknown` if it cannot infer the type of such a default expression. Use an explicit parser to keep the generated type bounded by the parser's declared type.
+
+The parser receives the hash contents without `#`. An absent hash skips the getter. To extract several values, return an object from this one parser. Only the deepest matched route's hash parser runs.
 
 ```ts
 // src/params/section.ts
-import { defineParamParserRaw } from 'vue-router/experimental'
+import { defineHashParamParser } from 'vue-router/experimental'
 
-export const parser = defineParamParserRaw<
-  { heading: string; tab: string },
-  { heading: string; tab: string },
-  string
->({
+export const parser = defineHashParamParser<{ heading: string; tab: string }>({
   get: hash => {
-    const [heading = '', tab = ''] = hash.slice(1).split('/')
+    if (!hash) throw new Error('Missing section')
+    const [heading = '', tab = ''] = hash.split('/')
     return { heading, tab }
   },
-  set: ({ heading, tab }) => (heading ? `#${heading}/${tab}` : ''),
+  set: ({ heading, tab }) => `${heading}/${tab}`,
 })
 ```
 
@@ -285,4 +308,4 @@ router.push({
 })
 ```
 
-You can omit an optional hash param or one with a default during navigation. Pass `null` to clear an optional hash param. Required params without a default must be provided. Nullish values produce an empty hash without calling the setter. The setter returns the entire hash, including `#`, or an empty string. The router then runs the getter to validate and normalize the result.
+You can omit an optional hash param or one with a default during navigation. Pass `undefined` to clear an optional hash param. You can also pass `null` when the parser or default type includes it. Required params without a default must be provided. Nullish values produce an empty hash without calling the setter. The setter returns contents without `#`. The matcher adds `#` to each present result, including `''`, which produces a bare `#`. The router then runs the getter on these contents to validate and normalize the result. Clearing the URL hash skips the getter and produces `undefined` or the configured default in `route.params`.

packages/playground-file-based/src/pages/(home).vue

@@ -1,7 +1,37 @@
-<script lang="ts" setup></script>
+<script lang="ts" setup>
+import { useRoute } from 'vue-router'
+
+definePage({
+  params: {
+    hash: {
+      myHash: {
+        parser: 'int',
+        default: 46,
+      },
+    },
+  },
+})
+
+const route = useRoute()
+console.log('Route params:', route.params)
+route.params.myHash
+</script>
 
 <template>
   <h1>Home</h1>
 
   <p>This is the homepage.</p>
+
+  <h2>Hash with the integer parser</h2>
+  <p>An absent or invalid hash uses the default: 46.</p>
+  <ul>
+    <li><RouterLink to="/">No hash → 46</RouterLink></li>
+    <li><RouterLink to="/#">Bare # → 46</RouterLink></li>
+    <li><RouterLink to="/#0">#0 → 0</RouterLink></li>
+    <li>
+      <RouterLink to="/test-params/hash">Custom hash parser</RouterLink>
+    </li>
+  </ul>
+
+  <pre>{{ $route.params }}</pre>
 </template>

packages/playground-file-based/src/pages/test-params/hash.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+definePage({
+  params: {
+    hash: {
+      section: { parser: 'test-hash-split', default: () => [] },
+    },
+  },
+})
+</script>
+
+<template>
+  <h1>Custom hash parser</h1>
+  <p>
+    The parser receives the hash contents without #. An absent hash skips the
+    getter and uses the empty array default. A bare # calls the getter with an
+    empty string and produces [""]. Other contents split into an array at each
+    /.
+  </p>
+  <ul>
+    <li>
+      <RouterLink to="/test-params/hash">No hash → []</RouterLink>
+    </li>
+    <li><RouterLink to="/test-params/hash#">Bare # → [""]</RouterLink></li>
+    <li>
+      <RouterLink to="/test-params/hash#setup">#setup → ["setup"]</RouterLink>
+    </li>
+    <li>
+      <RouterLink to="/test-params/hash#setup/vue">
+        #setup/vue → ["setup", "vue"]
+      </RouterLink>
+    </li>
+  </ul>
+  <pre>{{ $route.params }}</pre>
+  <RouterLink to="/">Hash without a custom parser</RouterLink>
+</template>

packages/playground-file-based/src/params/test-hash-split.ts

@@ -0,0 +1,6 @@
+import { defineHashParamParser } from 'vue-router/experimental'
+
+export const parser = defineHashParamParser<string[]>({
+  get: value => value.split('/'),
+  set: value => value.join('/'),
+})