@wildo-ai/saas-website 1.1.1

package/src/components/low-level/WebsiteInternalLink.tsx

@@ -0,0 +1,193 @@
+import React, { type CSSProperties, type ReactNode } from 'react';
+
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import { useWebsiteRuntime } from '../../core/contexts/useWebsiteRuntime';
+import { buildLocalizedRoutePath } from '../../core/routing/internal-routing.utils';
+
+import { WebsiteLink } from './WebsiteLink';
+
+/**
+ * @wildo_source:part:start saas.website.primitives.internal-link facet:layer:components facet:family:website
+ *
+ * `WebsiteInternalLink` — L1 marketing-site link primitive for
+ * INTERNAL routes (any path served by the same Astro build).
+ *
+ * **The architectural problem this solves** (Phase 6 third audit fix
+ * H-β): the marketing site mounts the default locale at the
+ * un-prefixed path (`/`, `/pricing`) and every other locale under
+ * `/<locale>/…` (`/fr/`, `/fr/pricing`). A naive `<a href="/pricing">`
+ * authored in the chrome therefore works on EN pages and SILENTLY
+ * BREAKS on FR pages — the visitor falls out of their locale on every
+ * navigation. The dist-HTML audit confirmed the regression.
+ *
+ * **Why a dedicated primitive** (parallel to `WebsiteLink`, not a flag
+ * on it):
+ *   1. The two primitives have different authoring contracts — an
+ *      external link's `href` is a fully-qualified URL the author
+ *      already commits to; an internal link's `href` is a raw
+ *      `routePath` (`'/pricing'`) that the framework prefixes. Mixing
+ *      both shapes behind one `external?` prop forces the author to
+ *      think about a routing rule on every link they place; mixing
+ *      them behind one component invites the wrong shape on the wrong
+ *      branch (an internal href passed with `external` set, or vice
+ *      versa) without a type-system signal.
+ *   2. Internal links REQUIRE the runtime context; external links do
+ *      not. Forcing every external-link consumer to wrap in
+ *      `<WebsiteRuntimeContextProvider>` (or pay the
+ *      throw-on-missing-context cost) is wrong. Two primitives keep
+ *      the dependency surface honest.
+ *   3. The framework can layer additional internal-link concerns
+ *      later (active-route highlighting, prefetch directives,
+ *      router-aware navigation when the consumer overrides
+ *      `WebsiteLink`) without complicating the external-link
+ *      contract.
+ *
+ * **Why `routePath` is a string and NOT `WebsitePageRef`**:
+ *   - Many internal targets are NOT pages (anchor links to a section
+ *     within the current page: `'#features'`; same-locale subroutes
+ *     served by the consumer's Astro build but not registered as
+ *     `WebsitePageManifest` entries: `'/blog/launch'`). A `pageRef`
+ *     prop would force every link target to be a registered manifest,
+ *     which is too restrictive for chrome.
+ *   - The consumer's chrome typically links to a small fixed set of
+ *     `routePath` values they author once. The boilerplate cost of
+ *     looking up the matching manifest by ref is non-trivial; the
+ *     payoff (typo protection on `'/pricing'`) is small.
+ *   - We DO validate at runtime that `routePath` starts with `/` and
+ *     does not double-prefix (a path already starting with `/<locale>/`
+ *     would otherwise become `/fr/fr/pricing` on a FR page) — see the
+ *     in-render guard below.
+ *
+ * **Anchor-only links** (`href="#features"`) are passed through
+ * verbatim: they navigate within the current page, no locale prefix
+ * applies. Same for `mailto:` / `tel:` — recognized by colon presence
+ * and forwarded as-is.
+ *
+ * **Boundary**: this component MUST stay in the React-island bundle
+ * tier (`components/low-level/`). It depends on `useWebsiteRuntime`
+ * (which throws when called outside a `<WebsiteRuntimeContextProvider>`)
+ * — the throw is the contract that prevents the chrome from being
+ * rendered outside a bridged page accidentally.
+ *
+ * @example
+ *   ```tsx
+ *   // In HeaderComponent.tsx — the framework computes the right URL
+ *   // automatically (`/pricing` on EN pages, `/fr/pricing` on FR
+ *   // pages):
+ *   <WebsiteInternalLink routePath="/pricing">
+ *     <WebsiteText variant={WebsiteTextVariant.BODY}>Pricing</WebsiteText>
+ *   </WebsiteInternalLink>
+ *   ```
+ */
+export interface WebsiteInternalLinkProps {
+  /**
+   * The locale-NEUTRAL route path. Must match a value the consumer's
+   * Astro build serves (typically a `WebsitePageManifest.routePath`,
+   * but anchor-only `#section` and same-page subroutes are also
+   * accepted). MUST start with `/` (or `#` for in-page anchors, or
+   * include `:` for `mailto:` / `tel:`).
+   */
+  routePath: string;
+  className?: string;
+  style?: CSSProperties;
+  id?: string;
+  /**
+   * Optional `aria-label` for icon-only links (where the link text
+   * is a glyph or sr-only).
+   */
+  ariaLabel?: string;
+  children: ReactNode;
+}
+
+function isAnchorOrUrlScheme(routePath: string): boolean {
+  return routePath.startsWith('#') || routePath.includes(':');
+}
+
+/**
+ * Pre-computed set of every known locale code (`'en'`, `'fr'`,
+ * `'en-GB'`, …). Built ONCE at module load from `AvailableLanguage`
+ * so the per-render double-prefix guard below is an O(1) Set.has
+ * check rather than an Object.values() walk on every link render.
+ */
+const ALL_LOCALE_CODES: ReadonlySet<string> = new Set(
+  Object.values(AvailableLanguage) as readonly string[],
+);
+
+/**
+ * Defensive in-render guard: rejects route paths whose first segment
+ * matches a known locale code. The marketing-site convention is that
+ * the consumer authors locale-NEUTRAL paths and the framework
+ * prefixes them; an already-prefixed path would either render as a
+ * `/<locale>/<locale>/pricing` double-prefix on non-default-locale
+ * pages or silently work on default-locale pages and break on other
+ * locales — both are silent regressions. Throwing here makes the
+ * misuse loud at first render.
+ *
+ * Returns the offending locale segment if the path is misused, or
+ * `null` if the path is well-formed.
+ */
+function detectAccidentalLocalePrefix(routePath: string): string | null {
+  const slashIdx = routePath.indexOf('/', 1);
+  const firstSegment =
+    slashIdx === -1 ? routePath.slice(1) : routePath.slice(1, slashIdx);
+  if (firstSegment === '') return null;
+  return ALL_LOCALE_CODES.has(firstSegment) ? firstSegment : null;
+}
+
+export function WebsiteInternalLink({
+  routePath,
+  className,
+  style,
+  id,
+  ariaLabel,
+  children,
+}: WebsiteInternalLinkProps): ReactNode {
+  const runtime = useWebsiteRuntime();
+
+  let href: string;
+  if (isAnchorOrUrlScheme(routePath)) {
+    href = routePath;
+  } else {
+    if (!routePath.startsWith('/')) {
+      throw new Error(
+        `[WebsiteInternalLink] routePath="${routePath}" must start with "/" ` +
+          `(framework-relative path), "#" (in-page anchor) or include ":" ` +
+          `(URL scheme like mailto:/tel:). Use <WebsiteLink href={...} external={true}> ` +
+          `for fully-qualified external URLs.`,
+      );
+    }
+    const accidentalPrefix = detectAccidentalLocalePrefix(routePath);
+    if (accidentalPrefix !== null) {
+      throw new Error(
+        `[WebsiteInternalLink] routePath="${routePath}" begins with the ` +
+          `locale segment "/${accidentalPrefix}" — the framework prefixes ` +
+          `the active locale automatically, so passing a pre-prefixed path ` +
+          `would render as "/${accidentalPrefix}${routePath}" on non-default ` +
+          `locale pages (double-prefix) or silently break locale routing on ` +
+          `default-locale pages. Pass the locale-NEUTRAL path instead ` +
+          `(eg. "/pricing", not "/${accidentalPrefix}/pricing").`,
+      );
+    }
+    href = buildLocalizedRoutePath({
+      locale: runtime.locale,
+      defaultLocale: runtime.defaultLocale,
+      routePath,
+    });
+  }
+
+  return (
+    <WebsiteLink
+      href={href}
+      external={false}
+      className={className}
+      style={style}
+      id={id}
+      ariaLabel={ariaLabel}
+    >
+      {children}
+    </WebsiteLink>
+  );
+}
+WebsiteInternalLink.displayName = 'WebsiteInternalLink';
+/** @wildo_source:part:end saas.website.primitives.internal-link */

package/src/components/low-level/WebsiteLink.tsx

@@ -0,0 +1,71 @@
+import React, { type CSSProperties, type ReactNode } from 'react';
+
+/**
+ * @wildo_source:part:start saas.website.primitives.link facet:layer:components facet:family:website
+ *
+ * `WebsiteLink` — L1 marketing-site link primitive.
+ *
+ * **Status (Phase 2 / D18)**: minimal placeholder. Renders a plain
+ * `<a>` with `data-website-primitive="link"` and forwards href +
+ * standard link attributes. Consumers override at the L1 boundary
+ * to wire in their preferred client-side router (Astro `<a>` does
+ * full navigation by default; consumers using View Transitions or
+ * a router-aware link wrap that here).
+ *
+ * **Why `external` is an explicit prop** (vs. inferred from the
+ * href shape): inference is unreliable (relative paths from a CMS
+ * may resolve to external; protocol-relative URLs are external but
+ * don't start with `http`). An explicit prop forces the section
+ * author to decide. When `external === true`, the primitive applies
+ * `rel="noopener noreferrer"` and `target="_blank"` automatically
+ * — security best-practice baked in.
+ *
+ * **Why no `variant`**: link visual variants (button-like CTA,
+ * inline-text link, icon-only) are too tightly coupled to the
+ * design system to be useful as a placeholder vocabulary. The
+ * override implementation defines its own variants; the
+ * placeholder ships only the security-correct attribute defaults.
+ */
+export interface WebsiteLinkProps {
+  href: string;
+  /**
+   * Marks the link as external. Adds `target="_blank"` and
+   * `rel="noopener noreferrer"`. Defaults to `false`.
+   */
+  external?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  id?: string;
+  /**
+   * Optional `aria-label` for icon-only links (where the link text
+   * is a glyph or sr-only).
+   */
+  ariaLabel?: string;
+  children: ReactNode;
+}
+
+export function WebsiteLink({
+  href,
+  external = false,
+  className,
+  style,
+  id,
+  ariaLabel,
+  children,
+}: WebsiteLinkProps): ReactNode {
+  const attrs: Record<string, unknown> = {
+    'data-website-primitive': 'link',
+    href,
+  };
+  if (external) {
+    attrs.target = '_blank';
+    attrs.rel = 'noopener noreferrer';
+  }
+  if (className !== undefined) attrs.className = className;
+  if (style !== undefined) attrs.style = style;
+  if (id !== undefined) attrs.id = id;
+  if (ariaLabel !== undefined) attrs['aria-label'] = ariaLabel;
+  return <a {...attrs}>{children}</a>;
+}
+WebsiteLink.displayName = 'WebsiteLink';
+/** @wildo_source:part:end saas.website.primitives.link */

package/src/components/low-level/WebsiteText.tsx

@@ -0,0 +1,75 @@
+import React, { type CSSProperties, type ReactNode } from 'react';
+
+/**
+ * @wildo_source:part:start saas.website.primitives.text facet:layer:components facet:family:website
+ *
+ * `WebsiteText` — L1 marketing-site body-text primitive.
+ *
+ * Same Phase 2 / D18 status as `WebsiteHeading` — minimal,
+ * self-contained placeholder; consumers override at the L1 boundary
+ * via barrel re-export. The skill-driven authoring path will require
+ * an override before shipping a public marketing site.
+ *
+ * **Why `variant` (lead vs. body vs. caption) is shipped here**:
+ * marketing-site body copy has a distinct typographic scale from
+ * in-app body copy (looser line-height for scannability, larger
+ * `lead` paragraphs under headlines, smaller `caption` under
+ * pricing tier features). The variant slot exists at the
+ * placeholder level so section authors call the same prop the
+ * override implementation honors.
+ *
+ * **Why default tag is `<p>`**: the overwhelming majority of
+ * marketing copy is a paragraph. The `as` prop allows escaping to
+ * `<span>` (inline copy inside a heading), `<strong>` (emphatic
+ * inline), or `<em>` (italicized inline) without compromising the
+ * paragraph default.
+ */
+export enum WebsiteTextVariant {
+  /**
+   * Lead paragraph immediately under a section headline (slightly
+   * larger / less dense than body).
+   */
+  LEAD = 'lead',
+  /**
+   * Standard body copy. The default.
+   */
+  BODY = 'body',
+  /**
+   * Small / supporting copy (footnotes, captions, fine print).
+   */
+  CAPTION = 'caption',
+}
+
+export type WebsiteTextElement = 'p' | 'span' | 'strong' | 'em' | 'div';
+
+export interface WebsiteTextProps {
+  /** Visual variant. Defaults to `BODY`. */
+  variant?: WebsiteTextVariant;
+  /** Rendered tag. Defaults to `'p'`. */
+  as?: WebsiteTextElement;
+  className?: string;
+  style?: CSSProperties;
+  id?: string;
+  children: ReactNode;
+}
+
+export function WebsiteText({
+  variant = WebsiteTextVariant.BODY,
+  as = 'p',
+  className,
+  style,
+  id,
+  children,
+}: WebsiteTextProps): ReactNode {
+  const Tag = as;
+  const attrs: Record<string, unknown> = {
+    'data-website-primitive': 'text',
+    'data-website-text-variant': variant,
+  };
+  if (className !== undefined) attrs.className = className;
+  if (style !== undefined) attrs.style = style;
+  if (id !== undefined) attrs.id = id;
+  return <Tag {...attrs}>{children}</Tag>;
+}
+WebsiteText.displayName = 'WebsiteText';
+/** @wildo_source:part:end saas.website.primitives.text */

package/src/components/low-level/__tests__/WebsiteInternalButton.test.tsx

@@ -0,0 +1,169 @@
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import { WebsiteRuntimeContextProvider } from '../../../core/contexts/WebsiteRuntimeContext';
+import { WebsiteLabelKeySchema } from '../../../schemas/label-keys/website-label-key.schemas';
+
+import { WebsiteInternalButton } from '../WebsiteInternalButton';
+import { WebsiteButtonSize, WebsiteButtonVariant } from '../WebsiteButton';
+
+const SKIP_KEY = WebsiteLabelKeySchema.parse('website.chrome.layout.skip-to-main-content');
+
+function renderWithRuntime(
+  ui: React.ReactNode,
+  opts: { locale: AvailableLanguage; defaultLocale: AvailableLanguage },
+): ReturnType<typeof render> {
+  return render(
+    <WebsiteRuntimeContextProvider
+      value={{
+        locale: opts.locale,
+        defaultLocale: opts.defaultLocale,
+        labelPack: {},
+        designTokens: {
+          colors: {
+            background: '#fff',
+            foreground: '#111',
+            primary: '#0070f3',
+            primaryForeground: '#fff',
+            accent: '#ff5e5b',
+            accentForeground: '#fff',
+            surface: '#fafafa',
+            surfaceForeground: '#111',
+            border: '#e5e5e5',
+            muted: '#f5f5f5',
+            mutedForeground: '#737373',
+          },
+          radii: {
+            none: '0',
+            sm: '0.125rem',
+            md: '0.375rem',
+            lg: '0.75rem',
+            xl: '1.5rem',
+            full: '9999px',
+          },
+        },
+        navigation: {
+          headerComponent: () => null,
+          footerComponent: () => null,
+        },
+        skipToMainContentLabelKey: SKIP_KEY,
+      }}
+    >
+      {ui}
+    </WebsiteRuntimeContextProvider>,
+  );
+}
+
+describe('WebsiteInternalButton', () => {
+  describe('default-locale page (un-prefixed routing)', () => {
+    it('renders the routePath verbatim when locale === defaultLocale', () => {
+      const { container } = renderWithRuntime(
+        <WebsiteInternalButton routePath="/contact">Contact</WebsiteInternalButton>,
+        { locale: AvailableLanguage.EN, defaultLocale: AvailableLanguage.EN },
+      );
+      expect(container.querySelector('a')?.getAttribute('href')).toBe('/contact');
+    });
+  });
+
+  describe('non-default-locale page (prefixed routing)', () => {
+    it('prefixes /<locale> on FR pages', () => {
+      const { container } = renderWithRuntime(
+        <WebsiteInternalButton routePath="/contact">Contactez-nous</WebsiteInternalButton>,
+        { locale: AvailableLanguage.FR, defaultLocale: AvailableLanguage.EN },
+      );
+      expect(container.querySelector('a')?.getAttribute('href')).toBe('/fr/contact');
+    });
+
+    it('collapses root to /<locale> (NOT /<locale>/)', () => {
+      const { container } = renderWithRuntime(
+        <WebsiteInternalButton routePath="/">Home</WebsiteInternalButton>,
+        { locale: AvailableLanguage.FR, defaultLocale: AvailableLanguage.EN },
+      );
+      expect(container.querySelector('a')?.getAttribute('href')).toBe('/fr');
+    });
+  });
+
+  describe('misuse guards', () => {
+    it('throws when routePath does not start with /', () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      expect(() =>
+        renderWithRuntime(
+          <WebsiteInternalButton routePath="contact">Contact</WebsiteInternalButton>,
+          { locale: AvailableLanguage.EN, defaultLocale: AvailableLanguage.EN },
+        ),
+      ).toThrow(/must start with/i);
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('rejects anchor-only routePaths (use WebsiteButton instead)', () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      expect(() =>
+        renderWithRuntime(
+          <WebsiteInternalButton routePath="#features">Features</WebsiteInternalButton>,
+          { locale: AvailableLanguage.EN, defaultLocale: AvailableLanguage.EN },
+        ),
+      ).toThrow(/must start with "\/"/i);
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('rejects URL schemes (mailto: / tel:)', () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      expect(() =>
+        renderWithRuntime(
+          <WebsiteInternalButton routePath="mailto:hi@wildo.ai">Email</WebsiteInternalButton>,
+          { locale: AvailableLanguage.EN, defaultLocale: AvailableLanguage.EN },
+        ),
+      ).toThrow(/must start with "\/"/i);
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('throws when used outside <WebsiteRuntimeContextProvider>', () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      expect(() =>
+        render(<WebsiteInternalButton routePath="/contact">Contact</WebsiteInternalButton>),
+      ).toThrow(/WebsiteRuntimeContextProvider/);
+      consoleErrorSpy.mockRestore();
+    });
+  });
+
+  describe('attribute / variant forwarding', () => {
+    it('forwards variant + size to the underlying WebsiteButton', () => {
+      const { container } = renderWithRuntime(
+        <WebsiteInternalButton
+          routePath="/contact"
+          variant={WebsiteButtonVariant.SECONDARY}
+          size={WebsiteButtonSize.LG}
+        >
+          Contact
+        </WebsiteInternalButton>,
+        { locale: AvailableLanguage.EN, defaultLocale: AvailableLanguage.EN },
+      );
+      const span = container.querySelector('[data-website-primitive="button"]');
+      expect(span?.getAttribute('data-website-button-variant')).toBe('secondary');
+      expect(span?.getAttribute('data-website-button-size')).toBe('lg');
+      expect(span?.getAttribute('data-website-button-mode')).toBe('link');
+    });
+
+    it('forwards className, id, ariaLabel to the rendered anchor', () => {
+      const { container } = renderWithRuntime(
+        <WebsiteInternalButton
+          routePath="/contact"
+          className="wt-cta"
+          id="hero-cta"
+          ariaLabel="Open contact page"
+        >
+          Contact
+        </WebsiteInternalButton>,
+        { locale: AvailableLanguage.EN, defaultLocale: AvailableLanguage.EN },
+      );
+      const a = container.querySelector('a');
+      expect(a?.getAttribute('class')).toBe('wt-cta');
+      expect(a?.getAttribute('id')).toBe('hero-cta');
+      expect(a?.getAttribute('aria-label')).toBe('Open contact page');
+    });
+  });
+});