zudoku 0.0.0-e5be921 → 0.0.0-e614aaa

package/src/lib/plugins/search-pagefind/index.tsx

@@ -0,0 +1,21 @@
+import type { ZudokuConfig } from "../../../config/validators/validate.js";
+import { ClientOnly } from "../../components/ClientOnly.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
+import { PagefindSearch } from "./PagefindSearch.js";
+
+export type PagefindOptions = Extract<
+  ZudokuConfig["search"],
+  { type: "pagefind" }
+>;
+
+export const pagefindSearchPlugin = (
+  options: PagefindOptions,
+): ZudokuPlugin => {
+  return {
+    renderSearch: ({ isOpen, onClose }) => (
+      <ClientOnly>
+        <PagefindSearch isOpen={isOpen} onClose={onClose} options={options} />
+      </ClientOnly>
+    ),
+  };
+};

package/src/lib/plugins/search-pagefind/types.ts

@@ -0,0 +1,118 @@
+interface PagefindIndexOptions {
+  basePath?: string;
+  baseUrl?: string;
+  excerptLength?: number;
+  indexWeight?: number;
+  mergeFilter?: Record<string, unknown>;
+  highlightParam?: string;
+  language?: string;
+  primary?: boolean;
+  ranking?: PagefindRankingWeights;
+}
+
+interface PagefindRankingWeights {
+  termSimilarity?: number;
+  pageLength?: number;
+  termSaturation?: number;
+  termFrequency?: number;
+}
+
+interface PagefindSearchOptions {
+  preload?: boolean;
+  verbose?: boolean;
+  filters?: Record<string, unknown>;
+  sort?: Record<string, unknown>;
+}
+
+type PagefindFilterCounts = Record<string, Record<string, number>> & {};
+
+interface PagefindSearchResults {
+  results: PagefindSearchResult[];
+  unfilteredResultCount: number;
+  filters: PagefindFilterCounts;
+  totalFilters: PagefindFilterCounts;
+  timings: {
+    preload: number;
+    search: number;
+    total: number;
+  };
+}
+
+interface PagefindSearchResult {
+  id: string;
+  score: number;
+  words: number[];
+  data: () => Promise<PagefindSearchFragment>;
+}
+
+interface PagefindSearchFragment {
+  url: string;
+  raw_url?: string;
+  content: string;
+  raw_content?: string;
+  excerpt: string;
+  sub_results: PagefindSubResult[];
+  word_count: number;
+  locations: number[];
+  weighted_locations: PagefindWordLocation[];
+  filters: Record<string, string[]>;
+  meta: Record<string, string>;
+  anchors: PagefindSearchAnchor[];
+}
+
+interface PagefindSubResult {
+  title: string;
+  url: string;
+  locations: number[];
+  weighted_locations: PagefindWordLocation[];
+  excerpt: string;
+  anchor?: PagefindSearchAnchor;
+}
+
+interface PagefindWordLocation {
+  weight: number;
+  balanced_score: number;
+  location: number;
+}
+
+interface PagefindSearchAnchor {
+  element: string;
+  id: string;
+  text?: string;
+  location: number;
+}
+
+interface Pagefind {
+  debouncedSearch: (
+    query: string,
+    options?: PagefindSearchOptions,
+    duration?: number,
+  ) => Promise<PagefindSearchResults>;
+  destroy: () => Promise<void>;
+  filters: () => Promise<PagefindFilterCounts>;
+  init: () => Promise<void>;
+  mergeIndex: (
+    indexPath: string,
+    options?: Record<string, unknown>,
+  ) => Promise<void>;
+  options: (options: PagefindIndexOptions) => Promise<void>;
+  preload: (term: string, options?: PagefindIndexOptions) => Promise<void>;
+  search: (
+    term: string,
+    options?: PagefindSearchOptions,
+  ) => Promise<PagefindSearchResults>;
+}
+
+export type {
+  Pagefind,
+  PagefindFilterCounts,
+  PagefindIndexOptions,
+  PagefindRankingWeights,
+  PagefindSearchAnchor,
+  PagefindSearchFragment,
+  PagefindSearchOptions,
+  PagefindSearchResult,
+  PagefindSearchResults,
+  PagefindSubResult,
+  PagefindWordLocation,
+};

package/src/lib/ui/Badge.tsx

@@ -4,7 +4,7 @@ import * as React from "react";
 import { cn } from "../util/cn.js";
 
 const badgeVariants = cva(
-  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
   {
     variants: {
       variant: {
@@ -12,6 +12,7 @@ const badgeVariants = cva(
           "border-transparent bg-primary text-primary-foreground hover:bg-primary/80",
         secondary:
           "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        muted: "bg-muted text-muted-foreground ",
         destructive:
           "border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
         outline: "text-foreground",

package/src/lib/ui/Card.tsx

@@ -8,7 +8,7 @@ const Card = React.forwardRef<
   <div
     ref={ref}
     className={cn(
-      "rounded-xl border bg-card text-card-foreground shadow",
+      "rounded-xl border bg-card text-card-foreground shadow-sm",
       className,
     )}
     {...props}

package/src/lib/ui/Checkbox.tsx

@@ -1,19 +1,36 @@
 import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
+import { cva, type VariantProps } from "class-variance-authority";
 import { Check } from "lucide-react";
 import * as React from "react";
 
 import { cn } from "../util/cn.js";
 
+const checkboxVariants = cva(
+  "peer h-4 w-4 shrink-0 rounded-sm ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:text-primary",
+  {
+    variants: {
+      variant: {
+        default: "border border-primary data-[state=checked]:bg-primary",
+        outline: "border border-input data-[state=checked]:bg-accent",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+interface CheckboxProps
+  extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,
+    VariantProps<typeof checkboxVariants> {}
+
 const Checkbox = React.forwardRef<
   React.ElementRef<typeof CheckboxPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
->(({ className, ...props }, ref) => (
+  CheckboxProps
+>(({ className, variant, ...props }, ref) => (
   <CheckboxPrimitive.Root
     ref={ref}
-    className={cn(
-      "peer h-4 w-4 shrink-0 rounded-sm border border-primary ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
-      className,
-    )}
+    className={cn(checkboxVariants({ variant, className }))}
     {...props}
   >
     <CheckboxPrimitive.Indicator
@@ -25,4 +42,4 @@ const Checkbox = React.forwardRef<
 ));
 Checkbox.displayName = CheckboxPrimitive.Root.displayName;
 
-export { Checkbox };
+export { Checkbox, type CheckboxProps };

package/src/lib/ui/Command.tsx

@@ -2,6 +2,7 @@ import { type DialogProps } from "@radix-ui/react-dialog";
 import { Command as CommandPrimitive } from "cmdk";
 import { Search } from "lucide-react";
 import * as React from "react";
+import { ComponentPropsWithoutRef } from "react";
 import { Dialog, DialogContent } from "zudoku/ui/Dialog.js";
 import { cn } from "../util/cn.js";
 
@@ -20,11 +21,32 @@ const Command = React.forwardRef<
 ));
 Command.displayName = CommandPrimitive.displayName;
 
-const CommandDialog = ({ children, ...props }: DialogProps) => {
+const CommandDialog = ({
+  children,
+  command,
+  content,
+  ...props
+}: DialogProps & {
+  command?: ComponentPropsWithoutRef<typeof CommandPrimitive>;
+  content?: ComponentPropsWithoutRef<typeof DialogContent>;
+}) => {
   return (
     <Dialog {...props}>
-      <DialogContent className="overflow-hidden p-0 shadow-lg">
-        <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
+      <DialogContent
+        {...content}
+        className={cn(
+          "overflow-hidden p-0 shadow-lg top-[15vh] translate-y-[0%]",
+          content?.className,
+        )}
+        aria-describedby={undefined}
+      >
+        <Command
+          {...command}
+          className={cn(
+            "[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5",
+            command?.className,
+          )}
+        >
           {children}
         </Command>
       </DialogContent>
@@ -52,6 +74,25 @@ const CommandInput = React.forwardRef<
 
 CommandInput.displayName = CommandPrimitive.Input.displayName;
 
+const CommandInlineInput = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Input>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
+>(({ className, ...props }, ref) => (
+  // eslint-disable-next-line react/no-unknown-property
+  <div className="flex items-center" cmdk-input-wrapper="">
+    <CommandPrimitive.Input
+      ref={ref}
+      className={cn(
+        "flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50",
+        "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+        className,
+      )}
+      {...props}
+    />
+  </div>
+));
+
+CommandInlineInput.displayName = CommandPrimitive.Input.displayName;
 const CommandList = React.forwardRef<
   React.ElementRef<typeof CommandPrimitive.List>,
   React.ComponentPropsWithoutRef<typeof CommandPrimitive.List>
@@ -143,6 +184,7 @@ export {
   CommandDialog,
   CommandEmpty,
   CommandGroup,
+  CommandInlineInput,
   CommandInput,
   CommandItem,
   CommandList,

package/src/lib/ui/Input.tsx

@@ -1,8 +1,7 @@
 import * as React from "react";
 import { cn } from "../util/cn.js";
 
-export interface InputProps
-  extends React.InputHTMLAttributes<HTMLInputElement> {}
+type InputProps = React.InputHTMLAttributes<HTMLInputElement>;
 
 const Input = React.forwardRef<HTMLInputElement, InputProps>(
   ({ className, type, ...props }, ref) => {

package/src/lib/ui/Select.tsx

@@ -83,9 +83,9 @@ const SelectContent = React.forwardRef<
       <SelectScrollUpButton />
       <SelectPrimitive.Viewport
         className={cn(
-          "p-1",
           position === "popper" &&
             "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)]",
+          "divide-y",
         )}
       >
         {children}

package/src/lib/ui/Stepper.css

@@ -0,0 +1,43 @@
+@tailwind components;
+
+@layer components {
+  .stepper {
+    /* @apply mb-6; */
+  }
+
+  .stepper > ol {
+    --bullet-size: 1.75rem;
+    --line-spacing: 0.25rem;
+    @apply flex flex-col list-none p-0 m-0;
+    counter-reset: step-counter;
+  }
+
+  .stepper > ol > li {
+    @apply relative ps-12 pb-6 my-0;
+    counter-increment: step-counter;
+  }
+
+  .stepper > ol > li:last-child {
+    @apply pb-0;
+  }
+
+  /* Bullet with number */
+  .stepper > ol > li::before {
+    @apply absolute left-0 flex items-center justify-center size-[--bullet-size];
+    @apply bg-muted/80 border border-border text-muted-foreground text-[calc(var(--bullet-size)/2)] font-semibold rounded-full;
+    content: counter(step-counter);
+  }
+
+  /* Vertical line */
+  .stepper > ol > li::after {
+    @apply absolute content-[''] w-[2px] bg-border -translate-x-1/2;
+    left: calc(var(--bullet-size) / 2);
+    top: calc(var(--bullet-size) + var(--line-spacing));
+    height: calc(100% - var(--bullet-size) - (2 * var(--line-spacing)));
+  }
+
+  .stepper > ol > li > :first-child {
+    @apply mt-0 pt-0;
+    transform: translateY(calc((var(--bullet-size) - 1lh) / 2));
+  }
+}

package/src/lib/ui/Stepper.tsx

@@ -0,0 +1,8 @@
+import type { PropsWithChildren } from "react";
+import "./Stepper.css";
+
+const Stepper = ({ children }: PropsWithChildren) => {
+  return <div className="stepper">{children}</div>;
+};
+
+export { Stepper };

package/src/lib/{components → ui}/SyntaxHighlight.tsx

@@ -31,16 +31,20 @@ void import("prismjs/components/prism-typescript.min.js");
 
 import { useTheme } from "next-themes";
 import { useState } from "react";
+import { ClientOnly } from "../components/ClientOnly.js";
 import { cn } from "../util/cn.js";
-import { ClientOnly } from "./ClientOnly.js";
 
-type SyntaxHighlightProps = {
+export type SyntaxHighlightProps = {
   className?: string;
   noBackground?: boolean;
   wrapLines?: boolean;
-  copyable?: boolean;
   showLanguageIndicator?: boolean;
   language?: string;
+  title?: string;
+  children?: string;
+  code?: string;
+  showCopy?: "hover" | "always" | "never";
+  showCopyText?: boolean;
 } & Omit<HighlightProps, "children" | "language">;
 
 const remapLang = {
@@ -48,14 +52,19 @@ const remapLang = {
 } as Record<string, string>;
 
 export const SyntaxHighlight = ({
-  copyable = true,
   language = "plain",
+  showCopy = "hover",
+  showCopyText,
+  title,
+  children,
   ...props
 }: SyntaxHighlightProps) => {
   const { resolvedTheme } = useTheme();
   const [isCopied, setIsCopied] = useState(false);
 
-  if (!props.code) {
+  const code = children ?? props.code;
+
+  if (!code) {
     return null;
   }
 
@@ -70,15 +79,21 @@ export const SyntaxHighlight = ({
     <ClientOnly
       fallback={
         <div className="relative group">
+          {title && (
+            <div className="text-xs text-muted-foreground absolute top-2 font-mono border-b w-full pb-2 px-4 ">
+              {title}
+            </div>
+          )}
           <pre
             className={cn(
               "relative scrollbar overflow-x-auto",
               props.className,
               props.noBackground ? "!bg-transparent" : themeColorClasses,
               props.wrapLines && "whitespace-pre-wrap break-words",
+              title && "pt-10",
             )}
           >
-            {props.code}
+            {code}
           </pre>
           {props.showLanguageIndicator && (
             <span className="absolute top-1.5 right-3 text-[11px] font-mono text-muted-foreground transition group-hover:opacity-0">
@@ -92,9 +107,15 @@ export const SyntaxHighlight = ({
         theme={highlightTheme}
         language={remapLang[language] ?? language}
         {...props}
+        code={code}
       >
         {({ className, style, tokens, getLineProps, getTokenProps }) => (
           <div className="relative group">
+            {title && (
+              <div className="text-xs text-muted-foreground absolute top-2 font-mono border-b w-full pb-2 px-4 ">
+                {title}
+              </div>
+            )}
             <pre
               className={cn(
                 "relative scrollbar overflow-x-auto",
@@ -102,6 +123,7 @@ export const SyntaxHighlight = ({
                 props.className,
                 props.noBackground && "!bg-transparent",
                 props.wrapLines && "whitespace-pre-wrap break-words",
+                title && "pt-10",
               )}
               style={style}
             >
@@ -120,12 +142,18 @@ export const SyntaxHighlight = ({
                 {language}
               </span>
             )}
-            {copyable && (
+            {showCopy !== "never" && (
               <button
                 type="button"
                 aria-label="Copy code"
                 title="Copy code"
-                className="absolute top-2 right-2 p-2 opacity-0 group-hover:opacity-100 group-hover:bg-zinc-100 group-hover:dark:bg-zinc-700 hover:outline hover:outline-border/75 dark:hover:outline-border rounded-md text-sm text-gray-400 hover:text-gray-600 dark:text-gray-500 dark:hover:text-gray-400 transition"
+                className={cn(
+                  "absolute top-2 right-2 p-2  hover:outline hover:outline-border/75 dark:hover:outline-border rounded-md text-sm text-muted-foreground transition",
+                  showCopy === "hover"
+                    ? "opacity-0 group-hover:opacity-100 group-hover:bg-zinc-100 group-hover:dark:bg-zinc-700"
+                    : "bg-zinc-100 dark:bg-zinc-700",
+                  showCopyText && "flex gap-2 items-center font-medium",
+                )}
                 disabled={isCopied}
                 onClick={() => {
                   setIsCopied(true);
@@ -147,6 +175,7 @@ export const SyntaxHighlight = ({
                 ) : (
                   <CopyIcon size={16} />
                 )}
+                {showCopyText && "Copy"}
               </button>
             )}
           </div>

package/src/lib/ui/util.tsx

@@ -0,0 +1,3 @@
+import { cn as cnUtil } from "../util/cn.js";
+
+export const cn = cnUtil;

package/src/lib/util/MdxComponents.tsx

@@ -1,14 +1,14 @@
-import { MDXComponents } from "mdx/types.js";
-import { Link } from "react-router-dom";
+import { type MDXComponents } from "mdx/types.js";
+import { Link } from "react-router";
 import { Heading } from "../components/Heading.js";
 import { InlineCode } from "../components/InlineCode.js";
-import { SyntaxHighlight } from "../components/SyntaxHighlight.js";
 import { Callout } from "../ui/Callout.js";
+import { Stepper } from "../ui/Stepper.js";
+import { SyntaxHighlight } from "../ui/SyntaxHighlight.js";
 
 export type MdxComponentsType = Readonly<MDXComponents> | null | undefined;
 
 export const MdxComponents = {
-  // @ts-expect-error Node is not in types but still gets passed
   img: ({ node, ...props }) => {
     if (/\.(mp4|webm|mov|avi)$/.test(props.src ?? "")) {
       return <video src={props.src} controls playsInline autoPlay loop />;
@@ -45,7 +45,6 @@ export const MdxComponents = {
       {children}
     </Heading>
   ),
-  // @ts-expect-error Node is not in types but still gets passed
   a: ({ href, node, ...props }) =>
     href && !href.startsWith("http") ? (
       <Link to={href} relative="path" {...props} />
@@ -53,6 +52,8 @@ export const MdxComponents = {
       <a href={href} target="_blank" {...props} rel="noreferrer" />
     ),
   Callout,
+  Stepper,
+  SyntaxHighlight,
   tip: (props) => <Callout type="tip" {...props} />,
   info: (props) => <Callout type="info" {...props} />,
   note: (props) => <Callout type="note" {...props} />,
@@ -63,7 +64,7 @@ export const MdxComponents = {
   code: ({ className, children, ...props }) => {
     // `inline` provided by the rehype plugin, as react-markdown removed support for that
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const inline = (props as any).inline;
+    const { inline, title } = props as Record<string, unknown>;
 
     if (inline === true || inline === "true") {
       return <InlineCode className={className}>{children}</InlineCode>;
@@ -77,6 +78,7 @@ export const MdxComponents = {
         className="rounded-xl p-4 border dark:!bg-foreground/10 dark:border-transparent"
         showLanguageIndicator
         code={String(children).trim()}
+        title={typeof title === "string" ? title : undefined}
       />
     );
   },

package/src/lib/util/createVariantComponent.tsx

@@ -2,11 +2,11 @@ import { Slot } from "@radix-ui/react-slot";
 import { cva } from "class-variance-authority";
 import type { ClassValue } from "clsx";
 import * as React from "react";
-import type { JSX } from "react/jsx-runtime";
+import { type HTMLElementType, type JSX } from "react";
 import { cn } from "./cn.js";
 
 const createVariantComponent = <
-  E extends keyof React.ReactHTML,
+  E extends HTMLElementType,
   C extends ReturnType<typeof cva>,
 >(
   tag: E,

package/src/lib/util/joinUrl.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "vitest";
+import { joinUrl } from "./joinUrl.js";
+
+describe("joinUrl", () => {
+  test("handles basic URL joining", () => {
+    expect(joinUrl("https://example.com", "path")).toBe(
+      "https://example.com/path",
+    );
+    expect(joinUrl("https://example.com/", "path")).toBe(
+      "https://example.com/path",
+    );
+    expect(joinUrl("https://example.com/", "/path")).toBe(
+      "https://example.com/path",
+    );
+  });
+
+  test("handles multiple path segments", () => {
+    expect(joinUrl("https://example.com", "api", "v1", "users")).toBe(
+      "https://example.com/api/v1/users",
+    );
+  });
+
+  // test("handles query parameters", () => {
+  //   expect(joinUrl("https://example.com", "path?query=1")).toBe(
+  //     "https://example.com/path?query=1",
+  //   );
+  //   expect(joinUrl("https://example.com?base=1", "path?query=1")).toBe(
+  //     "https://example.com/path?query=1",
+  //   );
+  // });
+
+  // test("handles repeated dots and question marks", () => {
+  //   expect(joinUrl("https://example.com", "path/../../../test")).toBe(
+  //     "https://example.com/path/../../../test",
+  //   );
+  //   expect(joinUrl("https://example.com", "test????a=1")).toBe(
+  //     "https://example.com/test????a=1",
+  //   );
+  // });
+
+  test("handles falsy values", () => {
+    expect(joinUrl("https://example.com", null, undefined, false, "path")).toBe(
+      "https://example.com/path",
+    );
+  });
+
+  test("handles numeric values", () => {
+    expect(joinUrl("https://example.com", "api", 123, "test")).toBe(
+      "https://example.com/api/123/test",
+    );
+  });
+
+  test("handles relative paths", () => {
+    expect(joinUrl("/api", "v1", "users")).toBe("/api/v1/users");
+    expect(joinUrl("api", "v1", "users")).toBe("/api/v1/users");
+  });
+
+  test("handles empty input", () => {
+    expect(joinUrl()).toBe("/");
+    expect(joinUrl("")).toBe("/");
+  });
+});

package/src/lib/util/joinUrl.ts

@@ -0,0 +1,57 @@
+// Mostly adapted from https://github.com/moxystudio/js-proper-url-join
+const defaultUrlRegExp = /^(\w+:\/\/[^/?]+)?([^?]*)(\?.*)?$/;
+
+const normalizeParts = (
+  parts: (string | number | null | undefined | false)[],
+): string[] =>
+  parts
+    .filter(
+      (part): part is string | number =>
+        part !== null &&
+        part !== undefined &&
+        part !== false &&
+        (typeof part === "string" || typeof part === "number"),
+    )
+    .map((part) => `${part}`)
+    .filter((part) => part);
+
+interface ParsedParts {
+  prefix: string;
+  pathname: string[];
+}
+
+const parseParts = (parts: string[]): ParsedParts => {
+  const partsStr = parts.join("/");
+  const [, prefix = "", pathname = ""] = partsStr.match(defaultUrlRegExp) ?? [];
+
+  return {
+    prefix,
+    pathname: pathname.split("/").filter((part) => part !== ""),
+  };
+};
+
+const buildUrl = (parsedParts: ParsedParts): string => {
+  const { prefix, pathname } = parsedParts;
+  let url = prefix;
+
+  if (pathname.length > 0) {
+    if (url) {
+      url += "/";
+    } else {
+      url = "/";
+    }
+    url += pathname.join("/");
+  } else if (!url) {
+    url = "/";
+  }
+
+  return url;
+};
+
+export const joinUrl = (
+  ...parts: Array<string | number | null | undefined | false>
+): string => {
+  const normalizedParts = normalizeParts(parts);
+  const parsedParts = parseParts(normalizedParts);
+  return buildUrl(parsedParts);
+};