feat(attachment): adds links

Author: dvcol

README.md

@@ -316,6 +316,25 @@ Note: The action requires the router context to be present in the component tree
 <button href='/path/:param' use:link="{ params: { param: 'value' } }">button link</button>
 ```
 
+#### Link attachment
+
+The `link attachment` intercepts click events on dom elements and triggers a router navigation instead.
+
+Similar to the `link action`, see the [link action](#link-action) for more information.
+
+```svelte
+<script lang="ts">
+  import { useLink } from '@dvcol/svelte-simple-router/attachment';
+</script>
+
+<a href="/path/:param?query=value" {@attach useLink()}>simple link</a>
+<a href='goodbye' name {@attach useLink()}>named link</a>
+<a href='/path/:param' data-query='{"query":"value"}' {@attach useLink()}>link with query</a>
+<a href='/path/:param' {@attach useLink({ params: { param: 'value' } })}>link with params</a>
+<div href='/path/:param' {@attach useLink({ params: { param: 'value' } })}>div link</div>
+<button href='/path/:param' {@attach useLink({ params: { param: 'value' } })}>button link</button>
+```
+
 #### Links action
 
 The `links action` intercepts click events on dom elements and upwardly navigate the dom tree until it reaches a link element and triggers a router navigation instead.
@@ -351,6 +370,27 @@ Note: Unlike use:link, use:links does not normalize link attributes (role, tabin
 </div>
 ```
 
+#### Links attachment
+
+The `links attachment` intercepts click events on dom elements and upwardly navigate the dom tree until it reaches a link element and triggers a router navigation instead.
+
+Similar to the `links action`, see the [links action](#links-action) for more information.
+
+```svelte
+<script lang="ts">
+  import { useLinks } from '@dvcol/svelte-simple-router/attachment';
+</script>
+
+<div {@attach useLinks()}>
+  <div>
+    <a href="/path/:param?query=value">simple link</a>
+  </div>
+  <div data-router-link data-name="Hello">
+    <span>simple span</span>
+  </div>
+</div>
+```
+
 #### Active action
 
 The `active action` adds an active state (class, style or attribute) to an element when the route matches.

demo/routers/PathSelector.svelte

@@ -3,9 +3,9 @@
 
   import { NeoButton, NeoCard, NeoInput } from '@dvcol/neo-svelte';
 
-  import { active } from '~/action/active.action.svelte.js';
-  import { link } from '~/action/link.action.svelte.js';
-  import { links } from '~/action/links.action.svelte.js';
+  import { useActive } from '~/attachment/active.attachment.svelte.js';
+  import { useLink } from '~/attachment/link.attachment.svelte.js';
+  import { useLinks } from '~/attachment/links.attachment.svelte.js';
   import { NavigationCancelledError } from '~/models/error.model.js';
   import { useNavigate, useRouter } from '~/router/hooks.svelte.js';
 
@@ -77,7 +77,7 @@
 <NeoCard rounded>
   <div id="route-selector" class="container">
     <h4>Routes</h4>
-    <table class="routes" use:links>
+    <table class="routes" {@attach useLinks()}>
       <thead>
         <tr>
           <th>Name</th>
@@ -89,7 +89,7 @@
       </thead>
       <tbody>
         {#each routes as { name, path, redirect, meta } (name ?? path)}
-          <tr use:link={{ name, path, ...navOptions }} use:active={{ name, path, class: 'active', exact: true }}>
+          <tr {@attach useLink({ name, path, ...navOptions })} {@attach useActive({ name, path, class: 'active', exact: true })}>
             <td>{name}</td>
             <td>{path}</td>
             <td>{redirect?.name ?? redirect?.path ?? meta?.redirect ?? '-'}</td>

src/lib/action/links.action.svelte.ts

@@ -1,61 +1,12 @@
-import type { Action } from 'svelte/action';
+import type { ActionReturn } from 'svelte/action';
 
-import type { RouteName } from '~/models/index.js';
-import type { LinkNavigateFunction, LinkNavigateOptions } from '~/models/link.model.js';
+import type { LinkNavigateFunction } from '~/models/link.model.js';
+import type { InternalLinksActionOptions, LinksActionOptions } from '~/models/links.model.js';
 
-import { ensureLinkRouter, getNavigateFunction, getResolveFunction, parseBooleanAttribute } from '~/models/link.model.js';
+import { ensureLinkRouter, getNavigateFunction, getResolveFunction } from '~/models/link.model.js';
+import { getNavigateHandler, getResolveHandler } from '~/models/links.model.js';
 import { getRouter } from '~/router/context.svelte.js';
 
-export type NodeConditionFn = (node: HTMLElement) => boolean;
-export interface LinksActionOptions<Name extends RouteName = RouteName, Path extends string = string> {
-  /**
-   * Whether the target node should be considered a link.
-   */
-  apply?: NodeConditionFn;
-  /**
-   * The element to act as a boundary for the upward link search.
-   */
-  boundary?: HTMLElement | NodeConditionFn;
-  /**
-   * The navigate options to use for the navigation.
-   */
-  navigate?: LinkNavigateOptions<Name, Path>;
-}
-
-function isLinkNode(node: HTMLElement, apply?: LinksActionOptions['apply']): boolean {
-  if (node instanceof HTMLAnchorElement) return true;
-  if (parseBooleanAttribute(node, 'router-link')) return true;
-  return apply?.(node) ?? false;
-}
-
-function isBoundaryNode(node: HTMLElement, boundary: HTMLElement | NodeConditionFn): boolean {
-  if (typeof boundary === 'function') return boundary(node);
-  return node === boundary;
-}
-
-function isWithinBoundary(node: HTMLElement, boundary: HTMLElement | NodeConditionFn): boolean {
-  if (isBoundaryNode(node, boundary)) return true;
-  let _node: HTMLElement = node;
-  while (_node?.parentElement) {
-    _node = _node.parentElement;
-    if (isBoundaryNode(_node, boundary)) return true;
-  }
-  return false;
-}
-
-type InternalLinksActionOptions = LinksActionOptions & { host: HTMLElement };
-function findLinkNode(node: HTMLElement, { apply, boundary, host }: InternalLinksActionOptions): HTMLElement | undefined {
-  if (boundary && !isWithinBoundary(node, boundary ?? host)) return;
-  if (isLinkNode(node, apply)) return node;
-  let link: HTMLElement = node;
-  while (link?.parentElement) {
-    link = link.parentElement;
-
-    if (isBoundaryNode(link, boundary ?? host)) return;
-    if (isLinkNode(link, apply)) return link;
-  }
-}
-
 /**
  * The `links action` intercepts click events on dom elements and upwardly navigate the dom tree until it reaches a link element and triggers a router navigation instead.
  *
@@ -70,7 +21,7 @@ function findLinkNode(node: HTMLElement, { apply, boundary, host }: InternalLink
  * - The action requires either valid href or data-attributes to navigate.
  * - Once the action reaches the host element or the `boundary` element (or selector function), it will stop evaluating the dom tree.
  *
- * Note: The action requires the router context to be present in the component tree.
+ * Note: The action requires a router instance or the router context to be present in the component tree.
  * Note: Unlike use:link, use:links does not normalize link attributes (role, tabindex, href).
  *
  * @param node
@@ -88,36 +39,17 @@ function findLinkNode(node: HTMLElement, { apply, boundary, host }: InternalLink
  * </div>
  * ```
  */
-export const links: Action<HTMLElement, LinksActionOptions | undefined> = (node: HTMLElement, options: LinksActionOptions | undefined = {}) => {
+export function links(node: HTMLElement, options: LinksActionOptions | undefined = {}): ActionReturn<LinksActionOptions | undefined> {
   const router = options?.navigate?.router || getRouter();
   if (!ensureLinkRouter(node, router)) return {};
 
-  let _options: InternalLinksActionOptions = $state({ ...options, host: node });
+  let _options: InternalLinksActionOptions = $derived({ ...options, host: node });
 
   const navigate = $derived<LinkNavigateFunction | undefined>(getNavigateFunction(router, _options.navigate));
+  const navigateHandler = getNavigateHandler(_options, navigate);
 
-  const navigateHandler = async (event: MouseEvent | KeyboardEvent) => {
-    const { target } = event;
-    if (!(target instanceof HTMLElement)) return;
-    if (!navigate) return;
-
-    const nodeLink = findLinkNode(target, _options);
-    if (!nodeLink) return;
-    return navigate(event, nodeLink);
-  };
-
-  // Add resolve on hover option && view params
   const resolve = $derived(getResolveFunction(navigate, _options.navigate));
-
-  const resolveHandler = async (event: FocusEvent | PointerEvent) => {
-    const { target } = event;
-    if (!(target instanceof HTMLElement)) return;
-    if (!resolve) return;
-
-    const nodeLink = findLinkNode(target, _options);
-    if (!nodeLink) return;
-    return resolve(event, nodeLink);
-  };
+  const resolveHandler = getResolveHandler(_options, resolve);
 
   node.addEventListener('click', navigateHandler);
   node.addEventListener('keydown', navigateHandler);

src/lib/attachment/links.attachment.svelte.ts

@@ -0,0 +1,40 @@
+import type { Attachment } from 'svelte/attachments';
+
+import type { LinksActionOptions } from '~/models/links.model.js';
+
+import { links } from '~/action/links.action.svelte.js';
+
+/**
+ * The `links attachment` intercepts click events on dom elements and upwardly navigate the dom tree until it reaches a link element and triggers a router navigation instead.
+ *
+ * The links attachment will recognize a parent node as a router link if it satisfies any of the following conditions:
+ * - The element is an anchor element
+ * - The element has a `data-router-link` attribute
+ * - The element satisfies the `apply` selector function passed as argument
+ *
+ * When a node is recognized as a router link, the attachment will behave as the `link` attachment (all restrictions apply).
+ *
+ * Additionally:
+ * - The attachment requires either valid href or data-attributes to navigate.
+ * - Once the attachment reaches the host element or the `boundary` element (or selector function), it will stop evaluating the dom tree.
+ *
+ * Note: The attachment requires a router instance or the router context to be present in the component tree.
+ * Note: Unlike use:link, use:links does not normalize link attributes (role, tabindex, href).
+ *
+ * @param options
+ *
+ * @Example
+ * ```html
+ * <div {@attach useLinks()}>
+ *   <div>
+ *       <a href="/path/:param?query=value">simple link</a>
+ *   </div>
+ *   <div data-router-link data-name="Hello">
+ *     <span>simple span</span>
+ *   </div>
+ * </div>
+ * ```
+ */
+export function useLinks(options: LinksActionOptions = {}): Attachment<HTMLElement> {
+  return element => links(element, options).destroy;
+}

src/lib/models/index.ts

@@ -1,4 +1,6 @@
-export type * from './action.model.js';
+export type { ActiveOptions } from './action.model.js';
+export type { LinkNavigateOptions } from './link.model.js';
+
 export * from './component.model.js';
 export * from './error.model.js';
 export * from './matcher.model.js';

src/lib/models/links.model.ts

@@ -0,0 +1,78 @@
+import type { LinkNavigateFunction, LinkNavigateOptions, LinkResolveFunction } from '~/models/link.model.js';
+import type { RouteName } from '~/models/route.model.js';
+
+import { parseBooleanAttribute } from '~/models/link.model.js';
+
+export type NodeConditionFn = (node: HTMLElement) => boolean;
+export interface LinksActionOptions<Name extends RouteName = RouteName, Path extends string = string> {
+  /**
+   * Whether the target node should be considered a link.
+   */
+  apply?: NodeConditionFn;
+  /**
+   * The element to act as a boundary for the upward link search.
+   */
+  boundary?: HTMLElement | NodeConditionFn;
+  /**
+   * The navigate options to use for the navigation.
+   */
+  navigate?: LinkNavigateOptions<Name, Path>;
+}
+
+function isLinkNode(node: HTMLElement, apply?: LinksActionOptions['apply']): boolean {
+  if (node instanceof HTMLAnchorElement) return true;
+  if (parseBooleanAttribute(node, 'router-link')) return true;
+  return apply?.(node) ?? false;
+}
+
+function isBoundaryNode(node: HTMLElement, boundary: HTMLElement | NodeConditionFn): boolean {
+  if (typeof boundary === 'function') return boundary(node);
+  return node === boundary;
+}
+
+function isWithinBoundary(node: HTMLElement, boundary: HTMLElement | NodeConditionFn): boolean {
+  if (isBoundaryNode(node, boundary)) return true;
+  let _node: HTMLElement = node;
+  while (_node?.parentElement) {
+    _node = _node.parentElement;
+    if (isBoundaryNode(_node, boundary)) return true;
+  }
+  return false;
+}
+
+export type InternalLinksActionOptions = LinksActionOptions & { host: HTMLElement };
+function findLinkNode(node: HTMLElement, { apply, boundary, host }: InternalLinksActionOptions): HTMLElement | undefined {
+  if (boundary && !isWithinBoundary(node, boundary ?? host)) return;
+  if (isLinkNode(node, apply)) return node;
+  let link: HTMLElement = node;
+  while (link?.parentElement) {
+    link = link.parentElement;
+
+    if (isBoundaryNode(link, boundary ?? host)) return;
+    if (isLinkNode(link, apply)) return link;
+  }
+}
+
+export function getNavigateHandler(options: InternalLinksActionOptions, navigate?: LinkNavigateFunction) {
+  return async (event: MouseEvent | KeyboardEvent) => {
+    const { target } = event;
+    if (!(target instanceof HTMLElement)) return;
+    if (!navigate) return;
+
+    const nodeLink = findLinkNode(target, options);
+    if (!nodeLink) return;
+    return navigate(event, nodeLink);
+  };
+}
+
+export function getResolveHandler(options: InternalLinksActionOptions, resolve?: LinkResolveFunction) {
+  return async (event: FocusEvent | PointerEvent) => {
+    const { target } = event;
+    if (!(target instanceof HTMLElement)) return;
+    if (!resolve) return;
+
+    const nodeLink = findLinkNode(target, options);
+    if (!nodeLink) return;
+    return resolve(event, nodeLink);
+  };
+}