@tribe-nest/forge 3.34.0 → 3.36.0

package/src/ui/headless/film/_tests/useStageFullscreen.spec.ts

@@ -0,0 +1,167 @@
+// @vitest-environment jsdom
+import { renderHook, act } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useStageFullscreen } from "../useStageFullscreen";
+
+/**
+ * The regression this file exists for.
+ *
+ * The watermark is drawn INSIDE the stage. The browser promotes exactly one
+ * element into the fullscreen layer and hides the rest of the document, so when
+ * the native control bar fullscreened the `<video>`, the watermark stopped
+ * rendering for the whole session - and fullscreen is how a film is actually
+ * watched. Every test here is really asking one question: does the element that
+ * ends up fullscreen still CONTAIN the watermark?
+ */
+describe("useStageFullscreen", () => {
+  let stage: HTMLDivElement;
+  let video: HTMLVideoElement;
+  let fullscreenElement: Element | null;
+  let requestCalls: Element[];
+
+  const fireChange = () => document.dispatchEvent(new Event("fullscreenchange"));
+
+  beforeEach(() => {
+    Object.defineProperty(document, "fullscreenEnabled", { configurable: true, value: true });
+    requestCalls = [];
+    fullscreenElement = null;
+
+    stage = document.createElement("div");
+    video = document.createElement("video");
+    // The real shape: the video (and the watermark) are children of the stage.
+    stage.appendChild(video);
+    document.body.appendChild(stage);
+
+    Object.defineProperty(document, "fullscreenElement", {
+      configurable: true,
+      get: () => fullscreenElement,
+    });
+    document.exitFullscreen = vi.fn(async () => {
+      fullscreenElement = null;
+    });
+    Element.prototype.requestFullscreen = vi.fn(async function (this: Element) {
+      requestCalls.push(this);
+      fullscreenElement = this;
+    });
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  const mount = () => {
+    const hook = renderHook(() => useStageFullscreen());
+    act(() => {
+      hook.result.current.ref.current = stage;
+    });
+    return hook;
+  };
+
+  it("fullscreens the STAGE, so the watermark is inside the promoted element", async () => {
+    const { result } = mount();
+
+    await act(async () => {
+      result.current.toggle();
+    });
+
+    expect(requestCalls).toEqual([stage]);
+    // The whole point: whatever went fullscreen still contains the video, and
+    // therefore still contains the watermark drawn beside it.
+    expect(fullscreenElement).toBe(stage);
+    expect((fullscreenElement as HTMLElement).contains(video)).toBe(true);
+  });
+
+  it("swaps a native VIDEO fullscreen for the stage", async () => {
+    const { result } = mount();
+
+    // What Firefox and Safari do when the fan uses the native control bar: they
+    // ignore `controlsList="nofullscreen"` and promote the video itself.
+    await act(async () => {
+      fullscreenElement = video;
+      fireChange();
+    });
+    await act(async () => {
+      fireChange();
+    });
+
+    expect(document.exitFullscreen).toHaveBeenCalled();
+    expect(requestCalls).toContain(stage);
+  });
+
+  it("does not fight a browser that refuses the swap", async () => {
+    (Element.prototype.requestFullscreen as ReturnType<typeof vi.fn>).mockRejectedValue(new Error("gesture required"));
+    const { result } = mount();
+    expect(result.current).toBeTruthy();
+
+    await act(async () => {
+      fullscreenElement = video;
+      fireChange();
+    });
+    await act(async () => {
+      fireChange();
+      fireChange();
+    });
+
+    // One correction attempt per transition. A refusal read as another stray
+    // transition would ping-pong the fan in and out of fullscreen for ever.
+    expect((Element.prototype.requestFullscreen as ReturnType<typeof vi.fn>).mock.calls.length).toBeLessThanOrEqual(2);
+  });
+
+  it("reports fullscreen only when the STAGE is the promoted element", async () => {
+    const { result } = mount();
+
+    await act(async () => {
+      fullscreenElement = video;
+      fireChange();
+    });
+    // A video-level fullscreen is NOT the stage being fullscreen: the stage must
+    // keep its 16/9 box rather than stretch behind a layer it is not in.
+    expect(result.current.isFullscreen).toBe(false);
+
+    await act(async () => {
+      fullscreenElement = stage;
+      fireChange();
+    });
+    expect(result.current.isFullscreen).toBe(true);
+  });
+
+  it("reports support on the FIRST render, before the stage exists", () => {
+    // The regression. `<FilmWatch>` returns a loading panel first, so the stage
+    // is not in the DOM when the hook mounts. Probing `ref.current` there latched
+    // "unsupported" for ever, which hid Forge's fullscreen button while the
+    // player had already dropped the native one - desktop viewers ended up with
+    // no way into fullscreen at all.
+    Object.defineProperty(document, "fullscreenEnabled", { configurable: true, value: true });
+
+    const { result } = renderHook(() => useStageFullscreen());
+    // Deliberately NO ref attached: this is the loading render.
+    expect(result.current.ref.current).toBeNull();
+    expect(result.current.isSupported).toBe(true);
+  });
+
+  it("reports no support when the document forbids fullscreen", () => {
+    // An iframe without `allowfullscreen`. Hiding the button is right here, and
+    // the element probe could not see this at all.
+    Object.defineProperty(document, "fullscreenEnabled", { configurable: true, value: false });
+
+    const { result } = renderHook(() => useStageFullscreen());
+    expect(result.current.isSupported).toBe(false);
+  });
+
+  it("exits rather than re-requesting when already fullscreen", async () => {
+    const { result } = mount();
+    await act(async () => {
+      result.current.toggle();
+    });
+    requestCalls.length = 0;
+
+    await act(async () => {
+      result.current.toggle();
+    });
+
+    expect(document.exitFullscreen).toHaveBeenCalled();
+    expect(requestCalls).toEqual([]);
+  });
+});

package/src/ui/headless/film/index.ts

@@ -0,0 +1,36 @@
+// Films and series (Tier-1 headless).
+//
+// This tier is the point of the domain, not an afterthought: a creator who wants
+// a fully custom viewing experience builds it from here rather than pointing
+// their own `<video>` at a URL they found. Read `useFilmPlayback`'s docblock
+// before doing so - it says which protection layer a custom player gives up
+// (the viewer overlay, and only that) and what keeping it costs (one component,
+// `<FilmWatermark>`).
+
+export {
+  useFilmPlayback,
+  buildFilmPlaybackGate,
+  filmSignInHref,
+  msUntil,
+  type UseFilmPlaybackOptions,
+  type FilmPlaybackGate,
+  type FilmPlaybackGateKind,
+  type FilmPlaybackState,
+  type FilmPlaybackSubtitle,
+} from "./useFilmPlayback";
+
+export { useFilmCatalog, type UseFilmCatalogOptions, type FilmCatalogState } from "./useFilmCatalog";
+
+export {
+  useFilmRentalFlow,
+  type UseFilmRentalFlowOptions,
+  type FilmRentalStep,
+  type FilmRentalFlowState,
+} from "./useFilmRentalFlow";
+
+export { FilmWatermark, type FilmWatermarkProps } from "./FilmWatermark";
+// Container fullscreen. A custom player MUST use this rather than letting the
+// native control bar fullscreen its <video>: the browser promotes one element
+// and hides the rest of the document, so a video-level fullscreen leaves the
+// watermark behind for the whole session.
+export { useStageFullscreen, type StageFullscreen } from "./useStageFullscreen";

package/src/ui/headless/film/useFilmCatalog.ts

@@ -0,0 +1,66 @@
+import { useMemo, useState } from "react";
+import { useFilms, type FilmKind, type GetFilmsParams, type PublicFilmSummary } from "../../../data/queries/useFilms";
+
+export interface UseFilmCatalogOptions extends GetFilmsParams {
+  /** Rows per page. The API caps this at 50. */
+  limit?: number;
+}
+
+/**
+ * Headless film/series catalogue: paging, a kind filter and a search box over
+ * `useFilms`. Bring your own markup.
+ *
+ * The one thing worth reading before using it: `enabled` is not the same
+ * question as "are there films". With the film-rentals switch off the API
+ * answers 200 with an empty list and `enabled: false`, because `/i/films` ships
+ * to every site that takes a starter update and cannot itself be gated. A page
+ * that draws "no films yet" for both is telling a creator who has not turned the
+ * feature on that their catalogue is empty, which sends them looking in the
+ * wrong place.
+ */
+export function useFilmCatalog(opts: UseFilmCatalogOptions = {}) {
+  const [page, setPage] = useState(opts.page ?? 1);
+  const [query, setQuery] = useState(opts.query ?? "");
+  const [kind, setKind] = useState<FilmKind | undefined>(opts.kind);
+
+  const limit = opts.limit ?? 20;
+  const { data, isLoading, isError, refetch } = useFilms({ page, limit, kind, query: query.trim() || undefined });
+
+  const films: PublicFilmSummary[] = data?.data ?? [];
+  const total = data?.total ?? 0;
+  const pageCount = Math.max(1, Math.ceil(total / limit));
+
+  return {
+    films,
+    total,
+    page,
+    limit,
+    pageCount,
+    hasNextPage: page < pageCount,
+    hasPrevPage: page > 1,
+    /** Paging that also resets nothing else - the filters are the caller's to keep. */
+    nextPage: () => setPage((p) => Math.min(pageCount, p + 1)),
+    prevPage: () => setPage((p) => Math.max(1, p - 1)),
+    setPage,
+    query,
+    /** Changing the search resets to page 1; staying on page 4 of a new search shows nothing. */
+    setQuery: (next: string) => {
+      setQuery(next);
+      setPage(1);
+    },
+    kind,
+    setKind: (next: FilmKind | undefined) => {
+      setKind(next);
+      setPage(1);
+    },
+    /** Is the film-rentals feature switched on for this tenant? See the docblock. */
+    enabled: data?.enabled ?? false,
+    /** Nothing to show, and the feature IS on - a genuinely empty catalogue. */
+    isEmpty: useMemo(() => !isLoading && (data?.enabled ?? false) && films.length === 0, [isLoading, data, films]),
+    isLoading,
+    isError,
+    refetch,
+  };
+}
+
+export type FilmCatalogState = ReturnType<typeof useFilmCatalog>;