@harpy-js/core 0.4.7

package/src/cli.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+const { spawn } = require("child_process");
+const path = require("path");
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+const scripts: Record<string, string> = {
+  "build-hydration": path.join(__dirname, "../scripts/build-hydration.ts"),
+  "auto-wrap": path.join(__dirname, "../scripts/auto-wrap-exports.ts"),
+  "build-styles": path.join(__dirname, "../scripts/build-page-styles.ts"),
+  dev: path.join(__dirname, "../scripts/dev.ts"),
+};
+
+if (!command || !scripts[command]) {
+  console.error("Usage: harpy <command>");
+  console.error("Commands: build-hydration, auto-wrap, build-styles, dev");
+  process.exit(1);
+}
+
+const scriptPath = scripts[command];
+
+// Find tsx in node_modules - check multiple possible locations
+const findTsx = (): string => {
+  const fs = require("fs");
+  const possiblePaths = [
+    path.join(process.cwd(), "node_modules", ".bin", "tsx"),
+    path.join(process.cwd(), "apps", "test-app", "node_modules", ".bin", "tsx"),
+    path.join(__dirname, "../../node_modules", ".bin", "tsx"),
+    path.join(__dirname, "../../../node_modules", ".bin", "tsx"),
+    path.join(__dirname, "../../../../node_modules", ".bin", "tsx"),
+  ];
+
+  for (const tsxPath of possiblePaths) {
+    if (fs.existsSync(tsxPath)) {
+      return tsxPath;
+    }
+  }
+
+  // If tsx not found anywhere, throw error with helpful message
+  throw new Error(
+    "tsx not found. Please install tsx in your project: npm install -D tsx",
+  );
+};
+
+const tsxCmd = findTsx();
+
+// Handle "node --import" or "node --loader" commands
+let execCommand: string;
+let cmdArgs: string[];
+
+if (tsxCmd.startsWith("node ")) {
+  // Split node command and its flags
+  const parts = tsxCmd.split(" ");
+  execCommand = parts[0]; // 'node'
+  cmdArgs = [...parts.slice(1), scriptPath, ...args];
+} else {
+  // Direct tsx binary
+  execCommand = tsxCmd;
+  cmdArgs = [scriptPath, ...args];
+}
+
+const proc = spawn(execCommand, cmdArgs, {
+  stdio: "inherit",
+  shell: false,
+});
+
+proc.on("exit", (code: number | null) => {
+  process.exit(code || 0);
+});

package/src/client/Link.tsx

@@ -0,0 +1,62 @@
+import React, { AnchorHTMLAttributes, MouseEvent, useCallback } from "react";
+
+export type LinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
+  replace?: boolean;
+};
+
+/**
+ * A drop-in replacement for an `<a>` tag that performs client-side
+ * navigation for same-origin/internal links and falls back to a normal
+ * anchor for external links or when modifier keys / non-primary buttons
+ * are used. This keeps behaviour identical to a native `<a>` while
+ * enabling SPA-style history navigation when appropriate.
+ */
+export default function Link({
+  href = "#",
+  onClick,
+  replace,
+  ...rest
+}: LinkProps) {
+  const isLocal = typeof href === "string" && href.startsWith("/");
+
+  const handleClick = useCallback(
+    (e: MouseEvent<HTMLAnchorElement>) => {
+      if (onClick) {
+        onClick(e as unknown as any);
+      }
+
+      // If the event was already handled by a consumer, do nothing.
+      if (e.defaultPrevented) return;
+
+      // Let the browser handle clicks that intend to open a new tab/window
+      // or use a non-primary button.
+      if (e.button !== 0 || e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) {
+        return;
+      }
+
+      // External links: allow browser default.
+      if (!isLocal) return;
+
+      // Prevent full page reload and update history instead.
+      e.preventDefault();
+
+      try {
+        const method = replace ? "replaceState" : "pushState";
+        // @ts-ignore DOM typings are available in consumer environments
+        window.history[method]({}, "", href as string);
+        // Inform any listeners (e.g., client-side router) that the location changed.
+        window.dispatchEvent(new PopStateEvent("popstate"));
+      } catch (err) {
+        // If anything goes wrong, fall back to normal navigation.
+        // Do a full navigation as a last resort.
+        window.location.assign(href as string);
+      }
+    },
+    [href, isLocal, onClick, replace],
+  );
+
+  // Render a normal anchor for full compatibility (SEO, right-click,
+  // middle-click, screen readers). We only intercept clicks when it's
+  // safe to do SPA-style navigation.
+  return <a href={href} onClick={handleClick} {...rest} />;
+}

package/src/client/__tests__/getActiveItemId.test.ts

@@ -0,0 +1,49 @@
+import {
+  buildHrefIndex,
+  getActiveItemIdFromIndex,
+  getActiveItemIdFromManifest,
+} from '../getActiveItemId';
+
+describe('getActiveItemId helpers', () => {
+  const items = [
+    { id: 'home', href: '/' },
+    { id: 'docs', href: '/docs' },
+    { id: 'docs-start', href: '/docs/getting-started' },
+    { id: 'about', href: '/about/' },
+  ];
+
+  test('exact match prefers exact href over ancestor', () => {
+    const id = getActiveItemIdFromManifest(items, '/docs/getting-started');
+    expect(id).toBe('docs-start');
+  });
+
+  test('ancestor matching finds parent when exact missing', () => {
+    const id = getActiveItemIdFromManifest(items, '/docs/usage');
+    expect(id).toBe('docs');
+  });
+
+  test('normalizes query and fragment and trailing slash', () => {
+    const id = getActiveItemIdFromManifest(items, '/about?lang=en#team');
+    // item href '/about/' should match '/about?lang=en#team'
+    expect(id).toBe('about');
+  });
+
+  test('root fallback matches when no other match', () => {
+    const id = getActiveItemIdFromManifest(items, '/unknown/path');
+    // root '/' exists and is the fallback in ancestor trimming
+    expect(id).toBe('home');
+  });
+
+  test('returns undefined when no match and no root', () => {
+    const itemsNoRoot = items.filter((i) => i.href !== '/');
+    const id = getActiveItemIdFromManifest(itemsNoRoot, '/unknown/path');
+    expect(id).toBeUndefined();
+  });
+
+  test('index-based lookup returns same result as manifest-based', () => {
+    const idx = buildHrefIndex(items);
+    const byIndex = getActiveItemIdFromIndex(idx, '/docs/guide/intro');
+    const byManifest = getActiveItemIdFromManifest(items, '/docs/guide/intro');
+    expect(byIndex).toBe(byManifest);
+  });
+});

package/src/client/getActiveItemId.ts

@@ -0,0 +1,54 @@
+export type NavItemLite = { id: string; href?: string };
+
+function normalizePath(p?: string): string {
+  if (!p) return "";
+  const withoutQuery = p.split(/[?#]/)[0];
+  if (withoutQuery.length > 1 && withoutQuery.endsWith("/"))
+    return withoutQuery.slice(0, -1);
+  return withoutQuery;
+}
+
+export function buildHrefIndex(items: NavItemLite[]) {
+  const map = new Map<string, string[]>();
+  for (const it of items) {
+    if (!it.href) continue;
+    const key = normalizePath(it.href);
+    const arr = map.get(key) ?? [];
+    arr.push(it.id);
+    map.set(key, arr);
+  }
+  return map;
+}
+
+export function getActiveItemIdFromIndex(
+  hrefIndex: Map<string, string[]>,
+  currentPath?: string,
+): string | undefined {
+  if (!currentPath) return undefined;
+  let cur = normalizePath(currentPath);
+  while (cur !== "") {
+    const entry = hrefIndex.get(cur);
+    if (entry && entry.length > 0) return entry[0];
+    const lastSlash = cur.lastIndexOf("/");
+    if (lastSlash === -1) break;
+    if (lastSlash === 0) {
+      cur = "/";
+    } else {
+      cur = cur.slice(0, lastSlash);
+    }
+    if (cur === "/") {
+      const entryRoot = hrefIndex.get("/");
+      if (entryRoot && entryRoot.length > 0) return entryRoot[0];
+      break;
+    }
+  }
+  return undefined;
+}
+
+export function getActiveItemIdFromManifest(
+  items: NavItemLite[],
+  currentPath?: string,
+): string | undefined {
+  const idx = buildHrefIndex(items);
+  return getActiveItemIdFromIndex(idx, currentPath);
+}

package/src/client/use-i18n.ts

@@ -0,0 +1,111 @@
+/**
+ * React hook for i18n locale switching (Client-side only)
+ *
+ * This hook provides a simple way to switch locales from any component
+ * (buttons, dropdowns, selects, etc.)
+ *
+ * The hook updates the URL with the selected locale and reloads the page.
+ * The server-side interceptor will automatically set the cookie based on the URL.
+ *
+ * When used in a component, it automatically injects the language-aware navigation script.
+ *
+ * @example
+ * ```tsx
+ * import { useI18n } from '@harpy-js/core/client';
+ *
+ * function MyComponent() {
+ *   const { switchLocale } = useI18n();
+ *   return <button onClick={() => switchLocale('fr')}>French</button>;
+ * }
+ * ```
+ */
+
+"use client";
+
+import { useEffect } from "react";
+
+interface UseI18nReturn {
+  switchLocale: (locale: string) => void;
+  getCurrentLocale: () => string | null;
+  buildUrl: (path: string, locale?: string) => string;
+}
+
+export function useI18n(): UseI18nReturn {
+  // Register that this component uses i18n, so the navigation script gets injected
+  useEffect(() => {
+    // Mark that i18n is being used in this render
+    if (
+      typeof window !== "undefined" &&
+      !(window as any).__HARPY_I18N_INITIALIZED__
+    ) {
+      (window as any).__HARPY_I18N_INITIALIZED__ = true;
+
+      // Inject language-aware navigation script
+      const script = document.createElement("script");
+      script.textContent = `
+        (function() {
+          if (window.__HARPY_I18N_NAV_INSTALLED__) return;
+          window.__HARPY_I18N_NAV_INSTALLED__ = true;
+          
+          document.addEventListener('click', function(e) {
+            var target = e.target;
+            while (target && target.tagName !== 'A') {
+              target = target.parentElement;
+            }
+            if (target && target.tagName === 'A' && target.href) {
+              var url = new URL(target.href, window.location.origin);
+              var currentLang = new URLSearchParams(window.location.search).get('lang');
+              if (currentLang && url.origin === window.location.origin && !url.searchParams.has('lang')) {
+                url.searchParams.set('lang', currentLang);
+                target.href = url.toString();
+              }
+            }
+          });
+        })();
+      `;
+      document.head.appendChild(script);
+    }
+  }, []);
+
+  /**
+   * Switch to a new locale by updating the URL and reloading the page
+   */
+  const switchLocale = (locale: string): void => {
+    if (typeof window === "undefined") return;
+
+    const url = new URL(window.location.href);
+    url.searchParams.set("lang", locale);
+    window.location.href = url.toString();
+  };
+
+  /**
+   * Get the current locale from the URL
+   */
+  const getCurrentLocale = (): string | null => {
+    if (typeof window === "undefined") return null;
+
+    const url = new URL(window.location.href);
+    return url.searchParams.get("lang");
+  };
+
+  /**
+   * Build a URL with the current locale preserved
+   * Useful for navigation links that should maintain the language
+   */
+  const buildUrl = (path: string, locale?: string): string => {
+    if (typeof window === "undefined") return path;
+
+    const currentLocale = locale || getCurrentLocale();
+    if (!currentLocale) return path;
+
+    const url = new URL(path, window.location.origin);
+    url.searchParams.set("lang", currentLocale);
+    return url.pathname + url.search;
+  };
+
+  return {
+    switchLocale,
+    getCurrentLocale,
+    buildUrl,
+  };
+}

package/src/core/__tests__/component-analyzer.test.ts

@@ -0,0 +1,141 @@
+import * as fs from "fs";
+import * as path from "path";
+
+jest.mock("fs");
+jest.mock("path");
+
+describe("Component Analyzer", () => {
+  const mockFs = fs as jest.Mocked<typeof fs>;
+  const mockPath = path as jest.Mocked<typeof path>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("client component detection", () => {
+    it('should detect "use client" directive', () => {
+      const code = '"use client";\nexport function MyComponent() {}';
+      expect(code).toContain("use client");
+    });
+
+    it("should detect server components (no directive)", () => {
+      const code = "export function ServerComponent() {}";
+      expect(code).not.toContain("use client");
+    });
+
+    it("should handle single quotes", () => {
+      const code = "'use client';\nexport function Comp() {}";
+      expect(code).toMatch(/['"]use client['"]/);
+    });
+  });
+
+  describe("React hooks detection", () => {
+    it("should detect useState import", () => {
+      const code = 'import { useState } from "react";';
+      expect(code).toContain("useState");
+    });
+
+    it("should detect useEffect import", () => {
+      const code = 'import { useEffect } from "react";';
+      expect(code).toContain("useEffect");
+    });
+
+    it("should detect multiple hooks", () => {
+      const code = 'import { useState, useEffect, useRef } from "react";';
+      expect(code).toContain("useState");
+      expect(code).toContain("useEffect");
+      expect(code).toContain("useRef");
+    });
+  });
+
+  describe("event handler detection", () => {
+    it("should detect onClick handler", () => {
+      const code = "<button onClick={handleClick}>Click</button>";
+      expect(code).toContain("onClick");
+    });
+
+    it("should detect onChange handler", () => {
+      const code = "<input onChange={handleChange} />";
+      expect(code).toContain("onChange");
+    });
+
+    it("should detect onSubmit handler", () => {
+      const code = "<form onSubmit={handleSubmit}>";
+      expect(code).toContain("onSubmit");
+    });
+  });
+
+  describe("component name extraction", () => {
+    it("should extract function component name", () => {
+      const code = "export function MyComponent() {}";
+      const match = code.match(/function\s+(\w+)/);
+      expect(match).toBeDefined();
+      expect(match![1]).toBe("MyComponent");
+    });
+
+    it("should extract arrow function component name", () => {
+      const code = "export const MyComponent = () => {}";
+      const match = code.match(/const\s+(\w+)\s*=/);
+      expect(match).toBeDefined();
+      expect(match![1]).toBe("MyComponent");
+    });
+
+    it("should extract default export name", () => {
+      const code = "export default function Component() {}";
+      const match = code.match(/default\s+function\s+(\w+)/);
+      expect(match).toBeDefined();
+      expect(match![1]).toBe("Component");
+    });
+  });
+
+  describe("file system operations", () => {
+    it("should filter TypeScript files", () => {
+      const files = ["component.tsx", "utils.ts", "styles.css", "test.jsx"];
+      const tsxFiles = files.filter(
+        (f) => f.endsWith(".tsx") || f.endsWith(".jsx"),
+      );
+      expect(tsxFiles).toEqual(["component.tsx", "test.jsx"]);
+    });
+
+    it("should handle path operations", () => {
+      const basePath = "/src";
+      const fileName = "components";
+      const fullPath = `${basePath}/${fileName}`;
+      expect(fullPath).toBe("/src/components");
+    });
+  });
+
+  describe("code analysis patterns", () => {
+    it("should identify React imports", () => {
+      const patterns = [
+        'import React from "react"',
+        'import * as React from "react"',
+        'import { Component } from "react"',
+      ];
+
+      patterns.forEach((pattern) => {
+        expect(pattern).toMatch(/import.*from\s+['"]react['"]/);
+      });
+    });
+
+    it("should identify JSX syntax", () => {
+      const jsxPatterns = [
+        "<div>content</div>",
+        '<Component prop="value" />',
+        "<>{children}</>",
+      ];
+
+      jsxPatterns.forEach((pattern) => {
+        expect(pattern).toMatch(/<[\w>]/);
+      });
+    });
+
+    it("should detect client-side APIs", () => {
+      const clientAPIs = ["window", "document", "localStorage", "navigator"];
+      const code = "const width = window.innerWidth;";
+
+      const hasClientAPI = clientAPIs.some((api) => code.includes(api));
+      expect(hasClientAPI).toBe(true);
+    });
+  });
+});