@tribe-nest/forge 3.23.0 → 3.25.0

package/src/ui/styled/MusicLinkPage.tsx

@@ -0,0 +1,518 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { CSSProperties } from "react";
+import type { IMusicLink } from "../../types/models";
+import { useMusicLink } from "../../data/queries/useMusicLink";
+import { newEventId, useTrackEvent } from "../../data/queries/useAnalytics";
+import { usePageMetaPixel } from "../analytics/PageMetaPixel";
+import { PageMetaPixel } from "../analytics/PageMetaPixel";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { PageActions } from "./PageActions";
+import { DEFAULT_MUSIC_LINK_STYLE, MusicLinkLayout, type LayoutParts, type MusicLinkStyle } from "./musicLinkStyles";
+import { useCookieConsent } from "../headless/consent/useCookieConsent";
+
+/**
+ * How each streaming service is presented.
+ *
+ * `color` is the service's own brand colour, used for the badge, and `label` is
+ * the name a fan recognises rather than the API key.
+ *
+ * Marks and brand hex come from `musicServiceIcons.ts`, generated from
+ * simple-icons rather than drawn by hand: reproducing a dozen trademarked logos
+ * from memory gets several subtly wrong, and a wrong Spotify mark on an artist's
+ * own domain is the artist's problem. Four services (Amazon Music, Boomplay,
+ * Anghami, Audius) have no entry there and keep the initial badge; adding them
+ * means finding an officially published SVG, not guessing one.
+ *
+ * `color` below is only the fallback for those four. Anything with a real icon
+ * uses the official hex from the generated file.
+ */
+const SERVICES: Record<string, { label: string; color: string; action?: string }> = {
+  spotify: { label: "Spotify", color: "#1DB954", action: "Play" },
+  appleMusic: { label: "Apple Music", color: "#FA243C", action: "Play" },
+  itunes: { label: "iTunes", color: "#FA243C", action: "Buy" },
+  youtube: { label: "YouTube", color: "#FF0000", action: "Watch" },
+  youtubeMusic: { label: "YouTube Music", color: "#FF0000", action: "Play" },
+  deezer: { label: "Deezer", color: "#A238FF", action: "Play" },
+  tidal: { label: "Tidal", color: "#000000", action: "Play" },
+  amazonMusic: { label: "Amazon Music", color: "#25D1DA", action: "Play" },
+  soundcloud: { label: "SoundCloud", color: "#FF5500", action: "Play" },
+  bandcamp: { label: "Bandcamp", color: "#629AA9", action: "Buy" },
+  audiomack: { label: "Audiomack", color: "#FFA200", action: "Play" },
+  boomplay: { label: "Boomplay", color: "#E62E2D", action: "Play" },
+  anghami: { label: "Anghami", color: "#8A2BE2", action: "Play" },
+  pandora: { label: "Pandora", color: "#3668FF", action: "Play" },
+  napster: { label: "Napster", color: "#00B9F1", action: "Play" },
+  audius: { label: "Audius", color: "#CC0FE0", action: "Play" },
+  tiktok: { label: "TikTok", color: "#000000", action: "Open" },
+};
+
+/**
+ * Below `CookieConsent`, which is fixed at 70.
+ *
+ * This page covers the viewport, so anything the shell renders underneath is
+ * hidden. The consent banner must NOT be: this page fires a Meta Pixel, so
+ * hiding the control that governs it would mean running marketing tracking
+ * with the consent UI painted over. The gap is deliberate, and a spec asserts
+ * the ordering so a future bump here cannot quietly close it.
+ */
+const OVERLAY_Z_INDEX = 60;
+
+/** TribeNest's hosted policy, matching what `CookieConsent` falls back to. */
+const TRIBENEST_PRIVACY_URL = "https://www.tribenest.co/privacy";
+
+const serviceMeta = (platform: string) => SERVICES[platform] ?? { label: platform, color: "#666666", action: "Open" };
+
+export interface MusicLinkPageProps {
+  /** The slug from the route. Ignored when `link` is passed directly. */
+  slug?: string;
+  /** Server-fetched link from the route loader. Renders with no client fetch. */
+  initialLink?: IMusicLink | null;
+  /** Heading above the service list. */
+  listHeading?: string;
+  /** The site's own privacy policy. Falls back to TribeNest's hosted one. */
+  privacyHref?: string;
+  /** The "Powered by TribeNest" credit. */
+  showPoweredBy?: boolean;
+  /** Accessible names for the preview control. */
+  playLabel?: string;
+  pauseLabel?: string;
+  /** Shown when the slug resolves to nothing. */
+  notFoundMessage?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * A music smart link page: artwork, title, and one row per streaming service.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHY THIS RENDERS AS A FIXED FULL-VIEWPORT LAYER
+ * ─────────────────────────────────────────────────────────────────────────
+ * A landing page has to own the screen, and on a deployed site there is no other
+ * way to get it. The starter's `__root.tsx` wraps every route in `<Nav/>`, a
+ * `max-width: 1040px` `<main>`, and `<SiteFooter/>`; it is tenant-owned, it is
+ * never overwritten by an update, and a route cannot escape the root route in
+ * TanStack. So a page that merely styles itself well still renders as a column
+ * in the middle of the artist's website, under their menu.
+ *
+ * Covering the viewport from inside the block is the only mechanism that works
+ * on sites that already exist, which is all of them. It is the default rather
+ * than an option for the same reason.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHY EACH SERVICE IS A REAL ANCHOR
+ * ─────────────────────────────────────────────────────────────────────────
+ * `<a href>`, not a button with a JS redirect. Fans long-press to copy, open in
+ * a new tab, and share these links onward, and a click handler pretending to be
+ * a link breaks all three. The tracking hangs off the click; it does not own the
+ * navigation, and if tracking fails the fan still reaches Spotify.
+ */
+export function MusicLinkPage({
+  slug,
+  initialLink,
+  listHeading = "Listen on",
+  privacyHref,
+  showPoweredBy = true,
+  playLabel = "Play a preview",
+  pauseLabel = "Pause the preview",
+  notFoundMessage = "This link is no longer available.",
+  className,
+  style,
+}: MusicLinkPageProps) {
+  const siteTokens = useThemeTokens();
+  const { data, isLoading } = useMusicLink(slug, { initialData: initialLink });
+  const link = data ?? initialLink ?? null;
+
+  /**
+   * Site theme, then the link's `mode` preset, then its explicit colours.
+   *
+   * Three layers rather than one because the three answer different questions.
+   * The site theme is what every link should look like by default, and a creator
+   * who restyles their site should not then restyle twenty links. `mode` is how
+   * people actually talk about a release page ("make this one dark"), and it has
+   * to move background, text, surface and border together or the result is
+   * unreadable. Explicit colours are the escape from both.
+   */
+  const t = useMemo(() => {
+    const theme = link?.theme;
+    if (!theme) return siteTokens;
+
+    const preset =
+      theme.mode === "dark"
+        ? { background: "#0b0b0d", text: "#ffffff", surface: "#17171b", border: "#2a2a30", muted: "#a1a1aa" }
+        : theme.mode === "light"
+          ? { background: "#ffffff", text: "#111113", surface: "#f5f5f7", border: "#e4e4e7", muted: "#71717a" }
+          : {};
+
+    return {
+      ...siteTokens,
+      ...preset,
+      ...(theme.background ? { background: theme.background } : {}),
+      ...(theme.text ? { text: theme.text } : {}),
+      ...(theme.surface ? { surface: theme.surface } : {}),
+      ...(theme.border ? { border: theme.border } : {}),
+      ...(theme.accent ? { primary: theme.accent } : {}),
+      cornerRadius: theme.buttonShape === "pill" ? 999 : theme.buttonShape === "square" ? 0 : siteTokens.cornerRadius,
+    };
+  }, [siteTokens, link?.theme]);
+
+  // Falls back rather than throwing on an unknown value: a style saved by a
+  // newer admin than the site's Forge must render as something, and Classic is
+  // the safe something.
+  const activeStyle: MusicLinkStyle = (link?.theme?.style as MusicLinkStyle) ?? DEFAULT_MUSIC_LINK_STYLE;
+
+  const pixelId = link?.metaPixelId ?? "";
+  const { fire } = usePageMetaPixel(pixelId);
+  const { track, trackBeacon } = useTrackEvent();
+
+  // Lock the page behind the overlay. Without this the tenant's own page keeps
+  // scrolling underneath on iOS, which reads as a rendering bug.
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const previous = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = previous;
+    };
+  }, []);
+
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const [playing, setPlaying] = useState(false);
+
+  // Stop the preview when the page goes away. Without this a fan who taps play
+  // and then taps Spotify leaves audio running underneath the store they just
+  // opened, which on mobile is both confusing and hard to stop.
+  useEffect(() => {
+    return () => {
+      audioRef.current?.pause();
+    };
+  }, []);
+
+  const togglePreview = () => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    if (audio.paused) {
+      // A tap IS the user gesture mobile autoplay policy requires, so this is
+      // allowed where an autoplaying preview would be blocked. `catch` because
+      // it still rejects on some in-app browsers and a rejected promise here
+      // must not surface as an error to a fan.
+      void audio
+        .play()
+        .then(() => setPlaying(true))
+        .catch(() => setPlaying(false));
+    } else {
+      audio.pause();
+      setPlaying(false);
+    }
+    if (!audio.paused)
+      track("preview_play", {
+        pathname: typeof window !== "undefined" ? window.location.pathname : undefined,
+        slug: link?.slug,
+      });
+  };
+
+  const destinations = useMemo(() => link?.destinations ?? [], [link]);
+
+  const onDestinationClick = (platform: string, url: string) => {
+    // ONE id, shared by the browser pixel event and the server-side CAPI twin
+    // that `maybeSendPageCapi` emits for this click. Meta deduplicates on
+    // (event_id, event_name), so without a shared id the same tap is counted as
+    // two conversions and the campaign optimises against inflated numbers.
+    const eventId = newEventId();
+
+    fire("Lead", { content_name: serviceMeta(platform).label, content_category: "music_link" });
+
+    trackBeacon("click", {
+      pathname: typeof window !== "undefined" ? window.location.pathname : undefined,
+      destination: platform,
+      slug: link?.slug,
+      href: url,
+      eventId,
+    });
+  };
+
+  if (!link) {
+    return (
+      <Overlay t={t} className={className} style={style}>
+        <p style={{ color: t.muted, fontFamily: t.fontFamily }}>{isLoading ? "" : notFoundMessage}</p>
+      </Overlay>
+    );
+  }
+
+  const previewButton = (size: number) =>
+    link.previewUrl ? (
+      <button
+        type="button"
+        onClick={togglePreview}
+        aria-label={playing ? pauseLabel : playLabel}
+        data-track-skip=""
+        style={{
+          width: size,
+          height: size,
+          borderRadius: 999,
+          border: "none",
+          cursor: "pointer",
+          background: "rgba(0,0,0,0.55)",
+          backdropFilter: "blur(4px)",
+          color: "#ffffff",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          padding: 0,
+          flex: "none",
+        }}
+      >
+        <svg
+          viewBox="0 0 24 24"
+          width={Math.round(size * 0.44)}
+          height={Math.round(size * 0.44)}
+          fill="currentColor"
+          aria-hidden="true"
+        >
+          {playing ? (
+            <path d="M6 5h4v14H6zM14 5h4v14h-4z" />
+          ) : (
+            <path d="M8 5.14v13.72a.5.5 0 0 0 .76.43l11.14-6.86a.5.5 0 0 0 0-.86L8.76 4.71a.5.5 0 0 0-.76.43z" />
+          )}
+        </svg>
+      </button>
+    ) : null;
+
+  const artwork = (size: number) =>
+    link.artworkUrl ? (
+      <div style={{ position: "relative", lineHeight: 0 }}>
+        <img
+          src={link.artworkUrl}
+          alt={link.title}
+          width={size}
+          height={size}
+          style={{
+            width: size,
+            height: size,
+            maxWidth: "70vw",
+            maxHeight: "70vw",
+            objectFit: "cover",
+            borderRadius: t.cornerRadius,
+            boxShadow: "0 18px 50px rgba(0,0,0,0.45)",
+          }}
+        />
+
+        {/*
+          The preview, over the cover. Only when there IS one: a play button that
+          does nothing is worse than no play button, and plenty of releases
+          resolve without a preview. Scaled with the artwork so it stays
+          proportionate on the styles that shrink the cover.
+        */}
+        {size >= 110 ? (
+          <div
+            style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }}
+          >
+            {previewButton(Math.round(size * 0.25))}
+          </div>
+        ) : null}
+      </div>
+    ) : null;
+
+  const parts: LayoutParts = {
+    t,
+    link: {
+      title: link.title,
+      artistName: link.artistName,
+      description: link.description,
+      artworkUrl: link.artworkUrl,
+    },
+    destinations,
+    metaFor: serviceMeta,
+    onDestinationClick,
+    artwork,
+    previewButton: previewButton(72),
+    listHeading,
+    pageActions: (
+      <div style={{ width: "100%", marginTop: 28 }}>
+        <PageActions pageType="music_link" entityId={link.id} />
+      </div>
+    ),
+    footer: <SmartLinkFooter t={t} privacyHref={privacyHref} showPoweredBy={showPoweredBy} />,
+  };
+
+  // The immersive style uses the cover AS the page, so its backdrop is opaque
+  // rather than the faint blur the others sit on.
+  const immersive = activeStyle === "immersive";
+
+  return (
+    <Overlay
+      t={t}
+      className={className}
+      style={style}
+      artworkUrl={link.theme?.artworkBackdrop === false ? null : link.artworkUrl}
+      backdropOpacity={immersive ? 0.62 : 0.35}
+      scrim={immersive}
+    >
+      {pixelId ? <PageMetaPixel pixelId={pixelId} /> : null}
+
+      {link.previewUrl ? (
+        <audio
+          ref={audioRef}
+          src={link.previewUrl}
+          preload="none"
+          onEnded={() => setPlaying(false)}
+          onPause={() => setPlaying(false)}
+        />
+      ) : null}
+
+      <MusicLinkLayout style={activeStyle} parts={parts} />
+    </Overlay>
+  );
+}
+
+function SmartLinkFooter({
+  t,
+  privacyHref,
+  showPoweredBy,
+}: {
+  t: ReturnType<typeof useThemeTokens>;
+  privacyHref?: string;
+  showPoweredBy: boolean;
+}) {
+  const { reopen } = useCookieConsent();
+  const href = privacyHref ?? TRIBENEST_PRIVACY_URL;
+  const external = !privacyHref;
+
+  const linkStyle: CSSProperties = {
+    color: t.muted,
+    textDecoration: "none",
+    borderBottom: `1px solid ${t.border}`,
+    background: "none",
+    border: "none",
+    borderBottomWidth: 1,
+    borderBottomStyle: "solid",
+    borderBottomColor: t.border,
+    padding: 0,
+    font: "inherit",
+    cursor: "pointer",
+  };
+
+  return (
+    <footer
+      style={{
+        marginTop: 36,
+        display: "flex",
+        flexWrap: "wrap",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: 14,
+        fontSize: 12,
+        color: t.muted,
+        fontFamily: t.fontFamily,
+      }}
+    >
+      <a
+        href={href}
+        {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+        data-track-skip=""
+        style={linkStyle}
+      >
+        Privacy
+      </a>
+
+      {/* Reopening the banner is the only way a visitor can change their mind
+          once a choice is stored, and the shell puts this in the footer we are
+          covering. */}
+      <button type="button" onClick={reopen} data-track-skip="" style={linkStyle}>
+        Cookie settings
+      </button>
+
+      {showPoweredBy ? (
+        <a
+          href="https://www.tribenest.co"
+          target="_blank"
+          rel="noopener noreferrer"
+          data-track-skip=""
+          style={{ ...linkStyle, borderBottom: "none" }}
+        >
+          Powered by TribeNest
+        </a>
+      ) : null}
+    </footer>
+  );
+}
+
+function Overlay({
+  t,
+  artworkUrl,
+  className,
+  style,
+  children,
+  backdropOpacity = 0.35,
+  scrim = false,
+}: {
+  t: ReturnType<typeof useThemeTokens>;
+  artworkUrl?: string | null;
+  className?: string;
+  style?: CSSProperties;
+  children: React.ReactNode;
+  /** How strongly the cover shows through. Immersive leans on it; the rest hint. */
+  backdropOpacity?: number;
+  /** A dark gradient over the cover, so light type stays legible on any artwork. */
+  scrim?: boolean;
+}) {
+  return (
+    <div
+      className={className}
+      style={{
+        position: "fixed",
+        inset: 0,
+        zIndex: OVERLAY_Z_INDEX,
+        overflowY: "auto",
+        background: t.background,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "flex-start",
+        padding: "48px 20px 64px",
+        ...style,
+      }}
+    >
+      {artworkUrl ? (
+        <div
+          aria-hidden="true"
+          style={{
+            position: "absolute",
+            inset: 0,
+            backgroundImage: `url(${artworkUrl})`,
+            backgroundSize: "cover",
+            backgroundPosition: "center",
+            filter: "blur(48px) saturate(1.4)",
+            transform: "scale(1.2)",
+            opacity: backdropOpacity,
+            pointerEvents: "none",
+          }}
+        />
+      ) : null}
+      {/* Artwork is uncontrollable input: a pale cover would leave white type on
+          white. The scrim guarantees a dark ground under the immersive style. */}
+      {artworkUrl && scrim ? (
+        <div
+          aria-hidden="true"
+          style={{
+            position: "absolute",
+            inset: 0,
+            background: "linear-gradient(180deg, rgba(0,0,0,0.35) 0%, rgba(0,0,0,0.78) 65%, rgba(0,0,0,0.9) 100%)",
+            pointerEvents: "none",
+          }}
+        />
+      ) : null}
+      <div
+        style={{
+          position: "relative",
+          width: "100%",
+          display: "flex",
+          justifyContent: "center",
+          minHeight: scrim ? "100%" : undefined,
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/ui/styled/_tests/musicLinkChrome.spec.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const read = (p: string) => readFileSync(join(__dirname, "..", p), "utf8");
+
+/**
+ * `MusicLinkPage` covers the viewport, so everything the app shell renders
+ * underneath it is hidden. These assertions pin the two things that must NOT be.
+ *
+ * Source assertions rather than a render test on purpose: what is being checked
+ * is a relationship between two components' stacking, which a render of either
+ * one alone cannot see, and which a person editing one of them would have no
+ * reason to think about.
+ */
+describe("music link page chrome", () => {
+  const page = read("MusicLinkPage.tsx");
+  const consent = read("CookieConsent.tsx");
+
+  const zIndexOf = (src: string, pattern: RegExp) => {
+    const match = pattern.exec(src);
+    if (!match) throw new Error("no z-index found");
+    return Number(match[1]);
+  };
+
+  it("stays below the cookie banner", () => {
+    // The page fires a Meta Pixel. Painting over the consent UI would mean
+    // running marketing tracking with its only control hidden, which is a
+    // compliance problem rather than a layout one.
+    const overlay = zIndexOf(page, /const OVERLAY_Z_INDEX = (\d+);/);
+    const banner = zIndexOf(consent, /zIndex:\s*(\d+)/);
+
+    expect(overlay).toBeLessThan(banner);
+  });
+
+  it("carries its own privacy and cookie-settings links", () => {
+    // The site footer that normally holds these is covered by the overlay, so
+    // the page has to supply them itself or a visitor has no way to read the
+    // policy or withdraw consent from the page that tracks them.
+    expect(page).toContain("Cookie settings");
+    expect(page).toContain("Privacy");
+    expect(page).toContain("useCookieConsent");
+  });
+
+  it("credits the platform", () => {
+    expect(page).toContain("Powered by TribeNest");
+  });
+});