From 83362a65c1512c8f7a8d21b2e25a39ebbdb10daa Mon Sep 17 00:00:00 2001 From: lrnselfreliance <33263708+lrnselfreliance@users.noreply.github.com> Date: Sat, 26 Sep 2026 11:22:37 -0600 Subject: [PATCH] app: video comments and description distinguish pending from empty (#727) * app: video comments and description distinguish pending from empty useVideoExtras initialised both values to null and the page treated null the same as "none", so every video open (and every prev/next) showed "No comments have been downloaded. Refresh the video?" with a live Refresh button until the comments arrived. The Description tab showed "No description available." the same way. A failed fetch was also rendered as "none", and the previous video's data lingered until the next video's responses arrived. Invariants now enforced and tested: * null = pending, undefined = fetch failed, [] / '' = loaded and empty. The API serialises a missing info_json field as null, so the hook normalises that to empty; consumers never see null for "none". * Switching video resets both to pending, and a slow response for the previous video is dropped. * The page renders a placeholder while pending, an error message on failure, and offers Refresh only once the server confirmed there are no comments. Co-Authored-By: Claude Fable 5.1 * app: useVideoExtras drops any request that is not the newest Matching on the video id let a stale request land when the user left and returned to the same video, or saved an edit while the page's first description request was still in flight. Each fetch now takes a generation number and only the newest generation may write state, per value, so a description refetch never invalidates a comments request. The edit dialog adopts a description that arrives while it is open only if the user has not typed, so a draft written over the placeholder is not wiped by the empty or failed value that follows. Tests: 7 -> none -> 8 -> 7 with the first request rejecting last; a save refetch beating the initial request; the draft surviving; the pending placeholder asserted; the console spy restored in finally. Co-Authored-By: Claude Fable 5.1 --------- Co-authored-by: Claude Fable 5.1 --- app/src/components/VideoEditMenu.js | 15 ++- app/src/components/VideoEditMenu.test.js | 20 ++++ app/src/components/VideoExtras.test.js | 66 +++++++++++ app/src/components/VideoPlayer.js | 35 ++++-- app/src/hooks/customHooks.js | 34 +++++- app/src/hooks/customHooks.test.js | 134 +++++++++++++++++++++++ 6 files changed, 286 insertions(+), 18 deletions(-) create mode 100644 app/src/components/VideoExtras.test.js diff --git a/app/src/components/VideoEditMenu.js b/app/src/components/VideoEditMenu.js index 5fa2eee6..4cf981a4 100644 --- a/app/src/components/VideoEditMenu.js +++ b/app/src/components/VideoEditMenu.js @@ -379,14 +379,27 @@ export function EditVideoModal({open, onClose, fileGroupId, videoFile, descripti const [title, setTitle] = useState(''); const [description, setDescription] = useState(''); const [saving, setSaving] = useState(false); + // The description last copied into the textarea; the user has typed when the field differs. + const syncedDescription = useRef(''); useEffect(() => { if (open) { // Start from the current details on every open, discarding an abandoned edit. setTitle(videoFile?.title || ''); setDescription(currentDescription || ''); + syncedDescription.current = currentDescription || ''; } - }, [open, videoFile?.title, currentDescription]); + }, [open, videoFile?.title]); + + useEffect(() => { + // The description may still be loading when the dialog opens (null), and it is refetched + // after a save. Adopt what arrives only while the user has not typed, so a draft written + // over the placeholder is never wiped by the empty or failed value that follows it. + if (open && currentDescription != null && description === syncedDescription.current) { + setDescription(currentDescription); + syncedDescription.current = currentDescription; + } + }, [currentDescription]); const trimmed = title.trim(); const titleChanged = trimmed !== (videoFile?.title || ''); diff --git a/app/src/components/VideoEditMenu.test.js b/app/src/components/VideoEditMenu.test.js index c74c4c59..958785af 100644 --- a/app/src/components/VideoEditMenu.test.js +++ b/app/src/components/VideoEditMenu.test.js @@ -269,6 +269,26 @@ describe('EditVideoModal', () => { await waitFor(() => expect(updateVideo).toHaveBeenCalledWith(7, {description: ''})); }); + test('a draft typed while the description was still loading survives its arrival', () => { + // The page passes null while the description is pending, then '' when the server has none. + const {rerender} = renderWithProviders( + , + ); + fireEvent.change(screen.getByLabelText('Description'), {target: {value: 'my new words'}}); + rerender(); + expect(screen.getByLabelText('Description')).toHaveValue('my new words'); + }); + + test('a description that arrives while the field is untouched is adopted', () => { + const {rerender} = renderWithProviders( + , + ); + expect(screen.getByLabelText('Description')).toHaveValue(''); + rerender(); + expect(screen.getByLabelText('Description')).toHaveValue('From the server'); + }); + test('WROL Mode disables saving', async () => { renderWithProviders( , diff --git a/app/src/components/VideoExtras.test.js b/app/src/components/VideoExtras.test.js new file mode 100644 index 00000000..72f7d259 --- /dev/null +++ b/app/src/components/VideoExtras.test.js @@ -0,0 +1,66 @@ +import React from 'react'; +import {render, screen} from '../test-utils'; +import {Comments, VideoDescription} from './VideoPlayer'; + +// What the video page shows for each state of useVideoExtras. The states are null (pending), +// undefined (fetch failed), and an empty value (loaded, nothing to show). "No comments have been +// downloaded" carries a Refresh button that re-downloads the video, so it must only appear once +// the server has confirmed there are none. + +const video = {id: 7, url: 'https://example.com/v'}; +const NO_COMMENTS = /No comments have been/; +const NO_DESCRIPTION = /No description available/; + +describe('Comments', () => { + test('pending: shows a placeholder, not "no comments" or an error', () => { + const {container} = render(); + expect(container.querySelector('.wrolpi-placeholder')).toBeInTheDocument(); + expect(screen.queryByText(NO_COMMENTS)).not.toBeInTheDocument(); + expect(screen.queryByText(/Could not/)).not.toBeInTheDocument(); + expect(screen.queryByRole('button', {name: 'Refresh'})).not.toBeInTheDocument(); + }); + + test('failed: shows an error, not "no comments"', () => { + render(); + expect(screen.getByText(/Could not fetch the comments/)).toBeInTheDocument(); + expect(screen.queryByText(NO_COMMENTS)).not.toBeInTheDocument(); + }); + + test('empty: shows "no comments" with the Refresh button', () => { + render(); + expect(screen.getByText(NO_COMMENTS)).toBeInTheDocument(); + expect(screen.getByRole('button', {name: 'Refresh'})).toBeInTheDocument(); + }); + + test('loaded: renders the comments', () => { + render(); + expect(screen.getByText('first!')).toBeInTheDocument(); + expect(screen.queryByText(NO_COMMENTS)).not.toBeInTheDocument(); + }); +}); + +describe('VideoDescription', () => { + test('pending: shows a placeholder, not "no description" or an error', () => { + const {container} = render( null}/>); + expect(container.querySelector('.wrolpi-placeholder')).toBeInTheDocument(); + expect(screen.queryByText(NO_DESCRIPTION)).not.toBeInTheDocument(); + expect(screen.queryByText(/Could not/)).not.toBeInTheDocument(); + }); + + test('failed: shows an error, not "no description"', () => { + render( null}/>); + expect(screen.getByText(/Could not fetch the description/)).toBeInTheDocument(); + expect(screen.queryByText(NO_DESCRIPTION)).not.toBeInTheDocument(); + }); + + test('empty: shows "no description"', () => { + render( null}/>); + expect(screen.getByText(NO_DESCRIPTION)).toBeInTheDocument(); + }); + + test('loaded: renders the description', () => { + render( null}/>); + expect(screen.getByText('A fine video.')).toBeInTheDocument(); + expect(screen.queryByText(NO_DESCRIPTION)).not.toBeInTheDocument(); + }); +}); diff --git a/app/src/components/VideoPlayer.js b/app/src/components/VideoPlayer.js index d957f773..106296f2 100644 --- a/app/src/components/VideoPlayer.js +++ b/app/src/components/VideoPlayer.js @@ -8,6 +8,7 @@ import { BackButton, DirectoryLink, encodeMediaPath, + ErrorMessage, humanFileSize, humanNumber, isoDatetimeToAgoPopup, @@ -19,7 +20,7 @@ import { } from "./Common"; import {VideoPlaceholder} from "./Placeholder"; import {useChannel, useVideoCaptions, useVideoExtras} from "../hooks/customHooks"; -import {Button, Grid, Header, Icon, Label, Loading, Panel, Tabs, TextInput} from "./ui"; +import {Button, Grid, Header, Icon, Label, Loading, Panel, Placeholder, Tabs, TextInput} from "./ui"; import {VideoCard} from "./Videos"; import {TagsSelector} from "../Tags"; import {AddToPlaylistButton} from "./AddToPlaylist"; @@ -170,8 +171,14 @@ const VideoComment = ({comment, children}) => { } -const Comments = ({comments, video}) => { - if (!comments || _.isEmpty(comments)) { +// `comments` follows useVideoExtras: null = pending, undefined = fetch failed, [] = none downloaded. +// Only the last of those may offer the Refresh button. +export const Comments = ({comments, video}) => { + if (comments === null) { + return + } else if (comments === undefined) { + return Could not fetch the comments. + } else if (_.isEmpty(comments)) { return } @@ -343,12 +350,6 @@ function VideoPage({videoFile, prevFile, nextFile, fetchVideo, ...props}) { caption_files.filter(i => i['mimetype'] === 'text/vtt').map(i => `${MEDIA_PATH}/${encodeMediaPath(i['path'])}`) : []; - let description = 'No description available.'; - if (videoDescription) { - // Only replace empty description if there is one available. - description = formatVideoDescription(videoDescription, setVideoTime) - } - const getFile = (suffix) => videoFile.files.find(i => i.path.toLowerCase().endsWith(suffix)); const fileSize = (file) => file && file.size ? ({humanFileSize(file.size)}) @@ -550,9 +551,7 @@ function VideoPage({videoFile, prevFile, nextFile, fetchVideo, ...props}) { -
-                        {description}
-                    
+
@@ -717,6 +716,18 @@ export default VideoPage; const chapterRegex = new RegExp('^(\\(?(?:((\\d?\\d):)?(?:(\\d?\\d):(\\d\\d)))\\)?)\.?\\s+(.*)$', 'i'); +// `description` follows useVideoExtras: null = pending, undefined = fetch failed, '' = none. +export const VideoDescription = ({description, setVideoTime}) => { + if (description === null) { + return + } else if (description === undefined) { + return Could not fetch the description. + } + return
+        {description ? formatVideoDescription(description, setVideoTime) : 'No description available.'}
+    
+} + function formatVideoDescription(description, setVideoTime) { // Convert timestamps to links which change the video's playback location. Change hashtags to search links. if (description && description.length > 0) { diff --git a/app/src/hooks/customHooks.js b/app/src/hooks/customHooks.js index b0e93298..e54ae984 100644 --- a/app/src/hooks/customHooks.js +++ b/app/src/hooks/customHooks.js @@ -767,34 +767,58 @@ export const useVideo = (fileGroupId) => { export const useVideoExtras = (fileGroupId) => { // Fetches extra data to display on a Video's page. These are served separately from the // Video itself so list responses stay small and never read files from disk. + // + // Each value is null while pending, undefined when the fetch failed, and empty ([] or '') when + // the server confirmed there is nothing. The API serializes a missing info_json field as null, + // so a null response is normalized to empty here; consumers must never see null for "none". const [comments, setComments] = useState(null); const [description, setDescription] = useState(null); + // Every fetch takes the next generation number; only the newest generation may write state. + // Matching on the video id is not enough: leaving and returning to the same video, or a save + // that refetches the description, must both beat an older request still in flight. + const commentsGen = useRef(0); + const descriptionGen = useRef(0); const fetchComments = async () => { + const gen = ++commentsGen.current; try { const result = await getVideoComments(fileGroupId); - setComments(result.comments); + if (gen === commentsGen.current) { + setComments(result.comments || []); + } } catch (e) { console.error(e); + if (gen === commentsGen.current) { + setComments(undefined); + } } } const fetchDescription = async () => { + const gen = ++descriptionGen.current; try { const result = await getVideoDescription(fileGroupId); - setDescription(result.description); + if (gen === descriptionGen.current) { + setDescription(result.description || ''); + } } catch (e) { console.error(e); + if (gen === descriptionGen.current) { + setDescription(undefined); + } } } useEffect(() => { + // Whether switching to a new video or to none, the previous video's data must not linger, + // and any request still in flight for it must not land. + commentsGen.current++; + descriptionGen.current++; + setComments(null); + setDescription(null); if (fileGroupId) { fetchComments(); fetchDescription(); - } else { - setComments(null); - setDescription(null); } }, [fileGroupId]); diff --git a/app/src/hooks/customHooks.test.js b/app/src/hooks/customHooks.test.js index 7e8f8183..9c010598 100644 --- a/app/src/hooks/customHooks.test.js +++ b/app/src/hooks/customHooks.test.js @@ -306,4 +306,138 @@ describe('useVideoExtras', () => { expect(result.current.comments).toBeNull(); expect(result.current.description).toBeNull(); }); + + // State contract, matching the rest of the hooks: null = pending, undefined = error, + // [] / '' = loaded and empty. The page branches on these to choose between a placeholder, + // an error, and "No comments have been downloaded". + test('both are pending (null) until the responses arrive', () => { + getVideoComments.mockReturnValue(new Promise(() => { + })); + getVideoDescription.mockReturnValue(new Promise(() => { + })); + const {result} = renderHook(() => useVideoExtras(7)); + expect(result.current.comments).toBeNull(); + expect(result.current.description).toBeNull(); + }); + + test('a video with no comments or description loads as empty, not pending', async () => { + // The API serializes a missing info_json field as null. + getVideoComments.mockResolvedValue({comments: null}); + getVideoDescription.mockResolvedValue({description: null}); + const {result} = renderHook(() => useVideoExtras(7)); + await act(async () => { + }); + expect(result.current.comments).toEqual([]); + expect(result.current.description).toBe(''); + }); + + test('a failed fetch yields undefined so the page can show an error instead of "no comments"', async () => { + getVideoComments.mockRejectedValue(new Error('boom')); + getVideoDescription.mockRejectedValue(new Error('boom')); + const spy = jest.spyOn(console, 'error').mockImplementation(() => { + }); + try { + const {result} = renderHook(() => useVideoExtras(7)); + await act(async () => { + }); + expect(result.current.comments).toBeUndefined(); + expect(result.current.description).toBeUndefined(); + } finally { + spy.mockRestore(); + } + }); + + test('switching video resets both to pending before the new responses arrive', async () => { + getVideoComments.mockResolvedValue({comments: [{id: 'c1', parent: 'root'}]}); + getVideoDescription.mockResolvedValue({description: 'first'}); + const {result, rerender} = renderHook(({id}) => useVideoExtras(id), {initialProps: {id: 7}}); + await act(async () => { + }); + expect(result.current.description).toBe('first'); + + // The next video's responses are slow: the previous video's data must not linger. + getVideoComments.mockReturnValue(new Promise(() => { + })); + getVideoDescription.mockReturnValue(new Promise(() => { + })); + rerender({id: 8}); + expect(result.current.comments).toBeNull(); + expect(result.current.description).toBeNull(); + }); + + test('a slow response for the previous video does not overwrite the current one', async () => { + // Video 7's responses are slow; the user moves on to video 8 before they arrive. + let resolveComments, resolveDescription; + getVideoComments.mockReturnValueOnce(new Promise(res => resolveComments = res)); + getVideoDescription.mockReturnValueOnce(new Promise(res => resolveDescription = res)); + const {result, rerender} = renderHook(({id}) => useVideoExtras(id), {initialProps: {id: 7}}); + + getVideoComments.mockResolvedValue({comments: [{id: 'c8', parent: 'root'}]}); + getVideoDescription.mockResolvedValue({description: 'eighth'}); + rerender({id: 8}); + await act(async () => { + }); + expect(result.current.description).toBe('eighth'); + + await act(async () => { + resolveComments({comments: [{id: 'c7', parent: 'root'}]}); + resolveDescription({description: 'seventh'}); + }); + expect(result.current.comments).toEqual([{id: 'c8', parent: 'root'}]); + expect(result.current.description).toBe('eighth'); + }); + + test('returning to a video does not let its first, still-pending request land', async () => { + // The route clears the video between pages, so the id goes 7 -> undefined -> 8 -> 7 while + // the very first request for 7 is still in flight (the API timeout is a minute). + let rejectComments, rejectDescription; + getVideoComments.mockReturnValueOnce(new Promise((_, rej) => rejectComments = rej)); + getVideoDescription.mockReturnValueOnce(new Promise((_, rej) => rejectDescription = rej)); + const {result, rerender} = renderHook(({id}) => useVideoExtras(id), {initialProps: {id: 7}}); + + rerender({id: undefined}); + getVideoComments.mockResolvedValue({comments: [{id: 'c8', parent: 'root'}]}); + getVideoDescription.mockResolvedValue({description: 'eighth'}); + rerender({id: 8}); + getVideoComments.mockResolvedValue({comments: [{id: 'c7b', parent: 'root'}]}); + getVideoDescription.mockResolvedValue({description: 'seventh again'}); + rerender({id: 7}); + await act(async () => { + }); + expect(result.current.comments).toEqual([{id: 'c7b', parent: 'root'}]); + expect(result.current.description).toBe('seventh again'); + + // The first request finally times out. Same id, but it is not the newest request. + const spy = jest.spyOn(console, 'error').mockImplementation(() => { + }); + try { + await act(async () => { + rejectComments(new Error('timeout')); + rejectDescription(new Error('timeout')); + }); + } finally { + spy.mockRestore(); + } + expect(result.current.comments).toEqual([{id: 'c7b', parent: 'root'}]); + expect(result.current.description).toBe('seventh again'); + }); + + test('a refetch after saving beats the initial description request still in flight', async () => { + let resolveInitial; + getVideoComments.mockResolvedValue({comments: []}); + getVideoDescription.mockReturnValueOnce(new Promise(res => resolveInitial = res)); + const {result} = renderHook(() => useVideoExtras(7)); + + // The user edits and saves before the page's first description request returned. + getVideoDescription.mockResolvedValue({description: 'edited'}); + await act(async () => { + await result.current.fetchDescription(); + }); + expect(result.current.description).toBe('edited'); + + await act(async () => { + resolveInitial({description: 'pre-edit'}); + }); + expect(result.current.description).toBe('edited'); + }); });