feat(attachment): adds active attachment

Author: dvcol

README.md

@@ -366,13 +366,29 @@ Note: The action requires the router context to be present in the component tree
 
 ```svelte
 <script lang="ts">
-  import { active } from '@dvcol/svelte-simple-router/router';
+  import { active } from '@dvcol/svelte-simple-router/action';
 </script>
 
 <a href="/path" use:active>simple link</a>
 <a href="/path" data-name="route-name" use:active>named link</a>
-<button :use:active="{ path: '/path' }">button link</button>
-<div :use:active="{ name: 'route-name' }">div link</div>
+<button use:active="{ path: '/path' }">button link</button>
+<div use:active="{ name: 'route-name' }">div link</div>
+```
+#### Active attachment
+
+The `active attachment` adds an active state (class, style or attribute) to an element when the route matches.
+
+Similar to the `active` action, see the [active action](#active-action) for more information.
+
+```svelte
+<script lang="ts">
+  import { useActive } from '@dvcol/svelte-simple-router/attachment';
+</script>
+
+<a href="/path" {@attach useActive()}>simple link</a>
+<a href="/path" data-name="route-name" {@attach useActive()}>named link</a>
+<button {@attach useActive({ path: '/path' })}>button link</button>
+<div {@attach useActive({ name: 'route-name' })}>div link</div>
 ```
 
 ### Programmatic navigation

package.json

@@ -50,6 +50,10 @@
       "types": "./dist/action/index.d.ts",
       "import": "./dist/action/index.js"
     },
+    "./attachment": {
+      "types": "./dist/attachment/index.d.ts",
+      "import": "./dist/attachment/index.js"
+    },
     "./components": {
       "types": "./dist/components/index.d.ts",
       "import": "./dist/components/index.js"

src/lib/action/active.action.svelte.ts

@@ -1,9 +1,9 @@
 import type { Action } from 'svelte/action';
 
-import type { ActiveOptions } from '~/action/action.model.js';
+import type { ActiveOptions } from '~/models/action.model.js';
 import type { RouteName } from '~/models/route.model.js';
 
-import { activeStyles, doNameMatch, doPathMatch, ensurePathName, ensureRouter, getOriginalStyle, restoreStyles } from '~/action/action.model.js';
+import { activeStyles, doNameMatch, doPathMatch, ensurePathName, ensureRouter, getOriginalStyle, restoreStyles } from '~/models/action.model.js';
 import { Matcher } from '~/models/index.js';
 import { getRouter } from '~/router/context.svelte.js';
 

src/lib/attachment/active.attachment.svelte.ts

@@ -0,0 +1,40 @@
+import type { Attachment } from 'svelte/attachments';
+
+import type { ActiveOptions } from '~/models/action.model.js';
+import type { RouteName } from '~/models/route.model.js';
+
+import { activeStyles, doNameMatch, doPathMatch, ensurePathName, ensureRouter, getOriginalStyle, restoreStyles } from '~/models/action.model.js';
+import { Matcher } from '~/models/index.js';
+import { getRouter } from '~/router/context.svelte.js';
+
+export function useActive(options: ActiveOptions): Attachment {
+  const router = getRouter();
+
+  return (element) => {
+    if (!ensureRouter(element, router)) return;
+
+    const _options = $derived(options);
+    const _path: string | null = $derived(options?.path || element.getAttribute('data-path') || element.getAttribute('href'));
+    const _name: RouteName | null = $derived(options?.name || element.getAttribute('data-name'));
+
+    const caseSensitive = $derived(_options?.caseSensitive ?? router.options?.caseSensitive);
+    const matchName = $derived(doNameMatch(router.route, _name, { caseSensitive, exact: _options?.exact }));
+
+    const location = $derived(router.location?.path);
+    const matcher = $derived(_path ? new Matcher(_path) : undefined);
+    const matchPath = $derived(doPathMatch(matcher, _name, location, _options?.exact));
+
+    const match = $derived(matchName || matchPath);
+
+    const originalStyle = $derived(getOriginalStyle(element, _options?.style));
+
+    $effect(() => {
+      if (match) activeStyles(element, _options);
+      else restoreStyles(element, originalStyle, _options);
+    });
+
+    $effect(() => {
+      ensurePathName(element, { path: _path, name: _name });
+    });
+  };
+}

src/lib/attachment/index.ts

@@ -0,0 +1 @@
+export * from './active.attachment.svelte.js';

src/lib/index.ts

@@ -1,3 +1,5 @@
+export * from './action/index.js';
+export * from './attachment/index.js';
 export * from './components/index.js';
 export * from './models/index.js';
 export * from './router/index.js';

src/lib/action/action.model.ts src/lib/models/action.model.tssrc/lib/action/action.model.ts renamed to src/lib/models/action.model.ts

@@ -1,3 +1,4 @@
+export type * from './action.model.js';
 export * from './component.model.js';
 export * from './error.model.js';
 export * from './matcher.model.js';

src/lib/models/index.ts

@@ -0,0 +1,34 @@
+<script lang="ts">
+  import type { IRouter } from '~/models/router.model.js';
+
+  import { useActive } from '~/attachment/active.attachment.svelte.js';
+  import RouterView from '~/components/RouterView.svelte';
+
+  const { router }: { router: IRouter } = $props();
+</script>
+
+<RouterView {router}>
+  <span data-testid="span-error" {@attach useActive()}>error</span>
+
+  <a data-testid="anchor-path" href="/home" {@attach useActive()}>path</a>
+  <a data-testid="anchor-name" href="/other" data-name="home" {@attach useActive()}>name</a>
+
+  <span data-testid="span-path" data-path="/home" {@attach useActive()}>path</span>
+  <span data-testid="span-name" data-name="home" {@attach useActive()}>name</span>
+
+  <div data-testid="param-path" data-path="/other" {@attach useActive({ path: '/home' })}></div>
+  <div data-testid="param-name" data-name="other" {@attach useActive({ name: 'home' })}></div>
+
+  <a data-testid="anchor-parent" href="/other" {@attach useActive()}>path-parent</a>
+  <a data-testid="anchor-child" href="/other/target" {@attach useActive()}>path-child</a>
+  <a data-testid="anchor-exact-parent" href="/other" {@attach useActive({ exact: true })}>path-exact-parent</a>
+
+  <a data-testid="anchor-name-sensitive" href="/home" {@attach useActive({ name: 'Other', caseSensitive: true })}>path</a>
+  <a data-testid="anchor-name-insensitive" href="/home" {@attach useActive({ name: 'Other' })}>path</a>
+
+  <a data-testid="anchor-class-active" href="/home" {@attach useActive({ class: 'active' })}>path</a>
+  <a data-testid="anchor-class-existing" href="/home" class="some-class" {@attach useActive({ class: 'active' })}>path</a>
+
+  <a data-testid="anchor-style-active" href="/home" {@attach useActive({ style: { color: 'red' } })}>path</a>
+  <a data-testid="anchor-style-existing" href="/home" style="color:blue; font-weight: bold;" {@attach useActive({ style: { color: 'red' } })}>path</a>
+</RouterView>