Merge pull request #1458 from techisigu/feat/landing-1345-1348

feat(landing,seo): Step + FooterColumn rebuild, SEO metadata, responsive hardening (#1345 #1346 #1347 #1348)

Author: hman38705

docs/pr/techisigu-1345-1348.md

@@ -0,0 +1,89 @@
+# Landing page: Step, FooterColumn, SEO metadata, responsive
+
+Four landing-page issues.
+
+## What changed and why
+
+### #1345 - Step component + real "how it works" flow
+- `Step` takes an optional `href` and links the step title to the corresponding feature.
+  The **step number is not passed in** - `landing.css` already derives it with a CSS
+  `counter()` from the `<ol>` order, so it can't drift from the visual list.
+- The four steps now describe the real, shipped flow: connect a Stellar wallet -> browse
+  markets -> place a bet -> claim a payout (i18n `howItWorks.*`), each linking to `/markets`
+  or `/account/bets`.
+- Tests: title links to its feature; plain title without `href`; no hardcoded numbering in
+  the DOM; the `LandingPage` data-driven test asserts the `<ol>` and the four step links.
+
+### #1346 - FooterColumn + real footer navigation
+- `FooterColumn` gains a `children` slot (for embeds) and an `external` link flag
+  (`target="_blank"` + `rel="noopener noreferrer"`).
+- The footer columns were rewritten to routes that **exist**: Product (Markets `/markets`,
+  Statistics `/statistics`, Create a market `/markets/create`), Resources (Documentation +
+  GitHub, both external), and a "stay in the loop" column linking back to the hero signup
+  form (a second `<NewsletterSignup>` would duplicate its field ids and break a11y). The
+  dead `/docs`, `/github` (internal), `/discord`, `/privacy`, `/terms` links and the Legal
+  column were removed - there are no such pages.
+- `e2e/landing-links-responsive.spec.ts` asserts every internal footer link resolves
+  (`request.get(href)` < 400) - the CI link-check the AC asks for.
+- Tests: external vs internal link attributes; `children` render; the data-driven test now
+  asserts real routes and the absence of the removed links.
+
+### #1347 - SEO metadata + structured data
+- `app/layout.tsx`: site-wide defaults - `metadataBase`, a `title` template, Open Graph
+  `siteName`/`url`, Twitter `summary_large_image`.
+- `app/page.tsx` (kept server-side, still code-split via `next/dynamic` with `ssr: true` and
+  the existing loading fallback): route-level `title` / `description` / canonical / full
+  Open Graph + Twitter with an `/og-image.png`, plus an `Organization` + `WebSite` JSON-LD
+  `<script type="application/ld+json">` (a build-time constant, server-rendered so
+  link-unfurl crawlers see it).
+- Locale-specific metadata (#25) is out of scope here - the i18n layer only has an `en`
+  bundle today; `SITE_URL` reads `NEXT_PUBLIC_SITE_URL` with a default.
+- Tests: `landing-metadata.test.ts` asserts the exported `metadata` shape and the layout
+  defaults.
+
+### #1348 - responsive hardening
+- `overflow-wrap: anywhere` on hero/feature/step/footer text so a long word in a translated
+  locale wraps instead of widening the page.
+- Grid tracks changed to `minmax(min(100%, 230px), 1fr)` so a track can shrink below its
+  content's min-content size; `.footer-content { max-width: 100% }`.
+- A `@media (max-width: 360px)` block forces single-column grids and trims inline padding.
+- `e2e/landing-links-responsive.spec.ts` asserts `scrollWidth - clientWidth <= 1` at 320 /
+  768 / 1440.
+
+## How to test
+
+```
+cd frontend
+PUPPETEER_SKIP_DOWNLOAD=true npm ci --legacy-peer-deps --ignore-scripts
+./node_modules/.bin/jest src/components/__tests__/Step.test.tsx \
+  src/components/__tests__/FooterColumn.test.tsx \
+  src/components/__tests__/LandingPage.dataDriven.test.tsx \
+  src/app/__tests__/landing-metadata.test.tsx
+```
+
+- 37 tests pass across the touched suites; `page.test.tsx` (the dynamic-loading fallback
+  test) still passes - the code-split + loading spinner were preserved.
+- `tsc --noEmit`: no errors in the touched files over the repo's pre-existing count.
+- `e2e/landing-links-responsive.spec.ts` not run here (needs the browser install).
+- Pre-existing on `main`, unchanged by this branch (verified against a clean `upstream/main`
+  worktree - identical 30 failures): `Statistics.test.tsx`, `LandingPage.keyboard.test.tsx`,
+  `LandingPage.accessibility.test.tsx`, `useAsync.test.ts`, `useReferral.test.ts`.
+
+## Breaking changes
+
+None. New props and metadata only. Footer link targets changed (removed dead links).
+
+## Related issues
+
+Closes #1345
+Closes #1346
+Closes #1347
+Closes #1348
+
+## PR Checklist
+
+- [x] Branch is up to date with `main`
+- [x] Commit messages follow Conventional Commits
+- [x] Tests added or updated for the change
+- [x] Documentation updated if behaviour changed (n/a)
+- [x] No secrets or credentials committed

frontend/e2e/landing-links-responsive.spec.ts

@@ -0,0 +1,41 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * #1346 - every internal footer link resolves (no dead links to removed pages).
+ * #1348 - no horizontal scroll at 320 / 768 / 1440.
+ */
+
+test.describe('landing footer links resolve (#1346)', () => {
+  test('every internal footer link returns a non-error status', async ({ page, request }) => {
+    await page.goto('/');
+    const footer = page.getByRole('contentinfo');
+    const hrefs = await footer.locator('a[href^="/"]:not([href^="//"])').evaluateAll((els) =>
+      Array.from(new Set(els.map((el) => (el as HTMLAnchorElement).getAttribute('href') ?? ''))),
+    );
+
+    expect(hrefs.length).toBeGreaterThan(0);
+    for (const href of hrefs) {
+      if (href.startsWith('/#') || href === '/#') continue; // in-page anchor
+      const res = await request.get(href);
+      expect(res.status(), `${href} should resolve`).toBeLessThan(400);
+    }
+  });
+});
+
+test.describe('landing has no horizontal scroll (#1348)', () => {
+  for (const width of [320, 768, 1440]) {
+    test(`at ${width}px`, async ({ page }) => {
+      await page.setViewportSize({ width, height: 900 });
+      await page.goto('/');
+      await page.waitForLoadState('networkidle');
+      await page.evaluate(() => document.fonts.ready);
+
+      const overflow = await page.evaluate(() => {
+        const doc = document.documentElement;
+        return doc.scrollWidth - doc.clientWidth;
+      });
+      // allow a 1px rounding tolerance
+      expect(overflow, `viewport ${width}px must not scroll horizontally`).toBeLessThanOrEqual(1);
+    });
+  }
+});

frontend/src/app/__tests__/landing-metadata.test.tsx

@@ -0,0 +1,36 @@
+import { metadata } from '../page';
+import { metadata as rootMetadata } from '../layout';
+
+/**
+ * #1347 - the landing route emits SEO metadata (title/description/OG/Twitter) via
+ * the Next.js Metadata API, and the root layout carries the site-wide defaults.
+ * The JSON-LD is asserted structurally.
+ */
+
+describe('landing page metadata (#1347)', () => {
+  it('sets a descriptive title and description', () => {
+    expect(String(metadata.title)).toMatch(/PredictIQ/);
+    expect(metadata.description).toEqual(expect.stringContaining('prediction markets'));
+  });
+
+  it('has Open Graph and Twitter card metadata with an image', () => {
+    expect(metadata.openGraph?.type).toBe('website');
+    expect(metadata.openGraph?.images).toBeTruthy();
+    expect(metadata.twitter?.card).toBe('summary_large_image');
+  });
+
+  it('resolves relative asset URLs via metadataBase', () => {
+    expect(metadata.metadataBase).toBeInstanceOf(URL);
+    expect(metadata.alternates?.canonical).toBe('/');
+  });
+});
+
+describe('root layout metadata', () => {
+  it('provides site-wide defaults and a title template', () => {
+    expect(rootMetadata.metadataBase).toBeInstanceOf(URL);
+    const title = rootMetadata.title as { default: string; template: string };
+    expect(title.default).toMatch(/PredictIQ/);
+    expect(title.template).toContain('%s');
+    expect(rootMetadata.openGraph?.siteName).toBe('PredictIQ');
+  });
+});

frontend/src/app/layout.tsx

@@ -26,10 +26,27 @@ const body = Exo_2({
   display: 'swap',
 });
 
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://predictiq.app';
+
+// Site-wide metadata defaults. Per-route pages (e.g. app/page.tsx) override
+// title/description and add route-specific Open Graph data.
 export const metadata = {
-  title: 'PredictIQ — Decentralized Prediction Markets on Stellar',
+  metadataBase: new URL(SITE_URL),
+  title: {
+    default: 'PredictIQ — Decentralized Prediction Markets on Stellar',
+    template: '%s · PredictIQ',
+  },
   description:
     'Create, bet on, and resolve prediction markets with transparency, security, and fairness powered by the Stellar blockchain.',
+  applicationName: 'PredictIQ',
+  openGraph: {
+    type: 'website',
+    siteName: 'PredictIQ',
+    url: SITE_URL,
+  },
+  twitter: {
+    card: 'summary_large_image',
+  },
 };
 
 export default async function RootLayout({ children }: { children: ReactNode }) {

frontend/src/app/page.tsx

@@ -1,14 +1,68 @@
-'use client';
+import type { Metadata } from 'next';
 import dynamic from 'next/dynamic';
 import { LoadingSpinner } from '../components/LoadingSpinner';
 
-// Dynamic import with code splitting. With ssr: true, next/dynamic manages
-// its own loading boundary, so no outer <Suspense> is needed here.
-const LandingPage = dynamic(() => import('../components/LandingPage').then(mod => ({ default: mod.LandingPage })), {
-  loading: () => <LoadingSpinner aria-label="Loading page" />,
-  ssr: true,
-});
+// Landing-page SEO (#1347). `metadataBase` lets the relative OG/Twitter image
+// paths resolve to absolute URLs for link-unfurl crawlers.
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://predictiq.app';
+
+export const metadata: Metadata = {
+  metadataBase: new URL(SITE_URL),
+  title: 'PredictIQ — Decentralized Prediction Markets on Stellar',
+  description:
+    'Create, bet on, and resolve prediction markets on the Stellar blockchain. Multi-outcome markets, hybrid oracle + community resolution, and instant payouts.',
+  alternates: { canonical: '/' },
+  openGraph: {
+    type: 'website',
+    url: SITE_URL,
+    siteName: 'PredictIQ',
+    title: 'PredictIQ — Decentralized Prediction Markets on Stellar',
+    description: 'Create, bet on, and resolve prediction markets on the Stellar blockchain.',
+    images: [{ url: '/og-image.png', width: 1200, height: 630, alt: 'PredictIQ' }],
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: 'PredictIQ — Decentralized Prediction Markets on Stellar',
+    description: 'Create, bet on, and resolve prediction markets on the Stellar blockchain.',
+    images: ['/og-image.png'],
+  },
+};
+
+// Organization + WebSite JSON-LD. Build-time constant, no user input, no `<`.
+const structuredData = {
+  '@context': 'https://schema.org',
+  '@graph': [
+    {
+      '@type': 'Organization',
+      '@id': SITE_URL + '/#organization',
+      name: 'PredictIQ',
+      url: SITE_URL,
+      logo: SITE_URL + '/icons/logo.svg',
+      sameAs: ['https://github.com/solutions-plug/predictIQ'],
+    },
+    {
+      '@type': 'WebSite',
+      '@id': SITE_URL + '/#website',
+      url: SITE_URL,
+      name: 'PredictIQ',
+      description: 'Decentralized prediction markets on Stellar.',
+      publisher: { '@id': SITE_URL + '/#organization' },
+    },
+  ],
+};
+
+// Code-split, with a single accessible loading fallback. `ssr: true` keeps the
+// initial HTML server-rendered for crawlers.
+const LandingPage = dynamic(
+  () => import('../components/LandingPage').then((mod) => ({ default: mod.LandingPage })),
+  { loading: () => <LoadingSpinner aria-label="Loading page" />, ssr: true },
+);
 
 export default function Home() {
-  return <LandingPage />;
+  return (
+    <>
+      <script type="application/ld+json">{JSON.stringify(structuredData)}</script>
+      <LandingPage />
+    </>
+  );
 }

frontend/src/components/LandingPage.tsx

@@ -1,3 +1,5 @@
+'use client';
+
 import React from 'react';
 import { useI18n } from '../lib/hooks/useI18n';
 import { useDarkMode } from '../lib/hooks/useDarkMode';
@@ -24,22 +26,25 @@ export const LandingPage: React.FC<LandingPageProps> = ({ className }) => {
   ];
 
   const steps = [
-    { title: t('howItWorks.step1.title'), description: t('howItWorks.step1.description') },
-    { title: t('howItWorks.step2.title'), description: t('howItWorks.step2.description') },
-    { title: t('howItWorks.step3.title'), description: t('howItWorks.step3.description') },
-    { title: t('howItWorks.step4.title'), description: t('howItWorks.step4.description') },
+    { title: t('howItWorks.step1.title'), description: t('howItWorks.step1.description'), href: '/markets' },
+    { title: t('howItWorks.step2.title'), description: t('howItWorks.step2.description'), href: '/markets' },
+    { title: t('howItWorks.step3.title'), description: t('howItWorks.step3.description'), href: '/markets' },
+    { title: t('howItWorks.step4.title'), description: t('howItWorks.step4.description'), href: '/account/bets' },
   ];
 
+  // Product links point at routes that actually exist; Resources links are
+  // external. The Legal column was dropped - there are no privacy/terms pages
+  // yet, and #1346 requires no dead links.
   const footerColumns = [
     { heading: t('footer.title'), headingLevel: 'h2' as const, tagline: t('footer.tagline') },
-    { heading: t('footer.linksHeading'), links: [
-      { href: '/docs', label: t('footer.documentation') },
-      { href: '/github', label: t('footer.github') },
-      { href: '/discord', label: t('footer.discord') },
+    { heading: t('footer.productHeading'), links: [
+      { href: '/markets', label: t('footer.markets') },
+      { href: '/statistics', label: t('footer.statistics') },
+      { href: '/markets/create', label: t('footer.createMarket') },
     ] },
-    { heading: t('footer.legalHeading'), links: [
-      { href: '/privacy', label: t('footer.privacy') },
-      { href: '/terms', label: t('footer.terms') },
+    { heading: t('footer.resourcesHeading'), links: [
+      { href: 'https://github.com/solutions-plug/predictIQ#readme', label: t('footer.documentation'), external: true },
+      { href: 'https://github.com/solutions-plug/predictIQ', label: t('footer.github'), external: true },
     ] },
   ];
 
@@ -192,8 +197,15 @@ export const LandingPage: React.FC<LandingPageProps> = ({ className }) => {
           {footerColumns.map((column) => (
             <FooterColumn key={column.heading} {...column} />
           ))}
+          <FooterColumn heading={t('footer.newsletterHeading')}>
+            {/* The signup form itself lives in the hero (one set of field ids on
+                the page); the footer points people back to it. */}
+            <p>
+              <a href="#main-content">{t('hero.signupHeading')}</a>
+            </p>
+          </FooterColumn>
         </div>
-        
+
         <div className="footer-bottom">
           <p>{t('footer.copyright')}</p>
         </div>

frontend/src/components/__tests__/FooterColumn.test.tsx

@@ -56,4 +56,32 @@ describe('FooterColumn', () => {
     );
     expect(screen.getAllByRole('link', { name: 'Guide' })).toHaveLength(2);
   });
+
+  it('external links open in a new tab with a safe rel', () => {
+    render(
+      <FooterColumn
+        heading="Resources"
+        links={[{ href: 'https://github.com/x/y', label: 'GitHub', external: true }]}
+      />,
+    );
+    const link = screen.getByRole('link', { name: 'GitHub' });
+    expect(link).toHaveAttribute('target', '_blank');
+    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+  });
+
+  it('internal links get no target/rel', () => {
+    render(<FooterColumn heading="Product" links={[{ href: '/markets', label: 'Markets' }]} />);
+    const link = screen.getByRole('link', { name: 'Markets' });
+    expect(link).not.toHaveAttribute('target');
+    expect(link).not.toHaveAttribute('rel');
+  });
+
+  it('renders arbitrary children (e.g. a newsletter embed) under the heading', () => {
+    render(
+      <FooterColumn heading="Stay in the loop">
+        <button type="button">Subscribe</button>
+      </FooterColumn>,
+    );
+    expect(screen.getByRole('button', { name: 'Subscribe' })).toBeInTheDocument();
+  });
 });