@eifi1/ui-kit 0.30.0 → 0.31.1

package/src/landing/landing-sections.tsx

@@ -0,0 +1,337 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+
+import { cn } from "../lib/cn";
+import { Chip } from "../components/chip";
+import { LegalFooter } from "../components/legal";
+import type { LegalFooterProps } from "../components/legal";
+import { LandingActions } from "./landing-actions";
+import type { LandingActionsProps } from "./landing-actions";
+import { useLandingLabels } from "./landing-labels";
+import type { LandingLabels } from "./landing-labels";
+
+/**
+ * The sections of the public landing page (docs/landing-demo-harmonization.md §4.1),
+ * top to bottom: `Hero`, `FeatureRows` of `FeatureRow`, `TrustStrip`, `CtaBand`,
+ * `PublicFooter` — keksdose's landing-page.tsx, taken apart.
+ *
+ * The kit draws the frame; every word of marketing copy is the app's. Colours are the
+ * kit's tokens (`--brand`, `--text-*`, `--bg-surface`, `--border`), so keksdose's ten
+ * hard-coded teal sites follow the palette now (§2.11).
+ *
+ * **Visuals are decorative** (§4.1): the `visual` slots are `aria-hidden` and `inert` —
+ * mock UI drawn with kit tokens, never screenshots with real data, and never anything a
+ * keyboard could land on. The copy beside each one carries the information. A mock's
+ * amounts use the demo data's currency, so the landing shows what "Try the demo" opens.
+ */
+
+type HeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+/** The decorative slot: hidden from assistive tech and out of the tab order. */
+function Visual({ children, className }: { children: ReactNode; className?: string }) {
+  return (
+    <div aria-hidden inert data-slot="landing-visual" className={cn("mx-auto w-full select-none", className)}>
+      {children}
+    </div>
+  );
+}
+
+/** The action pair's props, as `Hero` and `CtaBand` pass them on. */
+type ActionProps = Pick<LandingActionsProps, "session" | "access" | "demoHref" | "openAppHref">;
+
+/* ── Hero ────────────────────────────────────────────────────────────────── */
+
+export interface HeroProps extends Omit<ComponentPropsWithoutRef<"section">, "title" | "children">, ActionProps {
+  /** The page's `h1`: what the app does, in a line. */
+  title: ReactNode;
+  /** Under it: for whom, and why. */
+  subtitle?: ReactNode;
+  /** The kit's "Beta" chip above the title. */
+  beta?: boolean;
+  /** A badge of the app's own in that place; wins over `beta`. */
+  badge?: ReactNode;
+  /** Under the actions, quiet: "Free while in beta. Your data stays yours." */
+  trust?: ReactNode;
+  /** The product glimpse beside the copy (below it on a phone). Decorative. */
+  visual?: ReactNode;
+  /** Replaces the action pair ({@link LandingActions}). */
+  actions?: ReactNode;
+  /** Default `h1`; lower where the hero is embedded in another page. */
+  headingAs?: HeadingLevel;
+  labels?: Partial<LandingLabels>;
+}
+
+/**
+ * The top of the landing (§4.1.2): an optional "Beta" badge, the `h1`, a subtitle, the
+ * action pair for the visitor's state ({@link LandingActions}: "Request access" and "Try
+ * the demo", or "Open app" for a session), a trust line, and a visual. Copy left and
+ * visual right from `lg` up, stacked below.
+ */
+export function Hero({
+  title,
+  subtitle,
+  beta = false,
+  badge,
+  trust,
+  visual,
+  actions,
+  headingAs: Heading = "h1",
+  session,
+  access,
+  demoHref,
+  openAppHref,
+  labels: labelsProp,
+  className,
+  ...rest
+}: HeroProps) {
+  const labels = useLandingLabels(labelsProp);
+  const shownBadge =
+    badge ??
+    (beta ? (
+      // keksdose's chip, padded out to the hero's scale.
+      <Chip size="sm" tone="warning" className="px-3 py-1 font-medium">
+        {labels.beta}
+      </Chip>
+    ) : null);
+  return (
+    <section
+      {...rest}
+      data-slot="landing-hero"
+      className={cn(
+        "mx-auto grid max-w-6xl items-center gap-12 px-4 py-16 sm:py-24",
+        visual != null && "lg:grid-cols-2",
+        className,
+      )}
+    >
+      <div>
+        {shownBadge != null && <div className="mb-4">{shownBadge}</div>}
+        <Heading className="text-4xl font-bold tracking-tight text-balance text-[var(--text-primary)] sm:text-5xl">
+          {title}
+        </Heading>
+        {subtitle != null && <p className="mt-4 max-w-xl text-lg text-[var(--text-secondary)]">{subtitle}</p>}
+        <div className="mt-8">
+          {actions ?? (
+            <LandingActions
+              session={session}
+              access={access}
+              demoHref={demoHref}
+              openAppHref={openAppHref}
+              labels={labelsProp}
+            />
+          )}
+        </div>
+        {trust != null && <p className="mt-4 text-sm text-[var(--text-muted)]">{trust}</p>}
+      </div>
+      {visual != null && <Visual className="max-w-sm">{visual}</Visual>}
+    </section>
+  );
+}
+
+/* ── Feature rows ────────────────────────────────────────────────────────── */
+
+export type FeatureRowsProps = ComponentPropsWithoutRef<"section">;
+
+/**
+ * The band that holds the feature rows (§4.1.3): two to four {@link FeatureRow}s on the
+ * surface colour, between hairlines. The rows alternate sides by themselves — the copy
+ * of every second row moves to the end from `lg` up — so the app lists them in order
+ * and nothing else.
+ */
+export function FeatureRows({ className, children, ...rest }: FeatureRowsProps) {
+  return (
+    <section
+      {...rest}
+      data-slot="landing-feature-rows"
+      className={cn("border-t border-[var(--border)] bg-[var(--bg-surface)]", className)}
+    >
+      <div className="mx-auto max-w-6xl px-4 py-8 sm:py-12">{children}</div>
+    </section>
+  );
+}
+
+export interface FeatureRowProps extends Omit<ComponentPropsWithoutRef<"div">, "title" | "children"> {
+  /** A lucide icon (or any SVG) before the eyebrow. Decorative. */
+  icon?: ReactNode;
+  /** The small uppercase line above the heading: "Capture", "Plan". */
+  eyebrow?: ReactNode;
+  /** The row's `h2`. */
+  title: ReactNode;
+  description?: ReactNode;
+  /** Up to three short points; the first three are shown. */
+  bullets?: readonly ReactNode[];
+  /** The mock beside the copy. Decorative. */
+  visual?: ReactNode;
+  /** Default `h2`. */
+  headingAs?: HeadingLevel;
+}
+
+/**
+ * One job of the app (§4.1.3), keksdose's "capture → budget → understand": an icon
+ * eyebrow, the `h2`, a description, up to three bullets, and a visual on the other side.
+ * Inside {@link FeatureRows} every second row puts its copy at the end (`group-even`),
+ * which is keksdose's alternation without an index to pass.
+ */
+export function FeatureRow({
+  icon,
+  eyebrow,
+  title,
+  description,
+  bullets,
+  visual,
+  headingAs: Heading = "h2",
+  className,
+  ...rest
+}: FeatureRowProps) {
+  const shown = bullets?.slice(0, 3) ?? [];
+  return (
+    <div
+      {...rest}
+      data-slot="landing-feature-row"
+      className={cn("group/feature grid items-center gap-8 py-10", visual != null && "lg:grid-cols-2 lg:gap-16", className)}
+    >
+      <div className="lg:group-even/feature:order-last">
+        {(icon != null || eyebrow != null) && (
+          <p className="flex items-center gap-2 text-xs font-semibold uppercase tracking-wider text-[var(--brand)]">
+            {icon != null && (
+              <span aria-hidden className="flex shrink-0 [&_svg]:size-4">
+                {icon}
+              </span>
+            )}
+            {eyebrow}
+          </p>
+        )}
+        <Heading className="mt-2 text-2xl font-semibold tracking-tight text-balance text-[var(--text-primary)] sm:text-3xl">
+          {title}
+        </Heading>
+        {description != null && <p className="mt-3 max-w-xl text-[var(--text-secondary)]">{description}</p>}
+        {shown.length > 0 && (
+          <ul className="mt-4 space-y-2">
+            {shown.map((bullet, i) => (
+              <li key={i} className="flex gap-2.5 text-sm text-[var(--text-secondary)]">
+                <span aria-hidden className="mt-1.5 size-1.5 shrink-0 rounded-full bg-[var(--brand)]" />
+                <span className="min-w-0">{bullet}</span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+      {visual != null && <Visual className="max-w-md">{visual}</Visual>}
+    </div>
+  );
+}
+
+/* ── Trust strip ─────────────────────────────────────────────────────────── */
+
+export interface TrustItem {
+  /** A lucide icon. Decorative. */
+  icon?: ReactNode;
+  /** The item's `h3`: "Hosted in Switzerland". */
+  title: ReactNode;
+  /** One sentence. */
+  description: ReactNode;
+}
+
+export interface TrustStripProps extends Omit<ComponentPropsWithoutRef<"section">, "children"> {
+  /** Three or four (§4.1.4): hosting, security, data ownership, sharing. */
+  items: readonly TrustItem[];
+  /** The items' heading level. Default `h3`. */
+  headingAs?: HeadingLevel;
+}
+
+/**
+ * Quiet, start-aligned facts after the feature rows (§4.1.4) — an icon, an `h3` and one
+ * sentence each, on one row from `lg` up (three or four columns), two on a tablet, one
+ * on a phone. No marketing volume: keksdose's "trust strip".
+ */
+export function TrustStrip({ items, headingAs: Heading = "h3", className, ...rest }: TrustStripProps) {
+  return (
+    <section {...rest} data-slot="landing-trust" className={cn("mx-auto max-w-6xl px-4 py-12 sm:py-16", className)}>
+      <ul className={cn("grid gap-8 sm:grid-cols-2", items.length === 3 ? "lg:grid-cols-3" : "lg:grid-cols-4")}>
+        {items.map((item, i) => (
+          <li key={i}>
+            {item.icon != null && (
+              <span aria-hidden className="flex text-[var(--brand)] [&_svg]:size-5">
+                {item.icon}
+              </span>
+            )}
+            <Heading className="mt-2 text-sm font-semibold text-[var(--text-primary)]">{item.title}</Heading>
+            <p className="mt-1 text-sm text-[var(--text-secondary)]">{item.description}</p>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+/* ── CTA band ────────────────────────────────────────────────────────────── */
+
+export interface CtaBandProps extends Omit<ComponentPropsWithoutRef<"section">, "title" | "children">, ActionProps {
+  /** The band's `h2`: the last ask. */
+  title: ReactNode;
+  subtitle?: ReactNode;
+  /** Replaces the action pair ({@link LandingActions}). */
+  actions?: ReactNode;
+  /** Default `h2`. */
+  headingAs?: HeadingLevel;
+  labels?: Partial<LandingLabels>;
+}
+
+/**
+ * The closing band before the footer (§4.1.5): a centred `h2`, a subtitle, and the same
+ * action pair as the hero.
+ */
+export function CtaBand({
+  title,
+  subtitle,
+  actions,
+  headingAs: Heading = "h2",
+  session,
+  access,
+  demoHref,
+  openAppHref,
+  labels,
+  className,
+  ...rest
+}: CtaBandProps) {
+  return (
+    <section
+      {...rest}
+      data-slot="landing-cta"
+      className={cn("border-t border-[var(--border)] bg-[var(--bg-surface)]", className)}
+    >
+      <div className="mx-auto max-w-5xl px-4 py-16 text-center">
+        <Heading className="text-2xl font-semibold tracking-tight text-balance text-[var(--text-primary)] sm:text-3xl">
+          {title}
+        </Heading>
+        {subtitle != null && <p className="mx-auto mt-3 max-w-xl text-[var(--text-secondary)]">{subtitle}</p>}
+        <div className="mt-8">
+          {actions ?? (
+            <LandingActions
+              session={session}
+              access={access}
+              demoHref={demoHref}
+              openAppHref={openAppHref}
+              align="center"
+              labels={labels}
+            />
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+/* ── Footer ──────────────────────────────────────────────────────────────── */
+
+export interface PublicFooterProps extends Omit<LegalFooterProps, "children"> {
+  /** The app's line under the legal links: "Self-hosted household budgeting." */
+  tagline?: ReactNode;
+}
+
+/**
+ * The public pages' footer (§4.1.6): the kit's {@link LegalFooter} — the three legal
+ * links — with the app's tagline under them. keksdose's `SiteFooter`, which was already
+ * this.
+ */
+export function PublicFooter({ tagline, ...rest }: PublicFooterProps) {
+  return <LegalFooter {...rest}>{tagline}</LegalFooter>;
+}

package/src/landing/page-seo.ts

@@ -0,0 +1,251 @@
+import { useEffect } from "react";
+
+/**
+ * Search-engine helpers for the public landing page (docs/landing-demo-harmonization.md
+ * §4.3): the hook that declares a page's canonical URL, title, description and JSON-LD,
+ * and the two pure helpers each app's SEO test is built from.
+ */
+
+/**
+ * Declares the current page's canonical URL — and optionally its title and meta
+ * description — while the calling component is mounted (feedback #129).
+ *
+ * Client-side because there is nowhere else to put it: the SPA is served by
+ * Caddy's `try_files … /index.html`, so every route shares one static head.
+ * Googlebot renders JS and reads the canonical from the RENDERED DOM, which is
+ * what makes this work; non-rendering scrapers (WhatsApp, Slack) only ever see
+ * index.html's static tags, which is why those stay in place as the fallback.
+ *
+ * The href is resolved against `window.location.origin` rather than hardcoded, so
+ * a preview deployment or the VPS host stays self-referential instead of pointing
+ * every copy of the app at production.
+ *
+ * The cleanup matters for the same reason as in {@link useNoIndex}: an SPA
+ * navigation from the landing page into the app must not leave the landing's
+ * canonical (or title) behind on an app page.
+ *
+ * 0.31 (§4.3): keksdose's `usePageSeo` (shared/hooks/use-page-seo.ts), verbatim. The
+ * landing calls it with `canonicalPath: "/"` on both `/` and `/welcome`, so the two URLs
+ * of one page are one result; there are no per-language URLs and no hreflang.
+ */
+export function usePageSeo({
+  canonicalPath,
+  title,
+  description,
+  jsonLd,
+}: {
+  canonicalPath: string;
+  title?: string;
+  description?: string;
+  /** Structured data for this page, as the object (not a string). Injected as an
+   *  `application/ld+json` DATA BLOCK — a script element the browser never executes,
+   *  which is also why it can be added here rather than in `index.html`: the CSP
+   *  carries a HASH of the one inline script that file is allowed to have, and
+   *  `csp-inline-script.test.ts` fails the build on a second one (live #250). */
+  jsonLd?: Record<string, unknown>;
+}): void {
+  useEffect(() => {
+    const link = document.createElement("link");
+    link.rel = "canonical";
+    link.href = new URL(canonicalPath, window.location.origin).toString();
+    document.head.appendChild(link);
+
+    const previousTitle = document.title;
+    if (title) document.title = title;
+
+    // The description tag ships in index.html, so upsert rather than append —
+    // two `meta[name=description]` tags would be a coin flip for the scraper.
+    const meta = description
+      ? document.head.querySelector<HTMLMetaElement>('meta[name="description"]')
+      : null;
+    const previousDescription = meta?.content;
+    if (meta && description) meta.content = description;
+
+    let ld: HTMLScriptElement | null = null;
+    if (jsonLd) {
+      ld = document.createElement("script");
+      ld.type = "application/ld+json";
+      ld.textContent = JSON.stringify(jsonLd);
+      document.head.appendChild(ld);
+    }
+
+    return () => {
+      link.remove();
+      ld?.remove();
+      if (title) document.title = previousTitle;
+      if (meta && previousDescription !== undefined) meta.content = previousDescription;
+    };
+    // `jsonLd` is built inline by the caller, so it is a new object every render and
+    // cannot be a dependency — it is derived from `title`/`description`, which are.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [canonicalPath, title, description]);
+}
+
+/* ── The SEO test's helpers ──────────────────────────────────────────────── */
+
+/** What a search result shows of the landing, in one language. */
+export interface SeoCopy {
+  /** The page title (`landing.seo.title`): "Keksdose — envelope budgeting". */
+  title: string;
+  /** The meta description. */
+  description: string;
+  /** The product name the title carries, before or after its tagline. */
+  brand: string;
+}
+
+/** The width budgets, as characters. */
+export interface SeoCopyLimits {
+  /** Default 60: a result's title is cut around 580px. */
+  maxTitle?: number;
+  /** Default 155: a snippet is cut around 920px. */
+  maxDescription?: number;
+}
+
+export type SeoCopyProblemCode =
+  | "title-empty"
+  | "description-empty"
+  | "title-too-long"
+  | "description-too-long"
+  | "title-without-brand"
+  | "description-repeats-title";
+
+/** One thing wrong with a language's copy. `message` is for the test's failure output. */
+export interface SeoCopyProblem {
+  code: SeoCopyProblemCode;
+  message: string;
+}
+
+/** Characters as a reader counts them: code points, so an emoji or a rare CJK character
+ *  is one, not two UTF-16 units. */
+const length = (text: string) => Array.from(text).length;
+
+const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** The separators a title puts between the brand and its tagline. */
+const SEPARATOR = "\\s*[—–\\-|:·•]\\s*";
+
+/** The title without the brand and its separator, or `null` when the brand is in
+ *  neither place. */
+function taglineOf(title: string, brand: string): string | null {
+  const name = escapeRegExp(brand.trim());
+  const leading = new RegExp(`^${name}${SEPARATOR}`, "i");
+  if (leading.test(title)) return title.replace(leading, "").trim();
+  const trailing = new RegExp(`${SEPARATOR}${name}$`, "i");
+  if (trailing.test(title)) return title.replace(trailing, "").trim();
+  return null;
+}
+
+/**
+ * What is wrong with one language's search-result copy (§4.3) — an empty list when
+ * nothing is. keksdose's landing-seo.test.ts (live #305), made reusable:
+ *
+ * - the title fits `maxTitle` characters (60) and the description `maxDescription`
+ *   (155) — conservative stand-ins for Google's pixel budgets; German is the language
+ *   most likely to blow through them, and what gets cut is always the end;
+ * - the title carries the brand, before or after its tagline ("Keksdose — …");
+ * - the description does not open with the title's tagline again — a snippet that
+ *   repeats the line above it spends its first forty characters saying nothing new.
+ *
+ * ```ts
+ * for (const [locale, bundle] of Object.entries(LOCALES)) {
+ *   it(`fits ${locale} into a search result`, () => {
+ *     expect(seoCopyProblems({ ...bundle.landing.seo, brand: "Keksdose" })).toEqual([]);
+ *   });
+ * }
+ * ```
+ */
+export function seoCopyProblems(copy: SeoCopy, limits: SeoCopyLimits = {}): SeoCopyProblem[] {
+  const { maxTitle = 60, maxDescription = 155 } = limits;
+  const title = copy.title.replace(/\s+/g, " ").trim();
+  const description = copy.description.replace(/\s+/g, " ").trim();
+  const problems: SeoCopyProblem[] = [];
+  if (!title) problems.push({ code: "title-empty", message: "the title is empty" });
+  if (!description) problems.push({ code: "description-empty", message: "the description is empty" });
+  if (length(title) > maxTitle) {
+    problems.push({
+      code: "title-too-long",
+      message: `the title is ${length(title)} characters, over ${maxTitle}: "${title}"`,
+    });
+  }
+  if (length(description) > maxDescription) {
+    problems.push({
+      code: "description-too-long",
+      message: `the description is ${length(description)} characters, over ${maxDescription}: "${description}"`,
+    });
+  }
+  if (!title) return problems;
+  const tagline = taglineOf(title, copy.brand);
+  if (tagline === null) {
+    problems.push({
+      code: "title-without-brand",
+      message: `the title does not start or end with "${copy.brand}" and a separator: "${title}"`,
+    });
+  }
+  const repeated = (tagline ?? title).toLowerCase();
+  if (repeated && description.toLowerCase().startsWith(repeated)) {
+    problems.push({
+      code: "description-repeats-title",
+      message: `the description opens with the title's tagline "${tagline ?? title}"`,
+    });
+  }
+  return problems;
+}
+
+/** The five named references and the numeric ones — enough for a meta tag's text. */
+function decodeEntities(text: string): string {
+  const named: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+  return text.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (whole, ref: string) => {
+    if (ref[0] === "#") {
+      const code = ref[1] === "x" || ref[1] === "X" ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    return named[ref.toLowerCase()] ?? whole;
+  });
+}
+
+/** A tag's attributes, names lower-cased; values double-, single- or un-quoted. */
+function attributesOf(tag: string): Map<string, string> {
+  const found = new Map<string, string>();
+  for (const m of tag.matchAll(/([^\s=/<>"']+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g)) {
+    found.set(m[1]!.toLowerCase(), m[2] ?? m[3] ?? m[4] ?? "");
+  }
+  return found;
+}
+
+/**
+ * The `content` of the first `<meta>` in `html` that `selector` picks, whitespace
+ * collapsed and entities decoded — or `undefined` when there is none. For each app's
+ * parity test (§4.3): `index.html`'s static description and `og:` tags must equal the
+ * default language's strings, because a scraper that runs no script (WhatsApp, Slack)
+ * sees only those.
+ *
+ * `selector` names attributes, as in CSS — `meta[name="description"]`,
+ * `[property="og:title"]` or just `property="og:description"` — and every one named must
+ * match. A `RegExp` is matched against the tag's source instead (keksdose's form).
+ * String parsing, not a DOM: the test runs under `@vitest-environment node`.
+ *
+ * ```ts
+ * expect(metaContent(html, 'meta[name="description"]')).toBe(de.landing.seo.description);
+ * ```
+ */
+export function metaContent(html: string, selector: string | RegExp): string | undefined {
+  const wanted =
+    typeof selector === "string"
+      ? Array.from(selector.matchAll(/([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g), (m) => [
+          m[1]!.toLowerCase(),
+          m[2] ?? m[3] ?? "",
+        ])
+      : null;
+  if (wanted !== null && wanted.length === 0) {
+    throw new Error(`metaContent: the selector names no attribute: ${selector as string}`);
+  }
+  const pattern = selector instanceof RegExp ? new RegExp(selector.source, selector.flags.replace("g", "")) : null;
+  for (const tag of html.match(/<meta\b[^>]*>/gi) ?? []) {
+    const attrs = attributesOf(tag);
+    const matches = pattern ? pattern.test(tag) : wanted!.every(([name, value]) => attrs.get(name!) === value);
+    if (!matches) continue;
+    const content = attrs.get("content");
+    return content === undefined ? undefined : decodeEntities(content).replace(/\s+/g, " ").trim();
+  }
+  return undefined;
+}