@tribe-nest/forge 3.24.0 → 3.26.0

package/src/ui/styled/MusicLinkPage.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import type { CSSProperties } from "react";
 import type { IMusicLink } from "../../types/models";
 import { useMusicLink } from "../../data/queries/useMusicLink";
@@ -7,6 +7,8 @@ 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.
@@ -14,13 +16,15 @@ import { PageActions } from "./PageActions";
  * `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.
  *
- * There is deliberately no logo artwork here. Reproducing a dozen trademarked
- * marks from memory gets some of them subtly wrong, and every one of these
- * services publishes brand guidelines with rules about colour, clear space and
- * permitted alterations. A wrong Spotify logo on an artist's own domain is the
- * artist's problem, not ours to create. Drop real SVGs in behind `icon` when
- * the assets have been taken from each service's brand kit; the layout already
- * reserves the space.
+ * 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" },
@@ -42,6 +46,20 @@ const SERVICES: Record<string, { label: string; color: string; action?: string }
   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 {
@@ -51,6 +69,13 @@ export interface MusicLinkPageProps {
   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;
@@ -86,6 +111,10 @@ 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,
@@ -127,9 +156,14 @@ export function MusicLinkPage({
     };
   }, [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 { trackBeacon } = useTrackEvent();
+  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.
@@ -142,6 +176,41 @@ export function MusicLinkPage({
     };
   }, []);
 
+  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) => {
@@ -170,146 +239,201 @@ export function MusicLinkPage({
     );
   }
 
+  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}
 
-      <div style={{ width: "100%", maxWidth: 420, display: "flex", flexDirection: "column", alignItems: "center" }}>
-        {link.artworkUrl ? (
-          <img
-            src={link.artworkUrl}
-            alt={link.title}
-            width={260}
-            height={260}
-            style={{
-              width: 260,
-              height: 260,
-              maxWidth: "70vw",
-              maxHeight: "70vw",
-              objectFit: "cover",
-              borderRadius: t.cornerRadius,
-              boxShadow: "0 18px 50px rgba(0,0,0,0.45)",
-            }}
-          />
-        ) : null}
+      {link.previewUrl ? (
+        <audio
+          ref={audioRef}
+          src={link.previewUrl}
+          preload="none"
+          onEnded={() => setPlaying(false)}
+          onPause={() => setPlaying(false)}
+        />
+      ) : null}
 
-        <h1
-          style={{
-            margin: "24px 0 4px",
-            fontSize: 24,
-            lineHeight: 1.25,
-            textAlign: "center",
-            color: t.text,
-            fontFamily: t.headingFontFamily || t.fontFamily,
-          }}
-        >
-          {link.title}
-        </h1>
+      <MusicLinkLayout style={activeStyle} parts={parts} />
+    </Overlay>
+  );
+}
 
-        {link.artistName ? (
-          <p style={{ margin: 0, fontSize: 16, color: t.muted, fontFamily: t.fontFamily }}>{link.artistName}</p>
-        ) : null}
+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;
 
-        {link.description ? (
-          <p
-            style={{
-              margin: "12px 0 0",
-              fontSize: 14,
-              textAlign: "center",
-              color: t.muted,
-              fontFamily: t.fontFamily,
-            }}
-          >
-            {link.description}
-          </p>
-        ) : null}
+  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",
+  };
 
-        {destinations.length > 0 ? (
-          <p
-            style={{
-              margin: "28px 0 12px",
-              fontSize: 12,
-              letterSpacing: "0.08em",
-              textTransform: "uppercase",
-              color: t.muted,
-              fontFamily: t.fontFamily,
-            }}
-          >
-            {listHeading}
-          </p>
-        ) : null}
+  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>
 
-        <div style={{ width: "100%", display: "flex", flexDirection: "column", gap: 10 }}>
-          {destinations.map((destination) => {
-            const meta = serviceMeta(destination.platform);
-            return (
-              <a
-                key={destination.platform}
-                href={destination.url}
-                target="_blank"
-                rel="noopener noreferrer"
-                // Stands the global click listener down. It would otherwise
-                // record a second, poorer event for this same tap, and its
-                // payload would drive a duplicate CAPI Lead.
-                data-track-skip=""
-                data-track={`music-link-${destination.platform}`}
-                onClick={() => onDestinationClick(destination.platform, destination.url)}
-                style={{
-                  display: "flex",
-                  alignItems: "center",
-                  gap: 12,
-                  padding: "12px 14px",
-                  borderRadius: t.cornerRadius,
-                  background: t.surface,
-                  border: `1px solid ${t.border}`,
-                  color: t.text,
-                  textDecoration: "none",
-                  fontFamily: t.fontFamily,
-                }}
-              >
-                <span
-                  aria-hidden="true"
-                  style={{
-                    width: 34,
-                    height: 34,
-                    flex: "0 0 34px",
-                    borderRadius: 999,
-                    background: meta.color,
-                    color: "#ffffff",
-                    display: "flex",
-                    alignItems: "center",
-                    justifyContent: "center",
-                    fontSize: 15,
-                    fontWeight: 700,
-                  }}
-                >
-                  {meta.label.charAt(0)}
-                </span>
-                <span style={{ flex: 1, fontSize: 15, fontWeight: 600 }}>{meta.label}</span>
-                <span style={{ fontSize: 13, fontWeight: 700, color: t.primary }}>{meta.action}</span>
-              </a>
-            );
-          })}
-        </div>
+      {/* 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>
 
-        {/*
-          The creator's own additions: a newsletter form, a vinyl pre-order, a
-          lead magnet, a donation. This route is a platform-owned chassis file
-          that is re-materialized from the starter on every build, so anything
-          added to it IN CODE would be overwritten on the next deploy. Page
-          actions are data instead, resolved per link with a per-page-type
-          default, so the shell stays ours and the contents stay theirs.
-        */}
-        <div style={{ width: "100%", marginTop: 28 }}>
-          <PageActions pageType="music_link" entityId={link.id} />
-        </div>
-      </div>
-    </Overlay>
+      {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>
   );
 }
 
@@ -319,12 +443,18 @@ function Overlay({
   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
@@ -332,7 +462,7 @@ function Overlay({
       style={{
         position: "fixed",
         inset: 0,
-        zIndex: 60,
+        zIndex: OVERLAY_Z_INDEX,
         overflowY: "auto",
         background: t.background,
         display: "flex",
@@ -354,12 +484,35 @@ function Overlay({
             backgroundPosition: "center",
             filter: "blur(48px) saturate(1.4)",
             transform: "scale(1.2)",
-            opacity: 0.35,
+            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" }}>{children}</div>
+      <div
+        style={{
+          position: "relative",
+          width: "100%",
+          display: "flex",
+          justifyContent: "center",
+          minHeight: scrim ? "100%" : undefined,
+        }}
+      >
+        {children}
+      </div>
     </div>
   );
 }

package/src/ui/styled/PageActions.tsx

@@ -15,7 +15,7 @@ export interface PageActionsProps {
   placement?: string;
   /**
    * Where product detail lives on this site — `/i/store` on code sites,
-   * `/products` on Craft ones. Only the `addons` block uses it.
+   * `/products` on Craft ones. Only add-on product cards use it.
    */
   productBasePath?: string;
   className?: string;
@@ -63,14 +63,11 @@ function ActionRenderer({
     case "offer":
       return <OfferButton productId={c.productId} text={c.text} />;
     case "product_cards":
-      return (
-        <div>
-          {c.title && <h3 style={{ fontWeight: 600, marginBottom: 12 }}>{c.title}</h3>}
-          <ProductGrid columns={c.columns} limit={c.limit} />
-        </div>
-      );
-    case "addons":
-      return (
+      // One config, two buying rules. `isAddon` gates the products behind the
+      // page's own purchase (a ticket on an event page); without it they are
+      // ordinary cards anyone can buy on their own. Both draw the same grid,
+      // which is why this is one action type rather than two.
+      return c.isAddon ? (
         <Addons
           entityId={entityId}
           productIds={c.productIds ?? []}
@@ -78,6 +75,13 @@ function ActionRenderer({
           columns={c.columns}
           productBasePath={productBasePath}
         />
+      ) : (
+        <div>
+          {c.title && <h3 style={{ fontWeight: 600, marginBottom: 12 }}>{c.title}</h3>}
+          {/* Chosen products win; with none chosen the grid falls back to the
+              shop listing capped at `limit`. */}
+          <ProductGrid columns={c.columns} limit={c.limit} productIds={c.productIds} />
+        </div>
       );
     case "donation":
       return <DonationButton donationId={c.donationId} text={c.text} />;

package/src/ui/styled/ProductGrid.tsx

@@ -78,11 +78,24 @@ export function ProductGrid({
   if (isLoading) return <Loading />;
   if (!products.length) return <p style={{ color: t.text, opacity: 0.7 }}>{emptyLabel ?? "No products yet."}</p>;
 
-  // Responsive: each card is at least ~150px wide, but also at least
-  // (container / columns), so it renders `columns` across on wide screens and
-  // wraps to fewer on narrow ones — no fixed column count that cramps mobile.
+  // `columns` is the DESKTOP count. Each card is also given a minimum width, so
+  // the grid drops to fewer columns as the container narrows and reaches a
+  // single column on a phone.
+  //
+  // No media query, because the column count is per-instance data: a static
+  // stylesheet would need a generated class for every distinct `columns` value
+  // on the page. `auto-fill` expresses the same intent with no injected CSS,
+  // and it responds to the CONTAINER rather than the viewport, so a grid in a
+  // narrow column behaves correctly on a wide screen.
+  //
+  // The minimum is what sets the phone breakpoint. At 260px a 390px-wide phone
+  // fits one card ((390 + 16) / (260 + 16) = 1.47), and anything under ~552px
+  // stays single-column; a 3-column desktop is unaffected because
+  // (1200 - 32) / 3 = 389px already exceeds it. Raised from 150px, which fitted
+  // two cramped cards side by side on every phone.
   const gap = 16;
-  const track = `minmax(max(150px, calc((100% - ${(columns - 1) * gap}px) / ${columns})), 1fr)`;
+  const minCardWidth = 260;
+  const track = `minmax(max(${minCardWidth}px, calc((100% - ${(columns - 1) * gap}px) / ${columns})), 1fr)`;
 
   return (
     <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");
+  });
+});