# @route-weaver/vue

[![npm version](https://badge.fury.io/js/@route-weaver%2Fvue.svg)](https://badge.fury.io/js/@route-weaver%2Fvue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The official Vue integration for `route-weaver`. It offers a plugin and a set of Composables to integrate `route-weaver` into your Vue applications, providing a reactive and intuitive API with full typesafety.

## Why @route-weaver/vue?

Tired of string-based navigation and the runtime errors that come with it? `@route-weaver/vue` brings the power of TypeScript to your Vue routing, ensuring that your routes are always valid at compile-time. This means no more typos in route names, no more missing parameters, and a more robust and maintainable application. By leveraging Vue's reactivity system, it provides a seamless and intuitive developer experience.

## Installation

```bash
npm install @route-weaver/core @route-weaver/vue
```

## Setup

First, create your `routeWeaver` instance and install the Vue plugin in your `main.ts`.

```typescript
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { createRouteWeaver } from '@route-weaver/core';
import { createRouteWeaverVue } from '@route-weaver/vue';

const routeWeaver = createRouteWeaver({
  home: { label: 'Home', path: '/' },
  users: {
    label: 'Users',
    path: 'users',
    children: {
      view: { label: 'View User', path: ':id' },
    },
  },
});

const navInstance = routeWeaver.build({
  main: ['home', 'users'],
});

const app = createApp(App);
app.use(createRouteWeaverVue(navInstance, routeWeaver));
app.mount('#app');
```

## Expanded API Reference

### `useNavigation(groupName)`

*   **Why and When to Use**: Use this composable to get a reactive reference to a specific navigation group. It's ideal for building dynamic navigation menus that automatically update when the underlying data changes.
*   **`groupName`**: The name of the navigation group (e.g., `'main'`).
*   **Returns**: A `Ref<StructuredNavItem[]>` for the specified group.

**Practical Example**:

```vue
<script setup lang="ts">
import { useNavigation } from '@route-weaver/vue';

const mainNav = useNavigation('main');
</script>

<template>
  <nav>
    <router-link v-for="item in mainNav" :key="item.id" :to="item.fullPath">
      {{ item.label }}
    </router-link>
  </nav>
</template>
```

---

### `useActiveRoute()`

*   **Why and When to Use**: Use this composable to get a computed property for the active route. This is useful for displaying details about the current page, highlighting active links, or conditionally rendering components based on the current route.
*   **Returns**: A `ComputedRef<ActiveRoute | undefined>`.

**Practical Example**:

```vue
<script setup lang="ts">
import { useActiveRoute } from '@route-weaver/vue';

const activeRoute = useActiveRoute();
</script>

<template>
  <h1 v-if="activeRoute">{{ activeRoute.route.label }}</h1>
</template>
```

---

### `useBreadcrumbs()`

*   **Why and When to Use**: Use this composable to get a computed property for the breadcrumb trail of the active route. It's the perfect tool for building breadcrumb navigation components that help users orient themselves within your app.
*   **Returns**: A `ComputedRef<StructuredNavItem[]>`.

**Practical Example**:

```vue
<script setup lang="ts">
import { useBreadcrumbs } from '@route-weaver/vue';

const breadcrumbs = useBreadcrumbs();
</script>

<template>
  <nav>
    <span v-for="(crumb, index) in breadcrumbs" :key="crumb.id">
      <router-link :to="crumb.fullPath">{{ crumb.label }}</router-link>
      <span v-if="index < breadcrumbs.length - 1"> > </span>
    </span>
  </nav>
</template>
```

---

### `useBuildPath()`

*   **Why and When to Use**: This is your go-to composable for creating typesafe links. It provides the `buildPath` function, which ensures that you can only build URLs for routes that actually exist and that you provide all the necessary parameters. This eliminates a whole class of common routing errors.
*   **Returns**: The `buildPath(routeId, params)` function.

**Practical Example**:

```vue
<script setup lang="ts">
import { useBuildPath } from '@route-weaver/vue';

const buildPath = useBuildPath();
const userProfilePath = buildPath('users.view', { id: '42' });
</script>

<template>
  <router-link :to="userProfilePath">View User Profile</router-link>
</template>
```

## Before and After: The Typesafety Advantage

### Before: Risky, String-Based Paths

```vue
// This is not typesafe. If the route changes, this link will break silently.
const userProfilePath = `/users/123`;
```

This is brittle. A typo or a change in the route structure leads to runtime errors.

### After: Reactive, Typesafe, and Error-Free

```vue
<script setup lang="ts">
import { useBuildPath } from '@route-weaver/vue';

const buildPath = useBuildPath();

// ✅ Correct: Autocompletion for 'users.view' and 'id'.
const userDetailPath = buildPath('users.view', { id: '123' });

// ❌ Compile-Time Error: 'userId' is not a valid parameter.
// const invalidPath = buildPath('users.view', { userId: '123' });

// ❌ Compile-Time Error: 'posts' is not a valid route name.
// const nonExistentPath = buildPath('posts', { id: '456' });
</script>
```

Refactor with confidence. TypeScript will instantly flag any invalid `buildPath` calls.

## Live Examples

Explore interactive examples on CodeSandbox to see `@route-weaver/vue` in action.

*   **Basic Setup**: [Link to CodeSandbox](https://codesandbox.io/p/sandbox/route-weaver-vue-example-y7qj9m)
*   **Advanced Usage with Pinia**: [Link to CodeSandbox] (coming soon)

## Contributing

Contributions are welcome! Please see the main [CONTRIBUTING.md](../../CONTRIBUTING.md) file for details.

## License

MIT