feat(attachment): rework link action and add link attachment

Author: dvcol

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

@@ -1,9 +1,17 @@
-import type { Action } from 'svelte/action';
+import type { ActionReturn } from 'svelte/action';
 
 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 {
+  activeStyles,
+  doNameMatch,
+  doPathMatch,
+  ensureActionRouter,
+  ensurePathName,
+  getOriginalStyle,
+  restoreStyles,
+} from '~/models/action.model.js';
 import { Matcher } from '~/models/index.js';
 import { getRouter } from '~/router/context.svelte.js';
 
@@ -16,7 +24,7 @@ import { getRouter } from '~/router/context.svelte.js';
  * - Name always takes precedence over path.
  * - When the route un-matches, the original style will be restored.
  *
- * 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.
  *
  * @param node - The element to add the active state to
  * @param options - The options to use for the active state
@@ -27,13 +35,13 @@ import { getRouter } from '~/router/context.svelte.js';
  * ```html
  * <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>
  * ```
  */
-export const active: Action<HTMLElement, ActiveOptions | undefined> = (node: HTMLElement, options: ActiveOptions | undefined = {}) => {
+export function active(node: HTMLElement, options: ActiveOptions | undefined = {}): ActionReturn<ActiveOptions | undefined> {
   const router = options?.router || getRouter();
-  if (!ensureRouter(node, router)) return {};
+  if (!ensureActionRouter(node, router)) return {};
 
   let _options = $state(options);
   let _path: string | null = $state(options?.path || node.getAttribute('data-path') || node.getAttribute('href'));
@@ -67,4 +75,4 @@ export const active: Action<HTMLElement, ActiveOptions | undefined> = (node: HTM
     ensurePathName(node, { path: _path, name: _name });
   });
   return { update };
-};
+}

src/lib/action/link.action.svelte.ts

@@ -1,12 +1,9 @@
-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 { getLinkNavigateFunction, getResolveFunction, normalizeLinkAttributes } from '~/models/link.model.js';
-import { Logger } from '~/utils/logger.utils.js';
-
-export type LinkActionOptions<Name extends RouteName = RouteName, Path extends string = string> = LinkNavigateOptions<Name, Path>;
+import { ensureLinkRouter, getNavigateFunction, getResolveFunction, normalizeLinkAttributes } from '~/models/link.model.js';
+import { getRouter } from '~/router/context.svelte.js';
 
 /**
  * A svelte action to add to an element to navigate to a new location using the router.
@@ -26,7 +23,7 @@ export type LinkActionOptions<Name extends RouteName = RouteName, Path extends s
  * - Name takes precedence over path.
  * - If the host is not an anchor element, the role and tabindex attributes will be set.
  *
- * 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.
  *
  * @param node - The element to add the link action to
  * @param options - The options to use for the navigation
@@ -41,38 +38,26 @@ export type LinkActionOptions<Name extends RouteName = RouteName, Path extends s
  * <button href='/path/:param' use:link="{ params: { param: 'value' } }">button link</button>
  * ```
  */
-export const link: Action<HTMLElement, LinkActionOptions | undefined> = (node: HTMLElement, options: LinkActionOptions | undefined = {}) => {
-  normalizeLinkAttributes(node, options);
-
-  let _options = $state(options);
-  const update = (newOptions: LinkNavigateOptions | undefined = {}) => {
-    _options = newOptions;
-  };
+export function link(node: HTMLElement, options: LinkNavigateOptions | undefined = {}): ActionReturn<LinkNavigateOptions | undefined> {
+  const router = options?.router || getRouter();
+  if (!ensureLinkRouter(node, router)) return {};
 
-  const navigate = $derived.by<LinkNavigateFunction | undefined>(() => {
-    try {
-      const fn = getLinkNavigateFunction(_options);
-      node.removeAttribute('data-error');
-      return fn;
-    } catch (error) {
-      Logger.warn('Router not found. Make sure you are using the link(s) action within a Router context.', { node, options, error });
-      node.setAttribute('data-error', 'Router not found.');
-    }
-  });
+  let _options = $state(normalizeLinkAttributes(node, options));
 
+  const navigate = $derived<LinkNavigateFunction | undefined>(getNavigateFunction(router, options));
   const navigateHandler = async (event: MouseEvent | KeyboardEvent) => navigate?.(event, node);
 
-  // Add resolve on hover option && view params
   const resolve = $derived(getResolveFunction(navigate, _options));
-
   const resolveHandler = async (event: FocusEvent | PointerEvent) => resolve(event, node);
 
   node.addEventListener('click', navigateHandler);
   node.addEventListener('keydown', navigateHandler);
   node.addEventListener('pointerenter', resolveHandler);
   node.addEventListener('focus', resolveHandler);
   return {
-    update,
+    update(newOptions: LinkNavigateOptions | undefined = {}) {
+      _options = newOptions;
+    },
     destroy() {
       node.removeEventListener('click', navigateHandler);
       node.removeEventListener('keydown', navigateHandler);

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

@@ -3,8 +3,8 @@ import type { Action } from 'svelte/action';
 import type { RouteName } from '~/models/index.js';
 import type { LinkNavigateFunction, LinkNavigateOptions } from '~/models/link.model.js';
 
-import { getLinkNavigateFunction, getResolveFunction, parseBooleanAttribute } from '~/models/link.model.js';
-import { Logger } from '~/utils/logger.utils.js';
+import { ensureLinkRouter, getNavigateFunction, getResolveFunction, parseBooleanAttribute } from '~/models/link.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> {
@@ -89,21 +89,12 @@ function findLinkNode(node: HTMLElement, { apply, boundary, host }: InternalLink
  * ```
  */
 export const links: Action<HTMLElement, LinksActionOptions | undefined> = (node: HTMLElement, options: LinksActionOptions | undefined = {}) => {
+  const router = options?.navigate?.router || getRouter();
+  if (!ensureLinkRouter(node, router)) return {};
+
   let _options: InternalLinksActionOptions = $state({ ...options, host: node });
-  const update = (newOptions: LinksActionOptions | undefined = {}) => {
-    _options = { ...newOptions, host: node };
-  };
 
-  const navigate = $derived.by<LinkNavigateFunction | undefined>(() => {
-    try {
-      const fn = getLinkNavigateFunction(_options.navigate);
-      node.removeAttribute('data-error');
-      return fn;
-    } catch (error) {
-      Logger.warn('Router not found. Make sure you are using the link(s) action within a Router context.', { node, options, error });
-      node.setAttribute('data-error', 'Router not found.');
-    }
-  });
+  const navigate = $derived<LinkNavigateFunction | undefined>(getNavigateFunction(router, _options.navigate));
 
   const navigateHandler = async (event: MouseEvent | KeyboardEvent) => {
     const { target } = event;
@@ -133,7 +124,9 @@ export const links: Action<HTMLElement, LinksActionOptions | undefined> = (node:
   node.addEventListener('pointerover', resolveHandler);
   node.addEventListener('focusin', resolveHandler);
   return {
-    update,
+    update(newOptions: LinksActionOptions | undefined = {}) {
+      _options = { ...newOptions, host: node };
+    },
     destroy() {
       node.removeEventListener('click', navigateHandler);
       node.removeEventListener('keydown', navigateHandler);

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

@@ -3,15 +3,46 @@ 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 {
+  activeStyles,
+  doNameMatch,
+  doPathMatch,
+  ensureActionRouter,
+  ensurePathName,
+  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 {
+/**
+ * A svelte attachment to add an active state (class, style or attribute) to an element when the route matches.
+ *
+ * Additionally:
+ * - If attached to an anchor element, it will attempt to match the href attribute.
+ * - If path or name options are provided, they will take precedence over the element attributes.
+ * - Name always takes precedence over path.
+ * - When the route un-matches, the original style will be restored.
+ *
+ * Note: The attachment requires a router instance or the router context to be present in the component tree.
+ *
+ * @param options - The options to use for the active state
+ *
+ * @see {@link RouterView}
+ *
+ * @example
+ * ```html
+ * <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>
+ * ```
+ */
+export function useActive(options: ActiveOptions = {}): Attachment<HTMLElement> {
   const router = options?.router || getRouter();
 
   return (element) => {
-    if (!ensureRouter(element, router)) return;
+    if (!ensureActionRouter(element, router)) return;
 
     const _options = $derived(options);
     const _path: string | null = $derived(options?.path || element.getAttribute('data-path') || element.getAttribute('href'));

src/lib/attachment/index.ts

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

src/lib/attachment/link.attachment.svelte.ts

@@ -0,0 +1,64 @@
+import type { Attachment } from 'svelte/attachments';
+
+import type { LinkNavigateFunction, LinkNavigateOptions } from '~/models/link.model.js';
+
+import { ensureLinkRouter, getNavigateFunction, getResolveFunction, normalizeLinkAttributes } from '~/models/link.model.js';
+import { getRouter } from '~/router/context.svelte.js';
+
+/**
+ * A svelte attachment to add to an element to navigate to a new location using the router.
+ *
+ * The link attachment will prevent the default behavior and use the router only if the following conditions are met:
+ * - The element is within a router context
+ * - The event is a left click or enter key
+ * - The event does not have a modifier key
+ * - The target is not an external link (for anchor elements)
+ * - The target is not a new tab or window (for anchor elements)
+ *
+ * Additionally:
+ * - The attachment merge data-attributes with the options passed as argument.
+ * - Passed options have precedence over data-attributes.
+ * - If attribute expects a JSON object, it will be parsed.
+ * - If a name or path parameter are provided, they will be used to navigate and href will be ignored.
+ * - Name takes precedence over path.
+ * - If the host is not an anchor element, the role and tabindex attributes will be set.
+ *
+ * Note: The attachment requires a router instance or the router context to be present in the component tree.
+ *
+ * @param options - The options to use for the navigation
+ *
+ * @Example
+ * ```html
+ * <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>
+ * ```
+ */
+export function useLink(options: LinkNavigateOptions = {}): Attachment<HTMLElement> {
+  return (element) => {
+    const _options = $state(normalizeLinkAttributes(element, options));
+
+    const router = _options?.router || getRouter();
+    if (!ensureLinkRouter(element, router)) return;
+
+    const navigate = $derived<LinkNavigateFunction | undefined>(getNavigateFunction(router, options));
+    const navigateHandler = async (event: MouseEvent | KeyboardEvent) => navigate?.(event, element);
+
+    const resolve = $derived(getResolveFunction(navigate, _options));
+    const resolveHandler = async (event: FocusEvent | PointerEvent) => resolve(event, element);
+
+    element.addEventListener('click', navigateHandler);
+    element.addEventListener('keydown', navigateHandler);
+    element.addEventListener('pointerenter', resolveHandler);
+    element.addEventListener('focus', resolveHandler);
+    return () => {
+      element.removeEventListener('click', navigateHandler);
+      element.removeEventListener('keydown', navigateHandler);
+      element.removeEventListener('pointerenter', resolveHandler);
+      element.removeEventListener('focus', resolveHandler);
+    };
+  };
+}

src/lib/models/action.model.ts

@@ -45,7 +45,7 @@ export interface ActiveOptions<Name extends RouteName = RouteName> {
   caseSensitive?: boolean;
 }
 
-export function ensureRouter(element: Element, router?: IRouter): router is IRouter {
+export function ensureActionRouter(element: Element, router?: IRouter): router is IRouter {
   if (router) return true;
   Logger.warn('Router not found. Make sure you are using the active action within a Router context.', { element });
   element.setAttribute('data-error', 'Router not found.');
@@ -87,21 +87,18 @@ export function doPathMatch(matcher?: Matcher, name?: RouteName | null, location
 
 type Styles = CSSStyleDeclaration[keyof CSSStyleDeclaration];
 
-export function getOriginalStyle(element: Element, style: Partial<CSSStyleDeclaration> = {}): Record<string, Styles> | undefined {
-  if (!(element instanceof HTMLElement)) return;
+export function getOriginalStyle(element: HTMLElement, style: Partial<CSSStyleDeclaration> = {}): Record<string, Styles> | undefined {
   return Object.fromEntries(Object.keys(style).map(key => [key, element.style[key as keyof CSSStyleDeclaration]]));
 }
 
-export function activeStyles(element: Element, options?: ActiveOptions) {
-  if (!(element instanceof HTMLElement)) return;
+export function activeStyles(element: HTMLElement, options?: ActiveOptions) {
   element.setAttribute('data-active', 'true');
   if (options?.class) element.classList.add(options.class);
   if (!options?.style) return;
   Object.assign(element.style, options.style);
 }
 
-export function restoreStyles(element: Element, original?: Record<string, Styles>, options?: ActiveOptions) {
-  if (!(element instanceof HTMLElement)) return;
+export function restoreStyles(element: HTMLElement, original?: Record<string, Styles>, options?: ActiveOptions) {
   element.removeAttribute('data-active');
   if (options?.class) element.classList.remove(options.class);
   if (!options?.style) return;

src/lib/models/link.model.ts

@@ -3,8 +3,7 @@ import type { IRouter, ResolvedRouterLocationSnapshot, RouterNavigationOptions }
 
 import { resolveComponent } from '@dvcol/svelte-utils/component';
 
-import { MissingRouterContextError, NavigationCancelledError } from '~/models/index.js';
-import { getRouter } from '~/router/context.svelte.js';
+import { NavigationCancelledError } from '~/models/index.js';
 import { Logger, LoggerKey } from '~/utils/logger.utils.js';
 
 function isAnchorTarget(target: EventTarget | null): target is HTMLAnchorElement {
@@ -74,14 +73,12 @@ export type LinkNavigateFunction = <Action extends 'replace' | 'push' | 'resolve
 
 /**
  * Get the router link navigation function for the given options.
- * @param options
+ * @param router - The router instance to use for matching.
+ * @param options - The options to use for the navigation.
  *
  * @throws {MissingRouterContextError} - If the router context is not found
  */
-export function getLinkNavigateFunction(options: LinkNavigateOptions = {}): LinkNavigateFunction {
-  const router = options?.router || getRouter();
-  if (!router) throw new MissingRouterContextError();
-
+export function getNavigateFunction(router: IRouter, options: LinkNavigateOptions = {}): LinkNavigateFunction {
   return async (event, node, action) => {
     // if the element is disabled, we return
     if (options?.disabled) return;
@@ -137,6 +134,16 @@ export function getLinkNavigateFunction(options: LinkNavigateOptions = {}): Link
   };
 }
 
+export function ensureLinkRouter(element: Element, router?: IRouter): router is IRouter {
+  if (router) {
+    element.removeAttribute('data-error');
+    return true;
+  }
+  Logger.warn('Router not found. Make sure you are using the link(s) action within a Router context.', { element });
+  element.setAttribute('data-error', 'Router not found.');
+  return false;
+}
+
 /**
  * Normalize the link attributes and options.
  * If the host is not an anchor element, the role and tabindex attributes will be set.
@@ -145,14 +152,14 @@ export function getLinkNavigateFunction(options: LinkNavigateOptions = {}): Link
  * @param node
  * @param options
  */
-export function normalizeLinkAttributes(node: HTMLElement, options: LinkNavigateOptions) {
+export function normalizeLinkAttributes(node: Element, options: LinkNavigateOptions) {
   if (!isAnchorTarget(node)) {
     if (!node.hasAttribute('role')) node.setAttribute('role', 'link');
     if (!node.hasAttribute('tabindex')) node.setAttribute('tabindex', '0');
   } else if (!node.hasAttribute('href') && options?.path) {
     node.setAttribute('href', options.path);
   }
-  return { node, options };
+  return options;
 }
 
 export interface LinkNavigateOptions<Name extends RouteName = RouteName, Path extends string = string> extends CommonRouteNavigation<Path>,

test/action/active/active.test.ts

@@ -70,9 +70,9 @@ describe('active', () => {
         spyRouter.mockReturnValueOnce(undefined);
 
         if (title === 'action') {
-          active(mockNode, {});
+          active(mockNode);
         } else {
-          useActive({})(mockNode);
+          useActive()(mockNode);
         }
 
         expect(spyRouter).toHaveBeenCalledWith();