Merge pull request #42 from g4rcez/link-features

Author: OrionFable

docs/pnpm-lock.yaml

@@ -1,7 +1,7 @@
 {
   "name": "brouther",
   "type": "module",
-  "version": "4.4.1",
+  "version": "4.4.2",
   "source": "./src/index.ts",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -48,17 +48,17 @@
     "react": ">=16.8.3"
   },
   "devDependencies": {
-    "@types/node": "18.11.19",
-    "@types/qs": "6.9.7",
-    "@types/react": "18.0.27",
-    "cypress": "12.10.0",
-    "prettier": "2.8.8",
+    "@types/node": "^20.5.9",
+    "@types/qs": "^6.9.8",
+    "@types/react": "^18.2.21",
+    "cypress": "^13.1.0",
+    "prettier": "^3.0.3",
     "start-server-and-test": "2.0.0",
     "ts-node": "10.9.1",
-    "tslib": "2.5.0",
-    "typescript": "5.0.4",
-    "vite": "4.3.9",
-    "vitest": "0.30.1"
+    "tslib": "^2.6.2",
+    "typescript": "^5.2.2",
+    "vite": "^4.4.9",
+    "vitest": "^0.34.3"
   },
   "browserslist": {
     "production": [

package-lock.json

@@ -50,3 +50,4 @@ export { createFormPath } from "./form/form-path";
 export { redirectResponse, jsonResponse, type InferLoader, type CustomResponse } from "./brouther/brouther-response";
 export { waitFor, Scroll, useScroll } from "./brouther/scroll";
 export { Await } from "./brouther/await";
+export { parseTextFragment } from "./utils/text-fragment";

package.json

@@ -1,45 +1,47 @@
 import React, { forwardRef } from "react";
 import { join, mergeUrlEntities } from "../utils/utils";
 import { useBasename, useHref, useNavigation } from "../brouther/brouther";
-import type { Paths } from "../types/paths";
 import type { QueryString } from "../types/query-string";
 import { AnyJson } from "../types";
+import { Paths } from "../types/paths";
+import { TextFragment } from "../utils/text-fragment";
+import { QueryStringMapper } from "../utils/mappers";
 
 const isLeftClick = (e: React.MouseEvent) => e.button === 0;
 
 const isMod = (event: React.MouseEvent): boolean => event.metaKey || event.altKey || event.ctrlKey || event.shiftKey;
 
 type AnchorProps = React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>;
 
-export type LinkProps<Path extends string> = AnchorProps & {
+type QueryAndPaths<Path extends string> = (Paths.Has<Path> extends true ? { paths: Paths.Parse<Path> } : { paths?: never }) &
+    (QueryString.Has<Path> extends true ? { query: NonNullable<QueryString.Parse<Path>> } : { query?: never });
+
+export type LinkProps<Path extends string> = Omit<AnchorProps, "href" | "onClick"> & {
+    fragments?: TextFragment[];
     href: Path;
-    state?: AnyJson;
+    onClick?: (event: Parameters<NonNullable<AnchorProps["onClick"]>>[0], pathAndQuery: QueryAndPaths<Path>) => void;
+    parsers?: Partial<QueryStringMapper<string>>;
     replace?: boolean;
-} & (Paths.Parse<Paths.Pathname<Path>> extends null
-        ? { paths?: undefined }
-        : Omit<Path, string> extends string
-        ? { paths: Paths.Parse<Paths.Pathname<Path>> }
-        : { paths?: Paths.Parse<Paths.Pathname<Path>> }) &
-    (QueryString.Has<Path> extends false
-        ? { query?: undefined }
-        : QueryString.HasRequired<Path> extends true
-        ? { query: QueryString.Parse<Path> }
-        : { query?: QueryString.Parse<Path> });
+    state?: AnyJson;
+} & QueryAndPaths<Path>;
 
 const httpRegex = /^https?:\/\//;
 
-export const Link: <TPath extends string>(props: LinkProps<TPath>, ref: React.MutableRefObject<HTMLAnchorElement>) => JSX.Element = forwardRef(
-    <TPath extends string>({ href, state, replace = false, onClick, query, paths, ...props }: LinkProps<TPath>, ref: any) => {
+export const Link: <TPath extends string>(props: LinkProps<TPath>) => React.ReactElement = forwardRef(
+    <TPath extends string>(
+        { href, state, replace = false, onClick, parsers, query, paths, fragments, ...props }: LinkProps<TPath>,
+        ref: React.Ref<HTMLAnchorElement>
+    ) => {
         const { push, replace: _replace } = useNavigation();
         const contextHref = useHref();
         const basename = useBasename();
-        const _href = httpRegex.test(href) ? href : join(basename, mergeUrlEntities(href, paths, query));
-        const _onClick: NonNullable<typeof onClick> = (event) => {
+        const _href = httpRegex.test(href) ? href : join(basename, mergeUrlEntities(href, paths, query, parsers, fragments));
+        const _onClick: NonNullable<AnchorProps["onClick"]> = (event) => {
             if (props.target === undefined && props.target !== "_self") event.preventDefault();
             if (_href === contextHref) return;
             if (!isLeftClick(event)) return;
             if (isMod(event)) return;
-            onClick?.(event);
+            onClick?.(event, { query, paths } as QueryAndPaths<TPath>);
             return replace ? _replace(_href, state) : push(_href, state);
         };
         return <a {...props} href={_href} onClick={_onClick} ref={ref} />;

src/index.ts

@@ -6,6 +6,7 @@ import type { Paths } from "./paths";
 import { BrowserHistory } from "./history";
 import { X } from "./x";
 import { CustomResponse } from "../brouther/brouther-response";
+import { TextFragment } from "../utils/text-fragment";
 
 export type RouteData = { [k in string]: unknown } | {};
 
@@ -62,18 +63,19 @@ export type CreateHref<T extends readonly Route[]> = <
     const Path extends FetchPaths<T>,
     const Qs extends QueryString.Parse<Path>,
     const Params extends Paths.Parse<Path>,
-    const QueryStringParsers extends QueryString.ParseURL<Path>
+    const QueryStringParsers extends QueryString.ParseURL<Path>,
+    const TextFragments extends TextFragment[],
 >(
     ...args: Paths.Parse<Path> extends null
         ? QueryString.Has<Path> extends true
             ? QueryString.HasRequired<Path> extends true
-                ? readonly [path: Path, qs: Qs, parsers?: QueryStringParsers]
-                : readonly [path: Path, qs?: Qs, parsers?: QueryStringParsers]
+                ? readonly [path: Path, qs: Qs, parsers?: QueryStringParsers, textFragments?: TextFragments]
+                : readonly [path: Path, qs?: Qs, parsers?: QueryStringParsers, textFragments?: TextFragments]
             : readonly [path: Path]
         : QueryString.Has<Path> extends true
         ? QueryString.HasRequired<Path> extends true
-            ? readonly [path: Path, params: Params, qs: Qs, parsers?: QueryStringParsers]
-            : readonly [path: Path, params: Params, qs?: Qs, parsers?: QueryStringParsers]
+            ? readonly [path: Path, params: Params, qs: Qs, parsers?: QueryStringParsers, textFragments?: TextFragments]
+            : readonly [path: Path, params: Params, qs?: Qs, parsers?: QueryStringParsers, textFragments?: TextFragments]
         : readonly [path: Path, params: Paths.Parse<Path>]
 ) => Paths.Parse<Path> extends null
     ? QueryString.Assign<Path, NonNullable<Qs>>

src/router/link.tsx

@@ -57,4 +57,6 @@ export namespace Paths {
               Params,
               Number.Add<I, 1>
           >;
+
+    export type Has<T extends string> = T extends `${string}/:${string}` ? true : T extends `${string}/<:${string}` ? true : false;
 }

src/types/index.ts

@@ -0,0 +1,46 @@
+export type TextFragment = {
+    text: string;
+    prefix?: string;
+    suffix?: string;
+};
+
+const regex = /(?<prefix>\w+-,)?.*?(?<suffix>,-\w+)?/;
+
+const specialText = (str: string): TextFragment => {
+    const groups = (regex.exec(str) as any)?.groups;
+    if (!groups) return { text: str };
+    const text = str.replace(groups.prefix || "", "").replace(groups.suffix || "", "");
+    const prefix = groups.prefix?.replace(/-$/, "");
+    const suffix = groups.suffix?.replace(/^-/, "");
+    return { text, prefix, suffix };
+};
+
+export const TEXT_FRAGMENT_ID = ":~:";
+
+const hasTextIdentifier = (url: string) => url.includes(TEXT_FRAGMENT_ID);
+
+export const stringifyTextFragment = (textFragments: TextFragment[]) =>
+    textFragments
+        .map((x) => {
+            let text = "text=";
+            if (x.prefix) text += `${x.prefix}-,`;
+            text += `${x.text}`;
+            if (x.suffix) text += `,-${x.suffix}`;
+            return text;
+        })
+        .join("&");
+
+export const parseTextFragment = (url: string): TextFragment[] | null => {
+    if (!("fragmentDirective" in document)) {
+        return null;
+    }
+    const u = new URL(url);
+    const hash = u.hash;
+    const textFragment = hash.split(TEXT_FRAGMENT_ID)[1];
+    if (!textFragment) return null;
+    return textFragment.split("&").reduce<TextFragment[]>((acc, el) => {
+        const v = el.split("=")[1] || "";
+        const text = decodeURIComponent(v);
+        return [...acc, v.includes(",") ? specialText(text) : { text }];
+    }, []);
+};

src/types/paths.ts

@@ -3,6 +3,7 @@ import { fromValueToString, QueryStringMapper } from "./mappers";
 import type { Paths } from "../types/paths";
 import type { QueryString } from "../types/query-string";
 import { X } from "../types/x";
+import { stringifyTextFragment, TEXT_FRAGMENT_ID, TextFragment } from "./text-fragment";
 
 export const has = <T extends {}, K extends X.AnyString<keyof T>>(o: T, k: K): k is K => Object.prototype.hasOwnProperty.call(o, k as any);
 
@@ -13,13 +14,22 @@ const replaceUrlParams = <Path extends string, Keys extends Paths.Parse<Path>>(p
         .replace(/:(\w+)/g, (_, b) => `${(keys as any)[b]}`);
 };
 
-export const mergeUrlEntities = (url: string, params: any | undefined, qs: any | undefined, parsers?: Partial<QueryStringMapper<string>>) => {
+export const mergeUrlEntities = (
+    url: string,
+    params: any | undefined,
+    qs: any | undefined,
+    parsers: Partial<QueryStringMapper<string>> | undefined,
+    textFragment: TextFragment[] | undefined
+) => {
     const u = urlEntity(url);
     const path = u.pathname;
     const withParams = replaceUrlParams(path, params);
     const queryString = qs === undefined ? "" : qsToString(url, qs, parsers);
     const href = queryString === "" ? withParams : `${withParams}?${queryString}`;
-    return u.hash ? `${href}#${u.hash}` : href;
+    const hasFragments = textFragment !== undefined && textFragment.length >= 1;
+    return u.hash || hasFragments
+        ? `${href}${u.hash || "#"}${hasFragments ? `${TEXT_FRAGMENT_ID}${stringifyTextFragment(textFragment!)}` : ""}`
+        : href;
 };
 
 export const trailingOptionalPath = (str: string) => str.replace(/\/+$/g, "/?");
@@ -103,7 +113,7 @@ export const qsToString = <Path extends string, T extends QueryString.Map>(
 export const createLink =
     <T extends readonly Route[]>(_routes: T): CreateHref<T> =>
     (...args: any): any =>
-        mergeUrlEntities(args[0], args[1], args[2], args[3]) as never;
+        mergeUrlEntities(args[0], args[1], args[2], args[3], args[4]) as never;
 
 const rankBinds = (path: string) => path.split(":").length * 5;
 

src/utils/text-fragment.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "vitest";
+import { mergeUrlEntities } from "../src";
+
+describe("Should test mergeUrlEntities utility", () => {
+    test("Should create a simple url", () => {
+        const url = mergeUrlEntities("/", {}, {}, undefined, []);
+        expect(url).toBe("/");
+    });
+
+    test("Should create a params url", () => {
+        const url = mergeUrlEntities("/:id", { id: "1" }, {}, undefined, []);
+        expect(url).toBe("/1");
+    });
+
+    test("Should create a query string url", () => {
+        const url = mergeUrlEntities("/?name=string", {}, { name: "name" }, undefined, []);
+        expect(url).toBe("/?name=name");
+    });
+
+    test("Should create a query string url", () => {
+        const url = mergeUrlEntities("/?name=string", {}, { name: "name" }, undefined, []);
+        expect(url).toBe("/?name=name");
+    });
+
+    test("Should create a text-fragment url with hash", () => {
+        const url = mergeUrlEntities("/#hash", {}, {}, undefined, [{ text: "test" }]);
+        expect(url).toBe("/#hash:~:text=test");
+    });
+
+    test("Should create a text-fragment url without hash", () => {
+        const url = mergeUrlEntities("/", {}, {}, undefined, [{ text: "test" }]);
+        expect(url).toBe("/#:~:text=test");
+    });
+
+    test("Should create multiple text-fragment url", () => {
+        const url = mergeUrlEntities("/", {}, {}, undefined, [{ text: "test" }, { text: "fragments" }]);
+        expect(url).toBe("/#:~:text=test&text=fragments");
+    });
+
+    test("Should create a text-fragment using prefix", () => {
+        const url = mergeUrlEntities("/", {}, {}, undefined, [{ text: "test", prefix: "property" }]);
+        expect(url).toBe("/#:~:text=property-,test");
+    });
+
+    test("Should create a text-fragment using suffix", () => {
+        const url = mergeUrlEntities("/", {}, {}, undefined, [{ text: "test", suffix: "property" }]);
+        expect(url).toBe("/#:~:text=test,-property");
+    });
+
+    test("Should create a text-fragment using both prefix and suffix", () => {
+        const url = mergeUrlEntities("/", {}, {}, undefined, [{ text: "test", prefix: "prefix", suffix: "suffix" }]);
+        expect(url).toBe("/#:~:text=prefix-,test,-suffix");
+    });
+});