fix(components): route internal html-page links through the SPA navigation handler (#2642)

Authored kind:'html' pages write app-root-relative hrefs
(apps/<app>/<object>, docs/<name>). The anchor passthrough rendered them
as raw <a> tags, so resolution depended entirely on document.baseURI:
correct when the host injected a matching <base> tag (/_console
deployments), but nested under the current page path — and 404ing — on
deployments without one (root-mounted consoles, vite dev).

The anchor renderer now resolves internal hrefs to app-root-absolute
paths and navigates via the url action's navigation handler (React
Router aware, so the router basename is applied in every deployment),
turning full page reloads into SPA navigations as a bonus. External
schemes, protocol-relative URLs, in-page fragments, target="_blank",
modified clicks, and no-ActionProvider contexts keep native browser
behavior; success toasts are suppressed for link follows.

Fixes #2638

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: baozhoutao

packages/components/src/__tests__/html-anchor-links.test.tsx

@@ -0,0 +1,149 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * kind:'html' anchor navigation (objectui#2638).
+ *
+ * Authored pages write app-root-relative hrefs (`apps/<app>/<object>`). A raw
+ * `<a>` resolves those against `document.baseURI`, which 404s on deployments
+ * without a host-injected `<base>` tag. The anchor renderer therefore routes
+ * internal links through the SPA's navigation handler (url action) and leaves
+ * external / fragment / new-tab / modified-click navigation to the browser.
+ */
+
+import { describe, it, expect, beforeAll, vi } from 'vitest';
+import { render, fireEvent, waitFor } from '@testing-library/react';
+import { SchemaRenderer, ActionProvider } from '@object-ui/react';
+import type { NavigationHandler } from '@object-ui/core';
+import type { SchemaNode } from '@object-ui/types';
+
+beforeAll(async () => {
+  await import('../renderers');
+}, 30000);
+
+function renderAnchor(
+  schema: Record<string, unknown>,
+  onNavigate?: NavigationHandler,
+) {
+  const tree = <SchemaRenderer schema={{ type: 'a', ...schema } as SchemaNode} />;
+  return render(
+    onNavigate ? (
+      <ActionProvider onNavigate={onNavigate}>{tree}</ActionProvider>
+    ) : (
+      tree
+    ),
+  );
+}
+
+describe('html anchor internal-link navigation', () => {
+  it('routes app-root-relative hrefs through the navigation handler', async () => {
+    const onNavigate = vi.fn();
+    const { getByText } = renderAnchor(
+      { href: 'apps/com.example.showcase/showcase_project', children: 'Projects' },
+      onNavigate,
+    );
+
+    const notPrevented = fireEvent.click(getByText('Projects'));
+    expect(notPrevented).toBe(false); // default was prevented — no raw browser navigation
+
+    await waitFor(() =>
+      expect(onNavigate).toHaveBeenCalledWith(
+        '/apps/com.example.showcase/showcase_project',
+        expect.objectContaining({ external: false, newTab: false }),
+      ),
+    );
+  });
+
+  it('keeps already-absolute paths as-is and preserves query + hash', async () => {
+    const onNavigate = vi.fn();
+    const { getByText } = renderAnchor(
+      { href: '/docs/showcase_tour_data?x=1#top', children: 'Tour' },
+      onNavigate,
+    );
+
+    fireEvent.click(getByText('Tour'));
+    await waitFor(() =>
+      expect(onNavigate).toHaveBeenCalledWith(
+        '/docs/showcase_tour_data?x=1#top',
+        expect.anything(),
+      ),
+    );
+  });
+
+  it('resolves ./ and ../ segments against the app root, not the current page', async () => {
+    const onNavigate = vi.fn();
+    const { getByText } = renderAnchor(
+      { href: '../docs/showcase_index', children: 'Manual' },
+      onNavigate,
+    );
+
+    fireEvent.click(getByText('Manual'));
+    await waitFor(() =>
+      expect(onNavigate).toHaveBeenCalledWith('/docs/showcase_index', expect.anything()),
+    );
+  });
+
+  it.each([
+    ['https://example.com/x', 'external https'],
+    ['mailto:hi@example.com', 'mailto'],
+    ['//example.com/x', 'protocol-relative'],
+    ['#section', 'in-page fragment'],
+  ])('leaves %s (%s) to the browser', (href) => {
+    const onNavigate = vi.fn();
+    const { getByText } = renderAnchor({ href, children: 'Link' }, onNavigate);
+
+    const el = getByText('Link');
+    // Prevent jsdom "navigation not implemented" noise without affecting the
+    // renderer's own handler (capture runs on the container, after bubbling).
+    el.ownerDocument.addEventListener('click', (e) => e.preventDefault());
+    fireEvent.click(el);
+
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it('does not intercept target="_blank" links', () => {
+    const onNavigate = vi.fn();
+    const { getByText } = renderAnchor(
+      { href: 'apps/x/y', target: '_blank', children: 'New tab' },
+      onNavigate,
+    );
+
+    const el = getByText('New tab');
+    el.ownerDocument.addEventListener('click', (e) => e.preventDefault());
+    fireEvent.click(el);
+
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it('does not intercept modified clicks (cmd/ctrl-click)', () => {
+    const onNavigate = vi.fn();
+    const { getByText } = renderAnchor(
+      { href: 'apps/x/y', children: 'Modified' },
+      onNavigate,
+    );
+
+    const el = getByText('Modified');
+    el.ownerDocument.addEventListener('click', (e) => e.preventDefault());
+    fireEvent.click(el, { metaKey: true });
+    fireEvent.click(el, { ctrlKey: true });
+
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it('renders untouched without an ActionProvider', () => {
+    const { getByText } = renderAnchor({
+      href: 'apps/x/y',
+      children: 'Bare',
+    });
+
+    const el = getByText('Bare') as HTMLAnchorElement;
+    expect(el.getAttribute('href')).toBe('apps/x/y');
+    el.ownerDocument.addEventListener('click', (e) => e.preventDefault());
+    expect(() => fireEvent.click(el)).not.toThrow();
+  });
+});

packages/components/src/renderers/basic/html-elements.tsx

@@ -21,9 +21,11 @@
  * neutralizes `javascript:`/`data:` URLs on `<a href>`.
  */
 
-import { ComponentRegistry } from '@object-ui/core';
+import { ComponentRegistry, type ActionResult } from '@object-ui/core';
+import { ActionCtxReact } from '@object-ui/react';
 import { renderChildren } from '../../lib/utils';
-import { createElement, forwardRef } from 'react';
+import { createElement, forwardRef, useContext } from 'react';
+import type { MouseEventHandler } from 'react';
 
 type AnyProps = { schema: any; className?: string; [key: string]: any };
 
@@ -70,6 +72,34 @@ function sanitizeHref(value: unknown): string | undefined {
   return v;
 }
 
+/**
+ * Resolve an authored href to an app-root-absolute path (`/apps/...`) when it
+ * is an internal SPA link, or null when the browser should handle it natively
+ * (scheme-qualified, protocol-relative, or in-page fragment links).
+ *
+ * Authored pages write app-root-relative hrefs (`apps/<app>/<object>`,
+ * `docs/<name>`). A raw `<a>` resolves those against `document.baseURI`,
+ * which only lands on the app root when the host injected a matching `<base>`
+ * tag — without one (root-mounted consoles, vite dev) the browser nests the
+ * path under the current page URL and 404s (objectui#2638). Routing internal
+ * links through the SPA's navigation handler makes them deployment-agnostic.
+ */
+function toInternalPath(href: unknown): string | null {
+  if (typeof href !== 'string' || href.trim().length === 0) return null;
+  const v = href.trim();
+  if (/^[a-z][a-z0-9+.-]*:/i.test(v)) return null; // http:, https:, mailto:, tel:, …
+  if (v.startsWith('//')) return null; // protocol-relative external
+  if (v.startsWith('#')) return null; // in-page fragment
+  try {
+    // Resolve ./ and ../ segments against a synthetic root so the result is
+    // app-root-absolute regardless of the current page path.
+    const u = new URL(v, 'https://internal.invalid/');
+    return u.pathname + u.search + u.hash;
+  } catch {
+    return null;
+  }
+}
+
 for (const tag of TAGS) {
   const isVoid = VOID_TAGS.has(tag);
   const Component = forwardRef<HTMLElement, AnyProps>(({ schema, className, ...props }, ref) => {
@@ -91,12 +121,41 @@ for (const tag of TAGS) {
     }
     if (tag === 'a' && 'href' in safe) safe.href = sanitizeHref(safe.href);
 
+    // Internal links navigate through the SPA router (via the url action's
+    // navigation handler) instead of a raw browser navigation, so they no
+    // longer depend on a host-injected <base> tag (objectui#2638). Modified
+    // clicks, new-tab targets, fragments, and external URLs keep native
+    // behavior; without an ActionProvider the anchor stays untouched.
+    const actionCtx = useContext(ActionCtxReact);
+    let onClick: MouseEventHandler | undefined;
+    if (tag === 'a' && actionCtx) {
+      const path = toInternalPath(safe.href);
+      const linkTarget = typeof safe.target === 'string' ? safe.target : '';
+      if (path && (!linkTarget || linkTarget === '_self')) {
+        onClick = (e) => {
+          if (e.defaultPrevented || e.button !== 0) return;
+          if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+          e.preventDefault();
+          // The url action keeps SPA-vs-full-page semantics (`/api/` paths
+          // escape the router); with no navigation handler wired it reports
+          // the redirect back for us to follow. Success toasts are suppressed
+          // — following a link is not a feedback-worthy "action".
+          void actionCtx.runner
+            .execute({ type: 'url', target: path, toast: { showOnSuccess: false } })
+            .then((r: ActionResult) => {
+              if (r?.success && r.redirect) window.location.assign(r.redirect);
+            });
+        };
+      }
+    }
+
     return createElement(
       tag,
       {
         ref,
         className,
         ...safe,
+        ...(onClick ? { onClick } : {}),
         'data-obj-id': dataObjId,
         'data-obj-type': dataObjType,
         style,