feat: text-fragments implementation

Author: OrionFable

src/index.ts

@@ -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";

src/router/link.tsx

@@ -4,6 +4,7 @@ import { useBasename, useHref, useNavigation } from "../brouther/brouther";
 import type { QueryString } from "../types/query-string";
 import { AnyJson } from "../types";
 import { Paths } from "../types/paths";
+import { TextFragment } from "../utils/text-fragment";
 
 const isLeftClick = (e: React.MouseEvent) => e.button === 0;
 
@@ -18,20 +19,21 @@ export type LinkProps<Path extends string> = Omit<AnchorProps, "href" | "onClick
     href: Path;
     state?: AnyJson;
     replace?: boolean;
+    fragments?: TextFragment[];
     onClick?: (event: Parameters<NonNullable<AnchorProps["onClick"]>>[0], pathAndQuery: QueryAndPaths<Path>) => void;
 } & QueryAndPaths<Path>;
 
 const httpRegex = /^https?:\/\//;
 
 export const Link: <TPath extends string>(props: LinkProps<TPath>) => React.ReactElement = forwardRef(
     <TPath extends string>(
-        { href, state, replace = false, onClick, query, paths, ...props }: LinkProps<TPath>,
+        { href, state, replace = false, onClick, 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 _href = httpRegex.test(href) ? href : join(basename, mergeUrlEntities(href, paths, query, undefined, fragments));
         const _onClick: NonNullable<AnchorProps["onClick"]> = (event) => {
             if (props.target === undefined && props.target !== "_self") event.preventDefault();
             if (_href === contextHref) return;

src/types/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/utils/text-fragment.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/utils/utils.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;
 

tests/create-url.test.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");
+    });
+});